waygraph 0.12.42 → 0.12.44

package/dist/cli.js

@@ -412,10 +412,14 @@ function seedMemForFlow(mem, flowBlocks, json, label) {
 const RING_CSS =
   "#wg-ring{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
   "border:2.5px solid #7C3AED;border-radius:10px;" +
-  "box-shadow:0 0 0 4px rgba(124,58,237,.16);transition:opacity .3s ease,border-color .15s,box-shadow .15s;}" +
+  // Opacity fade only - NEVER transition border-color/box-shadow. Tone swaps
+  // (auto gray -> planned purple -> warning yellow) must snap instantly;
+  // color transitions read as a muddy gray/purple/yellow morph on ring 2+.
+  "box-shadow:0 0 0 4px rgba(124,58,237,.16);transition:opacity .3s ease;}" +
   // Planned (stubs / fixtures / YAP / instruction.highlights) = purple.
   // Automation (verify fallback, unmatched fill/click) = gray - operators
   // can ignore engine checks and watch purple + semantic tones.
+  "#wg-ring[data-tone=planned]{border-color:#7C3AED;box-shadow:0 0 0 4px rgba(124,58,237,.16);}" +
   "#wg-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}" +
   "#wg-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}" +
   "#wg-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}" +
@@ -431,7 +435,8 @@ const RING_CSS =
   // window.__wgPositionRing in installOverlay.
   "#wg-ring-label{position:fixed;z-index:2147483646;pointer-events:none;opacity:0;" +
   "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,background .15s,color .15s;}" +
+  "font:600 12px/1.35 system-ui,sans-serif;transition:opacity .3s ease;}" +
+  "#wg-ring-label[data-tone=planned]{background:#7C3AED;color:#fff;}" +
   "#wg-ring-label[data-tone=auto]{background:#6B7280;color:#fff;}" +
   "#wg-ring-label[data-tone=info]{background:#2563EB;color:#fff;}" +
   "#wg-ring-label[data-tone=warning]{background:#EAB308;color:#1c1917;}" +
@@ -509,6 +514,18 @@ const RING_CSS =
   "#wg-panel .wg-pace[data-pace-kind=blitz] .wg-pace-badge{background:#22C55E;color:#052e16;}" +
   "#wg-panel .wg-pace[data-pace-kind=ms] .wg-pace-badge{background:#3B82F6;color:#fff;}" +
   "#wg-panel .wg-narration{margin:0 0 12px;font:italic 14px/1.4 system-ui,sans-serif;color:#f0e8ff;}" +
+  // Todo checklist lives in #wg-todo-dock (fixed, outside #wg-panel) so
+  // --mini / Hide collapse never hides it (.wg-body {display:none} would).
+  // Click dock to slide left <-> right (WAYGRAPH_TODO_POS / --todo-left|right).
+  "#wg-todo-dock{position:fixed;z-index:2147483646;top:72px;left:14px;" +
+  "width:min(280px,42vw);max-height:calc(100vh - 100px);overflow:auto;box-sizing:border-box;" +
+  "padding:10px 12px;background:rgba(20,10,40,.94);color:#fff;border-radius:12px;" +
+  "border:1px solid rgba(124,58,237,.45);box-shadow:0 8px 24px rgba(0,0,0,.35);" +
+  "pointer-events:auto;cursor:pointer;" +
+  "transition:transform .4s cubic-bezier(.22,1,.36,1);transform:translateX(0);}" +
+  "#wg-todo-dock[data-pos=right]{transform:translateX(calc(100vw - 100% - 28px));}" +
+  "#wg-todo-dock[data-pos=left]{transform:translateX(0);}" +
+  "#wg-todo-dock #wg-todos{list-style:none;margin:0;padding:0;background:transparent;border:none;}" +
   "#wg-todos{list-style:none;margin:0 0 12px;padding:8px 10px;background:#0f0620;border-radius:8px;" +
   "border:1px solid #3a2a60;}" +
   "#wg-todos li{display:flex;gap:8px;align-items:flex-start;margin:0 0 6px;font:600 12.5px/1.35 system-ui,sans-serif;}" +
@@ -647,10 +664,12 @@ async function installOverlay(page, title) {
   // navigation that rebuilds the banner keeps the human's last pick).
   const envPos = (process.env.WAYGRAPH_TITLE_POS || "left").toLowerCase();
   const bannerPos = envPos === "center" || envPos === "right" ? envPos : "left";
+  const envTodoPos = (process.env.WAYGRAPH_TODO_POS || "left").toLowerCase();
+  const todoPos = envTodoPos === "right" ? "right" : "left";
   const envAutoplay = process.env.WAYGRAPH_AUTOPLAY === "1";
   await page
     .evaluate(
-      ({ title, favicon, bannerPos, envAutoplay }) => {
+      ({ title, favicon, bannerPos, todoPos, envAutoplay }) => {
         // Seed the live autoplay toggle from the env default on first ever
         // load only - a real navigation re-runs this, and re-stamping here
         // would silently undo a human's mid-run checkbox click.
@@ -818,32 +837,46 @@ async function installOverlay(page, title) {
             /* private mode / blocked storage - position still applies this page */
           }
         };
-        if (title && !document.getElementById("wg-banner")) {
-          const banner = document.createElement("div");
-          banner.id = "wg-banner";
-          let saved = null;
-          try {
-            saved = localStorage.getItem("wg-banner-pos");
-          } catch {
-            /* ignore */
+        if (title) {
+          let banner = document.getElementById("wg-banner");
+          if (!banner) {
+            banner = document.createElement("div");
+            banner.id = "wg-banner";
+            let saved = null;
+            try {
+              saved = localStorage.getItem("wg-banner-pos");
+            } catch {
+              /* ignore */
+            }
+            const startPos =
+              saved && POSITIONS.includes(saved) ? saved : bannerPos;
+            applyPos(banner, startPos);
+            banner.title = "Click to move: top left / center / right";
+            banner.addEventListener("click", (e) => {
+              e.stopPropagation();
+              const i = POSITIONS.indexOf(banner.dataset.pos || "left");
+              applyPos(banner, POSITIONS[(i + 1) % POSITIONS.length]);
+            });
+            const tag = document.createElement("span");
+            tag.className = "wg-banner-tag";
+            tag.textContent = "waygraph demo";
+            const text = document.createElement("span");
+            text.className = "wg-banner-text";
+            text.textContent = title;
+            banner.appendChild(tag);
+            banner.appendChild(text);
+            document.documentElement.appendChild(banner);
+          } else {
+            // Fixture / episode title changes every step - update in place
+            // (banner is created once; do not leave the first step's text stuck).
+            let text = banner.querySelector(".wg-banner-text");
+            if (!text) {
+              text = document.createElement("span");
+              text.className = "wg-banner-text";
+              banner.appendChild(text);
+            }
+            text.textContent = title;
           }
-          const startPos =
-            saved && POSITIONS.includes(saved) ? saved : bannerPos;
-          applyPos(banner, startPos);
-          banner.title = "Click to move: top left / center / right";
-          banner.addEventListener("click", (e) => {
-            e.stopPropagation();
-            const i = POSITIONS.indexOf(banner.dataset.pos || "left");
-            applyPos(banner, POSITIONS[(i + 1) % POSITIONS.length]);
-          });
-          const tag = document.createElement("span");
-          tag.className = "wg-banner-tag";
-          tag.textContent = "waygraph demo";
-          const text = document.createElement("span");
-          text.textContent = title;
-          banner.appendChild(tag);
-          banner.appendChild(text);
-          document.documentElement.appendChild(banner);
         }
         // Tab title/favicon: a real navigation resets document.title and any
         // <link rel="icon"> the new document brings, so re-check (not
@@ -858,6 +891,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 +1011,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;
@@ -1004,8 +1079,93 @@ async function installOverlay(page, title) {
             }
           }
         };
+        // Floating todo dock - lives outside #wg-panel so --mini / Hide never
+        // hide the checklist. Click cycles left <-> right with CSS transform.
+        // Authors set side via ctx.todoPos("left"|"right"); env / --todo-* fallback.
+        window.__wgSyncTodos = (list, pos) => {
+          list = Array.isArray(list) ? list : [];
+          const POS = ["left", "right"];
+          let dock = document.getElementById("wg-todo-dock");
+          // Drop any in-panel leftover (old builds put #wg-todos in .wg-body).
+          document.querySelectorAll("#wg-panel #wg-todos").forEach((el) => el.remove());
+          if (!list.length) {
+            if (dock) dock.remove();
+            return;
+          }
+          const wantPos =
+            pos === "left" || pos === "right"
+              ? pos
+              : null;
+          if (!dock) {
+            dock = document.createElement("div");
+            dock.id = "wg-todo-dock";
+            dock.setAttribute("data-wg-ui", "1");
+            dock.setAttribute("data-wg-modal", "todos");
+            dock.setAttribute("data-wg-ready", "1");
+            let saved = null;
+            try {
+              saved = localStorage.getItem("wg-todo-pos");
+            } catch {
+              /* ignore */
+            }
+            const start =
+              wantPos ||
+              (saved && POS.includes(saved) ? saved : todoPos === "right" ? "right" : "left");
+            dock.dataset.pos = start;
+            dock.title = "Click to move checklist: left / right";
+            dock.addEventListener("click", (e) => {
+              e.stopPropagation();
+              const i = POS.indexOf(dock.dataset.pos || "left");
+              const next = POS[(i + 1) % POS.length];
+              dock.dataset.pos = next;
+              try {
+                localStorage.setItem("wg-todo-pos", next);
+              } catch {
+                /* ignore */
+              }
+            });
+            document.documentElement.appendChild(dock);
+          } else if (wantPos) {
+            dock.dataset.pos = wantPos;
+            try {
+              localStorage.setItem("wg-todo-pos", wantPos);
+            } catch {
+              /* ignore */
+            }
+          }
+          const esc = (s) =>
+            String(s)
+              .replace(/&/g, "&amp;")
+              .replace(/</g, "&lt;")
+              .replace(/>/g, "&gt;");
+          dock.innerHTML =
+            '<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 ? "\u2713" : t.current ? "\u2192" : "\u25CB";
+                return (
+                  '<li class="' +
+                  cls +
+                  '"><span class="wg-todo-mark">' +
+                  mark +
+                  "</span><span>" +
+                  esc(t.text || "") +
+                  "</span></li>"
+                );
+              })
+              .join("") +
+            "</ul>";
+          if (window.__wgStampModal) {
+            window.__wgStampModal(dock, "todos", { ready: true });
+          }
+        };
       },
-      { title, favicon: WAYGRAPH_FAVICON, bannerPos, envAutoplay },
+      { title, favicon: WAYGRAPH_FAVICON, bannerPos, todoPos, envAutoplay },
     )
     .catch(() => {});
 }
