waygraph 0.15.52 → 0.15.54

package/templates/quickstart/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/templates/quickstart/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/templates/quickstart/tests/chain-flow.spec.ts

@@ -1,5 +1,6 @@
 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 { viewerBlockedFlow } from "../src/flows/viewer-blocked.flow.js";
@@ -7,12 +8,12 @@ import { LoginCreds, SelectedItem } from "../src/states/checkout.mem-keys.js";
 
 const BACKPACK = SelectedItem({ id: "sauce-labs-backpack", name: "Sauce Labs Backpack" });
 
-test("chainFlow: Episode 1 signs in + shops, Episode 2 locked-out user stays on LoginPage", async () => {
+test("nested flows: Episode 1 signs in + shops, Episode 2 locked-out user stays on LoginPage", async () => {
   const mem = new MemPage();
   mem.set(LoginCreds({ username: "standard_user", password: "secret_sauce" }));
   mem.set(BACKPACK);
 
-  const ep1 = chainFlow(loginFlow, shopFlow);
+  const ep1 = engine.map().start().flow(loginFlow).flow(shopFlow).end();
   const result1 = await ep1.run(mem);
   expect(result1).toEqual(checkpoint("OrderComplete"));
 
@@ -26,16 +27,12 @@ test("shopFlow alone: already-seeded SelectedItem completes checkout after login
   mem.set(LoginCreds({ username: "standard_user", password: "secret_sauce" }));
   mem.set(BACKPACK);
 
-  const result = await chainFlow(loginFlow, shopFlow).run(mem);
+  const result = await engine.map().start().flow(loginFlow).flow(shopFlow).end().run(mem);
   expect(result).toEqual(checkpoint("OrderComplete"));
 });
 
-test("chainFlow blocks() lists the flattened episode chain in order", () => {
-  expect(loginFlow.title).toBe("Sign In");
-  expect(shopFlow.title).toBe("Shop & Checkout");
-  expect(viewerBlockedFlow.title).toBe("Viewer: Blocked Login Attempt");
-
-  const blocks = chainFlow(loginFlow, shopFlow, viewerBlockedFlow).blocks();
+test("blocks() lists the flattened episode chain in order", () => {
+  const blocks = engine.map().start().flow(loginFlow).flow(shopFlow).flow(viewerBlockedFlow).end().blocks();
   expect(blocks.map((b) => b.name)).toEqual([
     "nav-login",
     "fill-username",

package/templates/scaffold/README.md

@@ -20,7 +20,7 @@ More: `npm run check` (lint your Blocks), `npm run graph` (see the whole graph),
 ## Where things live
 
 See [STRUCTURE.md](./STRUCTURE.md). Short version: one folder per page under `src/map/`,
-one Block per action, flows in `src/flows/`.
+one Block per action, one flow per use case in `src/flows/` (a folder per page: its success, its failures, its bad inputs).
 
 ## Point it at your real app
 

package/templates/scaffold/STRUCTURE.md

@@ -27,7 +27,10 @@ Next.js route groups) and never appear in a URL or Checkpoint name.
 │   │   ├── (external)/mailpit/        # a different origin (mail catcher)
 │   │   └── (external)/hoppscotch/     # API client, REST client, needs the hoppscotch extension
 │   ├── states/                        # Checkpoint types + mem keys
-│   └── flows/                         # example / shop / mail-verify
+│   └── flows/                         # use cases, one file per scenario (see flows/README.md)
+│       ├── home/                      #   a page: hello, cart
+│       ├── (user-stories)/            #   flows that cross pages
+│       └── (external)/hoppscotch/     #   a tool on another origin
 └── tests/example.spec.ts
 ```
 
@@ -41,7 +44,7 @@ page folder uses, so any agent or teammate knows where to look without asking.
 | Add a page | copy a folder under `src/map/`, keep the `_nav` / `_page` / `_sel` names |
 | Add an action on a page | one file in that page's `_methods/` |
 | Verify a state (button disabled, error shown) | `defineAssertBlock` + `Trait.disabled` / `Trait.enabled` |
-| Wire steps together | `src/flows/*.flow.ts` |
+| Define a use case (success, failed, bad input) | one `*.flow.ts` in `src/flows/<page>/`, or `(user-stories)/` for one that crosses pages |
 | Give a flow fake data | `registerMemStub(key, fake)` + `memStub: true` in the flow's options (docs: docs/REFERENCE.md, "memStub") |
 | Explore by hand | `npm run auto` (headed) or `npm run auto:cli` |
 | Check your work | `npm run check`, `npm run graph`, `waygraph map` |

package/templates/scaffold/config/waygraph.config.ts

@@ -1,6 +1,6 @@
-import { defineConfig } from "waygraph";
+import { Engine, defineConfig } from "waygraph";
 
-export default defineConfig(({ env }) => ({
+const config = defineConfig(({ env }) => ({
   // Where the app under test lives. BASE_URL comes from .env / .env.<mode>:  waygraph test --env staging
   baseUrl: env.BASE_URL ?? "__APP_BASE_URL__",
 
@@ -10,11 +10,25 @@ export default defineConfig(({ env }) => ({
   //   dir: "~/Downloads/waygraph-videos",   //   where they are saved (default: Downloads/waygraph-videos/<project>)
   //   viewport: "1920x1080",                //   recording size: demo defaults to 1920x1080, run to 1280x720
   // },
-  // slowMo: 250,                            // ms to pause before each browser action, so a run is watchable
-  // headed: true,                           // show the browser window (demo and auto already do)
-  // demo: { autoNext: true, fast: false },  // advance demo steps without clicking Next; blitz fast-forward steps
+  // slowMo: 250,                            // shared by run and demo: ms to pause around each browser action
+  // headed: true,                           // shared: show the browser window (demo and auto already do)
+  // run: {                                  // `waygraph run` only; overrides the shared values above
+  //   slowMo: 0,
+  //   video: { viewport: "1280x720" },
+  // },
+  // demo: {                                 // `waygraph demo` only; overrides the shared values above
+  //   pace: "fast",                         //   default pace for steps that set none: "fast" | "slow" | "blitz" | 0.5 | 2
+  //   speeds: { blitz: 0.05, fast: 0.33, slow: 2 },   // what each pace means, x normal dwell (lower = faster)
+  //   typingMs: 30,                         //   typing animation, ms per character (0 types instantly)
+  //   slowMo: 350,                          //   pause after each action, once per action (a step with pace "blitz" skips it)
+  //   autoNext: true,                       //   advance steps without clicking Next
+  //   fast: false,                          //   shorter Next / auto-next gates
+  //   video: { viewport: "1920x1080" },
+  // },
   // webServer: { command: "npm start", port: 3000 },   // started around test / run / demo / auto
 
+  // Another config for another environment: config/waygraph.staging.config.ts, chosen with `waygraph test --config staging`.
+
   // ── test runner (Playwright) ──────────────────────────────────────────────────────────────────
   // testDir: "tests",
   // playwright: {                           // any Playwright test option, merged over waygraph's defaults
@@ -24,3 +38,8 @@ export default defineConfig(({ env }) => ({
   //   use: { video: "on", trace: "on", screenshot: "only-on-failure", viewport: { width: 1280, height: 720 } },
   // },
 }));
+
+export default config;
+
+// Flows import this, so they run with the config above already applied.
+export const engine = new Engine(config);

package/templates/scaffold/package.json

@@ -13,12 +13,12 @@
     "graph:mermaid": "waygraph graph --mermaid",
     "auto": "waygraph auto",
     "auto:cli": "waygraph auto --cli",
-    "demo": "waygraph demo --blocks exampleFlow",
-    "demo:auto-next": "waygraph demo --blocks exampleFlow --auto-next",
-    "demo:shop": "waygraph demo --blocks shopFlow",
-    "demo:shop:auto-next": "waygraph demo --blocks shopFlow --auto-next",
-    "run": "waygraph run --blocks exampleFlow",
-    "run:shop": "waygraph run --blocks shopFlow"
+    "demo": "waygraph demo --blocks homeHelloFlow",
+    "demo:auto-next": "waygraph demo --blocks homeHelloFlow --auto-next",
+    "demo:shop": "waygraph demo --blocks homeCartFlow",
+    "demo:shop:auto-next": "waygraph demo --blocks homeCartFlow --auto-next",
+    "run": "waygraph run --blocks homeHelloFlow",
+    "run:shop": "waygraph run --blocks homeCartFlow"
   },
   "dependencies": {
     "waygraph": "latest"

package/templates/scaffold/src/flows/(external)/hoppscotch/auth.flow.ts

@@ -0,0 +1,36 @@
+import { engine } from "../../../../config/waygraph.config.js";
+import { NavHoppscotchSettingsBlock } from "../../../map/(external)/hoppscotch/settings/_nav.block.js";
+import { PickExtensionInterceptorBlock } from "../../../map/(external)/hoppscotch/_methods/pick-extension-interceptor.method.block.js";
+import { NavHoppscotchRestBlock } from "../../../map/(external)/hoppscotch/_nav.block.js";
+import { SetQueryParamsBlock } from "../../../map/(external)/hoppscotch/_methods/set-query-params.method.block.js";
+import { SetUrlBlock } from "../../../map/(external)/hoppscotch/_methods/set-url.method.block.js";
+import { SetBearerTokenBlock } from "../../../map/(external)/hoppscotch/_methods/set-bearer-token.method.block.js";
+import { SendRequestBlock } from "../../../map/(external)/hoppscotch/_methods/send-request.method.block.js";
+import { AssertStatusBlock } from "../../../map/(external)/hoppscotch/_methods/assert-status.method.block.js";
+import { ReadResponseHeadersBlock } from "../../../map/(external)/hoppscotch/_methods/read-response-headers.method.block.js";
+import { AssertResponseHeaderBlock } from "../../../map/(external)/hoppscotch/_methods/assert-response-header.method.block.js";
+import { ReadResponseBodyBlock } from "../../../map/(external)/hoppscotch/_methods/read-response-body.method.block.js";
+import { AssertResponseBodyBlock } from "../../../map/(external)/hoppscotch/_methods/assert-response-body.method.block.js";
+import "../../../map/(external)/hoppscotch/_page.block.js";
+
+/** GET with query params and a bearer token, check the status, that the API received them, and a response header. Needs `extensions: ["hoppscotch"]`. */
+export const hoppscotchAuthFlow = engine
+  .map()
+  .start()
+  .gotoExternal(
+    NavHoppscotchSettingsBlock.stubBefore((ctx) => {
+      ctx.title("Scaffold: Hoppscotch GET with query params and bearer token");
+    }),
+  )
+  .method(PickExtensionInterceptorBlock)
+  .gotoExternal(NavHoppscotchRestBlock)
+  .method(SetUrlBlock)
+  .method(SetQueryParamsBlock)
+  .method(SetBearerTokenBlock)
+  .method(SendRequestBlock)
+  .assert(AssertStatusBlock)
+  .method(ReadResponseBodyBlock)
+  .assert(AssertResponseBodyBlock)
+  .method(ReadResponseHeadersBlock)
+  .assert(AssertResponseHeaderBlock)
+  .end();

package/templates/scaffold/src/flows/(external)/hoppscotch/get.flow.ts

@@ -0,0 +1,24 @@
+import { engine } from "../../../../config/waygraph.config.js";
+import { NavHoppscotchSettingsBlock } from "../../../map/(external)/hoppscotch/settings/_nav.block.js";
+import { PickExtensionInterceptorBlock } from "../../../map/(external)/hoppscotch/_methods/pick-extension-interceptor.method.block.js";
+import { NavHoppscotchRestBlock } from "../../../map/(external)/hoppscotch/_nav.block.js";
+import { SetUrlBlock } from "../../../map/(external)/hoppscotch/_methods/set-url.method.block.js";
+import { SendRequestBlock } from "../../../map/(external)/hoppscotch/_methods/send-request.method.block.js";
+import { AssertStatusBlock } from "../../../map/(external)/hoppscotch/_methods/assert-status.method.block.js";
+import "../../../map/(external)/hoppscotch/_page.block.js";
+
+/** GET a URL and check the status. Needs `extensions: ["hoppscotch"]` in waygraph.config.ts. */
+export const hoppscotchGetFlow = engine
+  .map()
+  .start()
+  .gotoExternal(
+    NavHoppscotchSettingsBlock.stubBefore((ctx) => {
+      ctx.title("Scaffold: Hoppscotch GET");
+    }),
+  )
+  .method(PickExtensionInterceptorBlock)
+  .gotoExternal(NavHoppscotchRestBlock)
+  .method(SetUrlBlock)
+  .method(SendRequestBlock)
+  .assert(AssertStatusBlock)
+  .end();

package/templates/scaffold/src/flows/(external)/hoppscotch/post.flow.ts

@@ -0,0 +1,34 @@
+import { engine } from "../../../../config/waygraph.config.js";
+import { NavHoppscotchSettingsBlock } from "../../../map/(external)/hoppscotch/settings/_nav.block.js";
+import { PickExtensionInterceptorBlock } from "../../../map/(external)/hoppscotch/_methods/pick-extension-interceptor.method.block.js";
+import { NavHoppscotchRestBlock } from "../../../map/(external)/hoppscotch/_nav.block.js";
+import { SetMethodBlock } from "../../../map/(external)/hoppscotch/_methods/set-method.method.block.js";
+import { SetUrlBlock } from "../../../map/(external)/hoppscotch/_methods/set-url.method.block.js";
+import { SetHeadersBlock } from "../../../map/(external)/hoppscotch/_methods/set-headers.method.block.js";
+import { SetJsonBodyBlock } from "../../../map/(external)/hoppscotch/_methods/set-json-body.method.block.js";
+import { SendRequestBlock } from "../../../map/(external)/hoppscotch/_methods/send-request.method.block.js";
+import { AssertStatusBlock } from "../../../map/(external)/hoppscotch/_methods/assert-status.method.block.js";
+import { ReadResponseBodyBlock } from "../../../map/(external)/hoppscotch/_methods/read-response-body.method.block.js";
+import { AssertResponseBodyBlock } from "../../../map/(external)/hoppscotch/_methods/assert-response-body.method.block.js";
+import "../../../map/(external)/hoppscotch/_page.block.js";
+
+/** POST JSON with a header, check the status and the response body. Needs `extensions: ["hoppscotch"]`. */
+export const hoppscotchPostFlow = engine
+  .map()
+  .start()
+  .gotoExternal(
+    NavHoppscotchSettingsBlock.stubBefore((ctx) => {
+      ctx.title("Scaffold: Hoppscotch POST with header and JSON body");
+    }),
+  )
+  .method(PickExtensionInterceptorBlock)
+  .gotoExternal(NavHoppscotchRestBlock)
+  .method(SetMethodBlock)
+  .method(SetUrlBlock)
+  .method(SetHeadersBlock)
+  .method(SetJsonBodyBlock)
+  .method(SendRequestBlock)
+  .assert(AssertStatusBlock)
+  .method(ReadResponseBodyBlock)
+  .assert(AssertResponseBodyBlock)
+  .end();

package/templates/scaffold/src/flows/(user-stories)/email-verification.flow.ts

@@ -0,0 +1,47 @@
+import { engine } from "../../../config/waygraph.config.js";
+import { NavMailpitInboxBlock } from "../../map/(external)/mailpit/_nav.block.js";
+import { AssertEmailReceivedBlock } from "../../map/(external)/mailpit/_methods/assert-email-received.method.block.js";
+import { OpenMessageBlock } from "../../map/(external)/mailpit/_methods/open-message.method.block.js";
+import { AssertEmailContentBlock } from "../../map/(external)/mailpit/_methods/assert-email-content.method.block.js";
+import { ExtractEmailLinkBlock } from "../../map/(external)/mailpit/_methods/extract-email-link.method.block.js";
+import { NavVerificationLinkBlock } from "../../map/(app_base)/home/nav-verification-link.block.js";
+import "../../map/(external)/mailpit/_page.block.js";
+import { MailpitSel } from "../../map/(external)/mailpit/_sel.js";
+
+/** Needs a Mailpit at WAYGRAPH_MAIL_URL (default http://127.0.0.1:8025); tests/mail-verify.spec.ts starts one. */
+export const emailVerificationFlow = engine
+  .map()
+  .start()
+  .gotoExternal(
+    NavMailpitInboxBlock.stubBefore((ctx) => {
+      ctx.title("Scaffold: Cross-origin mail verification (QA-rich)");
+    }),
+  )
+  .assert(
+    AssertEmailReceivedBlock.stubAfter((ctx) => {
+      ctx.ring("note", {
+        selector: MailpitSel.messageRow,
+        label: "AC · email arrived",
+        detail: "Confirmed before opening anything.",
+        tag: "AC",
+      });
+    }),
+  )
+  .method(OpenMessageBlock)
+  .assert(
+    AssertEmailContentBlock.stubAfter((ctx) => {
+      ctx.ring("note", { selector: MailpitSel.previewIframe, label: "AC · email body matches expected copy", tag: "AC" });
+    }),
+  )
+  .method(
+    ExtractEmailLinkBlock.stubAfter((ctx) => {
+      ctx.ring("note", {
+        selector: MailpitSel.previewIframe,
+        label: "AC · link found",
+        detail: "Read from the message preview iframe.",
+        tag: "AC",
+      });
+    }),
+  )
+  .gotoPage(NavVerificationLinkBlock)
+  .end();

package/templates/scaffold/src/flows/README.md

@@ -1,18 +1,39 @@
 # `src/flows/`
 
-A `*.flow.ts` composes Blocks from `src/map/` into a runnable path - `waygraph run`/`demo`/`test`
-all point at an export here by name (`waygraph run --blocks shopFlow`).
+A flow is one **use case**: a path a user takes through the app, with its own pass or fail. `waygraph run`, `demo` and
+`test` all point at an export here by name (`waygraph run --blocks homeCartFlow`).
 
-- Prefer `new Engine().map()...end()` (the Map builder: `.gotoPage()`/`.method()`/`.assert()`/
-  `.branch()`) over hand-composing raw Blocks - it checks each step's Block kind at runtime and
-  the Checkpoint chain at compile time, so a wrong step is a build/test failure, not a
-  mid-run surprise.
-- Flow settings go in `.end({ title, memStub, sessionReset })`. No nested `withTitle(withMemStub(...))`.
-- Demo highlights are ctx stubs chained on the Block where the flow uses it:
-  `AddItemBlock.stubAfter((ctx) => { ctx.ring("cart", { selector, label }); })`.
-- One flow, one scenario. A flow that needs a genuinely different starting session
-  (re-entering the login page mid-chain) sets `sessionReset: true`, rather than hand-clearing
-  cookies inside a Block.
+## The folder mocks the front end
 
-New flow → new file here, named for the scenario (`checkout.flow.ts`), not for the Blocks it
-happens to use.
+`src/flows/` mirrors the app's endpoints the way `src/map/` does, but where the map holds the *pieces* of a page, a flow
+folder holds the *stories* of it. One folder per page or area, one file per use case. The scaffold only has the demo pages, so `auth/login/` below is the shape to copy for a real login page:
+
+```text
+src/flows/
+  auth/login/
+    success.flow.ts          # valid credentials -> dashboard
+    wrong-password.flow.ts   # refused, error banner, stays on login
+    empty-fields.flow.ts     # each required field flags itself
+  home/
+    hello.flow.ts
+    cart.flow.ts
+  (user-stories)/            # not a page: a story that crosses pages
+    email-verification.flow.ts
+  (external)/hoppscotch/     # a tool on another origin
+    post.flow.ts
+```
+
+- **`<area>/<page>/`** matches the app URL, like the map. Open the folder and you see every way a user can go through that
+  page: the happy path, each failure, each bad input.
+- **`(user-stories)/`** (any `(group)` name) is for flows that don't belong to one page: checkout end to end, onboarding,
+  "a viewer is locked out". Parentheses mean organizational only, as in the map.
+- **A file is one scenario**, named for the outcome (`success`, `wrong-password`), not for the Blocks it happens to use.
+  An export is `<page><Outcome>Flow` (`loginWrongPasswordFlow`) so `--blocks` names stay unique across the project; a file path works too (`waygraph run src/flows/auth/login/success.flow.ts`).
+
+## Writing one
+
+- Build it with `engine.map({ memStub })…end()`; nest another with `.flow(sub, { reset: true })`. No `defineFlow([...])`,
+  no nested `withTitle(withMemStub(...))`, and `.end()` takes nothing.
+- The flow's name and narration are ctx stubs chained on the Block where they apply: `ctx.title("…")`, `ctx.ring(…)`.
+- A flow expected to fail (a locked-out user) says so in `map({ expectedFailure: "…" })`.
+- A step's speed in the demo is `{ pace }`: `.method(FillBlock, { pace: "blitz" })`.

package/templates/scaffold/src/flows/{shop.flow.ts → home/cart.flow.ts}

@@ -1,17 +1,14 @@
-import { Engine } from "waygraph";
-import config from "../../config/waygraph.config.js";
-import { DemoSel } from "../map/(app_base)/home/_sel.js";
-import { NavHomeBlock } from "../map/(app_base)/home/_nav.block.js";
-import { AddItemBlock } from "../map/(app_base)/home/_methods/add-item.effect.block.js";
-import { AssertItemAddedBlock } from "../map/(app_base)/home/_methods/assert-item-added.method.block.js";
-import { RemoveItemBlock } from "../map/(app_base)/home/_methods/remove-item.effect.block.js";
-import { ClearCartBlock } from "../map/(app_base)/home/_methods/clear-cart.method.block.js";
-import "../states/demo.mem-stubs.js";
-import "../map/(app_base)/home/_page.block.js";
+import { engine } from "../../../config/waygraph.config.js";
+import { DemoSel } from "../../map/(app_base)/home/_sel.js";
+import { NavHomeBlock } from "../../map/(app_base)/home/_nav.block.js";
+import { AddItemBlock } from "../../map/(app_base)/home/_methods/add-item.effect.block.js";
+import { AssertItemAddedBlock } from "../../map/(app_base)/home/_methods/assert-item-added.method.block.js";
+import { RemoveItemBlock } from "../../map/(app_base)/home/_methods/remove-item.effect.block.js";
+import { ClearCartBlock } from "../../map/(app_base)/home/_methods/clear-cart.method.block.js";
+import "../../states/demo.mem-stubs.js";
+import "../../map/(app_base)/home/_page.block.js";
 
-const engine = new Engine(config);
-
-// `memStub: true` fills SelectedItem (alpha) from src/states/demo.mem-stubs.ts; --data overrides it.
+// `map({ memStub: true })` fills SelectedItem (alpha) from src/states/demo.mem-stubs.ts; --data overrides it.
 const AddShown = AddItemBlock.stubBefore((ctx) => {
   ctx.ring("add", { selector: DemoSel.catalog, label: "Catalog" });
 })
@@ -38,13 +35,17 @@ const ClearShown = ClearCartBlock.stubBefore((ctx) => {
   ctx.ring("cart", { selector: DemoSel.cartCount, label: "Empty cart", duration: true });
 });
 
-export const shopFlow = engine
-  .map()
+export const homeCartFlow = engine
+  .map({ memStub: true })
   .start()
-  .gotoPage(NavHomeBlock)
+  .gotoPage(
+    NavHomeBlock.stubBefore((ctx) => {
+      ctx.title("Scaffold: Shop (Effect + clear)");
+    }),
+  )
   .method(AddShown)
   .assert(AssertItemAddedBlock)
   .method(RemoveShown)
   .method(AddShown)
   .method(ClearShown)
-  .end({ title: "Scaffold: Shop (Effect + clear)", sessionReset: true, memStub: true });
+  .end();