@yagejs-addons/dialogue 0.1.0 → 0.2.0

package/dist/DialogueController-Cs5IUc-u.d.ts

@@ -0,0 +1,1204 @@
+import { Scene, Component } from '@yagejs/core';
+import { M as MarkerToken, P as ParsedText, b as VarMap, D as DialogueScript, N as NodeId, q as DialogueNode, w as SpeakerId, d as SpeakerDef, V as VarValue, g as Command, h as CommandContext, a as VariableStorage, c as DialogueFunction, k as CommandHandler, r as DialoguePlayOptions, p as DialogueHandle } from './types-DSbBSlh7.js';
+import { InputManager } from '@yagejs/input';
+
+/**
+ * LineReveal — the headless typewriter clock. Given a {@link ParsedText} (markup
+ * already parsed into runs + an ordered {@link RevealToken} stream), a base
+ * `charsPerSec`, a per-line speed multiplier, and `update(dt)` ticks, it advances
+ * a reveal cursor in **graphemes** (the unit `markup.ts` counts and the renderer
+ * splits glyphs by), drains the tokens IN SOURCE ORDER (a `pause` holds, a
+ * `marker` fires a {@link RevealBeat}), applies per-run `[speed]`, and fires
+ * completion **exactly once** per line.
+ *
+ * It is renderer-free on purpose: a DOM-overlay or per-word presenter can drive
+ * the same reveal logic and map the grapheme cursor onto its own rendering,
+ * without pulling the renderer in. The default `DialogueTextView` consumes it
+ * and keeps only the SplitText concerns — the code-unit→glyph prefix mapping and
+ * per-glyph style fan-out — which LineReveal deliberately does NOT own.
+ *
+ * What it owns: the reveal cursor, the `ParsedText.tokens` drain (one ordered
+ * index over pauses + markers), the hold-to-fast-forward multiplier, the per-line
+ * and per-run (`RunStyle.speed`) speeds, and the fired-once completion. What it
+ * does NOT own: anything that touches a glyph, a texture, or a layout. Counts are
+ * graphemes throughout — it reads the pre-computed grapheme counts off
+ * `ParsedText` (`length`, `TextRun.graphemeCount`, a token's `atChar`) and never
+ * re-segments.
+ */
+
+/**
+ * A reveal-time beat the clock emits as the cursor advances: a per-grapheme
+ * `tick` (one per revealed grapheme — raw, including whitespace; the host
+ * filters) and a `marker` when the cursor reaches a {@link MarkerToken}'s
+ * offset. `viaSkip` is true when the marker was drained by {@link
+ * LineReveal.complete} (a skip / fast-forward) rather than reached during normal
+ * typing, so a host can suppress a loud one-shot that only fired because of a
+ * skip click. Ticks are NOT emitted on a skip (replaying dozens at once would
+ * machine-gun).
+ */
+type RevealBeat = {
+    readonly kind: "tick";
+    readonly index: number;
+} | {
+    readonly kind: "marker";
+    readonly marker: MarkerToken;
+    readonly viaSkip: boolean;
+};
+declare class LineReveal {
+    private readonly charsPerSec;
+    private parsed;
+    /** Reveal cursor, in graphemes (fractional while typing). */
+    private cursor;
+    private pauseTimer;
+    /** Next un-drained token in `parsed.tokens` (one ordered cursor over pauses +
+     *  markers — source order is drain order). */
+    private tokenIdx;
+    /** Graphemes already ticked (so each grapheme ticks exactly once). */
+    private tickCount;
+    /** Hold-to-fast-forward rate (1 = normal). */
+    private speedMul;
+    /** Per-line `say.speed` multiplier (1 = base). */
+    private lineSpeed;
+    private done;
+    private completed;
+    /** Fired exactly once when the line finishes revealing. The consuming view
+     *  wires this to the session-owned reveal listener (NOT a public mutable
+     *  field a game could clobber). */
+    private onComplete;
+    /** Per-grapheme ticks + inline markers, wired by the consuming view to the
+     *  session-owned beat listener (like {@link onComplete}, never a public field). */
+    private onBeat;
+    /** @param charsPerSec base reveal rate (graphemes/second), scaled by the
+     *   hold, per-line, and per-run multipliers. */
+    constructor(charsPerSec: number);
+    /**
+     * Register the completion listener — fires once per line, the moment the
+     * cursor reaches the end (or synchronously from {@link begin} for an empty
+     * line, or from {@link complete}). Pass `undefined` to clear.
+     */
+    setCompletionListener(listener: (() => void) | undefined): void;
+    /**
+     * Register the reveal-beat listener — per-grapheme ticks and inline markers,
+     * in char order, the moment the cursor reaches each. Session-owned (set once,
+     * like {@link setCompletionListener}); pass `undefined` to clear.
+     */
+    setBeatListener(listener: ((beat: RevealBeat) => void) | undefined): void;
+    /**
+     * Start revealing a new line. Resets the cursor, pauses, and the hold
+     * multiplier (a stale fast-forward must not leak into the next line — an
+     * active binding re-asserts it on its next poll). An **empty** line
+     * (`parsed.length === 0`) is complete immediately and fires the completion
+     * listener synchronously, matching the no-typewriter contract.
+     */
+    begin(parsed: ParsedText, lineSpeed?: number): void;
+    /** Hold-to-fast-forward multiplier (1 = normal, e.g. 4 while skip is held). */
+    setSpeedMultiplier(m: number): void;
+    /** Advance the reveal cursor by `dt` (ms). Honours armed pauses and per-run
+     *  speed; fires completion once the cursor reaches the end. No-op after the
+     *  line is done or before the first {@link begin}. */
+    update(dt: number): void;
+    /** Reveal everything now (skip-to-end on a click/tap). Drains any not-yet-fired
+     *  markers in order so their consequences still happen (`viaSkip=true` lets a
+     *  host suppress a loud one-shot) and blows straight through pending pauses (a
+     *  skip ignores holds), but DISCARDS pending ticks — replaying dozens of
+     *  typewriter blips at once would machine-gun. Fires completion. */
+    complete(): void;
+    /** Revealed grapheme count (fractional while typing). The view floors this to
+     *  map onto its glyph prefix table. */
+    get revealed(): number;
+    /** True once the line is fully revealed (also true for an empty line). */
+    isComplete(): boolean;
+    /** True while glyphs are still appearing. */
+    isRevealing(): boolean;
+    private finish;
+    /**
+     * Drain tokens whose offset the cursor has reached, IN SOURCE ORDER. A `marker`
+     * emits a beat; a `pause` arms the hold, clamps the cursor to its offset, and
+     * STOPS the drain for this frame (a one-frame advance can overshoot the offset,
+     * so the clamp keeps glyphs past the beat from popping in early, and a later
+     * token waits until the hold resumes). `viaSkip` (from {@link complete}) tags
+     * drained markers and blows straight through pauses without holding. Monotonic
+     * `tokenIdx` → each token is handled exactly once.
+     */
+    private drainTokens;
+    /** Emit a `tick` for each grapheme newly revealed since the last call (raw —
+     *  no whitespace test; the host filters). Multiple in order on a large-dt
+     *  frame; `tickCount` is monotonic so none repeat. */
+    private emitTicks;
+    /** Reveal speed multiplier for whichever run the cursor currently sits in. */
+    private runSpeedAt;
+}
+
+/**
+ * `defineScript` — the TS-first authoring path. An identity function at
+ * runtime; at compile time it captures the script's declared variable value
+ * types (from their {@link DialogueScript.declare} defaults), branding the
+ * returned script so `play()` can hand back a typed {@link DialogueHandle}.
+ *
+ * JSON scripts (a plain {@link DialogueScript} literal) get the exact same
+ * runtime rules via load-/play-time validation — the brand is a pure
+ * compile-time convenience and never exists at runtime. Inference stays shallow:
+ * it lives here and at the `play()` boundary, never threaded through the
+ * session/controller internals.
+ *
+ *     const script = defineScript({
+ *       id: "shop", start: "n",
+ *       declare: { greeted: false, gold: 0 },   // greeted: boolean, gold: number
+ *       nodes: { n: { id: "n", steps: [{ kind: "end" }] } },
+ *     });
+ *     const handle = controller.play(script);    // content-only
+ *     handle.setVar("greeted", true);            // ^ key is typed to keyof declare
+ */
+
+declare const VARS_BRAND: unique symbol;
+/** Phantom carrier of a script's captured variable types. Never present at
+ *  runtime — only `defineScript`'s cast asserts it. */
+interface ScriptTypes<V extends VarMap> {
+    readonly [VARS_BRAND]: V;
+}
+/** A {@link DialogueScript} branded with its declared variable types. */
+type TypedScript<V extends VarMap> = DialogueScript & ScriptTypes<V>;
+/** Widen a declared default's literal type to its base — a variable declared
+ *  `false` is a boolean (accepts `true`), `0` is a number, `"x"` is a string. A
+ *  `null` default is untyped, so it widens to the full {@link VarValue} union. */
+type Widen<T extends VarValue> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : VarValue;
+type WidenVars<V extends VarMap> = {
+    [K in keyof V]: Widen<V[K]>;
+};
+declare function defineScript<V extends VarMap = Record<never, never>>(script: Omit<DialogueScript, "declare"> & {
+    readonly id: string;
+    readonly start?: NodeId;
+    readonly nodes: Record<NodeId, DialogueNode>;
+    readonly speakers?: Record<SpeakerId, SpeakerDef>;
+    readonly declare?: V;
+}): TypedScript<WidenVars<V>>;
+/** Declared variable types captured for a script (the loose {@link VarMap} for a
+ *  plain JSON script). Drives the typed {@link DialogueHandle} `play()` returns. */
+type VarsOf<S> = S extends ScriptTypes<infer V> ? V : VarMap;
+
+/**
+ * i18n seam. The runtime never reaches for a translation library directly —
+ * it asks an {@link I18nAdapter}. Ship the identity adapter (literal text +
+ * `{param}` interpolation) by default; wrap i18next / FormatJS / your own
+ * string table in a ~10-line adapter to localise without touching the engine.
+ */
+interface I18nAdapter {
+    /** Current locale tag, e.g. "en", "fr-CA". Informational. */
+    readonly locale: string;
+    /**
+     * Resolve a string. `key` is the translation key when the script provides
+     * one; `fallback` is the authored literal text. `params` feed interpolation.
+     * Implementations should return localised markup-bearing text.
+     */
+    t(key: string | undefined, fallback: string, params?: Readonly<Record<string, unknown>>): string;
+}
+/**
+ * No-op adapter: returns the authored literal, interpolating `{name}` tokens
+ * from `params`. This is what runs until a real i18n backend is plugged in.
+ */
+declare class IdentityI18n implements I18nAdapter {
+    readonly locale: string;
+    constructor(locale?: string);
+    t(_key: string | undefined, fallback: string, params?: Readonly<Record<string, unknown>>): string;
+}
+/** Replace `{token}` with `params.token`; leaves unknown tokens untouched.
+ *  Own-property check only — `{constructor}`/`{toString}` must not stringify
+ *  inherited Object.prototype members. */
+declare function interpolate(text: string, params: Readonly<Record<string, unknown>>): string;
+
+/**
+ * Extensible presentation channels — the open-ended companion to the built-in
+ * typed trio (text / choices / avatar / chrome). A host *registers* one of these
+ * on a running conversation to add behaviour the addon doesn't own (voice-over,
+ * a shop reacting to a `buy` command, a camera shake, a history recorder).
+ *
+ * Pixi-free, like the rest of `core/`: a channel that needs the scene also
+ * implements {@link Mountable} (re-exported from the root barrel), but this
+ * interface itself imposes no engine dependency.
+ */
+
+/**
+ * An optional-hook channel the host registers via
+ * {@link DialogueController.addChannel} / {@link DialogueSession.addChannel} (or
+ * the controller's `channels` ctor array). **Every method is optional** — a
+ * one-method observer (a shop reacting to `command`, a history recorder reacting
+ * to `revealComplete`) implements just what it needs and ignores the rest.
+ *
+ * The {@link DialogueSession} fans its cross-cutting stream out to every
+ * registered channel at the same sites it drives the trio — `present`,
+ * `command`, `clear`, `setVisible`, `setPaused`, `completeReveal`, `update` —
+ * each call wrapped so a throwing channel is routed to the session's `onError`
+ * and never breaks the conversation. The trio stays trusted/unwrapped.
+ *
+ * Coupling is deliberately one-directional: the ONLY value a channel hands back
+ * is {@link isRevealComplete}, a boolean the session folds into the auto-advance
+ * gate. Everything else is **consequences-out** — a channel changes game state
+ * through {@link CommandContext.setVar} (write-only) and reads it back through
+ * the host-held `DialogueHandle.getVars()`, never through the session.
+ */
+interface DialogueExtraChannel {
+    /**
+     * A say line was presented — called right after the text channel's `present`
+     * and before the line's `show` commands. Read `line.voice` / `line.meta`
+     * here. NOT called for choice prompts (only say lines carry a voice/reveal).
+     */
+    present?(line: PresentedLine): void;
+    /**
+     * The current say line finished its typewriter reveal (right after the host's
+     * `onRevealCompleted`). For a history / analytics recorder that commits a line
+     * once it's fully shown. Carries the same {@link PresentedLine} as `present`.
+     */
+    revealComplete?(line: PresentedLine): void;
+    /**
+     * A non-built-in command fired — mirrors the host `onCommand`, with the same
+     * exclusion (never `set`, which the runner owns). A shop channel reacts to a
+     * `buy` command here. (A mid-line face change is an `[expression=…/]` reveal
+     * marker on {@link revealBeat}, not a command.)
+     */
+    command?(command: Command, ctx: CommandContext): void;
+    /** The conversation cleared (a `stop()` or its natural end) — reset any
+     *  per-conversation state. Distinct from {@link dispose} (final teardown). */
+    clear?(): void;
+    /** The whole dialogue UI was shown / hidden (the host `setHidden` lever). */
+    setVisible?(visible: boolean): void;
+    /** The conversation was paused / resumed — freezes player-facing time. A voice
+     *  channel pauses its clip here. */
+    setPaused?(paused: boolean): void;
+    /** The player skipped the typewriter (advance-while-revealing) or fast-forwarded
+     *  the section (skip) — cut a clip, drain a queued effect. */
+    completeReveal?(): void;
+    /**
+     * A reveal beat fired during the current say line's typewriter — a
+     * per-grapheme `tick` or an inline `[name k=v/]` `marker`. A typewriter-SFX
+     * channel blips on ticks; a CameraEffects channel reacts to a `[shake/]`
+     * marker. Fires once per grapheme (hundreds per line), so keep it cheap.
+     * Markers also reach the host via `DialogueRevealMarkerEvent` and the avatar
+     * channel; this is the registered-channel path to the same stream.
+     */
+    revealBeat?(beat: RevealBeat): void;
+    /** Per-frame tick. Already gated by the session pause (not called while
+     *  paused), so a dt-driven timer freezes for free. */
+    update?(dt: number): void;
+    /** Final teardown — called by the {@link DialogueSession.addChannel} disposer
+     *  and the controller's `onDestroy`. Release anything {@link clear} doesn't. */
+    dispose?(): void;
+    /**
+     * Auto-advance gate. While this returns `false` the session's auto-advance
+     * clock is frozen (a manual advance is **always** allowed). Omit it to never
+     * gate — a pure observer. The session **arms** its clock on the TEXT reveal
+     * but **counts down** only once text AND every registered gater report
+     * complete, so a line auto-advances at `max(clipEnd, revealEnd)` with no
+     * duration plumbing. Must be a cheap, total boolean read (never throws — it is
+     * polled every frame and, unlike the fanned-out hooks, is not wrapped).
+     */
+    isRevealComplete?(): boolean;
+}
+
+/**
+ * DialogueSession — the headless orchestrator. It binds a {@link DialogueRunner}
+ * to a set of presentation *channels* (text / choices / avatar / chrome) and
+ * sequences a conversation: resolve i18n + markup, drive the typewriter, gate on
+ * reveal-completion, run the auto-advance clock, and book-keep choice selection.
+ *
+ * It is engine-agnostic (zero `@yagejs` imports): the channels are semantic
+ * interfaces — `present(line)`, `highlight(i)`, `setSpeaking(bool)` — with no
+ * pixels, no input, and no world entities. A YAGE host (`DialogueController`)
+ * supplies concrete channels, an `InputBinding`, and pumps `update(dt)`; a
+ * headless test can supply stubs. The public API is input-agnostic
+ * (`advance / moveSelection / confirm / choose / setFastForward`) so any device
+ * binding maps onto it.
+ *
+ * Observation is via callbacks (`onLine`, `onChoiceMade`, `onCommand`, …) so a
+ * host can forward to engine events or a history recorder without the Session
+ * knowing about either.
+ */
+
+/** One previewed line: speaker name + plain (markup-stripped) text. */
+interface PreviewedLine {
+    readonly speaker?: string | undefined;
+    readonly text: string;
+}
+/** Resolved speaker descriptor on a presented line (for nameplates / anchoring). */
+interface SpeakerView {
+    readonly id: string;
+    readonly name?: string | undefined;
+    readonly color?: number | undefined;
+}
+/** A fully-resolved line (i18n + markup already applied) handed to presenters. */
+interface PresentedLine {
+    /** Who's speaking (if anyone) — lets world presenters anchor to their actor. */
+    readonly speaker?: SpeakerView | undefined;
+    readonly text: ParsedText;
+    /** Per-line reveal-speed multiplier (`say.speed`, default 1). */
+    readonly speed: number;
+    /** Opaque preset name for per-line layout/variant (presenter interprets). */
+    readonly view?: string | undefined;
+    readonly meta?: Readonly<Record<string, unknown>> | undefined;
+    /** Voice-clip id (audio handler interprets; reveal may sync to it). */
+    readonly voice?: string | undefined;
+}
+/** One choice row, resolved to a display label. Position = array index. */
+interface PresentedChoice {
+    readonly label: string;
+    readonly meta?: Readonly<Record<string, unknown>> | undefined;
+    /** True for a visible-but-disabled row (its condition failed and its
+     *  `presentation` is `"disabled"`). Presenters render it greyed and
+     *  non-selectable; the Session's nav/confirm skip it. */
+    readonly disabled?: boolean | undefined;
+    /** i18n-resolved reason for a {@link disabled} row, shown beside it where the
+     *  layout allows (e.g. "Requires the rusty key"). */
+    readonly disabledReason?: string | undefined;
+}
+/**
+ * Body-text channel. Owns reveal timing (the Session only learns *that* a line
+ * finished, via the reveal listener, never *when* a glyph appears). An
+ * accessibility / no-typewriter presenter is
+ * `present(){ draw(); this.revealListener?.() }`.
+ */
+interface TextChannel {
+    present(line: PresentedLine): void;
+    /** Reveal everything immediately (skip-to-end). */
+    completeReveal(): void;
+    isRevealComplete(): boolean;
+    isRevealing(): boolean;
+    /** Hold-to-fast-forward rate flag (1 = normal). */
+    setSpeedMultiplier(multiplier: number): void;
+    /**
+     * Show or hide the body text **without** disturbing reveal progress — a
+     * cutscene can hide mid-typewriter and show again to resume mid-line. Purely
+     * visual: the reveal cursor, timers, and the laid-out line are untouched.
+     */
+    setVisible(visible: boolean): void;
+    update(dt: number): void;
+    clear(): void;
+    /**
+     * Register the reveal-completed listener. The Session owns this seam — it
+     * registers its handler once in the ctor — so a game can't clobber the wiring
+     * by assigning a public field. Pass `undefined` to clear.
+     */
+    setRevealListener(listener: (() => void) | undefined): void;
+    /**
+     * Register the reveal-beat listener — per-grapheme typewriter ticks and inline
+     * `[name k=v/]` markers, in char order, as the reveal cursor reaches each.
+     * Session-owned like {@link setRevealListener} (registered once in the ctor);
+     * pass `undefined` to clear. A no-typewriter presenter that reveals instantly
+     * may omit beats; the bundled view forwards the headless {@link LineReveal}
+     * clock's beats.
+     */
+    setBeatListener(listener: ((beat: RevealBeat) => void) | undefined): void;
+}
+/** Per-choice presentation context, so a choice list can route/anchor the same
+ *  way lines do (box list vs a bubble over `speaker`'s actor) and optionally
+ *  render the prompt itself. */
+interface ChoiceContext {
+    readonly view?: string | undefined;
+    readonly speaker?: SpeakerView | undefined;
+    /** The (resolved + parsed) prompt, made available so a presenter can render
+     *  it itself (see {@link ChoiceChannel.ownsPrompt}). Empty when no prompt. */
+    readonly prompt?: ParsedText | undefined;
+    /** The choice step's opaque `meta` bag, passed straight through. A custom
+     *  presenter reads it to render extras the model doesn't own — e.g. the
+     *  timed-choice recipe's `{ timeoutMs }` for a countdown. */
+    readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+/** Choice channel. Selection nav lives in the Session; pointer/touch commits
+ *  come back through `onChoiceChosen(position)`. `context` carries the choice's
+ *  view/speaker/prompt so a composite presenter can route (box vs bubble). */
+interface ChoiceChannel {
+    present(choices: readonly PresentedChoice[], context?: ChoiceContext): void;
+    highlight(position: number): void;
+    /** Show or hide the choice list without clearing it — state-preserving,
+     *  so the selection and laid-out rows survive a hide/show round-trip. */
+    setVisible(visible: boolean): void;
+    clear(): void;
+    onChoiceChosen?: (position: number) => void;
+    /**
+     * If true for this `context`, the presenter draws the prompt itself (e.g. a
+     * self-contained bubble panel), so the Session suppresses the chrome + body-
+     * text prompt. Default false → the chrome/text show the prompt (box body).
+     */
+    ownsPrompt?(context?: ChoiceContext): boolean;
+}
+/** Avatar channel — who's talking + their expression + talk state. */
+interface AvatarChannel {
+    setSpeaker(speaker: SpeakerDef | undefined): void;
+    setExpression(expression: string | undefined): void;
+    setSpeaking(speaking: boolean): void;
+    /**
+     * Optional per-line hook (mirrors {@link ChromeChannel.present}) so an avatar
+     * can be **line-driven**: read the line's `meta` (e.g. `portrait` / `side` /
+     * `presence`) to pick an image/side/presence, beyond what `setSpeaker` carries.
+     * The Session calls it on each say/choice line alongside `setSpeaker`, and
+     * with `undefined` when the conversation clears (stop/end). A reflowing in-box
+     * avatar registers a text inset here so the body text reflows around it. Most
+     * avatars (portrait, scene-figure) omit it.
+     */
+    present?(line: PresentedLine | undefined): void;
+    /**
+     * Optional inline-marker hook (sibling to {@link present} / {@link setVisible}).
+     * The Session fans every `[name k=v/]` reveal marker here so an avatar can
+     * interpret the ones it owns — the bundled portrait/scene presenters read
+     * `[expression=…/]` and call their own `setExpression`. The Session name-matches
+     * NOTHING; an avatar ignores markers it doesn't recognize. `viaSkip` markers
+     * (drained by a skip) arrive here too — the avatar collapses to the last one.
+     */
+    marker?(marker: MarkerToken): void;
+    /** Optional visibility gate — a portrait hides during a cutscene; a
+     *  scene-figure avatar (a world NPC the game owns) omits it and stays put. */
+    setVisible?(visible: boolean): void;
+    update(dt: number): void;
+}
+/** Chrome channel — frame / nameplate / continue caret (everything but body
+ *  text and choices). `present?` lets a chrome react to per-line variants;
+ *  `present(undefined)` means "no line — clear the chrome's content". */
+interface ChromeChannel {
+    /** Set the speaker name, or `undefined` for **no name** — NOT a covert
+     *  hide-all; visibility is governed solely by {@link setVisible}. */
+    setNameplate(name: string | undefined, color?: number): void;
+    setContinueVisible(visible: boolean): void;
+    /**
+     * Show or hide the whole chrome — the honest visibility verb the Session
+     * drives (a composite restores its active variant on show). State-preserving.
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * React to a per-line variant (`meta.chrome`, `meta.position`). Called
+     * **before** {@link TextChannel.present} for the same line, so a composite
+     * selects its active variant and a layout owner commits the frame the text
+     * then reads. `present(undefined)` means "no line — clear the chrome's content".
+     */
+    present?(line: PresentedLine | undefined): void;
+    update(dt: number): void;
+}
+/**
+ * The presentation channels a {@link DialogueSession} drives. Writing a custom
+ * presenter (a DOM overlay, a ui-react chrome) means implementing these — so the
+ * **call-order contract** the Session guarantees is documented here, on the
+ * interfaces themselves:
+ *
+ * Per say line, the Session calls (in this order):
+ *  1. `chrome.setNameplate(name)` / `chrome.setContinueVisible(false)`
+ *  2. `avatar.setSpeaker` / `setExpression` / `setSpeaking`, then `avatar.present?(line)`
+ *  3. `chrome.present?(line)` — **before** the text, so a composite picks the
+ *     active variant first and a layout owner commits the frame the text reads
+ *  4. `text.present(line)` — render + start revealing
+ *  5. (each channel's `setVisible(shown)` reflects the host-hidden lever)
+ *
+ * Then, exactly once, when the line finishes revealing, the text channel fires
+ * the listener registered via {@link TextChannel.setRevealListener} (the
+ * Session owns that seam — never a public field). For an **empty** line the
+ * completion fires synchronously inside `text.present`.
+ *
+ * Per choice the order mirrors a line (chrome/avatar/text for the optional
+ * prompt) and then `choices.present(options, context)`. If a presenter
+ * {@link ChoiceChannel.ownsPrompt | owns the prompt}, the Session clears the
+ * chrome + body instead of step 3/4.
+ *
+ * `setBox`/geometry is always applied **before** `present` for that line (a
+ * presenter that lays out off a region reads the committed region in `present`).
+ */
+interface DialogueChannels {
+    readonly text: TextChannel;
+    readonly choices: ChoiceChannel;
+    readonly avatar?: AvatarChannel | undefined;
+    readonly chrome?: ChromeChannel | undefined;
+}
+interface DialogueSessionOptions {
+    readonly i18n?: I18nAdapter | undefined;
+    /** Hold-to-fast-forward multiplier. Default 4. */
+    readonly skipMultiplier?: number | undefined;
+    /**
+     * The variable storage installed for every `play()`. Persists across
+     * plays. Omit for a zero-config {@link MemoryVariableStorage}; supply your own
+     * or {@link compose} several to bridge game state. A per-`play()`
+     * `overrides.storage` replaces it for that conversation.
+     */
+    readonly storage?: VariableStorage | undefined;
+    /** Argument-capable read functions (`has_item("key")`) for conditions/`set`
+     *  expressions. Per-`play()` `overrides.functions` merge on top. */
+    readonly functions?: Readonly<Record<string, DialogueFunction>> | undefined;
+    /** Command handlers (`type` → handler). Per-`play()` `overrides.commands`
+     *  merge on top (call site wins). */
+    readonly commands?: Readonly<Record<string, CommandHandler>> | undefined;
+    /** Catch-all for command types with no explicit handler. */
+    readonly fallbackCommand?: CommandHandler | undefined;
+    /** Non-fatal runtime diagnostics (e.g. a `set` to a read-only `cells`
+     *  accessor that was ignored). The controller routes these to the engine
+     *  logger; a bare session may handle or drop them. */
+    readonly onError?: ((message: string, error: unknown) => void) | undefined;
+    readonly onStarted?: (e: {
+        scriptId: string;
+    }) => void;
+    /** Plain (markup-stripped) line text — for logs / a11y / history. */
+    readonly onLine?: (e: {
+        speaker?: string | undefined;
+        text: string;
+    }) => void;
+    readonly onChoiceShown?: (e: {
+        options: readonly string[];
+    }) => void;
+    readonly onChoiceMade?: (e: {
+        index: number;
+        text: string;
+    }) => void;
+    /**
+     * Observation hook fired for every non-built-in command (`set` is runner-owned
+     * and never reaches it) — the host forwards it to {@link DialogueCommandEvent}.
+     * The actual *handling* (and any `blocking` await) is the binding's `commands`
+     * map / `fallbackCommand`, not this; this returns nothing.
+     */
+    readonly onCommand?: (command: Command, ctx: CommandContext) => void;
+    readonly onEnded?: (e: {
+        scriptId: string;
+    }) => void;
+    /** A line finished its typewriter reveal — the "typing finished" hook
+     *  (audio blip, etc.). Plain (markup-stripped) text, like {@link onLine}. */
+    readonly onRevealCompleted?: (e: {
+        speaker?: string | undefined;
+        text: string;
+    }) => void;
+    /**
+     * Per-grapheme typewriter tick — a direct CALLBACK only (NOT forwarded to an
+     * entity event; it fires hundreds of times per line). `index` is the 0-based
+     * grapheme index just revealed, raw (whitespace included — the host filters if
+     * it only wants a blip on visible glyphs). Wire a typewriter SFX here. Not
+     * fired on a skip / fast-forward (pending ticks are discarded).
+     */
+    readonly onRevealTick?: ((index: number) => void) | undefined;
+    /**
+     * An inline `[name k=v/]` marker reached its char offset during reveal — the
+     * host forwards it to {@link DialogueRevealMarkerEvent}. `viaSkip` is true when
+     * a skip/complete drained it (a host can suppress a loud one-shot that only
+     * fired because the player skipped). The Session name-matches NO marker: the
+     * avatar channel interprets `[expression=…/]` itself; every other name flows
+     * opaquely to the host / registered channels.
+     */
+    readonly onRevealMarker?: (marker: MarkerToken, viaSkip: boolean) => void;
+    /** The choice cursor moved — keyboard nav AND pointer hover both funnel here
+     *  `index` is the resolved option index, `text` its plain label. */
+    readonly onSelectionChanged?: (e: {
+        index: number;
+        text: string;
+    }) => void;
+    /** The player skipped the current section — for skip-used analytics. */
+    readonly onSkipUsed?: (e: {
+        scriptId: string;
+    }) => void;
+    /** A line auto-advanced via the auto-advance clock — distinct from a
+     *  manual advance so a game can tell them apart. */
+    readonly onAutoAdvance?: (e: {
+        scriptId: string;
+    }) => void;
+}
+declare class DialogueSession {
+    private readonly channels;
+    private readonly opts;
+    private readonly i18n;
+    private readonly skipMul;
+    /** Controller-installed environment (persists across plays); per-`play()`
+     *  overrides are layered on top into the resolved fields below. */
+    private readonly defaultStorage;
+    private readonly defaultFunctions;
+    private readonly defaultCommands;
+    private readonly defaultFallback;
+    private storage;
+    private functions;
+    private commands;
+    private fallbackCommand;
+    private runner;
+    private script;
+    private mode;
+    private scriptId;
+    private saying;
+    private autoTimer;
+    /** Default auto-advance delay (ms) applied to lines without their own
+     *  `autoAdvanceMs`. `null` = off (manual advance). Set via {@link setAutoAdvance}. */
+    private autoAdvanceDefault;
+    private resolved;
+    private selected;
+    /** Count of in-flight blocking line-command batches (show/afterReveal/advance).
+     *  Input is gated while > 0. An ownership counter (not a shared boolean) so an
+     *  overlapping batch resolving — e.g. the afterReveal batch finishing while a
+     *  long blocking `show` command is still awaited — can't drop a gate it
+     *  doesn't own. */
+    private blockedCount;
+    /** True between an advance request and the runner stepping off the line —
+     *  guards against a second advance double-firing `advance`-timed commands. */
+    private advancing;
+    /** True once the current line's `advance`-timed commands have fired, so a
+     *  second advance() while the runner is still stepping (e.g. awaiting a
+     *  blocking command step) can't re-fire them against the stale line. */
+    private advanceFired;
+    /** True once the current line's `afterReveal`-timed commands have fired
+     *  (normally via handleRevealComplete; skip() fires them early when the line
+     *  hasn't finished revealing). */
+    private afterRevealFired;
+    /** Latched by the first confirm() until the runner produces its next state
+     *  (handleSay/handleChoice/handleEnd), so mashing confirm while the runner
+     *  awaits the option's blocking commands can't emit duplicate onChoiceMade
+     *  events (`mode` stays "choosing" for that whole window). */
+    private confirming;
+    /** Bumped by every stop()/play(). A suspended async continuation from a prior
+     *  conversation captures this and bails on resume if it changed, so it can't
+     *  drive (advance / show the caret on) the runner of a *new* conversation. */
+    private generation;
+    /** `setHidden` — visual only; gates every channel's `setVisible`. Survives
+     *  `stop()`/`play()` (a host that hides for a cutscene and forgets to unhide
+     *  gets what it asked for) — so it is deliberately NOT reset by `stop()`. */
+    private hidden;
+    /** `setPaused` — freezes the update loop AND the input-agnostic API. State is
+     *  left fully intact (no generation bump); also host-level, survives replays. */
+    private paused;
+    /** Whether the chrome / body text are part of the CURRENT choice's layout
+     *  (false when a self-contained bubble panel owns the prompt) — remembered so
+     *  {@link applyVisibility} can recompute after a hide toggle mid-choice. */
+    private choiceShowsChrome;
+    private choiceShowsBody;
+    /** Plain (speaker, text) of the line on screen — for the reveal-completed
+     *  event, which fires after `present` has discarded the resolved string. */
+    private currentLine;
+    /** The full {@link PresentedLine} on screen — handed to an extra channel's
+     *  `revealComplete` (the session discards the local `line` after present). */
+    private currentPresented;
+    /** Host-registered extra channels (Voice / Shop / CameraEffects / History).
+     *  The session fans its cross-cutting stream to these alongside the typed trio
+     *  and folds their `isRevealComplete()` into the auto-advance gate. */
+    private readonly extras;
+    constructor(channels: DialogueChannels, opts?: DialogueSessionOptions);
+    /**
+     * Begin a conversation. `play(script)` is **content-only** — the storage,
+     * functions, and commands are installed on the session; `overrides` layers
+     * per-conversation specifics on top (a scoped `storage`, extra `functions` /
+     * `commands`). Declared defaults seed into the storage **only if absent**
+     * (game-linked values win); variables persist across plays. Returns a
+     * generation-stamped {@link DialogueHandle} for live `setVar` / `getVars`.
+     */
+    play<S extends DialogueScript>(rawScript: S, overrides?: DialoguePlayOptions): DialogueHandle<VarsOf<S>>;
+    isActive(): boolean;
+    isChoosing(): boolean;
+    /**
+     * Register an extra channel (Voice / Shop / CameraEffects / History) — the
+     * open-ended companion to the built-in trio. It receives the cross-cutting
+     * stream (`present` / `command` / `clear` / `setVisible` / `setPaused` /
+     * `completeReveal` / `update`) and can gate auto-advance via
+     * `isRevealComplete()`. Returns a disposer that unregisters **and** disposes
+     * it. On register the channel catches up the current `setVisible` / `setPaused`
+     * lever state ONLY — no content replay (replaying `present` would re-trigger a
+     * voice clip). Safe to call mid-conversation.
+     */
+    addChannel(ch: DialogueExtraChannel): () => void;
+    /**
+     * Hide or show the whole dialogue UI — purely visual, state-preserving.
+     * Drives every channel's `setVisible`; the conversation keeps running
+     * underneath (reveal, timers, cursor intact). Host-level and **persistent**:
+     * it survives `stop()` and the next `play()`, so a cutscene that hides and
+     * forgets to unhide stays hidden — call `setHidden(false)` to restore.
+     */
+    setHidden(hidden: boolean): void;
+    /** True while the UI is hidden via {@link setHidden}. */
+    isHidden(): boolean;
+    /**
+     * Freeze or resume the conversation — `update()` no-ops (reveal,
+     * auto-advance clock, caret blink, avatar anim all freeze since they are
+     * dt-driven) and the input-agnostic API (`advance`/`confirm`/`choose`/
+     * `moveSelection`/`selectAt`/`skip`) no-ops. State is left fully intact: no
+     * generation bump, and `lineBlocked`/`advancing`/`autoTimer` survive. It does
+     * NOT block host-driven writes (`handle.setVar` / `ctx.setVar` / storage) —
+     * only player-facing time + input freeze. Host-level and persistent like hide.
+     */
+    setPaused(paused: boolean): void;
+    /** True while the conversation is frozen via {@link setPaused}. */
+    isPaused(): boolean;
+    /**
+     * Push the current desired visibility to every channel: a channel shows when
+     * it has content for the current mode AND the host hasn't hidden the UI. The
+     * single visibility authority — `setHidden` and every line/choice transition
+     * route through here, so the host-hidden lever composes cleanly with per-line
+     * content and a custom chrome (which may not implement the optional `present`)
+     * is still reliably hidden by the explicit `setVisible(false)`.
+     */
+    private applyVisibility;
+    /** Clear every presentation channel's content — text, choices, chrome
+     *  (nameplate + caret + line), the avatar, and the registered extras. The
+     *  shared teardown for {@link stop} and the ended state; it touches no session
+     *  bookkeeping or visibility (the caller resets its own state, then
+     *  {@link goIdle} reasserts visibility). */
+    private clearAllChannels;
+    /** Drop to a quiescent presentation state (`mode` "idle" or "ended"): reset the
+     *  per-line/choice bookkeeping, clear every channel, and reassert visibility
+     *  (idle/ended → nothing shown, honestly via each channel's `setVisible`,
+     *  preserving the host-hidden lever). The caller owns any further reset —
+     *  {@link stop} also abandons the runner + timing latches. */
+    private goIdle;
+    /** Abandon the current conversation and reset to idle (clears all visuals).
+     *  Useful for ambient/eavesdrop dialogue that should stop when out of range. */
+    stop(): void;
+    update(dt: number): void;
+    /** True while any blocking line-command batch is awaited (input is gated). */
+    private get lineBlocked();
+    /**
+     * The auto-advance gate: the text reveal AND every registered extra channel
+     * that *gates* (implements `isRevealComplete`) report complete. The clock is
+     * armed on the text reveal alone (see `handleRevealComplete`/`setAutoAdvance`)
+     * but only counts down once this is true — so a voice clip outlasting the
+     * typewriter holds the line for `max(clipEnd, revealEnd)` with no duration
+     * plumbing. A channel without the method never gates (a pure observer).
+     */
+    private allRevealsComplete;
+    /**
+     * The storage read view for `{token}` interpolation at *this* present-time.
+     * Materialized per evaluation so an earlier command's `set` shows up on a
+     * later line; already-shown lines never re-render.
+     */
+    private readView;
+    /** Primary action. Saying → reveal-all if typing, else next line. Choosing → confirm. */
+    advance(): void;
+    /** Fire any `advance`-timed line commands, then step the runner off the line.
+     *  `advancing` is held for the whole turn so a second advance can't re-fire
+     *  the (possibly non-blocking) `advance` commands before the runner steps. */
+    private advanceLine;
+    /**
+     * Fast-forward the current section: run intervening commands (in skip mode)
+     * without presenting, stopping at the next choice or the end. No-op unless a
+     * line is showing.
+     */
+    skip(): void;
+    /**
+     * Fire the *displayed* line's not-yet-fired batches in skip mode — the runner
+     * fires every skipped line's commands for world reconstruction, so dropping
+     * the current line's `afterReveal`/`advance` batches would diverge from
+     * normal play — then fast-forward the runner.
+     */
+    private skipLine;
+    /**
+     * Side-effect-free lookahead: the lines a node would show along its linear
+     * path — following `goto` and conditional `command` jumps using the *current*
+     * variable snapshot — stopping at the first choice or the end. Runs no
+     * commands and mutates nothing. For a "skip with a summary" affordance.
+     */
+    preview(nodeId: string, limit?: number): PreviewedLine[];
+    /** Move the choice cursor by `delta`, skipping disabled rows and wrapping.
+     *  No-op outside a choice, and a zero `delta` is a no-op (no cursor move, no
+     *  event). A move that steps over disabled rows fires exactly one
+     *  selection-changed event, for the row it lands on. */
+    moveSelection(delta: number): void;
+    /** Highlight a choice by absolute position (e.g. pointer hover). No wrap;
+     *  a disabled row is skipped (the cursor stays put). */
+    selectAt(position: number): void;
+    /** The next enabled choice position from `from` in direction `dir` (±1),
+     *  wrapping. Returns `from` when no other enabled row exists (so a single
+     *  enabled option among disabled ones never moves). */
+    private nextEnabled;
+    /** Fire onSelectionChanged for the currently-highlighted choice (keyboard nav
+     *  and pointer hover both land here — one canonical selection event). */
+    private emitSelectionChanged;
+    /** Commit the highlighted choice. */
+    confirm(): void;
+    /** Commit by original option index (e.g. a direct pointer hit, or the
+     *  timed-choice recipe firing its default). Refuses an unknown or disabled
+     *  option. */
+    choose(optionIndex: number): void;
+    /** Commit by display position (a pointer hit on a row). The position-keyed
+     *  counterpart to {@link choose}; refuses an out-of-range or disabled row.
+     *  Used by the pointer binding and the presenter pointer-commit seam. */
+    confirmAt(position: number): void;
+    /**
+     * The single choice-commit authority: every commit path routes here after
+     * translating its argument to a display position. It guards (paused / not
+     * choosing / already confirming / a missing or disabled row), latches against a
+     * double-commit, fires `onChoiceMade`, and steps the runner. The latch (not the
+     * runner) is what guarantees a single commit: `mode` stays "choosing" while the
+     * runner awaits the option's blocking commands, so without it a second confirm
+     * would emit a duplicate `onChoiceMade`.
+     */
+    private commit;
+    /** Toggle hold-to-fast-forward; the text channel scales its reveal rate. */
+    setFastForward(on: boolean): void;
+    /**
+     * Default auto-advance: lines without their own `autoAdvanceMs` advance `ms`
+     * after they finish revealing; `null` turns it off (manual advance). A
+     * per-line `autoAdvanceMs` always overrides this. Toggling it while a line is
+     * already sitting revealed arms/clears its timer immediately.
+     */
+    setAutoAdvance(ms: number | null): void;
+    private handleSay;
+    private handleChoice;
+    private handleCommand;
+    private handleEnd;
+    private handleRevealComplete;
+    /**
+     * Fan one reveal beat out — the per-line typewriter stream. Extras (Voice /
+     * CameraEffects / a typewriter-SFX channel) see the WHOLE stream via
+     * `revealBeat?`. A `tick` then reaches the host's `onRevealTick` callback; a
+     * `marker` reaches the avatar channel (which interprets `[expression=…/]`
+     * itself — the Session name-matches nothing) and the host's `onRevealMarker`.
+     */
+    private handleRevealBeat;
+    /**
+     * Fire the current line's commands matching `at`, via the runner's command
+     * pipeline (so `set`/blocking behave identically). While a blocking one is
+     * awaited, `lineBlocked` gates input so the player can't advance through it.
+     * `mode` overrides the runner's run mode (skip() fires the displayed line's
+     * batches in skip mode).
+     */
+    private fireLineCommands;
+    private speakerName;
+    private speakerView;
+}
+
+/**
+ * Adapter-level presenter contracts. The headless {@link DialogueChannels}
+ * (core) describe *what* a chrome / choice presenter does; these add the YAGE
+ * lifecycle (`mount(scene)` / `dispose()`) the host drives. Concrete renderer
+ * presenters ({@link DialogueChrome}, {@link ChoiceListPresenter}) implement
+ * these; a ui-react / DOM chrome you write later implements the same shape.
+ */
+
+/** A dev-facing diagnostics sink — the controller wires this to the engine
+ *  Logger (the same seam as the session's `onError`), so a presenter-level
+ *  warning (e.g. a missing actor) routes there instead of `console.warn`. */
+type DiagnosticSink = (message: string) => void;
+/** YAGE lifecycle shared by the renderer-based presenters. */
+interface Mountable {
+    mount(scene: Scene): void;
+    dispose(): void;
+    /** Optional: receive a diagnostics sink. The controller injects one at
+     *  mount so a presenter can report dev-facing issues (a missing actor) through
+     *  the engine Logger. Presenters with nothing to report omit it. */
+    setDiagnostics?(warn: DiagnosticSink): void;
+}
+/** Frame / nameplate / continue caret. `setVisible` (now part of
+ *  {@link ChromeChannel}) lets a composite chrome show/hide a whole variant
+ *  (e.g. hide the box while a bubble line plays). */
+interface ChromePresenter extends ChromeChannel, Mountable {
+}
+/** The choice list / wheel / panel. Optionally hit-tests pointer coords so a
+ *  pointer binding can hover/click rows ({@link PointerChoiceTarget}). The
+ *  hit-test (and `pointerSpace`) are read in screen space by default; a
+ *  world-anchored presenter (e.g. a bubble) sets `pointerSpace: "world"`. */
+interface ChoicePresenter extends ChoiceChannel, Mountable {
+    choiceAtPoint?(x: number, y: number): number | undefined;
+    /** Coordinate space `choiceAtPoint` expects. Default "screen". */
+    readonly pointerSpace?: "screen" | "world";
+}
+/**
+ * Body-text presenter: the headless {@link TextChannel} (reveal timing) plus the
+ * YAGE lifecycle the host drives.
+ *
+ * This contract lives in this pixi-free adapter module — NOT on the concrete,
+ * renderer-backed `DialogueTextView` — so the headless root entry (`"."`) can
+ * reach it through the `DialogueController` without transitively importing
+ * `@yagejs/renderer`. The renderer-backed views only *implement* this shape.
+ */
+interface TextPresenter extends TextChannel, Mountable {
+}
+
+/**
+ * The avatar layer is deliberately decoupled from the box: the controller only
+ * ever talks to this interface, so a speaker can be shown as a portrait beside
+ * the box, as a full figure already standing in the scene, or not at all —
+ * without the dialogue runtime knowing which. Implementations live alongside
+ * (PortraitPresenter, SceneFigurePresenter); swap freely or compose your own.
+ */
+
+/**
+ * The adapter-level avatar presenter: the headless {@link AvatarChannel}
+ * (setSpeaker / setExpression / setSpeaking / marker / update) plus the YAGE
+ * lifecycle the host drives (mount / dispose).
+ */
+interface AvatarPresenter extends AvatarChannel {
+    /** Called once when the controller mounts. */
+    mount(scene: Scene): void;
+    dispose(): void;
+}
+/** No-op presenter — the default when a script has no avatars. */
+declare class NullAvatarPresenter implements AvatarPresenter {
+    mount(): void;
+    setSpeaker(): void;
+    setExpression(): void;
+    setSpeaking(): void;
+    update(): void;
+    dispose(): void;
+}
+
+/**
+ * Input is externalised so it's obviously *optional* and obviously *swappable*.
+ * A `DialogueSession` exposes an input-agnostic API (`advance / moveSelection /
+ * setFastForward`); an {@link InputBinding} is whatever maps a device onto it.
+ * The default {@link KeyboardInputBinding} polls the YAGE `InputManager` action
+ * map. An ambient (auto-advancing) conversation simply attaches no binding; a
+ * touch/gamepad/pointer binding is a parallel implementation of this interface.
+ */
+
+interface DialogueActions {
+    /** Tap → reveal-all if typing, else next line / confirm choice. */
+    readonly advance: readonly string[];
+    /** Hold → fast-forward the typewriter. */
+    readonly speed: readonly string[];
+    readonly up: readonly string[];
+    readonly down: readonly string[];
+    /** Tap → skip the current section to the next choice/end. Unbound by default. */
+    readonly skip?: readonly string[];
+}
+declare const DEFAULT_ACTIONS: DialogueActions;
+/** Keyboard actions with skip bound (the game maps `skip` → KeyX in main.ts). */
+declare const FULL_ACTIONS: DialogueActions;
+interface InputBinding {
+    /**
+     * Wire a device to a session. Called by the host once both exist. A binding
+     * has a single owner: re-binding re-targets it (implementations must release
+     * any resources held for the previous bind) — don't share one instance
+     * between two live controllers.
+     */
+    bind(input: InputManager, session: DialogueSession): void;
+    /** Poll the device and drive the session. Called once per frame by the host. */
+    poll(): void;
+    /** Optional teardown (e.g. unsubscribe pointer listeners). */
+    dispose?(): void;
+}
+/**
+ * A presenter that can resolve a pointer point to a choice position — lets a
+ * pointer binding pick/hover choices without owning their geometry. Coords are
+ * in `pointerSpace` ("screen" default; a bubble/world list uses "world").
+ */
+interface PointerChoiceTarget {
+    /** Position of the choice row under this point, or undefined. Omit for no
+     *  pointer hit-testing. */
+    choiceAtPoint?(x: number, y: number): number | undefined;
+    readonly pointerSpace?: "screen" | "world";
+}
+/** Fan a single session out to several device bindings (keyboard + pointer …). */
+declare class CompositeInputBinding implements InputBinding {
+    private readonly bindings;
+    constructor(bindings: readonly InputBinding[]);
+    bind(input: InputManager, session: DialogueSession): void;
+    poll(): void;
+    dispose(): void;
+}
+/** Keyboard/gamepad action-map binding (the default). */
+declare class KeyboardInputBinding implements InputBinding {
+    private readonly actions;
+    private readonly skipHoldMs;
+    private input?;
+    private session?;
+    /** Latch so a held skip fires once per hold, not every frame past threshold. */
+    private skipFired;
+    /**
+     * @param skipHoldMs Hold the `skip` action this long before it fires (the
+     *   classic "hold to skip" confirm). `0` (default) fires on press.
+     */
+    constructor(actions?: DialogueActions, skipHoldMs?: number);
+    bind(input: InputManager, session: DialogueSession): void;
+    poll(): void;
+    /** Fire skip once the action has been held `skipHoldMs` (hold-to-confirm),
+     *  re-arming only after it's released. */
+    private pollSkip;
+}
+/**
+ * Mouse/touch binding. A tap during a line advances (reveal-all, then next);
+ * a tap on a choice row picks it, and hover highlights it — provided a
+ * {@link PointerChoiceTarget} is supplied so the binding can hit-test rows.
+ * Works for both mouse and touch since it rides the unified pointer stream.
+ */
+declare class PointerInputBinding implements InputBinding {
+    private input?;
+    private session?;
+    private unsub;
+    /** A primary-button press happened since the last poll (consumed in poll). */
+    private clicked;
+    private readonly choices;
+    /** Pointer position at the last hover hit-test, so an unmoved pointer
+     *  doesn't re-run the hit-test every frame. */
+    private lastX;
+    private lastY;
+    /** Whether the previous poll saw a choice up (a fresh choice set must be
+     *  hit-tested even under a stationary pointer). */
+    private wasChoosing;
+    constructor(choices?: PointerChoiceTarget);
+    bind(input: InputManager, session: DialogueSession): void;
+    /** Pointer position in the choice presenter's coordinate space. */
+    private pointer;
+    poll(): void;
+    dispose(): void;
+}
+/**
+ * The full control set in one binding: keyboard/gamepad (advance / fast-forward
+ * hold / choice nav / skip) **and** mouse/touch (tap to advance, tap/hover
+ * choices). Pass a scene's choice presenter so the pointer can hit-test rows;
+ * `skipHoldMs` adds the classic "hold to skip" confirm.
+ */
+declare function fullControls(choices?: PointerChoiceTarget, options?: {
+    actions?: DialogueActions;
+    skipHoldMs?: number;
+}): InputBinding;
+
+/**
+ * DialogueController — the thin YAGE host. It owns no dialogue logic; it just:
+ *
+ *   • mounts the presenters onto the scene,
+ *   • builds a headless {@link DialogueSession} over them,
+ *   • forwards the session's observation callbacks to engine events,
+ *   • attaches an {@link InputBinding} (keyboard by default) and pumps it,
+ *   • pumps `session.update(dt)` each frame.
+ *
+ * All the sequencing, reveal-gating, choice book-keeping, and i18n live in the
+ * session (engine-agnostic). The presenter bundle usually comes from a factory
+ * (`createBoxDialogue(theme)`), spread-and-overridden as needed:
+ *
+ *   host.add(new DialogueController({ ...createBoxDialogue(theme), avatar, storage }));
+ */
+
+/** The presenter trio a factory assembles (see `createBoxDialogue`).
+ *  Optional fields are `T | undefined` so factories and games can assign
+ *  possibly-undefined theme values directly (exactOptionalPropertyTypes). */
+interface DialogueBundle {
+    readonly chrome: ChromePresenter;
+    readonly text: TextPresenter;
+    readonly choices: ChoicePresenter;
+    readonly avatar?: AvatarPresenter | undefined;
+    /** Hold-to-fast-forward multiplier. Default 4. */
+    readonly skipMultiplier?: number | undefined;
+}
+interface DialogueControllerOptions<TStorage extends VariableStorage = VariableStorage> extends DialogueBundle {
+    readonly i18n?: I18nAdapter | undefined;
+    /**
+     * The variable storage installed for every `play()`. Persists across
+     * plays. Omit for a zero-config `MemoryVariableStorage`; supply your own (or
+     * `compose(cells(...), new MemoryVariableStorage())`) to bridge game state. A
+     * per-`play()` `overrides.storage` replaces it for that conversation.
+     */
+    readonly storage?: TStorage | undefined;
+    /** Argument-capable read functions (`has_item("key")`) shared across plays. */
+    readonly functions?: Readonly<Record<string, DialogueFunction>> | undefined;
+    /** Command handlers (`type` → handler) shared across plays; per-`play()`
+     *  `overrides.commands` merge on top (call site wins). */
+    readonly commands?: Readonly<Record<string, CommandHandler>> | undefined;
+    /** Catch-all for command types with no explicit handler. */
+    readonly fallbackCommand?: CommandHandler | undefined;
+    /** Device → session binding. Omit for the default keyboard binding. */
+    readonly input?: InputBinding;
+    /**
+     * Extra channels registered on the session at mount (Voice / Shop /
+     * CameraEffects / History) — the open-ended companion to the presenter trio.
+     * Each is wired via {@link DialogueController.addChannel}; one that also
+     * implements {@link Mountable} (it needs the scene) is mounted in `onAdd` and
+     * disposed in `onDestroy`. A factory bundle can pre-wire e.g. a voice channel
+     * here; a game can also add one live with {@link DialogueController.addChannel}.
+     */
+    readonly channels?: readonly DialogueExtraChannel[] | undefined;
+    /**
+     * Per-grapheme typewriter tick — a direct callback (NOT an entity event; it
+     * fires hundreds of times per line). `index` is the raw grapheme index revealed
+     * (whitespace included — filter if you only want a blip on visible glyphs).
+     * Wire a typewriter SFX here. Inline `[name k=v/]` markers, by contrast, come
+     * through {@link DialogueRevealMarkerEvent} on the entity bus.
+     */
+    readonly onRevealTick?: ((index: number) => void) | undefined;
+    /** Called once when a conversation ends (in addition to the scene event). */
+    readonly onEnded?: () => void;
+}
+declare class DialogueController<TStorage extends VariableStorage = VariableStorage> extends Component {
+    private readonly opts;
+    private readonly input;
+    private readonly binding;
+    private session;
+    /** Captured at onAdd (the scene is gone by the time a stale play() arrives). */
+    private logger;
+    /** Set by onDestroy — the presenters are disposed, so play() must refuse. */
+    private destroyed;
+    /** Input focus. When false, `update()` keeps pumping the session (an
+     *  ambient conversation stays alive) but the binding is NOT polled, so this
+     *  instance doesn't consume device input. NOT `Component.enabled` (which would
+     *  also freeze the session). */
+    private inputEnabled;
+    /** Pause. Mirrors the session's pause so the binding poll is also gated
+     *  while frozen — a paused conversation neither updates nor consumes input.
+     *  Also the source of truth re-applied to the session in `onAdd` when a host
+     *  set it before the component was added (the session didn't exist yet). */
+    private paused;
+    /** Hidden. Mirrors the session's hide so a `setHidden` issued before the
+     *  component was added isn't lost — it's re-applied once the session exists. */
+    private hidden;
+    /** Disposers for every registered extra channel (ctor `channels` + live
+     *  `addChannel`). `onDestroy` runs them all — each idempotent — to unregister
+     *  and dispose (unmounting the Mountable ones). */
+    private readonly channelDisposers;
+    constructor(opts: DialogueControllerOptions<TStorage>);
+    onAdd(): void;
+    onDestroy(): void;
+    /**
+     * Begin a conversation. `play(script)` is **content-only** — storage,
+     * functions, and commands are installed on the controller. `overrides` layers
+     * per-conversation specifics on top (a scoped `storage`, extra
+     * `functions`/`commands`). Returns a {@link DialogueHandle} for live `setVar` /
+     * `getVars`, or `undefined` if the controller was removed.
+     */
+    play<S extends DialogueScript>(script: S, overrides?: DialoguePlayOptions): DialogueHandle<VarsOf<S>> | undefined;
+    isActive(): boolean;
+    /** Abandon the current conversation and reset to idle. */
+    stop(): void;
+    /**
+     * Register an extra channel live — Voice / Shop / CameraEffects / History.
+     * Mounts it if it needs the scene ({@link Mountable}), hands it to the session
+     * (where it joins the cross-cutting stream and can gate auto-advance), and
+     * returns a disposer that unregisters + disposes it. The `channels` ctor option
+     * registers a bundle the same way at mount. Returns a no-op disposer if the
+     * controller was destroyed; **throws** if called before the component is added
+     * to an entity (use the `channels` ctor option to pre-wire a channel) — mirrors
+     * {@link play}.
+     */
+    addChannel(ch: DialogueExtraChannel): () => void;
+    /** Fast-forward the current section to the next choice or the end. */
+    skip(): void;
+    /**
+     * Auto-advance lines after they finish revealing (`ms`), or `null` to disable
+     * (manual advance). A per-line `autoAdvanceMs` still overrides this. Toggle it
+     * live for a VN-style "auto" control.
+     */
+    setAutoAdvance(ms: number | null): void;
+    /**
+     * Hide or show the whole dialogue UI without ending the conversation —
+     * for a cutscene takeover (`setHidden(true)` while the camera pans, then
+     * `setHidden(false)` to restore the exact line + caret). Purely visual; the
+     * conversation keeps its state. **Persistent**: it survives `stop()`/`play()`,
+     * so a host that hides and forgets to unhide stays hidden.
+     */
+    setHidden(hidden: boolean): void;
+    /**
+     * Freeze or resume the conversation — a pause menu. While paused the
+     * reveal, auto-advance, caret blink, and avatar anim all halt, input is inert,
+     * and no state is lost (an in-flight blocking command keeps running). Also
+     * gates this controller's input binding so a frozen conversation consumes no
+     * device input. Does NOT block host-driven `handle.setVar` / storage writes.
+     */
+    setPaused(paused: boolean): void;
+    /**
+     * Set whether this controller consumes device input — the focus seam for
+     * the multi-instance story. `setInputEnabled(false)` keeps the conversation
+     * fully alive (it still updates, reveals, auto-advances) but stops polling its
+     * binding, so an ambient conversation doesn't steal the advance key. Switch
+     * focus between two conversations with `a.setInputEnabled(true);
+     * b.setInputEnabled(false)`. (YAGE input is non-consuming, so two *enabled*
+     * controllers both advance on one press — focus is the game's policy.)
+     */
+    setInputEnabled(enabled: boolean): void;
+    /**
+     * Primary action, host-driven (the input-agnostic seam): while saying,
+     * reveal-all if still typing else advance to the next line; while choosing,
+     * confirm the highlighted option. Lets a host (cutscene script, custom input,
+     * or a test) drive the conversation without synthesising device input — the
+     * same call the default {@link InputBinding} makes.
+     */
+    advance(): void;
+    /** Move the choice cursor by `delta` (wraps). No-op outside a choice. */
+    moveSelection(delta: number): void;
+    /** Commit a choice by its original option index. No-op outside a choice. */
+    choose(optionIndex: number): void;
+    /** True while a choice is being presented. */
+    isChoosing(): boolean;
+    /** Side-effect-free lookahead of the lines a node would show. */
+    preview(nodeId: string): PreviewedLine[];
+    update(dt: number): void;
+}
+
+export { type AvatarChannel as A, type ChoiceChannel as C, type DialogueExtraChannel as D, FULL_ACTIONS as F, type I18nAdapter as I, KeyboardInputBinding as K, LineReveal as L, type Mountable as M, NullAvatarPresenter as N, type PointerChoiceTarget as P, type RevealBeat as R, type SpeakerView as S, type TextChannel as T, type VarsOf as V, type ChoiceContext as a, type ChromeChannel as b, CompositeInputBinding as c, DEFAULT_ACTIONS as d, type DialogueActions as e, type DialogueBundle as f, type DialogueChannels as g, DialogueController as h, type DialogueControllerOptions as i, DialogueSession as j, type DialogueSessionOptions as k, IdentityI18n as l, type InputBinding as m, PointerInputBinding as n, type PresentedChoice as o, type PresentedLine as p, type PreviewedLine as q, type TypedScript as r, defineScript as s, fullControls as t, interpolate as u, type TextPresenter as v, type DiagnosticSink as w, type ChromePresenter as x, type ChoicePresenter as y, type AvatarPresenter as z };