waygraph 0.15.26 → 0.15.28

package/dist/auto-session.js

@@ -1,843 +1,3 @@
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { Engine } from "./engine.js";
-import { MemPage } from "./mem-page.js";
-import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
-import { ensureLivePage, detectHere, seedDefaultMem, ensureMem, runOneBlock, resolveBaseUrl, } from "./auto-explore-run.js";
-import { runStubPhase } from "./highlights.js";
-import { findBlockPathDetailed } from "./graph.js";
-import { updatePilotOverlay, showPilotActivity, showPilotVision, showPilotFixtures, installPersistentPilotOverlay, } from "./pilot-overlay.js";
-import { collectKnownInteractionSelectors, unmappedInteractionsPageScript, } from "./coverage-gap.js";
-/** True when a stub-phase result actually carries authored content worth keeping. */
-function stubPhaseHasContent(r) {
-    return (Object.keys(r.highlights).length > 0 ||
-        r.todos.length > 0 ||
-        r.device !== undefined ||
-        r.todoDock !== undefined);
-}
-/** Plain, JSON-serializable view of a menu - no Block/MemKey/class references. */
-export function buildSessionSnapshot(menu, library, here, lastRunNote) {
-    let n = 0;
-    const sections = menu.sections.map((section) => ({
-        title: section.title,
-        edges: section.edges.map((edge) => {
-            n++;
-            const entry = library.get(edge.block);
-            return {
-                index: n,
-                block: edge.block,
-                kind: edge.kind,
-                to: edge.to,
-                ...(edge.label ? { label: edge.label } : {}),
-                ...(entry?.description ? { description: entry.description } : {}),
-            };
-        }),
-    }));
-    return { here, sections, done: menu.flat.length === 0, lastRunNote };
-}
-/**
- * Same number/`q`/range rules `cliPick` already applies, but returning a
- * result instead of looping to re-prompt - one request gets one answer.
- * Also accepts a Block name (exact, case-sensitive) as a shorthand for its
- * menu index - `send <id> "submit-login"` instead of hunting the number.
- * Ambiguous (the same Block name appearing more than once in one menu)
- * refuses rather than guessing which occurrence was meant - a pick runs a
- * real browser action, not something to silently get wrong.
- */
-export function parsePick(raw, menu) {
-    const ans = raw.trim();
-    const lower = ans.toLowerCase();
-    if (lower === "q" || lower === "quit")
-        return { type: "quit" };
-    const n = Number(lower);
-    if (Number.isInteger(n) && n >= 1 && n <= menu.flat.length) {
-        return { type: "pick", index: n - 1 };
-    }
-    const matches = [];
-    menu.flat.forEach((edge, i) => {
-        if (edge.block === ans)
-            matches.push(i);
-    });
-    if (matches.length === 1) {
-        return { type: "pick", index: matches[0] };
-    }
-    if (matches.length > 1) {
-        return {
-            type: "invalid",
-            reason: `"${raw}" matches ${matches.length} menu entries - use the numeric index instead of the Block name`,
-        };
-    }
-    return {
-        type: "invalid",
-        reason: `"${raw}" is not a valid pick - enter a number from 1 to ${menu.flat.length}, a Block name, or "q" to quit`,
-    };
-}
-const FULL_MODE_DEFAULT_DEPTH = 12;
-const FULL_MODE_MAX_NODES = 800;
-const FULL_MODE_MAX_TEXT_LENGTH = 300;
-/** Runs entirely inside the browser (page.evaluate) - no closures over outer TS state. */
-function walkFullDom(root, caps) {
-    let count = 0;
-    let truncated = false;
-    function walk(el, depth) {
-        if (depth > caps.depth) {
-            truncated = true;
-            return null;
-        }
-        if (count >= caps.maxNodes) {
-            truncated = true;
-            return null;
-        }
-        count++;
-        const node = { tag: el.tagName.toLowerCase() };
-        const attrs = {};
-        for (const a of Array.from(el.attributes))
-            attrs[a.name] = a.value;
-        if (Object.keys(attrs).length > 0)
-            node.attrs = attrs;
-        const directText = Array.from(el.childNodes)
-            .filter((n) => n.nodeType === 3)
-            .map((n) => n.textContent ?? "")
-            .join("")
-            .trim();
-        if (directText) {
-            node.text =
-                directText.length > caps.maxTextLength
-                    ? directText.slice(0, caps.maxTextLength) + "..."
-                    : directText;
-        }
-        const children = [];
-        for (const child of Array.from(el.children)) {
-            if (count >= caps.maxNodes) {
-                truncated = true;
-                break;
-            }
-            const c = walk(child, depth + 1);
-            if (c)
-                children.push(c);
-        }
-        if (children.length > 0)
-            node.children = children;
-        return node;
-    }
-    const tree = walk(root, 0) ?? { tag: root.tagName.toLowerCase() };
-    return { tree, truncated };
-}
-const TRACE_MAX_STEPS = 500;
-/**
- * Real, minimal, valid fixture files bundled at `assets/stubs/` - not
- * placeholder/renamed-empty files: `stub.png` is a real 1x1 PNG,
- * `stub.pdf` a real single-page PDF, `stub.mp4` a real ffmpeg-encoded
- * 1s black clip. Real, direct user request: Blind Pilot hitting a real
- * `<input type="file">` (e.g. an avatar upload) had no way to supply
- * anything without a human handing over a real file each time - these are
- * small enough to ship in the package and pass most apps' basic file-type
- * checks (magic bytes, not just extension).
- */
-/**
- * Public so a Block a consumer writes can reach the same real fixture files
- * `rawUpload` uses - not just the raw primitive. Needed when a real upload
- * flow has no stable `<input type="file">` to hand a selector to at all
- * (e.g. one created on the fly inside a click handler, then immediately
- * `.click()`'d to open the OS picker and possibly torn down right after) -
- * a Block's own `act()` should pair this with `page.waitForEvent("filechooser")`
- * around the triggering click, not go hunting for a selector that may not
- * exist for more than a moment.
- */
-export function stubFilePath(kind) {
-    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-    const names = {
-        image: "stub.png",
-        pdf: "stub.pdf",
-        video: "stub.mp4",
-    };
-    return join(packageRoot, "assets", "stubs", names[kind]);
-}
-const CONSOLE_LOG_MAX_ENTRIES = 200;
-/**
- * Non-interactive explore session: same graph/library/mem/browser setup
- * `runAutoExplore` runs in `--cli` mode, driven by `applyPick` instead of a
- * blocking `readline` loop. Headless by default (matching
- * `runAutoExplore`'s own `cli` branch), optionally visible via
- * `AutoSessionInit.headless: false` - this type only ever backs the `--cli`
- * picker, never the headful page-embedded panel, headless or not.
- */
-export class AutoSession {
-    projectDir;
-    inject;
-    blocksSelect;
-    graph;
-    library;
-    mem;
-    engine;
-    browser;
-    context;
-    page;
-    startUrl;
-    sessionId;
-    here = null;
-    lastRunNote = null;
-    trace = [];
-    consoleLog = [];
-    knownInteractionSelectors;
-    headless;
-    lastOverlayInfo = null;
-    constructor(projectDir, inject, blocksSelect, graph, library, mem, engine, browser, context, page, startUrl, sessionId, knownInteractionSelectors, headless) {
-        this.projectDir = projectDir;
-        this.inject = inject;
-        this.blocksSelect = blocksSelect;
-        this.graph = graph;
-        this.library = library;
-        this.mem = mem;
-        this.engine = engine;
-        this.browser = browser;
-        this.context = context;
-        this.page = page;
-        this.startUrl = startUrl;
-        this.sessionId = sessionId;
-        this.knownInteractionSelectors = knownInteractionSelectors;
-        this.headless = headless;
-    }
-    static async start(init) {
-        const baseURL = init.baseURL ?? resolveBaseUrl(init.projectDir);
-        const skipNav = init.skipInitialNavigation === true;
-        const startUrl = skipNav ? undefined : (init.startUrl ?? baseURL);
-        const exploreOpts = {
-            ...(init.blocksSelect ? { blocksSelect: init.blocksSelect } : {}),
-            ...(init.inject?.length ? { inject: init.inject } : {}),
-        };
-        const { graph, library } = await buildExploreContext(init.projectDir, Object.keys(exploreOpts).length ? exploreOpts : undefined);
-        const mem = new MemPage();
-        seedDefaultMem(library.byName, mem);
-        const headless = init.headless ?? true;
-        const engine = new Engine({ headless });
-        const { chromium } = await import("@playwright/test");
-        const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
-        // Real gap found live: a headed (--non-headless) session kept a fixed
-        // 1280x720 content area even when the user maximized/fullscreened the
-        // actual window - `viewport: null` alone only makes the PAGE track the
-        // window; the window itself still launches at Chromium's own small
-        // default size unless told to start maximized. Same fix cli.ts's own
-        // --step/headed launch already uses (see its own comment there) -
-        // headless keeps the fixed viewport since there's no real window to size.
-        const launchOpts = {
-            headless,
-            // Keep Playwright's default --no-startup-window for headful: without it
-            // Chromium opens its own "New Tab" window AND our context.newPage() opens
-            // a second about:blank window. bringToFront() below surfaces the real page.
-            args: headless ? [] : ["--start-maximized"],
-        };
-        if (executablePath)
-            launchOpts.executablePath = executablePath;
-        const browser = await chromium.launch(launchOpts);
-        const contextOpts = {
-            viewport: headless ? { width: 1280, height: 720 } : null,
-        };
-        if (baseURL)
-            contextOpts.baseURL = baseURL;
-        const context = await browser.newContext(contextOpts);
-        await installPersistentPilotOverlay(context);
-        const page = await context.newPage();
-        if (startUrl) {
-            await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
-            await page.waitForLoadState("load").catch(() => { });
-        }
-        else {
-            await page.goto("about:blank").catch(() => { });
-        }
-        const knownInteractionSelectors = collectKnownInteractionSelectors(init.projectDir, library, init.inject);
-        const session = new AutoSession(init.projectDir, init.inject, init.blocksSelect, graph, library, mem, engine, browser, context, page, startUrl, init.sessionId, knownInteractionSelectors, headless);
-        page.on("load", () => {
-            void session.repaintOverlayAfterNavigation();
-        });
-        if (!headless) {
-            await session.bootstrapOverlay().catch(() => { });
-            await page.bringToFront().catch(() => { });
-        }
-        // 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
-        // closing the tab), not on ordinary same-page SPA navigation, which is
-        // all this target (and most real sites) actually do.
-        page.on("console", (msg) => {
-            session.pushConsoleLog({
-                type: "console",
-                level: msg.type(),
-                text: msg.text(),
-                timestamp: new Date().toISOString(),
-            });
-        });
-        page.on("pageerror", (err) => {
-            session.pushConsoleLog({
-                type: "pageerror",
-                text: err instanceof Error ? err.message : String(err),
-                timestamp: new Date().toISOString(),
-            });
-        });
-        page.on("response", (res) => {
-            // Every failed response (the original case), PLUS every mutation
-            // (non-GET) response regardless of status - a real gap found live:
-            // "auto console" only logging failures made a SUCCESSFUL POST that
-            // simply didn't navigate anywhere look identical to "nothing
-            // happened at all," undiagnosable the same way a real failure was.
-            // A mutation's outcome (2xx or not) is always diagnostically
-            // relevant; a GET's usually isn't (assets, trackers) unless it failed.
-            const method = res.request().method();
-            if (res.status() < 400 && method === "GET")
-                return;
-            session.pushConsoleLog({
-                type: "response",
-                text: `${method} ${res.statusText()}`,
-                url: res.url(),
-                status: res.status(),
-                timestamp: new Date().toISOString(),
-            });
-        });
-        return session;
-    }
-    /** Pure getter - returns a copy, not the live array. */
-    getTrace() {
-        return [...this.trace];
-    }
-    pushTrace(step) {
-        this.trace.push(step);
-        if (this.trace.length > TRACE_MAX_STEPS)
-            this.trace.shift();
-    }
-    /** Pure getter - returns a copy, not the live array. */
-    getConsoleLog() {
-        return [...this.consoleLog];
-    }
-    pushConsoleLog(entry) {
-        this.consoleLog.push(entry);
-        if (this.consoleLog.length > CONSOLE_LOG_MAX_ENTRIES)
-            this.consoleLog.shift();
-    }
-    async currentMenu() {
-        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        if (this.here === null) {
-            this.here = await detectHere(this.page, this.library.navBlocks);
-        }
-        const menu = await buildExploreMenu(this.page, this.graph, this.library, this.here);
-        // Every caller of currentMenu() (status reads, applyPick/applyPath,
-        // the raw click/type/goto primitives, resync) already routes through
-        // here, so hooking the overlay refresh at this one point covers every
-        // real state-changing (and reading) path without needing a separate
-        // call at each site. Awaited deliberately, not fire-and-forget - the
-        // whole point is a human watching the screen sees the SAME state a
-        // concurrent API caller just got back, not a stale frame that catches
-        // up moments later.
-        this.lastOverlayInfo = {
-            sessionId: this.sessionId,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
-            graph: this.graph,
-        };
-        await updatePilotOverlay(this.page, this.lastOverlayInfo);
-        await this.warnUnmappedInteractions();
-        return menu;
-    }
-    /** Paint the overlay on about:blank / immediately after session start (headful browser). */
-    async bootstrapOverlay() {
-        await this.currentMenu();
-    }
-    /** Re-apply cached overlay state after navigation (init script restores shell only). */
-    async repaintOverlayAfterNavigation() {
-        if (this.lastOverlayInfo) {
-            await updatePilotOverlay(this.page, this.lastOverlayInfo).catch(() => { });
-            return;
-        }
-        if (!this.headless) {
-            await this.bootstrapOverlay().catch(() => { });
-        }
-    }
-    /**
-     * Flags same-origin `<a href>` paths and visible buttons with no NavBlock
-     * URL / Block selector in the loaded library — read via `auto console`.
-     * Deduped per page load so repeated status/send calls stay quiet.
-     */
-    async warnUnmappedInteractions() {
-        const knownPathnames = [];
-        for (const entry of this.library.navBlocks) {
-            const url = entry.block.__waygraphNavUrl;
-            if (!url)
-                continue;
-            try {
-                knownPathnames.push(new URL(url, this.page.url()).pathname);
-            }
-            catch {
-                /* not a resolvable URL (relative to an unset base, etc.) - skip */
-            }
-        }
-        const payload = {
-            knownPathnames,
-            knownSelectors: this.knownInteractionSelectors,
-        };
-        await this.page.evaluate(unmappedInteractionsPageScript, payload).catch(() => { });
-    }
-    /** Pure getter - no Block runs, no mem/page mutation. */
-    async currentSnapshot() {
-        const menu = await this.currentMenu();
-        return buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote);
-    }
-    /**
-     * Pure getter - reads the live page's structure at the requested fidelity.
-     * No Block runs, no mem/page mutation. `selector` scopes either mode to one
-     * element's subtree; it is a modifier, not a third mode.
-     */
-    async inspectDom(opts) {
-        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        const mode = opts.mode ?? "aria";
-        const ariaOptions = opts.depth !== undefined ? { mode: "ai", depth: opts.depth } : { mode: "ai" };
-        if (opts.selector) {
-            const locator = this.page.locator(opts.selector).first();
-            if ((await locator.count()) === 0) {
-                return { ok: false, error: `no element matches selector "${opts.selector}"` };
-            }
-            await showPilotVision(this.page, opts.selector, `dom (${mode}): ${opts.selector}`, "orange");
-            if (mode === "full") {
-                const caps = {
-                    depth: opts.depth ?? FULL_MODE_DEFAULT_DEPTH,
-                    maxNodes: FULL_MODE_MAX_NODES,
-                    maxTextLength: FULL_MODE_MAX_TEXT_LENGTH,
-                };
-                const { tree, truncated } = await locator.evaluate(walkFullDom, caps);
-                return { ok: true, snapshot: { mode: "full", selector: opts.selector, truncated, tree } };
-            }
-            const tree = await locator.ariaSnapshotJSON(ariaOptions);
-            return { ok: true, snapshot: { mode: "aria", selector: opts.selector, truncated: false, tree } };
-        }
-        await showPilotActivity(this.page, `Running (Dom): ${mode}, whole page`);
-        if (mode === "full") {
-            // page.evaluate only ships the one function passed to it - it can't
-            // reach another named function by closure. Routing the whole-page case
-            // through the same `html` Locator lets both cases share one
-            // self-contained walkFullDom instead of two near-duplicate callbacks.
-            const caps = {
-                depth: opts.depth ?? FULL_MODE_DEFAULT_DEPTH,
-                maxNodes: FULL_MODE_MAX_NODES,
-                maxTextLength: FULL_MODE_MAX_TEXT_LENGTH,
-            };
-            const { tree, truncated } = await this.page.locator("html").first().evaluate(walkFullDom, caps);
-            return { ok: true, snapshot: { mode: "full", truncated, tree } };
-        }
-        const tree = await this.page.ariaSnapshotJSON(ariaOptions);
-        return { ok: true, snapshot: { mode: "aria", truncated: false, tree } };
-    }
-    /**
-     * Pure getter - reads the live page's client-side state: localStorage,
-     * sessionStorage, and registered service workers (scope/active URL/state).
-     * Real, direct follow-up to `auto console`'s own gap: a site doing web
-     * push (this target has a real `NOTIFICATION_VAPID` config, confirmed via
-     * `auto dom` earlier) keeps push-subscription/auth state in these places,
-     * not in the rendered DOM `inspectDom` reads.
-     */
-    async inspectStorage() {
-        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        const [localStorageEntries, sessionStorageEntries] = await this.page.evaluate(() => [
-            Object.entries(window.localStorage),
-            Object.entries(window.sessionStorage),
-        ]);
-        const cookies = await this.context.cookies();
-        const workers = this.context.serviceWorkers();
-        const registrations = await this.page
-            .evaluate(async () => {
-            if (!("serviceWorker" in navigator))
-                return [];
-            const regs = await navigator.serviceWorker.getRegistrations();
-            return regs.map((r) => ({
-                scope: r.scope,
-                ...(r.active?.scriptURL ? { activeUrl: r.active.scriptURL } : {}),
-                ...(r.active?.state ? { state: r.active.state } : {}),
-            }));
-        })
-            .catch(() => []);
-        return {
-            localStorage: Object.fromEntries(localStorageEntries),
-            sessionStorage: Object.fromEntries(sessionStorageEntries),
-            cookies: cookies.map((c) => ({
-                name: c.name,
-                value: c.value,
-                domain: c.domain,
-                path: c.path,
-                httpOnly: c.httpOnly,
-                secure: c.secure,
-            })),
-            serviceWorkers: workers.map((w) => w.url()),
-            serviceWorkerRegistrations: registrations,
-        };
-    }
-    /**
-     * Runs one already-resolved Block entry for real - the shared core both
-     * `applyPick` (resolved via a live-menu index) and `applyPath` (resolved
-     * directly by name, bypassing live-menu-visibility entirely - see
-     * `applyPath`'s own comment for why) call. `expectedTo` is only used as a
-     * fallback when a Block's own `resolve()` doesn't set `__state` - same
-     * behavior `applyPick` always had, just factored out, not changed.
-     */
-    async runNamedBlock(entry, expectedTo, instanceOption) {
-        const from = this.here;
-        const stubBeforeResult = await runStubPhase(entry.block, "stubBefore");
-        const stepBase = {
-            block: entry.block.name,
-            from,
-            timestamp: new Date().toISOString(),
-            ...(stubPhaseHasContent(stubBeforeResult) ? { stubBefore: stubBeforeResult } : {}),
-        };
-        try {
-            if (instanceOption) {
-                this.mem.set(instanceOption.key, instanceOption.value);
-            }
-            // Always the non-interactive path (cli: false) - a detached session has
-            // no TTY to prompt on; a missing mem key fails loud instead of hanging.
-            await ensureMem(entry, this.mem, false);
-            const result = await runOneBlock(this.engine, entry, this.context, this.page, this.mem, false);
-            this.here = result.__state ?? expectedTo;
-            this.lastRunNote = `${entry.block.name} -> ${this.here}`;
-            const stubAfterResult = await runStubPhase(entry.block, "stubAfter", { out: result });
-            this.pushTrace({
-                ...stepBase,
-                to: this.here,
-                ...(stubPhaseHasContent(stubAfterResult) ? { stubAfter: stubAfterResult } : {}),
-            });
-        }
-        catch (err) {
-            this.lastRunNote = `${entry.block.name} failed`;
-            const message = err instanceof Error ? err.message : String(err);
-            const stubOnErrorResult = await runStubPhase(entry.block, "stubOnError", { error: err });
-            this.pushTrace({
-                ...stepBase,
-                error: message,
-                ...(stubPhaseHasContent(stubOnErrorResult) ? { stubOnError: stubOnErrorResult } : {}),
-            });
-            return { ok: false, error: `${entry.block.name} failed - ${message}` };
-        }
-        const nextMenu = await this.currentMenu();
-        return {
-            ok: true,
-            snapshot: buildSessionSnapshot(nextMenu, this.library.byName, this.here, this.lastRunNote),
-            quit: false,
-        };
-    }
-    /** Applies exactly one pick: runs at most one Block, returns the resulting state. */
-    async applyPick(raw) {
-        const menu = await this.currentMenu();
-        const pick = parsePick(raw, menu);
-        if (pick.type === "invalid")
-            return { ok: false, error: pick.reason };
-        if (pick.type === "quit") {
-            return {
-                ok: true,
-                snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
-                quit: true,
-            };
-        }
-        const edge = menu.flat[pick.index];
-        const entry = this.library.byName.get(edge.block);
-        if (!entry) {
-            return { ok: false, error: `Block "${edge.block}" not loaded - skipped` };
-        }
-        await showPilotActivity(this.page, `Running (Block): ${edge.block}`);
-        return this.runNamedBlock(entry, edge.to, edge.instanceOption);
-    }
-    /**
-     * Re-discovers the project's Block library and graph from disk, using the
-     * exact same call `start()` itself makes - not a duplicated read - and
-     * replaces `this.library`/`this.graph` in place. Leaves the live page,
-     * mem, browser/context, and current Checkpoint (`here`) untouched, so a
-     * Block written to disk mid-session becomes pickable via a later
-     * `applyPick` without restarting the session. See
-     * openspec/changes/waygraph-blind-pilot/design.md.
-     */
-    async reloadLibrary() {
-        if (this.page)
-            await showPilotActivity(this.page, "Running: reload");
-        const exploreOpts = {
-            ...(this.blocksSelect ? { blocksSelect: this.blocksSelect } : {}),
-            ...(this.inject?.length ? { inject: this.inject } : {}),
-        };
-        const { graph, library } = await buildExploreContext(this.projectDir, Object.keys(exploreOpts).length ? exploreOpts : undefined);
-        this.graph = graph;
-        this.library = library;
-        if (this.page)
-            await showPilotActivity(this.page, "Map updated");
-    }
-    /**
-     * Forces `here` to be re-detected from the real live page, discarding
-     * whatever was cached - the fix for a real, confirmed gap: `here` is only
-     * ever updated by an action this class itself ran (`applyPick`/`applyPath`
-     * set it to a Block's own resolved Checkpoint; `rawClick`/`rawType`/
-     * `rawGoto` reset it to `null` because *they* just changed the page). If a
-     * human co-driving the same visible session clicks/types/navigates
-     * directly - a real scenario for a headful Pilot session someone is
-     * watching, not hypothetical - none of that goes through this class at
-     * all, so `here` silently goes stale: `currentMenu()`'s own lazy check
-     * (`if (this.here === null)`, just above) only re-detects when `here` is
-     * already unknown, never to confirm a *known* value is still correct.
-     * This does not crash the session (the process/socket/page all stay
-     * alive) but subsequent `send`/`reach` calls would act on a menu built
-     * from the wrong Checkpoint until something forces re-detection - this
-     * method is that: unconditionally re-run the same `detectHere` logic the
-     * lazy path already uses, regardless of what `here` currently holds.
-     */
-    async resync() {
-        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        await showPilotActivity(this.page, "Running: resync");
-        this.here = await detectHere(this.page, this.library.navBlocks);
-        const menu = await this.currentMenu();
-        this.lastRunNote = `resync -> ${this.here ?? "Unknown"}`;
-        return {
-            ok: true,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
-            quit: false,
-        };
-    }
-    /**
-     * Raw interaction primitives for a page no Block covers yet (Blind Pilot -
-     * see openspec/changes/waygraph-blind-pilot). Unlike `applyPick`, the
-     * resulting Checkpoint isn't known ahead of time from a Block's own
-     * `resolve()`, so each of these invalidates the cached `here` (forcing
-     * `currentMenu()`'s existing lazy `detectHere` call to run again) rather
-     * than assuming the page didn't move anywhere a Block now recognizes.
-     * A selector matching nothing is a reported failure, not a silent no-op.
-     */
-    async rawClick(selector) {
-        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        await showPilotActivity(this.page, `Running (no Block): click "${selector}"`);
-        const locator = this.page.locator(selector).first();
-        if ((await locator.count()) === 0) {
-            return { ok: false, error: `no element matches selector "${selector}"` };
-        }
-        await showPilotVision(this.page, selector, `click: ${selector}`);
-        await locator.click();
-        this.here = null;
-        const menu = await this.currentMenu();
-        this.lastRunNote = `click "${selector}" -> ${this.here ?? "Unknown"}`;
-        return {
-            ok: true,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
-            quit: false,
-        };
-    }
-    async rawType(selector, text) {
-        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        await showPilotActivity(this.page, `Running (no Block): type into "${selector}"`);
-        const locator = this.page.locator(selector).first();
-        if ((await locator.count()) === 0) {
-            return { ok: false, error: `no element matches selector "${selector}"` };
-        }
-        await showPilotVision(this.page, selector, `type: ${selector}`);
-        await locator.fill(text);
-        this.here = null;
-        const menu = await this.currentMenu();
-        this.lastRunNote = `type into "${selector}" -> ${this.here ?? "Unknown"}`;
-        return {
-            ok: true,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
-            quit: false,
-        };
-    }
-    /**
-     * Presses a real key on a real focused element - a real gap found live:
-     * many real inline-edit inputs (no visible Save button at all) commit on
-     * Enter, not on blur/click-elsewhere. `key` is a Playwright key name
-     * (e.g. "Enter", "Escape", "Tab") - same vocabulary as
-     * `page.keyboard.press`, which this wraps.
-     */
-    async rawPress(selector, key) {
-        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        await showPilotActivity(this.page, `Running (no Block): press "${key}" on "${selector}"`);
-        const locator = this.page.locator(selector).first();
-        if ((await locator.count()) === 0) {
-            return { ok: false, error: `no element matches selector "${selector}"` };
-        }
-        await showPilotVision(this.page, selector, `press ${key}: ${selector}`);
-        await locator.press(key);
-        this.here = null;
-        const menu = await this.currentMenu();
-        this.lastRunNote = `press "${key}" on "${selector}" -> ${this.here ?? "Unknown"}`;
-        return {
-            ok: true,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
-            quit: false,
-        };
-    }
-    async rawGoto(url) {
-        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        await showPilotActivity(this.page, `Running (no Block): goto "${url}"`);
-        try {
-            await this.page.goto(url, { waitUntil: "domcontentloaded" });
-        }
-        catch (err) {
-            return { ok: false, error: `goto "${url}" failed - ${err instanceof Error ? err.message : String(err)}` };
-        }
-        this.here = null;
-        const menu = await this.currentMenu();
-        this.lastRunNote = `goto "${url}" -> ${this.here ?? "Unknown"}`;
-        return {
-            ok: true,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
-            quit: false,
-        };
-    }
-    /**
-     * Fills a real `<input type="file">` - a built-in stub kind
-     * ("image"/"pdf"/"video", see `stubFilePath`) or a caller-supplied
-     * `filePath` for anything else ("whatever", per the real request this
-     * responds to). Same raw-primitive shape as click/type/goto: works with
-     * zero Blocks, invalidates `here` since the app may react to the upload.
-     */
-    async rawUpload(selector, stub) {
-        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        const filePath = typeof stub === "string" ? stubFilePath(stub) : stub.filePath;
-        const label = typeof stub === "string" ? stub : filePath;
-        await showPilotActivity(this.page, `Running (no Block): upload ${label} into "${selector}"`);
-        const locator = this.page.locator(selector).first();
-        if ((await locator.count()) === 0) {
-            return { ok: false, error: `no element matches selector "${selector}"` };
-        }
-        await showPilotVision(this.page, selector, `upload ${label}: ${selector}`);
-        try {
-            await locator.setInputFiles(filePath);
-        }
-        catch (err) {
-            return { ok: false, error: `upload into "${selector}" failed - ${err instanceof Error ? err.message : String(err)}` };
-        }
-        this.here = null;
-        const menu = await this.currentMenu();
-        this.lastRunNote = `upload ${label} into "${selector}" -> ${this.here ?? "Unknown"}`;
-        return {
-            ok: true,
-            snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
-            quit: false,
-        };
-    }
-    /**
-     * Agent-sent highlight fixtures (rings + optional todos) on the live page -
-     * the Pilot equivalent of Block `stubBefore` narration in `waygraph demo`.
-     * Does not run a Block; paint-only. Missing selectors are reported, not fatal.
-     */
-    async applyHighlight(fixtures) {
-        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
-        const detail = fixtures.clear === true
-            ? "clear"
-            : [
-                fixtures.rings?.length ? `${fixtures.rings.length} ring(s)` : null,
-                fixtures.todos?.length ? `${fixtures.todos.length} todo(s)` : null,
-                fixtures.zoom && fixtures.zoom > 1.001 ? `zoom ${fixtures.zoom}` : null,
-                fixtures.device
-                    ? `device ${typeof fixtures.device === "string" ? fixtures.device : fixtures.device.preset || "custom"}`
-                    : null,
-                fixtures.rings?.some((r) => r.focus) ? "focus" : null,
-            ]
-                .filter(Boolean)
-                .join(", ") || "fixtures";
-        // Same bottom-left activity toast as Running (Dom)/(Block) - agent narration.
-        await showPilotActivity(this.page, `Highlighting: ${detail}`);
-        try {
-            const { painted, missing } = await showPilotFixtures(this.page, fixtures);
-            const menu = await this.currentMenu();
-            this.lastRunNote = fixtures.clear
-                ? "highlight cleared"
-                : `highlight painted ${painted}` +
-                    (missing.length ? ` (missing: ${missing.join(", ")})` : "");
-            return {
-                ok: true,
-                painted,
-                missing,
-                snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
-            };
-        }
-        catch (err) {
-            return {
-                ok: false,
-                error: `highlight failed - ${err instanceof Error ? err.message : String(err)}`,
-            };
-        }
-    }
-    /**
-     * Runs a whole multi-step route to `targetCheckpoint` in one call, instead
-     * of an agent hand-picking one index at a time across many separate
-     * `applyPick` round trips - real, reported pain for any non-trivial task
-     * on a rich graph ("the entire prompts of the day" driving one step per
-     * call).
-     *
-     * Two other designs were tried and rejected by direct reproduction against
-     * live saucedemo.com before this one, both undone by the same root cause:
-     * a `from: "*"` edge (e.g. "Checkout", only clickable once you're actually
-     * on the cart page with items) looks globally reachable to
-     * `findBlockPath`'s static-graph BFS, which has no live-page access and
-     * can't know the edge's real precondition isn't showing yet. Computing the
-     * whole route once upfront names a premature wildcard step immediately;
-     * scoring each live menu option by its static-graph distance to the
-     * target (greedy best-first) doesn't fix it either - a harmless self-loop
-     * Method can score just as well as real progress once wildcard "shortcuts"
-     * are baked into every distance calculation, and the session gets stuck
-     * repeating it.
-     *
-     * The fix that actually works: stop trying to be clever about live-menu
-     * visibility per step, and reuse `auto --blocks <From> <To>`'s own already
-     * -proven approach instead - compute the path ONCE (via
-     * `findBlockPathDetailed`, the same BFS `findBlockPath`/`runChainAuto`
-     * already use, extended to also return each hop's specific edge - see its
-     * own doc comment for why that extra detail is load-bearing, not cosmetic),
-     * then run each Block in it directly via `runNamedBlock`, trusting the
-     * graph the same way `runChain`'s own flow execution already does, not
-     * gated on live-menu visibility at all. The one real difference from
-     * `runChainAuto`: this runs against the session's own already-live
-     * page/context/mem, not a freshly spawned browser - the whole point of
-     * staying in one session. A step whose real precondition genuinely isn't
-     * met still fails loud, naming that step, exactly the way a mis-ordered
-     * `runChain` spec would - and a step that runs without throwing but lands
-     * somewhere other than what its own edge promised (a real, observed case,
-     * not hypothetical - see this method's own test suite) fails loud too,
-     * rather than reporting false success.
-     */
-    async applyPath(targetCheckpoint) {
-        await this.currentMenu();
-        const from = this.here;
-        if (from === null) {
-            return { ok: false, error: "cannot path-find: the session's current Checkpoint is unknown (here is null)" };
-        }
-        const path = findBlockPathDetailed(this.graph, from, targetCheckpoint);
-        if (!path) {
-            return { ok: false, error: `no Block path from "${from}" to "${targetCheckpoint}" in the discovered graph` };
-        }
-        for (const step of path) {
-            const entry = this.library.byName.get(step.block);
-            if (!entry) {
-                return { ok: false, error: `path step "${step.block}" is in the discovered graph but not loaded in this session's library` };
-            }
-            if (entry.block.instanceOptions) {
-                return {
-                    ok: false,
-                    error: `path step "${step.block}" needs a specific live option chosen (an instanceOptions Block, e.g. one per product) - ambiguous for automatic routing, use applyPick directly with the specific index`,
-                };
-            }
-            if (this.page)
-                await showPilotActivity(this.page, `Running (Block): ${step.block} (reach -> ${targetCheckpoint})`);
-            const result = await this.runNamedBlock(entry, step.to);
-            if (!result.ok) {
-                return { ok: false, error: `step "${step.block}" failed - ${result.error}` };
-            }
-            // A Block can resolve to a DIFFERENT real Checkpoint than this exact
-            // hop's own edge expected, without throwing at all - e.g.
-            // submit-login's own resolve() legitimately "stays on LoginPage" on
-            // bad auth instead of erroring. Trusting `result.ok` alone would
-            // silently report success while sitting on the wrong page - a real
-            // bug caught by this method's own test suite, not theoretical.
-            // `step.to` (not a name-based re-lookup - a union-Out Block can have
-            // several edges sharing one name with different `to` tags) is exactly
-            // the Checkpoint THIS hop's own edge in the computed route promised.
-            if (this.here !== step.to) {
-                return {
-                    ok: false,
-                    error: `step "${step.block}" ran but landed on "${this.here}", not the expected "${step.to}" - it did not throw, but did not make the expected progress either`,
-                };
-            }
-        }
-        return { ok: true, path: path.map((s) => s.block), snapshot: await this.currentSnapshot() };
-    }
-    async close() {
-        await this.context.close();
-        await this.browser.close();
-    }
-}
+// Barrel: auto-session lives in src/auto-session/ (see src/ARCHITECTURE.md). Kept so existing imports of "./auto-session.js" don't change.
+export * from "./auto-session/helpers.js";
+export * from "./auto-session/session.js";