waygraph 0.15.54 → 0.16.1

package/dist/index.js

@@ -1,20 +1,47 @@
-export { connect, checkpoint } from "./types.js";
-export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
-export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
-export { css, byText, byRole } from "./selector.js";
-export { WaygraphError, WAYGRAPH_ERRORS } from "./errors.js";
-export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, defineApiBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, withDialog, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./core.js";
-export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
+// The runtime layer supplies how an Engine launches its own browser (config, Chromium path, extensions).
+import "./runtime/full-launch.js";
+// Run events are written to the project's run log (.waygraph/runs) when the CLI turns it on.
+import "./runtime/run-log.js";
+export { connect } from "./engine/run/connect.js";
+export { checkpoint } from "./engine/checkpoint/checkpoint.js";
+export { MemKey, MemPage, key, keyGroup } from "./engine/mem/mem.js";
+export { registerMemStub, seedMemStub, getMemStub } from "./engine/mem/mem-stub.js";
+export { css, byText, byRole } from "./engine/trait/selector.js";
+export { WaygraphError, WAYGRAPH_ERRORS } from "./engine/errors.js";
+export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText } from "./engine/trait/trait.js";
+export { runGraph, spawnTab, narrate, preflight, defineLayout } from "./engine/run/run.js";
+export { Engine, map } from "./engine/engine.js";
+export { branch } from "./engine/block/branch.js";
+export { withVerify, modVerify, modVerifyAll, defineBlock } from "./engine/block/block.js";
+export { withDialog } from "./engine/block/dialog.js";
+export { defineNavBlock, defineNavClickBlock, defineMemNavBlock } from "./engine/block/kinds/nav.js";
+export { defineMethodBlock, defineAssertBlock } from "./engine/block/kinds/method.js";
+export { definePageBlock } from "./engine/block/kinds/page.js";
+export { defineEffectBlock } from "./engine/block/kinds/effect.js";
+export { defineApiBlock } from "./engine/block/kinds/api.js";
+export { locate } from "./engine/locate.js";
+export { composeBlock, fastForwardComposeBlock, isFastForwardBlock } from "./engine/block/compose.js";
+export { MapBuilder } from "./engine/flow/map-builder.js";
+export { branchRoutes, collectBranchFlows, runBranchRegression } from "./engine/flow/branch-regression.js";
+export { resolveHighlightSlots, resolveSlides, runStubPhase, hasAuthoredStubAfter, hasAuthoredStubOnError } from "./demo/narration/narration.js";
+export { resolveFixtureDwellMs, normalizeDemoPace, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT } from "./demo/narration/demo-pace.js";
+export { formatHighlightCaption, applyHighlightStyleDefaults, toneIconPrefix } from "./demo/narration/style.js";
+export { normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight } from "./engine/stub/ring.js";
+export { normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, resolveTodoDockUi } from "./demo/narration/todo-dock.js";
+export { applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS } from "./demo/narration/device.js";
+export { WAYGRAPH_RING_CSS } from "./demo/narration/css.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./analysis/graph.js";
-export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
-export { EdgeLeaseCoordinator } from "./traverse/lease.js";
-export { runTraverse } from "./traverse/run.js";
-export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport, } from "./traverse/coverage.js";
-export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady, } from "./session/overlay-beacon.js";
-export { AutoSession, stubFilePath } from "./auto-session.js";
-export { pilotStart } from "./session/pilot.js";
-export { defineConfig, resolveBaseUrl } from "./config.js";
-export { withWebServer } from "./webserver.js";
-export { chromiumExecutablePath } from "./browser.js";
-export { resolveExtension, KNOWN_EXTENSIONS } from "./extensions.js";
+export { buildManifest } from "./manifest/manifest.js";
+export { onRunEvent } from "./engine/run/events.js";
+export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp } from "./manifest/select.js";
+export { EdgeLeaseCoordinator } from "./live/traverse/lease.js";
+export { runTraverse } from "./live/traverse/traverse.js";
+export { buildCoverageReport, collectGraphEdgeKeys, defaultCoverageOutPath, formatCoverageLine, normalizeHitKey, parseMinEdgeCoverage, writeCoverageReport } from "./live/traverse/coverage.js";
+export { WG_UI_SEL, WG_READY_PANEL_SEL, WG_READY_AUTO_SEL, WG_READY_BANNER_SEL, readWgOverlayBeacon, readWgOverlayBeaconInPage, assertWgOverlayReady } from "./demo/overlay/beacon.js";
+export { AutoSession } from "./live/auto-session/auto-session.js";
+export { stubFilePath } from "./live/auto-session/helpers.js";
+export { pilotStart } from "./live/pilot/pilot.js";
+export { defineConfig, resolveBaseUrl } from "./runtime/waygraph-config.js";
+export { withWebServer } from "./runtime/webserver.js";
+export { chromiumExecutablePath } from "./runtime/browser.js";
+export { resolveExtension, KNOWN_EXTENSIONS } from "./runtime/extensions.js";

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

