waygraph 0.16.0 → 0.16.1

package/dist/demo/stepper/teardown.js

@@ -30,10 +30,9 @@ import { ignorePageGone } from "../../engine/page-gone.js";
  * ("subtree intercepts pointer events"). Empty/partial fills + a lucky
  * edge click on Login then produced Sauce Demo's Epic sadface, verify
  * still passed on the error banner, and the next block blew up. Collapse
- * also matches the user's "step is running / can't interrupt" ask. (_opts kept
- * for call-site compat; autoCollapsePanel is now unconditional.)
+ * also matches the user's "step is running / can't interrupt" ask.
  */
-export async function markStepRunning(page, _opts) {
+export async function markStepRunning(page) {
     await page
         .evaluate(() => {
         const runBtn = __wgById("wg-run");
@@ -82,13 +81,13 @@ export async function markStepRunning(page, _opts) {
 export async function restoreTheaterAfterNavigation(page, todoDockRef, deviceRef, stubBeforeRef) {
     const needs = (await page
         .evaluate(() => !window.__wgSyncTodos || !__wgById("wg-ring"))
-        .catch(() => true)) || false;
+        .catch(ignorePageGone)) ?? true;
     if (!needs) {
         // Overlay survived (SPA / no full document wipe) - still refresh dock
         // if Node has a carry and the DOM lost .wg-todo-dock.
         const hasDock = await page
             .evaluate(() => !!__wgQ(".wg-todo-dock, #wg-todo-dock"))
-            .catch(() => false);
+            .catch(ignorePageGone);
         if (hasDock || !todoDockRef || !todoDockRef.current)
             return;
     }

package/dist/demo/stepper/todo-advance.d.ts

@@ -1,6 +1,7 @@
-import type { WgPage } from "../types.js";
+import type { StepperRefs, WgPage } from "../types.js";
+import type { ResolvedHighlight } from "../../engine/stub/ring.js";
 /** Advance sequential todo dock to stubIndex and push to the page (Method act). */
-export declare function syncTodoDockAdvance(page: WgPage, todoDockRef: any, stubIndex: number, stub: any): Promise<void>;
+export declare function syncTodoDockAdvance(page: WgPage, todoDockRef: StepperRefs["todoDock"] | undefined, stubIndex: number, stub: ResolvedHighlight | null | undefined): Promise<void>;
 export declare function probeTodoDocksOnPage(page: WgPage): Promise<never[] | {
     key: string;
     pos: string;

package/dist/demo/stepper/todo-advance.js

@@ -22,7 +22,7 @@ function resolveTodoAdvanceIndex(dock, stub, stubIndex) {
         return stubIndex;
     const curIdx = items.findIndex((t) => t.current);
     let idx = stubIndex;
-    const key = stub && (stub.todo || stub.slotId || stub.id);
+    const key = stub && (stub.todo || stub.slotId);
     if (key) {
         const k = String(key).trim().toLowerCase();
         let found = items.findIndex((t) => t.id && String(t.id).toLowerCase() === k);
@@ -90,7 +90,7 @@ export async function probeTodoDocksOnPage(page) {
             let current = "";
             items.forEach((li) => {
                 if (li.classList.contains("wg-todo-current")) {
-                    current = (li.textContent || "").replace(/s+/g, " ").trim().slice(0, 48);
+                    current = (li.textContent || "").replace(/\s+/g, " ").trim().slice(0, 48);
                 }
             });
             return {

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

@@ -1,14 +1,14 @@
 import type { MemPage } from "../../engine/mem/mem.js";
-import type { Block } from "../../engine/block/block.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 { WgPage } from "../types.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: Block<any, any> & {
+    block: SomeBlock & {
         description?: string;
         fastForward?: boolean;
         demoPace?: DemoPace;
@@ -30,17 +30,7 @@ export interface StepperContext {
     stage: ReturnType<typeof createOverlayStage>;
     gate: Gate;
     pacing: Pacing;
-    refs: {
-        stubBefore: {
-            current: any[];
-        };
-        todoDock: {
-            current: any;
-        };
-        device: {
-            current: any;
-        };
-    };
+    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. */

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/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,11 @@
 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 { WaygraphSlidesOrFn } from "../stub/ring.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
@@ -89,34 +67,6 @@ export interface Instruction<In extends Checkpoint<string>, Out extends Checkpoi
      */
     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.
  * `next` is optional routing attached by `branch()` - unset on a plain or
@@ -246,24 +196,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 +252,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 +277,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/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>>;