@solidrt/cli 0.0.26 → 0.0.27

package/package.json

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

package/scaffold/AGENTS.md

@@ -97,6 +97,66 @@ its tools over guessing at runtime state:
 - get_render_tree: what the app actually rendered - node kinds, text, and
   window-relative boxes
 - get_stats: fps, CPU/memory, frame phase timings, setProperty rate
+- get_snapshot: PNG capture of any render-tree node's pixels (get node ids
+  from get_render_tree; the window node captures everything)
+- get_gpu_resources: inventory of GPU state - textures (size, render target
+  or not), vertex buffers (byteLength), pipelines (draw count, attribute
+  layout, bound textures, last-applied uniform values)
+- get_texture: any GPU texture read back as a PNG by id - atlases, data
+  textures, and shader/pipeline render targets alike (a render target is
+  "what this pipeline last drew", no frame or snapshot needed); crop with
+  x/y/width/height
+- get_buffer: a vertex-buffer range decoded to numbers (f32/u16/u8, 64 KiB
+  per call) - verify geometry after a writeBuffer instead of inferring it
+  from pixels
+- reload: rebuild from source and push to every client - THE dev loop is
+  edit -> reload -> get_logs -> get_snapshot. reload surfaces build errors
+  but not type errors; run the typecheck separately.
 
 The tools need a running app: if list_clients is empty, ask the user to start
 `bunx srt run src/index.tsx`.
+
+## Debugging a running app (lessons that cost real time)
+
+- console.log + get_logs is your primary probe into runtime state. For state
+  you will want repeatedly (a pose, a mode, a counter), bind a debug key that
+  logs it and read it back via get_logs.
+- Key events are delivered ONLY to the focused node (no bubbling): call
+  setFocus(node.id) from the window's ref or onKeyDown never fires. This
+  runtime names arrow keys "Left"/"Right"/"Up"/"Down", not "ArrowLeft".
+- Idle frames skip work: shaders/pipelines only re-render when their params
+  change, so measure performance while uniforms are actually changing, and
+  a get_snapshot of an idle client can time out - retry, make the app
+  produce a frame, or use get_texture on the pipeline's render target, which
+  reads the last-drawn frame without needing a new one.
+- When a human reports a visual bug: capture a snapshot and SAY WHAT YOU SEE
+  in it before investigating, so you agree on the symptom. If you cannot see
+  the problem in the capture, say that instead of guessing.
+- GPU/geometry bugs: inspect the actual GPU data FIRST - get_gpu_resources
+  for draw counts/uniforms/sizes, get_texture for atlas or data-texture
+  contents ("is this tile blank?" is a ten-second question), get_buffer for
+  vertex data. The pixels only tell you THAT something is wrong; the
+  resources tell you WHERE the data stops being right. In a one-big-pipeline
+  app the render tree is a single <texture> leaf and tells you nothing -
+  these tools are the visibility layer behind it. Only when the GPU data is
+  all correct (so the bug is in producing it, or in the shader), reproduce
+  the math CPU-side in a scratch bun script against the app's real data and
+  print values.
+- Validate assets at load time and log anomalies (missing lumps/files,
+  fully-transparent composites, zero-sized images). Silent fallbacks hide
+  bugs for days; a one-line warning surfaces them the first run.
+- After every reload the app restarts from its initial state. If reaching
+  the bug site takes navigation, add a dev shortcut (teleport key, noclip,
+  initial-state override) before iterating - the round trips add up fast.
+- Clamp onFrame time deltas to [0, cap], not just capped: across a hot
+  reload the runtime's tick counter resets AFTER the new instance's first
+  frame, so the second frame computes a hugely NEGATIVE delta.
+  Math.min(dt, cap) lets it through, and one bad frame can corrupt anything
+  integrated from dt (positions fly off, accumulators go so negative they
+  never recover). Math.max(0, Math.min(dt, cap)) costs nothing.
+- Frames are demand-gated: JS frame callbacks only run when the previous
+  frame changed something (input, signal write, GPU upload). An app whose
+  onFrame returns early without side effects on its first frame never gets
+  a second one - self-running animation (game clocks, shader-driven
+  effects) must make one state change at startup to prime the loop; after
+  that its own writes keep it awake.

package/scaffold/package.json

@@ -9,12 +9,12 @@
     "android": "srt client --android"
   },
   "dependencies": {
-    "@solidrt/core": "0.0.26",
-    "@solidrt/components": "0.0.26"
+    "@solidrt/core": "0.0.27",
+    "@solidrt/components": "0.0.27"
   },
   "devDependencies": {
-    "@solidrt/cli": "0.0.26",
-    "@solidrt/flux-types": "0.0.26",
+    "@solidrt/cli": "0.0.27",
+    "@solidrt/flux-types": "0.0.27",
     "typescript": "^7"
   }
 }

package/server/control.ts

@@ -1,4 +1,6 @@
 import { state } from "./state"
+import { rebuildAndBroadcast } from "./rebuild"
+import { remapPositions } from "./remap"
 import type { ServerWebSocket } from "flux:http"
 
 // The control API under /__control__/: read-only introspection of connected
@@ -29,8 +31,9 @@ function sleep(ms: number): Promise<void> {
 }
 
 /// A `log` message arrived from a client: buffer it and wake long-polls.
