waygraph 0.15.10 → 0.15.14

package/examples/saucedemo/.waygraph-auto/5bd8fedf.log

@@ -0,0 +1,4 @@
+(node:1438409) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1438409) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/5dde8331.log

@@ -0,0 +1,4 @@
+(node:1424575) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1424575) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/7efa646f.log

@@ -0,0 +1,4 @@
+(node:1424626) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1424626) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/9cecb0c8.log

@@ -0,0 +1,4 @@
+(node:1434346) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1434346) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/cd0d5b50.log

@@ -0,0 +1,4 @@
+(node:1434366) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1434366) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/.waygraph-auto/ea2df316.log

@@ -0,0 +1,4 @@
+(node:1429810) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:1429810) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.10",
+  "version": "0.15.14",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
@@ -35,7 +35,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "node bin/waygraph typecheck .",
     "test": "playwright test",
     "docs:preview": "python3 -m http.server 4173 --directory docs",
     "example:saucedemo:install": "npm --prefix examples/saucedemo install",

package/templates/scaffold/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "waygraph typecheck .",
     "test": "playwright test",
     "fixture": "node scripts/fixture-server.mjs",
     "list": "waygraph list",

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

@@ -24,6 +24,14 @@ against a live site, use `--skill-pilot-blind`.
    an explicit type argument when it sits between two specifically-typed Blocks in a Flow.
 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.
+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.
+   Same for `defineAssertBlock({…})` without an explicit type arg — use
+   `defineAssertBlock<YourCheckpoint>({…})`.
+7. **One input/action per Method Block.** No block that `.fill()`s two fields or `.fill()` + `.click()` in one
+   `act()` — split like saucedemo login (`fill-username`, `fill-password`, `submit-login`). Opt out per file:
+   `// waygraph-ignore: multi-input` or `// waygraph-ignore-practices`.
 
 ## Block kinds (file convention)
 
@@ -84,7 +92,9 @@ the site's `*-web/` tree. Browser-driven (DOM / iframe Traits), not the catcher'
 ## Verify before you call it done
 
 ```bash
-npx waygraph check .          # orphans + nav-escape + inline-selector warnings
+npx waygraph check .          # orphans + nav-escape + inline-selector + bad-practice warnings
+npx waygraph typecheck .      # tsc --noEmit + bad-practice warnings (npm run typecheck)
+npx waygraph check --no-practices .   # skip bad-practice scan only
 npx waygraph map .            # exit 1 if src/map/ folder path != real static url
 npx waygraph validate .       # every .flow.ts loads
 npx waygraph graph .          # nodes/edges/skipped/orphans - counts should make sense

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

@@ -1,6 +1,6 @@
 ---
 name: waygraph-pilot
-description: Drive an existing waygraph Block graph as a real agent - use when a task needs to operate a web app that already has waygraph Blocks written for it (login, checkout, matching, chat, admin flows, etc.), not when writing new Blocks from scratch.
+description: Drive an existing waygraph Block graph as a real agent - use when a task needs to operate a web app that already has waygraph Blocks written for it (login, checkout, matching, chat, admin flows, etc.), not when writing new Blocks from scratch. Includes how to paint demo-parity fixture highlights in Pilot via `auto highlight` (pilot:watch / --non-headless).
 ---
 
 Waygraph Pilot is not a planner you call and get an answer from - `pilot start` only
@@ -9,10 +9,37 @@ the reasoning agent. Every multi-step decision (which Block to run next, when a
 `reach` vs `send`, when to fall back to raw primitives) is yours to make, turn by turn, by
 reading each `auto status`/`auto send` response.
 
+## auto vs browser vs pilot (do not conflate them)
+
+| Layer | Command | What it is |
+|-------|---------|------------|
+| **auto** | `waygraph auto` | Interactive explore (picker / `--cli` menu). **Not** a persistent agent browser. |
+| **browser** | `waygraph browser start` | New persistent Playwright session — **headful by default**, **about:blank by default**. `waygraph browser` lists live sessions only. |
+| **pilot** | `waygraph pilot start` | Bootstrap only: `browser start` + whole-project `graph` + starting `snapshot` in one JSON payload. Does not plan or act. |
+
+Session control (`send`, `status`, `highlight`, `dom`, …) works on **`auto`**, **`browser`**, and **`pilot`** — same socket, same session id:
+
+```
+waygraph browser send <sessionId> "<pick>"     # same as auto send / pilot send
+```
+
+**Session lifecycle — list first, then attach or start:**
+
+```
+waygraph browser sessions [project]          # what's live right now
+waygraph browser attach <sessionId>          # terminal picker on an existing session
+waygraph browser stop <sessionId|--all>      # shut one down when done
+waygraph pilot attach <sessionId>          # graph + snapshot for an existing session
+```
+
+`browser start` / `pilot start` always open a **new** session. Check `browser sessions` before starting another.
+
 ## Starting a session
 
 ```
 waygraph pilot start                      # bootstraps: {sessionId, socketPath, headless, graph, snapshot}
