waygraph 0.15.53 → 0.16.0

package/dist/engine/flow/flow.d.ts

@@ -0,0 +1,162 @@
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { RunGraphOptions } from "../run/run.js";
+import type { EngineConfig } from "../config.js";
+import type { BrowserContext, Page } from "@playwright/test";
+import { MemPage } from "../mem/mem.js";
+import type { Trait } from "../trait/trait.js";
+import type { DemoPace } from "../stub/pace.js";
+import type { HighlightStyleDefaults } from "../stub/ring.js";
+import type { SomeBlock } from "../block/block.js";
+/**
+ * A composed, runnable flow. Always begins from Checkpoint<"__start__">, same as
+ * runGraph's `entry`. `run(context, mem)` uses a context you already have (the
+ * usual case inside a `@playwright/test` file, via its `context` fixture) -
+ * there's no browser for this Flow to launch, so no config to pass. `run(mem,
+ * config?)` - no context - has the Engine launch and own its own browser for
+ * this one run instead, and closes it in `finally`; use this outside a
+ * Playwright test file, or when a flow genuinely needs its own browser instance
+ * rather than sharing the test's. `config` here overrides, per key, whatever
+ * `new Engine(...)` was constructed with - so one flow (module-level, imported
+ * by many specs) can still have every run choose its own `headless`/`slowMo`
+ * rather than being stuck with whatever the flow's own file happened to set.
+ *
+ * `withBlockVerify`/`modBlockVerify` do what {@link withVerify}/{@link modVerify}
+ * do for a single Block, one level up - a spec that only imports the finished
+ * Flow (not necessarily the individual Blocks it was built from) can still
+ * patch one Block's verify for just that call, without editing the flow's own
+ * file or hand-rebuilding its Block list. Addressed the same three ways
+ * `modVerify` already addresses a Trait - the Block reference itself
+ * (`LoginBlock`, imported like any other Block; typo-proof, refactor-safe,
+ * jump-to-definition works), a plain string name, or a numeric index into this
+ * Flow's Block list (position between `start`/`end`, 0-based) for a spec that
+ * genuinely doesn't have the Block imported and doesn't want to spell its
+ * name. A reference or string resolves by `.name` under the hood (a Block's
+ * own stable identity in this codebase, same as every error message elsewhere
+ * in this file already uses) rather than object identity - it stays
+ * resolvable even after an earlier patch already swapped that slot for a new
+ * object, since the name survives every `withVerify`/`modVerify` in the
+ * chain; an index is checked fresh against this Flow's current Block list
+ * each call, so it's still correct after a patch too. Returns a new Flow -
+ * the original is untouched, same as every other decorator in this module.
+ */
+/**
+ * One Block's identity as exposed by graph introspection - {@link Flow.blocks},
+ * {@link ComposedBlock.steps} - without needing to execute anything. Does not
+ * include the Block's literal Checkpoint `In`/`Out` tags: those are TypeScript
+ * literal types, erased at runtime, and can only be recovered by a build-time
+ * static-analysis tool reading the source's own type annotations - see the
+ * `graph-visualization` openspec change for that piece.
+ */
+export interface BlockInfo {
+    name: string;
+    /** `branch()`'s routing table, if this Block has one - see {@link Block.routes}. */
+    routes?: Readonly<Record<string, string | null>>;
+    /**
+     * True when a session-reset boundary runs immediately before this Block: the first Block of a sub-flow nested with
+     * `.flow(sub, { reset: true })` (or a CLI chain segment whose flow has `sessionReset`). Absent on an ordinary Flow.
+     */
+    resetSessionBefore?: boolean;
+    /**
+     * The actual Block, re-runnable on its own - e.g. step-through tooling that runs a Flow's Blocks one at a time.
+     * Introspection that only wants to read the shape (a visualizer) can ignore this and use `name`/`routes` alone.
+     */
+    block: SomeBlock;
+}
+/** A runnable chain of Blocks built by `engine.map()`. `run(mem)` launches its own browser; `run(context, mem)` reuses one. */
+export interface Flow<Out extends Checkpoint<string>> {
+    /**
+     * `map({ sessionReset: true })`: this Flow wants a fresh browser session when it runs after another one (nested with
+     * `.flow(sub)` or chained on the CLI). `run()` itself never reads it.
+     */
+    readonly resetSession: boolean;
+    /** The engine config the Flow was built with (launcher, layouts); running one of its steps on its own uses it too. */
+    readonly config: EngineConfig;
+    /**
+     * `map({ expectedFailure })` - a display hint for a step-through overlay: this Flow is DESIGNED to throw
+     * (e.g. a blocked user's login attempt genuinely failing), not a bug in
+     * the demo itself. `run()` never reads this - the Flow still throws
+     * exactly as it would otherwise; only the overlay's error panel reads it,
+     * to show an informational "this is the point" panel instead of an
+     * alarming one indistinguishable from a real break.
+     */
+    readonly expectedFailureReason?: string;
+    /**
+     * Demo pacing for this Flow's episode (`map({ demoPace })`).
+     * `run()` ignores; step/demo applies per Block in the episode.
+     */
+    readonly demoPace?: import("../stub/pace.js").DemoPace;
+    /**
+     * Default highlight size/weight/tone for this Flow's episode (`map({ highlightStyle })`).
+     * Per-slot stub/fixture values win. `run()` ignores.
+     */
+    readonly highlightStyle?: import("../stub/ring.js").HighlightStyleDefaults;
+    /**
+     * `map({ memStub: true })` - opts into
+     * auto-filling `requires` keys with registered fake values
+     * (`registerMemStub`, `src/engine/mem/mem-stub.ts`) instead of failing preflight when
+     * the caller didn't supply them. `run()` never reads this - the CLI's own
+     * `--data`/`--mem-stub` seeding, or a bare-library caller's own explicit
+     * `seedMemStub(mem, flow)` call, is what actually fills mem before `run()`.
+     */
+    readonly memStub?: boolean;
+    /**
+     * This Flow's constituent Blocks, in order between `start`/`end`, as plain
+     * data - for introspection/visualization tools, without running anything.
+     * @example loginFlow.blocks() // [{ name: "login" }, { name: "add-to-cart", routes: {...} }]
+     */
+    blocks(): readonly BlockInfo[];
+    run(context: BrowserContext, mem: MemPage): Promise<Out>;
+    /**
+     * `options.closeOnFinish: false` hands the driven page back instead of
+     * closing it - use this overload (a literal `false`, not a `boolean`) to
+     * get the `{ result, page }` shape typed correctly.
+     * @example const { result, page } = await loginFlow.run(context, mem, { closeOnFinish: false });
+     */
+    run(context: BrowserContext, mem: MemPage, options: RunGraphOptions & {
+        closeOnFinish: false;
+    }): Promise<{
+        result: Out;
+        page: Page;
+    }>;
+    /**
+     * `options.page` drives that already-open page instead of opening a new
+     * one - see {@link RunGraphOptions}.
+     * @example await loginFlow.run(context, mem, { page: existingPage });
+     */
+    run(context: BrowserContext, mem: MemPage, options?: RunGraphOptions): Promise<Out>;
+    run(mem: MemPage, config?: EngineConfig): Promise<Out>;
+    /**
+     * Replaces the given Block's whole verify list, wherever it sits in this
+     * Flow - same rules as {@link withVerify}. Throws if no Block in this Flow
+     * matches.
+     * @example checkoutFlow.withBlockVerify(LoginBlock, [])
+     * @example checkoutFlow.withBlockVerify("login", [])
+     * @example checkoutFlow.withBlockVerify(0, [])
+     */
+    withBlockVerify(block: SomeBlock | string | number, verify: Trait[] | ((out: any) => Trait[])): Flow<Out>;
+    /**
+     * Replaces one Trait inside the given Block's verify list - same rules as
+     * {@link modVerify}. Throws if no Block in this Flow matches, or if that
+     * Block has no verify trait at the given name/index.
+     * @example checkoutFlow.modBlockVerify(LoginBlock, "url-matches", Trait.url({ pathname: "/inventory.html" }))
+     */
+    modBlockVerify(block: SomeBlock | string | number, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): Flow<Out>;
+}
+export declare function buildFlow<Out extends Checkpoint<string>>(middle: readonly SomeBlock[], engineConfig: EngineConfig): Flow<Out>;
+/** The settings `map({ ... })` gives a Flow. */
+export interface FlowSettings {
+    memStub?: boolean;
+    sessionReset?: boolean;
+    expectedFailure?: string;
+    demoPace?: DemoPace;
+    highlightStyle?: HighlightStyleDefaults;
+}
+/** The Flow with its `map()` settings set; they survive `withBlockVerify`/`modBlockVerify` patches. */
+export declare function withSettings<Out extends Checkpoint<string>>(flow: Flow<Out>, settings: FlowSettings): Flow<Out>;
+export declare function clearSessionState(context: BrowserContext, page: Page): Promise<void>;
+/**
+ * Runs whole Flows one after another on the same page, context and mem - the runner's way of executing a CLI chain
+ * (`waygraph run "a then b"`) with each segment still its own episode. A Flow with `resetSession` gets its cookies and
+ * storage cleared right before it runs (skipped for the first one). Authors nest flows with `map().flow(sub)` instead.
+ */
+export declare function chainFlow(...flows: readonly Flow<Checkpoint<string>>[]): Flow<Checkpoint<string>>;

