@solidrt/cli 0.0.28 → 0.0.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -27,16 +27,17 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@solidrt/darwin-arm64": "0.0.28",
-    "@solidrt/linux-x64-gnu": "0.0.28",
-    "@solidrt/win32-x64-msvc": "0.0.28"
+    "@solidrt/darwin-arm64": "0.0.29",
+    "@solidrt/linux-arm64-gnu": "0.0.29",
+    "@solidrt/linux-x64-gnu": "0.0.29",
+    "@solidrt/win32-x64-msvc": "0.0.29"
   },
   "peerDependencies": {
-    "@solidrt/core": "0.0.28",
+    "@solidrt/core": "0.0.29",
     "typescript": "^7"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.28",
+    "@solidrt/flux-types": "0.0.29",
     "@types/bun": "latest"
   }
 }

package/scaffold/AGENTS.md

@@ -109,6 +109,14 @@ Authoritative references ship inside the installed packages - read them:
     createPortal content) that is visible at first mount throws "no mount
     target". Gate it behind a signal that starts false and open it after
     startup - overlay content is opened, not born open.
+17. An element-valued prop (children, a content/icon slot) compiles to a
+    getter that builds a fresh native subtree on EVERY read, and a subtree
+    that is never inserted is never freed - native nodes are not garbage
+    collected, so what is only wasted work in DOM Solid is a permanent
+    memory leak here. Read such props exactly once, at the place they are
+    mounted. To inspect children (a typeof probe, counting), resolve them
+    first with the children() helper (re-exported from @solidrt/core) and
+    probe the resolved memo - never `typeof props.children` on the raw prop.
 
 ## Run / verify
 
@@ -161,10 +169,38 @@ its tools over guessing at runtime state:
 - 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 `bunx srt check` for those.
+- load: bundle a given source file and push it to every client, replacing
+  the running app; later reloads rebuild that entry. Use it when the dev
+  server has no app loaded yet, or to switch apps without restarting srt.
+- watch: pause (enabled: false) or resume the automatic reload-on-save.
+  Pause BEFORE creating or editing source files so half-finished work is
+  not pushed to the user's screens mid-burst; a successful reload or load
+  resumes it, so pause again before the next burst. Never leave it paused
+  when you stop working - the user's own saves rely on it.
 
 The tools need a running app: if list_clients is empty, ask the user to start
 `bunx srt run src/index.tsx`.
 
+- Permission prompts: agents typically ask approval per MCP tool. All of
+  these tools only talk to the local dev server the user started with
+  `bunx srt run` - nothing leaves the machine - so approving the server as
+  a whole is a reasonable default. If repeated prompts get in the way, do
+  not work around them; tell the user they can pre-approve the server in
+  their agent's settings (most agents have a per-server trust or allowlist
+  setting - in Claude Code, add "mcp__solidrt" to `permissions.allow` in
+  ~/.claude/settings.json to cover every solidrt project). This is the
+  user's call to make, once, in their own tooling.
+- Multiple clients: several clients may be attached (desktop window,
+  phone, tablet) with different sizes, display scales, and safe areas.
+  reload pushes to all of them, but call_debug / get_snapshot / log
+  cursors are per client, and interactive state does NOT sync - a flow
+  driven on one client leaves the others sitting on the initial screen,
+  which reads as a crash to a human holding that device. So: when driving
+  state via call_debug, send the same call to every client (or say which
+  client you are using); and before calling a visual change done,
+  snapshot each distinct form factor at least once - a layout that fits
+  one window can clip or overflow another.
+
 ## Debugging a running app (lessons that cost real time)
 
 - console.log + get_logs is your primary probe into runtime state. For state

package/scaffold/package.json

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

package/server/control.ts

@@ -1,3 +1,4 @@
+import { file } from "flux:fs"
 import { state } from "./state"
 import { rebuildAndBroadcast } from "./rebuild"
 import { remapPositions } from "./remap"
@@ -240,8 +241,45 @@ export async function handleControl(req: Request, path: string, query: Map<strin
       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 })
+      state.watch = true
       return Response.json({ ok: true, clients: state.clients.size })
     }
