waygraph 0.15.47 → 0.15.50

package/dist/{engine → core}/blocks/method.js

@@ -1,6 +1,6 @@
 // Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { checkpoint } from "../../types.js";
-import { defineBlock } from "../core.js";
+import { defineBlock } from "../block.js";
 export function defineMethodBlock(base) {
     const built = defineBlock(base);
     Object.defineProperty(built, "__waygraphSalt", {

package/dist/{engine → core}/blocks/nav.js

@@ -1,6 +1,6 @@
 // Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { checkpoint } from "../../types.js";
-import { defineBlock } from "../core.js";
+import { defineBlock } from "../block.js";
 /**
  * Builds a {@link NavBlock}. The generated `act()` is always exactly
  * `page.goto(url)` or `page.locator(click).click()` - never anything else,

package/dist/{engine → core}/blocks/page.js

@@ -1,6 +1,6 @@
 // Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { checkpoint } from "../../types.js";
-import { defineBlock } from "../core.js";
+import { defineBlock } from "../block.js";
 function resolvePageMethods(methods) {
     if (!methods)
         return [];

package/dist/{engine → core}/branch-regression.js

@@ -1,4 +1,4 @@
-import { WaygraphError } from "../errors.js";
+import { WaygraphError, MSG_BRANCH_REGRESSION_NO_BROWSER } from "../errors.js";
 import { MemPage } from "../mem-page.js";
 import { seedMemStub } from "../mem-stub.js";
 function branchInfo(flow) {
@@ -48,8 +48,7 @@ export async function runBranchRegression(flow, context, mem = new MemPage(), op
     const results = [];
     const browser = cloneSession ? context.browser() : null;
     if (cloneSession && !browser) {
-        throw new WaygraphError("WG_BRANCH_REGRESSION_NO_BROWSER", "Waygraph runBranchRegression: cloneSession needs context.browser() (a persistent context " +
-            "has none) - pass { cloneSession: false } to run the single live path in this context instead.");
+        throw new WaygraphError("WG_BRANCH_REGRESSION_NO_BROWSER", MSG_BRANCH_REGRESSION_NO_BROWSER);
     }
     /** `entryPage`, when given, is already positioned (cloned session + navigated) - reused as-is,
      *  never replaced by a fresh `ctx.newPage()` (that would throw away the whole point of cloning). */

package/dist/{engine → core}/compose.js

@@ -1,9 +1,9 @@
 import { connect } from "../types.js";
-import { WaygraphError } from "../errors.js";
-import { findBlockIndex, modVerify, withVerify } from "./core.js";
+import { WaygraphError, MSG_COMPOSE_EMPTY, MSG_FASTFORWARD_EMPTY } from "../errors.js";
+import { findBlockIndex, modVerify, withVerify } from "./block.js";
 export function composeBlock(name, steps) {
     if (steps.length === 0) {
-        throw new WaygraphError("WG_COMPOSE_EMPTY", `composeBlock: "${name}" needs at least one step`);
+        throw new WaygraphError("WG_COMPOSE_EMPTY", MSG_COMPOSE_EMPTY(name));
     }
     const chain = steps.reduce((a, b) => connect(a, b));
     return {
@@ -42,7 +42,7 @@ function wrapFfError(ffName, err) {
 }
 export function fastForwardComposeBlock(name, steps) {
     if (steps.length === 0) {
-        throw new WaygraphError("WG_FASTFORWARD_EMPTY", `fastForwardComposeBlock: "${name}" needs at least one step`);
+        throw new WaygraphError("WG_FASTFORWARD_EMPTY", MSG_FASTFORWARD_EMPTY(name));
     }
     const base = composeBlock(name, steps);
     const origAct = base.instruction.act.bind(base.instruction);

package/dist/{engine/engine-class.d.ts → core/engine.d.ts}

@@ -2,10 +2,8 @@ import type { Block, Checkpoint } from "../types.js";
 import type { EngineConfig } from "./config.js";
 import type { EndMarker, StartMarker } from "./run-graph.js";
 import type { Flow } from "./flow.js";
-import type { NavBlock } from "./blocks/nav.js";
-import type { PageBlock } from "./blocks/page.js";
-import type { AssertBlock, MethodBlock } from "./blocks/method.js";
-import type { EffectBlock } from "./blocks/effect.js";
+import { MapBuilder } from "./map-builder.js";
+import type { MapBuilderOptions } from "./map-builder.js";
 type S = Checkpoint<"__start__">;
 /**
  * Holds engine-level configuration shared across every flow defined from it -
@@ -187,135 +185,6 @@ export declare class Engine {
      */
     map(options?: MapBuilderOptions): MapBuilder<S>;
 }
-export interface MapBuilderOptions {
-    /**
-     * This project's own origin (e.g. `"https://app.example.com"`) - enables
-     * `.gotoPage()`/`.gotoExternal()`'s origin check against a Block's static
-     * `url`. Omit to skip that check entirely (still fully kind-checked either
-     * way; only the internal/external origin distinction is opt-in).
-     */
-    homeOrigin?: string;
-}
-/**
- * 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 declare class MapBuilder<Out extends Checkpoint<string>> {
-    private readonly engine;
-    private readonly steps;
-    private readonly homeOrigin;
-    private readonly ff;
-    private constructor();
-    /** @internal - use `engine.map()` or the standalone `map()` export. */
-    static begin(engine: Engine, homeOrigin: string | undefined): MapBuilder<S>;
-    /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
-    start(): MapBuilder<Out>;
-    /**
-     * 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?: string): MapBuilder<Out>;
-    /**
-     * Close the current fast-forward window and append one FFCompose step.
-     * Throws if empty or if {@link ffStart} was never opened.
-     */
-    ffEnd(): MapBuilder<Out>;
-    private appendStep;
-    /**
-     * 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<NextOut extends Checkpoint<string>>(block: (NavBlock<NextOut> | PageBlock<NextOut>) & {
-        name: string;
-    }): MapBuilder<NextOut>;
-    /**
-     * 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<NextOut extends Checkpoint<string>>(block: (NavBlock<NextOut> | PageBlock<NextOut>) & {
-        name: string;
-    }): MapBuilder<NextOut>;
-    /**
-     * Appends a self-loop verification step - requires a Block from
-     * `defineAssertBlock`. Compile-time: {@link AssertBlock} only (not `.method()`).
-     */
-    assert(block: AssertBlock<Out> & {
-        name: string;
-    }): MapBuilder<Out>;
-    /**
-     * 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<NextOut extends Checkpoint<string>>(block: (MethodBlock<Out, NextOut> | EffectBlock<Out, NextOut>) & {
-        name: string;
-    }): MapBuilder<NextOut>;
-    /**
-     * Branch: run everything added so far, then continue into whichever `routes[tag]` matches the
-     * resolved Checkpoint's tag - same page, same context, same mem. `routes` must cover every tag
-     * of `Out` (a missing one is a compile error, matching {@link branch}'s own exhaustiveness);
-     * `null` means that tag is terminal (the branched Flow just returns that Checkpoint).
-     *
-     * Each non-null route is a function, not a ready-made `Flow` - a fresh Flow always starts at the
-     * special `S` (start) Checkpoint, but a branch's blocks start from the TAG it routes on (e.g.
-     * `LoggedIn`), so the function is handed a brand-new `MapBuilder` already seeded at that exact
-     * Checkpoint to chain `.method()/.gotoPage()/.assert()/.end()` (or another `.branch()`) off of.
-     *
-     * Real gap this fixes: the plain `branch()` helper's `.next` routing is only ever consulted by
-     * `runGraph`'s own graph walk - `defineFlow`/`.end()` compose steps pairwise via `connect()`,
-     * which never looks at `.next` at all, so a Map-built Flow had no way to branch. This method
-     * branches at the Flow level instead: it finalizes the prefix, runs it, and picks the next Flow
-     * itself once the real tag is known - no engine-level routing involved.
-     *
-     * Only the `run(context, mem[, options])` signature is supported - the page must survive across
-     * the branch, and the bare `run(mem, config)` convenience form always closes its own browser
-     * before a tag is even known, so it throws instead of silently reopening a fresh (state-losing) page.
-     *
-     * The route's first Block still sees `input.__state === "__start__"` in `act()`, not the tag that
-     * routed there - `runGraph` seeds every Flow's entry Block that way unconditionally, the same as
-     * any standalone `defineFlow([start, block, end])` already does. Read `page`/`mem`, not `input`,
-     * in `act()` - every real Block in this codebase already follows that convention.
-     *
-     * @example
-     * map({ homeOrigin }).gotoPage(NavCartBlock).branch({
-     *   ItemInCart: (m) => m.method(RemoveFromCartBlock).end(),
-     *   LoggedIn: (m) => m.method(AddToCartBlock).end(),
-     * });
-     */
-    branch<Routes extends {
-        [K in Out["__state"]]: ((m: MapBuilder<Extract<Out, Checkpoint<K>>>) => Flow<any>) | null;
-    }>(routes: Routes): Flow<{
-        [K in keyof Routes & string]: Routes[K] extends (m: any) => Flow<infer R> ? R : Extract<Out, Checkpoint<K>>;
-    }[keyof Routes & string]>;
-    /**
-     * 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(): Flow<Out>;
-}
 /**
  * Standalone convenience for `new Engine(config).map(options)` - use this
  * when a call site doesn't otherwise need its own `Engine` instance (no

package/dist/core/engine.js

@@ -0,0 +1,50 @@
+import { buildFlow } from "./flow.js";
+import { MapBuilder } from "./map-builder.js";
+/**
+ * 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.defineFlow.bind(this), options?.homeOrigin);
+    }
+}
+/**
+ * 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);
+}

package/dist/{engine → core}/flow.js

@@ -1,10 +1,10 @@
 // Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { connect } from "../types.js";
-import { WaygraphError } from "../errors.js";
+import { WaygraphError, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_CHAINFLOW_EMPTY, } from "../errors.js";
 import { preflight, runGraph } from "./run-graph.js";
 import { resolveLauncher } from "./config.js";
 import { MemPage } from "../mem-page.js";
-import { findBlockIndex, modVerify, withVerify } from "./core.js";
+import { findBlockIndex, modVerify, withVerify } from "./block.js";
 import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../highlights.js";
 export function buildFlow(middle, engineConfig) {
     // resetSession/title start false/unset here - defineFlow itself carries
@@ -268,7 +268,7 @@ function locateInChain(flows, block) {
                 return { flowIndex: fi, localIndex: remaining };
             remaining -= len;
         }
-        throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", `chainFlow: no Block at index ${block} across ${flows.length} chained flows`);
+        throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_INDEX(block, flows.length));
     }
     const blockName = typeof block === "string" ? block : block.name;
     for (let fi = 0; fi < flows.length; fi++) {
@@ -276,7 +276,7 @@ function locateInChain(flows, block) {
         if (localIndex !== -1)
             return { flowIndex: fi, localIndex };
     }
-    throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", `chainFlow: no Block named "${blockName}" in any chained flow`);
+    throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME(blockName));
 }
 async function clearSessionState(context, page) {
     await context.clearCookies().catch(() => { });
@@ -312,7 +312,7 @@ async function clearSessionState(context, page) {
  */
 export function chainFlow(...flows) {
     if (flows.length === 0) {
-        throw new WaygraphError("WG_CHAINFLOW_EMPTY", "chainFlow: give at least one Flow");
+        throw new WaygraphError("WG_CHAINFLOW_EMPTY", MSG_CHAINFLOW_EMPTY);
     }
     const run = async function run(contextOrMem, memOrConfig, options) {
         if (contextOrMem instanceof MemPage) {

package/dist/core/map-builder.d.ts

@@ -0,0 +1,171 @@
+import type { Block, Checkpoint } from "../types.js";
+import type { EndMarker, StartMarker } from "./run-graph.js";
+import type { Flow } from "./flow.js";
+import type { NavBlock } from "./blocks/nav.js";
+import type { PageBlock } from "./blocks/page.js";
+import type { AssertBlock, MethodBlock } from "./blocks/method.js";
+import type { EffectBlock } from "./blocks/effect.js";
+type S = Checkpoint<"__start__">;
+/**
+ * The one capability MapBuilder needs from Engine - a plain defineFlow-shaped function, not the
+ * whole Engine class. Depending on Engine-the-type here would make engine.ts and map-builder.ts
+ * import each other (Engine.map() builds a MapBuilder; MapBuilder.end() calls back into
+ * defineFlow) - a real cycle check:structure forbids. This type is how that's avoided.
+ */
+export type DefineFlowFn = (blocks: readonly [StartMarker, ...Block<any, any>[], EndMarker]) => Flow<any>;
+/** Per-step options every `MapBuilder` step method (`.gotoPage()`/`.method()`/`.assert()`) takes. */
+export interface MapStepOpts {
+    /**
+     * Fast-forward just this step, inline - no `.ffStart()/.ffEnd()` bracket needed. Consecutive
+     * `{ ff: true }` steps merge into ONE fast-forward block, same result as the explicit bracket
+     * form; a step without the flag closes an auto-opened window first.
+     * @example map().gotoPage(NavLoginBlock, { ff: true }).method(FillUsernameBlock, { ff: true })
+     */
+    ff?: boolean;
+}
+export interface MapBuilderOptions {
+    /**
+     * This project's own origin (e.g. `"https://app.example.com"`) - enables
+     * `.gotoPage()`/`.gotoExternal()`'s origin check against a Block's static
+     * `url`. Omit to skip that check entirely (still fully kind-checked either
+     * way; only the internal/external origin distinction is opt-in).
+     */
+    homeOrigin?: string;
+}
+/**
+ * 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 declare class MapBuilder<Out extends Checkpoint<string>> {
+    private readonly defineFlow;
+    private readonly steps;
+    private readonly homeOrigin;
+    private readonly ff;
+    private constructor();
+    /** @internal - use `engine.map()` or the standalone `map()` export. */
+    static begin(defineFlow: DefineFlowFn, homeOrigin: string | undefined): MapBuilder<S>;
+    /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
+    start(): MapBuilder<Out>;
+    /**
+     * 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?: string): MapBuilder<Out>;
+    /**
+     * Close the current fast-forward window and append one FFCompose step.
+     * Throws if empty or if {@link ffStart} was never opened.
+     */
+    ffEnd(): MapBuilder<Out>;
+    /** Shared by the explicit {@link ffEnd} and the implicit close a `{ ff: true }` step flag triggers. */
+    private closeFf;
+    /**
+     * `ff`: inline fast-forward, no `.ffStart()/.ffEnd()` bracket needed - `.method(X, { ff: true })`
+     * marks just that step; consecutive `{ ff: true }` steps merge into ONE fast-forward block (same
+     * runtime result as the explicit bracket form), same as if they'd been wrapped in
+     * `.ffStart()/.ffEnd()`. A step WITHOUT the flag closes an auto-opened window first, so a plain
+     * step is never silently swept into one; an EXPLICIT `.ffStart()` window still behaves as before
+     * (stays open until its own `.ffEnd()`, regardless of whether a step passed `{ ff: true }`).
+     */
+    private appendStep;
+    /**
+     * 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).
+     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
+     */
+    gotoPage<NextOut extends Checkpoint<string>>(block: (NavBlock<NextOut> | PageBlock<NextOut>) & {
+        name: string;
+    }, opts?: MapStepOpts): MapBuilder<NextOut>;
+    /**
+     * 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.
+     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
+     */
+    gotoExternal<NextOut extends Checkpoint<string>>(block: (NavBlock<NextOut> | PageBlock<NextOut>) & {
+        name: string;
+    }, opts?: MapStepOpts): MapBuilder<NextOut>;
+    /**
+     * Appends a self-loop verification step - requires a Block from
+     * `defineAssertBlock`. Compile-time: {@link AssertBlock} only (not `.method()`).
+     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
+     */
+    assert(block: AssertBlock<Out> & {
+        name: string;
+    }, opts?: MapStepOpts): MapBuilder<Out>;
+    /**
+     * 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).
+     * `{ ff: true }`: fast-forward this one step inline - see {@link appendStep}'s own comment.
+     */
+    method<NextOut extends Checkpoint<string>>(block: (MethodBlock<Out, NextOut> | EffectBlock<Out, NextOut>) & {
+        name: string;
+    }, opts?: MapStepOpts): MapBuilder<NextOut>;
+    /**
+     * Branch: run everything added so far, then continue into whichever `routes[tag]` matches the
+     * resolved Checkpoint's tag - same page, same context, same mem. `routes` must cover every tag
+     * of `Out` (a missing one is a compile error, matching {@link branch}'s own exhaustiveness);
+     * `null` means that tag is terminal (the branched Flow just returns that Checkpoint).
+     *
+     * Each non-null route is a function, not a ready-made `Flow` - a fresh Flow always starts at the
+     * special `S` (start) Checkpoint, but a branch's blocks start from the TAG it routes on (e.g.
+     * `LoggedIn`), so the function is handed a brand-new `MapBuilder` already seeded at that exact
+     * Checkpoint to chain `.method()/.gotoPage()/.assert()/.end()` (or another `.branch()`) off of.
+     *
+     * Real gap this fixes: the plain `branch()` helper's `.next` routing is only ever consulted by
+     * `runGraph`'s own graph walk - `defineFlow`/`.end()` compose steps pairwise via `connect()`,
+     * which never looks at `.next` at all, so a Map-built Flow had no way to branch. This method
+     * branches at the Flow level instead: it finalizes the prefix, runs it, and picks the next Flow
+     * itself once the real tag is known - no engine-level routing involved.
+     *
+     * Only the `run(context, mem[, options])` signature is supported - the page must survive across
+     * the branch, and the bare `run(mem, config)` convenience form always closes its own browser
+     * before a tag is even known, so it throws instead of silently reopening a fresh (state-losing) page.
+     *
+     * The route's first Block still sees `input.__state === "__start__"` in `act()`, not the tag that
+     * routed there - `runGraph` seeds every Flow's entry Block that way unconditionally, the same as
+     * any standalone `defineFlow([start, block, end])` already does. Read `page`/`mem`, not `input`,
+     * in `act()` - every real Block in this codebase already follows that convention.
+     *
+     * @example
+     * map({ homeOrigin }).gotoPage(NavCartBlock).branch({
+     *   ItemInCart: (m) => m.method(RemoveFromCartBlock).end(),
+     *   LoggedIn: (m) => m.method(AddToCartBlock).end(),
+     * });
+     */
+    branch<Routes extends {
+        [K in Out["__state"]]: ((m: MapBuilder<Extract<Out, Checkpoint<K>>>) => Flow<any>) | null;
+    }>(routes: Routes): Flow<{
+        [K in keyof Routes & string]: Routes[K] extends (m: any) => Flow<infer R> ? R : Extract<Out, Checkpoint<K>>;
+    }[keyof Routes & string]>;
+    /**
+     * 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. An auto-opened `{ ff: true }` window (see {@link MapStepOpts})
+     * left open at `.end()` closes silently; an EXPLICIT `.ffStart()` left open
+     * still throws - the author opened that one and needs to close it themselves.
+     */
+    end(): Flow<Out>;
+}
+export {};