@jgengine/core 0.13.0 → 0.15.0-next.0

package/dist/time/timerSet.d.ts

@@ -0,0 +1,132 @@
+/**
+ * A serializable set of named countdown / countup timers evaluated against an
+ * injected clock. One primitive covers round timers, respawn clocks, and ability
+ * cooldown/charge — they are the same mechanic (elapsed vs. duration on a clock),
+ * so `id` and any labels are free strings the engine never interprets.
+ *
+ * No hidden interval math: the set stores only accumulated elapsed time plus a
+ * clock anchor while running, and derives every read on demand. `subscribe`
+ * reports structural changes (start/pause/stop/reset); `poll` reports expiry
+ * edges so a game can react (respawn, round end, ability ready). `snapshot` /
+ * `restore` round-trip through a save by resolving elapsed at snapshot time and
+ * re-anchoring on restore, so pause/resume survives serialization.
+ */
+/** Direction a timer counts. `"down"` leads with `remainingMs` (countdown); `"up"` leads with `elapsedMs` (charge). */
+export type TimerDirection = "down" | "up";
+/** Options for {@link TimerSet.start}. */
+export interface TimerStartOptions {
+    /** Full span of the timer in milliseconds. Non-positive spans read as instantly expired. */
+    durationMs: number;
+    /** Count direction. Default `"down"`. Purely a read convenience — expiry is the same either way. */
+    direction?: TimerDirection;
+    /** When true the timer wraps at its duration and emits an expiry edge each cycle instead of stopping. Default `false`. */
+    loop?: boolean;
+}
+/**
+ * A single timer's resolved state for one read. All fields are plain numbers so
+ * a HUD can render without touching the model. For a looping timer the values
+ * describe the current cycle; `expired` is only ever `true` for a finished
+ * non-looping timer (loops signal completion through {@link TimerSet.poll}).
+ */
+export interface TimerRead {
+    /** The timer's id (free string). */
+    id: string;
+    /** The configured count direction — lets a readout auto-pick remaining (`"down"`) vs elapsed (`"up"`). */
+    direction: TimerDirection;
+    /** Milliseconds left in this cycle, clamped to `0`. */
+    remainingMs: number;
+    /** Milliseconds elapsed in this cycle, clamped to `durationMs`. */
+    elapsedMs: number;
+    /** The configured span in milliseconds. */
+    durationMs: number;
+    /** Fill fraction `0..1` = `elapsedMs / durationMs` — a ring or bar fills as time passes. */
+    progress01: number;
+    /** Whether the timer is counting (not paused/stopped). */
+    running: boolean;
+    /** True once a non-looping timer has reached its duration. Always `false` for a looping timer. */
+    expired: boolean;
+}
+/** One timer's serializable state — elapsed resolved at snapshot time, ready to re-anchor on restore. */
+export interface TimerSnapshot {
+    id: string;
+    durationMs: number;
+    direction: TimerDirection;
+    loop: boolean;
+    /** Elapsed milliseconds at the moment of the snapshot. */
+    elapsedMs: number;
+    running: boolean;
+    /** Whether this non-looping timer had already emitted its expiry edge. */
+    fired: boolean;
+}
+/** Serializable state of a whole {@link TimerSet}. */
+export interface TimerSetSnapshot {
+    timers: TimerSnapshot[];
+}
+/** Options for {@link createTimerSet}. */
+export interface TimerSetOptions {
+    /** Injected clock (ms). Default `Date.now`. Inject a sim clock for determinism. */
+    now?: () => number;
+}
+/** Listener notified when a timer newly expires. Receives the timer id. */
+export type TimerExpiryListener = (id: string) => void;
+/**
+ * A named set of countdown / countup timers on an injected clock. Start, pause,
+ * resume, stop, reset, and read timers by free-string id; observe structural
+ * changes with {@link TimerSet.subscribe} and expiry edges with
+ * {@link TimerSet.poll} / {@link TimerSet.onExpire}.
+ */
+export interface TimerSet {
+    /** Start (or replace) a timer by id, running from zero. */
+    start(id: string, options: TimerStartOptions): void;
+    /** Pause a running timer, freezing its elapsed time. No-op if unknown or already paused. */
+    pause(id: string): void;
+    /** Resume a paused timer from where it stopped. No-op if unknown or already running. */
+    resume(id: string): void;
+    /** Halt a timer and reset its elapsed time to zero, keeping it in the set (not running). */
+    stop(id: string): void;
+    /** Restart a timer's elapsed time from zero, preserving its running state. */
+    reset(id: string): void;
+    /** Remove a timer from the set entirely. */
+    remove(id: string): void;
+    /** Pause every running timer (e.g. a global game pause). */
+    pauseAll(): void;
+    /** Resume every paused timer. */
+    resumeAll(): void;
+    /** Whether a timer with this id exists. */
+    has(id: string): boolean;
+    /** Every timer id currently in the set. */
+    ids(): readonly string[];
+    /**
+     * Resolve a timer's current state. Pass `out` to reuse an object and avoid
+     * per-read allocation in a hot HUD loop. Returns `null` for an unknown id.
+     */
+    read(id: string, out?: TimerRead): TimerRead | null;
+    /** Resolve every timer, newest reads. Allocates an array — for per-frame reads prefer {@link TimerSet.read} with `out`. */
+    list(): TimerRead[];
+    /**
+     * Advance expiry detection to the current clock time and return the ids that
+     * newly expired since the last poll (firing {@link TimerSet.onExpire}
+     * listeners for each). Looping timers report once per completed cycle. Call
+     * once per frame/tick to react to finished timers.
+     */
+    poll(): readonly string[];
+    /** Observe structural changes (start/pause/resume/stop/reset/remove/restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Observe expiry edges surfaced by {@link TimerSet.poll}. Returns an unsubscribe fn. */
+    onExpire(listener: TimerExpiryListener): () => void;
+    /** Serializable state for a save. */
+    snapshot(): TimerSetSnapshot;
+    /** Restore from a {@link TimerSetSnapshot}, re-anchoring running timers to the current clock. */
+    restore(snapshot: TimerSetSnapshot): void;
+}
+/**
+ * Create a serializable set of named countdown / countup timers on an injected
+ * clock — one primitive for round timers, respawn clocks, and ability
+ * cooldown/charge. Start/pause/resume/stop/reset timers by free-string id, read
+ * `{ remainingMs, elapsedMs, durationMs, progress01, running, expired }` for a
+ * mm:ss readout or a radial/bar fill, and `poll` for expiry edges. Ids and
+ * labels carry no genre meaning; `snapshot`/`restore` round-trip through a save.
+ *
+ * @capability countdown-timers named countdown/countup timer set on an injected clock — round timers, respawn clocks, ability cooldown/charge; read remaining/elapsed/progress + expiry, snapshot/restore
+ */
+export declare function createTimerSet(options?: TimerSetOptions): TimerSet;

