waygraph 0.12.6 → 0.12.7

package/README.md

@@ -89,7 +89,8 @@ Live reference: `examples/saucedemo/src/blocks/saucedemo-web/inventory/`
 |------|---------|
 | Watch Sauce Demo step-through (temp dir only) | `npx waygraph try demo` |
 | Interactive explore (Add/Remove/Open details from live page) | `cd examples/saucedemo && npm i && npx waygraph auto` |
-| Scaffold a new **offline** project (green `npm test` on a `data:` URL) | `npx create-waygraph my-app` **or** `npx waygraph init my-app` |
+| Scaffold a new **offline** project (green `npm test` on local fixture `:4177`) | `npx create-waygraph my-app` **or** `npx waygraph init my-app` |
+| Install coding-agent defs for diving an app into Blocks | `npx waygraph agent-dive --loop claude` (also `opencode` / `cursor` / `vscode`) |
 | Add waygraph to an existing repo | `npm install waygraph @playwright/test` |
 
 **Scaffold is not hidden inside waygraph alone** - the offline starter also ships as

package/dist/agent-dive.d.ts

@@ -0,0 +1,19 @@
+export type AgentDiveLoop = "claude" | "opencode" | "cursor" | "vscode";
+export interface AgentSpec {
+    name: string;
+    description: string;
+    model?: string;
+    color?: string;
+    tools: string[];
+    instructions: string;
+}
+/** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
+export declare function parseAgentSpec(filePath: string): AgentSpec;
+export declare function loadAgentSpecs(): AgentSpec[];
+export interface AgentDiveOptions {
+    loop: AgentDiveLoop;
+    projectDir: string;
+    /** Also copy raw prompts under docs/waygraph-agents/ */
+    prompts?: boolean;
+}
+export declare function runAgentDive(opts: AgentDiveOptions): void;

package/dist/agent-dive.js

@@ -0,0 +1,162 @@
+/**
+ * `waygraph agent-dive` — initialize coding-agent definitions for diving an app
+ * into waygraph Blocks (Playwright `init-agents` analogue).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+function packageRoot() {
+    // dist/agent-dive.js -> ..
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function agentsTemplateDir() {
+    return join(packageRoot(), "templates", "agents");
+}
+/** Minimal YAML-ish frontmatter parser for `*.agent.md` templates. */
+export function parseAgentSpec(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    if (!raw.startsWith("---\n")) {
+        throw new Error(`agent-dive: missing frontmatter in ${filePath}`);
+    }
+    const end = raw.indexOf("\n---\n", 4);
+    if (end < 0)
+        throw new Error(`agent-dive: unclosed frontmatter in ${filePath}`);
+    const fm = raw.slice(4, end);
+    const body = raw.slice(end + 5).trim();
+    const meta = {};
+    let listKey = null;
+    const lists = {};
+    for (const line of fm.split("\n")) {
+        if (/^\s+-\s+/.test(line) && listKey) {
+            lists[listKey].push(line.replace(/^\s+-\s+/, "").trim());
+            continue;
+        }
+        listKey = null;
+        const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1];
+        const val = m[2].trim();
+        if (val === "") {
+            listKey = key;
+            lists[key] = [];
+        }
+        else {
+            meta[key] = val;
+        }
+    }
+    const name = meta.name || basename(filePath).replace(/\.agent\.md$/, "");
+    return {
+        name,
+        description: meta.description || name,
+        ...(meta.model ? { model: meta.model } : {}),
+        ...(meta.color ? { color: meta.color } : {}),
+        tools: lists.tools ?? [],
+        instructions: body,
+    };
+}
+export function loadAgentSpecs() {
+    const dir = agentsTemplateDir();
+    if (!existsSync(dir)) {
+        throw new Error(`agent-dive: templates missing at ${dir}`);
+    }
+    return readdirSync(dir)
+        .filter((f) => f.endsWith(".agent.md"))
+        .sort()
+        .map((f) => parseAgentSpec(join(dir, f)));
+}
+function writeFileLogged(path, content, kind) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content.endsWith("\n") ? content : content + "\n");
+    console.log(`  wrote ${path} (${kind})`);
+}
+function claudeAgentMd(agent) {
+    const tools = agent.tools.join(", ");
+    const lines = [
+        "---",
+        `name: ${agent.name}`,
+        `description: ${agent.description}`,
+        ...(agent.model ? [`model: ${agent.model}`] : []),
+        ...(agent.color ? [`color: ${agent.color}`] : []),
+        ...(tools ? [`tools: ${tools}`] : []),
+        "---",
+        "",
+        agent.instructions,
+        "",
+    ];
+    return lines.join("\n");
+}
+function opencodePromptMd(agent) {
+    return `${agent.instructions}\n`;
+}
+function cursorRuleMdc(agent) {
+    return `---
+description: ${agent.description}
+globs:
+alwaysApply: false
+---
+
+# ${agent.name}
+
+${agent.instructions}
+`;
+}
+function vscodeAgentMd(agent) {
+    return claudeAgentMd(agent);
+}
+export function runAgentDive(opts) {
+    const agents = loadAgentSpecs();
+    const root = opts.projectDir;
+    console.log(`waygraph agent-dive (${opts.loop}) -> ${root}`);
+    console.log(`  ${agents.length} agent(s) from package templates`);
+    switch (opts.loop) {
+        case "claude": {
+            const dir = join(root, ".claude", "agents");
+            mkdirSync(dir, { recursive: true });
+            for (const a of agents) {
+                writeFileLogged(join(dir, `${a.name}.md`), claudeAgentMd(a), "claude agent");
+            }
+            break;
+        }
+        case "opencode": {
+            const dir = join(root, ".opencode", "prompts");
+            mkdirSync(dir, { recursive: true });
+            for (const a of agents) {
+                writeFileLogged(join(dir, `${a.name}.md`), opencodePromptMd(a), "opencode prompt");
+            }
+            break;
+        }
+        case "cursor": {
+            const dir = join(root, ".cursor", "rules");
+            mkdirSync(dir, { recursive: true });
+            for (const a of agents) {
+                writeFileLogged(join(dir, `${a.name}.mdc`), cursorRuleMdc(a), "cursor rule");
+            }
+            break;
+        }
+        case "vscode": {
+            const dir = join(root, ".github", "agents");
+            mkdirSync(dir, { recursive: true });
+            for (const a of agents) {
+                writeFileLogged(join(dir, `${a.name}.md`), vscodeAgentMd(a), "vscode agent");
+            }
+            break;
+        }
+        default: {
+            const _exhaustive = opts.loop;
+            throw new Error(`agent-dive: unsupported loop ${_exhaustive}`);
+        }
+    }
+    if (opts.prompts) {
+        const dir = join(root, "docs", "waygraph-agents");
+        mkdirSync(dir, { recursive: true });
+        for (const a of agents) {
+            writeFileLogged(join(dir, `${a.name}.md`), `# ${a.name}\n\n${a.description}\n\n${a.instructions}\n`, "prompt copy");
+        }
+    }
+    console.log("");
+    console.log("Next: point your coding agent at those files, then:");
+    console.log("  npx waygraph check .");
+    console.log("  npx waygraph auto --cli");
+    console.log("  (scaffold: npx waygraph init my-app)");
+}

