@solidrt/cli 0.0.52 → 0.0.54

package/dist/demos/components/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "solidrt-components-demos",
+  "type": "module",
+  "private": true,
+  "solidrt": {
+    "appId": "dev.solidrt.demos.components",
+    "displayName": "Gallery"
+  }
+}

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})`);
@@ -3842,7 +3849,7 @@ async function bindFirstFree() {
     candidates.push(p);
   let last = null;
   for (let port of candidates) {
-    if (await probe("127.0.0.1", port, { timeoutMs: 200 }) !== "closed")
+    if (await probe("127.0.0.1", port, { timeoutMs: 200 }) === "open")
       continue;
     try {
       return bind(port);
@@ -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.52",
+  "version": "0.0.54",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -24,22 +24,22 @@
     "@jridgewell/remapping": "^2.3.0",
     "@jridgewell/trace-mapping": "^0.3.25",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "babel-preset-solid": "2.0.0-rc.1",
+    "@solidjs/babel-plugin": "2.0.0-rc.3",
     "bonjour-service": "^1.4.0",
     "qrcode-generator": "^2.0.4",
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@solidrt/darwin-arm64": "0.0.52",
-    "@solidrt/linux-arm64-gnu": "0.0.52",
-    "@solidrt/linux-x64-gnu": "0.0.52",
-    "@solidrt/win32-x64-msvc": "0.0.52"
+    "@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.52",
+    "@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/bundle/bundler.ts

@@ -2,7 +2,7 @@ import { transformAsync } from "@babel/core"
 import jsx from "@babel/plugin-syntax-jsx"
 import ts from "@babel/preset-typescript"
 import remapping from "@jridgewell/remapping"
-import solid from "babel-preset-solid"
+import solid from "@solidjs/babel-plugin"
 import { type BunPlugin, type BuildArtifact } from "bun"
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
 import { dirname, join, relative, resolve as resolvePath, sep } from "node:path"
@@ -76,7 +76,7 @@ async function codeFromOutputs(outputs: BuildArtifact[]): Promise<string> {
   return code
 }
 
-// Bun build plugin that runs JSX/TSX through babel-preset-solid (universal
+// Bun build plugin that runs JSX/TSX through @solidjs/babel-plugin (universal
 // generate, targeting @solidrt/core) plus the TS preset. `moduleName` only ends
 // up as an import specifier in the emitted code, resolved from the app's tree at
 // bundle time; the CLI itself never loads core, so core is deliberately neither
@@ -108,8 +108,8 @@ function solidPlugin(inputs: Set<string>, babelMaps?: Map<string, object>, isola
         let transforms = await transformAsync(code, {
           filename: args.path,
           sourceMaps: !!babelMaps,
-          presets: [[solid, { moduleName: "@solidrt/core", generate: "universal" }], [ts]],
-          plugins: [jsx, inlineImport(inputs)],
+          presets: [[ts]],
+          plugins: [jsx, [solid, { moduleName: "@solidrt/core", generate: "universal" }], inlineImport(inputs)],
         })
         if (babelMaps && transforms?.map) babelMaps.set(args.path, transforms.map)
         return { contents: transforms?.code ?? "", loader: "js" }

package/src/bundle/untyped-deps.d.ts

@@ -11,8 +11,8 @@ declare module "@babel/preset-typescript" {
   let preset: PluginItem
   export default preset
 }
-declare module "babel-preset-solid" {
+declare module "@solidjs/babel-plugin" {
   import { type PluginItem } from "@babel/core"
-  let preset: PluginItem
-  export default preset
+  let plugin: PluginItem
+  export default plugin
 }

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/demo/docs.md

@@ -2,26 +2,32 @@
 
 {{ usage demo }}
 
-The demos that come with the packages this project installs. Without an
-argument it lists them, numbered:
+The demos the SolidRT packages come with, shipped pre-bundled with the CLI so
+every install has all of them, whether or not the packages themselves are
+installed. Without an argument it lists them, numbered:
 
 ```
   1  3d/the-third-dimension
+  2  components/gallery
 ```
 
 `srt demo 1` runs that one, exactly as [srt run](../server/docs.md) runs any
-project: a dev server, a local client window, reload on save, and the same
-server options (`--lan` to reach it from a device, `--port`, `--tunnel`). The qualified
-name works too (`srt demo 3d/the-third-dimension`), which is the stable way to
-name one in a script - the numbers follow the list, and the list follows what
-is installed.
+project: a dev server and a local client window, with the same server
+options (`--lan` to reach it from a device, `--port`, `--tunnel`). So a
+running demo is an app the [console](../console/docs.md) picks up like any
+other, with its tree, stats and control API. The qualified name works too
+(`srt demo 3d/the-third-dimension`), which is the stable way to name one in
+a script - the numbers follow the list.
 
-A package keeps its demos in `demos/`, and that folder is one project: its own
-package.json, one `assets/` folder, and `src/<name>.tsx` per demo. So the
-demos of one package share a dev server and a port - start a second one while
-the first is up and it says so. Demos from different packages run side by
-side.
+A package keeps its demos in `demos/` in the repository, and that folder is
+one project: its own package.json, one `assets/` folder, and `src/<name>.tsx`
+per demo. The CLI ships that project bundled (`dist/demos/<package>/`, built
+by `make -C packages/cli demos`), and `srt demo` serves it with the chosen
+bundle as its entry. So the demos of one package share a dev server and a
+port - start a second one while the first is up and it says so. Demos from
+different packages run side by side.
 
-The demos ship inside the packages, so `node_modules` is where they are found:
-`srt demo` looks in the current directory and nowhere above it. Run it from
-the project root.
+The bundles are what runs, so editing a demo's source does not reload it. In
+a checkout, work on a demo with `srt run src/<name>.tsx --project` from the
+package's `demos/` folder, and rebuild the shipped bundles with
+`make -C packages/cli demos` when done.