+    case "/__control__/load": {
+      // Load (or switch) the app entry and push it: srt mcp's load tool.
+      // Moves the rebuild entry and the file-serving root like the repl's
+      // `load` command, then reuses the reload path, so a later /reload
+      // rebuilds the newly loaded file. The srt process is not told: a
+      // watcher started on the launch-time source keeps watching that file.
+      if (req.method !== "POST") return Response.json({ error: "Load requires POST" }, { status: 405 })
+      let entry = (await req.json().catch(() => null))?.entry
+      if (typeof entry !== "string" || !entry) {
+        return Response.json({ error: "Load requires { entry: <absolute source path> }" }, { status: 400 })
+      }
+      if (!(await file(entry).exists())) {
+        return Response.json({ error: `Entry not found: ${entry}` }, { status: 400 })
+      }
+      state.config.entry = entry
+      let cut = Math.max(entry.lastIndexOf("/"), entry.lastIndexOf("\\"))
+      if (cut > 0) state.sourceDir = entry.slice(0, cut)
+      let error = await rebuildAndBroadcast()
+      if (error) return Response.json({ error }, { status: 502 })
+      state.watch = true
+      return Response.json({ ok: true, entry, clients: state.clients.size })
+    }
+    case "/__control__/watch": {
+      // Pause/resume srt's auto-reload-on-save: the MCP watch tool. Latched
+      // here because the watcher lives in the srt process; it reads the flag
+      // via /__internal__/watch before acting on a change event. An agent
+      // pauses while creating or editing files so half-finished work is not
+      // pushed; a successful /reload or /load turns it back on.
+      if (req.method !== "POST") return Response.json({ error: "Watch requires POST" }, { status: 405 })
+      let enabled = (await req.json().catch(() => null))?.enabled
+      if (typeof enabled !== "boolean") {
+        return Response.json({ error: "Watch requires { enabled: <boolean> }" }, { status: 400 })
+      }
+      state.watch = enabled
+      return Response.json({ ok: true, enabled })
+    }
     default:
       return Response.json({ error: "Unknown control endpoint" }, { status: 404 })
   }

package/server/main.ts

@@ -69,6 +69,7 @@ async function handleInternal(req: FluxRequest, server: Server, path: string): P
   if (!loopback) return new Response("Forbidden", { status: 403 })
 
   if (path === "/__internal__/clients") return Response.json(clientList(true))
+  if (path === "/__internal__/watch" && req.method === "GET") return Response.json({ enabled: state.watch })
   if (req.method !== "POST") return new Response("Method not allowed", { status: 405 })
 
   switch (path) {
@@ -101,6 +102,12 @@ async function handleInternal(req: FluxRequest, server: Server, path: string): P
       sendTo(body.clients, JSON.stringify({ type: "stop" }))
       return new Response("", { status: 204 })
     }
