@jgengine/core 0.14.0 → 0.15.0-next.0

package/dist/game/achievements.d.ts

@@ -0,0 +1,80 @@
+/** Definition of one achievement. Content-agnostic — the game supplies names, targets, and icons. */
+export interface AchievementDef {
+    id: string;
+    name: string;
+    description?: string;
+    /**
+     * Counter goal: the achievement unlocks when accumulated progress reaches it.
+     * Omit for a boolean achievement unlocked directly with `unlock(id)`.
+     */
+    target?: number;
+    /** Hide the name/description in UI until unlocked (a spoiler-guarded achievement). */
+    secret?: boolean;
+    /** Optional score weight (gamerscore-style), summed by {@link AchievementTracker.score}. */
+    points?: number;
+    category?: string;
+    /** Optional icon id / glyph the game renders; the engine never picks art. */
+    icon?: string;
+}
+/** A definition plus its live unlock/progress state — what UI renders. */
+export interface AchievementView extends AchievementDef {
+    unlocked: boolean;
+    /** Unlock time from the injected clock, or null while locked. */
+    unlockedAt: number | null;
+    /** Current counter value (0 for untouched or boolean achievements). */
+    progress: number;
+    /** `progress / target` in `[0, 1]`; 1 when unlocked or when there is no target. */
+    fraction: number;
+}
+/** Emitted the instant an achievement unlocks — wire to a toast, feed, or sound. */
+export interface AchievementUnlock {
+    id: string;
+    def: AchievementDef;
+    at: number;
+}
+/** Whole serializable state of a tracker — drop into a save blob. */
+export interface AchievementSnapshot {
+    /** Achievement id → unlock timestamp. */
+    unlocked: Record<string, number>;
+    /** Achievement id → counter progress. */
+    counters: Record<string, number>;
+}
+/** Live achievement state over a fixed definition set — drives progress, unlocks, score, and a UI view list. */
+export interface AchievementTracker {
+    /** Add `amount` (default 1) to a counter achievement; unlocks on reaching `target`. Returns the unlock if it just crossed, else null. */
+    progress(id: string, amount?: number): AchievementUnlock | null;
+    /** Set a counter achievement's absolute value; unlocks on reaching `target`. Returns the unlock if it just crossed, else null. */
+    setProgress(id: string, value: number): AchievementUnlock | null;
+    /** Unlock directly (boolean or counter). Returns the unlock, or null if unknown or already unlocked. */
+    unlock(id: string): AchievementUnlock | null;
+    isUnlocked(id: string): boolean;
+    get(id: string): AchievementView | null;
+    /** All achievements with live state, in definition order. Stable identity between changes (safe for `useSyncExternalStore`). */
+    list(): readonly AchievementView[];
+    unlocked(): readonly AchievementView[];
+    /** Total `points` across unlocked achievements. */
+    score(): number;
+    /** Fraction of achievements unlocked, `[0, 1]`. */
+    completion(): number;
+    subscribe(listener: () => void): () => void;
+    snapshot(): AchievementSnapshot;
+    restore(snapshot: AchievementSnapshot): void;
+}
+/** Options for {@link createAchievementTracker}. */
+export interface AchievementTrackerOptions {
+    defs: readonly AchievementDef[];
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Fires whenever an achievement unlocks — the seam for toasts, kill-feed lines, sounds, or telemetry. */
+    onUnlock?: (unlock: AchievementUnlock) => void;
+}
+/**
+ * Tracks achievement/trophy unlocks over caller-driven events — counter goals
+ * (`progress`/`setProgress`) and boolean flags (`unlock`) — with score,
+ * completion, an `onUnlock` seam, and serializable `snapshot`/`restore`. State
+ * is plain data; the view list keeps a stable identity between changes so React
+ * can read it through `useSyncExternalStore` without re-projecting every frame.
+ *
+ * @capability achievements track achievement/trophy unlocks over counter goals and boolean flags, with score, completion, an onUnlock seam, and serializable snapshot/restore
+ */
+export declare function createAchievementTracker(options: AchievementTrackerOptions): AchievementTracker;

package/dist/game/achievements.js

