@solidrt/cli 0.0.25 → 0.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "bin/",
     "src/",
+    "server/",
     "scaffold/",
     "AGENTS.md"
   ],
@@ -17,21 +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.15",
+    "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.25",
-    "@solidrt/linux-x64-gnu": "0.0.25",
-    "@solidrt/win32-x64-msvc": "0.0.25"
+    "@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.25",
-    "typescript": "^6"
+    "@solidrt/core": "0.0.27",
+    "typescript": "^7"
   },
   "devDependencies": {
+    "@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.25",
-    "@solidrt/components": "0.0.25"
+    "@solidrt/core": "0.0.27",
+    "@solidrt/components": "0.0.27"
   },
   "devDependencies": {
-    "@solidrt/cli": "0.0.25",
-    "@solidrt/flux-types": "0.0.25",
-    "typescript": "^6"
+    "@solidrt/cli": "0.0.27",
+    "@solidrt/flux-types": "0.0.27",
+    "typescript": "^7"
   }
 }

package/{src → server}/cache.ts

@@ -1,15 +1,16 @@
 // SQLite-backed HTTP response cache for the dev server's /__proxy__ endpoint.
 //
-// Project-local: stored at <cwd>/.srt-cache.db. Opt-in via the --cache
-// flag. Entries live forever; delete .srt-cache.db to drop them.
+// Project-local: stored at <dir>/.srt-cache.db. Entries live forever; delete
+// .srt-cache.db to drop them.
 //
 // Cached: GET (and HEAD) 2xx responses with no Authorization on the request
 // and no Cache-Control: no-store on either side. The cache key is
-// sha256(method + "\n" + url); headers are intentionally not part of the key.
+// method + "\n" + url, stored raw; headers are intentionally not part of the
+// key. (The Bun predecessor hashed the key with sha256, which was cosmetic:
+// old hashed entries simply miss and re-populate.)
 
-import { Database } from "bun:sqlite"
-import { resolve } from "path"
-import { createHash } from "node:crypto"
+import { Database } from "flux:sqlite"
+import { join } from "flux:path"
 
 const CACHE_FILE = ".srt-cache.db"
 
