brustjs 0.1.52-alpha → 0.1.54-alpha

package/package.json

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

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

@@ -3,7 +3,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 { insertGeneratorMeta, insertShellMeta, resolveGenerator } from '../generator.ts'
 import { islandChunkBasename } from '../islands/chunk-id.ts'
 import { DIRECTIVES_BOOTSTRAP, ISLANDS_IMPORTMAP_AND_BOOTSTRAP } from '../islands/importmap.ts'
 
@@ -285,6 +285,11 @@ export interface NativeRouteEmitOpts {
     /** Chain nodes parent→leaf. A leaf carrying `__mdSource` is a markdown
      * page (runtime/md/routes.ts) — emitted by `emitMdTemplates`, NOT here. */
     chain?: Array<{ Component?: { name?: string }; __mdSource?: unknown }>
+    /** SPA shell signature (FlatRoute.shellId), computed in routes.ts makeFlat.
+     * Baked into the composed template's head as `<meta name="brust-shell">` so
+     * the client full-loads on a layout-chain change. Threaded here (NOT
+     * recomputed) so native + React stamp the identical signature. */
+    shellId?: string
   }[]
   /** `.brust/jinja` absolute output dir. Created if missing. */
   outDir: string
@@ -345,6 +350,7 @@ function canonicalCompileInputs(input: {
   mergedImports: Map<string, ResolvedImport>
   hasDirectives: boolean
   generatorMeta: string
+  shellId: string
   devClient: boolean
 }): string {
   return JSON.stringify({
@@ -367,6 +373,7 @@ function canonicalCompileInputs(input: {
       .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)),
     hasDirectives: input.hasDirectives,
     generatorMeta: input.generatorMeta,
+    shellId: input.shellId,
     devClient: input.devClient,
   })
 }
@@ -589,7 +596,10 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<Na
     | null = null
   if (nativeRoutes.length > 0) {
     const native = await import('../index.js')
-    compileJsx = (native as { compileJsx?: typeof compileJsx }).compileJsx ?? null
+    // index.ts now re-exports a public 2-arg `compileJsx` facade; this emitter
+    // uses the raw 5-arg native binding, so cast through `unknown` to the local
+    // (full-arity) signature rather than the narrowed public one.
+    compileJsx = (native as unknown as { compileJsx?: typeof compileJsx }).compileJsx ?? null
     if (typeof compileJsx !== 'function') {
       throw new Error(
         'brust: the native addon does not expose compileJsx — rebuild it with ' +
@@ -719,6 +729,7 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<Na
             mergedImports,
             hasDirectives,
             generatorMeta,
+            shellId: r.shellId ?? '',
             devClient: process.env.BRUST_DEV === '1',
           }),
         )
@@ -763,8 +774,13 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<Na
     // this on every hot reload, so the script is always present in dev.
     const withDirectives = bakeDirectivesIfUsed(compiled.template, hasDirectives)
     const withGenerator = insertGeneratorMeta(withDirectives, generatorMeta)
+    // SPA shell signature — baked emit-side (native routes render via
+    // napiRenderJinja, not the React stream injector). shellId is threaded from
+    // routes.ts makeFlat (never recomputed here), so native + React documents
+    // carry the identical signature. Empty/missing → no-op.
+    const withShell = insertShellMeta(withGenerator, r.shellId ?? '')
     const template =
-      process.env.BRUST_DEV === '1' ? injectDevClientIntoTemplate(withGenerator) : withGenerator
+      process.env.BRUST_DEV === '1' ? injectDevClientIntoTemplate(withShell) : withShell
     writeFileSync(outPath, template)
     built.push(name)
     stats.compiled++

package/runtime/compile-jsx.ts

@@ -0,0 +1,26 @@
+// Public, typed facade over the native `compileJsx` NAPI binding. The native fn
+// takes (source, path, componentSources?, lucideIcons?, directiveNames?) — this
+// facade exposes the common 2-arg form for compiling a single self-contained
+// component (custom sections, tooling). `path` is the source location used as
+// the prefix in compiler error messages (e.g. "shop/42/section/7:0:0: …").
+// THROWS on invalid source (verified under Bun — unlike the fallible
+// napiRegister* bindings, compileJsx propagates a real throw, not a returned
+// Error). Mirrors the `templates.ts` wrapper pattern.
+import * as native from './index.js'
+
+export interface CompileJsxResult {
+  /** Compiled minijinja template. Interpolations are auto-escaped (`| e`). */
+  template: string
+  /** Island manifest JSON — `"[]"` when the component references no <Island>. */
+  islandsJson: string
+  /** SSR-component manifest JSON — `"[]"` when none. */
+  componentsJson: string
+  /** Non-fatal compiler diagnostics. */
+  warnings: string[]
+}
+
+export function compileJsx(source: string, path: string): CompileJsxResult {
+  return (
+    native as unknown as { compileJsx(source: string, path: string): CompileJsxResult }
+  ).compileJsx(source, path)
+}

