brustjs 0.1.46-alpha → 0.1.48-alpha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brustjs",
-  "version": "0.1.46-alpha",
+  "version": "0.1.48-alpha",
   "description": "Bun + Rust SSR framework — React on the server, Rust everywhere else (napi cdylib + per-worker SharedArrayBuffer).",
   "license": "MIT",
   "repository": {
@@ -41,12 +41,12 @@
     "typescript": "^6.0.3"
   },
   "optionalDependencies": {
-    "brustjs-darwin-x64": "0.1.46-alpha",
-    "brustjs-darwin-arm64": "0.1.46-alpha",
-    "brustjs-linux-x64-gnu": "0.1.46-alpha",
-    "brustjs-linux-arm64-gnu": "0.1.46-alpha",
-    "brustjs-linux-x64-musl": "0.1.46-alpha",
-    "brustjs-linux-arm64-musl": "0.1.46-alpha"
+    "brustjs-darwin-x64": "0.1.48-alpha",
+    "brustjs-darwin-arm64": "0.1.48-alpha",
+    "brustjs-linux-x64-gnu": "0.1.48-alpha",
+    "brustjs-linux-arm64-gnu": "0.1.48-alpha",
+    "brustjs-linux-x64-musl": "0.1.48-alpha",
+    "brustjs-linux-arm64-musl": "0.1.48-alpha"
   },
   "peerDependencies": {
     "react": "^19.2.6",

package/runtime/cli/build.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
-import { copyFile, cp, mkdir, readdir, rm } from 'node:fs/promises'
+import { copyFile, cp, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
 import path, { isAbsolute, resolve } from 'node:path'
 import type { BunPlugin } from 'bun'
 import { emitNativeTemplates } from './native-routes-emit.ts'
@@ -144,6 +145,7 @@ export interface ParsedArgs {
   target: string // --target value (default 'auto')
   ssg: boolean // --ssg — prerender static routes after the build
   ssgOut: string | null // --ssg-out value (absolute); null → <outDir>/static computed later
+  generatorVersion: boolean // false ⇔ --no-generator-version (name-only generator tag)
 }
 
 /** Parse `brust build` argv. Pure (no fs access, no process.exit) so it's
@@ -154,6 +156,7 @@ export function parseArgs(args: string[]): ParsedArgs {
   let target = 'auto'
   let ssg = false
   let ssgOut: string | undefined
+  let generatorVersion = true
 
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
@@ -176,6 +179,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       }
     } else if (a === '--ssg') {
       ssg = true
+    } else if (a === '--no-generator-version') {
+      generatorVersion = false
     } else if (a === '--ssg-out') {
       ssgOut = args[++i]
       if (!ssgOut) {
@@ -213,7 +218,7 @@ export function parseArgs(args: string[]): ParsedArgs {
   }
   const ssgOutPath = ssgOut ? (isAbsolute(ssgOut) ? ssgOut : resolve(cwd, ssgOut)) : null
 
-  return { entry: entryPath, outDir: outPath, target, ssg, ssgOut: ssgOutPath }
+  return { entry: entryPath, outDir: outPath, target, ssg, ssgOut: ssgOutPath, generatorVersion }
 }
 
 export async function runBuild(args: string[]): Promise<void> {
@@ -321,6 +326,22 @@ export async function runBuild(args: string[]): Promise<void> {
   // the same dual-emit the jinja mirror below does). Strict no-op without md
   // routes: no files, no dirs, byte-identical dist.
   const jinjaDir = path.join(outDir, 'jinja')
+
+  // Generator tag decision — baked at build time into BOTH jinja dirs so every
+  // runtime path (prebuilt dist reads <distDir>/jinja; dev/source reads
+  // .brust/jinja) picks up the same artifact. Runs unconditionally: even a
+  // React-only app with zero native/md routes needs the artifact so the React
+  // stream injector and X-Powered-By thread share the same decision.
+  // The .brust/jinja write is defense-in-depth: the 4.1 mirror cp below
+  // overwrites it with identical content, but this write must NOT be removed —
+  // it keeps the artifact correct even if that cp ever becomes conditional.
+  {
+    const { generatorStrings, writeGeneratorArtifact } = await import('../generator.ts')
+    const gen = generatorStrings(parsed.generatorVersion)
+    writeGeneratorArtifact(jinjaDir, gen)
+    writeGeneratorArtifact(path.join(process.cwd(), '.brust', 'jinja'), gen)
+  }
+
   let mdIslands = new Map<string, string>()
   if (existsSync(routesFile) && loadedRoutes !== undefined) {
     const { emitMdArtifacts } = await import('../md/emit.ts')
@@ -345,7 +366,17 @@ export async function runBuild(args: string[]): Promise<void> {
   const islandMap = existsSync(routesFile)
     ? scanIslandChunks(routesFile, mdIslands)
     : new Map<string, string>()
-  if (islandMap.size > 0) {
+  // `fallback: 'client'` SSG routes need the islands RUNTIME (_bootstrap.js
+  // drives the client takeover; _react*.js back the fallback chunk's
+  // externals) even when the app ships ZERO islands — buildIslands with an
+  // empty map emits exactly those runtime files. Without this, the fallback
+  // shell references a /_brust/islands/_bootstrap.js that was never built.
+  const needsFallbackRuntime =
+    parsed.ssg &&
+    ((loadedRoutes ?? []) as { chain?: Array<{ ssg?: { fallback?: string } }> }[]).some(
+      (r) => r.chain?.at(-1)?.ssg?.fallback === 'client',
+    )
+  if (islandMap.size > 0 || needsFallbackRuntime) {
     const islandsOutDir = path.join(outDir, 'islands')
     const result = await buildIslands(islandMap, {
       outDir: islandsOutDir,
@@ -570,22 +601,108 @@ export async function runBuild(args: string[]): Promise<void> {
     console.log(`[brust build] native:  ${name}`)
   }
 
+  // 7.5. SSG fallback chunks (--ssg only): for every route whose LEAF declares
+  // `ssg.fallback: 'client'`, bundle a browser chunk that re-exports the leaf
+  // component + its `clientLoader` (generated entry → islands buildOne, react
+  // externals, content-addressed `Fallback_<Name>_<hash>.js`). Constraint
+  // (documented in the spec): the leaf Component must be a DEFAULT import in
+  // routes.tsx (scanImports resolution), and its file must export clientLoader.
+  // Step 8 hands these to exportStatic (shell/payload crawl + manifest + 404).
+  const ssgFallbacks: Array<{ pattern: string; chunk: string }> = []
+  if (parsed.ssg) {
+    const fallbackRoutes = (
+      (loadedRoutes ?? []) as {
+        fullPath: string
+        chain?: Array<{ ssg?: { fallback?: string }; Component?: { name?: string } }>
+      }[]
+    ).filter((r) => r.chain?.at(-1)?.ssg?.fallback === 'client')
+    if (fallbackRoutes.length > 0) {
+      const { fallbackEntrySource, hasClientLoaderExport } = await import('./ssg.ts')
+      const { scanImports } = await import('./native-routes-emit.ts')
+      const { buildOne } = await import('../islands/build.ts')
+      const { islandChunkBasename } = await import('../islands/chunk-id.ts')
+      const importMap = scanImports(routesFile)
+      const islandsOutDir = path.join(outDir, 'islands')
+      await mkdir(islandsOutDir, { recursive: true })
+      // Temp dir for the generated entry modules; removed after the bundles land.
+      // Error paths THROW (not process.exit) so the finally's cleanup runs —
+      // exit(1) inside the try would skip it and leak the temp dir; the catch
+      // below owns stderr + exit.
+      const entryTmp = await mkdtemp(path.join(tmpdir(), 'brust-fallback-'))
+      try {
+        for (const [i, route] of fallbackRoutes.entries()) {
+          const name = route.chain?.at(-1)?.Component?.name
+          const source = name ? importMap.get(name) : undefined
+          if (!name || !source) {
+            throw new Error(
+              `[brust build] ssg: fallback 'client' on "${route.fullPath}": leaf Component must be a DEFAULT import in the routes file`,
+            )
+          }
+          const text = await readFile(source, 'utf8')
+          if (!hasClientLoaderExport(text)) {
+            throw new Error(
+              `[brust build] ssg: fallback 'client' on "${route.fullPath}": ` +
+                `${path.relative(process.cwd(), source)} must \`export const clientLoader\``,
+            )
+          }
+          const file = `Fallback_${islandChunkBasename(name, source)}.js`
+          // Index-suffixed entry name: two fallback routes may share a component
+          // NAME (different files) — the chunk name is already content-addressed.
+          const entryPath = path.join(entryTmp, `${name}_${i}.entry.ts`)
+          await writeFile(entryPath, fallbackEntrySource(source))
+          try {
+            await buildOne(
+              [entryPath],
+              islandsOutDir,
+              file,
+              ['react', 'react/jsx-runtime', 'react-dom/client'],
+              cssBuildPlugins,
+            )
+          } catch (err) {
+            // Browser-safety convention: server-only deps at the component file's
+            // top level surface here as bundle errors.
+            throw new Error(
+              `[brust build] ssg: fallback chunk for "${route.fullPath}": ${err instanceof Error ? err.message : String(err)}`,
+            )
+          }
+          ssgFallbacks.push({ pattern: route.fullPath, chunk: `/_brust/islands/${file}` })
+        }
+      } catch (err) {
+        await rm(entryTmp, { recursive: true, force: true })
+        console.error(err instanceof Error ? err.message : String(err))
+        process.exit(1)
+      }
+      await rm(entryTmp, { recursive: true, force: true })
+    }
+  }
+
   // 8. SSG export (--ssg): boot the just-built dist once and crawl every
   // statically-renderable route into <--ssg-out | outDir/static>. Reuses the
   // routes module ALREADY loaded for the MCP/css steps (loadedRoutes) — no
   // second import. Without the flag this is a strict no-op.
   if (parsed.ssg) {
-    const { collectStaticPaths, exportStatic } = await import('./ssg.ts')
-    const decisions = collectStaticPaths(
-      (loadedRoutes ?? []) as Parameters<typeof collectStaticPaths>[0],
-    )
+    const { collectStaticPaths, expandDynamicRoutes, exportStatic } = await import('./ssg.ts')
+    // Initialized to [] so the post-catch read type-checks even where
+    // process.exit isn't narrowed to `never` (exit(1) still prevents use).
+    let expanded: Awaited<ReturnType<typeof expandDynamicRoutes>> = []
+    try {
+      expanded = await expandDynamicRoutes(
+        (loadedRoutes ?? []) as Parameters<typeof expandDynamicRoutes>[0],
+      )
+    } catch (err) {
+      console.error(`[brust build] ssg: ${err instanceof Error ? err.message : String(err)}`)
+      process.exit(1)
+    }
+    const expandedCount = expanded.length - (loadedRoutes ?? []).length
+    const decisions = collectStaticPaths(expanded)
     const staticOut = parsed.ssgOut ?? path.join(outDir, 'static')
     try {
-      const { written, navWritten, skipped } = await exportStatic({
+      const { written, navWritten, fallbackWritten, skipped } = await exportStatic({
         distDir: outDir,
         entryDir,
         staticOut,
         routes: decisions,
+        fallbacks: ssgFallbacks,
       })
       const counts = new Map<string, number>()
       for (const s of skipped) {
@@ -597,9 +714,17 @@ export async function runBuild(args: string[]): Promise<void> {
         .map((r) => `${r}=${counts.get(r)}`)
         .join(', ')
       const skippedDesc = skipped.length > 0 ? ` (skipped ${skipped.length}: ${reasons})` : ''
+      const expandedDesc = expandedCount > 0 ? `, expanded ${expandedCount} dynamic page(s)` : ''
+      const fallbackDesc =
+        fallbackWritten.length > 0 ? `, ${fallbackWritten.length} fallback file(s)` : ''
       console.log(
-        `[brust build] ssg:     ${written.length} pages + ${navWritten.length} spa payloads → ${staticOut}${skippedDesc}`,
+        `[brust build] ssg:     ${written.length} pages + ${navWritten.length} spa payloads${expandedDesc}${fallbackDesc} → ${staticOut}${skippedDesc}`,
       )
+      for (const f of ssgFallbacks) {
+        console.log(
+          `[brust build] ssg:     fallback chunk ${path.basename(f.chunk)} (${f.pattern})`,
+        )
+      }
     } catch (err) {
       console.error(`[brust build] ssg: ${err instanceof Error ? err.message : String(err)}`)
       process.exit(1)

package/runtime/cli/dev.ts

@@ -10,11 +10,13 @@ const REPO_ROOT = path.resolve(import.meta.dir, '..', '..')
 interface ParsedArgs {
   entry: string
   port: number | undefined
+  generatorVersion: boolean
 }
 
 function parseArgs(args: string[]): ParsedArgs {
   let entry: string | undefined
   let port: number | undefined
+  let generatorVersion = true
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if (a === '--port') {
@@ -28,6 +30,8 @@ function parseArgs(args: string[]): ParsedArgs {
         console.error(`brust dev: invalid port ${v}`)
         process.exit(1)
       }
+    } else if (a === '--no-generator-version') {
+      generatorVersion = false
     } else if (a.startsWith('--port=')) {
       port = parseInt(a.slice('--port='.length), 10)
     } else if (a.startsWith('-')) {
@@ -50,14 +54,22 @@ function parseArgs(args: string[]): ParsedArgs {
     console.error(`brust dev: no entry file at ${entryPath}; pass a path or create ./index.ts`)
     process.exit(1)
   }
-  return { entry: entryPath, port }
+  return { entry: entryPath, port, generatorVersion }
 }
 
 export async function runDev(args: string[]): Promise<void> {
-  const { entry, port } = parseArgs(args)
+  const { entry, port, generatorVersion } = parseArgs(args)
   process.env.BRUST_DEV = '1'
   if (port !== undefined) process.env.BRUST_PORT = String(port)
 
+  // Bake the generator decision BEFORE the first emit — emitters and the boot
+  // re-emit paths all resolve <cwd>/.brust/jinja/generator.json internally.
+  const { generatorStrings, writeGeneratorArtifact } = await import('../generator.ts')
+  writeGeneratorArtifact(
+    path.join(process.cwd(), '.brust', 'jinja'),
+    generatorStrings(generatorVersion),
+  )
+
   // Sub-project J — emit .brust/jinja/<Name>.jinja templates BEFORE handing
   // off to the user's entry. The runtime loads these on boot. Dev-mode HMR
   // on .tsx edit is deferred per spec S12 (restart-to-reload for v2).

package/runtime/cli/help.ts

@@ -61,6 +61,10 @@ export const COMMANDS: CommandDef[] = [
         flag: '--ssg-out <dir>',
         desc: 'Output directory for prerendered HTML (default <out-dir>/static)',
       },
+      {
+        flag: '--no-generator-version',
+        desc: 'Drop the version from the generator meta tag + X-Powered-By header (the name stays)',
+      },
     ],
     notes: [
       'Markdown pages: routes mounted with mdRoutes(<contentDir>) compile to native',
@@ -75,6 +79,10 @@ export const COMMANDS: CommandDef[] = [
     flags: [
       { flag: '[entry]', desc: 'Entry file (default ./index.ts)' },
       { flag: '--port <n>', desc: 'Port to listen on' },
+      {
+        flag: '--no-generator-version',
+        desc: 'Drop the version from the generator meta tag + X-Powered-By header (the name stays)',
+      },
     ],
   },
   {

package/runtime/cli/native-routes-emit.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node
 import { createRequire } from 'node:module'
 import { dirname, relative, resolve } from 'node:path'
 import { buildDevClientTag } from '../dev/client.ts'
+import { insertGeneratorMeta, resolveGenerator } from '../generator.ts'
 import { islandChunkBasename } from '../islands/chunk-id.ts'
 import { DIRECTIVES_BOOTSTRAP, ISLANDS_IMPORTMAP_AND_BOOTSTRAP } from '../islands/importmap.ts'
 
@@ -527,6 +528,12 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
     nativeRoutes.length > 0 &&
     (await import('../native/build.ts')).scanDirectiveComponents(opts.entryFile).size > 0
 
+  // Generator meta: resolved INTERNALLY from the out dir's artifact (NOT a
+  // caller param) — emit re-runs from five call sites (build, dev, boot
+  // staleness, md boot re-emit, dev HMR) and a param would silently drop the
+  // tag on re-emit. Fallback (no artifact) = version-on defaults.
+  const generatorMeta = resolveGenerator(opts.outDir).meta
+
   const built: string[] = []
   for (const r of nativeRoutes) {
     const name = r.nativeTemplate!
@@ -632,8 +639,9 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
     // injection, so splice the /_brust/dev WS script in here. reEmitJinja() runs
     // this on every hot reload, so the script is always present in dev.
     const withDirectives = bakeDirectivesIfUsed(compiled.template, hasDirectives)
+    const withGenerator = insertGeneratorMeta(withDirectives, generatorMeta)
     const template =
-      process.env.BRUST_DEV === '1' ? injectDevClientIntoTemplate(withDirectives) : withDirectives
+      process.env.BRUST_DEV === '1' ? injectDevClientIntoTemplate(withGenerator) : withGenerator
     writeFileSync(outPath, template)
     built.push(name)