waygraph 0.15.54 → 0.16.1

package/dist/{mem-page.js → engine/mem/mem.js}

@@ -1,4 +1,5 @@
-import { WaygraphError, MSG_MEM_READ_BEFORE_SET } from "./errors.js";
+// Mem: the values a run carries between Blocks (credentials, the row just added), typed by MemKey.
+import { WaygraphError, MSG_MEM_READ_BEFORE_SET } from "../errors.js";
 /**
  * A typed key into MemPage. The phantom `_phantom` field is never assigned - it
  * exists only so TypeScript can infer `T` at each call site. The store is keyed by

package/dist/engine/page-gone.d.ts

@@ -0,0 +1,5 @@
+export declare function isPageGone(err: unknown): boolean;
+/** `.catch(ignorePageGone)`: the call is moot when the page went away; anything else is rethrown. */
+export declare function ignorePageGone(err: unknown): undefined;
+/** `.catch(ignoreTimeout)`: a probe that waited as long as it should (or whose page went away); anything else is rethrown. */
+export declare function ignoreTimeout(err: unknown): undefined;

package/dist/engine/page-gone.js

@@ -0,0 +1,20 @@
+// The failures a page call may ignore, and nothing else: the page went away (a navigation or a close), or a probe ran
+// out of time. Any other error is real and goes through.
+import { errors } from "@playwright/test";
+/** Playwright has no error class for a closed page or a destroyed document, only these messages. */
+const GONE = /Target page, context or browser has been closed|Target closed|Browser has been closed|Execution context was destroyed|frame was detached|Frame has been detached|Session closed|Cannot find context with specified id|Failed to find context with id/i;
+export function isPageGone(err) {
+    return err instanceof Error && GONE.test(err.message);
+}
+/** `.catch(ignorePageGone)`: the call is moot when the page went away; anything else is rethrown. */
+export function ignorePageGone(err) {
+    if (isPageGone(err))
+        return undefined;
+    throw err;
+}
+/** `.catch(ignoreTimeout)`: a probe that waited as long as it should (or whose page went away); anything else is rethrown. */
+export function ignoreTimeout(err) {
+    if (err instanceof errors.TimeoutError || isPageGone(err))
+        return undefined;
+    throw err;
+}

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

@@ -0,0 +1,28 @@
+import type { Block } from "../block/block.js";
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { Trait } from "../trait/trait.js";
+/**
+ * Structural twin of `run.ts`'s `Layout`, so this file needs no import from it. Any real `Layout` satisfies it with no
+ * cast at the `connect()` call site.
+ */
+export interface ConnectLayout {
+    name: string;
+    appliesTo: (tag: string) => boolean;
+    verify: Trait[] | ((out: any) => Trait[]);
+}
+/**
+ * Composes two Blocks into one, typechecked so this only compiles when A's output
+ * tag equals B's input tag. The composed Block's act runs A's full instruction
+ * (act -> observe? -> resolve) then hands the resulting Checkpoint into B's act;
+ * its own observe/resolve are simply B's, since B is what decides the final Out.
+ *
+ * `layouts`, if given, also runs against the intermediate Checkpoint (A's
+ * resolved output, right before B's act) - the same enforcement `runGraph`'s
+ * own loop already applies to a chain's FINAL Checkpoint, but a
+ * `map()`-built Flow never reaches that loop per-hop: `buildFlow`
+ * reduces the whole Block array into one `connect()`-composed super-Block, so
+ * every intermediate hop's verify (and now layout) has to run HERE, inside
+ * this recursive `act`, not in `runGraph`'s loop, which only ever sees the
+ * one composed Block run start to finish.
+ */
+export declare function connect<A extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>>(a: Block<A, B>, b: Block<B, C>, layouts?: readonly ConnectLayout[]): Block<A, C>;

package/dist/{types.js → engine/run/connect.js}

