waygraph 0.15.47 → 0.15.49

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,5 +1,5 @@
 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";

package/dist/session/auto-explore-run.js

@@ -3,10 +3,10 @@ import { ensureShadowRoot } from "../ui/shadow.js";
 import { stdin as input, stdout as output } from "node:process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { Engine, start, end, locate } from "../engine.js";
+import { Engine, start, end, locate } from "../core.js";
 import { MemPage } from "../mem-page.js";
 import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
-import { installDemoChrome, instrumentInteractionHighlighting } from "../step-overlay.js";
+import { installDemoChrome, instrumentInteractionHighlighting } from "./step-overlay.js";
 export function resolveBaseUrl(projectDir) {
     const pkgPath = join(projectDir, "package.json");
     if (existsSync(pkgPath)) {
@@ -355,6 +355,37 @@ async function headfulPick(page, menu, library, mem, waitPick) {
             memIdx++;
         }
     }
+    // Pre-resolve every candidate's hover-preview box THROUGH Playwright's own locator (>>
+    // piercing / :has-text() / :visible support), once, here on the Node side - not a raw selector
+    // string handed to the page for a per-mouseenter document.querySelector to fail silently on
+    // (same class of bug as rings.js's showRing; see its own comment for the full story). A
+    // mouseenter handler can't itself await a Node-side locator without visible hover lag, so the
+    // box is embedded as a data attribute instead and the in-page handler just reads it.
+    const hlSelectors = new Set();
+    for (const section of menu.sections) {
+        for (const c of section.edges) {
+            const entry = library.get(c.block);
+            const navClick = entry?.block?.__waygraphNavClick;
+            const hl = c.instanceOption?.highlight ?? (typeof navClick === "string" ? navClick : undefined);
+            if (hl)
+                hlSelectors.add(hl);
+        }
+    }
+    const hlBoxes = new Map();
+    await Promise.all([...hlSelectors].map(async (sel) => {
+        const loc = page.locator(sel).first();
+        const box = (await loc.count().catch(() => 0)) > 0
+            ? await loc
+                .evaluate((el) => {
+                const r = el.getBoundingClientRect();
+                if (r.width < 1 && r.height < 1)
+                    return null;
+                return { x: r.x, y: r.y, width: r.width, height: r.height };
+            })
+                .catch(() => null)
+            : null;
+        hlBoxes.set(sel, box);
+    }));
     html += `<div class="wg-actions">`;
     let idx = 0;
     if (menu.sections.length === 0) {
@@ -366,7 +397,8 @@ async function headfulPick(page, menu, library, mem, waitPick) {
             const entry = library.get(c.block);
             const navClick = entry?.block?.__waygraphNavClick;
             const hl = c.instanceOption?.highlight ?? (typeof navClick === "string" ? navClick : undefined);
-            const hlAttr = hl ? ` data-hl="${esc(hl)}"` : "";
+            const hlBox = hl ? hlBoxes.get(hl) : null;
+            const hlAttr = hlBox ? ` data-hl-box='${esc(JSON.stringify(hlBox))}'` : "";
             if (c.label) {
                 html += `<button class="wg-act" data-idx="${idx}"${hlAttr}>${esc(c.label)}</button>`;
             }
@@ -476,14 +508,19 @@ async function headfulPick(page, menu, library, mem, waitPick) {
           window.__wgAutoPick?.(idx);
         });
         btn.addEventListener("mouseenter", () => {
-          const sel = btn.getAttribute("data-hl");
-          if (!sel) return;
-          const el = document.querySelector(sel);
-          if (!el || typeof window.__wgPositionRing !== "function") return;
-          const r = el.getBoundingClientRect();
-          if (r.width < 1 && r.height < 1) return;
+          // Pre-resolved on the Node side via Playwright's own locator (>> piercing / :has-text()
+          // support) when this menu was built - see headfulPick's own comment for why a
+          // mouseenter handler can't itself round-trip to a Node-side locator per hover.
+          const raw = btn.getAttribute("data-hl-box");
+          if (!raw || typeof window.__wgPositionRing !== "function") return;
+          let box;
+          try {
+            box = JSON.parse(raw);
+          } catch {
+            return;
+          }
           window.__wgPositionRing(
-            { x: r.x, y: r.y, width: r.width, height: r.height },
+            box,
             btn.textContent?.trim()?.slice(0, 80) || "target",
             "auto",
           );

package/dist/{step-overlay.d.ts → session/step-overlay.d.ts}

@@ -1,5 +1,5 @@
 import type { Page } from "@playwright/test";
-import type { MemPage } from "./mem-page.js";
+import type { MemPage } from "../mem-page.js";
 export declare function installDemoChrome(page: Page, title?: string, options?: {
     banner?: boolean;
 }): Promise<void>;

package/dist/{step-overlay.js → session/step-overlay.js}

@@ -1,4 +1,4 @@
-import { ensureShadowRoot } from "./ui/shadow.js";
+import { ensureShadowRoot } from "../ui/shadow.js";
 const 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>");
 export async function installDemoChrome(page, title = "waygraph auto", options = {}) {

package/dist/trait.d.ts

@@ -1,5 +1,6 @@
 import type { Page } from "@playwright/test";
 import type { MemPage } from "./mem-page.js";
+import "urlpattern-polyfill";
 /**
  * A named, independently-reportable check. `check` never runs before `resolve` has
  * already decided the Checkpoint, and it can only confirm or fail loud - it has no

package/dist/trait.js

@@ -1,3 +1,12 @@
+// URLPattern is only a Node global from v23.8+ (and even then, Node's own, not a browser's) -
+// CI's Node 20/22 matrix has no global at all. Side-effect import only: the polyfill package sets
+// globalThis.URLPattern itself, but only when one doesn't already exist - so below Node 23.8 this
+// becomes THE global, and from 23.8 up it's a no-op and the native one stays. Playwright's own
+// waitForURL(pattern) checks `pattern instanceof globalThis.URLPattern` internally, so the instance
+// constructed below must always come from whatever ends up on globalThis, not this import
+// directly - a named `import { URLPattern }` gives a fixed class that's a different constructor
+// than the native global on newer Node, and `instanceof` would then fail on those versions.
+import "urlpattern-polyfill";
 /**
  * Common, generic Trait factories - reusable across any Block, not one-off
  * `{ name, check }` objects written inline per Block. Reach for one of these
@@ -36,6 +45,12 @@ export function urlMatches(pattern) {
             // `verify()` case this was originally written for - just via the same
             // mechanism every other Trait already uses instead of its own
             // hardcoded, wrong-context value.
+            // Cast, not a bare `urlPattern` reference: @types/node and the polyfill both declare an
+            // ambient global `URLPattern` (`skipLibCheck` hides the conflict between them instead of
+            // erroring), and they resolve to two DIFFERENT types depending on where in the program the
+            // name is looked up - so the very same runtime value that satisfies Playwright's actual
+            // (structural, .test()-based) check at runtime fails typechecking as "not assignable" against
+            // whichever of the two ambient declarations Playwright's own .d.ts happens to see.
             await page.waitForURL(urlPattern);
             return true;
         },

package/dist/traverse/run.js

@@ -4,7 +4,7 @@
  */
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { Engine, start, end, locate } from "../engine.js";
+import { Engine, start, end, locate } from "../core.js";
 import { MemPage } from "../mem-page.js";
 import { buildExploreContext, buildExploreMenu, } from "../session/auto-explore.js";
 import { defaultMemValueForKey } from "../session/auto-explore-run.js";

package/dist/ui/components/ring.js

@@ -1,6 +1,8 @@
 import { TONES } from "../tokens.js";
-/** Prefix icon for gray (auto) labels. */
-const ROBOT = 'content:"\\1F916\\00a0";';
+/** Prefix icon for gray (auto) labels - a real inline SVG (terminal chevron), not an emoji. */
+const ROBOT = 'content:"";display:inline-block;width:12px;height:12px;margin-right:5px;vertical-align:-1px;' +
+    "background-repeat:no-repeat;background-size:contain;" +
+    "background-image:url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none'%3E%3Cpath d='M2.5 3.5l5 4.5-5 4.5M8.5 12.5h5' stroke='white' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E\");";
 const toneNames = Object.keys(TONES);
 /** Tone rules for `sel[data-tone=x]{...}` from the token table. */
 function toneRules(sel, decl, only) {

package/dist/ui/overlay.css

@@ -93,8 +93,14 @@
 .wg-ring-el-label[data-tone=danger]  { --wg-tone-bg: var(--wg-tone-danger-bg);  --wg-tone-fg: var(--wg-tone-danger-fg); }
 .wg-ring-el-label[data-tone=success] { --wg-tone-bg: var(--wg-tone-success-bg); --wg-tone-fg: var(--wg-tone-success-fg); }
 .wg-ring-el-label[data-tone=orange]  { --wg-tone-bg: var(--wg-tone-orange-bg);  --wg-tone-fg: var(--wg-tone-orange-fg); }
-/* Gray (auto) = a real Playwright-driven instruction - mark it, a human/AI watching can't "see" DOM state otherwise. */
-.wg-ring-el-label[data-tone=auto]::before { content: "\1F916\00a0"; }
+/* Gray (auto) = a real Playwright-driven instruction - mark it, a human/AI watching can't "see" DOM
+   state otherwise. A real inline SVG icon (small terminal chevron), not an emoji - emoji rendering
+   is font/OS-dependent and reads as an unpolished placeholder next to the rest of this design. */
+.wg-ring-el-label[data-tone=auto]::before {
+  content: ""; display: inline-block; width: 12px; height: 12px; margin-right: 5px;
+  vertical-align: -1px; background-repeat: no-repeat; background-size: contain;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none'%3E%3Cpath d='M2.5 3.5l5 4.5-5 4.5M8.5 12.5h5' stroke='white' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+}
 .wg-ring-el-label[data-size=sm] { font-size: 10px; line-height: 1.25; padding: 4px 7px; border-radius: 5px; }
 .wg-ring-el-label[data-size=lg] { font-size: 16px; line-height: 1.35; padding: 8px 14px; border-radius: 9px; max-width: min(480px, 85vw); }
 .wg-ring-el-label[data-weight=bold] { font-weight: 800; }
@@ -136,6 +142,9 @@
 #wg-banner[data-pos=left]   { left: 14px; right: auto; transform: none; }
 #wg-banner[data-pos=center] { left: 50%; right: auto; transform: translateX(-50%); }
 #wg-banner[data-pos=right]  { right: 14px; left: auto; transform: none; }
+/* Same "auto opacity" step-back the todo dock already has (.wg-todo-behind) while a ring caption
+   is the current focus - added via __wgBannerSetBehind, not just the collision-driven move. */
+#wg-banner.wg-banner-behind { opacity: .42; }
 #wg-banner .wg-banner-tag {
   display: block; font-size: 10px; font-weight: 700; color: var(--wg-accent-soft);
   letter-spacing: .05em; text-transform: uppercase; margin-bottom: 2px;
@@ -151,7 +160,7 @@
  * duplicate of this file's own rules, is consolidated.
  */
 #wg-pilot-fx-todos {
-  position: fixed; z-index: var(--wg-z-fx); top: 72px; max-width: 280px; max-height: calc(100vh - 100px);
+  position: fixed; z-index: var(--wg-z-fx); top: 104px; max-width: 280px; max-height: calc(100vh - 132px);
   overflow: auto; font: 12px/1.4 ui-sans-serif, system-ui, sans-serif; color: #fff;
   background: var(--wg-surface); border-radius: var(--wg-radius-md); padding: 10px 12px;
   box-shadow: var(--wg-shadow-dock); pointer-events: auto; transition: opacity .25s ease;
@@ -181,3 +190,27 @@
   background: var(--wg-surface); color: #fff; border-radius: var(--wg-radius-sm);
   box-shadow: 0 2px 8px rgba(0,0,0,.25);
 }
+
+
+/*
+ * Bottom subtitle caption (#wg-caption-bar) - a white rounded card, not a full-width dark scrim
+ * (matches the rest of the overlay's light "toast" surfaces - banner/panel are the dark violet
+ * chrome, this narrates the PAGE itself so it reads as a caption card, not more chrome).
+ */
+#wg-caption-bar {
+  position: fixed; z-index: var(--wg-z-focus); left: 0; right: 0; bottom: 0;
+  /* Bottom padding clears the collapsed step-pill (#wg-panel, bottom:12px, ~40px tall,
+     z-index:2147483647 - always on top) - without it the pill sat right over the caption card,
+     both centered at the bottom of the viewport (see #wg-typing-badge's own bottom:88px, same
+     reason). */
+  padding: 0 6% 64px; display: flex; justify-content: center;
+  pointer-events: none; opacity: 0; transform: translateY(6px);
+  transition: opacity .3s ease, transform .3s ease;
+}
+#wg-caption-bar.wg-in { opacity: 1; transform: translateY(0); }
+#wg-caption-bar .wg-caption-text {
+  font: 500 15px/1.4 var(--wg-font); color: #1c1917; text-align: center;
+  max-width: 82%; text-wrap: balance;
+  background: #fff; border-radius: var(--wg-radius-lg);
+  padding: 10px 18px; box-shadow: var(--wg-shadow-banner);
+}

package/examples/saucedemo/.waygraph-auto/00d147d1.log

@@ -0,0 +1,21 @@
+[18:43:31.014] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[18:43:31.014] waygraph pilot: stub.before ctx.todos n=6 index=0
+[18:43:31.015] waygraph pilot: stub.before ctx.device(mobile)
+[18:43:31.015] waygraph pilot: stub.before ctx.zoom(1.35)
+[18:43:31.015] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[18:43:31.780] waygraph pilot: stub.after ctx.todos n=6 index=1
+[18:43:32.878] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[18:43:33.035] waygraph pilot: stub.after ctx.todos n=6 index=2
+[18:43:34.170] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[18:43:34.393] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[18:43:34.393] waygraph pilot: stub.after ctx.todos n=6 index=3
+[18:43:34.393] waygraph pilot: stub.after ctx.device(mobile)
+[18:43:34.393] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[18:43:37.076] waygraph pilot: stub.before ctx.title("Open cart · landscape")
+[18:43:37.076] waygraph pilot: stub.before ctx.todos n=6 index=5
+[18:43:37.076] waygraph pilot: stub.before ctx.device(mobile)
+[18:43:37.076] waygraph pilot: stub.before ctx.zoom(1.4)
+[18:43:37.076] waygraph pilot: stub.before ring .shopping_cart_link tone=planned label="Cart"
+[18:43:37.510] waygraph pilot: stub.after ctx.title("Your cart · desktop")
+[18:43:37.511] waygraph pilot: stub.after ring .cart_item tone=success label="Cart items"
+[18:43:37.589] waygraph pilot: ring not painted - selector matched nothing (or a zero-size element): .cart_item

package/examples/saucedemo/.waygraph-auto/0402cfcf.log

@@ -0,0 +1,6 @@
+[14:01:13.381] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[14:01:13.382] waygraph pilot: stub.before ctx.todos n=6 index=0
+[14:01:13.382] waygraph pilot: stub.before ctx.device(mobile)
+[14:01:13.382] waygraph pilot: stub.before ctx.zoom(1.35)
+[14:01:13.382] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[14:01:14.418] waygraph pilot: stub.after ctx.todos n=6 index=1

package/examples/saucedemo/.waygraph-auto/062b581f.log

@@ -0,0 +1,20 @@
+[15:11:57.159] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[15:11:57.159] waygraph pilot: stub.before ctx.todos n=6 index=0
+[15:11:57.160] waygraph pilot: stub.before ctx.device(mobile)
+[15:11:57.160] waygraph pilot: stub.before ctx.zoom(1.35)
+[15:11:57.160] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[15:11:58.387] waygraph pilot: stub.after ctx.todos n=6 index=1
+[15:11:59.771] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[15:11:59.868] waygraph pilot: stub.after ctx.todos n=6 index=2
+[15:12:01.498] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[15:12:01.761] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[15:12:01.763] waygraph pilot: stub.after ctx.todos n=6 index=3
+[15:12:01.763] waygraph pilot: stub.after ctx.device(mobile)
+[15:12:01.763] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[15:12:05.024] waygraph pilot: stub.before ctx.title("Open cart · landscape")
+[15:12:05.024] waygraph pilot: stub.before ctx.todos n=6 index=5
+[15:12:05.024] waygraph pilot: stub.before ctx.device(mobile)
+[15:12:05.024] waygraph pilot: stub.before ctx.zoom(1.4)
+[15:12:05.024] waygraph pilot: stub.before ring .shopping_cart_link tone=planned label="Cart"
+[15:12:05.374] waygraph pilot: stub.after ctx.title("Your cart · desktop")
+[15:12:05.374] waygraph pilot: stub.after ring .cart_item tone=success label="Cart items"

package/examples/saucedemo/.waygraph-auto/0681582b.log

@@ -0,0 +1,6 @@
+[10:25:35.405] waygraph pilot: highlight ctx.todos n=3 index=0
+[10:25:35.406] waygraph pilot: highlight ring #user-name tone=planned label="Username"
+[10:25:35.406] waygraph pilot: highlight ring #password tone=info label="Password"
+[10:25:40.761] waygraph pilot: highlight ring #no-such-element-waygraph tone=danger label="Gone"
+[10:25:40.795] waygraph pilot: ring not painted - selector matched nothing (or a zero-size element): #no-such-element-waygraph
+[10:25:44.204] waygraph pilot: highlight ring #login-button tone=success label="Login"

package/examples/saucedemo/.waygraph-auto/07f3e964.log

@@ -0,0 +1,6 @@
+[18:22:04.004] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[18:22:04.004] waygraph pilot: stub.before ctx.todos n=6 index=0
+[18:22:04.005] waygraph pilot: stub.before ctx.device(mobile)
+[18:22:04.005] waygraph pilot: stub.before ctx.zoom(1.35)
+[18:22:04.005] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[18:22:05.633] waygraph pilot: stub.after ctx.todos n=6 index=1