waygraph 0.15.23 → 0.15.25

package/dist/engine/blocks/method.js

@@ -0,0 +1,70 @@
+// 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";
+export function defineMethodBlock(base) {
+    const built = defineBlock(base);
+    Object.defineProperty(built, "__waygraphSalt", {
+        value: "method",
+        enumerable: false,
+        configurable: false,
+    });
+    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.
+ * `resolve` is generated from the one `checkpoint` field given, closing the
+ * copy/rename footgun where a hand-restated checkpoint string can silently
+ * drift wrong across a copy/pasted file. Mirrors `definePageBlock`'s own
+ * construction pattern (flat options in, `defineBlock` built internally).
+ * See openspec/changes/waygraph-agent-skill-hardening/spec.md.
+ * @example
+ * defineAssertBlock({
+ *   name: "assert-raw-materials-table",
+ *   checkpoint: "RawMaterials",
+ *   waitForHeading: "Raw Materials & Lead Times",
+ *   verify: [Trait.visible(RawMaterialsSel.reorderBadge)],
+ * });
+ */
+export function defineAssertBlock(options) {
+    const built = defineMethodBlock({
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        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,
+        configurable: false,
+    });
+    // Brand for map().assert() - distinct from MethodBlock so .method(assert)
+    // is a compile error even though runtime still carries method salt.
+    return built;
+}

package/dist/engine/blocks/nav.d.ts

@@ -0,0 +1,138 @@
+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";
+/**
+ * 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
+ * Block - no special-casing needed anywhere that only expects a `Block`.
+ * See `openspec/specs/nav-block-and-check/spec.md` for why this exists.
+ *
+ * `__wgFactory` is a TypeScript-only brand so {@link MapBuilder.gotoPage} /
+ * {@link MapBuilder.gotoExternal} can reject Assert/Method Blocks at compile
+ * time (runtime still checks `__waygraphKind`). Decorate methods are re-stated
+ * (via Omit) so `.stubBefore()` / `.withVerify()` keep the brand.
+ */
+export type NavBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Checkpoint<string>, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "nav";
+    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>;
+    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
+    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
+    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
+    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
+    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
+    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
+    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): NavBlock<Out>;
+};
+/**
+ * `defineNavBlock`'s own options - exactly one of `url`/`click` required,
+ * enforced at compile time (giving both, or neither, is a type error - see
+ * `typecheck/nav-block.types.ts`). `checkpoint` is the tag this NavBlock
+ * resolves to once navigation completes - a NavBlock never branches on
+ * observed evidence the way a regular Block can, so there's no `resolve`
+ * logic to author; it always just declares "arrived."
+ */
+export type NavBlockOptions<Out extends Checkpoint<string>> = {
+    name: string;
+    description?: string;
+    checkpoint: Out["__state"];
+    requires?: readonly MemKey<any>[];
+    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
+     * generic nav edge - used by {@link defineMemNavBlock}.
+     */
+    instanceOptions?: Block<Checkpoint<string>, Out>["instanceOptions"];
+} & ({
+    /**
+     * Direct URL navigation. Accepts a plain string or a function
+     * `(mem) => string` for parameterized routes (e.g.
+     * `/dashboard/requests/:id` with a real id read from mem). The
+     * escape hatch for the few real cases with no click path to get
+     * there (a deep link from an email, a public share link) - not for
+     * skipping past navigation an agent didn't feel like finding. Prefer
+     * `click` whenever the target app actually has one.
+     */
+    url: string | ((mem: MemPage) => string);
+    click?: never;
+} | {
+    /**
+     * Navigates by clicking a real element already on the page (a nav
+     * link, a sidebar item) instead of teleporting straight to a URL -
+     * the opinionated default. Accepts a Playwright selector string, or
+     * a function `(mem) => selector` for a target that depends on mem
+     * (e.g. clicking the row for a specific id). Verifying arrival is
+     * `verify`'s job (typically `Trait.url(...)`), same as a `url`-based
+     * NavBlock - the click itself is only ever awaited for its own
+     * completion, not for whatever navigation it triggers.
+     */
+    click: string | ((mem: MemPage) => string);
+    url?: never;
+});
+/**
+ * Builds a {@link NavBlock}. The generated `act()` is always exactly
+ * `page.goto(url)` or `page.locator(click).click()` - never anything else,
+ * never author-supplied. Callers get a real `Page` here internally (the one
+ * legitimate place navigation belongs); `defineBlock`'s own `ActionPage`
+ * narrowing is what discourages navigation everywhere else, and never
+ * applies to this generated function since no author ever writes it by
+ * hand.
+ * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
+ * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
+ * @example defineNavClickBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ * For click-nav in app code prefer {@link defineNavClickBlock} (url stays here).
+ */
+export declare function defineNavBlock<Out extends Checkpoint<string>>(options: NavBlockOptions<Out>): NavBlock<Out>;
+/**
+ * Click-only {@link NavBlock}. Same runtime as {@link defineNavBlock} with
+ * `click` - use this in app code so you never wonder whether a Nav is url or
+ * click (no `__waygraphNavClick` sniffing at author time). Prefer
+ * {@link defineNavBlock} only for `url` / `goto` deep links.
+ */
+export type NavClickBlockOptions<Out extends Checkpoint<string>> = {
+    name: string;
+    description?: string;
+    checkpoint: Out["__state"];
+    click: string | ((mem: MemPage) => string);
+    requires?: readonly MemKey<any>[];
+    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"];
+};
+export type NavClickBlock<Out extends Checkpoint<string>> = NavBlock<Out>;
+/** @see {@link NavClickBlockOptions} */
+export declare function defineNavClickBlock<Out extends Checkpoint<string>>(options: NavClickBlockOptions<Out>): NavClickBlock<Out>;
+/**
+ * TypeScript salt over {@link defineNavBlock}: mem-picked destination
+ * (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>[];
+    instanceOptions: NonNullable<Block<Checkpoint<string>, Out>["instanceOptions"]>;
+};
+/**
+ * {@link defineNavBlock} constrained to mem-picked navigation: requires +
+ * instanceOptions mandatory, and `click`/`url` should depend on that mem
+ * (typically `click: (mem) => …`). Prefer this when the Block opens one of
+ * 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>[];
+    instanceOptions: NonNullable<Block<Checkpoint<string>, Out>["instanceOptions"]>;
+}): MemNavBlock<Out>;

package/dist/engine/blocks/nav.js

@@ -0,0 +1,110 @@
+// 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";
+/**
+ * Builds a {@link NavBlock}. The generated `act()` is always exactly
+ * `page.goto(url)` or `page.locator(click).click()` - never anything else,
+ * never author-supplied. Callers get a real `Page` here internally (the one
+ * legitimate place navigation belongs); `defineBlock`'s own `ActionPage`
+ * narrowing is what discourages navigation everywhere else, and never
+ * applies to this generated function since no author ever writes it by
+ * hand.
+ * @example defineNavBlock({ name: "nav-web-login", checkpoint: "LoginForm", url: "/login" })
+ * @example defineNavBlock({ name: "nav-web-request-detail", checkpoint: "RequestDetail", url: (mem) => `/dashboard/requests/${mem.get(RequestId.key)}` })
+ * @example defineNavClickBlock({ name: "nav-web-documents", checkpoint: "DocumentsList", click: "nav >> text=Documents" })
+ * For click-nav in app code prefer {@link defineNavClickBlock} (url stays here).
+ */
+export function defineNavBlock(options) {
+    const built = defineBlock({
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
+        instruction: {
+            async act(page, _input, mem) {
+                if (options.url !== undefined) {
+                    const url = typeof options.url === "function" ? options.url(mem) : options.url;
+                    await page.goto(url);
+                }
+                else {
+                    // Always Locator.click() so step-mode's demo cursor/pulse patch
+                    // (instrumentInteractionHighlighting) sees NavBlock click-nav -
+                    // never page.click() / goto teleport.
+                    const selector = typeof options.click === "function" ? options.click(mem) : options.click;
+                    await page.locator(selector).click();
+                }
+            },
+            resolve: () => checkpoint(options.checkpoint),
+            ...(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 } : {}),
+        },
+    });
+    // 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
+    // one, since the TypeScript type alone (NavBlock = DefinedBlock) doesn't
+    // survive to runtime.
+    Object.defineProperty(built, "__waygraphKind", {
+        value: "nav",
+        enumerable: false,
+        configurable: false,
+    });
+    // Demo/step tooling: remember the click selector (or factory) so
+    // overlays can label "nav click" without re-parsing source.
+    if (options.click !== undefined) {
+        Object.defineProperty(built, "__waygraphNavClick", {
+            value: options.click,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    // Same idea, for the url case - only when it's a plain string (a
+    // function URL is mem-dependent/dynamic, can't be compared statically
+    // without running it). Real, direct request this responds to: an agent
+    // driving Blind Pilot had no structured way to ask "which of the links
+    // on THIS page are already covered by a NavBlock" without re-parsing
+    // every nav.block.ts's own source - this is what `AutoSession` now reads
+    // to warn about real, unmapped nav links found live on the page.
+    if (typeof options.url === "string") {
+        Object.defineProperty(built, "__waygraphNavUrl", {
+            value: options.url,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    return built;
+}
+/** @see {@link NavClickBlockOptions} */
+export function defineNavClickBlock(options) {
+    return defineNavBlock({
+        name: options.name,
+        checkpoint: options.checkpoint,
+        click: options.click,
+        ...(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 } : {}),
+    });
+}
+/**
+ * {@link defineNavBlock} constrained to mem-picked navigation: requires +
+ * instanceOptions mandatory, and `click`/`url` should depend on that mem
+ * (typically `click: (mem) => …`). Prefer this when the Block opens one of
+ * several live rows/items rather than a fixed nav target. Still a Block.
+ */
+export function defineMemNavBlock(options) {
+    const built = defineNavBlock(options);
+    Object.defineProperty(built, "__waygraphMemKind", {
+        value: "nav",
+        enumerable: false,
+        configurable: false,
+    });
+    return built;
+}

package/dist/engine/blocks/page.d.ts

@@ -0,0 +1,59 @@
+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";
+/** One Block (or lazy factory) registered on a {@link PageBlock}. */
+export type PageMethodEntry = DefinedBlock<any, any> | (() => DefinedBlock<any, any>);
+export type PageBlockOptions<Out extends Checkpoint<string>> = {
+    name: string;
+    description?: string;
+    /** Checkpoint tag for this screen (hub). */
+    checkpoint: Out["__state"];
+    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>[];
+    /**
+     * Methods available on this page. Array, or a record of Blocks / `() => Block`
+     * factories (lazy so the page object can colocate method definitions).
+     */
+    methods?: readonly PageMethodEntry[] | Record<string, PageMethodEntry>;
+    /**
+     * Optional deep-link onto this page (`goto`). XOR with `click`. Omit when the
+     * hub is arrival-only (previous Block already resolved here).
+     */
+    url?: string | ((mem: MemPage) => string);
+    /** Optional click-nav onto this page. XOR with `url`. */
+    click?: string | ((mem: MemPage) => string);
+    instanceOptions?: Block<Checkpoint<string>, Out>["instanceOptions"];
+};
+/**
+ * Page hub Block: one Checkpoint = this screen; methods hang off the hub for
+ * readability / auto grouping. Runtime is still a Block (`__waygraphKind = "page"`).
+ * `act` is goto/click when `url`/`click` is set, otherwise a no-op (already here).
+ * Child methods stay ordinary Blocks for graph edges - the page only registers them.
+ * Branded `__wgFactory: "page"` (not `"nav"`) - both are accepted by
+ * {@link MapBuilder.gotoPage} / {@link MapBuilder.gotoExternal}.
+ */
+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>[];
+    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>;
+    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
+    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
+    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
+    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
+    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
+    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
+    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): PageBlock<Out>;
+};
+/** @see {@link PageBlockOptions} */
+export declare function definePageBlock<Out extends Checkpoint<string>>(options: PageBlockOptions<Out>): PageBlock<Out>;

package/dist/engine/blocks/page.js

@@ -0,0 +1,91 @@
+// 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";
+function resolvePageMethods(methods) {
+    if (!methods)
+        return [];
+    const entries = Array.isArray(methods) ? methods : Object.values(methods);
+    return entries.map((entry) => (typeof entry === "function" ? entry() : entry));
+}
+/** @see {@link PageBlockOptions} */
+export function definePageBlock(options) {
+    if (options.url !== undefined && options.click !== undefined) {
+        throw new Error(`definePageBlock("${options.name}"): pass url XOR click (or neither for arrival-only hub)`);
+    }
+    const methodList = resolvePageMethods(options.methods);
+    const built = defineBlock({
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
+        instruction: {
+            async act(page, _input, mem) {
+                if (options.url !== undefined) {
+                    const url = typeof options.url === "function" ? options.url(mem) : options.url;
+                    await page.goto(url);
+                }
+                else if (options.click !== undefined) {
+                    const selector = typeof options.click === "function" ? options.click(mem) : options.click;
+                    await page.locator(selector).click();
+                }
+                // else: arrival-only hub — previous Block already landed here
+            },
+            resolve: () => checkpoint(options.checkpoint),
+            ...(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 } : {}),
+        },
+    });
+    Object.defineProperty(built, "__waygraphKind", {
+        value: "page",
+        enumerable: false,
+        configurable: false,
+    });
+    Object.defineProperty(built, "__waygraphSalt", {
+        value: "page",
+        enumerable: false,
+        configurable: false,
+    });
+    Object.defineProperty(built, "methods", {
+        value: Object.freeze([...methodList]),
+        enumerable: true,
+        configurable: false,
+        writable: false,
+    });
+    Object.defineProperty(built, "__waygraphMethods", {
+        value: methodList.map((m) => m.name),
+        enumerable: false,
+        configurable: false,
+    });
+    // Same marker `defineNavBlock` sets, same reason - a page hub with a
+    // `url` (deep-link) is exactly as "known, coverable" as a plain
+    // `defineNavBlock`, and in practice most real projects' own nav Blocks
+    // ARE page hubs (methods hanging off them), not bare NavBlocks - the real
+    // saucedemo fixture this whole package tests against uses definePageBlock
+    // for every one of its own nav-* Blocks. Missing this here meant the
+    // marker existed but was never actually set on any real project's Blocks.
+    if (typeof options.url === "string") {
+        Object.defineProperty(built, "__waygraphNavUrl", {
+            value: options.url,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    if (options.url !== undefined || options.click !== undefined) {
+        Object.defineProperty(built, "__waygraphPageDeepLink", {
+            value: true,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    if (options.click !== undefined) {
+        Object.defineProperty(built, "__waygraphNavClick", {
+            value: options.click,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    return built;
+}

package/dist/engine/compose.d.ts

@@ -0,0 +1,75 @@
+import type { BlockInfo } from "./flow.js";
+import type { Block, Checkpoint } from "../types.js";
+import type { Trait } from "../trait.js";
+/**
+ * A Block guaranteed to have `withStepVerify`/`modStepVerify` attached - what
+ * {@link composeBlock} returns. Extends plain `Block`, so it drops straight into
+ * `defineFlow([start, ..., composed, ..., end])` like any other Block; no special
+ * casing needed anywhere that only expects a `Block`.
+ */
+export interface ComposedBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> extends Block<In, Out> {
+    /**
+     * This composed Block's constituent steps, in order, as plain data - same
+     * shape and purpose as {@link Flow.blocks}.
+     * @example GovFormBlock.steps() // [{ name: "step-1-name" }, { name: "step-2-address" }, ...]
+     */
+    steps(): readonly BlockInfo[];
+    /**
+     * Replaces one step's whole verify list, wherever it sits in this composed
+     * Block - same rules as {@link withVerify}. Throws if no step matches.
+     * @example GovFormBlock.withStepVerify("step-2-address", [])
+     */
+    withStepVerify(step: Block<any, any> | string | number, verify: Trait[] | ((out: any) => Trait[])): ComposedBlock<In, Out>;
+    /**
+     * Replaces one Trait inside one step's verify list - same rules as
+     * {@link modVerify}. Throws if no step matches, or that step has no verify
+     * trait at the given name/index.
+     * @example GovFormBlock.modStepVerify("step-2-address", "zip-visible", Trait.visible("#zip-confirmed"))
+     */
+    modStepVerify(step: Block<any, any> | string | number, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): ComposedBlock<In, Out>;
+}
+/**
+ * Chains several Blocks into one named, exported unit - what a naturally
+ * multi-step feature (a stepper form with several pages, say) wants instead of
+ * either one giant Block with no per-step confirmation, or several separately
+ * exported Blocks the caller has to wire together by hand every time. Each
+ * step keeps its own real `act`/`resolve`/`verify`, chained the same way
+ * `connect()` already chains any two Blocks - `composeBlock` is not a new
+ * execution mechanism, just `connect()` reduced over the list plus a name and
+ * the same step-list closure `Flow` already keeps for its own Block list, so
+ * `withStepVerify`/`modStepVerify` can patch one step from outside without the
+ * caller needing to hand-rebuild the chain. Resolution is by `.name`, not
+ * object identity, so a step reference stays valid even after an earlier patch
+ * swapped that slot for a new object - see {@link Flow.withBlockVerify} for
+ * the identical guarantee one level up. Each call returns a new composed
+ * Block; the original is untouched.
+ * @example composeBlock("gov-form", [step1, step2, step3, step4])
+ */
+export declare function composeBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, Out>]): ComposedBlock<In, Out>;
+export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, Out>]): ComposedBlock<In, Out>;
+export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, Out>]): ComposedBlock<In, Out>;
+export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, Out>]): ComposedBlock<In, Out>;
+export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, E>, Block<E, Out>]): ComposedBlock<In, Out>;
+export declare function composeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, E>, Block<E, F>, Block<F, Out>]): ComposedBlock<In, Out>;
+/**
+ * Same shape as {@link composeBlock}, marked {@link FastForwardComposedBlock.fastForward}
+ * so demo/run/traverse treat it as **one opaque step** that **blitzes wall-clock**
+ * (skip overlay theater + no Playwright slowMo on that step's acts) unless
+ * `--ff-expand` / `WAYGRAPH_FF_EXPAND=1`. Inner acts still run for real;
+ * failures are prefixed `ff-name > …` so the locus names both the FF unit and
+ * the inner step. Prefer this for boring or heavy-check prefixes (auth, seed,
+ * dashboard settle) — you may put **several** FF units in one Flow with normal
+ * Blocks between them.
+ * @example fastForwardComposeBlock("ff-owner-auth", [NavLoginBlock, SubmitLoginForFlow])
+ */
+export interface FastForwardComposedBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> extends ComposedBlock<In, Out> {
+    readonly fastForward: true;
+}
+/** True when `block` came from {@link fastForwardComposeBlock}. */
+export declare function isFastForwardBlock(block: Block<any, any>): block is FastForwardComposedBlock<any, any>;
+export declare function fastForwardComposeBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, Out>]): FastForwardComposedBlock<In, Out>;
+export declare function fastForwardComposeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, Out>]): FastForwardComposedBlock<In, Out>;
+export declare function fastForwardComposeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, Out>]): FastForwardComposedBlock<In, Out>;
+export declare function fastForwardComposeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, Out>]): FastForwardComposedBlock<In, Out>;
+export declare function fastForwardComposeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, E>, Block<E, Out>]): FastForwardComposedBlock<In, Out>;
+export declare function fastForwardComposeBlock<In extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>, D extends Checkpoint<string>, E extends Checkpoint<string>, F extends Checkpoint<string>, Out extends Checkpoint<string>>(name: string, steps: readonly [Block<In, B>, Block<B, C>, Block<C, D>, Block<D, E>, Block<E, F>, Block<F, Out>]): FastForwardComposedBlock<In, Out>;