@@ -1027,6 +1187,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,14 +1255,15 @@ async function renderBeforeStep(page, info) {
             esc(info.paceLabel || "") +
             "</span></div>"
           : "";
+      // Todos render into floating #wg-todo-dock via __wgSyncTodos - never
+      // inside .wg-body (would vanish under --mini / Hide collapse).
       let html =
         "<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>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
-        narrationHtml +
-        todosHtmlFromInfo(info, esc);
+        narrationHtml;
       if (info.keys.length === 0) {
         html += "<div class=\\"wg-key\\">(no MemKeys required)</div>";
       }
@@ -1130,13 +1293,25 @@ 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.__wgSyncTodos) window.__wgSyncTodos(info.todos || [], info.todoPos || null);
+      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 +1381,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 +1542,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
@@ -1359,6 +1645,11 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
               : normalizeTodos(h.todos, h.todoIndex);
           await page
             .evaluate((todos) => {
+              if (window.__wgSyncTodos) {
+                window.__wgSyncTodos(todos);
+                return;
+              }
+              // Fallback for pages that never got installOverlay sync helper.
               const ul = document.getElementById("wg-todos");
               if (!ul) return;
               ul.innerHTML = todos
@@ -1447,7 +1738,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 +1818,38 @@ async function renderAfterStep(page, info) {
             escA(info.paceLabel || "") +
             "</span></div>"
           : "";
+      const todosHtml = ""; // todos float in #wg-todo-dock via __wgSyncTodos
       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.__wgSyncTodos) window.__wgSyncTodos(info.todos || [], info.todoPos || null);
+      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 +1876,7 @@ async function renderAfterStep(page, info) {
           if (auto) auto.style.display = cb.checked ? "" : "none";
         });
       }
