waygraph 0.13.7 → 0.15.0

package/examples/saucedemo/src/blocks/saucedemo-web/nav-login.block.ts

@@ -1,23 +1,31 @@
 import { definePageBlock, Trait } from "waygraph";
 import type { LoginPage } from "../../states/checkout.states.js";
-import { SubmitLoginActionBlock } from "./methods/submit-login.method.block.js";
+import { FillUsernameBlock } from "./methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "./methods/fill-password.method.block.js";
+import { SubmitLoginBlock } from "./methods/submit-login.method.block.js";
+import { LoginSel } from "./methods/login.sel.js";
 
 /**
  * Kind: Page
  * Helper: definePageBlock
  * Route: saucedemo-web/  (= /)
  *
- * Login screen hub. Deep-link via url; method submit-login hangs off this
- * page (stubBefore/stubAfter todos live on the Method). Name stays
- * `nav-login` so existing flows / chain specs keep working.
+ * Login screen hub. Deep-link via url; fill-username / fill-password /
+ * submit-login hang off this page as three atomic Methods - fill-* are
+ * self-loops (LoginPage -> LoginPage), submit-login owns the one real
+ * transition (LoginPage -> LoggedIn|LoginPage). No single Block both fills
+ * and submits. Name stays `nav-login` so existing flows / chain specs keep
+ * working.
  */
 export const NavLoginBlock = definePageBlock<LoginPage>({
   name: "nav-login",
   description: "Goes to the Swag Labs login page.",
   checkpoint: "LoginPage",
   url: "/",
-  verify: [Trait.visible("#login-button")],
+  verify: [Trait.visible(LoginSel.loginButton)],
   methods: {
-    submitLogin: () => SubmitLoginActionBlock,
+    fillUsername: () => FillUsernameBlock,
+    fillPassword: () => FillPasswordBlock,
+    submitLogin: () => SubmitLoginBlock,
   },
 });

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

