waygraph 0.15.24 → 0.15.26

package/dist/engine/compose.d.ts

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

package/dist/engine/compose.js

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

package/dist/engine/config.d.ts

@@ -0,0 +1,55 @@
+import type { BrowserType } from "@playwright/test";
+import type { Layout } from "./run-graph.js";
+/**
+ * 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.
+ */
+export declare function resolveLauncher(browserName: "chromium" | "firefox" | "webkit", config: EngineConfig | undefined): BrowserType;
+/** Configures how an Engine launches its own browser - only used by `Flow.run(mem)` (no context given); ignored by `Flow.run(context, mem)`, since that context is already launched. */
+export interface EngineConfig {
+    /** Default `true`, matching Playwright's own default. */
+    headless?: boolean;
+    /** Default `"chromium"`. */
+    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>>;
+    /**
+     * Playwright `recordVideo` - saves a `.webm` when the context closes.
+     * Works headless. Lighter than a full clip-engine pipeline (no overlay/ffmpeg).
+     * @example new Engine({ recordVideo: { dir: "./videos" } })
+     */
+    recordVideo?: {
+        dir: string;
+        size?: {
+            width: number;
+            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[];
+}

package/dist/engine/config.js

@@ -0,0 +1,17 @@
+// Split out of the former 2,900-line engine.ts (see src/ARCHITECTURE.md). Behavior unchanged.
+import { chromium, firefox, webkit } from "@playwright/test";
+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.
+ */
+export function resolveLauncher(browserName, config) {
+    return config?.browsers?.[browserName] ?? LAUNCHERS[browserName];
+}

package/dist/engine/core.d.ts

@@ -0,0 +1,92 @@
+import type { ActionPage, Block, Checkpoint, DefinedBlock, Instruction } from "../types.js";
+import { MemPage } from "../mem-page.js";
+import type { Trait } from "../trait.js";
+export declare function findBlockIndex(middle: readonly Block<any, any>[], block: Block<any, any> | string | number): number;
+/**
+ * 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
+ * error), and the returned Block runs exactly as `block` always did, just followed
+ * by whichever next Block the resolved tag routes to. `null` for a tag means that
+ * tag is terminal - the run stops there, same as a Block with no routing at all.
+ * A route pointing back at `block` itself is a self-loop; see `runGraph`'s
+ * `maxSteps` for its safety net. The return type is deliberately `Block<In, any>` -
+ * a route can lead anywhere, including back through itself, so there is no fixed
+ * Out type to express; state the expected outcomes to `runGraph` via `terminals`
+ * instead.
+ */
+export declare function branch<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, routes: {
+    [K in Out["__state"]]: Block<Extract<Out, Checkpoint<K>>, any> | null;
+}): DefinedBlock<In, any>;
+/**
+ * Builds a Block with `withVerify`/`modVerify`/`modVerifyAll` attached as
+ * methods - `LoginBlock.withVerify([...])`, discoverable by typing
+ * `LoginBlock.` in an editor, not just callable as `withVerify(LoginBlock, ...)`
+ * if you already know it exists. A raw object literal is still a perfectly
+ * valid Block (every test fixture in this codebase is one) - it just won't have
+ * these attached. The methods are thin: they delegate to the identically-named
+ * free functions, which remain the one place this logic actually lives.
+ */
+export declare function defineBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: {
+    name: string;
+    description?: Block<In, Out>["description"];
+    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"];
+    instanceOptions?: Block<In, Out>["instanceOptions"];
+}): DefinedBlock<In, 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
+ * looser, or just different) confirmation on a Block it didn't author, without
+ * that Block needing to have been written as a parameterized factory in
+ * anticipation. Same move as `branch()`: decorate an existing Block, don't ask
+ * every Block to pre-build its own override mechanism.
+ *
+ * Wrap the one Block you want to change, in place, wherever it already sits in
+ * a `defineFlow([...])` array - every other Block stays untouched:
+ * `defineFlow([start, LoginBlock, withVerify(AddToCartBlock, [...]), end])`.
+ * There is no separate positional array to keep in sync and no `null`
+ * placeholder for "skip this one" - `defineFlow` has no per-slot verify
+ * argument at all, only whatever `verify` each Block's own `instruction` (or
+ * a `withVerify(...)` wrapping it) carries with it.
+ */
+export declare function withVerify<B extends Block<any, any>>(block: B, verify: Trait[] | ((out: any) => Trait[])): B;
+type StubPhaseFn<Out extends Checkpoint<string>> = import("../highlights.js").HighlightStubPhaseOrFn<Out>;
+/**
+ * Attach / chain a stubBefore lifecycle on a Block. Prefer
+ * `(ctx) => { ctx.ring(...); const x = ctx.mem?.get(Key); }`.
+ * @example FillUsernameBlock.stubBefore((ctx) => { ctx.ring("username", { ... }) })
+ */
+export declare function withStubBefore<B extends Block<any, any>>(block: B, stub: StubPhaseFn<any>): B;
+/** @see {@link withStubBefore} */
+export declare function withStubAfter<B extends Block<any, any>>(block: B, stub: StubPhaseFn<any>): B;
+/** @see {@link withStubBefore} */
+export declare function withStubOnError<B extends Block<any, any>>(block: B, stub: StubPhaseFn<any>): B;
+/**
+ * Replaces one Trait inside `block`'s verify list, leaving every other check
+ * untouched - the v1/v2/legacy-variant case, where one check needs a different
+ * selector or URL pattern but the rest of the Block is identical. Addressed by
+ * the Trait's own `name` (recommended - inserting or reordering other checks
+ * can't silently retarget it) or, if you genuinely know the position and don't
+ * need that safety, a numeric index. Either way a bad address fails loud
+ * immediately instead of quietly doing nothing. `newCheck` can be a bare
+ * `check` function (keeps the existing name) or a full `Trait` (to rename too).
+ * Only works on a flat `verify` array - a function-form `verify` (from
+ * `verify: (out) => Trait[]`) has no fixed list to address into, so this
+ * throws rather than guess; use `withVerify` to replace it wholesale instead.
+ */
+export declare function modVerify<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): DefinedBlock<In, Out>;
+/**
+ * `modVerify`, but for several named checks in one call - a v2 variant that
+ * differs in five ways from v1 shouldn't need five nested `modVerify(modVerify(
+ * modVerify(...)))` calls to track by eye. `patches` keys are plain strings (a
+ * Trait's `name`, not a `MemKey` instance), so an ordinary object literal is
+ * fine here - unlike `MemPage`, there's no identity-collision reason to need
+ * `[name, check]` pairs. Applies each patch in turn via `modVerify`, so the
+ * same fail-loud-on-unknown-name behavior holds for every entry.
+ */
+export declare function modVerifyAll<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, patches: Record<string, Trait["check"] | Trait>): DefinedBlock<In, Out>;
+export {};