+waygraph browser start [--inject path] [--goto <url>] [--cli]  # new browser session; --cli opens terminal picker
+waygraph pilot start [--cli]              # --cli opens terminal picker after bootstrap JSON
 waygraph auto status <sessionId>          # re-read the live menu, no side effects
 waygraph auto send <sessionId> "<pick>"   # run exactly one Block (by menu index or name)
 waygraph auto reach <sessionId> <Checkpoint>  # path-find + run a whole route in one call
@@ -23,15 +50,83 @@ waygraph auto highlight <sessionId> '<json>'  # paint rings/todos on the live pa
 just what's reachable from here - use it to plan several steps ahead before you start
 sending picks.
 
-## Highlight fixtures (agent-sent narration)
+## Bad practices (`waygraph check` / `waygraph typecheck`)
+
+Run `waygraph typecheck .` (or `npm run typecheck`) — runs `tsc --noEmit` then bad-practice warnings.
+`waygraph check` includes the same practice scan plus nav/orphan/selector hygiene.
+Use `--no-practices` on either command to skip the practice scan.
+
+Patterns warned (does not fail `check`; fails `typecheck` only when `tsc` fails):
+
+- **`Checkpoint<string>` in Block generics** — e.g. `defineMethodBlock<Checkpoint<string>, …>` instead of a project Checkpoint type from `src/states/`.
+- **`defineAssertBlock({…})` without an explicit type arg** — use `defineAssertBlock<YourCheckpoint>({…})` so `defineFlow` typing stays honest.
+- **Multiple `.fill()` in one Method** — split into one Block per input (fill-username, fill-password, …).
+- **`.fill()` + `.click()` in one Method** — split fill and submit into separate Blocks.
+
+Opt out per file: `// waygraph-ignore-practices` or `// waygraph-ignore: multi-input, combined-action`.
+
+Fix these before adding more Blocks; wildcard Checkpoints hide real graph edges from the type checker.
+
+## Coverage gaps on the live page (`auto console`)
+
+After `auto status` / `auto send`, read `waygraph auto console <sessionId>` — the session warns once per page load about:
+
+- **Unmapped hrefs** — same-origin `<a href>` paths with no `defineNavBlock` URL.
+- **Unmapped buttons** — visible `button` / `[role=button]` / submit inputs with no Method or NavClick selector in the Block library.
 
