brustjs 0.1.26-alpha → 0.1.27-alpha

package/package.json

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

package/runtime/cli/jinja-staleness.ts

@@ -0,0 +1,50 @@
+import { type Dirent, existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+// Dirs that never hold authored route/component source — skip them so a stray
+// newer .tsx in a build cache or dependency doesn't force a needless recompile.
+const IGNORED_DIRS = new Set(['node_modules', '.brust', 'dist', '.git'])
+
+/** Walk `dir` recursively, returning the newest mtime (ms) of any `.tsx` file
+ * found, or 0 when there are none. Ignored dirs (build caches, deps) are pruned. */
+function newestTsxMtime(dir: string): number {
+  let newest = 0
+  let entries: Dirent[]
+  try {
+    entries = readdirSync(dir, { withFileTypes: true }) as Dirent[]
+  } catch {
+    return newest
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRS.has(entry.name)) continue
+      newest = Math.max(newest, newestTsxMtime(join(dir, entry.name)))
+    } else if (entry.isFile() && entry.name.endsWith('.tsx')) {
+      try {
+        newest = Math.max(newest, statSync(join(dir, entry.name)).mtimeMs)
+      } catch {
+        // file vanished mid-walk — ignore
+      }
+    }
+  }
+  return newest
+}
+
+/** True when the emitted native templates in `jinjaDir` are missing or older
+ * than the authored `.tsx` sources under `scanRoot` — i.e. a boot-time
+ * recompile is warranted so `bun run <entry>` (source mode) doesn't require a
+ * prior `brust build`, and an edited page is picked up without a stale render.
+ *
+ * Staleness = the build marker (`_manifest.json`, written last by
+ * `emitNativeTemplates`) is absent, OR any source `.tsx` is newer than it. */
+export function isJinjaStale(scanRoot: string, jinjaDir: string): boolean {
+  const manifestPath = join(jinjaDir, '_manifest.json')
+  if (!existsSync(manifestPath)) return true
+  let manifestMtime: number
+  try {
+    manifestMtime = statSync(manifestPath).mtimeMs
+  } catch {
+    return true
+  }
+  return newestTsxMtime(scanRoot) > manifestMtime
+}

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

