@solidrt/cli 0.0.48 → 0.0.50

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/init.ts

@@ -1,7 +1,7 @@
 import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises"
 import { basename, dirname, join, resolve } from "node:path"
 import { source, values } from "../args"
-import { select, text } from "../prompt"
+import { multiselect, note, text } from "../prompt"
 
 const DEFAULT_NAME = "solidrt-app"
 
@@ -29,76 +29,57 @@ function packageName(dir: string): string {
 }
 
 const DEFAULT_TEMPLATE = "default"
-const TEMPLATE_MANIFEST = "template.json"
-
-// Each template's template.json declares which level the scaffolded app is
-// written at: "core" (only @solidrt/core, no component framework) or
-// "components" (built with @solidrt/components). The level decides the
-// generated dependencies; the description labels the template in the picker.
-interface TemplateInfo {
-  name: string
-  level: "core" | "components"
+
+// Optional packages an app can opt into on top of core. Each maps to a
+// dependency in the scaffold package.json (kept when selected, removed
+// otherwise) and optionally to a starter under scaffold/templates/.
+interface Extension {
+  pkg: string
+  template?: string
   description: string
 }
 
-// Templates are the directories under scaffold/templates/; each holds the files
-// that become the new project's src/, plus a template.json manifest. `default`
-// sorts first as the starting point, the rest alphabetically.
-async function listTemplates(): Promise<TemplateInfo[]> {
-  let entries = await readdir(TEMPLATES_DIR, { withFileTypes: true })
-  let names = entries
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name)
-    .sort((a, b) =>
-      a === DEFAULT_TEMPLATE ? -1 : b === DEFAULT_TEMPLATE ? 1 : a.localeCompare(b),
-    )
-  let templates: TemplateInfo[] = []
-  for (let name of names) {
-    // A missing manifest falls back to the components level: it keeps every
-    // dependency, so the scaffolded app works at either level.
-    let manifest = await readFile(join(TEMPLATES_DIR, name, TEMPLATE_MANIFEST), "utf8")
-      .then((raw) => JSON.parse(raw))
-      .catch(() => ({}))
-    templates.push({
-      name,
-      level: manifest.level === "core" ? "core" : "components",
-      description: typeof manifest.description === "string" ? manifest.description : "",
-    })
-  }
-  return templates
-}
+const EXTENSIONS: Extension[] = [
+  {
+    pkg: "@solidrt/components",
+    template: "components",
+    description: "component framework: widgets, theming, navigation",
+  },
+  { pkg: "@solidrt/3d", description: "general purpose 3D library" },
+]
 
