waygraph 0.15.54 → 0.16.1

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

@@ -1,35 +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 { SomeBlock } from "../block/block.js";
+import type { EffectBlock } from "../block/kinds/effect.js";
+import type { AssertBlock, MethodBlock } from "../block/kinds/method.js";
+import type { NavBlock } from "../block/kinds/nav.js";
+import type { PageBlock } from "../block/kinds/page.js";
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { DemoPace } from "../stub/pace.js";
+import type { HighlightStyleDefaults } from "../stub/ring.js";
+import type { Flow, FlowSettings } from "./flow.js";
+import { MapStepOpts } from "./map-steps.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>;
-/** 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
-     * `{ 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;
-    /**
-     * 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.
-     * @example map().method(SetBearerTokenBlock, { pace: "blitz" })
-     */
-    pace?: DemoPace;
-}
+export type BuildFlowFn = (steps: readonly SomeBlock[], settings: FlowSettings) => Flow<Checkpoint<string>>;
 /** Flow-level settings for `engine.map({ … })`: `memStub`, `sessionReset`, `expectedFailure`, `demoPace`, `highlightStyle`, `homeOrigin`. */
 export interface MapBuilderOptions {
     /**
@@ -39,18 +23,18 @@ 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;
     /**
      * 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 (what `withExpectedFailure` did). */
+    /** 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. */
@@ -59,7 +43,7 @@ export interface MapFlowOpts {
     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`/
@@ -67,21 +51,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
@@ -110,7 +94,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;
@@ -120,7 +104,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;
@@ -128,7 +112,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;
@@ -140,7 +124,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;
@@ -148,7 +132,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>;
     /**
@@ -163,7 +147,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.
@@ -174,7 +158,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
@@ -184,21 +168,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 {};

package/dist/engine/flow/map-builder.js

@@ -0,0 +1,242 @@
+import { fastForwardComposeBlock } from "../block/compose.js";
+import { MSG_MAP_BRANCH_NO_PRIOR_STEP, MSG_MAP_EMPTY, MSG_MAP_FF_ALREADY_OPEN, MSG_MAP_FF_EMPTY, MSG_MAP_FF_NOT_CLOSED, MSG_MAP_FF_NOT_OPEN, MSG_MAP_METHOD_GOT_ASSERT, WaygraphError, } from "../errors.js";
+import { buildBranchedFlow } from "./map-branch.js";
+import { assertMapKind, assertMapOrigin, assertMapSalt, mapKindOf, paced, resetBefore } from "./map-steps.js";
+/**
+ * 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`/
+ * `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 (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 {
+    build;
+    settings;
+    steps;
+    homeOrigin;
+    ff;
+    constructor(
+    // From Engine.map(): see BuildFlowFn.
+    build, settings, steps, homeOrigin, 
+    // `auto: true` = opened implicitly by a `{ ff: true }` step flag, not an explicit .ffStart() -
+    // closes silently at the next non-flagged step (or at .end()/.branch()) instead of demanding a
+    // matching .ffEnd(), since the author never opened anything they'd need to remember to close.
+    ff = null) {
+        this.build = build;
+        this.settings = settings;
+        this.steps = steps;
+        this.homeOrigin = homeOrigin;
+        this.ff = ff;
+    }
+    /** @internal - use `engine.map()` or the standalone `map()` export. */
+    static begin(build, settings, homeOrigin) {
+        return new MapBuilder(build, settings, [], homeOrigin, null);
+    }
+    /** Readable chain-opener. 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 WaygraphError("WG_MAP_FF_ALREADY_OPEN", MSG_MAP_FF_ALREADY_OPEN(this.ff.name));
+        }
+        const ffName = typeof name === "string" && name.trim()
+            ? name.trim()
+            : `ff-${this.steps.length + 1}`;
+        return new MapBuilder(this.build, this.settings, this.steps, this.homeOrigin, {
+            name: ffName,
+            buffer: [],
+            auto: false,
+        });
+    }
+    /**
+     * 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 WaygraphError("WG_MAP_FF_NOT_OPEN", MSG_MAP_FF_NOT_OPEN);
+        }
+        return this.closeFf();
+    }
+    /** Shared by the explicit {@link ffEnd} and the implicit close a `{ ff: true }` step flag triggers. */
+    closeFf() {
+        const ff = this.ff;
+        if (!ff)
+            return this;
+        if (ff.buffer.length === 0) {
+            throw new WaygraphError("WG_MAP_FF_EMPTY", MSG_MAP_FF_EMPTY(ff.name));
+        }
+        const composed = fastForwardComposeBlock(ff.name, 
+        // The window's steps were typechecked as they were added; the one-step overload takes them as one Block.
+        ff.buffer);
+        return new MapBuilder(this.build, this.settings, [...this.steps, composed], this.homeOrigin, null);
+    }
+    /**
+     * `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 }`).
+     */
+    appendStep(block, ff) {
+        if (ff) {
+            const win = this.ff ?? { name: `ff-${this.steps.length + 1}`, buffer: [], auto: true };
+            return new MapBuilder(this.build, this.settings, this.steps, this.homeOrigin, {
+                name: win.name,
+                buffer: [...win.buffer, block],
+                auto: win.auto,
+            });
+        }
+        if (this.ff && this.ff.auto) {
+            return this.closeFf().appendStep(block);
+        }
+        if (this.ff) {
+            // Explicit .ffStart() window still open - absorbs a plain step too, same as always.
+            return new MapBuilder(this.build, this.settings, this.steps, this.homeOrigin, {
+                name: this.ff.name,
+                buffer: [...this.ff.buffer, block],
+                auto: false,
+            });
+        }
+        return new MapBuilder(this.build, this.settings, [...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).
+     * `{ ff: true }`: fast-forward this one step inline - see `appendStep`'s own comment.
+     */
+    gotoPage(block, opts) {
+        assertMapKind(block, ["nav", "page"], "gotoPage");
+        assertMapOrigin(block, this.homeOrigin, "internal", "gotoPage");
+        return this.appendStep(paced(block, opts), opts?.ff);
+    }
+    /**
+     * 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 `appendStep`'s own comment.
+     */
+    gotoExternal(block, opts) {
+        assertMapKind(block, ["nav", "page"], "gotoExternal");
+        assertMapOrigin(block, this.homeOrigin, "external", "gotoExternal");
+        return this.appendStep(paced(block, opts), opts?.ff);
+    }
+    /**
+     * 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 `appendStep`'s own comment.
+     */
+    assert(block, opts) {
+        assertMapKind(block, ["assert"], "assert");
+        return this.appendStep(paced(block, opts), opts?.ff);
+    }
+    /**
+     * 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 `appendStep`'s own comment.
+     */
+    method(block, opts) {
+        if (mapKindOf(block) === "assert") {
+            throw new WaygraphError("WG_MAP_WRONG_KIND", MSG_MAP_METHOD_GOT_ASSERT(block.name));
+        }
+        assertMapSalt(block, ["method", "effect", "api"], "method");
+        return this.appendStep(paced(block, opts), opts?.ff);
+    }
+    /**
+     * 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.
+     */
+    flow(sub, opts) {
+        // The steps' types live in `sub`; at runtime this is one untyped walk, typed again as the sub-flow's last Checkpoint.
+        let next = this;
+        sub.blocks().forEach((info, i) => {
+            const block = i === 0 && (opts?.reset ?? sub.resetSession) ? resetBefore(info.block) : info.block;
+            next = next.appendStep(block);
+        });
+        return next;
+    }
+    /**
+     * 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 - `.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.
+     *
+     * 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 single-Block Flow 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) {
+        if (this.steps.length === 0) {
+            throw new WaygraphError("WG_MAP_BRANCH_NO_PRIOR_STEP", MSG_MAP_BRANCH_NO_PRIOR_STEP);
+        }
+        const before = this.end();
+        const resolvedRoutes = {};
+        for (const [tag, fn] of Object.entries(routes)) {
+            resolvedRoutes[tag] = fn ? fn(new MapBuilder(this.build, this.settings, [], this.homeOrigin, null)) : null;
+        }
+        return buildBranchedFlow(before, resolvedRoutes);
+    }
+    /**
+     * 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.
+     */
+    end() {
+        if (this.ff && !this.ff.auto) {
+            throw new WaygraphError("WG_MAP_FF_NOT_CLOSED", MSG_MAP_FF_NOT_CLOSED(this.ff.name));
+        }
+        if (this.ff && this.ff.auto) {
+            return this.closeFf().end();
+        }
+        if (this.steps.length === 0) {
+            throw new WaygraphError("WG_MAP_EMPTY", MSG_MAP_EMPTY);
+        }
+        return this.build(this.steps, this.settings);
+    }
+}