package/dist/auto-explore-run.d.ts

@@ -5,6 +5,11 @@ export interface AutoExploreOptions {
     /** Initial URL when the page is blank (defaults to baseURL). */
     startUrl?: string;
 }
+/**
+ * Saucedemo-only defaults. Exact key names only — never substring `"login"`
+ * (PIA `login-email` string must stay unset; see docs/proposals/auto-login-email-seed-bug.md).
+ */
+export declare function defaultMemValueForKey(keyName: string): unknown | undefined;
 /**
  * Interactive waygraph auto: locate current Checkpoint, list runnable Blocks, pick one, repeat.
  */

package/dist/auto-explore-run.js

@@ -77,12 +77,24 @@ function missingMemKeys(entry, mem) {
     return requires.filter((k) => !mem.has(k));
 }
 const DEFAULT_CREDENTIALS = { username: "standard_user", password: "secret_sauce" };
-function defaultMemValueForKey(keyName) {
-    if (keyName.includes("credential") || keyName.includes("login")) {
+/**
+ * Saucedemo-only defaults. Exact key names only — never substring `"login"`
+ * (PIA `login-email` string must stay unset; see docs/proposals/auto-login-email-seed-bug.md).
+ */
+export function defaultMemValueForKey(keyName) {
+    if (keyName === "login-credentials" ||
+        keyName === "credentials" ||
+        keyName === "saucedemo.credentials") {
         return DEFAULT_CREDENTIALS;
     }
     return undefined;
 }
+function defaultMemJsonPrompt(keyName) {
+    const def = defaultMemValueForKey(keyName);
+    if (def !== undefined)
+        return JSON.stringify(def);
+    return "{}";
+}
 function seedMemFromEnv(mem, entry) {
     const raw = process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
     if (!raw)
@@ -129,9 +141,7 @@ async function promptMemCli(entry, mem) {
     const rl = createInterface({ input, output });
     try {
         for (const k of missingMemKeys(entry, mem)) {
-            const def = k.name.includes("credential") || k.name.includes("login")
-                ? '{"username":"standard_user","password":"secret_sauce"}'
-                : "{}";
+            const def = defaultMemJsonPrompt(k.name);
             const line = await rl.question(`  ${k.name} JSON [${def}]: `);
             const json = line.trim() || def;
             mem.set(k, JSON.parse(json));

package/dist/cli.d.ts

@@ -7,7 +7,7 @@
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
- * Also: list / nav / validate / check / graph / init / try
+ * Also: list / nav / validate / check / graph / init / agent-dive / try
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.

package/dist/cli.js

@@ -7,7 +7,7 @@
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--ff-expand`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
  *
- * Also: list / nav / validate / check / graph / init / try
+ * Also: list / nav / validate / check / graph / init / agent-dive / try
  * Aliases (one release): `chain` -> run/demo --blocks; `--autoplay` -> `--auto-next`
  *
  * "project" defaults to cwd. Flags beat WAYGRAPH_* env.
@@ -19,6 +19,7 @@ import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 import { runAutoExplore } from "./auto-explore-run.js";
+import { runAgentDive } from "./agent-dive.js";
 // ---------------------------------------------------------------------------
 // Filesystem
 // ---------------------------------------------------------------------------
@@ -3660,6 +3661,8 @@ Primary (less is more):
 
 Also:
   waygraph list | nav | validate | check | graph | init <name>
+  waygraph agent-dive [--loop claude|opencode|cursor|vscode] [--prompts]
+                 Initialize coding-agent defs (Playwright init-agents analogue)
   waygraph try [demo|auto|auto:cli]        One-shot saucedemo in a temp dir
                  try auto                  Headed browser panel (default)
                  try auto:cli / --cli      Terminal menu instead
@@ -3756,6 +3759,55 @@ async function main() {
             initCommand(args[1] ?? "");
             break;
         }
+        case "agent-dive":
+        case "init-agents": {
+            // Playwright analogue: npx playwright init-agents --loop <provider>
+            const rest = args.slice(1);
+            let loop = "claude";
+            let prompts = false;
+            let projectDir = process.cwd();
+            for (let i = 0; i < rest.length; i++) {
+                const a = rest[i];
+                if (a === "--prompts") {
+                    prompts = true;
+                    continue;
+                }
+                if (a === "--loop" || a.startsWith("--loop=")) {
+                    const v = a.startsWith("--loop=") ? a.slice("--loop=".length) : rest[++i];
+                    if (!v || !["claude", "opencode", "cursor", "vscode"].includes(v)) {
+                        console.error("waygraph agent-dive: --loop must be claude | opencode | cursor | vscode");
+                        process.exit(1);
+                    }
+                    loop = v;
+                    continue;
+                }
+                if (a === "--help" || a === "-h") {
+                    console.log(`waygraph agent-dive [--loop claude|opencode|cursor|vscode] [--prompts] [project]
+
+Initialize coding-agent definitions for diving an app into waygraph Blocks
+(Playwright \`init-agents\` analogue).
+
+  --loop claude     write .claude/agents/*.md (default)
+  --loop opencode   write .opencode/prompts/*.md
+  --loop cursor     write .cursor/rules/waygraph-*.mdc
+  --loop vscode     write .github/agents/*.md
+  --prompts         also copy docs/waygraph-agents/*.md
+
+Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
+`);
+                    process.exit(0);
+                }
+                if (!a.startsWith("-")) {
+                    projectDir = resolve(a);
+                }
+            }
+            if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
+                console.error(`waygraph agent-dive: no such directory: ${projectDir}`);
+                process.exit(1);
+            }
+            runAgentDive({ loop, projectDir, prompts });
+            break;
+        }
         case "chain": {
             // Compat alias: chain auto A B -> auto --blocks A B; else -> run --blocks.
             const flags = parseRunFlags(args.slice(1));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.12.6",
+  "version": "0.12.7",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/agents/waygraph-author.agent.md

@@ -0,0 +1,36 @@
+---
+name: waygraph-author
+description: Author waygraph Nav/Page/Method/Effect blocks and flows from an approved SITE-MAP. Use after planning, or when extending coverage for a named route.
+model: sonnet
+color: green
+tools:
+  - search
+  - edit
+---
+
+You are a waygraph block author. Implement Blocks and Flows that match the consumer SITE-MAP.
+
+## Rules
+
+1. One concern per file: `nav-*.block.ts`, `*.page.block.ts`, `*.method.block.ts`, `*.effect.block.ts`, `*.flow.ts`.
+2. Navigation only inside `defineNavBlock` / `defineNavClickBlock`. Regular Method/Effect `act` uses ActionPage (no goto).
+3. Effects that appear in `waygraph auto` menus need `instanceOptions` that scan the live DOM (or mem) for labeled rows.
+4. Stubs: `stubBefore` / `stubAfter` / `stubOnError` for demo narration; YAP slides on Methods when useful; flow fixtures via `withHighlightFixtures` when AC copy is flow-specific.
+5. Mem: `requires` lists keys the block needs; seed via `--data` / `WAYGRAPH_DATA` / project defaults — never assume saucedemo creds for email keys.
+6. External Mailpit/MailHog: nav to inbox URL from env; Methods open message / click verify link; never put mail UI under `*-web/`.
+
+## Verify locally
+
+```bash
+npx waygraph check .
+npx waygraph list
+npm run typecheck
+# offline fixtures or live:
+npx playwright test
+# explore:
+npm run auto        # or: npx waygraph auto --cli
+```
+
+## Output
+
+Ship compiling TypeScript under `src/blocks/` + `src/flows/` + `src/states/`. Update NAV.md when edges change. Keep STRUCTURE / SITE-MAP honest.

package/templates/agents/waygraph-healer.agent.md

@@ -0,0 +1,33 @@
+---
+name: waygraph-healer
+description: Debug and fix failing waygraph flows, auto menus, Mem seeds, and Mailpit/email verify hops. Use when npm test, waygraph run, or waygraph auto fails.
+model: sonnet
+color: red
+tools:
+  - search
+  - edit
+---
+
+You are a waygraph healer. Fix failing Blocks/Flows with evidence — do not rewrite the architecture.
+
+## Diagnose order
+
+1. Read the error (selector timeout, Trait fail, Mem missing, wrong checkpoint).
+2. Confirm base URL / fixture server / env (`WAYGRAPH_BASE_URL`, Mailpit URL).
+3. Check Mem: wrong type for a key (object vs string) is a common auto bug — `login-email` must be a string address, not `{username,password}`.
+4. Nav vs Method: accidental `page.goto` outside NavBlock → move to `defineNavBlock`.
+5. Effect auto menus: `instanceOptions` must match live DOM; empty menu usually means wrong selector or not on the page yet.
+6. Mailpit: filter by the real recipient email in Mem; ambiguous `.msglist-message` with multiple rows → tighten locator.
+
+## Fix loop
+
+1. Reproduce with the smallest command (`waygraph run --blocks …` or one Playwright spec).
+2. Patch the owning block (or fixture), re-run the same command.
+3. Keep stubs/fixtures working after selector changes.
+4. Report proof: command + exit 0 / expected checkpoint.
+
+## Do not
+
+- Invent new route folders that are not app URLs
+- Seed credential objects into email Mem keys
+- Clear shared remote MailHog/Mailpit unless the operator said so

package/templates/agents/waygraph-planner.agent.md

@@ -0,0 +1,35 @@
+---
+name: waygraph-planner
+description: Plan waygraph SITE-MAP and route coverage for an existing web app. Use when diving into a product codebase to map URLs to Nav/Page/Method/Effect blocks before writing code.
+model: sonnet
+color: blue
+tools:
+  - search
+  - edit
+---
+
+You are a waygraph planner. Your job is to dive an existing app and produce a SITE-MAP + NAV.md plan — not dump ad hoc Playwright helpers.
+
+## Hard conventions
+
+1. **Route folders = app URL folders.** A folder gets `NAV.md` + a nav block iff the app has a real page at that URL. Do not invent `landing/`, `root/`, or shell folders that are not routes.
+2. **Namespaces by origin:** `<app>-web/` for the product FE; `<app>-external/` for Mailpit/MailHog, Studio, probes (never mix).
+3. **Block kinds:**
+   - Nav — `defineNavBlock` / `defineNavClickBlock` — only place for `page.goto` / click-nav
+   - Page — `definePageBlock` hub + `methods` registry
+   - Method — forms, asserts, same-URL actions without instance menus
+   - Effect — `defineEffectBlock` + `instanceOptions` for per-row auto menus (add/remove/toggle)
+4. **Mem keys:** typed `key` / `keyGroup`. Never rely on substring `"login"` defaults — email keys like `login-email` stay strings; credential objects use exact names such as `saucedemo.credentials` / `login-credentials`.
+5. Prefer `click` NavBlocks when the product has a real control; use `url` for deep links / email tokens.
+
+## Workflow
+
+1. Read the app router (Next.js `app/`, etc.) and list real page URLs.
+2. Draft `src/blocks/SITE-MAP.md` with namespaces + route folders.
+3. For each route: list nav-to edges, methods/effects, checkpoints, mem keys in `NAV.md` (plan only).
+4. Call out external surfaces (Mailpit inbox, magic-link verify) under `*-external/`.
+5. Propose 1-3 starter flows (happy path, login/verify, one feature) — do not implement unless asked.
+
+## Output
+
+Write/update markdown under `src/blocks/` (`SITE-MAP.md`, route `NAV.md` stubs). ASCII only. No localhost ports in shared docs.

package/templates/scaffold/README.md

@@ -1,10 +1,11 @@
 # __PROJECT_NAME__
 
-Offline waygraph scaffold (`data:` URL - no network for `npm test`).
+Offline waygraph scaffold - Nav, Page hub, Method, Effect (`instanceOptions` for
+`waygraph auto`), stubs/fixtures/YAP, mem keys.
 
 ## Layout
 
-See [STRUCTURE.md](./STRUCTURE.md). Package docs:
+See [STRUCTURE.md](./STRUCTURE.md). Docs:
 https://deviate-dv8.github.io/waygraph/scaffold.html
 
 ## Commands
@@ -13,13 +14,15 @@ https://deviate-dv8.github.io/waygraph/scaffold.html
 npm install
 npx playwright install chromium
 npm test
-npm run list
-npm run check
-npm run demo          # headed step (manual Next)
-npm run demo:auto-next
-npm run auto
+npm run list && npm run check && npm run graph
+npm run demo                 # exampleFlow (hello + YAP)
+npm run demo:shop            # Effect path (needs --data selectedItem)
+npm run auto                 # headed explore - pick Add Alpha / …
 npm run auto:cli
+npx waygraph agent-dive --loop claude   # coding-agent defs (optional)
 ```
 
 Point `package.json` `waygraph.baseUrl` at your real app when you leave the
-`data:` demo. Keep route folders = app URLs (consumer layout).
+fixture (and drop `scripts/with-fixture.mjs` wrappers). Keep route folders =
+app URLs (consumer layout).
+Offline fixture is HTTP `http://127.0.0.1:4177/home.html` (Flatpak-safe).

package/templates/scaffold/STRUCTURE.md

@@ -1,36 +1,61 @@
 # Offline scaffold layout (`waygraph init` / `create-waygraph`)
 
 Shipped under `templates/scaffold/` in the **waygraph** package.
-Same tree is what `npx waygraph init my-app` copies.
-
-Docs (readable in the package site): [docs/scaffold.html](../../docs/scaffold.html)
+Docs: [docs/scaffold.html](../../docs/scaffold.html)
 
 ```text
 .
-├── package.json              # waygraph ^0.12.6, demo/run/auto scripts
-├── playwright.config.ts
-├── tsconfig.json
+├── package.json
 ├── STRUCTURE.md              # this file
 ├── README.md
 ├── src/
 │   ├── blocks/
-│   │   ├── SITE-MAP.md       # namespace map (consumer convention)
-│   │   └── demo-web/         # synthetic site (data: URL) - mirrors app "/"
+│   │   ├── SITE-MAP.md
+│   │   └── demo-web/         # synthetic "/" (HTTP fixture :4177)
 │   │       ├── NAV.md
-│   │       ├── nav-home.block.ts
+│   │       ├── home.html     # offline fixture (catalog + cart)
+│   │       ├── demo-sel.ts
+│   │       ├── nav-home.block.ts          # Nav
+│   │       ├── home.page.block.ts         # Page hub (methods registry)
 │   │       └── methods/
-│   │           └── assert-hello.method.block.ts
+│   │           ├── assert-hello.method.block.ts   # Method + stubs + YAP
+│   │           ├── add-item.effect.block.ts       # Effect + instanceOptions (auto)
+│   │           ├── remove-item.effect.block.ts    # Effect + instanceOptions
+│   │           └── clear-cart.method.block.ts     # Method
 │   ├── states/
-│   │   └── demo.states.ts
+│   │   ├── demo.states.ts
+│   │   └── demo.mem-keys.ts  # SelectedItem for Effect / auto
 │   └── flows/
-│       └── example.flow.ts   # withTitle + withHighlightFixtures
+│       ├── example.flow.ts   # nav + assert (smoke)
+│       └── shop.flow.ts      # nav + add-item + clear (Effect path)
+├── scripts/
+│   ├── fixture-server.mjs    # serves home.html on :4177
+│   └── with-fixture.mjs      # start server + run waygraph auto/demo/run
 └── tests/
     └── example.spec.ts
 ```
 
-**Rule of thumb:** route folders = app URL folders; `/` lives at the namespace
-root (`demo-web/`). Methods hang under `methods/`. Chrome/shared UI would be
-`shared/chrome/` (not invented for this offline hello).
+## Features covered
+
+| Feature | Where |
+|---------|--------|
+| Nav (`defineNavBlock`) | `nav-home.block.ts` |
+| Page hub (`definePageBlock` + `methods`) | `home.page.block.ts` |
+| Method (`defineMethodBlock`) | `assert-hello`, `clear-cart` |
+| Effect + `instanceOptions` (auto menus) | `add-item`, `remove-item` |
+| Mem (`keyGroup`) | `demo.mem-keys.ts` |
+| `stubBefore` / `stubAfter` / `stubOnError` | all instruction blocks |
+| Flow fixtures + title | `example.flow.ts`, `shop.flow.ts` |
+| YAP slides | `assert-hello` |
+| `withSessionReset` | `shop.flow.ts` |
+| `waygraph auto` / `auto --cli` | `npm run auto` |
+| `demo` / `run` / `list` / `check` / `graph` | `package.json` scripts |
+
+## Auto
+
+```bash
+npm run auto        # headed explore - pick Add Alpha / Add Beta from live DOM
+npm run auto:cli    # same menus in the terminal
+```
 
-Grow this into a real app by renaming `demo-web/` to your FE origin namespace
-and adding one folder per `page.tsx` URL. See package docs **Consumer layout**.
+After `nav-home`, Effect blocks expose one menu row per visible Add/Remove button.

package/templates/scaffold/package.json

@@ -6,20 +6,25 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "playwright test",
+    "fixture": "node scripts/fixture-server.mjs",
     "list": "waygraph list",
     "check": "waygraph check",
-    "auto": "waygraph auto",
-    "auto:cli": "waygraph auto --cli",
-    "demo": "waygraph demo --blocks exampleFlow",
-    "demo:auto-next": "waygraph demo --blocks exampleFlow --auto-next --title \"Scaffold demo\"",
-    "run": "waygraph run --blocks exampleFlow",
-    "graph": "waygraph graph"
+    "graph": "waygraph graph",
+    "graph:mermaid": "waygraph graph --mermaid",
+    "auto": "node scripts/with-fixture.mjs waygraph auto",
+    "auto:cli": "node scripts/with-fixture.mjs waygraph auto --cli",
+    "demo": "node scripts/with-fixture.mjs waygraph demo --blocks exampleFlow",
+    "demo:auto-next": "node scripts/with-fixture.mjs waygraph demo --blocks exampleFlow --auto-next --title \"Scaffold hello\"",
+    "demo:shop": "node scripts/with-fixture.mjs waygraph demo --blocks shopFlow --data \"{\\\"demo.selectedItem\\\":{\\\"id\\\":\\\"alpha\\\",\\\"name\\\":\\\"Alpha\\\"}}\" --title \"Scaffold shop\"",
+    "demo:shop:auto-next": "node scripts/with-fixture.mjs waygraph demo --blocks shopFlow --auto-next --data \"{\\\"demo.selectedItem\\\":{\\\"id\\\":\\\"alpha\\\",\\\"name\\\":\\\"Alpha\\\"}}\"",
+    "run": "node scripts/with-fixture.mjs waygraph run --blocks exampleFlow",
+    "run:shop": "node scripts/with-fixture.mjs waygraph run --blocks shopFlow --data \"{\\\"demo.selectedItem\\\":{\\\"id\\\":\\\"alpha\\\",\\\"name\\\":\\\"Alpha\\\"}}\""
   },
   "waygraph": {
-    "baseUrl": "about:blank"
+    "baseUrl": "http://127.0.0.1:4177"
   },
   "dependencies": {
-    "waygraph": "^0.12.6"
+    "waygraph": "^0.12.7"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

package/templates/scaffold/playwright.config.ts

@@ -1,12 +1,27 @@
 import { defineConfig } from "@playwright/test";
 
+const FIXTURE_PORT = process.env.WAYGRAPH_FIXTURE_PORT || "4177";
+const FIXTURE_HOST = process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1";
+const FIXTURE_ORIGIN = `http://${FIXTURE_HOST}:${FIXTURE_PORT}`;
+
 export default defineConfig({
   testDir: "./tests",
   fullyParallel: true,
   reporter: "list",
   use: {
+    baseURL: FIXTURE_ORIGIN,
     launchOptions: {
       executablePath: process.env.CHROME_PATH || process.env.CHROMIUM_PATH,
     },
   },
+  webServer: {
+    command: "node scripts/fixture-server.mjs",
+    url: `${FIXTURE_ORIGIN}/home.html`,
+    reuseExistingServer: !process.env.CI,
+    env: {
+      WAYGRAPH_FIXTURE_PORT: FIXTURE_PORT,
+      WAYGRAPH_FIXTURE_HOST: FIXTURE_HOST,
+      WAYGRAPH_FIXTURE_QUIET: "1",
+    },
+  },
 });

package/templates/scaffold/scripts/fixture-server.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Tiny static server for the offline scaffold fixture (home.html).
+ * Flatpak Chromium cannot open file:// under /tmp — HTTP localhost works.
+ */
+import { createServer } from "node:http";
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, extname, normalize } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "../src/blocks/demo-web");
+const PORT = Number(process.env.WAYGRAPH_FIXTURE_PORT || 4177);
+const HOST = process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1";
+
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+};
+
+const server = createServer((req, res) => {
+  const raw = (req.url || "/").split("?")[0] || "/";
+  const rel = raw === "/" ? "home.html" : raw.replace(/^\//, "");
+  const full = normalize(join(ROOT, rel));
+  if (!full.startsWith(ROOT) || !existsSync(full)) {
+    res.writeHead(404, { "content-type": "text/plain" });
+    res.end("not found");
+    return;
+  }
+  const type = TYPES[extname(full)] || "application/octet-stream";
+  res.writeHead(200, { "content-type": type });
+  res.end(readFileSync(full));
+});
+
+server.listen(PORT, HOST, () => {
+  if (process.env.WAYGRAPH_FIXTURE_QUIET !== "1") {
+    console.error(`waygraph fixture: http://${HOST}:${PORT}/home.html`);
+  }
+});

package/templates/scaffold/scripts/with-fixture.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Start fixture-server, run a child command, tear down on exit.
+ * Usage: node scripts/with-fixture.mjs [--] <cmd> [args...]
+ */
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PORT = process.env.WAYGRAPH_FIXTURE_PORT || "4177";
+const HOST = process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1";
+
+const argv = process.argv.slice(2).filter((a) => a !== "--");
+if (argv.length === 0) {
+  console.error("usage: node scripts/with-fixture.mjs <cmd> [args...]");
+  process.exit(1);
+}
+
+const env = {
+  ...process.env,
+  WAYGRAPH_FIXTURE_PORT: PORT,
+  WAYGRAPH_FIXTURE_HOST: HOST,
+  WAYGRAPH_FIXTURE_QUIET: "1",
+  WAYGRAPH_BASE_URL: process.env.WAYGRAPH_BASE_URL || `http://${HOST}:${PORT}`,
+};
+
+const server = spawn(process.execPath, [join(HERE, "fixture-server.mjs")], {
+  env,
+  stdio: ["ignore", "ignore", "inherit"],
+});
+
+function killServer() {
+  try {
+    server.kill("SIGTERM");
+  } catch {
+    /* ignore */
+  }
+}
+
+async function waitReady(ms = 5000) {
+  const url = `http://${HOST}:${PORT}/home.html`;
+  const start = Date.now();
+  while (Date.now() - start < ms) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) return;
+    } catch {
+      /* retry */
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  throw new Error(`fixture server not ready at ${url}`);
+}
+
+let code = 1;
+try {
+  await waitReady();
+  const child = spawn(argv[0], argv.slice(1), { env, stdio: "inherit", shell: false });
+  code = await new Promise((resolve) => {
+    child.on("exit", (c, signal) => resolve(signal ? 1 : (c ?? 1)));
+  });
+} catch (e) {
+  console.error(e instanceof Error ? e.message : String(e));
+  code = 1;
+} finally {
+  killServer();
+}
+process.exit(code);

