@solidrt/cli 0.0.26 → 0.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "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.28",
+    "@solidrt/linux-x64-gnu": "0.0.28",
+    "@solidrt/win32-x64-msvc": "0.0.28"
   },
   "peerDependencies": {
-    "@solidrt/core": "0.0.26",
+    "@solidrt/core": "0.0.28",
     "typescript": "^7"
   },
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.26",
+    "@solidrt/flux-types": "0.0.28",
     "@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,29 @@ 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.
 
 ## 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,10 +129,103 @@ 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). 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)
+- 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 `bunx srt check` for those.
 
 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.
+  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.
+- 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.
+- 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.26",
-    "@solidrt/components": "0.0.26"
+    "@solidrt/core": "0.0.28",
+    "@solidrt/components": "0.0.28"
   },
   "devDependencies": {
-    "@solidrt/cli": "0.0.26",
-    "@solidrt/flux-types": "0.0.26",
+    "@solidrt/cli": "0.0.28",
+    "@solidrt/flux-types": "0.0.28",
     "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,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 } : {}),
   }))
@@ -71,7 +75,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] }
 }
 
@@ -85,40 +101,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.error) return Response.json({ error: msg.error }, { status: 502 })
+  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": {
@@ -126,6 +193,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) : [],
           })