waygraph 0.15.52 → 0.15.54

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

@@ -1,40 +1,32 @@
-import { Engine, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
+import { engine } from "../../config/waygraph.config.js";
+import "../states/checkout.mem-stubs.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 { SubmitLoginBlock } from "../blocks/saucedemo-web/methods/submit-login.method.block.js";
+import { loginRefused } from "../stubs/login.js";
 
-const engine = new Engine();
-
-// A genuinely DIFFERENT scenario from checkoutFlow - not the same steps
-// split in half. Same login blocks, different user, different outcome:
-// locked_out_user attempts the exact same login an Owner (standard_user,
-// checkoutFlow) just completed successfully, and is blocked -
-// saucedemo.com's real response, verified live: stays on "/", shows
-// "Epic sadface: Sorry, this user has been locked out."
-//
-// withSessionReset matters here for real, not cosmetically - entered right
-// after checkoutFlow's already-authenticated session, this needs its own
-// genuinely fresh cookies/storage, or the previous user's session would
-// still be live and this login attempt wouldn't mean anything.
-//
-// submit-login branches: observe sees no /inventory.html navigation,
-// resolve -> LoginPage, verify confirms the error banner. Demo still wraps
-// withExpectedFailure so step 9/9 shows stubOnError rings + amber
-// "expected outcome" panel (branching no longer throws).
-export const viewerBlockedFlow = withExpectedFailure(
-  withTitle(
-    withSessionReset(
-      engine
-        .map()
-        .start()
-        .gotoPage(NavLoginBlock)
-        .method(FillUsernameBlock)
-        .method(FillPasswordBlock)
-        .method(SubmitLoginBlock)
-        .end(),
+/**
+ * locked_out_user attempts the login a standard user just completed and is refused: the app stays on the login page and
+ * shows the error banner. Run it after another flow to see it needs a reset: `.flow(viewerBlockedFlow, { reset: true })`.
+ */
+export const viewerBlockedFlow = engine
+  .map({
+    sessionReset: true,
+    expectedFailure:
+      "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",
+  })
+  .start()
+  .gotoPage(
+    NavLoginBlock.stubBefore((ctx) =>
+      ctx.title("Viewer: Blocked Login Attempt"),
     ),
-    "Viewer: Blocked Login Attempt",
-  ),
-  "locked_out_user stays on LoginPage with the error banner - this is the product working as intended.",
-);
+  )
+  .method(FillUsernameBlock)
+  .method(FillPasswordBlock)
+  .method(
+    SubmitLoginBlock.stubAfter((ctx) => {
+      if (ctx.out?.__state === "LoginPage") loginRefused(ctx);
+    }),
+  )
+  .end();

package/examples/saucedemo/src/states/checkout.mem-stubs.ts

@@ -0,0 +1,11 @@
+import { registerMemStub } from "waygraph";
+import { LoginCreds, SelectedItem } from "./checkout.mem-keys.js";
+
+registerMemStub(LoginCreds.key, () => ({
+  username: "standard_user",
+  password: "secret_sauce",
+}));
+registerMemStub(SelectedItem.key, () => ({
+  id: "sauce-labs-backpack",
+  name: "Sauce Labs Backpack",
+}));

package/examples/saucedemo/src/stubs/device-showcase.ts

@@ -0,0 +1,193 @@
+import type { StubCtx } from "waygraph";
+import { LoginCreds } from "../states/checkout.mem-keys.js";
+import { LoginSel } from "../blocks/saucedemo-web/methods/login.sel.js";
+import { CartSel } from "../blocks/saucedemo-web/cart/cart.sel.js";
+import { InventorySel } from "../blocks/saucedemo-web/inventory/methods/inventory-items.js";
+
+const PRODUCT_ID = "sauce-labs-backpack";
+
+/** The six-step checklist of the device showcase; `done` is how many are ticked, `index` the highlighted one. */
+function checklist(done: number, index: number) {
+  const steps = [
+    "Enter username",
+    "Enter password",
+    "Tap Login",
+    "Find the product",
+    "Add to cart",
+    "Open cart",
+  ];
+  const ids = [
+    "login-user",
+    "login-pass",
+    "login-submit",
+    "cart-find",
+    "cart-add",
+    "cart-open",
+  ];
+  return [
+    ids.map((id, i) => ({
+      id,
+      text: steps[i]!,
+      ...(i < done ? { done: true } : {}),
+    })),
+    { title: "Device showcase", index },
+  ] as const;
+}
+
+/** Narration for the device showcase flow: phone login, tablet shelf, landscape cart. Each is a stub to chain on its Block. */
+export const deviceShowcase = {
+  username: {
+    before: (ctx: StubCtx) => {
+      ctx.title("Signing in · mobile");
+      ctx.device("mobile");
+      ctx.portrait();
+      ctx.todos("saucedemo", ...checklist(0, 0));
+      ctx.zoom(1.35);
+      const fromMem = ctx.mem?.get(LoginCreds.key)?.username;
+      ctx.ring("username", {
+        selector: LoginSel.username,
+        label: "Username",
+        detail: fromMem
+          ? `tone: info (blue) - mem ${fromMem}`
+          : "tone: info (blue)",
+        tone: "info",
+        todo: "login-user",
+        focus: true,
+        zoom: 1.4,
+      });
+    },
+    after: (ctx: StubCtx) => {
+      ctx.todos("saucedemo", ...checklist(1, 1));
+    },
+  },
+  password: {
+    before: (ctx: StubCtx) => {
+      ctx.ring("password", {
+        selector: LoginSel.password,
+        label: "Password",
+        detail: "tone: planned (purple)",
+        todo: "login-pass",
+        tone: "planned",
+        focus: true,
+        zoom: 1.4,
+      });
+    },
+    after: (ctx: StubCtx) => {
+      ctx.todos("saucedemo", ...checklist(2, 2));
+    },
+  },
+  submit: {
+    before: (ctx: StubCtx) => {
+      ctx.highlights({
+        submit: {
+          selector: LoginSel.loginButton,
+          label: "Login",
+          detail: "tone: warning (yellow)",
+          todo: "login-submit",
+          tone: "warning",
+          focus: true,
+          zoom: 1.55,
+          weight: "bold",
+          gesture: "tap",
+        },
+      });
+    },
+    after: (ctx: StubCtx) => {
+      ctx.banner("Inventory · landscape");
+      ctx.landscape();
+      ctx.todos("saucedemo", ...checklist(3, 3));
+      ctx.ring("shelf", {
+        selector: ".inventory_list",
+        label: "Product shelf",
+        detail: "tone: success (green) - ready to shop",
+        tone: "success",
+        focus: true,
+        zoom: 1.25,
+        duration: true,
+      });
+    },
+  },
+  addToCart: {
+    before: (ctx: StubCtx) => {
+      ctx.title("Pick a product · tablet");
+      ctx.device("tablet");
+      ctx.portrait();
+      ctx.todos("saucedemo", ...checklist(3, 3));
+      ctx.zoom(1.35);
+      ctx.zoomOut(false);
+      ctx.highlights({
+        product: {
+          selector: InventorySel.title(PRODUCT_ID),
+          label: "Sauce Labs Backpack",
+          detail: "tone: info (blue)",
+          tone: "info",
+          focus: true,
+          zoom: 1.45,
+          zoomOut: false,
+        },
+        add: {
+          selector: InventorySel.addBtn(PRODUCT_ID),
+          label: "Add to cart",
+          detail: "tone: success (green)",
+          tone: "success",
+          focus: true,
+          zoom: 1.5,
+          zoomOut: false,
+          weight: "bold",
+        },
+      });
+    },
+    after: (ctx: StubCtx) => {
+      ctx.banner("In the cart");
+      ctx.todos("saucedemo", ...checklist(4, 4));
+      ctx.zoomOut(false);
+      ctx.ring("badge", {
+        selector: InventorySel.cartBadge,
+        label: "Cart badge",
+        detail: "tone: success (green) - count updated",
+        tone: "success",
+        focus: true,
+        zoomOut: false,
+        duration: true,
+      });
+    },
+  },
+  openCart: {
+    before: (ctx: StubCtx) => {
+      ctx.title("Open cart · landscape");
+      ctx.landscape();
+      ctx.todos("saucedemo", ...checklist(5, 5));
+      ctx.zoom(1.4);
+      ctx.zoomOut(false);
+      ctx.highlights({
+        cart: {
+          selector: CartSel.cartLink,
+          label: "Cart",
+          detail: "tone: planned (purple) - open cart",
+          tone: "planned",
+          focus: true,
+          zoomOut: false,
+          followMouse: false,
+          weight: "bold",
+          gesture: "tap",
+        },
+      });
+    },
+    after: (ctx: StubCtx) => {
+      ctx.banner("Your cart · desktop");
+      ctx.clearDevice();
+      ctx.hideTodos();
+      ctx.zoomOut(true);
+      ctx.ring("items", {
+        selector: InventorySel.cartItem,
+        label: "Cart items",
+        detail: "tone: success (green) - product in cart",
+        tone: "success",
+        focus: true,
+        zoomOut: true,
+        followMouse: false,
+        duration: true,
+      });
+    },
+  },
+};

package/examples/saucedemo/src/stubs/login.ts

@@ -0,0 +1,37 @@
+import type { StubCtx } from "waygraph";
+import { LoginSel } from "../blocks/saucedemo-web/methods/login.sel.js";
+
+/** What a refused login looks like on screen: the title, a finished checklist and the error banner. */
+export function loginRefused(ctx: StubCtx): void {
+  ctx.title("Login blocked");
+  ctx.todos(
+    "saucedemo",
+    [
+      { id: "login-user", text: "Enter username", done: true },
+      { id: "login-pass", text: "Enter password", done: true },
+      { id: "login-submit", text: "Click Login", done: true },
+    ],
+    { title: "Sign in", style: "checklist" },
+  );
+  ctx.ring("error", {
+    selector: LoginSel.errorBanner,
+    label: "Login error banner",
+    detail: "tone: danger (red)",
+    tone: "danger",
+    focus: true,
+    duration: true,
+  });
+}
+
+/** Rings the error banner when the login step itself throws. */
+export function loginFailed(ctx: StubCtx): void {
+  ctx.title("Login failed");
+  ctx.ring("error", {
+    selector: LoginSel.errorBanner,
+    label: "Login error banner",
+    detail: "tone: danger (red)",
+    tone: "danger",
+    focus: true,
+    duration: true,
+  });
+}

package/examples/saucedemo/tests/chain-flow-episodes.spec.ts

@@ -1,30 +1,28 @@
 import { test, expect } from "@playwright/test";
-import { MemPage, checkpoint, chainFlow } from "waygraph";
+import { MemPage, checkpoint } from "waygraph";
+import { engine } from "../config/waygraph.config.js";
 import { loginFlow } from "../src/flows/login.flow.js";
 import { shopFlow } from "../src/flows/shop.flow.js";
 import { LoginCreds, SelectedItem } from "../src/states/checkout.mem-keys.js";
 
-// Proves the 2-episode chainFlow scenario the step-mode CLI demo shows
+// Proves the 2-episode nested-flow scenario the step-mode CLI demo shows
 // interactively ("Episode 1: Sign In" -> "Episode 2: Shop & Checkout") also
 // works as a real, automated, headless test - not just something you have
 // to click through by hand. loginFlow/shopFlow are the exact same Flow
 // objects `waygraph chain "loginFlow(...) then shopFlow"` drives.
-test("chainFlow sequences 2 titled episodes (loginFlow then shopFlow) against the real live site", async () => {
+test("nested flows run 2 episodes (loginFlow then shopFlow) against the real live site", async () => {
   const mem = new MemPage();
   mem.set(LoginCreds({ username: "standard_user", password: "secret_sauce" }));
   mem.set(SelectedItem({ id: "sauce-labs-backpack", name: "Sauce Labs Backpack" }));
 
-  const combined = chainFlow(loginFlow, shopFlow);
+  const combined = engine.map().start().flow(loginFlow).flow(shopFlow).end();
   const result = await combined.run(mem);
 
   expect(result).toEqual(checkpoint("OrderComplete"));
 });
 
-test("each episode's title survives chaining, and blocks() reports the flattened chain in order", () => {
-  expect(loginFlow.title).toBe("Sign In");
-  expect(shopFlow.title).toBe("Shop & Checkout");
-
-  const combined = chainFlow(loginFlow, shopFlow);
+test("blocks() reports the flattened chain in order", () => {
+  const combined = engine.map().start().flow(loginFlow).flow(shopFlow).end();
   const blocks = combined.blocks();
 
   expect(blocks.map((b) => b.name)).toEqual([

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

@@ -1,5 +1,6 @@
 import { test, expect } from "@playwright/test";
-import { MemPage, Engine, start, end } from "waygraph";
+import { MemPage } from "waygraph";
+import { engine } from "../config/waygraph.config.js";
 import { NavLoginBlock } from "../src/blocks/saucedemo-web/nav-login.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";
@@ -10,8 +11,14 @@ test("submit-login: wrong password branches to LoginPage with error banner", asy
   const mem = new MemPage();
   mem.set(LoginCreds({ username: "standard_user", password: "wrong-password" }));
 
-  const engine = new Engine();
-  const flow = engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]);
+  const flow = engine
+    .map()
+    .start()
+    .gotoPage(NavLoginBlock)
+    .method(FillUsernameBlock)
+    .method(FillPasswordBlock)
+    .method(SubmitLoginBlock)
+    .end();
   const result = await flow.run(mem);
 
   expect(result.__state).toBe("LoginPage");
@@ -21,8 +28,14 @@ test("submit-login: good password branches to LoggedIn", async () => {
   const mem = new MemPage();
   mem.set(LoginCreds({ username: "standard_user", password: "secret_sauce" }));
 
-  const engine = new Engine();
-  const flow = engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]);
+  const flow = engine
+    .map()
+    .start()
+    .gotoPage(NavLoginBlock)
+    .method(FillUsernameBlock)
+    .method(FillPasswordBlock)
+    .method(SubmitLoginBlock)
+    .end();
   const result = await flow.run(mem);
 
   expect(result.__state).toBe("LoggedIn");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.52",
+  "version": "0.15.54",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
@@ -48,16 +48,19 @@
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/copy-runner.mjs && node scripts/copy-ui-css.mjs",
     "typecheck": "node bin/waygraph typecheck .",
-    "test": "npm run check:structure && npm run test:unit && playwright test",
+    "test": "npm run check:structure && npm run knip && npm run test:unit && playwright test",
     "test:ui": "playwright test --ui",
     "test:unit": "node --import tsx/esm --test tests/unit/*.spec.ts",
     "example:saucedemo:install": "npm --prefix examples/saucedemo install",
     "example:saucedemo:test": "npm --prefix examples/saucedemo test",
     "example:saucedemo:auto": "npm --prefix examples/saucedemo run auto",
     "check:structure": "node scripts/check-structure.mjs",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
+    "docs:dev": "npm run docs:api && vitepress dev docs",
+    "docs:build": "npm run docs:api && vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "docs:api": "typedoc && node scripts/gen-deprecated.mjs",
+    "knip": "knip",
+    "sync:quickstart": "node scripts/sync-quickstart.mjs"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"
@@ -70,6 +73,10 @@
   "devDependencies": {
     "@playwright/test": "^1.63.0",
     "@types/node": "^26.0.0",
+    "knip": "^6.42.1",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.14.1",
+    "typedoc-vitepress-theme": "^1.1.4",
     "typescript": "^5.6.0",
     "vitepress": "^1.6.4"
   }

package/templates/quickstart/README.md

@@ -1,10 +1,7 @@
 # waygraph quickstart (Sauce Demo)
 
-Temp-dir template for `npx waygraph try demo`. Same Blocks as
-`examples/saucedemo` (route-folder convention under `src/blocks/saucedemo-web/`).
+Temp-dir template for `npx waygraph try demo`. A copy of `examples/saucedemo` (freeform route-folder layout under
+`src/blocks/saucedemo-web/`, flows in `src/flows/`, narration in `src/stubs/`, settings in `config/waygraph.config.ts`).
 
-Convention walkthrough on Pages:
-https://deviate-dv8.github.io/waygraph/saucedemo/
-
-Do not edit this tree as the long-lived showcase - edit `examples/saucedemo`,
-then re-copy Blocks here when shipping a release that bumps `try demo`.
+Do not edit this tree as the long-lived showcase: edit `examples/saucedemo`, then run `npm run sync:quickstart` in the
+waygraph repo before a release.

package/templates/quickstart/config/waygraph.config.ts

@@ -0,0 +1,17 @@
+import { Engine, defineConfig } from "waygraph";
+
+const config = defineConfig({
+  baseUrl: "https://www.saucedemo.com",
+  playwright: {
+    workers: 1,
+    fullyParallel: false,
+    timeout: 30_000,
+    use: {
+      headless: true,
+      launchOptions: { args: ["--no-sandbox", "--disable-dev-shm-usage"] },
+    },
+  },
+});
+
+export default config;
+export const engine = new Engine(config);

package/templates/quickstart/docs/CONVENTION.md

@@ -82,5 +82,4 @@ waygraph chain "loginFlow" --step --no-autoplay
 
 Flags beat env: `--step` / `--no-step`, `--autoplay` / `--no-autoplay`,
 `--base-url <url>`, `--title <text>`. Default BASE_URL resolution order for
-`demo`: `--base-url` > `WAYGRAPH_BASE_URL` > `package.json` `waygraph.baseUrl`
-> `playwright.config` `baseURL`.
+`demo`: `--base-url` > `WAYGRAPH_BASE_URL` > `baseUrl` in `config/waygraph.config.ts`.

package/templates/quickstart/docs/HELPERS.md

@@ -99,7 +99,7 @@ branch(SubmitLoginActionBlock, {
 });
 ```
 
-Linear `defineFlow([start, …, end])` usually skips `branch()` (one happy path).
+A linear `map()` chain usually skips `branch()` (one happy path).
 
 ---
 

package/templates/quickstart/package.json

@@ -4,30 +4,30 @@
   "type": "module",
   "description": "Self-contained saucedemo quickstart (copied into a temp dir by `waygraph try demo`).",
   "scripts": {
+    "typecheck": "tsc --noEmit",
     "test": "waygraph test",
     "test:ui": "waygraph test ui",
-    "typecheck": "tsc --noEmit",
+    "flows": "waygraph list",
     "check": "waygraph check",
-    "auto": "waygraph auto",
-    "auto:cli": "waygraph auto --cli --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
-    "traverse": "waygraph traverse --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 40",
-    "traverse:parallel": "waygraph traverse --parallel 2 --session clone --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 30",
-    "traverse:coverage": "waygraph traverse --min-edge-coverage 10% --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --max-steps 40",
     "graph": "waygraph graph",
     "graph:mermaid": "waygraph graph --mermaid",
-    "demo": "waygraph demo --blocks \"loginFlow then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
-    "demo:auto-next": "waygraph demo --blocks \"loginFlow then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --auto-next",
-    "record": "waygraph run --blocks \"loginFlow then shopFlow({\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}) then viewerBlockedFlow({\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"locked_out_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}})\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --video --no-step",
-    "demo:bulk": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\"",
-    "demo:bulk:auto-next": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --auto-next --title \"Cart bulk demo\"",
-    "demo:bulk:video": "waygraph demo --blocks cartBulkFlow --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\" --auto-play-video --title \"Cart bulk demo\"",
-    "run:bulk": "waygraph run --blocks \"loginFlow then add-all-to-cart then remove-all-from-cart\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"}}\""
+    "auto": "waygraph auto",
+    "auto:cli": "waygraph auto --cli",
+    "demo": "waygraph demo --blocks \"loginFlow then shopFlow\"",
+    "demo:auto-next": "waygraph demo --blocks \"loginFlow then shopFlow\" --auto-next",
+    "demo:checkout": "waygraph demo --blocks checkoutFlow --auto-next",
+    "demo:device": "waygraph demo --blocks deviceShowcaseFlow --auto-next",
+    "demo:bulk": "waygraph demo --blocks cartBulkFlow --auto-next",
+    "demo:api": "waygraph demo --blocks apiDemoFlow --auto-next",
+    "demo:video": "waygraph demo --blocks deviceShowcaseFlow --auto-play-video",
+    "record": "waygraph run --blocks \"loginFlow then shopFlow\" --video --no-step",
+    "traverse": "waygraph traverse --max-steps 40"
   },
   "waygraph": {
     "baseUrl": "https://www.saucedemo.com"
   },
   "dependencies": {
-    "waygraph": "^0.12.20"
+    "waygraph": "latest"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

package/templates/quickstart/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/templates/quickstart/src/blocks/saucedemo-web/cart/nav-cart.block.ts

@@ -1,7 +1,5 @@
 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";
 
 /**
@@ -17,51 +15,4 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   checkpoint: "CartPage",
   click: CartSel.cartLink,
   verify: [Trait.url({ pathname: "/cart.html" })],
-  stubBefore: (ctx: StubCtx) => {
-    ctx.title("Open cart · landscape");
-    ctx.landscape();
-    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: CartSel.cartLink,
-        label: "Cart",
-        detail: "tone: planned (purple) - open cart",
-        tone: "planned",
-        focus: true,
-        zoomOut: false,
-        followMouse: false,
-        weight: "bold",
-        gesture: "tap",
-      },
-    });
-  },
-  stubAfter: (ctx: StubCtx) => {
-    ctx.banner("Your cart · desktop");
-    ctx.clearDevice();
-    ctx.hideTodos();
-    ctx.zoomOut(true);
-    ctx.ring("items", {
-      selector: InventorySel.cartItem,
-      label: "Cart items",
-      detail: "tone: success (green) - product in cart",
-      tone: "success",
-      focus: true,
-      zoomOut: true,
-      followMouse: false,
-      duration: true,
-    });
-  },
 });