package/templates/scaffold/src/blocks/SITE-MAP.md

@@ -1,13 +1,12 @@
 # Site map (scaffold)
 
-Offline hello uses one synthetic namespace (`demo-web/`) and a `data:` home URL
-so `npm test` stays green without the network.
+Offline catalog uses one synthetic namespace (`demo-web/`) and a local
+`home.html` fixture so `npm test` / `waygraph auto` need no network.
 
 | Folder | URL | Notes |
 |--------|-----|-------|
-| `demo-web/` | `/` (synthetic) | Nav + methods for the hello page |
-| `demo-web/methods/` | same URL | On-page asserts / future form acts |
+| `demo-web/` | `/` (synthetic) | Nav + Page hub + methods/effects |
+| `demo-web/methods/` | same URL | assert, add/remove Effects, clear |
 
 When you wire a real app, rename `demo-web/` to your FE origin namespace and
-add one folder per real `page.tsx` route. Grouping dirs without a page get no
-`NAV.md`. Full contract: waygraph **Consumer layout** docs.
+add one folder per real `page.tsx` route. See **Consumer layout** docs.

package/templates/scaffold/src/blocks/demo-web/NAV.md

@@ -1,20 +1,29 @@
 # demo-web / (synthetic home)
 
-**URL:** `data:text/html,…` (offline hello - replace with your real `/`)
+**URL:** `http://127.0.0.1:4177/home.html` (offline catalog via `scripts/fixture-server.mjs` - replace with your real `/`)
 
 ## Nav-to
 
 | From | Block | How |
 |------|-------|-----|
