@jgengine/core 0.14.0 → 0.15.0

package/dist/ui/modalStack.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Headless, serializable model for a stack of modal dialogs — the data layer behind a pause menu, a
+ * "quit to menu?" confirmation, a level-up popup, or any blocking overlay a game raises over its
+ * scene. It carries an ordered stack of opaque {@link ModalRecord}s (push to open, pop/resolve to
+ * close) and nothing about how they look: the model NEVER interprets a record's `kind` or a
+ * resolution's `result` string — those are free-form game vocabulary the React chrome in
+ * `@jgengine/react` renders. Observable ({@link ModalStack.subscribe}) and round-trips through a save
+ * ({@link ModalStack.snapshot}/{@link ModalStack.restore}). An injected clock powers optional
+ * per-modal auto-dismiss timers; leave those unset and the model is pure and clockless.
+ */
+/**
+ * One entry on the modal stack — a caller-authored, opaque record the game renders however it likes.
+ * `kind` and `payload` are never inspected by the model, so a confirm dialog, a pause menu, and a
+ * bespoke reward popup all share this shape.
+ */
+export interface ModalRecord {
+    /** Stable id, unique within the stack. Auto-assigned (`modal-<n>`) by {@link ModalStack.push} when omitted. */
+    id: string;
+    /** Free-form game style tag the renderer switches on (e.g. `"confirm"`, `"pause"`). Never interpreted here. */
+    kind: string;
+    /** Arbitrary serializable data for the renderer (title/body/button labels, context ids, …). */
+    payload?: unknown;
+    /**
+     * Auto-dismiss the modal this many ms after it opens, resolved by {@link ModalStack.tick} against
+     * the injected clock. Omit for a modal that only closes on an explicit pop/resolve.
+     */
+    timeoutMs?: number;
+    /** Result delivered when {@link ModalRecord.timeoutMs} fires. Default {@link MODAL_CANCEL}. */
+    timeoutResult?: string;
+}
+/** A modal to push — {@link ModalRecord} with an optional id (auto-assigned when absent). */
+export type ModalInput = Omit<ModalRecord, "id"> & {
+    id?: string;
+};
+/**
+ * The outcome of closing a modal via {@link ModalStack.resolve} (or an auto-dismiss) — the closed
+ * record's identity plus the free-form `result` string the caller chose. Delivered to the
+ * `onResolve` option and stashed as {@link ModalStack.lastResolution}.
+ */
+export interface ModalResolution {
+    /** The resolved record's id. */
+    id: string;
+    /** The resolved record's kind. */
+    kind: string;
+    /** Free-form outcome — e.g. {@link MODAL_CONFIRM}, {@link MODAL_CANCEL}, or a game-specific choice. Never interpreted here. */
+    result: string;
+    /** The resolved record's payload, echoed back so a handler needn't re-look-it-up. */
+    payload?: unknown;
+    /** Clock time (ms) the modal resolved, from the injected clock. */
+    at: number;
+}
+/** A serialized stack entry: the opaque record plus the clock time it opened (for timer restore). */
+export interface ModalStackEntry {
+    record: ModalRecord;
+    /** Clock time (ms) this modal was pushed — the base for its auto-dismiss timer. */
+    openedAt: number;
+}
+/** Serializable state — the ordered entries (bottom-first) and the id counter. Plain JSON. */
+export interface ModalStackSnapshot {
+    /** Stack entries from bottom to top; the last is the active (topmost) modal. */
+    entries: readonly ModalStackEntry[];
+    /** Next auto-id counter, so restored stacks keep generating unique ids. */
+    seq: number;
+}
+/** Options for {@link createModalStack}. */
+export interface ModalStackOptions {
+    /** Injected clock (ms) for timestamps and auto-dismiss timers. Default `Date.now`. */
+    now?: () => number;
+    /** Modals to open at construction, bottom-first. */
+    initial?: readonly ModalInput[];
+    /** Called whenever a modal is pushed (opened). */
+    onOpen?: (record: ModalRecord) => void;
+    /** Called whenever a modal closes via {@link ModalStack.resolve}, {@link ModalStack.pop}, or an auto-dismiss. */
+    onResolve?: (resolution: ModalResolution) => void;
+}
+/** Conventional confirm result for a two-button dialog — a shared string, not model behavior. */
+export declare const MODAL_CONFIRM = "confirm";
+/** Conventional cancel/dismiss result (also the default auto-dismiss and pop result). */
+export declare const MODAL_CANCEL = "cancel";
+/** An observable, serializable stack of modal dialogs. See {@link createModalStack}. */
+export interface ModalStack {
+    /**
+     * Push a modal onto the top of the stack and return the stored record (with its resolved id).
+     * Fires `onOpen`.
+     */
+    push(modal: ModalInput): ModalRecord;
+    /**
+     * Pop the topmost modal without a caller result — it resolves with {@link MODAL_CANCEL} (the ESC /
+     * backdrop-click behavior). Returns the removed record, or `null` when the stack is empty.
+     */
+    pop(): ModalRecord | null;
+    /**
+     * Resolve a modal with a free-form `result` and remove it: the top by default, or the entry with
+     * `options.id` from anywhere in the stack. Fires `onResolve` and records {@link ModalStack.lastResolution}.
+     * Returns the resolution, or `null` when the stack is empty or the id is unknown.
+     */
+    resolve(result: string, options?: {
+        id?: string;
+        payload?: unknown;
+    }): ModalResolution | null;
+    /** The active (topmost) modal, or `null` when nothing is open. */
+    top(): ModalRecord | null;
+    /** Whether any modal is open (`depth() > 0`) — a game gates input/pause on this. */
+    isOpen(): boolean;
+    /** Whether a modal with the given id is anywhere in the stack. */
+    has(id: string): boolean;
+    /** Number of stacked modals. */
+    depth(): number;
+    /** The full stack, bottom-first (last is the active modal). */
+    stack(): readonly ModalRecord[];
+    /** The most recent resolution (survives the modal being closed), or `null` if none yet. */
+    lastResolution(): ModalResolution | null;
+    /** Close every open modal, each resolving with {@link MODAL_CANCEL} (top-first). */
+    clear(): void;
+    /**
+     * Resolve every modal whose {@link ModalRecord.timeoutMs} has elapsed against `now` (default: the
+     * injected clock), top-first, using each record's `timeoutResult`. Call it from the game loop when
+     * any modal uses a timer. Returns the resolutions fired (possibly empty).
+     */
+    tick(now?: number): ModalResolution[];
+    /**
+     * Milliseconds until the given modal (default: the top) auto-dismisses, or `null` when it has no
+     * timer / is absent. Clamped at 0 once elapsed — feed a countdown ring off it.
+     */
+    timeRemaining(id?: string): number | null;
+    /** Observe every change (push/pop/resolve/clear/tick/restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): ModalStackSnapshot;
+    /** Restore from a {@link ModalStackSnapshot}, replacing the current stack. */
+    restore(snapshot: ModalStackSnapshot): void;
+}
+/**
+ * A stack of modal dialogs: push opaque records to open blocking overlays (a pause menu, a confirm
+ * prompt, a reward popup), pop or resolve them with a free-form result to close, and query the top /
+ * open / depth to gate game input. The model is deliberately vocabulary-free — it never reads a
+ * record's `kind` or a resolution's `result`, so a game owns every dialog style — and fully
+ * serializable, with an optional injected clock driving per-modal auto-dismiss. A React host renders
+ * `top()`; `subscribe` re-renders it, `snapshot`/`restore` round-trip it through a save.
+ *
+ * @capability modal-stack serializable, observable stack of opaque modal/dialog records — push/pop/resolve blocking overlays (pause menu, confirm dialog) with optional auto-dismiss; never interprets kind or result
+ */
+export declare function createModalStack(options?: ModalStackOptions): ModalStack;

