waygraph 0.15.47 → 0.15.49

package/dist/pilot-overlay/fixtures.js

@@ -1,6 +1,7 @@
 // Split out of the former 950-line pilot-overlay.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { buildTodoDock, formatHighlightCaption, normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight, resolveDeviceState, resolveTodoDockUi } from "../highlights.js";
 import { ensureInstalled } from "./shell.js";
+import { verboseLog } from "../auto-session/verbose-log.js";
 /**
  * Paint (or clear) agent-authored highlight fixtures on the live page.
  * Multi-ring + optional todo strip + zoom/focus/device - the Pilot equivalent
@@ -117,8 +118,34 @@ export async function showPilotFixtures(page, fixtures) {
         })
             .catch(() => { });
     }
+    // Resolve every ring's box (and the zoom target, if any) through Playwright's own locator, not a
+    // selector string handed to the page for a raw DOM querySelector to fail silently on - >>
+    // piercing / :has-text() / :visible are Playwright-only selector syntax. "Prefer live in-page
+    // rect (honors device-shell scale)" still holds: .evaluate() runs the callback bound to the
+    // resolved element, in the page's own real JS context, same as before - only the RESOLUTION
+    // step moved from an in-page querySelector to Playwright's full selector engine. count() gate:
+    // Locator.evaluate() has no timeout option and auto-waits ~30s for a match to appear - count()
+    // never waits, so a genuinely-missing selector (a real, expected case - see `missing` below)
+    // still resolves immediately instead of hanging.
+    const ringBoxes = await Promise.all(rings.map(async (r) => {
+        const loc = page.locator(r.selector).first();
+        if ((await loc.count().catch(() => 0)) === 0)
+            return null;
+        return loc
+            .evaluate((el) => {
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0)
+                return null;
+            return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+        })
+            .catch(() => null);
+    }));
+    const resolvedZoomSelector = zoomSelector ?? "";
+    const zoomHandle = zoom > 1.001 && resolvedZoomSelector
+        ? await page.locator(resolvedZoomSelector).first().elementHandle({ timeout: 100 }).catch(() => null)
+        : null;
     return page
-        .evaluate(({ rings, todoGroups, todoPos, holdMs, zoom, zoomSelector, zoomOut, clearAll, todoUi, }) => {
+        .evaluate(({ rings, ringBoxes, todoGroups, todoPos, holdMs, zoom, zoomSelector, zoomEl, zoomOut, clearAll, todoUi, }) => {
         const w = window;
         if (w.__wgPilotFxHideTimer)
             clearTimeout(w.__wgPilotFxHideTimer);
@@ -193,17 +220,11 @@ export async function showPilotFixtures(page, fixtures) {
         // (window.__wgPaintRingAt, installed by runner/inpage/core.js's installCore - see
         // ensureInstalled) - one ring implementation, not a separate DOM-building copy here.
         rings.forEach((ring, i) => {
-            const el = document.querySelector(ring.selector);
-            if (!el) {
-                missing.push(ring.selector);
-                return;
-            }
-            const rect = el.getBoundingClientRect();
-            if (rect.width === 0 && rect.height === 0) {
+            const box = ringBoxes[i];
+            if (!box) {
                 missing.push(ring.selector);
                 return;
             }
-            const box = { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
             const ringId = `wg-fx-ring-${i}`;
             const labelId = `wg-fx-ring-${i}-label`;
             if (window.__wgPaintRingAt) {
@@ -294,7 +315,7 @@ export async function showPilotFixtures(page, fixtures) {
             }
         }
         if (zoom > 1.001 && zoomSelector) {
-            const target = document.querySelector(zoomSelector);
+            const target = zoomEl;
             if (target) {
                 target.scrollIntoView({
                     block: "center",
@@ -322,14 +343,25 @@ export async function showPilotFixtures(page, fixtures) {
         return { painted, missing };
     }, {
         rings,
+        ringBoxes,
         todoGroups,
         todoPos,
         holdMs,
         zoom,
         zoomSelector: zoomSelector ?? "",
+        zoomEl: zoomHandle,
         zoomOut,
         clearAll: fixtures.clear === true,
         todoUi,
+    })
+        .then((result) => {
+        // Debuggability: a demo/pilot run is a sequential list of steps - when a ring silently
+        // doesn't render, "where in the flow" and "which selector" are exactly what's needed to fix
+        // it, not a quiet no-op. See rings.js/slides.js/teardown.js for the same fix, same reason.
+        for (const sel of result.missing) {
+            verboseLog("pilot", `ring not painted - selector matched nothing (or a zero-size element): ${sel}`);
+        }
+        return result;
     })
         .catch(() => ({ painted: 0, missing: rings.map((r) => r.selector) }));
 }

package/dist/pilot-overlay/shell.js

@@ -1,6 +1,7 @@
 // Split out of the former 950-line pilot-overlay.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { SURFACE } from "../ui/tokens.js";
 import { ensureShadowRoot, installShadowRoot } from "../ui/shadow.js";
+import { verboseLog } from "../auto-session/verbose-log.js";
 // Real, direct user request: this overlay's own colors were an improvised
 // purple/white scheme (#a78bfa / #1a1033) that didn't match anything else -
 // "our design here seems like barely shares with the ui on the stepper
@@ -216,8 +217,26 @@ export async function showPilotActivity(page, text) {
  */
 export async function showPilotVision(page, selector, label, tone = "auto") {
     await ensureInstalled(page);
+    // Resolved through 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 right now" check.
+    const visionLoc = page.locator(selector).first();
+    const box = (await visionLoc.count().catch(() => 0)) > 0
+        ? await visionLoc
+            .evaluate((el) => {
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0)
+                return null;
+            return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+        })
+            .catch(() => null)
+        : null;
+    if (!box) {
+        verboseLog("pilot", `vision ring not painted - selector matched nothing (or a zero-size element): ${selector}`);
+    }
     await page