-| start | `nav-home` | `defineNavBlock` `url` → data HTML |
+| start | `nav-home` | `defineNavBlock` `url` → home.html |
 
-## Methods
+## Page hub
 
-| Block | Kind | Notes |
-|-------|------|-------|
-| `assert-hello` | Method | Verify heading; demo stubs + fixtures |
+| Block | Checkpoint | Methods |
+|-------|------------|---------|
+| `page-home` | `Home` | add-item, remove-item, clear-cart, assert-hello |
+
+## Methods / Effects
+
+| Block | Kind | Auto |
+|-------|------|------|
+| `assert-hello` | Method | single row |
+| `add-item` | Effect | one row per live Add button (`instanceOptions`) |
+| `remove-item` | Effect | one row per live Remove button |
+| `clear-cart` | Method | single row |
 
 ## States / mem-keys
 
-- Checkpoint `Home` after nav
-- Checkpoint `HomeVerified` after assert-hello
+- Checkpoints: `Home`, `HomeVerified`, `ItemInCart`, `CartEmpty`
+- Mem: `demo.selectedItem` (`SelectedItem`) - filled by auto or `--data`

package/templates/scaffold/src/blocks/demo-web/demo-sel.ts

@@ -0,0 +1,14 @@
+/** Offline catalog URL — HTTP fixture server (not file://; Flatpak Chromium blocks /tmp file URLs). */
+export const HOME_URL =
+  process.env.WAYGRAPH_HOME_URL ??
+  `http://${process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1"}:${process.env.WAYGRAPH_FIXTURE_PORT || "4177"}/home.html`;
+
+export const DemoSel = {
+  title: "h1",
+  sub: "#sub",
+  cartCount: "[data-test=cart-count]",
+  catalog: "#catalog",
+  clear: "[data-test=clear-cart]",
+  addBtn: (id: string) => `[data-test=add-${id}]`,
+  removeBtn: (id: string) => `[data-test=remove-${id}]`,
+} as const;