@@ -27,9 +28,9 @@ export type Entry = {
 let db: Database | null = null
 let enabled = false
 
-export function initCache(opts: { dir: string }) {
-  let d = new Database(resolve(opts.dir, CACHE_FILE), { create: true })
-  d.run(`CREATE TABLE IF NOT EXISTS entries (
+export async function initCache(opts: { dir: string }) {
+  let d = await Database.connect(join(opts.dir, CACHE_FILE), "rw+")
+  await d.exec(`CREATE TABLE IF NOT EXISTS entries (
     key         TEXT PRIMARY KEY,
     method      TEXT NOT NULL,
     url         TEXT NOT NULL,
@@ -46,28 +47,8 @@ export function isEnabled(): boolean {
   return enabled
 }
 
-// Strings returned by bun:sqlite carry an internal representation that
-// Headers.set() rejects, even when value-identical to an acceptable string
-// (Bun bug oven-sh/bun#28266, present through 1.3.14). Rebuilding each char
-// yields a clean string.
-function reflatten(s: string): string {
-  return Array.from(s, (c) => String.fromCharCode(c.charCodeAt(0))).join("")
-}
-
-function reflattenHeaders(obj: Record<string, string>): Record<string, string> {
-  let out: Record<string, string> = {}
-  for (let key in obj) {
-    out[reflatten(key)] = reflatten(obj[key]!)
-  }
-  return out
-}
-
 function keyFor(method: string, url: string): string {
-  let h = createHash("sha256")
-  h.update(method)
-  h.update("\n")
-  h.update(url)
-  return h.digest("hex")
+  return method + "\n" + url
 }
 
 function cacheableMethod(method: string): boolean {
@@ -98,32 +79,23 @@ export function isBypass(reqHeaders: Headers): boolean {
   return false
 }
 
-export function get(method: string, url: string): Entry | null {
+export async function get(method: string, url: string): Promise<Entry | null> {
   if (!db || !enabled) return null
-  let row = db
+  let row = await db
     .query("SELECT method, url, status, headers, body, cached_at FROM entries WHERE key = ?")
-    .get(keyFor(method, url)) as
-    | {
-        method: string
-        url: string
-        status: number
-        headers: string
-        body: Uint8Array
-        cached_at: number
-      }
-    | null
+    .get([keyFor(method, url)])
   if (!row) return null
   return {
-    method: row.method,
-    url: row.url,
-    status: row.status,
-    headers: reflattenHeaders(JSON.parse(row.headers)),
-    body: row.body,
-    cachedAt: row.cached_at,
+    method: row.method as string,
+    url: row.url as string,
+    status: row.status as number,
+    headers: JSON.parse(row.headers as string),
+    body: row.body as Uint8Array,
+    cachedAt: row.cached_at as number,
   }
 }
 
-export function put(
+export async function put(
   method: string,
   url: string,
   status: number,
@@ -133,10 +105,10 @@ export function put(
   if (!db || !enabled) return
   if (status < 200 || status >= 300) return
   if (hasNoStore(headers["cache-control"] ?? null)) return
-  db.run(
+  await db.run(
     `INSERT OR REPLACE INTO entries
      (key, method, url, status, headers, body, cached_at)
      VALUES (?, ?, ?, ?, ?, ?, ?)`,
     [keyFor(method, url), method, url, status, JSON.stringify(headers), body, Date.now()],
   )
-}
+}

package/server/control.ts

@@ -0,0 +1,187 @@
+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
+// app clients, served next to the file routes. The MCP bridge (srt mcp) is the
+// primary consumer. Two shapes: server-held data answered directly (clients,
+// logs) and queries forwarded to a client over its websocket and correlated
+// back by id (tree, stats).
+
+export type LogEntry = { seq: number; at: number; client: number; level: string; text: string }
+
+// Ring buffer of forwarded client logs. Capped so a chatty app cannot grow the
+// server without bound; readers page through it with the `since` cursor.
+const LOG_CAP = 2000
+const QUERY_TIMEOUT_MS = 5000
+const MAX_WAIT_MS = 30000
+
+let logs: LogEntry[] = []
+let logSeq = 0
+// Pending long-poll wakeups (see handleLogs). Flushed on every append; a
+// waiter that already timed out resolves again harmlessly.
+let logWaiters: Array<() => void> = []
+
+let nextQueryId = 1
+let pendingQueries = new Map<number, (msg: any) => void>()
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/// 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: remapPositions(text, state.currentMap) })
+  if (logs.length > LOG_CAP) logs.splice(0, logs.length - LOG_CAP)
+  let waiters = logWaiters
+  logWaiters = []
+  for (let wake of waiters) wake()
+}
+
+/// A `result` message arrived from a client: hand it to the awaiting query.
+export function resolveQuery(msg: { id?: number }) {
+  if (typeof msg.id !== "number") return
+  let resolve = pendingQueries.get(msg.id)
+  if (resolve) {
+    pendingQueries.delete(msg.id)
+    resolve(msg)
+  }
+}
+
+// The connected-client list. `withAddress` adds each socket's peer address for
+// the internal API (the repl `list` display); the public control shape stays
+// without it.
+export function clientList(withAddress = false) {
+  return [...state.clients.entries()].map(([ws, info]) => ({
+    id: info.id,
+    platform: info.platform,
+    version: info.version,
+    profile: info.profile,
+    capabilities: info.capabilities,
+    ...(withAddress ? { address: ws.remoteAddress ?? null } : {}),
+  }))
+}
+
+// Resolve the target client for a query: an explicit ?client=<id>, or the only
+// connected client when the parameter is omitted.
+function findClient(param: string | undefined): { ws: ServerWebSocket } | { error: Response } {
+  let entries = [...state.clients.entries()]
+  if (param === undefined) {
+    if (entries.length === 1) return { ws: entries[0]![0] }
+    if (entries.length === 0) return { error: Response.json({ error: "No connected clients" }, { status: 503 }) }
+    return { error: Response.json({ error: "Multiple clients connected; pass ?client=<id>" }, { status: 400 }) }
+  }
+  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 }) }
+  return { ws: entry[0] }
+}
+
+async function handleQuery(query: Map<string, string>, kind: string, extra?: Record<string, unknown>): Promise<Response> {
+  let target = findClient(query.get("client"))
+  if ("error" in target) return target.error
+  let id = nextQueryId++
+  let reply = new Promise<any>((resolve) => {
+    pendingQueries.set(id, resolve)
+  })
+  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 })
+  // 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.
+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) {
+    await new Promise<void>((resolve) => {
+      let timer = setTimeout(resolve, wait)
+      logWaiters.push(() => {
+        clearTimeout(timer)
+        resolve()
+      })
+    })
+    entries = logs.filter((e) => e.seq > since)
+  }
+  return Response.json({ entries, latest: logSeq })
+}
+
+export async function handleControl(req: Request, path: string, query: Map<string, string>): Promise<Response> {
+  switch (path) {
+    case "/__control__/clients":
+      return Response.json(clientList())
+    case "/__control__/logs":
+      return handleLogs(query)
+    case "/__control__/tree":
+      return handleQuery(query, "tree")
+    case "/__control__/stats":
+      return handleQuery(query, "stats")
+    case "/__control__/snapshot": {
+      let nodeId = parseInt(query.get("node") ?? "", 10)
+      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 })
+  }
+}