+/// Bundle positions in stack traces are remapped to .tsx sources on the way in.
 export function appendLog(client: number, level: string, text: string) {
-  logs.push({ seq: ++logSeq, at: Date.now(), client, level, text })
+  logs.push({ seq: ++logSeq, at: Date.now(), client, level, text: remapPositions(text, state.currentMap) })
   if (logs.length > LOG_CAP) logs.splice(0, logs.length - LOG_CAP)
   let waiters = logWaiters
   logWaiters = []
@@ -55,6 +58,7 @@ export function clientList(withAddress = false) {
     id: info.id,
     platform: info.platform,
     version: info.version,
+    profile: info.profile,
     capabilities: info.capabilities,
     ...(withAddress ? { address: ws.remoteAddress ?? null } : {}),
   }))
@@ -86,7 +90,9 @@ async function handleQuery(query: Map<string, string>, kind: string, extra?: Rec
   let msg = await Promise.race([reply, sleep(QUERY_TIMEOUT_MS)])
   pendingQueries.delete(id)
   if (!msg) return Response.json({ error: "Query timed out" }, { status: 504 })
-  if (msg.error) return Response.json({ error: msg.error }, { status: 502 })
+  // Error strings may carry stack traces (e.g. a debug command threw); remap
+  // bundle positions to .tsx sources like appendLog does for forwarded logs.
+  if (msg.error) return Response.json({ error: remapPositions(String(msg.error), state.currentMap) }, { status: 502 })
   return Response.json(msg.data)
 }
 
@@ -126,6 +132,55 @@ export async function handleControl(req: Request, path: string, query: Map<strin
       if (!Number.isFinite(nodeId)) return Response.json({ error: "Snapshot requires ?node=<id>" }, { status: 400 })
       return handleQuery(query, "snapshot", { nodeId })
     }
+    case "/__control__/gpu":
+      return handleQuery(query, "gpu")
+    case "/__control__/debug": {
+      // GET lists the app's registered debug commands; POST calls one, with
+      // an optional JSON body as its args.
+      if (req.method !== "POST") return handleQuery(query, "debug_list")
+      let name = query.get("name")
+      if (!name) return Response.json({ error: "Debug call requires ?name=<command>" }, { status: 400 })
+      let args: unknown = null
+      try {
+        args = await req.json()
+      } catch {}
+      return handleQuery(query, "debug_call", { name, args })
+    }
+    case "/__control__/texture": {
+      let textureId = parseInt(query.get("id") ?? "", 10)
+      if (!Number.isFinite(textureId)) return Response.json({ error: "Texture requires ?id=<textureId>" }, { status: 400 })
+      // Optional crop: all four of x/y/width/height, in texture pixels.
+      let rectParams = ["x", "y", "width", "height"].map((k) => query.get(k))
+      let extra: Record<string, unknown> = { textureId }
+      if (rectParams.some((v) => v !== undefined)) {
+        let [x, y, width, height] = rectParams.map((v) => parseInt(v ?? "", 10))
+        if (![x, y, width, height].every(Number.isFinite))
+          return Response.json({ error: "Texture rect requires all of x, y, width, height" }, { status: 400 })
+        extra.rect = { x, y, width, height }
+      }
+      return handleQuery(query, "texture", extra)
+    }
+    case "/__control__/buffer": {
+      let bufferId = parseInt(query.get("id") ?? "", 10)
+      if (!Number.isFinite(bufferId)) return Response.json({ error: "Buffer requires ?id=<bufferId>" }, { status: 400 })
+      let extra: Record<string, unknown> = { bufferId }
+      let byteOffset = parseInt(query.get("offset") ?? "", 10)
+      if (Number.isFinite(byteOffset)) extra.byteOffset = byteOffset
+      let length = parseInt(query.get("length") ?? "", 10)
+      if (Number.isFinite(length)) extra.length = length
+      let as = query.get("as")
+      if (as !== undefined) extra.as = as
+      return handleQuery(query, "buffer", extra)
+    }
+    case "/__control__/reload": {
+      // Explicit rebuild-and-push, the primary way a coding agent applies its
+      // edits (srt mcp's reload tool). Unlike the repl's file watcher this is
+      // on demand, so a burst of edits collapses into one reload.
+      if (req.method !== "POST") return Response.json({ error: "Reload requires POST" }, { status: 405 })
+      let error = await rebuildAndBroadcast()
+      if (error) return Response.json({ error }, { status: 502 })
+      return Response.json({ ok: true, clients: state.clients.size })
+    }
     default:
       return Response.json({ error: "Unknown control endpoint" }, { status: 404 })
   }

package/server/main.ts

