waygraph 0.15.53 → 0.16.0

package/dist/{highlights/run-phase.js → demo/narration/narration.js}

@@ -1,5 +1,5 @@
-import { createStubCtx, liftLegacySlotTodos } from "./stub-ctx.js";
-import { applyDefaultZoom, applyDefaultZoomOut, applyLegacyHighlightsShim, isStubPhase, mergePhaseMaps, readStubRaw } from "./merge.js";
+import { createStubCtx } from "./stub-ctx.js";
+import { applyDefaultZoom, applyDefaultZoomOut, readStubRaw, resolvePhaseMap } from "./merge.js";
 import { buildTodoDock, normalizeTodoStyle, normalizeTodos } from "./todo-dock.js";
 import { resolveDeviceState } from "./device.js";
 /**
@@ -7,7 +7,7 @@ import { resolveDeviceState } from "./device.js";
  * Returns rings + episode fixtures (todos / todoIndex / zoom).
  *
  * @example
- * const before = await runStubPhase(block, "stubBefore", { fixtures });
+ * const before = await runStubPhase(block, "stubBefore", { mem });
  * // before.todos, before.highlights
  */
 export async function runStubPhase(block, phase, opts) {
@@ -18,43 +18,16 @@ export async function runStubPhase(block, phase, opts) {
         ...(opts?.mem !== undefined ? { mem: opts.mem } : {}),
     });
     const raw = readStubRaw(block, phase);
