@solidrt/cli 0.0.27 → 0.0.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.27",
+  "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.27",
-    "@solidrt/linux-x64-gnu": "0.0.27",
-    "@solidrt/win32-x64-msvc": "0.0.27"
+    "@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.27",
+    "@solidrt/core": "0.0.29",
     "typescript": "^7"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.27",
+    "@solidrt/flux-types": "0.0.29",
     "@types/bun": "latest"
   }
 }

package/scaffold/AGENTS.md

@@ -4,6 +4,23 @@ This project uses SolidRT: a custom SolidJS renderer that paints through a Rust
 runtime. No DOM, no HTML, no CSS cascade. If you are an AI assistant, read this
 before writing or editing code here.
 
+## Levels: core, and frameworks on top
+
+- @solidrt/core is the low-level foundation: host intrinsics (`<window>`,
+  `<view>`, `<text>`, the detached `d-*` drawing primitives) with flat props
+  that feed the layout and paint engine directly. An app can be written
+  entirely at this level.
+- Higher-level component frameworks build on core. @solidrt/components is
+  the first-party one: themed widgets (Window, View, Text, Button,
+  ScrollView, SafeArea, ...) with the `layout={{...}}`/`style={{...}}` prop
+  split. It is not privileged - a framework is just functions returning core
+  JSX, and an app can use a third-party one or grow its own.
+
+Match the level the code you are editing already uses. package.json shows
+the choice this app made: if no component framework is among the
+dependencies, the app is core-only - do not add one for a change core
+covers.
+
 Authoritative references ship inside the installed packages - read them:
 - node_modules/solid-js/CHEATSHEET.md          - SolidJS 2.0 reactivity/control-flow model
 - node_modules/@solidrt/components/AGENTS.md   - the component vocabulary; build UI from these
@@ -24,10 +41,10 @@ Authoritative references ship inside the installed packages - read them:
 
 1. This is SolidJS 2.0 (see CHEATSHEET.md for the reactivity/control-flow
    model), rendering through a custom Rust runtime instead of the DOM. Build
-   UI from @solidrt/components (Window, View, Text, Image, TextInput,
-   ScrollView, Pressable, Button, SafeArea, theme/setTheme) - it is the
-   higher-level, batteries-included vocabulary and is where most app code
-   should live.
+   UI at the level the app uses (see "Levels" above): core intrinsics
+   directly, or a component framework such as @solidrt/components (Window,
+   View, Text, Image, TextInput, ScrollView, Pressable, Button, SafeArea,
+   theme/setTheme) - the first-party, batteries-included one.
 2. Most components split their props into two objects: `layout={{...}}` for
    anything that feeds the layout engine (flex/grid, sizing, padding/margin,
    position; font fields for Text) and `style={{...}}` for paint-only
@@ -52,7 +69,8 @@ Authoritative references ship inside the installed packages - read them:
    (runtime-paced, auto-cleans), re-exported from @solidrt/core.
    requestAnimationFrame(t => {}) exists as a web-standard one-shot but is
    not the preferred animation driver.
