brustjs 0.1.48-alpha → 0.1.50-alpha

package/package.json

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

package/runtime/cli/build.ts

@@ -696,6 +696,12 @@ export async function runBuild(args: string[]): Promise<void> {
     const expandedCount = expanded.length - (loadedRoutes ?? []).length
     const decisions = collectStaticPaths(expanded)
     const staticOut = parsed.ssgOut ?? path.join(outDir, 'static')
+    // A GLOBAL catch-all (notFound flag + empty prefix) gets rendered into
+    // 404.html. Nested per-prefix catch-alls are live-only on static hosts
+    // (the spec's documented SSG limitation).
+    const globalNotFound = (
+      (loadedRoutes ?? []) as { notFound?: boolean; notFoundPrefix?: string }[]
+    ).some((r) => r.notFound === true && (r.notFoundPrefix ?? '') === '')
     try {
       const { written, navWritten, fallbackWritten, skipped } = await exportStatic({
         distDir: outDir,
@@ -703,6 +709,7 @@ export async function runBuild(args: string[]): Promise<void> {
         staticOut,
         routes: decisions,
         fallbacks: ssgFallbacks,
+        globalNotFound,
       })
       const counts = new Map<string, number>()
       for (const s of skipped) {

package/runtime/cli/ssg.ts

@@ -147,6 +147,14 @@ export function collectStaticPaths(flatRoutes: FlatRouteLike[]): SsgRouteDecisio
 /** Reserved sentinel param value (Phase B fallback shell crawl). */
 export const SSG_FALLBACK_SENTINEL = '__brust_fallback__'
 
+/** Definitely-unmatched URL path used to crawl the GLOBAL catch-all into
+ * 404.html: the dist server's NotFound tier renders the global catch-all at
+ * status 404 for any path no real route matches. Deliberately bogus — a
+ * double-underscore-namespaced segment no app route declares. NOT `/_brust/`-
+ * prefixed: those resolve to brust-internal handlers BEFORE route matching, so
+ * the catch-all tier would never see them. */
+export const SSG_NOT_FOUND_SENTINEL_PATH = '/__brust_not_found_sentinel__'
+
 /** Structural view of the leaf's ssg config (mirrors RouteSsgConfig). */
 export interface RouteSsgLike {
   params?: () => Array<Record<string, string>> | Promise<Array<Record<string, string>>>
@@ -263,24 +271,24 @@ export function hasClientLoaderExport(source: string): boolean {
   return /export\s*\{[^}]*\bclientLoader\b[^}]*\}/.test(code)
 }
 
-/** Static-host 404 document for `fallback: 'client'` routes: inlines the
- * [{pattern, doc}] manifest pairs; a path matching a fallback pattern stashes
- * the REAL url in sessionStorage (the takeover runtime restores it via
- * history.replaceState) and redirects to the prerendered fallback shell.
- * No match → plain 404 text. Pure string fn so the script/inline-JSON
- * contract is unit-testable. Escapes for the <script> context: `<`/`>` (no
- * `</script>`/`<!--`/`-->` sequences) and U+2028/U+2029 (legal in JSON,
- * illegal in pre-ES2019-parsed JS string literals). Patterns are
- * author-controlled — belt-and-braces, not a trust boundary. */
-export function fallback404Html(pairs: Array<{ pattern: string; doc: string }>): string {
+/** The redirect-only `<script>` for `fallback: 'client'` routes (no surrounding
+ * document): inlines the [{pattern, doc}] manifest pairs; a path matching a
+ * fallback pattern stashes the REAL url in sessionStorage (the takeover runtime
+ * restores it via history.replaceState) and redirects to the prerendered
+ * fallback shell. No match → no-op (the surrounding document is the 404 body).
+ * Extracted so it can be wrapped in the minimal `fallback404Html` shell OR
+ * injected into a crawled global-404 page (compose404Html). Pure string fn so
+ * the script/inline-JSON contract is unit-testable. Escapes for the <script>
+ * context: `<`/`>` (no `</script>`/`<!--`/`-->` sequences) and U+2028/U+2029
+ * (legal in JSON, illegal in pre-ES2019-parsed JS string literals). Patterns
+ * are author-controlled — belt-and-braces, not a trust boundary. */
+export function fallback404Script(pairs: Array<{ pattern: string; doc: string }>): string {
   const inlineJson = JSON.stringify(pairs)
     .replace(/</g, '\\u003c')
     .replace(/>/g, '\\u003e')
     .replace(/\u2028/g, '\\u2028')
     .replace(/\u2029/g, '\\u2029')
-  return `<!doctype html><html><head><meta charset="utf-8"><title>404</title></head><body>
-<p>Not found.</p>
-<script>
+  return `<script>
 (function () {
   var MANIFEST = ${inlineJson};
   function match(pattern, path) {
@@ -300,10 +308,43 @@ export function fallback404Html(pairs: Array<{ pattern: string; doc: string }>):
     }
   }
 })()
-</script></body></html>
+</script>`
+}
+
+/** Static-host 404 document for `fallback: 'client'` routes when NO global
+ * catch-all page exists: the minimal shell (`<p>Not found.</p>`) wrapping the
+ * redirect `<script>` from `fallback404Script`. When a global catch-all DOES
+ * exist its crawled page is the document and the script is injected instead
+ * (compose404Html) — this shell is unused in that case. */
+export function fallback404Html(pairs: Array<{ pattern: string; doc: string }>): string {
+  return `<!doctype html><html><head><meta charset="utf-8"><title>404</title></head><body>
+<p>Not found.</p>
+${fallback404Script(pairs)}</body></html>
 `
 }
 
+/** Inject `<script>…</script>` into `html` just before the closing `</body>`
+ * (last occurrence, case-insensitive). If the document has no `</body>` the
+ * script is appended — a static host still parses a trailing script. Used to
+ * compose the fallback redirect into a crawled global-404 page. */
+export function injectBeforeBodyClose(html: string, script: string): string {
+  const idx = html.toLowerCase().lastIndexOf('</body>')
+  if (idx === -1) return `${html}\n${script}`
+  return `${html.slice(0, idx)}${script}\n${html.slice(idx)}`
+}
+
+/** Compose the final SSG `404.html` from a crawled global-catch-all page and,
+ * when `fallback: 'client'` routes also exist, the fallback redirect `<script>`
+ * injected before `</body>`. With no fallback pairs the crawled page is
+ * returned verbatim (pure rendered 404 page). */
+export function compose404Html(
+  crawled: string,
+  fallbackPairs: Array<{ pattern: string; doc: string }>,
+): string {
+  if (fallbackPairs.length === 0) return crawled
+  return injectBeforeBodyClose(crawled, fallback404Script(fallbackPairs))
+}
+
 // ----- static export -----
 
 const READY_LINE = '[brust] listening on' // println! in brust-core server/mod.rs
@@ -415,13 +456,19 @@ export async function exportStatic(opts: {
   routes: SsgRouteDecision[]
   /** `fallback: 'client'` routes (pattern + built chunk URL) to emit shells for. */
   fallbacks?: Array<{ pattern: string; chunk: string }>
+  /** True when the app declares a GLOBAL catch-all (notFoundPrefix === ''). The
+   * crawler fetches an unmatched sentinel path (→ NotFound tier renders the
+   * catch-all at 404) and writes its HTML to staticOut/404.html, composing the
+   * fallback redirect script when fallbacks also exist. An app public/404.html
+   * still wins. */
+  globalNotFound?: boolean
 }): Promise<{
   written: string[]
   navWritten: string[]
   fallbackWritten: string[]
   skipped: SsgRouteDecision[]
 }> {
-  const { distDir, entryDir, staticOut, routes, fallbacks = [] } = opts
+  const { distDir, entryDir, staticOut, routes, fallbacks = [], globalNotFound = false } = opts
   const included = routes.filter((r) => r.include)
   const skipped = routes.filter((r) => !r.include)
 
@@ -431,7 +478,7 @@ export async function exportStatic(opts: {
   const written: string[] = []
   const navWritten: string[] = []
   const fallbackWritten: string[] = []
-  if (included.length > 0 || fallbacks.length > 0) {
+  if (included.length > 0 || fallbacks.length > 0 || globalNotFound) {
     const port = await freePort()
     const proc = Bun.spawn(['bun', join(distDir, 'index.js')], {
       env: { ...process.env, BRUST_PORT: String(port), BRUST_WORKERS: '1' },
@@ -541,6 +588,13 @@ export async function exportStatic(opts: {
         fallbackWritten.push(payloadFile)
       }
 
+      // Fallback {pattern, doc} pairs for the 404.html redirect script — also
+      // inlined in the routes.json manifest. Empty when no fallback routes.
+      const fallbackPairs = fallbacks.map((f) => ({
+        pattern: f.pattern,
+        doc: `/_brust/fallback/${fallbackDiskPath(f.pattern)}/`,
+      }))
+
       if (fallbacks.length > 0) {
         // Manifest the client takeover runtime fetches to map a 404'd path to
         // its fallback shell. doc/payload are directory-index URLs (trailing
@@ -557,19 +611,36 @@ export async function exportStatic(opts: {
         const manifestPath = join(staticOut, '_brust', 'routes.json')
         await mkdir(dirname(manifestPath), { recursive: true })
         await Bun.write(manifestPath, JSON.stringify(manifest))
+      }
 
-        // 404.html redirects non-prerendered fallback paths to their shell.
-        // An app-authored public/404.html wins — it lands via the public/
-        // copy below, and the author owns the redirect contract.
+      // 404.html, single static-host slot. Resolution:
+      //  - app public/404.html present → author owns it (lands via the public/
+      //    copy below); never overwrite, warn only when it would have mattered.
+      //  - GLOBAL catch-all → crawl an unmatched sentinel (NotFound tier renders
+      //    the catch-all at 404), use its HTML as the document; inject the
+      //    fallback redirect <script> when fallbacks ALSO exist (compose404Html).
+      //  - fallbacks only → the minimal fallback404Html shell (unchanged).
+      //  - neither → no framework 404.html (byte-identical-today).
+      if (globalNotFound || fallbacks.length > 0) {
         if (existsSync(join(entryDir, 'public', '404.html'))) {
           console.warn(
             '[brust build] ssg: public/404.html exists — NOT overwriting; your 404 page must redirect fallback routes itself (see docs)',
           )
+        } else if (globalNotFound) {
+          // Crawl the global catch-all via an unmatched path: the dist server's
+          // NotFound tier renders it at status 404. A non-404 here means the
+          // catch-all isn't wired — fail the export rather than ship a wrong
+          // (or 200) page as the 404.
+          const resp = await fetch(`http://127.0.0.1:${port}${SSG_NOT_FOUND_SENTINEL_PATH}`)
+          const body = await resp.text()
+          if (resp.status !== 404) {
+            throw new Error(
+              `global catch-all crawl GET ${SSG_NOT_FOUND_SENTINEL_PATH} → ${resp.status} (expected 404)\n${body.slice(0, 500)}`,
+            )
+          }
+          await Bun.write(join(staticOut, '404.html'), compose404Html(body, fallbackPairs))
         } else {
-          await Bun.write(
-            join(staticOut, '404.html'),
-            fallback404Html(manifest.fallbacks.map(({ pattern, doc }) => ({ pattern, doc }))),
-          )
+          await Bun.write(join(staticOut, '404.html'), fallback404Html(fallbackPairs))
         }
       }
     } catch (err) {

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

package/runtime/index.ts

@@ -245,6 +245,12 @@ export const brust = {
             }
           : null,
         nativeTemplate: r.nativeTemplate ?? null,
+        // Catch-all (`{ path: '*' }`) markers. Rust reads these via serde
+        // rename (`notFound` / `notFoundPrefix`) in a later task to skip the
+        // matchit insert + register the not-found fallback table entry.
+        // Emitting them now is harmless before Rust consumes them.
+        notFound: r.notFound === true,
+        notFoundPrefix: r.notFoundPrefix ?? '',
       }),
     )
     const result = (native as any).registerRoutes(configs)

