waygraph 0.15.47 → 0.15.49

package/dist/runner/inpage/network.js

@@ -0,0 +1,217 @@
+// In-page installer (page.evaluate target) - must stay self-contained, no module-scope closure
+// (page.evaluate serializes ONLY the passed function's own source, not sibling top-level
+// functions in this file - every helper below is nested inside addNetworkEntry itself for exactly
+// that reason; a row's click handler still works after addNetworkEntry returns because it's a
+// closure over ITS OWN invocation's nested helpers, not a reference to module scope).
+//
+// A real network-tab overlay (`#wg-network-log`): the DevTools Network panel itself can't be
+// embedded (it lives in browser chrome, not reachable from automation), but every entry's real
+// data is - this renders that, on-page: method, url, status, and (click a row) request/response
+// headers + bodies + a "copy as cURL" command, a Postman-style inspector for both real page
+// traffic (installNetworkCapture, network-capture.js) and defineApiBlock's own page.request calls.
+export function addNetworkEntry(entry) {
+  // No-op outside a demo/pilot/auto run - ensureShadowRoot() (and its __wgById/__wgAdd globals)
+  // is never installed for a plain `waygraph run`/Playwright test, and this must not throw there.
+  if (typeof __wgById !== "function" || typeof __wgAdd !== "function") return;
+
+  function esc(s) {
+    const d = document.createElement("div");
+    d.textContent = String(s == null ? "" : s);
+    return d.innerHTML;
+  }
+
+  function methodClass(method) {
+    const m = (method || "GET").toUpperCase();
+    if (m === "GET") return "get";
+    if (m === "POST") return "post";
+    if (m === "PUT" || m === "PATCH") return "put";
+    if (m === "DELETE") return "delete";
+    return "other";
+  }
+
+  function toCurl(e) {
+    let cmd = "curl -X " + (e.method || "GET") + " '" + String(e.url || "").replace(/'/g, "'\\''") + "'";
+    const headers = e.reqHeaders || {};
+    for (const k of Object.keys(headers)) {
+      if (/^:/.test(k)) continue; // HTTP/2 pseudo-headers - not valid curl -H input
+      cmd += " \\\n  -H '" + k + ": " + String(headers[k]).replace(/'/g, "'\\''") + "'";
+    }
+    if (e.reqBody) cmd += " \\\n  --data '" + String(e.reqBody).replace(/'/g, "'\\''") + "'";
+    return cmd;
+  }
+
+  function renderHeaders(headers) {
+    const h = headers || {};
+    const keys = Object.keys(h);
+    if (keys.length === 0) return '<div class="wg-net-empty">(none)</div>';
+    return (
+      '<table class="wg-net-headers">' +
+      keys.map((k) => "<tr><td>" + esc(k) + "</td><td>" + esc(h[k]) + "</td></tr>").join("") +
+      "</table>"
+    );
+  }
+
+  function renderBody(body) {
+    if (body === undefined || body === null || body === "") return '<div class="wg-net-empty">(empty)</div>';
+    let text = body;
+    try {
+      text = JSON.stringify(JSON.parse(body), null, 2);
+    } catch {
+      /* not JSON - show raw */
+    }
+    return "<pre class=\"wg-net-body\">" + esc(String(text).slice(0, 4000)) + "</pre>";
+  }
+
+  function renderDetail(e) {
+    return (
+      '<div class="wg-net-detail-section"><h4>Request headers</h4>' +
+      renderHeaders(e.reqHeaders) +
+      "</div>" +
+      (e.reqBody
+        ? '<div class="wg-net-detail-section"><h4>Request body</h4>' + renderBody(e.reqBody) + "</div>"
+        : "") +
+      '<div class="wg-net-detail-section"><h4>Response headers</h4>' +
+      renderHeaders(e.resHeaders) +
+      "</div>" +
+      '<div class="wg-net-detail-section"><h4>Response body</h4>' +
+      renderBody(e.resBody) +
+      "</div>" +
+      '<div class="wg-net-detail-section"><h4>cURL</h4>' +
+      '<pre class="wg-net-body wg-net-curl">' +
+      esc(toCurl(e)) +
+      "</pre>" +
+      '<button type="button" class="wg-net-copy" data-copy="1">Copy as cURL</button></div>'
+    );
+  }
+
+  let panel = __wgById("wg-network-log");
+  if (!panel) {
+    panel = document.createElement("div");
+    panel.id = "wg-network-log";
+    panel.setAttribute("data-wg-ui", "1");
+    const header = document.createElement("div");
+    header.className = "wg-net-header";
+    const title = document.createElement("span");
+    title.className = "wg-net-title";
+    title.textContent = "Network";
+    const count = document.createElement("span");
+    count.className = "wg-net-count";
+    count.textContent = "0";
+    const toggle = document.createElement("button");
+    toggle.type = "button";
+    toggle.className = "wg-net-collapse";
+    toggle.textContent = "−"; // minus
+    toggle.addEventListener("click", (ev) => {
+      ev.stopPropagation();
+      panel.classList.toggle("wg-net-collapsed");
+      toggle.textContent = panel.classList.contains("wg-net-collapsed") ? "+" : "−";
+    });
+    header.appendChild(title);
+    header.appendChild(count);
+    header.appendChild(toggle);
+    const list = document.createElement("ol");
+    list.className = "wg-net-list";
+    panel.appendChild(header);
+    panel.appendChild(list);
+    __wgAdd(panel);
+  }
+
+  const w = window;
+  w.__wgNetworkEntries = w.__wgNetworkEntries || [];
+  w.__wgNetworkEntries.push(entry);
+  while (w.__wgNetworkEntries.length > 30) w.__wgNetworkEntries.shift();
+
+  const list = panel.querySelector(".wg-net-list");
+  const row = document.createElement("li");
+  row.className = "wg-net-row";
+  row.dataset.ok = entry.ok ? "1" : "0";
+  let path = entry.url;
+  try {
+    const u = new URL(entry.url);
+    path = u.pathname + u.search;
+  } catch {
+    /* not an absolute URL - show as given */
+  }
+  row.innerHTML =
+    '<span class="wg-net-method wg-net-method-' +
+    methodClass(entry.method) +
+    '">' +
+    esc((entry.method || "GET").toUpperCase()) +
+    '</span><span class="wg-net-path" title="' +
+    esc(entry.url) +
+    '">' +
+    esc(path) +
+    '</span><span class="wg-net-status">' +
+    esc(entry.status) +
+    (entry.ms !== undefined ? '</span><span class="wg-net-ms">' + esc(entry.ms) + "ms</span>" : "</span>");
+  row.addEventListener("click", () => {
+    const open = row.classList.contains("wg-net-open");
+    __wgQA(".wg-net-row.wg-net-open").forEach((r) => {
+      r.classList.remove("wg-net-open");
+      const d = r.nextElementSibling;
+      if (d && d.classList && d.classList.contains("wg-net-detail")) d.remove();
+    });
+    if (open) return;
+    row.classList.add("wg-net-open");
+    const detail = document.createElement("li");
+    detail.className = "wg-net-detail";
+    detail.innerHTML = renderDetail(entry);
+    const copyBtn = detail.querySelector("[data-copy]");
+    if (copyBtn) {
+      copyBtn.addEventListener("click", (ev) => {
+        ev.stopPropagation();
+        const text = toCurl(entry);
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          navigator.clipboard.writeText(text).catch(() => {});
+        }
+        copyBtn.textContent = "Copied!";
+        setTimeout(() => {
+          copyBtn.textContent = "Copy as cURL";
+        }, 1200);
+      });
+    }
+    row.after(detail);
+  });
+  list.appendChild(row);
+  while (list.children.length > 30) list.removeChild(list.firstChild);
+  const countEl = panel.querySelector(".wg-net-count");
+  if (countEl) countEl.textContent = String(w.__wgNetworkEntries.length);
+  // Always captured, only shown when explicitly turned on (ctx.showNetworkTab(); default hidden -
+  // see StubCtx's own doc comment) - the DOM/row still gets built either way, so toggling visible
+  // later shows the full history immediately, not just entries captured after that point.
+  if (w.__wgNetworkTabVisible) {
+    panel.classList.remove("wg-out");
+    void panel.offsetWidth;
+    panel.classList.add("wg-in");
+    void row.offsetWidth;
+    row.classList.add("wg-in");
+  }
+}
+
+/**
+ * Shows or hides the network-tab panel - capture keeps happening either way (addNetworkEntry
+ * always builds the DOM row; this only toggles whether the panel itself is visible). Safe to call
+ * before any entry exists yet - it just remembers the flag for addNetworkEntry to check later.
+ */
+export function setNetworkTabVisible(visible) {
+  if (typeof __wgById !== "function") return;
+  window.__wgNetworkTabVisible = !!visible;
+  const panel = __wgById("wg-network-log");
+  if (!panel) return;
+  if (visible) {
+    panel.classList.remove("wg-out");
+    panel.classList.add("wg-in");
+    __wgQA(".wg-net-row").forEach((r) => r.classList.add("wg-in"));
+  } else {
+    panel.classList.remove("wg-in");
+    panel.classList.add("wg-out");
+  }
+}
+
+/** Clears every captured entry and removes the panel - a fresh navigation/session starting over. */
+export function clearNetworkLog() {
+  if (typeof __wgById !== "function") return;
+  window.__wgNetworkEntries = [];
+  const panel = __wgById("wg-network-log");
+  if (panel) panel.remove();
+}

package/dist/runner/inpage/panel-chrome.js

@@ -60,6 +60,40 @@ export function installPanelChrome({ title, favicon, bannerPos, todoPos, envAuto
           ensureChrome();
           const stepLabel = opts.stepLabel || panel.dataset.wgStepLabel || "";
           if (stepLabel) panel.dataset.wgStepLabel = stepLabel;
+          if (opts.fastForward !== undefined) {
+            panel.dataset.wgFastForward = opts.fastForward ? "1" : "0";
+          }
+          if (opts.isApi !== undefined) {
+            panel.dataset.wgIsApi = opts.isApi ? "1" : "0";
+          }
+          const buildFfIcon = () => {
+            const span = document.createElement("span");
+            span.className = "wg-ff-icon";
+            span.setAttribute("aria-hidden", "true");
+            span.innerHTML =
+              '<svg viewBox="0 0 16 16" fill="none">' +
+              '<path class="wg-ff-chev" d="M2 3l5 5-5 5" stroke="#c9a6ff" stroke-width="1.8" ' +
+              'stroke-linecap="round" stroke-linejoin="round"/>' +
+              '<path class="wg-ff-chev" d="M8 3l5 5-5 5" stroke="#c9a6ff" stroke-width="1.8" ' +
+              'stroke-linecap="round" stroke-linejoin="round"/></svg>';
+            return span;
+          };
+          // Terminal icon: the current step is an API check (defineApiBlock) - no DOM change, no
+          // ring of its own, so without this it's an unexplained instant step with nothing visibly
+          // happening on the page at all (worse than a fast-forward block, which at least has the
+          // FF icon marking it as different).
+          const buildApiIcon = () => {
+            const span = document.createElement("span");
+            span.className = "wg-api-icon";
+            span.setAttribute("aria-hidden", "true");
+            span.innerHTML =
+              '<svg viewBox="0 0 16 16" fill="none">' +
+              '<rect x="1" y="2" width="14" height="12" rx="1.5" stroke="#7dd3fc" stroke-width="1.3"/>' +
+              '<path d="M3.5 5.5l2.5 2.5-2.5 2.5" stroke="#7dd3fc" stroke-width="1.3" ' +
+              'stroke-linecap="round" stroke-linejoin="round"/>' +
+              '<path d="M7.5 10.5h4" stroke="#7dd3fc" stroke-width="1.3" stroke-linecap="round"/></svg>';
+            return span;
+          };
           const syncMiniNext = (hidden) => {
             const miniNext = panel.querySelector("[data-wg-mini-next]");
             if (!miniNext) return;
@@ -85,10 +119,16 @@ export function installPanelChrome({ title, favicon, bannerPos, todoPos, envAuto
             const t = panel.querySelector("[data-wg-toggle]");
             const titleEl = panel.querySelector(".wg-chrome-title");
             const label = panel.dataset.wgStepLabel || stepLabel;
+            const isFf = panel.dataset.wgFastForward === "1";
+            const isApi = panel.dataset.wgIsApi === "1";
             if (titleEl) {
-              titleEl.textContent = hidden
+              const text = hidden
                 ? (label || chromeTitle || "waygraph demo")
                 : (chromeTitle || "waygraph demo");
+              titleEl.textContent = "";
+              if (hidden && isFf) titleEl.appendChild(buildFfIcon());
+              if (hidden && isApi) titleEl.appendChild(buildApiIcon());
+              titleEl.appendChild(document.createTextNode(text));
             }
             if (t) t.textContent = hidden ? "Show" : "Hide";
             syncMiniNext(hidden);

package/dist/runner/inpage/swipe-zoom.js

@@ -125,7 +125,7 @@ export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutopl
           if (window.__wgSetZoomBadge) window.__wgSetZoomBadge(1, "");
         };
         const ZOOM_ICO =
-          '<svg viewBox="0 0 24 24" fill="none" stroke="#fde68a" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
+          '<svg viewBox="0 0 24 24" fill="none" stroke="#c9a6ff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
           '<circle cx="11" cy="11" r="7"/><path d="M20 20l-3.5-3.5"/></svg>';
         window.__wgSetZoomBadge = (scale, sel) => {
           const n = Number(scale);

package/dist/runner/inpage/todos.js

@@ -51,7 +51,12 @@ export function installTodos({ title, favicon, bannerPos, todoPos, envAutoplay,
             );
           const relayoutTodoDocks = () => {
             const docks = allDocks();
-            let top = 72;
+            // Must match .wg-todo-dock/#wg-todo-dock's own CSS `top` (runner/overlay-css.js,
+            // ui/css/dock.css) - this inline style OVERRIDES that CSS the instant more than one
+            // dock exists (multi-todo stacking), so a CSS-only change here is silently underwater;
+            // real bug this was: the CSS top was bumped 72 -> 104 for banner clearance, but this
+            // hardcoded 72 kept winning at runtime and nothing actually moved.
+            let top = 104;
             for (const el of docks) {
               el.style.top = top + "px";
               top += Math.max(48, el.getBoundingClientRect().height) + 10;

package/dist/runner/main.js

@@ -8,7 +8,7 @@ import { isExpectedChainFailure, parseVideoViewport, runChainedFlows, runJsonRep
 import { runStepMode } from "./step-mode.js";
 import { connect } from "../types.js";
 import { MemPage } from "../mem-page.js";
-import { Engine, start, end, chainFlow, isFastForwardBlock, branchRoutes, runBranchRegression } from "../engine.js";
+import { Engine, start, end, chainFlow, isFastForwardBlock, branchRoutes, runBranchRegression } from "../core.js";
 
 async function main() {
   const projectDir = process.argv[2];
@@ -356,6 +356,13 @@ async function main() {
         }
       }
     } finally {
+      // A recorded run's last visible state (a fixture ring, the network panel, a todo dock update)
+      // gets cut off mid-fade otherwise - context.close() used to fire the instant the flow's own
+      // promise resolved, with zero trailing room. Real, confirmed case: defineApiBlock's network
+      // panel only became visible in the recording's final ~1-2s because of this.
+      if (process.env.WAYGRAPH_VIDEO && pageForVideo && !pageForVideo.isClosed()) {
+        await new Promise((r) => setTimeout(r, 1800));
+      }
       await context.close();
       const savedVideo =
         pageForVideo?.video() !== null && pageForVideo?.video() !== undefined
@@ -394,7 +401,7 @@ async function main() {
 
 /**
  * `waygraph run --blocks <flowName> --all-branches`: explore every path through that flow's own
- * `.branch()` tree (see src/engine/branch-regression.ts), not just whichever one the live state
+ * `.branch()` tree (see src/core/branch-regression.ts), not just whichever one the live state
  * would dispatch to. Needs a single, bare Flow reference - a multi-segment chain spec has no one
  * Flow to walk. `--shared-session` opts out of session cloning (WAYGRAPH_SHARED_SESSION=1).
  */

package/dist/runner/network-capture.d.ts

@@ -0,0 +1,9 @@
+import type { Page } from "@playwright/test";
+import type { NetworkEntry } from "./inpage/network.js";
+
+/** Records one network-tab entry (and paints it live) - see network-capture.js's own header. */
+export function recordNetworkEntry(page: Page, entry: NetworkEntry): Promise<void>;
+/** Replays page.__wgNetworkHistory into a freshly (re)installed panel after a navigation. */
+export function restoreNetworkHistory(page: Page): Promise<void>;
+/** Hooks page.on('request'/'requestfinished') to capture real page traffic into the same panel. */
+export function installNetworkCapture(page: Page): void;

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 (