-8. Reach for @solidrt/core directly only for what components doesn't wrap:
+8. In a components-based app, reach for @solidrt/core directly only for
+   what components doesn't wrap:
    raw host intrinsics and the `d-` (detached, non-layout) primitives like
    `d-rect`/`d-path`/`d-oval` for vector art or perf-sensitive positioned
    drawing, device/GPU subpath imports (@solidrt/core/camera, /microphone,
@@ -76,11 +94,37 @@ Authoritative references ship inside the installed packages - read them:
     `compute` is the tracked read phase; `apply(value, prev)` runs untracked
     and is where side effects/DOM-equivalent writes belong. The old
     single-arg `createEffect(fn)` form is gone - using it is an error.
+13. A scroll container (ScrollView, or anything on createScroll) needs an
+    explicit main-axis size - a height, or flex inside a sized parent. With
+    neither it resolves to 0 and its content silently vanishes; maxHeight
+    alone does not size it (the auto size it would clamp is already 0). The
+    runtime warns when this happens.
+14. Text `lineHeight` is a MULTIPLIER of fontSize (the theme uses 1.3-1.6),
+    not pixels. A CSS-reflex value like 22 makes each line box 22x the font
+    size: the text becomes blank space and the parent balloons.
+15. Signal writes flush on a microtask: a handler that sets a signal and
+    immediately reads it back gets the OLD value. Read the new value in an
+    effect, or call `flush()` (from @solidjs/signals) to force it through.
+16. Portals cannot mount during the app's initial render: a Modal (or any
+    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
 
 - bunx srt run src/index.tsx     - dev server + window (needs a display)
-- bunx srt bundle src/index.tsx  - exit 0 means it compiles
+- bunx srt check src/index.tsx   - exit 0 means it compiles and the app's
+  types hold (dependency-internal type errors are hidden). Builds in memory:
+  writes nothing and never triggers a dev-server reload, so use this while
+  iterating - `srt bundle` writes output files and reloads connected clients
 - bunx srt render src/index.tsx --size 480x640 --duration 1 --fps 2 - headless
   render to PNG frames (proves it renders; see the cli AGENTS.md for where the
   frames land)
@@ -93,12 +137,25 @@ its tools over guessing at runtime state:
 
 - list_clients: connected app clients, their platform and runtime capabilities
 - get_logs: console output and runtime errors (seq cursor; `wait_ms` long-poll
-  to catch output right after a reload)
+  to catch output right after a reload; `level`/`contains` filters; repeated
+  lines collapse into one entry with a `repeats` count)
 - 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
+  window-relative boxes. Whole trees get large: `query` finds nodes by
+  kind/text, then `root` + `depth` inspect just that region
+- client ids and log cursors die with the dev server: list_clients and
+  get_logs responses carry `generation`, and a changed generation means
+  re-fetch ids and restart cursors
+- get_stats: fps, CPU/memory, frame phase timings, setProperty rate, plus
+  layout-activity counters for the last rebuild (nodes, measureCalls,
+  paraShapes, dirtiedNodes, cacheGets/cacheHits) - when layoutMs looks
+  wrong, these say whether the cost is text shaping, invalidation breadth,
+  or a defeated layout cache (healthy incremental rebuilds show a near-100%
+  cacheHits rate)
 - get_snapshot: PNG capture of any render-tree node's pixels (get node ids
-  from get_render_tree; the window node captures everything)
+  from get_render_tree; the window node captures everything). Pass `save_to`
+  on get_snapshot or get_texture to also write the PNG to a file - the image
+  in the tool result cannot be saved afterwards, so decide before capturing
+  (e.g. keep a before/after pair to diff)
 - 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)
@@ -111,11 +168,39 @@ its tools over guessing at runtime state:
   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.
+  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
@@ -125,10 +210,10 @@ The tools need a running app: if list_clients is empty, ask the user to start
   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.
+  change, so measure performance while uniforms are actually changing.
+  get_snapshot works on an idle client (it requests its own frame); a
+  timeout means the JS thread is busy or wedged. get_texture on a pipeline's
+  render target 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.
@@ -160,3 +245,23 @@ The tools need a running app: if list_clients is empty, ask the user to start
   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.
