waygraph 0.15.47 → 0.15.50

package/dist/runner/network-capture.js

@@ -0,0 +1,126 @@
+// Real page network traffic -> the same network-tab overlay defineApiBlock's own calls use (see
+// inpage/network.js's own header). Playwright's page.on('request'/'requestfinished') events cover
+// every real request the PAGE makes (XHR/fetch/navigation) - not page.request.get()-style calls,
+// which go through a separate APIRequestContext entirely and never touch the browser at all (that
+// side is covered by defineApiBlock's own explicit call, in src/core/blocks/api.ts).
+import { addNetworkEntry, clearNetworkLog } from "./inpage/network.js";
+
+// Fetch/XHR/navigation only - a real page can fire dozens of image/font/stylesheet requests per
+// second, which would flood a panel meant to answer "what API calls did this page just made".
+const RELEVANT_TYPES = new Set(["xhr", "fetch", "document"]);
+// Response bodies this size or smaller, and only if they look text-ish, get captured for the
+// detail view - a multi-MB image/video response has no business being buffered into page memory
+// just because a demo happened to be running.
+const MAX_BODY_BYTES = 200_000;
+// Matches the in-page addNetworkEntry's own cap (network.js) - the Node-side history this backs
+// stays in sync with what the panel can actually show.
+const MAX_HISTORY = 30;
+
+/**
+ * Records one entry AND paints it live - the single place that touches page.__wgNetworkHistory,
+ * so every caller (this file's own listeners, defineApiBlock) stays in sync automatically. History
+ * lives on the Playwright `Page` object (Node side), which survives navigation - the panel DOM
+ * (page side, inside the shadow root) does not, and gets wiped on every real navigation. Without
+ * this, the "network tab" reset to empty on every step that navigated - not what a persistent
+ * Network tab is supposed to do.
+ */
+export function recordNetworkEntry(page, entry) {
+  page.__wgNetworkHistory = page.__wgNetworkHistory || [];
+  page.__wgNetworkHistory.push(entry);
+  while (page.__wgNetworkHistory.length > MAX_HISTORY) page.__wgNetworkHistory.shift();
+  return page.evaluate(addNetworkEntry, entry).catch(() => {});
+}
+
+/**
+ * Replays whatever history survived the last navigation back into a freshly (re)installed panel -
+ * call this after ensureShadowRoot, every step, same as the rest of the overlay's own per-step
+ * resync (banner/todos/device), and BEFORE that step's own network activity can add anything new
+ * (installOverlay runs at the very start of a step, so this is always true in practice - no
+ * interleaving race between "replay old" and "record new" to reason about). A no-op when there's
+ * no history yet, or the panel already shows exactly as many entries as history has (nothing was
+ * wiped this step). Otherwise clears and rebuilds from scratch, in order - simpler and more
+ * obviously correct than trying to diff/append just the "missing" ones.
+ */
+export async function restoreNetworkHistory(page) {
+  const history = page.__wgNetworkHistory;
+  if (!history || history.length === 0) return;
+  // page.__wgNetworkNeedsRestore is set by installNetworkCapture's own framenavigated listener -
+  // skip the page.evaluate() round-trip entirely (an extra one on EVERY step otherwise, since this
+  // runs from installOverlay every step) unless a real navigation actually happened since the last
+  // successful restore. A real, caught perf regression: this used to always evaluate() a shown-count
+  // check first, which measurably slowed down every step of every test that had ever captured any
+  // traffic at all, not just ones that navigate.
+  if (!page.__wgNetworkNeedsRestore) return;
+  page.__wgNetworkNeedsRestore = false;
+  await page.evaluate(clearNetworkLog).catch(() => {});
+  for (const entry of history) {
+    await page.evaluate(addNetworkEntry, entry).catch(() => {});
+  }
+}
+
+export function installNetworkCapture(page) {
+  if (page.__wgNetworkCaptureInstalled) return;
+  page.__wgNetworkCaptureInstalled = true;
+
+  // Marks history as needing a replay - see restoreNetworkHistory's own comment. Main frame only;
+  // an iframe navigating doesn't wipe the top-level shadow root the panel lives in.
+  page.on("framenavigated", (frame) => {
+    if (frame === page.mainFrame()) page.__wgNetworkNeedsRestore = true;
+  });
+
+  const startedAt = new Map();
+
+  page.on("request", (request) => {
+    startedAt.set(request, Date.now());
+  });
+
+  page.on("requestfinished", async (request) => {
+    try {
+      if (!RELEVANT_TYPES.has(request.resourceType())) return;
+      const response = await request.response();
+      if (!response) return;
+      const start = startedAt.get(request);
+      startedAt.delete(request);
+      let resBody;
+      try {
+        const contentType = (await response.headerValue("content-type")) || "";
+        if (/json|text|xml|html|javascript/.test(contentType)) {
+          const buf = await response.body();
+          if (buf.length <= MAX_BODY_BYTES) resBody = buf.toString("utf8");
+        }
+      } catch {
+        /* body already consumed / redirected away / not available - best-effort only */
+      }
+      const [reqHeaders, resHeaders] = await Promise.all([
+        request.allHeaders().catch(() => undefined),
+        response.allHeaders().catch(() => undefined),
+      ]);
+      await recordNetworkEntry(page, {
+        method: request.method(),
+        url: request.url(),
+        status: response.status(),
+        ok: response.ok(),
+        ms: start !== undefined ? Date.now() - start : undefined,
+        reqHeaders,
+        resHeaders,
+        reqBody: request.postData() || undefined,
+        resBody,
+      });
+    } catch {
+      /* a capture failure must never break the actual run it's observing */
+    }
+  });
+
+  page.on("requestfailed", (request) => {
+    startedAt.delete(request);
+    if (!RELEVANT_TYPES.has(request.resourceType())) return;
+    recordNetworkEntry(page, {
+      method: request.method(),
+      url: request.url(),
+      status: 0,
+      ok: false,
+      reqBody: request.postData() || undefined,
+      resBody: request.failure() ? request.failure().errorText : undefined,
+    });
+  });
+}

