@solidrt/cli 0.0.48 → 0.0.50

package/AGENTS.md

@@ -24,7 +24,11 @@ bundled `flux` runtime, not on Bun. Invoke via `bunx srt <command>`.
   separately (server distributes code; clients on other devices connect to it).
 - `bunx srt run src/index.tsx --capture out.script.json` - records keydown/keyup
   from every connected client into one script file (written on client
-  disconnect), for replaying later with `render --script`.
+  disconnect), for replaying later with `render --script`. The file is JSON
+  Lines and hand-authorable - the exact shape (`after` ms, `type`, `key`,
+  `device`) is in `docs/cli.md` under `--capture`. For probing app state
+  without a display, `-- <args...>` reaches the app as `flux:process` argv
+  (also `docs/cli.md`), which is often simpler than scripting input.
 
 ## Verifying without a display (headless / CI / agent box)
 
@@ -35,7 +39,8 @@ Two reliable checks that need no GUI:
    renders offscreen via EGL and writes `frame-NNNNNN.png`. This actually
    proves the app renders. Combine with `--fps`/`--duration` (defaults
    1280x720, 60fps, 1s). No display needed: rendering uses SDL's offscreen
-   driver (falling back to a hidden window where EGL cannot go headless).
+   driver, or alloy's own EGL pbuffer where that driver cannot go headless
+   (see the ANGLE gotcha below).
 
 Also headless: the bundled flux runtime runs a plain `.js` file directly -
 `node_modules/@solidrt/<platform>/flux script.js` (e.g.
@@ -49,12 +54,38 @@ behavior in isolation.
 - `--size` is physical output pixels: layout runs at exactly that size
   (display scale is pinned to 1), so frames are identical on every machine.
 - Run from the project directory. There is no `bunx --cwd` flag.
+- On ANGLE stacks (Windows, macOS) SDL's offscreen driver cannot go
+  headless (no EGL device enumeration), so `render` there builds its own
+  EGL pbuffer context behind SDL's dummy video driver instead; the log says
+  "using a headless EGL context". If that also fails it renders into a
+  hidden window, which needs an interactive desktop session (fails under a
+  service, in Session 0, or over SSH-only). Verified headless on Linux
+  (Wayland) and the pbuffer path on Windows from a desktop session; a
+  non-interactive Windows session and macOS are unverified.
+
+## Sessions (parallel dev servers on one machine)
+
+- `-s <N>` / `--session <N>` (default 0) picks the dev server: port
+  `34884 + N`. Valid on `run`, `server`, `client`, `mcp`. `srt run -s1` is a
+  second, fully independent dev setup; `srt client -s1 -c2` attaches another
+  client to it.
+- `-c <N>` / `--client <N>` picks the client data tree, defaulting to the
+  session number. (`--compile` gave its short to `--client`.)
+- Dev state lives in `~/.solidrt/`: `servers/<port>/` holds each server's tunnel
+  key and `live.json` (the registry record MCP resolution reads, removed at
+  exit), `clients/client<M>/` the client trees (srt passes
+  `--data-root ~/.solidrt/clients` to every locally spawned client).
+- A server run serves the project it was started in; `load` outside the
+  project root is refused. Restart the server in another project to switch.
+- `srt mcp` needs no port: each tool call resolves the server serving the
+  project the bridge runs in (registry match + probe); `-s`/`--port` pin it.
 
 ## Dev server proxies (when clients on other devices need your machine's data)
 
 - `--proxy-http` - route `fetch` through the dev server; responses cached in
-  `.srt-data/http-cache.db` (delete the file to clear).
+  `.srt-data/http-cache.db` in the project root (delete the file to clear).
 
 ## REPL (opened by `run`/`server`)
 
 `load <file>`, `reload [n]`, `stop [n]`, `list`, `!<cmd>`, `quit`/`exit`.
+`load` is bound to the project root the server was started in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.48",
+  "version": "0.0.50",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -19,25 +19,26 @@
     "@babel/core": "^7.0.0",
     "@babel/plugin-syntax-jsx": "^7.0.0",
     "@babel/preset-typescript": "^7.0.0",
+    "@clack/prompts": "^1.7.0",
     "@jridgewell/remapping": "^2.3.0",
     "@jridgewell/trace-mapping": "^0.3.25",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "babel-preset-solid": "2.0.0-beta.31",
+    "babel-preset-solid": "2.0.0-rc.0",
     "bonjour-service": "^1.4.0",
     "qrcode-generator": "^2.0.4",
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@solidrt/darwin-arm64": "0.0.48",
-    "@solidrt/linux-arm64-gnu": "0.0.48",
-    "@solidrt/linux-x64-gnu": "0.0.48",
-    "@solidrt/win32-x64-msvc": "0.0.48"
+    "@solidrt/darwin-arm64": "0.0.50",
+    "@solidrt/linux-arm64-gnu": "0.0.50",
+    "@solidrt/linux-x64-gnu": "0.0.50",
+    "@solidrt/win32-x64-msvc": "0.0.50"
   },
   "peerDependencies": {
     "typescript": "^7"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.48",
+    "@solidrt/flux-types": "0.0.50",
     "@types/babel__core": "^7.20.5",
     "@types/bun": "latest"
   }

