waygraph 0.15.28 → 0.15.30

package/dist/pilot-overlay/fixtures.d.ts

@@ -0,0 +1,81 @@
+import type { DevicePreset, DeviceState, HighlightTone, TodoDockUiOpts } from "../highlights.js";
+import type { Page } from "@playwright/test";
+/** One ring the Pilot agent wants painted (same fields as demo stub rings). */
+export type PilotFixtureRing = {
+    selector: string;
+    label: string;
+    /** Extra caption line (demo `detail`). */
+    detail?: string;
+    /** Short badge, e.g. AC / BUG / GATE. */
+    tag?: string;
+    /** Any {@link HighlightTone} or alias (`error`/`blue`/…). Normalized on paint. */
+    tone?: HighlightTone | string;
+    size?: "sm" | "md" | "lg" | string;
+    weight?: "normal" | "bold" | string;
+    /** Caption text color (CSS). Overrides tone label color when set. */
+    color?: string;
+    /**
+     * Camera zoom while this ring is up (demo parity: scroll + zoom badge;
+     * does not CSS-scale the page). Typical `1.25`..`2`.
+     */
+    zoom?: number;
+    /** When false, keep zoom after this paint / holdMs. Default true. */
+    zoomOut?: boolean;
+    /** Spotlight: dim the rest of the page around this target. */
+    focus?: boolean;
+};
+/**
+ * Agent-sent highlight fixtures for a live Pilot / auto session.
+ * Painted by {@link showPilotFixtures}; driven via IPC `op: "highlight"`.
+ * Mirrors demo stub surface: rings, todos, zoom, focus, device.
+ */
+export type PilotHighlightFixtures = {
+    /** Replace current fixture rings with these (empty + no todos = clear). */
+    rings?: readonly PilotFixtureRing[];
+    /** Optional floating todo list (demo-dock language, simplified). */
+    todos?: readonly string[];
+    /** 0-based index of the "current" todo row (others before it = done). */
+    todoIndex?: number;
+    /** Optional title above the todo list. */
+    todoTitle?: string;
+    /** Todo dock side. Default `right`. */
+    todoPos?: "left" | "right";
+    /**
+     * Todo-dock UX (compact / collision / behind-ring). Defaults smart-on;
+     * pass false fields to opt out. See {@link TodoDockUiOpts}.
+     */
+    todoUi?: TodoDockUiOpts;
+    /**
+     * How long fixtures stay visible (ms). `0` = until the next highlight /
+     * clear. Default `30000` (30s) unless specified.
+     */
+    holdMs?: number;
+    /**
+     * Camera zoom toward a selector (demo parity: scrollIntoView + zoom badge).
+     * Defaults the zoom target to {@link zoomSelector}, else the last ring's
+     * selector (or a ring that sets its own `zoom`). Cleared on `clear: true`
+     * or when holdMs expires (if zoomOut).
+     */
+    zoom?: number;
+    /** Element to zoom toward when {@link zoom} is set (defaults to last ring). */
+    zoomSelector?: string;
+    /** When false, keep zoom after fixtures clear/expire. Default true. */
+    zoomOut?: boolean;
+    /**
+     * Viewport / device fixture (`mobile` | `tablet` | `desktop`, or a full
+     * {@link DeviceState}). Applied via Playwright `setViewportSize`.
+     */
+    device?: DevicePreset | DeviceState;
+    /** Drop every agent fixture ring/todo/focus/zoom immediately. */
+    clear?: boolean;
+};
+/**
+ * Paint (or clear) agent-authored highlight fixtures on the live page.
+ * Multi-ring + optional todo strip + zoom/focus/device - the Pilot equivalent
+ * of Block `stubBefore` narration in `waygraph demo`.
+ * Does not import `cli.ts` (see file header).
+ */
+export declare function showPilotFixtures(page: Page, fixtures: PilotHighlightFixtures): Promise<{
+    painted: number;
+    missing: string[];
+}>;

package/dist/pilot-overlay/fixtures.js