package/templates/scaffold/src/blocks/demo-web/home.html

@@ -0,0 +1,65 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Waygraph scaffold demo</title>
+    <style>
+      body { font-family: system-ui, sans-serif; margin: 2rem; max-width: 32rem; }
+      h1 { margin: 0 0 0.5rem; }
+      #cart { margin: 1rem 0; font-weight: 600; }
+      .item { display: flex; gap: 0.75rem; align-items: center; margin: 0.5rem 0; }
+      button { cursor: pointer; }
+    </style>
+  </head>
+  <body>
+    <h1>Hello Waygraph</h1>
+    <p id="sub">Scaffold demo - Effect / auto / Page hub</p>
+    <div id="cart">Cart: <span data-test="cart-count">0</span></div>
+    <ul id="catalog">
+      <li class="item" data-id="alpha">
+        <span class="name">Alpha</span>
+        <button type="button" data-test="add-alpha" class="add">Add Alpha</button>
+        <button type="button" data-test="remove-alpha" class="remove" hidden>Remove Alpha</button>
+      </li>
+      <li class="item" data-id="beta">
+        <span class="name">Beta</span>
+        <button type="button" data-test="add-beta" class="add">Add Beta</button>
+        <button type="button" data-test="remove-beta" class="remove" hidden>Remove Beta</button>
+      </li>
+      <li class="item" data-id="gamma">
+        <span class="name">Gamma</span>
+        <button type="button" data-test="add-gamma" class="add">Add Gamma</button>
+        <button type="button" data-test="remove-gamma" class="remove" hidden>Remove Gamma</button>
+      </li>
+    </ul>
+    <button type="button" data-test="clear-cart" id="clear">Clear cart</button>
+    <script>
+      const countEl = document.querySelector("[data-test=cart-count]");
+      const sync = () => {
+        const n = document.querySelectorAll(".remove:not([hidden])").length;
+        countEl.textContent = String(n);
+      };
+      document.querySelectorAll(".item").forEach((row) => {
+        const add = row.querySelector(".add");
+        const remove = row.querySelector(".remove");
+        add.addEventListener("click", () => {
+          add.hidden = true;
+          remove.hidden = false;
+          sync();
+        });
+        remove.addEventListener("click", () => {
+          remove.hidden = true;
+          add.hidden = false;
+          sync();
+        });
+      });
+      document.getElementById("clear").addEventListener("click", () => {
+        document.querySelectorAll(".item").forEach((row) => {
+          row.querySelector(".add").hidden = false;
+          row.querySelector(".remove").hidden = true;
+        });
+        sync();
+      });
+    </script>
+  </body>
+</html>

