waygraph 0.15.19 → 0.15.21

package/templates/scaffold/STRUCTURE.md

@@ -1,81 +1,48 @@
-# Offline scaffold layout (`waygraph init` / `create-waygraph`)
+# Scaffold layout (`waygraph init`)
 
-Shipped under `templates/scaffold/` in the **waygraph** package.
-Docs: [docs/scaffold.html](../../docs/scaffold.html)
+This scaffold uses the **Waygraph Map**: folders under `src/map/` mirror your app's URLs.
+One folder = one page = one Checkpoint. `(group)` folders are organizational only (like
+Next.js route groups) and never appear in a URL or Checkpoint name.
 
 ```text
 .
 ├── package.json
-├── STRUCTURE.md              # this file
-├── README.md
 ├── src/
-│   ├── blocks/
-│   │   ├── SITE-MAP.md
-│   │   └── demo-web/         # synthetic "/" (HTTP fixture :4177)
-│   │       ├── NAV.md
-│   │       ├── 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   # 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.mem-keys.ts  # SelectedItem for Effect / auto
-│   ├── flows/
-│   │   ├── example.flow.ts   # nav + assert (smoke)
-│   │   ├── shop.flow.ts      # nav + add-item + clear (Effect path)
-│   │   └── routes-demo.flow.ts  # Home (manual mode) -> Docs (Map convention)
-│   └── routes/                       # Waygraph Map convention - see README.md
-│       └── (external)/
-│           └── docs/
-│               ├── docs.sel.ts
-│               ├── nav.block.ts      # fixed name - every page-slug folder's Nav
-│               └── page.block.ts     # fixed name - every page-slug folder's arrival hub
-├── scripts/
-│   ├── fixture-server.mjs    # serves home.html on :4177
-│   └── with-fixture.mjs      # start server + run waygraph auto/demo/run
-└── tests/
-    └── example.spec.ts
+│   ├── map/
+│   │   ├── (app_base)/                # your app (served on :4177 here)
+│   │   │   ├── home/                  # URL /home.html
+│   │   │   │   ├── _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
+│   │   │   │   └── _methods/          # one action per Block
+│   │   │   │       ├── add-item.effect.block.ts       # + instanceOptions (auto menu)
+│   │   │   │       ├── remove-item.effect.block.ts
+│   │   │   │       ├── clear-cart.method.block.ts
+│   │   │   │       ├── assert-hello.method.block.ts   # + stubs + YAP slide
+│   │   │   │       └── assert-item-added.method.block.ts
+│   │   │   └── docs/                  # a second page, same shape
+│   │   └── (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
 ```
 
-## Features covered
+Underscore-prefixed files (`_nav`, `_page`, `_sel`, `_methods/`) are the fixed names every
+page folder uses, so any agent or teammate knows where to look without asking.
 
-| 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 |
+## What each piece is for
 
-## Auto
+| Want to... | Look at |
+|---|---|
+| Add a page | copy a folder under `src/map/`, keep the `_nav` / `_page` / `_sel` names |
+| Add an action on a page | one file in that page's `_methods/` |
+| Verify a state (button disabled, error shown) | `defineAssertBlock` + `Trait.disabled` / `Trait.enabled` |
+| Wire steps together | `src/flows/*.flow.ts` |
+| Give a flow fake data | `registerMemStub(key, fake)` + `withMemStub(flow)` (docs: docs/REFERENCE.md, "memStub") |
+| Explore by hand | `npm run auto` (headed) or `npm run auto:cli` |
+| Check your work | `npm run check`, `npm run graph`, `waygraph map` |
 
