waygraph 0.10.9 → 0.11.1

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
@@ -1337,12 +1343,18 @@ function extractVerifyHighlights(block, resultTag) {
  * __wgNext no-ops once already consumed - but looked live when it wasn't).
  * Disables the button and mem-key textareas, and swaps whichever gate
  * text was showing (manual button or "Auto-advancing...") to "Running...".
- * When autoCollapsePanel is set (QA video / autoplay), tuck the stepper
- * away so ring captions + the app fill the frame - Dan: stepper + auto panels.
+ * ALWAYS collapses the panel while act() runs - leaving it expanded was a
+ * real bug: #wg-panel sits at z-index max with pointer-events:auto, so
+ * Playwright's login/add-to-cart clicks hit the stepper instead of the app
+ * ("subtree intercepts pointer events"). Empty/partial fills + a lucky
+ * edge click on Login then produced Sauce Demo's Epic sadface, verify
+ * still passed on the error banner, and the next block blew up. Collapse
+ * also matches Dan's "step is running / can't interrupt" ask. (_opts kept
+ * for call-site compat; autoCollapsePanel is now unconditional.)
  */
-async function markStepRunning(page, opts) {
+async function markStepRunning(page, _opts) {
   await page
-    .evaluate(({ autoCollapsePanel }) => {
+    .evaluate(() => {
       const runBtn = document.getElementById("wg-run");
       if (runBtn) {
         runBtn.disabled = true;
@@ -1353,18 +1365,16 @@ async function markStepRunning(page, opts) {
       document.querySelectorAll("#wg-panel textarea[data-key]").forEach((ta) => {
         ta.disabled = true;
       });
-      if (autoCollapsePanel) {
-        const panel = document.getElementById("wg-panel");
-        if (panel) {
-          panel.classList.add("wg-collapsed");
-          const toggle = panel.querySelector("[data-wg-toggle]");
-          if (toggle) toggle.textContent = "Show";
-          const titleEl = panel.querySelector(".wg-chrome-title");
-          const label = panel.dataset.wgStepLabel;
-          if (titleEl && label) titleEl.textContent = label;
-        }
+      const panel = document.getElementById("wg-panel");
+      if (panel) {
+        panel.classList.add("wg-collapsed");
+        const toggle = panel.querySelector("[data-wg-toggle]");
+        if (toggle) toggle.textContent = "Show";
+        const titleEl = panel.querySelector(".wg-chrome-title");
+        const label = panel.dataset.wgStepLabel;
+        if (titleEl && label) titleEl.textContent = label;
       }
-    }, { autoCollapsePanel: !!(opts && opts.autoCollapsePanel) })
+    })
     .catch(() => {});
 }
 
@@ -1379,6 +1389,210 @@ 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.
+ *
+ * Advance wait does NOT use exposeFunction/gate(): after a real navigation
+ * (e.g. finish-order -> checkout-complete) the panel can render while
+ * __wgNext is momentarily wedged, which left "Next slide" looking live but
+ * doing nothing. In-page data-wg-acked + autoplay poll is the source of truth.
+ */
+async function presentSlides(page, slides, _gate, opts) {
+  const title = (opts && opts.title) || "waygraph demo";
+  const blockName = (opts && opts.blockName) || "";
+  const episodeNumber = opts && opts.episodeNumber;
+  const episodeTitle = (opts && opts.episodeTitle) || "";
+  const autoplayMs =
+    opts && opts.autoplayMs
+      ? Number(opts.autoplayMs)
+      : process.env.WAYGRAPH_AUTOPLAY_MS
+        ? Number(process.env.WAYGRAPH_AUTOPLAY_MS)
+        : 1800;
+  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;");
+        const episodeLine =
+          info.episodeNumber !== undefined && info.episodeNumber !== null
+            ? "<div class=\\"wg-episode\\">Episode " +
+              info.episodeNumber +
+              (info.episodeTitle ? ": " + esc(info.episodeTitle) : "") +
+              " · yap slides</div>"
+            : "";
+        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\\">" +
+          episodeLine +
+          "<h3>Slide " +
+          (info.index + 1) +
+          " / " +
+          info.total +
+          (info.blockName ? " · " + esc(info.blockName) : "") +
+          "</h3>" +
+          (info.tag
+            ? "<div 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 type=\\"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,
+          });
+        }
+        let autoNow = false;
+        try {
+          autoNow = localStorage.getItem("wg-autoplay") === "1";
+        } catch {
+          /* ignore */
+        }
+        const cb = document.getElementById("wg-autoplay-cb");
+        if (cb) {
+          cb.checked = autoNow;
+          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 manual = document.getElementById("wg-gate-manual");
+        const auto = document.getElementById("wg-gate-auto");
+        if (manual) manual.style.display = autoNow ? "none" : "";
+        if (auto) auto.style.display = autoNow ? "" : "none";
+        const runBtn = document.getElementById("wg-run");
+        if (runBtn) {
+          runBtn.removeAttribute("data-wg-acked");
+          runBtn.addEventListener(
+            "click",
+            (e) => {
+              e.preventDefault();
+              e.stopPropagation();
+              runBtn.setAttribute("data-wg-acked", "1");
+            },
+            { once: true },
+          );
+        }
+      },
+      {
+        index: i,
+        total: slides.length,
+        caption: s.caption,
+        detail: s.detail || "",
+        tag: s.tag || "",
+        blockName,
+        isLast,
+        autoNow: false,
+        episodeNumber: episodeNumber !== undefined ? episodeNumber : null,
+        episodeTitle,
+      },
+    );
+    const started = Date.now();
+    for (;;) {
+      const acked = await page
+        .evaluate(() => {
+          const btn = document.getElementById("wg-run");
+          return !!(btn && btn.getAttribute("data-wg-acked") === "1");
+        })
+        .catch(() => false);
+      if (acked) break;
+      const auto = await page
+        .evaluate(() => {
+          try {
+            return localStorage.getItem("wg-autoplay") === "1";
+          } catch {
+            return false;
+          }
+        })
+        .catch(() => false);
+      if (auto && Date.now() - started >= autoplayMs) break;
+      await new Promise((res) => setTimeout(res, 100));
+    }
+  }
+  await hideRing(page);
+}
+
 async function hideRing(page) {
   await page
     .evaluate(() => {
@@ -1455,7 +1669,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 +1683,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 +1720,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 +1777,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 +1788,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 +1922,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
@@ -1733,14 +1953,34 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   // already is.
   page.setViewportSize = async () => {};
   let resolveNext = null;
+  // Render-to-gate race: a slide/step panel's Next button is wired to
+  // window.__wgNext BEFORE gate() calls waitForNext() (there is at least
+  // one more await - the autoplay-sync evaluate - in between on the
+  // presentSlides path). A click landing in that small window used to be
+  // dropped silently (resolveNext was still null) - the panel then looked
+  // "stuck" forever since gate() started listening AFTER the click already
+  // fired and no second click ever came. Queue it instead: the very next
+  // waitForNext() call picks up a pending click immediately.
+  let pendingNext = null;
   await page.exposeFunction("__wgNext", (edits) => {
     if (resolveNext) {
       const r = resolveNext;
       resolveNext = null;
       r(edits);
+    } else {
+      pendingNext = edits;
     }
   });
-  const waitForNext = () => new Promise((res) => (resolveNext = res));
+  const waitForNext = () =>
+    new Promise((res) => {
+      if (pendingNext !== null) {
+        const edits = pendingNext;
+        pendingNext = null;
+        res(edits);
+        return;
+      }
+      resolveNext = res;
+    });
   // WAYGRAPH_AUTOPLAY=1 only sets the STARTING checkbox state now - the
   // panel's own "Auto-advance" checkbox can flip it live, mid-run, and a
   // manual click always wins over an in-flight autoplay wait regardless of
@@ -1852,6 +2092,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 +2217,29 @@ 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,
+        episodeNumber: r.episodeNumber,
+        episodeTitle: r.episodeTitle,
+        autoplayMs,
+      });
+    }
+    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 +2390,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 +2452,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 +2461,7 @@ async function main() {
         flowMeta.push({
           episodeNumber: undefined,
           episodeTitle: undefined,
+          highlightFixtures: undefined,
           seedMem: () => seedMemForBlock(mem, r, seg.json),
         });
       }