@@ -0,0 +1,124 @@
+/**
+ * Tracks achievement/trophy unlocks over caller-driven events — counter goals
+ * (`progress`/`setProgress`) and boolean flags (`unlock`) — with score,
+ * completion, an `onUnlock` seam, and serializable `snapshot`/`restore`. State
+ * is plain data; the view list keeps a stable identity between changes so React
+ * can read it through `useSyncExternalStore` without re-projecting every frame.
+ *
+ * @capability achievements track achievement/trophy unlocks over counter goals and boolean flags, with score, completion, an onUnlock seam, and serializable snapshot/restore
+ */
+export function createAchievementTracker(options) {
+    const now = options.now ?? Date.now;
+    const order = [];
+    const defs = new Map();
+    for (const def of options.defs) {
+        if (defs.has(def.id))
+            continue;
+        defs.set(def.id, def);
+        order.push(def.id);
+    }
+    const unlockedAt = new Map();
+    const counters = new Map();
+    const listeners = new Set();
+    let cache = null;
+    function notify() {
+        cache = null;
+        for (const listener of listeners)
+            listener();
+    }
+    function viewOf(id) {
+        const def = defs.get(id);
+        const at = unlockedAt.get(id) ?? null;
+        const progress = counters.get(id) ?? 0;
+        const fraction = at !== null ? 1 : def.target !== undefined && def.target > 0 ? Math.min(1, progress / def.target) : 0;
+        return { ...def, unlocked: at !== null, unlockedAt: at, progress, fraction };
+    }
+    function doUnlock(id) {
+        const at = now();
+        unlockedAt.set(id, at);
+        const def = defs.get(id);
+        if (def.target !== undefined)
+            counters.set(id, def.target);
+        const unlock = { id, def, at };
+        options.onUnlock?.(unlock);
+        return unlock;
+    }
+    function applyCounter(id, value) {
+        const def = defs.get(id);
+        if (def === undefined || def.target === undefined)
+            return null;
+        if (unlockedAt.has(id))
+            return null;
+        const clamped = Math.max(0, Math.min(def.target, value));
+        counters.set(id, clamped);
+        if (clamped >= def.target) {
+            const unlock = doUnlock(id);
+            notify();
+            return unlock;
+        }
+        notify();
+        return null;
+    }
+    const tracker = {
+        progress(id, amount = 1) {
+            return applyCounter(id, (counters.get(id) ?? 0) + amount);
+        },
+        setProgress(id, value) {
+            return applyCounter(id, value);
+        },
+        unlock(id) {
+            if (!defs.has(id) || unlockedAt.has(id))
+                return null;
+            const unlock = doUnlock(id);
+            notify();
+            return unlock;
+        },
+        isUnlocked(id) {
+            return unlockedAt.has(id);
+        },
+        get(id) {
+            return defs.has(id) ? viewOf(id) : null;
+        },
+        list() {
+            if (cache === null)
+                cache = order.map(viewOf);
+            return cache;
+        },
+        unlocked() {
+            return tracker.list().filter((view) => view.unlocked);
+        },
+        score() {
+            let total = 0;
+            for (const id of unlockedAt.keys())
+                total += defs.get(id)?.points ?? 0;
+            return total;
+        },
+        completion() {
+            return order.length === 0 ? 0 : unlockedAt.size / order.length;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return {
+                unlocked: Object.fromEntries(unlockedAt),
+                counters: Object.fromEntries(counters),
+            };
+        },
+        restore(snapshot) {
+            unlockedAt.clear();
+            counters.clear();
+            for (const [id, at] of Object.entries(snapshot.counters)) {
+                if (defs.has(id))
+                    counters.set(id, at);
+            }
+            for (const [id, at] of Object.entries(snapshot.unlocked)) {
+                if (defs.has(id))
+                    unlockedAt.set(id, at);
+            }
+            notify();
+        },
+    };
+    return tracker;
+}

package/dist/game/cameraConfig.d.ts

@@ -198,6 +198,13 @@ export interface ChaseCameraConfig {
         minSpeed?: number;
         response?: number;
     };
+    /**
+     * Exponential response (`1-exp(-response*dt)`) the chase yaw follows the target's facing with
+     * (#1370). The default (5) arcs the boom smoothly behind a body whose facing flips from a strafe
+     * or direction change instead of teleporting it to the far side; `Infinity` restores the legacy
+     * rigid follow (yaw exactly equals body facing every frame).
+     */
+    yawResponse?: number;
     /** Which view to mount. Default "chase". */
     view?: ChaseView;
     /** Local offset for cockpit/hood/rear seats (relative to the vehicle, +z forward). */

package/dist/game/codex.d.ts