@@ -0,0 +1,22 @@
+import type { BrowserContext, Page } from "@playwright/test";
+import type { Checkpoint } from "../../engine/checkpoint/checkpoint.js";
+import { Engine } from "../../engine/engine.js";
+import { MemPage } from "../../engine/mem/mem.js";
+import type { BlockEntry } from "../../manifest/project.js";
+export interface AutoExploreOptions {
+    /** Terminal menu (browser still runs for act()). Default false = headful picker panel. */
+    cli?: boolean;
+    baseURL?: string;
+    /** Initial URL when the page is blank (defaults to baseURL). */
+    startUrl?: string;
+    /** Phase C: glob / regex / bare `--blocks` file select for discovery. */
+    blocksSelect?: import("../../manifest/select.js").BlocksSelect;
+}
+/** Which Checkpoint the page is on, asked of the project's own Nav / Page Blocks (their verify). */
+export declare function detectHere(page: Page, navBlocks: BlockEntry[]): Promise<string | null>;
+export declare function ensureLivePage(context: BrowserContext, page: Page, startUrl: string | undefined): Promise<Page>;
+export declare function runOneBlock(engine: Engine, entry: BlockEntry, context: BrowserContext, page: Page, mem: MemPage, headful: boolean): Promise<Checkpoint<string>>;
+/**
+ * Interactive waygraph auto: locate current Checkpoint, list runnable Blocks, pick one, repeat.
+ */
+export declare function runAutoExplore(projectDir: string, options?: AutoExploreOptions): Promise<void>;

package/dist/live/auto/auto.js

