waygraph 0.15.53 → 0.16.0

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

@@ -9,9 +9,13 @@
  * Agents: do not claim the stepper works unless
  *   `assertWgOverlayReady(page)` (or WAYGRAPH_PROVE_EXIT=1) passes.
  */
+/** Selector matching every element waygraph's overlay draws into a page. */
 export const WG_UI_SEL = '[data-wg-ui="1"]';
+/** Selector of the overlay element that appears when the step panel is ready. */
 export 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 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 const WG_READY_BANNER_SEL = '[data-wg-modal="banner"][data-wg-ready="1"]';
 /** Browser-side beacon reader (also installed as window.__wgOverlayBeacon). */
 export function readWgOverlayBeaconInPage() {
@@ -37,6 +41,7 @@ export function readWgOverlayBeaconInPage() {
         };
     });
 }
+/** Reads the overlay beacon from a page: what waygraph's own UI is showing. */
 export async function readWgOverlayBeacon(page) {
     return page.evaluate(() => {
         const w = window;

package/dist/demo/overlay/cursor.d.ts

@@ -0,0 +1,12 @@
+import type { WgBox, WgPage } from "../types.js";
+export declare function moveCursorTo(page: WgPage, box: WgBox, ms: number): Promise<{
+    x: number;
+    y: number;
+}>;
+export declare function clickPulseAt(page: WgPage, x: any, y: any, tone: any): Promise<void>;
+/**
+ * Touch swipe trail (mobile/tablet). dir: left|right|up|down.
+ * Returns after the trail animation completes.
+ * Self-contained when overlay helper is not installed yet (device runs before panel).
+ */
+export declare function playSwipeTrail(page: WgPage, opts: any): Promise<void>;

package/dist/demo/overlay/cursor.js

@@ -0,0 +1,142 @@
+// The demo cursor: travels to what a step clicks, pulses on the click, draws a swipe trail on touch devices.
+import { ignorePageGone } from "../../engine/page-gone.js";
+export async function moveCursorTo(page, box, ms) {
+    const x = box.x + box.width / 2;
+    const y = box.y + box.height / 2;
+    const travel = Math.max(0, Number(ms) || 0);
+    await page
+        .evaluate(({ x, y, ms }) => {
+        if (window.__wgMoveCursorTo)
+            window.__wgMoveCursorTo(x, y, ms);
+    }, { x, y, ms: travel })
+        .catch(ignorePageGone);
+    // CSS transition is async - wait the full travel so the cursor is ON the
+    // target before ring/pulse/real click (NavBlock click nav was skipping
+    // this and looked like a teleport).
+    if (travel > 0) {
+        await new Promise((res) => setTimeout(res, travel));
+    }
+    return { x, y };
+}
+export async function clickPulseAt(page, x, y, tone) {
+    await page
+        .evaluate(({ x, y, tone }) => {
+        if (window.__wgClickPulse)
+            window.__wgClickPulse(x, y, tone || "planned");
+    }, { x, y, tone: tone || "planned" })
+        .catch(ignorePageGone);
+}
+/**
+ * Touch swipe trail (mobile/tablet). dir: left|right|up|down.
+ * Returns after the trail animation completes.
+ * Self-contained when overlay helper is not installed yet (device runs before panel).
+ */
+export async function playSwipeTrail(page, opts) {
+    const o = opts || {};
+    const waitMs = await page
+        .evaluate((payload) => {
+        if (typeof window.__wgSwipeTrail === "function") {
+            return window.__wgSwipeTrail(payload);
+        }
+        // Fallback: inject a one-shot trail without full overlay install.
+        const dir = payload.dir === "right" || payload.dir === "up" || payload.dir === "down"
+            ? payload.dir
+            : "left";
+        const ms = Math.max(280, Math.min(1400, Number(payload.ms) || 720));
+        const label = payload.label || "swipe";
+        let layer = __wgById("wg-swipe-layer");
+        if (layer)
+            layer.remove();
+        layer = document.createElement("div");
+        layer.id = "wg-swipe-layer";
+        layer.setAttribute("data-wg-ui", "1");
+        layer.style.cssText =
+            "position:fixed;inset:0;z-index:2147483646;pointer-events:none;overflow:hidden;";
+        const finger = document.createElement("div");
+        finger.style.cssText =
+            "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);";
+        const lab = document.createElement("div");
+        lab.textContent = label;
+        lab.style.cssText =
+            "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;";
+        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";
+        const steps = 12;
+        const stepMs = Math.floor(ms / steps);
+        for (let i = 1; i <= steps; i++) {
+            const t = i / steps;
+            const e = t * t * (3 - 2 * t);
+            const x = x0 + (x1 - x0) * e;
+            const y = y0 + (y1 - y0) * e;
+            setTimeout(() => {
+                finger.style.left = x + "px";
+                finger.style.top = y + "px";
+                const dot = document.createElement("div");
+                dot.style.cssText =
+                    "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);left:" +
+                        x +
+                        "px;top:" +
+                        y +
+                        "px;opacity:" +
+                        (0.85 - t * 0.55) +
+                        ";transition:opacity .45s ease,transform .45s ease;";
+                layer.appendChild(dot);
+                requestAnimationFrame(() => {
+                    dot.style.opacity = "0";
+                    dot.style.transform = "scale(1.8)";
+                });
+                if (i === steps) {
+                    setTimeout(() => {
+                        const el = __wgById("wg-swipe-layer");
+                        if (el)
+                            el.remove();
+                    }, 400);
+                }
+            }, i * stepMs);
+        }
+        return ms + 120;
+    }, {
+        dir: o.dir || "left",
+        label: o.label || "swipe",
+        hint: o.hint || "",
+        ms: o.ms || 720,
+    })
+        .catch(() => 0);
+    const n = Number(waitMs) || 0;
+    if (n > 0)
+        await new Promise((r) => setTimeout(r, n));
+}

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

@@ -0,0 +1,13 @@
+import type { WgPage } from "../types.js";
+/**
+ * Video recording locks Playwright viewport to recordVideo.size. Shrinking
+ * setViewportSize to mobile/tablet letterboxes the .webm top-left. Instead keep
+ * the stage size and center a device-sized #wg-device-shell inside the frame.
+ */
+export declare function applyVideoDeviceStage(page: WgPage, target: any, stage: any, opts: any): Promise<void>;
+/**
+ * Apply authored device fixture to the live page (0.13+).
+ * Seamless viewport lerp + centered window + toast on set/clear.
+ * With --video: keep recordVideo stage size and center a device shell in-frame.
+ */
+export declare function applyDeviceToPage(page: WgPage, device: any, sync: any): Promise<void>;

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

@@ -0,0 +1,396 @@
+import { resolveDeviceState } from "../narration/device.js";
+import { envNumber } from "../../engine/env.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+/**
+ * Fit + center the OS browser window on the device viewport so mobile/tablet
+ * is not stuck top-left inside a maximized frame (0.13.4).
+ * Desktop clear restores maximized.
+ */
+async function fitWindowToDeviceViewport(page, viewport, opts) {
+    const maximize = !!(opts && opts.maximize);
+    let client;
+    try {
+        client = await page.context().newCDPSession(page);
+        const { windowId } = await client.send("Browser.getWindowForTarget");
+        if (maximize) {
+            await client.send("Browser.setWindowBounds", {
+                windowId,
+                bounds: { windowState: "maximized" },
+            });
+            return;
+        }
+        if (!viewport || !viewport.width || !viewport.height)
+            return;
+        const metrics = await page
+            .evaluate(() => {
+            const chromeW = Math.max(0, (window.outerWidth || 0) - (window.innerWidth || 0));
+            const chromeH = Math.max(0, (window.outerHeight || 0) - (window.innerHeight || 0));
+            return {
+                chromeW: Number.isFinite(chromeW) ? chromeW : 0,
+                // First paint after maximize often reports 0 chrome - use a floor.
+                chromeH: chromeH > 20 ? chromeH : 88,
+                screenW: window.screen.availWidth || 1920,
+                screenH: window.screen.availHeight || 1080,
+            };
+        })
+            .catch(() => ({ chromeW: 0, chromeH: 88, screenW: 1920, screenH: 1080 }));
+        // Leave maximized before setting pixel bounds (Chromium ignores size while max).
+        await client.send("Browser.setWindowBounds", {
+            windowId,
+            bounds: { windowState: "normal" },
+        });
+        const winW = Math.min(metrics.screenW, Math.max(320, Math.floor(viewport.width + metrics.chromeW)));
+        const winH = Math.min(metrics.screenH, Math.max(320, Math.floor(viewport.height + metrics.chromeH)));
+        const left = Math.max(0, Math.floor((metrics.screenW - winW) / 2));
+        const top = Math.max(0, Math.floor((metrics.screenH - winH) / 2));
+        await client.send("Browser.setWindowBounds", {
+            windowId,
+            bounds: {
+                windowState: "normal",
+                left,
+                top,
+                width: winW,
+                height: winH,
+            },
+        });
+    }
+    catch {
+        /* headless / no window - ignore */
+    }
+    finally {
+        if (client)
+            await client.detach().catch(ignorePageGone);
+    }
+}
+/**
+ * Video recording locks Playwright viewport to recordVideo.size. Shrinking
+ * setViewportSize to mobile/tablet letterboxes the .webm top-left. Instead keep
+ * the stage size and center a device-sized #wg-device-shell inside the frame.
+ */
+export async function applyVideoDeviceStage(page, target, stage, opts) {
+    const clear = !!(opts && opts.clear);
+    const shutterOut = !!(opts && opts.shutterOut);
+    const enterIn = !!(opts && opts.enterIn);
+    const desktopFlat = !!(opts && (opts.desktopFlat || opts.shutterOut));
+    const result = await page
+        .evaluate(({ tw, th, sw, sh, clear, shutterOut, enterIn, desktopFlat }) => {
+        const MATTE = "#0b1220";
+        const unwrap = () => {
+            const shell = document.getElementById("wg-device-shell");
+            if (shell) {
+                const parent = shell.parentNode;
+                if (parent) {
+                    while (shell.firstChild)
+                        parent.insertBefore(shell.firstChild, shell);
+                }
+                shell.remove();
+            }
+            document.documentElement.classList.remove("wg-video-device-stage");
+            document.documentElement.style.removeProperty("background");
+            const b = document.body;
+            if (b) {
+                b.style.margin = "";
+                b.style.minHeight = "";
+                b.style.display = "";
+                b.style.alignItems = "";
+                b.style.justifyContent = "";
+                b.style.background = "";
+                b.style.overflow = "";
+            }
+        };
+        if (clear) {
+            unwrap();
+            return { waitMs: 0 };
+        }
+        if (!document.body)
+            return { waitMs: 0 };
+        document.documentElement.classList.add("wg-video-device-stage");
+        document.documentElement.style.background = MATTE;
+        document.body.style.margin = "0";
+        document.body.style.minHeight = "100vh";
+        document.body.style.display = "flex";
+        document.body.style.alignItems = "center";
+        document.body.style.justifyContent = "center";
+        document.body.style.background = MATTE;
+        document.body.style.overflow = "hidden";
+        let shell = document.getElementById("wg-device-shell");
+        const created = !shell;
+        if (!shell) {
+            shell = document.createElement("div");
+            shell.id = "wg-device-shell";
+            const move = [];
+            for (const child of [...document.body.childNodes]) {
+                if (child.nodeType === 1 &&
+                    child.getAttribute &&
+                    child.getAttribute("data-wg-ui") === "1") {
+                    continue;
+                }
+                if (child.nodeType === 1 && child.id === "wg-device-shell")
+                    continue;
+                move.push(child);
+            }
+            for (const n of move)
+                shell.appendChild(n);
+            document.body.appendChild(shell);
+        }
+        // Desktop flat: always full-bleed, never reintroduce bezel on overlay rebuild.
+        if (desktopFlat) {
+            shell.classList.remove("wg-shell-enter");
+            shell.classList.add("wg-shell-shutter-out");
+            shell.classList.add("wg-shell-desktop-flat");
+            shell.style.width = sw + "px";
+            shell.style.height = sh + "px";
+            shell.style.maxWidth = sw + "px";
+            shell.style.maxHeight = sh + "px";
+            shell.style.transform = "scale(1)";
+            shell.style.transformOrigin = "center center";
+            shell.style.borderRadius = "0";
+            shell.style.boxShadow = "none";
+            shell.style.border = "none";
+            shell.style.outline = "none";
+            return { waitMs: shutterOut ? 480 : 0 };
+        }
+        // Leaving desktop-flat: clear INLINE radius/shadow overrides so CSS
+        // border-radius:16px applies evenly on all corners again.
+        shell.style.removeProperty("border-radius");
+        shell.style.removeProperty("box-shadow");
+        shell.style.removeProperty("border");
+        shell.style.removeProperty("outline");
+        if (enterIn && (created || shell.classList.contains("wg-shell-shutter-out"))) {
+            shell.classList.remove("wg-shell-shutter-out");
+            shell.classList.remove("wg-shell-desktop-flat");
+            shell.classList.add("wg-shell-enter");
+            void shell.offsetWidth;
+        }
+        const scale = Math.min(sw / tw, sh / th) * 0.92;
+        shell.style.width = tw + "px";
+        shell.style.height = th + "px";
+        shell.style.maxWidth = tw + "px";
+        shell.style.maxHeight = th + "px";
+        shell.style.transform = "scale(" + scale + ")";
+        shell.style.transformOrigin = "center center";
+        shell.classList.remove("wg-shell-shutter-out");
+        shell.classList.remove("wg-shell-desktop-flat");
+        if (enterIn && shell.classList.contains("wg-shell-enter")) {
+            requestAnimationFrame(() => {
+                shell.classList.remove("wg-shell-enter");
+            });
+            return { waitMs: 520 };
+        }
+        shell.classList.remove("wg-shell-enter");
+        return { waitMs: 0 };
+    }, {
+        tw: target.width,
+        th: target.height,
+        sw: stage.width,
+        sh: stage.height,
+        clear,
+        shutterOut,
+        enterIn,
+        desktopFlat,
+    })
+        .catch(() => ({ waitMs: 0 }));
+    const waitMs = result && result.waitMs ? Number(result.waitMs) : 0;
+    if (waitMs > 0)
+        await new Promise((r) => setTimeout(r, waitMs));
+}
+/**
+ * Apply authored device fixture to the live page (0.13+).
+ * Seamless viewport lerp + centered window + toast on set/clear.
+ * With --video: keep recordVideo stage size and center a device shell in-frame.
+ */
+export async function applyDeviceToPage(page, device, sync) {
+    const mode = sync || (device ? "set" : "keep");
+    if (mode === "keep" && !device)
+        return;
+    const d = device ||
+        resolveDeviceState("desktop", false) || {
+        preset: "desktop",
+        viewport: { width: 1280, height: 720, deviceScaleFactor: 1 },
+        isMobile: false,
+        hasTouch: false,
+        touchMode: false,
+    };
+    const realSet = typeof page.__wgRealSetViewportSize === "function"
+        ? page.__wgRealSetViewportSize
+        : page.setViewportSize.bind(page);
+    const target = {
+        width: Math.max(200, Math.floor(d.viewport.width)),
+        height: Math.max(200, Math.floor(d.viewport.height)),
+    };
+    const videoStage = page.__wgVideoViewport &&
+        page.__wgVideoViewport.width > 0 &&
+        page.__wgVideoViewport.height > 0
+        ? {
+            width: Math.floor(page.__wgVideoViewport.width),
+            height: Math.floor(page.__wgVideoViewport.height),
+        }
+        : null;
+    let from = null;
+    try {
+        from = page.viewportSize();
+    }
+    catch {
+        from = null;
+    }
+    // Non-headless (no --video) used to literally resize the real OS browser window/viewport to
+    // each device's pixel size - a real, confirmed complaint: it didn't look like the same animated
+    // device-shell bezel the --video path already has, just a plain resize. Both now use the exact
+    // same applyVideoDeviceStage bezel technique - the "stage" (the fixed outer viewport the shell is
+    // centered within) is the recordVideo canvas size when recording, or the window's own size at
+    // the FIRST device switch when not (captured once, persisted on the page - the window itself is
+    // only really resized that one time, to establish a stable stage; every device switch after that
+    // paints the animated shell inside it instead of resizing the window again).
+    let establishingHeadedStage = false;
+    if (!videoStage && !page.__wgHeadedStage) {
+        page.__wgHeadedStage =
+            from && from.width > 0 && from.height > 0 ? { width: from.width, height: from.height } : { width: 1280, height: 720 };
+        establishingHeadedStage = true;
+    }
+    const stage = videoStage || page.__wgHeadedStage;
+    const announce = mode === "set" || mode === "clear";
+    const toDesktop = mode === "clear" || (d.preset === "desktop" && !d.touchMode);
+    const shouldAnimate = announce &&
+        from &&
+        from.width > 0 &&
+        from.height > 0 &&
+        (from.width !== target.width || from.height !== target.height);
+    // Always clear camera zoom when returning to desktop (video + headed).
+    if (toDesktop) {
+        page.__wgDesktopFlat = true;
+        await page
+            .evaluate(() => {
+            window.__wgZoomOutOnHide = true;
+            if (window.__wgClearZoom)
+                window.__wgClearZoom();
+        })
+            .catch(ignorePageGone);
+    }
+    else if (announce) {
+        page.__wgDesktopFlat = false;
+    }
+    // Swipe trail is for scrolling (see ensureLocatorInView), not device morph.
+    const nextOrient = d.orientation === "landscape" || d.orientation === "portrait"
+        ? d.orientation
+        : target.height > target.width
+            ? "portrait"
+            : "landscape";
+    page.__wgDeviceOrient = nextOrient;
+    page.__wgDevicePreset = toDesktop ? "desktop" : d.preset || "";
+    if (stage) {
+        // Lock the Playwright viewport to the stage size so frames/window fill it; center the device
+        // shell inside (OS window centering alone does not). Do NOT fitWindow to the device size -
+        // that shrinks the viewport below the stage and (when recording) pads the .webm with grey
+        // (top-left bias). Headed-without-video reuses this exact technique (see `stage`'s own
+        // comment above) - the real OS window is only ever resized once, right here, to establish the
+        // stage itself; every device switch after that paints the animated shell inside it instead.
+        if (!videoStage && establishingHeadedStage) {
+            await fitWindowToDeviceViewport(page, stage, { maximize: false }).catch(ignorePageGone);
+        }
+        await realSet(stage).catch(ignorePageGone);
+        const shellFrom = page.__wgDeviceShell || target;
+        if (toDesktop) {
+            // Zoom already cleared above. Full-bleed desktop shell (no matte frame).
+            // Shutter-out: soft rounded -> radius 0, then flat edge-to-edge.
+            const desk = {
+                width: stage.width,
+                height: stage.height,
+            };
+            page.__wgDeviceShell = { ...desk };
+            await applyVideoDeviceStage(page, desk, stage, {
+                clear: false,
+                shutterOut: true,
+                desktopFlat: true,
+            });
+            await realSet(stage).catch(ignorePageGone);
+        }
+        else {
+            // Lerp shell size when switching mobile <-> tablet mid-run.
+            const firstDevice = !page.__wgDeviceShell;
+            if (announce &&
+                shellFrom &&
+                (shellFrom.width !== target.width || shellFrom.height !== target.height)) {
+                const steps = 14;
+                const ms = envNumber("WAYGRAPH_DEVICE_TRANSITION_MS") ?? 520;
+                const stepMs = Math.max(12, Math.floor(ms / steps));
+                for (let i = 1; i <= steps; i++) {
+                    const t = i / steps;
+                    const e = t * t * (3 - 2 * t);
+                    const mid = {
+                        width: Math.round(shellFrom.width + (target.width - shellFrom.width) * e),
+                        height: Math.round(shellFrom.height + (target.height - shellFrom.height) * e),
+                    };
+                    await applyVideoDeviceStage(page, mid, stage, {
+                        clear: false,
+                        enterIn: i === 1 && firstDevice,
+                    });
+                    if (i < steps)
+                        await new Promise((r) => setTimeout(r, stepMs));
+                }
+            }
+            else {
+                await applyVideoDeviceStage(page, target, stage, {
+                    clear: false,
+                    enterIn: firstDevice || announce,
+                });
+            }
+            page.__wgDeviceShell = { ...target };
+            // Re-assert stage size after any prior fitWindow.
+            await realSet(stage).catch(ignorePageGone);
+        }
+    }
+    else {
+        // Unmaximize + center early so the lerp does not sit in the corner of a
+        // maximized frame. Desktop clear maximizes at the end instead.
+        if (!toDesktop) {
+            await fitWindowToDeviceViewport(page, from && from.width ? from : target, {
+                maximize: false,
+            });
+        }
+        try {
+            if (shouldAnimate) {
+                const steps = 14;
+                const ms = envNumber("WAYGRAPH_DEVICE_TRANSITION_MS") ?? 520;
+                const stepMs = Math.max(12, Math.floor(ms / steps));
+                for (let i = 1; i <= steps; i++) {
+                    const t = i / steps;
+                    const e = t * t * (3 - 2 * t); // smoothstep
+                    const mid = {
+                        width: Math.round(from.width + (target.width - from.width) * e),
+                        height: Math.round(from.height + (target.height - from.height) * e),
+                    };
+                    await realSet(mid);
+                    if (!toDesktop && (i === 1 || i === steps || i % 3 === 0)) {
+                        await fitWindowToDeviceViewport(page, mid, { maximize: false });
+                    }
+                    if (i < steps)
+                        await new Promise((r) => setTimeout(r, stepMs));
+                }
+            }
+            else {
+                await realSet(target);
+            }
+        }
+        catch {
+            /* maximized / null viewport hosts may reject - toast still updates */
+        }
+        if (toDesktop) {
+            await fitWindowToDeviceViewport(page, target, { maximize: true });
+        }
+        else {
+            await fitWindowToDeviceViewport(page, target, { maximize: false });
+        }
+    }
+    // Fire toast near the end of the lerp so it reads as one seamless beat.
+    await page
+        .evaluate((payload) => {
+        if (window.__wgSyncDevice)
+            window.__wgSyncDevice(payload);
+    }, {
+        sync: mode,
+        device: d,
+        remain: mode === "keep" || mode === "set",
+        announce,
+    })
+        .catch(ignorePageGone);
+}

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

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