waygraph 0.13.7 → 0.15.0

package/dist/engine.d.ts

@@ -13,6 +13,52 @@ import { type HighlightStyleDefaults, type DemoPace } from "./highlights.js";
  * since those depend on a runtime decision that hasn't happened yet.
  */
 export declare function preflight(mem: MemPage, block: Block<any, any>): void;
+/**
+ * A cross-cutting, automatically-enforced verify - the real engine
+ * primitive behind "persistent UI" (a sidebar, a header, anything that's
+ * supposed to be present on many/most Checkpoints, not just one page's own
+ * Block). Deliberately NOT tied to any folder convention - `appliesTo`
+ * matches by Checkpoint tag, explicitly, so this works the same whether a
+ * project uses the Waygraph Map folder convention or the older freeform
+ * "manual mode" layout real production consumers (pia-waygraph,
+ * zsign-atomic-waygraph) already use - registering a Layout with an Engine
+ * is the only requirement, folder structure is irrelevant to it.
+ *
+ * Not a Block: no `act`/`resolve`/Checkpoint of its own, never a graph
+ * node - it only ever adds extra `verify` Traits to Checkpoints something
+ * else already resolved to, the same way `runVerify` already runs after
+ * any Block's own `resolve()` (see `runGraph`'s own verify step, just
+ * below) - a Layout is that mechanism made reusable across many
+ * Checkpoints instead of hand-repeated per Block.
+ */
+export interface Layout {
+    name: string;
+    description?: string;
+    appliesTo: (tag: string) => boolean;
+    /** Function form gets the full resolved Checkpoint, same shape `runVerify`/a Block's own `verify` already use - not just the tag. */
+    verify: Trait[] | ((out: Checkpoint<string>) => Trait[]);
+}
+export interface LayoutOptions {
+    name: string;
+    description?: string;
+    /** A fixed tag list, or a predicate for open-ended matching (e.g. a naming pattern). */
+    appliesTo: readonly string[] | ((tag: string) => boolean);
+    verify: Trait[] | ((out: Checkpoint<string>) => Trait[]);
+}
+/**
+ * @example
+ * const AppShellLayout = defineLayout({
+ *   name: "app-shell",
+ *   appliesTo: ["AppHome", "Chats", "Notifications", "Settings"],
+ *   verify: [Trait.visible(SidebarSel.root)],
+ * });
+ * const engine = new Engine({ layouts: [AppShellLayout] });
+ * // Now every Block resolving to one of those four Checkpoints, in any
+ * // Flow this engine defines, also gets AppShellLayout's own verify run
+ * // automatically - a page that silently drops the sidebar fails loud,
+ * // even though no individual Block's own `verify` mentions it.
+ */
+export declare function defineLayout(options: LayoutOptions): Layout;
 /**
  * Runs `entry` against a fresh tab and returns the resulting terminal Checkpoint.
  * The engine owns the tab's lifecycle, not any individual Block: the tab is
@@ -52,6 +98,14 @@ export interface RunGraphOptions {
      * `page` and `closeOnFinish` together) - it just does what you ask.
      */
     closeOnFinish?: boolean;