@@ -635,6 +635,14 @@ export function reconcileIslandManifest(
 
   const raw = JSON.parse(readFileSync(islandsJsonPath, 'utf8')) as RawIslandEntry[]
 
+  // sourcePath is written PROJECT-RELATIVE (relative to the build's cwd), never
+  // the build machine's absolute path — the absolute path leaks the developer's
+  // username into shipped dist/jinja artifacts, and a relative path survives the
+  // dual-emit copy into `.brust/jinja` (both dirs sit directly under cwd, so the
+  // same relative string resolves correctly from either). The runtime
+  // (`loadIslandManifest`) rehydrates it to an absolute path against cwd before
+  // the SSR import. Mirrors the .components.json contract (emitComponentArtifacts).
+  const projectRoot = process.cwd()
   const enriched: EnrichedIslandEntry[] = raw.map((entry) => {
     const sourcePath = pageImports.get(entry.component)
     if (!sourcePath) {
@@ -642,7 +650,7 @@ export function reconcileIslandManifest(
         `island component "${entry.component}" in native route "${routeName}" has no matching import in the page source (expected \`import ${entry.component} from "..."\`)`,
       )
     }
-    return { ...entry, sourcePath }
+    return { ...entry, sourcePath: relative(projectRoot, sourcePath).replaceAll('\\', '/') }
   })
 
   writeFileSync(islandsJsonPath, JSON.stringify(enriched))

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

package/runtime/index.ts

@@ -459,6 +459,39 @@ export const brust = {
       const jinjaDir = prebuilt
         ? path.join(distDir!, 'jinja')
         : path.resolve(process.cwd(), '.brust/jinja')
+
+      // Source mode (`bun run <entry>`, not prebuilt): the emitted native
+      // templates in `.brust/jinja` may be missing (never built) or older than
+      // the authored `.tsx` (edited since). Recompile them at boot so a native
+      // route doesn't 404/stale without a prior `brust build` — the "must build
+      // first" papercut. `brust dev` already emits before this boot, so the
+      // staleness check is a no-op there; prebuilt ships the templates and skips
+      // entirely. A compile failure warns and continues (non-native routes still
+      // boot). The heavy emitter is imported lazily so it never enters the hot
+      // path (or the prebuilt bundle's live code).
+      if (!prebuilt) {
+        const routesPath = path.join(scanRoot, 'routes.tsx')
+        if (existsSync(routesPath)) {
+          const { isJinjaStale } = await import('./cli/jinja-staleness.ts')
+          if (isJinjaStale(scanRoot, jinjaDir)) {
+            try {
+              const { emitNativeTemplates } = await import('./cli/native-routes-emit.ts')
+              await emitNativeTemplates({
+                entryFile: routesPath,
+                flatRoutes: opts.routes as { nativeTemplate?: string }[],
+                outDir: jinjaDir,
+                repoRoot: process.cwd(),
+              })
+              console.log(`[brust] main: compiled native templates → ${jinjaDir}`)
+            } catch (err) {
+              console.warn(
+                `[brust] main: native template recompile failed (run \`brust build\`): ${(err as Error).message}`,
+              )
+            }
+          }
+        }
+      }
+
       configureJinjaDir(jinjaDir)
       loadJinjaOnce(jinjaDir)
       if (prebuilt && existsSync(jinjaDir)) {
@@ -708,11 +741,24 @@ export const brust = {
         console.log(`[brust] worker: mcp server ready (${mcpManifest.tools.length} tools)`)
       }
 
-      // Sub-project J note: jinja templates are loaded ONCE process-wide by the
+      // Sub-project J note: jinja TEMPLATES are loaded ONCE process-wide by the
       // main branch's loadJinjaOnce call. Rust's ENV is a process-global
       // OnceLock; Bun Workers share that process, so calling it from each
       // worker would panic on second set(). The worker reads ENV.get() at
       // napi_render_jinja time — no per-worker load needed.
+      //
+      // BUT the JS-side island/component sidecar readers (native-render.ts)
+      // resolve against a MODULE-LOCAL `_configuredJinjaDir`, and Bun Workers
+      // are separate JS isolates — that variable is unset here unless we set it.
+      // Without this, the worker falls back to `cwd/.brust/jinja`; a prebuilt
+      // run then silently depends on the build's `.brust` dual-emit, and once
+      // that cache is removed the island manifest reads null → `data-brust-props`
+      // renders empty → the client's JSON.parse throws. Configure it to the SAME
+      // dir main loads from so native island/component render works dist-only.
+      const workerJinjaDir = prebuilt
+        ? path.join(distDir!, 'jinja')
+        : path.resolve(process.cwd(), '.brust/jinja')
+      configureJinjaDir(workerJinjaDir)
 
       const { makeRenderer: make } = await import('./routes.ts')
       let wid: number | null = null

package/runtime/islands/bootstrap.ts

@@ -16,7 +16,13 @@
 import { createRoot, hydrateRoot, type Root } from 'react-dom/client'
 import { createElement } from 'react'
 import { applyStoreSnapshot } from '../store/client-hydrate.ts'
-import { __navStart, __navCommit, __navError, __navInit } from '../navigation/store.ts'
+import {
+  __navStart,
+  __navCommit,
+  __navError,
+  __navInit,
+  registerNavigator,
+} from '../navigation/store.ts'
 import { installActiveNav } from '../navigation/active-nav.ts'
 
 // Track React roots created by hydrateOne so we can unmount them before
@@ -207,7 +213,7 @@ export function isInternalLink(a: HTMLAnchorElement, event: MouseEvent): boolean
 
 let inFlight: AbortController | null = null
 
-export async function navigate(url: URL, push: boolean): Promise<void> {
+export async function navigate(url: URL, mode: 'push' | 'replace' | 'none'): Promise<void> {
   inFlight?.abort()
   const ac = new AbortController()
   inFlight = ac
@@ -229,7 +235,8 @@ export async function navigate(url: URL, push: boolean): Promise<void> {
     swapMainContent(main as HTMLElement, html)
     if (store) applyStoreSnapshot(store)
     if (title) document.title = title
-    if (push) history.pushState({}, '', url.href)
+    if (mode === 'push') history.pushState({}, '', url.href)
+    else if (mode === 'replace') history.replaceState({}, '', url.href)
     window.scrollTo(0, 0)
     hydrateMarkersIn(main as HTMLElement)
     __navCommit(url.pathname, url.search)
@@ -255,14 +262,15 @@ function installInterceptor(): void {
     e.preventDefault()
     // 'reload' = clicking the page we're already on → no-op (no refetch).
     if (intent === 'reload') return
-    void navigate(new URL(a.href, location.href), /* push */ true)
+    void navigate(new URL(a.href, location.href), 'push')
   })
   window.addEventListener('popstate', () => {
-    void navigate(new URL(location.href), /* push */ false)
+    void navigate(new URL(location.href), 'none')
   })
 }
 
 if (typeof document !== 'undefined') {
+  registerNavigator((url, replace) => navigate(url, replace ? 'replace' : 'push'))
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', () => {
       __navInit(location.pathname, location.search)

package/runtime/islands/native-render.ts

@@ -128,6 +128,17 @@ export function loadIslandManifest(
     manifestCache.set(abs, null)
     return null
   }
+  // sourcePath ships PROJECT-RELATIVE (no leaked absolute build path). Rehydrate
+  // it to an absolute path against cwd so the SSR `import(entry.sourcePath)` in
+  // resolveIslandContext resolves regardless of where the manifest lives. An
+  // already-absolute path (old manifests, unit-test stubs) passes through.
+  if (parsed) {
+    for (const entry of parsed) {
+      if (entry.sourcePath && !path.isAbsolute(entry.sourcePath)) {
+        entry.sourcePath = path.resolve(process.cwd(), entry.sourcePath)
+      }
+    }
+  }
   manifestCache.set(abs, parsed)
   return parsed
 }

package/runtime/navigation/index.ts

@@ -11,3 +11,5 @@ export {
   onNavigateError,
 } from './store.ts'
 export { installActiveNav } from './active-nav.ts'
+export { navigate, buildSearch } from './navigate.ts'
+export type { NavigateOptions, QueryInit, QueryValue } from './navigate.ts'

package/runtime/navigation/navigate.ts

@@ -0,0 +1,58 @@
+// runtime/navigation/navigate.ts — public imperative SPA navigation for
+// brustjs/navigation. DOM-free at import (touches location/history only at call
+// time, like active-nav.ts); delegates the swap to the navigator bootstrap
+// registers, so this module never imports DOM/island code.
+import { _getNavigator } from './store.ts'
+
+export type QueryValue = string | number | boolean
+export type QueryInit = Record<string, QueryValue | null | undefined | ReadonlyArray<QueryValue>>
+export interface NavigateOptions {
+  query?: QueryInit
+  replace?: boolean
+}
+
+function applyQuery(params: URLSearchParams, query: QueryInit): void {
+  for (const key of Object.keys(query)) {
+    const v = query[key]
+    params.delete(key)
+    if (v === null || v === undefined) continue
+    if (Array.isArray(v)) {
+      for (const item of v) params.append(key, String(item))
+    } else {
+      params.append(key, String(v as QueryValue))
+    }
+  }
+}
+
+/** Serialize a query object to a `?...` string (or '' when empty). Pure, DOM-free. */
+export function buildSearch(query: QueryInit): string {
+  const params = new URLSearchParams()
+  applyQuery(params, query)
+  const s = params.toString()
+  return s ? `?${s}` : ''
+}
+
+/** Programmatic SPA navigation. Resolves `path` against the current location,
+ * merges `options.query` over any query already in `path` (each key replaces all
+ * base occurrences; null/undefined deletes), then delegates to the registered
+ * navigator (full SPA swap + nav-state lifecycle). No navigator registered (no
+ * islands bootstrap) → full-document load so the call still navigates. */
+export async function navigate(path: string, options?: NavigateOptions): Promise<void> {
+  // navigate() is a client-only action (resolves against location + drives the DOM
+  // swap). Guard the bare `location` access so a server-side call surfaces a
+  // legible error instead of a raw `ReferenceError` (mirrors active-nav.ts's
+  // typeof-guard discipline; see the SSR non-goal in the design).
+  if (typeof location === 'undefined') {
+    throw new Error(
+      '[brust] navigate() is a client-only action — no location/DOM available (called during SSR?)',
+    )
+  }
+  const url = new URL(path, location.href)
+  if (options?.query) applyQuery(url.searchParams, options.query)
+  const nav = _getNavigator()
+  if (nav) {
+    await nav(url, options?.replace ?? false)
+  } else {
+    location.assign(url.href)
+  }
+}

package/runtime/navigation/store.ts

@@ -46,6 +46,7 @@ interface NavInternal extends NavStore {
   // would infinite-loop "getSnapshot should be cached"). Mirrors defineStore.
   _version: number
   _snap: { value: NavState; version: number } | null
+  _navigator: ((url: URL, replace: boolean) => Promise<void>) | null
 }
 
 function createNav(): NavInternal {
@@ -62,6 +63,7 @@ function createNav(): NavInternal {
     _error: new Set(),
     _version: 0,
     _snap: null,
+    _navigator: null,
   }
 }
 
@@ -202,6 +204,16 @@ export function __navError(toPath: string, error: unknown): void {
   emit(s)
 }
 
+/** Register the SPA navigator implementation (bootstrap's swap). Last-write-wins;
+ * re-registration with the same closure (HMR / multiple chunks) is idempotent. */
+export function registerNavigator(fn: (url: URL, replace: boolean) => Promise<void>): void {
+  store()._navigator = fn
+}
+/** @internal — the registered navigator, or null when no islands bootstrap loaded. */
+export function _getNavigator(): ((url: URL, replace: boolean) => Promise<void>) | null {
+  return store()._navigator
+}
+
 // Test-only: drop the singleton so the next access rebuilds fresh signals.
 export function __resetNavForTest(): void {
   G.__BRUST_NAV__ = undefined

package/runtime/routes.ts

@@ -11,6 +11,7 @@ import { Buffer } from 'node:buffer'
 import * as native from './index.js'
 import { renderBranchStreaming } from './render/stream.ts'
 import { runInStoreContext, collectSnapshot } from './store/server-context.ts'
+import { buildStoreScripts } from './render/inject-store.ts'
 import { runInRequestCache } from './loader-cache.ts'
 import { runInRequestScope, __scope } from './request-context.ts'
 import {
@@ -729,17 +730,22 @@ export function makeRenderer(
         let data: Record<string, unknown>
         const ctx = { params: call.params, path: call.path, req: call.req }
         let chainResult: NativeChainResult
+        let storeSnapshot: Record<string, Record<string, unknown>> | null = null
         try {
           // Run the WHOLE route chain's loaders top-down (parent → leaf) and
           // merge into ONE flat context (child keys win), mirroring the React
           // chain-loader path. Wrap the entire loop in a SINGLE per-request
           // store scope so a parent loader's defineStore writes are visible to
-          // child loaders (one Map per request — NOT one per loader). No
-          // snapshot is collected and no <script> is injected on native paths —
-          // Spec B owns native store delivery (hard non-goal here).
-          chainResult = await runInRequestContext(call.req?.cookies ?? {}, () =>
-            runNativeChainLoaders(flat.chain, ctx),
-          )
+          // child loaders (one Map per request — NOT one per loader). B7: the
+          // store snapshot IS collected here, inside the request-store scope and
+          // AFTER the loaders run (the only point native store writes happen —
+          // the render is Rust-side and touches no store), feeding the
+          // document-shell `{{ __brust_store__ }}` slot below.
+          chainResult = await runInRequestContext(call.req?.cookies ?? {}, async () => {
+            const r = await runNativeChainLoaders(flat.chain, ctx)
+            storeSnapshot = collectSnapshot()
+            return r
+          })
         } catch (err) {
           console.error(`[brust] loader failed for native route ${flat.fullPath}:`, err)
           // FAST LANE: native routes take dispatch_single_chunk (no chunk
@@ -769,6 +775,24 @@ export function makeRenderer(
         } else {
           data = chainResult.data
         }
+        // B7 — native store-snapshot SSR. Fill the framework-owned
+        // `{{ __brust_store__ | safe }}` slot (emitted into every native
+        // full-document <head>) with the defineStore SSR snapshot collected
+        // inside the request-store scope above. buildStoreScripts(null) === '',
+        // so the key is always a string and both render sub-paths (the
+        // island/component JSON.parse path and the no-island encode path)
+        // inherit it for free.
+        if (data && typeof data === 'object') {
+          // `__brust_store__` is a framework-reserved render-context key. A user
+          // loader returning it would be silently overwritten here; dev-warn so
+          // the collision isn't invisible (mirrors the Set-Cookie warning below).
+          if (process.env.BRUST_DEV === '1' && '__brust_store__' in data) {
+            console.warn(
+              `[brust] native loader for "${flat.nativeTemplate}" returned a reserved "__brust_store__" key — overwritten by the store snapshot`,
+            )
+          }
+          ;(data as Record<string, unknown>).__brust_store__ = buildStoreScripts(storeSnapshot)
+        }
         const json = JSON.stringify(data)
         // napiRenderJinja has no headers param — any Set-Cookie staged by a
         // native loader is dropped on this path. Dev-warn so it's not silent.

package/runtime/tsconfig.typecheck.json

@@ -18,6 +18,7 @@
     "treaty.type-test.ts",
     "navigation/index.ts",
     "navigation/store.ts",
-    "navigation/active-nav.ts"
+    "navigation/active-nav.ts",
+    "navigation/navigate.ts"
   ]
 }