waygraph 0.13.7 → 0.15.0

package/examples/saucedemo/docs/CONVENTION.md

@@ -1,7 +1,21 @@
 # saucedemo waygraph conventions
 
-Atomic Blocks - one nav / effect / method per real URL or on-page mutation so
-`waygraph auto` can discover a real state graph (not a fat multi-page Block).
+**How this maps to the app:** navigate to the site -> you land on a `Page` Block
+(the screen hub) -> every Method/Effect/Nav that screen can do hangs off that
+Page. Each Block does exactly **one** distinct action - never two or more
+bundled together. Filling a form field and submitting it are two different
+actions, so they are two different Blocks, even on the same screen:
+`fill-username` / `fill-password` (self-loop Methods, no checkpoint change) and
+`submit-login` (the real transition) are three real Blocks, not one Method
+that "inputs username and password and logs in at the same time." The same
+split applies to `fill-first-name` / `fill-last-name` / `fill-postal-code` /
+`submit-checkout-info` on the shipping form.
+
+This is what makes `waygraph auto`/`traverse` see a clean, honest graph of the
+app: every real user-visible action is its own edge, and no Block silently
+"teleports" the user past several actions at once. It is also why a
+`page.goto()` (or NavBlock `click`) never appears anywhere except inside a
+`defineNavBlock`/`defineNavClickBlock` - see `waygraph check` below.
 
 **TypeScript salt only.** Helpers force a useful shape. At runtime everything is
 still a `Block` - there is no separate Page / Effect / Nav engine.
@@ -33,9 +47,12 @@ src/blocks/
   SITE-MAP.md
   saucedemo-web/                 # THIS FOLDER IS URL "/"
     NAV.md
-    nav-login.block.ts
+    nav-login.block.ts             # Page hub
+    ff-owner-auth.block.ts         # FFCompose wrapping the 4 Blocks below
     methods/
-      submit-login.method.block.ts
+      fill-username.method.block.ts   # self-loop, fills only
+      fill-password.method.block.ts   # self-loop, fills only
+      submit-login.method.block.ts    # click only, branches
       submit-login-for-flow.ts
       submit-logout.method.block.ts
     inventory/                   # /inventory.html
@@ -58,7 +75,10 @@ src/blocks/
     checkout-step-one/           # /checkout-step-one.html
       NAV.md
       methods/
-        submit-checkout-info.method.block.ts
+        fill-first-name.method.block.ts    # self-loop, fills only
+        fill-last-name.method.block.ts     # self-loop, fills only
+        fill-postal-code.method.block.ts   # self-loop, fills only
+        submit-checkout-info.method.block.ts  # click only
     checkout-step-two/           # /checkout-step-two.html
       NAV.md
       methods/

package/examples/saucedemo/docs/HELPERS.md

@@ -8,13 +8,24 @@ Runtime is always a `Block`. Helpers are TypeScript salt + clear intent.
 | `defineNavBlock` | URL / `goto` only | `nav-*.block.ts` |
 | `defineNavClickBlock` | Click-to-navigate only | `nav-*.block.ts` |
 | `defineMemNavBlock` | Nav + per-row `instanceOptions` | `nav-*.block.ts` |
-| `defineMethodBlock` | One-shot non-nav app step | `*.method.block.ts` under `methods/` |
+| `defineMethodBlock` | One-shot non-nav app step, exactly one action | `*.method.block.ts` under `methods/` |
+| `defineAssertBlock` | Self-loop assertion, no state change - `verify` only | `*.method.block.ts` under `methods/` |
 | `defineEffectBlock` | Instance mutate + auto menu rows | `*.effect.block.ts` under `methods/` |
 | `defineBlock` | Escape hatch: tests, unsure, probes | any |
-| `defineActionBlock` | **Deprecated** alias of `defineMethodBlock` | — |
+| `defineActionBlock` | **Deprecated** alias of `defineMethodBlock` | - |
 
 `defineNavBlock({ click })` still works (compat) - prefer `defineNavClickBlock` in app code.
 
+**One distinct action per Block.** A Method that fills fields *and* submits is wrong even if
+it "works" - split it (`fill-username` + `fill-password` + `submit-login`, not one Block).
+`defineAssertBlock({ name, checkpoint, verify, waitForHeading?, requires? })` is the
+self-loop-only shape for "assert something on the current page, no state change" - no
+hand-written `act`/`resolve` to accidentally make do two things. `waygraph check` warns when
+a `verify` array inlines a literal selector string instead of a `*Sel` reference. Give it an
+explicit type argument (`defineAssertBlock<LoggedIn>({...})`) whenever it is not the last
+Block before `end` - otherwise `Out` defaults to wildcard `Checkpoint<string>`, which breaks
+`defineFlow`'s tuple typing mid-chain.
+
 ---
 
 ## Page hub + methods + Sel