+- Layout is incremental: a change re-solves only the dirty path, and clean
+  subtrees answer from a per-node cache, so long lists no longer cap layout
+  (a thousand-node tree relays out in well under a millisecond). If layoutMs
+  still grows with tree size, read the get_stats counters - a low
+  cacheHits/cacheGets ratio means the layout cache is being defeated, high
+  paraShapes means text is actually reshaping. Very long lists still pay
+  for the initial mount and for memory, so windowing stays sensible at the
+  thousands-of-rows scale.
+- Remote images: createImage (and Image) dedupes repeated URLs, caches the
+  bytes on disk, and the runtime rate-limits concurrent asset fetches per
+  host - do not build your own promise cache around it. Images are fetched
+  with no freshness check (an already-cached URL is never re-checked), so
+  use versioned URLs for content that changes. Use Image's `fallback` prop
+  (an image source) for the broken-image case instead of catching errors
+  yourself.
+- fetch() never caches by default and ignores server cache headers. Caching
+  is explicit and per call: `fetch(url, { cache: "force-cache" })` for
+  assets (serve from disk or fetch-and-store, no freshness),
+  `{ cache: "reload" }` to refresh an entry. Image/createImage already do
+  this for you.

package/scaffold/package.json

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

package/scaffold/templates/components/index.tsx

@@ -0,0 +1,15 @@
+// Components template: built with the @solidrt/components framework.
+import { render } from "@solidrt/core"
+import { Window, SafeArea, Text } from "@solidrt/components"
+
+function App() {
+  return (
+    <Window>
+      <SafeArea>
+        <Text>Hello, World!</Text>
+      </SafeArea>
+    </Window>
+  )
+}
+
+render(() => <App />)

package/scaffold/templates/components/template.json

@@ -0,0 +1,4 @@
+{
+  "level": "components",
+  "description": "components, blank start"
+}

package/scaffold/templates/default/index.tsx

@@ -1,5 +1,5 @@
+// Core-only template: built from @solidrt/core primitives.
 import { render, For, onFrame, createSignal, createLinearGradient } from "@solidrt/core"
-import { View, Window } from "@solidrt/components"
 
 const FADE = 360 
 
@@ -13,7 +13,7 @@ let SEGMENTS = [
   { base: 540, light: "#7ea9ea", dark: "#5681c1", d: "M100.000 50.000 L75.000 75.000 L75.000 65.830 C73.810 65.830 72.711 65.195 72.116 64.165 C71.521 63.135 71.521 61.865 72.116 60.835 C72.711 59.805 73.810 59.170 75.000 59.170 L75.000 50.000 L75.000 40.830 C73.810 40.830 72.711 40.195 72.116 39.165 C71.521 38.135 71.521 36.865 72.116 35.835 C72.711 34.805 73.810 34.170 75.000 34.170 L75.000 25.000 L100.000 50.000 Z" },
 ]
 
-let LAST = SEGMENTS[SEGMENTS.length - 1].base
+let LAST = SEGMENTS[SEGMENTS.length - 1]!.base
 let IN_DONE = LAST + FADE
 let CYCLE = IN_DONE + LAST + FADE
 
@@ -32,7 +32,7 @@ function Icon() {
   let start = -1
   onFrame((t) => (start < 0 && (start = t), setClock((t - start) % CYCLE)))
   return (
-    <View layout={{ width: 100, height: 100 }} style={{ scale: 3 }}>
+    <view width={100} height={100} scale={3}>
       <For each={SEGMENTS}>
         {(seg) => {
           let a = () => {
@@ -43,7 +43,7 @@ function Icon() {
           return <d-path d={seg.d} color={fill(seg, a())} />
         }}
       </For>
-    </View>
+    </view>
   )
 }
 
@@ -54,12 +54,10 @@ function App() {
   ])
 
   return (
-    <Window
-      layout={{ alignItems: "center", justifyContent: "center" }}
-      style={{ backgroundColor }}
-    >
+    <window alignItems="center" justifyContent="center">
+      <d-rect color={backgroundColor} />
       <Icon />
-    </Window>
+    </window>
   )
 }
 

package/scaffold/templates/default/template.json

@@ -0,0 +1,4 @@
+{
+  "level": "core",
+  "description": "core, animated logo"
+}

package/scaffold/templates/gallery/template.json

@@ -0,0 +1,4 @@
+{
+  "level": "components",
+  "description": "components, widget tour"
+}

