brustjs 0.1.43-alpha → 0.1.45-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.43-alpha",
+  "version": "0.1.45-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.43-alpha",
-    "brustjs-darwin-arm64": "0.1.43-alpha",
-    "brustjs-linux-x64-gnu": "0.1.43-alpha",
-    "brustjs-linux-arm64-gnu": "0.1.43-alpha",
-    "brustjs-linux-x64-musl": "0.1.43-alpha",
-    "brustjs-linux-arm64-musl": "0.1.43-alpha"
+    "brustjs-darwin-x64": "0.1.45-alpha",
+    "brustjs-darwin-arm64": "0.1.45-alpha",
+    "brustjs-linux-x64-gnu": "0.1.45-alpha",
+    "brustjs-linux-arm64-gnu": "0.1.45-alpha",
+    "brustjs-linux-x64-musl": "0.1.45-alpha",
+    "brustjs-linux-arm64-musl": "0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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.43-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.43-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.45-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.45-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/md/render.ts

@@ -1,4 +1,7 @@
 import { Marked, type Tokens } from 'marked'
+// Heading slugger shared with the public `brustjs/routes` export so a consumer's
+// anchors can't drift from the ids we stamp here (FRAMEWORK-GAPS G1).
+import { slugifyHeading as slugify } from './slug.ts'
 
 // ---------------------------------------------------------------------------
 // Types
@@ -397,14 +400,6 @@ function scanBalancedBraces(text: string, start: number): number {
 // Markdown → HTML (marked, GFM, heading ids, shiki fences)
 // ---------------------------------------------------------------------------
 
-function slugify(text: string): string {
-  return text
-    .toLowerCase()
-    .trim()
-    .replace(/\s+/g, '-')
-    .replace(/[^\w-]/g, '')
-}
-
 async function renderMarkdown(source: string): Promise<string> {
   // Fresh instance per page: heading-id dedupe state is page-local.
   const slugCounts = new Map<string, number>()

package/runtime/md/routes.ts

@@ -60,6 +60,13 @@ export interface MdRoutesOptions {
   layout?: ComponentType<any>
   /** Component-tag registry for `<Name />` tags inside the md body. */
   components?: Record<string, ComponentType<any>>
+  /** Loader for the LAYOUT parent route — runs before each md leaf renders and
+   * its data merges into the leaf's context top-down (so it feeds the layout
+   * chrome: sidebar, pager, …). Only applies when `layout` is set. Return keys
+   * that DON'T collide with the leaf's `__md` head metadata, which must win.
+   * Without this, the layout loader had to be attached by mutating the returned
+   * route node (`tree.loader = …`) — undocumented surface (was FRAMEWORK-GAPS G2). */
+  loader?: Route['loader']
 }
 
 /** One frozen-manifest entry (everything route construction needs per page).
@@ -270,7 +277,15 @@ export function mdRoutes(contentDir: string, opts: MdRoutesOptions = {}): Route[
   })
 
   if (opts.layout === undefined) return leaves
-  return [{ path: basePath, native: true, Component: opts.layout, children: leaves }]
+  const layoutRoute: Route = {
+    path: basePath,
+    native: true,
+    Component: opts.layout,
+    children: leaves,
+  }
+  // First-class layout loader (was a post-hoc `tree.loader = …` mutation).
+  if (opts.loader !== undefined) layoutRoute.loader = opts.loader
+  return [layoutRoute]
 }
 
 /** Strip the mount base off a full url path (index page → `''`, which

package/runtime/md/slug.ts

@@ -0,0 +1,16 @@
+// Heading-anchor slugger — the SINGLE source of truth for the ids brust stamps
+// on markdown `<h2>/<h3>`. render.ts uses it when emitting heading ids, and it
+// is re-exported on `brustjs/routes` so a consumer (e.g. a search-index
+// generator) can compute the SAME anchors without copying this logic — which
+// is exactly the parity that used to drift (FRAMEWORK-GAPS G1).
+//
+// `\w` is ASCII-only: non-ascii heading text strips to nothing (matches marked
+// GFM's behavior as wired here). Per-page duplicate-id disambiguation
+// (`-2`, `-3`, …) is the caller's concern — render.ts keeps a page-local count.
+export function slugifyHeading(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/[^\w-]/g, '')
+}

package/runtime/routes.ts

@@ -31,7 +31,7 @@ import { validate } from './standard-schema.ts'
 // surface — apps spread `...mdRoutes('content/docs', …)` into defineRoutes and
 // render sidebars from `mdNav(...)`. Re-exported here so user code never
 // imports runtime-internal paths.
-export { mdNav, mdRoutes } from './md/routes.ts'
+export { mdNav, mdRoutes, mdUrlPath } from './md/routes.ts'
 export type {
   MdNavGroup,
   MdNavItem,
@@ -39,6 +39,12 @@ export type {
   MdRoutesOptions,
   MdRouteSource,
 } from './md/routes.ts'
+// Lower-level md building blocks — the directory scanner and the heading
+// slugger — so consumers (search indexers, sitemaps) build on the SAME
+// scan/slug brust uses internally instead of copying it (FRAMEWORK-GAPS G1).
+export { scanMdDir } from './md/scan.ts'
+export type { MdFile } from './md/scan.ts'
+export { slugifyHeading } from './md/slug.ts'
 
 // S2 + B3 — unified per-request scope. The request scope (B3 cookies/context) is
 // the OUTERMOST layer, then the request-scoped loader cache/dedupe (S2: one Map
@@ -150,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).
@@ -415,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)'
@@ -447,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`.
@@ -566,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'
@@ -633,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,
@@ -751,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
@@ -890,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)
@@ -920,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)