@solidrt/cli 0.0.46 → 0.0.47

package/package.json

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

package/scaffold/AGENTS.md

@@ -37,6 +37,61 @@ Authoritative references ship inside the installed packages - read them:
 @./node_modules/@solidrt/core/AGENTS.md
 @./node_modules/@solidrt/cli/AGENTS.md
 
+## What you paint with (there is no CSS layer)
+
+Layout and props are half the model. There is no stylesheet: no filters, no
+box-shadow, no keyframes, no canvas. The visual range a web app gets from CSS
+comes from the tiers below instead, and reaching past tier 1 is ordinary
+app-building here, not optimization - a screen built only from view
+backgrounds and text is using a fraction of the runtime. Pick the tier the
+CONTENT calls for, not the one that looks safest.
+
+1. Laid-out elements - `<view>`/`<text>`, with `<rect>` (or a filling
+   `<d-rect>` child) for background, border, radius. The structure of a
+   screen, not its finish.
+2. Vector art, detached from layout - `d-path`/`d-rect`/`d-oval`/`d-line`,
+   whose `color` takes a gradient (createLinearGradient /
+   createRadialGradient) and which honour `blendMode`, plus `parseSvg` to
+   draw a whole SVG document as one subtree. Free-form shapes, decoration,
+   diagrams, charts, anything positioned rather than flowed. Examples:
+   parse-svg, detached-positioning, text-paint-styling.
+3. GPU textures - `createShaderTexture` puts a fragment shader in a
+   `<texture>` (moving gradients, noise, glow, dissolves, a background that
+   is alive), `createPipelineTexture` draws geometry you generate yourself
+   (particles, point clouds, splats), and the `shader` prop post-processes
+   content that already exists: on a `<view>` it grades, warps or dissolves
+   that subtree, on `<window>` the whole frame. Stack `<texture>` elements
+   with `blendMode` to combine passes. Examples: gpu-shader, gpu-particles,
+   gpu-pipeline, gpu-instancing, gpu-texture-blend, view-shader,
+   window-shader.
+4. 3D scenes - add `@solidrt/3d` (not a scaffold dependency): meshes,
+   materials and a camera declared as Solid components, rendered into a
+   texture that sits in the UI tree like any other element.
+
+Tier 3 is cheaper than it looks. A shader costs one property write per frame
+no matter how complex the effect, which is why the performance notes below
+reach for it first rather than as a last resort.
+
+Web reflexes and what replaces them:
+- gradient background -> a gradient `color` on a `d-rect` (gradients are
+  paint values, usable anywhere a color is)
+- `filter: blur/grayscale/hue-rotate`, and any "make this look processed" ->
+  a `shader` on the view (requires repaintBoundary="snapshot"), or on
+  `<window>` for the whole frame
+- `box-shadow` / `text-shadow` / glow -> no shadow prop exists: draw an
+  offset `d-*` shape under the content, or a view shader with `outset` (the
+  transparent margin an effect bleeds into)
+- `backdrop-filter` -> no equivalent. A view shader sees only its own
+  subtree's pixels, never what is behind it. Frost the whole frame with a
+  window shader, or fake the layer with your own content
+- `@keyframes` / transitions -> `onFrame` writing a signal for discrete
+  motion; a `uTime` uniform when the animation is continuous and visual
+- `<canvas>` 2D -> `d-*` primitives (rebuild one `d-path` string per frame
+  rather than animating N elements)
+- `<canvas>` WebGL, three.js -> `createPipelineTexture`, or `@solidrt/3d`
+- video background, animated hero, particle field -> a shader texture; this
+  is the case the runtime is built for
+
 ## The things assistants get wrong (this is not React/DOM)
 
 1. This is SolidJS 2.0 (see CHEATSHEET.md for the reactivity/control-flow
@@ -209,6 +264,22 @@ work stops being free" below is where it does not. Rules, in order of leverage:
 5. "snapshot" boundaries pay first-frame texture allocation + raster:
    creating many at once (dealing a board of 64 sprites) is a visible
    one-frame hiccup - pool or pre-warm if that moment matters.
+6. Shading pixels the app already drew is a different mechanism from rule 1's
+   generated textures, and both forms are a `shader` prop taking a linked
+   program from compileShader/linkProgram (@solidrt/core/gpu), not a
+   createShaderTexture source. On `<window>`, `shader={{ program, params }}`
+   runs the finished frame through the program as the last step before it
+   reaches the screen: the frame binds as `uniform sampler2D uSource`,
+   `iResolution` fills by name, and `previous: true` retains the last frame as
+   `uPrevious` for motion echo or frame differencing. On a `<view>` the same
+   prop shades that subtree in place and REQUIRES repaintBoundary="snapshot"
+   (without it the shader is ignored with a warning); the pass sees only the
+   subtree's own pixels - grading, warping or dissolving the panel works,
+   anything needing what is behind it does not - and is split from content
+   invalidation, so a params-only change re-runs the pass against the cached
+   snapshot instead of re-rasterizing. A window shader's output is invisible
+   to get_snapshot and every other MCP tool; `srt render` is the only way to
+   see it (Run / verify below).
 
 ### Where GPU work stops being free
 
@@ -290,7 +361,10 @@ up to the frame period, because work outside the frame call is not in them.
   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)
