waygraph 0.7.15 → 0.10.0

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

@@ -0,0 +1,186 @@
+# Block helpers (convention)
+
+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` |
+| `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.
+
+---
+
+## Page hub + methods + Sel
+
+One **PageBlock** = this screen. Methods hang off it. DOM strings live in `*Sel` (not in mem).
+
+```ts
+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 */ },
+    async observe(page) {
+      try {
+        await page.waitForURL(/\/inventory\.html/, { timeout: 8000 });
+        return "success";
+      } catch {
+        return "failure";
+      }
+    },
+    resolve: (o) => checkpoint(o === "success" ? "LoggedIn" : "LoginPage"),
+  },
+});
+```
+
+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` |
+
+

package/templates/quickstart/package.json

@@ -8,18 +8,22 @@
     "typecheck": "tsc --noEmit",
     "check": "waygraph check",
     "auto": "waygraph auto",
-    "auto:cli": "waygraph auto --cli",
+    "auto:cli": "waygraph auto --cli --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
     "graph": "waygraph graph",
     "graph:mermaid": "waygraph graph --mermaid",
-    "demo": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --step --no-autoplay",
-    "demo:autoplay": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --step --autoplay",
-    "record": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --video --no-step"
+    "demo": "waygraph demo --blocks \"loginFlow then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
+    "demo:auto-next": "waygraph demo --blocks \"loginFlow then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --auto-next",
+    "record": "waygraph run --blocks \"loginFlow then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --video --no-step",
+    "demo:bulk": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
+    "demo:bulk:auto-next": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --auto-next --title \"Cart bulk demo\"",
+    "demo:bulk:video": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --auto-play-video --title \"Cart bulk demo\"",
+    "run:bulk": "waygraph run --blocks \"loginFlow then add-all-to-cart then remove-all-from-cart\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\""
   },
   "waygraph": {
     "baseUrl": "https://www.saucedemo.com"
   },
   "dependencies": {
-    "waygraph": "^0.7.15"
+    "waygraph": "^0.10.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

package/templates/quickstart/scripts/drive-auto-cli.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Drive `waygraph auto --cli` through login -> add-all -> remove-all -> quit.
+ * Waits for each Choose: prompt so picks are not sent early.
+ *
+ * Usage (from examples/saucedemo):
+ *   node scripts/drive-auto-cli.mjs
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const waygraphBin = join(root, "../../bin/waygraph");
+const DATA =
+  process.env.WAYGRAPH_DATA ??
+  '{"saucedemo.credentials":{"username":"standard_user","password":"secret_sauce"}}';
+
+function pickByLabel(menuText, label) {
+  const re = new RegExp(`\\[(\\d+)\\]\\s+${label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+  const m = menuText.match(re);
+  if (!m) throw new Error(`menu missing "${label}"\n${menuText}`);
+  return m[1];
+}
+
+async function main() {
+  const child = spawn(waygraphBin, ["auto", "--cli", "--data", DATA, "."], {
+    cwd: root,
+    stdio: ["pipe", "pipe", "pipe"],
+    env: process.env,
+  });
+
+  let buf = "";
+  const dump = (chunk, stream) => {
+    const s = chunk.toString();
+    buf += s;
+    process[stream].write(s);
+  };
+  child.stdout.on("data", (c) => dump(c, "stdout"));
+  child.stderr.on("data", (c) => dump(c, "stderr"));
+
+  const waitChoose = () =>
+    new Promise((resolve, reject) => {
+      const start = Date.now();
+      const tick = () => {
+        if (buf.includes("Choose:")) {
+          const i = buf.lastIndexOf("Choose:");
+          const slice = buf.slice(Math.max(0, i - 4000), i + 8);
+          resolve(slice);
+          return;
+        }
+        if (Date.now() - start > 120_000) {
+          reject(new Error(`timeout waiting for Choose:\n${buf.slice(-2000)}`));
+          return;
+        }
+        setTimeout(tick, 100);
+      };
+      tick();
+    });
+
+  const send = (line) => {
+    console.error(`\n>> pick ${line.trim()}`);
+    buf = buf.replace(/Choose:/g, "Choose(done):");
+    child.stdin.write(line);
+  };
+
+  try {
+    let menu = await waitChoose();
+    send("1\n"); // submit-login
+    menu = await waitChoose();
+    if (!/LoggedIn|Add all to cart/.test(menu)) {
+      throw new Error(`expected inventory after login, got:\n${menu}`);
+    }
+    send(`${pickByLabel(menu, "Add all to cart")}\n`);
+    menu = await waitChoose();
+    send(`${pickByLabel(menu, "Remove all from cart")}\n`);
+    menu = await waitChoose();
+    if (!/Add all to cart/.test(menu)) {
+      throw new Error(`expected Add all again after remove-all, got:\n${menu}`);
+    }
+    send("q\n");
+    const code = await new Promise((res) => child.on("exit", res));
+    if (code !== 0 && code !== null) process.exitCode = code;
+    else console.error("\ndrive-auto-cli: PASS login -> add-all -> remove-all -> quit");
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    child.kill("SIGTERM");
+    process.exitCode = 1;
+  }
+}
+
+main();

