waygraph 0.15.54 → 0.16.0

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

@@ -1,7 +1,8 @@
-import type { Checkpoint, DefinedBlock } from "../../types.js";
-import type { Trait } from "../../trait.js";
-import { defineBlock } from "../block.js";
-import type { MemKey } from "../../mem-page.js";
+import type { Checkpoint } from "../../checkpoint/checkpoint.js";
+import type { DefinedBlock } from "../block.js";
+import type { Trait } from "../../trait/trait.js";
+import type { RoutedBlockBase } from "../../checkpoint/route.js";
+import type { MemKey } from "../../mem/mem.js";
 /**
  * TypeScript salt over {@link defineBlock} for one-shot non-nav app steps
  * (submit, upload, finish, logout) - **methods** on a page. Same runtime Block;
@@ -15,25 +16,18 @@ export type MethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<st
     withVerify(verify: Trait[] | ((out: Out) => Trait[])): MethodBlock<In, Out>;
     modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): MethodBlock<In, Out>;
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): MethodBlock<In, Out>;
-    stubBefore(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
-    stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
-    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
-    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
-    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
-    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubBefore(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubAfter(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubOnError(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
 };
-/** @deprecated Prefer {@link MethodBlock} - same type; Action was the 0.7 name. */
-export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = MethodBlock<In, Out>;
 /** Builds a Block for one page action (fill, submit, click) that does not navigate. */
-export declare function defineMethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0]): MethodBlock<In, Out>;
-/** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
-export declare const defineActionBlock: typeof defineMethodBlock;
+export declare function defineMethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: RoutedBlockBase<In, Out>): MethodBlock<In, Out>;
 /** Options for `defineAssertBlock`: a Checkpoint to stay on and the Traits that must hold. */
 export interface AssertBlockOptions<Out extends Checkpoint<string> = Checkpoint<string>> {
     name: string;
     description?: string;
-    /** Self-loop target - the Checkpoint this assertion runs on and returns to. */
-    checkpoint: Out["__state"];
+    /** The Checkpoint this assertion runs on and returns to: its value (`Home`). */
+    checkpoint: Out;
     /**
      * Shorthand for the wait-then-assert shape found repeatedly in hand-written
      * assertion Blocks: waits for a heading with this accessible name before
@@ -44,12 +38,9 @@ export interface AssertBlockOptions<Out extends Checkpoint<string> = Checkpoint<
     waitForHeading?: string;
     verify: Trait[] | ((out: Out) => Trait[]);
     /** Mem keys this assertion's `verify` reads (e.g. a mem-aware Trait) - checked by preflight before the flow runs. */
-    requires?: readonly MemKey<any>[];
-    stubBefore?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    stubAfter?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    stubOnError?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+    requires?: readonly MemKey<unknown>[];
     /** Multi-step yap slides (demo only) - same field `Instruction.slides` exposes elsewhere. */
-    slides?: import("../../highlights.js").WaygraphSlidesOrFn<Out>;
+    slides?: import("../../stub/ring.js").WaygraphSlidesOrFn<Out>;
 }
 /**
  * Sugar for a self-loop-only "pure assertion" Block: no hand-written
@@ -67,7 +58,7 @@ export interface AssertBlockOptions<Out extends Checkpoint<string> = Checkpoint<
  *   verify: [Trait.visible(RawMaterialsSel.reorderBadge)],
  * });
  */
