waygraph 0.12.30 → 0.12.32

package/dist/cli.js

@@ -274,12 +274,12 @@ async function findBlock(projectDir, ref) {
   if (byRuntimeName.length === 1) return byRuntimeName[0];
   if (byRuntimeName.length > 1) {
     throw new Error(
-      "waygraph chain: \\"" + ref + "\\" matches " + byRuntimeName.length + " Blocks by name - " +
+      "waygraph chain: \\\"" + ref + "\\\" matches " + byRuntimeName.length + " Blocks by name - " +
         byRuntimeName.map((b) => b.exportName + " (" + b.file + ")").join(", ") +
         ". Use the export name to disambiguate.",
     );
   }
-  throw new Error("waygraph chain: no Block named \\"" + ref + "\\" found under " + projectDir);
+  throw new Error("waygraph chain: no Block named \\\"" + ref + "\\\" found under " + projectDir);
 }
 
 /**
@@ -316,7 +316,7 @@ function parseChainSpec(spec) {
       const m = /^([A-Za-z_$][\\w-]*)\\s*(?:\\(([\\s\\S]*)\\))?$/.exec(s);
       if (!m) {
         throw new Error(
-          "waygraph chain: could not parse segment \\"" + s + "\\" - expected \\"blockName\\" or \\"blockName({...json...})\\"",
+          "waygraph chain: could not parse segment \\\"" + s + "\\\" - expected \\\"blockName\\\" or \\\"blockName({...json...})\\\"",
         );
       }
       const ref = m[1];
@@ -329,7 +329,7 @@ function seedMemFromRequires(mem, requires, json, label) {
   if (requires.length === 0) {
     if (json !== undefined) {
       throw new Error(
-        "waygraph chain: \\"" + label + "\\" takes no input (empty requires) but got a payload: " + json,
+        "waygraph chain: \\\"" + label + "\\\" takes no input (empty requires) but got a payload: " + json,
       );
     }
     return;
@@ -341,7 +341,7 @@ function seedMemFromRequires(mem, requires, json, label) {
       json = fromEnv;
     } else {
       throw new Error(
-        "waygraph chain: \\"" + label + "\\" requires " + requires.map((k) => k.name).join(", ") +
+        "waygraph chain: \\\"" + label + "\\\" requires " + requires.map((k) => k.name).join(", ") +
           " - give a JSON payload (inline blockName({...}) or --data '{...}')",
       );
     }
@@ -350,7 +350,7 @@ function seedMemFromRequires(mem, requires, json, label) {
   try {
     parsed = JSON.parse(json);
   } catch (err) {
-    throw new Error("waygraph chain: \\"" + label + "\\" payload is not valid JSON - " + String(err));
+    throw new Error("waygraph chain: \\\"" + label + "\\\" payload is not valid JSON - " + String(err));
   }
   // Keyed-by-name when every require name is a top-level key (preferred for
   // --data and for {"saucedemo.credentials":{...}} even with one require).
@@ -367,13 +367,13 @@ function seedMemFromRequires(mem, requires, json, label) {
   }
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(
-      "waygraph chain: \\"" + label + "\\" requires " + requires.length + " keys (" +
+      "waygraph chain: \\\"" + label + "\\\" requires " + requires.length + " keys (" +
         requires.map((k) => k.name).join(", ") + ") - payload must be an object keyed by each key's name",
     );
   }
   for (const k of requires) {
     if (!(k.name in parsed)) {
-      throw new Error("waygraph chain: \\"" + label + "\\" payload is missing required key \\"" + k.name + "\\"");
+      throw new Error("waygraph chain: \\\"" + label + "\\\" payload is missing required key \\\"" + k.name + "\\\"");
     }
     mem.set(k, parsed[k.name]);
   }
@@ -415,7 +415,7 @@ const RING_CSS =
   "box-shadow:0 0 0 4px rgba(124,58,237,.16);" +
   "transition:opacity .32s ease,left .28s ease,top .28s ease,width .28s ease,height .28s ease,border-color .15s,box-shadow .32s ease;}" +
   // Unquoted [data-focus=1]: this lives inside CHAIN_RUNNER_SCRIPT's template
-  // literal - a \" here would be eaten by the outer template and break the
+  // literal - a \\" here would be eaten by the outer template and break the
   // generated .mjs. CSS allows unquoted attr values for identifiers.
   "#wg-ring[data-focus=1]{box-shadow:0 0 0 4px rgba(124,58,237,.2),0 0 0 9999px rgba(15,6,32,.55);}" +
   "#wg-ring[data-tone=auto][data-focus=1]{box-shadow:0 0 0 4px rgba(156,163,175,.28),0 0 0 9999px rgba(15,6,32,.55);}" +
@@ -527,6 +527,24 @@ const RING_CSS =
   "#wg-todos .wg-todo-done{color:#6ee7b7;text-decoration:line-through;opacity:.85;}" +
   "#wg-todos .wg-todo-current{color:#fff;}" +
   "#wg-todos .wg-todo-pending{color:#9a7ad1;}" +
+  "#wg-todo-modal{position:fixed;z-index:2147483647;left:14px;bottom:14px;min-width:240px;max-width:min(360px,92vw);" +
+  "padding:14px 16px 12px;background:rgba(18,8,36,.94);color:#f0e8ff;" +
+  "border:1px solid rgba(124,58,237,.55);border-radius:12px;" +
+  "box-shadow:0 12px 40px rgba(0,0,0,.45);backdrop-filter:blur(8px);" +
+  "opacity:0;transform:translateY(8px);pointer-events:none;" +
+  "transition:opacity .28s ease,transform .28s ease;}" +
+  "#wg-todo-modal.wg-todo-on{opacity:1;transform:none;pointer-events:auto;}" +
+  "#wg-todo-modal .wg-todo-head{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
+  "letter-spacing:.04em;text-transform:uppercase;margin:0 0 10px;}" +
+  "#wg-todo-modal ul{list-style:none;margin:0;padding:0;}" +
+  "#wg-todo-modal li{display:flex;gap:10px;align-items:flex-start;margin:0 0 8px;" +
+  "font:600 14px/1.4 system-ui,sans-serif;}" +
+  "#wg-todo-modal li:last-child{margin-bottom:0;}" +
+  "#wg-todo-modal .wg-todo-mark{flex:0 0 auto;width:1.2em;text-align:center;font-size:15px;}" +
+  "#wg-todo-modal .wg-todo-done{color:#6ee7b7;text-decoration:line-through;opacity:.8;}" +
+  "#wg-todo-modal .wg-todo-current{color:#fff;}" +
+  "#wg-todo-modal .wg-todo-current .wg-todo-mark{color:#c9a6ff;}" +
+  "#wg-todo-modal .wg-todo-pending{color:#9a7ad1;}" +
   "#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
@@ -707,11 +725,6 @@ async function installOverlay(page, title) {
             cursor.style.transform = "translate(" + x + "px," + y + "px)";
           }
           cursor.style.opacity = "1";
-          // Screen Studio: pan the zoomed camera with the cursor.
-          const cam = window.__wgCamera;
-          if (cam && cam.scale > 1.001 && window.__wgSetCamera) {
-            window.__wgSetCamera(x, y, cam.scale, instant ? 0 : travel);
-          }
         };
         window.__wgHideCursor = () => {
           const cursor = document.getElementById("wg-cursor");
@@ -801,12 +814,14 @@ async function installOverlay(page, title) {
         };
         // Screen Studio-style camera: scale <body>, keep overlays on <html> fixed.
         window.__wgCamera = { scale: 1, cx: 0, cy: 0 };
-        window.__wgSetCamera = (cx, cy, scale, ms) => {
+        window.__wgSetCamera = (fx, fy, scale, ms) => {
           const body = document.body;
           if (!body) return;
           const s = Math.max(1, Math.min(Number(scale) || 1, 2.75));
-          window.__wgCamera = { scale: s, cx, cy };
-          const dur = ms != null && Number(ms) >= 0 ? Number(ms) : 500;
+          const vw = window.innerWidth;
+          const vh = window.innerHeight;
+          window.__wgCamera = { scale: s, cx: fx, cy: fy };
+          const dur = ms != null && Number(ms) >= 0 ? Number(ms) : 650;
           body.style.transition =
             dur <= 0
               ? "none"
@@ -816,10 +831,57 @@ async function installOverlay(page, title) {
             body.style.transform = "";
             return;
           }
+          // One transform: scale AND bring focus to viewport center.
           body.style.transform =
-            "translate(" + cx + "px," + cy + "px) scale(" + s + ") translate(" + -cx + "px," + -cy + "px)";
+            "translate(" + vw / 2 + "px," + vh / 2 + "px) scale(" + s + ") translate(" + -fx + "px," + -fy + "px)";
         };
-        window.__wgResetCamera = () => {
+        window.__wgSetTodos = (todos) => {
+          let modal = document.getElementById("wg-todo-modal");
+          if (!todos || !todos.length) {
+            if (modal) {
+              modal.classList.remove("wg-todo-on");
+              modal.innerHTML = "";
+            }
+            return;
+          }
+          if (!modal) {
+            modal = document.createElement("div");
+            modal.id = "wg-todo-modal";
+            document.documentElement.appendChild(modal);
+          }
+          const esc = (s) =>
+            String(s)
+              .replace(/&/g, "&amp;")
+              .replace(/</g, "&lt;")
+              .replace(/>/g, "&gt;");
+          const rows = todos
+            .map((t) => {
+              const cls = t.current
+                ? "wg-todo-current"
+                : t.done
+                  ? "wg-todo-done"
+                  : "wg-todo-pending";
+              const mark = t.done
+                ? String.fromCharCode(0x2713)
+                : t.current
+                  ? String.fromCharCode(0x2192)
+                  : String.fromCharCode(0x25cb);
+              return (
+                '<li class="' +
+                cls +
+                '"><span class="wg-todo-mark">' +
+                mark +
+                '</span><span>' +
+                esc(t.text || "") +
+                '</span></li>'
+              );
+            })
+            .join("");
+          modal.innerHTML =
+            '<div class="wg-todo-head">Checklist</div><ul>' + rows + '</ul>';
+          modal.classList.add("wg-todo-on");
+        };
+window.__wgResetCamera = () => {
           window.__wgSetCamera(window.innerWidth / 2, window.innerHeight / 2, 1);
         };
         window.__wgClearZoom = () => {
@@ -1008,7 +1070,7 @@ async function renderBeforeStep(page, info) {
       // 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\\">" +
+        ? "<div id=\\\"wg-episodes\\\">" +
           info.allEpisodes
             .map((e) => {
               const cls = e.episodeNumber < info.episodeNumber ? "wg-ep-done"
@@ -1019,7 +1081,7 @@ async function renderBeforeStep(page, info) {
               const enteredCls = info.justEnteredEpisode && e.episodeNumber === info.episodeNumber
                 ? " wg-ep-entered"
                 : "";
-              return "<span class=\\"wg-ep-tab " + cls + enteredCls + "\\">Episode " + e.episodeNumber + ": " +
+              return "<span class=\\\"wg-ep-tab " + cls + enteredCls + "\\\">Episode " + e.episodeNumber + ": " +
                 esc(e.episodeTitle || "") + "</span>";
             })
             .join("") +
@@ -1035,40 +1097,66 @@ async function renderBeforeStep(page, info) {
         .map((name, idx) => {
           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>";
+          const titleAttr = desc ? " title=\\\"" + esc(desc) + "\\\"" : "";
+          return "<span class=\\\"wg-mod " + cls + "\\\"" + titleAttr + ">" + name + "</span>";
         })
         .join("");
       const narrationHtml = info.description
-        ? "<div class=\\"wg-narration\\">" + esc(info.description) + "</div>"
+        ? "<div class=\\\"wg-narration\\\">" + esc(info.description) + "</div>"
         : "";
       const paceHtml =
         info.paceBadge || info.paceLabel
-          ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
+          ? "<div class=\\\"wg-pace\\\" data-pace-kind=\\\"" +
             esc(info.paceKind || "normal") +
-            "\\"><span class=\\"wg-pace-badge\\">" +
+            "\\\"><span class=\\\"wg-pace-badge\\\">" +
             esc(info.paceBadge || "1x") +
             "</span><span>" +
             esc(info.paceLabel || "") +
             "</span></div>"
           : "";
       let html =
-        "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
+        "<div id=\\\"wg-progress\\\"><div id=\\\"wg-progress-bar\\\" style=\\\"width:" + pct + "%\\\"></div></div>" +
         episodesHtml +
         paceHtml +
-        "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
+        "<div id=\\\"wg-modules\\\" class=\\\"" + modulesClass + "\\\">" + modulesHtml + "</div>" +
         "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
         narrationHtml +
-        todosHtmlFromInfo(info, esc);
+        ((() => {
+          const list = info.todos || [];
+          if (!list.length) return "";
+          return (
+            '<ul id="wg-todos">' +
+            list
+              .map((t) => {
+                const cls = t.current ? "wg-todo-current" : t.done ? "wg-todo-done" : "wg-todo-pending";
+                const mark = t.done
+                  ? String.fromCharCode(0x2713)
+                  : t.current
+                    ? String.fromCharCode(0x2192)
+                    : String.fromCharCode(0x25cb);
+                return (
+                  '<li class="' +
+                  cls +
+                  '"><span class="wg-todo-mark">' +
+                  mark +
+                  '</span><span>' +
+                  esc(t.text || "") +
+                  '</span></li>'
+                );
+              })
+              .join("") +
+            '</ul>'
+          );
+        })());
       if (info.keys.length === 0) {
-        html += "<div class=\\"wg-key\\">(no MemKeys required)</div>";
+        html += "<div class=\\\"wg-key\\\">(no MemKeys required)</div>";
       }
       for (const k of info.keys) {
         html +=
-          "<div class=\\"wg-key\\"><label>" + k.name + "</label>" +
-          "<textarea data-key=\\"" + k.name + "\\" rows=\\"2\\">" +
+          "<div class=\\\"wg-key\\\"><label>" + k.name + "</label>" +
+          "<textarea data-key=\\\"" + k.name + "\\\" rows=\\\"2\\\">" +
           k.value.replace(/</g, "&lt;") + "</textarea>" +
-          "<div class=\\"wg-key-pretty\\" data-pretty-for=\\"" + esc(k.name) + "\\"></div>" +
+          "<div class=\\\"wg-key-pretty\\\" data-pretty-for=\\\"" + esc(k.name) + "\\\"></div>" +
           "</div>";
       }
       let autoNow = false;
@@ -1078,12 +1166,12 @@ async function renderBeforeStep(page, info) {
         /* private mode / blocked storage - defaults to manual */
       }
       html +=
