waygraph 0.15.51 → 0.15.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.51",
+  "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,13 +20,15 @@ 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
 
 Change each `_nav.block.ts`'s `url` from the local `file://` path to a real one, and set a real
-`baseUrl` if your Nav Blocks use relative paths (`waygraph.config.ts`, a `.env`, or
-`package.json`'s `"waygraph"` field - see the main docs' "Project config" section). Keep each
+`baseUrl` if your Nav Blocks use relative paths (`config/waygraph.config.ts`, a `.env`, or
+`package.json`'s `"waygraph"` field - see the main docs' "Project config" section). That file also
+holds the test settings (`testDir`, `webServer`, `playwright: { workers, timeout, ... }`), so the
+project needs no `playwright.config.ts`. Keep each
 `src/map/` folder matching the URL it represents (`waygraph map` enforces this).
 
 Docs: https://deviate-dv8.github.io/waygraph/

package/templates/scaffold/STRUCTURE.md

@@ -7,6 +7,8 @@ Next.js route groups) and never appear in a URL or Checkpoint name.
 ```text
 .
 ├── package.json
+├── .agents/skills/                    # waygraph skills for coding agents
+├── config/waygraph.config.ts          # baseUrl, tests, extensions, webServer - no playwright.config
 ├── src/
 │   ├── map/
 │   │   ├── (app_base)/                # your app (opened via file:// here)
@@ -22,9 +24,13 @@ Next.js route groups) and never appear in a URL or Checkpoint name.
 │   │   │   │       ├── assert-hello.method.block.ts   # + stubs + YAP slide
 │   │   │   │       └── assert-item-added.method.block.ts
 │   │   │   └── docs/                  # a second page, same shape
-│   │   └── (external)/mailpit/        # a different origin (mail catcher)
+│   │   ├── (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
 ```
 
@@ -38,8 +44,8 @@ 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` |
-| Give a flow fake data | `registerMemStub(key, fake)` + `withMemStub(flow)` (docs: docs/REFERENCE.md, "memStub") |
+| 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

@@ -0,0 +1,45 @@
+import { Engine, defineConfig } from "waygraph";
+
+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__",
+
+  // ── waygraph: uncomment what you need ─────────────────────────────────────────────────────────
+  // extensions: ["hoppscotch"],             // browser extensions to load (a waygraph feature, not Playwright's)
+  // video: {                                // recordings made with `waygraph run|demo --video`
+  //   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,                            // 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
+  //   workers: 1,
+  //   retries: 1,
+  //   timeout: 60_000,
+  //   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,15 +13,15 @@
     "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": "^0.12.20"
+    "waygraph": "latest"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

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.
-- `withTitle`/`withHighlightFixtures`/`withSessionReset`/etc. are non-destructive wrappers -
-  `someFlow.withTitle("...")` doesn't mutate `someFlow`, it returns a new one. Compose them
-  around the finished `.end()` result, not inside the Map chain itself.
-- One flow, one scenario. A flow that needs a genuinely different starting session
-  (re-entering the login page mid-chain) wraps that segment in `withSessionReset`, 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/home/cart.flow.ts

@@ -0,0 +1,51 @@
+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";
+
+// `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" });
+})
+  .stubAfter((ctx) => {
+    ctx.ring("cart", {
+      selector: DemoSel.cartCount,
+      label: "AC · item in cart",
+      detail: "Cart count bumped after Add.",
+      tag: "AC",
+      duration: true,
+    });
+  })
+  .stubOnError((ctx) => {
+    ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart at failure", tag: "FAIL" });
+  });
+
+const RemoveShown = RemoveItemBlock.stubAfter((ctx) => {
+  ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart count", duration: true });
+});
+
+const ClearShown = ClearCartBlock.stubBefore((ctx) => {
+  ctx.ring("clear", { selector: DemoSel.clear, label: "Clear cart" });
+}).stubAfter((ctx) => {
+  ctx.ring("cart", { selector: DemoSel.cartCount, label: "Empty cart", duration: true });
+});
+
+export const homeCartFlow = engine
+  .map({ memStub: true })
+  .start()
+  .gotoPage(
+    NavHomeBlock.stubBefore((ctx) => {
+      ctx.title("Scaffold: Shop (Effect + clear)");
+    }),
+  )
+  .method(AddShown)
+  .assert(AssertItemAddedBlock)
+  .method(RemoveShown)
+  .method(AddShown)
+  .method(ClearShown)
+  .end();