package/templates/quickstart/src/blocks/SITE-MAP.md

@@ -9,16 +9,19 @@ src/blocks/
   saucedemo-web/                      # URL /
     NAV.md
     nav-login.block.ts                # Nav  defineNavBlock url:/
-    actions/
-      submit-login.action.block.ts    # Action defineBlock
+    methods/
+      submit-login.method.block.ts    # Method defineMethodBlock
       submit-login-for-flow.ts        # helper (not a discoverable *.block.ts alone)
-      submit-logout.action.block.ts   # Action
+      submit-logout.method.block.ts   # Method defineMethodBlock
     inventory/                        # URL /inventory.html
+      inventory.page.block.ts       # Page definePageBlock
       NAV.md
       nav-item-detail.block.ts        # Nav  defineMemNavBlock (instance row)
-      actions/
+      methods/
         inventory-items.ts            # DOM helpers for Effects (not a Block)
         add-to-cart.effect.block.ts   # Effect defineEffectBlock
+        add-all-to-cart.method.block.ts
+        remove-all-from-cart.method.block.ts
         remove-from-cart.effect.block.ts
     inventory-item/                   # URL /inventory-item.html
       NAV.md
@@ -31,12 +34,12 @@ src/blocks/
       nav-checkout-info.block.ts
     checkout-step-one/                # URL /checkout-step-one.html
       NAV.md
-      actions/
-        submit-checkout-info.action.block.ts
+      methods/
+        submit-checkout-info.method.block.ts
     checkout-step-two/                # URL /checkout-step-two.html
       NAV.md
