waygraph 0.13.6 → 0.14.0

package/dist/pilot-overlay.js

@@ -0,0 +1,363 @@
+import { WAYGRAPH_RING_CSS } from "./highlights.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
+// design... looks a bit different and out of sync". These are the SAME
+// colors `cli.ts`'s own demo panel/ring already use (#7C3AED primary
+// purple, the dark rgba(20,10,40,.94) panel background + white text,
+// #c9a6ff for a secondary purple accent on that dark background - all
+// copied verbatim from cli.ts's own `#wg-panel`/`RING_CSS`, not
+// re-invented) - genuinely the same visual language, not just the ring CSS
+// this file already shared via WAYGRAPH_RING_CSS.
+const OVERLAY_CSS = `
+#wg-pilot-overlay {
+  position: fixed; z-index: 2147483000; bottom: 12px; right: 12px;
+  font: 12px/1.4 ui-monospace, "SF Mono", Consolas, monospace;
+  color: #fff; pointer-events: auto;
+}
+#wg-pilot-badge {
+  background: #7C3AED; color: #fff; padding: 6px 10px; border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.25); cursor: pointer; white-space: nowrap;
+  font-weight: 600; user-select: none;
+}
+#wg-pilot-panel {
+  display: none; margin-top: 6px; max-width: 420px; max-height: 320px;
+  overflow-y: auto; background: rgba(20,10,40,.94); color: #fff; border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.25); padding: 8px 10px;
+}
+/* The graph tab renders a real Mermaid flowchart, which needs more room than
+   the flat-list "Here" tab and its own scroll - real, direct user request:
+   "a 2d version. left to right stuff. maybe mermaid?" replacing the original
+   flat indented-text tree. Widened+its own scrollbox rather than growing
+   the shared panel unconditionally, so "Here" stays compact. */
+#wg-pilot-panel:has(#wg-pilot-panel-graph:not([style*="display: none"])) {
+  max-width: 640px; max-height: 460px;
+}
+#wg-pilot-panel-graph { overflow: auto; }
+#wg-pilot-panel-graph svg { max-width: none; }
+#wg-pilot-panel-graph .wg-pilot-graph-note { color: #999; font-style: italic; font-size: 11px; padding: 4px 2px 0; }
+#wg-pilot-panel.wg-pilot-open { display: block; }
+#wg-pilot-panel-toggle { display: flex; gap: 6px; margin-bottom: 8px; }
+#wg-pilot-panel-toggle button {
+  background: transparent; color: #bbb; border: 1px solid rgba(255,255,255,.2);
+  border-radius: 6px; padding: 3px 8px; font: inherit; cursor: pointer;
+}
+#wg-pilot-panel-toggle button.wg-pilot-tab-active { background: #7C3AED; color: #fff; border-color: #7C3AED; }
+#wg-pilot-panel .wg-pilot-section { font-weight: 700; margin: 6px 0 2px; color: #c9a6ff; }
+#wg-pilot-panel .wg-pilot-edge { padding: 2px 0; border-bottom: 1px solid rgba(255,255,255,.12); }
+#wg-pilot-panel .wg-pilot-kind { color: #c9a6ff; font-weight: 600; }
+#wg-pilot-panel .wg-pilot-desc { color: #bbb; }
+#wg-pilot-panel .wg-pilot-empty { color: #999; font-style: italic; }
+#wg-pilot-panel-graph .wg-pilot-graph-node { margin: 6px 0; }
+#wg-pilot-panel-graph .wg-pilot-graph-checkpoint { color: #c9a6ff; font-weight: 700; }
+#wg-pilot-panel-graph .wg-pilot-graph-edge { padding: 2px 0 2px 14px; border-left: 2px solid rgba(255,255,255,.15); font-size: 11px; }
+#wg-pilot-panel-graph .wg-pilot-graph-edge .wg-pilot-kind { color: #c9a6ff; }
+#wg-pilot-activity {
+  position: fixed; z-index: 2147483000; bottom: 12px; left: 12px;
+  font: 12px/1.4 ui-monospace, "SF Mono", Consolas, monospace;
+  background: rgba(20,10,40,.94); color: #fff; padding: 6px 10px; border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.25); white-space: nowrap; pointer-events: none;
+  opacity: 0; transform: translateY(4px); transition: opacity 0.15s, transform 0.15s;
+}
+#wg-pilot-activity.wg-pilot-toast-show { opacity: 1; transform: translateY(0); }
+` + WAYGRAPH_RING_CSS;
+/** Idempotent - safe to call before every update, matching narrate mode's own precedent. */
+async function ensureInstalled(page) {
+    await page.addStyleTag({ content: OVERLAY_CSS }).catch(() => { });
+    await page.evaluate(() => {
+        if (document.getElementById("wg-pilot-overlay"))
+            return;
+        const root = document.createElement("div");
+        root.id = "wg-pilot-overlay";
+        // Real, direct user request: a way to see the WHOLE project's graph
+        // (every Checkpoint/Block, not just what's reachable from the current
+        // page) directly in the overlay, "like a node tree" - toggled inside
+        // the same panel rather than a second popup, so there's one place to
+        // look, not two.
+        root.innerHTML =
+            '<div id="wg-pilot-badge"></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>";
+        document.documentElement.appendChild(root);
+        document.getElementById("wg-pilot-badge").addEventListener("click", () => {
+            document.getElementById("wg-pilot-panel").classList.toggle("wg-pilot-open");
+        });
+        document.getElementById("wg-pilot-view-current").addEventListener("click", () => {
+            document.getElementById("wg-pilot-view-current").classList.add("wg-pilot-tab-active");
+            document.getElementById("wg-pilot-view-graph").classList.remove("wg-pilot-tab-active");
+            document.getElementById("wg-pilot-panel-current").style.display = "";
+            document.getElementById("wg-pilot-panel-graph").style.display = "none";
+        });
+        document.getElementById("wg-pilot-view-graph").addEventListener("click", () => {
+            document.getElementById("wg-pilot-view-graph").classList.add("wg-pilot-tab-active");
+            document.getElementById("wg-pilot-view-current").classList.remove("wg-pilot-tab-active");
+            document.getElementById("wg-pilot-panel-graph").style.display = "";
+            document.getElementById("wg-pilot-panel-current").style.display = "none";
+        });
+        const toast = document.createElement("div");
+        toast.id = "wg-pilot-activity";
+        document.documentElement.appendChild(toast);
+        const ring = document.createElement("div");
+        ring.id = "wg-ring";
+        const ringLabel = document.createElement("div");
+        ringLabel.id = "wg-ring-label";
+        document.documentElement.appendChild(ring);
+        document.documentElement.appendChild(ringLabel);
+    }).catch(() => { });
+}
+/**
+ * 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 async function showPilotActivity(page, text) {
+    await ensureInstalled(page);
+    await page
+        .evaluate((text) => {
+        const toast = document.getElementById("wg-pilot-activity");
+        if (!toast)
+            return;
+        toast.textContent = text;
+        toast.classList.add("wg-pilot-toast-show");
+        const w = window;
+        if (w.__wgPilotToastTimer)
+            clearTimeout(w.__wgPilotToastTimer);
+        w.__wgPilotToastTimer = setTimeout(() => {
+            toast.classList.remove("wg-pilot-toast-show");
+        }, 2500);
+    }, text)
+        .catch(() => { });
+}
+/**
+ * "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.
+ */
+export async function showPilotVision(page, selector, label, tone = "auto") {
+    await ensureInstalled(page);
+    await page
+        .evaluate(({ selector, label, tone }) => {
+        const ring = document.getElementById("wg-ring");
+        const tag = document.getElementById("wg-ring-label");
+        if (!ring || !tag)
+            return;
+        const w = window;
+        if (w.__wgVisionHideTimer)
+            clearTimeout(w.__wgVisionHideTimer);
+        const el = document.querySelector(selector);
+        if (!el) {
+            ring.style.opacity = "0";
+            tag.style.opacity = "0";
+            return;
+        }
+        const rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) {
+            ring.style.opacity = "0";
+            tag.style.opacity = "0";
+            return;
+        }
+        ring.dataset.tone = tone;
+        ring.dataset.size = "md";
+        tag.dataset.tone = tone;
+        tag.dataset.size = "md";
+        tag.dataset.weight = "normal";
+        ring.style.left = `${rect.left - 3}px`;
+        ring.style.top = `${rect.top - 3}px`;
+        ring.style.width = `${rect.width + 6}px`;
+        ring.style.height = `${rect.height + 6}px`;
+        tag.textContent = label;
+        tag.style.left = `${Math.max(0, rect.left)}px`;
+        tag.style.top = `${Math.max(0, rect.top - 24)}px`;
+        ring.style.opacity = "1";
+        tag.style.opacity = "1";
+        // Real, direct user correction: this used to be a 30s "long
+        // fallback" (stay up until explicitly replaced) - after actually
+        // watching it, the user wants it to auto-clear after a few real
+        // seconds instead, not linger. Short enough to still read as "just
+        // happened", not so short it's gone before you look (that was the
+        // ORIGINAL complaint this session, at 2.5s - this is deliberately
+        // in between).
+        w.__wgVisionHideTimer = setTimeout(() => {
+            ring.style.opacity = "0";
+            tag.style.opacity = "0";
+        }, 4_000);
+    }, { selector, label, tone })
+        .catch(() => { });
+}
+/**
+ * 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";
+        badge.textContent = `Waygraph Pilot - ${idPart} - ${snapshot.here ?? "(unknown)"}`;
+        const totalEdges = snapshot.sections.reduce((n, s) => n + s.edges.length, 0);
+        if (totalEdges === 0) {
+            current.innerHTML = '<div class="wg-pilot-empty">No 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.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Waygraph Pilot: the one bootstrap call an agent needs to start driving a
+ * real, persistent, inspectable browser session toward a natural-language
+ * goal it plans and executes itself.
+ *
+ * Deliberately NOT a resolver that maps one ask to one Block
+ * (`resolveAsk`/`pilotNarrate`/`pilotAct`, the v1 shape this replaced - see
+ * git tag `waygraph-pilot-v1-logs-prettified` for that history). Real
+ * requests are multi-step ("log in and buy the backpack for me", "make a
+ * signature draft request") and need an agent that plans a whole sequence
+ * against the graph, not a single best-matching edge. `pilotStart` does not
+ * plan, resolve, narrate, or act on anything - it only combines two
+ * already-proven, separately-existing primitives into one payload:
+ *
+ * - `spawnDetachedSession` (same mechanism as `auto --cli --detach`) - a
+ *   real, persistent, visible-if-headful Playwright session an agent can
+ *   keep driving across many calls, not a fresh session per request.
+ * - `discoverGraph` (same mechanism as `waygraph graph`) - the WHOLE
+ *   project's Checkpoint/edge/description graph, not just what's reachable
+ *   from the session's current position, because planning a multi-step
+ *   route needs to see steps ahead, not just the next one.
+ *
+ * Driving the session afterward - `auto send <id> "<pick>"`, `auto status
+ * <id>`, `auto dom <id>`, `auto trace <id>` - is left entirely to whatever
+ * agent is holding it. All four already existed before this file did; see
+ * openspec/changes/waygraph-pilot/design.md for the worked example (a real
+ * login + add-to-cart + checkout run against examples/saucedemo, driven by
+ * hand-picking indices from each status response) that proved this needs no
+ * new execution primitive.
+ */
+import { type WaygraphGraph } from "./graph.js";
+import type { AutoSessionInit, SessionSnapshot } from "./auto-session.js";
+export interface PilotStartResult {
+    sessionId: string;
+    socketPath: string;
+    headless: boolean;
+    /** The whole project's Block graph - every Checkpoint/edge/description, not just what's reachable right now. */
+    graph: WaygraphGraph;
+    /** The session's starting position, or `null` if the very first `status` read failed. */
+    snapshot: SessionSnapshot | null;
+}
+/**
+ * Starts a detached session and reads back its own graph + starting
+ * snapshot in one call, so an agent bootstraps with everything it needs
+ * (a live session it can keep driving, and the full map of what exists) in
+ * one round trip instead of separately knowing to chain `auto --cli
+ * --detach` and `waygraph graph` itself.
+ */
+export declare function pilotStart(init: AutoSessionInit): Promise<PilotStartResult>;

