waygraph 0.15.14 → 0.15.16

package/README.md

@@ -296,6 +296,13 @@ nothing is blocked, nothing fails to build. `waygraph check [project]` is the
 complementary whole-project sweep for contexts with no editor watching (CI, generated
 code, an autonomous agent authoring Blocks) - it warns, never fails the process.
 
+**`waygraph typecheck [project]`** runs `tsc --noEmit` then the same **bad-practice** scan
+(wildcard `Checkpoint<string>`, assert blocks missing type args, multi-`.fill()` Methods,
+fill+click in one Method). Practices warn only unless `tsc` fails; use `--no-practices` to
+skip the scan. Opt out per file: `// waygraph-ignore-practices` or
+`// waygraph-ignore: multi-input, combined-action`. Print full agent guidance:
+`waygraph --skill-convention`.
+
 ### Demo narration
 
 Automation rings are gray; authored stubs/slides can use
@@ -662,27 +669,52 @@ space is constrained to this project's own pre-verified Blocks (each with a real
 already checked) instead of freeform DOM/pixel guessing - narrower, but far more accurate and
 deterministic.
 
+### auto vs browser vs pilot
+
+| 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**. |
+| **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. Prefer the `browser`/`pilot` prefix when driving a
+detached session; `auto` remains for the interactive picker and legacy `--cli --detach`.
+
+**Session lifecycle is explicit** — list what's live before opening another:
+
 ```bash
-waygraph pilot start --non-headless
+waygraph browser                         # show browser subcommands
+waygraph browser sessions [--json]       # list live sessions; --json for agents
+waygraph browser start                   # always opens a new session
+waygraph browser stop <sessionId>        # shut one down
+waygraph browser stop --all              # shut every session for this project
+waygraph browser attach <sessionId>        # terminal picker on an existing session
+waygraph pilot attach <sessionId>          # graph + snapshot, no new browser
+```
+
+```bash
+waygraph pilot start
 # {"sessionId":"bb65d74c","socketPath":"...","headless":false,"graph":{...},"snapshot":{...}}
 ```
 
-One call gives an agent everything it needs to start: a real, already-running Playwright
-session (the exact mechanism `auto --cli --detach` already provides), and the whole project's
-Block graph (`graph` - every Checkpoint/edge/description, not just what's reachable from the
-current position, so the agent can plan several steps ahead). From there, the agent drives the
-session itself, one pick at a time, using the session-control commands that already existed
-before Pilot did:
+`pilot start` is one round trip for agents that need the whole graph immediately. For browser-only
+work (no graph payload), use `browser start`. `auto --cli --detach` still works but is the older
+explore entry point — prefer `browser start` for agent-driven sessions.
+
+From a live session, drive one pick at a time:
 
 ```bash
-waygraph auto status <sessionId>              # read the current menu (no side effects)
-waygraph auto send <sessionId> "<pick>"       # run one pick, get the resulting menu back
-waygraph auto dom <sessionId>                 # inspect the live DOM/ARIA tree
-waygraph auto trace <sessionId>               # read the Checkpoint/Block history so far
-waygraph auto reach <sessionId> <Checkpoint>  # run a whole multi-step route in one call
-waygraph auto resync <sessionId>              # force here to re-detect from the real page
+waygraph browser status <sessionId>              # read the current menu (no side effects)
+waygraph browser send <sessionId> "<pick>"       # run one pick, get the resulting menu back
+waygraph browser dom <sessionId>                 # inspect the live DOM/ARIA tree
+waygraph browser trace <sessionId>               # read the Checkpoint/Block history so far
+waygraph browser reach <sessionId> <Checkpoint>  # run a whole multi-step route in one call
+waygraph browser resync <sessionId>              # force here to re-detect from the real page
 ```
 
+(`auto …` and `pilot …` accept the same subcommands with the same `<sessionId>`.)
+
 Worked example (run for real against `examples/saucedemo`, no new execution code involved): an
 agent gets a plain request - "log me in and buy the backpack" - reads the graph and the starting
 `status`, reasons out login -> add-to-cart -> cart -> checkout info -> submit -> finish as the
@@ -1007,6 +1039,14 @@ immediately - see "Waygraph Pilot" above for the full picture.
 when no Block covers that action yet, and `auto reload <sessionId>` picks up a Block just
 written to disk without restarting the session - see "Blind Pilot" above.
 
