waygraph 0.11.2 → 0.12.4

package/dist/engine.js

@@ -379,8 +379,8 @@ export function withExpectedFailure(flow, reason) {
 }
 /**
  * Attaches demo highlight fixtures to a Flow - unlimited purposes on `.flow.ts`
- * (AC copy, BUG/GATE tags, detail) merged onto each block's stubBefore/stubAfter
- * slots. Non-destructive, same pattern as {@link withTitle}.
+ * (AC copy, BUG/GATE tags, detail) merged onto each block's stubBefore/stubAfter/
+ * stubOnError slots. Non-destructive, same pattern as {@link withTitle}.
  * Demo/`chain --step` reads `flow.highlightFixtures`; `run()` ignores it.
  * @example withHighlightFixtures(issueFlow, { "submit-login": { stubBefore: { email: { label: "AC-1" } } } })
  */
@@ -542,6 +542,57 @@ export function composeBlock(name, steps) {
         },
     };
 }
+/** True when `block` came from {@link fastForwardComposeBlock}. */
+export function isFastForwardBlock(block) {
+    return (block.fastForward === true &&
+        typeof block.steps === "function");
+}
+function wrapFfError(ffName, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.startsWith(`${ffName} > `)) {
+        return err instanceof Error ? err : new Error(msg);
+    }
+    const wrapped = new Error(`${ffName} > ${msg}`);
+    if (err instanceof Error && err.stack) {
+        wrapped.stack = err.stack;
+    }
+    return wrapped;
+}
+export function fastForwardComposeBlock(name, steps) {
+    if (steps.length === 0) {
+        throw new Error(`fastForwardComposeBlock: "${name}" needs at least one step`);
+    }
+    const base = composeBlock(name, steps);
+    const origAct = base.instruction.act.bind(base.instruction);
+    const ff = {
+        ...base,
+        fastForward: true,
+        instruction: {
+            ...base.instruction,
+            async act(page, input, mem) {
+                try {
+                    await origAct(page, input, mem);
+                }
+                catch (e) {
+                    throw wrapFfError(name, e);
+                }
+            },
+        },
+        withStepVerify(step, verify) {
+            const index = findBlockIndex(steps, step);
+            const patched = [...steps];
+            patched[index] = withVerify(steps[index], verify);
+            return fastForwardComposeBlock(name, patched);
+        },
+        modStepVerify(step, nameOrIndex, newCheck) {
+            const index = findBlockIndex(steps, step);
+            const patched = [...steps];
+            patched[index] = modVerify(steps[index], nameOrIndex, newCheck);
+            return fastForwardComposeBlock(name, patched);
+        },
+    };
+    return ff;
+}
 /**
  * Holds engine-level configuration shared across every flow defined from it -
  * for now, just how to launch a browser when a Flow owns its own
@@ -676,6 +727,7 @@ export function defineNavBlock(options) {
             ...(options.verify ? { verify: options.verify } : {}),
             ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
             ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
+            ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
             ...(options.highlights ? { highlights: options.highlights } : {}),
         },
     });
@@ -711,6 +763,7 @@ export function defineNavClickBlock(options) {
         ...(options.verify ? { verify: options.verify } : {}),
         ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
         ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
+        ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
         ...(options.highlights ? { highlights: options.highlights } : {}),
         ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
     });
@@ -759,6 +812,7 @@ export function definePageBlock(options) {
             ...(options.verify ? { verify: options.verify } : {}),
             ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
             ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
+            ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
             ...(options.highlights ? { highlights: options.highlights } : {}),
         },
     });

package/dist/highlights.d.ts

@@ -1,13 +1,31 @@
 /**
- * Block stubBefore / stubAfter + flow highlightFixtures + demo slides.
+ * Block stubBefore / stubAfter / stubOnError + flow highlightFixtures + demo slides.
  * Demo narration only - never affects runGraph pass/fail.
  *
- * Lifecycle (stubs) ≠ yap slides: stubs are fill/after rings tied to the block;
+ * Lifecycle (stubs) ≠ yap slides: stubs are fill/after/error rings tied to the block;
  * slides are multi-step captions with Next between them (long-process explain).
+ *
+ * All fixture shapes share optional {@link FixtureDurationFields} so demo dwell
+ * before advancing is authored the same way on stubs, flow fixtures, and slides.
  */
 import type { Block, Checkpoint } from "./types.js";
