waygraph 0.15.53 → 0.16.0

package/dist/demo/overlay/overlay.d.ts

@@ -0,0 +1,10 @@
+import type { WgPage } from "../types.js";
+/**
+ * `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 declare function installOverlay(page: WgPage, title?: any, ui?: any, caption?: any, networkTabVisible?: any): Promise<void>;

package/dist/demo/overlay/overlay.js

@@ -0,0 +1,89 @@
+import { HOST_CSS, RUNNER_EXTRA_CSS, WAYGRAPH_FAVICON } from "./overlay-css.js";
+import { ensureShadowRoot } from "./ui/shadow.js";
+import { resolveTodoDockUi } from "../narration/todo-dock.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-chip.js";
+import { applyVideoDeviceStage } from "./device-stage.js";
+import { installNetworkCapture, restoreNetworkHistory } from "./network-capture.js";
+import { setNetworkTabVisible } from "./inpage/network.js";
+import { envFlag, envString } from "../../engine/env.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+/**
+ * `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(ignorePageGone);
+    // 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(ignorePageGone);
+    }
+    // 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(ignorePageGone);
+    await page.addStyleTag({ content: HOST_CSS }).catch(ignorePageGone);
+    // Default top-left; override with WAYGRAPH_TITLE_POS=left|center|right.
+    // Click cycles left -> center -> right (persisted in localStorage so a
+    // navigation that rebuilds the banner keeps the human's last pick).
+    const envPos = (envString("WAYGRAPH_TITLE_POS") || "left").toLowerCase();
+    const bannerPos = envPos === "center" || envPos === "right" ? envPos : "left";
+    const envTodoPos = (envString("WAYGRAPH_TODO_POS") || "left").toLowerCase();
+    const todoPos = envTodoPos === "right" ? "right" : "left";
+    const envAutoplay = envFlag("WAYGRAPH_AUTOPLAY");
+    const todoDockUi = resolveTodoDockUi();
+    const args = { title, favicon: WAYGRAPH_FAVICON, bannerPos, todoPos, envAutoplay, todoDockUi, bannerUi: ui || null };
+    await page.evaluate(installCore, args).catch(ignorePageGone);
+    await page.evaluate(installSwipeZoom, args).catch(ignorePageGone);
+    await page.evaluate(installBanner, args).catch(ignorePageGone);
+    await page.evaluate(installStamp, args).catch(ignorePageGone);
+    await page.evaluate(installPanelChrome, args).catch(ignorePageGone);
+    await page.evaluate(installTodos, args).catch(ignorePageGone);
+    await page.evaluate(installDevice, args).catch(ignorePageGone);
+    if (caption !== undefined) {
+        if (caption === "") {
+            await page.evaluate(hideCaption).catch(ignorePageGone);
+        }
+        else {
+            await page.evaluate(showCaption, caption).catch(ignorePageGone);
+        }
+    }
+    // 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 (page.__wgVideoViewport &&
+        page.__wgDeviceShell &&
+        page.__wgDeviceShell.width &&
+        page.__wgDeviceShell.height) {
+        await applyVideoDeviceStage(page, page.__wgDeviceShell, page.__wgVideoViewport, {
+            clear: false,
+            shutterOut: !!page.__wgDesktopFlat,
+            desktopFlat: !!page.__wgDesktopFlat,
+        });
+    }
+}

package/dist/{pilot-overlay/overlay-fixtures.d.ts → demo/overlay/phase-fixtures.d.ts}

@@ -1,5 +1,5 @@
-import type { StubPhaseResult } from "../highlights.js";
-import type { PilotHighlightFixtures } from "./fixtures.js";
+import type { StubPhaseResult } from "../../engine/stub/stub.js";
+import type { PilotHighlightFixtures } from "./pilot/fixtures.js";
 /**
  * The reverse: a resolved stub phase (what `runStubPhase` returns for a Block's stubBefore/After/OnError)
  * -> what the Pilot painter takes. Lets `auto/browser/pilot send` paint a Block's authored waygraph overlay

package/dist/{pilot-overlay/overlay-fixtures.js → demo/overlay/phase-fixtures.js}

@@ -48,8 +48,8 @@ export function describeOverlayFixtures(tag, f) {
         out.push(`${tag} ctx.bannerUi(${JSON.stringify(f.bannerUi)})`);
     if (f.todos?.length)
         out.push(`${tag} ctx.todos n=${f.todos.length} index=${f.todoIndex ?? 0}${f.todoPos ? ` pos=${f.todoPos}` : ""}`);
-    if (f.todoDockUi ?? f.todoUi)
-        out.push(`${tag} ctx.todoDockUi(${JSON.stringify(f.todoDockUi ?? f.todoUi)})`);
+    if (f.todoUi)
+        out.push(`${tag} todoUi ${JSON.stringify(f.todoUi)}`);
     if (f.device)
         out.push(`${tag} ctx.device(${typeof f.device === "string" ? f.device : f.device.preset ?? "custom"})`);
     if (f.zoom)

package/dist/{pilot-overlay/action-ring.js → demo/overlay/pilot/actions.js}

@@ -1,4 +1,5 @@
 import { ensureInstalled } from "./shell.js";
+import { ignorePageGone } from "../../../engine/page-gone.js";
 /** Paint the gray "auto" ring (Playwright is about to act here) at a viewport rectangle. */
 async function showPilotRect(page, box, label, tone = "auto") {
     await ensureInstalled(page);
@@ -30,7 +31,7 @@ async function showPilotRect(page, box, label, tone = "auto") {
             tag.style.opacity = "0";
         }, 4_000);
     }, { box, label, tone })
