@kumbatio/energy-system 0.3.0 → 0.4.0

package/dist/gate.d.ts

@@ -0,0 +1,84 @@
+import type { EnergyEngine, EnergyEngineOptions } from './engine.js';
+import type { NotificationConfig } from './strategies.js';
+import type { AdaptationStrategy, EnergyLevel } from './types.js';
+/** Priority of a single notification intent */
+export type NotificationPriority = 'normal' | 'high' | 'critical';
+/** Validate that an unknown value is a valid NotificationPriority */
+export declare function isNotificationPriority(value: unknown): value is NotificationPriority;
+/** A single notification intent held or delivered by the gate */
+export interface EnergyNotification {
+    readonly priority: NotificationPriority;
+    readonly payload: unknown;
+    /** When the intent was published (epoch ms, gate clock) */
+    readonly createdAt: number;
+}
+/** Why a delivery is happening */
+export type NotificationDeliveryReason = 'immediate' | 'batch' | 'released';
+/** Output channels permitted by the config active at delivery time */
+export interface NotificationChannels {
+    readonly visual: boolean;
+    readonly sound: boolean;
+    readonly vibration: boolean;
+}
+/** One call to `onDeliver`: one or more notifications plus delivery context */
+export interface NotificationDelivery {
+    readonly notifications: readonly EnergyNotification[];
+    readonly reason: NotificationDeliveryReason;
+    readonly channels: NotificationChannels;
+    readonly level: EnergyLevel;
+}
+/** What happened to a published notification */
+export type PublishOutcome = 'delivered' | 'batched' | 'deferred';
+/**
+ * Pure gating decision: given the active config, an intent priority, and the
+ * suppression flag, decide the outcome. Extracted so apps can unit-test their
+ * notification policy without constructing a gate.
+ */
+export declare function resolveNotificationOutcome(config: NotificationConfig, priority: NotificationPriority, suppressed: boolean): PublishOutcome;
+/** Timer contract so tests can drive batch windows deterministically */
+export interface GateScheduler {
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface NotificationGateOptions {
+    /** Delivery sink. Called with everything the gate decides to surface. */
+    onDeliver(delivery: NotificationDelivery): void;
+    /** Strategy resolving level -> NotificationConfig. Default: `notificationStrategy`. */
+    strategy?: AdaptationStrategy<NotificationConfig>;
+    /** Deterministic time source for tests/simulations */
+    clock?: EnergyEngineOptions['clock'];
+    /** Deterministic timer source for tests/simulations */
+    scheduler?: GateScheduler;
+}
+export interface NotificationGate {
+    /** Publish a notification intent. Returns what the gate did with it. */
+    publish(input: {
+        priority?: NotificationPriority;
+        payload?: unknown;
+    }): PublishOutcome;
+    /**
+     * Hard-suppress delivery (e.g. during a focus session). While suppressed,
+     * every publish defers; lifting suppression releases the deferred queue.
+     */
+    setSuppressed(suppressed: boolean): void;
+    isSuppressed(): boolean;
+    /** Counts of undelivered notifications currently held by the gate */
+    pendingCount(): {
+        batched: number;
+        deferred: number;
+    };
+    /** Deliver the open batch now and release any deferred items that qualify */
+    flush(): void;
+    /**
+     * Release resources. Pending notifications are delivered as a final
+     * 'released' delivery first — a disposed gate never swallows intents.
+     */
+    dispose(): void;
+}
+/**
+ * Create a notification gate bound to an engine. The gate re-resolves its
+ * config on every energy change and releases deferred notifications the
+ * moment the new level's config (or lifted suppression) admits them.
+ */
+export declare function createNotificationGate(engine: EnergyEngine, options: NotificationGateOptions): NotificationGate;
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAsBjE,+CAA+C;AAC/C,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAA;AAQjE,qEAAqE;AACrE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,oBAAoB,CAEpF;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,kCAAkC;AAClC,MAAM,MAAM,0BAA0B,GAAG,WAAW,GAAG,OAAO,GAAG,UAAU,CAAA;AAE3E,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACrD,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAA;IAC3C,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAA;IACvC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;CAC5B;AAED,gDAAgD;AAChD,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAA;AAEjE;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,oBAAoB,EAC9B,UAAU,EAAE,OAAO,GAClB,cAAc,CAiBhB;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IACrD,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;CACpC;AAWD,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAAA;IAC/C,uFAAuF;IACvF,QAAQ,CAAC,EAAE,kBAAkB,CAAC,kBAAkB,CAAC,CAAA;IACjD,sDAAsD;IACtD,KAAK,CAAC,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAA;IACpC,uDAAuD;IACvD,SAAS,CAAC,EAAE,aAAa,CAAA;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,OAAO,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,oBAAoB,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,cAAc,CAAA;IACtF;;;OAGG;IACH,aAAa,CAAC,UAAU,EAAE,OAAO,GAAG,IAAI,CAAA;IACxC,YAAY,IAAI,OAAO,CAAA;IACvB,qEAAqE;IACrE,YAAY,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;IACrD,6EAA6E;IAC7E,KAAK,IAAI,IAAI,CAAA;IACb;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAQD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,uBAAuB,GAC/B,gBAAgB,CAkLlB"}

package/dist/gate.js

@@ -0,0 +1,224 @@
+import { notificationStrategy } from './strategies.js';
+/**
+ * Notification gate — the runtime that ENFORCES `NotificationConfig` instead
+ * of leaving it as guidance. Apps publish notification intents through the
+ * gate; the gate resolves the current energy level's config and decides
+ * whether each intent is delivered now, batched, or deferred.
+ *
+ * Design rule inherited from field evidence (GingerMail's scheduler destroyed
+ * reminders that came due while suppressed): the gate NEVER silently drops a
+ * notification. Anything not deliverable now is deferred and released when
+ * energy rises, suppression lifts, or the gate is disposed.
+ */
+function logGateError(message, err) {
+    console.error(`[energy-system] ${message}`, err);
+}
+function freezeObject(value) {
+    return Object.freeze(value);
+}
+const NOTIFICATION_PRIORITIES = new Set([
+    'normal',
+    'high',
+    'critical',
+]);
+/** Validate that an unknown value is a valid NotificationPriority */
+export function isNotificationPriority(value) {
+    return typeof value === 'string' && NOTIFICATION_PRIORITIES.has(value);
+}
+/**
+ * Pure gating decision: given the active config, an intent priority, and the
+ * suppression flag, decide the outcome. Extracted so apps can unit-test their
+ * notification policy without constructing a gate.
+ */
+export function resolveNotificationOutcome(config, priority, suppressed) {
+    if (suppressed)
+        return 'deferred';
+    switch (config.priorityThreshold) {
+        case 'none':
+            return 'deferred';
+        case 'critical':
+            if (priority !== 'critical')
+                return 'deferred';
+            break;
+        case 'high':
+            if (priority === 'normal')
+                return 'deferred';
+            break;
+        case 'all':
+            break;
+    }
+    return config.batchInterval > 0 ? 'batched' : 'delivered';
+}
+const defaultScheduler = {
+    setTimeout(callback, ms) {
+        return setTimeout(callback, ms);
+    },
+    clearTimeout(handle) {
+        clearTimeout(handle);
+    },
+};
+function resolveNow(clock) {
+    if (typeof clock === 'function')
+        return clock;
+    if (clock?.now)
+        return () => clock.now();
+    return () => Date.now();
+}
+/**
+ * Create a notification gate bound to an engine. The gate re-resolves its
+ * config on every energy change and releases deferred notifications the
+ * moment the new level's config (or lifted suppression) admits them.
+ */
+export function createNotificationGate(engine, options) {
+    const { onDeliver, strategy = notificationStrategy, clock, scheduler = defaultScheduler, } = options;
+    if (typeof onDeliver !== 'function') {
+        throw new TypeError('createNotificationGate requires an onDeliver callback');
+    }
+    const now = resolveNow(clock);
+    let disposed = false;
+    let suppressed = false;
+    let batch = [];
+    let deferred = [];
+    let batchTimer;
+    function currentConfig() {
+        return strategy.resolve(engine.getState().level);
+    }
+    function channelsFrom(config) {
+        return freezeObject({
+            visual: config.allowVisual,
+            sound: config.allowSound,
+            vibration: config.allowVibration,
+        });
+    }
+    function deliver(notifications, reason) {
+        if (notifications.length === 0)
+            return;
+        const config = currentConfig();
+        const delivery = freezeObject({
+            notifications: Object.freeze([...notifications]),
+            reason,
+            channels: channelsFrom(config),
+            level: engine.getState().level,
+        });
+        try {
+            onDeliver(delivery);
+        }
+        catch (err) {
+            logGateError('onDeliver callback threw', err);
+        }
+    }
+    function clearBatchTimer() {
+        if (batchTimer !== undefined) {
+            scheduler.clearTimeout(batchTimer);
+            batchTimer = undefined;
+        }
+    }
+    function deliverBatch() {
+        clearBatchTimer();
+        if (batch.length === 0)
+            return;
+        const toDeliver = batch;
+        batch = [];
+        deliver(toDeliver, 'batch');
+    }
+    function scheduleBatch(intervalMs) {
+        if (batchTimer !== undefined)
+            return;
+        batchTimer = scheduler.setTimeout(() => {
+            batchTimer = undefined;
+            deliverBatch();
+        }, intervalMs);
+    }
+    /**
+     * Re-evaluate the deferred queue against the active config. Anything no
+     * longer deferred is released immediately (not re-batched: these intents
+     * already waited once, adding a second batch delay would compound it).
+     */
+    function releaseEligibleDeferred() {
+        if (disposed || deferred.length === 0)
+            return;
+        const config = currentConfig();
+        const stillDeferred = [];
+        const released = [];
+        for (const notification of deferred) {
+            if (resolveNotificationOutcome(config, notification.priority, suppressed) === 'deferred') {
+                stillDeferred.push(notification);
+            }
+            else {
+                released.push(notification);
+            }
+        }
+        deferred = stillDeferred;
+        deliver(released, 'released');
+    }
+    const unsubscribe = engine.subscribe(() => {
+        releaseEligibleDeferred();
+    });
+    return {
+        publish(input) {
+            if (disposed) {
+                throw new Error('Cannot publish through a disposed notification gate');
+            }
+            const priority = input.priority ?? 'normal';
+            if (!isNotificationPriority(priority)) {
+                throw new Error(`Invalid notification priority: ${String(priority)}`);
+            }
+            const notification = freezeObject({
+                priority,
+                payload: input.payload,
+                createdAt: now(),
+            });
+            const config = currentConfig();
+            const outcome = resolveNotificationOutcome(config, priority, suppressed);
+            switch (outcome) {
+                case 'delivered':
+                    deliver([notification], 'immediate');
+                    break;
+                case 'batched':
+                    batch.push(notification);
+                    scheduleBatch(config.batchInterval);
+                    break;
+                case 'deferred':
+                    deferred.push(notification);
+                    break;
+            }
+            return outcome;
+        },
+        setSuppressed(next) {
+            if (disposed)
+                return;
+            if (suppressed === next)
+                return;
+            suppressed = next;
+            if (!suppressed) {
+                releaseEligibleDeferred();
+            }
+        },
+        isSuppressed() {
+            return suppressed;
+        },
+        pendingCount() {
+            return { batched: batch.length, deferred: deferred.length };
+        },
+        flush() {
+            if (disposed)
+                return;
+            deliverBatch();
+            releaseEligibleDeferred();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            // Surface everything still held before going inert: an intent that
+            // entered the gate must always exit through onDeliver.
+            clearBatchTimer();
+            const pending = [...batch, ...deferred];
+            batch = [];
+            deferred = [];
+            deliver(pending, 'released');
+            disposed = true;
+            unsubscribe();
+        },
+    };
+}
+//# sourceMappingURL=gate.js.map

package/dist/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAItD;;;;;;;;;;GAUG;AAEH,SAAS,YAAY,CAAC,OAAe,EAAE,GAAY;IACjD,OAAO,CAAC,KAAK,CAAC,mBAAmB,OAAO,EAAE,EAAE,GAAG,CAAC,CAAA;AAClD,CAAC;AAED,SAAS,YAAY,CAAmB,KAAQ;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC7B,CAAC;AAKD,MAAM,uBAAuB,GAAsC,IAAI,GAAG,CAAC;IACzE,QAAQ;IACR,MAAM;IACN,UAAU;CACX,CAAC,CAAA;AAEF,qEAAqE;AACrE,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAA6B,CAAC,CAAA;AAChG,CAAC;AA+BD;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAA0B,EAC1B,QAA8B,EAC9B,UAAmB;IAEnB,IAAI,UAAU;QAAE,OAAO,UAAU,CAAA;IAEjC,QAAQ,MAAM,CAAC,iBAAiB,EAAE,CAAC;QACjC,KAAK,MAAM;YACT,OAAO,UAAU,CAAA;QACnB,KAAK,UAAU;YACb,IAAI,QAAQ,KAAK,UAAU;gBAAE,OAAO,UAAU,CAAA;YAC9C,MAAK;QACP,KAAK,MAAM;YACT,IAAI,QAAQ,KAAK,QAAQ;gBAAE,OAAO,UAAU,CAAA;YAC5C,MAAK;QACP,KAAK,KAAK;YACR,MAAK;IACT,CAAC;IAED,OAAO,MAAM,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAA;AAC3D,CAAC;AAQD,MAAM,gBAAgB,GAAkB;IACtC,UAAU,CAAC,QAAQ,EAAE,EAAE;QACrB,OAAO,UAAU,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;IACjC,CAAC;IACD,YAAY,CAAC,MAAM;QACjB,YAAY,CAAC,MAA4C,CAAC,CAAA;IAC5D,CAAC;CACF,CAAA;AAiCD,SAAS,UAAU,CAAC,KAAoC;IACtD,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,KAAK,CAAA;IAC7C,IAAI,KAAK,EAAE,GAAG;QAAE,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;IACxC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAA;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAoB,EACpB,OAAgC;IAEhC,MAAM,EACJ,SAAS,EACT,QAAQ,GAAG,oBAAoB,EAC/B,KAAK,EACL,SAAS,GAAG,gBAAgB,GAC7B,GAAG,OAAO,CAAA;IAEX,IAAI,OAAO,SAAS,KAAK,UAAU,EAAE,CAAC;QACpC,MAAM,IAAI,SAAS,CAAC,uDAAuD,CAAC,CAAA;IAC9E,CAAC;IAED,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;IAE7B,IAAI,QAAQ,GAAG,KAAK,CAAA;IACpB,IAAI,UAAU,GAAG,KAAK,CAAA;IACtB,IAAI,KAAK,GAAyB,EAAE,CAAA;IACpC,IAAI,QAAQ,GAAyB,EAAE,CAAA;IACvC,IAAI,UAAmB,CAAA;IAEvB,SAAS,aAAa;QACpB,OAAO,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAA;IAClD,CAAC;IAED,SAAS,YAAY,CAAC,MAA0B;QAC9C,OAAO,YAAY,CAAC;YAClB,MAAM,EAAE,MAAM,CAAC,WAAW;YAC1B,KAAK,EAAE,MAAM,CAAC,UAAU;YACxB,SAAS,EAAE,MAAM,CAAC,cAAc;SACjC,CAAC,CAAA;IACJ,CAAC;IAED,SAAS,OAAO,CACd,aAA4C,EAC5C,MAAkC;QAElC,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAEtC,MAAM,MAAM,GAAG,aAAa,EAAE,CAAA;QAC9B,MAAM,QAAQ,GAAyB,YAAY,CAAC;YAClD,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC;YAChD,MAAM;YACN,QAAQ,EAAE,YAAY,CAAC,MAAM,CAAC;YAC9B,KAAK,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK;SAC/B,CAAC,CAAA;QAEF,IAAI,CAAC;YACH,SAAS,CAAC,QAAQ,CAAC,CAAA;QACrB,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,YAAY,CAAC,0BAA0B,EAAE,GAAG,CAAC,CAAA;QAC/C,CAAC;IACH,CAAC;IAED,SAAS,eAAe;QACtB,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,SAAS,CAAC,YAAY,CAAC,UAAU,CAAC,CAAA;YAClC,UAAU,GAAG,SAAS,CAAA;QACxB,CAAC;IACH,CAAC;IAED,SAAS,YAAY;QACnB,eAAe,EAAE,CAAA;QACjB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAC9B,MAAM,SAAS,GAAG,KAAK,CAAA;QACvB,KAAK,GAAG,EAAE,CAAA;QACV,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;IAC7B,CAAC;IAED,SAAS,aAAa,CAAC,UAAkB;QACvC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAM;QACpC,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC,GAAG,EAAE;YACrC,UAAU,GAAG,SAAS,CAAA;YACtB,YAAY,EAAE,CAAA;QAChB,CAAC,EAAE,UAAU,CAAC,CAAA;IAChB,CAAC;IAED;;;;OAIG;IACH,SAAS,uBAAuB;QAC9B,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAE7C,MAAM,MAAM,GAAG,aAAa,EAAE,CAAA;QAC9B,MAAM,aAAa,GAAyB,EAAE,CAAA;QAC9C,MAAM,QAAQ,GAAyB,EAAE,CAAA;QAEzC,KAAK,MAAM,YAAY,IAAI,QAAQ,EAAE,CAAC;YACpC,IAAI,0BAA0B,CAAC,MAAM,EAAE,YAAY,CAAC,QAAQ,EAAE,UAAU,CAAC,KAAK,UAAU,EAAE,CAAC;gBACzF,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;YAClC,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;YAC7B,CAAC;QACH,CAAC;QAED,QAAQ,GAAG,aAAa,CAAA;QACxB,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;IAC/B,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE;QACxC,uBAAuB,EAAE,CAAA;IAC3B,CAAC,CAAC,CAAA;IAEF,OAAO;QACL,OAAO,CAAC,KAAK;YACX,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAA;YACxE,CAAC;YAED,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,QAAQ,CAAA;YAC3C,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACtC,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;YACvE,CAAC;YAED,MAAM,YAAY,GAAuB,YAAY,CAAC;gBACpD,QAAQ;gBACR,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,SAAS,EAAE,GAAG,EAAE;aACjB,CAAC,CAAA;YAEF,MAAM,MAAM,GAAG,aAAa,EAAE,CAAA;YAC9B,MAAM,OAAO,GAAG,0BAA0B,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAA;YAExE,QAAQ,OAAO,EAAE,CAAC;gBAChB,KAAK,WAAW;oBACd,OAAO,CAAC,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,CAAA;oBACpC,MAAK;gBACP,KAAK,SAAS;oBACZ,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;oBACxB,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,CAAA;oBACnC,MAAK;gBACP,KAAK,UAAU;oBACb,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAA;oBAC3B,MAAK;YACT,CAAC;YAED,OAAO,OAAO,CAAA;QAChB,CAAC;QAED,aAAa,CAAC,IAAI;YAChB,IAAI,QAAQ;gBAAE,OAAM;YACpB,IAAI,UAAU,KAAK,IAAI;gBAAE,OAAM;YAC/B,UAAU,GAAG,IAAI,CAAA;YACjB,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,uBAAuB,EAAE,CAAA;YAC3B,CAAC;QACH,CAAC;QAED,YAAY;YACV,OAAO,UAAU,CAAA;QACnB,CAAC;QAED,YAAY;YACV,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAA;QAC7D,CAAC;QAED,KAAK;YACH,IAAI,QAAQ;gBAAE,OAAM;YACpB,YAAY,EAAE,CAAA;YACd,uBAAuB,EAAE,CAAA;QAC3B,CAAC;QAED,OAAO;YACL,IAAI,QAAQ;gBAAE,OAAM;YAEpB,mEAAmE;YACnE,uDAAuD;YACvD,eAAe,EAAE,CAAA;YACjB,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,EAAE,GAAG,QAAQ,CAAC,CAAA;YACvC,KAAK,GAAG,EAAE,CAAA;YACV,QAAQ,GAAG,EAAE,CAAA;YACb,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;YAE5B,QAAQ,GAAG,IAAI,CAAA;YACf,WAAW,EAAE,CAAA;QACf,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,11 +1,19 @@
-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 type { AdaptationStrategy, CognitiveProfile, DecisionCapacity, EnergyClock, EnergyChangeListener, EnergyLevel, EnergyLevelDefinition, EnergyMetrics, EnergyPersistence, EnergyPresence, EnergyPresenceMap, EnergySource, EnergyState, FocusDuration, InterruptionTolerance, TaskComplexity, } from './types.js';
+export { ENERGY_LEVEL_VALUES, ENERGY_PRESENCE_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';
+export type { InteractionForgivenessConfig, NotificationConfig, TaskComplexityConfig, UIVisibilityConfig, } from './strategies.js';
+export { interactionForgivenessStrategy, notificationStrategy, taskComplexityStrategy, uiVisibilityStrategy, } from './strategies.js';
+export type { EnergyPresenceSpec } from './presence.js';
+export { createPresenceStrategy, defineEnergyPresence, isEnergyPresence, isPresenceVisible, presenceAtOrAbove, presenceAtOrBelow, resolveEnergyPresence, } from './presence.js';
+export type { FocusSession, FocusSessionController, FocusSessionControllerOptions, FocusSessionEvent, FocusSessionListener, FocusSuppressible, StartFocusSessionOptions, } from './session.js';
+export { createFocusSessionController, isSessionExpired, sessionRemainingMs } from './session.js';
+export type { DeferralConfig, DeferralPreset, DeferralPresetOptions } from './defer.js';
+export { DEFERRAL_PRESET_IDS, createDeferralPresets, deferralStrategy, resolveDeferral, } from './defer.js';
+export type { EnergyNotification, GateScheduler, NotificationChannels, NotificationDelivery, NotificationDeliveryReason, NotificationGate, NotificationGateOptions, NotificationPriority, PublishOutcome, } from './gate.js';
+export { createNotificationGate, isNotificationPriority, resolveNotificationOutcome, } from './gate.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,qBAAqB,EACrB,cAAc,GACf,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAG9F,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,EACV,4BAA4B,EAC5B,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,8BAA8B,EAC9B,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,iBAAiB,CAAA;AAGxB,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AAGtB,YAAY,EACV,YAAY,EACZ,sBAAsB,EACtB,6BAA6B,EAC7B,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,4BAA4B,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAGjG,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AACvF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAA;AAGnB,YAAY,EACV,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,cAAc,GACf,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -1,9 +1,13 @@
-export { ENERGY_LEVEL_VALUES, ENERGY_SOURCE_VALUES } from './types.js';
+export { ENERGY_LEVEL_VALUES, ENERGY_PRESENCE_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';
+export { interactionForgivenessStrategy, notificationStrategy, taskComplexityStrategy, uiVisibilityStrategy, } from './strategies.js';
+export { createPresenceStrategy, defineEnergyPresence, isEnergyPresence, isPresenceVisible, presenceAtOrAbove, presenceAtOrBelow, resolveEnergyPresence, } from './presence.js';
+export { createFocusSessionController, isSessionExpired, sessionRemainingMs } from './session.js';
+export { DEFERRAL_PRESET_IDS, createDeferralPresets, deferralStrategy, resolveDeferral, } from './defer.js';
+export { createNotificationGate, isNotificationPriority, resolveNotificationOutcome, } from './gate.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAE9F,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;AAShD,OAAO,EACL,8BAA8B,EAC9B,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,iBAAiB,CAAA;AAIxB,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,eAAe,CAAA;AAYtB,OAAO,EAAE,4BAA4B,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAIjG,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAA;AAcnB,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,WAAW,CAAA"}

package/dist/presence.d.ts

@@ -0,0 +1,56 @@
+import type { AdaptationStrategy, EnergyLevel, EnergyPresence, EnergyPresenceMap } from './types.js';
+/** Validate that an unknown value is a valid EnergyPresence */
+export declare function isEnergyPresence(value: unknown): value is EnergyPresence;
+/**
+ * Per-level presence spec. Unlisted levels fall back to `default`
+ * ('visible' when omitted).
+ */
+export type EnergyPresenceSpec = Partial<Record<EnergyLevel, EnergyPresence>> & {
+    default?: EnergyPresence;
+};
+/**
+ * Build a complete, frozen presence map from a partial spec.
+ *
+ * ```ts
+ * // Hide the AI chat at 50 and below, keep it muted at 75:
+ * const aiChatPresence = defineEnergyPresence({
+ *   default: 'visible',
+ *   75: 'muted',
+ *   50: 'hidden',
+ *   25: 'hidden',
+ *   0: 'hidden',
+ * })
+ * ```
+ */
+export declare function defineEnergyPresence(spec?: EnergyPresenceSpec): EnergyPresenceMap;
+/**
+ * Presence map for elements that need at least `min` energy.
+ * Below `min` the element is `below` ('hidden' by default).
+ *
+ * ```ts
+ * const composerToolbar = presenceAtOrAbove(50)          // hidden at 25 and 0
+ * const aiSidebar = presenceAtOrAbove(75, 'muted')       // muted below 75
+ * ```
+ */
+export declare function presenceAtOrAbove(min: EnergyLevel, below?: EnergyPresence): EnergyPresenceMap;
+/**
+ * Presence map for elements that only belong at low energy — recovery hints,
+ * "one thing at a time" affordances. Above `max` the element is `above`
+ * ('hidden' by default).
+ */
+export declare function presenceAtOrBelow(max: EnergyLevel, above?: EnergyPresence): EnergyPresenceMap;
+/** Resolve the presence of an element for a given energy level */
+export declare function resolveEnergyPresence(presence: EnergyPresenceMap, level: EnergyLevel): EnergyPresence;
+/** True unless the presence is 'hidden' */
+export declare function isPresenceVisible(presence: EnergyPresence): boolean;
+/**
+ * Lift a presence map into an AdaptationStrategy so it can be resolved
+ * through the engine like any built-in strategy:
+ *
+ * ```ts
+ * const aiChat = createPresenceStrategy('ai-chat', presenceAtOrAbove(75))
+ * engine.resolve(aiChat) // 'visible' | 'muted' | 'hidden'
+ * ```
+ */
+export declare function createPresenceStrategy(name: string, presence: EnergyPresenceMap): AdaptationStrategy<EnergyPresence>;
+//# sourceMappingURL=presence.d.ts.map

package/dist/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAOpG,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,GAAG;IAC9E,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,kBAAuB,GAAG,iBAAiB,CAkBrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,KAAK,GAAE,cAAyB,GAC/B,iBAAiB,CAanB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,KAAK,GAAE,cAAyB,GAC/B,iBAAiB,CAanB;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,WAAW,GACjB,cAAc,CAUhB;AAED,2CAA2C;AAC3C,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAEnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,iBAAiB,GAC1B,kBAAkB,CAAC,cAAc,CAAC,CAoBpC"}

package/dist/presence.js

@@ -0,0 +1,122 @@
+import { getEnergyLevel, getEnergyLevels, isEnergyLevel } from './levels.js';
+import { ENERGY_PRESENCE_VALUES } from './types.js';
+function freezeObject(value) {
+    return Object.freeze(value);
+}
+/** Validate that an unknown value is a valid EnergyPresence */
+export function isEnergyPresence(value) {
+    return typeof value === 'string' && ENERGY_PRESENCE_VALUES.has(value);
+}
+/**
+ * Build a complete, frozen presence map from a partial spec.
+ *
+ * ```ts
+ * // Hide the AI chat at 50 and below, keep it muted at 75:
+ * const aiChatPresence = defineEnergyPresence({
+ *   default: 'visible',
+ *   75: 'muted',
+ *   50: 'hidden',
+ *   25: 'hidden',
+ *   0: 'hidden',
+ * })
+ * ```
+ */
+export function defineEnergyPresence(spec = {}) {
+    const fallback = spec.default ?? 'visible';
+    if (!isEnergyPresence(fallback)) {
+        throw new Error(`Invalid energy presence: ${String(fallback)}`);
+    }
+    const entries = {};
+    for (const definition of getEnergyLevels()) {
+        const declared = spec[definition.value];
+        if (declared !== undefined && !isEnergyPresence(declared)) {
+            throw new Error(`Invalid energy presence for level ${String(definition.value)}: ${String(declared)}`);
+        }
+        entries[definition.value] = declared ?? fallback;
+    }
+    return freezeObject(entries);
+}
+/**
+ * Presence map for elements that need at least `min` energy.
+ * Below `min` the element is `below` ('hidden' by default).
+ *
+ * ```ts
+ * const composerToolbar = presenceAtOrAbove(50)          // hidden at 25 and 0
+ * const aiSidebar = presenceAtOrAbove(75, 'muted')       // muted below 75
+ * ```
+ */
+export function presenceAtOrAbove(min, below = 'hidden') {
+    if (!isEnergyLevel(min)) {
+        throw new Error(`Invalid energy level: ${String(min)}`);
+    }
+    if (!isEnergyPresence(below)) {
+        throw new Error(`Invalid energy presence: ${String(below)}`);
+    }
+    const entries = {};
+    for (const definition of getEnergyLevels()) {
+        entries[definition.value] = definition.value >= min ? 'visible' : below;
+    }
+    return freezeObject(entries);
+}
+/**
+ * Presence map for elements that only belong at low energy — recovery hints,
+ * "one thing at a time" affordances. Above `max` the element is `above`
+ * ('hidden' by default).
+ */
+export function presenceAtOrBelow(max, above = 'hidden') {
+    if (!isEnergyLevel(max)) {
+        throw new Error(`Invalid energy level: ${String(max)}`);
+    }
+    if (!isEnergyPresence(above)) {
+        throw new Error(`Invalid energy presence: ${String(above)}`);
+    }
+    const entries = {};
+    for (const definition of getEnergyLevels()) {
+        entries[definition.value] = definition.value <= max ? 'visible' : above;
+    }
+    return freezeObject(entries);
+}
+/** Resolve the presence of an element for a given energy level */
+export function resolveEnergyPresence(presence, level) {
+    if (!isEnergyLevel(level)) {
+        throw new Error(`Invalid energy level: ${String(level)}`);
+    }
+    const resolved = presence[level];
+    if (!isEnergyPresence(resolved)) {
+        throw new Error(`Presence map has no valid entry for level ${String(level)}`);
+    }
+    return resolved;
+}
+/** True unless the presence is 'hidden' */
+export function isPresenceVisible(presence) {
+    return presence !== 'hidden';
+}
+/**
+ * Lift a presence map into an AdaptationStrategy so it can be resolved
+ * through the engine like any built-in strategy:
+ *
+ * ```ts
+ * const aiChat = createPresenceStrategy('ai-chat', presenceAtOrAbove(75))
+ * engine.resolve(aiChat) // 'visible' | 'muted' | 'hidden'
+ * ```
+ */
+export function createPresenceStrategy(name, presence) {
+    if (typeof name !== 'string' || name.trim().length === 0) {
+        throw new Error(`Invalid presence strategy name: ${String(name)}`);
+    }
+    // Validate the full map once at creation so resolve() cannot fail later.
+    for (const definition of getEnergyLevels()) {
+        resolveEnergyPresence(presence, definition.value);
+    }
+    return {
+        name,
+        describe(level) {
+            const def = getEnergyLevel(level);
+            return `${def.label}: ${name} is ${resolveEnergyPresence(presence, level)}`;
+        },
+        resolve(level) {
+            return resolveEnergyPresence(presence, level);
+        },
+    };
+}
+//# sourceMappingURL=presence.js.map

package/dist/presence.js.map

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

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import type { EnergyEngine } from './engine.js';
-import type { AdaptationStrategy, EnergyChangeListener, EnergyLevel, EnergyLevelDefinition, EnergyPersistence, EnergySource, EnergyState } from './types.js';
+import type { AdaptationStrategy, EnergyChangeListener, EnergyLevel, EnergyLevelDefinition, EnergyPersistence, EnergyPresence, EnergyPresenceMap, EnergySource, EnergyState } from './types.js';
 export interface EnergyProviderProps {
     /** Pre-created engine. When provided, this engine is used directly. */
     engine?: EnergyEngine;
@@ -29,6 +29,52 @@ export declare function useEnergyLevelCycler(): () => void;
 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;
+/** Resolve a presence map against the current energy level */
+export declare function useEnergyPresence(presence: EnergyPresenceMap): EnergyPresence;
+interface EnergyGateBaseProps {
+    /** Rendered instead of children while hidden. Default: nothing. */
+    fallback?: React.ReactNode;
+    /**
+     * Content to gate. The function form receives the resolved presence so
+     * 'muted' can style itself differently from 'visible'.
+     */
+    children: React.ReactNode | ((presence: EnergyPresence) => React.ReactNode);
+}
+export type EnergyGateProps = EnergyGateBaseProps & ({
+    /** Full presence declaration for this element */
+    presence: EnergyPresenceMap;
+    min?: never;
+    max?: never;
+} | {
+    presence?: never;
+    /** Shorthand: visible at or above this level, hidden below */
+    min: EnergyLevel;
+    /** Optionally also hidden above this level (band gating) */
+    max?: EnergyLevel;
+} | {
+    presence?: never;
+    min?: never;
+    /** Shorthand: visible at or below this level, hidden above */
+    max: EnergyLevel;
+});
+/**
+ * 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 declare function EnergyGate({ presence, min, max, fallback, children, }: EnergyGateProps): React.ReactNode;
 export interface EnergyIndicatorRenderProps {
     level: EnergyLevel;
     label: string;
@@ -45,4 +91,5 @@ export interface EnergyIndicatorProps {
 }
 /** Headless energy indicator - bring your own UI */
 export declare function EnergyIndicator({ children }: EnergyIndicatorProps): React.ReactNode;
+export {};
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +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,YAAY,EACZ,WAAW,EACZ,MAAM,YAAY,CAAA;AAqDnB,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,gGAoGrB;AAmBD,6DAA6D;AAC7D,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,IAAI;IAChC,WAAW;IACX,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,YAAY,KAAK,IAAI;CACpD,CAUA;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,EAAE,MAAM,CAAC,EAAE,YAAY,KAAK,IAAI,CAAA;CAC9D;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"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"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"}