package/runtime/islands/bootstrap.ts

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

package/runtime/islands/page-cache.ts

@@ -9,7 +9,12 @@
 export interface PagePayload {
   html: string
   title: string
-  store?: Record<string, Record<string, unknown>>
+  store?: Record<string, Record<string, unknown>> | null
+  /** 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,
+   * and caching it would poison a later real navigation to the same path. */
+  notFound?: boolean
 }
 
 /** Bound the cache so a long session can't grow memory unbounded (LRU evict). */
@@ -60,7 +65,32 @@ export async function fetchPagePayload(url: URL, signal?: AbortSignal): Promise<
     signal,
     headers: { Accept: 'application/json' },
   })
-  if (!resp.ok) throw new Error(`navigation: status ${resp.status}`)
+  // A 404 carrying a rendered page payload (the framework's catch-all 404 page)
+  // is renderable, NOT a transport error: parse it, tag it `notFound`, and hand
+  // it to the caller to swap in-place. Anything else that isn't 2xx (5xx, other
+  // statuses) is a real transport failure → throw so the caller full-reloads or
+  // tries the `fallback:'client'` takeover. A 404 whose body is empty / not a
+  // valid `{ html }` payload is ALSO a transport failure (no page to render):
+  // the json()/shape check below throws and is caught here.
+  if (!resp.ok) {
+    if (resp.status === 404) {
+      try {
+        const payload = (await resp.json()) as PagePayload
+        // `html` is the SOLE discriminator: its presence means "a renderable
+        // page came back" (vs a bare transport 404). `title`/`store` are NOT
+        // required — title may legitimately be empty, and `store` is null for a
+        // native catch-all; both have downstream guards (bootstrap applies the
+        // snapshot only when truthy, same contract as the 200 path). Requiring
+        // them here would spuriously full-reload valid 404 pages.
+        if (payload && typeof payload.html === 'string') {
+          return { ...payload, notFound: true }
+        }
+      } catch {
+        // empty / non-JSON 404 body → fall through to the transport-error throw
+      }
+    }
+    throw new Error(`navigation: status ${resp.status}`)
+  }
   const payload = (await resp.json()) as PagePayload
   setCachedPage(pageCacheKey(url), payload)
   return payload