package/dist/ui/modalStack.js

@@ -0,0 +1,160 @@
+/**
+ * Headless, serializable model for a stack of modal dialogs — the data layer behind a pause menu, a
+ * "quit to menu?" confirmation, a level-up popup, or any blocking overlay a game raises over its
+ * scene. It carries an ordered stack of opaque {@link ModalRecord}s (push to open, pop/resolve to
+ * close) and nothing about how they look: the model NEVER interprets a record's `kind` or a
+ * resolution's `result` string — those are free-form game vocabulary the React chrome in
+ * `@jgengine/react` renders. Observable ({@link ModalStack.subscribe}) and round-trips through a save
+ * ({@link ModalStack.snapshot}/{@link ModalStack.restore}). An injected clock powers optional
+ * per-modal auto-dismiss timers; leave those unset and the model is pure and clockless.
+ */
+/** Conventional confirm result for a two-button dialog — a shared string, not model behavior. */
+export const MODAL_CONFIRM = "confirm";
+/** Conventional cancel/dismiss result (also the default auto-dismiss and pop result). */
+export const MODAL_CANCEL = "cancel";
+/**
+ * A stack of modal dialogs: push opaque records to open blocking overlays (a pause menu, a confirm
+ * prompt, a reward popup), pop or resolve them with a free-form result to close, and query the top /
+ * open / depth to gate game input. The model is deliberately vocabulary-free — it never reads a
+ * record's `kind` or a resolution's `result`, so a game owns every dialog style — and fully
+ * serializable, with an optional injected clock driving per-modal auto-dismiss. A React host renders
+ * `top()`; `subscribe` re-renders it, `snapshot`/`restore` round-trip it through a save.
+ *
+ * @capability modal-stack serializable, observable stack of opaque modal/dialog records — push/pop/resolve blocking overlays (pause menu, confirm dialog) with optional auto-dismiss; never interprets kind or result
+ */
+export function createModalStack(options = {}) {
+    const now = options.now ?? Date.now;
+    const onOpen = options.onOpen;
+    const onResolve = options.onResolve;
+    const listeners = new Set();
+    let entries = [];
+    let seq = 0;
+    let last = null;
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function nextId() {
+        return `modal-${seq++}`;
+    }
+    function toRecord(input) {
+        const record = { id: input.id ?? nextId(), kind: input.kind };
+        if (input.payload !== undefined)
+            record.payload = input.payload;
+        if (input.timeoutMs !== undefined)
+            record.timeoutMs = input.timeoutMs;
+        if (input.timeoutResult !== undefined)
+            record.timeoutResult = input.timeoutResult;
+        return record;
+    }
+    /** @internal Remove the entry at `index` and produce+record its resolution. Does not notify. */
+    function resolveAt(index, result, payload, at = now()) {
+        const [entry] = entries.splice(index, 1);
+        const record = entry.record;
+        const resolution = {
+            id: record.id,
+            kind: record.kind,
+            result,
+            at,
+        };
+        const echo = payload !== undefined ? payload : record.payload;
+        if (echo !== undefined)
+            resolution.payload = echo;
+        last = resolution;
+        onResolve?.(resolution);
+        return resolution;
+    }
+    function push(input) {
+        const record = toRecord(input);
+        entries.push({ record, openedAt: now() });
+        onOpen?.(record);
+        notify();
+        return record;
+    }
+    for (const input of options.initial ?? [])
+        push(input);
+    return {
+        push,
+        pop() {
+            if (entries.length === 0)
+                return null;
+            const record = entries[entries.length - 1].record;
+            resolveAt(entries.length - 1, MODAL_CANCEL);
+            notify();
+            return record;
+        },
+        resolve(result, opts) {
+            const index = opts?.id !== undefined
+                ? entries.findIndex((entry) => entry.record.id === opts.id)
+                : entries.length - 1;
+            if (index < 0)
+                return null;
+            const resolution = resolveAt(index, result, opts?.payload);
+            notify();
+            return resolution;
+        },
+        top() {
+            return entries.length === 0 ? null : entries[entries.length - 1].record;
+        },
+        isOpen() {
+            return entries.length > 0;
+        },
+        has(id) {
+            return entries.some((entry) => entry.record.id === id);
+        },
+        depth() {
+            return entries.length;
+        },
+        stack() {
+            return entries.map((entry) => entry.record);
+        },
+        lastResolution() {
+            return last;
+        },
+        clear() {
+            if (entries.length === 0)
+                return;
+            while (entries.length > 0)
+                resolveAt(entries.length - 1, MODAL_CANCEL);
+            notify();
+        },
+        tick(nowOverride) {
+            const at = nowOverride ?? now();
+            const fired = [];
+            for (let i = entries.length - 1; i >= 0; i -= 1) {
+                const entry = entries[i];
+                const timeout = entry.record.timeoutMs;
+                if (timeout !== undefined && at - entry.openedAt >= timeout) {
+                    fired.push(resolveAt(i, entry.record.timeoutResult ?? MODAL_CANCEL, undefined, at));
+                }
+            }
+            if (fired.length > 0)
+                notify();
+            return fired;
+        },
+        timeRemaining(id) {
+            const entry = id !== undefined
+                ? entries.find((e) => e.record.id === id)
+                : entries[entries.length - 1];
+            if (entry === undefined || entry.record.timeoutMs === undefined)
+                return null;
+            return Math.max(0, entry.openedAt + entry.record.timeoutMs - now());
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return {
+                entries: entries.map((entry) => ({ record: { ...entry.record }, openedAt: entry.openedAt })),
+                seq,
+            };
+        },
+        restore(snapshot) {
+            entries = snapshot.entries.map((entry) => ({ record: { ...entry.record }, openedAt: entry.openedAt }));
+            seq = snapshot.seq;
+            last = null;
+            notify();
+        },
+    };
+}