@@ -0,0 +1,60 @@
+/** A codex/bestiary/lorebook entry the game defines. Discovery state is tracked separately. */
+export interface CodexEntryDef<TMeta = unknown> {
+    id: string;
+    name: string;
+    category?: string;
+    description?: string;
+    /** Longer lore for a detail pane. */
+    lore?: string;
+    /** Icon/image id or glyph the game renders; the engine never picks art. */
+    icon?: string;
+    /** Hide name/description/lore until discovered (a spoiler-guarded entry). */
+    secret?: boolean;
+    meta?: TMeta;
+}
+/** A definition plus its discovery state — what UI renders. */
+export interface CodexEntryView<TMeta = unknown> extends CodexEntryDef<TMeta> {
+    discovered: boolean;
+    /** Discovery time from the injected clock, or null. */
+    discoveredAt: number | null;
+}
+/** Serializable discovery state — a save blob. */
+export interface CodexSnapshot {
+    /** Entry id → discovery timestamp. */
+    discovered: Record<string, number>;
+}
+/** A codex/bestiary of defined entries with per-player discovery tracking. */
+export interface Codex<TMeta = unknown> {
+    /** Mark an entry discovered; returns the newly-discovered view, or null if unknown or already discovered. */
+    discover(id: string): CodexEntryView<TMeta> | null;
+    isDiscovered(id: string): boolean;
+    get(id: string): CodexEntryView<TMeta> | null;
+    /** All entries (optionally filtered to a category) with discovery state, in definition order. Stable identity between changes. */
+    list(category?: string): readonly CodexEntryView<TMeta>[];
+    categories(): readonly string[];
+    discoveredCount(): number;
+    total(): number;
+    /** Fraction discovered, `[0, 1]`. */
+    completion(): number;
+    subscribe(listener: () => void): () => void;
+    snapshot(): CodexSnapshot;
+    restore(snapshot: CodexSnapshot): void;
+}
+/** Options for {@link createCodex}. */
+export interface CodexOptions<TMeta = unknown> {
+    entries: readonly CodexEntryDef<TMeta>[];
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+    /** Fires when an entry is discovered for the first time — wire to a toast/notification. */
+    onDiscover?: (entry: CodexEntryView<TMeta>) => void;
+}
+/**
+ * A codex / bestiary / lorebook: a fixed set of defined entries plus per-player
+ * discovery tracking, with categories, secret masking, completion, an
+ * `onDiscover` seam, and serializable `snapshot`/`restore`. The view `list()`
+ * keeps a stable identity between changes so React reads it through
+ * `useSyncExternalStore` without re-projecting each frame.
+ *
+ * @capability codex codex/bestiary/lorebook of defined entries with discovery tracking, categories, secret masking, completion, an onDiscover seam, and serializable state
+ */
+export declare function createCodex<TMeta = unknown>(options: CodexOptions<TMeta>): Codex<TMeta>;

package/dist/game/codex.js

@@ -0,0 +1,89 @@
+/**
+ * A codex / bestiary / lorebook: a fixed set of defined entries plus per-player
+ * discovery tracking, with categories, secret masking, completion, an
+ * `onDiscover` seam, and serializable `snapshot`/`restore`. The view `list()`
+ * keeps a stable identity between changes so React reads it through
+ * `useSyncExternalStore` without re-projecting each frame.
+ *
+ * @capability codex codex/bestiary/lorebook of defined entries with discovery tracking, categories, secret masking, completion, an onDiscover seam, and serializable state
+ */
+export function createCodex(options) {
+    const now = options.now ?? Date.now;
+    const order = [];
+    const defs = new Map();
+    for (const def of options.entries) {
+        if (defs.has(def.id))
+            continue;
+        defs.set(def.id, def);
+        order.push(def.id);
+    }
+    const discoveredAt = new Map();
+    const listeners = new Set();
+    let cache = null;
+    function notify() {
+        cache = null;
+        for (const listener of listeners)
+            listener();
+    }
+    function viewOf(id) {
+        const def = defs.get(id);
+        const at = discoveredAt.get(id) ?? null;
+        return { ...def, discovered: at !== null, discoveredAt: at };
+    }
+    const codex = {
+        discover(id) {
+            if (!defs.has(id) || discoveredAt.has(id))
+                return null;
+            discoveredAt.set(id, now());
+            const view = viewOf(id);
+            options.onDiscover?.(view);
+            notify();
+            return view;
+        },
+        isDiscovered(id) {
+            return discoveredAt.has(id);
+        },
+        get(id) {
+            return defs.has(id) ? viewOf(id) : null;
+        },
+        list(category) {
+            if (cache === null)
+                cache = order.map(viewOf);
+            return category === undefined ? cache : cache.filter((view) => view.category === category);
+        },
+        categories() {
+            const seen = [];
+            for (const id of order) {
+                const category = defs.get(id).category;
+                if (category !== undefined && !seen.includes(category))
+                    seen.push(category);
+            }
+            return seen;
+        },
+        discoveredCount() {
+            return discoveredAt.size;
+        },
+        total() {
+            return order.length;
+        },
+        completion() {
+            return order.length === 0 ? 0 : discoveredAt.size / order.length;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { discovered: Object.fromEntries(discoveredAt) };
+        },
+        restore(snapshot) {
+            discoveredAt.clear();
+            for (const [id, at] of Object.entries(snapshot.discovered)) {
+                if (defs.has(id))
+                    discoveredAt.set(id, at);
+            }
+            notify();
+        },
+    };
+    return codex;
+}

