waygraph 0.15.53 → 0.16.0

package/dist/demo/stepper/stepper.js

@@ -0,0 +1,122 @@
+import { createOverlayStage } from "../overlay/overlay-stage.js";
+import { instrumentInteractionHighlighting } from "./interaction-patch.js";
+import { markStepRunning, restoreTheaterAfterNavigation, teardownOverlay } from "./teardown.js";
+import { keepOverlayOnNavigation } from "../overlay/reattach.js";
+import { presentFailPanel } from "./step-panels.js";
+import { installGate } from "./gate.js";
+import { newPacing, paceStep } from "./pacing.js";
+import { showBefore } from "./before.js";
+import { showAfter } from "./after.js";
+import { episodesOf, viewOf } from "./view.js";
+import { envFlag, envString } from "../../engine/env.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+export async function createStepper(page, mem, steps, options) {
+    const demoFast = envFlag("WAYGRAPH_DEMO_FAST");
+    const pacing = newPacing(demoFast);
+    const refs = { stubBefore: { current: [] }, todoDock: { current: undefined }, device: { current: undefined } };
+    instrumentInteractionHighlighting(page, mem, options.beat, pacing, refs.stubBefore, refs.todoDock, refs.device);
+    // A navigation inside a step (a redirect, a login bounce) repaints the overlay with the step's todos, device and ring.
+    keepOverlayOnNavigation(page, () => restoreTheaterAfterNavigation(page, refs.todoDock, refs.device, refs.stubBefore));
+    keepWindowSize(page);
+    const gate = await installGate(page, pacing, demoFast);
+    await gate.syncAutoplay();
+    const ctx = {
+        page,
+        mem,
+        steps,
+        stage: createOverlayStage(page, { todoDockRef: refs.todoDock, deviceRef: refs.device }),
+        gate,
+        pacing,
+        refs,
+        title: options.title,
+        stepperMode: envString("WAYGRAPH_STEPPER") === "full" ? "full" : "carousel",
+        stickyTitle: undefined,
+        allEpisodes: episodesOf(steps),
+    };
+    let view;
+    return {
+        afterReset: gate.syncAutoplay,
+        async before(index) {
+            view = viewOf(ctx, index);
+            paceStep(pacing, view.step, demoFast, options.fastBlocks);
+            await showBefore(ctx, view);
+            applyMemEdits(ctx, view, await gate.wait());
+            await markStepRunning(page, {});
+            await labelNavClick(page, view.step);
+        },
+        async after(_index, result) {
+            await stepRan(ctx);
+            await showAfter(ctx, view, result);
+        },
+        async failed(index, failure) {
+            await stepRan(ctx);
+            const step = view.step;
+            const edits = await presentFailPanel(page, {
+                block: step.block,
+                highlightStyle: step.highlightStyle,
+                error: failure.error,
+                ...(failure.result ? { out: failure.result } : {}),
+                index,
+                total: steps.length,
+                blockName: step.block.name,
+                message: failure.result
+                    ? "Resolved " + (failure.result.__state ?? JSON.stringify(failure.result)) + " (expected failure path)"
+                    : failure.error instanceof Error ? failure.error.message : String(failure.error),
+                allNames: view.moduleNames,
+                allDescriptions: view.moduleDescriptions,
+                moduleIndex: view.moduleIndex,
+                allEpisodes: ctx.allEpisodes,
+                title: options.title,
+                episodeNumber: step.episodeNumber,
+                episodeTitle: step.episodeTitle,
+                expectedFailureReason: step.expectedFailureReason,
+                stepperMode: ctx.stepperMode,
+                gatesFast: pacing.gatesFast,
+                demoPace: pacing.demoPace,
+                gate: gate.wait,
+                mem,
+            });
+            return edits && edits.__wgRetry ? "retry" : "stop";
+        },
+        end: () => teardownOverlay(page),
+    };
+}
+/**
+ * Some Blocks call page.setViewportSize() in their own act for their own tests; in a watched demo that would resize
+ * the window, so it does nothing here. An authored ctx.device() still resizes through __wgRealSetViewportSize.
+ */
+function keepWindowSize(page) {
+    page.__wgRealSetViewportSize = page.setViewportSize.bind(page);
+    page.setViewportSize = async () => { };
+}
+/** Values typed into the panel's mem fields replace the step's inputs (left as authored when not valid JSON). */
+function applyMemEdits(ctx, view, edits) {
+    for (const k of view.step.block.requires ?? []) {
+        if (edits[k.name] === undefined)
+            continue;
+        try {
+            ctx.mem.set(k, JSON.parse(edits[k.name]));
+        }
+        catch {
+            // left as-authored if the human's edit isn't valid JSON
+        }
+    }
+}
+/** A click-based Nav Block's cursor reads "nav: <block>", like any other Block's click. */
+async function labelNavClick(page, step) {
+    const label = step.block.__waygraphKind === "nav" && step.block.__waygraphNavClick !== undefined ? "nav: " + (step.block.name || "click") : undefined;
+    await page
+        .evaluate((l) => {
+        if (l)
+            window.__wgPendingNavClickLabel = l;
+        else
+            delete window.__wgPendingNavClickLabel;
+    }, label)
+        .catch(ignorePageGone);
+}
+/** The step finished: drop its nav label, and keep the todo dock it advanced for the steps after it. */
+async function stepRan(ctx) {
+    await ctx.page.evaluate(() => delete window.__wgPendingNavClickLabel).catch(ignorePageGone);
+    if (ctx.refs.todoDock.current)
+        ctx.stage.state.lastTodoDock = ctx.refs.todoDock.current;
+}

