waygraph 0.12.42 → 0.12.43

package/README.md

@@ -3,7 +3,7 @@
 A typed graph of reusable Blocks for driving a browser through E2E flows, in place of a
 flat pile of ad hoc helper functions.
 
-**Current:** `0.10.9` — demo carousel stepper (default), `--fast` / `--full`, Hide = compact `N / M`.
+**Current:** `0.12.43` — overlay beacons (blind-agent gate), expected-failure panel on branched LoginPage, `--mini`, Hide stickiness.
 
 This repo is the `waygraph` npm package itself. The full live **Sauce Demo** example
 (Page inventory hub, Effect Add/Remove, MemNav Open details, `waygraph auto`) ships
@@ -429,6 +429,25 @@ npm run test        # playwright test
 npm run build       # tsc -p tsconfig.build.json, emits dist/
 ```
 
+### Blind-agent overlay gate (anti-blank)
+
+Every live modal (`#wg-panel`, `#wg-banner`, `#wg-auto-panel`) stamps
+`data-wg-ui` / `data-wg-modal` / `data-wg-ready="1"`. Do **not** claim the
+stepper works unless one of these passes:
+
+```bash
+# Playwright helper (exported from waygraph)
+import { assertWgOverlayReady } from "waygraph";
+await assertWgOverlayReady(page); // throws on blank / opacity-0 / missing stamp
+
+# Live demo prove (exit 0 = painted, exit 2 = blank)
+WAYGRAPH_PROVE_EXIT=1 WAYGRAPH_PROVE_SHOT=/tmp/wg.png \
+  waygraph demo --blocks loginFlow --data '...'
+# stderr: WAYGRAPH_PROVE {"ok":true,"beacons":[...],"readyAttr":"1"}
+```
+
+Tests: `tests/cli/overlay-beacon.spec.ts`. Helpers: `src/overlay-beacon.ts`.
+
 ## Layout
 
 ```

package/dist/auto-explore-run.js

@@ -177,6 +177,19 @@ async function setAutoPanelRunning(page, label) {
         if (typeof window.__wgWirePanelChrome === "function") {
             window.__wgWirePanelChrome(panel, "wg-auto-panel-hidden", "waygraph auto");
         }
+        if (typeof window.__wgStampModal === "function") {
+            window.__wgStampModal(panel, "auto-panel", {
+                phase: "running",
+                block: label,
+                ready: true,
+            });
+        }
+        else {
+            panel.setAttribute("data-wg-ui", "1");
+            panel.setAttribute("data-wg-modal", "auto-panel");
+            panel.setAttribute("data-wg-phase", "running");
+            panel.setAttribute("data-wg-ready", "1");
+        }
     }, label)
         .catch(() => { });
 }
@@ -399,6 +412,7 @@ async function headfulPick(page, menu, library, mem, waitPick) {
         }
         const apply = (hidden) => {
           el.classList.toggle("wg-collapsed", hidden);
+          el.setAttribute("data-wg-collapsed", hidden ? "1" : "0");
           const t = el.querySelector("[data-wg-toggle]");
           if (t) t.textContent = hidden ? "Show" : "Hide";
           try { localStorage.setItem(storageKey, hidden ? "1" : "0"); } catch {}
@@ -416,6 +430,41 @@ async function headfulPick(page, menu, library, mem, waitPick) {
         }
       };
       window.__wgWirePanelChrome(root, "wg-auto-panel-hidden", "waygraph auto");
+      if (typeof window.__wgStampModal === "function") {
+        window.__wgStampModal(root, "auto-panel", { phase: "pick", ready: true });
+      } else {
+        root.setAttribute("data-wg-ui", "1");
+        root.setAttribute("data-wg-modal", "auto-panel");
+        root.setAttribute("data-wg-phase", "pick");
+        root.setAttribute(
+          "data-wg-collapsed",
+          root.classList.contains("wg-collapsed") ? "1" : "0",
+        );
+        root.setAttribute("data-wg-ready", "1");
+        window.__wgOverlayBeacon =
+          window.__wgOverlayBeacon ||
+          (() =>
+            Array.from(document.querySelectorAll('[data-wg-ui="1"]')).map((el) => {
+              const r = el.getBoundingClientRect();
+              const st = getComputedStyle(el);
+              return {
+                id: el.id || null,
+                modal: el.getAttribute("data-wg-modal"),
+                ready: el.getAttribute("data-wg-ready") === "1",
+                phase: el.getAttribute("data-wg-phase"),
+                step: el.getAttribute("data-wg-step"),
+                block: el.getAttribute("data-wg-block"),
+                collapsed:
+                  el.getAttribute("data-wg-collapsed") === "1" ||
+                  el.classList.contains("wg-collapsed"),
+                opacity: st.opacity,
+                textLen: (el.innerText || "").trim().length,
+                w: Math.round(r.width),
+                h: Math.round(r.height),
+                visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
+              };
+            }));
+      }
       root.querySelectorAll("button[data-idx]").forEach((btn) => {
         btn.addEventListener("click", () => {
           const idx = Number(btn.getAttribute("data-idx"));

package/dist/cli.js

@@ -858,6 +858,47 @@ async function installOverlay(page, title) {
           document.head.appendChild(iconLink);
         }
         if (iconLink.href !== favicon) iconLink.href = favicon;
+        // Blind-agent overlay beacons: every modal root gets data-wg-ui /
+        // data-wg-modal / data-wg-ready so tests can fail on a blank panel.
+        window.__wgStampModal = (el, kind, meta) => {
+          if (!el) return;
+          meta = meta || {};
+          el.setAttribute("data-wg-ui", "1");
+          el.setAttribute("data-wg-modal", kind || "panel");
+          if (meta.phase != null) el.setAttribute("data-wg-phase", String(meta.phase));
+          if (meta.step != null) el.setAttribute("data-wg-step", String(meta.step));
+          if (meta.total != null) el.setAttribute("data-wg-total", String(meta.total));
+          if (meta.block != null) el.setAttribute("data-wg-block", String(meta.block));
+          el.setAttribute(
+            "data-wg-collapsed",
+            el.classList.contains("wg-collapsed") ? "1" : "0",
+          );
+          el.setAttribute("data-wg-ready", meta.ready === false ? "0" : "1");
+        };
+        window.__wgOverlayBeacon = () => {
+          return Array.from(document.querySelectorAll("[data-wg-ui=\\"1\\"]")).map((el) => {
+            const r = el.getBoundingClientRect();
+            const st = getComputedStyle(el);
+            return {
+              id: el.id || null,
+              modal: el.getAttribute("data-wg-modal"),
+              ready: el.getAttribute("data-wg-ready") === "1",
+              phase: el.getAttribute("data-wg-phase"),
+              step: el.getAttribute("data-wg-step"),
+              block: el.getAttribute("data-wg-block"),
+              collapsed:
+                el.getAttribute("data-wg-collapsed") === "1" ||
+                el.classList.contains("wg-collapsed"),
+              opacity: st.opacity,
+              textLen: (el.innerText || "").trim().length,
+              w: Math.round(r.width),
+              h: Math.round(r.height),
+              visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
+            };
+          });
+        };
+        const existingBanner = document.getElementById("wg-banner");
+        if (existingBanner) window.__wgStampModal(existingBanner, "banner", { ready: true });
         // Hide/Show for #wg-panel - call after every panel.innerHTML refresh.
         // Collapsed = "N / M · block" + Next (when not auto). Never pass
         // forceCollapsed:false - omit so Hide/localStorage wins.
@@ -937,6 +978,7 @@ async function installOverlay(page, title) {
           };
           const apply = (hidden, persist) => {
             panel.classList.toggle("wg-collapsed", hidden);
+            panel.setAttribute("data-wg-collapsed", hidden ? "1" : "0");
             const t = panel.querySelector("[data-wg-toggle]");
             const titleEl = panel.querySelector(".wg-chrome-title");
             const label = panel.dataset.wgStepLabel || stepLabel;
@@ -1027,6 +1069,8 @@ async function renderBeforeStep(page, info) {
       if (window.__wgHideCursor) window.__wgHideCursor();
     })
     .catch(() => {});
+  // miniStepLabel / todosHtmlFromInfo are Node-only — browser evaluate has no closure.
+  const payload = { ...info, stepLabel: miniStepLabel(info) };
   await page
     .evaluate((info) => {
       // Reused in place, not removed + recreated, every step - the old
@@ -1093,6 +1137,33 @@ async function renderBeforeStep(page, info) {
             esc(info.paceLabel || "") +
             "</span></div>"
           : "";
+      const todosHtml = (() => {
+        const list = info.todos || [];
+        if (!list.length) return "";
+        return (
+          '<ul id=\\"wg-todos\\">' +
+          list
+            .map((t) => {
+              const cls = t.current ? "wg-todo-current" : t.done ? "wg-todo-done" : "wg-todo-pending";
+              const mark = t.done
+                ? String.fromCharCode(0x2713)
+                : t.current
+                  ? String.fromCharCode(0x2192)
+                  : String.fromCharCode(0x25cb);
+              return (
+                '<li class=\\"' +
+                cls +
+                '\\"><span class=\\"wg-todo-mark\\">' +
+                mark +
+                '</span><span>' +
+                esc(t.text || "") +
+                "</span></li>"
+              );
+            })
+            .join("") +
+          "</ul>"
+        );
+      })();
       let html =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         episodesHtml +
@@ -1100,7 +1171,7 @@ async function renderBeforeStep(page, info) {
         "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
         narrationHtml +
-        todosHtmlFromInfo(info, esc);
+        todosHtml;
       if (info.keys.length === 0) {
         html += "<div class=\\"wg-key\\">(no MemKeys required)</div>";
       }
@@ -1130,13 +1201,24 @@ async function renderBeforeStep(page, info) {
       if (isNewPanel) {
         document.documentElement.appendChild(panel);
         requestAnimationFrame(() => panel.classList.add("wg-in"));
+      } else {
+        panel.classList.add("wg-in");
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel: miniStepLabel(info),
+          stepLabel: info.stepLabel || "",
           forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
+      if (window.__wgStampModal) {
+        window.__wgStampModal(panel, "panel", {
+          phase: "before",
+          step: info.index + 1,
+          total: info.total,
+          block: info.blockName || "",
+          ready: true,
+        });
+      }
       // 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
@@ -1206,8 +1288,40 @@ async function renderBeforeStep(page, info) {
           if (auto) auto.style.display = cb.checked ? "" : "none";
         });
       }
-    }, info)
+    }, payload)
     .catch(() => {});
+  if (process.env.WAYGRAPH_PROVE_SHOT || process.env.WAYGRAPH_PROVE_EXIT === "1") {
+    // Default: prove once on first painted panel. PROVE_EVERY=1 re-checks
+    // every step (noisy; useful when hunting a mid-chain blank).
+    const proveEvery = process.env.WAYGRAPH_PROVE_EVERY === "1";
+    const already = globalThis.__wgProveDone;
+    if (!already || proveEvery || process.env.WAYGRAPH_PROVE_EXIT === "1") {
+      await page.waitForTimeout(500).catch(() => {});
+      if (process.env.WAYGRAPH_PROVE_SHOT) {
+        await page.screenshot({ path: process.env.WAYGRAPH_PROVE_SHOT }).catch(() => {});
+      }
+      const ok = await page
+        .evaluate(() => {
+          const beacons =
+            typeof window.__wgOverlayBeacon === "function" ? window.__wgOverlayBeacon() : [];
+          const panel = beacons.find((b) => b.modal === "panel" && b.ready && b.visible);
+          const textOk = panel && panel.textLen >= 12;
+          const opacityOk = panel && Number(panel.opacity) > 0.5;
+          return {
+            ok: !!(panel && textOk && opacityOk),
+            beacons,
+            hasRun: !!document.getElementById("wg-run"),
+            readyAttr: document.getElementById("wg-panel")?.getAttribute("data-wg-ready") || null,
+          };
+        })
+        .catch((e) => ({ ok: false, reason: String(e && e.message ? e.message : e) }));
+      console.error("WAYGRAPH_PROVE " + JSON.stringify(ok));
+      globalThis.__wgProveDone = true;
+      if (process.env.WAYGRAPH_PROVE_EXIT === "1") {
+        process.exit(ok && ok.ok ? 0 : 2);
+      }
+    }
+  }
 }
 
 async function ensureSelectorInView(page, selector) {
@@ -1335,6 +1449,85 @@ function miniStepLabel(info) {
   );
 }
 
+/**
+ * stubOnError rings + amber "expected outcome" / red error panel, then wait
+ * for Stop/Retry. Used when a step throws OR when withExpectedFailure's last
+ * block succeeds on the intentional fail branch (e.g. LoginPage + error banner).
+ */
+async function presentFailPanel(page, opts) {
+  const {
+    block,
+    fixtures,
+    error,
+    index,
+    total,
+    blockName,
+    message,
+    allNames,
+    allDescriptions,
+    moduleIndex,
+    allEpisodes,
+    title,
+    episodeNumber,
+    episodeTitle,
+    expectedFailureReason,
+    stepperMode,
+    gatesFast,
+    demoPace,
+    gate,
+  } = opts;
+  if (hasAuthoredStubOnError(block, fixtures)) {
+    await page
+      .evaluate(() => {
+        if (window.__wgRingTrack) {
+          window.removeEventListener("resize", window.__wgRingTrack);
+          window.removeEventListener("scroll", window.__wgRingTrack, true);
+          window.__wgRingTrack = null;
+        }
+      })
+      .catch(() => {});
+    const errPhase = await runStubPhase(block, "stubOnError", {
+      fixtures,
+      error,
+      out: opts.out,
+    });
+    const errHighlights = errPhase.highlights.map((h) => {
+      const styled = applyHighlightStyleDefaults(h, opts.highlightStyle);
+      return {
+        selector: styled.selector,
+        label: formatHighlightCaption(styled),
+        duration: styled.duration,
+        fastMode: styled.fastMode,
+        tone: styled.tone,
+        size: styled.size,
+        weight: styled.weight,
+        zoom: styled.zoom,
+      };
+    });
+    await cycleHighlightRings(page, errHighlights, !!gatesFast, {
+      defaultHoldMs: 2000,
+      pace: demoPace,
+      todos: errPhase.todos,
+    });
+  }
+  await renderStepError(page, {
+    index,
+    total,
+    blockName,
+    message,
+    allNames,
+    allDescriptions,
+    moduleIndex,
+    allEpisodes,
+    title,
+    episodeNumber,
+    episodeTitle,
+    expectedFailureReason,
+    stepperMode,
+  });
+  return gate();
+}
+
 async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   const list = highlights || [];
   // defaultHoldMs: when set (fail path), use instead of legacy 900/200 so BUG
@@ -1447,7 +1640,9 @@ async function renderAfterStep(page, info) {
   // 900ms / 200ms holds when set.
   await cycleHighlightRings(page, highlights, gatesFast, {
     pace: info.pace,
+    stepLabel: miniStepLabel(info),
   });
+  const afterPayload = { ...info, stepLabel: miniStepLabel(info) };
   await page
     .evaluate((info) => {
       // Reused in place - see renderBeforeStep's own comment on this.
@@ -1525,25 +1720,63 @@ async function renderAfterStep(page, info) {
             escA(info.paceLabel || "") +
             "</span></div>"
           : "";
+      const todosHtml = (() => {
+        const list = info.todos || [];
+        if (!list.length) return "";
+        return (
+          '<ul id=\\"wg-todos\\">' +
+          list
+            .map((t) => {
+              const cls = t.current ? "wg-todo-current" : t.done ? "wg-todo-done" : "wg-todo-pending";
+              const mark = t.done
+                ? String.fromCharCode(0x2713)
+                : t.current
+                  ? String.fromCharCode(0x2192)
+                  : String.fromCharCode(0x25cb);
+              return (
+                '<li class=\\"' +
+                cls +
+                '\\"><span class=\\"wg-todo-mark\\">' +
+                mark +
+                '</span><span>' +
+                escA(t.text || "") +
+                "</span></li>"
+              );
+            })
+            .join("") +
+          "</ul>"
+        );
+      })();
       panel.innerHTML =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         episodesHtml +
         paceHtml +
         "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>" + heading + "</h3>" +
-        todosHtmlFromInfo(info, escA) +
+        todosHtml +
         resultHtml +
         gateHtml;
       if (isNewPanel) {
         document.documentElement.appendChild(panel);
         requestAnimationFrame(() => panel.classList.add("wg-in"));
+      } else {
+        panel.classList.add("wg-in");
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel: miniStepLabel(info),
+          stepLabel: info.stepLabel || "",
           forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
+      if (window.__wgStampModal) {
+        window.__wgStampModal(panel, "panel", {
+          phase: "after",
+          step: info.index + 1,
+          total: info.total,
+          block: info.blockName || "",
+          ready: true,
+        });
+      }
       panel.querySelectorAll(".wg-toggle-btn").forEach((btn) => {
         btn.addEventListener("click", () => {
           const wantPretty = btn.getAttribute("data-mode") === "pretty";
@@ -1570,7 +1803,7 @@ async function renderAfterStep(page, info) {
           if (auto) auto.style.display = cb.checked ? "" : "none";
         });
       }
-    }, info)
+    }, afterPayload)
     .catch(() => {});
 }
 
@@ -1582,6 +1815,7 @@ async function renderAfterStep(page, info) {
  */
 async function renderStepError(page, info) {
   await installOverlay(page, info.title);
+  const errorPayload = { ...info, stepLabel: miniStepLabel(info) };
   await page
     .evaluate((info) => {
       // Reused in place - see renderBeforeStep's own comment on this.
@@ -1639,18 +1873,29 @@ async function renderStepError(page, info) {
       if (isNewPanel) {
         document.documentElement.appendChild(panel);
         requestAnimationFrame(() => panel.classList.add("wg-in"));
+      } else {
+        panel.classList.add("wg-in");
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel: miniStepLabel(info),
+          stepLabel: info.stepLabel || "",
           forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
+      if (window.__wgStampModal) {
+        window.__wgStampModal(panel, "panel", {
+          phase: "error",
+          step: info.index + 1,
+          total: info.total,
+          block: info.blockName || "",
+          ready: true,
+        });
+      }
       const runBtn = document.getElementById("wg-run");
       if (runBtn) runBtn.addEventListener("click", () => window.__wgNext({}));
       const retryBtn = document.getElementById("wg-error-retry");
       if (retryBtn) retryBtn.addEventListener("click", () => window.__wgNext({ __wgRetry: "1" }));
-    }, info)
+    }, errorPayload)
     .catch(() => {});
 }
 
@@ -1761,6 +2006,14 @@ async function markStepRunning(page, _opts) {
       const panel = document.getElementById("wg-panel");
       if (panel) {
         panel.classList.add("wg-collapsed");
+        panel.setAttribute("data-wg-collapsed", "1");
+        panel.setAttribute("data-wg-phase", "running");
+        if (typeof window.__wgStampModal === "function") {
+          window.__wgStampModal(panel, "panel", {
+            phase: "running",
+            ready: true,
+          });
+        }
         const toggle = panel.querySelector("[data-wg-toggle]");
         if (toggle) toggle.textContent = "Show";
         const titleEl = panel.querySelector(".wg-chrome-title");
@@ -1978,6 +2231,15 @@ async function presentSlides(page, slides, _gate, opts) {
             forceCollapsed: info.forceCollapsed === true ? true : undefined,
           });
         }
+        if (window.__wgStampModal) {
+          window.__wgStampModal(panel, "panel", {
+            phase: "slide",
+            step: info.index + 1,
+            total: info.total,
+            block: info.blockName || "",
+            ready: true,
+          });
+        }
         let autoNow = false;
         try {
           autoNow = localStorage.getItem("wg-autoplay") === "1";
@@ -2451,7 +2713,10 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   // installOverlay only seeds localStorage when the key is null (so mid-run
   // checkbox clicks survive navigations). Without this, a prior --autoplay
   // session sticks forever and agents cannot flip back with --no-autoplay.
-  if (process.env.WAYGRAPH_AUTOPLAY !== undefined) {
+  // Must run on the *demo origin* (after goto), not about:blank - localStorage
+  // is origin-scoped.
+  const syncAutoplayFromEnv = async () => {
+    if (process.env.WAYGRAPH_AUTOPLAY === undefined) return;
     const on = process.env.WAYGRAPH_AUTOPLAY === "1";
     await page
       .evaluate((want) => {
@@ -2462,7 +2727,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         }
       }, on)
       .catch(() => {});
-  }
+  };
+  await syncAutoplayFromEnv();
   // Some real Blocks (e.g. zsign-all's login.block.ts) call
   // page.setViewportSize({ width: 1280, height: 720 }) inside their own
   // act() - a hardcoded override for THEIR OWN testing consistency, with no
@@ -2616,6 +2882,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     // still rendered on screen.
     if ((clearSession || r.resetSession) && i > 0) {
       await resetPageState(context, page, baseURL);
+      // clear() wiped origin storage - re-apply CLI autoplay default.
+      await syncAutoplayFromEnv();
     }
     // Episode pace: block > flow > CLI --fast (only when no authored pace).
     // Authoring wins: withDemoPace("slow"|2|4500) keeps slow dwell even under --fast.
@@ -2748,47 +3016,12 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
           delete window.__wgPendingNavClickLabel;
         })
         .catch(() => {});
-      // stubOnError: ring the broken UI BEFORE the error panel (PIA RFC).
-      // stubAfter stays success-only - distinct BUG/FAIL copy on the fail path.
-      const fixturesOnError = r.highlightFixtures;
-      if (hasAuthoredStubOnError(r.block, fixturesOnError)) {
-        await page
-          .evaluate(() => {
-            if (window.__wgRingTrack) {
-              window.removeEventListener("resize", window.__wgRingTrack);
-              window.removeEventListener("scroll", window.__wgRingTrack, true);
-              window.__wgRingTrack = null;
-            }
-          })
-          .catch(() => {});
-        const errPhase = await runStubPhase(r.block, "stubOnError", {
-          fixtures: fixturesOnError,
-          error: err,
-        });
-        const errHighlights = errPhase.highlights.map((h) => {
-          const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
-          return {
-            selector: styled.selector,
-            label: formatHighlightCaption(styled),
-            duration: styled.duration,
-            fastMode: styled.fastMode,
-            tone: styled.tone,
-            size: styled.size,
-            weight: styled.weight,
-            zoom: styled.zoom,
-          };
-        });
-        await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
-          defaultHoldMs: 2000,
-          pace: pacing.demoPace,
-          todos: errPhase.todos,
-        });
-      }
-      // A thrown act()/observe()/a failed verify Trait used to just crash
-      // the whole Node process with a raw stack trace - the browser closes
-      // (main()'s own try/finally) before a human watching ever sees WHY.
-      // Show it on-screen and let a real click acknowledge it first.
-      await renderStepError(page, {
+      // stubOnError + error/expected panel BEFORE acknowledging (PIA RFC).
+      const errEdits = await presentFailPanel(page, {
+        block: r.block,
+        fixtures: r.highlightFixtures,
+        highlightStyle: r.highlightStyle,
+        error: err,
         index: i,
         total: resolved.length,
         blockName: r.block.name,
@@ -2802,14 +3035,13 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         episodeTitle: r.episodeTitle,
         expectedFailureReason: r.expectedFailureReason,
         stepperMode,
-        // Omit forceCollapsed on errors so Hide is not stomped.
+        gatesFast: pacing.gatesFast,
+        demoPace: pacing.demoPace,
+        gate,
       });
-      const errEdits = await gate();
       if (errEdits && errEdits.__wgRetry) {
-        // Same clean slate a normal episode boundary gets - not just
-        // re-running the failed block against whatever broken/half-
-        // navigated state it left the page in.
         await resetPageState(context, page, baseURL);
+        await syncAutoplayFromEnv();
         i = episodeStartIndex - 1;
         continue;
       }
@@ -2831,6 +3063,50 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       })
       .catch(() => {});
     result = stepOutcome.result;
+    // withExpectedFailure last block that SUCCEEDS on the intentional fail
+    // branch (e.g. submit-login -> LoginPage + error banner). Still show
+    // stubOnError rings + amber "expected outcome" panel - branching no
+    // longer throws, but the demo must not skip the educational overlay.
+    if (r.expectedFailureReason) {
+      const errEdits = await presentFailPanel(page, {
+        block: r.block,
+        fixtures: r.highlightFixtures,
+        highlightStyle: r.highlightStyle,
+        error: undefined,
+        out: result,
+        index: i,
+        total: resolved.length,
+        blockName: r.block.name,
+        message:
+          "Resolved " +
+          (result && result.__state ? result.__state : JSON.stringify(result)) +
+          " (expected failure path)",
+        allNames: moduleNames,
+        allDescriptions: moduleDescriptions,
+        moduleIndex,
+        allEpisodes,
+        title,
+        episodeNumber: r.episodeNumber,
+        episodeTitle: r.episodeTitle,
+        expectedFailureReason: r.expectedFailureReason,
+        stepperMode,
+        gatesFast: pacing.gatesFast,
+        demoPace: pacing.demoPace,
+        gate,
+      });
+      if (errEdits && errEdits.__wgRetry) {
+        await resetPageState(context, page, baseURL);
+        await syncAutoplayFromEnv();
+        i = episodeStartIndex - 1;
+        continue;
+      }
+      if (process.env.WAYGRAPH_JSON !== "1") {
+        console.log(
+          "waygraph: expected failure on " + r.block.name + " - " + r.expectedFailureReason,
+        );
+      }
+      break;
+    }
     const fixturesAfter = r.highlightFixtures;
     const slides = resolveSlides(r.block, { out: result, fixtures: fixturesAfter }).map((s) =>
       applyHighlightStyleDefaults(s, r.highlightStyle),

package/dist/engine.d.ts

@@ -292,15 +292,15 @@ export declare function withBlockPace<In extends Checkpoint<string>, Out extends
  * {@link withTitle}.
  *
  * By itself this changes nothing about how the Flow runs - it still throws
- * exactly as it would otherwise. It's a hint a step-through overlay
- * (waygraph's `chain --step`) reads when that throw happens, to show an
- * informational "this is the point" panel instead of one indistinguishable
- * from a genuine break - the distinction a demo author needs so a viewer
- * (or the author, mid-build) can tell "the app just did what it's supposed
- * to" apart from "something in this demo is actually broken."
+ * Marks a Flow whose last step is an intentional product failure (demo overlay).
+ * Step mode shows stubOnError rings + an amber "expected outcome" panel when:
+ * - the last block **throws**, or
+ * - the last block **succeeds** on the fail branch (e.g. LoginPage + error banner
+ *   after submit-login branched instead of throwing).
+ * Headless `run()` is unchanged - branching success returns the checkpoint.
  * @example const viewerBlockedFlow = withExpectedFailure(
- *   engine.defineFlow([start, NavLoginBlock, blockedLoginCheck, end]),
- *   "locked_out_user can never reach /inventory.html - this is the block working as intended.",
+ *   engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]),
+ *   "locked_out_user stays on LoginPage with the error banner - working as intended.",
  * );
  */
 export declare function withExpectedFailure<Out extends Checkpoint<string>>(flow: Flow<Out>, reason: string): Flow<Out>;

package/dist/engine.js

@@ -405,15 +405,15 @@ export function withBlockPace(block, pace) {
  * {@link withTitle}.
  *
  * By itself this changes nothing about how the Flow runs - it still throws
- * exactly as it would otherwise. It's a hint a step-through overlay
- * (waygraph's `chain --step`) reads when that throw happens, to show an
- * informational "this is the point" panel instead of one indistinguishable
- * from a genuine break - the distinction a demo author needs so a viewer
- * (or the author, mid-build) can tell "the app just did what it's supposed
- * to" apart from "something in this demo is actually broken."
+ * Marks a Flow whose last step is an intentional product failure (demo overlay).
+ * Step mode shows stubOnError rings + an amber "expected outcome" panel when:
+ * - the last block **throws**, or
+ * - the last block **succeeds** on the fail branch (e.g. LoginPage + error banner
+ *   after submit-login branched instead of throwing).
+ * Headless `run()` is unchanged - branching success returns the checkpoint.
  * @example const viewerBlockedFlow = withExpectedFailure(
- *   engine.defineFlow([start, NavLoginBlock, blockedLoginCheck, end]),
- *   "locked_out_user can never reach /inventory.html - this is the block working as intended.",
+ *   engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]),
+ *   "locked_out_user stays on LoginPage with the error banner - working as intended.",
  * );
  */
 export function withExpectedFailure(flow, reason) {

package/dist/index.d.ts

@@ -16,3 +16,5 @@ export { runTraverse } from "./traverse-run.js";
 export type { TraverseOptions, TraverseSessionMode, TraverseWorkerResult, } from "./traverse-run.js";
 export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";
 export type { TraverseCoverageReport } from "./traverse-coverage.js";
+export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./overlay-beacon.js";
+export type { WgModalKind, WgBeaconRow } from "./overlay-beacon.js";

package/dist/index.js

@@ -8,3 +8,4 @@ export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp,
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";
 export { runTraverse } from "./traverse-run.js";
 export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse-coverage.js";
+export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./overlay-beacon.js";

package/dist/overlay-beacon.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Blind-agent / Playwright checks for waygraph overlay modals.
+ *
+ * Every live modal root must carry:
+ *   data-wg-ui="1"
+ *   data-wg-modal="panel|banner|auto-panel"
+ *   data-wg-ready="1" when painted and readable
+ *
+ * Agents: do not claim the stepper works unless
+ *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
+ */
+import type { Page } from "@playwright/test";
+export declare const WG_UI_SEL = "[data-wg-ui=\"1\"]";
+export declare const WG_READY_PANEL_SEL = "[data-wg-modal=\"panel\"][data-wg-ready=\"1\"]";
+export declare const WG_READY_AUTO_SEL = "[data-wg-modal=\"auto-panel\"][data-wg-ready=\"1\"]";
+export declare const WG_READY_BANNER_SEL = "[data-wg-modal=\"banner\"][data-wg-ready=\"1\"]";
+export type WgModalKind = "panel" | "banner" | "auto-panel";
+export type WgBeaconRow = {
+    id: string | null;
+    modal: string | null;
+    ready: boolean;
+    phase: string | null;
+    step: string | null;
+    block: string | null;
+    collapsed: boolean;
+    opacity: string;
+    textLen: number;
+    w: number;
+    h: number;
+    visible: boolean;
+};
+/** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
+export declare function readWgOverlayBeaconInPage(): WgBeaconRow[];
+export declare function readWgOverlayBeacon(page: Page): Promise<WgBeaconRow[]>;
+/**
+ * Hard gate: a blank / missing / opacity-0 modal fails.
+ * Use after demo/auto paints its first overlay.
+ */
+export declare function assertWgOverlayReady(page: Page, opts?: {
+    modal?: WgModalKind;
+    minTextLen?: number;
+    /** When true, collapsed mini chrome is allowed (still needs visible box + text). */
+    allowCollapsed?: boolean;
+}): Promise<WgBeaconRow>;

package/dist/overlay-beacon.js

@@ -0,0 +1,85 @@
+/**
+ * Blind-agent / Playwright checks for waygraph overlay modals.
+ *
+ * Every live modal root must carry:
+ *   data-wg-ui="1"
+ *   data-wg-modal="panel|banner|auto-panel"
+ *   data-wg-ready="1" when painted and readable
+ *
+ * Agents: do not claim the stepper works unless
+ *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
+ */
+export const WG_UI_SEL = '[data-wg-ui="1"]';
+export const WG_READY_PANEL_SEL = '[data-wg-modal="panel"][data-wg-ready="1"]';
+export const WG_READY_AUTO_SEL = '[data-wg-modal="auto-panel"][data-wg-ready="1"]';
+export const WG_READY_BANNER_SEL = '[data-wg-modal="banner"][data-wg-ready="1"]';
+/** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
+export function readWgOverlayBeaconInPage() {
+    const w = globalThis;
+    if (typeof w.__wgOverlayBeacon === "function")
+        return w.__wgOverlayBeacon();
+    return Array.from(document.querySelectorAll(WG_UI_SEL)).map((el) => {
+        const r = el.getBoundingClientRect();
+        const st = getComputedStyle(el);
+        return {
+            id: el.id || null,
+            modal: el.getAttribute("data-wg-modal"),
+            ready: el.getAttribute("data-wg-ready") === "1",
+            phase: el.getAttribute("data-wg-phase"),
+            step: el.getAttribute("data-wg-step"),
+            block: el.getAttribute("data-wg-block"),
+            collapsed: el.getAttribute("data-wg-collapsed") === "1" || el.classList.contains("wg-collapsed"),
+            opacity: st.opacity,
+            textLen: (el.textContent || "").trim().length,
+            w: Math.round(r.width),
+            h: Math.round(r.height),
+            visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
+        };
+    });
+}
+export async function readWgOverlayBeacon(page) {
+    return page.evaluate(() => {
+        const w = window;
+        if (typeof w.__wgOverlayBeacon === "function") {
+            return w.__wgOverlayBeacon();
+        }
+        return Array.from(document.querySelectorAll('[data-wg-ui="1"]')).map((el) => {
+            const r = el.getBoundingClientRect();
+            const st = getComputedStyle(el);
+            return {
+                id: el.id || null,
+                modal: el.getAttribute("data-wg-modal"),
+                ready: el.getAttribute("data-wg-ready") === "1",
+                phase: el.getAttribute("data-wg-phase"),
+                step: el.getAttribute("data-wg-step"),
+                block: el.getAttribute("data-wg-block"),
+                collapsed: el.getAttribute("data-wg-collapsed") === "1" || el.classList.contains("wg-collapsed"),
+                opacity: st.opacity,
+                textLen: (el.textContent || "").trim().length,
+                w: Math.round(r.width),
+                h: Math.round(r.height),
+                visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
+            };
+        });
+    });
+}
+/**
+ * Hard gate: a blank / missing / opacity-0 modal fails.
+ * Use after demo/auto paints its first overlay.
+ */
+export async function assertWgOverlayReady(page, opts) {
+    const modal = opts?.modal ?? "panel";
+    const minText = opts?.minTextLen ?? 12;
+    const rows = await readWgOverlayBeacon(page);
+    const hit = rows.find((r) => r.modal === modal &&
+        r.ready &&
+        r.visible &&
+        r.textLen >= minText &&
+        (opts?.allowCollapsed || !r.collapsed || r.textLen >= minText));
+    if (!hit) {
+        throw new Error(`waygraph overlay NOT ready (modal=${modal}, minTextLen=${minText}). ` +
+            `beacons=${JSON.stringify(rows)}. ` +
+            `Do not claim stepper/modal works.`);
+    }
+    return hit;
+}

package/dist/step-overlay.d.ts

@@ -18,5 +18,20 @@ declare global {
         __wgHideRing?: () => void;
         __wgPendingNavClickLabel?: string;
         __wgWirePanelChrome?: (panel: HTMLElement, storageKey: string, chromeTitle?: string) => void;
+        __wgStampModal?: (el: Element, kind: string, meta?: Record<string, unknown>) => void;
+        __wgOverlayBeacon?: () => Array<{
+            id: string | null;
+            modal: string | null;
+            ready: boolean;
+            phase: string | null;
+            step: string | null;
+            block: string | null;
+            collapsed: boolean;
+            opacity: string;
+            textLen: number;
+            w: number;
+            h: number;
+            visible: boolean;
+        }>;
     }
 }

package/dist/step-overlay.js

@@ -146,6 +146,17 @@ export async function installDemoChrome(page, title = "waygraph auto", options =
             banner.innerHTML =
                 "<span class='wg-banner-tag'>waygraph auto</span><span>" + title + "</span>";
             document.documentElement.appendChild(banner);
+            banner.setAttribute("data-wg-ui", "1");
+            banner.setAttribute("data-wg-modal", "banner");
+            banner.setAttribute("data-wg-ready", "1");
+        }
+        else {
+            const existing = document.getElementById("wg-banner");
+            if (existing) {
+                existing.setAttribute("data-wg-ui", "1");
+                existing.setAttribute("data-wg-modal", "banner");
+                existing.setAttribute("data-wg-ready", "1");
+            }
         }
         if (showBanner && !document.title.startsWith("[waygraph] ")) {
             document.title = "[waygraph] " + document.title;

package/examples/saucedemo/package-lock.json

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

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

@@ -78,6 +78,22 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       });
     },
     stubAfter: (ctx) => {
+      // Fail branch lands on LoginPage with Epic sadface - do not ring the
+      // inventory shelf. Success (LoggedIn) hands off to shopFlow.
+      if (ctx.out && ctx.out.__state === "LoginPage") {
+        ctx.title("Login blocked");
+        ctx.todos(["Enter username", "Enter password", "Click Login"]);
+        ctx.todoIndex(2);
+        ctx.ring("error", {
+          selector: '[data-test="error"]',
+          label: "Login error banner",
+          tone: "danger",
+          focus: true,
+          color: "#f87171",
+          duration: true,
+        });
+        return;
+      }
       ctx.banner("Inventory");
       ctx.todos(["Enter username", "Enter password", "Click Login"]);
       ctx.todoIndex(2);

package/examples/saucedemo/src/flows/viewer-blocked.flow.ts

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle, withSessionReset } from "waygraph";
+import { Engine, start, end, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
 import { SubmitLoginActionBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
 
@@ -16,10 +16,14 @@ const engine = new Engine();
 // genuinely fresh cookies/storage, or the previous user's session would
 // still be live and this login attempt wouldn't mean anything.
 //
-// submit-login now branches: observe sees no /inventory.html navigation,
-// resolve -> LoginPage, verify confirms the error banner - the flow completes
-// at LoginPage (not a thrown verify on a fake LoggedIn resolve).
-export const viewerBlockedFlow = withTitle(
-  withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
-  "Viewer: Blocked Login Attempt",
+// submit-login branches: observe sees no /inventory.html navigation,
+// resolve -> LoginPage, verify confirms the error banner. Demo still wraps
+// withExpectedFailure so step 9/9 shows stubOnError rings + amber
+// "expected outcome" panel (branching no longer throws).
+export const viewerBlockedFlow = withExpectedFailure(
+  withTitle(
+    withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
+    "Viewer: Blocked Login Attempt",
+  ),
+  "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",
 );

package/package.json

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

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

@@ -78,6 +78,22 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       });
     },
     stubAfter: (ctx) => {
+      // Fail branch lands on LoginPage with Epic sadface - do not ring the
+      // inventory shelf. Success (LoggedIn) hands off to shopFlow.
+      if (ctx.out && ctx.out.__state === "LoginPage") {
+        ctx.title("Login blocked");
+        ctx.todos(["Enter username", "Enter password", "Click Login"]);
+        ctx.todoIndex(2);
+        ctx.ring("error", {
+          selector: '[data-test="error"]',
+          label: "Login error banner",
+          tone: "danger",
+          focus: true,
+          color: "#f87171",
+          duration: true,
+        });
+        return;
+      }
       ctx.banner("Inventory");
       ctx.todos(["Enter username", "Enter password", "Click Login"]);
       ctx.todoIndex(2);

package/templates/quickstart/src/flows/viewer-blocked.flow.ts

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle, withSessionReset } from "waygraph";
+import { Engine, start, end, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
 import { SubmitLoginActionBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
 
@@ -16,10 +16,14 @@ const engine = new Engine();
 // genuinely fresh cookies/storage, or the previous user's session would
 // still be live and this login attempt wouldn't mean anything.
 //
-// submit-login now branches: observe sees no /inventory.html navigation,
-// resolve -> LoginPage, verify confirms the error banner - the flow completes
-// at LoginPage (not a thrown verify on a fake LoggedIn resolve).
-export const viewerBlockedFlow = withTitle(
-  withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
-  "Viewer: Blocked Login Attempt",
+// submit-login branches: observe sees no /inventory.html navigation,
+// resolve -> LoginPage, verify confirms the error banner. Demo still wraps
+// withExpectedFailure so step 9/9 shows stubOnError rings + amber
+// "expected outcome" panel (branching no longer throws).
+export const viewerBlockedFlow = withExpectedFailure(
+  withTitle(
+    withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
+    "Viewer: Blocked Login Attempt",
+  ),
+  "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",
 );