+  frames land). It is also the ONLY way to see the output of a window shader
+  (the `shader` prop on `<window>`): that pass runs on the finished frame on
+  its way to the screen, past the point every other capture reads, so `render`
+  frames are the only programmatic view of what it produces
 
 ## MCP: inspect the running app
 
@@ -298,12 +372,22 @@ The project ships an MCP server (.mcp.json, `srt mcp`) that talks to the dev
 server `bunx srt run` starts. When it is loaded in your environment, prefer
 its tools over guessing at runtime state:
 
-- list_clients: connected app clients, their platform and runtime capabilities
+- list_clients: connected app clients, their platform and runtime
+  capabilities, plus the server's `entry` (the app source it serves) and
+  `projectDir` - check entry matches the app you think you are driving; the
+  dev port is fixed, so another project's server answers on the same port.
+  Each client also lists `queries`, the dev-tool query kinds its runtime
+  answers - check it before planning verification against a mixed-version
+  fleet (no "input" = the client predates send_input)
 - get_logs: console output and runtime errors (seq cursor; `wait_ms` long-poll
   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. Whole trees get large: `query` finds nodes by
+  window-relative boxes. Pass `props: true` for each node's current
+  property values (JSX names, off-default only - "is rotate/color/overflow/d
+  applied right now" is one call, not a probe entry) and, on transformed nodes, the
+  painted `quad` (four corners after transforms; the box is just its
+  axis-aligned bounds). 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
@@ -313,12 +397,46 @@ its tools over guessing at runtime state:
   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)
+  cacheHits rate). reusedPerSec/skippedPerSec are the demand gate's visible
+  signal: frames presented from the cached display list without a rebuild
+  (texture content changed, no property writes - expect reusedPerSec near
+  fps on texture-driven apps) and frames skipped entirely (nothing
+  requested one)
 - 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)
+  from get_render_tree; the window node captures everything). A subtree
+  capture renders with NO ancestor paint: pixels the subtree does not draw
+  come back transparent, not the background behind the node. Captures
+  re-rasterize the tree offscreen, so they are also PRE window shader: an app
+  with a `shader` on its `<window>` snapshots as its unshaded content, window
+  node included, and no MCP tool reads the shaded result (its layer is
+  runtime-owned, so get_texture has no id for it; get_gpu_resources reports
+  only that the pass exists). Use `srt render` for that one. Crop with
+  x/y/width/height (captured-image pixels) and magnify with `scale` (1-8,
+  nearest-neighbour) - a tight crop at 4-8x is how small geometry gets
+  verified. 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)
+- set_time_scale / step_frames: the runtime clock. `set_time_scale 0`
+  freezes app time (onFrame, requestAnimationFrame, timers, and
+  performance.now all stop; Date.now stays wall time), so a snapshot can
+  catch an exact frame of any animation instead of racing it; `step_frames
+  n` then advances exactly n frames (one refresh period each). Pause,
+  snapshot, step, snapshot again to see precisely what changed. ALWAYS set
+  the scale back to 1 when done - a paused client looks wedged to the human
+  watching - though reload/load also reset it
+- send_input: synthetic pointer/key/wheel/text events through the REAL
+  input pipeline (hit testing, focus, bubbling) - the way to verify an
+  interaction actually works, where call_debug would bypass it. A click is
+  one call ({type: "pointer", action: "tap", x, y} - logical points, the
+  same space get_render_tree reports); a key hold is {type: "key", action:
+  "tap", key: "w", holdMs: 500}; text needs the field focused first (tap
+  it), then {type: "text", text: "go"}; drags are down + moves (delayMs
+  ~16 apiece) + up. Sequences run in order with per-event delayMs and the
+  call returns after the last event is delivered, so a following snapshot
+  sees the result. A synthetic mouse keeps hovering at its last position
+  (like a real cursor at rest); use pointerType: "touch" for gestures that
+  should end hover-free. Composes with the clock: pause, send_input,
+  step_frames, snapshot = a deterministic interaction test
 - get_gpu_resources: inventory of GPU state - textures (size, render target
   or not), vertex buffers (byteLength), pipelines (draw count, attribute
   layout, bound textures, current uniform values - the most recent writes,
@@ -326,7 +444,7 @@ its tools over guessing at runtime state:
 - get_texture: any GPU texture read back as a PNG by id - atlases, data
   textures, and shader/pipeline render targets alike (a render target reads
   as its current output, pending writes included, with no frame or snapshot
-  needed); crop with x/y/width/height
+  needed); crop with x/y/width/height, magnify with `scale`
 - 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
