waygraph 0.15.54 → 0.16.0

package/dist/{types.d.ts → engine/block/block.d.ts}

@@ -1,30 +1,10 @@
 import type { Page } from "@playwright/test";
-import type { MemPage, MemKey } from "./mem-page.js";
-import type { Trait } from "./trait.js";
-import type { HighlightStubPhaseOrFn, WaygraphHighlight, WaygraphSlidesOrFn } from "./highlights.js";
-export type { WaygraphHighlight } from "./highlights.js";
-/**
- * A Checkpoint is identified solely by its string tag - a phantom marker with no
- * embedded data. Two Checkpoints with the same tag are the same state everywhere.
- */
-export type Checkpoint<Tag extends string> = {
-    readonly __state: Tag;
-};
-/**
- * Builds a Checkpoint - spells `__state` for you so no call site does it by hand.
- * @example resolve: () => checkpoint("LoggedIn")
- */
-export declare function checkpoint<Tag extends string>(tag: Tag): Checkpoint<Tag>;
-/**
- * The type every entry Block's `In` must be - `runGraph` always seeds a fresh
- * run with `checkpoint("__start__")` as the fake initial input, so a Block
- * meant to lead off a Flow needs exactly this type. Exported so no project
- * has to know or hand-type the `"__start__"` literal itself - the same reason
- * `checkpoint()` exists instead of every call site spelling `{ __state: tag }`
- * by hand.
- * @example export const LoginBlock: Block<Start, LoggedIn> = { ... }
- */
-export type Start = Checkpoint<"__start__">;
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { StubLifecycleFn } from "../stub/stub.js";
+import type { WaygraphSlidesOrFn } from "../stub/ring.js";
+import { MemPage } from "../mem/mem.js";
+import type { MemKey } from "../mem/mem.js";
+import type { Trait } from "../trait/trait.js";
 /**
  * The `page` a regular Block's `act()` is typed against via `defineBlock` -
  * structurally identical to Playwright's own `Page` (the same real object is
@@ -90,36 +70,14 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
      */
     verify?: Trait[] | ((out: Out) => Trait[]);
     /**
-     * Open block lifecycle **before / during** `act` (demo rings + fixtures).
-     * Prefer `stubBefore(ctx) { ctx.todos(...); ctx.ring(...) }` — not a closed
-     * slot object. Object map `{ email: { selector, label } }` remains a shorthand.
-     * Flow {@link HighlightFixtureMap} still overrides ring labels.
-     * @example stubBefore: (ctx) => {
-     *   ctx.todos(["Email", "Password", "Submit"]);
-     *   ctx.todoIndex(0);
-     *   ctx.highlights({ email: { selector: "#email", label: "Email" } });
-     * }
-     */
-    stubBefore?: HighlightStubPhaseOrFn<Out>;
-    /**
-     * Open block lifecycle **after** resolve (step panel rings + fixtures).
-     * Prefer `stubAfter(ctx) { ... }`. Object map shorthand still works.
-     * Prefer this over legacy {@link Instruction.highlights}.
-     * @example stubAfter: (ctx) => {
-     *   ctx.todoIndex(2);
-     *   ctx.ring("badge", { selector: ".cart", label: "Cart updated" });
-     * }
+     * The demo's narration before the step, written by `Block.stubBefore((ctx) => ...)` where a flow uses the Block (stubs
+     * chained there add up). Not something to set in a Block's definition: Blocks carry no narration.
      */
-    stubAfter?: HighlightStubPhaseOrFn<Out>;
-    /**
-     * Open block lifecycle when a **step throws** (failed verify / act error) -
-     * before the error panel. Success-only {@link Instruction.stubAfter} never runs
-     * here. Prefer `stubOnError(ctx) { ... }`.
-     * @example stubOnError: (ctx) => {
-     *   ctx.ring("card", { selector: ".alt-1", label: "Card at failure", tag: "BUG" });
-     * }
-     */
-    stubOnError?: HighlightStubPhaseOrFn<Out>;
+    stubBefore?: StubLifecycleFn<Out>;
+    /** After the step lands; written by `Block.stubAfter((ctx) => ...)`. */
+    stubAfter?: StubLifecycleFn<Out>;
+    /** When the step fails, before the failure panel; written by `Block.stubOnError((ctx) => ...)`. */
+    stubOnError?: StubLifecycleFn<Out>;
     /**
      * Multi-step demo captions ("yap" slides) with Next between each -
      * not block lifecycle. Explains a long process; optional `selector` rings
@@ -130,11 +88,6 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
      * ]
      */
     slides?: WaygraphSlidesOrFn<Out>;
