brustjs 0.1.0-alpha

package/runtime/index.ts

@@ -0,0 +1,618 @@
+import * as native from './index.js'
+import type { ActionDef } from './actions.ts'
+import { isValidActionId } from './actions.ts'
+import { loadConfig } from './config.ts'
+import { configureCssEnabled, configureCssHrefsForRoute } from './css.ts'
+
+export interface ServeOptions {
+  port: number
+  workers: number
+  entry: string
+  bootTimeoutMs?: number
+  /** Action definitions discovered by `brust.scanActions()`. When present,
+   * `serve` calls the internal action registry before the listener binds.
+   * Optional — omit if the app has no server actions. */
+  actions?: ActionDef[]
+  /** MCP support — pass a manifest built via brust.buildMcpManifest. brust.serve
+   * does NOT auto-wire MCP into workers; the worker branch of the entry file must
+   * call brust.loadMcpManifest() + makeMcpServer() itself and pass the McpServer
+   * to makeRenderer via `opts.mcp`. See example/hello-world/index.ts for the
+   * pattern. The field here is currently unused inside serve() and is reserved
+   * for future IPC-based propagation of the manifest. */
+  mcp?: { manifest: import('./mcp/manifest.ts').McpManifest }
+}
+
+// Render callback. Resolves with a framed-response length: `> 0` → FAST LANE
+// (the worker wrote `[meta_len][meta][body]` into the SAB; Rust reads it
+// directly), `0` → the worker used the chunk channel via
+// `napi.renderChunk(workerId, len)` (React Suspense streaming) or owns the
+// socket independently (SSE/WS). The argument is a JSON envelope
+// `{ route_id, path, params }` produced by Rust's route table — see
+// runtime/routes.ts::RouteCall.
+export type RenderFn = (envelopeJsonOrLen: number | string) => Promise<number>
+
+// Bun Workers run in the same OS process as the main thread; the `env` option
+// only patches the JS-visible process.env, not the native OS environment that
+// Rust reads via std::env::var.  Read the flag here in JS instead.
+export const isWorker: boolean = process.env.BRUST_WORKER_ID !== undefined
+
+// native.workerId() reads a thread-local set by registerRenderer, so it must
+// be re-evaluated at the point of use (not cached at module load).
+export function workerId(): number | null {
+  return (native as any).workerId()
+}
+
+// Sub-project J — boot-time jinja loader. Idempotent: Rust holds the loaded
+// templates in a OnceLock, so a second `set()` would panic. The flag guards
+// repeated calls in both main and worker branches of `run()`, and from any
+// future test/embedded entrypoint that calls `registerRoutes` directly.
+let _jinjaLoaded = false
+function loadJinjaOnce(dir: string): void {
+  if (_jinjaLoaded) return
+  ;(native as any).napiLoadJinjaTemplates(dir)
+  _jinjaLoaded = true
+}
+
+function registerActionsInternal(actions: Array<{ id: string }>): number {
+  const seen = new Set<string>()
+  for (const a of actions) {
+    if (!isValidActionId(a.id)) {
+      throw new Error(
+        `action id ${JSON.stringify(a.id)} contains invalid characters; ` +
+          `allowed: [A-Za-z0-9_-]+ (max 128 chars)`,
+      )
+    }
+    if (seen.has(a.id)) {
+      throw new Error(`action id ${JSON.stringify(a.id)} registered more than once`)
+    }
+    seen.add(a.id)
+  }
+  return (native as any).registerActions(actions.map((a) => a.id))
+}
+
+/** Read and schema-validate a prebuilt mcp-manifest.json at an absolute path.
+ *  Returns null if the file does not exist. Throws on malformed JSON or version mismatch. */
+async function readManifestFromPath(
+  absolutePath: string,
+): Promise<import('./mcp/manifest.ts').McpManifest | null> {
+  const f = Bun.file(absolutePath)
+  if (!(await f.exists())) return null
+  const text = await f.text()
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (e) {
+    throw new Error(`mcp-manifest.json is malformed: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (!parsed || typeof parsed !== 'object' || (parsed as { version?: unknown }).version !== 1) {
+    throw new Error(`mcp-manifest.json version mismatch (expected 1)`)
+  }
+  return parsed as import('./mcp/manifest.ts').McpManifest
+}
+
+export const brust = {
+  async serve(opts: ServeOptions): Promise<void> {
+    if (opts.actions && opts.actions.length > 0) {
+      // Register action ids with Rust. registerActionsInternal validates
+      // charset + uniqueness; throws on either. Mirrors the previous
+      // `brust.registerActions` user-facing call exactly.
+      registerActionsInternal(opts.actions)
+    }
+    ;(native as any).beginServe({
+      port: opts.port,
+      workers: opts.workers,
+      entry: opts.entry,
+    })
+    const baseEnv = { ...process.env }
+    const workersArr: Worker[] = []
+    for (let i = 0; i < opts.workers; i++) {
+      // Bun.Worker requires the JS entry (post-bundling). For the skeleton,
+      // the entry is a TS file that Bun executes directly.
+      workersArr.push(
+        new Worker(opts.entry, {
+          env: { ...baseEnv, BRUST_WORKER_ID: String(i) },
+        }),
+      )
+    }
+    if (process.env.BRUST_DEV === '1') {
+      const { registerInitialPool } = await import('./dev/worker-registry.ts')
+      registerInitialPool(workersArr, opts.entry, opts.workers, baseEnv as Record<string, string>)
+    }
+    // Bun Workers intercept SIGINT before Rust's ctrl_c() handler fires.
+    // Install a JS-level handler so the process actually exits on SIGINT.
+    process.on('SIGINT', () => process.exit(0))
+    await (native as any).untilReady(opts.bootTimeoutMs ?? 5000)
+    await (native as any).untilShutdown()
+  },
+  /** Install the route table in Rust. MUST be called before `serve()`.
+   * Pass an array of FlatRoutes from `defineRoutes(...)` — each is JSON-encoded
+   * with its optional cache config. Rust matches against `fullPath`. */
+  registerRoutes(routes: import('./routes.ts').FlatRoute[]): number {
+    const configs = routes.map((r) =>
+      JSON.stringify({
+        path: r.fullPath,
+        cache: r.cache ?? null,
+        nativeTemplate: r.nativeTemplate ?? null,
+      }),
+    )
+    const result = (native as any).registerRoutes(configs)
+
+    // Sub-project J — startup validation. Every native: true route's
+    // Component.name must have a registered .jinja template, else 500 at
+    // request time. Warn here so boot logs surface the misconfiguration
+    // before any traffic hits.
+    const expected = routes.filter((r) => r.nativeTemplate).map((r) => r.nativeTemplate!)
+    if (expected.length > 0) {
+      const registered = new Set<string>((native as any).napiListNativeTemplates() ?? [])
+      for (const name of expected) {
+        if (!registered.has(name)) {
+          console.warn(
+            `[brust] native: true route expects template "${name}.jinja" but it's not registered (boot warning — request will 500)`,
+          )
+        }
+      }
+    }
+    return result
+  },
+  /** Register the list of literal route paths that should be dispatched as
+   * SSE (text/event-stream) instead of going through the render pipeline.
+   * Call from the main process after defineRoutes — the worker only needs
+   * the call if it also accepts SSE traffic, but in the current model the
+   * main accept loop owns dispatch so this is main-only. MVP supports only
+   * literal paths; parameterized routes (e.g. `/sse/{room}`) are a follow-up. */
+  registerSsePaths(paths: string[]): void {
+    ;(native as any).napiRegisterSsePaths(paths)
+  },
+  /** Register the list of literal route paths that should be dispatched as
+   * WebSocket upgrades. Call from the main process after defineRoutes.
+   * MVP supports only literal paths — parameterized routes (e.g.
+   * `/ws/chat/{room}`) are a follow-up. */
+  registerWsPaths(paths: string[]): void {
+    ;(native as any).napiRegisterWsPaths(paths)
+  },
+  /** Set the response cache capacity (entries). Default is 1000.
+   * Safe to call at any time; if shrinking below current size, excess
+   * LRU entries are evicted. */
+  configureCache(opts: { maxEntries: number }): void {
+    ;(native as any).configureCache(opts.maxEntries)
+  },
+  /** Tell Rust where to read `/_brust/islands/<file>` from. Called once at
+   * boot after buildIslands() emits chunks. Path must be absolute. */
+  configureIslandsDir(dir: string): void {
+    ;(native as any).configureIslandsDir(dir)
+  },
+  /** Tell Rust where to read `/_brust/css/<file>` from. Called from the
+   * main thread when CSS is configured. Path must be absolute. */
+  configureCssDir(dir: string): void {
+    ;(native as any).configureCssDir(dir)
+  },
+  /** Walk the project for files marked `'use server'`, import them, and
+   * return all named function exports as ActionDef[] plus the list of source
+   * files (needed by brust.buildMcpManifest). Both the main process and each
+   * worker should call this once at module top-level and pass `actions` to
+   * `brust.serve({ actions, ... })` (main) and `makeRenderer(..., { actions,
+   * ... })` (worker). See ScanOptions for roots / ignore overrides. */
+  async scanActions(
+    opts?: import('./scan-actions.ts').ScanOptions,
+  ): Promise<import('./scan-actions.ts').ScanActionsResult> {
+    const { scanActions } = await import('./scan-actions.ts')
+    return scanActions(opts)
+  },
+  /** Extract the MCP manifest from TypeScript source using the compiler API,
+   * write it to `.brust/mcp-manifest.json`, and return it. Call once in the
+   * main process after `brust.registerRoutes(routes)`. Workers must read the
+   * persisted manifest themselves via `brust.loadMcpManifest()` in the worker
+   * branch and pass an `McpServer` (built via `makeMcpServer`) to
+   * `makeRenderer` via `opts.mcp`. See example/hello-world/index.ts. */
+  async buildMcpManifest(opts: {
+    serverFiles: string[]
+    routesFile: string
+    sourceRoots: string[]
+    actions: import('./actions.ts').ActionDef[]
+    routes: import('./routes.ts').FlatRoute[]
+    cwd?: string
+  }): Promise<import('./mcp/manifest.ts').McpManifest> {
+    const { extractMcpManifest } = await import('./mcp/extractor.ts')
+    const { writeManifest } = await import('./mcp/manifest.ts')
+    const m = await extractMcpManifest(opts)
+    await writeManifest(opts.cwd ?? process.cwd(), m)
+    return m
+  },
+  /** Read the MCP manifest from `.brust/mcp-manifest.json`. Returns null if
+   * the file does not exist (i.e. the main process hasn't called
+   * `brust.buildMcpManifest` yet). Throws if the file is malformed. */
+  async loadMcpManifest(
+    cwd: string = process.cwd(),
+  ): Promise<import('./mcp/manifest.ts').McpManifest | null> {
+    const { readManifest } = await import('./mcp/manifest.ts')
+    return readManifest(cwd)
+  },
+  // Register a renderer for this Bun Worker. `buf` MUST be backed by a SharedArrayBuffer
+  // (or any ArrayBuffer the worker keeps rooted) — Rust captures the backing-store
+  // pointer once here and reuses it for every render call. The buffer is held alive
+  // by the worker's module scope; do not let it go out of scope.
+  registerRenderer(buf: Uint8Array, fn: RenderFn): number {
+    return (native as any).registerRenderer(buf, fn)
+  },
+
+  /**
+   * One-call lifecycle: scans actions, builds islands (if `routes.tsx` uses
+   * `<Island>`), registers routes + SSE/WS paths, builds the MCP manifest, then
+   * branches to `serve()` (main thread) or registers a renderer (worker
+   * thread). Replaces ~70 lines of boilerplate; the lower-level helpers
+   * (`scanActions`, `registerRoutes`, `makeRenderer`, etc.) are still exported
+   * for apps that need finer control.
+   *
+   * Conventions assumed (override via the corresponding option if your layout
+   * differs):
+   *   - `<scanRoot>/routes.tsx`       — scanned for `<Island>` usage (islands)
+   *                                     and referenced by the MCP manifest builder
+   *
+   * `scanRoot` defaults to the directory of `entry` so the typical caller
+   * passes only `{ routes, entry: import.meta.url }`.
+   */
+  async run(opts: {
+    routes: import('./routes.ts').FlatRoute[]
+    entry: string
+    scanRoot?: string
+    /** Overrides merged into the underlying `serve()` call (main thread). */
+    serve?: Partial<Omit<ServeOptions, 'entry' | 'actions' | 'mcp'>>
+    /** Per-worker SAB size in bytes. Default 256 KB. */
+    sabBytes?: number
+    /** When true, prepend the dev WS route, install file watcher, set the
+     * dev-client snippet, and start the TUI. Default false.
+     * Also activated by BRUST_DEV=1 environment variable. */
+    dev?: boolean
+  }): Promise<void> {
+    const { existsSync } = await import('node:fs')
+    const { fileURLToPath } = await import('node:url')
+    const path = await import('node:path')
+
+    const prebuilt = process.env.BRUST_PREBUILT === '1'
+    const distDir = process.env.BRUST_DIST_DIR
+
+    const scanRoot = opts.scanRoot ?? path.dirname(fileURLToPath(opts.entry))
+
+    const dev = opts.dev === true || process.env.BRUST_DEV === '1'
+    let routes = opts.routes
+    if (dev) {
+      const { createDevWsRoute } = await import('./dev/ws-channel.ts')
+      const { buildDevClientTag } = await import('./dev/client.ts')
+      const { configureDevClientSnippet } = await import('./dev/inject.ts')
+      const devRoute = createDevWsRoute()
+      routes = [
+        { ...devRoute, fullPath: devRoute.path!, chain: [devRoute as any] } as any,
+        ...opts.routes,
+      ]
+      configureDevClientSnippet(buildDevClientTag())
+    }
+    // scanActions is plugin-aliased in prebuilt bundles → returns pre-baked
+    // list with sourceFiles=[]. In dev mode it walks the filesystem.
+    const { actions, sourceFiles } = await this.scanActions({ roots: [scanRoot] })
+
+    if (!isWorker) {
+      const { port, workers, cacheMaxEntries } = await loadConfig()
+      console.log(`[brust] main: spawning ${workers} worker threads`)
+      if (cacheMaxEntries !== undefined) this.configureCache({ maxEntries: cacheMaxEntries })
+
+      // Component CSS pipeline. Must run BEFORE buildIslands so the Bun.plugin
+      // is active during island bundling — otherwise Bun's default loader would
+      // see .module.css imports as separate asset outputs, producing duplicate-
+      // output-path errors when an island and its module share a basename
+      // (e.g. Counter.tsx + Counter.module.css → both want to emit Counter.js).
+      {
+        const { readComponentCssManifest } = await import('./css/manifest.ts')
+        const { cssLoaderPlugin } = await import('./css/component-loader.ts')
+        let manifest: import('./css/manifest.ts').ComponentCssManifest | null = null
+
+        if (prebuilt) {
+          const manifestPath = path.join(distDir!, 'css', 'component-manifest.json')
+          manifest = await readComponentCssManifest(manifestPath)
+        } else {
+          const { scanCssImports } = await import('./css/scan-imports.ts')
+          const scan = await scanCssImports(scanRoot)
+          if (scan.size > 0) {
+            const { buildComponentCss } = await import('./css/component-build.ts')
+            const routeForCss = opts.routes.map((r) => ({
+              fullPath: r.fullPath,
+              componentSource: path.join(scanRoot, 'routes.tsx'),
+            }))
+            const cssOutDir = path.join(process.cwd(), '.brust', 'css')
+            manifest = await buildComponentCss({
+              scanRoot,
+              outDir: cssOutDir,
+              tailwindCompile: null,
+              routes: routeForCss,
+            })
+            console.log(
+              `[brust] main: built ${Object.keys(manifest.modules).length} component CSS chunk(s)`,
+            )
+          }
+        }
+
+        if (manifest) {
+          Bun.plugin(cssLoaderPlugin(manifest))
+          for (const [routePath, hrefs] of Object.entries(manifest.routeChunks)) {
+            configureCssHrefsForRoute(routePath, hrefs)
+          }
+        }
+      }
+
+      if (prebuilt) {
+        // Pre-built islands live at <distDir>/islands.
+        const prebuiltIslandsDir = path.join(distDir!, 'islands')
+        if (existsSync(prebuiltIslandsDir)) {
+          this.configureIslandsDir(prebuiltIslandsDir)
+          console.log(`[brust] main: using pre-built islands at ${prebuiltIslandsDir}`)
+        }
+      } else {
+        const routesPath = path.join(scanRoot, 'routes.tsx')
+        if (existsSync(routesPath)) {
+          const { scanIslandChunks, buildIslands: build } = await import('./islands/build.ts')
+          const islandMap = scanIslandChunks(routesPath)
+          if (islandMap.size > 0) {
+            const islands = await build(islandMap)
+            this.configureIslandsDir(islands.outDir)
+            console.log(`[brust] main: built ${islands.islandCount} island chunk(s)`)
+          }
+        }
+      }
+
+      // CSS pipeline — opt-in via convention: <scanRoot>/app.css.
+      if (prebuilt) {
+        const prebuiltCssDir = path.join(distDir!, 'css')
+        if (existsSync(prebuiltCssDir)) {
+          this.configureCssDir(prebuiltCssDir)
+          configureCssEnabled(['/_brust/css/app.css'])
+          console.log(`[brust] main: using pre-built CSS at ${prebuiltCssDir}`)
+        }
+      } else {
+        const appCssPath = path.join(scanRoot, 'app.css')
+        if (existsSync(appCssPath)) {
+          const { buildCss } = await import('./css/build.ts')
+          const cssOutDir = path.join(process.cwd(), '.brust', 'css')
+          await buildCss({ entry: appCssPath, outDir: cssOutDir })
+          this.configureCssDir(cssOutDir)
+          configureCssEnabled(['/_brust/css/app.css'])
+          console.log(`[brust] main: built CSS → ${cssOutDir}/app.css`)
+        }
+      }
+
+      // Sub-project J — load .brust/jinja/*.jinja into the minijinja env so
+      // the startup-validation warning in registerRoutes can compare against
+      // a populated registry. Idempotent (Rust uses OnceLock).
+      loadJinjaOnce(path.resolve(process.cwd(), '.brust/jinja'))
+
+      this.registerRoutes(routes)
+      const ssePaths = routes
+        .filter((r) => r.chain[r.chain.length - 1].sse !== undefined)
+        .map((r) => r.fullPath)
+      if (ssePaths.length > 0) {
+        this.registerSsePaths(ssePaths)
+        console.log(
+          `[brust] main: registered ${ssePaths.length} sse path(s): ${ssePaths.join(', ')}`,
+        )
+      }
+      const wsPaths = routes
+        .filter((r) => r.chain[r.chain.length - 1].websocket !== undefined)
+        .map((r) => r.fullPath)
+      if (wsPaths.length > 0) {
+        this.registerWsPaths(wsPaths)
+        console.log(`[brust] main: registered ${wsPaths.length} ws path(s): ${wsPaths.join(', ')}`)
+      }
+      console.log(
+        `[brust] main: scanActions found ${actions.length} action(s): ${actions.map((a) => a.id).join(', ')}`,
+      )
+
+      if (dev) {
+        const { createWatcher } = await import('./dev/watcher.ts')
+        const { Coordinator } = await import('./dev/coordinator.ts')
+        const { broadcast } = await import('./dev/ws-channel.ts')
+        const { Tui } = await import('./dev/tui.ts')
+        const { terminateAll: termWorkers, spawnAll: spawnWorkers } = await import(
+          './dev/worker-registry.ts'
+        )
+        const fsModule = await import('node:fs')
+        const pathModule = await import('node:path')
+
+        const tui = new Tui({
+          isTty: process.stdout.isTTY === true,
+          write: (s: string) => process.stdout.write(s),
+        })
+        tui.updateStatus({ port, workers, watching: [scanRoot] })
+        tui.appendEvent(`▶ serving on http://127.0.0.1:${port}`)
+
+        const coordinator = new Coordinator({
+          workers: {
+            terminateAll: termWorkers,
+            spawnAll: async () => {
+              await spawnWorkers()
+            },
+          },
+          buildCss: async () => {
+            const appCss = pathModule.join(scanRoot, 'app.css')
+            if (fsModule.existsSync(appCss)) {
+              const { buildCss } = await import('./css/build.ts')
+              const outDir = pathModule.join(process.cwd(), '.brust', 'css')
+              await buildCss({ entry: appCss, outDir })
+            }
+          },
+          buildIslands: async () => {
+            const routesPath = pathModule.join(scanRoot, 'routes.tsx')
+            if (fsModule.existsSync(routesPath)) {
+              const { scanIslandChunks, buildIslands } = await import('./islands/build.ts')
+              const islandMap = scanIslandChunks(routesPath)
+              if (islandMap.size > 0) {
+                await buildIslands(islandMap)
+              }
+            }
+          },
+          buildComponentCss: async () => {
+            const { scanCssImports } = await import('./css/scan-imports.ts')
+            const scan = await scanCssImports(scanRoot)
+            if (scan.size === 0) return
+            const { buildComponentCss } = await import('./css/component-build.ts')
+            const { cssLoaderPlugin } = await import('./css/component-loader.ts')
+            const routeForCss = opts.routes.map((r) => ({
+              fullPath: r.fullPath,
+              componentSource: pathModule.join(scanRoot, 'routes.tsx'),
+            }))
+            const cssOutDir = pathModule.join(process.cwd(), '.brust', 'css')
+            const manifest = await buildComponentCss({
+              scanRoot,
+              outDir: cssOutDir,
+              tailwindCompile: null,
+              routes: routeForCss,
+            })
+            Bun.plugin(cssLoaderPlugin(manifest))
+            for (const [rp, hrefs] of Object.entries(manifest.routeChunks)) {
+              configureCssHrefsForRoute(rp, hrefs)
+            }
+          },
+          snapshotComponentCss: async () => {
+            const { readComponentCssManifest } = await import('./css/manifest.ts')
+            const p = pathModule.join(process.cwd(), '.brust', 'css', 'component-manifest.json')
+            return await readComponentCssManifest(p)
+          },
+          broadcast,
+          tui: { appendEvent: (l) => tui.appendEvent(l) },
+        })
+
+        createWatcher({
+          root: scanRoot,
+          onChange: (ev) => {
+            void coordinator.handleChange(ev)
+          },
+        })
+      }
+
+      let mcpManifest: import('./mcp/manifest.ts').McpManifest | null
+      if (prebuilt) {
+        const manifestPath = path.join(distDir!, 'mcp-manifest.json')
+        mcpManifest = await readManifestFromPath(manifestPath)
+        if (mcpManifest) {
+          console.log(
+            `[brust] main: loaded pre-built mcp manifest (${mcpManifest.tools.length} tools + ${mcpManifest.resources.length} resources)`,
+          )
+        }
+      } else {
+        mcpManifest = await this.buildMcpManifest({
+          serverFiles: sourceFiles,
+          routesFile: path.join(scanRoot, 'routes.tsx'),
+          sourceRoots: [scanRoot],
+          actions,
+          routes,
+        })
+        console.log(
+          `[brust] main: mcp manifest has ${mcpManifest.tools.length} tools + ${mcpManifest.resources.length} resources`,
+        )
+      }
+
+      await this.serve({
+        port,
+        workers,
+        entry: opts.entry,
+        actions,
+        ...(mcpManifest ? { mcp: { manifest: mcpManifest } } : {}),
+        ...opts.serve,
+      })
+    } else {
+      // Worker branch
+      let workerRoutes = opts.routes
+      if (dev) {
+        const { buildDevClientTag } = await import('./dev/client.ts')
+        const { configureDevClientSnippet } = await import('./dev/inject.ts')
+        configureDevClientSnippet(buildDevClientTag())
+        const { createDevWsRoute, installWorkerBroadcastListener } = await import(
+          './dev/ws-channel.ts'
+        )
+        installWorkerBroadcastListener()
+        const devRoute = createDevWsRoute()
+        workerRoutes = [
+          { ...devRoute, fullPath: devRoute.path!, chain: [devRoute as any] } as any,
+          ...opts.routes,
+        ]
+      }
+      // Worker: detect CSS the same way main did (no compile, no configureCssDir
+      // — Rust state is shared, but the per-worker renderer needs the hrefs).
+      if (prebuilt) {
+        if (existsSync(path.join(distDir!, 'css'))) {
+          configureCssEnabled(['/_brust/css/app.css'])
+        }
+      } else {
+        if (existsSync(path.join(scanRoot, 'app.css'))) {
+          configureCssEnabled(['/_brust/css/app.css'])
+        }
+      }
+
+      // Worker: register the component CSS Bun.plugin so .module.css imports
+      // resolve to the same hash map main saw. (Workers don't seed
+      // configureCssHrefsForRoute — that's a renderer concern only on the
+      // main thread.)
+      {
+        const { readComponentCssManifest } = await import('./css/manifest.ts')
+        const { cssLoaderPlugin } = await import('./css/component-loader.ts')
+        const manifestPath = prebuilt
+          ? path.join(distDir!, 'css', 'component-manifest.json')
+          : path.join(process.cwd(), '.brust', 'css', 'component-manifest.json')
+        const manifest = await readComponentCssManifest(manifestPath)
+        if (manifest) {
+          Bun.plugin(cssLoaderPlugin(manifest))
+        }
+      }
+
+      const sab = new SharedArrayBuffer(opts.sabBytes ?? 256 * 1024)
+      const view = new Uint8Array(sab)
+
+      let mcpManifest: import('./mcp/manifest.ts').McpManifest | null
+      if (prebuilt) {
+        const manifestPath = path.join(distDir!, 'mcp-manifest.json')
+        mcpManifest = await readManifestFromPath(manifestPath)
+      } else {
+        mcpManifest = await this.loadMcpManifest()
+      }
+      let mcpServer: import('./mcp/server.ts').McpServer | undefined
+      if (mcpManifest) {
+        const { makeMcpServer } = await import('./mcp/server.ts')
+        mcpServer = makeMcpServer({ manifest: mcpManifest, actions, routes: workerRoutes })
+        console.log(`[brust] worker: mcp server ready (${mcpManifest.tools.length} tools)`)
+      }
+
+      // Sub-project J note: jinja templates are loaded ONCE process-wide by the
+      // main branch's loadJinjaOnce call. Rust's ENV is a process-global
+      // OnceLock; Bun Workers share that process, so calling it from each
+      // worker would panic on second set(). The worker reads ENV.get() at
+      // napi_render_jinja time — no per-worker load needed.
+
+      const { makeRenderer: make } = await import('./routes.ts')
+      let wid: number | null = null
+      const renderer = make(workerRoutes, view, { actions, getWorkerId: () => wid, mcp: mcpServer })
+      wid = this.registerRenderer(view, renderer)
+    }
+  },
+}
+
+export { defineRoutes, makeRenderer, Outlet } from './routes.ts'
+export type {
+  Route,
+  RouteCall,
+  RouteContext,
+  ErrorBoundaryProps,
+  RouteCacheConfig,
+  BrustRequest,
+  RouteResponse,
+  Middleware,
+} from './routes.ts'
+
+export { withMiddleware, isValidActionId } from './actions.ts'
+export type { ActionDef, ActionFn } from './actions.ts'
+export type { ScanOptions, ScanActionsResult } from './scan-actions.ts'
+
+export { loadConfig, BrustConfigError } from './config.ts'
+export type { BrustConfig } from './config.ts'
+
+export { Island } from './islands/island.tsx'
+export type { IslandProps, HydrateTrigger } from './islands/island.tsx'
+
+export { buildIslands } from './islands/build.ts'
+export type { IslandsBuildResult, BuildIslandsOptions } from './islands/build.ts'