package/dist/runner/overlay-css.js

@@ -80,7 +80,7 @@ export const RUNNER_EXTRA_CSS =
   // Todo checklist(s) float outside #wg-panel so --mini / Hide never hide them.
   // Multiple docks (one per todoId) are supported - stacked on the same side.
   // Click a dock to slide left <-> right (WAYGRAPH_TODO_POS / --todo-left|right).
-  ".wg-todo-dock,#wg-todo-dock{position:fixed;z-index:2147483646;top:72px;left:14px;" +
+  ".wg-todo-dock,#wg-todo-dock{position:fixed;z-index:2147483646;top:104px;left:14px;" +
   "width:min(280px,42vw);max-height:calc(100vh - 100px);overflow:auto;box-sizing:border-box;" +
   "padding:10px 12px;background:" + SURFACE + ";color:#fff;border-radius:12px;" +
   "border:1px solid rgba(124,58,237,.45);box-shadow:0 8px 24px rgba(0,0,0,.35);" +
@@ -102,18 +102,74 @@ export const RUNNER_EXTRA_CSS =
   ".wg-todo-dock .wg-todo-dock-title{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
   "letter-spacing:.04em;text-transform:uppercase;margin:0 0 8px;}" +
   ".wg-todo-dock .wg-todos-list,#wg-todo-dock #wg-todos,.wg-todo-dock #wg-todos{list-style:none;margin:0;padding:0;background:transparent;border:none;}" +
-  // Always-on zoom HUD - bottom-right (top-left is crowded: todos + banners).
+  // Always-on zoom HUD - bottom-right (top-left is crowded: todos + banners). Violet, matching the
+  // rest of the overlay's design tokens - this used to be a lone amber/yellow badge, the one
+  // surface that never got pulled into the shared palette when everything else did.
   "#wg-zoom-badge{position:fixed;z-index:2147483646;bottom:14px;right:14px;" +
   "display:flex;align-items:center;gap:7px;padding:6px 11px 6px 8px;" +
   "border-radius:999px;background:" + SURFACE + ";color:#f0e8ff;" +
-  "border:1px solid rgba(250,204,21,.6);box-shadow:0 6px 18px rgba(0,0,0,.4);" +
+  "border:1px solid rgba(124,58,237,.55);box-shadow:0 6px 18px rgba(0,0,0,.4);" +
   "font:700 12px/1.2 system-ui,sans-serif;pointer-events:none;" +
   "opacity:1;transform:translateY(0);}" +
   "#wg-zoom-badge .wg-zoom-ico{width:18px;height:18px;display:flex;align-items:center;justify-content:center;" +
-  "border-radius:6px;background:rgba(250,204,21,.22);}" +
+  "border-radius:6px;background:rgba(124,58,237,.28);}" +
   "#wg-zoom-badge .wg-zoom-ico svg{width:14px;height:14px;display:block;}" +
