waygraph 0.15.54 → 0.16.1

package/dist/demo/stepper/view.d.ts

@@ -0,0 +1,58 @@
+import type { MemPage } from "../../engine/mem/mem.js";
+import type { SomeBlock } from "../../engine/block/block.js";
+import type { DemoPace } from "../../engine/stub/pace.js";
+import type { HighlightStyleDefaults } from "../../engine/stub/ring.js";
+import type { StepperRefs, WgPage } from "../types.js";
+import type { createOverlayStage } from "../overlay/overlay-stage.js";
+import type { Gate } from "./gate.js";
+import type { Pacing } from "./pacing.js";
+/** A step as the stepper sees it (the runner's PlayStep). */
+export interface StepperStep {
+    block: SomeBlock & {
+        description?: string;
+        fastForward?: boolean;
+        demoPace?: DemoPace;
+        __waygraphKind?: string;
+        __waygraphNavClick?: unknown;
+    };
+    episodeNumber?: number | undefined;
+    episodeTitle?: string | undefined;
+    expectedFailureReason?: string | undefined;
+    demoPace?: DemoPace | undefined;
+    highlightStyle?: HighlightStyleDefaults | undefined;
+    wasFastForward?: boolean | undefined;
+}
+/** The stepper's state for the whole run. */
+export interface StepperContext {
+    page: WgPage;
+    mem: MemPage;
+    steps: readonly StepperStep[];
+    stage: ReturnType<typeof createOverlayStage>;
+    gate: Gate;
+    pacing: Pacing;
+    refs: StepperRefs;
+    title: string | undefined;
+    stepperMode: "full" | "carousel";
+    /** A title set by a stub (`ctx.title`) names the flow from that step on, until another stub sets a new one. */
+    stickyTitle: string | undefined;
+    allEpisodes: {
+        episodeNumber: number;
+        episodeTitle: string;
+    }[];
+}
+/** The current step: where it sits in its episode, and what its before panel showed. */
+export interface StepView {
+    index: number;
+    step: StepperStep;
+    /** The breadcrumb is this step's episode ("1st of 2"), or the whole chain when there are no episodes. */
+    moduleNames: string[];
+    moduleDescriptions: string[];
+    moduleIndex: number;
+    justEnteredEpisode: boolean;
+    overlayTitle: string;
+    overlayTodoPos: string | undefined;
+}
+export declare function episodesOf(steps: readonly StepperStep[]): StepperContext["allEpisodes"];
+export declare function viewOf(ctx: StepperContext, index: number): StepView;
+/** Video and --mini get the compact pill; never false, so the person's Hide/Show choice wins otherwise. */
+export declare function forceCollapsed(): true | undefined;

package/dist/demo/stepper/view.js

@@ -0,0 +1,31 @@
+import { envFlag, envString } from "../../engine/env.js";
+export function episodesOf(steps) {
+    const episodes = [];
+    for (const s of steps) {
+        if (s.episodeNumber && !episodes.some((e) => e.episodeNumber === s.episodeNumber)) {
+            episodes.push({ episodeNumber: s.episodeNumber, episodeTitle: s.episodeTitle ?? "" });
+        }
+    }
+    return episodes;
+}
+export function viewOf(ctx, index) {
+    const step = ctx.steps[index];
+    const indices = step.episodeNumber
+        ? ctx.steps.flatMap((s, i) => (s.episodeNumber === step.episodeNumber ? [i] : []))
+        : ctx.steps.map((_s, i) => i);
+    const moduleIndex = indices.indexOf(index);
+    return {
+        index,
+        step,
+        moduleNames: indices.map((i) => ctx.steps[i].block.name),
+        moduleDescriptions: indices.map((i) => ctx.steps[i].block.description || ""),
+        moduleIndex,
+        justEnteredEpisode: moduleIndex === 0 && step.episodeNumber !== undefined,
+        overlayTitle: ctx.title || "waygraph demo",
+        overlayTodoPos: undefined,
+    };
+}
+/** Video and --mini get the compact pill; never false, so the person's Hide/Show choice wins otherwise. */
+export function forceCollapsed() {
+    return envString("WAYGRAPH_VIDEO") || envFlag("WAYGRAPH_MINI") ? true : undefined;
+}

