@solidrt/cli 0.0.51 → 0.0.52

package/AGENTS.md

@@ -1,20 +1,29 @@
 # @solidrt/cli - agent notes
 
-Dense, self-contained facts for running and verifying a SolidRT app. Full docs
-live in docs/ (and the website). For the authoring model (elements, props,
-reactivity), see @solidrt/core (its AGENTS.md).
+Dense, self-contained facts for running and verifying a SolidRT app. The
+prose lives in README.md and src/<command>/docs.md (also the website). For
+the authoring model (elements, props, reactivity), see @solidrt/core (its
+AGENTS.md).
 
 `srt` is the dev tool. Bun is a dev prerequisite only; SolidRT apps run on the
 bundled `flux` runtime, not on Bun. Invoke via `bunx srt <command>`.
 
-Two companion files carry the depth this one leaves out; read the one that
-matches the work before starting it:
-- agents/debugging.md - driving a running app over MCP, and the debugging
-  lessons that cost real time. Read before investigating a bug or verifying
-  a change against the live app.
-- agents/assets.md - the assets/ folder, inlined imports, fonts, and the
-  `solidrt` package.json key. Read before adding an asset or font, or
-  building for distribution.
+The dev loop against a running app is pause_watch -> edit -> reload ->
+resume_watch -> get_logs -> get_snapshot, with mute_user_input while you
+measure or test and unmute_user_input after; agents/debugging.md has the
+why of each hold. `reload` surfaces build errors but not type errors:
+`bunx srt check` is for those.
+
+agents/ carries the depth this one leaves out; read the one that matches
+the work before starting it:
+- agents/debugging.md - driving a running app over MCP, pointing an agent
+  client at the `srt mcp` server, what the dev server serves and its control
+  API without MCP (a shell, a CI step), and the debugging lessons that cost
+  real time. Read before investigating a bug, verifying a change against the
+  live app, or scripting against a server.
+- agents/assets.md - the assets/ folder, inlined imports and the bundle
+  output; fonts, the `solidrt` package.json identity key, and distribution
+  builds. Read before adding an asset or a font, or building to distribute.
 
 ## Commands
 
@@ -22,19 +31,34 @@ matches the work before starting it:
   folder: package.json, tsconfig.json, AGENTS.md, a starter src/index.tsx, an
   empty assets/ (everything in it ships with the app), then installs deps. Greenfield shortcut (no install needed first):
   `bun create solidrt <dir>`.
