waygraph 0.15.2 → 0.15.4

package/dist/auto-session-ipc.d.ts

@@ -1,4 +1,6 @@
 import { AutoSession, type AutoSessionInit, type SessionSnapshot, type InspectDomOptions, type DomSnapshot, type TraceStep, type ApplyPathResult, type ConsoleLogEntry, type StorageSnapshot, type StubFileKind } from "./auto-session.js";
+import type { PilotHighlightFixtures } from "./pilot-overlay.js";
+export type { PilotHighlightFixtures, PilotFixtureRing } from "./pilot-overlay.js";
 export interface SessionMeta {
     sessionId: string;
     socketPath: string;
@@ -43,6 +45,15 @@ export type StorageResponse = ({
     error: string;
 };
 export type ReachResponse = ApplyPathResult;
+export type HighlightResponse = {
+    ok: true;
+    painted: number;
+    missing: string[];
+    snapshot: SessionSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * Client-side: sends one request to a running session and returns its
  * response. Reports a stale/unreachable session as an error within
@@ -94,6 +105,9 @@ export declare function requestSession(projectDir: string, sessionId: string, re
     op: "reach";
     checkpoint: string;
 }, timeoutMs?: number): Promise<ReachResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "highlight";
+} & PilotHighlightFixtures, timeoutMs?: number): Promise<HighlightResponse>;
 /**
  * Server-side: runs `session` behind a unix socket at
  * `.waygraph-auto/<sessionId>.sock`, writing session metadata only once the

package/dist/auto-session-ipc.js

@@ -235,6 +235,10 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
                 else if (request.op === "resync") {
                     response = await session.resync();
                 }
+                else if (request.op === "highlight") {
+                    const { op: _op, ...fixtures } = request;
+                    response = await session.applyHighlight(fixtures);
+                }
                 else {
                     response = { ok: false, error: `unknown op "${request.op}"` };
                 }

package/dist/auto-session.d.ts

@@ -1,6 +1,7 @@
 import { type BlockEntry, type ExploreMenu } from "./auto-explore.js";
 import { type PickResult } from "./auto-explore-run.js";
 import { type StubPhaseResult } from "./highlights.js";
+import type { PilotHighlightFixtures } from "./pilot-overlay.js";
 export interface SessionSnapshotEdge {
     /** 1-based, matching the numbers a human/agent picks by (same as printCliMenu). */
     index: number;
@@ -299,6 +300,20 @@ export declare class AutoSession {
     rawUpload(selector: string, stub: StubFileKind | {
         filePath: string;
     }): Promise<ApplyPickResult>;
+    /**
+     * Agent-sent highlight fixtures (rings + optional todos) on the live page -
+     * the Pilot equivalent of Block `stubBefore` narration in `waygraph demo`.
+     * Does not run a Block; paint-only. Missing selectors are reported, not fatal.
+     */
+    applyHighlight(fixtures: PilotHighlightFixtures): Promise<{
+        ok: true;
+        painted: number;
+        missing: string[];
+        snapshot: SessionSnapshot;
+    } | {
+        ok: false;
+        error: string;
+    }>;
     /**
      * Runs a whole multi-step route to `targetCheckpoint` in one call, instead
      * of an agent hand-picking one index at a time across many separate

package/dist/auto-session.js

@@ -5,7 +5,7 @@ import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { ensureLivePage, detectHere, seedDefaultMem, ensureMem, runOneBlock, resolveBaseUrl, } from "./auto-explore-run.js";
 import { runStubPhase } from "./highlights.js";
 import { findBlockPathDetailed } from "./graph.js";
-import { updatePilotOverlay, showPilotActivity, showPilotVision } from "./pilot-overlay.js";
+import { updatePilotOverlay, showPilotActivity, showPilotVision, showPilotFixtures } from "./pilot-overlay.js";
 /** True when a stub-phase result actually carries authored content worth keeping. */
 function stubPhaseHasContent(r) {
     return (Object.keys(r.highlights).length > 0 ||
@@ -670,6 +670,39 @@ export class AutoSession {
             quit: false,
         };
     }
+    /**
+     * Agent-sent highlight fixtures (rings + optional todos) on the live page -
+     * the Pilot equivalent of Block `stubBefore` narration in `waygraph demo`.
+     * Does not run a Block; paint-only. Missing selectors are reported, not fatal.
+     */
+    async applyHighlight(fixtures) {
+        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
+        const label = fixtures.clear === true
+            ? "clear fixtures"
+            : `${fixtures.rings?.length ?? 0} ring(s)` +
+                (fixtures.todos?.length ? `, ${fixtures.todos.length} todo(s)` : "");
+        await showPilotActivity(this.page, `Highlight: ${label}`);
+        try {
+            const { painted, missing } = await showPilotFixtures(this.page, fixtures);
+            const menu = await this.currentMenu();
+            this.lastRunNote = fixtures.clear
+                ? "highlight cleared"
+                : `highlight painted ${painted}` +
+                    (missing.length ? ` (missing: ${missing.join(", ")})` : "");
+            return {
+                ok: true,
+                painted,
+                missing,
+                snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: `highlight failed - ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
     /**
      * Runs a whole multi-step route to `targetCheckpoint` in one call, instead
      * of an agent hand-picking one index at a time across many separate

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,
@@ -7001,6 +7006,13 @@ Primary (less is more):
                                            --non-headless session someone is co-driving);
                                            send/reach never do this on their own, since they
                                            only re-detect when the position is already unknown
+  waygraph auto highlight <sessionId> '<json>'
+                                           Paint agent highlight fixtures on the live page
+                                           (rings + optional todos). Same visual language as
+                                           Block stubBefore in demo. JSON: rings[{selector,
+                                           label,tone?,size?,weight?}], todos[], todoIndex?,
+                                           todoTitle?, holdMs? (0=until next), clear:true.
+                                           Missing selectors listed in response, not fatal.
   waygraph pilot start                     Bootstrap for an agent: starts a --detach session
                                            (same as auto --cli --detach) AND reads back the
                                            whole project's Block graph (same as waygraph
@@ -7463,7 +7475,8 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                     args[1] === "goto" ||
                     args[1] === "reload" ||
                     args[1] === "reach" ||
-                    args[1] === "resync")) {
+                    args[1] === "resync" ||
+                    args[1] === "highlight")) {
                 const sub = args[1];
                 const sessionId = args[2];
                 if (!sessionId) {
@@ -7665,6 +7678,34 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                         process.exitCode = 1;
                     break;
                 }
+                if (sub === "highlight") {
+                    const raw = args[3];
+                    if (raw === undefined) {
+                        console.error('waygraph auto highlight: usage: waygraph auto highlight <sessionId> \'{"rings":[{"selector":"#x","label":"X"}]}\'');
+                        process.exit(1);
+                    }
+                    let fixtures;
+                    try {
+                        fixtures = JSON.parse(raw);
+                    }
+                    catch {
+                        console.error("waygraph auto highlight: body must be valid JSON");
+                        process.exit(1);
+                    }
+                    if (fixtures.op !== undefined && fixtures.op !== "highlight") {
+                        console.error('waygraph auto highlight: do not set "op" (or set it to "highlight")');
+                        process.exit(1);
+                    }
+                    const { op: _ignore, ...rest } = fixtures;
+                    const res = await requestSession(proj, sessionId, {
+                        op: "highlight",
+                        ...rest,
+                    });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
                 const res = await requestSession(proj, sessionId, { op: "status" });
                 console.log(JSON.stringify(res));
                 if (!res.ok)

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