-// Resolve which template to scaffold from: an explicit --template if valid, an
-// interactive picker on a TTY, else `default` (or the first available).
-async function resolveTemplate(): Promise<TemplateInfo> {
-  let templates = await listTemplates()
-  if (templates.length === 0) {
-    console.error(`!! No templates found in ${TEMPLATES_DIR}`)
-    process.exit(1)
-  }
-  let chosen = values.template
-  if (chosen) {
-    let found = templates.find((t) => t.name === chosen)
-    if (!found) {
-      let names = templates.map((t) => t.name).join(", ")
-      console.error(`!! Unknown template "${chosen}"; choose from: ${names}`)
-      process.exit(1)
+// Resolve which extensions the app takes: an explicit --with list if valid,
+// an interactive picker on a TTY, else none (core only).
+async function resolveExtensions(): Promise<Extension[]> {
+  let raw = values.with
+  if (raw !== undefined) {
+    let names = raw.split(",").map((n) => n.trim()).filter(Boolean)
+    let chosen: Extension[] = []
+    for (let name of names) {
+      let found = EXTENSIONS.find((e) => e.pkg === name)
+      if (!found) {
+        let all = EXTENSIONS.map((e) => e.pkg).join(", ")
+        console.error(`!! Unknown extension "${name}"; choose from: ${all}`)
+        process.exit(1)
+      }
+      if (!chosen.includes(found)) chosen.push(found)
     }
-    return found
-  }
-  if (process.stdin.isTTY) {
-    let picked = await select(
-      "Select a template",
-      templates.map((t) => {
-        // Core is the runtime every app has; anything else is a package the
-        // app opts into, so the picker marks it as such.
-        let name = t.level === "core" ? t.name : `${t.name} (extension)`
-        return { label: t.description ? `${name} - ${t.description}` : name, value: t.name }
-      }),
-    )
-    return templates.find((t) => t.name === picked)!
+    return chosen
   }
-  return templates.find((t) => t.name === DEFAULT_TEMPLATE) ?? templates[0]!
+  if (!process.stdin.isTTY) return []
+  // Core is the runtime every app has, so it is not a choice.
+  note("@solidrt/core is always included", "Packages")
+  let picked = await multiselect(
+    "Select extensions",
+    EXTENSIONS.map((e) => ({ label: `${e.pkg} - ${e.description}`, value: e.pkg })),
+  )
+  return EXTENSIONS.filter((e) => picked.includes(e.pkg))
+}
+
+// The starter src/ comes from the first selected extension that brings a
+// template; with none, the core `default` starter.
+function resolveTemplate(extensions: Extension[]): string {
+  return extensions.find((e) => e.template)?.template ?? DEFAULT_TEMPLATE
 }
 
 export async function runInitCommand() {
@@ -120,9 +101,11 @@ export async function runInitCommand() {
     process.exit(1)
   }
 
-  let template = await resolveTemplate()
+  let extensions = await resolveExtensions()
+  let template = resolveTemplate(extensions)
+  let summary = ["@solidrt/core", ...extensions.map((e) => e.pkg)].join(", ")
 
-  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${template.name})`)
+  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${summary})`)
   for (let { from, to } of TEMPLATE_FILES) {
     let dest = join(dir, to)
     await mkdir(dirname(dest), { recursive: true })
@@ -130,13 +113,11 @@ export async function runInitCommand() {
     console.log(`   Write ${to}`)
   }
 
-  // The chosen template's files become the project's src/. Entries may be
-  // nested directories (e.g. an asset folder), so copy recursively. The
-  // manifest describes the template rather than belonging to the app.
-  let templateDir = join(TEMPLATES_DIR, template.name)
+  // The template's files become the project's src/. Entries may be nested
+  // directories (e.g. an asset folder), so copy recursively.
+  let templateDir = join(TEMPLATES_DIR, template)
   await mkdir(join(dir, "src"), { recursive: true })
   for (let file of await readdir(templateDir)) {
-    if (file === TEMPLATE_MANIFEST) continue
     await cp(join(templateDir, file), join(dir, "src", file), { recursive: true })
     console.log(`   Write src/${file}`)
   }
@@ -149,12 +130,15 @@ export async function runInitCommand() {
   await writeFile(join(dir, "assets", "icon.svg"), await readFile(join(SCAFFOLD_DIR, "icon.svg")))
   console.log("   Write assets/icon.svg")
 
-  // The scaffold package.json carries a placeholder name; set it from the
-  // target folder. A core-level app gets no component framework dependency.
+  // The scaffold package.json carries a placeholder name and every extension
+  // dependency; set the name from the target folder and keep only the
+  // selected extensions.
   let pkgPath = join(dir, "package.json")
   let pkg = JSON.parse(await readFile(pkgPath, "utf8"))
   pkg.name = packageName(dir)
-  if (template.level === "core") delete pkg.dependencies["@solidrt/components"]
+  for (let ext of EXTENSIONS) {
+    if (!extensions.includes(ext)) delete pkg.dependencies[ext.pkg]
+  }
   await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n")
 
   // Deps are declared in scaffold/package.json (Solid peers resolve via

package/src/commands/mcp.ts

@@ -9,14 +9,153 @@ 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, realpathSync } from "node:fs"
+import { values, DEFAULT_DEV_PORT } 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
+  }
+}
+
+// The two sides of a projectDir comparison come from different processes
+// (the server's entry path, the bridge's cwd) and only agree by construction
+// on the directory, not the spelling: an editor-spawned bridge on Windows
+// keeps its parent's lower-case drive letter while a shell writes it upper
+// case, and 8.3 names, symlinks and subst drives are the same class. Compare
+// the canonical path, so the spelling never decides.
+function sameDir(a: string, b: string): boolean {
+  if (a === b) return true
+  try {
+    return realpathSync.native(a) === realpathSync.native(b)
+  } catch {
+    return false
+  }
+}
+
+// Only ESRCH means the process is gone. EPERM is a live process this bridge
+// may not signal (Windows reports it for other users' processes), and a
+// bare try/catch would drop that healthy server from the registry.
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e: any) {
+    return e?.code === "EPERM"
+  }
+}
+
+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 records = liveRecords()
+  let matches = records.filter((r) => sameDir(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) {
+    // A lookup by key that fails against a small table prints the table: an
+    // empty registry, a dead pid and a record for another project are three
+    // different problems, and the reader can only tell them apart if the
+    // candidates are listed next to the key that was looked up.
+    let listing =
+      records.length === 0
+        ? `Registry ${devDir("servers")}: no records.`
+        : `Registry ${devDir("servers")}: ${records.length} record(s).\n` +
+          records
+            .map((r) => {
+              let session = r.port - DEFAULT_DEV_PORT
+              let flag = session >= 0 && session < 100 ? `-s ${session}` : `--port ${r.port}`
+              return `  port ${r.port} (${flag})  pid ${r.pid} (${pidAlive(r.pid) ? "alive" : "dead"})  serving ${r.projectDir}`
+            })
+            .join("\n")
+    return {
+      ok: false,
+      message: `No dev server for ${project}.\n${listing}\nStart one with srt run, or pin one of the servers above by passing its flag 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 || typeof body?.projectDir !== "string" || !sameDir(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 +163,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,
@@ -104,7 +243,7 @@ let TOOLS: {
     name: "get_stats",
     readOnly: true,
     description:
-      "Performance statistics from a running app client: fps, CPU%, memory, smoothed JS/layout/paint/hover frame times (ms), setProperty writes per frame, demand-gate reuse/skip counts per second, and live texture count. Layout-activity counters cover the last full rebuild, raw: nodes (live node count, mounted AND detached), mountedNodes/orphanNodes (live at query time: nodes reachable from the root vs not - orphans growing at a stable tree shape mean an unmount leak; absent when no engine is running), measureCalls (text measures; mostly cache hits, cheap), paraShapes (paragraphs actually shaped; the expensive signal - high layoutMs with near-zero paraShapes means the cost is not text shaping), dirtiedNodes (layout caches cleared by property writes since the previous rebuild; how much of the tree a write burst invalidated), cacheGets/cacheHits (layout-cache lookups during the rebuild; a hit on a container skips its whole subtree, so a healthy incremental rebuild shows a near-100% hit rate - a low rate at scale means the layout cache is being defeated). GPU-side health, read live at query time (absent when no engine is running): rasterQueue (raster commands sent but not yet executed; stuck nonzero means the raster thread is backlogged - the state where fps and frameMs go blind because no frames complete), idleTicks (cumulative idle frame signals emitted while the GPU had nothing queued; idleTicks racing while rasterQueue sits nonzero would mean the idle-tick gate is broken), fenceTimeouts (cumulative present-fence waits that expired instead of signaling - each one is a frame where the GPU was over budget for 100ms+ and one-frame-in-flight pacing was lost; zero on a healthy machine, climbing means the GPU is the bottleneck right now), gpuPasses/gpuPassMs (cumulative shader/pipeline target renders on the raster thread and the wall time they took in whole ms - diff two queries to get a rate; passes racing far ahead of frames means redundant target re-renders, the failure mode where fps and frameMs look healthy while the raster thread drowns; the ms figure is raster-thread occupancy issuing the passes, not GPU-side duration), rasterCmdMs (cumulative wall time in whole ms the raster thread spent executing non-frame commands - texture uploads, readbacks, offscreen rasterizations, shader compiles, param writes and the target re-renders they trigger; the work frameMs never sees, so rasterCmdMs growing much faster than frames are presented means the raster thread is drowning in side work even if every counter above looks calm).",
+      "Performance statistics from a running app client: fps, CPU%, memory, smoothed JS/layout/paint/hover frame times (ms), setProperty writes per frame, demand-gate reuse/skip counts per second, and live texture count. Layout-activity counters cover the last full rebuild, raw: nodes (live node count, mounted AND detached), mountedNodes/orphanNodes (live at query time: nodes reachable from the root vs not - orphans growing at a stable tree shape mean an unmount leak; absent when no engine is running), measureCalls (text measures; mostly cache hits, cheap), paraShapes (paragraphs actually shaped, i.e. words the shared word cache did not have; the expensive signal - high layoutMs with near-zero paraShapes means the cost is not text shaping), wordHits (words answered from the shared word cache; hits high and paraShapes near zero on a text change means only the changed words were reshaped), dirtiedNodes (layout caches cleared by property writes since the previous rebuild; how much of the tree a write burst invalidated), cacheGets/cacheHits (layout-cache lookups during the rebuild; a hit on a container skips its whole subtree, so a healthy incremental rebuild shows a near-100% hit rate - a low rate at scale means the layout cache is being defeated). GPU-side health, read live at query time (absent when no engine is running): rasterQueue (raster commands sent but not yet executed; stuck nonzero means the raster thread is backlogged - the state where fps and frameMs go blind because no frames complete), idleTicks (cumulative idle frame signals emitted while the GPU had nothing queued; idleTicks racing while rasterQueue sits nonzero would mean the idle-tick gate is broken), fenceTimeouts (cumulative present-fence waits that expired instead of signaling - each one is a frame where the GPU was over budget for 100ms+ and one-frame-in-flight pacing was lost; zero on a healthy machine, climbing means the GPU is the bottleneck right now), gpuPasses/gpuPassMs (cumulative shader/pipeline target renders on the raster thread and the wall time they took in whole ms - diff two queries to get a rate; passes racing far ahead of frames means redundant target re-renders, the failure mode where fps and frameMs look healthy while the raster thread drowns; the ms figure is raster-thread occupancy issuing the passes, not GPU-side duration), rasterCmdMs (cumulative wall time in whole ms the raster thread spent executing non-frame commands - texture uploads, readbacks, offscreen rasterizations, shader compiles, param writes and the target re-renders they trigger; the work frameMs never sees, so rasterCmdMs growing much faster than frames are presented means the raster thread is drowning in side work even if every counter above looks calm).",
     inputSchema: { client: CLIENT_ARG },
   },
   {