waygraph 0.7.16 → 0.10.1

package/examples/saucedemo/src/blocks/saucedemo-web/inventory/methods/remove-all-from-cart.method.block.ts

@@ -0,0 +1,55 @@
+import { defineMethodBlock, checkpoint, type Checkpoint } from "waygraph";
+import type { RemoveFromCartOutcome } from "../../../../states/checkout.states.js";
+import { collectRemovableItems, InventorySel } from "./inventory-items.js";
+
+type BulkObserve = "still-has-items" | "cart-empty";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/inventory/methods/  (= /inventory.html)
+ *
+ * Bulk: click every live "Remove" once. No instanceOptions - one auto menu
+ * row. In is Checkpoint<string> (from: "*") so round-trips work the same as
+ * single-item remove. Out: LoggedIn when cart empty; ItemInCart if anything
+ * remains (partial failure / race).
+ */
+export const RemoveAllFromCartBlock = defineMethodBlock<
+  Checkpoint<string>,
+  RemoveFromCartOutcome
+>({
+  name: "remove-all-from-cart",
+  description: "Removes every product still showing Remove on this page.",
+  instruction: {
+    async act(page) {
+      const items = await collectRemovableItems(page);
+      for (const item of items) {
+        await page.locator(InventorySel.removeBtn(item.id)).click();
+      }
+    },
+    async observe(page): Promise<BulkObserve> {
+      const left = await collectRemovableItems(page);
+      return left.length > 0 ? "still-has-items" : "cart-empty";
+    },
+    resolve: (observed) =>
+      checkpoint(observed === "still-has-items" ? "ItemInCart" : "LoggedIn"),
+    verify: (out) =>
+      out.__state === "ItemInCart"
+        ? [
+            {
+              name: "cart-still-has-items",
+              async check(page) {
+                return (await collectRemovableItems(page)).length > 0;
+              },
+            },
+          ]
+        : [
+            {
+              name: "cart-empty",
+              async check(page) {
+                return (await page.locator(InventorySel.cartBadge).count()) === 0;
+              },
+            },
+          ],
+  },
+});

package/{templates/quickstart/src/blocks/saucedemo-web/inventory/actions → examples/saucedemo/src/blocks/saucedemo-web/inventory/methods}/remove-from-cart.effect.block.ts

@@ -1,14 +1,14 @@
 import { defineEffectBlock, checkpoint, type Checkpoint, type WaygraphInstanceOption } from "waygraph";
 import type { RemoveFromCartOutcome } from "../../../../states/checkout.states.js";
 import { SelectedItem } from "../../../../states/checkout.mem-keys.js";