package/dist/ui/objectiveBanner.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Which part of its life a banner is in: flying `"in"`, holding centered, or
+ * fading `"out"`. Progress `0..1` (see {@link ObjectiveBannerView.progress})
+ * runs within whichever phase is active — the renderer maps phase + progress to
+ * opacity/scale/translate however it likes.
+ */
+export type ObjectiveBannerPhase = "in" | "hold" | "out";
+/** One announcement request handed to {@link ObjectiveBannerController.announce}. */
+export interface ObjectiveBannerAnnouncement {
+    /** The big centered headline (e.g. `"WAVE 3"`, `"VICTORY"`). */
+    title: string;
+    /** Optional smaller line under the title (e.g. `"Defend the core"`). */
+    subtitle?: string;
+    /**
+     * Free-string label the game owns and styles ("wave", "victory", "defeat",
+     * "objective", …); the model never interprets it — it only carries it through
+     * to the renderer so a game can color/skin per kind. Default `"default"`.
+     */
+    kind?: string;
+    /** Fly-in duration in ms. Default `350`. */
+    inMs?: number;
+    /** Centered hold duration in ms. Default `2000`. */
+    holdMs?: number;
+    /** Fade-out duration in ms. Default `500`. */
+    outMs?: number;
+}
+/**
+ * The banner to draw right now: its content, the game-owned `kind`, the current
+ * {@link ObjectiveBannerPhase}, and `progress` `0..1` through that phase. This
+ * object is pooled and overwritten on the next {@link ObjectiveBannerController.current}
+ * call — read it, don't retain it.
+ */
+export interface ObjectiveBannerView {
+    /** Stable id assigned at announce time. */
+    id: number;
+    /** The headline. */
+    title: string;
+    /** The optional subtitle, or `undefined`. */
+    subtitle: string | undefined;
+    /** The game-owned free-string label. */
+    kind: string;
+    /** Which phase the banner is in. */
+    phase: ObjectiveBannerPhase;
+    /** Progress `0..1` within the current phase. */
+    progress: number;
+}
+/** A persisted banner record — all announcement fields resolved, plus id and schedule. */
+export interface StoredObjectiveBanner {
+    id: number;
+    title: string;
+    subtitle: string | undefined;
+    kind: string;
+    inMs: number;
+    holdMs: number;
+    outMs: number;
+    /** Clock time (ms) this banner started its fly-in, or `null` while still queued. */
+    startAt: number | null;
+}
+/** Serializable state of the queue and the active banner, for save/restore. */
+export interface ObjectiveBannerSnapshot {
+    /** Wall-clock (ms) the snapshot was taken, so restore re-anchors elapsed time. */
+    now: number;
+    /** Next id to hand out. */
+    nextId: number;
+    /** The active banner (head) followed by everything still queued, in order. */
+    queue: readonly StoredObjectiveBanner[];
+}
+/** A live, clock-driven objective/stage banner controller. */
+export interface ObjectiveBannerController {
+    /**
+     * Enqueue a banner. If nothing is showing it starts flying in immediately;
+     * otherwise it waits its turn (one banner shows at a time). Returns the new id.
+     */
+    announce(announcement: ObjectiveBannerAnnouncement): number;
+    /**
+     * Advance the clock: transition the active banner through in → hold → out,
+     * reap it when its life ends, and start the next queued banner. Pass an explicit
+     * `nowMs` to drive deterministically, else the injected clock is read. Notifies
+     * subscribers. Call it each frame from the renderer.
+     */
+    advance(nowMs?: number): void;
+    /** The banner to draw right now (pooled — do not retain), or `null` when idle. */
+    current(): ObjectiveBannerView | null;
+    /** Dismiss the active banner immediately and start the next queued one, if any. */
+    skip(): void;
+    /** Drop the active banner and everything queued. */
+    clear(): void;
+    /** How many banners are waiting behind the active one. */
+    pending(): number;
+    /** Whether a banner is currently active. */
+    isActive(): boolean;
+    /** Observe changes (announce, advance, skip, clear, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): ObjectiveBannerSnapshot;
+    /** Restore from an {@link ObjectiveBannerSnapshot}. */
+    restore(snapshot: ObjectiveBannerSnapshot): void;
+}
+/** Options for {@link createObjectiveBanner}. */
+export interface ObjectiveBannerOptions {
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Default fly-in ms for announcements that omit `inMs`. Default `350`. */
+    inMs?: number;
+    /** Default hold ms for announcements that omit `holdMs`. Default `2000`. */
+    holdMs?: number;
+    /** Default fade-out ms for announcements that omit `outMs`. Default `500`. */
+    outMs?: number;
+}
+/**
+ * A serializable, clock-driven stage/objective banner controller: the classic
+ * transient centered title stamp ("WAVE 3", "VICTORY", "OBJECTIVE COMPLETE"). A
+ * game calls `announce({ title, subtitle?, kind? })` and the controller queues it,
+ * flies it in, holds it, and fades it out on an injected clock — one banner at a
+ * time — exposing the current banner plus its phase (in/hold/out) and `progress`
+ * `0..1` for a renderer to animate opacity/scale/translate. Nothing here is
+ * genre-specific: `kind` is a free label the game owns and styles, and all timings
+ * are parameters. Call `advance()` each frame; `current()` returns the pooled view
+ * to draw; `snapshot`/`restore` round-trips the queue through a save.
+ *
+ * @capability objective-banner serializable, clock-driven stage/objective banner queue — flies a big transient centered title + optional subtitle in, holds, and fades out one at a time, with phase + progress for animation, free-string kinds the game styles, and snapshot/restore
+ */
+export declare function createObjectiveBanner(options?: ObjectiveBannerOptions): ObjectiveBannerController;

