brustjs 0.1.6-alpha → 0.1.7-alpha

package/README.md

@@ -80,13 +80,15 @@ brustjs new   <name>              # scaffold a project (partial — see Status)
 
 - **React 19 SSR** via `renderToPipeableStream` (auto-Suspense → chunked streaming).
 - **Islands** — opt-in client hydration with `<Island>`; the rest ships zero JS.
+  SSR islands can opt into **ISR caching** (`isr={{ key, tags, revalidate }}`) so
+  `renderToString` runs once per key, then serves a frozen pair from Rust.
 - **`native: true` routes** — JSX compiled to a jinja template at build time and
   rendered Rust-side (`minijinja`), skipping React on the server entirely.
 - **Server actions** (`"use server"`) → per-action endpoints; client helper rewrites
   form/`fetch` targets.
 - **SSE & WebSockets** as first-class route shapes.
 - Nested routes + dynamic params, per-route typed loaders, request-scoped middleware,
-  forms/multipart, SPA-style navigation, in-process LRU cache, Tailwind v4 + CSS Modules.
+  forms/multipart, SPA-style navigation, in-process LRU response cache + island ISR cache, Tailwind v4 + CSS Modules.
 - **Agent-first** — server fns and routes expose MCP tool/resource schemas at
   `/_brust/mcp` so agents drive the app without scraping.
 

package/package.json

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

package/runtime/cache.ts

@@ -0,0 +1,18 @@
+// Dev-facing island ISR cache control. Invalidation crosses to the Rust-side
+// store (shared across the worker pool) via NAPI. Call from action/api/loader.
+import * as native from './index.js'
+
+export interface InvalidateArgs {
+  key?: string
+  tags?: 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). */
+  invalidate(args: InvalidateArgs): void {
+    ;(native as any).islandCacheInvalidate?.(args.key, args.tags)
+  },
+}

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

@@ -56,6 +56,12 @@ interface RawIslandEntry {
   propsPath: string
   ssr: boolean
   hydrate: string
+  /** ISR cache fields (present only on islands with an `isr` attr). Declared so
+   * reconcile's `{ ...entry }` spread is type-complete — they MUST survive into
+   * the enriched manifest, or runtime ISR caching silently never activates. */
+  keyPath?: string
+  tagsPath?: string
+  revalidate?: number
 }
 interface EnrichedIslandEntry extends RawIslandEntry {
   /** Absolute path to the island's client source, resolved from the page's

package/runtime/cli/templates/minimal/pages/Home.tsx.tmpl

@@ -10,9 +10,13 @@ import Counter from '../components/Counter'
 export default function Home({
   clientProps,
   serverProps,
+  cacheKey,
+  cacheTags,
 }: {
   clientProps: { start: number; label: string }
   serverProps: { start: number; label: string }
+  cacheKey: string
+  cacheTags: string[]
 }) {
   return (
     <BrustPage lang="en" className="dark" bodyClassName="brust-body" title="__PROJECT_NAME__">
@@ -49,18 +53,29 @@ export default function Home({
             </div>
           </section>
 
-          {/* Server island — rendered to string in the worker, then hydrated. */}
+          {/* Server island — ISR-cached: renderToString runs ONCE per `key`,
+              then every request serves the frozen markup from the Rust-side
+              cache (no re-render). `key`/`tags` come from the loader; invalidate
+              from server code with `import { cache } from 'brustjs'` →
+              `cache.invalidate({ tags: ['home'] })`. Drop the `isr` prop to
+              render on every request instead. */}
           <section className="island-card island-card-server">
             <div className="island-header">
-              <span className="island-badge island-badge-server">SSR + CSR</span>
+              <span className="island-badge island-badge-server">SSR + ISR</span>
               <h2 className="island-title">Server Island</h2>
             </div>
             <p className="island-desc">
-              Rendered to string in the Bun worker during the loader crossing, then hydrated — no
-              layout shift.
+              Rendered to string in the Bun worker, then cached (ISR) and hydrated — rendered once
+              per key, no layout shift.
             </p>
             <div className="island-mount-point">
-              <Island component={Counter} props={serverProps} ssr hydrate="load" />
+              <Island
+                component={Counter}
+                props={serverProps}
+                ssr
+                hydrate="load"
+                isr={{ key: cacheKey, tags: cacheTags }}
+              />
             </div>
           </section>
         </div>

package/runtime/cli/templates/minimal/routes.tsx