package/scaffold/AGENTS.md

@@ -280,6 +280,46 @@ work stops being free" below is where it does not. Rules, in order of leverage:
    snapshot instead of re-rasterizing. A window shader's output is invisible
    to get_snapshot and every other MCP tool; `srt render` is the only way to
    see it (Run / verify below).
+7. `flux:wasm` is not the fast lane. It runs a pure interpreter (wasmi, no
+   JIT), so tight typed compute gains a small constant factor over the same
+   loop in JavaScript, nowhere near browser wasm speed, and every host call
+   costs marshalling. Use it to ship one compiled module across every target
+   without native binaries, not to speed up per-frame work; for that, rules
+   1-2 (move it to the GPU, cut property writes) are the leverage.
+
+### Isolates: heavy work off the JS thread
+
+A long synchronous computation (a big parse, a simulation step, a blocking
+`flux:ffi`/`flux:wasm` call) freezes rendering and input for its duration.
+Move it into an isolate module: a file whose first statement is the
+`"use isolate"` directive runs in a second runtime on its own thread, and
+main calls its exports as async functions.
+
+```ts
+// src/worker.ts
+"use isolate"
+export function crunch(data: Uint8Array): number { /* ... */ }
+```
+
+```ts
+// src/index.tsx
+import { isolate } from "flux:isolate"
+import type * as Worker from "./worker"
+let worker = isolate<typeof Worker>("worker")   // id = path from src/, no extension
+let n = await worker.crunch(bytes)              // main keeps rendering meanwhile
+```
+
+The bundler builds each such module as its own bundle and ships it with the
+app (dev pushes and `srt pack` alike). Rules: main may only `import type`
+from an isolate module (a value import is a build error); arguments and
+results are copies (numbers, strings, byte buffers, arrays, plain objects -
+no functions, no class instances); the child has the non-gui `flux:*`
+modules only, so it never touches the render tree; module state persists
+between calls and each `isolate()` call is its own instance. An
+`async function*` export is a stream: `for await (let p of worker.progress())`
+pulls one item per step (progress, ticks, a subscription), `break` ends it in
+the isolate, and streams never block plain calls. Full contract:
+node_modules/@solidrt/flux-types/modules/isolate.d.ts.
 
 ### Where GPU work stops being free
 
@@ -346,7 +386,8 @@ up to the frame period, because work outside the frame call is not in them.
   (future launcher/window naming) with no storage meaning.
 - `bunx srt pack src/index.tsx` builds a single-file executable;
   `bunx srt pack --folder src/index.tsx` writes the flat app folder
-  (runner + manifest.json + bundle + assets/) to `dist/`.
+  (runner + manifest.json + bundle + assets/, plus the runner's GL
+  libraries on Windows and macOS) to `dist/`.
 
 ## Run / verify
 
@@ -374,8 +415,11 @@ its tools over guessing at runtime state:
 
 - list_clients: connected app clients, their platform and runtime
   capabilities, plus the server's `entry` (the app source it serves) and
-  `projectDir` - check entry matches the app you think you are driving; the
-  dev port is fixed, so another project's server answers on the same port.
+  `projectDir` - check entry matches the app you think you are driving. Each
+  tool call finds the dev server currently serving this project (by its
+  project root), so a server restarted on another port/session is followed
+  automatically; no server serving this project is an error, not a wrong
+  server.
   Each client also lists `queries`, the dev-tool query kinds its runtime
   answers - check it before planning verification against a mixed-version
   fleet (no "input" = the client predates send_input)
@@ -394,7 +438,7 @@ its tools over guessing at runtime state:
   re-fetch ids and restart cursors
 - get_stats: fps, CPU/memory, frame phase timings, setProperty rate, plus
   layout-activity counters for the last rebuild (nodes, measureCalls,
-  paraShapes, dirtiedNodes, cacheGets/cacheHits) - when layoutMs looks
+  paraShapes/wordHits, dirtiedNodes, cacheGets/cacheHits) - when layoutMs looks
   wrong, these say whether the cost is text shaping, invalidation breadth,
   or a defeated layout cache (healthy incremental rebuilds show a near-100%
   cacheHits rate). reusedPerSec/skippedPerSec are the demand gate's visible

