waygraph 0.15.24 → 0.15.25

package/dist/engine.js

@@ -1,1550 +1,12 @@
-import { chromium, firefox, webkit } from "@playwright/test";
-import { connect, checkpoint } from "./types.js";
-import { MemPage } from "./mem-page.js";
-import { runVerify, runPrecondition } from "./trait.js";
-import { normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight, } from "./highlights.js";
-const LAUNCHERS = { chromium, firefox, webkit };
-/**
- * Resolves which `BrowserType` actually launches for a `mem`-only run (no
- * caller-supplied context) - `config.browsers[browserName]` if given,
- * otherwise the real `@playwright/test` export. Waygraph is deliberately
- * "just an opinionated Playwright" - it doesn't own browser automation
- * itself, so it shouldn't force every consumer onto the vanilla launcher.
- * A stealth-patched or otherwise customized launcher (e.g. `playwright-extra`
- * plus a stealth plugin) is a drop-in replacement for `chromium`/`firefox`/
- * `webkit` - same `.launch()` shape - so accepting one here costs nothing for
- * a consumer who never sets it.
- */
-function resolveLauncher(browserName, config) {
-    return config?.browsers?.[browserName] ?? LAUNCHERS[browserName];
-}
-/**
- * Checks `block.requires` against `mem` and throws, naming every missing key at
- * once, if any are unset. `connect()` unions each Block's `requires` into the
- * composed Block, so calling this on a `defineFlow`-built Flow's entry - which
- * `runGraph` does automatically, before opening a tab - covers every Block in
- * that flow. It does not see Blocks only reachable through `branch()` routing,
- * since those depend on a runtime decision that hasn't happened yet.
- */
-export function preflight(mem, block) {
-    const missing = (block.requires ?? []).filter((k) => !mem.has(k));
-    if (missing.length > 0) {
-        throw new Error(`preflight: MemPage is missing required key(s) before "${block.name}" can run: ${missing
-            .map((k) => `"${k.name}"`)
-            .join(", ")}`);
-    }
-}
-/**
- * @example
- * const AppShellLayout = defineLayout({
- *   name: "app-shell",
- *   appliesTo: ["AppHome", "Chats", "Notifications", "Settings"],
- *   verify: [Trait.visible(SidebarSel.root)],
- * });
- * const engine = new Engine({ layouts: [AppShellLayout] });
- * // Now every Block resolving to one of those four Checkpoints, in any
- * // Flow this engine defines, also gets AppShellLayout's own verify run
- * // automatically - a page that silently drops the sidebar fails loud,
- * // even though no individual Block's own `verify` mentions it.
- */
-export function defineLayout(options) {
-    const appliesTo = typeof options.appliesTo === "function"
-        ? options.appliesTo
-        : (tag) => options.appliesTo.includes(tag);
-    return {
-        name: options.name,
-        ...(options.description ? { description: options.description } : {}),
-        appliesTo,
-        verify: options.verify,
-    };
-}
-/**
- * Runs every registered layout whose `appliesTo(tag)` matches the just-
- * resolved Checkpoint, in registration order, right after the Block's own
- * `verify` already ran. A layout's own Trait failing throws the same way
- * any other `runVerify` failure does, naming the layout so it's clearly
- * distinguishable from the Block's own verify in the error message.
- */
-async function runLayouts(layouts, tag, out, page, mem, blockName) {
-    if (!layouts)
-        return;
-    for (const layout of layouts) {
-        if (!layout.appliesTo(tag))
-            continue;
-        await runVerify(layout.verify, out, page, mem, `${blockName} (layout: "${layout.name}")`);
-    }
-}
-/**
- * Runs `entry` against a fresh tab and returns the resulting terminal Checkpoint.
- * The engine owns the tab's lifecycle, not any individual Block: the tab is
- * created before the first `act` runs and closed in `finally`, so it closes even
- * if a step throws.
- *
- * After each Block resolves, its `next` (if any, from `branch()`) is followed to
- * the following Block, in the same tab - a Block with no `next` runs exactly once,
- * unchanged from before `branch()` existed. `next` returning the same Block is a
- * self-loop; `maxSteps` bounds the loop so a routing bug fails loud instead of
- * hanging.
- *
- * `terminals`, if given, is a sanity check: the Checkpoint the run stops on must be
- * one of the tags the caller actually expects, or the run fails loud instead of
- * silently returning an unexpected result. Omit it when there is only ever one
- * reachable outcome by construction (as with a `defineFlow`-built Flow, which has
- * no routing at all) - there is nothing to validate against.
- */
-export async function runGraph(entry, terminals, context, mem, maxSteps = 5000, options) {
-    preflight(mem, entry);
-    const page = options?.page ?? (await context.newPage());
-    const closeOnFinish = options?.closeOnFinish ?? true;
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        let current = entry;
-        let input = checkpoint("__start__");
-        let steps = 0;
-        for (;;) {
-            if (++steps > maxSteps) {
-                throw new Error(`runGraph: exceeded ${maxSteps} steps - check for an unintended self-loop`);
-            }
-            await runPrecondition(current.instruction.precondition, input, page, mem, current.name);
-            await current.instruction.act(page, input, mem);
-            const observed = current.instruction.observe
-                ? await current.instruction.observe(page, mem)
-                : undefined;
-            const checkpoint = await current.instruction.resolve(observed);
-            await runVerify(current.instruction.verify, checkpoint, page, mem, current.name);
-            await runLayouts(options?.layouts, checkpoint.__state, checkpoint, page, mem, current.name);
-            const next = current.next?.(checkpoint);
-            if (!next) {
-                if (terminals && !terminals.has(checkpoint.__state)) {
-                    throw new Error(`runGraph: "${current.name}" resolved to "${checkpoint.__state}", which is not a registered terminal (expected one of: ${[...terminals].join(", ")})`);
-                }
-                return checkpoint;
-            }
-            current = next;
-            input = checkpoint;
-        }
-    }
-    finally {
-        if (closeOnFinish) {
-            await page.close();
-        }
-    }
-}
-/**
- * Drives a genuinely separate second tab through its own Block/Flow, in the
- * same browser context an existing `page` already belongs to - the primitive
- * `observe()` is specifically allowed to reach for (see {@link Instruction.observe}),
- * since `act`/`resolve` can't touch `page.context()` at all. A thin, named
- * wrapper around `runGraph` (which already opens its own page from whatever
- * context it's given) rather than a new mechanism - the point is making the
- * pattern discoverable and giving it a real name, not inventing new tab-lifecycle
- * logic. The spawned tab is closed (by `runGraph`'s own `finally`) before this
- * resolves; the original `page` is never touched.
- * @example
- * async observe(page, mem) {
- *   const receipt = await spawnTab(EmailReceiptFlow, page, mem);
- *   mem.set(ReceiptCode, receipt.__state);
- * }
- */
-export async function spawnTab(entry, page, mem, maxSteps = 5000) {
-    return runGraph(entry, undefined, page.context(), mem, maxSteps);
-}
-/**
- * Wraps one `act()` interaction with a caption and highlight, for a Block
- * author who wants to explicitly narrate a specific step rather than rely
- * on the generic per-fill/per-click narration `waygraph chain
- * WAYGRAPH_STEP=1` already does automatically -
- * `await narrate(submitButton, "confirms the order", () => submitButton.click())`
- * reads at the call site instead of being inferred.
- *
- * A true no-op everywhere except inside a `WAYGRAPH_STEP=1` run: it checks
- * for a `window.__wgPositionRing` hook the step-mode overlay installs on
- * the page before doing anything, so a headless/CI/automated run (nobody
- * watching, per-character delays and highlight pauses would just be wasted
- * time) pays zero extra cost - not even the boundingBox() lookup runs. The
- * `action` itself always runs regardless; only the narration is
- * conditional.
- * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
- */
-export async function narrate(locator, caption, action) {
-    const page = locator.page();
-    const active = await page
-        .evaluate(() => typeof globalThis.__wgPositionRing === "function")
-        .catch(() => false);
-    if (!active)
-        return action();
-    let owning = false;
-    try {
-        const box = await locator.boundingBox();
-        if (box) {
-            await page
-                .evaluate(({ box, caption }) => {
-                const w = globalThis;
-                if (w.__wgPositionRing)
-                    w.__wgPositionRing(box, caption, "planned");
-                // The CLI's own automatic per-fill/per-click narration checks
-                // this before showing (and overwriting) its own guess - an
-                // explicitly authored caption should win, not get immediately
-                // replaced a moment later by the generic one.
-                w.__wgLastNarrate = Date.now();
-                // Also claim the ring itself: the auto-highlight click/fill
-                // patches each hide the ring right after THEIR own step
-                // finishes, which - if action() below does more than one thing
-                // (e.g. a click then a wait for a toast) - would wipe this
-                // caption after just the first sub-step instead of the whole
-                // narrated action. Their hideRing() calls no-op while this is
-                // true; narrate() below is the one that actually clears it.
-                w.__wgNarrateOwnsRing = true;
-            }, { box, caption })
-                .catch(() => { });
-            owning = true;
-            // The ring alone is pointless if action() fires on the very next
-            // tick - a click that navigates (e.g. a form submit) wipes the ring
-            // before a human can read the caption at all. Give it the same
-            // "pop for a few seconds" dwell as the CLI's own auto-highlight
-            // clicks before the real action runs.
-            await new Promise((resolve) => setTimeout(resolve, 650));
-            // Re-stamp __wgLastNarrate right before handing off to action() - the
-            // CLI's auto-highlight patches only treat a narrate() as "just
-            // handled" within a short window (500ms), which the dwell above
-            // already burned through. Without this, action()'s own click/fill
-            // (same patched Locator prototype) would stomp this caption with its
-            // own generic one a moment after it finally became visible.
-            await page
-                .evaluate(() => {
-                globalThis.__wgLastNarrate = Date.now();
-            })
-                .catch(() => { });
-        }
-    }
-    catch {
-        // best-effort - the real action below still runs either way
-    }
-    try {
-        return await action();
-    }
-    finally {
-        if (owning) {
-            await page
-                .evaluate(() => {
-                const w = globalThis;
-                w.__wgNarrateOwnsRing = false;
-                if (w.__wgHideRing)
-                    w.__wgHideRing();
-            })
-                .catch(() => { });
-        }
-    }
-}
-/** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
-export const start = Symbol("waygraph.start");
-export const end = Symbol("waygraph.end");
-function findBlockIndex(middle, block) {
-    if (typeof block === "number") {
-        if (block < 0 || block >= middle.length) {
-            throw new Error(`Flow: no Block at index ${block} in this flow (has ${middle.length})`);
-        }
-        return block;
-    }
-    const blockName = typeof block === "string" ? block : block.name;
-    const index = middle.findIndex((b) => b.name === blockName);
-    if (index === -1) {
-        throw new Error(`Flow: no Block named "${blockName}" in this flow (has: ${middle.map((b) => b.name).join(", ")})`);
-    }
-    return index;
-}
-function buildFlow(middle, engineConfig) {
-    // resetSession/title start false/unset here - defineFlow itself carries
-    // no such options anymore. They're set by wrapping the result in
-    // withSessionReset()/withTitle() instead (non-destructive decorators,
-    // same pattern as withVerify), which also re-apply themselves after any
-    // further withBlockVerify/modBlockVerify patch so the flag survives.
-    // Layouts have to be threaded into every pairwise connect(), not just the
-    // trailing runGraph call - see connect()'s own doc comment in types.ts:
-    // buildFlow's reduce IS the only place a defineFlow-built Flow's
-    // intermediate (non-final) Checkpoints are ever verified at all.
-    const chain = middle.reduce((a, b) => connect(a, b, engineConfig.layouts));
-    // Declared separately (not as the object-literal method below) so the
-    // three-overload `Flow.run` signature can be checked against the actual
-    // per-call-shape behavior, then attached with a cast - object-literal
-    // methods can't satisfy TS's per-overload implementation check the way a
-    // standalone function assigned to the property can.
-    const run = async function run(contextOrMem, memOrConfig, options) {
-        if (contextOrMem instanceof MemPage) {
-            const mem = contextOrMem;
-            const config = { ...engineConfig, ...memOrConfig };
-            // Checked again inside runGraph too, but doing it here first means a
-            // missing key fails before a browser process even launches, not just
-            // before a page opens - the same "fail loud, cheaply" guarantee
-            // run(context, mem) already has via an existing context.
-            preflight(mem, chain);
-            const browserName = config.browserName ?? "chromium";
-            const launch = resolveLauncher(browserName, config);
-            // If CHROME_PATH/CHROMIUM_PATH is set in the environment (e.g. a system
-            // or Flatpak Chromium), launch that instead of Playwright's own bundled
-            // binary - only for chromium (the env var names a Chromium build, not a
-            // Firefox/WebKit one), and a no-op default anywhere that env var isn't set.
-            const executablePath = browserName === "chromium" ? process.env.CHROME_PATH || process.env.CHROMIUM_PATH : undefined;
-            const browser = await launch.launch({
-                headless: config.headless ?? true,
-                ...(config.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
-                ...(executablePath ? { executablePath } : {}),
-            });
-            try {
-                const context = await browser.newContext(config.recordVideo ? { recordVideo: config.recordVideo } : {});
-                try {
-                    return await runGraph(chain, undefined, context, mem, 5000, {
-                        ...(config.layouts !== undefined ? { layouts: config.layouts } : {}),
-                    });
-                }
-                finally {
-                    // Playwright finalizes recordVideo on context.close(); skip when
-                    // not recording so mem-only runs with stub contexts stay unchanged.
-                    if (config.recordVideo) {
-                        await context.close();
-                    }
-                }
-            }
-            finally {
-                await browser.close();
-            }
-        }
-        const context = contextOrMem;
-        const mem = memOrConfig;
-        // Open (or reuse) the page here, not inside runGraph, so this method -
-        // not runGraph - decides whether to close it once the run is over; the
-        // page reference has to survive past runGraph's own return either way.
-        const gotOwnPage = options?.page === undefined;
-        const page = options?.page ?? (await context.newPage());
-        // Defaulting close-on-finish to `true` unconditionally would close a
-        // page the *caller* opened and handed in via `options.page` - the exact
-        // thing this option exists to let a caller keep driving. Only default to
-        // closing when this call opened the page itself (no `options.page`
-        // given), which is the one case that matches every `run(context, mem)`
-        // call from before this option existed. An explicit `closeOnFinish`
-        // always wins either way.
-        const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
-        const resolvedLayouts = options?.layouts ?? engineConfig.layouts;
-        const result = await runGraph(chain, undefined, context, mem, 5000, {
-            page,
-            closeOnFinish: false,
-            ...(resolvedLayouts !== undefined ? { layouts: resolvedLayouts } : {}),
-        });
-        if (closeOnFinish) {
-            await page.close();
-        }
-        // The return *shape* only changes on an explicit `closeOnFinish: false`
-        // (the literal the `{ result, page }` overload is typed against) - not
-        // on the computed `closeOnFinish` default above. A caller who passed
-        // their own `page` and left `closeOnFinish` unset already holds that
-        // page reference; handing it back again in a different return shape
-        // would silently break the plain-`Out` overload their call actually
-        // matched at the type level.
-        if (options?.closeOnFinish === false) {
-            return { result, page };
-        }
-        return result;
-    };
-    return {
-        resetSession: false,
-        blocks: () => middle.map((b) => ({ name: b.name, block: b, ...(b.routes ? { routes: b.routes } : {}) })),
-        run: run,
-        withBlockVerify(block, verify) {
-            const index = findBlockIndex(middle, block);
-            const patched = [...middle];
-            patched[index] = withVerify(middle[index], verify);
-            return buildFlow(patched, engineConfig);
-        },
-        modBlockVerify(block, nameOrIndex, newCheck) {
-            const index = findBlockIndex(middle, block);
-            const patched = [...middle];
-            patched[index] = modVerify(middle[index], nameOrIndex, newCheck);
-            return buildFlow(patched, engineConfig);
-        },
-    };
-}
-/**
- * Marks a Flow as expecting to start from a genuinely fresh, unauthenticated
- * browser state - e.g. a login flow meant to be re-entered later in a longer
- * showcase. Non-destructive, same pattern as {@link withVerify}: returns a
- * new Flow: the original is untouched, and the flag survives any further
- * `withBlockVerify`/`modBlockVerify` patch applied to the result.
- *
- * By itself this does nothing - `Flow.run()` never reads `resetSession`.
- * It's a hint {@link chainFlow} looks for: right before this Flow's first
- * Block runs (skipped if it's the very first thing in the chain - nothing
- * to reset yet), chainFlow clears cookies and storage so this Flow starts
- * exactly as if a human had opened the app fresh, not wherever the
- * previous Flow in the chain happened to leave the page.
- * @example const loginFlow = withSessionReset(engine.defineFlow([start, LoginBlock, end]));
- */
-export function withSessionReset(flow) {
-    return {
-        ...flow,
-        resetSession: true,
-        withBlockVerify: (block, verify) => withSessionReset(flow.withBlockVerify(block, verify)),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withSessionReset(flow.modBlockVerify(block, nameOrIndex, newCheck)),
-    };
-}
-/**
- * Names a Flow for display - a step-through overlay/showcase (waygraph's
- * `chain --step`) shows this as the running banner while this Flow's own
- * Blocks are executing, instead of one fixed title for the whole run.
- * Non-destructive, same pattern as {@link withSessionReset}.
- * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
- */
-export function withTitle(flow, title) {
-    return {
-        ...flow,
-        title,
-        withBlockVerify: (block, verify) => withTitle(flow.withBlockVerify(block, verify), title),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withTitle(flow.modBlockVerify(block, nameOrIndex, newCheck), title),
-    };
-}
-/**
- * Opts this Flow into memStub: `requires` keys the caller didn't supply get
- * filled from `registerMemStub`'s registry (`src/mem-stub.ts`) instead of
- * failing preflight, for any key that has a registered fake generator - a
- * required key with no registration still fails exactly as before.
- * Non-destructive, same pattern as {@link withTitle}. `run()` never reads
- * this itself - the CLI's `--data`/`--mem-stub` seeding, or a bare-library
- * caller's own explicit `seedMemStub(mem, flow)` call, does the filling.
- * @example const demoLogin = withMemStub(loginFlow);
- */
-export function withMemStub(flow) {
-    return {
-        ...flow,
-        memStub: true,
-        withBlockVerify: (block, verify) => withMemStub(flow.withBlockVerify(block, verify)),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withMemStub(flow.modBlockVerify(block, nameOrIndex, newCheck)),
-    };
-}
-/**
- * Demo pacing for a whole Flow episode (fast review vs slow gap/wrong walkthrough).
- * Non-destructive. `fastForwardComposeBlock` is always blitz for its own step;
- * use this when an entire episode should be fast or slow.
- * @example withDemoPace(withTitle(gapFlow, "Episode 2 - gaps"), "slow")
- * @example withDemoPace(happyFlow, 0.5)  // 2x faster than normal
- * @example withDemoPace(gapFlow, 2.5)    // 2.5x slower
- * @example withDemoPace(gapFlow, 4500)   // absolute ~4.5s gates/dwells
- */
-export function withDemoPace(flow, pace) {
-    const demoPace = pace;
-    return {
-        ...flow,
-        demoPace,
-        withBlockVerify: (block, verify) => withDemoPace(flow.withBlockVerify(block, verify), demoPace),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withDemoPace(flow.modBlockVerify(block, nameOrIndex, newCheck), demoPace),
-    };
-}
-/**
- * Default highlight look for a Flow episode (size / weight / optional tone).
- * Per-slot stub or {@link withHighlightFixtures} values win when set.
- * @example withHighlightStyle(withDemoPace(gapFlow, "slow"), { size: "lg", weight: "bold" })
- */
-export function withHighlightStyle(flow, style) {
-    const highlightStyle = {
-        ...(style.tone !== undefined ? { tone: normalizeHighlightTone(style.tone) } : {}),
-        ...(style.size !== undefined ? { size: normalizeHighlightSize(style.size) } : {}),
-        ...(style.weight !== undefined ? { weight: normalizeHighlightWeight(style.weight) } : {}),
-    };
-    return {
-        ...flow,
-        highlightStyle,
-        withBlockVerify: (block, verify) => withHighlightStyle(flow.withBlockVerify(block, verify), highlightStyle),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withHighlightStyle(flow.modBlockVerify(block, nameOrIndex, newCheck), highlightStyle),
-    };
-}
-/**
- * Demo pacing for one Block or compose unit (not FF - use fastForwardComposeBlock for blitz).
- * @example withBlockPace(composeBlock("gap-review", [...]), "slow")
- */
-export function withBlockPace(block, pace) {
-    return {
-        ...block,
-        demoPace: pace,
-    };
-}
-/**
- * Marks a Flow as one that's SUPPOSED to throw - e.g. a locked-out user's
- * login attempt genuinely failing, demonstrating the app's own real
- * behavior rather than a bug in the demo. Non-destructive, same pattern as
- * {@link withTitle}.
- *
- * By itself this changes nothing about how the Flow runs - it still throws
- * Marks a Flow whose last step is an intentional product failure (demo overlay).
- * Step mode shows stubOnError rings + an amber "expected outcome" panel when:
- * - the last block **throws**, or
- * - the last block **succeeds** on the fail branch (e.g. LoginPage + error banner
- *   after submit-login branched instead of throwing).
- * Headless `run()` is unchanged - branching success returns the checkpoint.
- * @example const viewerBlockedFlow = withExpectedFailure(
- *   engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]),
- *   "locked_out_user stays on LoginPage with the error banner - working as intended.",
- * );
- */
-export function withExpectedFailure(flow, reason) {
-    return {
-        ...flow,
-        expectedFailureReason: reason,
-        withBlockVerify: (block, verify) => withExpectedFailure(flow.withBlockVerify(block, verify), reason),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withExpectedFailure(flow.modBlockVerify(block, nameOrIndex, newCheck), reason),
-    };
-}
-/**
- * Attaches demo highlight fixtures to a Flow - unlimited purposes on `.flow.ts`
- * (AC copy, BUG/GATE tags, detail) merged onto each block's stubBefore/stubAfter/
- * stubOnError slots. Non-destructive, same pattern as {@link withTitle}.
- * Demo/`chain --step` reads `flow.highlightFixtures`; `run()` ignores it.
- * @example withHighlightFixtures(issueFlow, { "submit-login": { stubBefore: { email: { label: "AC-1" } } } })
- */
-export function withHighlightFixtures(flow, fixtures) {
-    return {
-        ...flow,
-        highlightFixtures: fixtures,
-        withBlockVerify: (block, verify) => withHighlightFixtures(flow.withBlockVerify(block, verify), fixtures),
-        modBlockVerify: (block, nameOrIndex, newCheck) => withHighlightFixtures(flow.modBlockVerify(block, nameOrIndex, newCheck), fixtures),
-    };
-}
-function locateInChain(flows, block) {
-    if (typeof block === "number") {
-        let remaining = block;
-        for (let fi = 0; fi < flows.length; fi++) {
-            const len = flows[fi].blocks().length;
-            if (remaining < len)
-                return { flowIndex: fi, localIndex: remaining };
-            remaining -= len;
-        }
-        throw new Error(`chainFlow: no Block at index ${block} across ${flows.length} chained flows`);
-    }
-    const blockName = typeof block === "string" ? block : block.name;
-    for (let fi = 0; fi < flows.length; fi++) {
-        const localIndex = flows[fi].blocks().findIndex((bi) => bi.name === blockName);
-        if (localIndex !== -1)
-            return { flowIndex: fi, localIndex };
-    }
-    throw new Error(`chainFlow: no Block named "${blockName}" in any chained flow`);
-}
-async function clearSessionState(context, page) {
-    await context.clearCookies().catch(() => { });
-    await page
-        .evaluate(() => {
-        try {
-            localStorage.clear();
-            sessionStorage.clear();
-        }
-        catch {
-            /* storage blocked (e.g. about:blank) - nothing to clear anyway */
-        }
-    })
-        .catch(() => { });
-}
-/**
- * Runs several complete, independent Flows one after another, reusing the
- * same page/context/mem in order - each remains its own validated
- * start-to-end unit (a Flow's own `[start, ...blocks, end]` contract is
- * untouched), this only sequences whole Flows. Deliberately NOT the same
- * thing as {@link composeBlock}: composeBlock nests several Blocks into
- * one Block that can drop back into another `defineFlow([...])` - a
- * chainFlow result is a Flow, but not meant to be nested inside another
- * Flow's own Block list. Recursive nesting stays composeBlock's job alone;
- * chainFlow is a flat, one-level sequencing of complete showcases (e.g.
- * "ticket #123 end to end, then ticket #456 end to end").
- *
- * A sub-flow wrapped in {@link withSessionReset} gets its cookies/storage
- * cleared right before it runs (skipped for the very first flow in the
- * chain - nothing to reset yet). The combined result is whatever the LAST
- * flow resolved to.
- * @example chainFlow(ticket123Flow, ticket456Flow).run(context, mem)
- */
-export function chainFlow(...flows) {
-    if (flows.length === 0) {
-        throw new Error("chainFlow: give at least one Flow");
-    }
-    const run = async function run(contextOrMem, memOrConfig, options) {
-        if (contextOrMem instanceof MemPage) {
-            const mem = contextOrMem;
-            const config = memOrConfig;
-            // One browser for the WHOLE chain - each sub-flow's own run(mem,
-            // config) would otherwise each launch a separate browser, defeating
-            // the point of sequencing them (a fresh browser is itself a full
-            // session reset, silently making withSessionReset a no-op).
-            const browserName = config?.browserName ?? "chromium";
-            const launch = resolveLauncher(browserName, config);
-            const executablePath = browserName === "chromium" ? process.env.CHROME_PATH || process.env.CHROMIUM_PATH : undefined;
-            const browser = await launch.launch({
-                headless: config?.headless ?? true,
-                ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
-                ...(executablePath ? { executablePath } : {}),
-            });
-            try {
-                const context = await browser.newContext(config?.recordVideo ? { recordVideo: config.recordVideo } : {});
-                try {
-                    return await run(context, mem, { closeOnFinish: true });
-                }
-                finally {
-                    await context.close();
-                }
-            }
-            finally {
-                await browser.close();
-            }
-        }
-        const context = contextOrMem;
-        const mem = memOrConfig;
-        const gotOwnPage = options?.page === undefined;
-        const page = options?.page ?? (await context.newPage());
-        const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
-        let result;
-        for (let i = 0; i < flows.length; i++) {
-            const flow = flows[i];
-            if (i > 0 && flow.resetSession) {
-                await clearSessionState(context, page);
-            }
-            const outcome = (await flow.run(context, mem, { page, closeOnFinish: false }));
-            result = outcome.result;
-        }
-        if (closeOnFinish) {
-            await page.close();
-        }
-        if (options?.closeOnFinish === false) {
-            return { result, page };
-        }
-        return result;
-    };
-    return {
-        resetSession: false,
-        blocks: () => flows.flatMap((flow, idx) => flow.blocks().map((bi, i) => ({
-            ...bi,
-            ...(i === 0 && idx > 0 && flow.resetSession ? { resetSessionBefore: true } : {}),
-        }))),
-        run: run,
-        withBlockVerify(block, verify) {
-            const { flowIndex, localIndex } = locateInChain(flows, block);
-            const patched = [...flows];
-            patched[flowIndex] = patched[flowIndex].withBlockVerify(localIndex, verify);
-            return chainFlow(...patched);
-        },
-        modBlockVerify(block, nameOrIndex, newCheck) {
-            const { flowIndex, localIndex } = locateInChain(flows, block);
-            const patched = [...flows];
-            patched[flowIndex] = patched[flowIndex].modBlockVerify(localIndex, nameOrIndex, newCheck);
-            return chainFlow(...patched);
-        },
-    };
-}
-export function composeBlock(name, steps) {
-    if (steps.length === 0) {
-        throw new Error(`composeBlock: "${name}" needs at least one step`);
-    }
-    const chain = steps.reduce((a, b) => connect(a, b));
-    return {
-        ...chain,
-        name,
-        steps: () => steps.map((b) => ({ name: b.name, block: b, ...(b.routes ? { routes: b.routes } : {}) })),
-        withStepVerify(step, verify) {
-            const index = findBlockIndex(steps, step);
-            const patched = [...steps];
-            patched[index] = withVerify(steps[index], verify);
-            return composeBlock(name, patched);
-        },
-        modStepVerify(step, nameOrIndex, newCheck) {
-            const index = findBlockIndex(steps, step);
-            const patched = [...steps];
-            patched[index] = modVerify(steps[index], nameOrIndex, newCheck);
-            return composeBlock(name, patched);
-        },
-    };
-}
-/** True when `block` came from {@link fastForwardComposeBlock}. */
-export function isFastForwardBlock(block) {
-    return (block.fastForward === true &&
-        typeof block.steps === "function");
-}
-function wrapFfError(ffName, err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (msg.startsWith(`${ffName} > `)) {
-        return err instanceof Error ? err : new Error(msg);
-    }
-    const wrapped = new Error(`${ffName} > ${msg}`);
-    if (err instanceof Error && err.stack) {
-        wrapped.stack = err.stack;
-    }
-    return wrapped;
-}
-export function fastForwardComposeBlock(name, steps) {
-    if (steps.length === 0) {
-        throw new Error(`fastForwardComposeBlock: "${name}" needs at least one step`);
-    }
-    const base = composeBlock(name, steps);
-    const origAct = base.instruction.act.bind(base.instruction);
-    const ff = {
-        ...base,
-        fastForward: true,
-        instruction: {
-            ...base.instruction,
-            async act(page, input, mem) {
-                try {
-                    await origAct(page, input, mem);
-                }
-                catch (e) {
-                    throw wrapFfError(name, e);
-                }
-            },
-        },
-        withStepVerify(step, verify) {
-            const index = findBlockIndex(steps, step);
-            const patched = [...steps];
-            patched[index] = withVerify(steps[index], verify);
-            return fastForwardComposeBlock(name, patched);
-        },
-        modStepVerify(step, nameOrIndex, newCheck) {
-            const index = findBlockIndex(steps, step);
-            const patched = [...steps];
-            patched[index] = modVerify(steps[index], nameOrIndex, newCheck);
-            return fastForwardComposeBlock(name, patched);
-        },
-    };
-    return ff;
-}
-/**
- * Holds engine-level configuration shared across every flow defined from it -
- * for now, just how to launch a browser when a Flow owns its own
- * (`headless`/`browserName`/`slowMo`); traits/interstitials/watchers land here
- * in a later change.
- * @example const engine = new Engine({ headless: false, slowMo: 250 });
- */
-export class Engine {
-    config;
-    constructor(config = {}) {
-        this.config = config;
-    }
-    defineFlow(blocks) {
-        return buildFlow(blocks.slice(1, -1), this.config);
-    }
-    /**
-     * Fluent, kind-checked alternative to `defineFlow([start, ...blocks, end])` -
-     * see {@link MapBuilder}. Real, direct request this responds to: pia/zsign's
-     * own agents kept hand-editing/hand-composing Blocks into ad hoc shapes
-     * ("locks" convention tried, still got broken) - `map()` forces every step
-     * through this Engine's own `define*Block` factories (checked by the same
-     * `__waygraphKind`/`__waygraphSalt` runtime markers `graph.ts`/`map-check.ts`
-     * already trust), so a hand-rolled plain-object Block can never silently
-     * pass as a real navigation/assertion/method step. `homeOrigin`, if given,
-     * also gates `.gotoPage()`/`.gotoExternal()` against each Nav/Page Block's
-     * own static `url` (skipped, honestly, for click-based/dynamic nav - not
-     * statically checkable, same limitation `map-check.ts` already documents).
-     * @example
-     * const flow = engine.map({ homeOrigin: "https://app.example.com" })
-     *   .start()
-     *   .gotoPage(NavHomeBlock)
-     *   .assert(AssertHelloBlock)
-     *   .gotoExternal(NavMailpitBlock)
-     *   .end();
-     */
-    map(options) {
-        return MapBuilder.begin(this, options?.homeOrigin);
-    }
-}
-function mapKindOf(block) {
-    return block?.__waygraphKind;
-}
-function mapSaltOf(block) {
-    return block?.__waygraphSalt;
-}
-function mapNavUrlOf(block) {
-    const url = block?.__waygraphNavUrl;
-    return typeof url === "string" ? url : undefined;
-}
-const MAP_KIND_FACTORY_HINT = {
-    nav: "defineNavBlock/defineMemNavBlock",
-    page: "definePageBlock",
-    assert: "defineAssertBlock",
-};
-const MAP_SALT_FACTORY_HINT = {
-    method: "defineMethodBlock",
-    effect: "defineEffectBlock",
-};
-function assertMapKind(block, allowed, method) {
-    const kind = mapKindOf(block);
-    if (kind !== undefined && allowed.includes(kind))
-        return;
-    const wanted = allowed.map((k) => MAP_KIND_FACTORY_HINT[k] ?? k).join(" or ");
-    const found = kind ? `a Block of kind "${kind}"` : "an object with no waygraph kind marker at all";
-    throw new Error(`Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
-        `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
-        "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.");
-}
-function assertMapSalt(block, allowed, method) {
-    const salt = mapSaltOf(block);
-    if (salt !== undefined && allowed.includes(salt))
-        return;
-    const wanted = allowed.map((s) => MAP_SALT_FACTORY_HINT[s] ?? s).join(" or ");
-    const found = salt ? `a Block salted "${salt}"` : "an object with no waygraph salt marker at all";
-    throw new Error(`Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
-        `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
-        "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.");
-}
-function assertMapOrigin(block, homeOrigin, expect, method) {
-    if (!homeOrigin)
-        return; // not configured - can't validate, honest no-op
-    const navUrl = mapNavUrlOf(block);
-    if (navUrl === undefined)
-        return; // click-based/dynamic nav - not statically checkable
-    let targetOrigin;
-    let wantOrigin;
-    try {
-        targetOrigin = new URL(navUrl, homeOrigin).origin;
-        wantOrigin = new URL(homeOrigin).origin;
-    }
-    catch {
-        return; // malformed URL - not this check's job to validate that
-    }
-    const isExternal = targetOrigin !== wantOrigin;
-    if (expect === "internal" && isExternal) {
-        throw new Error(`Waygraph map: .gotoPage("${block.name}") targets ${targetOrigin}, which is NOT this map's ` +
-            `home origin (${wantOrigin}) - use .gotoExternal() for a genuinely cross-origin destination.`);
-    }
-    if (expect === "external" && !isExternal) {
-        throw new Error(`Waygraph map: .gotoExternal("${block.name}") targets ${targetOrigin}, which IS this map's ` +
-            `home origin (${wantOrigin}) - use .gotoPage() for an internal destination.`);
-    }
-}
-/**
- * Fluent builder over {@link Engine.defineFlow} - see `map()`'s own doc
- * comment for why this exists. Each step method is scoped to exactly the
- * Block kind its name promises, checked at RUNTIME against the
- * `__waygraphKind`/`__waygraphSalt` markers `defineNavBlock`/`definePageBlock`/
- * `defineAssertBlock`/`defineMethodBlock`/`defineEffectBlock` already set
- * (the same markers `graph.ts` and `map-check.ts` trust) - not just a type
- * hint, since a hand-rolled object can satisfy the TypeScript `Block<In,Out>`
- * shape without ever going through a real factory. Each call also
- * typechecks the accumulated Checkpoint chain exactly like `defineFlow`'s
- * own tuple overloads do (a step's `In` must equal the previous step's
- * `Out`) - this is what "no teleporting" means: there is no method on this
- * builder that can skip from one Checkpoint to an unrelated one without a
- * real, kind-correct Block in between.
- */
-export class MapBuilder {
-    engine;
-    steps;
-    homeOrigin;
-    ff;
-    constructor(engine, steps, homeOrigin, ff = null) {
-        this.engine = engine;
-        this.steps = steps;
-        this.homeOrigin = homeOrigin;
-        this.ff = ff;
-    }
-    /** @internal - use `engine.map()` or the standalone `map()` export. */
-    static begin(engine, homeOrigin) {
-        return new MapBuilder(engine, [], homeOrigin, null);
-    }
-    /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
-    start() {
-        return this;
-    }
-    /**
-     * Open a fast-forward window - steps until {@link ffEnd} collapse into one
-     * opaque `fastForwardComposeBlock` (blitz theater). Kind/salt checks still
-     * run on each inner step as it is added.
-     */
-    ffStart(name) {
-        if (this.ff) {
-            throw new Error(`Waygraph map: .ffStart() while already inside "${this.ff.name}" - call .ffEnd() first`);
-        }
-        const ffName = typeof name === "string" && name.trim()
-            ? name.trim()
-            : `ff-${this.steps.length + 1}`;
-        return new MapBuilder(this.engine, this.steps, this.homeOrigin, {
-            name: ffName,
-            buffer: [],
-        });
-    }
-    /**
-     * Close the current fast-forward window and append one FFCompose step.
-     * Throws if empty or if {@link ffStart} was never opened.
-     */
-    ffEnd() {
-        if (!this.ff) {
-            throw new Error("Waygraph map: .ffEnd() with no open .ffStart()");
-        }
-        if (this.ff.buffer.length === 0) {
-            throw new Error(`Waygraph map: .ffEnd() for "${this.ff.name}" has no steps - add .gotoPage/.method/… inside the window`);
-        }
-        const composed = fastForwardComposeBlock(this.ff.name, 
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        this.ff.buffer);
-        return new MapBuilder(this.engine, [...this.steps, composed], this.homeOrigin, null);
-    }
-    appendStep(block) {
-        if (this.ff) {
-            return new MapBuilder(this.engine, this.steps, this.homeOrigin, {
-                name: this.ff.name,
-                buffer: [...this.ff.buffer, block],
-            });
-        }
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin, null);
-    }
-    /**
-     * Appends an internal navigation/page-arrival step - requires a Block from
-     * `defineNavBlock`/`defineMemNavBlock`/`definePageBlock`. Throws if given
-     * anything else, including a `homeOrigin`-mismatched static `url`.
-     * Compile-time: {@link NavBlock} or {@link PageBlock} only (not Assert/Method).
-     */
-    gotoPage(block) {
-        assertMapKind(block, ["nav", "page"], "gotoPage");
-        assertMapOrigin(block, this.homeOrigin, "internal", "gotoPage");
-        return this.appendStep(block);
-    }
-    /**
-     * Appends a genuinely cross-origin navigation step (e.g. `(external)/`
-     * Blocks in the Waygraph Map convention: mailpit, maildrop.cc) - same
-     * kind requirement as {@link gotoPage}, plus the inverse `homeOrigin` check.
-     * Compile-time: {@link NavBlock} or {@link PageBlock} only.
-     */
-    gotoExternal(block) {
-        assertMapKind(block, ["nav", "page"], "gotoExternal");
-        assertMapOrigin(block, this.homeOrigin, "external", "gotoExternal");
-        return this.appendStep(block);
-    }
-    /**
-     * Appends a self-loop verification step - requires a Block from
-     * `defineAssertBlock`. Compile-time: {@link AssertBlock} only (not `.method()`).
-     */
-    assert(block) {
-        assertMapKind(block, ["assert"], "assert");
-        return this.appendStep(block);
-    }
-    /**
-     * Appends a non-navigating page action (submit, upload, add/remove an
-     * instance) - requires a Block from `defineMethodBlock`/`defineActionBlock`/
-     * `defineEffectBlock`/`defineMemEffectBlock`.
-     * Compile-time: {@link MethodBlock} or {@link EffectBlock} only - Assert
-     * Blocks must use `.assert()`. Runtime also rejects `__waygraphKind =
-     * "assert"` (those still carry method salt from the factory internals).
-     */
-    method(block) {
-        if (mapKindOf(block) === "assert") {
-            throw new Error(`Waygraph map: .method("${block.name}") got a defineAssertBlock - use .assert() for ` +
-                "self-loop verify steps (Assert Blocks share method salt internally but are not methods).");
-        }
-        assertMapSalt(block, ["method", "effect"], "method");
-        return this.appendStep(block);
-    }
-    /**
-     * Finalizes this chain into a real, runnable {@link Flow} - same object
-     * `defineFlow` returns, so `withBlockVerify`/`modBlockVerify` and every
-     * `withTitle`/`withHighlightFixtures`/etc. decorator still apply exactly
-     * as they do today; this builder only changes how the chain is assembled,
-     * never what it produces. Throws if no step was ever added - an empty map
-     * isn't a flow.
-     */
-    end() {
-        if (this.ff) {
-            throw new Error(`Waygraph map: .end() while .ffStart("${this.ff.name}") is still open - call .ffEnd() first`);
-        }
-        if (this.steps.length === 0) {
-            throw new Error("Waygraph map: .end() called with zero steps - add at least one .gotoPage()/.gotoExternal()/" +
-                ".assert()/.method() before .end()");
-        }
-        const chain = [start, ...this.steps, end];
-        return this.engine.defineFlow(chain);
-    }
-}
-/**
- * Standalone convenience for `new Engine(config).map(options)` - use this
- * when a call site doesn't otherwise need its own `Engine` instance (no
- * shared `headless`/`slowMo`/`layouts` across several flows).
- * @example const flow = map({ homeOrigin: "https://app.example.com" }).gotoPage(NavHomeBlock).end();
- */
-export function map(options) {
-    return new Engine(options).map(options);
-}
-/**
- * Attaches routing to `block` without touching its act/observe/resolve/verify -
- * `routes` must cover every tag of `block`'s output (a missing route is a compile
- * error), and the returned Block runs exactly as `block` always did, just followed
- * by whichever next Block the resolved tag routes to. `null` for a tag means that
- * tag is terminal - the run stops there, same as a Block with no routing at all.
- * A route pointing back at `block` itself is a self-loop; see `runGraph`'s
- * `maxSteps` for its safety net. The return type is deliberately `Block<In, any>` -
- * a route can lead anywhere, including back through itself, so there is no fixed
- * Out type to express; state the expected outcomes to `runGraph` via `terminals`
- * instead.
- */
-export function branch(block, routes) {
-    const base = stripMethods(block);
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    let routed;
-    const routesAsData = {};
-    for (const [tag, target] of Object.entries(routes)) {
-        routesAsData[tag] = target === null ? null : target === block ? base.name : target.name;
-    }
-    routed = defineBlock({
-        ...base,
-        next: (checkpoint) => {
-            const target = routes[checkpoint.__state];
-            if (target === undefined || target === null)
-                return undefined;
-            // A route naming `block` itself (the only self-reference in scope when
-            // `routes` was written) means "loop back with routing intact" - substitute
-            // the routed Block, not the original with no `next` of its own.
-            return target === block ? routed : target;
-        },
-        routes: routesAsData,
-    });
-    return routed;
-}
-/**
- * Strips `withVerify`/`modVerify`/`modVerifyAll` off a Block, keeping everything
- * else - `name`, `instruction`, `next`, `requires`. Every function below that
- * returns a new Block calls this on its input first, then rebuilds through
- * `defineBlock`. Without it, a Block's attached methods close over the shape it
- * had *when they were attached* - call `.withVerify()` on a Block that
- * `branch()` added routing to afterward, and without this step the result would
- * silently drop that routing, since the stale closure never knew about it.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function stripMethods(block) {
-    return {
-        name: block.name,
-        instruction: block.instruction,
-        ...(block.description ? { description: block.description } : {}),
-        ...(block.next ? { next: block.next } : {}),
-        ...(block.requires ? { requires: block.requires } : {}),
-        ...(block.routes ? { routes: block.routes } : {}),
-        ...(block.instanceOptions ? { instanceOptions: block.instanceOptions } : {}),
-    };
-}
-/** Copy non-enumerable waygraph markers so decorate/withVerify keep map() kind checks. */
-function copyWaygraphRuntime(from, to) {
-    for (const key of [
-        "__waygraphKind",
-        "__waygraphSalt",
-        "__waygraphNavUrl",
-        "__waygraphNavClick",
-    ]) {
-        const desc = Object.getOwnPropertyDescriptor(from, key);
-        if (!desc)
-            continue;
-        // Re-define as configurable so later decorate chains can copy again
-        // (factory markers are non-configurable on the original).
-        Object.defineProperty(to, key, {
-            value: desc.value,
-            enumerable: false,
-            writable: false,
-            configurable: true,
-        });
-    }
-    const ff = from.fastForward;
-    if (ff === true) {
-        to.fastForward = true;
-    }
-    const pace = from.demoPace;
-    if (pace !== undefined) {
-        to.demoPace = pace;
-    }
-}
-/**
- * Builds a Block with `withVerify`/`modVerify`/`modVerifyAll` attached as
- * methods - `LoginBlock.withVerify([...])`, discoverable by typing
- * `LoginBlock.` in an editor, not just callable as `withVerify(LoginBlock, ...)`
- * if you already know it exists. A raw object literal is still a perfectly
- * valid Block (every test fixture in this codebase is one) - it just won't have
- * these attached. The methods are thin: they delegate to the identically-named
- * free functions, which remain the one place this logic actually lives.
- */
-export function defineBlock(base) {
-    const plain = {
-        name: base.name,
-        instruction: base.instruction,
-        ...(base.description ? { description: base.description } : {}),
-        ...(base.next ? { next: base.next } : {}),
-        ...(base.requires ? { requires: base.requires } : {}),
-        ...(base.routes ? { routes: base.routes } : {}),
-        ...(base.instanceOptions ? { instanceOptions: base.instanceOptions } : {}),
-    };
-    // Methods must close over `defined` (this object), not `plain` - factories
-    // attach __waygraphKind/__waygraphSalt on the returned object after
-    // defineBlock returns; decorate/withVerify need those markers.
-    const defined = {
-        ...plain,
-        withVerify: (verify) => withVerify(defined, verify),
-        modVerify: (nameOrIndex, newCheck) => modVerify(defined, nameOrIndex, newCheck),
-        modVerifyAll: (patches) => modVerifyAll(defined, patches),
-        stubBefore: (stub) => withStubBefore(defined, stub),
-        stubAfter: (stub) => withStubAfter(defined, stub),
-        stubOnError: (stub) => withStubOnError(defined, stub),
-    };
-    return defined;
-}
-/**
- * Builds a {@link NavBlock}. The generated `act()` is always exactly
- * `page.goto(url)` or `page.locator(click).click()` - never anything else,
- * never author-supplied. Callers get a real `Page` here internally (the one
- * legitimate place navigation belongs); `defineBlock`'s own `ActionPage`
- * narrowing is what discourages navigation everywhere else, and never
- * applies to this generated function since no author ever writes it by
- * hand.
- * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
- * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
- * @example defineNavClickBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
- * For click-nav in app code prefer {@link defineNavClickBlock} (url stays here).
- */
-export function defineNavBlock(options) {
-    const built = defineBlock({
-        name: options.name,
-        ...(options.description ? { description: options.description } : {}),
-        ...(options.requires ? { requires: options.requires } : {}),
-        ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
-        instruction: {
-            async act(page, _input, mem) {
-                if (options.url !== undefined) {
-                    const url = typeof options.url === "function" ? options.url(mem) : options.url;
-                    await page.goto(url);
-                }
-                else {
-                    // Always Locator.click() so step-mode's demo cursor/pulse patch
-                    // (instrumentInteractionHighlighting) sees NavBlock click-nav -
-                    // never page.click() / goto teleport.
-                    const selector = typeof options.click === "function" ? options.click(mem) : options.click;
-                    await page.locator(selector).click();
-                }
-            },
-            resolve: () => checkpoint(options.checkpoint),
-            ...(options.verify ? { verify: options.verify } : {}),
-            ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
-            ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
-            ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
-            ...(options.highlights ? { highlights: options.highlights } : {}),
-        },
-    });
-    // Non-enumerable so it never shows up in Object.keys/JSON/autocomplete -
-    // purely a runtime marker `waygraph check` (or anything else walking a
-    // project's Blocks) can test for to tell a NavBlock apart from a regular
-    // one, since the TypeScript type alone (NavBlock = DefinedBlock) doesn't
-    // survive to runtime.
-    Object.defineProperty(built, "__waygraphKind", {
-        value: "nav",
-        enumerable: false,
-        configurable: false,
-    });
-    // Demo/step tooling: remember the click selector (or factory) so
-    // overlays can label "nav click" without re-parsing source.
-    if (options.click !== undefined) {
-        Object.defineProperty(built, "__waygraphNavClick", {
-            value: options.click,
-            enumerable: false,
-            configurable: false,
-        });
-    }
-    // Same idea, for the url case - only when it's a plain string (a
-    // function URL is mem-dependent/dynamic, can't be compared statically
-    // without running it). Real, direct request this responds to: an agent
-    // driving Blind Pilot had no structured way to ask "which of the links
-    // on THIS page are already covered by a NavBlock" without re-parsing
-    // every nav.block.ts's own source - this is what `AutoSession` now reads
-    // to warn about real, unmapped nav links found live on the page.
-    if (typeof options.url === "string") {
-        Object.defineProperty(built, "__waygraphNavUrl", {
-            value: options.url,
-            enumerable: false,
-            configurable: false,
-        });
-    }
-    return built;
-}
-/** @see {@link NavClickBlockOptions} */
-export function defineNavClickBlock(options) {
-    return defineNavBlock({
-        name: options.name,
-        checkpoint: options.checkpoint,
-        click: options.click,
-        ...(options.description ? { description: options.description } : {}),
-        ...(options.requires ? { requires: options.requires } : {}),
-        ...(options.verify ? { verify: options.verify } : {}),
-        ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
-        ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
-        ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
-        ...(options.highlights ? { highlights: options.highlights } : {}),
-        ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
-    });
-}
-export function defineMethodBlock(base) {
-    const built = defineBlock(base);
-    Object.defineProperty(built, "__waygraphSalt", {
-        value: "method",
-        enumerable: false,
-        configurable: false,
-    });
-    return built;
-}
-/** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
-export const defineActionBlock = defineMethodBlock;
-/**
- * Sugar for a self-loop-only "pure assertion" Block: no hand-written
- * `act`/`resolve`, just a name, a `checkpoint` tag, and a `verify` array.
- * `resolve` is generated from the one `checkpoint` field given, closing the
- * copy/rename footgun where a hand-restated checkpoint string can silently
- * drift wrong across a copy/pasted file. Mirrors `definePageBlock`'s own
- * construction pattern (flat options in, `defineBlock` built internally).
- * See openspec/changes/waygraph-agent-skill-hardening/spec.md.
- * @example
- * defineAssertBlock({
- *   name: "assert-raw-materials-table",
- *   checkpoint: "RawMaterials",
- *   waitForHeading: "Raw Materials & Lead Times",
- *   verify: [Trait.visible(RawMaterialsSel.reorderBadge)],
- * });
- */
-export function defineAssertBlock(options) {
-    const built = defineMethodBlock({
-        name: options.name,
-        ...(options.description ? { description: options.description } : {}),
-        ...(options.requires ? { requires: options.requires } : {}),
-        instruction: {
-            async act(page) {
-                if (options.waitForHeading !== undefined) {
-                    await page.getByRole("heading", { name: options.waitForHeading }).waitFor();
-                }
-            },
-            resolve: () => checkpoint(options.checkpoint),
-            verify: options.verify,
-            ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
-            ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
-            ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
-            ...(options.slides ? { slides: options.slides } : {}),
-        },
-    });
-    // Real bug this closes: `waygraph graph`'s static discovery only knows
-    // how to read a Block's Checkpoint tags from an EXPLICIT `<In, Out>`
-    // generic written in the source text (or, for Nav/Page Blocks, by calling
-    // their own input-independent `resolve()` directly). `defineAssertBlock`'s
-    // whole point is skipping that generic - called exactly as documented
-    // (`defineAssertBlock({ name, checkpoint, verify })`, no generics), it was
-    // silently invisible to both `waygraph graph` and the live Pilot menu
-    // ("2 Block(s) skipped (Out not resolvable)", confirmed live against a
-    // real veciro-waygraph session). `resolve()` here is ALSO input-
-    // independent (always `checkpoint(options.checkpoint)`), so the same
-    // resolve()-calling path Nav/Page Blocks already use is reused via this
-    // marker instead of requiring authors to write generics just to be found.
-    Object.defineProperty(built, "__waygraphKind", {
-        value: "assert",
-        enumerable: false,
-        configurable: false,
-    });
-    // Brand for map().assert() - distinct from MethodBlock so .method(assert)
-    // is a compile error even though runtime still carries method salt.
-    return built;
-}
-function resolvePageMethods(methods) {
-    if (!methods)
-        return [];
-    const entries = Array.isArray(methods) ? methods : Object.values(methods);
-    return entries.map((entry) => (typeof entry === "function" ? entry() : entry));
-}
-/** @see {@link PageBlockOptions} */
-export function definePageBlock(options) {
-    if (options.url !== undefined && options.click !== undefined) {
-        throw new Error(`definePageBlock("${options.name}"): pass url XOR click (or neither for arrival-only hub)`);
-    }
-    const methodList = resolvePageMethods(options.methods);
-    const built = defineBlock({
-        name: options.name,
-        ...(options.description ? { description: options.description } : {}),
-        ...(options.requires ? { requires: options.requires } : {}),
-        ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
-        instruction: {
-            async act(page, _input, mem) {
-                if (options.url !== undefined) {
-                    const url = typeof options.url === "function" ? options.url(mem) : options.url;
-                    await page.goto(url);
-                }
-                else if (options.click !== undefined) {
-                    const selector = typeof options.click === "function" ? options.click(mem) : options.click;
-                    await page.locator(selector).click();
-                }
-                // else: arrival-only hub — previous Block already landed here
-            },
-            resolve: () => checkpoint(options.checkpoint),
-            ...(options.verify ? { verify: options.verify } : {}),
-            ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
-            ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
-            ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
-            ...(options.highlights ? { highlights: options.highlights } : {}),
-        },
-    });
-    Object.defineProperty(built, "__waygraphKind", {
-        value: "page",
-        enumerable: false,
-        configurable: false,
-    });
-    Object.defineProperty(built, "__waygraphSalt", {
-        value: "page",
-        enumerable: false,
-        configurable: false,
-    });
-    Object.defineProperty(built, "methods", {
-        value: Object.freeze([...methodList]),
-        enumerable: true,
-        configurable: false,
-        writable: false,
-    });
-    Object.defineProperty(built, "__waygraphMethods", {
-        value: methodList.map((m) => m.name),
-        enumerable: false,
-        configurable: false,
-    });
-    // Same marker `defineNavBlock` sets, same reason - a page hub with a
-    // `url` (deep-link) is exactly as "known, coverable" as a plain
-    // `defineNavBlock`, and in practice most real projects' own nav Blocks
-    // ARE page hubs (methods hanging off them), not bare NavBlocks - the real
-    // saucedemo fixture this whole package tests against uses definePageBlock
-    // for every one of its own nav-* Blocks. Missing this here meant the
-    // marker existed but was never actually set on any real project's Blocks.
-    if (typeof options.url === "string") {
-        Object.defineProperty(built, "__waygraphNavUrl", {
-            value: options.url,
-            enumerable: false,
-            configurable: false,
-        });
-    }
-    if (options.url !== undefined || options.click !== undefined) {
-        Object.defineProperty(built, "__waygraphPageDeepLink", {
-            value: true,
-            enumerable: false,
-            configurable: false,
-        });
-    }
-    if (options.click !== undefined) {
-        Object.defineProperty(built, "__waygraphNavClick", {
-            value: options.click,
-            enumerable: false,
-            configurable: false,
-        });
-    }
-    return built;
-}
-/**
- * {@link defineBlock} constrained for effect-style instance menus: `requires` +
- * `instanceOptions` are mandatory. Prefer this when the Block adds / removes /
- * toggles a live instance rather than navigating. Runtime result is an ordinary
- * Block - the helper is TypeScript salt only.
- */
-export function defineEffectBlock(base) {
-    const built = defineBlock(base);
-    Object.defineProperty(built, "__waygraphMemKind", {
-        value: "effect",
-        enumerable: false,
-        configurable: false,
-    });
-    Object.defineProperty(built, "__waygraphSalt", {
-        value: "effect",
-        enumerable: false,
-        configurable: false,
-    });
-    return built;
-}
-/** @deprecated Prefer {@link defineEffectBlock} - identical helper. */
-export const defineMemEffectBlock = defineEffectBlock;
-/**
- * {@link defineNavBlock} constrained to mem-picked navigation: requires +
- * instanceOptions mandatory, and `click`/`url` should depend on that mem
- * (typically `click: (mem) => …`). Prefer this when the Block opens one of
- * several live rows/items rather than a fixed nav target. Still a Block.
- */
-export function defineMemNavBlock(options) {
-    const built = defineNavBlock(options);
-    Object.defineProperty(built, "__waygraphMemKind", {
-        value: "nav",
-        enumerable: false,
-        configurable: false,
-    });
-    return built;
-}
-/**
- * "Where am I" - reverse-matches a live `page` against every NavBlock /
- * PageBlock in `library`, in order, returning the first one whose own `verify`
- * Traits all pass (its `checkpoint`), or `null` if none match. Deliberately
- * Nav/Page hubs only: each has exactly one fixed `checkpoint` and a `verify`
- * list whose whole job is already "confirm arrival here," so it's a reliable
- * fingerprint - a regular `defineBlock` can branch to different `Out` tags
- * depending on runtime evidence, so its `verify` alone doesn't identify a
- * single state the way a hub's does.
- *
- * The primitive `waygraph auto`'s discovered graph is *for* - the graph says
- * what pages exist and how to reach them; `locate()` is how an autonomous
- * run figures out which one it's actually looking at right now, without a
- * human telling it.
- *
- * More than one NavBlock matching is a real possibility (two Checkpoints
- * whose `verify` Traits are both satisfied by the same page) - `locate()`
- * returns the first match rather than treating that as an error; resolving
- * genuine ambiguity is a follow-up, not solved here.
- * @example const here = await locate(page, [NavLoginBlock, NavDashboardBlock]);
- */
-export async function locate(page, library, options) {
-    const mem = new MemPage();
-    const timeoutMs = options?.timeoutMs;
-    if (timeoutMs !== undefined) {
-        page.setDefaultTimeout(timeoutMs);
-    }
-    try {
-        for (const block of library) {
-            try {
-                // NavBlock's own resolve() ignores whatever it's called with - always
-                // exactly `checkpoint(options.checkpoint)` - so this is safe to call
-                // before verify, unlike a regular Block where resolve depends on
-                // observed evidence.
-                const resolved = await block.instruction.resolve(undefined);
-                const verify = block.instruction.verify;
-                const traits = typeof verify === "function" ? verify(resolved) : (verify ?? []);
-                let allPass = true;
-                for (const trait of traits) {
-                    // eslint-disable-next-line no-await-in-loop
-                    if (!(await trait.check(page, mem))) {
-                        allPass = false;
-                        break;
-                    }
-                }
-                if (allPass)
-                    return resolved.__state;
-            }
-            catch {
-                // This NavBlock's own verify threw (e.g. a waitFor timing out) -
-                // treat that the same as "didn't match," try the next candidate.
-            }
-        }
-        return null;
-    }
-    finally {
-        if (timeoutMs !== undefined) {
-            page.setDefaultTimeout(30_000);
-        }
-    }
-}
-/**
- * Returns a new Block that runs exactly like `block` - same act/observe/resolve,
- * same routing - but with `verify` replaced. For giving one flow stricter (or
- * looser, or just different) confirmation on a Block it didn't author, without
- * that Block needing to have been written as a parameterized factory in
- * anticipation. Same move as `branch()`: decorate an existing Block, don't ask
- * every Block to pre-build its own override mechanism.
- *
- * Wrap the one Block you want to change, in place, wherever it already sits in
- * a `defineFlow([...])` array - every other Block stays untouched:
- * `defineFlow([start, LoginBlock, withVerify(AddToCartBlock, [...]), end])`.
- * There is no separate positional array to keep in sync and no `null`
- * placeholder for "skip this one" - `defineFlow` has no per-slot verify
- * argument at all, only whatever `verify` each Block's own `instruction` (or
- * a `withVerify(...)` wrapping it) carries with it.
- */
-export function withVerify(block, verify) {
-    const base = stripMethods(block);
-    const next = defineBlock({ ...base, instruction: { ...base.instruction, verify } });
-    copyWaygraphRuntime(block, next);
-    return next;
-}
-function isHighlightStubPhase(v) {
-    return !!v && typeof v === "object" && !Array.isArray(v);
-}
-/** Run a prior stub (fn or slot map) into an open ctx so decorate can chain. */
-async function applyStubIntoCtx(raw, ctx) {
-    if (raw === undefined)
-        return;
-    if (typeof raw === "function") {
-        const ret = await raw(ctx);
-        if (isHighlightStubPhase(ret)) {
-            for (const [id, stub] of Object.entries(ret)) {
-                if (stub)
-                    ctx.ring(id, stub);
-            }
-        }
-        return;
-    }
-    if (isHighlightStubPhase(raw)) {
-        for (const [id, stub] of Object.entries(raw)) {
-            if (stub)
-                ctx.ring(id, stub);
-        }
-    }
-}
-function withStubPhase(block, phase, stub) {
-    const base = stripMethods(block);
-    const instr = base.instruction;
-    const prev = instr[phase];
-    const chained = async (ctx) => {
-        await applyStubIntoCtx(prev, ctx);
-        await applyStubIntoCtx(stub, ctx);
-    };
-    const next = defineBlock({
-        ...base,
-        instruction: { ...base.instruction, [phase]: chained },
-    });
-    copyWaygraphRuntime(block, next);
-    return next;
-}
-/**
- * Attach / chain a stubBefore lifecycle on a Block. Prefer
- * `(ctx) => { ctx.ring(...); const x = ctx.mem?.get(Key); }`.
- * @example FillUsernameBlock.stubBefore((ctx) => { ctx.ring("username", { ... }) })
- */
-export function withStubBefore(block, stub) {
-    return withStubPhase(block, "stubBefore", stub);
-}
-/** @see {@link withStubBefore} */
-export function withStubAfter(block, stub) {
-    return withStubPhase(block, "stubAfter", stub);
-}
-/** @see {@link withStubBefore} */
-export function withStubOnError(block, stub) {
-    return withStubPhase(block, "stubOnError", stub);
-}
-/**
- * Replaces one Trait inside `block`'s verify list, leaving every other check
- * untouched - the v1/v2/legacy-variant case, where one check needs a different
- * selector or URL pattern but the rest of the Block is identical. Addressed by
- * the Trait's own `name` (recommended - inserting or reordering other checks
- * can't silently retarget it) or, if you genuinely know the position and don't
- * need that safety, a numeric index. Either way a bad address fails loud
- * immediately instead of quietly doing nothing. `newCheck` can be a bare
- * `check` function (keeps the existing name) or a full `Trait` (to rename too).
- * Only works on a flat `verify` array - a function-form `verify` (from
- * `verify: (out) => Trait[]`) has no fixed list to address into, so this
- * throws rather than guess; use `withVerify` to replace it wholesale instead.
- */
-export function modVerify(block, nameOrIndex, newCheck) {
-    const verify = block.instruction.verify;
-    if (typeof verify === "function") {
-        throw new Error(`modVerify: "${block.name}" has a function-form verify, which has no fixed list to address into - use withVerify to replace it wholesale instead`);
-    }
-    const traits = verify ?? [];
-    const index = typeof nameOrIndex === "number" ? nameOrIndex : traits.findIndex((t) => t.name === nameOrIndex);
-    const existing = traits[index];
-    if (!existing) {
-        throw new Error(typeof nameOrIndex === "number"
-            ? `modVerify: "${block.name}" has no verify trait at index ${nameOrIndex} (has ${traits.length})`
-            : `modVerify: "${block.name}" has no verify trait named "${nameOrIndex}" (has: ${traits.map((t) => t.name).join(", ") || "none"})`);
-    }
-    const replacement = typeof newCheck === "function"
-        ? { name: typeof nameOrIndex === "string" ? nameOrIndex : existing.name, check: newCheck }
-        : newCheck;
-    const updated = [...traits];
-    updated[index] = replacement;
-    return withVerify(block, updated);
-}
-/**
- * `modVerify`, but for several named checks in one call - a v2 variant that
- * differs in five ways from v1 shouldn't need five nested `modVerify(modVerify(
- * modVerify(...)))` calls to track by eye. `patches` keys are plain strings (a
- * Trait's `name`, not a `MemKey` instance), so an ordinary object literal is
- * fine here - unlike `MemPage`, there's no identity-collision reason to need
- * `[name, check]` pairs. Applies each patch in turn via `modVerify`, so the
- * same fail-loud-on-unknown-name behavior holds for every entry.
- */
-export function modVerifyAll(block, patches) {
-    const seed = defineBlock(stripMethods(block));
-    copyWaygraphRuntime(block, seed);
-    return Object.entries(patches).reduce((current, [name, newCheck]) => modVerify(current, name, newCheck), seed);
-}
+// Barrel: the engine lives in src/engine/ (see src/ARCHITECTURE.md). Kept so existing imports of "./engine.js" don't change.
+export * from "./engine/config.js";
+export * from "./engine/run-graph.js";
+export * from "./engine/flow.js";
+export * from "./engine/core.js";
+export * from "./engine/compose.js";
+export * from "./engine/engine-class.js";
+export * from "./engine/blocks/nav.js";
+export * from "./engine/blocks/method.js";
+export * from "./engine/blocks/page.js";
+export * from "./engine/blocks/effect.js";
+export * from "./engine/locate.js";