waygraph 0.7.10 → 0.7.12

package/README.md

@@ -23,6 +23,8 @@ Browser docs (quick start, **demo / step / autoplay**, **auto explore**, engine
 - **Demo contract:** [`docs/demo.html`](./docs/demo.html) — `--step` vs `--autoplay`
 - **Auto explore:** [`docs/auto.html`](./docs/auto.html) — Effect / MemNav picker (TS salt over Blocks)
 - **In-repo example:** [`examples/saucedemo`](./examples/saucedemo) — full Sauce Demo project
+- **Convention showcase (Pages):** [`docs/saucedemo/`](./docs/saucedemo/) —
+  https://deviate-dv8.github.io/waygraph/saucedemo/
 
 This README stays the in-repo API narrative; Pages is the same material for eyeballing and cross-mesh handoff.
 

package/dist/auto-explore-run.js

@@ -182,7 +182,21 @@ async function runOneBlock(engine, entry, context, page, mem, headful) {
     if (headful)
         await setAutoPanelRunning(page, entry.block.name);
     const flow = engine.defineFlow([start, entry.block, end]);
-    await flow.run(context, mem, { page, closeOnFinish: false });
+    const BLOCK_TIMEOUT_MS = 45_000;
+    let timer;
+    try {
+        await Promise.race([
+            flow.run(context, mem, { page, closeOnFinish: false }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Block "${entry.block.name}" timed out after ${BLOCK_TIMEOUT_MS / 1000}s - ` +
+                    "click Quit and retry, or check network / mem credentials")), BLOCK_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
     await page.evaluate("delete window.__wgPendingNavClickLabel").catch(() => { });
 }
 const PANEL_CSS = "#wg-auto-panel{position:fixed;z-index:2147483647;left:50%;bottom:12px;transform:translateX(-50%);" +

package/dist/cli.d.ts

@@ -4,7 +4,7 @@
  *
  * Commands (watch first, then run, then inspect, then scaffold):
  *   demo <flow|spec> [project]   Watch a flow/chain with step overlay (default STEP+headed)
- *   try [demo]                   One-shot saucedemo onboarding in an OS temp dir
+ *   try [demo|auto]              One-shot saucedemo in an OS temp dir (demo=stepper, auto=explore)
  *   chain <spec> [project]       Ad-hoc Blocks by name (+ --step/--autoplay like demo)
  *   run <flow> [project]         Run a named flow (no overlay unless --step)
  *   list / nav / validate        Discover and inspect flows

package/dist/cli.js

@@ -4,7 +4,7 @@
  *
  * Commands (watch first, then run, then inspect, then scaffold):
  *   demo <flow|spec> [project]   Watch a flow/chain with step overlay (default STEP+headed)
- *   try [demo]                   One-shot saucedemo onboarding in an OS temp dir
+ *   try [demo|auto]              One-shot saucedemo in an OS temp dir (demo=stepper, auto=explore)
  *   chain <spec> [project]       Ad-hoc Blocks by name (+ --step/--autoplay like demo)
  *   run <flow> [project]         Run a named flow (no overlay unless --step)
  *   list / nav / validate        Discover and inspect flows
@@ -2459,15 +2459,12 @@ async function wireQuickstartToPackageRoot(destDir) {
     writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
 /**
- * `waygraph try demo` - copy a self-contained saucedemo project into a temp
- * dir (never the caller's cwd), run a chainFlow step demo (Sign In + Shop +
- * blocked Viewer), then run the headless Playwright test, and print where
- * everything lives.
+ * Copy templates/quickstart into a fresh OS temp dir and wire it to this
+ * package build. Returns destDir, or null after setting exitCode on failure.
  */
-async function runTryDemo() {
-    const destDir = mkdtempSync(join(tmpdir(), "waygraph-try-demo-"));
+async function prepareTryQuickstart(label) {
+    const destDir = mkdtempSync(join(tmpdir(), `${label}-`));
     cpSync(join(packageRoot(), "templates", "quickstart"), destDir, { recursive: true });
-    // Never copy dev node_modules / test output into the temp demo (Playwright double-load).
     rmSync(join(destDir, "node_modules"), { recursive: true, force: true });
     rmSync(join(destDir, "test-results"), { recursive: true, force: true });
     rmSync(join(destDir, "package-lock.json"), { force: true });
@@ -2477,14 +2474,26 @@ async function runTryDemo() {
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
         process.exitCode = 1;
-        return;
+        return null;
     }
-    const problem = await ensureDirPrereqs(destDir, "waygraph try demo");
+    const problem = await ensureDirPrereqs(destDir, label);
     if (problem) {
-        console.error(`waygraph try demo: couldn't get ready.\n${problem}`);
+        console.error(`${label}: couldn't get ready.\n${problem}`);
         process.exitCode = 1;
-        return;
+        return null;
     }
+    return destDir;
+}
+/**
+ * `waygraph try demo` - copy a self-contained saucedemo project into a temp
+ * dir (never the caller's cwd), run a chainFlow step demo (Sign In + Shop +
+ * blocked Viewer), then run the headless Playwright test, and print where
+ * everything lives.
+ */
+async function runTryDemo() {
+    const destDir = await prepareTryQuickstart("waygraph-try-demo");
+    if (!destDir)
+        return;
     process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
     // Default: headed stepper, manual Next. --video records that session (not headless rush).
     process.env.WAYGRAPH_HEADED ??= "1";
@@ -2529,6 +2538,27 @@ async function runTryDemo() {
         "Permanent full example in this package: examples/saucedemo\n" +
         "Keep a permanent scaffold in your tree: waygraph init my-app\n");
 }
+/**
+ * `waygraph try auto` - same temp Sauce Demo as try demo, but opens the
+ * headed `waygraph auto` explorer (Effect Add/Remove, MemNav Open details).
+ */
+async function runTryAuto() {
+    const destDir = await prepareTryQuickstart("waygraph-try-auto");
+    if (!destDir)
+        return;
+    process.env.WAYGRAPH_BASE_URL ??= "https://www.saucedemo.com";
+    console.log("waygraph try auto: headed explore on Sauce Demo (temp dir).\n" +
+        "  Pick nav-login, then submit-login (creds are pre-seeded).\n" +
+        "  On inventory: Add/Remove Effect rows + Open details MemNav.\n" +
+        "  Quit from the panel when done.\n");
+    await runAutoExplore(destDir, { baseURL: process.env.WAYGRAPH_BASE_URL });
+    console.log("\nwaygraph try auto: explorer closed.\n\n" +
+        `Temp project:\n  ${destDir}\n\n` +
+        "Run again:\n" +
+        `  cd ${destDir} && npm run auto\n\n` +
+        "In-package: examples/saucedemo\n" +
+        "Docs: https://deviate-dv8.github.io/waygraph/saucedemo/\n");
+}
 async function validateFlows(projectDir) {
     const files = discoverFlows(projectDir);
     const results = [];
@@ -2858,7 +2888,7 @@ Usage (watch -> run -> inspect -> scaffold):
                                   --base-url, else WAYGRAPH_BASE_URL, else
                                   package.json waygraph.baseUrl, else
                                   playwright.config baseURL.
-  waygraph try [demo]             One-shot saucedemo (temp dir) + npm test
+  waygraph try [demo|auto]        One-shot saucedemo (temp dir): demo=stepper+test, auto=explore
   waygraph chain <spec> [project] Ad-hoc Blocks by name ("a then b"); add
                                   --step / --autoplay for the same overlay
   waygraph run <flow> [project]   Run a named flow (no overlay unless --step)
@@ -2885,6 +2915,7 @@ Demo / step / autoplay (read this - agents get this wrong):
   Same overlay on a chain:    waygraph chain "login then nav-cart" . --step
   Unattended (no overlay):    waygraph demo shopFlow . --no-step
   Onboarding (temp dir):      npx waygraph try demo
+  Explore (temp dir):         npx waygraph try auto
 
 Other run flags (chain / demo / try) - flags beat WAYGRAPH_* env:
   --base-url <url>                base URL for relative page.goto()
@@ -3157,7 +3188,17 @@ async function main() {
         case "try": {
             const flags = parseRunFlags(args.slice(1));
             applyRunFlags(flags);
-            await runTryDemo();
+            const mode = (flags.positionals[0] ?? "demo").toLowerCase();
+            if (mode === "auto") {
+                await runTryAuto();
+            }
+            else if (mode === "demo" || mode === "") {
+                await runTryDemo();
+            }
+            else {
+                console.error(`waygraph try: unknown mode "${mode}" - use "demo" or "auto"`);
+                process.exitCode = 1;
+            }
             break;
         }
         case "check": {

package/dist/step-overlay.js

@@ -140,47 +140,56 @@ export function instrumentInteractionHighlighting(page, mem, slowMo) {
         // Keep unbound — originalFill.call(this, …) must receive the Locator as `this`, not the prototype.
         const originalFill = proto.fill;
         proto.fill = async function (value, options) {
+            const livePage = (typeof this.page === "function" ? this.page() : page);
             try {
-                await installDemoChrome(page);
+                await installDemoChrome(livePage);
                 const box = await this.boundingBox();
                 if (box) {
                     const label = memTrack.lastKeyName && Date.now() - memTrack.at < 3000
                         ? "from mem: " + memTrack.lastKeyName
                         : "writing";
-                    await moveCursorTo(page, box, cursorMs(500));
-                    await showRing(page, box, label);
+                    await moveCursorTo(livePage, box, cursorMs(500));
+                    await showRing(livePage, box, label);
                     await new Promise((r) => setTimeout(r, 200));
                 }
             }
             catch {
                 /* best-effort */
             }
-            try {
-                await originalFill.call(this, "", options);
-                const seqOpts = { delay: typeDelay() };
-                if (options?.timeout !== undefined)
-                    seqOpts.timeout = options.timeout;
-                await this.pressSequentially(String(value), seqOpts);
-            }
-            catch {
+            // Prefer a single fill - clear+pressSequentially can hang when the auto
+            // panel steals focus mid-type (looks stuck on "Running: submit-login").
+            if (slowMo || typeDelay() === 0) {
                 await originalFill.call(this, value, options);
             }
-            await hideRing(page);
+            else {
+                try {
+                    await originalFill.call(this, "", options);
+                    const seqOpts = { delay: typeDelay() };
+                    if (options?.timeout !== undefined)
+                        seqOpts.timeout = options.timeout;
+                    await this.pressSequentially(String(value), seqOpts);
+                }
+                catch {
+                    await originalFill.call(this, value, options);
+                }
+            }
+            await hideRing(livePage);
         };
     }
     if (!proto.__wgClickPatched) {
         proto.__wgClickPatched = true;
         const originalClick = proto.click;
         proto.click = async function (options) {
+            const livePage = (typeof this.page === "function" ? this.page() : page);
             let clickPoint = null;
             try {
-                await installDemoChrome(page);
-                await this.waitFor({ state: "visible", timeout: options?.timeout ?? 30000 }).catch(() => { });
+                await installDemoChrome(livePage);
+                await this.waitFor({ state: "visible", timeout: options?.timeout ?? 15000 }).catch(() => { });
                 const box = await this.boundingBox();
                 if (box) {
                     let label = "click";
                     try {
-                        const navLabel = await page.evaluate(() => window.__wgPendingNavClickLabel ?? null);
+                        const navLabel = await livePage.evaluate(() => window.__wgPendingNavClickLabel ?? null);
                         if (navLabel)
                             label = String(navLabel);
                         else {
@@ -192,8 +201,8 @@ export function instrumentInteractionHighlighting(page, mem, slowMo) {
                     catch {
                         /* ignore */
                     }
-                    clickPoint = await moveCursorTo(page, box, cursorMs(600));
-                    await showRing(page, box, label);
+                    clickPoint = await moveCursorTo(livePage, box, cursorMs(600));
+                    await showRing(livePage, box, label);
                     await new Promise((r) => setTimeout(r, clickPrePop()));
                 }
             }
@@ -201,12 +210,12 @@ export function instrumentInteractionHighlighting(page, mem, slowMo) {
                 /* best-effort */
             }
             if (clickPoint) {
-                await clickPulseAt(page, clickPoint.x, clickPoint.y);
-                await new Promise((r) => setTimeout(r, 500));
+                await clickPulseAt(livePage, clickPoint.x, clickPoint.y);
+                await new Promise((r) => setTimeout(r, 200));
             }
             const result = await originalClick.call(this, options);
             await new Promise((r) => setTimeout(r, clickPostPop()));
-            await hideRing(page);
+            await hideRing(livePage).catch(() => { });
             return result;
         };
     }

package/examples/saucedemo/README.md

@@ -1,12 +1,21 @@
-# Sauce Demo example
+# Sauce Demo - convention showcase
 
-Full live consumer for [saucedemo.com](https://www.saucedemo.com) - Effect
-Add/Remove (`defineEffectBlock` / `*.effect.block.ts`), MemNav Open details,
-`waygraph auto`, and Playwright flows. Helpers are TypeScript salt: runtime is
-still just Blocks.
+Full live consumer for [saucedemo.com](https://www.saucedemo.com). This tree is
+the **reference** for waygraph consumer conventions:
 
-This tree is the in-package reference. `waygraph try demo` copies the sibling
-template at `templates/quickstart` (same Blocks) into an OS temp dir.
+- Route folders under `src/blocks/saucedemo-web/` = real Swag Labs URLs
+- **Nav** / **Effect** / **Action** file kinds (helpers are TypeScript salt;
+  runtime is still `Block`)
+- `instanceOptions` menus for `waygraph auto` (Add/Remove + Open details)
+- Detailed Kind / Helper / Route comments on every Block file
+- Per-route `NAV.md` + root `src/blocks/SITE-MAP.md`
+
+**GitHub Pages walkthrough:**
+[docs/saucedemo](https://deviate-dv8.github.io/waygraph/saucedemo/)
+(`docs/saucedemo/` in this repo - README, SITE-MAP, kinds, layout, auto, comments).
+
+`waygraph try demo` copies the sibling template at `templates/quickstart`
+(same Blocks) into an OS temp dir.
 
 ## Setup
 
@@ -28,4 +37,22 @@ npx playwright install chromium
 | Stepper (Auto-advance) | `npm run demo:autoplay` |
 | List flows | `npm run flows` |
 
-Docs: [Auto explore](../../docs/auto.html) · [Demo / step](../../docs/demo.html)
+## Layout (short)
+
+```text
+src/blocks/
+  SITE-MAP.md
+  saucedemo-web/                 # URL /
+    NAV.md
+    nav-login.block.ts
+    actions/                     # submit-login, logout, …
+    inventory/                   # URL /inventory.html
+      nav-item-detail.block.ts   # MemNav
+      actions/*.effect.block.ts  # Add / Remove
+    cart/                        # URL /cart.html
+    checkout-step-one/
+    checkout-step-two/
+```
+
+Docs: [Sauce Demo showcase](../../docs/saucedemo/) ·
+[Auto explore](../../docs/auto.html) · [Consumer layout](../../docs/consumer.html)

package/examples/saucedemo/docs/CONVENTION.md

@@ -27,20 +27,38 @@ app changes URL as a side effect of `#continue`.
 
 ```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
-    remove-from-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/examples/saucedemo/package-lock.json

@@ -0,0 +1,118 @@
+{
+  "name": "waygraph-example-saucedemo",
+  "version": "0.0.1",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "waygraph-example-saucedemo",
+      "version": "0.0.1",
+      "dependencies": {
+        "waygraph": "file:../.."
+      },
+      "devDependencies": {
+        "@playwright/test": "^1.55.0",
+        "@types/node": "^26.0.0",
+        "typescript": "^5.6.0"
+      }
+    },
+    "../..": {
+      "version": "0.7.11",
+      "license": "MIT",
+      "dependencies": {
+        "tsx": "^4.0.0"
+      },
+      "bin": {
+        "waygraph": "bin/waygraph"
+      },
+      "devDependencies": {
+        "@playwright/test": "^1.55.0",
+        "@types/node": "^26.0.0",
+        "typescript": "^5.6.0"
+      },
+      "peerDependencies": {
+        "@playwright/test": "^1.40.0"
+      }
+    },
+    "node_modules/@playwright/test": {
+      "version": "1.63.0",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.63.0.tgz",
+      "integrity": "sha512-oxMK4vllB9RK5NQ2l1pq1IfOf2AvnEuj/vYGDj0H2nMtmtZpKtCwt/l00GEO6xjGfpBNAvjovvYdCm50dRQkpQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright": "1.63.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "26.6.1",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.1.tgz",
+      "integrity": "sha512-VqGJBMCtdhqkBUCcBLvywI0NJ+KLuVzgNnlBUNFOQjqVxzo2lxLUNg1DSey8+u2u6ktswSAxg+s68QLzWHNOuA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~8.9.0"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.63.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.63.0.tgz",
+      "integrity": "sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.63.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.63.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.63.0.tgz",
+      "integrity": "sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "8.9.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.9.0.tgz",
+      "integrity": "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/waygraph": {
+      "resolved": "../..",
+      "link": true
+    }
+  }
+}

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

@@ -86,9 +86,9 @@ async function snap(page, name) {
 const { graph, library } = await buildExploreContext(root);
 const nodeNames = graph.nodes.map((n) => n.checkpoint);
 
-const { NavLoginBlock } = await import(pathToFileURL(join(root, "src/blocks/nav-login.block.js")).href);
+const { NavLoginBlock } = await import(pathToFileURL(join(root, "src/blocks/saucedemo-web/nav-login.block.js")).href);
 const { SubmitLoginActionBlock } = await import(
-  pathToFileURL(join(root, "src/blocks/actions/submit-login.action.block.js")).href
+  pathToFileURL(join(root, "src/blocks/saucedemo-web/actions/submit-login.action.block.js")).href
 );
 const { LoginCreds } = await import(pathToFileURL(join(root, "src/states/checkout.mem-keys.js")).href);
 

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

@@ -13,9 +13,9 @@ await import(require.resolve("tsx/esm"));
 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/nav-login.block.js")).href);
+const { NavLoginBlock } = await import(pathToFileURL(join(root, "src/blocks/saucedemo-web/nav-login.block.js")).href);
 const { SubmitLoginActionBlock } = await import(
-  pathToFileURL(join(root, "src/blocks/actions/submit-login.action.block.js")).href
+  pathToFileURL(join(root, "src/blocks/saucedemo-web/actions/submit-login.action.block.js")).href
 );
 const { LoginCreds } = await import(pathToFileURL(join(root, "src/states/checkout.mem-keys.js")).href);
 

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