waygraph 0.7.16 → 0.10.0

package/dist/engine.d.ts

@@ -561,12 +561,54 @@ export type NavClickBlock<Out extends Checkpoint<string>> = NavBlock<Out>;
 export declare function defineNavClickBlock<Out extends Checkpoint<string>>(options: NavClickBlockOptions<Out>): NavClickBlock<Out>;
 /**
  * TypeScript salt over {@link defineBlock} for one-shot non-nav app steps
- * (submit, finish, logout). Same runtime Block; marks `__waygraphSalt = "action"`
- * so auto/docs can tell Action from bare {@link defineBlock} (tests / unsure).
- * Does not force `instanceOptions` - use {@link defineEffectBlock} for that.
+ * (submit, upload, finish, logout) - **methods** on a page. Same runtime Block;
+ * marks `__waygraphSalt = "method"` so auto/docs can tell Method from bare
+ * {@link defineBlock}. Does not force `instanceOptions` - use
+ * {@link defineEffectBlock} when the auto menu should spawn one row per live
+ * DOM instance. Prefer hanging methods off a {@link definePageBlock} hub.
  */
-export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = DefinedBlock<In, Out>;
-export declare function defineActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0]): ActionBlock<In, Out>;
+export type MethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = DefinedBlock<In, Out>;
+/** @deprecated Prefer {@link MethodBlock} - same type; Action was the 0.7 name. */
+export type ActionBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>> = MethodBlock<In, Out>;
+export declare function defineMethodBlock<In extends Checkpoint<string>, Out extends Checkpoint<string>>(base: Parameters<typeof defineBlock<In, Out>>[0]): MethodBlock<In, Out>;
+/** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
+export declare const defineActionBlock: typeof defineMethodBlock;
+/** One Block (or lazy factory) registered on a {@link PageBlock}. */
+export type PageMethodEntry = DefinedBlock<any, any> | (() => DefinedBlock<any, any>);
+export type PageBlockOptions<Out extends Checkpoint<string>> = {
+    name: string;
+    description?: string;
+    /** Checkpoint tag for this screen (hub). */
+    checkpoint: Out["__state"];
+    verify?: Trait[] | ((out: Out) => Trait[]);
+    highlights?: readonly WaygraphHighlight[] | ((out: Out) => readonly WaygraphHighlight[]);
+    requires?: readonly MemKey<any>[];
+    /**
+     * Methods available on this page. Array, or a record of Blocks / `() => Block`
+     * factories (lazy so the page object can colocate method definitions).
+     */
+    methods?: readonly PageMethodEntry[] | Record<string, PageMethodEntry>;
+    /**
+     * Optional deep-link onto this page (`goto`). XOR with `click`. Omit when the
+     * hub is arrival-only (previous Block already resolved here).
+     */
+    url?: string | ((mem: MemPage) => string);
+    /** Optional click-nav onto this page. XOR with `url`. */
+    click?: string | ((mem: MemPage) => string);
+    instanceOptions?: Block<Checkpoint<string>, Out>["instanceOptions"];
+};
+/**
+ * Page hub Block: one Checkpoint = this screen; methods hang off the hub for
+ * readability / auto grouping. Runtime is still a Block (`__waygraphKind = "page"`).
+ * `act` is goto/click when `url`/`click` is set, otherwise a no-op (already here).
+ * Child methods stay ordinary Blocks for graph edges - the page only registers them.
+ */
+export type PageBlock<Out extends Checkpoint<string>> = NavBlock<Out> & {
+    /** Resolved method Blocks registered at define time. */
+    readonly methods: readonly DefinedBlock<any, any>[];
+};
+/** @see {@link PageBlockOptions} */
+export declare function definePageBlock<Out extends Checkpoint<string>>(options: PageBlockOptions<Out>): PageBlock<Out>;
 /**
  * TypeScript salt over {@link defineBlock}: same runtime Block, but the type
  * forces `requires` + `instanceOptions` so `waygraph auto` can list one menu
@@ -610,14 +652,14 @@ export declare function defineMemNavBlock<Out extends Checkpoint<string>>(option
     instanceOptions: NonNullable<Block<Checkpoint<string>, Out>["instanceOptions"]>;
 }): MemNavBlock<Out>;
 /**
- * "Where am I" - reverse-matches a live `page` against every NavBlock in
- * `library`, in order, returning the first one whose own `verify` Traits all
- * pass (its `checkpoint`), or `null` if none match. Deliberately NavBlocks
- * only: a NavBlock has exactly one fixed `checkpoint` and a `verify` list
- * whose whole job is already "confirm arrival here," so it's a reliable
+ * "Where am I" - reverse-matches a live `page` against every NavBlock /
+ * PageBlock in `library`, in order, returning the first one whose own `verify`
+ * Traits all pass (its `checkpoint`), or `null` if none match. Deliberately
+ * Nav/Page hubs only: each has exactly one fixed `checkpoint` and a `verify`
+ * list whose whole job is already "confirm arrival here," so it's a reliable
  * fingerprint - a regular `defineBlock` can branch to different `Out` tags
  * depending on runtime evidence, so its `verify` alone doesn't identify a
- * single state the way a NavBlock's does.
+ * single state the way a hub's does.
  *
  * The primitive `waygraph auto`'s discovered graph is *for* - the graph says
  * what pages exist and how to reach them; `locate()` is how an autonomous

package/dist/engine.js

@@ -696,15 +696,88 @@ export function defineNavClickBlock(options) {
         ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
     });
 }
-export function defineActionBlock(base) {
+export function defineMethodBlock(base) {
     const built = defineBlock(base);
     Object.defineProperty(built, "__waygraphSalt", {
-        value: "action",
+        value: "method",
         enumerable: false,
         configurable: false,
     });
     return built;
 }
+/** @deprecated Prefer {@link defineMethodBlock} - identical helper (0.7 name). */
+export const defineActionBlock = defineMethodBlock;
+function resolvePageMethods(methods) {
+    if (!methods)
+        return [];
+    const entries = Array.isArray(methods) ? methods : Object.values(methods);
+    return entries.map((entry) => (typeof entry === "function" ? entry() : entry));
+}
+/** @see {@link PageBlockOptions} */
+export function definePageBlock(options) {
+    if (options.url !== undefined && options.click !== undefined) {
+        throw new Error(`definePageBlock("${options.name}"): pass url XOR click (or neither for arrival-only hub)`);
+    }
+    const methodList = resolvePageMethods(options.methods);
+    const built = defineBlock({
+        name: options.name,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.requires ? { requires: options.requires } : {}),
+        ...(options.instanceOptions ? { instanceOptions: options.instanceOptions } : {}),
+        instruction: {
+            async act(page, _input, mem) {
+                if (options.url !== undefined) {
+                    const url = typeof options.url === "function" ? options.url(mem) : options.url;
+                    await page.goto(url);
+                }
+                else if (options.click !== undefined) {
+                    const selector = typeof options.click === "function" ? options.click(mem) : options.click;
+                    await page.locator(selector).click();
+                }
+                // else: arrival-only hub — previous Block already landed here
+            },
+            resolve: () => checkpoint(options.checkpoint),
+            ...(options.verify ? { verify: options.verify } : {}),
+            ...(options.highlights ? { highlights: options.highlights } : {}),
+        },
+    });
+    Object.defineProperty(built, "__waygraphKind", {
+        value: "page",
+        enumerable: false,
+        configurable: false,
+    });
+    Object.defineProperty(built, "__waygraphSalt", {
+        value: "page",
+        enumerable: false,
+        configurable: false,
+    });
+    Object.defineProperty(built, "methods", {
+        value: Object.freeze([...methodList]),
+        enumerable: true,
+        configurable: false,
+        writable: false,
+    });
+    Object.defineProperty(built, "__waygraphMethods", {
+        value: methodList.map((m) => m.name),
+        enumerable: false,
+        configurable: false,
+    });
+    if (options.url !== undefined || options.click !== undefined) {
+        Object.defineProperty(built, "__waygraphPageDeepLink", {
+            value: true,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    if (options.click !== undefined) {
+        Object.defineProperty(built, "__waygraphNavClick", {
+            value: options.click,
+            enumerable: false,
+            configurable: false,
+        });
+    }
+    return built;
+}
 /**
  * {@link defineBlock} constrained for effect-style instance menus: `requires` +
  * `instanceOptions` are mandatory. Prefer this when the Block adds / removes /
@@ -743,14 +816,14 @@ export function defineMemNavBlock(options) {
     return built;
 }
 /**
- * "Where am I" - reverse-matches a live `page` against every NavBlock in
- * `library`, in order, returning the first one whose own `verify` Traits all
- * pass (its `checkpoint`), or `null` if none match. Deliberately NavBlocks
- * only: a NavBlock has exactly one fixed `checkpoint` and a `verify` list
- * whose whole job is already "confirm arrival here," so it's a reliable
+ * "Where am I" - reverse-matches a live `page` against every NavBlock /
+ * PageBlock in `library`, in order, returning the first one whose own `verify`
+ * Traits all pass (its `checkpoint`), or `null` if none match. Deliberately
+ * Nav/Page hubs only: each has exactly one fixed `checkpoint` and a `verify`
+ * list whose whole job is already "confirm arrival here," so it's a reliable
  * fingerprint - a regular `defineBlock` can branch to different `Out` tags
  * depending on runtime evidence, so its `verify` alone doesn't identify a
- * single state the way a NavBlock's does.
+ * single state the way a hub's does.
  *
  * The primitive `waygraph auto`'s discovered graph is *for* - the graph says
  * what pages exist and how to reach them; `locate()` is how an autonomous

package/dist/graph.d.ts

@@ -48,7 +48,8 @@ export declare function toMermaid(graph: WaygraphGraph): string;
 /**
  * Blocks present on disk but never wired into a `.flow.ts` defineFlow array.
  * Required before `chain auto` can build a path from the discovered graph -
- * orphan Blocks are intentionally excluded from auto shorthand.
+ * orphan Blocks are intentionally excluded from auto shorthand. Arrival-only
+ * Page hubs and Blocks listed on a Page's `methods` are not orphans.
  */
 export declare function findOrphanBlocks(projectDir: string): Promise<OrphanBlock[]>;
 /**

package/dist/graph.js

@@ -77,7 +77,8 @@ function exportNameToBlockName(exportName) {
 /**
  * Blocks present on disk but never wired into a `.flow.ts` defineFlow array.
  * Required before `chain auto` can build a path from the discovered graph -
- * orphan Blocks are intentionally excluded from auto shorthand.
+ * orphan Blocks are intentionally excluded from auto shorthand. Arrival-only
+ * Page hubs and Blocks listed on a Page's `methods` are not orphans.
  */
 export async function findOrphanBlocks(projectDir) {
     const blockFiles = discoverBlocks(projectDir);
@@ -88,6 +89,27 @@ export async function findOrphanBlocks(projectDir) {
             referenced.add(ref);
         }
     }
+    const pageMethodNames = new Set();
+    for (const file of blockFiles) {
+        let mod;
+        try {
+            mod = await importModule(file);
+        }
+        catch {
+            continue;
+        }
+        for (const exported of Object.values(mod)) {
+            if (!exported || typeof exported !== "object")
+                continue;
+            if (exported.__waygraphKind !== "page")
+                continue;
+            const names = exported.__waygraphMethods;
+            if (Array.isArray(names)) {
+                for (const n of names)
+                    pageMethodNames.add(n);
+            }
+        }
+    }
     const orphans = [];
     for (const file of blockFiles) {
         const relFile = relative(projectDir, file);
@@ -98,7 +120,11 @@ export async function findOrphanBlocks(projectDir) {
             const exportName = m[1];
             if (referenced.has(exportName))
                 continue;
-            if (!/defineBlock|defineActionBlock|defineEffectBlock|defineMemEffectBlock|defineNavBlock|defineNavClickBlock|defineMemNavBlock/.test(src))
+            if (!/defineBlock|defineMethodBlock|defineActionBlock|definePageBlock|defineEffectBlock|defineMemEffectBlock|defineNavBlock|defineNavClickBlock|defineMemNavBlock/.test(src))
+                continue;
+            // Arrival-only Page hubs are never orphans (even if import fails without tsx).
+            const assignSlice = src.slice(m.index, m.index + exportName.length + 80);
+            if (/=\s*definePageBlock\b/.test(assignSlice))
                 continue;
             let block = exportNameToBlockName(exportName);
             try {
@@ -106,6 +132,13 @@ export async function findOrphanBlocks(projectDir) {
                 const exported = mod[exportName];
                 if (isBlockLike(exported))
                     block = exported.name;
+                if (exported &&
+                    typeof exported === "object" &&
+                    exported.__waygraphKind === "page") {
+                    continue;
+                }
+                if (pageMethodNames.has(block))
+                    continue;
             }
             catch {
                 // import may fail in partial projects - keep derived name
@@ -155,7 +188,8 @@ function isBlockLike(val) {
 }
 /** Set by `defineNavBlock` (non-enumerable) - see src/engine.ts. */
 function isNavBlockMarked(val) {
-    return val.__waygraphKind === "nav";
+    const kind = val.__waygraphKind;
+    return kind === "nav" || kind === "page";
 }
 /**
  * Resolves `typeName` to every literal Checkpoint tag it can mean, within
@@ -242,9 +276,9 @@ function extractDefineBlockGenerics(src) {
     // alternation so both shapes come out of the same two capture groups.
     // Effect helpers are TypeScript salt over defineBlock - same In/Out edges.
     const arg = String.raw `(Checkpoint<[^>]*>|[A-Za-z_$][\w]*)`;
-    const re = new RegExp(String.raw `define(?:(?:Mem)?Effect|Action)?Block<\s*${arg}\s*,\s*${arg}\s*>`, "g");
-    // Matches: defineBlock | defineActionBlock | defineEffectBlock | defineMemEffectBlock
-    // (Nav / NavClick use runtime markers, not this regex.)
+    const re = new RegExp(String.raw `define(?:(?:Mem)?Effect|Method|Action)?Block<\s*${arg}\s*,\s*${arg}\s*>`, "g");
+    // Matches: defineBlock | defineMethodBlock | defineActionBlock | defineEffectBlock |
+    // defineMemEffectBlock (Nav / NavClick / Page use runtime markers, not this regex.)
     const calls = [];
     let m;
     while ((m = re.exec(src)) !== null) {
@@ -289,16 +323,22 @@ export async function discoverGraph(projectDir) {
             const blockName = exported.name;
             if (isNavBlockMarked(exported)) {
                 try {
-                    // NavBlock's own resolve() ignores whatever it's called with -
-                    // always exactly `checkpoint(options.checkpoint)`.
+                    // NavBlock / PageBlock resolve() ignores input - always checkpoint(tag).
                     const resolveFn = exported.instruction.resolve;
                     const resolved = await resolveFn(undefined);
                     const to = resolved.__state;
                     nodeTags.add(to);
-                    edges.push({ block: blockName, file: relFile, from: "*", to, kind: "nav" });
+                    // Arrival-only Page hubs register the Checkpoint node but do not emit
+                    // a Start-here edge (no deep link). Methods own the action edges.
+                    const isPage = exported.__waygraphKind === "page";
+                    const deepLink = !isPage ||
+                        exported.__waygraphPageDeepLink === true;
+                    if (deepLink) {
+                        edges.push({ block: blockName, file: relFile, from: "*", to, kind: "nav" });
+                    }
                 }
                 catch {
-                    skipped.push({ block: blockName, file: relFile, reason: "NavBlock's own resolve() threw" });
+                    skipped.push({ block: blockName, file: relFile, reason: "NavBlock/PageBlock resolve() threw" });
                 }
                 continue;
             }
@@ -307,7 +347,7 @@ export async function discoverGraph(projectDir) {
                 skipped.push({
                     block: blockName,
                     file: relFile,
-                    reason: "no defineBlock/defineEffectBlock<In, Out> generic call found",
+                    reason: "no defineBlock/defineMethodBlock/defineEffectBlock<In, Out> generic call found",
                 });
                 continue;
             }

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInsta
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineActionBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
-export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, ActionBlock, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
+export type { Flow, EngineConfig, ComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible } from "./trait.js";
-export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineActionBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
+export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, preflight, withSessionReset, withTitle, withExpectedFailure, chainFlow, } from "./engine.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

package/examples/saucedemo/README.md

@@ -32,11 +32,25 @@ npx playwright install chromium
 | Want | Command |
 |------|---------|
 | Headless suite | `npm test` |
-| Interactive explore | `npm run auto` |
-| Stepper (manual Next) | `npm run demo:step` |
-| Stepper (Auto-advance) | `npm run demo:autoplay` |
+| Interactive explore (headed panel) | `npm run auto` |
+| Interactive explore (terminal menu) | `npm run auto:cli` |
+| Shop demo stepper | `npm run demo:step` |
+| Shop demo autoplay | `npm run demo:autoplay` |
+| **Cart bulk** demo (add-all → remove-all) | `npm run demo:bulk` |
+| Cart bulk stepper | `npm run demo:bulk:step` |
 | List flows | `npm run flows` |
 
+**Demo vs auto vs run for cart bulk**
+
+| | CLI | Needs `.flow.ts`? |
+|--|-----|-------------------|
+| **`run --blocks`** | `npm run run:bulk` — Block names + `--data` | No |
+| **`demo --blocks`** | `npm run demo:bulk` — named flow + `--data` | Optional (`cartBulkFlow`) |
+| **`auto`** | `npm run auto` / `auto:cli` | No — live menu |
+| **`auto --blocks From To`** | path-find on graph | No — checkpoints only |
+
+QA watch+record: `npm run demo:bulk:video` (`--auto-play-video`).
+
 ## Layout (short)
 
 ```text
@@ -45,10 +59,10 @@ src/blocks/
   saucedemo-web/                 # URL /
     NAV.md
     nav-login.block.ts
-    actions/                     # submit-login, logout, …
+    methods/                     # submit-login, logout, …
     inventory/                   # URL /inventory.html
       nav-item-detail.block.ts   # MemNav
-      actions/*.effect.block.ts  # Add / Remove
+      methods/*.effect.block.ts  # Add / Remove
     cart/                        # URL /cart.html
     checkout-step-one/
     checkout-step-two/

package/examples/saucedemo/docs/CONVENTION.md

@@ -1,11 +1,10 @@
 # saucedemo waygraph conventions
 
-Atomic Blocks - one nav / effect / action per real URL or on-page mutation so
+Atomic Blocks - one nav / effect / method per real URL or on-page mutation so
 `waygraph auto` can discover a real state graph (not a fat multi-page Block).
 
-**TypeScript salt only.** `defineNavBlock`, `defineEffectBlock`, and plain
-`defineBlock` are helpers that force a useful shape. At runtime everything is
-still a `Block` - there is no separate Effect or Nav engine.
+**TypeScript salt only.** Helpers force a useful shape. At runtime everything is
+still a `Block` - there is no separate Page / Effect / Nav engine.
 
 **Multi-route consumers:** folder layout must mirror Next.js `app/` page routes -
 see package docs `docs/consumer.html` (no invented `root/`, `landing/`, or
@@ -15,14 +14,18 @@ see package docs `docs/consumer.html` (no invented `root/`, `landing/`, or
 
 | Kind | File | Helper | `page.goto`? |
 |------|------|--------|--------------|
+| Page | `*.page.block.ts` | `definePageBlock` | Optional deep-link; usually arrival-only hub |
 | Nav | `nav-*.block.ts` | `defineNavBlock` / `defineMemNavBlock` | Yes (`url` XOR `click`) |
-| Effect | `*.effect.block.ts` | `defineEffectBlock` | No - mutates a live instance (add/remove/toggle) via mem + `instanceOptions` |
-| Action | `*.action.block.ts` | `defineBlock` | No - forms, submit, logout, etc. |
+| Effect | `*.effect.block.ts` in `methods/` | `defineEffectBlock` | No - mutates a live instance via mem + `instanceOptions` |
+| Method | `*.method.block.ts` in `methods/` | `defineMethodBlock` | No - forms, submit, logout, predefined queues |
 
-Only an explicit `page.goto()` (or NavBlock `click`) counts as navigation - an
-action/effect that fills a form or clicks a button stays non-nav even when the
+Only an explicit `page.goto()` (or NavBlock `click`) counts as navigation - a
+method/effect that fills a form or clicks a button stays non-nav even when the
 app changes URL as a side effect of `#continue`.
 
+**Selectors:** put DOM strings in `*Sel` next to the page (static + `(id) => …`).
+Mem keys store values, not selectors.
+
 ## Layout
 
 ```text
@@ -31,15 +34,16 @@ src/blocks/
   saucedemo-web/                 # THIS FOLDER IS URL "/"
     NAV.md
     nav-login.block.ts
-    actions/
-      submit-login.action.block.ts
+    methods/
+      submit-login.method.block.ts
       submit-login-for-flow.ts
-      submit-logout.action.block.ts
+      submit-logout.method.block.ts
     inventory/                   # /inventory.html
       NAV.md
+      inventory.page.block.ts     # Page hub + methods registry
       nav-item-detail.block.ts
-      actions/
-        inventory-items.ts
+      methods/
+        inventory-items.ts       # InventorySel + collectors
         add-to-cart.effect.block.ts
         remove-from-cart.effect.block.ts
     inventory-item/              # /inventory-item.html
@@ -53,18 +57,18 @@ src/blocks/
       nav-checkout-info.block.ts
     checkout-step-one/           # /checkout-step-one.html
       NAV.md
-      actions/
-        submit-checkout-info.action.block.ts
+      methods/
+        submit-checkout-info.method.block.ts
     checkout-step-two/           # /checkout-step-two.html
       NAV.md
-      actions/
-        finish-order.action.block.ts
+      methods/
+        finish-order.method.block.ts
 src/states/
 src/flows/
 ```
 
 `waygraph check` should report zero warnings - every navigation goes through
-a `defineNavBlock`, nothing else calls `page.goto`.
+a `defineNavBlock` / Page deep-link, nothing else calls `page.goto`.
 
 `waygraph auto` should discover Checkpoints as nodes and these Blocks as
 edges (including cycles via logout / continue-shopping / back-to-products).

package/examples/saucedemo/docs/HELPERS.md

@@ -4,23 +4,76 @@ Runtime is always a `Block`. Helpers are TypeScript salt + clear intent.
 
 | Helper | Use when | File |
 |--------|----------|------|
+| `definePageBlock` | Screen hub (checkpoint + methods + optional Sel) | `*.page.block.ts` |
 | `defineNavBlock` | URL / `goto` only | `nav-*.block.ts` |
 | `defineNavClickBlock` | Click-to-navigate only | `nav-*.block.ts` |
 | `defineMemNavBlock` | Nav + per-row `instanceOptions` | `nav-*.block.ts` |
-| `defineActionBlock` | One-shot non-nav app step | `*.action.block.ts` |
-| `defineEffectBlock` | Instance mutate + auto menu rows | `*.effect.block.ts` |
+| `defineMethodBlock` | One-shot non-nav app step | `*.method.block.ts` under `methods/` |
+| `defineEffectBlock` | Instance mutate + auto menu rows | `*.effect.block.ts` under `methods/` |
 | `defineBlock` | Escape hatch: tests, unsure, probes | any |
+| `defineActionBlock` | **Deprecated** alias of `defineMethodBlock` | — |
 
 `defineNavBlock({ click })` still works (compat) - prefer `defineNavClickBlock` in app code.
 
-## Branching (not Mem)
+---
 
-Mem / `instanceOptions` = pick *which instance* before run.
+## Page hub + methods + Sel
 
-Conditional outcomes = `observe` + union `Out` (already supported, not a new Block kind):
+One **PageBlock** = this screen. Methods hang off it. DOM strings live in `*Sel` (not in mem).
 
 ```ts
-defineActionBlock<LoginPage, LoggedIn | LoginPage>({
+export const InventorySel = {
+  list: ".inventory_list",
+  addBtn: (id: string) => `[data-test="add-to-cart-${id}"]`,
+  // …
+};
+
+export const InventoryPageBlock = definePageBlock({
+  name: "page-inventory",
+  checkpoint: "LoggedIn",
+  verify: [Trait.url({ pathname: "/inventory.html" }), Trait.visible(InventorySel.list)],
+  methods: {
+    addToCart: () => AddToCartBlock,
+    removeFromCart: () => RemoveFromCartBlock,
+    addAllToCart: () => AddAllToCartBlock,
+    removeAllFromCart: () => RemoveAllFromCartBlock,
+    openDetail: () => NavItemDetailBlock,
+  },
+});
+```
+
+| Piece | Stores |
+|-------|--------|
+| `*Sel` | DOM selectors only (static + `(id) => …`) |
+| Mem keys | Typed values (which item / queue) — not selectors |
+| `instanceOptions` | Live DOM → menu rows → `mem.set` on pick |
+| Predefined method | No `instanceOptions`; flow seeds mem first |
+
+Live: `inventory/inventory.page.block.ts`, `inventory/methods/`.
+
+**Round-trip (not forward-only):** cart Methods/Effects use `In = Checkpoint<string>`
+so the graph edge is `from: "*"`. Auto lists them whenever the live page has matching
+buttons (Add vs Remove), including after continue-shopping / back to inventory. Bulk
+`add-all-to-cart` / `remove-all-from-cart` are one menu row each (no `instanceOptions`);
+Out is `ItemInCart` vs `LoggedIn` from cart emptiness.
+
+---
+
+## Checkpoint vs `branch()`
+
+| | **Checkpoint** | **`branch()`** |
+|--|----------------|----------------|
+| Answers | *Where* are you? (`LoggedIn`, `LoginPage`) | *Which Block runs next?* |
+| How | `observe` + `resolve` -> union `Out` | `branch(block, { Tag: nextBlock \| null })` |
+| Alone can | Label state; graph edges; verify | Route a `runGraph` walk |
+| Alone cannot | Pick the next Block | Decide the state |
+
+Checkpoint = place on the map. `branch()` = which road to take from that place.
+
+Conditional Out (no `branch()` needed for auto/graph):
+
+```ts
+defineMethodBlock<LoginPage, LoggedIn | LoginPage>({
   name: "submit-login",
   instruction: {
     async act(page, _in, mem) { /* fill + click */ },
@@ -37,6 +90,97 @@ defineActionBlock<LoginPage, LoggedIn | LoginPage>({
 });
 ```
 
-Graph expands the union Out into two edges. Optional flow routing: `branch(block, { LoggedIn: next, LoginPage: null })`.
+Optional routing for `runGraph`:
+
+```ts
+branch(SubmitLoginActionBlock, {
+  LoggedIn: AddToCartBlock,
+  LoginPage: null, // stop
+});
+```
+
+Linear `defineFlow([start, …, end])` usually skips `branch()` (one happy path).
+
+---
+
+## Mem / `instanceOptions` (spawns menu rows)
+
+Not a separate runtime type. One Block + `requires` + `instanceOptions(page)` ->
+`waygraph auto` lists **one row per live DOM match**. On pick: `mem.set(key, value)`
+then run the Block (act reads mem as usual).
+
+### Effect - spawn Method-like rows (Add / Remove)
+
+```ts
+defineEffectBlock<Checkpoint<string>, ItemInCart>({
+  name: "add-to-cart",
+  requires: [SelectedItem.key],
+  instruction: {
+    async act(page, _in, mem) {
+      const { id } = mem.get(SelectedItem.key);
+      await page.locator(InventorySel.addBtn(id)).click();
+    },
+    resolve: () => checkpoint("ItemInCart"),
+  },
+  async instanceOptions(page) {
+    const items = await collectAddableItems(page);
+    return items.map((item) => ({
+      id: item.id,
+      label: `Add "${item.name}" to cart`,
+      key: SelectedItem.key,
+      value: item,
+      highlight: InventorySel.addBtn(item.id),
+    }));
+  },
+});
+```
+
+Auto shows: `Add "Sauce Labs Backpack" to cart`, `Add "Bike Light"…`, …
+
+### MemNav - spawn Nav rows (Open details)
+
+```ts
+defineMemNavBlock<ItemDetailPage>({
+  name: "nav-item-detail",
+  checkpoint: "ItemDetailPage",
+  requires: [SelectedItem.key],
+  click: (mem) => InventorySel.title(mem.get(SelectedItem.key).id),
+  verify: [Trait.url({ pathname: "/inventory-item.html" })],
+  async instanceOptions(page) {
+    const items = await collectInventoryItems(page);
+    return items.map((item) => ({
+      id: item.id,
+      label: `Open "${item.name}" details`,
+      key: SelectedItem.key,
+      value: item,
+      highlight: InventorySel.title(item.id),
+    }));
+  },
+});
+```
+
+Auto shows: `Open "Backpack" details`, … - still a NavBlock (click nav), salt only.
+
+| | Effect | MemNav |
+|--|--------|--------|
+| Helper | `defineEffectBlock` | `defineMemNavBlock` |
+| Spawns | mutate rows | navigate rows |
+| `act` / nav | click Add/Remove | `click: (mem) => …` title link |
+| Mem | same pattern: `requires` + row `key`/`value` | same |
+
+Live source: `inventory/methods/add-to-cart.effect.block.ts`,
+`inventory/nav-item-detail.block.ts`.
+
+---
+
+## Cart bulk: demo / run / auto
+
+| | Command |
+|--|---------|
+| **Run (Block names)** | `npm run run:bulk` — `run --blocks "loginFlow then add-all…" --data '{…}'` |
+| **Demo (named flow)** | `npm run demo:bulk` — `--blocks cartBulkFlow --data '{…}'` |
+| **Demo QA video** | `npm run demo:bulk:video` — `--auto-play-video` |
+| **Auto headed / CLI** | `npm run auto` / `auto:cli` |
+| **Auto path-find** | `waygraph auto --blocks LoginPage OrderComplete` |
+
 
-No breaking change for atomics - document observe/resolve (+ optional `branch`) as the Branch pattern.