-  "#wg-zoom-badge .wg-zoom-val{color:#fde68a;font-variant-numeric:tabular-nums;font-weight:800;min-width:3.2em;}" +
-  "#wg-zoom-badge[data-zoomed=\"1\"]{border-color:#fbbf24;}" +
+  "#wg-zoom-badge .wg-zoom-val{color:#c9a6ff;font-variant-numeric:tabular-nums;font-weight:800;min-width:3.2em;}" +
+  "#wg-zoom-badge[data-zoomed=\"1\"]{border-color:#7C3AED;}" +
+  // Network-tab overlay (real page traffic via network-capture.js + defineApiBlock's own
+  // page.request calls) - bottom-left, the one corner free of the zoom HUD (bottom-right) and the
+  // typing chip (bottom-center). Persistent (does not auto-fade) once any entry exists - this is a
+  // real Postman/DevTools-style inspector meant to be reviewed, not a flash-and-gone toast.
+  "#wg-network-log{position:fixed;z-index:2147483646;bottom:14px;left:14px;min-width:260px;" +
+  "max-width:min(92vw,420px);max-height:min(60vh,420px);display:flex;flex-direction:column;" +
+  "border-radius:10px;background:" + SURFACE + ";color:#f0e8ff;border:1px solid rgba(124,58,237,.45);" +
+  "box-shadow:0 8px 22px rgba(0,0,0,.4);font:12px/1.4 ui-monospace,\"SF Mono\",Consolas,monospace;" +
+  "opacity:0;transform:translateY(8px);transition:opacity .25s ease,transform .25s ease;overflow:hidden;}" +
+  "#wg-network-log.wg-in{opacity:1;transform:translateY(0);}" +
+  "#wg-network-log.wg-net-collapsed .wg-net-list{display:none;}" +
+  "#wg-network-log .wg-net-header{display:flex;align-items:center;gap:6px;padding:8px 10px;" +
+  "border-bottom:1px solid rgba(124,58,237,.25);cursor:default;flex:0 0 auto;}" +
+  "#wg-network-log .wg-net-title{font:700 10px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
+  "letter-spacing:.06em;text-transform:uppercase;flex:1 1 auto;}" +
+  "#wg-network-log .wg-net-count{font:700 10px/1.2 system-ui,sans-serif;color:#9CA3AF;" +
+  "background:rgba(124,58,237,.22);border-radius:999px;padding:1px 7px;}" +
+  "#wg-network-log .wg-net-collapse{flex:0 0 auto;width:18px;height:18px;border-radius:5px;border:none;" +
+  "background:rgba(124,58,237,.28);color:#e8dcff;font:700 13px/1 system-ui,sans-serif;cursor:pointer;" +
+  "pointer-events:auto;}" +
+  "#wg-network-log .wg-net-collapse:hover{background:rgba(124,58,237,.42);}" +
+  "#wg-network-log .wg-net-list{list-style:none;margin:0;padding:6px 8px;display:flex;" +
+  "flex-direction:column;gap:2px;overflow-y:auto;pointer-events:auto;}" +
+  "#wg-network-log .wg-net-row{display:flex;align-items:baseline;gap:7px;opacity:0;padding:3px 4px;" +
+  "border-radius:5px;cursor:pointer;transform:translateX(-4px);transition:opacity .2s ease,transform .2s ease;}" +
+  "#wg-network-log .wg-net-row:hover,#wg-network-log .wg-net-row.wg-net-open{background:rgba(124,58,237,.18);}" +
+  "#wg-network-log .wg-net-row.wg-in{opacity:1;transform:translateX(0);}" +
+  "#wg-network-log .wg-net-method{flex:0 0 auto;font-weight:800;font-size:10px;min-width:38px;}" +
+  "#wg-network-log .wg-net-method-get{color:#3B82F6;}" +
+  "#wg-network-log .wg-net-method-post{color:#22C55E;}" +
+  "#wg-network-log .wg-net-method-put{color:#F97316;}" +
+  "#wg-network-log .wg-net-method-delete{color:#EF4444;}" +
+  "#wg-network-log .wg-net-method-other{color:#9CA3AF;}" +
+  "#wg-network-log .wg-net-path{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;" +
+  "white-space:nowrap;color:#e0e0f0;}" +
+  "#wg-network-log .wg-net-status{flex:0 0 auto;font-weight:700;color:#22C55E;}" +
+  "#wg-network-log .wg-net-row[data-ok=\"0\"] .wg-net-status{color:#EF4444;}" +
+  "#wg-network-log .wg-net-ms{flex:0 0 auto;color:#9CA3AF;font-size:10px;}" +
+  "#wg-network-log .wg-net-detail{list-style:none;background:rgba(0,0,0,.28);border-radius:6px;" +
+  "padding:8px;margin:2px 0 6px;}" +
+  "#wg-network-log .wg-net-detail-section{margin-bottom:8px;}" +
+  "#wg-network-log .wg-net-detail-section:last-child{margin-bottom:0;}" +
+  "#wg-network-log .wg-net-detail-section h4{margin:0 0 4px;font:700 9px/1.2 system-ui,sans-serif;" +
+  "color:#9CA3AF;letter-spacing:.06em;text-transform:uppercase;}" +
+  "#wg-network-log .wg-net-headers{width:100%;border-collapse:collapse;font-size:11px;}" +
+  "#wg-network-log .wg-net-headers td{padding:1px 6px 1px 0;vertical-align:top;word-break:break-all;}" +
+  "#wg-network-log .wg-net-headers td:first-child{color:#c9a6ff;white-space:nowrap;}" +
+  "#wg-network-log .wg-net-body{margin:0;font-size:11px;white-space:pre-wrap;word-break:break-all;" +
+  "max-height:160px;overflow-y:auto;color:#e0e0f0;}" +
+  "#wg-network-log .wg-net-curl{color:#7dd3fc;}" +
+  "#wg-network-log .wg-net-empty{font-size:11px;color:#6b7280;font-style:italic;}" +
+  "#wg-network-log .wg-net-copy{margin-top:5px;padding:3px 9px;border-radius:5px;border:1px solid rgba(124,58,237,.5);" +
+  "background:rgba(124,58,237,.22);color:#e8dcff;font:700 10px system-ui,sans-serif;cursor:pointer;}" +
+  "#wg-network-log .wg-net-copy:hover{background:rgba(124,58,237,.38);}" +
   // Typing chip (method fills: username / password / etc.)
   "#wg-typing-badge{position:fixed;z-index:2147483646;bottom:88px;left:50%;transform:translateX(-50%);" +
   "display:flex;align-items:center;gap:8px;padding:8px 14px;" +
