@yagejs-addons/dialogue 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,591 @@
+import { P as ParsedText, D as DialogueScript, V as VarValue, a as VariableStorage, b as VarMap, C as Condition, E as Expr, c as DialogueFunction, S as SayStep, d as SpeakerDef, e as ChoiceStep, f as ChoiceOption, g as Command, h as CommandContext, R as RunMode, M as MarkerToken } from './types-DSbBSlh7.cjs';
+export { A as ArithmeticOp, i as AvatarRef, B as BinaryOp, j as BuiltinEffectId, k as CommandHandler, l as CommandStep, m as CommandTiming, n as CompareOp, o as ComparisonOp, p as DialogueHandle, q as DialogueNode, r as DialoguePlayOptions, s as EndStep, G as GotoStep, L as LogicalOp, N as NodeId, t as PauseToken, u as RevealToken, v as RunStyle, w as SpeakerId, x as Step, T as TextRun, U as UnaryOp } from './types-DSbBSlh7.cjs';
+import { D as DialogueExtraChannel } from './DialogueController-BMeNLi0v.cjs';
+export { A as AvatarChannel, C as ChoiceChannel, a as ChoiceContext, b as ChromeChannel, c as CompositeInputBinding, d as DEFAULT_ACTIONS, e as DialogueActions, f as DialogueBundle, g as DialogueChannels, h as DialogueController, i as DialogueControllerOptions, j as DialogueSession, k as DialogueSessionOptions, F as FULL_ACTIONS, I as I18nAdapter, l as IdentityI18n, m as InputBinding, K as KeyboardInputBinding, L as LineReveal, M as Mountable, P as PointerChoiceTarget, n as PointerInputBinding, o as PresentedChoice, p as PresentedLine, q as PreviewedLine, R as RevealBeat, S as SpeakerView, T as TextChannel, r as TypedScript, V as VarsOf, s as defineScript, t as fullControls, u as interpolate } from './DialogueController-BMeNLi0v.cjs';
+import * as _yagejs_core from '@yagejs/core';
+import '@yagejs/input';
+
+/**
+ * Inline-markup parser. Turns an authored string into styled {@link TextRun}s
+ * plus {@link RevealToken}s, using a small BBCode-ish tag syntax that survives
+ * translation (translators keep the tags, reorder the words):
+ *
+ *   plain text
+ *   [b]bold[/b] [i]italic[/i]
+ *   [color=#ffcc00]hex[/color]   [color=gold]named[/color]
+ *   [wave]animated[/wave]      (effect span — OPEN vocabulary: any [name]..[/name];
+ *                               the bundled view animates wave/shake/pulse/rainbow)
+ *   [speed=2]faster[/speed]  [speed=0.5]slower[/speed]
+ *   [pause=400/]               (self-closing reveal PAUSE — holds at its offset, in ms)
+ *   [sfx=ding/]                (self-closing reveal MARKER — fires at its offset)
+ *   [expression=happy/]        (self-named shortcut → props { expression: happy })
+ *   [shake amount=3/]          (marker with explicit key=value props)
+ *   [shake=500 amount=3/]      (shortcut + props compose → { shake: 500, amount: 3 })
+ *   \[literal bracket]
+ *
+ * Tags nest; styles inherit down the stack (so [b][color=red]X[/color][/b]
+ * is bold+red). A trailing `/` makes a tag **self-closing** — a zero-width
+ * {@link RevealToken} (a `[pause=600/]` hold or a `[name k=v/]` marker) that the
+ * reveal drains at its char offset, distinct from the styling tags (which never
+ * end in `/`). Pause + markers share one ordered stream, so **source order is
+ * drain order**: `[pause=600/][shake/]` holds then fires; `[shake/][pause=600/]`
+ * fires then holds. A non-self-closing tag that isn't a built-in text attribute
+ * opens an EFFECT span named after the tag (an open vocabulary the presenter
+ * interprets); translators MUST keep a marker/pause's self-closing `/` so the
+ * token survives a re-order.
+ */
+
+/** The empty parse result (no runs / tokens, length 0). Shared so a presenter or
+ *  the session can present a contentless line (an empty choice prompt) without
+ *  re-constructing the shape — and without forgetting the required `tokens`
+ *  field. */
+declare const EMPTY_PARSED: ParsedText;
+/**
+ * Split a string into graphemes (user-perceived characters) — the unit the
+ * renderer creates one glyph node per, and the unit every reveal-side count
+ * (`ParsedText.length`, `TextRun.graphemeCount`, `PauseToken.atChar`) uses.
+ */
+declare function splitGraphemes(text: string): string[];
+declare function parseMarkup(input: string): ParsedText;
+/** Strip every tag, returning plain text (useful for measuring / a11y / logs). */
+declare function stripMarkup(input: string): string;
+
+/**
+ * Two-stage validation for the storage model.
+ *
+ *   • **Load-time** ({@link analyzeScript}, environment-free): walk the script
+ *     once, collecting the names it **reads** (conditions, `{token}`s, `set`
+ *     values), the names it **writes** (`set` targets), the **functions** it
+ *     calls, and the **command types** it fires. Type-check what's statically
+ *     knowable — an atomic numeric comparison against a declared non-number, a
+ *     literal `set` value whose type conflicts with the target's declared
+ *     default. Undeclared *references* are NOT rejected here: the installed
+ *     storage / functions may provide them, which is only known at play-time.
+ *   • **Play-time** ({@link validatePlay}): given the installed storage,
+ *     functions, and commands, throw on a *significant* mismatch — a read name
+ *     nothing provides, a called function with no implementation, a `set` target
+ *     that's a function (read-only), a command type with no handler/fallback, a
+ *     declared default whose type conflicts with the value the storage already
+ *     holds.
+ *
+ * Both throw hard — a dangling reference or an environment that can't satisfy the
+ * script is a programming error, not a recoverable runtime condition.
+ */
+
+/** A script reference is broken (load-time). */
+declare class DialogueScriptError extends Error {
+}
+/** The installed storage/functions/commands don't satisfy the script (play-time). */
+declare class DialoguePlayError extends Error {
+}
+
+/**
+ * Canonical loader: validates + normalises a hand-authored / JSON
+ * {@link DialogueScript} into a frozen, structurally-checked script the runner
+ * can trust. Other "common formats" (a Yarn/ink-style screenplay parser) are
+ * additional modules in this folder that emit the same canonical shape — the
+ * runner only ever sees the canonical model.
+ */
+
+declare function loadScript(raw: DialogueScript): DialogueScript;
+
+/**
+ * Compact authoring front-end — a small, line-oriented DSL for RPG-style
+ * dialogue that compiles to the same {@link DialogueScript} IR as JSON / YAML.
+ * `parseCompact(text)` produces the IR; `loadCompact(text)` runs it through
+ * {@link loadScript}, so validation and the frozen model are identical to every
+ * other loader. Pixi-free: it imports only the headless core (`parseExpr`,
+ * `loadScript`, the markup tag guard).
+ *
+ * One statement per line. Leading whitespace is insignificant (indent nodes for
+ * readability). Blank lines and `// comment` lines are ignored. Each non-blank
+ * line is one of:
+ *
+ *   # id                 script id (required, once) — the start node is the
+ *                        first `::` node defined.
+ *   @ id Name [#hex]     a speaker: an opaque id, a display name (may have
+ *                        spaces), an optional nameplate colour (`#ffcc00` /
+ *                        `#fc0`). `@` lines may appear before or after their use.
+ *   :: nodeId            opens a node; following step lines belong to it.
+ *   speaker[ face]: text a spoken line — ONLY when the first token is a declared
+ *                        `@`-speaker. `face` (a 2nd header token) becomes the
+ *                        line's avatar `expression`. Otherwise the WHOLE line,
+ *                        colons and all, is a narrator line.
+ *   text                 a narrator line (no declared speaker prefix).
+ *   ? text …             a choice option; consecutive `?` lines coalesce into
+ *                        one choice step (see below).
+ *   -> nodeId [if: cond] a jump — unconditional, or conditional (taken only if
+ *                        `cond` holds, else fall through to the next step).
+ *   declare v = value    a script-level variable default (a literal value).
+ *   set v = rhs          write a variable. A bare number / `true` / `false` /
+ *                        `null` stays a literal; anything else is parsed as an
+ *                        expression (`set hp = hp - 1`), so the host reads it
+ *                        back through the same evaluator JSON uses.
+ *   do type k=v … #flag  a host command: `type` then `key=value` data and
+ *                        `#flag` booleans (`do give-item id=key count=1 #blocking`).
+ *   end                  ends the conversation.
+ *
+ * **Per-line hints** ride the end of a `say` line: `view=` / `voice=` / `speed=`
+ * / `auto=` set the first-class {@link SayStep} fields, and trailing `#key:value`
+ * / bare `#flag` hashtags become {@link SayStep.meta} (Yarn-aligned — metadata is
+ * trailing). A `say` line's text is otherwise passed to the markup parser
+ * **verbatim**, so inline `[..]` markup (and any markup tokens a later release
+ * adds) survives untouched.
+ *
+ * **Choices** carry their attributes as non-bracket sigils, in this order after
+ * the text: `if: cond`, then `-> target` (or `target=node`), then `#once` /
+ * `#disabled` / `#key:value` hashtags. They are lexed off and stripped before
+ * the remaining choice text reaches markup — `[..]` is reserved for inline
+ * markup there, so a bracketed token that markup doesn't recognize is reported
+ * as an error (it is almost always a mistyped attribute that would otherwise be
+ * dropped silently).
+ *
+ * Conditions and non-literal `set` values are parsed with the shared
+ * {@link parseExpr}, so a malformed expression throws {@link DialogueExprError}
+ * (a {@link DialogueScriptError} subtype) with its position.
+ */
+
+/**
+ * Parse compact-DSL source into a (mutable) {@link DialogueScript}. Throws
+ * {@link DialogueScriptError} on a structural problem (with the 1-based line) and
+ * {@link DialogueExprError} on a malformed condition / `set` expression.
+ */
+declare function parseCompact(text: string): DialogueScript;
+/** Parse compact-DSL source and run it through {@link loadScript} — same
+ *  validated, frozen IR as the JSON and YAML loaders. */
+declare function loadCompact(text: string): DialogueScript;
+
+/**
+ * {@link VariableStorage} implementations — the read/write bridge between a
+ * conversation and game state. One **opaque** name namespace; scoping is
+ * the host's policy. Three building blocks:
+ *
+ *   • {@link MemoryVariableStorage} — the zero-config default. A plain Map; holds
+ *     dialogue-locals and seeded defaults, persists across plays.
+ *   • {@link cells} — first-class **two-way binding**: `{ gold: { get, set } }`
+ *     drives a value the *script* owns the arithmetic of (a read-only getter
+ *     throws on `set`). A bare `() => value` is the read-only shorthand.
+ *   • {@link compose} — layer several storages into one (reads/writes route to
+ *     the first that `has` the name; a brand-new name lands in the last —
+ *     so put a writable store last to catch seeds + locals).
+ *
+ * The interface lives in `types.ts`; this file is the concrete kit. Seed-if-
+ * absent + persistence are policy of the *caller* (`session.play`), not the
+ * storage — these just hold values.
+ */
+
+/** Materialize a storage's enumerable variables into a plain map — backs
+ *  `{token}` interpolation params and `handle.getVars()`. */
+declare function materialize(storage: VariableStorage): VarMap;
+/** The zero-config default storage: a Map-backed, fully-enumerable store. */
+declare class MemoryVariableStorage implements VariableStorage {
+    private readonly map;
+    constructor(initial?: Readonly<VarMap>);
+    get(name: string): VarValue | undefined;
+    set(name: string, value: VarValue): void;
+    has(name: string): boolean;
+    entries(): Iterable<readonly [string, VarValue]>;
+    /** Drop everything — host-controlled reset (variables persist across plays by default). */
+    clear(): void;
+}
+/** A two-way (or read-only) binding for one game-owned value. A bare function is
+ *  the read-only shorthand for `{ get }`. */
+type Cell = {
+    get(): VarValue;
+    set?(value: VarValue): void;
+} | (() => VarValue);
+/**
+ * A {@link VariableStorage} over named accessors into game state. `has` is true
+ * for exactly the declared names; `get` invokes the getter live; `set` writes
+ * through the setter, or throws if the cell is read-only (a getter with no
+ * setter). This is the seam for a value whose arithmetic the *script* owns
+ * (`set gold = gold - 50`).
+ */
+declare function cells(defs: Readonly<Record<string, Cell>>): VariableStorage;
+/**
+ * Layer storages into one. `get`/`has` consult them in order (first that `has`
+ * the name wins); `set` writes through the first that `has` it, else the **last**
+ * storage — so a brand-new name (a dialogue-local or a seeded default) lands in
+ * whatever writable store you put last. Typical: `compose(cells(...game), new
+ * MemoryVariableStorage())`.
+ */
+declare function compose(...storages: readonly VariableStorage[]): VariableStorage;
+
+/**
+ * Expression evaluator. `Condition`s and `set` values are expression
+ * *trees* — `literal | varRef | call | unary | binary | group` — evaluated
+ * against an {@link EvalScope} (variable reads + installed functions). The
+ * operator set mirrors Yarn Spinner so a future Yarn parser maps onto this IR
+ * 1:1; the atomic `{ var, op, value }` comparison evaluates as the degenerate
+ * one-level tree (lowered into a `binary` node in {@link evalCondition}).
+ */
+
+/** What an expression evaluates against: per-name reads + function calls, plus
+ *  a materialized snapshot for the `(vars) => boolean` predicate escape hatch. */
+interface EvalScope {
+    /** Read a variable (absent → `null`). */
+    get(name: string): VarValue;
+    /** Invoke an installed function with already-evaluated args. */
+    call(fn: string, args: readonly VarValue[]): VarValue;
+    /** Materialize the readable variables (for a predicate condition). */
+    vars(): VarMap;
+}
+/** A condition holds when its value is truthy. */
+declare function evalCondition(condition: Condition, scope: EvalScope): boolean;
+/** Evaluate an expression tree to a single value. */
+declare function evaluate(expr: Expr, scope: EvalScope): VarValue;
+/** True for an {@link Expr} node (discriminated by `kind`), so `Condition` can
+ *  tell a tree apart from the atomic `{ var, op, value }` shape. */
+declare function isExpr(value: unknown): value is Expr;
+
+/**
+ * String → expression front-end. `parseExpr("str >= 8 and has_item('key')")`
+ * produces the same {@link Expr} tree a hand-authored JSON condition / `set`
+ * value would — `literal | varRef | call | unary | binary | group`, no new node
+ * kinds — so the evaluator (`expr.ts`) and the load-time walk (`validate.ts`)
+ * are reused unchanged. This is purely a parser: it does no type-checking and
+ * no name resolution (that stays in `validate.ts`), which keeps it reusable 1:1
+ * for a future Yarn front-end.
+ *
+ * The operator set mirrors Yarn Spinner. v1 wires what the authoring examples
+ * exercise: `or`/`||`, `and`/`&&`, `not`/`!`, the comparisons (`== != > < >= <=`
+ * plus the word forms `eq neq gt lt gte lte is`), unary `-`, binary `+ -`, calls
+ * `f(a, b)`, and parentheses. `xor`/`^` and `* / %` are reserved but not yet
+ * wired (the IR + evaluator already accept them, so adding them later is purely
+ * additive). Word-form operators normalise to their symbol equivalents in the IR
+ * (`and` → `&&`, `eq` → `==`, `gt` → `>`, …), so `a and b` and `a && b` parse to
+ * the identical tree.
+ *
+ * An identifier is `[A-Za-z_$]` followed by `[A-Za-z0-9_.$]` repeats — `.` and
+ * `$` are included (so `$gold` and `quest.stage` each read as ONE name,
+ * Yarn-forward) but `-` is excluded, so `hp-1` is `hp` minus `1` and an item id
+ * like `'rusty-key'` must live in a quoted string literal.
+ */
+
+/**
+ * A string expression failed to parse. Carries the 1-based source position.
+ * Extends {@link DialogueScriptError} so the loaders' contract holds: a malformed
+ * string condition / `set` value surfaced by `loadScript` / `loadYaml` is caught
+ * by a single `catch (e instanceof DialogueScriptError)`, while `instanceof
+ * DialogueExprError` (and `line` / `col`) still distinguish a parse error.
+ */
+declare class DialogueExprError extends DialogueScriptError {
+    readonly line: number;
+    readonly col: number;
+    constructor(message: string, line: number, col: number);
+}
+/**
+ * Parse a string into an {@link Expr} tree. Throws {@link DialogueExprError}
+ * (with line/col) on an empty/blank source, a leftover trailing token, or a
+ * dangling operator.
+ */
+declare function parseExpr(src: string): Expr;
+
+/**
+ * DialogueRunner — the engine-agnostic state machine. It walks a normalised
+ * {@link DialogueScript}, pausing on `say`/`choice` steps (which need player
+ * input) and running `command`/`goto`/`end` steps straight through. All
+ * presentation is delegated via callbacks, so the same runner drives a
+ * renderer-based box, a ui-react box, or a headless test.
+ *
+ * Branching reads one {@link VariableStorage} namespace through an
+ * {@link EvalScope} (per-name reads + installed functions): `set` / `ctx.setVar`
+ * write storage, conditions and `set` values are evaluated as expression trees.
+ * The runner resolves built-in commands (`set`) itself and surfaces every other
+ * command to the host through `onCommand` — that's the seam where the game turns
+ * `{ type: "give-item", id: "key" }` into an actual effect.
+ */
+
+/** The runtime environment the session installs behind a running conversation:
+ *  the variable storage (read + guarded write) + the callable functions. */
+interface RunnerEnv {
+    readonly storage: VariableStorage;
+    readonly functions: Readonly<Record<string, DialogueFunction>>;
+    /**
+     * Surfaces a non-fatal runtime diagnostic — currently a `set` whose write the
+     * storage rejected (a getter-only `cells` accessor). The runner ignores the
+     * write and keeps the conversation running; the host (via the session →
+     * controller) routes the message to the engine logger. Engine-agnostic: the
+     * core never reaches for `console`/a logger directly.
+     */
+    readonly onError?: ((message: string, error: unknown) => void) | undefined;
+}
+interface ResolvedChoice {
+    readonly index: number;
+    readonly option: ChoiceOption;
+    /**
+     * A visible-but-disabled row: the option's condition currently fails AND its
+     * `presentation` is `"disabled"`, so it's shown greyed-out and non-selectable
+     * instead of filtered. Omitted (falsy) for a normal, selectable option.
+     * Default-`"hidden"` condition failures and spent `once` options aren't
+     * returned at all.
+     */
+    readonly disabled?: boolean;
+}
+interface RunnerHandlers {
+    /** A line is ready to display. Runner waits for `advance()`. */
+    onSay(step: SayStep, speaker: SpeakerDef | undefined): void;
+    /** Choices are ready. Runner waits for `choose(index)`. `prompt` pre-resolved by host. */
+    onChoice(step: ChoiceStep, choices: readonly ResolvedChoice[], speaker: SpeakerDef | undefined): void;
+    /**
+     * A non-built-in command fired (give-item, play-sfx, …). May return a promise;
+     * if the command is `blocking`, the runner waits for it.
+     */
+    onCommand(command: Command, ctx: CommandContext): void | Promise<void>;
+    /** Conversation finished (ran off the end or hit an `end` step). */
+    onEnd(): void;
+}
+declare class DialogueRunner {
+    private readonly script;
+    private readonly handlers;
+    /** `option.once` keys already picked — per-conversation **cursor** state, NOT
+     *  the variable storage. Fresh per runner, so a new `play()` starts it empty
+     *  (a re-played conversation re-shows its `once` options; {@link getChosenOnce}
+     *  exposes the set so a save cursor could capture/restore it). */
+    private readonly chosenOnce;
+    private nodeId;
+    private stepIndex;
+    private state;
+    /** "play" normally; `skip()` flips it to "skip" to fast-forward the section. */
+    private runMode;
+    /** Storage (write through this so a read-only `cells` accessor throws) +
+     *  functions, wrapped once as the condition/`set`-value eval scope. */
+    private readonly storage;
+    private readonly scope;
+    private readonly onError;
+    constructor(script: DialogueScript, 
+    /** The variable storage + functions (built by the session per play()). */
+    env: RunnerEnv, handlers: RunnerHandlers);
+    /** Snapshot of the storage's variables — the `handle.getVars()` /
+     *  future save-cursor view. */
+    getVars(): Readonly<VarMap>;
+    /** Current node id (durable cursor; save seam). */
+    getNodeId(): string;
+    /** Current step index within the node (durable cursor; save seam). */
+    getStepIndex(): number;
+    /** One-shot choice keys already picked (`option.once`); save seam. */
+    getChosenOnce(): ReadonlySet<string>;
+    isEnded(): boolean;
+    /** Begin at the start node. Idempotent guard against double-start. The cursor
+     *  (`nodeId`/`stepIndex`) is already at the start from the ctor + field init. */
+    start(): void;
+    /** Advance past the current `say` line. No-op unless we're awaiting it. */
+    advance(): void;
+    /**
+     * Fast-forward from the current line: run intervening commands in `skip` mode
+     * (so the game can reconstruct world state idempotently) without presenting
+     * any lines, stopping at the next choice or the end. No-op unless on a line.
+     */
+    skip(): Promise<void>;
+    /**
+     * Public, **wait-state-free** entry the Session uses to fire a `say` line's
+     * commands at show / after-reveal / advance time. Handles built-in `set`,
+     * surfaces the rest with the current mode (or `mode`, when the Session fires the
+     * displayed line's batches as part of its own skip), and awaits `blocking` ones.
+     * Delegates to {@link executeBatch}; the runner's wait-state is untouched (the
+     * Session gates its own input).
+     */
+    runCommands(commands: readonly Command[] | undefined, mode?: RunMode): Promise<void>;
+    /** Pick choice `index` (the original option index). */
+    choose(index: number): Promise<void>;
+    /** Run non-blocking steps until we hit one that needs input, or the end. */
+    private run;
+    /** @returns true if the step blocks (waiting for advance/choose/command/end). */
+    private handleStep;
+    private jump;
+    private end;
+    private currentStep;
+    private speaker;
+    /**
+     * Resolve a choice step to its visible rows. A spent `once` option is always
+     * dropped (presentation governs condition failures only). A passing option is
+     * enabled; a failing one is returned as a `disabled` row when its
+     * `presentation` is `"disabled"`, else dropped (the default `"hidden"`).
+     */
+    private resolveChoices;
+    /** Whether option `index` can actually be picked — the gate `choose()` uses.
+     *  A spent `once` option or a failing condition refuses (a `"disabled"` row is
+     *  shown but still unpickable, so this stays the single selection authority). */
+    private choiceEnabled;
+    /** A `once` option already chosen this run — always dropped from the menu
+     *  regardless of `presentation`. Single source of truth for the once-gate,
+     *  shared by `resolveChoices` and `choiceEnabled`. Reads the option from
+     *  `step.options[index]`, so `(step, index)` is the only input. */
+    private isSpent;
+    private onceKey;
+    /**
+     * Fire an inline command batch (a `command` step or a chosen option). Manages
+     * wait-state: enters `awaiting-command` up front when the batch contains a
+     * blocking command, so a stray advance/confirm during the await is ignored; the
+     * caller transitions out of the state afterwards. The work itself goes through
+     * the wait-state-free {@link executeBatch}.
+     */
+    private fireBatch;
+    /**
+     * The wait-state-free command executor, shared by {@link fireBatch} (inline
+     * firing) and {@link runCommands} (the Session's line-timed firing). Applies
+     * built-in `set`; surfaces the rest to the host with the current mode; awaits
+     * `blocking` handlers and fire-and-forgets the others. Touches no wait-state.
+     */
+    private executeBatch;
+    /** The context handed to a command handler. `setVar` writes through the
+     *  conversation's storage (guarded by the session for staleness), the same
+     *  path as the `set` built-in — so the skill-check seam and `set` share one
+     *  guarded write. */
+    private commandContext;
+    private test;
+}
+
+/**
+ * Voice-over as a registered {@link DialogueExtraChannel}. It plays a line's
+ * `voice` clip and gates auto-advance until the clip ends — so a line
+ * auto-advances at `max(clipEnd, revealEnd)` with no duration plumbing, and a
+ * short line never moves on while its long clip is still talking.
+ *
+ * The addon owns **no audio**: the host supplies `play` (wired over
+ * `@yagejs/audio` in the game), which starts a clip and returns a handle. This
+ * module imports neither audio nor a renderer, so it stays on the pixi-free root
+ * entry alongside the rest of the headless model.
+ */
+
+/**
+ * The host-owned playback handle returned by {@link VoiceChannelOptions.play}.
+ * `pause` / `resume` are optional — a host that can't pause a clip degrades to a
+ * no-op (the conversation still pauses; the clip just keeps playing).
+ */
+interface VoiceHandle {
+    /** Stop the clip immediately and release it. */
+    stop(): void;
+    /** Pause playback (optional). */
+    pause?(): void;
+    /** Resume playback (optional). */
+    resume?(): void;
+}
+interface VoiceChannelOptions {
+    /**
+     * Start the clip for `id` (the line's `voice`) and return a {@link VoiceHandle}.
+     * Call `onEnded` when the clip finishes **naturally** — that releases the
+     * auto-advance gate. The addon imports no audio; a YAGE host wires this over
+     * `@yagejs/audio`, e.g.
+     *
+     *   play: (id, onEnded) => {
+     *     const sound = audio.play(id, { onEnd: onEnded });
+     *     return { stop: () => sound.stop(), pause: () => sound.pause(), resume: () => sound.resume() };
+     *   }
+     */
+    play(id: string, onEnded: () => void): VoiceHandle;
+    /**
+     * What a skip does to a still-playing clip. `"cut"` (default) stops it and
+     * releases the gate the moment the player completes the typewriter or
+     * fast-forwards the section; `"ring"` lets the clip play out — auto-advance
+     * keeps waiting for `onEnded`, a manual advance still works (it is never gated).
+     */
+    onSkip?: "cut" | "ring";
+    /**
+     * Pause the clip when the conversation pauses ({@link DialogueSession.setPaused}).
+     * Default `true` — a paused conversation stops talking, the least-surprising
+     * default now that the channel knows a clip is mid-flight. Set `false` to let a
+     * clip play through a pause. `pause` / `resume` on the handle are optional, so
+     * this is a no-op when the host omits them.
+     */
+    pauseWithConversation?: boolean;
+    /**
+     * Safety budget (ms). If a clip's `onEnded` never arrives within this many ms
+     * of starting, the gate is force-released and {@link onError} is called — so a
+     * wedged host (a clip that silently fails to report its end) can't soft-lock
+     * auto-advance. Omit (or `0`) to disable the cap.
+     */
+    livenessMs?: number;
+    /** Diagnostics sink for the liveness cap — route it to the engine logger, the
+     *  same seam as the session's `onError`. */
+    onError?: (message: string, error: unknown) => void;
+}
+/**
+ * Build a voice-over {@link DialogueExtraChannel}. Register it on a controller:
+ *
+ *   const voice = createVoiceChannel({ play: (id, onEnded) => host.playClip(id, onEnded) });
+ *   controller.addChannel(voice);
+ *
+ * Hardened against two real failure modes:
+ *  - **generation guard** — a late `onEnded` from a clip that has since been
+ *    superseded (the next line started) can't ungate the new line.
+ *  - **liveness cap** — an optional budget force-releases the gate if a clip
+ *    never reports its end, so the conversation can't soft-lock.
+ *
+ * On a mid-line save/restore the host re-presents the current line, so `present`
+ * fires again here — it stops any active clip first, so a restore restarts the
+ * line's clip cleanly (the restore-safety property).
+ */
+declare function createVoiceChannel(opts: VoiceChannelOptions): DialogueExtraChannel;
+
+/**
+ * Lifecycle + command events the {@link DialogueController} emits from its host
+ * entity. A scene listens with `this.on(DialogueEndedEvent, …)` (events bubble
+ * entity → scene). `DialogueCommandEvent` is the main game hook: every script
+ * command that isn't a built-in (`set`) arrives here for the game to interpret.
+ */
+declare const DialogueStartedEvent: _yagejs_core.EventToken<{
+    scriptId: string;
+}>;
+declare const DialogueLineEvent: _yagejs_core.EventToken<{
+    speaker?: string | undefined;
+    /** Plain (markup-stripped) text — handy for logs, a11y, history. */
+    text: string;
+}>;
+declare const DialogueChoiceShownEvent: _yagejs_core.EventToken<{
+    options: readonly string[];
+}>;
+declare const DialogueChoiceMadeEvent: _yagejs_core.EventToken<{
+    index: number;
+    text: string;
+}>;
+declare const DialogueCommandEvent: _yagejs_core.EventToken<{
+    command: Command;
+    mode: RunMode;
+}>;
+declare const DialogueEndedEvent: _yagejs_core.EventToken<{
+    scriptId: string;
+}>;
+/**
+ * Lifecycle observation events. These are the moments games
+ * actually hook — a "typing finished" blip, a choice-hover tick, skip-used
+ * analytics, an auto-advance beat — emitted by the controller from the session's
+ * observation callbacks (the one canonical observation path; there are no
+ * matching controller callback options).
+ */
+/** A line finished its typewriter reveal — the "typing finished" hook. Plain
+ *  (markup-stripped) text, mirroring {@link DialogueLineEvent}. */
+declare const DialogueRevealCompletedEvent: _yagejs_core.EventToken<{
+    speaker?: string | undefined;
+    text: string;
+}>;
+/** The choice cursor moved (keyboard nav OR pointer hover) — `index` is the
+ *  original option index, `text` its plain label. */
+declare const DialogueSelectionChangedEvent: _yagejs_core.EventToken<{
+    index: number;
+    text: string;
+}>;
+/** The player skipped the current section (skip-used analytics). */
+declare const DialogueSkipUsedEvent: _yagejs_core.EventToken<{
+    scriptId: string;
+}>;
+/** A line advanced on its own via the auto-advance clock (vs a manual advance). */
+declare const DialogueAutoAdvanceEvent: _yagejs_core.EventToken<{
+    scriptId: string;
+}>;
+/**
+ * An inline `[name k=v/]` reveal marker reached its char offset during the
+ * current line's typewriter — the game hook for positional effects
+ * (`[sfx=ding/]` → play a sound). `viaSkip` is true when a skip / complete
+ * drained it, so a loud one-shot can be suppressed. The avatar channel handles
+ * `[expression=…/]` itself; the addon name-matches no marker, so every other
+ * name flows here opaquely. Per-grapheme typewriter *ticks* are deliberately NOT
+ * an event (they fire hundreds of times per line) — wire `onRevealTick` on the
+ * controller instead.
+ */
+declare const DialogueRevealMarkerEvent: _yagejs_core.EventToken<{
+    marker: MarkerToken;
+    viaSkip: boolean;
+}>;
+
+export { type Cell, ChoiceOption, ChoiceStep, Command, CommandContext, Condition, DialogueAutoAdvanceEvent, DialogueChoiceMadeEvent, DialogueChoiceShownEvent, DialogueCommandEvent, DialogueEndedEvent, DialogueExprError, DialogueExtraChannel, DialogueFunction, DialogueLineEvent, DialoguePlayError, DialogueRevealCompletedEvent, DialogueRevealMarkerEvent, DialogueRunner, DialogueScript, DialogueScriptError, DialogueSelectionChangedEvent, DialogueSkipUsedEvent, DialogueStartedEvent, EMPTY_PARSED, type EvalScope, Expr, MarkerToken, MemoryVariableStorage, ParsedText, type ResolvedChoice, RunMode, type RunnerEnv, type RunnerHandlers, SayStep, SpeakerDef, VarMap, VarValue, VariableStorage, type VoiceChannelOptions, type VoiceHandle, cells, compose, createVoiceChannel, evalCondition, evaluate, isExpr, loadCompact, loadScript, materialize, parseCompact, parseExpr, parseMarkup, splitGraphemes, stripMarkup };