@@ -0,0 +1,334 @@
+// Split out of the former 950-line pilot-overlay.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { formatHighlightCaption, normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight, resolveDeviceState, resolveTodoDockUi } from "../highlights.js";
+import { ensureInstalled } from "./shell.js";
+/**
+ * Paint (or clear) agent-authored highlight fixtures on the live page.
+ * Multi-ring + optional todo strip + zoom/focus/device - the Pilot equivalent
+ * of Block `stubBefore` narration in `waygraph demo`.
+ * Does not import `cli.ts` (see file header).
+ */
+export async function showPilotFixtures(page, fixtures) {
+    await ensureInstalled(page);
+    const holdMs = fixtures.clear === true
+        ? 0
+        : fixtures.holdMs === undefined
+            ? 30_000
+            : Math.max(0, fixtures.holdMs);
+    const rings = (fixtures.clear ? [] : (fixtures.rings ?? [])).map((r) => {
+        const tone = normalizeHighlightTone(r.tone);
+        const size = normalizeHighlightSize(r.size);
+        const weight = normalizeHighlightWeight(r.weight);
+        const caption = { label: r.label, tone };
+        if (r.detail)
+            caption.detail = r.detail;
+        if (r.tag)
+            caption.tag = r.tag;
+        const label = formatHighlightCaption(caption);
+        return {
+            selector: r.selector,
+            label,
+            tone,
+            size,
+            weight,
+            color: typeof r.color === "string" && r.color.trim() ? r.color.trim() : "",
+            zoom: typeof r.zoom === "number" && Number.isFinite(r.zoom) && r.zoom > 0
+                ? r.zoom
+                : undefined,
+            zoomOut: r.zoomOut,
+            focus: r.focus === true,
+        };
+    });
+    const todos = fixtures.clear ? [] : (fixtures.todos ?? []);
+    const todoIndex = fixtures.todoIndex ?? 0;
+    const todoTitle = fixtures.todoTitle ?? "Plan";
+    const todoPos = fixtures.todoPos === "left" ? "left" : "right";
+    const todoUi = resolveTodoDockUi(fixtures.todoUi ?? null);
+    // Effective zoom: phase zoom, else last ring that authored zoom.
+    let zoom = fixtures.clear === true
+        ? 1
+        : typeof fixtures.zoom === "number" && Number.isFinite(fixtures.zoom)
+            ? fixtures.zoom
+            : 1;
+    let zoomSelector = fixtures.zoomSelector ??
+        (rings.length > 0 ? rings[rings.length - 1].selector : undefined);
+    let zoomOut = fixtures.zoomOut !== false;
+    if (!fixtures.clear && zoom <= 1.001) {
+        for (let i = rings.length - 1; i >= 0; i--) {
+            const r = rings[i];
+            if (r.zoom !== undefined && r.zoom > 1.001) {
+                zoom = r.zoom;
+                zoomSelector = r.selector;
+                if (r.zoomOut !== undefined)
+                    zoomOut = r.zoomOut !== false;
+                break;
+            }
+        }
+    }
+    else if (!fixtures.clear) {
+        // Phase zoomOut can still be overridden by the targeted ring.
+        const hit = rings.find((r) => r.selector === zoomSelector);
+        if (hit?.zoomOut !== undefined)
+            zoomOut = hit.zoomOut !== false;
+    }
+    // Device viewport (Node-side) before paint so rings land on the new size.
+    if (fixtures.clear === true) {
+        // Leave viewport alone on clear - only drop overlays.
+    }
+    else if (fixtures.device !== undefined) {
+        const d = resolveDeviceState(fixtures.device);
+        if (d) {
+            await page
+                .setViewportSize({
+                width: Math.max(200, Math.floor(d.viewport.width)),
+                height: Math.max(200, Math.floor(d.viewport.height)),
+            })
+                .catch(() => { });
+        }
+    }
+    const deviceLabel = fixtures.clear === true
+        ? ""
+        : fixtures.device === undefined
+            ? ""
+            : typeof fixtures.device === "string"
+                ? fixtures.device
+                : fixtures.device.preset || "device";
+    return page
+        .evaluate(({ rings, todos, todoIndex, todoTitle, todoPos, holdMs, zoom, zoomSelector, zoomOut, clearAll, deviceLabel, todoUi, }) => {
+        const w = window;
+        if (w.__wgPilotFxHideTimer)
+            clearTimeout(w.__wgPilotFxHideTimer);
+        const clearFocus = () => {
+            const veil = document.getElementById("wg-pilot-fx-focus");
+            if (!veil)
+                return;
+            veil.classList.remove("wg-in");
+            setTimeout(() => {
+                const v = document.getElementById("wg-pilot-fx-focus");
+                if (v && !v.classList.contains("wg-in"))
+                    v.remove();
+            }, 320);
+        };
+        const applyFocus = (box) => {
+            let veil = document.getElementById("wg-pilot-fx-focus");
+            if (!veil) {
+                veil = document.createElement("div");
+                veil.id = "wg-pilot-fx-focus";
+                document.documentElement.appendChild(veil);
+            }
+            const pad = 10;
+            veil.style.left = `${Math.max(0, box.x - pad)}px`;
+            veil.style.top = `${Math.max(0, box.y - pad)}px`;
+            veil.style.width = `${Math.max(8, box.width + pad * 2)}px`;
+            veil.style.height = `${Math.max(8, box.height + pad * 2)}px`;
+            void veil.offsetWidth;
+            veil.classList.add("wg-in");
+        };
+        const setZoomBadge = (scale) => {
+            const level = Number.isFinite(scale) && scale > 0 ? scale : 1;
+            let badge = document.getElementById("wg-pilot-fx-zoom");
+            if (!badge) {
+                badge = document.createElement("div");
+                badge.id = "wg-pilot-fx-zoom";
+                document.documentElement.appendChild(badge);
+            }
+            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>`;
+        };
+        const clearZoom = () => {
+            // Undo any leftover CSS-scale from older Pilot zoom path.
+            const root = document.documentElement;
+            root.style.removeProperty("transform");
+            root.style.removeProperty("transform-origin");
+            root.style.removeProperty("transition");
+            document.getElementById("wg-pilot-fx-zoom")?.remove();
+        };
+        const setDeviceChip = (label) => {
+            document.getElementById("wg-pilot-fx-device")?.remove();
+            if (!label)
+                return;
+            const chip = document.createElement("div");
+            chip.id = "wg-pilot-fx-device";
+            chip.dataset.preset = label;
+            chip.textContent = `device \u00b7 ${label}`;
+            document.documentElement.appendChild(chip);
+        };
+        w.__wgPilotFxZoomOutOnHide = zoomOut;
+        const clearFx = () => {
+            document.querySelectorAll(".wg-pilot-fx-ring, .wg-pilot-fx-label").forEach((el) => el.remove());
+            document.getElementById("wg-pilot-fx-todos")?.remove();
+            clearFocus();
+            if (w.__wgPilotFxZoomOutOnHide !== false || clearAll)
+                clearZoom();
+            if (clearAll) {
+                document.getElementById("wg-pilot-fx-device")?.remove();
+                clearZoom();
+            }
+        };
+        w.__wgPilotFxClear = clearFx;
+        clearFx();
+        if (clearAll) {
+            return { painted: 0, missing: [] };
+        }
+        const missing = [];
+        let painted = 0;
+        let focusBox = null;
+        for (const ring of rings) {
+            const el = document.querySelector(ring.selector);
+            if (!el) {
+                missing.push(ring.selector);
+                continue;
+            }
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0) {
+                missing.push(ring.selector);
+                continue;
+            }
+            const pad = ring.size === "sm" ? 3 : ring.size === "lg" ? 10 : 6;
+            const ringEl = document.createElement("div");
+            ringEl.className = "wg-pilot-fx-ring";
+            ringEl.dataset.tone = ring.tone;
+            ringEl.dataset.size = ring.size;
+            ringEl.style.left = `${rect.left - pad}px`;
+            ringEl.style.top = `${rect.top - pad}px`;
+            ringEl.style.width = `${Math.max(4, rect.width + pad * 2)}px`;
+            ringEl.style.height = `${Math.max(4, rect.height + pad * 2)}px`;
+            ringEl.style.opacity = "1";
+            const labelEl = document.createElement("div");
+            labelEl.className = "wg-pilot-fx-label";
+            labelEl.dataset.tone = ring.tone;
+            labelEl.dataset.size = ring.size;
+            labelEl.dataset.weight = ring.weight;
+            labelEl.textContent = ring.label;
+            labelEl.style.opacity = "1";
+            if (ring.color) {
+                labelEl.style.color = ring.color;
+            }
+            document.documentElement.appendChild(ringEl);
+            document.documentElement.appendChild(labelEl);
+            const lw = labelEl.offsetWidth;
+            const lh = labelEl.offsetHeight;
+            let labelLeft = rect.left - pad;
+            let labelTop = rect.top - pad + rect.height + pad * 2 + 8;
+            if (labelTop + lh > window.innerHeight - 6)
+                labelTop = rect.top - pad - lh - 8;
+            if (labelTop < 6)
+                labelTop = 6;
+            if (labelLeft + lw > window.innerWidth - 6) {
+                labelLeft = Math.max(6, window.innerWidth - 6 - lw);
+            }
+            if (labelLeft < 6)
+                labelLeft = 6;
+            labelEl.style.left = `${labelLeft}px`;
+            labelEl.style.top = `${labelTop}px`;
+            painted += 1;
+            if (ring.focus) {
+                focusBox = { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+            }
+        }
+        if (todos.length > 0) {
+            const dock = document.createElement("div");
+            dock.id = "wg-pilot-fx-todos";
+            dock.dataset.pos = todoPos;
+            const title = document.createElement("div");
+            title.className = "wg-pilot-fx-todo-title";
+            title.textContent = todoTitle;
+            dock.appendChild(title);
+            const WINDOW = todoUi.cap > 0 ? todoUi.cap : 5;
+            const compact = todoUi.compact !== false && todos.length > WINDOW;
+            if (compact)
+                dock.dataset.compact = "1";
+            let start = 0;
+            let end = todos.length;
+            if (compact) {
+                start = Math.max(0, todoIndex - Math.floor((WINDOW - 1) / 2));
+                end = Math.min(todos.length, start + WINDOW);
+                start = Math.max(0, end - WINDOW);
+            }
+            const ol = document.createElement("ol");
+            todos.forEach((text, i) => {
+                const li = document.createElement("li");
+                li.textContent = text;
+                if (i < todoIndex)
+                    li.className = "wg-pilot-fx-todo-done";
+                else if (i === todoIndex)
+                    li.className = "wg-pilot-fx-todo-now";
+                if (compact && (i < start || i >= end))
+                    li.classList.add("wg-todo-fold");
+                ol.appendChild(li);
+            });
+            dock.appendChild(ol);
+            if (compact && todos.length - (end - start) > 0) {
+                const more = document.createElement("div");
+                more.className = "wg-todo-more";
+                more.textContent = "+" + (todos.length - (end - start)) + " more";
+                dock.appendChild(more);
+            }
+            document.documentElement.appendChild(dock);
+        }
+        if (focusBox)
+            applyFocus(focusBox);
+        // Dim todos under rings / focus so captions stay readable.
+        const dockEl = document.getElementById("wg-pilot-fx-todos");
+        if (dockEl && todoUi.behindRing !== false && (painted > 0 || focusBox)) {
+            dockEl.classList.add("wg-todo-behind");
+        }
+        // Collision flip: if a painted ring intersects the dock, flip side once.
+        if (dockEl && todoUi.collision !== false && painted > 0) {
+            const firstRing = document.querySelector(".wg-pilot-fx-ring");
+            if (firstRing) {
+                const rr = firstRing.getBoundingClientRect();
+                const dr = dockEl.getBoundingClientRect();
+                const hit = !(rr.right < dr.left || rr.left > dr.right || rr.bottom < dr.top || rr.top > dr.bottom);
+                if (hit) {
+                    dockEl.dataset.pos = dockEl.dataset.pos === "right" ? "left" : "right";
+                }
+            }
+        }
+        if (zoom > 1.001 && zoomSelector) {
+            const target = document.querySelector(zoomSelector);
+            if (target) {
+                target.scrollIntoView({
+                    block: "center",
+                    inline: "center",
+                    behavior: "instant",
+                });
+                // Re-apply focus after scroll so the cutout tracks the new rect.
+                if (focusBox) {
+                    const r = target.getBoundingClientRect();
+                    applyFocus({ x: r.left, y: r.top, width: r.width, height: r.height });
+                }
+                setZoomBadge(zoom);
+            }
+            else {
+                missing.push(zoomSelector);
+            }
+        }
+        else if (zoom > 1.001) {
+            setZoomBadge(zoom);
+        }
+        if (deviceLabel)
+            setDeviceChip(deviceLabel);
+        if (holdMs > 0 &&
+            (painted > 0 || todos.length > 0 || zoom > 1.001 || !!deviceLabel)) {
+            w.__wgPilotFxHideTimer = setTimeout(() => clearFx(), holdMs);
+        }
+        return { painted, missing };
+    }, {
+        rings,
+        todos,
+        todoIndex,
+        todoTitle,
+        todoPos,
+        holdMs,
+        zoom,
+        zoomSelector: zoomSelector ?? "",
+        zoomOut,
+        clearAll: fixtures.clear === true,
+        deviceLabel,
+        todoUi,
+    })
+        .catch(() => ({ painted: 0, missing: rings.map((r) => r.selector) }));
+}

package/dist/pilot-overlay/panel.d.ts

@@ -0,0 +1,34 @@
+import type { SessionSnapshot } from "../auto-session.js";
+import type { Page } from "@playwright/test";
+/** Minimal shape needed to render the graph tree - matches WaygraphGraph. */
+export interface PilotOverlayGraph {
+    nodes: readonly {
+        checkpoint: string;
+    }[];
+    edges: readonly {
+        block: string;
+        from: string;
+        to: string;
+        kind: "nav" | "action";
+    }[];
+}
+export interface PilotOverlayInfo {
+    sessionId: string | undefined;
+    snapshot: SessionSnapshot;
+    /**
+     * The WHOLE project's graph, not just what's reachable from the current
+     * page - real, direct user request: "i have a button where it shows all
+     * the nodes like a node tree stuff". Optional so a caller that doesn't
+     * have it handy (or doesn't want the extra payload every call) can omit
+     * it; the "All nodes" tab just shows nothing until one arrives.
+     */
+    graph?: PilotOverlayGraph;
+}
+/**
+ * Refreshes the badge text and the (possibly-collapsed) panel's two tabs
+ * ("Here" - current live menu; "All nodes" - whole project graph as a
+ * tree). Never throws - a page mid-navigation when this fires is a real,
+ * expected timing case, not an error worth failing the caller's own real
+ * operation over.
+ */
+export declare function updatePilotOverlay(page: Page, info: PilotOverlayInfo): Promise<void>;

package/dist/pilot-overlay/panel.js

@@ -0,0 +1,155 @@
+import { ensureInstalled } from "./shell.js";
+/**
+ * Refreshes the badge text and the (possibly-collapsed) panel's two tabs
+ * ("Here" - current live menu; "All nodes" - whole project graph as a
+ * tree). Never throws - a page mid-navigation when this fires is a real,
+ * expected timing case, not an error worth failing the caller's own real
+ * operation over.
+ */
+export async function updatePilotOverlay(page, info) {
+    await ensureInstalled(page);
+    await page
+        .evaluate(async ({ sessionId, snapshot, graph }) => {
+        const badge = document.getElementById("wg-pilot-badge");
+        const current = document.getElementById("wg-pilot-panel-current");
+        const graphPanel = document.getElementById("wg-pilot-panel-graph");
+        if (!badge || !current || !graphPanel)
+            return;
+        const idPart = sessionId ? `session ${sessionId}` : "no session id";
+        const onBlank = location.href === "about:blank" || location.protocol === "about:";
+        const hereLabel = snapshot.here ?? (onBlank ? "(blank page)" : "(unknown)");
+        badge.textContent = `Waygraph Pilot - ${idPart} - ${hereLabel}`;
+        const totalEdges = snapshot.sections.reduce((n, s) => n + s.edges.length, 0);
+        if (totalEdges === 0) {
+            current.innerHTML = onBlank
+                ? '<div class="wg-pilot-empty">Blank page — no Block moves yet. Use auto goto or a nav Block when ready.</div>'
+                : '<div class="wg-pilot-empty">No Block moves from here right now.</div>';
+        }
+        else {
+            current.innerHTML = snapshot.sections
+                .map((section) => {
+                const rows = section.edges
+                    .map((edge) => {
+                    const desc = edge.description ? ` - ${edge.description}` : "";
+                    const label = edge.label ? ` (${edge.label})` : "";
+                    return `<div class="wg-pilot-edge">[${edge.index}] <span class="wg-pilot-kind">${edge.kind}</span> ${edge.block}${label} -&gt; ${edge.to}${desc}</div>`;
+                })
+                    .join("");
+                return `<div class="wg-pilot-section">${section.title}</div>${rows}`;
+            })
+                .join("");
+        }
+        if (!graph || graph.nodes.length === 0) {
+            graphPanel.innerHTML = '<div class="wg-pilot-empty">No graph data yet.</div>';
+            return;
+        }
+        // Flat indented-text tree - the ORIGINAL "All nodes" rendering.
+        // Real, direct user correction: "i also dont like the all node
+        // stuff. ther should be a 2d version" - kept only as a fallback for
+        // when Mermaid genuinely can't load (e.g. offline), not the primary
+        // rendering anymore.
+        const renderTextTree = () => {
+            graphPanel.innerHTML = graph.nodes
+                .map((node) => {
+                const outgoing = graph.edges.filter((e) => e.from === node.checkpoint || e.from === "*");
+                const rows = outgoing.length
+                    ? outgoing
+                        .map((e) => `<div class="wg-pilot-graph-edge"><span class="wg-pilot-kind">${e.kind}</span> ${e.block} -&gt; ${e.to}</div>`)
+                        .join("")
+                    : '<div class="wg-pilot-graph-edge wg-pilot-empty">(no outgoing edges)</div>';
+                const here = node.checkpoint === snapshot.here ? " (here)" : "";
+                return `<div class="wg-pilot-graph-node"><div class="wg-pilot-graph-checkpoint">${node.checkpoint}${here}</div>${rows}</div>`;
+            })
+                .join("");
+        };
+        try {
+            const w = window;
+            if (!w.mermaid) {
+                if (!w.__wgMermaidLoadPromise) {
+                    w.__wgMermaidLoadPromise = new Promise((resolve, reject) => {
+                        const script = document.createElement("script");
+                        script.src = "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js";
+                        script.onload = () => resolve(undefined);
+                        script.onerror = () => reject(new Error("mermaid script failed to load"));
+                        document.head.appendChild(script);
+                    });
+                }
+                await w.__wgMermaidLoadPromise;
+            }
+            if (!w.mermaid)
+                throw new Error("mermaid did not attach to window after load");
+            // Real, direct user request: "left to right stuff. maybe mermaid?
+            // with square ish arrows???" - LR layout, linear (non-curvy) edges.
+            w.mermaid.initialize({ startOnLoad: false, theme: "dark", securityLevel: "loose", flowchart: { curve: "linear" } });
+            const sanitize = (s) => s.replace(/[^A-Za-z0-9_]/g, "_");
+            // Every Nav Block gets a `from:"*"` wildcard edge for pathfinding
+            // (see auto-explore.ts's own isUrlNav comment). Real, screenshot-
+            // confirmed finding, TWICE over:
+            // 1. Collapsing all of these into one shared "Anywhere" hub node
+            //    still broke the layout - ~9 of 10 Checkpoints have their own
+            //    nav edge, so nearly every node ends up one hop from that hub
+            //    and dagre stacks them in a single rank/column ("it dones't
+            //    look left to right").
+            // 2. Dropping them entirely (no edges, just a footnote) fixed the
+            //    layout but then hid real connectivity - a node like Settings
+            //    that has ONLY a nav edge looked like a disconnected orphan
+            //    ("the all nodes doesn't even show the navs block... whre is
+            //    settings there").
+            // Neither extreme is right: a wildcard nav edge isn't really a
+            // flow TRANSITION (it doesn't come from any one specific screen,
+            // it's global infrastructure - the persistent sidebar), so it
+            // doesn't belong in the layout-driving edge set at all, but the
+            // fact that a node is directly nav-reachable is still real
+            // information worth showing. Marked on the node's own label
+            // instead of as a graph edge - visible on every affected node,
+            // adds zero layout-warping connectivity.
+            const nonWildcard = graph.edges.filter((e) => e.from !== "*");
+            const navReachable = new Set(graph.edges.filter((e) => e.from === "*").map((e) => e.to));
+            // Real, direct user finding (screenshot-confirmed): a self-loop
+            // edge (an action that stays on the same Checkpoint, e.g.
+            // "fill-email -> SignIn") renders as a spiral squiggle Mermaid
+            // draws back into the same node - with several per node (every
+            // fill-* / select-* action), these dominated the diagram and
+            // broke the left-to-right layout dagre otherwise produces cleanly
+            // for a real DAG of inter-Checkpoint transitions. Self-loops add
+            // no flow information anyway (the "Here" tab already lists every
+            // action from wherever you are) - excluded from the graph itself,
+            // kept only as a "(+N)" count on the node label so the count
+            // isn't silently lost.
+            const selfLoopCounts = new Map();
+            for (const e of nonWildcard) {
+                if (e.from === e.to)
+                    selfLoopCounts.set(e.from, (selfLoopCounts.get(e.from) ?? 0) + 1);
+            }
+            const specific = nonWildcard.filter((e) => e.from !== e.to);
+            const lines = ["graph LR"];
+            for (const node of graph.nodes) {
+                const id = sanitize(node.checkpoint);
+                const here = node.checkpoint === snapshot.here;
+                const loops = selfLoopCounts.get(node.checkpoint);
+                const nav = navReachable.has(node.checkpoint) ? " [nav]" : "";
+                const suffix = `${here ? " (here)" : ""}${loops ? ` (+${loops})` : ""}${nav}`;
+                lines.push(`  ${id}["${node.checkpoint}${suffix}"]`);
+                if (here)
+                    lines.push(`  style ${id} stroke:#7C3AED,stroke-width:3px`);
+            }
+            for (const e of specific) {
+                lines.push(`  ${sanitize(e.from)} -->|${e.block}| ${sanitize(e.to)}`);
+            }
+            const { svg } = await w.mermaid.render(`wg-mermaid-${Date.now()}`, lines.join("\n"));
+            graphPanel.innerHTML =
+                svg + `<div class="wg-pilot-graph-note">[nav] = also directly reachable via sidebar/URL from anywhere (not drawn as an edge - see the "Here" tab for what's live on this page).</div>`;
+            // Real, direct user request: "i hope it is zoomed to the current
+            // node" - the diagram is usually bigger than the panel, so scroll
+            // (not zoom - the SVG itself stays real size, legible) the "here"
+            // node into view instead of leaving it wherever dagre placed it.
+            const hereId = snapshot.here ? sanitize(snapshot.here) : null;
+            const hereEl = hereId ? graphPanel.querySelector(`[id^="flowchart-${hereId}-"]`) : null;
+            hereEl?.scrollIntoView({ block: "center", inline: "center" });
+        }
+        catch {
+            renderTextTree();
+        }
+    }, { sessionId: info.sessionId, snapshot: info.snapshot, graph: info.graph ?? null })
+        .catch(() => { });
+}

