@solidrt/cli 0.0.27 → 0.0.28

package/package.json

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

package/scaffold/AGENTS.md

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

package/scaffold/package.json

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

package/scaffold/templates/components/index.tsx

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

package/scaffold/templates/components/template.json

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

package/scaffold/templates/default/index.tsx

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

package/scaffold/templates/default/template.json

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

package/scaffold/templates/gallery/template.json

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

package/scaffold/templates/minimal/index.tsx

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

package/scaffold/templates/minimal/template.json

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

package/scaffold/tsconfig.json

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

package/server/control.ts

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

package/server/state.ts

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

package/src/args.ts

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

package/src/commands/check.ts

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { source } from "../args"
+import { bundleWith } from "../bundler"
+
+// srt check: verify the app without side effects. Bundles in memory (nothing
+// written, so no dev-server reload fires and no build outputs land in the
+// project) and typechecks with the project's own tsc, reporting only
+// diagnostics in app code. @solidrt packages ship raw .ts sources, so a strict
+// consumer config surfaces their internal errors too; those are counted and
+// hidden, not the caller's problem to wade through.
+
+// Walk up from the entry to the enclosing project (tsconfig.json or, failing
+// that, package.json).
+function findProjectRoot(entry: string): string | null {
+  let dir = dirname(resolve(entry))
+  let byConfig: string | null = null
+  let byPackage: string | null = null
+  while (true) {
+    if (!byConfig && existsSync(join(dir, "tsconfig.json"))) byConfig = dir
+    if (!byPackage && existsSync(join(dir, "package.json"))) byPackage = dir
+    let parent = dirname(dir)
+    if (parent === dir) return byConfig ?? byPackage
+    dir = parent
+  }
+}
+
+// One tsc --pretty false diagnostic: the "path(line,col): error TS...: ..."
+// head line plus any indented continuation lines.
+type Diagnostic = { head: string; lines: string[]; inDependencies: boolean }
+
+function parseDiagnostics(output: string): Diagnostic[] {
+  let diagnostics: Diagnostic[] = []
+  let current: Diagnostic | null = null
+  for (let line of output.split("\n")) {
+    let head = /^(.*?)\(\d+,\d+\): (error|warning) TS\d+: /.exec(line) ?? /^(error|warning) TS\d+: /.exec(line)
+    if (head) {
+      let file = line.includes("): ") ? head[1]! : ""
+      current = { head: line, lines: [line], inDependencies: file.includes("node_modules") }
+      diagnostics.push(current)
+    } else if (current && line.trim() !== "") {
+      current.lines.push(line)
+    }
+  }
+  return diagnostics
+}
+
+async function typecheck(root: string): Promise<{ app: Diagnostic[]; hidden: number } | null> {
+  let tsc = join(root, "node_modules", ".bin", process.platform === "win32" ? "tsc.exe" : "tsc")
+  if (!existsSync(tsc)) {
+    console.warn("Typecheck skipped: no tsc in the project (add the typescript devDependency)")
+    return null
+  }
+  let proc = Bun.spawn([tsc, "--noEmit", "--pretty", "false"], { cwd: root, stdout: "pipe", stderr: "pipe" })
+  let [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()])
+  await proc.exited
+  let diagnostics = parseDiagnostics(out + err)
+  let app = diagnostics.filter((d) => !d.inDependencies)
+  return { app, hidden: diagnostics.length - app.length }
+}
+
+export async function runCheckCommand() {
+  let entry = source!
+  let failed = false
+
+  let result = await bundleWith({ entry, dev: true, minify: false })
+  if (!result) {
+    // bundleWith already printed the compile errors.
+    failed = true
+  }
+
+  let root = findProjectRoot(entry)
+  if (!root) {
+    console.warn("Typecheck skipped: no tsconfig.json or package.json above the entry")
+  } else {
+    let types = await typecheck(root)
+    if (types) {
+      for (let d of types.app) console.error(d.lines.join("\n"))
+      if (types.app.length > 0) {
+        failed = true
+        let hidden = types.hidden > 0 ? ` (${types.hidden} in dependencies hidden)` : ""
+        console.error(`${types.app.length} type error${types.app.length === 1 ? "" : "s"} in app code${hidden}`)
+      } else if (types.hidden > 0) {
+        console.log(`Types OK (${types.hidden} dependency-internal errors hidden)`)
+      } else {
+        console.log("Types OK")
+      }
+    }
+  }
+
+  if (failed) process.exit(1)
+  console.log("Check passed")
+  process.exit(0)
+}