package/runtime/generator.ts

@@ -44,6 +44,22 @@ export function insertGeneratorMeta(jinja: string, metaTag: string): string {
   return jinja.slice(0, end) + metaTag + jinja.slice(end)
 }
 
+/** Insert the SPA shell-signature meta immediately after the compiler-emitted
+ * viewport meta (same anchor as the generator meta — the native bake's emit-time
+ * equivalent of inject-shell-meta.ts on the React render path). Anchor missing
+ * (a fragment child template with no own head) → no-op, never an error: the
+ * signature lands in the LAYOUT's BrustPage head, which is the shell document.
+ * Empty shellId → no-op. CALLER CONTRACT: fresh compiler output per emit (no
+ * idempotency check), same as insertGeneratorMeta. */
+export function insertShellMeta(jinja: string, shellId: string): string {
+  if (!shellId) return jinja
+  const at = jinja.indexOf(VIEWPORT_ANCHOR)
+  if (at === -1) return jinja
+  const end = at + VIEWPORT_ANCHOR.length
+  const tag = `<meta name="brust-shell" content="${shellId}">`
+  return jinja.slice(0, end) + tag + 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 })

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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-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.52-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.52-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.54-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.54-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {

package/runtime/index.ts

@@ -1183,6 +1183,10 @@ export type { InvalidateArgs } from './cache.ts'
 
 export { templates } from './templates.ts'
 
+// R1 (compile half) — public TSX→minijinja compile for custom sections /
+// tooling. The native fn always existed; this exposes a typed 2-arg facade.
+export { compileJsx, type CompileJsxResult } from './compile-jsx.ts'
+
 export { getRequestContext } from './request-context.ts'
 export { cookies } from './cookies.ts'
 export type { CookieOptions } from './cookies.ts'

package/runtime/islands/bootstrap.ts

@@ -270,6 +270,34 @@ const scrollPositions = new Map<string, number>()
 // would record the leaving page's scroll under the wrong key.
 let currentPageKey = ''
 
+// SPA shell signature of the document currently in the DOM, read ONCE at boot
+// from the server-stamped <meta name="brust-shell">. navigate() compares it to a
+// nav payload's `shell`: a mismatch means the layout-ancestor chain changed, so
+// the fast in-place <main> swap would keep the WRONG shell — full-load instead.
+// NOT updated on a same-shell swap (swapMainContent only replaces <main>'s
+// children, so the head meta — and thus the signature — persists); a full load
+// re-seeds this from the fresh document at boot.
+let currentShell: string | null =
+  typeof document !== 'undefined'
+    ? (document.querySelector('meta[name="brust-shell"]')?.getAttribute('content') ?? null)
+    : null
+
+/** True when the destination's shell signature differs from the current
+ * document's — the nav must full-load to render the correct shell. The
+ * BOTH-PRESENT requirement is load-bearing: if either side is absent (an old
+ * cached payload without `shell`, a stale addon that didn't bake the meta, or
+ * the very first nav before a meta exists) we fall through to the existing swap
+ * behavior and never over-full-load. */
+function shellChanged(payloadShell: string | undefined): boolean {
+  return !!currentShell && !!payloadShell && payloadShell !== currentShell
+}
+
+/** Test-only: seed/clear the boot-read shell signature (module state, otherwise
+ * fixed at import before any test meta exists). */
+export function __setCurrentShellForTest(shell: string | null): void {
+  currentShell = shell
+}
+
 /** SPA-navigate onto a `fallback: 'client'` SSG route on a static host.
  *
  * Called from navigate() when the normal payload fetch fails: a
@@ -300,18 +328,26 @@ async function attemptClientFallback(
   if (!entry) return false
   let html: string
   let title: string | undefined
+  let shell: string | undefined
   try {
     const resp = await fetch(entry.payload, { headers: { Accept: 'application/json' } })
     if (!resp.ok) return false
-    const payload = (await resp.json()) as { html?: unknown; title?: unknown }
+    const payload = (await resp.json()) as { html?: unknown; title?: unknown; shell?: unknown }
     if (typeof payload.html !== 'string') return false
     html = payload.html
     title = typeof payload.title === 'string' ? payload.title : undefined
+    shell = typeof payload.shell === 'string' ? payload.shell : undefined
   } catch {
     return false
   }
   // Superseded while fetching → a newer navigation owns the DOM; do nothing.
   if (signal?.aborted) return false
+  // Same shell-signature guard as the normal path: a layout-chain change must
+  // full-load (correct shell), not swap into the current <main>.
+  if (shellChanged(shell)) {
+    location.href = url.href
+    return true
+  }
   // Same full-document guard as the normal path: a standalone-route shell
   // cannot be swapped into the current <main> — authoritative full load.
   if (isFullDocumentPayload(html)) {
@@ -418,6 +454,16 @@ export async function navigate(url: URL, mode: 'push' | 'replace' | 'none'): Pro
       if (ac.signal.aborted) return
     }
     const { html, title, store } = payload
+    // SPA shell signature: if the destination's layout-ancestor chain differs
+    // from the current document's, the fast <main> swap would keep the WRONG
+    // shell (studio bug: login shown without AppLayout chrome, logout keeps it).
+    // Full-load so the correct shell renders. Guarded both-present (see
+    // shellChanged) — backward/stale-addon safe. Same-shell nav falls through
+    // to the existing swap untouched.
+    if (shellChanged(payload.shell)) {
+      location.href = url.href
+      return
+    }
     // A standalone (no-<main>) route ships its FULL document here. We can't swap
     // that into the current shell's <main> without nesting a second document
     // (duplicate chrome — the classic two-topbars artifact), and the current

package/runtime/islands/page-cache.ts

@@ -10,6 +10,13 @@ export interface PagePayload {
   html: string
   title: string
   store?: Record<string, Record<string, unknown>> | null
+  /** SPA shell signature of the destination route (FlatRoute.shellId). The
+   * client compares it to the current document's `<meta name="brust-shell">`
+   * and full-loads on mismatch (correct shell), keeping the fast in-place swap
+   * when they match. Optional: old cached payloads / stale addons omit it, in
+   * which case the client falls through to the existing swap behavior. Round-
+   * trips through the cache automatically (the whole parsed object is stored). */
+  shell?: string
   /** True when this payload was delivered at HTTP 404 (a rendered catch-all
    * page, NOT a transport error). The caller swaps it in-place like any other
    * payload but must NOT cache it — a 404 is not a stable, re-servable entry,

package/runtime/render/inject-shell-meta.ts

@@ -0,0 +1,68 @@
+// Render-time SPA shell-signature injection for React-streamed HTML. Mirrors
+// inject-generator.ts exactly (the generator-meta dual-path precedent): the
+// buffering branch splices `<meta name="brust-shell" content="…">` before
+// </head> with a presence guard; the streaming branch (stream.ts) prepends the
+// raw tag with the other first-chunk tags instead. The signature comes from the
+// matched route's FlatRoute.shellId, threaded through RenderBranchStreamingArgs.
+//
+// The client (bootstrap.ts) reads this meta at boot and full-loads when a nav
+// payload's `shell` differs — so a layout-chain change renders the correct shell.
+const ENC = new TextEncoder()
+
+/** Build the shell-signature meta tag for a given shellId (no escaping needed —
+ * shellId is a server-derived `L:`/`S:` token of component names / route paths,
+ * not user input). Empty → empty string (the inject path no-ops). */
+export function shellMetaTag(shellId: string): string {
+  return shellId ? `<meta name="brust-shell" content="${shellId}">` : ''
+}
+
+const GUARD = ENC.encode('name="brust-shell"')
+
+/** Splice the shell meta immediately before the first `</head>` (case-insensitive).
+ * No </head> in the chunk, empty shellId, or an existing brust-shell meta → body
+ * returned untouched. Byte-level (no decode) — safe with multibyte content. */
+export function injectShellMeta(body: Uint8Array, shellId: string): Uint8Array {
+  if (!shellId) return body
+  const pos = findHeadCloseTag(body)
+  if (pos < 0) return body
+  if (bytesInclude(body, GUARD, pos)) return body
+  const tagBytes = ENC.encode(shellMetaTag(shellId))
+  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). 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

@@ -13,6 +13,7 @@ import { injectActionPrefix, getActionPrefixSnippet } from './inject-action-pref
 import { injectBrustStore, buildStoreScripts } from './inject-store.ts'
 import { getDevClientSnippet } from '../dev/inject.ts'
 import { getGeneratorMeta, injectGeneratorMeta } from './inject-generator.ts'
+import { injectShellMeta, shellMetaTag } from './inject-shell-meta.ts'
 
 export interface RenderBranchStreamingArgs {
   element: ReactNode
@@ -56,6 +57,10 @@ export interface RenderBranchStreamingArgs {
    * SSG fallback shells need the bootstrap (client takeover runtime) on pages
    * that may have zero real islands. */
   forceIslands?: boolean
+  /** The matched route's SPA shell signature (FlatRoute.shellId). Stamped into
+   * the document head as `<meta name="brust-shell">` so the client can full-load
+   * on a layout-chain change. Empty/undefined → no injection (mirror generator). */
+  shellId?: string
 }
 
 const encoder = new TextEncoder()
@@ -177,6 +182,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             const perRouteHrefs = args.routePath ? getCssHrefsForRoute(args.routePath) : []
             body = injectCssLink(body, [...getCssHrefs(), ...perRouteHrefs])
             body = injectGeneratorMeta(body, getGeneratorMeta())
+            body = injectShellMeta(body, args.shellId ?? '')
             body = injectDevClient(body, getDevClientSnippet())
             body = injectActionPrefix(body, getActionPrefixSnippet())
             body = injectBrustStore(body, args.storeSnapshot ?? null)
@@ -243,14 +249,18 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             const prefixTag = getActionPrefixSnippet() ?? ''
             const storeTag = buildStoreScripts(args.storeSnapshot ?? null)
             const genTag = getGeneratorMeta() ?? ''
+            const shellTag = shellMetaTag(args.shellId ?? '')
             if (
               linkTagsStr.length > 0 ||
               devTag.length > 0 ||
               prefixTag.length > 0 ||
               storeTag.length > 0 ||
-              genTag.length > 0
+              genTag.length > 0 ||
+              shellTag.length > 0
             ) {
-              const prepend = encoder.encode(genTag + linkTagsStr + prefixTag + devTag + storeTag)
+              const prepend = encoder.encode(
+                genTag + shellTag + linkTagsStr + prefixTag + devTag + storeTag,
+              )
               const out = new Uint8Array(flushed.length + prepend.length)
               out.set(flushed, 0)
               out.set(prepend, flushed.length)

package/runtime/routes.ts

@@ -567,6 +567,13 @@ export interface FlatRoute {
   /** Sub-project J — Component.name when leaf had `native: true`. Captured
    * at flatten time (build-time AST identifier), so minifier-safe. */
   nativeTemplate?: string
+  /** SPA shell signature — identity of the layout-ancestor chain. All leaves
+   * under the same layout chain share an `L:` sig (→ fast in-place <main> swap);
+   * a standalone leaf gets a unique `S:` sig (→ full document load on cross-nav,
+   * so the correct shell renders). Computed in `makeFlat`. Server stamps it into
+   * the rendered document head (`<meta name="brust-shell">`) AND the nav payload;
+   * the client full-loads on mismatch. See the SPA shell-signature design. */
+  shellId: string
   /** Catch-all (`{ path: '*' }`) marker. When true this FlatRoute is a
    * "not found" fallback: it stays in the array at its natural index (route_id
    * stable) but install SKIPS the matchit insert for it — it only renders when
@@ -787,7 +794,15 @@ function makeFlat(chain: Route[], fullPath: string): FlatRoute {
     )
   }
   const nativeTemplate = leaf.native === true && leaf.Component ? leaf.Component.name : undefined
-  return { fullPath, chain, middleware, errorBoundary, cache, nativeTemplate }
+  // SPA shell signature: the layout-ancestor chain's identity. Server runs the
+  // real module so `Component.name` is stable (not minified); fall back to the
+  // route path. Layout-wrapped leaves (ancestors.length > 0) collapse to a
+  // shared `L:` sig per chain; a standalone leaf gets a unique `S:` sig.
+  const routeIdent = (r: Route): string => r.Component?.name || r.path || '?'
+  const ancestors = chain.slice(0, -1)
+  const shellId =
+    ancestors.length > 0 ? 'L:' + ancestors.map(routeIdent).join('>') : 'S:' + routeIdent(leaf)
+  return { fullPath, chain, middleware, errorBoundary, cache, nativeTemplate, shellId }
 }
 
 /** Internal React context that carries the next-deeper rendered element to
@@ -1475,6 +1490,7 @@ export function makeRenderer(
           status: renderStatus,
           headers: flushSetCookie(verdict.headers),
           routePath: renderFlat.fullPath,
+          shellId: renderFlat.shellId,
           storeSnapshot,
           // SSG fallback shells have zero islands on the page but the
           // client-loader runtime still needs the importmap + bootstrap.
@@ -1686,6 +1702,11 @@ async function navigationBranch(
     // route (notFound === false), so the status must be forced to 404 explicitly,
     // not derived from `flat.notFound`.
     let navStatus = flat.notFound === true ? 404 : 200
+    // The shellId of the route ACTUALLY rendered into `fullHtml`. Normally the
+    // matched route, but a React notFound() swap renders the catch-all instead —
+    // the payload must report the catch-all's shell, not the matched route's,
+    // or the next hop compares against the wrong currentShell.
+    let renderedShellId: string | undefined = flat.shellId
     if (flat.nativeTemplate !== undefined) {
       fullHtml = await renderNativeRouteToHtml(call, flat, view, encoder, workerId, slot)
     } else {
@@ -1728,6 +1749,7 @@ async function navigationBranch(
         if (nfFlat) {
           try {
             fullHtml = await renderFlatToHtml(nfFlat)
+            renderedShellId = nfFlat.shellId
           } catch (nfErr) {
             // The catch-all's OWN loader/render threw (notFound or a real error):
             // ship the framework default 404 body — don't recurse into another
@@ -1735,12 +1757,16 @@ async function navigationBranch(
             console.error('[brust] catch-all nav render failed:', nfErr)
             fullHtml = DEFAULT_NOT_FOUND_BODY
             store = null
+            // Default 404 body is a full <html> doc (no <main>) → client takes
+            // the full-document path; leave shell unset so it never mis-matches.
+            renderedShellId = undefined
           }
         } else {
           // No catch-all registered for this prefix → framework default 404 body
           // shipped as a nav payload (so the client swaps it in), at 404.
           fullHtml = DEFAULT_NOT_FOUND_BODY
           store = null
+          renderedShellId = undefined
         }
       }
     }
@@ -1762,7 +1788,11 @@ async function navigationBranch(
     const titleMatch = fullHtml.match(/<title[^>]*>([\s\S]*?)<\/title>/i)
     const title = titleMatch ? titleMatch[1].replace(/<!--.*?-->/g, '').trim() : ''
 
-    const body = JSON.stringify({ html: innerHtml, title, store })
+    // `shell` is the destination route's SPA shell signature. The client
+    // compares it to the current document's <meta name="brust-shell"> and does a
+    // full document load on mismatch (correct shell), keeping the fast in-place
+    // <main> swap when they match. `flat` is the matched destination FlatRoute.
+    const body = JSON.stringify({ html: innerHtml, title, store, shell: renderedShellId })
     await emitSingleChunkResponse(
       view,
       napi,

package/types/cli/native-routes-emit.d.ts

@@ -103,6 +103,11 @@ export interface NativeRouteEmitOpts {
             };
             __mdSource?: unknown;
         }>;
+        /** SPA shell signature (FlatRoute.shellId), computed in routes.ts makeFlat.
+         * Baked into the composed template's head as `<meta name="brust-shell">` so
+         * the client full-loads on a layout-chain change. Threaded here (NOT
+         * recomputed) so native + React stamp the identical signature. */
+        shellId?: string;
     }[];
     /** `.brust/jinja` absolute output dir. Created if missing. */
     outDir: string;

package/types/compile-jsx.d.ts

@@ -0,0 +1,11 @@
+export interface CompileJsxResult {
+    /** Compiled minijinja template. Interpolations are auto-escaped (`| e`). */
+    template: string;
+    /** Island manifest JSON — `"[]"` when the component references no <Island>. */
+    islandsJson: string;
+    /** SSR-component manifest JSON — `"[]"` when none. */
+    componentsJson: string;
+    /** Non-fatal compiler diagnostics. */
+    warnings: string[];
+}
+export declare function compileJsx(source: string, path: string): CompileJsxResult;

package/types/generator.d.ts

@@ -14,6 +14,14 @@ export declare function generatorStrings(versionOn: boolean): GeneratorStrings;
  * 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 declare function insertGeneratorMeta(jinja: string, metaTag: string): string;
+/** Insert the SPA shell-signature meta immediately after the compiler-emitted
+ * viewport meta (same anchor as the generator meta — the native bake's emit-time
+ * equivalent of inject-shell-meta.ts on the React render path). Anchor missing
+ * (a fragment child template with no own head) → no-op, never an error: the
+ * signature lands in the LAYOUT's BrustPage head, which is the shell document.
+ * Empty shellId → no-op. CALLER CONTRACT: fresh compiler output per emit (no
+ * idempotency check), same as insertGeneratorMeta. */
+export declare function insertShellMeta(jinja: string, shellId: string): string;
 /** Write the decision artifact into `dir` (a jinja out dir), creating it. */
 export declare function writeGeneratorArtifact(dir: string, strings: GeneratorStrings): void;
 /** Read the artifact; null on missing/malformed (caller decides the fallback). */

package/types/index.d.ts

@@ -217,6 +217,7 @@ export type { IslandsBuildResult, BuildIslandsOptions } from './islands/build.ts
 export { cache } from './cache.ts';
 export type { InvalidateArgs } from './cache.ts';
 export { templates } from './templates.ts';
+export { compileJsx, type CompileJsxResult } from './compile-jsx.ts';
 export { getRequestContext } from './request-context.ts';
 export { cookies } from './cookies.ts';
 export type { CookieOptions } from './cookies.ts';

package/types/render/inject-shell-meta.d.ts

@@ -0,0 +1,8 @@
+/** Build the shell-signature meta tag for a given shellId (no escaping needed —
+ * shellId is a server-derived `L:`/`S:` token of component names / route paths,
+ * not user input). Empty → empty string (the inject path no-ops). */
+export declare function shellMetaTag(shellId: string): string;
+/** Splice the shell meta immediately before the first `</head>` (case-insensitive).
+ * No </head> in the chunk, empty shellId, or an existing brust-shell meta → body
+ * returned untouched. Byte-level (no decode) — safe with multibyte content. */
+export declare function injectShellMeta(body: Uint8Array, shellId: string): Uint8Array;

package/types/render/stream.d.ts

@@ -33,6 +33,10 @@ export interface RenderBranchStreamingArgs {
      * SSG fallback shells need the bootstrap (client takeover runtime) on pages
      * that may have zero real islands. */
     forceIslands?: boolean;
+    /** The matched route's SPA shell signature (FlatRoute.shellId). Stamped into
+     * the document head as `<meta name="brust-shell">` so the client can full-load
+     * on a layout-chain change. Empty/undefined → no injection (mirror generator). */
+    shellId?: string;
 }
 /** JSON.stringify the per-chunk meta. Defaults match the renderToString
  * path so single-chunk responses keep their existing wire shape. */

package/types/routes.d.ts

@@ -367,6 +367,13 @@ export interface FlatRoute {
     /** Sub-project J — Component.name when leaf had `native: true`. Captured
      * at flatten time (build-time AST identifier), so minifier-safe. */
     nativeTemplate?: string;
+    /** SPA shell signature — identity of the layout-ancestor chain. All leaves
+     * under the same layout chain share an `L:` sig (→ fast in-place <main> swap);
+     * a standalone leaf gets a unique `S:` sig (→ full document load on cross-nav,
+     * so the correct shell renders). Computed in `makeFlat`. Server stamps it into
+     * the rendered document head (`<meta name="brust-shell">`) AND the nav payload;
+     * the client full-loads on mismatch. See the SPA shell-signature design. */
+    shellId: string;
     /** Catch-all (`{ path: '*' }`) marker. When true this FlatRoute is a
      * "not found" fallback: it stays in the array at its natural index (route_id
      * stable) but install SKIPS the matchit insert for it — it only renders when