waygraph 0.16.0 → 0.16.1

package/dist/demo/overlay/device-stage.d.ts

@@ -1,13 +1,26 @@
+import type { DeviceState } from "../../engine/stub/viewport.js";
 import type { WgPage } from "../types.js";
+interface Size {
+    width: number;
+    height: number;
+}
+/** How a device-shell change animates: clear it, shutter out to desktop, enter in, or stay flat. */
+interface DeviceStageOptions {
+    clear?: boolean;
+    shutterOut?: boolean;
+    enterIn?: boolean;
+    desktopFlat?: boolean;
+}
 /**
  * Video recording locks Playwright viewport to recordVideo.size. Shrinking
  * setViewportSize to mobile/tablet letterboxes the .webm top-left. Instead keep
  * the stage size and center a device-sized #wg-device-shell inside the frame.
  */
-export declare function applyVideoDeviceStage(page: WgPage, target: any, stage: any, opts: any): Promise<void>;
+export declare function applyVideoDeviceStage(page: WgPage, target: Size, stage: Size, opts?: DeviceStageOptions): Promise<void>;
 /**
  * Apply authored device fixture to the live page (0.13+).
  * Seamless viewport lerp + centered window + toast on set/clear.
  * With --video: keep recordVideo stage size and center a device shell in-frame.
  */
-export declare function applyDeviceToPage(page: WgPage, device: any, sync: any): Promise<void>;
+export declare function applyDeviceToPage(page: WgPage, device: DeviceState | null | undefined, sync?: string): Promise<void>;
+export {};

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

@@ -1 +1,2 @@
-export declare function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi, bannerUi, tag: bannerTag }: any): void;
+import type { OverlayInstallArgs } from "../../types.js";
+export declare function installBanner({ title, favicon, bannerPos, bannerUi, tag: bannerTag }: OverlayInstallArgs): void;

package/dist/demo/overlay/inpage/banner.js

