waygraph 0.15.54 → 0.16.0

package/dist/engine/run/hooks.js

@@ -0,0 +1,8 @@
+let apiCallRecorder;
+/** The demo layer registers how an API call is shown (the network panel). Without one, calls are not recorded. */
+export function setApiCallRecorder(recorder) {
+    apiCallRecorder = recorder;
+}
+export async function recordApiCall(page, entry) {
+    await apiCallRecorder?.(page, entry);
+}

package/dist/engine/run/launch.d.ts

@@ -0,0 +1,13 @@
+import type { BrowserContext } from "@playwright/test";
+import type { EngineConfig } from "../config.js";
+/** A browser context an Engine opened for itself, and how to close it again. */
+export interface OwnContext {
+    context: BrowserContext;
+    close(): Promise<void>;
+}
+type OwnContextLauncher = (config: EngineConfig | undefined) => Promise<OwnContext>;
+/** The runtime layer registers the full launch (selected config, Chromium path, extensions); see `runtime/full-launch.ts`. */
+export declare function setOwnContextLauncher(next: OwnContextLauncher): void;
+/** Opens the browser and context a `Flow.run(mem)` uses when the caller gave none. */
+export declare function launchOwnContext(config: EngineConfig | undefined): Promise<OwnContext>;
+export {};

package/dist/engine/run/launch.js

@@ -0,0 +1,27 @@
+import { resolveLauncher } from "../config.js";
+import { envString } from "../env.js";
+/** Plain Playwright launch: what an Engine does when nothing richer is registered (no config file, no extensions). */
+async function plainLaunch(config) {
+    if (config?.extensions?.length) {
+        throw new Error('waygraph: browser extensions need the runtime layer - import the Engine from "waygraph"');
+    }
+    const browser = await resolveLauncher(config?.browserName ?? "chromium", config).launch({
+        headless: config?.headless ?? true,
+        ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
+    });
+    const baseURL = config?.baseUrl ?? envString("WAYGRAPH_BASE_URL");
+    const context = await browser.newContext({
+        ...(baseURL ? { baseURL } : {}),
+        ...(config?.recordVideo ? { recordVideo: config.recordVideo } : {}),
+    });
+    return { context, close: () => browser.close() };
+}
+let launcher = plainLaunch;
+/** The runtime layer registers the full launch (selected config, Chromium path, extensions); see `runtime/full-launch.ts`. */
+export function setOwnContextLauncher(next) {
+    launcher = next;
+}
+/** Opens the browser and context a `Flow.run(mem)` uses when the caller gave none. */
+export function launchOwnContext(config) {
+    return launcher(config);
+}

package/dist/{core/run-graph.d.ts → engine/run/run.d.ts}

@@ -1,16 +1,18 @@
-import { MemPage } from "../mem-page.js";
-import type { Block, Checkpoint } from "../types.js";
-import type { Trait } from "../trait.js";
+import { MemPage } from "../mem/mem.js";
+import type { Block } from "../block/block.js";
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { Trait } from "../trait/trait.js";
 import type { BrowserContext, Locator, Page } from "@playwright/test";
+import type { SomeBlock } from "../block/block.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
  * once, if any are unset. `connect()` unions each Block's `requires` into the
- * composed Block, so calling this on a `defineFlow`-built Flow's entry - which
+ * composed Block, so calling this on a `map()`-built Flow's entry - which
  * `runGraph` does automatically, before opening a tab - covers every Block in
  * that flow. It does not see Blocks only reachable through `branch()` routing,
  * since those depend on a runtime decision that hasn't happened yet.
  */
-export declare function preflight(mem: MemPage, block: Block<any, any>): void;
+export declare function preflight(mem: MemPage, block: SomeBlock): void;
 /**
  * A cross-cutting, automatically-enforced verify - the real engine
  * primitive behind "persistent UI" (a sidebar, a header, anything that's
@@ -73,7 +75,7 @@ export declare function defineLayout(options: LayoutOptions): Layout;
  * `terminals`, if given, is a sanity check: the Checkpoint the run stops on must be
  * one of the tags the caller actually expects, or the run fails loud instead of
  * silently returning an unexpected result. Omit it when there is only ever one
- * reachable outcome by construction (as with a `defineFlow`-built Flow, which has
+ * reachable outcome by construction (as with a `map()`-built Flow, which has
  * no routing at all) - there is nothing to validate against.
  */
 export declare function runGraph<TOut extends Checkpoint<string>>(entry: Block<Checkpoint<"__start__">, TOut>, terminals: ReadonlySet<string> | undefined, context: BrowserContext, mem: MemPage, maxSteps?: number, options?: RunGraphOptions): Promise<TOut>;