+**`waygraph test [...args]`** is a thin wrapper around the project's own `@playwright/test`
+suite - it forwards to the local `node_modules/.bin/playwright` (falling back to
+`npx playwright` if the project hasn't installed it locally yet), so `waygraph test` behaves
+exactly like `playwright test`, and anything after it (`--grep`, a spec path, `--headed`, …)
+passes straight through. `waygraph test ui` (or `waygraph test --ui`) launches Playwright's
+interactive UI Mode the same way. Scaffolded projects (`waygraph init`/`create-waygraph`)
+wire this up as `npm test` / `npm run test:ui`.
+
 Flows are files (0.10.5+):
 
 | Want | Command |
@@ -1023,22 +1063,31 @@ Flows are files (0.10.5+):
 | Ad-hoc Blocks | `waygraph run --blocks "login then nav-cart" --data '{...}'` |
 | Headed execute | `waygraph run --blocks shopFlow --non-headless --video` |
 | Explore | `waygraph auto` / `waygraph auto --cli` |
+| Browser command reference | `waygraph browser` |
+| List live browser sessions | `waygraph browser sessions [--json]` |
+| Open a new persistent browser | `waygraph browser start` (headful, about:blank by default) |
+| Stop a browser session | `waygraph browser stop <sessionId>` / `stop --all` |
+| Pilot bootstrap (browser + graph + snapshot) | `waygraph pilot start` |
+| Attach to existing session (graph only) | `waygraph pilot attach <sessionId>` |
 | Path-find | `waygraph auto --blocks LoginPage OrderComplete` |
-| Run `--cli` as a background session | `waygraph auto --cli --detach` -> `{sessionId, socketPath}` |
-| Drive a detached session (no TTY) | `waygraph auto send <sessionId> "<pick>"` -> JSON state |
-| Read a detached session's state | `waygraph auto status <sessionId>` (no side effects) |
-| Reattach a terminal to a detached session | `waygraph auto attach <sessionId>` |
+| Run `--cli` as a background session (legacy) | `waygraph auto --cli --detach` -> `{sessionId, socketPath}` |
+| Drive a detached session (no TTY) | `waygraph browser send <sessionId> "<pick>"` -> JSON state |
+| Read a detached session's state | `waygraph browser status <sessionId>` (no side effects) |
+| Reattach a terminal to a detached session | `waygraph browser attach <sessionId>` |
 | Read the live page (aria, small/default) | `waygraph auto dom <sessionId>` |
 | Read the live page (raw DOM, bounded) | `waygraph auto dom <sessionId> --mode full` |
 | Scope either to one element | `waygraph auto dom <sessionId> --selector ".inventory_list"` |
 | Detached session with a real visible browser | `waygraph auto --cli --detach --non-headless` |
 | Read the session's Checkpoint/Block history | `waygraph auto trace <sessionId>` |
 | Whole-project nav-escape + inline-selector + orphan sweep | `waygraph check [project]` |
+| `tsc --noEmit` + bad-practice warnings | `waygraph typecheck [project]` (`--no-practices` to skip scan) |
 | Waygraph Map enforcement (verbatim url-vs-folder, exits 1 on a violation) | `waygraph map [project]` |
 | Graph crawl | `waygraph traverse [project] --parallel N --min-edge-coverage 80%` |
 | Coding-agent defs | `waygraph agent-dive --loop claude` |
 | Print packaged skills | `waygraph --skill` / `--skill-pilot` / `--skill-pilot-blind` / `--skill-convention` |
 | One-shot temp-dir demo | `waygraph try demo` / `waygraph try auto` / `waygraph try auto:cli` |
+| Run the project's `@playwright/test` suite | `waygraph test` |
+| Same suite, Playwright's interactive UI Mode | `waygraph test ui` (or `--ui`) |
 
 `--blocks` / positional accepts a Flow export, a `.flow.ts` path, or `"a then b"`.
 `auto <file.flow.ts>` **runs** that flow (same as `run`); bare `auto` still explores.
@@ -1167,8 +1216,9 @@ it out from under you.
 git clone git@github.com:deviate-dv8/waygraph.git
 cd waygraph
 npm install
-npm run typecheck   # tsc --noEmit
-npm run test        # playwright test
+npm run typecheck   # waygraph typecheck . (tsc --noEmit + practice warnings)
+npm run test        # node --test tests/unit + playwright test
+npm run test:ui     # playwright test --ui
 npm run build       # tsc -p tsconfig.build.json, emits dist/
 ```
 

package/dist/cli.d.ts

@@ -6,6 +6,7 @@
  *   auto   Explore picker; `.flow.ts` / `--blocks From To` = run that path
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--mini` `--ff-expand` `--ff-disabled`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
+ *   test   Runs the project's own @playwright/test suite; `test ui` / `--ui` = UI Mode
  *
  * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
  * Skills: --skill / --skill-pilot / --skill-pilot-blind / --skill-convention

package/dist/cli.js

@@ -6,6 +6,7 @@
  *   auto   Explore picker; `.flow.ts` / `--blocks From To` = run that path
  *   demo   Watch (step overlay); `--blocks` `--data` `--auto-next` `--fast` `--full` `--mini` `--ff-expand` `--ff-disabled`
  *   run    Execute; `--blocks` `--data` `--non-headless` `--video`
+ *   test   Runs the project's own @playwright/test suite; `test ui` / `--ui` = UI Mode
  *
  * Also: list / nav / validate / check / graph / init / agent-dive / traverse / try
  * Skills: --skill / --skill-pilot / --skill-pilot-blind / --skill-convention
@@ -7186,6 +7187,24 @@ async function expandSpecFlowFiles(projectDir, spec) {
 }
 const args = process.argv.slice(2);
 const command = args[0];
+function printBrowserUsage() {
+    console.log(`waygraph browser — persistent Playwright sessions (headful by default)
+
+  waygraph browser start [--inject preset|path] [--goto <url>] [--blank] [--headless] [--cli] [project]
+                           Open a new session (about:blank by default)
+  waygraph browser sessions [--json] [project]
+                           List live sessions for a project
+  waygraph browser stop <sessionId|--all> [project]
+  waygraph browser attach <sessionId>       Terminal picker on a live session
+
+  waygraph browser status <sessionId>       Current menu (no side effects)
+  waygraph browser send <sessionId> "<pick>"
+  waygraph browser reach <sessionId> <Checkpoint>
+  waygraph browser dom|trace|console|storage|highlight <sessionId> …
+  waygraph browser click|type|press|goto|upload|reload|resync <sessionId> …
+
+  auto send|status|… and pilot send|status|… use the same session ids.`);
+}
 function printBrowserSessionsList(sessions, projectDir) {
     if (sessions.length === 0) {
         console.log(`No live browser sessions for ${projectDir}.`);
@@ -7278,7 +7297,7 @@ Primary (less is more):
                                            label,tone?,size?,weight?}], todos[], todoIndex?,
                                            todoTitle?, holdMs? (0=until next), clear:true.
                                            Missing selectors listed in response, not fatal.
-  waygraph browser                         List live browser sessions for cwd
+  waygraph browser                         Show browser subcommands
   waygraph browser start                   Open a new session (headful by default, about:blank)
                  --inject preset|path            Merge an external Block library (e.g. saucedemo)
                  --goto <url>              Navigate on start (disables blank page)
@@ -7318,6 +7337,11 @@ Primary (less is more):
                  --video-viewport WxH       Recording size (default run: 1280x720)
                  --ff-expand               Same as demo (expand FFCompose inners)
                  --ff-disabled             Same as demo (dispute: expand FF)
+  waygraph test                            Runs the project's @playwright/test suite (cwd) -
+                                           thin wrapper: forwards to the local playwright
+                                           binary (or npx playwright as a fallback)
+                 test ui  /  test --ui     Playwright UI Mode (interactive, watch + trace)
+                 <any other args>          Forwarded verbatim (--grep, a spec path, --headed, …)
 
 Also:
   waygraph list | nav | validate | check | typecheck | graph | init <name>
@@ -7449,6 +7473,21 @@ async function main() {
             await runChain(proj, spec);
             break;
         }
+        case "test": {
+            const rest = args.slice(1);
+            const wantsUi = rest[0] === "ui" || rest.includes("--ui");
+            const forwarded = rest[0] === "ui" ? rest.slice(1) : rest;
+            const pwArgs = wantsUi && !forwarded.includes("--ui")
+                ? ["test", "--ui", ...forwarded]
+                : ["test", ...forwarded];
+            const proj = process.cwd();
+            const localPlaywrightBin = join(proj, "node_modules", ".bin", "playwright");
+            const code = existsSync(localPlaywrightBin)
+                ? await runInherited(localPlaywrightBin, pwArgs, proj)
+                : await runInherited("npx", ["--yes", "playwright", ...pwArgs], proj);
+            process.exitCode = code;
+            break;
+        }
         case "init": {
             initCommand(args[1] ?? "");
             break;
@@ -7784,8 +7823,7 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                     break;
                 }
                 if (!sub) {
-                    const proj = resolve(process.cwd());
-                    printBrowserSessionsList(listBrowserSessions(proj), proj);
+                    printBrowserUsage();
                     break;
                 }
                 if (sub === "start" || sub.startsWith("-")) {
@@ -7839,12 +7877,8 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                     sub !== "reach" &&
                     sub !== "resync" &&
                     sub !== "highlight") {
-                    console.error("waygraph browser: usage:\n" +
-                        "  waygraph browser                       List live sessions (cwd)\n" +
-                        "  waygraph browser start [--inject preset|path] [--goto <url>] [--blank] [--headless] [--cli] [project]\n" +
-                        "  waygraph browser sessions [--json] [project]\n" +
-                        "  waygraph browser stop <sessionId|--all> [project]\n" +
-                        "  waygraph browser send|status|attach|highlight|dom|… <sessionId> …  (same as auto)");
+                    console.error("waygraph browser: unknown subcommand — run `waygraph browser` for usage");
+                    printBrowserUsage();
                     process.exit(1);
                 }
             }

package/examples/saucedemo/package.json

@@ -6,7 +6,8 @@
   "description": "Full Sauce Demo (saucedemo.com) example - Effect / MemNav / waygraph auto.",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "playwright test",
+    "test": "waygraph test",
+    "test:ui": "waygraph test ui",
     "flows": "waygraph list",
     "demo": "waygraph demo --blocks \"loginFlow then shopFlow\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",
     "demo:step": "waygraph demo --blocks \"loginFlow then shopFlow\" --title \"Shop demo\" --data \"{\\\"saucedemo.credentials\\\":{\\\"username\\\":\\\"standard_user\\\",\\\"password\\\":\\\"secret_sauce\\\"},\\\"saucedemo.selectedItem\\\":{\\\"id\\\":\\\"sauce-labs-backpack\\\",\\\"name\\\":\\\"Sauce Labs Backpack\\\"}}\"",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.14",
+  "version": "0.15.16",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
@@ -36,7 +36,9 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "node bin/waygraph typecheck .",
-    "test": "playwright test",
+    "test": "npm run test:unit && playwright test",
+    "test:ui": "playwright test --ui",
+    "test:unit": "node --import tsx/esm --test tests/unit/*.spec.ts",
     "docs:preview": "python3 -m http.server 4173 --directory docs",
     "example:saucedemo:install": "npm --prefix examples/saucedemo install",
     "example:saucedemo:test": "npm --prefix examples/saucedemo test",

package/templates/quickstart/package.json

@@ -4,7 +4,8 @@
   "type": "module",
   "description": "Self-contained saucedemo quickstart (copied into a temp dir by `waygraph try demo`).",
   "scripts": {
-    "test": "playwright test",
+    "test": "waygraph test",
+    "test:ui": "waygraph test ui",
     "typecheck": "tsc --noEmit",
     "check": "waygraph check",
     "auto": "waygraph auto",

package/templates/scaffold/package.json

@@ -5,7 +5,8 @@
   "type": "module",
   "scripts": {
     "typecheck": "waygraph typecheck .",
-    "test": "playwright test",
+    "test": "waygraph test",
+    "test:ui": "waygraph test ui",
     "fixture": "node scripts/fixture-server.mjs",
     "list": "waygraph list",
     "check": "waygraph check",

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

@@ -4,16 +4,29 @@ description: Cold-start a waygraph project against a real site with zero existin
 ---
 
 Blind Pilot is the same session mechanism as `waygraph-pilot`, minus the requirement of any
-pre-existing Blocks. `auto --cli --detach` tolerates a project with zero `.block.ts` files -
-`auto click/type/goto/press/upload` act on the real page before any Block exists to cover it.
+pre-existing Blocks. A project with zero `.block.ts` files still gets a live session —
+`browser click/type/goto/press/upload` act on the real page before any Block exists to cover it.
 This package generates **no Block content for you** - you write real `.block.ts`/`*Sel`/
 mem-key files by hand as you go. That's the whole point: turn one-off exploration into
 permanent, reusable, typed coverage instead of leaving nothing behind.
 
+## Session lifecycle (list first)
+
+```
+waygraph browser                         # show browser subcommands
+waygraph browser sessions                # list live sessions (cwd)
+waygraph browser start [--goto <url>]    # new headful session (about:blank by default)
+waygraph browser attach <sessionId>      # terminal picker on existing session
+waygraph browser stop <sessionId|--all>  # shut down when done
+```
+
+`browser start` always opens a **new** session. Check `browser sessions` before starting another.
+Session control works as `browser …` or `auto …` with the same `<sessionId>`.
+
 ## The real loop
 
-1. `auto goto <sessionId> <url>` / `auto click` / `auto type` to explore the real page.
-2. `auto dom <sessionId> --mode full --selector <sel>` to read real structure before writing
+1. `browser goto <sessionId> <url>` / `browser click` / `browser type` to explore the real page.
+2. `browser dom <sessionId> --mode full --selector <sel>` to read real structure before writing
    a selector - never guess a selector, confirm it against the real DOM first. `--mode aria`
    is faster for a first pass but can show stale/hidden responsive-duplicate content in some
    real apps (confirmed live: a hidden `lg:hidden` panel's heading text showed up in an aria
@@ -24,19 +37,20 @@ permanent, reusable, typed coverage instead of leaving nothing behind.
    then `Nav`/`Page`/`Method` Blocks, following `templates/scaffold`'s own folder convention
    (`(group)/<page-slug>/page.block.ts` + `nav.block.ts` + `methods/*.block.ts` + one `*.sel.ts`)
    so the result becomes part of the Waygraph Map, not a scattered one-off file.
-4. `auto reload <sessionId>` to pick up the newly-written Block(s) without restarting.
-5. Optionally narrate for a headful watcher: `auto highlight <sessionId> '{"rings":[...],"todos":[...]}'`
-6. Run the new Block for real via `auto send` - prove it works before moving to the next
+4. `browser reload <sessionId>` to pick up the newly-written Block(s) without restarting.
+5. Optionally narrate for a headful watcher: `browser highlight <sessionId> '{"rings":[...],"todos":[...]}'`
+   Raw ops show **`Running (no Block): …`** in the bottom-left toast; Block runs show **`Running (Block): …`**.
+6. Run the new Block for real via `browser send` - prove it works before moving to the next
    pattern, exactly like any other real Block.
-6. Ask the user a clarifying question only when something genuinely can't be resolved from
+7. Ask the user a clarifying question only when something genuinely can't be resolved from
    the DOM alone (is this instance local or published? does a downstream integration exist?)
-   - don't ask about things `auto dom` can just answer.
+   - don't ask about things `browser dom` can just answer.
 
 ## Real gotchas specific to cold-start authoring
 
 - **`discoverGraph`'s per-file import errors are mostly silent.** A malformed newly-written
   Block file can simply vanish from the graph with no error printed anywhere obvious - if a
-  Block you just wrote doesn't show up after `auto reload`, check `waygraph graph`'s own
+  Block you just wrote doesn't show up after `browser reload`, check `waygraph graph`'s own
   `skipped` list and the file's syntax directly, don't assume it just needs more time.
 - **`defineAssertBlock` needs no `<In, Out>` generic to type-check** (`checkpoint: "X"` alone
   is enough for TypeScript to infer it) - but older/naive static-graph discovery logic may
@@ -47,9 +61,9 @@ permanent, reusable, typed coverage instead of leaving nothing behind.
 - **A `<p>`/text-based selector often needs scoping**, not just a class name - a sibling
   "chat list item" and "message preview" frequently share the exact same CSS classes in real
   apps, distinguished only by DOM position (first vs second child of a specific wrapper).
-  Confirm via `auto dom --mode full` before assuming a class alone is unique enough.
+  Confirm via `browser dom --mode full` before assuming a class alone is unique enough.
 - **Confirm a selector count, not just its first match**, when building anything the menu
-  will expand into multiple live rows (an `instanceOptions`-driven Block) - `auto dom`'s
+  will expand into multiple live rows (an `instanceOptions`-driven Block) - `browser dom`'s
   default read can silently show only one match even when several exist; check the real
   page count (e.g. via a scoped debug script) before assuming a plain `.first()` is safe
   long-term. A `.first()`-shaped Block is a legitimate STARTING point for a page that only
@@ -57,6 +71,7 @@ permanent, reusable, typed coverage instead of leaving nothing behind.
   `defineEffectBlock` (see the `waygraph-pilot` skill and
   `examples/saucedemo/.../nav-item-detail.block.ts` for the real pattern) once a second real
   row genuinely exists to pick between, not before.
-- **Prefer the real Pilot overlay over ad hoc status output** when driving a
-  `--non-headless` session someone might be watching - it auto-updates on every menu build,
-  point a human at the badge/panel instead of re-inventing status reporting.
+- **Prefer the real Pilot overlay over ad hoc status output** when driving a headful session
+  someone might be watching - badge/panel on `about:blank` and after every navigation; raw
+  ops toast **`Running (no Block): …`**. Point a human at the badge instead of re-inventing
+  status reporting.

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

@@ -14,7 +14,7 @@ reading each `auto status`/`auto send` response.
 | 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. |
+| **browser** | `waygraph browser start` | New persistent Playwright session — **headful by default**, **about:blank by default**. `waygraph browser` prints subcommands; `browser sessions` lists live ones. |
 | **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: