waygraph 0.16.0 → 0.16.2

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) {
@@ -431,18 +405,3 @@ export async function hideRing(page) {
     })
         .catch(ignorePageGone);
 }
-/**
- * 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 async function wasJustNarrated(page) {
-    return page
-        .evaluate(() => {
-        const w = window;
-        return typeof w.__wgLastNarrate === "number" && Date.now() - w.__wgLastNarrate < 500;
-    })
-        .catch(() => false);
-}

package/dist/demo/overlay/ui/overlay.css

@@ -215,3 +215,43 @@
   background: #fff; border-radius: var(--wg-radius-lg);
   padding: 10px 18px; box-shadow: var(--wg-shadow-banner);
 }
+
+
+/* The network tab: real page traffic (network-capture.ts) and defineApiBlock's own calls, bottom-left (the one corner
+ * free of the zoom HUD and the typing chip). Hidden until ctx.showNetworkTab(); stays up once shown. In the shared
+ * bundle, not the runner CSS: a navigation rebuilds the panel the moment the shadow root is back, before any later
+ * stylesheet, and without its CSS it painted unstyled and visible, then faded out. */
+#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:var(--wg-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);}

package/dist/demo/stepper/after.js

@@ -1,17 +1,19 @@
-import { hasAuthoredStubAfter, resolveSlides, runStubPhase } from "../narration/narration.js";
+import { envFlag } from "../../engine/env.js";
+import { hasAuthoredStubAfter, 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 { showSlides } 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;
-    await showSlides(ctx, view, result);
     const after = hasAuthoredStubAfter(view.step.block, result) ? await narrateAfter(ctx, view, result) : undefined;
+    if (after)
+        await showSlides(ctx, view, after.phase.slides);
     const applied = after ? await stage.applyPhase(after.phase) : { appliedTodo: { sync: "keep" }, appliedDevice: { sync: "keep" } };
     await renderAfterStep(ctx.page, {
         index: view.index,
@@ -61,20 +63,6 @@ export async function showAfter(ctx, view, result) {
     }
     await ctx.gate.wait();
 }
-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, {
-        title: ctx.title,
-        blockName: view.step.block.name,
-        fast: ctx.pacing.gatesFast,
-        pace: ctx.pacing.demoPace,
-        episodeNumber: view.step.episodeNumber,
-        episodeTitle: view.step.episodeTitle,
-        autoplayMs: ctx.gate.autoplayMs,
-    });
-}
 /** Runs the Block's stubAfter; its rings carry the flow's highlight style and a caption. */
 async function narrateAfter(ctx, view, result) {
     const style = view.step.highlightStyle;
@@ -89,21 +77,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,18 +1,20 @@
-// Before a demo step runs: play the Block's stubBefore narration (rings, todos, device, title, caption) and show the
+// Before a demo step runs: play the Block's stubBefore narration (slides, 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 { showSlides } from "./slides.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;
     const phase = await narrateBefore(ctx, view);
     const { appliedTodo } = await stage.applyPhase(phase, { reapplyDeviceOnKeep: true });
+    await showSlides(ctx, view, phase.slides);
     if (phase.title && String(phase.title).trim())
         ctx.stickyTitle = String(phase.title).trim();
     view.overlayTitle = ctx.stickyTitle || (view.step.episodeTitle && String(view.step.episodeTitle).trim()) || ctx.title || "waygraph demo";

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

@@ -1,5 +1,21 @@
-export declare function demoPaceKind(pace: any): "normal" | "blitz" | "fast" | "slow" | "ms" | "num-slow";
-export declare function paceSpeakFields(pace: any, baseAutoplayMs: any): {
+import type { StubPhaseResult } from "../../engine/stub/stub.js";
+import type { TodoDockState } from "../../engine/stub/todos.js";
+import type { DeviceState } from "../../engine/stub/viewport.js";
+/** What a HIGHLIGHT log line shows: a ring as painted (no selector for a narrated caption). Logged, not checked. */
+type LoggedHighlight = {
+    selector?: string | null | undefined;
+    label?: string | undefined;
+    tone?: string | undefined;
+    color?: string | undefined;
+    focus?: boolean | undefined;
+    zoom?: number | undefined;
+    zoomOut?: boolean | undefined;
+    gesture?: string | undefined;
+    weight?: string | undefined;
+    size?: string | undefined;
+};
+export declare function demoPaceKind(pace: unknown): string;
+export declare function paceSpeakFields(pace: unknown, baseAutoplayMs: number | undefined): {
     pace: import("../../index.js").DemoPace;
     paceBadge: string;
     paceLabel: string;
@@ -19,13 +35,14 @@ export declare const ANSI: {
     magenta: string;
     white: string;
 };
-export declare function ansiPaint(code: any, text: any): string;
-export declare function demoLog(msg: any): void;
+export declare function ansiPaint(code: string, text: unknown): string;
+export declare function demoLog(msg: string): void;
 /** Fixture catch-all: how it was called + value. */
-export declare function demoFixture(kind: any, call: any, value: any): void;
+export declare function demoFixture(kind: string, call: string, value?: unknown): void;
 /** Highlight trigger line: PURPLE · Cart items - Product landed in cart */
-export declare function demoHighlight(h: any, extra: any): void;
-export declare function logStubPhaseFixtures(phaseName: any, phase: any): void;
+export declare function demoHighlight(h: LoggedHighlight | null | undefined, extra?: string): void;
+export declare function logStubPhaseFixtures(phaseName: string, phase: StubPhaseResult | null | undefined): void;
 /** Full todo dump for agents (every group/item id + flags). */
-export declare function logTodoDockFull(dock: any, tag: any): void;
-export declare function summarizeDevice(d: any): string;
+export declare function logTodoDockFull(dock: TodoDockState | null | undefined, tag?: string): void;
+export declare function summarizeDevice(d: DeviceState | null | undefined): string;
+export {};

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

@@ -14,7 +14,7 @@ export function demoPaceKind(pace) {
 }
 export function paceSpeakFields(pace, baseAutoplayMs) {
     const p = normalizeDemoPace(pace);
-    const base = Number.isFinite(baseAutoplayMs) && baseAutoplayMs > 0 ? baseAutoplayMs : 1800;
+    const base = baseAutoplayMs !== undefined && Number.isFinite(baseAutoplayMs) && baseAutoplayMs > 0 ? baseAutoplayMs : 1800;
     return {
         pace: p,
         paceBadge: formatDemoPaceBadge(p, base),
@@ -207,12 +207,10 @@ export function logStubPhaseFixtures(phaseName, phase) {
             }
             : phase.todoSync);
     }
-    const rings = phase.highlights || [];
-    for (let i = 0; i < rings.length; i++) {
-        const h = rings[i];
-        demoFixture(tag, "ctx.ring/highlights[" + i + "]", {
+    phase.highlights.forEach((h, i) => {
+        demoFixture(tag, "ctx.ring[" + i + "]", {
             selector: h.selector,
-            label: h.label || h.caption,
+            label: h.label,
             detail: h.detail,
             tone: h.tone || "planned",
             color: h.color,
@@ -222,10 +220,7 @@ export function logStubPhaseFixtures(phaseName, phase) {
             gesture: h.gesture,
             duration: h.duration,
         });
-    }
-    if (phase.slides && phase.slides.length) {
-        demoFixture(tag, "ctx.slides(...)", { n: phase.slides.length });
-    }
+    });
 }
 function summarizeTodoDock(dock) {
     if (!dock)
@@ -267,8 +262,7 @@ export function logTodoDockFull(dock, tag) {
         demoLog(prefix + "  (no groups)");
         return;
     }
-    for (let gi = 0; gi < groups.length; gi++) {
-        const g = groups[gi];
+    groups.forEach((g, gi) => {
         const gLabel = "group[" +
             gi +
             "]" +
@@ -276,22 +270,11 @@ export function logTodoDockFull(dock, tag) {
             (g.title ? ' title="' + String(g.title).slice(0, 40) + '"' : "") +
             (g.style ? " style=" + g.style : "");
         demoLog(prefix + "  " + gLabel);
-        const items = g.items || [];
-        for (let ti = 0; ti < items.length; ti++) {
-            const t = items[ti];
+        (g.items || []).forEach((t, ti) => {
             const mark = t.done ? "done" : t.current ? "CURRENT" : "pending";
-            demoLog(prefix +
-                "    [" +
-                ti +
-                "] " +
-                mark +
-                (t.id ? " id=" + t.id : "") +
-                ' text="' +
-                String(t.text || "").slice(0, 80) +
-                '"' +
-                (t.detail ? ' detail="' + String(t.detail).slice(0, 40) + '"' : ""));
-        }
-    }
+            demoLog(prefix + "    [" + ti + "] " + mark + (t.id ? " id=" + t.id : "") + ' text="' + String(t.text || "").slice(0, 80) + '"');
+        });
+    });
 }
 export function summarizeDevice(d) {
     if (!d)

package/dist/demo/stepper/interaction-patch.d.ts

@@ -1,3 +1,4 @@
-import type { WgPage } from "../types.js";
+import type { StepperRefs, WgPage } from "../types.js";
+import type { Pacing } from "./pacing.js";
 import type { MemPage } from "../../engine/mem/mem.js";
-export declare function instrumentInteractionHighlighting(page: WgPage, mem: MemPage, slowMo: number, pacing: any, stubBeforeRef: any, todoDockRef: any, deviceRef: any): void;
+export declare function instrumentInteractionHighlighting(page: WgPage, mem: MemPage, slowMo: number, pacing: Pacing, stubBeforeRef: StepperRefs["stubBefore"], todoDockRef: StepperRefs["todoDock"], deviceRef: StepperRefs["device"]): void;

package/dist/demo/stepper/interaction-patch.js

@@ -1,5 +1,5 @@
 import { installOverlay } from "../overlay/overlay.js";
-import { applyHighlightZoom, captionForLocator, dwellMatchedStub, ensureLocatorInView, hideRing, matchStubIndexForLocator, showRing, wasJustNarrated } from "../overlay/rings.js";
+import { applyHighlightZoom, captionForLocator, dwellMatchedStub, ensureLocatorInView, hideRing, matchStubIndexForLocator, showRing } from "../overlay/rings.js";
 import { syncTodoDockAdvance } from "./todo-advance.js";
 import { clickPulseAt, moveCursorTo } from "../overlay/cursor.js";
 import { demoHighlight } from "./demo-log.js";
@@ -70,7 +70,7 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
     const memTrack = { lastKeyName: null, at: 0 };
     const originalGet = mem.get.bind(mem);
     mem.get = (key) => {
-        memTrack.lastKeyName = key && key.name;
+        memTrack.lastKeyName = key.name;
         memTrack.at = Date.now();
         return originalGet(key);
     };
@@ -109,7 +109,7 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
             catch {
                 /* ignore */
             }
-            if (box && !(await wasJustNarrated(page))) {
+            if (box) {
                 // Only trust the "last mem.get()" as THIS fill's source if it
                 // happened recently - a stale read from several actions ago is
                 // more likely unrelated than actually describing this field.
@@ -126,33 +126,28 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
                     await applyHighlightZoom(page, stub.selector, stub.zoom, stub.zoomOut);
                 }
                 demoHighlight({
-                    selector: stub && stub.selector,
+                    selector: stub?.selector,
                     label: cap.label,
-                    tone: cap.tone || (stub && stub.tone) || "planned",
-                    color: stub && stub.color,
-                    focus: !!(stub && stub.focus),
-                    zoom: stub && stub.zoom,
-                    zoomOut: stub && stub.zoomOut,
-                    gesture: stub && stub.gesture,
+                    tone: cap.tone || (stub?.tone) || "planned",
+                    color: stub?.color,
+                    focus: !!(stub?.focus),
+                    zoom: stub?.zoom,
+                    zoomOut: stub?.zoomOut,
+                    gesture: stub?.gesture,
                     weight: cap.weight,
                     size: cap.size,
                 }, "fill");
                 await showRing(page, box, cap.label, cap.tone, {
                     size: cap.size,
                     weight: cap.weight,
-                    selector: stub && stub.selector ? stub.selector : undefined,
-                    focus: !!(stub && stub.focus),
+                    selector: stub?.selector,
+                    focus: !!(stub?.focus),
                 });
                 await dwellMatchedStub(page, locator, stubs, pacing);
                 await new Promise((res) => setTimeout(res, skipTheater() ? 0 : 200));
                 if (cap && cap.label)
                     typeLabel = String(cap.label).slice(0, 40);
             }
-            else if (box) {
-                // Ring/caption already handled by narrate() - still move the
-                // cursor there, just skip re-showing the ring with a generic label.
-                await moveCursorTo(page, box, cursorMs(200));
-            }
             await page
                 .evaluate((label) => {
                 if (window.__wgSetTypingBadge)
@@ -191,8 +186,7 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
             // own click scroll is instant and reads as a teleport under --fast.
             await ensureLocatorInView(locator, { instant: skipTheater() });
             const box = await locator.boundingBox();
-            const narrated = box ? await wasJustNarrated(page) : false;
-            if (box && !narrated) {
+            if (box) {
                 let fallback = "click";
                 try {
                     const text = (await locator.textContent())?.trim();
@@ -218,22 +212,22 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
                     await applyHighlightZoom(page, stub.selector, stub.zoom, stub.zoomOut);
                 }
                 demoHighlight({
-                    selector: stub && stub.selector,
+                    selector: stub?.selector,
                     label: cap.label,
-                    tone: cap.tone || (stub && stub.tone) || "planned",
-                    color: stub && stub.color,
-                    focus: !!(stub && stub.focus),
-                    zoom: stub && stub.zoom,
-                    zoomOut: stub && stub.zoomOut,
-                    gesture: stub && stub.gesture,
+                    tone: cap.tone || (stub?.tone) || "planned",
+                    color: stub?.color,
+                    focus: !!(stub?.focus),
+                    zoom: stub?.zoom,
+                    zoomOut: stub?.zoomOut,
+                    gesture: stub?.gesture,
                     weight: cap.weight,
                     size: cap.size,
                 }, "click");
                 await showRing(page, box, cap.label, cap.tone, {
                     size: cap.size,
                     weight: cap.weight,
-                    selector: stub && stub.selector ? stub.selector : undefined,
-                    focus: !!(stub && stub.focus),
+                    selector: stub?.selector,
+                    focus: !!(stub?.focus),
                 });
                 await dwellMatchedStub(page, locator, stubs, pacing);
                 // "pop for a few seconds" - the user's own phrase, matching the
@@ -241,12 +235,6 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
                 // services/help-center-clip-engine's video-pipeline.
                 await new Promise((res) => setTimeout(res, clickPrePop()));
             }
-            else if (box) {
-                // Ring/caption already handled by narrate() - still move the
-                // cursor + pulse the click point, just skip re-showing the ring.
-                clickPoint = await moveCursorTo(page, box, cursorMs(200));
-                clickTone = "planned";
-            }
             if (clickPoint) {
                 await clickPulseAt(page, clickPoint.x, clickPoint.y, clickTone);
                 // clickPulseAt only triggers the CSS animation class - it doesn't

package/dist/demo/stepper/panel-after.d.ts

@@ -0,0 +1,17 @@
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+import type { DemoPace } from "../../engine/stub/pace.js";
+import type { ResolvedHighlight } from "../../engine/stub/ring.js";
+import type { TodoDockState } from "../../engine/stub/todos.js";
+import type { Ref, WgPage } from "../types.js";
+import { type PanelTodos, type StepPanelInfo } from "./step-panels.js";
+/** The panel after a step: the Checkpoint it resolved to, the rings to cycle, and whether it was the last step. */
+export interface AfterPanelInfo extends StepPanelInfo, PanelTodos {
+    result: Checkpoint<string>;
+    resultTag: string;
+    highlights: readonly ResolvedHighlight[];
+    gatesFast?: boolean | undefined;
+    isLast: boolean;
+    pace?: DemoPace | undefined;
+    todoDockRef?: Ref<TodoDockState | undefined> | undefined;
+}
+export declare function renderAfterStep(page: WgPage, info: AfterPanelInfo): Promise<void>;