package/dist/engine/flow/flow.js

@@ -0,0 +1,244 @@
+// A Flow: Blocks joined in order (connect), run as one with `run()`; map() builds them, with its settings (withSettings).
+import { connect } from "../run/connect.js";
+import { launchOwnContext } from "../run/launch.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/run.js";
+import { MemPage } from "../mem/mem.js";
+import { findBlockIndex, modVerify, withVerify } from "../block/block.js";
+import { normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight } from "../stub/ring.js";
+import { ignorePageGone } from "../page-gone.js";
+export function buildFlow(middle, engineConfig) {
+    // Settings (sessionReset, memStub, ...) are added afterwards by withSettings, which re-applies them after any
+    // withBlockVerify/modBlockVerify patch so they survive.
+    // 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 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 { context, close } = await launchOwnContext(config);
+            try {
+                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 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,
+        config: engineConfig,
+        blocks: () => middle.map((b) => ({
+            name: b.name,
+            block: b,
+            ...(b.routes ? { routes: b.routes } : {}),
+            ...(b.__waygraphResetBefore ? { resetSessionBefore: true } : {}),
+        })),
+        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);
+        },
+    };
+}
+/** The Flow with its `map()` settings set; they survive `withBlockVerify`/`modBlockVerify` patches. */
+export function withSettings(flow, settings) {
+    const style = settings.highlightStyle;
+    const fields = {
+        ...(settings.sessionReset ? { resetSession: true } : {}),
+        ...(settings.memStub ? { memStub: true } : {}),
+        ...(settings.expectedFailure !== undefined ? { expectedFailureReason: settings.expectedFailure } : {}),
+        ...(settings.demoPace ? { demoPace: settings.demoPace } : {}),
+        ...(style
+            ? {
+                highlightStyle: {
+                    ...(style.tone !== undefined ? { tone: normalizeHighlightTone(style.tone) } : {}),
+                    ...(style.size !== undefined ? { size: normalizeHighlightSize(style.size) } : {}),
+                    ...(style.weight !== undefined ? { weight: normalizeHighlightWeight(style.weight) } : {}),
+                },
+            }
+            : {}),
+    };
+    if (Object.keys(fields).length === 0)
+        return flow;
+    return {
+        ...flow,
+        ...fields,
+        withBlockVerify: (block, verify) => withSettings(flow.withBlockVerify(block, verify), settings),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withSettings(flow.modBlockVerify(block, nameOrIndex, newCheck), settings),
+    };
+}
+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 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++) {
+        const localIndex = flows[fi].blocks().findIndex((bi) => bi.name === blockName);
+        if (localIndex !== -1)
+            return { flowIndex: fi, localIndex };
+    }
+    throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_CHAINFLOW_BLOCK_NOT_FOUND_BY_NAME(blockName));
+}
+export async function clearSessionState(context, page) {
+    await context.clearCookies().catch(ignorePageGone);
+    await page
+        .evaluate(() => {
+        try {
+            localStorage.clear();
+            sessionStorage.clear();
+        }
+        catch {
+            /* storage blocked (e.g. about:blank) - nothing to clear anyway */
+        }
+    })
+        .catch(ignorePageGone);
+}
+/**
+ * Runs whole Flows one after another on the same page, context and mem - the runner's way of executing a CLI chain
+ * (`waygraph run "a then b"`) with each segment still its own episode. A Flow with `resetSession` gets its cookies and
+ * storage cleared right before it runs (skipped for the first one). Authors nest flows with `map().flow(sub)` instead.
+ */
+export function chainFlow(...flows) {
+    if (flows.length === 0) {
+        throw new WaygraphError("WG_CHAINFLOW_EMPTY", MSG_CHAINFLOW_EMPTY);
+    }
+    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 sessionReset a no-op).
+            const { context, close } = await launchOwnContext(config);
+            try {
+                try {
+                    return await run(context, mem, { closeOnFinish: true });
+                }
+                finally {
+                    await context.close();
+                }
+            }
+            finally {
+                await 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 {
+        config: flows[0].config,
+        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);
+        },
+    };
+}

