@solidrt/cli 0.0.39 → 0.0.41

package/package.json

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

package/scaffold/AGENTS.md

@@ -117,7 +117,15 @@ Authoritative references ship inside the installed packages - read them:
     mounted. To inspect children (a typeof probe, counting), resolve them
     first with the children() helper (re-exported from @solidrt/core) and
     probe the resolved memo - never `typeof props.children` on the raw prop.
-18. Cover/contain images: give `Image` a `fit` prop ("fill" | "cover" |
+18. Writing a signal or store from inside an owned scope - a component body, a
+    `createMemo`, an effect's compute phase - throws
+    `REACTIVE_WRITE_IN_OWNED_SCOPE` in dev. Calling a loader/init function in
+    the component body that sets state is the classic React / Solid 1.x
+    reflex and hits this every time. Move the write into an event handler, an
+    effect's apply phase, or `onSettled`; opt in narrowly with
+    `createSignal(v, { ownedWrite: true })` for a signal that genuinely is
+    internal state.
+19. Cover/contain images: give `Image` a `fit` prop ("fill" | "cover" |
     "contain" | "none" | "scale-down", CSS object-fit semantics, centered)
     plus a box via `layout` in any form - numbers, pct(), flex. Without
     `fit`, only NUMERIC layout sizes reach the image; `width: pct(100)`
@@ -128,14 +136,39 @@ Authoritative references ship inside the installed packages - read them:
 
 The JS engine is interpreted and every property write crosses an FFI boundary
 into the runtime, so per-frame JS work is the expensive path while GPU work is
-nearly free. Rules, in order of leverage:
+nearly free. That holds on desktop and on current mobile hardware; "Where GPU
+work stops being free" below is where it does not. Rules, in order of leverage:
 
 1. Continuous effects (snow, particles, animated backgrounds) belong in a
-   fragment shader: createShader (from @solidrt/core/gpu) + `<texture
-   params={{ iTime }}>`. The whole effect then costs one setProperty per
-   frame - the iTime write - regardless of visual complexity. Shader output
+   fragment shader: createShaderTexture (from @solidrt/core/gpu) + `<texture
+   params={{ uTime }}>` (the shader declares `uniform float uTime;` itself -
+   the preamble declares only what the runtime fills). The whole effect then
+   costs one setProperty per frame - the uTime write - regardless of visual
+   complexity. Shader output
    must be premultiplied alpha (white flakes are `vec4(vec3(a), a)`);
-   straight alpha (`vec4(1,1,1,a)`) composites as opaque white.
+   straight alpha (`vec4(1,1,1,a)`) composites as opaque white. A source that
+   starts with `#version 300 es` is compiled exactly as written - no preamble
+   is injected, though the built-in vertex stage still supplies `vUV` - so a
+   shader ported from elsewhere keeps its own uniform names without dropping
+   to compileShader/linkProgram. Params drive any uniform type: a number
+   fills a `float`/`int` scalar, a flat number array fills `vec2`/`vec3`/
+   `vec4` (2/3/4 numbers) or `mat4` (16, column-major), dispatched by the
+   shader's own declaration - a ported shader's `vec2 uCenter` or Shadertoy's
+   `vec3 iResolution` needs no splitting into scalars. To combine several
+   GPU passes, stack `<texture>` elements and set `blendMode` (e.g. a base
+   pass plus an additive `blendMode="plus"` pass) rather than writing a
+   compositing shader. Within one pipeline draw, createPipelineTexture's
+   `blend: "add"` accumulates overlapping geometry additively (soft point
+   splats, glow) - pair it with `depthWrite: false` when depth-tested;
+   neither option implies the other. A pipeline's own vertex stage writes
+   into a y-down clip space: `gl_Position` y = -1 is the top row of the
+   target and +1 the bottom, so camera-up geometry must negate y (or fold
+   the flip into its projection) or it draws upside down. Sampling is a
+   create-time option on every texture: `{ filter: "nearest" }` for
+   hard-pixel upscaling (render a small target, display it big - the
+   retro/pixel-art path) and `{ wrap: "repeat" }` to tile outside 0..1 in
+   shaders; the defaults are linear and clamp, and the choice applies both
+   on screen and to shaders sampling the texture.
 2. Reduce setProperty calls wherever possible: one path string rebuilt per
    frame beats N elements with N animated positions; a shader beats the path
    string. get_stats' setPropsPerFrame is the counter to watch.
@@ -159,6 +192,44 @@ nearly free. Rules, in order of leverage:
    creating many at once (dealing a board of 64 sprites) is a visible
    one-frame hiccup - pool or pre-warm if that moment matters.
 
+### Where GPU work stops being free
+
+"GPU work is nearly free" is a property of the hardware, not of the engine, and
+the spread is wide enough to design against rather than discover late. The same
+app - two point-cloud pipelines, 233,600 vertices, one params write each per
+onFrame, i.e. exactly what rule 1 recommends - measured 16.7 ms/frame (60 fps,
+vsync-locked) on both desktop and a mid-range 2020 tablet, and 120 ms/frame
+(8.3 fps) on a 2017 Android TV. Roughly 8x for identical work, with the tablet
+indistinguishable from desktop. Measure on a target device if it matters; do
+not infer it from the desktop number.
+
+- **On a tiled GPU the budget is primitive count, not pixels.** Every point or
+  triangle costs the tiler regardless of how few pixels it covers. On that TV,
+  frame time against total vertices with a trivial vertex shader: 20k -> 80 ms,
+  35k -> 100 ms, 100k -> 380 ms. Meanwhile `gl_PointSize = 3.0` - nine times
+  the fill - measured within one vsync of 1.0, and rendering into a
+  quarter-size target measured identical to full size. So for a heavy pass the
+  lever is fewer primitives; shrinking the target or the splat usually is not,
+  and coverage is far cheaper bought with point size than with more points.
+- **A device's compositor can set the frame budget outright**, in which case
+  none of the above moves. That TV never presents faster than every 80 ms -
+  four refresh periods blocked inside `eglSwapBuffers` - even for a near-empty
+  scene, so its ceiling is ~12 fps whatever you draw. Recognise it by a
+  content-independent floor: if a trivial scene and a heavy one present at
+  nearly the same rate, you are compositor-bound and tuning the scene is
+  wasted effort.
+- **Per-frame writes are gated on the raster thread, not on vsync**, so a pass
+  that costs more than a refresh period does not silently pile up. If
+  `rasterQueue` sits persistently above 0 the raster thread is behind; if
+  `fenceTimeouts` climbs, the GPU is over its pacing budget.
+
+Finding your own numbers: `get_stats` gives fps, frameMs, setPropsPerFrame,
+rasterQueue and fenceTimeouts. When those disagree with what the screen is
+visibly doing, ground truth on Android is
+`adb shell dumpsys SurfaceFlinger --latency <layer>` for real present
+timestamps - engine-reported phase timings can each be honest and still not add
+up to the frame period, because work outside the frame call is not in them.
+
 ## Assets and app identity
 
 - Everything under `assets/` ships with the app: the folder is collected
@@ -167,10 +238,13 @@ nearly free. Rules, in order of leverage:
   from `flux:fs` - and treat them as read-only at runtime; writes belong in
   plain relative paths, which land in the app's private data dir.
 - Small text-like assets (SVG documents, shaders) can instead be inlined via
-  imports (`import icon from "./icon.svg"` yields the file's text;
-  `with { type: "binary" }` yields a Uint8Array). Inlining trades update
-  granularity for zero I/O - keep big or streamable files (audio, images) in
-  `assets/`.
+  imports. An import attribute picks the form and works on any extension:
+  `import src from "./effect.glsl" with { type: "text" }` yields the file's
+  contents as a string, `with { type: "binary" }` yields a Uint8Array. `.svg`
+  is text-loaded with no attribute needed. Shader sources (`.glsl`/`.vert`/
+  `.frag`) are declared as text modules out of the box, so they typecheck
+  without setup. Inlining trades update granularity for zero I/O - keep big or
+  streamable files (audio, images) in `assets/`.
 - Custom fonts go in `assets/fonts/` and are declared in the `solidrt.fonts`
   map in package.json (alias -> file path; role aliases `sans`/`serif`/`mono`
   replace the built-in defaults, `false` drops one, other keys add fonts
@@ -225,11 +299,12 @@ its tools over guessing at runtime state:
   (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)
+  layout, bound textures, current uniform values - the most recent writes,
+  which the next frame or readback draws with)
 - 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
+  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
 - 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
@@ -246,7 +321,9 @@ its tools over guessing at runtime state:
   when you stop working - the user's own saves rely on it.
 
 The tools need a running app: if list_clients is empty, ask the user to start
-`bunx srt run src/index.tsx`.
+`bunx srt run src/index.tsx`. The bridge dials the dev server's default port
+(34884), so if the user started it with `--port N`, .mcp.json needs the same
+flag: `"args": [..., "mcp", "--port", "N"]`.
 
 - Permission prompts: agents typically ask approval per MCP tool. All of
   these tools only talk to the local dev server the user started with
@@ -274,13 +351,17 @@ The tools need a running app: if list_clients is empty, ask the user to start
   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.
+  setFocus(node.id) from the window's ref or onKeyDown never fires. `key` and
+  `code` are W3C KeyboardEvent values, so arrow keys arrive as "ArrowLeft"/
+  "ArrowRight"/"ArrowUp"/"ArrowDown" (not "Left"), alongside "Enter",
+  "Escape", "a".
+- Idle frames skip work: shaders/pipelines only re-render when an input
+  changes - their own params/geometry, or a sampled texture (a data upload,
+  or a sampled target re-rendering; chains propagate automatically). Measure
+  performance while inputs 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
+  current output, pending writes included, without needing a new frame.
 - 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.

package/scaffold/package.json

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

package/src/args.ts

@@ -21,6 +21,7 @@ export let { values, positionals } = parseArgs({
     "data-root": { type: "string" },
     client: { type: "string" },
     server: { type: "string" },
+    port: { type: "string" },
     android: { type: "boolean", default: false },
     device: { type: "string" },
     template: { type: "string", short: "t" },
@@ -95,6 +96,12 @@ export function validateArgs() {
   if (values.server && command !== "client") {
     usage("srt client --server <host[:port]>  (--server is only valid with the client command)")
   }
+  // --port moves the dev server off its default port, so it belongs to the
+  // commands that start one (`run`, `server`) or attach to one (`mcp`). A
+  // standalone client carries the port in --server <host:port> instead.
+  if (values.port !== undefined && command !== "run" && command !== "server" && command !== "mcp") {
+    usage("srt <run|server|mcp> --port <N>  (--port is only valid with the run, server and mcp commands)")
+  }
 }
 
 export function printUsage() {
@@ -115,6 +122,7 @@ init options:
   -t, --template <name>  Start from a named template (skips the interactive picker)
 
 run/server options:
+      --port <N>         Dev server port (default: 34884)
       --proxy-http       Route fetch calls through the dev server (HTTP cache enabled)
       --capture <file>   Record connected clients' key events to a script file
       --tunnel           Accept ticket-paired clients through the p2p tunnel
@@ -130,6 +138,9 @@ client options:
       --android          Install and launch the client on a connected Android device
       --device <serial>  Target a specific adb device by serial or unique prefix
 
+mcp options:
+      --port <N>         Port of the dev server to attach to (default: 34884)
+
 bundle options:
   -f, --flux             Bundle for the bare Flux runtime, without SolidJS (entry must be .ts|.js)
   -d, --dev              Use development build of SolidJS (default: production)

package/src/bundler.ts

@@ -11,40 +11,48 @@ import { state, print, requireBinary } from "./util"
 import { buildManifest } from "./project"
 
 // Babel plugin: rewrite `import data from "./x" with { type: "binary" }` into an
-// inline Uint8Array of the file's bytes. The import attribute is invisible to
+// inline Uint8Array of the file's bytes, and `with { type: "text" }` into an
+// inline string of its UTF-8 contents. The import attribute is invisible to
 // Bun's bundler and its plugins in this Bun version, so we handle it here in the
 // transform where the AST still carries it. Inlining (rather than emitting a
 // separate asset) keeps a single bundle output and hands JS a Uint8Array, which
-// is what createImage and friends expect. Decoded at runtime via the global
-// atob; for ASCII-extension files (.jpg/.png/...) we may add an attribute-free
-// path later.
-function binaryImport({ types: t }: { types: any }) {
+// is what createImage and friends expect. Binary is decoded at runtime via the
+// global atob; for ASCII-extension files (.jpg/.png/...) we may add an
+// attribute-free path later. Both attributes work on any extension, so shader
+// and other text sources inline by attribute the same way bytes do; `.svg` is
+// additionally text-loaded without an attribute (see Bun's `loader` below).
+function inlineImport({ types: t }: { types: any }) {
   return {
     visitor: {
       ImportDeclaration(path: any, pluginState: any) {
         let attrs = path.node.attributes ?? path.node.assertions
-        let isBinary = attrs?.some((a: any) => a.key.name === "type" && a.value.value === "binary")
-        if (!isBinary) return
+        let kind = attrs?.find((a: any) => a.key.name === "type")?.value.value
+        if (kind !== "binary" && kind !== "text") return
 
         let def = path.node.specifiers.find((s: any) => s.type === "ImportDefaultSpecifier")
         if (!def) {
           throw path.buildCodeFrameError(
-            'A binary import needs a default import: import data from "./file" with { type: "binary" }',
+            `A ${kind} import needs a default import: import data from "./file" with { type: "${kind}" }`,
           )
         }
 
         let importer = pluginState.file.opts.filename as string
         let abs = resolvePath(dirname(importer), path.node.source.value)
-        let b64 = readFileSync(abs).toString("base64")
-
-        // var <local> = Uint8Array.from(atob("<b64>"), c => c.charCodeAt(0))
-        let expr = t.callExpression(t.memberExpression(t.identifier("Uint8Array"), t.identifier("from")), [
-          t.callExpression(t.identifier("atob"), [t.stringLiteral(b64)]),
-          t.arrowFunctionExpression(
-            [t.identifier("c")],
-            t.callExpression(t.memberExpression(t.identifier("c"), t.identifier("charCodeAt")), [t.numericLiteral(0)]),
-          ),
-        ])
+
+        // text: var <local> = "<contents>"
+        // binary: var <local> = Uint8Array.from(atob("<b64>"), c => c.charCodeAt(0))
+        let expr =
+          kind === "text"
+            ? t.stringLiteral(readFileSync(abs, "utf8"))
+            : t.callExpression(t.memberExpression(t.identifier("Uint8Array"), t.identifier("from")), [
+                t.callExpression(t.identifier("atob"), [t.stringLiteral(readFileSync(abs).toString("base64"))]),
+                t.arrowFunctionExpression(
+                  [t.identifier("c")],
+                  t.callExpression(t.memberExpression(t.identifier("c"), t.identifier("charCodeAt")), [
+                    t.numericLiteral(0),
+                  ]),
+                ),
+              ])
         path.replaceWith(t.variableDeclaration("var", [t.variableDeclarator(t.identifier(def.local.name), expr)]))
       },
     },
@@ -65,7 +73,7 @@ async function codeFromOutputs(outputs: BuildArtifact[]): Promise<string> {
 
 // Bun build plugin that runs JSX/TSX through babel-preset-solid (universal
 // generate, targeting @solidrt/core) plus the TS preset. Plain .js/.ts app
-// modules take the same path (solid is a no-op without JSX) so binaryImport
+// modules take the same path (solid is a no-op without JSX) so inlineImport
 // can rewrite their `with { type: "binary" }` imports too; dependency code
 // (node_modules) skips the babel detour and keeps Bun's native loaders.
 // With `babelMaps`, each file's transform map (original -> babel output) is
@@ -82,7 +90,7 @@ function solidPlugin(babelMaps?: Map<string, object>): BunPlugin {
           filename: args.path,
           sourceMaps: !!babelMaps,
           presets: [[solid, { moduleName: "@solidrt/core", generate: "universal" }], [ts]],
-          plugins: [jsx, binaryImport],
+          plugins: [jsx, inlineImport],
         })
         if (babelMaps && transforms?.map) babelMaps.set(args.path, transforms.map)
         return { contents: transforms?.code ?? "", loader: "js" }

package/src/commands/check.ts

@@ -60,11 +60,11 @@ function findTsc(fromDir: string): string | null {
 
 // Typecheck the entry's program, not the enclosing project: a transient
 // config extends the project's tsconfig and roots the program at the entry
-// alone, so tsc checks exactly the entry's import closure - unrelated files
-// are excluded by construction. The config lives in the project-local
-// .srt-data (the dev-artifact dir; absolute paths inside, so its location
-// only matters for type-package resolution, which walks up to the project's
-// node_modules from there).
+// alone (plus the project's ambient declarations), so tsc checks exactly the
+// entry's import closure - unrelated files are excluded by construction. The
+// config lives in the project-local .srt-data (the dev-artifact dir; absolute
+// paths inside, so its location only matters for type-package resolution,
+// which walks up to the project's node_modules from there).
 export async function typecheck(root: string, entry: string): Promise<{ app: Diagnostic[]; hidden: number } | null> {
   let tsconfig = join(root, "tsconfig.json")
   if (!existsSync(tsconfig)) {
@@ -79,10 +79,14 @@ export async function typecheck(root: string, entry: string): Promise<{ app: Dia
   let dataDir = join(root, ".srt-data")
   mkdirSync(dataDir, { recursive: true })
   let config = join(dataDir, `typecheck-${process.pid}.tsconfig.json`)
-  // include: [] overrides any include inherited from the extended config -
-  // files and include are unioned, so without this a base config's include
-  // would drag the whole project back into the program.
-  await Bun.write(config, JSON.stringify({ extends: tsconfig, include: [], files: [resolve(entry)] }))
+  // The include narrows the inherited one (files and include are unioned, so
+  // without it a base config's include would drag the whole project back into
+  // the program) down to declaration files only. Those are the one thing the
+  // entry's import closure cannot reach: an ambient `declare module "*.glsl"`
+  // applies precisely because nothing imports it, so entry-only rooting would
+  // silently drop it and every asset import would fail with TS2307. The
+  // pattern is relative to this config, which sits one level under the root.
+  await Bun.write(config, JSON.stringify({ extends: tsconfig, include: ["../**/*.d.ts"], files: [resolve(entry)] }))
   try {
     let proc = Bun.spawn([tsc, "-p", config, "--noEmit", "--pretty", "false"], {
       cwd: root,

package/src/commands/mcp.ts

@@ -103,7 +103,7 @@ let TOOLS: {
     name: "get_stats",
     readOnly: true,
     description:
-      "Performance statistics from a running app client: fps, CPU%, memory, smoothed JS/layout/paint/hover frame times (ms), setProperty writes per frame, demand-gate reuse/skip counts per second, and live texture count. Layout-activity counters cover the last full rebuild, raw: nodes (live node count, mounted AND detached), mountedNodes/orphanNodes (live at query time: nodes reachable from the root vs not - orphans growing at a stable tree shape mean an unmount leak; absent when no engine is running), measureCalls (text measures; mostly cache hits, cheap), paraShapes (paragraphs actually shaped; the expensive signal - high layoutMs with near-zero paraShapes means the cost is not text shaping), dirtiedNodes (layout caches cleared by property writes since the previous rebuild; how much of the tree a write burst invalidated), cacheGets/cacheHits (layout-cache lookups during the rebuild; a hit on a container skips its whole subtree, so a healthy incremental rebuild shows a near-100% hit rate - a low rate at scale means the layout cache is being defeated). GPU-side health, read live at query time (absent when no engine is running): rasterQueue (raster commands sent but not yet executed; stuck nonzero means the raster thread is backlogged - the state where fps and frameMs go blind because no frames complete), idleTicks (cumulative idle frame signals emitted while the GPU had nothing queued; idleTicks racing while rasterQueue sits nonzero would mean the idle-tick gate is broken), fenceTimeouts (cumulative present-fence waits that expired instead of signaling - each one is a frame where the GPU was over budget for 100ms+ and one-frame-in-flight pacing was lost; zero on a healthy machine, climbing means the GPU is the bottleneck right now).",
+      "Performance statistics from a running app client: fps, CPU%, memory, smoothed JS/layout/paint/hover frame times (ms), setProperty writes per frame, demand-gate reuse/skip counts per second, and live texture count. Layout-activity counters cover the last full rebuild, raw: nodes (live node count, mounted AND detached), mountedNodes/orphanNodes (live at query time: nodes reachable from the root vs not - orphans growing at a stable tree shape mean an unmount leak; absent when no engine is running), measureCalls (text measures; mostly cache hits, cheap), paraShapes (paragraphs actually shaped; the expensive signal - high layoutMs with near-zero paraShapes means the cost is not text shaping), dirtiedNodes (layout caches cleared by property writes since the previous rebuild; how much of the tree a write burst invalidated), cacheGets/cacheHits (layout-cache lookups during the rebuild; a hit on a container skips its whole subtree, so a healthy incremental rebuild shows a near-100% hit rate - a low rate at scale means the layout cache is being defeated). GPU-side health, read live at query time (absent when no engine is running): rasterQueue (raster commands sent but not yet executed; stuck nonzero means the raster thread is backlogged - the state where fps and frameMs go blind because no frames complete), idleTicks (cumulative idle frame signals emitted while the GPU had nothing queued; idleTicks racing while rasterQueue sits nonzero would mean the idle-tick gate is broken), fenceTimeouts (cumulative present-fence waits that expired instead of signaling - each one is a frame where the GPU was over budget for 100ms+ and one-frame-in-flight pacing was lost; zero on a healthy machine, climbing means the GPU is the bottleneck right now), gpuPasses/gpuPassMs (cumulative shader/pipeline target renders on the raster thread and the wall time they took in whole ms - diff two queries to get a rate; passes racing far ahead of frames means redundant target re-renders, the failure mode where fps and frameMs look healthy while the raster thread drowns; the ms figure is raster-thread occupancy issuing the passes, not GPU-side duration), rasterCmdMs (cumulative wall time in whole ms the raster thread spent executing non-frame commands - texture uploads, readbacks, offscreen rasterizations, shader compiles, param writes and the target re-renders they trigger; the work frameMs never sees, so rasterCmdMs growing much faster than frames are presented means the raster thread is drowning in side work even if every counter above looks calm).",
     inputSchema: { client: CLIENT_ARG },
   },
   {
@@ -137,7 +137,7 @@ 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 have a non-zero layout box. Works on an idle client (the capture requests its own frame); a timeout means the client's JS thread is busy or wedged, not that the app is idle.",
+      "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.",
     inputSchema: {
       nodeId: z
         .number()
@@ -151,14 +151,14 @@ let TOOLS: {
     name: "get_gpu_resources",
     readOnly: true,
     description:
-      "Inventory of a running app client's GPU resources: textures (id, size, whether a shader renders into it), vertex buffers (id, byteLength), and shader/pipeline targets (output textureId, kind, bufferId, topology, drawCount, depth, attribute layout, bound sampler texture ids, last-applied uniform values). Use it when the render tree is just a <texture> leaf and the interesting state lives behind it; follow up with get_texture or get_buffer to see contents.",
+      "Inventory of a running app client's GPU resources: textures (id, size, whether a shader renders into it), vertex buffers (id, byteLength), and shader/pipeline targets (output textureId, kind, bufferId, topology, drawCount plus firstVertex/instanceCount when off their 0/1 defaults, depth, attribute layout, bound sampler texture ids, current uniform values - the most recent writes, which the next frame or readback draws with - plus passes/passMs, cumulative per-target render count and raster-thread wall time in whole ms: when get_stats shows gpuPasses running hot, these attribute the cost to the specific target). Use it when the render tree is just a <texture> leaf and the interesting state lives behind it; follow up with get_texture or get_buffer to see contents.",
     inputSchema: { client: CLIENT_ARG },
   },
   {
     name: "get_texture",
     readOnly: true,
     description:
-      "Read back any GPU texture from a running app client as a PNG, by texture id (from get_gpu_resources, or the id returned by createImage/createShader/createPipeline in app code). Works on sampled textures (atlases, data textures) and shader/pipeline render targets alike, without needing a frame. Pass x/y/width/height to crop, e.g. one tile of an atlas.",
+      "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.",
     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(),

package/src/dev-server.ts

@@ -5,7 +5,23 @@ import { state, print, printErr, requireBinary, pipeAbovePrompt, shutdown } from
 import { values } from "./args"
 
 export const DEV_HOST = "127.0.0.1"
-export const DEV_PORT = 0x8844
+export const DEFAULT_DEV_PORT = 0x8844
+
+// The port every dev-server consumer dials: the spawned server, the local and
+// Android clients' --dev-server address, and the MCP bridge's control base.
+// Resolved once here, so --port needs no threading through those call sites.
+function resolveDevPort(): number {
+  let raw = values.port
+  if (raw === undefined) return DEFAULT_DEV_PORT
+  let port = Number(raw)
+  if (!/^\d+$/.test(raw) || port < 1 || port > 65535) {
+    console.error(`Invalid --port value "${raw}": expected a port number between 1 and 65535`)
+    process.exit(1)
+  }
+  return port
+}
+
+export let DEV_PORT = resolveDevPort()
 
 // The dev server itself is a flux script (packages/cli/server/), spawned by
 // srt: bundling, file watching, and the repl stay here and drive the server
@@ -157,8 +173,23 @@ async function bundleServer(): Promise<string> {
   return outfile
 }
 
+// The server runs as a separate flux process, so a port clash surfaces there as
+// a bare non-zero exit ("Dev server exited unexpectedly (1)"). Claim the port
+// here first to turn that into the actual reason, and into the fix.
+function requireFreePort(port: number) {
+  try {
+    // Default hostname: the server binds every interface, so probe the same way.
+    let probe = Bun.serve({ port, fetch: () => new Response() })
+    probe.stop(true)
+  } catch {
+    printErr(`[cli] Port ${port} is already in use; start on another port with --port <N>`)
+    process.exit(1)
+  }
+}
+
 export async function startServer() {
   let flux = requireBinary("flux")
+  requireFreePort(DEV_PORT)
   let script = await bundleServer()
 
   let lanAddress = Object.values(networkInterfaces())