package/dist/game/credits.d.ts

@@ -0,0 +1,36 @@
+/** One credited line — a person, a studio, an asset pack, a tool. */
+export interface CreditsEntry {
+    /** Who or what is credited. */
+    label: string;
+    /** Free-string qualifier shown beside the label — a role, a license, a pack title. */
+    detail?: string;
+    /** Where the work came from. Never fetched; the view decides whether to link it. */
+    href?: string;
+}
+/** A titled group of entries — "Design", "Music", "3D Assets". */
+export interface CreditsSection {
+    heading: string;
+    entries: readonly CreditsEntry[];
+}
+/** Everything a credits screen shows. `notice` is the closing line (a license summary, a thank-you). */
+export interface CreditsDocument {
+    title?: string;
+    sections: readonly CreditsSection[];
+    notice?: string;
+}
+/**
+ * Merges credit documents into one, concatenating same-heading sections in first-seen order and
+ * dropping exact duplicate entries. Use it to fold generated credits (asset packs, dependencies)
+ * into the game's hand-authored ones without curating the overlap by hand.
+ *
+ * @capability merge-credits fold generated and hand-authored credit documents into one, deduped by entry
+ */
+export declare function mergeCredits(...documents: readonly (CreditsDocument | null | undefined)[]): CreditsDocument;
+/**
+ * Groups entries into sections by a caller-supplied key — the shape most generated credits arrive
+ * in (a flat list of things used, grouped by license, provider, or role). Section order follows
+ * first appearance, so a stable input gives a stable screen.
+ *
+ * @capability group-credits turn a flat list of credited things into ordered credit sections
+ */
+export declare function groupCredits<T>(items: readonly T[], heading: (item: T) => string, entry: (item: T) => CreditsEntry): CreditsSection[];

package/dist/game/defineGame.d.ts

@@ -15,7 +15,7 @@ import type { TimeConfig } from "../time/simClock.js";
 import type { WorldFeature } from "../world/features.js";
 /** Tunes offline whole-world save (`defineGameDefinition({ persist })`). Offline games already autosave to `localStorage` by default — pass this only to tune it (or `persist: false` to opt out). Defaults: continuous `autosave` to `localStorage`, one slot, no version. */
 export interface PersistConfig {
-    /** `"autosave"` (default) writes on a debounce after any change; `"manual"` writes only on `ctx.game.save.checkpoint()` (save points / quest triggers). */
+    /** `"autosave"` (default) writes on a trailing timer while the world changes — at most once per `autosaveMs`, so a never-idle world (AI, physics, day/night) still persists; `"manual"` writes only on `ctx.game.save.checkpoint()` (save points / quest triggers). */
     mode?: RuntimeSaveMode;
     /** `"local"` (default) persists to `localStorage`; `"memory"` keeps saves in-session only (tests, "no persistence" mode). */
     storage?: "local" | "memory";
@@ -140,6 +140,20 @@ export interface LifecycleConfig<TState = unknown> {
         restart?: string;
     };
 }