@@ -141,9 +143,3 @@ export declare function spawnTab<TOut extends Checkpoint<string>>(entry: Block<C
  * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
  */
 export declare function narrate<T>(locator: Locator, caption: string, action: () => Promise<T>): Promise<T>;
-/** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
-export declare const start: unique symbol;
-/** Marks the end of a hand-built chain. Only the deprecated `defineFlow` needs it; `map()` does not. */
-export declare const end: unique symbol;
-export type StartMarker = typeof start;
-export type EndMarker = typeof end;

package/dist/{core/run-graph.js → engine/run/run.js}

@@ -1,10 +1,12 @@
 import { WaygraphError, MSG_PREFLIGHT_MISSING_KEY, MSG_RUNGRAPH_MAX_STEPS, MSG_RUNGRAPH_NOT_TERMINAL } from "../errors.js";
-import { checkpoint } from "../types.js";
-import { runPrecondition, runVerify } from "../trait.js";
+import { checkpoint } from "../checkpoint/checkpoint.js";
+import { beginRun, endRun, isConnected, lastLeaf, stepEnded, stepFailed, stepStarted } from "./events.js";
+import { runPrecondition, runVerify } from "../trait/trait.js";
+import { ignorePageGone } from "../page-gone.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
  * once, if any are unset. `connect()` unions each Block's `requires` into the
- * composed Block, so calling this on a `defineFlow`-built Flow's entry - which
+ * composed Block, so calling this on a `map()`-built Flow's entry - which
  * `runGraph` does automatically, before opening a tab - covers every Block in
  * that flow. It does not see Blocks only reachable through `branch()` routing,
  * since those depend on a runtime decision that hasn't happened yet.
@@ -70,15 +72,17 @@ async function runLayouts(layouts, tag, out, page, mem, blockName) {
  * `terminals`, if given, is a sanity check: the Checkpoint the run stops on must be
  * one of the tags the caller actually expects, or the run fails loud instead of
  * silently returning an unexpected result. Omit it when there is only ever one
- * reachable outcome by construction (as with a `defineFlow`-built Flow, which has
+ * reachable outcome by construction (as with a `map()`-built Flow, which has
  * no routing at all) - there is nothing to validate against.
  */
 export async function runGraph(entry, terminals, context, mem, maxSteps = 5000, options) {
     preflight(mem, entry);
     const page = options?.page ?? (await context.newPage());
     const closeOnFinish = options?.closeOnFinish ?? true;
+    const opened = beginRun();
+    let result;
+    let failure;
     try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let current = entry;
         let input = checkpoint("__start__");
         let steps = 0;
@@ -86,6 +90,8 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
             if (++steps > maxSteps) {
                 throw new WaygraphError("WG_RUNGRAPH_MAX_STEPS", MSG_RUNGRAPH_MAX_STEPS(maxSteps));
             }
+            if (!isConnected(current))
+                stepStarted(current.name, input.__state);
             await runPrecondition(current.instruction.precondition, input, page, mem, current.name);
             await current.instruction.act(page, input, mem);
             const observed = current.instruction.observe
@@ -94,18 +100,26 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
             const checkpoint = await current.instruction.resolve(observed);
             await runVerify(current.instruction.verify, checkpoint, page, mem, current.name);
             await runLayouts(options?.layouts, checkpoint.__state, checkpoint, page, mem, current.name);
+            stepEnded(lastLeaf(current), checkpoint.__state);
             const next = current.next?.(checkpoint);
             if (!next) {
                 if (terminals && !terminals.has(checkpoint.__state)) {
                     throw new WaygraphError("WG_RUNGRAPH_NOT_TERMINAL", MSG_RUNGRAPH_NOT_TERMINAL(current.name, checkpoint.__state, [...terminals].join(", ")));
                 }
+                result = checkpoint.__state;
                 return checkpoint;
             }
             current = next;
             input = checkpoint;
         }
     }
+    catch (err) {
+        failure = err;
+        stepFailed(err);
+        throw err;
+    }
     finally {
+        endRun(opened, failure === undefined ? { ...(result !== undefined ? { result } : {}) } : { error: failure });
         if (closeOnFinish) {
             await page.close();
         }
@@ -177,7 +191,7 @@ export async function narrate(locator, caption, action) {
                 // true; narrate() below is the one that actually clears it.
                 w.__wgNarrateOwnsRing = true;
             }, { box, caption })
-                .catch(() => { });
+                .catch(ignorePageGone);
             owning = true;
             // The ring alone is pointless if action() fires on the very next
             // tick - a click that navigates (e.g. a form submit) wipes the ring
@@ -195,7 +209,7 @@ export async function narrate(locator, caption, action) {
                 .evaluate(() => {
                 globalThis.__wgLastNarrate = Date.now();
             })
-                .catch(() => { });
+                .catch(ignorePageGone);
         }
     }
     catch {
@@ -213,11 +227,7 @@ export async function narrate(locator, caption, action) {
                 if (w.__wgHideRing)
                     w.__wgHideRing();
             })
-                .catch(() => { });
+                .catch(ignorePageGone);
         }
     }
 }
