waygraph 0.7.16 → 0.10.1

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.16"
+    "waygraph": "^0.10.1"
   },
   "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/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 { defineActionBlock, checkpoint, Trait } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait } from "waygraph";
 import type { CheckoutInfoPage, CheckoutOverviewPage } from "../../../../states/checkout.states.js";
 
 /**
- * Kind: Action
- * Helper: defineActionBlock
- * 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 = defineActionBlock<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 { defineActionBlock, checkpoint, Trait, narrate } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait, narrate } from "waygraph";
 import type { CheckoutOverviewPage, OrderComplete } from "../../../../states/checkout.states.js";
 
 /**
- * Kind: Action
- * Helper: defineActionBlock
- * 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 = defineActionBlock<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).

package/templates/quickstart/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,
+  },
+});

package/templates/quickstart/src/blocks/saucedemo-web/inventory/methods/add-all-to-cart.method.block.ts

@@ -0,0 +1,55 @@
+import { defineMethodBlock, checkpoint, type Checkpoint } from "waygraph";
+import type { RemoveFromCartOutcome } from "../../../../states/checkout.states.js";
+import { collectAddableItems, InventorySel } from "./inventory-items.js";
+
+type BulkObserve = "added" | "nothing";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/inventory/methods/  (= /inventory.html)
+ *
+ * Bulk: click every live "Add to cart" once. No instanceOptions - one auto
+ * menu row. In is Checkpoint<string> (from: "*") so back-and-forth works:
+ * leave inventory and return, collectors re-read Add buttons from the DOM.
+ * Out: ItemInCart if the cart has items after; LoggedIn if still empty.
+ */
+export const AddAllToCartBlock = defineMethodBlock<
+  Checkpoint<string>,
+  RemoveFromCartOutcome
+>({
+  name: "add-all-to-cart",
+  description: "Adds every product still showing Add to cart on this page.",
+  instruction: {
+    async act(page) {
+      const items = await collectAddableItems(page);
+      for (const item of items) {
+        await page.locator(InventorySel.addBtn(item.id)).click();
+      }
+    },
+    async observe(page): Promise<BulkObserve> {
+      const badge = await page.locator(InventorySel.cartBadge).count();
+      return badge > 0 ? "added" : "nothing";
+    },
+    resolve: (observed) =>
+      checkpoint(observed === "added" ? "ItemInCart" : "LoggedIn"),
+    verify: (out) =>
+      out.__state === "ItemInCart"
+        ? [
+            {
+              name: "cart-has-items",
+              async check(page) {
+                return (await page.locator(InventorySel.cartBadge).count()) > 0;
+              },
+            },
+          ]
+        : [
+            {
+              name: "cart-still-empty",
+              async check(page) {
+                return (await page.locator(InventorySel.cartBadge).count()) === 0;
+              },
+            },
+          ],
+  },
+});

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

@@ -1,12 +1,12 @@
 import { defineEffectBlock, checkpoint, type Checkpoint, type WaygraphInstanceOption } from "waygraph";
 import type { ItemInCart } from "../../../../states/checkout.states.js";
 import { SelectedItem } from "../../../../states/checkout.mem-keys.js";
-import { collectAddableItems } from "./inventory-items.js";
+import { collectAddableItems, InventorySel } from "./inventory-items.js";
 
 /**
  * Kind: Effect
  * Helper: defineEffectBlock
- * Route: saucedemo-web/inventory/actions/  (= /inventory.html)
+ * Route: saucedemo-web/inventory/methods/  (= /inventory.html)
  *
  * Mutates cart for the mem-picked product. waygraph auto lists one
  * "Add ..." row per live Add button via instanceOptions.
@@ -18,7 +18,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
   instruction: {
     async act(page, _input, mem) {
       const { id } = mem.get(SelectedItem.key);
-      await page.locator(`[data-test="add-to-cart-${id}"]`).click();
+      await page.locator(InventorySel.addBtn(id)).click();
     },
     resolve: () => checkpoint("ItemInCart"),
     verify: [
@@ -26,11 +26,11 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         name: "item-added-to-cart",
         async check(page, mem) {
           const { id } = mem.get(SelectedItem.key);
-          return await page.locator(`[data-test="remove-${id}"]`).first().isVisible();
+          return await page.locator(InventorySel.removeBtn(id)).first().isVisible();
         },
       },
     ],
-    highlights: () => [{ selector: ".shopping_cart_badge", label: "remember this: cart now has the item" }],
+    highlights: () => [{ selector: InventorySel.cartBadge, label: "remember this: cart now has the item" }],
   },
   async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
     const items = await collectAddableItems(page);
@@ -39,7 +39,7 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
       label: `Add "${item.name}" to cart`,
       key: SelectedItem.key,
       value: item,
-      highlight: `[data-test="add-to-cart-${item.id}"]`,
+      highlight: InventorySel.addBtn(item.id),
     }));
   },
 });

package/templates/quickstart/src/blocks/saucedemo-web/inventory/{actions → methods}/inventory-items.ts

@@ -2,27 +2,45 @@ import type { Page, Locator } from "@playwright/test";
 
 /**
  * Kind: helper (not a Block)
- * Route: saucedemo-web/inventory/actions/  (= /inventory.html)
+ * Route: saucedemo-web/inventory/methods/  (= /inventory.html)
  *
- * DOM collectors for Effect / MemNav instanceOptions. Discovery ignores this
- * file (no *.block.ts suffix). Keep selectors here so add/remove/detail stay thin.
+ * DOM selectors + collectors for Effect / MemNav instanceOptions. Discovery
+ * ignores this file (no *.block.ts suffix). InventorySel = strings only;
+ * collectors use Sel to spawn auto menu rows.
  */
 
 /** Product slug + display name (saucedemo inventory / detail / cart). */
 export type InventoryItem = { id: string; name: string };
 