-- `bunx srt run src/index.tsx` - dev server + a local client window, watches and
-  hot-reloads. NEEDS A DISPLAY (opens a GUI window). Not usable headless.
-- `bunx srt bundle src/index.tsx` - bundle into `dist/bundle/` (or
+- `bunx srt run` - dev server + a local client window, from the project root
+  (entry `solidrt.entry` in package.json, default src/index.tsx); `bunx srt run
+  <file>` serves a single file outside a project. NEEDS A DISPLAY (opens a GUI
+  window). Not usable headless. Reloads on save (the bundle's inputs and
+  `assets/`); an agent pauses that with `pause_watch` and pushes its edits
+  with the MCP `reload` tool.
+- `bunx srt tool` - list the build-time tools the installed `@solidrt/*`
+  packages ship (`<package>/tools/<name>.ts`, named `<package>/<name>`);
+  `bunx srt tool <package>/<name> [arguments]` runs one under bun in the
+  project, everything after the name passed through as the tool's own
+  arguments (each tool prints its own usage on `--help`). What a tool does
+  is the package's business (e.g. `3d/model` bakes a glTF into a model
+  file); srt only finds and runs them.
+- `bunx srt check [file|dir]` - build in memory and typecheck, no output
+  and no reload. With a folder it covers every entry under it (src/index.tsx
+  and examples/*), so `bunx srt check .` answers "did I break any example"
+  in one call. The dev server runs it once at startup without gating on it.
+- `bunx srt bundle` - bundle the project into `dist/bundle/` (or
   `--output <dir>`): `<name>.srt.js` plus the app's isolate modules as
   `isolates/<id>.js`. With `--compile`, bytecode (`.srt.bin`/`.bin`)
   instead. Move the dir, not the bare file - a bundle loaded without its
   isolates/ dir loses them (`--stdout` cannot carry them at all).
   `--minify`, `--dev` also available.
-- `bunx srt render src/index.tsx [flags]` - render OFFSCREEN to PNG frames,
+- `bunx srt render [flags]` - render the project OFFSCREEN to PNG frames,
   optionally replaying a `--script` file recorded via `--capture`.
 - `bunx srt server [file]` / `bunx srt client` - the two halves of `run`
   separately (server distributes code; clients on other devices connect to it).
-- `bunx srt run src/index.tsx --capture out.script.json` - records keydown/keyup
+- `bunx srt run --capture out.script.json` - records keydown/keyup
   from every connected client into one script file (written on client
   disconnect), for replaying later with `render --script`. The file is JSON
   Lines and hand-authorable: one object per line,
@@ -47,8 +71,8 @@ matches the work before starting it:
 
 Two reliable checks that need no GUI:
 
-1. `bunx srt bundle src/index.tsx` - exit 0 means the app compiles. Fast.
-2. `bunx srt render src/index.tsx --size 480x640 --duration 1 --fps 2` -
+1. `bunx srt bundle` - exit 0 means the app compiles. Fast.
+2. `bunx srt render --size 480x640 --duration 1 --fps 2` -
    renders offscreen via EGL and writes `frame-NNNNNN.png`. This actually
    proves the app renders. Combine with `--fps`/`--duration` (defaults
    1280x720, 60fps, 1s). No display needed: rendering uses SDL's offscreen
@@ -76,29 +100,35 @@ behavior in isolation.
   (Wayland) and the pbuffer path on Windows from a desktop session; a
   non-interactive Windows session and macOS are unverified.
 
-## Sessions (parallel dev servers on one machine)
-
-- `-s <N>` / `--session <N>` (default 0) picks the dev server: port
-  `34884 + N`. Valid on `run`, `server`, `client`, `mcp`. `srt run -s1` is a
-  second, fully independent dev setup; `srt client -s1 -c2` attaches another
-  client to it.
-- `-c <N>` / `--client <N>` picks the client data tree, defaulting to the
-  session number. (`--compile` gave its short to `--client`.)
-- Dev state lives in `~/.solidrt/`: `servers/<port>/` holds each server's tunnel
-  key and `live.json` (the registry record MCP resolution reads, removed at
-  exit), `clients/client<M>/` the client trees (srt passes
-  `--data-root ~/.solidrt/clients` to every locally spawned client).
-- A server run serves the project it was started in; `load` outside the
-  project root is refused. Restart the server in another project to switch.
-- `srt mcp` needs no port: each tool call resolves the server serving the
-  project the bridge runs in (registry match + probe); `-s`/`--port` pin it.
+## Servers (what is served, and finding it again)
+
+- A dev server serves a project (started in its root: the cwd must hold the
+  package.json) or a single file (`srt run <file>` outside a project). Both
+  in one place is ambiguous, so `srt run <file>` in a project root needs
+  `--project` (the project, with this entry) or `--file` (the file alone).
+  Nothing searches upward for a package.json.
+- One server per project or file. The server binds the port it had last
+  time, else the first free one from 34884 up, and prints it; `--port <N>`
+  pins it. Loopback only
+  unless `--lan`, which is what phones and other devices (and `srt android`
+  on a real device) need; `--tunnel` works without it.
+- `-c <N>` / `--client <N>` picks the client data tree (default 0). Storage
+  is per app inside a tree, so two projects share client 0; only two clients
+  of the same app need distinct slots.
+- Dev state lives in `~/.solidrt/`: `servers/<key hash>/` holds each server's
+  `live.json` (the registry record, written by the server and removed at
+  exit), its remembered `port` and tunnel key; `clients/client<M>/` the
+  client trees (srt passes `--data-root ~/.solidrt/clients` to every locally
+  spawned client). A record left behind by a crash is pruned when the next
+  server starts, and `srt client`, `srt mcp` and `srt android` confirm a
+  record against the server (its control API names the key it serves)
+  before using it.
+- `srt client` and `srt mcp` need no port: run from the project root (or the
+  directory of a served file) they resolve the server from the registry;
+  `--port` pins one.
 
 ## Dev server proxies (when clients on other devices need your machine's data)
 
 - `--proxy-http` - route `fetch` through the dev server; responses cached in
   `.srt-data/http-cache.db` in the project root (delete the file to clear).
 
-## REPL (opened by `run`/`server`)
-
-`load <file>`, `reload [n]`, `stop [n]`, `list`, `!<cmd>`, `quit`/`exit`.
-`load` is bound to the project root the server was started in.

package/README.md

@@ -1,26 +1,97 @@
 # @solidrt/cli
 
-Developer tooling for SolidRT. Provides a development environment for `@solidrt/core` applications.
+Developer tooling for SolidRT: `srt`, one command-line tool covering the
+whole cycle of a `@solidrt/core` application: scaffold, develop, inspect,
+ship. A GUI inspector, itself a SolidRT app, is in progress alongside it.
 
-> LLM agents: see [AGENTS.md](./AGENTS.md) for a dense, self-contained quickstart.
+> LLM agents: `AGENTS.md` in this package is a dense, self-contained quickstart.
+
+Bun is a dev prerequisite only; apps run on the bundled `flux` runtime.
+Invoke via `bunx srt <command>`. A scaffolded project wires the common
+commands into scripts, so day-to-day work is `bun run dev`, `bun run
+android` (and `server`, `client`, `pack` for the rest).
 
 ## Commands
 
+| Command | |
+| --- | --- |
+| [`srt init <dir>`](src/init/docs.md) | scaffold a new project into a new (empty) folder |
+| [`srt run [file]`](src/server/docs.md) | dev server + local client window |
+| [`srt server [file]`](src/server/docs.md) | dev server only |
+| [`srt client`](src/client/docs.md) | client only, attached to the project's dev server |
+| [`srt android`](src/android/docs.md) | install and launch the client on a connected Android device |
+| [`srt demo [n]`](src/demo/docs.md) | list the demos the installed packages ship, or run one |
+| [`srt console`](src/console/docs.md) | start the dev console: the dev servers on this machine and their clients |
+| [`srt check [file]`](src/check/docs.md) | build and typecheck, writing nothing |
+| [`srt bundle [file]`](src/bundle/docs.md) | transpile to JS or bytecode (dist/bundle/) |
+| [`srt render [file]`](src/render/docs.md) | render frames offscreen, optionally replaying a script |
+| [`srt pack [file]`](src/pack/docs.md) | bundle + compile to a standalone executable (experimental) |
+| [`srt mcp`](src/mcp/docs.md) | MCP server (stdio) exposing the running dev server to agents |
+
+`srt --help` lists every command and option; `srt --version` prints the
+version. Run from the project root to work on the project (its entry is
+`solidrt.entry` in package.json, default `src/index.tsx`); pass a file to
+work on that file on its own.
+
+## Develop
+
+```sh
+srt run
+```
+
+Starts the dev server and a local client window against it. The server
+pushes the bundle to every connected client, so one server can drive a
+desktop window and a phone at the same time; edits reach them on an
+explicit reload (the MCP `reload` tool) or on save.
+
+Split them when you need to:
+
+```sh
+srt server                        # server only
+srt client                        # client only, the project's server (from its root)
+srt client --server 192.168.1.5:34884  # client only, pointed at that address
+srt android                       # install and launch on a connected device
+```
+
+## Inspect
+
+```sh
+srt mcp
+```
+
+Exposes the running app to a coding agent: logs, stats, the live render
+tree, screenshots, GPU resources, input injection, a virtual-time transport,
+reload, and the app's own debug commands. A scaffolded project ships an
+`.mcp.json`, so Claude Code attaches with no setup.
+
+## Record and replay
+
+```sh
+srt run --capture session.json
+srt render --script session.json --fps 60 --duration 5
+```
+
+`--capture` records key events from connected clients to a script; `render`
+replays it headlessly and writes frames, which makes bug reports
+reproducible and turns an interaction into a video.
+
+## Ship
+
 ```sh
-bunx srt run [file]          # start dev server + client, optionally load a file
-bunx srt run --server [file] # start dev server only
-bunx srt run --client        # start dev client only
+srt check .                # build and typecheck every entry, no build output
+srt bundle                 # transpile to JS or bytecode
+srt pack                   # standalone executable (experimental)
 ```
 
-## REPL
+`srt bundle --flux` and `srt pack --flux` target the bare Flux runtime
+instead of a SolidRT app, for scripts and servers with no UI.
 
-Running `bunx srt run` opens an interactive REPL. The loaded file is watched for changes and automatically pushed to connected clients.
+## Layout
 
-| Command         | Description                                      |
-| --------------- | ------------------------------------------------ |
-| `load <file>`   | load and push a `.tsx`, `.srt.js`, or `.srt.bin` |
-| `reload [n]`    | rebuild and push to all clients, or client `n`   |
-| `stop [n]`      | stop all clients, or client `n`                  |
-| `list`          | list connected clients                           |
-| `!<cmd>`        | run a shell command                              |
-| `quit` / `exit` | exit the dev server                              |
+One folder per command under `src/`, named for what it does; the first line
+of each says its runtime. `src/server/` is the dev server, a flux script
+(`bun`-free at runtime, its own tsconfig); every other command runs on bun.
+`src/lib/` is what the bun commands share, `src/types/` the type-only
+contracts between the two runtimes. Each command folder carries its
+`docs.md` (this site); the depth agents need lives in `agents/` at the
+package root, as in the other packages.

package/agents/assets.md

@@ -1,7 +1,9 @@
-# Assets and app identity
+# Assets, fonts, identity and distribution
 
-Read this before adding an asset, a font, or preparing a build for
-distribution.
+Read this before adding an asset or a font, setting the app's identity, or
+preparing a build for distribution.
+
+## Assets and inlined imports
 
 - Everything under `assets/` ships with the app: the folder is collected
   wholesale into each build's version manifest (no bundler analysis, no
@@ -16,6 +18,17 @@ distribution.
   `.frag`) are declared as text modules out of the box, so they typecheck
   without setup. Inlining trades update granularity for zero I/O - keep big or
   streamable files (audio, images) in `assets/`.
+- `bunx srt bundle` writes `dist/bundle/` (or `--output <dir>`):
+  `<name>.srt.js` plus the app's isolate modules as `isolates/<id>.js`; with
+  `--compile`, bytecode (`.srt.bin`/`.bin`) instead. Move the dir, not the
+  bare file - a bundle loaded without its isolates/ dir loses them
+  (`--stdout` cannot carry them at all). Isolates (`"use isolate"` modules)
+  exist in projects only, not for a file served on its own.
+- `bunx srt bundle --json` is the dev server's rebuild contract: one JSON
+  object (code, sourcemap, manifest, isolates) on stdout. Not for humans.
+
+## Fonts, identity and distribution
+
 - Custom fonts go in `assets/fonts/` and are declared in the `solidrt.fonts`
   map in package.json (alias -> file path; role aliases `sans`/`serif`/`mono`
   replace the built-in defaults, `false` drops one, other keys add fonts
@@ -26,7 +39,8 @@ distribution.
   folder, defaults from the package name in dev, and `srt pack` warns
   while defaulted. `org` and `displayName` are optional display metadata
   (future launcher/window naming) with no storage meaning.
-- `bunx srt pack src/index.tsx` builds a single-file executable;
-  `bunx srt pack --folder src/index.tsx` writes the flat app folder
+- `bunx srt pack` builds a single-file executable (the runner with the
+  bytecode, manifest, assets and fonts appended as a trailer);
+  `bunx srt pack --folder` writes the flat app folder
   (runner + manifest.json + bundle + assets/, plus the runner's GL
   libraries on Windows and macOS) to `dist/pack/`.

package/agents/debugging.md

@@ -1,30 +1,46 @@
 # Debugging a running app
 
 Read this before investigating a bug in a running app, or before driving the
-app over MCP to verify a change.
+app to verify a change: over MCP, or through the same control API from a
+shell or a CI step ("The control API without MCP" below).
 
 ## Driving the app over MCP
 
-The project ships an MCP server (`.mcp.json`, `srt mcp`) that talks to the dev
-server `bunx srt run` starts. Each tool documents itself in full - read the
-tool description rather than guessing at its arguments. What the individual
-descriptions cannot tell you:
+The project ships an MCP server (`srt mcp`) that talks to the dev server
+`bunx srt run` starts. If your client lists no `solidrt` tools, it has not
+been pointed at the server yet - see "Wiring up an agent client" below. Each
+tool documents itself in full - read the tool description rather than guessing
+at its arguments. What the individual descriptions cannot tell you:
 
 - If `list_clients` is empty, no app is running: ask the user to start
-  `bunx srt run src/index.tsx` rather than starting a second one yourself.
-  The bridge dials the dev server's default port (34884), so if the user
-  started it with `--port N`, `.mcp.json` needs the same flag:
-  `"args": [..., "mcp", "--port", "N"]`.
+  `bunx srt run` rather than starting a second one yourself.
+  The bridge needs no port: it resolves the server currently serving this
+  project, whatever `--port` it was started with, and re-resolves when
+  that server goes away or a different project's server takes its port.
+  Passing the flag to `srt mcp` pins the bridge to that one server instead.
 - Several clients may be attached at once (desktop window, phone, tablet)
   with different sizes, display scales and safe areas. `reload` pushes to all
-  of them, but `call_debug` / `send_input` / `get_snapshot` / log cursors are
-  per client, and interactive state does NOT sync - a flow driven on one
-  client leaves the others sitting on the initial screen, which reads as a
-  crash to a human holding that device. So: when driving state via
-  `call_debug`, send the same call to every client (or say which client you
-  are using); and before calling a visual change done, snapshot each distinct
-  form factor at least once - a layout that fits one window can clip or
-  overflow another.
+  of them, but `call_debug` / `send_input` / `get_snapshot` are per client
+  (`get_logs` takes a `client` filter), and interactive state does NOT sync
+  - a flow driven on one client leaves the others sitting on the initial
+  screen, which reads as a crash to a human holding that device. So: when
+  driving state via `call_debug`, send the same call to every client (or say
+  which client you are using); and before calling a visual change done,
+  snapshot each distinct form factor at least once - a layout that fits one
+  window can clip or overflow another.
+- Measuring or testing? `mute_user_input` first: it mutes the user's own
+  input on every client (a stray click or keypress mid-measurement corrupts
+  the result); `send_input` still works. `unmute_user_input` the moment you
+  are done, or whenever you need the human to press something: they see an
+  unresponsive client meanwhile. The bridge unmutes when it exits, the
+  server when it stops, but neither is a reason to leave a mute on.
+- Editing? `pause_watch` first: the server reloads on save, and a
+  half-finished save would land on the user's screens as a build error or
+  a broken app. Edit, `reload`, then `resume_watch`. The two holds are
+  separate on purpose: the mute keeps the human out while you measure, the
+  pause keeps your own saves out while you edit, and a human editing next
+  to you keeps auto-reload unless you hold it. The bridge resumes when it
+  exits, but do not rely on that.
 - A `shader` on `<window>` runs on the finished frame past the point every
   capture reads: `get_snapshot` returns the UNSHADED content (window node
   included), `get_texture` has no id for the shaded layer, and
@@ -40,6 +56,142 @@ descriptions cannot tell you:
   ~/.claude/settings.json to cover every solidrt project). This is the user's
   call to make, once, in their own tooling.
 
+## Wiring up an agent client
+
+`.mcp.json` in the project root is Claude Code's convention, and a scaffolded
+app ships one. MCP standardizes the protocol, not how a client discovers
+servers, so every other client reads its own file. The entry is the same
+everywhere, in the client's syntax:
+
+```json
+{ "command": "bun", "args": ["node_modules/@solidrt/cli/bin/srt", "mcp"] }
+```
+
+Where it goes (these locations move between client releases; check the
+client's own docs if it does not match):
+
+- Claude Code: `.mcp.json` in the project root, under `mcpServers`. Claude
+  Code asks once, per project, before it will launch a server from this
+  file; until that is approved the `solidrt` tools are absent.
+- Cursor: `.cursor/mcp.json`, under `mcpServers`
+- VS Code / Copilot: `.vscode/mcp.json`, under `servers`
+- Gemini CLI: `.gemini/settings.json`, under `mcpServers`
+- Codex CLI: `~/.codex/config.toml`, under `[mcp_servers.solidrt]`
+
+Several of these also ship a command that writes the entry for you
+(`claude mcp add`, `codex mcp add`); prefer it over hand-editing.
+
+The one constraint: the bridge must run with the project as its working
+directory. It finds the dev server through the nearest package.json above
+its cwd, and the `args` path is relative to the project root. A per-project
+file gives that for free. A user-level entry works too, but only while the
+client itself was launched from the project root (or the client supports a
+`cwd` field and it is set); launched from elsewhere, every tool call answers
+"No dev server for ..." while one is running.
+
+## The dev server
+
+What the dev server (`srt run` / `srt server`) is and what it serves.
+
+- A dev server serves a project (started in its root: the cwd must hold the
+  package.json) or a single file (`srt run <file>` outside a project). Both
+  in one place is ambiguous, so `srt run <file>` in a project root needs
+  `--project` (the project, with this entry) or `--file` (the file alone).
+  Nothing searches upward for a package.json.
+- One server per project or file. The server binds the port it had last
+  time, else the first free one from 34884 up, and prints it; `--port <N>`
+  pins it. Loopback only unless `--lan`.
+- Dev state lives in `~/.solidrt/`: `servers/<key hash>/` holds each server's
+  `live.json` (the registry record, written by the server and removed at
+  exit), its remembered `port` and tunnel key; `clients/client<N>/` the
+  client trees. `srt client` and `srt mcp` resolve the server from the
+  registry by the project (or served file) at their cwd; `--port` pins one.
+  A record whose process died is pruned when the next server starts, and
+  resolution confirms a record against the server before using it.
+- The server is one flux process, complete on its own:
+  `flux dist/server.js [file] [--project|--file] [--port N] [--lan]
+  [--proxy-http] [--capture f] [--tunnel] [--stats] [--client N ...] [-- args]`
+  (src/server/args.ts). It finds the platform binaries, bun and srt through
+  `SRT_PLATFORM_DIR`, `SRT_BUN` and `SRT_CLI`, which `srt` sets; started by
+  hand in a checkout it needs only `SRT_HOME`.
+- Reload-on-save watches the bundle's inputs (every file the running
+  bundle was built from, dependencies included) and the `assets/` tree, not
+  a directory: a file the app does not import never triggers a rebuild.
+  While the last build failed, the source tree is watched as a whole until
+  a build succeeds. `POST /__control__/watch?active=false` pauses it (the
+  MCP `pause_watch` tool) while an agent edits; `POST /__control__/reload`
+  (the `reload` tool) is the agent's push.
+
+## The control API without MCP
+
+Every MCP tool is a thin wrapper over the dev server's HTTP control API, so
+a shell script, a CI step, or an agent with no MCP bridge can drive the app
+the same way. Base: `http://127.0.0.1:<port>/__control__/`, where `<port>`
+is the one `srt run` printed at startup (also in the server's
+`~/.solidrt/servers/*/live.json` record). GET unless noted;
+every endpoint answers JSON and an error is `{ "error": "..." }` with a
+4xx/5xx status, and every response carries `x-solidrt-project` (the key
+served) and `x-solidrt-generation` (the server run) headers, so a caller can
+confirm it reached the server it meant and notice a restart. Endpoints that
+talk to a client take `?client=<id>` (from `/clients`); it may be omitted
+when exactly one client is connected.
+
+- `/clients` - `{ generation, key, mode, entry, projectDir, userInputMuted,
+  watchPaused, clients: [{ id, ... }] }`. Check `key` (the project root or
+  single file served) is the app you mean.
+- `/logs?since=<seq>&level=<lvl>&contains=<text>&wait=<ms>&client=<id>` -
+  `{ entries: [{ seq, at, client, level, text, repeats? }], latest,
+  generation }`. Pass the previous `latest` as `since` to read only new
+  output; `client` keeps one client's entries (all clients without); a
+  changed `generation` means the server restarted and cursors and client
+  ids are stale.
+- `/tree?query=<text>&root=<id>&depth=<n>&props=true` - `{ limit, matches:
+  [{ id, kind, path, x, y, width, height }] }` for a query, the nested tree
+  otherwise. Node ids are per client and change on reload; re-query after
+  `/reload`.
+- `/snapshot?node=<id>` - `{ width, height, pngBase64 }`, display-scaled;
+  add `&format=raw` for `rgbaBase64` (RGBA8 bytes, no decoder needed for
+  pixel assertions), `&x=&y=&width=&height=` (all four) to crop,
+  `&scale=<1-8>`. Snapshot the smallest node that shows the change, not the
+  window root.
+- `/texture?id=<textureId>` - same shape and options as `/snapshot`, at the
+  texture's native size (a scene or shader target behind a `<texture>` leaf).
+- `/gpu?label=<text>` - the GPU resource inventory; `label` keeps only the
+  resources created with exactly that label (ids change on reload, labels
+  do not).
+- `/buffer?id=<bufferId>&offset=<n>&length=<n>&as=<f32|u16|u8>` - vertex
+  buffer contents (default f32; reads cap at 64 KiB).
+- `/stats?window=<ms>` - the performance statistics. POST
+  `/stats?active=true|false` switches the on-screen stats overlay instead
+  (the `set_stats_overlay` tool): one client with `&client=<id>`, every
+  client (and the setting new clients join with) without; `/clients`
+  reports each client's `stats`.
+- `/debug` - the app's registered debug commands; POST
+  `/debug?name=<cmd>` with a JSON body as its args to call one.
+- POST `/input` with `{ "events": [...] }` - synthetic input through the
+  real pipeline, same event shape as the `send_input` tool (tap real
+  coordinates read from `/tree`).
+- POST `/clock?scale=<x>` (0 pauses) / `?step=<n>` frames while paused;
+  `{ scale, pendingSteps }` back. `/clients` reports each client's `timeScale`,
+  reset to 1 by every push.
+- POST `/reload` - rebuild and push to every client; `{ ok, clients }` or
+  the build error.
+- POST `/load` with `{ "entry": "<path>" }` - switch the entry and push it;
+  `{ ok, entry, clients }` or the build error. Relative paths resolve
+  against the project root (file mode: the served file's directory). A
+  project server only loads files inside its project.
+- POST `/mute?active=true|false` - mute/unmute the user's own input on
+  every client, gamepads included (synthetic `/input` still goes through;
+  resize and close cannot be muted). `{ ok, active, clients }`. The mute
+  lifts when the server stops; unmute yourself when done.
+- POST `/watch?active=true|false` - resume/pause reload-on-save (`active`
+  is whether it watches). `{ ok, active }`. Paused, saves push nothing
+  until `/reload`; changes made meanwhile are not replayed on resume. The
+  pause lifts when the server stops; resume yourself when done.
+
+The loop is the same as over MCP: `/reload`, then `/logs?since=`, then
+`/tree` for coordinates and `/snapshot` of the smallest relevant node.
+
 ## Lessons that cost real time
 
 - console.log + get_logs is your primary probe into runtime state. For state