package/dist/ui/objectiveBanner.js

@@ -0,0 +1,162 @@
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * A serializable, clock-driven stage/objective banner controller: the classic
+ * transient centered title stamp ("WAVE 3", "VICTORY", "OBJECTIVE COMPLETE"). A
+ * game calls `announce({ title, subtitle?, kind? })` and the controller queues it,
+ * flies it in, holds it, and fades it out on an injected clock — one banner at a
+ * time — exposing the current banner plus its phase (in/hold/out) and `progress`
+ * `0..1` for a renderer to animate opacity/scale/translate. Nothing here is
+ * genre-specific: `kind` is a free label the game owns and styles, and all timings
+ * are parameters. Call `advance()` each frame; `current()` returns the pooled view
+ * to draw; `snapshot`/`restore` round-trips the queue through a save.
+ *
+ * @capability objective-banner serializable, clock-driven stage/objective banner queue — flies a big transient centered title + optional subtitle in, holds, and fades out one at a time, with phase + progress for animation, free-string kinds the game styles, and snapshot/restore
+ */
+export function createObjectiveBanner(options = {}) {
+    const now = options.now ?? Date.now;
+    const defaultIn = Math.max(0, options.inMs ?? 350);
+    const defaultHold = Math.max(0, options.holdMs ?? 2000);
+    const defaultOut = Math.max(0, options.outMs ?? 500);
+    // queue[0] is the active banner; the rest wait their turn.
+    const queue = [];
+    const listeners = new Set();
+    // Pooled view — reused across current() calls, never per-frame allocated.
+    const view = { id: 0, title: "", subtitle: undefined, kind: "", phase: "in", progress: 0 };
+    let nextId = 1;
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** Total lifetime of a banner in ms. */
+    function totalMs(banner) {
+        return banner.inMs + banner.holdMs + banner.outMs;
+    }
+    /**
+     * Activate/chain the head, reap any that have fully expired at `t`, and cache
+     * the active banner's phase + progress. Deterministic regardless of how often
+     * it is called: a finished banner hands its scheduled end time to the next.
+     */
+    function recompute(t) {
+        while (queue.length > 0) {
+            const head = queue[0];
+            if (head.startAt === null)
+                head.startAt = t;
+            const total = totalMs(head);
+            const elapsed = t - head.startAt;
+            if (total <= 0 || elapsed >= total) {
+                queue.shift();
+                const next = queue[0];
+                if (next !== undefined && next.startAt === null)
+                    next.startAt = head.startAt + total;
+                continue;
+            }
+            if (elapsed < head.inMs) {
+                head.phase = "in";
+                head.progress = head.inMs > 0 ? clamp01(elapsed / head.inMs) : 1;
+            }
+            else if (elapsed < head.inMs + head.holdMs) {
+                head.phase = "hold";
+                head.progress = head.holdMs > 0 ? clamp01((elapsed - head.inMs) / head.holdMs) : 1;
+            }
+            else {
+                head.phase = "out";
+                head.progress = head.outMs > 0 ? clamp01((elapsed - head.inMs - head.holdMs) / head.outMs) : 1;
+            }
+            return;
+        }
+    }
+    return {
+        announce(announcement) {
+            const id = nextId++;
+            queue.push({
+                id,
+                title: announcement.title,
+                subtitle: announcement.subtitle,
+                kind: announcement.kind ?? "default",
+                inMs: Math.max(0, announcement.inMs ?? defaultIn),
+                holdMs: Math.max(0, announcement.holdMs ?? defaultHold),
+                outMs: Math.max(0, announcement.outMs ?? defaultOut),
+                startAt: null,
+                phase: "in",
+                progress: 0,
+            });
+            recompute(now());
+            notify();
+            return id;
+        },
+        advance(nowMs) {
+            recompute(nowMs ?? now());
+            notify();
+        },
+        current() {
+            const head = queue[0];
+            if (head === undefined || head.startAt === null)
+                return null;
+            view.id = head.id;
+            view.title = head.title;
+            view.subtitle = head.subtitle;
+            view.kind = head.kind;
+            view.phase = head.phase;
+            view.progress = head.progress;
+            return view;
+        },
+        skip() {
+            if (queue.length === 0)
+                return;
+            queue.shift();
+            recompute(now());
+            notify();
+        },
+        clear() {
+            if (queue.length === 0)
+                return;
+            queue.length = 0;
+            notify();
+        },
+        pending() {
+            return queue.length === 0 ? 0 : queue.length - 1;
+        },
+        isActive() {
+            const head = queue[0];
+            return head !== undefined && head.startAt !== null;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return {
+                now: now(),
+                nextId,
+                queue: queue.map((banner) => ({
+                    id: banner.id,
+                    title: banner.title,
+                    subtitle: banner.subtitle,
+                    kind: banner.kind,
+                    inMs: banner.inMs,
+                    holdMs: banner.holdMs,
+                    outMs: banner.outMs,
+                    startAt: banner.startAt,
+                })),
+            };
+        },
+        restore(snapshot) {
+            queue.length = 0;
+            nextId = snapshot.nextId;
+            const t = now();
+            const drift = t - snapshot.now;
+            for (const stored of snapshot.queue) {
+                queue.push({
+                    ...stored,
+                    startAt: stored.startAt === null ? null : stored.startAt + drift,
+                    phase: "in",
+                    progress: 0,
+                });
+            }
+            recompute(t);
+            notify();
+        },
+    };
+}

