@kumbatio/energy-system 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominikos Pritis / Kumbatio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# @kumbatio/energy-system
+
+Framework-agnostic TypeScript library for building **energy-aware applications**.
+
+Instead of adapting software to clock time, adapt behavior to current cognitive capacity.
+`energy-system` models energy as explicit state and resolves strategies from that state.
+
+## Why this exists
+
+Most tooling assumes equal capacity across a day. Real-world cognitive energy is variable and non-linear.
+
+The core model is:
+
+- **Work Hours (wh):** total time present
+- **Productive Hours (ph):** focused subset of that time
+- **Stuff Done (sd):** measurable output
+
+And the constraint is always `ph ≤ wh`.
+
+In other words: extending time does not linearly increase productive output.
+This library gives applications a structured way to adapt to energy state instead of raw time.
+
+## Features
+
+- 5-level energy model: `100 | 75 | 50 | 25 | 0`
+- Rich immutable state object: `level`, `timestamp`, `source`
+- Framework-agnostic core engine
+- Strategy system for behavior adaptation
+- Built-in strategies:
+  - UI visibility
+  - Notification filtering
+  - Task complexity guidance
+- DOM adapter (`data-energy-level` + CSS variables)
+- React provider, hooks, and headless render component
+- Persistence adapters (`localStorage`, in-memory)
+- Deterministic clock support for testing/simulation
+- Optional external persistence observation (`observe`)
+- Derived metrics helper (`getEnergyMetrics`)
+- Compatibility helpers for non-native external level models
+
+## Installation
+
+```bash
+pnpm add @kumbatio/energy-system
+```
+
+React integration is optional and provided via `@kumbatio/energy-system/react`.
+
+## Quick start (core)
+
+```ts
+import {
+  createEnergyEngine,
+  uiVisibilityStrategy,
+  notificationStrategy,
+} from '@kumbatio/energy-system'
+import { localStoragePersistence } from '@kumbatio/energy-system/persistence'
+
+const engine = createEnergyEngine({
+  initialLevel: 75,
+  persistence: localStoragePersistence(),
+})
+
+engine.setLevel(50)
+
+const uiConfig = engine.resolve(uiVisibilityStrategy)
+const notifConfig = engine.resolve(notificationStrategy)
+```
+
+## Quick start (React)
+
+```tsx
+import {
+  EnergyProvider,
+  useEnergyLevel,
+  useEnergyState,
+  useStrategy,
+} from '@kumbatio/energy-system/react'
+import { uiVisibilityStrategy } from '@kumbatio/energy-system'
+
+function Screen() {
+  const [level, setLevel] = useEnergyLevel()
+  const state = useEnergyState()
+  const ui = useStrategy(uiVisibilityStrategy)
+
+  return (
+    <div>
+      <button onClick={() => setLevel(level === 100 ? 75 : 100)}>
+        Energy: {state.level}
+      </button>
+      {ui.sidebar && <aside>Sidebar</aside>}
+    </div>
+  )
+}
+
+export function App() {
+  return (
+    <EnergyProvider defaultLevel={100}>
+      <Screen />
+    </EnergyProvider>
+  )
+}
+```
+
+## Quick start (DOM)
+
+```ts
+import {
+  applyEnergyLevel,
+  observeEnergyLevel,
+} from '@kumbatio/energy-system/dom'
+
+applyEnergyLevel(50)
+
+const cleanup = observeEnergyLevel((state, prev) => {
+  console.log(`Energy: ${prev.level} -> ${state.level}`)
+})
+```
+
+## CSS usage
+
+Import the reference stylesheet:
+
+```ts
+import '@kumbatio/energy-system/css'
+```
+
+Then use classes like:
+
+- `.energy-chrome`
+- `.energy-sidebar`
+- `.energy-tab-bar`
+- `.energy-status-bar`
+- `.energy-toolbar`
+- `.energy-content`
+
+## API map
+
+### Core package
+
+- `createEnergyEngine(options?)`
+- `getEnergyLevels()`, `getEnergyLevel(level)`
+- `cycleEnergyLevel(level)`, `isEnergyLevel(value)`, `isEnergySource(value)`
+- `createExternalLevelCompatibility(options)`
+- `cycleDiscreteLevel(current, levels, fallback)`
+- `mapToNearestDiscreteLevel(value, levels, fallback)`
+- `mapToNearestEnergyLevel(value)`
+- Strategies: `uiVisibilityStrategy`, `notificationStrategy`, `taskComplexityStrategy`
+- Types: `EnergyLevel`, `EnergyState`, `AdaptationStrategy`, etc.
+
+### `@kumbatio/energy-system/react`
+
+- `EnergyProvider`
+- `useEnergyState()`
+- `useEnergyLevel()`
+- `useEnergyLevelCycler()`
+- `useStrategy(strategy)`
+- `useEnergyGate(minLevel)`
+- `EnergyIndicator`
+
+### `@kumbatio/energy-system/persistence`
+
+- `localStoragePersistence(key?)`
+- `memoryPersistence(initial?)`
+
+### `@kumbatio/energy-system/dom`
+
+- `applyEnergyLevel(level, root?)`
+- `readEnergyLevel(root?)`
+- `observeEnergyLevel(listener, root?)`
+
+### Additional APIs
+
+- `createEnergyEngine({ clock })` - inject a deterministic time source
+- `engine.dispose()` - release engine-owned observation/subscription resources
+- `EnergyPersistence.observe(onState)` - subscribe to external state changes
+- `getEnergyMetrics(state, now?)` - derive productivity/break/task guidance metrics
+
+## Migrating from legacy scales to native package levels
+
+The package model is fixed to `100 | 75 | 50 | 25 | 0`.
+If your existing app uses a different discrete scale (for example `100 | 66 | 33 | 0`),
+use compatibility helpers during migration.
+
+```ts
+import {
+  createExternalLevelCompatibility,
+  cycleEnergyLevel,
+} from '@kumbatio/energy-system'
+
+const legacy = createExternalLevelCompatibility({
+  levels: [100, 66, 33, 0] as const,
+  toEnergyLevel: {
+    100: 100,
+    66: 50,
+    33: 25,
+    0: 0,
+  },
+  fallbackLevel: 100,
+})
+
+// Read legacy persisted values -> native package level
+const nativeLevel = legacy.toEnergyLevel(66) // 50
+
+// Keep old control cycle order while internally applying native levels
+const nextNativeLevel = legacy.cycleMappedEnergyLevel(33) // maps next legacy level to native
+
+// Once migration is complete, use native cycling directly
+const next = cycleEnergyLevel(nativeLevel)
+```
+
+Recommended migration sequence:
+
+1. **Read** legacy values through `createExternalLevelCompatibility(...).toEnergyLevel(...)`.
+2. **Write** and persist native package levels (`100 | 75 | 50 | 25 | 0`).
+3. **Switch UI controls** to native `cycleEnergyLevel`.
+4. **Remove compatibility mapping** after persisted data is fully normalized.
+
+## Development
+
+```bash
+pnpm run check-types
+pnpm run build
+pnpm run pack:dry-run
+```
+
+## Notes
+
+This package is framework-agnostic at its core. Platform-specific persistence
+adapters (e.g., SQLite-backed desktop stores) should live in consuming apps.
+
+## Kumbatio
+
+`energy-system` is the infrastructure layer of [Kumbatio](https://kumbat.io) — an ecosystem of open-source, neuroinclusive software built from lived experience with ADHD and depression. The position behind it, in one line: **energy ≠ time**, and software should adapt to real cognitive capacity instead of assuming a default brain.
+
+- The full argument: [kumbat.io/manifesto](https://kumbat.io/manifesto) — agree? [Sign it](https://kumbat.io/endorse)
+- Where this library is going: [ROADMAP.md](./ROADMAP.md)
+- How to help: [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Live demo: [kumbat.io](https://kumbat.io) adapts its entire interface with this model — move the energy control and watch
+
+## License
+
+[MIT](./LICENSE)
+
+---
+
+_energy-system supports self-management and workflow adaptation. It is not a medical device, diagnosis tool, or treatment._

package/dist/compat.d.ts

@@ -0,0 +1,49 @@
+import type { EnergyLevel } from './types.js';
+/**
+ * Cycle through any discrete numeric level list.
+ */
+export declare function cycleDiscreteLevel<TLevel extends number>(current: number, levels: readonly TLevel[], fallback: TLevel): TLevel;
+/**
+ * Map an arbitrary number to the nearest available discrete level.
+ */
+export declare function mapToNearestDiscreteLevel<TLevel extends number>(value: number, levels: readonly TLevel[], fallback: TLevel): TLevel;
+/**
+ * Map any number to the closest native package energy level.
+ */
+export declare function mapToNearestEnergyLevel(value: number): EnergyLevel;
+export interface ExternalLevelCompatibilityOptions<TExternal extends number> {
+    /**
+     * External level cycle order (e.g. [100, 66, 33, 0]).
+     */
+    levels: readonly TExternal[];
+    /**
+     * Mapping from external level values to native package levels.
+     */
+    toEnergyLevel: Readonly<Record<TExternal, EnergyLevel>>;
+    /**
+     * Fallback external level when input is unknown.
+     */
+    fallbackLevel: TExternal;
+    /**
+     * Fallback native level when mapping is invalid or missing.
+     * Defaults to the mapped value of fallbackLevel.
+     */
+    fallbackEnergyLevel?: EnergyLevel;
+}
+export interface ExternalLevelCompatibility<TExternal extends number> {
+    levels: readonly TExternal[];
+    fallbackLevel: TExternal;
+    fallbackEnergyLevel: EnergyLevel;
+    toEnergyLevel: (externalLevel: TExternal | number) => EnergyLevel;
+    fromEnergyLevel: (level: EnergyLevel) => TExternal;
+    cycleExternalLevel: (current: TExternal | number) => TExternal;
+    cycleMappedEnergyLevel: (current: TExternal | number) => EnergyLevel;
+}
+/**
+ * Build a compatibility bridge for systems that use non-native level values.
+ *
+ * This is useful during migrations (e.g. legacy 4-level models) while keeping
+ * the package's native fixed 5-level model unchanged.
+ */
+export declare function createExternalLevelCompatibility<TExternal extends number>(options: ExternalLevelCompatibilityOptions<TExternal>): ExternalLevelCompatibility<TExternal>;
+//# sourceMappingURL=compat.d.ts.map

package/dist/compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compat.d.ts","sourceRoot":"","sources":["../src/compat.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAM7C;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,SAAS,MAAM,EACtD,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,QAAQ,EAAE,MAAM,GACf,MAAM,CAIR;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,SAAS,MAAM,EAC7D,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,QAAQ,EAAE,MAAM,GACf,MAAM,CAiBR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAElE;AAED,MAAM,WAAW,iCAAiC,CAAC,SAAS,SAAS,MAAM;IACzE;;OAEG;IACH,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5B;;OAEG;IACH,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAA;IACvD;;OAEG;IACH,aAAa,EAAE,SAAS,CAAA;IACxB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,WAAW,CAAA;CAClC;AAED,MAAM,WAAW,0BAA0B,CAAC,SAAS,SAAS,MAAM;IAClE,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5B,aAAa,EAAE,SAAS,CAAA;IACxB,mBAAmB,EAAE,WAAW,CAAA;IAChC,aAAa,EAAE,CAAC,aAAa,EAAE,SAAS,GAAG,MAAM,KAAK,WAAW,CAAA;IACjE,eAAe,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,SAAS,CAAA;IAClD,kBAAkB,EAAE,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,KAAK,SAAS,CAAA;IAC9D,sBAAsB,EAAE,CAAC,OAAO,EAAE,SAAS,GAAG,MAAM,KAAK,WAAW,CAAA;CACrE;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,SAAS,SAAS,MAAM,EACvE,OAAO,EAAE,iCAAiC,CAAC,SAAS,CAAC,GACpD,0BAA0B,CAAC,SAAS,CAAC,CAuFvC"}

package/dist/compat.js

@@ -0,0 +1,109 @@
+import { isEnergyLevel } from './levels.js';
+const NATIVE_ENERGY_LEVELS = [100, 75, 50, 25, 0];
+const hasOwn = (target, key) => Object.hasOwn(target, key);
+/**
+ * Cycle through any discrete numeric level list.
+ */
+export function cycleDiscreteLevel(current, levels, fallback) {
+    const index = levels.findIndex((level) => level === current);
+    if (index === -1)
+        return fallback;
+    return levels[(index + 1) % levels.length] ?? fallback;
+}
+/**
+ * Map an arbitrary number to the nearest available discrete level.
+ */
+export function mapToNearestDiscreteLevel(value, levels, fallback) {
+    if (levels.length === 0 || Number.isNaN(value)) {
+        return fallback;
+    }
+    let nearest = levels[0] ?? fallback;
+    let nearestDistance = Math.abs(nearest - value);
+    for (const level of levels) {
+        const distance = Math.abs(level - value);
+        if (distance < nearestDistance) {
+            nearest = level;
+            nearestDistance = distance;
+        }
+    }
+    return nearest;
+}
+/**
+ * Map any number to the closest native package energy level.
+ */
+export function mapToNearestEnergyLevel(value) {
+    return mapToNearestDiscreteLevel(value, NATIVE_ENERGY_LEVELS, 100);
+}
+/**
+ * Build a compatibility bridge for systems that use non-native level values.
+ *
+ * This is useful during migrations (e.g. legacy 4-level models) while keeping
+ * the package's native fixed 5-level model unchanged.
+ */
+export function createExternalLevelCompatibility(options) {
+    const { levels, toEnergyLevel, fallbackLevel } = options;
+    const normalizedLevels = Object.freeze([...levels]);
+    if (normalizedLevels.length === 0) {
+        throw new Error('External compatibility requires at least one level value');
+    }
+    if (!normalizedLevels.includes(fallbackLevel)) {
+        throw new Error('fallbackLevel must be present in levels');
+    }
+    const normalizedMap = new Map();
+    for (const externalLevel of normalizedLevels) {
+        if (!hasOwn(toEnergyLevel, externalLevel)) {
+            throw new Error(`Missing toEnergyLevel mapping for external level: ${externalLevel}`);
+        }
+        const mapped = toEnergyLevel[externalLevel];
+        if (!isEnergyLevel(mapped)) {
+            throw new Error(`Invalid native energy level mapping for external level ${externalLevel}: ${String(mapped)}`);
+        }
+        normalizedMap.set(externalLevel, mapped);
+    }
+    const fallbackEnergyLevel = options.fallbackEnergyLevel ?? normalizedMap.get(fallbackLevel) ?? 100;
+    const reverseMap = new Map();
+    for (const externalLevel of normalizedLevels) {
+        const mapped = normalizedMap.get(externalLevel);
+        if (!mapped)
+            continue;
+        if (!reverseMap.has(mapped)) {
+            reverseMap.set(mapped, externalLevel);
+        }
+    }
+    const toNativeLevel = (externalLevel) => {
+        if (hasOwn(toEnergyLevel, externalLevel)) {
+            const mapped = toEnergyLevel[externalLevel];
+            return isEnergyLevel(mapped) ? mapped : fallbackEnergyLevel;
+        }
+        const nearestExternal = mapToNearestDiscreteLevel(externalLevel, normalizedLevels, fallbackLevel);
+        return normalizedMap.get(nearestExternal) ?? fallbackEnergyLevel;
+    };
+    const fromNativeLevel = (level) => {
+        const exact = reverseMap.get(level);
+        if (exact !== undefined) {
+            return exact;
+        }
+        let nearest = fallbackLevel;
+        let nearestDistance = Number.POSITIVE_INFINITY;
+        for (const externalLevel of normalizedLevels) {
+            const mapped = normalizedMap.get(externalLevel) ?? fallbackEnergyLevel;
+            const distance = Math.abs(mapped - level);
+            if (distance < nearestDistance) {
+                nearest = externalLevel;
+                nearestDistance = distance;
+            }
+        }
+        return nearest;
+    };
+    const cycleExternal = (current) => cycleDiscreteLevel(current, normalizedLevels, fallbackLevel);
+    return Object.freeze({
+        levels: normalizedLevels,
+        fallbackLevel,
+        fallbackEnergyLevel,
+        toEnergyLevel: toNativeLevel,
+        fromEnergyLevel: fromNativeLevel,
+        cycleExternalLevel: cycleExternal,
+        cycleMappedEnergyLevel: (current) => toNativeLevel(cycleExternal(current)),
+    });
+}
+//# sourceMappingURL=compat.js.map

package/dist/compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compat.js","sourceRoot":"","sources":["../src/compat.ts"],"names":[],"mappings":"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"}

package/dist/dom.d.ts

@@ -0,0 +1,19 @@
+import type { EnergyChangeListener, EnergyLevel } from './types.js';
+/**
+ * Apply energy level to a root element.
+ * Sets `data-energy-level` attribute and CSS custom properties
+ * derived from the UI visibility strategy.
+ */
+export declare function applyEnergyLevel(level: EnergyLevel, root?: HTMLElement): void;
+/**
+ * Read the current energy level from a root element's data attribute.
+ * Returns 100 if no valid level is set.
+ */
+export declare function readEnergyLevel(root?: HTMLElement): EnergyLevel;
+/**
+ * Observe energy level changes on a root element via MutationObserver.
+ * Calls back with EnergyState (timestamp will be observation time, source 'inferred').
+ * Returns a cleanup function to disconnect the observer.
+ */
+export declare function observeEnergyLevel(callback: EnergyChangeListener, root?: HTMLElement): () => void;
+//# sourceMappingURL=dom.d.ts.map

package/dist/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAwBnE;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAU7E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAI/D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,oBAAoB,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,IAAI,CA0BjG"}

package/dist/dom.js

@@ -0,0 +1,72 @@
+import { createEnergyState, isEnergyLevel } from './levels.js';
+import { uiVisibilityStrategy } from './strategies.js';
+const ATTR = 'energyLevel';
+function resolveRoot(root) {
+    if (root) {
+        return root;
+    }
+    if (typeof document === 'undefined' || !document.body) {
+        throw new Error('Energy DOM APIs require a browser document or an explicit root element');
+    }
+    return document.body;
+}
+function normalizeEnergyLevel(level) {
+    if (!isEnergyLevel(level)) {
+        throw new Error(`Invalid energy level: ${String(level)}`);
+    }
+    return level;
+}
+/**
+ * Apply energy level to a root element.
+ * Sets `data-energy-level` attribute and CSS custom properties
+ * derived from the UI visibility strategy.
+ */
+export function applyEnergyLevel(level, root) {
+    const target = resolveRoot(root);
+    const normalizedLevel = normalizeEnergyLevel(level);
+    const config = uiVisibilityStrategy.resolve(normalizedLevel);
+    target.dataset[ATTR] = normalizedLevel.toString();
+    target.style.setProperty('--energy-chrome-opacity', config.chromeOpacity.toString());
+    target.style.setProperty('--energy-chrome-opacity-hover', config.chromeOpacityHover.toString());
+    target.style.setProperty('--energy-content-max-width', config.contentMaxWidth);
+    target.style.setProperty('--energy-content-font-scale', config.contentFontScale.toString());
+}
+/**
+ * Read the current energy level from a root element's data attribute.
+ * Returns 100 if no valid level is set.
+ */
+export function readEnergyLevel(root) {
+    const target = resolveRoot(root);
+    const raw = Number(target.dataset[ATTR]);
+    return isEnergyLevel(raw) ? raw : 100;
+}
+/**
+ * Observe energy level changes on a root element via MutationObserver.
+ * Calls back with EnergyState (timestamp will be observation time, source 'inferred').
+ * Returns a cleanup function to disconnect the observer.
+ */
+export function observeEnergyLevel(callback, root) {
+    const target = resolveRoot(root);
+    let prevLevel = readEnergyLevel(target);
+    const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+            if (mutation.type === 'attributes' && mutation.attributeName === 'data-energy-level') {
+                const currentLevel = readEnergyLevel(target);
+                if (currentLevel !== prevLevel) {
+                    const prev = createEnergyState(prevLevel, 'inferred', Date.now());
+                    const current = createEnergyState(currentLevel, 'inferred', Date.now());
+                    prevLevel = currentLevel;
+                    callback(current, prev);
+                }
+            }
+        }
+    });
+    observer.observe(target, {
+        attributes: true,
+        attributeFilter: ['data-energy-level'],
+    });
+    return () => {
+        observer.disconnect();
+    };
+}
+//# sourceMappingURL=dom.js.map

package/dist/dom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../src/dom.ts"],"names":[],"mappings":"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"}

package/dist/engine.d.ts

@@ -0,0 +1,26 @@
+import type { AdaptationStrategy, EnergyClock, EnergyChangeListener, EnergyLevel, EnergyPersistence, EnergySource, EnergyState } from './types.js';
+export interface EnergyEngineOptions {
+    initialLevel?: EnergyLevel;
+    persistence?: EnergyPersistence;
+    onChange?: EnergyChangeListener;
+    /** Deterministic time source for tests/simulations */
+    clock?: EnergyClock | (() => number);
+}
+export interface EnergyEngine {
+    /** Get current energy state */
+    getState(): EnergyState;
+    /** Set energy level with optional source */
+    setLevel(level: EnergyLevel, source?: EnergySource): void;
+    /** Cycle to next energy level */
+    cycleLevel(): void;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(listener: EnergyChangeListener): () => void;
+    /** Resolve a strategy against current energy state */
+    resolve<T>(strategy: AdaptationStrategy<T>): T;
+    /** Load persisted state (called automatically, but can be called manually) */
+    hydrate(): Promise<void>;
+    /** Release engine-owned subscriptions/resources */
+    dispose(): void;
+}
+export declare function createEnergyEngine(options?: EnergyEngineOptions): EnergyEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACZ,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,WAAW,CAAA;IAC1B,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,QAAQ,CAAC,EAAE,oBAAoB,CAAA;IAC/B,sDAAsD;IACtD,KAAK,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,MAAM,CAAC,CAAA;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,QAAQ,IAAI,WAAW,CAAA;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IACzD,iCAAiC;IACjC,UAAU,IAAI,IAAI,CAAA;IAClB,gEAAgE;IAChE,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAAA;IACrD,sDAAsD;IACtD,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAC9C,8EAA8E;IAC9E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,mDAAmD;IACnD,OAAO,IAAI,IAAI,CAAA;CAChB;AAqDD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAmMlF"}