+/** DOM selectors for this screen - static strings + per-id factories. */
+export const InventorySel = {
+  list: ".inventory_list",
+  card: ".inventory_item",
+  name: ".inventory_item_name",
+  detailName: ".inventory_details_name",
+  cartItem: ".cart_item",
+  cartBadge: ".shopping_cart_badge",
+  addBtn: (id: string) => `[data-test="add-to-cart-${id}"]`,
+  removeBtn: (id: string) => `[data-test="remove-${id}"]`,
+  addBtnPrefix: 'button[data-test^="add-to-cart-"]',
+  removeBtnPrefix: 'button[data-test^="remove-"]',
+  title: (id: string) =>
+    `div.inventory_item:has(button[data-test="add-to-cart-${id}"], button[data-test="remove-${id}"]) ` +
+    `.inventory_item_name`,
+};
+
 async function readItemName(page: Page, button: Locator, id: string): Promise<string> {
   const card = button.locator("xpath=ancestor::div[contains(@class,'inventory_item')][1]");
   if ((await card.count()) > 0) {
-    const text = await card.locator(".inventory_item_name").first().textContent().catch(() => null);
+    const text = await card.locator(InventorySel.name).first().textContent({ timeout: 500 }).catch(() => null);
     if (text?.trim()) return text.trim();
   }
   const cartRow = button.locator("xpath=ancestor::div[contains(@class,'cart_item')][1]");
   if ((await cartRow.count()) > 0) {
-    const text = await cartRow.locator(".inventory_item_name").first().textContent().catch(() => null);
+    const text = await cartRow.locator(InventorySel.name).first().textContent({ timeout: 500 }).catch(() => null);
     if (text?.trim()) return text.trim();
   }
-  const detailName = await page.locator(".inventory_details_name").first().textContent().catch(() => null);
+  const detailName = await page.locator(InventorySel.detailName).first().textContent({ timeout: 500 }).catch(() => null);
   if (detailName?.trim()) return detailName.trim();
   return id.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
@@ -33,7 +51,7 @@ async function collectByPrefix(page: Page, prefix: "add-to-cart-" | "remove-"):
   const items: InventoryItem[] = [];
   for (let i = 0; i < count; i++) {
     const button = buttons.nth(i);
-    const testId = await button.getAttribute("data-test");
+    const testId = await button.getAttribute("data-test", { timeout: 500 }).catch(() => null);
     const id = testId?.replace(new RegExp(`^${prefix}`), "");
     if (!id) continue;
     items.push({ id, name: await readItemName(page, button, id) });
@@ -56,32 +74,34 @@ export function collectRemovableItems(page: Page): Promise<InventoryItem[]> {
  * Used by MemNavBlock (open item details) - not filtered by cart state.
  */
 export async function collectInventoryItems(page: Page): Promise<InventoryItem[]> {
-  const cards = page.locator(".inventory_item");
+  const cards = page.locator(InventorySel.card);
   const count = await cards.count();
   const items: InventoryItem[] = [];
   for (let i = 0; i < count; i++) {
     const card = cards.nth(i);
-    const addTest = await card.locator('button[data-test^="add-to-cart-"]').first().getAttribute("data-test").catch(() => null);
-    const removeTest = await card
-      .locator('button[data-test^="remove-"]')
-      .first()
-      .getAttribute("data-test")
-      .catch(() => null);
+    // count() first - getAttribute on a missing locator waits the full default timeout.
+    const addLoc = card.locator(InventorySel.addBtnPrefix);
+    const removeLoc = card.locator(InventorySel.removeBtnPrefix);
+    const addTest =
+      (await addLoc.count()) > 0
+        ? await addLoc.first().getAttribute("data-test", { timeout: 500 }).catch(() => null)
+        : null;
+    const removeTest =
+      (await removeLoc.count()) > 0
+        ? await removeLoc.first().getAttribute("data-test", { timeout: 500 }).catch(() => null)
+        : null;
     const id =
       addTest?.replace(/^add-to-cart-/, "") ?? removeTest?.replace(/^remove-/, "") ?? null;
     if (!id) continue;
     const name =
-      (await card.locator(".inventory_item_name").first().textContent().catch(() => null))?.trim() ??
+      (await card.locator(InventorySel.name).first().textContent({ timeout: 500 }).catch(() => null))?.trim() ??
       id.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
     items.push({ id, name });
   }
   return items;
 }
 
-/** Click the product title link inside the card that owns this item id. */
+/** @deprecated Prefer {@link InventorySel.title} */
 export function inventoryItemTitleSelector(id: string): string {
-  return (
-    `div.inventory_item:has(button[data-test="add-to-cart-${id}"], button[data-test="remove-${id}"]) ` +
-    `.inventory_item_name`
-  );
+  return InventorySel.title(id);
 }

package/templates/quickstart/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/{examples/saucedemo/src/blocks/saucedemo-web/inventory/actions → templates/quickstart/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),
     }));
   },
 });