package/dist/{core → engine/flow}/map-builder.d.ts

@@ -1,19 +1,19 @@
-import type { Block, Checkpoint } from "../types.js";
-import type { EndMarker, StartMarker } from "./run-graph.js";
-import type { Flow, FlowOptions } from "./flow.js";
-import type { DemoPace, HighlightStyleDefaults } from "../highlights.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 type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { Flow, FlowSettings } from "./flow.js";
+import type { DemoPace } from "../stub/pace.js";
+import type { HighlightStyleDefaults } from "../stub/ring.js";
+import type { NavBlock } from "../block/kinds/nav.js";
+import type { PageBlock } from "../block/kinds/page.js";
+import type { AssertBlock, MethodBlock } from "../block/kinds/method.js";
+import type { EffectBlock } from "../block/kinds/effect.js";
+import type { SomeBlock } from "../block/block.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.
+ * The one capability MapBuilder needs from Engine: turn the finished steps into a Flow with the engine's config. A
+ * function, not the Engine class, so engine.ts and map-builder.ts don't import each other.
  */
-export type DefineFlowFn = (blocks: readonly [StartMarker, ...Block<any, any>[], EndMarker], options?: FlowOptions) => Flow<any>;
+export type BuildFlowFn = (steps: readonly SomeBlock[], settings: FlowSettings) => Flow<Checkpoint<string>>;
+/** Per-step options for the map builder: `ff` fast-forwards the step, `pace` sets its demo pace. */
 export interface MapStepOpts {
     /**
      * Fast-forward just this step, inline - no `.ffStart()/.ffEnd()` bracket needed. Consecutive
@@ -24,11 +24,12 @@ export interface MapStepOpts {
     ff?: boolean;
     /**
      * Demo pace for just this step (`"blitz"` skips the typing animation and the pause after the action; `"fast"`, `"slow"`,
-     * or a number scale the narration gates). The map equivalent of `withBlockPace`, with no wrapper.
+     * or a number scale the narration gates).
      * @example map().method(SetBearerTokenBlock, { pace: "blitz" })
      */
     pace?: DemoPace;
 }
