waygraph 0.4.0 → 0.6.0

package/dist/cli.js

@@ -12,8 +12,9 @@
  * "project" defaults to the current directory.
  * A project is any directory containing *.flow.ts files (typically under src/flows/).
  */
-import { existsSync, readdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
-import { resolve, relative, join, basename } from "node:path";
+import { existsSync, readdirSync, readFileSync, writeFileSync, rmSync, cpSync } from "node:fs";
+import { resolve, relative, join, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { MemPage } from "./mem-page.js";
 // ---------------------------------------------------------------------------
@@ -401,7 +402,15 @@ const RING_CSS =
   "max-width:min(92vw,640px);max-height:calc(100vh - 24px);overflow-y:auto;box-sizing:border-box;" +
   "background:rgba(20,10,40,.94);color:#fff;border-radius:14px;" +
   "padding:16px 20px;font:14px/1.4 system-ui,sans-serif;box-shadow:0 12px 30px rgba(0,0,0,.35);" +
-  "opacity:0;transition:opacity .06s ease;}" +
+  // .06s was tuned back when the panel was removed and recreated on
+  // EVERY step - fast was the only way to avoid feeling laggy. Now that
+  // routine per-step updates reuse the same element (no fade at all - see
+  // the panel-reuse fix), this only ever fires for a genuinely fresh DOM
+  // (first load, or a real navigation - which is exactly what an episode
+  // boundary is). Slower and smoother reads as a real, comfortable
+  // transition instead of an instant pop - "eyes friendly," not laggy,
+  // since it no longer costs anything on the common case.
+  "opacity:0;transition:opacity .35s ease;}" +
   "#wg-panel.wg-in{opacity:1;}" +
   "#wg-panel .wg-auto{margin-top:10px;font:600 13px system-ui,sans-serif;color:#c9a6ff;}" +
   "#wg-panel .wg-autoplay-row{margin-top:8px;}" +
@@ -420,6 +429,32 @@ const RING_CSS =
   "#wg-panel .wg-narration{margin:0 0 12px;font:italic 14px/1.4 system-ui,sans-serif;color:#f0e8ff;}" +
   "#wg-progress{height:4px;background:#2a1650;border-radius:2px;margin:0 0 12px;overflow:hidden;}" +
   "#wg-progress-bar{height:100%;background:#7C3AED;border-radius:2px;transition:width .3s ease;}" +
+  // A real tab bar for episodes - the currently-active episode reads as
+  // active (filled underline, full-brightness text), every other episode
+  // reads as inactive (dimmed, no underline) - Dan's own ask: "if episode
+  // 1 is active, the episode 2 tab is inactive." Only rendered when the
+  // chain spec actually named real Flows (chainFlow tags each via
+  // BlockInfo - same gate the "Episode N:" heading already uses); an
+  // ad hoc block chain with no episodes shows no tab bar at all.
+  "#wg-episodes{display:flex;gap:4px;margin:0 0 10px;border-bottom:1px solid #3a2a60;}" +
+  "#wg-episodes .wg-ep-tab{padding:6px 14px 8px;font:600 12px system-ui,sans-serif;" +
+  "border-bottom:2px solid transparent;margin-bottom:-1px;white-space:nowrap;}" +
+  "#wg-episodes .wg-ep-current{color:#fff;border-bottom-color:#7C3AED;}" +
+  "#wg-episodes .wg-ep-done{color:#9a7ad1;}" +
+  "#wg-episodes .wg-ep-upcoming{color:#5a4a80;}" +
+  // A one-time, gentle signal for "you just entered this episode" - Dan:
+  // "i want a clear ui eyes friendly to remind me that i am on next
+  // episode." A slow outward glow, not an opacity blink/strobe (that's
+  // exactly the kind of flashing that already caused the original
+  // complaint) - plays once (no loop), 1.1s, only on the FIRST block of a
+  // newly-entered episode, not on every step within it.
+  "@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;}" +
   "#wg-modules .wg-mod-done{background:#2a1650;color:#9a7ad1;}" +
@@ -435,12 +470,23 @@ const RING_CSS =
   "#wg-banner .wg-banner-tag{display:block;font-size:10px;font-weight:700;color:#c9a6ff;" +
   "letter-spacing:.05em;text-transform:uppercase;margin-bottom:2px;}" +
   "#wg-panel .wg-key{margin:8px 0;}" +
+  // A live, human-readable preview of what's about to be written for this
+  // MemKey - Dan: "i want pretty to exist in memkeys too... it shows what
+  // input its gonig to be written." Same global Pretty/JSON preference the
+  // result display already has (window.__wgPretty) - hidden entirely in
+  // JSON mode, since the raw textarea already speaks for itself there.
+  "#wg-panel .wg-key-pretty{margin-top:4px;font:12px/1.5 system-ui,sans-serif;" +
+  "background:#0f0620;border-radius:6px;padding:6px 8px;}" +
+  "#wg-panel .wg-key-pretty-row{color:#f0e8ff;}" +
+  "#wg-panel .wg-key-pretty-label{color:#9a7ad1;font-weight:600;}" +
   "#wg-panel label{display:block;font-size:12px;color:#d8c8ff;margin-bottom:3px;}" +
   "#wg-panel textarea{width:100%;box-sizing:border-box;background:#0f0620;color:#fff;" +
   "border:1px solid #4b2a80;border-radius:8px;padding:6px 8px;font:12px/1.3 monospace;resize:vertical;}" +
   "#wg-panel button{margin-top:10px;background:#7C3AED;color:#fff;border:none;border-radius:8px;" +
   "padding:8px 16px;font:600 13px system-ui,sans-serif;cursor:pointer;}" +
   "#wg-panel button:hover{background:#6b2fd6;}" +
+  "#wg-panel button:disabled{background:#4b2a80;cursor:default;opacity:.7;}" +
+  "#wg-panel textarea:disabled{opacity:.6;}" +
   "#wg-panel .wg-result{font:12px/1.4 monospace;background:#0f0620;border-radius:8px;padding:8px;" +
   "margin:8px 0;white-space:pre-wrap;}" +
   "#wg-panel .wg-result-pretty{font:600 14px/1.4 system-ui,sans-serif;}" +
@@ -452,8 +498,15 @@ const RING_CSS =
   "#wg-panel .wg-error-heading{color:#ff8fa0;}" +
   "#wg-panel .wg-error-msg{font:12px/1.5 monospace;background:#2a0f16;color:#ffc7cf;" +
   "border-radius:8px;padding:10px;margin:0 0 12px;white-space:pre-wrap;max-height:200px;overflow-y:auto;}" +
-  "#wg-panel .wg-error-stop{background:#e0475c;}" +
-  "#wg-panel .wg-error-stop:hover{background:#c33a4c;}";
+  "#wg-panel .wg-error-actions{display:flex;gap:8px;}" +
+  "#wg-panel .wg-error-stop{background:#e0475c;margin-top:0;}" +
+  "#wg-panel .wg-error-stop:hover{background:#c33a4c;}" +
+  "#wg-panel .wg-error-retry{background:#2a9d6f;margin-top:0;}" +
+  "#wg-panel .wg-error-retry:hover{background:#22855e;}" +
+  "#wg-panel.wg-expected{border:1.5px solid #e0a53e;}" +
+  "#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;}";
 
 // Purple dot favicon (matches the overlay's own theme color) - the tab-bar
 // signal that "this Chromium window is a waygraph run," even at a glance
@@ -668,15 +721,51 @@ async function renderBeforeStep(page, info) {
     .catch(() => {});
   await page
     .evaluate((info) => {
-      const old = document.getElementById("wg-panel");
-      if (old) old.remove();
-      const panel = document.createElement("div");
-      panel.id = "wg-panel";
+      // Reused in place, not removed + recreated, every step - the old
+      // remove()-then-fade-back-in cycle was a real flash on every single
+      // transition (Dan: "the appear and disappear... hurts eyes and
+      // dizzy"). Updating one persistent element's content has nothing to
+      // flash - it only ever fades in ONCE, the first time this page
+      // genuinely has no panel yet (a real navigation wiped the whole
+      // document, or this is the very first step).
+      let panel = document.getElementById("wg-panel");
+      const isNewPanel = !panel;
+      if (!panel) {
+        panel = document.createElement("div");
+        panel.id = "wg-panel";
+      }
       const pct = Math.round((info.index / info.total) * 100);
       const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+      // A real tab bar, not a single text line - every episode this chain
+      // touches, the current one reading as active (Dan: "if episode 1 is
+      // active, the episode 2 tab is inactive"). Absent entirely for an ad
+      // hoc block chain with no named Flows.
+      const episodesHtml = info.allEpisodes && info.allEpisodes.length > 0
+        ? "<div id=\\"wg-episodes\\">" +
+          info.allEpisodes
+            .map((e) => {
+              const cls = e.episodeNumber < info.episodeNumber ? "wg-ep-done"
+                : e.episodeNumber === info.episodeNumber ? "wg-ep-current"
+                : "wg-ep-upcoming";
+              // The gentle one-time glow only plays on the tab actually
+              // being entered right now, not on every render of it.
+              const enteredCls = info.justEnteredEpisode && e.episodeNumber === info.episodeNumber
+                ? " wg-ep-entered"
+                : "";
+              return "<span class=\\"wg-ep-tab " + cls + enteredCls + "\\">Episode " + e.episodeNumber + ": " +
+                esc(e.episodeTitle || "") + "</span>";
+            })
+            .join("") +
+          "</div>"
+        : "";
+      // Scoped to THIS episode's own blocks (info.allNames is already the
+      // episode-local subset the caller computed) - moduleIndex is this
+      // 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 modulesHtml = info.allNames
         .map((name, idx) => {
-          const cls = idx < info.index ? "wg-mod-done" : idx === info.index ? "wg-mod-current" : "wg-mod-upcoming";
+          const cls = idx < info.moduleIndex ? "wg-mod-done" : idx === info.moduleIndex ? "wg-mod-current" : "wg-mod-upcoming";
           const desc = info.allDescriptions && info.allDescriptions[idx];
           const titleAttr = desc ? " title=\\"" + esc(desc) + "\\"" : "";
           return "<span class=\\"wg-mod " + cls + "\\"" + titleAttr + ">" + name + "</span>";
@@ -685,13 +774,10 @@ async function renderBeforeStep(page, info) {
       const narrationHtml = info.description
         ? "<div class=\\"wg-narration\\">" + esc(info.description) + "</div>"
         : "";
-      const episodeHtml = info.episodeNumber
-        ? "<div class=\\"wg-episode\\">Episode " + info.episodeNumber + ": " + esc(info.episodeTitle || "") + "</div>"
-        : "";
       let html =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
+        episodesHtml +
         "<div id=\\"wg-modules\\">" + modulesHtml + "</div>" +
-        episodeHtml +
         "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
         narrationHtml;
       if (info.keys.length === 0) {
@@ -701,7 +787,9 @@ async function renderBeforeStep(page, info) {
         html +=
           "<div class=\\"wg-key\\"><label>" + k.name + "</label>" +
           "<textarea data-key=\\"" + k.name + "\\" rows=\\"2\\">" +
-          k.value.replace(/</g, "&lt;") + "</textarea></div>";
+          k.value.replace(/</g, "&lt;") + "</textarea>" +
+          "<div class=\\"wg-key-pretty\\" data-pretty-for=\\"" + esc(k.name) + "\\"></div>" +
+          "</div>";
       }
       let autoNow = false;
       try {
@@ -718,8 +806,49 @@ async function renderBeforeStep(page, info) {
         "<div id=\\"wg-gate-auto\\" class=\\"wg-auto\\"" + (autoNow ? "" : " style=\\"display:none\\"") +
         ">Auto-advancing...</div>";
       panel.innerHTML = html;
-      document.documentElement.appendChild(panel);
-      requestAnimationFrame(() => panel.classList.add("wg-in"));
+      if (isNewPanel) {
+        document.documentElement.appendChild(panel);
+        requestAnimationFrame(() => panel.classList.add("wg-in"));
+      }
+      // 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
+      // non-object payload (a plain string/number/array) is shown as-is.
+      // Hidden entirely in JSON mode - shares the SAME global toggle the
+      // result display's own Pretty/JSON buttons already set, not a
+      // second, separate preference.
+      const prettyMemValue = (raw) => {
+        let parsed;
+        try {
+          parsed = JSON.parse(raw);
+        } catch {
+          return "<em>(invalid JSON)</em>";
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+          return esc(JSON.stringify(parsed));
+        }
+        return Object.entries(parsed)
+          .map(([field, value]) => {
+            const label = field.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/^./, (c) => c.toUpperCase());
+            return "<div class=\\"wg-key-pretty-row\\"><span class=\\"wg-key-pretty-label\\">" +
+              esc(label) + ":</span> " + esc(String(value)) + "</div>";
+          })
+          .join("");
+      };
+      const applyKeyPretty = () => {
+        const prettyOn = window.__wgPretty !== false;
+        panel.querySelectorAll("textarea[data-key]").forEach((ta) => {
+          const key = ta.getAttribute("data-key");
+          const previewEl = panel.querySelector(".wg-key-pretty[data-pretty-for=\\"" + key + "\\"]");
+          if (!previewEl) return;
+          previewEl.style.display = prettyOn ? "" : "none";
+          if (prettyOn) previewEl.innerHTML = prettyMemValue(ta.value);
+        });
+      };
+      applyKeyPretty();
+      panel.querySelectorAll("textarea[data-key]").forEach((ta) => {
+        ta.addEventListener("input", applyKeyPretty);
+      });
       const runBtn = document.getElementById("wg-run");
       if (runBtn) {
         runBtn.addEventListener("click", () => {
@@ -810,10 +939,13 @@ async function renderAfterStep(page, info) {
   }
   await page
     .evaluate((info) => {
-      const old = document.getElementById("wg-panel");
-      if (old) old.remove();
-      const panel = document.createElement("div");
-      panel.id = "wg-panel";
+      // Reused in place - see renderBeforeStep's own comment on this.
+      let panel = document.getElementById("wg-panel");
+      const isNewPanel = !panel;
+      if (!panel) {
+        panel = document.createElement("div");
+        panel.id = "wg-panel";
+      }
       const pct = Math.round(((info.index + 1) / info.total) * 100);
       const heading = info.isLast
         ? "End of chain - " + info.total + " / " + info.total + " blocks covered - " + info.blockName + " done"
@@ -822,7 +954,7 @@ async function renderAfterStep(page, info) {
       const escA = (s) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
       const modulesHtml = info.allNames
         .map((name, idx) => {
-          const cls = idx <= info.index ? "wg-mod-done" : "wg-mod-upcoming";
+          const cls = idx <= info.moduleIndex ? "wg-mod-done" : "wg-mod-upcoming";
           const desc = info.allDescriptions && info.allDescriptions[idx];
           const titleAttr = desc ? " title=\\"" + escA(desc) + "\\"" : "";
           return "<span class=\\"wg-mod " + cls + "\\"" + titleAttr + ">" + name + "</span>";
@@ -858,18 +990,30 @@ async function renderAfterStep(page, info) {
         "><button id=\\"wg-run\\">" + buttonLabel + "</button></div>" +
         "<div id=\\"wg-gate-auto\\" class=\\"wg-auto\\"" + (autoNow ? "" : " style=\\"display:none\\"") +
         ">Auto-advancing...</div>";
-      const episodeHtml = info.episodeNumber
-        ? "<div class=\\"wg-episode\\">Episode " + info.episodeNumber + ": " + escA(info.episodeTitle || "") + "</div>"
+      const episodesHtml = info.allEpisodes && info.allEpisodes.length > 0
+        ? "<div id=\\"wg-episodes\\">" +
+          info.allEpisodes
+            .map((e) => {
+              const cls = e.episodeNumber < info.episodeNumber ? "wg-ep-done"
+                : e.episodeNumber === info.episodeNumber ? "wg-ep-current"
+                : "wg-ep-upcoming";
+              return "<span class=\\"wg-ep-tab " + cls + "\\">Episode " + e.episodeNumber + ": " +
+                escA(e.episodeTitle || "") + "</span>";
+            })
+            .join("") +
+          "</div>"
         : "";
       panel.innerHTML =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
+        episodesHtml +
         "<div id=\\"wg-modules\\">" + modulesHtml + "</div>" +
-        episodeHtml +
         "<h3>" + heading + "</h3>" +
         resultHtml +
         gateHtml;
-      document.documentElement.appendChild(panel);
-      requestAnimationFrame(() => panel.classList.add("wg-in"));
+      if (isNewPanel) {
+        document.documentElement.appendChild(panel);
+        requestAnimationFrame(() => panel.classList.add("wg-in"));
+      }
       panel.querySelectorAll(".wg-toggle-btn").forEach((btn) => {
         btn.addEventListener("click", () => {
           const wantPretty = btn.getAttribute("data-mode") === "pretty";
@@ -910,30 +1054,63 @@ async function renderStepError(page, info) {
   await installOverlay(page, info.title);
   await page
     .evaluate((info) => {
-      const old = document.getElementById("wg-panel");
-      if (old) old.remove();
-      const panel = document.createElement("div");
-      panel.id = "wg-panel";
-      panel.className = "wg-error";
+      // Reused in place - see renderBeforeStep's own comment on this.
+      let panel = document.getElementById("wg-panel");
+      const isNewPanel = !panel;
+      if (!panel) {
+        panel = document.createElement("div");
+        panel.id = "wg-panel";
+      }
+      const isExpected = !!info.expectedFailureReason;
+      const errClass = isExpected ? "wg-expected" : "wg-error";
+      panel.className = isNewPanel ? errClass : errClass + " wg-in";
       const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+      const episodesHtml = info.allEpisodes && info.allEpisodes.length > 0
+        ? "<div id=\\"wg-episodes\\">" +
+          info.allEpisodes
+            .map((e) => {
+              const cls = e.episodeNumber < info.episodeNumber ? "wg-ep-done"
+                : e.episodeNumber === info.episodeNumber ? "wg-ep-current"
+                : "wg-ep-upcoming";
+              return "<span class=\\"wg-ep-tab " + cls + "\\">Episode " + e.episodeNumber + ": " +
+                esc(e.episodeTitle || "") + "</span>";
+            })
+            .join("") +
+          "</div>"
+        : "";
       const modulesHtml = info.allNames
         .map((name, idx) => {
-          const cls = idx === info.index ? "wg-mod-current" : idx < info.index ? "wg-mod-done" : "wg-mod-upcoming";
+          const cls = idx === info.moduleIndex ? "wg-mod-current" : idx < info.moduleIndex ? "wg-mod-done" : "wg-mod-upcoming";
           const desc = info.allDescriptions && info.allDescriptions[idx];
           const titleAttr = desc ? " title=\\"" + esc(desc) + "\\"" : "";
           return "<span class=\\"wg-mod " + cls + "\\"" + titleAttr + ">" + name + "</span>";
         })
         .join("");
+      const retryLabel = info.episodeNumber !== undefined ? "Retry Episode " + info.episodeNumber : "Retry";
+      const headingText = isExpected
+        ? "Expected outcome - Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + " failed as intended"
+        : "Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + " threw";
+      const reasonHtml = isExpected
+        ? "<div class=\\"wg-expected-reason\\">" + esc(info.expectedFailureReason) + "</div>"
+        : "";
       panel.innerHTML =
+        episodesHtml +
         "<div id=\\"wg-modules\\">" + modulesHtml + "</div>" +
-        "<h3 class=\\"wg-error-heading\\">Step " + (info.index + 1) + " / " + info.total + " - " +
-        info.blockName + " threw</h3>" +
+        "<h3 class=\\"" + (isExpected ? "wg-expected-heading" : "wg-error-heading") + "\\">" + headingText + "</h3>" +
+        reasonHtml +
         "<div class=\\"wg-error-msg\\">" + esc(info.message) + "</div>" +
-        "<button id=\\"wg-run\\" class=\\"wg-error-stop\\">Stop</button>";
-      document.documentElement.appendChild(panel);
-      requestAnimationFrame(() => panel.classList.add("wg-in"));
+        "<div class=\\"wg-error-actions\\">" +
+        "<button id=\\"wg-error-retry\\" class=\\"wg-error-retry\\">" + esc(retryLabel) + "</button>" +
+        "<button id=\\"wg-run\\" class=\\"wg-error-stop\\">Stop</button>" +
+        "</div>";
+      if (isNewPanel) {
+        document.documentElement.appendChild(panel);
+        requestAnimationFrame(() => panel.classList.add("wg-in"));
+      }
       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)
     .catch(() => {});
 }
@@ -1006,6 +1183,35 @@ function extractVerifyHighlights(block, resultTag) {
  * highlight then slowly input." One-time patch (idempotent - guarded so a
  * multi-step chain doesn't re-wrap an already-wrapped fill).
  */
+/**
+ * Called once the gate resolves - manual click OR autoplay timeout, both
+ * covered from here rather than duplicating this in the in-page click
+ * handler - right before the Block's own act() actually starts. Dan: "i
+ * want the button, step is running thing. so i wont be able to interrupt
+ * the playwright automation" - the "Run this step" button used to sit
+ * there still looking clickable for the entire multi-second duration a
+ * real act()/observe() takes, inviting a confusing extra click (harmless -
+ * __wgNext no-ops once already consumed - but looked live when it wasn't).
+ * Disables the button and mem-key textareas, and swaps whichever gate
+ * text was showing (manual button or "Auto-advancing...") to "Running...".
+ */
+async function markStepRunning(page) {
+  await page
+    .evaluate(() => {
+      const runBtn = document.getElementById("wg-run");
+      if (runBtn) {
+        runBtn.disabled = true;
+        runBtn.textContent = "Running \\u25B6";
+      }
+      const autoEl = document.getElementById("wg-gate-auto");
+      if (autoEl) autoEl.textContent = "Running...";
+      document.querySelectorAll("#wg-panel textarea[data-key]").forEach((ta) => {
+        ta.disabled = true;
+      });
+    })
+    .catch(() => {});
+}
+
 async function showRing(page, box, label) {
   await page
     .evaluate(
@@ -1204,7 +1410,16 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing) {
       } catch {
         // best-effort - the real click below still runs either way
       }
-      if (clickPoint) await clickPulseAt(page, clickPoint.x, clickPoint.y);
+      if (clickPoint) {
+        await clickPulseAt(page, clickPoint.x, clickPoint.y);
+        // clickPulseAt only triggers the CSS animation class - it doesn't
+        // wait for it. Without a pause here, the real click (and any
+        // resulting navigation/DOM change) fires while the ripple is still
+        // mid-animation, sometimes cutting it off before it's even visible.
+        // Wait out the same .5s the "@keyframes wg-pulse" rule uses, so the
+        // mock click visually completes before the real one fires.
+        await new Promise((res) => setTimeout(res, pacing.fast ? 0 : 500));
+      }
       const result = await originalClick.call(this, options);
       await new Promise((res) => setTimeout(res, clickPostPop()));
       await hideRing(page);
@@ -1275,6 +1490,28 @@ function instrumentInteractionHighlighting(page, mem, slowMo, pacing) {
   }
 }
 
+/**
+ * Clears cookies + storage and re-navigates to a known-fresh page. Shared by
+ * the per-block session-reset check below and by the error panel's own
+ * "Retry Episode" button - a retry needs the exact 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.
+ */
+async function resetPageState(context, page, baseURL) {
+  await context.clearCookies().catch(() => {});
+  await page
+    .evaluate(() => {
+      try {
+        localStorage.clear();
+        sessionStorage.clear();
+      } catch {
+        /* storage blocked (e.g. about:blank) - nothing to clear anyway */
+      }
+    })
+    .catch(() => {});
+  await page.goto(baseURL || "about:blank").catch(() => {});
+}
+
 async function runStepMode(engine, start, end, context, page, mem, resolved, slowMo, title, fastBlockNames, clearSession, baseURL) {
   // A shared, mutable pacing knob the interaction patches read live (per
   // call, not once at setup) - flipped per-block below so one block (e.g.
@@ -1351,10 +1588,46 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   };
   const allNames = resolved.map((r) => r.block.name);
   const allDescriptions = resolved.map((r) => r.block.description || "");
+  // Deduped, in-order list of every real episode this chain touches - for
+  // the episode tab bar. Ad hoc block segments (no named Flow) carry no
+  // episodeNumber and never appear here, same gate the "Episode N:"
+  // heading already used.
+  const allEpisodes = [];
+  for (const r of resolved) {
+    if (r.episodeNumber && !allEpisodes.some((e) => e.episodeNumber === r.episodeNumber)) {
+      allEpisodes.push({ episodeNumber: r.episodeNumber, episodeTitle: r.episodeTitle });
+    }
+  }
 
   let result;
   for (let i = 0; i < resolved.length; i++) {
     const r = resolved[i];
+    // The block breadcrumb is scoped to THIS step's own episode, not the
+    // whole chain - within episode 2, step 1 should read as "1st of 2,"
+    // not "6th of 7." Falls back to the whole chain when this block has no
+    // episode (an ad hoc chain with no named Flows), unchanged from before.
+    const episodeBlockIndices = r.episodeNumber
+      ? resolved.reduce((acc, x, idx) => {
+          if (x.episodeNumber === r.episodeNumber) acc.push(idx);
+          return acc;
+        }, [])
+      : resolved.map((_x, idx) => idx);
+    const moduleNames = episodeBlockIndices.map((idx) => allNames[idx]);
+    const moduleDescriptions = episodeBlockIndices.map((idx) => allDescriptions[idx]);
+    const moduleIndex = episodeBlockIndices.indexOf(i);
+    // Where a "Retry Episode" click (see the catch block below) rewinds to -
+    // the current episode's own first block, or the whole chain's first
+    // block when there's no real episode (episodeBlockIndices degrades to
+    // the full resolved array in that case, so this is just 0).
+    const episodeStartIndex = episodeBlockIndices[0];
+    // True only on an episode's own first block - the one moment worth a
+    // gentle "you're here now" signal, not every step inside it.
+    const justEnteredEpisode = moduleIndex === 0 && r.episodeNumber !== undefined;
+    // Seed THIS segment's own json payload now, not earlier - see the long
+    // comment where seedMem closures are built, in main()'s resolution
+    // loop. Must run before "keys" below reads mem.get() for the panel
+    // display, and before this segment's own first block executes.
+    if (r.seedMem) r.seedMem();
     // Reset session state before this block if EITHER: the blanket
     // WAYGRAPH_CLEAR_SESSION=1 override is set (a manual, always-on-after-
     // the-first-block stopgap for ad hoc block chains with no real Flow
@@ -1373,22 +1646,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     // look fresh again - clearing storage alone doesn't change what's
     // still rendered on screen.
     if ((clearSession || r.resetSession) && i > 0) {
-      await context.clearCookies().catch(() => {});
-      await page
-        .evaluate(() => {
-          try {
-            localStorage.clear();
-            sessionStorage.clear();
-          } catch {
-            /* storage blocked (e.g. about:blank) - nothing to clear anyway */
-          }
-        })
-        .catch(() => {});
-      if (baseURL) {
-        await page.goto(baseURL).catch(() => {});
-      } else {
-        await page.goto("about:blank").catch(() => {});
-      }
+      await resetPageState(context, page, baseURL);
     }
     pacing.fast = fastBlockNames.has(r.block.name);
     const requires = r.block.requires ?? [];
@@ -1407,8 +1665,11 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       blockName: r.block.name,
       description: r.block.description || "",
       keys,
-      allNames,
-      allDescriptions,
+      allNames: moduleNames,
+      allDescriptions: moduleDescriptions,
+      moduleIndex,
+      allEpisodes,
+      justEnteredEpisode,
       title,
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
@@ -1423,6 +1684,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         }
       }
     }
+    await markStepRunning(page);
     const stepFlow = engine.defineFlow([start, r.block, end]);
     // { closeOnFinish: false } makes Flow.run return { result, page }, not
     // the plain checkpoint - destructure it, don't treat the wrapper as the
@@ -1441,11 +1703,24 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         total: resolved.length,
         blockName: r.block.name,
         message: err && err.message ? err.message : String(err),
-        allNames,
-        allDescriptions,
+        allNames: moduleNames,
+        allDescriptions: moduleDescriptions,
+        moduleIndex,
+        allEpisodes,
         title,
+        episodeNumber: r.episodeNumber,
+        episodeTitle: r.episodeTitle,
+        expectedFailureReason: r.expectedFailureReason,
       });
-      await 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);
+        i = episodeStartIndex - 1;
+        continue;
+      }
       throw err;
     }
     result = stepOutcome.result;
@@ -1458,8 +1733,10 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       resultTag: JSON.stringify(result),
       highlights,
       isLast: i === resolved.length - 1,
-      allNames,
-      allDescriptions,
+      allNames: moduleNames,
+      allDescriptions: moduleDescriptions,
+      moduleIndex,
+      allEpisodes,
       title,
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
@@ -1484,7 +1761,11 @@ async function main() {
   if (bareRef) {
     const flow = await findFlow(projectDir, bareRef);
     if (flow && typeof flow.blocks === "function") {
-      resolved = flow.blocks().map((bi) => ({ block: bi.block, exportName: bi.name }));
+      resolved = flow.blocks().map((bi) => ({
+        block: bi.block,
+        exportName: bi.name,
+        expectedFailureReason: flow.expectedFailureReason,
+      }));
       console.log(
         "waygraph: running existing flow \\"" + bareRef + "\\" - " +
           resolved.map((r) => r.block.name).join(" -> ") + " (" + resolved.length + " block" +
@@ -1517,37 +1798,62 @@ async function main() {
     // "Episode 2" labels on things that were never episodes to begin with.
     const flowMeta = [];
     let episodeCounter = 0;
+    // seedMem is a closure, NOT called here - seeding every segment's own
+    // json payload eagerly, all upfront during resolution, was a real bug:
+    // mem is one shared object, so when two segments require the SAME key
+    // (e.g. two segments both requiring LoginCreds, each with a DIFFERENT
+    // payload - "login as standard_user then login as locked_out_user"),
+    // the LAST segment resolved silently overwrote the first's value
+    // before either segment had even started running - so the FIRST
+    // segment's own blocks would run against the SECOND segment's
+    // credentials. Deferred to execution time instead (runStepMode calls
+    // this exactly once, right as each segment's first block is reached -
+    // see resolved[i].seedMem below), same moment session-reset already
+    // happens for the same reason.
     for (const seg of segments) {
       const flow = await findFlow(projectDir, seg.ref);
       if (flow && typeof flow.blocks === "function") {
-        seedMemForFlow(mem, flow.blocks(), seg.json, seg.ref);
         flows.push(flow);
         episodeCounter += 1;
-        flowMeta.push({ episodeNumber: episodeCounter, episodeTitle: flow.title || seg.ref });
+        flowMeta.push({
+          episodeNumber: episodeCounter,
+          episodeTitle: flow.title || seg.ref,
+          expectedFailureReason: flow.expectedFailureReason,
+          seedMem: () => seedMemForFlow(mem, flow.blocks(), seg.json, seg.ref),
+        });
       } else {
         const r = await findBlock(projectDir, seg.ref);
-        seedMemForBlock(mem, r, seg.json);
         flows.push(wrapEngine.defineFlow([start, r.block, end]));
-        flowMeta.push(null);
+        flowMeta.push({
+          episodeNumber: undefined,
+          episodeTitle: undefined,
+          seedMem: () => seedMemForBlock(mem, r, seg.json),
+        });
       }
     }
     const combinedBlocks = chainFlow(...flows).blocks();
     let fi = 0;
     let remainingInFlow = flows[0].blocks().length;
+    let isFirstOfSegment = true;
     resolved = combinedBlocks.map((bi) => {
       while (remainingInFlow === 0) {
         fi += 1;
         remainingInFlow = flows[fi].blocks().length;
+        isFirstOfSegment = true;
       }
-      remainingInFlow -= 1;
       const meta = flowMeta[fi];
-      return {
+      const entry = {
         block: bi.block,
         exportName: bi.name,
         resetSession: bi.resetSessionBefore === true,
-        episodeNumber: meta ? meta.episodeNumber : undefined,
-        episodeTitle: meta ? meta.episodeTitle : undefined,
+        episodeNumber: meta.episodeNumber,
+        episodeTitle: meta.episodeTitle,
+        expectedFailureReason: meta.expectedFailureReason,
+        seedMem: isFirstOfSegment ? meta.seedMem : undefined,
       };
+      remainingInFlow -= 1;
+      isFirstOfSegment = false;
+      return entry;
     });
     console.log(
       "waygraph: chaining " + resolved.map((r) => r.block.name).join(" -> ") +
@@ -1586,6 +1892,19 @@ async function main() {
   const clearSession = process.env.WAYGRAPH_CLEAR_SESSION === "1";
   const engine = new Engine({ headless: !headed, slowMo });
   let result;
+  // Non-interactive execution (no --step) runs the whole chain as one
+  // composed flow with no per-block loop of its own to defer seeding
+  // into - it can't support two segments needing DIFFERENT values for the
+  // SAME mem key (e.g. two segments both requiring LoginCreds, each with
+  // its own payload). Fall back to seeding every segment eagerly, upfront -
+  // the same limitation "chain" always had; only --step's own runStepMode
+  // loop actually needs (and correctly supports, via resolved[i].seedMem)
+  // per-segment differentiated values.
+  if (!step) {
+    for (const r of resolved) {
+      if (r.seedMem) r.seedMem();
+    }
+  }
   if (step || baseURL) {
     const { chromium } = await import("playwright");
     // --start-maximized (step mode only): viewport: null alone only made
@@ -1667,6 +1986,111 @@ async function runChain(projectDir, spec) {
         rmSync(scriptPath, { force: true });
     }
 }
+// ---------------------------------------------------------------------------
+// `try` - a bundled, self-contained showcase. No .flow.ts to write, no
+// scenario to design - copies a small real Flow (nav/action Blocks, Trait
+// verify, narrate()) into the target project and runs it in step mode
+// against a public demo site, so a curious dev sees the real overlay/panel
+// experience in under a minute, then gets pointed at the plain waygraph
+// source that produced it.
+// ---------------------------------------------------------------------------
+/** This package's own installed root - dist/cli.js -> .. */
+function packageRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+/**
+ * Runs a throwaway probe script rooted at `projectDir` - the exact same
+ * directory the real demo files get copied into, so it resolves "waygraph"
+ * and "@playwright/test" exactly as they will - and actually launches (then
+ * immediately closes) chromium, a real check rather than a guess at whether
+ * the browser's installed. Returns null when everything's ready, or a
+ * friendly, actionable message naming exactly what to install when it
+ * isn't. Never leaves the probe script behind.
+ */
+async function checkTryPrereqs(projectDir) {
+    const tsxEsm = import.meta.resolve("tsx/esm");
+    const probeScript = [
+        "try {",
+        '  await import("waygraph");',
+        "} catch {",
+        '  console.error("WAYGRAPH_TRY_MISSING_WAYGRAPH");',
+        "  process.exit(1);",
+        "}",
+        "let mod;",
+        "try {",
+        '  mod = await import("@playwright/test");',
+        "} catch {",
+        '  console.error("WAYGRAPH_TRY_MISSING_PLAYWRIGHT_TEST");',
+        "  process.exit(1);",
+        "}",
+        "try {",
+        "  const browser = await mod.chromium.launch({ headless: true });",
+        "  await browser.close();",
+        "} catch (err) {",
+        "  if (String(err && err.message).includes(\"Executable doesn't exist\")) {",
+        '    console.error("WAYGRAPH_TRY_MISSING_BROWSER");',
+        "    process.exit(1);",
+        "  }",
+        "  console.error(String((err && err.stack) || err));",
+        "  process.exit(1);",
+        "}",
+    ].join("\n");
+    const probePath = join(projectDir, `.waygraph-try-probe-${process.pid}.mjs`);
+    writeFileSync(probePath, probeScript);
+    try {
+        const result = await new Promise((res, rej) => {
+            const child = spawn(process.execPath, ["--import", tsxEsm, probePath], {
+                cwd: projectDir,
+                stdio: ["ignore", "ignore", "pipe"],
+                env: process.env,
+            });
+            let stderrBuf = "";
+            child.stderr?.on("data", (d) => { stderrBuf += d.toString(); });
+            child.on("error", rej);
+            child.on("exit", (code) => res({ code: code ?? 1, stderr: stderrBuf }));
+        });
+        if (result.code === 0)
+            return null;
+        const stderr = result.stderr;
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_WAYGRAPH")) {
+            return `"waygraph" isn't resolvable as a dependency from ${projectDir}.\nRun this first, inside that directory:\n  npm install waygraph\n  npm install -D @playwright/test\n  npx playwright install chromium`;
+        }
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_PLAYWRIGHT_TEST")) {
+            return `"@playwright/test" isn't resolvable as a dependency from ${projectDir}.\nRun this first, inside that directory:\n  npm install -D @playwright/test\n  npx playwright install chromium`;
+        }
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_BROWSER")) {
+            return "Playwright's chromium browser isn't installed yet.\nRun this first:\n  npx playwright install chromium";
+        }
+        return `couldn't verify prerequisites:\n${stderr.trim()}`;
+    }
+    finally {
+        rmSync(probePath, { force: true });
+    }
+}
+async function runTry(projectDir) {
+    const problem = await checkTryPrereqs(projectDir);
+    if (problem) {
+        console.error(`waygraph try: not ready yet.\n${problem}`);
+        process.exitCode = 1;
+        return;
+    }
+    const destDir = join(projectDir, ".waygraph-quickstart");
+    // Regenerated fresh every run (like chain's own .waygraph-chain-<pid>.mjs)
+    // so an updated waygraph version's demo never goes stale - not meant to be
+    // hand-edited and kept, just a real, readable copy to point people at.
+    cpSync(join(packageRoot(), "templates", "quickstart"), destDir, { recursive: true });
+    process.env.WAYGRAPH_HEADED ??= "1";
+    process.env.WAYGRAPH_STEP ??= "1";
+    process.env.WAYGRAPH_AUTOPLAY ??= "1";
+    process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
+    await runChain(destDir, "quickstartFlow");
+    if (!process.exitCode) {
+        console.log("\nwaygraph try: that's plain waygraph - defineNavBlock, defineBlock, Trait, connect() - nothing hidden.\n" +
+            "See the code that just ran:\n" +
+            "  " + join(destDir, "src", "flows", "quickstart.flow.ts") + "\n" +
+            "  " + join(destDir, "src", "blocks"));
+    }
+}
 async function validateFlows(projectDir) {
     const files = discoverFlows(projectDir);
     const results = [];
@@ -1687,6 +2111,64 @@ async function validateFlows(projectDir) {
     return results;
 }
 // ---------------------------------------------------------------------------
+// `check` - secondary/complementary to the ActionPage @deprecated warning
+// (src/types.ts). That's the primary, always-on signal an editor shows the
+// instant a regular Block's act() calls a navigation method; this command
+// sweeps a whole project in one shot for contexts with no editor watching
+// (CI, an autonomous agent writing Block files without a language server).
+// See openspec/changes/nav-block-and-check/ for the full rationale.
+// ---------------------------------------------------------------------------
+function discoverBlocks(projectDir) {
+    return walkDir(projectDir, /\.block\.ts$/);
+}
+function isBlockLike(val) {
+    if (val === null || typeof val !== "object")
+        return false;
+    const obj = val;
+    if (typeof obj.name !== "string")
+        return false;
+    const instruction = obj.instruction;
+    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
+}
+/** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
+function isNavBlockMarked(val) {
+    return val.__waygraphKind === "nav";
+}
+const NAV_METHOD_CALLS = ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
+/**
+ * Walks every `*.block.ts` file under `projectDir`, imports each to find its
+ * exported Blocks, and for any Block NOT built via `defineNavBlock`, scans
+ * that file's own source text for a navigation call. Warning only - never
+ * throws, never changes the caller's exit code on its own account (a Block
+ * file that fails to import for unrelated reasons is silently skipped here;
+ * `validate` is the command that reports import failures).
+ */
+async function checkCommand(projectDir) {
+    const files = discoverBlocks(projectDir);
+    const warnings = [];
+    for (const file of files) {
+        let mod;
+        try {
+            mod = await importModule(file);
+        }
+        catch {
+            continue;
+        }
+        let src;
+        for (const [exportName, exported] of Object.entries(mod)) {
+            if (!isBlockLike(exported))
+                continue;
+            if (isNavBlockMarked(exported))
+                continue;
+            src ??= readFileSync(file, "utf-8");
+            if (NAV_METHOD_CALLS.some((needle) => src.includes(needle))) {
+                warnings.push({ file, blockName: exported.name, exportName });
+            }
+        }
+    }
+    return warnings;
+}
+// ---------------------------------------------------------------------------
 // `run`
 // ---------------------------------------------------------------------------
 async function runFlow(projectDir, flowName) {
@@ -1725,6 +2207,28 @@ Usage:
   waygraph validate [project]     Import and validate all flows
   waygraph run <flow> [project]   Run a named flow
   waygraph chain <spec> [project] Run one or more Blocks by name, ad hoc
+  waygraph check   [project]      Warn about navigation outside a NavBlock
+  waygraph try     [project]      Quickstart showcase - no setup beyond
+                                  "waygraph" + "@playwright/test" installed
+                                  in [project] (default: cwd) and its
+                                  chromium browser downloaded. Checks both
+                                  for real (a real launch+close, not a
+                                  guess) and tells you exactly what to run
+                                  if either's missing, instead of a raw
+                                  Playwright stack trace. If ready, copies a
+                                  small real Flow (nav/action Blocks, Trait
+                                  verify, narrate()) into
+                                  [project]/.waygraph-quickstart/ and runs
+                                  it in step mode against a public demo
+                                  site - then prints the absolute path to
+                                  that plain waygraph source, so whoever's
+                                  watching can go read exactly how it works.
+
+    "check" is a secondary sweep, complementary to the always-on TypeScript
+    warning every regular Block's act() already gets (a struck-through
+    page.goto/reload/goBack/goForward, pointing at defineNavBlock) - useful
+    where nothing is watching in an editor (CI, generated code). Warning
+    only, never fails - see openspec/changes/nav-block-and-check/.
 
     "chain" needs no .flow.ts file - reference Blocks (by their own
     runtime .name, or their export identifier) straight from the command
@@ -1844,6 +2348,32 @@ async function main() {
             await runChain(proj, spec);
             break;
         }
+        case "try": {
+            const proj = resolve(args[1] ?? process.cwd());
+            if (!existsSync(proj)) {
+                console.error(`waygraph: no such directory: ${proj}`);
+                process.exit(1);
+            }
+            await runTry(proj);
+            break;
+        }
+        case "check": {
+            const proj = resolve(args[1] ?? process.cwd());
+            const warnings = await checkCommand(proj);
+            if (warnings.length === 0) {
+                console.log(`waygraph check: no navigation found outside NavBlocks under ${proj}`);
+            }
+            else {
+                for (const w of warnings) {
+                    const rel = relative(proj, w.file);
+                    console.warn(`waygraph check: ${rel} (${w.blockName}) calls page.goto/reload/goBack/goForward outside a NavBlock - consider defineNavBlock instead`);
+                }
+                console.log(`waygraph check: ${warnings.length} warning${warnings.length === 1 ? "" : "s"}`);
+            }
+            // Warning only - never fails the command, matching the spec's
+            // "never a build failure" requirement.
+            break;
+        }
         default:
             console.error(`waygraph: unknown command "${command}"`);
             process.exit(1);