@solidrt/cli 0.0.48 → 0.0.49

package/AGENTS.md

@@ -50,11 +50,29 @@ behavior in isolation.
   (display scale is pinned to 1), so frames are identical on every machine.
 - Run from the project directory. There is no `bunx --cwd` flag.
 
+## 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.49",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -22,22 +22,22 @@
     "@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.49",
+    "@solidrt/linux-arm64-gnu": "0.0.49",
+    "@solidrt/linux-x64-gnu": "0.0.49",
+    "@solidrt/win32-x64-msvc": "0.0.49"
   },
   "peerDependencies": {
     "typescript": "^7"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.48",
+    "@solidrt/flux-types": "0.0.49",
     "@types/babel__core": "^7.20.5",
     "@types/bun": "latest"
   }

package/scaffold/AGENTS.md

@@ -281,6 +281,40 @@ work stops being free" below is where it does not. Rules, in order of leverage:
    to get_snapshot and every other MCP tool; `srt render` is the only way to
    see it (Run / verify below).
 
+### 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
 
 "GPU work is nearly free" is a property of the hardware, not of the engine, and
@@ -346,7 +380,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 +409,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)

package/scaffold/package.json

@@ -10,12 +10,12 @@
     "android": "srt client --android"
   },
   "dependencies": {
-    "@solidrt/core": "0.0.48",
-    "@solidrt/components": "0.0.48"
+    "@solidrt/core": "0.0.49",
+    "@solidrt/components": "0.0.49"
   },
   "devDependencies": {
-    "@solidrt/cli": "0.0.48",
-    "@solidrt/flux-types": "0.0.48",
+    "@solidrt/cli": "0.0.49",
+    "@solidrt/flux-types": "0.0.49",
     "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,7 +30,7 @@ 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 },
@@ -38,23 +40,41 @@ export let { values, positionals } = parseArgs({
   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() {
@@ -131,7 +162,8 @@ init options:
   -t, --template <name>  Start from a named template (skips the interactive 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"
 

package/src/bundler.ts

@@ -4,11 +4,11 @@ import ts from "@babel/preset-typescript"
 import remapping from "@jridgewell/remapping"
 import solid from "babel-preset-solid"
 import { type BunPlugin, type BuildArtifact } from "bun"
-import { readFileSync } from "node:fs"
-import { dirname, resolve as resolvePath } from "node:path"
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
+import { dirname, join, relative, resolve as resolvePath, sep } from "node:path"
 import { values, source } from "./args"
 import { state, print, requireBinary } from "./util"
-import { buildManifest } from "./project"
+import { buildManifest, manifestAssetFor } from "./project"
 
 // Babel plugin: rewrite `import data from "./x" with { type: "binary" }` into an
 // inline Uint8Array of the file's bytes, and `with { type: "text" }` into an
@@ -82,7 +82,10 @@ async function codeFromOutputs(outputs: BuildArtifact[]): Promise<string> {
 // (node_modules) skips the babel detour and keeps Bun's native loaders.
 // With `babelMaps`, each file's transform map (original -> babel output) is
 // collected there, keyed by absolute path, for sourcemap composition later.
-function solidPlugin(babelMaps?: Map<string, object>): BunPlugin {
+// `isolateEntry` is the one "use isolate" module this build may load (its own
+// entry); loading any other one means a by-value import of an isolate module,
+// which is a build error (see isolate modules below).
+function solidPlugin(babelMaps?: Map<string, object>, isolateEntry?: string): BunPlugin {
   return {
     name: "bun-plugin-solid",
     setup: (build) => {
@@ -90,6 +93,11 @@ function solidPlugin(babelMaps?: Map<string, object>): BunPlugin {
         if (!/\.(js|ts)x$/.test(args.path) && args.path.includes("node_modules")) return
         let file = Bun.file(args.path)
         let code = await file.text()
+        if (args.path !== isolateEntry && hasIsolateDirective(code)) {
+          throw new Error(
+            `${args.path} is a "use isolate" module: import its types only (import type * as W from "./...") and call it through isolate() from flux:isolate`,
+          )
+        }
         let transforms = await transformAsync(code, {
           filename: args.path,
           sourceMaps: !!babelMaps,
@@ -103,6 +111,53 @@ function solidPlugin(babelMaps?: Map<string, object>): BunPlugin {
   }
 }
 
+// Isolate modules (okf/done/isolates-and-ports.md): a source file whose first
+// statement is the "use isolate" directive is the entry of its own bundle,
+// run by flux:isolate in a second runtime. Its id is its path relative to
+// the source root (the entry's directory) without extension; the bundle
+// travels as the manifest asset isolates/<id>.js (dev) or .bin (pack). The
+// main build never loads such a module (only `import type` reaches it), so
+// the set is found by scanning the tree rather than by following imports.
+
+// The directive is the first statement: leading whitespace, comments and a
+// shebang may precede it, nothing else.
+let ISOLATE_DIRECTIVE = /^(?:#![^\n]*\n)?(?:\s|\/\/[^\n]*|\/\*[\s\S]*?\*\/)*(?:"use isolate"|'use isolate')\s*(?:;|\n|$)/
+
+export function hasIsolateDirective(code: string): boolean {
+  return ISOLATE_DIRECTIVE.test(code)
+}
+
+let SKIP_DIRS = new Set(["node_modules", "dist"])
+
+export type IsolateModule = { id: string; path: string }
+
+/** Every "use isolate" module under `root`, in id order. */
+export function findIsolateModules(root: string): IsolateModule[] {
+  let out: IsolateModule[] = []
+  let walk = (dir: string) => {
+    for (let entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue
+      let abs = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        walk(abs)
+      } else if (entry.isFile() && /\.(js|ts)x?$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+        if (hasIsolateDirective(readFileSync(abs, "utf8"))) {
+          let id = relative(root, abs).split(sep).join("/").replace(/\.(js|ts)x?$/, "")
+          out.push({ id, path: abs })
+        }
+      }
+    }
+  }
+  walk(root)
+  out.sort((a, b) => (a.id < b.id ? -1 : 1))
+  return out
+}
+
+/** The manifest asset path of an isolate bundle. */
+export function isolateAssetPath(id: string, ext: "js" | "bin"): string {
+  return `isolates/${id}.${ext}`
+}
+
 export type BundleOptions = { entry: string; devBase?: string; dev: boolean; minify: boolean }
 
 export type BundleResult = {
@@ -111,6 +166,8 @@ export type BundleResult = {
   map: string | null
   /** Version manifest JSON for this bundle; clients install pushes under its hash. */
   manifest: string
+  /** The app's isolate bundles, one per "use isolate" module, in id order. */
+  isolates: { id: string; code: string }[]
 }
 
 // The pure bundle: every input is explicit, so it runs identically in the srt
@@ -130,32 +187,66 @@ export async function bundleWith(opts: BundleOptions): Promise<BundleResult | nu
   }
   if (opts.devBase) define.__SRT_DEV_BASE__ = opts.devBase
 
+  // One Bun.build per entry: the app, then each isolate module as its own
+  // self-contained bundle (splitting is off, so a helper both import gets
+  // duplicated rather than shared). Only the app's build gets a composed
+  // sourcemap for now.
+  let build = async (entry: string, babelMaps?: Map<string, object>, isolateEntry?: string) => {
+    let result = null
+    try {
+      result = await Bun.build({
+        entrypoints: [entry],
+        target: "browser",
+        format: "esm",
+        minify: opts.minify,
+        external: ["flux:*", "srt:*"],
+        define,
+        loader: { ".svg": "text" },
+        sourcemap: babelMaps ? "external" : "none",
+        plugins: [solidPlugin(babelMaps, isolateEntry)],
+      })
+    } catch (e) {
+      console.error("[cli] compile error:\n", e)
+      return null
+    }
+    if (!result.success) {
+      for (let msg of result.logs) console.error(msg)
+      return null
+    }
+    return result
+  }
+
   let babelMaps = opts.dev ? new Map<string, object>() : undefined
-  let result = null
-  try {
-    result = await Bun.build({
-      entrypoints: [opts.entry],
-      target: "browser",
-      format: "esm",
-      minify: opts.minify,
-      external: ["flux:*", "srt:*"],
-      define,
-      loader: { ".svg": "text" },
-      sourcemap: opts.dev ? "external" : "none",
-      plugins: [solidPlugin(babelMaps)],
-    })
-  } catch (e) {
-    console.error("[cli] compile error:\n", e)
-    return null
+  let main = await build(opts.entry, babelMaps)
+  if (!main) return null
+  let code = await codeFromOutputs(main.outputs)
+
+  let isolates: { id: string; code: string }[] = []
+  for (let module of findIsolateModules(dirname(resolvePath(opts.entry)))) {
+    let result = await build(module.path, undefined, module.path)
+    if (!result) return null
+    isolates.push({ id: module.id, code: await codeFromOutputs(result.outputs) })
   }
 
-  if (!result.success) {
-    for (let msg of result.logs) console.error(msg)
-    return null
+  let extra = isolates.map((i) => manifestAssetFor(isolateAssetPath(i.id, "js"), Buffer.from(i.code, "utf8")))
+  return {
+    code,
+    map: await composeMap(main.outputs, babelMaps),
+    manifest: buildManifest(code, opts.entry, extra),
+    isolates,
   }
+}
 
-  let code = await codeFromOutputs(result.outputs)
-  return { code, map: await composeMap(result.outputs, babelMaps), manifest: buildManifest(code, opts.entry) }
+// Write dev isolate bundles where the dev server serves /isolates/ from
+// (<project>/.srt-data/isolates/<id>.js), so clients can fetch the manifest
+// assets the bundle lists. Stale files from removed modules stay behind
+// unlisted, which is harmless.
+export function writeIsolates(dir: string, isolates: { id: string; code: string }[]) {
+  for (let i of isolates) {
+    let file = join(dir, `${i.id}.js`)
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, i.code)
+  }
 }
 
 // Compose Bun's bundle map (babel output -> bundle) with the per-file Babel
@@ -185,7 +276,15 @@ export async function bundle(entry = source) {
   let dev = !!devBase || values.dev
   // Keep stdout clean when the bundle itself is written to stdout.
   if (!values.stdout) print(`[cli] Bundling (${dev ? "development" : "production"})`)
-  return bundleWith({ entry: entry!, devBase, dev, minify: values.minify })
+  let result = await bundleWith({ entry: entry!, devBase, dev, minify: values.minify })
+  // With a server running, its /isolates/ route serves what we write here.
+  if (result && devBase) writeIsolates(devIsolatesDir(state.projectDir), result.isolates)
+  return result
+}
+
+/** Where a project's dev isolate bundles are written and served from. */
+export function devIsolatesDir(projectDir: string): string {
+  return join(projectDir, ".srt-data", "isolates")
 }
 
 export async function bundleTo(outfile: string) {
@@ -216,13 +315,13 @@ export async function bundleFlux(entry: string): Promise<string> {
 }
 
 // Bundle for the SolidRT runtime via the standard Solid-aware bundler.
-export async function bundleSolid(): Promise<string> {
+export async function bundleSolid(): Promise<BundleResult> {
   let result = await bundle()
   if (!result) {
     console.error("Build failed")
     process.exit(1)
   }
-  return result.code
+  return result
 }
 
 // Compile JS source to QuickJS bytecode via the fluxc binary.

package/src/commands/check.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, rmSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
 import { source } from "../args"
-import { bundleWith } from "../bundler"
+import { bundleWith, findIsolateModules } from "../bundler"
 
 // srt check: verify the app without side effects. Bundles in memory (nothing
 // written, so no dev-server reload fires and no build outputs land in the
@@ -86,7 +86,11 @@ export async function typecheck(root: string, entry: string): Promise<{ app: Dia
   // applies precisely because nothing imports it, so entry-only rooting would
   // silently drop it and every asset import would fail with TS2307. The
   // pattern is relative to this config, which sits one level under the root.
-  await Bun.write(config, JSON.stringify({ extends: tsconfig, include: ["../**/*.d.ts"], files: [resolve(entry)] }))
+  // Isolate modules are program roots of their own: main reaches them by
+  // `import type` at most, and one nothing imports would otherwise go
+  // unchecked.
+  let files = [resolve(entry), ...findIsolateModules(dirname(resolve(entry))).map((m) => m.path)]
+  await Bun.write(config, JSON.stringify({ extends: tsconfig, include: ["../**/*.d.ts"], files }))
   try {
     let proc = Bun.spawn([tsc, "-p", config, "--noEmit", "--pretty", "false"], {
       cwd: root,

package/src/commands/client.ts

@@ -1,13 +1,14 @@
 import { values, clientStorageArgs } from "../args"
 import { requireBinary, run } from "../util"
 import { spawnAndroidClient } from "../dev-android"
-import { DEV_PORT } from "../dev-server"
+import { DEV_HOST, DEV_PORT } from "../dev-server"
 
 // Standalone solidrt-go client (no dev server). The `run` command instead uses
 // spawnClient() to launch a client tied to the dev-server lifecycle. --server
-// auto-connects to a dev server at the given address (otherwise the client
-// starts on the connect screen); with --android it is installed and launched
-// on a connected Android device instead of run locally.
+// auto-connects to a dev server at the given address, and -s <N> is its
+// shorthand for the session's server on this machine; without either, the
+// client starts on the connect screen. With --android it is installed and
+// launched on a connected Android device instead of run locally.
 export async function runClientCommand() {
   if (values.android) {
     await spawnAndroidClient()
@@ -17,10 +18,17 @@ export async function runClientCommand() {
   let runner = requireBinary("solidrt-go")
   let args: string[] = [...clientStorageArgs()]
   if (values.size) args.push("--size", values.size)
-  if (values.server) {
-    let address = values.server.includes(":") ? values.server : `${values.server}:${DEV_PORT}`
-    args.push("--dev-server", address)
-  }
+  // Both flags resolve to the one address the client understands. --server
+  // wins: an explicit host is never overridden by a session number, which
+  // only ever names a loopback port.
+  let address = values.server
+    ? values.server.includes(":")
+      ? values.server
+      : `${values.server}:${DEV_PORT}`
+    : values.session !== undefined
+      ? `${DEV_HOST}:${DEV_PORT}`
+      : null
+  if (address) args.push("--dev-server", address)
   let exit = await run(runner, args)
   process.exit(exit)
 }

package/src/commands/mcp.ts

@@ -9,14 +9,116 @@ import { z } from "zod"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"
-import { resolve } from "node:path"
+import { dirname, join, resolve } from "node:path"
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { values } from "../args"
 import { DEV_PORT } from "../dev-server"
+import { devDir } from "../dev-dir"
 
-const CONTROL_BASE = `http://127.0.0.1:${DEV_PORT}/__control__`
+// An explicit -s/--port pins the port for the bridge's lifetime. Otherwise
+// the port is resolved per tool call from the server registry, so one bridge
+// (started when the workspace opens, kept alive across server restarts)
+// follows whichever server is currently serving this project - and the
+// scaffold's mcp.json never carries a port.
+const FIXED_PORT = values.port !== undefined || values.session !== undefined ? DEV_PORT : null
+
+// The projectDir the bridge is working in: the nearest package.json above its
+// own cwd, the same rule srt applies to an entry (project.ts projectDirFor),
+// so both sides derive the same string.
+function findProjectDir(): string | null {
+  let dir = process.cwd()
+  while (true) {
+    if (existsSync(join(dir, "package.json"))) return dir
+    let parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+type LiveRecord = { pid: number; port: number; projectDir: string }
+
+// The global server registry: every running dev server keeps a live.json in
+// ~/.solidrt/servers/<port>/ (see dev-server.ts writeLiveRecord). Unreadable or
+// malformed records are skipped, not fatal - the registry is a hint.
+function liveRecords(): LiveRecord[] {
+  let root = devDir("servers")
+  let names: string[]
+  try {
+    names = readdirSync(root)
+  } catch {
+    return []
+  }
+  let records: LiveRecord[] = []
+  for (let name of names) {
+    try {
+      let record = JSON.parse(readFileSync(join(root, name, "live.json"), "utf8"))
+      if (typeof record?.pid === "number" && typeof record?.port === "number" && typeof record?.projectDir === "string") {
+        records.push(record)
+      }
+    } catch {}
+  }
+  return records
+}
+
+type PortResult = { ok: true; port: number } | { ok: false; message: string }
+
+async function resolvePort(): Promise<PortResult> {
+  if (FIXED_PORT !== null) return { ok: true, port: FIXED_PORT }
+  let project = findProjectDir()
+  if (!project) {
+    return {
+      ok: false,
+      message: `No package.json found above ${process.cwd()}, so no dev server can be resolved by project. Pass -s <N> or --port <N> to srt mcp.`,
+    }
+  }
+  let matches = liveRecords().filter((r) => r.projectDir === project && pidAlive(r.pid))
+  if (matches.length > 1) {
+    let ports = matches
+      .map((r) => r.port)
+      .sort((a, b) => a - b)
+      .join(", ")
+    return { ok: false, message: `${matches.length} dev servers are serving this project (ports ${ports}); pass -s <N> to srt mcp` }
+  }
+  if (matches.length === 0) {
+    return { ok: false, message: `No dev server for ${project}. Start one with srt run, or pass -s <N> to srt mcp.` }
+  }
+  let port = matches[0]!.port
+  // The record is a hint; the server is authoritative. The probe catches a
+  // stale record whose pid was reused by an unrelated process.
+  try {
+    let probe = await fetch(`http://127.0.0.1:${port}/__control__/clients`)
+    let body: any = await probe.json().catch(() => null)
+    if (!probe.ok || body?.projectDir !== project) {
+      return {
+        ok: false,
+        message: `The server on port ${port} is not serving ${project}${
+          typeof body?.projectDir === "string" ? ` (it serves ${body.projectDir})` : ""
+        }. Start one with srt run, or pass -s <N> to srt mcp.`,
+      }
+    }
+  } catch {
+    return {
+      ok: false,
+      message: `No dev server for ${project}: the registry lists port ${port} but nothing answers there. Start one with srt run.`,
+    }
+  }
+  return { ok: true, port }
+}
 
 type ControlResult = { ok: true; body: any } | { ok: false; message: string }
 
 async function control(path: string, method: "GET" | "POST" = "GET", payload?: unknown): Promise<ControlResult> {
+  let resolved = await resolvePort()
+  if (!resolved.ok) return resolved
   let resp
   try {
     let init: RequestInit = { method }
@@ -24,7 +126,7 @@ async function control(path: string, method: "GET" | "POST" = "GET", payload?: u
       init.headers = { "content-type": "application/json" }
       init.body = JSON.stringify(payload)
     }
-    resp = await fetch(CONTROL_BASE + path, init)
+    resp = await fetch(`http://127.0.0.1:${resolved.port}/__control__${path}`, init)
   } catch {
     return {
       ok: false,

package/src/commands/pack.ts

@@ -41,8 +41,12 @@ export async function runPackCommand() {
   let fonts = resolvePackFonts(source!)
   console.log(`>> fonts: ${fonts.length ? fonts.map((f) => f.alias).join(", ") : "none"}`)
 
-  let bytecode = await compileToBytecode(await bundleSolid())
-  let folder = buildPackFolder(source!, bytecode)
+  let bundled = await bundleSolid()
+  let bytecode = await compileToBytecode(bundled.code)
+  let isolates = []
+  for (let i of bundled.isolates) isolates.push({ id: i.id, bytecode: await compileToBytecode(i.code) })
+  if (isolates.length) console.log(`>> isolates: ${isolates.map((i) => i.id).join(", ")}`)
+  let folder = buildPackFolder(source!, bytecode, isolates)
 
   if (values.folder) {
     let outDir = values.output ?? "dist"

package/src/commands/server.ts

@@ -16,7 +16,10 @@ export async function runServerCommand() {
   // Initialize state from args
   state.source = source
   state.sourceDir = source ? dirname(resolve(source)) : process.cwd()
-  state.projectDir = source ? projectDirFor(resolve(source)) : process.cwd()
+  // With no entry the project is wherever srt was started: walk up to the
+  // nearest package.json exactly like an entry would, so the projectDir the
+  // MCP bridge derives for its registry match agrees with ours.
+  state.projectDir = projectDirFor(source ? resolve(source) : resolve("package.json"))
   state.stats = values.stats
   state.capture = values.capture ? resolve(values.capture) : undefined
 

package/src/dev-dir.ts

@@ -0,0 +1,25 @@
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+// The folder name is deliberately isolated here: one switch point if it ever
+// changes or becomes configurable.
+const DEV_DIR_NAME = ".solidrt"
+
+// All dev-tooling state lives in one home dotdir, one rule on every platform
+// (okf/backlog/parallel-dev-servers.md): servers/<port>/ holds a dev server's
+// identity (tunnel.key) and its registry record (live.json), clients/ is the
+// data root srt passes for every locally spawned client, so dev client trees
+// land in clients/client<M>/. Deleting the dir resets every bit of dev state.
+export function devDir(...parts: string[]): string {
+  return join(homedir(), DEV_DIR_NAME, ...parts)
+}
+
+/** `servers/<port>/` under the dev dir - a dev server's identity and registry record, keyed by port. */
+export function serverDir(port: number): string {
+  return devDir("servers", String(port))
+}
+
+/** `clients/` under the dev dir - the --data-root for locally spawned dev clients. */
+export function clientsRoot(): string {
+  return devDir("clients")
+}

package/src/dev-server.ts

@@ -1,18 +1,21 @@
-import { resolve } from "path"
+import { resolve, join } from "path"
 import { tmpdir, networkInterfaces } from "node:os"
 import { fileURLToPath } from "node:url"
+import { mkdirSync, writeFileSync, unlinkSync } from "node:fs"
 import { state, print, printErr, requireBinary, pipeAbovePrompt, shutdown } from "./util"
-import { appArgs, values } from "./args"
+import { appArgs, values, session, DEFAULT_DEV_PORT } from "./args"
+import { serverDir } from "./dev-dir"
 
 export const DEV_HOST = "127.0.0.1"
-export const DEFAULT_DEV_PORT = 0x8844
 
 // The port every dev-server consumer dials: the spawned server, the local and
 // Android clients' --dev-server address, and the MCP bridge's control base.
-// Resolved once here, so --port needs no threading through those call sites.
+// Resolved once here, so --port/--session need no threading through those
+// call sites. An explicit --port wins over the session; the server folder is
+// keyed by the port actually bound either way.
 function resolveDevPort(): number {
   let raw = values.port
-  if (raw === undefined) return DEFAULT_DEV_PORT
+  if (raw === undefined) return DEFAULT_DEV_PORT + session
   let port = Number(raw)
   if (!/^\d+$/.test(raw) || port < 1 || port > 65535) {
     console.error(`Invalid --port value "${raw}": expected a port number between 1 and 65535`)
@@ -58,10 +61,10 @@ async function post(path: string, body: object) {
  * Send a client-protocol message through the server: to the given client ids,
  * or to every client when omitted. `latch` keeps the message for late-joining
  * clients (code reloads latch, one-shot bytecode loads do not); `sourceDir`
- * moves the server's file-serving root and `projectDir` its /assets/ root
- * (repl `load`); `map` is the bundle's sourcemap, kept server-side for
- * stack-trace remapping (omitting it clears the server's map, so a mapless
- * reload never remaps against a stale one).
+ * moves the server's file-serving root (repl `load`; the project root is
+ * fixed for the life of the run); `map` is the bundle's sourcemap, kept
+ * server-side for stack-trace remapping (omitting it clears the server's map,
+ * so a mapless reload never remaps against a stale one).
  */
 export async function sendReload(
   message: object,
@@ -69,7 +72,6 @@ export async function sendReload(
     clients?: number[]
     latch?: boolean
     sourceDir?: string
-    projectDir?: string
     entry?: string
     map?: string | null
   } = {},
@@ -185,15 +187,41 @@ function requireFreePort(port: number) {
     let probe = Bun.serve({ port, fetch: () => new Response() })
     probe.stop(true)
   } catch {
-    printErr(`[cli] Port ${port} is already in use; start on another port with --port <N>`)
+    printErr(`[cli] Port ${port} is already in use; start on another session with -s <N> (or --port <P>)`)
     process.exit(1)
   }
 }
 
+// The server's registry record: written once the server answers, removed at
+// exit, so MCP bridges can resolve a project to a port without any per-project
+// config (okf/backlog/parallel-dev-servers.md). The pid is the flux server's
+// (the process owning the port), so a record left behind by a crash fails the
+// bridge's liveness check; the record is a hint either way - the bridge's
+// /__control__/clients probe is authoritative.
+function writeLiveRecord() {
+  let record = {
+    pid: state.serverProc?.pid,
+    port: DEV_PORT,
+    projectDir: state.projectDir,
+    entry: state.source ?? null,
+    started: new Date().toISOString(),
+  }
+  writeFileSync(join(serverDir(DEV_PORT), "live.json"), JSON.stringify(record))
+}
+
+function removeLiveRecord() {
+  try {
+    unlinkSync(join(serverDir(DEV_PORT), "live.json"))
+  } catch {}
+}
+
 export async function startServer() {
   let flux = requireBinary("flux")
   requireFreePort(DEV_PORT)
   let script = await bundleServer()
+  // The server's own folder (tunnel.key lands there, written by the flux
+  // process, which does not create directories).
+  mkdirSync(serverDir(DEV_PORT), { recursive: true })
 
   let lanAddress = Object.values(networkInterfaces())
     .flat()
@@ -220,8 +248,8 @@ export async function startServer() {
     minify: values.minify,
     bundlerCmd: [process.execPath, bundleCli],
     cache: values["proxy-http"],
-    cacheDir: resolve(".srt-data"),
-    keyDir: process.cwd(),
+    cacheDir: resolve(state.projectDir, ".srt-data"),
+    keyDir: serverDir(DEV_PORT),
     capture: state.capture,
     stats: state.stats,
     tunnel: values.tunnel,
@@ -257,6 +285,11 @@ export async function startServer() {
     }
   }
 
+  writeLiveRecord()
+  // shutdown() exits via process.exit, so the exit hook covers every orderly
+  // path; only a kill -9 leaves the record behind, for the pid check to catch.
+  process.on("exit", removeLiveRecord)
+
   // mDNS advertise (dropped, code kept for future use - see
   // docs/flux-dev-server-plan.md): the p2p ticket is the cross-device connect
   // story now. If advertise returns, it belongs next to the server (a flux

package/src/pack-folder.ts

@@ -10,6 +10,8 @@ import {
   type ManifestFont,
 } from "./project"
 import { resolvePackFonts } from "./fonts"
+import { runnerGlLibs } from "./packer"
+import { isolateAssetPath } from "./bundler"
 
 // The canonical flat pack folder (okf/plans/client-storage-updates.md, Pack
 // output): runner + manifest.json + bundle.bin + assets/. The manifest
@@ -32,13 +34,20 @@ export type PackFolder = {
   manifest: string
   /** Files to place in the folder: absolute source -> folder-relative path. */
   copies: Array<{ from: string; to: string }>
+  /** Build outputs to place in the folder (isolate bytecode): folder-relative path + bytes. */
+  files: Array<{ to: string; bytes: Buffer }>
 }
 
-export function buildPackFolder(entry: string, bytecode: Buffer): PackFolder {
+// `isolates` are the app's isolate bundles compiled to bytecode; they ship as
+// the manifest assets isolates/<id>.bin (the production runtime has no
+// compiler, so pack never ships isolate source).
+export function buildPackFolder(entry: string, bytecode: Buffer, isolates: { id: string; bytecode: Buffer }[]): PackFolder {
   let identity = loadAppIdentity(entry)
   let projectDir = projectDirFor(resolve(entry))
   let { assets, icon } = collectAssets(entry)
   let copies = assets.map((a) => ({ from: join(projectDir, a.path), to: a.path }))
+  let files = isolates.map((i) => ({ to: isolateAssetPath(i.id, "bin"), bytes: i.bytecode }))
+  for (let f of files) assets.push({ path: f.to, sha256: hashHex(f.bytes), size: f.bytes.length })
 
   // The full resolved font set: custom fonts are already collected assets;
   // defaults materialize under assets/fonts/ (a user file already at that
@@ -77,7 +86,7 @@ export function buildPackFolder(entry: string, bytecode: Buffer): PackFolder {
     ...(assets.length ? { assets } : {}),
     ...(fonts.length ? { fonts } : {}),
   })
-  return { manifest, copies }
+  return { manifest, copies, files }
 }
 
 /**
@@ -93,9 +102,11 @@ export function writePackFolder(outDir: string, runnerPath: string, bytecode: Bu
   }
 
   let runnerName = "solidrt" + (process.platform === "win32" ? ".exe" : "")
+  let glLibs = runnerGlLibs(runnerPath)
   mkdirSync(outDir, { recursive: true })
   rmSync(join(outDir, "assets"), { recursive: true, force: true })
-  for (let name of ["manifest.json", "bundle.bin", runnerName]) {
+  rmSync(join(outDir, "isolates"), { recursive: true, force: true })
+  for (let name of ["manifest.json", "bundle.bin", runnerName, ...glLibs.map((lib) => lib.name)]) {
     rmSync(join(outDir, name), { force: true })
   }
 
@@ -105,6 +116,11 @@ export function writePackFolder(outDir: string, runnerPath: string, bytecode: Bu
   if (process.platform !== "win32") {
     Bun.spawnSync(["chmod", "+x", join(outDir, runnerName)])
   }
+  // The runner loads its GL libraries from next to itself; a folder pack must
+  // carry them like the platform package does.
+  for (let lib of glLibs) {
+    cpSync(lib.path, join(outDir, lib.name), { dereference: true })
+  }
   writeFileSync(join(outDir, "bundle.bin"), bytecode)
   writeFileSync(join(outDir, "manifest.json"), folder.manifest)
   for (let { from, to } of folder.copies) {
@@ -112,4 +128,9 @@ export function writePackFolder(outDir: string, runnerPath: string, bytecode: Bu
     mkdirSync(dirname(dest), { recursive: true })
     cpSync(from, dest)
   }
+  for (let { to, bytes } of folder.files) {
+    let dest = join(outDir, to)
+    mkdirSync(dirname(dest), { recursive: true })
+    writeFileSync(dest, bytes)
+  }
 }

package/src/packer.ts

@@ -1,4 +1,5 @@
-import { readFileSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
 import { requireBinary } from "./util"
 import { compileToBytecode } from "./bundler"
 import type { PackFolder } from "./pack-folder"
@@ -14,6 +15,33 @@ const MAGIC = {
 // Section kinds in the solidrt trailer. Must match lattice/src/main.rs.
 const SECTION_MANIFEST = 1
 const SECTION_FILE = 2
+const SECTION_GL_LIB = 3
+
+// The GL libraries the runner needs next to it (or, single-file, embedded as
+// kind-3 sections it extracts at boot): ANGLE's libraries on Windows and
+// macOS, nothing on platforms with a system GL. Order matters and the runner
+// preloads in section order: libGLESv2 must load before libEGL so libEGL's
+// import of it resolves against the already-loaded module instead of a
+// directory search.
+const GL_LIB_NAMES: Partial<Record<NodeJS.Platform, string[]>> = {
+  win32: ["libGLESv2.dll", "libEGL.dll"],
+  darwin: ["libGLESv2.dylib", "libEGL.dylib"],
+}
+
+// The GL libraries shipped next to the runner binary, resolved to their paths.
+// Missing files are fatal: a pack without them cannot create a window.
+export function runnerGlLibs(runnerPath: string): Array<{ name: string; path: string }> {
+  let names = GL_LIB_NAMES[process.platform] ?? []
+  let dir = dirname(runnerPath)
+  return names.map((name) => {
+    let path = join(dir, name)
+    if (!existsSync(path)) {
+      console.error(`Could not find ${name} next to the runner (${dir}); the packed app needs it to create a GL context.`)
+      process.exit(1)
+    }
+    return { name, path }
+  })
+}
 
 type Section = { kind: number; bytes: Buffer; name?: string }
 
@@ -48,13 +76,18 @@ function packSections(runnerBytes: Buffer, sections: Section[], magic: Buffer):
 // section form - the canonical manifest verbatim, then every manifest-listed
 // file named by its manifest path. Bundle, fonts, and identity all come from
 // the manifest; assets are read in place via ranged reads at their section
-// offsets, so nothing is unpacked at runtime.
+// offsets, so nothing is unpacked at runtime. GL libraries ride along as
+// kind-3 sections (runtime freight, deliberately outside the manifest); the
+// runner extracts those to its cache and preloads them before window setup.
 export function packSolid(folder: PackFolder, bytecode: Buffer): Buffer {
-  let runnerBytes = readFileSync(requireBinary("solidrt"))
+  let runnerPath = requireBinary("solidrt")
+  let runnerBytes = readFileSync(runnerPath)
   let sections: Section[] = [
     { kind: SECTION_MANIFEST, bytes: Buffer.from(folder.manifest, "utf8") },
     { kind: SECTION_FILE, bytes: bytecode, name: "bundle.bin" },
     ...folder.copies.map((c) => ({ kind: SECTION_FILE, bytes: readFileSync(c.from), name: c.to })),
+    ...folder.files.map((f) => ({ kind: SECTION_FILE, bytes: f.bytes, name: f.to })),
+    ...runnerGlLibs(runnerPath).map((lib) => ({ kind: SECTION_GL_LIB, bytes: readFileSync(lib.path), name: lib.name })),
   ]
   return packSections(runnerBytes, sections, MAGIC.solidrt)
 }

package/src/project.ts

@@ -71,10 +71,13 @@ export const RUNTIME_VERSION = 1
 let pkgVersion = JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"), "utf8")).version
 export const SOLIDRT_VERSION: string = pkgVersion === "0.0.0" ? "unknown" : pkgVersion
 
-export function buildManifest(code: string, entry: string): string {
+// `extra` are build outputs that ship as assets too (isolate bundles); they
+// follow the assets/ tree in the list, in the order given.
+export function buildManifest(code: string, entry: string, extra: ManifestAsset[] = []): string {
   let identity = loadAppIdentity(entry)
   let sha256 = new Bun.CryptoHasher("sha256").update(code).digest("hex")
   let { assets, fonts, icon } = collectAssets(entry)
+  assets.push(...extra)
   return JSON.stringify({
     appId: identity.appId,
     displayName: identity.displayName,
@@ -90,6 +93,11 @@ export function buildManifest(code: string, entry: string): string {
 export type ManifestAsset = { path: string; sha256: string; size: number }
 export type ManifestFont = { path: string; alias: string }
 
+/** The manifest entry for in-memory asset bytes at `path`. */
+export function manifestAssetFor(path: string, bytes: Uint8Array): ManifestAsset {
+  return { path, sha256: new Bun.CryptoHasher("sha256").update(bytes).digest("hex"), size: bytes.length }
+}
+
 // The project root the assets/ convention hangs off: the nearest package.json
 // dir, or the entry's own dir when there is none.
 export function projectDirFor(sourcePath: string): string {

package/src/repl.ts

@@ -4,7 +4,7 @@ import { readdirSync } from "node:fs"
 import { state, print, printErr, shutdown } from "./util"
 import { buildReload, getClients, sendReload, sendStop, sendStats, sendWatch, showBuildFailure } from "./dev-server"
 import { bundle } from "./bundler"
-import { buildManifest, projectDirFor } from "./project"
+import { buildManifest } from "./project"
 import { startWatcher, stopWatcher } from "./watcher"
 
 // Resolve repl client indexes ("0 2") against the server's client list,
@@ -101,6 +101,15 @@ async function cmdLoad(file: string) {
     return
   }
   let path = resolve(file)
+  // Same rule as /__control__/load (control.ts): a server run serves the
+  // project it started in, and an entry outside the project root cannot
+  // resolve the project's dependencies anyway.
+  let norm = (p: string) => p.replace(/\\/g, "/")
+  let root = norm(state.projectDir).replace(/\/+$/, "") + "/"
+  if (!norm(path).startsWith(root)) {
+    printErr(`[cli] Entry is outside the project root: ${path} is not under ${state.projectDir}. Restart srt in that project to work on it.`)
+    return
+  }
   if (file.endsWith(".tsx")) {
     let result = await bundle(path)
     if (!result) {
@@ -126,15 +135,14 @@ async function cmdLoad(file: string) {
   }
   state.source = path
   state.sourceDir = dirname(path)
-  state.projectDir = projectDirFor(path)
   startWatcher()
-  // The load also moves the server's file-serving root to the new source dir,
-  // its /assets/ root to the new project dir, and its rebuild entry to the
-  // new file (for a later MCP reload).
+  // The load also moves the server's file-serving root to the new source dir
+  // and its rebuild entry to the new file (for a later MCP reload). The
+  // project root - and with it the /assets/ root - is fixed for the life of
+  // the run.
   await sendReload(buildReload({ code: state.currentCode, manifest: state.currentManifest }), {
     latch: true,
     sourceDir: state.sourceDir,
-    projectDir: state.projectDir,
     entry: file.endsWith(".tsx") ? path : undefined,
     map: state.currentMap,
   })