waygraph 0.5.0 → 0.7.0

package/README.md

@@ -103,9 +103,16 @@ a fresh tab (the run won't close a page you handed it unless you say so), and
 so the caller can keep driving it - hands a run tab back instead of losing it. See
 "Recipes" for capture-on-popup, which stays a documented pattern until a second real use
 case promotes it to an engine API.
-`defineNavBlock({ name, checkpoint, url })` builds a Block whose only possible action is
-navigating - `url` accepts a plain string or `(mem) => string` for parameterized routes,
-and the generated `act()` is always exactly `page.goto(url)`, never author-supplied. A
+`defineNavBlock({ name, checkpoint, url })` or `defineNavBlock({ name, checkpoint, click })`
+builds a Block whose only possible action is navigating - exactly one of `url`/`click` is
+required, enforced at compile time. Both accept a plain string or `(mem) => string`/
+`(mem) => selector` for parameterized routes; the generated `act()` is always exactly
+`page.goto(url)` or `page.locator(click).click()`, never author-supplied. `click` is the
+opinionated default - navigating by clicking a real element already on the page (a nav
+link, a sidebar item) instead of teleporting straight to a URL, so a Block actually proves
+the app's own navigation path works instead of skipping past it. `url` still exists for the
+real cases with no click path to get there (a deep link from an email, a public share
+link). A
 regular `defineBlock`'s `act()` receives its `page` typed as `ActionPage` instead of raw
 `Page` - structurally identical, every method still fully present and callable, except
 `goto`/`reload`/`goBack`/`goForward` are re-declared `@deprecated`, so a TypeScript-aware

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,162 @@ 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. Never leaves the probe script behind.
+ */
+async function probeTryPrereqs(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 { ok: true };
+        const stderr = result.stderr;
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_WAYGRAPH"))
+            return { ok: false, missing: "waygraph" };
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_PLAYWRIGHT_TEST"))
+            return { ok: false, missing: "playwright-test" };
+        if (stderr.includes("WAYGRAPH_TRY_MISSING_BROWSER"))
+            return { ok: false, missing: "browser" };
+        return { ok: false, missing: "unknown", detail: stderr.trim() || `probe exited with code ${result.code}` };
+    }
+    finally {
+        rmSync(probePath, { force: true });
+    }
+}
+/** Spawns with inherited stdio (the real npm/playwright output, visible) and resolves to its exit code. */
+function runInherited(cmd, args, cwd) {
+    return new Promise((res, rej) => {
+        const child = spawn(cmd, args, { cwd, stdio: "inherit", env: process.env });
+        child.on("error", rej);
+        child.on("exit", (code) => res(code ?? 1));
+    });
+}
+/**
+ * `waygraph try` is meant to be a genuine one-shot `npx waygraph try` -
+ * no separate init/install step the human has to remember, the same shape
+ * as `npm create vite@latest`. Probes first; anything missing gets
+ * installed right here (a minimal package.json if none exists, then
+ * `npm install waygraph @playwright/test`, then Playwright's own chromium
+ * download), with the real install output visible the whole time - not
+ * silent, just not a separate step you have to run yourself first. Returns
+ * null once everything's actually ready, or a message naming whatever
+ * still isn't after really trying.
+ */
+async function ensureTryPrereqs(projectDir) {
+    let status = await probeTryPrereqs(projectDir);
+    if (status.ok)
+        return null;
+    if (status.missing === "unknown") {
+        return `couldn't verify prerequisites:\n${status.detail}`;
+    }
+    if (status.missing === "waygraph" || status.missing === "playwright-test") {
+        if (!existsSync(join(projectDir, "package.json"))) {
+            writeFileSync(join(projectDir, "package.json"), JSON.stringify({ name: basename(projectDir) || "waygraph-quickstart", private: true, type: "module" }, null, 2) + "\n");
+            console.log(`waygraph try: no package.json in ${projectDir} - created a minimal one.`);
+        }
+        console.log(`waygraph try: installing waygraph + @playwright/test in ${projectDir} ...`);
+        const installCode = await runInherited("npm", ["install", "waygraph", "@playwright/test"], projectDir);
+        if (installCode !== 0) {
+            return `npm install exited with code ${installCode} - see the output above.`;
+        }
+        status = await probeTryPrereqs(projectDir);
+        if (status.ok)
+            return null;
+        if (status.missing === "unknown")
+            return `couldn't verify prerequisites:\n${status.detail}`;
+    }
+    // Only the browser can still be missing at this point.
+    console.log("waygraph try: downloading Playwright's chromium browser ...");
+    const localPlaywrightBin = join(projectDir, "node_modules", ".bin", "playwright");
+    const browserCode = existsSync(localPlaywrightBin)
+        ? await runInherited(localPlaywrightBin, ["install", "chromium"], projectDir)
+        : await runInherited("npx", ["--yes", "playwright", "install", "chromium"], projectDir);
+    if (browserCode !== 0) {
+        return `"playwright install chromium" exited with code ${browserCode} - see the output above.`;
+    }
+    status = await probeTryPrereqs(projectDir);
+    if (status.ok)
+        return null;
+    return status.detail ?? "prerequisites still aren't ready after attempting to install them.";
+}
+async function runTry(projectDir) {
+    const problem = await ensureTryPrereqs(projectDir);
+    if (problem) {
+        console.error(`waygraph try: couldn't get ready.\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 = [];
@@ -1784,6 +2259,25 @@ Usage:
   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]      One-shot quickstart showcase - genuinely
+                                  "npx waygraph try", no separate init step.
+                                  Checks (a real launch+close, not a guess)
+                                  whether "waygraph" + "@playwright/test"
+                                  resolve from [project] (default: cwd) and
+                                  its chromium browser is downloaded; if
+                                  anything's missing, installs it right
+                                  there (writes a minimal package.json if
+                                  [project] doesn't have one yet, then
+                                  npm install, then the browser download),
+                                  real output visible the whole time. Once
+                                  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
@@ -1909,6 +2403,15 @@ 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);

package/dist/engine.d.ts

@@ -170,6 +170,16 @@ export interface Flow<Out extends Checkpoint<string>> {
      * something `run()` itself uses.
      */
     readonly title?: string;
+    /**
+     * Set once this Flow has been wrapped in {@link withExpectedFailure} - a
+     * display hint for a step-through overlay: this Flow is DESIGNED to throw
+     * (e.g. a blocked user's login attempt genuinely failing), not a bug in
+     * the demo itself. `run()` never reads this - the Flow still throws
+     * exactly as it would otherwise; only the overlay's error panel reads it,
+     * to show an informational "this is the point" panel instead of an
+     * alarming one indistinguishable from a real break.
+     */
+    readonly expectedFailureReason?: string;
     /**
      * This Flow's constituent Blocks, in order between `start`/`end`, as plain
      * data - for introspection/visualization tools, without running anything.
@@ -237,6 +247,25 @@ export declare function withSessionReset<Out extends Checkpoint<string>>(flow: F
  * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
  */
 export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out>, title: string): Flow<Out>;
+/**
+ * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
+ * login attempt genuinely failing, demonstrating the app's own real
+ * behavior rather than a bug in the demo. Non-destructive, same pattern as
+ * {@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."
+ * @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.",
+ * );
+ */
+export declare function withExpectedFailure<Out extends Checkpoint<string>>(flow: Flow<Out>, reason: string): Flow<Out>;
 /**
  * Runs several complete, independent Flows one after another, reusing the
  * same page/context/mem in order - each remains its own validated
@@ -415,31 +444,59 @@ export declare function defineBlock<In extends Checkpoint<string>, Out extends C
  */
 export type NavBlock<Out extends Checkpoint<string>> = DefinedBlock<Checkpoint<string>, Out>;
 /**
- * Builds a {@link NavBlock}. `url` accepts a plain string or a function
- * `(mem) => string` for parameterized routes (e.g. `/dashboard/requests/:id`
- * with a real id read from mem). `checkpoint` is the tag this NavBlock
+ * `defineNavBlock`'s own options - exactly one of `url`/`click` required,
+ * enforced at compile time (giving both, or neither, is a type error - see
+ * `typecheck/nav-block.types.ts`). `checkpoint` is the tag this NavBlock
  * resolves to once navigation completes - a NavBlock never branches on
  * observed evidence the way a regular Block can, so there's no `resolve`
  * logic to author; it always just declares "arrived."
- *
- * The generated `act()` is always exactly `page.goto(url)` - never anything
- * else, never author-supplied. Callers get a real `Page` here internally
- * (the one legitimate place navigation belongs); `defineBlock`'s own
- * `ActionPage` narrowing is what discourages navigation everywhere else,
- * and never applies to this generated function since no author ever writes
- * it by hand.
- * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
- * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
  */
-export declare function defineNavBlock<Out extends Checkpoint<string>>(options: {
+export type NavBlockOptions<Out extends Checkpoint<string>> = {
     name: string;
     description?: string;
     checkpoint: Out["__state"];
-    url: string | ((mem: MemPage) => string);
     requires?: readonly MemKey<any>[];
     verify?: Trait[] | ((out: Out) => Trait[]);
     highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
-}): NavBlock<Out>;
+} & ({
+    /**
+     * Direct URL navigation. Accepts a plain string or a function
+     * `(mem) => string` for parameterized routes (e.g.
+     * `/dashboard/requests/:id` with a real id read from mem). The
+     * escape hatch for the few real cases with no click path to get
+     * there (a deep link from an email, a public share link) - not for
+     * skipping past navigation an agent didn't feel like finding. Prefer
+     * `click` whenever the target app actually has one.
+     */
+    url: string | ((mem: MemPage) => string);
+    click?: never;
+} | {
+    /**
+     * Navigates by clicking a real element already on the page (a nav
+     * link, a sidebar item) instead of teleporting straight to a URL -
+     * the opinionated default. Accepts a Playwright selector string, or
+     * a function `(mem) => selector` for a target that depends on mem
+     * (e.g. clicking the row for a specific id). Verifying arrival is
+     * `verify`'s job (typically `Trait.url(...)`), same as a `url`-based
+     * NavBlock - the click itself is only ever awaited for its own
+     * completion, not for whatever navigation it triggers.
+     */
+    click: string | ((mem: MemPage) => string);
+    url?: never;
+});
+/**
+ * Builds a {@link NavBlock}. The generated `act()` is always exactly
+ * `page.goto(url)` or `page.locator(click).click()` - never anything else,
+ * never author-supplied. Callers get a real `Page` here internally (the one
+ * legitimate place navigation belongs); `defineBlock`'s own `ActionPage`
+ * narrowing is what discourages navigation everywhere else, and never
+ * applies to this generated function since no author ever writes it by
+ * hand.
+ * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
+ * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
+ * @example defineNavBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ */
+export declare function defineNavBlock<Out extends Checkpoint<string>>(options: NavBlockOptions<Out>): NavBlock<Out>;
 /**
  * Returns a new Block that runs exactly like `block` - same act/observe/resolve,
  * same routing - but with `verify` replaced. For giving one flow stricter (or

package/dist/engine.js

@@ -341,6 +341,32 @@ export function withTitle(flow, title) {
         modBlockVerify: (block, nameOrIndex, newCheck) => withTitle(flow.modBlockVerify(block, nameOrIndex, newCheck), title),
     };
 }
+/**
+ * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
+ * login attempt genuinely failing, demonstrating the app's own real
+ * behavior rather than a bug in the demo. Non-destructive, same pattern as
+ * {@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."
+ * @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.",
+ * );
+ */
+export function withExpectedFailure(flow, reason) {
+    return {
+        ...flow,
+        expectedFailureReason: reason,
+        withBlockVerify: (block, verify) => withExpectedFailure(flow.withBlockVerify(block, verify), reason),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withExpectedFailure(flow.modBlockVerify(block, nameOrIndex, newCheck), reason),
+    };
+}
 function locateInChain(flows, block) {
     if (typeof block === "number") {
         let remaining = block;
@@ -583,21 +609,16 @@ export function defineBlock(base) {
     };
 }
 /**
- * Builds a {@link NavBlock}. `url` accepts a plain string or a function
- * `(mem) => string` for parameterized routes (e.g. `/dashboard/requests/:id`
- * with a real id read from mem). `checkpoint` is the tag this NavBlock
- * resolves to once navigation completes - a NavBlock never branches on
- * observed evidence the way a regular Block can, so there's no `resolve`
- * logic to author; it always just declares "arrived."
- *
- * The generated `act()` is always exactly `page.goto(url)` - never anything
- * else, never author-supplied. Callers get a real `Page` here internally
- * (the one legitimate place navigation belongs); `defineBlock`'s own
- * `ActionPage` narrowing is what discourages navigation everywhere else,
- * and never applies to this generated function since no author ever writes
- * it by hand.
+ * Builds a {@link NavBlock}. The generated `act()` is always exactly
+ * `page.goto(url)` or `page.locator(click).click()` - never anything else,
+ * never author-supplied. Callers get a real `Page` here internally (the one
+ * legitimate place navigation belongs); `defineBlock`'s own `ActionPage`
+ * narrowing is what discourages navigation everywhere else, and never
+ * applies to this generated function since no author ever writes it by
+ * hand.
  * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
  * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
+ * @example defineNavBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
  */
 export function defineNavBlock(options) {
     const built = defineBlock({
@@ -606,8 +627,14 @@ export function defineNavBlock(options) {
         ...(options.requires ? { requires: options.requires } : {}),
         instruction: {
             async act(page, _input, mem) {
-                const url = typeof options.url === "function" ? options.url(mem) : options.url;
-                await page.goto(url);
+                if (options.url !== undefined) {
+                    const url = typeof options.url === "function" ? options.url(mem) : options.url;
+                    await page.goto(url);
+                }
+                else {
+                    const selector = typeof options.click === "function" ? options.click(mem) : options.click;
+                    await page.locator(selector).click();
+                }
             },
             resolve: () => checkpoint(options.checkpoint),
             ...(options.verify ? { verify: options.verify } : {}),

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start } from "./type
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, composeBlock, preflight, withSessionReset, withTitle, chainFlow, } from "./engine.js";
-export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions } from "./engine.js";
 export type { ActionPage } from "./types.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, composeBlock, preflight, withSessionReset, withTitle, chainFlow, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "main": "./dist/index.js",
@@ -16,7 +16,8 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "templates"
   ],
   "repository": {
     "type": "git",

package/templates/quickstart/src/blocks/actions/add-to-cart.action.block.ts

@@ -0,0 +1,18 @@
+import { defineBlock, checkpoint, Trait } from "waygraph";
+import type { LoggedIn, ItemInCart } from "../../states/quickstart.states.js";
+
+export const AddToCartBlock = defineBlock<LoggedIn, ItemInCart>({
+  name: "add-to-cart",
+  description: "Adds the Sauce Labs Backpack to the cart and confirms the cart badge shows 1 item.",
+  instruction: {
+    async act(page) {
+      await page.locator("#add-to-cart-sauce-labs-backpack").click();
+    },
+    resolve: () => checkpoint("ItemInCart"),
+    verify: [Trait.text(".shopping_cart_badge", "1")],
+    // Author-declared highlights - independent of verify's own pass/fail
+    // check. "Remember this" moments a step-through overlay can call out
+    // even when there's nothing to assert, just something worth pointing at.
+    highlights: () => [{ selector: ".shopping_cart_badge", label: "remember this: cart now has 1 item" }],
+  },
+});

package/templates/quickstart/src/blocks/actions/checkout-info.action.block.ts

@@ -0,0 +1,19 @@
+import { defineBlock, checkpoint, Trait } from "waygraph";
+import type { ItemInCart, CheckoutInfoFilled } from "../../states/quickstart.states.js";
+
+export const CheckoutInfoBlock = defineBlock<ItemInCart, CheckoutInfoFilled>({
+  name: "checkout-info",
+  description: "Goes to the cart, starts checkout, and fills in the shipping info form.",
+  instruction: {
+    async act(page) {
+      await page.locator(".shopping_cart_link").click();
+      await page.locator("#checkout").click();
+      await page.locator("#first-name").fill("Ada");
+      await page.locator("#last-name").fill("Lovelace");
+      await page.locator("#postal-code").fill("1000");
+      await page.locator("#continue").click();
+    },
+    resolve: () => checkpoint("CheckoutInfoFilled"),
+    verify: [Trait.url({ pathname: "/checkout-step-two.html" })],
+  },
+});

package/templates/quickstart/src/blocks/actions/finish-order.action.block.ts

@@ -0,0 +1,18 @@
+import { defineBlock, checkpoint, Trait, narrate } from "waygraph";
+import type { CheckoutInfoFilled, OrderComplete } from "../../states/quickstart.states.js";
+
+export const FinishOrderBlock = defineBlock<CheckoutInfoFilled, OrderComplete>({
+  name: "finish-order",
+  description: "Places the order and confirms the 'Thank you for your order!' completion page.",
+  instruction: {
+    async act(page) {
+      // narrate() captions an explicit action for a step-through overlay,
+      // instead of it guessing a generic label from the element's own text.
+      const finishButton = page.locator("#finish");
+      await narrate(finishButton, "Placing the order", () => finishButton.click());
+    },
+    resolve: () => checkpoint("OrderComplete"),
+    verify: [Trait.text(".complete-header", "Thank you for your order!")],
+    highlights: () => [{ selector: ".complete-header", label: "remember this: order confirmed" }],
+  },
+});

package/templates/quickstart/src/blocks/actions/submit-login.action.block.ts

@@ -0,0 +1,22 @@
+import { defineBlock, checkpoint, Trait } from "waygraph";
+import type { LoginPage, LoggedIn } from "../../states/quickstart.states.js";
+
+// Credentials hardcoded on purpose, to keep this first look at waygraph
+// self-contained - no setup step, nothing to type before you can watch it
+// run. A real project reaches for a MemKey/keyGroup instead (see waygraph's
+// own README, or projects_waygraph/saucedemo in this same workspace) so
+// different scenarios (an Owner vs. a blocked Viewer, say) can hand a Flow
+// different credentials at run time without editing the Block itself.
+export const SubmitLoginActionBlock = defineBlock<LoginPage, LoggedIn>({
+  name: "submit-login",
+  description: "Logs a standard user into Swag Labs and confirms the inventory page loads.",
+  instruction: {
+    async act(page) {
+      await page.locator("#user-name").fill("standard_user");
+      await page.locator("#password").fill("secret_sauce");
+      await page.locator("#login-button").click();
+    },
+    resolve: () => checkpoint("LoggedIn"),
+    verify: [Trait.url({ pathname: "/inventory.html" })],
+  },
+});

package/templates/quickstart/src/blocks/nav-login.block.ts

@@ -0,0 +1,15 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { LoginPage } from "../states/quickstart.states.js";
+
+// Navigation lives in its own Block, built by defineNavBlock - its act() is
+// ALWAYS exactly page.goto(url), generated for you, never hand-written. A
+// regular defineBlock() Block that calls page.goto/reload/goBack/goForward
+// instead gets a struck-through @deprecated warning in your editor, pointing
+// back here - see waygraph's ActionPage type and `waygraph check`.
+export const NavLoginBlock = defineNavBlock<LoginPage>({
+  name: "nav-login",
+  description: "Goes to the Swag Labs login page.",
+  checkpoint: "LoginPage",
+  url: "/",
+  verify: [Trait.visible("#login-button")],
+});

package/templates/quickstart/src/flows/quickstart.flow.ts

@@ -0,0 +1,19 @@
+import { Engine, start, end, withTitle } from "waygraph";
+import { NavLoginBlock } from "../blocks/nav-login.block.js";
+import { SubmitLoginActionBlock } from "../blocks/actions/submit-login.action.block.js";
+import { AddToCartBlock } from "../blocks/actions/add-to-cart.action.block.js";
+import { CheckoutInfoBlock } from "../blocks/actions/checkout-info.action.block.js";
+import { FinishOrderBlock } from "../blocks/actions/finish-order.action.block.js";
+
+const engine = new Engine();
+
+// This is it - a whole real waygraph Flow, five Blocks wide, generated by
+// `waygraph try` but otherwise no different from a Flow you'd hand-write:
+// nav-* Blocks (defineNavBlock) navigate, action-* Blocks (defineBlock) do
+// everything else, connect() (here, defineFlow's own array form) chains
+// them into one typed graph, each Block's own Trait verify confirms it
+// actually landed where it says it did.
+export const quickstartFlow = withTitle(
+  engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, AddToCartBlock, CheckoutInfoBlock, FinishOrderBlock, end]),
+  "waygraph quickstart - swag labs demo",
+);

package/templates/quickstart/src/states/quickstart.states.ts

@@ -0,0 +1,11 @@
+import type { Checkpoint } from "waygraph";
+
+// One Checkpoint per real state the target app can be in - the whole shape
+// of this quickstart's Flow, readable in one place before you ever open a
+// Block file. `Start` is waygraph's own exported type, not redeclared here.
+
+export type LoginPage = Checkpoint<"LoginPage">;
+export type LoggedIn = Checkpoint<"LoggedIn">;
+export type ItemInCart = Checkpoint<"ItemInCart">;
+export type CheckoutInfoFilled = Checkpoint<"CheckoutInfoFilled">;
+export type OrderComplete = Checkpoint<"OrderComplete">;