package/dist/ui/photoMode.d.ts

@@ -0,0 +1,32 @@
+/** Serializable photo-mode preferences a game reads to compose its capture UI. */
+export interface PhotoModeState {
+    /** Photo mode is engaged (game frees the camera / pauses as it sees fit). */
+    active: boolean;
+    /** Hide the gameplay HUD for a clean shot. */
+    hideHud: boolean;
+}
+/** The out-of-the-box photo-mode state: not active, HUD hidden when it engages. */
+export declare const DEFAULT_PHOTO_MODE: PhotoModeState;
+/** Observable photo-mode store — genre-agnostic state a game binds its capture flow to. */
+export interface PhotoModeStore {
+    get(): PhotoModeState;
+    /** Engage photo mode. */
+    enter(): void;
+    /** Leave photo mode. */
+    exit(): void;
+    toggle(): void;
+    setHideHud(hide: boolean): void;
+    set(patch: Partial<PhotoModeState>): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): PhotoModeState;
+    restore(snapshot: Partial<PhotoModeState>): void;
+}
+/**
+ * Serializable, observable photo-mode state (active + hide-HUD). Genre-agnostic
+ * plumbing — a game engages it to free its camera and hide gameplay chrome for a
+ * clean capture, and reads `hideHud` to conditionally render its HUD. Pair with
+ * React `PhotoModeControls` and shell `captureCanvas`.
+ *
+ * @capability photo-mode observable photo-mode state (active + hide-HUD) a game binds its screenshot/camera flow to
+ */
+export declare function createPhotoModeStore(initial?: Partial<PhotoModeState>): PhotoModeStore;

