waygraph 0.10.8 → 0.11.0

package/dist/engine.d.ts

@@ -180,6 +180,12 @@ export interface Flow<Out extends Checkpoint<string>> {
      * alarming one indistinguishable from a real break.
      */
     readonly expectedFailureReason?: string;
+    /**
+     * Set once this Flow has been wrapped in {@link withHighlightFixtures} -
+     * demo narration overrides (unlimited purposes on `.flow.ts`) keyed by
+     * block.name. `run()` never reads this; step/`demo` merges onto block stubs.
+     */
+    readonly highlightFixtures?: import("./highlights.js").HighlightFixtureMap;
     /**
      * This Flow's constituent Blocks, in order between `start`/`end`, as plain
      * data - for introspection/visualization tools, without running anything.
@@ -266,6 +272,14 @@ export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out
  * );
  */
 export declare function withExpectedFailure<Out extends Checkpoint<string>>(flow: Flow<Out>, reason: string): Flow<Out>;
+/**
+ * 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}.
+ * Demo/`chain --step` reads `flow.highlightFixtures`; `run()` ignores it.
+ * @example withHighlightFixtures(issueFlow, { "submit-login": { stubBefore: { email: { label: "AC-1" } } } })
+ */
+export declare function withHighlightFixtures<Out extends Checkpoint<string>>(flow: Flow<Out>, fixtures: import("./highlights.js").HighlightFixtureMap): Flow<Out>;
 /**
  * Runs several complete, independent Flows one after another, reusing the
  * same page/context/mem in order - each remains its own validated
@@ -493,6 +507,9 @@ export type NavBlockOptions<Out extends Checkpoint<string>> = {
     checkpoint: Out["__state"];
     requires?: readonly MemKey<any>[];
     verify?: Trait[] | ((out: Out) => Trait[]);
+    stubBefore?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
+    stubAfter?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
+    /** @deprecated Prefer stubAfter. */
     highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
     /**
      * Live per-instance menu rows for `waygraph auto` (see {@link Block.instanceOptions}).
@@ -553,6 +570,9 @@ export type NavClickBlockOptions<Out extends Checkpoint<string>> = {
     click: string | ((mem: MemPage) => string);
     requires?: readonly MemKey<any>[];
     verify?: Trait[] | ((out: Out) => Trait[]);
+    stubBefore?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
+    stubAfter?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
+    /** @deprecated Prefer stubAfter. */
     highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
     instanceOptions?: Block<Checkpoint<string>, Out>["instanceOptions"];
 };
@@ -581,6 +601,9 @@ export type PageBlockOptions<Out extends Checkpoint<string>> = {
     /** Checkpoint tag for this screen (hub). */
     checkpoint: Out["__state"];
     verify?: Trait[] | ((out: Out) => Trait[]);
+    stubBefore?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
+    stubAfter?: import("./highlights.js").HighlightStubPhase | ((out: Out) => import("./highlights.js").HighlightStubPhase);
+    /** @deprecated Prefer stubAfter. */
     highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
     requires?: readonly MemKey<any>[];
     /**

package/dist/engine.js

@@ -377,6 +377,21 @@ export function withExpectedFailure(flow, reason) {
         modBlockVerify: (block, nameOrIndex, newCheck) => withExpectedFailure(flow.modBlockVerify(block, nameOrIndex, newCheck), 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}.
+ * Demo/`chain --step` reads `flow.highlightFixtures`; `run()` ignores it.
+ * @example withHighlightFixtures(issueFlow, { "submit-login": { stubBefore: { email: { label: "AC-1" } } } })
+ */
+export function withHighlightFixtures(flow, fixtures) {
+    return {
+        ...flow,
+        highlightFixtures: fixtures,
+        withBlockVerify: (block, verify) => withHighlightFixtures(flow.withBlockVerify(block, verify), fixtures),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withHighlightFixtures(flow.modBlockVerify(block, nameOrIndex, newCheck), fixtures),
+    };
+}
 function locateInChain(flows, block) {
     if (typeof block === "number") {
         let remaining = block;
@@ -659,6 +674,8 @@ export function defineNavBlock(options) {
             },
             resolve: () => checkpoint(options.checkpoint),
             ...(options.verify ? { verify: options.verify } : {}),
+            ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
+            ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
             ...(options.highlights ? { highlights: options.highlights } : {}),
         },
     });
