@jgengine/core 0.13.0 → 0.15.0-next.0

package/dist/ui/coachMarks.js

@@ -0,0 +1,126 @@
+/**
+ * An onboarding coach-mark run: an ordered sequence of hint steps, each shown as
+ * a centered callout or anchored to a UI element, with a persisted "seen" set so
+ * completed onboarding stays done across sessions, and data-first condition
+ * gating so a step waits until its trigger id is satisfied. Advance/skip/dismiss
+ * drive it; `snapshot`/`restore` round-trip the seen set through a save. Purely a
+ * model — a React host renders `current()`.
+ *
+ * @capability coach-marks ordered, gated, persist-once onboarding coach-marks/tutorial callouts — anchored or centered steps with a seen set and Next/Skip
+ */
+export function createCoachMarkSequence(options) {
+    const steps = [...options.steps];
+    const now = options.now ?? Date.now;
+    const seenAtMap = new Map();
+    let satisfied = new Set(options.satisfied ?? []);
+    const listeners = new Set();
+    for (const id of options.seen ?? []) {
+        if (!seenAtMap.has(id))
+            seenAtMap.set(id, now());
+    }
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function markSeen(id) {
+        if (seenAtMap.has(id))
+            return false;
+        seenAtMap.set(id, now());
+        return true;
+    }
+    function eligible(step) {
+        if (seenAtMap.has(step.id))
+            return false;
+        return step.condition === undefined || satisfied.has(step.condition);
+    }
+    function remaining() {
+        let count = 0;
+        for (const step of steps)
+            if (!seenAtMap.has(step.id))
+                count += 1;
+        return count;
+    }
+    function current() {
+        for (let index = 0; index < steps.length; index += 1) {
+            const step = steps[index];
+            if (eligible(step)) {
+                return { step, index, total: steps.length, remaining: remaining() };
+            }
+        }
+        return null;
+    }
+    return {
+        steps,
+        current,
+        advance() {
+            const active = current();
+            if (active !== null && markSeen(active.step.id))
+                notify();
+            return current();
+        },
+        next() {
+            return this.advance();
+        },
+        dismiss(id) {
+            if (markSeen(id))
+                notify();
+        },
+        skipAll() {
+            let changed = false;
+            for (const step of steps)
+                if (markSeen(step.id))
+                    changed = true;
+            if (changed)
+                notify();
+        },
+        satisfy(...triggerIds) {
+            let changed = false;
+            for (const id of triggerIds) {
+                if (!satisfied.has(id)) {
+                    satisfied.add(id);
+                    changed = true;
+                }
+            }
+            if (changed)
+                notify();
+        },
+        setSatisfied(triggerIds) {
+            satisfied = new Set(triggerIds);
+            notify();
+        },
+        isTriggerSatisfied(triggerId) {
+            return satisfied.has(triggerId);
+        },
+        isSeen(id) {
+            return seenAtMap.has(id);
+        },
+        seenAt(id) {
+            return seenAtMap.get(id);
+        },
+        isComplete() {
+            return steps.every((step) => seenAtMap.has(step.id));
+        },
+        remaining,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            const seen = [];
+            const seenAt = {};
+            for (const [id, at] of seenAtMap) {
+                seen.push(id);
+                seenAt[id] = at;
+            }
+            return { seen, seenAt, satisfied: [...satisfied] };
+        },
+        restore(snapshot) {
+            seenAtMap.clear();
+            for (const id of snapshot.seen) {
+                seenAtMap.set(id, snapshot.seenAt[id] ?? now());
+            }
+            satisfied = new Set(snapshot.satisfied);
+            notify();
+        },
+    };
+}

package/dist/ui/floatingText.d.ts

