waygraph 0.15.25 → 0.15.26

package/dist/highlights.d.ts

@@ -1,734 +1,9 @@
-/**
- * Block stubBefore / stubAfter / stubOnError + flow highlightFixtures + demo slides.
- * Demo narration only - never affects runGraph pass/fail.
- *
- * Stubs are **open block lifecycles** - prefer `stubBefore(ctx) { ... }`, not a
- * closed slot object. Inside the fn authors set fixtures (todos, zoom) and rings.
- * Object maps remain a shorthand for highlight-only slots.
- *
- * Lifecycle (stubs) ≠ yap slides: stubs are fill/after/error rings tied to the block;
- * slides are multi-step captions with Next between them (long-process explain).
- *
- * All fixture shapes share optional {@link FixtureDurationFields} so demo dwell
- * before advancing is authored the same way on stubs, flow fixtures, and slides.
- */
-import type { Block, Checkpoint } from "./types.js";
-import type { MemPage } from "./mem-page.js";
-/** Shared dwell fields on stubs, fixtures, and yap slides. */
-export type FixtureDurationFields = {
-    /**
-     * Min time this fixture stays visible before the demo advances.
-     * - `true` - defaults (2000ms normal, {@link FixtureDurationFields.fastMode} or 600ms when --fast)
-     * - `number` - override normal dwell ms
-     * - omit / false - no authored dwell (caller keeps legacy timing)
-     */
-    duration?: boolean | number;
-    /**
-     * Dwell ms when demo `--fast` / gatesFast (only when {@link duration} is set).
-     * Default 600.
-     */
-    fastMode?: number;
-};
-/**
- * One checklist row for episode planning (demo panel).
- * Set via {@link StubCtx.todos} / {@link StubCtx.todoIndex} inside the lifecycle.
- */
-export type WaygraphTodoItem = {
-    text: string;
-    /**
-     * Stable id for external asserts / redirects (Mailhog, deep links).
-     * Stamped as `data-wg-todo-item` on the row.
-     */
-    id?: string;
-    /** Alias for {@link WaygraphTodoItem.id}. */
-    name?: string;
-    /** Explicit done. If omitted, derived from todoIndex (index < todoIndex). */
-    done?: boolean;
-    /** Explicit current. If omitted, derived from todoIndex (index === todoIndex). */
-    current?: boolean;
-};
-export type WaygraphTodoInput = string | WaygraphTodoItem;
-/**
- * Dock list presentation:
- * - `sequential` - arrow on current, strike done (demo walkthrough)
- * - `checklist` - checkbox done/pending only (no current arrow; independent checks)
- * - `bullets` - flat bullet list (no arrow/checkbox; open notes / trimmed dock)
- */
-export type TodoListStyle = "sequential" | "checklist" | "bullets";
-/** One titled group in the floating todo dock (FR / Scenarios / ACs, etc.). */
-export type WaygraphTodoGroupInput = {
-    /** Stable group id -> `data-wg-todo-group`. */
-    id?: string;
-    /** Alias for {@link WaygraphTodoGroupInput.id}. */
-    name?: string;
-    /** Group heading shown above the items. */
-    title?: string;
-    /** Per-group style; falls back to dock default ({@link StubCtx.todoStyle}). */
-    style?: TodoListStyle;
-    items: readonly WaygraphTodoInput[];
-    /** Sequential only: which item is current (0-based). */
-    todoIndex?: number;
-};
-export type WaygraphTodoGroup = {
-    id?: string;
-    title?: string;
-    style: TodoListStyle;
-    items: WaygraphTodoItem[];
-};
-/** Full floating dock payload passed to the browser. */
-export type TodoDockState = {
-    /**
-     * Stable dock id for external targeting after redirects
-     * (`#wg-todo-dock[data-wg-todo-id="…"]`).
-     */
-    id?: string;
-    /** Default style for groups that omit their own. */
-    style: TodoListStyle;
-    /** Single-list title when using {@link StubCtx.todos} + {@link StubCtx.todoTitle}. */
-    title?: string;
-    groups: WaygraphTodoGroup[];
-    pos?: "left" | "right";
-};
-/** Options for compact {@link StubCtx.todos}(`id`, items, opts). */
-export type WaygraphTodosOpts = {
-    /** Dock heading. */
-    title?: string;
-    /** Current item index (0-based). */
-    index?: number;
-    /** `sequential` | `checklist` | `bullets`. */
-    style?: TodoListStyle;
-    /** Dock side. */
-    pos?: "left" | "right";
-    /**
-     * Keep other docks with different ids (multi-todo). Default false —
-     * one checklist at a time (setting todos replaces the previous dock).
-     */
-    parallel?: boolean;
-};
-/**
- * Floating todo-dock UX knobs (0.15.8+). Defaults are **smart on** so long
- * FR/AC checklists do not bury highlight rings. Opt out per phase or globally.
- *
- * Defaults: `compact`, `collision`, `behindRing` = true; `cap` = 5; `expandCap` = 14.
- *
- * Global: `WAYGRAPH_TODO_UI=full` / `waygraph demo --todo-full` turns smart off.
- * Per-knob env: `WAYGRAPH_TODO_COMPACT=0`, `WAYGRAPH_TODO_COLLISION=0`,
- * `WAYGRAPH_TODO_BEHIND=0`, `WAYGRAPH_TODO_CAP`, `WAYGRAPH_TODO_EXPAND_CAP`.
- */
-export type TodoDockUiOpts = {
-    /** Fold long lists around the current row (+N more / hover). Default true. */
-    compact?: boolean;
-    /** Visible rows when compact. Default 5. */
-    cap?: number;
-    /** Visible rows on hover / pinned expand. Default 14. */
-    expandCap?: number;
-    /** Flip dock L/R when an active ring overlaps it. Default true. */
-    collision?: boolean;
-    /** Dim + lower z-index while a highlight ring is up. Default true. */
-    behindRing?: boolean;
-};
-/** Resolved todo-dock UX (all fields present). */
-export type TodoDockUiResolved = {
-    compact: boolean;
-    cap: number;
-    expandCap: number;
-    collision: boolean;
-    behindRing: boolean;
-};
-/**
- * Resolve todo-dock UX from env + optional author patch.
- * `WAYGRAPH_TODO_UI=full|off|legacy` forces compact/collision/behindRing off.
- */
-export declare function resolveTodoDockUi(patch?: TodoDockUiOpts | null, env?: NodeJS.ProcessEnv): TodoDockUiResolved;
-/** Episode-level fixtures authored inside stubBefore/After/OnError(ctx). */
-export type StubPhaseFixtures = {
-    todos?: readonly WaygraphTodoInput[];
-    /** Which todo is current (0-based). Rows before = done, after = pending. */
-    todoIndex?: number;
-    /** Heading above a single {@link StubCtx.todos} list. */
-    todoTitle?: string;
-    /**
-     * Stable dock id (`data-wg-todo-id`) for external redirect asserts
-     * (e.g. Mailhog -> back to app and still find the checklist).
-     */
-    todoId?: string;
-    /** `sequential` (default), `checklist`, or `bullets`. */
-    todoStyle?: TodoListStyle;
-    /** Multiple titled lists (FR / Scenarios / ACs). Wins over bare todos when set. */
-    todoGroups?: readonly WaygraphTodoGroupInput[];
-    /**
-     * Camera zoom (Screen Studio style) - scales the page toward the target /
-     * cursor. Not element CSS zoom. Typical `1.25` .. `2`.
-     */
-    zoom?: number;
-    /** Default zoomOut for rings (false = keep camera between rings). */
-    zoomOut?: boolean;
-    /** Top demo banner title (the purple "waygraph demo" card). */
-    title?: string;
-    /**
-     * Floating checklist dock side. `left` | `right`.
-     * Authored control (also click / WAYGRAPH_TODO_POS / --todo-left|right).
-     */
-    todoPos?: "left" | "right";
-    /**
-     * Todo-dock UX (compact / collision / behind-ring). Merged onto env defaults.
-     * See {@link TodoDockUiOpts}.
-     */
-    todoDockUi?: TodoDockUiOpts;
-    /**
-     * Viewport preset: `mobile` | `tablet` | `desktop` (default / clear).
-     * Omit on later blocks = **keep** (same persist pattern as todos).
-     */
-    device?: DevicePreset | DeviceState;
-    /** Explicit pixel viewport (wins over preset width/height when both set). */
-    viewport?: DeviceViewport;
-    /** Touch theater + Playwright touchscreen when true. */
-    touch?: boolean;
-    /** Portrait / landscape (swaps preset width/height). */
-    orientation?: DeviceOrientation;
-};
-/** Named viewport presets (0.13+). */
-export type DevicePreset = "mobile" | "tablet" | "desktop";
-/** Explicit viewport box. */
-export type DeviceViewport = {
-    width: number;
-    height: number;
-    deviceScaleFactor?: number;
-};
-/**
- * Carried device fixture (todo-dock shaped persist).
- * Omit on a later step = keep; hideDevice/clearDevice/desktop = clear to desktop.
- */
-export type DeviceState = {
-    preset: DevicePreset;
-    viewport: DeviceViewport;
-    /** Playwright-ish: treat as mobile layout. */
-    isMobile: boolean;
-    /** Context needs hasTouch for touchscreen.tap (demo launches with hasTouch). */
-    hasTouch: boolean;
-    /** Demo gesture theater: finger cursor, tap/hold timing, prefer touchscreen. */
-    touchMode: boolean;
-    /** Viewport orientation (0.13.3+). Default derived from width/height. */
-    orientation?: DeviceOrientation;
-};
-/** Portrait (tall) or landscape (wide). */
-export type DeviceOrientation = "portrait" | "landscape";
-/** Built-in preset sizes (CSS pixels) — stored in portrait for mobile/tablet. */
-export declare const DEVICE_PRESETS: Record<DevicePreset, Omit<DeviceState, "touchMode"> & {
-    touchMode?: boolean;
-}>;
-export declare function normalizeDevicePreset(raw: unknown): DevicePreset | undefined;
-export declare function normalizeDeviceOrientation(raw: unknown): DeviceOrientation | undefined;
-/** Infer orientation from box (square counts as landscape). */
-export declare function orientationFromViewport(vp: DeviceViewport): DeviceOrientation;
-/**
- * Swap width/height so the viewport matches the requested orientation.
- * Preserves deviceScaleFactor. No-op when already oriented.
- */
-export declare function applyOrientation(state: DeviceState, orientation: DeviceOrientation): DeviceState;
-/** Resolve a preset name or partial state into a full DeviceState. */
-export declare function resolveDeviceState(input: DevicePreset | DeviceState | DeviceViewport | undefined, touchOverride?: boolean, orientationOverride?: DeviceOrientation): DeviceState | undefined;
-/**
- * Carry-forward for device fixtures (mirror {@link applyTodoPhase}).
- * - clear: hideDevice / clearDevice / device("desktop") with clear intent
- * - set: author set device/viewport/touch this phase
- * - keep: omit - preserve previous (whole episode remain)
- */
-export declare function applyDevicePhase(prev: DeviceState | undefined, phase: {
-    deviceSync?: "set" | "clear" | "keep";
-    device?: DeviceState;
-}): {
-    device: DeviceState | undefined;
-    sync: "set" | "clear" | "keep";
-};
-/**
- * The `#wg-ring` / `#wg-ring-label` CSS (tone/size/weight variants) - the
- * actual visual language `cli.ts`'s own demo stepper paints with. Extracted
- * here (not left as a private `cli.ts` constant) so anything else wanting the
- * SAME "waygraph vision" ring can import pure CSS text, not the rendering
- * engine around it - `cli.ts` runs `main().catch(...)` unconditionally at
- * module load with no `import.meta.url` guard, so importing anything from it
- * is unsafe as a library dependency (see `pilot-overlay.ts`'s own doc
- * comment for the same reasoning re: the badge/panel). This file has always
- * been the pure, side-effect-free home for tone/size/weight - the CSS that
- * renders them belongs alongside it for the same reason. `cli.ts` imports
- * this constant instead of keeping its own duplicate copy.
- */
-export declare const WAYGRAPH_RING_CSS: string;
-/** One named highlight slot on a block (selector + caption). */
-export interface WaygraphHighlightStub extends FixtureDurationFields {
-    selector: string;
-    /** Primary caption line. */
-    label: string;
-    /** Extra caption line (ring / slide body). */
-    detail?: string;
-    /** Short badge, e.g. AC / BUG / GATE / YAP. */
-    tag?: string;
-    /**
-     * Demo ring color + icon:
-     * - `planned` purple (authored narration, default)
-     * - `auto` gray (engine automation / verify fallback)
-     * - `info` blue · `warning` yellow · `danger` red · `success` green
-     */
-    tone?: HighlightTone;
-    /**
-     * Ring padding + label font scale: `sm` | `md` (default) | `lg`.
-     * Aliases: small/medium/large, s/m/l.
-     */
-    size?: HighlightSize;
-    /**
-     * Label font weight: `normal` (default) | `bold`.
-     * Aliases: regular, strong.
-     */
-    weight?: HighlightWeight;
-    /**
-     * Camera zoom while this ring is up (Screen Studio style - page scales toward
-     * the target / cursor). Typical `1.25` .. `2`. Cleared when the ring hides
-     * unless `zoomOut: false`. Episode default: {@link StubCtx.zoom}.
-     */
-    zoom?: number;
-    /**
-     * When false, keep the camera zoomed after this ring (pan to the next target
-     * instead of zooming out). Default true. Phase default: {@link StubCtx.zoomOut}.
-     */
-    zoomOut?: boolean;
-    /**
-     * Spotlight: dim the rest of the page, keep this target as the focal point.
-     */
-    focus?: boolean;
-    /**
-     * Deprecated no-op. Camera auto-centers on the ring target; host mouse is
-     * ignored. Playwright's real mouse is driven to the centered target instead.
-     */
-    followMouse?: boolean;
-    /** Alias for {@link WaygraphHighlightStub.followMouse} (no-op). */
-    follow?: boolean;
-    /**
-     * Caption text color (CSS color). Overrides tone label color when set.
-     * Aliases accepted at runtime: `color`, `labelColor`, `textColor`.
-     */
-    color?: string;
-    /**
-     * Move the demo cursor to the target while this ring is up (default true
-     * for authored stub queues; set false to keep cursor hidden).
-     */
-    cursor?: boolean;
-    /**
-     * Optional link to a todo item id. When set, Method fill/click advances that
-     * todo row instead of relying on stub array index (avoids password/submit/username
-     * alphabetical reorder bugs).
-     */
-    todo?: string;
-    /** Slot key from stubBefore/After map (e.g. "username") - set by resolver. */
-    slotId?: string;
-    /**
-     * Pointer feel when touchMode is on (0.13+):
-     * - `tap` - short press via touchscreen (default in touch mode)
-     * - `hold` - long-press (~600ms) then release
-     * - `click` - mouse click even in touch mode
-     */
-    gesture?: "tap" | "hold" | "click" | "swipe";
-}
-/** Flow fixture patch: label required; selector optional (inherits from stub). */
-export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "zoom" | "zoomOut" | "focus" | "followMouse" | "follow" | "color" | "cursor" | "todo" | "gesture"> & FixtureDurationFields;
-export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
-/**
- * Open stub lifecycle context. Authors set rings + episode fixtures freely —
- * not restricted to returning a closed slot object.
- *
- * @example
- * stubBefore: (ctx) => {
- *   ctx.todos(["Enter email", "Enter password", "Click Sign in"]);
- *   ctx.todoIndex(0);
- *   ctx.zoom(1.35);
- *   ctx.highlights({
- *     email: { selector: "#email", label: "Email" },
- *     submit: { selector: "#login-button", label: "Sign in" },
- *   });
- * }
- * // Sequential plan: bump todoIndex in a later phase / later block's stubBefore
- * stubAfter: (ctx) => {
- *   ctx.todos(["Enter email", "Enter password", "Click Sign in"]);
- *   ctx.todoIndex(2);
- *   ctx.ring("inventory", { selector: ".inventory_list", label: "Landed" });
- * }
- */
-export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
-    /**
-     * Live Mem for this run - same store `act`/`observe` read. Prefer this over
-     * closing over outer scope or inventing parallel fixture bags.
-     * Undefined only if the caller ran a stub phase without passing mem (tests).
-     */
-    readonly mem: MemPage | undefined;
-    /** Present after resolve (stubAfter). Undefined for stubBefore. */
-    readonly out: Out | undefined;
-    /** Present on stubOnError when the step threw. */
-    readonly error: unknown | undefined;
-    /** Replace named highlight rings for this phase. */
-    highlights(slots: HighlightStubPhase): void;
-    /** Set / overwrite one named ring. */
-    ring(id: string, stub: WaygraphHighlightStub): void;
-    /**
-     * Floating checklist. Prefer the compact form:
-     *   ctx.todos("login", ["Enter email", "Enter password"], { title: "Sign in", index: 0 })
-     * Legacy: ctx.todos([...]); ctx.todoId(...); ctx.todoIndex(...); …
-     * Default = one dock (setting todos replaces). Pass `{ parallel: true }` to keep others.
-     */
-    todos(items: readonly WaygraphTodoInput[]): void;
-    todos(id: string, items: readonly WaygraphTodoInput[], opts?: WaygraphTodosOpts): void;
-    /** Current checklist index (bump for sequential plans). */
-    todoIndex(n: number): void;
-    /** Heading above the single {@link StubCtx.todos} list. */
-    todoTitle(text: string): void;
-    /**
-     * Stable dock id for external selectors after redirects
-     * (`#wg-todo-dock[data-wg-todo-id="ep10-coverage"]`).
-     */
-    todoId(id: string): void;
-    /**
-     * Dock presentation: `sequential` (arrow walkthrough), `checklist`
-     * (independent checkboxes), or `bullets` (flat • list, no progress marks).
-     */
-    todoStyle(style: TodoListStyle): void;
-    /**
-     * Multiple titled lists (e.g. Functional Requirements / Scenarios / ACs).
-     * Replaces a bare {@link StubCtx.todos} list when set.
-     */
-    todoGroups(groups: readonly WaygraphTodoGroupInput[]): void;
-    /**
-     * Hide the floating todo dock. Omit todos on a later block = **keep** the
-     * previous dock (carry forward). Only hideTodos / clearTodos / todos([]) clears it.
-     */
-    hideTodos(): void;
-    /** Alias for {@link StubCtx.hideTodos}. */
-    clearTodos(): void;
-    /**
-     * Viewport / device fixture (0.13+). `mobile` | `tablet` | `desktop`.
-     * Omit on later blocks = **keep** (same persist as todos). Use
-     * {@link StubCtx.hideDevice} / {@link StubCtx.clearDevice} to return to desktop.
-     */
-    device(preset: DevicePreset | DeviceState): void;
-    /** Explicit CSS-pixel viewport (implies mobile-ish unless desktop-sized). */
-    viewport(box: DeviceViewport): void;
-    /** Enable / disable touch theater + touchscreen gestures. */
-    touch(on?: boolean): void;
-    /**
-     * Rotate viewport to portrait or landscape (0.13.3+).
-     * Keeps current preset; swaps width/height. Toast + lerp like device().
-     */
-    orientation(o: DeviceOrientation): void;
-    /** Alias for {@link StubCtx.orientation}("landscape"). */
-    landscape(): void;
-    /** Alias for {@link StubCtx.orientation}("portrait"). */
-    portrait(): void;
-    /**
-     * Reset to desktop viewport and clear touch mode. Omit device on a later
-     * block = **keep**; only hideDevice / clearDevice / device("desktop") clears.
-     */
-    hideDevice(): void;
-    /** Alias for {@link StubCtx.hideDevice}. */
-    clearDevice(): void;
-    /** Default camera zoom for rings without their own zoom. */
-    zoom(n: number): void;
-    /**
-     * Default zoomOut for rings in this phase. `false` = keep camera between rings.
-     */
-    zoomOut(keep: boolean): void;
-    /** Top banner title (waygraph demo card). */
-    title(text: string): void;
-    /** Alias for {@link StubCtx.title}. */
-    banner(text: string): void;
-    /**
-     * Floating checklist dock side (`left` | `right`). Authors control this in
-     * code; click / env / --todo-left|right are fallbacks.
-     */
-    todoPos(side: "left" | "right"): void;
-    /**
-     * Todo-dock UX: compact fold, collision flip, dim-behind-ring.
-     * Defaults are smart-on; pass false fields to opt out for this phase.
-     * @example
-     * ctx.todoDockUi({ compact: false }); // always show full list
-     * ctx.todoDockFull(); // shorthand: compact+collision+behindRing off
-     */
-    todoDockUi(opts: TodoDockUiOpts): void;
-    /** Shorthand: full checklist, no compact/collision/behind-ring for this phase. */
-    todoDockFull(): void;
-    /** Batch-set rings + episode fixtures. */
-    set(partial: {
-        highlights?: HighlightStubPhase;
-    } & StubPhaseFixtures): void;
-};
-export type StubLifecycleFn<Out extends Checkpoint<string>> = (ctx: StubCtx<Out>) => void | HighlightStubPhase | Promise<void | HighlightStubPhase>;
-/**
- * Block stub authoring:
- * - **preferred:** open lifecycle `stubBefore(ctx) { ctx.todos(...); ctx.ring(...) }`
- * - **shorthand:** static slot map `{ email: { selector, label } }`
- * - **legacy:** `(out) => slotMap` still accepted (treated as highlights only)
- */
-export type HighlightStubPhaseOrFn<Out extends Checkpoint<string>> = HighlightStubPhase | StubLifecycleFn<Out> | ((out: Out) => HighlightStubPhase);
-/** Result of running a stub phase (rings + episode fixtures). */
-export type StubPhaseResult = {
-    highlights: ResolvedHighlight[];
-    /** Flattened first-group items (compat). Prefer {@link todoDock}. */
-    todos: WaygraphTodoItem[];
-    todoIndex?: number;
-    todoDock?: TodoDockState;
-    /**
-     * Todo dock intent for this phase:
-     * - `set` - replace dock with {@link todoDock}
-     * - `clear` - hide dock (author called hideTodos / empty todos())
-     * - `keep` - author omitted todos; demo must leave previous dock alone
-     */
-    todoSync?: "set" | "clear" | "keep";
-    /** Todo-dock UX for this phase (when author called {@link StubCtx.todoDockUi}). */
-    todoDockUi?: TodoDockUiOpts;
-    /** Resolved device after this phase (undefined when keep with no prior). */
-    device?: DeviceState;
-    /**
-     * Device intent (mirror todoSync):
-     * - `set` - apply {@link device}
-     * - `clear` - reset to desktop (hideDevice / clearDevice / device desktop)
-     * - `keep` - author omitted device; demo must leave previous alone
-     */
-    deviceSync?: "set" | "clear" | "keep";
-    zoom?: number;
-    zoomOut?: boolean;
-    title?: string;
-    todoPos?: "left" | "right";
-    /** When true, keep other docks (multi-todo). Default false = replace. */
-    todoParallel?: boolean;
-};
-/**
- * One yap/slide in a multi-step demo caption sequence.
- * Not block lifecycle - demo pauses (Next / auto-next) between slides.
- */
-export interface WaygraphSlide extends FixtureDurationFields {
-    /** Primary caption (required). */
-    caption: string;
-    detail?: string;
-    tag?: string;
-    /** Optional ring while this slide is showing. */
-    selector?: string;
-    tone?: HighlightTone;
-    size?: HighlightSize;
-    weight?: HighlightWeight;
-    /** Magnify via camera (Screen Studio) while this slide is showing. */
-    zoom?: number;
-}
-/**
- * Demo ring tones (iconified).
- * Automation (`auto`) is gray so authored planned/info/warning/danger/success stand out.
- * `orange` added for Blind Pilot's own real, direct user request: a visible
- * color distinction between a real Playwright-driven action (a Block run,
- * or a raw click/type/upload - `auto` gray, already meant exactly this) and
- * a pure DOM inspection (`auto dom` - orange, new) - "gray is waygraph
- * playwright run. orange is dom check."
- */
-export type HighlightTone = "planned" | "auto" | "info" | "warning" | "danger" | "success" | "orange";
-/** Ring + label scale. */
-export type HighlightSize = "sm" | "md" | "lg";
-/** Label font weight. */
-export type HighlightWeight = "normal" | "bold";
-/** Optional Flow-level defaults for demo rings (episode-wide). Stub/fixture wins. */
-export type HighlightStyleDefaults = {
-    tone?: HighlightTone;
-    size?: HighlightSize;
-    weight?: HighlightWeight;
-};
-/** Apply Flow defaults under per-slot authored values (slot wins when set). */
-export declare function applyHighlightStyleDefaults<T extends {
-    tone?: HighlightTone | string;
-    size?: HighlightSize | string;
-    weight?: HighlightWeight | string;
-}>(slot: T, defaults?: HighlightStyleDefaults | null): T & {
-    tone: HighlightTone;
-    size: HighlightSize;
-    weight: HighlightWeight;
-};
-/** Map author aliases (`error` -> danger) to a canonical tone. */
-export declare function normalizeHighlightTone(raw: unknown): HighlightTone;
-/** Map size aliases to sm/md/lg. */
-export declare function normalizeHighlightSize(raw: unknown): HighlightSize;
-/** Map weight aliases to normal/bold. */
-export declare function normalizeHighlightWeight(raw: unknown): HighlightWeight;
-/** Prefix label with a short ASCII icon for semantic tones. */
-export declare function toneIconPrefix(tone: HighlightTone): string;
-/**
- * Demo pacing for a Flow episode or a Block/compose group.
- * - `blitz` - FF-like: skip theater + short gates (same as fastForwardComposeBlock)
- * - `fast` - shorter gates, keep cursor theater (~0.33x normal)
- * - `normal` - default demo pace (1x)
- * - `slow` - longer autoplay + fixture dwell (~2x)
- * - `number` - scale vs normal when `<= 20` (e.g. `0.5`, `1.5`, `3`);
- *   absolute gate/dwell ms when `> 20` (e.g. `4500`)
- */
-export type DemoPaceName = "blitz" | "fast" | "normal" | "slow";
-export type DemoPace = DemoPaceName | number;
-/** Default fixture dwell when `duration: true`. */
-export declare const FIXTURE_DURATION_MS_DEFAULT = 2000;
-/** Default fixture dwell under `--fast` when duration is enabled. */
-export declare const FIXTURE_DURATION_FAST_MS_DEFAULT = 600;
-/** Default fixture dwell under demo pace `slow` (gaps / wrongs review). */
-export declare const FIXTURE_DURATION_SLOW_MS_DEFAULT = 4000;
-/** @deprecated Prefer FIXTURE_DURATION_MS_DEFAULT */
-export declare const SLIDE_DURATION_MS_DEFAULT = 2000;
-/** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
-export declare const SLIDE_DURATION_FAST_MS_DEFAULT = 600;
-export declare function normalizeDemoPace(raw: unknown): DemoPace;
-/** Named / numeric pace -> scale vs normal (1 = normal). Absolute ms (>20) maps via default dwell. */
-export declare function demoPaceScale(pace: DemoPace): number;
-export declare function demoPaceIsBlitz(pace: DemoPace): boolean;
-/** True when pace should use the short-gate / fast fixture path (not slow authored). */
-export declare function demoPaceIsFast(pace: DemoPace): boolean;
-export declare function demoPaceIsSlow(pace: DemoPace): boolean;
-/** Autoplay / Next-gate ms for this pace (base is WAYGRAPH_AUTOPLAY_MS or 1800). */
-export declare function demoPaceGateMs(pace: DemoPace, baseAutoplayMs: number): number;
-/**
- * Short chip for the demo panel (e.g. `2.5x`, `4500ms`, `slow`).
- * Always printable - numbers speak in the UI, not only in code.
- */
-export declare function formatDemoPaceBadge(pace: DemoPace, baseAutoplayMs?: number): string;
-/**
- * Loud one-line pace description for panel + console
- * (e.g. `pace 2.5x (~4500ms gates)` / `pace 4500ms gates (~2.25x)`).
- */
-export declare function formatDemoPaceLabel(pace: DemoPace, baseAutoplayMs?: number): string;
-/**
- * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
- * or `null` when duration is unset (caller keeps legacy timing).
- *
- * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`
- * (`gatesFast`). `--fast` only shortens when pace is unset/normal.
- */
-export declare function resolveFixtureDwellMs(fixture: FixtureDurationFields, opts?: {
-    gatesFast?: boolean;
-    pace?: DemoPace;
-}): number | null;
-/** @deprecated Prefer {@link resolveFixtureDwellMs} */
-export declare function resolveSlideDwellMs(slide: FixtureDurationFields, opts?: {
-    gatesFast?: boolean;
-    pace?: DemoPace;
-}): number | null;
-/**
- * Effective demo pace for a step: block override > flow episode > normal.
- * Opaque FF / wasFastForward always win as blitz.
- */
-export declare function resolveStepDemoPace(opts: {
-    blockPace?: DemoPace | string | number | null;
-    flowPace?: DemoPace | string | number | null;
-    fastForward?: boolean;
-    wasFastForward?: boolean;
-}): DemoPace;
-export type WaygraphSlidesOrFn<Out extends Checkpoint<string>> = readonly WaygraphSlide[] | ((out: Out) => readonly WaygraphSlide[]);
-/** Demo stub phase names (block instruction + flow fixtures). */
-export type HighlightStubPhaseName = "stubBefore" | "stubAfter" | "stubOnError";
-/** Per-block fixture map attached to a Flow via {@link withHighlightFixtures}. */
-export type HighlightFixtureMap = Record<string, {
-    stubBefore?: Record<string, WaygraphHighlightFixture>;
-    stubAfter?: Record<string, WaygraphHighlightFixture>;
-    /** Fail-path rings (demo step throw) - distinct copy from success stubAfter. */
-    stubOnError?: Record<string, WaygraphHighlightFixture>;
-    /** Override / supply multi-step yap slides for this block (demo only). */
-    slides?: readonly WaygraphSlide[];
-}>;
-/** Legacy array highlight (shimmed to stubAfter keys "0", "1", ...). */
-export interface WaygraphHighlight {
-    selector: string;
-    label: string;
-    tone?: HighlightTone;
-}
-export type ResolvedHighlight = WaygraphHighlightStub;
-/** Normalize checklist dock side. */
-export declare function normalizeTodoPos(raw: unknown): "left" | "right" | undefined;
-/** Normalize dock list style. */
-export declare function normalizeTodoStyle(raw: unknown): TodoListStyle | undefined;
-/**
- * Normalize checklist rows; apply todoIndex for sequential done/current.
- * In checklist / bullets mode, todoIndex is ignored unless items omit explicit done
- * (bullets never auto-mark current).
- */
-export declare function normalizeTodos(todos: readonly WaygraphTodoInput[] | undefined, todoIndex?: number, style?: TodoListStyle): WaygraphTodoItem[];
-/** Build the floating dock from bag / phase fields. */
-export declare function buildTodoDock(opts: {
-    todos?: readonly WaygraphTodoInput[] | undefined;
-    todoIndex?: number | undefined;
-    todoTitle?: string | undefined;
-    todoId?: string | undefined;
-    todoStyle?: TodoListStyle | undefined;
-    todoGroups?: readonly WaygraphTodoGroupInput[] | undefined;
-    todoPos?: "left" | "right" | undefined;
-}): TodoDockState | undefined;
-/**
- * Carry-forward rules for the floating todo dock across demo steps.
- * - clear: author called hideTodos / empty todos()
- * - set: author authored a new dock this phase
- * - keep: author omitted todos — preserve previous dock (do not wipe)
- */
-export declare function applyTodoPhase(prev: TodoDockState | undefined, phase: {
-    todoSync?: "set" | "clear" | "keep";
-    todoDock?: TodoDockState;
-    todos?: WaygraphTodoItem[];
-    todoPos?: "left" | "right";
-    todoId?: string;
-}): {
-    dock: TodoDockState | undefined;
-    sync: "set" | "clear" | "keep";
-};
-/**
- * Advance every sequential group to `index` (capped). Checklist / bullets unchanged.
- * Used while cycling rings / fill/click stubs so the walkthrough moves.
- */
-export declare function advanceTodoDock(dock: TodoDockState | undefined, index: number): TodoDockState | undefined;
-/**
- * Mark sequential groups complete (all done, none current) - e.g. end of step.
- * Checklist / bullets groups keep explicit done flags.
- */
-export declare function completeSequentialTodoDock(dock: TodoDockState | undefined): TodoDockState | undefined;
-/**
- * Run an open stub lifecycle (preferred) or resolve a static slot map.
- * Returns rings + episode fixtures (todos / todoIndex / zoom).
- *
- * @example
- * const before = await runStubPhase(block, "stubBefore", { fixtures });
- * // before.todos, before.highlights
- */
-export declare function runStubPhase(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
-    out?: Checkpoint<string>;
-    error?: unknown;
-    mem?: MemPage;
-    fixtures?: HighlightFixtureMap;
-}): Promise<StubPhaseResult>;
-/**
- * Sync resolve of highlight slots. Prefer {@link runStubPhase} for open
- * async lifecycles + episode fixtures (todos/zoom).
- */
-export declare function resolveHighlightSlots(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
-    out?: Checkpoint<string>;
-    fixtures?: HighlightFixtureMap;
-}): ResolvedHighlight[];
-/**
- * Resolve multi-step yap slides: flow fixture `slides` wins when present,
- * else `instruction.slides` (function form allowed).
- */
-export declare function resolveSlides(block: Block<any, any>, opts?: {
-    out?: Checkpoint<string>;
-    fixtures?: HighlightFixtureMap;
-}): WaygraphSlide[];
-/** Caption for ring / slide UI (label|caption + optional detail/tag + tone icon). */
-export declare function formatHighlightCaption(h: {
-    label?: string;
-    caption?: string;
-    detail?: string;
-    tag?: string;
-    tone?: HighlightTone | string;
-}): string;
-/**
- * True when the block authored stubAfter (lifecycle fn, slots, fixtures, or legacy highlights).
- * When true, demo should not use verify-trait fallback.
- */
-export declare function hasAuthoredStubAfter(block: Block<any, any>, out?: Checkpoint<string>, fixtures?: HighlightFixtureMap): boolean;
-/**
- * True when stubOnError is authored (lifecycle fn and/or rings).
- * Demo fail path only - success never consults this.
- */
-export declare function hasAuthoredStubOnError(block: Block<any, any>, fixtures?: HighlightFixtureMap): boolean;
+export * from "./highlights/types.js";
+export * from "./highlights/todo-dock.js";
+export * from "./highlights/device.js";
+export * from "./highlights/css.js";
+export * from "./highlights/style.js";
+export * from "./highlights/demo-pace.js";
+export * from "./highlights/merge.js";
+export * from "./highlights/stub-ctx.js";
+export * from "./highlights/run-phase.js";