-        "<div class=\\"wg-autoplay-row\\"><label><input type=\\"checkbox\\" id=\\"wg-autoplay-cb\\"" +
+        "<div class=\\\"wg-autoplay-row\\\"><label><input type=\\\"checkbox\\\" id=\\\"wg-autoplay-cb\\\"" +
         (autoNow ? " checked" : "") +
         "> Auto-advance</label></div>" +
-        "<div id=\\"wg-gate-manual\\"" + (autoNow ? " style=\\"display:none\\"" : "") +
-        "><button id=\\"wg-run\\">Run this step \\u25B6</button></div>" +
-        "<div id=\\"wg-gate-auto\\" class=\\"wg-auto\\"" + (autoNow ? "" : " style=\\"display:none\\"") +
+        "<div id=\\\"wg-gate-manual\\\"" + (autoNow ? " style=\\\"display:none\\\"" : "") +
+        "><button id=\\\"wg-run\\\">Run this step \\u25B6</button></div>" +
+        "<div id=\\\"wg-gate-auto\\\" class=\\\"wg-auto\\\"" + (autoNow ? "" : " style=\\\"display:none\\\"") +
         ">Auto-advancing...</div>";
       panel.innerHTML = html;
       if (isNewPanel) {
@@ -1116,7 +1204,7 @@ async function renderBeforeStep(page, info) {
         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\\">" +
+            return "<div class=\\\"wg-key-pretty-row\\\"><span class=\\\"wg-key-pretty-label\\\">" +
               esc(label) + ":</span> " + esc(String(value)) + "</div>";
           })
           .join("");
