waygraph 0.7.11 → 0.7.13

package/templates/quickstart/docs/CONVENTION.md

@@ -1,42 +1,64 @@
 # saucedemo waygraph conventions
 
-Atomic nav/action blocks, same split `zsign-atomic-waygraph` uses - one nav
-(or action) per real URL / `page.tsx`-equivalent endpoint so `waygraph auto`
-can discover a real state graph (not a fat multi-page Block).
+Atomic Blocks - one nav / effect / action per real URL or on-page mutation so
+`waygraph auto` can discover a real state graph (not a fat multi-page Block).
 
-**Multi-route consumers:** folder layout must mirror Next.js `app/` page routes —
-see `.sm/seats/_shared/WAYGRAPH-CONSUMER-CONVENTION.md` and
-`../zsign-atomic-waygraph/docs/CONVENTION.md` (no invented `root/`, `landing/`, or
+**TypeScript salt only.** `defineNavBlock`, `defineEffectBlock`, and plain
+`defineBlock` are helpers that force a useful shape. At runtime everything is
+still a `Block` - there is no separate Effect or Nav engine.
+
+**Multi-route consumers:** folder layout must mirror Next.js `app/` page routes -
+see package docs `docs/consumer.html` (no invented `root/`, `landing/`, or
 `shell/nav/*` families; `/` lives at the namespace root).
 
-## Block kinds
+## Block kinds (file convention)
 
-| Kind | File | `page.goto`? |
-|------|------|--------------|
-| Nav | `nav-*.block.ts` at `src/blocks/` root, built with `defineNavBlock` | Yes (`url` XOR `click`) |
-| Action | `*.action.block.ts` in `src/blocks/actions/` | No |
+| Kind | File | Helper | `page.goto`? |
+|------|------|--------|--------------|
+| Nav | `nav-*.block.ts` | `defineNavBlock` / `defineMemNavBlock` | Yes (`url` XOR `click`) |
+| Effect | `*.effect.block.ts` | `defineEffectBlock` | No - mutates a live instance (add/remove/toggle) via mem + `instanceOptions` |
+| Action | `*.action.block.ts` | `defineBlock` | No - forms, submit, logout, etc. |
 
 Only an explicit `page.goto()` (or NavBlock `click`) counts as navigation - an
-action that fills a form and continues stays an action even when the app
-changes URL as a side effect of `#continue`.
+action/effect that fills a form or clicks a button stays non-nav even when the
+app changes URL as a side effect of `#continue`.
 
 ## Layout
 
 ```text
 src/blocks/
-  nav-login.block.ts
-  nav-cart.block.ts
-  nav-checkout-info.block.ts
-  nav-item-detail.block.ts
-  nav-back-to-inventory.block.ts
-  nav-continue-shopping.block.ts
-  nav-back-to-products.block.ts
-  actions/
-    submit-login.action.block.ts
-    add-to-cart.effect.block.ts
-    submit-checkout-info.action.block.ts
-    finish-order.action.block.ts
-    submit-logout.action.block.ts
+  SITE-MAP.md
+  saucedemo-web/                 # THIS FOLDER IS URL "/"
+    NAV.md
+    nav-login.block.ts
+    actions/
+      submit-login.action.block.ts
+      submit-login-for-flow.ts
+      submit-logout.action.block.ts
+    inventory/                   # /inventory.html
+      NAV.md
+      nav-item-detail.block.ts
+      actions/
+        inventory-items.ts
+        add-to-cart.effect.block.ts
+        remove-from-cart.effect.block.ts
+    inventory-item/              # /inventory-item.html
+      NAV.md
+      nav-continue-shopping.block.ts
+      nav-back-to-products.block.ts
+      nav-back-to-inventory.block.ts
+    cart/                        # /cart.html
+      NAV.md
+      nav-cart.block.ts
+      nav-checkout-info.block.ts
+    checkout-step-one/           # /checkout-step-one.html
+      NAV.md
+      actions/
+        submit-checkout-info.action.block.ts
+    checkout-step-two/           # /checkout-step-two.html
+      NAV.md
+      actions/
+        finish-order.action.block.ts
 src/states/
 src/flows/
 ```

package/templates/quickstart/package.json

@@ -19,7 +19,7 @@
     "baseUrl": "https://www.saucedemo.com"
   },
   "dependencies": {
-    "waygraph": "^0.7.11"
+    "waygraph": "^0.7.13"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

package/templates/quickstart/src/blocks/SITE-MAP.md

@@ -0,0 +1,43 @@
+# SITE-MAP - Sauce Demo blocks
+
+Namespace `saucedemo-web/` is URL `/` for [saucedemo.com](https://www.saucedemo.com).
+Route folders mirror real Swag Labs paths (consumer convention).
+
+```text
+src/blocks/
+  SITE-MAP.md
+  saucedemo-web/                      # URL /
+    NAV.md
+    nav-login.block.ts                # Nav  defineNavBlock url:/
+    actions/
+      submit-login.action.block.ts    # Action defineBlock
+      submit-login-for-flow.ts        # helper (not a discoverable *.block.ts alone)
+      submit-logout.action.block.ts   # Action
+    inventory/                        # URL /inventory.html
+      NAV.md
+      nav-item-detail.block.ts        # Nav  defineMemNavBlock (instance row)
+      actions/
+        inventory-items.ts            # DOM helpers for Effects (not a Block)
+        add-to-cart.effect.block.ts   # Effect defineEffectBlock
+        remove-from-cart.effect.block.ts
+    inventory-item/                   # URL /inventory-item.html
+      NAV.md
+      nav-continue-shopping.block.ts
+      nav-back-to-products.block.ts
+      nav-back-to-inventory.block.ts
+    cart/                             # URL /cart.html
+      NAV.md
+      nav-cart.block.ts               # Nav click header cart
+      nav-checkout-info.block.ts
+    checkout-step-one/                # URL /checkout-step-one.html
+      NAV.md
+      actions/
+        submit-checkout-info.action.block.ts
+    checkout-step-two/                # URL /checkout-step-two.html
+      NAV.md
+      actions/
+        finish-order.action.block.ts
+```
+
+Checkpoints and mem keys live under `src/states/`. Flows under `src/flows/`
+compose Blocks into episodes for `waygraph demo` / Playwright.

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

@@ -0,0 +1,26 @@
+# saucedemo-web/ - URL `/`
+
+Login page for Swag Labs. This folder is the namespace root (`/` in the browser).
+
+## URL
+
+- `/` (login form)
+
+## Nav blocks
+
+| File | Helper | Notes |
+|------|--------|-------|
+| `nav-login.block.ts` | `defineNavBlock` | `url: "/"` - only goto onto login |
+
+## Effects / actions
+
+| 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 |
+
+## Related mem keys / checkpoints
+
+- Mem: `saucedemo.credentials` (`LoginCreds`)
+- Checkpoints: `LoginPage`, `LoggedIn` (success path of submit-login)

package/templates/quickstart/src/blocks/saucedemo-web/actions/submit-login-for-flow.ts

@@ -0,0 +1,13 @@
+import type { DefinedBlock } from "waygraph";
+import type { LoginPage, LoggedIn } from "../../../states/checkout.states.js";
+import { SubmitLoginActionBlock } from "./submit-login.action.block.js";
+
+/**
+ * Kind: helper (not a discoverable Block file)
+ * Helper: typed alias over SubmitLoginActionBlock
+ * Route: saucedemo-web/actions/  (page URL /)
+ *
+ * DefinedBlock cast so linear Flows can chain .withVerify on Out=LoggedIn;
+ * runtime still branches on bad credentials via SubmitLoginActionBlock.
+ */
+export const SubmitLoginForFlow = SubmitLoginActionBlock as unknown as DefinedBlock<LoginPage, LoggedIn>;

package/templates/quickstart/src/blocks/{actions → saucedemo-web/actions}/submit-login.action.block.ts

@@ -1,15 +1,17 @@
 import { defineBlock, checkpoint, Trait } from "waygraph";
-import type { LoginPage, LoginSubmitOutcome } from "../../states/checkout.states.js";
-import { LoginCreds } from "../../states/checkout.mem-keys.js";
+import type { LoginPage, LoginSubmitOutcome } from "../../../states/checkout.states.js";
+import { LoginCreds } from "../../../states/checkout.mem-keys.js";
 
 type LoginObserve = "success" | "failure";
 
-// Fills credentials on the login page and submits - never navigates (nav-login.block.ts
-// does that). Port of the old login.block.ts with the goto split out.
-//
-// Branches on real auth outcome: good creds -> LoggedIn; bad creds / locked user ->
-// LoginPage (error banner visible). waygraph auto stays on LoginPage instead of
-// pretending the run reached inventory.
+/**
+ * Kind: Action
+ * Helper: defineBlock
+ * Route: saucedemo-web/actions/  (page URL /)
+ *
+ * Fills credentials and submits - never page.goto (nav-login owns that).
+ * Branches: good creds -> LoggedIn; bad/locked -> LoginPage with error banner.
+ */
 export const SubmitLoginActionBlock = defineBlock<LoginPage, LoginSubmitOutcome>({
   name: "submit-login",
   description: "Logs a user in when credentials are valid; stays on LoginPage when auth fails.",
@@ -19,11 +21,13 @@ export const SubmitLoginActionBlock = defineBlock<LoginPage, LoginSubmitOutcome>
       const { username, password } = mem.get(LoginCreds.key);
       await page.locator("#user-name").fill(username);
       await page.locator("#password").fill(password);
-      await page.locator("#login-button").click();
+      // noWaitAfter: observe owns the inventory URL wait. Default click
+      // navigation-wait can hang under waygraph auto's demo cursor patch.
+      await page.locator("#login-button").click({ noWaitAfter: true });
     },
     async observe(page): Promise<LoginObserve> {
       try {
-        await page.waitForURL(/\/inventory\.html/, { timeout: 5_000 });
+        await page.waitForURL(/\/inventory\.html/, { timeout: 8_000 });
         return "success";
       } catch {
         return "failure";

package/{examples/saucedemo/src/blocks → templates/quickstart/src/blocks/saucedemo-web}/actions/submit-logout.action.block.ts

@@ -1,8 +1,13 @@
 import { defineBlock, checkpoint, Trait } from "waygraph";
-import type { LoggedIn, LoginPage } from "../../states/checkout.states.js";
+import type { LoggedIn, LoginPage } from "../../../states/checkout.states.js";
 
-// Opens the burger menu and clicks Logout - completes the graph's own real
-// cycle back to LoginPage, the same Checkpoint nav-login.block.ts lands on.
+/**
+ * Kind: Action
+ * Helper: defineBlock
+ * Route: saucedemo-web/actions/  (page URL / after logout)
+ *
+ * Burger menu Logout - real cycle back to LoginPage (same Checkpoint nav-login lands on).
+ */
 export const SubmitLogoutBlock = defineBlock<LoggedIn, LoginPage>({
   name: "submit-logout",
   description: "Opens the burger menu and logs out.",

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

@@ -0,0 +1,22 @@
+# cart/ - URL `/cart.html`
+
+Shopping cart page and checkout entry.
+
+## URL
+
+- `/cart.html`
+
+## Nav blocks
+
+| File | Helper | Notes |
+|------|--------|-------|
+| `nav-cart.block.ts` | `defineNavBlock` | Header cart link (`click`, not url) |
+| `nav-checkout-info.block.ts` | `defineNavBlock` | "Checkout" button -> step one |
+
+## Effects / actions
+
+(none on this route; cart mutations live under `inventory/actions/`)
+
+## Related mem keys / checkpoints
+
+- Checkpoints: `CartPage`, `CheckoutInfoPage`, `ItemInCart` / `LoggedIn` (cart contents)

package/{examples/saucedemo/src/blocks → templates/quickstart/src/blocks/saucedemo-web/cart}/nav-cart.block.ts

@@ -1,8 +1,13 @@
 import { defineNavBlock, Trait } from "waygraph";
-import type { CartPage } from "../states/checkout.states.js";
+import type { CartPage } from "../../../states/checkout.states.js";
 
-// click, not url - the real "Cart" link in the page header, clickable from
-// any inventory-adjacent page (with or without an item already added).
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: saucedemo-web/cart/  (= /cart.html)
+ *
+ * click, not url - header cart link from inventory-adjacent pages.
+ */
 export const NavCartBlock = defineNavBlock<CartPage>({
   name: "nav-cart",
   description: "Clicks the cart link in the header.",

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

@@ -1,6 +1,13 @@
 import { defineNavBlock, Trait } from "waygraph";
-import type { CheckoutInfoPage } from "../states/checkout.states.js";
+import type { CheckoutInfoPage } from "../../../states/checkout.states.js";
 
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: saucedemo-web/cart/  (click leaves /cart.html -> /checkout-step-one.html)
+ *
+ * Cart page "Checkout" button - owns the nav into step one.
+ */
 export const NavCheckoutInfoBlock = defineNavBlock<CheckoutInfoPage>({
   name: "nav-checkout-info",
   description: "Clicks 'Checkout' on the cart page.",

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

@@ -0,0 +1,21 @@
+# checkout-step-one/ - URL `/checkout-step-one.html`
+
+Shipping info form before order overview.
+
+## URL
+
+- `/checkout-step-one.html`
+
+## Nav blocks
+
+(none - arrival is via `cart/nav-checkout-info.block.ts`)
+
+## Effects / actions
+
+| File | Kind | Notes |
+|------|------|-------|
+| `actions/submit-checkout-info.action.block.ts` | Action | Fill form + Continue -> overview |
+
+## Related mem keys / checkpoints
+
+- Checkpoints: `CheckoutInfoPage`, `CheckoutOverviewPage`

package/{examples/saucedemo/src/blocks → templates/quickstart/src/blocks/saucedemo-web/checkout-step-one}/actions/submit-checkout-info.action.block.ts

@@ -1,11 +1,14 @@
 import { defineBlock, checkpoint, Trait } from "waygraph";
-import type { CheckoutInfoPage, CheckoutOverviewPage } from "../../states/checkout.states.js";
+import type { CheckoutInfoPage, CheckoutOverviewPage } from "../../../../states/checkout.states.js";
 
-// Fills the shipping info form and continues - never navigates
-// (nav-checkout-info.block.ts already got here). Replaces the old
-// checkout-info.action.block.ts, which used to also click the cart link and
-// the checkout button itself - three real page transitions bundled into one
-// non-atomic Block.
+/**
+ * Kind: Action
+ * Helper: defineBlock
+ * Route: saucedemo-web/checkout-step-one/actions/  (= /checkout-step-one.html)
+ *
+ * Fills shipping form and continues - never navigates itself
+ * (nav-checkout-info already got here).
+ */
 export const SubmitCheckoutInfoBlock = defineBlock<CheckoutInfoPage, CheckoutOverviewPage>({
   name: "submit-checkout-info",
   description: "Fills in the shipping info form and continues to the order overview.",

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

@@ -0,0 +1,21 @@
+# checkout-step-two/ - URL `/checkout-step-two.html`
+
+Order overview / finish page.
+
+## URL
+
+- `/checkout-step-two.html`
+
+## Nav blocks
+
+(none - arrival is via submit-checkout-info Action)
+
+## Effects / actions
+
+| File | Kind | Notes |
+|------|------|-------|
+| `actions/finish-order.action.block.ts` | Action | Finish -> thank-you / OrderComplete |
+
+## Related mem keys / checkpoints
+
+- Checkpoints: `CheckoutOverviewPage`, `OrderComplete`

package/{examples/saucedemo/src/blocks → templates/quickstart/src/blocks/saucedemo-web/checkout-step-two}/actions/finish-order.action.block.ts

@@ -1,6 +1,13 @@
 import { defineBlock, checkpoint, Trait, narrate } from "waygraph";
-import type { CheckoutOverviewPage, OrderComplete } from "../../states/checkout.states.js";
+import type { CheckoutOverviewPage, OrderComplete } from "../../../../states/checkout.states.js";
 
+/**
+ * Kind: Action
+ * Helper: defineBlock
+ * Route: saucedemo-web/checkout-step-two/actions/  (= /checkout-step-two.html)
+ *
+ * Places the order on the overview page - form/finish click, not a NavBlock.
+ */
 export const FinishOrderBlock = defineBlock<CheckoutOverviewPage, OrderComplete>({
   name: "finish-order",
   description: "Places the order and confirms the 'Thank you for your order!' completion page.",

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

@@ -0,0 +1,26 @@
+# inventory/ - URL `/inventory.html`
+
+Product catalog after a successful login.
+
+## URL
+
+- `/inventory.html`
+
+## Nav blocks
+
+| File | Helper | Notes |
+|------|--------|-------|
+| `nav-item-detail.block.ts` | `defineMemNavBlock` | Opens mem-picked product detail; instance rows per card |
+
+## Effects / actions
+
+| 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) |
+
+## Related mem keys / checkpoints
+
+- Mem: `saucedemo.selectedItem` (`SelectedItem`)
+- Checkpoints: `LoggedIn`, `ItemInCart`, `ItemDetailPage` (via MemNav)

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

@@ -1,10 +1,16 @@
 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 type { ItemInCart } from "../../../../states/checkout.states.js";
+import { SelectedItem } from "../../../../states/checkout.mem-keys.js";
 import { collectAddableItems } from "./inventory-items.js";
 
-// EffectBlock: mutates cart for the mem-picked product. waygraph auto lists
-// one "Add …" row per live Add button via instanceOptions.
+/**
+ * Kind: Effect
+ * Helper: defineEffectBlock
+ * Route: saucedemo-web/inventory/actions/  (= /inventory.html)
+ *
+ * Mutates cart for the mem-picked product. waygraph auto lists one
+ * "Add ..." row per live Add button via instanceOptions.
+ */
 export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>({
   name: "add-to-cart",
   description: "Adds the item named by mem (saucedemo.selectedItem) to the cart.",

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

@@ -1,5 +1,13 @@
 import type { Page, Locator } from "@playwright/test";
 
+/**
+ * Kind: helper (not a Block)
+ * Route: saucedemo-web/inventory/actions/  (= /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.
+ */
+
 /** Product slug + display name (saucedemo inventory / detail / cart). */
 export type InventoryItem = { id: string; name: string };
 

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

@@ -1,12 +1,18 @@
 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 type { RemoveFromCartOutcome } from "../../../../states/checkout.states.js";
+import { SelectedItem } from "../../../../states/checkout.mem-keys.js";
 import { collectRemovableItems } from "./inventory-items.js";
 
 type RemoveObserve = "still-has-items" | "cart-empty";
 
-// EffectBlock: removes the mem-picked product. After Add, waygraph auto
-// shows matching "Remove …" rows from the live Remove buttons.
+/**
+ * Kind: Effect
+ * Helper: defineEffectBlock
+ * Route: saucedemo-web/inventory/actions/  (= /inventory.html)
+ *
+ * Removes the mem-picked product. After Add, waygraph auto shows matching
+ * "Remove ..." rows from live Remove buttons.
+ */
 export const RemoveFromCartBlock = defineEffectBlock<Checkpoint<string>, RemoveFromCartOutcome>({
   name: "remove-from-cart",
   description: "Removes the item named by mem (saucedemo.selectedItem) from the cart.",

package/templates/quickstart/src/blocks/{nav-item-detail.block.ts → saucedemo-web/inventory/nav-item-detail.block.ts}

@@ -1,13 +1,19 @@
 import { defineMemNavBlock, Trait, type WaygraphInstanceOption } from "waygraph";
-import type { ItemDetailPage } from "../states/checkout.states.js";
-import { SelectedItem } from "../states/checkout.mem-keys.js";
+import type { ItemDetailPage } from "../../../states/checkout.states.js";
+import { SelectedItem } from "../../../states/checkout.mem-keys.js";
 import {
   collectInventoryItems,
   inventoryItemTitleSelector,
 } from "./actions/inventory-items.js";
 
-// MemNavBlock: opens the mem-picked product's detail page. waygraph auto
-// lists one "Open … details" row per inventory card (not only the first item).
+/**
+ * Kind: Nav
+ * Helper: defineMemNavBlock
+ * Route: saucedemo-web/inventory/  (= /inventory.html)
+ *
+ * Opens the mem-picked product detail page. waygraph auto lists one
+ * "Open ... details" row per inventory card via instanceOptions.
+ */
 export const NavItemDetailBlock = defineMemNavBlock<ItemDetailPage>({
   name: "nav-item-detail",
   description: "Opens the product named by mem (saucedemo.selectedItem) on its detail page.",

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

@@ -0,0 +1,25 @@
+# inventory-item/ - URL `/inventory-item.html`
+
+Single product detail page, plus nav edges that return to catalog
+(continue shopping / back home / back to products).
+
+## URL
+
+- `/inventory-item.html` (detail)
+- Related landings: `/inventory.html` (via back / continue-shopping clicks)
+
+## Nav blocks
+
+| File | Helper | Notes |
+|------|--------|-------|
+| `nav-continue-shopping.block.ts` | `defineNavBlock` | Cart "Continue Shopping" -> inventory |
+| `nav-back-to-products.block.ts` | `defineNavBlock` | Order-complete "Back Home" -> inventory |
+| `nav-back-to-inventory.block.ts` | `defineNavBlock` | Detail "Back to products" -> inventory |
+
+## Effects / actions
+
+(none on this route)
+
+## Related mem keys / checkpoints
+
+- Checkpoints: `ItemDetailPage`, `LoggedIn` (after back / continue), `OrderComplete` (from for back-to-products)

package/templates/quickstart/src/blocks/saucedemo-web/inventory-item/nav-back-to-inventory.block.ts

@@ -0,0 +1,18 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { LoggedIn } from "../../../states/checkout.states.js";
+
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: saucedemo-web/inventory-item/  (= /inventory-item.html From)
+ *
+ * click, not url - detail page "Back to products". Separate Block from
+ * nav-back-to-products (different From Checkpoint; atomic convention).
+ */
+export const NavBackToInventoryBlock = defineNavBlock<LoggedIn>({
+  name: "nav-back-to-inventory",
+  description: "Clicks 'Back to products' on the item detail page.",
+  checkpoint: "LoggedIn",
+  click: "#back-to-products",
+  verify: [Trait.url({ pathname: "/inventory.html" })],
+});

package/templates/quickstart/src/blocks/saucedemo-web/inventory-item/nav-back-to-products.block.ts

@@ -0,0 +1,18 @@
+import { defineNavBlock, Trait } from "waygraph";
+import type { LoggedIn } from "../../../states/checkout.states.js";
+
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: saucedemo-web/inventory-item/  (lands on /inventory.html)
+ *
+ * click, not url - order-complete "Back Home" proves the button path
+ * (a url NavBlock would teleport without exercising the control).
+ */
+export const NavBackToProductsBlock = defineNavBlock<LoggedIn>({
+  name: "nav-back-to-products",
+  description: "Clicks 'Back Home' on the order confirmation page.",
+  checkpoint: "LoggedIn",
+  click: "#back-to-products",
+  verify: [Trait.url({ pathname: "/inventory.html" })],
+});

package/templates/quickstart/src/blocks/{nav-continue-shopping.block.ts → saucedemo-web/inventory-item/nav-continue-shopping.block.ts}

@@ -1,7 +1,13 @@
 import { defineNavBlock, Trait } from "waygraph";
-import type { LoggedIn } from "../states/checkout.states.js";
+import type { LoggedIn } from "../../../states/checkout.states.js";
 
-// click, not url - the cart page's own real "Continue Shopping" button.
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: saucedemo-web/inventory-item/  (lands on /inventory.html)
+ *
+ * click, not url - cart page "Continue Shopping" proves the app's own path.
+ */
 export const NavContinueShoppingBlock = defineNavBlock<LoggedIn>({
   name: "nav-continue-shopping",
   description: "Clicks 'Continue Shopping' on the cart page.",

package/templates/quickstart/src/blocks/{nav-login.block.ts → saucedemo-web/nav-login.block.ts}

@@ -1,8 +1,13 @@
 import { defineNavBlock, Trait } from "waygraph";
-import type { LoginPage } from "../states/checkout.states.js";
+import type { LoginPage } from "../../states/checkout.states.js";
 
-// Nav to the login page (/). page.goto lives here, generated by defineNavBlock -
-// actions/submit-login.action.block.ts never navigates.
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: saucedemo-web/  (= /)
+ *
+ * page.goto to the login form lives here only. submit-login Action never navigates.
+ */
 export const NavLoginBlock = defineNavBlock<LoginPage>({
   name: "nav-login",
   description: "Goes to the Swag Labs login page.",

package/templates/quickstart/src/flows/cart-continue.flow.ts

@@ -1,6 +1,6 @@
 import { Engine, start, end, withTitle } from "waygraph";
-import { NavCartBlock } from "../blocks/nav-cart.block.js";
-import { NavContinueShoppingBlock } from "../blocks/nav-continue-shopping.block.js";
+import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
+import { NavContinueShoppingBlock } from "../blocks/saucedemo-web/inventory-item/nav-continue-shopping.block.js";
 
 const engine = new Engine();
 

package/templates/quickstart/src/flows/cart-mem.flow.ts

@@ -1,5 +1,5 @@
 import { Engine, start, end } from "waygraph";
-import { RemoveFromCartBlock } from "../blocks/actions/remove-from-cart.effect.block.js";
+import { RemoveFromCartBlock } from "../blocks/saucedemo-web/inventory/actions/remove-from-cart.effect.block.js";
 
 const engine = new Engine();
 

package/templates/quickstart/src/flows/catalog-logout.flow.ts

@@ -1,7 +1,7 @@
 import { Engine, start, end, withTitle } from "waygraph";
-import { NavItemDetailBlock } from "../blocks/nav-item-detail.block.js";
-import { NavBackToInventoryBlock } from "../blocks/nav-back-to-inventory.block.js";
-import { SubmitLogoutBlock } from "../blocks/actions/submit-logout.action.block.js";
+import { NavItemDetailBlock } from "../blocks/saucedemo-web/inventory/nav-item-detail.block.js";
+import { NavBackToInventoryBlock } from "../blocks/saucedemo-web/inventory-item/nav-back-to-inventory.block.js";
+import { SubmitLogoutBlock } from "../blocks/saucedemo-web/actions/submit-logout.action.block.js";
 
 const engine = new Engine();