@solidrt/cli 0.0.49 → 0.0.51

package/src/commands/bundle.ts

@@ -1,6 +1,17 @@
 import { values, source, isPrebuilt } from "../args"
-import { bundle, bundleTo, bundleFlux, compileToBytecode } from "../bundler"
-import { resolve } from "path"
+import {
+  bundleFlux,
+  bundleIsolatesDir,
+  bundleSolid,
+  compileToBytecode,
+  findFluxIsolates,
+  readPrebuiltIsolates,
+  walkFiles,
+  writeIsolates,
+} from "../bundler"
+import { projectDirFor } from "../project"
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
 
 // Write to stdout and resolve only once the whole payload is flushed.
 // process.stdout.write to a pipe is async and applies backpressure; the
@@ -11,7 +22,41 @@ function writeStdout(data: string): Promise<void> {
   })
 }
 
-// Compile JS to a .srt.bin file and report its size.
+// The bundle output dir (okf/backlog/build-output-dirs.md): the bundle flow's
+// subdir of the build root, or an explicit --output dir. Only reused when it
+// is empty or already a bundle output (a *.srt.* or *.flux.* bundle at top
+// level) - the writePackFolder rule - so it never writes into an unrelated
+// directory.
+function ensureOutDir(entry: string): string {
+  let outDir = values.output ?? join(projectDirFor(entry), "dist", "bundle")
+  let existing = existsSync(outDir) ? readdirSync(outDir) : null
+  if (existing && existing.length > 0 && !existing.some((name) => /\.(srt|flux)\.(js|bin)$/.test(name))) {
+    console.error(`${resolve(outDir)} exists and is not a bundle output; choose another --output`)
+    process.exit(1)
+  }
+  mkdirSync(outDir, { recursive: true })
+  return outDir
+}
+
+// Clear one form's files from the output's isolates/ dir before rewriting it,
+// so removed modules cannot go stale. The dir is shared by a bundle's .js and
+// .bin forms, so only the form being rewritten is cleared - a --compile must
+// not delete the .js set the .js bundle pairs with, nor the reverse.
+function clearIsolates(dir: string, ext: ".js" | ".bin") {
+  walkFiles(dir, (abs) => {
+    if (abs.endsWith(ext)) rmSync(abs)
+  })
+}
+
+// Compile one isolate bundle to `<dir>/<id>.bin` (module name = its id, for
+// stack attribution).
+async function writeIsolateBytecode(dir: string, isolate: { id: string; code: string }) {
+  let outfile = join(dir, isolate.id + ".bin")
+  mkdirSync(dirname(outfile), { recursive: true })
+  await Bun.write(outfile, await compileToBytecode(isolate.code, isolate.id))
+}
+
+// Compile JS to a bytecode file and report its size.
 async function writeBytecode(jsCode: string, outfile: string) {
   let bytecode = await compileToBytecode(jsCode)
   await Bun.write(outfile, bytecode)
@@ -21,18 +66,47 @@ async function writeBytecode(jsCode: string, outfile: string) {
 
 export async function runBundleCommand() {
   if (values.flux) {
-    let baseName = values.output ?? source!.replace(/\.[jt]s$/, "")
-    let jsCode = await bundleFlux(source!)
+    let entry = resolve(source!)
+    let name = basename(entry).replace(/\.[jt]s$/, "")
+    let jsCode = await bundleFlux(entry)
+    // Standalone flux resolves isolates by location, not directive: module
+    // <id> is <entry dir>/isolates/<id>.js. Bundling keeps that shape - every
+    // module under the entry's isolates/ dir is built bare like the entry
+    // (which also lets a worker be .ts, unlike running from source) and lands
+    // as isolates/<id>.js next to the bundle.
+    let isolateModules = findFluxIsolates(dirname(entry))
 
     if (values.stdout) {
+      if (isolateModules.length) {
+        console.error("[cli] Warning: this script has isolate modules; --stdout carries only the main bundle")
+      }
       await writeStdout(jsCode)
-    } else if (values.compile) {
-      await writeBytecode(jsCode, baseName + ".flux.bin")
+      process.exit()
+    }
+    let outDir = ensureOutDir(entry)
+    if (values.compile) {
+      await writeBytecode(jsCode, join(outDir, name + ".flux.bin"))
     } else {
-      let outfile = baseName + ".flux.js"
+      let outfile = join(outDir, name + ".flux.js")
       await Bun.write(outfile, jsCode)
       console.log(`>> wrote ${jsCode.length} bytes to ${outfile}`)
     }
+    // Isolates follow the main bundle's form: source beside a .flux.js,
+    // bytecode beside a .flux.bin (the flux resolver reads .bin first).
+    let isolatesDir = join(outDir, "isolates")
+    if (values.compile) {
+      clearIsolates(isolatesDir, ".bin")
+      for (let module of isolateModules) {
+        await writeIsolateBytecode(isolatesDir, { id: module.id, code: await bundleFlux(module.path) })
+      }
+    } else {
+      clearIsolates(isolatesDir, ".js")
+      for (let module of isolateModules) {
+        let file = join(isolatesDir, module.id + ".js")
+        mkdirSync(dirname(file), { recursive: true })
+        await Bun.write(file, await bundleFlux(module.path))
+      }
+    }
     process.exit()
   }
 
@@ -44,33 +118,44 @@ export async function runBundleCommand() {
     let jsFile = resolve(source!)
     let binOut = jsFile.replace(/\.srt\.js$/, ".srt.bin").replace(/\.js$/, ".bin")
     await writeBytecode(await Bun.file(jsFile).text(), binOut)
+    // The isolate bundles compile along, .bin beside .js in the output's
+    // isolates/ dir (the ids match, the extension picks the form).
+    for (let isolate of readPrebuiltIsolates(jsFile)) {
+      await writeIsolateBytecode(bundleIsolatesDir(jsFile), isolate)
+    }
     process.exit()
   }
 
-  let baseName = values.output ?? source!.replace(/\.[jt]sx?$/, "")
+  let entry = resolve(source!)
+  let name = basename(entry).replace(/\.[jt]sx?$/, "")
 
   if (values.stdout) {
-    let result = await bundle()
-    if (!result) {
-      console.error("Build failed")
-      process.exit(1)
+    let result = await bundleSolid()
+    if (result.isolates.length) {
+      console.error("[cli] Warning: this app has isolate modules; --stdout carries only the main bundle")
     }
     await writeStdout(result.code)
     process.exit()
   }
 
+  let outDir = ensureOutDir(entry)
+  let isolatesDir = join(outDir, "isolates")
+
   if (values.compile) {
-    let result = await bundle()
-    if (!result) {
-      console.error("Build failed")
-      process.exit(1)
+    let result = await bundleSolid()
+    await writeBytecode(result.code, join(outDir, name + ".srt.bin"))
+    clearIsolates(isolatesDir, ".bin")
+    for (let isolate of result.isolates) {
+      await writeIsolateBytecode(isolatesDir, isolate)
     }
-    await writeBytecode(result.code, baseName + ".srt.bin")
     process.exit()
   }
 
-  let jsOutfile = baseName + ".srt.js"
-  let result = await bundleTo(jsOutfile)
+  let result = await bundleSolid()
+  let jsOutfile = join(outDir, name + ".srt.js")
+  await Bun.write(jsOutfile, result.code)
+  clearIsolates(isolatesDir, ".js")
+  writeIsolates(isolatesDir, result.isolates)
   console.log(`>> wrote ${result.code.length} bytes to ${jsOutfile}`)
   process.exit()
-}
+}

package/src/commands/check.ts

@@ -128,6 +128,13 @@ export function reportTypes(
 
 export async function runCheckCommand() {
   let entry = source!
+  if (!existsSync(entry)) {
+    // Without this, the missing file surfaces later as an internal ENOENT
+    // stack trace (scandir/Bun.build), which reads as a CLI bug - the common
+    // cause is just running from the wrong directory.
+    console.error(`No such entry: ${entry} (resolved from ${process.cwd()})`)
+    process.exit(1)
+  }
   let failed = false
 
   let result = await bundleWith({ entry, dev: true, minify: false })

package/src/commands/init.ts

@@ -1,7 +1,7 @@
 import { cp, mkdir, readFile, readdir, writeFile } from "node:fs/promises"
 import { basename, dirname, join, resolve } from "node:path"
 import { source, values } from "../args"
-import { select, text } from "../prompt"
+import { multiselect, note, text } from "../prompt"
 
 const DEFAULT_NAME = "solidrt-app"
 
@@ -29,76 +29,55 @@ 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"
+
+// One AGENTS.md serves every template, so the lines that point an agent at
+// @solidrt/components docs are fenced between markers: with the extension
+// selected only the markers go, without it the block goes too, so a core-only
+// app never ships references to files that are not installed.
+const MARKED_BLOCK = /^<!-- components:begin -->\n[\s\S]*?^<!-- components:end -->\n/gm
+const MARKER = /^<!-- components:(?:begin|end) -->\n/gm
+
+function resolveMarkers(text: string, extensions: Extension[]): string {
+  let selected = extensions.some((e) => e.pkg === "@solidrt/components")
+  return selected ? text.replace(MARKER, "") : text.replace(MARKED_BLOCK, "")
+}
+
+// Optional packages an app can opt into on top of core. Each maps to a
+// dependency in the scaffold package.json (kept when selected, removed
+// otherwise) and optionally to a starter under scaffold/templates/.
+interface Extension {
+  pkg: string
+  template?: string
   description: string
 }
 
-// Templates are the directories under scaffold/templates/; each holds the files
-// 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 })
-  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
+const EXTENSIONS: Extension[] = [
+  {
+    pkg: "@solidrt/components",
+    template: "components",
+    description: "component framework: widgets, theming, navigation",
+  },
+  { pkg: "@solidrt/3d", description: "general purpose 3D library" },
+]
+
+// Resolve which extensions the app takes: an interactive picker on a TTY,
+// else none (core only). Extensions are ordinary dependencies, so a script
+// adds them afterwards with `bun add`.
+async function resolveExtensions(): Promise<Extension[]> {
+  if (!process.stdin.isTTY) return []
+  // Core is the runtime every app has, so it is not a choice.
+  note("@solidrt/core is always included", "Packages")
+  let picked = await multiselect(
+    "Select extensions",
+    EXTENSIONS.map((e) => ({ label: `${e.pkg} - ${e.description}`, value: e.pkg })),
+  )
+  return EXTENSIONS.filter((e) => picked.includes(e.pkg))
 }
 
-// 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<TemplateInfo> {
-  let templates = await listTemplates()
-  if (templates.length === 0) {
-    console.error(`!! No templates found in ${TEMPLATES_DIR}`)
-    process.exit(1)
-  }
-  let chosen = values.template
-  if (chosen) {
-    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 found
-  }
-  if (process.stdin.isTTY) {
-    let picked = await select(
-      "Select a template",
-      templates.map((t) => {
-        // Core is the runtime every app has; anything else is a package the
-        // app opts into, so the picker marks it as such.
-        let name = t.level === "core" ? t.name : `${t.name} (extension)`
-        return { label: t.description ? `${name} - ${t.description}` : name, value: t.name }
-      }),
-    )
-    return templates.find((t) => t.name === picked)!
-  }
-  return templates.find((t) => t.name === DEFAULT_TEMPLATE) ?? templates[0]!
+// The starter src/ comes from the first selected extension that brings a
+// template; with none, the core `default` starter.
+function resolveTemplate(extensions: Extension[]): string {
+  return extensions.find((e) => e.template)?.template ?? DEFAULT_TEMPLATE
 }
 
 export async function runInitCommand() {
@@ -120,23 +99,25 @@ export async function runInitCommand() {
     process.exit(1)
   }
 
-  let template = await resolveTemplate()
+  let extensions = await resolveExtensions()
+  let template = resolveTemplate(extensions)
+  let summary = ["@solidrt/core", ...extensions.map((e) => e.pkg)].join(", ")
 
-  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${template.name})`)
+  console.log(`>> Scaffolding SolidRT project in ${resolve(dir)} (${summary})`)
   for (let { from, to } of TEMPLATE_FILES) {
     let dest = join(dir, to)
     await mkdir(dirname(dest), { recursive: true })
-    await writeFile(dest, await readFile(join(SCAFFOLD_DIR, from)))
+    let body: string | Buffer = await readFile(join(SCAFFOLD_DIR, from))
+    if (to === "AGENTS.md") body = resolveMarkers(body.toString("utf8"), extensions)
+    await writeFile(dest, body)
     console.log(`   Write ${to}`)
   }
 
-  // The chosen template's files become the project's src/. Entries may be
-  // 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)
+  // The 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)
   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}`)
   }
@@ -149,12 +130,15 @@ export async function runInitCommand() {
   await writeFile(join(dir, "assets", "icon.svg"), await readFile(join(SCAFFOLD_DIR, "icon.svg")))
   console.log("   Write assets/icon.svg")
 
-  // The scaffold package.json carries a placeholder name; set it from the
-  // target folder. A core-level app gets no component framework dependency.
+  // The scaffold package.json carries a placeholder name and every extension
+  // dependency; set the name from the target folder and keep only the
+  // selected extensions.
   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"]
+  for (let ext of EXTENSIONS) {
+    if (!extensions.includes(ext)) delete pkg.dependencies[ext.pkg]
+  }
   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

@@ -10,8 +10,8 @@ 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 { dirname, join, resolve } from "node:path"
-import { existsSync, readdirSync, readFileSync } from "node:fs"
-import { values } from "../args"
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs"
+import { values, DEFAULT_DEV_PORT } from "../args"
 import { DEV_PORT } from "../dev-server"
 import { devDir } from "../dev-dir"
 
@@ -35,12 +35,30 @@ function findProjectDir(): string | null {
   }
 }
 
+// The two sides of a projectDir comparison come from different processes
+// (the server's entry path, the bridge's cwd) and only agree by construction
+// on the directory, not the spelling: an editor-spawned bridge on Windows
+// keeps its parent's lower-case drive letter while a shell writes it upper
+// case, and 8.3 names, symlinks and subst drives are the same class. Compare
+// the canonical path, so the spelling never decides.
+function sameDir(a: string, b: string): boolean {
+  if (a === b) return true
+  try {
+    return realpathSync.native(a) === realpathSync.native(b)
+  } catch {
+    return false
+  }
+}
+
+// Only ESRCH means the process is gone. EPERM is a live process this bridge
+// may not signal (Windows reports it for other users' processes), and a
+// bare try/catch would drop that healthy server from the registry.
 function pidAlive(pid: number): boolean {
   try {
     process.kill(pid, 0)
     return true
-  } catch {
-    return false
+  } catch (e: any) {
+    return e?.code === "EPERM"
   }
 }
 
@@ -80,7 +98,8 @@ async function resolvePort(): Promise<PortResult> {
       message: `No package.json found above ${process.cwd()}, so no dev server can be resolved by project. Pass -s <N> or --port <N> to srt mcp.`,
     }
   }
-  let matches = liveRecords().filter((r) => r.projectDir === project && pidAlive(r.pid))
+  let records = liveRecords()
+  let matches = records.filter((r) => sameDir(r.projectDir, project) && pidAlive(r.pid))
   if (matches.length > 1) {
     let ports = matches
       .map((r) => r.port)
@@ -89,7 +108,25 @@ async function resolvePort(): Promise<PortResult> {
     return { ok: false, message: `${matches.length} dev servers are serving this project (ports ${ports}); pass -s <N> to srt mcp` }
   }
   if (matches.length === 0) {
-    return { ok: false, message: `No dev server for ${project}. Start one with srt run, or pass -s <N> to srt mcp.` }
+    // A lookup by key that fails against a small table prints the table: an
+    // empty registry, a dead pid and a record for another project are three
+    // different problems, and the reader can only tell them apart if the
+    // candidates are listed next to the key that was looked up.
+    let listing =
+      records.length === 0
+        ? `Registry ${devDir("servers")}: no records.`
+        : `Registry ${devDir("servers")}: ${records.length} record(s).\n` +
+          records
+            .map((r) => {
+              let session = r.port - DEFAULT_DEV_PORT
+              let flag = session >= 0 && session < 100 ? `-s ${session}` : `--port ${r.port}`
+              return `  port ${r.port} (${flag})  pid ${r.pid} (${pidAlive(r.pid) ? "alive" : "dead"})  serving ${r.projectDir}`
+            })
+            .join("\n")
+    return {
+      ok: false,
+      message: `No dev server for ${project}.\n${listing}\nStart one with srt run, or pin one of the servers above by passing its flag to srt mcp.`,
+    }
   }
   let port = matches[0]!.port
   // The record is a hint; the server is authoritative. The probe catches a
@@ -97,7 +134,7 @@ async function resolvePort(): Promise<PortResult> {
   try {
     let probe = await fetch(`http://127.0.0.1:${port}/__control__/clients`)
     let body: any = await probe.json().catch(() => null)
-    if (!probe.ok || body?.projectDir !== project) {
+    if (!probe.ok || typeof body?.projectDir !== "string" || !sameDir(body.projectDir, project)) {
       return {
         ok: false,
         message: `The server on port ${port} is not serving ${project}${
@@ -206,8 +243,17 @@ 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), 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 },
+      "Performance statistics from a running app client. Start with `window`: a summary of the frames rebuilt in the last window_ms (default 5000, max 10000) - frames, p50Ms/p95Ms/maxMs of the JS-thread critical path per frame (render handler + layout + postLayout + paint + hover), slowFrames (frames over the refresh period, periodMs), and `worst`, the single most expensive frame with its ageMs, phase breakdown (jsMs/layoutMs/postLayoutMs/paintMs/hoverMs) and that frame's own layout activity (paraShapes, measureCalls, dirtiedNodes, cacheGets/cacheHits, nodesPainted). This is where jank shows: the smoothed figures below average a one-frame hitch away, the window keeps it. Typical flow: send_input a burst (typing, a drag), then get_stats - `frames: 0` means nothing was rebuilt in the window (idle app), which is different from all-fast. The window also carries rates for the GPU counters when it spans 2+ frames: fenceTimeoutsPerSec, gpuPassesPerFrame (per presented frame), gpuPassMsPerFrame, rasterCmdMsPerSec - read these instead of differencing the cumulatives yourself. timeMs (client monotonic clock) and frame (present index) stamp the payload so two samples can be differenced. Then the smoothed figures: 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, i.e. words the shared word cache did not have; the expensive signal - high layoutMs with near-zero paraShapes means the cost is not text shaping), wordHits (words answered from the shared word cache; hits high and paraShapes near zero on a text change means only the changed words were reshaped), 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), nodesPainted (nodes the last paint walk entered; mountedNodes minus this is what viewport culling skipped - a long scroller should paint a near-constant number of nodes however long its content). GPU-side health, read live at query time (absent when no engine is running): rasterQueue (raster commands sent but not yet executed at the instant of the query, including the one executing; the frame command blocks on vsync in it, so 1 while frames flow is normal - it is a backlog signal only when it climbs across queries while fps drops; a persistently high idle reading has been seen once on a Windows client and is unexplained, so do not conclude from this field alone), 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: {
+      window_ms: z
+        .number()
+        .int()
+        .min(0)
+        .max(10000)
+        .describe("How far back the window summary looks, in ms (default 5000, max 10000)")
+        .optional(),
+      client: CLIENT_ARG,
+    },
   },
   {
     name: "get_render_tree",
@@ -352,7 +398,7 @@ let TOOLS: {
     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.",
+      "Control a running app client's clock. scale=0 freezes app time: onFrame/requestAnimationFrame stop being delivered, setTimeout/setInterval freeze, and the picture stops (performance.now() and Date.now() keep running: they are real time, not the frame timeline, so only animations driven off the onFrame tick pause) - 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. 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()
@@ -431,8 +477,13 @@ async function callTool(name: string, args: any): Promise<ControlResult> {
       let qs = params.toString()
       return control(qs ? `/logs?${qs}` : "/logs")
     }
-    case "get_stats":
-      return control(`/stats${clientParam(args)}`)
+    case "get_stats": {
+      let params = new URLSearchParams()
+      if (typeof args?.window_ms === "number") params.set("window", String(args.window_ms))
+      if (typeof args?.client === "number") params.set("client", String(args.client))
+      let qs = params.toString()
+      return control(qs ? `/stats?${qs}` : "/stats")
+    }
     case "get_render_tree": {
       let params = new URLSearchParams()
       if (typeof args?.root === "number") params.set("root", String(args.root))

package/src/commands/pack.ts

@@ -1,11 +1,17 @@
 import { values, source } from "../args"
-import { bundleFlux, bundleSolid, compileToBytecode } from "../bundler"
+import { bundleFlux, bundleSolid, compileToBytecode, findFluxIsolates } from "../bundler"
 import { resolvePackFonts } from "../fonts"
 import { loadAppIdentity } from "../project"
 import { packFlux, packSolid } from "../packer"
 import { buildPackFolder, writePackFolder } from "../pack-folder"
 import { requireBinary } from "../util"
-import { resolve } from "node:path"
+import { dirname, join, resolve } from "node:path"
+
+// Windows executables need the suffix; a user-given --output may already
+// carry it.
+function exeName(outfile: string): string {
+  return process.platform === "win32" && !outfile.toLowerCase().endsWith(".exe") ? outfile + ".exe" : outfile
+}
 
 // Write the packed executable, mark it runnable, and report its size.
 async function writeExecutable(packed: Buffer, outfile: string) {
@@ -22,11 +28,15 @@ export async function runPackCommand() {
       console.error("--folder is for app packs; flux scripts have no folder output")
       process.exit(1)
     }
-    let outfile = values.output ?? source!.replace(/\.[jt]sx?$/, "")
-    if (process.platform === "win32" && !outfile.toLowerCase().endsWith(".exe")) {
-      outfile += ".exe"
+    let outfile = exeName(values.output ?? source!.replace(/\.[jt]s$/, ""))
+    // The entry's isolate modules ride along as isolates/<id>.bin sections
+    // (module name = id, for stack attribution).
+    let isolates = []
+    for (let module of findFluxIsolates(dirname(resolve(source!)))) {
+      isolates.push({ id: module.id, bytecode: await compileToBytecode(await bundleFlux(module.path), module.id) })
     }
-    await writeExecutable(await packFlux(await bundleFlux(source!)), outfile)
+    if (isolates.length) console.log(`>> isolates: ${isolates.map((i) => i.id).join(", ")}`)
+    await writeExecutable(packFlux(await compileToBytecode(await bundleFlux(source!)), isolates), outfile)
     process.exit()
   }
 
@@ -44,12 +54,12 @@ export async function runPackCommand() {
   let bundled = await bundleSolid()
   let bytecode = await compileToBytecode(bundled.code)
   let isolates = []
-  for (let i of bundled.isolates) isolates.push({ id: i.id, bytecode: await compileToBytecode(i.code) })
+  for (let i of bundled.isolates) isolates.push({ id: i.id, bytecode: await compileToBytecode(i.code, i.id) })
   if (isolates.length) console.log(`>> isolates: ${isolates.map((i) => i.id).join(", ")}`)
   let folder = buildPackFolder(source!, bytecode, isolates)
 
   if (values.folder) {
-    let outDir = values.output ?? "dist"
+    let outDir = values.output ?? join("dist", "pack")
     writePackFolder(outDir, requireBinary("solidrt"), bytecode, folder)
     console.log(`>> wrote pack folder to ${resolve(outDir)}`)
     process.exit()

package/src/commands/render.ts

@@ -1,11 +1,33 @@
 import { appArgs, source, values } from "../args"
 import { requireBinary, run } from "../util"
-import { bundleTo } from "../bundler"
-import { resolve } from "path"
+import { bundleSolid, writeIsolates } from "../bundler"
+import { collectAssets, projectDirFor } from "../project"
+import { cpSync, mkdirSync, rmSync } from "node:fs"
+import { basename, dirname, join, resolve } from "path"
 
 export async function runRenderCommand() {
-  let jsOutfile = source!.replace(/\.[jt]sx$/, "") + ".srt.js"
-  await bundleTo(jsOutfile)
+  let entry = resolve(source!)
+  let projectDir = projectDirFor(entry)
+  let result = await bundleSolid()
+  // The staged run dir (okf/backlog/build-output-dirs.md): bundle +
+  // isolates/ + assets/ under one root - the shape of an installed version
+  // dir, so the runtime's assets mount resolves both trees. Wiped first so
+  // removed isolates and deleted assets cannot go stale; render owns this
+  // subdir and nothing else under dist/.
+  let outDir = join(projectDir, "dist", "render")
+  rmSync(outDir, { recursive: true, force: true })
+  let jsOutfile = join(outDir, basename(entry).replace(/\.[jt]sx?$/, "") + ".srt.js")
+  await Bun.write(jsOutfile, result.code)
+  writeIsolates(join(outDir, "isolates"), result.isolates)
+  // The project's assets/ tree, copied in (dotfiles filtered, like a pack)
+  // so `assets/...` resolves like it does under the dev server and in a
+  // packed app (the runtime's cwd is the data sandbox, which holds no
+  // assets).
+  for (let asset of collectAssets(entry).assets) {
+    let dest = join(outDir, asset.path)
+    mkdirSync(dirname(dest), { recursive: true })
+    cpSync(join(projectDir, asset.path), dest)
+  }
   let runner = requireBinary("solidrt-go")
   let playbackArgs = ["--playback"]
   if (values.fps) playbackArgs.push("--fps", values.fps)
@@ -15,7 +37,8 @@ export async function runRenderCommand() {
   // Always absolute: the runtime chdirs into the app's data sandbox before
   // frames are written, so a bare prefix would land the PNGs there.
   playbackArgs.push("--out", resolve(values.output ?? "."))
-  playbackArgs.push(resolve(jsOutfile))
+  playbackArgs.push("--assets", outDir)
+  playbackArgs.push(jsOutfile)
   // The runner takes everything after the source path verbatim as the app's
   // argument vector (flux:process argv).
   playbackArgs.push(...appArgs)