waygraph 0.3.2 → 0.5.0

package/dist/engine.d.ts

@@ -1,6 +1,7 @@
-import type { BrowserContext, Page } from "@playwright/test";
-import type { Block, Checkpoint, Instruction, DefinedBlock } from "./types.js";
+import type { BrowserContext, BrowserType, Page, Locator } from "@playwright/test";
+import type { Block, Checkpoint, Instruction, DefinedBlock, ActionPage, WaygraphHighlight } from "./types.js";
 import { MemPage } from "./mem-page.js";
+import type { MemKey } from "./mem-page.js";
 import type { Trait } from "./trait.js";
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
@@ -68,6 +69,24 @@ export interface RunGraphOptions {
  * }
  */
 export declare function spawnTab<TOut extends Checkpoint<string>>(entry: Block<Checkpoint<"__start__">, TOut>, page: Page, mem: MemPage, maxSteps?: number): Promise<TOut>;
+/**
+ * Wraps one `act()` interaction with a caption and highlight, for a Block
+ * author who wants to explicitly narrate a specific step rather than rely
+ * on the generic per-fill/per-click narration `waygraph chain
+ * WAYGRAPH_STEP=1` already does automatically -
+ * `await narrate(submitButton, "confirms the order", () => submitButton.click())`
+ * reads at the call site instead of being inferred.
+ *
+ * A true no-op everywhere except inside a `WAYGRAPH_STEP=1` run: it checks
+ * for a `window.__wgPositionRing` hook the step-mode overlay installs on
+ * the page before doing anything, so a headless/CI/automated run (nobody
+ * watching, per-character delays and highlight pauses would just be wasted
+ * time) pays zero extra cost - not even the boundingBox() lookup runs. The
+ * `action` itself always runs regardless; only the narration is
+ * conditional.
+ * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
+ */
+export declare function narrate<T>(locator: Locator, caption: string, action: () => Promise<T>): Promise<T>;
 /** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
 export declare const start: unique symbol;
 export declare const end: unique symbol;
@@ -117,6 +136,14 @@ export interface BlockInfo {
     name: string;
     /** `branch()`'s routing table, if this Block has one - see {@link Block.routes}. */
     routes?: Readonly<Record<string, string | null>>;
+    /**
+     * True when {@link chainFlow} inserted a session-reset boundary
+     * immediately before this Block - i.e. this is the first Block of a
+     * sub-flow that was wrapped in {@link withSessionReset}, and it isn't
+     * the very first sub-flow in the chain. Absent (not just false) from
+     * `Flow.blocks()` on an ordinary, non-chained Flow.
+     */
+    resetSessionBefore?: boolean;
     /**
      * The actual Block, re-runnable on its own via
      * `engine.defineFlow([start, info.block, end])` - e.g. step-through
@@ -127,6 +154,22 @@ export interface BlockInfo {
     block: Block<any, any>;
 }
 export interface Flow<Out extends Checkpoint<string>> {
+    /**
+     * True once this Flow has been wrapped in {@link withSessionReset} - a
+     * hint for `chainFlow`, not something `run()` itself checks: it marks
+     * this Flow as one that expects to start from a genuinely fresh,
+     * unauthenticated browser state (e.g. a login flow meant to be
+     * re-entered later in a longer chain). `chainFlow` clears cookies and
+     * storage right before this Flow's first Block runs, but only when this
+     * Flow isn't the very first thing in the chain (nothing to reset yet).
+     */
+    readonly resetSession: boolean;
+    /**
+     * Set once this Flow has been wrapped in {@link withTitle} - a display
+     * hint for a step-through overlay/showcase (e.g. "Ticket #123"), not
+     * something `run()` itself uses.
+     */
+    readonly title?: string;
     /**
      * This Flow's constituent Blocks, in order between `start`/`end`, as plain
      * data - for introspection/visualization tools, without running anything.
@@ -170,6 +213,49 @@ export interface Flow<Out extends Checkpoint<string>> {
      */
     modBlockVerify(block: Block<any, any> | string | number, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): Flow<Out>;
 }