package/dist/engine/compose.js

@@ -0,0 +1,76 @@
+import { connect } from "../types.js";
+import { findBlockIndex, modVerify, withVerify } from "./core.js";
+export function composeBlock(name, steps) {
+    if (steps.length === 0) {
+        throw new Error(`composeBlock: "${name}" needs at least one step`);
+    }
+    const chain = steps.reduce((a, b) => connect(a, b));
+    return {
+        ...chain,
+        name,
+        steps: () => steps.map((b) => ({ name: b.name, block: b, ...(b.routes ? { routes: b.routes } : {}) })),
+        withStepVerify(step, verify) {
+            const index = findBlockIndex(steps, step);
+            const patched = [...steps];
+            patched[index] = withVerify(steps[index], verify);
+            return composeBlock(name, patched);
+        },
+        modStepVerify(step, nameOrIndex, newCheck) {
+            const index = findBlockIndex(steps, step);
+            const patched = [...steps];
+            patched[index] = modVerify(steps[index], nameOrIndex, newCheck);
+            return composeBlock(name, patched);
+        },
+    };
+}
+/** True when `block` came from {@link fastForwardComposeBlock}. */
+export function isFastForwardBlock(block) {
+    return (block.fastForward === true &&
+        typeof block.steps === "function");
+}
+function wrapFfError(ffName, err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.startsWith(`${ffName} > `)) {
+        return err instanceof Error ? err : new Error(msg);
+    }
+    const wrapped = new Error(`${ffName} > ${msg}`);
+    if (err instanceof Error && err.stack) {
+        wrapped.stack = err.stack;
+    }
+    return wrapped;
+}
+export function fastForwardComposeBlock(name, steps) {
+    if (steps.length === 0) {
+        throw new Error(`fastForwardComposeBlock: "${name}" needs at least one step`);
+    }
+    const base = composeBlock(name, steps);
+    const origAct = base.instruction.act.bind(base.instruction);
+    const ff = {
+        ...base,
+        fastForward: true,
+        instruction: {
+            ...base.instruction,
+            async act(page, input, mem) {
+                try {
+                    await origAct(page, input, mem);
+                }
+                catch (e) {
+                    throw wrapFfError(name, e);
+                }
+            },
+        },
+        withStepVerify(step, verify) {
+            const index = findBlockIndex(steps, step);
+            const patched = [...steps];
+            patched[index] = withVerify(steps[index], verify);
+            return fastForwardComposeBlock(name, patched);
+        },
+        modStepVerify(step, nameOrIndex, newCheck) {
+            const index = findBlockIndex(steps, step);
+            const patched = [...steps];
+            patched[index] = modVerify(steps[index], nameOrIndex, newCheck);
+            return fastForwardComposeBlock(name, patched);
+        },
+    };
+    return ff;
+}