package/dist/demo/stepper/teardown.d.ts

@@ -0,0 +1,48 @@
+import type { WgPage } from "../types.js";
+/**
+ * Patches Locator.prototype.fill (via any real locator's own prototype
+ * chain - Playwright doesn't export the class directly) so every fill(),
+ * regardless of how the Block built that locator (page.locator, chained
+ * .getByLabel off a scoped form locator, etc.), highlights the real target
+ * first, then types it out character by character instead of snapping the
+ * whole value in - "when something is written from mem, it should
+ * highlight then slowly input." One-time patch (idempotent - guarded so a
+ * multi-step chain doesn't re-wrap an already-wrapped fill).
+ */
+/**
+ * Called once the gate resolves - manual click OR autoplay timeout, both
+ * covered from here rather than duplicating this in the in-page click
+ * handler - right before the Block's own act() actually starts. the user: "i
+ * want the button, step is running thing. so i wont be able to interrupt
+ * the playwright automation" - the "Run this step" button used to sit
+ * there still looking clickable for the entire multi-second duration a
+ * real act()/observe() takes, inviting a confusing extra click (harmless -
+ * __wgNext no-ops once already consumed - but looked live when it wasn't).
+ * Disables the button and mem-key textareas, and swaps whichever gate
+ * text was showing (manual button or "Auto-advancing...") to "Running...".
+ * ALWAYS collapses the panel while act() runs - leaving it expanded was a
+ * real bug: #wg-panel sits at z-index max with pointer-events:auto, so
+ * Playwright's login/add-to-cart clicks hit the stepper instead of the app
+ * ("subtree intercepts pointer events"). Empty/partial fills + a lucky
+ * edge click on Login then produced Sauce Demo's Epic sadface, verify
+ * still passed on the error banner, and the next block blew up. Collapse
+ * also matches the user's "step is running / can't interrupt" ask. (_opts kept
+ * for call-site compat; autoCollapsePanel is now unconditional.)
+ */
+export declare function markStepRunning(page: WgPage, _opts: any): Promise<void>;
+/**
+ * Real navigation wipes document + overlay helpers. Reinstall and re-paint
+ * carried todos / device / optional stubBefore ring so keep-dock and nav
+ * highlights do not vanish until the next ctx.todos() / stubAfter (PIA #15).
+ */
+export declare function restoreTheaterAfterNavigation(page: WgPage, todoDockRef: any, deviceRef: any, stubBeforeRef: any): Promise<void>;
+/**
+ * Removes every overlay element (panel, ring, ring-label, cursor,
+ * click-pulse, banner) and stops the live resize/scroll ring tracker, once
+ * the whole chain is genuinely done - "I want to see the same page just
+ * like the demo opened for the first time," not the last step's panel and
+ * highlight ring stuck over the real app forever. installOverlay only ever
+ * ADDS these elements back on demand (idempotent, per-page-load) - nothing
+ * re-creates them once torn down here unless another Block/fill/click runs.
+ */
+export declare function teardownOverlay(page: WgPage): Promise<void>;

package/dist/demo/stepper/teardown.js

