waygraph 0.16.1 → 0.16.2

package/dist/demo/stepper/slides.js

@@ -1,10 +1,10 @@
 import { demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeDemoPace, resolveFixtureDwellMs } from "../narration/demo-pace.js";
-import { formatHighlightCaption } from "../narration/style.js";
 import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../../engine/stub/ring.js";
 import { installOverlay } from "../overlay/overlay.js";
 import { applyHighlightZoom, ensureSelectorInView, hideRing, showRing } from "../overlay/rings.js";
-import { demoPaceKind } from "./demo-log.js";
+import { demoLog, demoPaceKind } from "./demo-log.js";
 import { envFlag, envNumber, envString } from "../../engine/env.js";
+import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narration/style.js";
 /**
  * Multi-step yap captions - not block lifecycle. Each slide waits for Next
  * (or auto-next), optional ring via slide.selector.
@@ -231,3 +231,19 @@ export async function presentSlides(page, slides, opts) {
     }
     await hideRing(page);
 }
+/** Plays a stub phase's `ctx.slides(...)` for the step on screen, in the flow's highlight style. */
+export async function showSlides(ctx, view, slides) {
+    if (slides.length === 0)
+        return;
+    if (!envFlag("WAYGRAPH_JSON"))
+        demoLog(`  slides ${slides.length}: ` + slides.map((s) => JSON.stringify(s.caption)).join(" | "));
+    await presentSlides(ctx.page, slides.map((s) => applyHighlightStyleDefaults(s, view.step.highlightStyle)), {
+        title: ctx.title,
+        blockName: view.step.block.name,
+        fast: ctx.pacing.gatesFast,
+        pace: ctx.pacing.demoPace,
+        episodeNumber: view.step.episodeNumber,
+        episodeTitle: view.step.episodeTitle,
+        autoplayMs: ctx.gate.autoplayMs,
+    });
+}

package/dist/demo/stepper/teardown.js

@@ -154,7 +154,6 @@ export async function teardownOverlay(page) {
             window.removeEventListener("scroll", window.__wgRingTrack, true);
             window.__wgRingTrack = null;
         }
