waygraph 0.16.0 → 0.16.2

package/dist/engine/flow/map-builder.d.ts

@@ -1,34 +1,19 @@
+import type { SomeBlock } from "../block/block.js";
+import type { EffectBlock } from "../block/kinds/effect.js";
+import type { AssertBlock, MethodBlock } from "../block/kinds/method.js";
+import type { NavBlock } from "../block/kinds/nav.js";
+import type { PageBlock } from "../block/kinds/page.js";
 import type { Checkpoint } from "../checkpoint/checkpoint.js";
-import type { Flow, FlowSettings } from "./flow.js";
 import type { DemoPace } from "../stub/pace.js";
 import type { HighlightStyleDefaults } from "../stub/ring.js";
-import type { NavBlock } from "../block/kinds/nav.js";
-import type { PageBlock } from "../block/kinds/page.js";
-import type { AssertBlock, MethodBlock } from "../block/kinds/method.js";
-import type { EffectBlock } from "../block/kinds/effect.js";
-import type { SomeBlock } from "../block/block.js";
+import type { Flow, FlowSettings } from "./flow.js";
+import { MapStepOpts } from "./map-steps.js";
 type S = Checkpoint<"__start__">;
 /**
  * The one capability MapBuilder needs from Engine: turn the finished steps into a Flow with the engine's config. A
  * function, not the Engine class, so engine.ts and map-builder.ts don't import each other.
  */
 export type BuildFlowFn = (steps: readonly SomeBlock[], settings: FlowSettings) => Flow<Checkpoint<string>>;
