waygraph 0.16.0 → 0.16.2

package/dist/demo/narration/narration.js

@@ -3,7 +3,7 @@ import { applyDefaultZoom, applyDefaultZoomOut, readStubRaw, resolvePhaseMap } f
 import { buildTodoDock, normalizeTodoStyle, normalizeTodos } from "./todo-dock.js";
 import { resolveDeviceState } from "./device.js";
 /**
- * Run an open stub lifecycle (preferred) or resolve a static slot map.
+ * Runs a Block's stub for one phase and returns what it painted.
  * Returns rings + episode fixtures (todos / todoIndex / zoom).
  *
  * @example
@@ -27,6 +27,9 @@ export async function runStubPhase(block, phase, opts) {
             throw new Error(`${block.name}: its ${phase} stub threw: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
         }
     }
+    if (phase === "stubOnError" && bag.slides?.length) {
+        throw new Error(`${block.name}: its stubOnError stub set slides; slides play before or after a step (stubBefore / stubAfter), not on its failure`);
+    }
     let highlights = applyDefaultZoom(resolvePhaseMap(bag.highlights), bag.zoom);
     highlights = applyDefaultZoomOut(highlights, bag.zoomOut);
     const todoDock = bag.hideTodos
@@ -95,6 +98,7 @@ export async function runStubPhase(block, phase, opts) {
         // Boolean, not string - "" isn't a state here, so a plain undefined-check (like zoom/title)
         // is enough; false is real ("author called hideNetworkTab()") and must still be forwarded.
         ...(bag.networkTabVisible !== undefined ? { networkTabVisible: bag.networkTabVisible } : {}),
+        slides: [...(bag.slides ?? [])],
         ...(bag.todoPos !== undefined ? { todoPos: bag.todoPos } : {}),
         ...(bag.todoDockUi !== undefined ? { todoDockUi: bag.todoDockUi } : {}),
         ...(bag.todoParallel === true ? { todoParallel: true } : {}),
@@ -118,22 +122,6 @@ export function resolveHighlightSlots(block, phase, opts) {
     }
     return applyDefaultZoom(resolvePhaseMap(bag.highlights), bag.zoom);
 }
-/** Resolve multi-step yap slides from `instruction.slides` (function form allowed). */
-export function resolveSlides(block, opts) {
-    const instr = block.instruction;
-    let raw = instr.slides;
-    if (typeof raw === "function") {
-        try {
-            raw = raw(opts?.out ?? { __state: "" });
-        }
-        catch {
-            raw = [];
-        }
-    }
-    if (!Array.isArray(raw))
-        return [];
-    return raw.filter((s) => s && typeof s.caption === "string" && s.caption.length > 0);
-}
 function stubPhaseLooksAuthored(block, phase) {
     return readStubRaw(block, phase) !== undefined;
 }

package/dist/demo/narration/stub-ctx.js

