waygraph 0.15.1 → 0.15.3

package/dist/cli.js

@@ -2381,6 +2381,7 @@ async function presentFailPanel(page, opts) {
     gatesFast,
     demoPace,
     gate,
+    mem,
   } = opts;
   if (hasAuthoredStubOnError(block, fixtures)) {
     await page
@@ -2396,6 +2397,7 @@ async function presentFailPanel(page, opts) {
       fixtures,
       error,
       out: opts.out,
+      mem,
     });
     const errHighlights = errPhase.highlights.map((h) => {
       const styled = applyHighlightStyleDefaults(h, opts.highlightStyle);
@@ -5101,7 +5103,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       !!r.wasFastForward;
     const fixtures = r.highlightFixtures;
     const flowStyle = r.highlightStyle;
-    const stubBeforePhase = await runStubPhase(r.block, "stubBefore", { fixtures });
+    const stubBeforePhase = await runStubPhase(r.block, "stubBefore", { fixtures, mem });
     stubBeforeRef.current = stubBeforePhase.highlights.map((h) =>
       applyHighlightStyleDefaults(h, flowStyle),
     );
@@ -5317,6 +5319,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         gatesFast: pacing.gatesFast,
         demoPace: pacing.demoPace,
         gate,
+        mem,
       });
       if (errEdits && errEdits.__wgRetry) {
         await resetPageState(context, page, baseURL);
@@ -5376,6 +5379,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         gatesFast: pacing.gatesFast,
         demoPace: pacing.demoPace,
         gate,
+        mem,
       });
       if (errEdits && errEdits.__wgRetry) {
         await resetPageState(context, page, baseURL);
@@ -5416,6 +5420,7 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       const afterPhase = await runStubPhase(r.block, "stubAfter", {
         out: result,
         fixtures: fixturesAfter,
+        mem,
       });
       logStubPhaseFixtures("after", {
         ...afterPhase,

package/dist/engine.d.ts

@@ -707,37 +707,58 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
     private readonly engine;
     private readonly steps;
     private readonly homeOrigin;
+    private readonly ff;
     private constructor();
     /** @internal - use `engine.map()` or the standalone `map()` export. */
     static begin(engine: Engine, homeOrigin: string | undefined): MapBuilder<S>;
     /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
     start(): MapBuilder<Out>;
+    /**
+     * Open a fast-forward window - steps until {@link ffEnd} collapse into one
+     * opaque `fastForwardComposeBlock` (blitz theater). Kind/salt checks still
+     * run on each inner step as it is added.
+     */
+    ffStart(name?: string): MapBuilder<Out>;
+    /**
+     * Close the current fast-forward window and append one FFCompose step.
+     * Throws if empty or if {@link ffStart} was never opened.
+     */
+    ffEnd(): MapBuilder<Out>;
+    private appendStep;
     /**
      * Appends an internal navigation/page-arrival step - requires a Block from
      * `defineNavBlock`/`defineMemNavBlock`/`definePageBlock`. Throws if given
      * anything else, including a `homeOrigin`-mismatched static `url`.
+     * Compile-time: {@link NavBlock} or {@link PageBlock} only (not Assert/Method).
      */
-    gotoPage<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+    gotoPage<NextOut extends Checkpoint<string>>(block: (NavBlock<NextOut> | PageBlock<NextOut>) & {
         name: string;
     }): MapBuilder<NextOut>;
     /**
      * Appends a genuinely cross-origin navigation step (e.g. `(external)/`
      * Blocks in the Waygraph Map convention: mailpit, maildrop.cc) - same
      * kind requirement as {@link gotoPage}, plus the inverse `homeOrigin` check.
+     * Compile-time: {@link NavBlock} or {@link PageBlock} only.
      */
-    gotoExternal<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+    gotoExternal<NextOut extends Checkpoint<string>>(block: (NavBlock<NextOut> | PageBlock<NextOut>) & {
         name: string;
     }): MapBuilder<NextOut>;
-    /** Appends a self-loop verification step - requires a Block from `defineAssertBlock`. */
-    assert<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+    /**
+     * Appends a self-loop verification step - requires a Block from
+     * `defineAssertBlock`. Compile-time: {@link AssertBlock} only (not `.method()`).
+     */
+    assert(block: AssertBlock<Out> & {
         name: string;
-    }): MapBuilder<NextOut>;
+    }): MapBuilder<Out>;
     /**
      * Appends a non-navigating page action (submit, upload, add/remove an
      * instance) - requires a Block from `defineMethodBlock`/`defineActionBlock`/
      * `defineEffectBlock`/`defineMemEffectBlock`.
+     * Compile-time: {@link MethodBlock} or {@link EffectBlock} only - Assert
+     * Blocks must use `.assert()`. Runtime also rejects `__waygraphKind =
+     * "assert"` (those still carry method salt from the factory internals).
      */
-    method<NextOut extends Checkpoint<string>>(block: Block<Out, NextOut> & {
+    method<NextOut extends Checkpoint<string>>(block: (MethodBlock<Out, NextOut> | EffectBlock<Out, NextOut>) & {
         name: string;
     }): MapBuilder<NextOut>;
     /**
@@ -799,8 +820,27 @@ export declare function defineBlock<In extends Checkpoint<string>, Out extends C
  * `defineFlow([...])`, `connect()`, `composeBlock()` exactly like any other
  * Block - no special-casing needed anywhere that only expects a `Block`.
  * See `openspec/specs/nav-block-and-check/spec.md` for why this exists.
+ *
+ * `__wgFactory` is a TypeScript-only brand so {@link MapBuilder.gotoPage} /
+ * {@link MapBuilder.gotoExternal} can reject Assert/Method Blocks at compile
+ * time (runtime still checks `__waygraphKind`). Decorate methods are re-stated
+ * (via Omit) so `.stubBefore()` / `.withVerify()` keep the brand.
  */
-export type NavBlock<Out extends Checkpoint<string>> = DefinedBlock<Checkpoint<string>, Out>;
+export type NavBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Checkpoint<string>, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "nav";
+    withVerify(verify: Trait[] | ((out: Out) => Trait[])): NavBlock<Out>;
+    modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): NavBlock<Out>;
+    modVerifyAll(patches: Record<string, Trait["check"] | Trait>): NavBlock<Out>;
+    stubBefore(stub: import("./highlights.js").HighlightStubPhase): NavBlock<Out>;
+    stubBefore(stub: import("./highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
+    stubBefore(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): NavBlock<Out>;
+    stubAfter(stub: import("./highlights.js").HighlightStubPhase): NavBlock<Out>;
+    stubAfter(stub: import("./highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
+    stubAfter(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): NavBlock<Out>;
+    stubOnError(stub: import("./highlights.js").HighlightStubPhase): NavBlock<Out>;
+    stubOnError(stub: import("./highlights.js").StubLifecycleFn<Out>): NavBlock<Out>;
+    stubOnError(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): NavBlock<Out>;
+};
 /**
  * `defineNavBlock`'s own options - exactly one of `url`/`click` required,
  * enforced at compile time (giving both, or neither, is a type error - see
@@ -897,7 +937,21 @@ export declare function defineNavClickBlock<Out extends Checkpoint<string>>(opti
  * {@link defineEffectBlock} when the auto menu should spawn one row per live
  * DOM instance. Prefer hanging methods off a {@link definePageBlock} hub.
  */
-export type MethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = DefinedBlock<In, Out>;
+export type MethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = Omit<DefinedBlock<In, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "method";
+    withVerify(verify: Trait[] | ((out: Out) => Trait[])): MethodBlock<In, Out>;
+    modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): MethodBlock<In, Out>;
+    modVerifyAll(patches: Record<string, Trait["check"] | Trait>): MethodBlock<In, Out>;
+    stubBefore(stub: import("./highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubBefore(stub: import("./highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubBefore(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubAfter(stub: import("./highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubAfter(stub: import("./highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubAfter(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubOnError(stub: import("./highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+    stubOnError(stub: import("./highlights.js").StubLifecycleFn<Out>): MethodBlock<In, Out>;
+    stubOnError(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): MethodBlock<In, Out>;
+};
 /** @deprecated Prefer {@link MethodBlock} - same type; Action was the 0.7 name. */
 export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = MethodBlock<In, Out>;
 export declare function defineMethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0]): MethodBlock<In, Out>;
@@ -941,7 +995,26 @@ export interface AssertBlockOptions<Out extends Checkpoint<string> = Checkpoint<
  *   verify: [Trait.visible(RawMaterialsSel.reorderBadge)],
  * });
  */
-export declare function defineAssertBlock<Out extends Checkpoint<string> = Checkpoint<string>>(options: AssertBlockOptions<Out>): MethodBlock<Out, Out>;
+export declare function defineAssertBlock<Out extends Checkpoint<string> = Checkpoint<string>>(options: AssertBlockOptions<Out>): AssertBlock<Out>;
+/**
+ * Self-loop verify Block from {@link defineAssertBlock}. Branded for
+ * {@link MapBuilder.assert} (not accepted by `.method()`).
+ */
+export type AssertBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Out, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "assert";
+    withVerify(verify: Trait[] | ((out: Out) => Trait[])): AssertBlock<Out>;
+    modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): AssertBlock<Out>;
+    modVerifyAll(patches: Record<string, Trait["check"] | Trait>): AssertBlock<Out>;
+    stubBefore(stub: import("./highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubBefore(stub: import("./highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubBefore(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubAfter(stub: import("./highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubAfter(stub: import("./highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubAfter(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubOnError(stub: import("./highlights.js").HighlightStubPhase): AssertBlock<Out>;
+    stubOnError(stub: import("./highlights.js").StubLifecycleFn<Out>): AssertBlock<Out>;
+    stubOnError(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): AssertBlock<Out>;
+};
 /** One Block (or lazy factory) registered on a {@link PageBlock}. */
 export type PageMethodEntry = DefinedBlock<any, any> | (() => DefinedBlock<any, any>);
 export type PageBlockOptions<Out extends Checkpoint<string>> = {
@@ -975,10 +1048,25 @@ export type PageBlockOptions<Out extends Checkpoint<string>> = {
  * readability / auto grouping. Runtime is still a Block (`__waygraphKind = "page"`).
  * `act` is goto/click when `url`/`click` is set, otherwise a no-op (already here).
  * Child methods stay ordinary Blocks for graph edges - the page only registers them.
+ * Branded `__wgFactory: "page"` (not `"nav"`) - both are accepted by
+ * {@link MapBuilder.gotoPage} / {@link MapBuilder.gotoExternal}.
  */
-export type PageBlock<Out extends Checkpoint<string>> = NavBlock<Out> & {
+export type PageBlock<Out extends Checkpoint<string>> = Omit<DefinedBlock<Checkpoint<string>, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "page";
     /** Resolved method Blocks registered at define time. */
     readonly methods: readonly DefinedBlock<any, any>[];
+    withVerify(verify: Trait[] | ((out: Out) => Trait[])): PageBlock<Out>;
+    modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): PageBlock<Out>;
+    modVerifyAll(patches: Record<string, Trait["check"] | Trait>): PageBlock<Out>;
+    stubBefore(stub: import("./highlights.js").HighlightStubPhase): PageBlock<Out>;
+    stubBefore(stub: import("./highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
+    stubBefore(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): PageBlock<Out>;
+    stubAfter(stub: import("./highlights.js").HighlightStubPhase): PageBlock<Out>;
+    stubAfter(stub: import("./highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
+    stubAfter(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): PageBlock<Out>;
+    stubOnError(stub: import("./highlights.js").HighlightStubPhase): PageBlock<Out>;
+    stubOnError(stub: import("./highlights.js").StubLifecycleFn<Out>): PageBlock<Out>;
+    stubOnError(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): PageBlock<Out>;
 };
 /** @see {@link PageBlockOptions} */
 export declare function definePageBlock<Out extends Checkpoint<string>>(options: PageBlockOptions<Out>): PageBlock<Out>;
@@ -988,9 +1076,22 @@ export declare function definePageBlock<Out extends Checkpoint<string>>(options:
  * row per live instance (add/remove/toggle). Not a separate engine concept -
  * everything is still a Block.
  */
-export type EffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = DefinedBlock<In, Out> & {
+export type EffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = Omit<DefinedBlock<In, Out>, "withVerify" | "modVerify" | "modVerifyAll" | "stubBefore" | "stubAfter" | "stubOnError"> & {
+    readonly __wgFactory?: "effect";
     requires: readonly MemKey<any>[];
     instanceOptions: NonNullable<Block<In, Out>["instanceOptions"]>;
+    withVerify(verify: Trait[] | ((out: Out) => Trait[])): EffectBlock<In, Out>;
+    modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): EffectBlock<In, Out>;
+    modVerifyAll(patches: Record<string, Trait["check"] | Trait>): EffectBlock<In, Out>;
+    stubBefore(stub: import("./highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubBefore(stub: import("./highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubBefore(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubAfter(stub: import("./highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubAfter(stub: import("./highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubAfter(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubOnError(stub: import("./highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
+    stubOnError(stub: import("./highlights.js").StubLifecycleFn<Out>): EffectBlock<In, Out>;
+    stubOnError(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): EffectBlock<In, Out>;
 };
 /** @deprecated Prefer {@link EffectBlock} - same type; Mem* was an early name. */
 export type MemEffectBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = EffectBlock<In, Out>;
@@ -1064,7 +1165,18 @@ export declare function locate(page: Page, library: readonly NavBlock<any>[], op
  * argument at all, only whatever `verify` each Block's own `instruction` (or
  * a `withVerify(...)` wrapping it) carries with it.
  */
-export declare function withVerify<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, verify: Trait[] | ((out: Out) => Trait[])): DefinedBlock<In, Out>;
+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

package/dist/engine.js

@@ -811,52 +811,108 @@ export class MapBuilder {
     engine;
     steps;
     homeOrigin;
-    constructor(engine, steps, homeOrigin) {
+    ff;
+    constructor(engine, steps, homeOrigin, ff = null) {
         this.engine = engine;
         this.steps = steps;
         this.homeOrigin = homeOrigin;
+        this.ff = ff;
     }
     /** @internal - use `engine.map()` or the standalone `map()` export. */
     static begin(engine, homeOrigin) {
-        return new MapBuilder(engine, [], homeOrigin);
+        return new MapBuilder(engine, [], homeOrigin, null);
     }
     /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
     start() {
         return this;
     }
+    /**
+     * Open a fast-forward window - steps until {@link ffEnd} collapse into one
+     * opaque `fastForwardComposeBlock` (blitz theater). Kind/salt checks still
+     * run on each inner step as it is added.
+     */
+    ffStart(name) {
+        if (this.ff) {
+            throw new Error(`Waygraph map: .ffStart() while already inside "${this.ff.name}" - call .ffEnd() first`);
+        }
+        const ffName = typeof name === "string" && name.trim()
+            ? name.trim()
+            : `ff-${this.steps.length + 1}`;
+        return new MapBuilder(this.engine, this.steps, this.homeOrigin, {
+            name: ffName,
+            buffer: [],
+        });
+    }
+    /**
+     * Close the current fast-forward window and append one FFCompose step.
+     * Throws if empty or if {@link ffStart} was never opened.
+     */
+    ffEnd() {
+        if (!this.ff) {
+            throw new Error("Waygraph map: .ffEnd() with no open .ffStart()");
+        }
+        if (this.ff.buffer.length === 0) {
+            throw new Error(`Waygraph map: .ffEnd() for "${this.ff.name}" has no steps - add .gotoPage/.method/… inside the window`);
+        }
+        const composed = fastForwardComposeBlock(this.ff.name, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.ff.buffer);
+        return new MapBuilder(this.engine, [...this.steps, composed], this.homeOrigin, null);
+    }
+    appendStep(block) {
+        if (this.ff) {
+            return new MapBuilder(this.engine, this.steps, this.homeOrigin, {
+                name: this.ff.name,
+                buffer: [...this.ff.buffer, block],
+            });
+        }
+        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin, null);
+    }
     /**
      * Appends an internal navigation/page-arrival step - requires a Block from
      * `defineNavBlock`/`defineMemNavBlock`/`definePageBlock`. Throws if given
      * anything else, including a `homeOrigin`-mismatched static `url`.
+     * Compile-time: {@link NavBlock} or {@link PageBlock} only (not Assert/Method).
      */
     gotoPage(block) {
         assertMapKind(block, ["nav", "page"], "gotoPage");
         assertMapOrigin(block, this.homeOrigin, "internal", "gotoPage");
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+        return this.appendStep(block);
     }
     /**
      * Appends a genuinely cross-origin navigation step (e.g. `(external)/`
      * Blocks in the Waygraph Map convention: mailpit, maildrop.cc) - same
      * kind requirement as {@link gotoPage}, plus the inverse `homeOrigin` check.
+     * Compile-time: {@link NavBlock} or {@link PageBlock} only.
      */
     gotoExternal(block) {
         assertMapKind(block, ["nav", "page"], "gotoExternal");
         assertMapOrigin(block, this.homeOrigin, "external", "gotoExternal");
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+        return this.appendStep(block);
     }
-    /** Appends a self-loop verification step - requires a Block from `defineAssertBlock`. */
+    /**
+     * Appends a self-loop verification step - requires a Block from
+     * `defineAssertBlock`. Compile-time: {@link AssertBlock} only (not `.method()`).
+     */
     assert(block) {
         assertMapKind(block, ["assert"], "assert");
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+        return this.appendStep(block);
     }
     /**
      * Appends a non-navigating page action (submit, upload, add/remove an
      * instance) - requires a Block from `defineMethodBlock`/`defineActionBlock`/
      * `defineEffectBlock`/`defineMemEffectBlock`.
+     * Compile-time: {@link MethodBlock} or {@link EffectBlock} only - Assert
+     * Blocks must use `.assert()`. Runtime also rejects `__waygraphKind =
+     * "assert"` (those still carry method salt from the factory internals).
      */
     method(block) {
+        if (mapKindOf(block) === "assert") {
+            throw new Error(`Waygraph map: .method("${block.name}") got a defineAssertBlock - use .assert() for ` +
+                "self-loop verify steps (Assert Blocks share method salt internally but are not methods).");
+        }
         assertMapSalt(block, ["method", "effect"], "method");
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+        return this.appendStep(block);
     }
     /**
      * Finalizes this chain into a real, runnable {@link Flow} - same object
@@ -867,6 +923,9 @@ export class MapBuilder {
      * isn't a flow.
      */
     end() {
+        if (this.ff) {
+            throw new Error(`Waygraph map: .end() while .ffStart("${this.ff.name}") is still open - call .ffEnd() first`);
+        }
         if (this.steps.length === 0) {
             throw new Error("Waygraph map: .end() called with zero steps - add at least one .gotoPage()/.gotoExternal()/" +
                 ".assert()/.method() before .end()");
@@ -937,8 +996,38 @@ function stripMethods(block) {
         ...(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
@@ -958,12 +1047,19 @@ export function defineBlock(base) {
         ...(base.routes ? { routes: base.routes } : {}),
         ...(base.instanceOptions ? { instanceOptions: base.instanceOptions } : {}),
     };
-    return {
+    // 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(plain, verify),
-        modVerify: (nameOrIndex, newCheck) => modVerify(plain, nameOrIndex, newCheck),
-        modVerifyAll: (patches) => modVerifyAll(plain, patches),
+        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;
 }
 /**
  * Builds a {@link NavBlock}. The generated `act()` is always exactly
@@ -1120,6 +1216,8 @@ export function defineAssertBlock(options) {
         enumerable: false,
         configurable: false,
     });
+    // Brand for map().assert() - distinct from MethodBlock so .method(assert)
+    // is a compile error even though runtime still carries method salt.
     return built;
 }
 function resolvePageMethods(methods) {
@@ -1326,7 +1424,64 @@ export async function locate(page, library, options) {
  */
 export function withVerify(block, verify) {
     const base = stripMethods(block);
-    return defineBlock({ ...base, instruction: { ...base.instruction, verify } });
+    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
@@ -1371,5 +1526,7 @@ export function modVerify(block, nameOrIndex, newCheck) {
  * same fail-loud-on-unknown-name behavior holds for every entry.
  */
 export function modVerifyAll(block, patches) {
-    return Object.entries(patches).reduce((current, [name, newCheck]) => modVerify(current, name, newCheck), defineBlock(stripMethods(block)));
+    const seed = defineBlock(stripMethods(block));
+    copyWaygraphRuntime(block, seed);
+    return Object.entries(patches).reduce((current, [name, newCheck]) => modVerify(current, name, newCheck), seed);
 }

package/dist/highlights.d.ts

@@ -13,6 +13,7 @@
  * before advancing is authored the same way on stubs, flow fixtures, and slides.
  */
 import type { Block, Checkpoint } from "./types.js";
+import type { MemPage } from "./mem-page.js";
 /** Shared dwell fields on stubs, fixtures, and yap slides. */
 export type FixtureDurationFields = {
     /**
@@ -313,6 +314,12 @@ export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
  * }
  */
 export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
+    /**
+     * Live Mem for this run - same store `act`/`observe` read. Prefer this over
+     * closing over outer scope or inventing parallel fixture bags.
+     * Undefined only if the caller ran a stub phase without passing mem (tests).
+     */
+    readonly mem: MemPage | undefined;
     /** Present after resolve (stubAfter). Undefined for stubBefore. */
     readonly out: Out | undefined;
     /** Present on stubOnError when the step threw. */
@@ -636,6 +643,7 @@ export declare function completeSequentialTodoDock(dock: TodoDockState | undefin
 export declare function runStubPhase(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
     out?: Checkpoint<string>;
     error?: unknown;
+    mem?: MemPage;
     fixtures?: HighlightFixtureMap;
 }): Promise<StubPhaseResult>;
 /**

package/dist/highlights.js

@@ -795,6 +795,7 @@ export function completeSequentialTodoDock(dock) {
 }
 function createStubCtx(bag, opts) {
     return {
+        mem: opts.mem,
         out: opts.out,
         error: opts.error,
         highlights(slots) {
@@ -1143,6 +1144,7 @@ export async function runStubPhase(block, phase, opts) {
     const ctx = createStubCtx(bag, {
         ...(opts?.out !== undefined ? { out: opts.out } : {}),
         ...(opts?.error !== undefined ? { error: opts.error } : {}),
+        ...(opts?.mem !== undefined ? { mem: opts.mem } : {}),
     });
     const raw = readStubRaw(block, phase);
     if (typeof raw === "function") {

package/dist/index.d.ts

@@ -2,10 +2,10 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInsta
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible, frameVisible, frameTextEquals, frameContainsText } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
 export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
-export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible, frameVisible, frameTextEquals, frameContainsText } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";

package/dist/types.d.ts

@@ -276,6 +276,23 @@ export type DefinedBlock<In extends Checkpoint<string>, Out extends Checkpoint<s
     withVerify(verify: Trait[] | ((out: Out) => Trait[])): DefinedBlock<In, Out>;
     modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): DefinedBlock<In, Out>;
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): DefinedBlock<In, Out>;
+    /**
+     * Demo narration before act - prefer `(ctx) => { ctx.ring(...); ctx.mem?.get(...) }`.
+     * Chains after any existing stubBefore on this Block (library then call-site).
+     * 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: (out: Out) => import("./highlights.js").HighlightStubPhase): 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: (out: Out) => import("./highlights.js").HighlightStubPhase): 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: (out: Out) => import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
 };
 /**
  * Structural (not imported) twin of `engine.ts`'s `Layout` - `types.ts` sits