-export declare function defineAssertBlock<Out extends Checkpoint<string> = Checkpoint<string>>(options: AssertBlockOptions<Out>): AssertBlock<Out>;
+export declare function defineAssertBlock<Out extends Checkpoint<string>>(options: AssertBlockOptions<Out>): AssertBlock<Out>;
 /**
  * Self-loop verify Block from {@link defineAssertBlock}. Branded for
  * {@link MapBuilder.assert} (not accepted by `.method()`).
@@ -77,10 +68,7 @@ export type AssertBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Out,
     withVerify(verify: Trait[] | ((out: Out) => Trait[])): AssertBlock<Out>;
     modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): AssertBlock<Out>;
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): AssertBlock<Out>;
-    stubBefore(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
-    stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
-    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
-    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
-    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
-    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubBefore(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubAfter(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubOnError(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): AssertBlock<Out>;
 };

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

@@ -1,9 +1,9 @@
-// Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { checkpoint } from "../../types.js";
 import { defineBlock } from "../block.js";
+import { markRouteOf, routed } from "../../checkpoint/route.js";
 /** Builds a Block for one page action (fill, submit, click) that does not navigate. */
 export function defineMethodBlock(base) {
-    const built = defineBlock(base);
+    const built = defineBlock(routed(base));
+    markRouteOf(built, base);
     Object.defineProperty(built, "__waygraphSalt", {
         value: "method",
         enumerable: false,
@@ -11,8 +11,6 @@ export function defineMethodBlock(base) {
     });
     return built;
 }
-/** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
-export const defineActionBlock = defineMethodBlock;
 /**
  * Sugar for a self-loop-only "pure assertion" Block: no hand-written
  * `act`/`resolve`, just a name, a `checkpoint` tag, and a `verify` array.
@@ -34,32 +32,19 @@ export function defineAssertBlock(options) {
         name: options.name,
         ...(options.description ? { description: options.description } : {}),
         ...(options.requires ? { requires: options.requires } : {}),
+        // An assertion stays where it is: from and to are its one Checkpoint, and resolve lands there.
+        from: options.checkpoint,
+        to: options.checkpoint,
         instruction: {
             async act(page) {
                 if (options.waitForHeading !== undefined) {
                     await page.getByRole("heading", { name: options.waitForHeading }).waitFor();
                 }
             },
-            resolve: () => checkpoint(options.checkpoint),
             verify: options.verify,
-            ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
-            ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
-            ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
             ...(options.slides ? { slides: options.slides } : {}),
         },
     });
-    // Real bug this closes: `waygraph graph`'s static discovery only knows
-    // how to read a Block's Checkpoint tags from an EXPLICIT `<In, Out>`
-    // generic written in the source text (or, for Nav/Page Blocks, by calling
-    // their own input-independent `resolve()` directly). `defineAssertBlock`'s
-    // whole point is skipping that generic - called exactly as documented
-    // (`defineAssertBlock({ name, checkpoint, verify })`, no generics), it was
-    // silently invisible to both `waygraph graph` and the live Pilot menu
-    // ("2 Block(s) skipped (Out not resolvable)", confirmed live against a
-    // real veciro-waygraph session). `resolve()` here is ALSO input-
-    // independent (always `checkpoint(options.checkpoint)`), so the same
-    // resolve()-calling path Nav/Page Blocks already use is reused via this
-    // marker instead of requiring authors to write generics just to be found.
     Object.defineProperty(built, "__waygraphKind", {
         value: "assert",
         enumerable: false,

package/dist/{core/blocks → engine/block/kinds}/nav.d.ts

@@ -1,12 +1,13 @@
-import type { Block, Checkpoint, DefinedBlock, WaygraphHighlight } from "../../types.js";
-import type { Trait } from "../../trait.js";
-import { MemPage } from "../../mem-page.js";
-import type { MemKey } from "../../mem-page.js";
+import type { Block, DefinedBlock } from "../block.js";
+import type { Checkpoint } from "../../checkpoint/checkpoint.js";
+import type { Trait } from "../../trait/trait.js";
+import { MemPage } from "../../mem/mem.js";
+import type { MemKey } from "../../mem/mem.js";
 /**
  * A Block whose only possible action is navigating to a URL - built via
  * {@link defineNavBlock}, never with a hand-authored `act()`. Extends `Block`
  * (same shape `DefinedBlock`/`ComposedBlock` already use), so it drops into
- * `defineFlow([...])`, `connect()`, `composeBlock()` exactly like any other
+ * `map()`, `connect()`, `composeBlock()` exactly like any other
  * Block - no special-casing needed anywhere that only expects a `Block`.
  * See `openspec/specs/nav-block-and-check/spec.md` for why this exists.
  *
@@ -20,12 +21,9 @@ export type NavBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Checkpo
     withVerify(verify: Trait[] | ((out: Out) => Trait[])): NavBlock<Out>;
     modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): NavBlock<Out>;
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): NavBlock<Out>;
-    stubBefore(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
-    stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
-    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
-    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
-    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
-    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
+    stubBefore(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): NavBlock<Out>;
+    stubAfter(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): NavBlock<Out>;
+    stubOnError(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): NavBlock<Out>;
 };
 /**
  * `defineNavBlock`'s own options - exactly one of `url`/`click` required,
@@ -38,23 +36,19 @@ export type NavBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Checkpo
 export type NavBlockOptions<Out extends Checkpoint<string>> = {
     name: string;
     description?: string;
-    checkpoint: Out["__state"];
+    /** The Checkpoint this Nav lands on: its value (`Home`). */
+    checkpoint: Out;
     /**
      * Checkpoint tags this Nav can run from. Omit (the default) = reachable from anywhere. Set it for
      * a page that only exists after something else - e.g. every in-app page after sign-in - so route
      * finding (`auto --blocks`, `pilot reach`, `traverse`) goes through the sign-in steps instead of
      * jumping straight there from the login page.
-     * @example const SIGNED_IN = ["Dashboard", "CommandCenter"] as const; // src/states/
+     * @example const SIGNED_IN = [Dashboard, CommandCenter] as const; // src/states/
      * defineNavBlock({ ..., from: SIGNED_IN })
      */
-    from?: readonly string[];
-    requires?: readonly MemKey<any>[];
+    from?: readonly Checkpoint<string>[];
+    requires?: readonly MemKey<unknown>[];
     verify?: Trait[] | ((out: Out) => Trait[]);
-    stubBefore?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    stubAfter?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    stubOnError?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    /** @deprecated Prefer stubAfter. */
-    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
     /**
      * Live per-instance menu rows for `waygraph auto` (see {@link Block.instanceOptions}).
      * When set, the explore menu lists one row per option instead of a single
@@ -110,17 +104,13 @@ export declare function defineNavBlock<Out extends Checkpoint<string>>(options:
 export type NavClickBlockOptions<Out extends Checkpoint<string>> = {
     name: string;
     description?: string;
-    checkpoint: Out["__state"];
+    /** The Checkpoint this Nav lands on: its value (`Home`). */
+    checkpoint: Out;
     click: string | ((mem: MemPage) => string);
-    /** See {@link NavBlockOptions.from}. */
-    from?: readonly string[];
-    requires?: readonly MemKey<any>[];
+    /** Where the click can start: the Checkpoints whose page shows the link. Leave out for "from anywhere". */
+    from?: readonly Checkpoint<string>[];
+    requires?: readonly MemKey<unknown>[];
     verify?: Trait[] | ((out: Out) => Trait[]);
-    stubBefore?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    stubAfter?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    stubOnError?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    /** @deprecated Prefer stubAfter. */
-    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
     instanceOptions?: Block<Checkpoint<string>, Out>["instanceOptions"];
 };
 /** A Block whose only action is clicking a link; built with `defineNavClickBlock`. */
