waygraph 0.15.43 → 0.15.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.43",
+  "version": "0.15.44",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

package/templates/scaffold/scripts/README.md

@@ -0,0 +1,13 @@
+# `scripts/`
+
+- `fixture-server.mjs` - serves the offline `.html` fixture pages under `src/map/` on
+  `127.0.0.1:4177` (override with `WAYGRAPH_FIXTURE_PORT`/`WAYGRAPH_FIXTURE_HOST`). This is
+  what makes `npm test` pass with no network and no real app running.
+- `with-fixture.mjs` - starts `fixture-server.mjs`, runs whatever command you give it
+  (`waygraph auto`, `waygraph demo --blocks ...`), then tears the server down when that command
+  exits. Every `npm run demo*`/`auto*` script in `package.json` goes through this wrapper -
+  don't run `waygraph demo`/`auto` directly against this scaffold's own fixture pages without it.
+
+Pointing this scaffold at a real app instead of the offline fixtures: change `_nav.block.ts`'s
+`url`/`homeOrigin` to the real one and drop `with-fixture.mjs` from the scripts that no longer
+need it.

package/templates/scaffold/src/flows/README.md

@@ -0,0 +1,18 @@
+# `src/flows/`
+
+A `*.flow.ts` composes Blocks from `src/map/` into a runnable path - `waygraph run`/`demo`/`test`
+all point at an export here by name (`waygraph run --blocks shopFlow`).
+
+- Prefer `new Engine().map()...end()` (the Map builder: `.gotoPage()`/`.method()`/`.assert()`/
+  `.branch()`) over hand-composing raw Blocks - it checks each step's Block kind at runtime and
+  the Checkpoint chain at compile time, so a wrong step is a build/test failure, not a
+  mid-run surprise.
+- `withTitle`/`withHighlightFixtures`/`withSessionReset`/etc. are non-destructive wrappers -
+  `someFlow.withTitle("...")` doesn't mutate `someFlow`, it returns a new one. Compose them
+  around the finished `.end()` result, not inside the Map chain itself.
+- One flow, one scenario. A flow that needs a genuinely different starting session
+  (re-entering the login page mid-chain) wraps that segment in `withSessionReset`, rather than
+  hand-clearing cookies inside a Block.
+
+New flow → new file here, named for the scenario (`checkout.flow.ts`), not for the Blocks it
+happens to use.

package/templates/scaffold/src/map/README.md

@@ -0,0 +1,31 @@
+# `src/map/`
+
+The Waygraph Map: one folder per page, mirroring your app's real URLs. See the root
+[`STRUCTURE.md`](../../STRUCTURE.md) for the full picture; this file is the local, one-screen
+version for whoever is inside this directory.
+
+## The fixed names, every page folder
+
+| File | Kind | Job |
+|---|---|---|
+| `_nav.block.ts` | Nav | How to get here - `url` (goto) or `click` (in-app link). One per page. |
+| `_page.block.ts` | Page | "You have arrived" - the hub other pages navigate to. One per page. |
+| `_sel.ts` | data | Every selector this page's Blocks use, in one object. Never inline a selector when this file exists - `waygraph check` warns on it. |
+| `_methods/` | folder | One file per action, one action per file (`add-item.effect.block.ts`, not one file with three `.fill()` calls). |
+
+Never rename these, never combine them into one file, never add a `_selectors/` folder in
+place of `_sel.ts` - one page, one selector file, same as every other page in the Map.
+
+## `(group)` folders
+
+A parenthesized folder (`(app_base)`, `(external)`) is organizational only - like a Next.js
+route group. It groups pages by origin/base URL and never appears in a Checkpoint name or a
+real URL. `waygraph map`/`waygraph check` fail loudly if a page folder's real URL stops
+matching its own name - that's the point of this layout: drift becomes a build failure, not a
+silent surprise months later.
+
+## Adding a page
+
+Copy an existing page folder, keep the four fixed names, update `_nav`/`_page`/`_sel` for the
+new page, then add `_methods/` files for its actions. Don't invent a new folder shape - every
+page in this Map looks the same on purpose.

package/templates/scaffold/src/states/README.md

@@ -0,0 +1,15 @@
+# `src/states/`
+
+Checkpoint types and Mem keys - the typed vocabulary every Block in `src/map/` is written
+against. Nothing here drives the browser; this is pure data shape.
+
+- `*.states.ts` - `type X = Checkpoint<"X">` declarations. One per real app state
+  (`LoginPage`, `LoggedIn`), never `Checkpoint<string>` (a wildcard - `waygraph check` warns
+  on it; a Block should say exactly which states it moves between).
+- `*.mem-keys.ts` - `key<T>("...")` / `keyGroup<T>("...")` declarations. A Mem key stores a
+  *value* a Block needs (credentials, a selected row's id) - never a selector (those live in
+  `_sel.ts` next to the page) and never something a Block could instead read straight off the
+  live page.
+
+Add a new Checkpoint or Mem key here before writing the Block that needs it - Blocks import
+from this directory, this directory never imports from `src/map/`.

package/templates/scaffold/tests/README.md

@@ -0,0 +1,10 @@
+# `tests/`
+
+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`.
+
+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`
+checks; the spec is proving the flow itself still works end to end, not re-deriving selectors.