-import { collectRemovableItems } from "./inventory-items.js";
+import { collectRemovableItems, InventorySel } from "./inventory-items.js";
 
 type RemoveObserve = "still-has-items" | "cart-empty";
 
 /**
  * Kind: Effect
  * Helper: defineEffectBlock
- * Route: saucedemo-web/inventory/actions/  (= /inventory.html)
+ * Route: saucedemo-web/inventory/methods/  (= /inventory.html)
  *
  * Removes the mem-picked product. After Add, waygraph auto shows matching
  * "Remove ..." rows from live Remove buttons.
@@ -20,7 +20,7 @@ export const RemoveFromCartBlock = defineEffectBlock<Checkpoint<string>, RemoveF
   instruction: {
     async act(page, _input, mem) {
       const { id } = mem.get(SelectedItem.key);
-      await page.locator(`[data-test="remove-${id}"]`).click();
+      await page.locator(InventorySel.removeBtn(id)).click();
     },
     async observe(page): Promise<RemoveObserve> {
       const left = await collectRemovableItems(page);
@@ -42,7 +42,7 @@ export const RemoveFromCartBlock = defineEffectBlock<Checkpoint<string>, RemoveF
             {
               name: "cart-empty",
               async check(page) {
-                return (await page.locator(".shopping_cart_badge").count()) === 0;
+                return (await page.locator(InventorySel.cartBadge).count()) === 0;
               },
             },
           ],
@@ -54,7 +54,7 @@ export const RemoveFromCartBlock = defineEffectBlock<Checkpoint<string>, RemoveF
       label: `Remove "${item.name}" from cart`,
       key: SelectedItem.key,
       value: item,
-      highlight: `[data-test="remove-${item.id}"]`,
+      highlight: InventorySel.removeBtn(item.id),
     }));
   },
 });

package/examples/saucedemo/src/blocks/saucedemo-web/inventory/nav-item-detail.block.ts

@@ -3,8 +3,8 @@ import type { ItemDetailPage } from "../../../states/checkout.states.js";
 import { SelectedItem } from "../../../states/checkout.mem-keys.js";
 import {
   collectInventoryItems,
-  inventoryItemTitleSelector,
-} from "./actions/inventory-items.js";
+  InventorySel,
+} from "./methods/inventory-items.js";
 
 /**
  * Kind: Nav
@@ -19,7 +19,7 @@ export const NavItemDetailBlock = defineMemNavBlock<ItemDetailPage>({
   description: "Opens the product named by mem (saucedemo.selectedItem) on its detail page.",
   checkpoint: "ItemDetailPage",
   requires: [SelectedItem.key],
-  click: (mem) => inventoryItemTitleSelector(mem.get(SelectedItem.key).id),
+  click: (mem) => InventorySel.title(mem.get(SelectedItem.key).id),
   verify: [Trait.url({ pathname: "/inventory-item.html" })],
   async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
     const items = await collectInventoryItems(page);
@@ -28,7 +28,7 @@ export const NavItemDetailBlock = defineMemNavBlock<ItemDetailPage>({
       label: `Open "${item.name}" details`,
       key: SelectedItem.key,
       value: item,
-      highlight: inventoryItemTitleSelector(item.id),
+      highlight: InventorySel.title(item.id),
     }));
   },
 });

package/examples/saucedemo/src/blocks/saucedemo-web/{actions → methods}/submit-login-for-flow.ts

@@ -1,11 +1,11 @@
 import type { DefinedBlock } from "waygraph";
 import type { LoginPage, LoggedIn } from "../../../states/checkout.states.js";
-import { SubmitLoginActionBlock } from "./submit-login.action.block.js";
+import { SubmitLoginActionBlock } from "./submit-login.method.block.js";
 
 /**
  * Kind: helper (not a discoverable Block file)
  * Helper: typed alias over SubmitLoginActionBlock
- * Route: saucedemo-web/actions/  (page URL /)
+ * Route: saucedemo-web/methods/  (page URL /)
  *
  * DefinedBlock cast so linear Flows can chain .withVerify on Out=LoggedIn;
  * runtime still branches on bad credentials via SubmitLoginActionBlock.

package/examples/saucedemo/src/blocks/saucedemo-web/{actions/submit-login.action.block.ts → methods/submit-login.method.block.ts}

@@ -1,18 +1,18 @@
-import { defineActionBlock, checkpoint, Trait } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait } from "waygraph";
 import type { LoginPage, LoginSubmitOutcome } from "../../../states/checkout.states.js";
 import { LoginCreds } from "../../../states/checkout.mem-keys.js";
 
 type LoginObserve = "success" | "failure";
 
 /**
- * Kind: Action
- * Helper: defineActionBlock
- * Route: saucedemo-web/actions/  (page URL /)
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/methods/  (page URL /)
  *
  * Fills credentials and submits - never page.goto (nav-login owns that).
  * Branches: good creds -> LoggedIn; bad/locked -> LoginPage with error banner.
  */