-        .evaluate(({ selector, label, tone }) => {
+        .evaluate(({ box, label, tone }) => {
         const ring = __wgById("wg-ring");
         const tag = __wgById("wg-ring-label");
         if (!ring || !tag)
@@ -225,18 +244,12 @@ export async function showPilotVision(page, selector, label, tone = "auto") {
         const w = window;
         if (w.__wgVisionHideTimer)
             clearTimeout(w.__wgVisionHideTimer);
-        const el = document.querySelector(selector);
-        if (!el) {
-            ring.style.opacity = "0";
-            tag.style.opacity = "0";
-            return;
-        }
-        const rect = el.getBoundingClientRect();
-        if (rect.width === 0 && rect.height === 0) {
+        if (!box) {
             ring.style.opacity = "0";
             tag.style.opacity = "0";
             return;
         }
+        const rect = box;
         ring.dataset.tone = tone;
         ring.dataset.size = "md";
         tag.dataset.tone = tone;
@@ -262,6 +275,6 @@ export async function showPilotVision(page, selector, label, tone = "auto") {
             ring.style.opacity = "0";
             tag.style.opacity = "0";
         }, 4_000);
-    }, { selector, label, tone })
+    }, { box, label, tone })
         .catch(() => { });
 }

package/dist/runner/banner-log.js

@@ -9,6 +9,7 @@ export function bannerUiFromPhase(phase) {
   if (phase && phase.bannerUi) {
     if (phase.bannerUi.collision !== undefined) ui.collision = !!phase.bannerUi.collision;
     if (phase.bannerUi.hidden !== undefined) ui.hidden = !!phase.bannerUi.hidden;
+    if (phase.bannerUi.captionFadeMs !== undefined) ui.captionFadeMs = Number(phase.bannerUi.captionFadeMs);
   }
   return ui;
 }

package/dist/runner/device-stage.js

@@ -242,6 +242,21 @@ export async function applyDeviceToPage(page, device, sync) {
   } catch {
     from = null;
   }
+  // Non-headless (no --video) used to literally resize the real OS browser window/viewport to
+  // each device's pixel size - a real, confirmed complaint: it didn't look like the same animated
+  // device-shell bezel the --video path already has, just a plain resize. Both now use the exact
+  // same applyVideoDeviceStage bezel technique - the "stage" (the fixed outer viewport the shell is
+  // centered within) is the recordVideo canvas size when recording, or the window's own size at
+  // the FIRST device switch when not (captured once, persisted on the page - the window itself is
+  // only really resized that one time, to establish a stable stage; every device switch after that
+  // paints the animated shell inside it instead of resizing the window again).
+  let establishingHeadedStage = false;
+  if (!videoStage && !page.__wgHeadedStage) {
+    page.__wgHeadedStage =
+      from && from.width > 0 && from.height > 0 ? { width: from.width, height: from.height } : { width: 1280, height: 720 };
+    establishingHeadedStage = true;
+  }
+  const stage = videoStage || page.__wgHeadedStage;
   const announce = mode === "set" || mode === "clear";
   const toDesktop =
     mode === "clear" || (d.preset === "desktop" && !d.touchMode);
