waygraph 0.12.6 → 0.12.8

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"));
+});