waygraph 0.13.6 → 0.14.0

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

@@ -1,6 +1,8 @@
 import { Engine, start, end, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
-import { SubmitLoginActionBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
+import { SubmitLoginBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
 
 const engine = new Engine();
 
@@ -22,7 +24,9 @@ const engine = new Engine();
 // "expected outcome" panel (branching no longer throws).
 export const viewerBlockedFlow = withExpectedFailure(
   withTitle(
-    withSessionReset(engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])),
+    withSessionReset(
+      engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]),
+    ),
     "Viewer: Blocked Login Attempt",
   ),
   "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",

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/methods/submit-login.method.block.js";
+import { SubmitLoginBlock } 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
@@ -31,9 +31,9 @@ test("withBlockVerify: replacing login's verify with an extra real check still p
   mem.set(LoginCreds({ username: "standard_user", password: "secret_sauce" }));
   mem.set(SelectedItem({ id: "sauce-labs-backpack", name: "Sauce Labs Backpack" }));
 
-  // Addressed by the actual SubmitLoginActionBlock reference - the preferred
+  // Addressed by the actual SubmitLoginBlock reference - the preferred
   // form: no typo risk, refactor-safe, jump-to-definition works.
-  const patched = checkoutFlow.withBlockVerify(SubmitLoginActionBlock, [
+  const patched = checkoutFlow.withBlockVerify(SubmitLoginBlock, [
     Trait.url({ pathname: "/inventory.html" }),
     Trait.visible(".inventory_list"),
   ]);

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

@@ -1,7 +1,9 @@
 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/methods/submit-login.method.block.js";
+import { FillUsernameBlock } from "../src/blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../src/blocks/saucedemo-web/methods/fill-password.method.block.js";
+import { SubmitLoginBlock } 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 () => {
@@ -9,7 +11,7 @@ test("submit-login: wrong password branches to LoginPage with error banner", asy
   mem.set(LoginCreds({ username: "standard_user", password: "wrong-password" }));
 
   const engine = new Engine();
-  const flow = engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]);
+  const flow = engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]);
   const result = await flow.run(mem);
 
   expect(result.__state).toBe("LoginPage");
@@ -20,7 +22,7 @@ test("submit-login: good password branches to LoggedIn", async () => {
   mem.set(LoginCreds({ username: "standard_user", password: "secret_sauce" }));
 
   const engine = new Engine();
-  const flow = engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]);
+  const flow = engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]);
   const result = await flow.run(mem);
 
   expect(result.__state).toBe("LoggedIn");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.13.6",
+  "version": "0.14.0",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
@@ -20,6 +20,7 @@
     "bin",
     "templates",
     "examples",
+    "assets",
     "!examples/**/.tmp",
     "!examples/**/.tmp/**",
     "!examples/**/.waygraph-traverse",

package/templates/agents/waygraph-author.agent.md

@@ -13,11 +13,43 @@ You are a waygraph block author. Implement Blocks and Flows that match the consu
 ## Rules
 
 1. One concern per file: `nav-*.block.ts`, `*.page.block.ts`, `*.method.block.ts`, `*.effect.block.ts`, `*.flow.ts`.