@@ -361,8 +479,8 @@ flag: `"args": [..., "mcp", "--port", "N"]`.
   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
+  reload pushes to all of them, but call_debug / send_input / 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
@@ -377,11 +495,18 @@ flag: `"args": [..., "mcp", "--port", "N"]`.
   logs it and read it back via get_logs.
 - Better than debug keys when driving the app over MCP: register debug
   COMMANDS - `registerDebug(name, fn)` from `srt:dev`, invoked via the
-  list_debug/call_debug tools. `seek`/`pause`/`play` commands turn verifying
-  an animation into "jump to t, snapshot, look"; a `zoom` command that
-  shrinks a viewBox to a region gives magnified captures without touching
-  source. Registrations reset on hot reload, so register at module init;
-  sync return values only.
+  list_debug/call_debug tools. Use them to SET UP state (jump to a level,
+  force a mode, seed a scenario); then the runtime-level tools take over -
+  set_time_scale 0 freezes the result for as many snapshots as you need,
+  and step_frames walks it forward deterministically. Set state, pause,
+  snapshot. Registrations reset on hot reload, so register at module init;
+  sync return values only - and note a signal you just wrote flushes on a
+  microtask, so returning a signal read straight after setting it returns
+  the OLD value.
+- call_debug sets state directly, skipping focus, key routing, and
+  TextInput - fine for SETUP, but "the interaction works" is only shown by
+  the real pipeline: verify clicks, typing, and drags with send_input,
+  which enters events where SDL input does.
 - Key events start at the focused node and bubble to the window root; with
   nothing focused they go to the window root alone. So a debug key bound via
   `<window onKeyDown>` always fires (unless a focused component consumes the
@@ -402,10 +527,12 @@ flag: `"args": [..., "mcp", "--port", "N"]`.
 - Snapshots are downscaled by the time you see them, so a full-window capture
   cannot show you a defect a few pixels across. Whenever you hand-author
   geometry - a `d-path` from raw path math, a `radius` where two shapes meet,
-  a stroke join - inspect it MAGNIFIED once, when you write it: a throwaway
-  entry file drawing the construction at 4-8x (pushed with `load`), or a
-  `zoom` debug command on the real app. Verifying that a shape is in the
-  right place is not the same check as verifying it is drawn right.
+  a stroke join - inspect it MAGNIFIED once, when you write it: get_snapshot
+  with a tight crop at scale 4-8 shows the actual rendered pixels enlarged,
+  in one call, on the real app. Verifying that a shape is in the right place
+  is not the same check as verifying it is drawn right - and get_render_tree
+  props answers the third question, whether the value you set is the value
+  the renderer holds.
 - 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

package/scaffold/package.json

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

package/server/control.ts

@@ -61,6 +61,7 @@ export function clientList(withAddress = false) {
     version: info.version,
     profile: info.profile,
     capabilities: info.capabilities,
+    queries: info.queries,
     ...(withAddress ? { address: ws.remoteAddr ?? null } : {}),
   }))
 }
@@ -72,7 +73,7 @@ function findClient(param: string | undefined): { ws: ServerWebSocket } | { erro
   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 }) }
+    return { error: Response.json({ error: "Multiple clients connected; pass a client id (list_clients has the ids)" }, { status: 400 }) }
   }
   let id = parseInt(param, 10)
   let entry = entries.find(([, info]) => info.id === id)
@@ -92,7 +93,35 @@ function findClient(param: string | undefined): { ws: ServerWebSocket } | { erro
   return { ws: entry[0] }
 }
 