-```bash
-npm run auto        # headed explore - pick Add Alpha / Add Beta from live DOM
-npm run auto:cli    # same menus in the terminal
-```
-
-After `nav-home`, Effect blocks expose one menu row per visible Add/Remove button.
-
-## Two authoring modes
-
-`src/blocks/` (`demo-web/`, `demo-external/`) is **manual mode** - freeform, developer-chosen
-file layout, the default this whole scaffold otherwise uses.
-
-`src/routes/` is the **Waygraph Map** convention - `(group)/<page-slug>/page.block.ts` +
-`nav.block.ts` + `methods/*.block.ts`, one Checkpoint per folder, `(group)` purely
-organizational (parens, Next.js route-group style - never part of the Checkpoint tag). Same
-Block helpers, same execution - only where files live and what they're named changes. A
-project can adopt it folder by folder; `routes-demo.flow.ts` proves both modes compose in one
-flow (`nav-home` from `blocks/`, `nav-docs` from `routes/`). See the main package's own
-`README.md` "Waygraph Map" section and `openspec/changes/waygraph-map/`.
+`waygraph map` fails if a folder path stops matching the real URL it claims to represent.
+Full convention: https://deviate-dv8.github.io/waygraph/consumer.html

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

@@ -7,7 +7,7 @@ import { DocsSel, DOCS_URL } from "./_sel.js";
  * Route: (app_base)/docs/
  *
  * Same origin as home/ (same fixture server, different HTML file) - lives
- * under (app_base), not (external). See README.md "Waygraph Map" and
+ * 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/(external)/mailpit/_methods/assert-email-content.method.block.ts

@@ -27,7 +27,7 @@ const bodyContainsExpectedText: Trait = {
  * "Does the email actually say what it's supposed to" - not just "does a
  * link exist somewhere in it." Reads the message body straight out of the
  * preview iframe (the top-level page's own `Trait.text`/`Trait.visible`
- * can't see inside an iframe at all - see README's "Mail adapters" section).
+ * can't see inside an iframe at all - see docs/REFERENCE.md "Mail adapters" section).
  * Self-loop on MailpitMessageOpen - no state change, verify only.
  *
  * Deliberately named for what it does, not for one scenario: the expected

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

@@ -28,7 +28,11 @@ against a live site, use `--skill-pilot-blind`.
    `Trait.enabled(selector)` cover that directly; write a custom Trait only for a state
    condition neither one expresses.
 5. **`requires` = externally supplied.** A key an earlier Block in the same chain produces
-   is never listed under `requires` - preflight checks the whole chain up front.
+   is never listed under `requires` - preflight checks the whole chain up front. For a
+   genuinely arbitrary key (a username, an email) that a demo/dev run shouldn't need
+   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.

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

@@ -134,7 +134,7 @@ waygraph auto highlight <sessionId> '{"clear":true}'
 Supported fields (demo parity):
 - `rings[]`: `selector`, `label`, `detail`, `tag`, `tone`, `size`, `weight`, `color`, `zoom`, `zoomOut`, `focus`
 - `todos` / `todoIndex` / `todoTitle` / `todoPos` (`right` default | `left`)
-- `todoUi`: `{ compact?, cap?, expandCap?, collision?, behindRing? }` — same dock UX as demo (defaults smart-on; see README "Todo dock UI")
+- `todoUi`: `{ compact?, cap?, expandCap?, collision?, behindRing? }` — same dock UX as demo (defaults smart-on; see docs/REFERENCE.md "Todo dock UI")
 - `zoom` / `zoomSelector` / `zoomOut` - scroll + zoom badge (not CSS page scale)
 - `device`: `mobile` | `tablet` | `desktop` (Playwright viewport)
 - `holdMs`: ms to keep fixtures; `0` = until the next highlight / clear (default 30000)

package/examples/saucedemo/.waygraph-auto/4adfbe91.json

@@ -1,8 +0,0 @@
-{
-  "sessionId": "4adfbe91",
-  "socketPath": "/tmp/waygraph-auto/4adfbe91.sock",
-  "pid": 1479053,
-  "projectDir": "/home/dan/Desktop/Projects/waygraph/examples/saucedemo",
-  "startedAt": "2026-09-22T02:04:35.751Z",
-  "headless": false
-}

package/examples/saucedemo/.waygraph-auto/9f0287e6.json

@@ -1,8 +0,0 @@
-{
-  "sessionId": "9f0287e6",
-  "socketPath": "/tmp/waygraph-auto/9f0287e6.sock",
-  "pid": 2653914,
-  "projectDir": "/home/dan/Desktop/Projects/waygraph/examples/saucedemo",
-  "startedAt": "2026-09-23T01:33:06.508Z",
-  "headless": false
-}