@@ -275,13 +290,18 @@ export async function applyDeviceToPage(page, device, sync) {
   page.__wgDeviceOrient = nextOrient;
   page.__wgDevicePreset = toDesktop ? "desktop" : d.preset || "";
 
-  if (videoStage) {
-    // Lock Playwright viewport to the recordVideo size so frames fill the
-    // .webm; center the device shell inside (OS window centering alone does not).
-    // Do NOT fitWindow to the device size - that shrinks the viewport below the
-    // recordVideo canvas and Playwright pads the .webm with grey (top-left bias).
+  if (stage) {
+    // Lock the Playwright viewport to the stage size so frames/window fill it; center the device
+    // shell inside (OS window centering alone does not). Do NOT fitWindow to the device size -
+    // that shrinks the viewport below the stage and (when recording) pads the .webm with grey
+    // (top-left bias). Headed-without-video reuses this exact technique (see `stage`'s own
+    // comment above) - the real OS window is only ever resized once, right here, to establish the
+    // stage itself; every device switch after that paints the animated shell inside it instead.
+    if (!videoStage && establishingHeadedStage) {
+      await fitWindowToDeviceViewport(page, stage, { maximize: false }).catch(() => {});
+    }
     try {
-      await realSet(videoStage);
+      await realSet(stage);
     } catch {
       /* ignore */
     }
@@ -290,22 +310,22 @@ export async function applyDeviceToPage(page, device, sync) {
       // Zoom already cleared above. Full-bleed desktop shell (no matte frame).
       // Shutter-out: soft rounded -> radius 0, then flat edge-to-edge.
       const desk = {
-        width: videoStage.width,
-        height: videoStage.height,
+        width: stage.width,
+        height: stage.height,
       };
       page.__wgDeviceShell = { ...desk };
-      await applyVideoDeviceStage(page, desk, videoStage, {
+      await applyVideoDeviceStage(page, desk, stage, {
         clear: false,
         shutterOut: true,
         desktopFlat: true,
       });
       try {
-        await realSet(videoStage);
+        await realSet(stage);
       } catch {
         /* ignore */
       }
     } else {
-      // Lerp shell size when switching mobile <-> tablet mid-video.
+      // Lerp shell size when switching mobile <-> tablet mid-run.
       const firstDevice = !page.__wgDeviceShell;
       if (
         announce &&
@@ -322,22 +342,22 @@ export async function applyDeviceToPage(page, device, sync) {
             width: Math.round(shellFrom.width + (target.width - shellFrom.width) * e),
             height: Math.round(shellFrom.height + (target.height - shellFrom.height) * e),
           };
-          await applyVideoDeviceStage(page, mid, videoStage, {
+          await applyVideoDeviceStage(page, mid, stage, {
             clear: false,
             enterIn: i === 1 && firstDevice,
           });
           if (i < steps) await new Promise((r) => setTimeout(r, stepMs));
         }
       } else {
-        await applyVideoDeviceStage(page, target, videoStage, {
+        await applyVideoDeviceStage(page, target, stage, {
           clear: false,
           enterIn: firstDevice || announce,
         });
       }
       page.__wgDeviceShell = { ...target };
-      // Re-assert stage size after any prior non-video fitWindow.
+      // Re-assert stage size after any prior fitWindow.
       try {
-        await realSet(videoStage);
+        await realSet(stage);
       } catch {
         /* ignore */
       }

package/dist/runner/inpage/banner.d.ts

@@ -8,6 +8,14 @@ export function installBanner(args: {
   todoPos?: string | undefined;
   envAutoplay?: boolean | undefined;
   todoDockUi?: unknown;
-  bannerUi?: { hidden?: boolean | undefined; collision?: boolean | undefined; pos?: string | undefined } | undefined;
+  bannerUi?:
+    | {
+        hidden?: boolean | undefined;
+        collision?: boolean | undefined;
+        pos?: string | undefined;
+        /** Title-change fade duration in ms (default 220); 0 = instant swap, no fade. */
+        captionFadeMs?: number | undefined;
+      }
+    | undefined;
   tag?: string | undefined;
 }): void;

package/dist/runner/inpage/banner.js

@@ -43,14 +43,31 @@ export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay,
             __wgAdd(banner);
           } else {
             // Fixture / episode title changes every step - update in place
-            // (banner is created once; do not leave the first step's text stuck).
+            // (banner is created once; do not leave the first step's text stuck). Fades out/in
+            // instead of an instant swap, so a title change reads as a deliberate beat, not a
+            // flicker - opt-out (or re-tune) via bannerUi.captionFadeMs, 0 = instant.
             let text = banner.querySelector(".wg-banner-text");
             if (!text) {
               text = document.createElement("span");
               text.className = "wg-banner-text";
               banner.appendChild(text);
             }
-            text.textContent = title;
+            if (text.textContent !== title) {
+              const fadeMs =
+                bannerUi && Number.isFinite(Number(bannerUi.captionFadeMs))
+                  ? Math.max(0, Number(bannerUi.captionFadeMs))
+                  : 220;
+              if (fadeMs <= 0 || !text.textContent) {
+                text.textContent = title;
+              } else {
+                text.style.transition = "opacity " + fadeMs + "ms ease";
+                text.style.opacity = "0";
+                setTimeout(() => {
+                  text.textContent = title;
+                  text.style.opacity = "1";
+                }, fadeMs);
+              }
+            }
           }
         }
         // Authored banner UX (StubCtx.titlePos / bannerUi): applied every step, wins over click/env.
@@ -107,6 +124,14 @@ export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay,
           if (b.dataset.home) b.dataset.pos = b.dataset.home;
           delete b.dataset.moved;
         };
+        // Dim the banner while a ring caption is the focus - same "auto opacity" effect the todo
+        // dock already has via __wgTodosSetBehind, extended to the banner so both floating chrome
+        // pieces step back the same way instead of only one of them fading.
+        window.__wgBannerSetBehind = (on) => {
+          const b = __wgById("wg-banner");
+          if (!b) return;
+          b.classList.toggle("wg-banner-behind", !!on);
+        };
         // Tab title/favicon: a real navigation resets document.title and any
         // <link rel="icon"> the new document brings, so re-check (not
         // re-append) on every call instead of a one-time flag.

package/dist/runner/inpage/caption.d.ts

@@ -0,0 +1,3 @@
+/** In-page installer (page.evaluate target) - see caption.js's own header. */
+export function showCaption(text: string): void;
+export function hideCaption(): void;

package/dist/runner/inpage/caption.js

@@ -0,0 +1,23 @@
+// In-page installer (page.evaluate target) - must stay self-contained, no module-scope closure.
+// Bottom subtitle-bar caption, ported from zsign's help-center-clip-engine (see ui/css/caption.css's
+// own header) - same visual fixture, narration-timeline/TTS sync not ported yet.
+export function showCaption(text) {
+  let bar = __wgById("wg-caption-bar");
+  if (!bar) {
+    bar = document.createElement("div");
+    bar.id = "wg-caption-bar";
+    bar.setAttribute("data-wg-ui", "1");
+    const span = document.createElement("span");
+    span.className = "wg-caption-text";
+    bar.appendChild(span);
+    __wgAdd(bar);
+  }
+  const span = bar.querySelector(".wg-caption-text");
+  span.textContent = text;
+  bar.classList.add("wg-in");
+}
+
+export function hideCaption() {
+  const bar = __wgById("wg-caption-bar");
+  if (bar) bar.classList.remove("wg-in");
+}

package/dist/runner/inpage/core.js

@@ -78,7 +78,25 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           const lh = ringLabel.offsetHeight;
           let labelLeft = left;
           let labelTop = top + height + 8;
-          if (labelTop + lh > vh - margin) labelTop = top - lh - 8;
+          const aboveTop = top - lh - 8;
+          if (labelTop + lh > vh - margin) {
+            labelTop = aboveTop;
+          } else {
+            // Below the ringed box is often the NEXT form field in a tightly stacked list (e.g.
+            // saucedemo's checkout "First Name" / "Last Name" / "Zip" inputs) - a fixed +8px gap
+            // has no idea that's there and the label just sits on top of it. Sample a few points
+            // under the would-be label and flip above if any land on real page content (not our
+            // own ring/label elements, which are the only things expected there otherwise).
+            const probe = (x, y) => {
+              const el = document.elementFromPoint(x, y);
+              return el && el.id !== ringId && el.id !== labelId && !(el.closest && el.closest("#wg-root"));
+            };
+            const hitsPageContent =
+              probe(labelLeft + 2, labelTop + 2) ||
+              probe(labelLeft + lw - 2, labelTop + 2) ||
+              probe(labelLeft + 2, labelTop + lh - 2);
+            if (hitsPageContent && aboveTop >= margin) labelTop = aboveTop;
+          }
           if (labelTop < margin) labelTop = margin;
           if (labelLeft + lw > vw - margin) labelLeft = Math.max(margin, vw - margin - lw);
           if (labelLeft < margin) labelLeft = margin;
@@ -136,6 +154,7 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           if (!box) return;
           window.__wgPaintRingAt("wg-ring", "wg-ring-label", box, label, tone, style);
           if (window.__wgTodosSetBehind) window.__wgTodosSetBehind(true);
+          if (window.__wgBannerSetBehind) window.__wgBannerSetBehind(true);
           if (window.__wgTodosAvoidRingCollision) window.__wgTodosAvoidRingCollision(box);
           if (window.__wgBannerAvoidRing) window.__wgBannerAvoidRing(box);
         };
@@ -188,22 +207,25 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
             break;
           }
         };
-        /** Live-follow a selector with rAF (accurate under device shell scale). */
+        /** Live-follow a resolved element with rAF (accurate under device shell scale). */
         window.__wgStopRingFollow = () => {
           if (window.__wgRingFollowRaf) {
             cancelAnimationFrame(window.__wgRingFollowRaf);
             window.__wgRingFollowRaf = 0;
           }
-          window.__wgRingFollowSel = "";
+          window.__wgRingFollowEl = null;
         };
-        window.__wgFollowRing = (sel, label, tone, style, focus) => {
+        // `el` is a real DOM element (a Playwright ElementHandle unwrapped by evaluate() - see
+        // rings.js's showRing), not a selector string - >> piercing / :has-text() are Playwright's
+        // own selector-engine syntax, which document.querySelector has no way to understand, so
+        // resolution happens once on the Node side via page.locator(), before this ever runs.
+        window.__wgFollowRing = (el, label, tone, style, focus) => {
           window.__wgStopRingFollow();
-          if (!sel) return;
-          window.__wgRingFollowSel = sel;
+          if (!el) return;
+          window.__wgRingFollowEl = el;
           const tick = () => {
-            if (window.__wgRingFollowSel !== sel) return;
-            const el = document.querySelector(sel);
-            if (!el) {
+            if (window.__wgRingFollowEl !== el) return;
+            if (!el.isConnected) {
               window.__wgRingFollowRaf = requestAnimationFrame(tick);
               return;
             }
@@ -244,6 +266,7 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
           if (ringLabel) ringLabel.style.opacity = "0";
           if (window.__wgClearFocus) window.__wgClearFocus();
           if (window.__wgTodosSetBehind) window.__wgTodosSetBehind(false);
+          if (window.__wgBannerSetBehind) window.__wgBannerSetBehind(false);
           if (window.__wgBannerRestore) window.__wgBannerRestore();
           window.__wgTodoCollisionLocked = false;
           __wgQA(".wg-todo-dock[data-tucked], #wg-todo-dock[data-tucked]").forEach((el) => {

package/dist/runner/inpage/network.d.ts

@@ -0,0 +1,15 @@
+/** In-page installer (page.evaluate target) - see network.js's own header. */
+export interface NetworkEntry {
+  method: string;
+  url: string;
+  status: number;
+  ok: boolean;
+  ms?: number | undefined;
+  reqHeaders?: Record<string, string> | undefined;
+  resHeaders?: Record<string, string> | undefined;
+  reqBody?: string | undefined;
+  resBody?: string | undefined;
+}
+export function addNetworkEntry(entry: NetworkEntry): void;
+export function setNetworkTabVisible(visible: boolean): void;
+export function clearNetworkLog(): void;