-        window.__wgNarrateOwnsRing = false;
         for (const id of [
             "wg-panel",
             "wg-ring",

package/dist/demo/verbose-log.js

@@ -1,7 +1,7 @@
 import { envFlag } from "../engine/env.js";
 /**
  * One log format for the live overlay surfaces (auto / browser / pilot): `[HH:MM:SS.mmm] waygraph <surface>: ...`, the
- * same shape as the demo runner's `step-mode/demo-log.ts`. Silenced by WAYGRAPH_JSON=1.
+ * same shape as the demo stepper's `stepper/demo-log.ts`. Silenced by WAYGRAPH_JSON=1.
  */
 function ts() {
     const d = new Date();

package/dist/engine/block/block.d.ts

@@ -2,7 +2,6 @@ import type { Page } from "@playwright/test";
 import type { Checkpoint } from "../checkpoint/checkpoint.js";
 import type { MemKey } from "../mem/mem.js";
 import { MemPage } from "../mem/mem.js";
-import type { WaygraphSlidesOrFn } from "../stub/ring.js";
 import type { StubLifecycleFn } from "../stub/stub.js";
 import type { Trait } from "../trait/trait.js";
 import type { ActionPage, WaygraphInstanceOption } from "./action-page.js";
@@ -56,16 +55,6 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
     stubAfter?: StubLifecycleFn<Out>;
     /** When the step fails, before the failure panel; written by `Block.stubOnError((ctx) => ...)`. */
     stubOnError?: StubLifecycleFn<Out>;
-    /**
-     * Multi-step demo captions ("yap" slides) with Next between each -
-     * not block lifecycle. Explains a long process; optional `selector` rings
-     * while that slide is up. Flow fixtures may override via `slides`.
-     * @example slides: [
-     *   { caption: "Checkout is three screens", tag: "YAP" },
-     *   { caption: "Overview confirms totals", selector: ".summary_info" },
-     * ]
-     */
-    slides?: WaygraphSlidesOrFn<Out>;
 }
 /**
  * A Block wraps one instruction. Its Observed type is an internal detail, erased here.
@@ -90,7 +79,7 @@ export interface Block<In extends Checkpoint<string>, Out extends Checkpoint<str
      * A human-readable sentence describing what this Block actually tests or
      * does - "the outsider case: a user outside a request's audience is
      * denied its detail page," not a restatement of the code. Purely
-     * additive, optional narration for a human watching a run (step-mode
+     * additive, optional narration for a human watching a run (demo
      * tooling shows it before the Block runs) - never read by
      * `runGraph`/`connect`/anything that decides behavior. A Block with none
      * just shows its `name` instead.

package/dist/engine/block/kinds/method.d.ts

@@ -39,8 +39,6 @@ export interface AssertBlockOptions<Out extends Checkpoint<string> = Checkpoint<
     verify: Trait[] | ((out: Out) => Trait[]);
     /** Mem keys this assertion's `verify` reads (e.g. a mem-aware Trait) - checked by preflight before the flow runs. */
     requires?: readonly MemKey<unknown>[];
-    /** Multi-step yap slides (demo only) - same field `Instruction.slides` exposes elsewhere. */
-    slides?: import("../../stub/ring.js").WaygraphSlidesOrFn<Out>;
 }
 /**
  * Sugar for a self-loop-only "pure assertion" Block: no hand-written

package/dist/engine/block/kinds/method.js

@@ -42,7 +42,6 @@ export function defineAssertBlock(options) {
                 }
             },
             verify: options.verify,
-            ...(options.slides ? { slides: options.slides } : {}),
         },
     });
     Object.defineProperty(built, "__waygraphKind", {

package/dist/engine/block/kinds/nav.js

@@ -28,7 +28,7 @@ export function defineNavBlock(options) {
                     await page.goto(url);
                 }
                 else {
-                    // Always Locator.click() so step-mode's demo cursor/pulse patch
+                    // Always Locator.click() so the demo stepper's cursor/pulse patch
                     // (instrumentInteractionHighlighting) sees NavBlock click-nav -
                     // never page.click() / goto teleport.
                     const selector = typeof options.click === "function" ? options.click(mem) : options.click;

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/index.d.ts

@@ -11,7 +11,7 @@ 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 { runGraph, spawnTab, preflight, defineLayout } from "./engine/run/run.js";
 export { Engine, map } from "./engine/engine.js";
 export { branch } from "./engine/block/branch.js";
 export { withVerify, modVerify, modVerifyAll, defineBlock } from "./engine/block/block.js";
@@ -29,7 +29,7 @@ export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from ".
 export type { ApiBlockOptions, ApiCallResult } from "./engine/block/kinds/api.js";
 export type { MapStepOpts } from "./engine/flow/map-steps.js";
 export type { MapFlowOpts } from "./engine/flow/map-builder.js";
-export { resolveHighlightSlots, resolveSlides, runStubPhase, hasAuthoredStubAfter, hasAuthoredStubOnError } from "./demo/narration/narration.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";
@@ -79,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";

package/dist/index.js

@@ -9,7 +9,7 @@ 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 { 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 { runGraph, spawnTab, preflight, defineLayout } from "./engine/run/run.js";
 export { Engine, map } from "./engine/engine.js";
 export { branch } from "./engine/block/branch.js";
 export { withVerify, modVerify, modVerifyAll, defineBlock } from "./engine/block/block.js";
@@ -23,7 +23,7 @@ export { locate } from "./engine/locate.js";
 export { composeBlock, fastForwardComposeBlock, isFastForwardBlock } from "./engine/block/compose.js";
 export { MapBuilder } from "./engine/flow/map-builder.js";
 export { branchRoutes, collectBranchFlows, runBranchRegression } from "./engine/flow/branch-regression.js";
-export { resolveHighlightSlots, resolveSlides, runStubPhase, hasAuthoredStubAfter, hasAuthoredStubOnError } from "./demo/narration/narration.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";

package/dist/runner/plan/find.js

@@ -32,11 +32,11 @@ export async function findBlock(projectDir, ref) {
     if (byRuntimeName.length === 1)
         return byRuntimeName[0];
     if (byRuntimeName.length > 1) {
-        throw new Error("waygraph chain: \"" + ref + "\" matches " + byRuntimeName.length + " Blocks by name - " +
+        throw new Error("waygraph run --blocks: \"" + ref + "\" matches " + byRuntimeName.length + " Blocks by name - " +
             byRuntimeName.map((b) => b.exportName + " (" + b.file + ")").join(", ") +
             ". Use the export name to disambiguate.");
     }
-    throw new Error("waygraph chain: no Block named \"" + ref + "\" found under " + projectDir);
+    throw new Error("waygraph run --blocks: no Block named \"" + ref + "\" found under " + projectDir);
 }
 /**
  * Finds an already-defined Flow by its export name (e.g. loginFlow) among

package/dist/runner/plan/plan.js

@@ -24,7 +24,7 @@ async function findBareFlow(projectDir, spec) {
 function parseSegments(spec) {
     const segments = parseChainSpec(spec);
     if (segments.length === 0)
-        throw new Error("waygraph chain: empty spec - give at least one block name");
+        throw new Error("waygraph run --blocks: empty spec - give at least one block name");
     return segments;
 }
 async function resolveSegment(projectDir, seg, mem, options) {

package/dist/runner/plan/seed-mem.js

@@ -4,7 +4,7 @@ const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
 function seedMemFromRequires(mem, requires, json, label, stubActive) {
     if (requires.length === 0) {
         if (json !== undefined) {
-            throw new Error("waygraph chain: \"" + label + "\" takes no input (empty requires) but got a payload: " + json);
+            throw new Error("waygraph run --blocks: \"" + label + "\" takes no input (empty requires) but got a payload: " + json);
         }
         return;
     }
@@ -22,7 +22,7 @@ function seedMemFromRequires(mem, requires, json, label, stubActive) {
             haveParsed = true;
         }
         catch (err) {
-            throw new Error("waygraph chain: \"" + label + "\" payload is not valid JSON - " + String(err));
+            throw new Error("waygraph run --blocks: \"" + label + "\" payload is not valid JSON - " + String(err));
         }
     }
     if (!haveParsed) {
@@ -30,7 +30,7 @@ function seedMemFromRequires(mem, requires, json, label, stubActive) {
         // this flow; when it is, fall through with an empty object so the
         // per-key loop below gets a chance to fill each one from the registry.
         if (!stubActive) {
-            throw new Error("waygraph chain: \"" + label + "\" requires " + requires.map((k) => k.name).join(", ") +
+            throw new Error("waygraph run --blocks: \"" + label + "\" requires " + requires.map((k) => k.name).join(", ") +
                 " - give a JSON payload (inline blockName({...}) or --data '{...}'), or enable --mem-stub" +
                 " with registerMemStub for these keys");
         }
@@ -54,7 +54,7 @@ function seedMemFromRequires(mem, requires, json, label, stubActive) {
         return;
     }
     if (!isRecord(parsed)) {
-        throw new Error("waygraph chain: \"" + label + "\" requires " + requires.length + " keys (" +
+        throw new Error("waygraph run --blocks: \"" + label + "\" requires " + requires.length + " keys (" +
             requires.map((k) => k.name).join(", ") + ") - payload must be an object keyed by each key's name");
     }
     const payload = parsed;
@@ -72,7 +72,7 @@ function seedMemFromRequires(mem, requires, json, label, stubActive) {
         stillMissing.push(k);
     }
     if (stillMissing.length > 0) {
-        throw new Error("waygraph chain: \"" + label + "\" payload is missing required key(s): " +
+        throw new Error("waygraph run --blocks: \"" + label + "\" payload is missing required key(s): " +
             stillMissing.map((k) => "\"" + k.name + "\"").join(", "));
     }
 }

package/dist/runner/plan/spec.js

@@ -8,7 +8,7 @@ export function parseChainSpec(spec) {
         .map((s) => {
         const m = /^([A-Za-z_$][\w-]*)\s*(?:\(([\s\S]*)\))?$/.exec(s);
         if (!m) {
-            throw new Error("waygraph chain: could not parse segment \"" + s + "\" - expected \"blockName\" or \"blockName({...json...})\"");
+            throw new Error("waygraph run --blocks: could not parse segment \"" + s + "\" - expected \"blockName\" or \"blockName({...json...})\"");
         }
         const ref = m[1];
         const json = m[2] ? m[2].trim() : undefined;

package/examples/saucedemo/src/blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.ts

@@ -1,4 +1,4 @@
-import { defineMethodBlock, Trait, narrate } from "waygraph";
+import { defineMethodBlock, Trait } from "waygraph";
 import {
   CheckoutOverviewPage,
   OrderComplete,
@@ -21,9 +21,7 @@ export const FinishOrderBlock = defineMethodBlock({
   instruction: {
     async act(page) {
       const finishButton = page.locator(CheckoutOverviewSel.finishBtn);
-      await narrate(finishButton, "Placing the order", () =>
-        finishButton.click(),
-      );
+      await finishButton.click();
     },
     verify: [
       Trait.text(
@@ -31,35 +29,5 @@ export const FinishOrderBlock = defineMethodBlock({
         "Thank you for your order!",
       ),
     ],
-    // Shown AFTER act (order already placed) - selectors must match the
-    // completion page, not #finish on the overview.
-    slides: [
-      {
-        caption: "Checkout is a short pipeline",
-        detail: "Cart -> info -> overview -> done. You just placed the order.",
-        tag: "YAP",
-        tone: "info",
-        duration: true,
-      },
-      {
-        caption: "Completion page is the durable proof",
-        detail:
-          "tone: success - the thank-you header is what verify asserts on.",
-        tag: "YAP",
-        tone: "success",
-        selector: CheckoutOverviewSel.completeHeader,
-        duration: 2500,
-        fastMode: 700,
-      },
-      {
-        caption: "Episode continues after this yap",
-        detail: "Next step rings the same banner, then you move on.",
-        tag: "YAP",
-        tone: "planned",
-        selector: CheckoutOverviewSel.completeHeader,
-        duration: true,
-        fastMode: 500,
-      },
-    ],
   },
 });

package/examples/saucedemo/src/flows/checkout-then-browse-again.flow.ts

@@ -12,6 +12,7 @@ import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/met
 import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
+import { orderPlacedYap, placingOrder } from "../stubs/finish-order.js";
 import { NavBackToProductsBlock } from "../blocks/saucedemo-web/inventory-item/nav-back-to-products.block.js";
 
 /** Full checkout, then the "Back Home" click-based Nav Block returns to the catalogue. */
@@ -35,6 +36,6 @@ export const checkoutThenBrowseAgainFlow = engine
   .method(FillLastNameBlock)
   .method(FillPostalCodeBlock)
   .method(SubmitCheckoutInfoBlock)
-  .method(FinishOrderBlock)
+  .method(FinishOrderBlock.stubBefore(placingOrder).stubAfter(orderPlacedYap))
   .gotoPage(NavBackToProductsBlock)
   .end();

package/examples/saucedemo/src/flows/checkout.flow.ts

@@ -12,6 +12,7 @@ import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/met
 import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
+import { orderPlacedYap, placingOrder } from "../stubs/finish-order.js";
 import { LoginSel } from "../blocks/saucedemo-web/methods/login.sel.js";
 
 export const checkoutFlow = engine
@@ -80,5 +81,5 @@ export const checkoutFlow = engine
     }),
   )
   .method(SubmitCheckoutInfoBlock.stubBefore((ctx) => ctx.hideCaption()))
-  .method(FinishOrderBlock)
+  .method(FinishOrderBlock.stubBefore(placingOrder).stubAfter(orderPlacedYap))
   .end();

package/examples/saucedemo/src/flows/shop.flow.ts

@@ -8,6 +8,7 @@ import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/met
 import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
+import { orderPlacedYap, placingOrder } from "../stubs/finish-order.js";
 
 /** Add the selected item, check out and place the order. Starts signed in (run it after loginFlow). */
 export const shopFlow = engine
@@ -20,5 +21,5 @@ export const shopFlow = engine
   .method(FillLastNameBlock)
   .method(FillPostalCodeBlock)
   .method(SubmitCheckoutInfoBlock)
-  .method(FinishOrderBlock)
+  .method(FinishOrderBlock.stubBefore(placingOrder).stubAfter(orderPlacedYap))
   .end();