+/**
+ * How a game declares its run-phase story to {@link defineGameDefinition}. Every game states this
+ * explicitly so the shell never has to guess — a silent game used to default to `"playing"`, which
+ * painted the touch dock over title/menu/results screens (#1337, Vice Isle #1329).
+ *
+ * - A {@link LifecycleConfig} — the game moves through menu/playing/paused/ended run states; the
+ *   runtime owns the command glue and phase sync.
+ * - `"always-live"` — an explicit, truthful declaration that the game has **no** menu/pause/end
+ *   screens and runs live from boot. Runtime behaviour is identical to declaring no lifecycle at all
+ *   (no phase sync, no start/restart commands), but the intent is now *stated*, not implied by
+ *   silence. Games that instead drive phases by hand call {@link setGamePhase} directly and leave
+ *   this unset.
+ */
+export type GameLifecycle<TState = unknown> = LifecycleConfig<TState> | "always-live";
 /** Fully-resolved game description produced by {@link defineGameDefinition} — assets, scene, and opted-in subsystems. */
 export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
     name: string;
@@ -177,7 +191,12 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     persist?: boolean | PersistConfig;
     ui?: unknown;
     loop?: GameLoop<GameContext>;
-    /** Declarative start/restart run lifecycle — see {@link LifecycleConfig}. Omitted games keep hand-rolling their own commands. */
+    /**
+     * Resolved run lifecycle — see {@link LifecycleConfig}. The config boundary also accepts the
+     * `"always-live"` sentinel ({@link GameLifecycle}); {@link defineGameDefinition} resolves that to
+     * `undefined` here, so a resolved definition only ever carries a real {@link LifecycleConfig} or
+     * nothing.
+     */
     lifecycle?: LifecycleConfig;
     /**
      * Host-side per-viewer replication policy — private-state and area-of-interest projection over the
@@ -188,8 +207,14 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     replication?: ReplicationPolicy;
 }
 /** Input to {@link defineGameDefinition} — a `GameDefinition` with `scene` derived and `assets` optional. */
