waygraph 0.15.53 → 0.16.0

package/dist/{session/auto-explore.js → live/auto/explore.js}

@@ -1,62 +1,7 @@
-import { readdirSync, statSync } from "node:fs";
-import { join, relative, resolve } from "node:path";
-import { discoverGraph } from "../analysis/graph.js";
-import { exploreRoots, injectTaggedFile } from "./block-inject.js";
-function walkDir(dir, pattern) {
-    const results = [];
-    let entries;
-    try {
-        entries = readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return results;
-    }
-    for (const entry of entries) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git")
-                continue;
-            results.push(...walkDir(full, pattern));
-        }
-        else if (pattern.test(entry.name)) {
-            results.push(full);
-        }
-    }
-    return results;
-}
-/**
- * Real, confirmed bug this fixes: a bare `import(url.href)` is permanently
- * cached by Node's ESM loader for the lifetime of the process, keyed on the
- * exact specifier. `AutoSession.reloadLibrary()` exists specifically so a
- * Block edited on disk mid-session takes effect without restarting the
- * session - but a SECOND `reload` of a file already imported once in this
- * process silently kept returning the FIRST version's content, no matter
- * how many times the file changed on disk after that. A one-shot CLI
- * process (`waygraph graph`, etc.) never hits this - it only ever imports
- * each file once anyway - but a long-running `--detach` session calling
- * `reloadLibrary()` repeatedly does.
- *
- * Fix: bust the cache with the file's own mtime as a query param - a
- * genuinely changed file gets a new specifier (forcing a fresh import); an
- * UNCHANGED file between two reloads keeps hitting the SAME specifier (no
- * unbounded accumulation of dead module instances across many reloads).
- */
-async function importModule(filePath) {
-    const resolved = resolve(filePath);
-    const url = new URL(`file://${resolved}`);
-    const mtimeMs = statSync(resolved).mtimeMs;
-    url.searchParams.set("t", String(mtimeMs));
-    return (await import(url.href));
-}
-function isBlockLike(val) {
-    if (val === null || typeof val !== "object")
-        return false;
-    const obj = val;
-    if (typeof obj.name !== "string")
-        return false;
-    const instruction = obj.instruction;
-    return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
-}
+import { join } from "node:path";
+import { discoverGraph } from "../../analysis/graph.js";
+import { scanProject } from "../../manifest/project.js";
+import { importFresh, walkDir } from "../../manifest/scan.js";
 function isNavBlockMarked(val) {
     const kind = val.__waygraphKind;
     return kind === "nav" || kind === "page";
@@ -103,56 +48,26 @@ async function wildcardActionRunnable(page, entry, here) {
  * Import every `*.block.ts` export keyed by runtime Block `.name`.
  */
 export async function loadBlockLibrary(projectDir, opts) {
-    const { matchBlocksSelect } = await import("../blocks-select.js");
     const byName = new Map();
     const navBlocks = [];
-    const navSeen = new Set();
-    const select = opts?.blocksSelect;
-    for (const root of exploreRoots(projectDir, opts?.inject)) {
-        for (const file of walkDir(root, /\.block\.ts$/)) {
-            const relFile = relative(root, file).replace(/\\/g, "/");
-            const taggedFile = injectTaggedFile(projectDir, root, relFile);
-            // Glob/bare: path filter before import. Regex: need block name — filter after.
-            if (select && select.kind !== "regex" && !matchBlocksSelect(select, { relFile })) {
-                continue;
-            }
-            let mod;
-            try {
-                mod = await importModule(file);
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                if (/second time|playwright/i.test(msg)) {
-                    console.error(`waygraph auto: skip ${relFile}: ${msg.split("\n")[0]}`);
-                }
-                continue;
-            }
-            for (const [exportName, exported] of Object.entries(mod)) {
-                if (!isBlockLike(exported))
-                    continue;
-                if (select &&
-                    !matchBlocksSelect(select, { relFile, blockName: exported.name })) {
-                    continue;
-                }
-                const kind = isNavBlockMarked(exported) ? "nav" : "action";
-                const entry = {
-                    block: exported,
-                    exportName,
-                    file: taggedFile,
-                    kind,
-                    description: typeof exported.description === "string" ? exported.description : "",
-                };
-                if (byName.has(exported.name)) {
-                    console.error(`waygraph: inject skipped duplicate Block name "${exported.name}" (${taggedFile})`);
-                    continue;
-                }
-                byName.set(exported.name, entry);
-                if (kind === "nav" && !navSeen.has(exported.name)) {
-                    navSeen.add(exported.name);
-                    navBlocks.push(entry);
-                }
-            }
+    const scan = await scanProject(projectDir, {
+        blocksSelect: opts?.blocksSelect,
+        inject: opts?.inject,
+        flows: false,
+    });
+    // A Block's required keys get the project's own defaults: every `*.mem-stubs.ts` registers its fakes on import.
+    for (const file of walkDir(join(projectDir, "src"), /\.mem-stubs\.ts$/))
+        await importFresh(file);
+    for (const b of scan.blocks) {
+        const kind = isNavBlockMarked(b.block) ? "nav" : "action";
+        if (byName.has(b.name)) {
+            console.error(`waygraph: inject skipped duplicate Block name "${b.name}" (${b.file})`);
+            continue;
         }
+        const entry = { block: b.block, exportName: b.exportName, file: b.file, kind, description: b.description };
+        byName.set(b.name, entry);
+        if (kind === "nav")
+            navBlocks.push(entry);
     }
     navBlocks.sort((a, b) => {
         const aUrl = isUrlNav(a) ? 0 : 1;
@@ -161,27 +76,6 @@ export async function loadBlockLibrary(projectDir, opts) {
     });
     return { byName, navBlocks };
 }
-/**
- * @deprecated Use {@link buildExploreMenu} — kept for unit tests.
- */
-export function exploreChoices(graph, here) {
-    const seen = new Set();
-    const out = [];
-    for (const edge of graph.edges) {
-        if (here === null) {
-            if (edge.kind !== "nav" || edge.from !== "*")
-                continue;
-        }
-        else if (edge.from !== here && edge.from !== "*") {
-            continue;
-        }
-        if (seen.has(edge.block))
-            continue;
-        seen.add(edge.block);
-        out.push(edge);
-    }
-    return out.sort((a, b) => a.block.localeCompare(b.block));
-}
 /**
  * Runtime-filtered menu: only Blocks that can run on the live page, grouped forward/back.
  */

package/dist/{auto-session/session.d.ts → live/auto-session/auto-session.d.ts}

@@ -1,5 +1,5 @@
 import type { ApplyPathResult, ApplyPickResult, AutoSessionInit, ConsoleLogEntry, InspectDomOptions, InspectDomResult, SessionSnapshot, StorageSnapshot, StubFileKind, TraceStep } from "./helpers.js";
-import type { PilotHighlightFixtures } from "../pilot-overlay.js";
+import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
 /**
  * Non-interactive explore session: same graph/library/mem/browser setup
  * `runAutoExplore` runs in `--cli` mode, driven by `applyPick` instead of a

package/dist/{auto-session/session.js → live/auto-session/auto-session.js}

@@ -1,16 +1,21 @@
-// Split out of the former 1,078-line auto-session.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { CONSOLE_LOG_MAX_ENTRIES, FULL_MODE_DEFAULT_DEPTH, FULL_MODE_MAX_NODES, FULL_MODE_MAX_TEXT_LENGTH, TRACE_MAX_STEPS, buildSessionSnapshot, parsePick, stubFilePath, stubPhaseHasContent, walkFullDom } from "./helpers.js";
-import { instrumentPilotActions, installPersistentPilotOverlay, showPilotActivity, showPilotFixtures, showPilotVision, phaseToOverlayFixtures, describeOverlayFixtures, updatePilotOverlay } from "../pilot-overlay.js";
-import { buildExploreContext, buildExploreMenu } from "../session/auto-explore.js";
-import { MemPage } from "../mem-page.js";
-import { Engine } from "../core.js";
-import { detectHere, ensureLivePage, ensureMem, resolveBaseUrl, runOneBlock, seedDefaultMem } from "../session/auto-explore-run.js";
-import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from "../analysis/coverage-gap.js";
-import { runStubPhase } from "../highlights.js";
-import { verboseLog } from "./verbose-log.js";
-import { findBlockPathDetailed } from "../analysis/graph.js";
-import { configuredExtensions } from "../config.js";
-import { chromiumExecutablePath, launchContext } from "../browser.js";
+import { keepOverlayOnNavigation } from "../../demo/overlay/reattach.js";
+import { installPersistentPilotOverlay, showPilotActivity, showPilotVision } from "../../demo/overlay/pilot/shell.js";
+import { showPilotFixtures } from "../../demo/overlay/pilot/fixtures.js";
+import { instrumentPilotActions } from "../../demo/overlay/pilot/actions.js";
+import { phaseToOverlayFixtures, describeOverlayFixtures } from "../../demo/overlay/phase-fixtures.js";
+import { updatePilotOverlay } from "../pilot/panel.js";
+import { buildExploreContext, buildExploreMenu } from "../auto/explore.js";
+import { MemPage } from "../../engine/mem/mem.js";
+import { Engine } from "../../engine/engine.js";
+import { detectHere, ensureLivePage, ensureMem, runOneBlock, seedDefaultMem } from "../auto/auto.js";
+import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from "../../analysis/coverage-gap.js";
+import { runStubPhase } from "../../demo/narration/narration.js";
+import { verboseLog } from "../../demo/verbose-log.js";
+import { findBlockPathDetailed } from "../../analysis/graph.js";
+import { configuredExtensions, resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { chromiumExecutablePath, launchContext } from "../../runtime/browser.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
 /**
  * Non-interactive explore session: same graph/library/mem/browser setup
  * `runAutoExplore` runs in `--cli` mode, driven by `applyPick` instead of a
@@ -101,20 +106,18 @@ export class AutoSession {
         const page = await context.newPage();
         instrumentPilotActions(page, headless ? 0 : 450);
         if (startUrl) {
-            await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
-            await page.waitForLoadState("load").catch(() => { });
+            await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+            await page.waitForLoadState("load").catch(ignoreTimeout);
         }
         else {
-            await page.goto("about:blank").catch(() => { });
+            await page.goto("about:blank").catch(ignorePageGone);
         }
         const knownInteractionSelectors = collectKnownInteractionSelectors(init.projectDir, library, init.inject);
         const session = new AutoSession(init.projectDir, init.inject, init.blocksSelect, graph, library, mem, engine, closeBrowser, context, page, startUrl, init.sessionId, knownInteractionSelectors, headless);
-        page.on("load", () => {
-            void session.repaintOverlayAfterNavigation();
-        });
+        keepOverlayOnNavigation(page, () => session.repaintOverlayAfterNavigation());
         if (!headless) {
-            await session.bootstrapOverlay().catch(() => { });
-            await page.bringToFront().catch(() => { });
+            await session.bootstrapOverlay().catch(ignorePageGone);
+            await page.bringToFront().catch(ignorePageGone);
         }
         // Attached once, on the page created here - `ensureLivePage` only swaps
         // to a fresh Page if the current one closed (a rare case, e.g. the human
@@ -204,11 +207,11 @@ export class AutoSession {
     /** Re-apply cached overlay state after navigation (init script restores shell only). */
     async repaintOverlayAfterNavigation() {
         if (this.lastOverlayInfo) {
-            await updatePilotOverlay(this.page, this.lastOverlayInfo).catch(() => { });
+            await updatePilotOverlay(this.page, this.lastOverlayInfo).catch(ignorePageGone);
             return;
         }
         if (!this.headless) {
-            await this.bootstrapOverlay().catch(() => { });
+            await this.bootstrapOverlay().catch(ignorePageGone);
         }
     }
     /**
@@ -233,7 +236,7 @@ export class AutoSession {
             knownPathnames,
             knownSelectors: this.knownInteractionSelectors,
         };
-        await this.page.evaluate(unmappedInteractionsPageScript, payload).catch(() => { });
+        await this.page.evaluate(unmappedInteractionsPageScript, payload).catch(ignorePageGone);
     }
     /** Pure getter - no Block runs, no mem/page mutation. */
     async currentSnapshot() {
@@ -342,7 +345,7 @@ export class AutoSession {
         const fixtures = phaseToOverlayFixtures(phase, holdMs);
         for (const line of describeOverlayFixtures(tag, fixtures))
             verboseLog("pilot", line);
-        await showPilotFixtures(this.page, fixtures).catch(() => { });
+        await showPilotFixtures(this.page, fixtures).catch(ignorePageGone);
     }
     async runNamedBlock(entry, expectedTo, instanceOption) {
         const from = this.here;

package/dist/{auto-session → live/auto-session}/helpers.d.ts

@@ -1,8 +1,10 @@
-import type { StubPhaseResult } from "../highlights.js";
-import type { BlockEntry, ExploreMenu } from "../session/auto-explore.js";
-import type { PickResult } from "../session/auto-explore-run.js";
+import type { StubPhaseResult } from "../../engine/stub/stub.js";
+import type { ExploreMenu } from "../auto/explore.js";
+import type { BlockEntry } from "../../manifest/project.js";
+import type { PickResult } from "../auto/auto.js";
 /** True when a stub-phase result actually carries authored content worth keeping. */
 export declare function stubPhaseHasContent(r: StubPhaseResult): boolean;
+/** One available move in a session snapshot: a Block and the Checkpoint it leads to. */
 export interface SessionSnapshotEdge {
     /** 1-based, matching the numbers a human/agent picks by (same as printCliMenu). */
     index: number;
@@ -12,10 +14,12 @@ export interface SessionSnapshotEdge {
     label?: string;
     description?: string;
 }
+/** A group of moves in a session snapshot, by page. */
 export interface SessionSnapshotSection {
     title: string;
     edges: SessionSnapshotEdge[];
 }
+/** The state of a live session: where it is, the moves available from there, and the trace so far. */
 export interface SessionSnapshot {
     here: string | null;
     sections: SessionSnapshotSection[];
@@ -82,11 +86,12 @@ export declare function walkFullDom(root: Element, caps: FullDomCaps): {
     tree: FullDomNode;
     truncated: boolean;
 };
+/** What `AutoSession.start` needs: project, selection, headless mode and the session id. */
 export interface AutoSessionInit {
     projectDir: string;
     baseURL?: string;
     startUrl?: string;
-    blocksSelect?: import("../blocks-select.js").BlocksSelect;
+    blocksSelect?: import("../../manifest/select.js").BlocksSelect;
     /** Absolute paths — merged Block libraries (see `waygraph browser --inject`). */
     inject?: string[];
     /** When true, open about:blank instead of baseURL/startUrl (browser default). */
@@ -102,6 +107,7 @@ export interface AutoSessionInit {
      */
     sessionId?: string;
 }
+/** The result of running one menu pick in a live session. */
 export type ApplyPickResult = {
     ok: true;
     snapshot: SessionSnapshot;
@@ -110,6 +116,7 @@ export type ApplyPickResult = {
     ok: false;
     error: string;
 };
+/** The result of running a multi-step route in a live session. */
 export type ApplyPathResult = {
     ok: true;
     path: string[];
@@ -133,7 +140,7 @@ export interface TraceStep {
      * Resolved demo-narration fixtures (highlights/todos/device), when the
      * Block actually authors `stubBefore`/`stubAfter`/`stubOnError` - the same
      * data `waygraph demo`'s lifecycle logging already computes (`runStubPhase`
-     * in highlights.ts), reused here for extra context on what a step meant to
+     * in demo/narration/index.ts), reused here for extra context on what a step meant to
      * convey. Omitted when the Block has none, or the result carries nothing.
      */
     stubBefore?: StubPhaseResult;
@@ -141,6 +148,7 @@ export interface TraceStep {
     stubOnError?: StubPhaseResult;
 }
 export declare const TRACE_MAX_STEPS = 500;
+/** Which stub file a live session wrote: before, after or on-error. */
 export type StubFileKind = "image" | "pdf" | "video";
 /**
  * Real, minimal, valid fixture files bundled at `assets/stubs/` - not
@@ -180,11 +188,13 @@ export interface ConsoleLogEntry {
     timestamp: string;
 }
 export declare const CONSOLE_LOG_MAX_ENTRIES = 200;
+/** One service worker registration as reported by a live session. */
 export interface ServiceWorkerRegistrationInfo {
     scope: string;
     activeUrl?: string;
     state?: string;
 }
+/** One cookie as reported by a live session's `auto cookies`. */
 export interface CookieInfo {
     name: string;
     value: string;
@@ -193,6 +203,7 @@ export interface CookieInfo {
     httpOnly: boolean;
     secure: boolean;
 }
+/** Local and session storage of a live session's page. */
 export interface StorageSnapshot {
     localStorage: Record<string, string>;
     sessionStorage: Record<string, string>;

package/dist/{auto-session → live/auto-session}/helpers.js

@@ -137,7 +137,7 @@ export const TRACE_MAX_STEPS = 500;
  * exist for more than a moment.
  */
 export function stubFilePath(kind) {
-    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
     const names = {
         image: "stub.png",
         pdf: "stub.pdf",

package/dist/{session/auto-session-ipc.d.ts → live/auto-session/ipc.d.ts}

@@ -1,6 +1,6 @@
-import { AutoSession, type AutoSessionInit, type SessionSnapshot, type InspectDomOptions, type DomSnapshot, type TraceStep, type ApplyPathResult, type ConsoleLogEntry, type StorageSnapshot, type StubFileKind } from "../auto-session.js";
-import type { PilotHighlightFixtures } from "../pilot-overlay.js";
-export type { PilotHighlightFixtures } from "../pilot-overlay.js";
+import { AutoSession } from "./auto-session.js";
+import { type AutoSessionInit, type SessionSnapshot, type InspectDomOptions, type DomSnapshot, type TraceStep, type ApplyPathResult, type ConsoleLogEntry, type StorageSnapshot, type StubFileKind } from "./helpers.js";
+import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
 export interface SessionMeta {
     sessionId: string;
     socketPath: string;
@@ -128,8 +128,10 @@ export declare function serveSession(session: AutoSession, projectDir: string, s
 export declare function runAutoServeCommand(init: AutoSessionInit, sessionId: string): Promise<void>;
 /**
  * Parent-side: spawns a detached background process running the same
- * explore session as a socket server, waits for it to signal readiness (its
- * metadata file appearing), and returns its identity. Recurses through the
+ * explore session as a socket server, waits for it to say it is serving (one
+ * message over an IPC channel, then disconnect), and returns its identity. A
+ * child that exits or stays silent past the timeout fails the start, and a silent
+ * one is stopped. Recurses through the
  * existing `bin/waygraph` launcher (same tsx/esm registration every other
  * invocation already gets) with the hidden `__auto-serve` command, rather
  * than re-implementing that resolution here.

package/dist/{session/auto-session-ipc.js → live/auto-session/ipc.js}

@@ -14,7 +14,8 @@ import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
-import { AutoSession, } from "../auto-session.js";
+import { AutoSession } from "./auto-session.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
 function sessionDir(projectDir) {
     return join(projectDir, ".waygraph-auto");
 }
@@ -318,7 +319,7 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
             return;
         shuttingDown = true;
         server.close();
-        await session.close().catch(() => { });
+        await session.close().catch(ignorePageGone);
         removeSessionFiles(projectDir, sessionId);
         process.exit(0);
     }
@@ -343,14 +344,19 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
 export async function runAutoServeCommand(init, sessionId) {
     const session = await AutoSession.start({ ...init, sessionId });
     await serveSession(session, init.projectDir, sessionId, init.headless ?? true);
+    // Tell the parent that spawned us (spawnDetachedSession) we are serving, then let it go.
+    process.send?.({ ready: true });
+    process.disconnect?.();
     // Keep the event loop alive - the listening server already does this,
     // but await forever here documents the intent for a reader.
     await new Promise(() => { });
 }
 /**
  * Parent-side: spawns a detached background process running the same
- * explore session as a socket server, waits for it to signal readiness (its
- * metadata file appearing), and returns its identity. Recurses through the
+ * explore session as a socket server, waits for it to say it is serving (one
+ * message over an IPC channel, then disconnect), and returns its identity. A
+ * child that exits or stays silent past the timeout fails the start, and a silent
+ * one is stopped. Recurses through the
  * existing `bin/waygraph` launcher (same tsx/esm registration every other
  * invocation already gets) with the hidden `__auto-serve` command, rather
  * than re-implementing that resolution here.
@@ -358,12 +364,12 @@ export async function runAutoServeCommand(init, sessionId) {
 export async function spawnDetachedSession(init, readyTimeoutMs = 20_000) {
     const sessionId = generateSessionId();
     mkdirSync(sessionDir(init.projectDir), { recursive: true });
-    // This file compiles to dist/session/auto-session-ipc.js - two levels down from the package
+    // This file compiles to dist/live/auto-session/ipc.js - three levels down from the package
     // root, not one. Same bug class as cli/util.ts's own packageRoot(); see its comment.
-    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
     const require = createRequire(join(pkgRoot, "package.json"));
     const tsxEsm = require.resolve("tsx/esm");
-    const cli = join(pkgRoot, "dist", "cli.js");
+    const cli = join(pkgRoot, "dist", "cli", "cli.js");
     const logFd = openSync(logPathFor(init.projectDir, sessionId), "a");
     const args = ["--import", tsxEsm, cli, "__auto-serve", init.projectDir, "--session-id", sessionId];
     if (init.baseURL)
@@ -382,20 +388,29 @@ export async function spawnDetachedSession(init, readyTimeoutMs = 20_000) {
     // Spawn cli.js directly — not bin/waygraph (which would fork a second Node).
     const child = spawn(process.execPath, args, {
         detached: true,
-        stdio: ["ignore", logFd, logFd],
+        stdio: ["ignore", logFd, logFd, "ipc"],
         windowsHide: true,
         env: process.env,
     });
+    const log = logPathFor(init.projectDir, sessionId);
+    const outcome = await new Promise((done) => {
+        const timer = setTimeout(() => done("timeout"), readyTimeoutMs);
+        child.once("message", () => (clearTimeout(timer), done("ready")));
+        child.once("exit", (code) => (clearTimeout(timer), done({ exit: code })));
+    });
+    if (child.connected)
+        child.disconnect();
     child.unref();
-    const deadline = Date.now() + readyTimeoutMs;
-    while (Date.now() < deadline) {
-        const meta = readSessionMeta(init.projectDir, sessionId);
-        if (meta)
-            return meta;
-        await new Promise((r) => setTimeout(r, 150));
+    if (outcome === "timeout") {
+        child.kill("SIGTERM");
+        throw new Error(`session "${sessionId}" did not become ready within ${readyTimeoutMs}ms (stopped it) - check ${log} for errors`);
     }
-    throw new Error(`session "${sessionId}" did not become ready within ${readyTimeoutMs}ms - ` +
-        `check ${logPathFor(init.projectDir, sessionId)} for errors`);
+    if (outcome !== "ready")
+        throw new Error(`session "${sessionId}" exited (code ${outcome.exit}) before it was ready - check ${log}`);
+    const meta = readSessionMeta(init.projectDir, sessionId);
+    if (!meta)
+        throw new Error(`session "${sessionId}" said it was ready but wrote no metadata - check ${log}`);
+    return meta;
 }
 /** Stop one detached session (SIGTERM + cleanup metadata/socket). */
 export function stopBrowserSession(projectDir, sessionId) {

package/dist/{session/browser.d.ts → live/auto-session/start.d.ts}

@@ -1,4 +1,4 @@
-import type { AutoSessionInit } from "../auto-session.js";
+import type { AutoSessionInit } from "./helpers.js";
 export interface BrowserStartInit extends AutoSessionInit {
     /** Preset names or paths; resolved before spawn. */
     injectTokens?: string[];
@@ -12,4 +12,3 @@ export interface BrowserStartResult {
 }
 /** Always spawns a new detached session — does not stop or reuse existing ones. */
 export declare function browserStart(init: BrowserStartInit): Promise<BrowserStartResult>;
-export { listBrowserSessions, stopBrowserSession, stopAllBrowserSessions, type SessionMeta, } from "./auto-session-ipc.js";

package/dist/{session/browser.js → live/auto-session/start.js}

@@ -6,8 +6,8 @@
  * Session lifecycle is explicit: `browser sessions` lists what's live;
  * `browser start` always opens another; `browser attach` / `browser stop` pick one up or shut it down.
  */
-import { spawnDetachedSession } from "./auto-session-ipc.js";
-import { resolveInjectRoots } from "./block-inject.js";
+import { spawnDetachedSession } from "./ipc.js";
+import { resolveInjectRoots } from "../../manifest/roots.js";
 /** Always spawns a new detached session — does not stop or reuse existing ones. */
 export async function browserStart(init) {
     const inject = init.inject ??
@@ -26,4 +26,3 @@ export async function browserStart(init) {
         inject,
     };
 }
-export { listBrowserSessions, stopBrowserSession, stopAllBrowserSessions, } from "./auto-session-ipc.js";

package/dist/{pilot-overlay → live/pilot}/panel.d.ts

@@ -1,4 +1,4 @@
-import type { SessionSnapshot } from "../auto-session.js";
+import type { SessionSnapshot } from "../auto-session/helpers.js";
 import type { Page } from "@playwright/test";
 /** Minimal shape needed to render the graph tree - matches WaygraphGraph. */
 interface PilotOverlayGraph {

package/dist/{pilot-overlay → live/pilot}/panel.js

@@ -1,4 +1,5 @@
-import { ensureInstalled } from "./shell.js";
+import { ensureInstalled } from "../../demo/overlay/pilot/shell.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
 /**
  * Refreshes the badge text and the (possibly-collapsed) panel's two tabs
  * ("Here" - current live menu; "All nodes" - whole project graph as a
@@ -10,6 +11,8 @@ export async function updatePilotOverlay(page, info) {
     await ensureInstalled(page);
     await page
         .evaluate(async ({ sessionId, snapshot, graph }) => {
+        // Block names, labels and descriptions can carry the page's own text (an Effect's instance label is read off
+        // the live DOM), so they go in as text nodes (__wgEl), never as markup.
         const badge = __wgById("wg-pilot-badge");
         const current = __wgById("wg-pilot-panel-current");
         const graphPanel = __wgById("wg-pilot-panel-graph");
@@ -21,26 +24,16 @@ export async function updatePilotOverlay(page, info) {
         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>';
+            __wgSet(current, __wgEl("div", { class: "wg-pilot-empty" }, onBlank ? "Blank page — no Block moves yet. Use auto goto or a nav Block when ready." : "No Block moves from here right now."));
         }
         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("");
+            __wgSet(current, snapshot.sections.map((section) => [
+                __wgEl("div", { class: "wg-pilot-section" }, section.title),
+                section.edges.map((edge) => __wgEl("div", { class: "wg-pilot-edge" }, `[${edge.index}] `, __wgEl("span", { class: "wg-pilot-kind" }, edge.kind), ` ${edge.block}${edge.label ? ` (${edge.label})` : ""} -> ${edge.to}${edge.description ? ` - ${edge.description}` : ""}`)),
+            ]));
         }
         if (!graph || graph.nodes.length === 0) {
-            graphPanel.innerHTML = '<div class="wg-pilot-empty">No graph data yet.</div>';
+            __wgSet(graphPanel, __wgEl("div", { class: "wg-pilot-empty" }, "No graph data yet."));
             return;
         }
         // Flat indented-text tree - the ORIGINAL "All nodes" rendering.
@@ -49,18 +42,14 @@ export async function updatePilotOverlay(page, info) {
         // when Mermaid genuinely can't load (e.g. offline), not the primary
         // rendering anymore.
         const renderTextTree = () => {
-            graphPanel.innerHTML = graph.nodes
-                .map((node) => {
+            __wgSet(graphPanel, 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>';
+                    ? outgoing.map((e) => __wgEl("div", { class: "wg-pilot-graph-edge" }, __wgEl("span", { class: "wg-pilot-kind" }, e.kind), ` ${e.block} -> ${e.to}`))
+                    : [__wgEl("div", { class: "wg-pilot-graph-edge wg-pilot-empty" }, "(no outgoing edges)")];
                 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("");
+                return __wgEl("div", { class: "wg-pilot-graph-node" }, __wgEl("div", { class: "wg-pilot-graph-checkpoint" }, node.checkpoint + here), rows);
+            }));
         };
         try {
             const w = window;
@@ -80,10 +69,11 @@ export async function updatePilotOverlay(page, info) {
                 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" } });
+            // strict: Mermaid escapes label text itself; plain SVG labels (no HTML) so the result parses as SVG.
+            w.mermaid.initialize({ startOnLoad: false, theme: "dark", securityLevel: "strict", flowchart: { curve: "linear", htmlLabels: false } });
             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-
+            // (see live/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
@@ -137,8 +127,10 @@ export async function updatePilotOverlay(page, info) {
                 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>`;
+            const diagram = __wgSvg(svg);
+            if (diagram.nodeName !== "svg")
+                throw new Error("mermaid output did not parse as SVG");
+            __wgSet(graphPanel, diagram, __wgEl("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).'));
             // 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"
@@ -151,5 +143,5 @@ export async function updatePilotOverlay(page, info) {
             renderTextTree();
         }
     }, { sessionId: info.sessionId, snapshot: info.snapshot, graph: info.graph ?? null })
-        .catch(() => { });
+        .catch(ignorePageGone);
 }