@@ -1125,7 +1213,7 @@ async function renderBeforeStep(page, info) {
         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 + "\\"]");
+          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);
@@ -1237,9 +1325,9 @@ async function ensureSelectorInView(page, selector) {
   }
 }
 
-async function applyCameraZoom(page, box, zoom) {
+async function applyCameraZoom(page, box, zoom, ms) {
   const z = zoom != null && Number(zoom) > 1 ? Number(zoom) : 1;
-  if (!box) {
+  if (!box || z <= 1) {
     await page.evaluate(() => {
       if (window.__wgResetCamera) window.__wgResetCamera();
     }).catch(() => {});
@@ -1247,10 +1335,19 @@ async function applyCameraZoom(page, box, zoom) {
   }
   const cx = box.x + box.width / 2;
   const cy = box.y + box.height / 2;
+  const dur = ms != null ? ms : 650;
   await page
-    .evaluate(({ cx, cy, scale }) => {
-      if (window.__wgSetCamera) window.__wgSetCamera(cx, cy, scale);
-    }, { cx, cy, scale: z })
+    .evaluate(({ cx, cy, scale, dur }) => {
+      if (window.__wgSetCamera) window.__wgSetCamera(cx, cy, scale, dur);
+    }, { cx, cy, scale: z, dur })
+    .catch(() => {});
+}
+
+async function setDemoTodos(page, todos) {
+  await page
+    .evaluate((list) => {
+      if (window.__wgSetTodos) window.__wgSetTodos(list || []);
+    }, todos && todos.length ? todos : [])
     .catch(() => {});
 }
 
@@ -1355,15 +1452,27 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
       const box = await page.locator(h.selector).first().boundingBox();
       if (!box) continue;
       await updateHlProgress(i);
-      await applyCameraZoom(page, box, h.zoom);
-      const useCursor = h.cursor !== false;
-      if (useCursor) {
-        const cx = box.x + box.width / 2;
-        const cy = box.y + box.height / 2;
+      if (opts && opts.todos && opts.todos.length) {
+        const rows = opts.todos.map((t, ti) => ({
+          text: t.text,
+          done: ti < i,
+          current: ti === i,
+        }));
+        await setDemoTodos(page, rows);
+      } else if (h.todos && h.todos.length) {
+        await setDemoTodos(page, normalizeTodos(h.todos, h.todoIndex));
+      }
+      const cx = box.x + box.width / 2;
+      const cy = box.y + box.height / 2;
+      const z = h.zoom != null && Number(h.zoom) > 1 ? Number(h.zoom) : 1;
+      const camMs = 700;
+      // One-shot camera: zoom + center together (no zoom-then-align).
+      await applyCameraZoom(page, box, z, camMs);
+      if (h.cursor !== false) {
         await page
-          .evaluate(({ cx, cy }) => {
-            if (window.__wgMoveCursorTo) window.__wgMoveCursorTo(cx, cy, 500, false);
-          }, { cx, cy })
+          .evaluate(({ cx, cy, camMs }) => {
+            if (window.__wgMoveCursorTo) window.__wgMoveCursorTo(cx, cy, camMs, false);
+          }, { cx, cy, camMs })
           .catch(() => {});
       }
       await showRing(page, box, h.label, h.tone || "planned", {
@@ -1372,9 +1481,10 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
         focus: !!h.focus,
         color: h.color || h.labelColor || h.textColor,
       });
-      // Live follow while this ring is up (seamless, not taped).
+      await new Promise((res) => setTimeout(res, camMs));
+      // Live ring track only - camera stays locked (no per-frame re-pan).
       await page
-        .evaluate(({ sel, label, tone, size, weight, focus, color, zoom }) => {
+        .evaluate(({ sel, label, tone, size, weight, focus, color }) => {
           const tick = () => {
             const el = document.querySelector(sel);
             if (!el) {
@@ -1386,26 +1496,10 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
             if (window.__wgPositionRing) {
               window.__wgPositionRing(box, label, tone || "planned", { size, weight, focus, color });
             }
-            if (zoom && zoom > 1 && window.__wgSetCamera) {
-              // Prefer cursor tip when visible (Screen Studio follow-mouse);
-              // else keep the ring target centered.
-              let cx = box.x + box.width / 2;
-              let cy = box.y + box.height / 2;
-              const cur = document.getElementById("wg-cursor");
-              if (cur && cur.style.opacity !== "0") {
-                const m = /translate\(([-\d.]+)px,\s*([-\d.]+)px\)/.exec(cur.style.transform || "");
-                if (m) {
-                  cx = Number(m[1]);
-                  cy = Number(m[2]);
-                }
-              }
-              window.__wgSetCamera(cx, cy, zoom, 0);
-            }
             window.__wgRingRaf = requestAnimationFrame(tick);
           };
           window.__wgRingRaf = requestAnimationFrame(tick);
-          const onScroll = () => {};
-          window.__wgRingTrack = onScroll;
+          window.__wgRingTrack = () => {};
         }, {
           sel: h.selector,
           label: h.label,
@@ -1414,47 +1508,9 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
           weight: h.weight || "normal",
           focus: !!h.focus,
           color: h.color || h.labelColor || h.textColor || "",
-          zoom: h.zoom != null && h.zoom > 1 ? h.zoom : 0,
         })
         .catch(() => {});
 
-      if ((opts && opts.todos && opts.todos.length) || (h.todos && h.todos.length)) {
-        const rows =
-          opts && opts.todos && opts.todos.length
-            ? opts.todos
-            : normalizeTodos(h.todos, h.todoIndex);
-        await page
-          .evaluate((todos) => {
-            const ul = document.getElementById("wg-todos");
-            if (!ul) return;
-            ul.innerHTML = todos
-              .map((t) => {
-                const cls = t.current
-                  ? "wg-todo-current"
-                  : t.done
-                    ? "wg-todo-done"
-                    : "wg-todo-pending";
-                const mark = t.done ? "\\u2713" : t.current ? "\\u2192" : "\\u25CB";
-                const esc = (s) =>
-                  String(s)
-                    .replace(/&/g, "&amp;")
-                    .replace(/</g, "&lt;")
-                    .replace(/>/g, "&gt;");
-                return (
-                  "<li class=\\"" +
-                  cls +
-                  "\\"><span class=\\"wg-todo-mark\\">" +
-                  mark +
-                  "</span><span>" +
-                  esc(t.text || "") +
-                  "</span></li>"
-                );
-              })
-              .join("");
-          }, rows)
-          .catch(() => {});
-      }
-
       // Appear settle
       await new Promise((res) => setTimeout(res, fadeMs));
       const authored = resolveFixtureDwellMs(h, { gatesFast, pace });
@@ -1522,8 +1578,8 @@ async function renderAfterStep(page, info) {
         .map((name, idx) => {
           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>";
+          const titleAttr = desc ? " title=\\\"" + escA(desc) + "\\\"" : "";
+          return "<span class=\\\"wg-mod " + cls + "\\\"" + titleAttr + ">" + name + "</span>";
         })
         .join("");
       // QA-friendly by default ("LoginSuccess" -> "Login Success") - raw
@@ -1534,13 +1590,13 @@ async function renderAfterStep(page, info) {
         .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2") || info.resultTag;
       const pretty = window.__wgPretty !== false;
       const resultHtml =
-        "<div class=\\"wg-toggle\\">" +
-        "<button class=\\"wg-toggle-btn" + (pretty ? " wg-active" : "") + "\\" data-mode=\\"pretty\\">Pretty</button>" +
-        "<button class=\\"wg-toggle-btn" + (pretty ? "" : " wg-active") + "\\" data-mode=\\"json\\">JSON</button>" +
+        "<div class=\\\"wg-toggle\\\">" +
+        "<button class=\\\"wg-toggle-btn" + (pretty ? " wg-active" : "") + "\\\" data-mode=\\\"pretty\\\">Pretty</button>" +
+        "<button class=\\\"wg-toggle-btn" + (pretty ? "" : " wg-active") + "\\\" data-mode=\\\"json\\\">JSON</button>" +
         "</div>" +
-        "<div class=\\"wg-result wg-result-pretty\\" style=\\"display:" + (pretty ? "block" : "none") + "\\">" +
+        "<div class=\\\"wg-result wg-result-pretty\\\" style=\\\"display:" + (pretty ? "block" : "none") + "\\\">" +
         prettyText + "</div>" +
-        "<div class=\\"wg-result wg-result-json\\" style=\\"display:" + (pretty ? "none" : "block") + "\\">" +
+        "<div class=\\\"wg-result wg-result-json\\\" style=\\\"display:" + (pretty ? "none" : "block") + "\\\">" +
         info.resultTag + "</div>";
       let autoNow = false;
       try {
@@ -1549,21 +1605,21 @@ async function renderAfterStep(page, info) {
         /* private mode / blocked storage - defaults to manual */
       }
       const gateHtml =
-        "<div class=\\"wg-autoplay-row\\"><label><input type=\\"checkbox\\" id=\\"wg-autoplay-cb\\"" +
+        "<div class=\\\"wg-autoplay-row\\\"><label><input type=\\\"checkbox\\\" id=\\\"wg-autoplay-cb\\\"" +
         (autoNow ? " checked" : "") +
         "> Auto-advance</label></div>" +
-        "<div id=\\"wg-gate-manual\\"" + (autoNow ? " style=\\"display:none\\"" : "") +
-        "><button id=\\"wg-run\\">" + buttonLabel + "</button></div>" +
-        "<div id=\\"wg-gate-auto\\" class=\\"wg-auto\\"" + (autoNow ? "" : " style=\\"display:none\\"") +
+        "<div id=\\\"wg-gate-manual\\\"" + (autoNow ? " style=\\\"display:none\\\"" : "") +
+        "><button id=\\\"wg-run\\\">" + buttonLabel + "</button></div>" +
+        "<div id=\\\"wg-gate-auto\\\" class=\\\"wg-auto\\\"" + (autoNow ? "" : " style=\\\"display:none\\\"") +
         ">Auto-advancing...</div>";
       const episodesHtml = info.allEpisodes && info.allEpisodes.length > 0
-        ? "<div id=\\"wg-episodes\\">" +
+        ? "<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 + ": " +
+              return "<span class=\\\"wg-ep-tab " + cls + "\\\">Episode " + e.episodeNumber + ": " +
                 escA(e.episodeTitle || "") + "</span>";
             })
             .join("") +
@@ -1571,21 +1627,47 @@ async function renderAfterStep(page, info) {
         : "";
       const paceHtml =
         info.paceBadge || info.paceLabel
-          ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
+          ? "<div class=\\\"wg-pace\\\" data-pace-kind=\\\"" +
             escA(info.paceKind || "normal") +
-            "\\"><span class=\\"wg-pace-badge\\">" +
+            "\\\"><span class=\\\"wg-pace-badge\\\">" +
             escA(info.paceBadge || "1x") +
             "</span><span>" +
             escA(info.paceLabel || "") +
             "</span></div>"
           : "";
       panel.innerHTML =
-        "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
+        "<div id=\\\"wg-progress\\\"><div id=\\\"wg-progress-bar\\\" style=\\\"width:" + pct + "%\\\"></div></div>" +
         episodesHtml +
         paceHtml +
-        "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
+        "<div id=\\\"wg-modules\\\" class=\\\"" + modulesClass + "\\\">" + modulesHtml + "</div>" +
         "<h3>" + heading + "</h3>" +
-        todosHtmlFromInfo(info, escA) +
+        ((() => {
+          const list = info.todos || [];
+          if (!list.length) return "";
+          return (
+            '<ul id="wg-todos">' +
+            list
+              .map((t) => {
+                const cls = t.current ? "wg-todo-current" : t.done ? "wg-todo-done" : "wg-todo-pending";
+                const mark = t.done
+                  ? String.fromCharCode(0x2713)
+                  : t.current
+                    ? String.fromCharCode(0x2192)
+                    : String.fromCharCode(0x25cb);
+                return (
+                  '<li class="' +
+                  cls +
+                  '"><span class="wg-todo-mark">' +
+                  mark +
+                  '</span><span>' +
+                  escA(t.text || "") +
+                  '</span></li>'
+                );
+              })
+              .join("") +
+            '</ul>'
+          );
+        })()) +
         resultHtml +
         gateHtml;
       if (isNewPanel) {
@@ -1652,13 +1734,13 @@ async function renderStepError(page, info) {
       if (!isNewPanel) panel.classList.add("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\\">" +
+        ? "<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 + ": " +
+              return "<span class=\\\"wg-ep-tab " + cls + "\\\">Episode " + e.episodeNumber + ": " +
                 esc(e.episodeTitle || "") + "</span>";
             })
             .join("") +
@@ -1669,8 +1751,8 @@ async function renderStepError(page, info) {
         .map((name, idx) => {
           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>";
+          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";
@@ -1678,17 +1760,17 @@ async function renderStepError(page, info) {
         ? "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>"
+        ? "<div class=\\\"wg-expected-reason\\\">" + esc(info.expectedFailureReason) + "</div>"
         : "";
       panel.innerHTML =
         episodesHtml +
-        "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
-        "<h3 class=\\"" + (isExpected ? "wg-expected-heading" : "wg-error-heading") + "\\">" + headingText + "</h3>" +
+        "<div id=\\\"wg-modules\\\" class=\\\"" + modulesClass + "\\\">" + modulesHtml + "</div>" +
+        "<h3 class=\\\"" + (isExpected ? "wg-expected-heading" : "wg-error-heading") + "\\\">" + headingText + "</h3>" +
         reasonHtml +
-        "<div class=\\"wg-error-msg\\">" + esc(info.message) + "</div>" +
-        "<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 class=\\\"wg-error-msg\\\">" + esc(info.message) + "</div>" +
+        "<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);
@@ -1952,25 +2034,25 @@ async function presentSlides(page, slides, _gate, opts) {
           String(t).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
         const episodeLine =
           info.episodeNumber !== undefined && info.episodeNumber !== null
-            ? "<div class=\\"wg-episode\\">Episode " +
+            ? "<div class=\\\"wg-episode\\\">Episode " +
               info.episodeNumber +
               (info.episodeTitle ? ": " + esc(info.episodeTitle) : "") +
               " · yap slides</div>"
             : "";
         const paceHtml =
           info.paceBadge || info.paceLabel
-            ? "<div class=\\"wg-pace\\" data-pace-kind=\\"" +
+            ? "<div class=\\\"wg-pace\\\" data-pace-kind=\\\"" +
               esc(info.paceKind || "normal") +
-              "\\"><span class=\\"wg-pace-badge\\">" +
+              "\\\"><span class=\\\"wg-pace-badge\\\">" +
               esc(info.paceBadge || "1x") +
               "</span><span>" +
               esc(info.paceLabel || "") +
               "</span></div>"
             : "";
         panel.innerHTML =
-          "<div class=\\"wg-chrome\\"><span class=\\"wg-chrome-title\\">waygraph demo</span>" +
-          "<button type=\\"button\\" class=\\"wg-hide-btn\\" data-wg-toggle=\\"1\\">Hide</button></div>" +
-          "<div class=\\"wg-body\\">" +
+          "<div class=\\\"wg-chrome\\\"><span class=\\\"wg-chrome-title\\\">waygraph demo</span>" +
+          "<button type=\\\"button\\\" class=\\\"wg-hide-btn\\\" data-wg-toggle=\\\"1\\\">Hide</button></div>" +
+          "<div class=\\\"wg-body\\\">" +
           episodeLine +
           paceHtml +
           "<h3>Slide " +
@@ -1980,35 +2062,35 @@ async function presentSlides(page, slides, _gate, opts) {
           (info.blockName ? " · " + esc(info.blockName) : "") +
           "</h3>" +
           (info.tag
-            ? "<div style=\\"border:none;padding:0;margin:0 0 6px;font-size:11px;color:#c9a6ff\\">" +
+            ? "<div style=\\\"border:none;padding:0;margin:0 0 6px;font-size:11px;color:#c9a6ff\\\">" +
               esc(info.tag) +
               "</div>"
             : "") +
-          "<div class=\\"wg-narration\\">" +
+          "<div class=\\\"wg-narration\\\">" +
           esc(info.caption) +
           "</div>" +
           (info.detail
-            ? "<div class=\\"wg-result-pretty\\" style=\\"margin:0 0 12px;color:#f0e8ff\\">" +
+            ? "<div class=\\\"wg-result-pretty\\\" style=\\\"margin:0 0 12px;color:#f0e8ff\\\">" +
               esc(info.detail) +
               "</div>"
             : "") +
           (info.dwellMs != null
-            ? "<div class=\\"wg-auto\\" id=\\"wg-dwell-hint\\" style=\\"margin:0 0 8px\\">Hold " +
+            ? "<div class=\\\"wg-auto\\\" id=\\\"wg-dwell-hint\\\" style=\\\"margin:0 0 8px\\\">Hold " +
               (info.dwellMs / 1000).toFixed(1) +
               "s before next...</div>"
             : "") +
-          "<div class=\\"wg-autoplay-row\\"><label><input type=\\"checkbox\\" id=\\"wg-autoplay-cb\\"" +
+          "<div class=\\\"wg-autoplay-row\\\"><label><input type=\\\"checkbox\\\" id=\\\"wg-autoplay-cb\\\"" +
           (info.autoNow ? " checked" : "") +
           "> Auto-advance</label></div>" +
-          "<div id=\\"wg-gate-manual\\"" +
-          (info.autoNow ? " style=\\"display:none\\"" : "") +
-          "><button type=\\"button\\" id=\\"wg-run\\"" +
+          "<div id=\\\"wg-gate-manual\\\"" +
+          (info.autoNow ? " style=\\\"display:none\\\"" : "") +
+          "><button type=\\\"button\\\" id=\\\"wg-run\\\"" +
           (info.dwellMs != null ? " disabled" : "") +
           ">" +
           (info.isLast ? "Continue \\u25B6" : "Next slide \\u25B6") +
           "</button></div>" +
-          "<div id=\\"wg-gate-auto\\" class=\\"wg-auto\\"" +
-          (info.autoNow ? "" : " style=\\"display:none\\"") +
+          "<div id=\\\"wg-gate-auto\\\" class=\\\"wg-auto\\\"" +
+          (info.autoNow ? "" : " style=\\\"display:none\\\"") +
           ">Auto-advancing...</div>" +
           "</div>";
         if (isNew) {
@@ -2173,7 +2255,7 @@ async function teardownOverlay(page) {
         window.__wgRingTrack = null;
       }
       window.__wgNarrateOwnsRing = false;
-      for (const id of ["wg-panel", "wg-ring", "wg-ring-label", "wg-cursor", "wg-click-pulse", "wg-banner"]) {
+      for (const id of ["wg-panel", "wg-ring", "wg-ring-label", "wg-cursor", "wg-click-pulse", "wg-banner", "wg-todo-modal"]) {
         const el = document.getElementById(id);
         if (el) el.remove();
       }
@@ -2747,6 +2829,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       todos: stubBeforeTodos,
       ...paceSpeak,
     });
+    await setDemoTodos(page, stubBeforeTodos);
     const edits = await gate();
     for (const k of requires) {
       if (edits[k.name] !== undefined) {
@@ -2934,6 +3017,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       });
       stubAfterTodos = afterPhase.todos || [];
       await setDemoBannerTitle(page, afterPhase.title);
+      await setDemoTodos(page, afterPhase.todos || []);
       highlights = afterPhase.highlights.map((h) => {
         const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
         return {

package/dist/engine.d.ts

@@ -544,6 +544,57 @@ export declare class Engine {
         Block<K, L>,
         EndMarker
     ]): Flow<L>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>, K extends Checkpoint<string>, L extends Checkpoint<string>, M extends Checkpoint<string>>(blocks: readonly [
+        StartMarker,
+        Block<S, B>,
+        Block<B, C>,
+        Block<C, D>,
+        Block<D, E>,
+        Block<E, F>,
+        Block<F, G>,
+        Block<G, H>,
+        Block<H, I>,
+        Block<I, J>,
+        Block<J, K>,
+        Block<K, L>,
+        Block<L, M>,
+        EndMarker
+    ]): Flow<M>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>, K extends Checkpoint<string>, L extends Checkpoint<string>, M extends Checkpoint<string>, N extends Checkpoint<string>>(blocks: readonly [
+        StartMarker,
+        Block<S, B>,
+        Block<B, C>,
+        Block<C, D>,
+        Block<D, E>,
+        Block<E, F>,
+        Block<F, G>,
+        Block<G, H>,
+        Block<H, I>,
+        Block<I, J>,
+        Block<J, K>,
+        Block<K, L>,
+        Block<L, M>,
+        Block<M, N>,
+        EndMarker
+    ]): Flow<N>;
+    defineFlow<B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, G extends Checkpoint<string>, H extends Checkpoint<string>, I extends Checkpoint<string>, J extends Checkpoint<string>, K extends Checkpoint<string>, L extends Checkpoint<string>, M extends Checkpoint<string>, N extends Checkpoint<string>, O extends Checkpoint<string>>(blocks: readonly [
+        StartMarker,
+        Block<S, B>,
+        Block<B, C>,
+        Block<C, D>,
+        Block<D, E>,
+        Block<E, F>,
+        Block<F, G>,
+        Block<G, H>,
+        Block<H, I>,
+        Block<I, J>,
+        Block<J, K>,
+        Block<K, L>,
+        Block<L, M>,
+        Block<M, N>,
+        Block<N, O>,
+        EndMarker
+    ]): Flow<O>;
 }
 /**
  * Attaches routing to `block` without touching its act/observe/resolve/verify -

package/package.json

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