package/dist/pilot.js

@@ -0,0 +1,53 @@
+/**
+ * Waygraph Pilot: the one bootstrap call an agent needs to start driving a
+ * real, persistent, inspectable browser session toward a natural-language
+ * goal it plans and executes itself.
+ *
+ * Deliberately NOT a resolver that maps one ask to one Block
+ * (`resolveAsk`/`pilotNarrate`/`pilotAct`, the v1 shape this replaced - see
+ * git tag `waygraph-pilot-v1-logs-prettified` for that history). Real
+ * requests are multi-step ("log in and buy the backpack for me", "make a
+ * signature draft request") and need an agent that plans a whole sequence
+ * against the graph, not a single best-matching edge. `pilotStart` does not
+ * plan, resolve, narrate, or act on anything - it only combines two
+ * already-proven, separately-existing primitives into one payload:
+ *
+ * - `spawnDetachedSession` (same mechanism as `auto --cli --detach`) - a
+ *   real, persistent, visible-if-headful Playwright session an agent can
+ *   keep driving across many calls, not a fresh session per request.
+ * - `discoverGraph` (same mechanism as `waygraph graph`) - the WHOLE
+ *   project's Checkpoint/edge/description graph, not just what's reachable
+ *   from the session's current position, because planning a multi-step
+ *   route needs to see steps ahead, not just the next one.
+ *
+ * Driving the session afterward - `auto send <id> "<pick>"`, `auto status
+ * <id>`, `auto dom <id>`, `auto trace <id>` - is left entirely to whatever
+ * agent is holding it. All four already existed before this file did; see
+ * openspec/changes/waygraph-pilot/design.md for the worked example (a real
+ * login + add-to-cart + checkout run against examples/saucedemo, driven by
+ * hand-picking indices from each status response) that proved this needs no
+ * new execution primitive.
+ */
+import { discoverGraph } from "./graph.js";
+import { spawnDetachedSession, requestSession } from "./auto-session-ipc.js";
+/**
+ * Starts a detached session and reads back its own graph + starting
+ * snapshot in one call, so an agent bootstraps with everything it needs
+ * (a live session it can keep driving, and the full map of what exists) in
+ * one round trip instead of separately knowing to chain `auto --cli
+ * --detach` and `waygraph graph` itself.
+ */
+export async function pilotStart(init) {
+    const [meta, graph] = await Promise.all([
+        spawnDetachedSession(init),
+        discoverGraph(init.projectDir),
+    ]);
+    const status = await requestSession(init.projectDir, meta.sessionId, { op: "status" });
+    return {
+        sessionId: meta.sessionId,
+        socketPath: meta.socketPath,
+        headless: meta.headless,
+        graph,
+        snapshot: status.ok ? status.snapshot : null,
+    };
+}