@@ -132,7 +122,7 @@ export declare function defineNavClickBlock<Out extends Checkpoint<string>>(opti
  * (which product row / which request id). Still a NavBlock / Block at runtime.
  */
 export type MemNavBlock<Out extends Checkpoint<string>> = NavBlock<Out> & {
-    requires: readonly MemKey<any>[];
+    requires: readonly MemKey<unknown>[];
     instanceOptions: NonNullable<Block<Checkpoint<string>, Out>["instanceOptions"]>;
 };
 /**
@@ -142,6 +132,6 @@ export type MemNavBlock<Out extends Checkpoint<string>> = NavBlock<Out> & {
  * several live rows/items rather than a fixed nav target. Still a Block.
  */
 export declare function defineMemNavBlock<Out extends Checkpoint<string>>(options: NavBlockOptions<Out> & {
-    requires: readonly MemKey<any>[];
+    requires: readonly MemKey<unknown>[];
     instanceOptions: NonNullable<Block<Checkpoint<string>, Out>["instanceOptions"]>;
 }): MemNavBlock<Out>;

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

@@ -1,6 +1,7 @@
-// Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { checkpoint } from "../../types.js";
+// A Nav Block: gets to a page, by URL or by clicking a link, and lands on that page's Checkpoint.
+import { checkpoint } from "../../checkpoint/checkpoint.js";
 import { defineBlock } from "../block.js";
+import { markRoute, tagsOf } from "../../checkpoint/route.js";
 /**
  * Builds a {@link NavBlock}. The generated `act()` is always exactly
  * `page.goto(url)` or `page.locator(click).click()` - never anything else,
@@ -34,14 +35,11 @@ export function defineNavBlock(options) {
                     await page.locator(selector).click();
                 }
             },
-            resolve: () => checkpoint(options.checkpoint),
+            resolve: () => checkpoint(options.checkpoint.__state),
             ...(options.verify ? { verify: options.verify } : {}),
-            ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
-            ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
-            ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
-            ...(options.highlights ? { highlights: options.highlights } : {}),
         },
     });
+    markRoute(built, options.from?.length ? tagsOf(options.from) : ["*"], [options.checkpoint.__state]);
     // Non-enumerable so it never shows up in Object.keys/JSON/autocomplete -
     // purely a runtime marker `waygraph check` (or anything else walking a
     // project's Blocks) can test for to tell a NavBlock apart from a regular
@@ -56,7 +54,7 @@ export function defineNavBlock(options) {
     // overlays can label "nav click" without re-parsing source.
     if (options.from && options.from.length > 0) {
         Object.defineProperty(built, "__waygraphNavFrom", {
-            value: [...options.from],
+            value: tagsOf(options.from),
             enumerable: false,
             configurable: false,
         });
@@ -94,10 +92,6 @@ export function defineNavClickBlock(options) {
         ...(options.description ? { description: options.description } : {}),
         ...(options.requires ? { requires: options.requires } : {}),
         ...(options.verify ? { verify: options.verify } : {}),
-        ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
-        ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
-        ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
-        ...(options.highlights ? { highlights: options.highlights } : {}),
         ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
     });
 }

package/dist/{core/blocks → engine/block/kinds}/page.d.ts

@@ -1,22 +1,19 @@
-import type { Block, Checkpoint, DefinedBlock, WaygraphHighlight } from "../../types.js";
-import type { Trait } from "../../trait.js";
-import { MemPage } from "../../mem-page.js";
-import type { MemKey } from "../../mem-page.js";
+import type { Block, DefinedBlock } from "../block.js";
+import type { Checkpoint } from "../../checkpoint/checkpoint.js";
+import type { Trait } from "../../trait/trait.js";
+import { MemPage } from "../../mem/mem.js";
+import type { MemKey } from "../../mem/mem.js";
+import type { SomeDefinedBlock } from "../block.js";
 /** One Block (or lazy factory) registered on a {@link PageBlock}. */
-export type PageMethodEntry = DefinedBlock<any, any> | (() => DefinedBlock<any, any>);
+export type PageMethodEntry = SomeDefinedBlock | (() => SomeDefinedBlock);
 /** Options for `definePageBlock`: the Checkpoint a page hub confirms and the Methods that hang off it. */
 export type PageBlockOptions<Out extends Checkpoint<string>> = {
     name: string;
     description?: string;
-    /** Checkpoint tag for this screen (hub). */
-    checkpoint: Out["__state"];
+    /** The Checkpoint this page hub confirms: its value (`Home`). */
+    checkpoint: Out;
     verify?: Trait[] | ((out: Out) => Trait[]);
-    stubBefore?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    stubAfter?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    stubOnError?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    /** @deprecated Prefer stubAfter. */
-    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
-    requires?: readonly MemKey<any>[];
+    requires?: readonly MemKey<unknown>[];
     /**
      * Methods available on this page. Array, or a record of Blocks / `() => Block`
      * factories (lazy so the page object can colocate method definitions).
@@ -42,16 +39,13 @@ export type PageBlockOptions<Out extends Checkpoint<string>> = {
 export type PageBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Checkpoint<string>, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
     readonly __wgFactory?: "page";
     /** Resolved method Blocks registered at define time. */
-    readonly methods: readonly DefinedBlock<any, any>[];
+    readonly methods: readonly SomeDefinedBlock[];
     withVerify(verify: Trait[] | ((out: Out) => Trait[])): PageBlock<Out>;
     modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): PageBlock<Out>;
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): PageBlock<Out>;
-    stubBefore(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
-    stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
-    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
-    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
-    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
-    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
+    stubBefore(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): PageBlock<Out>;
+    stubAfter(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): PageBlock<Out>;
+    stubOnError(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): PageBlock<Out>;
 };
 /** @see {@link PageBlockOptions} */
 export declare function definePageBlock<Out extends Checkpoint<string>>(options: PageBlockOptions<Out>): PageBlock<Out>;

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

