waygraph 0.7.15 → 0.10.0

package/examples/saucedemo/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/examples/saucedemo/package-lock.json

@@ -17,7 +17,7 @@
       }
     },
     "../..": {
-      "version": "0.7.11",
+      "version": "0.10.0",
       "license": "MIT",
       "dependencies": {
         "tsx": "^4.0.0"

package/examples/saucedemo/package.json

@@ -8,18 +8,24 @@
     "typecheck": "tsc --noEmit",
     "test": "playwright test",
     "flows": "waygraph list",
-    "demo": "waygraph demo shopFlow",
-    "demo:step": "waygraph demo shopFlow --step --no-autoplay --title \"Shop demo\"",
-    "demo:autoplay": "waygraph demo shopFlow --autoplay --title \"Shop demo\"",
+    "demo": "waygraph demo --blocks shopFlow",
+    "demo:step": "waygraph demo --blocks shopFlow --title \"Shop demo\"",
+    "demo:auto-next": "waygraph demo --blocks shopFlow --auto-next --title \"Shop demo\"",
     "auto": "waygraph auto",
-    "auto:cli": "waygraph auto --cli",
+    "auto:cli": "waygraph auto --cli --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
+    "prove:auto-cli": "node scripts/drive-auto-cli.mjs",
     "graph": "waygraph graph",
     "graph:mermaid": "waygraph graph --mermaid",
     "prove:login-branch": "node scripts/prove-wrong-login-runtime.mjs",
     "prove:graph": "node scripts/prove-auto-graph.mjs",
     "prove:add-to-cart-menu": "node scripts/prove-add-to-cart-menu.mjs",
     "prove": "npm run prove:login-branch && npm run prove:graph && npm run prove:add-to-cart-menu && npm test",
-    "record": "waygraph chain \"loginFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}) then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}})\" --video --no-step"
+    "record": "waygraph run --blocks \"loginFlow then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}})\" --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\\\"}}\"",
+    "chain:bulk": "waygraph run --blocks \"loginFlow then add-all-to-cart then remove-all-from-cart\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --non-headless"
   },
   "waygraph": {
     "baseUrl": "https://www.saucedemo.com"

package/examples/saucedemo/scripts/capture-wrong-login.mjs

@@ -88,7 +88,7 @@ const nodeNames = graph.nodes.map((n) => n.checkpoint);
 
 const { NavLoginBlock } = await import(pathToFileURL(join(root, "src/blocks/saucedemo-web/nav-login.block.js")).href);
 const { SubmitLoginActionBlock } = await import(
-  pathToFileURL(join(root, "src/blocks/saucedemo-web/actions/submit-login.action.block.js")).href
+  pathToFileURL(join(root, "src/blocks/saucedemo-web/methods/submit-login.method.block.js")).href
 );
 const { LoginCreds } = await import(pathToFileURL(join(root, "src/states/checkout.mem-keys.js")).href);
 

package/examples/saucedemo/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/examples/saucedemo/scripts/prove-wrong-login-runtime.mjs

@@ -15,7 +15,7 @@ const waygraphDist = join(root, "../../dist");
 const { Engine, start, end, MemPage } = await import(pathToFileURL(join(waygraphDist, "index.js")).href);
 const { NavLoginBlock } = await import(pathToFileURL(join(root, "src/blocks/saucedemo-web/nav-login.block.js")).href);
 const { SubmitLoginActionBlock } = await import(
-  pathToFileURL(join(root, "src/blocks/saucedemo-web/actions/submit-login.action.block.js")).href
+  pathToFileURL(join(root, "src/blocks/saucedemo-web/methods/submit-login.method.block.js")).href
 );
 const { LoginCreds } = await import(pathToFileURL(join(root, "src/states/checkout.mem-keys.js")).href);
 

package/examples/saucedemo/scripts/show-auto-menu.mjs

@@ -0,0 +1,72 @@
+// Dump waygraph auto menu sections on inventory (incl. bulk add/remove-all).
+import { chromium } from "@playwright/test";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+await import(require.resolve("tsx/esm"));
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const waygraphDist = join(root, "../../dist");
+
+const { buildExploreContext, buildExploreMenu } = await import(
+  pathToFileURL(join(waygraphDist, "auto-explore.js")).href
+);
+const { MemPage, Engine, start, end } = await import(
+  pathToFileURL(join(waygraphDist, "index.js")).href
+);
+
+const exe = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+
+async function runBlock(engine, entry, context, page, mem) {
+  const flow = engine.defineFlow([start, entry.block, end]);
+  await flow.run(context, mem, { page, closeOnFinish: false });
+}
+
+function dump(title, menu) {
+  console.log(`\n=== ${title} (here=${menu.here}) ===`);
+  for (const sec of menu.sections) {
+    console.log(`\n[${sec.title}]`);
+    for (const e of sec.edges) {
+      const label = e.label ?? `${e.block} -> ${e.to}`;
+      console.log(`  • ${label}`);
+    }
+  }
+}
+
+const { graph, library } = await buildExploreContext(root);
+const mem = new MemPage();
+mem.set(library.byName.get("submit-login").block.requires[0], {
+  username: "standard_user",
+  password: "secret_sauce",
+});
+
+const browser = await chromium.launch({
+  headless: true,
+  ...(exe ? { executablePath: exe, args: ["--no-sandbox"] } : {}),
+});
+const context = await browser.newContext({
+  baseURL: "https://www.saucedemo.com",
+  viewport: { width: 1280, height: 900 },
+});
+const page = await context.newPage();
+const engine = new Engine({ headless: true });
+
+await page.goto("/", { waitUntil: "load" });
+await runBlock(engine, library.byName.get("submit-login"), context, page, mem);
+await page.waitForURL(/inventory\.html/);
+
+const menu1 = await buildExploreMenu(page, graph, library, "LoggedIn");
+dump("AFTER LOGIN — cart empty", menu1);
+
+const bike = menu1.flat.find(
+  (e) => e.block === "add-to-cart" && e.instanceOption?.value?.id === "sauce-labs-bike-light",
+);
+mem.set(bike.instanceOption.key, bike.instanceOption.value);
+await runBlock(engine, library.byName.get("add-to-cart"), context, page, mem);
+
+const menu2 = await buildExploreMenu(page, graph, library, "LoggedIn");
+dump("AFTER ADD BIKE LIGHT — mixed", menu2);
+
+await browser.close();

package/examples/saucedemo/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/examples/saucedemo/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/examples/saucedemo/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/examples/saucedemo/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/examples/saucedemo/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/examples/saucedemo/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/{templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/actions/submit-checkout-info.action.block.ts → examples/saucedemo/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/examples/saucedemo/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/examples/saucedemo/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/examples/saucedemo/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).

package/examples/saucedemo/src/blocks/saucedemo-web/inventory/inventory.page.block.ts

@@ -0,0 +1,37 @@
+import { definePageBlock, Trait } from "waygraph";
+import type { LoggedIn } from "../../../states/checkout.states.js";
+import { AddToCartBlock } from "./methods/add-to-cart.effect.block.js";
+import { RemoveFromCartBlock } from "./methods/remove-from-cart.effect.block.js";
+import { AddAllToCartBlock } from "./methods/add-all-to-cart.method.block.js";
+import { RemoveAllFromCartBlock } from "./methods/remove-all-from-cart.method.block.js";
+import { NavItemDetailBlock } from "./nav-item-detail.block.js";
+import { InventorySel } from "./methods/inventory-items.js";
+
+/**
+ * Kind: Page
+ * Helper: definePageBlock
+ * Route: saucedemo-web/inventory/  (= /inventory.html)
+ *
+ * Hub for the inventory screen after login. Methods (per-item + bulk
+ * add/remove, open detail) hang off this page; DOM strings live in
+ * InventorySel. Arrival-only (no url/click) - submit-login already resolved
+ * to LoggedIn. Cart Effects/Methods use In Checkpoint<string> (from: "*") so
+ * auto still offers them after leave/return - menu follows live DOM buttons.
+ */
+export const InventoryPageBlock = definePageBlock<LoggedIn>({
+  name: "page-inventory",
+  description:
+    "Inventory catalog hub - per-item and bulk add/remove, open item detail.",
+  checkpoint: "LoggedIn",
+  verify: [
+    Trait.url({ pathname: "/inventory.html" }),
+    Trait.visible(InventorySel.list),
+  ],
+  methods: {
+    addToCart: () => AddToCartBlock,
+    removeFromCart: () => RemoveFromCartBlock,
+    addAllToCart: () => AddAllToCartBlock,
+    removeAllFromCart: () => RemoveAllFromCartBlock,
+    openDetail: () => NavItemDetailBlock,
+  },
+});