@@ -1,11 +1,5 @@
-import { runVerify, runPrecondition } from "./trait.js";
-/**
- * Builds a Checkpoint - spells `__state` for you so no call site does it by hand.
- * @example resolve: () => checkpoint("LoggedIn")
- */
-export function checkpoint(tag) {
-    return { __state: tag };
-}
+import { runVerify, runPrecondition } from "../trait/trait.js";
+import { isConnected, lastLeaf, stepEnded, stepStarted } from "./events.js";
 /**
  * Composes two Blocks into one, typechecked so this only compiles when A's output
  * tag equals B's input tag. The composed Block's act runs A's full instruction
@@ -15,7 +9,7 @@ export function checkpoint(tag) {
  * `layouts`, if given, also runs against the intermediate Checkpoint (A's
  * resolved output, right before B's act) - the same enforcement `runGraph`'s
  * own loop already applies to a chain's FINAL Checkpoint, but a
- * `defineFlow`-built Flow never reaches that loop per-hop: `buildFlow`
+ * `map()`-built Flow never reaches that loop per-hop: `buildFlow`
  * reduces the whole Block array into one `connect()`-composed super-Block, so
  * every intermediate hop's verify (and now layout) has to run HERE, inside
  * this recursive `act`, not in `runGraph`'s loop, which only ever sees the
@@ -25,11 +19,13 @@ export function connect(a, b, layouts) {
     const bObserve = b.instruction.observe;
     const bVerify = b.instruction.verify;
     const requires = [...(a.requires ?? []), ...(b.requires ?? [])];
-    return {
+    const connected = {
         name: `${a.name} -> ${b.name}`,
         ...(requires.length > 0 ? { requires } : {}),
         instruction: {
             async act(page, input, mem) {
+                if (!isConnected(a))
+                    stepStarted(a.name, input.__state);
                 await runPrecondition(a.instruction.precondition, input, page, mem, a.name);
                 await a.instruction.act(page, input, mem);
                 const aObserved = a.instruction.observe
@@ -44,6 +40,9 @@ export function connect(a, b, layouts) {
                         await runVerify(layout.verify, mid, page, mem, `${a.name} (layout: "${layout.name}")`);
                     }
                 }
+                stepEnded(lastLeaf(a), mid.__state);
+                if (!isConnected(b))
+                    stepStarted(b.name, mid.__state);
                 await runPrecondition(b.instruction.precondition, mid, page, mem, b.name);
                 await b.instruction.act(page, mid, mem);
             },
@@ -54,4 +53,6 @@ export function connect(a, b, layouts) {
             ...(bVerify ? { verify: bVerify } : {}),
         },
     };
+    Object.defineProperty(connected, "__wgLastLeaf", { value: lastLeaf(b), enumerable: false });
+    return connected;
 }

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

@@ -0,0 +1,67 @@
+export type RunEvent = {
+    type: "run:start";
+    runId: string;
+    at: number;
+    label?: string;
+} | {
+    type: "step:start";
+    runId: string;
+    at: number;
+    index: number;
+    block: string;
+    from: string;
+} | {
+    type: "step:end";
+    runId: string;
+    at: number;
+    index: number;
+    block: string;
+    to: string;
+    ms: number;
+} | {
+    type: "step:error";
+    runId: string;
+    at: number;
+    index: number;
+    block: string;
+    error: string;
+    ms: number;
+} | {
+    type: "run:end";
+    runId: string;
+    at: number;
+    ok: boolean;
+    result?: string;
+    error?: string;
+    ms: number;
+} | {
+    type: "run:artifact";
+    runId: string;
+    at: number;
+    kind: "video" | "trace" | "screenshot";
+    path: string;
+};
+/** What {@link onRunEvent} calls with each event. */
+export type RunEventListener = (event: RunEvent) => void;
+/** Subscribes to every run event in this process; returns the unsubscribe function. */
+export declare function onRunEvent(listener: RunEventListener): () => void;
+/**
+ * Opens a run, or joins the one already open (a flow nested in another, or a runner driving a chain step by step). Returns
+ * whether this call opened it, so only the opener closes it.
+ */
+export declare function beginRun(label?: string): boolean;
+/** Closes the run when the matching `beginRun` opened it. */
+export declare function endRun(opened: boolean, outcome: {
+    result?: string;
+    error?: unknown;
+}): void;
+export declare function stepStarted(block: string, from: string): void;
+export declare function stepEnded(block: string, to: string): void;
+/** The step that started last failed. */
+export declare function stepFailed(error: unknown): void;
+/** The id of the run open right now, if any. */
+export declare function currentRunId(): string | undefined;
+export declare function recordArtifact(kind: "video" | "trace" | "screenshot", path: string, runId?: string | undefined): void;
+/** The last real Block inside a Block built by `connect` (or the Block itself). */
+export declare function lastLeaf(block: object): string;
+export declare function isConnected(block: object): boolean;