package/runtime/islands/view-transition.ts

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

package/runtime/routes.ts

@@ -235,8 +235,25 @@ export interface NativeVerdict {
   readonly headers?: Record<string, string>
 }
 
-/** Return from a native route loader to render the route's OWN template with
- * HTTP 404. `data` (default `{}`) becomes the template context. */
+/** Signal "not found" from a route loader. ONE helper, two call shapes —
+ * matching how each render path consumes a loader result:
+ *
+ *  - NATIVE route loader: `return notFound(data?)`. The returned verdict is
+ *    inspected by `runNativeChainLoaders` and renders the route's OWN template
+ *    at HTTP 404 (`data` default `{}` becomes the template context).
+ *
+ *  - REACT route loader: `throw notFound()`. A React loader's RETURN value is
+ *    the component's `data` prop (never inspected as a verdict), so the only
+ *    way to signal not-found is to throw. The render dispatch discriminates the
+ *    thrown verdict (it is symbol-tagged — `isNativeVerdict`) BEFORE the generic
+ *    500/errorBoundary handler and renders the NEAREST catch-all (`path: '*'`)
+ *    for the route's prefix at HTTP 404 — NOT the route's own Component, NOT a
+ *    500. If no catch-all is registered for the prefix, a framework default 404
+ *    body is rendered. `data` is ignored on the React throw path (the catch-all
+ *    runs its own loader chain).
+ *
+ * Same value type (`NativeVerdict`) either way — native returns it, React
+ * throws it — so there is a single public `notFound()` API. */
 export function notFound(data?: unknown): NativeVerdict {
   return { [BRUST_VERDICT]: true, status: 404, render: true, data: data ?? {} }
 }