@@ -9,10 +9,15 @@ import type {
   OrderComplete,
 } from "../states/checkout.states.js";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.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 { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
+import { FillFirstNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.js";
+import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.js";
+import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 import { NavBackToProductsBlock } from "../blocks/saucedemo-web/inventory-item/nav-back-to-products.block.js";
@@ -23,21 +28,31 @@ const engine = new Engine({ headless: false, slowMo: 250 });
 // (proves OrderComplete -> LoggedIn without a goto teleport).
 export const checkoutThenBrowseAgainFlow = withTitle(
   engine.defineFlow<
+    LoginPage,
+    LoginPage,
     LoginPage,
     LoggedIn,
     ItemInCart,
     CartPage,
     CheckoutInfoPage,
+    CheckoutInfoPage,
+    CheckoutInfoPage,
+    CheckoutInfoPage,
     CheckoutOverviewPage,
     OrderComplete,
     LoggedIn
   >([
     start,
     NavLoginBlock,
+    FillUsernameBlock,
+    FillPasswordBlock,
     SubmitLoginForFlow,
     AddToCartBlock,
     NavCartBlock,
     NavCheckoutInfoBlock,
+    FillFirstNameBlock,
+    FillLastNameBlock,
+    FillPostalCodeBlock,
     SubmitCheckoutInfoBlock,
     FinishOrderBlock,
     NavBackToProductsBlock,

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

@@ -11,6 +11,9 @@ import { FfOwnerAuthBlock } from "../blocks/saucedemo-web/ff-owner-auth.block.js
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
+import { FillFirstNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.js";
+import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.js";
+import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 
@@ -32,6 +35,9 @@ export const checkoutFlow = withHighlightFixtures(
       ItemInCart,
       CartPage,
       CheckoutInfoPage,
+      CheckoutInfoPage,
+      CheckoutInfoPage,
+      CheckoutInfoPage,
       CheckoutOverviewPage,
       OrderComplete
     >([
@@ -40,6 +46,9 @@ export const checkoutFlow = withHighlightFixtures(
       AddToCartBlock,
       NavCartBlock,
       NavCheckoutInfoBlock,
+      FillFirstNameBlock,
+      FillLastNameBlock,
+      FillPostalCodeBlock,
       SubmitCheckoutInfoBlock,
       FinishOrderBlock,
       end,
@@ -57,8 +66,9 @@ export const checkoutFlow = withHighlightFixtures(
         },
       },
     },
-    // Kept for --ff-expand (inners become separate steps again).
-    "submit-login": {
+    // Kept for --ff-expand (inners become separate steps again: nav-login,
+    // fill-username, fill-password, submit-login).
+    "fill-username": {
       stubBefore: {
         username: {
           label: "Demo user",
@@ -66,7 +76,15 @@ export const checkoutFlow = withHighlightFixtures(
           tag: "AC",
           duration: true,
         },
+      },
+    },
+    "fill-password": {
+      stubBefore: {
         password: { label: "Password", detail: "Filled from Mem credentials.", duration: 1500 },
+      },
+    },
+    "submit-login": {
+      stubBefore: {
         submit: { label: "Sign in", tag: "GATE", duration: true, fastMode: 500 },
       },
     },

package/examples/saucedemo/src/flows/device-showcase.flow.ts

@@ -1,5 +1,7 @@
 import { Engine, start, end, withTitle } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.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 { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
@@ -19,6 +21,8 @@ export const deviceShowcaseFlow = withTitle(
   engine.defineFlow([
     start,
     NavLoginBlock,
+    FillUsernameBlock,
+    FillPasswordBlock,
     SubmitLoginForFlow,
     AddToCartBlock,
     NavCartBlock,

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

@@ -1,5 +1,7 @@
 import { Engine, start, end, withTitle } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.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 { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 
 const engine = new Engine();
@@ -7,6 +9,6 @@ const engine = new Engine();
 // The step-mode overlay prepends "Episode N: " itself - the title here is
 // just the label, not the full heading.
 export const loginFlow = withTitle(
-  engine.defineFlow([start, NavLoginBlock, SubmitLoginForFlow, end]),
+  engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginForFlow, end]),
   "Sign In",
 );

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

@@ -2,6 +2,9 @@ import { Engine, start, end, withTitle } from "waygraph";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
+import { FillFirstNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-first-name.method.block.js";
+import { FillLastNameBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-last-name.method.block.js";
+import { FillPostalCodeBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/fill-postal-code.method.block.js";
 import { SubmitCheckoutInfoBlock } from "../blocks/saucedemo-web/checkout-step-one/methods/submit-checkout-info.method.block.js";
 import { FinishOrderBlock } from "../blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.js";
 
@@ -15,6 +18,9 @@ export const shopFlow = withTitle(
     AddToCartBlock,
     NavCartBlock,
     NavCheckoutInfoBlock,
+    FillFirstNameBlock,
+    FillLastNameBlock,
+    FillPostalCodeBlock,
     SubmitCheckoutInfoBlock,
     FinishOrderBlock,
     end,

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

@@ -1,6 +1,8 @@
 import { Engine, start, end } from "waygraph";
 import type { LoginPage, LoggedIn, ItemInCart } from "../states/checkout.states.js";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
+import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
+import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
 import { SubmitLoginForFlow } from "../blocks/saucedemo-web/methods/submit-login-for-flow.js";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 
@@ -10,17 +12,21 @@ const engine = new Engine();
 // it doesn't need the same DOM confirmation the real checkout.flow.ts wants.
 // Same Blocks, same act/resolve, zero duplication - only verify differs.
 // .withVerify([]) reads from the Block itself, discoverable by typing
-// "NavLoginBlock."/"SubmitLoginActionBlock." in an editor - not a free function
+// "NavLoginBlock."/"SubmitLoginForFlow." in an editor - not a free function
 // you have to already know exists.
 //
-// Explicit <LoginPage, LoggedIn, ItemInCart> here - AddToCartBlock's In is now
-// the wildcard Checkpoint<string> (it's reused as shopFlow's own entry block
-// too), and inferring B/C/D purely from three chained .withVerify([]) calls in
-// one array trips TS's overload resolution into unifying the wrong Out type
-// partway through; pinning the type args sidesteps it rather than fighting it.
-export const smokeFlow = engine.defineFlow<LoginPage, LoggedIn, ItemInCart>([
+// Explicit <LoginPage, LoginPage, LoginPage, LoggedIn, ItemInCart> here -
+// AddToCartBlock's In is now the wildcard Checkpoint<string> (it's reused as
+// shopFlow's own entry block too), and inferring the chain purely from
+// several chained .withVerify([]) calls in one array trips TS's overload
+// resolution into unifying the wrong Out type partway through; pinning the
+// type args sidesteps it rather than fighting it. The two middle `LoginPage`
+// entries are fill-username / fill-password (self-loop Methods).
+export const smokeFlow = engine.defineFlow<LoginPage, LoginPage, LoginPage, LoggedIn, ItemInCart>([
   start,
   NavLoginBlock.withVerify([]),
+  FillUsernameBlock,
+  FillPasswordBlock,
   SubmitLoginForFlow.withVerify([]),
   AddToCartBlock.withVerify([]),
   end,

package/examples/saucedemo/src/flows/stub-on-error.flow.ts

@@ -9,7 +9,9 @@ import {
   Trait,
 } 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();
 
@@ -23,7 +25,7 @@ const engine = new Engine();
  */
 const forcedInventoryVerify = withSessionReset(
   engine
-    .defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end])
+    .defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end])
     .withBlockVerify("submit-login", [Trait.url({ pathname: "/inventory.html" })]),
 );
 

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.7",
+  "version": "0.15.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",
+};