@@ -0,0 +1,207 @@
+import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { installDemoChrome, instrumentAutoInteractions } from "../../demo/overlay/auto-chrome.js";
+import { keepOverlayOnNavigation } from "../../demo/overlay/reattach.js";
+import { Engine } from "../../engine/engine.js";
+import { envString } from "../../engine/env.js";
+import { buildFlow } from "../../engine/flow/flow.js";
+import { locate } from "../../engine/locate.js";
+import { MemPage } from "../../engine/mem/mem.js";
+import { ignorePageGone, ignoreTimeout } from "../../engine/page-gone.js";
+import { chromiumExecutablePath, launchContext } from "../../runtime/browser.js";
+import { configuredExtensions, resolveBaseUrl } from "../../runtime/waygraph-config.js";
+import { withWebServer } from "../../runtime/webserver.js";
+import { buildExploreContext, buildExploreMenu, } from "./explore.js";
+import { ensureMem, seedDefaultMem } from "./mem.js";
+import { armPickWait, cliPick, headfulPick, printCliMenu, setAutoPanelRunning, syncPanelMem } from "./menu.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 tags = navBlocks.map((n) => n.block);
+    return locate(page, tags, { timeoutMs: 1500 });
+}
+export async function ensureLivePage(context, page, startUrl) {
+    if (!page.isClosed())
+        return page;
+    const fresh = await context.newPage();
+    if (startUrl) {
+        await fresh.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(ignorePageGone);
+        await fresh.waitForLoadState("load").catch(ignoreTimeout);
+    }
+    return fresh;
+}
+export async function runOneBlock(engine, entry, context, page, mem, headful) {
+    const navClick = entry.block.__waygraphNavClick;
+    if (entry.kind === "nav" && navClick !== undefined) {
+        await page
+            .evaluate((label) => {
+            window.__wgPendingNavClickLabel = label;
+        }, `nav: ${entry.block.name}`)
+            .catch(ignorePageGone);
+    }
+    if (headful)
+        await setAutoPanelRunning(page, entry.block.name);
+    const flow = buildFlow([entry.block], engine.config);
+    const BLOCK_TIMEOUT_MS = 45_000;
+    let timer;
+    let result;
+    try {
+        const ran = await Promise.race([
+            flow.run(context, mem, { page, closeOnFinish: false }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Block "${entry.block.name}" timed out after ${BLOCK_TIMEOUT_MS / 1000}s - ` +
+                    "click Quit and retry, or check network / mem credentials")), BLOCK_TIMEOUT_MS);
+            }),
+        ]);
+        result = ran.result;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+    await page.evaluate("delete window.__wgPendingNavClickLabel").catch(ignorePageGone);
+    return result;
+}
+/** Shown in the headful panel after each Block run. */
+let lastRunNote = null;
+/**
+ * Interactive waygraph auto: locate current Checkpoint, list runnable Blocks, pick one, repeat.
+ */
+export async function runAutoExplore(projectDir, options = {}) {
+    await withWebServer(projectDir, () => runAutoExploreCore(projectDir, options));
+}
+async function runAutoExploreCore(projectDir, options = {}) {
+    lastRunNote = null;
+    const cli = options.cli === true;
+    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) {
+        console.error(`waygraph auto: --blocks ${options.blocksSelect.raw} → ` +
+            `${library.byName.size} block(s), ${graph.edges.length} edge(s)`);
+    }
+    const mem = new MemPage();
+    seedDefaultMem(library.byName, mem);
+    const engine = cli ? new Engine({ headless: true }) : new Engine({ headless: false, slowMo: 250 });
+    const { chromium } = await import("@playwright/test");
+    const executablePath = chromiumExecutablePath();
+    const launchOpts = {
+        headless: cli,
+        args: cli ? [] : ["--start-maximized"],
+    };
+    if (!cli)
+        launchOpts.slowMo = 250;
+    if (executablePath)
+        launchOpts.executablePath = executablePath;
+    const contextOpts = cli
+        ? { viewport: { width: 1280, height: 720 } }
+        : { viewport: null };
+    if (baseURL)
+        contextOpts.baseURL = baseURL;
+    const { close: closeBrowser, context } = await launchContext({
+        launcher: chromium,
+        launch: launchOpts,
+        context: contextOpts,
+        extensions: await configuredExtensions(projectDir),
+    });
+    let page = await context.newPage();
+    if (startUrl) {
+        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)"));
+    const pickSlot = { resolve: null };
+    let wiredPage = null;
+    async function wirePage(target) {
+        if (wiredPage === target)
+            return;
+        await target.exposeFunction("__wgAutoPick", (index) => {
+            pickSlot.resolve?.({ type: "pick", index });
+        });
+        await target.exposeFunction("__wgAutoQuit", () => {
+            pickSlot.resolve?.({ type: "quit" });
+        });
+        if (!cli) {
+            await installDemoChrome(target, "", { banner: false });
+            keepOverlayOnNavigation(target, () => installDemoChrome(target, "", { banner: false }));
+            instrumentAutoInteractions(target, mem, 250);
+        }
+        wiredPage = target;
+    }
+    let here = null;
+    const cliRl = cli ? createInterface({ input, output }) : null;
+    try {
+        for (;;) {
+            page = await ensureLivePage(context, page, startUrl);
+            await wirePage(page);
+            const pickWait = armPickWait();
+            pickSlot.resolve = pickWait.resolve;
+            if (here === null) {
+                here = await detectHere(page, library.navBlocks);
+            }
+            if (cli)
+                console.error("waygraph auto: scanning page for moves ...");
+            const menu = await buildExploreMenu(page, graph, library, here);
+            if (cli)
+                console.error(`waygraph auto: ${menu.flat.length} move(s) available`);
+            if (menu.flat.length === 0) {
+                const fromHere = graph.edges.filter((e) => e.from === here).map((e) => e.block);
+                const missing = [...new Set(fromHere)].filter((b) => !library.byName.has(b));
+                console.error(here
+                    ? `waygraph auto: no runnable Blocks on "${here}"` +
+                        (fromHere.length
+                            ? ` (graph has: ${[...new Set(fromHere)].join(", ")}${missing.length ? `; not loaded: ${missing.join(", ")}` : ""})`
+                            : " - nothing on this page matches the graph.") +
+                        (cli ? "" : " Tip: waygraph auto --cli")
+                    : "waygraph auto: location unknown - pick nav-login (Start here) if shown.");
+                if (cli)
+                    break;
+            }
+            let pick;
+            if (cli && cliRl) {
+                printCliMenu(menu, library.byName);
+                pick = await cliPick(menu, cliRl);
+            }
+            else {
+                pick = await headfulPick(page, menu, library.byName, mem, () => pickWait.promise, lastRunNote);
+            }
+            if (pick.type === "quit")
+                break;
+            if (pick.index < 0 || pick.index >= menu.flat.length)
+                continue;
+            const edge = menu.flat[pick.index];
+            const entry = library.byName.get(edge.block);
+            if (!entry) {
+                console.error(`waygraph auto: Block "${edge.block}" not loaded - skipped`);
+                continue;
+            }
+            try {
+                if (edge.instanceOption) {
+                    mem.set(edge.instanceOption.key, edge.instanceOption.value);
+                }
+                if (!cli && (entry.block.requires?.length ?? 0) > 0) {
+                    await syncPanelMem(page, mem, entry.block.requires ?? []);
+                }
+                else {
+                    await ensureMem(entry, mem, cli);
+                }
+                const pickLabel = edge.label ?? entry.block.name;
+                console.error(`waygraph auto: running [${pick.index + 1}] ${pickLabel} ...`);
+                const result = await runOneBlock(engine, entry, context, page, mem, !cli);
+                // Trust block output over locate() - nav verify traits collide on /dashboard.
+                here = result.__state ?? edge.to;
+                lastRunNote = `${entry.block.name} -> ${here}`;
+                console.error(`waygraph auto: ran ${entry.block.name} -> ${here}`);
+            }
+            catch (err) {
+                lastRunNote = `${entry.block.name} failed`;
+                console.error(`waygraph auto: ${entry.block.name} failed - ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    finally {
+        cliRl?.close();
+        await context.close();
+        await closeBrowser();
+    }
+}

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 WaygraphEdge, type WaygraphGraph } from "../../analysis/graph.js";
+import type { WaygraphInstanceOption } from "../../engine/block/action-page.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.
  */

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

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

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

@@ -0,0 +1,11 @@
+import { MemPage, type MemKey } from "../../engine/mem/mem.js";
+import type { BlockEntry } from "../../manifest/project.js";
+export declare function missingMemKeys(entry: BlockEntry, mem: MemPage): MemKey<unknown>[];
+/** The project's own default for a key: its `registerMemStub` fake (live sessions load every `*.mem-stubs.ts`). */
+export declare function memStubValue(key: MemKey<unknown>): unknown | undefined;
+export declare function defaultMemJsonPrompt(key: MemKey<unknown>): string;
+export declare function seedMemFromEnv(mem: MemPage, entry: BlockEntry): boolean;
+/** Pre-seeds required keys from WAYGRAPH_DATA and the project's mem stubs, so a session does not stop for mem forms. */
+export declare function seedDefaultMem(library: Map<string, BlockEntry>, mem: MemPage): void;
+export declare function promptMemCli(entry: BlockEntry, mem: MemPage): Promise<void>;
+export declare function ensureMem(entry: BlockEntry, mem: MemPage, cli: boolean): Promise<void>;

package/dist/live/auto/mem.js

@@ -0,0 +1,85 @@
+// Mem for a live session: --data first, then the project's mem stubs; the terminal prompt for what is missing.
+import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { envString } from "../../engine/env.js";
+import { getMemStub } from "../../engine/mem/mem-stub.js";
+export function missingMemKeys(entry, mem) {
+    const requires = entry.block.requires ?? [];
+    return requires.filter((k) => !mem.has(k));
+}
+/** 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)?.();
+}
+export function defaultMemJsonPrompt(key) {
+    const def = memStubValue(key);
+    return def === undefined ? "{}" : JSON.stringify(def);
+}
+export function seedMemFromEnv(mem, entry) {
+    const raw = envString("WAYGRAPH_DATA") ?? envString("WAYGRAPH_AUTO_MEM");
+    if (!raw)
+        return false;
+    try {
+        const parsed = JSON.parse(raw);
+        for (const k of entry.block.requires ?? []) {
+            if (k.name in parsed)
+                mem.set(k, parsed[k.name]);
+        }
+        return missingMemKeys(entry, mem).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** 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 = envString("WAYGRAPH_DATA") ?? envString("WAYGRAPH_AUTO_MEM");
+    let envParsed = {};
+    if (raw) {
+        try {
+            envParsed = JSON.parse(raw);
+        }
+        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()) {
+        for (const k of entry.block.requires ?? []) {
+            if (mem.has(k))
+                continue;
+            if (k.name in envParsed) {
+                mem.set(k, envParsed[k.name]);
+                continue;
+            }
+            const def = memStubValue(k);
+            if (def !== undefined)
+                mem.set(k, def);
+        }
+    }
+}
+export async function promptMemCli(entry, mem) {
+    const rl = createInterface({ input, output });
+    try {
+        for (const k of missingMemKeys(entry, mem)) {
+            const def = defaultMemJsonPrompt(k);
+            const line = await rl.question(`  ${k.name} JSON [${def}]: `);
+            const json = line.trim() || def;
+            mem.set(k, JSON.parse(json));
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function ensureMem(entry, mem, cli) {
+    if (missingMemKeys(entry, mem).length === 0)
+        return;
+    if (seedMemFromEnv(mem, entry))
+        return;
+    if (cli) {
+        console.log(`\nBlock "${entry.block.name}" needs MemPage keys:`);
+        await promptMemCli(entry, mem);
+        return;
+    }
+    throw new Error(`Block "${entry.block.name}" needs MemPage keys - pass --data '{...}' / WAYGRAPH_DATA (or WAYGRAPH_AUTO_MEM), or enter values in --cli`);
+}

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>;