waygraph 0.16.0 → 0.16.2

package/dist/live/auto/menu.d.ts

@@ -0,0 +1,30 @@
+import type { Page } from "@playwright/test";
+import { createInterface } from "node:readline/promises";
+import type { MemKey, MemPage } from "../../engine/mem/mem.js";
+import type { BlockEntry } from "../../manifest/project.js";
+import type { ExploreMenu } from "./explore.js";
+export declare function setAutoPanelRunning(page: Page, label: string): Promise<void>;
+export declare const PANEL_CSS: string;
+export type PickResult = {
+    type: "pick";
+    index: number;
+} | {
+    type: "quit";
+};
+/**
+ * Mem keys any Block on the current menu might read this turn - minus keys a
+ * dynamic `instanceOptions` row already answers by picking it (e.g. "which
+ * item to add to cart" comes from the menu row itself, not a hand-typed JSON
+ * textarea).
+ */
+export declare function memKeysForMenu(menu: ExploreMenu, library: Map<string, BlockEntry>): readonly MemKey<unknown>[];
+export declare function syncPanelMem(page: Page, mem: MemPage, keys: readonly MemKey<unknown>[]): Promise<void>;
+export declare function armPickWait(): {
+    promise: Promise<PickResult>;
+    resolve: (v: PickResult) => void;
+};
+export declare function headfulPick(page: Page, menu: ExploreMenu, library: Map<string, BlockEntry>, mem: MemPage, waitPick: () => Promise<PickResult>, 
+/** What the last Block run did, shown at the top of the menu. */
+note: string | null): Promise<PickResult>;
+export declare function printCliMenu(menu: ExploreMenu, library: Map<string, BlockEntry>): void;
+export declare function cliPick(menu: ExploreMenu, rl: ReturnType<typeof createInterface>): Promise<PickResult>;

package/dist/live/auto/menu.js