package/dist/engine/flow/map-steps.d.ts

@@ -0,0 +1,30 @@
+import { type SomeBlock, type SomeDefinedBlock } from "../block/block.js";
+import type { DemoPace } from "../stub/pace.js";
+/** The same Block, but it clears cookies and storage before it acts. Keeps the runtime markers. */
+export declare function resetBefore(block: SomeBlock): SomeBlock;
+/** Applies a step's `pace` option, keeping the Block's runtime markers. */
+export declare function paced(block: object, opts: MapStepOpts | undefined): SomeDefinedBlock;
+export declare function mapKindOf(block: unknown): string | undefined;
+export declare function mapSaltOf(block: unknown): string | undefined;
+export declare function mapNavUrlOf(block: unknown): string | undefined;
+export declare function assertMapKind(block: SomeBlock, allowed: readonly string[], method: string): void;
+export declare function assertMapSalt(block: SomeBlock, allowed: readonly string[], method: string): void;
+export declare function assertMapOrigin(block: SomeBlock, homeOrigin: string | undefined, expect: "internal" | "external", method: string): void;
+export declare const MAP_KIND_FACTORY_HINT: Record<string, string>;
+export declare const MAP_SALT_FACTORY_HINT: Record<string, 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
+     * `{ 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;
+    /**
+     * 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).
+     * @example map().method(SetBearerTokenBlock, { pace: "blitz" })
+     */
+    pace?: DemoPace;
+}

package/dist/engine/flow/map-steps.js

@@ -0,0 +1,87 @@
+import { copyWaygraphRuntime } from "../block/block.js";
+import { MSG_MAP_WRONG_KIND, MSG_MAP_WRONG_ORIGIN_EXTERNAL, MSG_MAP_WRONG_ORIGIN_INTERNAL, MSG_MAP_WRONG_SALT, WaygraphError } from "../errors.js";
+import { clearSessionState } from "./flow.js";
+/** The same Block, but it clears cookies and storage before it acts. Keeps the runtime markers. */
+export function resetBefore(block) {
+    const act = block.instruction.act.bind(block.instruction);
+    const next = {
+        ...block,
+        instruction: {
+            ...block.instruction,
+            async act(page, input, mem) {
+                await clearSessionState(page.context(), page);
+                return act(page, input, mem);
+            },
+        },
+    };
+    copyWaygraphRuntime(block, next);
+    Object.defineProperty(next, "__waygraphResetBefore", { value: true, enumerable: false, configurable: true });
+    return next;
+}
+/** Applies a step's `pace` option, keeping the Block's runtime markers. */
+export function paced(block, opts) {
+    if (opts?.pace === undefined)
+        return block;
+    const next = { ...block, demoPace: opts.pace };
+    copyWaygraphRuntime(block, next);
+    return next;
+}
+export function mapKindOf(block) {
+    return block?.__waygraphKind;
+}
+export function mapSaltOf(block) {
+    return block?.__waygraphSalt;
+}
+export function mapNavUrlOf(block) {
+    const url = block?.__waygraphNavUrl;
+    return typeof url === "string" ? url : undefined;
+}
+export 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 WaygraphError("WG_MAP_WRONG_KIND", MSG_MAP_WRONG_KIND(method, block?.name ?? "?", wanted, found));
+}
+export 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 WaygraphError("WG_MAP_WRONG_SALT", MSG_MAP_WRONG_SALT(method, block?.name ?? "?", wanted, found));
+}
+export 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 WaygraphError("WG_MAP_WRONG_ORIGIN", MSG_MAP_WRONG_ORIGIN_INTERNAL(block.name, targetOrigin, wantOrigin));
+    }
+    if (expect === "external" && !isExternal) {
+        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", MSG_MAP_WRONG_ORIGIN_EXTERNAL(block.name, targetOrigin, wantOrigin));
+    }
+}
+export const MAP_KIND_FACTORY_HINT = {
+    nav: "defineNavBlock/defineMemNavBlock",
+    page: "definePageBlock",
+    assert: "defineAssertBlock",
+};
+export const MAP_SALT_FACTORY_HINT = {
+    method: "defineMethodBlock",
+    effect: "defineEffectBlock",
+    api: "defineApiBlock",
+};

package/dist/{core → engine}/locate.d.ts

@@ -1,4 +1,4 @@
-import type { NavBlock } from "./blocks/nav.js";
+import type { NavBlock } from "./block/kinds/nav.js";
 import type { Page } from "@playwright/test";
 /**
  * "Where am I" - reverse-matches a live `page` against every NavBlock /

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

@@ -1,4 +1,4 @@
-import { MemPage } from "../mem-page.js";
+import { MemPage } from "./mem/mem.js";
 /**
  * "Where am I" - reverse-matches a live `page` against every NavBlock /
  * PageBlock in `library`, in order, returning the first one whose own `verify`
@@ -38,7 +38,6 @@ export async function locate(page, library, options) {
                 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;

package/dist/{mem-stub.d.ts → engine/mem/mem-stub.d.ts}

@@ -6,18 +6,19 @@
  *
  * "Stub" here is unrelated to the other two meanings already in this
  * codebase: `stubBefore`/`stubAfter`/`stubOnError` (demo narration fixtures,
- * see highlights.ts's `runStubPhase`) and `upload`'s `stub: "image"|"pdf"|
+ * see demo/narration/index.ts's `runStubPhase`) and `upload`'s `stub: "image"|"pdf"|
  * "video"` (a placeholder file). This is a third, separate "stub."
  *