@@ -73,13 +73,18 @@ async function handleInternal(req: FluxRequest, server: Server, path: string): P
 
   switch (path) {
     case "/__internal__/reload": {
-      // { message, clients?, latch?, sourceDir? }: send `message` (a full
+      // { 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`).
+      // file-serving root (repl `load`); `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
+      // 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
+      state.currentMap = typeof body.map === "string" ? body.map : null
       let text = JSON.stringify(body.message)
       if (body.latch) state.currentReload = text
       sendTo(body.clients, text)
@@ -89,7 +94,10 @@ async function handleInternal(req: FluxRequest, server: Server, path: string): P
       let body = await req.json()
       // A broadcast stop also forgets the latched reload, so a client that
       // connects afterwards starts clean.
-      if (!body.clients) state.currentReload = null
+      if (!body.clients) {
+        state.currentReload = null
+        state.currentMap = null
+      }
       sendTo(body.clients, JSON.stringify({ type: "stop" }))
       return new Response("", { status: 204 })
     }
@@ -215,7 +223,7 @@ serve({
   websocket: {
     open(ws) {
       let id = state.nextClientId++
-      state.clients.set(ws, { platform: "unknown", version: "unknown", id, capabilities: [] })
+      state.clients.set(ws, { platform: "unknown", version: "unknown", profile: "unknown", id, capabilities: [] })
       console.log(`[cli] Client connected ${ws.remoteAddress ?? "unknown"}`)
       // Advertise our real LAN address so clients dialed over a loopback hop
       // can show/remember the directly reachable address (see connection.rs).
@@ -239,6 +247,7 @@ serve({
           state.clients.set(ws, {
             platform: data.platform ?? "unknown",
             version: data.version ?? "unknown",
+            profile: data.profile ?? "unknown",
             id: existing?.id ?? state.nextClientId++,
             capabilities: Array.isArray(data.capabilities) ? data.capabilities.map(String) : [],
           })

package/server/rebuild.ts

@@ -0,0 +1,54 @@
+import { command } from "flux:subprocess"
+import { state } from "./state"
+
+// Server-owned "rebuild and push": the single place the running app is rebuilt
+// from source on demand (an MCP reload). The srt repl still bundles in-process
+// for its own keystroke reloads, but both routes call the same bundle-cli, so
+// the bundling logic cannot drift. Making the server the rebuild authority is
+// the interim step toward folding the whole CLI into flux (see
+// okf/backlog/cli-flux-migration.md).
+
+// Build the reload message the same way srt's buildReload does, so a
+// server-triggered reload is indistinguishable from a repl-triggered one to
+// clients. proxyFiles/proxyHttp are message flags, not build inputs.
+function buildReload(code: string) {
+  let config = state.config
+  return { type: "reload", proxyFiles: config.proxyFiles, proxyHttp: config.proxyHttp, code }
+}
+
+// Rebuild from state.config.entry via the external bundle-cli subprocess, then
+// latch (for late-joining clients) and broadcast the reload to every connected
+// client. Resolves with an error message on failure (no entry configured, or a
+// build error), or null on success.
+export async function rebuildAndBroadcast(): Promise<string | null> {
+  let config = state.config
+  if (!config.entry) {
+    return "No app entry to rebuild. Start srt with a source file (srt run src/index.tsx)."
+  }
+
+  let params = JSON.stringify({
+    entry: config.entry,
+    devBase: state.serverUrl,
+    dev: true,
+    minify: config.minify,
+  })
+
+  let result = await command(config.bundlerCmd[0]!, [...config.bundlerCmd.slice(1), params]).output()
+  if (!result.success) {
+    let stderr = typeof result.stderr === "string" ? result.stderr : ""
+    return `Rebuild failed:\n${stderr.trim()}`
+  }
+
+  // bundle-cli writes one JSON object { code, map } to stdout.
+  let bundle: { code?: string; map?: string | null }
+  try {
+    bundle = JSON.parse(typeof result.stdout === "string" ? result.stdout : "")
+  } catch {
+    return "Rebuild failed: unreadable bundler output"
+  }
+  state.currentMap = bundle.map ?? null
+  let text = JSON.stringify(buildReload(bundle.code ?? ""))
+  state.currentReload = text
+  for (let ws of state.clients.keys()) ws.send(text)
+  return null
+}

package/server/remap.ts

@@ -0,0 +1,47 @@
+import { TraceMap, originalPositionFor } from "@jridgewell/trace-mapping"
+
+// Stack-trace remapping for forwarded client logs. The runtime evaluates the
+// bundle as module "main", so QuickJS frames cite bundle positions like
+// "at boom (main:212:9)". With the current reload's sourcemap latched on the
+// server (state.currentMap), those positions are rewritten to the original
+// .tsx sources before a log entry is buffered.
+
+// The parsed map is cached per map text; a reload swaps the text and the next
+// lookup rebuilds the tracer.
+let cachedText: string | null = null
+let tracer: TraceMap | null = null
+
+function tracerFor(map: string | null): TraceMap | null {
+  if (map !== cachedText) {
+    cachedText = map
+    tracer = null
+    if (map) {
+      try {
+        tracer = new TraceMap(JSON.parse(map))
+      } catch {
+        // A malformed map disables remapping until the next reload.
+      }
+    }
+  }
+  return tracer
+}
+
+/**
+ * Rewrite every "main:LINE:COL" (or "main:LINE") position in `text` to its
+ * original source position, e.g. "src/app.tsx:42:7". Positions the map has no
+ * entry for, and all text when `map` is null, pass through unchanged.
+ * QuickJS lines and columns are 1-based; sourcemap columns are 0-based.
+ */
+export function remapPositions(text: string, map: string | null): string {
+  if (!map || !text.includes("main:")) return text
+  let t = tracerFor(map)
+  if (!t) return text
+  return text.replace(/\bmain:(\d+)(?::(\d+))?\b/g, (frame, line, column) => {
+    let pos = originalPositionFor(t, {
+      line: parseInt(line, 10),
+      column: column ? Math.max(parseInt(column, 10) - 1, 0) : 0,
+    })
+    if (pos.source == null || pos.line == null) return frame
+    return `${pos.source}:${pos.line}:${(pos.column ?? 0) + 1}`
+  })
+}

package/server/state.ts

@@ -11,6 +11,15 @@ export type Config = {
   address: string
   proxyFiles: boolean
   proxyHttp: boolean
+  /** The app entry (absolute .tsx/.jsx path) the server rebuilds on an
+   * MCP-triggered reload, or undefined when srt was started without a source.
+   * Moved by the repl `load` command via /__internal__/reload. */
+  entry?: string
+  /** Minify the rebuild output, mirroring the srt --minify flag. */
+  minify: boolean
+  /** How the server invokes the external bundler: [bunPath, bundleCliPath],
+   * spawned with a JSON params argument appended (see rebuild.ts). */
+  bundlerCmd: string[]
   /** Enable the sqlite-backed proxy cache. */
   cache: boolean
   /** Directory holding .srt-cache.db. */
@@ -22,7 +31,7 @@ export type Config = {
   tunnel: boolean
 }
 
-export type ClientInfo = { platform: string; version: string; id: number; capabilities: string[] }
+export type ClientInfo = { platform: string; version: string; profile: string; id: number; capabilities: string[] }
 
 export let state = {
   config: undefined as unknown as Config,
@@ -33,6 +42,13 @@ export let state = {
    * Set by /__internal__/reload posts with `latch`, cleared by a broadcast stop.
    */
   currentReload: null as string | null,
+  /**
+   * The running bundle's sourcemap (JSON text, bundle -> .tsx sources), used
+   * to remap stack traces in forwarded client logs (see control.ts). Replaced
+   * on every reload; a reload without a map clears it so frames are never
+   * remapped against a stale map.
+   */
+  currentMap: null as string | null,
   sourceDir: "",
   serverUrl: "",
   stats: false,

package/src/bundle-cli.ts

@@ -0,0 +1,12 @@
+// 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.
+
+import { bundleWith, type BundleOptions } from "./bundler"
+
+let params = JSON.parse(process.argv[2] ?? "{}") as BundleOptions
+let result = await bundleWith(params)
+if (!result) process.exit(1)
+process.stdout.write(JSON.stringify(result))

package/src/bundler.ts

@@ -1,6 +1,7 @@
 import { transformAsync } from "@babel/core"
 import jsx from "@babel/plugin-syntax-jsx"
 import ts from "@babel/preset-typescript"
+import remapping from "@jridgewell/remapping"
 import solid from "babel-preset-solid"
 import { type BunPlugin, type BuildArtifact } from "bun"
 import { readFileSync } from "node:fs"
@@ -53,7 +54,7 @@ function binaryImport({ types: t }: { types: any }) {
 // build, skipping emitted asset outputs. Bun's file loader emits binary assets
 // as extra outputs; the callers that flatten outputs into a single code string
 // must not glue those raw bytes onto the program.
-export async function codeFromOutputs(outputs: BuildArtifact[]): Promise<string> {
+async function codeFromOutputs(outputs: BuildArtifact[]): Promise<string> {
   let code = ""
   for (let o of outputs) {
     if (o.kind === "entry-point" || o.kind === "chunk") code += await o.text()
@@ -62,61 +63,106 @@ export async function codeFromOutputs(outputs: BuildArtifact[]): Promise<string>
 }
 
 // Bun build plugin that runs JSX/TSX through babel-preset-solid (universal
-// generate, targeting @solidrt/core) plus the TS preset.
-function solidPlugin(): BunPlugin {
+// generate, targeting @solidrt/core) plus the TS preset. Plain .js/.ts app
+// modules take the same path (solid is a no-op without JSX) so binaryImport
+// can rewrite their `with { type: "binary" }` imports too; dependency code
+// (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 {
   return {
     name: "bun-plugin-solid",
     setup: (build) => {
-      build.onLoad({ filter: /\.(js|ts)x$/ }, async (args) => {
+      build.onLoad({ filter: /\.(js|ts)x?$/ }, async (args) => {
+        if (!/\.(js|ts)x$/.test(args.path) && args.path.includes("node_modules")) return
         let file = Bun.file(args.path)
         let code = await file.text()
         let transforms = await transformAsync(code, {
           filename: args.path,
+          sourceMaps: !!babelMaps,
           presets: [[solid, { moduleName: "@solidrt/core", generate: "universal" }], [ts]],
           plugins: [jsx, binaryImport],
         })
+        if (babelMaps && transforms?.map) babelMaps.set(args.path, transforms.map)
         return { contents: transforms?.code ?? "", loader: "js" }
       })
     },
   }
 }
 
-export async function bundle(entry = source) {
-  let result = null
+export type BundleOptions = { entry: string; devBase?: string; dev: boolean; minify: boolean }
 
-  let devBase = state.serverUrl ?? undefined
-  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"})`)
+export type BundleResult = {
+  code: string
+  /** Composed sourcemap JSON (bundle -> original .tsx sources), dev builds only. */
+  map: string | null
+}
+
+// The pure bundle: every input is explicit, so it runs identically in the srt
+// (Bun) process and in the standalone bundle-cli subprocess the dev server
+// spawns. It never touches the ambient args/state singletons and never prints
+// progress (callers own that), so its stdout stays clean for subprocess use.
+export async function bundleWith(opts: BundleOptions): Promise<BundleResult | null> {
   let define: Record<string, string> = {
-    "process.env.NODE_ENV": dev ? "development" : "production",
+    "process.env.NODE_ENV": opts.dev ? "development" : "production",
   }
-  if (devBase) define.__SRT_DEV_BASE__ = devBase
+  if (opts.devBase) define.__SRT_DEV_BASE__ = opts.devBase
 
+  let babelMaps = opts.dev ? new Map<string, object>() : undefined
+  let result = null
   try {
     result = await Bun.build({
-      entrypoints: [entry!],
+      entrypoints: [opts.entry],
       target: "browser",
       format: "esm",
-      minify: values.minify,
+      minify: opts.minify,
       external: ["flux:*", "srt:*"],
       define,
       loader: { ".svg": "text" },
-      plugins: [solidPlugin()],
+      sourcemap: opts.dev ? "external" : "none",
+      plugins: [solidPlugin(babelMaps)],
     })
   } catch (e) {
     console.error("[cli] compile error:\n", e)
     return null
   }
 
-  if (result?.success) {
-    return result
+  if (!result.success) {
+    for (let msg of result.logs) console.error(msg)
+    return null
   }
 
-  if (result) {
-    for (let msg of result?.logs) console.error(msg)
-  }
-  return null
+  return { code: await codeFromOutputs(result.outputs), map: await composeMap(result.outputs, babelMaps) }
+}
+
+// Compose Bun's bundle map (babel output -> bundle) with the per-file Babel
+// maps (original source -> babel output) so positions point at the .tsx
+// sources. Bun ignores sourcemaps in plugin onLoad contents, so this second
+// hop has to happen here. Only a single-artifact build gets a map: code
+// splitting is off, and concatenated artifacts would invalidate offsets.
+async function composeMap(outputs: BuildArtifact[], babelMaps?: Map<string, object>): Promise<string | null> {
+  if (!babelMaps) return null
+  let js = outputs.filter((o) => o.kind === "entry-point" || o.kind === "chunk")
+  if (js.length !== 1 || !js[0]!.sourcemap) return null
+  let bunMap = JSON.parse(await js[0]!.sourcemap.text())
+  let composed = remapping(bunMap, (file: string) => {
+    // Bun writes cwd-relative source paths; the babel maps are keyed by the
+    // absolute path. Serve each map exactly once: remapping asks again for a
+    // served map's own original source, and that lookup must return null.
+    let abs = resolvePath(file)
+    let map = babelMaps.get(abs)
+    babelMaps.delete(abs)
+    return (map as any) ?? null
+  })
+  return composed.toString()
+}
+
+export async function bundle(entry = source) {
+  let devBase = state.serverUrl ?? undefined
+  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 })
 }
 
 export async function bundleTo(outfile: string) {
@@ -125,7 +171,7 @@ export async function bundleTo(outfile: string) {
     console.error("Build failed")
     process.exit(1)
   }
-  await Bun.write(outfile, await codeFromOutputs(result.outputs))
+  await Bun.write(outfile, result.code)
   return result
 }
 
@@ -153,7 +199,7 @@ export async function bundleSolid(): Promise<string> {
     console.error("Build failed")
     process.exit(1)
   }
-  return codeFromOutputs(result.outputs)
+  return result.code
 }
 
 // Compile JS source to QuickJS bytecode via the fluxc binary.

package/src/commands/bundle.ts

@@ -1,5 +1,5 @@
 import { values, source, isPrebuilt } from "../args"
-import { bundle, bundleTo, bundleFlux, compileToBytecode, codeFromOutputs } from "../bundler"
+import { bundle, bundleTo, bundleFlux, compileToBytecode } from "../bundler"
 import { resolve } from "path"
 
 // Write to stdout and resolve only once the whole payload is flushed.
@@ -55,7 +55,7 @@ export async function runBundleCommand() {
       console.error("Build failed")
       process.exit(1)
     }
-    await writeStdout(await codeFromOutputs(result.outputs))
+    await writeStdout(result.code)
     process.exit()
   }
 
@@ -65,15 +65,12 @@ export async function runBundleCommand() {
       console.error("Build failed")
       process.exit(1)
     }
-    let jsCode = await codeFromOutputs(result.outputs)
-    await writeBytecode(jsCode, baseName + ".srt.bin")
+    await writeBytecode(result.code, baseName + ".srt.bin")
     process.exit()
   }
 
   let jsOutfile = baseName + ".srt.js"
   let result = await bundleTo(jsOutfile)
-  for (let output of result.outputs) {
-    console.log(`>> wrote ${output.size} bytes to ${jsOutfile}`)
-  }
+  console.log(`>> wrote ${result.code.length} bytes to ${jsOutfile}`)
   process.exit()
 }

package/src/commands/mcp.ts

@@ -5,16 +5,25 @@
 //
 // stdout is the JSON-RPC channel; nothing here may print to it.
 
+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 { DEV_PORT } from "../dev-server"
 
 const CONTROL_BASE = `http://127.0.0.1:${DEV_PORT}/__control__`
 
 type ControlResult = { ok: true; body: any } | { ok: false; message: string }
 
-async function control(path: string): Promise<ControlResult> {
+async function control(path: string, method: "GET" | "POST" = "GET", payload?: unknown): Promise<ControlResult> {
   let resp
   try {
-    resp = await fetch(CONTROL_BASE + path)
+    let init: RequestInit = { method }
+    if (payload !== undefined) {
+      init.headers = { "content-type": "application/json" }
+      init.body = JSON.stringify(payload)
+    }
+    resp = await fetch(CONTROL_BASE + path, init)
   } catch {
     return {
       ok: false,
@@ -29,70 +38,110 @@ async function control(path: string): Promise<ControlResult> {
   return { ok: true, body }
 }
 
-let TOOLS = [
+let CLIENT_ARG = z
+  .number()
+  .int()
+  .describe("Client id from list_clients (default: the only connected client)")
+  .optional()
+
+let TOOLS: { name: string; description: string; inputSchema: Record<string, z.ZodTypeAny> }[] = [
   {
     name: "list_clients",
     description:
-      "List the app clients connected to the SolidRT dev server. Each entry has id (pass it as `client` to the other tools), platform, runtime version, and the capability names compiled into that client's runtime.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      "List the app clients connected to the SolidRT dev server. Each entry has id (pass it as `client` to the other tools), platform, runtime version (git describe; a -dirty suffix means the binary was built from uncommitted engine changes), build profile (debug/release), and the capability names compiled into that client's runtime. Use version/profile to check whether a connected binary contains a given engine change before debugging against it.",
+    inputSchema: {},
   },
   {
     name: "get_logs",
     description:
       "Read console output and runtime errors from connected app clients. Returns entries (seq, at, client, level, text) plus `latest`, the newest seq. Pass `since` (a seq or `latest` from a previous call) to only get newer entries; pass `wait_ms` to hold the call until new output arrives, e.g. right after triggering a reload.",
     inputSchema: {
-      type: "object",
-      properties: {
-        since: {
-          type: "integer",
-          description: "Only return entries with seq greater than this (default 0: the whole buffer)",
-        },
-        wait_ms: {
-          type: "integer",
-          description: "If nothing is newer than `since`, wait up to this many milliseconds for new output (max 30000)",
-        },
-      },
-      additionalProperties: false,
+      since: z
+        .number()
+        .int()
+        .describe("Only return entries with seq greater than this (default 0: the whole buffer)")
+        .optional(),
+      wait_ms: z
+        .number()
+        .int()
+        .describe("If nothing is newer than `since`, wait up to this many milliseconds for new output (max 30000)")
+        .optional(),
     },
   },
   {
     name: "get_stats",
     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.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        client: { type: "integer", description: "Client id from list_clients (default: the only connected client)" },
-      },
-      additionalProperties: false,
-    },
+    inputSchema: { client: CLIENT_ARG },
   },
   {
     name: "get_render_tree",
     description:
       "Snapshot of a running app client's render tree: node id, kind, window-relative box (x, y, width, height), text content, and children. Use it to verify what the app actually rendered and where.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        client: { type: "integer", description: "Client id from list_clients (default: the only connected client)" },
-      },
-      additionalProperties: false,
-    },
+    inputSchema: { client: CLIENT_ARG },
   },
   {
     name: "get_snapshot",
     description:
       "Capture a PNG image of any node in a running app client's render tree, by node id (get ids from get_render_tree). Returns the rendered pixels of that node's subtree, so you can see what the app actually drew. The node must be currently mounted and have a non-zero layout box.",
     inputSchema: {
-      type: "object",
-      properties: {
-        nodeId: { type: "integer", description: "Id of the node to capture, from get_render_tree" },
-        client: { type: "integer", description: "Client id from list_clients (default: the only connected client)" },
-      },
-      required: ["nodeId"],
-      additionalProperties: false,
+      nodeId: z.number().int().describe("Id of the node to capture, from get_render_tree"),
+      client: CLIENT_ARG,
+    },
+  },
+  {
+    name: "get_gpu_resources",
+    description:
+      "Inventory of a running app client's GPU resources: textures (id, size, whether a shader renders into it), vertex buffers (id, byteLength), and shader/pipeline targets (output textureId, kind, bufferId, topology, drawCount, depth, attribute layout, bound sampler texture ids, last-applied uniform values). Use it when the render tree is just a <texture> leaf and the interesting state lives behind it; follow up with get_texture or get_buffer to see contents.",
+    inputSchema: { client: CLIENT_ARG },
+  },
+  {
+    name: "get_texture",
+    description:
+      "Read back any GPU texture from a running app client as a PNG, by texture id (from get_gpu_resources, or the id returned by createImage/createShader/createPipeline in app code). Works on sampled textures (atlases, data textures) and shader/pipeline render targets alike, without needing a frame. Pass x/y/width/height to crop, e.g. one tile of an atlas.",
+    inputSchema: {
+      id: z.number().int().describe("Texture id, from get_gpu_resources"),
+      x: z.number().int().describe("Crop rect left edge in texture pixels (requires y, width, height)").optional(),
+      y: z.number().int().describe("Crop rect top edge in texture pixels").optional(),
+      width: z.number().int().describe("Crop rect width in texture pixels").optional(),
+      height: z.number().int().describe("Crop rect height in texture pixels").optional(),
+      client: CLIENT_ARG,
+    },
+  },
+  {
+    name: "get_buffer",
+    description:
+      "Read back part of a GPU vertex buffer from a running app client, decoded to numbers. Returns values plus byteOffset/byteLength actually read and bufferByteLength. Reads are capped at 64 KiB per call; page through larger buffers with offset. Use it to verify geometry after a writeBuffer, e.g. the dynamic sprite tail of a vertex buffer.",
+    inputSchema: {
+      id: z.number().int().describe("Buffer id, from get_gpu_resources"),
+      offset: z.number().int().describe("Byte offset to start reading at (default 0)").optional(),
+      length: z.number().int().describe("Number of values to read (default: the rest of the buffer, capped)").optional(),
+      as: z.enum(["f32", "u16", "u8"]).describe("How to decode the bytes (default f32)").optional(),
+      client: CLIENT_ARG,
+    },
+  },
+  {
+    name: "list_debug",
+    description:
+      "List the debug commands the running app registered via registerDebug from srt:dev. Returns the command names; call one with call_debug. Empty when the app registered none.",
+    inputSchema: { client: CLIENT_ARG },
+  },
+  {
+    name: "call_debug",
+    description:
+      "Call a debug command the running app registered via registerDebug from srt:dev, by name (from list_debug). `args` is passed to the command's function as its single argument; the command's return value comes back JSON-serialized (undefined as null). Commands run synchronously on the app's JS thread - use them to query app state (positions, counters, internal flags) or trigger app behavior (toggle a mode, open a door) without touching its real input handling.",
+    inputSchema: {
+      name: z.string().describe("Debug command name, from list_debug"),
+      args: z.record(z.string(), z.any()).describe("Argument object passed to the command (default: none)").optional(),
+      client: CLIENT_ARG,
     },
   },
+  {
+    name: "reload",
+    description:
+      "Rebuild the app from source and push it to every connected client. Call this after editing the app's .tsx/.jsx source to apply the changes: it bundles once and reloads all clients, so a burst of edits becomes a single explicit reload. Returns the number of clients reloaded, or a build error if the source failed to compile. Follow with get_logs to see runtime output from the reloaded app.",
+    inputSchema: {},
+  },
 ]
 
 function clientParam(args: any): string {
@@ -114,43 +163,72 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
       return control(`/stats${clientParam(args)}`)
     case "get_render_tree":
       return control(`/tree${clientParam(args)}`)
+    case "reload":
+      return control("/reload", "POST")
     case "get_snapshot": {
       if (typeof args?.nodeId !== "number") return { ok: false, message: "get_snapshot requires a numeric nodeId" }
       let params = new URLSearchParams({ node: String(args.nodeId) })
       if (typeof args?.client === "number") params.set("client", String(args.client))
       return control(`/snapshot?${params.toString()}`)
     }
+    case "get_gpu_resources":
+      return control(`/gpu${clientParam(args)}`)
+    case "list_debug":
+      return control(`/debug${clientParam(args)}`)
+    case "call_debug": {
+      if (typeof args?.name !== "string") return { ok: false, message: "call_debug requires a command name" }
+      let params = new URLSearchParams({ name: args.name })
+      if (typeof args?.client === "number") params.set("client", String(args.client))
+      return control(`/debug?${params.toString()}`, "POST", args?.args)
+    }
+    case "get_texture": {
+      if (typeof args?.id !== "number") return { ok: false, message: "get_texture requires a numeric id" }
+      let params = new URLSearchParams({ id: String(args.id) })
+      for (let key of ["x", "y", "width", "height"]) {
+        if (typeof args?.[key] === "number") params.set(key, String(args[key]))
+      }
+      if (typeof args?.client === "number") params.set("client", String(args.client))
+      return control(`/texture?${params.toString()}`)
+    }
+    case "get_buffer": {
+      if (typeof args?.id !== "number") return { ok: false, message: "get_buffer requires a numeric id" }
+      let params = new URLSearchParams({ id: String(args.id) })
+      if (typeof args?.offset === "number") params.set("offset", String(args.offset))
+      if (typeof args?.length === "number") params.set("length", String(args.length))
+      if (typeof args?.as === "string") params.set("as", args.as)
+      if (typeof args?.client === "number") params.set("client", String(args.client))
+      return control(`/buffer?${params.toString()}`)
+    }
     default:
       return { ok: false, message: `Unknown tool: ${name}` }
   }
 }
 
-export async function runMcpCommand() {
-  let { Server } = await import("@modelcontextprotocol/sdk/server/index.js")
-  let { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js")
-  let { ListToolsRequestSchema, CallToolRequestSchema } = await import("@modelcontextprotocol/sdk/types.js")
-
-  let server = new Server({ name: "solidrt", version: "0.0.0" }, { capabilities: { tools: {} } })
+function toContent(name: string, result: ControlResult): CallToolResult {
+  if (!result.ok) return { content: [{ type: "text", text: result.message }], isError: true }
+  if (name === "get_snapshot" || name === "get_texture") {
+    let { pngBase64, width, height } = result.body
+    let label = name === "get_snapshot" ? "Captured node snapshot" : "Texture contents"
+    return {
+      content: [
+        { type: "image", data: pngBase64, mimeType: "image/png" },
+        { type: "text", text: `${label}: ${width}x${height} px` },
+      ],
+    }
+  }
+  return { content: [{ type: "text", text: JSON.stringify(result.body, null, 2) }] }
+}
 
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+export async function runMcpCommand() {
+  let server = new McpServer({ name: "solidrt", version: "0.0.0" })
 
-  server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
-    let name = request.params.name
-    let result = await callTool(name, request.params.arguments ?? {})
-    if (!result.ok) {
-      return { content: [{ type: "text", text: result.message }], isError: true }
-    }
-    if (name === "get_snapshot") {
-      let { pngBase64, width, height } = result.body
-      return {
-        content: [
-          { type: "image", data: pngBase64, mimeType: "image/png" },
-          { type: "text", text: `Captured node snapshot: ${width}x${height} px` },
-        ],
-      }
-    }
-    return { content: [{ type: "text", text: JSON.stringify(result.body, null, 2) }] }
-  })
+  for (let tool of TOOLS) {
+    server.registerTool(
+      tool.name,
+      { description: tool.description, inputSchema: tool.inputSchema },
+      async (args: any) => toContent(tool.name, await callTool(tool.name, args ?? {})),
+    )
+  }
 
   // The stdin read keeps the process alive; it exits when the agent host
   // closes the pipe.

package/src/commands/server.ts

@@ -1,7 +1,7 @@
 import pkg from "../../package.json"
 import { source, isSource, isPrebuilt, values } from "../args"
 import { state, shutdown } from "../util"
-import { bundle, codeFromOutputs } from "../bundler"
+import { bundle } from "../bundler"
 import { startServer, buildReload, sendReload, showBuildFailure } from "../dev-server"
 import { startRepl } from "../repl"
 import { startWatcher } from "../watcher"
@@ -27,8 +27,9 @@ export async function runServerCommand() {
   if (source && isSource) {
     let initialResult = await bundle()
     if (initialResult) {
-      state.currentCode = await codeFromOutputs(initialResult.outputs)
-      await sendReload(buildReload({ code: state.currentCode }), { latch: true })
+      state.currentCode = initialResult.code
+      state.currentMap = initialResult.map
+      await sendReload(buildReload({ code: state.currentCode }), { latch: true, map: state.currentMap })
     } else {
       await showBuildFailure()
     }

package/src/dev-server.ts

@@ -30,9 +30,14 @@ 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 (repl `load`).
+ * moves the server's file-serving 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).
  */
-export async function sendReload(message: object, opts: { clients?: number[]; latch?: boolean; sourceDir?: string } = {}) {
+export async function sendReload(
+  message: object,
+  opts: { clients?: number[]; latch?: boolean; sourceDir?: string; entry?: string; map?: string | null } = {},
+) {
   await post("/reload", { message, ...opts })
 }
 
@@ -125,12 +130,20 @@ export async function startServer() {
   // computes it and passes it down.
   state.serverUrl = `${address}:${DEV_PORT}`
 
+  // How the server rebuilds on an MCP-triggered reload: it cannot call
+  // Bun.build itself (it is a flux process), so it spawns srt's own bun on the
+  // standalone bundle-cli entry. Both paths are known here at spawn time.
+  let bundleCli = fileURLToPath(new URL("./bundle-cli.ts", import.meta.url))
+
   let config = {
     port: DEV_PORT,
     sourceDir: state.sourceDir,
     address,
     proxyFiles: values["proxy-files"],
     proxyHttp: values["proxy-http"],
+    entry: state.source,
+    minify: values.minify,
+    bundlerCmd: [process.execPath, bundleCli],
     cache: values["proxy-http"],
     cacheDir: process.cwd(),
     capture: state.capture,

package/src/repl.ts

@@ -3,7 +3,7 @@ import { resolve, dirname } from "path"
 import { readdirSync } from "node:fs"
 import { state, print, printErr, shutdown } from "./util"
 import { buildReload, getClients, sendReload, sendStop, sendStats, showBuildFailure } from "./dev-server"
-import { bundle, codeFromOutputs } from "./bundler"
+import { bundle } from "./bundler"
 import { startWatcher, stopWatcher } from "./watcher"
 
 // Resolve repl client indexes ("0 2") against the server's client list,
@@ -27,6 +27,7 @@ async function cmdStop(args: string) {
   if (!args) {
     stopWatcher()
     state.currentCode = null
+    state.currentMap = null
     state.source = undefined
     await sendStop()
     print("[cli] Sent stop to all clients")
@@ -47,17 +48,18 @@ async function cmdReload(args: string) {
       await showBuildFailure()
       return
     }
-    state.currentCode = await codeFromOutputs(result.outputs)
+    state.currentCode = result.code
+    state.currentMap = result.map
   }
   let msg = buildReload({ code: state.currentCode })
   if (!args) {
-    await sendReload(msg, { latch: true })
+    await sendReload(msg, { latch: true, map: state.currentMap })
     print("[cli] Sent reload to all clients")
     return
   }
   let ids = await indexesToIds(args)
   if (ids.length) {
-    await sendReload(msg, { clients: ids })
+    await sendReload(msg, { clients: ids, map: state.currentMap })
     print(`[cli] Sent reload to client(s) ${ids.join(", ")}`)
   }
 }
@@ -102,9 +104,11 @@ async function cmdLoad(file: string) {
       printErr("[cli] Build failed")
       return
     }
-    state.currentCode = await codeFromOutputs(result.outputs)
+    state.currentCode = result.code
+    state.currentMap = result.map
   } else if (file.endsWith(".srt.js")) {
     state.currentCode = await Bun.file(path).text()
+    state.currentMap = null
   } else if (file.endsWith(".srt.bin")) {
     let bytes = await Bun.file(path).arrayBuffer()
     // One-shot: bytecode loads are pushed but not latched for late joiners.
@@ -118,8 +122,14 @@ async function cmdLoad(file: string) {
   state.source = path
   state.sourceDir = dirname(path)
   startWatcher()
-  // The load also moves the server's file-serving root to the new source dir.
-  await sendReload(buildReload({ code: state.currentCode }), { latch: true, sourceDir: state.sourceDir })
+  // 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).
+  await sendReload(buildReload({ code: state.currentCode }), {
+    latch: true,
+    sourceDir: state.sourceDir,
+    entry: file.endsWith(".tsx") ? path : undefined,
+    map: state.currentMap,
+  })
   print(`[cli] Loaded ${file}`)
 }
 

package/src/util.ts

@@ -8,6 +8,9 @@ export let state = {
   // What srt believes the current bundle is; the server process keeps its own
   // latched copy for late-joining clients (see packages/cli/server/).
   currentCode: null as string | null,
+  // The bundle's composed sourcemap (dev builds), sent to the server alongside
+  // reloads so it can remap logged stack traces to .tsx positions.
+  currentMap: null as string | null,
   source: undefined as string | undefined,
   sourceDir: process.cwd(),
   child: null as ReturnType<typeof Bun.spawn> | null,

package/src/watcher.ts

@@ -2,7 +2,7 @@ import { watch } from "node:fs"
 import { resolve, dirname } from "path"
 import { state, print, printErr } from "./util"
 import { buildReload, sendReload, showBuildFailure } from "./dev-server"
-import { bundle, codeFromOutputs } from "./bundler"
+import { bundle } from "./bundler"
 
 let currentWatcher: ReturnType<typeof watch> | null = null
 
@@ -31,7 +31,8 @@ export function startWatcher() {
       await showBuildFailure()
       return
     }
-    state.currentCode = await codeFromOutputs(result.outputs)
-    await sendReload(buildReload({ code: state.currentCode }), { latch: true })
+    state.currentCode = result.code
+    state.currentMap = result.map
+    await sendReload(buildReload({ code: state.currentCode }), { latch: true, map: state.currentMap })
   })
 }