-async function handleQuery(query: Map<string, string>, kind: string, extra?: Record<string, unknown>): Promise<Response> {
+// Optional crop rect shared by /snapshot and /texture: all four of
+// x/y/width/height in captured/texture pixels, or none. Returns undefined
+// when absent, a 400 Response when malformed.
+function parseRect(query: Map<string, string>): { x: number; y: number; width: number; height: number } | Response | undefined {
+  let params = ["x", "y", "width", "height"].map((k) => query.get(k))
+  if (params.every((v) => v === undefined)) return undefined
+  let [x, y, width, height] = params.map((v) => parseInt(v ?? "", 10))
+  if (![x, y, width, height].every(Number.isFinite))
+    return Response.json({ error: "Crop rect requires all of x, y, width, height" }, { status: 400 })
+  return { x: x!, y: y!, width: width!, height: height! }
+}
+
+// Optional integer magnification shared by /snapshot and /texture. Returns
+// undefined when absent or 1, a 400 Response when out of range.
+function parseScale(query: Map<string, string>): number | Response | undefined {
+  let param = query.get("scale")
+  if (param === undefined) return undefined
+  let scale = parseInt(param, 10)
+  if (!Number.isFinite(scale) || scale < 1 || scale > 8)
+    return Response.json({ error: "Scale must be an integer between 1 and 8" }, { status: 400 })
+  return scale === 1 ? undefined : scale
+}
+
+async function handleQuery(
+  query: Map<string, string>,
+  kind: string,
+  extra?: Record<string, unknown>,
+  timeoutMs: number = QUERY_TIMEOUT_MS,
+): Promise<Response> {
   let target = findClient(query.get("client"))
   if ("error" in target) return target.error
   let id = nextQueryId++
@@ -100,7 +129,7 @@ async function handleQuery(query: Map<string, string>, kind: string, extra?: Rec
     pendingQueries.set(id, resolve)
   })
   target.ws.send(JSON.stringify({ type: "query", kind, id, ...extra }))
-  let msg = await Promise.race([reply, sleep(QUERY_TIMEOUT_MS)])
+  let msg = await Promise.race([reply, sleep(timeoutMs)])
   pendingQueries.delete(id)
   if (!msg)
     return Response.json(
@@ -174,7 +203,15 @@ async function handleLogs(query: Map<string, string>): Promise<Response> {
 export async function handleControl(req: Request, path: string, query: Map<string, string>): Promise<Response> {
   switch (path) {
     case "/__control__/clients":
-      return Response.json({ generation: state.generation, clients: clientList() })
+      // `entry`/`projectDir` identify which app this server is serving: the
+      // fixed dev port means an agent can reach a different project's server
+      // than it thinks, and a repl/MCP `load` moves the entry mid-session.
+      return Response.json({
+        generation: state.generation,
+        entry: state.config.entry ?? null,
+        projectDir: state.projectDir,
+        clients: clientList(),
+      })
     case "/__control__/logs":
       return handleLogs(query)
     case "/__control__/tree": {
@@ -185,6 +222,7 @@ export async function handleControl(req: Request, path: string, query: Map<strin
       if (Number.isFinite(depth)) extra.depth = depth
       let q = query.get("query")
       if (q) extra.query = q
+      if (query.get("props") === "true") extra.props = true
       return handleQuery(query, "tree", extra)
     }
     case "/__control__/stats":
@@ -192,7 +230,14 @@ export async function handleControl(req: Request, path: string, query: Map<strin
     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 })
+      let extra: Record<string, unknown> = { nodeId }
+      let rect = parseRect(query)
+      if (rect instanceof Response) return rect
+      if (rect) extra.rect = rect
+      let scale = parseScale(query)
+      if (scale instanceof Response) return scale
+      if (scale) extra.scale = scale
+      return handleQuery(query, "snapshot", extra)
     }
     case "/__control__/gpu":
       return handleQuery(query, "gpu")
@@ -211,17 +256,72 @@ export async function handleControl(req: Request, path: string, query: Map<strin
     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 }
-      }
+      let rect = parseRect(query)
+      if (rect instanceof Response) return rect
+      if (rect) extra.rect = rect
+      let scale = parseScale(query)
+      if (scale instanceof Response) return scale
+      if (scale) extra.scale = scale
       return handleQuery(query, "texture", extra)
     }
+    case "/__control__/clock": {
+      // Clock control: ?scale=<x> sets the client's time scale (0 pauses),
+      // ?step=<n> advances n frames while paused. Applied by the client
+      // runtime; the reply carries the resulting clock state.
+      if (req.method !== "POST") return Response.json({ error: "Clock requires POST" }, { status: 405 })
+      let extra: Record<string, unknown> = {}
+      let scaleParam = query.get("scale")
+      if (scaleParam !== undefined) {
+        let scale = parseFloat(scaleParam)
+        if (!Number.isFinite(scale) || scale < 0)
+          return Response.json({ error: "Clock scale must be a number >= 0" }, { status: 400 })
+        extra.scale = scale
+      }
+      let stepParam = query.get("step")
+      if (stepParam !== undefined) {
+        let step = parseInt(stepParam, 10)
+        if (!Number.isFinite(step) || step < 1 || step > 1000)
+          return Response.json({ error: "Clock step must be an integer between 1 and 1000" }, { status: 400 })
+        extra.step = step
+      }
+      if (!("scale" in extra) && !("step" in extra))
+        return Response.json({ error: "Clock requires ?scale=<x> or ?step=<n>" }, { status: 400 })
+      return handleQuery(query, "clock", extra)
+    }
+    case "/__control__/input": {
+      // Synthetic input injection: POST {events: [...]} forwards a timed
+      // event sequence to the client, which feeds it through the real input
+      // pipeline. Shape checks only here - the runtime validates each event
+      // and rejects the whole sequence on any bad one. The query timeout
+      // stretches by the sequence's own delays, since the client replies
+      // only after the last event has been sent.
+      if (req.method !== "POST") return Response.json({ error: "Input requires POST" }, { status: 405 })
+      let body: any = null
+      try {
+        body = await req.json()
+      } catch {}
+      let events = body?.events
+      if (!Array.isArray(events) || events.length === 0)
+        return Response.json({ error: "Input requires a body {events: [...]} with at least one event" }, { status: 400 })
+      if (events.length > 200) return Response.json({ error: "Input sequences are capped at 200 events" }, { status: 400 })
+      let totalMs = 0
+      for (let e of events) {
+        if (typeof e !== "object" || e === null)
+          return Response.json({ error: "Each event must be an object" }, { status: 400 })
+        for (let f of ["delayMs", "holdMs"]) {
+          let v = e[f]
+          if (v !== undefined) {
+            if (typeof v !== "number" || !Number.isInteger(v) || v < 0 || v > 5000)
+              return Response.json({ error: `Event ${f} must be an integer between 0 and 5000` }, { status: 400 })
+            totalMs += v
+          }
+        }
+      }
+      if (totalMs > 30000)
+        return Response.json({ error: "Input sequence too long: delays and holds total over 30000 ms" }, { status: 400 })
+      return handleQuery(query, "input", { events }, QUERY_TIMEOUT_MS + totalMs)
+    }
     case "/__control__/buffer": {
       let bufferId = parseInt(query.get("id") ?? "", 10)
       if (!Number.isFinite(bufferId)) return Response.json({ error: "Buffer requires ?id=<bufferId>" }, { status: 400 })
@@ -258,6 +358,19 @@ export async function handleControl(req: Request, path: string, query: Map<strin
       if (!(await file(entry).exists())) {
         return Response.json({ error: `Entry not found: ${entry}` }, { status: 400 })
       }
+      // An entry outside the project root cannot resolve the project's
+      // dependencies, so the bundler would fail with misleading "bun install"
+      // advice; name the real constraint instead.
+      let norm = (p: string) => p.replace(/\\/g, "/")
+      let root = norm(state.projectDir).replace(/\/+$/, "") + "/"
+      if (!norm(entry).startsWith(root)) {
+        return Response.json(
+          {
+            error: `Entry is outside the project root: ${entry} is not under ${state.projectDir}. The dev server can only bundle sources inside the project it was started in - move the file into the project or start srt there.`,
+          },
+          { status: 400 },
+        )
+      }
       state.config.entry = entry
       let cut = Math.max(entry.lastIndexOf("/"), entry.lastIndexOf("\\"))
       if (cut > 0) state.sourceDir = entry.slice(0, cut)

package/server/main.ts

@@ -216,7 +216,14 @@ serve({
   websocket: {
     open(ws) {
       let id = state.nextClientId++
-      state.clients.set(ws, { platform: "unknown", version: "unknown", profile: "unknown", id, capabilities: [] })
+      state.clients.set(ws, {
+        platform: "unknown",
+        version: "unknown",
+        profile: "unknown",
+        id,
+        capabilities: [],
+        queries: [],
+      })
       console.log(`[cli] Client connected ${ws.remoteAddr ?? "unknown"}`)
       // Advertise our real LAN address so clients dialed over a loopback hop
       // can show/remember the directly reachable address (see connection.rs).
@@ -243,6 +250,7 @@ serve({
             profile: data.profile ?? "unknown",
             id: existing?.id ?? state.nextClientId++,
             capabilities: Array.isArray(data.capabilities) ? data.capabilities.map(String) : [],
+            queries: Array.isArray(data.queries) ? data.queries.map(String) : [],
           })
           console.log(`[cli] Client info ${ws.remoteAddr ?? "unknown"} ${data.platform} (${data.version})`)
         } else if (data.type === "log") {

package/server/state.ts

@@ -38,7 +38,16 @@ export type Config = {
   tunnel: boolean
 }
 
-export type ClientInfo = { platform: string; version: string; profile: string; id: number; capabilities: string[] }
+export type ClientInfo = {
+  platform: string
+  version: string
+  profile: string
+  id: number
+  capabilities: string[]
+  /** Query kinds this client's runtime answers (empty on runtimes that predate
+   * the advertisement); dev tools plan their verification surface from it. */
+  queries: string[]
+}
 
 export let state = {
   config: undefined as unknown as Config,

package/src/commands/mcp.ts

@@ -42,7 +42,7 @@ async function control(path: string, method: "GET" | "POST" = "GET", payload?: u
 let CLIENT_ARG = z
   .number()
   .int()
-  .describe("Client id from list_clients (default: the only connected client)")
+  .describe("Client id from list_clients (default: the only connected client; required when several are connected)")
   .optional()
 
 let SAVE_TO_ARG = z
@@ -54,8 +54,9 @@ let SAVE_TO_ARG = z
 
 // 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);
+// auto-approve the inspection majority. load, reload, call_debug, and
+// send_input 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.
@@ -70,7 +71,7 @@ let TOOLS: {
     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.",
+      "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), `entry` (the app source file this server currently serves and rebuilds - check it matches the app you intend to drive before acting, since the dev port is fixed and a `load` moves the entry mid-session), `projectDir` (the project root the server was started in), 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, and `queries` - the dev-tool query kinds that client's runtime answers (clock, input, snapshot, tree, ...). Check `queries` before planning a verification strategy: a client whose list lacks \"input\" predates send_input, one that lacks \"clock\" predates set_time_scale/step_frames (an empty list means the runtime predates the advertisement itself). Use version/profile to check whether a connected binary contains a given engine change before debugging against it.",
     inputSchema: {},
   },
   {
@@ -110,7 +111,7 @@ let TOOLS: {
     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>.",
+      "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. Pass props: true to also get each node's current property values (JSX names, only values that differ from the defaults - so an empty/absent props object means everything is at its default) and, for nodes moved off their box by a rotate/scale/3D transform anywhere on their ancestor chain, `quad`: the four painted corners in window coordinates [x0,y0, x1,y1, x2,y2, x3,y3] (pre-transform top-left, top-right, bottom-right, bottom-left). The box is always the quad's axis-aligned bounds, so under a transform the box alone overstates the footprint - read the quad for where edges actually landed. Use props to answer 'is rotate/color/d applied right now' in one call instead of loading probe entries. Whole trees get large: prefer `query` to find nodes by kind or text first, then `root` + `depth` (+ props) 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: {
       root: z
         .number()
@@ -130,6 +131,10 @@ let TOOLS: {
             "scope the search; `depth` is ignored.",
         )
         .optional(),
+      props: z
+        .boolean()
+        .describe("Include each node's current off-default property values and, for transformed nodes, the painted quad")
+        .optional(),
       client: CLIENT_ARG,
     },
   },
@@ -137,12 +142,30 @@ let TOOLS: {
     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. Capture the smallest node that contains what you are checking (e.g. the <texture> leaf itself) - that is exactly the content at its own pixel size; the window root is mostly empty layout around it and orders of magnitude more pixels. Reserve root captures for when layout/positioning itself is the question. The node must be currently mounted and paint a non-zero box. Detached (`d-*`) nodes capture their painted box: their own `w`/`h` when set, else the box inherited from the nearest laid-out ancestor (the same box get_render_tree reports for them). 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.",
+      "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. Capture the smallest node that contains what you are checking (e.g. the <texture> leaf itself) - that is exactly the content at its own pixel size; the window root is mostly empty layout around it and orders of magnitude more pixels. Reserve root captures for when layout/positioning itself is the question. The node must be currently mounted and paint a non-zero box. Detached (`d-*`) nodes capture their painted box: their own `w`/`h` when set, else the box inherited from the nearest laid-out ancestor (the same box get_render_tree reports for them). A capture renders only that node's subtree, with no ancestor paint: pixels nothing in the subtree draws come back transparent, not the background an ancestor draws behind the node - capture the window root when the background matters. Pass x/y/width/height to crop and `scale` to magnify: captures may be downscaled before you see them, so verify small hand-authored geometry (sprites, path data, icons) with a tight crop at 4x-8x rather than squinting at a full capture. Crop coordinates are in captured-image pixels (the width x height a capture of that node reports - device pixels), not the logical units get_render_tree reports. 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: {
       nodeId: z
         .number()
         .int()
         .describe("Id of the node to capture, from get_render_tree; prefer the smallest relevant node over the root"),
+      x: z
+        .number()
+        .int()
+        .describe("Crop rect left edge in captured-image pixels (requires y, width, height)")
+        .optional(),
+      y: z.number().int().describe("Crop rect top edge in captured-image pixels").optional(),
+      width: z.number().int().describe("Crop rect width in captured-image pixels").optional(),
+      height: z.number().int().describe("Crop rect height in captured-image pixels").optional(),
+      scale: z
+        .number()
+        .int()
+        .min(1)
+        .max(8)
+        .describe(
+          "Integer magnification, 1-8: each captured pixel becomes an NxN block (nearest-neighbour), so you see " +
+            "the actual rendered pixels enlarged. Combine with a crop; the scaled output is capped at 8192 px per side",
+        )
+        .optional(),
       save_to: SAVE_TO_ARG,
       client: CLIENT_ARG,
     },
@@ -158,13 +181,23 @@ let TOOLS: {
     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/createShaderTexture/createPipelineTexture in app code). Works on sampled textures (atlases, data textures) and shader/pipeline render targets alike, without needing a frame: a render target reads as its current output, with any pending params, geometry or sampled-input changes resolved first. Pass x/y/width/height to crop, e.g. one tile of an atlas.",
+      "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/createShaderTexture/createPipelineTexture in app code). Works on sampled textures (atlases, data textures) and shader/pipeline render targets alike, without needing a frame: a render target reads as its current output, with any pending params, geometry or sampled-input changes resolved first. Pass x/y/width/height to crop, e.g. one tile of an atlas, and `scale` to magnify small content like a single tile or glyph.",
     inputSchema: {
       id: z.number().int().describe("Texture id, from get_gpu_resources"),
       x: z.number().int().describe("Crop rect left edge in texture pixels (requires y, width, height)").optional(),
       y: z.number().int().describe("Crop rect top edge in texture pixels").optional(),
       width: z.number().int().describe("Crop rect width in texture pixels").optional(),
       height: z.number().int().describe("Crop rect height in texture pixels").optional(),
+      scale: z
+        .number()
+        .int()
+        .min(1)
+        .max(8)
+        .describe(
+          "Integer magnification, 1-8: each texture pixel becomes an NxN block (nearest-neighbour). Combine with " +
+            "a crop; the scaled output is capped at 8192 px per side",
+        )
+        .optional(),
       save_to: SAVE_TO_ARG,
       client: CLIENT_ARG,
     },
@@ -213,6 +246,61 @@ let TOOLS: {
       entry: z.string().describe("App entry source file to load (relative paths resolve against the project root)"),
     },
   },
+  {
+    name: "set_time_scale",
+    annotations: { destructiveHint: false, idempotentHint: true },
+    description:
+      "Control a running app client's clock. scale=0 freezes app time: onFrame/requestAnimationFrame stop being delivered, setTimeout/setInterval freeze, performance.now() holds still, and the picture stops - so get_snapshot can capture an exact frame of any animation instead of racing it (tool round trips are usually slower than the animation). Combine with a registerDebug command that sets up the state to photograph: set state, pause, snapshot. Other values scale time for dt-driven apps (0.5 = half speed, 2 = double); apps that advance a fixed amount per onFrame call only respond to 0 and 1. Date.now() stays wall time throughout. The scale is client runtime state: it survives across your snapshots but resets to 1 on reload/load and on client restart. ALWAYS set it back to 1 when you are done - a paused client looks wedged to the human watching the screen.",
+    inputSchema: {
+      scale: z
+        .number()
+        .min(0)
+        .describe("Time scale: 0 = pause, 1 = normal, 0.5 = half speed, 2 = double speed"),
+      client: CLIENT_ARG,
+    },
+  },
+  {
+    name: "step_frames",
+    annotations: { destructiveHint: false },
+    description:
+      "While paused (set_time_scale 0), advance a running app client by exactly n frames: each frame moves app time forward one refresh period (~16.7 ms at 60 Hz), runs onFrame/requestAnimationFrame and any timers that come due, and presents the result. Deterministic single-stepping for animations and game logic: pause, snapshot, step, snapshot again to see exactly what changed in n frames. With the clock running this is a no-op (frames already flow). Steps are applied at the client's frame rate, so n frames take about n refresh periods of wall time before a following snapshot shows the result.",
+    inputSchema: {
+      n: z.number().int().min(1).max(1000).describe("Number of frames to advance (1-1000)"),
+      client: CLIENT_ARG,
+    },
+  },
+  {
+    name: "send_input",
+    description:
+      "Send synthetic input to a running app client through the real input pipeline (hit testing, focus, event bubbling) - the same path physical input takes, unlike call_debug which sets state directly, so use this to verify interactions actually work. Events run in order; each may wait delayMs (0-5000 ms) before firing, and the call returns after the last event has entered the pipeline, so a following get_snapshot sees the result. Event kinds: {type:'pointer', action:'down'|'up'|'move'|'tap', x, y} for clicks and drags - coordinates in logical points, the same space get_render_tree reports; 'tap' is down+up with an optional holdMs between; button 0 = left (default), 1 = middle, 2 = right; pointerType 'mouse' (default) keeps hovering at its last position afterwards like a real cursor, use 'touch' for gestures that should end hover-free. {type:'key', action:'down'|'up'|'tap', key} with W3C key names exactly as the runtime reports them ('w', 'ArrowLeft', 'Enter', ' '); a 'tap' with holdMs holds the key down that long, e.g. holdMs 500 = walk forward half a second in one call; modifier booleans shift/ctrl/alt/meta. {type:'text', text} enters text through the TextInput path - focus the target first with a pointer tap on it (the tap also activates the text session). {type:'wheel', x, y, deltaX, deltaY} scrolls; positive deltaY scrolls content down. Recipes: click a button = [{type:'pointer',action:'tap',x:400,y:300}]. Drag = down, then moves with delayMs 16 each, then up. Deterministic interaction test = set_time_scale 0, send_input, step_frames, get_snapshot. A down/up over empty space hits nothing, exactly like real input - check coordinates against get_render_tree when a click seems to do nothing.",
+    inputSchema: {
+      events: z
+        .array(
+          z.object({
+            type: z.enum(["key", "pointer", "wheel", "text"]),
+            action: z.enum(["down", "up", "move", "tap"]).optional(),
+            key: z.string().optional().describe("W3C key name, required for type key"),
+            text: z.string().optional().describe("Text to enter, required for type text"),
+            x: z.number().optional().describe("Logical points, required for pointer and wheel"),
+            y: z.number().optional().describe("Logical points, required for pointer and wheel"),
+            deltaX: z.number().optional(),
+            deltaY: z.number().optional(),
+            button: z.number().int().min(0).max(4).optional(),
+            pointerType: z.enum(["mouse", "touch"]).optional(),
+            delayMs: z.number().int().min(0).max(5000).optional().describe("Wait before this event"),
+            holdMs: z.number().int().min(0).max(5000).optional().describe("Tap only: time between down and up"),
+            shift: z.boolean().optional(),
+            ctrl: z.boolean().optional(),
+            alt: z.boolean().optional(),
+            meta: z.boolean().optional(),
+          }),
+        )
+        .min(1)
+        .max(200)
+        .describe("Event sequence, executed in order"),
+      client: CLIENT_ARG,
+    },
+  },
   {
     name: "watch",
     annotations: { destructiveHint: false, idempotentHint: true },
@@ -248,6 +336,7 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
       if (typeof args?.root === "number") params.set("root", String(args.root))
       if (typeof args?.depth === "number") params.set("depth", String(args.depth))
       if (typeof args?.query === "string") params.set("query", args.query)
+      if (args?.props === true) params.set("props", "true")
       if (typeof args?.client === "number") params.set("client", String(args.client))
       let qs = params.toString()
       return control(qs ? `/tree?${qs}` : "/tree")
@@ -267,9 +356,31 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
     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) })
+      for (let key of ["x", "y", "width", "height", "scale"]) {
+        if (typeof args?.[key] === "number") params.set(key, String(args[key]))
+      }
       if (typeof args?.client === "number") params.set("client", String(args.client))
       return control(`/snapshot?${params.toString()}`)
     }
+    case "set_time_scale": {
+      if (typeof args?.scale !== "number" || !(args.scale >= 0)) {
+        return { ok: false, message: "set_time_scale requires scale >= 0" }
+      }
+      let params = new URLSearchParams({ scale: String(args.scale) })
+      if (typeof args?.client === "number") params.set("client", String(args.client))
+      return control(`/clock?${params.toString()}`, "POST")
+    }
+    case "step_frames": {
+      if (typeof args?.n !== "number" || !(args.n >= 1)) return { ok: false, message: "step_frames requires n >= 1" }
+      let params = new URLSearchParams({ step: String(args.n) })
+      if (typeof args?.client === "number") params.set("client", String(args.client))
+      return control(`/clock?${params.toString()}`, "POST")
+    }
+    case "send_input": {
+      if (!Array.isArray(args?.events) || args.events.length === 0)
+        return { ok: false, message: "send_input requires a non-empty events array" }
+      return control(`/input${clientParam(args)}`, "POST", { events: args.events })
+    }
     case "get_gpu_resources":
       return control(`/gpu${clientParam(args)}`)
     case "list_debug":
@@ -283,7 +394,7 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
     case "get_texture": {
       if (typeof args?.id !== "number") return { ok: false, message: "get_texture requires a numeric id" }
       let params = new URLSearchParams({ id: String(args.id) })
-      for (let key of ["x", "y", "width", "height"]) {
+      for (let key of ["x", "y", "width", "height", "scale"]) {
         if (typeof args?.[key] === "number") params.set(key, String(args[key]))
       }
       if (typeof args?.client === "number") params.set("client", String(args.client))