- * Opt-in only, per Flow (`withMemStub`, engine.ts) or per-run (`--mem-stub` /
+ * Opt-in only, per Flow (`map({ memStub: true })`) or per-run (`--mem-stub` /
  * WAYGRAPH_MEM_STUB=1) - a required key with no registered generator still
  * fails preflight exactly as before. Registered per MemKey *instance*
  * (identity, not `.name`), matching MemPage's own store - two keys sharing a
  * debug name must never cross-contaminate here either.
  */
-import type { MemKey } from "./mem-page.js";
-import type { MemPage } from "./mem-page.js";
-import type { Flow } from "./core.js";
+import type { MemKey } from "./mem.js";
+import type { MemPage } from "./mem.js";
+import type { Flow } from "../flow/flow.js";
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
 /**
  * Registers a fake-value generator for one required MemKey.
  * @example registerMemStub(LoginCreds.key, () => ({
@@ -26,16 +27,16 @@ import type { Flow } from "./core.js";
  * }));
  */
 export declare function registerMemStub<T>(key: MemKey<T>, fake: () => T): void;
-/** Used by waygraph's own `--mem-stub`-aware CLI seeding and by {@link seedMemStub} - flow authors normally use {@link registerMemStub}/{@link withMemStub} instead. */
+/** Used by waygraph's own `--mem-stub`-aware CLI seeding and by {@link seedMemStub} - flow authors normally use {@link registerMemStub} and `map({ memStub: true })` instead. */
 export declare function getMemStub<T>(key: MemKey<T>): (() => T) | undefined;
 /**
  * For a bare library `flow.run(mem, ...)` call outside the CLI (which has its
  * own `--mem-stub`-aware seeding) - call this yourself before `run()` when
  * `flow.memStub` is true, the same way external tooling already reads
  * `flow.resetSession`/`flow.title`/etc. (`run()` itself never reads Flow
- * flags - see the `with*` helpers in engine.ts).
+ * flags; the settings come from `map({ ... })`).
  * @example
  * if (flow.memStub) seedMemStub(mem, flow);
  * await flow.run(mem, config);
  */
-export declare function seedMemStub(mem: MemPage, flow: Flow<any>): void;
+export declare function seedMemStub(mem: MemPage, flow: Flow<Checkpoint<string>>): void;

package/dist/{mem-stub.js → engine/mem/mem-stub.js}

@@ -9,7 +9,7 @@ const registry = new Map();
 export function registerMemStub(key, fake) {
     registry.set(key, fake);
 }
-/** Used by waygraph's own `--mem-stub`-aware CLI seeding and by {@link seedMemStub} - flow authors normally use {@link registerMemStub}/{@link withMemStub} instead. */
+/** Used by waygraph's own `--mem-stub`-aware CLI seeding and by {@link seedMemStub} - flow authors normally use {@link registerMemStub} and `map({ memStub: true })` instead. */
 export function getMemStub(key) {
     return registry.get(key);
 }
@@ -18,7 +18,7 @@ export function getMemStub(key) {
  * own `--mem-stub`-aware seeding) - call this yourself before `run()` when
  * `flow.memStub` is true, the same way external tooling already reads
  * `flow.resetSession`/`flow.title`/etc. (`run()` itself never reads Flow
- * flags - see the `with*` helpers in engine.ts).
+ * flags; the settings come from `map({ ... })`).
  * @example
  * if (flow.memStub) seedMemStub(mem, flow);
  * await flow.run(mem, config);

package/dist/{mem-page.d.ts → engine/mem/mem.d.ts}

@@ -55,7 +55,7 @@ export declare class MemPage {
      * can only have string/symbol property names, not object instances - a `[key,
      * value]` pair is the shape that keeps that identity-based guarantee.
      *
-     * Overloaded per pair count (2-6, same reasoning as `Engine.defineFlow`'s
+     * Overloaded per pair count (2-6, per-arity overloads like the old `defineFlow`'s
      * overloads) rather than one fully-generic variadic signature - each pair binds
      * its own type parameter independently, which TS checks reliably; a single
      * self-referential mapped-tuple-over-a-rest-parameter type was tried first and