@pix3/cli 1.6.4 → 2.0.0-alpha.0

package/README.md

@@ -1,788 +1,722 @@
-# @pix3/cli
-
-Command line for Pix3:
-
-```text
-pix3 new [<recipe> [dir]] [--name <n>]        create a project from a recipe/template
-pix3 mcp --workspace [--project <dir>]        stdio MCP server for your agent, through `pix3 serve`
-pix3 mcp [--project <dir>] [--agent <name>]   phase-0 prototype: stdio MCP + FSA link server
-pix3 setup [claude|codex]                     print how to register the MCP server
-pix3 serve [--project <dir>] [--port <n>] [--new-token]
-                                              serve a project folder to a Pix3 editor
-pix3 validate [paths…] [--json]               strict scene check
-pix3 check [--json] [--no-hydrate] [--offline] [--project <dir>]
-                                              validate + tsc over the scripts + merge-log + versions
-pix3 smoke [scene] [--changed|--all] [--frames N] [--timeout S] [--json] [--project <dir>]
-                                              run the game headless in Node, report what threw
-pix3 tree [scene] [--depth N] [--types A,B] [--props] [--json] [--project <dir>]
-                                              scene outline, one line per node; no scene = overview
-pix3 kit [--update] [--project <dir>]         install / update the agent kit in a project
-pix3 read <path>                              print a file and ack its bytes' sha256
-pix3 ack <path> --sha256 <hash>               ack a version you read (hash of raw bytes)
-pix3 sfx <preset|"text"> [--out <f.wav>] [--seed <n>] [--json]
-                                              synthesize a sound effect to WAV, offline
-```
-
-`new`, `kit`, `mcp`, `serve`, `read`/`ack` load neither TypeScript nor the kit generator: the kit
-and the runtime types are prebuilt into the package (`kit/`, `dist/runtime-types.json`, at
-`prepack`).
-`tree` reads YAML only; `smoke` and `tree --props` load the runtime from a bundle prebuilt at
-`prepack` (`dist/smoke/prebuilt/`, like validate's), so none of this slows `new` / `mcp` / `serve`.
-
-`read` / `ack` append `{ path, sha256, at }` to `.pix3/ack.json`. The editor, merging the next
-version of that file you write, lifts the protection of the manual edits that version contained
-and removes the ack (one-shot); see `docs/pix3-specification.md` → "Co-authoring mode".
-
-## `pix3 check` — everything an agent should run after a batch of edits
-
-`pix3 check` = `pix3 validate` (both levels) + a TypeScript type-check of the project's scripts +
-the newest `.pix3/merge-log.jsonl` entries + a version check. Exit 0 = no errors (warnings
-allowed), 1 = at least one error, 2 = could not run. Diagnostics are one list, validate's plus:
-
-| Code | Severity | When |
-| --- | --- | --- |
-| `E_TYPE` | error | a tsc diagnostic (`message` starts with `TS<code>:`; `file`, `line`) |
-| `E_TYPECHECK_UNAVAILABLE` | error | TypeScript could not be found or installed (`fix` = the command to run) |
-| `W_RUNTIME_VERSION_MISMATCH` | warning | own `tsconfig.json`, and `node_modules/@pix3/runtime` is not this CLI's version |
-| `W_RUNTIME_NOT_INSTALLED` | warning | own `tsconfig.json`, and no `node_modules/@pix3/runtime` |
-| `W_KIT_OUTDATED` | warning | `metadata.agentKit.version` is not this CLI's version (`pix3 kit --update`) |
-
-`--json`:
-
-```text
-{
-  "ok": true, "projectRoot": "…", "errorCount": 0, "warningCount": 2,
-  "level2": { "state": "ran", "filesHydrated": 5, "filesSkipped": 0, "filesSkippedForScripts?": 0 },
-  "files": [{ "file": "scenes/main.pix3scene", "sha256": "<hex of the raw bytes>" }],
-  "diagnostics": [{ "severity", "code", "file", "line?", "nodeId?", "path?", "message", "fix?" }],
-  "notes": [],
-  "typecheck": { "ok": true, "errors": 0, "tsconfig": ".pix3/tsconfig.check.json", "mode": "pix3-types",
-                 "files": 5, "typescript": { "version": "5.8.3", "source": "cache" } },
-  "mergeLog": [{ "at", "file", "event", "…": "the newest 10 lines of .pix3/merge-log.jsonl" }],
-  "kit": { "version": "1.6.0", "cliVersion": "1.6.0", "upToDate": true },
-  "timingsMs": { "validate": 190, "typecheck": 1180, "total": 1380 }
-}
-```
-
-`files` holds every scene validated and every script type-checked, hashed over the **raw bytes** —
-the hashes `expect` (barrier tools) and `pix3 ack --sha256` take. `typecheck.errors` counts the
-`E_TYPE` / `E_TYPECHECK_UNAVAILABLE` entries of `diagnostics`.
-
-**A compile error hides level 2.** When the scripts do not compile (`E_SCRIPT_COMPILE`), level 2
-skips every scene with `user:` components — their `E_UNKNOWN_CONFIG_KEY` / `E_PROPERTY_TYPE` /
-component checks are *missing*, not passed. The report says so: `level2.filesSkippedForScripts`,
-a `SKIPPED: N scene(s) …` note, and the human summary line reads `level 2 hydrated 0 file(s), N
-SKIPPED (scripts do not compile — user: components unchecked)`. Fix the compile error and run again.
-
-**Merge-log notes.** An `ack-unknown` entry (a `pix3 read` / `pix3 ack` of bytes the editor never
-recorded) prints as a `note:` only while its hash is the file's *current* version; one about a
-version the disk no longer holds is history and is not printed (it stays in `mergeLog` of `--json`).
-
-**Which tsconfig.** A project with its **own** root `tsconfig.json` (a Vite project, or one the
-editor's *build from templates* turned into one) is checked with it, as is, against its own
-`node_modules` (`mode: "project"`); nothing is written into it. Otherwise (`mode: "pix3-types"`)
-`check` uses `.pix3/tsconfig.check.json` against the bundled types in `.pix3/types/`, and first
-(re)writes both when they are missing or from another CLI build.
-
-**Where TypeScript comes from** — it is not a dependency of `@pix3/cli`: (1) the project's own
-`node_modules/typescript` (or an ancestor's); (2) the CLI's sibling install
-(`import.meta.resolve('typescript')`, e.g. the monorepo); (3) `~/.pix3/typescript/5.8.3/`,
-installed there once with `npm install --prefix ~/.pix3/typescript/5.8.3 typescript@5.8.3 …`
-(printed before it runs). `--offline` never installs: it fails with `E_TYPECHECK_UNAVAILABLE` and
-the command. `PIX3_TYPESCRIPT=<package dir>` overrides the search. Loaded with a dynamic `import()`.
-
-Measured (recipe-tapper-2d, 5 scripts, packed CLI installed outside the repo, fresh `HOME`):
-first `check` 2.1 s including the TypeScript install, then 1.45 s (validate ~0.2 s, tsc ~1.2 s).
-
-### SVG sprites
-
-Every texture in Pix3 (editor viewport, play mode, the single-file export) loads as bytes → `Blob`
-→ object URL → three's `TextureLoader` → `<img>`, so an `.svg` renders exactly when a browser
-`<img>` decodes it, at the size the `<img>` reports. Level 1 checks every `.svg` a scene
-references (once per file per scene, at its first reference):
-
-| Code | Severity | When |
-| --- | --- | --- |
-| `E_SVG_INVALID` | error | no `<svg>` root, or the root lacks `xmlns="http://www.w3.org/2000/svg"` (the browser refuses to decode it) |
-| `E_SVG_NO_SIZE` | error | no absolute `width`/`height` and no `viewBox` (renders into a cropped 300x150 box), or one dimension without a `viewBox` |
-| `W_SVG_VIEWBOX_ONLY` | warning | a `viewBox` but no absolute `width`/`height` (`%` and `style=` sizes count as none): Chrome gives it 300x150, art letterboxed |
-| `W_SVG_EXTERNAL_REF` | warning | an `href`, CSS `url()` or `@import` to anything but `#fragment` / `data:` — never loads in SVG-as-image mode |
-
-Measured in Chromium 129 through the runtime's own `ResourceManager` + `AssetLoader` + `Sprite2D`:
-a sized SVG auto-sizes the sprite to its `width`×`height`; a viewBox-only one to 300×150; one
-without `xmlns`, or any SVG whose Blob type is not `image/svg+xml`, fails to load (browsers do
-not sniff SVG).
-
-## `pix3 sfx` — sound effects without the editor
-
-```text
-pix3 sfx coin                                   # -> audio/coin.wav in the project root
-pix3 sfx "short high coin pickup" --out audio/pickup.wav --seed 7
-pix3 sfx explosion --json                       # { path, res, durationMs, preset, seed, modifiers, bytes, peak, params }
-```
-
-Presets: `coin`, `jump`, `hit`, `explosion`, `powerup`, `click`. Free text picks the preset whose
-keyword appears first (`boom`, `pickup`, `button`, `hurt`, …) and applies modifier words
-(`high`/`low` pitch ×1.4/×0.7, `short`/`long` time ×0.65/×1.6, `soft`). `--seed <n>` renders a
-deterministic variation (pitch ±15 %, times ±20 %, duty/vibrato/cutoff nudged); without it the
-preset as tuned. Output is 44.1 kHz 16-bit mono PCM WAV — `AssetLoader.loadAudio` decodes it with
-`decodeAudioData` like any `.ogg`/`.mp3`, and the export embeds it as `audio/wav`. `res` in the
-JSON is the `res://` path when the file lands inside a project. Exit 2 on a bad argument or a
-description that names no preset.
-
-The synth (`src/sfx/synth.ts`, no dependencies) is one jsfxr-style voice: square / saw / sine /
-triangle / noise, exponential pitch slide, pitch jump, vibrato, ADSR, resonant low-pass, DC
-blocker, peak normalisation. It does not use the editor's `@txt2sfx/*` packages: their only
-renderer drives an `OfflineAudioContext` the caller supplies, i.e. a native Web Audio module
-(`node-web-audio-api`) in Node. Each preset renders in well under 10 ms; the whole command runs in
-~0.12 s; files are 2–67 KiB (click 24 ms … explosion 772 ms).
-
-## `pix3 smoke` — run the game headless
-
-`pix3 smoke [scene]` runs the game in Node — no browser, no editor, no `pix3 serve` — for
-`--frames N` fixed steps of 1/60 s (default 120) and reports everything that went wrong. It is the
-behavioural check after `pix3 check` when no editor is connected; with the live channel,
-`game_run` is the stronger one (it renders).
-
-What runs: the project's scripts compiled with esbuild (as `validate` level 2 does, but bare
-imports are bundled for real from the project's `node_modules` — Rapier, three addons — and only
-what resolves nowhere becomes an empty module, reported as `W_SMOKE_STUBBED_IMPORT`), the scene
-loaded from disk by the real `SceneLoader`, a real `SceneRunner` in manual time. Frame 0 is loading
-and starting the scene (`onAttach`/`onStart`, then 128 event-loop turns so spawn chains land);
-frame N is the N-th step. The run happens in a worker thread, so a script stuck in a loop is
-stopped by `--timeout` (default 20 s).
-
-Stubbed: rendering (a null renderer; post-processing never loads), audio (no Web Audio in Node),
-input (no events), network (`scene.network` is null). Textures resolve empty, glTF models and
-Spine skeletons referenced by nodes are not built; images a script loads through three's
-`TextureLoader` "load" as blank 1×1 pictures (so preloaders finish). A small browser shim provides
-`window` / `document` / canvas / `localStorage` / `matchMedia` / `requestAnimationFrame`; any other
-browser property a script reads is recorded, and an error right after such a read is
-`E_SMOKE_DOM` with the read attached (`domAccess`).
-
-Scene: the argument (`res://`, project-relative or a path) runs that one scene. With no argument
-several run, one after another from one bundle, a line each (`src/smoke/select-scenes.ts`):
-
-1. In a git work tree with uncommitted changes (staged, unstaged or untracked): the **top-level**
-   scenes those changes reach — the scene itself, a prefab / `scenes/ui/` overlay it instances, a
-   script exporting a class it attaches as `user:X`, a `res://` file it names. `--changed` forces
-   this (exit 2 without git or without changes). Changes under `node_modules/`, `.yalc/` (a linked
-   package copy), `.git/`, `.pix3/`, `dist/`, `.vite/`, `.cache/` are not project changes and are
-   ignored, and a `*.spec.ts` / `*.test.ts` next to the scripts is not game code — a consumer
-   project's `.yalc/@pix3/runtime/**` and its unit tests used to read as hundreds of changed
-   scripts that reach no scene and widen every run to everything.
-2. Otherwise — no git, nothing changed, a changed scene/script that reaches no top-level scene (a
-   helper module, an unused prefab), or a changed `pix3project.yaml` — **every** top-level scene
-   (not instanced by another, not under `prefabs/` / `ui/`), `scenes/main.pix3scene` first (the
-   editor's startup scene, where the game lives), then `defaultExportScenePath`, then by path.
-   `--all` forces this.
-
-It never picks `defaultExportScenePath` alone any more: in every recipe that is the menu, input is
-empty, PLAY is never pressed, and a game whose `onStart` throws used to smoke green.
-
-| Code | |
-| --- | --- |
-| `E_SMOKE_SCRIPT` | A script hook threw (`onAttach`/`onStart`/`onUpdate`…); the engine disabled that component |
-| `E_SMOKE_DOM` | …and it was a browser API the shim does not provide (`domAccess` names it) |
-| `E_SMOKE_TICK` / `E_SMOKE_COMMAND` | The engine tick / a game command handler threw |
-| `E_SMOKE_CONSOLE_ERROR` | `console.error` (not the engine re-reporting one of the above) |
-| `E_SMOKE_UNHANDLED` | An unhandled promise rejection, or a timer callback that threw |
-| `E_SMOKE_LOAD` | The scene failed to load (missing prefab, invalid scene) |
-| `E_SMOKE_SCRIPT_COMPILE` / `E_SMOKE_SCRIPT_IMPORT` | Scripts do not compile / throw at module top level |
-| `W_SMOKE_MISSING_RESOURCE` | A `res://` file does not exist (the node loads without it) |
-| `W_SMOKE_PENDING_COMPONENT` | A component type is not registered — it never runs |
-| `W_SMOKE_CONSOLE_WARN`, `W_SMOKE_LOADER`, `W_SMOKE_STUBBED_IMPORT`, `W_SMOKE_STOPPED` | `console.warn`, loader warnings, an import replaced by `{}`, the game stopped itself |
-
-Exit 0 = no errors (warnings allowed), 1 = errors, 2 = could not run (with several scenes, the
-worst run decides): `E_SMOKE_NO_PROJECT`,
-`E_SMOKE_NO_SCENE`, `E_SMOKE_BUNDLE`, `E_SMOKE_UNSUPPORTED` (no esbuild), `E_SMOKE_TIMEOUT`,
-`E_SMOKE_CRASH`. The human report prints the `game` snapshot whole — on one line when it is short, pretty-printed
-and indented otherwise, cut only past 4 000 characters (`--json` always carries it whole).
-`--json` prints `{ ok, scene, frames, framesRequested, firstFrameOk, errors:
-[{ code, frame, script?, nodeId?, nodeName?, phase?, message, stack?, domAccess? }], warnings,
-nodes: { start, end }, timingsMs: { compile, load, firstFrame, step: { total, mean, p95, max },
-total }, scripts, domMissing, notes, game, logs }` — `game` is the `registerGameDebug` provider's
-`snapshot()` at the end (when the game registers one), `logs` the first `console.log` lines,
-frame-stamped. Stacks are source-mapped to the project's files. With no scene argument `--json`
-prints `{ ok, selection: "changed" | "all", reason, changed?, runs: [<that report, per scene>] }`.
-
-A green smoke run means nothing threw for N frames without input. It does not mean the game
-plays: nothing was tapped, nothing was drawn.
-
-## `pix3 tree` — find your way around a scene
-
-`pix3 tree <scene>` prints one line per node, indented by depth, from the YAML alone (no loader,
-no project code — instant):
-
-```text
-scenes/main.pix3scene — 12 nodes
-Group2D#game-root "Game Root" size=1080x1920 layout=stretch/stretch  components=[user:GameRules, user:TouchRules]
-  CanvasLayer2D#hud "HUD" size=1080x1920 layout=stretch/stretch  components=[user:ScoreHud]
-    Label2D#score-label "Score Label" text="SCORE 0" pos=(-340,850) layout=left/top
-    Group2D#result-overlay "Result Overlay" ↳ instance res://scenes/ui/result.pix3scene (1 property) hidden
-```
-
-`--depth N` stops N levels below the roots (cut subtrees end in `… +K below`); `--types A,B` keeps
-nodes of those types (or carrying those components; `instance` = prefab instances) with their
-ancestors as `·` context lines; `--props` adds, under each node, the properties that differ from
-the node type's defaults (read from a bare instance of the runtime class, through the disk-format
-table — the one step that loads the runtime bundle); `--json` gives the same as nested
-`{ id, type, name, depth, position?, size?, layout?, hidden?, text?, groups?, components,
-instance?: { path, rootType?, rootName?, overrides, properties }, props?, children }`. On an instance
-`overrides` counts every `overrides.byLocalId.*.properties` key (edits to nodes inside the prefab)
-and `properties` the instance node's own `properties` keys (applied to the prefab root); the line
-prints `(2 overrides, 1 property)`, or `(no overrides)` when both are 0.
-
-`pix3 tree` with no scene is the project overview: manifest facts, the `user:` scripts, and every
-scene/prefab/overlay with its node count, node types, components and instances (entry scene
-marked `*`). Exit 0, 1 when a scene does not parse, 2 for bad arguments or a missing file.
-
-## `pix3 kit` — the agent kit
-
-`pix3 kit` installs the agent kit into an existing project (one the editor created, or after a CLI
-upgrade); `pix3 new` runs the same step. What lands in the project:
-
-| Path | What |
-| --- | --- |
-| `AGENTS.md` | Root rules (read by Codex, Cursor, …). If the project already has its own, it is kept and the kit goes to `AGENTS.pix3.md` (the command prints the line to add). |
-| `CLAUDE.md` | `@AGENTS.md` (plus `@AGENTS.pix3.md` in that case). A `CLAUDE.md` of the project's own is never touched — the command prints the line to add. |
-| `.claude/skills/pix3-{scene-format,nodes,scripts,verify}/SKILL.md` + `reference.md` | Skills loaded on demand; the `reference.md` files are generated from `docs/` and the runtime's registry |
-| `.mcp.json` | The pinned `pix3 mcp --workspace` entry; other servers kept |
-| `.gitignore` | `.pix3/` appended when not covered; existing content kept |
-| `tsconfig.json`, `.pix3/tsconfig.check.json`, `.pix3/types/` | Only without a `tsconfig.json` of the project's own (see below) |
-| `pix3project.yaml` | `metadata.agentKit: { version, files }` (everything else as written) |
-| `.pix3/kit-manifest.json` | sha256 of every file the kit wrote |
-
-Without `--update`, existing files are never replaced (missing ones are written; an unchanged file
-from an older kit is reported `outdated`). `--update` replaces every kit file whose bytes still
-match the hash in `.pix3/kit-manifest.json` and **skips** (and reports) every file edited since.
-`.pix3/` is gitignored, so on a fresh clone the manifest is gone and every differing kit file counts
-as edited.
-
-**Generated, not copied.** `scripts/build-kit.mjs` (run at `prepack`; a repo checkout regenerates
-`kit/` automatically whenever an input changed) expands the templates in `kit-src/`: hand-written
-prose plus `{{include:<repo path>#<heading>}}` / `{{include:<repo path>@<paragraph>}}` directives
-over `docs/pix3-specification.md`, `docs/node-types-reference.md`, `docs/nodes-and-systems.md`,
-`src/services/agent/agent-skills/engine-api-map.md` and this README, and `{{generated:…}}` blocks
-computed from code (the `core:` component table from the runtime's registry, the MCP tool list,
-the barrier error codes). Syntax: `src/kit/generate.ts`. `src/kit.spec.ts` builds the kit and fails
-on drift: an unresolved directive, a `pix3` command or flag not in the usage text, a tool name
-outside the 14, a diagnostic code no command emits, a node type the loader does not know, a
-property in the nodes skill's tables that the disk-format descriptor
-(`packages/pix3-runtime/src/core/scene-disk-format.ts`) does not accept, a `core:` component that
-does not exist.
-
-### Script types (`.pix3/types/`)
-
-`scripts/build-runtime-types.mjs` (at `prepack`; rebuilt on demand in a checkout when the runtime
-sources change) runs `tsc -p packages/pix3-runtime/tsconfig.types.json` (declarations of what
-`src/index.ts` reaches — no specs, samples or `testing/`) into `runtime-types/@pix3/runtime/`, and
-copies `@types/three` (without its `node_modules`) to `runtime-types/@types/three/` — the runtime's
-public types extend three.js. The tarball carries that tree packed into one file,
-`dist/runtime-types.json` (see "Package layout" below); the installed CLI expands it on first use. `lit` (re-exported `property`/`state` decorators), `postprocessing`
-and the Spine runtime are not shipped: they are only reached from inside declaration files, which
-`skipLibCheck` leaves alone (they type as `any`). In a project without its own `tsconfig.json`:
-
-```text
-.pix3/types/@pix3/runtime/**      the runtime's .d.ts (+ package.json with the version)
-.pix3/types/@types/three/**       three.js types
-.pix3/types/version.json          which CLI build wrote them
-.pix3/tsconfig.check.json         paths → ./types/…, strict, noEmit, skipLibCheck, lib ES2022 + DOM,
-                                  include ../scripts/**/*.ts and ../src/scripts/**/*.ts
-tsconfig.json                     { "extends": "./.pix3/tsconfig.check.json" } — so an IDE sees them
-```
-
-## `pix3 serve` — workspace server
-
-Serves one project folder to the Pix3 editor over **one loopback port**, without File System
-Access. Built for a project that lives on a remote machine (VS Code Remote SSH): run `pix3 serve`
-there, forward the port, and connect the editor on your computer with the address and token.
-
-- Binds `127.0.0.1` only. `--port N`: exactly N; if it is busy the command fails (no silent
-  switch). Without `--port`: the first free port of 8490–8499.
-- Project root: `--project`, else the nearest ancestor of the cwd with `pix3project.yaml`.
-  A folder without `pix3project.yaml` is refused.
-- **One server per root.** A second `pix3 serve` on the same root prints the running server's
-  address and exits 0 (`--new-token` then rotates the token of the running server).
-- Stops on Ctrl+C / SIGTERM. stdout is for humans; the event log goes to stderr.
-
-Protocol version: **`WORKSPACE_PROTOCOL = 1`** (`src/protocol.ts`), reported as `protocol` in
-`hello` and `/ws/status`. It is independent of the CLI's lockstep product version.
-
-### Pairing and server state
-
-- On the first run the server mints a **token**: `p3ws_` + base64url of 32 random bytes. It is
-  printed **once** and never stored in plaintext. `pix3 serve --new-token` issues a new one; the
-  old token stops working at once, live sockets authenticated with it are closed.
-- State lives in `<root>/.pix3/` (mode 0700, with a `.gitignore` of `*`):
-  - `workspace.json` (mode 0600):
-
-    ```json
-    {
-      "version": 1,
-      "workspaceId": "<uuid, minted once per root>",
-      "root": "<canonical absolute root>",
-      "token": { "sha256": "<hex sha256 of the token>", "issuedAt": "<ISO time>" },
-      "server": {
-        "pid": 1234,
-        "port": 8490,
-        "serverSession": "<uuid>",
-        "control": "<secret>",
-        "startedAt": "<ISO time>"
-      }
-    }
-    ```
-
-    `server` is `null` while no server runs. **Revoke = delete this file**: a running server
-    notices within ~2 s, closes every socket and refuses the old token.
-    If `root` differs from the folder's canonical path (the project was copied), the server
-    mints a new `workspaceId` and token instead of trusting the copied file.
-  - `serve.lock` — pid of the server owning the root.
-  - `tmp/` — staging for atomic writes.
-  - `link/` — challenge files of the FSA link server.
-- **Server-private** = `.pix3` itself, `.pix3/workspace.json`, `.pix3/serve.lock`, `.pix3/tmp/**`
-  and `.pix3/link/**` (names compared case-insensitively): unreachable through every route
-  (`403 reserved_path`) and never listed.
-- **Everything else under `.pix3/`** is the editor's co-authoring bookkeeping
-  (`protected.json`, `merge-log.jsonl`, `recovery/**`, `ack.json`, …) and is readable and
-  writable like any other path. It is **never part of the revision set**: it does not move
-  `revision` and produces no `change` events — with one exception, `.pix3/ack.json` (see
-  `ChangeEvent` below). `/ws/manifest` lists it (see there).
-
-### Common rules (every HTTP route)
-
-- **Host**: `localhost`, `127.0.0.1` or `[::1]`, **with any port or none** (a forwarded local
-  port may differ from the server's). Anything else → `403 forbidden_host`.
-- **Origin**: absent (a local process) or one of `https://editor.pix3.dev`,
-  `http://localhost:8123`, `http://127.0.0.1:8123`. Anything else → `403 forbidden_origin`,
-  without CORS headers. Allowed origins get `Access-Control-Allow-Origin: <origin>`,
-  `Vary: Origin`, and `Access-Control-Expose-Headers: ETag, Content-Range, Content-Length,
-  Accept-Ranges, X-Mutation-Replayed`.
-- **Preflight** `OPTIONS` (no auth): `204`, `Access-Control-Allow-Methods: GET, HEAD, PUT,
-  POST, OPTIONS`, `Access-Control-Allow-Headers: Authorization, Content-Type, If-Match,
-  If-None-Match, X-Mutation-Id, Range`, `Access-Control-Max-Age: 600`.
-- **Auth**: `Authorization: Bearer <token>` on every route. Missing/wrong/revoked →
-  `401 unauthorized` with `WWW-Authenticate: Bearer`. After **10 failures within 60 s**, every
-  attempt (valid token or not) gets `429 rate_limited` with `Retry-After: <s>` and
-  `retryAfter` in the body, until the window moves on.
-- **Errors** are JSON: `{ "error": "<code>", "message": "<text>", ...extra }`.
-- **Paths** are POSIX, relative to the root, case preserved: `scenes/main.pix3scene`. Refused
-  with `400 bad_path`: empty, absolute (`/…`), backslashes, a drive prefix (`C:`), NUL, empty
-  segments (leading/trailing/double `/`), `.` or `..` segments, a `:` in a segment (an NTFS
-  stream: `name::$DATA`), a segment ending in `.` or a space (Win32 strips them). On Windows an
-  8.3 short name (`WORKSP~1.JSO`) is refused too — only an entry's own long name is accepted. A server-private path (see
-  above) → `403 reserved_path`.
-  `?path=` is percent-decoded **exactly once** (a literal `%2e%2e` after that one decoding is a
-  file name, not `..`); JSON bodies are not decoded. **No operation passes through a symlink**:
-  a symlink anywhere on the path, parents of a path being created included, →
-  `403 symlink`. A file where a parent directory is expected → `409 not_a_directory`.
-
-### Revision set, manifest and `revision`
-
-The **revision set** is what an export ships (the walk of `ProjectBuildService`): every file under
-the root except inside directories named `node_modules`, `.git`, `.yalc`, `.vscode`, `.idea`,
-`dist`, `build`, `out`, `coverage`, `.cache` (at any depth) and `.pix3/` at the root. A *file*
-named like one of those is included. Symlinks are neither listed nor followed.
-
-`revision` = lowercase hex sha256 of the UTF-8 text formed by the lines `<path>:<sha256>` of every
-**file** of the set, sorted by JavaScript string comparison (UTF-16 code units), joined with `\n`,
-no trailing newline. Directories do not contribute. (Empty set → sha256 of the empty string.)
-
-### Routes
-
-#### `GET /ws/manifest`
-
-A **full scan** of the disk (hashes cached by inode + size + mtime), so it also reconciles
-anything the watcher missed — differences it finds are broadcast as a `change` frame first.
-
-```json
-{
-  "workspaceId": "…",
-  "serverSession": "…",
-  "revision": "<hex>",
-  "seq": 12,
-  "files": [
-    { "path": "scenes", "kind": "dir", "size": 0, "mtime": 1790373745915 },
-    { "path": "scenes/main.pix3scene", "kind": "file", "size": 9, "mtime": 1790373745915, "sha256": "<hex>" }
-  ]
-}
-```
-
-`files` is sorted by path; `mtime` is integer epoch milliseconds; `sha256` is present on every
-file and absent on directories. Not an atomic snapshot of a folder others keep writing to.
-
-`files` is the revision set **plus** the non-private part of `.pix3/` (`.pix3` itself as a `dir`,
-then e.g. `.pix3/protected.json`, `.pix3/recovery/…`), so a client can list and find its
-bookkeeping the same way it would in a local folder. `revision` is computed from the revision set
-only: a client recomputing it from `files` must leave out every path under `.pix3/`.
-
-#### `GET /ws/file?path=<p>` (and `HEAD`)
-
-Raw bytes. Headers: `Content-Type` (by extension; unknown → `application/octet-stream`),
-`Content-Length`, `ETag: "<sha256 of the bytes>"`, `Accept-Ranges: bytes`,
-`Cache-Control: private, no-cache`, `X-Content-Type-Options: nosniff`.
-
-- `If-None-Match: "<sha256>"` (list, `W/` and `*` accepted) → `304` with the `ETag`, no body.
-- `Range: bytes=a-b` | `bytes=a-` | `bytes=-n` (one range) → `206` with
-  `Content-Range: bytes a-b/size`; unsatisfiable → `416` with `Content-Range: bytes */size`.
-  Several ranges or an unparsable header → the whole file, `200`.
-- A directory → `400 not_a_file`; missing → `404 not_found`.
-
-#### `PUT /ws/file?path=<p>`
-
-Body = the new bytes (≤ 1 GiB). Written to `.pix3/tmp/`, then renamed over the target (atomic on
-one filesystem; the file mode of a replaced file is kept). Missing parent directories are created.
-
-- `If-Match: "<baseHash>"` — optional. Current content hash ≠ base →
-  `409 { "error": "base_mismatch", "currentHash": "<hex>" | null, … }` and nothing is written.
-  `If-Match: *` = the file must exist.
-- `If-None-Match: *` — create only; existing file → `409 { "error": "exists", "currentHash" }`.
-- The target is a directory → `409 not_a_file`.
-- `X-Mutation-Id` — see *Mutation journal*.
-
-→ `200 { "path": "…", "sha256": "<hex>", "size": 10, "mtime": 1790373745915, "seq": 13 }`
-
-The check and the rename are serialised with the server's other writes, but they are **not** a
-compare-and-swap against a process writing the folder directly (the agent): that race remains.
-
-#### `POST /ws/mkdir` — `{ "path": "<p>" }`
-
-Recursive. → `200 { "path", "created": true | false, "seq" }` (`false` = already a directory);
-a file in the way → `409 exists`.
-
-#### `POST /ws/delete` — `{ "path": "<p>", "recursive"?: boolean }`
-
-→ `200 { "path", "kind": "file" | "dir", "seq" }`. Missing → `404 not_found`; non-empty
-directory without `recursive: true` → `409 not_empty`.
-
-#### `POST /ws/move` — `{ "from": "<p>", "to": "<p>", "overwrite"?: boolean }`
-
-Creates missing parents of `to`. → `200 { "from", "to", "kind": "file" | "dir", "sha256"?, "seq" }`
-(`sha256` for files). `to` exists → `409 exists` (unless `overwrite: true` and both are files);
-`to` equal to or inside `from` → `400 bad_move`; `from` missing → `404 not_found`.
-
-#### `POST /ws/hash` — `{ "paths": ["<p>", …] }` (≤ 20 000)
-
-Hashes of the disk **now** (for the sync barrier). → `200 { "hashes": { "<p>": "<hex>" | null }, "seq" }`;
-`null` = missing or not a file. Any invalid path fails the whole request (`400 bad_path`,
-`403 reserved_path`, `403 symlink`).
-
-#### `GET /ws/status`
-
-→ `200 { "workspaceId", "serverSession", "protocol", "cliVersion", "root", "pid", "port",
-"revision", "seq", "leased" }`. Accepts the bearer token **or** `X-Pix3-Control: <server.control>`
-from `workspace.json` (how another local `pix3` process confirms a live server is the one the file
-describes; beyond this route and `GET /ws/revision`, the control secret grants only the agent
-lane below — never the file API).
-
-#### `GET /ws/revision`
-
-→ `200 { "revision", "seq", "serverSession" }` — no scan, the table as it is. Bearer token or
-`X-Pix3-Control`.
-
-### Mutation journal (`X-Mutation-Id`)
-
-`PUT /ws/file`, `/ws/mkdir`, `/ws/delete`, `/ws/move` accept `X-Mutation-Id: <1–128 chars of
-[A-Za-z0-9_.:-]>`. Within one `serverSession`, the first request with an id is applied and its
-answer recorded (success **and** failure). A retry with the same id — also while the first is
-still in flight — is **not applied again**: it gets the recorded status and body plus
-`X-Mutation-Replayed: true` (a PUT retry's body is drained and discarded). The same id on a
-different request (other route, path or conditions) → `422 mutation_id_reused`. The journal keeps
-the last 2 000 ids and is lost on restart: after a new `serverSession`, the outcome of an
-unanswered mutation is unknown and must be checked against the disk, not retried blindly.
-
-### `seq`
-
-One counter per `serverSession`, starting at 0. Every change of the file table takes the next
-value: an external change batch (sent as a `change` frame) or one of the server's own mutations
-(returned in its response, **not** sent as a frame). So `seq` is monotonic but **not dense** on the
-event stream — a gap is a write made through the API, not a lost event. Nothing is replayed: a
-client that reconnects gets the current `revision`/`seq` in `hello` and must re-scan
-(`/ws/manifest`) if its revision differs.
-
-### WebSocket `/ws/events`
-
-Same Host/Origin rules as HTTP (checked at the upgrade; refused → `403` before the handshake).
-**The token is never in the URL.** All frames are JSON text objects; binary frames close the
-socket (`1003`).
-
-**Client → server**
-
-| Frame | Meaning |
-| --- | --- |
-| `{ "type": "auth", "token": "<token>" }` | Must be the **first** frame, within **5 s**. |
-| `{ "type": "pong" }` | Answer to `ping`. |
-| `{ "type": "ping" }` | Server answers `{ "type": "pong" }`. |
-| `{ "type": "lease", "action": "acquire", "leaseId"?: "<id>" }` | Take the free lease; with the current `leaseId`, resume it (during the grace period, or from a new socket while the old one is still open). |
-| `{ "type": "lease", "action": "takeover" }` | Take the lease from whoever holds it. |
-| `{ "type": "lease", "action": "release" }` | Give it up. |
-| `{ "type": "call-result", "id": "<call id>", "result": { "content": [Block, …], "isError"?: true, "_meta"?: {…} } }` | Answer a `call` (lease holder only). `Block` = `{ "type": "text", "text" }` or `{ "type": "image", "data": "<base64, no data: prefix>", "mimeType": "image/png" }`. `_meta.pix3 = { playRevision, stale }` on observing tools (see the agent lane). |
-
-**Server → client**
-
-| Frame | When |
-| --- | --- |
-| `{ "type": "hello", "workspaceId", "serverSession", "protocol": 1, "cliVersion", "revision", "seq", "root", "projectId": string \| null, "projectName", "lease": "held" \| "free", "leaseGraceMs": 10000, "agentPresence": { "attached", "agent" } }` | Right after a valid `auth`. `root` is the server's absolute path, `projectName` is `metadata.projectName` (else the folder name), `projectId` is `metadata.projectId`, `leaseGraceMs` is the lease grace (below), `agentPresence` the current agent presence (next row). |
-| `{ "type": "agent-presence", "attached": boolean, "agent": { "name": string \| null, "verified": false } \| null }` | Whenever the agent presence changes: a `pix3 mcp --workspace` process announced itself, left, or went silent for 30 s (see `POST /ws/agent/presence`). `agent` is the most recently heard process; its name is self-declared. The editor keeps its background loops running while `attached` (keepalive). |
-| `{ "type": "change", "seq", "revision", "events": [ChangeEvent, …] }` | External changes, debounced ~100 ms (at most ~1 s under a steady stream). `revision` is the revision after the batch. |
-| `{ "type": "ping" }` | Every 10 s. A socket silent (no frame at all) for 30 s is terminated. |
-| `{ "type": "lease", "state": "granted", "leaseId", "resumed": boolean }` | Lease granted (`resumed: true` = same lease after a reconnect). |
-| `{ "type": "lease", "state": "busy", "inGrace": boolean }` | Someone else holds it (`inGrace`: its holder is disconnected but may come back). |
-| `{ "type": "lease", "state": "lost", "reason": "taken_over" \| "expired" \| "revoked" \| "resumed_elsewhere", "leaseId" }` | Sent to the holder that lost it. `resumed_elsewhere`: its `leaseId` was presented on another socket (then this one closes with `4409`). |
-| `{ "type": "lease", "state": "released" }` | Answer to `release`. |
-| `{ "type": "call", "id", "name", "input", "agent"? }` | An MCP tool call for the lease holder. `agent = { name, session, verified: false }` on agent-lane calls: `name` is what the `pix3 mcp` process calls itself (its MCP client's `clientInfo.name`, else `--agent` / `PIX3_AGENT`), `session` a random id per `pix3 mcp` process. Nothing verifies either. |
-| `{ "type": "error", "error": "<code>", "message", "id"? }` | `unauthorized`, `auth_timeout`, `rate_limited`, `revoked` (then the socket closes), or `bad_frame`, `unknown_frame`, `not_lease_holder`, `bad_result`, `unknown_call`. |
-
-`ChangeEvent`:
-
-```json
-{ "op": "create" | "modify" | "delete" | "rename", "path": "<p>", "kind": "file" | "dir", "sha256"?: "<hex>", "from"?: "<p>" }
-```
-
-`sha256` on file `create`/`modify`/`rename`; `from` only on `rename` (a delete + create of the same
-content in one batch, when unambiguous). Events are sorted by `path`. A file touched without a
-content change produces no event. Changes made **through this API** never appear as events.
-Nothing under `.pix3/` produces events, except an outside change of `.pix3/ack.json` (what
-`pix3 read` / `pix3 ack` write): it comes as its own frame with one `create` / `modify` /
-`delete` event for that path, and the frame's `revision` is unchanged. Clients may also poll it.
-Events are hints, not a guarantee of seeing every write — the barrier re-checks with
-`/ws/manifest` or `/ws/hash`.
-
-**Close codes**: `4401` unauthorized / auth timeout / revoked, `4409` lease resumed on another
-socket, `4429` rate limited, `1003` binary frame, `1001` server shutting down.
-
-**Lease.** One holder at a time; it is the window that edits and answers MCP calls. When the
-holder's socket closes, the lease is kept for a **10 s grace**: the same window reconnecting
-sends `acquire` with its `leaseId` and gets `resumed: true` (calls it had been handed are sent
-again); anyone else gets `busy` with `inGrace: true`. After the grace, the lease is free and
-pending calls fail. The server does **not** announce that expiry: a client answered
-`busy {inGrace: true}` should send `acquire` again after `leaseGraceMs` (the editor adds 500 ms,
-and falls back to 11 s for a server that omits the field), repeating until `granted` or a
-`busy {inGrace: false}`. The editor keeps its `leaseId` per workspace in `sessionStorage`, so a
-reloaded tab resumes its own lease; another tab never shares it.
-
-**The `leaseId` is the holder's secret**: an `acquire` presenting the current holder's `leaseId`
-from a **different socket while the holder's socket is still open** is the same tab after a
-reload whose new page connected before the old page's socket closed. The lease moves to the new
-socket at once — `granted {resumed: true}` there, `lost {reason: "resumed_elsewhere"}` on the old
-socket, which is then closed with `4409` (no grace starts); calls the old socket had not answered
-are sent again on the new one, same ids. Any other `leaseId` (or none) still gets
-`busy {inGrace: false}`. Because of that rule the editor presents a stored `leaseId` only when the
-page is a reload (`PerformanceNavigationTiming.type === "reload"`) or the page that stored it
-marked it on `pagehide` — the copy of `sessionStorage` a duplicated tab inherits from a live tab
-is dropped, and that tab acquires without an id. Against an older server (no move on a matching
-id), an editor answered `busy {inGrace: false}` while presenting its own `leaseId` asks again
-every 1 s for up to 15 s. On `takeover`, the old holder
-gets `lost/taken_over` and calls it had not
-answered go to the new holder. On `release`, pending calls fail. The HTTP routes do not check the
-lease (v1): a window without it is expected to stay read-only.
-
-**Calls.** `WorkspaceServer.enqueueCall(name, input, timeoutMs = 60 000, extra?) →
-Promise<ToolCallResult>` (in process; the agent lane below is its HTTP face). With no lease holder
-it resolves at once with an error result (`isError: true`, `relayFailure: 'no_editor'`); otherwise
-the call is delivered to the holder (`extra` becomes extra fields of the `call` frame) and the
-promise settles with its `call-result`, or an error result on timeout (`relayFailure: 'timeout'`)
-or lease loss (`'cancelled'`). A reconnecting holder that resumes its lease gets the calls it had
-been handed again, with the same ids — the editor answers a repeated id once.
-
-### Agent lane — `/ws/agent/*`
-
-The routes a local `pix3 mcp --workspace` process drives. **Auth: `X-Pix3-Control: <server.control>`
-only** (from `.pix3/workspace.json`, 0600 — a process of the same user; the plan's trust model).
-The browser's bearer token is refused (`401 unauthorized`), and so is any request carrying an
-`Origin` (`403 forbidden_origin`): browsers never call this lane.
-
-| Route | Answer |
-| --- | --- |
-| `GET /ws/agent/status` | `/ws/status` fields plus `holder: "connected" \| "grace" \| null`, `projectName`, `projectId`, `agentPresence: { attached, agent }`. |
-| `POST /ws/agent/presence` `{ agent: { name, session }, leaving? }` | Heartbeat of a `pix3 mcp --workspace` process: `pix3 mcp` sends it on start, once its MCP client has introduced itself, every 10 s, and with `leaving: true` on shutdown. One presence per `session`; it expires 30 s after its last heartbeat (an agent-lane `call` also counts as one). Answers `{ agentPresence }`; every change goes out as an `agent-presence` frame. |
-| `GET /ws/agent/tools` | `{ tools: [{name, description, inputSchema}], serverSession }` — the window's own tool definitions for the v1 allowlist (it answers an internal `tools_manifest` call within 5 s). `409 no_editor` without a window. |
-| `POST /ws/agent/call` `{ name, input, timeoutMs?, agent? }` | Parks the call for the lease holder and answers when it replies: `200 { result }` (the window's result as is, error results included). `timeoutMs` is clamped to 1–120 s (default 120 s). `409 no_editor` at once when no window holds the lease (message: open `<root>` in Pix3 — File → Connect to Workspace…); `504 no_editor_reply` when it does not answer in time; `409 lease_lost` when the lease ended under the call (on a takeover the call goes to the new holder instead); `429 too_many_calls`. `agent` → the `call` frame's `agent`. |
-| `POST /ws/agent/hash` `{ paths }` | Same as `POST /ws/hash`. |
-| `POST /ws/agent/expect` `{ expect: { path: sha256 } }` | The agent's expectations against the disk **now**: `{ matchesAgent, differing: [{ path, diskHash \| null, agentHash, recovery, mergeLog? }], hashes, seq }`. `recovery` = the wire path of a file under `.pix3/recovery/<encodeURIComponent(path)>/` whose bytes hash to `agentHash` (every journaled version of that path is hashed), else `null` — a copy is named only when it exists. `mergeLog: true` when `.pix3/merge-log.jsonl` has a line for that path whose `mergedHash`/`hash` is the disk hash, or one no older than the file's mtime minus 5 s — the editor wrote those bytes. |
-| `GET /ws/agent/changes?since=<seq>` | Rescans the whole revision set first (the watcher may have missed a write; differences go out as a `change` frame), then `{ since, seq, revision, paths, complete, entries }`: `paths` = distinct revision-set **files** changed after `since` — external writes and writes through the file API alike (`.pix3/` never, directories never); `entries` = one `{ seq, path, origin }` per recorded change, `origin` = `external` (seen by the watcher or this rescan) or `editor` (a mutation through the file API, i.e. the editor window). The server keeps the last 5 000 file changes; `complete: false` = the ring no longer reaches back to `since`, so an empty list proves nothing. |
-
-## `pix3 mcp --workspace` — the live channel
-
-A stdio MCP server the agent starts from its config (`.mcp.json`, `pix3 setup`). It has no port
-of its own: it finds the running `pix3 serve` of the project (`--project`, else the nearest
-ancestor of the cwd with `pix3project.yaml`) through `.pix3/workspace.json` and confirms it with
-`GET /ws/agent/status` + the control secret. When none runs, every tool answers
-`no_workspace_server` and stderr says ``Workspace server is not running. Run `pix3 serve` in
-<root>``; the next call looks again, so the agent never restarts its MCP server.
-
-**Presence.** While it runs, the process announces itself to that server
-(`POST /ws/agent/presence`, every 10 s and on start/stop; failures are silent and the next beat
-rediscovers a restarted server). That is what tells the editor an agent is attached, so it keeps
-the game, the viewport, file polling and reconnects running in a hidden or unfocused tab instead
-of pausing them for battery (`AgentKeepaliveService`; the user can switch this off in Settings →
-General). `PIX3_PRESENCE_HEARTBEAT_MS` overrides the cadence (tests).
-
-**Tools (v1, exactly):** `project_status`, `play_start`, `play_stop`, `play_restart`,
-`play_status`, `game_run`, `game_input`, `game_observe`, `read_errors`, `read_logs`,
-`viewport_screenshot` (the PNG comes back as an MCP image block), `generate_asset`,
-`generate_sfx`, `get_selection`. No scene-mutating tool: the agent edits files. Schemas are the
-window's (`GET /ws/agent/tools`), with a static fallback so `tools/list` works before a window
-connects (a `notifications/tools/list_changed` follows once a window's schemas are known).
-`play_start` / `play_restart` / `game_run` also take `expect: { path: sha256 }` — the sha256 of the
-raw bytes of every file the agent wrote.
-
-**The sync barrier** (plan §5 D) runs before `play_start`, `play_restart` and `game_run`:
-
-1. **Agent's expectations.** `expect` is checked against the disk (`/ws/agent/expect`) before
-   anything syncs. Any mismatch → `disk_differs_from_agent` with, per file: merged by the editor
-   (`mergeLog: true` — re-read it), or overwritten — with `recovery: ".pix3/recovery/…"` only when
-   a copy with exactly those bytes exists, else "no copy exists — write the file again". Nothing
-   starts. Without `expect` the answer says `agentExpectations: "none"`.
-2. **Editor = disk.** The window's internal `sync_barrier` holds autosave (edits accumulate and are
-   saved after the run), stops play, runs `syncNow()` (waits for the stabilisation window and the
-   script build; re-reads `pix3project.yaml` when the disk holds another version) and returns
-   `{loaded: {path: sha256}, errors}` — every open scene/prefab (any path), every source the last
-   script build read (the entry scripts **and every module the bundle pulled in**, e.g. `src/**`;
-   the hash recorded when the build read it, so nothing is re-read) and `pix3project.yaml`. An open
-   scene the editor holds no disk version of is a `load_failed` error, never silently left out. The
-   MCP process gives this call 100 s. These hashes (plus `expect`) are compared with `/ws/agent/hash` at that moment;
-   a mismatch retries the editor's sync for up to ~5 s. Then: loader/compiler errors →
-   `load_failed` (`{file, line, message, kind}`); a file that stays unreadable →
-   `pending_external`; hashes that never agree → `sync_timeout` with the differing paths — except
-   when every difference is an `expect` path whose disk version moved on *after* step 1 while the
-   editor already holds what the disk holds (`loadedHash === diskHash !== agentHash`): that is the
-   agent's expectation being stale (the editor merged the write with a human edit, a human saved,
-   another agent wrote), retrying cannot bring the old bytes back, and it answers
-   `expectation_stale` at once. The
-   window then starts the game (`game_run` starts play itself; `play_restart` of a stopped game is
-   a start) and answers only once the game is actually running: up to 30 s, as soon as it runs,
-   failing fast (`load_failed` with the play-mode error) when play mode stops instead; `startupMs`
-   says how long the start took (always present in the answer: `null` means no start happened —
-   `game_run` found the game already running — never "0 ms"). The MCP process gives the tool call 120 s (the server's cap). The
-   hold is released (`sync_release`) after the run.
-3. **After the run** (for `game_run` when it finished; for `play_start` / `play_restart` right
-   after the start was acknowledged) the verified files are hashed again and
-   `/ws/agent/changes?since=<seq of the verification>` is read: `changedDuringRun` and
-   `editorWroteDuringRun`.
-
-The answer of a barrier tool:
-
-```json
-{
-  "revision": { "files": 91, "digest": "<sha256 of the whole map>",
-                "changed": { "<path>": "<sha256 of the verified version>" }, "removed?": ["<path>"] },
-  "startupMs": 8123,
-  "matchesAgent": true,
-  "matchesDisk": true,
-  "changedDuringRun": [],
-  "editorWroteDuringRun": [],
-  "editorChangedSinceAgentWrite": [],
-  "result": { "…": "the editor tool's own result" }
-}
-```
-
-`revision` is **compact by default**: the verified map (every open scene, every source the build
-read, the manifest — ~90 entries on a real game) used to open every answer in full. Now `files` is
-its size, `digest` a sha256 over its sorted `path\0hash` lines (equal digests = equal maps), and
-`changed` holds only the entries that are new or different since the **previous answer of this
-`pix3 mcp` process** (the whole map on the first answer; `removed` names paths that dropped out).
-Pass `fullRevision: true` to any barrier or observing tool for the plain `{ "<path>": "<sha256>" }`
-map, or read `editor.playRevision` from `project_status` while the game plays. `startupMs` is
-always present: the milliseconds from the start request until the game was running, or `null`
-when no start happened (the game was already running, so there was nothing to measure). `matchesAgent` is `null` (with `agentExpectations: "none"`) without `expect`; `matchesDisk` is
-whether every verified hash still matched the disk at the final check; `changedDuringRun` is what
-the barrier did not verify: every file changed meanwhile by someone other than the editor, plus
-every verified file whose hash moved between the two checks with no editor write on record
-(`changeLogIncomplete: true` when the server's ring did not reach back); `editorWroteDuringRun` is
-every file whose only changes since the verification are the editor's own writes through the file
-API (e.g. a run report under `design/tests/reports/`) — known to the server, so not a
-detection. Both list files only, never directories; `editorChangedSinceAgentWrite` is
-the `expect` paths the merge log says the editor wrote after the check. **A green answer without
-marks means: at start disk = agent's expectations = verified version; at the final check the
-verified hashes match disk; detected changes are listed.** It does not mean the disk did not change
-during the run: `v1 → v2 → v1` between the two checks is invisible, and the game reads resources
-lazily.
-
-**Observing tools** (`play_status`, `game_input`, `game_observe`, `viewport_screenshot`,
-`read_errors`, `read_logs`) neither stop nor sync: `{ revision, stale, result }`, where `revision` is
-what the running game was verified against (compact, as above; `null` when play was not started
-through the barrier) and `stale: true` when the editor saw an external change during play or a
-`revision` path's disk hash moved since. `read_errors` takes `since` (epoch ms) like `read_logs`;
-every entry carries its `at`. Other tools (`project_status`, `play_stop`, `get_selection`, `generate_*`) answer
-with the editor's result as is. `project_status` without a window answers
-`{ connected: false, server, editor: null, message }` (not an error).
-
-**Error codes** (every error is `isError: true` with `{ "error": "<code>", "message", … }`):
-
-| Code | When |
-| --- | --- |
-| `disk_differs_from_agent` | Step 1: the disk does not hold the `expect` versions (`differing[]` with `recovery`, `mergeLog`, `hint`). |
-| `expectation_stale` | Step 2, at once: the disk moved past an `expect` version after step 1 and the editor already matches the disk (`differing[]` with `diskHash` / `agentHash` / `loadedHash`, plus `mergeLog` / `recovery` / `hint` as in step 1). Somebody wrote a newer version — re-read it, re-run `pix3 check --json`, pass the new hashes. Not editor lag. |
-| `sync_timeout` | Step 2: the editor's loaded hashes did not match the disk within ~5 s (`differing[]` with `loadedHash` / `agentHash` / `diskHash`) — the editor is still catching up with a write. |
-| `load_failed` | Step 2: the loader or the script compiler failed on the current files, or an open scene has no verified version (`errors[]`). At the start: the game was not running within 30 s, or play mode stopped (`result` carries it, with `startupMs`). |
-| `pending_external` | Step 2: a file stays unreadable (partial / invalid write); the editor keeps its last good version. |
-| `no_editor` | No window holds the lease, it did not answer (`reason: "no_reply"`), or it lost the lease mid-call (`reason: "lease_lost"`). |
-| `permission_denied` | `generate_*`: the human denied, or did not answer within 60 s. |
-| `no_workspace_server` | No `pix3 serve` runs for the project root. |
-
-Anything else the editor refuses (`unknown_tool`, `agent_disabled` when the human switched the
-channel off) is passed through as the editor wrote it.
-
-**Generation permission.** The first `generate_asset` / `generate_sfx` of a connection (server
-session + lease + `pix3 mcp` process) opens a prompt in the editor naming the process and what it
-calls itself (unverified); the call waits up to 60 s. Allowed → 20 generations, then it asks again.
-In memory only: a reconnect, a new `pix3 serve` run, a lease takeover or a new `pix3 mcp` process
-resets it; the status-bar Agent pill has a revoke button and switches the channel off.
-
-## MCP configuration and `pix3 setup`
-
-`pix3 new` and `pix3 kit` write the project's `.mcp.json` (Claude Code's project format), **pinned
-to the CLI version that wrote it** — never a bare `@pix3/cli`:
-
-```json
-{ "mcpServers": { "pix3": { "command": "npx", "args": ["-y", "@pix3/cli@<X.Y.Z>", "mcp", "--workspace"] } } }
-```
-
-`pix3 setup [claude|codex]` prints (never runs) the registration for a project without one:
-`claude mcp add pix3 -- npx -y @pix3/cli@<X.Y.Z> mcp --workspace` (run in the project folder), and
-for Codex a `~/.codex/config.toml` block — `[mcp_servers.pix3]` with `command`, `args` (plus
-`--project <root>`, since that config is global) and `tool_timeout_sec = 180`. The Codex keys are
-the ones `tools/pix3-agent-bridge` passes to `codex exec -c mcp_servers.pix3.*`; the file form is
-best-effort, check `codex mcp --help` of your Codex version.
-
-**Dev mode.** From a checkout of the pix3 repo (the CLI runs from `packages/pix3-cli/src/`), or
-with `PIX3_CLI_DEV=1`, both write `node <repo>/packages/pix3-cli/src/index.ts mcp --workspace`
-instead, so the channel can be tried before that version is on npm. `PIX3_CLI_DEV=0` forces the
-pinned form.
-
-## Package layout and publishing
-
-The published package has **no runtime `dependencies`**, so a cold `npx -y @pix3/cli@X.Y.Z …`
-fetches one tarball and installs nothing else (measured in
-`.plans/measurements/external-agent-phase0-cold-start.md`). `prepack` builds:
-
-```text
-dist/index.js               the bin: src/index.ts + yaml + @modelcontextprotocol/sdk (zod, ajv, …) + ws,
-                            one minified ESM file (scripts/build-bin.mjs); lazy commands stay lazy
-dist/validate/prebuilt/     validate + @pix3/runtime + three (scripts/build-validate.mjs)
-dist/smoke/prebuilt/        smoke worker + tree defaults + @pix3/runtime + three (scripts/build-smoke.mjs)
-dist/runtime-types.json     runtime-types/ packed into one file (scripts/build-runtime-types.mjs):
-                            ~1 100 small .d.ts cost npm over a second to unpack on every npx run
-kit/                        the agent kit (scripts/build-kit.mjs)
-templates/                  copy of src/templates/projects (scripts/copy-templates.mjs; removed at postpack)
-```
-
-Left out of the bin on purpose: Node built-ins; `esbuild` (an `optionalDependency` — level 2 of
-`validate`, `smoke` and `check` resolve it from the bin with `import.meta.resolve`, and degrade
-with a note when it is absent) and `typescript` (fetched on demand by `check`); `ws`'s optional
-native `bufferutil` / `utf-8-validate`; and the checkout-only modules (`validate/bundle.ts`,
-`smoke/bundle.ts`, the kit generator), which become a throwing stub. Every file the CLI reads from
-its own package is addressed from the package root (`src/package-root.ts`), never relative to the
-current module — in the bundle every module's `import.meta.url` is the bin's. The sources (`node
-src/index.ts`, the specs) never use a prebuilt bundle, even when an old `dist/` exists.
-`src/bin-bundle.spec.ts` builds the bin into a temp package layout and checks `--version` against
-`package.json` (and that against the lockstep root version), the pinned `@pix3/cli@X.Y.Z` launch,
-and that nothing but built-ins and the optional externals is imported at run time.
-
-Publishing is `.github/workflows/publish-packages.yml` (npm Trusted Publishing / OIDC, no token):
-a `runtime-vX.Y.Z` tag publishes `@pix3/runtime` and `@pix3/cli` together, `cli-vX.Y.Z` the CLI
-alone, or run the workflow manually. The job runs `npm ci` at the repo root (the build needs the
-runtime sources, the root TypeScript and esbuild), checks the lockstep version against the root
-and the tag, type-checks, runs the CLI specs and `npm publish`es. Try the tarball locally with
-`npm pack -w packages/pix3-cli` at the repo root, then `npx -y --package ./pix3-cli-X.Y.Z.tgz pix3 …`.
+# @pix3/cli
+
+Command line for Pix3:
+
+```text
+pix3 new [<2d|3d> [dir]] [--name <n>]         create an empty 2D or 3D project (npm create pix3)
+pix3 editor [--project <dir>] [--stop] [--stop-chrome] [--chrome-only] [--no-chrome] [--port <n>] [--cdp-port <n>] [--headless]
+                                              find/start the dev server, open the editor in Chrome (CDP behind the token proxy)
+pix3 agent-setup [claude|codex] [--repair] [--cdp-port <n>] [--project <dir>]
+                                              write the project's chrome-devtools-mcp config
+pix3 validate [paths…] [--json]               strict scene check
+pix3 check [--json] [--no-hydrate] [--offline] [--no-sync] [--project <dir>]
+                                              validate + tsc over the scripts + versions
+pix3 smoke [scene] [--changed|--all] [--frames N] [--timeout S] [--json] [--project <dir>]
+                                              run the game headless in Node, report what threw
+pix3 tree [scene] [--depth N] [--types A,B] [--props] [--json] [--project <dir>]
+                                              scene outline, one line per node; no scene = overview
+pix3 kit [--update] [--migrate] [--project <dir>]
+                                              install / update the agent kit; --migrate: a 1.x kit → 2.x
+pix3 character-compile <spec> [--dry-run] [--force] [--json] [--project <dir>]
+                                              a 2D character (.pix3anim + prefab) from frame PNGs
+pix3 sfx <preset|"text"> [--out <f.wav>] [--seed <n>] [--json]
+                                              synthesize a sound effect to WAV, offline
+pix3 gap "<what was missing>" [--kind …] [--list] record what the agent had to work around
+pix3 help [command]                           this overview, or one command's usage
+```
+
+`pix3 <command> --help` (or `-h`, or `pix3 help <command>`) prints that command's own usage —
+every text lives in `src/usage.ts` (`USAGE`, `COMMAND_USAGE`), and `bin-bundle.spec` holds every
+command the entry dispatches to an entry there, answered by the bundled bin. `validate --help`
+adds its codes, `check --help` the ones it adds.
+
+A usage error exits **2**: an unknown option, an option without its value, a bad argument, or no
+`pix3project.yaml` above the folder — with the message (and, for a bad argument, the command's
+usage) on stderr. That holds for `editor`, `agent-setup` and `gap` as for the checks; `kit`
+refuses an unknown option rather than ignoring it (`pix3 kit --updat` is exit 2, not a plain
+install).
+
+`pix3 new` is what `npm create pix3` runs: the `base` layer of `packages/create-pix3/templates/`
+(package.json, vite.config.ts with `pix3()`, index.html, src/main.ts, tsconfig.json, gitignore,
+README.md) plus the `2d` or `3d` layer (one empty entry scene), `{{PROJECT_NAME}}` /
+`{{PACKAGE_NAME}}` / `{{PIX3_VERSION}}` substituted, `pix3project.yaml` generated, then the agent
+kit. Nothing in it plays a game. Record: `.plans/templates.md`.
+
+Two things a first run trips on: **2.0.0-alpha packages are not published yet** — a new
+project's `npm install` fails until they are; the starter's README says how to link a pix3-core
+checkout meanwhile (`node_modules` → the checkout's, `node <checkout>/packages/cli/src/index.ts`
+for `pix3`). And **the dev port is Vite's**, 5173 only when free: `pix3 editor`, the kit and every
+harness read `.pix3/dev.json` (`editorUrl`, `publicEditorUrl`), never a fixed port.
+
+`new`, `kit`, `editor` and `agent-setup` load neither TypeScript nor the kit generator: the kit
+and the runtime types are prebuilt into the package (`kit/`, `dist/runtime-types.json`, at
+`prepack`).
+`tree` reads YAML only; `smoke` and `tree --props` load the runtime from a bundle prebuilt at
+`prepack` (`dist/smoke/prebuilt/`, like validate's), so none of this slows `new` / `editor`.
+
+Coding agents drive the open editor tab through Chrome DevTools MCP (`chrome-devtools-mcp`): the
+tab registers its `pix3_*` tools on the page (`packages/editor-core/src/host/bridge-tools.ts`),
+`pix3 editor` puts that tab in a Chrome whose DevTools protocol is reachable only through its
+token proxy, `pix3 agent-setup` points the agent's MCP config at the proxy with the token. There is no Pix3 MCP server (plan §D.2); the agent-facing procedure is
+the kit's `pix3-editor` skill.
+
+## `pix3 check` — everything an agent should run after a batch of edits
+
+`pix3 check` = `pix3 validate` (both levels) + a TypeScript type-check of the project's scripts +
+a version check. Exit 0 = no errors (warnings
+allowed), 1 = at least one error, 2 = could not run. Files are the truth only once the editor has
+written them: when `.pix3/dev.json` names a live dev server, `check` first asks it to flush the
+editor's unsaved scenes (`POST /__pix3/api/flush`, up to 15 s; `--no-sync` skips it, a dead
+server is ignored). Diagnostics are one list, validate's plus:
+
+| Code | Severity | When |
+| --- | --- | --- |
+| `E_TYPE` | error | a tsc diagnostic (`message` starts with `TS<code>:`; `file`, `line`) |
+| `E_TYPECHECK_UNAVAILABLE` | error | TypeScript could not be found or installed (`fix` = the command to run) |
+| `E_EDITOR_UNSYNCED` | error | `.pix3/dev.json` points at a live dev server whose editor did not flush its unsaved scenes within 15 s (`--no-sync` reads the disk as it is) |
+| `E_RUNTIME_VERSION` | error | the version gate: the project resolves a `node_modules/@pix3/runtime` that is not the runtime this CLI validates (and smoke-runs) with — run the project's own CLI (`npx pix3 …`) or install the matching runtime |
+| `W_PIX3_VERSION_MISMATCH` | warning | an installed `@pix3/cli`, `@pix3/vite-plugin` or `@pix3/editor-core` is not this CLI's version (lockstep packages) |
+| `W_RUNTIME_NOT_INSTALLED` | warning | own `tsconfig.json`, and no `node_modules/@pix3/runtime` |
+| `W_KIT_OUTDATED` | warning | `metadata.agentKit.version` is not this CLI's version (`pix3 kit --update`) |
+| `W_EDITOR_HMR_API` | warning | `import.meta.hot` in a module the editor runs |
+| `W_EDITOR_CSS_IMPORT` | warning | a stylesheet import (not `?inline`/`?raw`/`?url`) in a module the editor runs |
+| `W_EDITOR_DYNAMIC_IMPORT` | warning | an `import()` whose argument is not one plain string, in a module the editor runs |
+
+"A module the editor runs" = the editor's script chain (plugin contract B): `scripts/**`,
+`src/scripts/**`, `design/tests/bots/**` (`.ts`, minus specs/tests/`.d.ts`) and every local module
+they import, transitively; `message` names the root that reaches it. Each of the three makes Vite
+put `/@vite/client` on the editor page, and then the game's `full-reload` reloads the editor too.
+The scan is lexical (`src/check/editor-chain.ts`), bare packages are not followed.
+
+`--json`:
+
+```text
+{
+  "ok": true, "projectRoot": "…", "errorCount": 0, "warningCount": 2,
+  "level2": { "state": "ran", "filesHydrated": 5, "filesSkipped": 0, "filesSkippedForScripts?": 0 },
+  "files": [{ "file": "scenes/main.pix3scene", "sha256": "<hex of the raw bytes>" }],
+  "diagnostics": [{ "severity", "code", "file", "line?", "nodeId?", "path?", "message", "fix?" }],
+  "notes": [],
+  "typecheck": { "ok": true, "errors": 0, "tsconfig": ".pix3/tsconfig.check.json", "mode": "pix3-types",
+                 "files": 5, "typescript": { "version": "5.8.3", "source": "cache" } },
+  "kit": { "version": "1.6.0", "cliVersion": "1.6.0", "upToDate": true },
+  "timingsMs": { "validate": 190, "typecheck": 1180, "total": 1380 }
+}
+```
+
+`files` holds every scene validated and every script type-checked, hashed over the **raw bytes** —
+the hashes `pix3_sync`'s `expect` takes. `typecheck.errors` counts the
+`E_TYPE` / `E_TYPECHECK_UNAVAILABLE` entries of `diagnostics`.
+
+**A compile error hides level 2.** When the scripts do not compile (`E_SCRIPT_COMPILE`), level 2
+skips every scene with `user:` components — their `E_UNKNOWN_CONFIG_KEY` / `E_PROPERTY_TYPE` /
+component checks are *missing*, not passed. The report says so: `level2.filesSkippedForScripts`,
+a `SKIPPED: N scene(s) …` note, and the human summary line reads `0 scene file(s) loaded as the game loads
+them, N NOT loaded (scripts do not compile — user: components unchecked)`. Fix the compile error and run again.
+
+**Which tsconfig.** A project with its **own** root `tsconfig.json` (a Vite project — every
+`npm create pix3` starter) is checked with it, as is, against its own
+`node_modules` (`mode: "project"`); nothing is written into it. Otherwise (`mode: "pix3-types"`)
+`check` uses `.pix3/tsconfig.check.json` against the bundled types in `.pix3/types/`, and first
+(re)writes both when they are missing or from another CLI build.
+
+**Where TypeScript comes from** — it is not a dependency of `@pix3/cli`: (1) the project's own
+`node_modules/typescript` (or an ancestor's); (2) the CLI's sibling install
+(`import.meta.resolve('typescript')`, e.g. the monorepo); (3) `~/.pix3/typescript/5.8.3/`,
+installed there once with `npm install --prefix ~/.pix3/typescript/5.8.3 typescript@5.8.3 …`
+(printed before it runs). `--offline` never installs: it fails with `E_TYPECHECK_UNAVAILABLE` and
+the command. `PIX3_TYPESCRIPT=<package dir>` overrides the search. Loaded with a dynamic `import()`.
+
+Measured (the 1.x recipe-tapper-2d, 5 scripts, packed CLI installed outside the repo, fresh `HOME`):
+first `check` 2.1 s including the TypeScript install, then 1.45 s (validate ~0.2 s, tsc ~1.2 s).
+
+### SVG sprites
+
+Every texture in Pix3 (editor viewport, play mode, the single-file export) loads as bytes → `Blob`
+→ object URL → three's `TextureLoader` → `<img>`, so an `.svg` renders exactly when a browser
+`<img>` decodes it, at the size the `<img>` reports. Level 1 checks every `.svg` a scene
+references (once per file per scene, at its first reference):
+
+| Code | Severity | When |
+| --- | --- | --- |
+| `E_SVG_INVALID` | error | no `<svg>` root, or the root lacks `xmlns="http://www.w3.org/2000/svg"` (the browser refuses to decode it) |
+| `E_SVG_NO_SIZE` | error | no absolute `width`/`height` and no `viewBox` (renders into a cropped 300x150 box), or one dimension without a `viewBox` |
+| `W_SVG_VIEWBOX_ONLY` | warning | a `viewBox` but no absolute `width`/`height` (`%` and `style=` sizes count as none): Chrome gives it 300x150, art letterboxed |
+| `W_SVG_EXTERNAL_REF` | warning | an `href`, CSS `url()` or `@import` to anything but `#fragment` / `data:` — never loads in SVG-as-image mode |
+
+Measured in Chromium 129 through the runtime's own `ResourceManager` + `AssetLoader` + `Sprite2D`:
+a sized SVG auto-sizes the sprite to its `width`×`height`; a viewBox-only one to 300×150; one
+without `xmlns`, or any SVG whose Blob type is not `image/svg+xml`, fails to load (browsers do
+not sniff SVG).
+
+### `.pix3anim` frames, locale tables and keys
+
+Level 1 also follows what a scene reaches through another file. Every `.pix3anim` (all of them on
+a whole-project run, else those the validated scenes name) must be a JSON object, and every image
+it names — each frame's `texturePath`, the spritesheet's top-level one — must exist; an `.svg`
+frame gets the sprite rules above (`E_SVG_*`), reported on the `.pix3anim` with the frame's path.
+An `AnimatedSprite3D` names its frames itself (`frames:` — `res://` paths, bare paths or
+`{ url }`): each must exist (`E_MISSING_RESOURCE`, the SVG rules on an `.svg`), and an entry that
+is not a texture is `E_PROPERTY_TYPE` (a blank frame).
+The locales are the ones the plugin ships: the `localization:` block of `pix3project.yaml`, else
+every `locales/*.json` (`en` the default when there is one). Severity is what the player would
+see: the default or fallback locale's table not loading means every `labelKey` shows its key
+(error); another locale's means its texts fall back (warning). A key is looked up the way
+`LocalizationService` does — the default table, then the fallback's, `""` counting as none.
+
+| Code | Severity | When |
+| --- | --- | --- |
+| `E_ANIM_JSON` | error | a `.pix3anim` is not JSON, not an object, or its `clips` are not a list |
+| `E_MISSING_FRAME` | error | a frame image or the spritesheet a `.pix3anim` names does not exist (case hint as for `E_MISSING_RESOURCE`) |
+| `E_LOCALE_MISSING` / `W_LOCALE_MISSING` | error / warning | a declared locale has no `locales/<id>.json` (default or fallback / another); on `pix3project.yaml` at its line |
+| `E_LOCALE_JSON` / `W_LOCALE_JSON` | error / warning | the table is not JSON, not an object, or `strings` / `sprites` is not a map |
+| `E_LOCALE_VALUE` / `W_LOCALE_VALUE` | error / warning | a `strings` / `sprites` value is not a string (the runtime drops it; nested keys are the usual cause) |
+| `E_MISSING_LOCALE_SPRITE` | error | an image a table's `sprites` names does not exist — in any locale: the table wins over a node's own texture, so its keyed nodes draw nothing in that locale; an `.svg` gets `E_SVG_*`, on the table at `sprites.<key>` |
+| `E_LOCALE_KEY` | error | a `labelKey` (on a node or an instance) with no text — the node shows the key |
+| `E_LOCALE_SCRIPT_KEY` | error | a key a script passes as a string literal to `tr` / `setTextKey` / `trPlural` with no text — the game shows the key (`trPlural`: neither `<key>.other` nor `<key>`, its last two steps). Every `.ts`/`.js` of the project but specs, tests and declarations (`*.spec.ts`, `*.test.ts`, `*.d.ts` — the project-script rule's exclusions, `PROJECT_SCRIPT_EXCLUDE_PATTERN`); the same scan as the editor's Localization Scan (`scanScriptLocalizationKeys` in the runtime). A computed key — a variable, an interpolated template — is skipped |
+| `E_LOCALE_SPRITE_KEY` / `W_LOCALE_SPRITE_KEY` | error / warning | a `Sprite2D` `textureKey`, a `Button2D` `stateTextureKeys.<state>` (`texture<State>Key` on an instance) or a script's `trSprite('…')` with no `sprites` entry: an error for a `Sprite2D` with no `texture` of its own (it draws nothing), a warning otherwise (its own texture in every locale; a button keeps its skin; `trSprite` returns null) |
+
+The tables, their images and the scripts' keys are checked on whole-project runs (as
+`W_UNUSED_ASSET`); the keys a scene sets on every run. Nothing is said about keys when the project
+has no tables or the default one does not load (that is its own error).
+
+### Autoloads
+
+`pix3project.yaml` `autoloads:` is checked on every run, against the rule every host builds them
+by (the runtime's `normalizeAutoloads` / `autoloadComponentType`; the player, the editor's play
+mode and `pix3 smoke` run them): each entry needs a `singleton` and a `scriptPath`, the file must
+be a script entry under `scripts/` or `src/scripts/` exporting a `Script` class named like the
+file. A disabled entry is not checked.
+
+| Code | Severity | When |
+| --- | --- | --- |
+| `E_AUTOLOAD` | error | an autoload that would never run: no `singleton`/`scriptPath`, a repeated singleton, a script that is missing, outside the script folders, not an entry, or exporting no class named like the file (level 1, by text); at level 2, the class named like the file is not a `Script` |
+
+## `pix3 sfx` — sound effects without the editor
+
+```text
+pix3 sfx coin                                   # -> audio/coin.wav in the project root
+pix3 sfx "short high coin pickup" --out audio/pickup.wav --seed 7
+pix3 sfx explosion --json                       # { path, res, durationMs, preset, seed, modifiers, bytes, peak, params }
+```
+
+Presets: `coin`, `jump`, `hit`, `explosion`, `powerup`, `click`. Free text picks the preset whose
+keyword appears first (`boom`, `pickup`, `button`, `hurt`, …) and applies modifier words
+(`high`/`low` pitch ×1.4/×0.7, `short`/`long` time ×0.65/×1.6, `soft`). `--seed <n>` renders a
+deterministic variation (pitch ±15 %, times ±20 %, duty/vibrato/cutoff nudged); without it the
+preset as tuned. Output is 44.1 kHz 16-bit mono PCM WAV — `AssetLoader.loadAudio` decodes it with
+`decodeAudioData` like any `.ogg`/`.mp3`, and the export embeds it as `audio/wav`. `res` in the
+JSON is the `res://` path when the file lands inside a project. Exit 2 on a bad argument or a
+description that names no preset.
+
+The synth (`src/sfx/synth.ts`, no dependencies) is one jsfxr-style voice: square / saw / sine /
+triangle / noise, exponential pitch slide, pitch jump, vibrato, ADSR, resonant low-pass, DC
+blocker, peak normalisation. It does not use the editor's `@txt2sfx/*` packages: their only
+renderer drives an `OfflineAudioContext` the caller supplies, i.e. a native Web Audio module
+(`node-web-audio-api`) in Node. Each preset renders in well under 10 ms; the whole command runs in
+~0.12 s; files are 2–67 KiB (click 24 ms … explosion 772 ms).
+
+## `pix3 character-compile` — a 2D character from frame PNGs
+
+```text
+pix3 character-compile art/goblin.yaml            # writes into the project around the cwd
+pix3 character-compile art/goblin.yaml --dry-run  # the plan, nothing written
+pix3 character-compile art/goblin.yaml --json     # { ok, name, slug, animationPath, prefabPath, clips, files, warnings }
+```
+
+The 1.x Store compiler (`character2d`, `pix3: src/services/library/character-compiler.ts`) as a
+command. A spec (YAML or JSON; frame paths relative to the spec file) groups PNG frames into
+`variant × state` clips:
+
+```yaml
+name: Goblin                     # display name, prefab file name
+slug: goblin                     # sprite folder (default: from name)
+anchor: { x: 0.5, y: 0.9 }       # frame anchor, y from the top: the feet land on the node position
+defaultVariant: sword            # the pair the prefab starts on (default: the first clip's)
+defaultState: idle
+clips:
+  - { variant: sword, state: idle, fps: 10, frames: [sword/idle_1.png, sword/idle_2.png] }
+  - { variant: sword, state: attack, fps: 15, sequence: sword/attack }  # sword/attack_<n>.png, numeric order
+  - { state: die, sequence: die/die }                                   # no variant: clip "die"
+```
+
+Output, in the managed-sprite-folder layout:
+`sprites/<slug>/<slug>.pix3anim` (clips `<variant>.<state>`, every frame with `texturePath`,
+`anchor`, `sourceSize`), the frames copied beside it as `<variant>_<state>_<nnnn>.png`, and
+`scenes/prefabs/<Name>.pix3scene` — an `AnimatedSprite2D` root (`sizeMode: native`) carrying
+`core:CharacterVisual2D` (`variant`, `state`, `separator`); game code calls
+`playState('attack', { restart: true })` / `setVariant('bow')`. `spriteDirectory` /
+`prefabDirectory` / `separator` override the defaults. Defaults are proposals and print as
+warnings (fps 12; `loop: false` for `attack`, `die`, `death`, `hit`, `hurt`); a sequence with gaps
+warns, one with a duplicate number fails. Writes are all or nothing: a target that exists with
+other bytes is refused (exit 1, nothing written) unless `--force`; identical bytes are `current`.
+Frames must be PNG (the size comes from the header; the Node-runnable CLI does not load the
+engine's image reader). Exit 0 = written or current, 1 = refused, 2 = usage / no project.
+
+`src/character/character.spec.ts` holds the output to the runtime (`normalizeAnimationResource` of
+the written `.pix3anim` is the identity; the compiler's types are assignable to
+`AnimationResource`), to the managed folder's frame naming (`<clip>_<nnnn>.png`), and to
+`pix3 validate` on a starter that instances the prefab; `character.headless.spec.ts` boots the
+prefab through the real loader and drives idle → attack → restart → die → variant switch. The
+format itself: the kit's `.claude/skills/pix3-scene-format/pix3anim.md`.
+
+## `pix3 smoke` — run the game headless
+
+`pix3 smoke [scene]` runs the game in Node — no browser, no editor, no dev server — for
+`--frames N` fixed steps of 1/60 s (default 120) and reports everything that went wrong. It is the
+behavioural check after `pix3 check` when no editor is connected; with the editor open,
+`pix3_game_run` is the stronger one (it renders).
+
+What runs: the project's scripts compiled with esbuild (as `validate` level 2 does, but bare
+imports are bundled for real from the project's `node_modules` — Rapier, three addons — and only
+what resolves nowhere becomes an empty module, reported as `W_SMOKE_STUBBED_IMPORT`), the scene
+loaded from disk by the real `SceneLoader`, a real `SceneRunner` in manual time. Frame 0 is loading
+and starting the scene (`onAttach`/`onStart`, then 128 event-loop turns so spawn chains land);
+frame N is the N-th step. The run happens in a worker thread, so a script stuck in a loop is
+stopped by `--timeout` (default 20 s).
+
+Stubbed: rendering (a null renderer; post-processing never loads), audio (no Web Audio in Node),
+input (no events), network (`scene.network` is null). Textures resolve empty, glTF models and
+Spine skeletons referenced by nodes are not built; images a script loads through three's
+`TextureLoader` "load" as blank 1×1 pictures (so preloaders finish). A small browser shim provides
+`window` / `document` / canvas / `localStorage` / `matchMedia` / `requestAnimationFrame`; any other
+browser property a script reads is recorded, and an error right after such a read is
+`E_SMOKE_DOM` with the read attached (`domAccess`).
+
+Scene: the argument (`res://`, project-relative or a path) runs that one scene. With no argument
+several run, one after another from one bundle, a line each (`src/smoke/select-scenes.ts`):
+
+1. In a git work tree with uncommitted changes (staged, unstaged or untracked): the **top-level**
+   scenes those changes reach — the scene itself, a prefab / `scenes/ui/` overlay it instances, a
+   script exporting a class it attaches as `user:X`, a `res://` file it names. `--changed` forces
+   this (exit 2 without git or without changes). Changes under `node_modules/`, `.yalc/` (a linked
+   package copy), `.git/`, `.pix3/`, `dist/`, `.vite/`, `.cache/` are not project changes and are
+   ignored, and a `*.spec.ts` / `*.test.ts` next to the scripts is not game code — a consumer
+   project's `.yalc/@pix3/runtime/**` and its unit tests used to read as hundreds of changed
+   scripts that reach no scene and widen every run to everything.
+2. Otherwise — no git, nothing changed, a changed scene/script that reaches no top-level scene (a
+   helper module, an unused prefab), or a changed `pix3project.yaml` — **every** top-level scene
+   (not instanced by another, not under `prefabs/` / `ui/`, not a `.prefab` — those are only
+   instanced, and a whole-project `pix3 validate` checks them as prefabs),
+   `scenes/main.pix3scene` first (where the starters and the 1.x recipes put the game), then
+   `defaultExportScenePath`, then by path.
+   `--all` forces this.
+
+It never picks `defaultExportScenePath` alone any more: in every 1.x recipe that is the menu, input is
+empty, PLAY is never pressed, and a game whose `onStart` throws used to smoke green.
+
+| Code | |
+| --- | --- |
+| `E_SMOKE_SCRIPT` | A script hook threw (`onAttach`/`onStart`/`onUpdate`…); the engine disabled that component |
+| `E_SMOKE_DOM` | …and it was a browser API the shim does not provide (`domAccess` names it) |
+| `E_SMOKE_TICK` / `E_SMOKE_COMMAND` | The engine tick / a game command handler threw |
+| `E_SMOKE_CONSOLE_ERROR` | `console.error` (not the engine re-reporting one of the above) |
+| `E_SMOKE_UNHANDLED` | An unhandled promise rejection, or a timer callback that threw |
+| `E_SMOKE_LOAD` | The scene failed to load (missing prefab, invalid scene) |
+| `E_SMOKE_SCRIPT_COMPILE` / `E_SMOKE_SCRIPT_IMPORT` | Scripts do not compile / throw at module top level |
+| `W_SMOKE_MISSING_RESOURCE` | A `res://` file does not exist (the node loads without it) |
+| `W_SMOKE_PENDING_COMPONENT` | A component type is not registered — it never runs |
+| `W_SMOKE_CONSOLE_WARN`, `W_SMOKE_LOADER`, `W_SMOKE_STUBBED_IMPORT`, `W_SMOKE_STOPPED` | `console.warn`, loader warnings, an import replaced by `{}`, the game stopped itself |
+
+Exit 0 = no errors (warnings allowed), 1 = errors, 2 = could not run (with several scenes, the
+worst run decides): `E_SMOKE_NO_PROJECT`,
+`E_SMOKE_NO_SCENE`, `E_SMOKE_BUNDLE`, `E_SMOKE_UNSUPPORTED` (no esbuild), `E_SMOKE_TIMEOUT`,
+`E_SMOKE_CRASH`, `E_EDITOR_UNSYNCED` (a live editor named by `.pix3/dev.json` did not flush its
+unsaved scenes first; `--no-sync` reads the disk as it is), `E_RUNTIME_VERSION` (the version gate:
+the project installs another `@pix3/runtime` than the one bundled into this CLI, so a run would
+test an engine the game does not ship). The human report prints the `game` snapshot whole — on one line when it is short, pretty-printed
+and indented otherwise, cut only past 4 000 characters (`--json` always carries it whole).
+`--json` prints `{ ok, scene, frames, framesRequested, firstFrameOk, errors:
+[{ code, frame, script?, nodeId?, nodeName?, phase?, message, stack?, domAccess? }], warnings,
+nodes: { start, end }, timingsMs: { compile, load, firstFrame, step: { total, mean, p95, max },
+total }, scripts, domMissing, notes, game, logs }` — `game` is the `registerGameDebug` provider's
+`snapshot()` at the end (when the game registers one), `logs` the first `console.log` lines,
+frame-stamped. Stacks are source-mapped to the project's files. With no scene argument `--json`
+prints `{ ok, selection: "changed" | "all", reason, changed?, runs: [<that report, per scene>] }`.
+
+A green smoke run means nothing threw for N frames without input. It does not mean the game
+plays: nothing was tapped, nothing was drawn.
+
+## `pix3 tree` — find your way around a scene
+
+`pix3 tree <scene>` prints one line per node, indented by depth, from the YAML alone (no loader,
+no project code — instant):
+
+```text
+scenes/main.pix3scene — 12 nodes
+Group2D#game-root "Game Root" size=1080x1920 layout=stretch/stretch  components=[user:GameRules, user:TouchRules]
+  CanvasLayer2D#hud "HUD" size=1080x1920 layout=stretch/stretch  components=[user:ScoreHud]
+    Label2D#score-label "Score Label" text="SCORE 0" pos=(-340,850) layout=left/top
+    Group2D#result-overlay "Result Overlay" ↳ instance res://scenes/ui/result.pix3scene (1 property) hidden
+```
+
+`--depth N` stops N levels below the roots (cut subtrees end in `… +K below`); `--types A,B` keeps
+nodes of those types (or carrying those components; `instance` = prefab instances) with their
+ancestors as `·` context lines; `--props` adds, under each node, the properties that differ from
+the node type's defaults (read from a bare instance of the runtime class, through the disk-format
+table — the one step that loads the runtime bundle); `--json` gives the same as nested
+`{ id, type, name, depth, position?, size?, layout?, margins?, resolved?, hidden?, text?, groups?,
+components, instance?: { path, rootType?, rootName?, overrides, properties }, props?, children }`.
+On an instance
+`overrides` counts every `overrides.byLocalId.*.properties` key (edits to nodes inside the prefab)
+and `properties` the instance node's own `properties` keys (applied to the prefab root); the line
+prints `(2 overrides, 1 property)`, or `(no overrides)` when both are 0.
+
+A node anchored in the margin form (W21: `layout: { enabled, horizontalAlign, verticalAlign,
+left?, right?, top?, bottom? }`, every side the alignment keeps written) holds `0` in the file for
+the position component of an anchored axis and no `width`/`height` for a stretched one — the
+margins are the rect. The line shows the margins beside the layout and, as `pos` / `size`, the
+rect they give at the design size (the parent's size; `viewportBaseSize` for a root), the way
+`Node2D`'s layout pass computes it; `?` where the file does not say enough (a parent or the node
+without a size in the file):
+
+```text
+Group2D#hud size=1080x1920 layout=stretch/stretch(left=0,right=0,top=0,bottom=0)
+  Group2D#bar pos=(0,-920) size=1000x40 layout=stretch/bottom(left=40,right=40,bottom=20)
+    Group2D#knob pos=(480,5) size=20x20 layout=right/none(right=10)
+  Sprite2D#unsized pos=(?,70) layout=left/none(left=10)
+```
+
+`--json` keeps `position` / `size` as the file has them and adds `margins` and
+`resolved: { position: [x, y], size: [w, h] }` (`null` for `?`). A pre-W21 anchor (no margins in
+the file) prints its file position as before.
+
+`pix3 tree` with no scene is the project overview: manifest facts, the `user:` scripts, and every
+scene/prefab/overlay with its node count, node types, components and instances (entry scene
+marked `*`). Exit 0, 1 when a scene does not parse, 2 for bad arguments or a missing file.
+
+## `pix3 kit` — the agent kit
+
+`pix3 kit` installs the agent kit into an existing project (one made without it, or after a CLI
+upgrade); `pix3 new` runs the same step. What lands in the project:
+
+| Path | What |
+| --- | --- |
+| `AGENTS.md` | Root rules (read by Codex, Cursor, …). If the project already has its own, it is kept and the kit goes to `AGENTS.pix3.md` (the command prints the line to add). |
+| `CLAUDE.md` | `@AGENTS.md` (plus `@AGENTS.pix3.md` in that case). A `CLAUDE.md` of the project's own is never touched — the command prints the line to add. |
+| `.claude/skills/pix3-{scene-format,nodes,scripts,verify,editor}/SKILL.md` + `reference.md` | Skills loaded on demand; the `reference.md` files are generated from `docs/` and the runtime's registry; `pix3-scene-format/pix3anim.md` is the `.pix3anim` format |
+| `design/tests/bots/pix3-test-bot.d.ts` | Global types for bot policies (`Pix3TestBot`, `BotPolicy`, …): a policy is `export default { name, tick(bot) { … } } satisfies BotPolicy`, and the starter's `tsconfig.json` includes `design/tests`, so `pix3 check` type-checks it. The editor writes no project files; this is where the 1.x editor-written declaration went |
+| `.gitignore` | `.pix3/*` with `!.pix3/kit-manifest.json` and `!.pix3/template.json` appended when no line ignores `.pix3` yet; existing content kept |
+| `tsconfig.json`, `.pix3/tsconfig.check.json`, `.pix3/types/` | Only without a `tsconfig.json` of the project's own (see below) |
+| `pix3project.yaml` | `metadata.agentKit: { version, files }` (everything else as written) |
+| `.pix3/kit-manifest.json` | sha256 of every file the kit wrote |
+
+Without `--update`, existing files are never replaced (missing ones are written; an unchanged file
+from an older kit is reported `outdated`). `--update` replaces every kit file whose bytes still
+match the hash in `.pix3/kit-manifest.json` and **skips** (and reports) every file edited since.
+The starters ignore `.pix3/*` but not `.pix3/kit-manifest.json` (nor `.pix3/template.json`), so a
+clone keeps the manifest. A project whose `.gitignore` ignores all of `.pix3/` (an older starter, or by
+hand) loses it on a fresh clone, and every differing kit file then counts as
+edited — replace that line with the three of the starter.
+
+**Generated, not copied.** `scripts/build-kit.mjs` (run at `prepack`; a repo checkout regenerates
+`kit/` automatically whenever an input changed) expands the templates in `kit-src/`: hand-written
+prose plus `{{include:<repo path>#<heading>}}` / `{{include:<repo path>@<paragraph>}}` directives
+over `docs/pix3-specification.md`, `docs/node-types-reference.md`, `docs/nodes-and-systems.md`,
+`packages/cli/kit-includes/engine-api-map.md` and this README, and `{{generated:…}}` blocks
+computed from code (the `core:` component table from the runtime's registry). Syntax:
+`src/kit/generate.ts`. `src/kit.spec.ts` builds the kit and fails on drift: an unresolved
+directive, a `pix3` command or flag not in the usage text, an `npm run` script the starter does
+not have, a `pix3_*` tool, parameter or sync reason the bridge (`bridge-tools.ts`) does not have, a
+retired 1.x in-editor tool, a verdict phrase `GameTestService` does not produce, a diagnostic code
+no command emits, a node type the loader does not know, a property in the nodes skill's tables
+that the disk-format descriptor (`packages/runtime/src/core/scene-disk-format.ts`) does not
+accept, a `core:` component that does not exist, and a `.pix3anim` reference (`pix3anim.md`)
+whose interfaces, fields, optionality, types or "Omitted →" defaults differ from
+`packages/runtime/src/core/AnimationResource.ts` and `normalizeAnimationResource`, and bot-policy
+types missing a member of `Pix3TestBot` / `BotPolicy` / `BotNodeView`
+(`packages/editor-core/src/services/game-test/game-bots.ts`).
+
+### `pix3 kit --migrate` — a 1.x project's kit to 2.x
+
+Plan §A.4 step 2. It migrates **the kit only** (`src/kit/migrate.ts`), and reports every change:
+
+| What | How |
+| --- | --- |
+| `.mcp.json` | the 1.x `pix3 mcp --workspace` server (`npx -y @pix3/cli@1.x mcp …`, or the dev `node …/packages/cli/src/index.ts mcp`) is removed; other servers stay; a file left empty is deleted |
+| Retired kit files | files in `.pix3/kit-manifest.json` that the 2.x kit no longer ships: deleted when unchanged, kept and reported when edited |
+| `pix3project.yaml` | `metadata.pix3Hybrid` (the 1.x cloud link) removed, its value printed; `metadata.agentKit` rewritten |
+| The kit | installed with `--update` semantics: unchanged 1.x kit files replaced, edited ones kept; an edited one that still mentions `pix3 mcp` / `pix3 serve` / `pix3 read` / the live channel / the in-editor tools is flagged `STILL 1.x` and the 2.x text written to `.pix3/kit-migrate/<path>` for a manual merge |
+
+Never touched: anything outside the project (`~/.codex/config.toml` — the report says to delete a
+1.x `[mcp_servers.pix3]` table), a project `.codex/config.toml` (reported when it runs `pix3 mcp`),
+the project's own `AGENTS.md` / `CLAUDE.md` (an edited copy of the 1.x kit's `AGENTS.md` is
+reported), scenes, scripts, assets, `package.json`, `vite.config.*`. The 2.x agent config is
+`pix3 agent-setup`'s (the report says to run it). Moving a 1.x project onto Vite (`pix3()` in
+`vite.config`, plan §A.4 step 3) is optional and by hand; the report notes a project without
+`@pix3/vite-plugin`. A second run finds nothing to migrate. Spec: `src/kit/migrate.spec.ts`
+(a 1.x-shaped starter, edits kept, idempotence, a copy of `../DeepCore` when present).
+
+### Script types (`.pix3/types/`)
+
+`scripts/build-runtime-types.mjs` (at `prepack`; rebuilt on demand in a checkout when the runtime
+sources change) runs `tsc -p packages/runtime/tsconfig.types.json` (declarations of what
+`src/index.ts` reaches — no specs, samples or `testing/`) into `runtime-types/@pix3/runtime/`, and
+copies `@types/three` (without its `node_modules`) to `runtime-types/@types/three/` — the runtime's
+public types extend three.js. The tarball carries that tree packed into one file,
+`dist/runtime-types.json` (see "Package layout" below); the installed CLI expands it on first use. `lit` (re-exported `property`/`state` decorators), `postprocessing`
+and the Spine runtime are not shipped: they are only reached from inside declaration files, which
+`skipLibCheck` leaves alone (they type as `any`). In a project without its own `tsconfig.json`:
+
+```text
+.pix3/types/@pix3/runtime/**      the runtime's .d.ts (+ package.json with the version)
+.pix3/types/@types/three/**       three.js types
+.pix3/types/version.json          which CLI build wrote them
+.pix3/tsconfig.check.json         paths → ./types/…, strict, noEmit, skipLibCheck, lib ES2022 + DOM,
+                                  include ../scripts/**/*.ts and ../src/scripts/**/*.ts
+tsconfig.json                     { "extends": "./.pix3/tsconfig.check.json" } — so an IDE sees them
+```
+
+## `pix3 gap` — what the agent had to work around
+
+Plan §G.3 «Чего не хватает?», §G.4. `pix3 gap "<what was missing>" --kind
+capability|tool|node|doc|other [--detail <text>] [--context <file or task>] [--agent <name>]`
+appends one line to the project's `.pix3/gaps.jsonl`:
+
+```json
+{"ts":"2026-10-10T12:00:00.000Z","agent":"claude-code","kind":"node","summary":"no 9-slice panel node","detail":"built from 9 Sprite2D","context":"scenes/ui/shop.pix3scene"}
+```
+
+`agent` comes from `--agent`, else the environment (`CLAUDECODE=1` → `claude-code`, a `CODEX_*`
+variable → `codex`), else it is left out; the summary is one line of ≤200 characters. One
+`O_APPEND` write per record, so two agents never interleave. `pix3 gap --list [--json]` prints
+them. The kit's `AGENTS.md` tells the agent to record a gap only after it worked around
+something Pix3 lacks — not its own mistakes or the game's features. A CLI command rather than a
+bridge tool: it needs no editor, and on a Remote SSH host it runs where the project is. `.pix3/`
+is gitignored in the starters: the file stays with the checkout.
+
+## `pix3 editor` — the editor in Chrome, for the agent
+
+Plan §D.3 / §D.4 / §D.5. Idempotent; run it from the project (or `--project <dir>`):
+
+1. **Dev server.** `.pix3/dev.json` (written by `@pix3/vite-plugin` while Vite listens: `url`,
+   `editorUrl`, `port`, `pid`) is probed with `GET <url>__pix3/api/hello`. A live server is
+   reused; a stale record is ignored and `node_modules/vite/bin/vite.js` is started **detached**
+   (`process.execPath`, `cwd` = the project, output in `.pix3/dev.log`), and the command waits
+   up to 15 s for the new `dev.json`. `--port <n>` passes `--port --strictPort` to Vite.
+   `--stop` sends SIGTERM to the recorded pid (and drops a record whose process is gone).
+2. **Chrome, owned.** `PIX3_CHROME` names the binary (a wrapper script works if it `exec`s
+   Chrome: the pipe is fds 3 and 4), else the platform's usual place (`google-chrome` /
+   `chromium` on the PATH, `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`,
+   `%ProgramFiles%\Google\Chrome\Application\chrome.exe`). `pix3 editor` starts a **detached
+   Chrome owner** (`pix3 __chrome-owner`, log in `~/.pix3/chrome-owner.log`) and returns once its
+   proxy answers; the owner launches Chrome with `--app=<editorUrl>
+   --user-data-dir=~/.pix3/chrome --remote-debugging-pipe` — **no debugging port** — no first run,
+   no default-browser check, background throttling off (`--disable-background-timer-throttling
+   --disable-renderer-backgrounding --disable-backgrounding-occluded-windows`). The owner lives
+   exactly as long as Chrome: Chrome gone → the owner closes every client, removes
+   `~/.pix3/chrome.json` and exits; the owner gone (killed) → the pipe closes and Chrome exits
+   with it. `--stop-chrome` asks the owner to close Chrome. Then, launched or reused, the editor
+   tab is checked in the proxy's `/json/list` and, when it is not there, opened through the proxy
+   (`Target.createTarget`: a new window, a tab in a headless Chrome) and checked again — a binary
+   that ignores `--app` (`PIX3_CHROME` pointing at a `chrome-headless-shell`) still gets its tab,
+   and `pix3 editor` fails rather than print success without one. A second project gets its tab
+   the same way: the profile is never launched a second time (a headless one would start a
+   second Chrome that nobody owns and `--stop-chrome` would not end). `--headless` opens the URL
+   as a plain tab with `--headless=new` (headless Chrome ignores `--app`). `--no-chrome` stops after the server;
+   under `SSH_CONNECTION` Chrome is not launched — see [Remote SSH](#remote-ssh--vs-code-on-a-remote-host-chrome-on-your-machine).
+3. **The token proxy (9333).** The owner serves `ws://127.0.0.1:9333/pix3` (the browser target;
+   `…/pix3/page/<targetId>` for one page) and `GET /json/version`, `/json/list` (`/json`) on
+   loopback. Every request needs `Authorization: Bearer <token>`, the token of
+   `~/.pix3/cdp-token` (32 random bytes, base64url, mode 0600, created once by whichever command
+   needs it first; delete the file to rotate, then `agent-setup --repair` and a new Chrome);
+   a request with an `Origin` (any web page) or a non-loopback `Host` is refused (403), a
+   missing or wrong token is 401 — a WebSocket is refused before the upgrade. Several clients
+   share the pipe (chrome-devtools-mcp, a harness, `pix3 editor` itself): each gets its own root
+   session (`Target.attachToBrowserTarget`, or `attachToTarget {flatten}` for a page), message
+   ids are remapped per client, events go only to the client owning their session, another
+   client's session is "not found", a client that leaves is detached with its child sessions.
+4. **The port.** The check sends `X-Pix3-Challenge` and **no token**: a proxy answering with the
+   proof that it knows our token (`X-Pix3-Proof`, the HMAC of [Remote SSH](#remote-ssh--vs-code-on-a-remote-host-chrome-on-your-machine))
+   = ours → reused (only then is it asked, with the token, for its tabs; when the editor tab is
+   open there, nothing is launched). A proxy without that proof (another user's, another
+   `PIX3_HOME`, a squatter), a foreign DevTools endpoint or any other listener — none of which
+   ever sees the token — → the next of 9334–9339, with a line per skipped port, the chosen one
+   recorded in `~/.pix3/chrome.json`, and the reminder to run `pix3 agent-setup --repair` (a
+   running Codex / Claude Code session keeps the old endpoint: new thread). A plain DevTools port
+   with a `/__pix3/` page (or on the recorded port) is the P1 launch (open port, no token): it
+   holds the profile, so `pix3 editor` stops and says to close that Chrome. When the port is the
+   usual one but the project's `.mcp.json` / `.codex/config.toml` entry is not the current launch
+   (an older one — `--wsHeaders` with the token on its command line, `--browserUrl`), or the
+   `~/.pix3/cdp-mcp.json` it names holds another port or token, it says to run
+   `pix3 agent-setup --repair`. `--cdp-port <n>` moves the preferred port
+   (test harnesses). `PIX3_HOME` relocates `~/.pix3`.
+
+Keepalive is the editor's: every bridge call keeps its loops running for 60 s, agent play until
+it stops (`AgentKeepaliveService`); the Chrome flags above keep Chrome from throttling the tab.
+
+## `pix3 agent-setup` — chrome-devtools-mcp for Codex and Claude Code
+
+Plan §D.6. Writes project-level config, idempotently:
+
+- Claude Code — `.mcp.json`, `mcpServers["pix3-browser"]`, other servers kept;
+- Codex — `.codex/config.toml`, the `[mcp_servers.pix3-browser]` table (`startup_timeout_sec =
+  20`, `tool_timeout_sec = 300`: `pix3_game_run` outlives the 60 s default), replaced as a whole,
+  every other byte of the file kept.
+
+The entry is `npx -y chrome-devtools-mcp@1.10.1 --categoryExperimentalThirdParty=true
+--experimentalVision=true --config=<~/.pix3/cdp-mcp.json>` (`cmd /c npx …` on Windows;
+`experimentalVision` enables `click_at {x, y}`, the agent's input at the coordinates
+`pix3_scene` returns as `screen`). `~/.pix3/cdp-mcp.json` (mode 0600, written by this command,
+rewritten whenever the port or the token moves) holds `wsEndpoint` = `ws://127.0.0.1:<port>/pix3`
+and `wsHeaders` = `{"Authorization":"Bearer <token>"}`: 1.10.1's `--config` reads a JSON object
+with the flags' own options and coercions (`build/src/config/mcp-options.js`; `wsEndpoint` /
+`wsHeaders` in `build/src/config/browser-options.js`, `wsHeaders` parsed as a JSON object); with
+`wsEndpoint` puppeteer connects to that WebSocket only, sending the headers on the upgrade, and
+makes no `/json/*` request. So **the token is in no project file and on no command line** (every
+user of a box can read every process's command line). The version is **pinned**:
+the third-party tool category is experimental and may move in a minor release, so it changes
+only after the S4 transport run is repeated (`CHROME_DEVTOOLS_MCP_VERSION` in
+`src/agent-setup/config.ts`); the inline fallback (`window.__PIX3_DEBUG__.call`) works on any
+version. The port is `--cdp-port`, else what `~/.pix3/chrome.json` recorded, else 9333; the token
+is `~/.pix3/cdp-token` (created here if `pix3 editor` has not run yet). `--remote` is the same
+shape for an agent on a Remote SSH host, with `~/.pix3/remote-cdp.json` (see Remote SSH below).
+
+The project files name a path in this machine's home, so the starters' `.gitignore` keeps
+listing `.mcp.json` and `.codex/config.toml`. An entry that already matches is `up to date`; one
+that differs (another version or config file, the P1 `--browserUrl` launch or the earlier
+`--wsEndpoint` + `--wsHeaders` launch that carried the token, each named as such) is reported as
+drift and exit 1 — `--repair` rewrites it after copying the file to `<file>.bak` (the `.bak` of a
+`--wsHeaders` entry still holds the token: delete it); that is the migration of a P1 or an early
+P2 project.
+Nothing is done to a sandbox: Codex must be allowed to reach `127.0.0.1` once when it asks.
+The alternative for every project at once is printed (`claude mcp add --scope user …`, or the
+table in `~/.codex/config.toml`).
+
+**The proxy (plan §D.5).** Chrome opens no debugging port; the only way in is the proxy with the
+token, so another local user, a web page or a process that cannot read `~/.pix3/cdp-token`
+cannot drive the editor's Chrome (checked: `../pix3-core-spikes/editor-e2e/gate-p2.mjs`). Same-user
+processes can read the token file — the boundary is the user account, as for any file in the
+home directory. Chrome on macOS / Windows is untested (`.plans/agent-bridge.md` debt).
+
+## Remote SSH — VS Code on a remote host, Chrome on your machine
+
+Plan §E.3. You work in VS Code connected to a Linux box over **Remote SSH**: the project, Vite and
+the coding agent (Claude Code, Codex) run there; the browser runs on your machine. The editor
+reaches your browser through VS Code's port forward; the agent reaches that browser through an SSH
+`RemoteForward` of the CDP token proxy, back onto the remote host's loopback.
+
+1. **On the remote host** (VS Code's terminal, in the project): `npm run editor`. Under
+   `SSH_CONNECTION` it starts (or reuses) the dev server, launches no Chrome, and prints what to
+   do on your machine — with the one remote port this host uses for the forward (9333, or
+   `--cdp-port <n>`, which it stores):
+
+   ```text
+   On your machine, once — ~/.ssh/config, under the Host you connect to, then reconnect:
+       RemoteForward 127.0.0.1:9333 127.0.0.1:9333
+       ExitOnForwardFailure yes
+   On your machine, each session — VS Code forwards port 5173 (its Ports tab shows the local address):
+       npx @pix3/cli@<version> editor --chrome-only --url http://localhost:5173/__pix3/ --remote-port 9333
+   ```
+
+   VS Code forwards the dev server's port by itself (it sees the URL in the terminal; the Ports
+   tab lists it). When the local port is not the same (5173 was taken on your machine), use the
+   local address in `--url`.
+2. **On your machine, once:** add the two lines to `~/.ssh/config` under that `Host`, close the
+   remote window and connect again. The first port is the one on the remote host — one port,
+   configured on both sides, never "the next free one": if another user of that host holds it,
+   the forward must fail visibly (`pix3 editor` there says the port is held; pick another with
+   `--cdp-port <n>` there, the same `<n>` in `RemoteForward` and in `--remote-port`); the second
+   is your proxy (9333 unless `pix3 editor` said it had to use another). `ExitOnForwardFailure
+   yes` is not optional: without it a connection whose forward failed — because someone else on
+   the remote host took the port — comes up anyway, and the agent would hand its token to
+   whoever holds the port.
+3. **On your machine, each session:** the `npx @pix3/cli … editor --chrome-only --url …` line.
+   No project needed there: it checks that the URL answers as a Pix3 editor, starts Chrome behind
+   the token proxy (as `pix3 editor` always does), opens the editor, and records `--remote-port`
+   (default 9333) in `~/.pix3/cdp-forward-ports.json`: the proxy proves its token for the ports
+   listed there and for its own, nothing else. It then prints one line
+   that copies its token to the remote host (`--ssh <host>` fills the host in):
+
+   ```text
+   ssh <host> 'umask 077 && mkdir -p ~/.pix3 && cat > ~/.pix3/remote-cdp-token' < ~/.pix3/cdp-token
+   ```
+
+   Run it once (again only after the token changes). The token goes from your token file through
+   the SSH channel into a 0600 file on the remote host: it is never printed, typed, pasted or put
+   on a command line.
+4. **On the remote host, once:** `npx pix3 agent-setup --remote`, then a new agent thread. It
+   asks the configured port (the one `pix3 editor` stored, or `--cdp-port <n>`) for **proof**
+   that it knows the token (`X-Pix3-Challenge` + `X-Pix3-Proof-Scope: forward` → `X-Pix3-Proof`,
+   an HMAC the proxy computes over the challenge **and the port the client dialled**; the token
+   itself is never sent to a port that has not proven it), writes `~/.pix3/remote-cdp.json`
+   (0600: the endpoint `ws://127.0.0.1:<port>/pix3` and the token, read by chrome-devtools-mcp's
+   `--config`), and the project's `.mcp.json` / `.codex/config.toml` entry `npx -y
+   chrome-devtools-mcp@1.10.1 … --config=<that file>`, which holds no secret. Something on the
+   port that cannot give the proof gets nothing written (exit 1: a squatter waiting for the
+   token, or your proxy not told the port — `--remote-port`); a port nothing answers on yet is
+   written with a warning. Bound to the port, a proof cannot be relayed: a squatter on 9333 that
+   passes the challenge to your real forward on 9334 gets an answer for 9334, which the agent's
+   side rejects.
+   `npm run editor` on the remote host says whether the forward is live (`CDP forward: live on
+   127.0.0.1:9333`).
+
+The agent finds its tab by `.pix3/dev.json`: `publicEditorUrl` is the address your browser
+reached the dev server at — learnt from the editor tab's `Origin` when it differs from the
+server's own (a port forward that is not 1:1), or set with `PIX3_PUBLIC_URL=http://localhost:5174`
+in the environment of the dev server; absent, `editorUrl` is the address.
+
+Why it is safe on a shared host: the remote host's loopback is reachable by every user of it, and
+so is the forwarded port — that is what the token is for (no token → 401). On the remote host the
+token lives only in two 0600 files of your home; not in the project, not in any process's command
+line (readable by every user of a host), not in any output. What the token does not protect: a
+process of your own account on the remote host can read it (the same boundary as on your
+machine), and the dev server itself (`/__pix3/api/*` reads and writes the project) answers any
+local user of the remote host, as every Vite dev server does. To rotate: delete
+`~/.pix3/cdp-token` on your machine, `pix3 editor --stop-chrome`, run the `--chrome-only` line and
+the copy line again, then `npx pix3 agent-setup --remote` and a new thread. Untested: a Windows
+or macOS machine on the human side (the `type … | ssh` line is cmd's and PowerShell's).
+
+## The editor bridge — what the tab exposes
+
+`packages/editor-core/src/host/bridge-tools.ts` is the tool table (names, descriptions, JSON
+Schemas), `debug-bridge.ts` the one implementation behind two transports: the page answers
+chrome-devtools-mcp's `devtoolstooldiscovery` with the `pix3` group
+(`list_3p_developer_tools` / `execute_3p_developer_tool {toolName, params: "<JSON>"}`), and
+`window.__PIX3_DEBUG__.call(name, params)` is the same call from `evaluate_script`
+(`waitForStableDom: false`). Tools: `pix3_status`, `pix3_sync` (`{expect?, timeoutMs?}` →
+flush, rescan, barrier), `pix3_scene` (`{path?, maxDepth?, nodeId?, find?}`), `pix3_play`
+(`{action: start|stop|restart|pause|status, scenePath?, force?}` — the designer's session is
+refused with `not_owner`, `force` included), `pix3_game_run` (`GameTestService.run`),
+`pix3_screenshot` (`{target: game|viewport}` prepares the view; the picture is
+`take_screenshot`), `pix3_errors` (`{since?, clear?}`). Params are validated on both paths;
+every refusal is `{ok:false, reason, detail}`. `pix3 check`, `pix3 smoke` and `vite build`
+flush the editor through `POST /__pix3/api/flush` (the CLI side is `src/editor-sync.ts`),
+without the bridge. The kit's `pix3-editor` skill is held to the table by `src/kit.spec.ts`.
+
+## Package layout and publishing
+
+The published package has **no runtime `dependencies`**, so a cold `npx -y @pix3/cli@X.Y.Z …`
+fetches one tarball and installs nothing else (measured in
+`.plans/measurements/external-agent-phase0-cold-start.md`). `prepack` builds:
+
+```text
+dist/index.js               the bin: src/index.ts + yaml, one minified ESM file
+                            (scripts/build-bin.mjs); lazy commands stay lazy
+dist/validate/prebuilt/     validate + @pix3/runtime + three (scripts/build-validate.mjs)
+dist/smoke/prebuilt/        smoke worker + tree defaults + @pix3/runtime + three (scripts/build-smoke.mjs)
+dist/runtime-types.json     runtime-types/ packed into one file (scripts/build-runtime-types.mjs):
+                            ~1 100 small .d.ts cost npm over a second to unpack on every npx run
+kit/                        the agent kit (scripts/build-kit.mjs)
+templates/                  copy of packages/create-pix3/templates (scripts/copy-templates.mjs; removed at postpack)
+```
+
+Left out of the bin on purpose: Node built-ins; `esbuild` (an `optionalDependency` — level 2 of
+`validate`, `smoke` and `check` resolve it from the bin with `import.meta.resolve`, and degrade
+with a note when it is absent) and `typescript` (fetched on demand by `check`); and the
+checkout-only modules (`validate/bundle.ts`,
+`smoke/bundle.ts`, the kit generator), which become a throwing stub. Every file the CLI reads from
+its own package is addressed from the package root (`src/package-root.ts`), never relative to the
+current module — in the bundle every module's `import.meta.url` is the bin's. The sources (`node
+src/index.ts`, the specs) never use a prebuilt bundle, even when an old `dist/` exists.
+`src/bin-bundle.spec.ts` builds the bin into a temp package layout and checks `--version` against
+`package.json` (and that against the lockstep root version), the pinned `chrome-devtools-mcp`
+launch `agent-setup` writes, and that nothing but built-ins and the optional externals is
+imported at run time.
+
+Publishing is `.github/workflows/publish-packages.yml` (npm Trusted Publishing / OIDC, no token):
+a `runtime-vX.Y.Z` tag publishes `@pix3/runtime` and `@pix3/cli` together, `cli-vX.Y.Z` the CLI
+alone, or run the workflow manually. The job runs `npm ci` at the repo root (the build needs the
+runtime sources, the root TypeScript and esbuild), checks the lockstep version against the root
+and the tag, type-checks, runs the CLI specs and `npm publish`es. Try the tarball locally with
+`npm pack -w packages/cli` at the repo root, then `npx -y --package ./pix3-cli-X.Y.Z.tgz pix3 …`.