waygraph 0.15.14 → 0.15.15

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
@@ -1023,17 +1055,24 @@ 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` |
@@ -1167,7 +1206,7 @@ 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 typecheck   # waygraph typecheck . (tsc --noEmit + practice warnings)
 npm run test        # playwright test
 npm run build       # tsc -p tsconfig.build.json, emits dist/
 ```

package/dist/cli.js

@@ -7186,6 +7186,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 +7296,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)
@@ -7784,8 +7802,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 +7856,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/package.json

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

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: