@solidrt/cli 0.0.53 → 0.0.54

package/AGENTS.md

@@ -11,7 +11,9 @@ 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:
+why of each hold. Several clients may be attached at once: `reload` reaches
+all of them, while call_debug / send_input / get_snapshot are per client
+(debugging.md). `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

package/agents/debugging.md

@@ -156,20 +156,26 @@ when exactly one client is connected.
   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).
+- `/gpu?label=<text>&draw=<id>` - the GPU resource inventory; `label` keeps
+  only the resources created with exactly that label (ids change on reload,
+  labels do not). A draw target's entries report uniforms wider than a vec4
+  (matrices) as their length, `"[16]"`; `draw` names the one entry (ids are
+  per target, so pair it with `label`) reported in full.
 - `/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`. `frames` counts the frames actually
-  rebuilt in the window, `fps` the refresh rate presented at: when motion
-  looks wrong and `fps` looks fine, `frames` is the number to read - a
-  picture that only changes 26 times a second shows 26 there, and the
-  stutter is the app's update cadence, not the engine's.
+  reports each client's `stats`. `frames` counts the frames that changed
+  the picture: tree rebuilds, plus GPU content changes presented without
+  one (a layer write, a shader param, an upload - a sprite or shader app
+  rebuilds nothing, every frame of it is one of these).
+  `fps` is the refresh rate presented at: when motion looks wrong and `fps`
+  looks fine, `frames` is the number to read - a picture that only changes
+  26 times a second shows 26 there, and the stutter is the app's update
+  cadence, not the engine's. `frames: 0` means the picture did not change
+  at all in the window.
 - `/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
@@ -263,6 +269,21 @@ The loop is the same as over MCP: `/reload`, then `/logs?since=`, then
   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 fixed-timestep simulation on that clamped dt still drifts: no panel