package/templates/scaffold/src/flows/home/hello.flow.ts

@@ -0,0 +1,42 @@
+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";
+
+/** Smoke: nav + assert (no mem), then nav to the sibling docs/ page. Green offline. */
+export const homeHelloFlow = engine
+  .map()
+  .start()
+  .gotoPage(
+    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" });
+    }),
+  )
+  .assert(
+    AssertHelloBlock.stubBefore((ctx) => {
+      ctx.ring("title", { selector: DemoSel.title, label: "Heading about to check" });
+    })
+      .stubAfter((ctx) => {
+        ctx.ring("title", {
+          selector: DemoSel.title,
+          label: "AC · Hello visible",
+          detail: "Replace this copy with your ticket lines.",
+          tag: "AC",
+          duration: true,
+        });
+        ctx.ring("sub", { selector: DemoSel.sub, label: "Subcopy", duration: 1500 });
+      })
+      .stubOnError((ctx) => {
+        ctx.ring("title", { selector: DemoSel.title, label: "Heading at failure", tag: "FAIL" });
+      }),
+  )
+  .gotoPage(NavDocsBlock)
+  .end();

package/templates/scaffold/src/map/(app_base)/docs/_nav.block.ts

@@ -2,15 +2,6 @@ import { defineNavBlock, Trait } from "waygraph";
 import type { Docs } from "../../../states/demo.states.js";
 import { DocsSel, DOCS_URL } from "./_sel.js";
 
