waygraph 0.15.49 → 0.15.51

package/examples/saucedemo/scripts/prove-add-to-cart-menu.mjs

@@ -6,6 +6,7 @@ import { chromium } from "@playwright/test";
 import { join, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
+import { chromiumExecutablePath } from "waygraph";
 
 const require = createRequire(import.meta.url);
 await import(require.resolve("tsx/esm"));
@@ -18,7 +19,7 @@ const { buildExploreContext, buildExploreMenu } = await import(
 );
 const { MemPage, Engine, start, end } = await import(pathToFileURL(join(waygraphDist, "index.js")).href);
 
-const exe = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+const exe = chromiumExecutablePath();
 
 async function runBlock(engine, entry, context, page, mem) {
   const flow = engine.defineFlow([start, entry.block, end]);

package/examples/saucedemo/scripts/prove-auto-graph.mjs

@@ -2,6 +2,7 @@ import { chromium } from "@playwright/test";
 import { join, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
+import { chromiumExecutablePath } from "waygraph";
 
 const require = createRequire(import.meta.url);
 await import(require.resolve("tsx/esm"));
@@ -15,7 +16,7 @@ const { buildExploreContext, buildExploreMenu } = await import(
 );
 const { locate, MemPage, Engine, start, end } = await import(pathToFileURL(join(waygraphDist, "index.js")).href);
 
-const exe = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+const exe = chromiumExecutablePath();
 
 async function snap(page, name) {
   const path = join(outDir, `graph-proof-${name}.png`);

package/examples/saucedemo/scripts/prove-wrong-login-runtime.mjs

@@ -6,6 +6,7 @@ import { chromium } from "@playwright/test";
 import { join, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
+import { chromiumExecutablePath } from "waygraph";
 
 const require = createRequire(import.meta.url);
 await import(require.resolve("tsx/esm"));
@@ -25,7 +26,7 @@ const { SubmitLoginBlock } = await import(
 );
 const { LoginCreds } = await import(pathToFileURL(join(root, "src/states/checkout.mem-keys.js")).href);
 
-const exe = process.env.CHROME_PATH || process.env.CHROMIUM_PATH;
+const exe = chromiumExecutablePath();
 const baseURL = "https://www.saucedemo.com";
 
 console.log("RUNTIME: headless browser (wrong password test)...");

package/examples/saucedemo/tests/flow-block-verify.spec.ts

@@ -1,7 +1,6 @@
 import { test, expect } from "@playwright/test";
 import { MemPage, checkpoint, Trait } from "waygraph";
 import { checkoutFlow } from "../src/flows/checkout.flow.js";
-import { FfOwnerAuthBlock } from "../src/blocks/saucedemo-web/ff-owner-auth.block.js";
 import { LoginCreds, SelectedItem } from "../src/states/checkout.mem-keys.js";
 
 // checkoutFlow.withBlockVerify/modBlockVerify - a spec that only imports the
@@ -31,12 +30,8 @@ test("withBlockVerify: replacing login's verify with an extra real check still p
   mem.set(LoginCreds({ username: "standard_user", password: "secret_sauce" }));
   mem.set(SelectedItem({ id: "sauce-labs-backpack", name: "Sauce Labs Backpack" }));
 
-  // Addressed by the actual FfOwnerAuthBlock reference - the preferred
-  // form: no typo risk, refactor-safe, jump-to-definition works. checkoutFlow
-  // drives login through the ff-owner-auth FFCompose step (collapsed
-  // nav-login + fill-username + fill-password + submit-login), not a bare
-  // SubmitLoginBlock reference, so that's the Block whose verify this patches.
-  const patched = checkoutFlow.withBlockVerify(FfOwnerAuthBlock, [
+  // checkoutFlow's login steps are one inline `{ ff: true }` group, auto-named "ff-1".
+  const patched = checkoutFlow.withBlockVerify("ff-1", [
     Trait.url({ pathname: "/inventory.html" }),
     Trait.visible(".inventory_list"),
   ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.49",
+  "version": "0.15.51",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
@@ -30,7 +30,15 @@
     "!examples/**/.waygraph-traverse/**",
     "!examples/**/.waygraph-videos",
     "!examples/**/.waygraph-videos/**",
-    "!**/*.webm"
+    "!**/*.webm",
+    "!**/.waygraph-auto",
+    "!**/.waygraph-auto/**",
+    "!**/test-results",
+    "!**/test-results/**",
+    "!**/playwright-report",
+    "!**/playwright-report/**",
+    "!**/.waygraph-chain-*.mjs",
+    "!**/*.log"
   ],
   "repository": {
     "type": "git",

package/templates/quickstart/playwright.config.ts

@@ -10,11 +10,5 @@ export default defineConfig({
     headless: true,
     baseURL: "https://www.saucedemo.com",
     trace: "retain-on-failure",
-    launchOptions: {
-      // Canonical Chromium on this machine is the Flatpak install - never let
-      // Playwright download its own bundled binary. See .agent/manager-agent.md.
-      executablePath: process.env.CHROME_PATH || process.env.CHROMIUM_PATH,
-      args: ["--no-sandbox", "--disable-dev-shm-usage"],
-    },
   },
 });

package/templates/scaffold/README.md

@@ -1,7 +1,7 @@
 # __PROJECT_NAME__
 
 A waygraph project on the **Waygraph Map** layout: `src/map/` folders mirror your app's URLs.
-Runs fully offline - `npm test` is green on a local fixture page.
+Runs fully offline - the demo pages open directly via `file://`, no server or network needed.
 
 ## Run it
 
@@ -24,7 +24,9 @@ one Block per action, flows in `src/flows/`.
 
 ## Point it at your real app
 
-Set `waygraph.baseUrl` in `package.json`, drop the `scripts/with-fixture.mjs` wrappers, and
-keep each `src/map/` folder matching the URL it represents (`waygraph map` enforces this).
+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
+`src/map/` folder matching the URL it represents (`waygraph map` enforces this).
 
 Docs: https://deviate-dv8.github.io/waygraph/

package/templates/scaffold/STRUCTURE.md

@@ -9,12 +9,12 @@ Next.js route groups) and never appear in a URL or Checkpoint name.
 ├── package.json
 ├── src/
 │   ├── map/
-│   │   ├── (app_base)/                # your app (served on :4177 here)
-│   │   │   ├── home/                  # URL /home.html
+│   │   ├── (app_base)/                # your app (opened via file:// here)
+│   │   │   ├── home/                  # URL /home
 │   │   │   │   ├── _nav.block.ts      # how to get here
 │   │   │   │   ├── _page.block.ts     # "you have arrived" hub
 │   │   │   │   ├── _sel.ts            # every selector for this page
-│   │   │   │   ├── home.html          # offline fixture page
+│   │   │   │   ├── index.html         # offline fixture page
 │   │   │   │   └── _methods/          # one action per Block
 │   │   │   │       ├── add-item.effect.block.ts       # + instanceOptions (auto menu)
 │   │   │   │       ├── remove-item.effect.block.ts
@@ -25,7 +25,6 @@ Next.js route groups) and never appear in a URL or Checkpoint name.
 │   │   └── (external)/mailpit/        # a different origin (mail catcher)
 │   ├── states/                        # Checkpoint types + mem keys
 │   └── flows/                         # example / shop / mail-verify
-├── scripts/                           # local fixture server
 └── tests/example.spec.ts
 ```
 

package/templates/scaffold/package.json

@@ -7,22 +7,18 @@
     "typecheck": "waygraph typecheck .",
     "test": "waygraph test",
     "test:ui": "waygraph test ui",
-    "fixture": "node scripts/fixture-server.mjs",
     "list": "waygraph list",
     "check": "waygraph check",
     "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": "http://127.0.0.1:4177"
+    "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"
   },
   "dependencies": {
     "waygraph": "^0.12.20"

package/templates/scaffold/playwright.config.ts

@@ -1,28 +1,12 @@
 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"], ["html", { open: "never" }]],
   use: {
-    baseURL: FIXTURE_ORIGIN,
+    // Demo pages open via file:// - no server. Filled in by `waygraph init`.
+    baseURL: "__APP_BASE_URL__",
     trace: "retain-on-failure",
-    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/src/flows/shop.flow.ts

@@ -5,21 +5,34 @@ import {
   withTitle,
   withHighlightFixtures,
   withSessionReset,
+  withMemStub,
+  registerMemStub,
 } from "waygraph";
 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 { SelectedItem } from "../states/demo.mem-keys.js";
 import "../map/(app_base)/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).
+ * memStub: a real fixture row (`alpha`/`Alpha`), registered once so this Flow never needs
+ * --data at all. Still override-able - `--data '{"demo.selectedItem":{"id":"beta",...}}'`
+ * wins over this registration, same as any other memStub (see docs/REFERENCE.md's own
+ * "memStub - fake values for requires" section).
+ */
+registerMemStub(SelectedItem.key, () => ({ id: "alpha", name: "Alpha" }));
+
+/**
+ * Effect + Method demo. `requires: [SelectedItem.key]` (on `add-item`) is filled automatically
+ * by the memStub registration above - no --data needed. Override it with real data, or use
+ * `waygraph auto` which fills SelectedItem via instanceOptions instead:
  *
- *   waygraph demo --blocks shopFlow --data '{"demo.selectedItem":{"id":"alpha","name":"Alpha"}}'
+ *   waygraph demo --blocks shopFlow                                    # memStub fills it
+ *   waygraph demo --blocks shopFlow --data '{"demo.selectedItem":{"id":"beta","name":"Beta"}}'
  *   waygraph auto   # after landing on home, pick Add Alpha / Add Beta / Remove ...
  *
  * Add -> assert it actually landed (mem-matched Remove button + cart count,
@@ -28,32 +41,34 @@ const engine = new Engine();
  * Clear cart (bulk Method, `clear-cart`) - keeps both the per-item and bulk
  * clear paths atomic and each wired into a real flow, not orphaned.
  */
-export const shopFlow = withHighlightFixtures(
-  withTitle(
-    withSessionReset(
-      engine.defineFlow([
-        start,
-        NavHomeBlock,
-        AddItemBlock,
-        AssertItemAddedBlock,
-        RemoveItemBlock,
-        AddItemBlock,
-        ClearCartBlock,
-        end,
-      ]),
+export const shopFlow = withMemStub(
+  withHighlightFixtures(
+    withTitle(
+      withSessionReset(
+        engine.defineFlow([
+          start,
+          NavHomeBlock,
+          AddItemBlock,
+          AssertItemAddedBlock,
+          RemoveItemBlock,
+          AddItemBlock,
+          ClearCartBlock,
+          end,
+        ]),
+      ),
+      "Scaffold: Shop (Effect + clear)",
     ),
-    "Scaffold: Shop (Effect + clear)",
-  ),
-  {
-    "add-item": {
-      stubAfter: {
-        cart: {
-          label: "AC · item in cart",
-          detail: "Cart count bumped after Add.",
-          tag: "AC",
-          duration: true,
+    {
+      "add-item": {
+        stubAfter: {
+          cart: {
+            label: "AC · item in cart",
+            detail: "Cart count bumped after Add.",
+            tag: "AC",
+            duration: true,
+          },
         },
       },
     },
-  },
+  ),
 );

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

@@ -6,7 +6,7 @@ import { DocsSel, DOCS_URL } from "./_sel.js";
  * Kind: Nav
  * Route: (app_base)/docs/
  *
- * Same origin as home/ (same fixture server, different HTML file) - lives
+ * 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.

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

@@ -1,6 +1,5 @@
-export const DOCS_URL =
-  process.env.WAYGRAPH_DOCS_URL ??
-  `http://${process.env.WAYGRAPH_FIXTURE_HOST || "127.0.0.1"}:${process.env.WAYGRAPH_FIXTURE_PORT || "4177"}/docs.html`;
+// Relative to playwright.config.ts's baseURL (the (app_base) folder, set by `waygraph init`).
+export const DOCS_URL = "docs/index.html";
 
 export const DocsSel = {
   heading: "#docs-heading",

package/templates/scaffold/src/map/(app_base)/docs/{docs.html → index.html}

@@ -3,6 +3,6 @@
 <head><title>Scaffold - docs (Waygraph Map convention demo)</title></head>
 <body>
   <h1 id="docs-heading">Docs</h1>
-  <a id="go-home" href="/home.html">Back home</a>
+  <a id="go-home" href="../home/index.html">Back home</a>
 </body>
 </html>

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

@@ -1,10 +1,9 @@
 import {
   defineEffectBlock,
   checkpoint,
-  type Checkpoint,
   type WaygraphInstanceOption,
 } from "waygraph";
-import type { ItemInCart } from "../../../../states/demo.states.js";
+import type { CanAddItem, ItemInCart } from "../../../../states/demo.states.js";
 import { SelectedItem } from "../../../../states/demo.mem-keys.js";
 import { DemoSel } from "../_sel.js";
 
@@ -16,7 +15,7 @@ import { DemoSel } from "../_sel.js";
  * 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>({
+export const AddItemBlock = defineEffectBlock<CanAddItem, ItemInCart>({
   name: "add-item",
   description: "Adds the mem-selected catalog item to the cart.",
   requires: [SelectedItem.key],
@@ -35,15 +34,6 @@ export const AddItemBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>({
         },
       },
     ],
-    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])");
@@ -65,4 +55,13 @@ export const AddItemBlock = defineEffectBlock<Checkpoint<string>, 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

@@ -1,4 +1,5 @@
 import { defineAssertBlock, Trait } from "waygraph";
+import type { Home } from "../../../../states/demo.states.js";
 import { DemoSel } from "../_sel.js";
 
 /**
@@ -10,31 +11,12 @@ import { DemoSel } from "../_sel.js";
  * act/resolve to accidentally do a second thing. Same-URL assert after nav,
  * with stubs + fixtures + a YAP slide.
  */
-export const AssertHelloBlock = defineAssertBlock({
+export const AssertHelloBlock = defineAssertBlock<Home>({
   name: "assert-hello",
   description: "Confirms the hello heading is still visible after arrival.",
-  checkpoint: "HomeVerified",
+  checkpoint: "Home",
   waitForHeading: "Hello Waygraph",
   verify: [Trait.text(DemoSel.title, "Hello Waygraph"), Trait.visible(DemoSel.sub)],
-  stubBefore: {
-    title: { selector: DemoSel.title, label: "Heading about to check" },
-  },
-  stubAfter: {
-    title: {
-      selector: DemoSel.title,
-      label: "Hello confirmed",
-      detail: "Offline scaffold proof point.",
-      duration: true,
-    },
-    sub: { selector: DemoSel.sub, label: "Subcopy", duration: 1500 },
-  },
-  stubOnError: {
-    title: {
-      selector: DemoSel.title,
-      label: "Heading at failure",
-      tag: "FAIL",
-    },
-  },
   slides: [
     {
       caption: "Scaffold covers auto + narration",
@@ -43,4 +25,19 @@ export const AssertHelloBlock = defineAssertBlock({
       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/clear-cart.method.block.ts

@@ -21,12 +21,11 @@ export const ClearCartBlock = defineMethodBlock<ItemInCart, CartEmpty>({
     },
     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: {},
   },
-});
+})
+  .stubBefore((ctx) => {
+    ctx.ring("clear", { selector: DemoSel.clear, label: "Clear cart" });
+  })
+  .stubAfter((ctx) => {
+    ctx.ring("cart", { selector: DemoSel.cartCount, label: "Empty cart", duration: true });
+  });

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

@@ -1,10 +1,9 @@
 import {
   defineEffectBlock,
   checkpoint,
-  type Checkpoint,
   type WaygraphInstanceOption,
 } from "waygraph";
-import type { CartEmpty } from "../../../../states/demo.states.js";
+import type { CartEmpty, ItemInCart } from "../../../../states/demo.states.js";
 import { SelectedItem } from "../../../../states/demo.mem-keys.js";
 import { DemoSel } from "../_sel.js";
 
@@ -15,7 +14,7 @@ import { DemoSel } from "../_sel.js";
  *
  * Removes one in-cart row. Auto menus one row per visible Remove button.
  */
-export const RemoveItemBlock = defineEffectBlock<Checkpoint<string>, CartEmpty>({
+export const RemoveItemBlock = defineEffectBlock<ItemInCart, CartEmpty>({
   name: "remove-item",
   description: "Removes the mem-selected catalog item from the cart.",
   requires: [SelectedItem.key],
@@ -34,11 +33,6 @@ export const RemoveItemBlock = defineEffectBlock<Checkpoint<string>, CartEmpty>(
         },
       },
     ],
-    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])");
@@ -60,4 +54,6 @@ export const RemoveItemBlock = defineEffectBlock<Checkpoint<string>, CartEmpty>(
     }
     return out;
   },
+}).stubAfter((ctx) => {
+  ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart count", duration: true });
 });

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

@@ -1,4 +1,5 @@
 import { defineNavBlock, Trait } from "waygraph";
+import type { Home } from "../../../states/demo.states.js";
 import { DemoSel, HOME_URL } from "./_sel.js";
 
 /**
@@ -6,17 +7,16 @@ import { DemoSel, HOME_URL } from "./_sel.js";
  * Helper: defineNavBlock
  * Route: (app_base)/home/  (synthetic "/")
  */
-export const NavHomeBlock = defineNavBlock({
+export const NavHomeBlock = defineNavBlock<Home>({
   name: "nav-home",
-  description: "Opens the offline catalog page (HTTP fixture :4177).",
+  description: "Opens the offline catalog page (file://, no server).",
   checkpoint: "Home",
   url: HOME_URL,
   verify: [Trait.text(DemoSel.title, "Hello Waygraph"), Trait.visible(DemoSel.catalog)],
-  stubBefore: {},
-  stubAfter: {
-    title: { selector: DemoSel.title, label: "Home heading", duration: true },
-  },
-  stubOnError: {
-    title: { selector: DemoSel.title, label: "Home heading at failure" },
-  },
-});
+})
+  .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" });
+  });

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

@@ -1,7 +1,5 @@
-/** 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`;
+// Relative to playwright.config.ts's baseURL (the (app_base) folder, set by `waygraph init`).
+export const HOME_URL = "home/index.html";
 
 export const DemoSel = {
   title: "h1",

package/templates/scaffold/src/map/(app_base)/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Waygraph scaffold demo</title>
+    <style>
+      body { font-family: system-ui, sans-serif; margin: 6rem 2rem 2rem; }
+    </style>
+  </head>
+  <body>
+    <h1>Waygraph scaffold demo</h1>
+    <ul>
+      <li><a href="home/index.html">Home</a></li>
+      <li><a href="docs/index.html">Docs</a></li>
+    </ul>
+  </body>
+</html>

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

@@ -4,6 +4,8 @@ export type Home = Checkpoint<"Home">;
 export type HomeVerified = Checkpoint<"HomeVerified">;
 export type ItemInCart = Checkpoint<"ItemInCart">;
 export type CartEmpty = Checkpoint<"CartEmpty">;
+/** Anywhere an item can be added from: fresh on Home, or after the cart was emptied. */
+export type CanAddItem = Home | CartEmpty;
 
 // --- Mailpit (external tool surface, src/map/(external)/mailpit/) ---
 

package/templates/scaffold/tests/README.md

@@ -2,8 +2,9 @@
 
 Real `@playwright/test` specs, run through `waygraph test` (an alias for `playwright test`,
 plus `waygraph test ui`/`report`/`show-trace` for Playwright's own UI Mode/HTML report/trace
-viewer). These run against the offline fixture server (see `scripts/README.md`), not a live
-network - that's what makes `npm test` green immediately after `waygraph init`.
+viewer). These run against the offline fixture pages under `src/map/` (opened directly via `file://`,
+no server), not a live network - that's what makes `npm test` green immediately after
+`waygraph init`.
 
 A spec here typically runs a `*.flow.ts` from `src/flows/` and asserts on its result, rather
 than driving the page directly - the flow already encodes the real path and its own `verify`

package/templates/scaffold/tsconfig.json

@@ -10,5 +10,5 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src/**/*.ts", "tests/**/*.ts"]
+  "include": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts"]
 }

package/templates/skills/waygraph-convention.skill.md

@@ -42,9 +42,11 @@ against a live site, use `--skill-pilot-blind`.
    hand-supplied every time, `registerMemStub(key, fake)` + `withMemStub(flow)` (or
    `--mem-stub`) fills it from a registry instead - a key with no registration still fails
    preflight exactly as before, so this narrows what needs real input, never removes the guard.
-6. **Keep Checkpoints typed — never `Checkpoint<string>`.** Block helpers take concrete
-   Checkpoint types from `src/states/` (e.g. `defineMethodBlock<LoginPage, LoginPage>`).
-   Wildcard `Checkpoint<string>` compiles but kills graph honesty; `waygraph check` / `waygraph typecheck` warn.
+6. **Keep Checkpoints typed.** Block helpers take concrete Checkpoint types from `src/states/`
+   (e.g. `defineMethodBlock<LoginPage, LoggedIn>`). A Block's **output** must never be
+   `Checkpoint<string>` — `waygraph check` / `waygraph typecheck` warn. When a Block runs from a
+   few known states, name them as a union in `src/states/` (`type CanAddItem = Home | CartEmpty`);
+   a `Checkpoint<string>` **input** is only for a Block that's genuinely reachable from anywhere.
    Same for `defineAssertBlock({…})` without an explicit type arg — use
    `defineAssertBlock<YourCheckpoint>({…})`.
 7. **One input/action per Method Block.** No block that `.fill()`s two fields or `.fill()` + `.click()` in one