@@ -254,7 +310,15 @@ export const RUNNER_EXTRA_CSS =
   // Hide / Show chrome: collapsed = compact "N / M · block" pill + Next (manual).
   "#wg-panel .wg-chrome{display:flex;align-items:center;justify-content:space-between;gap:8px;margin:0 0 8px;}" +
   "#wg-panel .wg-chrome-title{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
-  "letter-spacing:.04em;text-transform:uppercase;flex:1;min-width:0;}" +
+  "letter-spacing:.04em;text-transform:uppercase;flex:1;min-width:0;display:flex;align-items:center;gap:4px;}" +
+  // Animated fast-forward indicator on the collapsed bottom-center pill - a blitzed/FF step has
+  // no ring, no narration theater, nothing else visible marking it as different, so it read as
+  // just another normal step with no explanation for why it snapped past instantly.
+  "#wg-panel .wg-ff-icon{display:inline-flex;align-items:center;flex-shrink:0;width:13px;height:13px;}" +
+  "#wg-panel .wg-ff-icon svg{width:100%;height:100%;display:block;}" +
+  "#wg-panel .wg-ff-icon .wg-ff-chev{animation:wg-ff-pulse 900ms ease-in-out infinite;}" +
+  "#wg-panel .wg-ff-icon .wg-ff-chev:nth-child(2){animation-delay:150ms;}" +
+  "@keyframes wg-ff-pulse{0%,100%{opacity:.3;transform:translateX(-1.5px);}50%{opacity:1;transform:translateX(1.5px);}}" +
   "#wg-panel .wg-chrome-actions{display:flex;align-items:center;gap:6px;flex-shrink:0;}" +
   "#wg-panel button.wg-hide-btn,#wg-panel button.wg-mini-next{margin:0;padding:4px 10px;font:600 11px system-ui,sans-serif;" +
   "background:#3a2a60;color:#e8dcff;border:1px solid #5b3aa8;border-radius:6px;cursor:pointer;}" +

package/dist/runner/overlay-install.js

@@ -6,16 +6,46 @@ import { resolveTodoDockUi } from "../highlights.js";
 import { installCore } from "./inpage/core.js";
 import { installSwipeZoom } from "./inpage/swipe-zoom.js";
 import { installBanner } from "./inpage/banner.js";
+import { showCaption, hideCaption } from "./inpage/caption.js";
 import { installStamp } from "./inpage/stamp.js";
 import { installPanelChrome } from "./inpage/panel-chrome.js";
 import { installTodos } from "./inpage/todos.js";
 import { installDevice } from "./inpage/device.js";
 import { applyVideoDeviceStage } from "./device-stage.js";
+import { installNetworkCapture, restoreNetworkHistory } from "./network-capture.js";
+import { setNetworkTabVisible } from "./inpage/network.js";
 