package/src/commands/init.ts

@@ -29,23 +29,48 @@ function packageName(dir: string): string {
 }
 
 const DEFAULT_TEMPLATE = "default"
+const TEMPLATE_MANIFEST = "template.json"
+
+// Each template's template.json declares which level the scaffolded app is
+// written at: "core" (only @solidrt/core, no component framework) or
+// "components" (built with @solidrt/components). The level decides the
+// generated dependencies; the description labels the template in the picker.
+interface TemplateInfo {
+  name: string
+  level: "core" | "components"
+  description: string
+}
 
 // Templates are the directories under scaffold/templates/; each holds the files
-// that become the new project's src/. `default` sorts first as the starting
-// point, the rest alphabetically.
-async function listTemplates(): Promise<string[]> {
+// that become the new project's src/, plus a template.json manifest. `default`
+// sorts first as the starting point, the rest alphabetically.
+async function listTemplates(): Promise<TemplateInfo[]> {
   let entries = await readdir(TEMPLATES_DIR, { withFileTypes: true })
-  return entries
+  let names = entries
     .filter((e) => e.isDirectory())
     .map((e) => e.name)
     .sort((a, b) =>
       a === DEFAULT_TEMPLATE ? -1 : b === DEFAULT_TEMPLATE ? 1 : a.localeCompare(b),
     )
+  let templates: TemplateInfo[] = []
+  for (let name of names) {
+    // A missing manifest falls back to the components level: it keeps every
+    // dependency, so the scaffolded app works at either level.
+    let manifest = await readFile(join(TEMPLATES_DIR, name, TEMPLATE_MANIFEST), "utf8")
+      .then((raw) => JSON.parse(raw))
+      .catch(() => ({}))
+    templates.push({
+      name,
+      level: manifest.level === "core" ? "core" : "components",
+      description: typeof manifest.description === "string" ? manifest.description : "",
+    })
+  }
+  return templates
 }
 
 // Resolve which template to scaffold from: an explicit --template if valid, an
 // interactive picker on a TTY, else `default` (or the first available).
-async function resolveTemplate(): Promise<string> {
+async function resolveTemplate(): Promise<TemplateInfo> {
   let templates = await listTemplates()
   if (templates.length === 0) {
     console.error(`!! No templates found in ${TEMPLATES_DIR}`)
@@ -53,14 +78,25 @@ async function resolveTemplate(): Promise<string> {
   }
   let chosen = values.template
   if (chosen) {
-    if (!templates.includes(chosen)) {
-      console.error(`!! Unknown template "${chosen}"; choose from: ${templates.join(", ")}`)
+    let found = templates.find((t) => t.name === chosen)
+    if (!found) {
+      let names = templates.map((t) => t.name).join(", ")
+      console.error(`!! Unknown template "${chosen}"; choose from: ${names}`)
       process.exit(1)
     }
-    return chosen
+    return found
+  }
+  if (process.stdin.isTTY) {
+    let picked = await select(
+      "Select a template",
+      templates.map((t) => ({
+        label: t.description ? `${t.name} - ${t.description}` : t.name,
+        value: t.name,
+      })),
+    )
+    return templates.find((t) => t.name === picked)!
   }
-  if (process.stdin.isTTY) return select("Select a template", templates)
-  return templates.includes(DEFAULT_TEMPLATE) ? DEFAULT_TEMPLATE : templates[0]!
+  return templates.find((t) => t.name === DEFAULT_TEMPLATE) ?? templates[0]!
 }
 
 export async function runInitCommand() {
@@ -84,7 +120,7 @@ export async function runInitCommand() {
 
   let template = await resolveTemplate()
 
-  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${template})`)
+  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${template.name})`)
   for (let { from, to } of TEMPLATE_FILES) {
     let dest = join(dir, to)
     await mkdir(dirname(dest), { recursive: true })
@@ -93,19 +129,22 @@ export async function runInitCommand() {
   }
 
   // The chosen template's files become the project's src/. Entries may be
-  // nested directories (e.g. an asset folder), so copy recursively.
-  let templateDir = join(TEMPLATES_DIR, template)
+  // nested directories (e.g. an asset folder), so copy recursively. The
+  // manifest describes the template rather than belonging to the app.
+  let templateDir = join(TEMPLATES_DIR, template.name)
   await mkdir(join(dir, "src"), { recursive: true })
   for (let file of await readdir(templateDir)) {
+    if (file === TEMPLATE_MANIFEST) continue
     await cp(join(templateDir, file), join(dir, "src", file), { recursive: true })
     console.log(`   Write src/${file}`)
   }
 
   // The scaffold package.json carries a placeholder name; set it from the
-  // target folder.
+  // target folder. A core-level app gets no component framework dependency.
   let pkgPath = join(dir, "package.json")
   let pkg = JSON.parse(await readFile(pkgPath, "utf8"))
   pkg.name = packageName(dir)
+  if (template.level === "core") delete pkg.dependencies["@solidrt/components"]
   await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n")
 
   // Deps are declared in scaffold/package.json (Solid peers resolve via

package/src/commands/mcp.ts

@@ -9,6 +9,7 @@ import { z } from "zod"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js"
+import { resolve } from "node:path"
 import { DEV_PORT } from "../dev-server"
 
 const CONTROL_BASE = `http://127.0.0.1:${DEV_PORT}/__control__`
@@ -44,17 +45,24 @@ let CLIENT_ARG = z
   .describe("Client id from list_clients (default: the only connected client)")
   .optional()
 
+let SAVE_TO_ARG = z
+  .string()
+  .describe(
+    "Also write the PNG to this file path (relative paths resolve against the project root; parent directories are created)",
+  )
+  .optional()
+
 let TOOLS: { name: string; description: string; inputSchema: Record<string, z.ZodTypeAny> }[] = [
   {
     name: "list_clients",
     description:
-      "List the app clients connected to the SolidRT dev server. 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) 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.",
     inputSchema: {},
   },
   {
     name: "get_logs",
     description:
-      "Read console output and runtime errors from connected app clients. Returns entries (seq, at, client, level, text) plus `latest`, the newest seq. Pass `since` (a seq or `latest` from a previous call) to only get newer entries; pass `wait_ms` to hold the call until new output arrives, e.g. right after triggering a reload.",
+      "Read console output and runtime errors from connected app clients. Returns entries (seq, at, client, level, text; consecutive identical entries are collapsed into one with a `repeats` count and the run's last seq), plus `latest` (the newest seq) and `generation` (identity of this server run; if it changed since your last call, your seq cursor and client ids are stale - start over from since 0). Pass `since` (a seq or `latest` from a previous call) to only get newer entries; pass `wait_ms` to hold the call until new output arrives, e.g. right after triggering a reload; pass `level`/`contains` to filter, e.g. level \"error\" to skip chatty output.",
     inputSchema: {
       since: z
         .number()
@@ -64,28 +72,57 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
       wait_ms: z
         .number()
         .int()
-        .describe("If nothing is newer than `since`, wait up to this many milliseconds for new output (max 30000)")
+        .describe("If nothing matches newer than `since`, wait up to this many milliseconds for new output (max 30000)")
+        .optional(),
+      level: z
+        .string()
+        .describe('Only return entries with one of these levels, comma-separated (e.g. "error" or "error,warn")')
+        .optional(),
+      contains: z
+        .string()
+        .describe("Only return entries whose text contains this substring (case-insensitive)")
         .optional(),
     },
   },
   {
     name: "get_stats",
     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.",
+      "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), 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).",
     inputSchema: { client: CLIENT_ARG },
   },
   {
     name: "get_render_tree",
     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.",
-    inputSchema: { client: CLIENT_ARG },
+      "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>.",
+    inputSchema: {
+      root: z
+        .number()
+        .int()
+        .describe("Only return the subtree under this node id (default: the whole tree)")
+        .optional(),
+      depth: z
+        .number()
+        .int()
+        .describe("Levels of children to include below the root (default: unlimited; 0 = the root node only)")
+        .optional(),
+      query: z
+        .string()
+        .describe(
+          "Search instead of snapshot: return `matches`, nodes whose kind equals or text contains this " +
+            "(case-insensitive), each with a `path` of ancestor ids from the search root. Combine with `root` to " +
+            "scope the search; `depth` is ignored.",
+        )
+        .optional(),
+      client: CLIENT_ARG,
+    },
   },
   {
     name: "get_snapshot",
     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. The node must be currently mounted and have a non-zero layout box.",
+      "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. 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.",
     inputSchema: {
       nodeId: z.number().int().describe("Id of the node to capture, from get_render_tree"),
+      save_to: SAVE_TO_ARG,
       client: CLIENT_ARG,
     },
   },
@@ -105,6 +142,7 @@ let TOOLS: { name: string; description: string; inputSchema: Record<string, z.Zo
       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(),
+      save_to: SAVE_TO_ARG,
       client: CLIENT_ARG,
     },
   },
@@ -156,13 +194,22 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
       let params = new URLSearchParams()
       if (typeof args?.since === "number") params.set("since", String(args.since))
       if (typeof args?.wait_ms === "number") params.set("wait", String(args.wait_ms))
+      if (typeof args?.level === "string") params.set("level", args.level)
+      if (typeof args?.contains === "string") params.set("contains", args.contains)
       let qs = params.toString()
       return control(qs ? `/logs?${qs}` : "/logs")
     }
     case "get_stats":
       return control(`/stats${clientParam(args)}`)
-    case "get_render_tree":
-      return control(`/tree${clientParam(args)}`)
+    case "get_render_tree": {
+      let params = new URLSearchParams()
+      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 (typeof args?.client === "number") params.set("client", String(args.client))
+      let qs = params.toString()
+      return control(qs ? `/tree?${qs}` : "/tree")
+    }
     case "reload":
       return control("/reload", "POST")
     case "get_snapshot": {
@@ -204,15 +251,29 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
   }
 }
 
-function toContent(name: string, result: ControlResult): CallToolResult {
+async function toContent(name: string, result: ControlResult, args?: any): Promise<CallToolResult> {
   if (!result.ok) return { content: [{ type: "text", text: result.message }], isError: true }
   if (name === "get_snapshot" || name === "get_texture") {
     let { pngBase64, width, height } = result.body
     let label = name === "get_snapshot" ? "Captured node snapshot" : "Texture contents"
+    let text = `${label}: ${width}x${height} px`
+    // save_to is handled here in the bridge, not by the dev server: this
+    // process runs on the caller's machine, so the path lands where the
+    // agent expects it. The image content block alone is a dead end for
+    // that - the model sees the pixels but never the bytes.
+    if (typeof args?.save_to === "string") {
+      let path = resolve(args.save_to)
+      try {
+        await Bun.write(path, Buffer.from(pngBase64, "base64"))
+        text += `, saved to ${path}`
+      } catch (e) {
+        return { content: [{ type: "text", text: `Captured, but saving to ${path} failed: ${e}` }], isError: true }
+      }
+    }
     return {
       content: [
         { type: "image", data: pngBase64, mimeType: "image/png" },
-        { type: "text", text: `${label}: ${width}x${height} px` },
+        { type: "text", text },
       ],
     }
   }
@@ -226,7 +287,7 @@ export async function runMcpCommand() {
     server.registerTool(
       tool.name,
       { description: tool.description, inputSchema: tool.inputSchema },
-      async (args: any) => toContent(tool.name, await callTool(tool.name, args ?? {})),
+      async (args: any) => toContent(tool.name, await callTool(tool.name, args ?? {}), args),
     )
   }
 

package/src/main.ts

@@ -3,6 +3,7 @@
 import { values, command, validateArgs, printUsage } from "./args"
 import { runInitCommand } from "./commands/init"
 import { runBundleCommand } from "./commands/bundle"
+import { runCheckCommand } from "./commands/check"
 import { runPackCommand } from "./commands/pack"
 import { runRenderCommand } from "./commands/render"
 import { runServerCommand } from "./commands/server"
@@ -41,6 +42,8 @@ if (command === "init") {
   await runInitCommand()
 } else if (command === "bundle") {
   await runBundleCommand()
+} else if (command === "check") {
+  await runCheckCommand()
 } else if (command === "pack") {
   await runPackCommand()
 } else if (command === "render") {

package/src/prompt.ts

@@ -15,16 +15,24 @@ export function text(message: string, def = ""): Promise<string> {
   })
 }
 
+export interface SelectOption {
+  label: string
+  value: string
+}
+
 // Minimal arrow-key single-select prompt, built on node:readline (same
 // dependency-free approach as repl.ts). Renders the option list, moves the
-// highlight on up/down, resolves the chosen value on enter. Callers guard on
-// process.stdin.isTTY; a non-TTY stdin here resolves the first option rather
-// than hanging on input that will never arrive.
-export function select(message: string, options: string[]): Promise<string> {
+// highlight on up/down, resolves the chosen value on enter. Options are plain
+// strings or { label, value } pairs when the display text differs from the
+// resolved value. Callers guard on process.stdin.isTTY; a non-TTY stdin here
+// resolves the first option rather than hanging on input that will never
+// arrive.
+export function select(message: string, options: Array<string | SelectOption>): Promise<string> {
+  let items = options.map((o) => (typeof o === "string" ? { label: o, value: o } : o))
   return new Promise((resolve) => {
     let input = process.stdin
     let output = process.stdout
-    if (!input.isTTY) return resolve(options[0]!)
+    if (!input.isTTY) return resolve(items[0]!.value)
 
     let selected = 0
     emitKeypressEvents(input)
@@ -34,13 +42,13 @@ export function select(message: string, options: string[]): Promise<string> {
     let render = (first = false) => {
       // After the first paint the cursor sits below the block; move it back up
       // to the message line so the list redraws in place.
-      if (!first) output.write(`\x1b[${options.length + 1}A`)
+      if (!first) output.write(`\x1b[${items.length + 1}A`)
       output.write(`\x1b[K? ${message}\n`)
-      for (let i = 0; i < options.length; i++) {
+      for (let i = 0; i < items.length; i++) {
         let active = i === selected
         let pointer = active ? "\x1b[36m> " : "  "
         let reset = active ? "\x1b[0m" : ""
-        output.write(`\x1b[K${pointer}${options[i]}${reset}\n`)
+        output.write(`\x1b[K${pointer}${items[i]!.label}${reset}\n`)
       }
     }
 
@@ -53,15 +61,15 @@ export function select(message: string, options: string[]): Promise<string> {
     let onKey = (_str: string, key: { name: string; ctrl: boolean } | undefined) => {
       if (!key) return
       if (key.name === "up") {
-        selected = (selected - 1 + options.length) % options.length
+        selected = (selected - 1 + items.length) % items.length
         render()
       } else if (key.name === "down") {
-        selected = (selected + 1) % options.length
+        selected = (selected + 1) % items.length
         render()
       } else if (key.name === "return" || key.name === "enter") {
         cleanup()
         output.write("\n")
-        resolve(options[selected]!)
+        resolve(items[selected]!.value)
       } else if (key.ctrl && (key.name === "c" || key.name === "d")) {
         cleanup()
         output.write("\n")