waygraph 0.16.0 → 0.16.2

package/dist/demo/types.d.ts

@@ -1,13 +1,51 @@
 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 {
-        [key: `__wg${string}`]: any;
+        /** 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;
@@ -15,3 +53,33 @@ export interface WgBox {
     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

@@ -1,7 +1,7 @@
 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.
+ * same shape as the demo stepper's `stepper/demo-log.ts`. Silenced by WAYGRAPH_JSON=1.
  */
 function ts() {
     const d = new Date();

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

@@ -1,33 +1,10 @@
 import type { Page } from "@playwright/test";
 import type { Checkpoint } from "../checkpoint/checkpoint.js";
-import type { StubLifecycleFn } from "../stub/stub.js";
-import type { WaygraphSlidesOrFn } from "../stub/ring.js";
-import { MemPage } from "../mem/mem.js";
 import type { MemKey } from "../mem/mem.js";
+import { MemPage } from "../mem/mem.js";
+import type { StubLifecycleFn } from "../stub/stub.js";
 import type { Trait } from "../trait/trait.js";
-/**
- * The `page` a regular Block's `act()` is typed against via `defineBlock` -
- * structurally identical to Playwright's own `Page` (the same real object is
- * 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 { 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
@@ -78,44 +55,6 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
     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
-     * while that slide is up. Flow fixtures may override via `slides`.
-     * @example slides: [
-     *   { caption: "Checkout is three screens", tag: "YAP" },
-     *   { caption: "Overview confirms totals", selector: ".summary_info" },
-     * ]
-     */
-    slides?: WaygraphSlidesOrFn<Out>;
-}
-/**
- * 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.
@@ -140,7 +79,7 @@ export interface Block<In extends Checkpoint<string>, Out extends Checkpoint<str
      * A human-readable sentence describing what this Block actually tests or
      * does - "the outsider case: a user outside a request's audience is
      * denied its detail page," not a restatement of the code. Purely
-     * additive, optional narration for a human watching a run (step-mode
+     * additive, optional narration for a human watching a run (demo
      * tooling shows it before the Block runs) - never read by
      * `runGraph`/`connect`/anything that decides behavior. A Block with none
      * just shows its `name` instead.
@@ -246,24 +185,29 @@ export type DefinedBlock<In extends Checkpoint<string>, Out extends Checkpoint<s
  * 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;
 /**
- * Attaches routing to `block` without touching its act/observe/resolve/verify -
- * `routes` must cover every tag of `block`'s output (a missing route is a compile
- * error), and the returned Block runs exactly as `block` always did, just followed
- * by whichever next Block the resolved tag routes to. `null` for a tag means that
- * tag is terminal - the run stops there, same as a Block with no routing at all.
- * A route pointing back at `block` itself is a self-loop; see `runGraph`'s
- * `maxSteps` for its safety net. The return type is deliberately `Block<In, any>` -
- * a route can lead anywhere, including back through itself, so there is no fixed
- * Out type to express; state the expected outcomes to `runGraph` via `terminals`
- * instead.
+ * 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 declare function branch<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, routes: {
-    [K in Out["__state"]]: Block<Extract<Out, Checkpoint<K>>, any> | null;
-}): DefinedBlock<In, any>;
+export declare function stripMethods<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>): {
+    name: string;
+    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;
 /**
@@ -297,18 +241,7 @@ export declare function defineBlock<In extends Checkpoint<string>, Out extends C
  * Wrap the one Block you want to change, in place, where a flow uses it:
  * `map().gotoPage(NavLoginBlock).method(withVerify(AddToCartBlock, [...]))`.
  */
-export declare function withVerify<B extends SomeBlock>(block: B, verify: Trait[] | ((out: any) => Trait[])): B;
-/**
- * Answers the browser's own dialog (`confirm`, `alert`, `prompt`, `beforeunload`) that this Block's action
- * triggers. A dialog freezes the page until it is answered, so the answer has to be armed before the click -
- * this does that without folding it into the Block's own `act`. The dialog's text can be kept in mem.
- * @example withDialog(CancelBlock, { accept: true, into: LeaveWarning })
- */
-export declare function withDialog<B extends SomeBlock>(block: B, options?: {
-    accept?: boolean;
-    into?: MemKey<string>;
-    promptText?: string;
-}): B;
+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
@@ -333,3 +266,4 @@ export declare function modVerify<In extends Checkpoint<string>, Out extends Che
  * same fail-loud-on-unknown-name behavior holds for every entry.
  */
 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 {};

package/dist/engine/block/block.js

@@ -1,4 +1,4 @@
-import { WaygraphError, MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_MODVERIFY_FUNCTION_FORM, MSG_MODVERIFY_NOT_FOUND_BY_INDEX, MSG_MODVERIFY_NOT_FOUND_BY_NAME, } from "../errors.js";
+import { MSG_FLOW_BLOCK_NOT_FOUND_BY_INDEX, MSG_FLOW_BLOCK_NOT_FOUND_BY_NAME, MSG_MODVERIFY_FUNCTION_FORM, MSG_MODVERIFY_NOT_FOUND_BY_INDEX, MSG_MODVERIFY_NOT_FOUND_BY_NAME, WaygraphError, } from "../errors.js";
 export function findBlockIndex(middle, block) {
     if (typeof block === "number") {
         if (block < 0 || block >= middle.length) {
@@ -13,45 +13,6 @@ export function findBlockIndex(middle, block) {
     }
     return index;
 }
-/**
- * Attaches routing to `block` without touching its act/observe/resolve/verify -
- * `routes` must cover every tag of `block`'s output (a missing route is a compile
- * error), and the returned Block runs exactly as `block` always did, just followed
- * by whichever next Block the resolved tag routes to. `null` for a tag means that
- * tag is terminal - the run stops there, same as a Block with no routing at all.
- * A route pointing back at `block` itself is a self-loop; see `runGraph`'s
- * `maxSteps` for its safety net. The return type is deliberately `Block<In, any>` -
- * a route can lead anywhere, including back through itself, so there is no fixed
- * Out type to express; state the expected outcomes to `runGraph` via `terminals`
- * instead.
- */
-export function branch(block, routes) {
-    const base = stripMethods(block);
-    let routed;
-    const routesAsData = {};
-    for (const [tag, target] of Object.entries(routes)) {
-        routesAsData[tag] = target === null ? null : target === block ? base.name : target.name;
-    }
-    routed = defineBlock({
-        ...base,
-        next: (checkpoint) => {
-            const target = routes[checkpoint.__state];
-            if (target === undefined || target === null)
-                return undefined;
-            // A route naming `block` itself (the only self-reference in scope when
-            // `routes` was written) means "loop back with routing intact" - substitute
-            // the routed Block, not the original with no `next` of its own.
-            return target === block ? routed : target;
-        },
-        routes: routesAsData,
-    });
-    // Without this, branch()'s output carried no __waygraphKind/__waygraphSalt at all (defineBlock
-    // never stamps them - factories do, after defineBlock returns), so a branched Block could never
-    // pass MapBuilder's assertMapKind/assertMapSalt checks. Real bug: branching was unusable from the
-    // Waygraph Map, only from a raw runGraph() call.
-    copyWaygraphRuntime(block, routed);
-    return routed;
-}
 /**
  * Strips `withVerify`/`modVerify`/`modVerifyAll` off a Block, keeping everything
  * else - `name`, `instruction`, `next`, `requires`. Every function below that
@@ -61,7 +22,7 @@ export function branch(block, routes) {
  * `branch()` added routing to afterward, and without this step the result would
  * silently drop that routing, since the stale closure never knew about it.
  */
-function stripMethods(block) {
+export function stripMethods(block) {
     return {
         name: block.name,
         instruction: block.instruction,
@@ -174,42 +135,6 @@ function withStubPhase(block, phase, stub) {
     copyWaygraphRuntime(block, next);
     return next;
 }
-/**
- * Answers the browser's own dialog (`confirm`, `alert`, `prompt`, `beforeunload`) that this Block's action
- * triggers. A dialog freezes the page until it is answered, so the answer has to be armed before the click -
- * this does that without folding it into the Block's own `act`. The dialog's text can be kept in mem.
- * @example withDialog(CancelBlock, { accept: true, into: LeaveWarning })
- */
-export function withDialog(block, options = {}) {
-    const base = stripMethods(block);
-    const act = base.instruction.act.bind(base.instruction);
-    const next = defineBlock({
-        ...base,
-        instruction: {
-            ...base.instruction,
-            async act(page, input, mem) {
-                const answer = async (dialog) => {
-                    if (options.into)
-                        mem.set(options.into, dialog.message());
-                    if (options.accept === false)
-                        await dialog.dismiss();
-                    else
-                        await dialog.accept(options.promptText);
-                };
-                const raw = page;
-                raw.once("dialog", answer);
-                try {
-                    await act(page, input, mem);
-                }
-                finally {
-                    raw.off("dialog", answer);
-                }
-            },
-        },
-    });
-    copyWaygraphRuntime(block, next);
-    return next;
-}
 /**
  * Replaces one Trait inside `block`'s verify list, leaving every other check
  * untouched - the v1/v2/legacy-variant case, where one check needs a different

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

@@ -0,0 +1,17 @@
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import { Block, DefinedBlock } from "./block.js";
+/**
+ * Attaches routing to `block` without touching its act/observe/resolve/verify -
+ * `routes` must cover every tag of `block`'s output (a missing route is a compile
+ * error), and the returned Block runs exactly as `block` always did, just followed
+ * by whichever next Block the resolved tag routes to. `null` for a tag means that
+ * tag is terminal - the run stops there, same as a Block with no routing at all.
+ * A route pointing back at `block` itself is a self-loop; see `runGraph`'s
+ * `maxSteps` for its safety net. The return type is deliberately `Block<In, any>` -
+ * a route can lead anywhere, including back through itself, so there is no fixed
+ * Out type to express; state the expected outcomes to `runGraph` via `terminals`
+ * instead.
+ */
+export declare function branch<In extends Checkpoint<string>, Out extends Checkpoint<string>>(block: Block<In, Out>, routes: {
+    [K in Out["__state"]]: Block<Extract<Out, Checkpoint<K>>, any> | null;
+}): DefinedBlock<In, any>;

package/dist/engine/block/branch.js

@@ -0,0 +1,40 @@
+import { copyWaygraphRuntime, defineBlock, stripMethods } from "./block.js";
+/**
+ * Attaches routing to `block` without touching its act/observe/resolve/verify -
+ * `routes` must cover every tag of `block`'s output (a missing route is a compile
+ * error), and the returned Block runs exactly as `block` always did, just followed
+ * by whichever next Block the resolved tag routes to. `null` for a tag means that
+ * tag is terminal - the run stops there, same as a Block with no routing at all.
+ * A route pointing back at `block` itself is a self-loop; see `runGraph`'s
+ * `maxSteps` for its safety net. The return type is deliberately `Block<In, any>` -
+ * a route can lead anywhere, including back through itself, so there is no fixed
+ * Out type to express; state the expected outcomes to `runGraph` via `terminals`
+ * instead.
+ */
+export function branch(block, routes) {
+    const base = stripMethods(block);
+    let routed;
+    const routesAsData = {};
+    for (const [tag, target] of Object.entries(routes)) {
+        routesAsData[tag] = target === null ? null : target === block ? base.name : target.name;
+    }
+    routed = defineBlock({
+        ...base,
+        next: (checkpoint) => {
+            const target = routes[checkpoint.__state];
+            if (target === undefined || target === null)
+                return undefined;
+            // A route naming `block` itself (the only self-reference in scope when
+            // `routes` was written) means "loop back with routing intact" - substitute
+            // the routed Block, not the original with no `next` of its own.
+            return target === block ? routed : target;
+        },
+        routes: routesAsData,
+    });
+    // Without this, branch()'s output carried no __waygraphKind/__waygraphSalt at all (defineBlock
+    // never stamps them - factories do, after defineBlock returns), so a branched Block could never
+    // pass MapBuilder's assertMapKind/assertMapSalt checks. Real bug: branching was unusable from the
+    // Waygraph Map, only from a raw runGraph() call.
+    copyWaygraphRuntime(block, routed);
+    return routed;
+}

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

@@ -0,0 +1,13 @@
+import type { MemKey } from "../mem/mem.js";
+import { SomeBlock } from "./block.js";
+/**
+ * Answers the browser's own dialog (`confirm`, `alert`, `prompt`, `beforeunload`) that this Block's action
+ * triggers. A dialog freezes the page until it is answered, so the answer has to be armed before the click -
+ * this does that without folding it into the Block's own `act`. The dialog's text can be kept in mem.
+ * @example withDialog(CancelBlock, { accept: true, into: LeaveWarning })
+ */
+export declare function withDialog<B extends SomeBlock>(block: B, options?: {
+    accept?: boolean;
+    into?: MemKey<string>;
+    promptText?: string;
+}): B;

package/dist/engine/block/dialog.js

@@ -0,0 +1,37 @@
+import { copyWaygraphRuntime, defineBlock, stripMethods } from "./block.js";
+/**
+ * Answers the browser's own dialog (`confirm`, `alert`, `prompt`, `beforeunload`) that this Block's action
+ * triggers. A dialog freezes the page until it is answered, so the answer has to be armed before the click -
+ * this does that without folding it into the Block's own `act`. The dialog's text can be kept in mem.
+ * @example withDialog(CancelBlock, { accept: true, into: LeaveWarning })
+ */
+export function withDialog(block, options = {}) {
+    const base = stripMethods(block);
+    const act = base.instruction.act.bind(base.instruction);
+    const next = defineBlock({
+        ...base,
+        instruction: {
+            ...base.instruction,
+            async act(page, input, mem) {
+                const answer = async (dialog) => {
+                    if (options.into)
+                        mem.set(options.into, dialog.message());
+                    if (options.accept === false)
+                        await dialog.dismiss();
+                    else
+                        await dialog.accept(options.promptText);
+                };
+                const raw = page;
+                raw.once("dialog", answer);
+                try {
+                    await act(page, input, mem);
+                }
+                finally {
+                    raw.off("dialog", answer);
+                }
+            },
+        },
+    });
+    copyWaygraphRuntime(block, next);
+    return next;
+}

package/dist/engine/block/kinds/method.d.ts

@@ -39,8 +39,6 @@ export interface AssertBlockOptions<Out extends Checkpoint<string> = Checkpoint<
     verify: Trait[] | ((out: Out) => Trait[]);
     /** Mem keys this assertion's `verify` reads (e.g. a mem-aware Trait) - checked by preflight before the flow runs. */
     requires?: readonly MemKey<unknown>[];
-    /** Multi-step yap slides (demo only) - same field `Instruction.slides` exposes elsewhere. */
-    slides?: import("../../stub/ring.js").WaygraphSlidesOrFn<Out>;
 }
 /**
  * Sugar for a self-loop-only "pure assertion" Block: no hand-written

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

@@ -42,7 +42,6 @@ export function defineAssertBlock(options) {
                 }
             },
             verify: options.verify,
-            ...(options.slides ? { slides: options.slides } : {}),
         },
     });
     Object.defineProperty(built, "__waygraphKind", {

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

@@ -28,7 +28,7 @@ export function defineNavBlock(options) {
                     await page.goto(url);
                 }
                 else {
-                    // Always Locator.click() so step-mode's demo cursor/pulse patch
+                    // Always Locator.click() so the demo stepper's cursor/pulse patch
                     // (instrumentInteractionHighlighting) sees NavBlock click-nav -
                     // never page.click() / goto teleport.
                     const selector = typeof options.click === "function" ? options.click(mem) : options.click;

package/dist/engine/flow/map-branch.d.ts

@@ -0,0 +1,9 @@
+import type { Checkpoint } from "../checkpoint/checkpoint.js";
+import type { Flow } from "./flow.js";
+/**
+ * Builds the `Flow` object `MapBuilder.branch()` returns: run `before`, then dispatch on the
+ * resolved tag into whichever `routes` entry matches (same page/context/mem), or return that
+ * Checkpoint as-is when its route is `null`. Factored out so `withBlockVerify`/`modBlockVerify`
+ * can patch `before` and rebuild the same branched shape, exactly like a plain Flow's own.
+ */
+export declare function buildBranchedFlow<Out extends Checkpoint<string>>(before: Flow<Out>, routes: Record<string, Flow<Checkpoint<string>> | null>): Flow<Checkpoint<string>>;

package/dist/engine/flow/map-branch.js

@@ -0,0 +1,57 @@
+import { MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED, WaygraphError } from "../errors.js";
+import { MemPage } from "../mem/mem.js";
+/**
+ * Builds the `Flow` object `MapBuilder.branch()` returns: run `before`, then dispatch on the
+ * resolved tag into whichever `routes` entry matches (same page/context/mem), or return that
+ * Checkpoint as-is when its route is `null`. Factored out so `withBlockVerify`/`modBlockVerify`
+ * can patch `before` and rebuild the same branched shape, exactly like a plain Flow's own.
+ */
+export function buildBranchedFlow(before, routes) {
+    const run = (async (contextOrMem, memOrConfig, options) => {
+        if (contextOrMem instanceof MemPage) {
+            throw new WaygraphError("WG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED", MSG_MAP_BRANCH_SHARED_SESSION_UNSUPPORTED);
+        }
+        const context = contextOrMem;
+        const mem = memOrConfig;
+        const gotOwnPage = options?.page === undefined;
+        const page = options?.page ?? (await context.newPage());
+        const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
+        const first = (await before.run(context, mem, { ...options, page, closeOnFinish: false }));
+        const branchFlow = routes[first.result.__state];
+        if (!branchFlow) {
+            if (options?.closeOnFinish === false)
+                return { result: first.result, page: first.page };
+            if (closeOnFinish)
+                await first.page.close();
+            return first.result;
+        }
+        return branchFlow.run(context, mem, { ...options, page: first.page, closeOnFinish });
+    });
+    return {
+        resetSession: before.resetSession,
+        config: before.config,
+        ...(before.expectedFailureReason !== undefined ? { expectedFailureReason: before.expectedFailureReason } : {}),
+        ...(before.demoPace !== undefined ? { demoPace: before.demoPace } : {}),
+        ...(before.highlightStyle !== undefined ? { highlightStyle: before.highlightStyle } : {}),
+        ...(before.memStub !== undefined ? { memStub: before.memStub } : {}),
+        // Read by branchRoutes()/branchInfo() (branch-regression.ts) - real, ORDINARY (enumerable)
+        // properties, not hidden ones, specifically so a `{ ...flow, ... }` spread (withSettings) carries them
+        // through instead of silently dropping them -
+        // the same class of bug branch()'s missing copyWaygraphRuntime call already was.
+        __wgBranch: { before, routes },
+        // Static introspection (`waygraph graph`/list): the fixed prefix, plus every branch's own
+        // Blocks prefixed by the tag that leads to them - can't know at analysis time which one a real
+        // run takes, so this shows all of them rather than none.
+        blocks: () => [
+            ...before.blocks(),
+            ...Object.entries(routes).flatMap(([tag, f]) => f ? f.blocks().map((b) => ({ ...b, name: `${tag} -> ${b.name}` })) : []),
+        ],
+        run,
+        withBlockVerify(block, verify) {
+            return buildBranchedFlow(before.withBlockVerify(block, verify), routes);
+        },
+        modBlockVerify(block, nameOrIndex, newCheck) {
+            return buildBranchedFlow(before.modBlockVerify(block, nameOrIndex, newCheck), routes);
+        },
+    };
+}