package/dist/demo/types.d.ts

@@ -0,0 +1,85 @@
+import type { Page } from "@playwright/test";
+import type { ResolvedHighlight } from "../engine/stub/ring.js";
+import type { BannerPos } from "../engine/stub/stub.js";
+import type { TodoDockState, TodoDockUiResolved } from "../engine/stub/todos.js";
+import type { DeviceState } from "../engine/stub/viewport.js";
+export type WgPage = Page;
+declare module "playwright-core" {
+    interface Page {
+        /** The recordVideo canvas size, when recording: the stage a device shell is centered in. */
+        __wgVideoViewport?: {
+            width: number;
+            height: number;
+        } | undefined;
+        /** Without a video, the window size at the first device switch (the stage from then on). */
+        __wgHeadedStage?: {
+            width: number;
+            height: number;
+        } | undefined;
+        /** The device shell's size, rebuilt after a navigation wipes it. */
+        __wgDeviceShell?: {
+            width: number;
+            height: number;
+        } | undefined;
+        __wgDesktopFlat?: boolean | undefined;
+        __wgDevicePreset?: string | undefined;
+        __wgDeviceOrient?: string | undefined;
+        /** The real setViewportSize, kept while the demo makes the page's own one do nothing. */
+        __wgRealSetViewportSize?: Page["setViewportSize"] | undefined;
+        /** The network panel's rows; the panel's DOM does not survive a navigation, this does. */
+        __wgNetworkHistory?: NetworkEntry[] | undefined;
+        __wgNetworkNeedsRestore?: boolean | undefined;
+        __wgNetworkCaptureInstalled?: boolean | undefined;
+        __wgNetworkTabVisible?: boolean | undefined;
+    }
+    interface Keyboard {
+        __wgBeatPatched?: boolean;
+    }
+}
+/** A value the stepper's parts share and update (the todo dock as it advances, the device, the step's rings). */
+export interface Ref<T> {
+    current: T;
+}
+/** What the demo carries between a step's panels, its fill / click theater and a re-paint after navigation. */
+export interface StepperRefs {
+    stubBefore: Ref<ResolvedHighlight[]>;
+    todoDock: Ref<TodoDockState | undefined>;
+    device: Ref<DeviceState | undefined>;
+}
+/** A box on the page, in CSS pixels. */
+export interface WgBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The banner UX installOverlay takes: where it sits and how it behaves. */
+export interface BannerUiState {
+    pos?: BannerPos;
+    collision?: boolean;
+    hidden?: boolean;
+    captionFadeMs?: number;
+}
+/** What installOverlay hands every in-page installer (inpage/*.ts) through page.evaluate; auto and pilot pass only what they use. */
+export interface OverlayInstallArgs {
+    title?: string | undefined;
+    favicon?: string;
+    bannerPos?: BannerPos;
+    todoPos?: "left" | "right";
+    envAutoplay?: boolean;
+    todoDockUi?: TodoDockUiResolved;
+    bannerUi?: BannerUiState | null;
+    tag?: string;
+}
+/** One row of the network panel (inpage/network.ts): a page request or an API Block's call. */
+export interface NetworkEntry {
+    method?: string | undefined;
+    url?: string | undefined;
+    status?: number | undefined;
+    ok?: boolean | undefined;
+    ms?: number | undefined;
+    reqHeaders?: Record<string, string> | undefined;
+    resHeaders?: Record<string, string> | undefined;
+    reqBody?: string | undefined;
+    resBody?: string | undefined;
+}

package/dist/demo/verbose-log.js