package/dist/ui/photoMode.js

@@ -0,0 +1,51 @@
+/** The out-of-the-box photo-mode state: not active, HUD hidden when it engages. */
+export const DEFAULT_PHOTO_MODE = { active: false, hideHud: true };
+/**
+ * Serializable, observable photo-mode state (active + hide-HUD). Genre-agnostic
+ * plumbing — a game engages it to free its camera and hide gameplay chrome for a
+ * clean capture, and reads `hideHud` to conditionally render its HUD. Pair with
+ * React `PhotoModeControls` and shell `captureCanvas`.
+ *
+ * @capability photo-mode observable photo-mode state (active + hide-HUD) a game binds its screenshot/camera flow to
+ */
+export function createPhotoModeStore(initial = {}) {
+    let state = { ...DEFAULT_PHOTO_MODE, ...initial };
+    const listeners = new Set();
+    function commit(next) {
+        if (next.active === state.active && next.hideHud === state.hideHud)
+            return;
+        state = next;
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        get() {
+            return state;
+        },
+        enter() {
+            commit({ ...state, active: true });
+        },
+        exit() {
+            commit({ ...state, active: false });
+        },
+        toggle() {
+            commit({ ...state, active: !state.active });
+        },
+        setHideHud(hide) {
+            commit({ ...state, hideHud: hide });
+        },
+        set(patch) {
+            commit({ ...state, ...patch });
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return state;
+        },
+        restore(snapshot) {
+            commit({ ...DEFAULT_PHOTO_MODE, ...snapshot });
+        },
+    };
+}