waygraph 0.15.20 → 0.15.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +72 -1346
  2. package/package.json +1 -1
  3. package/templates/scaffold/README.md +21 -19
  4. package/templates/scaffold/STRUCTURE.md +37 -70
  5. package/templates/scaffold/src/map/(app_base)/docs/_nav.block.ts +1 -1
  6. package/templates/scaffold/src/map/(external)/mailpit/_methods/assert-email-content.method.block.ts +1 -1
  7. package/templates/skills/waygraph-pilot.skill.md +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "waygraph",
3
- "version": "0.15.20",
3
+ "version": "0.15.21",
4
4
  "type": "module",
5
5
  "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
6
6
  "license": "MIT",
package/templates/scaffold/README.md CHANGED
@@ -1,28 +1,30 @@
1
1
  # __PROJECT_NAME__
2
2
 
3
- Offline waygraph scaffold - Nav, Page hub, Method, Effect (`instanceOptions` for
4
- `waygraph auto`), stubs/fixtures/YAP, mem keys.
3
+ A waygraph project on the **Waygraph Map** layout: `src/map/` folders mirror your app's URLs.
4
+ Runs fully offline - `npm test` is green on a local fixture page.
5
5
 
6
- ## Layout
7
-
8
- See [STRUCTURE.md](./STRUCTURE.md). Docs:
9
- https://deviate-dv8.github.io/waygraph/scaffold.html
10
-
11
- ## Commands
6
+ ## Run it
12
7
 
13
8
  ```bash
14
9
  npm install
15
10
  npx playwright install chromium
16
- npm test
17
- npm run list && npm run check && npm run graph
18
- npm run demo # exampleFlow (hello + YAP)
19
- npm run demo:shop # Effect path (needs --data selectedItem)
20
- npm run auto # headed explore - pick Add Alpha / …
21
- npm run auto:cli
22
- npx waygraph agent-dive --loop claude # coding-agent defs (optional)
11
+ npm test # run the tests
12
+ npm run test:ui # same, in Playwright's interactive UI
13
+ npm run demo # watch a flow with the step overlay
14
+ npm run auto # explore the app by picking Blocks
23
15
  ```
24
16
 
25
- Point `package.json` `waygraph.baseUrl` at your real app when you leave the
26
- fixture (and drop `scripts/with-fixture.mjs` wrappers). Keep route folders =
27
- app URLs (consumer layout).
28
- Offline fixture is HTTP `http://127.0.0.1:4177/home.html` (Flatpak-safe).
17
+ More: `npm run check` (lint your Blocks), `npm run graph` (see the whole graph),
18
+ `npx waygraph test report` (open the last report + traces).
19
+
20
+ ## Where things live
21
+
22
+ See [STRUCTURE.md](./STRUCTURE.md). Short version: one folder per page under `src/map/`,
23
+ one Block per action, flows in `src/flows/`.
24
+
25
+ ## Point it at your real app
26
+
27
+ Set `waygraph.baseUrl` in `package.json`, drop the `scripts/with-fixture.mjs` wrappers, and
28
+ keep each `src/map/` folder matching the URL it represents (`waygraph map` enforces this).
29
+
30
+ Docs: https://deviate-dv8.github.io/waygraph/
package/templates/scaffold/STRUCTURE.md CHANGED
@@ -1,81 +1,48 @@
1
- # Offline scaffold layout (`waygraph init` / `create-waygraph`)
1
+ # Scaffold layout (`waygraph init`)
2
2
 
3
- Shipped under `templates/scaffold/` in the **waygraph** package.
4
- Docs: [docs/scaffold.html](../../docs/scaffold.html)
3
+ This scaffold uses the **Waygraph Map**: folders under `src/map/` mirror your app's URLs.
4
+ One folder = one page = one Checkpoint. `(group)` folders are organizational only (like
5
+ Next.js route groups) and never appear in a URL or Checkpoint name.
5
6
 
