@solidrt/cli 0.0.50 → 0.0.52

package/AGENTS.md

@@ -1,41 +1,78 @@
 # @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>`.
 
+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
 
 - `bunx srt init <dir>` - scaffold a new SolidRT project into a new (empty)
   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` - transpile to `<file>.srt.js`. With
-  `--compile`, emits `.srt.bin` bytecode. `--minify`, `--dev`, `--stdout`,
-  `--output` also available.
-- `bunx srt render src/index.tsx [flags]` - render OFFSCREEN to PNG frames,
+- `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 [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 - the exact shape (`after` ms, `type`, `key`,
-  `device`) is in `docs/cli.md` under `--capture`. For probing app state
-  without a display, `-- <args...>` reaches the app as `flux:process` argv
-  (also `docs/cli.md`), which is often simpler than scripting input.
+  Lines and hand-authorable: one object per line,
+  `{"after": <ms since previous event>, "type": "keydown" | "keyup",
+  "key": <W3C KeyboardEvent.key>, "device": <client id>}`. For probing app
+  state without a display, `-- <args...>` reaches the app as `flux:process`
+  argv, which is often simpler than scripting input.
 
 ## Verifying without a display (headless / CI / agent box)
 
 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
@@ -63,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

@@ -0,0 +1,46 @@
+# Assets, fonts, identity and 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
+  registration step). Reference assets by path - `file("assets/sounds/x.ogg")`
+  from `flux:fs` - and treat them as read-only at runtime; writes belong in
+  plain relative paths, which land in the app's private data dir.
+- Small text-like assets (SVG documents, shaders) can instead be inlined via
+  imports. An import attribute picks the form and works on any extension:
+  `import src from "./effect.glsl" with { type: "text" }` yields the file's
+  contents as a string, `with { type: "binary" }` yields a Uint8Array. `.svg`
+  is text-loaded with no attribute needed. Shader sources (`.glsl`/`.vert`/
+  `.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
+  selectable via fontFamily). A newly added font shows after restarting the
+  client.
+- The `solidrt` key in package.json is the app's identity: set a stable
+  reverse-DNS `appId` before distributing - it keys the app's storage
+  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` 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

@@ -0,0 +1,294 @@
+# Debugging a running app
+
+Read this before investigating a bug in a running app, or before driving the
+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 (`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` 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` 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
+  `get_gpu_resources` reports only that the pass exists. `bunx srt render` is
+  the only programmatic view of what a window shader produces.
+- Permission prompts: agents typically ask approval per MCP tool. All of
+  these tools only talk to the local dev server the user started with
+  `bunx srt run` - nothing leaves the machine - so approving the server as a
+  whole is a reasonable default. If repeated prompts get in the way, do not
+  work around them; tell the user they can pre-approve the server in their
+  agent's settings (most agents have a per-server trust or allowlist setting
+  - in Claude Code, add "mcp__solidrt" to `permissions.allow` in
+  ~/.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
+  you will want repeatedly (a pose, a mode, a counter), bind a debug key that
+  logs it and read it back via get_logs.
+- Better than debug keys when driving the app over MCP: register debug
+  COMMANDS - `registerDebug(name, fn)` from `srt:dev`, invoked via the
+  list_debug/call_debug tools. Use them to SET UP state (jump to a level,
+  force a mode, seed a scenario); then the runtime-level tools take over -
+  set_time_scale 0 freezes the result for as many snapshots as you need,
+  and step_frames walks it forward deterministically. Set state, pause,
+  snapshot. Registrations reset on hot reload, so register at module init;
+  sync return values only - and note a signal you just wrote flushes on a
+  microtask, so returning a signal read straight after setting it returns
+  the OLD value.
+- call_debug sets state directly, skipping focus, key routing, and
+  TextInput - fine for SETUP, but "the interaction works" is only shown by
+  the real pipeline: verify clicks, typing, and drags with send_input,
+  which enters events where SDL input does.
+- Key events start at the focused node and bubble to the window root; with
+  nothing focused they go to the window root alone. So a debug key bound via
+  `<window onKeyDown>` always fires (unless a focused component consumes the
+  key with stopPropagation, as TextInput does for editing keys). `key` and
+  `code` are W3C KeyboardEvent values, so arrow keys arrive as "ArrowLeft"/
+  "ArrowRight"/"ArrowUp"/"ArrowDown" (not "Left"), alongside "Enter",
+  "Escape", "a".
+- Idle frames skip work: shaders/pipelines only re-render when an input
+  changes - their own params/geometry, or a sampled texture (a data upload,
+  or a sampled target re-rendering; chains propagate automatically). Measure
+  performance while inputs are actually changing. get_snapshot works on an
+  idle client (it requests its own frame); a timeout means the JS thread is
+  busy or wedged. get_texture on a pipeline's render target reads the
+  current output, pending writes included, without needing a new frame.
+- When a human reports a visual bug: capture a snapshot and SAY WHAT YOU SEE
+  in it before investigating, so you agree on the symptom. If you cannot see
+  the problem in the capture, say that instead of guessing.
+- Snapshots are downscaled by the time you see them, so a full-window capture
+  cannot show you a defect a few pixels across. Whenever you hand-author
+  geometry - a `d-path` from raw path math, a `radius` where two shapes meet,
+  a stroke join - inspect it MAGNIFIED once, when you write it: get_snapshot
+  with a tight crop at scale 4-8 shows the actual rendered pixels enlarged,
+  in one call, on the real app. Verifying that a shape is in the right place
+  is not the same check as verifying it is drawn right - and get_render_tree
+  props answers the third question, whether the value you set is the value
+  the renderer holds.
+- GPU/geometry bugs: inspect the actual GPU data FIRST - get_gpu_resources
+  for draw counts/uniforms/sizes, get_texture for atlas or data-texture
+  contents ("is this tile blank?" is a ten-second question), get_buffer for
+  vertex data. The pixels only tell you THAT something is wrong; the
+  resources tell you WHERE the data stops being right. In a one-big-pipeline
+  app the render tree is a single <texture> leaf and tells you nothing -
+  these tools are the visibility layer behind it. Only when the GPU data is
+  all correct (so the bug is in producing it, or in the shader), reproduce
+  the math CPU-side in a scratch bun script against the app's real data and
+  print values.
+- Validate assets at load time and log anomalies (missing lumps/files,
+  fully-transparent composites, zero-sized images). Silent fallbacks hide
+  bugs for days; a one-line warning surfaces them the first run.
+- After every reload the app restarts from its initial state. If reaching
+  the bug site takes navigation, add a dev shortcut (teleport key, noclip,
+  initial-state override) before iterating - the round trips add up fast.
+- Clamp onFrame time deltas to [0, cap], not just capped: across a hot
+  reload the runtime's tick counter resets AFTER the new instance's first
+  frame, so the second frame computes a hugely NEGATIVE delta.
+  Math.min(dt, cap) lets it through, and one bad frame can corrupt anything
+  integrated from dt (positions fly off, accumulators go so negative they
+  never recover). Math.max(0, Math.min(dt, cap)) costs nothing.
+- A registered onFrame is a standing request, not demand-gated: it re-requests
+  the next frame every time it runs, so the runtime keeps calling it - and
+  presents - every frame at the refresh rate until you deregister it (fps
+  stays at the refresh rate on an idle screen; that is the 60fps burn called
+  out in @solidrt/core agents/performance.md, rule 4). The upside is that a
+  self-running loop - a game clock, a shader driver, a stepped VM doing silent
+  CPU work with no console output - keeps advancing on its own: it does NOT
+  stall when the body changes nothing and needs no startup "prime" write.
+  Deregister onFrame (return its cleanup, or let onCleanup fire) whenever
+  there is nothing left to advance.
+- Layout is incremental: a change re-solves only the dirty path, and clean
+  subtrees answer from a per-node cache, so long lists no longer cap layout
+  (a thousand-node tree relays out in well under a millisecond). If layoutMs
+  still grows with tree size, read the get_stats counters - a low
+  cacheHits/cacheGets ratio means the layout cache is being defeated, high
+  paraShapes means text is actually reshaping. Paint is viewport-culled:
+  under an `overflow="hidden"` scroller only the subtrees that can reach the
+  visible box are painted, so paintMs tracks what is on screen, not what is
+  mounted (nodesPainted in get_stats shows the count). Very long lists still
+  pay for the initial mount and for memory, so windowing stays sensible at
+  the thousands-of-rows scale.
+- Remote images: createImage (and Image) dedupes repeated URLs, caches the
+  bytes on disk, and the runtime rate-limits concurrent asset fetches per
+  host - do not build your own promise cache around it. Images are fetched
+  with no freshness check (an already-cached URL is never re-checked), so
+  use versioned URLs for content that changes. Use Image's `fallback` prop
+  (an image source) for the broken-image case instead of catching errors
+  yourself.
+- fetch() never caches by default and ignores server cache headers. Caching
+  is explicit and per call: `fetch(url, { cache: "force-cache" })` for
+  assets (serve from disk or fetch-and-store, no freshness),
+  `{ cache: "reload" }` to refresh an entry. Image/createImage already do
+  this for you.