waygraph 0.15.47 → 0.15.49

package/dist/analysis/graph.js

@@ -229,12 +229,12 @@ function isBlockLike(val) {
     const instruction = obj.instruction;
     return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
 }
-/** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
+/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
 function isNavBlockMarked(val) {
     const kind = val.__waygraphKind;
     return kind === "nav" || kind === "page";
 }
-/** Set by `defineAssertBlock` (non-enumerable) - see src/engine.ts. */
+/** Set by `defineAssertBlock` (non-enumerable) - see src/core.ts. */
 function isAssertBlockMarked(val) {
     return val.__waygraphKind === "assert";
 }

package/dist/auto-session/session.js

@@ -3,11 +3,11 @@ import { CONSOLE_LOG_MAX_ENTRIES, FULL_MODE_DEFAULT_DEPTH, FULL_MODE_MAX_NODES,
 import { instrumentPilotActions, installPersistentPilotOverlay, showPilotActivity, showPilotFixtures, showPilotVision, phaseToOverlayFixtures, describeOverlayFixtures, updatePilotOverlay } from "../pilot-overlay.js";
 import { buildExploreContext, buildExploreMenu } from "../session/auto-explore.js";
 import { MemPage } from "../mem-page.js";
-import { Engine } from "../engine.js";
+import { Engine } from "../core.js";
 import { detectHere, ensureLivePage, ensureMem, resolveBaseUrl, runOneBlock, seedDefaultMem } from "../session/auto-explore-run.js";
 import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from "../analysis/coverage-gap.js";
 import { runStubPhase } from "../highlights.js";
-import { verboseLog } from "../verbose-log.js";
+import { verboseLog } from "./verbose-log.js";
 import { findBlockPathDetailed } from "../analysis/graph.js";
 /**
  * Non-interactive explore session: same graph/library/mem/browser setup

package/dist/cli/discover.d.ts

@@ -22,7 +22,7 @@ export declare function isBlockLike(val: unknown): val is {
         act: unknown;
     };
 };
-/** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
+/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
 export declare function isNavBlockMarked(val: Record<string, unknown>): boolean;
 export declare const NAV_METHOD_CALLS: readonly ["page.goto(", "page.reload(", "page.goBack(", "page.goForward("];
 /**

package/dist/cli/discover.js

@@ -128,7 +128,7 @@ export function isBlockLike(val) {
     const instruction = obj.instruction;
     return instruction !== null && typeof instruction === "object" && typeof instruction?.act === "function";
 }
-/** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
+/** Set by `defineNavBlock` (non-enumerable) - see src/core.ts. */
 export function isNavBlockMarked(val) {
     return val.__waygraphKind === "nav";
 }

package/dist/cli.js

@@ -14,7 +14,7 @@
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
  */
-import { SKILL_FLAG_MAP, printSkillIndex, readSkillMarkdown } from "./agent-dive.js";
+import { SKILL_FLAG_MAP, printSkillIndex, readSkillMarkdown } from "./commands/agent-dive-scaffold.js";
 import { usage } from "./cli/usage.js";
 import { listCase, navCase } from "./commands/list.js";
 import { checkCase, typecheckCase, validateCase } from "./commands/check.js";

package/dist/{agent-dive.js → commands/agent-dive-scaffold.js}

@@ -6,8 +6,8 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 function packageRoot() {
-    // dist/agent-dive.js -> ..
-    return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    // dist/commands/agent-dive-scaffold.js -> ../..
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 }
 function agentsTemplateDir() {
     return join(packageRoot(), "templates", "agents");

package/dist/commands/agent-dive.js

@@ -1,5 +1,5 @@
 // Split out of the former 8,700-line cli.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { runAgentDive } from "../agent-dive.js";
+import { runAgentDive } from "./agent-dive-scaffold.js";
 import { resolve } from "node:path";
 import { existsSync, statSync } from "node:fs";
 export async function agentDiveCase(args) {

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

@@ -1,15 +1,15 @@
-import { WaygraphError } from "../errors.js";
+import { WaygraphError, MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_MODVERIFY_FUNCTION_FORM, MSG_MODVERIFY_NOT_FOUND_BY_INDEX, MSG_MODVERIFY_NOT_FOUND_BY_NAME, } from "../errors.js";
 export function findBlockIndex(middle, block) {
     if (typeof block === "number") {
         if (block < 0 || block >= middle.length) {
-            throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", `Flow: no Block at index ${block} in this flow (has ${middle.length})`);
+            throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX(block, middle.length));
         }
         return block;
     }
     const blockName = typeof block === "string" ? block : block.name;
     const index = middle.findIndex((b) => b.name === blockName);
     if (index === -1) {
-        throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", `Flow: no Block named "${blockName}" in this flow (has: ${middle.map((b) => b.name).join(", ")})`);
+        throw new WaygraphError("WG_FLOW_BLOCK_NOT_FOUND", MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME(blockName, middle.map((b) => b.name).join(", ")));
     }
     return index;
 }
@@ -229,15 +229,15 @@ export function withStubOnError(block, stub) {
 export function modVerify(block, nameOrIndex, newCheck) {
     const verify = block.instruction.verify;
     if (typeof verify === "function") {
-        throw new WaygraphError("WG_MODVERIFY_FUNCTION_FORM", `modVerify: "${block.name}" has a function-form verify, which has no fixed list to address into - use withVerify to replace it wholesale instead`);
+        throw new WaygraphError("WG_MODVERIFY_FUNCTION_FORM", MSG_MODVERIFY_FUNCTION_FORM(block.name));
     }
     const traits = verify ?? [];
     const index = typeof nameOrIndex === "number" ? nameOrIndex : traits.findIndex((t) => t.name === nameOrIndex);
     const existing = traits[index];
     if (!existing) {
         throw new WaygraphError("WG_MODVERIFY_NOT_FOUND", typeof nameOrIndex === "number"
-            ? `modVerify: "${block.name}" has no verify trait at index ${nameOrIndex} (has ${traits.length})`
-            : `modVerify: "${block.name}" has no verify trait named "${nameOrIndex}" (has: ${traits.map((t) => t.name).join(", ") || "none"})`);
+            ? MSG_MODVERIFY_NOT_FOUND_BY_INDEX(block.name, nameOrIndex, traits.length)
+            : MSG_MODVERIFY_NOT_FOUND_BY_NAME(block.name, nameOrIndex, traits.map((t) => t.name).join(", ")));
     }
     const replacement = typeof newCheck === "function"
         ? { name: typeof nameOrIndex === "string" ? nameOrIndex : existing.name, check: newCheck }

package/dist/core/blocks/api.d.ts

@@ -0,0 +1,54 @@
+import type { Checkpoint, DefinedBlock } from "../../types.js";
+import type { Trait } from "../../trait.js";
+import { MemPage } from "../../mem-page.js";
+import type { MemKey } from "../../mem-page.js";
+import type { APIRequestContext, APIResponse } from "@playwright/test";
+/** What `resolve`/`verify` see: the response's status and parsed body, nothing Playwright-specific. */
+export interface ApiCallResult {
+    status: number;
+    ok: boolean;
+    /** `response.json()` if the body parses as JSON, else the raw text (or `undefined` if neither). */
+    body: unknown;
+}
+export interface ApiBlockOptions<In extends Checkpoint<string>, Out extends Checkpoint<string>> {
+    name: string;
+    description?: string;
+    /**
+     * Make the request - `request` is Playwright's own `page.request` (same cookies/origin as the
+     * browser context, so an authenticated UI session carries over to the API call for free).
+     * @example call: ({ request }) => request.get("/api/orders/1")
+     */
+    call: (ctx: {
+        request: APIRequestContext;
+        mem: MemPage;
+    }) => Promise<APIResponse>;
+    /**
+     * HTTP method shown in the network-tab overlay (GET/POST/PATCH/...) - `APIResponse` (unlike a
+     * page's own `Response`) carries no back-reference to the request that produced it, so this
+     * can't be read back automatically; defaults to "GET" if omitted. Purely cosmetic - never
+     * affects the actual request `call` makes.
+     * @example method: "POST"
+     */
+    method?: string;
+    /** Pure, like every other Block's resolve - classifies the response into a Checkpoint tag. */
+    resolve: (result: ApiCallResult) => Out;
+    verify?: Trait[] | ((out: Out) => Trait[]);
+    requires?: readonly MemKey<any>[];
+    stubBefore?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubAfter?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+    stubOnError?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+}
+/**
+ * A Block whose `act()` is a real HTTP request, not a page interaction - lets one Flow narrate a
+ * UI step (`.gotoPage()`) and a backend check (`.method(checkOrderCreated)`) as the same state
+ * machine, checked by the same Trait/verify system. Runs through `page.request`, so it shares the
+ * browser context's cookies/origin - no separate auth dance for an already-logged-in session.
+ * @example
+ * const CheckOrderCreated = defineApiBlock<LoggedIn, OrderConfirmed | OrderFailed>({
+ *   name: "check-order-created",
+ *   call: ({ request }) => request.get("/api/orders/latest"),
+ *   resolve: (r) => (r.ok ? checkpoint("OrderConfirmed") : checkpoint("OrderFailed")),
+ *   verify: [Trait.disabled],
+ * });
+ */
+export declare function defineApiBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(options: ApiBlockOptions<In, Out>): DefinedBlock<In, Out>;

package/dist/core/blocks/api.js

@@ -0,0 +1,75 @@
+import { defineBlock } from "../block.js";
+import { key } from "../../mem-page.js";
+// Internal scratch key threading act()'s result to observe()/resolve() - Instruction has no other
+// channel for this (resolve is pure, given only what observe returns). Identity-keyed, so this can
+// never collide with a real author's own MemKey even if names happened to match; safe to share one
+// instance across every ApiBlock since runGraph runs act->observe->resolve fully serially per Block.
+const API_RESULT_SCRATCH = key("__wgApiBlockResult");
+/**
+ * A Block whose `act()` is a real HTTP request, not a page interaction - lets one Flow narrate a
+ * UI step (`.gotoPage()`) and a backend check (`.method(checkOrderCreated)`) as the same state
+ * machine, checked by the same Trait/verify system. Runs through `page.request`, so it shares the
+ * browser context's cookies/origin - no separate auth dance for an already-logged-in session.
+ * @example
+ * const CheckOrderCreated = defineApiBlock<LoggedIn, OrderConfirmed | OrderFailed>({
+ *   name: "check-order-created",
+ *   call: ({ request }) => request.get("/api/orders/latest"),
+ *   resolve: (r) => (r.ok ? checkpoint("OrderConfirmed") : checkpoint("OrderFailed")),
+ *   verify: [Trait.disabled],
+ * });
+ */
+export function defineApiBlock(options) {
+    const built = defineBlock({
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        instruction: {
+            async act(page, _input, mem) {
+                const startedAt = Date.now();
+                const response = await options.call({ request: page.request, mem });
+                const ms = Date.now() - startedAt;
+                let body;
+                try {
+                    body = await response.json();
+                }
+                catch {
+                    body = await response.text().catch(() => undefined);
+                }
+                mem.set(API_RESULT_SCRATCH, { status: response.status(), ok: response.ok(), body });
+                // Best-effort, demo-only visibility - an API step has no DOM change and no ring of its own,
+                // so without this it's a silent title flash. No-ops outside a demo/pilot/auto run (see
+                // addNetworkEntry's own guard) and never fails the Block if painting the panel throws.
+                // Same network-tab panel real page traffic feeds too (network-capture.js) - this is the
+                // page.request side of it (a separate APIRequestContext, never seen by page.on('request')).
+                try {
+                    // recordNetworkEntry, not a bare addNetworkEntry evaluate - it also persists this entry
+                    // to page.__wgNetworkHistory (Node-side, survives navigation), so it isn't lost the
+                    // moment a later step in the same Flow navigates and wipes the panel's DOM.
+                    const { recordNetworkEntry } = await import("../../runner/network-capture.js");
+                    await recordNetworkEntry(page, {
+                        method: options.method || "GET",
+                        url: response.url(),
+                        status: response.status(),
+                        ok: response.ok(),
+                        ms,
+                        resHeaders: response.headers(),
+                        resBody: typeof body === "string" ? body : body !== undefined ? JSON.stringify(body) : undefined,
+                    });
+                }
+                catch {
+                    /* overlay not installed / page already closed - not this Block's job to report that */
+                }
+            },
+            async observe(_page, mem) {
+                return mem.get(API_RESULT_SCRATCH);
+            },
+            resolve: (observed) => options.resolve(observed),
+            ...(options.verify !== undefined ? { verify: options.verify } : {}),
+            ...(options.stubBefore !== undefined ? { stubBefore: options.stubBefore } : {}),
+            ...(options.stubAfter !== undefined ? { stubAfter: options.stubAfter } : {}),
+            ...(options.stubOnError !== undefined ? { stubOnError: options.stubOnError } : {}),
+        },
+    });
+    Object.defineProperty(built, "__waygraphKind", { value: "api", enumerable: false, configurable: false });
+    return built;
+}

package/dist/{engine → core}/blocks/effect.d.ts

@@ -1,7 +1,7 @@
 import type { Block, Checkpoint, DefinedBlock } from "../../types.js";
 import type { MemKey } from "../../mem-page.js";
 import type { Trait } from "../../trait.js";
-import { defineBlock } from "../core.js";
+import { defineBlock } from "../block.js";
 /**
  * TypeScript salt over {@link defineBlock}: same runtime Block, but the type
  * forces `requires` + `instanceOptions` so `waygraph auto` can list one menu

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

@@ -1,4 +1,4 @@
-import { defineBlock } from "../core.js";
+import { defineBlock } from "../block.js";
 /**
  * {@link defineBlock} constrained for effect-style instance menus: `requires` +
  * `instanceOptions` are mandatory. Prefer this when the Block adds / removes /

package/dist/{engine → core}/blocks/method.d.ts

@@ -1,6 +1,6 @@
 import type { Checkpoint, DefinedBlock } from "../../types.js";
 import type { Trait } from "../../trait.js";
-import { defineBlock } from "../core.js";
+import { defineBlock } from "../block.js";
 import type { MemKey } from "../../mem-page.js";
 /**
  * TypeScript salt over {@link defineBlock} for one-shot non-nav app steps

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

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

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

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

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

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

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

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

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

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

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

@@ -2,10 +2,8 @@ import type { Block, Checkpoint } from "../types.js";
 import type { EngineConfig } from "./config.js";
 import type { EndMarker, StartMarker } from "./run-graph.js";
 import type { Flow } from "./flow.js";
-import type { NavBlock } from "./blocks/nav.js";
-import type { PageBlock } from "./blocks/page.js";
-import type { AssertBlock, MethodBlock } from "./blocks/method.js";
-import type { EffectBlock } from "./blocks/effect.js";
+import { MapBuilder } from "./map-builder.js";
+import type { MapBuilderOptions } from "./map-builder.js";
 type S = Checkpoint<"__start__">;
 /**
  * Holds engine-level configuration shared across every flow defined from it -
@@ -187,135 +185,6 @@ export declare class Engine {
      */
     map(options?: MapBuilderOptions): MapBuilder<S>;
 }
-export interface MapBuilderOptions {
-    /**
-     * This project's own origin (e.g. `"https://app.example.com"`) - enables
-     * `.gotoPage()`/`.gotoExternal()`'s origin check against a Block's static
-     * `url`. Omit to skip that check entirely (still fully kind-checked either
-     * way; only the internal/external origin distinction is opt-in).
-     */
-    homeOrigin?: string;
-}
-/**
- * Fluent builder over {@link Engine.defineFlow} - see `map()`'s own doc
- * comment for why this exists. Each step method is scoped to exactly the
- * Block kind its name promises, checked at RUNTIME against the
- * `__waygraphKind`/`__waygraphSalt` markers `defineNavBlock`/`definePageBlock`/
- * `defineAssertBlock`/`defineMethodBlock`/`defineEffectBlock` already set
- * (the same markers `graph.ts` and `map-check.ts` trust) - not just a type
- * hint, since a hand-rolled object can satisfy the TypeScript `Block<In,Out>`
- * shape without ever going through a real factory. Each call also
- * typechecks the accumulated Checkpoint chain exactly like `defineFlow`'s
- * own tuple overloads do (a step's `In` must equal the previous step's
- * `Out`) - this is what "no teleporting" means: there is no method on this
- * builder that can skip from one Checkpoint to an unrelated one without a
- * real, kind-correct Block in between.
- */
-export declare class MapBuilder<Out extends Checkpoint<string>> {
-    private readonly engine;
-    private readonly steps;
-    private readonly homeOrigin;
-    private readonly ff;
-    private constructor();
-    /** @internal - use `engine.map()` or the standalone `map()` export. */
-    static begin(engine: Engine, homeOrigin: string | undefined): MapBuilder<S>;
-    /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
-    start(): MapBuilder<Out>;
-    /**
-     * Open a fast-forward window - steps until {@link ffEnd} collapse into one
-     * opaque `fastForwardComposeBlock` (blitz theater). Kind/salt checks still
-     * run on each inner step as it is added.
-     */
-    ffStart(name?: string): MapBuilder<Out>;
-    /**
-     * Close the current fast-forward window and append one FFCompose step.
-     * Throws if empty or if {@link ffStart} was never opened.
-     */
-    ffEnd(): MapBuilder<Out>;
-    private appendStep;
-    /**
-     * Appends an internal navigation/page-arrival step - requires a Block from
-     * `defineNavBlock`/`defineMemNavBlock`/`definePageBlock`. Throws if given
-     * anything else, including a `homeOrigin`-mismatched static `url`.
-     * Compile-time: {@link NavBlock} or {@link PageBlock} only (not Assert/Method).
-     */
-    gotoPage<NextOut extends Checkpoint<string>>(block: (NavBlock<NextOut> | PageBlock<NextOut>) & {
-        name: string;
-    }): MapBuilder<NextOut>;
-    /**
-     * Appends a genuinely cross-origin navigation step (e.g. `(external)/`
-     * Blocks in the Waygraph Map convention: mailpit, maildrop.cc) - same
-     * kind requirement as {@link gotoPage}, plus the inverse `homeOrigin` check.
-     * Compile-time: {@link NavBlock} or {@link PageBlock} only.
-     */
-    gotoExternal<NextOut extends Checkpoint<string>>(block: (NavBlock<NextOut> | PageBlock<NextOut>) & {
-        name: string;
-    }): MapBuilder<NextOut>;
-    /**
-     * Appends a self-loop verification step - requires a Block from
-     * `defineAssertBlock`. Compile-time: {@link AssertBlock} only (not `.method()`).
-     */
-    assert(block: AssertBlock<Out> & {
-        name: string;
-    }): MapBuilder<Out>;
-    /**
-     * Appends a non-navigating page action (submit, upload, add/remove an
-     * instance) - requires a Block from `defineMethodBlock`/`defineActionBlock`/
-     * `defineEffectBlock`/`defineMemEffectBlock`.
-     * Compile-time: {@link MethodBlock} or {@link EffectBlock} only - Assert
-     * Blocks must use `.assert()`. Runtime also rejects `__waygraphKind =
-     * "assert"` (those still carry method salt from the factory internals).
-     */
-    method<NextOut extends Checkpoint<string>>(block: (MethodBlock<Out, NextOut> | EffectBlock<Out, NextOut>) & {
-        name: string;
-    }): MapBuilder<NextOut>;
-    /**
-     * Branch: run everything added so far, then continue into whichever `routes[tag]` matches the
-     * resolved Checkpoint's tag - same page, same context, same mem. `routes` must cover every tag
-     * of `Out` (a missing one is a compile error, matching {@link branch}'s own exhaustiveness);
-     * `null` means that tag is terminal (the branched Flow just returns that Checkpoint).
-     *
-     * Each non-null route is a function, not a ready-made `Flow` - a fresh Flow always starts at the
-     * special `S` (start) Checkpoint, but a branch's blocks start from the TAG it routes on (e.g.
-     * `LoggedIn`), so the function is handed a brand-new `MapBuilder` already seeded at that exact
-     * Checkpoint to chain `.method()/.gotoPage()/.assert()/.end()` (or another `.branch()`) off of.
-     *
-     * Real gap this fixes: the plain `branch()` helper's `.next` routing is only ever consulted by
-     * `runGraph`'s own graph walk - `defineFlow`/`.end()` compose steps pairwise via `connect()`,
-     * which never looks at `.next` at all, so a Map-built Flow had no way to branch. This method
-     * branches at the Flow level instead: it finalizes the prefix, runs it, and picks the next Flow
-     * itself once the real tag is known - no engine-level routing involved.
-     *
-     * Only the `run(context, mem[, options])` signature is supported - the page must survive across
-     * the branch, and the bare `run(mem, config)` convenience form always closes its own browser
-     * before a tag is even known, so it throws instead of silently reopening a fresh (state-losing) page.
-     *
-     * The route's first Block still sees `input.__state === "__start__"` in `act()`, not the tag that
-     * routed there - `runGraph` seeds every Flow's entry Block that way unconditionally, the same as
-     * any standalone `defineFlow([start, block, end])` already does. Read `page`/`mem`, not `input`,
-     * in `act()` - every real Block in this codebase already follows that convention.
-     *
-     * @example
-     * map({ homeOrigin }).gotoPage(NavCartBlock).branch({
-     *   ItemInCart: (m) => m.method(RemoveFromCartBlock).end(),
-     *   LoggedIn: (m) => m.method(AddToCartBlock).end(),
-     * });
-     */
-    branch<Routes extends {
-        [K in Out["__state"]]: ((m: MapBuilder<Extract<Out, Checkpoint<K>>>) => Flow<any>) | null;
-    }>(routes: Routes): Flow<{
-        [K in keyof Routes & string]: Routes[K] extends (m: any) => Flow<infer R> ? R : Extract<Out, Checkpoint<K>>;
-    }[keyof Routes & string]>;
-    /**
-     * Finalizes this chain into a real, runnable {@link Flow} - same object
-     * `defineFlow` returns, so `withBlockVerify`/`modBlockVerify` and every
-     * `withTitle`/`withHighlightFixtures`/etc. decorator still apply exactly
-     * as they do today; this builder only changes how the chain is assembled,
-     * never what it produces. Throws if no step was ever added - an empty map
-     * isn't a flow.
-     */
-    end(): Flow<Out>;
-}
 /**
  * Standalone convenience for `new Engine(config).map(options)` - use this
  * when a call site doesn't otherwise need its own `Engine` instance (no

package/dist/core/engine.js

@@ -0,0 +1,50 @@
+import { buildFlow } from "./flow.js";
+import { MapBuilder } from "./map-builder.js";
+/**
+ * Holds engine-level configuration shared across every flow defined from it -
+ * for now, just how to launch a browser when a Flow owns its own
+ * (`headless`/`browserName`/`slowMo`); traits/interstitials/watchers land here
+ * in a later change.
+ * @example const engine = new Engine({ headless: false, slowMo: 250 });
+ */
+export class Engine {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    defineFlow(blocks) {
+        return buildFlow(blocks.slice(1, -1), this.config);
+    }
+    /**
+     * Fluent, kind-checked alternative to `defineFlow([start, ...blocks, end])` -
+     * see {@link MapBuilder}. Real, direct request this responds to: pia/zsign's
+     * own agents kept hand-editing/hand-composing Blocks into ad hoc shapes
+     * ("locks" convention tried, still got broken) - `map()` forces every step
+     * through this Engine's own `define*Block` factories (checked by the same
+     * `__waygraphKind`/`__waygraphSalt` runtime markers `graph.ts`/`map-check.ts`
+     * already trust), so a hand-rolled plain-object Block can never silently
+     * pass as a real navigation/assertion/method step. `homeOrigin`, if given,
+     * also gates `.gotoPage()`/`.gotoExternal()` against each Nav/Page Block's
+     * own static `url` (skipped, honestly, for click-based/dynamic nav - not
+     * statically checkable, same limitation `map-check.ts` already documents).
+     * @example
+     * const flow = engine.map({ homeOrigin: "https://app.example.com" })
+     *   .start()
+     *   .gotoPage(NavHomeBlock)
+     *   .assert(AssertHelloBlock)
+     *   .gotoExternal(NavMailpitBlock)
+     *   .end();
+     */
+    map(options) {
+        return MapBuilder.begin(this.defineFlow.bind(this), options?.homeOrigin);
+    }
+}
+/**
+ * Standalone convenience for `new Engine(config).map(options)` - use this
+ * when a call site doesn't otherwise need its own `Engine` instance (no
+ * shared `headless`/`slowMo`/`layouts` across several flows).
+ * @example const flow = map({ homeOrigin: "https://app.example.com" }).gotoPage(NavHomeBlock).end();
+ */
+export function map(options) {
+    return new Engine(options).map(options);
+}

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

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