@@ -25,9 +25,6 @@ export function createStubCtx(bag, opts) {
         mem: opts.mem,
         out: opts.out,
         error: opts.error,
-        highlights(slots) {
-            bag.highlights = { ...(slots || {}) };
-        },
         ring(id, stub) {
             bag.highlights = { ...bag.highlights, [id]: stub };
         },
@@ -134,6 +131,9 @@ export function createStubCtx(bag, opts) {
         caption(text) {
             bag.caption = String(text ?? "");
         },
+        slides(slides) {
+            bag.slides = slides;
+        },
         hideCaption() {
             bag.caption = "";
         },

package/dist/demo/narration/todo-dock.d.ts

@@ -31,11 +31,11 @@ export declare function buildTodoDock(opts: {
  * - keep: author omitted todos — preserve previous dock (do not wipe)
  */
 export declare function applyTodoPhase(prev: TodoDockState | undefined, phase: {
-    todoSync?: "set" | "clear" | "keep";
-    todoDock?: TodoDockState;
-    todos?: WaygraphTodoItem[];
-    todoPos?: "left" | "right";
-    todoId?: string;
+    todoSync?: "set" | "clear" | "keep" | undefined;
+    todoDock?: TodoDockState | undefined;
+    todos?: WaygraphTodoItem[] | undefined;
+    todoPos?: "left" | "right" | undefined;
+    todoId?: string | undefined;
 }): {
     dock: TodoDockState | undefined;
     sync: "set" | "clear" | "keep";

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

@@ -1,12 +1,19 @@
 import type { WgBox, WgPage } from "../types.js";
+/** A touch swipe: which way, its caption (plus an optional hint) and how long it takes. */
+export interface SwipeTrailOptions {
+    dir?: "left" | "right" | "up" | "down";
+    label?: string;
+    hint?: string;
+    ms?: number;
+}
 export declare function moveCursorTo(page: WgPage, box: WgBox, ms: number): Promise<{
     x: number;
     y: number;
 }>;
-export declare function clickPulseAt(page: WgPage, x: any, y: any, tone: any): Promise<void>;
+export declare function clickPulseAt(page: WgPage, x: number, y: number, tone?: string): Promise<void>;
 /**
  * Touch swipe trail (mobile/tablet). dir: left|right|up|down.
  * Returns after the trail animation completes.
  * Self-contained when overlay helper is not installed yet (device runs before panel).
  */
-export declare function playSwipeTrail(page: WgPage, opts: any): Promise<void>;
+export declare function playSwipeTrail(page: WgPage, opts?: SwipeTrailOptions): Promise<void>;

package/dist/demo/overlay/cursor.js

@@ -135,7 +135,7 @@ export async function playSwipeTrail(page, opts) {
         hint: o.hint || "",
         ms: o.ms || 720,
     })
-        .catch(() => 0);
+        .catch(ignorePageGone);
     const n = Number(waitMs) || 0;
     if (n > 0)
         await new Promise((r) => setTimeout(r, n));

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,
@@ -275,12 +275,6 @@ export function installCore({ title, favicon, bannerPos, todoPos, envAutoplay, t
         pulse.classList.add("wg-pulse");
     };
     window.__wgHideRing = (opts) => {
-        // While a narrate() call owns the ring (mid multi-step action),
-        // the auto-highlight click/fill patches' own end-of-step hide is
-        // a no-op - narrate() itself clears it once the WHOLE wrapped
-        // action finishes, not just its first sub-step.
-        if (window.__wgNarrateOwnsRing)
-            return;
         if (window.__wgStopRingFollow)
             window.__wgStopRingFollow();
         const ring = __wgById("wg-ring");

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-css.js

@@ -1,7 +1,7 @@
 // CSS for the runner-only chrome (step panel, chips) and for the host page (device stage), next to the shared bundle in ui/css.
 import { SURFACE } from "./ui/tokens.js";
 // ---------------------------------------------------------------------------
-// WAYGRAPH_STEP=1 - human-verification overlay: one Block at a time, a
+// The demo stepper (waygraph demo) - human-verification overlay: one Block at a time, a
 // browser-injected panel showing/editing that Block's MemKeys, a "Run this
 // step" gate, then a highlight ring over whatever its own verify Traits just
 // confirmed, then a "Next" gate before moving on. Ring CSS borrowed from
@@ -114,60 +114,6 @@ export const RUNNER_EXTRA_CSS =
     "#wg-zoom-badge .wg-zoom-ico svg{width:14px;height:14px;display:block;}" +
     "#wg-zoom-badge .wg-zoom-val{color:#c9a6ff;font-variant-numeric:tabular-nums;font-weight:800;min-width:3.2em;}" +
     "#wg-zoom-badge[data-zoomed=\"1\"]{border-color:#7C3AED;}" +
-    // Network-tab overlay (real page traffic via network-capture.js + defineApiBlock's own
-    // page.request calls) - bottom-left, the one corner free of the zoom HUD (bottom-right) and the
-    // typing chip (bottom-center). Persistent (does not auto-fade) once any entry exists - this is a
-    // real Postman/DevTools-style inspector meant to be reviewed, not a flash-and-gone toast.
-    "#wg-network-log{position:fixed;z-index:2147483646;bottom:14px;left:14px;min-width:260px;" +
-    "max-width:min(92vw,420px);max-height:min(60vh,420px);display:flex;flex-direction:column;" +
-    "border-radius:10px;background:" + SURFACE + ";color:#f0e8ff;border:1px solid rgba(124,58,237,.45);" +
-    "box-shadow:0 8px 22px rgba(0,0,0,.4);font:12px/1.4 ui-monospace,\"SF Mono\",Consolas,monospace;" +
-    "opacity:0;transform:translateY(8px);transition:opacity .25s ease,transform .25s ease;overflow:hidden;}" +
-    "#wg-network-log.wg-in{opacity:1;transform:translateY(0);}" +
-    "#wg-network-log.wg-net-collapsed .wg-net-list{display:none;}" +
-    "#wg-network-log .wg-net-header{display:flex;align-items:center;gap:6px;padding:8px 10px;" +
-    "border-bottom:1px solid rgba(124,58,237,.25);cursor:default;flex:0 0 auto;}" +
-    "#wg-network-log .wg-net-title{font:700 10px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
-    "letter-spacing:.06em;text-transform:uppercase;flex:1 1 auto;}" +
-    "#wg-network-log .wg-net-count{font:700 10px/1.2 system-ui,sans-serif;color:#9CA3AF;" +
-    "background:rgba(124,58,237,.22);border-radius:999px;padding:1px 7px;}" +
-    "#wg-network-log .wg-net-collapse{flex:0 0 auto;width:18px;height:18px;border-radius:5px;border:none;" +
-    "background:rgba(124,58,237,.28);color:#e8dcff;font:700 13px/1 system-ui,sans-serif;cursor:pointer;" +
-    "pointer-events:auto;}" +
-    "#wg-network-log .wg-net-collapse:hover{background:rgba(124,58,237,.42);}" +
-    "#wg-network-log .wg-net-list{list-style:none;margin:0;padding:6px 8px;display:flex;" +
-    "flex-direction:column;gap:2px;overflow-y:auto;pointer-events:auto;}" +
-    "#wg-network-log .wg-net-row{display:flex;align-items:baseline;gap:7px;opacity:0;padding:3px 4px;" +
-    "border-radius:5px;cursor:pointer;transform:translateX(-4px);transition:opacity .2s ease,transform .2s ease;}" +
-    "#wg-network-log .wg-net-row:hover,#wg-network-log .wg-net-row.wg-net-open{background:rgba(124,58,237,.18);}" +
-    "#wg-network-log .wg-net-row.wg-in{opacity:1;transform:translateX(0);}" +
-    "#wg-network-log .wg-net-method{flex:0 0 auto;font-weight:800;font-size:10px;min-width:38px;}" +
-    "#wg-network-log .wg-net-method-get{color:#3B82F6;}" +
-    "#wg-network-log .wg-net-method-post{color:#22C55E;}" +
-    "#wg-network-log .wg-net-method-put{color:#F97316;}" +
-    "#wg-network-log .wg-net-method-delete{color:#EF4444;}" +
-    "#wg-network-log .wg-net-method-other{color:#9CA3AF;}" +
-    "#wg-network-log .wg-net-path{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;" +
-    "white-space:nowrap;color:#e0e0f0;}" +
-    "#wg-network-log .wg-net-status{flex:0 0 auto;font-weight:700;color:#22C55E;}" +
-    "#wg-network-log .wg-net-row[data-ok=\"0\"] .wg-net-status{color:#EF4444;}" +
-    "#wg-network-log .wg-net-ms{flex:0 0 auto;color:#9CA3AF;font-size:10px;}" +
-    "#wg-network-log .wg-net-detail{list-style:none;background:rgba(0,0,0,.28);border-radius:6px;" +
-    "padding:8px;margin:2px 0 6px;}" +
-    "#wg-network-log .wg-net-detail-section{margin-bottom:8px;}" +
-    "#wg-network-log .wg-net-detail-section:last-child{margin-bottom:0;}" +
-    "#wg-network-log .wg-net-detail-section h4{margin:0 0 4px;font:700 9px/1.2 system-ui,sans-serif;" +
-    "color:#9CA3AF;letter-spacing:.06em;text-transform:uppercase;}" +
-    "#wg-network-log .wg-net-headers{width:100%;border-collapse:collapse;font-size:11px;}" +
-    "#wg-network-log .wg-net-headers td{padding:1px 6px 1px 0;vertical-align:top;word-break:break-all;}" +
-    "#wg-network-log .wg-net-headers td:first-child{color:#c9a6ff;white-space:nowrap;}" +
-    "#wg-network-log .wg-net-body{margin:0;font-size:11px;white-space:pre-wrap;word-break:break-all;" +
-    "max-height:160px;overflow-y:auto;color:#e0e0f0;}" +
-    "#wg-network-log .wg-net-curl{color:#7dd3fc;}" +
-    "#wg-network-log .wg-net-empty{font-size:11px;color:#6b7280;font-style:italic;}" +
-    "#wg-network-log .wg-net-copy{margin-top:5px;padding:3px 9px;border-radius:5px;border:1px solid rgba(124,58,237,.5);" +
-    "background:rgba(124,58,237,.22);color:#e8dcff;font:700 10px system-ui,sans-serif;cursor:pointer;}" +
-    "#wg-network-log .wg-net-copy:hover{background:rgba(124,58,237,.38);}" +
     // Typing chip (method fills: username / password / etc.)
     "#wg-typing-badge{position:fixed;z-index:2147483646;bottom:88px;left:50%;transform:translateX(-50%);" +
     "display:flex;align-items:center;gap:8px;padding:8px 14px;" +

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/overlay.js

@@ -25,6 +25,9 @@ import { ignorePageGone } from "../../engine/page-gone.js";
 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);
+    // Runner-only chrome (step panel, zoom/typing/device chips) - separate key, no collision. First, so nothing below
+    // builds chrome ahead of its CSS (an element painted unstyled for a moment, then restyled).
+    await page.evaluate(([css, key]) => __wgCss(css, key), [RUNNER_EXTRA_CSS, "wg-runner-css"]).catch(ignorePageGone);
     // 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.
@@ -46,8 +49,6 @@ export async function installOverlay(page, title, ui, caption, networkTabVisible
     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

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,26 +12,42 @@ 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
- * 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>;