waygraph 0.2.0 → 0.3.0

package/dist/cli.js

@@ -359,6 +359,7 @@ const RING_CSS =
   "#wg-panel .wg-auto{margin-top:10px;font:600 13px system-ui,sans-serif;color:#c9a6ff;}" +
   "#wg-panel h3{margin:0 0 8px;font-size:13px;color:#c9a6ff;font-weight:700;" +
   "letter-spacing:.02em;text-transform:uppercase;}" +
+  "#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;}" +
   "#wg-modules{display:flex;flex-wrap:wrap;gap:6px;margin:0 0 10px;}" +
@@ -366,6 +367,12 @@ const RING_CSS =
   "#wg-modules .wg-mod-done{background:#2a1650;color:#9a7ad1;}" +
   "#wg-modules .wg-mod-current{background:#7C3AED;color:#fff;}" +
   "#wg-modules .wg-mod-upcoming{background:transparent;color:#5a4a80;border:1px solid #3a2a60;}" +
+  "#wg-banner{position:fixed;z-index:2147483647;top:14px;right:14px;max-width:320px;" +
+  "background:rgba(20,10,40,.94);color:#fff;border-radius:12px;padding:10px 16px;" +
+  "font:14px/1.4 system-ui,sans-serif;box-shadow:0 8px 20px rgba(0,0,0,.3);" +
+  "border:1px solid rgba(124,58,237,.4);}" +
+  "#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;}" +
   "#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;" +
@@ -381,21 +388,59 @@ const RING_CSS =
   "background:transparent;border:1px solid #4b2a80;color:#9a7ad1;border-radius:6px;}" +
   "#wg-panel .wg-toggle button.wg-active{background:#4b2a80;color:#fff;}";
 
