brustjs 0.1.8-alpha → 0.1.10-alpha

package/package.json

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

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

@@ -1,8 +1,88 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
+import { dirname, relative, resolve } from 'node:path'
 import { buildDevClientTag } from '../dev/client.ts'
 import { ISLANDS_IMPORTMAP_AND_BOOTSTRAP } from '../islands/importmap.ts'
 
+/** Gather transitive component sources starting from a page source file.
+ *
+ * BFS/DFS over local imports reachable from `pageSourcePath`:
+ * - Reads each file's source text and adds it to `sources[ident]`.
+ * - Recursively follows local imports in each visited file.
+ * - Deduplicates by resolved path to handle cycles.
+ * - `mergedImports` is the union of every visited file's `scanImports`, with
+ *   the page's own imports taking precedence on a conflicting ident.
+ *
+ * Throws when the same ident resolves to two different absolute paths (across
+ * two different importing files) — that would be ambiguous for the Rust
+ * compiler. */
+export function gatherComponentSources(pageSourcePath: string): {
+  sources: Record<string, string>
+  mergedImports: Map<string, string>
+} {
+  const sources: Record<string, string> = {}
+  // mergedImports accumulates ident→resolvedPath across ALL visited files.
+  // The page's own imports win on conflict (inserted last below).
+  const mergedImports = new Map<string, string>()
+  const visited = new Set<string>()
+
+  // Queue items: { ident, resolvedPath } — ident is how the PARENT imported it.
+  // We start with the children of pageSourcePath (not the page itself).
+  function visit(filePath: string, ident: string) {
+    if (visited.has(filePath)) return
+    visited.add(filePath)
+
+    const sourceText = readFileSync(filePath, 'utf8')
+
+    // Record source keyed by ident — detect ambiguity.
+    if (ident in sources) {
+      // Same ident already seen — only an error if it resolves to a different path.
+      // We get the previous path from mergedImports (which maps ident → resolvedPath).
+      const existingPath = mergedImports.get(ident)
+      if (existingPath && existingPath !== filePath) {
+        throw new Error(
+          `native build: ambiguous component ident "${ident}" resolves to two paths: ${existingPath} and ${filePath}`,
+        )
+      }
+    } else {
+      sources[ident] = sourceText
+    }
+
+    // Scan this file's imports and recurse into local ones.
+    const childImports = scanImports(filePath)
+    for (const [childIdent, childPath] of childImports) {
+      // Merge into mergedImports — check for ambiguity.
+      const existing = mergedImports.get(childIdent)
+      if (existing !== undefined && existing !== childPath) {
+        throw new Error(
+          `native build: ambiguous component ident "${childIdent}" resolves to two paths: ${existing} and ${childPath}`,
+        )
+      }
+      if (existing === undefined) {
+        mergedImports.set(childIdent, childPath)
+      }
+      // Recurse into local files (skip node_modules / unresolved paths).
+      if (!childPath.includes('node_modules')) {
+        visit(childPath, childIdent)
+      }
+    }
+  }
+
+  // Seed: scan the page's own imports and visit each local file.
+  const pageImports = scanImports(pageSourcePath)
+  for (const [ident, resolvedPath] of pageImports) {
+    if (!resolvedPath.includes('node_modules')) {
+      visit(resolvedPath, ident)
+    }
+  }
+
+  // Page's own imports win on ident conflict — merge them last.
+  for (const [ident, resolvedPath] of pageImports) {
+    mergedImports.set(ident, resolvedPath)
+  }
+
+  return { sources, mergedImports }
+}
+
 /** Dev-only: splice the /_brust/dev WS client `<script>` into a compiled native
  * template so `native: true` (jinja) routes auto-reload like React-SSR routes.
  *
@@ -48,6 +128,29 @@ export interface NativeRouteEmitOpts {
   repoRoot: string
 }
 
+/** Raw component entry from compileJsx's `componentsJson` field. camelCase keys
+ * match what Rust's `components_to_json` emits. */
+interface RawComponentEntry {
+  component: string
+  instance: number
+  factoryExpr: string
+  referencedComponents: string[]
+  usesIsland: boolean
+  /** ISR cache fields (present only on components with an `isr` attr). Declared
+   * so the `{ ...entry }` / `{ ...e }` enrich spreads below are type-complete —
+   * they MUST survive into the enriched `<Name>.components.json`, or runtime ISR
+   * caching for SSR components silently never activates. Mirrors RawIslandEntry. */
+  keyPath?: string
+  tagsPath?: string
+  revalidate?: number
+}
+
+/** Enriched component entry written to `<Name>.components.json`. */
+interface EnrichedComponentEntry extends RawComponentEntry {
+  /** Absolute path to the component's source file (resolved from page imports). */
+  sourcePath: string
+}
+
 /** One entry in a `<Name>.islands.json` as emitted by `jsx-rustc` (camelCase,
  * see crates/jsx-rust-compiler/src/lib.rs). Enriched with `sourcePath`. */
 interface RawIslandEntry {
@@ -69,6 +172,130 @@ interface EnrichedIslandEntry extends RawIslandEntry {
   sourcePath: string
 }
 
+/** Build a portable ESM specifier (forward slashes, kept `./`/`../`-prefixed)
+ * for `to` interpreted against directory `from`. Used for the factory's
+ * component imports so they resolve relative to the factory FILE at runtime
+ * instead of baking the build machine's absolute path. */
+function toRelativeSpecifier(from: string, to: string): string {
+  const rel = relative(from, to).replaceAll('\\', '/')
+  return rel.startsWith('.') ? rel : `./${rel}`
+}
+
+/** Write `<Name>.components.json` and `<Name>.factory.ts` for a native route
+ * that has SSR components. Also scans each SSR component's source for Island
+ * `component={X}` references and returns those identifiers so the build step
+ * can ensure their JS chunks are built.
+ *
+ * Both artifacts use PROJECT-RELATIVE paths, never the build machine's absolute
+ * path: `components.json` stores `sourcePath` relative to the project root
+ * (cwd); `.factory.ts` imports relative to its own location (`.brust/jinja/`).
+ * `enriched` keeps the ABSOLUTE path internally for the build-time island scan
+ * below (`readFileSync`). */
+function emitComponentArtifacts(
+  jinjaPath: string,
+  componentsJsonStr: string,
+  pageImports: Map<string, string>,
+  routeName: string,
+): { islandIdsFromComponents: string[] } {
+  const raw = JSON.parse(componentsJsonStr) as RawComponentEntry[]
+  if (raw.length === 0) return { islandIdsFromComponents: [] }
+
+  const jinjaDir = dirname(jinjaPath)
+  const projectRoot = process.cwd()
+
+  // Enrich with ABSOLUTE source paths resolved from page's own imports — kept
+  // absolute for the readFileSync island scan further down.
+  const enriched: EnrichedComponentEntry[] = raw.map((entry) => {
+    const sourcePath = pageImports.get(entry.component)
+    if (!sourcePath) {
+      throw new Error(
+        `SSR component "${entry.component}" in native route "${routeName}" has no matching import in the page source (expected \`import ${entry.component} from "..."\`)`,
+      )
+    }
+    return { ...entry, sourcePath }
+  })
+
+  // Write <Name>.components.json with PROJECT-RELATIVE sourcePaths. (sourcePath
+  // is build-time metadata — resolveComponentContext imports the factory, not
+  // these paths — so relative is purely a portability/readability win.)
+  const compJsonPath = jinjaPath.replace(/\.jinja$/, '.components.json')
+  const compJsonEntries = enriched.map((e) => ({
+    ...e,
+    sourcePath: relative(projectRoot, e.sourcePath).replaceAll('\\', '/'),
+  }))
+  writeFileSync(compJsonPath, JSON.stringify(compJsonEntries))
+
+  // Collect import lines. Deduplicate referenced components.
+  const seen = new Set<string>()
+  const importLines: string[] = []
+  const needsIsland = enriched.some((e) => e.usesIsland)
+
+  // React createElement is always needed.
+  importLines.push("import { createElement as h } from 'react'")
+  if (needsIsland) {
+    importLines.push("import { Island } from 'brustjs'")
+  }
+
+  // Import each referenced component RELATIVE to the factory file's own dir so
+  // `await import(factory)` resolves them at runtime regardless of where the
+  // project lives (no absolute build-machine path baked in).
+  const allReferenced = [...new Set(enriched.flatMap((e) => e.referencedComponents))]
+  for (const compName of allReferenced) {
+    if (seen.has(compName)) continue
+    seen.add(compName)
+    const srcPath = pageImports.get(compName)
+    if (srcPath) {
+      const spec = toRelativeSpecifier(jinjaDir, srcPath)
+      importLines.push(`import ${compName} from ${JSON.stringify(spec)}`)
+    }
+  }
+
+  // Scan SSR component sources for <Island component={X}> to discover Island
+  // chunk identifiers that don't appear in the page's own .islands.json.
+  const islandIdsFromComponents: string[] = []
+  const islandAttrRe = /<Island\s[^>]*component=\{(\w+)\}/g
+  for (const entry of enriched) {
+    try {
+      const src = readFileSync(entry.sourcePath, 'utf8')
+      islandAttrRe.lastIndex = 0
+      for (;;) {
+        const m = islandAttrRe.exec(src)
+        if (m === null) break
+        if (m[1] && !islandIdsFromComponents.includes(m[1]!)) {
+          islandIdsFromComponents.push(m[1]!)
+        }
+      }
+    } catch {
+      // Unreadable source — skip
+    }
+  }
+
+  // Write <Name>.factory.ts
+  const factoryPath = jinjaPath.replace(/\.jinja$/, '.factory.ts')
+  const factoryLines = [
+    '// Auto-generated by brust build — do not edit',
+    ...importLines,
+    '',
+    'export const factories: Array<(ctx: any) => any> = [',
+    ...enriched.map((e, i) => `  // comp_${i}: ${e.component}\n  ${e.factoryExpr},`),
+    ']',
+  ]
+  writeFileSync(factoryPath, factoryLines.join('\n') + '\n')
+
+  // If any SSR component embeds an Island, bake the importmap + bootstrap into
+  // the Jinja template — the same injection reconcileIslandManifest would do.
+  // Without this the client bootstrap never loads and nested Islands don't hydrate.
+  if (needsIsland) {
+    const baked = `{% raw %}${ISLANDS_IMPORTMAP_AND_BOOTSTRAP}{% endraw %}`
+    const currentJinja = readFileSync(jinjaPath, 'utf8')
+    if (!currentJinja.includes(baked)) {
+      writeFileSync(jinjaPath, currentJinja + baked)
+    }
+  }
+
+  return { islandIdsFromComponents }
+}
+
 export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<void> {
   mkdirSync(opts.outDir, { recursive: true })
 
@@ -80,7 +307,11 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
   // the addon (`.node`) ships with every platform package, so this path works
   // for source builds and installed projects alike.
   let compileJsx:
-    | ((source: string, path: string) => { template: string; islandsJson: string })
+    | ((
+        source: string,
+        path: string,
+        componentSources?: Record<string, string>,
+      ) => { template: string; islandsJson: string; warnings?: string[] })
     | null = null
   if (nativeRoutes.length > 0) {
     const native = await import('../index.js')
@@ -107,12 +338,22 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
       continue
     }
     const outPath = resolve(opts.outDir, `${name}.jinja`)
-    let compiled: { template: string; islandsJson: string }
+
+    // Gather transitive component sources for native inlining and build the
+    // merged import map that covers nested components (e.g. islands inside an
+    // inlined native component that don't appear in the page's own imports).
+    const { sources, mergedImports } = gatherComponentSources(sourcePath)
+
+    let compiled: { template: string; islandsJson: string; warnings?: string[] }
     try {
-      compiled = compileJsx!(readFileSync(sourcePath, 'utf8'), sourcePath)
+      compiled = compileJsx!(readFileSync(sourcePath, 'utf8'), sourcePath, sources)
     } catch (e) {
       throw new Error(`native route "${name}" failed to compile (${sourcePath}):\n${String(e)}`)
     }
+
+    // Print non-fatal compiler warnings to stderr.
+    for (const w of compiled.warnings ?? []) process.stderr.write(`brust: ${w}\n`)
+
     // Dev-only: native routes don't pass through the React renderer's dev-client
     // injection, so splice the /_brust/dev WS script in here. reEmitJinja() runs
     // this on every hot reload, so the script is always present in dev.
@@ -130,12 +371,16 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
     const islandsJsonPath = resolve(opts.outDir, `${name}.islands.json`)
     if (compiled.islandsJson && compiled.islandsJson !== '[]') {
       writeFileSync(islandsJsonPath, compiled.islandsJson)
-      // Island source paths resolve from the PAGE file's own imports.
-      const pageImports = scanImports(sourcePath)
-      reconcileIslandManifest(outPath, islandsJsonPath, pageImports, name)
+      reconcileIslandManifest(outPath, islandsJsonPath, mergedImports, name)
     } else if (existsSync(islandsJsonPath)) {
       rmSync(islandsJsonPath, { force: true })
     }
+
+    // SSR component artifacts: .components.json + .factory.ts
+    const compJsonStr = (compiled as any).componentsJson ?? '[]'
+    if (compJsonStr !== '[]') {
+      emitComponentArtifacts(outPath, compJsonStr, mergedImports, name)
+    }
   }
 
   writeFileSync(

package/runtime/dev/coordinator.ts

@@ -39,8 +39,18 @@ export class Coordinator {
       switch (ev.kind) {
         case 'ts':
         case 'html':
+        case 'islands':
           // Stale frozen island renders must not survive a source edit.
           this.deps.clearIslandCache?.()
+          // Rebuild island CLIENT chunks. The watcher classifies every `.tsx`
+          // (incl. an island's client source) as `ts` — it has no way to tell
+          // an island source from a page/component by path alone, and the
+          // island set changes as you add/remove `<Island>` usages. So we
+          // rebuild island chunks on every render-affecting reload; otherwise
+          // editing an island's JS never reaches the browser without a
+          // dev-server restart (the chunk on disk stays stale). buildIslands
+          // re-scans routes + re-bundles into the served `.brust/islands` dir.
+          await this.deps.buildIslands()
           await this.deps.workers.terminateAll()
           await this.deps.workers.spawnAll()
           // Reload native-route templates (process-global minijinja env — does
@@ -48,14 +58,6 @@ export class Coordinator {
           await this.deps.reEmitJinja()
           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()
-          await this.deps.reEmitJinja()
-          await this.deps.broadcast({ type: 'reload' })
-          break
         case 'css':
           await this.deps.buildCss()
           await this.deps.broadcast({

package/runtime/index.d.ts

@@ -7,18 +7,19 @@ export interface CachedIslandJs {
   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
- * `compile_full` + `islands_to_json` so the TS emit step can write the same
- * `<Name>.jinja` and `<Name>.islands.json` files.
- */
-export declare function compileJsx(source: string, path: string): NapiCompiledJsx
+export declare function compileJsx(source: string, path: string, componentSources?: Record<string, string> | undefined | null): NapiCompiledJsx
 
 export declare function configureCache(maxEntries: number): NapiResult<undefined>
 
 export declare function configureCssDir(path: string): NapiResult<undefined>
 
+/**
+ * Enable/disable dev mode. Called by the TS dev coordinator (`brust.run` when
+ * `dev` is on). Flips static-asset caching to `no-store` so hot-reloaded island
+ * /CSS chunks (unhashed URLs) are never served stale from the browser cache.
+ */
+export declare function configureDevMode(enabled: boolean): void
+
 export declare function configureIslandsDir(path: string): NapiResult<undefined>
 
 export declare function islandCacheClear(): void
@@ -31,15 +32,24 @@ export declare function islandCacheSet(key: string, tags: Array<string>, ttlMs:
 
 export declare function isWorker(): boolean
 
-/** Result of compiling one `pages/<Name>.tsx` source. */
 export interface NapiCompiledJsx {
-  /** The emitted jinja template. */
   template: string
   /**
-   * Island manifest as JSON (`"[]"` when the route uses no `<Island>`). The
-   * camelCase keys match `RawIslandEntry` in native-routes-emit.ts.
+   * Island manifest as JSON (`"[]"` when no `<Island>`). camelCase keys match
+   * `RawIslandEntry` in native-routes-emit.ts.
    */
   islandsJson: string
+  /**
+   * SSR component manifest as JSON (`"[]"` when no SSR components). camelCase
+   * keys: `component`, `instance`, `factoryExpr`, `referencedComponents`,
+   * `usesIsland`.
+   */
+  componentsJson: string
+  /**
+   * Non-fatal diagnostic messages from native-inline lowering. Empty when no
+   * `component_sources` are provided (i.e. the default `None` path).
+   */
+  warnings: Array<string>
 }
 
 /**

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

package/runtime/index.ts

@@ -446,6 +446,11 @@ export const brust = {
       )
 
       if (dev) {
+        // Tell Rust we're in dev so static assets (islands/CSS chunks) are
+        // served `Cache-Control: no-store` — chunk URLs are unhashed, so a
+        // hot-reload rebuild would otherwise be masked by the browser cache.
+        // `?.` keeps an older addon (no export) from throwing.
+        ;(native as any).configureDevMode?.(true)
         const { createWatcher } = await import('./dev/watcher.ts')
         const { Coordinator } = await import('./dev/coordinator.ts')
         const { broadcast } = await import('./dev/ws-channel.ts')
@@ -678,6 +683,13 @@ export type { BrustConfig } from './config.ts'
 
 export { Island } from './islands/island.tsx'
 export type { IslandProps, HydrateTrigger } from './islands/island.tsx'
+// Side-effect import (NOT type-only) so the `react` JSX augmentation in
+// isr-jsx.ts is pulled into the program of any project that value-imports
+// brustjs — a type-only re-export would be elided and the augmentation lost.
+// The augmentation makes `isr` valid on any component, like `key`. (Compiles to
+// an empty module; harmless at runtime.)
+import './islands/isr-jsx.ts'
+export type { IsrConfig } from './islands/isr-jsx.ts'
 
 export { BrustPage } from './islands/brust-page.tsx'
 export type { BrustPageProps } from './islands/brust-page.tsx'

package/runtime/islands/__fixtures__/CountingComp.tsx

@@ -0,0 +1,11 @@
+// Test fixture: an SSR component that bumps the shared renderCounter on every
+// server render, so the component-ISR integration test can prove a cache HIT
+// skipped the factory render. Reuses the island fixture's render-counter
+// singleton (Bun module cache → same object across imports).
+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__/StubFactory.ts

@@ -0,0 +1,7 @@
+// Test fixture for resolveComponentContext. A factory that renders a <p>
+// element containing ctx.greeting. Uses createElement (no JSX) so it
+// transpiles trivially, and imports from the project's react so bare
+// specifiers resolve correctly from within the in-repo fixture directory.
+import { createElement as h } from 'react'
+
+export const factories: Array<(ctx: any) => any> = [(ctx: any) => h('p', null, ctx.greeting)]

package/runtime/islands/build.ts

@@ -35,7 +35,11 @@ export function scanIslandChunks(routesEntryFile: string): Map<string, string> {
     const source = readFileSync(pagePath, 'utf8')
     const pageImports = scanImports(pagePath)
 
-    const tags = source.match(/<Island\b[\s\S]*?\/>/g) ?? []
+    // `[^<]*?` (not `[\s\S]*?`) so a tag cannot bridge across another `<` — this
+    // stops a bare `<Island>` mentioned in a comment from lazily matching forward
+    // to an unrelated later `/>` (which would then falsely report "no component
+    // prop"). A real island tag never contains `<` between `<Island` and `/>`.
+    const tags = source.match(/<Island\b[^<]*?\/>/g) ?? []
     for (const tag of tags) {
       const compMatch = tag.match(/component=\{\s*(\w+)\s*\}/)
       if (!compMatch) {

package/runtime/islands/island.tsx

@@ -1,4 +1,5 @@
 import { createElement, type ComponentType, type ReactNode } from 'react'
+import type { IsrConfig } from './isr-jsx.ts'
 
 /** Triggers that activate hydration of an island marker. */
 export type HydrateTrigger = 'load' | 'idle' | 'visible' | 'interaction'
@@ -37,11 +38,7 @@ export interface IslandProps<P> {
    *
    * Example: `isr={{ key: data.cacheKey, tags: ['blog'], revalidate: 60 }}`
    */
-  isr?: {
-    key: string
-    tags?: string[]
-    revalidate?: number
-  }
+  isr?: IsrConfig
 }
 
 /** Module-scope flag flipped by every `<Island>` render. `makeRenderer`

package/runtime/islands/isr-jsx.ts

@@ -0,0 +1,53 @@
+// ISR config type + a global JSX augmentation that makes the `isr` attribute
+// accept-anywhere, the way React's built-in `key`/`ref` work.
+//
+// `isr` is a brust COMPILER attribute: the JSX compiler reads it at lower time
+// and strips it (it never reaches the component at runtime — the generated
+// factory contains no `isr` prop). So, like `key`, it is not part of any
+// component's own props type. Without this augmentation TypeScript would reject
+// `<MyLayout isr={{ … }}>` because the user's `MyLayout` props don't declare
+// `isr`. Augmenting `React.Attributes` (where `key` lives) makes `isr` valid on
+// every element/component with zero per-component boilerplate.
+//
+// This file must stay in the package's type import graph (it is re-exported
+// from `runtime/index.ts` and consumed by `island.tsx`) so the augmentation is
+// in scope for any project that imports from `brustjs`.
+
+/** Shape of the `isr` attribute on an SSR component or `ssr` island on a
+ * native-jinja route. `renderToString` runs ONCE per `key`; later same-key
+ * requests serve the frozen markup from the Rust-side cache. */
+export interface IsrConfig {
+  /** Required unique cache key. A different key is a different cached render.
+   * Compute it in the loader and pass it through (e.g. `data.cacheKey`). */
+  key: string
+  /** Optional groups for bulk invalidation —
+   * `import { cache } from 'brustjs'; cache.invalidate({ tags: ['blog'] })`
+   * evicts every entry carrying a tag. `cache.invalidate({ key })` evicts one. */
+  tags?: string[]
+  /** Optional TTL in SECONDS (integer). Omit to cache until invalidated. */
+  revalidate?: number
+}
+
+// Augment `React.JSX.IntrinsicAttributes` — the interface the `react-jsx`
+// transform consults for props allowed on EVERY element/component (it is where
+// `key` lives, via `IntrinsicAttributes extends React.Attributes`). Targeting it
+// directly is the form that actually merges under React 19's `export = React`
+// types; augmenting `React.Attributes` does not propagate through the export-=
+// module boundary.
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicAttributes {
+      /** brust ISR cache directive — compiler-consumed (stripped before the
+       * component is called), valid on any SSR component or `ssr` island on a
+       * native route. See {@link IsrConfig}. */
+      isr?: IsrConfig
+      /** brust `native` inline directive — compiler-consumed (stripped at lower
+       * time). On a native-jinja route, `<Comp native />` expands the component
+       * inline at compile time (no JS-worker render) when it is pure
+       * (props→JSX, no hooks/side-effects); otherwise it degrades to a normal
+       * SSR component with a build warning. Bare boolean, like `ssr` on an
+       * island. */
+      native?: boolean
+    }
+  }
+}

package/runtime/islands/native-render.ts

@@ -34,6 +34,10 @@ export interface NativeIslandEntry {
   tagsPath?: string
   /** Revalidate window in SECONDS; converted to ttlMs on cache.set. */
   revalidate?: number
+  /** Static ISR cache key (string literal in JSX). Takes precedence over keyPath. */
+  keyLiteral?: string
+  /** Static ISR cache tags (array literal in JSX). Takes precedence over tagsPath. */
+  tagsLiteral?: string[]
 }
 
 /** Rust-side ISR cache, injected as a port for testability. A `get` hit
@@ -143,22 +147,27 @@ export async function resolveIslandContext(
     // 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) {
+    if (cache && entry.keyLiteral !== undefined) {
+      // Literal key takes precedence over keyPath; it's always a string.
+      key = entry.keyLiteral
+    } else 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`,
         )
       }
     }
+    if (cache && key) {
+      const hit = cache.get(key)
+      if (hit) {
+        out['island_' + entry.instance + '_html'] = hit.html
+        out['island_' + entry.instance + '_props'] = hit.props
+        continue
+      }
+    }
 
     try {
       let Component = componentCache.get(entry.sourcePath)
@@ -185,7 +194,9 @@ export async function resolveIslandContext(
         // 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) {
+        if (entry.tagsLiteral !== undefined) {
+          tags = entry.tagsLiteral
+        } else if (entry.tagsPath !== undefined) {
           const tagsValue = pathInto(data, entry.tagsPath)
           if (Array.isArray(tagsValue) && tagsValue.every((t) => typeof t === 'string')) {
             tags = tagsValue
@@ -212,3 +223,144 @@ export async function resolveIslandContext(
   }
   return out
 }
+
+/** One entry in `<Name>.components.json` as enriched by `emitComponentArtifacts`. */
+export interface NativeComponentEntry {
+  component: string
+  instance: number
+  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
+  /** Static ISR cache key (string literal in JSX). Takes precedence over keyPath. */
+  keyLiteral?: string
+  /** Static ISR cache tags (array literal in JSX). Takes precedence over tagsPath. */
+  tagsLiteral?: string[]
+}
+
+// Cache component manifests by absolute path (same pattern as island manifests).
+const componentManifestCache = new Map<string, NativeComponentEntry[] | null>()
+
+/** Read `<jinjaDir>/<templateName>.components.json` and return the parsed entry
+ * array, or `null` if the file doesn't exist. Both hits and misses are cached
+ * by absolute path (same invariant as `loadIslandManifest`). */
+export function loadComponentManifest(
+  templateName: string,
+  jinjaDir?: string,
+): NativeComponentEntry[] | null {
+  const dir = jinjaDir ?? path.resolve(process.cwd(), '.brust/jinja')
+  const abs = path.resolve(dir, `${templateName}.components.json`)
+  if (componentManifestCache.has(abs)) return componentManifestCache.get(abs)!
+  let parsed: NativeComponentEntry[] | null
+  try {
+    parsed = JSON.parse(readFileSync(abs, 'utf8')) as NativeComponentEntry[]
+  } catch {
+    componentManifestCache.set(abs, null)
+    return null
+  }
+  componentManifestCache.set(abs, parsed)
+  return parsed
+}
+
+// Cache factory modules by absolute path.
+const factoryCache = new Map<string, { factories: Array<(ctx: unknown) => unknown> } | null>()
+
+/** Build the per-component context additions for a manifest. Each entry
+ * contributes `comp_<instance>_html` — the component rendered to HTML by
+ * the route's factory function. On `renderToString` failure: degrade to
+ * `comp_N_html = ""` and log, mirrors SSR island failure behaviour. */
+export async function resolveComponentContext(
+  manifest: NativeComponentEntry[],
+  data: unknown,
+  templateName: string,
+  jinjaDir?: string,
+  cache?: IslandCache,
+): Promise<Record<string, string>> {
+  const out: Record<string, string> = {}
+  if (!manifest.length) return out
+
+  const dir = jinjaDir ?? path.resolve(process.cwd(), '.brust/jinja')
+  const factoryPath = path.resolve(dir, `${templateName}.factory.ts`)
+
+  let factoryMod = factoryCache.get(factoryPath)
+  if (factoryMod === undefined) {
+    try {
+      factoryMod = (await import(factoryPath)) as {
+        factories: Array<(ctx: unknown) => unknown>
+      }
+    } catch {
+      factoryMod = null
+    }
+    factoryCache.set(factoryPath, factoryMod)
+  }
+
+  for (let i = 0; i < manifest.length; i++) {
+    const entry = manifest[i]!
+
+    // ISR fast-path: resolve a string cache key out of loader data. A hit
+    // serves the FROZEN html and skips the factory. 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.keyLiteral !== undefined) {
+      // Literal key takes precedence over keyPath; it's always a string.
+      key = entry.keyLiteral
+    } else if (cache && entry.keyPath) {
+      const k = pathInto(data, entry.keyPath)
+      if (typeof k === 'string') {
+        key = k
+      } else if (k !== undefined) {
+        console.warn(
+          `[brust] SSR component "${entry.component}" ISR keyPath "${entry.keyPath}" resolved to a non-string value; rendering uncached`,
+        )
+      }
+    }
+    if (cache && key) {
+      const hit = cache.get(key)
+      if (hit) {
+        // Components have NO `_props` slot (unlike islands): the cache stores
+        // props="" for component entries, so we serve only hit.html and
+        // deliberately ignore hit.props. See the write-through below.
+        out[`comp_${entry.instance}_html`] = hit.html
+        continue
+      }
+    }
+
+    try {
+      if (!factoryMod?.factories?.[i]) {
+        throw new Error(`factory[${i}] not found in ${factoryPath}`)
+      }
+      const node = factoryMod.factories[i]!(data)
+      const html = renderToString(node as React.ReactNode)
+      out[`comp_${entry.instance}_html`] = html
+      // Write-through: SUCCESS path only (a throwing render must not poison the
+      // cache). props is "" — components have no separate hydration props attr.
+      if (cache && key) {
+        let tags: string[] = []
+        if (entry.tagsLiteral !== undefined) {
+          tags = entry.tagsLiteral
+        } else 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 component "${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, '')
+      }
+    } catch (e) {
+      console.error(
+        `[brust] SSR component "${entry.component}" renderToString failed; degrading to empty:`,
+        e,
+      )
+      out[`comp_${entry.instance}_html`] = ''
+    }
+  }
+  return out
+}

package/runtime/routes.ts

@@ -8,10 +8,14 @@ import { createContext, createElement, useContext, type ComponentType, type Reac
 import { renderToPipeableStream } from 'react-dom/server.node'
 import { Writable } from 'node:stream'
 import { Buffer } from 'node:buffer'
-// @ts-expect-error - index.js is generated by napi-rs at build time
 import * as native from './index.js'
 import { renderBranchStreaming } from './render/stream.ts'
-import { loadIslandManifest, resolveIslandContext } from './islands/native-render.ts'
+import {
+  loadIslandManifest,
+  resolveIslandContext,
+  loadComponentManifest,
+  resolveComponentContext,
+} from './islands/native-render.ts'
 import type { IslandCache } from './islands/native-render.ts'
 import type { ActionDef } from './actions.ts'
 
@@ -605,19 +609,33 @@ export function makeRenderer(
           }
         }
         const json = JSON.stringify(data ?? {})
-        // Sub-project J — islands. If this template has an enriched islands
-        // manifest, merge per-island context vars (island_<id>_props, plus
-        // island_<id>_html for ssr entries) into the loader data before
-        // shipping it. resolveIslandContext is async (T9: it awaits the dynamic
-        // import + renderToString of each ssr island source).
+        // Sub-project J — islands + components. If this template has an enriched
+        // islands manifest or a components manifest, merge per-island context vars
+        // (island_<id>_props, plus island_<id>_html for ssr entries) and per-component
+        // context vars (comp_<id>_html for SSR components) into the loader data before
+        // shipping it. Both resolvers are async; run them in parallel via Promise.all.
         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, islandCache)
-          const ctx = { ...rt, ...extra }
+        const compManifest = loadComponentManifest(flat.nativeTemplate)
+        if ((manifest && manifest.length > 0) || (compManifest && compManifest.length > 0)) {
+          const rt = JSON.parse(json) as Record<string, unknown>
+          const [islandExtra, componentExtra] = await Promise.all([
+            manifest && manifest.length > 0
+              ? resolveIslandContext(manifest, rt, islandCache)
+              : Promise.resolve({} as Record<string, string>),
+            compManifest && compManifest.length > 0
+              ? resolveComponentContext(
+                  compManifest,
+                  rt,
+                  flat.nativeTemplate,
+                  undefined,
+                  islandCache,
+                )
+              : Promise.resolve({} as Record<string, string>),
+          ])
+          const ctx = { ...rt, ...islandExtra, ...componentExtra }
           const finalBytes = encoder.encode(JSON.stringify(ctx))
           // The original size check guarded the pre-island bytes; the merged
-          // context (with island props) can be larger. Re-check on finalBytes.
+          // context (with island props + component html) can be larger. Re-check on finalBytes.
           if (finalBytes.length > view.length) {
             return packSingleChunkResponse(view, encoder, {
               status: 413,