6
7
  ```text
7
8
  .
8
9
  ├── package.json
9
- ├── STRUCTURE.md # this file
10
- ├── README.md
11
10
  ├── src/
12
- │ ├── blocks/
13
- │ │ ├── SITE-MAP.md
14
- │ │ └── demo-web/ # synthetic "/" (HTTP fixture :4177)
15
- │ │ ├── NAV.md
16
- │ │ ├── home.html # offline fixture (catalog + cart)
17
- │ │ ├── demo-sel.ts
18
- │ │ ├── nav-home.block.ts # Nav
19
- │ │ ├── home.page.block.ts # Page hub (methods registry)
20
- │ │ └── methods/
21
- │ │ ├── assert-hello.method.block.ts # Method + stubs + YAP
22
- │ │ ├── add-item.effect.block.ts # Effect + instanceOptions (auto)
23
- │ │ ├── remove-item.effect.block.ts # Effect + instanceOptions
24
- │ │ └── clear-cart.method.block.ts # Method
25
- │ ├── states/
26
- │ │ ├── demo.states.ts
27
- │ │ └── demo.mem-keys.ts # SelectedItem for Effect / auto
28
- │ ├── flows/
29
- │ │ ├── example.flow.ts # nav + assert (smoke)
30
- │ │ ├── shop.flow.ts # nav + add-item + clear (Effect path)
31
- │ │ └── routes-demo.flow.ts # Home (manual mode) -> Docs (Map convention)
32
- │ └── routes/ # Waygraph Map convention - see README.md
33
- │ └── (external)/
34
- │ └── docs/
35
- │ ├── docs.sel.ts
36
- │ ├── nav.block.ts # fixed name - every page-slug folder's Nav
37
- │ └── page.block.ts # fixed name - every page-slug folder's arrival hub
38
- ├── scripts/
39
- │ ├── fixture-server.mjs # serves home.html on :4177
40
- │ └── with-fixture.mjs # start server + run waygraph auto/demo/run
41
- └── tests/
42
- └── example.spec.ts
11
+ │ ├── map/
12
+ │ │ ├── (app_base)/ # your app (served on :4177 here)
13
+ │ │ │ ├── home/ # URL /home.html
14
+ │ │ │ │ ├── _nav.block.ts # how to get here
15
+ │ │ │ │ ├── _page.block.ts # "you have arrived" hub
16
+ │ │ │ │ ├── _sel.ts # every selector for this page
17
+ │ │ │ │ ├── home.html # offline fixture page
18
+ │ │ │ │ └── _methods/ # one action per Block
19
+ │ │ │ │ ├── add-item.effect.block.ts # + instanceOptions (auto menu)
20
+ │ │ │ │ ├── remove-item.effect.block.ts
21
+ │ │ │ │ ├── clear-cart.method.block.ts
22
+ │ │ │ │ ├── assert-hello.method.block.ts # + stubs + YAP slide
23
+ │ │ │ │ └── assert-item-added.method.block.ts
24
+ │ │ │ └── docs/ # a second page, same shape
25
+ │ │ └── (external)/mailpit/ # a different origin (mail catcher)
26
+ │ ├── states/ # Checkpoint types + mem keys
27
+ │ └── flows/ # example / shop / mail-verify
28
+ ├── scripts/ # local fixture server
29
+ └── tests/example.spec.ts
43
30
  ```
44
31
 
45
- ## Features covered
32
+ Underscore-prefixed files (`_nav`, `_page`, `_sel`, `_methods/`) are the fixed names every
33
+ page folder uses, so any agent or teammate knows where to look without asking.
46
34
 
47
- | Feature | Where |
48
- |---------|--------|
49
- | Nav (`defineNavBlock`) | `nav-home.block.ts` |
50
- | Page hub (`definePageBlock` + `methods`) | `home.page.block.ts` |
51
- | Method (`defineMethodBlock`) | `assert-hello`, `clear-cart` |
52
- | Effect + `instanceOptions` (auto menus) | `add-item`, `remove-item` |
53
- | Mem (`keyGroup`) | `demo.mem-keys.ts` |
54
- | `stubBefore` / `stubAfter` / `stubOnError` | all instruction blocks |
55
- | Flow fixtures + title | `example.flow.ts`, `shop.flow.ts` |
56
- | YAP slides | `assert-hello` |
57
- | `withSessionReset` | `shop.flow.ts` |
58
- | `waygraph auto` / `auto --cli` | `npm run auto` |
59
- | `demo` / `run` / `list` / `check` / `graph` | `package.json` scripts |
35
+ ## What each piece is for
60
36
 