@@ -0,0 +1,179 @@
+import { installOverlay } from "../overlay/overlay.js";
+import { applyDeviceToPage } from "../overlay/device-stage.js";
+import { showRing } from "../overlay/rings.js";
+import { formatHighlightCaption } from "../narration/style.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+/**
+ * Patches Locator.prototype.fill (via any real locator's own prototype
+ * chain - Playwright doesn't export the class directly) so every fill(),
+ * regardless of how the Block built that locator (page.locator, chained
+ * .getByLabel off a scoped form locator, etc.), highlights the real target
+ * first, then types it out character by character instead of snapping the
+ * whole value in - "when something is written from mem, it should
+ * highlight then slowly input." One-time patch (idempotent - guarded so a
+ * multi-step chain doesn't re-wrap an already-wrapped fill).
+ */
+/**
+ * Called once the gate resolves - manual click OR autoplay timeout, both
+ * covered from here rather than duplicating this in the in-page click
+ * handler - right before the Block's own act() actually starts. the user: "i
+ * want the button, step is running thing. so i wont be able to interrupt
+ * the playwright automation" - the "Run this step" button used to sit
+ * there still looking clickable for the entire multi-second duration a
+ * real act()/observe() takes, inviting a confusing extra click (harmless -
+ * __wgNext no-ops once already consumed - but looked live when it wasn't).
+ * Disables the button and mem-key textareas, and swaps whichever gate
+ * text was showing (manual button or "Auto-advancing...") to "Running...".
+ * ALWAYS collapses the panel while act() runs - leaving it expanded was a
+ * real bug: #wg-panel sits at z-index max with pointer-events:auto, so
+ * Playwright's login/add-to-cart clicks hit the stepper instead of the app
+ * ("subtree intercepts pointer events"). Empty/partial fills + a lucky
+ * edge click on Login then produced Sauce Demo's Epic sadface, verify
+ * still passed on the error banner, and the next block blew up. Collapse
+ * also matches the user's "step is running / can't interrupt" ask. (_opts kept
+ * for call-site compat; autoCollapsePanel is now unconditional.)
+ */
+export async function markStepRunning(page, _opts) {
+    await page
+        .evaluate(() => {
+        const runBtn = __wgById("wg-run");
+        if (runBtn) {
+            runBtn.disabled = true;
+            runBtn.textContent = "Running \u25B6";
+        }
+        const autoEl = __wgById("wg-gate-auto");
+        if (autoEl)
+            autoEl.textContent = "Running...";
+        __wgQA("#wg-panel textarea[data-key]").forEach((ta) => {
+            ta.disabled = true;
+        });
+        const panel = __wgById("wg-panel");
+        if (panel) {
+            panel.classList.add("wg-collapsed");
+            panel.setAttribute("data-wg-collapsed", "1");
+            panel.setAttribute("data-wg-phase", "running");
+            if (typeof window.__wgStampModal === "function") {
+                window.__wgStampModal(panel, "panel", {
+                    phase: "running",
+                    ready: true,
+                });
+            }
+            const toggle = panel.querySelector("[data-wg-toggle]");
+            if (toggle)
+                toggle.textContent = "Show";
+            const titleEl = panel.querySelector(".wg-chrome-title");
+            const label = panel.dataset.wgStepLabel;
+            if (titleEl && label)
+                titleEl.textContent = label;
+            const miniNext = panel.querySelector("[data-wg-mini-next]");
+            if (miniNext) {
+                miniNext.disabled = true;
+                miniNext.classList.remove("wg-mini-next-show");
+            }
+        }
+    })
+        .catch(ignorePageGone);
+}
+/**
+ * Real navigation wipes document + overlay helpers. Reinstall and re-paint
+ * carried todos / device / optional stubBefore ring so keep-dock and nav
+ * highlights do not vanish until the next ctx.todos() / stubAfter (PIA #15).
+ */
+export async function restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef) {
+    const needs = (await page
+        .evaluate(() => !window.__wgSyncTodos || !__wgById("wg-ring"))
+        .catch(() => true)) || false;
+    if (!needs) {
+        // Overlay survived (SPA / no full document wipe) - still refresh dock
+        // if Node has a carry and the DOM lost .wg-todo-dock.
+        const hasDock = await page
+            .evaluate(() => !!__wgQ(".wg-todo-dock, #wg-todo-dock"))
+            .catch(() => false);
+        if (hasDock || !todoDockRef || !todoDockRef.current)
+            return;
+    }
+    await installOverlay(page);
+    const dock = todoDockRef && todoDockRef.current;
+    if (dock) {
+        await page
+            .evaluate((d) => {
+            if (window.__wgSyncTodos)
+                window.__wgSyncTodos({ sync: "set", dock: d });
+        }, dock)
+            .catch(ignorePageGone);
+    }
+    if (deviceRef && deviceRef.current) {
+        await applyDeviceToPage(page, deviceRef.current, "set").catch(ignorePageGone);
+    }
+    // Re-show first matching stubBefore ring if selector still exists (sidebar
+    // nav targets often survive the route change).
+    const stubs = (stubBeforeRef && stubBeforeRef.current) || [];
+    for (const h of stubs) {
+        if (!h || !h.selector)
+            continue;
+        // Playwright's own locator (>> piercing / :has-text() / :visible support), not a raw
+        // querySelector string - see rings.js's showRing for the same fix, same reason. count() gate:
+        // Locator.evaluate() has no timeout option and auto-waits ~30s for a match to appear - count()
+        // never waits, keeping this an immediate "does it still exist" check (this selector routinely
+        // won't, after a route change - that's the whole point of the loop).
+        const hLoc = page.locator(h.selector).first();
+        const box = (await hLoc.count().catch(() => 0)) > 0
+            ? await hLoc
+                .evaluate((el) => {
+                const r = el.getBoundingClientRect();
+                if (r.width < 2 || r.height < 2)
+                    return null;
+                return { x: r.x, y: r.y, width: r.width, height: r.height };
+            })
+                .catch(() => null)
+            : null;
+        if (box) {
+            await showRing(page, box, formatHighlightCaption(h), h.tone || "planned", {
+                size: h.size,
+                weight: h.weight,
+                selector: h.selector,
+                focus: !!h.focus,
+            }).catch(ignorePageGone);
+            break;
+        }
+    }
+}
+/**
+ * Removes every overlay element (panel, ring, ring-label, cursor,
+ * click-pulse, banner) and stops the live resize/scroll ring tracker, once
+ * the whole chain is genuinely done - "I want to see the same page just
+ * like the demo opened for the first time," not the last step's panel and
+ * highlight ring stuck over the real app forever. installOverlay only ever
+ * ADDS these elements back on demand (idempotent, per-page-load) - nothing
+ * re-creates them once torn down here unless another Block/fill/click runs.
+ */
+export async function teardownOverlay(page) {
+    await page
+        .evaluate(() => {
+        if (window.__wgRingTrack) {
+            window.removeEventListener("resize", window.__wgRingTrack);
+            window.removeEventListener("scroll", window.__wgRingTrack, true);
+            window.__wgRingTrack = null;
+        }
+        window.__wgNarrateOwnsRing = false;
+        for (const id of [
+            "wg-panel",
+            "wg-ring",
+            "wg-ring-label",
+            "wg-cursor",
+            "wg-click-pulse",
+            "wg-banner",
+            "wg-todo-dock",
+            "wg-device-shell",
+            "wg-device-toast",
+            "wg-device-badge",
+        ]) {
+            const el = __wgById(id);
+            if (el)
+                el.remove();
+        }
+        __wgQA(".wg-todo-dock").forEach((el) => el.remove());
+        document.documentElement.classList.remove("wg-video-device-stage");
+    })
+        .catch(ignorePageGone);
+}