-        .catch(() => { });
+        .catch(ignorePageGone);
 }
 const LOCATOR_ACTIONS = ["click", "dblclick", "hover", "tap", "fill", "check", "uncheck", "selectOption", "press", "pressSequentially", "setInputFiles"];
 const patched = new WeakSet();

package/dist/{pilot-overlay → demo/overlay/pilot}/fixtures.d.ts

@@ -1,4 +1,7 @@
-import type { BannerPos, BannerUiOpts, DevicePreset, DeviceState, HighlightTone, TodoDockUiOpts, TodoListStyle, WaygraphTodoGroupInput } from "../highlights.js";
+import type { BannerPos, BannerUiOpts } from "../../../engine/stub/stub.js";
+import type { DevicePreset, DeviceState } from "../../../engine/stub/viewport.js";
+import type { HighlightTone } from "../../../engine/stub/ring.js";
+import type { TodoDockUiOpts, TodoListStyle, WaygraphTodoGroupInput } from "../../../engine/stub/todos.js";
 import type { Page } from "@playwright/test";
 /** One ring the Pilot agent wants painted (same fields as demo stub rings). */
 export type PilotFixtureRing = {
@@ -26,7 +29,7 @@ export type PilotFixtureRing = {
 };
 /**
  * Agent-sent highlight fixtures for a live Pilot / auto session.
- * Painted by {@link showPilotFixtures}; driven via IPC `op: "highlight"`.
+ * Painted by `showPilotFixtures`; driven via IPC `op: "highlight"`.
  * Mirrors demo stub surface: rings, todos, zoom, focus, device.
  */
 export type PilotHighlightFixtures = {
@@ -40,7 +43,7 @@ export type PilotHighlightFixtures = {
     todoTitle?: string;
     /** Todo dock side. Default `right`. */
     todoPos?: "left" | "right";
-    /** Presentation: `sequential` (default, arrow walkthrough) | `checklist` | `bullets`. Same as ctx.todoStyle. */
+    /** Presentation: `sequential` (default, arrow walkthrough) | `checklist` | `bullets`. Same as ctx.todos(id, items, { style }). */
     todoStyle?: TodoListStyle;
     /** Multiple titled lists (FR/Scenarios/ACs, same as ctx.todoGroups) - replaces {@link todos} when set. */
     todoGroups?: readonly WaygraphTodoGroupInput[];
@@ -78,8 +81,6 @@ export type PilotHighlightFixtures = {
     titlePos?: BannerPos;
     /** Banner UX: collision / hidden (same as `ctx.bannerUi`). */
     bannerUi?: BannerUiOpts;
-    /** Alias of {@link todoUi} - the name `ctx.todoDockUi` uses. */
-    todoDockUi?: TodoDockUiOpts;
 };
 /**
  * Paint (or clear) agent-authored highlight fixtures on the live page.

package/dist/{pilot-overlay → demo/overlay/pilot}/fixtures.js

@@ -1,7 +1,10 @@
-// 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 { buildTodoDock, resolveTodoDockUi } from "../../narration/todo-dock.js";
+import { formatHighlightCaption } from "../../narration/style.js";
+import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../../../engine/stub/ring.js";
+import { resolveDeviceState } from "../../narration/device.js";
 import { ensureInstalled } from "./shell.js";
-import { verboseLog } from "../auto-session/verbose-log.js";
+import { verboseLog } from "../../verbose-log.js";
+import { ignorePageGone } from "../../../engine/page-gone.js";
 /**
  * Paint (or clear) agent-authored highlight fixtures on the live page.
  * Multi-ring + optional todo strip + zoom/focus/device - the Pilot equivalent
@@ -44,7 +47,7 @@ export async function showPilotFixtures(page, fixtures) {
     const todoPos = fixtures.todoPos === "left" ? "left" : "right";
     const todoUi = resolveTodoDockUi(fixtures.todoUi ?? null);
     // Real TodoDockState (groups/style), same builder the demo runner uses - not a flat string[]
-    // re-implementation, so a Block/agent that authors ctx.todoGroups()/ctx.todoStyle() looks the
+    // re-implementation, so a Block/agent that authors ctx.todoGroups() or a todos style looks the
     // same on Pilot as it does in `waygraph demo`.
     const todoDock = fixtures.clear
         ? undefined
@@ -84,31 +87,31 @@ export async function showPilotFixtures(page, fixtures) {
         if (hit?.zoomOut !== undefined)
             zoomOut = hit.zoomOut !== false;
     }
-    // Device viewport - same runner/device-stage.js + inpage/device.js every other surface uses
+    // Device viewport - same demo/overlay/device-stage.ts + inpage/device.ts every other surface uses
     // (toast + persistent chip + touch mode), not a separate, simpler Pilot-only chip.
     if (fixtures.clear === true) {
-        const { applyDeviceToPage } = await import("../runner/device-stage.js");
-        await applyDeviceToPage(page, undefined, "clear").catch(() => { });
+        const { applyDeviceToPage } = await import("../device-stage.js");
+        await applyDeviceToPage(page, undefined, "clear").catch(ignorePageGone);
     }
     else if (fixtures.device !== undefined) {
         const d = resolveDeviceState(fixtures.device);
         if (d) {
             const [{ applyDeviceToPage }, { installDevice }] = await Promise.all([
-                import("../runner/device-stage.js"),
-                import("../runner/inpage/device.js"),
+                import("../device-stage.js"),
+                import("../inpage/device-chip.js"),
             ]);
-            await page.evaluate(installDevice, {}).catch(() => { });
-            await applyDeviceToPage(page, d, "set").catch(() => { });
+            await page.evaluate(installDevice, {}).catch(ignorePageGone);
+            await applyDeviceToPage(page, d, "set").catch(ignorePageGone);
         }
     }
     const bannerTitle = fixtures.clear ? undefined : fixtures.title;
     const bannerPos = fixtures.clear ? undefined : fixtures.titlePos;
     const bannerHidden = !!fixtures.clear || !!fixtures.bannerUi?.hidden;
     const bannerCollision = fixtures.bannerUi?.collision !== false;
-    // Same #wg-banner installer the demo runner uses (runner/inpage/banner.js) - not a separate
+    // Same #wg-banner installer the demo runner uses (demo/overlay/inpage/banner.ts) - not a separate
     // re-implementation. `tag: "waygraph pilot"` is the only Pilot-specific bit.
     if (bannerTitle !== undefined || bannerHidden) {
-        const { installBanner } = await import("../runner/inpage/banner.js");
+        const { installBanner } = await import("../inpage/banner.js");
         await page
             .evaluate(installBanner, {
             title: bannerTitle,
@@ -116,7 +119,7 @@ export async function showPilotFixtures(page, fixtures) {
             bannerUi: { hidden: bannerHidden, collision: bannerCollision, ...(bannerPos ? { pos: bannerPos } : {}) },
             tag: "waygraph pilot",
         })
-            .catch(() => { });
+            .catch(ignorePageGone);
     }
     // 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 - >>
@@ -185,9 +188,7 @@ export async function showPilotFixtures(page, fixtures) {
             }
             const zoomed = level > 1.001 || level < 0.999;
             badge.dataset.zoomed = zoomed ? "1" : "0";
-            badge.innerHTML =
-                '<span class="wg-pilot-fx-zoom-ico"><svg viewBox="0 0 24 24" fill="none" stroke="#fde68a" 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></span>' +
-                    `<span class="wg-pilot-fx-zoom-val">${level.toFixed(2)}\u00d7</span>`;
+            __wgSet(badge, __wgEl("span", { class: "wg-pilot-fx-zoom-ico" }, __wgSvg('<svg viewBox="0 0 24 24" fill="none" stroke="#fde68a" 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>')), __wgEl("span", { class: "wg-pilot-fx-zoom-val" }, level.toFixed(2) + "\u00d7"));
         };
         const clearZoom = () => {
             // Undo any leftover CSS-scale from older Pilot zoom path.
@@ -217,7 +218,7 @@ export async function showPilotFixtures(page, fixtures) {
         let painted = 0;
         let focusBox = null;
         // Paint through the SAME shared ring primitive the demo/auto singleton ring uses
-        // (window.__wgPaintRingAt, installed by runner/inpage/core.js's installCore - see
+        // (window.__wgPaintRingAt, installed by demo/overlay/inpage/core.ts's installCore - see
         // ensureInstalled) - one ring implementation, not a separate DOM-building copy here.
         rings.forEach((ring, i) => {
             const box = ringBoxes[i];

package/dist/{pilot-overlay → demo/overlay/pilot}/shell.d.ts

@@ -1,4 +1,4 @@
-import type { HighlightTone } from "../highlights.js";
+import type { HighlightTone } from "../../../engine/stub/ring.js";
 import type { BrowserContext, Page } from "@playwright/test";
 /**
  * Re-install the overlay shell on every navigation (about:blank, goto, etc.)
@@ -26,7 +26,7 @@ export declare function showPilotActivity(page: Page, text: string): Promise<voi
  * JSON blob in a terminal. Real, direct user request.
  *
  * Reuses the real `#wg-ring`/`#wg-ring-label` elements + `WAYGRAPH_RING_CSS`
- * (see `highlights.ts`) - the exact same visual language `cli.ts`'s own demo
+ * (see `demo/narration/index.ts`) - the exact same visual language `cli.ts`'s own demo
  * stepper paints rings with, not a separate look-alike. Still a purpose-built
  * renderer here (position/show/hide only, via plain `getBoundingClientRect` -
  * no camera zoom/spotlight/todo-dock/pacing), since that whole engine still

package/dist/{pilot-overlay → demo/overlay/pilot}/shell.js

@@ -1,7 +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";
+import { verboseLog } from "../../verbose-log.js";
+import { ignorePageGone } from "../../../engine/page-gone.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
@@ -64,7 +64,7 @@ const OVERLAY_CSS = `
 }
 #wg-pilot-activity.wg-pilot-toast-show { opacity: 1; transform: translateY(0); }
 /* Agent fixture rings (painted via the shared .wg-ring-el primitive, see ui/css/ring.css and
-   runner/inpage/core.js's __wgPaintRingAt), #wg-pilot-fx-todos, #wg-ring/#wg-ring-label and
+   demo/overlay/inpage/core.ts's __wgPaintRingAt), #wg-pilot-fx-todos, #wg-ring/#wg-ring-label and
    #wg-banner all come from the ONE shared bundle ensureShadowRoot installs (ui/css/*.css) - not
    redefined here. */
 /* Spotlight (demo focus:true) - dim page, cutout around target. */
@@ -96,16 +96,7 @@ function installPilotOverlayShell(css) {
     if (__wgById("wg-pilot-overlay"))
         return;
     __wgCss(css, "wg-pilot-overlay-css");
-    const root = document.createElement("div");
-    root.id = "wg-pilot-overlay";
-    root.innerHTML =
-        '<div id="wg-pilot-badge">Waygraph Pilot</div>' +
-            '<div id="wg-pilot-panel">' +
-            '<div id="wg-pilot-panel-toggle"><button id="wg-pilot-view-current" class="wg-pilot-tab-active">Here</button>' +
-            '<button id="wg-pilot-view-graph">All nodes</button></div>' +
-            '<div id="wg-pilot-panel-current"></div>' +
-            '<div id="wg-pilot-panel-graph" style="display:none"></div>' +
-            "</div>";
+    const root = __wgEl("div", { id: "wg-pilot-overlay" }, __wgEl("div", { id: "wg-pilot-badge" }, "Waygraph Pilot"), __wgEl("div", { id: "wg-pilot-panel" }, __wgEl("div", { id: "wg-pilot-panel-toggle" }, __wgEl("button", { id: "wg-pilot-view-current", class: "wg-pilot-tab-active" }, "Here"), __wgEl("button", { id: "wg-pilot-view-graph" }, "All nodes")), __wgEl("div", { id: "wg-pilot-panel-current" }), __wgEl("div", { id: "wg-pilot-panel-graph", style: "display:none" })));
     __wgAdd(root);
     __wgById("wg-pilot-badge").addEventListener("click", () => {
         __wgById("wg-pilot-panel").classList.toggle("wg-pilot-open");
@@ -150,16 +141,16 @@ export async function installPersistentPilotOverlay(context) {
 /** Idempotent - safe to call before every update, matching narrate mode's own precedent. */
 export async function ensureInstalled(page) {
     await ensureShadowRoot(page);
-    await page.evaluate(installPilotOverlayShell, OVERLAY_CSS).catch(() => { });
+    await page.evaluate(installPilotOverlayShell, OVERLAY_CSS).catch(ignorePageGone);
     // The shared ring primitive (__wgEnsureRingEl/__wgPaintRingAt) - so Pilot's fixture rings paint
     // through the SAME implementation the demo/auto singleton ring uses (see ui/css/ring.css / this
     // file's own header comment on redundancy), not a separate DOM-building copy.
-    const { installCore } = await import("../runner/inpage/core.js");
-    await page.evaluate(installCore, {}).catch(() => { });
-    // Device toast/chip CSS (runner/overlay-css.js's RUNNER_EXTRA_CSS) - same rules the demo runner
+    const { installCore } = await import("../inpage/core.js");
+    await page.evaluate(installCore, {}).catch(ignorePageGone);
+    // Device toast/chip CSS (demo/overlay/overlay-css.ts's RUNNER_EXTRA_CSS) - same rules the demo runner
     // uses, reused here (not re-authored) so a device fixture looks identical on Pilot.
-    const { RUNNER_EXTRA_CSS } = await import("../runner/overlay-css.js");
-    await page.evaluate(([css, key]) => __wgCss(css, key), [RUNNER_EXTRA_CSS, "wg-runner-css"]).catch(() => { });
+    const { RUNNER_EXTRA_CSS } = await import("../overlay-css.js");
+    await page.evaluate(([css, key]) => __wgCss(css, key), [RUNNER_EXTRA_CSS, "wg-runner-css"]).catch(ignorePageGone);
 }
 /**
  * Bottom-left transient toast, separate from the persistent bottom-right
@@ -187,7 +178,7 @@ export async function showPilotActivity(page, text) {
             toast.classList.remove("wg-pilot-toast-show");
         }, 2500);
     }, text)
-        .catch(() => { });
+        .catch(ignorePageGone);
 }
 /**
  * "browser-use"-style vision box: a ring drawn around the exact element
@@ -196,7 +187,7 @@ export async function showPilotActivity(page, text) {
  * JSON blob in a terminal. Real, direct user request.
  *
  * Reuses the real `#wg-ring`/`#wg-ring-label` elements + `WAYGRAPH_RING_CSS`
- * (see `highlights.ts`) - the exact same visual language `cli.ts`'s own demo
+ * (see `demo/narration/index.ts`) - the exact same visual language `cli.ts`'s own demo
  * stepper paints rings with, not a separate look-alike. Still a purpose-built
  * renderer here (position/show/hide only, via plain `getBoundingClientRect` -
  * no camera zoom/spotlight/todo-dock/pacing), since that whole engine still
@@ -276,5 +267,5 @@ export async function showPilotVision(page, selector, label, tone = "auto") {
             tag.style.opacity = "0";
         }, 4_000);
     }, { box, label, tone })
-        .catch(() => { });
+        .catch(ignorePageGone);
 }

package/dist/demo/overlay/reattach.d.ts

@@ -0,0 +1,7 @@
+import type { Page } from "@playwright/test";
+type Repaint = () => Promise<unknown>;
+/** Repaints the page's overlay now, after any repaint already running (two never interleave). */
+export declare function repaintOverlay(page: Page): Promise<void>;
+/** Registers (or replaces) how this page's overlay repaints itself after a navigation. */
+export declare function keepOverlayOnNavigation(page: Page, repaint: Repaint): void;
+export {};

package/dist/demo/overlay/reattach.js

@@ -0,0 +1,23 @@
+import { ignorePageGone } from "../../engine/page-gone.js";
+const repaints = new WeakMap();
+const running = new WeakMap();
+/** Repaints the page's overlay now, after any repaint already running (two never interleave). */
+export function repaintOverlay(page) {
+    const next = (running.get(page) ?? Promise.resolve()).then(async () => {
+        await repaints.get(page)?.();
+    }).catch(ignorePageGone);
+    running.set(page, next);
+    return next;
+}
+/** Registers (or replaces) how this page's overlay repaints itself after a navigation. */
+export function keepOverlayOnNavigation(page, repaint) {
+    const listening = repaints.has(page);
+    repaints.set(page, repaint);
+    if (listening)
+        return;
+    let settle;
+    page.on("load", () => {
+        clearTimeout(settle);
+        settle = setTimeout(() => void repaintOverlay(page), 80);
+    });
+}

package/dist/demo/overlay/rings.d.ts

@@ -0,0 +1,33 @@
+import type { WgBox, WgPage } from "../types.js";
+import type { Locator } from "@playwright/test";
+/**
+ * Scroll a locator into view for demo theater.
+ * Prefer CSS smooth scroll + scrollend wait. Do NOT call Playwright's
+ * scrollIntoViewIfNeeded first - that jumps instantly and makes the
+ * following smooth scroll a no-op (looks like a teleport), especially
+ * noticeable under --fast when dwell is shorter.
+ * Pass opts.instant=true only for skipTheater / blitz.
+ */
+export declare function ensureLocatorInView(locator: Locator, opts: any): Promise<void>;
+export declare function ensureSelectorInView(page: WgPage, selector: any, opts?: any): Promise<void>;
+export declare function applyHighlightZoom(page: WgPage, selector: any, zoom: any, zoomOut: any): Promise<void>;
+export declare function cycleHighlightRings(page: WgPage, highlights: any, gatesFast: any, opts: any): Promise<void>;
+export declare function showRing(page: WgPage, box: WgBox, label: any, tone: any, style: any): Promise<void>;
+/** 0-based stub index for Method fill/click todo advance; -1 if none. */
+export declare function matchStubIndexForLocator(page: WgPage, locator: Locator, stubs: any): Promise<number>;
+export declare function captionForLocator(page: WgPage, locator: Locator, stubs: any, fallback: any): Promise<{
+    label: any;
+    tone: string;
+    size: string;
+    weight: string;
+}>;
+export declare function dwellMatchedStub(page: WgPage, locator: Locator, stubs: any, pacing: any): Promise<void>;
+export declare function hideRing(page: WgPage): Promise<void>;
+/**
+ * True if the engine's own narrate() (waygraph's public export, for a Block
+ * author explicitly captioning one action) JUST positioned the ring for
+ * THIS action, moments ago - the automatic per-fill/per-click narration
+ * below should not immediately overwrite an author's own explicit caption
+ * with its generic guess.
+ */
+export declare function wasJustNarrated(page: WgPage): Promise<boolean>;