@@ -1,6 +1,7 @@
-// Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { checkpoint } from "../../types.js";
+// A Page Block: "you have arrived" - the hub other pages navigate to, verified by what the page shows.
+import { checkpoint } from "../../checkpoint/checkpoint.js";
 import { defineBlock } from "../block.js";
+import { markRoute } from "../../checkpoint/route.js";
 function resolvePageMethods(methods) {
     if (!methods)
         return [];
@@ -30,14 +31,11 @@ export function definePageBlock(options) {
                 }
                 // else: arrival-only hub — previous Block already landed here
             },
-            resolve: () => checkpoint(options.checkpoint),
+            resolve: () => checkpoint(options.checkpoint.__state),
             ...(options.verify ? { verify: options.verify } : {}),
-            ...(options.stubBefore ? { stubBefore: options.stubBefore } : {}),
-            ...(options.stubAfter ? { stubAfter: options.stubAfter } : {}),
-            ...(options.stubOnError ? { stubOnError: options.stubOnError } : {}),
-            ...(options.highlights ? { highlights: options.highlights } : {}),
         },
     });
+    markRoute(built, ["*"], [options.checkpoint.__state]);
     Object.defineProperty(built, "__waygraphKind", {
         value: "page",
         enumerable: false,

package/dist/engine/checkpoint/checkpoint.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A Checkpoint is identified solely by its string tag - a phantom marker with no
+ * embedded data. Two Checkpoints with the same tag are the same state everywhere.
+ */
+export type Checkpoint<Tag extends string> = {
+    readonly __state: Tag;
+};
+/**
+ * Builds a Checkpoint - spells `__state` for you so no call site does it by hand.
+ * @example resolve: () => checkpoint("LoggedIn")
+ */
+export declare function checkpoint<Tag extends string>(tag: Tag): Checkpoint<Tag>;
+/**
+ * The type every entry Block's `In` must be - `runGraph` always seeds a fresh
+ * run with `checkpoint("__start__")` as the fake initial input, so a Block
+ * meant to lead off a Flow needs exactly this type. Exported so no project
+ * has to know or hand-type the `"__start__"` literal itself - the same reason
+ * `checkpoint()` exists instead of every call site spelling `{ __state: tag }`
+ * by hand.
+ * @example export const LoginBlock: Block<Start, LoggedIn> = { ... }
+ */
+export type Start = Checkpoint<"__start__">;

package/dist/engine/checkpoint/checkpoint.js

@@ -0,0 +1,8 @@
+// The states a flow moves between. A Checkpoint is just its tag; flows declare them once as values.
+/**
+ * Builds a Checkpoint - spells `__state` for you so no call site does it by hand.
+ * @example resolve: () => checkpoint("LoggedIn")
+ */
+export function checkpoint(tag) {
+    return { __state: tag };
+}

package/dist/engine/checkpoint/route.d.ts

@@ -0,0 +1,28 @@
+import type { Checkpoint } from "./checkpoint.js";
+import type { defineBlock } from "../block/block.js";
+/** Tags of one Checkpoint or a list of them. */
+export declare function tagsOf(refs: Checkpoint<string> | readonly Checkpoint<string>[]): string[];
+/**
+ * Records where a Block runs from and lands on, as tags, so the manifest can read the graph at runtime. `from` of `["*"]`
+ * means reachable from anywhere.
+ */
+export declare function markRoute(block: object, from: readonly string[], to: readonly string[]): void;
+export type BlockBase<In extends Checkpoint<string>, Out extends Checkpoint<string>> = Parameters<typeof defineBlock<In, Out>>[0];
+/**
+ * A Method or Effect that says where it runs: `from` (one Checkpoint value or a list; leave it out for "from anywhere") and
+ * `to`. `resolve` may be left out when `to` is one Checkpoint; it then always lands there.
+ */
+export type RoutedBlockBase<In extends Checkpoint<string>, Out extends Checkpoint<string>> = Omit<BlockBase<In, Out>, "instruction"> & {
+    from?: In | readonly In[];
+    to: Out | readonly Out[];
+    instruction: Omit<BlockBase<In, Out>["instruction"], "resolve" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+        resolve?: BlockBase<In, Out>["instruction"]["resolve"];
+    };
+};
+/** Turns a `from`/`to` Block base into the plain one `defineBlock` takes (filling `resolve` for a single `to`). */
+export declare function routed<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: RoutedBlockBase<In, Out>): BlockBase<In, Out>;
+/** Records a routed Block's `from`/`to` on the built Block. */
+export declare function markRouteOf(block: object, base: {
+    from?: Checkpoint<string> | readonly Checkpoint<string>[];
+    to: Checkpoint<string> | readonly Checkpoint<string>[];
+}): void;