-async function installOverlay(page) {
+// 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
+// across a taskbar/alt-tab, not just something visible inside the page.
+const WAYGRAPH_FAVICON =
+  "data:image/svg+xml," +
+  encodeURIComponent(
+    "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'>" +
+      "<circle cx='16' cy='16' r='14' fill='#7C3AED'/></svg>",
+  );
+
+async function installOverlay(page, title) {
   await page.addStyleTag({ content: RING_CSS }).catch(() => {});
   await page
-    .evaluate(() => {
-      if (!document.getElementById("wg-ring")) {
-        const ring = document.createElement("div");
-        ring.id = "wg-ring";
-        document.documentElement.appendChild(ring);
-      }
-    })
+    .evaluate(
+      ({ title, favicon }) => {
+        if (!document.getElementById("wg-ring")) {
+          const ring = document.createElement("div");
+          ring.id = "wg-ring";
+          document.documentElement.appendChild(ring);
+        }
+        if (title && !document.getElementById("wg-banner")) {
+          const banner = document.createElement("div");
+          banner.id = "wg-banner";
+          const tag = document.createElement("span");
+          tag.className = "wg-banner-tag";
+          tag.textContent = "waygraph demo";
+          const text = document.createElement("span");
+          text.textContent = title;
+          banner.appendChild(tag);
+          banner.appendChild(text);
+          document.documentElement.appendChild(banner);
+        }
+        // Tab title/favicon: a real navigation resets document.title and any
+        // <link rel="icon"> the new document brings, so re-check (not
+        // re-append) on every call instead of a one-time flag.
+        if (!document.title.startsWith("[waygraph] ")) {
+          document.title = "[waygraph] " + document.title;
+        }
+        let iconLink = document.querySelector("link[rel~='icon']");
+        if (!iconLink) {
+          iconLink = document.createElement("link");
+          iconLink.rel = "icon";
+          document.head.appendChild(iconLink);
+        }
+        if (iconLink.href !== favicon) iconLink.href = favicon;
+      },
+      { title, favicon: WAYGRAPH_FAVICON },
+    )
     .catch(() => {});
 }
 
 async function renderBeforeStep(page, info) {
-  await installOverlay(page);
+  await installOverlay(page, info.title);
   // A ring left highlighting the PREVIOUS step's element (and its live
   // resize/scroll tracker) shouldn't linger once a new step's own panel is
   // up - only relevant when a Block's act() doesn't navigate away, since a
@@ -418,16 +463,23 @@ async function renderBeforeStep(page, info) {
       const 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;");
       const modulesHtml = info.allNames
         .map((name, idx) => {
           const cls = idx < info.index ? "wg-mod-done" : idx === info.index ? "wg-mod-current" : "wg-mod-upcoming";
-          return "<span class=\\"wg-mod " + cls + "\\">" + name + "</span>";
+          const desc = info.allDescriptions && info.allDescriptions[idx];
+          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>"
+        : "";
       let html =
         "<div id=\\"wg-progress\\"><div id=\\"wg-progress-bar\\" style=\\"width:" + pct + "%\\"></div></div>" +
         "<div id=\\"wg-modules\\">" + modulesHtml + "</div>" +
-        "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>";
+        "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
+        narrationHtml;
       if (info.keys.length === 0) {
         html += "<div class=\\"wg-key\\">(no MemKeys required)</div>";
       }
@@ -458,46 +510,66 @@ async function renderBeforeStep(page, info) {
 }
 
 async function renderAfterStep(page, info) {
-  await installOverlay(page);
-  // Tracks the highlighted element live (recomputes on resize/scroll)
-  // instead of a one-time Node-side boundingBox() snapshot - a resized
-  // window used to leave the ring frozen at its stale old position.
-  // Only the first recovered selector is drawn (one ring); best-effort - a
-  // selector that never resolves just leaves the ring hidden.
+  await installOverlay(page, info.title);
+  // Clear any tracker from a previous highlight before cycling through this
+  // step's own.
   await page
-    .evaluate((highlights) => {
+    .evaluate(() => {
       if (window.__wgRingTrack) {
         window.removeEventListener("resize", window.__wgRingTrack);
         window.removeEventListener("scroll", window.__wgRingTrack, true);
         window.__wgRingTrack = null;
       }
-      const ring = document.getElementById("wg-ring");
-      if (!ring) return;
-      const h = highlights[0];
-      if (!h) {
-        ring.style.opacity = "0";
-        return;
-      }
-      const reposition = () => {
-        const el = document.querySelector(h.selector);
-        if (!el) {
-          ring.style.opacity = "0";
-          return;
-        }
-        const box = el.getBoundingClientRect();
-        ring.style.left = box.x - 6 + "px";
-        ring.style.top = box.y - 6 + "px";
-        ring.style.width = box.width + 12 + "px";
-        ring.style.height = box.height + 12 + "px";
-        ring.setAttribute("data-label", h.label);
-        ring.style.opacity = "1";
-      };
-      reposition();
-      window.__wgRingTrack = reposition;
-      window.addEventListener("resize", reposition);
-      window.addEventListener("scroll", reposition, true);
-    }, info.highlights)
+    })
     .catch(() => {});
+  const highlights = info.highlights || [];
+  // Cycle through EVERY declared/recovered highlight in order, each shown
+  // long enough to actually register - "it highlights something [...] then
+  // it highlights something [else] and next," not just the first one.
+  for (let i = 0; i < highlights.length; i++) {
+    const h = highlights[i];
+    try {
+      const box = await page.locator(h.selector).first().boundingBox();
+      if (box) {
+        await showRing(page, box, h.label);
+        await new Promise((res) => setTimeout(res, i === highlights.length - 1 ? 200 : 900));
+      }
+    } catch {
+      // best-effort - a selector that doesn't resolve just gets skipped
+    }
+  }
+  if (highlights.length > 0) {
+    // The LAST highlight is the one that stays lit while the human reads
+    // the after-step panel - give THAT one live resize/scroll tracking,
+    // same as before.
+    const last = highlights[highlights.length - 1];
+    await page
+      .evaluate((h) => {
+        const ring = document.getElementById("wg-ring");
+        if (!ring) return;
+        const reposition = () => {
+          const el = document.querySelector(h.selector);
+          if (!el) {
+            ring.style.opacity = "0";
+            return;
+          }
+          const box = el.getBoundingClientRect();
+          ring.style.left = box.x - 6 + "px";
+          ring.style.top = box.y - 6 + "px";
+          ring.style.width = box.width + 12 + "px";
+          ring.style.height = box.height + 12 + "px";
+          ring.setAttribute("data-label", h.label);
+          ring.style.opacity = "1";
+        };
+        reposition();
+        window.__wgRingTrack = reposition;
+        window.addEventListener("resize", reposition);
+        window.addEventListener("scroll", reposition, true);
+      }, last)
+      .catch(() => {});
+  } else {
+    await hideRing(page);
+  }
   await page
     .evaluate((info) => {
       const old = document.getElementById("wg-panel");
@@ -509,10 +581,13 @@ async function renderAfterStep(page, info) {
         ? "End of chain - " + info.total + " / " + info.total + " blocks covered - " + info.blockName + " done"
         : "Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + " done";
       const buttonLabel = info.isLast ? "Finish" : "Next \\u25B6";
+      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";
-          return "<span class=\\"wg-mod " + cls + "\\">" + name + "</span>";
+          const desc = info.allDescriptions && info.allDescriptions[idx];
+          const titleAttr = desc ? " title=\\"" + escA(desc) + "\\"" : "";
+          return "<span class=\\"wg-mod " + cls + "\\"" + titleAttr + ">" + name + "</span>";
         })
         .join("");
       // QA-friendly by default ("LoginSuccess" -> "Login Success") - raw
@@ -558,14 +633,37 @@ async function renderAfterStep(page, info) {
     .catch(() => {});
 }
 
+/**
+ * A Block's own explicit instruction.highlights, if it declared any -
+ * arbitrary, author-controlled highlight points, independent of verify
+ * ("remember this ID" isn't a pass/fail check). Takes priority over
+ * anything recovered from verify traits below.
+ */
+function resolveDeclaredHighlights(block, resultTag) {
+  let highlights = block.instruction && block.instruction.highlights;
+  if (typeof highlights === "function") {
+    try {
+      highlights = highlights({ __state: resultTag });
+    } catch {
+      highlights = [];
+    }
+  }
+  if (!Array.isArray(highlights)) return [];
+  return highlights.filter((h) => h && typeof h.selector === "string" && typeof h.label === "string");
+}
+
 /**
  * Recovers a DOM selector from a built-in Trait's own .name string -
  * visible(sel) / text-equals(sel, "...") - since Trait.check itself is
  * an opaque closure with no selector field of its own. Best-effort only: a
  * hand-written bespoke Trait, or url-matches(...) (no DOM target), yields
  * nothing to highlight, which is fine - the panel still shows the result.
+ * Only used as a FALLBACK when the Block declared no explicit
+ * instruction.highlights of its own - see resolveDeclaredHighlights.
  */
 function extractVerifyHighlights(block, resultTag) {
+  const declared = resolveDeclaredHighlights(block, resultTag);
+  if (declared.length > 0) return declared;
   let verify = block.instruction && block.instruction.verify;
   if (typeof verify === "function") {
     try {
@@ -603,53 +701,190 @@ 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).
  */
-function instrumentFillHighlighting(page) {
+async function showRing(page, box, label) {
+  await page
+    .evaluate(
+      ({ box, label }) => {
+        const ring = document.getElementById("wg-ring");
+        if (!ring) return;
+        ring.style.left = box.x - 6 + "px";
+        ring.style.top = box.y - 6 + "px";
+        ring.style.width = box.width + 12 + "px";
+        ring.style.height = box.height + 12 + "px";
+        ring.setAttribute("data-label", label);
+        ring.style.opacity = "1";
+      },
+      { box, label },
+    )
+    .catch(() => {});
+}
+
+async function hideRing(page) {
+  await page
+    .evaluate(() => {
+      const ring = document.getElementById("wg-ring");
+      if (ring) ring.style.opacity = "0";
+    })
+    .catch(() => {});
+}
+
+function instrumentInteractionHighlighting(page, mem, slowMo) {
+  // Playwright's own slowMo ALREADY pauses after every single low-level
+  // action it dispatches - and pressSequentially() fires one such action
+  // PER CHARACTER. Also giving pressSequentially its own fixed delay
+  // double-paces every keystroke (45ms + slowMo's own ~350ms, per
+  // character) - an ordinary 22-character email alone stretched past 8
+  // seconds. When slowMo is already doing the pacing, add none of our own;
+  // only fall back to a small typing delay when slowMo is off entirely.
+  const typeDelay = slowMo ? 0 : 30;
+  // Click is a single action, not per-character, so it doesn't compound
+  // the same way - but slowMo still adds its own pause around the actual
+  // click, so trim our own explicit "pop" pauses when it's already active
+  // rather than stacking a full 1.2s on top of that.
+  const clickPrePop = slowMo ? 300 : 700;
+  const clickPostPop = slowMo ? 200 : 500;
+  // Locator.fill()/click() only ever see a raw call, no context of where
+  // the value came from. Patching mem.get() to remember the most recently
+  // read key's name (Blocks read-then-immediately-fill, e.g. const { email
+  // } = mem.get(LoginInput.key); ...fill(email)) lets the fill patch below
+  // label the ring with the real key, not a generic "writing from mem".
+  // Patches this ONE mem instance only, not MemPage's shared prototype -
+  // there's exactly one mem per chain run.
+  const memTrack = { lastKeyName: null, at: 0 };
+  const originalGet = mem.get.bind(mem);
+  mem.get = (key) => {
+    memTrack.lastKeyName = key && key.name;
+    memTrack.at = Date.now();
+    return originalGet(key);
+  };
+
   const proto = Object.getPrototypeOf(page.locator("html"));
-  if (proto.__wgFillPatched) return;
-  proto.__wgFillPatched = true;
-  const originalFill = proto.fill;
-  proto.fill = async function (value, options) {
-    try {
-      await installOverlay(page);
-      const box = await this.boundingBox();
-      if (box) {
-        await page.evaluate(
-          (box) => {
-            const ring = document.getElementById("wg-ring");
-            if (!ring) return;
-            ring.style.left = box.x - 6 + "px";
-            ring.style.top = box.y - 6 + "px";
-            ring.style.width = box.width + 12 + "px";
-            ring.style.height = box.height + 12 + "px";
-            ring.setAttribute("data-label", "writing from mem");
-            ring.style.opacity = "1";
-          },
-          box,
-        );
-        await new Promise((res) => setTimeout(res, 200));
+
+  if (!proto.__wgFillPatched) {
+    proto.__wgFillPatched = true;
+    const originalFill = proto.fill;
+    proto.fill = async function (value, options) {
+      try {
+        await installOverlay(page);
+        const box = await this.boundingBox();
+        if (box) {
+          // Only trust the "last mem.get()" as THIS fill's source if it
+          // happened recently - a stale read from several actions ago is
+          // more likely unrelated than actually describing this field.
+          const label = memTrack.lastKeyName && Date.now() - memTrack.at < 3000
+            ? "from mem: " + memTrack.lastKeyName
+            : "writing from mem";
+          await showRing(page, box, label);
+          await new Promise((res) => setTimeout(res, 200));
+        }
+      } catch {
+        // best-effort - element not visible/attached yet is not this
+        // instrumentation's problem, the real fill below still runs
       }
-    } catch {
-      // best-effort - element not visible/attached yet is not this
-      // instrumentation's problem, the real fill below still runs
-    }
-    try {
-      // NOT this.clear() - Locator.clear() is itself implemented as
-      // fill(""), and since fill is patched on the shared prototype, that
-      // call would resolve back to THIS same patched function and recurse
-      // forever. Call the real original fill directly to clear instead.
-      await originalFill.call(this, "", { timeout: options && options.timeout });
-      return await this.pressSequentially(String(value), { delay: 45, timeout: options && options.timeout });
-    } catch {
-      // pressSequentially unsupported on this element (e.g. a
-      // contenteditable div, or a locator .fill() genuinely needs to
-      // handle specially) - fall back to the real, unpatched fill.
-      return await originalFill.call(this, value, options);
-    }
-  };
+      let result;
+      try {
+        // NOT this.clear() - Locator.clear() is itself implemented as
+        // fill(""), and since fill is patched on the shared prototype,
+        // that call would resolve back to THIS same patched function and
+        // recurse forever. Call the real original fill directly instead.
+        await originalFill.call(this, "", { timeout: options && options.timeout });
+        result = await this.pressSequentially(String(value), { delay: typeDelay, timeout: options && options.timeout });
+      } catch {
+        // pressSequentially unsupported on this element (e.g. a
+        // contenteditable div, or a locator .fill() genuinely needs to
+        // handle specially) - fall back to the real, unpatched fill.
+        result = await originalFill.call(this, value, options);
+      }
+      // Fade the ring back out once this field is actually done, instead
+      // of leaving it lit until the next Block's own before-panel clears
+      // it - it was sticking around through the whole rest of the step.
+      await hideRing(page);
+      return result;
+    };
+  }
+
+  if (!proto.__wgClickPatched) {
+    proto.__wgClickPatched = true;
+    const originalClick = proto.click;
+    proto.click = async function (options) {
+      try {
+        await installOverlay(page);
+        const box = await this.boundingBox();
+        if (box) {
+          let label = "click";
+          try {
+            const text = (await this.textContent())?.trim();
+            if (text && text.length > 0 && text.length <= 30) label = text;
+          } catch {
+            // element has no simple text (an icon button, say) - generic label is fine
+          }
+          await showRing(page, box, label);
+          // "pop for a few seconds" - Dan's own phrase, matching the
+          // zsign demo-engine's ring-before-click pattern in
+          // services/help-center-clip-engine's video-pipeline.
+          await new Promise((res) => setTimeout(res, clickPrePop));
+        }
+      } catch {
+        // best-effort - the real click below still runs either way
+      }
+      const result = await originalClick.call(this, options);
+      await new Promise((res) => setTimeout(res, clickPostPop));
+      await hideRing(page);
+      return result;
+    };
+  }
+
+  // Caps any Locator.waitFor()/page.waitForTimeout() timeout during step
+  // mode - a Block polling for something that will NEVER happen (e.g. "is
+  // there an unverified-account banner" on an account that IS verified)
+  // has no choice but to wait out its own hardcoded timeout in full before
+  // concluding "no". Only the WAIT gets capped, never the real outcome -
+  // if the thing genuinely appears at 800ms into a 5000ms wait, waitFor
+  // still resolves at 800ms same as always; this only shortens the "it's
+  // just never going to happen" case. Plain setTimeout()-based sleep()
+  // helpers some Blocks use for their own pacing are NOT Playwright calls
+  // at all and can't be touched this way - a real, disclosed limit, not
+  // silently ignored.
+  // 3000ms was the first, deliberately conservative pass (this codebase
+  // has documented real flakiness around slow-but-legitimate hydration
+  // waits, so a too-aggressive cap risks trading "one annoying dead wait"
+  // for "logins that sometimes fail outright"). Verified empirically
+  // (3 consecutive real login runs, no failures) that those legitimate
+  // waits actually resolve in well under a second in practice - the cap
+  // was never close to touching them - so it's safe to tighten further.
+  const WAIT_CAP_MS = 1500;
+  if (!proto.__wgWaitForPatched) {
+    proto.__wgWaitForPatched = true;
+    const originalWaitFor = proto.waitFor;
+    proto.waitFor = function (options) {
+      const capped = { ...(options || {}), timeout: Math.min((options && options.timeout) || 30000, WAIT_CAP_MS) };
+      return originalWaitFor.call(this, capped);
+    };
+  }
+  const pageProto = Object.getPrototypeOf(page);
+  if (!pageProto.__wgWaitForTimeoutPatched) {
+    pageProto.__wgWaitForTimeoutPatched = true;
+    const originalWaitForTimeout = pageProto.waitForTimeout;
+    pageProto.waitForTimeout = function (ms) {
+      return originalWaitForTimeout.call(this, Math.min(ms, WAIT_CAP_MS));
+    };
+  }
 }
 
-async function runStepMode(engine, start, end, context, page, mem, resolved) {
-  instrumentFillHighlighting(page);
+async function runStepMode(engine, start, end, context, page, mem, resolved, slowMo, title) {
+  instrumentInteractionHighlighting(page, mem, slowMo);
+  // Some real Blocks (e.g. zsign-all's login.block.ts) call
+  // page.setViewportSize({ width: 1280, height: 720 }) inside their own
+  // act() - a hardcoded override for THEIR OWN testing consistency, with no
+  // idea an interactive human session is watching. Restoring the size
+  // AFTER each step (the first attempt at this) was still just repairing
+  // damage after the fact, on a delay, per-step - not the real fix. The
+  // real fix is to stop the override from ever landing at all: no-op
+  // setViewportSize entirely for the duration of step mode. Blocks that
+  // call it don't need it to actually do anything here - their own
+  // selectors/layouts still work fine at whatever size the real window
+  // already is.
+  page.setViewportSize = async () => {};
   let resolveNext = null;
   await page.exposeFunction("__wgNext", (edits) => {
     if (resolveNext) {
@@ -666,6 +901,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved) {
   const autoplayMs = process.env.WAYGRAPH_AUTOPLAY_MS ? Number(process.env.WAYGRAPH_AUTOPLAY_MS) : 1800;
   const gate = () => (autoplay ? new Promise((res) => setTimeout(() => res({}), autoplayMs)) : waitForNext());
   const allNames = resolved.map((r) => r.block.name);
+  const allDescriptions = resolved.map((r) => r.block.description || "");
 
   let result;
   for (let i = 0; i < resolved.length; i++) {
@@ -680,7 +916,17 @@ async function runStepMode(engine, start, end, context, page, mem, resolved) {
       }
       return { name: k.name, value };
     });
-    await renderBeforeStep(page, { index: i, total: resolved.length, blockName: r.block.name, keys, allNames, autoplay });
+    await renderBeforeStep(page, {
+      index: i,
+      total: resolved.length,
+      blockName: r.block.name,
+      description: r.block.description || "",
+      keys,
+      allNames,
+      allDescriptions,
+      autoplay,
+      title,
+    });
     const edits = await gate();
     for (const k of requires) {
       if (edits[k.name] !== undefined) {
@@ -708,7 +954,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved) {
       highlights,
       isLast: i === resolved.length - 1,
       allNames,
+      allDescriptions,
       autoplay,
+      title,
     });
     await gate();
   }
@@ -764,6 +1012,7 @@ async function main() {
       ? 350
       : undefined;
   const baseURL = process.env.WAYGRAPH_BASE_URL;
+  const title = process.env.WAYGRAPH_TITLE;
   const engine = new Engine({ headless: !headed, slowMo });
   let result;
   if (step || baseURL) {
@@ -789,7 +1038,7 @@ async function main() {
         if (baseURL) {
           await page.goto(baseURL).catch(() => {});
         }
-        result = await runStepMode(engine, start, end, context, page, mem, resolved);
+        result = await runStepMode(engine, start, end, context, page, mem, resolved, slowMo, title);
       } else {
         const blocks = resolved.map((r) => r.block);
         const chained = blocks.reduce((a, b) => connect(a, b));
@@ -924,6 +1173,11 @@ Usage:
                           just confirmed, then "Next" before moving on.
                           Implies headed - stepping through headless defeats
                           the point.
+      WAYGRAPH_AUTOPLAY=1     step mode only - hands-off, advances on a
+                          timer instead of waiting for clicks
+      WAYGRAPH_AUTOPLAY_MS=ms delay between auto-advances (default 1800)
+      WAYGRAPH_TITLE="..."    step mode only - a persistent top-right
+                          banner naming what this whole run is about
 
 "project" defaults to the current directory.
 `);

package/dist/engine.d.ts

@@ -299,6 +299,7 @@ export declare function branch<In extends Checkpoint<string>, Out extends Checkp
  */
 export declare function defineBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: {
     name: string;
+    description?: Block<In, Out>["description"];
     instruction: Instruction<In, Out, any>;
     next?: Block<In, Out>["next"];
     requires?: Block<In, Out>["requires"];

package/dist/engine.js

@@ -284,6 +284,7 @@ function stripMethods(block) {
     return {
         name: block.name,
         instruction: block.instruction,
+        ...(block.description ? { description: block.description } : {}),
         ...(block.next ? { next: block.next } : {}),
         ...(block.requires ? { requires: block.requires } : {}),
         ...(block.routes ? { routes: block.routes } : {}),
@@ -302,6 +303,7 @@ export function defineBlock(base) {
     const plain = {
         name: base.name,
         instruction: base.instruction,
+        ...(base.description ? { description: base.description } : {}),
         ...(base.next ? { next: base.next } : {}),
         ...(base.requires ? { requires: base.requires } : {}),
         ...(base.routes ? { routes: base.routes } : {}),

package/dist/types.d.ts

@@ -51,6 +51,24 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
      * {@link Block.modVerify} for changing this from outside the Block's own file.
      */
     verify?: Trait[] | ((out: Out) => Trait[]);
+    /**
+     * Optional. Arbitrary highlight points for step-mode tooling to show, in
+     * order, after this Block resolves - independent of `verify`, for
+     * calling out something worth a human's attention regardless of whether
+     * it's also being asserted ("remember this signature ID" isn't a
+     * pass/fail check). A function form picks different highlights per
+     * resolved `Out`, same as `verify`. Purely additive UI narration - never
+     * consulted by `runGraph`/`connect`/anything that decides behavior.
+     * @example highlights: (out) => [{ selector: "#signature-id", label: "remember this ID" }]
+     */
+    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
+}
+/** One arbitrary highlight point - see {@link Instruction.highlights}. */
+export interface WaygraphHighlight {
+    /** CSS selector for the element to highlight. */
+    selector: string;
+    /** Caption shown next to the highlight ring. */
+    label: string;
 }
 /**
  * A Block wraps one instruction. Its Observed type is an internal detail, erased here.
@@ -71,6 +89,16 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
 export interface Block<In extends Checkpoint<string>, Out extends Checkpoint<string>> {
     /** A short, stable label - shows up in every error this Block can produce ("trait X failed after Y"). */
     name: string;
+    /**
+     * A human-readable sentence describing what this Block actually tests or
+     * does - "the outsider case: a user outside a request's audience is
+     * denied its detail page," not a restatement of the code. Purely
+     * additive, optional narration for a human watching a run (step-mode
+     * tooling shows it before the Block runs) - never read by
+     * `runGraph`/`connect`/anything that decides behavior. A Block with none
+     * just shows its `name` instead.
+     */
+    description?: string;
     /** The act/observe/resolve/verify pipeline itself. See {@link Instruction}. */
     instruction: Instruction<In, Out, any>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "main": "./dist/index.js",