package/dist/trait.d.ts

@@ -40,6 +40,25 @@ export declare function textEquals(selector: string, expected: string): Trait;
  * "something matching is visible", not "the selector is unambiguous".
  */
 export declare function visible(selector: string): Trait;
+/**
+ * `visible`, scoped to a frame (e.g. a mail catcher's message-preview iframe)
+ * instead of the top-level page. `page.locator(selector)` alone never reaches
+ * inside an iframe - Playwright requires `frameLocator` for that - so
+ * `Trait.visible` cannot express this on its own. `frameSelector` finds the
+ * iframe itself; `innerSelector` is resolved inside it.
+ * @example Trait.frameVisible("#preview-html", 'a[href*="verify"]')
+ */
+export declare function frameVisible(frameSelector: string, innerSelector: string): Trait;
+/** `textEquals`, scoped to a frame - see {@link frameVisible} for why this needs its own factory. */
+export declare function frameTextEquals(frameSelector: string, innerSelector: string, expected: string): Trait;
+/**
+ * Passes when `innerSelector`'s text inside `frameSelector` contains `expected`
+ * as a substring - the common QA shape for "the email says X somewhere" without
+ * needing to match the whole body verbatim (surrounding whitespace/markup in a
+ * real email template would otherwise break an exact-equality check).
+ * @example Trait.frameContains("#preview-html", "body", "Please verify your account")
+ */
+export declare function frameContainsText(frameSelector: string, innerSelector: string, expected: string): Trait;
 /**
  * Discoverable entry point for the built-in Trait factories - type `Trait.` in
  * an editor to see `url`/`text`/`visible` offered, instead of needing to
@@ -54,6 +73,9 @@ export declare const Trait: {
     url: typeof urlMatches;
     text: typeof textEquals;
     visible: typeof visible;
+    frameVisible: typeof frameVisible;
+    frameText: typeof frameTextEquals;
+    frameContains: typeof frameContainsText;
 };
 /**
  * Runs every Trait for a Block that just resolved, throwing on the first failure

package/dist/trait.js

@@ -22,9 +22,21 @@ export function urlMatches(pattern) {
     return {
         name: `url-matches(${JSON.stringify(pattern)})`,
         async check(page) {
-            // Bound wait - fail loud instead of hanging forever when navigation never comes
-            // (e.g. locked_out login still on / while verify demands /inventory.html).
-            await page.waitForURL(urlPattern, { timeout: 8_000 });
+            // No explicit timeout - inherits whatever `page.setDefaultTimeout()`
+            // is currently in effect (matching Trait.visible's own precedent),
+            // rather than a hardcoded value. Real, confirmed bug this fixes: an
+            // explicit `{ timeout: 8_000 }` here silently OVERRODE the much
+            // shorter bound `engine.ts`'s own `locate()` sets via
+            // `page.setDefaultTimeout()` while probing each NavBlock during
+            // `detectHere` (used by resync and every raw click/type/goto/upload) -
+            // a project with several `Trait.url` NavBlocks could take 8s PER
+            // candidate that doesn't match, turning one resync/raw call into many
+            // tens of seconds. Playwright's own ambient default (30s, unless
+            // something narrowed it) still fails loud for the normal post-resolve
+            // `verify()` case this was originally written for - just via the same
+            // mechanism every other Trait already uses instead of its own
+            // hardcoded, wrong-context value.
+            await page.waitForURL(urlPattern);
             return true;
         },
     };
@@ -53,6 +65,48 @@ export function visible(selector) {
         },
     };
 }
+/**
+ * `visible`, scoped to a frame (e.g. a mail catcher's message-preview iframe)
+ * instead of the top-level page. `page.locator(selector)` alone never reaches
+ * inside an iframe - Playwright requires `frameLocator` for that - so
+ * `Trait.visible` cannot express this on its own. `frameSelector` finds the
+ * iframe itself; `innerSelector` is resolved inside it.
+ * @example Trait.frameVisible("#preview-html", 'a[href*="verify"]')
+ */
+export function frameVisible(frameSelector, innerSelector) {
+    return {
+        name: `frame-visible(${frameSelector}, ${innerSelector})`,
+        async check(page) {
+            await page.frameLocator(frameSelector).locator(innerSelector).first().waitFor({ state: "visible" });
+            return true;
+        },
+    };
+}
+/** `textEquals`, scoped to a frame - see {@link frameVisible} for why this needs its own factory. */
+export function frameTextEquals(frameSelector, innerSelector, expected) {
+    return {
+        name: `frame-text-equals(${frameSelector}, ${innerSelector}, ${JSON.stringify(expected)})`,
+        async check(page) {
+            return (await page.frameLocator(frameSelector).locator(innerSelector).textContent()) === expected;
+        },
+    };
+}
+/**
+ * Passes when `innerSelector`'s text inside `frameSelector` contains `expected`
+ * as a substring - the common QA shape for "the email says X somewhere" without
+ * needing to match the whole body verbatim (surrounding whitespace/markup in a
+ * real email template would otherwise break an exact-equality check).
+ * @example Trait.frameContains("#preview-html", "body", "Please verify your account")
+ */
+export function frameContainsText(frameSelector, innerSelector, expected) {
+    return {
+        name: `frame-contains-text(${frameSelector}, ${innerSelector}, ${JSON.stringify(expected)})`,
+        async check(page) {
+            const text = await page.frameLocator(frameSelector).locator(innerSelector).textContent();
+            return (text ?? "").includes(expected);
+        },
+    };
+}
 /**
  * Discoverable entry point for the built-in Trait factories - type `Trait.` in
  * an editor to see `url`/`text`/`visible` offered, instead of needing to
@@ -67,6 +121,9 @@ export const Trait = {
     url: urlMatches,
     text: textEquals,
     visible,
+    frameVisible,
+    frameText: frameTextEquals,
+    frameContains: frameContainsText,
 };
 /**
  * Runs every Trait for a Block that just resolved, throwing on the first failure

package/examples/routed-demo/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "waygraph-example-routed-demo",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "description": "Waygraph Map folder convention proof - (group)/<page>/page.block.ts + nav.block.ts + methods/*.block.ts, offline fixture, zero new engine code.",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "npm run fixture:test",
+    "fixture": "node scripts/fixture-server.mjs",
+    "fixture:test": "node scripts/with-fixture.mjs npx playwright test",
+    "graph": "waygraph graph",
+    "auto:cli": "node scripts/with-fixture.mjs waygraph auto --cli"
+  },
+  "waygraph": {
+    "baseUrl": "http://127.0.0.1:4277"
+  },
+  "dependencies": {
+    "waygraph": "file:../.."
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.55.0",
+    "@types/node": "^26.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/examples/routed-demo/playwright.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "@playwright/test";
+
+const PORT = process.env.WAYGRAPH_FIXTURE_PORT || "4277";
+const HOST = process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1";
+
+export default defineConfig({
+  testDir: "./tests",
+  fullyParallel: false,
+  workers: 1,
+  timeout: 30_000,
+  reporter: "list",
+  use: {
+    headless: true,
+    baseURL: process.env.WAYGRAPH_BASE_URL || `http://${HOST}:${PORT}`,
+    launchOptions: {
+      executablePath: process.env.CHROME_PATH || process.env.CHROMIUM_PATH,
+      args: ["--no-sandbox", "--disable-dev-shm-usage"],
+    },
+  },
+});