+/**
+ * Marks a Flow as expecting to start from a genuinely fresh, unauthenticated
+ * browser state - e.g. a login flow meant to be re-entered later in a longer
+ * showcase. Non-destructive, same pattern as {@link withVerify}: returns a
+ * new Flow: the original is untouched, and the flag survives any further
+ * `withBlockVerify`/`modBlockVerify` patch applied to the result.
+ *
+ * By itself this does nothing - `Flow.run()` never reads `resetSession`.
+ * It's a hint {@link chainFlow} looks for: right before this Flow's first
+ * Block runs (skipped if it's the very first thing in the chain - nothing
+ * to reset yet), chainFlow clears cookies and storage so this Flow starts
+ * exactly as if a human had opened the app fresh, not wherever the
+ * previous Flow in the chain happened to leave the page.
+ * @example const loginFlow = withSessionReset(engine.defineFlow([start, LoginBlock, end]));
+ */
+export declare function withSessionReset<Out extends Checkpoint<string>>(flow: Flow<Out>): Flow<Out>;
+/**
+ * Names a Flow for display - a step-through overlay/showcase (waygraph's
+ * `chain --step`) shows this as the running banner while this Flow's own
+ * Blocks are executing, instead of one fixed title for the whole run.
+ * Non-destructive, same pattern as {@link withSessionReset}.
+ * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
+ */
+export declare function withTitle<Out extends Checkpoint<string>>(flow: Flow<Out>, title: string): Flow<Out>;
+/**
+ * Runs several complete, independent Flows one after another, reusing the
+ * same page/context/mem in order - each remains its own validated
+ * start-to-end unit (a Flow's own `[start, ...blocks, end]` contract is
+ * untouched), this only sequences whole Flows. Deliberately NOT the same
+ * thing as {@link composeBlock}: composeBlock nests several Blocks into
+ * one Block that can drop back into another `defineFlow([...])` - a
+ * chainFlow result is a Flow, but not meant to be nested inside another
+ * Flow's own Block list. Recursive nesting stays composeBlock's job alone;
+ * chainFlow is a flat, one-level sequencing of complete showcases (e.g.
+ * "ticket #123 end to end, then ticket #456 end to end").
+ *
+ * A sub-flow wrapped in {@link withSessionReset} gets its cookies/storage
+ * cleared right before it runs (skipped for the very first flow in the
+ * chain - nothing to reset yet). The combined result is whatever the LAST
+ * flow resolved to.
+ * @example chainFlow(ticket123Flow, ticket456Flow).run(context, mem)
+ */
+export declare function chainFlow(...flows: readonly Flow<any>[]): Flow<any>;
 /**
  * A Block guaranteed to have `withStepVerify`/`modStepVerify` attached - what
  * {@link composeBlock} returns. Extends plain `Block`, so it drops straight into
@@ -228,6 +314,18 @@ export interface EngineConfig {
     browserName?: "chromium" | "firefox" | "webkit";
     /** Milliseconds Playwright pauses before each operation - for watching a non-headless run with your own eyes, not for real runs. Default `0`. */
     slowMo?: number;