-/** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
-export const start = Symbol("waygraph.start");
-/** Marks the end of a hand-built chain. Only the deprecated `defineFlow` needs it; `map()` does not. */
-export const end = Symbol("waygraph.end");

package/dist/engine/stub/pace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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";
+/** How fast a demo step runs: `"fast"`, `"slow"`, `"blitz"`, `"normal"`, or a multiplier (`0.5`, `2`). */
+export type DemoPace = DemoPaceName | number;

package/dist/engine/stub/pace.js

@@ -0,0 +1,2 @@
+// How fast a demo step plays.
+export {};

package/dist/engine/stub/ring.d.ts

@@ -0,0 +1,130 @@
+import type { Checkpoint } from "../checkpoint/checkpoint.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 its default timing)
+     */
+    duration?: boolean | number;
+    /**
+     * Dwell ms when demo `--fast` / gatesFast (only when {@link duration} is set).
+     * Default 600.
+     */
+    fastMode?: number;
+};
+/** 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;
+    /**
+     * Caption text color (CSS color). Overrides tone label color when set.
+     */
+    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";
+}
+/** A static stub phase: named ring slots to paint before or after a step. */
+export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
+/**
+ * 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;
+};
+export type WaygraphSlidesOrFn<Out extends Checkpoint<string>> = readonly WaygraphSlide[] | ((out: Out) => readonly WaygraphSlide[]);
+/** A ring or caption after its defaults and overrides are merged, ready to paint. */
+export type ResolvedHighlight = WaygraphHighlightStub;
+/** 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;

package/dist/engine/stub/ring.js

@@ -0,0 +1,41 @@
+/** Map author aliases (`error` -> danger) to a canonical tone. */
+export function normalizeHighlightTone(raw) {
+    if (typeof raw !== "string")
+        return "planned";
+    const t = raw.trim().toLowerCase();
+    if (t === "auto" || t === "automation" || t === "engine")
+        return "auto";
+    if (t === "info" || t === "blue")
+        return "info";
+    if (t === "warning" || t === "warn" || t === "yellow")
+        return "warning";
+    if (t === "danger" || t === "error" || t === "red")
+        return "danger";
+    if (t === "success" || t === "ok" || t === "green")
+        return "success";
+    if (t === "orange" || t === "amber" || t === "dom" || t === "inspect")
+        return "orange";
+    if (t === "planned" || t === "purple" || t === "authored")
+        return "planned";
+    return "planned";
+}
+/** Map size aliases to sm/md/lg. */
+export function normalizeHighlightSize(raw) {
+    if (typeof raw !== "string")
+        return "md";
+    const t = raw.trim().toLowerCase();
+    if (t === "sm" || t === "s" || t === "small" || t === "tiny")
+        return "sm";
+    if (t === "lg" || t === "l" || t === "large" || t === "big" || t === "xl")
+        return "lg";
+    return "md";
+}
+/** Map weight aliases to normal/bold. */
+export function normalizeHighlightWeight(raw) {
+    if (typeof raw !== "string")
+        return "normal";
+    const t = raw.trim().toLowerCase();
+    if (t === "bold" || t === "strong" || t === "heavy" || t === "b")
+        return "bold";
+    return "normal";
+}

