waygraph 0.15.53 → 0.16.0

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

@@ -0,0 +1,127 @@
+import { addNetworkEntry, clearNetworkLog } from "./inpage/network.js";
+import { setApiCallRecorder } from "../../engine/run/hooks.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+// Fetch/XHR/navigation only - a real page can fire dozens of image/font/stylesheet requests per
+// second, which would flood a panel meant to answer "what API calls did this page just made".
+const RELEVANT_TYPES = new Set(["xhr", "fetch", "document"]);
+// Response bodies this size or smaller, and only if they look text-ish, get captured for the
+// detail view - a multi-MB image/video response has no business being buffered into page memory
+// just because a demo happened to be running.
+const MAX_BODY_BYTES = 200_000;
+// Matches the in-page addNetworkEntry's own cap (network.js) - the Node-side history this backs
+// stays in sync with what the panel can actually show.
+const MAX_HISTORY = 30;
+/**
+ * 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
+ * lives on the Playwright `Page` object (Node side), which survives navigation - the panel DOM
+ * (page side, inside the shadow root) does not, and gets wiped on every real navigation. Without
+ * this, the "network tab" reset to empty on every step that navigated - not what a persistent
+ * Network tab is supposed to do.
+ */
+export function recordNetworkEntry(page, entry) {
+    page.__wgNetworkHistory = page.__wgNetworkHistory || [];
+    page.__wgNetworkHistory.push(entry);
+    while (page.__wgNetworkHistory.length > MAX_HISTORY)
+        page.__wgNetworkHistory.shift();
+    return page.evaluate(addNetworkEntry, entry).catch(ignorePageGone);
+}
+/**
+ * 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
+ * resync (banner/todos/device), and BEFORE that step's own network activity can add anything new
+ * (installOverlay runs at the very start of a step, so this is always true in practice - no
+ * interleaving race between "replay old" and "record new" to reason about). A no-op when there's
+ * no history yet, or the panel already shows exactly as many entries as history has (nothing was
+ * wiped this step). Otherwise clears and rebuilds from scratch, in order - simpler and more
+ * obviously correct than trying to diff/append just the "missing" ones.
+ */
+export async function restoreNetworkHistory(page) {
+    const history = page.__wgNetworkHistory;
+    if (!history || history.length === 0)
+        return;
+    // page.__wgNetworkNeedsRestore is set by installNetworkCapture's own framenavigated listener -
+    // skip the page.evaluate() round-trip entirely (an extra one on EVERY step otherwise, since this
+    // runs from installOverlay every step) unless a real navigation actually happened since the last
+    // successful restore. A real, caught perf regression: this used to always evaluate() a shown-count
+    // check first, which measurably slowed down every step of every test that had ever captured any
+    // traffic at all, not just ones that navigate.
+    if (!page.__wgNetworkNeedsRestore)
+        return;
+    page.__wgNetworkNeedsRestore = false;
+    await page.evaluate(clearNetworkLog).catch(ignorePageGone);
+    for (const entry of history) {
+        await page.evaluate(addNetworkEntry, entry).catch(ignorePageGone);
+    }
+}
+export function installNetworkCapture(page) {
+    if (page.__wgNetworkCaptureInstalled)
+        return;
+    page.__wgNetworkCaptureInstalled = true;
+    // Marks history as needing a replay - see restoreNetworkHistory's own comment. Main frame only;
+    // an iframe navigating doesn't wipe the top-level shadow root the panel lives in.
+    page.on("framenavigated", (frame) => {
+        if (frame === page.mainFrame())
+            page.__wgNetworkNeedsRestore = true;
+    });
+    const startedAt = new Map();
+    page.on("request", (request) => {
+        startedAt.set(request, Date.now());
+    });
+    page.on("requestfinished", async (request) => {
+        try {
+            if (!RELEVANT_TYPES.has(request.resourceType()))
+                return;
+            const response = await request.response();
+            if (!response)
+                return;
+            const start = startedAt.get(request);
+            startedAt.delete(request);
+            let resBody;
+            try {
+                const contentType = (await response.headerValue("content-type")) || "";
+                if (/json|text|xml|html|javascript/.test(contentType)) {
+                    const buf = await response.body();
+                    if (buf.length <= MAX_BODY_BYTES)
+                        resBody = buf.toString("utf8");
+                }
+            }
+            catch {
+                /* body already consumed / redirected away / not available - best-effort only */
+            }
+            const [reqHeaders, resHeaders] = await Promise.all([
+                request.allHeaders().catch(ignorePageGone),
+                response.allHeaders().catch(ignorePageGone),
+            ]);
+            await recordNetworkEntry(page, {
+                method: request.method(),
+                url: request.url(),
+                status: response.status(),
+                ok: response.ok(),
+                ms: start !== undefined ? Date.now() - start : undefined,
+                reqHeaders,
+                resHeaders,
+                reqBody: request.postData() || undefined,
+                resBody,
+            });
+        }
+        catch {
+            /* a capture failure must never break the actual run it's observing */
+        }
+    });
+    page.on("requestfailed", (request) => {
+        startedAt.delete(request);
+        if (!RELEVANT_TYPES.has(request.resourceType()))
+            return;
+        recordNetworkEntry(page, {
+            method: request.method(),
+            url: request.url(),
+            status: 0,
+            ok: false,
+            reqBody: request.postData() || undefined,
+            resBody: request.failure() ? request.failure().errorText : undefined,
+        });
+    });
+}
+// defineApiBlock reports its calls through core's hook; show them in the same panel.
+setApiCallRecorder((page, entry) => recordNetworkEntry(page, entry));

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