@@ -257,6 +274,45 @@ export function isNativeVerdict(x: unknown): x is NativeVerdict {
   )
 }
 
+/** Framework default 404 body, served when a React `notFound()` fires but no
+ * catch-all (`path: '*'`) is registered for the route's prefix — so the response
+ * is still HTTP 404 with a body (never a 500, never a crash). */
+const DEFAULT_NOT_FOUND_BODY =
+  '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>404 Not Found</title></head><body><main><h1>404</h1><p>Not found.</p></main></body></html>'
+
+/** True when a thrown value is the React `notFound()` trigger: a NativeVerdict
+ * that renders at HTTP 404 (vs a thrown `redirect()`, which is `render: false`).
+ * Distinct from ActionError (a different Symbol) and from real Errors, so the
+ * render-dispatch catch can re-render the catch-all ONLY for this case and let
+ * everything else fall through to the 500/errorBoundary path. */
+function isNotFoundTrigger(x: unknown): x is NativeVerdict {
+  return isNativeVerdict(x) && x.render === true && x.status === 404
+}
+
+/** Select the nearest catch-all (`path: '*'`) FlatRoute for an unmatched path —
+ * the JS-side mirror of Rust's `select_not_found` (routing/routes.rs). Returns
+ * the catch-all's route_id (array index) or `undefined` if none covers the path.
+ *
+ * Longest segment-prefix wins: a `notFoundPrefix` of `/docs` covers `/docs` and
+ * `/docs/...` but NOT `/docsearch`; the root catch-all (`''`) covers everything
+ * as the last resort. Identical precedence to the Rust unmatched-path tier, so a
+ * React `notFound()` selects the SAME catch-all a genuinely-unmatched path would. */
+function selectNotFound(routes: FlatRoute[], path: string): number | undefined {
+  let bestId: number | undefined
+  let bestLen = -1
+  for (let i = 0; i < routes.length; i++) {
+    const r = routes[i]
+    if (r.notFound !== true) continue
+    const p = r.notFoundPrefix ?? ''
+    const covers = p === '' || path === p || path.startsWith(`${p}/`)
+    if (covers && p.length > bestLen) {
+      bestLen = p.length
+      bestId = i
+    }
+  }
+  return bestId
+}
+
 /** Loader context passed to native chain loaders. */
 export interface NativeLoaderCtx {
   params: Record<string, string>
@@ -409,6 +465,22 @@ 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
+  /** 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
+   * matchit returns NoMatch under `notFoundPrefix`. NEVER remove a flagged
+   * entry from the flat array (that would shift every later route_id).
+   *
+   * A catch-all render is stamped HTTP 404 UNCONDITIONALLY (spec invariant 4:
+   * "never 200"). A `redirect()` from the catch-all's OWN loader still wins —
+   * redirect verdicts short-circuit and return before the 404 stamp on every
+   * path. A non-redirect verdict status, however, is overridden by 404 (a 404
+   * page is a 404, by definition). */
+  notFound?: boolean
+  /** Parent layout's path prefix this catch-all covers. Root catch-all → `''`
+   * (matches everything as last resort). Longest segment-prefix wins at match
+   * time. Never contains `*` (it's the parent prefix, not the catch-all path). */
+  notFoundPrefix?: string
 }
 
 /** Compose a child's relative path onto a parent's base path.
@@ -530,7 +602,10 @@ function assertNativeSubtree(children: Route[], where: string): void {
  * the design spec (S3). */
 export function flattenRoutes(routes: Route[]): FlatRoute[] {
   const out: FlatRoute[] = []
-  walkRoutes(routes, [], '', out)
+  // Tracks `notFoundPrefix` values already claimed by a catch-all so a second
+  // catch-all under the same prefix throws instead of silently shadowing.
+  const seenNotFoundPrefixes = new Set<string>()
+  walkRoutes(routes, [], '', out, seenNotFoundPrefixes)
   return out
 }
 
