waygraph 0.15.54 → 0.16.0

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

@@ -1,48 +1,21 @@
-import { getMemStub } from "../mem-stub.js";
+import { getMemStub } from "../../engine/mem/mem-stub.js";
 import { createInterface } from "node:readline/promises";
-import { ensureShadowRoot } from "../ui/shadow.js";
+import { ensureShadowRoot } from "../../demo/overlay/ui/shadow.js";
 import { stdin as input, stdout as output } from "node:process";
-import { Engine, start, end, locate } from "../core.js";
-import { MemPage } from "../mem-page.js";
-import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
-import { installDemoChrome, instrumentInteractionHighlighting } from "./step-overlay.js";
-import { configuredExtensions, resolveBaseUrl } from "../config.js";
-import { withWebServer } from "../webserver.js";
-import { chromiumExecutablePath, launchContext } from "../browser.js";
-/** See `../config.js`'s own `resolveBaseUrl` - re-exported so existing importers of this module
- * don't need to change their import path. */
-export { resolveBaseUrl };
-/** URL-first - several Checkpoints share nav verify traits (e.g. LoggedIn = /inventory.html). */
-async function inferCheckpointFromUrl(page) {
-    try {
-        const path = new URL(page.url()).pathname;
-        if (path.includes("inventory-item.html"))
-            return "ItemDetailPage";
-        if (path.includes("inventory.html"))
-            return "LoggedIn";
-        if (path.includes("cart.html"))
-            return "CartPage";
-        if (path.includes("checkout-step-one.html"))
-            return "CheckoutInfoPage";
-        if (path.includes("checkout-step-two.html"))
-            return "CheckoutOverviewPage";
-        if (path.includes("checkout-complete.html"))
-            return "OrderComplete";
-        if (path === "/" || path === "") {
-            if (await page.locator("#login-button").isVisible({ timeout: 500 }).catch(() => false)) {
-                return "LoginPage";
-            }
-        }
-    }
-    catch {
-        /* ignore */
-    }
-    return null;
-}
+import { Engine } from "../../engine/engine.js";
+import { buildFlow } from "../../engine/flow/flow.js";
+import { locate } from "../../engine/locate.js";
+import { MemPage } from "../../engine/mem/mem.js";
+import { buildExploreContext, buildExploreMenu, } from "./explore.js";
+import { installDemoChrome, instrumentAutoInteractions } from "../../demo/overlay/auto-chrome.js";
+import { keepOverlayOnNavigation } from "../../demo/overlay/reattach.js";
+import { configuredExtensions, resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { withWebServer } from "../../runtime/webserver.js";
+import { chromiumExecutablePath, launchContext } from "../../runtime/browser.js";
+import { envString } from "../../engine/env.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
+/** Which Checkpoint the page is on, asked of the project's own Nav / Page Blocks (their verify). */
 export async function detectHere(page, navBlocks) {
-    const fromUrl = await inferCheckpointFromUrl(page);
-    if (fromUrl)
-        return fromUrl;
     const tags = navBlocks.map((n) => n.block);
     return locate(page, tags, { timeoutMs: 1500 });
 }
@@ -51,8 +24,8 @@ export async function ensureLivePage(context, page, startUrl) {
         return page;
     const fresh = await context.newPage();
     if (startUrl) {
-        await fresh.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
-        await fresh.waitForLoadState("load").catch(() => { });
+        await fresh.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+        await fresh.waitForLoadState("load").catch(ignoreTimeout);
     }
     return fresh;
 }
@@ -60,28 +33,16 @@ function missingMemKeys(entry, mem) {
     const requires = entry.block.requires ?? [];
     return requires.filter((k) => !mem.has(k));
 }
-const DEFAULT_CREDENTIALS = { username: "standard_user", password: "secret_sauce" };
-/**
- * Saucedemo-only defaults. Exact key names only — never substring `"login"`.
- * A consumer's own `key<string>("login-email")` must stay unset here, or it
- * silently gets a saucedemo credentials object instead of its own default.
- */
-export function defaultMemValueForKey(keyName) {
-    if (keyName === "login-credentials" ||
-        keyName === "credentials" ||
-        keyName === "saucedemo.credentials") {
-        return DEFAULT_CREDENTIALS;
-    }
-    return undefined;
+/** The project's own default for a key: its `registerMemStub` fake (live sessions load every `*.mem-stubs.ts`). */
+export function memStubValue(key) {
+    return getMemStub(key)?.();
 }
-function defaultMemJsonPrompt(keyName) {
-    const def = defaultMemValueForKey(keyName);
-    if (def !== undefined)
-        return JSON.stringify(def);
-    return "{}";
+function defaultMemJsonPrompt(key) {
+    const def = memStubValue(key);
+    return def === undefined ? "{}" : JSON.stringify(def);
 }
 function seedMemFromEnv(mem, entry) {
-    const raw = process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
+    const raw = envString("WAYGRAPH_DATA") ?? envString("WAYGRAPH_AUTO_MEM");
     if (!raw)
         return false;
     try {
@@ -96,16 +57,16 @@ function seedMemFromEnv(mem, entry) {
         return false;
     }
 }
-/** Pre-seed known demo keys (saucedemo creds) so headful/cli do not stop for mem forms. */
+/** Pre-seeds required keys from WAYGRAPH_DATA and the project's mem stubs, so a session does not stop for mem forms. */
 export function seedDefaultMem(library, mem) {
-    const raw = process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
+    const raw = envString("WAYGRAPH_DATA") ?? envString("WAYGRAPH_AUTO_MEM");
     let envParsed = {};
     if (raw) {
         try {
             envParsed = JSON.parse(raw);
         }
-        catch {
-            /* ignore */
+        catch (err) {
+            throw new Error(`waygraph: --data / WAYGRAPH_DATA is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     for (const entry of library.values()) {
@@ -116,12 +77,7 @@ export function seedDefaultMem(library, mem) {
                 mem.set(k, envParsed[k.name]);
                 continue;
             }
-            const stub = getMemStub(k);
-            if (stub) {
-                mem.set(k, stub());
-                continue;
-            }
-            const def = defaultMemValueForKey(k.name);
+            const def = memStubValue(k);
             if (def !== undefined)
                 mem.set(k, def);
         }
@@ -131,7 +87,7 @@ async function promptMemCli(entry, mem) {
     const rl = createInterface({ input, output });
     try {
         for (const k of missingMemKeys(entry, mem)) {
-            const def = defaultMemJsonPrompt(k.name);
+            const def = defaultMemJsonPrompt(k);
             const line = await rl.question(`  ${k.name} JSON [${def}]: `);
             const json = line.trim() || def;
             mem.set(k, JSON.parse(json));
@@ -159,11 +115,7 @@ async function setAutoPanelRunning(page, label) {
         const panel = __wgById("wg-auto-panel");
         if (!panel)
             return;
-        const body = "<h3>waygraph auto</h3><div style='padding:12px 0;color:#c9a6ff'>" +
-            "Running: <strong>" +
-            label +
-            "</strong></div>";
-        panel.innerHTML = body;
+        __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");
         }
@@ -181,7 +133,7 @@ async function setAutoPanelRunning(page, label) {
             panel.setAttribute("data-wg-ready", "1");
         }
     }, label)
-        .catch(() => { });
+        .catch(ignorePageGone);
 }
 export async function runOneBlock(engine, entry, context, page, mem, headful) {
     const navClick = entry.block.__waygraphNavClick;
@@ -190,11 +142,11 @@ export async function runOneBlock(engine, entry, context, page, mem, headful) {
             .evaluate((label) => {
             window.__wgPendingNavClickLabel = label;
         }, `nav: ${entry.block.name}`)
-            .catch(() => { });
+            .catch(ignorePageGone);
     }
     if (headful)
         await setAutoPanelRunning(page, entry.block.name);
-    const flow = engine.defineFlow([start, entry.block, end]);
+    const flow = buildFlow([entry.block], engine.config);
     const BLOCK_TIMEOUT_MS = 45_000;
     let timer;
     let result;
@@ -212,7 +164,7 @@ export async function runOneBlock(engine, entry, context, page, mem, headful) {
         if (timer)
             clearTimeout(timer);
     }
-    await page.evaluate("delete window.__wgPendingNavClickLabel").catch(() => { });
+    await page.evaluate("delete window.__wgPendingNavClickLabel").catch(ignorePageGone);
     return result;
 }
 const PANEL_CSS = "#wg-auto-panel{position:fixed;z-index:2147483647;left:50%;bottom:12px;transform:translateX(-50%);" +
@@ -248,9 +200,6 @@ const PANEL_CSS = "#wg-auto-panel{position:fixed;z-index:2147483647;left:50%;bot
     "#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;}" +
     "}";
-function esc(s) {
-    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
-}
 /** Shown in the headful panel after each Block run. */
 let lastRunNote = null;
 /**
@@ -312,36 +261,22 @@ async function headfulPick(page, menu, library, mem, waitPick) {
     const here = menu.here;
     const hereLabel = here ?? (menu.flat.length > 0 ? "Unknown - pick Start here" : "Unknown - no moves available");
     const menuMemKeys = memKeysForMenu(menu, library);
-    let html = `<style id="wg-auto-style">${PANEL_CSS}</style><div id="wg-auto-panel">` +
-        `<h3>waygraph auto</h3>`;
-    if (lastRunNote) {
-        html += `<div style="margin-bottom:8px;font-size:12px;color:#a7f3d0">${esc(lastRunNote)}</div>`;
-    }
-    html += `<div class="wg-here">You are here: <strong>${esc(hereLabel)}</strong></div>`;
-    if (menuMemKeys.length > 0) {
-        html +=
-            `<div class="wg-section">Mem - edit credentials, then click a block below</div>`;
-        let memIdx = 0;
-        for (const k of menuMemKeys) {
-            let value = "{}";
-            try {
-                if (mem.has(k))
-                    value = JSON.stringify(mem.get(k), null, 2);
-                else {
-                    const def = defaultMemValueForKey(k.name);
-                    if (def !== undefined)
-                        value = JSON.stringify(def, null, 2);
-                }
-            }
-            catch {
-                /* ignore */
+    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);
             }
-            html +=
-                `<label class="wg-mem">${esc(k.name)}</label>` +
-                    `<textarea class="wg-mem-input" data-mem-key="${esc(k.name)}" id="wg-mem-${memIdx}" rows="4">${esc(value)}</textarea>`;
-            memIdx++;
         }
-    }
+        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
@@ -373,152 +308,126 @@ async function headfulPick(page, menu, library, mem, waitPick) {
             : null;
         hlBoxes.set(sel, box);
     }));
-    html += `<div class="wg-actions">`;
     let idx = 0;
-    if (menu.sections.length === 0) {
-        html += `<div style="opacity:.85;padding:8px 0">No moves from this screen right now.</div>`;
-    }
-    for (const section of menu.sections) {
-        html += `<div class="wg-section">${esc(section.title)}</div>`;
-        for (const c of section.edges) {
+    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 hlAttr = hlBox ? ` data-hl-box='${esc(JSON.stringify(hlBox))}'` : "";
-            if (c.label) {
-                html += `<button class="wg-act" data-idx="${idx}"${hlAttr}>${esc(c.label)}</button>`;
+            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);
             }
-            else {
-                const desc = entry?.description ? `<br><span style="opacity:.85">${esc(entry.description)}</span>` : "";
-                html +=
-                    `<button class="wg-act" data-idx="${idx}"${hlAttr}><span class="wg-kind">${esc(c.kind)}</span> ` +
-                        `<strong>${esc(c.block)}</strong> -> ${esc(c.to)}${desc}</button>`;
+            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"));
+                });
             }
-            idx++;
-        }
-    }
-    html += `</div><button class="wg-act wg-quit" data-quit="1">Quit</button></div>`;
-    // Wrap body; chrome + Hide/Show wired in page (shared with stepper).
-    html =
-        `<style id="wg-auto-style">${PANEL_CSS}</style><div id="wg-auto-panel">` +
-            html.slice(html.indexOf("<h3>"));
-    await ensureShadowRoot(page);
-    await page.evaluate(`((inner) => {
-      let panel = __wgById("wg-auto-panel");
-      if (!panel) {
-        panel = document.createElement("div");
-        __wgAdd(panel);
-      }
-      panel.outerHTML = inner;
-      const root = __wgById("wg-auto-panel");
-      if (!root) return;
-      window.__wgWirePanelChrome = (el, storageKey, chromeTitle) => {
-        if (!el) return;
-        if (!el.querySelector(":scope > .wg-chrome")) {
-          const body = document.createElement("div");
-          body.className = "wg-body";
-          while (el.firstChild) body.appendChild(el.firstChild);
-          const chrome = document.createElement("div");
-          chrome.className = "wg-chrome";
-          const titleEl = document.createElement("span");
-          titleEl.className = "wg-chrome-title";
-          titleEl.textContent = chromeTitle || "waygraph auto";
-          const btn = document.createElement("button");
-          btn.type = "button";
-          btn.className = "wg-hide-btn";
-          btn.setAttribute("data-wg-toggle", "1");
-          btn.textContent = "Hide";
-          chrome.appendChild(titleEl);
-          chrome.appendChild(btn);
-          el.appendChild(chrome);
-          el.appendChild(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 {}
         };
-        let hidden = false;
-        try { hidden = localStorage.getItem(storageKey) === "1"; } catch {}
-        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 });
         }
-      };
-      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", () => {
-          const idx = Number(btn.getAttribute("data-idx"));
-          window.__wgAutoPick?.(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.getAttribute("data-hl-box");
-          if (!raw || typeof window.__wgPositionRing !== "function") return;
-          let box;
-          try {
-            box = JSON.parse(raw);
-          } catch {
-            return;
-          }
-          window.__wgPositionRing(
-            box,
-            btn.textContent?.trim()?.slice(0, 80) || "target",
-            "auto",
-          );
-        });
-        btn.addEventListener("mouseleave", () => {
-          window.__wgHideRing?.();
+        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?.());
         });
-      });
-      const quit = root.querySelector("[data-quit]");
-      if (quit) quit.addEventListener("click", () => window.__wgAutoQuit?.());
-    })(${JSON.stringify(html)})`);
+        root.querySelector("[data-quit]")?.addEventListener("click", () => window.__wgAutoQuit?.());
+    }, { css: PANEL_CSS, note: lastRunNote, hereLabel, memFields, sections });
     return waitPick();
 }
 function printCliMenu(menu, library) {
@@ -573,7 +482,7 @@ export async function runAutoExplore(projectDir, options = {}) {
 async function runAutoExploreCore(projectDir, options = {}) {
     lastRunNote = null;
     const cli = options.cli === true;
-    const baseURL = options.baseURL ?? (await resolveBaseUrl(projectDir)) ?? process.env.WAYGRAPH_BASE_URL;
+    const baseURL = options.baseURL ?? (await resolveBaseUrl(projectDir)) ?? envString("WAYGRAPH_BASE_URL");
     const startUrl = options.startUrl ?? baseURL;
     const { graph, library } = await buildExploreContext(projectDir, options.blocksSelect ? { blocksSelect: options.blocksSelect } : undefined);
     if (options.blocksSelect) {
@@ -606,8 +515,8 @@ async function runAutoExploreCore(projectDir, options = {}) {
     });
     let page = await context.newPage();
     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);
     }
     console.error(`waygraph auto: ${graph.nodes.length} checkpoint(s), ${graph.edges.length} edge(s) - ` +
         (cli ? "CLI picker (terminal menu)" : "headful picker (browser panel)"));
@@ -624,7 +533,8 @@ async function runAutoExploreCore(projectDir, options = {}) {
         });
         if (!cli) {
             await installDemoChrome(target, "", { banner: false });
-            instrumentInteractionHighlighting(target, mem, 250);
+            keepOverlayOnNavigation(target, () => installDemoChrome(target, "", { banner: false }));
+            instrumentAutoInteractions(target, mem, 250);
         }
         wiredPage = target;
     }

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

@@ -1,18 +1,12 @@
 import type { Page } from "@playwright/test";
-import type { Block, Checkpoint, WaygraphInstanceOption } from "../types.js";
-import { type WaygraphGraph, type WaygraphEdge } from "../analysis/graph.js";
+import type { WaygraphInstanceOption } from "../../engine/block/block.js";
+import { type WaygraphGraph, type WaygraphEdge } from "../../analysis/graph.js";
 export interface ExploreContextOpts {
-    blocksSelect?: import("../blocks-select.js").BlocksSelect;
+    blocksSelect?: import("../../manifest/select.js").BlocksSelect;
     /** Absolute paths of extra Block trees to merge (host projectDir is always first). */
     inject?: string[];
 }
-export interface BlockEntry {
-    block: Block<Checkpoint<string>, Checkpoint<string>>;
-    exportName: string;
-    file: string;
-    kind: "nav" | "action";
-    description: string;
-}
+import type { BlockEntry } from "../../manifest/project.js";
 /**
  * One menu row. Usually just a `WaygraphEdge` as discovered statically; when
  * a Block declares `instanceOptions`, one `ExploreEdge` is produced per live
@@ -41,10 +35,6 @@ export declare function loadBlockLibrary(projectDir: string, opts?: ExploreConte
     byName: Map<string, BlockEntry>;
     navBlocks: BlockEntry[];
 }>;
-/**
- * @deprecated Use {@link buildExploreMenu} — kept for unit tests.
- */
-export declare function exploreChoices(graph: WaygraphGraph, here: string | null): WaygraphEdge[];
 /**
  * Runtime-filtered menu: only Blocks that can run on the live page, grouped forward/back.
  */