package/dist/demo/stepper/todo-advance.d.ts

@@ -0,0 +1,14 @@
+import type { WgPage } from "../types.js";
+/** Advance sequential todo dock to stubIndex and push to the page (Method act). */
+export declare function syncTodoDockAdvance(page: WgPage, todoDockRef: any, stubIndex: number, stub: any): Promise<void>;
+export declare function probeTodoDocksOnPage(page: WgPage): Promise<never[] | {
+    key: string;
+    pos: string;
+    top: number;
+    left: number;
+    w: number;
+    h: number;
+    onScreen: boolean;
+    n: number;
+    current: string;
+}[]>;

package/dist/demo/stepper/todo-advance.js

@@ -0,0 +1,110 @@
+import { advanceTodoDock } from "../narration/todo-dock.js";
+import { demoLog } from "./demo-log.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+/** Flatten dock items in order (sequential groups). */
+function flattenTodoDockItems(dock) {
+    const items = [];
+    if (!dock || !dock.groups)
+        return items;
+    for (const g of dock.groups) {
+        for (const t of g.items || [])
+            items.push(t);
+    }
+    return items;
+}
+/**
+ * Resolve which todo index a matched stub should advance to.
+ * Prefer stub.todo / stub.slotId / stub.id against item.id; never jump backward.
+ */
+function resolveTodoAdvanceIndex(dock, stub, stubIndex) {
+    const items = flattenTodoDockItems(dock);
+    if (!items.length)
+        return stubIndex;
+    const curIdx = items.findIndex((t) => t.current);
+    let idx = stubIndex;
+    const key = stub && (stub.todo || stub.slotId || stub.id);
+    if (key) {
+        const k = String(key).trim().toLowerCase();
+        let found = items.findIndex((t) => t.id && String(t.id).toLowerCase() === k);
+        if (found < 0) {
+            // username -> login-user, password -> login-pass, submit -> login-submit
+            const aliases = {
+                username: ["login-user", "user", "email"],
+                password: ["login-pass", "pass"],
+                submit: ["login-submit", "login", "tap-login"],
+                user: ["login-user", "username"],
+                pass: ["login-pass", "password"],
+            };
+            const alts = aliases[k] || [];
+            for (const a of alts) {
+                found = items.findIndex((t) => t.id && String(t.id).toLowerCase() === a);
+                if (found >= 0)
+                    break;
+            }
+        }
+        if (found < 0) {
+            found = items.findIndex((t) => (t.id && String(t.id).toLowerCase().includes(k)) ||
+                (t.text && String(t.text).toLowerCase().includes(k)));
+        }
+        if (found >= 0)
+            idx = found;
+    }
+    // Monotonic: never retreat the walkthrough.
+    if (curIdx >= 0 && idx < curIdx)
+        idx = curIdx;
+    return idx;
+}
+/** Advance sequential todo dock to stubIndex and push to the page (Method act). */
+export async function syncTodoDockAdvance(page, todoDockRef, stubIndex, stub) {
+    if (!todoDockRef || stubIndex < 0)
+        return;
+    const prev = todoDockRef.current;
+    if (!prev)
+        return;
+    const idx = resolveTodoAdvanceIndex(prev, stub || null, stubIndex);
+    const advanced = advanceTodoDock(prev, idx);
+    todoDockRef.current = advanced;
+    demoLog("  todo advance -> idx=" +
+        idx +
+        (stub && (stub.slotId || stub.todo)
+            ? " slot=" + (stub.todo || stub.slotId)
+            : " stub#" + stubIndex) +
+        ' current="' +
+        String((flattenTodoDockItems(advanced).find((t) => t.current) || {}).text || "").slice(0, 40) +
+        '"');
+    await page
+        .evaluate((dock) => {
+        if (window.__wgSyncTodos) {
+            window.__wgSyncTodos({ sync: "set", dock });
+        }
+    }, advanced)
+        .catch(ignorePageGone);
+}
+export async function probeTodoDocksOnPage(page) {
+    return page
+        .evaluate(() => {
+        const docks = [...__wgQA(".wg-todo-dock, #wg-todo-dock")];
+        return docks.map((el) => {
+            const r = el.getBoundingClientRect();
+            const items = el.querySelectorAll("li");
+            let current = "";
+            items.forEach((li) => {
+                if (li.classList.contains("wg-todo-current")) {
+                    current = (li.textContent || "").replace(/s+/g, " ").trim().slice(0, 48);
+                }
+            });
+            return {
+                key: el.getAttribute("data-wg-todo-key") || el.id || "?",
+                pos: el.dataset.pos || "?",
+                top: Math.round(r.top),
+                left: Math.round(r.left),
+                w: Math.round(r.width),
+                h: Math.round(r.height),
+                onScreen: r.bottom > 0 && r.right > 0 && r.top < innerHeight && r.left < innerWidth,
+                n: items.length,
+                current,
+            };
+        });
+    })
+        .catch(() => []);
+}