package/templates/scaffold/src/blocks/demo-web/home.page.block.ts

@@ -0,0 +1,29 @@
+import { definePageBlock, Trait } from "waygraph";
+import type { Home } from "../../states/demo.states.js";
+import { DemoSel } from "./demo-sel.js";
+import { AddItemBlock } from "./methods/add-item.effect.block.js";
+import { RemoveItemBlock } from "./methods/remove-item.effect.block.js";
+import { ClearCartBlock } from "./methods/clear-cart.method.block.js";
+import { AssertHelloBlock } from "./methods/assert-hello.method.block.js";
+
+/**
+ * Kind: Page
+ * Helper: definePageBlock
+ * Route: demo-web/
+ *
+ * Hub for the offline home screen. Methods hang here for docs/auto grouping;
+ * edges in flows still reference the method Blocks directly.
+ * Arrival-only (nav-home already landed on Home).
+ */
+export const HomePageBlock = definePageBlock<Home>({
+  name: "page-home",
+  description: "Offline home hub - add/remove effects, clear, assert-hello.",
+  checkpoint: "Home",
+  verify: [Trait.visible(DemoSel.catalog)],
+  methods: {
+    addItem: () => AddItemBlock,
+    removeItem: () => RemoveItemBlock,
+    clearCart: () => ClearCartBlock,
+    assertHello: () => AssertHelloBlock,
+  },
+});

package/templates/scaffold/src/blocks/demo-web/methods/add-item.effect.block.ts