@@ -2216,6 +2483,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,
@@ -2233,8 +2501,13 @@ async function main() {
     }
   }
   const step = process.env.WAYGRAPH_STEP === "1";
-  // Stepping through headless defeats the point - a human can't watch it.
-  const headed = process.env.WAYGRAPH_HEADED === "1" || step;
+  // Stepping through headless defeats the point for a MANUAL demo - a
+  // human can't watch it. But an explicit WAYGRAPH_HEADED=0 always wins
+  // over that default: --auto-play-video sets STEP=1 (it still needs the
+  // overlay/narration machinery) AND HEADED=0 (unattended + recorded,
+  // nobody has to watch a live window for it to be right).
+  const headed =
+    process.env.WAYGRAPH_HEADED === "0" ? false : process.env.WAYGRAPH_HEADED === "1" || step;
   // Step mode defaults to a visible pace (each fill/click actually shows on
   // screen instead of snapping in) unless the human overrides it - an
   // explicit WAYGRAPH_SLOWMO=0 still means "off".
@@ -2622,13 +2895,23 @@ async function runTryDemo() {
     if (!destDir)
         return;
     process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
-    // Default: headed stepper, manual Next. --video records that session (not headless rush).
-    process.env.WAYGRAPH_HEADED ??= "1";
     process.env.WAYGRAPH_STEP ??= "1";
     process.env.WAYGRAPH_AUTOPLAY ??= "0";
-    // Explicit --no-step --video = unattended headless .webm only.
-    if (process.env.WAYGRAPH_VIDEO && process.env.WAYGRAPH_STEP === "0") {
+    // Explicit --no-step --video = unattended headless .webm only (the
+    // documented cloud/CI recipe above) - nobody needs to watch a live
+    // window for Playwright's own recordVideo to capture the right thing.
+    // This must be decided BEFORE the headed default below, or the
+    // unconditional "??=" there always wins and the documented recipe never
+    // actually runs headless.
+    const unattendedVideo = Boolean(process.env.WAYGRAPH_VIDEO) && process.env.WAYGRAPH_STEP === "0";
+    if (unattendedVideo) {
         process.env.WAYGRAPH_AUTOPLAY ??= "1";
+        process.env.WAYGRAPH_HEADED ??= "0";
+    }
+    else {
+        // Default: headed stepper, manual Next. --video records that session
+        // too (not a headless rush) as long as --step is still on.
+        process.env.WAYGRAPH_HEADED ??= "1";
     }
     const videoTo = process.env.WAYGRAPH_VIDEO;
     console.log(videoTo
@@ -2914,6 +3197,10 @@ function parseRunFlags(argv) {
         else if (a === "--auto-play-video") {
             out.autoPlayVideo = true;
         }
+        else if (a === "--auto-play-video-head") {
+            out.autoPlayVideo = true;
+            out.nonHeadless = true;
+        }
         else if (a === "--fast") {
             out.fast = true;
         }
@@ -3022,8 +3309,16 @@ function applyRunFlags(flags, opts) {
             flags.autoplay = true;
         if (flags.video === undefined)
             flags.video = "";
-        if (flags.step === undefined)
-            flags.step = true;
+        // Overlay narration (captions/rings/slides) needs step mode to run, but
+        // --auto-play-video is unattended-and-recorded by design - no human
+        // has to watch a live window for Playwright's own recordVideo to
+        // capture the right thing. Headless by default; --non-headless (or the
+        // --auto-play-video-head alias, parsed above) opts back into a
+        // visible browser for someone who wants to watch it live too.
+        process.env.WAYGRAPH_STEP = "1";
+        if (!flags.nonHeadless && process.env.WAYGRAPH_HEADED === undefined) {
+            process.env.WAYGRAPH_HEADED = "0";
+        }
     }
     if ((flags.fast || flags.fullStepper) && !opts?.allowDemoUi) {
         console.error("waygraph: --fast / --full are demo-only flags");
@@ -3227,7 +3522,8 @@ Primary (less is more):
                  --auto-next               Auto-advance steps (alias: --autoplay)
                  --fast                    Faster transitions + shorter auto-next gates
                  --full                    Classic wrap-all block chips (default: carousel)
-                 --auto-play-video         QA: --auto-next + --video (+ step)
+                 --auto-play-video         Unattended + recorded: --auto-next + --video (+ step); headless by default
+                 --auto-play-video-head    Same, but keep the browser visible (--non-headless)
                  --video-viewport WxH       Recording size (default demo: 1920x1080)
                  --title / --base-url
   waygraph run   [--blocks <flow|file|spec>]  Execute (no overlay unless --step)

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 } : {}),
         },
     });