waygraph 0.15.53 → 0.16.0

package/dist/demo/overlay/inpage/swipe-zoom.js

@@ -0,0 +1,220 @@
+// In-page (runs inside the browser via page.evaluate, must stay self-contained): swipe trails and ring zoom.
+export function installSwipeZoom({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) {
+    /**
+     * Finger swipe trail for touch theater (orientation rotate / device change).
+     * opts: { dir: 'left'|'right'|'up'|'down', label?, ms? }
+     * Returns duration waited (ms) via Promise when called from page.evaluate async.
+     */
+    window.__wgSwipeTrail = (opts) => {
+        const o = opts || {};
+        const dir = o.dir === "right" || o.dir === "up" || o.dir === "down" ? o.dir : "left";
+        const ms = Math.max(280, Math.min(1400, Number(o.ms) || 720));
+        const label = o.label ||
+            (dir === "left" || dir === "right" ? "swipe" : "swipe") +
+                (o.hint ? " \u00b7 " + o.hint : "");
+        let layer = __wgById("wg-swipe-layer");
+        if (layer && layer._wgTimer) {
+            clearTimeout(layer._wgTimer);
+            layer._wgTimer = undefined;
+        }
+        if (layer)
+            layer.remove();
+        layer = document.createElement("div");
+        layer.id = "wg-swipe-layer";
+        layer.setAttribute("data-wg-ui", "1");
+        const finger = document.createElement("div");
+        finger.className = "wg-swipe-finger";
+        const lab = document.createElement("div");
+        lab.className = "wg-swipe-label";
+        lab.textContent = label;
+        layer.appendChild(lab);
+        layer.appendChild(finger);
+        __wgAdd(layer);
+        const vw = window.innerWidth || 390;
+        const vh = window.innerHeight || 844;
+        const pad = Math.min(vw, vh) * 0.18;
+        let x0;
+        let y0;
+        let x1;
+        let y1;
+        if (dir === "left") {
+            x0 = vw - pad;
+            x1 = pad;
+            y0 = y1 = vh * 0.52;
+        }
+        else if (dir === "right") {
+            x0 = pad;
+            x1 = vw - pad;
+            y0 = y1 = vh * 0.52;
+        }
+        else if (dir === "up") {
+            x0 = x1 = vw * 0.5;
+            y0 = vh - pad;
+            y1 = pad;
+        }
+        else {
+            x0 = x1 = vw * 0.5;
+            y0 = pad;
+            y1 = vh - pad;
+        }
+        finger.style.left = x0 + "px";
+        finger.style.top = y0 + "px";
+        finger.style.opacity = "1";
+        void layer.offsetWidth;
+        layer.classList.add("wg-in");
+        const steps = 12;
+        const stepMs = Math.floor(ms / steps);
+        let i = 0;
+        const tick = () => {
+            i += 1;
+            const t = Math.min(1, i / steps);
+            const e = t * t * (3 - 2 * t);
+            const x = x0 + (x1 - x0) * e;
+            const y = y0 + (y1 - y0) * e;
+            finger.style.left = x + "px";
+            finger.style.top = y + "px";
+            const dot = document.createElement("div");
+            dot.className = "wg-swipe-dot";
+            dot.style.left = x + "px";
+            dot.style.top = y + "px";
+            dot.style.opacity = String(0.85 - t * 0.55);
+            layer.appendChild(dot);
+            requestAnimationFrame(() => {
+                dot.style.transition = "opacity .45s ease, transform .45s ease";
+                dot.style.opacity = "0";
+                dot.style.transform = "scale(1.8)";
+            });
+            if (i < steps) {
+                layer._wgTimer = setTimeout(tick, stepMs);
+            }
+            else {
+                finger.style.opacity = "0";
+                layer.classList.remove("wg-in");
+                layer._wgTimer = setTimeout(() => {
+                    const el = __wgById("wg-swipe-layer");
+                    if (el)
+                        el.remove();
+                }, 380);
+            }
+        };
+        layer._wgTimer = setTimeout(tick, 40);
+        return ms + 120;
+    };
+    window.__wgClearZoom = () => {
+        // Strip leftover element transforms from older zoom path.
+        document.querySelectorAll("[data-wg-zoomed=\"1\"]").forEach((el) => {
+            el.style.removeProperty("transform");
+            el.style.removeProperty("transform-origin");
+            el.style.removeProperty("transition");
+            el.style.removeProperty("z-index");
+            el.style.removeProperty("position");
+            delete el.dataset.wgZoomed;
+        });
+        // Undo any prior shell-camera experiment - restore device fit scale only.
+        const shell = __wgById("wg-device-shell");
+        if (shell && shell.dataset.wgCamBase != null) {
+            shell.style.transform = shell.dataset.wgCamBase;
+            if (shell.dataset.wgCamOrigin) {
+                shell.style.transformOrigin = shell.dataset.wgCamOrigin;
+            }
+            else {
+                shell.style.transformOrigin = "center center";
+            }
+            delete shell.dataset.wgCamBase;
+            delete shell.dataset.wgCamOrigin;
+            delete shell.dataset.wgCamZoom;
+        }
+        window.__wgZoomLevel = 1;
+        window.__wgZoomSel = "";
+        if (window.__wgSetZoomBadge)
+            window.__wgSetZoomBadge(1, "");
+    };
+    const ZOOM_ICO = '<svg viewBox="0 0 24 24" fill="none" stroke="#c9a6ff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
+        '<circle cx="11" cy="11" r="7"/><path d="M20 20l-3.5-3.5"/></svg>';
+    window.__wgSetZoomBadge = (scale, sel) => {
+        const n = Number(scale);
+        const level = Number.isFinite(n) && n > 0 ? n : 1;
+        let badge = __wgById("wg-zoom-badge");
+        if (!badge) {
+            badge = document.createElement("div");
+            badge.id = "wg-zoom-badge";
+            badge.setAttribute("data-wg-ui", "1");
+            __wgAdd(badge);
+        }
+        const zoomed = level > 1.001 || level < 0.999;
+        badge.dataset.zoomed = zoomed ? "1" : "0";
+        const txt = level.toFixed(2) + "\u00d7";
+        __wgSet(badge, __wgEl("span", { class: "wg-zoom-ico" }, __wgSvg(ZOOM_ICO)), __wgEl("span", { class: "wg-zoom-val" }, txt));
+        badge.classList.add("wg-in");
+        window.__wgZoomLevel = level;
+        window.__wgZoomSel = sel || "";
+    };
+    window.__wgEnsureZoomBadge = () => {
+        if (window.__wgSetZoomBadge) {
+            window.__wgSetZoomBadge(window.__wgZoomLevel || 1, window.__wgZoomSel || "");
+        }
+    };
+    window.__wgSetTypingBadge = (on, label) => {
+        let badge = __wgById("wg-typing-badge");
+        if (!on) {
+            if (badge) {
+                badge.classList.remove("wg-in");
+                setTimeout(() => {
+                    const b = __wgById("wg-typing-badge");
+                    if (b && !b.classList.contains("wg-in"))
+                        b.remove();
+                }, 220);
+            }
+            return;
+        }
+        if (!badge) {
+            badge = document.createElement("div");
+            badge.id = "wg-typing-badge";
+            badge.setAttribute("data-wg-ui", "1");
+            __wgAdd(badge);
+        }
+        const text = label ? String(label).slice(0, 40) : "typing";
+        __wgSet(badge, __wgEl("span", { class: "wg-ty-dots" }, "\u25cf\u25cf\u25cf"), __wgEl("span", null, "typing \u00b7 " + text));
+        void badge.offsetWidth;
+        badge.classList.add("wg-in");
+    };
+    /**
+     * Zoom HUD only - never CSS-scale the target or the device shell.
+     * Shell camera zoom fought device-theater fit-scale (broke ring follow
+     * + uneven border-radius). Element scale mangled cart rows. Emphasis
+     * is ring + focus veil; badge still shows authored zoom level.
+     */
+    window.__wgApplyZoom = (sel, scale) => {
+        document.querySelectorAll("[data-wg-zoomed=\"1\"]").forEach((el) => {
+            el.style.removeProperty("transform");
+            el.style.removeProperty("transform-origin");
+            el.style.removeProperty("transition");
+            el.style.removeProperty("z-index");
+            el.style.removeProperty("position");
+            delete el.dataset.wgZoomed;
+        });
+        const shell = __wgById("wg-device-shell");
+        if (shell && shell.dataset.wgCamBase != null) {
+            shell.style.transform = shell.dataset.wgCamBase;
+            shell.style.transformOrigin = shell.dataset.wgCamOrigin || "center center";
+            delete shell.dataset.wgCamBase;
+            delete shell.dataset.wgCamOrigin;
+            delete shell.dataset.wgCamZoom;
+        }
+        const n = Number(scale);
+        if (!Number.isFinite(n) || n <= 1.001) {
+            window.__wgZoomLevel = 1;
+            window.__wgZoomSel = "";
+            if (window.__wgSetZoomBadge)
+                window.__wgSetZoomBadge(1, "");
+            return;
+        }
+        window.__wgZoomLevel = n;
+        window.__wgZoomSel = sel || "";
+        if (window.__wgSetZoomBadge)
+            window.__wgSetZoomBadge(n, sel || "");
+    };
+    // Mount zoom HUD immediately so demos always show 1.00x.
+    if (window.__wgEnsureZoomBadge)
+        window.__wgEnsureZoomBadge();
+}

package/dist/demo/overlay/inpage/todos.d.ts

@@ -0,0 +1 @@
+export declare function installTodos({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }: any): void;

package/dist/demo/overlay/inpage/todos.js

@@ -0,0 +1,294 @@
+// In-page (runs inside the browser via page.evaluate, must stay self-contained): the todo dock(s).
+export function installTodos({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) {
+    // Floating todo dock - lives outside #wg-panel so --mini / Hide never
+    // hide the checklist. Click cycles left <-> right with CSS transform.
+    // Authors set side via ctx.todos(id, items, { pos }); env / --todo-* fallback.
+    // Payload:
+    //   { sync: "clear" }                         -> remove dock
+    //   { sync: "keep" }                          -> leave dock alone (no wipe)
+    //   { sync: "set", dock } / { sync:"set", list } -> render / recreate
+    window.__wgSyncTodos = (payload, pos) => {
+        const syncPayload = payload;
+        let sync = "set";
+        let list = [];
+        let dockState = null;
+        let wantPos = pos === "left" || pos === "right" ? pos : null;
+        if (payload && typeof payload === "object") {
+            sync = payload.sync === "clear" || payload.sync === "keep" ? payload.sync : "set";
+            dockState = payload.dock || null;
+            if (payload.pos === "left" || payload.pos === "right")
+                wantPos = payload.pos;
+            if (Array.isArray(payload.list))
+                list = payload.list;
+            else if (dockState && Array.isArray(dockState.groups)) {
+                // The flat list; the full dock is rendered below.
+                list = [];
+                for (const g of dockState.groups) {
+                    if (g && Array.isArray(g.items))
+                        list = list.concat(g.items);
+                }
+            }
+        }
+        else {
+            list = [];
+            sync = "clear";
+        }
+        let dockKey = (dockState && dockState.id && String(dockState.id).trim()) ||
+            (payload && !Array.isArray(payload) && payload.todoId && String(payload.todoId).trim()) ||
+            "_default";
+        // Drop any in-panel leftover (old builds put #wg-todos in .wg-body).
+        __wgQA("#wg-panel #wg-todos").forEach((el) => el.remove());
+        const allDocks = () => [...__wgQA(".wg-todo-dock, #wg-todo-dock")].filter((el, i, arr) => arr.indexOf(el) === i);
+        const relayoutTodoDocks = () => {
+            const docks = allDocks();
+            // Must match .wg-todo-dock/#wg-todo-dock's own CSS `top` (demo/overlay/overlay-css.ts,
+            // ui/css/dock.css) - this inline style OVERRIDES that CSS the instant more than one
+            // dock exists (multi-todo stacking), so a CSS-only change here is silently underwater;
+            // real bug this was: the CSS top was bumped 72 -> 104 for banner clearance, but this
+            // hardcoded 72 kept winning at runtime and nothing actually moved.
+            let top = 104;
+            for (const el of docks) {
+                el.style.top = top + "px";
+                top += Math.max(48, el.getBoundingClientRect().height) + 10;
+            }
+        };
+        const findDock = (key) => {
+            if (key === "_default") {
+                return (__wgQ('.wg-todo-dock[data-wg-todo-key="_default"]') ||
+                    __wgById("wg-todo-dock"));
+            }
+            const all = __wgQA(".wg-todo-dock");
+            for (let i = 0; i < all.length; i++) {
+                if (all[i].getAttribute("data-wg-todo-key") === String(key))
+                    return all[i];
+            }
+            return null;
+        };
+        // keep + no new payload: do not remove existing docks (PIA #10).
+        if (sync === "keep") {
+            if (!dockState && !list.length)
+                return;
+            // After navigation the DOM may be gone - recreate from carried dock.
+            sync = "set";
+        }
+        // Default replace=true: one checklist. parallel docks only when replace:false.
+        const replace = !(payload && !Array.isArray(payload) && payload.replace === false) &&
+            !(payload && !Array.isArray(payload) && payload.parallel === true);
+        const hasDock = !!(dockState && Array.isArray(dockState.groups) && dockState.groups.length);
+        // Explicit clear only - never treat "set + dock + empty list" as clear
+        // (that thrash was marks -> blank in a few ms).
+        if (sync === "clear" || (sync === "set" && !hasDock && !list.length)) {
+            const clearId = (payload && !Array.isArray(payload) && payload.todoId && String(payload.todoId).trim()) ||
+                (dockState && dockState.id && String(dockState.id).trim()) ||
+                "";
+            if (clearId && !replace) {
+                const el = findDock(clearId);
+                if (el)
+                    el.remove();
+            }
+            else {
+                allDocks().forEach((el) => el.remove());
+            }
+            relayoutTodoDocks();
+            return;
+        }
+        if (sync === "set" && replace) {
+            // Drop sibling docks so we never stack duplicates.
+            for (const el of allDocks()) {
+                const key = el.getAttribute("data-wg-todo-key") || "_default";
+                if (key !== dockKey)
+                    el.remove();
+            }
+        }
+        const POS = ["left", "right"];
+        let dock = findDock(dockKey);
+        if (!dock) {
+            dock = document.createElement("div");
+            dock.className = "wg-todo-dock";
+            dock.setAttribute("data-wg-todo-key", dockKey);
+            if (dockKey === "_default")
+                dock.id = "wg-todo-dock";
+            else
+                dock.id = "wg-todo-dock--" + dockKey.replace(/[^a-zA-Z0-9_-]/g, "-");
+            dock.setAttribute("data-wg-ui", "1");
+            dock.setAttribute("data-wg-modal", "todos");
+            dock.setAttribute("data-wg-ready", "1");
+            let saved = null;
+            try {
+                saved = localStorage.getItem("wg-todo-pos");
+            }
+            catch {
+                /* ignore */
+            }
+            const start = wantPos ||
+                (saved && POS.includes(saved) ? saved : todoPos === "right" ? "right" : "left");
+            dock.dataset.pos = start;
+            dock.title = "Click to move checklist: left / right";
+            dock.addEventListener("click", (e) => {
+                e.stopPropagation();
+                const i = POS.indexOf(dock.dataset.pos || "left");
+                const next = POS[(i + 1) % POS.length];
+                dock.dataset.pos = next;
+                try {
+                    localStorage.setItem("wg-todo-pos", next ?? "left");
+                }
+                catch {
+                    /* ignore */
+                }
+            });
+            __wgAdd(dock);
+        }
+        else if (wantPos) {
+            dock.dataset.pos = wantPos;
+            try {
+                localStorage.setItem("wg-todo-pos", wantPos);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        const trimmedId = (raw) => (raw != null && String(raw).trim() ? String(raw).trim() : undefined);
+        // Compact + cap: >cap rows folds overflow; hover shows up to expandCap; "+N more" pins expand.
+        const ui = (payload && !Array.isArray(payload) && payload.ui) || window.__wgTodoDockUi || {};
+        const COMPACT_AT = Number(ui.cap) > 0 ? Number(ui.cap) : 5;
+        const WINDOW = COMPACT_AT;
+        const EXPAND_MAX = Number(ui.expandCap) > 0 ? Number(ui.expandCap) : 14;
+        const compactEnabled = ui.compact !== false;
+        const flattenItems = () => {
+            if (dockState && Array.isArray(dockState.groups) && dockState.groups.length) {
+                const out = [];
+                for (const g of dockState.groups) {
+                    for (const t of g.items || [])
+                        out.push({ ...t, __style: g.style || dockState.style });
+                }
+                return out;
+            }
+            return (list || []).map((t) => ({ ...t, __style: "sequential" }));
+        };
+        const windowBounds = (items, cap) => {
+            const n = items.length;
+            if (n <= cap)
+                return { start: 0, end: n };
+            let cur = items.findIndex((t) => t.current);
+            if (cur < 0)
+                cur = items.findIndex((t) => !t.done);
+            if (cur < 0)
+                cur = 0;
+            let start = Math.max(0, cur - Math.floor((cap - 1) / 2));
+            let end = Math.min(n, start + cap);
+            start = Math.max(0, end - cap);
+            return { start, end };
+        };
+        const renderItems = (items, style, foldMeta, indexOffset) => {
+            const offset = indexOffset || 0;
+            const rawStyle = String(style || "sequential").toLowerCase();
+            const st = rawStyle === "checklist"
+                ? "checklist"
+                : rawStyle === "bullets" ||
+                    rawStyle === "bullet" ||
+                    rawStyle === "list" ||
+                    rawStyle === "ul" ||
+                    rawStyle === "points" ||
+                    rawStyle === "plain"
+                    ? "bullets"
+                    : "sequential";
+            const foldStart = foldMeta ? foldMeta.foldStart : -1;
+            const foldEnd = foldMeta ? foldMeta.foldEnd : -1;
+            const deepStart = foldMeta ? foldMeta.deepStart : -1;
+            const deepEnd = foldMeta ? foldMeta.deepEnd : -1;
+            return __wgEl("ul", { class: "wg-todos-list", data: { wgTodoStyle: st } }, (items || []).map((t, idx) => {
+                const gi = offset + idx;
+                const clsBase = st === "bullets"
+                    ? t.done
+                        ? "wg-todo-done"
+                        : "wg-todo-pending"
+                    : t.current
+                        ? "wg-todo-current"
+                        : t.done
+                            ? "wg-todo-done"
+                            : "wg-todo-pending";
+                let foldCls = "";
+                if (foldStart >= 0 && (gi < foldStart || gi >= foldEnd))
+                    foldCls += " wg-todo-fold";
+                if (deepStart >= 0 && (gi < deepStart || gi >= deepEnd))
+                    foldCls += " wg-todo-fold-deep";
+                let mark;
+                if (st === "checklist") {
+                    mark = t.done ? "☑" : "☐";
+                }
+                else if (st === "bullets") {
+                    mark = "•";
+                }
+                else {
+                    mark = t.done ? "✓" : t.current ? "→" : "○";
+                }
+                return __wgEl("li", { class: clsBase + foldCls, data: { wgTodoItem: trimmedId(t.id) } }, __wgEl("span", { class: "wg-todo-mark" }, mark), __wgEl("span", null, t.text || ""));
+            }));
+        };
+        if (dockKey !== "_default")
+            dock.setAttribute("data-wg-todo-id", dockKey);
+        else
+            dock.removeAttribute("data-wg-todo-id");
+        const flat = flattenItems();
+        const compact = compactEnabled && flat.length > COMPACT_AT;
+        const win = windowBounds(flat, WINDOW);
+        const expand = windowBounds(flat, EXPAND_MAX);
+        const foldMeta = compact
+            ? {
+                foldStart: win.start,
+                foldEnd: win.end,
+                deepStart: expand.start,
+                deepEnd: expand.end,
+            }
+            : null;
+        const hiddenCompact = compact ? flat.length - (win.end - win.start) : 0;
+        const hiddenExpand = compact ? flat.length - (expand.end - expand.start) : 0;
+        const children = [];
+        if (dockState && Array.isArray(dockState.groups) && dockState.groups.length) {
+            const dockTitle = dockState.title && String(dockState.title).trim();
+            if (dockTitle)
+                children.push(__wgEl("div", { class: "wg-todo-dock-title" }, dockTitle));
+            let globalIdx = 0;
+            for (const g of dockState.groups) {
+                const gTitle = g.title && String(g.title).trim();
+                const gItems = g.items || [];
+                children.push(__wgEl("div", { class: "wg-todo-group", data: { wgTodoGroup: trimmedId(g.id) } }, gTitle ? __wgEl("div", { class: "wg-todo-group-title" }, gTitle) : null, renderItems(gItems, g.style || dockState.style, foldMeta, globalIdx)));
+                globalIdx += gItems.length;
+            }
+        }
+        else {
+            children.push(renderItems(list, "sequential", foldMeta, 0));
+        }
+        if (compact && hiddenCompact > 0) {
+            const n = dock.dataset.expanded === "1" ? hiddenExpand : hiddenCompact;
+            if (n > 0) {
+                children.push(__wgEl("div", { class: "wg-todo-more", data: { wgTodoMore: "1" }, title: "Click to expand / collapse" }, "+" + n + " more"));
+            }
+        }
+        if (compact)
+            dock.dataset.compact = "1";
+        else {
+            delete dock.dataset.compact;
+            delete dock.dataset.expanded;
+        }
+        __wgSet(dock, children);
+        const moreBtn = dock.querySelector("[data-wg-todo-more]");
+        if (moreBtn) {
+            moreBtn.addEventListener("click", (e) => {
+                e.stopPropagation();
+                if (dock.dataset.expanded === "1")
+                    delete dock.dataset.expanded;
+                else
+                    dock.dataset.expanded = "1";
+                if (window.__wgSyncTodos && dock._wgLastPayload) {
+                    window.__wgSyncTodos(dock._wgLastPayload);
+                }
+            });
+        }
+        dock._wgLastPayload = syncPayload;
+        relayoutTodoDocks();
+        if (window.__wgStampModal) {
+            window.__wgStampModal(dock, "todos", { ready: true });
+        }
+    };
+}

package/dist/demo/overlay/locator-theater.d.ts

@@ -0,0 +1,25 @@
+import type { Locator, Page } from "@playwright/test";
+/** How a click is performed once the theater has shown it. */
+export type ClickGesture = "click" | "tap" | "hold";
+export interface LocatorTheater {
+    /** Before the value is typed: cursor, ring, typing badge. A failure here never stops the fill. */
+    beforeFill(locator: Locator, options: {
+        timeout?: number;
+    } | undefined): Promise<void>;
+    /** Per-character typing delay, ms. */
+    typingDelay(): number;
+    afterFill(locator: Locator): Promise<void>;
+    /** Before the click: cursor, ring, pulse. Returns the gesture to perform. A failure here never stops the click. */
+    beforeClick(locator: Locator, options: {
+        timeout?: number;
+    } | undefined): Promise<ClickGesture>;
+    /** How long a "hold" keeps the press down, ms. */
+    holdMs(): number;
+    afterClick(locator: Locator): Promise<void>;
+    /** A shorter timeout for a wait that may never succeed (a probe), or the declared one. */
+    capWait?(declaredMs: number): number;
+    /** A shorter plain sleep. */
+    capSleep?(ms: number): number;
+}
+/** Shows every fill and click on `page` through `theater` from now on. */
+export declare function setLocatorTheater(page: Page, theater: LocatorTheater): void;

package/dist/demo/overlay/locator-theater.js

@@ -0,0 +1,76 @@
+import { isPageGone } from "../../engine/page-gone.js";
+const theaters = new WeakMap();
+/** Shows every fill and click on `page` through `theater` from now on. */
+export function setLocatorTheater(page, theater) {
+    theaters.set(page, theater);
+    patchLocator(Object.getPrototypeOf(page.locator("html")));
+    patchPage(Object.getPrototypeOf(page));
+}
+/**
+ * The theater only shows the action; the action itself must still run. So a theater failure is printed (unless the page
+ * simply went away) and the real fill / click goes ahead.
+ */
+function theaterFailed(err) {
+    if (!isPageGone(err))
+        console.error(`waygraph: overlay: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`);
+    return undefined;
+}
+function patchLocator(proto) {
+    if (proto.__wgTheaterPatched)
+        return;
+    proto.__wgTheaterPatched = true;
+    const { fill, click, waitFor } = proto;
+    proto.fill = async function (value, options) {
+        const theater = theaters.get(this.page());
+        if (!theater)
+            return fill.call(this, value, options);
+        await theater.beforeFill(this, options).catch(theaterFailed);
+        try {
+            // Not this.clear(): Locator.clear() is fill(""), which would come back into this wrapper.
+            await fill.call(this, "", { ...(options?.timeout !== undefined ? { timeout: options.timeout } : {}) });
+            await this.pressSequentially(String(value), { delay: theater.typingDelay(), ...(options?.timeout !== undefined ? { timeout: options.timeout } : {}) });
+        }
+        catch {
+            // An element pressSequentially can't type into (a contenteditable, say): Playwright's own fill.
+            await fill.call(this, value, options);
+        }
+        await theater.afterFill(this);
+    };
+    proto.click = async function (options) {
+        const theater = theaters.get(this.page());
+        if (!theater)
+            return click.call(this, options);
+        const gesture = (await theater.beforeClick(this, options).catch(theaterFailed)) ?? "click";
+        if (gesture === "hold")
+            await click.call(this, { ...(options ?? {}), delay: theater.holdMs() });
+        else if (gesture === "tap") {
+            try {
+                await this.tap(options);
+            }
+            catch {
+                // A context without touch: a real click.
+                await click.call(this, options);
+            }
+        }
+        else
+            await click.call(this, options);
+        await theater.afterClick(this);
+    };
+    proto.waitFor = function (options) {
+        const theater = theaters.get(this.page());
+        if (!theater?.capWait)
+            return waitFor.call(this, options);
+        const declared = options?.timeout ?? 30000;
+        return waitFor.call(this, { ...(options ?? {}), timeout: theater.capWait(declared) });
+    };
+}
+function patchPage(proto) {
+    if (proto.__wgTheaterPatched)
+        return;
+    proto.__wgTheaterPatched = true;
+    const { waitForTimeout } = proto;
+    proto.waitForTimeout = function (ms) {
+        const theater = theaters.get(this);
+        return waitForTimeout.call(this, theater?.capSleep ? theater.capSleep(ms) : ms);
+    };
+}

package/dist/demo/overlay/network-capture.d.ts

@@ -0,0 +1,22 @@
+import type { WgPage } from "../types.js";
+/**
+ * Records one entry AND paints it live - the single place that touches page.__wgNetworkHistory,
+ * so every caller (this file's own listeners, defineApiBlock) stays in sync automatically. History
+ * 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 declare function recordNetworkEntry(page: WgPage, entry: any): Promise<void | undefined>;
+/**
+ * Replays whatever history survived the last navigation back into a freshly (re)installed panel -
+ * call this after ensureShadowRoot, every step, same as the rest of the overlay's own per-step
+ * 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 declare function restoreNetworkHistory(page: WgPage): Promise<void>;
+export declare function installNetworkCapture(page: WgPage): void;