-2. Navigation only inside `defineNavBlock` / `defineNavClickBlock`. Regular Method/Effect `act` uses ActionPage (no goto).
-3. Effects that appear in `waygraph auto` menus need `instanceOptions` that scan the live DOM (or mem) for labeled rows.
-4. Stubs: `stubBefore` / `stubAfter` / `stubOnError` for demo narration; YAP slides on Methods when useful; flow fixtures via `withHighlightFixtures` when AC copy is flow-specific.
-5. Mem: `requires` lists keys the block needs; seed via `--data` / `WAYGRAPH_DATA` / project defaults — never assume saucedemo creds for email keys.
-6. External Mailpit/MailHog: nav to inbox URL from env; Methods open message / click verify link; never put mail UI under `*-web/`.
+2. **One distinct action per Block - hard rule, not a style preference.** A Method/Effect that
+   fills form fields *and* submits, or that drives a multi-step sequence inside one `act()`,
+   is wrong even if it "works" - split it into separate atomic Blocks. Concretely: a login
+   form is `fill-username` (self-loop) + `fill-password` (self-loop) + `submit-login` (the
+   real transition), never one Block doing all three. See `examples/saucedemo/src/blocks/saucedemo-web/methods/`
+   (`fill-username.method.block.ts`, `fill-password.method.block.ts`,
+   `submit-login.method.block.ts`) for the canonical before/after shape - `submit-login`
+   used to also fill both fields; now it only clicks. A Block that only asserts something on
+   the current page (no state change) is `defineAssertBlock({ name, checkpoint, verify,
+   requires? })` - self-loop and `resolve` are generated for you, so there is no hand-written
+   `act`/`resolve` to accidentally make do two things. Give it an explicit type argument
+   (`defineAssertBlock<LoggedIn>({...})`) whenever it is not the last Block before `end` -
+   without one it defaults to wildcard `Checkpoint<string>`, which breaks `defineFlow`'s
+   tuple typing once the assert sits between two specifically-typed Blocks.
+3. Navigation only inside `defineNavBlock` / `defineNavClickBlock`. Regular Method/Effect `act` uses ActionPage (no goto).
+4. Effects that appear in `waygraph auto` menus need `instanceOptions` that scan the live DOM (or mem) for labeled rows.
+5. Stubs: `stubBefore` / `stubAfter` / `stubOnError` for demo narration; YAP slides on Methods when useful; flow fixtures via `withHighlightFixtures` when AC copy is flow-specific.
+6. Mem: `requires` lists keys the block needs; seed via `--data` / `WAYGRAPH_DATA` / project defaults - never assume saucedemo creds for email keys. A key an *earlier Block in the same chain* produces (not the caller) is never declared under `requires` - `requires` means externally supplied, and preflight checks the whole chain up front, before any Block runs.
+7. **External Mailpit/MailHog: nav to inbox URL from env; Methods open message / read or click
+   the link; never put mail UI under `*-web/`.** Read the message via `page.locator`/
+   `page.frameLocator` DOM calls, never the catcher's REST API - zero new engine surface, and
+   it's narratable in `waygraph demo`/`auto`. Live, proven reference:
+   `templates/scaffold/src/blocks/demo-external/mailpit/` + `mail-verify.flow.ts`. Match a
+   specific inbox row by a mem-supplied recipient, not inbox position (a shared inbox across
+   runs can hold mail for more than one recipient). **Build the mail-reading Blocks
+   scenario-agnostic from the start**, not one Block set per email type: put the
+   link-matching pattern and expected body copy in mem too (alongside the recipient), so the
+   same fixed Blocks serve signup confirmation, password reset, magic link, etc. - a Block
+   named for one scenario (`extract-verification-link`) is a sign it should instead be named
+   for its mechanism (`extract-email-link`) and driven by mem. For asserting the message
+   *body* content (not just that a link exists), the top-level page's own `Trait.text`/
+   `Trait.visible` cannot see inside the preview iframe at all - use `Trait.frameVisible`/
+   `Trait.frameText`/`Trait.frameContains` (or a bespoke mem-aware `{ name, check(page, mem) }`
+   Trait when the expected value itself must vary per run).
+8. `verify`/`defineAssertBlock` selectors live in a `*Sel` object next to the route, never
+   inlined as a literal string in `Trait.visible(...)`/`Trait.text(...)` - `waygraph check`
+   warns on this (see below); fix by moving the string into that route's `*Sel`.
 
 ## Verify locally
 
