waygraph 0.10.8 → 0.11.0

package/dist/cli.js

@@ -4,7 +4,7 @@
  *
  * Primary verbs (less is more):
  *   auto   Explore picker; `.flow.ts` / `--blocks From To` = run that path
- *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--auto-play-video`
+ *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
  * Also: list / nav / validate / check / graph / init / try
@@ -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
@@ -469,12 +475,16 @@ const RING_CSS =
   "@keyframes wg-ep-enter{0%{box-shadow:0 0 0 0 rgba(124,58,237,.55);}" +
   "100%{box-shadow:0 0 0 10px rgba(124,58,237,0);}}" +
   "#wg-episodes .wg-ep-entered{border-radius:6px;animation:wg-ep-enter 1.1s ease-out;}" +
-  // The block breadcrumb below it is scoped to the CURRENT episode's own
-  // blocks only, not the whole chain - "in episode 2 it shows 2nd to the
-  // last... it should start from the first block" (Dan). An ad hoc block
-  // chain with no episodes still shows the whole chain here, unchanged.
-  "#wg-modules{display:flex;flex-wrap:wrap;gap:6px;margin:0 0 10px;}" +
-  "#wg-modules .wg-mod{padding:3px 9px;border-radius:6px;font:600 11px system-ui,sans-serif;}" +
+  // Block strip: carousel (default) or classic wrap (--full).
+  "#wg-modules.wg-modules-carousel{display:flex;flex-wrap:nowrap;gap:8px;margin:0 0 10px;" +
+  "overflow-x:auto;scroll-snap-type:x mandatory;-webkit-overflow-scrolling:touch;" +
+  "padding:4px 2px 8px;scrollbar-width:thin;}" +
+  "#wg-modules.wg-modules-carousel .wg-mod{flex:0 0 auto;scroll-snap-align:center;" +
+  "padding:6px 12px;border-radius:999px;font:600 12px system-ui,sans-serif;}" +
+  "#wg-modules.wg-modules-carousel .wg-mod-current{transform:scale(1.06);" +
+  "box-shadow:0 0 0 2px rgba(124,58,237,.45);}" +
+  "#wg-modules.wg-modules-full{display:flex;flex-wrap:wrap;gap:6px;margin:0 0 10px;}" +
+  "#wg-modules.wg-modules-full .wg-mod{padding:3px 9px;border-radius:6px;font:600 11px system-ui,sans-serif;}" +
   "#wg-modules .wg-mod-done{background:#2a1650;color:#9a7ad1;}" +
   "#wg-modules .wg-mod-current{background:#7C3AED;color:#fff;}" +
   "#wg-modules .wg-mod-upcoming{background:transparent;color:#5a4a80;border:1px solid #3a2a60;}" +
@@ -525,22 +535,23 @@ const RING_CSS =
   "#wg-panel .wg-expected-heading{color:#ffcf7a;}" +
   "#wg-panel .wg-expected-reason{font:600 12.5px/1.5 system-ui,sans-serif;background:#2a2410;" +
   "color:#ffe6ae;border-radius:8px;padding:10px;margin:0 0 8px;}" +
-  // Hide / Show chrome + mobile bottom-sheet layout (Dan: stepper + auto panels).
+  // Hide / Show chrome: collapsed = compact "N / M · block" pill (not empty chrome).
   "#wg-panel .wg-chrome{display:flex;align-items:center;justify-content:space-between;gap:8px;margin:0 0 8px;}" +
   "#wg-panel .wg-chrome-title{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
   "letter-spacing:.04em;text-transform:uppercase;}" +
   "#wg-panel button.wg-hide-btn{margin:0;padding:4px 10px;font:600 11px system-ui,sans-serif;" +
   "background:#3a2a60;color:#e8dcff;border:1px solid #5b3aa8;border-radius:6px;cursor:pointer;}" +
   "#wg-panel button.wg-hide-btn:hover{background:#4b2a80;}" +
-  "#wg-panel.wg-collapsed{width:auto;max-width:90vw;padding:8px 12px;max-height:none;overflow:hidden;}" +
+  "#wg-panel.wg-collapsed{width:auto;max-width:92vw;padding:8px 12px;max-height:none;overflow:hidden;}" +
   "#wg-panel.wg-collapsed .wg-body{display:none;}" +
   "#wg-panel.wg-collapsed .wg-chrome{margin:0;}" +
+  "#wg-panel.wg-collapsed .wg-chrome-title{font:700 13px/1.25 system-ui,sans-serif;color:#fff;" +
+  "letter-spacing:0;text-transform:none;}" +
   "@media (max-width:640px){" +
   "#wg-panel{left:8px;right:8px;bottom:8px;transform:none;max-width:none;width:auto;" +
   "max-height:min(55vh,calc(100vh - 16px));padding:12px 14px;border-radius:12px;}" +
   "#wg-panel.wg-collapsed{left:50%;right:auto;transform:translateX(-50%);width:auto;}" +
   "#wg-episodes{overflow-x:auto;-webkit-overflow-scrolling:touch;flex-wrap:nowrap;}" +
-  "#wg-modules{gap:4px;}" +
   "#wg-panel .wg-narration{font-size:13px;}" +
   "#wg-panel button{width:100%;}" +
   "#wg-panel .wg-error-actions{flex-direction:column;}" +
@@ -736,8 +747,11 @@ async function installOverlay(page, title) {
         }
         if (iconLink.href !== favicon) iconLink.href = favicon;
         // Hide/Show for #wg-panel - call after every panel.innerHTML refresh.
-        window.__wgWirePanelChrome = (panel, storageKey, chromeTitle) => {
+        // Collapsed title shows "N / M · block" (compact progress). forceCollapsed
+        // is for auto-next navs / video - does not overwrite the user's Hide preference.
+        window.__wgWirePanelChrome = (panel, storageKey, chromeTitle, opts) => {
           if (!panel) return;
+          opts = opts || {};
           if (!panel.querySelector(":scope > .wg-chrome")) {
             const body = document.createElement("div");
             body.className = "wg-body";
@@ -757,31 +771,56 @@ async function installOverlay(page, title) {
             panel.appendChild(chrome);
             panel.appendChild(body);
           }
-          const apply = (hidden) => {
+          const stepLabel = opts.stepLabel || panel.dataset.wgStepLabel || "";
+          if (stepLabel) panel.dataset.wgStepLabel = stepLabel;
+          const apply = (hidden, persist) => {
             panel.classList.toggle("wg-collapsed", hidden);
             const t = panel.querySelector("[data-wg-toggle]");
+            const titleEl = panel.querySelector(".wg-chrome-title");
+            const label = panel.dataset.wgStepLabel || stepLabel;
+            if (titleEl) {
+              titleEl.textContent = hidden
+                ? (label || chromeTitle || "waygraph demo")
+                : (chromeTitle || "waygraph demo");
+            }
             if (t) t.textContent = hidden ? "Show" : "Hide";
-            try {
-              localStorage.setItem(storageKey, hidden ? "1" : "0");
-            } catch {
-              /* private mode */
+            if (persist !== false) {
+              try {
+                localStorage.setItem(storageKey, hidden ? "1" : "0");
+              } catch {
+                /* private mode */
+              }
             }
           };
           let hidden = false;
-          try {
-            hidden = localStorage.getItem(storageKey) === "1";
-          } catch {
-            /* ignore */
+          if (opts.forceCollapsed === true) {
+            hidden = true;
+          } else if (opts.forceCollapsed === false) {
+            hidden = false;
+          } else {
+            try {
+              hidden = localStorage.getItem(storageKey) === "1";
+            } catch {
+              /* ignore */
+            }
           }
-          apply(hidden);
+          apply(hidden, opts.forceCollapsed === true ? false : true);
           const toggle = panel.querySelector("[data-wg-toggle]");
           if (toggle && !toggle.dataset.wgWired) {
             toggle.dataset.wgWired = "1";
             toggle.addEventListener("click", (e) => {
               e.stopPropagation();
-              apply(!panel.classList.contains("wg-collapsed"));
+              apply(!panel.classList.contains("wg-collapsed"), true);
             });
           }
+          const cur = panel.querySelector("#wg-modules .wg-mod-current");
+          if (cur && typeof cur.scrollIntoView === "function") {
+            try {
+              cur.scrollIntoView({ inline: "center", block: "nearest", behavior: "smooth" });
+            } catch {
+              cur.scrollIntoView(false);
+            }
+          }
         };
       },
       { title, favicon: WAYGRAPH_FAVICON, bannerPos, envAutoplay },
@@ -850,6 +889,7 @@ async function renderBeforeStep(page, info) {
       // step's position WITHIN that subset, not the whole chain's index -
       // "in episode 2 it shows 2nd to the last... it should start from the
       // first block" (Dan).
+      const modulesClass = info.stepperMode === "full" ? "wg-modules-full" : "wg-modules-carousel";
       const modulesHtml = info.allNames
         .map((name, idx) => {
           const cls = idx < info.moduleIndex ? "wg-mod-done" : idx === info.moduleIndex ? "wg-mod-current" : "wg-mod-upcoming";
@@ -864,7 +904,7 @@ async function renderBeforeStep(page, info) {
       let html =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         episodesHtml +
-        "<div id=\\"wg-modules\\">" + modulesHtml + "</div>" +
+        "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
         narrationHtml;
       if (info.keys.length === 0) {
@@ -897,7 +937,12 @@ async function renderBeforeStep(page, info) {
         document.documentElement.appendChild(panel);
         requestAnimationFrame(() => panel.classList.add("wg-in"));
       }
-      if (window.__wgWirePanelChrome) window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo");
+      if (window.__wgWirePanelChrome) {
+        window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
+          stepLabel: (info.index + 1) + " / " + info.total + (info.blockName ? " · " + info.blockName : ""),
+          forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
+        });
+      }
       // Live, human-readable preview of what a MemKey's raw JSON will
       // actually write - object fields become "Field: value" lines
       // (camelCase split the same way state tags already are); a
@@ -1040,6 +1085,7 @@ async function renderAfterStep(page, info) {
         : "Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + " done";
       const buttonLabel = info.isLast ? "Finish" : "Next \\u25B6";
       const escA = (s) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+      const modulesClass = info.stepperMode === "full" ? "wg-modules-full" : "wg-modules-carousel";
       const modulesHtml = info.allNames
         .map((name, idx) => {
           const cls = idx <= info.moduleIndex ? "wg-mod-done" : "wg-mod-upcoming";
@@ -1094,7 +1140,7 @@ async function renderAfterStep(page, info) {
       panel.innerHTML =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         episodesHtml +
-        "<div id=\\"wg-modules\\">" + modulesHtml + "</div>" +
+        "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>" + heading + "</h3>" +
         resultHtml +
         gateHtml;
@@ -1102,7 +1148,12 @@ async function renderAfterStep(page, info) {
         document.documentElement.appendChild(panel);
         requestAnimationFrame(() => panel.classList.add("wg-in"));
       }
-      if (window.__wgWirePanelChrome) window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo");
+      if (window.__wgWirePanelChrome) {
+        window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
+          stepLabel: (info.index + 1) + " / " + info.total + (info.blockName ? " · " + info.blockName : ""),
+          forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
+        });
+      }
       panel.querySelectorAll(".wg-toggle-btn").forEach((btn) => {
         btn.addEventListener("click", () => {
           const wantPretty = btn.getAttribute("data-mode") === "pretty";
@@ -1169,6 +1220,7 @@ async function renderStepError(page, info) {
             .join("") +
           "</div>"
         : "";
+      const modulesClass = info.stepperMode === "full" ? "wg-modules-full" : "wg-modules-carousel";
       const modulesHtml = info.allNames
         .map((name, idx) => {
           const cls = idx === info.moduleIndex ? "wg-mod-current" : idx < info.moduleIndex ? "wg-mod-done" : "wg-mod-upcoming";
@@ -1186,7 +1238,7 @@ async function renderStepError(page, info) {
         : "";
       panel.innerHTML =
         episodesHtml +
-        "<div id=\\"wg-modules\\">" + modulesHtml + "</div>" +
+        "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3 class=\\"" + (isExpected ? "wg-expected-heading" : "wg-error-heading") + "\\">" + headingText + "</h3>" +
         reasonHtml +
         "<div class=\\"wg-error-msg\\">" + esc(info.message) + "</div>" +
@@ -1198,7 +1250,12 @@ async function renderStepError(page, info) {
         document.documentElement.appendChild(panel);
         requestAnimationFrame(() => panel.classList.add("wg-in"));
       }
-      if (window.__wgWirePanelChrome) window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo");
+      if (window.__wgWirePanelChrome) {
+        window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
+          stepLabel: (info.index + 1) + " / " + info.total + (info.blockName ? " · " + info.blockName : ""),
+          forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
+        });
+      }
       const runBtn = document.getElementById("wg-run");
       if (runBtn) runBtn.addEventListener("click", () => window.__wgNext({}));
       const retryBtn = document.getElementById("wg-error-retry");
@@ -1308,6 +1365,9 @@ async function markStepRunning(page, opts) {
           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) })
@@ -1325,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(() => {
@@ -1401,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
@@ -1415,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
@@ -1451,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));
@@ -1506,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
           }
@@ -1517,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
@@ -1644,8 +1865,13 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   // own added dwell while the rest of the chain keeps the full theatrical
   // pace. Playwright's own slowMo is process-wide and untouched by this -
   // only OUR added pauses (ring pop, cursor travel, typing delay) shrink.
-  const pacing = { fast: false };
-  instrumentInteractionHighlighting(page, mem, slowMo, pacing);
+  // --fast / WAYGRAPH_DEMO_FAST: every step uses fast interaction pacing + shorter gates.
+  // WAYGRAPH_FAST_BLOCKS still names per-block overrides when --fast is off.
+  const demoFast = process.env.WAYGRAPH_DEMO_FAST === "1";
+  const stepperMode = process.env.WAYGRAPH_STEPPER === "full" ? "full" : "carousel";
+  const pacing = { fast: demoFast };
+  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
@@ -1689,7 +1915,11 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   // which way the checkbox is set. That's the hybrid Dan asked for: some
   // steps auto-advance, some get a manual click, toggled as the demo goes,
   // not fixed for the whole run from a single env var.
-  const autoplayMs = process.env.WAYGRAPH_AUTOPLAY_MS ? Number(process.env.WAYGRAPH_AUTOPLAY_MS) : 1800;
+  const autoplayMs = process.env.WAYGRAPH_AUTOPLAY_MS
+    ? Number(process.env.WAYGRAPH_AUTOPLAY_MS)
+    : demoFast
+      ? 450
+      : 1800;
   const currentAutoplay = () =>
     page
       .evaluate(() => {
@@ -1789,7 +2019,14 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     if ((clearSession || r.resetSession) && i > 0) {
       await resetPageState(context, page, baseURL);
     }
-    pacing.fast = fastBlockNames.has(r.block.name);
+    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.
+    // Video recording still collapses every step.
+    const forceCollapsed = !!process.env.WAYGRAPH_VIDEO || (autoNow && isNavBlock);
     const requires = r.block.requires ?? [];
     const keys = requires.map((k) => {
       let value = "<not yet set>";
@@ -1814,6 +2051,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       title,
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
+      stepperMode,
+      forceCollapsed,
     });
     const edits = await gate();
     for (const k of requires) {
@@ -1826,7 +2065,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       }
     }
     const recordingVideo = !!process.env.WAYGRAPH_VIDEO;
-    const autoCollapsePanel = recordingVideo || (await currentAutoplay());
+    const autoCollapsePanel = recordingVideo || (await currentAutoplay() && isNavBlock) || forceCollapsed;
     await markStepRunning(page, { autoCollapsePanel });
     // NavBlock click-nav: label the upcoming Locator.click demo cursor as
     // "nav: <block>" so pia/demo watchers see cursor+pulse on click nav
@@ -1876,6 +2115,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         episodeNumber: r.episodeNumber,
         episodeTitle: r.episodeTitle,
         expectedFailureReason: r.expectedFailureReason,
+        stepperMode,
+        forceCollapsed: false,
       });
       const errEdits = await gate();
       if (errEdits && errEdits.__wgRetry) {
@@ -1904,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,
@@ -1920,6 +2180,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       title,
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
+      stepperMode,
+      // After a nav under auto-next, stay compact until the next action block expands.
+      forceCollapsed: !!process.env.WAYGRAPH_VIDEO || ((await currentAutoplay()) && isNavBlock),
     });
     await gate();
   }
@@ -2052,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
@@ -2113,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 {
@@ -2121,6 +2386,7 @@ async function main() {
         flowMeta.push({
           episodeNumber: undefined,
           episodeTitle: undefined,
+          highlightFixtures: undefined,
           seedMem: () => seedMemForBlock(mem, r, seg.json),
         });
       }
@@ -2142,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,
@@ -2840,6 +3107,12 @@ function parseRunFlags(argv) {
         else if (a === "--auto-play-video") {
             out.autoPlayVideo = true;
         }
+        else if (a === "--fast") {
+            out.fast = true;
+        }
+        else if (a === "--full") {
+            out.fullStepper = true;
+        }
         else if (a === "--non-headless") {
             out.nonHeadless = true;
         }
@@ -2945,6 +3218,10 @@ function applyRunFlags(flags, opts) {
         if (flags.step === undefined)
             flags.step = true;
     }
+    if ((flags.fast || flags.fullStepper) && !opts?.allowDemoUi) {
+        console.error("waygraph: --fast / --full are demo-only flags");
+        process.exit(1);
+    }
     if (flags.step === true) {
         process.env.WAYGRAPH_STEP = "1";
         process.env.WAYGRAPH_HEADED = "1";
@@ -2980,6 +3257,12 @@ function applyRunFlags(flags, opts) {
     if (flags.data !== undefined) {
         process.env.WAYGRAPH_DATA = flags.data;
     }
+    if (flags.fast) {
+        process.env.WAYGRAPH_DEMO_FAST = "1";
+    }
+    if (flags.fullStepper) {
+        process.env.WAYGRAPH_STEPPER = "full";
+    }
 }
 /**
  * BASE_URL when neither --base-url nor WAYGRAPH_BASE_URL is set:
@@ -3135,6 +3418,8 @@ Primary (less is more):
   waygraph demo  [--blocks <flow|file|spec>]  Watch with step overlay (QA path)
                  --data '{...}'            Mem seed JSON (or inline flow({...}))
                  --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)
                  --video-viewport WxH       Recording size (default demo: 1920x1080)
                  --title / --base-url
@@ -3155,7 +3440,8 @@ Examples:
   waygraph list                                          # file → export map
   waygraph run src/flows/shop.flow.ts --data '{...}'
   waygraph run --blocks shopFlow --non-headless --video
-  waygraph demo --blocks src/flows/cart-bulk.flow.ts --auto-next
+  waygraph demo --blocks src/flows/cart-bulk.flow.ts --auto-next --fast
+  waygraph demo src/flows/shop.flow.ts --full
   waygraph try auto
   waygraph try auto:cli
   waygraph auto src/flows/shop.flow.ts --data '{...}'   # run by file (same as run)
@@ -3168,6 +3454,7 @@ Aliases (compat): \`chain <spec>\` -> run --blocks; \`chain auto A B\` -> auto -
 
 Project path optional (defaults to cwd). Flags beat WAYGRAPH_* env.
 \`run\`/\`demo\`/\`auto\`: Flow export, .flow.ts path, or "a then b" chain (auto also explores).
+Hide stepper = compact "N / M · block" pill. Auto-next auto-hides on NavBlocks.
 `);
     process.exit(0);
 }
@@ -3282,13 +3569,13 @@ async function main() {
         }
         case "demo": {
             const flags = parseRunFlags(args.slice(1));
-            applyRunFlags(flags, { allowAutoPlayVideo: true });
+            applyRunFlags(flags, { allowAutoPlayVideo: true, allowDemoUi: true });
             const spec = resolveSpec(flags);
             if (!spec) {
                 console.error("waygraph demo: missing flow/spec — e.g.\n" +
                     "  waygraph demo src/flows/shop.flow.ts\n" +
                     "  waygraph demo --blocks shopFlow\n" +
-                    "  Flags: --blocks --data --auto-next --auto-play-video --title --base-url --video");
+                    "  Flags: --blocks --data --auto-next --fast --full --auto-play-video --title --base-url --video");
                 process.exit(1);
             }
             const proj = flags.blocks