@@ -0,0 +1,3 @@
+export declare const RUNNER_EXTRA_CSS: string;
+export declare const WAYGRAPH_FAVICON: string;
+export declare const HOST_CSS: string;

package/dist/demo/overlay/overlay-css.js

@@ -0,0 +1,369 @@
+// 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
+// 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
+// help-center-clip-engine's video-pipeline overlay (same purple ring +
+// label-under-box language, minus everything camera/narration-specific).
+// Purely CLI-level orchestration - no engine changes, no change to the
+// non-STEP path above.
+// Runner-only chrome (step panel, zoom/typing/device chips) - NOT
+// ring/cursor/banner, which come from the one shared bundle every surface installs
+// (ui/css/*.css, see ensureShadowRoot in overlay.ts). Injected under its own key so it
+// never collides with that bundle.
+export const RUNNER_EXTRA_CSS = 
+// Spotlight: dim everything except the highlight target (focus: true).
+"#wg-focus-veil{position:fixed;z-index:2147483644;pointer-events:none;" +
+    "border-radius:12px;box-shadow:0 0 0 9999px rgba(8,4,20,.62);" +
+    "opacity:0;transition:opacity .3s ease,left .3s ease,top .3s ease,width .3s ease,height .3s ease;}" +
+    "#wg-focus-veil.wg-in{opacity:1;}" +
+    // Touch swipe trail (mobile/tablet orientation + device theater).
+    "#wg-swipe-layer{position:fixed;inset:0;z-index:2147483646;pointer-events:none;" +
+    "overflow:hidden;}" +
+    "#wg-swipe-layer .wg-swipe-dot{position:absolute;width:14px;height:14px;margin:-7px 0 0 -7px;" +
+    "border-radius:50%;background:rgba(147,197,253,.55);border:2px solid rgba(255,255,255,.85);" +
+    "box-shadow:0 0 12px rgba(59,130,246,.55);opacity:0;}" +
+    "#wg-swipe-layer .wg-swipe-finger{position:absolute;width:28px;height:28px;margin:-14px 0 0 -14px;" +
+    "border-radius:50%;background:rgba(15,23,42,.92);border:2px solid #fff;" +
+    "box-shadow:0 4px 16px rgba(0,0,0,.4);opacity:0;" +
+    "transition:left .05s linear,top .05s linear,opacity .15s ease;}" +
+    "#wg-swipe-layer .wg-swipe-label{position:absolute;left:50%;top:18%;transform:translateX(-50%);" +
+    "padding:6px 12px;border-radius:999px;background:rgba(15,23,42,.88);color:#e0f2fe;" +
+    "border:1px solid rgba(56,189,248,.55);font:700 12px/1.2 system-ui,sans-serif;" +
+    "letter-spacing:.04em;text-transform:uppercase;opacity:0;transition:opacity .25s ease;}" +
+    "#wg-swipe-layer.wg-in .wg-swipe-label{opacity:1;}" +
+    "#wg-panel{position:fixed;z-index:2147483647;left:50%;bottom:12px;transform:translateX(-50%);" +
+    "max-width:min(92vw,640px);max-height:calc(100vh - 24px);overflow-y:auto;box-sizing:border-box;" +
+    "background:" + SURFACE + ";color:#fff;border-radius:14px;" +
+    "padding:16px 20px;font:14px/1.4 system-ui,sans-serif;box-shadow:0 12px 30px rgba(0,0,0,.35);" +
+    // .06s was tuned back when the panel was removed and recreated on
+    // EVERY step - fast was the only way to avoid feeling laggy. Now that
+    // routine per-step updates reuse the same element (no fade at all - see
+    // the panel-reuse fix), this only ever fires for a genuinely fresh DOM
+    // (first load, or a real navigation - which is exactly what an episode
+    // boundary is). Slower and smoother reads as a real, comfortable
+    // transition instead of an instant pop - "eyes friendly," not laggy,
+    // since it no longer costs anything on the common case.
+    "opacity:0;transition:opacity .35s ease;}" +
+    "#wg-panel.wg-in{opacity:1;}" +
+    "#wg-panel .wg-auto{margin-top:10px;font:600 13px system-ui,sans-serif;color:#c9a6ff;}" +
+    "#wg-panel .wg-autoplay-row{margin-top:8px;}" +
+    "#wg-panel .wg-autoplay-row label{display:inline-flex;align-items:center;gap:6px;" +
+    "font:12px system-ui,sans-serif;color:#b8a0e0;cursor:pointer;user-select:none;}" +
+    "#wg-panel .wg-autoplay-row input{margin:0;cursor:pointer;}" +
+    "#wg-panel h3{margin:0 0 8px;font-size:13px;color:#c9a6ff;font-weight:700;" +
+    "letter-spacing:.02em;text-transform:uppercase;}" +
+    // Sits ABOVE the per-Block "Step i/N" heading - the episode/scenario
+    // this Block belongs to, not another block-level label. Only rendered
+    // when the chain spec actually named a real Flow (chainFlow tags it via
+    // BlockInfo.resetSessionBefore's sibling metadata) - a plain ad hoc
+    // block chain shows no episode heading at all.
+    "#wg-panel .wg-episode{margin:0 0 6px;font:700 15px system-ui,sans-serif;color:#fff;" +
+    "padding-bottom:6px;border-bottom:1px solid rgba(124,58,237,.35);}" +
+    // Pace chip - numbers speak in the overlay (2.5x / 4500ms / slow).
+    "#wg-panel .wg-pace{display:inline-flex;align-items:center;gap:8px;margin:0 0 10px;" +
+    "padding:6px 10px;border-radius:8px;background:rgba(124,58,237,.22);" +
+    "border:1px solid rgba(124,58,237,.45);font:600 12px/1.35 system-ui,sans-serif;color:#f0e8ff;}" +
+    "#wg-panel .wg-pace-badge{display:inline-block;padding:2px 8px;border-radius:999px;" +
+    "background:#7C3AED;color:#fff;font:800 11px/1.2 system-ui,sans-serif;letter-spacing:.04em;" +
+    "text-transform:uppercase;}" +
+    "#wg-panel .wg-pace[data-pace-kind=slow] .wg-pace-badge," +
+    "#wg-panel .wg-pace[data-pace-kind=num-slow] .wg-pace-badge{background:#EAB308;color:#1c1917;}" +
+    "#wg-panel .wg-pace[data-pace-kind=fast] .wg-pace-badge," +
+    "#wg-panel .wg-pace[data-pace-kind=blitz] .wg-pace-badge{background:#22C55E;color:#052e16;}" +
+    "#wg-panel .wg-pace[data-pace-kind=ms] .wg-pace-badge{background:#3B82F6;color:#fff;}" +
+    "#wg-panel .wg-narration{margin:0 0 12px;font:italic 14px/1.4 system-ui,sans-serif;color:#f0e8ff;}" +
+    // Todo checklist(s) float outside #wg-panel so --mini / Hide never hide them.
+    // Multiple docks (one per todoId) are supported - stacked on the same side.
+    // Click a dock to slide left <-> right (WAYGRAPH_TODO_POS / --todo-left|right).
+    ".wg-todo-dock,#wg-todo-dock{position:fixed;z-index:2147483646;top:104px;left:14px;" +
+    "width:min(280px,42vw);max-height:calc(100vh - 100px);overflow:auto;box-sizing:border-box;" +
+    "padding:10px 12px;background:" + SURFACE + ";color:#fff;border-radius:12px;" +
+    "border:1px solid rgba(124,58,237,.45);box-shadow:0 8px 24px rgba(0,0,0,.35);" +
+    "pointer-events:auto;cursor:pointer;" +
+    "transition:transform .4s cubic-bezier(.22,1,.36,1),top .35s ease,opacity .25s ease,z-index 0s;transform:translateX(0);}" +
+    ".wg-todo-dock[data-pos=right],#wg-todo-dock[data-pos=right]{transform:translateX(calc(100vw - 100% - 28px));}" +
+    ".wg-todo-dock[data-pos=left],#wg-todo-dock[data-pos=left]{transform:translateX(0);}" +
+    /* While a highlight ring is up: sit under the ring so captions stay readable. */
+    ".wg-todo-dock.wg-todo-behind,#wg-todo-dock.wg-todo-behind{z-index:2147483643;opacity:.42;}" +
+    /* Collision tuck: shrink so a mid-page ring can still breathe. */
+    ".wg-todo-dock[data-tucked=\"1\"],#wg-todo-dock[data-tucked=\"1\"]{max-height:min(28vh,220px);}" +
+    /* Compact + cap: fold overflow rows; hover / data-expanded reveals more. */
+    ".wg-todo-dock[data-compact=\"1\"]:not(:hover):not([data-expanded=\"1\"]) li.wg-todo-fold{display:none;}" +
+    ".wg-todo-dock[data-compact=\"1\"]:is(:hover,[data-expanded=\"1\"]) li.wg-todo-fold-deep{display:none;}" +
+    ".wg-todo-dock .wg-todo-more{display:flex;align-items:center;gap:6px;margin-top:6px;padding:5px 8px;" +
+    "border-radius:8px;background:rgba(124,58,237,.22);border:1px solid rgba(124,58,237,.4);" +
+    "font:700 11px/1.2 system-ui,sans-serif;color:#e8dcff;cursor:pointer;user-select:none;}" +
+    ".wg-todo-dock .wg-todo-more:hover{background:rgba(124,58,237,.35);}" +
+    ".wg-todo-dock .wg-todo-dock-title{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
+    "letter-spacing:.04em;text-transform:uppercase;margin:0 0 8px;}" +
+    ".wg-todo-dock .wg-todos-list,#wg-todo-dock #wg-todos,.wg-todo-dock #wg-todos{list-style:none;margin:0;padding:0;background:transparent;border:none;}" +
+    // Always-on zoom HUD - bottom-right (top-left is crowded: todos + banners). Violet, matching the
+    // rest of the overlay's design tokens - this used to be a lone amber/yellow badge, the one
+    // surface that never got pulled into the shared palette when everything else did.
+    "#wg-zoom-badge{position:fixed;z-index:2147483646;bottom:14px;right:14px;" +
+    "display:flex;align-items:center;gap:7px;padding:6px 11px 6px 8px;" +
+    "border-radius:999px;background:" + SURFACE + ";color:#f0e8ff;" +
+    "border:1px solid rgba(124,58,237,.55);box-shadow:0 6px 18px rgba(0,0,0,.4);" +
+    "font:700 12px/1.2 system-ui,sans-serif;pointer-events:none;" +
+    "opacity:1;transform:translateY(0);}" +
+    "#wg-zoom-badge .wg-zoom-ico{width:18px;height:18px;display:flex;align-items:center;justify-content:center;" +
+    "border-radius:6px;background:rgba(124,58,237,.28);}" +
+    "#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;" +
+    "border-radius:999px;background:rgba(20,10,40,.95);color:#e0f2fe;" +
+    "border:1px solid rgba(56,189,248,.55);box-shadow:0 8px 22px rgba(0,0,0,.4);" +
+    "font:700 12px/1.2 system-ui,sans-serif;pointer-events:none;" +
+    "opacity:0;transition:opacity .2s ease;}" +
+    "#wg-typing-badge.wg-in{opacity:1;}" +
+    "#wg-typing-badge .wg-ty-dots{letter-spacing:.15em;color:#7dd3fc;}" +
+    // Device toast + chip (0.13.2+) - icon toast on fixture change, then compact chip.
+    "#wg-device-toast{position:fixed;z-index:2147483647;top:14px;right:14px;" +
+    "display:flex;align-items:center;gap:10px;min-width:200px;max-width:min(92vw,320px);" +
+    "padding:12px 14px;border-radius:14px;background:rgba(20,10,40,.96);color:#f0e8ff;" +
+    "border:1px solid rgba(124,58,237,.55);box-shadow:0 10px 28px rgba(0,0,0,.4);" +
+    "font:600 13px/1.35 system-ui,sans-serif;pointer-events:none;" +
+    "opacity:0;transform:translateX(18px) scale(.96);" +
+    "transition:opacity .35s ease,transform .45s cubic-bezier(.22,1,.36,1);}" +
+    "#wg-device-toast.wg-in{opacity:1;transform:translateX(0) scale(1);}" +
+    "#wg-device-toast.wg-out{opacity:0;transform:translateX(12px) scale(.98);}" +
+    "#wg-device-toast[data-preset=mobile]{border-color:#3B82F6;}" +
+    "#wg-device-toast[data-preset=tablet]{border-color:#22C55E;}" +
+    "#wg-device-toast[data-preset=desktop]{border-color:#9CA3AF;}" +
+    "#wg-device-toast .wg-dev-icon{flex:0 0 auto;width:36px;height:36px;border-radius:10px;" +
+    "display:flex;align-items:center;justify-content:center;background:rgba(124,58,237,.28);}" +
+    "#wg-device-toast[data-preset=mobile] .wg-dev-icon{background:rgba(59,130,246,.28);}" +
+    "#wg-device-toast[data-preset=tablet] .wg-dev-icon{background:rgba(34,197,94,.28);}" +
+    "#wg-device-toast[data-preset=desktop] .wg-dev-icon{background:rgba(156,163,175,.28);}" +
+    "#wg-device-toast .wg-dev-icon svg{width:22px;height:22px;display:block;}" +
+    "#wg-device-toast .wg-dev-copy{flex:1 1 auto;min-width:0;}" +
+    "#wg-device-toast .wg-dev-title{font:800 13px/1.2 system-ui,sans-serif;color:#fff;}" +
+    "#wg-device-toast .wg-dev-sub{margin-top:3px;font:600 11px/1.3 system-ui,sans-serif;" +
+    "color:#c9a6ff;letter-spacing:.02em;}" +
+    "#wg-device-badge{position:fixed;z-index:2147483646;top:14px;right:14px;" +
+    "display:inline-flex;align-items:center;gap:6px;padding:6px 10px 6px 8px;" +
+    "border-radius:999px;background:rgba(20,10,40,.92);color:#f0e8ff;" +
+    "border:1px solid rgba(124,58,237,.5);font:700 11px/1.2 system-ui,sans-serif;" +
+    "letter-spacing:.04em;text-transform:uppercase;pointer-events:none;" +
+    "box-shadow:0 4px 14px rgba(0,0,0,.3);opacity:0;transform:translateY(-4px);" +
+    "transition:opacity .3s ease,transform .35s cubic-bezier(.22,1,.36,1);}" +
+    "#wg-device-badge.wg-in{opacity:1;transform:translateY(0);}" +
+    "#wg-device-badge[data-preset=mobile]{border-color:#3B82F6;}" +
+    "#wg-device-badge[data-preset=tablet]{border-color:#22C55E;}" +
+    "#wg-device-badge[data-preset=desktop]{border-color:#9CA3AF;}" +
+    "#wg-device-badge .wg-dev-icon{width:16px;height:16px;display:flex;align-items:center;justify-content:center;}" +
+    "#wg-device-badge .wg-dev-icon svg{width:14px;height:14px;display:block;}" +
+    "#wg-device-badge .wg-dev-label{white-space:nowrap;}" +
+    "#wg-cursor[data-touch=1]{width:28px;height:28px;}" +
+    "#wg-todos,.wg-todos-list{list-style:none;margin:0 0 12px;padding:8px 10px;background:#0f0620;border-radius:8px;" +
+    "border:1px solid #3a2a60;}" +
+    "#wg-todos li,.wg-todos-list li{display:flex;gap:8px;align-items:flex-start;margin:0 0 6px;font:600 12.5px/1.35 system-ui,sans-serif;}" +
+    "#wg-todos li:last-child,.wg-todos-list li:last-child{margin-bottom:0;}" +
+    "#wg-todos .wg-todo-mark,.wg-todos-list .wg-todo-mark{flex:0 0 auto;width:1.1em;text-align:center;}" +
+    "#wg-todos .wg-todo-done,.wg-todos-list .wg-todo-done{color:#6ee7b7;text-decoration:line-through;opacity:.85;}" +
+    "#wg-todos .wg-todo-current,.wg-todos-list .wg-todo-current{color:#fff;}" +
+    "#wg-todos .wg-todo-pending,.wg-todos-list .wg-todo-pending{color:#9a7ad1;}" +
+    "#wg-todos[data-wg-todo-style=bullets] .wg-todo-pending," +
+    "#wg-todos[data-wg-todo-style=bullets] .wg-todo-current," +
+    ".wg-todos-list[data-wg-todo-style=bullets] .wg-todo-pending," +
+    ".wg-todos-list[data-wg-todo-style=bullets] .wg-todo-current{color:#e8dcff;}" +
+    "#wg-todos[data-wg-todo-style=bullets] .wg-todo-mark," +
+    ".wg-todos-list[data-wg-todo-style=bullets] .wg-todo-mark{color:#c9a6ff;}" +
+    "#wg-progress{height:4px;background:#2a1650;border-radius:2px;margin:0 0 12px;overflow:hidden;}" +
+    "#wg-progress-bar{height:100%;background:#7C3AED;border-radius:2px;transition:width .3s ease;}" +
+    // A real tab bar for episodes - the currently-active episode reads as
+    // active (filled underline, full-brightness text), every other episode
+    // reads as inactive (dimmed, no underline) - the user's own ask: "if episode
+    // 1 is active, the episode 2 tab is inactive." Only rendered when the
+    // chain spec actually named real Flows (chainFlow tags each via
+    // BlockInfo - same gate the "Episode N:" heading already uses); an
+    // ad hoc block chain with no episodes shows no tab bar at all.
+    "#wg-episodes{display:flex;gap:4px;margin:0 0 10px;border-bottom:1px solid #3a2a60;}" +
+    "#wg-episodes .wg-ep-tab{padding:6px 14px 8px;font:600 12px system-ui,sans-serif;" +
+    "border-bottom:2px solid transparent;margin-bottom:-1px;white-space:nowrap;}" +
+    "#wg-episodes .wg-ep-current{color:#fff;border-bottom-color:#7C3AED;}" +
+    "#wg-episodes .wg-ep-done{color:#9a7ad1;}" +
+    "#wg-episodes .wg-ep-upcoming{color:#5a4a80;}" +
+    // A one-time, gentle signal for "you just entered this episode" - the user:
+    // "i want a clear ui eyes friendly to remind me that i am on next
+    // episode." A slow outward glow, not an opacity blink/strobe (that's
+    // exactly the kind of flashing that already caused the original
+    // complaint) - plays once (no loop), 1.1s, only on the FIRST block of a
+    // newly-entered episode, not on every step within it.
+    "@keyframes wg-ep-enter{0%{box-shadow:0 0 0 0 rgba(124,58,237,.55);}" +
+    "100%{box-shadow:0 0 0 10px rgba(124,58,237,0);}}" +
+    "#wg-episodes .wg-ep-entered{border-radius:6px;animation:wg-ep-enter 1.1s ease-out;}" +
+    // Block strip: carousel (default) or classic wrap (--full).
+    "#wg-modules.wg-modules-carousel{display:flex;flex-wrap:nowrap;gap:8px;margin:0 0 10px;" +
+    "overflow-x:auto;scroll-snap-type:x mandatory;-webkit-overflow-scrolling:touch;" +
+    "padding:4px 2px 8px;scrollbar-width:thin;}" +
+    "#wg-modules.wg-modules-carousel .wg-mod{flex:0 0 auto;scroll-snap-align:center;" +
+    "padding:6px 12px;border-radius:999px;font:600 12px system-ui,sans-serif;}" +
+    "#wg-modules.wg-modules-carousel .wg-mod-current{transform:scale(1.06);" +
+    "box-shadow:0 0 0 2px rgba(124,58,237,.45);}" +
+    "#wg-modules.wg-modules-full{display:flex;flex-wrap:wrap;gap:6px;margin:0 0 10px;}" +
+    "#wg-modules.wg-modules-full .wg-mod{padding:3px 9px;border-radius:6px;font:600 11px system-ui,sans-serif;}" +
+    "#wg-modules .wg-mod-done{background:#2a1650;color:#9a7ad1;}" +
+    "#wg-modules .wg-mod-current{background:#7C3AED;color:#fff;}" +
+    "#wg-modules .wg-mod-upcoming{background:transparent;color:#5a4a80;border:1px solid #3a2a60;}" +
+    // #wg-banner: comes from the shared bundle (ui/css/banner.css) now - not redefined here.
+    "#wg-panel .wg-key{margin:8px 0;}" +
+    // A live, human-readable preview of what's about to be written for this
+    // MemKey - the user: "i want pretty to exist in memkeys too... it shows what
+    // input its gonig to be written." Same global Pretty/JSON preference the
+    // result display already has (window.__wgPretty) - hidden entirely in
+    // JSON mode, since the raw textarea already speaks for itself there.
+    "#wg-panel .wg-key-pretty{margin-top:4px;font:12px/1.5 system-ui,sans-serif;" +
+    "background:#0f0620;border-radius:6px;padding:6px 8px;}" +
+    "#wg-panel .wg-key-pretty-row{color:#f0e8ff;}" +
+    "#wg-panel .wg-key-pretty-label{color:#9a7ad1;font-weight:600;}" +
+    "#wg-panel label{display:block;font-size:12px;color:#d8c8ff;margin-bottom:3px;}" +
+    "#wg-panel textarea{width:100%;box-sizing:border-box;background:#0f0620;color:#fff;" +
+    "border:1px solid #4b2a80;border-radius:8px;padding:6px 8px;font:12px/1.3 monospace;resize:vertical;}" +
+    "#wg-panel button{margin-top:10px;background:#7C3AED;color:#fff;border:none;border-radius:8px;" +
+    "padding:8px 16px;font:600 13px system-ui,sans-serif;cursor:pointer;}" +
+    "#wg-panel button:hover{background:#6b2fd6;}" +
+    "#wg-panel button:disabled{background:#4b2a80;cursor:default;opacity:.7;}" +
+    "#wg-panel textarea:disabled{opacity:.6;}" +
+    "#wg-panel .wg-result{font:12px/1.4 monospace;background:#0f0620;border-radius:8px;padding:8px;" +
+    "margin:8px 0;white-space:pre-wrap;}" +
+    "#wg-panel .wg-result-pretty{font:600 14px/1.4 system-ui,sans-serif;}" +
+    "#wg-panel .wg-toggle{display:flex;gap:4px;margin:0 0 4px;}" +
+    "#wg-panel .wg-toggle button{margin:0;padding:3px 10px;font:600 11px system-ui,sans-serif;" +
+    "background:transparent;border:1px solid #4b2a80;color:#9a7ad1;border-radius:6px;}" +
+    "#wg-panel .wg-toggle button.wg-active{background:#4b2a80;color:#fff;}" +
+    "#wg-panel.wg-error{border:1.5px solid #e0475c;}" +
+    "#wg-panel .wg-error-heading{color:#ff8fa0;}" +
+    "#wg-panel .wg-error-msg{font:12px/1.5 monospace;background:#2a0f16;color:#ffc7cf;" +
+    "border-radius:8px;padding:10px;margin:0 0 12px;white-space:pre-wrap;max-height:200px;overflow-y:auto;}" +
+    "#wg-panel .wg-error-actions{display:flex;gap:8px;}" +
+    "#wg-panel .wg-error-stop{background:#e0475c;margin-top:0;}" +
+    "#wg-panel .wg-error-stop:hover{background:#c33a4c;}" +
+    "#wg-panel .wg-error-retry{background:#2a9d6f;margin-top:0;}" +
+    "#wg-panel .wg-error-retry:hover{background:#22855e;}" +
+    "#wg-panel.wg-expected{border:1.5px solid #e0a53e;}" +
+    "#wg-panel .wg-expected-heading{color:#ffcf7a;}" +
+    "#wg-panel .wg-expected-reason{font:600 12.5px/1.5 system-ui,sans-serif;background:#2a2410;" +
+    "color:#ffe6ae;border-radius:8px;padding:10px;margin:0 0 8px;}" +
+    // Hide / Show chrome: collapsed = compact "N / M · block" pill + Next (manual).
+    "#wg-panel .wg-chrome{display:flex;align-items:center;justify-content:space-between;gap:8px;margin:0 0 8px;}" +
+    "#wg-panel .wg-chrome-title{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
+    "letter-spacing:.04em;text-transform:uppercase;flex:1;min-width:0;display:flex;align-items:center;gap:4px;}" +
+    // Animated fast-forward indicator on the collapsed bottom-center pill - a blitzed/FF step has
+    // no ring, no narration theater, nothing else visible marking it as different, so it read as
+    // just another normal step with no explanation for why it snapped past instantly.
+    "#wg-panel .wg-ff-icon{display:inline-flex;align-items:center;flex-shrink:0;width:13px;height:13px;}" +
+    "#wg-panel .wg-ff-icon svg{width:100%;height:100%;display:block;}" +
+    "#wg-panel .wg-ff-icon .wg-ff-chev{animation:wg-ff-pulse 900ms ease-in-out infinite;}" +
+    "#wg-panel .wg-ff-icon .wg-ff-chev:nth-child(2){animation-delay:150ms;}" +
+    "@keyframes wg-ff-pulse{0%,100%{opacity:.3;transform:translateX(-1.5px);}50%{opacity:1;transform:translateX(1.5px);}}" +
+    "#wg-panel .wg-chrome-actions{display:flex;align-items:center;gap:6px;flex-shrink:0;}" +
+    "#wg-panel button.wg-hide-btn,#wg-panel button.wg-mini-next{margin:0;padding:4px 10px;font:600 11px system-ui,sans-serif;" +
+    "background:#3a2a60;color:#e8dcff;border:1px solid #5b3aa8;border-radius:6px;cursor:pointer;}" +
+    "#wg-panel button.wg-hide-btn:hover,#wg-panel button.wg-mini-next:hover{background:#4b2a80;}" +
+    "#wg-panel button.wg-mini-next{background:#2a9d6f;border-color:#22855e;color:#fff;display:none;}" +
+    "#wg-panel button.wg-mini-next:hover{background:#22855e;}" +
+    "#wg-panel button.wg-mini-next:disabled{opacity:.55;cursor:default;}" +
+    "#wg-panel.wg-collapsed{width:auto;max-width:92vw;padding:8px 12px;max-height:none;overflow:hidden;}" +
+    "#wg-panel.wg-collapsed .wg-body{display:none;}" +
+    "#wg-panel.wg-collapsed .wg-chrome{margin:0;}" +
+    "#wg-panel.wg-collapsed .wg-chrome-title{font:700 13px/1.25 system-ui,sans-serif;color:#fff;" +
+    "letter-spacing:0;text-transform:none;}" +
+    "#wg-panel.wg-collapsed button.wg-mini-next.wg-mini-next-show{display:inline-block;}" +
+    "@media (max-width:640px){" +
+    "#wg-panel{left:8px;right:8px;bottom:8px;transform:none;max-width:none;width:auto;" +
+    "max-height:min(55vh,calc(100vh - 16px));padding:12px 14px;border-radius:12px;}" +
+    "#wg-panel.wg-collapsed{left:50%;right:auto;transform:translateX(-50%);width:auto;}" +
+    "#wg-episodes{overflow-x:auto;-webkit-overflow-scrolling:touch;flex-wrap:nowrap;}" +
+    "#wg-panel .wg-narration{font-size:13px;}" +
+    "#wg-panel button{width:100%;}" +
+    "#wg-panel.wg-collapsed button.wg-mini-next,#wg-panel.wg-collapsed button.wg-hide-btn{width:auto;}" +
+    "#wg-panel .wg-error-actions{flex-direction:column;}" +
+    "#wg-banner{max-width:min(92vw,320px);font-size:13px;}" +
+    "}";
+// Purple dot favicon (matches the overlay's own theme color) - the tab-bar
+// signal that "this Chromium window is a waygraph run," even at a glance
+// across a taskbar/alt-tab, not just something visible inside the page.
+export const WAYGRAPH_FAVICON = "data:image/svg+xml," +
+    encodeURIComponent("<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'>" +
+        "<circle cx='16' cy='16' r='14' fill='#7C3AED'/></svg>");
+// Rules that style the HOST page (device stage) - these must stay in the light DOM, outside the overlay's shadow root.
+export const HOST_CSS = 
+// Video device stage: keep recordVideo size fixed; center a device-sized shell.
+"html.wg-video-device-stage{background:#0b1220 !important;}" +
+    "html.wg-video-device-stage body{margin:0 !important;min-height:100vh !important;" +
+    "display:flex !important;align-items:center !important;justify-content:center !important;" +
+    "background:#0b1220 !important;overflow:hidden !important;}" +
+    "#wg-device-shell{flex-shrink:0;overflow:auto;background:#fff;" +
+    "border-radius:16px;box-shadow:0 24px 80px rgba(0,0,0,.55),0 0 0 1px rgba(255,255,255,.08);" +
+    "transform-origin:center center;" +
+    /* Force radius clip on all corners (Chrome + transform/scale). */
+    "-webkit-mask-image:-webkit-radial-gradient(white,black);" +
+    "isolation:isolate;" +
+    "transition:border-radius .55s cubic-bezier(.22,1,.36,1),box-shadow .55s ease," +
+    "transform .55s cubic-bezier(.22,1,.36,1),width .5s ease,height .5s ease,max-width .5s ease,max-height .5s ease;}" +
+    "#wg-device-shell.wg-shell-enter{border-radius:0;box-shadow:none;}" +
+    "#wg-device-shell.wg-shell-shutter-out{border-radius:0 !important;" +
+    "box-shadow:none !important;outline:none !important;border:none !important;}" +
+    "#wg-device-shell.wg-shell-desktop-flat{border-radius:0 !important;box-shadow:none !important;" +
+    "outline:none !important;border:none !important;-webkit-mask-image:none;}";

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