@@ -0,0 +1,15 @@
+import { envFlag } from "../engine/env.js";
+/**
+ * One log format for the live overlay surfaces (auto / browser / pilot): `[HH:MM:SS.mmm] waygraph <surface>: ...`, the
+ * same shape as the demo runner's `step-mode/demo-log.ts`. Silenced by WAYGRAPH_JSON=1.
+ */
+function ts() {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, "0");
+    return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, "0")}`;
+}
+export function verboseLog(surface, msg) {
+    if (envFlag("WAYGRAPH_JSON"))
+        return;
+    console.log(`[${ts()}] waygraph ${surface}: ${msg}`);
+}

package/dist/engine/block/action-page.d.ts

@@ -0,0 +1,53 @@
+import type { Page } from "@playwright/test";
+/**
+ * The `page` a regular Block's `act()` is typed against via `defineBlock` -
+ * structurally identical to Playwright's own `Page` (the same real object is
+ * passed at runtime; this is a type-only narrowing), except `goto`, `reload`,
+ * `goBack`, and `goForward` are re-declared under `@deprecated`. Nothing is
+ * blocked - every method is still fully present and callable, and this never
+ * causes a build to fail - but a TypeScript-aware editor shows the call
+ * struck through with a hover warning the instant it's typed, pointing at
+ * `defineNavBlock` instead. `NavBlock`'s own generated `act()` (the one place
+ * navigation actually belongs) uses the real `Page`, not this type - that
+ * distinction lives entirely inside `defineNavBlock` and never reaches a
+ * NavBlock's own author, who never writes its `act()` by hand.
+ */
+import type { MemKey } from "../mem/mem.js";
+export type ActionPage = Omit<Page, "goto" | "reload" | "goBack" | "goForward"> & {
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    goto: Page["goto"];
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    reload: Page["reload"];
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    goBack: Page["goBack"];
+    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
+    goForward: Page["goForward"];
+};
+/**
+ * One selectable option for a Block whose real choices depend on the live
+ * page - "which of these items to add to cart" is only knowable by looking
+ * at the DOM, not from static analysis. `waygraph auto` calls
+ * {@link Block.instanceOptions} while building its menu and lists one row
+ * per option (via `label`) instead of a single generic "block -> checkpoint"
+ * row; picking a row does `mem.set(key, value)` before that Block's own
+ * `act()` runs, so `act()` just reads mem exactly like any other required
+ * key - it never needs to know whether it was driven by a human-authored
+ * Flow or a dynamic auto-explore menu.
+ * @example { id: "sauce-labs-backpack", label: 'Add "Sauce Labs Backpack" to cart', key: SelectedItem.key, value: { id: "sauce-labs-backpack", name: "Sauce Labs Backpack" } }
+ */
+export interface WaygraphInstanceOption<T = unknown> {
+    /** Stable id for this option - used to dedupe menu rows across rebuilds. */
+    id: string;
+    /** Shown in the menu instead of a generic "block -> checkpoint" line. */
+    label: string;
+    /** Must be one of this Block's own `requires` keys. */
+    key: MemKey<T>;
+    /** `mem.set(key, value)` right before this Block's `act()` runs. */
+    value: T;
+    /**
+     * Optional CSS selector for the element this option will act on.
+     * `waygraph auto` (headful) rings that element while the menu row is hovered
+     * so you can see what a pick would click before committing.
+     */
+    highlight?: string;
+}

package/dist/engine/block/action-page.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,53 +1,11 @@
 import type { Page } from "@playwright/test";
-import type { MemPage, MemKey } from "./mem-page.js";
-import type { Trait } from "./trait.js";
-import type { HighlightStubPhaseOrFn, WaygraphHighlight, WaygraphSlidesOrFn } from "./highlights.js";
-export type { WaygraphHighlight } from "./highlights.js";
-/**
- * A Checkpoint is identified solely by its string tag - a phantom marker with no
- * embedded data. Two Checkpoints with the same tag are the same state everywhere.
- */
-export type Checkpoint<Tag extends string> = {
-    readonly __state: Tag;
-};
-/**
- * Builds a Checkpoint - spells `__state` for you so no call site does it by hand.
- * @example resolve: () => checkpoint("LoggedIn")
- */
-export declare function checkpoint<Tag extends string>(tag: Tag): Checkpoint<Tag>;
-/**
- * The type every entry Block's `In` must be - `runGraph` always seeds a fresh
- * run with `checkpoint("__start__")` as the fake initial input, so a Block
- * meant to lead off a Flow needs exactly this type. Exported so no project
- * has to know or hand-type the `"__start__"` literal itself - the same reason
- * `checkpoint()` exists instead of every call site spelling `{ __state: tag }`
- * by hand.
- * @example export const LoginBlock: Block<Start, LoggedIn> = { ... }
- */
-export type Start = Checkpoint<"__start__">;
-/**
- * The `page` a regular Block's `act()` is typed against via `defineBlock` -
- * structurally identical to Playwright's own `Page` (the same real object is
- * passed at runtime; this is a type-only narrowing), except `goto`, `reload`,
- * `goBack`, and `goForward` are re-declared under `@deprecated`. Nothing is
- * blocked - every method is still fully present and callable, and this never
- * causes a build to fail - but a TypeScript-aware editor shows the call
- * struck through with a hover warning the instant it's typed, pointing at
- * `defineNavBlock` instead. `NavBlock`'s own generated `act()` (the one place
- * navigation actually belongs) uses the real `Page`, not this type - that
- * distinction lives entirely inside `defineNavBlock` and never reaches a
- * NavBlock's own author, who never writes its `act()` by hand.
- */
-export type ActionPage = Omit<Page, "goto" | "reload" | "goBack" | "goForward"> & {
-    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
-    goto: Page["goto"];
-    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
-    reload: Page["reload"];
-    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
-    goBack: Page["goBack"];
-    /** @deprecated Navigation doesn't belong in a regular Block's act() - use defineNavBlock instead. */
-    goForward: Page["goForward"];
-};
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { MemKey } from "../mem/mem.js";
+import { MemPage } from "../mem/mem.js";
+import type { WaygraphSlidesOrFn } from "../stub/ring.js";
+import type { StubLifecycleFn } from "../stub/stub.js";
+import type { Trait } from "../trait/trait.js";
+import type { ActionPage, WaygraphInstanceOption } from "./action-page.js";
 /**
  * The four-phase pipeline every Block runs. Most Blocks only need `act` + a
  * one-line `resolve` - add `observe` only once a Block genuinely branches, add
@@ -90,36 +48,14 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
      */
     verify?: Trait[] | ((out: Out) => Trait[]);
     /**
-     * Open block lifecycle **before / during** `act` (demo rings + fixtures).
-     * Prefer `stubBefore(ctx) { ctx.todos(...); ctx.ring(...) }` — not a closed
-     * slot object. Object map `{ email: { selector, label } }` remains a shorthand.
-     * Flow {@link HighlightFixtureMap} still overrides ring labels.
-     * @example stubBefore: (ctx) => {
-     *   ctx.todos(["Email", "Password", "Submit"]);
-     *   ctx.todoIndex(0);
-     *   ctx.highlights({ email: { selector: "#email", label: "Email" } });
-     * }
-     */
-    stubBefore?: HighlightStubPhaseOrFn<Out>;
-    /**
-     * Open block lifecycle **after** resolve (step panel rings + fixtures).
-     * Prefer `stubAfter(ctx) { ... }`. Object map shorthand still works.
-     * Prefer this over legacy {@link Instruction.highlights}.
-     * @example stubAfter: (ctx) => {
-     *   ctx.todoIndex(2);
-     *   ctx.ring("badge", { selector: ".cart", label: "Cart updated" });
-     * }
+     * The demo's narration before the step, written by `Block.stubBefore((ctx) => ...)` where a flow uses the Block (stubs
+     * chained there add up). Not something to set in a Block's definition: Blocks carry no narration.
      */
-    stubAfter?: HighlightStubPhaseOrFn<Out>;
-    /**
-     * Open block lifecycle when a **step throws** (failed verify / act error) -
-     * before the error panel. Success-only {@link Instruction.stubAfter} never runs
-     * here. Prefer `stubOnError(ctx) { ... }`.
-     * @example stubOnError: (ctx) => {
-     *   ctx.ring("card", { selector: ".alt-1", label: "Card at failure", tag: "BUG" });
-     * }
-     */
-    stubOnError?: HighlightStubPhaseOrFn<Out>;
+    stubBefore?: StubLifecycleFn<Out>;
+    /** After the step lands; written by `Block.stubAfter((ctx) => ...)`. */
+    stubAfter?: StubLifecycleFn<Out>;
+    /** When the step fails, before the failure panel; written by `Block.stubOnError((ctx) => ...)`. */
+    stubOnError?: StubLifecycleFn<Out>;
     /**
      * Multi-step demo captions ("yap" slides) with Next between each -
      * not block lifecycle. Explains a long process; optional `selector` rings
@@ -130,39 +66,6 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
      * ]
      */
     slides?: WaygraphSlidesOrFn<Out>;
-    /**
-     * @deprecated Prefer {@link Instruction.stubAfter}. Shimmed to stubAfter keys
-     * `"0"`, `"1"`, … when stubAfter is empty.
-     */
-    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
-}
-/**
- * One selectable option for a Block whose real choices depend on the live
- * page - "which of these items to add to cart" is only knowable by looking
- * at the DOM, not from static analysis. `waygraph auto` calls
- * {@link Block.instanceOptions} while building its menu and lists one row
- * per option (via `label`) instead of a single generic "block -> checkpoint"
- * row; picking a row does `mem.set(key, value)` before that Block's own
- * `act()` runs, so `act()` just reads mem exactly like any other required
- * key - it never needs to know whether it was driven by a human-authored
- * Flow or a dynamic auto-explore menu.
- * @example { id: "sauce-labs-backpack", label: 'Add "Sauce Labs Backpack" to cart', key: SelectedItem.key, value: { id: "sauce-labs-backpack", name: "Sauce Labs Backpack" } }
- */
-export interface WaygraphInstanceOption<T = unknown> {
-    /** Stable id for this option - used to dedupe menu rows across rebuilds. */
-    id: string;
-    /** Shown in the menu instead of a generic "block -> checkpoint" line. */
-    label: string;
-    /** Must be one of this Block's own `requires` keys. */
-    key: MemKey<T>;
-    /** `mem.set(key, value)` right before this Block's `act()` runs. */
-    value: T;
-    /**
-     * Optional CSS selector for the element this option will act on.
-     * `waygraph auto` (headful) rings that element while the menu row is hovered
-     * so you can see what a pick would click before committing.
-     */
-    highlight?: string;
 }
 /**
  * A Block wraps one instruction. Its Observed type is an internal detail, erased here.
@@ -200,7 +103,7 @@ export interface Block<In extends Checkpoint<string>, Out extends Checkpoint<str
      * Block, meaning "terminal after one step". Returning the Block itself is a
      * self-loop - see `runGraph`'s `maxSteps` for the safety net that needs.
      */
-    next?(checkpoint: Out): Block<any, any> | null | undefined;
+    next?(checkpoint: Out): SomeBlock | null | undefined;
     /**
      * `branch()`'s routing table as plain, readable data - Checkpoint tag ->
      * target Block's `.name` (`null` for a terminal tag) - alongside {@link next}
@@ -220,12 +123,12 @@ export interface Block<In extends Checkpoint<string>, Out extends Checkpoint<str
      * `act`.
      * @example requires: [LoginCreds.key]
      */
-    requires?: readonly MemKey<any>[];
+    requires?: readonly MemKey<unknown>[];
     /**
-     * Demo pacing for this Block or compose group (`withBlockPace`).
+     * Demo pacing for this Block (the `{ pace }` step option).
      * Demo/step only - `runGraph` ignores. Prefer `fastForwardComposeBlock` for blitz.
      */
-    demoPace?: import("./highlights.js").DemoPace;
+    demoPace?: import("../stub/pace.js").DemoPace;
     /**
      * Optional. When this Block's real choices depend on the live page
      * (which of several items to add to cart, which of several rows to
@@ -282,39 +185,96 @@ export type DefinedBlock<In extends Checkpoint<string>, Out extends Checkpoint<s
      * Overloads keep `ctx` typed when the author passes a lifecycle function
      * (a single union parameter would make the callback param `any`).
      */
-    stubBefore(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
-    stubBefore(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
+    stubBefore(stub: import("../stub/stub.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
     /** Demo narration after resolve. Prefer ctx callbacks over slot-map objects. */
-    stubAfter(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
-    stubAfter(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
+    stubAfter(stub: import("../stub/stub.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
     /** Demo narration when the step fails / expected-failure path. */
-    stubOnError(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
-    stubOnError(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
+    stubOnError(stub: import("../stub/stub.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
 };
 /**
- * Structural (not imported) twin of `engine.ts`'s `Layout` - `types.ts` sits
- * below `engine.ts` in the module graph, so it can't import `Layout` without
- * a cycle. Same shape, matched by TypeScript's structural typing: any real
- * `Layout` satisfies this with no cast needed at the `connect()` call site.
+ * Any Block, whatever its route. A Block takes its `In` Checkpoint as a callback argument, so it is contravariant in `In`
+ * and no one Checkpoint type covers every Block: `any` is that "some Block", written once here.
+ */
+export type SomeBlock = Block<any, any>;
+/** The Checkpoint a Block resolves to. */
+type BlockOut<B> = B extends Block<infer _In, infer Out> ? Out : never;
+/** Any {@link DefinedBlock} (see {@link SomeBlock}). */
+export type SomeDefinedBlock = DefinedBlock<any, any>;
+export declare function findBlockIndex(middle: readonly SomeBlock[], block: SomeBlock | string | number): number;
+/**
+ * Strips `withVerify`/`modVerify`/`modVerifyAll` off a Block, keeping everything
+ * else - `name`, `instruction`, `next`, `requires`. Every function below that
+ * returns a new Block calls this on its input first, then rebuilds through
+ * `defineBlock`. Without it, a Block's attached methods close over the shape it
+ * had *when they were attached* - call `.withVerify()` on a Block that
+ * `branch()` added routing to afterward, and without this step the result would
+ * silently drop that routing, since the stale closure never knew about it.
  */
-export interface ConnectLayout {
+export declare function stripMethods<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>): {
     name: string;
-    appliesTo: (tag: string) => boolean;
-    verify: Trait[] | ((out: any) => Trait[]);
-}
+    description?: Block<In, Out>["description"];
+    instruction: Block<In, Out>["instruction"];
+    next?: Block<In, Out>["next"];
+    requires?: Block<In, Out>["requires"];
+    routes?: Block<In, Out>["routes"];
+    instanceOptions?: Block<In, Out>["instanceOptions"];
+};
+/** Copy non-enumerable waygraph markers so decorate/withVerify keep map() kind checks. */
+export declare function copyWaygraphRuntime(from: object, to: object): void;
+/**
+ * Builds a Block with `withVerify`/`modVerify`/`modVerifyAll` attached as
+ * methods - `LoginBlock.withVerify([...])`, discoverable by typing
+ * `LoginBlock.` in an editor, not just callable as `withVerify(LoginBlock, ...)`
+ * if you already know it exists. A raw object literal is still a perfectly
+ * valid Block (every test fixture in this codebase is one) - it just won't have
+ * these attached. The methods are thin: they delegate to the identically-named
+ * free functions, which remain the one place this logic actually lives.
+ */
+export declare function defineBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: {
+    name: string;
+    description?: Block<In, Out>["description"];
+    instruction: Omit<Instruction<In, Out, any>, "act"> & {
+        act(page: ActionPage, input: In, mem: MemPage): Promise<void>;
+    };
+    next?: Block<In, Out>["next"];
+    requires?: Block<In, Out>["requires"];
+    routes?: Block<In, Out>["routes"];
+    instanceOptions?: Block<In, Out>["instanceOptions"];
+}): DefinedBlock<In, Out>;
 /**
- * Composes two Blocks into one, typechecked so this only compiles when A's output
- * tag equals B's input tag. The composed Block's act runs A's full instruction
- * (act -> observe? -> resolve) then hands the resulting Checkpoint into B's act;
- * its own observe/resolve are simply B's, since B is what decides the final Out.
+ * Returns a new Block that runs exactly like `block` - same act/observe/resolve,
+ * same routing - but with `verify` replaced. For giving one flow stricter (or
+ * looser, or just different) confirmation on a Block it didn't author, without
+ * that Block needing to have been written as a parameterized factory in
+ * anticipation. Same move as `branch()`: decorate an existing Block, don't ask
+ * every Block to pre-build its own override mechanism.
  *
- * `layouts`, if given, also runs against the intermediate Checkpoint (A's
- * resolved output, right before B's act) - the same enforcement `runGraph`'s
- * own loop already applies to a chain's FINAL Checkpoint, but a
- * `defineFlow`-built Flow never reaches that loop per-hop: `buildFlow`
- * reduces the whole Block array into one `connect()`-composed super-Block, so
- * every intermediate hop's verify (and now layout) has to run HERE, inside
- * this recursive `act`, not in `runGraph`'s loop, which only ever sees the
- * one composed Block run start to finish.
+ * Wrap the one Block you want to change, in place, where a flow uses it:
+ * `map().gotoPage(NavLoginBlock).method(withVerify(AddToCartBlock, [...]))`.
+ */
+export declare function withVerify<B extends SomeBlock>(block: B, verify: Trait[] | ((out: BlockOut<B>) => Trait[])): B;
+/**
+ * Replaces one Trait inside `block`'s verify list, leaving every other check
+ * untouched - the v1/v2/legacy-variant case, where one check needs a different
+ * selector or URL pattern but the rest of the Block is identical. Addressed by
+ * the Trait's own `name` (recommended - inserting or reordering other checks
+ * can't silently retarget it) or, if you genuinely know the position and don't
+ * need that safety, a numeric index. Either way a bad address fails loud
+ * immediately instead of quietly doing nothing. `newCheck` can be a bare
+ * `check` function (keeps the existing name) or a full `Trait` (to rename too).
+ * Only works on a flat `verify` array - a function-form `verify` (from
+ * `verify: (out) => Trait[]`) has no fixed list to address into, so this
+ * throws rather than guess; use `withVerify` to replace it wholesale instead.
+ */
+export declare function modVerify<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, nameOrIndex: string | number, newCheck: Trait["check"] | Trait): DefinedBlock<In, Out>;
+/**
+ * `modVerify`, but for several named checks in one call - a v2 variant that
+ * differs in five ways from v1 shouldn't need five nested `modVerify(modVerify(
+ * modVerify(...)))` calls to track by eye. `patches` keys are plain strings (a
+ * Trait's `name`, not a `MemKey` instance), so an ordinary object literal is
+ * fine here - unlike `MemPage`, there's no identity-collision reason to need
+ * `[name, check]` pairs. Applies each patch in turn via `modVerify`, so the
+ * same fail-loud-on-unknown-name behavior holds for every entry.
  */
-export declare function connect<A extends Checkpoint<string>, B extends Checkpoint<string>, C extends Checkpoint<string>>(a: Block<A, B>, b: Block<B, C>, layouts?: readonly ConnectLayout[]): Block<A, C>;
+export declare function modVerifyAll<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, patches: Record<string, Trait["check"] | Trait>): DefinedBlock<In, Out>;
+export {};