create-waygraph 0.0.3 → 0.0.4

package/README.md

@@ -5,48 +5,50 @@ one fixed shape, no prompts, no template picker.
 
 This is the scaffold command linked from
 [waygraph GitHub Pages](https://deviate-dv8.github.io/waygraph/) (`npx create-waygraph`).
-Same template as `npx waygraph init` (waygraph >= 0.7.5). For a live saucedemo walkthrough
+Same template as `npx waygraph init` (waygraph >= 0.12.6). For a live saucedemo walkthrough
 without creating a folder in your cwd, use `npx waygraph try demo` instead.
 
+**Scaffold tree (authoritative):** https://deviate-dv8.github.io/waygraph/scaffold.html
+
 ```bash
 npx create-waygraph my-project
 cd my-project
 npm install
 npx playwright install chromium
 npm test
+npm run demo
 ```
 
-Generates:
+Generates (0.12+):
 
-```
+```text
 my-project/
-  package.json          waygraph + @playwright/test
-  tsconfig.json
-  playwright.config.ts
-  .gitignore
+  package.json
+  STRUCTURE.md
   src/
-    blocks/load-page.block.ts   one real Block (act/resolve/verify)
-    flows/example.flow.ts       Engine.defineFlow([start, LoadPageBlock, end])
-  tests/
-    example.spec.ts             runs the flow, asserts the terminal Checkpoint
+    blocks/
+      SITE-MAP.md
+      demo-web/                    # synthetic "/" (data: URL)
+        NAV.md
+        nav-home.block.ts
+        methods/
+          assert-hello.method.block.ts
+    states/demo.states.ts
+    flows/example.flow.ts          # withTitle + withHighlightFixtures
+  tests/example.spec.ts
 ```
 
-`npm test` goes green immediately, offline - the example Block navigates to a self-contained
-`data:` URL, not a live site, so scaffolding a project never depends on network access.
-
-Ships as its own package rather than a `waygraph init` subcommand, so consuming `waygraph`
-at runtime never pulls in scaffolding code - `npx create-waygraph` resolves and runs without
-adding anything to your own `node_modules`.
+`npm test` goes green offline - nav uses a `data:` URL. Stubs / fixtures / one YAP
+slide are already wired so `npm run demo` shows narration.
 
 ## Consumer layout (App Router projects)
 
-The minimal scaffold above is intentionally tiny (one block, no route tree). When the target
-app has real Next.js routes, **block folders mirror `app/` page routes**:
+When the target app has real Next.js routes, **block folders mirror `app/` page routes**:
 
 - URL `/` -> nav at namespace root (`zsign-web/` or `pia-web/`), not `landing/` or `root/`
 - Route groups `(auth)` / `(app)` vanish from folder names
 - Folders with no `page.tsx` are grouping only - no NAV.md, no nav block
 - Sidebar / layout chrome -> `shared/chrome/`, not a parallel `shell/nav/*` family
 
-Full contract: `WAYGRAPH-CONSUMER-CONVENTION.md` in your mesh
-(`.sm/seats/_shared/` on zsign/pia). Engine API: package `waygraph` README + WAYGRAPH-HANDOUT.
+Full contract: waygraph [Consumer layout](https://deviate-dv8.github.io/waygraph/consumer.html)
+and mesh handout `WAYGRAPH-CONSUMER-CONVENTION.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-waygraph",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Scaffold a new waygraph project - package.json, tsconfig, playwright.config, and one working example flow.",
   "license": "MIT",
   "type": "module",

package/templates/README.md

@@ -0,0 +1,25 @@
+# __PROJECT_NAME__
+
+Offline waygraph scaffold (`data:` URL - no network for `npm test`).
+
+## Layout
+
+See [STRUCTURE.md](./STRUCTURE.md). Package docs:
+https://deviate-dv8.github.io/waygraph/scaffold.html
+
+## Commands
+
+```bash
+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 auto:cli
+```
+
+Point `package.json` `waygraph.baseUrl` at your real app when you leave the
+`data:` demo. Keep route folders = app URLs (consumer layout).

package/templates/STRUCTURE.md

@@ -0,0 +1,36 @@
+# 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)
+
+```text
+.
+├── package.json              # waygraph ^0.12.6, demo/run/auto scripts
+├── playwright.config.ts
+├── tsconfig.json
+├── STRUCTURE.md              # this file
+├── README.md
+├── src/
+│   ├── blocks/
+│   │   ├── SITE-MAP.md       # namespace map (consumer convention)
+│   │   └── demo-web/         # synthetic site (data: URL) - mirrors app "/"
+│   │       ├── NAV.md
+│   │       ├── nav-home.block.ts
+│   │       └── methods/
+│   │           └── assert-hello.method.block.ts
+│   ├── states/
+│   │   └── demo.states.ts
+│   └── flows/
+│       └── example.flow.ts   # withTitle + withHighlightFixtures
+└── 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).
+
+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**.

package/templates/package.json

@@ -10,15 +10,16 @@
     "check": "waygraph check",
     "auto": "waygraph auto",
     "auto:cli": "waygraph auto --cli",
-    "demo": "waygraph demo src/flows/example.flow.ts",
-    "run": "waygraph run src/flows/example.flow.ts",
+    "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"
   },
   "waygraph": {
-    "baseUrl": "https://example.com"
+    "baseUrl": "about:blank"
   },
   "dependencies": {
-    "waygraph": "^0.10.6"
+    "waygraph": "^0.12.6"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0",

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

@@ -0,0 +1,13 @@
+# Site map (scaffold)
+
+Offline hello uses one synthetic namespace (`demo-web/`) and a `data:` home URL
+so `npm test` stays green without the network.
+
+| Folder | URL | Notes |
+|--------|-----|-------|
+| `demo-web/` | `/` (synthetic) | Nav + methods for the hello page |
+| `demo-web/methods/` | same URL | On-page asserts / future form acts |
+
+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.

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

@@ -0,0 +1,20 @@
+# demo-web / (synthetic home)
+
+**URL:** `data:text/html,…` (offline hello - replace with your real `/`)
+
+## Nav-to
+
+| From | Block | How |
+|------|-------|-----|
+| start | `nav-home` | `defineNavBlock` `url` → data HTML |
+
+## Methods
+
+| Block | Kind | Notes |
+|-------|------|-------|
+| `assert-hello` | Method | Verify heading; demo stubs + fixtures |
+
+## States / mem-keys
+
+- Checkpoint `Home` after nav
+- Checkpoint `HomeVerified` after assert-hello

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

@@ -0,0 +1,51 @@
+import { defineMethodBlock, checkpoint, Trait } from "waygraph";
+
+/**
+ * Kind: Method
+ * Helper: defineMethodBlock
+ * Route: demo-web/methods/
+ *
+ * Same-URL assert after nav - shows stubBefore / stubAfter / stubOnError shape.
+ */
+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 observe(page) {
+      await page.locator("h1").first().waitFor({ state: "visible", timeout: 5_000 });
+      return "ok" as const;
+    },
+    resolve: () => checkpoint("HomeVerified"),
+    verify: [Trait.text("h1", "Hello Waygraph"), Trait.visible("#sub")],
+    stubBefore: {
+      title: { selector: "h1", label: "Heading about to check" },
+    },
+    stubAfter: {
+      title: {
+        selector: "h1",
+        label: "Hello confirmed",
+        detail: "Offline scaffold proof point.",
+        duration: true,
+      },
+      sub: { selector: "#sub", label: "Subcopy", duration: 1500 },
+    },
+    stubOnError: {
+      title: {
+        selector: "h1",
+        label: "Heading at failure",
+        tag: "FAIL",
+      },
+    },
+    slides: [
+      {
+        caption: "Scaffold is route-shaped",
+        detail: "demo-web/ = synthetic /. Grow folders per real page.tsx.",
+        tag: "YAP",
+        duration: true,
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,25 @@
+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>';
+
+/**
+ * Kind: Nav
+ * Helper: defineNavBlock
+ * Route: demo-web/  (synthetic "/")
+ */
+export const NavHomeBlock = defineNavBlock({
+  name: "nav-home",
+  description: "Opens the offline hello page (data: URL).",
+  checkpoint: "Home",
+  url: HOME_URL,
+  verify: [Trait.text("h1", "Hello Waygraph")],
+  stubBefore: {},
+  stubAfter: {
+    title: { selector: "h1", label: "Home heading", duration: true },
+  },
+  stubOnError: {
+    title: { selector: "h1", label: "Home heading at failure" },
+  },
+});

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

@@ -1,6 +1,28 @@
-import { Engine, start, end } from "waygraph";
-import { LoadPageBlock } from "../blocks/load-page.block.js";
+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";
 
 const engine = new Engine();
 
-export const exampleFlow = engine.defineFlow([start, LoadPageBlock, end]);
+/**
+ * Offline example: nav to data: hello page, then assert heading.
+ * Flow fixtures override ticket-style copy on stubs (demo narration).
+ */
+export const exampleFlow = withHighlightFixtures(
+  withTitle(
+    engine.defineFlow([start, NavHomeBlock, AssertHelloBlock, end]),
+    "Scaffold: Hello Waygraph",
+  ),
+  {
+    "assert-hello": {
+      stubAfter: {
+        title: {
+          label: "AC · Hello visible",
+          detail: "Replace this fixture copy with your ticket lines.",
+          tag: "AC",
+          duration: true,
+        },
+      },
+    },
+  },
+);

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

@@ -0,0 +1,4 @@
+import type { Checkpoint } from "waygraph";
+
+export type Home = Checkpoint<"Home">;
+export type HomeVerified = Checkpoint<"HomeVerified">;

package/templates/tests/example.spec.ts

@@ -2,7 +2,7 @@ import { test, expect } from "@playwright/test";
 import { MemPage, checkpoint } from "waygraph";
 import { exampleFlow } from "../src/flows/example.flow.js";
 
-test("example flow reaches Loaded", async ({ context }) => {
+test("example flow reaches HomeVerified", async ({ context }) => {
   const result = await exampleFlow.run(context, new MemPage());
-  expect(result).toEqual(checkpoint("Loaded"));
+  expect(result).toEqual(checkpoint("HomeVerified"));
 });

package/templates/src/blocks/load-page.block.ts

@@ -1,18 +0,0 @@
-import { defineBlock, checkpoint, Trait } from "waygraph";
-import type { Checkpoint } from "waygraph";
-
-export type Start = Checkpoint<"__start__">;
-export type Loaded = Checkpoint<"Loaded">;
-
-const PAGE_URL = "data:text/html,<h1>Hello Waygraph</h1>";
-
-export const LoadPageBlock = defineBlock<Start, Loaded>({
-  name: "load-page",
-  instruction: {
-    async act(page) {
-      await page.goto(PAGE_URL);
-    },
-    resolve: () => checkpoint("Loaded"),
-    verify: [Trait.text("h1", "Hello Waygraph")],
-  },
-});