package/dist/engine/stub/stub.d.ts

@@ -0,0 +1,268 @@
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { MemPage } from "../mem/mem.js";
+import type { TodoDockState, TodoDockUiOpts, TodoListStyle, WaygraphTodoGroupInput, WaygraphTodoInput, WaygraphTodoItem, WaygraphTodosOpts } from "./todos.js";
+import type { DeviceOrientation, DevicePreset, DeviceState, DeviceViewport } from "./viewport.js";
+import type { HighlightStubPhase, ResolvedHighlight, WaygraphHighlightStub } from "./ring.js";
+/** Where the top banner sits. */
+export type BannerPos = "left" | "center" | "right";
+/** Banner UX, mirrors {@link TodoDockUiOpts}: pass `false` fields to opt out for this phase. */
+export interface BannerUiOpts {
+    /** Move to a free spot while a highlight ring would overlap it (default true). */
+    collision?: boolean;
+    /** Hide the banner entirely for this phase. */
+    hidden?: boolean;
+    /**
+     * Fade duration (ms) when the banner's title text changes, so a change reads as a deliberate
+     * beat instead of an instant flicker. Default 220; 0 disables the fade (instant swap).
+     */
+    captionFadeMs?: number;
+}
+/** 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;
+    /** Banner side/position (`left` | `center` | `right`). Authored control, like the todo dock's `pos`. */
+    titlePos?: BannerPos;
+    /** Banner UX: collision (move away from a ring it overlaps), hidden. See {@link BannerUiOpts}. */
+    bannerUi?: BannerUiOpts;
+    /**
+     * Bottom narration caption - a white rounded card (black text, shadow), bottom-centered above
+     * the step pill, distinct from the banner (top, card-shaped). Omit/clear to hide it; set again
+     * to change the text, fading out/in.
+     */
+    caption?: string;
+    /**
+     * Network-tab overlay visibility - capture always happens in the background regardless; this
+     * only controls whether the panel itself is shown. Intentionally hidden by default (`undefined`
+     * on the very first phase); omit to leave whatever the previous step set alone.
+     */
+    networkTabVisible?: boolean;
+    /**
+     * 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;
+};
+/**
+ * What a stub is given: chained where a flow uses a Block, it paints rings, todos, the device and the banner.
+ *
+ * @example
+ * LoginBlock.stubBefore((ctx) => {
+ *   ctx.todos("sign-in", ["Enter email", "Enter password", "Click Sign in"], { index: 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 / a later Block's stubBefore
+ * .stubAfter((ctx) => {
+ *   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: `ctx.todos("login", ["Enter email", "Enter password"], { title: "Sign in", index: 0 })`.
+     * The id is the dock's `data-wg-todo-id` (stable through redirects). One dock at a time (setting todos replaces it);
+     * pass `{ parallel: true }` to keep docks with other ids. An empty list hides the dock.
+     */
+    todos(id: string, items: readonly WaygraphTodoInput[], opts?: WaygraphTodosOpts): void;
+    /** Moves the current dock's current item (sequential plans: a later step bumps it). */
+    todoIndex(n: number): void;
+    /** Several titled lists in one dock (e.g. Functional Requirements / Scenarios / ACs), with the same id and options as {@link StubCtx.todos}. */
+    todoGroups(id: string, groups: readonly WaygraphTodoGroupInput[], opts?: Omit<WaygraphTodosOpts, "index">): void;
+    /**
+     * Hide the floating todo dock. Omit todos on a later block = **keep** the
+     * previous dock (carry forward). Only hideTodos or an empty todos list clears it.
+     */
+    hideTodos(): void;
+    /**
+     * Viewport / device fixture (0.13+). `mobile` | `tablet` | `desktop`.
+     * Omit on later blocks = **keep** (same persist as todos). Use
+     * {@link StubCtx.hideDevice} or `device("desktop")` 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;
+    /**
+     * Reset to desktop viewport and clear touch mode. Omit device on a later
+     * block = **keep**; only hideDevice / device("desktop") clears.
+     */
+    hideDevice(): 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). `opts.pos` also places it (left | center | right). */
+    title(text: string, opts?: {
+        pos?: BannerPos;
+    }): void;
+    /** Place the banner: `left` | `center` | `right` (authored; click / env are fallbacks). */
+    titlePos(side: BannerPos): void;
+    /**
+     * Banner UX: `{ collision: false }` keeps it put even over a ring; `{ hidden: true }` hides it.
+     * @example ctx.bannerUi({ collision: false });
+     */
+    bannerUi(opts: BannerUiOpts): void;
+    /**
+     * Bottom narration caption - a white rounded card (black text, shadow), bottom-centered above
+     * the step pill; distinct from {@link StubCtx.title}, which is the top banner card. Fades in/out
+     * on change. Pass `""` (or call {@link StubCtx.hideCaption}) to clear.
+     * @example ctx.caption("Click Add to cart to continue");
+     */
+    caption(text: string): void;
+    /** Clears the caption (fades it out). */
+    hideCaption(): void;
+    /** Shorthand for `bannerUi({ hidden: true })`. */
+    hideBanner(): void;
+    /**
+     * Shows the network-tab overlay (Postman-style inspector of real page traffic + defineApiBlock
+     * calls) - capture always runs in the background; this just reveals the panel. Hidden by default.
+     * @example ctx.showNetworkTab();
+     */
+    showNetworkTab(): void;
+    /** Hides the network-tab overlay (capture keeps running - only the panel disappears). */
+    hideNetworkTab(): 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 the full list
+     */
+    todoDockUi(opts: TodoDockUiOpts): void;
+};
+/** A stub callback: receives the stub `ctx` and paints rings, titles and todos. */
+export type StubLifecycleFn<Out extends Checkpoint<string>> = (ctx: StubCtx<Out>) => void | Promise<void>;
+/** 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 / device desktop)
+     * - `keep` - author omitted device; demo must leave previous alone
+     */
+    deviceSync?: "set" | "clear" | "keep";
+    zoom?: number;
+    zoomOut?: boolean;
+    title?: string;
+    titlePos?: BannerPos;
+    bannerUi?: BannerUiOpts;
+    caption?: string;
+    networkTabVisible?: boolean;
+    todoPos?: "left" | "right";
+    /** When true, keep other docks (multi-todo). Default false = replace. */
+    todoParallel?: boolean;
+};
+/** Demo stub phase names. */
+export type HighlightStubPhaseName = "stubBefore" | "stubAfter" | "stubOnError";
+export type StubBagState = {
+    highlights: HighlightStubPhase;
+    todos?: readonly WaygraphTodoInput[] | undefined;
+    todoIndex?: number | undefined;
+    todoTitle?: string | undefined;
+    todoId?: string | undefined;
+    todoStyle?: TodoListStyle | undefined;
+    todoGroups?: readonly WaygraphTodoGroupInput[] | undefined;
+    /** Author touched the todo dock this phase (set or clear). */
+    todoTouched?: boolean | undefined;
+    /** Author asked to hide the dock. */
+    hideTodos?: boolean | undefined;
+    /** Author touched device this phase (set or clear). */
+    deviceTouched?: boolean | undefined;
+    /** Author asked to reset to desktop. */
+    hideDevice?: boolean | undefined;
+    device?: DeviceState | undefined;
+    /** Touch override when set via ctx.touch() alone or with device. */
+    touchOverride?: boolean | undefined;
+    /** Orientation override when set via ctx.orientation / landscape / portrait. */
+    orientationOverride?: DeviceOrientation | undefined;
+    zoom?: number | undefined;
+    zoomOut?: boolean | undefined;
+    title?: string | undefined;
+    titlePos?: BannerPos | undefined;
+    bannerUi?: BannerUiOpts | undefined;
+    caption?: string | undefined;
+    networkTabVisible?: boolean | undefined;
+    todoPos?: "left" | "right" | undefined;
+    /** Author patched todo-dock UX this phase. */
+    todoDockUi?: TodoDockUiOpts | undefined;
+    /** Keep sibling docks (compact todos opts.parallel). */
+    todoParallel?: boolean | undefined;
+};

package/dist/engine/stub/stub.js

@@ -0,0 +1 @@
+export {};