waygraph 0.15.54 → 0.16.1

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

@@ -1,4 +1,4 @@
-import { WaygraphError, MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_MODVERIFY_FUNCTION_FORM, MSG_MODVERIFY_NOT_FOUND_BY_INDEX, MSG_MODVERIFY_NOT_FOUND_BY_NAME, } from "../errors.js";
+import { MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_MODVERIFY_FUNCTION_FORM, MSG_MODVERIFY_NOT_FOUND_BY_INDEX, MSG_MODVERIFY_NOT_FOUND_BY_NAME, WaygraphError, } from "../errors.js";
 export function findBlockIndex(middle, block) {
     if (typeof block === "number") {
         if (block < 0 || block >= middle.length) {
@@ -13,46 +13,6 @@ export function findBlockIndex(middle, block) {
     }
     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,
-    });
-    // Without this, branch()'s output carried no __waygraphKind/__waygraphSalt at all (defineBlock
-    // never stamps them - factories do, after defineBlock returns), so a branched Block could never
-    // pass MapBuilder's assertMapKind/assertMapSalt checks. Real bug: branching was unusable from the
-    // Waygraph Map, only from a raw runGraph() call.
-    copyWaygraphRuntime(block, routed);
-    return routed;
-}
 /**
  * Strips `withVerify`/`modVerify`/`modVerifyAll` off a Block, keeping everything
  * else - `name`, `instruction`, `next`, `requires`. Every function below that
@@ -62,8 +22,7 @@ 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) {
+export function stripMethods(block) {
     return {
         name: block.name,
         instruction: block.instruction,
@@ -82,6 +41,8 @@ export function copyWaygraphRuntime(from, to) {
         "__waygraphNavUrl",
         "__waygraphNavClick",
         "__waygraphNavFrom",
+        "__waygraphFrom",
+        "__waygraphTo",
     ]) {
         const desc = Object.getOwnPropertyDescriptor(from, key);
         if (!desc)
@@ -131,9 +92,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 +106,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 +115,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,61 +135,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 -
- * 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 function withDialog(block, options = {}) {
-    const base = stripMethods(block);
-    const act = base.instruction.act.bind(base.instruction);
-    const next = defineBlock({
-        ...base,
-        instruction: {
-            ...base.instruction,
-            async act(page, input, mem) {
-                const answer = async (dialog) => {
-                    if (options.into)
-                        mem.set(options.into, dialog.message());
-                    if (options.accept === false)
-                        await dialog.dismiss();
-                    else
-                        await dialog.accept(options.promptText);
-                };
-                const raw = page;
-                raw.once("dialog", answer);
-                try {
-                    await act(page, input, mem);
-                }
-                finally {
-                    raw.off("dialog", answer);
-                }
-            },
-        },
-    });
-    copyWaygraphRuntime(block, next);
-    return next;
-}
 /**
  * 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

package/dist/engine/block/branch.d.ts

@@ -0,0 +1,17 @@
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import { Block, DefinedBlock } from "./block.js";
+/**
+ * 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>;

package/dist/engine/block/branch.js

@@ -0,0 +1,40 @@
+import { copyWaygraphRuntime, defineBlock, stripMethods } from "./block.js";
+/**
+ * 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);
+    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,
+    });
+    // Without this, branch()'s output carried no __waygraphKind/__waygraphSalt at all (defineBlock
+    // never stamps them - factories do, after defineBlock returns), so a branched Block could never
+    // pass MapBuilder's assertMapKind/assertMapSalt checks. Real bug: branching was unusable from the
+    // Waygraph Map, only from a raw runGraph() call.
+    copyWaygraphRuntime(block, routed);
+    return routed;
+}

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/engine/block/dialog.d.ts

@@ -0,0 +1,13 @@
+import type { MemKey } from "../mem/mem.js";
+import { SomeBlock } from "./block.js";
+/**
+ * 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;

package/dist/engine/block/dialog.js

@@ -0,0 +1,37 @@
+import { copyWaygraphRuntime, defineBlock, stripMethods } from "./block.js";
+/**
+ * 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 function withDialog(block, options = {}) {
+    const base = stripMethods(block);
+    const act = base.instruction.act.bind(base.instruction);
+    const next = defineBlock({
+        ...base,
+        instruction: {
+            ...base.instruction,
+            async act(page, input, mem) {
+                const answer = async (dialog) => {
+                    if (options.into)
+                        mem.set(options.into, dialog.message());
+                    if (options.accept === false)
+                        await dialog.dismiss();
+                    else
+                        await dialog.accept(options.promptText);
+                };
+                const raw = page;
+                raw.once("dialog", answer);
+                try {
+                    await act(page, input, mem);
+                }
+                finally {
+                    raw.off("dialog", answer);
+                }
+            },
+        },
+    });
+    copyWaygraphRuntime(block, next);
+    return next;
+}

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