-    }, info)
+    }, afterPayload)
     .catch(() => {});
 }
 
@@ -1582,6 +1888,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 +1946,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 +2079,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 +2304,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";
@@ -2128,7 +2463,7 @@ async function teardownOverlay(page) {
         window.__wgRingTrack = null;
       }
       window.__wgNarrateOwnsRing = false;
-      for (const id of ["wg-panel", "wg-ring", "wg-ring-label", "wg-cursor", "wg-click-pulse", "wg-banner"]) {
+      for (const id of ["wg-panel", "wg-ring", "wg-ring-label", "wg-cursor", "wg-click-pulse", "wg-banner", "wg-todo-dock"]) {
         const el = document.getElementById(id);
         if (el) el.remove();
       }
@@ -2451,7 +2786,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 +2800,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 +2955,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.
@@ -2653,6 +2994,12 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       applyHighlightStyleDefaults(h, flowStyle),
     );
     const stubBeforeTodos = stubBeforePhase.todos || [];
+    const overlayTitle =
+      (stubBeforePhase.title && String(stubBeforePhase.title).trim()) ||
+      (r.episodeTitle && String(r.episodeTitle).trim()) ||
+      title ||
+      "waygraph demo";
+    const overlayTodoPos = stubBeforePhase.todoPos || undefined;
     const isNavBlock = r.block.__waygraphKind === "nav";
     const autoNow = await currentAutoplay();
     // Video / --mini: compact pill. Never pass false - Hide/localStorage wins.
