waygraph 0.12.6 → 0.12.8

package/dist/traverse-run.js

@@ -0,0 +1,227 @@
+/**
+ * Phase B: serial graph traverse (RFC traverse-ffcompose).
+ * Walk unused legal edges until leaf / budget / break. No parallel yet.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { Engine, start, end, locate } from "./engine.js";
+import { MemPage } from "./mem-page.js";
+import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
+import { defaultMemValueForKey } from "./auto-explore-run.js";
+function resolveBaseUrl(projectDir) {
+    if (process.env.WAYGRAPH_BASE_URL)
+        return process.env.WAYGRAPH_BASE_URL;
+    const pkgPath = join(projectDir, "package.json");
+    if (!existsSync(pkgPath))
+        return undefined;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.waygraph?.baseUrl;
+    }
+    catch {
+        return undefined;
+    }
+}
+function seedMem(library, mem, dataJson) {
+    const raw = dataJson ?? process.env.WAYGRAPH_DATA ?? process.env.WAYGRAPH_AUTO_MEM;
+    let envParsed = {};
+    if (raw) {
+        try {
+            envParsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`waygraph traverse: --data / WAYGRAPH_DATA is not valid JSON`);
+        }
+    }
+    for (const entry of library.values()) {
+        for (const k of entry.block.requires ?? []) {
+            if (mem.has(k))
+                continue;
+            if (k.name in envParsed) {
+                mem.set(k, envParsed[k.name]);
+                continue;
+            }
+            const def = defaultMemValueForKey(k.name);
+            if (def !== undefined)
+                mem.set(k, def);
+        }
+    }
+}
+function missingMemKeys(entry, mem) {
+    return (entry.block.requires ?? []).filter((k) => !mem.has(k));
+}
+function ensureMem(entry, mem) {
+    const missing = missingMemKeys(entry, mem);
+    if (missing.length === 0)
+        return;
+    throw new Error(`Block "${entry.block.name}" needs Mem keys: ${missing.map((k) => k.name).join(", ")} ` +
+        `(pass --data '{...}' or WAYGRAPH_DATA)`);
+}
+function edgeKey(edge) {
+    const id = edge.instanceOption?.id;
+    return id ? `${edge.block}::${id}` : edge.block;
+}
+async function detectHere(page, navBlocks) {
+    try {
+        const url = page.url();
+        if (url.includes("/login"))
+            return "PiaLogin";
+        if (url.includes("mailpit") || url.includes(":54324") || url.includes("/mailhog")) {
+            return "PiaMailpitGui";
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    const tags = navBlocks.map((n) => n.block);
+    return locate(page, tags, { timeoutMs: 1500 });
+}
+async function runOneBlock(engine, entry, context, page, mem) {
+    const flow = engine.defineFlow([start, entry.block, end]);
+    const BLOCK_TIMEOUT_MS = 45_000;
+    let timer;
+    try {
+        const ran = await Promise.race([
+            flow.run(context, mem, { page, closeOnFinish: false }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Block "${entry.block.name}" timed out after ${BLOCK_TIMEOUT_MS / 1000}s`)), BLOCK_TIMEOUT_MS);
+            }),
+        ]);
+        return ran.result;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Serial graph crawl. Prints greppable PASS/FAIL lines; non-zero exit on break.
+ */
+export async function runTraverse(projectDir, options = {}) {
+    const traverseId = options.traverseId ?? "traverse-1";
+    const maxSteps = options.maxSteps ?? 50;
+    const maxVisitsPerNode = options.maxVisitsPerNode ?? 2;
+    const maxVisitsPerEdge = options.maxVisitsPerEdge ?? 1;
+    const timeoutMs = options.timeoutMs ?? 15 * 60_000;
+    const headed = options.headed === true || process.env.WAYGRAPH_HEADED === "1";
+    const baseURL = options.baseURL ?? resolveBaseUrl(projectDir) ?? process.env.WAYGRAPH_BASE_URL;
+    const startUrl = options.startUrl ?? baseURL;
+    const { graph, library } = await buildExploreContext(projectDir);
+    const mem = new MemPage();
+    seedMem(library.byName, mem, options.data);
+    const engine = new Engine({ headless: !headed, slowMo: headed ? 100 : 0 });
+    const { chromium } = await import("@playwright/test");
+    const executablePath = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+    const launchOpts = {
+        headless: !headed,
+    };
+    if (executablePath)
+        launchOpts.executablePath = executablePath;
+    const browser = await chromium.launch(launchOpts);
+    const contextOpts = {
+        viewport: { width: 1280, height: 720 },
+    };
+    if (baseURL)
+        contextOpts.baseURL = baseURL;
+    const context = await browser.newContext(contextOpts);
+    let page = await context.newPage();
+    const nodeVisits = new Map();
+    const edgeVisits = new Map();
+    const edgesHit = new Set();
+    let steps = 0;
+    const startedAt = Date.now();
+    let lastHere = options.from ?? null;
+    let exitCode = 0;
+    console.error(`waygraph traverse[${traverseId}]: ${graph.nodes.length} node(s), ${graph.edges.length} edge(s)` +
+        (baseURL ? ` base=${baseURL}` : "") +
+        ` maxSteps=${maxSteps} maxVisits/node=${maxVisitsPerNode} maxVisits/edge=${maxVisitsPerEdge}`);
+    try {
+        if (startUrl) {
+            await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+            await page.waitForLoadState("load").catch(() => { });
+        }
+        for (;;) {
+            if (Date.now() - startedAt > timeoutMs) {
+                console.log(`[Killed timeout[${traverseId}] node=${lastHere ?? "?"} wallMs=${timeoutMs}]`);
+                exitCode = 1;
+                break;
+            }
+            if (steps >= maxSteps) {
+                console.log(`[Killed max-steps[${traverseId}] node=${lastHere ?? "?"} steps=${steps} max=${maxSteps}]`);
+                exitCode = 1;
+                break;
+            }
+            if (page.isClosed()) {
+                page = await context.newPage();
+                if (startUrl) {
+                    await page.goto(startUrl, { waitUntil: "domcontentloaded" }).catch(() => { });
+                }
+            }
+            const detected = await detectHere(page, library.navBlocks);
+            const here = lastHere ?? detected ?? options.from ?? null;
+            if (here && (nodeVisits.get(here) ?? 0) >= maxVisitsPerNode) {
+                console.log(`[Killed loop[${traverseId}] node=${here} visits=${nodeVisits.get(here)} max=${maxVisitsPerNode}]`);
+                exitCode = 1;
+                break;
+            }
+            const menu = await buildExploreMenu(page, graph, library, here);
+            const candidates = menu.flat.filter((edge) => {
+                const key = edgeKey(edge);
+                return (edgeVisits.get(key) ?? 0) < maxVisitsPerEdge;
+            });
+            if (candidates.length === 0) {
+                const label = here ?? detected ?? "unknown";
+                console.log(`[Reached Leaf Node[${traverseId}] at=${label} steps=${steps}]`);
+                console.error(`waygraph traverse[${traverseId}]: PASS leaf edgesHit=${edgesHit.size} steps=${steps}`);
+                break;
+            }
+            const pick = [...candidates].sort((a, b) => {
+                const aWild = a.from === "*" ? 1 : 0;
+                const bWild = b.from === "*" ? 1 : 0;
+                if (aWild !== bWild)
+                    return aWild - bWild;
+                return edgeKey(a).localeCompare(edgeKey(b));
+            })[0];
+            const entry = library.byName.get(pick.block);
+            if (!entry) {
+                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${here ?? "?"} to=${pick.to} reason=not-loaded]`);
+                exitCode = 1;
+                break;
+            }
+            const fromLabel = here ?? pick.from;
+            try {
+                if (pick.instanceOption) {
+                    mem.set(pick.instanceOption.key, pick.instanceOption.value);
+                }
+                ensureMem(entry, mem);
+                console.error(`waygraph traverse[${traverseId}]: step ${steps + 1} ${fromLabel} -[${pick.block}]-> ${pick.to}` +
+                    (pick.label ? ` (${pick.label})` : ""));
+                const out = await runOneBlock(engine, entry, context, page, mem);
+                const observed = typeof out === "object" && out && "__state" in out
+                    ? String(out.__state)
+                    : pick.to;
+                const key = edgeKey(pick);
+                edgeVisits.set(key, (edgeVisits.get(key) ?? 0) + 1);
+                edgesHit.add(key);
+                if (here)
+                    nodeVisits.set(here, (nodeVisits.get(here) ?? 0) + 1);
+                lastHere = observed;
+                steps += 1;
+                if (observed !== pick.to && pick.to !== "*") {
+                    console.error(`waygraph traverse[${traverseId}]: WARN static to=${pick.to} observed=${observed}`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.log(`[Broke at edge[${traverseId}] block=${pick.block} from=${fromLabel} to=${pick.to}] ${msg}`);
+                exitCode = 1;
+                break;
+            }
+        }
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+    console.error(`waygraph traverse[${traverseId}]: done exit=${exitCode} steps=${steps} edgesHit=${edgesHit.size}`);
+    return exitCode;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.12.6",
+  "version": "0.12.8",
   "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.