@@ -0,0 +1,23 @@
+import type { WgPage } from "../types.js";
+export declare function createOverlayStage(page: WgPage, { todoDockRef, deviceRef }: any): {
+    state: {
+        lastTodoDock: any;
+        lastDevice: any;
+        lastBannerUi: Record<string, any>;
+    };
+    pushTodoDockUi: (patch: any) => Promise<void>;
+    rememberTodoDock: (dock: any, sync: any, parallel: any) => void;
+    syncAllTodoDocks: (opts: any) => Promise<void>;
+    applyPhase: (phase: any, { reapplyDeviceOnKeep }?: {
+        reapplyDeviceOnKeep?: boolean | undefined;
+    }) => Promise<{
+        appliedTodo: {
+            dock: import("../../index.js").TodoDockState | undefined;
+            sync: "set" | "clear" | "keep";
+        };
+        appliedDevice: {
+            device: import("../../index.js").DeviceState | undefined;
+            sync: "set" | "clear" | "keep";
+        };
+    }>;
+};

package/dist/demo/overlay/overlay-stage.js

@@ -0,0 +1,106 @@
+import { applyDevicePhase } from "../narration/device.js";
+import { applyTodoPhase, resolveTodoDockUi } from "../narration/todo-dock.js";
+import { applyDeviceToPage } from "./device-stage.js";
+import { bannerUiFromPhase } from "../stepper/banner-log.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+export function createOverlayStage(page, { todoDockRef, deviceRef }) {
+    /** Carried across steps: omitting a fixture in a later phase = keep (todos, device, banner UX). */
+    const state = {
+        lastTodoDock: undefined,
+        lastDevice: undefined,
+        lastBannerUi: {},
+    };
+    /** Author todoDockUi patches (merged); resolved against env each step. */
+    let lastTodoDockUiPatch = undefined;
+    /** Multi-todo: every dock keyed by todoId (or "_default"), survives navigation. */
+    const todoDockById = new Map();
+    const pushTodoDockUi = async (patch) => {
+        if (patch && typeof patch === "object") {
+            lastTodoDockUiPatch = { ...(lastTodoDockUiPatch || {}), ...patch };
+        }
+        const ui = resolveTodoDockUi(lastTodoDockUiPatch);
+        await page
+            .evaluate((u) => {
+            window.__wgTodoDockUi = u;
+        }, ui)
+            .catch(ignorePageGone);
+    };
+    const dockRegistryKey = (dock) => dock && dock.id && String(dock.id).trim() ? String(dock.id).trim() : "_default";
+    const rememberTodoDock = (dock, sync, parallel) => {
+        if (sync === "clear") {
+            todoDockById.clear();
+            return;
+        }
+        if (sync === "set" && dock) {
+            if (!parallel)
+                todoDockById.clear();
+            todoDockById.set(dockRegistryKey(dock), dock);
+            return;
+        }
+        // keep: refresh / re-seed so syncAllTodoDocks never sees an empty map
+        // while lastTodoDock still carries (nav wipe + mid-act advance).
+        if (sync === "keep" && dock) {
+            todoDockById.set(dockRegistryKey(dock), dock);
+        }
+    };
+    const syncAllTodoDocks = async (opts) => {
+        const docks = [...todoDockById.values()];
+        const parallel = !!(opts && opts.parallel);
+        if (!docks.length) {
+            // Empty registry: do NOT clear the DOM. renderBefore/After may have
+            // just painted from lastTodoDock (keep). Clearing here made todos
+            // vanish until the next ctx.todos() set (PIA #15).
+            return;
+        }
+        await page
+            .evaluate(({ list, parallel }) => {
+            if (!window.__wgSyncTodos)
+                return;
+            for (let i = 0; i < list.length; i++) {
+                const d = list[i];
+                window.__wgSyncTodos({
+                    sync: "set",
+                    dock: d,
+                    todoId: (d && d.id) || null,
+                    pos: (d && d.pos) || null,
+                    // First dock replaces; later ones keep siblings when parallel.
+                    replace: !(parallel && i > 0),
+                    parallel: parallel && i > 0,
+                });
+            }
+        }, { list: docks, parallel })
+            .catch(ignorePageGone);
+    };
+    /**
+     * Merge one resolved stub phase (banner UX, todo dock, device) into the carried state and push it to the page.
+     * `reapplyDeviceOnKeep`: also re-apply the carried device when the phase says keep (after a navigation wipe).
+     */
+    const applyPhase = async (phase, { reapplyDeviceOnKeep = false } = {}) => {
+        state.lastBannerUi = { ...state.lastBannerUi, ...bannerUiFromPhase(phase) };
+        const appliedTodo = applyTodoPhase(state.lastTodoDock, {
+            todoSync: phase.todoSync,
+            todoDock: phase.todoDock,
+            todos: phase.todos,
+            todoPos: phase.todoPos,
+        });
+        state.lastTodoDock = appliedTodo.dock;
+        todoDockRef.current = state.lastTodoDock;
+        rememberTodoDock(appliedTodo.dock, appliedTodo.sync, !!phase.todoParallel);
+        const appliedDevice = applyDevicePhase(state.lastDevice, {
+            deviceSync: phase.deviceSync,
+            device: phase.device,
+        });
+        state.lastDevice = appliedDevice.device;
+        deviceRef.current = state.lastDevice;
+        if (appliedDevice.sync !== "keep" || (reapplyDeviceOnKeep && state.lastDevice)) {
+            await applyDeviceToPage(page, state.lastDevice, appliedDevice.sync);
+            // A deliberate settle beat: applyDeviceToPage's own viewport lerp is fully awaited above, but
+            // a ring/camera-zoom transition kicked off immediately after (the very next thing this step
+            // does) reads as happening AT THE SAME TIME as the device change on video, with no visual
+            // breathing room between them - two transitions with no gap look like one confused one.
+            await new Promise((r) => setTimeout(r, 220));
+        }
+        return { appliedTodo, appliedDevice };
+    };
+    return { state, pushTodoDockUi, rememberTodoDock, syncAllTodoDocks, applyPhase };
+}