waygraph 0.16.1 → 0.16.2

package/dist/cli/commands/codemod-stubs.js

@@ -4,7 +4,9 @@
 // aliases (`banner`, `bannerPos`, `clearDevice`, `clearTodos`, `landscape`, `portrait`, `todoDockFull`) become the
 // names they stood for. A stub written as a slot map (`{ email: { selector, label } }`) becomes a function of
 // `ctx.ring` calls, and a stub set in a `define*Block({ ... })` (options or instruction) moves out to a chained
-// `.stubBefore(...)` on the Block. Works on the TypeScript AST (ts-morph).
+// `.stubBefore(...)` on the Block; a Block's `slides` become `ctx.slides(...)` in its chained `.stubAfter(...)`;
+// `ctx.highlights({ a: ring })` becomes one `ctx.ring("a", ring)` per ring; `narrate(locator, caption, action)` in an
+// `act` becomes the action, reported so the caption can move to a stubBefore ring. Works on the TypeScript AST (ts-morph).
 import { Node, SyntaxKind } from "ts-morph";
 const RENAMED = {
     banner: (a) => `title(${a.join(", ")})`,
@@ -127,7 +129,7 @@ function convertSlotMaps(sf) {
     }
     return changed;
 }
-/** `defineXBlock({ ..., stubBefore: fn })` (or in its instruction) -> `defineXBlock({ ... }).stubBefore(fn)`. */
+/** `defineXBlock({ ..., stubBefore: fn, slides })` (or in its instruction) -> `defineXBlock({ ... }).stubBefore(fn).stubAfter(slides)`. */
 function hoistDefinitionStubs(sf) {
     let changed = false;
     for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
@@ -141,9 +143,17 @@ function hoistDefinitionStubs(sf) {
         if (Node.isPropertyAssignment(instruction) && Node.isObjectLiteralExpression(instruction.getInitializer()))
             holders.push(instruction.getInitializer());
         const chained = [];
+        let slides;
         for (const holder of holders) {
             for (const prop of holder.getProperties()) {
                 const name = Node.isPropertyAssignment(prop) || Node.isMethodDeclaration(prop) ? prop.getName() : "";
+                if (name === "slides" && Node.isPropertyAssignment(prop)) {
+                    const init = prop.getInitializerOrThrow();
+                    // `slides: (out) => [...]` read the Checkpoint the step reached; in stubAfter that is ctx.out.
+                    slides = Node.isArrowFunction(init) || Node.isFunctionExpression(init) ? `(${init.getText()})(ctx.out!)` : init.getText();
+                    prop.remove();
+                    continue;
+                }
                 if (!PHASES.has(name))
                     continue;
                 let fn;
@@ -157,6 +167,15 @@ function hoistDefinitionStubs(sf) {
                 prop.remove();
             }
         }
+        if (slides !== undefined) {
+            const after = chained.findIndex((c) => c.startsWith(".stubAfter("));
+            if (after < 0)
+                chained.push(`.stubAfter((ctx) => ctx.slides(${slides}))`);
+            else {
+                const fn = chained[after].slice(".stubAfter(".length, -1);
+                chained[after] = `.stubAfter(async (ctx) => {\n  await (${fn})(ctx);\n  ctx.slides(${slides});\n})`;
+            }
+        }
         if (chained.length) {
             call.replaceWithText(call.getText() + chained.join(""));
             changed = true;
@@ -164,6 +183,71 @@ function hoistDefinitionStubs(sf) {
     }
     return changed;
 }
+/** `ctx.highlights({ a: ring, b: ring })` -> `ctx.ring("a", ring); ctx.ring("b", ring);`, one call at a time. */
+function convertHighlights(sf, problems) {
+    let changed = false;
+    const skipped = new Set();
+    for (;;) {
+        // Raw text replacement forgets the file's nodes, so look the next call up again each time.
+        const statement = sf.getDescendantsOfKind(SyntaxKind.ExpressionStatement).find((st) => {
+            const c = ctxCall(st);
+            return c && c.method === "highlights" && !skipped.has(st.getStart()) && isStubCtx(c.call, c.receiver);
+        });
+        if (!statement)
+            return changed;
+        const c = ctxCall(statement);
+        const map = c.call.getArguments()[0];
+        if (!Node.isObjectLiteralExpression(map)) {
+            problems.push({ line: c.call.getStartLineNumber(), reason: "ctx.highlights(...) was removed and its argument is not an object literal: call ctx.ring(id, ring) for each ring" });
+            skipped.add(statement.getStart());
+            continue;
+        }
+        // Each ring keeps its own lines, moved to the statement's indent (replaceWithText would re-indent them).
+        const column = (n) => n.getStart() - n.getStartLinePos();
+        const indent = " ".repeat(column(statement));
+        const rings = map.getProperties().flatMap((p) => {
+            if (!Node.isPropertyAssignment(p))
+                return [];
+            const from = column(p);
+            const value = p.getInitializerOrThrow().getText().split("\n").map((l, n) => (n === 0 ? l : indent + l.slice(Math.min(from, l.search(/\S|$/))))).join("\n");
+            return [`${c.receiver}.ring(${JSON.stringify(p.getName().replace(/^["']|["']$/g, ""))}, ${value});`];
+        });
+        sf.replaceText([statement.getStart(), statement.getEnd()], rings.join("\n" + indent));
+        changed = true;
+    }
+}
+/**
+ * `narrate(locator, caption, () => action)` in an `act` -> just the action. The caption was narration inside the
+ * Block; it belongs in a `stubBefore` ring where the flow uses the Block, which the codemod can't place, so it is
+ * reported.
+ */
+function unwrapNarrate(sf, problems) {
+    let changed = false;
+    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression).reverse()) {
+        if (call.wasForgotten() || call.getExpression().getText() !== "narrate" || call.getArguments().length !== 3)
+            continue;
+        const [, captionNode, action] = call.getArguments();
+        const caption = captionNode.getText();
+        const line = call.getStartLineNumber();
+        let body = `(${action.getText()})()`;
+        if (Node.isArrowFunction(action) && !Node.isBlock(action.getBody()))
+            body = action.getBody().getText();
+        call.replaceWithText(body);
+        problems.push({ line, reason: `narrate(...) was removed; its caption ${caption} is gone: ring the element in a stubBefore where the flow uses this Block` });
+        changed = true;
+    }
+    if (changed) {
+        for (const decl of sf.getImportDeclarations()) {
+            const spec = decl.getNamedImports().find((n) => n.getName() === "narrate");
+            if (!spec)
+                continue;
+            spec.remove();
+            if (decl.getNamedImports().length === 0 && !decl.getDefaultImport() && !decl.getNamespaceImport())
+                decl.remove();
+        }
+    }
+    return changed;
+}
 /** Rewrites the old stub forms in every file; returns the files it changed and the calls left for a person. */
 export function convertStubs(project) {
     const changed = [];
@@ -171,6 +255,10 @@ export function convertStubs(project) {
     for (const sf of project.getSourceFiles()) {
         const left = [];
         let touched = hoistDefinitionStubs(sf);
+        if (unwrapNarrate(sf, left))
+            touched = true;
+        if (convertHighlights(sf, left))
+            touched = true;
         if (convertSlotMaps(sf))
             touched = true;
         for (const block of sf.getDescendantsOfKind(SyntaxKind.Block).reverse()) {

package/dist/cli/run-chain.js

@@ -92,12 +92,12 @@ export async function runChainAuto(projectDir, fromTag, toTag) {
     const graph = await discoverGraph(projectDir);
     const path = findBlockPath(graph, fromTag, toTag);
     if (!path) {
-        console.error(`waygraph chain auto: no Block path from "${fromTag}" to "${toTag}" in the discovered graph`);
+        console.error(`waygraph auto --blocks: no Block path from "${fromTag}" to "${toTag}" in the discovered graph`);
         process.exitCode = 1;
         return;
     }
     const spec = path.join(" then ");
-    console.error(`waygraph chain auto: ${fromTag} -> ${toTag} via ${spec}`);
+    console.error(`waygraph auto --blocks: ${fromTag} -> ${toTag} via ${spec}`);
     if (!envString("WAYGRAPH_BASE_URL")) {
         const resolved = await resolveBaseUrl(projectDir);
         if (resolved)

package/dist/cli/util.js

@@ -4,7 +4,7 @@ import { spawn } from "node:child_process";
 // ---------------------------------------------------------------------------
 // `try` - a bundled, self-contained showcase. No .flow.ts to write, no
 // scenario to design - copies a small real Flow (nav/action Blocks, Trait
-// verify, narrate()) into the target project and runs it in step mode
+// verify, ctx stubs) into the target project and runs it in step mode
 // against a public demo site, so a curious dev sees the real overlay/panel
 // experience in under a minute, then gets pointed at the plain waygraph
 // source that produced it.

package/dist/demo/narration/demo-pace.d.ts

@@ -29,7 +29,7 @@ export declare function formatDemoPaceBadge(pace: DemoPace, baseAutoplayMs?: num
  */
 export declare function formatDemoPaceLabel(pace: DemoPace, baseAutoplayMs?: number): string;
 /**
- * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
+ * Resolve min dwell ms for any fixture (a stub ring or a yap slide),
  * or `null` when duration is unset (caller keeps its default timing).
  *
  * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`

package/dist/demo/narration/demo-pace.js

@@ -150,7 +150,7 @@ export function formatDemoPaceLabel(pace, baseAutoplayMs = 1800) {
     return `pace normal (1x, ~${gate}ms gates)`;
 }
 /**
- * Resolve min dwell ms for any fixture (stub / flow fixture / yap slide),
+ * Resolve min dwell ms for any fixture (a stub ring or a yap slide),
  * or `null` when duration is unset (caller keeps its default timing).
  *
  * Authoring wins: an explicit slow/numeric pace is not crushed by CLI `--fast`

package/dist/demo/narration/merge.d.ts

@@ -4,7 +4,7 @@ import type { SomeBlock } from "../../engine/block/block.js";
 import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
 export declare function applyDefaultZoom(slots: ResolvedHighlight[], defaultZoom?: number): ResolvedHighlight[];
 export declare function applyDefaultZoomOut(slots: ResolvedHighlight[], defaultZoomOut?: boolean): ResolvedHighlight[];
-/** A stub phase's slot map as an ordered list of resolved highlights. */
+/** A stub phase's rings (by id, as ctx.ring set them) as an ordered list of resolved highlights. */
 export declare function resolvePhaseMap(phaseMap: HighlightStubPhase): ResolvedHighlight[];
 /** The stub a Block's flow chained for this phase, if any. */
 export declare function readStubRaw(block: SomeBlock, phase: HighlightStubPhaseName): StubLifecycleFn<Checkpoint<string>> | undefined;

package/dist/demo/narration/merge.js

@@ -40,7 +40,7 @@ export function applyDefaultZoomOut(slots, defaultZoomOut) {
         return slots;
     return slots.map((h) => h.zoomOut !== undefined ? h : { ...h, zoomOut: defaultZoomOut });
 }
-/** A stub phase's slot map as an ordered list of resolved highlights. */
+/** A stub phase's rings (by id, as ctx.ring set them) as an ordered list of resolved highlights. */
 export function resolvePhaseMap(phaseMap) {
     const phaseKeys = Object.keys(phaseMap);
     const allNumeric = phaseKeys.length > 0 && phaseKeys.every((k) => Number.isFinite(Number(k)) && String(Number(k)) === k);

package/dist/demo/narration/narration.d.ts

@@ -1,10 +1,10 @@
 import type { HighlightStubPhaseName, StubPhaseResult } from "../../engine/stub/stub.js";
-import type { ResolvedHighlight, WaygraphSlide } from "../../engine/stub/ring.js";
+import type { ResolvedHighlight } from "../../engine/stub/ring.js";
 import type { SomeBlock } from "../../engine/block/block.js";
 import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
 import type { MemPage } from "../../engine/mem/mem.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
@@ -23,10 +23,6 @@ export declare function runStubPhase(block: SomeBlock, phase: HighlightStubPhase
 export declare function resolveHighlightSlots(block: SomeBlock, phase: HighlightStubPhaseName, opts?: {
     out?: Checkpoint<string>;
 }): ResolvedHighlight[];
-/** Resolve multi-step yap slides from `instruction.slides` (function form allowed). */
-export declare function resolveSlides(block: SomeBlock, opts?: {
-    out?: Checkpoint<string>;
-}): WaygraphSlide[];
 /**
  * True when the block authored stubAfter (lifecycle fn or slots).
  * When true, demo should not use verify-trait fallback.

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

@@ -275,12 +275,6 @@ export function installCore({ envAutoplay, todoDockUi }) {
         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/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.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

@@ -51,11 +51,3 @@ export declare function captionForLocator(page: WgPage, locator: Locator, stubs:
 }>;
 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>;

package/dist/demo/overlay/rings.js

@@ -405,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,18 +1,19 @@
 import { envFlag } from "../../engine/env.js";
-import { hasAuthoredStubAfter, resolveSlides, runStubPhase } from "../narration/narration.js";
+import { hasAuthoredStubAfter, runStubPhase } from "../narration/narration.js";
 import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narration/style.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 { showSlides } from "./slides.js";
 import { extractVerifyHighlights } from "./step-panels.js";
 import { forceCollapsed } from "./view.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,
@@ -62,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, {
-        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;

package/dist/demo/stepper/before.js

@@ -1,4 +1,4 @@
-// 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";
@@ -6,6 +6,7 @@ import { applyHighlightStyleDefaults, formatHighlightCaption } from "../narratio
 import { logBannerDom, probeBanner } from "./banner-log.js";
 import { demoLog, logStubPhaseFixtures, logTodoDockFull, paceSpeakFields, summarizeDevice } from "./demo-log.js";
 import { renderBeforeStep } from "./panel-before.js";
+import { showSlides } from "./slides.js";
 import { probeTodoDocksOnPage } from "./todo-advance.js";
 import { forceCollapsed } from "./view.js";
 const quiet = () => envFlag("WAYGRAPH_JSON");
@@ -13,6 +14,7 @@ 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.js

@@ -208,7 +208,7 @@ export function logStubPhaseFixtures(phaseName, phase) {
             : phase.todoSync);
     }
     phase.highlights.forEach((h, i) => {
-        demoFixture(tag, "ctx.ring/highlights[" + i + "]", {
+        demoFixture(tag, "ctx.ring[" + i + "]", {
             selector: h.selector,
             label: h.label,
             detail: h.detail,

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";
@@ -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.
@@ -148,11 +148,6 @@ export function instrumentInteractionHighlighting(page, mem, slowMo, pacing, stu
                 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();
@@ -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.js

@@ -21,7 +21,7 @@ export async function renderAfterStep(page, info) {
     // Cycle through EVERY declared/recovered highlight in order, each shown
     // long enough to actually register - "it highlights something [...] then
     // it highlights something [else] and next," not just the first one.
-    // duration / fastMode on stubAfter (or flow fixtures) override the default
+    // duration / fastMode on stubAfter rings override the default
     // 900ms / 200ms holds when set.
     await cycleHighlightRings(page, highlights, gatesFast, {
         pace: info.pace,

package/dist/demo/stepper/slides.d.ts

@@ -1,6 +1,7 @@
 import type { WgPage } from "../types.js";
 import { type WaygraphSlide } from "../../engine/stub/ring.js";
 import type { DemoPace } from "../../engine/stub/pace.js";
+import type { StepperContext, StepView } from "./view.js";
 /** Where the slides sit (title, Block, episode) and how fast they advance. */
 export interface SlidesOptions {
     title?: string | undefined;
@@ -21,3 +22,5 @@ export interface SlidesOptions {
  * doing nothing. In-page data-wg-acked + autoplay poll is the source of truth.
  */
 export declare function presentSlides(page: WgPage, slides: readonly WaygraphSlide[], opts?: SlidesOptions): Promise<void>;
+/** Plays a stub phase's `ctx.slides(...)` for the step on screen, in the flow's highlight style. */
+export declare function showSlides(ctx: StepperContext, view: StepView, slides: readonly WaygraphSlide[]): Promise<void>;