+/** Flow-level settings for `engine.map({ … })`: `memStub`, `sessionReset`, `expectedFailure`, `demoPace`, `highlightStyle`, `homeOrigin`. */
 export interface MapBuilderOptions {
     /**
      * This project's own origin (e.g. `"https://app.example.com"`) - enables
@@ -37,22 +38,27 @@ export interface MapBuilderOptions {
      * way; only the internal/external origin distinction is opt-in).
      */
     homeOrigin?: string;
-    /** Fill missing `requires` keys from `registerMemStub` when the flow runs (what `withMemStub` did). */
+    /** Fill missing `requires` keys from `registerMemStub` when the flow runs. */
     memStub?: boolean;
-    /** Marks a flow that is supposed to throw, with the reason shown in the demo (what `withExpectedFailure` did). */
+    /**
+     * This flow wants a fresh browser session (cookies and storage cleared) when it runs after another one, in a CLI chain
+     * (`waygraph run "a then b"`) or nested with `.flow(sub)`: a second user signing in, a logged-out check.
+     */
+    sessionReset?: boolean;
+    /** Marks a flow that is supposed to throw, with the reason shown in the demo. */
     expectedFailure?: string;
-    /** Default demo pace for the whole flow (what `withDemoPace` did). */
+    /** Default demo pace for the whole flow. */
     demoPace?: DemoPace;
-    /** Default ring tone, size and weight for the whole flow (what `withHighlightStyle` did). */
+    /** Default ring tone, size and weight for the whole flow. */
     highlightStyle?: HighlightStyleDefaults;
 }
 /** What `.flow()` takes for the sub-flow it runs inline. */
 export interface MapFlowOpts {
-    /** Clear cookies and storage right before the sub-flow, e.g. to start a second user fresh (what `withSessionReset` + `chainFlow` did). */
+    /** Clear cookies and storage right before the sub-flow, e.g. to start a second user fresh. Defaults to the sub-flow's own `sessionReset`. */
     reset?: boolean;
 }
 /**
- * Fluent builder over {@link Engine.defineFlow} - see `map()`'s own doc
+ * The flow builder behind `engine.map()` - 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`/
@@ -60,21 +66,21 @@ export interface MapFlowOpts {
  * (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
+ * typechecks the accumulated Checkpoint chain (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 build;
+    private readonly settings;
     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. */