package/dist/demo/stepper/view.d.ts

@@ -0,0 +1,68 @@
+import type { MemPage } from "../../engine/mem/mem.js";
+import type { Block } from "../../engine/block/block.js";
+import type { DemoPace } from "../../engine/stub/pace.js";
+import type { HighlightStyleDefaults } from "../../engine/stub/ring.js";
+import type { WgPage } from "../types.js";
+import type { createOverlayStage } from "../overlay/overlay-stage.js";
+import type { Gate } from "./gate.js";
+import type { Pacing } from "./pacing.js";
+/** A step as the stepper sees it (the runner's PlayStep). */
+export interface StepperStep {
+    block: Block<any, any> & {
+        description?: string;
+        fastForward?: boolean;
+        demoPace?: DemoPace;
+        __waygraphKind?: string;
+        __waygraphNavClick?: unknown;
+    };
+    episodeNumber?: number | undefined;
+    episodeTitle?: string | undefined;
+    expectedFailureReason?: string | undefined;
+    demoPace?: DemoPace | undefined;
+    highlightStyle?: HighlightStyleDefaults | undefined;
+    wasFastForward?: boolean | undefined;
+}
+/** The stepper's state for the whole run. */
+export interface StepperContext {
+    page: WgPage;
+    mem: MemPage;
+    steps: readonly StepperStep[];
+    stage: ReturnType<typeof createOverlayStage>;
+    gate: Gate;
+    pacing: Pacing;
+    refs: {
+        stubBefore: {
+            current: any[];
+        };
+        todoDock: {
+            current: any;
+        };
+        device: {
+            current: any;
+        };
+    };
+    title: string | undefined;
+    stepperMode: "full" | "carousel";
+    /** A title set by a stub (`ctx.title`) names the flow from that step on, until another stub sets a new one. */
+    stickyTitle: string | undefined;
+    allEpisodes: {
+        episodeNumber: number;
+        episodeTitle: string;
+    }[];
+}
+/** The current step: where it sits in its episode, and what its before panel showed. */
+export interface StepView {
+    index: number;
+    step: StepperStep;
+    /** The breadcrumb is this step's episode ("1st of 2"), or the whole chain when there are no episodes. */
+    moduleNames: string[];
+    moduleDescriptions: string[];
+    moduleIndex: number;
+    justEnteredEpisode: boolean;
+    overlayTitle: string;
+    overlayTodoPos: string | undefined;
+}
+export declare function episodesOf(steps: readonly StepperStep[]): StepperContext["allEpisodes"];
+export declare function viewOf(ctx: StepperContext, index: number): StepView;
+/** Video and --mini get the compact pill; never false, so the person's Hide/Show choice wins otherwise. */
+export declare function forceCollapsed(): true | undefined;

