API Reference
Complete TypeScript API reference for @kumbatio/energy-system - entry points, engine, strategies, runtime, and adapters
@kumbatio/energy-system is a framework-agnostic TypeScript library for energy-aware application behavior.
This section has two halves, and they are kept honest in different ways:
Explained reference
Hand-written pages, grouped by topic, with worked examples and the reasoning behind each API. Every type table on these pages is compiled from the installed package's own declarations.
Generated reference
Every public export, with its exact signature and doc comment, generated from the type declarations of the version this site has installed. Complete by construction.
Deliberately no version number is written on this page. The generated reference states the version it was built from, and it is the only place that can state it without going stale.
Requirements
The package is ESM-only ("type": "module") and requires Node.js >=24. It has one optional peer dependency: react >= 19.2 and @types/react >= 19.2, needed only for the /react entry point, which imports <Activity> - added in React 19.2. Earlier React majors throw on first render rather than degrading, which is why the range is a hard floor rather than a recommendation.
Entry points
| Import path | Contents |
|---|---|
@kumbatio/energy-system | Core: engine, types, level definitions, built-in strategies, presence, focus sessions, notification gate, deferral, inbound-demand policy, metrics, external-level compatibility |
@kumbatio/energy-system/react | EnergyProvider, hooks, and headless components (EnergyGate, EnergyIndicator) |
@kumbatio/energy-system/dom | Direct DOM projection: applyEnergyLevel, readEnergyLevel, observeEnergyLevel |
@kumbatio/energy-system/persistence | Persistence adapters: localStoragePersistence, memoryPersistence |
@kumbatio/energy-system/css | Reference stylesheet (energy.css) implementing the UI visibility strategy in pure CSS |
Three more subpaths are published as data rather than code, and exist so that consumers and other implementations can check themselves against this one: ./api-surface.json (the exact public surface), ./conformance.json (the level table and the values every built-in strategy resolves to), and ./spec/energy-state.schema.json with ./spec/conformance.schema.json. See Spec and conformance.
Explained pages
Core entry
Everything exported from the package root, from createEnergyEngine to the notification gate.
React
EnergyProvider, all hooks, and the EnergyGate and EnergyIndicator components.
DOM
Apply and observe energy levels on DOM elements without a framework.
Persistence
Built-in EnergyPersistence adapters for localStorage and memory.
CSS
Every class, custom property, and data-attribute selector in the reference stylesheet.
Core pages
Engine
createEnergyEngine - options, state access, subscriptions, persistence flushing, disposal.
Types
EnergyLevel, EnergyState, CognitiveProfile, AdaptationStrategy, EnergyPersistence, and friends.
Levels
The five level definitions and the pure level functions.
Strategies
The built-in adaptation strategies and their config types.
Presence
Declare which energy levels a UI element belongs to.
Sessions and gates
Focus sessions and the runtime notification gate.
Deferral
Not-now presets and energy-aware deferral resolution.
Demand
The inbound-demand admission policy and its acknowledgments.
Metrics and compatibility
Derived metrics and bridges for non-native level models.