@kumbatio/energy-system 0.3.0 → 0.4.0

package/dist/react.js

@@ -1,7 +1,8 @@
-import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useReducer, useRef, useSyncExternalStore, } from 'react';
+import { createContext, createElement, useCallback, useContext, useEffect, useInsertionEffect, useLayoutEffect, useMemo, useReducer, useRef, useSyncExternalStore, } from 'react';
 import { applyEnergyLevel } from './dom.js';
 import { createEnergyEngine } from './engine.js';
 import { getEnergyLevel, getEnergyLevels } from './levels.js';
+import { defineEnergyPresence, presenceAtOrAbove, resolveEnergyPresence } from './presence.js';
 // ── Context ──
 const EnergyEngineContext = createContext(null);
 const DOM_STYLE_PROPERTIES = [
@@ -11,6 +12,16 @@ const DOM_STYLE_PROPERTIES = [
     '--energy-content-font-scale',
 ];
 const domProjectionStacks = new WeakMap();
+function callLevelChange(listener, state, prev) {
+    if (!listener)
+        return;
+    try {
+        listener(state, prev);
+    }
+    catch (err) {
+        console.error('[energy-system] onLevelChange listener threw', err);
+    }
+}
 function restoreDOMProjection(target, snapshot) {
     if (snapshot.attribute === null) {
         target.removeAttribute('data-energy-level');
@@ -36,11 +47,26 @@ function useEngine() {
 export function EnergyProvider({ engine: externalEngine, defaultLevel = 100, persistence, onLevelChange, applyToDOM = true, children, }) {
     const internalEngineRef = useRef(null);
     const [, refreshEngine] = useReducer((version) => version + 1, 0);
+    const onLevelChangeRef = useRef(onLevelChange);
+    const isProviderCommittedRef = useRef(false);
+    const pendingInternalChangesRef = useRef([]);
+    useInsertionEffect(() => {
+        onLevelChangeRef.current = onLevelChange;
+    }, [onLevelChange]);
     // `defaultLevel` and `persistence` are initial-only by contract: they
     // configure the engine the provider creates, they do not reconfigure it.
     const createInternalEngine = () => createEnergyEngine({
         initialLevel: defaultLevel,
         ...(persistence ? { persistence } : {}),
+        onChange(state, prev) {
+            if (isProviderCommittedRef.current) {
+                callLevelChange(onLevelChangeRef.current, state, prev);
+                return;
+            }
+            if (onLevelChangeRef.current) {
+                pendingInternalChangesRef.current.push({ state, prev });
+            }
+        },
     });
     if (!externalEngine && !internalEngineRef.current) {
         internalEngineRef.current = createInternalEngine();
@@ -60,6 +86,8 @@ export function EnergyProvider({ engine: externalEngine, defaultLevel = 100, per
             return;
         }
         if (!internalEngineRef.current) {
+            isProviderCommittedRef.current = false;
+            pendingInternalChangesRef.current.length = 0;
             internalEngineRef.current = createInternalEngine();
             refreshEngine();
         }
@@ -68,6 +96,32 @@ export function EnergyProvider({ engine: externalEngine, defaultLevel = 100, per
             internalEngineRef.current = null;
         };
     }, [externalEngine]);
+    // Internal changes can happen during hydration or child layout effects
+    // before a parent effect subscription would exist. Queue them until the
+    // provider commits, then deliver them in transition order.
+    useLayoutEffect(() => {
+        if (externalEngine)
+            return;
+        isProviderCommittedRef.current = true;
+        const pending = pendingInternalChangesRef.current.splice(0);
+        for (const transition of pending) {
+            callLevelChange(onLevelChangeRef.current, transition.state, transition.prev);
+        }
+        return () => {
+            isProviderCommittedRef.current = false;
+            pendingInternalChangesRef.current.length = 0;
+        };
+    }, [engine, externalEngine]);
+    // External engines own their own pre-provider history. Subscribe before
+    // descendant layout effects so changes made after this provider commits are
+    // still reported through onLevelChange.
+    useInsertionEffect(() => {
+        if (!externalEngine)
+            return;
+        return engine.subscribe((state, prev) => {
+            callLevelChange(onLevelChangeRef.current, state, prev);
+        });
+    }, [engine, externalEngine]);
     // Sync to DOM when state changes
     useEffect(() => {
         if (!applyToDOM || typeof document === 'undefined')
@@ -114,11 +168,6 @@ export function EnergyProvider({ engine: externalEngine, defaultLevel = 100, per
             }
         };
     }, [engine, applyToDOM]);
-    useEffect(() => {
-        if (!onLevelChange)
-            return;
-        return engine.subscribe(onLevelChange);
-    }, [engine, onLevelChange]);
     return createElement(EnergyEngineContext.Provider, { value: engine }, children);
 }
 // ── Hooks ──
@@ -166,6 +215,56 @@ export function useEnergyGate(minLevel) {
     const state = useEnergyStoreState();
     return state.level >= minLevel;
 }
+/** Resolve a presence map against the current energy level */
+export function useEnergyPresence(presence) {
+    const state = useEnergyStoreState();
+    return useMemo(() => resolveEnergyPresence(presence, state.level), [presence, state.level]);
+}
+/**
+ * Declarative energy gating for a subtree.
+ *
+ * ```tsx
+ * // Hide the AI chat at 50 and below:
+ * <EnergyGate min={75}>
+ *   <AiChatPanel />
+ * </EnergyGate>
+ *
+ * // Full presence map, muted state styled by the child:
+ * <EnergyGate presence={aiChatPresence}>
+ *   {(presence) => <AiChatPanel muted={presence === 'muted'} />}
+ * </EnergyGate>
+ * ```
+ *
+ * Headless: renders no wrapper element of its own.
+ */
+export function EnergyGate({ presence, min, max, fallback = null, children, }) {
+    const map = useMemo(() => {
+        if (presence)
+            return presence;
+        if (min !== undefined && max !== undefined) {
+            const spec = {};
+            for (const definition of getEnergyLevels()) {
+                spec[definition.value] =
+                    definition.value >= min && definition.value <= max ? 'visible' : 'hidden';
+            }
+            return defineEnergyPresence(spec);
+        }
+        if (min !== undefined)
+            return presenceAtOrAbove(min);
+        if (max !== undefined) {
+            const spec = {};
+            for (const definition of getEnergyLevels()) {
+                spec[definition.value] = definition.value <= max ? 'visible' : 'hidden';
+            }
+            return defineEnergyPresence(spec);
+        }
+        throw new Error('EnergyGate requires a presence map or min/max level');
+    }, [presence, min, max]);
+    const resolved = useEnergyPresence(map);
+    if (resolved === 'hidden')
+        return fallback;
+    return typeof children === 'function' ? children(resolved) : children;
+}
 /** Headless energy indicator - bring your own UI */
 export function EnergyIndicator({ children }) {
     const [level, setLevel] = useEnergyLevel();

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,aAAa,EACb,WAAW,EACX,UAAU,EACV,SAAS,EACT,OAAO,EACP,UAAU,EACV,MAAM,EACN,oBAAoB,GACrB,MAAM,OAAO,CAAA;AAEd,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAE3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAW7D,gBAAgB;AAEhB,MAAM,mBAAmB,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAA;AACpE,MAAM,oBAAoB,GAAG;IAC3B,yBAAyB;IACzB,+BAA+B;IAC/B,4BAA4B;IAC5B,6BAA6B;CACrB,CAAA;AAiBV,MAAM,mBAAmB,GAAG,IAAI,OAAO,EAAmC,CAAA;AAE1E,SAAS,oBAAoB,CAAC,MAAmB,EAAE,QAA+B;IAChF,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAChC,MAAM,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAA;IAC7C,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,YAAY,CAAC,mBAAmB,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAA;IAC9D,CAAC;IAED,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QAChD,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACjB,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAA;QACvC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;QAC3C,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,MAAM,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAA;IAC9C,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAA;IAClF,OAAO,MAAM,CAAA;AACf,CAAC;AAkBD,MAAM,UAAU,cAAc,CAAC,EAC7B,MAAM,EAAE,cAAc,EACtB,YAAY,GAAG,GAAG,EAClB,WAAW,EACX,aAAa,EACb,UAAU,GAAG,IAAI,EACjB,QAAQ,GACY;IACpB,MAAM,iBAAiB,GAAG,MAAM,CAAsB,IAAI,CAAC,CAAA;IAC3D,MAAM,CAAC,EAAE,aAAa,CAAC,GAAG,UAAU,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IAEzE,sEAAsE;IACtE,yEAAyE;IACzE,MAAM,oBAAoB,GAAG,GAAG,EAAE,CAChC,kBAAkB,CAAC;QACjB,YAAY,EAAE,YAAY;QAC1B,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAC,CAAA;IAEJ,IAAI,CAAC,cAAc,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,CAAC;QAClD,iBAAiB,CAAC,OAAO,GAAG,oBAAoB,EAAE,CAAA;IACpD,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,IAAI,iBAAiB,CAAC,OAAO,CAAA;IAE1D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAC3E,CAAC;IAED,0EAA0E;IAC1E,sEAAsE;IACtE,0EAA0E;IAC1E,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,cAAc,EAAE,CAAC;YACnB,mEAAmE;YACnE,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,CAAA;YACpC,iBAAiB,CAAC,OAAO,GAAG,IAAI,CAAA;YAChC,OAAM;QACR,CAAC;QAED,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,CAAC;YAC/B,iBAAiB,CAAC,OAAO,GAAG,oBAAoB,EAAE,CAAA;YAClD,aAAa,EAAE,CAAA;QACjB,CAAC;QAED,OAAO,GAAG,EAAE;YACV,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,CAAA;YACpC,iBAAiB,CAAC,OAAO,GAAG,IAAI,CAAA;QAClC,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAA;IAEpB,iCAAiC;IACjC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,UAAU,IAAI,OAAO,QAAQ,KAAK,WAAW;YAAE,OAAM;QAE1D,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAA;QAC5B,MAAM,KAAK,GAAG,EAAE,CAAA;QAChB,MAAM,aAAa,GAAG,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACrD,MAAM,KAAK,GAAG,aAAa,IAAI;YAC7B,QAAQ,EAAE;gBACR,SAAS,EAAE,MAAM,CAAC,YAAY,CAAC,mBAAmB,CAAC;gBACnD,MAAM,EAAE,IAAI,GAAG,CACb,oBAAoB,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;oBACrC,QAAQ;oBACR,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,QAAQ,CAAC;iBACxC,CAAC,CACH;aACF;YACD,MAAM,EAAE,EAAE;SACX,CAAA;QACD,MAAM,KAAK,GAAuB,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAA;QAC3E,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACxB,mBAAmB,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;QACtC,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QACrC,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;YAC7C,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;YACzB,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,KAAK,EAAE,CAAC;gBACzC,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;YACvC,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,OAAO,GAAG,EAAE;YACV,WAAW,EAAE,CAAA;YACb,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,KAAK,KAAK,CAAC,CAAA;YACnF,IAAI,UAAU,KAAK,CAAC,CAAC;gBAAE,OAAM;YAE7B,MAAM,WAAW,GAAG,UAAU,KAAK,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAA;YAC1D,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAA;YAClC,IAAI,CAAC,WAAW;gBAAE,OAAM;YAExB,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;YACrC,IAAI,SAAS,EAAE,CAAC;gBACd,gBAAgB,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;YAC3C,CAAC;iBAAM,CAAC;gBACN,mBAAmB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBAClC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;YAC9C,CAAC;QACH,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;IAExB,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,aAAa;YAAE,OAAM;QAE1B,OAAO,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,CAAA;IACxC,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAA;IAE3B,OAAO,aAAa,CAAC,mBAAmB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAA;AACjF,CAAC;AAED,cAAc;AAEd,SAAS,mBAAmB;IAC1B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAC1B,0EAA0E;IAC1E,4EAA4E;IAC5E,oEAAoE;IACpE,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,aAAyB,EAAE,EAAE,CAC5B,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE;QACpB,aAAa,EAAE,CAAA;IACjB,CAAC,CAAC,EACJ,CAAC,MAAM,CAAC,CACT,CAAA;IACD,OAAO,oBAAoB,CAAC,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;AAC1E,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,cAAc;IAC5B,OAAO,mBAAmB,EAAE,CAAA;AAC9B,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,cAAc;IAI5B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAC1B,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAA;IACnC,MAAM,QAAQ,GAAG,WAAW,CAC1B,CAAC,KAAkB,EAAE,MAAM,GAAiB,QAAQ,EAAE,EAAE;QACtD,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAChC,CAAC,EACD,CAAC,MAAM,CAAC,CACT,CAAA;IACD,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;AAChC,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,kBAAkB;IAChC,OAAO,mBAAmB,EAAE,CAAA;AAC9B,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,oBAAoB;IAClC,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAC1B,OAAO,WAAW,CAAC,GAAG,EAAE;QACtB,MAAM,CAAC,UAAU,EAAE,CAAA;IACrB,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;AACd,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,WAAW,CAAI,QAA+B;IAC5D,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAA;IACnC,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;AAC9E,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,QAAqB;IACjD,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAA;IACnC,OAAO,KAAK,CAAC,KAAK,IAAI,QAAQ,CAAA;AAChC,CAAC;AAoBD,oDAAoD;AACpD,MAAM,UAAU,eAAe,CAAC,EAAE,QAAQ,EAAwB;IAChE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,cAAc,EAAE,CAAA;IAC1C,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAA;IACnC,MAAM,KAAK,GAAG,oBAAoB,EAAE,CAAA;IAEpC,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IAChE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,eAAe,EAAE,EAAE,EAAE,CAAC,CAAA;IAEnD,OAAO,QAAQ,CAAC;QACd,KAAK;QACL,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;QAC7C,KAAK;QACL,UAAU;QACV,MAAM;QACN,KAAK;QACL,QAAQ;KACT,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,aAAa,EACb,WAAW,EACX,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,eAAe,EACf,OAAO,EACP,UAAU,EACV,MAAM,EACN,oBAAoB,GACrB,MAAM,OAAO,CAAA;AAEd,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAE3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAa9F,gBAAgB;AAEhB,MAAM,mBAAmB,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAA;AACpE,MAAM,oBAAoB,GAAG;IAC3B,yBAAyB;IACzB,+BAA+B;IAC/B,4BAA4B;IAC5B,6BAA6B;CACrB,CAAA;AAiBV,MAAM,mBAAmB,GAAG,IAAI,OAAO,EAAmC,CAAA;AAE1E,SAAS,eAAe,CACtB,QAA0C,EAC1C,KAAkB,EAClB,IAAiB;IAEjB,IAAI,CAAC,QAAQ;QAAE,OAAM;IAErB,IAAI,CAAC;QACH,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IACvB,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,OAAO,CAAC,KAAK,CAAC,8CAA8C,EAAE,GAAG,CAAC,CAAA;IACpE,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,MAAmB,EAAE,QAA+B;IAChF,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAChC,MAAM,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAA;IAC7C,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,YAAY,CAAC,mBAAmB,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAA;IAC9D,CAAC;IAED,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QAChD,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACjB,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAA;QACvC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;QAC3C,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,MAAM,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAA;IAC9C,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAA;IAClF,OAAO,MAAM,CAAA;AACf,CAAC;AAkBD,MAAM,UAAU,cAAc,CAAC,EAC7B,MAAM,EAAE,cAAc,EACtB,YAAY,GAAG,GAAG,EAClB,WAAW,EACX,aAAa,EACb,UAAU,GAAG,IAAI,EACjB,QAAQ,GACY;IACpB,MAAM,iBAAiB,GAAG,MAAM,CAAsB,IAAI,CAAC,CAAA;IAC3D,MAAM,CAAC,EAAE,aAAa,CAAC,GAAG,UAAU,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IACzE,MAAM,gBAAgB,GAAG,MAAM,CAAC,aAAa,CAAC,CAAA;IAC9C,MAAM,sBAAsB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IAC5C,MAAM,yBAAyB,GAAG,MAAM,CAAmD,EAAE,CAAC,CAAA;IAE9F,kBAAkB,CAAC,GAAG,EAAE;QACtB,gBAAgB,CAAC,OAAO,GAAG,aAAa,CAAA;IAC1C,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAA;IAEnB,sEAAsE;IACtE,yEAAyE;IACzE,MAAM,oBAAoB,GAAG,GAAG,EAAE,CAChC,kBAAkB,CAAC;QACjB,YAAY,EAAE,YAAY;QAC1B,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,QAAQ,CAAC,KAAK,EAAE,IAAI;YAClB,IAAI,sBAAsB,CAAC,OAAO,EAAE,CAAC;gBACnC,eAAe,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;gBACtD,OAAM;YACR,CAAC;YAED,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC;gBAC7B,yBAAyB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;YACzD,CAAC;QACH,CAAC;KACF,CAAC,CAAA;IAEJ,IAAI,CAAC,cAAc,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,CAAC;QAClD,iBAAiB,CAAC,OAAO,GAAG,oBAAoB,EAAE,CAAA;IACpD,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,IAAI,iBAAiB,CAAC,OAAO,CAAA;IAE1D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;IAC3E,CAAC;IAED,0EAA0E;IAC1E,sEAAsE;IACtE,0EAA0E;IAC1E,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,cAAc,EAAE,CAAC;YACnB,mEAAmE;YACnE,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,CAAA;YACpC,iBAAiB,CAAC,OAAO,GAAG,IAAI,CAAA;YAChC,OAAM;QACR,CAAC;QAED,IAAI,CAAC,iBAAiB,CAAC,OAAO,EAAE,CAAC;YAC/B,sBAAsB,CAAC,OAAO,GAAG,KAAK,CAAA;YACtC,yBAAyB,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAA;YAC5C,iBAAiB,CAAC,OAAO,GAAG,oBAAoB,EAAE,CAAA;YAClD,aAAa,EAAE,CAAA;QACjB,CAAC;QAED,OAAO,GAAG,EAAE;YACV,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,CAAA;YACpC,iBAAiB,CAAC,OAAO,GAAG,IAAI,CAAA;QAClC,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAA;IAEpB,uEAAuE;IACvE,wEAAwE;IACxE,2DAA2D;IAC3D,eAAe,CAAC,GAAG,EAAE;QACnB,IAAI,cAAc;YAAE,OAAM;QAE1B,sBAAsB,CAAC,OAAO,GAAG,IAAI,CAAA;QACrC,MAAM,OAAO,GAAG,yBAAyB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;QAC3D,KAAK,MAAM,UAAU,IAAI,OAAO,EAAE,CAAC;YACjC,eAAe,CAAC,gBAAgB,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,CAAC,CAAA;QAC9E,CAAC;QAED,OAAO,GAAG,EAAE;YACV,sBAAsB,CAAC,OAAO,GAAG,KAAK,CAAA;YACtC,yBAAyB,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAA;QAC9C,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAA;IAE5B,wEAAwE;IACxE,4EAA4E;IAC5E,wCAAwC;IACxC,kBAAkB,CAAC,GAAG,EAAE;QACtB,IAAI,CAAC,cAAc;YAAE,OAAM;QAE3B,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;YACtC,eAAe,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;QACxD,CAAC,CAAC,CAAA;IACJ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAA;IAE5B,iCAAiC;IACjC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,UAAU,IAAI,OAAO,QAAQ,KAAK,WAAW;YAAE,OAAM;QAE1D,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAA;QAC5B,MAAM,KAAK,GAAG,EAAE,CAAA;QAChB,MAAM,aAAa,GAAG,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACrD,MAAM,KAAK,GAAG,aAAa,IAAI;YAC7B,QAAQ,EAAE;gBACR,SAAS,EAAE,MAAM,CAAC,YAAY,CAAC,mBAAmB,CAAC;gBACnD,MAAM,EAAE,IAAI,GAAG,CACb,oBAAoB,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;oBACrC,QAAQ;oBACR,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,QAAQ,CAAC;iBACxC,CAAC,CACH;aACF;YACD,MAAM,EAAE,EAAE;SACX,CAAA;QACD,MAAM,KAAK,GAAuB,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAA;QAC3E,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACxB,mBAAmB,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;QACtC,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QACrC,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;YAC7C,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAA;YACzB,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,KAAK,EAAE,CAAC;gBACzC,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;YACvC,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,OAAO,GAAG,EAAE;YACV,WAAW,EAAE,CAAA;YACb,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,KAAK,KAAK,CAAC,CAAA;YACnF,IAAI,UAAU,KAAK,CAAC,CAAC;gBAAE,OAAM;YAE7B,MAAM,WAAW,GAAG,UAAU,KAAK,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAA;YAC1D,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAA;YAClC,IAAI,CAAC,WAAW;gBAAE,OAAM;YAExB,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;YACrC,IAAI,SAAS,EAAE,CAAC;gBACd,gBAAgB,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;YAC3C,CAAC;iBAAM,CAAC;gBACN,mBAAmB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBAClC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;YAC9C,CAAC;QACH,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;IAExB,OAAO,aAAa,CAAC,mBAAmB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAA;AACjF,CAAC;AAED,cAAc;AAEd,SAAS,mBAAmB;IAC1B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAC1B,0EAA0E;IAC1E,4EAA4E;IAC5E,oEAAoE;IACpE,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,aAAyB,EAAE,EAAE,CAC5B,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE;QACpB,aAAa,EAAE,CAAA;IACjB,CAAC,CAAC,EACJ,CAAC,MAAM,CAAC,CACT,CAAA;IACD,OAAO,oBAAoB,CAAC,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;AAC1E,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,cAAc;IAC5B,OAAO,mBAAmB,EAAE,CAAA;AAC9B,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,cAAc;IAI5B,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAC1B,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAA;IACnC,MAAM,QAAQ,GAAG,WAAW,CAC1B,CAAC,KAAkB,EAAE,MAAM,GAAiB,QAAQ,EAAE,EAAE;QACtD,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAChC,CAAC,EACD,CAAC,MAAM,CAAC,CACT,CAAA;IACD,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;AAChC,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,kBAAkB;IAChC,OAAO,mBAAmB,EAAE,CAAA;AAC9B,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,oBAAoB;IAClC,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;IAC1B,OAAO,WAAW,CAAC,GAAG,EAAE;QACtB,MAAM,CAAC,UAAU,EAAE,CAAA;IACrB,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;AACd,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,WAAW,CAAI,QAA+B;IAC5D,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAA;IACnC,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;AAC9E,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,QAAqB;IACjD,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAA;IACnC,OAAO,KAAK,CAAC,KAAK,IAAI,QAAQ,CAAA;AAChC,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,iBAAiB,CAAC,QAA2B;IAC3D,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAA;IACnC,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,qBAAqB,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;AAC7F,CAAC;AAqCD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU,CAAC,EACzB,QAAQ,EACR,GAAG,EACH,GAAG,EACH,QAAQ,GAAG,IAAI,EACf,QAAQ,GACQ;IAChB,MAAM,GAAG,GAAG,OAAO,CAAoB,GAAG,EAAE;QAC1C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAA;QAC7B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAiD,EAAE,CAAA;YAC7D,KAAK,MAAM,UAAU,IAAI,eAAe,EAAE,EAAE,CAAC;gBAC3C,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;oBACpB,UAAU,CAAC,KAAK,IAAI,GAAG,IAAI,UAAU,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAA;YAC7E,CAAC;YACD,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAA;QACnC,CAAC;QACD,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,iBAAiB,CAAC,GAAG,CAAC,CAAA;QACpD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,GAAiD,EAAE,CAAA;YAC7D,KAAK,MAAM,UAAU,IAAI,eAAe,EAAE,EAAE,CAAC;gBAC3C,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAA;YACzE,CAAC;YACD,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAA;QACnC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAA;IACxE,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;IAExB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAA;IAEvC,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAA;IAC1C,OAAO,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;AACvE,CAAC;AAoBD,oDAAoD;AACpD,MAAM,UAAU,eAAe,CAAC,EAAE,QAAQ,EAAwB;IAChE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,cAAc,EAAE,CAAA;IAC1C,MAAM,KAAK,GAAG,mBAAmB,EAAE,CAAA;IACnC,MAAM,KAAK,GAAG,oBAAoB,EAAE,CAAA;IAEpC,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IAChE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,eAAe,EAAE,EAAE,EAAE,CAAC,CAAA;IAEnD,OAAO,QAAQ,CAAC;QACd,KAAK;QACL,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;QAC7C,KAAK;QACL,UAAU;QACV,MAAM;QACN,KAAK;QACL,QAAQ;KACT,CAAC,CAAA;AACJ,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,67 @@
+import type { EnergyEngine, EnergyEngineOptions } from './engine.js';
+import type { GateScheduler } from './gate.js';
+/** An active focus session snapshot */
+export interface FocusSession {
+    /** When the session started (epoch ms) */
+    readonly startedAt: number;
+    /** When the session ends (epoch ms). Sessions are always bounded. */
+    readonly endsAt: number;
+    /** Break nudge cadence in ms. 0 = no break nudges. */
+    readonly breakIntervalMs: number;
+}
+/**
+ * Session lifecycle events:
+ * - `start`: a session began
+ * - `break`: a break nudge is due (recurring while the session runs)
+ * - `end`: the session reached `endsAt` and auto-expired
+ * - `stop`: the session was ended manually before `endsAt`
+ */
+export type FocusSessionEvent = 'start' | 'break' | 'end' | 'stop';
+export type FocusSessionListener = (event: FocusSessionEvent, session: FocusSession) => void;
+/** Milliseconds left in a session (0 when expired) */
+export declare function sessionRemainingMs(session: FocusSession, now?: number): number;
+/** True once a session has reached its end time */
+export declare function isSessionExpired(session: FocusSession, now?: number): boolean;
+/** Anything that can be suppressed for the lifetime of a session */
+export interface FocusSuppressible {
+    setSuppressed(suppressed: boolean): void;
+}
+export interface FocusSessionControllerOptions {
+    /**
+     * Engine used for energy-aware defaults: session length from the level's
+     * expected productivity window, break cadence from the task-complexity
+     * strategy. Optional — without it, defaults are 25 minutes / no breaks.
+     */
+    engine?: EnergyEngine;
+    /**
+     * Suppression target (typically a NotificationGate). Suppressed on start,
+     * released on stop/end/dispose — the controller owns the flag for the
+     * session's lifetime, so it can never be left stuck on.
+     */
+    gate?: FocusSuppressible;
+    /** Deterministic time source for tests/simulations */
+    clock?: EnergyEngineOptions['clock'];
+    /** Deterministic timer source for tests/simulations */
+    scheduler?: GateScheduler;
+}
+export interface StartFocusSessionOptions {
+    /** Session length. Default: engine's expected productivity window, else 25. */
+    durationMinutes?: number;
+    /** Break nudge cadence. 0 disables. Default: engine's task-complexity guidance. */
+    breakEveryMinutes?: number;
+}
+export interface FocusSessionController {
+    /** Start a session (replacing any active one, which is stopped first). */
+    start(options?: StartFocusSessionOptions): FocusSession;
+    /** End the active session early. No-op when idle. */
+    stop(): void;
+    getSession(): FocusSession | null;
+    /** Milliseconds left in the active session (0 when idle) */
+    remainingMs(): number;
+    /** Subscribe to session lifecycle events. Returns unsubscribe function. */
+    subscribe(listener: FocusSessionListener): () => void;
+    /** Stop any active session and release resources */
+    dispose(): void;
+}
+export declare function createFocusSessionController(options?: FocusSessionControllerOptions): FocusSessionController;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AA2B9C,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAA;AAElE,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,YAAY,KAAK,IAAI,CAAA;AAE5F,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,SAAa,GAAG,MAAM,CAElF;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,SAAa,GAAG,OAAO,CAEjF;AAED,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI,CAAA;CACzC;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,iBAAiB,CAAA;IACxB,sDAAsD;IACtD,KAAK,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAA;IACpC,uDAAuD;IACvD,SAAS,CAAC,EAAE,aAAa,CAAA;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,KAAK,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,YAAY,CAAA;IACvD,qDAAqD;IACrD,IAAI,IAAI,IAAI,CAAA;IACZ,UAAU,IAAI,YAAY,GAAG,IAAI,CAAA;IACjC,4DAA4D;IAC5D,WAAW,IAAI,MAAM,CAAA;IACrB,2EAA2E;IAC3E,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAAA;IACrD,oDAAoD;IACpD,OAAO,IAAI,IAAI,CAAA;CAChB;AAmBD,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,6BAAkC,GAC1C,sBAAsB,CAmKxB"}

package/dist/session.js

@@ -0,0 +1,197 @@
+import { getEnergyMetrics } from './metrics.js';
+import { taskComplexityStrategy } from './strategies.js';
+/**
+ * Focus sessions — time-boxed "one thing at a time" windows layered on top of
+ * the energy model. A session is a temporary commitment, not an energy level:
+ * it suppresses interruptions for a bounded duration, surfaces break nudges,
+ * and ALWAYS ends on time.
+ *
+ * Two invariants come from field evidence (GingerMail shipped the opposite
+ * and both were user-hostile):
+ *   1. Sessions auto-expire. Expiry is an emitted event, not a predicate the
+ *      app must remember to poll — suppression can never outlive the session.
+ *   2. Suppression is lifted BEFORE the end event is emitted, so an
+ *      end-of-session notification can never be swallowed by the session's
+ *      own suppression.
+ */
+function logSessionError(message, err) {
+    console.error(`[energy-system] ${message}`, err);
+}
+function freezeObject(value) {
+    return Object.freeze(value);
+}
+/** Milliseconds left in a session (0 when expired) */
+export function sessionRemainingMs(session, now = Date.now()) {
+    return Math.max(0, session.endsAt - now);
+}
+/** True once a session has reached its end time */
+export function isSessionExpired(session, now = Date.now()) {
+    return now >= session.endsAt;
+}
+const DEFAULT_SESSION_MINUTES = 25;
+function resolveNow(clock) {
+    if (typeof clock === 'function')
+        return clock;
+    if (clock?.now)
+        return () => clock.now();
+    return () => Date.now();
+}
+const defaultScheduler = {
+    setTimeout(callback, ms) {
+        return setTimeout(callback, ms);
+    },
+    clearTimeout(handle) {
+        clearTimeout(handle);
+    },
+};
+export function createFocusSessionController(options = {}) {
+    const { engine, gate, clock, scheduler = defaultScheduler } = options;
+    const now = resolveNow(clock);
+    const listeners = new Set();
+    let session = null;
+    let endTimer;
+    let breakTimer;
+    let disposed = false;
+    function emit(event, snapshot) {
+        // Iterate over a snapshot so listeners that unsubscribe (or subscribe)
+        // during emission cannot skew the iteration.
+        const emissionListeners = [...listeners];
+        for (const listener of emissionListeners) {
+            try {
+                listener(event, snapshot);
+            }
+            catch (err) {
+                logSessionError('Focus session listener threw', err);
+            }
+        }
+    }
+    function clearTimers() {
+        if (endTimer !== undefined) {
+            scheduler.clearTimeout(endTimer);
+            endTimer = undefined;
+        }
+        if (breakTimer !== undefined) {
+            scheduler.clearTimeout(breakTimer);
+            breakTimer = undefined;
+        }
+    }
+    function releaseSuppression() {
+        try {
+            gate?.setSuppressed(false);
+        }
+        catch (err) {
+            logSessionError('Failed to release suppression', err);
+        }
+    }
+    function scheduleNextBreak(active, fromMs) {
+        if (active.breakIntervalMs <= 0)
+            return;
+        const nextBreakAt = fromMs + active.breakIntervalMs;
+        // A break nudge that would land at (or after) the session end is noise:
+        // the end event already tells the user to step away.
+        if (nextBreakAt >= active.endsAt)
+            return;
+        breakTimer = scheduler.setTimeout(() => {
+            breakTimer = undefined;
+            if (session !== active)
+                return;
+            emit('break', active);
+            scheduleNextBreak(active, nextBreakAt);
+        }, nextBreakAt - now());
+    }
+    function endSession(event) {
+        const ended = session;
+        if (!ended)
+            return;
+        clearTimers();
+        session = null;
+        // Invariant: suppression lifts before the event fires, so end/stop
+        // handlers can notify the user without being swallowed.
+        releaseSuppression();
+        emit(event, ended);
+    }
+    function defaultDurationMinutes() {
+        if (!engine)
+            return DEFAULT_SESSION_MINUTES;
+        const window = getEnergyMetrics(engine.getState(), now()).expectedProductivityWindowMinutes;
+        // At rest (0) the metrics window is 0 — an explicit session at rest still
+        // deserves a real bound rather than an instantly-expiring one.
+        return window > 0 ? window : DEFAULT_SESSION_MINUTES;
+    }
+    function defaultBreakMinutes() {
+        if (!engine)
+            return 0;
+        const config = taskComplexityStrategy.resolve(engine.getState().level);
+        return config.suggestBreaks ? config.breakIntervalMinutes : 0;
+    }
+    return {
+        start(startOptions = {}) {
+            if (disposed) {
+                throw new Error('Cannot start a session on a disposed controller');
+            }
+            const durationMinutes = startOptions.durationMinutes ?? defaultDurationMinutes();
+            if (!Number.isFinite(durationMinutes) || durationMinutes <= 0) {
+                throw new Error(`Invalid session duration: ${String(startOptions.durationMinutes)}`);
+            }
+            const breakEveryMinutes = startOptions.breakEveryMinutes ?? defaultBreakMinutes();
+            if (!Number.isFinite(breakEveryMinutes) || breakEveryMinutes < 0) {
+                throw new Error(`Invalid break interval: ${String(startOptions.breakEveryMinutes)}`);
+            }
+            if (session) {
+                endSession('stop');
+            }
+            const startedAt = now();
+            const next = freezeObject({
+                startedAt,
+                endsAt: startedAt + durationMinutes * 60_000,
+                breakIntervalMs: breakEveryMinutes * 60_000,
+            });
+            session = next;
+            try {
+                gate?.setSuppressed(true);
+            }
+            catch (err) {
+                logSessionError('Failed to apply suppression', err);
+            }
+            endTimer = scheduler.setTimeout(() => {
+                endTimer = undefined;
+                if (session === next) {
+                    endSession('end');
+                }
+            }, next.endsAt - startedAt);
+            scheduleNextBreak(next, startedAt);
+            emit('start', next);
+            return next;
+        },
+        stop() {
+            if (disposed)
+                return;
+            endSession('stop');
+        },
+        getSession() {
+            return session;
+        },
+        remainingMs() {
+            return session ? sessionRemainingMs(session, now()) : 0;
+        },
+        subscribe(listener) {
+            if (disposed) {
+                return () => { };
+            }
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        dispose() {
+            if (disposed)
+                return;
+            // Ending first guarantees suppression is released and observers hear
+            // about the interruption before listeners are torn down.
+            endSession('stop');
+            disposed = true;
+            listeners.clear();
+        },
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/strategies.d.ts

@@ -33,4 +33,19 @@ export interface TaskComplexityConfig {
     readonly breakIntervalMinutes: number;
 }
 export declare const taskComplexityStrategy: AdaptationStrategy<TaskComplexityConfig>;
+/**
+ * How much room the interface gives the user to notice and reverse mistakes.
+ * Lower energy means slower error detection, so forgiveness scales inversely
+ * with capacity: longer undo windows, confirmation on destructive actions,
+ * more frequent autosave.
+ */
+export interface InteractionForgivenessConfig {
+    /** How long an undo affordance stays available after an action */
+    readonly undoWindowMs: number;
+    /** Whether destructive actions (delete, discard, overwrite) ask first */
+    readonly confirmDestructive: boolean;
+    /** Suggested autosave cadence for in-progress work */
+    readonly autosaveIntervalMs: number;
+}
+export declare const interactionForgivenessStrategy: AdaptationStrategy<InteractionForgivenessConfig>;
 //# sourceMappingURL=strategies.d.ts.map

package/dist/strategies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../src/strategies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAe,cAAc,EAAE,MAAM,YAAY,CAAA;AAQjF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;CACjC;AA4DD,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,CAAC,kBAAkB,CAoBvE,CAAA;AAID,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,KAAK,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAA;CACjE;AAwCD,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,CAAC,kBAAkB,CAgBvE,CAAA;AAID,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAA;IACtC,4CAA4C;IAC5C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;CACtC;AAgCD,eAAO,MAAM,sBAAsB,EAAE,kBAAkB,CAAC,oBAAoB,CAY3E,CAAA"}
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../src/strategies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAe,cAAc,EAAE,MAAM,YAAY,CAAA;AAQjF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;CACjC;AA4DD,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,CAAC,kBAAkB,CAoBvE,CAAA;AAID,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,+BAA+B;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,KAAK,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAA;CACjE;AAwCD,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,CAAC,kBAAkB,CAgBvE,CAAA;AAID,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAA;IACtC,4CAA4C;IAC5C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;CACtC;AAgCD,eAAO,MAAM,sBAAsB,EAAE,kBAAkB,CAAC,oBAAoB,CAY3E,CAAA;AAID;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IAC3C,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAA;IACpC,sDAAsD;IACtD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;CACpC;AA8BD,eAAO,MAAM,8BAA8B,EAAE,kBAAkB,CAAC,4BAA4B,CAa3F,CAAA"}

package/dist/strategies.js

@@ -177,4 +177,45 @@ export const taskComplexityStrategy = {
         return TASK_CONFIGS[getEnergyLevel(level).value];
     },
 };
+const FORGIVENESS_CONFIGS = freezeObject({
+    100: freezeObject({
+        undoWindowMs: 5000,
+        confirmDestructive: false,
+        autosaveIntervalMs: 60_000,
+    }),
+    75: freezeObject({
+        undoWindowMs: 8000,
+        confirmDestructive: false,
+        autosaveIntervalMs: 45_000,
+    }),
+    50: freezeObject({
+        undoWindowMs: 10_000,
+        confirmDestructive: true,
+        autosaveIntervalMs: 30_000,
+    }),
+    25: freezeObject({
+        undoWindowMs: 15_000,
+        confirmDestructive: true,
+        autosaveIntervalMs: 20_000,
+    }),
+    0: freezeObject({
+        undoWindowMs: 20_000,
+        confirmDestructive: true,
+        autosaveIntervalMs: 15_000,
+    }),
+});
+export const interactionForgivenessStrategy = {
+    name: 'interaction-forgiveness',
+    describe(level) {
+        const def = getEnergyLevel(level);
+        const config = FORGIVENESS_CONFIGS[def.value];
+        const confirm = config.confirmDestructive
+            ? 'destructive actions confirm first'
+            : 'no confirmation friction';
+        return `${def.label}: ${config.undoWindowMs / 1000}s undo window, ${confirm}`;
+    },
+    resolve(level) {
+        return FORGIVENESS_CONFIGS[getEnergyLevel(level).value];
+    },
+};
 //# sourceMappingURL=strategies.js.map

package/dist/strategies.js.map

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

package/dist/types.d.ts

@@ -6,6 +6,22 @@ export type EnergySource = 'manual' | 'scheduled' | 'inferred';
 export declare const ENERGY_LEVEL_VALUES: ReadonlySet<number>;
 /** Valid energy source values for runtime validation */
 export declare const ENERGY_SOURCE_VALUES: ReadonlySet<EnergySource>;
+/**
+ * How a UI element participates at a given energy level.
+ *
+ * - `visible`: rendered normally
+ * - `muted`: rendered but de-emphasized (reduced opacity, secondary styling)
+ * - `hidden`: not rendered at all
+ */
+export type EnergyPresence = 'visible' | 'muted' | 'hidden';
+/**
+ * A complete presence declaration: one presence value per energy level.
+ * This is the annotation apps attach to components/views to state which
+ * energy levels they belong to (e.g. "hide the AI chat at 50 and below").
+ */
+export type EnergyPresenceMap = Readonly<Record<EnergyLevel, EnergyPresence>>;
+/** Valid energy presence values for runtime validation */
+export declare const ENERGY_PRESENCE_VALUES: ReadonlySet<EnergyPresence>;
 /** A point-in-time snapshot of cognitive capacity */
 export interface EnergyState {
     /** Current cognitive capacity */
@@ -14,7 +30,7 @@ export interface EnergyState {
     readonly timestamp: number;
     /** How this state was determined */
     readonly source: EnergySource;
-    /** Logical sequence for writes sharing the same timestamp and source priority */
+    /** Logical sequence for writes sharing the same timestamp */
     readonly revision: number;
     /** Stable identity of the engine/context that produced this state */
     readonly origin: string;

package/dist/types.d.ts.map

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