package/scaffold/package.json

@@ -10,12 +10,13 @@
     "android": "srt client --android"
   },
   "dependencies": {
-    "@solidrt/core": "0.0.48",
-    "@solidrt/components": "0.0.48"
+    "@solidrt/core": "0.0.50",
+    "@solidrt/components": "0.0.50",
+    "@solidrt/3d": "0.0.50"
   },
   "devDependencies": {
-    "@solidrt/cli": "0.0.48",
-    "@solidrt/flux-types": "0.0.48",
+    "@solidrt/cli": "0.0.50",
+    "@solidrt/flux-types": "0.0.50",
     "typescript": "^7"
   }
 }

package/server/main.ts

@@ -74,16 +74,16 @@ async function handleInternal(req: FluxRequest, server: Server, path: string): P
 
   switch (path) {
     case "/__internal__/reload": {
-      // { message, clients?, latch?, sourceDir?, projectDir?, map? }: send
-      // `message` (a full client-protocol message, built by srt) to the listed
-      // client ids, or to all when omitted. `latch` keeps it for late-joining
-      // clients (code reloads latch, one-shot bytecode loads do not);
-      // `sourceDir` moves the file-serving root and `projectDir` the /assets/
-      // root (repl `load`); `map` is the bundle's sourcemap for log remapping,
-      // replaced on every reload (absent means none).
+      // { message, clients?, latch?, sourceDir?, map? }: send `message` (a
+      // full client-protocol message, built by srt) to the listed client ids,
+      // or to all when omitted. `latch` keeps it for late-joining clients
+      // (code reloads latch, one-shot bytecode loads do not); `sourceDir`
+      // moves the file-serving root (repl `load`; the project root - and with
+      // it the /assets/ root - is fixed for the life of the run); `map` is
+      // the bundle's sourcemap for log remapping, replaced on every reload
+      // (absent means none).
       let body = await req.json()
       if (typeof body.sourceDir === "string") state.sourceDir = body.sourceDir
-      if (typeof body.projectDir === "string") state.projectDir = body.projectDir
       // Keep the rebuild entry in sync when `load` moves it, so a later MCP
       // reload bundles the newly loaded file, not the launch-time one.
       if (typeof body.entry === "string") state.config.entry = body.entry
@@ -211,6 +211,12 @@ serve({
     if (path === "/assets" || path.startsWith("/assets/")) {
       return handleFiles(req, path, state.projectDir)
     }
+    // Isolate bundles are build outputs, not project files: srt (and the
+    // rebuild here) write them under .srt-data/isolates/, and the manifest
+    // lists them as isolates/<id>.js.
+    if (path.startsWith("/isolates/")) {
+      return handleFiles(req, path, config.cacheDir)
+    }
     return handleFiles(req, path, state.sourceDir)
   },
   websocket: {

package/server/rebuild.ts

@@ -1,4 +1,5 @@
 import { command } from "flux:subprocess"
+import { dir, file } from "flux:fs"
 import { state } from "./state"
 
 // Server-owned "rebuild and push": the single place the running app is rebuilt
@@ -45,13 +46,20 @@ export async function rebuildAndBroadcast(): Promise<string | null> {
     return `Rebuild failed:\n${stderr.trim()}`
   }
 
-  // bundle-cli writes one JSON object { code, map, manifest } to stdout.
-  let bundle: { code?: string; map?: string | null; manifest?: string }
+  // bundle-cli writes one JSON object { code, map, manifest, isolates } to stdout.
+  let bundle: { code?: string; map?: string | null; manifest?: string; isolates?: { id: string; code: string }[] }
   try {
     bundle = JSON.parse(typeof result.stdout === "string" ? result.stdout : "")
   } catch {
     return "Rebuild failed: unreadable bundler output"
   }
+  // Isolate bundles are manifest assets clients fetch from our /isolates/
+  // route (served from cacheDir), so they must be on disk before the push.
+  for (let isolate of bundle.isolates ?? []) {
+    let path = `${config.cacheDir}/isolates/${isolate.id}.js`
+    await dir(path.slice(0, path.lastIndexOf("/"))).create()
+    await file(path).write(isolate.code)
+  }
   state.currentMap = bundle.map ?? null
   let text = JSON.stringify(buildReload(bundle.code ?? "", bundle.manifest))
   state.currentReload = text

package/server/state.ts

@@ -29,7 +29,7 @@ export type Config = {
   cache: boolean
   /** Directory holding the proxy cache db (the project-local .srt-data). */
   cacheDir: string
-  /** Directory holding .srt-tunnel-key (the project root). */
+  /** Directory holding tunnel.key (the server's ~/.solidrt/servers/<port>/ folder). */
   keyDir: string
   /** Destination for captured key events, or unset when off. */
   capture?: string

package/server/tunnel.ts

@@ -15,15 +15,16 @@ import { printQr } from "./qr"
 // the handshake instead of desyncing.
 export const TUNNEL_PROTOCOL = "solidrt-dev/0"
 
-// The persisted identity file, at the project root. Delete it to rotate the
-// tunnel's identity (which invalidates any old ticket).
-const KEY_FILE = ".srt-tunnel-key"
+// The persisted identity file, in the server's ~/.solidrt/servers/<port>/ folder
+// (keyDir): the tunnel identity belongs to the server, not to any project it
+// serves. Delete it to rotate the identity (which invalidates any old ticket).
+const KEY_FILE = "tunnel.key"
 
 /**
  * Bind the tunnel endpoint and print its ticket (text + QR). The endpoint is
  * kept stable across restarts so a paired client can re-dial the old ticket
  * without re-scanning: the UDP port is pinned to the dev server's port, and the
- * secret key is persisted in <keyDir>/.srt-tunnel-key (generated on first
+ * secret key is persisted in <keyDir>/tunnel.key (generated on first
  * run). Both are needed - a moving port or a fresh key each start would change
  * the ticket. Stable across restarts on the same network only; a new machine IP
  * still stales the ticket's addresses (that is the discovery/off-LAN story).

package/src/args.ts

@@ -1,5 +1,6 @@
 import { parseArgs } from "node:util"
 import { resolve } from "node:path"
+import { clientsRoot } from "./dev-dir"
 
 // Everything after a bare "--" is the app's argument vector, kept out of
 // parseArgs (which would fold it into positionals) and forwarded verbatim to
@@ -14,8 +15,9 @@ export let { values, positionals } = parseArgs({
   options: {
     dev: { type: "boolean", short: "d", default: false },
     minify: { type: "boolean", short: "m", default: false },
-    compile: { type: "boolean", short: "c", default: false },
+    compile: { type: "boolean", default: false },
     flux: { type: "boolean", short: "f", default: false },
+    session: { type: "string", short: "s" },
     folder: { type: "boolean", default: false },
     stdout: { type: "boolean", default: false },
     output: { type: "string", short: "o" },
@@ -28,33 +30,51 @@ export let { values, positionals } = parseArgs({
     tunnel: { type: "boolean", default: false },
     stats: { type: "boolean", default: false },
     "data-root": { type: "string" },
-    client: { type: "string" },
+    client: { type: "string", short: "c" },
     server: { type: "string" },
     port: { type: "string" },
     android: { type: "boolean", default: false },
     device: { type: "string" },
-    template: { type: "string", short: "t" },
+    with: { type: "string" },
   },
   allowPositionals: true,
 })
 
-// Storage flags for a locally spawned client, forwarded only when given: with
-// no --data-root the client resolves its platform pref path (see
-// lattice/src/storage.rs); --client <N> selects the client<N>/ tree under
-// either root. An explicit root is passed absolute because the client chdirs
-// into its app sandbox at startup.
+export const DEFAULT_DEV_PORT = 0x8844
+
+// The session number: -s/--session <N> selects the dev server (port
+// DEFAULT_DEV_PORT + N, see dev-server.ts resolveDevPort) and the default
+// client slot. Resolved at load, like the port.
+function resolveSession(): number {
+  let raw = values.session
+  if (raw === undefined) return 0
+  let n = Number(raw)
+  if (!/^\d+$/.test(raw) || DEFAULT_DEV_PORT + n > 65535) {
+    console.error(
+      `Invalid --session value "${raw}": expected a non-negative integer with ${DEFAULT_DEV_PORT} + N at most 65535`,
+    )
+    process.exit(1)
+  }
+  return n
+}
+export let session = resolveSession()
+
+// Storage flags for a locally spawned client. Dev client trees live in
+// ~/.solidrt/clients/client<M>/, reached through --data-root so the client
+// runtime keeps its single pref-path default rule (see lattice/src/storage.rs
+// and okf/backlog/parallel-dev-servers.md); an explicit --data-root wins. The
+// client slot defaults to the session number, so each session gets its own
+// tree with a single flag. Roots are passed absolute because the client
+// chdirs into its app sandbox at startup.
 export function clientStorageArgs(): string[] {
-  let args: string[] = []
   let root = values["data-root"]
-  if (root) args.push("--data-root", resolve(root))
-  let client = values.client
-  if (client !== undefined) {
-    if (!/^\d+$/.test(client)) {
-      console.error(`Invalid --client value "${client}": expected a non-negative integer`)
-      process.exit(1)
-    }
-    args.push("--client", client)
+  let args = ["--data-root", root ? resolve(root) : clientsRoot()]
+  let client = values.client ?? String(session)
+  if (!/^\d+$/.test(client)) {
+    console.error(`Invalid --client value "${client}": expected a non-negative integer`)
+    process.exit(1)
   }
+  args.push("--client", client)
   return args
 }
 
@@ -111,6 +131,17 @@ export function validateArgs() {
   if (values.port !== undefined && command !== "run" && command !== "server" && command !== "mcp") {
     usage("srt <run|server|mcp> --port <N>  (--port is only valid with the run, server and mcp commands)")
   }
+  // --session selects a dev server (and the default client slot), so it is
+  // valid wherever a dev server is started, attached to, or resolved.
+  if (
+    values.session !== undefined &&
+    command !== "run" &&
+    command !== "server" &&
+    command !== "client" &&
+    command !== "mcp"
+  ) {
+    usage("srt <run|server|client|mcp> -s <N>  (--session is only valid with the run, server, client and mcp commands)")
+  }
 }
 
 export function printUsage() {
@@ -128,10 +159,11 @@ Commands:
   mcp                    MCP server (stdio) exposing the running dev server to coding agents
 
 init options:
-  -t, --template <name>  Start from a named template (skips the interactive picker)
+      --with <pkg,pkg>   Extensions to include, e.g. @solidrt/components,@solidrt/3d (skips the picker)
 
 run/server options:
-      --port <N>         Dev server port (default: 34884)
+  -s, --session <N>      Session number: dev server on port 34884+N, client slot N (default: 0)
+      --port <N>         Dev server port (default: 34884 + session)
       --proxy-http       Route fetch calls through the dev server (HTTP cache enabled)
       --capture <file>   Record connected clients' key events to a script file
       --tunnel           Accept ticket-paired clients through the p2p tunnel
@@ -140,22 +172,25 @@ run/server options:
 run/client options:
       --size <WxH>       Window size (default: 1280x720)
       --stats            Show the debug stats overlay (FPS, memory, frame timings)
-      --data-root <dir>  Client data root (default: the platform pref path)
-      --client <N>       Client number: its own data tree under the data root (default: 0)
+      --data-root <dir>  Client data root (default: ~/.solidrt/clients)
+  -c, --client <N>       Client number: its own data tree under the data root (default: the session)
 
 client options:
-      --server <host[:port]>  Connect to a dev server at this address (default port: 34884)
+  -s, --session <N>      Connect to this session's dev server on this machine
+                         (127.0.0.1:34884+N); without it, start on the connect screen
+      --server <host[:port]>  Connect to a dev server at this address (default port: 34884 + session)
       --android          Install and launch the client on a connected Android device
       --device <serial>  Target a specific adb device by serial or unique prefix
 
 mcp options:
-      --port <N>         Port of the dev server to attach to (default: 34884)
+  -s, --session <N>      Attach to the dev server of this session (default: resolve by project)
+      --port <N>         Port of the dev server to attach to (default: resolve by project)
 
 bundle options:
   -f, --flux             Bundle for the bare Flux runtime, without SolidJS (entry must be .ts|.js)
   -d, --dev              Use development build of SolidJS (default: production)
   -m, --minify           Minify the output
-  -c, --compile          Compile to bytecode
+      --compile          Compile to bytecode
   -o, --output <name>    Output filename
       --stdout           Write bundle to stdout
 

package/src/bundle-cli.ts

@@ -1,8 +1,9 @@
 // Standalone bundler entry, spawned by the dev server (a flux process) as a
 // Bun subprocess to rebuild the app on an MCP-triggered reload. flux cannot call
 // Bun.build, so the server shells out to this. Params arrive as one JSON
-// argument; one JSON object { code, map } goes to stdout and diagnostics to
-// stderr. On a build failure it exits non-zero with an empty stdout.
+// argument; one JSON object { code, map, manifest, isolates } goes to stdout
+// and diagnostics to stderr. On a build failure it exits non-zero with an
+// empty stdout.
 
 import { bundleWith, type BundleOptions } from "./bundler"