-/** Per-step options for the map builder: `ff` fast-forwards the step, `pace` sets its demo pace. */
-export interface MapStepOpts {
-    /**
-     * Fast-forward just this step, inline - no `.ffStart()/.ffEnd()` bracket needed. Consecutive
-     * `{ ff: true }` steps merge into ONE fast-forward block, same result as the explicit bracket
-     * form; a step without the flag closes an auto-opened window first.
-     * @example map().gotoPage(NavLoginBlock, { ff: true }).method(FillUsernameBlock, { ff: true })
-     */
-    ff?: boolean;
-    /**
-     * Demo pace for just this step (`"blitz"` skips the typing animation and the pause after the action; `"fast"`, `"slow"`,
-     * or a number scale the narration gates).
-     * @example map().method(SetBearerTokenBlock, { pace: "blitz" })
-     */
-    pace?: DemoPace;
-}
 /** Flow-level settings for `engine.map({ … })`: `memStub`, `sessionReset`, `expectedFailure`, `demoPace`, `highlightStyle`, `homeOrigin`. */
 export interface MapBuilderOptions {
     /**

package/dist/engine/flow/map-builder.js

@@ -1,148 +1,7 @@
-import { WaygraphError, MSG_MAP_WRONG_KIND, MSG_MAP_WRONG_SALT, MSG_MAP_WRONG_ORIGIN_INTERNAL, MSG_MAP_WRONG_ORIGIN_EXTERNAL, MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED, MSG_MAP_FF_ALREADY_OPEN, MSG_MAP_FF_NOT_OPEN, MSG_MAP_FF_EMPTY, MSG_MAP_METHOD_GOT_ASSERT, MSG_MAP_BRANCH_NO_PRIOR_STEP, MSG_MAP_FF_NOT_CLOSED, MSG_MAP_EMPTY, } from "../errors.js";
-import { MemPage } from "../mem/mem.js";
 import { fastForwardComposeBlock } from "../block/compose.js";
-import { clearSessionState } from "./flow.js";
-import { copyWaygraphRuntime } from "../block/block.js";
-/** Per-step options every `MapBuilder` step method (`.gotoPage()`/`.method()`/`.assert()`) takes. */
-/** The same Block, but it clears cookies and storage before it acts. Keeps the runtime markers. */
-function resetBefore(block) {
-    const act = block.instruction.act.bind(block.instruction);
-    const next = {
-        ...block,
-        instruction: {
-            ...block.instruction,
-            async act(page, input, mem) {
-                await clearSessionState(page.context(), page);
-                return act(page, input, mem);
-            },
-        },
-    };
-    copyWaygraphRuntime(block, next);
-    Object.defineProperty(next, "__waygraphResetBefore", { value: true, enumerable: false, configurable: true });
-    return next;
-}
-/** Applies a step's `pace` option, keeping the Block's runtime markers. */
-function paced(block, opts) {
-    if (opts?.pace === undefined)
-        return block;
-    const next = { ...block, demoPace: opts.pace };
-    copyWaygraphRuntime(block, next);
-    return next;
-}
-function mapKindOf(block) {
-    return block?.__waygraphKind;
-}
-function mapSaltOf(block) {
-    return block?.__waygraphSalt;
-}
-function mapNavUrlOf(block) {
-    const url = block?.__waygraphNavUrl;
-    return typeof url === "string" ? url : undefined;
-}
-const MAP_KIND_FACTORY_HINT = {
-    nav: "defineNavBlock/defineMemNavBlock",
-    page: "definePageBlock",
-    assert: "defineAssertBlock",
-};
-const MAP_SALT_FACTORY_HINT = {
-    method: "defineMethodBlock",
-    effect: "defineEffectBlock",
-    api: "defineApiBlock",
-};
-function assertMapKind(block, allowed, method) {
-    const kind = mapKindOf(block);
-    if (kind !== undefined && allowed.includes(kind))
-        return;
-    const wanted = allowed.map((k) => MAP_KIND_FACTORY_HINT[k] ?? k).join(" or ");
-    const found = kind ? `a Block of kind "${kind}"` : "an object with no waygraph kind marker at all";
-    throw new WaygraphError("WG_MAP_WRONG_KIND", MSG_MAP_WRONG_KIND(method, block?.name ?? "?", wanted, found));
-}
-function assertMapSalt(block, allowed, method) {
-    const salt = mapSaltOf(block);
-    if (salt !== undefined && allowed.includes(salt))
-        return;
-    const wanted = allowed.map((s) => MAP_SALT_FACTORY_HINT[s] ?? s).join(" or ");
-    const found = salt ? `a Block salted "${salt}"` : "an object with no waygraph salt marker at all";
-    throw new WaygraphError("WG_MAP_WRONG_SALT", MSG_MAP_WRONG_SALT(method, block?.name ?? "?", wanted, found));
-}
-function assertMapOrigin(block, homeOrigin, expect, method) {
-    if (!homeOrigin)
-        return; // not configured - can't validate, honest no-op
-    const navUrl = mapNavUrlOf(block);
-    if (navUrl === undefined)
-        return; // click-based/dynamic nav - not statically checkable
-    let targetOrigin;
-    let wantOrigin;
-    try {
-        targetOrigin = new URL(navUrl, homeOrigin).origin;
-        wantOrigin = new URL(homeOrigin).origin;
-    }
-    catch {
-        return; // malformed URL - not this check's job to validate that
-    }
-    const isExternal = targetOrigin !== wantOrigin;
-    if (expect === "internal" && isExternal) {
-        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", MSG_MAP_WRONG_ORIGIN_INTERNAL(block.name, targetOrigin, wantOrigin));
-    }
-    if (expect === "external" && !isExternal) {
-        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", MSG_MAP_WRONG_ORIGIN_EXTERNAL(block.name, targetOrigin, wantOrigin));
-    }
-}
-/**
- * Builds the `Flow` object `MapBuilder.branch()` returns: run `before`, then dispatch on the
- * resolved tag into whichever `routes` entry matches (same page/context/mem), or return that
- * Checkpoint as-is when its route is `null`. Factored out so `withBlockVerify`/`modBlockVerify`
- * can patch `before` and rebuild the same branched shape, exactly like a plain Flow's own.
- */
-function buildBranchedFlow(before, routes) {
-    const run = (async (contextOrMem, memOrConfig, options) => {
-        if (contextOrMem instanceof MemPage) {
-            throw new WaygraphError("WG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED", MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED);
-        }
-        const context = contextOrMem;
-        const mem = memOrConfig;
-        const gotOwnPage = options?.page === undefined;
-        const page = options?.page ?? (await context.newPage());
-        const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
-        const first = (await before.run(context, mem, { ...options, page, closeOnFinish: false }));
-        const branchFlow = routes[first.result.__state];
-        if (!branchFlow) {
-            if (options?.closeOnFinish === false)
-                return { result: first.result, page: first.page };
-            if (closeOnFinish)
-                await first.page.close();
-            return first.result;
-        }
-        return branchFlow.run(context, mem, { ...options, page: first.page, closeOnFinish });
-    });
-    return {
-        resetSession: before.resetSession,
-        config: before.config,
-        ...(before.expectedFailureReason !== undefined ? { expectedFailureReason: before.expectedFailureReason } : {}),
-        ...(before.demoPace !== undefined ? { demoPace: before.demoPace } : {}),
-        ...(before.highlightStyle !== undefined ? { highlightStyle: before.highlightStyle } : {}),
-        ...(before.memStub !== undefined ? { memStub: before.memStub } : {}),
-        // Read by branchRoutes()/branchInfo() (branch-regression.ts) - real, ORDINARY (enumerable)
-        // properties, not hidden ones, specifically so a `{ ...flow, ... }` spread (withSettings) carries them
-        // through instead of silently dropping them -
-        // the same class of bug branch()'s missing copyWaygraphRuntime call already was.
-        __wgBranch: { before, routes },
-        // Static introspection (`waygraph graph`/list): the fixed prefix, plus every branch's own
-        // Blocks prefixed by the tag that leads to them - can't know at analysis time which one a real
-        // run takes, so this shows all of them rather than none.
-        blocks: () => [
-            ...before.blocks(),
-            ...Object.entries(routes).flatMap(([tag, f]) => f ? f.blocks().map((b) => ({ ...b, name: `${tag} -> ${b.name}` })) : []),
-        ],
-        run,
-        withBlockVerify(block, verify) {
-            return buildBranchedFlow(before.withBlockVerify(block, verify), routes);
-        },
-        modBlockVerify(block, nameOrIndex, newCheck) {
-            return buildBranchedFlow(before.modBlockVerify(block, nameOrIndex, newCheck), routes);
-        },
-    };
-}
+import { MSG_MAP_BRANCH_NO_PRIOR_STEP, MSG_MAP_EMPTY, MSG_MAP_FF_ALREADY_OPEN, MSG_MAP_FF_EMPTY, MSG_MAP_FF_NOT_CLOSED, MSG_MAP_FF_NOT_OPEN, MSG_MAP_METHOD_GOT_ASSERT, WaygraphError, } from "../errors.js";
+import { buildBranchedFlow } from "./map-branch.js";
+import { assertMapKind, assertMapOrigin, assertMapSalt, mapKindOf, paced, resetBefore } from "./map-steps.js";
 /**
  * The flow builder behind `engine.map()` - see `map()`'s own doc
  * comment for why this exists. Each step method is scoped to exactly the
@@ -220,7 +79,9 @@ export class MapBuilder {
         if (ff.buffer.length === 0) {
             throw new WaygraphError("WG_MAP_FF_EMPTY", MSG_MAP_FF_EMPTY(ff.name));
         }
-        const composed = fastForwardComposeBlock(ff.name, ff.buffer);
+        const composed = fastForwardComposeBlock(ff.name, 
+        // The window's steps were typechecked as they were added; the one-step overload takes them as one Block.
+        ff.buffer);
         return new MapBuilder(this.build, this.settings, [...this.steps, composed], this.homeOrigin, null);
     }
     /**

package/dist/engine/flow/map-steps.d.ts

@@ -0,0 +1,30 @@
+import { type SomeBlock, type SomeDefinedBlock } from "../block/block.js";
+import type { DemoPace } from "../stub/pace.js";
+/** The same Block, but it clears cookies and storage before it acts. Keeps the runtime markers. */
+export declare function resetBefore(block: SomeBlock): SomeBlock;
+/** Applies a step's `pace` option, keeping the Block's runtime markers. */
+export declare function paced(block: object, opts: MapStepOpts | undefined): SomeDefinedBlock;
+export declare function mapKindOf(block: unknown): string | undefined;
+export declare function mapSaltOf(block: unknown): string | undefined;
+export declare function mapNavUrlOf(block: unknown): string | undefined;
+export declare function assertMapKind(block: SomeBlock, allowed: readonly string[], method: string): void;
+export declare function assertMapSalt(block: SomeBlock, allowed: readonly string[], method: string): void;
+export declare function assertMapOrigin(block: SomeBlock, homeOrigin: string | undefined, expect: "internal" | "external", method: string): void;
+export declare const MAP_KIND_FACTORY_HINT: Record<string, string>;
+export declare const MAP_SALT_FACTORY_HINT: Record<string, string>;
+/** Per-step options for the map builder: `ff` fast-forwards the step, `pace` sets its demo pace. */
+export interface MapStepOpts {
+    /**
+     * Fast-forward just this step, inline - no `.ffStart()/.ffEnd()` bracket needed. Consecutive
+     * `{ ff: true }` steps merge into ONE fast-forward block, same result as the explicit bracket
+     * form; a step without the flag closes an auto-opened window first.
+     * @example map().gotoPage(NavLoginBlock, { ff: true }).method(FillUsernameBlock, { ff: true })
+     */
+    ff?: boolean;
+    /**
+     * Demo pace for just this step (`"blitz"` skips the typing animation and the pause after the action; `"fast"`, `"slow"`,
+     * or a number scale the narration gates).
+     * @example map().method(SetBearerTokenBlock, { pace: "blitz" })
+     */
+    pace?: DemoPace;
+}

package/dist/engine/flow/map-steps.js

@@ -0,0 +1,87 @@
+import { copyWaygraphRuntime } from "../block/block.js";
+import { MSG_MAP_WRONG_KIND, MSG_MAP_WRONG_ORIGIN_EXTERNAL, MSG_MAP_WRONG_ORIGIN_INTERNAL, MSG_MAP_WRONG_SALT, WaygraphError } from "../errors.js";
+import { clearSessionState } from "./flow.js";
+/** The same Block, but it clears cookies and storage before it acts. Keeps the runtime markers. */
+export function resetBefore(block) {
+    const act = block.instruction.act.bind(block.instruction);
+    const next = {
+        ...block,
+        instruction: {
+            ...block.instruction,
+            async act(page, input, mem) {
+                await clearSessionState(page.context(), page);
+                return act(page, input, mem);
+            },
+        },
+    };
+    copyWaygraphRuntime(block, next);
+    Object.defineProperty(next, "__waygraphResetBefore", { value: true, enumerable: false, configurable: true });
+    return next;
+}
+/** Applies a step's `pace` option, keeping the Block's runtime markers. */
+export function paced(block, opts) {
+    if (opts?.pace === undefined)
+        return block;
+    const next = { ...block, demoPace: opts.pace };
+    copyWaygraphRuntime(block, next);
+    return next;
+}
+export function mapKindOf(block) {
+    return block?.__waygraphKind;
+}
+export function mapSaltOf(block) {
+    return block?.__waygraphSalt;
+}
+export function mapNavUrlOf(block) {
+    const url = block?.__waygraphNavUrl;
+    return typeof url === "string" ? url : undefined;
+}
+export function assertMapKind(block, allowed, method) {
+    const kind = mapKindOf(block);
+    if (kind !== undefined && allowed.includes(kind))
+        return;
+    const wanted = allowed.map((k) => MAP_KIND_FACTORY_HINT[k] ?? k).join(" or ");
+    const found = kind ? `a Block of kind "${kind}"` : "an object with no waygraph kind marker at all";
+    throw new WaygraphError("WG_MAP_WRONG_KIND", MSG_MAP_WRONG_KIND(method, block?.name ?? "?", wanted, found));
+}
+export function assertMapSalt(block, allowed, method) {
+    const salt = mapSaltOf(block);
+    if (salt !== undefined && allowed.includes(salt))
+        return;
+    const wanted = allowed.map((s) => MAP_SALT_FACTORY_HINT[s] ?? s).join(" or ");
+    const found = salt ? `a Block salted "${salt}"` : "an object with no waygraph salt marker at all";
+    throw new WaygraphError("WG_MAP_WRONG_SALT", MSG_MAP_WRONG_SALT(method, block?.name ?? "?", wanted, found));
+}
+export function assertMapOrigin(block, homeOrigin, expect, method) {
+    if (!homeOrigin)
+        return; // not configured - can't validate, honest no-op
+    const navUrl = mapNavUrlOf(block);
+    if (navUrl === undefined)
+        return; // click-based/dynamic nav - not statically checkable
+    let targetOrigin;
+    let wantOrigin;
+    try {
+        targetOrigin = new URL(navUrl, homeOrigin).origin;
+        wantOrigin = new URL(homeOrigin).origin;
+    }
+    catch {
+        return; // malformed URL - not this check's job to validate that
+    }
+    const isExternal = targetOrigin !== wantOrigin;
+    if (expect === "internal" && isExternal) {
+        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", MSG_MAP_WRONG_ORIGIN_INTERNAL(block.name, targetOrigin, wantOrigin));
+    }
+    if (expect === "external" && !isExternal) {
+        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", MSG_MAP_WRONG_ORIGIN_EXTERNAL(block.name, targetOrigin, wantOrigin));
+    }
+}
+export const MAP_KIND_FACTORY_HINT = {
+    nav: "defineNavBlock/defineMemNavBlock",
+    page: "definePageBlock",
+    assert: "defineAssertBlock",
+};
+export const MAP_SALT_FACTORY_HINT = {
+    method: "defineMethodBlock",
+    effect: "defineEffectBlock",
+    api: "defineApiBlock",
+};

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

@@ -2,7 +2,7 @@ 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 { BrowserContext, Page } from "@playwright/test";
 import type { SomeBlock } from "../block/block.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
@@ -125,21 +125,3 @@ export interface RunGraphOptions {
  * }
  */
 export declare function spawnTab<TOut extends Checkpoint<string>>(entry: Block<Checkpoint<"__start__">, TOut>, page: Page, mem: MemPage, maxSteps?: number): Promise<TOut>;
-/**
- * Wraps one `act()` interaction with a caption and highlight, for a Block
- * author who wants to explicitly narrate a specific step rather than rely
- * on the generic per-fill/per-click narration `waygraph chain
- * WAYGRAPH_STEP=1` already does automatically -
- * `await narrate(submitButton, "confirms the order", () => submitButton.click())`
- * reads at the call site instead of being inferred.
- *
- * A true no-op everywhere except inside a `WAYGRAPH_STEP=1` run: it checks
- * for a `window.__wgPositionRing` hook the step-mode overlay installs on
- * the page before doing anything, so a headless/CI/automated run (nobody
- * watching, per-character delays and highlight pauses would just be wasted
- * time) pays zero extra cost - not even the boundingBox() lookup runs. The
- * `action` itself always runs regardless; only the narration is
- * conditional.
- * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
- */
-export declare function narrate<T>(locator: Locator, caption: string, action: () => Promise<T>): Promise<T>;

package/dist/engine/run/run.js

@@ -2,7 +2,6 @@ import { WaygraphError, MSG_PREFLIGHT_MISSING_KEY, MSG_RUNGRAPH_MAX_STEPS, MSG_R
 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
@@ -144,90 +143,3 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
 export async function spawnTab(entry, page, mem, maxSteps = 5000) {
     return runGraph(entry, undefined, page.context(), mem, maxSteps);
 }
-/**
- * Wraps one `act()` interaction with a caption and highlight, for a Block
- * author who wants to explicitly narrate a specific step rather than rely
- * on the generic per-fill/per-click narration `waygraph chain
- * WAYGRAPH_STEP=1` already does automatically -
- * `await narrate(submitButton, "confirms the order", () => submitButton.click())`
- * reads at the call site instead of being inferred.
- *
- * A true no-op everywhere except inside a `WAYGRAPH_STEP=1` run: it checks
- * for a `window.__wgPositionRing` hook the step-mode overlay installs on
- * the page before doing anything, so a headless/CI/automated run (nobody
- * watching, per-character delays and highlight pauses would just be wasted
- * time) pays zero extra cost - not even the boundingBox() lookup runs. The
- * `action` itself always runs regardless; only the narration is
- * conditional.
- * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
- */
-export async function narrate(locator, caption, action) {
-    const page = locator.page();
-    const active = await page
-        .evaluate(() => typeof globalThis.__wgPositionRing === "function")
-        .catch(() => false);
-    if (!active)
-        return action();
-    let owning = false;
-    try {
-        const box = await locator.boundingBox();
-        if (box) {
-            await page
-                .evaluate(({ box, caption }) => {
-                const w = globalThis;
-                if (w.__wgPositionRing)
-                    w.__wgPositionRing(box, caption, "planned");
-                // The CLI's own automatic per-fill/per-click narration checks
-                // this before showing (and overwriting) its own guess - an
-                // explicitly authored caption should win, not get immediately
-                // replaced a moment later by the generic one.
-                w.__wgLastNarrate = Date.now();
-                // Also claim the ring itself: the auto-highlight click/fill
-                // patches each hide the ring right after THEIR own step
-                // finishes, which - if action() below does more than one thing
-                // (e.g. a click then a wait for a toast) - would wipe this
-                // caption after just the first sub-step instead of the whole
-                // narrated action. Their hideRing() calls no-op while this is
-                // true; narrate() below is the one that actually clears it.
-                w.__wgNarrateOwnsRing = true;
-            }, { box, caption })
-                .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
-            // before a human can read the caption at all. Give it the same
-            // "pop for a few seconds" dwell as the CLI's own auto-highlight
-            // clicks before the real action runs.
-            await new Promise((resolve) => setTimeout(resolve, 650));
-            // Re-stamp __wgLastNarrate right before handing off to action() - the
-            // CLI's auto-highlight patches only treat a narrate() as "just
-            // handled" within a short window (500ms), which the dwell above
-            // already burned through. Without this, action()'s own click/fill
-            // (same patched Locator prototype) would stomp this caption with its
-            // own generic one a moment after it finally became visible.
-            await page
-                .evaluate(() => {
-                globalThis.__wgLastNarrate = Date.now();
-            })
-                .catch(ignorePageGone);
-        }
-    }
-    catch {
-        // best-effort - the real action below still runs either way
-    }
-    try {
-        return await action();
-    }
-    finally {
-        if (owning) {
-            await page
-                .evaluate(() => {
-                const w = globalThis;
-                w.__wgNarrateOwnsRing = false;
-                if (w.__wgHideRing)
-                    w.__wgHideRing();
-            })
-                .catch(ignorePageGone);
-        }
-    }
-}

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

@@ -1,4 +1,3 @@
-import type { Checkpoint } from "../checkpoint/checkpoint.js";
 /** Shared dwell fields on stubs, fixtures, and yap slides. */
 export type FixtureDurationFields = {
     /**
@@ -83,8 +82,8 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
 /** 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.
+ * One yap/slide in a multi-step demo caption sequence, painted with {@link StubCtx.slides}.
+ * The demo pauses on each (Next, or auto-next) before moving on.
  */
 export interface WaygraphSlide extends FixtureDurationFields {
     /** Primary caption (required). */
@@ -119,7 +118,6 @@ export type HighlightStyleDefaults = {
     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. */

package/dist/engine/stub/ring.js

@@ -1,3 +1,4 @@
+// A ring: one highlighted element with its caption, and its tone, size and weight; slides between steps.
 /** Map author aliases (`error` -> danger) to a canonical tone. */
 export function normalizeHighlightTone(raw) {
     if (typeof raw !== "string")

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

@@ -2,7 +2,7 @@ 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";
+import type { HighlightStubPhase, ResolvedHighlight, WaygraphHighlightStub, WaygraphSlide } 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. */
@@ -87,10 +87,8 @@ export type StubPhaseFixtures = {
  * 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" },
- *   });
+ *   ctx.ring("email", { selector: "#email", label: "Email" });
+ *   ctx.ring("submit", { selector: "#login-button", label: "Sign in" });
  * })
  * // Sequential plan: bump todoIndex in a later phase / a later Block's stubBefore
  * .stubAfter((ctx) => {
@@ -109,9 +107,7 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     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. */
+    /** Paints one named ring this phase; the same id again replaces it. */
     ring(id: string, stub: WaygraphHighlightStub): void;
     /**
      * Floating checklist: `ctx.todos("login", ["Enter email", "Enter password"], { title: "Sign in", index: 0 })`.
@@ -174,6 +170,15 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     caption(text: string): void;
     /** Clears the caption (fades it out). */
     hideCaption(): void;
+    /**
+     * Multi-step "yap" captions with Next between each, for explaining a longer process. In `stubBefore` they play
+     * before the step runs, in `stubAfter` after it lands; a slide with a `selector` rings it while it is up.
+     * @example ctx.slides([
+     *   { caption: "Checkout is three screens", tag: "YAP" },
+     *   { caption: "Overview confirms totals", selector: ".summary_info", duration: true },
+     * ]);
+     */
+    slides(slides: readonly WaygraphSlide[]): void;
     /** Shorthand for `bannerUi({ hidden: true })`. */
     hideBanner(): void;
     /**
@@ -226,6 +231,8 @@ export type StubPhaseResult = {
     bannerUi?: BannerUiOpts;
     caption?: string;
     networkTabVisible?: boolean;
+    /** Slides to play in this phase ({@link StubCtx.slides}); empty when the stub set none. */
+    slides: WaygraphSlide[];
     todoPos?: "left" | "right";
     /** When true, keep other docks (multi-todo). Default false = replace. */
     todoParallel?: boolean;
@@ -260,6 +267,7 @@ export type StubBagState = {
     bannerUi?: BannerUiOpts | undefined;
     caption?: string | undefined;
     networkTabVisible?: boolean | undefined;
+    slides?: readonly WaygraphSlide[] | undefined;
     todoPos?: "left" | "right" | undefined;
     /** Author patched todo-dock UX this phase. */
     todoDockUi?: TodoDockUiOpts | undefined;

package/dist/engine/trait/trait.js

@@ -1,5 +1,5 @@
 // URLPattern is only a Node global from v23.8+ (and even then, Node's own, not a browser's) -
-// CI's Node 20/22 matrix has no global at all. Side-effect import only: the polyfill package sets
+// Node 22 (the oldest supported) has no global at all. Side-effect import only: the polyfill package sets
 // globalThis.URLPattern itself, but only when one doesn't already exist - so below Node 23.8 this
 // becomes THE global, and from 23.8 up it's a no-op and the native one stays. Playwright's own
 // waitForURL(pattern) checks `pattern instanceof globalThis.URLPattern` internally, so the instance

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import "./runtime/full-launch.js";
 import "./runtime/run-log.js";
 export type { Checkpoint, Start } from "./engine/checkpoint/checkpoint.js";
-export type { Instruction, Block, DefinedBlock, SomeBlock, SomeDefinedBlock, WaygraphInstanceOption } from "./engine/block/block.js";
+export type { Instruction, Block, DefinedBlock, SomeBlock, SomeDefinedBlock } from "./engine/block/block.js";
+export type { WaygraphInstanceOption } from "./engine/block/action-page.js";
 export { connect } from "./engine/run/connect.js";
 export { checkpoint } from "./engine/checkpoint/checkpoint.js";
 export { MemKey, MemPage, key, keyGroup } from "./engine/mem/mem.js";
@@ -9,10 +10,12 @@ export { registerMemStub, seedMemStub, getMemStub } from "./engine/mem/mem-stub.
 export { css, byText, byRole } from "./engine/trait/selector.js";
 export { WaygraphError, WAYGRAPH_ERRORS } from "./engine/errors.js";
 export type { WaygraphErrorCode } from "./engine/errors.js";
-export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./engine/trait/trait.js";
-export { runGraph, spawnTab, narrate, preflight, defineLayout } from "./engine/run/run.js";
+export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText } from "./engine/trait/trait.js";
+export { runGraph, spawnTab, preflight, defineLayout } from "./engine/run/run.js";
 export { Engine, map } from "./engine/engine.js";
-export { branch, withVerify, modVerify, modVerifyAll, defineBlock, withDialog } from "./engine/block/block.js";
+export { branch } from "./engine/block/branch.js";
+export { withVerify, modVerify, modVerifyAll, defineBlock } from "./engine/block/block.js";
+export { withDialog } from "./engine/block/dialog.js";
 export { defineNavBlock, defineNavClickBlock, defineMemNavBlock } from "./engine/block/kinds/nav.js";
 export { defineMethodBlock, defineAssertBlock } from "./engine/block/kinds/method.js";
 export { definePageBlock } from "./engine/block/kinds/page.js";
@@ -24,8 +27,9 @@ export { MapBuilder } from "./engine/flow/map-builder.js";
 export { branchRoutes, collectBranchFlows, runBranchRegression } from "./engine/flow/branch-regression.js";
 export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from "./engine/flow/branch-regression.js";
 export type { ApiBlockOptions, ApiCallResult } from "./engine/block/kinds/api.js";
-export type { MapStepOpts, MapFlowOpts } from "./engine/flow/map-builder.js";
-export { resolveHighlightSlots, resolveSlides, runStubPhase, hasAuthoredStubAfter, hasAuthoredStubOnError } from "./demo/narration/narration.js";
+export type { MapStepOpts } from "./engine/flow/map-steps.js";
+export type { MapFlowOpts } from "./engine/flow/map-builder.js";
+export { resolveHighlightSlots, runStubPhase, hasAuthoredStubAfter, hasAuthoredStubOnError } from "./demo/narration/narration.js";
 export { resolveFixtureDwellMs, normalizeDemoPace, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT } from "./demo/narration/demo-pace.js";
 export { formatHighlightCaption, applyHighlightStyleDefaults, toneIconPrefix } from "./demo/narration/style.js";
 export { normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight } from "./engine/stub/ring.js";
@@ -46,21 +50,21 @@ export type { MethodBlock, AssertBlock, AssertBlockOptions } from "./engine/bloc
 export type { PageBlock, PageBlockOptions, PageMethodEntry } from "./engine/block/kinds/page.js";
 export type { EffectBlock } from "./engine/block/kinds/effect.js";
 export type { MapBuilderOptions } from "./engine/flow/map-builder.js";
-export type { ActionPage } from "./engine/block/block.js";
+export type { ActionPage } from "./engine/block/action-page.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./analysis/graph.js";
 export { buildManifest } from "./manifest/manifest.js";
 export { onRunEvent } from "./engine/run/events.js";
 export type { RunEvent } from "./engine/run/events.js";
 export type { Manifest, ManifestBlock, ManifestFlow } from "./manifest/manifest.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./analysis/graph.js";
-export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./manifest/select.js";
+export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp } from "./manifest/select.js";
 export type { BlocksSelect, BlocksSelectKind } from "./manifest/select.js";
 export { EdgeLeaseCoordinator } from "./live/traverse/lease.js";
 export { runTraverse } from "./live/traverse/traverse.js";
-export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult, } from "./live/traverse/traverse.js";
-export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./live/traverse/coverage.js";
+export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult } from "./live/traverse/traverse.js";
+export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport } from "./live/traverse/coverage.js";
 export type { TraverseCoverageReport } from "./live/traverse/coverage.js";
-export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./demo/overlay/beacon.js";
+export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady } from "./demo/overlay/beacon.js";
 export type { WgModalKind, WgBeaconRow } from "./demo/overlay/beacon.js";
 export { AutoSession } from "./live/auto-session/auto-session.js";
 export { stubFilePath } from "./live/auto-session/helpers.js";
@@ -75,7 +79,6 @@ export { resolveExtension, KNOWN_EXTENSIONS } from "./runtime/extensions.js";
 export type { ExtensionSpec } from "./engine/config.js";
 export type { WebServerConfig } from "./runtime/webserver.js";
 export type { MapStart } from "./engine/engine.js";
-export type { WaygraphSlidesOrFn } from "./engine/stub/ring.js";
 export type { ConnectLayout } from "./engine/run/connect.js";
 export type { EffectExtras } from "./engine/block/kinds/effect.js";
 export type { BlockBase, RoutedBlockBase } from "./engine/checkpoint/route.js";