waygraph 0.10.9 → 0.11.0

package/dist/cli.js

@@ -200,6 +200,12 @@ const CHAIN_RUNNER_SCRIPT = `
 import { readdirSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import {
+  resolveHighlightSlots,
+  resolveSlides,
+  formatHighlightCaption,
+  hasAuthoredStubAfter,
+} from "waygraph";
 
 function walkDir(dir, pattern) {
   const results = [];
@@ -395,8 +401,8 @@ const RING_CSS =
   // pushed back onto screen, same width, never shrunk. See
   // window.__wgPositionRing in installOverlay.
   "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
-  "white-space:nowrap;padding:4px 9px;border-radius:7px;background:#7C3AED;color:#fff;" +
-  "font:600 12px/1.2 system-ui,sans-serif;transition:opacity .3s ease;}" +
+  "max-width:min(360px,70vw);white-space:normal;padding:6px 10px;border-radius:7px;background:#7C3AED;color:#fff;" +
+  "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease;}" +
   // Mouse cursor icon that travels to a target before it's acted on, plus a
   // quick expanding ripple at the moment of a click - same idea as
   // help-center-clip-engine's #clip-cursor/#clip-ring (video-pipeline). The
@@ -1379,6 +1385,162 @@ async function showRing(page, box, label) {
     .catch(() => {});
 }
 
+/** Match a locator to a stubBefore slot by overlapping bounding boxes. */
+async function captionForLocator(page, locator, stubs, fallback) {
+  if (!stubs || stubs.length === 0) return fallback;
+  const box = await locator.boundingBox().catch(() => null);
+  if (!box) return fallback;
+  for (const s of stubs) {
+    try {
+      const b = await page.locator(s.selector).first().boundingBox();
+      if (
+        b &&
+        Math.abs(b.x - box.x) < 4 &&
+        Math.abs(b.y - box.y) < 4 &&
+        Math.abs(b.width - box.width) < 8
+      ) {
+        return formatHighlightCaption(s);
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  return fallback;
+}
+
+/**
+ * Multi-step yap captions - not block lifecycle. Each slide waits for Next
+ * (or auto-next), optional ring via slide.selector.
+ */
+async function presentSlides(page, slides, gate, opts) {
+  const title = (opts && opts.title) || "waygraph demo";
+  const blockName = (opts && opts.blockName) || "";
+  for (let i = 0; i < slides.length; i++) {
+    const s = slides[i];
+    const caption = formatHighlightCaption(s);
+    const isLast = i === slides.length - 1;
+    await installOverlay(page, title);
+    if (s.selector) {
+      try {
+        const box = await page.locator(s.selector).first().boundingBox();
+        if (box) await showRing(page, box, caption);
+      } catch {
+        await hideRing(page);
+      }
+    } else {
+      await hideRing(page);
+    }
+    await page
+      .evaluate(
+        (info) => {
+          let panel = document.getElementById("wg-panel");
+          const isNew = !panel;
+          if (!panel) {
+            panel = document.createElement("div");
+            panel.id = "wg-panel";
+          }
+          panel.classList.remove("wg-collapsed", "wg-error", "wg-expected");
+          const esc = (t) =>
+            String(t).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
+          panel.innerHTML =
+            "<div class=\\"wg-chrome\\"><span class=\\"wg-chrome-title\\">waygraph demo</span>" +
+            "<button type=\\"button\\" class=\\"wg-hide-btn\\" data-wg-toggle=\\"1\\">Hide</button></div>" +
+            "<div class=\\"wg-body\\">" +
+            "<h3>Slide " +
+            (info.index + 1) +
+            " / " +
+            info.total +
+            (info.blockName ? " · " + esc(info.blockName) : "") +
+            "</h3>" +
+            (info.tag
+              ? "<div class=\\"wg-episode\\" style=\\"border:none;padding:0;margin:0 0 6px;font-size:11px;color:#c9a6ff\\">" +
+                esc(info.tag) +
+                "</div>"
+              : "") +
+            "<div class=\\"wg-narration\\">" +
+            esc(info.caption) +
+            "</div>" +
+            (info.detail
+              ? "<div class=\\"wg-result-pretty\\" style=\\"margin:0 0 12px;color:#f0e8ff\\">" +
+                esc(info.detail) +
+                "</div>"
+              : "") +
+            "<div class=\\"wg-autoplay-row\\"><label><input type=\\"checkbox\\" id=\\"wg-autoplay-cb\\"" +
+            (info.autoNow ? " checked" : "") +
+            "> Auto-advance</label></div>" +
+            "<div id=\\"wg-gate-manual\\"" +
+            (info.autoNow ? " style=\\"display:none\\"" : "") +
+            "><button id=\\"wg-run\\">" +
+            (info.isLast ? "Continue \\u25B6" : "Next slide \\u25B6") +
+            "</button></div>" +
+            "<div id=\\"wg-gate-auto\\" class=\\"wg-auto\\"" +
+            (info.autoNow ? "" : " style=\\"display:none\\"") +
+            ">Auto-advancing...</div>" +
+            "</div>";
+          if (isNew) {
+            document.documentElement.appendChild(panel);
+            requestAnimationFrame(() => panel.classList.add("wg-in"));
+          }
+          if (window.__wgWirePanelChrome) {
+            window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
+              stepLabel:
+                "Slide " +
+                (info.index + 1) +
+                " / " +
+                info.total +
+                (info.blockName ? " · " + info.blockName : ""),
+              forceCollapsed: false,
+            });
+          }
+          const cb = document.getElementById("wg-autoplay-cb");
+          if (cb) {
+            cb.addEventListener("change", () => {
+              try {
+                localStorage.setItem("wg-autoplay", cb.checked ? "1" : "0");
+              } catch {
+                /* ignore */
+              }
+              const manual = document.getElementById("wg-gate-manual");
+              const auto = document.getElementById("wg-gate-auto");
+              if (manual) manual.style.display = cb.checked ? "none" : "";
+              if (auto) auto.style.display = cb.checked ? "" : "none";
+            });
+          }
+          const runBtn = document.getElementById("wg-run");
+          if (runBtn) runBtn.addEventListener("click", () => window.__wgNext({}));
+        },
+        {
+          index: i,
+          total: slides.length,
+          caption: s.caption,
+          detail: s.detail || "",
+          tag: s.tag || "",
+          blockName,
+          isLast,
+          autoNow: false,
+        },
+      )
+      .catch(() => {});
+    await page
+      .evaluate(() => {
+        try {
+          const on = localStorage.getItem("wg-autoplay") === "1";
+          const cb = document.getElementById("wg-autoplay-cb");
+          if (cb) cb.checked = on;
+          const manual = document.getElementById("wg-gate-manual");
+          const auto = document.getElementById("wg-gate-auto");
+          if (manual) manual.style.display = on ? "none" : "";
+          if (auto) auto.style.display = on ? "" : "none";
+        } catch {
+          /* ignore */
+        }
+      })
+      .catch(() => {});
+    await gate();
+  }
+  await hideRing(page);
+}
+
 async function hideRing(page) {
   await page
     .evaluate(() => {
@@ -1455,7 +1617,7 @@ async function wasJustNarrated(page) {
     .catch(() => false);
 }
 
-function instrumentInteractionHighlighting(page, mem, slowMo, pacing) {
+function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef) {
   // Playwright's own slowMo ALREADY pauses after every single low-level
   // action it dispatches - and pressSequentially() fires one such action
   // PER CHARACTER. Also giving pressSequentially its own fixed delay
@@ -1469,6 +1631,7 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing) {
   // per-block (WAYGRAPH_FAST_BLOCKS), and the Locator.fill/click patches
   // below are installed once on the shared prototype but invoked once per
   // real interaction, long after this closure was created.
+  // stubBeforeRef.current = resolved stubBefore slots for the active block.
   const typeDelay = () => (pacing.fast ? 0 : slowMo ? 0 : 30);
   // Click is a single action, not per-character, so it doesn't compound
   // the same way - but slowMo still adds its own pause around the actual
@@ -1505,9 +1668,11 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing) {
           // Only trust the "last mem.get()" as THIS fill's source if it
           // happened recently - a stale read from several actions ago is
           // more likely unrelated than actually describing this field.
-          const label = memTrack.lastKeyName && Date.now() - memTrack.at < 3000
+          const fallback = memTrack.lastKeyName && Date.now() - memTrack.at < 3000
             ? "from mem: " + memTrack.lastKeyName
             : "writing from mem";
+          const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
+          const label = await captionForLocator(page, this, stubs, fallback);
           await moveCursorTo(page, box, cursorMs(500));
           await showRing(page, box, label);
           await new Promise((res) => setTimeout(res, pacing.fast ? 0 : 200));
@@ -1560,10 +1725,10 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing) {
         const box = await this.boundingBox();
         const narrated = box ? await wasJustNarrated(page) : false;
         if (box && !narrated) {
-          let label = "click";
+          let fallback = "click";
           try {
             const text = (await this.textContent())?.trim();
-            if (text && text.length > 0 && text.length <= 30) label = text;
+            if (text && text.length > 0 && text.length <= 30) fallback = text;
           } catch {
             // element has no simple text (an icon button, say) - generic label is fine
           }
@@ -1571,10 +1736,12 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing) {
           // (set on page by runStepMode just before act).
           try {
             const navLabel = await page.evaluate(() => window.__wgPendingNavClickLabel || null);
-            if (navLabel) label = String(navLabel);
+            if (navLabel) fallback = String(navLabel);
           } catch {
             /* ignore */
           }
+          const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
+          const label = await captionForLocator(page, this, stubs, fallback);
           clickPoint = await moveCursorTo(page, box, cursorMs(600));
           await showRing(page, box, label);
           // "pop for a few seconds" - Dan's own phrase, matching the
@@ -1703,7 +1870,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   const demoFast = process.env.WAYGRAPH_DEMO_FAST === "1";
   const stepperMode = process.env.WAYGRAPH_STEPPER === "full" ? "full" : "carousel";
   const pacing = { fast: demoFast };
-  instrumentInteractionHighlighting(page, mem, slowMo, pacing);
+  const stubBeforeRef = { current: [] };
+  instrumentInteractionHighlighting(page, mem, slowMo, pacing, stubBeforeRef);
   // Force the panel checkbox from this process's flags/env at run start.
   // installOverlay only seeds localStorage when the key is null (so mid-run
   // checkbox clicks survive navigations). Without this, a prior --autoplay
@@ -1852,6 +2020,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       await resetPageState(context, page, baseURL);
     }
     pacing.fast = demoFast || fastBlockNames.has(r.block.name);
+    const fixtures = r.highlightFixtures;
+    stubBeforeRef.current = resolveHighlightSlots(r.block, "stubBefore", { fixtures });
     const isNavBlock = r.block.__waygraphKind === "nav";
     const autoNow = await currentAutoplay();
     // Auto-next: tuck stepper on NavBlocks so the page transition fills the frame.
@@ -1975,7 +2145,26 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       })
       .catch(() => {});
     result = stepOutcome.result;
-    const highlights = extractVerifyHighlights(r.block, result.__state);
+    const fixturesAfter = r.highlightFixtures;
+    const slides = resolveSlides(r.block, { out: result, fixtures: fixturesAfter });
+    if (slides.length > 0) {
+      await presentSlides(page, slides, gate, {
+        title,
+        blockName: r.block.name,
+        fast: pacing.fast,
+      });
+    }
+    let highlights;
+    if (hasAuthoredStubAfter(r.block, result, fixturesAfter)) {
+      highlights = resolveHighlightSlots(r.block, "stubAfter", { out: result, fixtures: fixturesAfter }).map(
+        (h) => ({
+          selector: h.selector,
+          label: formatHighlightCaption(h),
+        }),
+      );
+    } else {
+      highlights = extractVerifyHighlights(r.block, result.__state);
+    }
     await renderAfterStep(page, {
       index: i,
       total: resolved.length,
@@ -2126,6 +2315,7 @@ async function main() {
         block: bi.block,
         exportName: bi.name,
         seedMem: idx === 0 ? seedMem : undefined,
+        highlightFixtures: flow.highlightFixtures,
         expectedFailureReason:
           flow.expectedFailureReason && idx === blockInfos.length - 1
             ? flow.expectedFailureReason
@@ -2187,6 +2377,7 @@ async function main() {
           episodeNumber: episodeCounter,
           episodeTitle: flow.title || seg.ref,
           expectedFailureReason: flow.expectedFailureReason,
+          highlightFixtures: flow.highlightFixtures,
           seedMem: () => seedMemForFlow(mem, flow.blocks(), seg.json, seg.ref),
         });
       } else {
@@ -2195,6 +2386,7 @@ async function main() {
         flowMeta.push({
           episodeNumber: undefined,
           episodeTitle: undefined,
+          highlightFixtures: undefined,
           seedMem: () => seedMemForBlock(mem, r, seg.json),
         });
       }
@@ -2216,6 +2408,7 @@ async function main() {
         resetSession: bi.resetSessionBefore === true,
         episodeNumber: meta.episodeNumber,
         episodeTitle: meta.episodeTitle,
+        highlightFixtures: meta.highlightFixtures,
         expectedFailureReason:
           meta.expectedFailureReason && remainingInFlow === 1 ? meta.expectedFailureReason : undefined,
         seedMem: isFirstOfSegment ? meta.seedMem : undefined,

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.9",
+  "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.9"
+    "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: {},
   },
 });

package/templates/quickstart/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/templates/scaffold/package.json

@@ -18,7 +18,7 @@
     "baseUrl": "https://example.com"
   },
   "dependencies": {
-    "waygraph": "^0.10.9"
+    "waygraph": "^0.11.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",