waygraph 0.15.54 → 0.16.1

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. */
@@ -31,11 +31,11 @@ export declare function buildTodoDock(opts: {
  * - keep: author omitted todos — preserve previous dock (do not wipe)
  */
 export declare function applyTodoPhase(prev: TodoDockState | undefined, phase: {
-    todoSync?: "set" | "clear" | "keep";
-    todoDock?: TodoDockState;
-    todos?: WaygraphTodoItem[];
-    todoPos?: "left" | "right";
-    todoId?: string;
+    todoSync?: "set" | "clear" | "keep" | undefined;
+    todoDock?: TodoDockState | undefined;
+    todos?: WaygraphTodoItem[] | undefined;
+    todoPos?: "left" | "right" | undefined;
+    todoId?: string | undefined;
 }): {
     dock: TodoDockState | undefined;
     sync: "set" | "clear" | "keep";

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/demo/overlay/cursor.d.ts

@@ -0,0 +1,19 @@
+import type { WgBox, WgPage } from "../types.js";
+/** A touch swipe: which way, its caption (plus an optional hint) and how long it takes. */
+export interface SwipeTrailOptions {
+    dir?: "left" | "right" | "up" | "down";
+    label?: string;
+    hint?: string;
+    ms?: number;
+}
+export declare function moveCursorTo(page: WgPage, box: WgBox, ms: number): Promise<{
+    x: number;
+    y: number;
+}>;
+export declare function clickPulseAt(page: WgPage, x: number, y: number, tone?: string): 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?: SwipeTrailOptions): 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(ignorePageGone);
+    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,26 @@
+import type { DeviceState } from "../../engine/stub/viewport.js";
+import type { WgPage } from "../types.js";
+interface Size {
+    width: number;
+    height: number;
+}
+/** How a device-shell change animates: clear it, shutter out to desktop, enter in, or stay flat. */
+interface DeviceStageOptions {
+    clear?: boolean;
+    shutterOut?: boolean;
+    enterIn?: boolean;
+    desktopFlat?: boolean;
+}
+/**
+ * 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: Size, stage: Size, opts?: DeviceStageOptions): 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: DeviceState | null | undefined, sync?: string): Promise<void>;
+export {};