+    /**
+     * Overrides which `BrowserType` actually launches, per browser name -
+     * default is the real `@playwright/test` export for whichever one
+     * `browserName` picks. Accepts anything shaped like Playwright's own
+     * `chromium`/`firefox`/`webkit` (same `.launch()` signature) - a
+     * stealth-patched or otherwise customized launcher (e.g. `playwright-extra`
+     * plus a stealth plugin) drops in here unmodified. Puppeteer is a
+     * different `Page`/`BrowserContext` shape entirely and isn't supported by
+     * this seam.
+     * @example new Engine({ browsers: { chromium: stealthChromium } })
+     */
+    browsers?: Partial<Record<"chromium" | "firefox" | "webkit", BrowserType>>;
 }
 type S = Checkpoint<"__start__">;
 /**
@@ -300,11 +398,48 @@ export declare function branch<In extends Checkpoint<string>, Out extends Checkp
 export declare function defineBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: {
     name: string;
     description?: Block<In, Out>["description"];
-    instruction: Instruction<In, Out, any>;
+    instruction: Omit<Instruction<In, Out, any>, "act"> & {
+        act(page: ActionPage, input: In, mem: MemPage): Promise<void>;
+    };
     next?: Block<In, Out>["next"];
     requires?: Block<In, Out>["requires"];
     routes?: Block<In, Out>["routes"];
 }): DefinedBlock<In, Out>;
+/**
+ * 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/changes/nav-block-and-check/` for why this exists.
+ */
+export type NavBlock<Out extends Checkpoint<string>> = DefinedBlock<Checkpoint<string>, Out>;
+/**
+ * Builds a {@link NavBlock}. `url` accepts a plain string or a function
+ * `(mem) => string` for parameterized routes (e.g. `/dashboard/requests/:id`
+ * with a real id read from mem). `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."
+ *
+ * The generated `act()` is always exactly `page.goto(url)` - 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)}` })
+ */
+export declare function defineNavBlock<Out extends Checkpoint<string>>(options: {
+    name: string;
+    description?: string;
+    checkpoint: Out["__state"];
+    url: string | ((mem: MemPage) => string);
+    requires?: readonly MemKey<any>[];
+    verify?: Trait[] | ((out: Out) => Trait[]);
+    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
+}): NavBlock<Out>;
 /**
  * Returns a new Block that runs exactly like `block` - same act/observe/resolve,
  * same routing - but with `verify` replaced. For giving one flow stricter (or

package/dist/engine.js

@@ -3,6 +3,20 @@ import { connect, checkpoint } from "./types.js";
 import { MemPage } from "./mem-page.js";
 import { runVerify } from "./trait.js";
 const LAUNCHERS = { chromium, firefox, webkit };
+/**
+ * Resolves which `BrowserType` actually launches for a `mem`-only run (no
+ * caller-supplied context) - `config.browsers[browserName]` if given,
+ * otherwise the real `@playwright/test` export. Waygraph is deliberately
+ * "just an opinionated Playwright" - it doesn't own browser automation
+ * itself, so it shouldn't force every consumer onto the vanilla launcher.
+ * A stealth-patched or otherwise customized launcher (e.g. `playwright-extra`
+ * plus a stealth plugin) is a drop-in replacement for `chromium`/`firefox`/
+ * `webkit` - same `.launch()` shape - so accepting one here costs nothing for
+ * a consumer who never sets it.
+ */
+function resolveLauncher(browserName, config) {
+    return config?.browsers?.[browserName] ?? LAUNCHERS[browserName];
+}
 /**
  * Checks `block.requires` against `mem` and throws, naming every missing key at
  * once, if any are unset. `connect()` unions each Block's `requires` into the
@@ -92,6 +106,93 @@ export async function runGraph(entry, terminals, context, mem, maxSteps = 5000,
 export async function spawnTab(entry, page, mem, maxSteps = 5000) {
     return runGraph(entry, undefined, page.context(), mem, maxSteps);
 }
+/**
+ * Wraps one `act()` interaction with a caption and highlight, for a Block
+ * author who wants to explicitly narrate a specific step rather than rely
+ * on the generic per-fill/per-click narration `waygraph chain
+ * WAYGRAPH_STEP=1` already does automatically -
+ * `await narrate(submitButton, "confirms the order", () => submitButton.click())`
+ * reads at the call site instead of being inferred.
+ *
+ * A true no-op everywhere except inside a `WAYGRAPH_STEP=1` run: it checks
+ * for a `window.__wgPositionRing` hook the step-mode overlay installs on
+ * the page before doing anything, so a headless/CI/automated run (nobody
+ * watching, per-character delays and highlight pauses would just be wasted
+ * time) pays zero extra cost - not even the boundingBox() lookup runs. The
+ * `action` itself always runs regardless; only the narration is
+ * conditional.
+ * @example await narrate(submitButton, "confirms the order", () => submitButton.click())
+ */
+export async function narrate(locator, caption, action) {
+    const page = locator.page();
+    const active = await page
+        .evaluate(() => typeof globalThis.__wgPositionRing === "function")
+        .catch(() => false);
+    if (!active)
+        return action();
+    let owning = false;
+    try {
+        const box = await locator.boundingBox();
+        if (box) {
+            await page
+                .evaluate(({ box, caption }) => {
+                const w = globalThis;
+                if (w.__wgPositionRing)
+                    w.__wgPositionRing(box, caption);
+                // The CLI's own automatic per-fill/per-click narration checks
+                // this before showing (and overwriting) its own guess - an
+                // explicitly authored caption should win, not get immediately
+                // replaced a moment later by the generic one.
+                w.__wgLastNarrate = Date.now();
+                // Also claim the ring itself: the auto-highlight click/fill
+                // patches each hide the ring right after THEIR own step
+                // finishes, which - if action() below does more than one thing
+                // (e.g. a click then a wait for a toast) - would wipe this
+                // caption after just the first sub-step instead of the whole
+                // narrated action. Their hideRing() calls no-op while this is
+                // true; narrate() below is the one that actually clears it.
+                w.__wgNarrateOwnsRing = true;
+            }, { box, caption })
+                .catch(() => { });
+            owning = true;
+            // The ring alone is pointless if action() fires on the very next
+            // tick - a click that navigates (e.g. a form submit) wipes the ring
+            // before a human can read the caption at all. Give it the same
+            // "pop for a few seconds" dwell as the CLI's own auto-highlight
+            // clicks before the real action runs.
+            await new Promise((resolve) => setTimeout(resolve, 650));
+            // Re-stamp __wgLastNarrate right before handing off to action() - the
+            // CLI's auto-highlight patches only treat a narrate() as "just
+            // handled" within a short window (500ms), which the dwell above
+            // already burned through. Without this, action()'s own click/fill
+            // (same patched Locator prototype) would stomp this caption with its
+            // own generic one a moment after it finally became visible.
+            await page
+                .evaluate(() => {
+                globalThis.__wgLastNarrate = Date.now();
+            })
+                .catch(() => { });
+        }
+    }
+    catch {
+        // best-effort - the real action below still runs either way
+    }
+    try {
+        return await action();
+    }
+    finally {
+        if (owning) {
+            await page
+                .evaluate(() => {
+                const w = globalThis;
+                w.__wgNarrateOwnsRing = false;
+                if (w.__wgHideRing)
+                    w.__wgHideRing();
+            })
+                .catch(() => { });
+        }
+    }
+}
 /** Reserved markers bookending a `defineFlow([start, ...blocks, end])` call. */
 export const start = Symbol("waygraph.start");
 export const end = Symbol("waygraph.end");