-Block `stubBefore` / `withHighlightFixtures` only paint in `waygraph demo`. In Pilot they
-land in `auto trace` as metadata but do **not** draw on the page. When a human is watching
-a headful session (or you want to narrate intent before a send), paint yourself with the
-same fixture surface:
+Example warnings:
 
 ```
+[waygraph] unmapped nav link on this page: /settings - no NavBlock covers this URL; add defineNavBlock
+[waygraph] unmapped button on this page: #save-draft - no Method/NavClick Block selector matches; consider defineMethodBlock or defineNavClickBlock
+```
+
+When you see these, author the missing Block — do not keep clicking raw primitives.
+
+## Session reachability (multi-pane / wrong cwd)
+
+Session ids are registered globally under `/tmp/waygraph-auto/` as well as `<project>/.waygraph-auto/`. If `auto status` says unreachable:
+
+1. Run `waygraph pilot sessions` from the project that started the browser — reuse the id, do not spawn again.
+2. Or `waygraph pilot attach <sessionId>` for graph + snapshot without a new browser.
+3. Stale metadata (crashed pid) is pruned automatically — start fresh only when the pid is actually gone.
+
+## Highlight fixtures (Pilot supports them — use `auto highlight`)
+
+**Yes, Pilot paints rings/todos/zoom/device on the live page.** That is what
+`waygraph auto highlight` is for. It works on headful `pilot start --non-headless`
+(consumer `pilot:watch`) and on headless sessions alike. Same fixture surface as
+`waygraph demo` (rings, todos, focus veil, zoom badge, device viewport) — proven in
+`tests/cli/auto-session.spec.ts` ("auto highlight: paints agent fixture rings…").
+
+**Do not claim Pilot "doesn't support fixture highlights."** That is wrong. The only
+thing that differs from demo is *who* triggers the paint:
+
+| Mode | Who paints | How |
+|------|------------|-----|
+| `waygraph demo` | Engine, automatically | Block `stubBefore` / `stubAfter` / `withHighlightFixtures` run each step |
+| Pilot / `auto --detach` | **You (the agent)** | `waygraph auto highlight <sessionId> '<json>'` before (or between) sends |
+
+Block-authored `stubBefore` / `withHighlightFixtures` still exist on Blocks in Pilot —
+they show up in `auto trace` as metadata — but they do **not** auto-draw. You re-express
+the same intent with `auto highlight` (copy selectors/labels from the Block stubs or from
+`auto dom`). Paint, then `auto send` the real Block. Clear when done.
+
+```
+# Headful watch session (rings visible to a human audience):
+waygraph pilot start --non-headless
+# → note sessionId from the bootstrap JSON
+
 waygraph auto highlight <sessionId> '{"rings":[{"selector":"#user-name","label":"Username","tone":"planned","focus":true},{"selector":"#password","label":"Password","tone":"info","detail":"secret"}],"todos":["Fill username","Fill password","Submit"],"todoIndex":0,"zoom":1.5,"holdMs":0}'
+waygraph auto send <sessionId> fill-username
+waygraph auto highlight <sessionId> '{"rings":[{"selector":"#password","label":"Password","tone":"planned","focus":true}],"todoIndex":1,"holdMs":0}'
+waygraph auto send <sessionId> fill-password
+waygraph auto highlight <sessionId> '{"clear":true}'
+```
+
+More shapes:
+
+```
 waygraph auto highlight <sessionId> '{"device":"mobile","rings":[{"selector":".inventory_item:last-child","label":"Last item","zoom":1.6,"focus":true}],"holdMs":30000}'
 waygraph auto highlight <sessionId> '{"clear":true}'
 ```
@@ -46,7 +141,7 @@ Supported fields (demo parity):
 - `clear`: true drops rings/todos/focus/zoom badge
 
 - `tone`: all demo tones - `planned` | `auto` | `info` | `warning` | `danger` | `success` | `orange` (aliases like `error`/`blue`/`green` work too)
-- Bottom-left toast shows `Highlighting: …` (same strip as `Running (Dom): …`)
+- Bottom-left toast shows `Highlighting: …` (same strip as `Running (no Block): …` for raw ops)
 - Missing selectors are listed in the JSON response (`missing`) - not a hard failure
 - Does not replace `auto send` - paint, then run the real Block
 
@@ -73,9 +168,8 @@ only ever be as good as the project's own Block coverage: if two Checkpoints sha
 and nothing in their `verify` arrays tells them apart, `resync` will confidently report the
 wrong one. This is a coverage gap in the project's Blocks, not a `resync` bug - if you hit
 one, fix the ambiguity (add a second, concrete `Trait.visible` condition that's only true in
-one of the two states - see `AppHomePageBlock`/`InPoolPageBlock` in a real veciro-waygraph
-example of exactly this: the same `/app` route, split by presence of a "Join Pool" vs
-"Leave pool" button).
+one of the two states — e.g. the same route with different visible buttons that distinguish
+pool membership vs home).
 
 ## Rule 3: mem is intent, Checkpoint is reality - never blur them