package/runtime/islands/__fixtures__/NoDefault.tsx

@@ -0,0 +1,3 @@
+// Test fixture for native-render T9 contained-failure: a module with NO
+// default-exported component. Hits the `typeof Component !== 'function'` guard.
+export const notDefault = 42

package/runtime/islands/__fixtures__/StubIsland.tsx

@@ -0,0 +1,7 @@
+// Test fixture for native-render T9 ssr renderToString. A trivial island whose
+// markup embeds its `n` prop, so a test can assert (a) it server-renders to
+// `<span>N</span>` and (b) the value it received matches the roundtripped
+// `_props`. createElement (no JSX) keeps the fixture transpile-trivial.
+import { createElement } from 'react'
+
+export default ({ n }: { n: number }) => createElement('span', null, String(n))

package/runtime/islands/__fixtures__/ThrowingIsland.tsx

@@ -0,0 +1,9 @@
+// Test fixture for native-render T9 contained-failure: a valid default-exported
+// component that THROWS during render. This exercises the renderToString failure
+// path (the production-realistic SSR failure), not just the
+// `typeof Component !== 'function'` guard.
+import type { createElement } from 'react'
+
+export default function ThrowingIsland(): ReturnType<typeof createElement> {
+  throw new Error('boom in render')
+}

package/runtime/islands/_entries/react-dom.ts

@@ -0,0 +1,7 @@
+// Bun 1.4 doesn't translate `export *` from a CommonJS module into ES named
+// exports — the bundle ends up populating an internal object via __copyProps
+// but emits no `export { ... }` statement, so the importmap-targeted browser
+// import collapses to a SyntaxError. The CJS source (`node_modules/react-dom/
+// client.js`) exposes only `createRoot` and `hydrateRoot`; name them
+// explicitly so the bundler has a static export list to emit.
+export { createRoot, hydrateRoot } from 'react-dom/client'

package/runtime/islands/_entries/react.ts

@@ -0,0 +1,11 @@
+// Combined re-export. The browser's importmap maps BOTH `react` and
+// `react/jsx-runtime` to the chunk built from this file. Browser fetches
+// once; different import statements slice different named exports from
+// the same module.
+//
+// `export *` from `react` includes Fragment; `react/jsx-runtime` also
+// exports Fragment. We re-export only jsx + jsxs from jsx-runtime to
+// avoid the name collision (Fragment from react wins, which is the
+// same object).
+export * from 'react'
+export { jsx, jsxs } from 'react/jsx-runtime'