package/dist/engine/core.js

@@ -0,0 +1,256 @@
+export function findBlockIndex(middle, block) {
+    if (typeof block === "number") {
+        if (block < 0 || block >= middle.length) {
+            throw new Error(`Flow: no Block at index ${block} in this flow (has ${middle.length})`);
+        }
+        return block;
+    }
+    const blockName = typeof block === "string" ? block : block.name;
+    const index = middle.findIndex((b) => b.name === blockName);
+    if (index === -1) {
+        throw new Error(`Flow: no Block named "${blockName}" in this flow (has: ${middle.map((b) => b.name).join(", ")})`);
+    }
+    return index;
+}
+/**
+ * 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
+ * error), and the returned Block runs exactly as `block` always did, just followed
+ * by whichever next Block the resolved tag routes to. `null` for a tag means that
+ * tag is terminal - the run stops there, same as a Block with no routing at all.
+ * A route pointing back at `block` itself is a self-loop; see `runGraph`'s
+ * `maxSteps` for its safety net. The return type is deliberately `Block<In, any>` -
+ * a route can lead anywhere, including back through itself, so there is no fixed
+ * Out type to express; state the expected outcomes to `runGraph` via `terminals`
+ * instead.
+ */
+export function branch(block, routes) {
+    const base = stripMethods(block);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let routed;
+    const routesAsData = {};
+    for (const [tag, target] of Object.entries(routes)) {
+        routesAsData[tag] = target === null ? null : target === block ? base.name : target.name;
+    }
+    routed = defineBlock({
+        ...base,
+        next: (checkpoint) => {
+            const target = routes[checkpoint.__state];
+            if (target === undefined || target === null)
+                return undefined;
+            // A route naming `block` itself (the only self-reference in scope when
+            // `routes` was written) means "loop back with routing intact" - substitute
+            // the routed Block, not the original with no `next` of its own.
+            return target === block ? routed : target;
+        },
+        routes: routesAsData,
+    });
+    return routed;
+}
+/**
+ * Strips `withVerify`/`modVerify`/`modVerifyAll` off a Block, keeping everything
+ * else - `name`, `instruction`, `next`, `requires`. Every function below that
+ * returns a new Block calls this on its input first, then rebuilds through
+ * `defineBlock`. Without it, a Block's attached methods close over the shape it
+ * had *when they were attached* - call `.withVerify()` on a Block that
+ * `branch()` added routing to afterward, and without this step the result would
+ * silently drop that routing, since the stale closure never knew about it.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function stripMethods(block) {
+    return {
+        name: block.name,
+        instruction: block.instruction,
+        ...(block.description ? { description: block.description } : {}),
+        ...(block.next ? { next: block.next } : {}),
+        ...(block.requires ? { requires: block.requires } : {}),
+        ...(block.routes ? { routes: block.routes } : {}),
+        ...(block.instanceOptions ? { instanceOptions: block.instanceOptions } : {}),
+    };
+}
+/** Copy non-enumerable waygraph markers so decorate/withVerify keep map() kind checks. */
+function copyWaygraphRuntime(from, to) {
+    for (const key of [
+        "__waygraphKind",
+        "__waygraphSalt",
+        "__waygraphNavUrl",
+        "__waygraphNavClick",
+    ]) {
+        const desc = Object.getOwnPropertyDescriptor(from, key);
+        if (!desc)
+            continue;
+        // Re-define as configurable so later decorate chains can copy again
+        // (factory markers are non-configurable on the original).
+        Object.defineProperty(to, key, {
+            value: desc.value,
+            enumerable: false,
+            writable: false,
+            configurable: true,
+        });
+    }
+    const ff = from.fastForward;
+    if (ff === true) {
+        to.fastForward = true;
+    }
+    const pace = from.demoPace;
+    if (pace !== undefined) {
+        to.demoPace = pace;
+    }
+}
+/**
+ * Builds a Block with `withVerify`/`modVerify`/`modVerifyAll` attached as
+ * methods - `LoginBlock.withVerify([...])`, discoverable by typing
+ * `LoginBlock.` in an editor, not just callable as `withVerify(LoginBlock, ...)`
+ * if you already know it exists. A raw object literal is still a perfectly
+ * valid Block (every test fixture in this codebase is one) - it just won't have
+ * these attached. The methods are thin: they delegate to the identically-named
+ * free functions, which remain the one place this logic actually lives.
+ */
+export function defineBlock(base) {
+    const plain = {
+        name: base.name,
+        instruction: base.instruction,
+        ...(base.description ? { description: base.description } : {}),
+        ...(base.next ? { next: base.next } : {}),
+        ...(base.requires ? { requires: base.requires } : {}),
+        ...(base.routes ? { routes: base.routes } : {}),
+        ...(base.instanceOptions ? { instanceOptions: base.instanceOptions } : {}),
+    };
+    // Methods must close over `defined` (this object), not `plain` - factories
+    // attach __waygraphKind/__waygraphSalt on the returned object after
+    // defineBlock returns; decorate/withVerify need those markers.
+    const defined = {
+        ...plain,
+        withVerify: (verify) => withVerify(defined, verify),
+        modVerify: (nameOrIndex, newCheck) => modVerify(defined, nameOrIndex, newCheck),
+        modVerifyAll: (patches) => modVerifyAll(defined, patches),
+        stubBefore: (stub) => withStubBefore(defined, stub),
+        stubAfter: (stub) => withStubAfter(defined, stub),
+        stubOnError: (stub) => withStubOnError(defined, stub),
+    };
+    return defined;
+}
+/**
+ * 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
+ * looser, or just different) confirmation on a Block it didn't author, without
+ * that Block needing to have been written as a parameterized factory in
+ * anticipation. Same move as `branch()`: decorate an existing Block, don't ask
+ * every Block to pre-build its own override mechanism.
+ *
+ * Wrap the one Block you want to change, in place, wherever it already sits in
+ * a `defineFlow([...])` array - every other Block stays untouched:
+ * `defineFlow([start, LoginBlock, withVerify(AddToCartBlock, [...]), end])`.
+ * There is no separate positional array to keep in sync and no `null`
+ * placeholder for "skip this one" - `defineFlow` has no per-slot verify
+ * argument at all, only whatever `verify` each Block's own `instruction` (or
+ * a `withVerify(...)` wrapping it) carries with it.
+ */
+export function withVerify(block, verify) {
+    const base = stripMethods(block);
+    const next = defineBlock({ ...base, instruction: { ...base.instruction, verify } });
+    copyWaygraphRuntime(block, next);
+    return next;
+}
+function isHighlightStubPhase(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+/** Run a prior stub (fn or slot map) into an open ctx so decorate can chain. */
+async function applyStubIntoCtx(raw, ctx) {
+    if (raw === undefined)
+        return;
+    if (typeof raw === "function") {
+        const ret = await raw(ctx);
+        if (isHighlightStubPhase(ret)) {
+            for (const [id, stub] of Object.entries(ret)) {
+                if (stub)
+                    ctx.ring(id, stub);
+            }
+        }
+        return;
+    }
+    if (isHighlightStubPhase(raw)) {
+        for (const [id, stub] of Object.entries(raw)) {
+            if (stub)
+                ctx.ring(id, stub);
+        }
+    }
+}
+function withStubPhase(block, phase, stub) {
+    const base = stripMethods(block);
+    const instr = base.instruction;
+    const prev = instr[phase];
+    const chained = async (ctx) => {
+        await applyStubIntoCtx(prev, ctx);
+        await applyStubIntoCtx(stub, ctx);
+    };
+    const next = defineBlock({
+        ...base,
+        instruction: { ...base.instruction, [phase]: chained },
+    });
+    copyWaygraphRuntime(block, next);
+    return next;
+}
+/**
+ * Attach / chain a stubBefore lifecycle on a Block. Prefer
+ * `(ctx) => { ctx.ring(...); const x = ctx.mem?.get(Key); }`.
+ * @example FillUsernameBlock.stubBefore((ctx) => { ctx.ring("username", { ... }) })
+ */
+export function withStubBefore(block, stub) {
+    return withStubPhase(block, "stubBefore", stub);
+}
+/** @see {@link withStubBefore} */
+export function withStubAfter(block, stub) {
+    return withStubPhase(block, "stubAfter", stub);
+}
+/** @see {@link withStubBefore} */
+export function withStubOnError(block, stub) {
+    return withStubPhase(block, "stubOnError", stub);
+}
+/**
+ * Replaces one Trait inside `block`'s verify list, leaving every other check
+ * untouched - the v1/v2/legacy-variant case, where one check needs a different
+ * selector or URL pattern but the rest of the Block is identical. Addressed by
+ * the Trait's own `name` (recommended - inserting or reordering other checks
+ * can't silently retarget it) or, if you genuinely know the position and don't
+ * need that safety, a numeric index. Either way a bad address fails loud
+ * immediately instead of quietly doing nothing. `newCheck` can be a bare
+ * `check` function (keeps the existing name) or a full `Trait` (to rename too).
+ * Only works on a flat `verify` array - a function-form `verify` (from
+ * `verify: (out) => Trait[]`) has no fixed list to address into, so this
+ * throws rather than guess; use `withVerify` to replace it wholesale instead.
+ */
+export function modVerify(block, nameOrIndex, newCheck) {
+    const verify = block.instruction.verify;
+    if (typeof verify === "function") {
+        throw new Error(`modVerify: "${block.name}" has a function-form verify, which has no fixed list to address into - use withVerify to replace it wholesale instead`);
+    }
+    const traits = verify ?? [];
+    const index = typeof nameOrIndex === "number" ? nameOrIndex : traits.findIndex((t) => t.name === nameOrIndex);
+    const existing = traits[index];
+    if (!existing) {
+        throw new Error(typeof nameOrIndex === "number"
+            ? `modVerify: "${block.name}" has no verify trait at index ${nameOrIndex} (has ${traits.length})`
+            : `modVerify: "${block.name}" has no verify trait named "${nameOrIndex}" (has: ${traits.map((t) => t.name).join(", ") || "none"})`);
+    }
+    const replacement = typeof newCheck === "function"
+        ? { name: typeof nameOrIndex === "string" ? nameOrIndex : existing.name, check: newCheck }
+        : newCheck;
+    const updated = [...traits];
+    updated[index] = replacement;
+    return withVerify(block, updated);
+}
+/**
+ * `modVerify`, but for several named checks in one call - a v2 variant that
+ * differs in five ways from v1 shouldn't need five nested `modVerify(modVerify(
+ * modVerify(...)))` calls to track by eye. `patches` keys are plain strings (a
+ * Trait's `name`, not a `MemKey` instance), so an ordinary object literal is
+ * fine here - unlike `MemPage`, there's no identity-collision reason to need
+ * `[name, check]` pairs. Applies each patch in turn via `modVerify`, so the
+ * same fail-loud-on-unknown-name behavior holds for every entry.
+ */
+export function modVerifyAll(block, patches) {
+    const seed = defineBlock(stripMethods(block));
+    copyWaygraphRuntime(block, seed);
+    return Object.entries(patches).reduce((current, [name, newCheck]) => modVerify(current, name, newCheck), seed);
+}