brustjs 0.1.44-alpha → 0.1.46-alpha

package/README.md

@@ -88,8 +88,9 @@ Click either one — both update. [See it live](https://brust.assetsart.com/) ·
 
 - **Native rendering** — pages compile ahead of time and are served as plain
   HTML: no hydration pass, no framework runtime in the response. One compiled
-  page sustains **84,119 req/s** versus 28,938 for the same page through a
-  JavaScript pipeline — about 2.9× ([bench/RESULTS.md](./bench/RESULTS.md)).
+  page sustains **106,374 req/s** versus 44,448 for the same page through a
+  JavaScript pipeline — about 2.4×, on an M1 Pro (10c)
+  ([bench/RESULTS.md](./bench/RESULTS.md)).
   → [Rendering](https://brust.assetsart.com/docs/rendering)
 - **React islands** — hydrate one component, not the page. React 19 streaming
   SSR with auto-Suspense; SSR islands can opt into **ISR caching**

package/package.json

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

package/runtime/cache.ts

@@ -5,14 +5,28 @@ import * as native from './index.js'
 export interface InvalidateArgs {
   key?: string
   tags?: string[]
+  /** L1 response-cache: evict all entries for this request path (any prefix /
+   * query variant). Independent of `tags`. */
+  path?: string
+  /** HTTP method for the `path` eviction (defaults to GET in Rust). */
+  method?: string
 }
 
 export const cache = {
-  /** Evict by exact key and/or by tag group. Both optional; both may be given.
-   * `invalidate({})` forwards `(undefined, undefined)` — a deliberate no-op on
-   * the Rust side (neither the key nor the tags branch fires). The `?.` guards
-   * against a stale addon built before this export existed (degrades to no-op). */
+  /** Evict across all three caches: islands, L2 page cache, and L1 response
+   * cache. `key`/`tags` hit islands + L2; the L1 response cache is reached by
+   * `tags` (the ROUTE must declare static `cache.tags` for its L1 entries to
+   * carry them) and by `path` (evicts every L1 entry for that request path,
+   * any prefix/query variant). All fields optional; `invalidate({})` is a
+   * deliberate no-op. The `?.` guards against a stale addon built before a
+   * given binding existed (degrades to no-op). */
   invalidate(args: InvalidateArgs): void {
     ;(native as any).islandCacheInvalidate?.(args.key, args.tags)
+    // Fan out to the L2 page cache (same key/tag semantics). `?.` keeps a
+    // stale addon (built before page-cache bindings existed) a no-op.
+    ;(native as any).pageCacheInvalidate?.(args.key, args.tags)
+    // Fan out to the L1 response cache by tag (route must declare cache.tags)
+    // and/or by path. `?.` keeps a stale addon a no-op.
+    ;(native as any).responseCacheInvalidate?.(args.tags, args.path, args.method)
   },
 }

package/runtime/config.ts

@@ -10,8 +10,10 @@ export interface BrustConfig {
   port: number
   /** Bun Worker count for render dispatch. Default `availableParallelism()`. */
   workers: number
-  /** Cache capacity (entries). Undefined → Rust default of 1000. */
+  /** L1 response-cache capacity (entries). Undefined → Rust default of 1000. */
   cacheMaxEntries?: number
+  /** L2 page-cache capacity (entries). Undefined → Rust default of 1000. */
+  cachePageMaxEntries?: number
 }
 
 /** Caller-supplied fallbacks (e.g. `brust.run({ address, port })`) applied
@@ -77,7 +79,13 @@ export async function loadConfig(
   const port = fromEnv.port ?? fromToml.port ?? defaults.port ?? DEFAULT_PORT
   const workers = fromEnv.workers ?? fromToml.workers ?? defaultWorkers()
 
-  return { host, port, workers, cacheMaxEntries: fromToml.cacheMaxEntries }
+  return {
+    host,
+    port,
+    workers,
+    cacheMaxEntries: fromToml.cacheMaxEntries,
+    cachePageMaxEntries: fromToml.cachePageMaxEntries,
+  }
 }
 
 function extractFromToml(parsed: unknown, file: string): Partial<BrustConfig> {
@@ -146,6 +154,20 @@ function extractFromToml(parsed: unknown, file: string): Partial<BrustConfig> {
       }
       out.cacheMaxEntries = maxEntries
     }
+    const pageMaxEntries = (cache as Record<string, unknown>).page_max_entries
+    if (pageMaxEntries !== undefined) {
+      if (
+        typeof pageMaxEntries !== 'number' ||
+        !Number.isInteger(pageMaxEntries) ||
+        pageMaxEntries < 1
+      ) {
+        throw new BrustConfigError(
+          `${file}: cache.page_max_entries must be a positive integer (got ${JSON.stringify(pageMaxEntries)})`,
+          file,
+        )
+      }
+      out.cachePageMaxEntries = pageMaxEntries
+    }
   }
 
   return out

package/runtime/index.d.ts

@@ -19,7 +19,7 @@ export interface CachedIslandJs {
 
 export declare function compileJsx(source: string, path: string, componentSources?: Record<string, string> | undefined | null, lucideIcons?: Record<string, string> | undefined | null, directiveNames?: Record<string, string> | undefined | null): NapiCompiledJsx
 
-export declare function configureCache(maxEntries: number): NapiResult<undefined>
+export declare function configureCache(maxEntries: number, pageMaxEntries: number): NapiResult<undefined>
 
 export declare function configureCssDir(path: string): NapiResult<undefined>
 
@@ -235,6 +235,14 @@ export declare function napiWsSend(connId: bigint, data: Buffer, isBinary: boole
  */
 export declare function napiWsSignalOpen(connId: bigint, status: number, body: Buffer, contentType: string, subprotocol: string): NapiResult<undefined>
 
+export declare function pageCacheClear(): void
+
+export declare function pageCacheGet(key: string): Buffer | null
+
+export declare function pageCacheInvalidate(key?: string | undefined | null, tags?: Array<string> | undefined | null): void
+
+export declare function pageCacheSet(key: string, tags: Array<string>, ttlMs: number | undefined | null, payload: Buffer): void
+
 /**
  * Register action endpoints. Replaces any previous router state.
  * Returns the number of endpoints registered.
@@ -256,6 +264,8 @@ export declare function registerRoutes(configs: Array<string>): NapiResult<numbe
  */
 export declare function resetWorkerPool(): number
 
+export declare function responseCacheInvalidate(tags?: Array<string> | undefined | null, path?: string | undefined | null, method?: string | undefined | null): void
+
 export interface ServeOptions {
   /**
    * Host to bind on — a hostname (e.g. `localhost`, resolved here) or a
@@ -320,8 +330,9 @@ export interface ServeTuning {
   workerThreads?: number
   /**
    * Number of render slots per Bun worker (concurrent in-flight renders per
-   * isolate). Default 1 (single in-flight render per worker — byte-identical
-   * to the pre-multi-slot behaviour). The COUNT reaches `register_renderer`
+   * isolate). Default `min(cores, 16)` (set `BRUST_RENDER_SLOTS` to exceed 16
+   * cores); slots > 1 only speed renders that await during render and are
+   * byte-identical to slots = 1. The COUNT reaches `register_renderer`
    * via the `BRUST_RENDER_SLOTS` worker env var set in `runtime/index.ts`; it
    * is NOT consumed by the Rust `Tuning` struct here (the pool learns it from
    * `dispatch.slot_count()`). Carried on `ServeTuning` only so the JS layer

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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-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.44-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.44-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.46-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.46-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -605,10 +605,15 @@ module.exports.napiWsClose = nativeBinding.napiWsClose
 module.exports.napiWsRegisterHandlers = nativeBinding.napiWsRegisterHandlers
 module.exports.napiWsSend = nativeBinding.napiWsSend
 module.exports.napiWsSignalOpen = nativeBinding.napiWsSignalOpen
+module.exports.pageCacheClear = nativeBinding.pageCacheClear
+module.exports.pageCacheGet = nativeBinding.pageCacheGet
+module.exports.pageCacheInvalidate = nativeBinding.pageCacheInvalidate
+module.exports.pageCacheSet = nativeBinding.pageCacheSet
 module.exports.registerActions = nativeBinding.registerActions
 module.exports.registerRenderer = nativeBinding.registerRenderer
 module.exports.registerRoutes = nativeBinding.registerRoutes
 module.exports.resetWorkerPool = nativeBinding.resetWorkerPool
+module.exports.responseCacheInvalidate = nativeBinding.responseCacheInvalidate
 module.exports.untilReady = nativeBinding.untilReady
 module.exports.untilShutdown = nativeBinding.untilShutdown
 module.exports.workerId = nativeBinding.workerId

package/runtime/index.ts

@@ -1,9 +1,26 @@
+import os from 'node:os'
 import * as native from './index.js'
 import type { EndpointDef } from './define-actions.ts'
 import { loadConfig } from './config.ts'
 import { configureCssEnabled, configureCssHrefsForRoute } from './css.ts'
 import { configureJinjaDir } from './islands/native-render.ts'
 
+/** Default render slots per Bun worker: one per CPU, capped at 16. Above 16
+ * cores, set `BRUST_RENDER_SLOTS` explicitly to go higher. Slots > 1 only speed
+ * up renders that `await` DURING render (e.g. Suspense fetching async data);
+ * CPU-bound / native-jinja / cache-hit routes serialize on the worker's single
+ * JS isolate and are unaffected. Each slot costs one SAB region (`sabBytes`), so
+ * the cap bounds memory. slots > 1 is byte-identical to slots = 1. */
+function defaultRenderSlots(): number {
+  let cores: number
+  try {
+    cores = os.availableParallelism()
+  } catch {
+    cores = os.cpus().length
+  }
+  return Math.min(Math.max(cores, 1), 16)
+}
+
 export interface ServeOptions {
   /** Host/address to bind on. A hostname (e.g. `localhost`, resolved Rust-side)
    * or a literal IP such as `0.0.0.0` / `127.0.0.1`. */
@@ -54,9 +71,12 @@ export interface ServeOptions {
      * one-per-core. Default `min(availableParallelism, 4)` (fallback 2). */
     workerThreads?: number
     /** Render slots per Bun worker — concurrent in-flight renders per isolate.
-     * Default 1 (byte-identical to single in-flight render per worker). The
-     * count is propagated to each worker via the `BRUST_RENDER_SLOTS` env var
-     * and scales the per-worker SAB so each slot keeps the single-slot capacity. */
+     * Default `min(cores, 16)` (set `BRUST_RENDER_SLOTS` to go higher on >16-core
+     * hosts). Only speeds renders that `await` during render (e.g. Suspense with
+     * async data); CPU-bound/native/cache routes serialize on the one isolate and
+     * are unaffected. The count is propagated to each worker via the
+     * `BRUST_RENDER_SLOTS` env var and scales the per-worker SAB (one region per
+     * slot, so the cap bounds memory). slots > 1 is byte-identical to slots = 1. */
     renderSlots?: number
   }
 }
@@ -144,7 +164,7 @@ export const brust = {
     // per-app wiring), else 1 — byte-identical single in-flight render.
     const renderSlots = Math.max(
       1,
-      opts.tuning?.renderSlots ?? (Number(process.env.BRUST_RENDER_SLOTS) || 1),
+      opts.tuning?.renderSlots ?? (Number(process.env.BRUST_RENDER_SLOTS) || defaultRenderSlots()),
     )
     const baseEnv = { ...process.env, BRUST_RENDER_SLOTS: String(renderSlots) }
     const workersArr: Worker[] = []
@@ -190,7 +210,25 @@ export const brust = {
     const configs = routes.map((r) =>
       JSON.stringify({
         path: r.fullPath,
-        cache: r.cache ?? null,
+        // Rust-safe projection: the L2 `key` FUNCTION and `key_ttl_seconds`
+        // stay TS-side (the worker reads them off the FlatRoute). Only the
+        // L1 directives cross napi. `bypass` passes through as `true` or the
+        // string expr — serde's untagged BypassSpec handles both. `false` and
+        // absent both normalize to null → None (never bypass), so an explicitly
+        // disabled bypass doesn't ride a cross-language `false` contract. An
+        // EMPTY-STRING expr deliberately passes through: Expr::parse("") fails
+        // route install, surfacing the misconfiguration loudly at boot instead
+        // of silently never bypassing.
+        cache: r.cache
+          ? {
+              ttl_seconds: r.cache.ttl_seconds,
+              prefix: r.cache.prefix ?? null,
+              bypass: r.cache.bypass === false ? null : (r.cache.bypass ?? null),
+              // Static L1 invalidation tags carried into each L1 entry so
+              // `cache.invalidate({ tags })` can reach the response cache.
+              tags: r.cache.tags ?? null,
+            }
+          : null,
         nativeTemplate: r.nativeTemplate ?? null,
       }),
     )
@@ -229,11 +267,12 @@ export const brust = {
   registerWsPaths(paths: string[]): void {
     ;(native as any).napiRegisterWsPaths(paths)
   },
-  /** Set the response cache capacity (entries). Default is 1000.
-   * Safe to call at any time; if shrinking below current size, excess
-   * LRU entries are evicted. */
-  configureCache(opts: { maxEntries: number }): void {
-    ;(native as any).configureCache(opts.maxEntries)
+  /** Set the L1 response-cache and L2 page-cache capacities (entries).
+   * Default is 1000 each. Rust reconstructs both caches at the given
+   * capacities (moka fixes capacity at construction), so call this once at
+   * boot before serving begins. */
+  configureCache(opts: { maxEntries: number; pageMaxEntries: number }): void {
+    ;(native as any).configureCache(opts.maxEntries, opts.pageMaxEntries)
   },
   /** Tell Rust where to read `/_brust/islands/<file>` from. Called once at
    * boot after buildIslands() emits chunks. Path must be absolute. */
@@ -365,12 +404,19 @@ export const brust = {
     const endpoints: EndpointDef[] = opts.actions?.endpoints ?? []
 
     if (!isWorker) {
-      const { host, port, workers, cacheMaxEntries } = await loadConfig(process.cwd(), {
-        host: opts.address,
-        port: opts.port,
-      })
+      const { host, port, workers, cacheMaxEntries, cachePageMaxEntries } = await loadConfig(
+        process.cwd(),
+        {
+          host: opts.address,
+          port: opts.port,
+        },
+      )
       console.log(`[brust] main: spawning ${workers} worker threads`)
-      if (cacheMaxEntries !== undefined) this.configureCache({ maxEntries: cacheMaxEntries })
+      if (cacheMaxEntries !== undefined || cachePageMaxEntries !== undefined)
+        this.configureCache({
+          maxEntries: cacheMaxEntries ?? 1000,
+          pageMaxEntries: cachePageMaxEntries ?? 1000,
+        })
 
       // md routes present? (leaf carries `__mdSource`, attached by mdRoutes()).
       // Checked inline — no md-module import — so md-free apps never load the
@@ -883,7 +929,13 @@ export const brust = {
       // Render slots for this worker (set in serve() via the worker env). The
       // SAB scales with the slot count so each slot's disjoint sub-region keeps
       // the single-slot capacity; at K=1 this is byte-identical to before.
-      const renderSlots = Math.max(1, Number(process.env.BRUST_RENDER_SLOTS ?? 1) || 1)
+      // Normally main propagates the computed count via the worker env; the
+      // defaultRenderSlots() fallback keeps an in-process boot (env unset) in
+      // sync with the main-branch default above.
+      const renderSlots = Math.max(
+        1,
+        Number(process.env.BRUST_RENDER_SLOTS) || defaultRenderSlots(),
+      )
       const sab = new SharedArrayBuffer((opts.sabBytes ?? 256 * 1024) * renderSlots)
       const view = new Uint8Array(sab)
 

package/runtime/islands/bootstrap.ts

@@ -24,6 +24,14 @@ import {
   registerNavigator,
 } from '../navigation/store.ts'
 import { installActiveNav } from '../navigation/active-nav.ts'
+import {
+  pageCacheKey,
+  getCachedPage,
+  fetchPagePayload,
+  inflightPage,
+  prefetchPage,
+  type PagePayload,
+} from './page-cache.ts'
 
 // Track React roots created by hydrateOne so we can unmount them before
 // removing their DOM in swapMainContent. Without this, removing the DOM
@@ -242,22 +250,47 @@ export function isFullDocumentPayload(html: string): boolean {
 
 let inFlight: AbortController | null = null
 
+// scrollY of each page we navigated away from (keyed pathname+search), so
+// back/forward restores the reading position instead of jumping to top.
+const scrollPositions = new Map<string, number>()
+// The page currently in the DOM. Tracked here (set at boot + on every commit)
+// instead of read from `location` at save time, because popstate updates
+// `location` to the DESTINATION before the event fires — reading it there
+// would record the leaving page's scroll under the wrong key.
+let currentPageKey = ''
+
 export async function navigate(url: URL, mode: 'push' | 'replace' | 'none'): Promise<void> {
   inFlight?.abort()
   const ac = new AbortController()
   inFlight = ac
   try {
     __navStart(url.pathname, url.search)
-    const resp = await fetch(`/_brust/page${url.pathname}${url.search}`, {
-      signal: ac.signal,
-      headers: { Accept: 'application/json' },
-    })
-    if (!resp.ok) throw new Error(`navigation: status ${resp.status}`)
-    const { html, title, store } = (await resp.json()) as {
-      html: string
-      title: string
-      store?: Record<string, Record<string, unknown>>
+    const key = pageCacheKey(url)
+    // Visited pages are served from the in-memory cache — no refetch. Forward
+    // navigations respect PAGE_STALE_MS (default max age); back/forward reuses
+    // any entry regardless of age, like the browser's bfcache.
+    const cached = getCachedPage(key, mode === 'none' ? Number.POSITIVE_INFINITY : undefined)
+    let payload: PagePayload
+    if (cached) {
+      payload = cached
+    } else {
+      // A hover prefetch may already have this page in flight — await it
+      // instead of double-fetching; if it failed, fall back to a direct fetch.
+      const pre = inflightPage(key)
+      if (pre) {
+        try {
+          payload = await pre
+        } catch {
+          payload = await fetchPagePayload(url, ac.signal)
+        }
+      } else {
+        payload = await fetchPagePayload(url, ac.signal)
+      }
+      // The prefetch promise isn't tied to our AbortController, so an abort
+      // during that await doesn't throw — check for supersession explicitly.
+      if (ac.signal.aborted) return
     }
+    const { html, title, store } = payload
     // A standalone (no-<main>) route ships its FULL document here. We can't swap
     // that into the current shell's <main> without nesting a second document
     // (duplicate chrome — the classic two-topbars artifact), and the current
@@ -269,14 +302,20 @@ 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')
+    scrollPositions.set(currentPageKey, window.scrollY)
     unmountIslandsIn(main as HTMLElement)
     swapMainContent(main as HTMLElement, html)
-    if (store) applyStoreSnapshot(store)
+    // 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)
-    window.scrollTo(0, 0)
+    if (mode === 'none') window.scrollTo(0, scrollPositions.get(key) ?? 0)
+    else window.scrollTo(0, 0)
     hydrateMarkersIn(main as HTMLElement)
+    currentPageKey = key
     __navCommit(url.pathname, url.search)
   } catch (err) {
     if ((err as Error).name === 'AbortError') return
@@ -288,7 +327,76 @@ export async function navigate(url: URL, mode: 'push' | 'replace' | 'none'): Pro
   }
 }
 
+/** Resolve an <a> to a prefetchable in-app URL, or null when prefetch must not
+ * run: not ours (cross-origin, target, download, /_brust/), explicitly opted
+ * out (data-brust-no-intercept disables SPA handling entirely;
+ * data-brust-no-prefetch keeps the SPA click but skips the speculative fetch),
+ * or the page we are already on. Exported for unit testing. */
+export function prefetchUrlFor(a: HTMLAnchorElement): URL | null {
+  if (a.target && a.target !== '_self') return null
+  if (a.hasAttribute('download')) return null
+  if (a.dataset.brustNoIntercept !== undefined) return null
+  if (a.dataset.brustNoPrefetch !== undefined) return null
+  if (!a.getAttribute('href')) return null
+  const url = new URL(a.href, location.href)
+  if (url.origin !== location.origin) return null
+  if (url.pathname.startsWith('/_brust/')) return null
+  if (url.pathname === location.pathname && url.search === location.search) return null
+  return url
+}
+
+// Hover-intent delay: long enough that a cursor sweeping across a nav list
+// doesn't fire a fetch per link, short enough to beat the click (~200-300ms
+// between hover and press for a deliberate click).
+const HOVER_DELAY_MS = 80
+
+/** Hover/touch prefetch: pointer rests on an internal link for HOVER_DELAY_MS
+ * (or a touch starts — the tap commits within ~100ms anyway) → fetch its nav
+ * payload into the page cache so the eventual click swaps instantly.
+ * prefetchPage dedupes in-flight fetches and respects Save-Data/2g. */
+function installPrefetch(): void {
+  const timers = new WeakMap<HTMLAnchorElement, ReturnType<typeof setTimeout>>()
+  document.addEventListener('pointerover', (e) => {
+    const a = (e.target as HTMLElement | null)?.closest('a') as HTMLAnchorElement | null
+    if (!a || timers.has(a)) return
+    const url = prefetchUrlFor(a)
+    if (!url) return
+    timers.set(
+      a,
+      setTimeout(() => {
+        timers.delete(a)
+        void prefetchPage(url)
+      }, HOVER_DELAY_MS),
+    )
+  })
+  document.addEventListener('pointerout', (e) => {
+    const a = (e.target as HTMLElement | null)?.closest('a') as HTMLAnchorElement | null
+    if (!a) return
+    // Moving between children of the same link is not a leave.
+    if (e.relatedTarget instanceof Node && a.contains(e.relatedTarget)) return
+    const t = timers.get(a)
+    if (t !== undefined) {
+      clearTimeout(t)
+      timers.delete(a)
+    }
+  })
+  document.addEventListener(
+    'touchstart',
+    (e) => {
+      const a = (e.target as HTMLElement | null)?.closest('a') as HTMLAnchorElement | null
+      if (!a) return
+      const url = prefetchUrlFor(a)
+      if (url) void prefetchPage(url)
+    },
+    { passive: true },
+  )
+}
+
 function installInterceptor(): void {
+  // We restore scroll ourselves on popstate (the page cache makes back/forward
+  // an instant in-place swap); stop the browser's automatic restoration from
+  // fighting the swap.
+  if ('scrollRestoration' in history) history.scrollRestoration = 'manual'
   document.addEventListener('click', (e) => {
     const target = e.target as HTMLElement | null
     const a = target?.closest('a') as HTMLAnchorElement | null
@@ -309,17 +417,20 @@ function installInterceptor(): void {
 
 if (typeof document !== 'undefined') {
   registerNavigator((url, replace) => navigate(url, replace ? 'replace' : 'push'))
+  currentPageKey = location.pathname + location.search
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', () => {
       __navInit(location.pathname, location.search)
       installActiveNav()
       hydrateMarkersIn(document.body)
       installInterceptor()
+      installPrefetch()
     })
   } else {
     __navInit(location.pathname, location.search)
     installActiveNav()
     hydrateMarkersIn(document.body)
     installInterceptor()
+    installPrefetch()
   }
 }

package/runtime/islands/page-cache.ts

@@ -0,0 +1,108 @@
+// runtime/islands/page-cache.ts — in-memory cache for SPA navigation payloads
+// (/_brust/page/*) plus the fetch/dedupe machinery behind hover prefetch.
+// Browser-only at call time (fetch/navigator), but import-safe anywhere.
+//
+// Lifetime: one document load. A full reload (dev rebuild WS, full-document
+// fallback, hard refresh) drops the whole cache with the JS heap, so dev never
+// serves stale pages across rebuilds.
+
+export interface PagePayload {
+  html: string
+  title: string
+  store?: Record<string, Record<string, unknown>>
+}
+
+/** Bound the cache so a long session can't grow memory unbounded (LRU evict). */
+export const PAGE_CACHE_MAX = 64
+/** Forward navigations reuse an entry for this long; back/forward (popstate)
+ * passes Infinity and reuses any entry regardless of age (bfcache-like). */
+export const PAGE_STALE_MS = 5 * 60_000
+
+interface Entry {
+  payload: PagePayload
+  at: number
+}
+
+const cache = new Map<string, Entry>()
+const inflight = new Map<string, Promise<PagePayload>>()
+
+export function pageCacheKey(url: URL): string {
+  return url.pathname + url.search
+}
+
+export function getCachedPage(key: string, maxAgeMs: number = PAGE_STALE_MS): PagePayload | null {
+  const e = cache.get(key)
+  if (!e) return null
+  if (Date.now() - e.at > maxAgeMs) {
+    cache.delete(key)
+    return null
+  }
+  // LRU bump: Map iteration order is insertion order, so re-inserting moves
+  // this key to the "most recently used" end.
+  cache.delete(key)
+  cache.set(key, e)
+  return e.payload
+}
+
+export function setCachedPage(key: string, payload: PagePayload): void {
+  cache.delete(key)
+  cache.set(key, { payload, at: Date.now() })
+  if (cache.size > PAGE_CACHE_MAX) {
+    const oldest = cache.keys().next().value
+    if (oldest !== undefined) cache.delete(oldest)
+  }
+}
+
+/** Fetch a nav payload and cache it on success. Shared by navigate (direct,
+ * abortable) and prefetch (deduped, signal-less). */
+export async function fetchPagePayload(url: URL, signal?: AbortSignal): Promise<PagePayload> {
+  const resp = await fetch(`/_brust/page${url.pathname}${url.search}`, {
+    signal,
+    headers: { Accept: 'application/json' },
+  })
+  if (!resp.ok) throw new Error(`navigation: status ${resp.status}`)
+  const payload = (await resp.json()) as PagePayload
+  setCachedPage(pageCacheKey(url), payload)
+  return payload
+}
+
+/** @internal — the in-flight prefetch for `key`, if any. navigate() awaits it
+ * instead of double-fetching when a click lands mid-prefetch. */
+export function inflightPage(key: string): Promise<PagePayload> | undefined {
+  return inflight.get(key)
+}
+
+function prefetchAllowed(): boolean {
+  if (typeof navigator === 'undefined') return false
+  const conn = (navigator as { connection?: { saveData?: boolean; effectiveType?: string } })
+    .connection
+  if (conn?.saveData) return false
+  if (typeof conn?.effectiveType === 'string' && conn.effectiveType.includes('2g')) return false
+  return true
+}
+
+/** Speculatively load a page into the cache (hover/touch intent). No-op when
+ * already cached fresh or when the connection asks not to (Save-Data, 2g).
+ * Failures are silent — the eventual click just fetches normally. */
+export function prefetchPage(url: URL): Promise<void> {
+  if (!prefetchAllowed()) return Promise.resolve()
+  const key = pageCacheKey(url)
+  if (getCachedPage(key) !== null) return Promise.resolve()
+  let p = inflight.get(key)
+  if (!p) {
+    p = fetchPagePayload(url).finally(() => {
+      inflight.delete(key)
+    })
+    inflight.set(key, p)
+  }
+  return p.then(
+    () => undefined,
+    () => undefined,
+  )
+}
+
+// Test-only: drop all entries and in-flight markers.
+export function __resetPageCacheForTest(): void {
+  cache.clear()
+  inflight.clear()
+}

package/runtime/routes.ts

@@ -156,11 +156,37 @@ export interface ErrorBoundaryProps {
   error: Error
 }
 
-export interface RouteCacheConfig {
-  /** Time-to-live in seconds. */
+/** L2 programmatic cache-key result. The `key` function builds the COMPLETE
+ * cache key (you concat url + query + DB-derived data yourself). */
+export interface CacheKeyResult {
+  /** The COMPLETE L2 cache key. */
+  key: string
+  /** Tag groups for `cache.invalidate({ tags })`. */
+  tags?: string[]
+  /** Seconds; overrides `key_ttl_seconds` / `ttl_seconds`. */
+  ttl?: number
+}
+
+export interface RouteCacheConfig<Params = Record<string, string>> {
+  /** Base TTL in seconds (L1; L2 fallback). */
   ttl_seconds: number
-  /** Request headers that affect content. Each becomes part of the cache key. */
-  vary?: string[]
+  /** L1 declarative key prefix expression (evaluated in Rust, zero-Bun on hit). */
+  prefix?: string
+  /** Route to L2 when truthy: a key-expression (conditional) or `true` (always).
+   * Absent / `false` ⇒ L1 only. */
+  bypass?: string | boolean
+  /** L2 programmatic key (runs in the worker). Returns the COMPLETE key. */
+  key?: (ctx: {
+    req: BrustRequest
+    url: URL
+    params: Params
+  }) => CacheKeyResult | Promise<CacheKeyResult>
+  /** Static L2 TTL (seconds); `CacheKeyResult.ttl` overrides per-entry. */
+  key_ttl_seconds?: number
+  /** Static L1 invalidation tags. L1 entries cached for this route carry these
+   * tags so `cache.invalidate({ tags })` evicts them (L1 is no longer
+   * TTL-only). Route-level + static — not per-request. */
+  tags?: string[]
 }
 
 /** Shape returned by a middleware or by the terminal `next()` (loader + render).
@@ -421,10 +447,8 @@ function validateRoute(r: Route, basePath: string): void {
     if (r.children !== undefined) {
       assertNativeSubtree(r.children, where)
     }
-    if (r.cache !== undefined) {
-      throw new Error(`Route ${where}: 'native: true' cannot coexist with 'cache' (deferred)`)
-    }
-    // loader + middleware are EXPLICITLY allowed.
+    // `cache` is now allowed on native routes — they are the primary L1
+    // (zero-Bun) target. loader + middleware are EXPLICITLY allowed.
   }
   if (r.sse) {
     const where = r.path ?? '(no path)'
@@ -453,6 +477,14 @@ function validateRoute(r: Route, basePath: string): void {
       throw new Error(`Route ${where}: 'websocket' cannot have nested children`)
     }
   }
+  // L2 (cache.key) is only reachable via a truthy `bypass`. A key with no
+  // bypass is dead config — warn so it isn't silently ignored.
+  if (r.cache?.key && r.cache.bypass === undefined) {
+    const where = r.path ?? '(no path)'
+    console.warn(
+      `[brust] route ${where}: cache.key has no cache.bypass — L2 is unreachable (bypass never routes to it)`,
+    )
+  }
 }
 
 /** T2 — recursively assert every node in a native subtree is also `native: true`.
@@ -572,6 +604,9 @@ export type RouteCall =
       path: string
       params: Record<string, string>
       req: BrustRequest
+      /** Set by Rust when the route's `cache.bypass` matched — routes this
+       * request to the L2 programmatic cache (worker `cache.key`). */
+      bypassed?: boolean
     }
   | {
       kind: 'navigation'
@@ -639,6 +674,51 @@ export interface MakeRendererOptions {
   slots?: number
 }
 
+/** May a framed single-chunk payload (`[meta_len: u16 BE][meta JSON][body]`)
+ * enter the L2 page cache? Only a plain 200 without Set-Cookie. The status
+ * gate is load-bearing: a jinja render failure comes back as a framed 500
+ * through the SAME napiRenderJinja success return as a real render, so without
+ * it one flaky render would poison the L2 key for its full TTL. A Set-Cookie
+ * response is per-client (a cached one would leak a session). Short/truncated/
+ * malformed payloads → NOT cacheable (fail closed). */
+function payloadCacheable(payload: Uint8Array): boolean {
+  if (payload.length < 2) return false
+  const metaLen = (payload[0] << 8) | payload[1]
+  if (payload.length < 2 + metaLen) return false
+  try {
+    const meta = JSON.parse(new TextDecoder().decode(payload.subarray(2, 2 + metaLen)))
+    if (meta?.status !== 200) return false
+    const headers = (meta?.headers ?? {}) as Record<string, unknown>
+    return !Object.keys(headers).some((h) => h.toLowerCase() === 'set-cookie')
+  } catch {
+    return false
+  }
+}
+
+// Return a copy of a framed `[meta_len:u16 BE][meta JSON][body]` payload with
+// `X-Brust-Cache: HIT` added to the meta headers — stamped on an L2 replay so a
+// cache hit is observable on the wire (mirrors the L1 hit header). On any parse
+// failure the original payload is returned unchanged (never corrupt a response).
+function withCacheHitHeader(payload: Uint8Array): Uint8Array {
+  if (payload.length < 2) return payload
+  const metaLen = (payload[0] << 8) | payload[1]
+  if (payload.length < 2 + metaLen) return payload
+  try {
+    const meta = JSON.parse(new TextDecoder().decode(payload.subarray(2, 2 + metaLen)))
+    meta.headers = { ...(meta.headers ?? {}), 'X-Brust-Cache': 'HIT' }
+    const metaBytes = new TextEncoder().encode(JSON.stringify(meta))
+    const body = payload.subarray(2 + metaLen)
+    const out = new Uint8Array(2 + metaBytes.length + body.length)
+    out[0] = (metaBytes.length >> 8) & 0xff
+    out[1] = metaBytes.length & 0xff
+    out.set(metaBytes, 2)
+    out.set(body, 2 + metaBytes.length)
+    return out
+  } catch {
+    return payload
+  }
+}
+
 export function makeRenderer(
   routes: FlatRoute[],
   view: Uint8Array,
@@ -757,6 +837,78 @@ export function makeRenderer(
         })
       }
 
+      // L2 programmatic page cache (Task 10). Only on a bypassed request whose
+      // route declares a `cache.key` function. Runs AFTER middleware (which may
+      // set cookies / auth context the key depends on) and BEFORE render.
+      //   HIT  → write the cached framed payload into the SAB slot, return its
+      //          length — the exact fast-lane shape Rust reads from a native
+      //          render, so the loader+render are skipped entirely.
+      //   MISS → render normally, then capture slotView[0..len] and pageCacheSet.
+      // Streaming/Suspense responses never reach the `len > 0` fast-lane return
+      // below (renderBranchStreaming returns 0), so they are never L2-cached.
+      // L2 capture/replay rides the NATIVE SAB fast-lane (a framed payload in
+      // slotView + a length return). React routes emit via the chunk channel and
+      // return 0, so engaging L2 there would return a non-zero length into the
+      // streaming path = protocol corruption. Gate L2 to native routes; a React
+      // route with `bypass` still skips L1 and renders fresh (no L2).
+      const cc = flat.cache
+      const wantL2 =
+        call.bypassed === true && typeof cc?.key === 'function' && flat.nativeTemplate !== undefined
+      let l2Key: CacheKeyResult | undefined
+      if (wantL2 && cc) {
+        const url = new URL(call.req.url, 'http://internal') // req.url is a path+query
+        try {
+          l2Key = await cc.key!({ req: call.req, url, params: call.params ?? {} })
+        } catch (err) {
+          // A throwing/rejecting key() must not crash the worker — fall back to
+          // a fresh render. l2Key stays undefined → replay skipped, store no-op.
+          console.error('[brust] cache.key threw; bypassing L2 (rendering fresh):', err)
+        }
+        if (l2Key) {
+          const cached = (native as any).pageCacheGet?.(l2Key.key) as Buffer | null | undefined
+          if (cached && cached.length > 0) {
+            // REPLAY — stamp the framed meta with X-Brust-Cache: HIT, then write
+            // it into the slot and return its length (fast lane). Prefer the
+            // stamped payload; if the extra header tips it past the slot, fall
+            // back to the verbatim bytes; only a too-large verbatim payload
+            // falls through to a fresh render (never serve truncated bytes).
+            const stamped = withCacheHitHeader(cached)
+            const out =
+              stamped.length <= slotView.length
+                ? stamped
+                : cached.length <= slotView.length
+                  ? cached
+                  : null
+            if (out) {
+              slotView.set(out, 0)
+              return out.length
+            }
+          }
+        }
+      }
+      // Capture-and-store on an L2 miss. Wraps the native success returns; a
+      // no-op when not bypassed or no key. Only single-chunk (len > 0) bytes
+      // that fit the slot and carry no Set-Cookie are stored.
+      const maybeStoreL2 = (len: number): number => {
+        if (wantL2 && cc && l2Key && len > 0 && len <= slotView.length) {
+          const payload = slotView.subarray(0, len).slice() // copy out of the SAB
+          if (payloadCacheable(payload)) {
+            const ttlSec = l2Key.ttl ?? cc.key_ttl_seconds ?? cc.ttl_seconds
+            try {
+              ;(native as any).pageCacheSet?.(
+                l2Key.key,
+                l2Key.tags ?? [],
+                Math.round(ttlSec * 1000),
+                payload,
+              )
+            } catch (err) {
+              console.error('[brust] pageCacheSet failed (response served, not cached):', err)
+            }
+          }
+        }
+        return len
+      }
+
       // Sub-project J — native: true branch. Runs the leaf's loader (if any),
       // JSON-encodes the result into the SAB, then invokes napiRenderJinja
       // which performs the minijinja render Rust-side and emits a 200 chunk
@@ -896,12 +1048,14 @@ export function makeRenderer(
           }
           slotView.set(finalBytes, 0)
           try {
-            return (native as any).napiRenderJinja(
-              Number(workerId),
-              slot,
-              finalBytes.length,
-              flat.nativeTemplate,
-              renderStatus,
+            return maybeStoreL2(
+              (native as any).napiRenderJinja(
+                Number(workerId),
+                slot,
+                finalBytes.length,
+                flat.nativeTemplate,
+                renderStatus,
+              ),
             )
           } catch (err) {
             console.error(`[brust] napiRenderJinja failed for "${flat.nativeTemplate}":`, err)
@@ -926,12 +1080,14 @@ export function makeRenderer(
           // writes the framed response into the SAB, and returns its length
           // directly (no Promise round-trip). Return it up to the tsfn; Rust's
           // fast-lane arm reads the SAB directly (no chunk channel).
-          return (native as any).napiRenderJinja(
-            Number(workerId),
-            slot,
-            dataBytes.length,
-            flat.nativeTemplate,
-            renderStatus,
+          return maybeStoreL2(
+            (native as any).napiRenderJinja(
+              Number(workerId),
+              slot,
+              dataBytes.length,
+              flat.nativeTemplate,
+              renderStatus,
+            ),
           )
         } catch (err) {
           console.error(`[brust] napiRenderJinja failed for "${flat.nativeTemplate}":`, err)