@@ -692,6 +709,8 @@ export function defineNavClickBlock(options) {
         ...(options.description ? { description: options.description } : {}),
         ...(options.requires ? { requires: options.requires } : {}),
         ...(options.verify ? { verify: options.verify } : {}),
+        ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
+        ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
         ...(options.highlights ? { highlights: options.highlights } : {}),
         ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
     });
@@ -738,6 +757,8 @@ export function definePageBlock(options) {
             },
             resolve: () => checkpoint(options.checkpoint),
             ...(options.verify ? { verify: options.verify } : {}),
+            ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
+            ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
             ...(options.highlights ? { highlights: options.highlights } : {}),
         },
     });

package/dist/highlights.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Block stubBefore / stubAfter + 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;
+ * slides are multi-step captions with Next between them (long-process explain).
+ */
+import type { Block, Checkpoint } from "./types.js";
+/** One named highlight slot on a block (selector + caption). */
+export interface WaygraphHighlightStub {
+    selector: string;
+    /** Primary caption line. */
+    label: string;
+    /** Extra caption line (ring / slide body). */
+    detail?: string;
+    /** Short badge, e.g. AC / BUG / GATE / YAP. */
+    tag?: string;
+}
+/** 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 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 {
+    /** Primary caption (required). */
+    caption: string;
+    detail?: string;
+    tag?: string;
+    /** Optional ring while this slide is showing. */
+    selector?: string;
+}
+export type WaygraphSlidesOrFn<Out extends Checkpoint<string>> = readonly WaygraphSlide[] | ((out: Out) => readonly WaygraphSlide[]);
+/** Per-block fixture map attached to a Flow via {@link withHighlightFixtures}. */
+export type HighlightFixtureMap = Record<string, {
+    stubBefore?: Record<string, WaygraphHighlightFixture>;
+    stubAfter?: Record<string, WaygraphHighlightFixture>;
+    /** Override / supply multi-step yap slides for this block (demo only). */
+    slides?: readonly WaygraphSlide[];
+}>;
+/** Legacy array highlight (shimmed to stubAfter keys "0", "1", ...). */
+export interface WaygraphHighlight {
+    selector: string;
+    label: string;
+}
+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.
+ */
+export declare function resolveHighlightSlots(block: Block<any, any>, phase: "stubBefore" | "stubAfter", opts?: {
+    out?: Checkpoint<string>;
+    fixtures?: HighlightFixtureMap;
+}): ResolvedHighlight[];
+/**
+ * Resolve multi-step yap slides: flow fixture `slides` wins when present,
+ * else `instruction.slides` (function form allowed).
+ */
+export declare function resolveSlides(block: Block<any, any>, opts?: {
+    out?: Checkpoint<string>;
+    fixtures?: HighlightFixtureMap;
+}): WaygraphSlide[];
+/** Caption for ring / slide UI (label|caption + optional detail/tag). */
+export declare function formatHighlightCaption(h: {
+    label?: string;
+    caption?: string;
+    detail?: string;
+    tag?: string;
+}): string;
+/**
+ * True when the block authored a non-empty stubAfter (after resolve + shim),
+ * 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;

package/dist/highlights.js

@@ -0,0 +1,136 @@
+/**
+ * Block stubBefore / stubAfter + 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;
+ * slides are multi-step captions with Next between them (long-process explain).
+ */
+function isStubPhase(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function mergeSlot(base, patch) {
+    if (!base && !patch)
+        return null;
+    if (!base && patch) {
+        if (!patch.selector)
+            return null;
+        return {
+            selector: patch.selector,
+            label: patch.label,
+            ...(patch.detail ? { detail: patch.detail } : {}),
+            ...(patch.tag ? { tag: patch.tag } : {}),
+        };
+    }
+    if (base && !patch)
+        return { ...base };
+    return {
+        selector: patch.selector ?? base.selector,
+        label: patch.label,
+        ...(patch.detail !== undefined
+            ? { detail: patch.detail }
+            : base.detail
+                ? { detail: base.detail }
+                : {}),
+        ...(patch.tag !== undefined ? { tag: patch.tag } : base.tag ? { tag: base.tag } : {}),
+    };
+}
+function phaseFromLegacyHighlights(highlights) {
+    const out = {};
+    if (!highlights)
+        return out;
+    highlights.forEach((h, i) => {
+        if (h && typeof h.selector === "string" && typeof h.label === "string") {
+            out[String(i)] = { selector: h.selector, label: h.label };
+        }
+    });
+    return out;
+}
+/**
+ * Resolve ordered highlight slots for a phase, merging flow fixtures over block stubs.
+ * Shim: empty stubAfter + legacy `instruction.highlights` -> auto-keyed stubAfter.
+ */
+export function resolveHighlightSlots(block, phase, opts) {
+    const instr = block.instruction;
+    let raw = phase === "stubBefore" ? instr.stubBefore : instr.stubAfter;
+    let phaseMap = {};
+    if (typeof raw === "function") {
+        try {
+            phaseMap = raw(opts?.out ?? { __state: "" }) || {};
+        }
+        catch {
+            phaseMap = {};
+        }
+    }
+    else if (isStubPhase(raw)) {
+        phaseMap = { ...raw };
+    }
+    if (phase === "stubAfter" && Object.keys(phaseMap).length === 0 && instr.highlights) {
+        let legacy = instr.highlights;
+        if (typeof legacy === "function") {
+            try {
+                legacy = legacy(opts?.out ?? { __state: "" });
+            }
+            catch {
+                legacy = [];
+            }
+        }
+        phaseMap = phaseFromLegacyHighlights(Array.isArray(legacy) ? legacy : []);
+    }
+    const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
+    const slotIds = new Set([...Object.keys(phaseMap), ...Object.keys(fixturePhase || {})]);
+    const ordered = [...slotIds].sort((a, b) => {
+        const na = Number(a);
+        const nb = Number(b);
+        if (!Number.isNaN(na) && !Number.isNaN(nb))
+            return na - nb;
+        return a.localeCompare(b);
+    });
+    const resolved = [];
+    for (const id of ordered) {
+        const merged = mergeSlot(phaseMap[id], fixturePhase?.[id]);
+        if (merged)
+            resolved.push(merged);
+    }
+    return resolved;
+}
+/**
+ * Resolve multi-step yap slides: flow fixture `slides` wins when present,
+ * else `instruction.slides` (function form allowed).
+ */
+export function resolveSlides(block, opts) {
+    const fromFixture = opts?.fixtures?.[block.name]?.slides;
+    if (fromFixture && fromFixture.length > 0) {
+        return [...fromFixture];
+    }
+    const instr = block.instruction;
+    let raw = instr.slides;
+    if (typeof raw === "function") {
+        try {
+            raw = raw(opts?.out ?? { __state: "" });
+        }
+        catch {
+            raw = [];
+        }
+    }
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((s) => s && typeof s.caption === "string" && s.caption.length > 0);
+}
+/** Caption for ring / slide UI (label|caption + optional detail/tag). */
+export function formatHighlightCaption(h) {
+    const primary = h.caption ?? h.label ?? "";
+    const tag = h.tag ? `[${h.tag}] ` : "";
+    if (h.detail)
+        return `${tag}${primary} - ${h.detail}`;
+    return `${tag}${primary}`;
+}
+/**
+ * True when the block authored a non-empty stubAfter (after resolve + shim),
+ * including legacy highlights. When true, demo should not use verify-trait fallback.
+ */
+export function hasAuthoredStubAfter(block, out, fixtures) {
+    return resolveHighlightSlots(block, "stubAfter", {
+        ...(out !== undefined ? { out } : {}),
+        ...(fixtures !== undefined ? { fixtures } : {}),
+    }).length > 0;
+}

package/dist/index.d.ts

@@ -2,7 +2,9 @@ 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, chainFlow, } 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, 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 type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