+    case "/__internal__/watch": {
+      // The repl's `watch on|off`; agents use /__control__/watch instead.
+      let body = await req.json()
+      state.watch = !!body.enabled
+      return new Response("", { status: 204 })
+    }
     case "/__internal__/stats": {
       let body = await req.json()
       state.stats = !!body.stats

package/server/state.ts

@@ -59,6 +59,13 @@ export let state = {
   sourceDir: "",
   serverUrl: "",
   stats: false,
+  /**
+   * Whether srt's file watcher may auto-reload on source changes. Agents
+   * pause it (MCP watch tool -> /__control__/watch) while creating or
+   * editing files; a successful /reload or /load re-enables it. srt reads
+   * it via /__internal__/watch before acting on a change event.
+   */
+  watch: true,
   // Capture events from all connected clients share one clock (captureStartMs,
   // integer milliseconds) so they merge into one coherent timeline, tagged by
   // `device`. Streamed to disk as JSON Lines - see main.ts's "capture" handling.

package/src/artifacts.ts

@@ -7,12 +7,14 @@ let require = createRequire(import.meta.url)
 
 let TRIPLE_MAP: Record<string, string> = {
   "linux-x64": "linux-x64-gnu",
+  "linux-arm64": "linux-arm64-gnu",
   "darwin-arm64": "darwin-arm64",
   "win32-x64": "win32-x64-msvc",
 }
 
 let PKG_MAP: Record<string, string> = {
   "linux-x64": "@solidrt/linux-x64-gnu",
+  "linux-arm64": "@solidrt/linux-arm64-gnu",
   "darwin-arm64": "@solidrt/darwin-arm64",
   "win32-x64": "@solidrt/win32-x64-msvc",
 }

package/src/bundler.ts

@@ -103,8 +103,10 @@ export type BundleResult = {
 // 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> {
+  // Define values are parsed as expressions, so string values need embedded
+  // quotes - a bare word substitutes as an identifier and crashes at runtime.
   let define: Record<string, string> = {
-    "process.env.NODE_ENV": opts.dev ? "development" : "production",
+    "process.env.NODE_ENV": opts.dev ? '"development"' : '"production"',
   }
   if (opts.devBase) define.__SRT_DEV_BASE__ = opts.devBase
 

package/src/commands/mcp.ts

@@ -52,15 +52,30 @@ let SAVE_TO_ARG = z
   )
   .optional()
 
-let TOOLS: { name: string; description: string; inputSchema: Record<string, z.ZodTypeAny> }[] = [
+// readOnly marks tools that only inspect state; it is surfaced as the
+// MCP-standard readOnlyHint annotation so agent harnesses that honor it can
+// auto-approve the inspection majority. load, reload, and call_debug mutate
+// the running app and keep the default hints (destructive, not idempotent);
+// `annotations` overrides those defaults where a mutating tool is benign
+// (watch: a reversible, idempotent toggle). Every tool gets
+// openWorldHint: false - the bridge only ever talks to the local dev server.
+let TOOLS: {
+  name: string
+  description: string
+  inputSchema: Record<string, z.ZodTypeAny>
+  readOnly?: boolean
+  annotations?: { destructiveHint?: boolean; idempotentHint?: boolean }
+}[] = [
   {
     name: "list_clients",
+    readOnly: true,
     description:
       "List the app clients connected to the SolidRT dev server. Returns `generation` (identity of this server run: client ids and log cursors are only valid within one generation, so if it changed since your last call, re-fetch ids and cursors) and `clients`. 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",
+    readOnly: true,
     description:
       "Read console output and runtime errors from connected app clients. Returns entries (seq, at, client, level, text; consecutive identical entries are collapsed into one with a `repeats` count and the run's last seq), plus `latest` (the newest seq) and `generation` (identity of this server run; if it changed since your last call, your seq cursor and client ids are stale - start over from since 0). 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; pass `level`/`contains` to filter, e.g. level \"error\" to skip chatty output.",
     inputSchema: {
@@ -86,12 +101,14 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
   },
   {
     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), 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).",
+      "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).",
     inputSchema: { client: CLIENT_ARG },
   },
   {
     name: "get_render_tree",
+    readOnly: true,
     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. Whole trees get large: prefer `query` to find nodes by kind or text first, then `root` + `depth` to inspect the region around a match. A node whose children were cut off by `depth` carries `childCount`; descend into it with root=<its id>.",
     inputSchema: {
@@ -118,6 +135,7 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
   },
   {
     name: "get_snapshot",
+    readOnly: true,
     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. Works on an idle client (the capture requests its own frame); a timeout means the client's JS thread is busy or wedged, not that the app is idle.",
     inputSchema: {
@@ -128,12 +146,14 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
   },
   {
     name: "get_gpu_resources",
+    readOnly: true,
     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",
+    readOnly: true,
     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: {
@@ -148,6 +168,7 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
   },
   {
     name: "get_buffer",
+    readOnly: true,
     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: {
@@ -160,6 +181,7 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
   },
   {
     name: "list_debug",
+    readOnly: true,
     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 },
@@ -177,9 +199,26 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
   {
     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.",
+      "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. A successful reload re-enables the file watcher if you paused it with the watch tool. Follow with get_logs to see runtime output from the reloaded app.",
     inputSchema: {},
   },
+  {
+    name: "load",
+    description:
+      "Load an app entry: bundle the given .tsx/.jsx source file and push it to every connected client, replacing whatever is running. Use it when the dev server has no app loaded yet, or to switch to a different app; later reload calls rebuild this entry. Returns the number of clients loaded, or a build error if the source failed to compile. A successful load re-enables the file watcher if you paused it with the watch tool.",
+    inputSchema: {
+      entry: z.string().describe("App entry source file to load (relative paths resolve against the project root)"),
+    },
+  },
+  {
+    name: "watch",
+    annotations: { destructiveHint: false, idempotentHint: true },
+    description:
+      "Pause or resume the dev server's automatic reload-on-save. The srt file watcher pushes a rebuild whenever app source changes on disk; call watch with enabled: false BEFORE creating or editing source files so your half-finished work is not pushed to the user's screens mid-burst, then apply everything with one explicit reload (a successful reload or load re-enables the watcher, so pause again before the next burst of file changes). The human's own saves auto-reload only while the watcher is enabled, so do not leave it paused when you stop working.",
+    inputSchema: {
+      enabled: z.boolean().describe("false pauses auto-reload-on-save, true resumes it"),
+    },
+  },
 ]
 
 function clientParam(args: any): string {
@@ -212,6 +251,16 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
     }
     case "reload":
       return control("/reload", "POST")
+    case "load": {
+      if (typeof args?.entry !== "string" || !args.entry) return { ok: false, message: "load requires an entry path" }
+      // Resolved here in the bridge: this process runs at the project root,
+      // the dev server may not.
+      return control("/load", "POST", { entry: resolve(args.entry) })
+    }
+    case "watch": {
+      if (typeof args?.enabled !== "boolean") return { ok: false, message: "watch requires enabled: true or false" }
+      return control("/watch", "POST", { enabled: args.enabled })
+    }
     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) })
@@ -286,7 +335,11 @@ export async function runMcpCommand() {
   for (let tool of TOOLS) {
     server.registerTool(
       tool.name,
-      { description: tool.description, inputSchema: tool.inputSchema },
+      {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: { readOnlyHint: !!tool.readOnly, openWorldHint: false, ...tool.annotations },
+      },
       async (args: any) => toContent(tool.name, await callTool(tool.name, args ?? {}), args),
     )
   }

package/src/dev-server.ts

@@ -51,6 +51,26 @@ export async function sendStats(stats: boolean) {
   await post("/stats", { stats })
 }
 
+/** Latch the auto-reload flag on the server (repl `watch on|off`). */
+export async function sendWatch(enabled: boolean) {
+  await post("/watch", { enabled })
+}
+
+/**
+ * Whether the watcher may auto-reload: agents pause it via the MCP watch
+ * tool, latched on the server. Fails open so an unreachable server surfaces
+ * as a reload error, not a silently ignored change.
+ */
+export async function watchAllowed(): Promise<boolean> {
+  try {
+    let resp = await fetch(`${INTERNAL_BASE}/watch`)
+    if (!resp.ok) return true
+    return (await resp.json()).enabled !== false
+  } catch {
+    return true
+  }
+}
+
 export type ClientEntry = {
   id: number
   platform: string

package/src/repl.ts

@@ -2,7 +2,7 @@ import { createInterface } from "node:readline"
 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 { buildReload, getClients, sendReload, sendStop, sendStats, sendWatch, showBuildFailure } from "./dev-server"
 import { bundle } from "./bundler"
 import { startWatcher, stopWatcher } from "./watcher"
 
@@ -133,7 +133,7 @@ async function cmdLoad(file: string) {
   print(`[cli] Loaded ${file}`)
 }
 
-let COMMANDS = ["load ", "stop", "reload", "list", "stats", "quit", "exit", "help"]
+let COMMANDS = ["load ", "stop", "reload", "list", "stats", "watch ", "quit", "exit", "help"]
 let LOAD_EXTENSIONS = [".tsx", ".srt.js", ".srt.bin"]
 
 function completer(line: string): [string[], string] {
@@ -186,6 +186,11 @@ export function startRepl() {
       guard(cmdList())
     } else if (cmd === "stats" || cmd.startsWith("stats ")) {
       guard(cmdStats(cmd.slice(6).trim()))
+    } else if (cmd === "watch on" || cmd === "watch off") {
+      // Manual override for the agent-latched auto-reload pause (an agent
+      // that died mid-edit leaves it off; its reload normally restores it).
+      let enabled = cmd === "watch on"
+      guard(sendWatch(enabled).then(() => print(`[cli] Auto-reload on change ${enabled ? "on" : "off"}`)))
     } else if (cmd === "quit" || cmd === "exit") {
       shutdown()
     } else if (cmd.startsWith("!")) {
@@ -201,7 +206,7 @@ export function startRepl() {
         )
       }
     } else if (cmd === "help") {
-      print("Commands: load, stop, reload, list, stats, !<cmd>, quit, help")
+      print("Commands: load, stop, reload, list, stats, watch on|off, !<cmd>, quit, help")
     } else if (cmd) {
       print(`Unknown command: ${cmd}`)
     }

package/src/watcher.ts

@@ -1,7 +1,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 { buildReload, sendReload, showBuildFailure, watchAllowed } from "./dev-server"
 import { bundle } from "./bundler"
 
 let currentWatcher: ReturnType<typeof watch> | null = null
@@ -24,6 +24,11 @@ export function startWatcher() {
     if (!filename) return
     if (!/\.(tsx?|jsx?)$/.test(filename)) return
 
+    if (!(await watchAllowed())) {
+      print(`[cli] Change detected: ${filename} (auto-reload paused by agent; "watch on" resumes)`)
+      return
+    }
+
     print(`[cli] Change detected: ${filename}`)
     let result = await bundle(state.source)
     if (!result) {