-    if (typeof raw === "function") {
+    if (raw) {
         try {
-            const ret = await raw(ctx);
-            if (isStubPhase(ret)) {
-                bag.highlights = { ...bag.highlights, ...ret };
-            }
-        }
-        catch {
-            /* best-effort */
+            await raw(ctx);
         }
-        // Compat: legacy `(out) => map` that expected Checkpoint (__state on arg). Only worth trying
-        // when the real ctx call genuinely did nothing - checked against the WHOLE bag, not just
-        // highlights/todos, so a stubBefore that only calls e.g. ctx.caption()/ctx.title()/ctx.zoom()
-        // (no highlights, no todos) isn't mistaken for "didn't run" and re-invoked with a bare
-        // Checkpoint that has none of StubCtx's methods - a real, previously-triggered bug (caught via
-        // examples/saucedemo/src/flows/checkout.flow.ts's own stubBefore(ctx) { ctx.caption(...) }).
-        const bagUntouched = Object.keys(bag).length === 1 && Object.keys(bag.highlights).length === 0;
-        if (bagUntouched) {
-            try {
-                const legacyOut = (opts?.out ?? { __state: "" });
-                const ret2 = raw(legacyOut);
-                if (isStubPhase(ret2))
-                    bag.highlights = { ...ret2 };
-            }
-            catch {
-                /* ignore */
-            }
+        catch (err) {
+            // A mistake in the author's stub: shown on the step (the demo's failure panel), never dropped.
+            throw new Error(`${block.name}: its ${phase} stub threw: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
         }
     }
-    else if (isStubPhase(raw)) {
-        bag.highlights = { ...raw };
-    }
-    bag.highlights = applyLegacyHighlightsShim(block, phase, bag.highlights, opts?.out);
-    liftLegacySlotTodos(bag);
-    const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
-    let highlights = mergePhaseMaps(bag.highlights, fixturePhase);
-    highlights = applyDefaultZoom(highlights, bag.zoom);
+    let highlights = applyDefaultZoom(resolvePhaseMap(bag.highlights), bag.zoom);
     highlights = applyDefaultZoomOut(highlights, bag.zoomOut);
     const todoDock = bag.hideTodos
         ? undefined
@@ -134,45 +107,19 @@ export async function runStubPhase(block, phase, opts) {
 export function resolveHighlightSlots(block, phase, opts) {
     const bag = { highlights: {} };
     const raw = readStubRaw(block, phase);
-    if (typeof raw === "function") {
+    if (raw) {
+        // Synchronous read: the rings a stub paints before its first await.
         try {
-            const ctx = createStubCtx(bag, {
-                ...(opts?.out !== undefined ? { out: opts.out } : {}),
-            });
-            const ret = raw(ctx);
-            if (isStubPhase(ret)) {
-                bag.highlights = { ...bag.highlights, ...ret };
-            }
+            void raw(createStubCtx(bag, { ...(opts?.out !== undefined ? { out: opts.out } : {}) }));
         }
-        catch {
-            try {
-                const legacyOut = (opts?.out ?? { __state: "" });
-                const ret2 = raw(legacyOut);
-                if (isStubPhase(ret2))
-                    bag.highlights = { ...ret2 };
-            }
-            catch {
-                bag.highlights = {};
-            }
+        catch (err) {
+            throw new Error(`${block.name}: its ${phase} stub threw: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
         }
     }
-    else if (isStubPhase(raw)) {
-        bag.highlights = { ...raw };
-    }
-    bag.highlights = applyLegacyHighlightsShim(block, phase, bag.highlights, opts?.out);
-    liftLegacySlotTodos(bag);
-    const fixturePhase = opts?.fixtures?.[block.name]?.[phase];
-    return applyDefaultZoom(mergePhaseMaps(bag.highlights, fixturePhase), bag.zoom);
+    return applyDefaultZoom(resolvePhaseMap(bag.highlights), bag.zoom);
 }
-/**
- * Resolve multi-step yap slides: flow fixture `slides` wins when present,
- * else `instruction.slides` (function form allowed).
- */
+/** Resolve multi-step yap slides from `instruction.slides` (function form allowed). */
 export function resolveSlides(block, opts) {
-    const fromFixture = opts?.fixtures?.[block.name]?.slides;
-    if (fromFixture && fromFixture.length > 0) {
-        return [...fromFixture];
-    }
     const instr = block.instruction;
     let raw = instr.slides;
     if (typeof raw === "function") {
@@ -187,40 +134,24 @@ export function resolveSlides(block, opts) {
         return [];
     return raw.filter((s) => s && typeof s.caption === "string" && s.caption.length > 0);
 }
-function stubPhaseLooksAuthored(block, phase, fixtures) {
-    const raw = readStubRaw(block, phase);
-    if (typeof raw === "function")
-        return true;
-    if (isStubPhase(raw) && Object.keys(raw).length > 0)
-        return true;
-    const fx = fixtures?.[block.name]?.[phase];
-    if (fx && Object.keys(fx).length > 0)
-        return true;
-    return false;
+function stubPhaseLooksAuthored(block, phase) {
+    return readStubRaw(block, phase) !== undefined;
 }
 /**
- * True when the block authored stubAfter (lifecycle fn, slots, fixtures, or legacy highlights).
+ * True when the block authored stubAfter (lifecycle fn or slots).
  * When true, demo should not use verify-trait fallback.
  */
-export function hasAuthoredStubAfter(block, out, fixtures) {
-    if (stubPhaseLooksAuthored(block, "stubAfter", fixtures))
-        return true;
-    const instr = block.instruction;
-    if (instr.highlights)
+export function hasAuthoredStubAfter(block, out) {
+    if (stubPhaseLooksAuthored(block, "stubAfter"))
         return true;
-    return resolveHighlightSlots(block, "stubAfter", {
-        ...(out !== undefined ? { out } : {}),
-        ...(fixtures !== undefined ? { fixtures } : {}),
-    }).length > 0;
+    return resolveHighlightSlots(block, "stubAfter", out !== undefined ? { out } : {}).length > 0;
 }
 /**
  * True when stubOnError is authored (lifecycle fn and/or rings).
  * Demo fail path only - success never consults this.
  */
-export function hasAuthoredStubOnError(block, fixtures) {
-    if (stubPhaseLooksAuthored(block, "stubOnError", fixtures))
+export function hasAuthoredStubOnError(block) {
+    if (stubPhaseLooksAuthored(block, "stubOnError"))
         return true;
-    return (resolveHighlightSlots(block, "stubOnError", {
-        ...(fixtures !== undefined ? { fixtures } : {}),
-    }).length > 0);
+    return resolveHighlightSlots(block, "stubOnError").length > 0;
 }

package/dist/{highlights → demo/narration}/shorthand.d.ts

@@ -13,7 +13,7 @@
  * `a, b` lists). A selector/label containing a literal `;` or `|` needs the
  * full-JSON form instead - documented, not silently mishandled.
  */
-import type { PilotHighlightFixtures } from "../pilot-overlay.js";
+import type { PilotHighlightFixtures } from "../overlay/pilot/fixtures.js";
 export type ParsedHighlightShorthand = {
     type: "ok";
     fixtures: PilotHighlightFixtures;

package/dist/demo/narration/stub-ctx.d.ts

@@ -0,0 +1,8 @@
+import type { StubBagState, StubCtx } from "../../engine/stub/stub.js";
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+import type { MemPage } from "../../engine/mem/mem.js";
+export declare function createStubCtx<Out extends Checkpoint<string>>(bag: StubBagState, opts: {
+    out?: Out;
+    error?: unknown;
+    mem?: MemPage;
+}): StubCtx<Out>;

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

@@ -0,0 +1,164 @@
+import { normalizeTodoPos, normalizeTodoStyle } from "./todo-dock.js";
+import { applyOrientation, normalizeDeviceOrientation, resolveDeviceState } from "./device.js";
+export function createStubCtx(bag, opts) {
+    /** One dock per id: its title, style and side; without `parallel` it replaces the dock on screen. */
+    const setDock = (id, opts) => {
+        bag.todoTouched = true;
+        bag.hideTodos = false;
+        delete bag.todoGroups;
+        const cleaned = id.trim();
+        if (cleaned)
+            bag.todoId = cleaned;
+        else
+            delete bag.todoId;
+        if (opts.title != null)
+            bag.todoTitle = String(opts.title);
+        const style = normalizeTodoStyle(opts.style);
+        if (style)
+            bag.todoStyle = style;
+        const pos = normalizeTodoPos(opts.pos);
+        if (pos)
+            bag.todoPos = pos;
+        bag.todoParallel = opts.parallel === true;
+    };
+    return {
+        mem: opts.mem,
+        out: opts.out,
+        error: opts.error,
+        highlights(slots) {
+            bag.highlights = { ...(slots || {}) };
+        },
+        ring(id, stub) {
+            bag.highlights = { ...bag.highlights, [id]: stub };
+        },
+        todos(id, items, opts = {}) {
+            setDock(id, opts);
+            bag.todos = items;
+            if (opts.index != null)
+                bag.todoIndex = Number(opts.index);
+            if (!items.length)
+                bag.hideTodos = true;
+        },
+        todoIndex(n) {
+            bag.todoIndex = n;
+        },
+        todoGroups(id, groups, opts = {}) {
+            setDock(id, opts);
+            bag.todoGroups = groups;
+            if (!groups.length)
+                bag.hideTodos = true;
+        },
+        hideTodos() {
+            bag.todoTouched = true;
+            bag.hideTodos = true;
+            bag.todos = [];
+            delete bag.todoGroups;
+        },
+        device(preset) {
+            bag.deviceTouched = true;
+            bag.hideDevice = false;
+            const resolved = resolveDeviceState(preset, bag.touchOverride, bag.orientationOverride);
+            if (resolved) {
+                bag.device = resolved;
+                if (resolved.preset === "desktop" && !resolved.touchMode) {
+                    bag.hideDevice = true;
+                }
+            }
+        },
+        viewport(box) {
+            bag.deviceTouched = true;
+            bag.hideDevice = false;
+            const resolved = resolveDeviceState(box, bag.touchOverride, bag.orientationOverride);
+            if (resolved)
+                bag.device = resolved;
+        },
+        touch(on) {
+            bag.deviceTouched = true;
+            const enabled = on === undefined ? true : !!on;
+            bag.touchOverride = enabled;
+            if (enabled)
+                bag.hideDevice = false;
+            if (bag.device) {
+                bag.device = {
+                    ...bag.device,
+                    touchMode: enabled,
+                    hasTouch: bag.device.hasTouch || enabled,
+                };
+                if (enabled)
+                    bag.hideDevice = false;
+            }
+            else if (enabled) {
+                const base = resolveDeviceState("desktop", true, bag.orientationOverride);
+                if (base)
+                    bag.device = { ...base, touchMode: true, hasTouch: true };
+            }
+        },
+        orientation(o) {
+            const want = normalizeDeviceOrientation(o);
+            if (!want)
+                return;
+            bag.deviceTouched = true;
+            bag.hideDevice = false;
+            bag.orientationOverride = want;
+            const base = bag.device ||
+                resolveDeviceState("mobile", bag.touchOverride) ||
+                resolveDeviceState("mobile");
+            if (base)
+                bag.device = applyOrientation(base, want);
+        },
+        hideDevice() {
+            bag.deviceTouched = true;
+            bag.hideDevice = true;
+            bag.device = resolveDeviceState("desktop", false);
+            bag.touchOverride = false;
+            bag.orientationOverride = undefined;
+        },
+        zoom(n) {
+            if (Number.isFinite(n) && n > 0)
+                bag.zoom = n;
+        },
+        zoomOut(keep) {
+            bag.zoomOut = !!keep;
+        },
+        title(text, opts) {
+            bag.title = String(text ?? "");
+            const p = normalizeBannerPos(opts?.pos);
+            if (p)
+                bag.titlePos = p;
+        },
+        titlePos(side) {
+            const p = normalizeBannerPos(side);
+            if (p)
+                bag.titlePos = p;
+        },
+        caption(text) {
+            bag.caption = String(text ?? "");
+        },
+        hideCaption() {
+            bag.caption = "";
+        },
+        showNetworkTab() {
+            bag.networkTabVisible = true;
+        },
+        hideNetworkTab() {
+            bag.networkTabVisible = false;
+        },
+        bannerUi(opts) {
+            if (!opts || typeof opts !== "object")
+                return;
+            bag.bannerUi = { ...(bag.bannerUi || {}), ...opts };
+        },
+        hideBanner() {
+            bag.bannerUi = { ...(bag.bannerUi || {}), hidden: true };
+        },
+        todoDockUi(opts) {
+            if (!opts || typeof opts !== "object")
+                return;
+            bag.todoDockUi = { ...(bag.todoDockUi || {}), ...opts };
+        },
+    };
+}
+function normalizeBannerPos(raw) {
+    const v = String(raw ?? "").toLowerCase();
+    return v === "left" || v === "center" || v === "right" ? v : undefined;
+}

package/dist/{highlights → demo/narration}/style.d.ts

@@ -1,4 +1,4 @@
-import type { HighlightSize, HighlightStyleDefaults, HighlightTone, HighlightWeight } from "./types.js";
+import type { HighlightSize, HighlightStyleDefaults, HighlightTone, HighlightWeight } from "../../engine/stub/ring.js";
 /** Apply Flow defaults under per-slot authored values (slot wins when set). */
 export declare function applyHighlightStyleDefaults<T extends {
     tone?: HighlightTone | string;
@@ -9,12 +9,6 @@ export declare function applyHighlightStyleDefaults<T extends {
     size: HighlightSize;
     weight: HighlightWeight;
 };
-/** Map author aliases (`error` -> danger) to a canonical tone. */
-export declare function normalizeHighlightTone(raw: unknown): HighlightTone;
-/** Map size aliases to sm/md/lg. */
-export declare function normalizeHighlightSize(raw: unknown): HighlightSize;
-/** Map weight aliases to normal/bold. */
-export declare function normalizeHighlightWeight(raw: unknown): HighlightWeight;
 /** Prefix label with a short ASCII icon for semantic tones. */
 export declare function toneIconPrefix(tone: HighlightTone): string;
 /** Caption for ring / slide UI (label|caption + optional detail/tag + tone icon). */

package/dist/{highlights → demo/narration}/style.js

@@ -1,3 +1,4 @@
+import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../../engine/stub/ring.js";
 /** Apply Flow defaults under per-slot authored values (slot wins when set). */
 export function applyHighlightStyleDefaults(slot, defaults) {
     const tone = slot.tone !== undefined && slot.tone !== ""
@@ -26,47 +27,6 @@ const TONE_ICONS = {
     success: "+",
     orange: "",
 };
-/** Map author aliases (`error` -> danger) to a canonical tone. */
-export function normalizeHighlightTone(raw) {
-    if (typeof raw !== "string")
-        return "planned";
-    const t = raw.trim().toLowerCase();
-    if (t === "auto" || t === "automation" || t === "engine")
-        return "auto";
-    if (t === "info" || t === "blue")
-        return "info";
-    if (t === "warning" || t === "warn" || t === "yellow")
-        return "warning";
-    if (t === "danger" || t === "error" || t === "red")
-        return "danger";
-    if (t === "success" || t === "ok" || t === "green")
-        return "success";
-    if (t === "orange" || t === "amber" || t === "dom" || t === "inspect")
-        return "orange";
-    if (t === "planned" || t === "purple" || t === "authored")
-        return "planned";
-    return "planned";
-}
-/** Map size aliases to sm/md/lg. */
-export function normalizeHighlightSize(raw) {
-    if (typeof raw !== "string")
-        return "md";
-    const t = raw.trim().toLowerCase();
-    if (t === "sm" || t === "s" || t === "small" || t === "tiny")
-        return "sm";
-    if (t === "lg" || t === "l" || t === "large" || t === "big" || t === "xl")
-        return "lg";
-    return "md";
-}
-/** Map weight aliases to normal/bold. */
-export function normalizeHighlightWeight(raw) {
-    if (typeof raw !== "string")
-        return "normal";
-    const t = raw.trim().toLowerCase();
-    if (t === "bold" || t === "strong" || t === "heavy" || t === "b")
-        return "bold";
-    return "normal";
-}
 /** Prefix label with a short ASCII icon for semantic tones. */
 export function toneIconPrefix(tone) {
     const icon = TONE_ICONS[tone];

package/dist/{highlights → demo/narration}/todo-dock.d.ts

@@ -1,9 +1,9 @@
-import type { TodoDockState, TodoDockUiOpts, TodoDockUiResolved, TodoListStyle, WaygraphTodoGroupInput, WaygraphTodoInput, WaygraphTodoItem } from "./types.js";
+import type { TodoDockState, TodoDockUiOpts, TodoDockUiResolved, TodoListStyle, WaygraphTodoGroupInput, WaygraphTodoInput, WaygraphTodoItem } from "../../engine/stub/todos.js";
 /**
  * Resolve todo-dock UX from env + optional author patch.
- * `WAYGRAPH_TODO_UI=full|off|legacy` forces compact/collision/behindRing off.
+ * `WAYGRAPH_TODO_UI=full|off` forces compact/collision/behindRing off.
  */
-export declare function resolveTodoDockUi(patch?: TodoDockUiOpts | null, env?: NodeJS.ProcessEnv): TodoDockUiResolved;
+export declare function resolveTodoDockUi(patch?: TodoDockUiOpts | null): TodoDockUiResolved;
 /** Normalize checklist dock side. */
 export declare function normalizeTodoPos(raw: unknown): "left" | "right" | undefined;
 /** Normalize dock list style. */

package/dist/{highlights → demo/narration}/todo-dock.js

@@ -1,33 +1,20 @@
-function envFlagBool(env, key, fallback) {
-    const v = env[key];
-    if (v === undefined || v === "")
-        return fallback;
-    const s = String(v).trim().toLowerCase();
-    if (s === "0" || s === "false" || s === "off" || s === "no")
-        return false;
-    if (s === "1" || s === "true" || s === "on" || s === "yes")
-        return true;
-    return fallback;
-}
-function envFlagInt(env, key, fallback) {
-    const n = Number(env[key]);
-    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
-}
+import { envNumber, envString, envSwitch } from "../../engine/env.js";
+const positiveInt = (n, fallback) => (n !== undefined && n > 0 ? Math.floor(n) : fallback);
 /**
  * Resolve todo-dock UX from env + optional author patch.
- * `WAYGRAPH_TODO_UI=full|off|legacy` forces compact/collision/behindRing off.
+ * `WAYGRAPH_TODO_UI=full|off` forces compact/collision/behindRing off.
  */
-export function resolveTodoDockUi(patch, env = process.env) {
-    const mode = String(env.WAYGRAPH_TODO_UI || "smart")
+export function resolveTodoDockUi(patch) {
+    const mode = String(envString("WAYGRAPH_TODO_UI") || "smart")
         .trim()
         .toLowerCase();
-    const full = mode === "full" || mode === "off" || mode === "0" || mode === "legacy" || mode === "classic";
+    const full = mode === "full" || mode === "off" || mode === "0";
     const base = {
-        compact: full ? false : envFlagBool(env, "WAYGRAPH_TODO_COMPACT", true),
-        collision: full ? false : envFlagBool(env, "WAYGRAPH_TODO_COLLISION", true),
-        behindRing: full ? false : envFlagBool(env, "WAYGRAPH_TODO_BEHIND", true),
-        cap: envFlagInt(env, "WAYGRAPH_TODO_CAP", 5),
-        expandCap: envFlagInt(env, "WAYGRAPH_TODO_EXPAND_CAP", 14),
+        compact: full ? false : envSwitch("WAYGRAPH_TODO_COMPACT", true),
+        collision: full ? false : envSwitch("WAYGRAPH_TODO_COLLISION", true),
+        behindRing: full ? false : envSwitch("WAYGRAPH_TODO_BEHIND", true),
+        cap: positiveInt(envNumber("WAYGRAPH_TODO_CAP"), 5),
+        expandCap: positiveInt(envNumber("WAYGRAPH_TODO_EXPAND_CAP"), 14),
     };
     if (base.expandCap < base.cap)
         base.expandCap = base.cap;
@@ -96,7 +83,7 @@ export function normalizeTodos(todos, todoIndex, style = "sequential") {
                 item.done = !!t.done;
             if (t.current !== undefined)
                 item.current = !!t.current;
-            const idRaw = t.id ?? t.name;
+            const idRaw = t.id;
             if (idRaw != null && String(idRaw).trim())
                 item.id = String(idRaw).trim();
         }
@@ -135,7 +122,7 @@ export function buildTodoDock(opts) {
             const group = { style: gs, items };
             if (g.title && String(g.title).trim())
                 group.title = String(g.title).trim();
-            const gid = g.id ?? g.name;
+            const gid = g.id;
             if (gid != null && String(gid).trim())
                 group.id = String(gid).trim();
             return group;
@@ -209,8 +196,6 @@ export function advanceTodoDock(dock, index) {
                 const row = { text: it.text };
                 if (it.id)
                     row.id = it.id;
-                else if (it.name)
-                    row.id = it.name;
                 return row;
             });
             return {
@@ -238,8 +223,6 @@ export function completeSequentialTodoDock(dock) {
                     const row = { text: it.text, done: true, current: false };
                     if (it.id)
                         row.id = it.id;
-                    else if (it.name)
-                        row.id = it.name;
                     return row;
                 }),
             };

package/dist/demo/overlay/auto-chrome.d.ts

@@ -0,0 +1,7 @@
+import type { Page } from "@playwright/test";
+import type { MemPage } from "../../engine/mem/mem.js";
+export declare function installDemoChrome(page: Page, title?: string, options?: {
+    banner?: boolean;
+}): Promise<void>;
+/** Demo cursor + ring on fill/click during auto explore headful runs (automation = gray). */
+export declare function instrumentAutoInteractions(page: Page, mem: MemPage, slowMo: number): void;

package/dist/demo/overlay/auto-chrome.js

@@ -0,0 +1,97 @@
+import { ensureShadowRoot } from "./ui/shadow.js";
+import { installCore } from "./inpage/core.js";
+import { clickPulseAt, moveCursorTo } from "./cursor.js";
+import { hideRing } from "./rings.js";
+import { setLocatorTheater } from "./locator-theater.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
+export async function installDemoChrome(page, title = "waygraph auto", options = {}) {
+    const showBanner = options.banner !== false;
+    await ensureShadowRoot(page);
+    await page.evaluate(installCore, {}).catch(ignorePageGone);
+    await page
+        .evaluate(({ title, showBanner }) => {
+        if (showBanner && title && !__wgById("wg-banner")) {
+            const banner = document.createElement("div");
+            banner.id = "wg-banner";
+            const tag = document.createElement("span");
+            tag.className = "wg-banner-tag";
+            tag.textContent = "waygraph auto";
+            const text = document.createElement("span");
+            text.textContent = title;
+            banner.append(tag, text);
+            __wgAdd(banner);
+            banner.setAttribute("data-wg-ui", "1");
+            banner.setAttribute("data-wg-modal", "banner");
+            banner.setAttribute("data-wg-ready", "1");
+        }
+        else {
+            const existing = __wgById("wg-banner");
+            if (existing) {
+                existing.setAttribute("data-wg-ui", "1");
+                existing.setAttribute("data-wg-modal", "banner");
+                existing.setAttribute("data-wg-ready", "1");
+            }
+        }
+        if (showBanner && !document.title.startsWith("[waygraph] ")) {
+            document.title = "[waygraph] " + document.title;
+        }
+    }, { title, showBanner })
+        .catch(ignorePageGone);
+}
+async function showRing(page, box, label) {
+    await page.evaluate(({ box, label }) => window.__wgPositionRing?.(box, label, "auto"), { box, label }).catch(ignorePageGone);
+}
+/** Demo cursor + ring on fill/click during auto explore headful runs (automation = gray). */
+export function instrumentAutoInteractions(page, mem, slowMo) {
+    const typeDelay = () => (slowMo ? 0 : 30);
+    const clickPrePop = () => (slowMo ? 300 : 700);
+    const clickPostPop = () => (slowMo ? 200 : 500);
+    const cursorMs = (full) => full;
+    const memTrack = { lastKeyName: null, at: 0 };
+    const originalGet = mem.get.bind(mem);
+    mem.get = (key) => {
+        memTrack.lastKeyName = key?.name ?? null;
+        memTrack.at = Date.now();
+        return originalGet(key);
+    };
+    setLocatorTheater(page, {
+        async beforeFill(locator) {
+            await installDemoChrome(page, "", { banner: false });
+            const box = await locator.boundingBox();
+            if (!box)
+                return;
+            const label = memTrack.lastKeyName && Date.now() - memTrack.at < 3000 ? "from mem: " + memTrack.lastKeyName : "writing from mem";
+            await moveCursorTo(page, box, cursorMs(500));
+            await showRing(page, box, label);
+            await new Promise((res) => setTimeout(res, 200));
+        },
+        typingDelay: typeDelay,
+        async afterFill() {
+            await hideRing(page);
+        },
+        async beforeClick(locator, options) {
+            await installDemoChrome(page, "", { banner: false });
+            await locator.waitFor({ state: "visible", timeout: options?.timeout || 30000 }).catch(ignoreTimeout);
+            const box = await locator.boundingBox();
+            if (!box)
+                return "click";
+            let label = "click";
+            const text = (await locator.textContent().catch(() => null))?.trim();
+            if (text && text.length <= 30)
+                label = text;
+            const clickPoint = await moveCursorTo(page, box, cursorMs(600));
+            await showRing(page, box, label);
+            await new Promise((res) => setTimeout(res, clickPrePop()));
+            if (clickPoint) {
+                await clickPulseAt(page, clickPoint.x, clickPoint.y, "auto");
+                await new Promise((res) => setTimeout(res, 80));
+            }
+            return "click";
+        },
+        holdMs: () => 600,
+        async afterClick() {
+            await new Promise((res) => setTimeout(res, clickPostPop()));
+            await hideRing(page);
+        },
+    });
+}

package/dist/{session/overlay-beacon.d.ts → demo/overlay/beacon.d.ts}

@@ -10,11 +10,17 @@
  *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
  */
 import type { Page } from "@playwright/test";
+/** Selector matching every element waygraph's overlay draws into a page. */
 export declare const WG_UI_SEL = "[data-wg-ui=\"1\"]";
+/** Selector of the overlay element that appears when the step panel is ready. */
 export declare const WG_READY_PANEL_SEL = "[data-wg-modal=\"panel\"][data-wg-ready=\"1\"]";
+/** Selector of the overlay element that appears when the auto panel is ready. */
 export declare const WG_READY_AUTO_SEL = "[data-wg-modal=\"auto-panel\"][data-wg-ready=\"1\"]";
+/** Selector of the overlay element that appears when the banner is ready. */
 export declare const WG_READY_BANNER_SEL = "[data-wg-modal=\"banner\"][data-wg-ready=\"1\"]";
+/** The kind of modal the overlay beacon reports. */
 export type WgModalKind = "panel" | "banner" | "auto-panel";
+/** One overlay element a session reports through its beacon. */
 export type WgBeaconRow = {
     id: string | null;
     modal: string | null;
@@ -31,6 +37,7 @@ export type WgBeaconRow = {
 };
 /** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
 export declare function readWgOverlayBeaconInPage(): WgBeaconRow[];
+/** Reads the overlay beacon from a page: what waygraph's own UI is showing. */
 export declare function readWgOverlayBeacon(page: Page): Promise<WgBeaconRow[]>;
 /**
  * Hard gate: a blank / missing / opacity-0 modal fails.