waygraph 0.15.24 → 0.15.26

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

@@ -0,0 +1,41 @@
+import type { Block, Checkpoint, DefinedBlock } from "../../types.js";
+import type { MemKey } from "../../mem-page.js";
+import type { Trait } from "../../trait.js";
+import { defineBlock } from "../core.js";
+/**
+ * TypeScript salt over {@link defineBlock}: same runtime Block, but the type
+ * forces `requires` + `instanceOptions` so `waygraph auto` can list one menu
+ * row per live instance (add/remove/toggle). Not a separate engine concept -
+ * everything is still a Block.
+ */
+export type EffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = Omit<DefinedBlock<In, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "effect";
+    requires: readonly MemKey<any>[];
+    instanceOptions: NonNullable<Block<In, Out>["instanceOptions"]>;
+    withVerify(verify: Trait[] | ((out: Out) => Trait[])): EffectBlock<In, Out>;
+    modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): EffectBlock<In, Out>;
+    modVerifyAll(patches: Record<string, Trait["check"] | Trait>): EffectBlock<In, Out>;
+    stubBefore(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubBefore(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+};
+/** @deprecated Prefer {@link EffectBlock} - same type; Mem* was an early name. */
+export type MemEffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = EffectBlock<In, Out>;
+/**
+ * {@link defineBlock} constrained for effect-style instance menus: `requires` +
+ * `instanceOptions` are mandatory. Prefer this when the Block adds / removes /
+ * toggles a live instance rather than navigating. Runtime result is an ordinary
+ * Block - the helper is TypeScript salt only.
+ */
+export declare function defineEffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0] & {
+    requires: readonly MemKey<any>[];
+    instanceOptions: NonNullable<Block<In, Out>["instanceOptions"]>;
+}): EffectBlock<In, Out>;
+/** @deprecated Prefer {@link defineEffectBlock} - identical helper. */
+export declare const defineMemEffectBlock: typeof defineEffectBlock;

package/dist/engine/blocks/effect.js

@@ -0,0 +1,23 @@
+import { defineBlock } from "../core.js";
+/**
+ * {@link defineBlock} constrained for effect-style instance menus: `requires` +
+ * `instanceOptions` are mandatory. Prefer this when the Block adds / removes /
+ * toggles a live instance rather than navigating. Runtime result is an ordinary
+ * Block - the helper is TypeScript salt only.
+ */
+export function defineEffectBlock(base) {
+    const built = defineBlock(base);
+    Object.defineProperty(built, "__waygraphMemKind", {
+        value: "effect",
+        enumerable: false,
+        configurable: false,
+    });
+    Object.defineProperty(built, "__waygraphSalt", {
+        value: "effect",
+        enumerable: false,
+        configurable: false,
+    });
+    return built;
+}
+/** @deprecated Prefer {@link defineEffectBlock} - identical helper. */
+export const defineMemEffectBlock = defineEffectBlock;

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

@@ -0,0 +1,90 @@
+import type { Checkpoint, DefinedBlock } from "../../types.js";
+import type { Trait } from "../../trait.js";
+import { defineBlock } from "../core.js";
+import type { MemKey } from "../../mem-page.js";
+/**
+ * TypeScript salt over {@link defineBlock} for one-shot non-nav app steps
+ * (submit, upload, finish, logout) - **methods** on a page. Same runtime Block;
+ * marks `__waygraphSalt = "method"` so auto/docs can tell Method from bare
+ * {@link defineBlock}. Does not force `instanceOptions` - use
+ * {@link defineEffectBlock} when the auto menu should spawn one row per live
+ * DOM instance. Prefer hanging methods off a {@link definePageBlock} hub.
+ */
+export type MethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = Omit<DefinedBlock<In, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "method";
+    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>;
+    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): 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>;
+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>): AssertBlock<Out>;
+/**
+ * Self-loop verify Block from {@link defineAssertBlock}. Branded for
+ * {@link MapBuilder.assert} (not accepted by `.method()`).
+ */
+export type AssertBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Out, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "assert";
+    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>;
+    stubBefore(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubAfter(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubOnError(stub: (out: Out) => import("../../highlights.js").HighlightStubPhase): AssertBlock<Out>;
+};

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