@solidrt/cli 0.0.52 → 0.0.54

package/src/demo/main.ts

@@ -1,34 +1,36 @@
 import { readdirSync } from "node:fs"
-import { join, resolve } from "node:path"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
 import { source } from "../lib/args"
 
-// srt demo: the demos the installed @solidrt packages ship. A package's
-// demos are ONE project (`<package>/demos/`: package.json, one assets/, and
-// src/<name>.tsx per demo), so a demo runs as the project it lives in - this
-// file only lists and resolves, and main.ts starts the ordinary dev server
-// with its cwd set to that project. Nothing downstream knows about demos.
+// srt demo: the package demos the CLI ships pre-bundled (dist/demos/, built
+// by `make -C packages/cli demos`: the release workflow before publishing, a
+// checkout after editing a demo or its package). dist/demos/<pkg>/ is the
+// package's demos project as the dev server serves it - package.json,
+// assets/, and <slug>/<slug>.srt.js per demo - so a demo runs as the project
+// it lives in: this file only lists and resolves, and main.ts starts the
+// ordinary dev server with its cwd set to that project. Nothing downstream
+// knows about demos, and a demo shows up in the console like any app.
 
 export type Demo = { name: string; cwd: string; entry: string }
 
-const SCOPE = join("node_modules", "@solidrt")
+const DEMOS = fileURLToPath(new URL("../../dist/demos", import.meta.url))
 
-/** Every demo installed here, sorted so the printed numbers are stable.
- * The cwd and nothing above it - the same rule the server's mode resolution
- * follows (server/mode.ts), so this lists what THIS project installed. */
+/** Every demo the CLI ships, sorted so the printed numbers are stable. */
 function discover(): Demo[] {
   let demos: Demo[] = []
-  for (let pkg of names(SCOPE)) {
-    let dir = join(SCOPE, pkg, "demos")
-    for (let file of names(join(dir, "src"))) {
-      if (!file.endsWith(".tsx")) continue
-      demos.push({ name: `${pkg}/${file.slice(0, -".tsx".length)}`, cwd: resolve(dir), entry: join("src", file) })
+  for (let pkg of names(DEMOS)) {
+    let cwd = join(DEMOS, pkg)
+    for (let slug of names(cwd)) {
+      let entry = join(slug, `${slug}.srt.js`)
+      if (names(join(cwd, slug)).includes(`${slug}.srt.js`)) demos.push({ name: `${pkg}/${slug}`, cwd, entry })
     }
   }
   return demos
 }
 
-// A missing folder is the normal case (most packages ship no demos), so it
-// reads as an empty one rather than an error.
+// A missing folder reads as an empty one: a checkout without a demos build
+// has none, and assets/ is a sibling of the demo dirs, not one of them.
 function names(dir: string): string[] {
   try {
     return readdirSync(dir).sort()
@@ -45,7 +47,7 @@ function list(demos: Demo[]) {
 export async function main(): Promise<{ cwd: string; entry: string } | undefined> {
   let demos = discover()
   if (demos.length === 0) {
-    console.error(`No demos installed in ${process.cwd()} (looked in ${SCOPE}/*/demos/src/)`)
+    console.error("Demos not built: run make -C packages/cli demos")
     process.exit(1)
   }
 

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

@@ -11,7 +11,9 @@ should open whenever the work matches its trigger.
 - @solidrt/core is the low-level foundation: host intrinsics (`<window>`,
   `<view>`, `<text>`, the detached `d-*` drawing primitives) with flat props
   that feed the layout and paint engine directly. An app can be written
-  entirely at this level.
+  entirely at this level. d-* elements go under anything; laid-out elements
+  only under laid-out parents (a `<view>` inside a `<d-view>` throws), so a
+  component's doc comment says which kind it renders.
 - Extensions build on core. The first-party ones are @solidrt/components
   (UI components), @solidrt/2d (2D graphics) and @solidrt/3d (3D graphics).
   None is privileged - an extension is just functions returning core JSX,
@@ -88,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.52",
-    "@solidrt/components": "0.0.52",
-    "@solidrt/2d": "0.0.52",
-    "@solidrt/3d": "0.0.52"
+    "@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.52",
-    "@solidrt/flux-types": "0.0.52",
+    "@solidrt/cli": "0.0.54",
+    "@solidrt/flux-types": "0.0.54",
     "typescript": "^7"
   }
 }

package/src/lib/usage.ts

@@ -27,7 +27,7 @@ Commands:
   run [file]             Start dev server + local solidrt-go client
   server [file]          Start dev server only
   client                 Start solidrt-go client only
-  demo [<number>]        List the demos the installed packages ship, or run one
+  demo [<number>]        List the demos the CLI ships, or run one
   tool [<pkg>/<name>]    List the tools the installed packages ship, or run one
                          (everything after the tool name is the tool's own arguments)
   console                Start the dev console: the dev servers on this machine and their clients

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) ?? "" }
@@ -348,18 +346,21 @@ function bind(port: number): Server {
   })
 }
 
-// A bind alone does not prove a port free: with SO_REUSEADDR (the default
-// on a listener) Linux lets a loopback bind coexist with another process's
+// A bind alone does not prove a port free: on macOS (BSD SO_REUSEADDR, the
+// default on a listener) a loopback bind coexists with another process's
 // all-interfaces listener on the same port, and the newcomer then silently
-// takes the loopback traffic. So each candidate is dialed first; only a
-// refusal means free.
+// takes the loopback traffic; Linux and Windows refuse the second bind. So
+// each candidate is dialed first, and an answer means taken. Anything else
+// is left to the bind: a refusal cannot be waited for, because Windows only
+// reports one after ~2 s of SYN retries, so it reads as filtered within the
+// probe budget and the bind is the truth.
 async function bindFirstFree(): Promise<Server> {
   if (config.port !== undefined) return bind(config.port)
   let candidates: number[] = remembered !== null ? [remembered] : []
   for (let p = DEFAULT_PORT; p < DEFAULT_PORT + PORT_TRIES; p++) candidates.push(p)
   let last: unknown = null
   for (let port of candidates) {
-    if ((await probe("127.0.0.1", port, { timeoutMs: 200 })) !== "closed") continue
+    if ((await probe("127.0.0.1", port, { timeoutMs: 200 })) === "open") continue
     try {
       return bind(port)
     } catch (e) {
@@ -396,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()
@@ -460,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