+    static begin(build: BuildFlowFn, settings: FlowSettings, homeOrigin: string | undefined): MapBuilder<S>;
+    /** Readable chain-opener. Returns `this` unchanged; entirely optional. */
     start(): MapBuilder<Out>;
     /**
      * Open a fast-forward window - steps until {@link ffEnd} collapse into one
@@ -103,7 +109,7 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
      * `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.
+     * `{ ff: true }`: fast-forward this one step inline - see `appendStep`'s own comment.
      */
     gotoPage<NextOut extends Checkpoint<string>>(block: (NavBlock<NextOut> | PageBlock<NextOut>) & {
         name: string;
@@ -113,7 +119,7 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
      * 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.
+     * `{ ff: true }`: fast-forward this one step inline - see `appendStep`'s own comment.
      */
     gotoExternal<NextOut extends Checkpoint<string>>(block: (NavBlock<NextOut> | PageBlock<NextOut>) & {
         name: string;
@@ -121,7 +127,7 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
     /**
      * 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.
+     * `{ ff: true }`: fast-forward this one step inline - see `appendStep`'s own comment.
      */
     assert(block: AssertBlock<Out> & {
         name: string;
@@ -133,7 +139,7 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
      * 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.
+     * `{ ff: true }`: fast-forward this one step inline - see `appendStep`'s own comment.
      */
     method<NextOut extends Checkpoint<string>>(block: (MethodBlock<Out, NextOut> | EffectBlock<Out, NextOut>) & {
         name: string;
@@ -141,7 +147,7 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
     /**
      * Runs another flow's steps inline here, in the same page, browser and `mem`. This is how flows nest:
      * `map().flow(loginFlow).flow(viewerFlow, { reset: true })`. With `{ reset: true }` cookies and storage are cleared
-     * right before the sub-flow's first step. Replaces `chainFlow` and `withSessionReset`.
+     * right before the sub-flow's first step.
      */
     flow<NextOut extends Checkpoint<string>>(sub: Flow<NextOut>, opts?: MapFlowOpts): MapBuilder<NextOut>;
     /**
@@ -156,7 +162,7 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
      * 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()`,
+     * `runGraph`'s own graph walk - `.end()` composes 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.
@@ -167,7 +173,7 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
      *
      * 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`,
+     * any single-Block Flow does. Read `page`/`mem`, not `input`,
      * in `act()` - every real Block in this codebase already follows that convention.
      *
      * @example
@@ -177,21 +183,17 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
      * });
      */
     branch<Routes extends {
-        [K in Out["__state"]]: ((m: MapBuilder<Extract<Out, Checkpoint<K>>>) => Flow<any>) | null;
+        [K in Out["__state"]]: ((m: MapBuilder<Extract<Out, Checkpoint<K>>>) => Flow<Checkpoint<string>>) | 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
+     * Finalizes this chain into a runnable {@link Flow} with the settings given to `map({ ... })`;
+     * `withBlockVerify`/`modBlockVerify` work on it. 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.
      */
-    /** @param options @deprecated Pass flow settings to `map({ … })` instead. */
-    end(options?: FlowOptions): Flow<Out>;
+    end(): Flow<Out>;
 }
 export {};