brustjs 0.1.47-alpha → 0.1.49-alpha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brustjs",
-  "version": "0.1.47-alpha",
+  "version": "0.1.49-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.47-alpha",
-    "brustjs-darwin-arm64": "0.1.47-alpha",
-    "brustjs-linux-x64-gnu": "0.1.47-alpha",
-    "brustjs-linux-arm64-gnu": "0.1.47-alpha",
-    "brustjs-linux-x64-musl": "0.1.47-alpha",
-    "brustjs-linux-arm64-musl": "0.1.47-alpha"
+    "brustjs-darwin-x64": "0.1.49-alpha",
+    "brustjs-darwin-arm64": "0.1.49-alpha",
+    "brustjs-linux-x64-gnu": "0.1.49-alpha",
+    "brustjs-linux-arm64-gnu": "0.1.49-alpha",
+    "brustjs-linux-x64-musl": "0.1.49-alpha",
+    "brustjs-linux-arm64-musl": "0.1.49-alpha"
   },
   "peerDependencies": {
     "react": "^19.2.6",

package/runtime/cli/build.ts

@@ -145,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
@@ -155,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]
@@ -177,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) {
@@ -214,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> {
@@ -322,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')

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)
 

package/runtime/generator.ts

@@ -0,0 +1,76 @@
+// Generator-tag decision module. ONE resolved decision { meta, header } made at
+// build time (brust build / brust dev write generator.json into every jinja out
+// dir); consumed by the jinja emitters (bake), the React stream injector, and
+// the X-Powered-By napi thread. The name "brust" is mandatory; only the version
+// substring is optional (--no-generator-version). Spec:
+// docs/superpowers/specs/2026-06-12-generator-tag-design.md
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { readVersion } from './cli/help.ts'
+
+export interface GeneratorStrings {
+  /** Full meta tag, e.g. `<meta name="generator" content="brust 0.1.48-alpha"/>` */
+  meta: string
+  /** X-Powered-By value, e.g. `brust/0.1.48-alpha` */
+  header: string
+}
+
+/** Build the resolved strings. Version comes from the brustjs package.json
+ * (readVersion never throws — "unknown" degrades to name-only, never a crash).
+ * The version is sanitized to attr/header-safe bytes; semver chars only. */
+export function generatorStrings(versionOn: boolean): GeneratorStrings {
+  const raw = readVersion()
+  const v = raw === 'unknown' ? '' : raw.replace(/[^0-9A-Za-z.+-]/g, '')
+  const withVersion = versionOn && v.length > 0
+  return {
+    meta: `<meta name="generator" content="brust${withVersion ? ` ${v}` : ''}"/>`,
+    header: withVersion ? `brust/${v}` : 'brust',
+  }
+}
+
+/** The exact head literal the Rust compiler emits for every Document template
+ * (crates/jsx-rust-compiler/src/emit_jinja.rs:110). Compiler-owned and stable. */
+const VIEWPORT_ANCHOR = '<meta name="viewport" content="width=device-width, initial-scale=1"/>'
+
+/** Insert the generator meta immediately after the compiler-emitted viewport
+ * meta. Anchor missing (non-document template) → no-op, never an error.
+ * CALLER CONTRACT: pass fresh compiler output — this function does not check
+ * for an existing tag, so calling it twice on the same string duplicates.
+ * Every emit path recompiles from source each run, which keeps this safe. */
+export function insertGeneratorMeta(jinja: string, metaTag: string): string {
+  const at = jinja.indexOf(VIEWPORT_ANCHOR)
+  if (at === -1) return jinja
+  const end = at + VIEWPORT_ANCHOR.length
+  return jinja.slice(0, end) + metaTag + jinja.slice(end)
+}
+
+/** Write the decision artifact into `dir` (a jinja out dir), creating it. */
+export function writeGeneratorArtifact(dir: string, strings: GeneratorStrings): void {
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(path.join(dir, 'generator.json'), JSON.stringify(strings))
+}
+
+/** Read the artifact; null on missing/malformed (caller decides the fallback). */
+export function readGeneratorArtifact(dir: string): GeneratorStrings | null {
+  try {
+    const raw = readFileSync(path.join(dir, 'generator.json'), 'utf8')
+    // unknown + explicit narrowing (not a cast): a JSON `null`/non-object body
+    // must reach the `return null` below by DESIGN, not by riding the catch.
+    const p: unknown = JSON.parse(raw)
+    if (typeof p === 'object' && p !== null) {
+      const { meta, header } = p as Record<string, unknown>
+      if (typeof meta === 'string' && typeof header === 'string') {
+        return { meta, header }
+      }
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/** Artifact if present, else version-on defaults — the spec's fallback policy
+ * (an old dist with no artifact behaves as default = version on). */
+export function resolveGenerator(dir: string): GeneratorStrings {
+  return readGeneratorArtifact(dir) ?? generatorStrings(true)
+}

package/runtime/index.d.ts

@@ -279,6 +279,12 @@ export interface ServeOptions {
   tuning?: ServeTuning
   /** Optional action prefix override. Defaults to `/_brust/action`. */
   actionPrefix?: string
+  /**
+   * `X-Powered-By` header value (e.g. `brust/0.1.48-alpha`). Single-line
+   * ASCII; omit to skip the header. The TS runtime always passes it (name
+   * mandatory, version per the build's generator.json).
+   */
+  generator?: string
   /**
    * Optional in-process TLS: PEM certificate (chain) path. When BOTH this and
    * `tls_key_path` are present, the server terminates TLS itself (ALPN

package/runtime/index.js

@@ -77,8 +77,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-android-arm64')
         const bindingPackageVersion = require('brustjs-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -93,8 +93,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-android-arm-eabi')
         const bindingPackageVersion = require('brustjs-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -114,8 +114,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-win32-x64-gnu')
         const bindingPackageVersion = require('brustjs-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -130,8 +130,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-win32-x64-msvc')
         const bindingPackageVersion = require('brustjs-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -147,8 +147,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-win32-ia32-msvc')
         const bindingPackageVersion = require('brustjs-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -163,8 +163,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-win32-arm64-msvc')
         const bindingPackageVersion = require('brustjs-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -182,8 +182,8 @@ function requireNative() {
     try {
       const binding = require('brustjs-darwin-universal')
       const bindingPackageVersion = require('brustjs-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -198,8 +198,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-darwin-x64')
         const bindingPackageVersion = require('brustjs-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -214,8 +214,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-darwin-arm64')
         const bindingPackageVersion = require('brustjs-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-freebsd-x64')
         const bindingPackageVersion = require('brustjs-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -250,8 +250,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-freebsd-arm64')
         const bindingPackageVersion = require('brustjs-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -271,8 +271,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-x64-musl')
           const bindingPackageVersion = require('brustjs-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -287,8 +287,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-x64-gnu')
           const bindingPackageVersion = require('brustjs-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -305,8 +305,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-arm64-musl')
           const bindingPackageVersion = require('brustjs-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -321,8 +321,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-arm64-gnu')
           const bindingPackageVersion = require('brustjs-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -339,8 +339,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-arm-musleabihf')
           const bindingPackageVersion = require('brustjs-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -355,8 +355,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-arm-gnueabihf')
           const bindingPackageVersion = require('brustjs-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -373,8 +373,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-loong64-musl')
           const bindingPackageVersion = require('brustjs-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -389,8 +389,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-loong64-gnu')
           const bindingPackageVersion = require('brustjs-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -407,8 +407,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-riscv64-musl')
           const bindingPackageVersion = require('brustjs-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -423,8 +423,8 @@ function requireNative() {
         try {
           const binding = require('brustjs-linux-riscv64-gnu')
           const bindingPackageVersion = require('brustjs-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -440,8 +440,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-linux-ppc64-gnu')
         const bindingPackageVersion = require('brustjs-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -456,8 +456,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-linux-s390x-gnu')
         const bindingPackageVersion = require('brustjs-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-openharmony-arm64')
         const bindingPackageVersion = require('brustjs-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-openharmony-x64')
         const bindingPackageVersion = require('brustjs-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -508,8 +508,8 @@ function requireNative() {
       try {
         const binding = require('brustjs-openharmony-arm')
         const bindingPackageVersion = require('brustjs-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.1.47-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.47-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.49-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.49-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {

package/runtime/index.ts

@@ -115,6 +115,13 @@ function loadJinjaOnce(dir: string): void {
   _jinjaLoaded = true
 }
 
+// Resolved generator strings, set by the main-isolate view boot (which runs
+// before serve() binds the listener). serve() falls back to resolving the
+// artifact itself when boot hasn't stashed one (defensive — ordering holds in
+// every real entry: view registration precedes serve).
+// Main-isolate-only: the worker path resolves the artifact itself.
+let resolvedGeneratorStrings: import('./generator.ts').GeneratorStrings | null = null
+
 function registerActionsInternal(endpoints: Array<{ method: string; path: string }>): number {
   return (native as any).registerActions(endpoints.map((e) => ({ method: e.method, path: e.path })))
 }
@@ -146,6 +153,10 @@ export const brust = {
       // registration index; the worker dispatches on that same index string.
       registerActionsInternal(opts.actions.endpoints)
     }
+    const { resolveGenerator } = await import('./generator.ts')
+    const path = await import('node:path')
+    const gen =
+      resolvedGeneratorStrings ?? resolveGenerator(path.resolve(process.cwd(), '.brust/jinja'))
     ;(native as any).beginServe({
       host: opts.host,
       port: opts.port,
@@ -156,6 +167,10 @@ export const brust = {
       // `actionPrefix` (not snake_case). A snake_case key is silently dropped,
       // leaving the prefix at its default — which broke custom-prefix routing.
       actionPrefix: opts.actionPrefix,
+      // X-Powered-By value from the build's generator.json (stashed by view
+      // boot; artifact fallback covers any ordering edge). Single word — no
+      // napi case-mapping trap possible.
+      generator: gen.header,
     })
     // Render slots per worker. Propagated to each worker via env (Bun Workers
     // share the OS process, so the worker reads it from process.env at
@@ -632,6 +647,13 @@ export const brust = {
       }
 
       configureJinjaDir(jinjaDir)
+      {
+        const { resolveGenerator } = await import('./generator.ts')
+        const gen = resolveGenerator(jinjaDir)
+        resolvedGeneratorStrings = gen
+        const { configureGeneratorMeta } = await import('./render/inject-generator.ts')
+        configureGeneratorMeta(gen.meta)
+      }
       loadJinjaOnce(jinjaDir)
       if (prebuilt && existsSync(jinjaDir)) {
         console.log(`[brust] main: using pre-built jinja at ${jinjaDir}`)
@@ -971,6 +993,11 @@ export const brust = {
         ? path.join(distDir!, 'jinja')
         : path.resolve(process.cwd(), '.brust/jinja')
       configureJinjaDir(workerJinjaDir)
+      {
+        const { resolveGenerator } = await import('./generator.ts')
+        const { configureGeneratorMeta } = await import('./render/inject-generator.ts')
+        configureGeneratorMeta(resolveGenerator(workerJinjaDir).meta)
+      }
 
       const { makeRenderer: make } = await import('./routes.ts')
       let wid: number | null = null

package/runtime/islands/bootstrap.ts

@@ -38,6 +38,7 @@ import {
   takeover,
   unmountFallbackRootsIn,
 } from './fallback.ts'
+import { withViewTransition } from './view-transition.ts'
 
 // Track React roots created by hydrateOne so we can unmount them before
 // removing their DOM in swapMainContent. Without this, removing the DOM
@@ -321,16 +322,21 @@ async function attemptClientFallback(
   if (!main) return false
   // From here down: the SAME post-swap sequence navigate()'s normal path runs.
   scrollPositions.set(currentPageKey, window.scrollY)
-  unmountIslandsIn(main as HTMLElement)
-  swapMainContent(main as HTMLElement, html)
-  if (title) document.title = title
-  // History BEFORE takeover: takeover derives params from location.pathname,
-  // so the URL bar must already show the destination.
-  if (mode === 'push') history.pushState({}, '', url.href)
-  else if (mode === 'replace') history.replaceState({}, '', url.href)
-  if (mode === 'none') window.scrollTo(0, scrollPositions.get(pageCacheKey(url)) ?? 0)
-  else window.scrollTo(0, 0)
-  currentPageKey = pageCacheKey(url)
+  await withViewTransition(document, () => {
+    unmountIslandsIn(main as HTMLElement)
+    swapMainContent(main as HTMLElement, html)
+    if (title) document.title = title
+    // History BEFORE takeover: takeover derives params from location.pathname,
+    // so the URL bar must already show the destination.
+    if (mode === 'push') history.pushState({}, '', url.href)
+    else if (mode === 'replace') history.replaceState({}, '', url.href)
+    if (mode === 'none') window.scrollTo(0, scrollPositions.get(pageCacheKey(url)) ?? 0)
+    else window.scrollTo(0, 0)
+    currentPageKey = pageCacheKey(url)
+  })
+  // Superseded across the view-transition await → the newer navigation owns
+  // the DOM; don't run takeover/hydrate/commit on a soon-to-be-replaced shell.
+  if (signal?.aborted) return true
   const container = main.querySelector<HTMLElement>('[data-brust-fallback-root]')
   if (!container) {
     // A fallback payload without its marker is a build bug — log it, but
@@ -423,19 +429,28 @@ export async function navigate(url: URL, mode: 'push' | 'replace' | 'none'): Pro
     }
     const main = document.querySelector('main')
     if (!main) throw new Error('navigation: no <main> element')
+    // scrollY of the LEAVING page is read before the transition (it must see
+    // the old page's position under the old key).
     scrollPositions.set(currentPageKey, window.scrollY)
-    unmountIslandsIn(main as HTMLElement)
-    swapMainContent(main as HTMLElement, html)
-    // Only a FRESH payload re-applies the server store snapshot: replaying a
-    // cached (stale) snapshot would roll back live client store state the user
-    // changed since the page was first fetched.
-    if (!cached && store) applyStoreSnapshot(store)
-    if (title) document.title = title
-    if (mode === 'push') history.pushState({}, '', url.href)
-    else if (mode === 'replace') history.replaceState({}, '', url.href)
-    if (mode === 'none') window.scrollTo(0, scrollPositions.get(key) ?? 0)
-    else window.scrollTo(0, 0)
-    hydrateMarkersIn(main as HTMLElement)
+    await withViewTransition(document, () => {
+      unmountIslandsIn(main as HTMLElement)
+      swapMainContent(main as HTMLElement, html)
+      // Only a FRESH payload re-applies the server store snapshot: replaying a
+      // cached (stale) snapshot would roll back live client store state the
+      // user changed since the page was first fetched.
+      if (!cached && store) applyStoreSnapshot(store)
+      if (title) document.title = title
+      if (mode === 'push') history.pushState({}, '', url.href)
+      else if (mode === 'replace') history.replaceState({}, '', url.href)
+      if (mode === 'none') window.scrollTo(0, scrollPositions.get(key) ?? 0)
+      else window.scrollTo(0, 0)
+      hydrateMarkersIn(main as HTMLElement)
+    })
+    // The view-transition await is a new suspension point: a newer navigation
+    // could have aborted us between the swap and here. The DOM is already
+    // committed (irreversible), but skip the bookkeeping so we don't advance
+    // the nav store to this stale destination — the newer navigation owns it.
+    if (ac.signal.aborted) return
     currentPageKey = key
     __navCommit(url.pathname, url.search)
   } catch (err) {

package/runtime/islands/view-transition.ts

@@ -0,0 +1,50 @@
+// Opt-in View Transitions for SPA navigation. The framework default is an
+// INSTANT swap; an app opts in by putting `data-brust-view-transitions` on
+// <html> and shipping the `::view-transition-*(root)` CSS itself. The helper is
+// pure (takes `doc`) so it unit-tests without a real browser. Spec:
+// docs/superpowers/specs/2026-06-12-view-transitions-design.md
+
+/** True iff this navigation should animate: the browser supports the View
+ *  Transitions API AND the app opted in with the <html> marker. */
+export function viewTransitionsEnabled(doc: Document): boolean {
+  return (
+    typeof (doc as { startViewTransition?: unknown }).startViewTransition === 'function' &&
+    doc.documentElement.hasAttribute('data-brust-view-transitions')
+  )
+}
+
+/** Run the synchronous navigation `commit` inside a view transition when
+ *  enabled, else directly. Resolves once the DOM is committed (NOT when the
+ *  animation finishes) so caller ordering is preserved. `commit` runs EXACTLY
+ *  once on every path:
+ *   - disabled/unsupported → direct call
+ *   - startViewTransition throws synchronously (before the callback) → direct
+ *     call (the swap never happened — losing it would blank the page, B2)
+ *   - updateCallbackDone rejects (the callback ran-and-threw) → NOT re-run; the
+ *     rejection PROPAGATES so the caller can run its full-reload recovery. */
+export async function withViewTransition(doc: Document, commit: () => void): Promise<void> {
+  if (!viewTransitionsEnabled(doc)) {
+    commit()
+    return
+  }
+  const start = (
+    doc as Document & {
+      startViewTransition: (cb: () => void) => { updateCallbackDone: Promise<void> }
+    }
+  ).startViewTransition
+  let tr: { updateCallbackDone: Promise<void> }
+  try {
+    tr = start.call(doc, commit)
+  } catch {
+    commit()
+    return
+  }
+  // `updateCallbackDone` rejects ONLY when the update callback (`commit`) threw
+  // — animation failures surface on `.finished`, which we never await. So a
+  // rejection means the DOM may be half-committed: propagate it (do NOT re-run
+  // `commit`) so the caller's catch runs its error path (`__navError` +
+  // full-reload), exactly as the synchronous direct-commit branch does. A
+  // transition that is merely SKIPPED (a newer startViewTransition) still
+  // resolves `updateCallbackDone`, so this never throws on supersession.
+  await tr.updateCallbackDone
+}

package/runtime/md/emit.ts

@@ -12,6 +12,7 @@
 
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
+import { insertGeneratorMeta, resolveGenerator } from '../generator.ts'
 import {
   bakeDirectivesIfUsed,
   buildChainWrapperSource,
@@ -177,6 +178,12 @@ export async function emitMdTemplates(opts: MdEmitOpts): Promise<{
     return files.get(src.relPath)
   }
 
+  // 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
+
   // Tag-name → classification, shared across pages (one readFileSync per name).
   const resolutionCache = new Map<string, { res: MdComponentResolution; absPath: string }>()
 
@@ -328,7 +335,10 @@ export async function emitMdTemplates(opts: MdEmitOpts): Promise<{
       mdHtml = mdHtml.slice(0, at) + inlined + mdHtml.slice(at + use.marker.length)
     }
 
-    const template = spliceMdSlot(compiled.template, name, mdHtml)
+    const template = insertGeneratorMeta(
+      spliceMdSlot(compiled.template, name, mdHtml),
+      generatorMeta,
+    )
     if (countMainTags(template) > 1) {
       process.stderr.write(
         `brust: md route "${name}" has more than one <main> after splice — SPA navigation extracts only the first <main>…</main>.\n`,

package/runtime/render/inject-generator.ts

@@ -0,0 +1,71 @@
+// Render-time generator-meta injection for React-streamed HTML. The tag value
+// comes from the build's generator.json (configured at boot by BOTH the main
+// and worker isolates — module state is per-isolate, same trap as
+// configureJinjaDir). Buffered branch: splice before </head> with a duplicate
+// guard (a hand-authored generator meta wins). Streaming branch (stream.ts)
+// prepends the raw tag with the other first-chunk tags instead — no guard
+// possible there (head bytes arrive in later chunks); documented limitation.
+const ENC = new TextEncoder()
+
+let configured: string | null = null
+
+/** Seed from generator.json at boot (main + worker). null → no injection. */
+export function configureGeneratorMeta(meta: string | null): void {
+  configured = meta
+}
+
+export function getGeneratorMeta(): string | null {
+  return configured
+}
+
+const GUARD = ENC.encode('name="generator"')
+
+/** Splice `metaTag` immediately before the first `</head>` (case-insensitive).
+ * No </head> in the chunk, empty tag, or an existing generator meta → body
+ * returned untouched. Byte-level (no decode) — safe with multibyte content. */
+export function injectGeneratorMeta(body: Uint8Array, metaTag: string | null): Uint8Array {
+  if (!metaTag) return body
+  const pos = findHeadCloseTag(body)
+  if (pos < 0) return body
+  if (bytesInclude(body, GUARD, pos)) return body
+  const tagBytes = ENC.encode(metaTag)
+  const out = new Uint8Array(body.length + tagBytes.length)
+  out.set(body.subarray(0, pos), 0)
+  out.set(tagBytes, pos)
+  out.set(body.subarray(pos), pos + tagBytes.length)
+  return out
+}
+
+/** True if `needle` occurs in `hay[0..limit)`. Naive scan — head is small. */
+function bytesInclude(hay: Uint8Array, needle: Uint8Array, limit: number): boolean {
+  const max = Math.min(limit, hay.length) - needle.length
+  outer: for (let i = 0; i <= max; i++) {
+    for (let j = 0; j < needle.length; j++) {
+      if (hay[i + j] !== needle[j]) continue outer
+    }
+    return true
+  }
+  return false
+}
+
+/** Byte scan for `</head>` (letters case-insensitive) — same approach as
+ * inject-css-link.ts. Returns offset of `<` or -1. */
+function findHeadCloseTag(body: Uint8Array): number {
+  const LT = 0x3c
+  const SL = 0x2f
+  const GT = 0x3e
+  for (let i = 0, max = body.length - 6; i < max; i++) {
+    if (body[i] !== LT || body[i + 1] !== SL) continue
+    if (!isLetter(body[i + 2], 0x48)) continue // H
+    if (!isLetter(body[i + 3], 0x45)) continue // E
+    if (!isLetter(body[i + 4], 0x41)) continue // A
+    if (!isLetter(body[i + 5], 0x44)) continue // D
+    if (body[i + 6] !== GT) continue
+    return i
+  }
+  return -1
+}
+
+function isLetter(b: number, u: number): boolean {
+  return b === u || b === (u | 0x20)
+}

package/runtime/render/stream.ts

@@ -12,6 +12,7 @@ import { injectDevClient } from './inject-dev-client.ts'
 import { injectActionPrefix, getActionPrefixSnippet } from './inject-action-prefix.ts'
 import { injectBrustStore, buildStoreScripts } from './inject-store.ts'
 import { getDevClientSnippet } from '../dev/inject.ts'
+import { getGeneratorMeta, injectGeneratorMeta } from './inject-generator.ts'
 
 export interface RenderBranchStreamingArgs {
   element: ReactNode
@@ -175,6 +176,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             let body = concatBuffers(buffer, islandsUsed)
             const perRouteHrefs = args.routePath ? getCssHrefsForRoute(args.routePath) : []
             body = injectCssLink(body, [...getCssHrefs(), ...perRouteHrefs])
+            body = injectGeneratorMeta(body, getGeneratorMeta())
             body = injectDevClient(body, getDevClientSnippet())
             body = injectActionPrefix(body, getActionPrefixSnippet())
             body = injectBrustStore(body, args.storeSnapshot ?? null)
@@ -240,13 +242,15 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             const devTag = getDevClientSnippet() ?? ''
             const prefixTag = getActionPrefixSnippet() ?? ''
             const storeTag = buildStoreScripts(args.storeSnapshot ?? null)
+            const genTag = getGeneratorMeta() ?? ''
             if (
               linkTagsStr.length > 0 ||
               devTag.length > 0 ||
               prefixTag.length > 0 ||
-              storeTag.length > 0
+              storeTag.length > 0 ||
+              genTag.length > 0
             ) {
-              const prepend = encoder.encode(linkTagsStr + prefixTag + devTag + storeTag)
+              const prepend = encoder.encode(genTag + linkTagsStr + prefixTag + devTag + storeTag)
               const out = new Uint8Array(flushed.length + prepend.length)
               out.set(flushed, 0)
               out.set(prepend, flushed.length)