+    /**
+     * Layouts (see {@link defineLayout}) whose `verify` runs automatically
+     * after any Block in this run resolves to a Checkpoint they apply to -
+     * `Flow.run` threads this in from `EngineConfig.layouts` by default; pass
+     * it directly here to call `runGraph` standalone (outside a `Flow`) with
+     * layouts still enforced.
+     */
+    layouts?: readonly Layout[];
 }
 /**
  * Drives a genuinely separate second tab through its own Block/Flow, in the
@@ -435,6 +489,14 @@ export interface EngineConfig {
             height: number;
         };
     };
+    /**
+     * Cross-cutting, automatically-enforced verify (see {@link defineLayout})
+     * - applies to every Flow this Engine defines. Works the same regardless
+     * of folder convention (Waygraph Map or freeform "manual mode") since
+     * matching is by Checkpoint tag, never by file path.
+     * @example new Engine({ layouts: [AppShellLayout] })
+     */
+    layouts?: readonly Layout[];
 }
 type S = Checkpoint<"__start__">;
 /**
@@ -595,7 +657,106 @@ export declare class Engine {
         Block<N, O>,
         EndMarker
     ]): Flow<O>;
+    /**
+     * 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?: 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 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>;
+    /**
+     * 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`.
+     */
+    gotoPage<NextOut extends Checkpoint<string>>(block: Block<Out, 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.
+     */
+    gotoExternal<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+        name: string;
+    }): MapBuilder<NextOut>;
+    /** Appends a self-loop verification step - requires a Block from `defineAssertBlock`. */
+    assert<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+        name: string;
+    }): MapBuilder<NextOut>;
+    /**
+     * Appends a non-navigating page action (submit, upload, add/remove an
+     * instance) - requires a Block from `defineMethodBlock`/`defineActionBlock`/
+     * `defineEffectBlock`/`defineMemEffectBlock`.
+     */
+    method<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+        name: string;
+    }): MapBuilder<NextOut>;
+    /**
+     * 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
+ * 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<S>;
 /**
  * Attaches routing to `block` without touching its act/observe/resolve/verify -
  * `routes` must cover every tag of `block`'s output (a missing route is a compile
@@ -637,7 +798,7 @@ export declare function defineBlock<In extends Checkpoint<string>, Out extends C
  * (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/changes/nav-block-and-check/` for why this exists.
+ * See `openspec/specs/nav-block-and-check/spec.md` for why this exists.
  */
 export type NavBlock<Out extends Checkpoint<string>> = DefinedBlock<Checkpoint<string>, Out>;
 /**
@@ -742,6 +903,45 @@ export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<st
 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 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"];
+    /**
+     * Shorthand for the wait-then-assert shape found repeatedly in hand-written
+     * assertion Blocks: waits for a heading with this accessible name before
+     * `verify` runs. Omit for a pure "assert whatever is already on the page"
+     * check with no wait. Not a general `act()` override - a Block that needs
+     * more than this stays a plain `defineMethodBlock`.
+     */
+    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>;
+    /** Multi-step yap slides (demo only) - same field `Instruction.slides` exposes elsewhere. */
+    slides?: import("./highlights.js").WaygraphSlidesOrFn<Out>;
+}
+/**
+ * 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 declare function defineAssertBlock<Out extends Checkpoint<string> = Checkpoint<string>>(options: AssertBlockOptions<Out>): MethodBlock<Out, Out>;
 /** 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>> = {

package/dist/engine.js

@@ -34,6 +34,46 @@ export function preflight(mem, block) {
             .join(", ")}`);
     }
 }
+/**
+ * @example
+ * const AppShellLayout = defineLayout({
+ *   name: "app-shell",
+ *   appliesTo: ["AppHome", "Chats", "Notifications", "Settings"],
+ *   verify: [Trait.visible(SidebarSel.root)],
+ * });
+ * const engine = new Engine({ layouts: [AppShellLayout] });
+ * // Now every Block resolving to one of those four Checkpoints, in any
+ * // Flow this engine defines, also gets AppShellLayout's own verify run
+ * // automatically - a page that silently drops the sidebar fails loud,
+ * // even though no individual Block's own `verify` mentions it.
+ */
+export function defineLayout(options) {
+    const appliesTo = typeof options.appliesTo === "function"
+        ? options.appliesTo
+        : (tag) => options.appliesTo.includes(tag);
+    return {
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        appliesTo,
+        verify: options.verify,
+    };
+}
+/**
+ * Runs every registered layout whose `appliesTo(tag)` matches the just-
+ * resolved Checkpoint, in registration order, right after the Block's own
+ * `verify` already ran. A layout's own Trait failing throws the same way
+ * any other `runVerify` failure does, naming the layout so it's clearly
+ * distinguishable from the Block's own verify in the error message.
+ */
+async function runLayouts(layouts, tag, out, page, mem, blockName) {
+    if (!layouts)
+        return;
+    for (const layout of layouts) {
+        if (!layout.appliesTo(tag))
+            continue;
+        await runVerify(layout.verify, out, page, mem, `${blockName} (layout: "${layout.name}")`);
+    }
+}
 /**
  * Runs `entry` against a fresh tab and returns the resulting terminal Checkpoint.
  * The engine owns the tab's lifecycle, not any individual Block: the tab is
@@ -72,6 +112,7 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
                 : undefined;
             const checkpoint = await current.instruction.resolve(observed);
             await runVerify(current.instruction.verify, checkpoint, page, mem, current.name);
+            await runLayouts(options?.layouts, checkpoint.__state, checkpoint, page, mem, current.name);
             const next = current.next?.(checkpoint);
             if (!next) {
                 if (terminals && !terminals.has(checkpoint.__state)) {
@@ -218,7 +259,11 @@ function buildFlow(middle, engineConfig) {
     // withSessionReset()/withTitle() instead (non-destructive decorators,
     // same pattern as withVerify), which also re-apply themselves after any
     // further withBlockVerify/modBlockVerify patch so the flag survives.
-    const chain = middle.reduce((a, b) => connect(a, b));
+    // Layouts have to be threaded into every pairwise connect(), not just the
+    // trailing runGraph call - see connect()'s own doc comment in types.ts:
+    // buildFlow's reduce IS the only place a defineFlow-built Flow's
+    // intermediate (non-final) Checkpoints are ever verified at all.
+    const chain = middle.reduce((a, b) => connect(a, b, engineConfig.layouts));
     // Declared separately (not as the object-literal method below) so the
     // three-overload `Flow.run` signature can be checked against the actual
     // per-call-shape behavior, then attached with a cast - object-literal
@@ -248,7 +293,9 @@ function buildFlow(middle, engineConfig) {
             try {
                 const context = await browser.newContext(config.recordVideo ? { recordVideo: config.recordVideo } : {});
                 try {
-                    return await runGraph(chain, undefined, context, mem);
+                    return await runGraph(chain, undefined, context, mem, 5000, {
+                        ...(config.layouts !== undefined ? { layouts: config.layouts } : {}),
+                    });
                 }
                 finally {
                     // Playwright finalizes recordVideo on context.close(); skip when
@@ -277,9 +324,11 @@ function buildFlow(middle, engineConfig) {
         // call from before this option existed. An explicit `closeOnFinish`
         // always wins either way.
         const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
+        const resolvedLayouts = options?.layouts ?? engineConfig.layouts;
         const result = await runGraph(chain, undefined, context, mem, 5000, {
             page,
             closeOnFinish: false,
+            ...(resolvedLayouts !== undefined ? { layouts: resolvedLayouts } : {}),
         });
         if (closeOnFinish) {
             await page.close();
@@ -655,6 +704,185 @@ export class Engine {
     defineFlow(blocks) {
         return buildFlow(blocks.slice(1, -1), this.config);
     }
+    /**
+     * Fluent, kind-checked alternative to `defineFlow([start, ...blocks, end])` -
+     * see {@link MapBuilder}. Real, direct request this responds to: pia/zsign's
+     * own agents kept hand-editing/hand-composing Blocks into ad hoc shapes
+     * ("locks" convention tried, still got broken) - `map()` forces every step
+     * through this Engine's own `define*Block` factories (checked by the same
+     * `__waygraphKind`/`__waygraphSalt` runtime markers `graph.ts`/`map-check.ts`
+     * already trust), so a hand-rolled plain-object Block can never silently
+     * pass as a real navigation/assertion/method step. `homeOrigin`, if given,
+     * also gates `.gotoPage()`/`.gotoExternal()` against each Nav/Page Block's
+     * own static `url` (skipped, honestly, for click-based/dynamic nav - not
+     * statically checkable, same limitation `map-check.ts` already documents).
+     * @example
+     * const flow = engine.map({ homeOrigin: "https://app.example.com" })
+     *   .start()
+     *   .gotoPage(NavHomeBlock)
+     *   .assert(AssertHelloBlock)
+     *   .gotoExternal(NavMailpitBlock)
+     *   .end();
+     */
+    map(options) {
+        return MapBuilder.begin(this, options?.homeOrigin);
+    }
+}
+function mapKindOf(block) {
+    return block?.__waygraphKind;
+}
+function mapSaltOf(block) {
+    return block?.__waygraphSalt;
+}
+function mapNavUrlOf(block) {
+    const url = block?.__waygraphNavUrl;
+    return typeof url === "string" ? url : undefined;
+}
+const MAP_KIND_FACTORY_HINT = {
+    nav: "defineNavBlock/defineMemNavBlock",
+    page: "definePageBlock",
+    assert: "defineAssertBlock",
+};
+const MAP_SALT_FACTORY_HINT = {
+    method: "defineMethodBlock",
+    effect: "defineEffectBlock",
+};
+function assertMapKind(block, allowed, method) {
+    const kind = mapKindOf(block);
+    if (kind !== undefined && allowed.includes(kind))
+        return;
+    const wanted = allowed.map((k) => MAP_KIND_FACTORY_HINT[k] ?? k).join(" or ");
+    const found = kind ? `a Block of kind "${kind}"` : "an object with no waygraph kind marker at all";
+    throw new Error(`Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
+        `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
+        "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.");
+}
+function assertMapSalt(block, allowed, method) {
+    const salt = mapSaltOf(block);
+    if (salt !== undefined && allowed.includes(salt))
+        return;
+    const wanted = allowed.map((s) => MAP_SALT_FACTORY_HINT[s] ?? s).join(" or ");
+    const found = salt ? `a Block salted "${salt}"` : "an object with no waygraph salt marker at all";
+    throw new Error(`Waygraph map: .${method}("${block?.name ?? "?"}") requires a Block built with ${wanted} ` +
+        `(found ${found} - a hand-built plain object doesn't count). This check is the whole point ` +
+        "of the map() builder: only real Blocks from waygraph's own factories can enter a chain.");
+}
+function assertMapOrigin(block, homeOrigin, expect, method) {
+    if (!homeOrigin)
+        return; // not configured - can't validate, honest no-op
+    const navUrl = mapNavUrlOf(block);
+    if (navUrl === undefined)
+        return; // click-based/dynamic nav - not statically checkable
+    let targetOrigin;
+    let wantOrigin;
+    try {
+        targetOrigin = new URL(navUrl, homeOrigin).origin;
+        wantOrigin = new URL(homeOrigin).origin;
+    }
+    catch {
+        return; // malformed URL - not this check's job to validate that
+    }
+    const isExternal = targetOrigin !== wantOrigin;
+    if (expect === "internal" && isExternal) {
+        throw new Error(`Waygraph map: .gotoPage("${block.name}") targets ${targetOrigin}, which is NOT this map's ` +
+            `home origin (${wantOrigin}) - use .gotoExternal() for a genuinely cross-origin destination.`);
+    }
+    if (expect === "external" && !isExternal) {
+        throw new Error(`Waygraph map: .gotoExternal("${block.name}") targets ${targetOrigin}, which IS this map's ` +
+            `home origin (${wantOrigin}) - use .gotoPage() for an internal destination.`);
+    }
+}
+/**
+ * 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 class MapBuilder {
+    engine;
+    steps;
+    homeOrigin;
+    constructor(engine, steps, homeOrigin) {
+        this.engine = engine;
+        this.steps = steps;
+        this.homeOrigin = homeOrigin;
+    }
+    /** @internal - use `engine.map()` or the standalone `map()` export. */
+    static begin(engine, homeOrigin) {
+        return new MapBuilder(engine, [], homeOrigin);
+    }
+    /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
+    start() {
+        return this;
+    }
+    /**
+     * 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`.
+     */
+    gotoPage(block) {
+        assertMapKind(block, ["nav", "page"], "gotoPage");
+        assertMapOrigin(block, this.homeOrigin, "internal", "gotoPage");
+        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+    }
+    /**
+     * 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.
+     */
+    gotoExternal(block) {
+        assertMapKind(block, ["nav", "page"], "gotoExternal");
+        assertMapOrigin(block, this.homeOrigin, "external", "gotoExternal");
+        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+    }
+    /** Appends a self-loop verification step - requires a Block from `defineAssertBlock`. */
+    assert(block) {
+        assertMapKind(block, ["assert"], "assert");
+        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+    }
+    /**
+     * Appends a non-navigating page action (submit, upload, add/remove an
+     * instance) - requires a Block from `defineMethodBlock`/`defineActionBlock`/
+     * `defineEffectBlock`/`defineMemEffectBlock`.
+     */
+    method(block) {
+        assertMapSalt(block, ["method", "effect"], "method");
+        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+    }
+    /**
+     * 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() {
+        if (this.steps.length === 0) {
+            throw new Error("Waygraph map: .end() called with zero steps - add at least one .gotoPage()/.gotoExternal()/" +
+                ".assert()/.method() before .end()");
+        }
+        const chain = [start, ...this.steps, end];
+        return this.engine.defineFlow(chain);
+    }
+}
+/**
+ * Standalone convenience for `new Engine(config).map(options)` - use this
+ * when a call site doesn't otherwise need its own `Engine` instance (no
+ * shared `headless`/`slowMo`/`layouts` across several flows).
+ * @example const flow = map({ homeOrigin: "https://app.example.com" }).gotoPage(NavHomeBlock).end();
+ */
+export function map(options) {
+    return new Engine(options).map(options);
 }
 /**
  * Attaches routing to `block` without touching its act/observe/resolve/verify -
@@ -797,6 +1025,20 @@ export function defineNavBlock(options) {
             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} */