@@ -1,4 +1,4 @@
-export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi, bannerUi, tag: bannerTag }) {
+export function installBanner({ title, favicon, bannerPos, bannerUi, tag: bannerTag }) {
     const POSITIONS = ["left", "center", "right"];
     const applyPos = (el, pos) => {
         el.dataset.pos = pos;
@@ -22,7 +22,7 @@ export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay,
             catch {
                 /* ignore */
             }
-            const startPos = saved && POSITIONS.includes(saved) ? saved : bannerPos;
+            const startPos = saved && POSITIONS.includes(saved) ? saved : bannerPos || "left";
             applyPos(banner, startPos);
             banner.title = "Click to move: top left / center / right";
             banner.addEventListener("click", (e) => {
@@ -155,6 +155,6 @@ export function installBanner({ title, favicon, bannerPos, todoPos, envAutoplay,
         iconLink.rel = "icon";
         document.head.appendChild(iconLink);
     }
-    if (iconLink.href !== favicon)
+    if (favicon && iconLink.href !== favicon)
         iconLink.href = favicon;
 }

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

@@ -1,2 +1,2 @@
-export declare function showCaption(text: any): void;
+export declare function showCaption(text: string): void;
 export declare function hideCaption(): void;

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

@@ -1 +1,2 @@
-export declare function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }: any): void;
+import type { OverlayInstallArgs } from "../../types.js";
+export declare function installCore({ envAutoplay, todoDockUi }: OverlayInstallArgs): void;

package/dist/demo/overlay/inpage/core.js

@@ -1,4 +1,4 @@
-export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) {
+export function installCore({ envAutoplay, todoDockUi }) {
     window.__wgTodoDockUi = todoDockUi || {
         compact: true,
         cap: 5,

package/dist/demo/overlay/inpage/device-chip.d.ts

@@ -1 +1 @@
-export declare function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }: any): void;
+export declare function installDevice(): void;

package/dist/demo/overlay/inpage/device-chip.js

@@ -1,5 +1,5 @@
 // In-page (runs inside the browser via page.evaluate, must stay self-contained): the device toast and chip.
-export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) {
+export function installDevice() {
     // Device toast + chip (0.13.2+) - announce on set/clear; quiet chip on keep.
     // Payload: { sync, device?, remain?, announce? }
     window.__wgSyncDevice = (payload) => {
@@ -114,7 +114,7 @@ export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay,
             (device && device.preset === "desktop" && !device.touchMode);
         if (isDesktopClear) {
             setCursor(false);
-            const announce = payload.announce !== false && sync !== "keep";
+            const announce = payload?.announce !== false && sync !== "keep";
             if (announce) {
                 const vp = device && device.viewport ? device.viewport : { width: 1280, height: 720 };
                 showToast("desktop", false, "Back to desktop", vp.width + "×" + vp.height + " · mouse", "landscape");
@@ -144,8 +144,8 @@ export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay,
             return;
         const preset = device.preset || "desktop";
         const touch = !!device.touchMode;
-        const remain = payload.remain !== false && sync !== "clear";
-        const vp = device.viewport || {};
+        const remain = payload?.remain !== false;
+        const vp = device.viewport || { width: 0, height: 0 };
         const orient = device.orientation === "landscape" || device.orientation === "portrait"
             ? device.orientation
             : vp.height > vp.width
@@ -163,8 +163,8 @@ export function installDevice({ title, favicon, bannerPos, todoPos, envAutoplay,
         document.documentElement.dataset.wgTouch = touch ? "1" : "0";
         if (window.__wgEnsureZoomBadge)
             window.__wgEnsureZoomBadge();
-        const announce = payload.announce === true ||
-            (payload.announce !== false && (sync === "set" || sync === "clear") && changed);
+        const announce = payload?.announce === true ||
+            (payload?.announce !== false && sync === "set" && changed);
         const size = (vp.width || "?") +
             "×" +
             (vp.height || "?") +

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

@@ -1,9 +1,10 @@
-export declare function addNetworkEntry(entry: any): void;
+import type { NetworkEntry } from "../../types.js";
+export declare function addNetworkEntry(entry: NetworkEntry): void;
 /**
  * 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 declare function setNetworkTabVisible(visible: any): void;
+export declare function setNetworkTabVisible(visible: boolean): void;
 /** Clears every captured entry and removes the panel - a fresh navigation/session starting over. */
 export declare function clearNetworkLog(): void;

package/dist/demo/overlay/inpage/network.js

@@ -1,14 +1,3 @@
-// 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.
@@ -113,7 +102,7 @@ export function addNetworkEntry(entry) {
     row.dataset.ok = entry.ok ? "1" : "0";
     let path = entry.url;
     try {
-        const u = new URL(entry.url);
+        const u = new URL(String(entry.url));
         path = u.pathname + u.search;
     }
     catch {

package/dist/demo/overlay/inpage/panel-chrome.d.ts

@@ -1 +1 @@
-export declare function installPanelChrome({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }: any): void;
+export declare function installPanelChrome(): void;

package/dist/demo/overlay/inpage/panel-chrome.js

@@ -1,5 +1,5 @@
 // In-page (runs inside the browser via page.evaluate, must stay self-contained): the step panel's Hide/Show chrome and mini Next.
-export function installPanelChrome({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) {
+export function installPanelChrome() {
     // Hide/Show for #wg-panel - call after every panel content refresh.
     // Collapsed = "N / M · block" + Next (when not auto). Never pass
     // forceCollapsed:false - omit so Hide/localStorage wins.

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

@@ -1 +1 @@
-export declare function installStamp({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }: any): void;
+export declare function installStamp(): void;

package/dist/demo/overlay/inpage/stamp.js

@@ -1,5 +1,5 @@
 // In-page (runs inside the browser via page.evaluate, must stay self-contained): readiness stamps agents read to know a panel painted.
-export function installStamp({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) {
+export function installStamp() {
     // Blind-agent overlay beacons: every modal root gets data-wg-ui /
     // data-wg-modal / data-wg-ready so tests can fail on a blank panel.
     window.__wgStampModal = (el, kind, meta) => {

package/dist/demo/overlay/inpage/swipe-zoom.d.ts

@@ -1 +1 @@
-export declare function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }: any): void;
+export declare function installSwipeZoom(): void;

package/dist/demo/overlay/inpage/swipe-zoom.js

@@ -1,5 +1,5 @@
 // In-page (runs inside the browser via page.evaluate, must stay self-contained): swipe trails and ring zoom.
-export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) {
+export function installSwipeZoom() {
     /**
      * Finger swipe trail for touch theater (orientation rotate / device change).
      * opts: { dir: 'left'|'right'|'up'|'down', label?, ms? }

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

@@ -1 +1,2 @@
-export declare function installTodos({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }: any): void;
+import type { OverlayInstallArgs } from "../../types.js";
+export declare function installTodos({ todoPos }: OverlayInstallArgs): void;

package/dist/demo/overlay/inpage/todos.js

@@ -1,5 +1,4 @@
-// In-page (runs inside the browser via page.evaluate, must stay self-contained): the todo dock(s).
-export function installTodos({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) {
+export function installTodos({ todoPos }) {
     // Floating todo dock - lives outside #wg-panel so --mini / Hide never
     // hide the checklist. Click cycles left <-> right with CSS transform.
     // Authors set side via ctx.todos(id, items, { pos }); env / --todo-* fallback.

package/dist/demo/overlay/network-capture.d.ts

@@ -1,4 +1,4 @@
-import type { WgPage } from "../types.js";
+import type { NetworkEntry, WgPage } from "../types.js";
 /**
  * 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
@@ -7,7 +7,7 @@ import type { WgPage } from "../types.js";
  * this, the "network tab" reset to empty on every step that navigated - not what a persistent
  * Network tab is supposed to do.
  */
-export declare function recordNetworkEntry(page: WgPage, entry: any): Promise<void | undefined>;
+export declare function recordNetworkEntry(page: WgPage, entry: NetworkEntry): Promise<void | undefined>;
 /**
  * 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

package/dist/demo/overlay/network-capture.js

@@ -119,7 +119,7 @@ export function installNetworkCapture(page) {
             status: 0,
             ok: false,
             reqBody: request.postData() || undefined,
-            resBody: request.failure() ? request.failure().errorText : undefined,
+            resBody: request.failure()?.errorText,
         });
     });
 }

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

@@ -1,22 +1,30 @@
-import type { WgPage } from "../types.js";
-export declare function createOverlayStage(page: WgPage, { todoDockRef, deviceRef }: any): {
+import type { BannerUiState, StepperRefs, WgPage } from "../types.js";
+import type { StubPhaseResult } from "../../engine/stub/stub.js";
+import type { TodoDockState, TodoDockUiOpts } from "../../engine/stub/todos.js";
+import type { DeviceState } from "../../engine/stub/viewport.js";
+export declare function createOverlayStage(page: WgPage, { todoDockRef, deviceRef }: Pick<StepperRefs, never> & {
+    todoDockRef: StepperRefs["todoDock"];
+    deviceRef: StepperRefs["device"];
+}): {
     state: {
-        lastTodoDock: any;
-        lastDevice: any;
-        lastBannerUi: Record<string, any>;
+        lastTodoDock: TodoDockState | undefined;
+        lastDevice: DeviceState | undefined;
+        lastBannerUi: BannerUiState;
     };
-    pushTodoDockUi: (patch: any) => Promise<void>;
-    rememberTodoDock: (dock: any, sync: any, parallel: any) => void;
-    syncAllTodoDocks: (opts: any) => Promise<void>;
-    applyPhase: (phase: any, { reapplyDeviceOnKeep }?: {
+    pushTodoDockUi: (patch: TodoDockUiOpts | undefined) => Promise<void>;
+    rememberTodoDock: (dock: TodoDockState | undefined, sync: "set" | "clear" | "keep", parallel: boolean) => void;
+    syncAllTodoDocks: (opts?: {
+        parallel?: boolean;
+    }) => Promise<void>;
+    applyPhase: (phase: StubPhaseResult, { reapplyDeviceOnKeep }?: {
         reapplyDeviceOnKeep?: boolean | undefined;
     }) => Promise<{
         appliedTodo: {
-            dock: import("../../index.js").TodoDockState | undefined;
+            dock: TodoDockState | undefined;
             sync: "set" | "clear" | "keep";
         };
         appliedDevice: {
-            device: import("../../index.js").DeviceState | undefined;
+            device: DeviceState | undefined;
             sync: "set" | "clear" | "keep";
         };
     }>;

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

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

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

@@ -1,5 +1,9 @@
 import type { WgBox, WgPage } from "../types.js";
 import type { Locator } from "@playwright/test";
+import type { ResolvedHighlight } from "../../engine/stub/ring.js";
+import type { DemoPace } from "../../engine/stub/pace.js";
+import type { TodoDockState, WaygraphTodoItem } from "../../engine/stub/todos.js";
+import type { Pacing } from "../stepper/pacing.js";
 /**
  * Scroll a locator into view for demo theater.
  * Prefer CSS smooth scroll + scrollend wait. Do NOT call Playwright's
@@ -8,20 +12,44 @@ import type { Locator } from "@playwright/test";
  * 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;
+export declare function ensureLocatorInView(locator: Locator, opts?: {
+    instant?: boolean;
+}): Promise<void>;
+export declare function ensureSelectorInView(page: WgPage, selector: string, opts?: {
+    instant?: boolean;
+}): Promise<void>;
+export declare function applyHighlightZoom(page: WgPage, selector: string | undefined, zoom: number | undefined, zoomOut: boolean | undefined): Promise<void>;
+/** How `cycleHighlightRings` plays a step's rings: hold times, pace, and the todo dock it moves along. */
+export interface CycleRingsOptions {
+    /** Hold for each ring when it sets none (the failure path holds longer). */
+    defaultHoldMs?: number;
+    pace?: DemoPace | undefined;
+    todoDock?: TodoDockState | undefined;
+    todos?: readonly WaygraphTodoItem[] | undefined;
+    todoSync?: "set" | "clear" | "keep" | undefined;
+    todoDockRef?: {
+        current: TodoDockState | undefined;
+    } | undefined;
+    /** False when the stub already set the dock's progress. */
+    advanceTodos?: boolean;
+    stepLabel?: string;
+}
+export declare function cycleHighlightRings(page: WgPage, highlights: readonly ResolvedHighlight[] | undefined, gatesFast: boolean, opts?: CycleRingsOptions): Promise<void>;
+export declare function showRing(page: WgPage, box: WgBox, label: string, tone: string | undefined, style?: {
+    size?: string | undefined;
+    weight?: string | undefined;
+    selector?: string | undefined;
+    focus?: boolean;
+}): Promise<void>;
+/** The stubBefore ring a locator is, by overlapping bounding boxes: its index, or -1. For a Method's todo advance. */
+export declare function matchStubIndexForLocator(page: WgPage, locator: Locator, stubs: readonly ResolvedHighlight[] | undefined): Promise<number>;
+export declare function captionForLocator(page: WgPage, locator: Locator, stubs: readonly ResolvedHighlight[] | undefined, fallback: string): Promise<{
+    label: string;
     tone: string;
     size: string;
     weight: string;
 }>;
-export declare function dwellMatchedStub(page: WgPage, locator: Locator, stubs: any, pacing: any): Promise<void>;
+export declare function dwellMatchedStub(page: WgPage, locator: Locator, stubs: readonly ResolvedHighlight[] | undefined, pacing: Pick<Pacing, "gatesFast" | "demoPace"> | undefined): Promise<void>;
 export declare function hideRing(page: WgPage): Promise<void>;
 /**
  * True if the engine's own narrate() (waygraph's public export, for a Block

package/dist/demo/overlay/rings.js

@@ -1,11 +1,11 @@
 import { ANSI, ansiPaint, demoFixture, demoHighlight, demoLog } from "../stepper/demo-log.js";
 import { playSwipeTrail } from "./cursor.js";
-import { advanceTodoDock, normalizeTodos } from "../narration/todo-dock.js";
+import { advanceTodoDock } from "../narration/todo-dock.js";
 import { formatHighlightCaption } from "../narration/style.js";
 import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../../engine/stub/ring.js";
 import { resolveFixtureDwellMs } from "../narration/demo-pace.js";
 import { envNumber } from "../../engine/env.js";
-import { ignorePageGone } from "../../engine/page-gone.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
 /**
  * Scroll a locator into view for demo theater.
  * Prefer CSS smooth scroll + scrollend wait. Do NOT call Playwright's
@@ -184,8 +184,7 @@ export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
             .catch(ignorePageGone);
     }
     let lastRingEndedAt = null;
-    for (let i = 0; i < list.length; i++) {
-        const h = list[i];
+    for (const [i, h] of list.entries()) {
         const ringStarted = Date.now();
         try {
             await ensureSelectorInView(page, h.selector);
@@ -200,13 +199,13 @@ export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
             // "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
+            const box = ((await hLoc.count().catch(ignorePageGone)) ?? 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)
+                    .catch(ignorePageGone)
                 : null;
             if (box && box.width > 0 && box.height > 0) {
                 await showRing(page, box, h.label, h.tone || "planned", {
@@ -230,10 +229,8 @@ export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
                     }, dock)
                         .catch(ignorePageGone);
                 }
-                else if (!dock && ((opts && opts.todos && opts.todos.length) || (h.todos && h.todos.length))) {
-                    const rows = opts && opts.todos && opts.todos.length
-                        ? opts.todos
-                        : normalizeTodos(h.todos, h.todoIndex);
+                else if (!dock && opts?.todos?.length) {
+                    const rows = opts.todos;
                     await page
                         .evaluate((todos) => {
                         if (window.__wgSyncTodos)
@@ -273,16 +270,16 @@ export async function cycleHighlightRings(page, highlights, gatesFast, opts) {
             }
         }
         catch (err) {
-            demoHighlight(h || { selector: h && h.selector, label: "(error)" }, "SKIP " + String(err instanceof Error ? err.message : err).slice(0, 80));
+            demoHighlight(h, "SKIP " + String(err instanceof Error ? err.message : err).slice(0, 80));
         }
     }
-    if (list.length > 0) {
-        const last = list[list.length - 1];
+    const last = list.at(-1);
+    if (last) {
         // 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)
+            ? await page.locator(last.selector).first().elementHandle({ timeout: 100 }).catch(ignoreTimeout)
             : null;
         await page
             .evaluate(({ h, el }) => {
@@ -333,7 +330,7 @@ export async function showRing(page, box, label, tone, style) {
     // 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;
+    const handle = selector ? await page.locator(selector).first().elementHandle({ timeout: 100 }).catch(ignoreTimeout) : null;
     await page
         .evaluate(({ box, label, tone, size, weight, el, focus }) => {
         if (el && window.__wgFollowRing) {
@@ -352,46 +349,18 @@ export async function showRing(page, box, label, tone, style) {
     }, { box, label, tone: tone || "planned", size, weight, el: handle, focus })
         .catch(ignorePageGone);
 }
-/** Match a locator to a stubBefore slot by overlapping bounding boxes. */
-async function matchStubForLocator(page, locator, stubs) {
-    if (!stubs || stubs.length === 0)
-        return null;
-    const box = await locator.boundingBox().catch(() => null);
-    if (!box)
-        return null;
-    for (const s of stubs) {
-        try {
-            const b = await page.locator(s.selector).first().boundingBox();
-            if (b &&
-                Math.abs(b.x - box.x) < 4 &&
-                Math.abs(b.y - box.y) < 4 &&
-                Math.abs(b.width - box.width) < 8) {
-                return s;
-            }
-        }
-        catch {
-            // A stub selector Playwright can't parse can't be this element either.
-        }
-    }
-    return null;
-}
-/** 0-based stub index for Method fill/click todo advance; -1 if none. */
+/** The stubBefore ring a locator is, by overlapping bounding boxes: its index, or -1. For a Method's todo advance. */
 export async function matchStubIndexForLocator(page, locator, stubs) {
     if (!stubs || stubs.length === 0)
         return -1;
-    const box = await locator.boundingBox().catch(() => null);
+    const box = await locator.boundingBox().catch(ignorePageGone);
     if (!box)
         return -1;
     for (let i = 0; i < stubs.length; i++) {
-        const s = stubs[i];
         try {
-            const b = await page.locator(s.selector).first().boundingBox();
-            if (b &&
-                Math.abs(b.x - box.x) < 4 &&
-                Math.abs(b.y - box.y) < 4 &&
-                Math.abs(b.width - box.width) < 8) {
+            const b = await page.locator(stubs[i].selector).first().boundingBox();
+            if (b && Math.abs(b.x - box.x) < 4 && Math.abs(b.y - box.y) < 4 && Math.abs(b.width - box.width) < 8)
                 return i;
-            }
         }
         catch {
             // A stub selector Playwright can't parse can't be this element either.
@@ -399,6 +368,11 @@ export async function matchStubIndexForLocator(page, locator, stubs) {
     }
     return -1;
 }
+/** The stubBefore ring a locator is, or null. */
+async function matchStubForLocator(page, locator, stubs) {
+    const i = await matchStubIndexForLocator(page, locator, stubs);
+    return i >= 0 && stubs ? stubs[i] : null;
+}
 export async function captionForLocator(page, locator, stubs, fallback) {
     const matched = await matchStubForLocator(page, locator, stubs);
     if (matched) {

package/dist/demo/stepper/after.js

@@ -1,12 +1,13 @@
+import { envFlag } from "../../engine/env.js";
 import { hasAuthoredStubAfter, resolveSlides, runStubPhase } from "../narration/narration.js";
 import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narration/style.js";
-import { demoLog, logStubPhaseFixtures, logTodoDockFull, paceSpeakFields, summarizeDevice } from "./demo-log.js";
-import { extractVerifyHighlights, renderAfterStep } from "./step-panels.js";
-import { presentSlides } from "./slides.js";
 import { logBannerDom, probeBanner } from "./banner-log.js";
 import { logDocks } from "./before.js";
+import { demoLog, logStubPhaseFixtures, logTodoDockFull, paceSpeakFields, summarizeDevice } from "./demo-log.js";
+import { renderAfterStep } from "./panel-after.js";
+import { presentSlides } from "./slides.js";
+import { extractVerifyHighlights } from "./step-panels.js";
 import { forceCollapsed } from "./view.js";
-import { envFlag } from "../../engine/env.js";
 const quiet = () => envFlag("WAYGRAPH_JSON");
 export async function showAfter(ctx, view, result) {
     const { stage, refs } = ctx;
@@ -65,7 +66,7 @@ async function showSlides(ctx, view, result) {
     const slides = resolveSlides(view.step.block, { out: result }).map((s) => applyHighlightStyleDefaults(s, view.step.highlightStyle));
     if (slides.length === 0)
         return;
-    await presentSlides(ctx.page, slides, ctx.gate.wait, {
+    await presentSlides(ctx.page, slides, {
         title: ctx.title,
         blockName: view.step.block.name,
         fast: ctx.pacing.gatesFast,
@@ -89,21 +90,10 @@ async function narrateAfter(ctx, view, result) {
         }),
     });
     const highlights = phase.highlights.map((h) => {
+        // The ring's look and timing only; its todo, gesture and cursor belong to stubBefore.
         const styled = applyHighlightStyleDefaults(h, style);
-        return {
-            selector: styled.selector,
-            label: formatHighlightCaption(styled),
-            duration: styled.duration,
-            fastMode: styled.fastMode,
-            tone: styled.tone,
-            size: styled.size,
-            weight: styled.weight,
-            zoom: styled.zoom,
-            zoomOut: styled.zoomOut,
-            focus: !!styled.focus,
-            color: styled.color,
-            detail: styled.detail,
-        };
+        const { tag: _tag, cursor: _cursor, todo: _todo, slotId: _slotId, gesture: _gesture, ...ring } = styled;
+        return { ...ring, label: formatHighlightCaption(styled), focus: !!styled.focus };
     });
     return { phase, highlights };
 }

package/dist/demo/stepper/banner-log.d.ts

@@ -1,6 +1,7 @@
-import type { WgPage } from "../types.js";
+import type { BannerUiState, WgPage } from "../types.js";
+import type { StubPhaseResult } from "../../engine/stub/stub.js";
 /** Authored banner UX from a stub phase -> the { pos, collision, hidden } shape installOverlay takes. */
-export declare function bannerUiFromPhase(phase: any): Record<string, any>;
+export declare function bannerUiFromPhase(phase: Pick<StubPhaseResult, "titlePos" | "bannerUi"> | null | undefined): BannerUiState;
 /** Read the live banner: text, position, whether it was moved by ring collision; drains the move log. */
 export declare function probeBanner(page: WgPage): Promise<{
     present: boolean;
@@ -30,8 +31,5 @@ export declare function probeBanner(page: WgPage): Promise<{
     w: number;
     h: number;
     log: any;
-} | {
-    present: boolean;
-    log: never[];
 }>;
-export declare function logBannerDom(tag: any, p: any): void;
+export declare function logBannerDom(tag: string, p: Awaited<ReturnType<typeof probeBanner>> | null | undefined): void;

package/dist/demo/stepper/banner-log.js

@@ -1,4 +1,5 @@
 import { demoLog } from "./demo-log.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
 /** Authored banner UX from a stub phase -> the { pos, collision, hidden } shape installOverlay takes. */
 export function bannerUiFromPhase(phase) {
     const ui = {};
@@ -41,7 +42,8 @@ export async function probeBanner(page) {
             log,
         };
     })
-        .catch(() => ({ present: false, log: [] }));
+        .catch(ignorePageGone)
+        .then((probe) => probe ?? { present: false, log: [] });
 }
 export function logBannerDom(tag, p) {
     if (!p)

package/dist/demo/stepper/before.js

@@ -1,13 +1,13 @@
 // Before a demo step runs: play the Block's stubBefore narration (rings, todos, device, title, caption) and show the
 // step's panel, then log what was painted so an agent without eyes can check it.
+import { envFlag } from "../../engine/env.js";
 import { runStubPhase } from "../narration/narration.js";
 import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narration/style.js";
+import { logBannerDom, probeBanner } from "./banner-log.js";
 import { demoLog, logStubPhaseFixtures, logTodoDockFull, paceSpeakFields, summarizeDevice } from "./demo-log.js";
-import { renderBeforeStep } from "./step-panels.js";
+import { renderBeforeStep } from "./panel-before.js";
 import { probeTodoDocksOnPage } from "./todo-advance.js";
-import { logBannerDom, probeBanner } from "./banner-log.js";
 import { forceCollapsed } from "./view.js";
-import { envFlag } from "../../engine/env.js";
 const quiet = () => envFlag("WAYGRAPH_JSON");
 export async function showBefore(ctx, view) {
     const { stage } = ctx;