package/dist/engine/run/events.js

@@ -0,0 +1,90 @@
+// Run events: what happened, step by step, during a run. Core emits them; subscribers (the run log, the demo overlay,
+// reports, Waygraph UI) listen. Emitting never throws into the run.
+const listeners = new Set();
+/** Subscribes to every run event in this process; returns the unsubscribe function. */
+export function onRunEvent(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+function emit(event) {
+    for (const listener of listeners) {
+        try {
+            listener(event);
+        }
+        catch {
+            /* a broken subscriber never breaks a run */
+        }
+    }
+}
+let open;
+/**
+ * Opens a run, or joins the one already open (a flow nested in another, or a runner driving a chain step by step). Returns
+ * whether this call opened it, so only the opener closes it.
+ */
+export function beginRun(label) {
+    if (open) {
+        open.depth += 1;
+        return false;
+    }
+    const at = Date.now();
+    open = { runId: `${new Date(at).toISOString().replace(/[:.]/g, "-")}-${crypto.randomUUID().slice(0, 8)}`, startedAt: at, depth: 1, index: 0 };
+    emit({ type: "run:start", runId: open.runId, at, ...(label ? { label } : {}) });
+    return true;
+}
+/** Closes the run when the matching `beginRun` opened it. */
+export function endRun(opened, outcome) {
+    if (!open)
+        return;
+    open.depth -= 1;
+    if (!opened)
+        return;
+    const at = Date.now();
+    emit({
+        type: "run:end",
+        runId: open.runId,
+        at,
+        ok: outcome.error === undefined,
+        ...(outcome.result !== undefined ? { result: outcome.result } : {}),
+        ...(outcome.error !== undefined ? { error: outcome.error instanceof Error ? outcome.error.message : String(outcome.error) } : {}),
+        ms: at - open.startedAt,
+    });
+    open = undefined;
+}
+export function stepStarted(block, from) {
+    if (!open)
+        return;
+    const at = Date.now();
+    open.step = { index: open.index++, block, startedAt: at };
+    emit({ type: "step:start", runId: open.runId, at, index: open.step.index, block, from });
+}
+export function stepEnded(block, to) {
+    if (!open?.step)
+        return;
+    const at = Date.now();
+    emit({ type: "step:end", runId: open.runId, at, index: open.step.index, block, to, ms: at - open.step.startedAt });
+    open.step = undefined;
+}
+/** The step that started last failed. */
+export function stepFailed(error) {
+    if (!open?.step)
+        return;
+    const at = Date.now();
+    const { index, block, startedAt } = open.step;
+    emit({ type: "step:error", runId: open.runId, at, index, block, error: error instanceof Error ? error.message : String(error), ms: at - startedAt });
+    open.step = undefined;
+}
+/** The id of the run open right now, if any. */
+export function currentRunId() {
+    return open?.runId;
+}
+export function recordArtifact(kind, path, runId = open?.runId) {
+    if (runId)
+        emit({ type: "run:artifact", runId, at: Date.now(), kind, path });
+}
+/** The last real Block inside a Block built by `connect` (or the Block itself). */
+export function lastLeaf(block) {
+    return block.__wgLastLeaf ?? block.name;
+}
+export function isConnected(block) {
+    return block.__wgLastLeaf !== undefined;
+}

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

@@ -0,0 +1,16 @@
+import type { Page } from "@playwright/test";
+/** One HTTP call a Block made on its own (`defineApiBlock`), for whatever is showing network activity. */
+export interface ApiCallRecord {
+    method: string;
+    url: string;
+    status: number;
+    ok: boolean;
+    ms: number;
+    resHeaders?: Record<string, string> | undefined;
+    resBody?: string | undefined;
+}
+type ApiCallRecorder = (page: Page, entry: ApiCallRecord) => void | Promise<void>;
+/** The demo layer registers how an API call is shown (the network panel). Without one, calls are not recorded. */
+export declare function setApiCallRecorder(recorder: ApiCallRecorder | undefined): void;
+export declare function recordApiCall(page: Page, entry: ApiCallRecord): Promise<void>;
+export {};

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;