package/dist/engine/checkpoint/route.js

@@ -0,0 +1,28 @@
+import { checkpoint } from "./checkpoint.js";
+/** Tags of one Checkpoint or a list of them. */
+export function tagsOf(refs) {
+    return (Array.isArray(refs) ? refs : [refs]).map((r) => r.__state);
+}
+/**
+ * Records where a Block runs from and lands on, as tags, so the manifest can read the graph at runtime. `from` of `["*"]`
+ * means reachable from anywhere.
+ */
+export function markRoute(block, from, to) {
+    Object.defineProperty(block, "__waygraphFrom", { value: [...from], enumerable: false, configurable: true });
+    Object.defineProperty(block, "__waygraphTo", { value: [...to], enumerable: false, configurable: true });
+}
+/** Turns a `from`/`to` Block base into the plain one `defineBlock` takes (filling `resolve` for a single `to`). */
+export function routed(base) {
+    const { from: _from, to, ...rest } = base;
+    if (rest.instruction.resolve)
+        return rest;
+    const targets = tagsOf(to);
+    if (targets.length !== 1) {
+        throw new Error(`waygraph: Block "${base.name}" lands on ${targets.join(" or ")}; give it a resolve() that picks one`);
+    }
+    return { ...rest, instruction: { ...rest.instruction, resolve: () => checkpoint(targets[0]) } };
+}
+/** Records a routed Block's `from`/`to` on the built Block. */
+export function markRouteOf(block, base) {
+    markRoute(block, base.from === undefined ? ["*"] : tagsOf(base.from), tagsOf(base.to));
+}

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