61
- ## Auto
37
+ | Want to... | Look at |
38
+ |---|---|
39
+ | Add a page | copy a folder under `src/map/`, keep the `_nav` / `_page` / `_sel` names |
40
+ | Add an action on a page | one file in that page's `_methods/` |
41
+ | Verify a state (button disabled, error shown) | `defineAssertBlock` + `Trait.disabled` / `Trait.enabled` |
42
+ | Wire steps together | `src/flows/*.flow.ts` |
43
+ | Give a flow fake data | `registerMemStub(key, fake)` + `withMemStub(flow)` (docs: docs/REFERENCE.md, "memStub") |
44
+ | Explore by hand | `npm run auto` (headed) or `npm run auto:cli` |
45
+ | Check your work | `npm run check`, `npm run graph`, `waygraph map` |
62
46
 
63
- ```bash
64
- npm run auto # headed explore - pick Add Alpha / Add Beta from live DOM
65
- npm run auto:cli # same menus in the terminal
66
- ```
67
-
68
- After `nav-home`, Effect blocks expose one menu row per visible Add/Remove button.
69
-
70
- ## Two authoring modes
71
-
72
- `src/blocks/` (`demo-web/`, `demo-external/`) is **manual mode** - freeform, developer-chosen
73
- file layout, the default this whole scaffold otherwise uses.
74
-
75
- `src/routes/` is the **Waygraph Map** convention - `(group)/<page-slug>/page.block.ts` +
76
- `nav.block.ts` + `methods/*.block.ts`, one Checkpoint per folder, `(group)` purely
77
- organizational (parens, Next.js route-group style - never part of the Checkpoint tag). Same
78
- Block helpers, same execution - only where files live and what they're named changes. A
79
- project can adopt it folder by folder; `routes-demo.flow.ts` proves both modes compose in one
80
- flow (`nav-home` from `blocks/`, `nav-docs` from `routes/`). See the main package's own
81
- `README.md` "Waygraph Map" section and `openspec/changes/waygraph-map/`.
47
+ `waygraph map` fails if a folder path stops matching the real URL it claims to represent.
48
+ Full convention: https://deviate-dv8.github.io/waygraph/consumer.html
package/templates/scaffold/src/map/(app_base)/docs/_nav.block.ts CHANGED
@@ -7,7 +7,7 @@ import { DocsSel, DOCS_URL } from "./_sel.js";
7
7
  * Route: (app_base)/docs/
8
8
  *
9
9
  * Same origin as home/ (same fixture server, different HTML file) - lives
10
- * under (app_base), not (external). See README.md "Waygraph Map" and
10
+ * under (app_base), not (external). See docs/REFERENCE.md "Waygraph Map" and
11
11
  * openspec/changes/waygraph-map. `(app_base)` is purely organizational
12
12
  * (Next.js route-group style) - never part of the Checkpoint tag.
13
13
  */
package/templates/scaffold/src/map/(external)/mailpit/_methods/assert-email-content.method.block.ts CHANGED
@@ -27,7 +27,7 @@ const bodyContainsExpectedText: Trait = {
27
27
  * "Does the email actually say what it's supposed to" - not just "does a
28
28
  * link exist somewhere in it." Reads the message body straight out of the
29
29
  * preview iframe (the top-level page's own `Trait.text`/`Trait.visible`
30
- * can't see inside an iframe at all - see README's "Mail adapters" section).
30
+ * can't see inside an iframe at all - see docs/REFERENCE.md "Mail adapters" section).
31
31
  * Self-loop on MailpitMessageOpen - no state change, verify only.
32
32
  *
33
33
  * Deliberately named for what it does, not for one scenario: the expected
package/templates/skills/waygraph-pilot.skill.md CHANGED
@@ -134,7 +134,7 @@ waygraph auto highlight <sessionId> '{"clear":true}'
134
134
  Supported fields (demo parity):
135
135
  - `rings[]`: `selector`, `label`, `detail`, `tag`, `tone`, `size`, `weight`, `color`, `zoom`, `zoomOut`, `focus`
136
136
  - `todos` / `todoIndex` / `todoTitle` / `todoPos` (`right` default | `left`)
137
- - `todoUi`: `{ compact?, cap?, expandCap?, collision?, behindRing? }` — same dock UX as demo (defaults smart-on; see README "Todo dock UI")
137
+ - `todoUi`: `{ compact?, cap?, expandCap?, collision?, behindRing? }` — same dock UX as demo (defaults smart-on; see docs/REFERENCE.md "Todo dock UI")
138
138
  - `zoom` / `zoomSelector` / `zoomOut` - scroll + zoom badge (not CSS page scale)
139
139
  - `device`: `mobile` | `tablet` | `desktop` (Playwright viewport)
140
140
  - `holdMs`: ms to keep fixtures; `0` = until the next highlight / clear (default 30000)