-    /**
-     * @deprecated Prefer {@link Instruction.stubAfter}. Shimmed to stubAfter keys
-     * `"0"`, `"1"`, … when stubAfter is empty.
-     */
-    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
 }
 /**
  * One selectable option for a Block whose real choices depend on the live
@@ -200,7 +153,7 @@ export interface Block<In extends Checkpoint<string>, Out extends Checkpoint<str
      * Block, meaning "terminal after one step". Returning the Block itself is a
      * self-loop - see `runGraph`'s `maxSteps` for the safety net that needs.
      */
-    next?(checkpoint: Out): Block<any, any> | null | undefined;
+    next?(checkpoint: Out): SomeBlock | null | undefined;
     /**
      * `branch()`'s routing table as plain, readable data - Checkpoint tag ->
      * target Block's `.name` (`null` for a terminal tag) - alongside {@link next}
@@ -220,12 +173,12 @@ export interface Block<In extends Checkpoint<string>, Out extends Checkpoint<str
      * `act`.
      * @example requires: [LoginCreds.key]
      */
-    requires?: readonly MemKey<any>[];
+    requires?: readonly MemKey<unknown>[];
     /**
-     * Demo pacing for this Block or compose group (`withBlockPace`).
+     * Demo pacing for this Block (the `{ pace }` step option).
      * Demo/step only - `runGraph` ignores. Prefer `fastForwardComposeBlock` for blitz.
      */
-    demoPace?: import("./highlights.js").DemoPace;
+    demoPace?: import("../stub/pace.js").DemoPace;
     /**
      * Optional. When this Block's real choices depend on the live page
      * (which of several items to add to cart, which of several rows to
@@ -282,39 +235,101 @@ export type DefinedBlock<In extends Checkpoint<string>, Out extends Checkpoint<s
      * Overloads keep `ctx` typed when the author passes a lifecycle function
      * (a single union parameter would make the callback param `any`).
      */