@@ -5,6 +5,11 @@ export const routes = defineRoutes([
   // `native: true` — Home is compiled to a jinja template and rendered in Rust
   // (no React on the server). The loader's return value is the template
   // context; each island's `props` is a path into it.
+  //
+  // `cacheKey`/`cacheTags` feed the server island's `isr` cache: with a stable
+  // key its renderToString runs once and later requests serve the frozen markup
+  // from Rust. In a real app derive the key from the data the island depends on
+  // (e.g. `product:${id}`) and invalidate by tag when that data changes.
   {
     path: '/',
     Component: Home,
@@ -12,6 +17,8 @@ export const routes = defineRoutes([
     loader: async () => ({
       clientProps: { start: 0, label: 'client clicks' },
       serverProps: { start: 100, label: 'server clicks' },
+      cacheKey: 'home:server-island',
+      cacheTags: ['home'],
     }),
   },
 ] as const)

package/runtime/dev/coordinator.ts

@@ -11,6 +11,11 @@ export interface CoordinatorDeps {
   /** Recompile native-route `.jinja` templates from source and reload them into
    * the minijinja env, so `native: true` routes pick up .tsx edits on reload. */
   reEmitJinja: () => Promise<void>
+  /** Clear the Rust-side island ISR cache. Called on every render-affecting
+   * reload (`ts`/`html`/`islands`) so a `.tsx` edit is reflected immediately —
+   * a frozen island render from before the edit must never survive a hot reload.
+   * Optional: a build without the island-cache addon export omits it. */
+  clearIslandCache?: () => void
   buildComponentCss?: () => Promise<void>
   snapshotComponentCss?: () => Promise<import('../css/manifest.ts').ComponentCssManifest | null>
   broadcast: (msg: DevMessage) => Promise<void> | void
@@ -34,6 +39,8 @@ export class Coordinator {
       switch (ev.kind) {
         case 'ts':
         case 'html':
+          // Stale frozen island renders must not survive a source edit.
+          this.deps.clearIslandCache?.()
           await this.deps.workers.terminateAll()
           await this.deps.workers.spawnAll()
           // Reload native-route templates (process-global minijinja env — does
@@ -42,6 +49,7 @@ export class Coordinator {
           await this.deps.broadcast({ type: 'reload' })
           break
         case 'islands':
+          this.deps.clearIslandCache?.()
           await this.deps.buildIslands()
           await this.deps.workers.terminateAll()
           await this.deps.workers.spawnAll()

package/runtime/index.d.ts

@@ -2,6 +2,11 @@
 /* eslint-disable */
 export declare function beginServe(opts: ServeOptions): NapiResult<undefined>
 
+export interface CachedIslandJs {
+  html: string
+  props: string
+}
+
 /**
  * Compile a single native-route source to its jinja template + island
  * manifest. `path` is used only in error messages. Mirrors `jsx-rustc`'s
@@ -16,6 +21,14 @@ export declare function configureCssDir(path: string): NapiResult<undefined>
 
 export declare function configureIslandsDir(path: string): NapiResult<undefined>
 
+export declare function islandCacheClear(): void
+
+export declare function islandCacheGet(key: string): CachedIslandJs | null
+
+export declare function islandCacheInvalidate(key?: string | undefined | null, tags?: Array<string> | undefined | null): void
+
+export declare function islandCacheSet(key: string, tags: Array<string>, ttlMs: number | undefined | null, html: string, props: string): void
+
 export declare function isWorker(): boolean
 
 /** Result of compiling one `pages/<Name>.tsx` source. */

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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-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.6-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.6-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.7-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.7-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -581,6 +581,10 @@ module.exports.compileJsx = nativeBinding.compileJsx
 module.exports.configureCache = nativeBinding.configureCache
 module.exports.configureCssDir = nativeBinding.configureCssDir
 module.exports.configureIslandsDir = nativeBinding.configureIslandsDir
+module.exports.islandCacheClear = nativeBinding.islandCacheClear
+module.exports.islandCacheGet = nativeBinding.islandCacheGet
+module.exports.islandCacheInvalidate = nativeBinding.islandCacheInvalidate
+module.exports.islandCacheSet = nativeBinding.islandCacheSet
 module.exports.isWorker = nativeBinding.isWorker
 module.exports.napiDevBroadcast = nativeBinding.napiDevBroadcast
 module.exports.napiListNativeTemplates = nativeBinding.napiListNativeTemplates

package/runtime/index.ts

@@ -488,6 +488,11 @@ export const brust = {
             },
           },
           reEmitJinja,
+          // Wipe the Rust-side island ISR cache on every render-affecting reload
+          // so a frozen island render never survives a `.tsx` edit in dev.
+          clearIslandCache: () => {
+            ;(native as any).islandCacheClear?.()
+          },
           buildCss: async () => {
             const appCss = pathModule.join(scanRoot, 'app.css')
             if (fsModule.existsSync(appCss)) {
@@ -679,3 +684,6 @@ export type { BrustPageProps } from './islands/brust-page.tsx'
 
 export { buildIslands } from './islands/build.ts'
 export type { IslandsBuildResult, BuildIslandsOptions } from './islands/build.ts'
+
+export { cache } from './cache.ts'
+export type { InvalidateArgs } from './cache.ts'

package/runtime/islands/__fixtures__/CountingIsland.tsx

@@ -0,0 +1,10 @@
+// Test fixture: an SSR island that bumps a shared counter on every render, so
+// the ISR integration test can prove a cache HIT skipped renderToString. Markup
+// embeds `n` (same shape as StubIsland) so the served html is assertable.
+import { createElement } from 'react'
+import { renderCounter } from './render-counter.ts'
+
+export default ({ n }: { n: number }) => {
+  renderCounter.count++
+  return createElement('span', null, String(n))
+}

package/runtime/islands/__fixtures__/render-counter.ts

@@ -0,0 +1,5 @@
+// Shared render counter for the ISR integration test. The CountingIsland
+// fixture increments `count` each time it server-renders; the test imports this
+// SAME module (Bun module cache makes it a singleton) to assert how many times
+// renderToString actually ran — i.e. whether the ISR cache served a hit.
+export const renderCounter = { count: 0 }

package/runtime/islands/native-render.ts

@@ -28,6 +28,21 @@ export interface NativeIslandEntry {
   ssr: boolean
   hydrate: string
   sourcePath: string
+  /** Dotted path into loader data yielding the ISR cache key (string). */
+  keyPath?: string
+  /** Dotted path into loader data yielding the ISR cache tags (string[]). */
+  tagsPath?: string
+  /** Revalidate window in SECONDS; converted to ttlMs on cache.set. */
+  revalidate?: number
+}
+
+/** Rust-side ISR cache, injected as a port for testability. A `get` hit
+ * returns a FROZEN {html,props} pair (the props are the entity-encoded attr
+ * string, identical to what was stored) so the served markup and the hydrated
+ * props stay byte-identical regardless of live loader-data mutation. */
+export interface IslandCache {
+  get(key: string): { html: string; props: string } | null
+  set(key: string, tags: string[], ttlMs: number | undefined, html: string, props: string): void
 }
 
 /** Walk a dotted path into `data`. Each segment must be an OWN enumerable
@@ -109,17 +124,42 @@ const componentCache = new Map<string, unknown>()
 export async function resolveIslandContext(
   manifest: NativeIslandEntry[],
   data: unknown,
+  cache?: IslandCache,
 ): Promise<Record<string, string>> {
   const out: Record<string, string> = {}
   for (const entry of manifest) {
     const props = pathInto(data, entry.propsPath)
     // `?? null` handles undefined props; the `?? 'null'` belt-and-braces covers
     // the case where JSON.stringify itself returns undefined (e.g. a function
-    // value), so entityEncode never receives undefined.
-    out['island_' + entry.instance + '_props'] = entityEncode(
-      JSON.stringify(props ?? null) ?? 'null',
-    )
+    // value), so entityEncode never receives undefined. Hoisted ABOVE the ssr
+    // branch so the SAME attr string is stored in (and served from) the cache
+    // AND hydrated against — byte-identity is the ISR hydration-safety invariant.
+    const propsAttr = entityEncode(JSON.stringify(props ?? null) ?? 'null')
+    out['island_' + entry.instance + '_props'] = propsAttr
     if (!entry.ssr) continue
+
+    // ISR fast-path: resolve a string cache key out of loader data. A hit
+    // serves the FROZEN {html,props} pair (overwriting the live _props with the
+    // stored one) and skips render. A non-string-but-defined key is a manifest
+    // bug — warn and fall through to an uncached render.
+    let key: string | undefined
+    if (cache && entry.keyPath) {
+      const k = pathInto(data, entry.keyPath)
+      if (typeof k === 'string') {
+        key = k
+        const hit = cache.get(key)
+        if (hit) {
+          out['island_' + entry.instance + '_html'] = hit.html
+          out['island_' + entry.instance + '_props'] = hit.props
+          continue
+        }
+      } else if (k !== undefined) {
+        console.warn(
+          `[brust] ssr island "${entry.component}" ISR keyPath "${entry.keyPath}" resolved to a non-string value; rendering uncached`,
+        )
+      }
+    }
+
     try {
       let Component = componentCache.get(entry.sourcePath)
       if (Component === undefined) {
@@ -134,9 +174,30 @@ export async function resolveIslandContext(
       // JSON.parse(data-brust-props) — byte-identity guarantees no hydration
       // mismatch. props ?? undefined: pass the actual value (or undefined) to
       // the component, NOT the `null` sentinel used for the props string.
-      out['island_' + entry.instance + '_html'] = renderToString(
-        createElement(Component as any, (props ?? undefined) as any),
-      )
+      const html = renderToString(createElement(Component as any, (props ?? undefined) as any))
+      out['island_' + entry.instance + '_html'] = html
+      // Write-through: only on the SUCCESS path (a throwing render must not
+      // poison the cache). Store the SAME entity-encoded propsAttr so a later
+      // hit hydrates byte-identically.
+      if (cache && key) {
+        // Resolve tags only when tagsPath is set (avoids pathInto('') returning
+        // the whole loader object). Must be a string[] — the value crosses to
+        // Rust as Vec<String>, so a non-array OR an array with a non-string
+        // element degrades to no tags + a warning, never a bad NAPI payload.
+        let tags: string[] = []
+        if (entry.tagsPath !== undefined) {
+          const tagsValue = pathInto(data, entry.tagsPath)
+          if (Array.isArray(tagsValue) && tagsValue.every((t) => typeof t === 'string')) {
+            tags = tagsValue
+          } else if (tagsValue !== undefined) {
+            console.warn(
+              `[brust] ssr island "${entry.component}" ISR tagsPath "${entry.tagsPath}" must resolve to a string[]; using no tags`,
+            )
+          }
+        }
+        const ttlMs = entry.revalidate !== undefined ? entry.revalidate * 1000 : undefined
+        cache.set(key, tags, ttlMs, html, propsAttr)
+      }
     } catch (e) {
       // CONTAINED FAILURE (spec invariant): a throwing ssr island degrades to
       // an empty mount (no _html) + logged warning, rather than 500-ing the

package/runtime/routes.ts

@@ -12,8 +12,26 @@ import { Buffer } from 'node:buffer'
 import * as native from './index.js'
 import { renderBranchStreaming } from './render/stream.ts'
 import { loadIslandManifest, resolveIslandContext } from './islands/native-render.ts'
+import type { IslandCache } from './islands/native-render.ts'
 import type { ActionDef } from './actions.ts'
 
+// Sub-project J — island ISR cache, backed by the Rust-side store (shared across
+// the worker pool) via NAPI. napi-rs maps snake→camel: island_cache_get →
+// islandCacheGet, island_cache_set → islandCacheSet. `as any` avoids depending on
+// the regenerated .d.ts — the addon isn't rebuilt locally; index.js/*.node are
+// gitignored and CI rebuilds. Optional-chaining (`?.`) means a STALE addon (built
+// before these exports existed) degrades gracefully: get → undefined → null (a
+// cache miss → normal render), set → no-op. Caching is an enhancement, never a
+// hard dependency — unlike napiRenderJinja which has no fallback.
+const islandCache: IslandCache = {
+  get(key) {
+    return (native as any).islandCacheGet?.(key) ?? null
+  },
+  set(key, tags, ttlMs, html, props) {
+    ;(native as any).islandCacheSet?.(key, tags, ttlMs, html, props)
+  },
+}
+
 // Permanently-unaborted AbortSignal sentinel for non-SSE routes.
 // The controller is held in module scope and never .abort()-ed, keeping
 // the signal alive in the unaborted state. Do NOT use AbortSignal.abort()
@@ -595,7 +613,7 @@ export function makeRenderer(
         const manifest = loadIslandManifest(flat.nativeTemplate)
         if (manifest && manifest.length > 0) {
           const rt = JSON.parse(json) // roundtrip ONCE; props read from rt
-          const extra = await resolveIslandContext(manifest, rt)
+          const extra = await resolveIslandContext(manifest, rt, islandCache)
           const ctx = { ...rt, ...extra }
           const finalBytes = encoder.encode(JSON.stringify(ctx))
           // The original size check guarded the pre-island bytes; the merged