waygraph 0.15.52 → 0.15.53

package/dist/session/pilot.js

@@ -29,7 +29,7 @@
  * new execution primitive.
  */
 import { discoverGraph } from "../analysis/graph.js";
-import { requestSession, listBrowserSessions, resolveSessionMeta, } from "./auto-session-ipc.js";
+import { requestSession, resolveSessionMeta, } from "./auto-session-ipc.js";
 import { browserStart } from "./browser.js";
 /**
  * Starts a detached session and reads back its own graph + starting
@@ -77,4 +77,3 @@ export async function pilotAttach(projectDir, sessionId, inject) {
         snapshot: status.snapshot,
     };
 }
-export { listBrowserSessions };

package/dist/traverse/coverage.d.ts

@@ -27,10 +27,6 @@ export interface TraverseCoverageReport {
         leaf?: string;
     }>;
 }
-/** Static graph edge key = Block runtime name. */
-export declare function edgeKeyFromGraphEdge(edge: {
-    block: string;
-}): string;
 /** Collect unique edge keys from a WaygraphGraph-like edges list. */
 export declare function collectGraphEdgeKeys(edges: ReadonlyArray<{
     block: string;

package/dist/traverse/coverage.js

@@ -10,7 +10,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 /** Static graph edge key = Block runtime name. */
-export function edgeKeyFromGraphEdge(edge) {
+function edgeKeyFromGraphEdge(edge) {
     return edge.block;
 }
 /** Collect unique edge keys from a WaygraphGraph-like edges list. */

package/dist/types.d.ts

@@ -2,7 +2,7 @@ import type { Page } from "@playwright/test";
 import type { MemPage, MemKey } from "./mem-page.js";
 import type { Trait } from "./trait.js";
 import type { HighlightStubPhaseOrFn, WaygraphHighlight, WaygraphSlidesOrFn } from "./highlights.js";
-export type { WaygraphHighlight, WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, HighlightStubPhase, HighlightStubPhaseOrFn, HighlightFixtureMap, ResolvedHighlight, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, WaygraphTodoItem, WaygraphTodoInput, } from "./highlights.js";
+export type { WaygraphHighlight } from "./highlights.js";
 /**
  * A Checkpoint is identified solely by its string tag - a phantom marker with no
  * embedded data. Two Checkpoints with the same tag are the same state everywhere.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.52",
+  "version": "0.15.53",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
@@ -48,16 +48,18 @@
     "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"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"
@@ -70,6 +72,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/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();

package/templates/scaffold/src/flows/{example.flow.ts → home/hello.flow.ts}

@@ -1,21 +1,20 @@
-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 { AssertHelloBlock } from "../map/(app_base)/home/_methods/assert-hello.method.block.js";
-import { NavDocsBlock } from "../map/(app_base)/docs/_nav.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 { AssertHelloBlock } from "../../map/(app_base)/home/_methods/assert-hello.method.block.js";
+import { NavDocsBlock } from "../../map/(app_base)/docs/_nav.block.js";
 // Page hubs registered for auto/docs grouping (arrival-only after nav).
-import "../map/(app_base)/home/_page.block.js";
-import "../map/(app_base)/docs/_page.block.js";
-
-const engine = new Engine(config);
+import "../../map/(app_base)/home/_page.block.js";
+import "../../map/(app_base)/docs/_page.block.js";
 
 /** Smoke: nav + assert (no mem), then nav to the sibling docs/ page. Green offline. */
-export const exampleFlow = engine
+export const homeHelloFlow = engine
   .map()
   .start()
   .gotoPage(
-    NavHomeBlock.stubAfter((ctx) => {
+    NavHomeBlock.stubBefore((ctx) => {
+      ctx.title("Scaffold: Hello Waygraph");
+    }).stubAfter((ctx) => {
       ctx.ring("title", { selector: DemoSel.title, label: "Home heading", duration: true });
     }).stubOnError((ctx) => {
       ctx.ring("title", { selector: DemoSel.title, label: "Home heading at failure" });
@@ -40,4 +39,4 @@ export const exampleFlow = engine
       }),
   )
   .gotoPage(NavDocsBlock)
-  .end({ title: "Scaffold: Hello Waygraph" });
+  .end();

package/templates/scaffold/tests/example.spec.ts

@@ -1,16 +1,16 @@
 import { test, expect } from "@playwright/test";
 import { MemPage, checkpoint, seedMemStub } from "waygraph";
-import { exampleFlow } from "../src/flows/example.flow.js";
-import { shopFlow } from "../src/flows/shop.flow.js";
+import { homeHelloFlow } from "../src/flows/home/hello.flow.js";
+import { homeCartFlow } from "../src/flows/home/cart.flow.js";
 
 test("example flow reaches Docs (home -> assert -> sibling docs/ page)", async ({ context }) => {
-  const result = await exampleFlow.run(context, new MemPage());
+  const result = await homeHelloFlow.run(context, new MemPage());
   expect(result).toEqual(checkpoint("Docs"));
 });
 
 test("shop flow adds then clears (Effect + Method)", async ({ context }) => {
   const mem = new MemPage();
-  seedMemStub(mem, shopFlow);
-  const result = await shopFlow.run(context, mem);
+  seedMemStub(mem, homeCartFlow);
+  const result = await homeCartFlow.run(context, mem);
   expect(result).toEqual(checkpoint("CartEmpty"));
 });

package/templates/scaffold/tests/hoppscotch.spec.ts

@@ -2,9 +2,9 @@ import { test, expect } from "@playwright/test";
 import { createServer, type Server } from "node:http";
 import { MemPage, checkpoint } from "waygraph";
 import config from "../config/waygraph.config.js";
-import { hoppscotchGetFlow } from "../src/flows/hoppscotch-get.flow.js";
-import { hoppscotchAuthFlow } from "../src/flows/hoppscotch-auth.flow.js";
-import { hoppscotchPostFlow } from "../src/flows/hoppscotch-post.flow.js";
+import { hoppscotchGetFlow } from "../src/flows/(external)/hoppscotch/get.flow.js";
+import { hoppscotchAuthFlow } from "../src/flows/(external)/hoppscotch/auth.flow.js";
+import { hoppscotchPostFlow } from "../src/flows/(external)/hoppscotch/post.flow.js";
 import {
   ExpectedResponseHeader,
   ExpectedResponseText,

package/templates/scaffold/tests/mail-verify.spec.ts

@@ -2,12 +2,12 @@ import { test, expect } from "@playwright/test";
 import { spawnSync } from "node:child_process";
 import net from "node:net";
 import { MemPage, checkpoint } from "waygraph";
-import { mailVerifyFlow } from "../src/flows/mail-verify.flow.js";
+import { emailVerificationFlow } from "../src/flows/(user-stories)/email-verification.flow.js";
 import { ExpectedRecipient, ExpectedLinkPattern, ExpectedEmailContent } from "../src/states/demo.mem-keys.js";
 import { HOME_URL } from "../src/map/(app_base)/home/_sel.js";
 
 // Plays "the app sent a verification email": starts a throwaway Mailpit container, sends a real SMTP message,
-// then runs mailVerifyFlow against it, including the no-email and wrong-content failure paths.
+// then runs emailVerificationFlow against it, including the no-email and wrong-content failure paths.
 
 function runMailpit(): { containerId: string; smtpPort: number; httpPort: number } {
   const run = spawnSync("docker", ["run", "--rm", "-d", "-p", "0:1025", "-p", "0:8025", "axllent/mailpit"], {
@@ -80,7 +80,7 @@ async function withMailpit<T>(fn: (opts: { httpPort: number; smtpPort: number })
 
 const VERIFICATION_CONTENT = "Please confirm your email address to finish setting up your account.";
 
-test("mailVerifyFlow: confirms arrival, confirms content, reads the real link, navigates to it", async ({
+test("emailVerificationFlow: confirms arrival, confirms content, reads the real link, navigates to it", async ({
   context,
 }) => {
   test.skip(!dockerAvailable(), "Docker not reachable in this environment");
@@ -100,7 +100,7 @@ test("mailVerifyFlow: confirms arrival, confirms content, reads the real link, n
     mem.set(ExpectedRecipient({ email: recipient }));
     mem.set(ExpectedLinkPattern, "verified=1");
     mem.set(ExpectedEmailContent, VERIFICATION_CONTENT);
-    const result = await mailVerifyFlow.run(context, mem);
+    const result = await emailVerificationFlow.run(context, mem);
     expect(result).toEqual(checkpoint("HomeVerified"));
   });
 });
@@ -130,7 +130,7 @@ test("the same four mail-reading Blocks handle a second, unrelated email scenari
     mem.set(ExpectedRecipient({ email: recipient }));
     mem.set(ExpectedLinkPattern, "verified=1");
     mem.set(ExpectedEmailContent, resetContent);
-    const result = await mailVerifyFlow.run(context, mem);
+    const result = await emailVerificationFlow.run(context, mem);
     expect(result).toEqual(checkpoint("HomeVerified"));
   });
 });
@@ -149,7 +149,7 @@ test("assert-email-received fails loud, naming itself, when no email ever arrive
     // not just the leaf Block - real, useful QA context, not a bug - so this
     // matches the accumulated name ending at assert-email-received, not an
     // exact "failed after \"assert-email-received\"" alone.
-    await expect(mailVerifyFlow.run(context, mem)).rejects.toThrow(
+    await expect(emailVerificationFlow.run(context, mem)).rejects.toThrow(
       /trait "email-received" failed after ".*assert-email-received"/,
     );
   });
@@ -175,7 +175,7 @@ test("assert-email-content fails loud, naming itself, when the email's copy does
     mem.set(ExpectedRecipient({ email: recipient }));
     mem.set(ExpectedLinkPattern, "verified=1");
     mem.set(ExpectedEmailContent, VERIFICATION_CONTENT);
-    await expect(mailVerifyFlow.run(context, mem)).rejects.toThrow(
+    await expect(emailVerificationFlow.run(context, mem)).rejects.toThrow(
       /trait "body-contains-expected-text" failed after ".*assert-email-content"/,
     );
   });