-    stubBefore(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
-    stubBefore(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
+    stubBefore(stub: import("../stub/stub.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
     /** Demo narration after resolve. Prefer ctx callbacks over slot-map objects. */
-    stubAfter(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
-    stubAfter(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
+    stubAfter(stub: import("../stub/stub.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
     /** Demo narration when the step fails / expected-failure path. */
-    stubOnError(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
-    stubOnError(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
+    stubOnError(stub: import("../stub/stub.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
 };
 /**
- * Structural (not imported) twin of `engine.ts`'s `Layout` - `types.ts` sits
- * below `engine.ts` in the module graph, so it can't import `Layout` without
- * a cycle. Same shape, matched by TypeScript's structural typing: any real
- * `Layout` satisfies this with no cast needed at the `connect()` call site.
+ * Any Block, whatever its route. A Block takes its `In` Checkpoint as a callback argument, so it is contravariant in `In`
+ * and no one Checkpoint type covers every Block: `any` is that "some Block", written once here.
+ */
+export type SomeBlock = Block<any, any>;
+/** Any {@link DefinedBlock} (see {@link SomeBlock}). */
+export type SomeDefinedBlock = DefinedBlock<any, any>;
+export declare function findBlockIndex(middle: readonly SomeBlock[], block: SomeBlock | 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 interface ConnectLayout {
+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>;
+/** Copy non-enumerable waygraph markers so decorate/withVerify keep map() kind checks. */
+export declare function copyWaygraphRuntime(from: object, to: object): void;
+/**
+ * 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;
-    appliesTo: (tag: string) => boolean;
-    verify: Trait[] | ((out: any) => Trait[]);
-}
+    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>;
 /**
- * Composes two Blocks into one, typechecked so this only compiles when A's output
- * tag equals B's input tag. The composed Block's act runs A's full instruction
- * (act -> observe? -> resolve) then hands the resulting Checkpoint into B's act;
- * its own observe/resolve are simply B's, since B is what decides the final 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.
  *
- * `layouts`, if given, also runs against the intermediate Checkpoint (A's
- * resolved output, right before B's act) - the same enforcement `runGraph`'s
- * own loop already applies to a chain's FINAL Checkpoint, but a
- * `defineFlow`-built Flow never reaches that loop per-hop: `buildFlow`
- * reduces the whole Block array into one `connect()`-composed super-Block, so
- * every intermediate hop's verify (and now layout) has to run HERE, inside
- * this recursive `act`, not in `runGraph`'s loop, which only ever sees the
- * one composed Block run start to finish.
+ * Wrap the one Block you want to change, in place, where a flow uses it:
+ * `map().gotoPage(NavLoginBlock).method(withVerify(AddToCartBlock, [...]))`.
+ */
+export declare function withVerify<B extends SomeBlock>(block: B, verify: Trait[] | ((out: any) => Trait[])): B;
+/**
+ * Answers the browser's own dialog (`confirm`, `alert`, `prompt`, `beforeunload`) that this Block's action
+ * triggers. A dialog freezes the page until it is answered, so the answer has to be armed before the click -
+ * this does that without folding it into the Block's own `act`. The dialog's text can be kept in mem.
+ * @example withDialog(CancelBlock, { accept: true, into: LeaveWarning })
+ */
+export declare function withDialog<B extends SomeBlock>(block: B, options?: {
+    accept?: boolean;
+    into?: MemKey<string>;
+    promptText?: string;
+}): 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 connect<A extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>>(a: Block<A, B>, b: Block<B, C>, layouts?: readonly ConnectLayout[]): Block<A, C>;
+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>;

package/dist/{core → engine/block}/block.js

@@ -27,7 +27,6 @@ export function findBlockIndex(middle, block) {
  */
 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)) {
@@ -62,7 +61,6 @@ export function branch(block, routes) {
  * `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,
@@ -82,6 +80,8 @@ export function copyWaygraphRuntime(from, to) {
         "__waygraphNavUrl",
         "__waygraphNavClick",
         "__waygraphNavFrom",
+        "__waygraphFrom",
+        "__waygraphTo",
     ]) {
         const desc = Object.getOwnPropertyDescriptor(from, key);
         if (!desc)
@@ -131,9 +131,9 @@ export function defineBlock(base) {
         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),
+        stubBefore: (stub) => withStubPhase(defined, "stubBefore", stub),
+        stubAfter: (stub) => withStubPhase(defined, "stubAfter", stub),
+        stubOnError: (stub) => withStubPhase(defined, "stubOnError", stub),
     };
     return defined;
 }
@@ -145,13 +145,8 @@ export function defineBlock(base) {
  * 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.
+ * Wrap the one Block you want to change, in place, where a flow uses it:
+ * `map().gotoPage(NavLoginBlock).method(withVerify(AddToCartBlock, [...]))`.
  */
 export function withVerify(block, verify) {
     const base = stripMethods(block);
@@ -159,29 +154,10 @@ export function withVerify(block, 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. */
+/** Runs a prior stub into the same ctx, so stubs chained on one Block add up. */
 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);
-        }
-    }
+    if (raw !== undefined)
+        await raw(ctx);
 }
 function withStubPhase(block, phase, stub) {
     const base = stripMethods(block);
@@ -198,25 +174,6 @@ function withStubPhase(block, phase, stub) {
     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", { ... }) })
- * @deprecated Use the chained method: `Block.stubBefore((ctx) => …)`.
- */
-export function withStubBefore(block, stub) {
-    return withStubPhase(block, "stubBefore", stub);
-}
-/** @see {@link withStubBefore}  * @deprecated Use the chained method: `Block.stubAfter((ctx) => …)`.
- */
-export function withStubAfter(block, stub) {
-    return withStubPhase(block, "stubAfter", stub);
-}
-/** @see {@link withStubBefore}  * @deprecated Use the chained method: `Block.stubOnError((ctx) => …)`.
- */
-export function withStubOnError(block, stub) {
-    return withStubPhase(block, "stubOnError", stub);
-}
 /**
  * Answers the browser's own dialog (`confirm`, `alert`, `prompt`, `beforeunload`) that this Block's action
  * triggers. A dialog freezes the page until it is answered, so the answer has to be armed before the click -

package/dist/{core → engine/block}/compose.d.ts

@@ -1,10 +1,12 @@
-import type { BlockInfo } from "./flow.js";
-import type { Block, Checkpoint } from "../types.js";
-import type { Trait } from "../trait.js";
+import type { BlockInfo } from "../flow/flow.js";
+import type { Block } from "./block.js";
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { Trait } from "../trait/trait.js";
+import type { SomeBlock } from "./block.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
+ * a flow 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> {
@@ -19,14 +21,14 @@ export interface ComposedBlock<In extends Checkpoint<string>, Out extends Checkp
      * 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>;
+    withStepVerify(step: SomeBlock | 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>;
+    modStepVerify(step: SomeBlock | string | number, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): ComposedBlock<In, Out>;
 }
 /**
  * Chains several Blocks into one named, exported unit - what a naturally
@@ -66,7 +68,7 @@ export interface FastForwardComposedBlock<In extends Checkpoint<string>, Out ext
     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 isFastForwardBlock(block: SomeBlock): block is FastForwardComposedBlock<any, any>;
 /** Like `composeBlock`, but the steps run as one blitz-paced unit in a demo. */
 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>;

package/dist/{core → engine/block}/compose.js

@@ -1,4 +1,4 @@
-import { connect } from "../types.js";
+import { connect } from "../run/connect.js";
 import { WaygraphError, MSG_COMPOSE_EMPTY, MSG_FASTFORWARD_EMPTY } from "../errors.js";
 import { findBlockIndex, modVerify, withVerify } from "./block.js";
 export function composeBlock(name, steps) {

package/dist/{core/blocks → engine/block/kinds}/api.d.ts

@@ -1,7 +1,8 @@
-import type { Checkpoint, DefinedBlock } from "../../types.js";
-import type { Trait } from "../../trait.js";
-import { MemPage } from "../../mem-page.js";
-import type { MemKey } from "../../mem-page.js";
+import type { Checkpoint } from "../../checkpoint/checkpoint.js";
+import type { DefinedBlock } from "../block.js";
+import type { Trait } from "../../trait/trait.js";
+import { MemPage } from "../../mem/mem.js";
+import type { MemKey } from "../../mem/mem.js";
 import type { APIRequestContext, APIResponse } from "@playwright/test";
 /** What `resolve`/`verify` see: the response's status and parsed body, nothing Playwright-specific. */
 export interface ApiCallResult {
@@ -31,13 +32,14 @@ export interface ApiBlockOptions<In extends Checkpoint<string>, Out extends Chec
      * @example method: "POST"
      */
     method?: string;
-    /** Pure, like every other Block's resolve - classifies the response into a Checkpoint tag. */
-    resolve: (result: ApiCallResult) => Out;
+    /** Where it runs: one Checkpoint value or a list; leave it out for "from anywhere". */
+    from?: In | readonly In[];
+    /** Where it lands: one Checkpoint value (then `resolve` may be left out) or a list. */
+    to: Out | readonly Out[];
+    /** Pure, like every other Block's resolve - picks the Checkpoint from the response. Optional when `to` is one Checkpoint. */
+    resolve?: (result: ApiCallResult) => Out;
     verify?: Trait[] | ((out: Out) => Trait[]);
-    requires?: readonly MemKey<any>[];
-    stubBefore?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    stubAfter?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
-    stubOnError?: import("../../highlights.js").HighlightStubPhaseOrFn<Out>;
+    requires?: readonly MemKey<unknown>[];
 }
 /**
  * A Block whose `act()` is a real HTTP request, not a page interaction - lets one Flow narrate a
@@ -45,10 +47,12 @@ export interface ApiBlockOptions<In extends Checkpoint<string>, Out extends Chec
  * machine, checked by the same Trait/verify system. Runs through `page.request`, so it shares the
  * browser context's cookies/origin - no separate auth dance for an already-logged-in session.
  * @example
- * const CheckOrderCreated = defineApiBlock<LoggedIn, OrderConfirmed | OrderFailed>({
+ * const CheckOrderCreated = defineApiBlock({
  *   name: "check-order-created",
+ *   from: LoggedIn,
+ *   to: [OrderConfirmed, OrderFailed],
  *   call: ({ request }) => request.get("/api/orders/latest"),
- *   resolve: (r) => (r.ok ? checkpoint("OrderConfirmed") : checkpoint("OrderFailed")),
+ *   resolve: (r) => (r.ok ? OrderConfirmed : OrderFailed),
  *   verify: [Trait.disabled],
  * });
  */

package/dist/{core/blocks → engine/block/kinds}/api.js

@@ -1,5 +1,13 @@
+// New Block kind: a backend/API check, not a page action - proves a Flow can mix a UI step
+// (defineNavBlock/defineMethodBlock) with a real HTTP request in the SAME state machine, verified
+// by the same Trait system everything else uses. Built on Playwright's own `page.request`
+// (APIRequestContext) - no shell-out to curl, no second HTTP client to depend on.
+import { recordApiCall } from "../../run/hooks.js";
+import { checkpoint } from "../../checkpoint/checkpoint.js";
+import { markRouteOf, tagsOf } from "../../checkpoint/route.js";
 import { defineBlock } from "../block.js";
-import { key } from "../../mem-page.js";
+import { key } from "../../mem/mem.js";
+import { ignorePageGone } from "../../page-gone.js";
 // Internal scratch key threading act()'s result to observe()/resolve() - Instruction has no other
 // channel for this (resolve is pure, given only what observe returns). Identity-keyed, so this can
 // never collide with a real author's own MemKey even if names happened to match; safe to share one
@@ -11,14 +19,22 @@ const API_RESULT_SCRATCH = key("__wgApiBlockResult");
  * machine, checked by the same Trait/verify system. Runs through `page.request`, so it shares the
  * browser context's cookies/origin - no separate auth dance for an already-logged-in session.
  * @example
- * const CheckOrderCreated = defineApiBlock<LoggedIn, OrderConfirmed | OrderFailed>({
+ * const CheckOrderCreated = defineApiBlock({
  *   name: "check-order-created",
+ *   from: LoggedIn,
+ *   to: [OrderConfirmed, OrderFailed],
  *   call: ({ request }) => request.get("/api/orders/latest"),
- *   resolve: (r) => (r.ok ? checkpoint("OrderConfirmed") : checkpoint("OrderFailed")),
+ *   resolve: (r) => (r.ok ? OrderConfirmed : OrderFailed),
  *   verify: [Trait.disabled],
  * });
  */
 export function defineApiBlock(options) {
+    const targets = tagsOf(options.to);
+    const pick = options.resolve;
+    if (!pick && targets.length !== 1) {
+        throw new Error(`waygraph: API Block "${options.name}" lands on several Checkpoints; give it a resolve() that picks one`);
+    }
+    const resolve = pick ?? (() => checkpoint(targets[0]));
     const built = defineBlock({
         name: options.name,
         ...(options.description ? { description: options.description } : {}),
@@ -33,20 +49,12 @@ export function defineApiBlock(options) {
                     body = await response.json();
                 }
                 catch {
-                    body = await response.text().catch(() => undefined);
+                    body = await response.text().catch(ignorePageGone);
                 }
                 mem.set(API_RESULT_SCRATCH, { status: response.status(), ok: response.ok(), body });
-                // Best-effort, demo-only visibility - an API step has no DOM change and no ring of its own,
-                // so without this it's a silent title flash. No-ops outside a demo/pilot/auto run (see
-                // addNetworkEntry's own guard) and never fails the Block if painting the panel throws.
-                // Same network-tab panel real page traffic feeds too (network-capture.js) - this is the
-                // page.request side of it (a separate APIRequestContext, never seen by page.on('request')).
+                // Shown in the demo's network panel when a demo layer registered a recorder; never fails the Block.
                 try {
-                    // recordNetworkEntry, not a bare addNetworkEntry evaluate - it also persists this entry
-                    // to page.__wgNetworkHistory (Node-side, survives navigation), so it isn't lost the
-                    // moment a later step in the same Flow navigates and wipes the panel's DOM.
-                    const { recordNetworkEntry } = await import("../../runner/network-capture.js");
-                    await recordNetworkEntry(page, {
+                    await recordApiCall(page, {
                         method: options.method || "GET",
                         url: response.url(),
                         status: response.status(),
@@ -63,13 +71,13 @@ export function defineApiBlock(options) {
             async observe(_page, mem) {
                 return mem.get(API_RESULT_SCRATCH);
             },
-            resolve: (observed) => options.resolve(observed),
+            resolve: (observed) => resolve(observed),
             ...(options.verify !== undefined ? { verify: options.verify } : {}),
-            ...(options.stubBefore !== undefined ? { stubBefore: options.stubBefore } : {}),
-            ...(options.stubAfter !== undefined ? { stubAfter: options.stubAfter } : {}),
-            ...(options.stubOnError !== undefined ? { stubOnError: options.stubOnError } : {}),
         },
     });
+    markRouteOf(built, options);
     Object.defineProperty(built, "__waygraphKind", { value: "api", enumerable: false, configurable: false });
+    // Accepted by map().method(), like a Method: one step that lands on a Checkpoint.
+    Object.defineProperty(built, "__waygraphSalt", { value: "api", enumerable: false, configurable: false });
     return built;
 }

package/dist/{core/blocks → engine/block/kinds}/effect.d.ts

@@ -1,7 +1,8 @@
-import type { Block, Checkpoint, DefinedBlock } from "../../types.js";
-import type { MemKey } from "../../mem-page.js";
-import type { Trait } from "../../trait.js";
-import { defineBlock } from "../block.js";
+import type { Block, DefinedBlock } from "../block.js";
+import type { Checkpoint } from "../../checkpoint/checkpoint.js";
+import type { MemKey } from "../../mem/mem.js";
+import type { Trait } from "../../trait/trait.js";
+import type { RoutedBlockBase } from "../../checkpoint/route.js";
 /**
  * TypeScript salt over {@link defineBlock}: same runtime Block, but the type
  * forces `requires` + `instanceOptions` so `waygraph auto` can list one menu
@@ -10,29 +11,23 @@ import { defineBlock } from "../block.js";
  */
 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>[];
+    requires: readonly MemKey<unknown>[];
     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>;
-    stubAfter(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
-    stubAfter(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
-    stubOnError(stub: import("../../highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
-    stubOnError(stub: import("../../highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubBefore(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubAfter(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubOnError(stub: import("../../stub/stub.js").StubLifecycleFn<Out>): 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>[];
+export type EffectExtras<In extends Checkpoint<string>, Out extends Checkpoint<string>> = {
+    requires: readonly MemKey<unknown>[];
     instanceOptions: NonNullable<Block<In, Out>["instanceOptions"]>;
-}): EffectBlock<In, Out>;
-/** @deprecated Prefer {@link defineEffectBlock} - identical helper. */
-export declare const defineMemEffectBlock: typeof defineEffectBlock;
+};
+export declare function defineEffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: RoutedBlockBase<In, Out> & EffectExtras<In, Out>): EffectBlock<In, Out>;

package/dist/engine/block/kinds/effect.js

@@ -0,0 +1,17 @@
+import { defineBlock } from "../block.js";
+import { markRouteOf, routed } from "../../checkpoint/route.js";
+export function defineEffectBlock(base) {
+    const built = defineBlock(routed(base));
+    markRouteOf(built, base);
+    Object.defineProperty(built, "__waygraphMemKind", {
+        value: "effect",
+        enumerable: false,
+        configurable: false,
+    });
+    Object.defineProperty(built, "__waygraphSalt", {
+        value: "effect",
+        enumerable: false,
+        configurable: false,
+    });
+    return built;
+}