package/dist/index.js

@@ -1,5 +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, chainFlow, } 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, preflight, withSessionReset, withTitle, withExpectedFailure, withHighlightFixtures, chainFlow, } from "./engine.js";
+export { resolveHighlightSlots, resolveSlides, formatHighlightCaption, hasAuthoredStubAfter, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 import type { Page } from "@playwright/test";
 import type { MemPage, MemKey } from "./mem-page.js";
 import type { Trait } from "./trait.js";
+import type { HighlightStubPhaseOrFn, WaygraphHighlight, WaygraphSlidesOrFn } from "./highlights.js";
+export type { WaygraphHighlight, WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, HighlightStubPhase, HighlightStubPhaseOrFn, HighlightFixtureMap, ResolvedHighlight, } from "./highlights.js";
 /**
  * A Checkpoint is identified solely by its string tag - a phantom marker with no
  * embedded data. Two Checkpoints with the same tag are the same state everywhere.
@@ -88,24 +90,33 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
      */
     verify?: Trait[] | ((out: Out) => Trait[]);
     /**
-     * Optional. Arbitrary highlight points for step-mode tooling to show, in
-     * order, after this Block resolves - independent of `verify`, for
-     * calling out something worth a human's attention regardless of whether
-     * it's also being asserted ("remember this signature ID" isn't a
-     * pass/fail check). A function form picks different highlights per
-     * resolved `Out`, same as `verify`. Purely additive UI narration - never
-     * consulted by `runGraph`/`connect`/anything that decides behavior.
-     * @example highlights: (out) => [{ selector: "#signature-id", label: "remember this ID" }]
+     * Catch-all demo slots shown **before / during** `act` (fill/click rings).
+     * Named map; `{}` is valid. Flow {@link HighlightFixtureMap} overrides labels.
+     * @example stubBefore: { email: { selector: "#email", label: "Email" } }
+     */
+    stubBefore?: HighlightStubPhaseOrFn<Out>;
+    /**
+     * Catch-all demo slots shown **after** resolve (step panel rings).
+     * Named map; `{}` is valid. Prefer this over legacy {@link Instruction.highlights}.
+     * @example stubAfter: { badge: { selector: ".cart", label: "Cart updated" } }
+     */
+    stubAfter?: HighlightStubPhaseOrFn<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>;
+    /**
+     * @deprecated Prefer {@link Instruction.stubAfter}. Shimmed to stubAfter keys
+     * `"0"`, `"1"`, … when stubAfter is empty.
      */
     highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
 }