+  presents at exactly its nominal rate (a "60 Hz" panel measured 60.3) and
+  the paced tick tracks the real cadence, so a 16.667 ms step against a
+  16.59 ms average dt comes up one step short every few seconds - one frame
+  runs no step (freeze), the next runs two (jump), and frame jitter
+  scatters which frame it lands on, so it reads as random stutter. The
+  runtime hands every callback the refresh rate,
+  `onFrame((tick, frame, rate) => ...)` (SDL's nominal Hz): when the step is
+  within a few percent of `1000 / rate`, run whole steps per frame
+  (`Math.round(dt / STEP_MS)`, clamped to [0, cap]) so the world rides the
+  refresh; only accumulate (`acc += dt; while (acc >= STEP_MS) ...`) when
+  the display is genuinely off-rate (50, 120, 144 Hz), or interpolate the
+  render by `acc / STEP_MS` if the game does not snap to whole pixels. It
+  is invisible in a five-second look and survives every renderer
+  optimisation; measure it with a steps-per-frame histogram, not by eye.
 - 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

package/dist/console.srtapp

@@ -1,4 +1,4 @@
-{"appId":"com.solidrt.console","org":"Console","displayName":"Console","icon":"assets/icon.svg","runtimeVersion":1,"solidrtVersion":"0.0.53","bundle":{"path":"bundle.bin","sha256":"61bad7f5442a7dc7eff593762727075a0678c7ef8ff47b637bdc425083829629","size":873391},"assets":[{"path":"assets/fonts/NotoSans.ttf","sha256":"bfb7bb691513f12e734dc346c03a03f784912432d7e3fa8e56efcf906fe86b3d","size":2049096},{"path":"assets/fonts/NotoSansMono.ttf","sha256":"2cb2adb378a8f574213e23df697050b83c54c27df465a2015552740b2769a081","size":1708408},{"path":"assets/icon.svg","sha256":"fc78e748eefeade49c5c4a74944d9f43b8d7a7c61e7003123b8b13fedb7f1050","size":466}],"fonts":[{"path":"assets/fonts/NotoSans.ttf","alias":"sans"},{"path":"assets/fonts/NotoSansMono.ttf","alias":"mono"}]}�a�Z�
main
flux:rendertree
srt:render
srt:events
srt:app
flux:gpu
flux:image
flux:svg
flux:fs
flux:process
flux:subprocess
requestFrame
setPointerLock
renderFrame
on
once
exit
depthTexture
destroyTexture
endBufferWrite
resizeTexture
setTargetParams
setTargetRect
setTargetSize
"setTargetTextures
uploadTexture
copyTexture
destroyBuffer
renderTarget
setDraw
addDraw
removeDraw
setDrawBuffers
setDrawOrder
setDrawParams
setDrawRange
setDrawTextures
limits
compileShader
(createRenderPipeline
destroyProgram
*destroyRenderPipeline
destroyShader
linkProgram
"programAttributes
captureSnapshot
readTexture
decodeImage
encodeImage
parseSvg
dir
file

+{"appId":"com.solidrt.console","org":"Console","displayName":"Console","icon":"assets/icon.svg","runtimeVersion":1,"solidrtVersion":"0.0.54","bundle":{"path":"bundle.bin","sha256":"61bad7f5442a7dc7eff593762727075a0678c7ef8ff47b637bdc425083829629","size":873391},"assets":[{"path":"assets/fonts/NotoSans.ttf","sha256":"bfb7bb691513f12e734dc346c03a03f784912432d7e3fa8e56efcf906fe86b3d","size":2049096},{"path":"assets/fonts/NotoSansMono.ttf","sha256":"2cb2adb378a8f574213e23df697050b83c54c27df465a2015552740b2769a081","size":1708408},{"path":"assets/icon.svg","sha256":"fc78e748eefeade49c5c4a74944d9f43b8d7a7c61e7003123b8b13fedb7f1050","size":466}],"fonts":[{"path":"assets/fonts/NotoSans.ttf","alias":"sans"},{"path":"assets/fonts/NotoSansMono.ttf","alias":"mono"}]}�a�Z�
main
flux:rendertree
srt:render
srt:events
srt:app
flux:gpu
flux:image
flux:svg
flux:fs
flux:process
flux:subprocess
requestFrame
setPointerLock
renderFrame
on
once
exit
depthTexture
destroyTexture
endBufferWrite
resizeTexture
setTargetParams
setTargetRect
setTargetSize
"setTargetTextures
uploadTexture
copyTexture
destroyBuffer
renderTarget
setDraw
addDraw
removeDraw
setDrawBuffers
setDrawOrder
setDrawParams
setDrawRange
setDrawTextures
limits
compileShader
(createRenderPipeline
destroyProgram
*destroyRenderPipeline
destroyShader
linkProgram
"programAttributes
captureSnapshot
readTexture
decodeImage
encodeImage
parseSvg
dir
file

 alive
execPath
homedir
platform
command
NotReadyError
StatusError
NoOwnerError
(ContextNotFoundError

 Queue
GlobalQueue
CollectionQueue

 tree2
on2
tree

package/dist/demos/3d/the-third-dimension/the-third-dimension.srt.js

@@ -5112,7 +5112,7 @@ function releaseGeometryBuffers(acquired) {
 }
 
 // ../src/material.ts
-var VERTEX_SRC = glsl`
+var UNLIT_VERTEX = glsl`
   in vec3 aPos;
   in vec2 aUV;
   out vec2 vUv;
@@ -5124,21 +5124,7 @@ var VERTEX_SRC = glsl`
     vUv = aUV;
   }
 `;
-var FRAGMENT_COLOR_SRC = glsl`
-  uniform vec4 uColor;
-  void main() {
-    fragColor = uColor;
-  }
-`;
-var FRAGMENT_MAP_SRC = glsl`
-  in vec2 vUv;
-  uniform sampler2D uMap;
-  uniform vec4 uColor;
-  void main() {
-    fragColor = texture(uMap, vUv) * uColor;
-  }
-`;
-var pipelines = new Map;
+var unlitClasses = new Map;
 var litClasses = new Map;
 var SHADOW_DEPTH_VERTEX = glsl`
   in vec3 aPos;
@@ -5153,18 +5139,48 @@ var SHADOW_DEPTH_FRAGMENT = glsl`
     fragColor = vec4(1.0);
   }
 `;
-var shadowDepth;
-function shadowDepthMaterial() {
-  if (shadowDepth === undefined) {
-    shadowDepth = shaderMaterialClass({
+var shadowDepth = new Map;
+function shadowDepthMaterial(cull = "front") {
+  let material = shadowDepth.get(cull);
+  if (material === undefined) {
+    material = shaderMaterialClass({
       vertex: SHADOW_DEPTH_VERTEX,
       fragment: SHADOW_DEPTH_FRAGMENT,
-      cull: "front",
-      label: "scene-shadow-depth"
+      cull,
+      label: "scene-shadow-depth-" + cull
     }).instance();
+    shadowDepth.set(cull, material);
   }
-  return shadowDepth;
+  return material;
+}
+function shadowCull(cull) {
+  return cull === "none" ? "none" : cull === "back" ? "front" : "back";
 }
+function shadowVariant(cull) {
+  return cull === "back" ? undefined : shadowDepthMaterial(shadowCull(cull));
+}
+var SHADOW_CUTOUT_VERTEX = glsl`
+  in vec3 aPos;
+  in vec2 aUV;
+  out vec2 vUv;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+  void main() {
+    gl_Position = uViewProj * uModel * vec4(aPos, 1.0);
+    vUv = aUV;
+  }
+`;
+var SHADOW_CUTOUT_FRAGMENT = glsl`
+  in vec2 vUv;
+  uniform sampler2D uMap;
+  uniform vec4 uColor;
+  uniform float uAlphaTest;
+  void main() {
+    if (texture(uMap, vUv).a * uColor.a < uAlphaTest) discard;
+    fragColor = vec4(1.0);
+  }
+`;
+var shadowCutout = new Map;
 var SPRITE_VERTEX_SRC = glsl`
   in vec3 aPos;
   in vec2 aUV;
@@ -5256,10 +5272,11 @@ function shaderMaterialClass(opts) {
     }
   }
   let program;
-  let pipelines2 = new Map;
+  let pipelines = new Map;
   let normalMatrix2 = /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment);
   let transparent = opts.transparent ?? (opts.blend !== undefined && opts.blend !== "none");
   let depth = opts.depth ?? true;
+  let cull = opts.cull ?? "back";
   let instanceAttributes = opts.instanceAttributes?.length ? opts.instanceAttributes.map((a) => ({
     ...a
   })) : undefined;
@@ -5282,7 +5299,7 @@ function shaderMaterialClass(opts) {
   let attributes = () => programAttributes(programFor()).filter((a) => !instanceAttributes?.some((i) => i.name === a.name));
   let pipelineFor = (layout) => {
     let key = layoutKey(layout);
-    let pipeline = pipelines2.get(key);
+    let pipeline = pipelines.get(key);
     if (pipeline === undefined) {
       pipeline = createRenderPipeline(programFor(), {
         attributes: layoutAttributes(layout),
@@ -5290,11 +5307,11 @@ function shaderMaterialClass(opts) {
         depth,
         depthWrite: opts.depthWrite ?? (transparent && depth ? false : undefined),
         blend: opts.blend ?? (transparent ? "alpha" : undefined),
-        cull: opts.cull ?? "back",
+        cull,
         topology: opts.topology,
         label: opts.label
       });
-      pipelines2.set(key, pipeline);
+      pipelines.set(key, pipeline);
     }
     return pipeline;
   };
@@ -5307,13 +5324,16 @@ function shaderMaterialClass(opts) {
         instanceAttributes,
         pipeline: pipelineFor,
         params: inst.params ?? {},
-        textures: inst.textures
+        textures: inst.textures,
+        get shadow() {
+          return inst.shadow ?? shadowVariant(cull);
+        }
       };
     },
     dispose() {
-      for (let pipeline of pipelines2.values())
+      for (let pipeline of pipelines.values())
         destroyRenderPipeline(pipeline);
-      pipelines2.clear();
+      pipelines.clear();
       if (program !== undefined) {
         destroyProgram(program);
         program = undefined;
@@ -5971,7 +5991,7 @@ function createScene(width, height, opts) {
       return;
     if (v.filter !== null && !v.filter(mesh))
       return;
-    let material = v.override ?? mesh.material;
+    let material = v.override !== null ? v.filter !== null ? mesh.material.shadow ?? v.override : v.override : mesh.material;
     let bufs = mesh._buffers;
     let entry = addDraw(v.texture, material.pipeline(mesh.geometry.layout), entrySeed(material, v.override !== null ? null : mesh._params), {
       buffer: bufs.buffer,

package/dist/server.js

@@ -1083,6 +1083,7 @@ function clientList(withAddress = false) {
     os: info.os,
     kernel: info.kernel,
     videoDriver: info.videoDriver,
+    refreshRate: info.refreshRate,
     gpu: info.gpu,
     ...withAddress ? { address: ws.remoteAddr ?? null } : {}
   }));
@@ -1335,8 +1336,14 @@ async function handleControl(req, path, query) {
       return handleQuery(query, "snapshot", extra);
     }
     case "/__control__/gpu": {
+      let extra = {};
       let label = query.get("label");
-      return handleQuery(query, "gpu", label === undefined ? undefined : { label });
+      if (label !== undefined)
+        extra.label = label;
+      let draw = parseInt(query.get("draw") ?? "", 10);
+      if (Number.isFinite(draw))
+        extra.draw = draw;
+      return handleQuery(query, "gpu", extra);
     }
     case "/__control__/debug": {
       if (req.method !== "POST")
@@ -3765,6 +3772,7 @@ function onOpen(ws) {
     os: null,
     kernel: null,
     videoDriver: null,
+    refreshRate: null,
     gpu: null
   });
   console.log(`[cli] Client connected ${ws.remoteAddr ?? "unknown"}`);
@@ -3777,8 +3785,6 @@ function onClose(ws) {
   let info = state.clients.get(ws);
   state.clients.delete(ws);
   console.log(`[cli] Client disconnected: ${info?.platform ?? "unknown"}`);
-  if (config.client && localClientExited && state.clients.size === 0)
-    shutdown();
 }
 function onMessage(ws, msg) {
   try {
@@ -3801,6 +3807,7 @@ function onMessage(ws, msg) {
         os: text(data.os),
         kernel: text(data.kernel),
         videoDriver: text(data.videoDriver),
+        refreshRate: typeof data.refreshRate === "number" ? data.refreshRate : null,
         gpu: data.gpu && typeof data.gpu === "object" ? { vendor: text(data.gpu.vendor) ?? "", renderer: text(data.gpu.renderer) ?? "", version: text(data.gpu.version) ?? "" } : null
       });
       console.log(`[cli] Client info ${ws.remoteAddr ?? "unknown"} ${data.platform} (${data.version})`);
@@ -3870,7 +3877,6 @@ var keepalive = setInterval(() => {
 var shuttingDown = false;
 var stopRepl = () => {};
 var localClient = null;
-var localClientExited = false;
 var signalOffs = ["SIGINT", "SIGTERM"].map((signal) => onSignal(signal, () => {
   shutdown();
 }));
@@ -3924,13 +3930,7 @@ if (config.client) {
   pump(child.stderr, (line) => console.error(line));
   child.status().then(() => {
     localClient = null;
-    localClientExited = true;
-    if (shuttingDown)
-      return;
-    if (state.clients.size === 0) {
-      shutdown();
-    } else {
-      console.log(`[cli] Local client exited, ${state.clients.size} remote client(s) still connected`);
-    }
+    if (!shuttingDown)
+      console.log("[cli] Local client exited; the server keeps running (srt client reattaches)");
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.53",
+  "version": "0.0.54",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -30,16 +30,16 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@solidrt/darwin-arm64": "0.0.53",
-    "@solidrt/linux-arm64-gnu": "0.0.53",
-    "@solidrt/linux-x64-gnu": "0.0.53",
-    "@solidrt/win32-x64-msvc": "0.0.53"
+    "@solidrt/darwin-arm64": "0.0.54",
+    "@solidrt/linux-arm64-gnu": "0.0.54",
+    "@solidrt/linux-x64-gnu": "0.0.54",
+    "@solidrt/win32-x64-msvc": "0.0.54"
   },
   "peerDependencies": {
     "typescript": "^7"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.53",
+    "@solidrt/flux-types": "0.0.54",
     "@types/babel__core": "^7.20.5",
     "@types/bun": "latest"
   }

package/src/android/docs.md

@@ -8,8 +8,11 @@ file) in the current directory, or `--port`. A running instance is restarted
 so it picks the server up. The command then waits a few seconds for the
 client to appear on the server and reports its client id. The server must
 run with `--lan` so the device can reach it; an emulator reaches a loopback
-server through its host alias. `--device` picks one of several connected
-devices by serial or unique prefix.
+server through its host alias. Without a running server the client starts
+on its own, into the launcher (`--port` must name a live server). With several
+devices connected a terminal asks which ones (all preselected, so enter
+launches on every device); `--device` picks one by serial or unique prefix
+(a script must).
 
 `--install` installs (or updates) the client first, from the
 `@solidrt/android-<abi>` dev dependency matching the device's ABI; the

package/src/android/main.ts

@@ -3,6 +3,8 @@ import { networkInterfaces } from "node:os"
 import { resolve } from "node:path"
 import { androidPackageVersion, resolveApk, ANDROID_PKG_MAP } from "../lib/artifacts"
 import { values, port } from "../lib/args"
+import { CLI_VERSION } from "../lib/project"
+import { multiselect } from "../lib/prompt"
 import { resolveByPort, resolveFromCwd } from "../lib/registry"
 import type { LiveRecord } from "../types/registry"
 
@@ -97,14 +99,19 @@ function devServerAddress(adb: string, target: string, server: LiveRecord): stri
 }
 
 // The dev server the device should dial: --port picks a local server by
-// port, otherwise the project (or file) in the current directory.
-async function resolveServer(): Promise<LiveRecord> {
-  let resolved = port !== undefined ? await resolveByPort(port) : await resolveFromCwd(process.cwd())
-  if (!resolved.ok) {
-    console.error(resolved.message)
-    process.exit(1)
+// port (and must exist), otherwise the project (or file) in the current
+// directory, or none: the client then starts on its own, into the launcher.
+async function resolveServer(): Promise<LiveRecord | null> {
+  if (port !== undefined) {
+    let resolved = await resolveByPort(port)
+    if (!resolved.ok) {
+      console.error(resolved.message)
+      process.exit(1)
+    }
+    return resolved.record
   }
-  return resolved.record
+  let resolved = await resolveFromCwd(process.cwd())
+  return resolved.ok ? resolved.record : null
 }
 
 // Serials of connected, authorized devices (excludes offline/unauthorized).
@@ -132,25 +139,39 @@ function deviceAbi(adb: string, target: string): string {
   return res.stdout.toString().trim()
 }
 
-// Always shown up front, regardless of how many devices are connected or
-// whether --device narrows it down: one line per device with the ABI its APK
-// build would target, then (with --install) a dev-dependency hint for each
-// ABI that isn't resolvable locally yet. Returns the device->abi map so
-// callers don't have to re-query it.
-function printDeviceStatus(adb: string, devices: string[]): Map<string, string> {
-  let abiByDevice = new Map<string, string>()
-  let missingAbis = new Set<string>()
-  for (let d of devices) {
-    let abi = deviceAbi(adb, d)
-    abiByDevice.set(d, abi)
-    console.log(`${d} - ${abi}`)
-    if (!resolveApk(abi)) missingAbis.add(abi)
+// One line per connected device with the ABI its APK build would target;
+// the picker shows the same lines, so this is for the cases without one.
+function printDeviceStatus(devices: string[], abiByDevice: Map<string, string>) {
+  for (let d of devices) console.log(`${d} - ${abiByDevice.get(d)}`)
+}
+
+// A published CLI version (x.y.z): the release action publishes the CLI and
+// the android packages at one version, so that is the one to pin. A checkout
+// reports a git describe (or the 0.0.0 placeholder), which npm does not have.
+let RELEASE_VERSION = /^\d+\.\d+\.\d+$/
+
+// The APK for `abi`, adding the project's @solidrt/android-<abi> dev
+// dependency in the cwd first when it is not installed. ABIs without a
+// published package (e.g. x86) only resolve through SRT_HOME.
+function ensureApk(abi: string): string {
+  let apk = resolveApk(abi)
+  if (apk) return apk
+  let pkg = ANDROID_PKG_MAP[abi]
+  if (!pkg) {
+    console.error(`Could not find a SolidRT-Go APK for ABI "${abi}".`)
+    process.exit(1)
   }
-  let missingPkgs = [...missingAbis].map((abi) => ANDROID_PKG_MAP[abi]).filter((pkg): pkg is string => Boolean(pkg))
-  if (values.install && missingPkgs.length > 0) {
-    console.log(`Add dev dependencies with: bun add -d ${missingPkgs.join(" ")}`)
+  let spec = RELEASE_VERSION.test(CLI_VERSION) && CLI_VERSION !== "0.0.0" ? `${pkg}@${CLI_VERSION}` : pkg
+  console.log(`[cli] Adding dev dependency ${spec}`)
+  let add = Bun.spawnSync(["bun", "add", "-d", spec], { cwd: process.cwd(), stdout: "inherit", stderr: "inherit" })
+  if (add.exitCode !== 0) {
+    console.error(`Could not add ${spec}; retry with bun add -d ${spec}`)
+    process.exit(1)
   }
-  return abiByDevice
+  apk = resolveApk(abi)
+  if (apk) return apk
+  console.error(`${pkg} is installed but carries no solidrt-go.apk for ABI "${abi}".`)
+  process.exit(1)
 }
 
 // The versionName of the client installed on `target`, null when none is.
@@ -171,25 +192,31 @@ async function connectedClients(server: LiveRecord): Promise<Client[]> {
   }
 }
 
-// The first Android client that appears beyond `before`, or null after ~10 s.
-async function waitForClient(server: LiveRecord, before: Set<number>): Promise<Client | null> {
-  for (let attempt = 0; attempt < 20; attempt++) {
+// The Android clients that appear beyond `before`: all of them once `count`
+// have, else whatever showed up within ~10 s.
+async function waitForClients(server: LiveRecord, before: Set<number>, count: number): Promise<Client[]> {
+  let fresh: Client[] = []
+  for (let attempt = 0; attempt < 20 && fresh.length < count; attempt++) {
     await sleep(500)
-    let fresh = (await connectedClients(server)).find((c) => c.platform === "android" && !before.has(c.id))
-    if (fresh) return fresh
+    fresh = (await connectedClients(server)).filter((c) => c.platform === "android" && !before.has(c.id))
   }
-  return null
+  return fresh
 }
 
-// Resolve the target device serial (and its ABI). With --device, treat the
+type Device = { target: string; abi: string }
+
+// Resolve the target devices (serial and ABI). With --device, treat the
 // value as a serial prefix and require it to match exactly one connected
-// device; without it, use the sole connected device. Exits with a clear
-// message on any ambiguity.
-function resolveTarget(adb: string): { target: string; abi: string } {
+// device; without it, use the sole connected device, or pick any number of
+// several on a terminal (all preselected: enter means every device). Exits
+// with a clear message on any ambiguity.
+async function resolveTargets(adb: string): Promise<Device[]> {
   let devices = listDevices(adb)
-  let abiByDevice = printDeviceStatus(adb, devices)
+  let abiByDevice = new Map(devices.map((d) => [d, deviceAbi(adb, d)]))
+  let device = (target: string): Device => ({ target, abi: abiByDevice.get(target)! })
 
   if (values.device) {
+    printDeviceStatus(devices, abiByDevice)
     let prefix = values.device
     let matches = devices.filter((d) => d.startsWith(prefix))
     if (matches.length > 1) {
@@ -201,86 +228,108 @@ function resolveTarget(adb: string): { target: string; abi: string } {
       console.error(`No connected device matches --device "${prefix}".`)
       process.exit(1)
     }
-    return { target: match, abi: abiByDevice.get(match)! }
+    return [device(match)]
   }
 
   if (devices.length > 1) {
-    console.error("Pick one with --device <serial or prefix>.")
-    process.exit(1)
+    // The prompt's non-TTY default is no way to pick devices, so a script has
+    // to say which.
+    if (!process.stdin.isTTY) {
+      printDeviceStatus(devices, abiByDevice)
+      console.error("Pick one with --device <serial or prefix>.")
+      process.exit(1)
+    }
+    let picked = await multiselect(
+      "Pick devices",
+      devices.map((d) => ({ label: `${d} - ${abiByDevice.get(d)}`, value: d, checked: true })),
+    )
+    if (picked.length === 0) {
+      console.error("No device picked.")
+      process.exit(1)
+    }
+    return picked.map(device)
   }
+  printDeviceStatus(devices, abiByDevice)
   let [only] = devices
   if (!only) {
     console.error("No authorized Android device found. Enable USB debugging and check `adb devices`.")
     process.exit(1)
   }
-  return { target: only, abi: abiByDevice.get(only)! }
+  return [device(only)]
 }
 
-// Launch the Android client on a connected device over adb (installing it
-// first on --install), passing it the dev-server address to dial as a
-// launch-intent extra (see devServerAddress), then wait briefly for it to show
-// up on the dev server. The client is not a child process here: its lifecycle
-// is the WS connect/disconnect the server sees.
-export async function main() {
-  let server = await resolveServer()
-  let adb = requireAdb()
-
-  let { target, abi } = resolveTarget(adb)
-
+// Install the client on `target` (on --install), else check that one is there
+// and note when its version is not the one the project's package carries.
+async function prepare(adb: string, { target, abi }: Device) {
   if (values.install) {
-    let apk = resolveApk(abi)
-    if (!apk) {
-      console.error(`Could not find a SolidRT-Go APK for ABI "${abi}".`)
-      let pkg = ANDROID_PKG_MAP[abi]
-      if (pkg) console.error(`Add it with: bun add -d ${pkg}`)
-      process.exit(1)
-    }
+    let apk = ensureApk(abi)
     console.log(`[cli] Installing SolidRT-Go on ${target}`)
     let install = Bun.spawn([adb, "-s", target, "install", "-r", apk], { stdout: "pipe", stderr: "pipe" })
     if ((await install.exited) !== 0) {
       console.error("adb install failed:\n" + (await new Response(install.stderr).text()))
       process.exit(1)
     }
-  } else {
-    let installed = installedVersion(adb, target)
-    if (installed === null) {
-      console.error(`No SolidRT-Go client on ${target}; install one with srt android --install`)
-      process.exit(1)
-    }
-    let expected = androidPackageVersion(abi)
-    if (expected !== null && expected !== installed) {
-      console.log(
-        `[cli] Installed client is ${installed}; the project's ${ANDROID_PKG_MAP[abi]} is ${expected} (srt android --install updates it)`,
-      )
-    }
+    return
+  }
+  let installed = installedVersion(adb, target)
+  if (installed === null) {
+    console.error(`No SolidRT-Go client on ${target}; install one with srt android --install`)
+    process.exit(1)
   }
+  let expected = androidPackageVersion(abi)
+  if (expected !== null && expected !== installed) {
+    console.log(
+      `[cli] Installed client is ${installed}; the project's ${ANDROID_PKG_MAP[abi]} is ${expected} (srt android --install updates it)`,
+    )
+  }
+}
 
-  // Hand the client the dev-server address to dial, as a launch-intent extra that
-  // MainActivity forwards to native argv (--dev-server); the client auto-connects
-  // to it. Replaces adb reverse, which never worked over wireless adb. -S stops
-  // a running instance first: a delivered intent does not reach one, so without
-  // it the client would keep whatever server it had.
-  let before = new Set((await connectedClients(server)).map((c) => c.id))
-  let devServer = devServerAddress(adb, target, server)
+// Launch the client on `target`, handing it the dev-server address to dial as
+// a launch-intent extra that MainActivity forwards to native argv
+// (--dev-server); the client auto-connects to it. Replaces adb reverse, which
+// never worked over wireless adb. -S stops a running instance first: a
+// delivered intent does not reach one, so without it the client would keep
+// whatever server it had. With no server there is no extra to pass.
+async function launch(adb: string, { target }: Device, server: LiveRecord | null) {
+  let devServer = server ? devServerAddress(adb, target, server) : null
   let launchArgs = [adb, "-s", target, "shell", "am", "start", "-S", "-n", PACKAGE_ACTIVITY]
   if (devServer) {
-    console.log(`[cli] Client will dial dev server at ${devServer}`)
+    console.log(`[cli] Client on ${target} will dial dev server at ${devServer}`)
     launchArgs.push("--es", "srt_dev_server", devServer)
-  } else {
-    console.log("[cli] Could not resolve a host address for the device; client will need a manual/QR connect")
+  } else if (server) {
+    console.log(`[cli] Could not resolve a host address for ${target}; client will need a manual/QR connect`)
   }
-
   let start = Bun.spawn(launchArgs, { stdout: "pipe", stderr: "pipe" })
   if ((await start.exited) !== 0) {
     console.error("adb start failed:\n" + (await new Response(start.stderr).text()))
     process.exit(1)
   }
+  console.log(`[cli] Launched SolidRT-Go on ${target}`)
+}
+
+// Launch the Android client on the connected devices over adb (installing it
+// first on --install), then wait briefly for them to show up on the dev
+// server. The clients are not child processes here: their lifecycle is the
+// WS connect/disconnect the server sees.
+export async function main() {
+  let server = await resolveServer()
+  let adb = requireAdb()
+
+  let devices = await resolveTargets(adb)
+  for (let device of devices) await prepare(adb, device)
+
+  let before = new Set(server ? (await connectedClients(server)).map((c) => c.id) : [])
+  for (let device of devices) await launch(adb, device, server)
+  if (!server) return
 
-  console.log(`[cli] Launched SolidRT-Go on ${target}; waiting for it to connect to the dev server...`)
-  let client = await waitForClient(server, before)
-  if (client) {
+  console.log("[cli] Waiting for the client(s) to connect to the dev server...")
+  let clients = await waitForClients(server, before, devices.length)
+  for (let client of clients) {
     console.log(`[cli] Client ${client.id} connected (${client.platform}, ${client.version})`)
-  } else {
-    console.log(`[cli] No connection after 10 s. The server must run with --lan and the device must reach this machine.`)
   }
-}
+  if (clients.length < devices.length) {
+    console.log(
+      `[cli] ${devices.length - clients.length} of ${devices.length} not connected after 10 s. The server must run with --lan and the device must reach this machine.`,
+    )
+  }
+}

package/src/client/docs.md

@@ -6,4 +6,6 @@ The client half of [srt run](../server/docs.md), on its own. Without flags
 it attaches to the dev server of the project (or file) in the current
 directory; `--port` picks a local server by port and `--server` names any
 address, which is how a second machine joins a server started with `--lan`.
-A phone or tablet is [srt android](../android/docs.md).
+Without a running server the client starts on its own, into the launcher
+(`--port` and `--server` must name a live server). A phone or tablet is
+[srt android](../android/docs.md).

package/src/client/main.ts

@@ -4,13 +4,14 @@ import { resolveFromCwd } from "../lib/registry"
 
 // Standalone solidrt-go client (no dev server of its own). Without flags it
 // attaches to the dev server of the project (or file) in the current
-// directory, resolved from the registry; --port picks a local server by port
-// and --server names any address. A device is `srt android`.
+// directory, resolved from the registry, and starts on its own (into the
+// launcher) when there is none; --port picks a local server by port and
+// --server names any address, and those must exist. A device is `srt android`.
 export async function main() {
   let runner = requireBinary("solidrt-go")
   let args: string[] = [...clientStorageArgs()]
   if (values.size) args.push("--size", values.size)
-  let address: string
+  let address: string | null
   if (values.server) {
     if (!values.server.includes(":")) {
       console.error(`--server needs host:port (got "${values.server}"); dev servers have no fixed port`)
@@ -21,13 +22,9 @@ export async function main() {
     address = `127.0.0.1:${port}`
   } else {
     let resolved = await resolveFromCwd(process.cwd())
-    if (!resolved.ok) {
-      console.error(resolved.message)
-      process.exit(1)
-    }
-    address = `127.0.0.1:${resolved.record.port}`
+    address = resolved.ok ? `127.0.0.1:${resolved.record.port}` : null
   }
-  args.push("--dev-server", address)
+  if (address) args.push("--dev-server", address)
   let exit = await run(runner, args)
   process.exit(exit)
 }

package/src/init/main.ts

@@ -1,7 +1,7 @@
 import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises"
 import { basename, dirname, join, resolve } from "node:path"
 import { source, values } from "../lib/args"
-import { multiselect, note, text } from "./prompt"
+import { multiselect, note, text } from "../lib/prompt"
 
 const DEFAULT_NAME = "solidrt-app"
 

package/src/init/scaffold/AGENTS.md

@@ -90,8 +90,10 @@ platform-wide and bite in every app:
 
 ## Run / verify
 
-- FIRST check whether a dev server and a client are already running and
-  build against those; do not start a second `srt run` when one is up.
+- FIRST check whether a dev server and its clients (possibly several) are
+  already running and build against those; do not start a second `srt run`
+  when one is up. `reload` reaches every connected client; the per-client
+  tools are listed in debugging.md.
 - The dev loop (reload, logs, snapshots, the holds on reload-on-save and on
   the user's input), typechecking, headless rendering and the MCP tools:
   node_modules/@solidrt/cli/AGENTS.md and its agents/debugging.md. Read it

package/src/init/scaffold/package.json

@@ -10,14 +10,14 @@
     "android": "srt android"
   },
   "dependencies": {
-    "@solidrt/core": "0.0.53",
-    "@solidrt/components": "0.0.53",
-    "@solidrt/2d": "0.0.53",
-    "@solidrt/3d": "0.0.53"
+    "@solidrt/core": "0.0.54",
+    "@solidrt/components": "0.0.54",
+    "@solidrt/2d": "0.0.54",
+    "@solidrt/3d": "0.0.54"
   },
   "devDependencies": {
-    "@solidrt/cli": "0.0.53",
-    "@solidrt/flux-types": "0.0.53",
+    "@solidrt/cli": "0.0.54",
+    "@solidrt/flux-types": "0.0.54",
     "typescript": "^7"
   }
 }

package/src/mcp/main.ts

@@ -192,7 +192,7 @@ let TOOLS: {
     name: "list_clients",
     annotations: READ_ONLY,
     description:
-      "List the app clients connected to the SolidRT dev server, and what the server serves. Server fields: `generation` (identity of this server run; client ids, node ids and log cursors are only valid within one, so if it changed since your last call, re-fetch them), `key` and `mode` (the project root, or the single file, this server serves - check it is the app you intend to drive before acting), `entry` (the app source file it rebuilds; `load` moves it), `projectDir` (null for a file served on its own), `userInputMuted` (see mute_user_input) and `watchPaused` (see pause_watch). Per client: `id` (pass it as `client` to the other tools), `platform`, `version` (the runtime's git describe; a -dirty suffix means it was built from uncommitted engine changes), `profile` (debug/release), `capabilities` (the capability names compiled into that runtime), `queries` (the dev-tool query kinds that runtime answers: clock, input, snapshot, tree, ...; a list without \"input\" predates send_input, one without \"clock\" predates set_time_scale/step_frames, an empty list predates the advertisement itself - check it before planning a verification strategy), `stats` (whether its overlay is drawn, see set_stats_overlay), `timeScale` (its clock as it last answered set_time_scale/step_frames: 0 paused, 1 real time; back to 1 on every reload), and what the client knows about itself: `clientDir` (its storage tree on its own machine, `<data-root>/client<N>` for a dev client), `pid`, `execPath` (the runtime binary), `host` (hostname), `os` and `kernel` (the OS as a person names it, e.g. \"Android 15 on Pixel 9 Pro\", and the kernel version), `videoDriver` (SDL's: wayland, x11, android, ...) and `gpu` (vendor, renderer, version as GL reports them) - each null on a runtime that predates it or has no such fact. Use version/profile to check whether a connected binary contains a given engine change before debugging against it.",
+      "List the app clients connected to the SolidRT dev server, and what the server serves. Server fields: `generation` (identity of this server run; client ids, node ids and log cursors are only valid within one, so if it changed since your last call, re-fetch them), `key` and `mode` (the project root, or the single file, this server serves - check it is the app you intend to drive before acting), `entry` (the app source file it rebuilds; `load` moves it), `projectDir` (null for a file served on its own), `userInputMuted` (see mute_user_input) and `watchPaused` (see pause_watch). Per client: `id` (pass it as `client` to the other tools), `platform`, `version` (the runtime's git describe; a -dirty suffix means it was built from uncommitted engine changes), `profile` (debug/release), `capabilities` (the capability names compiled into that runtime), `queries` (the dev-tool query kinds that runtime answers: clock, input, snapshot, tree, ...; a list without \"input\" predates send_input, one without \"clock\" predates set_time_scale/step_frames, an empty list predates the advertisement itself - check it before planning a verification strategy), `stats` (whether its overlay is drawn, see set_stats_overlay), `timeScale` (its clock as it last answered set_time_scale/step_frames: 0 paused, 1 real time; back to 1 on every reload), and what the client knows about itself: `clientDir` (its storage tree on its own machine, `<data-root>/client<N>` for a dev client), `pid`, `execPath` (the runtime binary), `host` (hostname), `os` and `kernel` (the OS as a person names it, e.g. \"Android 15 on Pixel 9 Pro\", and the kernel version), `videoDriver` (SDL's: wayland, x11, android, ...), `refreshRate` (the display's nominal refresh rate in Hz as SDL reported it at connect, what `onFrame`'s `rate` argument carries; null when the client connected before its window existed, a reconnect fills it in) and `gpu` (vendor, renderer, version as GL reports them) - each null on a runtime that predates it or has no such fact. Use version/profile to check whether a connected binary contains a given engine change before debugging against it.",
     inputSchema: {},
   },
   {
@@ -232,7 +232,7 @@ let TOOLS: {
     name: "get_stats",
     annotations: READ_ONLY,
     description:
-      "Performance statistics from a running app client. Start with `window`: a summary of the frames rebuilt in the last window_ms (default 5000, max 10000) - frames, p50Ms/p95Ms/maxMs of the JS-thread critical path per frame (render handler + layout + postLayout + paint + hover), slowFrames (frames over the refresh period, periodMs), and `worst`, the single most expensive frame with its ageMs, phase breakdown (jsMs/layoutMs/postLayoutMs/paintMs/hoverMs) and that frame's own layout activity (paraShapes, measureCalls, dirtiedNodes, cacheGets/cacheHits, nodesPainted). This is where jank shows: the smoothed figures below average a one-frame hitch away, the window keeps it. Typical flow: send_input a burst (typing, a drag), then get_stats - `frames: 0` means nothing was rebuilt in the window (idle app), which is different from all-fast. The window also carries rates for the GPU counters when it spans 2+ frames: fenceTimeoutsPerSec, gpuPassesPerFrame (per presented frame), gpuPassIssueMsPerFrame, gpuPassExecMsPerFrame, gpuFrameExecMsPerFrame, rasterCmdMsPerSec - read these instead of differencing the cumulatives yourself. timeMs (client monotonic clock) and frame (present index) stamp the payload so two samples can be differenced. Then the smoothed figures: fps, CPU%, memory, smoothed JS/layout/paint/hover frame times (ms), setProperty writes per frame, demand-gate reuse/skip counts per second, and live texture count. Layout-activity counters cover the last full rebuild, raw: nodes (live node count, mounted AND detached), mountedNodes/orphanNodes (live at query time: nodes reachable from the root vs not - orphans growing at a stable tree shape mean an unmount leak; absent when no engine is running), measureCalls (text measures; mostly cache hits, cheap), paraShapes (paragraphs actually shaped, i.e. words the shared word cache did not have; the expensive signal - high layoutMs with near-zero paraShapes means the cost is not text shaping), wordHits (words answered from the shared word cache; hits high and paraShapes near zero on a text change means only the changed words were reshaped), dirtiedNodes (layout caches cleared by property writes since the previous rebuild; how much of the tree a write burst invalidated), cacheGets/cacheHits (layout-cache lookups during the rebuild; a hit on a container skips its whole subtree, so a healthy incremental rebuild shows a near-100% hit rate - a low rate at scale means the layout cache is being defeated), nodesPainted (nodes the latest frame's paint walk entered, 0 when that frame reused the display list - the last rebuild's count is in `window.worst`; mountedNodes minus this is what viewport culling skipped - a long scroller should paint a near-constant number of nodes however long its content). GPU-side health, read live at query time (absent when no engine is running): rasterQueue (raster commands sent but not yet executed at the instant of the query, including the one executing; the frame command blocks on vsync in it, so 1 while frames flow is normal - it is a backlog signal only when it climbs across queries while fps drops; a persistently high idle reading has been seen once on a Windows client and is unexplained, so do not conclude from this field alone), idleTicks (cumulative idle frame signals emitted while the GPU had nothing queued; idleTicks racing while rasterQueue sits nonzero would mean the idle-tick gate is broken), fenceTimeouts (cumulative present-fence waits that expired instead of signaling - each one is a frame where the GPU was over budget for 100ms+ and one-frame-in-flight pacing was lost; zero on a healthy machine, climbing means the GPU is the bottleneck right now), gpuPasses/gpuPassIssueMs/gpuPassExecMs (cumulative shader/pipeline target renders on the raster thread, the wall time the raster thread spent issuing them, and the GPU-side time executing them, all in whole ms - diff two queries to get a rate; passes racing far ahead of frames means redundant target re-renders, the failure mode where fps and frameMs look healthy while the raster thread drowns; issue and exec are different clocks: a pass with a heavy fragment shader is cheap to issue and expensive to execute, so a busy GPU with a small issue figure is normal, and gpuPassExecMs is the number to compare against the refresh period. gpuPassExecMs comes from GL timer queries and lags the pass by a frame or two; it is absent, not 0, when the client's context has none), gpuFrameExecMs (cumulative GPU-side time executing the window draw of each presented frame - the display list plus any window shader, excluding the pass flush and the present - from the same timer queries, same absence rule; gpuFrameExecMsPerFrame in the window is the number to hold against periodMs: near or above it, the GPU is the bottleneck and fenceTimeouts follow, while a healthy jsMs says nothing about it), rasterCmdMs (cumulative wall time in whole ms the raster thread spent executing non-frame commands - texture uploads, readbacks, offscreen rasterizations, shader compiles, param writes and the target re-renders they trigger; the work frameMs never sees, so rasterCmdMs growing much faster than frames are presented means the raster thread is drowning in side work even if every counter above looks calm).",
+      "Performance statistics from a running app client. Start with `window`: a summary of the frames that changed the picture in the last window_ms (default 5000, max 10000): tree rebuilds, plus GPU content changes presented without one (a layer write, a shader param, an upload: a sprite or shader app's every frame, where the critical path is the render handler alone) - frames, p50Ms/p95Ms/maxMs of the JS-thread critical path per frame (render handler + layout + postLayout + paint + hover), slowFrames (frames over the refresh period, periodMs), and `worst`, the single most expensive frame with its ageMs, phase breakdown (jsMs/layoutMs/postLayoutMs/paintMs/hoverMs) and that frame's own layout activity (paraShapes, measureCalls, dirtiedNodes, cacheGets/cacheHits, nodesPainted). This is where jank shows: the smoothed figures below average a one-frame hitch away, the window keeps it. Typical flow: send_input a burst (typing, a drag), then get_stats - `frames: 0` means nothing changed the picture in the window (idle app), which is different from all-fast. The window also carries rates for the GPU counters when it spans 2+ frames: fenceTimeoutsPerSec, gpuPassesPerFrame (per presented frame), gpuPassIssueMsPerFrame, gpuPassExecMsPerFrame, gpuFrameExecMsPerFrame, rasterCmdMsPerSec - read these instead of differencing the cumulatives yourself. timeMs (client monotonic clock) and frame (present index) stamp the payload so two samples can be differenced. Then the smoothed figures: fps, CPU%, memory, smoothed JS/layout/paint/hover frame times (ms), setProperty writes per frame, demand-gate reuse/skip counts per second, and live texture count. Layout-activity counters cover the last full rebuild, raw: nodes (live node count, mounted AND detached), mountedNodes/orphanNodes (live at query time: nodes reachable from the root vs not - orphans growing at a stable tree shape mean an unmount leak; absent when no engine is running), measureCalls (text measures; mostly cache hits, cheap), paraShapes (paragraphs actually shaped, i.e. words the shared word cache did not have; the expensive signal - high layoutMs with near-zero paraShapes means the cost is not text shaping), wordHits (words answered from the shared word cache; hits high and paraShapes near zero on a text change means only the changed words were reshaped), dirtiedNodes (layout caches cleared by property writes since the previous rebuild; how much of the tree a write burst invalidated), cacheGets/cacheHits (layout-cache lookups during the rebuild; a hit on a container skips its whole subtree, so a healthy incremental rebuild shows a near-100% hit rate - a low rate at scale means the layout cache is being defeated), nodesPainted (nodes the latest frame's paint walk entered, 0 when that frame reused the display list - the last rebuild's count is in `window.worst`; mountedNodes minus this is what viewport culling skipped - a long scroller should paint a near-constant number of nodes however long its content). GPU-side health, read live at query time (absent when no engine is running): rasterQueue (raster commands sent but not yet executed at the instant of the query, including the one executing; the frame command blocks on vsync in it, so 1 while frames flow is normal - it is a backlog signal only when it climbs across queries while fps drops; a persistently high idle reading has been seen once on a Windows client and is unexplained, so do not conclude from this field alone), idleTicks (cumulative idle frame signals emitted while the GPU had nothing queued; idleTicks racing while rasterQueue sits nonzero would mean the idle-tick gate is broken), fenceTimeouts (cumulative present-fence waits that expired instead of signaling - each one is a frame where the GPU was over budget for 100ms+ and one-frame-in-flight pacing was lost; zero on a healthy machine, climbing means the GPU is the bottleneck right now), gpuPasses/gpuPassIssueMs/gpuPassExecMs (cumulative shader/pipeline target renders on the raster thread, the wall time the raster thread spent issuing them, and the GPU-side time executing them, all in whole ms - diff two queries to get a rate; passes racing far ahead of frames means redundant target re-renders, the failure mode where fps and frameMs look healthy while the raster thread drowns; issue and exec are different clocks: a pass with a heavy fragment shader is cheap to issue and expensive to execute, so a busy GPU with a small issue figure is normal, and gpuPassExecMs is the number to compare against the refresh period. gpuPassExecMs comes from GL timer queries and lags the pass by a frame or two; it is absent, not 0, when the client's context has none), gpuFrameExecMs (cumulative GPU-side time executing the window draw of each presented frame - the display list plus any window shader, excluding the pass flush and the present - from the same timer queries, same absence rule; gpuFrameExecMsPerFrame in the window is the number to hold against periodMs: near or above it, the GPU is the bottleneck and fenceTimeouts follow, while a healthy jsMs says nothing about it), rasterCmdMs (cumulative wall time in whole ms the raster thread spent executing non-frame commands - texture uploads, readbacks, offscreen rasterizations, shader compiles, param writes and the target re-renders they trigger; the work frameMs never sees, so rasterCmdMs growing much faster than frames are presented means the raster thread is drowning in side work even if every counter above looks calm).",
     inputSchema: {
       window_ms: z
         .number()
@@ -321,9 +321,10 @@ let TOOLS: {
     name: "get_gpu_resources",
     annotations: READ_ONLY,
     description:
-      "Inventory of a running app client's GPU resources: textures (id, size, whether a shader renders into it), vertex buffers (id, byteLength), and shader/pipeline targets (output textureId, kind, bufferId, topology, drawCount plus firstVertex/instanceCount when off their 0/1 defaults, depth, attribute layout, bound sampler texture ids, current uniform values - the most recent writes, which the next frame or readback draws with - plus passes/issueMs/execMs, cumulative per-target render count, raster-thread issue time and GPU-side execution time in whole ms: when get_stats shows gpuPasses or gpuPassExecMs running hot, these attribute the cost to the specific target). Use it when the render tree is just a <texture> leaf and the interesting state lives behind it; follow up with get_texture or get_buffer to see contents. Pass `label` to keep only the resources created with exactly that debug label (the create's `label` option) - the stable way to find a target again after a reload, since ids change.",
+      "Inventory of a running app client's GPU resources: textures (id, size, whether a shader renders into it), vertex buffers (id, byteLength), and shader/pipeline targets (output textureId, kind, bufferId, topology, drawCount plus firstVertex/instanceCount when off their 0/1 defaults, depth, attribute layout, bound sampler texture ids, current uniform values - the most recent writes, which the next frame or readback draws with - plus passes/issueMs/execMs, cumulative per-target render count, raster-thread issue time and GPU-side execution time in whole ms: when get_stats shows gpuPasses or gpuPassExecMs running hot, these attribute the cost to the specific target). Use it when the render tree is just a <texture> leaf and the interesting state lives behind it; follow up with get_texture or get_buffer to see contents. Pass `label` to keep only the resources created with exactly that debug label (the create's `label` option) - the stable way to find a target again after a reload, since ids change. In a draw target's entry list, uniforms wider than a vec4 (matrices) are elided to their length (\"[16]\") so a model's hundred entries stay readable; pass `draw` (an entry id from that list, with `label` to pin the target, since entry ids are per target) to get that one entry's params in full.",
     inputSchema: {
       label: z.string().describe("Keep only resources whose create label equals this").optional(),
+      draw: z.number().int().describe("Draw entry id whose params are reported in full (pair with label)").optional(),
       client: CLIENT_ARG,
     },
   },
@@ -565,6 +566,7 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
     case "get_gpu_resources": {
       let params = new URLSearchParams()
       if (typeof args?.label === "string") params.set("label", args.label)
+      if (typeof args?.draw === "number") params.set("draw", String(args.draw))
       if (typeof args?.client === "number") params.set("client", String(args.client))
       let qs = params.toString()
       return control(`/gpu${qs ? `?${qs}` : ""}`)

package/src/server/control.ts

@@ -81,6 +81,7 @@ export function clientList(withAddress = false): (ClientEntry & { address?: stri
     os: info.os,
     kernel: info.kernel,
     videoDriver: info.videoDriver,
+    refreshRate: info.refreshRate,
     gpu: info.gpu,
     ...(withAddress ? { address: ws.remoteAddr ?? null } : {}),
   }))
@@ -410,9 +411,15 @@ export async function handleControl(req: Request, path: string, query: Map<strin
       return handleQuery(query, "snapshot", extra)
     }
     case "/__control__/gpu": {
-      // ?label=<text> keeps only resources created with exactly that label.
+      // ?label=<text> keeps only resources created with exactly that label;
+      // ?draw=<id> reports that draw entry's params in full (matrix-valued
+      // params are elided everywhere else).
+      let extra: Record<string, unknown> = {}
       let label = query.get("label")
-      return handleQuery(query, "gpu", label === undefined ? undefined : { label })
+      if (label !== undefined) extra.label = label
+      let draw = parseInt(query.get("draw") ?? "", 10)
+      if (Number.isFinite(draw)) extra.draw = draw
+      return handleQuery(query, "gpu", extra)
     }
     case "/__control__/debug": {
       // GET lists the app's registered debug commands; POST calls one, with

package/src/server/docs.md

@@ -2,6 +2,8 @@
 
 `run` is the everyday command: it starts the dev server and a local client
 window together, and it is what `bun run dev` calls in a scaffolded project.
+The server outlives the client: closing (or killing) a wedged client keeps
+the server up, and `srt client` reattaches a new one.
 
 {{ usage run }}
 

package/src/server/main.ts

@@ -248,6 +248,7 @@ function onOpen(ws: ServerWebSocket) {
     os: null,
     kernel: null,
     videoDriver: null,
+    refreshRate: null,
     gpu: null,
   })
   console.log(`[cli] Client connected ${ws.remoteAddr ?? "unknown"}`)
@@ -263,10 +264,6 @@ function onClose(ws: ServerWebSocket) {
   let info = state.clients.get(ws)
   state.clients.delete(ws)
   console.log(`[cli] Client disconnected: ${info?.platform ?? "unknown"}`)
-  // `srt run` lives as long as its clients: once the local client is gone,
-  // the last remote disconnect ends the server. `srt server` runs until
-  // stopped.
-  if (config.client && localClientExited && state.clients.size === 0) shutdown()
 }
 
 function onMessage(ws: ServerWebSocket, msg: string | Uint8Array) {
@@ -290,6 +287,7 @@ function onMessage(ws: ServerWebSocket, msg: string | Uint8Array) {
         os: text(data.os),
         kernel: text(data.kernel),
         videoDriver: text(data.videoDriver),
+        refreshRate: typeof data.refreshRate === "number" ? data.refreshRate : null,
         gpu:
           data.gpu && typeof data.gpu === "object"
             ? { vendor: text(data.gpu.vendor) ?? "", renderer: text(data.gpu.renderer) ?? "", version: text(data.gpu.version) ?? "" }
@@ -399,7 +397,6 @@ let keepalive = setInterval(() => {
 let shuttingDown = false
 let stopRepl = () => {}
 let localClient: Child | null = null
-let localClientExited = false
 let signalOffs = ["SIGINT", "SIGTERM"].map((signal) =>
   onSignal(signal, () => {
     shutdown()
@@ -463,14 +460,11 @@ if (config.client) {
   localClient = child
   pump(child.stdout, (line) => console.log(line))
   pump(child.stderr, (line) => console.error(line))
+  // The server outlives its client: a wedged or crashed client is restarted
+  // with `srt client` (it reattaches by cwd) without losing the server, its
+  // bundle, the watcher or the MCP session. The server stops on quit/signal.
   child.status().then(() => {
     localClient = null
-    localClientExited = true
-    if (shuttingDown) return
-    if (state.clients.size === 0) {
-      shutdown()
-    } else {
-      console.log(`[cli] Local client exited, ${state.clients.size} remote client(s) still connected`)
-    }
+    if (!shuttingDown) console.log("[cli] Local client exited; the server keeps running (srt client reattaches)")
   })
 }

package/src/types/control.d.ts

@@ -35,6 +35,11 @@ export type ClientEntry = {
   kernel: string | null
   /** The SDL video driver ("wayland", "x11", "android", "offscreen", ...). */
   videoDriver: string | null
+  /** The display's nominal refresh rate in Hz as SDL reported it when the
+   * client connected (what `onFrame`'s `rate` argument carries); null on a
+   * runtime that predates it, or on a client that connected before its
+   * window existed (a reconnect fills it in). */
+  refreshRate: number | null
   /** The GPU strings as GL reports them; null on a client that connected
    * before its GL context existed (a reconnect fills it in). */
   gpu: GpuInfo | null