package/scaffold/templates/minimal/index.tsx

@@ -1,9 +1,12 @@
-import { render } from "@solidrt/core"
+// Core-only template: built from @solidrt/core primitives.
+import { render, safeArea } from "@solidrt/core"
 
 function App() {
   return (
     <window>
-      <text>Hello, World!</text>
+      <view flex={1} paddingTop={safeArea().top} paddingBottom={safeArea().bottom}>
+        <text>Hello, World!</text>
+      </view>
     </window>
   )
 }

package/scaffold/templates/minimal/template.json

@@ -0,0 +1,4 @@
+{
+  "level": "core",
+  "description": "core, blank start"
+}

package/scaffold/tsconfig.json

@@ -6,6 +6,7 @@
     "jsxImportSource": "@solidrt/core",
     "moduleResolution": "bundler",
     "strict": true,
+    "skipLibCheck": true,
     "types": ["@solidrt/flux-types"]
   },
   "include": ["src"]

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"
@@ -75,7 +76,19 @@ function findClient(param: string | undefined): { ws: ServerWebSocket } | { erro
   }
   let id = parseInt(param, 10)
   let entry = entries.find(([, info]) => info.id === id)
-  if (!entry) return { error: Response.json({ error: `No client with id ${param}` }, { status: 404 }) }
+  if (!entry) {
+    let ids = entries.map(([, info]) => info.id)
+    return {
+      error: Response.json(
+        {
+          error:
+            `Client ${param} is gone (connected ids: ${ids.length ? ids.join(", ") : "none"}). ` +
+            "Ids reset when the dev server restarts; call list_clients for current ones.",
+        },
+        { status: 404 },
+      ),
+    }
+  }
   return { ws: entry[0] }
 }
 
@@ -89,42 +102,91 @@ async function handleQuery(query: Map<string, string>, kind: string, extra?: Rec
   target.ws.send(JSON.stringify({ type: "query", kind, id, ...extra }))
   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)
+    return Response.json(
+      { error: "Query timed out: the client is connected but did not answer (JS thread busy or app wedged?)" },
+      { status: 504 },
+    )
   // 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)
 }
 