package/dist/demo/stepper/view.js

@@ -0,0 +1,31 @@
+import { envFlag, envString } from "../../engine/env.js";
+export function episodesOf(steps) {
+    const episodes = [];
+    for (const s of steps) {
+        if (s.episodeNumber && !episodes.some((e) => e.episodeNumber === s.episodeNumber)) {
+            episodes.push({ episodeNumber: s.episodeNumber, episodeTitle: s.episodeTitle ?? "" });
+        }
+    }
+    return episodes;
+}
+export function viewOf(ctx, index) {
+    const step = ctx.steps[index];
+    const indices = step.episodeNumber
+        ? ctx.steps.flatMap((s, i) => (s.episodeNumber === step.episodeNumber ? [i] : []))
+        : ctx.steps.map((_s, i) => i);
+    const moduleIndex = indices.indexOf(index);
+    return {
+        index,
+        step,
+        moduleNames: indices.map((i) => ctx.steps[i].block.name),
+        moduleDescriptions: indices.map((i) => ctx.steps[i].block.description || ""),
+        moduleIndex,
+        justEnteredEpisode: moduleIndex === 0 && step.episodeNumber !== undefined,
+        overlayTitle: ctx.title || "waygraph demo",
+        overlayTodoPos: undefined,
+    };
+}
+/** Video and --mini get the compact pill; never false, so the person's Hide/Show choice wins otherwise. */
+export function forceCollapsed() {
+    return envString("WAYGRAPH_VIDEO") || envFlag("WAYGRAPH_MINI") ? true : undefined;
+}

package/dist/demo/types.d.ts

@@ -0,0 +1,17 @@
+import type { Page } from "@playwright/test";
+export type WgPage = Page;
+declare module "playwright-core" {
+    interface Page {
+        [key: `__wg${string}`]: any;
+    }
+    interface Keyboard {
+        __wgBeatPatched?: boolean;
+    }
+}
+/** A box on the page, in CSS pixels. */
+export interface WgBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}

package/dist/demo/verbose-log.js

@@ -0,0 +1,15 @@
+import { envFlag } from "../engine/env.js";
+/**
+ * One log format for the live overlay surfaces (auto / browser / pilot): `[HH:MM:SS.mmm] waygraph <surface>: ...`, the
+ * same shape as the demo runner's `step-mode/demo-log.ts`. Silenced by WAYGRAPH_JSON=1.
+ */
+function ts() {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, "0");
+    return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, "0")}`;
+}
+export function verboseLog(surface, msg) {
+    if (envFlag("WAYGRAPH_JSON"))
+        return;
+    console.log(`[${ts()}] waygraph ${surface}: ${msg}`);
+}