@@ -1,6 +1,5 @@
 import type { BrowserType } from "@playwright/test";
-import type { Layout } from "./run-graph.js";
-import type { ExtensionSpec } from "../extensions.js";
+import type { Layout } from "./run/run.js";
 /**
  * Resolves which `BrowserType` actually launches for a `mem`-only run (no
  * caller-supplied context) - `config.browsers[browserName]` if given,
@@ -12,6 +11,12 @@ import type { ExtensionSpec } from "../extensions.js";
  * `webkit` - same `.launch()` shape - so accepting one here costs nothing for
  * a consumer who never sets it.
  */
+/** A browser extension to load: a known name (`"hoppscotch"`), a Chrome Web Store id, a path, or `{ id, sha256 }`. */
+export type ExtensionSpec = string | {
+    id?: string;
+    path?: string;
+    sha256?: string;
+};
 export declare function resolveLauncher(browserName: "chromium" | "firefox" | "webkit", config: EngineConfig | undefined): BrowserType;
 /** Configures how an Engine launches its own browser - only used by `Flow.run(mem)` (no context given); ignored by `Flow.run(context, mem)`, since that context is already launched. */
 export interface EngineConfig {

package/dist/engine/config.js

@@ -0,0 +1,6 @@
+// EngineConfig: which browser a flow launches when it opens its own, how, and the layouts every step is checked against.
+import { chromium, firefox, webkit } from "@playwright/test";
+const LAUNCHERS = { chromium, firefox, webkit };
+export function resolveLauncher(browserName, config) {
+    return config?.browsers?.[browserName] ?? LAUNCHERS[browserName];
+}

package/dist/engine/engine.d.ts

@@ -0,0 +1,45 @@
+import type { Checkpoint } from "./checkpoint/checkpoint.js";
+import type { EngineConfig } from "./config.js";
+import { MapBuilder } from "./flow/map-builder.js";
+import type { MapBuilderOptions } from "./flow/map-builder.js";
+/** Where every `map()` starts: before its first step. */
+export type MapStart = Checkpoint<"__start__">;
+/**
+ * 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 declare class Engine {
+    readonly config: EngineConfig;
+    /** How flows from this engine launch their own browser, and the layouts every step is checked against. */
+    constructor(config?: EngineConfig);
+    /**
+     * Builds a flow, one kind-checked step at a time - 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?: MapBuilderOptions): MapBuilder<MapStart>;
+}
+/**
+ * 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 declare function map(options?: MapBuilderOptions & EngineConfig): MapBuilder<MapStart>;

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

@@ -1,5 +1,5 @@
-import { applyFlowOptions, buildFlow } from "./flow.js";
-import { MapBuilder } from "./map-builder.js";
+import { buildFlow, withSettings } from "./flow/flow.js";
+import { MapBuilder } from "./flow/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
@@ -9,15 +9,12 @@ import { MapBuilder } from "./map-builder.js";
  */
 export class Engine {
     config;
+    /** How flows from this engine launch their own browser, and the layouts every step is checked against. */
     constructor(config = {}) {
         this.config = config;
     }
-    defineFlow(blocks, options) {
-        return applyFlowOptions(buildFlow(blocks.slice(1, -1), this.config), options);
-    }
     /**
-     * Fluent, kind-checked alternative to `defineFlow([start, ...blocks, end])` -
-     * see {@link MapBuilder}. Real, direct request this responds to: pia/zsign's
+     * Builds a flow, one kind-checked step at a time - 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
@@ -36,9 +33,8 @@ export class Engine {
      *   .end();
      */
     map(options) {
-        const { homeOrigin, ...flowOptions } = options ?? {};
-        const define = this.defineFlow.bind(this);
-        return MapBuilder.begin((blocks, extra) => define(blocks, { ...flowOptions, ...extra }), homeOrigin);
+        const { homeOrigin, ...settings } = options ?? {};
+        return MapBuilder.begin((steps, flowSettings) => withSettings(buildFlow(steps, this.config), flowSettings), settings, homeOrigin);
     }
 }
 /**