@solidrt/cli 0.0.50 → 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

@@ -30,6 +30,18 @@ function packageName(dir: string): string {
 
 const DEFAULT_TEMPLATE = "default"
 
+// 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/.
@@ -48,24 +60,10 @@ const EXTENSIONS: Extension[] = [
   { pkg: "@solidrt/3d", description: "general purpose 3D library" },
 ]
 
-// Resolve which extensions the app takes: an explicit --with list if valid,
-// an interactive picker on a TTY, else none (core only).
+// 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[]> {
-  let raw = values.with
-  if (raw !== undefined) {
-    let names = raw.split(",").map((n) => n.trim()).filter(Boolean)
-    let chosen: Extension[] = []
-    for (let name of names) {
-      let found = EXTENSIONS.find((e) => e.pkg === name)
-      if (!found) {
-        let all = EXTENSIONS.map((e) => e.pkg).join(", ")
-        console.error(`!! Unknown extension "${name}"; choose from: ${all}`)
-        process.exit(1)
-      }
-      if (!chosen.includes(found)) chosen.push(found)
-    }
-    return chosen
-  }
   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")
@@ -109,7 +107,9 @@ export async function runInitCommand() {
   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}`)
   }
 

package/src/commands/mcp.ts

@@ -243,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, 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). 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",
@@ -389,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()
@@ -468,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)

package/src/commands/server.ts

@@ -2,8 +2,8 @@ import pkg from "../../package.json"
 import { source, isSource, isPrebuilt, values } from "../args"
 import { state, shutdown, print, printErr } from "../util"
 import { findProjectRoot, typecheck, reportTypes } from "./check"
-import { bundle } from "../bundler"
-import { buildManifest, projectDirFor } from "../project"
+import { bundle, bundleMaps, prebuiltManifest } from "../bundler"
+import { projectDirFor } from "../project"
 import { startServer, buildReload, sendReload, showBuildFailure } from "../dev-server"
 import { startRepl } from "../repl"
 import { startWatcher } from "../watcher"
@@ -34,11 +34,11 @@ export async function runServerCommand() {
     let initialResult = await bundle()
     if (initialResult) {
       state.currentCode = initialResult.code
-      state.currentMap = initialResult.map
+      state.currentMaps = bundleMaps(initialResult)
       state.currentManifest = initialResult.manifest
       await sendReload(buildReload({ code: state.currentCode, manifest: state.currentManifest }), {
         latch: true,
-        map: state.currentMap,
+        maps: state.currentMaps,
       })
     } else {
       await showBuildFailure()
@@ -46,7 +46,7 @@ export async function runServerCommand() {
   } else if (source && isPrebuilt && source.endsWith(".srt.js")) {
     let path = resolve(source)
     state.currentCode = await Bun.file(path).text()
-    state.currentManifest = buildManifest(state.currentCode, path)
+    state.currentManifest = prebuiltManifest(state.currentCode, path, state.projectDir)
     await sendReload(buildReload({ code: state.currentCode, manifest: state.currentManifest }), { latch: true })
   }
 

package/src/dev-server.ts

@@ -28,8 +28,7 @@ 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
-// process over its loopback-only /__internal__/ routes. See
-// docs/flux-dev-server-plan.md.
+// process over its loopback-only /__internal__/ routes.
 
 const INTERNAL_BASE = `http://${DEV_HOST}:${DEV_PORT}/__internal__`
 
@@ -62,9 +61,10 @@ async function post(path: string, body: object) {
  * or to every client when omitted. `latch` keeps the message for late-joining
  * clients (code reloads latch, one-shot bytecode loads do not); `sourceDir`
  * moves the server's file-serving root (repl `load`; the project root is
- * fixed for the life of the run); `map` is the bundle's sourcemap, kept
- * server-side for stack-trace remapping (omitting it clears the server's map,
- * so a mapless reload never remaps against a stale one).
+ * fixed for the life of the run); `maps` is the bundle's sourcemaps keyed by
+ * module name ("main", each isolate id), kept server-side for stack-trace
+ * remapping (omitting it clears the server's maps, so a mapless reload never
+ * remaps against stale ones).
  */
 export async function sendReload(
   message: object,
@@ -73,7 +73,7 @@ export async function sendReload(
     latch?: boolean
     sourceDir?: string
     entry?: string
-    map?: string | null
+    maps?: Record<string, string> | null
   } = {},
 ) {
   await post("/reload", { message, ...opts })
@@ -291,7 +291,7 @@ export async function startServer() {
   process.on("exit", removeLiveRecord)
 
   // mDNS advertise (dropped, code kept for future use - see
-  // docs/flux-dev-server-plan.md): the p2p ticket is the cross-device connect
+  // okf/backlog/mdns-discovery.md): the p2p ticket is the cross-device connect
   // story now. If advertise returns, it belongs next to the server (a flux
   // capability), not here.
   //

package/src/packer.ts

@@ -1,18 +1,18 @@
 import { existsSync, readFileSync } from "node:fs"
 import { dirname, join } from "node:path"
 import { requireBinary } from "./util"
-import { compileToBytecode } from "./bundler"
 import type { PackFolder } from "./pack-folder"
 
-// Trailer magic identifying the runner an embedded payload belongs to. Must match
-// the runner-side checks: fluxrt -> flux/src/bin/fluxrt.rs, solidrt ->
-// lattice/src/main.rs (load_embedded_payload).
+// Trailer magic identifying the runner an embedded payload belongs to. Must
+// match the runner-side checks: both runners parse the trailer through
+// forge/src/trailer.rs (readers: lattice/src/main.rs, flux/src/bin/fluxrt.rs).
 const MAGIC = {
   fluxrt: Buffer.from([0x46, 0x4c, 0x55, 0x58, 0x52, 0x54, 0x88, 0x44]), // "FLUXRT\x88\x44"
   solidrt: Buffer.from([0x53, 0x4f, 0x4c, 0x49, 0x44, 0x52, 0x54, 0x88, 0x44]), // "SOLIDRT\x88\x44"
 }
 
-// Section kinds in the solidrt trailer. Must match lattice/src/main.rs.
+// Section kinds in the trailer. Must match forge/src/trailer.rs (fluxrt only
+// consumes kind-2 file sections; solidrt consumes all three).
 const SECTION_MANIFEST = 1
 const SECTION_FILE = 2
 const SECTION_GL_LIB = 3
@@ -92,12 +92,16 @@ export function packSolid(folder: PackFolder, bytecode: Buffer): Buffer {
   return packSections(runnerBytes, sections, MAGIC.solidrt)
 }
 
-// Compile JS to bytecode and append it to the fluxrt runner as its
-// single-payload trailer: [bytecode][u64 offset LE][8-byte magic].
-export async function packFlux(jsCode: string): Promise<Buffer> {
-  let bytecode = await compileToBytecode(jsCode)
+// The single-file flux executable: the fluxrt runner plus the program in the
+// same section trailer packSolid uses, kind-2 file sections only -
+// "bundle.bin" is the program, each isolate module "isolates/<id>.bin".
+// Like packSolid, this assembles precompiled bytecode; the pack command
+// compiles.
+export function packFlux(bytecode: Buffer, isolates: { id: string; bytecode: Buffer }[] = []): Buffer {
   let runnerBytes = readFileSync(requireBinary("fluxrt"))
-  let offsetBuf = Buffer.allocUnsafe(8)
-  offsetBuf.writeBigUInt64LE(BigInt(runnerBytes.length))
-  return Buffer.concat([runnerBytes, bytecode, offsetBuf, MAGIC.fluxrt])
+  let sections: Section[] = [
+    { kind: SECTION_FILE, bytes: bytecode, name: "bundle.bin" },
+    ...isolates.map((i) => ({ kind: SECTION_FILE, bytes: i.bytecode, name: `isolates/${i.id}.bin` })),
+  ]
+  return packSections(runnerBytes, sections, MAGIC.fluxrt)
 }

package/src/repl.ts

@@ -3,8 +3,7 @@ import { resolve, dirname } from "path"
 import { readdirSync } from "node:fs"
 import { state, print, printErr, shutdown } from "./util"
 import { buildReload, getClients, sendReload, sendStop, sendStats, sendWatch, showBuildFailure } from "./dev-server"
-import { bundle } from "./bundler"
-import { buildManifest } from "./project"
+import { bundle, bundleMaps, prebuiltManifest } from "./bundler"
 import { startWatcher, stopWatcher } from "./watcher"
 
 // Resolve repl client indexes ("0 2") against the server's client list,
@@ -28,7 +27,7 @@ async function cmdStop(args: string) {
   if (!args) {
     stopWatcher()
     state.currentCode = null
-    state.currentMap = null
+    state.currentMaps = null
     state.currentManifest = null
     state.source = undefined
     await sendStop()
@@ -51,18 +50,18 @@ async function cmdReload(args: string) {
       return
     }
     state.currentCode = result.code
-    state.currentMap = result.map
+    state.currentMaps = bundleMaps(result)
     state.currentManifest = result.manifest
   }
   let msg = buildReload({ code: state.currentCode, manifest: state.currentManifest })
   if (!args) {
-    await sendReload(msg, { latch: true, map: state.currentMap })
+    await sendReload(msg, { latch: true, maps: state.currentMaps })
     print("[cli] Sent reload to all clients")
     return
   }
   let ids = await indexesToIds(args)
   if (ids.length) {
-    await sendReload(msg, { clients: ids, map: state.currentMap })
+    await sendReload(msg, { clients: ids, maps: state.currentMaps })
     print(`[cli] Sent reload to client(s) ${ids.join(", ")}`)
   }
 }
@@ -104,7 +103,13 @@ async function cmdLoad(file: string) {
   // Same rule as /__control__/load (control.ts): a server run serves the
   // project it started in, and an entry outside the project root cannot
   // resolve the project's dependencies anyway.
-  let norm = (p: string) => p.replace(/\\/g, "/")
+  // Windows paths are case-insensitive and the same drive shows up as both
+  // `c:` and `C:` (an editor-spawned bridge keeps its parent's spelling), so a
+  // drive-letter path folds case; a POSIX path stays exact.
+  let norm = (p: string) => {
+    let s = p.replace(/\\/g, "/")
+    return /^[a-zA-Z]:\//.test(s) ? s.toLowerCase() : s
+  }
   let root = norm(state.projectDir).replace(/\/+$/, "") + "/"
   if (!norm(path).startsWith(root)) {
     printErr(`[cli] Entry is outside the project root: ${path} is not under ${state.projectDir}. Restart srt in that project to work on it.`)
@@ -117,12 +122,12 @@ async function cmdLoad(file: string) {
       return
     }
     state.currentCode = result.code
-    state.currentMap = result.map
+    state.currentMaps = bundleMaps(result)
     state.currentManifest = result.manifest
   } else if (file.endsWith(".srt.js")) {
     state.currentCode = await Bun.file(path).text()
-    state.currentMap = null
-    state.currentManifest = buildManifest(state.currentCode, path)
+    state.currentMaps = null
+    state.currentManifest = prebuiltManifest(state.currentCode, path, state.projectDir)
   } else if (file.endsWith(".srt.bin")) {
     let bytes = await Bun.file(path).arrayBuffer()
     // One-shot: bytecode loads are pushed but not latched for late joiners.
@@ -144,7 +149,7 @@ async function cmdLoad(file: string) {
     latch: true,
     sourceDir: state.sourceDir,
     entry: file.endsWith(".tsx") ? path : undefined,
-    map: state.currentMap,
+    maps: state.currentMaps,
   })
   print(`[cli] Loaded ${file}`)
 }
@@ -185,6 +190,17 @@ function guard(p: Promise<void>) {
 }
 
 export function startRepl() {
+  // Without a terminal there is nobody to prompt, and stdin is at EOF from the
+  // start: readline would fire `close` immediately and shutdown() would tear
+  // down the server, the client and the registry record about a second after
+  // boot. A backgrounded or supervisor-launched srt therefore runs with no
+  // repl at all, kept alive by the server process and the watcher, and stopped
+  // with a signal. See okf/backlog/srt-run-exits-on-stdin-eof.md.
+  if (!process.stdin.isTTY) {
+    print("[cli] No terminal on stdin, running without the repl")
+    return
+  }
+
   state.rl = createInterface({ input: process.stdin, output: process.stdout, completer })
   state.rl.setPrompt("srt> ")