-/**
- * Kind: Nav
- * Route: (app_base)/docs/
- *
- * Same shape as home/ (its own file:// page, no server) - lives
- * under (app_base), not (external). See docs/REFERENCE.md "Waygraph Map" and
- * openspec/changes/waygraph-map. `(app_base)` is purely organizational
- * (Next.js route-group style) - never part of the Checkpoint tag.
- */
 export const NavDocsBlock = defineNavBlock<Docs>({
   name: "nav-docs",
   description: "Opens the docs page (Waygraph Map convention demo).",

package/templates/scaffold/src/map/(app_base)/docs/_page.block.ts

@@ -2,11 +2,6 @@ import { definePageBlock, Trait } from "waygraph";
 import type { Docs } from "../../../states/demo.states.js";
 import { DocsSel } from "./_sel.js";
 
-/**
- * Kind: Page
- * Route: (app_base)/docs/
- * Arrival-only (nav.block.ts already landed on Docs).
- */
 export const DocsPageBlock = definePageBlock<Docs>({
   name: "page-docs",
   description: "Docs hub - Waygraph Map convention demo.",

package/templates/scaffold/src/map/(app_base)/docs/_sel.ts

@@ -1,4 +1,4 @@
-// Relative to playwright.config.ts's baseURL (the (app_base) folder, set by `waygraph init`).
+// Relative to baseUrl in config/waygraph.config.ts (the (app_base) folder, set by `waygraph init`).
 export const DOCS_URL = "docs/index.html";
 
 export const DocsSel = {

package/templates/scaffold/src/map/(app_base)/home/_methods/add-item.effect.block.ts

@@ -7,14 +7,7 @@ import type { CanAddItem, ItemInCart } from "../../../../states/demo.states.js";
 import { SelectedItem } from "../../../../states/demo.mem-keys.js";
 import { DemoSel } from "../_sel.js";
 
-/**
- * Kind: Effect
- * Helper: defineEffectBlock
- * Route: demo-web/methods/
- *
- * Mutates one catalog row from mem. `waygraph auto` lists one "Add …" row per
- * live Add button via instanceOptions.
- */
+/** `waygraph auto` lists one "Add …" row per live Add button via `instanceOptions`. */
 export const AddItemBlock = defineEffectBlock<CanAddItem, ItemInCart>({
   name: "add-item",
   description: "Adds the mem-selected catalog item to the cart.",
@@ -36,7 +29,7 @@ export const AddItemBlock = defineEffectBlock<CanAddItem, ItemInCart>({
     ],
   },
   async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
-    const buttons = page.locator("button.add:not([hidden])");
+    const buttons = page.locator(DemoSel.addButtons);
     const n = await buttons.count();
     const out: WaygraphInstanceOption[] = [];
     for (let i = 0; i < n; i++) {
@@ -55,13 +48,4 @@ export const AddItemBlock = defineEffectBlock<CanAddItem, ItemInCart>({
     }
     return out;
   },
-})
-  .stubBefore((ctx) => {
-    ctx.ring("add", { selector: DemoSel.catalog, label: "Catalog" });
-  })
-  .stubAfter((ctx) => {
-    ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart count", duration: true });
-  })
-  .stubOnError((ctx) => {
-    ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart at failure", tag: "FAIL" });
-  });
+});

package/templates/scaffold/src/map/(app_base)/home/_methods/assert-hello.method.block.ts

@@ -2,15 +2,7 @@ import { defineAssertBlock, Trait } from "waygraph";
 import type { Home } from "../../../../states/demo.states.js";
 import { DemoSel } from "../_sel.js";
 
-/**
- * Kind: Assert
- * Helper: defineAssertBlock
- * Route: demo-web/methods/
- *
- * Self-loop-only "verify what's already on the page" check - no hand-written
- * act/resolve to accidentally do a second thing. Same-URL assert after nav,
- * with stubs + fixtures + a YAP slide.
- */
+/** Heading still shows after arrival; the slide is a YAP caption for the demo overlay. */
 export const AssertHelloBlock = defineAssertBlock<Home>({
   name: "assert-hello",
   description: "Confirms the hello heading is still visible after arrival.",
@@ -25,19 +17,4 @@ export const AssertHelloBlock = defineAssertBlock<Home>({
       duration: true,
     },
   ],
-})
-  .stubBefore((ctx) => {
-    ctx.ring("title", { selector: DemoSel.title, label: "Heading about to check" });
-  })
-  .stubAfter((ctx) => {
-    ctx.ring("title", {
-      selector: DemoSel.title,
-      label: "Hello confirmed",
-      detail: "Offline scaffold proof point.",
-      duration: true,
-    });
-    ctx.ring("sub", { selector: DemoSel.sub, label: "Subcopy", duration: 1500 });
-  })
-  .stubOnError((ctx) => {
-    ctx.ring("title", { selector: DemoSel.title, label: "Heading at failure", tag: "FAIL" });
-  });
+});

package/templates/scaffold/src/map/(app_base)/home/_methods/assert-item-added.method.block.ts

@@ -3,11 +3,7 @@ import type { ItemInCart } from "../../../../states/demo.states.js";
 import { SelectedItem } from "../../../../states/demo.mem-keys.js";
 import { DemoSel } from "../_sel.js";
 
-/**
- * Mem-aware Trait: which item's Remove button should be visible depends on
- * which row add-item just acted on (mem, not a static selector) - a Trait's
- * own `check(page, mem)` already receives mem, so this reads it directly.
- */
+// Reads mem at check time, so it follows whichever item add-item acted on.
 const removeButtonVisibleForSelectedItem: TraitType = {
   name: "remove-button-visible-for-selected-item",
   async check(page, mem) {
@@ -16,20 +12,7 @@ const removeButtonVisibleForSelectedItem: TraitType = {
   },
 };
 
-/**
- * Kind: Assert
- * Helper: defineAssertBlock
- * Route: demo-web/methods/
- *
- * "Did add-item actually work" - provable only after the fact, from the
- * method's real effect on the page: the specific row's own Remove button
- * appeared (mem-matched, not just "some" row), AND the aggregate cart count
- * reflects it. Self-loop on ItemInCart - no state change, verify only.
- *
- * Explicit `<ItemInCart>` type argument - `defineAssertBlock` defaults to
- * wildcard `Checkpoint<string>` when uninferred, which only "works" when the
- * assert sits last in a chain; this one sits mid-chain (see shop.flow.ts).
- */
+/** The mem-selected item's own Remove button appeared and the cart count reflects it. */
 export const AssertItemAddedBlock = defineAssertBlock<ItemInCart>({
   name: "assert-item-added",
   description: "Confirms the mem-selected item's own Remove button appeared and the cart count reflects it.",