@@ -2697,7 +3044,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       moduleIndex,
       allEpisodes,
       justEnteredEpisode,
-      title,
+      title: overlayTitle,
+      todoPos: overlayTodoPos,
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
       stepperMode,
@@ -2748,47 +3096,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 +3115,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 +3143,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),
@@ -2848,12 +3204,18 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     }
     let highlights;
     let stubAfterTodos = [];
+    let afterOverlayTitle = overlayTitle;
+    let afterTodoPos = overlayTodoPos;
     if (hasAuthoredStubAfter(r.block, result, fixturesAfter)) {
       const afterPhase = await runStubPhase(r.block, "stubAfter", {
         out: result,
         fixtures: fixturesAfter,
       });
       stubAfterTodos = afterPhase.todos || [];
+      if (afterPhase.title && String(afterPhase.title).trim()) {
+        afterOverlayTitle = String(afterPhase.title).trim();
+      }
+      if (afterPhase.todoPos) afterTodoPos = afterPhase.todoPos;
       highlights = afterPhase.highlights.map((h) => {
         const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
         return {
@@ -2887,7 +3249,8 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       allDescriptions: moduleDescriptions,
       moduleIndex,
       allEpisodes,
-      title,
+      title: afterOverlayTitle,
+      todoPos: afterTodoPos,
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
       stepperMode,
@@ -3915,6 +4278,12 @@ function parseRunFlags(argv) {
         else if (a === "--mini" || a === "--stepper-mini") {
             out.miniStepper = true;
         }
+        else if (a === "--todo-left") {
+            out.todoPos = "left";
+        }
+        else if (a === "--todo-right") {
+            out.todoPos = "right";
+        }
         else if (a === "--ff-expand") {
             out.ffExpand = true;
         }
@@ -4035,8 +4404,8 @@ function applyRunFlags(flags, opts) {
             process.env.WAYGRAPH_HEADED = "0";
         }
     }
-    if ((flags.fast || flags.fullStepper || flags.miniStepper) && !opts?.allowDemoUi) {
-        console.error("waygraph: --fast / --full / --mini are demo-only flags");
+    if ((flags.fast || flags.fullStepper || flags.miniStepper || flags.todoPos) && !opts?.allowDemoUi) {
+        console.error("waygraph: --fast / --full / --mini / --todo-left|--todo-right are demo-only flags");
         process.exit(1);
     }
     if (flags.step === true) {
@@ -4083,6 +4452,9 @@ function applyRunFlags(flags, opts) {
     if (flags.miniStepper) {
         process.env.WAYGRAPH_MINI = "1";
     }
+    if (flags.todoPos === "left" || flags.todoPos === "right") {
+        process.env.WAYGRAPH_TODO_POS = flags.todoPos;
+    }
     if (flags.ffExpand) {
         process.env.WAYGRAPH_FF_EXPAND = "1";
     }
@@ -4248,6 +4620,7 @@ Primary (less is more):
                  --fast                    Shorter auto-next / Next gates (keeps smooth cursor)
                  --full                    Classic wrap-all block chips (default: carousel)
                  --mini                    Force compact mini panel (Hide pill + Next); alias --stepper-mini
+                 --todo-left|--todo-right  Floating checklist dock side (also ctx.todoPos / WAYGRAPH_TODO_POS)
                  --ff-expand               Expand fastForwardComposeBlock inners as separate steps
                  --ff-disabled             Dispute: expand FF (alias --no-ff); blitz kept on those inners
                  --auto-play-video         Unattended + recorded: --auto-next + --video (+ step); headless by default