@@ -0,0 +1,114 @@
+/** A world-space anchor `[x, y, z]` a floating-text entry rises from. */
+export type FloatingTextPosition = readonly [number, number, number];
+/**
+ * One text pop to spawn: what to say, where in the world, and how it moves and
+ * fades. Everything but `position` and `text` is optional and falls back to the
+ * field's defaults. `kind` is a free-form tag (`"damage"`, `"heal"`, `"crit"`,
+ * `"xp"`, `"gold"`, `"bark"`, …) the presentation layer styles — the model never
+ * interprets it, so nothing here is combat- or genre-specific.
+ */
+export interface FloatingTextDef {
+    /** World anchor the text rises from. */
+    position: FloatingTextPosition;
+    /** The text to show. */
+    text: string;
+    /** Free-form style tag the game colors/skins. Default `"default"`. */
+    kind?: string;
+    /** Optional CSS color hint carried straight through to the view (presentation may override per `kind`). */
+    color?: string;
+    /** Relative scale multiplier (before the birth pop-in). Default 1. */
+    size?: number;
+    /** Upward world-Y speed in units/second. Default = field `defaultRise`. */
+    rise?: number;
+    /** Horizontal world-X speed in units/second (signed). Default: a small seeded jitter in `±driftJitter`. */
+    drift?: number;
+    /** Lifetime in seconds. Default = field `defaultLifetime`. */
+    lifetime?: number;
+}
+/** Construction options for {@link createFloatingTextField}. */
+export interface FloatingTextFieldConfig {
+    /** Hard cap on live entries; the pool never grows past this. When full, the oldest entry is recycled. Default 64. */
+    max?: number;
+    /** Injected wall clock in ms, stamped on each entry's `bornAt`. Default `Date.now`; inject for deterministic tests. */
+    now?: () => number;
+    /** Seed for the horizontal-drift jitter stream — same seed + same calls reproduce identical motion. Default `"floating-text"`. */
+    seed?: string | number;
+    /** Default lifetime in seconds when a def omits `lifetime`. Default 1.4. */
+    defaultLifetime?: number;
+    /** Default upward speed in units/second when a def omits `rise`. Default 1.2. */
+    defaultRise?: number;
+    /** Max magnitude of the seeded horizontal drift used when a def omits `drift`. Default 0.6. */
+    driftJitter?: number;
+    /** Fraction of life spent on the birth scale pop-in (0.6→1). Default 0.16. */
+    popIn?: number;
+    /** Fraction of life over which alpha fades to 0 at the end. Default 0.4. */
+    fadeFraction?: number;
+}
+/** A live entry resolved for rendering: current world position and fade/scale over life. */
+export interface FloatingTextView {
+    /** Stable, monotonically increasing id assigned at emit — usable as a React key. */
+    id: number;
+    /** Current world position with rise (Y) and drift (X) applied. */
+    position: FloatingTextPosition;
+    /** The text to show. */
+    text: string;
+    /** The style tag (resolved; `"default"` when the def omitted `kind`). */
+    kind: string;
+    /** The def's color hint, if any. */
+    color?: string;
+    /** Resolved scale: base `size` times the current birth pop-in factor. */
+    size: number;
+    /** Opacity `0..1`, full until the fade window then easing to 0. */
+    alpha: number;
+    /** Age as a fraction of lifetime, `0..1`. */
+    progress: number;
+    /** Wall-clock ms the entry was emitted (from the injected `now`). */
+    bornAt: number;
+}
+/** Serializable state for save/restore and deterministic replay. */
+export interface FloatingTextSnapshot {
+    seed: number;
+    nextId: number;
+    count: number;
+    /** Numeric per-entry columns, flattened `count * NUMERIC_STRIDE`. */
+    data: number[];
+    /** Per-entry text. */
+    text: string[];
+    /** Per-entry kind. */
+    kind: string[];
+    /** Per-entry color (empty string = none). */
+    color: string[];
+}
+/** A live, dt-driven field of world-anchored floating text. */
+export interface FloatingTextField {
+    /** Spawn one entry; returns its id. When the pool is full the oldest live entry is recycled. */
+    emit(def: FloatingTextDef): number;
+    /** Advance every entry by `dt` seconds: age, rise, drift, and reap the expired. */
+    update(dt: number): void;
+    /** Snapshot of the live entries resolved for rendering (a fresh array each call). */
+    active(): FloatingTextView[];
+    /** Live entry count. */
+    count(): number;
+    /** Remove every entry (keeps the seed stream and id counter). */
+    clear(): void;
+    /** Subscribe to changes (emit/update/clear/restore); returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    snapshot(): FloatingTextSnapshot;
+    restore(snapshot: FloatingTextSnapshot): void;
+}
+/**
+ * A generic, allocation-aware field of world-anchored floating text: damage
+ * numbers, heals, crits, XP/gold gains, status pops, dialogue barks — anything a
+ * game wants to say at a point in the world for a moment. It is dt-driven (call
+ * `update(dt)` each frame) and deterministic: the only randomness is the
+ * horizontal drift jitter, which flows from the injected `seed`, so the same seed
+ * and the same emit/update sequence reproduce identical motion, and
+ * `snapshot`/`restore` round-trips the live pool. The model owns only the
+ * spawn → rise/drift → fade → reap lifecycle: `kind` is a free string and `color`
+ * a passthrough hint, so nothing here couples to combat or any genre. Presentation
+ * (projecting each entry to the screen and styling it per `kind`) lives in
+ * `@jgengine/react`'s `FloatingText`.
+ *
+ * @capability floating-text deterministic pooled world-anchored floating combat text / damage numbers with rise, drift, fade, and serializable state
+ */
+export declare function createFloatingTextField(config?: FloatingTextFieldConfig): FloatingTextField;

package/dist/ui/floatingText.js

@@ -0,0 +1,203 @@
+import { hashString, randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+/** Columns per entry in the numeric SoA pool: id, ox, oy, oz, age, life, rise, drift, size. */
+const NUMERIC_STRIDE = 9;
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * A generic, allocation-aware field of world-anchored floating text: damage
+ * numbers, heals, crits, XP/gold gains, status pops, dialogue barks — anything a
+ * game wants to say at a point in the world for a moment. It is dt-driven (call
+ * `update(dt)` each frame) and deterministic: the only randomness is the
+ * horizontal drift jitter, which flows from the injected `seed`, so the same seed
+ * and the same emit/update sequence reproduce identical motion, and
+ * `snapshot`/`restore` round-trips the live pool. The model owns only the
+ * spawn → rise/drift → fade → reap lifecycle: `kind` is a free string and `color`
+ * a passthrough hint, so nothing here couples to combat or any genre. Presentation
+ * (projecting each entry to the screen and styling it per `kind`) lives in
+ * `@jgengine/react`'s `FloatingText`.
+ *
+ * @capability floating-text deterministic pooled world-anchored floating combat text / damage numbers with rise, drift, fade, and serializable state
+ */
+export function createFloatingTextField(config = {}) {
+    const max = Math.max(1, Math.floor(config.max ?? 64));
+    const now = config.now ?? (() => Date.now());
+    const defaultLifetime = config.defaultLifetime ?? 1.4;
+    const defaultRise = config.defaultRise ?? 1.2;
+    const driftJitter = config.driftJitter ?? 0.6;
+    const popIn = clamp01(config.popIn ?? 0.16);
+    const fadeFraction = clamp01(config.fadeFraction ?? 0.4);
+    // Numeric SoA columns.
+    const id = new Float64Array(max);
+    const ox = new Float32Array(max);
+    const oy = new Float32Array(max);
+    const oz = new Float32Array(max);
+    const age = new Float32Array(max);
+    const life = new Float32Array(max);
+    const rise = new Float32Array(max);
+    const drift = new Float32Array(max);
+    const size = new Float32Array(max);
+    const bornAt = new Float64Array(max);
+    // String columns (strings can't live in a typed array).
+    const text = new Array(max).fill("");
+    const kind = new Array(max).fill("");
+    const color = new Array(max).fill(undefined);
+    let live = 0;
+    let nextId = 1;
+    let seed = randomSeedFrom(typeof config.seed === "number" ? config.seed : hashString(String(config.seed ?? "floating-text")));
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function rand() {
+        const [value, next] = stepRandomSeed(seed);
+        seed = next;
+        return value;
+    }
+    /** Index of the oldest live entry (highest age) — the one recycled when the pool is full. */
+    function oldestIndex() {
+        let best = 0;
+        for (let i = 1; i < live; i++)
+            if (age[i] > age[best])
+                best = i;
+        return best;
+    }
+    function writeEntry(i, def) {
+        const entryId = nextId++;
+        id[i] = entryId;
+        ox[i] = def.position[0];
+        oy[i] = def.position[1];
+        oz[i] = def.position[2];
+        age[i] = 0;
+        life[i] = Math.max(0.0001, def.lifetime ?? defaultLifetime);
+        rise[i] = def.rise ?? defaultRise;
+        // A seeded per-entry drift keeps stacked numbers from overlapping; still deterministic.
+        drift[i] = def.drift ?? (rand() * 2 - 1) * driftJitter;
+        size[i] = def.size ?? 1;
+        bornAt[i] = now();
+        text[i] = def.text;
+        kind[i] = def.kind ?? "default";
+        color[i] = def.color;
+        return entryId;
+    }
+    function swapRemove(i) {
+        const last = live - 1;
+        if (i !== last) {
+            id[i] = id[last];
+            ox[i] = ox[last];
+            oy[i] = oy[last];
+            oz[i] = oz[last];
+            age[i] = age[last];
+            life[i] = life[last];
+            rise[i] = rise[last];
+            drift[i] = drift[last];
+            size[i] = size[last];
+            bornAt[i] = bornAt[last];
+            text[i] = text[last];
+            kind[i] = kind[last];
+            color[i] = color[last];
+        }
+        live--;
+    }
+    /** Current scale (base times birth pop-in) for entry `i`. */
+    function resolveScale(i) {
+        const t = clamp01(age[i] / life[i]);
+        const pop = popIn > 0 && t < popIn ? 0.6 + 0.4 * (t / popIn) : 1;
+        return size[i] * pop;
+    }
+    /** Current alpha (full until the fade window, then easing to 0) for entry `i`. */
+    function resolveAlpha(i) {
+        const t = clamp01(age[i] / life[i]);
+        if (fadeFraction <= 0)
+            return 1;
+        const fadeStart = 1 - fadeFraction;
+        return t <= fadeStart ? 1 : clamp01((1 - t) / fadeFraction);
+    }
+    const field = {
+        emit(def) {
+            const i = live < max ? live++ : oldestIndex();
+            const entryId = writeEntry(i, def);
+            notify();
+            return entryId;
+        },
+        update(dt) {
+            if (dt <= 0)
+                return;
+            for (let i = live - 1; i >= 0; i--) {
+                age[i] += dt;
+                if (age[i] >= life[i]) {
+                    swapRemove(i);
+                }
+            }
+            notify();
+        },
+        active() {
+            const views = [];
+            for (let i = 0; i < live; i++) {
+                const a = age[i];
+                views.push({
+                    id: id[i],
+                    position: [ox[i] + drift[i] * a, oy[i] + rise[i] * a, oz[i]],
+                    text: text[i],
+                    kind: kind[i],
+                    color: color[i],
+                    size: resolveScale(i),
+                    alpha: resolveAlpha(i),
+                    progress: clamp01(a / life[i]),
+                    bornAt: bornAt[i],
+                });
+            }
+            return views;
+        },
+        count() {
+            return live;
+        },
+        clear() {
+            live = 0;
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            const data = [];
+            const outText = [];
+            const outKind = [];
+            const outColor = [];
+            for (let i = 0; i < live; i++) {
+                data.push(id[i], ox[i], oy[i], oz[i], age[i], life[i], rise[i], drift[i], size[i]);
+                outText.push(text[i]);
+                outKind.push(kind[i]);
+                outColor.push(color[i] ?? "");
+            }
+            return { seed: seed, nextId, count: live, data, text: outText, kind: outKind, color: outColor };
+        },
+        restore(snapshot) {
+            seed = randomSeedFrom(snapshot.seed);
+            nextId = snapshot.nextId;
+            live = Math.min(max, snapshot.count);
+            for (let i = 0; i < live; i++) {
+                const o = i * NUMERIC_STRIDE;
+                id[i] = snapshot.data[o];
+                ox[i] = snapshot.data[o + 1];
+                oy[i] = snapshot.data[o + 2];
+                oz[i] = snapshot.data[o + 3];
+                age[i] = snapshot.data[o + 4];
+                life[i] = snapshot.data[o + 5];
+                rise[i] = snapshot.data[o + 6];
+                drift[i] = snapshot.data[o + 7];
+                size[i] = snapshot.data[o + 8];
+                // bornAt is presentational only; it is not round-tripped, so re-stamp on restore.
+                bornAt[i] = now();
+                text[i] = snapshot.text[i];
+                kind[i] = snapshot.kind[i];
+                const c = snapshot.color[i];
+                color[i] = c === undefined || c === "" ? undefined : c;
+            }
+            notify();
+        },
+    };
+    return field;
+}

package/dist/ui/hudScale.d.ts

@@ -37,7 +37,22 @@ export interface HudOverflow {
 }
 /** Non-null when any edge of `rect` falls outside `viewport` by more than `tolerance` px; each field is the overflow distance past that edge (0 when inside). */
 export declare function rectOverflow(rect: HudRect, viewport: HudSize, tolerance?: number): Omit<HudOverflow, "id"> | null;
-/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+/**
+ * True when at least `minVisiblePx²` of `rect` actually falls inside `viewport`.
+ * The boundary check uses this to tell a *shown* surface from a *closed* one: a
+ * mail drawer parked fully off-screen (or a menu that has not been opened) never
+ * intersects the viewport, so it is not "escaping" — it is simply not on screen.
+ * Only a surface that is partly visible and partly past an edge is a real defect.
+ *
+ * @internal Consumed transitively through {@link overflowingPanels}; exported for unit tests.
+ */
+export declare function rectIntersectsViewport(rect: HudRect, viewport: HudSize, minVisiblePx?: number): boolean;
+/**
+ * Every panel rect that escapes the viewport — the data behind the HUD overflow
+ * gate. A rect is only reported when it is partly visible *and* crosses an edge;
+ * a fully off-screen (closed/hidden) surface is skipped, so parked drawers and
+ * unopened menus never raise a false alarm.
+ */
 export declare function overflowingPanels(panels: readonly {
     id: string;
     rect: HudRect;

package/dist/ui/hudScale.js

@@ -43,10 +43,31 @@ export function rectOverflow(rect, viewport, tolerance = 1.5) {
     const round = (n) => Math.round(n * 10) / 10;
     return { left: round(left), top: round(top), right: round(right), bottom: round(bottom) };
 }
-/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+/**
+ * True when at least `minVisiblePx²` of `rect` actually falls inside `viewport`.
+ * The boundary check uses this to tell a *shown* surface from a *closed* one: a
+ * mail drawer parked fully off-screen (or a menu that has not been opened) never
+ * intersects the viewport, so it is not "escaping" — it is simply not on screen.
+ * Only a surface that is partly visible and partly past an edge is a real defect.
+ *
+ * @internal Consumed transitively through {@link overflowingPanels}; exported for unit tests.
+ */
+export function rectIntersectsViewport(rect, viewport, minVisiblePx = 1) {
+    const visibleWidth = Math.min(rect.x + rect.width, viewport.width) - Math.max(rect.x, 0);
+    const visibleHeight = Math.min(rect.y + rect.height, viewport.height) - Math.max(rect.y, 0);
+    return visibleWidth >= minVisiblePx && visibleHeight >= minVisiblePx;
+}
+/**
+ * Every panel rect that escapes the viewport — the data behind the HUD overflow
+ * gate. A rect is only reported when it is partly visible *and* crosses an edge;
+ * a fully off-screen (closed/hidden) surface is skipped, so parked drawers and
+ * unopened menus never raise a false alarm.
+ */
 export function overflowingPanels(panels, viewport, tolerance = 1.5) {
     const out = [];
     for (const panel of panels) {
+        if (!rectIntersectsViewport(panel.rect, viewport))
+            continue;
         const overflow = rectOverflow(panel.rect, viewport, tolerance);
         if (overflow !== null)
             out.push({ id: panel.id, ...overflow });

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;