-export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & {
+export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets" | "lifecycle"> & {
     assets?: AssetCatalog<TAssetRef>;
+    /**
+     * The game's run-phase story — a {@link LifecycleConfig} or the `"always-live"` sentinel. Every
+     * game must state one (or drive phases by hand via {@link setGamePhase}); `check-game-shape`
+     * enforces it. See {@link GameLifecycle}.
+     */
+    lifecycle?: GameLifecycle;
 };
 /**
  * Host-level constructor for a bare `GameDefinition`: fills in `scene` and default `assets`, validates

package/dist/game/defineGame.js

@@ -43,11 +43,16 @@ export function defineGameDefinition(config) {
     // A place world carries the laws of that place: its physics resolves over the game-level default,
     // so every consumer of definition.physics (movement, combat, shell) sees the active world's laws.
     const physics = resolveWorldPhysics(config.world, config.physics);
+    // `"always-live"` is an explicit "no lifecycle sync" declaration — resolve the sentinel to
+    // `undefined` so every downstream consumer only ever sees a real LifecycleConfig or nothing,
+    // exactly as before the sentinel existed. The statement was for the gate, not the runtime.
+    const lifecycle = config.lifecycle === "always-live" ? undefined : config.lifecycle;
     return {
         ...config,
         ...(physics === undefined ? {} : { physics }),
         features,
         loop,
+        lifecycle,
         scene: createEntityStore(),
         assets: config.assets ?? createAssetCatalog(),
     };

package/dist/game/dialogueGraph.d.ts

@@ -0,0 +1,116 @@
+/**
+ * One selectable response on a conversation node — the text a player clicks and the
+ * node it advances to. `kind` is a free style tag the presenter interprets; the model
+ * never reads it (no genre baked in).
+ */
+export interface DialogueGraphChoice {
+    /** Player-facing choice text. */
+    text: string;
+    /** Id of the node this choice advances to. Omitted / `null` ends the conversation. */
+    to?: string | null;
+    /** Free-string style/category tag the game styles on (never interpreted by the model). */
+    kind?: string;
+}
+/**
+ * One conversation node: who is speaking, the line they say, and the branches out of it.
+ * `speaker`/`speakerKind`/`portrait` are opaque display data — the model never interprets them.
+ */
+export interface DialogueGraphNode {
+    /** Stable node id — choices point at it via {@link DialogueGraphChoice.to}. */
+    id: string;
+    /** Free-string speaker name shown in the view. Omitted → an unattributed line. */
+    speaker?: string;
+    /** Free-string speaker style tag (the game maps it to a portrait frame / name color). */
+    speakerKind?: string;
+    /** Opaque portrait key or URL the view renders in its portrait slot. */
+    portrait?: string;
+    /** The line this node speaks. */
+    text: string;
+    /** Branching responses. Empty / omitted → a terminal node the player can close. */
+    choices?: readonly DialogueGraphChoice[];
+}
+/** A serializable branching conversation: a start node id and the nodes it can reach. */
+export interface DialogueGraph {
+    /** Id of the node the conversation opens on. */
+    start: string;
+    /** Every node in the conversation. */
+    nodes: readonly DialogueGraphNode[];
+}
+/**
+ * The render-ready snapshot of a conversation at one node — everything a view needs to
+ * draw speaker, line, and choice buttons, with no traversal logic in the component.
+ */
+export interface DialogueGraphView {
+    /** Current node id. */
+    nodeId: string;
+    /** Speaker name to display, or `undefined` for an unattributed line. */
+    speaker?: string;
+    /** Speaker style tag the game skins on. */
+    speakerKind?: string;
+    /** Portrait key/URL for the portrait slot, or `undefined` when none. */
+    portrait?: string;
+    /** The current line text. */
+    text: string;
+    /** Branching responses at this node (empty at a terminal node). */
+    choices: readonly DialogueGraphChoice[];
+    /** True when this node has no onward choices — the conversation can be closed. */
+    done: boolean;
+}
+/** Serializable run state — the current node id and the ids already visited. */
+export interface DialogueGraphSnapshot {
+    /** Node the run is currently sitting on. */
+    nodeId: string;
+    /** Node ids visited so far, in order (a start node is the first). */
+    visited: readonly string[];
+}
+/** Options for {@link createDialogueRun}. */
+export interface DialogueRunOptions {
+    /** Node id to open on. Default: the graph's `start`. */
+    startAt?: string;
+    /** Visited node ids to seed (e.g. restored from a save). */
+    visited?: Iterable<string>;
+}
+/** An observable walk through a {@link DialogueGraph}: current view, choose to advance, serialize. */
+export interface DialogueRun {
+    /** The graph being walked. */
+    readonly graph: DialogueGraph;
+    /** Render-ready view at the current node, or `null` if the current id is unknown. */
+    current(): DialogueGraphView | null;
+    /** The current node's id. */
+    currentId(): string;
+    /** Advance via the choice at `index` on the current node; returns the new view (or `null`). */
+    choose(index: number): DialogueGraphView | null;
+    /** Jump straight to a node id (bypassing choices); returns its view (or `null`). */
+    goTo(nodeId: string): DialogueGraphView | null;
+    /** Re-open on the start node, clearing visited history. */
+    reset(): DialogueGraphView | null;
+    /** Whether the current node is terminal (no onward choices). */
+    isDone(): boolean;
+    /** Whether a node id has been visited this run. */
+    hasVisited(nodeId: string): boolean;
+    /** Observe advance / jump / reset. Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable run state for a save. */
+    snapshot(): DialogueGraphSnapshot;
+    /** Restore from a {@link DialogueGraphSnapshot}. */
+    restore(snapshot: DialogueGraphSnapshot): void;
+}
+/**
+ * Project a {@link DialogueGraph} node id to its render-ready {@link DialogueGraphView} —
+ * the pure "current view" selector a stateless renderer reads (speaker, line, choices,
+ * done). Returns `null` when the id is not in the graph. No traversal or mutation.
+ *
+ * @capability dialogue-graph-view select a conversation node's render-ready view (speaker, line, branching choices) from a serializable dialogue graph
+ */
+export declare function selectDialogueView(graph: DialogueGraph, nodeId: string): DialogueGraphView | null;
+/**
+ * Walk a branching {@link DialogueGraph}: hold the current node, expose its render-ready
+ * view, and advance by choosing one of the current node's responses (each choice names the
+ * node it leads to; a choice with no `to` ends the conversation). Purely a serializable
+ * model — a React host renders `current()` and calls `choose(index)` — so no game
+ * re-implements node lookup, choice-to-node traversal, or "am I at the end" bookkeeping.
+ * `snapshot`/`restore` round-trip the run through a save.
+ *
+ * @capability dialogue-run walk a serializable branching dialogue graph — current node view, choose-to-advance traversal, visited history, snapshot/restore
+ */
+export declare function createDialogueRun(graph: DialogueGraph, options?: DialogueRunOptions): DialogueRun;