-export const SubmitLoginActionBlock = defineActionBlock<LoginPage, LoginSubmitOutcome>({
+export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOutcome>({
   name: "submit-login",
   description: "Logs a user in when credentials are valid; stays on LoginPage when auth fails.",
   requires: [LoginCreds.key],

package/{templates/quickstart/src/blocks/saucedemo-web/actions/submit-logout.action.block.ts → examples/saucedemo/src/blocks/saucedemo-web/methods/submit-logout.method.block.ts}

@@ -1,14 +1,14 @@
-import { defineActionBlock, checkpoint, Trait } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait } from "waygraph";
 import type { LoggedIn, LoginPage } from "../../../states/checkout.states.js";
 
 /**
- * Kind: Action
- * Helper: defineActionBlock
- * Route: saucedemo-web/actions/  (page URL / after logout)
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/methods/  (page URL / after logout)
  *
  * Burger menu Logout - real cycle back to LoginPage (same Checkpoint nav-login lands on).
  */
-export const SubmitLogoutBlock = defineActionBlock<LoggedIn, LoginPage>({
+export const SubmitLogoutBlock = defineMethodBlock<LoggedIn, LoginPage>({
   name: "submit-logout",
   description: "Opens the burger menu and logs out.",
   instruction: {

package/examples/saucedemo/src/flows/cart-bulk.flow.ts

@@ -0,0 +1,19 @@
+import { Engine, start, end, withTitle, chainFlow } from "waygraph";
+import { loginFlow } from "./login.flow.js";
+import { AddAllToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-all-to-cart.method.block.js";
+import { RemoveAllFromCartBlock } from "../blocks/saucedemo-web/inventory/methods/remove-all-from-cart.method.block.js";
+
+const engine = new Engine();
+
+/**
+ * Episode after login: drain every Add button, then every Remove button.
+ * Proves bulk Methods + round-trip (LoggedIn <-> ItemInCart) without
+ * instanceOptions. Pair with loginFlow via chainFlow for `waygraph demo`.
+ */
+export const cartBulkEpisode = withTitle(
+  engine.defineFlow([start, AddAllToCartBlock, RemoveAllFromCartBlock, end]),
+  "Cart bulk add/remove all",
+);
+
+/** Full demo: Sign In -> Add all -> Remove all. */
+export const cartBulkFlow = chainFlow(loginFlow, cartBulkEpisode);

package/examples/saucedemo/src/flows/cart-mem.flow.ts

@@ -1,5 +1,5 @@
 import { Engine, start, end } from "waygraph";
-import { RemoveFromCartBlock } from "../blocks/saucedemo-web/inventory/actions/remove-from-cart.effect.block.js";
+import { RemoveFromCartBlock } from "../blocks/saucedemo-web/inventory/methods/remove-from-cart.effect.block.js";
 
 const engine = new Engine();
 

package/examples/saucedemo/src/flows/catalog-logout.flow.ts

@@ -1,7 +1,7 @@
 import { Engine, start, end, withTitle } from "waygraph";
 import { NavItemDetailBlock } from "../blocks/saucedemo-web/inventory/nav-item-detail.block.js";
 import { NavBackToInventoryBlock } from "../blocks/saucedemo-web/inventory-item/nav-back-to-inventory.block.js";
-import { SubmitLogoutBlock } from "../blocks/saucedemo-web/actions/submit-logout.action.block.js";
+import { SubmitLogoutBlock } from "../blocks/saucedemo-web/methods/submit-logout.method.block.js";
 
 const engine = new Engine();
 

package/examples/saucedemo/src/flows/checkout-then-browse-again.flow.ts

@@ -9,12 +9,12 @@ import type {
   OrderComplete,
 } from "../states/checkout.states.js";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
-import { SubmitLoginForFlow } from "../blocks/saucedemo-web/actions/submit-login-for-flow.js";
-import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/actions/add-to-cart.effect.block.js";
+import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
+import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
-import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/actions/submit-checkout-info.action.block.js";
-import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/actions/finish-order.action.block.js";
+import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
+import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 import { NavBackToProductsBlock } from "../blocks/saucedemo-web/inventory-item/nav-back-to-products.block.js";
 
 const engine = new Engine({ headless: false, slowMo: 250 });

package/examples/saucedemo/src/flows/checkout.flow.ts

@@ -9,12 +9,12 @@ import type {
   OrderComplete,
 } from "../states/checkout.states.js";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
-import { SubmitLoginForFlow } from "../blocks/saucedemo-web/actions/submit-login-for-flow.js";
-import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/actions/add-to-cart.effect.block.js";
+import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
+import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
-import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/actions/submit-checkout-info.action.block.js";
-import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/actions/finish-order.action.block.js";
+import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
+import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 
 const engine = new Engine({ headless: false, slowMo: 250 });
 

package/examples/saucedemo/src/flows/login.flow.ts

@@ -1,6 +1,6 @@
 import { Engine, start, end, withTitle } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
-import { SubmitLoginForFlow } from "../blocks/saucedemo-web/actions/submit-login-for-flow.js";
+import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 
 const engine = new Engine();
 

package/examples/saucedemo/src/flows/shop.flow.ts

@@ -1,9 +1,9 @@
 import { Engine, start, end, withTitle } from "waygraph";
-import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/actions/add-to-cart.effect.block.js";
+import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
-import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/actions/submit-checkout-info.action.block.js";
-import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/actions/finish-order.action.block.js";
+import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
+import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 
 const engine = new Engine();
 

package/examples/saucedemo/src/flows/smoke.flow.ts

@@ -1,8 +1,8 @@
 import { Engine, start, end } from "waygraph";
 import type { LoginPage, LoggedIn, ItemInCart } from "../states/checkout.states.js";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
-import { SubmitLoginForFlow } from "../blocks/saucedemo-web/actions/submit-login-for-flow.js";
-import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/actions/add-to-cart.effect.block.js";
+import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
+import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 
 const engine = new Engine();
 

package/examples/saucedemo/src/flows/viewer-blocked.flow.ts

@@ -1,6 +1,6 @@
 import { Engine, start, end, withTitle, withSessionReset } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
-import { SubmitLoginActionBlock } from "../blocks/saucedemo-web/actions/submit-login.action.block.js";
+import { SubmitLoginActionBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
 
 const engine = new Engine();
 

package/examples/saucedemo/tests/flow-block-verify.spec.ts

@@ -1,7 +1,7 @@
 import { test, expect } from "@playwright/test";
 import { MemPage, checkpoint, Trait } from "waygraph";
 import { checkoutFlow } from "../src/flows/checkout.flow.js";
-import { SubmitLoginActionBlock } from "../src/blocks/saucedemo-web/actions/submit-login.action.block.js";
+import { SubmitLoginActionBlock } from "../src/blocks/saucedemo-web/methods/submit-login.method.block.js";
 import { LoginCreds, SelectedItem } from "../src/states/checkout.mem-keys.js";
 
 // checkoutFlow.withBlockVerify/modBlockVerify - a spec that only imports the

package/examples/saucedemo/tests/submit-login-branch.spec.ts

@@ -1,7 +1,7 @@
 import { test, expect } from "@playwright/test";
 import { MemPage, Engine, start, end } from "waygraph";
 import { NavLoginBlock } from "../src/blocks/saucedemo-web/nav-login.block.js";
-import { SubmitLoginActionBlock } from "../src/blocks/saucedemo-web/actions/submit-login.action.block.js";
+import { SubmitLoginActionBlock } from "../src/blocks/saucedemo-web/methods/submit-login.method.block.js";
 import { LoginCreds } from "../src/states/checkout.mem-keys.js";
 
 test("submit-login: wrong password branches to LoginPage with error banner", async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.7.16",
+  "version": "0.10.1",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/quickstart/README-saucedemo-commands.md

@@ -0,0 +1,72 @@
+# Sauce Demo - convention showcase
+
+Full live consumer for [saucedemo.com](https://www.saucedemo.com). This tree is
+the **reference** for waygraph consumer conventions:
+
+- Route folders under `src/blocks/saucedemo-web/` = real Swag Labs URLs
+- **Nav** / **Effect** / **Action** file kinds (helpers are TypeScript salt;
+  runtime is still `Block`)
+- `instanceOptions` menus for `waygraph auto` (Add/Remove + Open details)
+- Detailed Kind / Helper / Route comments on every Block file
+- Per-route `NAV.md` + root `src/blocks/SITE-MAP.md`
+
+**GitHub Pages walkthrough:**
+[docs/saucedemo](https://deviate-dv8.github.io/waygraph/saucedemo/)
+(`docs/saucedemo/` in this repo - README, SITE-MAP, kinds, layout, auto, comments).
+
+`waygraph try demo` copies the sibling template at `templates/quickstart`
+(same Blocks) into an OS temp dir.
+
+## Setup
+
+From the waygraph package root (after `npm run build`):
+
+```bash
+cd examples/saucedemo
+npm install
+npx playwright install chromium
+```
+
+## Commands
+
+| Want | Command |
+|------|---------|
+| Headless suite | `npm test` |
+| 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 (named flow) | `npm run demo:bulk` |
+| Cart bulk stepper | `npm run demo:bulk:step` |
+| **Cart bulk** chain (Block names only) | `npm run chain:bulk` |
+| List flows | `npm run flows` |
+
+**Demo vs auto vs chain for cart bulk**
+
+| | CLI | Needs `.flow.ts`? |
+|--|-----|-------------------|
+| **`chain` (block names)** | `npm run chain:bulk` → `loginFlow({…}) then add-all-to-cart then remove-all-from-cart` | No — Block `.name` only |
+| **`demo` (named flow)** | `npm run demo:bulk` → `cartBulkFlow` | Yes — `cart-bulk.flow.ts` |
+| **`auto` (pick live)** | `npm run auto` / `auto:cli` | No — menu from graph |
+
+Same Blocks either way. `chain` is the ad-hoc path (handout-style `"A then B then C"`).
+
+## Layout (short)
+
+```text
+src/blocks/
+  SITE-MAP.md
+  saucedemo-web/                 # URL /
+    NAV.md
+    nav-login.block.ts
+    methods/                     # submit-login, logout, …
+    inventory/                   # URL /inventory.html
+      nav-item-detail.block.ts   # MemNav
+      methods/*.effect.block.ts  # Add / Remove
+    cart/                        # URL /cart.html
+    checkout-step-one/
+    checkout-step-two/
+```
+
+Docs: [Sauce Demo showcase](../../docs/saucedemo/) ·
+[Auto explore](../../docs/auto.html) · [Consumer layout](../../docs/consumer.html)

package/templates/quickstart/docs/CONVENTION.md

@@ -17,7 +17,7 @@ see package docs `docs/consumer.html` (no invented `root/`, `landing/`, or
 |------|------|--------|--------------|
 | 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. |
+| Action | `*.method.block.ts` | `defineBlock` | No - forms, submit, logout, etc. |
 
 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
@@ -32,9 +32,9 @@ src/blocks/
     NAV.md
     nav-login.block.ts
     actions/
-      submit-login.action.block.ts
+      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
       nav-item-detail.block.ts
@@ -54,11 +54,11 @@ src/blocks/
     checkout-step-one/           # /checkout-step-one.html
       NAV.md
       actions/
-        submit-checkout-info.action.block.ts
+        submit-checkout-info.method.block.ts
     checkout-step-two/           # /checkout-step-two.html
       NAV.md
       actions/
-        finish-order.action.block.ts
+        finish-order.method.block.ts
 src/states/
 src/flows/
 ```

package/templates/quickstart/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.