@@ -539,6 +614,7 @@ function walkRoutes(
   parentChain: Route[],
   basePath: string,
   out: FlatRoute[],
+  seenNotFoundPrefixes: Set<string>,
 ): void {
   for (const r of routes) {
     validateRoute(r, basePath)
@@ -549,11 +625,36 @@ function walkRoutes(
       continue
     }
 
+    // Catch-all (`{ path: '*' }`) — a "not found" fallback for the `basePath`
+    // subtree. It is a LEAF (no children/index) and is KEPT in the flat array
+    // at its natural index (route_id stable) flagged `notFound`. Its fullPath
+    // is set to the parent prefix (never a `*` matchit pattern) so a later
+    // install step can skip the matchit insert and rely on the flag.
+    if (r.path === '*') {
+      if (r.children && r.children.length > 0) {
+        throw new Error(`catch-all route "*" must be a leaf (no children) under "${basePath}"`)
+      }
+      // (index is already mutually exclusive with path via validateRoute.)
+      const prefix = basePath
+      if (seenNotFoundPrefixes.has(prefix)) {
+        throw new Error(
+          `duplicate catch-all route "*": only one catch-all allowed per prefix "${prefix}"`,
+        )
+      }
+      seenNotFoundPrefixes.add(prefix)
+      // Construct atomically (no post-hoc mutation) so the flag + prefix are
+      // never observable half-set. `fullPath === notFoundPrefix` by design; the
+      // install step gates the matchit-insert skip on the `notFound` flag, not
+      // on fullPath (see runtime/index.ts registerRoutes).
+      out.push({ ...makeFlat(chain, prefix), notFound: true, notFoundPrefix: prefix })
+      continue
+    }
+
     const ownPath = r.path ?? ''
     const myPath = joinPath(basePath, ownPath)
 
     if (r.children && r.children.length > 0) {
-      walkRoutes(r.children, chain, myPath, out)
+      walkRoutes(r.children, chain, myPath, out, seenNotFoundPrefixes)
     } else {
       // Leaf with a path (validated above).
       out.push(makeFlat(chain, myPath))
@@ -991,6 +1092,12 @@ export function makeRenderer(
         } else {
           data = chainResult.data
         }
+        // Catch-all (`path: '*'`) leaf rendered on an unmatched path: stamp HTTP
+        // 404 unconditionally, regardless of any verdict status. The loader does
+        // NOT need to call notFound() — being a catch-all IS the 404 signal.
+        if (flat.notFound === true) {
+          renderStatus = 404
+        }
         // 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
@@ -1127,32 +1234,89 @@ export function makeRenderer(
       return await runInRequestContext(call.req?.cookies ?? {}, async () => {
         // Computed ONCE and shared by buildRenderElement (leaf swap) and
         // renderBranchStreaming (forceIslands) so the two can never diverge.
-        const shellMode = wantsSsgFallbackShell(flat, call)
-        let element: ReactNode
-        let errorBoundary: ComponentType<{ error: Error }>
+        let shellMode = wantsSsgFallbackShell(flat, call)
+        let element: ReactNode = null
+        // The route actually rendered + its HTTP status. Normally the matched
+        // `flat` at the verdict status (404 when the matched route IS a
+        // catch-all). A React loader that `throw`s `notFound()` swaps both to
+        // the nearest catch-all at 404 below.
+        let renderFlat = flat
+        let renderStatus = flat.notFound === true ? 404 : verdict.status
         try {
           element = await buildRenderElement(call, flat, opts.getWorkerId, shellMode)
-          errorBoundary =
-            flat.errorBoundary ??
-            (({ error }) => createElement('div', null, `Internal Server Error: ${error.message}`))
         } catch (err) {
-          // Setup failure BEFORE renderToPipeableStream — loader throw, params
-          // bind throw. Shape matches the legacy "internal error" path so
-          // existing integration tests stay green.
-          console.error(`[brust] render setup failed:`, err)
-          return await emitSingleChunkResponse(
-            slotView,
-            napi,
-            workerId,
-            encoder,
-            {
-              status: 500,
-              contentType: 'text/html; charset=utf-8',
-              body: 'internal error',
-            },
-            slot,
-          )
+          if (isNotFoundTrigger(err)) {
+            // React `notFound()` trigger: abandon the matched route and render
+            // the NEAREST catch-all (same selection as a Rust-unmatched path)
+            // at HTTP 404 — NOT the route's own Component, NOT a 500. Reuse the
+            // existing 404-render machinery by re-running buildRenderElement
+            // against the catch-all's chain.
+            // nfId is the array index, which IS the route_id (catch-alls keep
+            // their natural slot — see FlatRoute.notFound), so byRouteId resolves
+            // the same flat route the Rust tier picks for an unmatched path.
+            const nfId = selectNotFound(routes, call.path)
+            const nfFlat = nfId !== undefined ? byRouteId.get(nfId) : undefined
+            renderStatus = 404
+            if (nfFlat) {
+              renderFlat = nfFlat
+              shellMode = wantsSsgFallbackShell(nfFlat, call)
+              try {
+                element = await buildRenderElement(call, nfFlat, opts.getWorkerId, shellMode)
+              } catch (nfErr) {
+                // The catch-all's OWN loader/render setup failed — don't loop;
+                // fall back to the framework default 404 body at 404.
+                console.error(`[brust] catch-all render setup failed:`, nfErr)
+                return await emitSingleChunkResponse(
+                  slotView,
+                  napi,
+                  workerId,
+                  encoder,
+                  {
+                    status: 404,
+                    contentType: 'text/html; charset=utf-8',
+                    body: DEFAULT_NOT_FOUND_BODY,
+                  },
+                  slot,
+                )
+              }
+            } else {
+              // No catch-all registered for this prefix → framework default 404
+              // body at status 404 (don't crash, don't 500).
+              return await emitSingleChunkResponse(
+                slotView,
+                napi,
+                workerId,
+                encoder,
+                {
+                  status: 404,
+                  contentType: 'text/html; charset=utf-8',
+                  body: DEFAULT_NOT_FOUND_BODY,
+                },
+                slot,
+              )
+            }
+          } else {
+            // Setup failure BEFORE renderToPipeableStream — loader throw, params
+            // bind throw. Shape matches the legacy "internal error" path so
+            // existing integration tests stay green.
+            console.error(`[brust] render setup failed:`, err)
+            return await emitSingleChunkResponse(
+              slotView,
+              napi,
+              workerId,
+              encoder,
+              {
+                status: 500,
+                contentType: 'text/html; charset=utf-8',
+                body: 'internal error',
+              },
+              slot,
+            )
+          }
         }
+        const errorBoundary: ComponentType<{ error: Error }> =
+          renderFlat.errorBoundary ??
+          (({ error }) => createElement('div', null, `Internal Server Error: ${error.message}`))
         const storeSnapshot = collectSnapshot()
         await renderBranchStreaming({
           element,
@@ -1161,9 +1325,11 @@ export function makeRenderer(
           workerId,
           napi,
           errorBoundary,
-          status: verdict.status,
+          // Catch-all (`path: '*'`) leaf rendered on an unmatched path OR a
+          // React `notFound()` swap: stamp HTTP 404 (mirrors the native path).
+          status: renderStatus,
           headers: flushSetCookie(verdict.headers),
-          routePath: flat.fullPath,
+          routePath: renderFlat.fullPath,
           storeSnapshot,
           // SSG fallback shells have zero islands on the page but the
           // client-loader runtime still needs the importmap + bootstrap.
@@ -1174,7 +1340,7 @@ export function makeRenderer(
       })
     }
     if (call.kind === 'navigation') {
-      await navigationBranch(call, byRouteId, slotView, encoder, opts.getWorkerId, slot)
+      await navigationBranch(call, byRouteId, routes, slotView, encoder, opts.getWorkerId, slot)
       return 0
     }
     if (call.kind === 'action') {
@@ -1268,6 +1434,7 @@ function renderToAwaitedString(element: ReactNode): Promise<string> {
 async function navigationBranch(
   call: Extract<RouteCall, { kind: 'navigation' }>,
   byRouteId: Map<number, FlatRoute>,
+  routes: FlatRoute[],
   view: Uint8Array,
   encoder: TextEncoder,
   getWorkerId: (() => number | null) | undefined,
@@ -1384,6 +1551,14 @@ async function navigationBranch(
     // with no headers param, so staged cookies are dropped there (same as the
     // full-document native render path).
     let navHeaders: Record<string, string> | undefined
+    // The nav-payload HTTP status. Normally 200, or 404 when the matched route
+    // IS a catch-all (rendered on a genuinely-unmatched `/_brust/page/*` path).
+    // A React loader `throw notFound()` (caught below) swaps the rendered route
+    // to the nearest catch-all and forces this to 404 — mirroring the
+    // full-document render path. NOTE: in the trigger case `flat` is the MATCHED
+    // route (notFound === false), so the status must be forced to 404 explicitly,
+    // not derived from `flat.notFound`.
+    let navStatus = flat.notFound === true ? 404 : 200
     if (flat.nativeTemplate !== undefined) {
       fullHtml = await renderNativeRouteToHtml(call, flat, view, encoder, workerId, slot)
     } else {
@@ -1393,23 +1568,54 @@ async function navigationBranch(
       // injection is needed in a NAV payload: the payload is swapped into a
       // document that already booted the bootstrap (the navigator IS the
       // bootstrap), and the takeover runtime imports its chunk itself.
-      fullHtml = await runInRequestContext(call.req?.cookies ?? {}, async () => {
-        const element = await buildRenderElement(
-          call as any,
-          flat,
-          getWorkerId,
-          wantsSsgFallbackShell(flat, call as any),
-        )
-        if (!element) throw new Error('render setup failed')
-        // Use renderToPipeableStream + onAllReady so pages with <Suspense> emit
-        // their RESOLVED markup, not the fallback. renderToString would only
-        // capture the shell — navigating SPA-style to a Suspense-using route
-        // would otherwise ship "loading…" and never recover.
-        const html = await renderToAwaitedString(element)
-        store = collectSnapshot()
-        navHeaders = flushSetCookie(undefined)
-        return html
-      })
+      const renderFlatToHtml = (target: FlatRoute): Promise<string> =>
+        runInRequestContext(call.req?.cookies ?? {}, async () => {
+          const element = await buildRenderElement(
+            call as any,
+            target,
+            getWorkerId,
+            wantsSsgFallbackShell(target, call as any),
+          )
+          if (!element) throw new Error('render setup failed')
+          // Use renderToPipeableStream + onAllReady so pages with <Suspense> emit
+          // their RESOLVED markup, not the fallback. renderToString would only
+          // capture the shell — navigating SPA-style to a Suspense-using route
+          // would otherwise ship "loading…" and never recover.
+          const html = await renderToAwaitedString(element)
+          store = collectSnapshot()
+          navHeaders = flushSetCookie(undefined)
+          return html
+        })
+      try {
+        fullHtml = await renderFlatToHtml(flat)
+      } catch (err) {
+        if (!isNotFoundTrigger(err)) throw err
+        // React `notFound()` trigger on the SPA-nav path: abandon the matched
+        // route and render the NEAREST catch-all (same selection as a
+        // Rust-unmatched path) as the nav payload at HTTP 404 — NOT a 500
+        // `{"error":"render failed"}`. Mirrors the full-document render path.
+        navStatus = 404
+        // nfId is the array index == route_id (catch-alls keep their slot).
+        const nfId = selectNotFound(routes, call.path)
+        const nfFlat = nfId !== undefined ? byRouteId.get(nfId) : undefined
+        if (nfFlat) {
+          try {
+            fullHtml = await renderFlatToHtml(nfFlat)
+          } 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
+            // catch-all selection.
+            console.error('[brust] catch-all nav render failed:', nfErr)
+            fullHtml = DEFAULT_NOT_FOUND_BODY
+            store = null
+          }
+        } 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
+        }
+      }
     }
 
     // Extract <main> inner content. If the page didn't render a <main>,
@@ -1436,7 +1642,11 @@ async function navigationBranch(
       workerId,
       encoder,
       {
-        status: 200,
+        // Catch-all (`path: '*'`) leaf rendered as a SPA-nav payload on an
+        // unmatched path — OR a React `throw notFound()` swapped to the nearest
+        // catch-all — stamps HTTP 404 while still shipping the rendered body so
+        // the client swaps it in (vs the bare `{"error":"not found"}`).
+        status: navStatus,
         contentType: 'application/json; charset=utf-8',
         body,
         headers: navHeaders,