package/dist/pilot-overlay/shell.d.ts

@@ -0,0 +1,48 @@
+import type { HighlightTone } from "../highlights.js";
+import type { BrowserContext, Page } from "@playwright/test";
+/**
+ * Re-install the overlay shell on every navigation (about:blank, goto, etc.)
+ * so the badge/panel persist outside the app's own DOM — not lost when the
+ * page is blank or replaced.
+ */
+export declare function installPersistentPilotOverlay(context: BrowserContext): Promise<void>;
+/** Idempotent - safe to call before every update, matching narrate mode's own precedent. */
+export declare function ensureInstalled(page: Page): Promise<void>;
+/**
+ * Bottom-left transient toast, separate from the persistent bottom-right
+ * badge - real, direct user request: something that visibly flags "a
+ * command is running" / "the map just changed" distinct from the
+ * always-on Checkpoint badge. Self-clearing (CSS fade after a timeout),
+ * not tied to the next `currentMenu()` snapshot the way the badge is,
+ * since some callers (rawClick/rawType/rawGoto/reloadLibrary/applyPick)
+ * only call `currentMenu()` again once the whole operation - including
+ * this toast's own lifetime - should already be over.
+ */
+export declare function showPilotActivity(page: Page, text: string): Promise<void>;
+/**
+ * "browser-use"-style vision box: a ring drawn around the exact element
+ * `auto dom --selector <sel>` just inspected, so a human watching a headful
+ * Pilot session can see what the agent is actually looking at, not just a
+ * 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
+ * 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
+ * lives in `cli.ts`, which this file continues to avoid importing (see this
+ * file's own header). Auto-fades a few real seconds after showing (or
+ * sooner if explicitly replaced/hidden first) - tuned live twice: an
+ * original 2.5s fade read as gone before it could be seen, a since-tried
+ * "stay up indefinitely" alternative read as lingering clutter instead.
+ *
+ * `tone` defaults to "auto" (gray) - real, direct user request: "gray is
+ * waygraph playwright run. orange is dom check" - a real Block run or a
+ * raw click/type/upload IS a real Playwright-driven action (`auto` was
+ * always documented as meaning exactly that), while a pure `auto dom` read
+ * touches nothing, so it gets its own "orange" tone instead.
+ *
+ * For agent-authored multi-ring / todo narration, use {@link showPilotFixtures}
+ * (`auto highlight`) instead - this vision ring is one-shot inspect feedback.
+ */
+export declare function showPilotVision(page: Page, selector: string, label: string, tone?: HighlightTone): Promise<void>;