waygraph 0.15.54 → 0.16.1

package/dist/{pilot-overlay/action-ring.js → demo/overlay/pilot/actions.js}

@@ -1,4 +1,5 @@
 import { ensureInstalled } from "./shell.js";
+import { ignorePageGone } from "../../../engine/page-gone.js";
 /** Paint the gray "auto" ring (Playwright is about to act here) at a viewport rectangle. */
 async function showPilotRect(page, box, label, tone = "auto") {
     await ensureInstalled(page);
@@ -30,7 +31,7 @@ async function showPilotRect(page, box, label, tone = "auto") {
             tag.style.opacity = "0";
         }, 4_000);
     }, { box, label, tone })
-        .catch(() => { });
+        .catch(ignorePageGone);
 }
 const LOCATOR_ACTIONS = ["click", "dblclick", "hover", "tap", "fill", "check", "uncheck", "selectOption", "press", "pressSequentially", "setInputFiles"];
 const patched = new WeakSet();

package/dist/{pilot-overlay → demo/overlay/pilot}/fixtures.d.ts

@@ -1,4 +1,7 @@
-import type { BannerPos, BannerUiOpts, DevicePreset, DeviceState, HighlightTone, TodoDockUiOpts, TodoListStyle, WaygraphTodoGroupInput } from "../highlights.js";
+import type { BannerPos, BannerUiOpts } from "../../../engine/stub/stub.js";
+import type { DevicePreset, DeviceState } from "../../../engine/stub/viewport.js";
+import type { HighlightTone } from "../../../engine/stub/ring.js";
+import type { TodoDockUiOpts, TodoListStyle, WaygraphTodoGroupInput } from "../../../engine/stub/todos.js";
 import type { Page } from "@playwright/test";
 /** One ring the Pilot agent wants painted (same fields as demo stub rings). */
 export type PilotFixtureRing = {
@@ -26,7 +29,7 @@ export type PilotFixtureRing = {
 };
 /**
  * Agent-sent highlight fixtures for a live Pilot / auto session.
- * Painted by {@link showPilotFixtures}; driven via IPC `op: "highlight"`.
+ * Painted by `showPilotFixtures`; driven via IPC `op: "highlight"`.
  * Mirrors demo stub surface: rings, todos, zoom, focus, device.
  */
 export type PilotHighlightFixtures = {
@@ -40,7 +43,7 @@ export type PilotHighlightFixtures = {
     todoTitle?: string;
     /** Todo dock side. Default `right`. */
     todoPos?: "left" | "right";
-    /** Presentation: `sequential` (default, arrow walkthrough) | `checklist` | `bullets`. Same as ctx.todoStyle. */
+    /** Presentation: `sequential` (default, arrow walkthrough) | `checklist` | `bullets`. Same as ctx.todos(id, items, { style }). */
     todoStyle?: TodoListStyle;
     /** Multiple titled lists (FR/Scenarios/ACs, same as ctx.todoGroups) - replaces {@link todos} when set. */
     todoGroups?: readonly WaygraphTodoGroupInput[];
@@ -78,8 +81,6 @@ export type PilotHighlightFixtures = {
     titlePos?: BannerPos;
     /** Banner UX: collision / hidden (same as `ctx.bannerUi`). */
     bannerUi?: BannerUiOpts;
-    /** Alias of {@link todoUi} - the name `ctx.todoDockUi` uses. */
-    todoDockUi?: TodoDockUiOpts;
 };
 /**
  * Paint (or clear) agent-authored highlight fixtures on the live page.

package/dist/{pilot-overlay → demo/overlay/pilot}/fixtures.js

@@ -1,7 +1,10 @@
-// Split out of the former 950-line pilot-overlay.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { buildTodoDock, formatHighlightCaption, normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight, resolveDeviceState, resolveTodoDockUi } from "../highlights.js";
+import { buildTodoDock, resolveTodoDockUi } from "../../narration/todo-dock.js";
+import { formatHighlightCaption } from "../../narration/style.js";
+import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../../../engine/stub/ring.js";
+import { resolveDeviceState } from "../../narration/device.js";
 import { ensureInstalled } from "./shell.js";
-import { verboseLog } from "../auto-session/verbose-log.js";
+import { verboseLog } from "../../verbose-log.js";
+import { ignorePageGone } from "../../../engine/page-gone.js";
 /**
  * Paint (or clear) agent-authored highlight fixtures on the live page.
  * Multi-ring + optional todo strip + zoom/focus/device - the Pilot equivalent
@@ -44,7 +47,7 @@ export async function showPilotFixtures(page, fixtures) {
     const todoPos = fixtures.todoPos === "left" ? "left" : "right";
     const todoUi = resolveTodoDockUi(fixtures.todoUi ?? null);
     // Real TodoDockState (groups/style), same builder the demo runner uses - not a flat string[]
-    // re-implementation, so a Block/agent that authors ctx.todoGroups()/ctx.todoStyle() looks the
+    // re-implementation, so a Block/agent that authors ctx.todoGroups() or a todos style looks the
     // same on Pilot as it does in `waygraph demo`.
     const todoDock = fixtures.clear
         ? undefined
@@ -84,31 +87,31 @@ export async function showPilotFixtures(page, fixtures) {
         if (hit?.zoomOut !== undefined)
             zoomOut = hit.zoomOut !== false;
     }
-    // Device viewport - same runner/device-stage.js + inpage/device.js every other surface uses
+    // Device viewport - same demo/overlay/device-stage.ts + inpage/device.ts every other surface uses
     // (toast + persistent chip + touch mode), not a separate, simpler Pilot-only chip.
     if (fixtures.clear === true) {
-        const { applyDeviceToPage } = await import("../runner/device-stage.js");
-        await applyDeviceToPage(page, undefined, "clear").catch(() => { });
+        const { applyDeviceToPage } = await import("../device-stage.js");
+        await applyDeviceToPage(page, undefined, "clear").catch(ignorePageGone);
     }
     else if (fixtures.device !== undefined) {
         const d = resolveDeviceState(fixtures.device);
         if (d) {
             const [{ applyDeviceToPage }, { installDevice }] = await Promise.all([
-                import("../runner/device-stage.js"),
-                import("../runner/inpage/device.js"),
+                import("../device-stage.js"),
+                import("../inpage/device-chip.js"),
             ]);
-            await page.evaluate(installDevice, {}).catch(() => { });
-            await applyDeviceToPage(page, d, "set").catch(() => { });
+            await page.evaluate(installDevice, {}).catch(ignorePageGone);
+            await applyDeviceToPage(page, d, "set").catch(ignorePageGone);
         }
     }
     const bannerTitle = fixtures.clear ? undefined : fixtures.title;
     const bannerPos = fixtures.clear ? undefined : fixtures.titlePos;
     const bannerHidden = !!fixtures.clear || !!fixtures.bannerUi?.hidden;
     const bannerCollision = fixtures.bannerUi?.collision !== false;
-    // Same #wg-banner installer the demo runner uses (runner/inpage/banner.js) - not a separate
+    // Same #wg-banner installer the demo runner uses (demo/overlay/inpage/banner.ts) - not a separate
     // re-implementation. `tag: "waygraph pilot"` is the only Pilot-specific bit.
     if (bannerTitle !== undefined || bannerHidden) {
-        const { installBanner } = await import("../runner/inpage/banner.js");
+        const { installBanner } = await import("../inpage/banner.js");
         await page
             .evaluate(installBanner, {
             title: bannerTitle,
@@ -116,7 +119,7 @@ export async function showPilotFixtures(page, fixtures) {
             bannerUi: { hidden: bannerHidden, collision: bannerCollision, ...(bannerPos ? { pos: bannerPos } : {}) },
             tag: "waygraph pilot",
         })
-            .catch(() => { });
+            .catch(ignorePageGone);
     }
     // Resolve every ring's box (and the zoom target, if any) through Playwright's own locator, not a
     // selector string handed to the page for a raw DOM querySelector to fail silently on - >>
@@ -185,9 +188,7 @@ export async function showPilotFixtures(page, fixtures) {
             }
             const zoomed = level > 1.001 || level < 0.999;
             badge.dataset.zoomed = zoomed ? "1" : "0";
-            badge.innerHTML =
-                '<span class="wg-pilot-fx-zoom-ico"><svg viewBox="0 0 24 24" fill="none" stroke="#fde68a" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="M20 20l-3.5-3.5"/></svg></span>' +
-                    `<span class="wg-pilot-fx-zoom-val">${level.toFixed(2)}\u00d7</span>`;
+            __wgSet(badge, __wgEl("span", { class: "wg-pilot-fx-zoom-ico" }, __wgSvg('<svg viewBox="0 0 24 24" fill="none" stroke="#fde68a" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="M20 20l-3.5-3.5"/></svg>')), __wgEl("span", { class: "wg-pilot-fx-zoom-val" }, level.toFixed(2) + "\u00d7"));
         };
         const clearZoom = () => {
             // Undo any leftover CSS-scale from older Pilot zoom path.
@@ -217,7 +218,7 @@ export async function showPilotFixtures(page, fixtures) {
         let painted = 0;
         let focusBox = null;
         // Paint through the SAME shared ring primitive the demo/auto singleton ring uses
-        // (window.__wgPaintRingAt, installed by runner/inpage/core.js's installCore - see
+        // (window.__wgPaintRingAt, installed by demo/overlay/inpage/core.ts's installCore - see
         // ensureInstalled) - one ring implementation, not a separate DOM-building copy here.
         rings.forEach((ring, i) => {
             const box = ringBoxes[i];

package/dist/{pilot-overlay → demo/overlay/pilot}/shell.d.ts

@@ -1,4 +1,4 @@
-import type { HighlightTone } from "../highlights.js";
+import type { HighlightTone } from "../../../engine/stub/ring.js";
 import type { BrowserContext, Page } from "@playwright/test";
 /**
  * Re-install the overlay shell on every navigation (about:blank, goto, etc.)
@@ -26,7 +26,7 @@ export declare function showPilotActivity(page: Page, text: string): Promise<voi
  * JSON blob in a terminal. Real, direct user request.
  *
  * Reuses the real `#wg-ring`/`#wg-ring-label` elements + `WAYGRAPH_RING_CSS`
- * (see `highlights.ts`) - the exact same visual language `cli.ts`'s own demo
+ * (see `demo/narration/index.ts`) - the exact same visual language `cli.ts`'s own demo
  * stepper paints rings with, not a separate look-alike. Still a purpose-built
  * renderer here (position/show/hide only, via plain `getBoundingClientRect` -
  * no camera zoom/spotlight/todo-dock/pacing), since that whole engine still

package/dist/{pilot-overlay → demo/overlay/pilot}/shell.js

@@ -1,7 +1,7 @@
-// Split out of the former 950-line pilot-overlay.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { SURFACE } from "../ui/tokens.js";
 import { ensureShadowRoot, installShadowRoot } from "../ui/shadow.js";
-import { verboseLog } from "../auto-session/verbose-log.js";
+import { verboseLog } from "../../verbose-log.js";
+import { ignorePageGone } from "../../../engine/page-gone.js";
 // Real, direct user request: this overlay's own colors were an improvised
 // purple/white scheme (#a78bfa / #1a1033) that didn't match anything else -
 // "our design here seems like barely shares with the ui on the stepper
@@ -64,7 +64,7 @@ const OVERLAY_CSS = `
 }
 #wg-pilot-activity.wg-pilot-toast-show { opacity: 1; transform: translateY(0); }
 /* Agent fixture rings (painted via the shared .wg-ring-el primitive, see ui/css/ring.css and
-   runner/inpage/core.js's __wgPaintRingAt), #wg-pilot-fx-todos, #wg-ring/#wg-ring-label and
+   demo/overlay/inpage/core.ts's __wgPaintRingAt), #wg-pilot-fx-todos, #wg-ring/#wg-ring-label and
    #wg-banner all come from the ONE shared bundle ensureShadowRoot installs (ui/css/*.css) - not
    redefined here. */
 /* Spotlight (demo focus:true) - dim page, cutout around target. */
@@ -96,16 +96,7 @@ function installPilotOverlayShell(css) {
     if (__wgById("wg-pilot-overlay"))
         return;
     __wgCss(css, "wg-pilot-overlay-css");
-    const root = document.createElement("div");
-    root.id = "wg-pilot-overlay";
-    root.innerHTML =
-        '<div id="wg-pilot-badge">Waygraph Pilot</div>' +
-            '<div id="wg-pilot-panel">' +
-            '<div id="wg-pilot-panel-toggle"><button id="wg-pilot-view-current" class="wg-pilot-tab-active">Here</button>' +
-            '<button id="wg-pilot-view-graph">All nodes</button></div>' +
-            '<div id="wg-pilot-panel-current"></div>' +
-            '<div id="wg-pilot-panel-graph" style="display:none"></div>' +
-            "</div>";
+    const root = __wgEl("div", { id: "wg-pilot-overlay" }, __wgEl("div", { id: "wg-pilot-badge" }, "Waygraph Pilot"), __wgEl("div", { id: "wg-pilot-panel" }, __wgEl("div", { id: "wg-pilot-panel-toggle" }, __wgEl("button", { id: "wg-pilot-view-current", class: "wg-pilot-tab-active" }, "Here"), __wgEl("button", { id: "wg-pilot-view-graph" }, "All nodes")), __wgEl("div", { id: "wg-pilot-panel-current" }), __wgEl("div", { id: "wg-pilot-panel-graph", style: "display:none" })));
     __wgAdd(root);
     __wgById("wg-pilot-badge").addEventListener("click", () => {
         __wgById("wg-pilot-panel").classList.toggle("wg-pilot-open");
@@ -150,16 +141,16 @@ export async function installPersistentPilotOverlay(context) {
 /** Idempotent - safe to call before every update, matching narrate mode's own precedent. */
 export async function ensureInstalled(page) {
     await ensureShadowRoot(page);
-    await page.evaluate(installPilotOverlayShell, OVERLAY_CSS).catch(() => { });
+    await page.evaluate(installPilotOverlayShell, OVERLAY_CSS).catch(ignorePageGone);
     // The shared ring primitive (__wgEnsureRingEl/__wgPaintRingAt) - so Pilot's fixture rings paint
     // through the SAME implementation the demo/auto singleton ring uses (see ui/css/ring.css / this
     // file's own header comment on redundancy), not a separate DOM-building copy.
-    const { installCore } = await import("../runner/inpage/core.js");
-    await page.evaluate(installCore, {}).catch(() => { });
-    // Device toast/chip CSS (runner/overlay-css.js's RUNNER_EXTRA_CSS) - same rules the demo runner
+    const { installCore } = await import("../inpage/core.js");
+    await page.evaluate(installCore, {}).catch(ignorePageGone);
+    // Device toast/chip CSS (demo/overlay/overlay-css.ts's RUNNER_EXTRA_CSS) - same rules the demo runner
     // uses, reused here (not re-authored) so a device fixture looks identical on Pilot.
-    const { RUNNER_EXTRA_CSS } = await import("../runner/overlay-css.js");
-    await page.evaluate(([css, key]) => __wgCss(css, key), [RUNNER_EXTRA_CSS, "wg-runner-css"]).catch(() => { });
+    const { RUNNER_EXTRA_CSS } = await import("../overlay-css.js");
+    await page.evaluate(([css, key]) => __wgCss(css, key), [RUNNER_EXTRA_CSS, "wg-runner-css"]).catch(ignorePageGone);
 }
 /**
  * Bottom-left transient toast, separate from the persistent bottom-right
@@ -187,7 +178,7 @@ export async function showPilotActivity(page, text) {
             toast.classList.remove("wg-pilot-toast-show");
         }, 2500);
     }, text)
-        .catch(() => { });
+        .catch(ignorePageGone);
 }
 /**
  * "browser-use"-style vision box: a ring drawn around the exact element
@@ -196,7 +187,7 @@ export async function showPilotActivity(page, text) {
  * JSON blob in a terminal. Real, direct user request.
  *
  * Reuses the real `#wg-ring`/`#wg-ring-label` elements + `WAYGRAPH_RING_CSS`
- * (see `highlights.ts`) - the exact same visual language `cli.ts`'s own demo
+ * (see `demo/narration/index.ts`) - the exact same visual language `cli.ts`'s own demo
  * stepper paints rings with, not a separate look-alike. Still a purpose-built
  * renderer here (position/show/hide only, via plain `getBoundingClientRect` -
  * no camera zoom/spotlight/todo-dock/pacing), since that whole engine still
@@ -276,5 +267,5 @@ export async function showPilotVision(page, selector, label, tone = "auto") {
             tag.style.opacity = "0";
         }, 4_000);
     }, { box, label, tone })
-        .catch(() => { });
+        .catch(ignorePageGone);
 }

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

@@ -0,0 +1,7 @@
+import type { Page } from "@playwright/test";
+type Repaint = () => Promise<unknown>;
+/** Repaints the page's overlay now, after any repaint already running (two never interleave). */
+export declare function repaintOverlay(page: Page): Promise<void>;
+/** Registers (or replaces) how this page's overlay repaints itself after a navigation. */
+export declare function keepOverlayOnNavigation(page: Page, repaint: Repaint): void;
+export {};

package/dist/demo/overlay/reattach.js

@@ -0,0 +1,23 @@
+import { ignorePageGone } from "../../engine/page-gone.js";
+const repaints = new WeakMap();
+const running = new WeakMap();
+/** Repaints the page's overlay now, after any repaint already running (two never interleave). */
+export function repaintOverlay(page) {
+    const next = (running.get(page) ?? Promise.resolve()).then(async () => {
+        await repaints.get(page)?.();
+    }).catch(ignorePageGone);
+    running.set(page, next);
+    return next;
+}
+/** Registers (or replaces) how this page's overlay repaints itself after a navigation. */
+export function keepOverlayOnNavigation(page, repaint) {
+    const listening = repaints.has(page);
+    repaints.set(page, repaint);
+    if (listening)
+        return;
+    let settle;
+    page.on("load", () => {
+        clearTimeout(settle);
+        settle = setTimeout(() => void repaintOverlay(page), 80);
+    });
+}

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

@@ -0,0 +1,61 @@
+import type { WgBox, WgPage } from "../types.js";
+import type { Locator } from "@playwright/test";
+import type { ResolvedHighlight } from "../../engine/stub/ring.js";
+import type { DemoPace } from "../../engine/stub/pace.js";
+import type { TodoDockState, WaygraphTodoItem } from "../../engine/stub/todos.js";
+import type { Pacing } from "../stepper/pacing.js";
+/**
+ * Scroll a locator into view for demo theater.
+ * Prefer CSS smooth scroll + scrollend wait. Do NOT call Playwright's
+ * scrollIntoViewIfNeeded first - that jumps instantly and makes the
+ * following smooth scroll a no-op (looks like a teleport), especially
+ * noticeable under --fast when dwell is shorter.
+ * Pass opts.instant=true only for skipTheater / blitz.
+ */
+export declare function ensureLocatorInView(locator: Locator, opts?: {
+    instant?: boolean;
+}): Promise<void>;
+export declare function ensureSelectorInView(page: WgPage, selector: string, opts?: {
+    instant?: boolean;
+}): Promise<void>;
+export declare function applyHighlightZoom(page: WgPage, selector: string | undefined, zoom: number | undefined, zoomOut: boolean | undefined): Promise<void>;
+/** How `cycleHighlightRings` plays a step's rings: hold times, pace, and the todo dock it moves along. */
+export interface CycleRingsOptions {
+    /** Hold for each ring when it sets none (the failure path holds longer). */
+    defaultHoldMs?: number;
+    pace?: DemoPace | undefined;
+    todoDock?: TodoDockState | undefined;
+    todos?: readonly WaygraphTodoItem[] | undefined;
+    todoSync?: "set" | "clear" | "keep" | undefined;
+    todoDockRef?: {
+        current: TodoDockState | undefined;
+    } | undefined;
+    /** False when the stub already set the dock's progress. */
+    advanceTodos?: boolean;
+    stepLabel?: string;
+}
+export declare function cycleHighlightRings(page: WgPage, highlights: readonly ResolvedHighlight[] | undefined, gatesFast: boolean, opts?: CycleRingsOptions): Promise<void>;
+export declare function showRing(page: WgPage, box: WgBox, label: string, tone: string | undefined, style?: {
+    size?: string | undefined;
+    weight?: string | undefined;
+    selector?: string | undefined;
+    focus?: boolean;
+}): Promise<void>;
+/** The stubBefore ring a locator is, by overlapping bounding boxes: its index, or -1. For a Method's todo advance. */
+export declare function matchStubIndexForLocator(page: WgPage, locator: Locator, stubs: readonly ResolvedHighlight[] | undefined): Promise<number>;
+export declare function captionForLocator(page: WgPage, locator: Locator, stubs: readonly ResolvedHighlight[] | undefined, fallback: string): Promise<{
+    label: string;
+    tone: string;
+    size: string;
+    weight: string;
+}>;
+export declare function dwellMatchedStub(page: WgPage, locator: Locator, stubs: readonly ResolvedHighlight[] | undefined, pacing: Pick<Pacing, "gatesFast" | "demoPace"> | undefined): Promise<void>;
+export declare function hideRing(page: WgPage): Promise<void>;
+/**
+ * True if the engine's own narrate() (waygraph's public export, for a Block
+ * author explicitly captioning one action) JUST positioned the ring for
+ * THIS action, moments ago - the automatic per-fill/per-click narration
+ * below should not immediately overwrite an author's own explicit caption
+ * with its generic guess.
+ */
+export declare function wasJustNarrated(page: WgPage): Promise<boolean>;