package/dist/time/timerSet.js

@@ -0,0 +1,243 @@
+/**
+ * A serializable set of named countdown / countup timers evaluated against an
+ * injected clock. One primitive covers round timers, respawn clocks, and ability
+ * cooldown/charge — they are the same mechanic (elapsed vs. duration on a clock),
+ * so `id` and any labels are free strings the engine never interprets.
+ *
+ * No hidden interval math: the set stores only accumulated elapsed time plus a
+ * clock anchor while running, and derives every read on demand. `subscribe`
+ * reports structural changes (start/pause/stop/reset); `poll` reports expiry
+ * edges so a game can react (respawn, round end, ability ready). `snapshot` /
+ * `restore` round-trip through a save by resolving elapsed at snapshot time and
+ * re-anchoring on restore, so pause/resume survives serialization.
+ */
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+function rawElapsed(rec, t) {
+    const live = rec.running ? Math.max(0, t - rec.anchor) : 0;
+    return rec.base + live;
+}
+/**
+ * Create a serializable set of named countdown / countup timers on an injected
+ * clock — one primitive for round timers, respawn clocks, and ability
+ * cooldown/charge. Start/pause/resume/stop/reset timers by free-string id, read
+ * `{ remainingMs, elapsedMs, durationMs, progress01, running, expired }` for a
+ * mm:ss readout or a radial/bar fill, and `poll` for expiry edges. Ids and
+ * labels carry no genre meaning; `snapshot`/`restore` round-trip through a save.
+ *
+ * @capability countdown-timers named countdown/countup timer set on an injected clock — round timers, respawn clocks, ability cooldown/charge; read remaining/elapsed/progress + expiry, snapshot/restore
+ */
+export function createTimerSet(options = {}) {
+    const now = options.now ?? Date.now;
+    const timers = new Map();
+    const listeners = new Set();
+    const expiryListeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function completedCycles(rec, t) {
+        if (rec.durationMs <= 0)
+            return rec.loop ? 0 : 1;
+        const raw = rawElapsed(rec, t);
+        if (rec.loop)
+            return Math.floor(raw / rec.durationMs);
+        return raw >= rec.durationMs ? 1 : 0;
+    }
+    function fill(rec, t, out) {
+        const duration = rec.durationMs;
+        const raw = rawElapsed(rec, t);
+        let cycleElapsed;
+        let expired;
+        if (duration <= 0) {
+            cycleElapsed = 0;
+            expired = !rec.loop;
+        }
+        else if (rec.loop) {
+            cycleElapsed = raw % duration;
+            expired = false;
+        }
+        else {
+            cycleElapsed = raw < duration ? raw : duration;
+            expired = raw >= duration;
+        }
+        out.id = rec.id;
+        out.direction = rec.direction;
+        out.durationMs = duration;
+        out.elapsedMs = cycleElapsed;
+        out.remainingMs = duration > 0 ? duration - cycleElapsed : 0;
+        out.progress01 = duration > 0 ? clamp01(cycleElapsed / duration) : 1;
+        out.running = rec.running;
+        out.expired = expired;
+        return out;
+    }
+    function blankRead() {
+        return {
+            id: "",
+            direction: "down",
+            remainingMs: 0,
+            elapsedMs: 0,
+            durationMs: 0,
+            progress01: 0,
+            running: false,
+            expired: false,
+        };
+    }
+    return {
+        start(id, startOptions) {
+            timers.set(id, {
+                id,
+                durationMs: startOptions.durationMs,
+                direction: startOptions.direction ?? "down",
+                loop: startOptions.loop ?? false,
+                base: 0,
+                running: true,
+                anchor: now(),
+                reported: 0,
+            });
+            notify();
+        },
+        pause(id) {
+            const rec = timers.get(id);
+            if (rec === undefined || !rec.running)
+                return;
+            rec.base = rawElapsed(rec, now());
+            rec.running = false;
+            notify();
+        },
+        resume(id) {
+            const rec = timers.get(id);
+            if (rec === undefined || rec.running)
+                return;
+            rec.anchor = now();
+            rec.running = true;
+            notify();
+        },
+        stop(id) {
+            const rec = timers.get(id);
+            if (rec === undefined)
+                return;
+            rec.base = 0;
+            rec.running = false;
+            rec.reported = 0;
+            notify();
+        },
+        reset(id) {
+            const rec = timers.get(id);
+            if (rec === undefined)
+                return;
+            rec.base = 0;
+            rec.anchor = now();
+            rec.reported = 0;
+            notify();
+        },
+        remove(id) {
+            if (timers.delete(id))
+                notify();
+        },
+        pauseAll() {
+            const t = now();
+            let changed = false;
+            for (const rec of timers.values()) {
+                if (rec.running) {
+                    rec.base = rawElapsed(rec, t);
+                    rec.running = false;
+                    changed = true;
+                }
+            }
+            if (changed)
+                notify();
+        },
+        resumeAll() {
+            const t = now();
+            let changed = false;
+            for (const rec of timers.values()) {
+                if (!rec.running) {
+                    rec.anchor = t;
+                    rec.running = true;
+                    changed = true;
+                }
+            }
+            if (changed)
+                notify();
+        },
+        has(id) {
+            return timers.has(id);
+        },
+        ids() {
+            return [...timers.keys()];
+        },
+        read(id, out) {
+            const rec = timers.get(id);
+            if (rec === undefined)
+                return null;
+            return fill(rec, now(), out ?? blankRead());
+        },
+        list() {
+            const t = now();
+            const reads = [];
+            for (const rec of timers.values())
+                reads.push(fill(rec, t, blankRead()));
+            return reads;
+        },
+        poll() {
+            const t = now();
+            const fired = [];
+            for (const rec of timers.values()) {
+                const cycles = completedCycles(rec, t);
+                if (cycles > rec.reported) {
+                    const times = cycles - rec.reported;
+                    rec.reported = cycles;
+                    for (let i = 0; i < times; i += 1) {
+                        fired.push(rec.id);
+                        for (const listener of expiryListeners)
+                            listener(rec.id);
+                    }
+                }
+            }
+            return fired;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        onExpire(listener) {
+            expiryListeners.add(listener);
+            return () => expiryListeners.delete(listener);
+        },
+        snapshot() {
+            const t = now();
+            const out = [];
+            for (const rec of timers.values()) {
+                out.push({
+                    id: rec.id,
+                    durationMs: rec.durationMs,
+                    direction: rec.direction,
+                    loop: rec.loop,
+                    elapsedMs: rawElapsed(rec, t),
+                    running: rec.running,
+                    fired: rec.reported > 0,
+                });
+            }
+            return { timers: out };
+        },
+        restore(snapshot) {
+            timers.clear();
+            const t = now();
+            for (const snap of snapshot.timers) {
+                timers.set(snap.id, {
+                    id: snap.id,
+                    durationMs: snap.durationMs,
+                    direction: snap.direction,
+                    loop: snap.loop,
+                    base: snap.elapsedMs,
+                    running: snap.running,
+                    anchor: t,
+                    reported: snap.fired ? 1 : 0,
+                });
+            }
+            notify();
+        },
+    };
+}

package/dist/ui/accessibility.d.ts

@@ -0,0 +1,51 @@
+/** Colorblind simulation/daltonization modes the engine ships matrices for. */
+export type ColorblindMode = "none" | "protanopia" | "deuteranopia" | "tritanopia" | "grayscale";
+/** Serializable accessibility preferences a game reads to adapt its presentation. */
+export interface AccessibilityState {
+    /** Suppress non-essential motion/animation. */
+    reducedMotion: boolean;
+    /** Boost contrast (stronger borders/backgrounds, less transparency). */
+    highContrast: boolean;
+    /** UI text scale multiplier (`1` = default). See {@link clampTextScale} for bounds. */
+    textScale: number;
+    /** Colorblind filter applied to the presentation. */
+    colorblind: ColorblindMode;
+    /** Show subtitles/captions for dialogue and important audio. */
+    captions: boolean;
+}
+/** The out-of-the-box accessibility state (all assistance off, `textScale` 1). */
+export declare const DEFAULT_ACCESSIBILITY: AccessibilityState;
+/** Minimum UI text scale. */
+export declare const TEXT_SCALE_MIN = 0.75;
+/** Maximum UI text scale. */
+export declare const TEXT_SCALE_MAX = 2;
+/** Clamp a text-scale multiplier into the supported `[TEXT_SCALE_MIN, TEXT_SCALE_MAX]` range. */
+export declare function clampTextScale(scale: number): number;
+/** Return `ms` when motion is allowed, or `reduced` (default 0) when `reducedMotion` is set — the animation-duration gate. */
+export declare function reducedMotionDuration(state: AccessibilityState, ms: number, reduced?: number): number;
+/**
+ * `feColorMatrix` `values` strings for each colorblind mode — simulate how a
+ * viewer with that condition perceives color (and a grayscale mode). `"none"`
+ * maps to `null` (no filter). Consumed by the React `ColorblindFilters` defs.
+ */
+export declare const COLORBLIND_MATRICES: Record<ColorblindMode, string | null>;
+/** Observable, serializable accessibility-preferences store. */
+export interface AccessibilityStore {
+    get(): AccessibilityState;
+    /** Merge a partial update (text scale is clamped); notifies on an actual change. */
+    set(patch: Partial<AccessibilityState>): void;
+    /** Restore defaults. */
+    reset(): void;
+    subscribe(listener: () => void): () => void;
+    snapshot(): AccessibilityState;
+    restore(snapshot: Partial<AccessibilityState>): void;
+}
+/**
+ * Serializable, observable store of accessibility preferences (reduced motion,
+ * high contrast, text scale, colorblind mode, captions). Genre-agnostic plumbing
+ * like input rebinding — a game binds these to its settings UI and adapts its
+ * presentation; `snapshot`/`restore` round-trip through a save or settings blob.
+ *
+ * @capability accessibility-store serializable, observable accessibility preferences (reduced motion, high contrast, text scale, colorblind mode, captions) a game binds to its settings and presentation
+ */
+export declare function createAccessibilityStore(initial?: Partial<AccessibilityState>): AccessibilityStore;

package/dist/ui/accessibility.js

@@ -0,0 +1,83 @@
+/** The out-of-the-box accessibility state (all assistance off, `textScale` 1). */
+export const DEFAULT_ACCESSIBILITY = {
+    reducedMotion: false,
+    highContrast: false,
+    textScale: 1,
+    colorblind: "none",
+    captions: false,
+};
+/** Minimum UI text scale. */
+export const TEXT_SCALE_MIN = 0.75;
+/** Maximum UI text scale. */
+export const TEXT_SCALE_MAX = 2;
+/** Clamp a text-scale multiplier into the supported `[TEXT_SCALE_MIN, TEXT_SCALE_MAX]` range. */
+export function clampTextScale(scale) {
+    if (Number.isNaN(scale))
+        return 1;
+    return Math.max(TEXT_SCALE_MIN, Math.min(TEXT_SCALE_MAX, scale));
+}
+/** Return `ms` when motion is allowed, or `reduced` (default 0) when `reducedMotion` is set — the animation-duration gate. */
+export function reducedMotionDuration(state, ms, reduced = 0) {
+    return state.reducedMotion ? reduced : ms;
+}
+/**
+ * `feColorMatrix` `values` strings for each colorblind mode — simulate how a
+ * viewer with that condition perceives color (and a grayscale mode). `"none"`
+ * maps to `null` (no filter). Consumed by the React `ColorblindFilters` defs.
+ */
+export const COLORBLIND_MATRICES = {
+    none: null,
+    protanopia: "0.567 0.433 0 0 0  0.558 0.442 0 0 0  0 0.242 0.758 0 0  0 0 0 1 0",
+    deuteranopia: "0.625 0.375 0 0 0  0.7 0.3 0 0 0  0 0.3 0.7 0 0  0 0 0 1 0",
+    tritanopia: "0.95 0.05 0 0 0  0 0.433 0.567 0 0  0 0.475 0.525 0 0  0 0 0 1 0",
+    grayscale: "0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0.299 0.587 0.114 0 0  0 0 0 1 0",
+};
+/**
+ * Serializable, observable store of accessibility preferences (reduced motion,
+ * high contrast, text scale, colorblind mode, captions). Genre-agnostic plumbing
+ * like input rebinding — a game binds these to its settings UI and adapts its
+ * presentation; `snapshot`/`restore` round-trip through a save or settings blob.
+ *
+ * @capability accessibility-store serializable, observable accessibility preferences (reduced motion, high contrast, text scale, colorblind mode, captions) a game binds to its settings and presentation
+ */
+export function createAccessibilityStore(initial = {}) {
+    let state = normalize({ ...DEFAULT_ACCESSIBILITY, ...initial });
+    const listeners = new Set();
+    function normalize(next) {
+        return { ...next, textScale: clampTextScale(next.textScale) };
+    }
+    function commit(next) {
+        const normalized = normalize(next);
+        if (normalized.reducedMotion === state.reducedMotion &&
+            normalized.highContrast === state.highContrast &&
+            normalized.textScale === state.textScale &&
+            normalized.colorblind === state.colorblind &&
+            normalized.captions === state.captions) {
+            return;
+        }
+        state = normalized;
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        get() {
+            return state;
+        },
+        set(patch) {
+            commit({ ...state, ...patch });
+        },
+        reset() {
+            commit({ ...DEFAULT_ACCESSIBILITY });
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return state;
+        },
+        restore(snapshot) {
+            commit({ ...DEFAULT_ACCESSIBILITY, ...snapshot });
+        },
+    };
+}

package/dist/ui/coachMarks.d.ts

@@ -0,0 +1,99 @@
+/** Where a coach-mark callout sits relative to its anchor (or `"center"` for an unanchored callout). */
+export type CoachMarkPlacement = "top" | "bottom" | "left" | "right" | "center";
+/** One onboarding hint: an ordered, optionally-anchored, optionally-gated callout. */
+export interface CoachMarkStep {
+    /** Stable id — also the key tracked in the persisted "seen" set. */
+    id: string;
+    title: string;
+    body?: string;
+    /**
+     * CSS selector (or a logical key the presenter resolves) for the element the
+     * callout points at. Omitted → the step renders as a centered callout.
+     */
+    anchor?: string;
+    /** Preferred side of the anchor. Default `"bottom"` when anchored, `"center"` otherwise. */
+    placement?: CoachMarkPlacement;
+    /**
+     * Serializable trigger id. While set, the step stays hidden until that id is
+     * in the sequence's satisfied set (see {@link CoachMarkSequence.satisfy}).
+     * Kept data-first — a string, not a function — so a whole sequence serializes.
+     */
+    condition?: string;
+}
+/** The active step plus its position, returned by {@link CoachMarkSequence.current}. */
+export interface CoachMarkView {
+    /** The step to render. */
+    step: CoachMarkStep;
+    /** 0-based position of this step within the full ordered list. */
+    index: number;
+    /** Total number of steps in the sequence. */
+    total: number;
+    /** Un-seen steps left, including this one (for an "N of M" style counter). */
+    remaining: number;
+}
+/** Serializable persisted state — the seen set (with timestamps) and satisfied triggers. */
+export interface CoachMarkSnapshot {
+    /** Ids of steps that have been advanced past, dismissed, or skipped. */
+    seen: readonly string[];
+    /** When each seen id was first marked, from the injected clock. */
+    seenAt: Readonly<Record<string, number>>;
+    /** Currently-satisfied trigger ids (gate state). */
+    satisfied: readonly string[];
+}
+/** Options for {@link createCoachMarkSequence}. */
+export interface CoachMarkSequenceOptions {
+    /** Ordered hint steps. */
+    steps: readonly CoachMarkStep[];
+    /** Injected clock (ms) used to timestamp when a step is marked seen. Default `Date.now`. */
+    now?: () => number;
+    /** Ids of steps already seen (e.g. restored from a save) so they never re-show. */
+    seen?: Iterable<string>;
+    /** Trigger ids already satisfied when the sequence starts. */
+    satisfied?: Iterable<string>;
+}
+/** An ordered, observable, serializable onboarding coach-mark run. */
+export interface CoachMarkSequence {
+    /** The configured steps, in order. */
+    readonly steps: readonly CoachMarkStep[];
+    /** First un-seen step whose condition (if any) is satisfied, or `null` when none is eligible. */
+    current(): CoachMarkView | null;
+    /** Mark the current step seen and return the next eligible step (or `null`). */
+    advance(): CoachMarkView | null;
+    /** Alias of {@link CoachMarkSequence.advance}. */
+    next(): CoachMarkView | null;
+    /** Mark a specific step seen so it never re-shows. */
+    dismiss(id: string): void;
+    /** Mark every step seen — "skip tour". */
+    skipAll(): void;
+    /** Add trigger ids to the satisfied set, un-gating any steps waiting on them. */
+    satisfy(...triggerIds: string[]): void;
+    /** Replace the satisfied trigger set wholesale (e.g. re-derived from game state). */
+    setSatisfied(triggerIds: Iterable<string>): void;
+    /** Whether the given trigger id is currently satisfied. */
+    isTriggerSatisfied(triggerId: string): boolean;
+    /** Whether a step id has been seen. */
+    isSeen(id: string): boolean;
+    /** Clock time a step was first seen, or `undefined` if not yet seen. */
+    seenAt(id: string): number | undefined;
+    /** True once every step has been seen. */
+    isComplete(): boolean;
+    /** How many steps remain un-seen (whether or not currently gated). */
+    remaining(): number;
+    /** Observe changes (advance, dismiss, satisfy, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): CoachMarkSnapshot;
+    /** Restore from a {@link CoachMarkSnapshot}. */
+    restore(snapshot: CoachMarkSnapshot): void;
+}
+/**
+ * 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 declare function createCoachMarkSequence(options: CoachMarkSequenceOptions): CoachMarkSequence;