@kumbatio/energy-system 0.1.0

package/dist/engine.js

@@ -0,0 +1,218 @@
+import { createEnergyState, cycleEnergyLevel, isEnergyLevel, isEnergySource } from './levels.js';
+function logEngineError(message, err) {
+    console.error(`[energy-system] ${message}`, err);
+}
+const PERSIST_RETRY_INITIAL_MS = 250;
+const PERSIST_RETRY_MAX_MS = 30_000;
+function resolveNow(clock) {
+    if (typeof clock === 'function')
+        return clock;
+    if (clock?.now)
+        return () => clock.now();
+    return () => Date.now();
+}
+function isSameState(a, b) {
+    return a.level === b.level && a.timestamp === b.timestamp && a.source === b.source;
+}
+function getSourcePriority(source) {
+    switch (source) {
+        case 'manual':
+            return 3;
+        case 'scheduled':
+            return 2;
+        case 'inferred':
+            return 1;
+    }
+}
+function isPreferredExternalState(candidate, current) {
+    if (candidate.timestamp !== current.timestamp) {
+        return candidate.timestamp > current.timestamp;
+    }
+    if (candidate.source !== current.source) {
+        return getSourcePriority(candidate.source) > getSourcePriority(current.source);
+    }
+    return false;
+}
+function normalizeState(candidate, now) {
+    if (!isEnergyLevel(candidate.level)) {
+        throw new Error(`Invalid energy level from persistence: ${String(candidate.level)}`);
+    }
+    const timestamp = Number.isFinite(candidate.timestamp) ? candidate.timestamp : now();
+    const source = isEnergySource(candidate.source) ? candidate.source : 'manual';
+    return createEnergyState(candidate.level, source, timestamp);
+}
+export function createEnergyEngine(options = {}) {
+    const { initialLevel = 100, persistence, onChange, clock } = options;
+    const now = resolveNow(clock);
+    const listeners = new Set();
+    let stateVersion = 0;
+    let disposed = false;
+    let state = createEnergyState(initialLevel, 'manual', now());
+    let persistedVersion = 0;
+    let requestedPersistVersion = 0;
+    let persistTask;
+    let persistRetryTimer;
+    let persistRetryDelayMs = PERSIST_RETRY_INITIAL_MS;
+    function queuePersist() {
+        if (!persistence || disposed)
+            return;
+        requestedPersistVersion = Math.max(requestedPersistVersion, stateVersion);
+        if (persistTask)
+            return;
+        persistTask = (async () => {
+            while (!disposed && persistedVersion < requestedPersistVersion) {
+                const snapshot = state;
+                const snapshotVersion = stateVersion;
+                try {
+                    await persistence.save(snapshot);
+                    persistedVersion = Math.max(persistedVersion, snapshotVersion);
+                    persistRetryDelayMs = PERSIST_RETRY_INITIAL_MS;
+                }
+                catch (err) {
+                    logEngineError('Failed to persist energy state', err);
+                    persistTask = undefined;
+                    if (!disposed && !persistRetryTimer && persistedVersion < requestedPersistVersion) {
+                        const retryDelayMs = persistRetryDelayMs;
+                        // Exponential backoff so a persistently failing store (e.g. quota
+                        // exceeded) is not hammered every 250ms forever.
+                        persistRetryDelayMs = Math.min(persistRetryDelayMs * 2, PERSIST_RETRY_MAX_MS);
+                        persistRetryTimer = setTimeout(() => {
+                            persistRetryTimer = undefined;
+                            queuePersist();
+                        }, retryDelayMs);
+                    }
+                    return;
+                }
+            }
+            persistTask = undefined;
+            if (!disposed && persistedVersion < requestedPersistVersion) {
+                queuePersist();
+            }
+        })();
+    }
+    function notify(prev) {
+        if (onChange) {
+            try {
+                onChange(state, prev);
+            }
+            catch (err) {
+                logEngineError('onChange listener threw', err);
+            }
+        }
+        for (const listener of listeners) {
+            try {
+                listener(state, prev);
+            }
+            catch (err) {
+                logEngineError('Energy subscriber threw', err);
+            }
+        }
+    }
+    function applyState(next) {
+        // A disposed engine is inert: it must not mutate state, notify onChange,
+        // or schedule persistence after its resources were released.
+        if (disposed || isSameState(next, state))
+            return false;
+        const prev = state;
+        state = next;
+        stateVersion += 1;
+        notify(prev);
+        if (persistence) {
+            queuePersist();
+        }
+        return true;
+    }
+    let disposePersistenceObservation = () => { };
+    const engine = {
+        getState() {
+            return state;
+        },
+        setLevel(level, source = 'manual') {
+            applyState(createEnergyState(level, source, now()));
+        },
+        cycleLevel() {
+            engine.setLevel(cycleEnergyLevel(state.level), 'manual');
+        },
+        subscribe(listener) {
+            if (disposed) {
+                return () => { };
+            }
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        resolve(strategy) {
+            return strategy.resolve(state.level);
+        },
+        async hydrate() {
+            if (!persistence || disposed)
+                return;
+            const hydrateStartVersion = stateVersion;
+            let stored;
+            try {
+                stored = await persistence.load();
+            }
+            catch (err) {
+                logEngineError('Failed to load persisted energy state', err);
+                return;
+            }
+            if (!stored || disposed)
+                return;
+            let normalized;
+            try {
+                normalized = normalizeState(stored, now);
+            }
+            catch (err) {
+                logEngineError('Ignoring invalid persisted energy state', err);
+                return;
+            }
+            if (isSameState(normalized, state))
+                return;
+            if (hydrateStartVersion === stateVersion || isPreferredExternalState(normalized, state)) {
+                applyState(normalized);
+            }
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            disposePersistenceObservation();
+            if (persistRetryTimer) {
+                clearTimeout(persistRetryTimer);
+                persistRetryTimer = undefined;
+            }
+            listeners.clear();
+        },
+    };
+    // Auto-hydrate from persistence
+    if (persistence) {
+        void engine.hydrate().catch((err) => {
+            logEngineError('Unexpected hydrate failure', err);
+        });
+    }
+    if (persistence?.observe) {
+        try {
+            disposePersistenceObservation = persistence.observe((externalState) => {
+                if (disposed)
+                    return;
+                let normalized;
+                try {
+                    normalized = normalizeState(externalState, now);
+                }
+                catch (err) {
+                    logEngineError('Ignoring invalid observed energy state', err);
+                    return;
+                }
+                if (!isPreferredExternalState(normalized, state))
+                    return;
+                applyState(normalized);
+            });
+        }
+        catch (err) {
+            logEngineError('Failed to subscribe to persistence observation', err);
+        }
+    }
+    return engine;
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { AdaptationStrategy, CognitiveProfile, DecisionCapacity, EnergyClock, EnergyChangeListener, EnergyLevel, EnergyLevelDefinition, EnergyMetrics, EnergyPersistence, EnergySource, EnergyState, FocusDuration, InterruptionTolerance, TaskComplexity, } from './types.js';
+export { ENERGY_LEVEL_VALUES, ENERGY_SOURCE_VALUES } from './types.js';
+export { createEnergyState, cycleEnergyLevel, getEnergyLevel, getEnergyLevels, isEnergyLevel, isEnergySource, isHigherEnergy, } from './levels.js';
+export type { ExternalLevelCompatibility, ExternalLevelCompatibilityOptions } from './compat.js';
+export { createExternalLevelCompatibility, cycleDiscreteLevel, mapToNearestDiscreteLevel, mapToNearestEnergyLevel, } from './compat.js';
+export { getEnergyMetrics } from './metrics.js';
+export type { EnergyEngine, EnergyEngineOptions } from './engine.js';
+export { createEnergyEngine } from './engine.js';
+export type { NotificationConfig, TaskComplexityConfig, UIVisibilityConfig } from './strategies.js';
+export { notificationStrategy, taskComplexityStrategy, uiVisibilityStrategy } from './strategies.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,oBAAoB,EACpB,WAAW,EACX,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,qBAAqB,EACrB,cAAc,GACf,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAGtE,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAA;AAEpB,YAAY,EAAE,0BAA0B,EAAE,iCAAiC,EAAE,MAAM,aAAa,CAAA;AAChG,OAAO,EACL,gCAAgC,EAChC,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAG/C,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAGhD,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACnG,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { ENERGY_LEVEL_VALUES, ENERGY_SOURCE_VALUES } from './types.js';
+// Level definitions and pure functions
+export { createEnergyState, cycleEnergyLevel, getEnergyLevel, getEnergyLevels, isEnergyLevel, isEnergySource, isHigherEnergy, } from './levels.js';
+export { createExternalLevelCompatibility, cycleDiscreteLevel, mapToNearestDiscreteLevel, mapToNearestEnergyLevel, } from './compat.js';
+// Derived metrics
+export { getEnergyMetrics } from './metrics.js';
+export { createEnergyEngine } from './engine.js';
+export { notificationStrategy, taskComplexityStrategy, uiVisibilityStrategy } from './strategies.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEtE,uCAAuC;AACvC,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,gCAAgC,EAChC,kBAAkB,EAClB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,aAAa,CAAA;AAEpB,kBAAkB;AAClB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAI/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAIhD,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/levels.d.ts

@@ -0,0 +1,16 @@
+import type { EnergyLevel, EnergyLevelDefinition, EnergySource, EnergyState } from './types.js';
+/** Get all energy level definitions, ordered highest to lowest */
+export declare function getEnergyLevels(): ReadonlyArray<Readonly<EnergyLevelDefinition>>;
+/** Get definition for a specific energy level */
+export declare function getEnergyLevel(level: EnergyLevel): Readonly<EnergyLevelDefinition>;
+/** Cycle to the next energy level: 100 -> 75 -> 50 -> 25 -> 0 -> 100 */
+export declare function cycleEnergyLevel(current: EnergyLevel): EnergyLevel;
+/** Validate that an unknown value is a valid EnergyLevel */
+export declare function isEnergyLevel(value: unknown): value is EnergyLevel;
+/** Validate that an unknown value is a valid EnergySource */
+export declare function isEnergySource(value: unknown): value is EnergySource;
+/** Returns true if level `a` represents higher energy than level `b` */
+export declare function isHigherEnergy(a: EnergyLevel, b: EnergyLevel): boolean;
+/** Create an EnergyState for the current moment */
+export declare function createEnergyState(level: EnergyLevel, source?: EnergySource, timestamp?: number): EnergyState;
+//# sourceMappingURL=levels.d.ts.map

package/dist/levels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.d.ts","sourceRoot":"","sources":["../src/levels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAyE/F,kEAAkE;AAClE,wBAAgB,eAAe,IAAI,aAAa,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC,CAEhF;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,QAAQ,CAAC,qBAAqB,CAAC,CAIlF;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CAKlE;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAEtE;AAED,mDAAmD;AACnD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,MAAM,GAAE,YAAuB,EAC/B,SAAS,SAAa,GACrB,WAAW,CAcb"}

package/dist/levels.js

@@ -0,0 +1,114 @@
+import { ENERGY_LEVEL_VALUES, ENERGY_SOURCE_VALUES } from './types.js';
+function freezeObject(value) {
+    return Object.freeze(value);
+}
+const LEVELS = Object.freeze([
+    freezeObject({
+        value: 100,
+        key: 'peak',
+        label: 'Peak',
+        description: 'High capacity. Planning, complex decisions, creative work.',
+        cognitiveProfile: freezeObject({
+            decisionCapacity: 'high',
+            focusDuration: 'extended',
+            taskComplexity: 'complex',
+            interruptionTolerance: 'high',
+        }),
+    }),
+    freezeObject({
+        value: 75,
+        key: 'active',
+        label: 'Active',
+        description: 'Good capacity. Focused execution, problem-solving.',
+        cognitiveProfile: freezeObject({
+            decisionCapacity: 'moderate',
+            focusDuration: 'moderate',
+            taskComplexity: 'moderate',
+            interruptionTolerance: 'moderate',
+        }),
+    }),
+    freezeObject({
+        value: 50,
+        key: 'steady',
+        label: 'Steady',
+        description: 'Moderate capacity. Routine tasks, familiar work.',
+        cognitiveProfile: freezeObject({
+            decisionCapacity: 'low',
+            focusDuration: 'short',
+            taskComplexity: 'routine',
+            interruptionTolerance: 'low',
+        }),
+    }),
+    freezeObject({
+        value: 25,
+        key: 'low',
+        label: 'Low',
+        description: 'Limited capacity. Simple tasks, review, light work.',
+        cognitiveProfile: freezeObject({
+            decisionCapacity: 'minimal',
+            focusDuration: 'minimal',
+            taskComplexity: 'simple',
+            interruptionTolerance: 'minimal',
+        }),
+    }),
+    freezeObject({
+        value: 0,
+        key: 'rest',
+        label: 'Rest',
+        description: 'Depleted. Consumption only \u2014 reading, reflecting.',
+        cognitiveProfile: freezeObject({
+            decisionCapacity: 'none',
+            focusDuration: 'none',
+            taskComplexity: 'consumption',
+            interruptionTolerance: 'none',
+        }),
+    }),
+]);
+/** Cycle order: 100 -> 75 -> 50 -> 25 -> 0 -> 100 */
+const CYCLE_ORDER = [100, 75, 50, 25, 0];
+/** Get all energy level definitions, ordered highest to lowest */
+export function getEnergyLevels() {
+    return LEVELS;
+}
+/** Get definition for a specific energy level */
+export function getEnergyLevel(level) {
+    const def = LEVELS.find((l) => l.value === level);
+    if (!def)
+        throw new Error(`Invalid energy level: ${level}`);
+    return def;
+}
+/** Cycle to the next energy level: 100 -> 75 -> 50 -> 25 -> 0 -> 100 */
+export function cycleEnergyLevel(current) {
+    const fallback = 100;
+    const idx = CYCLE_ORDER.indexOf(current);
+    if (idx === -1)
+        return fallback;
+    return CYCLE_ORDER[(idx + 1) % CYCLE_ORDER.length] ?? fallback;
+}
+/** Validate that an unknown value is a valid EnergyLevel */
+export function isEnergyLevel(value) {
+    return typeof value === 'number' && ENERGY_LEVEL_VALUES.has(value);
+}
+/** Validate that an unknown value is a valid EnergySource */
+export function isEnergySource(value) {
+    return typeof value === 'string' && ENERGY_SOURCE_VALUES.has(value);
+}
+/** Returns true if level `a` represents higher energy than level `b` */
+export function isHigherEnergy(a, b) {
+    return a > b;
+}
+/** Create an EnergyState for the current moment */
+export function createEnergyState(level, source = 'manual', timestamp = Date.now()) {
+    if (!isEnergyLevel(level)) {
+        throw new Error(`Invalid energy level: ${String(level)}`);
+    }
+    if (!isEnergySource(source)) {
+        throw new Error(`Invalid energy source: ${String(source)}`);
+    }
+    return freezeObject({
+        level,
+        timestamp: Number.isFinite(timestamp) ? timestamp : Date.now(),
+        source,
+    });
+}
+//# sourceMappingURL=levels.js.map

package/dist/levels.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,6 @@
+import type { EnergyMetrics, EnergyState } from './types.js';
+/**
+ * Derive app-agnostic energy metrics from the current state.
+ */
+export declare function getEnergyMetrics(state: EnergyState, now?: number): EnergyMetrics;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AA4BzE;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,SAAa,GAAG,aAAa,CAqBpF"}

package/dist/metrics.js

@@ -0,0 +1,47 @@
+import { getEnergyLevel } from './levels.js';
+function freezeObject(value) {
+    return Object.freeze(value);
+}
+const PRODUCTIVITY_WINDOW_MINUTES = {
+    100: 120,
+    75: 90,
+    50: 45,
+    25: 25,
+    0: 0,
+};
+const BREAK_INTERVAL_MINUTES = {
+    100: 90,
+    75: 60,
+    50: 45,
+    25: 25,
+    0: 15,
+};
+const RECOVERY_HINT_MINUTES = {
+    50: 10,
+    25: 20,
+    0: 30,
+};
+/**
+ * Derive app-agnostic energy metrics from the current state.
+ */
+export function getEnergyMetrics(state, now = Date.now()) {
+    const safeNow = Number.isFinite(now) ? now : Date.now();
+    const stateAgeMs = Math.max(0, safeNow - state.timestamp);
+    const definition = getEnergyLevel(state.level);
+    const recoveryHintMinutes = RECOVERY_HINT_MINUTES[state.level];
+    const base = {
+        stateAgeMs,
+        stateAgeMinutes: Math.round(stateAgeMs / 60_000),
+        expectedProductivityWindowMinutes: PRODUCTIVITY_WINDOW_MINUTES[state.level],
+        suggestedBreakIntervalMinutes: BREAK_INTERVAL_MINUTES[state.level],
+        recommendedTaskComplexity: definition.cognitiveProfile.taskComplexity,
+        sustainable: state.level > 0 && state.level < 100,
+    };
+    return recoveryHintMinutes === undefined
+        ? freezeObject(base)
+        : freezeObject({
+            ...base,
+            recoveryHintMinutes,
+        });
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAG5C,SAAS,YAAY,CAAmB,KAAQ;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC7B,CAAC;AAED,MAAM,2BAA2B,GAAgC;IAC/D,GAAG,EAAE,GAAG;IACR,EAAE,EAAE,EAAE;IACN,EAAE,EAAE,EAAE;IACN,EAAE,EAAE,EAAE;IACN,CAAC,EAAE,CAAC;CACL,CAAA;AAED,MAAM,sBAAsB,GAAgC;IAC1D,GAAG,EAAE,EAAE;IACP,EAAE,EAAE,EAAE;IACN,EAAE,EAAE,EAAE;IACN,EAAE,EAAE,EAAE;IACN,CAAC,EAAE,EAAE;CACN,CAAA;AAED,MAAM,qBAAqB,GAAyC;IAClE,EAAE,EAAE,EAAE;IACN,EAAE,EAAE,EAAE;IACN,CAAC,EAAE,EAAE;CACN,CAAA;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAkB,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACnE,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAA;IACvD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAA;IACzD,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC9C,MAAM,mBAAmB,GAAG,qBAAqB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAE9D,MAAM,IAAI,GAAkB;QAC1B,UAAU;QACV,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,MAAM,CAAC;QAChD,iCAAiC,EAAE,2BAA2B,CAAC,KAAK,CAAC,KAAK,CAAC;QAC3E,6BAA6B,EAAE,sBAAsB,CAAC,KAAK,CAAC,KAAK,CAAC;QAClE,yBAAyB,EAAE,UAAU,CAAC,gBAAgB,CAAC,cAAc;QACrE,WAAW,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,GAAG,GAAG;KAClD,CAAA;IAED,OAAO,mBAAmB,KAAK,SAAS;QACtC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC;QACpB,CAAC,CAAC,YAAY,CAAC;YACX,GAAG,IAAI;YACP,mBAAmB;SACpB,CAAC,CAAA;AACR,CAAC"}

package/dist/persistence.d.ts

@@ -0,0 +1,12 @@
+import type { EnergyPersistence, EnergyState } from './types.js';
+/**
+ * localStorage-based persistence adapter.
+ * Stores the full EnergyState as JSON.
+ */
+export declare function localStoragePersistence(key?: string): EnergyPersistence;
+/**
+ * In-memory persistence adapter.
+ * Useful for tests, SSR, or ephemeral sessions.
+ */
+export declare function memoryPersistence(initial?: EnergyState): EnergyPersistence;
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AA0B7E;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,SAAiB,GAAG,iBAAiB,CA4C/E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,iBAAiB,CAwB1E"}

package/dist/persistence.js

@@ -0,0 +1,93 @@
+import { createEnergyState, isEnergyLevel } from './levels.js';
+function parsePersistedState(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            'level' in parsed &&
+            isEnergyLevel(parsed.level)) {
+            const obj = parsed;
+            return createEnergyState(obj.level, obj.source === 'scheduled' || obj.source === 'inferred' ? obj.source : 'manual', typeof obj.timestamp === 'number' ? obj.timestamp : Date.now());
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * localStorage-based persistence adapter.
+ * Stores the full EnergyState as JSON.
+ */
+export function localStoragePersistence(key = 'energy-state') {
+    return {
+        async load() {
+            if (typeof localStorage === 'undefined') {
+                return null;
+            }
+            const raw = localStorage.getItem(key);
+            return parsePersistedState(raw);
+        },
+        async save(state) {
+            try {
+                localStorage.setItem(key, JSON.stringify(state));
+            }
+            catch (err) {
+                // Rejecting (instead of swallowing) lets the engine's persistence
+                // queue observe the failure and retry with backoff. This also covers
+                // environments without localStorage (ReferenceError).
+                throw new Error(`Failed to save energy state to localStorage key '${key}'`, { cause: err });
+            }
+        },
+        observe(onState) {
+            if (typeof globalThis.addEventListener !== 'function' ||
+                typeof localStorage === 'undefined') {
+                return () => { };
+            }
+            const handleStorage = (event) => {
+                if (event.storageArea !== localStorage)
+                    return;
+                if (event.key !== key)
+                    return;
+                const parsed = parsePersistedState(event.newValue);
+                if (parsed) {
+                    onState(parsed);
+                }
+            };
+            globalThis.addEventListener('storage', handleStorage);
+            return () => {
+                globalThis.removeEventListener('storage', handleStorage);
+            };
+        },
+    };
+}
+/**
+ * In-memory persistence adapter.
+ * Useful for tests, SSR, or ephemeral sessions.
+ */
+export function memoryPersistence(initial) {
+    let stored = initial === undefined
+        ? null
+        : createEnergyState(initial.level, initial.source, initial.timestamp);
+    const listeners = new Set();
+    return {
+        async load() {
+            return stored;
+        },
+        async save(state) {
+            stored = createEnergyState(state.level, state.source, state.timestamp);
+            for (const listener of listeners) {
+                listener(stored);
+            }
+        },
+        observe(onState) {
+            listeners.add(onState);
+            return () => {
+                listeners.delete(onState);
+            };
+        },
+    };
+}
+//# sourceMappingURL=persistence.js.map

package/dist/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG9D,SAAS,mBAAmB,CAAC,GAAkB;IAC7C,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAA;IAErB,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QACvC,IACE,OAAO,MAAM,KAAK,QAAQ;YAC1B,MAAM,KAAK,IAAI;YACf,OAAO,IAAI,MAAM;YACjB,aAAa,CAAE,MAA6B,CAAC,KAAK,CAAC,EACnD,CAAC;YACD,MAAM,GAAG,GAAG,MAAqE,CAAA;YACjF,OAAO,iBAAiB,CACtB,GAAG,CAAC,KAAK,EACT,GAAG,CAAC,MAAM,KAAK,WAAW,IAAI,GAAG,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,EAC/E,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAC/D,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAG,GAAG,cAAc;IAC1D,OAAO;QACL,KAAK,CAAC,IAAI;YACR,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;gBACxC,OAAO,IAAI,CAAA;YACb,CAAC;YAED,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;YACrC,OAAO,mBAAmB,CAAC,GAAG,CAAC,CAAA;QACjC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAkB;YAC3B,IAAI,CAAC;gBACH,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;YAClD,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,kEAAkE;gBAClE,qEAAqE;gBACrE,sDAAsD;gBACtD,MAAM,IAAI,KAAK,CAAC,oDAAoD,GAAG,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;YAC7F,CAAC;QACH,CAAC;QACD,OAAO,CAAC,OAAO;YACb,IACE,OAAO,UAAU,CAAC,gBAAgB,KAAK,UAAU;gBACjD,OAAO,YAAY,KAAK,WAAW,EACnC,CAAC;gBACD,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;YACjB,CAAC;YAED,MAAM,aAAa,GAAG,CAAC,KAAmB,EAAE,EAAE;gBAC5C,IAAI,KAAK,CAAC,WAAW,KAAK,YAAY;oBAAE,OAAM;gBAC9C,IAAI,KAAK,CAAC,GAAG,KAAK,GAAG;oBAAE,OAAM;gBAE7B,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;gBAClD,IAAI,MAAM,EAAE,CAAC;oBACX,OAAO,CAAC,MAAM,CAAC,CAAA;gBACjB,CAAC;YACH,CAAC,CAAA;YAED,UAAU,CAAC,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAA;YACrD,OAAO,GAAG,EAAE;gBACV,UAAU,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAA;YAC1D,CAAC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAqB;IACrD,IAAI,MAAM,GACR,OAAO,KAAK,SAAS;QACnB,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;IACzE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAgC,CAAA;IAEzD,OAAO;QACL,KAAK,CAAC,IAAI;YACR,OAAO,MAAM,CAAA;QACf,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAkB;YAC3B,MAAM,GAAG,iBAAiB,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;YACtE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,QAAQ,CAAC,MAAM,CAAC,CAAA;YAClB,CAAC;QACH,CAAC;QACD,OAAO,CAAC,OAAO;YACb,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YACtB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;YAC3B,CAAC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,45 @@
+import type { EnergyEngine } from './engine.js';
+import type { AdaptationStrategy, EnergyChangeListener, EnergyLevel, EnergyLevelDefinition, EnergyPersistence, EnergyState } from './types.js';
+export interface EnergyProviderProps {
+    /** Pre-created engine. When provided, this engine is used directly. */
+    engine?: EnergyEngine;
+    /** Initial energy level when the provider creates its own engine. */
+    defaultLevel?: EnergyLevel;
+    /** Persistence adapter when the provider creates its own engine. */
+    persistence?: EnergyPersistence;
+    /** Called on every level change. */
+    onLevelChange?: EnergyChangeListener;
+    /** Whether to apply energy level to DOM via data attributes */
+    applyToDOM?: boolean;
+    children: React.ReactNode;
+}
+export declare function EnergyProvider({ engine: externalEngine, defaultLevel, persistence, onLevelChange, applyToDOM, children, }: EnergyProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<EnergyEngine | null>>;
+/** Get the full energy state (level + timestamp + source) */
+export declare function useEnergyState(): EnergyState;
+/** Read the current energy level and setter */
+export declare function useEnergyLevel(): [EnergyLevel, (level: EnergyLevel) => void];
+/** @deprecated Use useEnergyState instead. */
+export declare function useFullEnergyState(): EnergyState;
+/** Returns a function that cycles to the next energy level */
+export declare function useEnergyLevelCycler(): () => void;
+/** Resolve a strategy against current energy level */
+export declare function useStrategy<T>(strategy: AdaptationStrategy<T>): T;
+/** Returns true if current energy level meets or exceeds the given minimum */
+export declare function useEnergyGate(minLevel: EnergyLevel): boolean;
+export interface EnergyIndicatorRenderProps {
+    level: EnergyLevel;
+    label: string;
+    description: string;
+    cognitiveProfile: EnergyLevelDefinition['cognitiveProfile'];
+    state: EnergyState;
+    definition: EnergyLevelDefinition;
+    levels: readonly EnergyLevelDefinition[];
+    cycle: () => void;
+    setLevel: (level: EnergyLevel) => void;
+}
+export interface EnergyIndicatorProps {
+    children: (props: EnergyIndicatorRenderProps) => React.ReactNode;
+}
+/** Headless energy indicator - bring your own UI */
+export declare function EnergyIndicator({ children }: EnergyIndicatorProps): React.ReactNode;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG/C,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACZ,MAAM,YAAY,CAAA;AAcnB,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,qEAAqE;IACrE,YAAY,CAAC,EAAE,WAAW,CAAA;IAC1B,oEAAoE;IACpE,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,oCAAoC;IACpC,aAAa,CAAC,EAAE,oBAAoB,CAAA;IACpC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAC1B;AAED,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EAAE,cAAc,EACtB,YAAkB,EAClB,WAAW,EACX,aAAa,EACb,UAAiB,EACjB,QAAQ,GACT,EAAE,mBAAmB,gGA8DrB;AAmBD,6DAA6D;AAC7D,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC,CAU5E;AAED,8CAA8C;AAC9C,wBAAgB,kBAAkB,IAAI,WAAW,CAEhD;AAED,8DAA8D;AAC9D,wBAAgB,oBAAoB,IAAI,MAAM,IAAI,CAKjD;AAED,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,CAGjE;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAG5D;AAID,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,WAAW,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,qBAAqB,CAAC,kBAAkB,CAAC,CAAA;IAC3D,KAAK,EAAE,WAAW,CAAA;IAClB,UAAU,EAAE,qBAAqB,CAAA;IACjC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAA;IACxC,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,KAAK,CAAC,SAAS,CAAA;CACjE;AAED,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,EAAE,oBAAoB,GAAG,KAAK,CAAC,SAAS,CAmBnF"}