-      actions/
-        finish-order.action.block.ts
+      methods/
+        finish-order.method.block.ts
 ```
 
 Checkpoints and mem keys live under `src/states/`. Flows under `src/flows/`

package/templates/quickstart/src/blocks/saucedemo-web/NAV.md

@@ -16,9 +16,9 @@ Login page for Swag Labs. This folder is the namespace root (`/` in the browser)
 
 | File | Kind | Notes |
 |------|------|-------|
-| `actions/submit-login.action.block.ts` | Action | Form submit; branches LoggedIn vs LoginPage |
-| `actions/submit-login-for-flow.ts` | helper | Typed alias for linear Flows |
-| `actions/submit-logout.action.block.ts` | Action | Burger menu logout -> LoginPage |
+| `methods/submit-login.method.block.ts` | Method | Form submit; branches LoggedIn vs LoginPage |
+| `methods/submit-login-for-flow.ts` | helper | Typed alias for linear Flows |
+| `methods/submit-logout.method.block.ts` | Method | Burger menu logout -> LoginPage |
 
 ## Related mem keys / checkpoints
 

package/templates/quickstart/src/blocks/saucedemo-web/cart/NAV.md

@@ -15,7 +15,7 @@ Shopping cart page and checkout entry.
 
 ## Effects / actions
 
-(none on this route; cart mutations live under `inventory/actions/`)
+(none on this route; cart mutations live under `inventory/methods/`)
 
 ## Related mem keys / checkpoints
 

package/templates/quickstart/src/blocks/saucedemo-web/cart/nav-cart.block.ts

@@ -1,14 +1,14 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { CartPage } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/cart/  (= /cart.html)
  *
  * click, not url - header cart link from inventory-adjacent pages.
  */
-export const NavCartBlock = defineNavBlock<CartPage>({
+export const NavCartBlock = defineNavClickBlock<CartPage>({
   name: "nav-cart",
   description: "Clicks the cart link in the header.",
   checkpoint: "CartPage",

package/templates/quickstart/src/blocks/saucedemo-web/cart/nav-checkout-info.block.ts

@@ -1,14 +1,14 @@
-import { defineNavBlock, Trait } from "waygraph";
+import { defineNavClickBlock, Trait } from "waygraph";
 import type { CheckoutInfoPage } from "../../../states/checkout.states.js";
 
 /**
  * Kind: Nav
- * Helper: defineNavBlock
+ * Helper: defineNavClickBlock
  * Route: saucedemo-web/cart/  (click leaves /cart.html -> /checkout-step-one.html)
  *
  * Cart page "Checkout" button - owns the nav into step one.
  */
-export const NavCheckoutInfoBlock = defineNavBlock<CheckoutInfoPage>({
+export const NavCheckoutInfoBlock = defineNavClickBlock<CheckoutInfoPage>({
   name: "nav-checkout-info",
   description: "Clicks 'Checkout' on the cart page.",
   checkpoint: "CheckoutInfoPage",

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/NAV.md

@@ -14,7 +14,7 @@ Shipping info form before order overview.
 
 | File | Kind | Notes |
 |------|------|-------|
-| `actions/submit-checkout-info.action.block.ts` | Action | Fill form + Continue -> overview |
+| `methods/submit-checkout-info.method.block.ts` | Method | Fill form + Continue -> overview |
 
 ## Related mem keys / checkpoints
 

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

@@ -1,15 +1,15 @@
-import { defineBlock, checkpoint, Trait } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait } from "waygraph";
 import type { CheckoutInfoPage, CheckoutOverviewPage } from "../../../../states/checkout.states.js";
 
 /**
- * Kind: Action
- * Helper: defineBlock
- * Route: saucedemo-web/checkout-step-one/actions/  (= /checkout-step-one.html)
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/checkout-step-one/methods/  (= /checkout-step-one.html)
  *
  * Fills shipping form and continues - never navigates itself
  * (nav-checkout-info already got here).
  */
-export const SubmitCheckoutInfoBlock = defineBlock<CheckoutInfoPage, CheckoutOverviewPage>({
+export const SubmitCheckoutInfoBlock = defineMethodBlock<CheckoutInfoPage, CheckoutOverviewPage>({
   name: "submit-checkout-info",
   description: "Fills in the shipping info form and continues to the order overview.",
   instruction: {

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-two/NAV.md

@@ -14,7 +14,7 @@ Order overview / finish page.
 
 | File | Kind | Notes |
 |------|------|-------|
-| `actions/finish-order.action.block.ts` | Action | Finish -> thank-you / OrderComplete |
+| `methods/finish-order.method.block.ts` | Method | Finish -> thank-you / OrderComplete |
 
 ## Related mem keys / checkpoints
 

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-two/{actions/finish-order.action.block.ts → methods/finish-order.method.block.ts}

@@ -1,14 +1,14 @@
-import { defineBlock, checkpoint, Trait, narrate } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait, narrate } from "waygraph";
 import type { CheckoutOverviewPage, OrderComplete } from "../../../../states/checkout.states.js";
 
 /**
- * Kind: Action
- * Helper: defineBlock
- * Route: saucedemo-web/checkout-step-two/actions/  (= /checkout-step-two.html)
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/checkout-step-two/methods/  (= /checkout-step-two.html)
  *
  * Places the order on the overview page - form/finish click, not a NavBlock.
  */
-export const FinishOrderBlock = defineBlock<CheckoutOverviewPage, OrderComplete>({
+export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderComplete>({
   name: "finish-order",
   description: "Places the order and confirms the 'Thank you for your order!' completion page.",
   instruction: {

package/templates/quickstart/src/blocks/saucedemo-web/inventory/NAV.md

@@ -6,21 +6,33 @@ Product catalog after a successful login.
 
 - `/inventory.html`
 
+## Page hub
+
+| File | Helper | Notes |
+|------|--------|-------|
+| `inventory.page.block.ts` | `definePageBlock` | Hub `LoggedIn`; registers add/remove/open methods; `InventorySel` for DOM |
+
 ## Nav blocks
 
 | File | Helper | Notes |
 |------|--------|-------|
 | `nav-item-detail.block.ts` | `defineMemNavBlock` | Opens mem-picked product detail; instance rows per card |
 
-## Effects / actions
+## Methods
 
 | File | Kind | Notes |
 |------|------|-------|
-| `actions/add-to-cart.effect.block.ts` | Effect | Add mem-picked item; instance menu |
-| `actions/remove-from-cart.effect.block.ts` | Effect | Remove mem-picked item; may empty cart |
-| `actions/inventory-items.ts` | helper | DOM collectors (not a Block) |
+| `methods/add-to-cart.effect.block.ts` | Effect | Add mem-picked item; instance menu |
+| `methods/remove-from-cart.effect.block.ts` | Effect | Remove mem-picked item; may empty cart |
+| `methods/add-all-to-cart.method.block.ts` | Method | Bulk add every Add button; one menu row |
+| `methods/remove-all-from-cart.method.block.ts` | Method | Bulk remove every Remove button; one menu row |
+| `methods/inventory-items.ts` | helper | `InventorySel` + DOM collectors (not a Block) |
 
 ## Related mem keys / checkpoints
 
-- Mem: `saucedemo.selectedItem` (`SelectedItem`)
+- Mem: `saucedemo.selectedItem` (`SelectedItem`) - per-item Effects only
 - Checkpoints: `LoggedIn`, `ItemInCart`, `ItemDetailPage` (via MemNav)
+- Sel: `InventorySel` (DOM only — not mem)
+- Round-trip: cart Methods/Effects use `In = Checkpoint<string>` (`from: "*"`).
+  Auto menu follows live Add/Remove buttons after leave/return; URL sniff on
+  `/inventory.html` still reports `LoggedIn` (same URL; cart is status).