+/** Shared dwell fields on stubs, fixtures, and yap slides. */
+export type FixtureDurationFields = {
+    /**
+     * Min time this fixture stays visible before the demo advances.
+     * - `true` - defaults (2000ms normal, {@link FixtureDurationFields.fastMode} or 600ms when --fast)
+     * - `number` - override normal dwell ms
+     * - omit / false - no authored dwell (caller keeps legacy timing)
+     */
+    duration?: boolean | number;
+    /**
+     * Dwell ms when demo `--fast` / gatesFast (only when {@link duration} is set).
+     * Default 600.
+     */
+    fastMode?: number;
+};
 /** One named highlight slot on a block (selector + caption). */
-export interface WaygraphHighlightStub {
+export interface WaygraphHighlightStub extends FixtureDurationFields {
     selector: string;
     /** Primary caption line. */
     label: string;
@@ -17,14 +35,14 @@ export interface WaygraphHighlightStub {
     tag?: string;
 }
 /** Flow fixture patch: label required; selector optional (inherits from stub). */
-export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag">;
+export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag"> & FixtureDurationFields;
 export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
 export type HighlightStubPhaseOrFn<Out extends Checkpoint<string>> = HighlightStubPhase | ((out: Out) => HighlightStubPhase);
 /**
  * One yap/slide in a multi-step demo caption sequence.
  * Not block lifecycle - demo pauses (Next / auto-next) between slides.
  */
-export interface WaygraphSlide {
+export interface WaygraphSlide extends FixtureDurationFields {
     /** Primary caption (required). */
     caption: string;
     detail?: string;
@@ -32,11 +50,34 @@ export interface WaygraphSlide {
     /** Optional ring while this slide is showing. */
     selector?: string;
 }
+/** Default fixture dwell when `duration: true`. */
+export declare const FIXTURE_DURATION_MS_DEFAULT = 2000;
+/** Default fixture dwell under `--fast` when duration is enabled. */
+export declare const FIXTURE_DURATION_FAST_MS_DEFAULT = 600;
+/** @deprecated Prefer FIXTURE_DURATION_MS_DEFAULT */
+export declare const SLIDE_DURATION_MS_DEFAULT = 2000;
+/** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
+export declare const SLIDE_DURATION_FAST_MS_DEFAULT = 600;
+/**
+ * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
+ * or `null` when duration is unset (caller keeps legacy timing).
+ */
+export declare function resolveFixtureDwellMs(fixture: FixtureDurationFields, opts?: {
+    gatesFast?: boolean;
+}): number | null;
+/** @deprecated Prefer {@link resolveFixtureDwellMs} */
+export declare function resolveSlideDwellMs(slide: FixtureDurationFields, opts?: {
+    gatesFast?: boolean;
+}): number | null;
 export type WaygraphSlidesOrFn<Out extends Checkpoint<string>> = readonly WaygraphSlide[] | ((out: Out) => readonly WaygraphSlide[]);
+/** Demo stub phase names (block instruction + flow fixtures). */
+export type HighlightStubPhaseName = "stubBefore" | "stubAfter" | "stubOnError";
 /** Per-block fixture map attached to a Flow via {@link withHighlightFixtures}. */
 export type HighlightFixtureMap = Record<string, {
     stubBefore?: Record<string, WaygraphHighlightFixture>;
     stubAfter?: Record<string, WaygraphHighlightFixture>;
+    /** Fail-path rings (demo step throw) - distinct copy from success stubAfter. */
+    stubOnError?: Record<string, WaygraphHighlightFixture>;
     /** Override / supply multi-step yap slides for this block (demo only). */
     slides?: readonly WaygraphSlide[];
 }>;
@@ -49,8 +90,9 @@ export type ResolvedHighlight = WaygraphHighlightStub;
 /**
  * Resolve ordered highlight slots for a phase, merging flow fixtures over block stubs.
  * Shim: empty stubAfter + legacy `instruction.highlights` -> auto-keyed stubAfter.
+ * `stubOnError` is fail-path only (demo step catch) - never run on success.
  */
-export declare function resolveHighlightSlots(block: Block<any, any>, phase: "stubBefore" | "stubAfter", opts?: {
+export declare function resolveHighlightSlots(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
     out?: Checkpoint<string>;
     fixtures?: HighlightFixtureMap;
 }): ResolvedHighlight[];
@@ -74,3 +116,8 @@ export declare function formatHighlightCaption(h: {
  * including legacy highlights. When true, demo should not use verify-trait fallback.
  */
 export declare function hasAuthoredStubAfter(block: Block<any, any>, out?: Checkpoint<string>, fixtures?: HighlightFixtureMap): boolean;
+/**
+ * True when stubOnError resolves to at least one ring (block and/or flow fixture).
+ * Demo fail path only - success never consults this.
+ */
+export declare function hasAuthoredStubOnError(block: Block<any, any>, fixtures?: HighlightFixtureMap): boolean;

package/dist/highlights.js

@@ -1,16 +1,62 @@
 /**
- * Block stubBefore / stubAfter + flow highlightFixtures + demo slides.
+ * Block stubBefore / stubAfter / stubOnError + flow highlightFixtures + demo slides.
  * Demo narration only - never affects runGraph pass/fail.
  *
- * Lifecycle (stubs) ≠ yap slides: stubs are fill/after rings tied to the block;
+ * Lifecycle (stubs) ≠ yap slides: stubs are fill/after/error rings tied to the block;
  * slides are multi-step captions with Next between them (long-process explain).
+ *
+ * All fixture shapes share optional {@link FixtureDurationFields} so demo dwell
+ * before advancing is authored the same way on stubs, flow fixtures, and slides.
+ */
+/** Default fixture dwell when `duration: true`. */
+export const FIXTURE_DURATION_MS_DEFAULT = 2000;
+/** Default fixture dwell under `--fast` when duration is enabled. */
+export const FIXTURE_DURATION_FAST_MS_DEFAULT = 600;
+/** @deprecated Prefer FIXTURE_DURATION_MS_DEFAULT */
+export const SLIDE_DURATION_MS_DEFAULT = FIXTURE_DURATION_MS_DEFAULT;
+/** @deprecated Prefer FIXTURE_DURATION_FAST_MS_DEFAULT */
+export const SLIDE_DURATION_FAST_MS_DEFAULT = FIXTURE_DURATION_FAST_MS_DEFAULT;
+/**
+ * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
+ * or `null` when duration is unset (caller keeps legacy timing).
  */
+export function resolveFixtureDwellMs(fixture, opts) {
+    if (fixture.duration === undefined || fixture.duration === false)
+        return null;
+    const fast = !!opts?.gatesFast;
+    const fastMs = typeof fixture.fastMode === "number" && Number.isFinite(fixture.fastMode) && fixture.fastMode >= 0
+        ? fixture.fastMode
+        : FIXTURE_DURATION_FAST_MS_DEFAULT;
+    if (fast)
+        return fastMs;
+    if (fixture.duration === true)
+        return FIXTURE_DURATION_MS_DEFAULT;
+    if (typeof fixture.duration === "number" && Number.isFinite(fixture.duration) && fixture.duration >= 0) {
+        return fixture.duration;
+    }
+    return FIXTURE_DURATION_MS_DEFAULT;
+}
+/** @deprecated Prefer {@link resolveFixtureDwellMs} */
+export function resolveSlideDwellMs(slide, opts) {
+    return resolveFixtureDwellMs(slide, opts);
+}
 function isStubPhase(v) {
     return !!v && typeof v === "object" && !Array.isArray(v);
 }
+function pickDurationFields(base, patch) {
+    const out = {};
+    const duration = patch?.duration !== undefined ? patch.duration : base?.duration;
+    const fastMode = patch?.fastMode !== undefined ? patch.fastMode : base?.fastMode;
+    if (duration !== undefined)
+        out.duration = duration;
+    if (fastMode !== undefined)
+        out.fastMode = fastMode;
+    return out;
+}
 function mergeSlot(base, patch) {
     if (!base && !patch)
         return null;
+    const dwell = pickDurationFields(base, patch);
     if (!base && patch) {
         if (!patch.selector)
             return null;
@@ -19,6 +65,7 @@ function mergeSlot(base, patch) {
             label: patch.label,
             ...(patch.detail ? { detail: patch.detail } : {}),
             ...(patch.tag ? { tag: patch.tag } : {}),
+            ...dwell,
         };
     }
     if (base && !patch)
@@ -32,6 +79,7 @@ function mergeSlot(base, patch) {
                 ? { detail: base.detail }
                 : {}),
         ...(patch.tag !== undefined ? { tag: patch.tag } : base.tag ? { tag: base.tag } : {}),
+        ...dwell,
     };
 }
 function phaseFromLegacyHighlights(highlights) {
@@ -48,10 +96,15 @@ function phaseFromLegacyHighlights(highlights) {
 /**
  * Resolve ordered highlight slots for a phase, merging flow fixtures over block stubs.
  * Shim: empty stubAfter + legacy `instruction.highlights` -> auto-keyed stubAfter.
+ * `stubOnError` is fail-path only (demo step catch) - never run on success.
  */
 export function resolveHighlightSlots(block, phase, opts) {
     const instr = block.instruction;
-    let raw = phase === "stubBefore" ? instr.stubBefore : instr.stubAfter;
+    let raw = phase === "stubBefore"
+        ? instr.stubBefore
+        : phase === "stubAfter"
+            ? instr.stubAfter
+            : instr.stubOnError;
     let phaseMap = {};
     if (typeof raw === "function") {
         try {
@@ -134,3 +187,12 @@ export function hasAuthoredStubAfter(block, out, fixtures) {
         ...(fixtures !== undefined ? { fixtures } : {}),
     }).length > 0;
 }
+/**
+ * True when stubOnError resolves to at least one ring (block and/or flow fixture).
+ * Demo fail path only - success never consults this.
+ */
+export function hasAuthoredStubOnError(block, fixtures) {
+    return (resolveHighlightSlots(block, "stubOnError", {
+        ...(fixtures !== undefined ? { fixtures } : {}),
+    }).length > 0);
+}

package/dist/index.d.ts

@@ -2,10 +2,10 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInsta
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
-export { resolveHighlightSlots, resolveSlides, formatHighlightCaption, hasAuthoredStubAfter, } from "./highlights.js";
-export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, HighlightStubPhase, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, } from "./highlights.js";
-export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, } from "./highlights.js";
+export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";

package/dist/index.js

@@ -1,6 +1,6 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
-export { resolveHighlightSlots, resolveSlides, formatHighlightCaption, hasAuthoredStubAfter, } from "./highlights.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

package/dist/trait.js

@@ -22,7 +22,9 @@ export function urlMatches(pattern) {
     return {
         name: `url-matches(${JSON.stringify(pattern)})`,
         async check(page) {
-            await page.waitForURL(urlPattern);
+            // Bound wait - fail loud instead of hanging forever when navigation never comes
+            // (e.g. locked_out login still on / while verify demands /inventory.html).
+            await page.waitForURL(urlPattern, { timeout: 8_000 });
             return true;
         },
     };

package/dist/types.d.ts

@@ -101,6 +101,13 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
      * @example stubAfter: { badge: { selector: ".cart", label: "Cart updated" } }
      */
     stubAfter?: HighlightStubPhaseOrFn<Out>;
+    /**
+     * Demo slots shown when a **step throws** (failed verify / act error) -
+     * before the error panel. Success-only {@link Instruction.stubAfter} never runs
+     * here; authors keep distinct BUG/FAIL copy. Named map; `{}` is valid.
+     * @example stubOnError: { card: { selector: ".alt-1", label: "Card at failure" } }
+     */
+    stubOnError?: HighlightStubPhaseOrFn<Out>;
     /**
      * Multi-step demo captions ("yap" slides) with Next between each -
      * not block lifecycle. Explains a long process; optional `selector` rings

package/examples/saucedemo/package-lock.json

@@ -17,7 +17,7 @@
       }
     },
     "../..": {
-      "version": "0.10.0",
+      "version": "0.12.4",
       "license": "MIT",
       "dependencies": {
         "tsx": "^4.0.0"

package/examples/saucedemo/package.json

@@ -16,6 +16,7 @@
     "prove:auto-cli": "node scripts/drive-auto-cli.mjs",
     "graph": "waygraph graph",
     "graph:mermaid": "waygraph graph --mermaid",
+    "demo:stub-on-error": "waygraph demo --blocks stubOnErrorFlow --auto-next --fast --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --title \"stubOnError prove\"",
     "prove:login-branch": "node scripts/prove-wrong-login-runtime.mjs",
     "prove:graph": "node scripts/prove-auto-graph.mjs",
     "prove:add-to-cart-menu": "node scripts/prove-add-to-cart-menu.mjs",

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

@@ -26,6 +26,7 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
         selector: ".complete-header",
         label: "Order confirmed",
         detail: "Thank you for your order!",
+        duration: true,
       },
     },
     // Shown AFTER act (order already placed) - selectors must match the
@@ -35,18 +36,23 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
         caption: "Checkout is a short pipeline",
         detail: "Cart -> info -> overview -> done. You just placed the order.",
         tag: "YAP",
+        duration: true,
       },
       {
         caption: "Completion page is the durable proof",
         detail: "The thank-you header is what verify asserts on.",
         tag: "YAP",
         selector: ".complete-header",
+        duration: 2500,
+        fastMode: 700,
       },
       {
         caption: "Episode continues after this yap",
         detail: "Next step rings the same banner, then you move on.",
         tag: "YAP",
         selector: ".complete-header",
+        duration: true,
+        fastMode: 500,
       },
     ],
   },

package/examples/saucedemo/src/blocks/saucedemo-web/ff-owner-auth.block.ts

@@ -0,0 +1,17 @@
+import { fastForwardComposeBlock } from "waygraph";
+import { NavLoginBlock } from "./nav-login.block.js";
+import { SubmitLoginForFlow } from "./methods/submit-login-for-flow.js";
+
+/**
+ * Kind: FFCompose (fast-forward)
+ * Helper: fastForwardComposeBlock
+ * Route: saucedemo-web/  (auth prefix)
+ *
+ * Collapses nav-login + submit-login into one opaque demo/run step so
+ * checkout demos skip watching auth. Use --ff-expand to gate inners again.
+ * loginFlow stays expanded for Sign In episode narration.
+ */
+export const FfOwnerAuthBlock = fastForwardComposeBlock("ff-owner-auth", [
+  NavLoginBlock,
+  SubmitLoginForFlow,
+]);

package/examples/saucedemo/src/blocks/saucedemo-web/methods/submit-login.method.block.ts

@@ -26,9 +26,16 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       await page.locator("#login-button").click({ noWaitAfter: true });
     },
     async observe(page): Promise<LoginObserve> {
+      // Race inventory nav vs error banner - locked_out / wrong password show
+      // Epic sadface immediately; do not burn the full inventory timeout.
+      const inventory = page.waitForURL(/\/inventory\.html/, { timeout: 8_000 }).then(() => "success" as const);
+      const errorBanner = page
+        .locator('[data-test="error"]')
+        .first()
+        .waitFor({ state: "visible", timeout: 8_000 })
+        .then(() => "failure" as const);
       try {
-        await page.waitForURL(/\/inventory\.html/, { timeout: 8_000 });
-        return "success";
+        return await Promise.race([inventory, errorBanner]);
       } catch {
         return "failure";
       }
@@ -44,5 +51,14 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       submit: { selector: "#login-button", label: "Login" },
     },
     stubAfter: {},
+    // Fail-path rings (demo step throw only) - locked-out / wrong-password
+    // bug-repro narration; success never shows these.
+    stubOnError: {
+      error: {
+        selector: '[data-test="error"]',
+        label: "Login error banner",
+        duration: true,
+      },
+    },
   },
 });

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

@@ -1,6 +1,5 @@
 import { Engine, start, end, withTitle, withHighlightFixtures } from "waygraph";
 import type {
-  LoginPage,
   LoggedIn,
   ItemInCart,
   CartPage,
@@ -8,8 +7,7 @@ import type {
   CheckoutOverviewPage,
   OrderComplete,
 } from "../states/checkout.states.js";
-import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
-import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
+import { FfOwnerAuthBlock } from "../blocks/saucedemo-web/ff-owner-auth.block.js";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
@@ -18,18 +16,18 @@ import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/meth
 
 const engine = new Engine({ headless: false, slowMo: 250 });
 
-// Atomic nav/action per real URL - the shape `waygraph auto` discovers.
-// Explicit type args: AddToCartBlock's In is Checkpoint<string> (wildcard),
-// which trips defineFlow overload inference across a long array.
+// Atomic nav/action per real URL after auth - the shape `waygraph auto` discovers.
+// Auth is one FFCompose step (ff-owner-auth) so demo pacing skips login yap;
+// use --ff-expand (or loginFlow) when you need per-step auth narration.
 //
-// Demo narration showcase (waygraph 0.11+):
-// - Block stubs: submit-login stubBefore, add-to-cart / finish-order stubAfter
-// - Flow fixtures: ticket-style captions (unlimited purposes on .flow.ts)
+// Demo narration showcase (waygraph 0.11+ / FFCompose 0.12):
+// - FF opaque: one gate for auth; stubs on interesting post-login blocks
+// - Block stubs: add-to-cart / finish-order stubAfter
+// - Flow fixtures: ticket-style captions
 // - Slides on finish-order: multi-step yap with Next between slides
 export const checkoutFlow = withHighlightFixtures(
   withTitle(
     engine.defineFlow<
-      LoginPage,
       LoggedIn,
       ItemInCart,
       CartPage,
@@ -38,8 +36,7 @@ export const checkoutFlow = withHighlightFixtures(
       OrderComplete
     >([
       start,
-      NavLoginBlock,
-      SubmitLoginForFlow,
+      FfOwnerAuthBlock,
       AddToCartBlock,
       NavCartBlock,
       NavCheckoutInfoBlock,
@@ -50,15 +47,27 @@ export const checkoutFlow = withHighlightFixtures(
     "Owner: Full Checkout",
   ),
   {
+    "ff-owner-auth": {
+      stubAfter: {
+        inventory: {
+          label: "Signed in (fast-forward)",
+          detail: "Auth collapsed via FFCompose - interesting work starts here.",
+          tag: "AC",
+          duration: true,
+        },
+      },
+    },
+    // Kept for --ff-expand (inners become separate steps again).
     "submit-login": {
       stubBefore: {
         username: {
           label: "Demo user",
-          detail: "standard_user from Mem — library block stays neutral.",
+          detail: "standard_user from Mem - library block stays neutral.",
           tag: "AC",
+          duration: true,
         },
-        password: { label: "Password", detail: "Filled from Mem credentials." },
-        submit: { label: "Sign in", tag: "GATE" },
+        password: { label: "Password", detail: "Filled from Mem credentials.", duration: 1500 },
+        submit: { label: "Sign in", tag: "GATE", duration: true, fastMode: 500 },
       },
     },
     "add-to-cart": {
@@ -67,6 +76,7 @@ export const checkoutFlow = withHighlightFixtures(
           label: "Cart now has the item",
           detail: "Badge updates after Add to cart.",
           tag: "AC",
+          duration: true,
         },
       },
     },
@@ -76,9 +86,10 @@ export const checkoutFlow = withHighlightFixtures(
           label: "Order placed",
           detail: "Completion header is the durable proof.",
           tag: "GATE",
+          duration: 2500,
+          fastMode: 700,
         },
       },
-      // Optional: fixture can replace block slides; leave unset to use block slides.
     },
   },
 );

package/examples/saucedemo/src/flows/stub-on-error.flow.ts

@@ -0,0 +1,48 @@
+import {
+  Engine,
+  start,
+  end,
+  withTitle,
+  withSessionReset,
+  withExpectedFailure,
+  withHighlightFixtures,
+  Trait,
+} from "waygraph";
+import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
+import { SubmitLoginActionBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
+
+const engine = new Engine();
+
+/**
+ * Prove stubOnError (waygraph 0.12.4+): force verify to demand /inventory.html
+ * while mem is locked_out_user — step throws, demo rings the error banner
+ * before the error panel, then expected-failure styling.
+ *
+ *   waygraph demo --blocks stubOnErrorFlow --auto-next --fast \\
+ *     --data '{"saucedemo.credentials":{"username":"locked_out_user","password":"secret_sauce"}}'
+ */
+const forcedInventoryVerify = withSessionReset(
+  engine
+    .defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])
+    .withBlockVerify("submit-login", [Trait.url({ pathname: "/inventory.html" })]),
+);
+
+export const stubOnErrorFlow = withHighlightFixtures(
+  withExpectedFailure(
+    withTitle(forcedInventoryVerify, "stubOnError: locked_out fail rings"),
+    "Intentional verify fail - stubOnError rings the error banner before the panel",
+  ),
+  {
+    "submit-login": {
+      stubOnError: {
+        error: {
+          label: "BUG · locked out still on login",
+          detail: "Verify demanded inventory; banner is the proof point.",
+          tag: "FAIL",
+          duration: true,
+          fastMode: 500,
+        },
+      },
+    },
+  },
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.11.2",
+  "version": "0.12.4",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",