waygraph 0.15.54 → 0.16.1

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

@@ -0,0 +1,293 @@
+export function installTodos({ todoPos }) {
+    // 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 { NetworkEntry, 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: NetworkEntry): 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;

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()?.errorText,
+        });
+    });
+}
+// 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;