-// GET /__control__/logs?since=N&wait=MS: entries with seq > since, plus the
-// latest seq as the next cursor. With `wait`, holds the response until a new
-// entry arrives or the timeout passes (long-poll), so a caller can follow the
-// stream without tight polling.
+// Merge runs of consecutive identical entries (same client, level, text) into
+// one entry carrying `repeats` and the run's last seq/at, so 176 copies of one
+// error read as a single line and a `since` cursor still skips the whole run.
+function collapseRepeats(entries: LogEntry[]): (LogEntry & { repeats?: number })[] {
+  let out: (LogEntry & { repeats?: number })[] = []
+  for (let e of entries) {
+    let last = out[out.length - 1]
+    if (last && last.client === e.client && last.level === e.level && last.text === e.text) {
+      last.repeats = (last.repeats ?? 1) + 1
+      last.seq = e.seq
+      last.at = e.at
+    } else {
+      out.push({ ...e })
+    }
+  }
+  return out
+}
+
+// GET /__control__/logs?since=N&wait=MS&level=L1,L2&contains=TEXT: entries with
+// seq > since, plus the latest seq as the next cursor and the server
+// generation. `level` keeps only the listed levels; `contains` keeps entries
+// whose text has the substring (case-insensitive). Consecutive identical
+// entries come back collapsed with a `repeats` count. With `wait`, holds the
+// response until an entry passes the filters or the timeout expires
+// (long-poll), so a caller can follow the stream without tight polling.
 async function handleLogs(query: Map<string, string>): Promise<Response> {
   let since = parseInt(query.get("since") ?? "0", 10) || 0
   let wait = Math.min(parseInt(query.get("wait") ?? "0", 10) || 0, MAX_WAIT_MS)
-  let entries = logs.filter((e) => e.seq > since)
-  if (entries.length === 0 && wait > 0) {
+  let levels = query
+    .get("level")
+    ?.split(",")
+    .map((l) => l.trim())
+    .filter(Boolean)
+  let contains = query.get("contains")?.toLowerCase()
+  let select = () =>
+    logs.filter(
+      (e) =>
+        e.seq > since &&
+        (!levels || levels.length === 0 || levels.includes(e.level)) &&
+        (!contains || e.text.toLowerCase().includes(contains)),
+    )
+  let entries = select()
+  // Filtered long-poll: an append may not pass the filters, so keep waiting
+  // until one does or the deadline runs out.
+  let deadline = Date.now() + wait
+  while (entries.length === 0 && Date.now() < deadline) {
     await new Promise<void>((resolve) => {
-      let timer = setTimeout(resolve, wait)
+      let timer = setTimeout(resolve, deadline - Date.now())
       logWaiters.push(() => {
         clearTimeout(timer)
         resolve()
       })
     })
-    entries = logs.filter((e) => e.seq > since)
+    entries = select()
   }
-  return Response.json({ entries, latest: logSeq })
+  return Response.json({ entries: collapseRepeats(entries), latest: logSeq, generation: state.generation })
 }
 
 export async function handleControl(req: Request, path: string, query: Map<string, string>): Promise<Response> {
   switch (path) {
     case "/__control__/clients":
-      return Response.json(clientList())
+      return Response.json({ generation: state.generation, clients: clientList() })
     case "/__control__/logs":
       return handleLogs(query)
-    case "/__control__/tree":
-      return handleQuery(query, "tree")
+    case "/__control__/tree": {
+      let extra: Record<string, unknown> = {}
+      let root = parseInt(query.get("root") ?? "", 10)
+      if (Number.isFinite(root)) extra.root = root
+      let depth = parseInt(query.get("depth") ?? "", 10)
+      if (Number.isFinite(depth)) extra.depth = depth
+      let q = query.get("query")
+      if (q) extra.query = q
+      return handleQuery(query, "tree", extra)
+    }
     case "/__control__/stats":
       return handleQuery(query, "stats")
     case "/__control__/snapshot": {
@@ -179,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

@@ -37,6 +37,13 @@ export let state = {
   config: undefined as unknown as Config,
   clients: new Map<ServerWebSocket, ClientInfo>(),
   nextClientId: 0,
+  /**
+   * Identity of this server run, included in control responses that carry
+   * cross-call state (client ids, log seq cursors). Both reset on restart, so
+   * a consumer that sees the generation change knows its ids and cursors are
+   * from a dead server and must be re-fetched.
+   */
+  generation: Date.now(),
   /**
    * The latched reload message (JSON text), replayed to late-joining clients.
    * Set by /__internal__/reload posts with `latch`, cleared by a broadcast stop.
@@ -52,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/args.ts

@@ -46,6 +46,9 @@ export function validateArgs() {
         usage("srt bundle [options] <entry.[tsx|jsx|ts|js|srt.js|srt.bin]>")
       }
       break
+    case "check":
+      if (!source || !isSource) usage("srt check <entry.[tsx|jsx|ts|js]>")
+      break
     case "render":
       if (!source || !isTsx) usage("srt render <entry.[tsx|jsx]>")
       break
@@ -74,6 +77,7 @@ Commands:
   server [file]          Start dev server only
   client                 Start solidrt-go client only
   bundle <file>          Transpile TS/JS/TSX/JSX to JS or bytecode
+  check <file>           Verify the app builds and typechecks, without writing anything
   render <file.tsx|jsx>  Replay a script (optional) and render frames for video generation
   pack <file>            Bundle + compile to a standalone executable (experimental)
   mcp                    MCP server (stdio) exposing the running dev server to coding agents

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