@@ -0,0 +1,68 @@
+import {
+  defineEffectBlock,
+  checkpoint,
+  type Checkpoint,
+  type WaygraphInstanceOption,
+} from "waygraph";
+import type { ItemInCart } from "../../../states/demo.states.js";
+import { SelectedItem } from "../../../states/demo.mem-keys.js";
+import { DemoSel } from "../demo-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.
+ */
+export const AddItemBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>({
+  name: "add-item",
+  description: "Adds the mem-selected catalog item to the cart.",
+  requires: [SelectedItem.key],
+  instruction: {
+    async act(page, _input, mem) {
+      const { id } = mem.get(SelectedItem.key);
+      await page.locator(DemoSel.addBtn(id)).click();
+    },
+    resolve: () => checkpoint("ItemInCart"),
+    verify: [
+      {
+        name: "item-added",
+        async check(page, mem) {
+          const { id } = mem.get(SelectedItem.key);
+          return page.locator(DemoSel.removeBtn(id)).isVisible();
+        },
+      },
+    ],
+    stubBefore: {
+      add: { selector: DemoSel.catalog, label: "Catalog" },
+    },
+    stubAfter: {
+      cart: { selector: DemoSel.cartCount, label: "Cart count", duration: true },
+    },
+    stubOnError: {
+      cart: { selector: DemoSel.cartCount, label: "Cart at failure", tag: "FAIL" },
+    },
+  },
+  async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
+    const buttons = page.locator("button.add:not([hidden])");
+    const n = await buttons.count();
+    const out: WaygraphInstanceOption[] = [];
+    for (let i = 0; i < n; i++) {
+      const btn = buttons.nth(i);
+      const label = ((await btn.textContent()) || "").trim();
+      const testId = await btn.getAttribute("data-test");
+      const id = (testId || "").replace(/^add-/, "");
+      if (!id) continue;
+      out.push({
+        id,
+        label: label || `Add ${id}`,
+        key: SelectedItem.key,
+        value: { id, name: id },
+        highlight: DemoSel.addBtn(id),
+      });
+    }
+    return out;
+  },
+});

package/templates/scaffold/src/blocks/demo-web/methods/assert-hello.method.block.ts

@@ -1,48 +1,47 @@
 import { defineMethodBlock, checkpoint, Trait } from "waygraph";