-/** One arbitrary highlight point - see {@link Instruction.highlights}. */
-export interface WaygraphHighlight {
-    /** CSS selector for the element to highlight. */
-    selector: string;
-    /** Caption shown next to the highlight ring. */
-    label: string;
-}
 /**
  * One selectable option for a Block whose real choices depend on the live
  * page - "which of these items to add to cart" is only knowable by looking

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

@@ -18,6 +18,34 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
     },
     resolve: () => checkpoint("OrderComplete"),
     verify: [Trait.text(".complete-header", "Thank you for your order!")],
-    highlights: () => [{ selector: ".complete-header", label: "remember this: order confirmed" }],
+    stubBefore: {
+      finish: { selector: "#finish", label: "Finish" },
+    },
+    stubAfter: {
+      thanks: {
+        selector: ".complete-header",
+        label: "Order confirmed",
+        detail: "Thank you for your order!",
+      },
+    },
+    slides: [
+      {
+        caption: "Checkout is a short pipeline",
+        detail: "Cart → info → overview → done. Watch the last click place the order.",
+        tag: "YAP",
+      },
+      {
+        caption: "Finish submits the overview",
+        detail: "This click is the only mutating step on this screen.",
+        tag: "YAP",
+        selector: "#finish",
+      },
+      {
+        caption: "Completion banner is the proof",
+        detail: "The next ring calls out the thank-you header.",
+        tag: "YAP",
+        selector: ".complete-header",
+      },
+    ],
   },
 });

package/examples/saucedemo/src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts

@@ -30,7 +30,14 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         },
       },
     ],
-    highlights: () => [{ selector: InventorySel.cartBadge, label: "remember this: cart now has the item" }],
+    stubBefore: {},
+    stubAfter: {
+      badge: {
+        selector: InventorySel.cartBadge,
+        label: "Cart badge",
+        detail: "Item is in the cart",
+      },
+    },
   },
   async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
     const items = await collectAddableItems(page);

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

@@ -38,5 +38,11 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       out.__state === "LoggedIn"
         ? [Trait.url({ pathname: "/inventory.html" })]
         : [Trait.visible('[data-test="error"]')],
+    stubBefore: {
+      username: { selector: "#user-name", label: "Username" },
+      password: { selector: "#password", label: "Password" },
+      submit: { selector: "#login-button", label: "Login" },
+    },
+    stubAfter: {},
   },
 });

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

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle } from "waygraph";
+import { Engine, start, end, withTitle, withHighlightFixtures } from "waygraph";
 import type {
   LoginPage,
   LoggedIn,
@@ -21,25 +21,64 @@ 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.
-export const checkoutFlow = withTitle(
-  engine.defineFlow<
-    LoginPage,
-    LoggedIn,
-    ItemInCart,
-    CartPage,
-    CheckoutInfoPage,
-    CheckoutOverviewPage,
-    OrderComplete
-  >([
-    start,
-    NavLoginBlock,
-    SubmitLoginForFlow,
-    AddToCartBlock,
-    NavCartBlock,
-    NavCheckoutInfoBlock,
-    SubmitCheckoutInfoBlock,
-    FinishOrderBlock,
-    end,
-  ]),
-  "Owner: Full Checkout",
+//
+// 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)
+// - Slides on finish-order: multi-step yap with Next between slides
+export const checkoutFlow = withHighlightFixtures(
+  withTitle(
+    engine.defineFlow<
+      LoginPage,
+      LoggedIn,
+      ItemInCart,
+      CartPage,
+      CheckoutInfoPage,
+      CheckoutOverviewPage,
+      OrderComplete
+    >([
+      start,
+      NavLoginBlock,
+      SubmitLoginForFlow,
+      AddToCartBlock,
+      NavCartBlock,
+      NavCheckoutInfoBlock,
+      SubmitCheckoutInfoBlock,
+      FinishOrderBlock,
+      end,
+    ]),
+    "Owner: Full Checkout",
+  ),
+  {
+    "submit-login": {
+      stubBefore: {
+        username: {
+          label: "Demo user",
+          detail: "standard_user from Mem — library block stays neutral.",
+          tag: "AC",
+        },
+        password: { label: "Password", detail: "Filled from Mem credentials." },
+        submit: { label: "Sign in", tag: "GATE" },
+      },
+    },
+    "add-to-cart": {
+      stubAfter: {
+        badge: {
+          label: "Cart now has the item",
+          detail: "Badge updates after Add to cart.",
+          tag: "AC",
+        },
+      },
+    },
+    "finish-order": {
+      stubAfter: {
+        thanks: {
+          label: "Order placed",
+          detail: "Completion header is the durable proof.",
+          tag: "GATE",
+        },
+      },
+      // Optional: fixture can replace block slides; leave unset to use block slides.
+    },
+  },
 );

package/package.json

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

package/templates/quickstart/package.json

@@ -23,7 +23,7 @@
     "baseUrl": "https://www.saucedemo.com"
   },
   "dependencies": {
-    "waygraph": "^0.10.6"
+    "waygraph": "^0.11.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

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

@@ -18,6 +18,34 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
     },
     resolve: () => checkpoint("OrderComplete"),
     verify: [Trait.text(".complete-header", "Thank you for your order!")],
-    highlights: () => [{ selector: ".complete-header", label: "remember this: order confirmed" }],
+    stubBefore: {
+      finish: { selector: "#finish", label: "Finish" },
+    },
+    stubAfter: {
+      thanks: {
+        selector: ".complete-header",
+        label: "Order confirmed",
+        detail: "Thank you for your order!",
+      },
+    },
+    slides: [
+      {
+        caption: "Checkout is a short pipeline",
+        detail: "Cart → info → overview → done. Watch the last click place the order.",
+        tag: "YAP",
+      },
+      {
+        caption: "Finish submits the overview",
+        detail: "This click is the only mutating step on this screen.",
+        tag: "YAP",
+        selector: "#finish",
+      },
+      {
+        caption: "Completion banner is the proof",
+        detail: "The next ring calls out the thank-you header.",
+        tag: "YAP",
+        selector: ".complete-header",
+      },
+    ],
   },
 });

package/templates/quickstart/src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts

@@ -30,7 +30,14 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         },
       },
     ],
-    highlights: () => [{ selector: InventorySel.cartBadge, label: "remember this: cart now has the item" }],
+    stubBefore: {},
+    stubAfter: {
+      badge: {
+        selector: InventorySel.cartBadge,
+        label: "Cart badge",
+        detail: "Item is in the cart",
+      },
+    },
   },
   async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
     const items = await collectAddableItems(page);

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

@@ -38,5 +38,11 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       out.__state === "LoggedIn"
         ? [Trait.url({ pathname: "/inventory.html" })]
         : [Trait.visible('[data-test="error"]')],
+    stubBefore: {
+      username: { selector: "#user-name", label: "Username" },
+      password: { selector: "#password", label: "Password" },
+      submit: { selector: "#login-button", label: "Login" },
+    },
+    stubAfter: {},
   },
 });