@@ -110,6 +211,11 @@ function findBlockIndex(middle, block) {
     return index;
 }
 function buildFlow(middle, engineConfig) {
+    // resetSession/title start false/unset here - defineFlow itself carries
+    // no such options anymore. They're set by wrapping the result in
+    // 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));
     // Declared separately (not as the object-literal method below) so the
     // three-overload `Flow.run` signature can be checked against the actual
@@ -126,7 +232,7 @@ function buildFlow(middle, engineConfig) {
             // run(context, mem) already has via an existing context.
             preflight(mem, chain);
             const browserName = config.browserName ?? "chromium";
-            const launch = LAUNCHERS[browserName];
+            const launch = resolveLauncher(browserName, config);
             // If CHROME_PATH/CHROMIUM_PATH is set in the environment (e.g. a system
             // or Flatpak Chromium), launch that instead of Playwright's own bundled
             // binary - only for chromium (the env var names a Chromium build, not a
@@ -180,6 +286,7 @@ function buildFlow(middle, engineConfig) {
         return result;
     };
     return {
+        resetSession: false,
         blocks: () => middle.map((b) => ({ name: b.name, block: b, ...(b.routes ? { routes: b.routes } : {}) })),
         run: run,
         withBlockVerify(block, verify) {
@@ -196,6 +303,166 @@ function buildFlow(middle, engineConfig) {
         },
     };
 }
+/**
+ * Marks a Flow as expecting to start from a genuinely fresh, unauthenticated
+ * browser state - e.g. a login flow meant to be re-entered later in a longer
+ * showcase. Non-destructive, same pattern as {@link withVerify}: returns a
+ * new Flow: the original is untouched, and the flag survives any further
+ * `withBlockVerify`/`modBlockVerify` patch applied to the result.
+ *
+ * By itself this does nothing - `Flow.run()` never reads `resetSession`.
+ * It's a hint {@link chainFlow} looks for: right before this Flow's first
+ * Block runs (skipped if it's the very first thing in the chain - nothing
+ * to reset yet), chainFlow clears cookies and storage so this Flow starts
+ * exactly as if a human had opened the app fresh, not wherever the
+ * previous Flow in the chain happened to leave the page.
+ * @example const loginFlow = withSessionReset(engine.defineFlow([start, LoginBlock, end]));
+ */
+export function withSessionReset(flow) {
+    return {
+        ...flow,
+        resetSession: true,
+        withBlockVerify: (block, verify) => withSessionReset(flow.withBlockVerify(block, verify)),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withSessionReset(flow.modBlockVerify(block, nameOrIndex, newCheck)),
+    };
+}
+/**
+ * Names a Flow for display - a step-through overlay/showcase (waygraph's
+ * `chain --step`) shows this as the running banner while this Flow's own
+ * Blocks are executing, instead of one fixed title for the whole run.
+ * Non-destructive, same pattern as {@link withSessionReset}.
+ * @example const ticket123 = withTitle(loginFlow, "Ticket #123 - Sales rep signs in");
+ */
+export function withTitle(flow, title) {
+    return {
+        ...flow,
+        title,
+        withBlockVerify: (block, verify) => withTitle(flow.withBlockVerify(block, verify), title),
+        modBlockVerify: (block, nameOrIndex, newCheck) => withTitle(flow.modBlockVerify(block, nameOrIndex, newCheck), title),
+    };
+}
+function locateInChain(flows, block) {
+    if (typeof block === "number") {
+        let remaining = block;
+        for (let fi = 0; fi < flows.length; fi++) {
+            const len = flows[fi].blocks().length;
+            if (remaining < len)
+                return { flowIndex: fi, localIndex: remaining };
+            remaining -= len;
+        }
+        throw new Error(`chainFlow: no Block at index ${block} across ${flows.length} chained flows`);
+    }
+    const blockName = typeof block === "string" ? block : block.name;
+    for (let fi = 0; fi < flows.length; fi++) {
+        const localIndex = flows[fi].blocks().findIndex((bi) => bi.name === blockName);
+        if (localIndex !== -1)
+            return { flowIndex: fi, localIndex };
+    }
+    throw new Error(`chainFlow: no Block named "${blockName}" in any chained flow`);
+}
+async function clearSessionState(context, page) {
+    await context.clearCookies().catch(() => { });
+    await page
+        .evaluate(() => {
+        try {
+            localStorage.clear();
+            sessionStorage.clear();
+        }
+        catch {
+            /* storage blocked (e.g. about:blank) - nothing to clear anyway */
+        }
+    })
+        .catch(() => { });
+}
+/**
+ * Runs several complete, independent Flows one after another, reusing the
+ * same page/context/mem in order - each remains its own validated
+ * start-to-end unit (a Flow's own `[start, ...blocks, end]` contract is
+ * untouched), this only sequences whole Flows. Deliberately NOT the same
+ * thing as {@link composeBlock}: composeBlock nests several Blocks into
+ * one Block that can drop back into another `defineFlow([...])` - a
+ * chainFlow result is a Flow, but not meant to be nested inside another
+ * Flow's own Block list. Recursive nesting stays composeBlock's job alone;
+ * chainFlow is a flat, one-level sequencing of complete showcases (e.g.
+ * "ticket #123 end to end, then ticket #456 end to end").
+ *
+ * A sub-flow wrapped in {@link withSessionReset} gets its cookies/storage
+ * cleared right before it runs (skipped for the very first flow in the
+ * chain - nothing to reset yet). The combined result is whatever the LAST
+ * flow resolved to.
+ * @example chainFlow(ticket123Flow, ticket456Flow).run(context, mem)
+ */
+export function chainFlow(...flows) {
+    if (flows.length === 0) {
+        throw new Error("chainFlow: give at least one Flow");
+    }
+    const run = async function run(contextOrMem, memOrConfig, options) {
+        if (contextOrMem instanceof MemPage) {
+            const mem = contextOrMem;
+            const config = memOrConfig;
+            // One browser for the WHOLE chain - each sub-flow's own run(mem,
+            // config) would otherwise each launch a separate browser, defeating
+            // the point of sequencing them (a fresh browser is itself a full
+            // session reset, silently making withSessionReset a no-op).
+            const browserName = config?.browserName ?? "chromium";
+            const launch = resolveLauncher(browserName, config);
+            const executablePath = browserName === "chromium" ? process.env.CHROME_PATH || process.env.CHROMIUM_PATH : undefined;
+            const browser = await launch.launch({
+                headless: config?.headless ?? true,
+                ...(config?.slowMo !== undefined ? { slowMo: config.slowMo } : {}),
+                ...(executablePath ? { executablePath } : {}),
+            });
+            try {
+                const context = await browser.newContext();
+                return await run(context, mem, { closeOnFinish: true });
+            }
+            finally {
+                await browser.close();
+            }
+        }
+        const context = contextOrMem;
+        const mem = memOrConfig;
+        const gotOwnPage = options?.page === undefined;
+        const page = options?.page ?? (await context.newPage());
+        const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
+        let result;
+        for (let i = 0; i < flows.length; i++) {
+            const flow = flows[i];
+            if (i > 0 && flow.resetSession) {
+                await clearSessionState(context, page);
+            }
+            const outcome = (await flow.run(context, mem, { page, closeOnFinish: false }));
+            result = outcome.result;
+        }
+        if (closeOnFinish) {
+            await page.close();
+        }
+        if (options?.closeOnFinish === false) {
+            return { result, page };
+        }
+        return result;
+    };
+    return {
+        resetSession: false,
+        blocks: () => flows.flatMap((flow, idx) => flow.blocks().map((bi, i) => ({
+            ...bi,
+            ...(i === 0 && idx > 0 && flow.resetSession ? { resetSessionBefore: true } : {}),
+        }))),
+        run: run,
+        withBlockVerify(block, verify) {
+            const { flowIndex, localIndex } = locateInChain(flows, block);
+            const patched = [...flows];
+            patched[flowIndex] = patched[flowIndex].withBlockVerify(localIndex, verify);
+            return chainFlow(...patched);
+        },
+        modBlockVerify(block, nameOrIndex, newCheck) {
+            const { flowIndex, localIndex } = locateInChain(flows, block);
+            const patched = [...flows];
+            patched[flowIndex] = patched[flowIndex].modBlockVerify(localIndex, nameOrIndex, newCheck);
+            return chainFlow(...patched);
+        },
+    };
+}
 export function composeBlock(name, steps) {
     if (steps.length === 0) {
         throw new Error(`composeBlock: "${name}" needs at least one step`);
@@ -315,6 +582,50 @@ export function defineBlock(base) {
         modVerifyAll: (patches) => modVerifyAll(plain, patches),
     };
 }
+/**
+ * Builds a {@link NavBlock}. `url` accepts a plain string or a function
+ * `(mem) => string` for parameterized routes (e.g. `/dashboard/requests/:id`
+ * with a real id read from mem). `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."
+ *
+ * The generated `act()` is always exactly `page.goto(url)` - 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)}` })
+ */
+export function defineNavBlock(options) {
+    const built = defineBlock({
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        instruction: {
+            async act(page, _input, mem) {
+                const url = typeof options.url === "function" ? options.url(mem) : options.url;
+                await page.goto(url);
+            },
+            resolve: () => checkpoint(options.checkpoint),
+            ...(options.verify ? { verify: options.verify } : {}),
+            ...(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,
+    });
+    return built;
+}
 /**
  * Returns a new Block that runs exactly like `block` - same act/observe/resolve,
  * same routing - but with `verify` replaced. For giving one flow stricter (or

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start } from "./type
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, composeBlock, preflight, } from "./engine.js";
-export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, composeBlock, preflight, withSessionReset, withTitle, chainFlow, } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock } from "./engine.js";
+export type { ActionPage } from "./types.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, composeBlock, preflight, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, composeBlock, preflight, withSessionReset, withTitle, chainFlow, } from "./engine.js";

package/dist/types.d.ts

@@ -23,6 +23,29 @@ export declare function checkpoint<Tag extends string>(tag: Tag): Checkpoint<Tag
  * @example export const LoginBlock: Block<Start, LoggedIn> = { ... }
  */
 export type Start = Checkpoint<"__start__">;
+/**
+ * The `page` a regular Block's `act()` is typed against via `defineBlock` -
+ * structurally identical to Playwright's own `Page` (the same real object is
+ * passed at runtime; this is a type-only narrowing), except `goto`, `reload`,
+ * `goBack`, and `goForward` are re-declared under `@deprecated`. Nothing is
+ * blocked - every method is still fully present and callable, and this never
+ * causes a build to fail - but a TypeScript-aware editor shows the call
+ * struck through with a hover warning the instant it's typed, pointing at
+ * `defineNavBlock` instead. `NavBlock`'s own generated `act()` (the one place
+ * navigation actually belongs) uses the real `Page`, not this type - that
+ * distinction lives entirely inside `defineNavBlock` and never reaches a
+ * NavBlock's own author, who never writes its `act()` by hand.
+ */
+export type ActionPage = Omit<Page, "goto" | "reload" | "goBack" | "goForward"> & {
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    goto: Page["goto"];
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    reload: Page["reload"];
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    goBack: Page["goBack"];
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    goForward: Page["goForward"];
+};
 /**
  * The four-phase pipeline every Block runs. Most Blocks only need `act` + a
  * one-line `resolve` - add `observe` only once a Block genuinely branches, add

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "main": "./dist/index.js",