+import { DemoSel } from "../demo-sel.js";
 
 /**
  * Kind: Method
  * Helper: defineMethodBlock
  * Route: demo-web/methods/
  *
- * Same-URL assert after nav - shows stubBefore / stubAfter / stubOnError shape.
+ * Same-URL assert after nav - stubs + fixtures + YAP slide.
  */
 export const AssertHelloBlock = defineMethodBlock({
   name: "assert-hello",
   description: "Confirms the hello heading is still visible after arrival.",
   instruction: {
-    async act(_page) {
-      // No DOM mutation - observe/verify own the proof.
-    },
+    async act(_page) {},
     async observe(page) {
-      await page.locator("h1").first().waitFor({ state: "visible", timeout: 5_000 });
+      await page.locator(DemoSel.title).first().waitFor({ state: "visible", timeout: 5_000 });
       return "ok" as const;
     },
     resolve: () => checkpoint("HomeVerified"),
-    verify: [Trait.text("h1", "Hello Waygraph"), Trait.visible("#sub")],
+    verify: [Trait.text(DemoSel.title, "Hello Waygraph"), Trait.visible(DemoSel.sub)],
     stubBefore: {
-      title: { selector: "h1", label: "Heading about to check" },
+      title: { selector: DemoSel.title, label: "Heading about to check" },
     },
     stubAfter: {
       title: {
-        selector: "h1",
+        selector: DemoSel.title,
         label: "Hello confirmed",
         detail: "Offline scaffold proof point.",
         duration: true,
       },
-      sub: { selector: "#sub", label: "Subcopy", duration: 1500 },
+      sub: { selector: DemoSel.sub, label: "Subcopy", duration: 1500 },
     },
     stubOnError: {
       title: {
-        selector: "h1",
+        selector: DemoSel.title,
         label: "Heading at failure",
         tag: "FAIL",
       },
     },
     slides: [
       {
-        caption: "Scaffold is route-shaped",
-        detail: "demo-web/ = synthetic /. Grow folders per real page.tsx.",
+        caption: "Scaffold covers auto + narration",
+        detail: "Page hub, Effect instanceOptions, stubs, fixtures, YAP.",
         tag: "YAP",
         duration: true,
       },

package/templates/scaffold/src/blocks/demo-web/methods/clear-cart.method.block.ts

@@ -0,0 +1,26 @@
+import { defineMethodBlock, checkpoint, Trait } from "waygraph";
+import { DemoSel } from "../demo-sel.js";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: demo-web/methods/
+ */
+export const ClearCartBlock = defineMethodBlock({
+  name: "clear-cart",
+  description: "Clears every item via the Clear cart control.",
+  instruction: {
+    async act(page) {
+      await page.locator(DemoSel.clear).click();
+    },
+    resolve: () => checkpoint("CartEmpty"),
+    verify: [Trait.text(DemoSel.cartCount, "0")],
+    stubBefore: {
+      clear: { selector: DemoSel.clear, label: "Clear cart" },
+    },
+    stubAfter: {
+      cart: { selector: DemoSel.cartCount, label: "Empty cart", duration: true },
+    },
+    stubOnError: {},
+  },
+});

package/templates/scaffold/src/blocks/demo-web/methods/remove-item.effect.block.ts

@@ -0,0 +1,63 @@
+import {
+  defineEffectBlock,
+  checkpoint,
+  type Checkpoint,
+  type WaygraphInstanceOption,
+} from "waygraph";
+import type { CartEmpty } from "../../../states/demo.states.js";
+import { SelectedItem } from "../../../states/demo.mem-keys.js";
+import { DemoSel } from "../demo-sel.js";
+
+/**
+ * Kind: Effect
+ * Helper: defineEffectBlock
+ * Route: demo-web/methods/
+ *
+ * Removes one in-cart row. Auto menus one row per visible Remove button.
+ */
+export const RemoveItemBlock = defineEffectBlock<Checkpoint<string>, CartEmpty>({
+  name: "remove-item",
+  description: "Removes the mem-selected catalog item from the cart.",
+  requires: [SelectedItem.key],
+  instruction: {
+    async act(page, _input, mem) {
+      const { id } = mem.get(SelectedItem.key);
+      await page.locator(DemoSel.removeBtn(id)).click();
+    },
+    resolve: () => checkpoint("CartEmpty"),
+    verify: [
+      {
+        name: "item-removed",
+        async check(page, mem) {
+          const { id } = mem.get(SelectedItem.key);
+          return page.locator(DemoSel.addBtn(id)).isVisible();
+        },
+      },
+    ],
+    stubBefore: {},
+    stubAfter: {
+      cart: { selector: DemoSel.cartCount, label: "Cart count", duration: true },
+    },
+    stubOnError: {},
+  },
+  async instanceOptions(page): Promise<readonly WaygraphInstanceOption[]> {
+    const buttons = page.locator("button.remove:not([hidden])");
+    const n = await buttons.count();
+    const out: WaygraphInstanceOption[] = [];
+    for (let i = 0; i < n; i++) {
+      const btn = buttons.nth(i);
+      const label = ((await btn.textContent()) || "").trim();
+      const testId = await btn.getAttribute("data-test");
+      const id = (testId || "").replace(/^remove-/, "");
+      if (!id) continue;
+      out.push({
+        id,
+        label: label || `Remove ${id}`,
+        key: SelectedItem.key,
+        value: { id, name: id },
+        highlight: DemoSel.removeBtn(id),
+      });
+    }
+    return out;
+  },
+});

package/templates/scaffold/src/blocks/demo-web/nav-home.block.ts

@@ -1,8 +1,5 @@
 import { defineNavBlock, Trait } from "waygraph";
-
-/** Offline hello page - swap `url` for a real app route when you graduate. */
-export const HOME_URL =
-  'data:text/html,<!doctype html><html><body><h1>Hello Waygraph</h1><p id="sub">Scaffold demo</p></body></html>';
+import { DemoSel, HOME_URL } from "./demo-sel.js";
 
 /**
  * Kind: Nav
@@ -11,15 +8,15 @@ export const HOME_URL =
  */
 export const NavHomeBlock = defineNavBlock({
   name: "nav-home",
-  description: "Opens the offline hello page (data: URL).",
+  description: "Opens the offline catalog page (HTTP fixture :4177).",
   checkpoint: "Home",
   url: HOME_URL,
-  verify: [Trait.text("h1", "Hello Waygraph")],
+  verify: [Trait.text(DemoSel.title, "Hello Waygraph"), Trait.visible(DemoSel.catalog)],
   stubBefore: {},
   stubAfter: {
-    title: { selector: "h1", label: "Home heading", duration: true },
+    title: { selector: DemoSel.title, label: "Home heading", duration: true },
   },
   stubOnError: {
-    title: { selector: "h1", label: "Home heading at failure" },
+    title: { selector: DemoSel.title, label: "Home heading at failure" },
   },
 });

package/templates/scaffold/src/flows/example.flow.ts

@@ -1,13 +1,12 @@
 import { Engine, start, end, withTitle, withHighlightFixtures } from "waygraph";
 import { NavHomeBlock } from "../blocks/demo-web/nav-home.block.js";
 import { AssertHelloBlock } from "../blocks/demo-web/methods/assert-hello.method.block.js";
+// Page hub registered for auto/docs grouping (arrival-only after nav).
+import "../blocks/demo-web/home.page.block.js";
 
 const engine = new Engine();
 
-/**
- * Offline example: nav to data: hello page, then assert heading.
- * Flow fixtures override ticket-style copy on stubs (demo narration).
- */
+/** Smoke: nav + assert (no mem). Green offline. */
 export const exampleFlow = withHighlightFixtures(
   withTitle(
     engine.defineFlow([start, NavHomeBlock, AssertHelloBlock, end]),

package/templates/scaffold/src/flows/shop.flow.ts

@@ -0,0 +1,42 @@
+import {
+  Engine,
+  start,
+  end,
+  withTitle,
+  withHighlightFixtures,
+  withSessionReset,
+} from "waygraph";
+import { NavHomeBlock } from "../blocks/demo-web/nav-home.block.js";
+import { AddItemBlock } from "../blocks/demo-web/methods/add-item.effect.block.js";
+import { ClearCartBlock } from "../blocks/demo-web/methods/clear-cart.method.block.js";
+import "../blocks/demo-web/home.page.block.js";
+
+const engine = new Engine();
+
+/**
+ * Effect + Method demo (set mem for add-item, or use `waygraph auto` which
+ * fills SelectedItem via instanceOptions).
+ *
+ *   waygraph demo --blocks shopFlow --data '{"demo.selectedItem":{"id":"alpha","name":"Alpha"}}'
+ *   waygraph auto   # after landing on home, pick Add Alpha / Add Beta / …
+ */
+export const shopFlow = withHighlightFixtures(
+  withTitle(
+    withSessionReset(
+      engine.defineFlow([start, NavHomeBlock, AddItemBlock, ClearCartBlock, end]),
+    ),
+    "Scaffold: Shop (Effect + clear)",
+  ),
+  {
+    "add-item": {
+      stubAfter: {
+        cart: {
+          label: "AC · item in cart",
+          detail: "Cart count bumped after Add.",
+          tag: "AC",
+          duration: true,
+        },
+      },
+    },
+  },
+);

package/templates/scaffold/src/states/demo.mem-keys.ts

@@ -0,0 +1,7 @@
+import { keyGroup } from "waygraph";
+
+/**
+ * Which catalog row `add-item` / `remove-item` act on.
+ * `waygraph auto` fills this via Effect `instanceOptions` (one menu row per live button).
+ */
+export const SelectedItem = keyGroup<{ id: string; name: string }>("demo.selectedItem");

package/templates/scaffold/src/states/demo.states.ts

@@ -2,3 +2,5 @@ import type { Checkpoint } from "waygraph";
 
 export type Home = Checkpoint<"Home">;
 export type HomeVerified = Checkpoint<"HomeVerified">;
+export type ItemInCart = Checkpoint<"ItemInCart">;
+export type CartEmpty = Checkpoint<"CartEmpty">;

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

@@ -1,8 +1,17 @@
 import { test, expect } from "@playwright/test";
 import { MemPage, checkpoint } from "waygraph";
 import { exampleFlow } from "../src/flows/example.flow.js";
+import { shopFlow } from "../src/flows/shop.flow.js";
+import { SelectedItem } from "../src/states/demo.mem-keys.js";
 
 test("example flow reaches HomeVerified", async ({ context }) => {
   const result = await exampleFlow.run(context, new MemPage());
   expect(result).toEqual(checkpoint("HomeVerified"));
 });
+
+test("shop flow adds then clears (Effect + Method)", async ({ context }) => {
+  const mem = new MemPage();
+  mem.set(SelectedItem.key, { id: "alpha", name: "Alpha" });
+  const result = await shopFlow.run(context, mem);
+  expect(result).toEqual(checkpoint("CartEmpty"));
+});