-/** `ui` = authored banner UX from the stub phase: { pos, collision, hidden } (all optional). */
-export async function installOverlay(page, title, ui) {
+/**
+ * `ui` = authored banner UX from the stub phase: { pos, collision, hidden } (all optional).
+ * `caption` = bottom subtitle-bar text (ctx.caption()/ctx.hideCaption()) - `undefined` leaves it
+ * alone (unset this step), `""` hides it, any other string shows/updates it.
+ * `networkTabVisible` = network-tab panel shown/hidden (ctx.showNetworkTab()/hideNetworkTab()) -
+ * `undefined` leaves it alone (default state is hidden, set the very first time restoreNetworkHistory
+ * builds a panel); capture itself is unconditional and unaffected by this either way.
+ */
+export async function installOverlay(page, title, ui, caption, networkTabVisible) {
   // ring/cursor/banner/dock come from the ONE shared bundle every surface installs (ui/css/*.css).
   await ensureShadowRoot(page);
+  // Idempotent (guarded on page.__wgNetworkCaptureInstalled) - safe to call every step even though
+  // installOverlay itself runs every step; the page.on() listeners this installs are attached to
+  // the Page object, not any one document, so they already survive navigations on their own.
+  installNetworkCapture(page);
+  // Visibility is Node-side state too (page.__wgNetworkTabVisible), same reason history is: a
+  // navigation wipes window.__wgNetworkTabVisible along with the rest of the page-side JS state,
+  // so "shown" would silently revert to the hidden default on the very next navigated step without
+  // this. Default false (hidden) - matches addNetworkEntry's own default-hidden behavior.
+  if (networkTabVisible !== undefined) page.__wgNetworkTabVisible = !!networkTabVisible;
+  await page.evaluate((v) => { window.__wgNetworkTabVisible = v; }, !!page.__wgNetworkTabVisible).catch(() => {});
+  // Real bug this fixes: a navigation wipes the shadow root (and with it, the network panel's DOM
+  // and in-page entry list) - without replaying page.__wgNetworkHistory (Node-side, survives
+  // navigation) back in every step, the "network tab" silently reset to empty on any step that
+  // navigated, instead of staying persistent like a real Network tab.
+  await restoreNetworkHistory(page);
+  // Explicit toggle too, not just the flag write above - covers the case where the panel already
+  // existed (no restore ran this step) and this step's `networkTabVisible` differs from before.
+  if (networkTabVisible !== undefined) {
+    await page.evaluate(setNetworkTabVisible, networkTabVisible).catch(() => {});
+  }
   // Runner-only chrome (step panel, zoom/typing/device chips) - separate key, no collision.
   await page.evaluate(([css, key]) => __wgCss(css, key), [RUNNER_EXTRA_CSS, "wg-runner-css"]).catch(() => {});
   await page.addStyleTag({ content: HOST_CSS }).catch(() => {});
@@ -36,6 +66,13 @@ export async function installOverlay(page, title, ui) {
   await page.evaluate(installPanelChrome, args).catch(() => {});
   await page.evaluate(installTodos, args).catch(() => {});
   await page.evaluate(installDevice, args).catch(() => {});
+  if (caption !== undefined) {
+    if (caption === "") {
+      await page.evaluate(hideCaption).catch(() => {});
+    } else {
+      await page.evaluate(showCaption, caption).catch(() => {});
+    }
+  }
   // Navigations wipe #wg-device-shell - rebuild when video stage + device are live.
   // If we already shuttered to desktop-flat, re-apply FLAT (never re-add bezel).
   if (

package/dist/runner/overlay-stage.js

@@ -97,6 +97,11 @@ export function createOverlayStage(page, { todoDockRef, deviceRef }) {
     deviceRef.current = state.lastDevice;
     if (appliedDevice.sync !== "keep" || (reapplyDeviceOnKeep && state.lastDevice)) {
       await applyDeviceToPage(page, state.lastDevice, appliedDevice.sync);
+      // A deliberate settle beat: applyDeviceToPage's own viewport lerp is fully awaited above, but
+      // a ring/camera-zoom transition kicked off immediately after (the very next thing this step
+      // does) reads as happening AT THE SAME TIME as the device change on video, with no visual
+      // breathing room between them - two transitions with no gap look like one confused one.
+      await new Promise((r) => setTimeout(r, 220));
     }
     return { appliedTodo, appliedDevice };
   };

package/dist/runner/rings.js

@@ -207,15 +207,25 @@ export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
     try {
       await ensureSelectorInView(page, h.selector);
       await applyHighlightZoom(page, h.selector, h.zoom, h.zoomOut);
-      // Prefer live in-page rect (honors device-shell scale) over Playwright box.
-      const box = await page
-        .evaluate((sel) => {
-          const el = document.querySelector(sel);
-          if (!el) return null;
-          const r = el.getBoundingClientRect();
-          return { x: r.x, y: r.y, width: r.width, height: r.height };
-        }, h.selector)
-        .catch(() => null);
+      // Prefer live in-page rect (honors device-shell scale) over Playwright's own boundingBox() -
+      // but resolve the element through Playwright's OWN locator (full selector engine: >>
+      // piercing, :has-text(), :visible, ...), not a raw DOM querySelector, which only understands
+      // real CSS and silently fails to match any Playwright-specific selector syntax.
+      // count() gate: a real, caught regression - Locator.evaluate() has no timeout option and
+      // auto-waits (Playwright's default ~30s) for a match to appear, unlike the instant
+      // document.querySelector it replaced. count() alone never waits, so this stays an immediate
+      // "does it exist right now" check - ensureSelectorInView above already gave the page a real
+      // moment to settle.
+      const hLoc = page.locator(h.selector).first();
+      const box =
+        (await hLoc.count().catch(() => 0)) > 0
+          ? await hLoc
+              .evaluate((el) => {
+                const r = el.getBoundingClientRect();
+                return { x: r.x, y: r.y, width: r.width, height: r.height };
+              })
+              .catch(() => null)
+          : null;
       if (box && box.width > 0 && box.height > 0) {
         await showRing(page, box, h.label, h.tone || "planned", {
           size: h.size,
@@ -318,44 +328,52 @@ export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   }
   if (list.length > 0) {
     const last = list[list.length - 1];
+    // Resolved through Playwright's own locator (>> piercing / :has-text() / :visible support),
+    // not handed to the page as a string for a raw DOM querySelector to fail silently on - see
+    // showRing's own comment (same fix, same reason) and __wgFollowRing's in core.js.
+    const handle = last.selector
+      ? await page.locator(last.selector).first().elementHandle({ timeout: 100 }).catch(() => null)
+      : null;
     await page
-      .evaluate((h) => {
-        if (!window.__wgFollowRing && !window.__wgPositionRing) return;
-        if (window.__wgFollowRing) {
-          window.__wgFollowRing(
-            h.selector,
-            h.label,
-            h.tone || "planned",
-            { size: h.size || "md", weight: h.weight || "normal" },
-            !!h.focus,
-          );
-          return;
-        }
-        const reposition = () => {
-          const el = document.querySelector(h.selector);
+      .evaluate(
+        ({ h, el }) => {
+          if (el && window.__wgFollowRing) {
+            window.__wgFollowRing(
+              el,
+              h.label,
+              h.tone || "planned",
+              { size: h.size || "md", weight: h.weight || "normal" },
+              !!h.focus,
+            );
+            return;
+          }
+          if (!window.__wgPositionRing) return;
           if (!el) {
             if (window.__wgHideRing) window.__wgHideRing();
             return;
           }
-          const box = el.getBoundingClientRect();
-          window.__wgPositionRing(box, h.label, h.tone || "planned", {
-            size: h.size || "md",
-            weight: h.weight || "normal",
-          });
-          if (h.focus && window.__wgApplyFocus) {
-            window.__wgApplyFocus({
-              x: box.x,
-              y: box.y,
-              width: box.width,
-              height: box.height,
+          const reposition = () => {
+            const box = el.getBoundingClientRect();
+            window.__wgPositionRing(box, h.label, h.tone || "planned", {
+              size: h.size || "md",
+              weight: h.weight || "normal",
             });
-          }
-        };
-        reposition();
-        window.__wgRingTrack = reposition;
-        window.addEventListener("resize", reposition);
-        window.addEventListener("scroll", reposition, true);
-      }, last)
+            if (h.focus && window.__wgApplyFocus) {
+              window.__wgApplyFocus({
+                x: box.x,
+                y: box.y,
+                width: box.width,
+                height: box.height,
+              });
+            }
+          };
+          reposition();
+          window.__wgRingTrack = reposition;
+          window.addEventListener("resize", reposition);
+          window.addEventListener("scroll", reposition, true);
+        },
+        { h: last, el: handle },
+      )
       .catch(() => {});
   } else {
     await hideRing(page);
@@ -417,11 +435,17 @@ export async function showRing(page, box, label, tone, style) {
   const weight = normalizeHighlightWeight(style && style.weight);
   const selector = style && style.selector ? String(style.selector) : "";
   const focus = !!(style && style.focus);
+  // Resolve through Playwright's own locator (full selector engine), not a selector string handed
+  // to the page for a raw DOM lookup - >> piercing / :has-text() / :visible are Playwright-only
+  // syntax, invisible to document.querySelector. The resolved element handle is passed straight
+  // into evaluate (Playwright unwraps it to the real DOM node inside the page), so __wgFollowRing's
+  // per-frame RAF loop tracks that exact element directly - no repeated selector re-resolution.
+  const handle = selector ? await page.locator(selector).first().elementHandle({ timeout: 100 }).catch(() => null) : null;
   await page
     .evaluate(
-      ({ box, label, tone, size, weight, selector, focus }) => {
-        if (selector && window.__wgFollowRing) {
-          window.__wgFollowRing(selector, label, tone || "planned", { size, weight }, focus);
+      ({ box, label, tone, size, weight, el, focus }) => {
+        if (el && window.__wgFollowRing) {
+          window.__wgFollowRing(el, label, tone || "planned", { size, weight }, focus);
           return;
         }
         if (window.__wgStopRingFollow) window.__wgStopRingFollow();
@@ -431,7 +455,7 @@ export async function showRing(page, box, label, tone, style) {
         if (focus && box && window.__wgApplyFocus) window.__wgApplyFocus(box);
         else if (!focus && window.__wgClearFocus) window.__wgClearFocus();
       },
-      { box, label, tone: tone || "planned", size, weight, selector, focus },
+      { box, label, tone: tone || "planned", size, weight, el: handle, focus },
     )
     .catch(() => {});
 }

package/dist/runner/slides.js

@@ -43,14 +43,20 @@ export async function presentSlides(page, slides, _gate, opts) {
       try {
         await ensureSelectorInView(page, s.selector);
         await applyHighlightZoom(page, s.selector, s.zoom, s.zoomOut);
-        const box = await page
-          .evaluate((sel) => {
-            const el = document.querySelector(sel);
-            if (!el) return null;
-            const r = el.getBoundingClientRect();
-            return { x: r.x, y: r.y, width: r.width, height: r.height };
-          }, s.selector)
-          .catch(() => null);
+        // Playwright's own locator (>> piercing / :has-text() / :visible support), not a raw
+        // querySelector string - see rings.js's showRing for the same fix, same reason. count()
+        // gate: Locator.evaluate() has no timeout option and auto-waits ~30s for a match to
+        // appear - count() never waits, keeping this an immediate "does it exist now" check.
+        const sLoc = page.locator(s.selector).first();
+        const box =
+          (await sLoc.count().catch(() => 0)) > 0
+            ? await sLoc
+                .evaluate((el) => {
+                  const r = el.getBoundingClientRect();
+                  return { x: r.x, y: r.y, width: r.width, height: r.height };
+                })
+                .catch(() => null)
+            : null;
         if (box && box.width > 0 && box.height > 0) {
           await showRing(page, box, caption, slideTone, {
             ...slideStyle,

package/dist/runner/step-mode.js

@@ -342,6 +342,10 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
       justEnteredEpisode,
       title: overlayTitle,
       bannerUi: stage.state.lastBannerUi,
+      caption: stubBeforePhase.caption,
+      networkTabVisible: stubBeforePhase.networkTabVisible,
+      fastForward: !!r.block.fastForward,
+      isApi: r.block.__waygraphKind === "api",
       todoPos: overlayTodoPos,
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
@@ -544,6 +548,8 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
     let highlights;
     let stubAfterTodos = [];
     let afterOverlayTitle = overlayTitle;
+    let afterCaption; // undefined = leave whatever's currently shown alone (see installOverlay's own comment)
+    let afterNetworkTabVisible; // undefined = leave the network tab's current shown/hidden state alone
     let afterTodoPos = overlayTodoPos;
     let appliedAfter = { dock: stage.state.lastTodoDock, sync: "keep" };
     let appliedDeviceAfter = { device: stage.state.lastDevice, sync: "keep" };
@@ -573,6 +579,8 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
       if (afterPhase.title && String(afterPhase.title).trim()) {
         afterOverlayTitle = String(afterPhase.title).trim();
       }
+      if (afterPhase.caption !== undefined) afterCaption = afterPhase.caption;
+      if (afterPhase.networkTabVisible !== undefined) afterNetworkTabVisible = afterPhase.networkTabVisible;
       if (afterPhase.todoPos) afterTodoPos = afterPhase.todoPos;
       if (stage.state.lastTodoDock && stage.state.lastTodoDock.pos) afterTodoPos = stage.state.lastTodoDock.pos;
       highlights = afterPhase.highlights.map((h) => {
@@ -615,6 +623,10 @@ export async function runStepMode(engine, start, end, context, page, mem, resolv
       allEpisodes,
       title: afterOverlayTitle,
       bannerUi: stage.state.lastBannerUi,
+      caption: afterCaption,
+      networkTabVisible: afterNetworkTabVisible,
+      fastForward: !!r.block.fastForward,
+      isApi: r.block.__waygraphKind === "api",
       todoPos: afterTodoPos,
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,

package/dist/runner/step-panels.js

@@ -6,7 +6,7 @@ import { applyHighlightStyleDefaults, formatHighlightCaption, hasAuthoredStubOnE
 import { cycleHighlightRings } from "./rings.js";
 
 export async function renderBeforeStep(page, info) {
-  await installOverlay(page, info.title, info.bannerUi);
+  await installOverlay(page, info.title, info.bannerUi, info.caption, info.networkTabVisible);
   // 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
@@ -135,6 +135,8 @@ export async function renderBeforeStep(page, info) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
           stepLabel: info.stepLabel || "",
           forceCollapsed: info.forceCollapsed === true ? true : undefined,
+          fastForward: !!info.fastForward,
+          isApi: !!info.isApi,
         });
       }
       if (window.__wgSyncTodos) {
@@ -375,7 +377,7 @@ export async function presentFailPanel(page, opts) {
 
 
 export async function renderAfterStep(page, info) {
-  await installOverlay(page, info.title, info.bannerUi);
+  await installOverlay(page, info.title, info.bannerUi, info.caption, info.networkTabVisible);
   // Clear any tracker from a previous highlight before cycling through this
   // step's own.
   await page
@@ -506,6 +508,8 @@ export async function renderAfterStep(page, info) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
           stepLabel: info.stepLabel || "",
           forceCollapsed: info.forceCollapsed === true ? true : undefined,
+          fastForward: !!info.fastForward,
+          isApi: !!info.isApi,
         });
       }
       if (window.__wgSyncTodos) {
@@ -574,7 +578,7 @@ export async function renderAfterStep(page, info) {
  * regardless - main()'s own try/finally - but not before this is visible).
  */
 async function renderStepError(page, info) {
-  await installOverlay(page, info.title, info.bannerUi);
+  await installOverlay(page, info.title, info.bannerUi, info.caption, info.networkTabVisible);
   const errorPayload = { ...info, stepLabel: miniStepLabel(info) };
   await page
     .evaluate((info) => {
@@ -640,6 +644,8 @@ async function renderStepError(page, info) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
           stepLabel: info.stepLabel || "",
           forceCollapsed: info.forceCollapsed === true ? true : undefined,
+          fastForward: !!info.fastForward,
+          isApi: !!info.isApi,
         });
       }
       if (window.__wgStampModal) {

package/dist/runner/teardown.js

@@ -110,15 +110,22 @@ export async function restoreTheaterAfterNavigation(page, todoDockRef, deviceRef
   const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
   for (const h of stubs) {
     if (!h || !h.selector) continue;
-    const box = await page
-      .evaluate((sel) => {
-        const el = document.querySelector(sel);
-        if (!el) return null;
-        const r = el.getBoundingClientRect();
-        if (r.width < 2 || r.height < 2) return null;
-        return { x: r.x, y: r.y, width: r.width, height: r.height };
-      }, h.selector)
-      .catch(() => null);
+    // Playwright's own locator (>> piercing / :has-text() / :visible support), not a raw
+    // querySelector string - see rings.js's showRing for the same fix, same reason. count() gate:
+    // Locator.evaluate() has no timeout option and auto-waits ~30s for a match to appear - count()
+    // never waits, keeping this an immediate "does it still exist" check (this selector routinely
+    // won't, after a route change - that's the whole point of the loop).
+    const hLoc = page.locator(h.selector).first();
+    const box =
+      (await hLoc.count().catch(() => 0)) > 0
+        ? await hLoc
+            .evaluate((el) => {
+              const r = el.getBoundingClientRect();
+              if (r.width < 2 || r.height < 2) return null;
+              return { x: r.x, y: r.y, width: r.width, height: r.height };
+            })
+            .catch(() => null)
+        : null;
     if (box) {
       await showRing(page, box, formatHighlightCaption(h), h.tone || "planned", {
         size: h.size,

package/dist/session/auto-explore-run.d.ts

@@ -1,8 +1,9 @@
 import type { Page, BrowserContext } from "@playwright/test";
-import { Engine } from "../engine.js";
+import { Engine } from "../core.js";
 import { MemPage } from "../mem-page.js";
 import { type BlockEntry } from "./auto-explore.js";
 import type { Checkpoint } from "../types.js";
+import { resolveBaseUrl } from "../config.js";
 export interface AutoExploreOptions {
     /** Terminal menu (browser still runs for act()). Default false = headful picker panel. */
     cli?: boolean;
@@ -12,7 +13,9 @@ export interface AutoExploreOptions {
     /** Phase C: glob / regex / bare `--blocks` file select for discovery. */
     blocksSelect?: import("../blocks-select.js").BlocksSelect;
 }
-export declare function resolveBaseUrl(projectDir: string): string | undefined;
+/** See `../config.js`'s own `resolveBaseUrl` - re-exported so existing importers of this module
+ * don't need to change their import path. */
+export { resolveBaseUrl };
 export declare function detectHere(page: Page, navBlocks: BlockEntry[]): Promise<string | null>;
 export declare function ensureLivePage(context: BrowserContext, page: Page, startUrl: string | undefined): Promise<Page>;
 /**