@yagejs-addons/dialogue 0.1.0 → 0.2.0

package/dist/presenters.d.ts

@@ -0,0 +1,1817 @@
+import { Scene, Entity, Component } from '@yagejs/core';
+import { v as TextPresenter, p as PresentedLine, R as RevealBeat, w as DiagnosticSink, x as ChromePresenter, y as ChoicePresenter, o as PresentedChoice, a as ChoiceContext, z as AvatarPresenter, f as DialogueBundle } from './DialogueController-Cs5IUc-u.js';
+export { M as Mountable, N as NullAvatarPresenter } from './DialogueController-Cs5IUc-u.js';
+import { P as ParsedText, d as SpeakerDef, M as MarkerToken } from './types-DSbBSlh7.js';
+import { TextureInput, LayerDef } from '@yagejs/renderer';
+import '@yagejs/input';
+
+/**
+ * Font plumbing shared by the renderer-backed presenters: every chrome / choice
+ * presenter renders incidental text (nameplates, choice labels) the same way — an
+ * optional baked bitmap font wins, else the canvas family + resolution. One
+ * {@link FontConfig} triplet + one {@link makeTextOptions} builder keep the
+ * presenter configs and their `TextComponent` construction in lockstep.
+ *
+ * (Choice-row helpers — labelling, disabled-row dimming, highlight — live in
+ * `./choiceRow.js`.)
+ */
+
+/** The font triplet every presenter config carries (canvas by default). */
+interface FontConfig {
+    /** Baked bitmap-font name (OPT-IN crisp-pixel path). Omit for canvas text. */
+    readonly bitmapFont?: string | undefined;
+    /** Canvas font family (used when {@link bitmapFont} is omitted). */
+    readonly fontFamily?: string | undefined;
+    /** Canvas render resolution (used when not bitmap). */
+    readonly resolution?: number | undefined;
+}
+
+/**
+ * DialogueTextView — renders one parsed line as a single {@link SplitTextComponent}
+ * (the engine wrapper for Pixi `SplitText`/`SplitBitmapText`) on a screen-space
+ * layer, revealing it glyph-by-glyph (typewriter), honouring per-run colour/
+ * bold/italic, and driving animated effects.
+ *
+ * Reveal *timing* — the grapheme cursor, inline `[pause=ms/]`, per-run/line
+ * `[speed]`, the hold multiplier, and fired-once completion — is owned by the
+ * headless {@link LineReveal} clock (pixi-free, reusable by a DOM presenter).
+ * This view keeps only the pixi-`SplitText` concerns: mapping the clock's
+ * grapheme cursor onto glyph visibility and fanning per-glyph styles out.
+ *
+ * Why one split per LINE (not per word): SplitText does its own tokenize /
+ * measure / wrap / glyph-split, so we delegate layout to it instead of hand-
+ * rolling it. We then reach into the per-glyph `chars` for everything rich:
+ *   - reveal   → toggle `chars[i].visible` (no re-layout; split is done once)
+ *   - colour   → `chars[i].tint` per run (independent per glyph)
+ *   - bold/italic → reassign that glyph's `style` to a baked variant atlas
+ *       (the chars SHARE one style object, so we assign a fresh one rather than
+ *        mutate — mutating would restyle the whole line)
+ *   - effects  → per-glyph `position`/`scale`/`tint` (wave now ripples per letter)
+ *
+ * Pixi nests the split `root → line → word → char`, so a glyph's position in the
+ * split's own space is the sum up its parent chain ({@link localInSplit}).
+ *
+ * All reveal bookkeeping counts GRAPHEMES (`splitGraphemes` — the same
+ * segmentation SplitText uses to make one glyph node per user-perceived
+ * character), so emoji / ZWJ sequences / combining marks stay aligned between
+ * the cursor, `[pause]` offsets, per-glyph styles, and the rendered glyphs.
+ * `SplitText.chars` additionally drops whitespace, but our runs / reveal
+ * cursor / `[pause]` offsets count it, so we map "global grapheme index (with
+ * spaces) → non-space glyph index" via a prefix table.
+ *
+ * This file is the only renderer-coupled part of text rendering; it takes the
+ * scene + a font/layout config so nothing here is game-specific.
+ */
+
+interface DialogueTextConfig extends FontConfig {
+    /** Font size in px. */
+    readonly textSize: number;
+    /** Vertical advance between wrapped lines, in px. */
+    readonly lineHeight: number;
+    /** Colour for runs that don't override it (0xRRGGBB). */
+    readonly textColor: number;
+    /** Base reveal rate (graphemes/second). Scaled by per-run + hold speed. */
+    readonly charsPerSec: number;
+    /** Render layer name (screen-space). */
+    readonly layer: string;
+    /** Resting text region (screen px). Bubbles override per line via `setBox`. */
+    readonly box?: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+    };
+}
+declare class DialogueTextView implements TextPresenter {
+    private readonly cfg;
+    private scene?;
+    private line?;
+    private parsed?;
+    private boxX;
+    private boxY;
+    private wrapWidth;
+    /** Top-left the split container sits at (box origin). */
+    private layoutOriginX;
+    private layoutOriginY;
+    /** Optional per-frame origin (a moving NPC's head) for diegetic bubbles. */
+    private originProvider?;
+    /** `nonSpacePrefix[k]` = count of non-space graphemes among the first `k`. */
+    private nonSpacePrefix;
+    /** Non-space glyphs currently visible. */
+    private shownCount;
+    /** Headless reveal clock — owns the grapheme cursor, `[pause]` arming, hold +
+     *  per-line + per-run speed, and the fired-once completion. This view keeps
+     *  only the pixi-`SplitText` concerns (glyph prefix mapping + per-glyph style
+     *  fan-out) and maps the clock's grapheme cursor onto them. */
+    private readonly reveal;
+    /** Elapsed ms for animated per-glyph EFFECTS (wave/shake/…) — distinct from
+     *  the reveal cursor, which LineReveal owns. */
+    private elapsedMs;
+    /** Scratch for {@link evaluateEffect} — one object reused across all glyphs. */
+    private readonly effectScratch;
+    /** Reveal-completed listener, registered by the Session through
+     *  {@link setRevealListener} (a private seam, not a public field, so a
+     *  game can't clobber the session's wiring). */
+    private revealListener?;
+    /** Reveal-beat listener (ticks + inline markers), registered by the Session
+     *  through {@link setBeatListener} — same private-seam discipline. */
+    private beatListener?;
+    /** Master visibility gate ({@link setVisible}); hides the line WITHOUT
+     *  clearing it, so a hide/show round-trip resumes mid-typewriter. */
+    private hidden;
+    constructor(cfg: DialogueTextConfig);
+    /** Attach to a scene (host lifecycle). Must run before the first `present`. */
+    mount(scene: Scene): void;
+    /** Top-left of the text region, in screen px, plus the wrap width. */
+    setBox(x: number, y: number, width: number): void;
+    /**
+     * Make the text track a per-frame origin (a diegetic bubble following an
+     * NPC). The provider returns the top-left the laid-out box should sit at;
+     * pass `undefined` to pin the text (the default box-dialogue behaviour).
+     */
+    setOrigin(provider: (() => {
+        x: number;
+        y: number;
+    }) | undefined): void;
+    /** TextChannel entry point: render + reveal a fully-resolved line. */
+    present(line: PresentedLine): void;
+    /** TextChannel: reveal everything now. */
+    completeReveal(): void;
+    /** TextChannel: true once the line is fully revealed. */
+    isRevealComplete(): boolean;
+    /** Hold-to-speed multiplier (1 = normal, e.g. 3 while the skip key is held). */
+    setSpeedMultiplier(m: number): void;
+    isRevealing(): boolean;
+    /**
+     * Show or hide the body text WITHOUT disturbing reveal progress. Toggles
+     * the laid-out split container's visibility; the per-glyph reveal cursor,
+     * timers, and styling are untouched, so a cutscene can hide mid-typewriter and
+     * show again to resume exactly where it left off.
+     */
+    setVisible(visible: boolean): void;
+    /** Register the reveal-completed listener. Session-owned (a private seam, not a
+     *  public field a game could clobber); pass `undefined` to clear. */
+    setRevealListener(listener: (() => void) | undefined): void;
+    /** Register the reveal-beat listener (ticks + inline markers). Session-owned;
+     *  pass `undefined` to clear. The clock emits in char order as glyphs reveal. */
+    setBeatListener(listener: ((beat: RevealBeat) => void) | undefined): void;
+    /** Build the split for a parsed line and start revealing. */
+    show(parsed: ParsedText, lineSpeed?: number): void;
+    /** Apply the master visibility gate to the laid-out line — toggles the split
+     *  container, leaving the per-glyph reveal state intact. */
+    private applyHidden;
+    /** Reveal everything immediately (jump-to-end on a click/tap). */
+    skipToEnd(): void;
+    update(dt: number): void;
+    clear(): void;
+    /** Per-line teardown (also the first step of `show()`). The reveal clock is
+     *  re-armed by the next `show()` via {@link LineReveal.begin}, so there is no
+     *  reveal state to reset here. */
+    private clearLine;
+    /** Permanent teardown. (No measurer nodes to free — SplitText owns layout.) */
+    dispose(): void;
+    private buildLine;
+    /**
+     * One grapheme-segmentation pass per line (build-time only — nothing
+     * re-segments per frame), producing both reveal tables:
+     *   - `nonSpacePrefix`: grapheme cursor → count of non-space glyphs shown
+     *   - returned styles: the run-style for each NON-SPACE glyph, in reading
+     *     order (1:1 with SplitText's `chars`, which drops whitespace)
+     * Segmenting per run matches how markup.ts counted `length`/`atChar`, so
+     * the cursor, pauses, and styles all share one basis.
+     */
+    private buildRevealTables;
+    /**
+     * Apply a run's bold/italic to one glyph. On the bitmap path we must NOT swap
+     * to the baked variant atlas — each atlas has its own `baseLineOffset`, which
+     * lifts/drops a swapped glyph out of line with the regular runs. So we keep the
+     * regular-atlas glyph (baseline intact) and synthesise:
+     *   - italic → shear it in place (`skew.x`)
+     *   - bold   → overlay a 1px-offset copy as a CHILD, so it rides the parent's
+     *              reveal/visibility, tint cascade, skew, and per-frame effects for
+     *              free (no separate bookkeeping).
+     * On the canvas path, real bold/italic of the same family is baseline-safe, so
+     * we just set the style flags.
+     */
+    private applyWeight;
+    private applyReveal;
+    /**
+     * Per-frame placement: follow a moving origin (bubble mode) by moving the
+     * split container's `Transform` — every glyph inherits it — then apply
+     * per-glyph animated effects on top, in the glyph's own (parent) space.
+     * Only effect-bearing glyphs are walked; a static pinned line costs nothing.
+     */
+    private reposition;
+    /** Options for the per-line split: regular atlas, wrap to the box, white fill
+     *  (per-glyph `tint` carries the real colour). */
+    private lineSplitOptions;
+}
+
+/**
+ * The ONE shared "where does this speaker's bubble go" resolver.
+ *
+ * The three bubble presenters (`BubbleChrome`, `BubbleTextView`,
+ * `BubbleChoicePresenter`) all need the same answer for "anchor the bubble for
+ * speaker X", including the failure cases: a
+ * despawned NPC, a typo'd speaker, or a speakerless narrator line routed to a
+ * pure-bubble bundle. Three independent copies of that logic is exactly the bug
+ * class — so it lives here once. (A future layout owner can absorb this.)
+ *
+ * Policy:
+ *  - A **live actor** wins: use its head anchor, and refresh the caches.
+ *  - A **missing declared speaker** (despawn / typo) falls back to that
+ *    speaker's last-known position, else the most recent any-speaker anchor,
+ *    else a configurable anchor — and warns (at most once per speaker id per
+ *    resolver instance) through the diagnostics sink (→ engine Logger), never
+ *    `console.warn`.
+ *  - A **speakerless narrator** line (no id) uses the same fallback chain but
+ *    never warns — it is authored intent, not a failure.
+ *
+ * The bubble stays VISIBLE in every case — anchored to a sane fallback rather
+ * than hidden — so a line is always readable somewhere with its continue caret.
+ */
+
+interface AnchorPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/** Resolves a speaker id to a world anchor, with last-known caching + a
+ *  fallback for missing/absent actors. Each bubble presenter owns its own
+ *  instance; the position caches converge frame-to-frame (every resolver sees
+ *  the same live actors), but the missing-actor warning dedups *per instance* —
+ *  a missing speaker warns at most once per presenter that anchors it (so up to
+ *  ~2–3× across a bubble bundle), not once globally. A future single layout
+ *  owner could collapse these into one shared instance. */
+declare class BubbleAnchorResolver {
+    private readonly fallback;
+    private readonly lastKnown;
+    private lastAnchor;
+    private readonly warned;
+    private warn;
+    /**
+     * @param fallback Ultimate anchor when nothing better is known (a speaker
+     *   never seen and no prior bubble). Defaults to the world origin; a
+     *   pure-bubble bundle that shows narrator lines should point this at its
+     *   camera centre so a speakerless line lands on screen.
+     */
+    constructor(fallback?: () => AnchorPoint);
+    /** Wire the diagnostics sink (the controller injects the engine-Logger one). */
+    setDiagnostics(warn: DiagnosticSink): void;
+    /**
+     * World anchor for `speakerId`. Live actor → its anchor (caches refreshed).
+     * Missing → last-known for that speaker, else the most recent any-speaker
+     * anchor, else {@link fallback}. Warns at most once per declared speaker id
+     * (per resolver instance); a speakerless line never warns.
+     */
+    resolve(scene: Scene, speakerId: string | undefined): AnchorPoint;
+}
+
+interface BubbleSize {
+    readonly width: number;
+    readonly height: number;
+}
+
+/**
+ * BubbleLayout — the single per-line geometry owner for the speech-bubble
+ * coordinate model (the bubble half of the "layout owner"). One instance is
+ * injected into `BubbleChrome`, `BubbleTextView`, and `BubbleChoicePresenter` so
+ * they can no longer drift: the bubble outer size is measured **once** per line
+ * (memoized — the session always calls `chrome.present` then `text.present` with
+ * the same line object, so the second read is free), the missing-actor anchor
+ * policy lives in ONE {@link BubbleAnchorResolver}, and the anchor→inner-top-left
+ * origin formula exists once.
+ *
+ * It owns the bubble *geometry* (sizing inputs + padding/offsetY); the
+ * presenters keep only their drawing config (colours, tail, caret).
+ */
+
+interface BubbleLayoutConfig {
+    /** Snuggest width; the bubble widens to its text up to {@link maxWidth}. */
+    readonly minWidth: number;
+    /** Widest the bubble grows before its text wraps to more lines. */
+    readonly maxWidth: number;
+    /** Minimum bubble height (px); grows past this to fit wrapped text. */
+    readonly height: number;
+    readonly padding: number;
+    /** Gap between the actor's head anchor and the bubble's bottom edge. */
+    readonly offsetY: number;
+    /** Body-text metrics the size measures with (the text view wraps to the same). */
+    readonly textSize: number;
+    readonly lineHeight: number;
+    readonly fontFamily?: string | undefined;
+    readonly bitmapFont?: string | undefined;
+    /** Anchor for a missing/absent speaker with no last-known position. Default
+     *  world origin; point it at the camera centre for a pure-bubble bundle that
+     *  shows narrator lines. */
+    readonly fallbackAnchor?: (() => AnchorPoint) | undefined;
+}
+/** A reserved portrait column INSIDE the bubble: the bubble grows to contain it
+ *  and the body text reflows past it (the in-bubble avatar registers one). */
+interface BubblePortraitInset {
+    readonly side: "left" | "right";
+    /** Full reserved column width (portrait + gap), px. */
+    readonly width: number;
+    /** Min content height the bubble clears for the portrait, px. */
+    readonly height: number;
+}
+declare class BubbleLayout {
+    private readonly cfg;
+    private readonly anchors;
+    /** One-line memo: the session presents one line to chrome then text, so a
+     *  one-deep cache makes the second `sizeFor` free (no redundant measure pass). */
+    private memoLine;
+    private memoSize;
+    /** Reserved portrait column for the current line (set by the in-bubble avatar
+     *  before the chrome/text present). */
+    private inset;
+    /** The current bubble content size — the say bubble (from {@link sizeFor}) or a
+     *  choice panel (from {@link setChoicePanelSize}). The in-bubble avatar centres
+     *  in this, so it follows whichever is on screen. */
+    private active;
+    private readonly listeners;
+    constructor(cfg: BubbleLayoutConfig);
+    /** Reserve (or clear with `undefined`) a portrait column inside the bubble.
+     *  The bubble (and a bubble choice panel) then grows to contain it and the
+     *  text/rows reflow to the narrowed column; the avatar sets this per line
+     *  before the chrome/text/choices present. */
+    setPortraitInset(inset: BubblePortraitInset | undefined): void;
+    /** The reserved portrait column (or undefined) — a bubble choice presenter
+     *  reads it to reflow its panel around the portrait. */
+    portraitInset(): BubblePortraitInset | undefined;
+    /** Register a callback fired when the active bubble content size changes (a
+     *  say line sizes its bubble, or a choice commits its panel) — the in-bubble
+     *  avatar re-places. */
+    onChange(listener: () => void): void;
+    /** The current bubble content size the avatar centres in (say bubble or choice
+     *  panel). */
+    activeSize(): BubbleSize | undefined;
+    /** A bubble choice presenter commits its (inset-grown) panel size here so the
+     *  in-bubble avatar follows the panel, not the say bubble. */
+    setChoicePanelSize(size: BubbleSize): void;
+    private setActive;
+    /** Inner padding (px) — the presenters position the name/caret/text by it. */
+    get padding(): number;
+    /** Gap between the speaker anchor and the bubble's bottom edge (px). */
+    get offsetY(): number;
+    /** Wire the missing-actor warning to the engine Logger (the controller's sink). */
+    setDiagnostics(warn: DiagnosticSink): void;
+    /** Outer bubble size to fit this line's text (+ a reserved portrait column,
+     *  if one is registered) — measured once, then memoized for the companion
+     *  presenter's read of the same line. */
+    sizeFor(line: PresentedLine): BubbleSize;
+    /** Body-text wrap width inside the bubble — the inner width minus the
+     *  reserved portrait column (so the text reflows past an in-bubble avatar). */
+    textWrapWidth(size: BubbleSize): number;
+    /** World anchor for a speaker: a live {@link DialogueActor}'s head, else the
+     *  last-known / fallback position (and a once-per-speaker warning). Shared by
+     *  all three bubble presenters so they track the same actor. */
+    anchorFor(scene: Scene, speakerId: string | undefined): AnchorPoint;
+    /** Inner top-left a content-sized bubble's body sits at, from the speaker
+     *  anchor + the bubble size (the once-derived origin formula). Shifts past a
+     *  left-side portrait column so the text reflows beside it. */
+    originFor(anchor: AnchorPoint, size: BubbleSize): {
+        x: number;
+        y: number;
+    };
+}
+
+/**
+ * A {@link DialogueTextView} that lays its body text inside a diegetic bubble
+ * and follows the speaking actor. Per line it asks the shared {@link BubbleLayout}
+ * for the bubble size + the speaker anchor, and points the view's origin
+ * provider at the bubble's inner top-left. Because the size and anchor come from
+ * the SAME owner the companion {@link BubbleChrome} reads, the text always sits
+ * inside its frame — no per-presenter sizing copies to drift. All the
+ * typewriter / effect / markup machinery is inherited unchanged.
+ */
+
+declare class BubbleTextView extends DialogueTextView {
+    private readonly layout;
+    private sceneRef?;
+    constructor(cfg: Omit<DialogueTextConfig, "box">, layout: BubbleLayout);
+    mount(scene: Scene): void;
+    /** Route the missing-actor warning to the engine Logger (the layout owns the
+     *  shared anchor resolver). The base view has no diagnostics of its own. */
+    setDiagnostics(warn: DiagnosticSink): void;
+    present(line: PresentedLine): void;
+}
+
+/**
+ * DialogueTheme — the single flat visual-config object the dialogue factories
+ * consume. A theme is a plain data object (no behaviour) so it can be authored
+ * inline, imported from a preset module, or serialized.
+ *
+ * The factories ({@link createBoxDialogue}, {@link createBubbleDialogue},
+ * {@link createMixedDialogue}) map every field below onto the chrome / text /
+ * choice presenter configs. The mapping is mechanical: a presenter-config field
+ * has the SAME name as the theme field it comes from (e.g. theme `frameColor` →
+ * config `frameColor`), so drift is visible and a `dialogue.exhaustiveness`
+ * test asserts every field reaches a presenter.
+ *
+ * {@link defaultTheme} returns a zero-asset instance (Graphics chrome + canvas
+ * text, no `bitmapFont`/`textured`), so the factories work with no
+ * caller-supplied theme.
+ *
+ * Bitmap fonts (`bitmapFont`) are an OPT-IN crisp-pixel path. Textured
+ * nine-slice chrome is a separate opt-in re-theming path driven by the
+ * {@link textured} field.
+ */
+
+/**
+ * Viewport-relative bounds for the dialogue box (virtual px). The box is a
+ * full-width bottom bar resolved against the renderer's design size at mount, so
+ * the default presenter works at ANY virtual resolution with no override: the
+ * width is `viewport.width - 2*marginX`, and the frame anchors `marginY` from the
+ * screen edge. `meta.position` reuses these: `bottom` (default) anchors at the
+ * bottom edge, `top` mirrors `marginY` to the top, `center` ignores it.
+ */
+interface BoxBounds {
+    /** Horizontal margin from the left and right screen edges (virtual px). */
+    readonly marginX: number;
+    /** Vertical margin from the anchored screen edge — the bottom by default, the
+     *  top for `meta.position: top` (the centred position ignores it). */
+    readonly marginY: number;
+    /** Box height (virtual px) — sized to hold the body text, not the screen, so
+     *  it holds the same number of lines at any resolution. */
+    readonly height: number;
+}
+/** Continue-caret styling. The caret is the blinking "press to advance"
+ *  triangle every chrome draws at its bottom-right; both fields are optional —
+ *  omit them for the built-in defaults ({@link DEFAULT_CARET_BLINK_MS} /
+ *  {@link DEFAULT_CARET_SIZE}). The nested-group shape is the convention the
+ *  (cut) glossary `term` styling returns into. */
+interface CaretTheme {
+    /** Blink time constant (ms) in `0.35 + 0.65·(0.5 + 0.5·sin(t/blinkMs))`.
+     *  Larger = slower pulse. Default {@link DEFAULT_CARET_BLINK_MS}. */
+    readonly blinkMs?: number;
+    /** Triangle size (px). Default {@link DEFAULT_CARET_SIZE} (7×5, pointing down). */
+    readonly size?: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+interface DialogueTheme {
+    /** Box geometry as viewport-relative margins + height — a full-width bottom
+     *  bar resolved against the renderer's design size, so it works at any
+     *  resolution with no override. See {@link BoxBounds}. */
+    readonly box: BoxBounds;
+    /** Inner padding between the frame and its contents. */
+    readonly padding: number;
+    readonly frameColor: number;
+    readonly frameAlpha: number;
+    readonly borderColor: number;
+    readonly cornerRadius: number;
+    readonly nameColor: number;
+    readonly nameSize: number;
+    /** Blinking "continue" caret colour. */
+    readonly indicatorColor: number;
+    /** Continue-caret blink + size (optional; built-in defaults otherwise). */
+    readonly caret?: CaretTheme;
+    readonly textSize: number;
+    readonly lineHeight: number;
+    readonly textColor: number;
+    /** Base reveal rate (characters/second). */
+    readonly charsPerSec: number;
+    readonly choiceSize: number;
+    readonly choiceColor: number;
+    readonly choiceSelectedColor: number;
+    readonly highlightColor: number;
+    /** Vertical gap (px) between choice rows. One value for box and bubble lists
+     *  (a per-bundle override stays possible via the presenter config). Optional;
+     *  default {@link DEFAULT_CHOICE_GAP}. */
+    readonly choiceGap?: number;
+    /** Bubble tail tip offset from the speaker anchor (px), the little
+     *  asymmetric "lean" of the pointer. Optional; default {@link DEFAULT_TAIL_LEAN}.
+     *  Bubble *size* (min/max width, height, tail height) is geometry, set via
+     *  `createBubbleDialogue`'s `bubble` option, not the theme. */
+    readonly tailLean?: {
+        readonly x: number;
+        readonly y: number;
+    };
+    /**
+     * Baked bitmap-font name (OPT-IN). Omit for canvas text. When set, the
+     * presenters render with the crisp pixel atlas instead of canvas SplitText.
+     * Bold/italic are synthesised on the regular atlas (skew + double-draw);
+     * variant-atlas fields will return if a baseline-compensating crisp path
+     * lands in the renderer.
+     */
+    readonly bitmapFont?: string;
+    /** Canvas font family (used when {@link bitmapFont} is omitted). */
+    readonly fontFamily?: string;
+    /** Canvas render resolution (used when not bitmap). */
+    readonly resolution?: number;
+    /** Layer for the frame + selection highlight + continue caret. */
+    readonly layerFrame: string;
+    /** Layer for all text (name, body, choice labels). */
+    readonly layerText: string;
+    /** Hold-to-fast-forward multiplier. Default 4 (applied by the session). */
+    readonly skipMultiplier?: number;
+    /**
+     * Optional textured nine-slice chrome (OPT-IN) — a MAP of named
+     * {@link ChromeStyle}s. A box line picks one by name through its
+     * `meta.chrome` key; the box chrome renders that style's `frame` as a
+     * stretchable nine-slice instead of the drawn rounded rect, and the bubble
+     * renders the `"default"` style's `bubble` (if any). Two style names are
+     * reserved:
+     *   - `"default"` — the look used for box lines with no (or an unknown)
+     *     `meta.chrome`. Omit it to keep the drawn Graphics frame as the default.
+     *   - `"none"` — built-in (needs no entry); hides the box frame entirely for
+     *     that line (e.g. a full-bleed narration line).
+     *
+     * Leave `textured` undefined for the Graphics-only default path.
+     */
+    readonly textured?: Readonly<Record<string, ChromeStyle>>;
+}
+/**
+ * NineSliceInsets — the four immutable border widths (in source-texture pixels)
+ * that define a nine-slice frame. The center + edges stretch; the corners stay
+ * fixed. Matches Pixi's NineSliceSprite `leftWidth`/`topHeight`/etc.
+ */
+interface NineSliceInsets {
+    /** Fixed-width left border in texture pixels. */
+    readonly left: number;
+    /** Fixed-height top border in texture pixels. */
+    readonly top: number;
+    /** Fixed-width right border in texture pixels. */
+    readonly right: number;
+    /** Fixed-height bottom border in texture pixels. */
+    readonly bottom: number;
+}
+/**
+ * A single nine-slice texture frame: the source texture plus its border insets.
+ * Textures are referenced by {@link TextureInput} (string key or Texture) so the
+ * theme stays serializable. Used for both box frames and speech bubbles.
+ */
+interface NineSliceFrame {
+    /** Nine-slice texture (string asset key or a resolved Texture). */
+    readonly texture: TextureInput;
+    /** Border insets for {@link texture}, in source-texture pixels. */
+    readonly insets: NineSliceInsets;
+}
+/**
+ * A named chrome style: a box-frame nine-slice and, optionally, a matching
+ * speech-bubble nine-slice. A box line selects a style by name via its
+ * `meta.chrome` key (see {@link DialogueTheme.textured}); the speech bubble uses
+ * the `"default"` style's `bubble` for every bubble line (per-line bubble
+ * variants are not a thing — bubbles are diegetic, anchored to an actor).
+ */
+interface ChromeStyle {
+    /** Box-frame nine-slice for this style. */
+    readonly frame: NineSliceFrame;
+    /** Speech-bubble nine-slice (only the `"default"` style's `bubble` is read).
+     *  Omit to keep the drawn Graphics bubble. */
+    readonly bubble?: NineSliceFrame;
+}
+/** Default continue-caret blink time constant (ms). */
+declare const DEFAULT_CARET_BLINK_MS = 260;
+/** Default continue-caret triangle size (px), pointing down. */
+declare const DEFAULT_CARET_SIZE: {
+    readonly width: number;
+    readonly height: number;
+};
+/** Default vertical gap (px) between choice rows (box + bubble). */
+declare const DEFAULT_CHOICE_GAP = 6;
+/** Default bubble tail tip offset from the speaker anchor (px). */
+declare const DEFAULT_TAIL_LEAN: {
+    readonly x: number;
+    readonly y: number;
+};
+/** Reserved `meta.chrome` / {@link DialogueTheme.textured} key: the box look
+ *  used when a line carries no (or an unknown) `meta.chrome`. */
+declare const CHROME_STYLE_DEFAULT = "default";
+/** Reserved `meta.chrome` value (built-in, needs no `textured` entry): hide the
+ *  box frame for that line. */
+declare const CHROME_STYLE_NONE = "none";
+
+/**
+ * BoxLayout — the single per-line geometry owner for the bottom-box coordinate
+ * model (the box half of the "layout owner"). One instance is shared by the box
+ * chrome, the box text view, the box choice list, and an in-box avatar
+ * presenter, so the **frame, nameplate, prompt, and choice rows move and grow as
+ * ONE coherent panel** instead of each presenter holding its own copy.
+ *
+ * It owns three things the presenters would otherwise compute independently:
+ *
+ *  - **Per-line position** — `meta.position` (`top|center|bottom`) places the
+ *    frame within the design viewport (the renderer's `virtualSize`, bound at
+ *    mount via {@link setViewport}); the frame AND the text region move together.
+ *    The box is a full-width bottom bar resolved from viewport-relative margins,
+ *    so the default presenter works at any resolution with no override.
+ *  - **Unified panel grow** — for a choice, the frame grows to fit the nameplate
+ *    + prompt + rows; the row rects are stacked inside it (see
+ *    `stackChoiceRows`). Growing is bottom-anchored at "bottom", so the frame top
+ *    rises and the chrome/nameplate/prompt follow.
+ *  - **Inset registry** — a presenter reserves a left/right column; the text
+ *    region subtracts it so the body text reflows around it (the reference
+ *    in-box avatar registers one).
+ *
+ * Presenters call {@link onChange} to re-place when the committed frame changes
+ * (a choice grows the frame after the chrome/text already presented).
+ */
+
+/** RPG-Maker-style vertical placement of the box within the field. */
+type BoxPosition = "top" | "center" | "bottom";
+/** A reserved column the body text reflows around (the avatar-reflow seam). */
+interface TextInset {
+    readonly side: "left" | "right";
+    readonly width: number;
+}
+/** A laid-out rectangle (screen px). */
+interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A choice row's screen rect — shared by placement, highlight, and hit-test. */
+interface ChoiceRowRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface BoxLayoutConfig {
+    /** Viewport-relative box bounds (margins + height); the frame is resolved
+     *  against the design viewport set by {@link BoxLayout.setViewport} at mount. */
+    readonly box: BoxBounds;
+    readonly padding: number;
+    /** Nameplate band height (theme.nameSize) — body text starts below it. */
+    readonly nameSize: number;
+    /** Body text metrics — for measuring an optional choice prompt's height. */
+    readonly textSize: number;
+    readonly lineHeight: number;
+    /** Vertical gap between choice rows (for the grown panel). */
+    readonly choiceGap: number;
+    readonly fontFamily?: string | undefined;
+    readonly bitmapFont?: string | undefined;
+}
+/**
+ * Stack choice-row slots bottom-up inside `box`, growing **upward** from the
+ * bottom edge. `rowHeights` are full slot heights (wrapped text height + gap).
+ * Rows are always contiguous and non-overlapping. Inside a frame the owner grew
+ * to fit, the topmost row lands right below the prompt; in a too-tall menu the
+ * excess spills off the top (the soft-cap advisory flags that). The single
+ * source of row geometry: placement, highlight, and hit-test all consume it.
+ */
+declare function stackChoiceRows(rowHeights: readonly number[], box: Rect, padding: number): ChoiceRowRect[];
+declare class BoxLayout {
+    private readonly cfg;
+    /** Design viewport (the renderer's `virtualSize`) the box is placed within —
+     *  bound at mount via {@link setViewport}. Defaults to a sane size so headless
+     *  use (no renderer) and pre-mount calls still produce a valid frame. */
+    private viewW;
+    private viewH;
+    private readonly insets;
+    private readonly listeners;
+    /** The committed frame — moved by `meta.position`, grown for a choice. */
+    private frame;
+    /** The line currently laid out (for the choice panel's prompt + nameplate). */
+    private line;
+    constructor(cfg: BoxLayoutConfig);
+    /**
+     * Bind the design viewport (the renderer's `virtualSize`), read at mount, so
+     * the box is a full-width bottom bar at any resolution and `meta.position`
+     * places the frame against the true screen. Recomputes the resting frame.
+     */
+    setViewport(width: number, height: number): void;
+    /** Register a callback fired when the committed frame changes (a choice grows
+     *  it, or an inset reflows the text) — the chrome redraws, the text re-places. */
+    onChange(listener: () => void): void;
+    /** The frame rect for the current line (read by the chrome to draw + place). */
+    frameRect(): Rect;
+    /** Inner content width — choice rows wrap to this. Frame minus padding minus
+     *  any registered insets, so choices reflow around an in-box avatar the same
+     *  way the body text does. */
+    contentWidth(): number;
+    /** Inner padding between the frame and its contents — an in-box presenter
+     *  aligns its column to this so it sits inside the border, like the text. */
+    padding(): number;
+    /** Lay out a say/prompt line: place the base-height frame at its
+     *  `meta.position`. Commits the frame (firing {@link onChange} if it moved). */
+    layoutLine(line: PresentedLine | undefined): Rect;
+    /**
+     * Grow the frame to fit a choice: nameplate band + optional prompt + the
+     * rows, capped at the field. Commits the grown frame (firing {@link onChange}
+     * so the chrome/nameplate/prompt follow) and returns the row rects stacked
+     * inside it.
+     */
+    layoutChoicePanel(rowHeights: readonly number[]): ChoiceRowRect[];
+    /** Body-text region inside the current frame: below the nameplate band, inset
+     *  by padding, minus any registered insets (so text reflows around an avatar).
+     *  For a choice, this is the prompt region above the rows. */
+    textRegion(): {
+        x: number;
+        y: number;
+        width: number;
+    };
+    /** Top-left of the nameplate inside the current frame. */
+    nameplatePos(): {
+        x: number;
+        y: number;
+    };
+    /** Bottom-right continue-caret position inside the current frame. */
+    caretPos(size: {
+        width: number;
+        height: number;
+    }): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Reserve (or clear with `undefined`) a left/right column the body text
+     * reflows around — the avatar-reflow seam. The reference in-box avatar
+     * presenter registers one keyed by its own id. Fires {@link onChange} so a
+     * text view already showing this line reflows.
+     */
+    setInset(key: string, inset: TextInset | undefined): void;
+    /** The reserved width on a side (0 if none) — an avatar presenter reads it to
+     *  place itself in the column it reserved. */
+    insetWidth(side: "left" | "right"): number;
+    /** Distance from the frame top to the body text (nameplate band + gap). */
+    private bodyOffset;
+    /** Measure the current choice line's prompt (0 when there is none). */
+    private promptHeight;
+    /** Place a full-width frame of `height` at `position` within the design
+     *  viewport: `bottom` anchors `marginY` from the bottom edge, `top` mirrors it
+     *  to the top, `center` centres. The width is the viewport minus side margins. */
+    private frameAt;
+    private commit;
+    private notify;
+}
+
+/**
+ * A {@link DialogueTextView} that reads its body-text region from the shared
+ * {@link BoxLayout} instead of a fixed box. Per line it wraps to the owner's
+ * current text region (which the owner narrows for a registered avatar inset, so
+ * the text reflows around it) and tracks the region's top-left via the origin
+ * provider, so when `meta.position` moves the frame or a choice grows it, the
+ * body follows. This mirrors {@link BubbleTextView}, which follows the speaker
+ * anchor the same way.
+ */
+
+declare class BoxTextView extends DialogueTextView {
+    private readonly layout;
+    constructor(cfg: Omit<DialogueTextConfig, "box">, layout: BoxLayout);
+    present(line: PresentedLine): void;
+}
+
+/**
+ * Screen-space render layers the dialogue system draws into. They sit ABOVE
+ * the auto-provisioned ui-react layer (order 1000) so a conversation overlays
+ * any in-scene React chrome, and `space: "screen"` pins the box to the
+ * viewport (it doesn't scroll/zoom with the world camera).
+ *
+ * A host scene opts in by spreading `DIALOGUE_LAYERS` into its `layers` field:
+ *   readonly layers = [...DIALOGUE_LAYERS];
+ */
+declare const DIALOGUE_LAYER_FRAME = "dialogue-frame";
+declare const DIALOGUE_LAYER_TEXT = "dialogue-text";
+declare const DIALOGUE_LAYER_AVATAR = "dialogue-avatar";
+declare const DIALOGUE_LAYERS: readonly LayerDef[];
+
+/**
+ * Per-glyph animated text effects. The line is one `SplitTextComponent`; we
+ * animate each glyph node (`chars[i]`) individually, phased by its position
+ * along the line — so `[wave]` ripples letter-by-letter, `[shake]` jitters each
+ * glyph, `[rainbow]` cycles per glyph. Effects are pure functions of time + the
+ * glyph's resting x (the phase), so they're deterministic and snapshot-safe.
+ *
+ * The effect name is an OPEN vocabulary (any `[name]` markup tag). This bundled
+ * evaluator animates the four built-ins (wave / shake / pulse / rainbow — the
+ * `BuiltinEffectId`s) and treats any other name — one a custom text channel owns,
+ * or a typo — as a no-op (identity transform), so the run renders as plain styled
+ * text.
+ */
+/** Mutable so a per-frame caller can reuse one scratch instance (see `out`). */
+interface EffectOutput {
+    /** Offset from the run's resting position, in px. */
+    dx: number;
+    dy: number;
+    /** Uniform scale multiplier (1 = none). */
+    scale: number;
+    /** Tint override (0xRRGGBB), or undefined to keep the run's base colour. */
+    tint: number | undefined;
+}
+/**
+ * @param effect    which effect by name (undefined or an unrecognized name → no motion)
+ * @param timeMs    elapsed time the run has been on screen
+ * @param phase     a per-run phase seed (use the run's resting x) so adjacent
+ *                  runs animate out of sync instead of in lockstep
+ * @param out       optional scratch object, reset and returned — pass one per
+ *                  caller to avoid an allocation per animated glyph per frame
+ */
+declare function evaluateEffect(effect: string | undefined, timeMs: number, phase: number, out?: EffectOutput): EffectOutput;
+/** True if the effect needs a tint each frame (so the view skips static tint).
+ *  False for an unrecognized name (it animates nothing). */
+declare function effectDrivesTint(effect: string | undefined): boolean;
+
+/**
+ * Default chrome — draws the dialogue box frame, the name plate, and the
+ * blinking "continue" caret with the renderer (Graphics + Text on screen-space
+ * layers), so this addon needs only renderer + core, not ui-react. The choice
+ * list lives in its own {@link ChoiceListPresenter}; the body text lives in
+ * {@link DialogueTextView}. This class owns only the frame + nameplate + caret,
+ * which makes z-order deterministic and the seams swappable independently.
+ *
+ * Geometry comes from the shared {@link BoxLayout}: the frame rect (moved per
+ * line by `meta.position`, grown to fit a choice's rows), the nameplate spot,
+ * and the caret spot. The chrome subscribes to the owner so when a choice grows
+ * the frame after the chrome already presented, it redraws + repositions — the
+ * frame, nameplate, prompt, and rows stay ONE coherent panel.
+ *
+ * The frame renders one of three ways per line, chosen by the line's
+ * `meta.chrome` key (box only): a named {@link NineSliceFrame} from
+ * {@link DialogueChromeConfig.frameStyles}, the built-in `"none"` (no frame), or
+ * the drawn Graphics rounded rect (the default).
+ */
+
+interface DialogueChromeConfig extends FontConfig {
+    readonly frameColor: number;
+    readonly frameAlpha: number;
+    readonly borderColor: number;
+    readonly cornerRadius: number;
+    readonly nameColor: number;
+    readonly nameSize: number;
+    readonly indicatorColor: number;
+    /** Continue-caret blink + size (built-in defaults when omitted). */
+    readonly caret?: CaretTheme | undefined;
+    /** Named nine-slice box-frame styles, keyed to match `meta.chrome`. The
+     *  reserved `"default"` entry is the no-meta look; `"none"` is built-in and
+     *  needs no entry. Omit the whole field for the Graphics-only default. */
+    readonly frameStyles?: Readonly<Record<string, NineSliceFrame>> | undefined;
+    /** Frame + continue indicator. */
+    readonly layerFrame: string;
+    /** Name plate (drawn above the frame layer). */
+    readonly layerText: string;
+}
+declare class DialogueChrome implements ChromePresenter {
+    private readonly cfg;
+    private readonly layout;
+    private frame?;
+    private frameGfx?;
+    /** Separate entity hosting the nine-slice sprites (one per textured style);
+     *  only spawned when {@link DialogueChromeConfig.frameStyles} has entries. Its
+     *  Transform tracks the per-line frame origin so the sprites draw at local 0. */
+    private frameTex?;
+    private frameTexTransform?;
+    private nineSliceHost?;
+    private readonly nineSlices;
+    private name?;
+    private indicator?;
+    private indicatorTime;
+    /** Selected textured-style name from the line's `meta.chrome`, or undefined
+     *  when the line names none. */
+    private styleKey;
+    private warn?;
+    private readonly warnedKeys;
+    /** Master gate (from {@link setVisible}); the Session drives it. Hidden at
+     *  mount until a line shows. The name/caret also need their own content
+     *  sub-state — each renders only when shown AND its content is present. */
+    private visible;
+    private nameShown;
+    private caretShown;
+    constructor(cfg: DialogueChromeConfig, layout: BoxLayout);
+    /** Route the unknown-`meta.chrome` warning to the engine Logger. */
+    setDiagnostics(warn: DiagnosticSink): void;
+    mount(scene: Scene): void;
+    setNameplate(name: string | undefined, color?: number): void;
+    setContinueVisible(visible: boolean): void;
+    /** Place this line's frame at its `meta.position` and pick its `meta.chrome`
+     *  style. Box only; the bubble ignores both. `undefined` (no line) resets to
+     *  the default look at the resting position. */
+    present(line: PresentedLine | undefined): void;
+    /** Show or hide the whole box. State-preserving — the name/caret content
+     *  sub-state survives, so showing again restores exactly what was up. */
+    setVisible(visible: boolean): void;
+    /** Redraw the frame + reposition the nameplate and caret from the owner's
+     *  current geometry (per line, and when a choice grows the frame). */
+    private applyGeometry;
+    /** Render each piece = master-visible AND its own content present. */
+    private apply;
+    update(dt: number): void;
+    dispose(): void;
+}
+
+/**
+ * Default choice presenter — a vertical list inside the box, with a highlight
+ * bar behind the selected row. Split out of `DialogueChrome` so the choice UI is
+ * swappable (a radial / Mass-Effect wheel, a separate panel, a touch list)
+ * without touching the frame or body text. Selection *navigation* lives in the
+ * Session; this presenter only paints what it's told and reports pointer commits
+ * back through {@link ChoiceChannel.onChoiceChosen}.
+ *
+ * Overflow + unified panel: labels word-wrap (a row may be several lines), and
+ * the row stack is laid out by the shared {@link BoxLayout}, which **grows the
+ * surrounding frame** to fit the rows + prompt + nameplate as one panel (a list
+ * too tall for the screen spills off the bottom, non-overlapping). Row
+ * placement, the selection highlight, and pointer hit-testing all derive from
+ * the ONE set of row rects the owner returns, so a wrapped/overflowing row can't
+ * desync them. A list longer than `softMaxChoices` logs a soft-cap advisory.
+ */
+
+interface ChoiceListConfig extends FontConfig {
+    readonly choiceSize: number;
+    readonly choiceColor: number;
+    readonly choiceSelectedColor: number;
+    readonly highlightColor: number;
+    /** Vertical gap (px) between choice rows. Default {@link DEFAULT_CHOICE_GAP}. */
+    readonly choiceGap?: number | undefined;
+    /** Soft cap on option count: more than this logs an advisory (the list still
+     *  grows to fit). Default {@link DEFAULT_SOFT_MAX_CHOICES}. */
+    readonly softMaxChoices?: number | undefined;
+    /** Selection highlight bar. */
+    readonly layerFrame: string;
+    /** Choice labels (drawn above the frame layer). */
+    readonly layerText: string;
+}
+declare class ChoiceListPresenter implements ChoicePresenter {
+    private readonly cfg;
+    private readonly layout;
+    private scene?;
+    private highlightBar?;
+    private rows;
+    private selected;
+    private warn?;
+    /** Master visibility gate — hides the list WITHOUT clearing it, so a
+     *  hide/show round-trip keeps the rows + selection. */
+    private hidden;
+    onChoiceChosen?: (position: number) => void;
+    constructor(cfg: ChoiceListConfig, layout: BoxLayout);
+    /** Route the soft-cap advisory to the engine Logger. */
+    setDiagnostics(warn: DiagnosticSink): void;
+    mount(scene: Scene): void;
+    present(choices: readonly PresentedChoice[]): void;
+    highlight(position: number): void;
+    /** Show or hide the list without clearing it — state-preserving. */
+    setVisible(visible: boolean): void;
+    /** Render = rows present AND not hidden. Disabled rows still show (greyed). */
+    private applyHidden;
+    /** {@link PointerChoiceTarget}: which row (if any) a screen point falls in —
+     *  from the same grown rects the rows are drawn at. */
+    choiceAtPoint(x: number, y: number): number | undefined;
+    clear(): void;
+    dispose(): void;
+    private highlightAt;
+    private drawHighlight;
+    private textOptions;
+}
+
+/**
+ * Diegetic speech-bubble chrome: a rounded bubble + downward tail drawn on a
+ * *world* layer, repositioned every frame to sit above the speaking actor's
+ * head. The per-line size, the speaker→world anchor (incl. the missing-actor
+ * fallback), and the inner-top-left origin all come from the shared
+ * {@link BubbleLayout} — the single owner the companion {@link BubbleTextView}
+ * and {@link BubbleChoicePresenter} read too, so they can never drift. This
+ * class keeps only the bubble's *drawing* config (colours, tail, caret, name).
+ *
+ * The bubble is content-sized per line (see {@link BubbleLayout.sizeFor}); the
+ * companion text view wraps to the same inner width so they stay aligned. With a
+ * textured {@link BubbleChromeConfig.frame}, the body renders as a nine-slice
+ * stretched to that same per-line size (the tail stays a drawn triangle).
+ */
+
+interface BubbleChromeConfig extends FontConfig {
+    /** World-space render layer. */
+    readonly layer: string;
+    /** Tail height (the little pointer toward the speaker). */
+    readonly tail: number;
+    /** Tail tip offset from the speaker anchor (the asymmetric "lean"). */
+    readonly tailLean?: {
+        readonly x: number;
+        readonly y: number;
+    } | undefined;
+    readonly frameColor: number;
+    readonly frameAlpha: number;
+    readonly borderColor: number;
+    readonly cornerRadius: number;
+    readonly nameColor: number;
+    readonly nameSize: number;
+    readonly indicatorColor: number;
+    /** Continue-caret blink + size (built-in defaults when omitted). */
+    readonly caret?: CaretTheme | undefined;
+    /** Optional textured nine-slice for the bubble body (the `"default"` style's
+     *  `bubble`). Resized per line; omit for the drawn Graphics bubble. */
+    readonly frame?: NineSliceFrame | undefined;
+}
+declare class BubbleChrome implements ChromePresenter {
+    private readonly cfg;
+    private readonly layout;
+    private scene?;
+    private root?;
+    private gfx?;
+    private transform?;
+    /** Nine-slice body sprite (child of {@link gfx}) when textured; resized per
+     *  line. The tail stays a drawn triangle on {@link gfx}. */
+    private bubbleSlice?;
+    private name?;
+    private nameTransform?;
+    private caret?;
+    private caretTransform?;
+    private caretTime;
+    /** Current (content-sized) bubble size; recomputed per line from the layout. */
+    private currentWidth;
+    private currentHeight;
+    private visible;
+    private hasLine;
+    private nameShown;
+    private caretShown;
+    /** Speaker id of the line on screen — re-resolved each frame by `follow()` so
+     *  the bubble tracks a live actor and falls back when one is missing. */
+    private speakerId;
+    constructor(cfg: BubbleChromeConfig, layout: BubbleLayout);
+    /** Route the missing-actor warning to the engine Logger (the layout owns the
+     *  shared anchor resolver). */
+    setDiagnostics(warn: DiagnosticSink): void;
+    mount(scene: Scene): void;
+    /** Re-anchor to the line's speaker, grow to fit the text, and reveal. The
+     *  bubble stays visible even when the speaker has no live actor — the layout
+     *  anchors it at the last-known / fallback position instead of vanishing. */
+    present(line: PresentedLine | undefined): void;
+    setNameplate(name: string | undefined): void;
+    setContinueVisible(visible: boolean): void;
+    /** Show or hide the whole bubble — state-preserving: the line, name, and
+     *  caret content survive a hide, so showing again restores them in place
+     *  (used by a composite chrome to hide the bubble while a box line plays). */
+    setVisible(visible: boolean): void;
+    /** Render each piece = master-visible AND a line is up AND its content present. */
+    private apply;
+    update(dt: number): void;
+    dispose(): void;
+    /** Move the bubble + name + caret to sit above the speaker — its live actor,
+     *  or the last-known / fallback anchor when the actor is missing. */
+    private follow;
+    private drawBubble;
+}
+
+/**
+ * A diegetic choice list: the options float in their own bubble panel over the
+ * speaking actor (resolved via the {@link ActorRegistry} from the choice's
+ * `context.speaker`), with their own background — so a bubble choice never
+ * leans on the box frame (the source of the "frameless options" glitch). Pairs
+ * with {@link BubbleChrome}/{@link BubbleTextView}; keyboard nav is Session-
+ * driven, pointer hover/click come back via `onChoiceChosen` (world coords).
+ *
+ * The actor is static while a focused choice is up (the player is frozen), so
+ * the panel is placed once on `present` rather than followed each frame.
+ */
+
+interface BubbleChoiceConfig extends FontConfig {
+    /** World-space render layer (same as the bubble). */
+    readonly layer: string;
+    readonly width: number;
+    readonly padding: number;
+    /** Gap between the actor's head anchor and the panel's bottom edge. */
+    readonly offsetY: number;
+    readonly tail: number;
+    readonly choiceSize: number;
+    readonly choiceColor: number;
+    readonly choiceSelectedColor: number;
+    readonly highlightColor: number;
+    /** Vertical gap (px) between choice rows. Default {@link DEFAULT_CHOICE_GAP}. */
+    readonly choiceGap?: number | undefined;
+    /** Colour for the optional prompt header rendered inside the panel — the
+     *  theme's body `textColor`. */
+    readonly textColor: number;
+    readonly frameColor: number;
+    readonly frameAlpha: number;
+    readonly borderColor: number;
+    readonly cornerRadius: number;
+}
+declare class BubbleChoicePresenter implements ChoicePresenter {
+    private readonly cfg;
+    private readonly layout;
+    readonly pointerSpace: "world";
+    private scene?;
+    private bg?;
+    private highlightBar?;
+    private prompt?;
+    private rows;
+    private selected;
+    /** Master visibility gate — state-preserving hide/show. */
+    private hidden;
+    onChoiceChosen?: (position: number) => void;
+    constructor(cfg: BubbleChoiceConfig, layout: BubbleLayout);
+    /** Route the missing-actor warning to the engine Logger (the layout owns the
+     *  shared anchor resolver). */
+    setDiagnostics(warn: DiagnosticSink): void;
+    /** This panel is self-contained (own bg + prompt header), so it owns the
+     *  prompt — the Session hides the chrome/body prompt for these choices. */
+    ownsPrompt(): boolean;
+    mount(scene: Scene): void;
+    present(choices: readonly PresentedChoice[], context?: ChoiceContext): void;
+    /** Show or hide the whole panel without clearing it — state-preserving. */
+    setVisible(visible: boolean): void;
+    /** Render every piece (bg, prompt, rows, highlight) gated by the master.
+     *  Disabled rows still show (greyed); only the highlight bar is suppressed. */
+    private applyHidden;
+    highlight(position: number): void;
+    /** {@link ChoicePresenter}: which option a *world* point falls in. */
+    choiceAtPoint(x: number, y: number): number | undefined;
+    clear(): void;
+    dispose(): void;
+    private drawPanel;
+    private drawHighlight;
+    private textOptions;
+}
+
+/**
+ * A Mass-Effect-style radial choice wheel — an alternative {@link ChoicePresenter}
+ * that proves the choice seam is swappable without touching the Session. Options
+ * are placed evenly around a centre hub; the Session's up/down nav still cycles
+ * them, and pointer hover/click works via {@link ChoicePresenter.choiceAtPoint}.
+ *
+ * @experimental This presenter is an unpolished spike. Geometry, hit radius, and
+ * styling are intentionally minimal; the API may change. Reach it via the
+ * `./presenters` subpath; it is not part of the default factory bundles.
+ */
+
+interface RadialChoiceConfig extends FontConfig {
+    readonly center: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly radius: number;
+    readonly choiceColor: number;
+    readonly choiceSelectedColor: number;
+    readonly hubColor: number;
+    /** Choice label size (px) — matches the theme's `choiceSize`. */
+    readonly choiceSize: number;
+    readonly layerFrame: string;
+    readonly layerText: string;
+}
+/** @experimental Unpolished radial choice wheel; see file header. */
+declare class RadialChoicePresenter implements ChoicePresenter {
+    private readonly cfg;
+    private scene?;
+    private hub?;
+    private spokes;
+    private selected;
+    /** Master visibility gate — state-preserving hide/show. */
+    private hidden;
+    onChoiceChosen?: (position: number) => void;
+    constructor(cfg: RadialChoiceConfig);
+    mount(scene: Scene): void;
+    present(choices: readonly PresentedChoice[]): void;
+    highlight(position: number): void;
+    /** Show or hide the wheel without clearing it — state-preserving. */
+    setVisible(visible: boolean): void;
+    private applyHidden;
+    /** {@link ChoicePresenter}: nearest spoke within a small radius. */
+    choiceAtPoint(x: number, y: number): number | undefined;
+    clear(): void;
+    dispose(): void;
+    private drawHub;
+}
+
+/**
+ * Box-vs-bubble routing for the three composite presenters. A route maps a
+ * {@link PresentedLine} (or a choice's context, adapted to one) to `"box"` or
+ * `"bubble"`. All three composites in a mixed bundle MUST consult the SAME
+ * route, or a line could send its chrome to the bubble and its text to the box.
+ *
+ * The default policy is **speaker-aware**: a narrator goes to the box (no head
+ * to float a bubble over), an explicit `view` hint wins for a real speaker, and
+ * otherwise a speaker with a registered {@link DialogueActor} floats in a bubble
+ * while one without falls to the box. Because the registry is scene-scoped, the
+ * default is built as a {@link MountRoute} whose `hasActor` lookup is bound at
+ * mount; `createMixedDialogue` shares one instance across the three composites
+ * and exposes a `route` override for a custom policy ("all of NPC X in bubbles").
+ */
+
+/** Decides which variant a line renders in. Reads `view`/`speaker`/`meta`; a
+ *  custom route can key off any of them (e.g. `meta.aside → bubble`). */
+type CompositeRoute = (line: PresentedLine | undefined) => "box" | "bubble";
+/**
+ * A route paired with a scene-bind hook the composites call at `mount`. The
+ * default route needs the scene to resolve registered actors; a caller-supplied
+ * route needs nothing, so its {@link bind} is a no-op. The composites store ONE
+ * of these (shared, for a mixed bundle) and route every line/choice through it.
+ */
+interface MountRoute {
+    readonly route: CompositeRoute;
+    /** Bind the scene at mount (idempotent across the three composites). */
+    bind(scene: Scene): void;
+}
+/**
+ * The default route decision as a pure function of the line + an actor lookup
+ * (testable without a scene). Precedence:
+ *   1. **narrator** (no `speaker`) → **box** — the genre convention; a bubble
+ *      has no head to float over. A *positioned* narrator is the invisible-anchor
+ *      recipe (give it a speaker whose actor sits on an invisible entity).
+ *   2. an explicit **`view`** hint wins for a real speaker (`"bubble"`/`"box"`) —
+ *      a `view:"bubble"` whose actor is missing still routes to the bubble path,
+ *      which renders at the fallback anchor rather than vanishing.
+ *   3. otherwise a speaker with a **registered actor** → **bubble**; else **box**.
+ */
+declare function routeWithActor(line: PresentedLine | undefined, hasActor: (speakerId: string) => boolean): "box" | "bubble";
+/**
+ * Build the default {@link MountRoute}. `hasActor` resolves the speaker through
+ * the scene's {@link ActorRegistry}, rebound at mount (before then it answers
+ * "no actor", so a pre-mount route call still resolves via the narrator/`view`
+ * rules).
+ */
+declare function makeDefaultRoute(): MountRoute;
+/** Wrap a caller-supplied route as a {@link MountRoute} (no scene needed). */
+declare function fixedRoute(route: CompositeRoute): MountRoute;
+
+/**
+ * Routes each line to one of two text presenters by its `view` hint and whether
+ * it has a speaker — e.g. a narrator's speakerless line types in the bottom box
+ * while NPC `view:"bubble"` lines float over their heads, all in one
+ * conversation. The inactive presenter is cleared so only one shows at a time.
+ * Reveal state + skip/fast-forward proxy to whichever is active; both are ticked
+ * each frame.
+ */
+
+declare class CompositeTextPresenter implements TextPresenter {
+    private readonly box;
+    private readonly bubble;
+    private readonly routing;
+    private active?;
+    private revealListener?;
+    private beatListener?;
+    /** Master visibility gate from the Session's setVisible. */
+    private visible;
+    constructor(box: TextPresenter, bubble: TextPresenter, routing?: MountRoute);
+    /** Register the Session's reveal-completed listener. */
+    setRevealListener(listener: (() => void) | undefined): void;
+    /** Register the Session's reveal-beat listener (ticks + inline markers). */
+    setBeatListener(listener: ((beat: RevealBeat) => void) | undefined): void;
+    private fireReveal;
+    private fireBeat;
+    setDiagnostics(warn: (message: string) => void): void;
+    mount(scene: Scene): void;
+    present(line: PresentedLine): void;
+    /** Show/hide the body text — forwarded to both views (the inactive one is
+     *  cleared, so its setVisible is a no-op); state-preserving on the active. */
+    setVisible(visible: boolean): void;
+    completeReveal(): void;
+    isRevealComplete(): boolean;
+    isRevealing(): boolean;
+    setSpeedMultiplier(multiplier: number): void;
+    update(dt: number): void;
+    clear(): void;
+    dispose(): void;
+}
+
+/**
+ * Chrome counterpart to {@link CompositeTextPresenter}: shows the box frame for
+ * box lines and the bubble for bubble lines, hiding the other. The Session
+ * calls `setNameplate`/`setContinueVisible` *before* `present`, so those are
+ * buffered and applied to whichever variant `present` then selects.
+ *
+ * Visibility is owned by the Session: it calls `setVisible(bool)`
+ * after each transition, and this composite restores **only the active variant**
+ * on show. `active` is therefore RETAINED across a hide (a cutscene
+ * mid-bubble-line shows the bubble again, not an empty box).
+ */
+
+declare class CompositeChrome implements ChromePresenter {
+    private readonly box;
+    private readonly bubble;
+    private readonly routing;
+    private active?;
+    private pendingName;
+    private pendingContinue;
+    /** Master gate from the Session's setVisible — composed with the active
+     *  variant's own content state. Hidden at mount. */
+    private visible;
+    constructor(box: ChromePresenter, bubble: ChromePresenter, routing?: MountRoute);
+    mount(scene: Scene): void;
+    setDiagnostics(warn: (message: string) => void): void;
+    setNameplate(name: string | undefined, color?: number): void;
+    setContinueVisible(visible: boolean): void;
+    present(line: PresentedLine | undefined): void;
+    /** Show/hide the chrome. On show, restore ONLY the active variant
+     *  and re-apply the buffered caret; the other stays hidden. On hide, hide both
+     *  but RETAIN `active` so the next show brings back the right one. */
+    setVisible(visible: boolean): void;
+    update(dt: number): void;
+    dispose(): void;
+}
+
+/**
+ * Routes a choice list to the box list or a bubble panel by its
+ * `context.view` — the choice counterpart to {@link CompositeTextPresenter} /
+ * {@link CompositeChrome}. A box choice keeps the framed bottom list; a
+ * `view:"bubble"` choice gets its own panel over the actor (so it never relies
+ * on the box frame, which the composite chrome hides for bubble lines).
+ */
+
+declare class CompositeChoicePresenter implements ChoicePresenter {
+    private readonly box;
+    private readonly bubble;
+    private readonly routing;
+    private active?;
+    /** Master visibility gate from the Session's setVisible. */
+    private visible;
+    onChoiceChosen?: (position: number) => void;
+    constructor(box: ChoicePresenter, bubble: ChoicePresenter, routing?: MountRoute);
+    /** The active list's pointer space (so the binding hit-tests correctly). */
+    get pointerSpace(): "screen" | "world";
+    setDiagnostics(warn: (message: string) => void): void;
+    /** Routes to the variant this choice will use, so the Session knows whether
+     *  to suppress its chrome/body prompt before `present` picks the active one. */
+    ownsPrompt(context?: ChoiceContext): boolean;
+    mount(scene: Scene): void;
+    present(choices: readonly PresentedChoice[], context?: ChoiceContext): void;
+    /** Show/hide the choices — forwarded to both (the inactive one is
+     *  cleared, so its setVisible is a no-op); state-preserving on the active. */
+    setVisible(visible: boolean): void;
+    highlight(position: number): void;
+    choiceAtPoint(x: number, y: number): number | undefined;
+    clear(): void;
+    dispose(): void;
+}
+
+/**
+ * Routes the avatar to a box-side or bubble-side presenter per line, the avatar
+ * counterpart to {@link CompositeChrome} / {@link CompositeTextPresenter} /
+ * {@link CompositeChoicePresenter}. It consults the SAME {@link MountRoute} the
+ * other composites do, so a line's avatar lands on the same side as its chrome
+ * and text. The non-routed presenter is cleared (`present(undefined)`), so only
+ * one portrait shows at a time. The speaker-def + visibility verbs forward to
+ * both (they are cheap and idempotent).
+ */
+
+declare class CompositeAvatarPresenter implements AvatarPresenter {
+    private readonly box;
+    private readonly bubble;
+    private readonly routing;
+    constructor(box: AvatarPresenter, bubble: AvatarPresenter, routing: MountRoute);
+    mount(scene: Scene): void;
+    setSpeaker(speaker: SpeakerDef | undefined): void;
+    setExpression(expression: string | undefined): void;
+    /** Forward an inline reveal marker to both (cheap + idempotent, like
+     *  setExpression — the inactive side's setExpression no-ops with no speaker). */
+    marker(marker: MarkerToken): void;
+    setSpeaking(speaking: boolean): void;
+    present(line: PresentedLine | undefined): void;
+    setVisible(visible: boolean): void;
+    update(dt: number): void;
+    dispose(): void;
+}
+
+/**
+ * Portrait avatar: a sprite that sits beside the box on the left or right.
+ * Expression variants are just different textures (from the speaker's
+ * `avatar.expressions` map); "speaking" adds a gentle talk bob. Textures must
+ * be preloaded by the host scene — the presenter only resolves handles.
+ */
+
+interface PortraitPresenterConfig {
+    readonly layer: string;
+    /** Centre X for a left-side portrait (screen px). */
+    readonly leftX: number;
+    /** Centre X for a right-side portrait (screen px). */
+    readonly rightX: number;
+    /** Centre Y (screen px). */
+    readonly y: number;
+    /** Uniform sprite scale. */
+    readonly scale: number;
+}
+declare class PortraitPresenter implements AvatarPresenter {
+    private readonly cfg;
+    private scene;
+    private entity;
+    private sprite;
+    private transform;
+    private current;
+    private speaking;
+    private bobMs;
+    private baseX;
+    private baseY;
+    /** Host-hidden gate — a cutscene hides the portrait with the rest of the
+     *  UI. Composes with "is a portrait speaker active": shown = current && !hidden. */
+    private hidden;
+    private readonly handles;
+    constructor(cfg: PortraitPresenterConfig);
+    mount(scene: Scene): void;
+    setSpeaker(speaker: SpeakerDef | undefined): void;
+    /** Host-hidden gate — hide the portrait during a cutscene, restore on
+     *  show. Composes with the active-speaker state, so showing again only
+     *  re-reveals the portrait if a portrait speaker is still current. */
+    setVisible(visible: boolean): void;
+    private applyVisibility;
+    setExpression(expression: string | undefined): void;
+    /** Interpret a mid-line `[expression=…/]` reveal marker as a face swap (the
+     *  Session name-matches nothing — the presenter owns the convention). */
+    marker(marker: MarkerToken): void;
+    setSpeaking(speaking: boolean): void;
+    update(dt: number): void;
+    dispose(): void;
+    private ensureSprite;
+    private applyTexture;
+    private handle;
+    private hide;
+}
+
+/**
+ * Scene-figure avatar: instead of a portrait, the "avatar" is an entity that
+ * already exists in the world (an NPC standing in the shop, say). The speaker's
+ * `avatar.ref` is that entity's name. This presenter is the communication seam
+ * the design calls for — it doesn't know about your character system, so it
+ * takes callbacks to translate expression/speaking into whatever the figure
+ * supports (swap an AnimatedSprite clip, tint, toggle a talk loop). Out of the
+ * box it does a subtle talk bob on the figure's Transform.
+ */
+
+interface SceneFigurePresenterConfig {
+    /** Map a script expression id onto your character system. */
+    readonly onExpression?: (figure: Entity, expression: string | undefined) => void;
+    /** Toggle a talk animation / mouth flap. */
+    readonly onSpeaking?: (figure: Entity, speaking: boolean) => void;
+    /** Apply the built-in talk bob (default true). */
+    readonly bob?: boolean;
+}
+declare class SceneFigurePresenter implements AvatarPresenter {
+    private readonly cfg;
+    private scene;
+    private figure;
+    private actor;
+    private transform;
+    private speaking;
+    private bobMs;
+    /** Bob displacement currently applied to the figure's Transform. The bob is
+     *  a *relative* offset (delta-translated each frame), so external movement —
+     *  an NPC walking mid-line — is preserved instead of being pinned back to a
+     *  position captured at setSpeaker time. */
+    private bobOffset;
+    constructor(cfg?: SceneFigurePresenterConfig);
+    mount(scene: Scene): void;
+    setSpeaker(speaker: SpeakerDef | undefined): void;
+    setExpression(expression: string | undefined): void;
+    /** Mid-line `[expression=…/]` reveal marker → the figure's own expression
+     *  (actor or the `onExpression` callback). The Session name-matches nothing. */
+    marker(marker: MarkerToken): void;
+    setSpeaking(speaking: boolean): void;
+    update(dt: number): void;
+    dispose(): void;
+    /** Remove only the residual bob displacement — never teleport to a captured
+     *  base, which would undo legitimate movement since speaking began. */
+    private releaseBob;
+}
+
+/**
+ * InBoxAvatarPresenter — the reference **line-driven, reflowing in-box avatar**.
+ * It is built ONLY from the documented presenter contract:
+ *
+ *  - {@link AvatarChannel.present} gives it the line, so it reads `meta.portrait`
+ *    (texture key), `meta.side` (`left`/`right`, default left), and `meta.presence`
+ *    (set `false` to speak from off-screen — portrait hidden, no inset);
+ *  - {@link BoxLayout.setInset} reserves a column, so the box body text **reflows**
+ *    around the portrait, and {@link BoxLayout.frameRect} places the sprite.
+ *
+ * It needs NO addon internals — that's the point: it doubles as the proof the
+ * contract is sufficient to write a custom presenter (if building it ever needed
+ * an internal, the contract — not the presenter — would be wrong). It is
+ * opt-in: wire it through `createBoxDialogue(theme, { avatar })`, which hands
+ * it the box's shared layout owner. With no avatar wired (or no `meta.portrait`),
+ * behavior is unchanged.
+ *
+ * Portrait textures must be **preloaded** by the host (the presenter only
+ * resolves `meta.portrait` to a handle), like `PortraitPresenter`.
+ */
+
+interface InBoxAvatarConfig {
+    /** Render layer (screen-space) — e.g. `DIALOGUE_LAYER_AVATAR`, which sits
+     *  between the frame and the text so the portrait tucks behind the box edge. */
+    readonly layer: string;
+    /** Width (px) of the reserved avatar column; the body text reflows past it. */
+    readonly width: number;
+    /** Gap (px) between the avatar column and the reflowed text. Default 8. */
+    readonly gap?: number;
+    /** Uniform sprite scale (textures must be preloaded by the host). Default 1. */
+    readonly scale?: number;
+    /** Optional rounded-rect panel drawn behind the portrait (a framed look),
+     *  sized to the {@link width} column. Omit for a bare sprite. */
+    readonly background?: {
+        readonly color: number;
+        readonly alpha?: number;
+        /** Corner radius (px). Default 8. */
+        readonly radius?: number;
+    };
+    /** Vertical alignment in the box: `top` (level with the body text) or
+     *  `center` (default — centred in the frame, so it sinks in a grown choice box). */
+    readonly align?: "top" | "center";
+}
+declare class InBoxAvatarPresenter implements AvatarPresenter {
+    private readonly layout;
+    private readonly cfg;
+    private readonly insetKey;
+    private scene;
+    private entity;
+    private sprite;
+    private transform;
+    /** Optional background panel (behind the portrait), its own entity so it draws
+     *  under the sprite on the same layer. */
+    private bgEntity;
+    private bg;
+    private bgTransform;
+    private side;
+    /** A portrait is up for the current line (from `meta.portrait` + presence). */
+    private shown;
+    /** Host-hidden gate (a cutscene hides the avatar with the rest of the UI). */
+    private hidden;
+    private readonly handles;
+    constructor(layout: BoxLayout, cfg: InBoxAvatarConfig);
+    mount(scene: Scene): void;
+    setSpeaker(): void;
+    setExpression(): void;
+    setSpeaking(): void;
+    /** Routes a mid-line `[expression=…/]` marker to its own setExpression (inert
+     *  here — this avatar is portrait-by-`meta`, not expression-mapped — so it's
+     *  the uniform contract, not a visible face swap). */
+    marker(marker: MarkerToken): void;
+    /** Read the line's `meta` to show/hide the portrait and reserve (or clear) the
+     *  text-reflow inset. Called before the body text presents, so the text wraps
+     *  to the narrowed region. */
+    present(line: PresentedLine | undefined): void;
+    /** Host-hidden gate — hide with a cutscene, restore on show (only if a
+     *  portrait is still current). */
+    setVisible(visible: boolean): void;
+    update(): void;
+    dispose(): void;
+    /** Centre the portrait (+ its panel) in its reserved column, inset by the box
+     *  padding so it sits inside the border like the text — at the frame's current
+     *  rect, so it follows `meta.position` and a grown choice panel. */
+    private place;
+    private applyVisibility;
+    private ensureSprite;
+    private applyTexture;
+    private handle;
+}
+
+/**
+ * BubbleAvatarPresenter — the reference **line-driven portrait INSIDE the speech
+ * bubble**, the bubble counterpart to {@link InBoxAvatarPresenter}. Built only
+ * from the documented contract: {@link AvatarChannel.present} gives it the line
+ * (so it reads `meta.portrait` / `meta.side` / `meta.presence`), and it reserves
+ * a portrait column on the shared {@link BubbleLayout} (`setPortraitInset`) — so
+ * the bubble **grows** to contain the portrait and its body text **reflows** past
+ * it, and the whole thing follows the speaker's actor.
+ *
+ * Portrait textures must be **preloaded** by the host. Wire it through
+ * `createMixedDialogue(theme, { avatar: { bubble } })`.
+ */
+
+interface BubbleAvatarConfig {
+    /** World-space render layer (same as the bubble). */
+    readonly layer: string;
+    /** Portrait column size (px) reserved beside the bubble. */
+    readonly size: number;
+    /** Gap (px) between the portrait and the bubble edge. Default 8. */
+    readonly gap?: number;
+    /** Uniform sprite scale. Default 1. */
+    readonly scale?: number;
+    /** Optional rounded-rect panel behind the portrait. */
+    readonly background?: {
+        readonly color: number;
+        readonly alpha?: number;
+        readonly radius?: number;
+    };
+    /** Vertical alignment in the bubble: `top` (level with the body text) or
+     *  `center` (default). */
+    readonly align?: "top" | "center";
+}
+declare class BubbleAvatarPresenter implements AvatarPresenter {
+    private readonly layout;
+    private readonly cfg;
+    private scene;
+    private entity;
+    private sprite;
+    private transform;
+    private bgEntity;
+    private bg;
+    private bgTransform;
+    private side;
+    private speakerId;
+    private shown;
+    private hidden;
+    private readonly handles;
+    constructor(layout: BubbleLayout, cfg: BubbleAvatarConfig);
+    mount(scene: Scene): void;
+    setSpeaker(): void;
+    setExpression(): void;
+    setSpeaking(): void;
+    /** Uniform marker contract: routes `[expression=…/]` to its own setExpression
+     *  (inert here — this avatar is portrait-by-`meta`). */
+    marker(marker: MarkerToken): void;
+    present(line: PresentedLine | undefined): void;
+    setVisible(visible: boolean): void;
+    update(): void;
+    dispose(): void;
+    /** Place the portrait in its reserved column INSIDE the active bubble (say
+     *  bubble or choice panel), vertically centred on the body, tracking the
+     *  speaker's (moving) anchor. */
+    private follow;
+    private applyVisibility;
+    private ensureSprite;
+    private applyTexture;
+    private handle;
+}
+
+/**
+ * A component you drop on any world entity to make it a dialogue *actor*: it
+ * self-registers under a logical `speaker` id (see {@link ActorRegistry}) so
+ * presenters can find "where is whoever is speaking" without an external map.
+ * It owns the per-entity translation of dialogue intent — expression + speaking
+ * — into whatever the entity's character system supports (swap an animation
+ * clip, tint, toggle a talk loop) via callbacks, and exposes a head/anchor
+ * point for diegetic bubbles to position against.
+ */
+
+interface DialogueActorOptions {
+    /** Logical speaker id this entity answers to (matches the script). */
+    readonly speaker: string;
+    /** Offset from the entity transform to the bubble anchor (head), in px. */
+    readonly anchor?: {
+        readonly x: number;
+        readonly y: number;
+    };
+    /** Map a script expression id onto this entity's character system. */
+    readonly onExpression?: (entity: Entity, expression: string | undefined) => void;
+    /** Toggle a talk animation / mouth flap. */
+    readonly onSpeaking?: (entity: Entity, speaking: boolean) => void;
+}
+declare class DialogueActor extends Component {
+    private readonly opts;
+    constructor(opts: DialogueActorOptions);
+    get speaker(): string;
+    onAdd(): void;
+    onDestroy(): void;
+    /** Bubble anchor in world space: the entity position plus the configured offset. */
+    anchorWorld(): {
+        x: number;
+        y: number;
+    };
+    setExpression(expression: string | undefined): void;
+    setSpeaking(speaking: boolean): void;
+}
+
+/**
+ * Scene-scoped speaker → live entity index. A {@link DialogueActor} self-
+ * registers under its logical speaker id; presenters resolve a speaker to a
+ * world entity through here instead of carrying an external map. Scripts always
+ * speak in *logical* ids (invariant) — instance selection happens here, never
+ * in the script.
+ *
+ * The registry is keyed off the `Scene` via a WeakMap, so it needs no service
+ * registration and is torn down with the scene. Multiple live entities for one
+ * speaker id is unsupported: last registration wins.
+ */
+
+declare class ActorRegistry {
+    private readonly actors;
+    register(speaker: string, actor: DialogueActor): void;
+    unregister(speaker: string, actor: DialogueActor): void;
+    resolve(speaker: string | undefined): DialogueActor | undefined;
+}
+/** The (lazily-created) registry for a scene. Shared by actors + presenters. */
+declare function actorRegistryFor(scene: Scene): ActorRegistry;
+
+/**
+ * defaultTheme — a zero-config, zero-asset {@link DialogueTheme}.
+ *
+ * Renders entirely with Graphics chrome (rounded rectangles + strokes) and
+ * canvas text (SplitText/Text). No bitmap fonts, no textures, no bundled
+ * assets — so `createBoxDialogue()` / `createBubbleDialogue(undefined, opts)`
+ * work with no caller-supplied theme.
+ *
+ * Returns a fresh object each call so callers can spread-and-tweak without
+ * mutating a shared singleton:
+ *
+ * ```ts
+ * const theme = { ...defaultTheme(), textColor: 0xff0000 };
+ * ```
+ *
+ * The `box` is viewport-relative (margins + height), so it's a full-width bottom
+ * bar at ANY virtual resolution with no override. Bitmap fonts (`bitmapFont`) and
+ * textured nine-slice chrome (the `textured` field) are OPT-IN re-theming paths,
+ * intentionally absent here.
+ */
+declare function defaultTheme(): DialogueTheme;
+
+/**
+ * `createBoxDialogue(theme)` is the easy on-ramp: hand it one {@link DialogueTheme}
+ * and get back the wired presenter bundle for a classic bottom-of-screen box
+ * (frame + nameplate + caret, a typewriter body, a vertical choice list). Spread
+ * it into a controller and override any one piece:
+ *
+ *   new DialogueController({ ...createBoxDialogue(theme), avatar, storage });
+ *
+ * It only assembles configs + presenters from the theme — no scene, no input —
+ * so the host stays in charge of lifecycle. All four box presenters share ONE
+ * {@link BoxLayout} so the frame, nameplate, body text, and choice rows move and
+ * grow as one panel (per-line `meta.position`, choice-grow, avatar reflow).
+ *
+ * `theme` defaults to {@link defaultTheme} so a zero-config call works out of
+ * the box (Graphics chrome + canvas text, no bundled assets).
+ */
+
+interface BoxDialogueOptions {
+    /**
+     * Build an avatar presenter wired to the box's shared {@link BoxLayout} — so
+     * a line-driven, reflowing in-box avatar (the reference `InBoxAvatarPresenter`)
+     * can reserve a text-reflow inset on it. Receives the layout the box
+     * chrome/text/choices share. Omit for no avatar (the default).
+     *
+     *   createBoxDialogue(theme, {
+     *     avatar: (layout) =>
+     *       new InBoxAvatarPresenter(layout, { layer: DIALOGUE_LAYER_AVATAR, width: 96 }),
+     *   })
+     */
+    readonly avatar?: (layout: BoxLayout) => AvatarPresenter;
+}
+declare function createBoxDialogue(theme?: DialogueTheme, opts?: BoxDialogueOptions): DialogueBundle;
+
+/**
+ * `createBubbleDialogue(theme, opts)` wires a diegetic variant: the body text
+ * floats in a world-space speech bubble over the speaking NPC (resolved via its
+ * {@link DialogueActor}), while choices float in their own bubble panel over the
+ * actor. Reuses the {@link DialogueTheme} for colours/fonts so a game's box and
+ * bubble dialogues look consistent.
+ *
+ *   new DialogueController({ ...createBubbleDialogue(theme, { worldLayer }), avatar });
+ *
+ * The actors must already carry a {@link DialogueActor} (speaker id + head
+ * anchor); the bubble follows that anchor every frame. Register exactly ONE
+ * actor per speaker id — the bubble chrome and the bubble text each resolve the
+ * speaker independently, so two actors sharing an id would let them track
+ * different entities and the text would drift off the bubble.
+ *
+ * `theme` defaults to {@link defaultTheme} so a zero-config call works out of
+ * the box (Graphics chrome + canvas text, no bundled assets).
+ */
+
+interface BubbleGeometry {
+    /** Snuggest width; the bubble widens to its text up to {@link maxWidth}. */
+    readonly minWidth: number;
+    /** Widest the bubble grows before its text wraps to more lines. */
+    readonly maxWidth: number;
+    /** Minimum height; grows to fit wrapped text once `maxWidth` is reached. */
+    readonly height: number;
+    readonly padding: number;
+    /** Gap between the actor's head anchor and the bubble's bottom edge. */
+    readonly offsetY: number;
+    /** Tail (pointer) height. */
+    readonly tail: number;
+}
+declare const DEFAULT_BUBBLE: BubbleGeometry;
+interface BubbleDialogueOptions {
+    /** World-space render layer the bubble + text draw into. */
+    readonly worldLayer: string;
+    readonly bubble?: Partial<BubbleGeometry>;
+    /**
+     * Where a bubble anchors when its speaker has no live actor and no last-known
+     * position (a never-seen speaker / a narrator in a pure-bubble bundle).
+     * Defaults to the world origin; point it at your camera centre so a
+     * speakerless line lands on screen. A despawned actor uses its last-known
+     * position regardless. Shared by the chrome, text, and choice presenters.
+     */
+    readonly fallbackAnchor?: () => {
+        x: number;
+        y: number;
+    };
+    /** Build an avatar presenter wired to the bubble's shared {@link BubbleLayout}
+     *  — e.g. the reference `BubbleAvatarPresenter`, a line-driven portrait beside
+     *  the bubble. Receives the layout the bubble chrome/text/choices share. */
+    readonly avatar?: (layout: BubbleLayout) => AvatarPresenter;
+}
+declare function createBubbleDialogue(theme: DialogueTheme | undefined, opts: BubbleDialogueOptions): DialogueBundle;
+
+/**
+ * `createMixedDialogue` composes the box and bubble factories so one
+ * conversation can place each line — and each choice — in either presentation,
+ * chosen per step by its `view` hint ("box" — default — vs "bubble"). Text,
+ * chrome, choices, and the avatar all route the same way, so a box choice keeps
+ * the framed bottom list while a bubble choice gets its own panel over the actor.
+ *
+ * `theme` defaults to {@link defaultTheme} so a zero-config call works out of
+ * the box (Graphics chrome + canvas text, no bundled assets).
+ */
+
+interface MixedDialogueOptions extends Omit<BubbleDialogueOptions, "avatar"> {
+    /**
+     * Override the box-vs-bubble routing policy for this bundle. The default is
+     * speaker-aware (narrator → box; explicit `view` wins; else a registered
+     * actor → bubble, otherwise box). Supply a route to key off anything on the
+     * line — e.g. `(line) => line?.speaker?.id === "boss" ? "bubble" : "box"`.
+     * All composites (and the avatar) consult this one route, so chrome, text,
+     * choices, and avatar always agree per line.
+     */
+    readonly route?: CompositeRoute;
+    /**
+     * Wire avatar presenters per side. `box` gets the box's {@link BoxLayout} (an
+     * in-box reflowing avatar); `bubble` gets the bubble's {@link BubbleLayout} (a
+     * portrait beside the bubble). With both, a {@link CompositeAvatarPresenter}
+     * routes each line to the matching side; with one, only that side shows.
+     */
+    readonly avatar?: {
+        readonly box?: BoxDialogueOptions["avatar"];
+        readonly bubble?: BubbleDialogueOptions["avatar"];
+    };
+}
+declare function createMixedDialogue(theme: DialogueTheme | undefined, opts: MixedDialogueOptions): DialogueBundle;
+
+export { ActorRegistry, type AnchorPoint, AvatarPresenter, type BoxBounds, type BoxDialogueOptions, BoxLayout, type BoxLayoutConfig, type BoxPosition, BoxTextView, BubbleAnchorResolver, type BubbleAvatarConfig, BubbleAvatarPresenter, type BubbleChoiceConfig, BubbleChoicePresenter, BubbleChrome, type BubbleChromeConfig, type BubbleDialogueOptions, type BubbleGeometry, BubbleLayout, type BubbleLayoutConfig, BubbleTextView, CHROME_STYLE_DEFAULT, CHROME_STYLE_NONE, type CaretTheme, type ChoiceListConfig, ChoiceListPresenter, ChoicePresenter, type ChoiceRowRect, ChromePresenter, type ChromeStyle, CompositeAvatarPresenter, CompositeChoicePresenter, CompositeChrome, type CompositeRoute, CompositeTextPresenter, DEFAULT_BUBBLE, DEFAULT_CARET_BLINK_MS, DEFAULT_CARET_SIZE, DEFAULT_CHOICE_GAP, DEFAULT_TAIL_LEAN, DIALOGUE_LAYERS, DIALOGUE_LAYER_AVATAR, DIALOGUE_LAYER_FRAME, DIALOGUE_LAYER_TEXT, DiagnosticSink, DialogueActor, type DialogueActorOptions, DialogueChrome, type DialogueChromeConfig, type DialogueTextConfig, DialogueTextView, type DialogueTheme, type EffectOutput, type FontConfig, type InBoxAvatarConfig, InBoxAvatarPresenter, type MixedDialogueOptions, type MountRoute, type NineSliceFrame, type NineSliceInsets, PortraitPresenter, type PortraitPresenterConfig, type RadialChoiceConfig, RadialChoicePresenter, type Rect, SceneFigurePresenter, type SceneFigurePresenterConfig, type TextInset, TextPresenter, actorRegistryFor, createBoxDialogue, createBubbleDialogue, createMixedDialogue, defaultTheme, effectDrivesTint, evaluateEffect, fixedRoute, makeDefaultRoute, routeWithActor, stackChoiceRows };