waygraph 0.15.46 → 0.15.49

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

package/dist/{engine/engine-class.js → core/map-builder.js}

@@ -1,47 +1,7 @@
-import { WaygraphError } from "../errors.js";
+import { WaygraphError, MSG_MAP_WRONG_KIND, MSG_MAP_WRONG_SALT, MSG_MAP_WRONG_ORIGIN_INTERNAL, MSG_MAP_WRONG_ORIGIN_EXTERNAL, MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED, MSG_MAP_FF_ALREADY_OPEN, MSG_MAP_FF_NOT_OPEN, MSG_MAP_FF_EMPTY, MSG_MAP_METHOD_GOT_ASSERT, MSG_MAP_BRANCH_NO_PRIOR_STEP, MSG_MAP_FF_NOT_CLOSED, MSG_MAP_EMPTY, } from "../errors.js";
 import { end, start } from "./run-graph.js";
-import { buildFlow } from "./flow.js";
 import { MemPage } from "../mem-page.js";
 import { fastForwardComposeBlock } from "./compose.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, options?.homeOrigin);
-    }
-}
 function mapKindOf(block) {
     return block?.__waygraphKind;
 }
@@ -67,9 +27,7 @@ function assertMapKind(block, allowed, method) {
         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", `Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
-        `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
-        "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.");
+    throw new WaygraphError("WG_MAP_WRONG_KIND", MSG_MAP_WRONG_KIND(method, block?.name ?? "?", wanted, found));
 }
 function assertMapSalt(block, allowed, method) {
     const salt = mapSaltOf(block);
@@ -77,9 +35,7 @@ function assertMapSalt(block, allowed, method) {
         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", `Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
-        `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
-        "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.");
+    throw new WaygraphError("WG_MAP_WRONG_SALT", MSG_MAP_WRONG_SALT(method, block?.name ?? "?", wanted, found));
 }
 function assertMapOrigin(block, homeOrigin, expect, method) {
     if (!homeOrigin)
@@ -98,12 +54,10 @@ function assertMapOrigin(block, homeOrigin, expect, method) {
     }
     const isExternal = targetOrigin !== wantOrigin;
     if (expect === "internal" && isExternal) {
-        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", `Waygraph map: .gotoPage("${block.name}") targets ${targetOrigin}, which is NOT this map's ` +
-            `home origin (${wantOrigin}) - use .gotoExternal() for a genuinely cross-origin destination.`);
+        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", `Waygraph map: .gotoExternal("${block.name}") targets ${targetOrigin}, which IS this map's ` +
-            `home origin (${wantOrigin}) - use .gotoPage() for an internal destination.`);
+        throw new WaygraphError("WG_MAP_WRONG_ORIGIN", MSG_MAP_WRONG_ORIGIN_EXTERNAL(block.name, targetOrigin, wantOrigin));
     }
 }
 /**
@@ -115,9 +69,7 @@ function assertMapOrigin(block, homeOrigin, expect, method) {
 function buildBranchedFlow(before, routes) {
     const run = (async (contextOrMem, memOrConfig, options) => {
         if (contextOrMem instanceof MemPage) {
-            throw new WaygraphError("WG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED", "Waygraph map: a .branch()-ed Flow can't run via run(mem, config) - that convenience form " +
-                "always closes its own browser/page before a branch's tag is even known. Call " +
-                "run(context, mem[, options]) instead, keeping the same page across the branch.");
+            throw new WaygraphError("WG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED", MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED);
         }
         const context = contextOrMem;
         const mem = memOrConfig;
@@ -180,19 +132,25 @@ function buildBranchedFlow(before, routes) {
  * real, kind-correct Block in between.
  */
 export class MapBuilder {
-    engine;
+    defineFlow;
     steps;
     homeOrigin;
     ff;
-    constructor(engine, steps, homeOrigin, ff = null) {
-        this.engine = engine;
+    constructor(
+    // A plain defineFlow-shaped function, not the whole Engine - see DefineFlowFn's own comment.
+    defineFlow, 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.defineFlow = defineFlow;
         this.steps = steps;
         this.homeOrigin = homeOrigin;
         this.ff = ff;
     }
     /** @internal - use `engine.map()` or the standalone `map()` export. */
-    static begin(engine, homeOrigin) {
-        return new MapBuilder(engine, [], homeOrigin, null);
+    static begin(defineFlow, homeOrigin) {
+        return new MapBuilder(defineFlow, [], homeOrigin, null);
     }
     /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
     start() {
@@ -205,14 +163,15 @@ export class MapBuilder {
      */
     ffStart(name) {
         if (this.ff) {
-            throw new WaygraphError("WG_MAP_FF_ALREADY_OPEN", `Waygraph map: .ffStart() while already inside "${this.ff.name}" - call .ffEnd() first`);
+            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.engine, this.steps, this.homeOrigin, {
+        return new MapBuilder(this.defineFlow, this.steps, this.homeOrigin, {
             name: ffName,
             buffer: [],
+            auto: false,
         });
     }
     /**
@@ -221,54 +180,85 @@ export class MapBuilder {
      */
     ffEnd() {
         if (!this.ff) {
-            throw new WaygraphError("WG_MAP_FF_NOT_OPEN", "Waygraph map: .ffEnd() with no open .ffStart()");
+            throw new WaygraphError("WG_MAP_FF_NOT_OPEN", MSG_MAP_FF_NOT_OPEN);
         }
-        if (this.ff.buffer.length === 0) {
-            throw new WaygraphError("WG_MAP_FF_EMPTY", `Waygraph map: .ffEnd() for "${this.ff.name}" has no steps - add .gotoPage/.method/… inside the window`);
+        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(this.ff.name, 
+        const composed = fastForwardComposeBlock(ff.name, 
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        this.ff.buffer);
-        return new MapBuilder(this.engine, [...this.steps, composed], this.homeOrigin, null);
+        ff.buffer);
+        return new MapBuilder(this.defineFlow, [...this.steps, composed], this.homeOrigin, null);
     }
-    appendStep(block) {
+    /**
+     * `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.defineFlow, 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) {
-            return new MapBuilder(this.engine, this.steps, this.homeOrigin, {
+            // Explicit .ffStart() window still open - absorbs a plain step too, same as always.
+            return new MapBuilder(this.defineFlow, this.steps, this.homeOrigin, {
                 name: this.ff.name,
                 buffer: [...this.ff.buffer, block],
+                auto: false,
             });
         }
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin, null);
+        return new MapBuilder(this.defineFlow, [...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 {@link appendStep}'s own comment.
      */
-    gotoPage(block) {
+    gotoPage(block, opts) {
         assertMapKind(block, ["nav", "page"], "gotoPage");
         assertMapOrigin(block, this.homeOrigin, "internal", "gotoPage");
-        return this.appendStep(block);
+        return this.appendStep(block, 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 {@link appendStep}'s own comment.
      */
-    gotoExternal(block) {
+    gotoExternal(block, opts) {
         assertMapKind(block, ["nav", "page"], "gotoExternal");
         assertMapOrigin(block, this.homeOrigin, "external", "gotoExternal");
-        return this.appendStep(block);
+        return this.appendStep(block, 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 {@link appendStep}'s own comment.
      */
-    assert(block) {
+    assert(block, opts) {
         assertMapKind(block, ["assert"], "assert");
-        return this.appendStep(block);
+        return this.appendStep(block, opts?.ff);
     }
     /**
      * Appends a non-navigating page action (submit, upload, add/remove an
@@ -277,14 +267,14 @@ export class MapBuilder {
      * 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(block) {
+    method(block, opts) {
         if (mapKindOf(block) === "assert") {
-            throw new WaygraphError("WG_MAP_WRONG_KIND", `Waygraph map: .method("${block.name}") got a defineAssertBlock - use .assert() for ` +
-                "self-loop verify steps (Assert Blocks share method salt internally but are not methods).");
+            throw new WaygraphError("WG_MAP_WRONG_KIND", MSG_MAP_METHOD_GOT_ASSERT(block.name));
         }
         assertMapSalt(block, ["method", "effect"], "method");
-        return this.appendStep(block);
+        return this.appendStep(block, opts?.ff);
     }
     /**
      * Branch: run everything added so far, then continue into whichever `routes[tag]` matches the
@@ -320,13 +310,12 @@ export class MapBuilder {
      */
     branch(routes) {
         if (this.steps.length === 0) {
-            throw new WaygraphError("WG_MAP_BRANCH_NO_PRIOR_STEP", "Waygraph map: .branch() needs at least one prior step - nothing to branch from. " +
-                "Add .gotoPage()/.gotoExternal()/.method()/.assert() first.");
+            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.engine, [], this.homeOrigin, null)) : null;
+            resolvedRoutes[tag] = fn ? fn(new MapBuilder(this.defineFlow, [], this.homeOrigin, null)) : null;
         }
         return buildBranchedFlow(before, resolvedRoutes);
     }
@@ -336,26 +325,21 @@ export class MapBuilder {
      * `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.
+     * 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) {
-            throw new WaygraphError("WG_MAP_FF_NOT_CLOSED", `Waygraph map: .end() while .ffStart("${this.ff.name}") is still open - call .ffEnd() first`);
+        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", "Waygraph map: .end() called with zero steps - add at least one .gotoPage()/.gotoExternal()/" +
-                ".assert()/.method() before .end()");
+            throw new WaygraphError("WG_MAP_EMPTY", MSG_MAP_EMPTY);
         }
         const chain = [start, ...this.steps, end];
-        return this.engine.defineFlow(chain);
+        return this.defineFlow(chain);
     }
 }
-/**
- * Standalone convenience for `new Engine(config).map(options)` - use this
- * when a call site doesn't otherwise need its own `Engine` instance (no
- * shared `headless`/`slowMo`/`layouts` across several flows).
- * @example const flow = map({ homeOrigin: "https://app.example.com" }).gotoPage(NavHomeBlock).end();
- */
-export function map(options) {
-    return new Engine(options).map(options);
-}

package/dist/{engine → core}/run-graph.js

@@ -1,4 +1,4 @@
-import { WaygraphError } from "../errors.js";
+import { WaygraphError, MSG_PREFLIGHT_MISSING_KEY, MSG_RUNGRAPH_MAX_STEPS, MSG_RUNGRAPH_NOT_TERMINAL } from "../errors.js";
 import { checkpoint } from "../types.js";
 import { runPrecondition, runVerify } from "../trait.js";
 /**
@@ -12,9 +12,7 @@ import { runPrecondition, runVerify } from "../trait.js";
 export function preflight(mem, block) {
     const missing = (block.requires ?? []).filter((k) => !mem.has(k));
     if (missing.length > 0) {
-        throw new WaygraphError("WG_PREFLIGHT_MISSING_KEY", `preflight: MemPage is missing required key(s) before "${block.name}" can run: ${missing
-            .map((k) => `"${k.name}"`)
-            .join(", ")}`);
+        throw new WaygraphError("WG_PREFLIGHT_MISSING_KEY", MSG_PREFLIGHT_MISSING_KEY(block.name, missing.map((k) => `"${k.name}"`).join(", ")));
     }
 }
 /**
@@ -86,7 +84,7 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
         let steps = 0;
         for (;;) {
             if (++steps > maxSteps) {
-                throw new WaygraphError("WG_RUNGRAPH_MAX_STEPS", `runGraph: exceeded ${maxSteps} steps - check for an unintended self-loop`);
+                throw new WaygraphError("WG_RUNGRAPH_MAX_STEPS", MSG_RUNGRAPH_MAX_STEPS(maxSteps));
             }
             await runPrecondition(current.instruction.precondition, input, page, mem, current.name);
             await current.instruction.act(page, input, mem);
@@ -99,7 +97,7 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
             const next = current.next?.(checkpoint);
             if (!next) {
                 if (terminals && !terminals.has(checkpoint.__state)) {
-                    throw new WaygraphError("WG_RUNGRAPH_NOT_TERMINAL", `runGraph: "${current.name}" resolved to "${checkpoint.__state}", which is not a registered terminal (expected one of: ${[...terminals].join(", ")})`);
+                    throw new WaygraphError("WG_RUNGRAPH_NOT_TERMINAL", MSG_RUNGRAPH_NOT_TERMINAL(current.name, checkpoint.__state, [...terminals].join(", ")));
                 }
                 return checkpoint;
             }

package/dist/core.d.ts

@@ -0,0 +1,14 @@
+export * from "./core/config.js";
+export * from "./core/run-graph.js";
+export * from "./core/flow.js";
+export * from "./core/block.js";
+export * from "./core/compose.js";
+export * from "./core/engine.js";
+export * from "./core/map-builder.js";
+export * from "./core/blocks/nav.js";
+export * from "./core/blocks/method.js";
+export * from "./core/blocks/page.js";
+export * from "./core/blocks/effect.js";
+export * from "./core/blocks/api.js";
+export * from "./core/locate.js";
+export * from "./core/branch-regression.js";

package/dist/core.js

@@ -0,0 +1,15 @@
+// Barrel: the engine lives in src/core/ (see src/ARCHITECTURE.md). Kept so existing imports of "./core.js" don't change.
+export * from "./core/config.js";
+export * from "./core/run-graph.js";
+export * from "./core/flow.js";
+export * from "./core/block.js";
+export * from "./core/compose.js";
+export * from "./core/engine.js";
+export * from "./core/map-builder.js";
+export * from "./core/blocks/nav.js";
+export * from "./core/blocks/method.js";
+export * from "./core/blocks/page.js";
+export * from "./core/blocks/effect.js";
+export * from "./core/blocks/api.js";
+export * from "./core/locate.js";
+export * from "./core/branch-regression.js";