@@ -31,6 +63,12 @@ npx playwright test
 npm run auto        # or: npx waygraph auto --cli
 ```
 
+**Do not report this work done until `waygraph check .` shows zero orphan Blocks and zero
+inline-selector warnings, and zero nav-escape warnings for anything you touched.** A nonzero
+count in any of those three is not an informational note to mention and move past - it means
+go fix it first (wire the orphan into a `.flow.ts`, move the inline selector into `*Sel`, or
+move the escaping navigation into a `defineNavBlock`), then re-run `check`.
+
 ## Output
 
 Ship compiling TypeScript under `src/blocks/` + `src/flows/` + `src/states/`. Update NAV.md when edges change. Keep STRUCTURE / SITE-MAP honest.

package/templates/agents/waygraph-planner.agent.md

@@ -17,7 +17,12 @@ You are a waygraph planner. Your job is to dive an existing app and produce a SI
 3. **Block kinds:**
    - Nav — `defineNavBlock` / `defineNavClickBlock` — only place for `page.goto` / click-nav
    - Page — `definePageBlock` hub + `methods` registry
-   - Method — forms, asserts, same-URL actions without instance menus
+   - Method - one same-URL action (a single form field fill, a single submit/click) - never
+     "fill several fields and submit" in one Block; each of those is its own Method
+   - Assert - `defineAssertBlock` - a same-URL check with no state change (self-loop);
+     prefer this over a hand-written Method for pure assertions, since `resolve` is generated
+     for you. Accepts `requires` like every other helper, for a mem-aware Trait's externally
+     -supplied input.
    - Effect — `defineEffectBlock` + `instanceOptions` for per-row auto menus (add/remove/toggle)
 4. **Mem keys:** typed `key` / `keyGroup`. Never rely on substring `"login"` defaults — email keys like `login-email` stay strings; credential objects use exact names such as `saucedemo.credentials` / `login-credentials`.
 5. Prefer `click` NavBlocks when the product has a real control; use `url` for deep links / email tokens.
@@ -27,9 +32,35 @@ You are a waygraph planner. Your job is to dive an existing app and produce a SI
 1. Read the app router (Next.js `app/`, etc.) and list real page URLs.
 2. Draft `src/blocks/SITE-MAP.md` with namespaces + route folders.
 3. For each route: list nav-to edges, methods/effects, checkpoints, mem keys in `NAV.md` (plan only).
-4. Call out external surfaces (Mailpit inbox, magic-link verify) under `*-external/`.
+4. Call out external surfaces (Mailpit inbox, magic-link verify) under `*-external/`. Plan
+   these Blocks as reusable across every email-driven scenario the product has (signup
+   confirmation, password reset, magic link, ...) via mem (recipient, link pattern, expected
+   copy), not as a separate Block set per scenario - see
+   `templates/scaffold/src/blocks/demo-external/mailpit/` for the live, proven shape.
 5. Propose 1-3 starter flows (happy path, login/verify, one feature) — do not implement unless asked.
 
+## Blind mode (no frontend source)
+
+When there is no app codebase to read - a production target, or a deliberately
+codebase-blind engagement - discover the route/interaction structure live instead, using the
+`waygraph auto` session tools rather than skipping planning:
+
+1. `waygraph auto --cli --detach [--base-url <url>]` against a throwaway project dir (or the
+   target project once a `src/blocks/` tree exists) - starts a driveable session, prints
+   `{sessionId, socketPath}`.
+2. `waygraph auto status <sessionId>` to read the current menu (what Blocks/edges are already
+   discoverable) and `waygraph auto dom <sessionId>` (default `aria` mode) to see the live
+   page's actual interactive elements by role/name - this is how you find real routes and
+   controls without reading a single line of frontend source.
+3. `waygraph auto send <sessionId> "<pick>"` to move to the next screen once you know what is
+   there; repeat status/dom/send to walk the app and build the same SITE-MAP/NAV.md picture
+   step 1-4 above describe, just discovered live instead of read from source.
+4. `waygraph auto trace <sessionId>` at the end to get the Checkpoint/Block sequence you just
+   walked as a JSON record - useful as a starting outline for the flows step 5 asks for.
+5. `waygraph auto send <sessionId> q` to end the session when done exploring.
+
+Same output contract as sighted planning: a SITE-MAP/NAV.md plan, not implemented Blocks.
+
 ## Output
 
 Write/update markdown under `src/blocks/` (`SITE-MAP.md`, route `NAV.md` stubs). ASCII only. No localhost ports in shared docs.

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

@@ -16,11 +16,25 @@ Login page for Swag Labs. This folder is the namespace root (`/` in the browser)
 
 | File | Kind | Notes |
 |------|------|-------|
-| `methods/submit-login.method.block.ts` | Method | Form submit; branches LoggedIn vs LoginPage |
+| `methods/fill-username.method.block.ts` | Method | Fills username only; self-loop on LoginPage |
+| `methods/fill-password.method.block.ts` | Method | Fills password only; self-loop on LoginPage |
+| `methods/submit-login.method.block.ts` | Method | Click Login only; 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 |
+| `methods/login.sel.ts` | helper | `LoginSel` (not a Block) |
+
+Fill and submit are three separate Blocks (not one that fills both fields and
+clicks Login) so the graph/demo show each as its own step - no Block does
+more than one distinct action.
+
+## Other
+
+| File | Kind | Notes |
+|------|------|-------|
+| `ff-owner-auth.block.ts` | FFCompose | Collapses nav-login + fill-username + fill-password + submit-login into one opaque demo/run step (`--ff-expand` shows all 4 again) |
 
 ## Related mem keys / checkpoints
 
 - Mem: `saucedemo.credentials` (`LoginCreds`)
 - Checkpoints: `LoginPage`, `LoggedIn` (success path of submit-login)
+- Sel: `LoginSel` (`methods/login.sel.ts`) - DOM only, not mem

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

@@ -20,3 +20,4 @@ Shopping cart page and checkout entry.
 ## Related mem keys / checkpoints
 
 - Checkpoints: `CartPage`, `CheckoutInfoPage`, `ItemInCart` / `LoggedIn` (cart contents)
+- Sel: `CartSel` (`cart.sel.ts`) - DOM only, not mem

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

@@ -0,0 +1,9 @@
+/**
+ * DOM selectors for the cart route (`/cart.html`) and its outbound nav
+ * controls. Convention: DOM strings live in `*Sel` next to the page, not
+ * inlined in each Block.
+ */
+export const CartSel = {
+  cartLink: ".shopping_cart_link",
+  checkoutBtn: "#checkout",
+};

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

@@ -2,6 +2,7 @@ import { defineNavClickBlock, Trait } from "waygraph";
 import type { StubCtx } from "waygraph";
 import type { CartPage } from "../../../states/checkout.states.js";
 import { InventorySel } from "../inventory/methods/inventory-items.js";
+import { CartSel } from "./cart.sel.js";
 
 /**
  * Kind: Nav
@@ -14,29 +15,32 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   name: "nav-cart",
   description: "Clicks the cart link in the header.",
   checkpoint: "CartPage",
-  click: ".shopping_cart_link",
+  click: CartSel.cartLink,
   verify: [Trait.url({ pathname: "/cart.html" })],
   stubBefore: (ctx: StubCtx) => {
     ctx.title("Open cart · landscape");
-    // Device showcase: rotate tablet to landscape before the cart tap.
     ctx.landscape();
-    ctx.todoId("saucedemo-cart");
-    ctx.todos([
-      { id: "cart-find", text: "Find the product" },
-      { id: "cart-add", text: "Add to cart" },
-      { id: "cart-open", text: "Open cart" },
-    ]);
-    ctx.todoIndex(2);
+    ctx.todos(
+      "saucedemo",
+      [
+        { id: "login-user", text: "Enter username", done: true },
+        { id: "login-pass", text: "Enter password", done: true },
+        { id: "login-submit", text: "Tap Login", done: true },
+        { id: "cart-find", text: "Find the product", done: true },
+        { id: "cart-add", text: "Add to cart", done: true },
+        { id: "cart-open", text: "Open cart" },
+      ],
+      { title: "Device showcase", index: 5 },
+    );
     ctx.zoom(1.4);
     ctx.zoomOut(false);
     ctx.highlights({
       cart: {
-        selector: ".shopping_cart_link",
+        selector: CartSel.cartLink,
         label: "Cart",
-        detail: "Zoom cart chrome",
+        detail: "Open cart",
         focus: true,
         color: "#c9a6ff",
-        zoom: 1.55,
         zoomOut: false,
         followMouse: false,
         weight: "bold",
@@ -46,16 +50,16 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   },
   stubAfter: (ctx: StubCtx) => {
     ctx.banner("Your cart · desktop");
-    // Showcase finale: back to desktop.
     ctx.clearDevice();
-    ctx.zoomOut(false);
+    ctx.hideTodos();
+    ctx.zoomOut(true);
     ctx.ring("items", {
       selector: InventorySel.cartItem,
       label: "Cart items",
       detail: "Product landed in cart",
       focus: true,
       color: "#86efac",
-      zoom: 1.4,
+      zoomOut: true,
       followMouse: false,
       duration: true,
     });

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

@@ -1,5 +1,6 @@
 import { defineNavClickBlock, Trait } from "waygraph";
 import type { CheckoutInfoPage } from "../../../states/checkout.states.js";
+import { CartSel } from "./cart.sel.js";
 
 /**
  * Kind: Nav
@@ -12,6 +13,6 @@ export const NavCheckoutInfoBlock = defineNavClickBlock<CheckoutInfoPage>({
   name: "nav-checkout-info",
   description: "Clicks 'Checkout' on the cart page.",
   checkpoint: "CheckoutInfoPage",
-  click: "#checkout",
+  click: CartSel.checkoutBtn,
   verify: [Trait.url({ pathname: "/checkout-step-one.html" })],
 });

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

@@ -14,8 +14,13 @@ Shipping info form before order overview.
 
 | File | Kind | Notes |
 |------|------|-------|
-| `methods/submit-checkout-info.method.block.ts` | Method | Fill form + Continue -> overview |
+| `methods/fill-first-name.method.block.ts` | Method | Fills first name only; self-loop on CheckoutInfoPage |
+| `methods/fill-last-name.method.block.ts` | Method | Fills last name only; self-loop on CheckoutInfoPage |
+| `methods/fill-postal-code.method.block.ts` | Method | Fills postal code only; self-loop on CheckoutInfoPage |
+| `methods/submit-checkout-info.method.block.ts` | Method | Click Continue only -> overview |
+| `methods/checkout-info.sel.ts` | helper | `CheckoutInfoSel` (not a Block) |
 
 ## Related mem keys / checkpoints
 
 - Checkpoints: `CheckoutInfoPage`, `CheckoutOverviewPage`
+- Sel: `CheckoutInfoSel` (`methods/checkout-info.sel.ts`) - DOM only, not mem

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/methods/checkout-info.sel.ts

@@ -0,0 +1,11 @@
+/**
+ * DOM selectors for the shipping info form (`/checkout-step-one.html`).
+ * Convention: DOM strings live in `*Sel` next to the page, not inlined in
+ * each Block.
+ */
+export const CheckoutInfoSel = {
+  firstName: "#first-name",
+  lastName: "#last-name",
+  postalCode: "#postal-code",
+  continueBtn: "#continue",
+};

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.ts

@@ -0,0 +1,22 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { CheckoutInfoPage } from "../../../../states/checkout.states.js";
+import { CheckoutInfoSel } from "./checkout-info.sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/checkout-step-one/methods/  (= /checkout-step-one.html)
+ *
+ * Fills the first name field only - self-loop on CheckoutInfoPage. Continue
+ * is its own Block (submit-checkout-info.method.block.ts).
+ */
+export const FillFirstNameBlock = defineMethodBlock<CheckoutInfoPage, CheckoutInfoPage>({
+  name: "fill-first-name",
+  description: "Fills the first name field on the shipping info form.",
+  instruction: {
+    async act(page) {
+      await page.locator(CheckoutInfoSel.firstName).fill("Ada");
+    },
+    resolve: () => checkpoint("CheckoutInfoPage"),
+  },
+});

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.ts

@@ -0,0 +1,21 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { CheckoutInfoPage } from "../../../../states/checkout.states.js";
+import { CheckoutInfoSel } from "./checkout-info.sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/checkout-step-one/methods/  (= /checkout-step-one.html)
+ *
+ * Fills the last name field only - self-loop on CheckoutInfoPage.
+ */
+export const FillLastNameBlock = defineMethodBlock<CheckoutInfoPage, CheckoutInfoPage>({
+  name: "fill-last-name",
+  description: "Fills the last name field on the shipping info form.",
+  instruction: {
+    async act(page) {
+      await page.locator(CheckoutInfoSel.lastName).fill("Lovelace");
+    },
+    resolve: () => checkpoint("CheckoutInfoPage"),
+  },
+});

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.ts

@@ -0,0 +1,21 @@
+import { defineMethodBlock, checkpoint } from "waygraph";
+import type { CheckoutInfoPage } from "../../../../states/checkout.states.js";
+import { CheckoutInfoSel } from "./checkout-info.sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: saucedemo-web/checkout-step-one/methods/  (= /checkout-step-one.html)
+ *
+ * Fills the postal code field only - self-loop on CheckoutInfoPage.
+ */
+export const FillPostalCodeBlock = defineMethodBlock<CheckoutInfoPage, CheckoutInfoPage>({
+  name: "fill-postal-code",
+  description: "Fills the postal code field on the shipping info form.",
+  instruction: {
+    async act(page) {
+      await page.locator(CheckoutInfoSel.postalCode).fill("1000");
+    },
+    resolve: () => checkpoint("CheckoutInfoPage"),
+  },
+});

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.ts

@@ -1,23 +1,22 @@
 import { defineMethodBlock, checkpoint, Trait } from "waygraph";
 import type { CheckoutInfoPage, CheckoutOverviewPage } from "../../../../states/checkout.states.js";
+import { CheckoutInfoSel } from "./checkout-info.sel.js";
 
 /**
  * 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).
+ * Clicks Continue only - fields are filled by fill-first-name /
+ * fill-last-name / fill-postal-code (each its own Block). One Block, one
+ * action: submit.
  */
 export const SubmitCheckoutInfoBlock = defineMethodBlock<CheckoutInfoPage, CheckoutOverviewPage>({
   name: "submit-checkout-info",
-  description: "Fills in the shipping info form and continues to the order overview.",
+  description: "Continues from the shipping info form to the order overview.",
   instruction: {
     async act(page) {
-      await page.locator("#first-name").fill("Ada");
-      await page.locator("#last-name").fill("Lovelace");
-      await page.locator("#postal-code").fill("1000");
-      await page.locator("#continue").click();
+      await page.locator(CheckoutInfoSel.continueBtn).click();
     },
     resolve: () => checkpoint("CheckoutOverviewPage"),
     verify: [Trait.url({ pathname: "/checkout-step-two.html" })],

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

@@ -15,7 +15,9 @@ Order overview / finish page.
 | File | Kind | Notes |
 |------|------|-------|
 | `methods/finish-order.method.block.ts` | Method | Finish -> thank-you / OrderComplete |
+| `methods/checkout-overview.sel.ts` | helper | `CheckoutOverviewSel` (not a Block) |
 
 ## Related mem keys / checkpoints
 
 - Checkpoints: `CheckoutOverviewPage`, `OrderComplete`
+- Sel: `CheckoutOverviewSel` (`methods/checkout-overview.sel.ts`) - DOM only, not mem

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-two/methods/checkout-overview.sel.ts

@@ -0,0 +1,9 @@
+/**
+ * DOM selectors for the order overview / completion page
+ * (`/checkout-step-two.html`). Convention: DOM strings live in `*Sel` next
+ * to the page, not inlined in each Block.
+ */
+export const CheckoutOverviewSel = {
+  finishBtn: "#finish",
+  completeHeader: ".complete-header",
+};

package/templates/quickstart/src/blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.ts

@@ -1,5 +1,6 @@
 import { defineMethodBlock, checkpoint, Trait, narrate } from "waygraph";
 import type { CheckoutOverviewPage, OrderComplete } from "../../../../states/checkout.states.js";
+import { CheckoutOverviewSel } from "./checkout-overview.sel.js";
 
 /**
  * Kind: Method
@@ -13,17 +14,17 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
   description: "Places the order and confirms the 'Thank you for your order!' completion page.",
   instruction: {
     async act(page) {
-      const finishButton = page.locator("#finish");
+      const finishButton = page.locator(CheckoutOverviewSel.finishBtn);
       await narrate(finishButton, "Placing the order", () => finishButton.click());
     },
     resolve: () => checkpoint("OrderComplete"),
-    verify: [Trait.text(".complete-header", "Thank you for your order!")],
+    verify: [Trait.text(CheckoutOverviewSel.completeHeader, "Thank you for your order!")],
     stubBefore: {
-      finish: { selector: "#finish", label: "Finish" },
+      finish: { selector: CheckoutOverviewSel.finishBtn, label: "Finish" },
     },
     stubAfter: {
       thanks: {
-        selector: ".complete-header",
+        selector: CheckoutOverviewSel.completeHeader,
         label: "Order confirmed",
         detail: "Thank you for your order!",
         duration: true,
@@ -42,7 +43,7 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
         caption: "Completion page is the durable proof",
         detail: "The thank-you header is what verify asserts on.",
         tag: "YAP",
-        selector: ".complete-header",
+        selector: CheckoutOverviewSel.completeHeader,
         duration: 2500,
         fastMode: 700,
       },
@@ -50,7 +51,7 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
         caption: "Episode continues after this yap",
         detail: "Next step rings the same banner, then you move on.",
         tag: "YAP",
-        selector: ".complete-header",
+        selector: CheckoutOverviewSel.completeHeader,
         duration: true,
         fastMode: 500,
       },

package/templates/quickstart/src/blocks/saucedemo-web/ff-owner-auth.block.ts

@@ -1,5 +1,7 @@
 import { fastForwardComposeBlock } from "waygraph";
 import { NavLoginBlock } from "./nav-login.block.js";
+import { FillUsernameBlock } from "./methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "./methods/fill-password.method.block.js";
 import { SubmitLoginForFlow } from "./methods/submit-login-for-flow.js";
 
 /**
@@ -7,11 +9,14 @@ import { SubmitLoginForFlow } from "./methods/submit-login-for-flow.js";
  * Helper: fastForwardComposeBlock
  * Route: saucedemo-web/  (auth prefix)
  *
- * Collapses nav-login + submit-login into one opaque demo/run step so
- * checkout demos skip watching auth. Use --ff-expand to gate inners again.
+ * Collapses nav-login + fill-username + fill-password + submit-login into
+ * one opaque demo/run step so checkout demos skip watching auth. Use
+ * --ff-expand to gate inners again (they show as 4 separate steps).
  * loginFlow stays expanded for Sign In episode narration.
  */
 export const FfOwnerAuthBlock = fastForwardComposeBlock("ff-owner-auth", [
   NavLoginBlock,
+  FillUsernameBlock,
+  FillPasswordBlock,
   SubmitLoginForFlow,
 ]);

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

@@ -37,16 +37,20 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     // Demo: zoom product -> add (stay zoomed), then badge after act.
     stubBefore: (ctx: StubCtx) => {
       ctx.title("Pick a product · tablet");
-      // Device showcase: tablet portrait (toast + lerp from mobile landscape).
       ctx.device("tablet");
       ctx.portrait();
-      ctx.todoId("saucedemo-cart");
-      ctx.todos([
-        { id: "cart-find", text: "Find the product" },
-        { id: "cart-add", text: "Add to cart" },
-        { id: "cart-open", text: "Open cart" },
-      ]);
-      ctx.todoIndex(0);
+      ctx.todos(
+        "saucedemo",
+        [
+          { id: "login-user", text: "Enter username", done: true },
+          { id: "login-pass", text: "Enter password", done: true },
+          { id: "login-submit", text: "Tap Login", done: true },
+          { id: "cart-find", text: "Find the product" },
+          { id: "cart-add", text: "Add to cart" },
+          { id: "cart-open", text: "Open cart" },
+        ],
+        { title: "Device showcase", index: 3 },
+      );
       ctx.zoom(1.35);
       ctx.zoomOut(false);
       ctx.highlights({
@@ -72,13 +76,18 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     },
     stubAfter: (ctx: StubCtx) => {
       ctx.banner("In the cart");
-      ctx.todoId("saucedemo-cart");
-      ctx.todos([
-        { id: "cart-find", text: "Find the product" },
-        { id: "cart-add", text: "Add to cart" },
-        { id: "cart-open", text: "Open cart" },
-      ]);
-      ctx.todoIndex(1);
+      ctx.todos(
+        "saucedemo",
+        [
+          { id: "login-user", text: "Enter username", done: true },
+          { id: "login-pass", text: "Enter password", done: true },
+          { id: "login-submit", text: "Tap Login", done: true },
+          { id: "cart-find", text: "Find the product", done: true },
+          { id: "cart-add", text: "Add to cart" },
+          { id: "cart-open", text: "Open cart" },
+        ],
+        { title: "Device showcase", index: 4 },
+      );
       ctx.zoomOut(false);
       ctx.ring("badge", {
         selector: InventorySel.cartBadge,
@@ -86,7 +95,6 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
         detail: "Item count updated",
         focus: true,
         color: "#86efac",
-        zoom: 1.6,
         zoomOut: false,
         duration: true,
       });