@@ -0,0 +1,335 @@
+import { ensureShadowRoot } from "../../demo/overlay/ui/shadow.js";
+import { ignorePageGone } from "../../engine/page-gone.js";
+import { memStubValue } from "./mem.js";
+export async function setAutoPanelRunning(page, label) {
+    await page
+        .evaluate((label) => {
+        const panel = __wgById("wg-auto-panel");
+        if (!panel)
+            return;
+        __wgSet(panel, __wgEl("h3", null, "waygraph auto"), __wgEl("div", { style: "padding:12px 0;color:#c9a6ff" }, "Running: ", __wgEl("strong", null, label)));
+        if (typeof window.__wgWirePanelChrome === "function") {
+            window.__wgWirePanelChrome(panel, "wg-auto-panel-hidden", "waygraph auto");
+        }
+        if (typeof window.__wgStampModal === "function") {
+            window.__wgStampModal(panel, "auto-panel", {
+                phase: "running",
+                block: label,
+                ready: true,
+            });
+        }
+        else {
+            panel.setAttribute("data-wg-ui", "1");
+            panel.setAttribute("data-wg-modal", "auto-panel");
+            panel.setAttribute("data-wg-phase", "running");
+            panel.setAttribute("data-wg-ready", "1");
+        }
+    }, label)
+        .catch(ignorePageGone);
+}
+export const PANEL_CSS = "#wg-auto-panel{position:fixed;z-index:2147483647;left:50%;bottom:12px;transform:translateX(-50%);" +
+    "max-width:min(92vw,720px);max-height:calc(100vh - 24px);overflow-y:auto;box-sizing:border-box;" +
+    "background:rgba(20,10,40,.94);color:#fff;border-radius:14px;padding:16px 20px;" +
+    "font:14px/1.4 system-ui,sans-serif;box-shadow:0 12px 30px rgba(0,0,0,.35);}" +
+    "#wg-auto-panel h3{margin:0 0 10px;font-size:16px;}" +
+    "#wg-auto-panel .wg-here{color:#c9a6ff;margin-bottom:12px;}" +
+    "#wg-auto-panel .wg-actions{display:flex;flex-direction:column;gap:8px;}" +
+    "#wg-auto-panel button.wg-act{text-align:left;padding:10px 12px;border-radius:10px;border:1px solid #5b3aa8;" +
+    "background:#2a1450;color:#fff;font:13px/1.3 system-ui,sans-serif;cursor:pointer;}" +
+    "#wg-auto-panel button.wg-act:hover{background:#3a1d70;}" +
+    "#wg-auto-panel button.wg-act .wg-kind{color:#a78bfa;font-size:11px;text-transform:uppercase;}" +
+    "#wg-auto-panel button.wg-quit{margin-top:12px;background:#3a1a1a;border-color:#7f1d1d;}" +
+    "#wg-auto-panel textarea{width:100%;box-sizing:border-box;margin:6px 0 10px;background:#1a1030;color:#fff;" +
+    "border:1px solid #5b3aa8;border-radius:8px;padding:8px;font:12px/1.3 monospace;}" +
+    "#wg-auto-panel label.wg-mem{display:block;margin-top:8px;font-size:12px;color:#ddd;}" +
+    "#wg-auto-panel .wg-section{margin:12px 0 6px;font-size:11px;font-weight:700;color:#a78bfa;text-transform:uppercase;letter-spacing:.04em;}" +
+    "#wg-auto-panel .wg-map{margin:8px 0 12px;padding:8px 10px;border-radius:8px;background:rgba(0,0,0,.25);font-size:11px;line-height:1.5;}" +
+    "#wg-auto-panel .wg-map .wg-cp{opacity:.55;}#wg-auto-panel .wg-map .wg-cp-here{color:#fff;opacity:1;font-weight:700;}" +
+    "#wg-auto-panel .wg-chrome{display:flex;align-items:center;justify-content:space-between;gap:8px;margin:0 0 8px;}" +
+    "#wg-auto-panel .wg-chrome-title{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
+    "letter-spacing:.04em;text-transform:uppercase;}" +
+    "#wg-auto-panel button.wg-hide-btn{margin:0;padding:4px 10px;font:600 11px system-ui,sans-serif;" +
+    "background:#3a2a60;color:#e8dcff;border:1px solid #5b3aa8;border-radius:6px;cursor:pointer;}" +
+    "#wg-auto-panel button.wg-hide-btn:hover{background:#4b2a80;}" +
+    "#wg-auto-panel.wg-collapsed{width:auto;max-width:90vw;padding:8px 12px;max-height:none;overflow:hidden;}" +
+    "#wg-auto-panel.wg-collapsed .wg-body{display:none;}" +
+    "#wg-auto-panel.wg-collapsed .wg-chrome{margin:0;}" +
+    "@media (max-width:640px){" +
+    "#wg-auto-panel{left:8px;right:8px;bottom:8px;transform:none;max-width:none;width:auto;" +
+    "max-height:min(55vh,calc(100vh - 16px));padding:12px 14px;border-radius:12px;}" +
+    "#wg-auto-panel.wg-collapsed{left:50%;right:auto;transform:translateX(-50%);width:auto;}" +
+    "#wg-auto-panel button.wg-act{padding:12px;font-size:14px;}" +
+    "}";
+/**
+ * Mem keys any Block on the current menu might read this turn - minus keys a
+ * dynamic `instanceOptions` row already answers by picking it (e.g. "which
+ * item to add to cart" comes from the menu row itself, not a hand-typed JSON
+ * textarea).
+ */
+export function memKeysForMenu(menu, library) {
+    const instanceKeys = new Set();
+    for (const edge of menu.flat) {
+        if (edge.instanceOption)
+            instanceKeys.add(edge.instanceOption.key);
+    }
+    const keys = new Map();
+    for (const edge of menu.flat) {
+        const entry = library.get(edge.block);
+        for (const k of entry?.block.requires ?? []) {
+            if (instanceKeys.has(k))
+                continue;
+            keys.set(k.name, k);
+        }
+    }
+    return [...keys.values()];
+}
+export async function syncPanelMem(page, mem, keys) {
+    if (keys.length === 0)
+        return;
+    await ensureShadowRoot(page);
+    const edits = (await page.evaluate(() => {
+        const out = {};
+        __wgQA("textarea.wg-mem-input").forEach((ta) => {
+            const key = ta.getAttribute("data-mem-key");
+            if (key)
+                out[key] = ta.value;
+        });
+        return out;
+    }));
+    for (const k of keys) {
+        const raw = edits[k.name];
+        if (raw === undefined)
+            continue;
+        try {
+            mem.set(k, JSON.parse(raw));
+        }
+        catch (err) {
+            throw new Error(`Invalid JSON for mem key "${k.name}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+export function armPickWait() {
+    let resolve;
+    const promise = new Promise((res) => {
+        resolve = res;
+    });
+    return { promise, resolve };
+}
+export async function headfulPick(page, menu, library, mem, waitPick, 
+/** What the last Block run did, shown at the top of the menu. */
+note) {
+    const here = menu.here;
+    const hereLabel = here ?? (menu.flat.length > 0 ? "Unknown - pick Start here" : "Unknown - no moves available");
+    const menuMemKeys = memKeysForMenu(menu, library);
+    const memFields = menuMemKeys.map((k) => {
+        let value = "{}";
+        try {
+            if (mem.has(k))
+                value = JSON.stringify(mem.get(k), null, 2);
+            else {
+                const def = memStubValue(k);
+                if (def !== undefined)
+                    value = JSON.stringify(def, null, 2);
+            }
+        }
+        catch {
+            /* a value JSON can't encode shows as {} for the person to fill in */
+        }
+        return { name: k.name, value };
+    });
+    // Pre-resolve every candidate's hover-preview box THROUGH Playwright's own locator (>>
+    // piercing / :has-text() / :visible support), once, here on the Node side - not a raw selector
+    // string handed to the page for a per-mouseenter document.querySelector to fail silently on
+    // (same class of bug as rings.js's showRing; see its own comment for the full story). A
+    // mouseenter handler can't itself await a Node-side locator without visible hover lag, so the
+    // box is embedded as a data attribute instead and the in-page handler just reads it.
+    const hlSelectors = new Set();
+    for (const section of menu.sections) {
+        for (const c of section.edges) {
+            const entry = library.get(c.block);
+            const navClick = entry?.block?.__waygraphNavClick;
+            const hl = c.instanceOption?.highlight ?? (typeof navClick === "string" ? navClick : undefined);
+            if (hl)
+                hlSelectors.add(hl);
+        }
+    }
+    const hlBoxes = new Map();
+    await Promise.all([...hlSelectors].map(async (sel) => {
+        const loc = page.locator(sel).first();
+        const box = (await loc.count().catch(() => 0)) > 0
+            ? await loc
+                .evaluate((el) => {
+                const r = el.getBoundingClientRect();
+                if (r.width < 1 && r.height < 1)
+                    return null;
+                return { x: r.x, y: r.y, width: r.width, height: r.height };
+            })
+                .catch(() => null)
+            : null;
+        hlBoxes.set(sel, box);
+    }));
+    let idx = 0;
+    const sections = menu.sections.map((section) => ({
+        title: section.title,
+        buttons: section.edges.map((c) => {
+            const entry = library.get(c.block);
+            const navClick = entry?.block?.__waygraphNavClick;
+            const hl = c.instanceOption?.highlight ?? (typeof navClick === "string" ? navClick : undefined);
+            const hlBox = hl ? hlBoxes.get(hl) : null;
+            const base = { idx: idx++, hlBox: hlBox ? JSON.stringify(hlBox) : undefined };
+            if (c.label)
+                return { ...base, label: c.label };
+            return { ...base, kind: c.kind, block: c.block, to: c.to, ...(entry?.description ? { description: entry.description } : {}) };
+        }),
+    }));
+    await ensureShadowRoot(page);
+    await page.evaluate(({ css, note, hereLabel, memFields, sections }) => {
+        __wgCss(css, "wg-auto-style");
+        __wgById("wg-auto-panel")?.remove();
+        const root = __wgEl("div", { id: "wg-auto-panel" }, __wgEl("h3", null, "waygraph auto"), note ? __wgEl("div", { style: "margin-bottom:8px;font-size:12px;color:#a7f3d0" }, note) : null, __wgEl("div", { class: "wg-here" }, "You are here: ", __wgEl("strong", null, hereLabel)), memFields.length ? __wgEl("div", { class: "wg-section" }, "Mem - edit credentials, then click a block below") : null, memFields.map((f, i) => {
+            const field = __wgEl("textarea", { class: "wg-mem-input", id: "wg-mem-" + i, data: { memKey: f.name }, attrs: { rows: 4 } });
+            field.value = f.value;
+            return [__wgEl("label", { class: "wg-mem" }, f.name), field];
+        }), __wgEl("div", { class: "wg-actions" }, sections.length === 0 ? __wgEl("div", { style: "opacity:.85;padding:8px 0" }, "No moves from this screen right now.") : null, sections.map((section) => [
+            __wgEl("div", { class: "wg-section" }, section.title),
+            section.buttons.map((b) => __wgEl("button", { class: "wg-act", data: { idx: b.idx, hlBox: b.hlBox } }, b.label !== undefined
+                ? b.label
+                : [
+                    __wgEl("span", { class: "wg-kind" }, b.kind ?? ""),
+                    " ",
+                    __wgEl("strong", null, b.block ?? ""),
+                    " -> " + (b.to ?? ""),
+                    b.description ? [__wgEl("br"), __wgEl("span", { style: "opacity:.85" }, b.description)] : null,
+                ])),
+        ])), __wgEl("button", { class: "wg-act wg-quit", data: { quit: "1" } }, "Quit"));
+        __wgAdd(root);
+        // Chrome + Hide/Show, shared with setAutoPanelRunning.
+        window.__wgWirePanelChrome = (el, storageKey, chromeTitle) => {
+            if (!el)
+                return;
+            if (!el.querySelector(":scope > .wg-chrome")) {
+                const body = __wgEl("div", { class: "wg-body" }, Array.from(el.childNodes));
+                const chrome = __wgEl("div", { class: "wg-chrome" }, __wgEl("span", { class: "wg-chrome-title" }, chromeTitle || "waygraph auto"), __wgEl("button", { class: "wg-hide-btn", data: { wgToggle: "1" }, attrs: { type: "button" } }, "Hide"));
+                el.append(chrome, body);
+            }
+            const apply = (hidden) => {
+                el.classList.toggle("wg-collapsed", hidden);
+                el.setAttribute("data-wg-collapsed", hidden ? "1" : "0");
+                const t = el.querySelector("[data-wg-toggle]");
+                if (t)
+                    t.textContent = hidden ? "Show" : "Hide";
+                try {
+                    localStorage.setItem(storageKey, hidden ? "1" : "0");
+                }
+                catch {
+                    /* blocked storage: Hide still works for this page */
+                }
+            };
+            let hidden = false;
+            try {
+                hidden = localStorage.getItem(storageKey) === "1";
+            }
+            catch {
+                /* blocked storage: starts shown */
+            }
+            apply(hidden);
+            const toggle = el.querySelector("[data-wg-toggle]");
+            if (toggle && !toggle.dataset.wgWired) {
+                toggle.dataset.wgWired = "1";
+                toggle.addEventListener("click", (e) => {
+                    e.stopPropagation();
+                    apply(!el.classList.contains("wg-collapsed"));
+                });
+            }
+        };
+        window.__wgWirePanelChrome(root, "wg-auto-panel-hidden", "waygraph auto");
+        if (typeof window.__wgStampModal === "function") {
+            window.__wgStampModal(root, "auto-panel", { phase: "pick", ready: true });
+        }
+        else {
+            root.setAttribute("data-wg-ui", "1");
+            root.setAttribute("data-wg-modal", "auto-panel");
+            root.setAttribute("data-wg-phase", "pick");
+            root.setAttribute("data-wg-collapsed", root.classList.contains("wg-collapsed") ? "1" : "0");
+            root.setAttribute("data-wg-ready", "1");
+            window.__wgOverlayBeacon =
+                window.__wgOverlayBeacon ||
+                    (() => Array.from(__wgQA('[data-wg-ui="1"]')).map((el) => {
+                        const r = el.getBoundingClientRect();
+                        const st = getComputedStyle(el);
+                        return {
+                            id: el.id || null,
+                            modal: el.getAttribute("data-wg-modal"),
+                            ready: el.getAttribute("data-wg-ready") === "1",
+                            phase: el.getAttribute("data-wg-phase"),
+                            step: el.getAttribute("data-wg-step"),
+                            block: el.getAttribute("data-wg-block"),
+                            collapsed: el.getAttribute("data-wg-collapsed") === "1" || el.classList.contains("wg-collapsed"),
+                            opacity: st.opacity,
+                            textLen: (el.innerText || "").trim().length,
+                            w: Math.round(r.width),
+                            h: Math.round(r.height),
+                            visible: r.width > 0 && r.height > 0 && Number(st.opacity) > 0.05,
+                        };
+                    }));
+        }
+        root.querySelectorAll("button[data-idx]").forEach((btn) => {
+            btn.addEventListener("click", () => window.__wgAutoPick?.(Number(btn.dataset.idx)));
+            btn.addEventListener("mouseenter", () => {
+                // Pre-resolved on the Node side via Playwright's own locator (>> piercing / :has-text()
+                // support) when this menu was built - see headfulPick's own comment for why a
+                // mouseenter handler can't itself round-trip to a Node-side locator per hover.
+                const raw = btn.dataset.hlBox;
+                if (!raw || typeof window.__wgPositionRing !== "function")
+                    return;
+                window.__wgPositionRing(JSON.parse(raw), btn.textContent?.trim()?.slice(0, 80) || "target", "auto");
+            });
+            btn.addEventListener("mouseleave", () => window.__wgHideRing?.());
+        });
+        root.querySelector("[data-quit]")?.addEventListener("click", () => window.__wgAutoQuit?.());
+    }, { css: PANEL_CSS, note, hereLabel, memFields, sections });
+    return waitPick();
+}
+export function printCliMenu(menu, library) {
+    console.log("");
+    console.log(`You are here: ${menu.here ?? "Unknown (pick Start here)"}`);
+    console.log("");
+    if (menu.flat.length === 0) {
+        console.log("  (no moves available on this page)");
+    }
+    let n = 0;
+    for (const section of menu.sections) {
+        console.log(`  -- ${section.title} --`);
+        for (const c of section.edges) {
+            const entry = library.get(c.block);
+            n++;
+            if (c.label) {
+                console.log(`  [${n}] ${c.label}`);
+            }
+            else {
+                const desc = entry?.description ? ` - ${entry.description}` : "";
+                console.log(`  [${n}] ${c.block} (${c.kind}) -> ${c.to}${desc}`);
+            }
+        }
+    }
+    console.log("  [q] quit");
+    console.log("");
+}
+export async function cliPick(menu, rl) {
+    while (true) {
+        let ans;
+        try {
+            ans = (await rl.question("Choose: ")).trim().toLowerCase();
+        }
+        catch {
+            return { type: "quit" }; // stdin ended (piped / Ctrl-D) - same as q
+        }
+        if (ans === "q" || ans === "quit")
+            return { type: "quit" };
+        const n = Number(ans);
+        if (Number.isInteger(n) && n >= 1 && n <= menu.flat.length) {
+            return { type: "pick", index: n - 1 };
+        }
+        console.log("Enter a number from the list, or q to quit.");
+    }
+}

package/dist/live/auto-session/auto-session.d.ts

@@ -1,12 +1,8 @@
-import type { ApplyPathResult, ApplyPickResult, AutoSessionInit, ConsoleLogEntry, InspectDomOptions, InspectDomResult, SessionSnapshot, StorageSnapshot, StubFileKind, TraceStep } from "./helpers.js";
 import type { PilotHighlightFixtures } from "../../demo/overlay/pilot/fixtures.js";
+import type { ApplyPathResult, ApplyPickResult, AutoSessionInit, ConsoleLogEntry, InspectDomOptions, InspectDomResult, SessionSnapshot, StorageSnapshot, StubFileKind, TraceStep } from "./helpers.js";
 /**
- * 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.
+ * A live session driven over IPC (`browser start`, `pilot start`): the same graph, library, mem and browser as
+ * `waygraph auto`, moved one call at a time (`applyPick`, `applyPath`, the raw actions) instead of a menu loop.
  */
 export declare class AutoSession {
     private readonly projectDir;
@@ -55,87 +51,42 @@ export declare class AutoSession {
      * element's subtree; it is a modifier, not a third mode.
      */
     inspectDom(opts: InspectDomOptions): Promise<InspectDomResult>;
-    /**
-     * 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.
-     */
+    /** Reads the live page's client state: storage, cookies, service workers (where web-push state lives). */
     inspectStorage(): Promise<StorageSnapshot>;
-    /**
-     * 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.
-     */
     /** Paint + log a Block's authored waygraph overlay fixtures (same as demo does), best-effort. */
     private paintStubPhase;
+    /**
+     * Runs one Block for real: the core of `applyPick` (picked from the live menu) and `applyPath` (named by the route).
+     * `expectedTo` is used when the Block's resolve doesn't set `__state`.
+     */
     private runNamedBlock;
     /** Applies exactly one pick: runs at most one Block, returns the resulting state. */
     applyPick(raw: string): Promise<ApplyPickResult>;
     /**
-     * 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.
+     * Re-reads the project's Blocks and graph from disk (the same call `start()` makes) and swaps them in, keeping the
+     * page, mem, browser and `here`: a Block written mid-session becomes pickable without a restart.
      */
     reloadLibrary(): Promise<void>;
     /**
-     * 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.
+     * Re-detects `here` from the live page, whatever is cached. `here` only changes when this session acts; a person
+     * clicking in a visible session moves the page without it, and later `send` / `reach` calls would use a stale menu.
      */
     resync(): Promise<ApplyPickResult>;
     /**
-     * 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.
+     * Raw actions for a page no Block covers yet (Blind Pilot). The Checkpoint they land on isn't known ahead, so each
+     * one forgets `here` and the next menu re-detects it. A selector that matches nothing is a reported failure.
      */
     rawClick(selector: string): Promise<ApplyPickResult>;
     rawType(selector: string, text: string): Promise<ApplyPickResult>;
-    /**
-     * 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.
-     */
+    /** Presses a key on an element (`Enter`, `Escape`, ...): inline-edit inputs often commit on Enter, with no Save button. */
     rawPress(selector: string, key: string): Promise<ApplyPickResult>;
     rawGoto(url: string): Promise<ApplyPickResult>;
-    /**
-     * 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.
-     */
+    /** Fills an `<input type="file">` with a built-in stub file ("image", "pdf", "video") or a `filePath` of your own. */
     rawUpload(selector: string, stub: StubFileKind | {
         filePath: string;
     }): Promise<ApplyPickResult>;
+    /** One raw primitive (no Block): announce it, run it, then forget `here` so the next menu re-detects it. */
+    private rawStep;
     /**
      * Agent-sent highlight fixtures (rings + optional todos) on the live page -
      * the Pilot equivalent of Block `stubBefore` narration in `waygraph demo`.
@@ -151,42 +102,11 @@ export declare class AutoSession {
         error: string;
     }>;
     /**
-     * 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.
+     * Runs a whole route to `targetCheckpoint` in one call, instead of one `applyPick` per step. The path is computed
+     * once with `findBlockPathDetailed` (the BFS `auto --blocks <From> <To>` uses) and each hop's Block runs directly on
+     * the session's live page and mem, trusting the graph rather than live-menu visibility. Per-step choosing was tried
+     * and fails: a `from: "*"` edge looks reachable from anywhere to a static BFS. A step whose precondition isn't met
+     * fails loud, naming it; so does a step that runs but lands somewhere other than its edge promised.
      */
     applyPath(targetCheckpoint: string): Promise<ApplyPathResult>;
     close(): Promise<void>;