@@ -826,6 +1068,60 @@ export function defineMethodBlock(base) {
 }
 /** @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,
+    });
+    return built;
+}
 function resolvePageMethods(methods) {
     if (!methods)
         return [];
@@ -884,6 +1180,20 @@ export function definePageBlock(options) {
         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,

package/dist/graph.d.ts

@@ -58,6 +58,24 @@ export declare function findOrphanBlocks(projectDir: string): Promise<OrphanBloc
  * edges. NavBlocks (`from: "*"`) count from any state.
  */
 export declare function findBlockPath(graph: WaygraphGraph, fromTag: string, toTag: string): string[] | null;
+export interface BlockPathStep {
+    block: string;
+    /** The specific Checkpoint this hop's edge targets - NOT re-derivable by
+     * looking up `block` by name afterward, since a union-Out Block (e.g.
+     * "Union Out tags create duplicate edges for the same Block", see
+     * `discoverGraph`'s own comment above) can have several edges with the
+     * same `block` name but different `to` tags; only the specific edge BFS
+     * actually routed through here is correct. */
+    to: string;
+}
+/**
+ * Same BFS as `findBlockPath`, but returns each hop's specific edge (block
+ * name + the Checkpoint it targets), not just the block name - needed by any
+ * caller that must verify a step actually landed where the route intended,
+ * not just re-guess it afterward. `findBlockPath` itself is unchanged and
+ * still used wherever only the block-name sequence matters.
+ */
+export declare function findBlockPathDetailed(graph: WaygraphGraph, fromTag: string, toTag: string): BlockPathStep[] | null;
 /**
  * Walks every `*.block.ts` file under `projectDir` and builds the app's own
  * state graph. Shares the same in-process-import limitation `waygraph