@@ -76,7 +87,7 @@ Conditional Out (no `branch()` needed for auto/graph):
 defineMethodBlock<LoginPage, LoggedIn | LoginPage>({
   name: "submit-login",
   instruction: {
-    async act(page, _in, mem) { /* fill + click */ },
+    async act(page) { /* click only - fields were filled by earlier Blocks */ },
     async observe(page) {
       try {
         await page.waitForURL(/\/inventory\.html/, { timeout: 8000 });
@@ -93,7 +104,7 @@ defineMethodBlock<LoginPage, LoggedIn | LoginPage>({
 Optional routing for `runGraph`:
 
 ```ts
-branch(SubmitLoginActionBlock, {
+branch(SubmitLoginBlock, {
   LoggedIn: AddToCartBlock,
   LoginPage: null, // stop
 });

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

@@ -87,7 +87,13 @@ const { graph, library } = await buildExploreContext(root);
 const nodeNames = graph.nodes.map((n) => n.checkpoint);
 
 const { NavLoginBlock } = await import(pathToFileURL(join(root, "src/blocks/saucedemo-web/nav-login.block.js")).href);
-const { SubmitLoginActionBlock } = await import(
+const { FillUsernameBlock } = await import(
+  pathToFileURL(join(root, "src/blocks/saucedemo-web/methods/fill-username.method.block.js")).href
+);
+const { FillPasswordBlock } = await import(
+  pathToFileURL(join(root, "src/blocks/saucedemo-web/methods/fill-password.method.block.js")).href
+);
+const { SubmitLoginBlock } = await import(
   pathToFileURL(join(root, "src/blocks/saucedemo-web/methods/submit-login.method.block.js")).href
 );
 const { LoginCreds } = await import(pathToFileURL(join(root, "src/states/checkout.mem-keys.js")).href);
@@ -111,7 +117,7 @@ await paintPanel(page, menuBefore, nodeNames, library.byName, "Mem: standard_use
 await snap(page, "wrong-login-1-before.png");
 
 mem.set(LoginCreds({ username: "standard_user", password: "wrong-password" }));
-const flow = engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]);
+const flow = engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]);
 const runOut = await flow.run(context, mem, { page, closeOnFinish: false });
 const result = runOut && typeof runOut === "object" && "result" in runOut ? runOut.result : runOut;
 

package/examples/saucedemo/scripts/prove-wrong-login-runtime.mjs

@@ -14,7 +14,13 @@ const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const waygraphDist = join(root, "../../dist");
 const { Engine, start, end, MemPage } = await import(pathToFileURL(join(waygraphDist, "index.js")).href);
 const { NavLoginBlock } = await import(pathToFileURL(join(root, "src/blocks/saucedemo-web/nav-login.block.js")).href);
-const { SubmitLoginActionBlock } = await import(
+const { FillUsernameBlock } = await import(
+  pathToFileURL(join(root, "src/blocks/saucedemo-web/methods/fill-username.method.block.js")).href
+);
+const { FillPasswordBlock } = await import(
+  pathToFileURL(join(root, "src/blocks/saucedemo-web/methods/fill-password.method.block.js")).href
+);
+const { SubmitLoginBlock } = await import(
   pathToFileURL(join(root, "src/blocks/saucedemo-web/methods/submit-login.method.block.js")).href
 );
 const { LoginCreds } = await import(pathToFileURL(join(root, "src/states/checkout.mem-keys.js")).href);
@@ -35,7 +41,7 @@ const engine = new Engine({ headless: true });
 const mem = new MemPage();
 mem.set(LoginCreds({ username: "standard_user", password: "wrong-password" }));
 
-const flow = engine.defineFlow([start, NavLoginBlock, SubmitLoginActionBlock, end]);
+const flow = engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]);
 const runOut = await flow.run(context, mem, { page, closeOnFinish: false });
 const result = runOut && typeof runOut === "object" && "result" in runOut ? runOut.result : runOut;
 

package/examples/saucedemo/src/blocks/SITE-MAP.md

@@ -8,11 +8,15 @@ src/blocks/
   SITE-MAP.md
   saucedemo-web/                      # URL /
     NAV.md
-    nav-login.block.ts                # Nav  defineNavBlock url:/
+    nav-login.block.ts                # Page  definePageBlock url:/
+    ff-owner-auth.block.ts            # FFCompose (nav-login + fill-username + fill-password + submit-login)
     methods/
-      submit-login.method.block.ts    # Method defineMethodBlock
+      fill-username.method.block.ts   # Method defineMethodBlock (self-loop on LoginPage)
+      fill-password.method.block.ts   # Method defineMethodBlock (self-loop on LoginPage)
+      submit-login.method.block.ts    # Method defineMethodBlock (click only; branches)
       submit-login-for-flow.ts        # helper (not a discoverable *.block.ts alone)
       submit-logout.method.block.ts   # Method defineMethodBlock
+      login.sel.ts                    # LoginSel (not a Block)
     inventory/                        # URL /inventory.html
       inventory.page.block.ts       # Page definePageBlock
       NAV.md
@@ -25,20 +29,27 @@ src/blocks/
         remove-from-cart.effect.block.ts
     inventory-item/                   # URL /inventory-item.html
       NAV.md
+      item-detail.sel.ts              # ItemDetailSel (not a Block)
       nav-continue-shopping.block.ts
       nav-back-to-products.block.ts
       nav-back-to-inventory.block.ts
     cart/                             # URL /cart.html
       NAV.md
+      cart.sel.ts                     # CartSel (not a Block)
       nav-cart.block.ts               # Nav click header cart
       nav-checkout-info.block.ts
     checkout-step-one/                # URL /checkout-step-one.html
       NAV.md
       methods/
-        submit-checkout-info.method.block.ts
+        checkout-info.sel.ts               # CheckoutInfoSel (not a Block)
+        fill-first-name.method.block.ts    # Method defineMethodBlock (self-loop on CheckoutInfoPage)
+        fill-last-name.method.block.ts     # Method defineMethodBlock (self-loop on CheckoutInfoPage)
+        fill-postal-code.method.block.ts   # Method defineMethodBlock (self-loop on CheckoutInfoPage)
+        submit-checkout-info.method.block.ts  # Method defineMethodBlock (click only)
     checkout-step-two/                # URL /checkout-step-two.html
       NAV.md
       methods/
+        checkout-overview.sel.ts      # CheckoutOverviewSel (not a Block)
         finish-order.method.block.ts
 ```
 

package/examples/saucedemo/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/examples/saucedemo/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/examples/saucedemo/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",
+};