@kumbatio/energy-system 0.1.0

package/dist/react.js

@@ -0,0 +1,130 @@
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useReducer, useRef, useSyncExternalStore, } from 'react';
+import { applyEnergyLevel } from './dom.js';
+import { createEnergyEngine } from './engine.js';
+import { getEnergyLevel, getEnergyLevels } from './levels.js';
+// ── Context ──
+const EnergyEngineContext = createContext(null);
+function useEngine() {
+    const engine = useContext(EnergyEngineContext);
+    if (!engine)
+        throw new Error('Energy hooks must be used within an EnergyProvider');
+    return engine;
+}
+export function EnergyProvider({ engine: externalEngine, defaultLevel = 100, persistence, onLevelChange, applyToDOM = true, children, }) {
+    const internalEngineRef = useRef(null);
+    const [, refreshEngine] = useReducer((version) => version + 1, 0);
+    // `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 } : {}),
+    });
+    if (!externalEngine && !internalEngineRef.current) {
+        internalEngineRef.current = createInternalEngine();
+    }
+    const engine = externalEngine ?? internalEngineRef.current;
+    if (!engine) {
+        throw new Error('EnergyProvider could not initialize an engine instance');
+    }
+    // Own the internal engine's lifecycle. The cleanup disposes it; the setup
+    // recreates it when the previous one was disposed (StrictMode re-runs
+    // effects without re-rendering, so render-time lazy init cannot recover).
+    useEffect(() => {
+        if (externalEngine) {
+            // An external engine took over; release the provider-owned engine.
+            internalEngineRef.current?.dispose();
+            internalEngineRef.current = null;
+            return;
+        }
+        if (!internalEngineRef.current) {
+            internalEngineRef.current = createInternalEngine();
+            refreshEngine();
+        }
+        return () => {
+            internalEngineRef.current?.dispose();
+            internalEngineRef.current = null;
+        };
+    }, [externalEngine]);
+    // Sync to DOM when state changes
+    useEffect(() => {
+        if (!applyToDOM || typeof document === 'undefined')
+            return;
+        // Apply initial
+        applyEnergyLevel(engine.getState().level);
+        // Subscribe to changes
+        return engine.subscribe((state) => {
+            applyEnergyLevel(state.level);
+        });
+    }, [engine, applyToDOM]);
+    useEffect(() => {
+        if (!onLevelChange)
+            return;
+        return engine.subscribe(onLevelChange);
+    }, [engine, onLevelChange]);
+    return createElement(EnergyEngineContext.Provider, { value: engine }, children);
+}
+// ── Hooks ──
+function useEnergyStoreState() {
+    const engine = useEngine();
+    // Stable subscribe identity so useSyncExternalStore doesn't unsubscribe +
+    // resubscribe on every render. `engine.getState` is closure-backed (doesn't
+    // use `this`), so it's safe to pass unbound as the snapshot getter.
+    const subscribe = useCallback((onStoreChange) => engine.subscribe(() => {
+        onStoreChange();
+    }), [engine]);
+    return useSyncExternalStore(subscribe, engine.getState, engine.getState);
+}
+/** Get the full energy state (level + timestamp + source) */
+export function useEnergyState() {
+    return useEnergyStoreState();
+}
+/** Read the current energy level and setter */
+export function useEnergyLevel() {
+    const engine = useEngine();
+    const state = useEnergyStoreState();
+    const setLevel = useCallback((level) => {
+        engine.setLevel(level);
+    }, [engine]);
+    return [state.level, setLevel];
+}
+/** @deprecated Use useEnergyState instead. */
+export function useFullEnergyState() {
+    return useEnergyStoreState();
+}
+/** Returns a function that cycles to the next energy level */
+export function useEnergyLevelCycler() {
+    const engine = useEngine();
+    return useCallback(() => {
+        engine.cycleLevel();
+    }, [engine]);
+}
+/** Resolve a strategy against current energy level */
+export function useStrategy(strategy) {
+    const state = useEnergyStoreState();
+    return useMemo(() => strategy.resolve(state.level), [strategy, state.level]);
+}
+/** Returns true if current energy level meets or exceeds the given minimum */
+export function useEnergyGate(minLevel) {
+    const state = useEnergyStoreState();
+    return state.level >= minLevel;
+}
+/** Headless energy indicator - bring your own UI */
+export function EnergyIndicator({ children }) {
+    const [level, setLevel] = useEnergyLevel();
+    const state = useEnergyStoreState();
+    const cycle = useEnergyLevelCycler();
+    const definition = useMemo(() => getEnergyLevel(level), [level]);
+    const levels = useMemo(() => getEnergyLevels(), []);
+    return children({
+        level,
+        label: definition.label,
+        description: definition.description,
+        cognitiveProfile: definition.cognitiveProfile,
+        state,
+        definition,
+        levels,
+        cycle,
+        setLevel,
+    });
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

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

package/dist/strategies.d.ts

@@ -0,0 +1,36 @@
+import type { AdaptationStrategy, TaskComplexity } from './types.js';
+export interface UIVisibilityConfig {
+    readonly sidebar: boolean;
+    readonly tabBar: boolean;
+    readonly statusBar: boolean;
+    readonly toolbar: boolean;
+    readonly chromeOpacity: number;
+    readonly chromeOpacityHover: number;
+    readonly contentMaxWidth: string;
+    readonly contentFontScale: number;
+    readonly readOnlyCursor: boolean;
+}
+export declare const uiVisibilityStrategy: AdaptationStrategy<UIVisibilityConfig>;
+export interface NotificationConfig {
+    /** Allow visual notifications (badges, toasts) */
+    readonly allowVisual: boolean;
+    /** Allow audio notifications */
+    readonly allowSound: boolean;
+    /** Allow haptic feedback */
+    readonly allowVibration: boolean;
+    /** Minimum ms between batched notifications (0 = immediate) */
+    readonly batchInterval: number;
+    /** Minimum priority to show */
+    readonly priorityThreshold: 'all' | 'high' | 'critical' | 'none';
+}
+export declare const notificationStrategy: AdaptationStrategy<NotificationConfig>;
+export interface TaskComplexityConfig {
+    /** Maximum task complexity to surface */
+    readonly maxComplexity: TaskComplexity;
+    /** Whether to proactively suggest breaks */
+    readonly suggestBreaks: boolean;
+    /** Minutes between break suggestions (when enabled) */
+    readonly breakIntervalMinutes: number;
+}
+export declare const taskComplexityStrategy: AdaptationStrategy<TaskComplexityConfig>;
+//# sourceMappingURL=strategies.d.ts.map

package/dist/strategies.d.ts.map

@@ -0,0 +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,CAYvE,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;AA8BD,eAAO,MAAM,sBAAsB,EAAE,kBAAkB,CAAC,oBAAoB,CAY3E,CAAA"}

package/dist/strategies.js

@@ -0,0 +1,175 @@
+import { getEnergyLevel } from './levels.js';
+function freezeObject(value) {
+    return Object.freeze(value);
+}
+const UI_CONFIGS = freezeObject({
+    100: freezeObject({
+        sidebar: true,
+        tabBar: true,
+        statusBar: true,
+        toolbar: true,
+        chromeOpacity: 1,
+        chromeOpacityHover: 1,
+        contentMaxWidth: 'none',
+        contentFontScale: 1,
+        readOnlyCursor: false,
+    }),
+    75: freezeObject({
+        sidebar: true,
+        tabBar: true,
+        statusBar: true,
+        toolbar: true,
+        chromeOpacity: 0.7,
+        chromeOpacityHover: 1,
+        contentMaxWidth: 'none',
+        contentFontScale: 1,
+        readOnlyCursor: false,
+    }),
+    50: freezeObject({
+        sidebar: true,
+        tabBar: true,
+        statusBar: true,
+        toolbar: true,
+        chromeOpacity: 0.4,
+        chromeOpacityHover: 1,
+        contentMaxWidth: '90ch',
+        contentFontScale: 1,
+        readOnlyCursor: false,
+    }),
+    25: freezeObject({
+        sidebar: false,
+        tabBar: false,
+        statusBar: false,
+        toolbar: true,
+        chromeOpacity: 0.1,
+        chromeOpacityHover: 1,
+        contentMaxWidth: '80ch',
+        contentFontScale: 1.05,
+        readOnlyCursor: false,
+    }),
+    0: freezeObject({
+        sidebar: false,
+        tabBar: false,
+        statusBar: false,
+        toolbar: false,
+        chromeOpacity: 0.05,
+        chromeOpacityHover: 0.8,
+        contentMaxWidth: '75ch',
+        contentFontScale: 1.1,
+        readOnlyCursor: true,
+    }),
+});
+export const uiVisibilityStrategy = {
+    name: 'ui-visibility',
+    describe(level) {
+        const def = getEnergyLevel(level);
+        const config = UI_CONFIGS[def.value];
+        const hidden = [
+            !config.sidebar && 'sidebar',
+            !config.tabBar && 'tabs',
+            !config.statusBar && 'status bar',
+            !config.toolbar && 'toolbar',
+        ].filter(Boolean);
+        if (hidden.length === 0) {
+            return `${def.label}: All UI elements visible${config.chromeOpacity < 1 ? `, chrome at ${Math.round(config.chromeOpacity * 100)}% opacity` : ''}`;
+        }
+        return `${def.label}: ${hidden.join(', ')} hidden, chrome at ${Math.round(config.chromeOpacity * 100)}% opacity`;
+    },
+    resolve(level) {
+        return UI_CONFIGS[getEnergyLevel(level).value];
+    },
+};
+const NOTIFICATION_CONFIGS = freezeObject({
+    100: freezeObject({
+        allowVisual: true,
+        allowSound: true,
+        allowVibration: true,
+        batchInterval: 0,
+        priorityThreshold: 'all',
+    }),
+    75: freezeObject({
+        allowVisual: true,
+        allowSound: true,
+        allowVibration: false,
+        batchInterval: 0,
+        priorityThreshold: 'all',
+    }),
+    50: freezeObject({
+        allowVisual: true,
+        allowSound: false,
+        allowVibration: false,
+        batchInterval: 5 * 60 * 1000, // 5 minutes
+        priorityThreshold: 'high',
+    }),
+    25: freezeObject({
+        allowVisual: true,
+        allowSound: false,
+        allowVibration: false,
+        batchInterval: 15 * 60 * 1000, // 15 minutes
+        priorityThreshold: 'critical',
+    }),
+    0: freezeObject({
+        allowVisual: false,
+        allowSound: false,
+        allowVibration: false,
+        batchInterval: 0,
+        priorityThreshold: 'none',
+    }),
+});
+export const notificationStrategy = {
+    name: 'notifications',
+    describe(level) {
+        const def = getEnergyLevel(level);
+        const config = NOTIFICATION_CONFIGS[def.value];
+        if (config.priorityThreshold === 'none')
+            return 'Rest: All notifications silenced';
+        if (config.priorityThreshold === 'all')
+            return `${def.label}: All notifications enabled`;
+        return `${def.label}: Only ${config.priorityThreshold} priority, batched every ${config.batchInterval / 60_000}min`;
+    },
+    resolve(level) {
+        return NOTIFICATION_CONFIGS[getEnergyLevel(level).value];
+    },
+};
+const TASK_CONFIGS = freezeObject({
+    100: freezeObject({
+        maxComplexity: 'complex',
+        suggestBreaks: false,
+        breakIntervalMinutes: 0,
+    }),
+    75: freezeObject({
+        maxComplexity: 'moderate',
+        suggestBreaks: false,
+        breakIntervalMinutes: 0,
+    }),
+    50: freezeObject({
+        maxComplexity: 'routine',
+        suggestBreaks: true,
+        breakIntervalMinutes: 45,
+    }),
+    25: freezeObject({
+        maxComplexity: 'simple',
+        suggestBreaks: true,
+        breakIntervalMinutes: 25,
+    }),
+    0: freezeObject({
+        maxComplexity: 'consumption',
+        suggestBreaks: true,
+        breakIntervalMinutes: 15,
+    }),
+});
+export const taskComplexityStrategy = {
+    name: 'task-complexity',
+    describe(level) {
+        const def = getEnergyLevel(level);
+        const config = TASK_CONFIGS[def.value];
+        const parts = [`${def.label}: Max complexity: ${config.maxComplexity}`];
+        if (config.suggestBreaks)
+            parts.push(`breaks every ${config.breakIntervalMinutes}min`);
+        return parts.join(', ');
+    },
+    resolve(level) {
+        return TASK_CONFIGS[getEnergyLevel(level).value];
+    },
+};
+//# sourceMappingURL=strategies.js.map

package/dist/strategies.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+/** Discrete cognitive capacity values */
+export type EnergyLevel = 0 | 25 | 50 | 75 | 100;
+/** How the energy level was set */
+export type EnergySource = 'manual' | 'scheduled' | 'inferred';
+/** Valid energy level values for runtime validation */
+export declare const ENERGY_LEVEL_VALUES: ReadonlySet<number>;
+/** Valid energy source values for runtime validation */
+export declare const ENERGY_SOURCE_VALUES: ReadonlySet<EnergySource>;
+/** A point-in-time snapshot of cognitive capacity */
+export interface EnergyState {
+    /** Current cognitive capacity */
+    readonly level: EnergyLevel;
+    /** When this state was set (epoch ms) */
+    readonly timestamp: number;
+    /** How this state was determined */
+    readonly source: EnergySource;
+}
+/** Time source contract for deterministic environments (tests, simulations) */
+export interface EnergyClock {
+    now(): number;
+}
+export type DecisionCapacity = 'high' | 'moderate' | 'low' | 'minimal' | 'none';
+export type FocusDuration = 'extended' | 'moderate' | 'short' | 'minimal' | 'none';
+export type TaskComplexity = 'complex' | 'moderate' | 'routine' | 'simple' | 'consumption';
+export type InterruptionTolerance = 'high' | 'moderate' | 'low' | 'minimal' | 'none';
+/** What the brain can handle at a given energy level */
+export interface CognitiveProfile {
+    readonly decisionCapacity: DecisionCapacity;
+    readonly focusDuration: FocusDuration;
+    readonly taskComplexity: TaskComplexity;
+    readonly interruptionTolerance: InterruptionTolerance;
+}
+/** Complete metadata for a single energy level */
+export interface EnergyLevelDefinition {
+    readonly value: EnergyLevel;
+    readonly key: string;
+    readonly label: string;
+    readonly description: string;
+    readonly cognitiveProfile: CognitiveProfile;
+}
+/**
+ * Maps energy levels to application behavior.
+ * Pure function - given a level, produce a configuration.
+ */
+export interface AdaptationStrategy<TConfig> {
+    /** Unique name for this strategy */
+    name: string;
+    /** Human-readable description of what this strategy does at a given level */
+    describe(level: EnergyLevel): string;
+    /** Compute the configuration for a given energy level */
+    resolve(level: EnergyLevel): TConfig;
+}
+/** Storage contract - implement per platform */
+export interface EnergyPersistence {
+    load(): Promise<EnergyState | null>;
+    save(state: EnergyState): Promise<void>;
+    /**
+     * Optional observer for externally persisted state updates (cross-tab, worker, etc.)
+     */
+    observe?(onState: (state: EnergyState) => void): () => void;
+}
+/** Callback for energy state changes */
+export type EnergyChangeListener = (state: EnergyState, prev: EnergyState) => void;
+/**
+ * Computed, app-agnostic metrics from an energy state snapshot.
+ */
+export interface EnergyMetrics {
+    /** Milliseconds since this state was set */
+    readonly stateAgeMs: number;
+    /** Rounded minutes since this state was set */
+    readonly stateAgeMinutes: number;
+    /** Suggested focused-work window length */
+    readonly expectedProductivityWindowMinutes: number;
+    /** Suggested break cadence for the current level */
+    readonly suggestedBreakIntervalMinutes: number;
+    /** Recommended task complexity based on cognitive profile */
+    readonly recommendedTaskComplexity: TaskComplexity;
+    /**
+     * Heuristic signal for maintainability of this state.
+     * True only for mid-range levels (25/50/75): peak (100) is a burst state
+     * that depletes rather than holds, and rest (0) is recovery, not a working
+     * state to maintain. Both extremes report false.
+     */
+    readonly sustainable: boolean;
+    /** Optional guidance for recovery horizon */
+    readonly recoveryHintMinutes?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,10 @@
+// ── Energy Levels ──
+/** Valid energy level values for runtime validation */
+export const ENERGY_LEVEL_VALUES = new Set([0, 25, 50, 75, 100]);
+/** Valid energy source values for runtime validation */
+export const ENERGY_SOURCE_VALUES = new Set([
+    'manual',
+    'scheduled',
+    'inferred',
+]);
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,sBAAsB;AAQtB,uDAAuD;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAA;AACrF,wDAAwD;AACxD,MAAM,CAAC,MAAM,oBAAoB,GAA8B,IAAI,GAAG,CAAC;IACrE,QAAQ;IACR,WAAW;IACX,UAAU;CACX,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@kumbatio/energy-system",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Framework-agnostic TypeScript library for energy-aware application behavior.",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src/energy.css",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./src/energy.css"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./dom": {
+      "types": "./dist/dom.d.ts",
+      "import": "./dist/dom.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./persistence": {
+      "types": "./dist/persistence.d.ts",
+      "import": "./dist/persistence.js"
+    },
+    "./css": "./src/energy.css",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit -p tsconfig.json",
+    "test": "pnpm run build && node --test --import tsx",
+    "pack:dry-run": "npm pack --dry-run",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "lint:fix-unsafe": "oxlint --import-plugin   --type-aware --type-check --vitest-plugin --fix --fix-suggestions --fix-dangerously src/",
+    "check:fix-suggestions": "oxlint --import-plugin   --type-aware --type-check --vitest-plugin --fix --fix-suggestions . && oxfmt --write ."
+  }
+}