brustjs 0.1.61-alpha → 0.1.63-alpha

package/package.json

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

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

@@ -1,12 +1,29 @@
 import { createHash } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { dirname, relative, resolve } from 'node:path'
 import { buildDevClientTag } from '../dev/client.ts'
 import { insertGeneratorMeta, insertShellMeta, resolveGenerator } from '../generator.ts'
 import { islandChunkBasename } from '../islands/chunk-id.ts'
+import { emitBehaviorSsrModule } from '../islands/behavior-ssr-loader.ts'
 import { DIRECTIVES_BOOTSTRAP, ISLANDS_IMPORTMAP_AND_BOOTSTRAP } from '../islands/importmap.ts'
 
+const NATIVE_INLINE_FALLBACK_WARNING = /^native component "([^"\r\n]+)" not inlined: ([\s\S]+)$/
+
+export function formatCompilerWarning(warning: string): string {
+  const match = NATIVE_INLINE_FALLBACK_WARNING.exec(warning)
+  if (!match) return `brust: ${warning}`
+
+  const [, component, reason] = match
+  return [
+    `brust: warning — native component "${component}" was not inlined`,
+    `  reason: ${reason}`,
+    '  impact: rendered through React SSR; React hooks and event handlers are not hydrated automatically on a native route',
+    `  interactive fix: use <Island component={${component}} props={...} />`,
+    `  zero-JS fix: rewrite ${component} using native-compatible JSX`,
+  ].join('\n')
+}
+
 /** Gather transitive component sources starting from a page source file.
  *
  * BFS/DFS over local imports reachable from `pageSourcePath`:
@@ -391,6 +408,7 @@ interface RawComponentEntry {
   factoryExpr: string
   referencedComponents: string[]
   usesIsland: boolean
+  behaviorModules: RawBehaviorModule[]
   /** 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
@@ -400,10 +418,58 @@ interface RawComponentEntry {
   revalidate?: number
 }
 
+interface RawBehaviorModule {
+  component: string
+  directiveName: string
+  source: string
+}
+
+interface EnrichedBehaviorModule extends RawBehaviorModule {
+  moduleId: string
+  sourcePath: string
+}
+
 /** 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
+  behaviorModules: EnrichedBehaviorModule[]
+}
+
+function behaviorArtifactPrefix(routeName: string): string {
+  const routeScope = createHash('sha256').update(routeName).digest('hex').slice(0, 16)
+  return `__brust_behavior_${routeScope}_`
+}
+
+function behaviorModuleId(
+  routeName: string,
+  sourcePath: string,
+  directiveName: string,
+  source: string,
+): string {
+  return createHash('sha256')
+    .update(`${routeName}\0${sourcePath}\0${directiveName}\0${source}`)
+    .digest('hex')
+}
+
+function behaviorArtifactPaths(jinjaPath: string, routeName: string): string[] {
+  const jinjaDir = dirname(jinjaPath)
+  const prefix = behaviorArtifactPrefix(routeName)
+  if (!existsSync(jinjaDir)) return []
+  return readdirSync(jinjaDir)
+    .filter((name) => name.startsWith(prefix) && name.endsWith('.tsx'))
+    .map((name) => resolve(jinjaDir, name))
+}
+
+/** Remove every server-only SSR-component sidecar owned by one route. The
+ * route hash in behavior filenames prevents cleanup from touching another
+ * route's generated module, even when both render the same component. */
+export function cleanupComponentArtifacts(jinjaPath: string, routeName: string): void {
+  rmSync(jinjaPath.replace(/\.jinja$/, '.components.json'), { force: true })
+  rmSync(jinjaPath.replace(/\.jinja$/, '.factory.ts'), { force: true })
+  for (const generatedPath of behaviorArtifactPaths(jinjaPath, routeName)) {
+    rmSync(generatedPath, { force: true })
+  }
 }
 
 /** One entry in a `<Name>.islands.json` as emitted by `jsx-rustc` (camelCase,
@@ -454,9 +520,9 @@ export function emitComponentArtifacts(
   componentsJsonStr: string,
   pageImports: Map<string, ResolvedImport>,
   routeName: string,
-): { islandIdsFromComponents: string[] } {
+): { islandIdsFromComponents: string[]; generatedPaths: string[] } {
   const raw = JSON.parse(componentsJsonStr) as RawComponentEntry[]
-  if (raw.length === 0) return { islandIdsFromComponents: [] }
+  if (raw.length === 0) return { islandIdsFromComponents: [], generatedPaths: [] }
 
   const jinjaDir = dirname(jinjaPath)
   const projectRoot = process.cwd()
@@ -464,6 +530,67 @@ export function emitComponentArtifacts(
   // Enrich with the resolved import ref. For local imports `ref.spec` is an
   // ABSOLUTE path (kept absolute for the readFileSync island scan below); for
   // bare imports it's the verbatim package specifier.
+  const behaviorByComponent = new Map<string, EnrichedBehaviorModule>()
+  for (const entry of raw) {
+    for (const module of entry.behaviorModules ?? []) {
+      const ref = pageImports.get(module.component)
+      if (!ref || ref.bare) {
+        throw new Error(
+          `SSR behavior component "${module.component}" in native route "${routeName}" has no local source import`,
+        )
+      }
+      const sourcePath = relative(projectRoot, ref.spec).replaceAll('\\', '/')
+      const moduleId = behaviorModuleId(routeName, sourcePath, module.directiveName, module.source)
+      const enrichedModule: EnrichedBehaviorModule = {
+        ...module,
+        moduleId,
+        sourcePath,
+      }
+      const prior = behaviorByComponent.get(module.component)
+      if (
+        prior &&
+        (prior.moduleId !== enrichedModule.moduleId ||
+          prior.directiveName !== enrichedModule.directiveName ||
+          prior.sourcePath !== enrichedModule.sourcePath)
+      ) {
+        throw new Error(
+          `SSR behavior component "${module.component}" has conflicting transformed definitions in native route "${routeName}"`,
+        )
+      }
+      behaviorByComponent.set(module.component, enrichedModule)
+    }
+  }
+
+  // If an opaque fallback parent imports one of the transformed behavior
+  // modules, its original source would otherwise bundle that child's original
+  // (unwired) source. Add unchanged passthrough parents until the import graph
+  // reaches a fixed point; the loader rewrites their local imports to the
+  // generated child artifacts below.
+  let addedPassthrough = true
+  while (addedPassthrough) {
+    addedPassthrough = false
+    const generatedSourcePaths = new Set(
+      [...behaviorByComponent.values()].map((module) => resolve(projectRoot, module.sourcePath)),
+    )
+    for (const [component, ref] of pageImports) {
+      if (!isComponentIdent(component) || ref.bare || behaviorByComponent.has(component)) continue
+      const importsGeneratedModule = [...scanImportRefs(ref.spec).values()].some(
+        (dependency) => !dependency.bare && generatedSourcePaths.has(dependency.spec),
+      )
+      if (!importsGeneratedModule) continue
+      const source = readFileSync(ref.spec, 'utf8')
+      const sourcePath = relative(projectRoot, ref.spec).replaceAll('\\', '/')
+      behaviorByComponent.set(component, {
+        component,
+        directiveName: '',
+        source,
+        sourcePath,
+        moduleId: behaviorModuleId(routeName, sourcePath, '', source),
+      })
+      addedPassthrough = true
+    }
+  }
+
   const enriched: Array<EnrichedComponentEntry & { ref: ResolvedImport }> = raw.map((entry) => {
     const ref = pageImports.get(entry.component)
     if (!ref) {
@@ -471,7 +598,14 @@ export function emitComponentArtifacts(
         `SSR component "${entry.component}" in native route "${routeName}" has no matching import in the page source (expected \`import ${entry.component} from "..."\`)`,
       )
     }
-    return { ...entry, sourcePath: ref.spec, ref }
+    return {
+      ...entry,
+      sourcePath: ref.spec,
+      behaviorModules: (entry.behaviorModules ?? []).map(
+        (module) => behaviorByComponent.get(module.component)!,
+      ),
+      ref,
+    }
   })
 
   // Write <Name>.components.json. For LOCAL imports sourcePath is PROJECT-RELATIVE
@@ -479,12 +613,70 @@ export function emitComponentArtifacts(
   // package spec verbatim. (sourcePath is build-time metadata — the factory
   // import is what's load-bearing at runtime.)
   const compJsonPath = jinjaPath.replace(/\.jinja$/, '.components.json')
-  const compJsonEntries = enriched.map(({ ref, ...e }) => ({
+  const compJsonEntries = enriched.map(({ ref, behaviorModules: _behaviorModules, ...e }) => ({
     ...e,
     sourcePath: ref.bare ? ref.spec : relative(projectRoot, ref.spec).replaceAll('\\', '/'),
   }))
   writeFileSync(compJsonPath, JSON.stringify(compJsonEntries))
 
+  const generatedSpecByComponent = new Map<string, string>()
+  const generatedPathByComponent = new Map<string, string>()
+  const generatedPaths: string[] = []
+  const artifactPrefix = behaviorArtifactPrefix(routeName)
+  for (const module of behaviorByComponent.values()) {
+    const filename = `${artifactPrefix}${module.moduleId}.tsx`
+    const outputPath = resolve(jinjaDir, filename)
+    generatedSpecByComponent.set(module.component, `./${filename}`)
+    generatedPathByComponent.set(module.component, outputPath)
+    generatedPaths.push(outputPath)
+  }
+  const componentBySourcePath = new Map(
+    [...behaviorByComponent.values()].map((module) => [
+      resolve(projectRoot, module.sourcePath),
+      module.component,
+    ]),
+  )
+  const emittedComponents = new Set<string>()
+  const emittingComponents = new Set<string>()
+  const emitGeneratedModule = (module: EnrichedBehaviorModule): void => {
+    if (emittedComponents.has(module.component)) return
+    if (!emittingComponents.add(module.component)) {
+      throw new Error(
+        `SSR behavior modules form an import cycle at "${module.component}" in native route "${routeName}"`,
+      )
+    }
+    const sourcePath = resolve(projectRoot, module.sourcePath)
+    for (const dependency of scanImportRefs(sourcePath).values()) {
+      if (dependency.bare) continue
+      const dependencyComponent = componentBySourcePath.get(dependency.spec)
+      if (!dependencyComponent) continue
+      emitGeneratedModule(behaviorByComponent.get(dependencyComponent)!)
+    }
+    const outputPath = generatedPathByComponent.get(module.component)!
+    emitBehaviorSsrModule(
+      {
+        ...module,
+        sourcePath,
+        dependencies: [...behaviorByComponent.values()]
+          .filter((dependency) => dependency.component !== module.component)
+          .map((dependency) => ({
+            sourcePath: resolve(projectRoot, dependency.sourcePath),
+            outputPath: generatedPathByComponent.get(dependency.component)!,
+          })),
+      },
+      outputPath,
+    )
+    emittingComponents.delete(module.component)
+    emittedComponents.add(module.component)
+  }
+  for (const module of behaviorByComponent.values()) {
+    emitGeneratedModule(module)
+  }
+  const currentGeneratedPaths = new Set(generatedPaths)
+  for (const stalePath of behaviorArtifactPaths(jinjaPath, routeName)) {
+    if (!currentGeneratedPaths.has(stalePath)) rmSync(stalePath, { force: true })
+  }
+
   // Collect import lines. Deduplicate referenced components.
   const seen = new Set<string>()
   const importLines: string[] = []
@@ -506,7 +698,12 @@ export function emitComponentArtifacts(
     seen.add(compName)
     const ref = pageImports.get(compName)
     if (!ref) continue
-    const spec = ref.bare ? ref.spec : toRelativeSpecifier(jinjaDir, ref.spec)
+    const generatedSpec = generatedSpecByComponent.get(compName)
+    const spec = generatedSpec
+      ? generatedSpec
+      : ref.bare
+        ? ref.spec
+        : toRelativeSpecifier(jinjaDir, ref.spec)
     const specStr = JSON.stringify(spec)
     if (ref.kind === 'namespace') {
       importLines.push(`import * as ${compName} from ${specStr}`)
@@ -566,7 +763,7 @@ export function emitComponentArtifacts(
     }
   }
 
-  return { islandIdsFromComponents }
+  return { islandIdsFromComponents, generatedPaths }
 }
 
 export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<NativeEmitStats> {
@@ -755,8 +952,12 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<Na
       )
     }
 
-    // Print non-fatal compiler warnings to stderr.
-    for (const w of compiled.warnings ?? []) process.stderr.write(`brust: ${w}\n`)
+    // Print non-fatal compiler warnings to stderr. Native-inline fallbacks get
+    // actionable multiline guidance; all other warning strings retain the
+    // existing one-line prefix.
+    for (const warning of compiled.warnings ?? []) {
+      process.stderr.write(`${formatCompilerWarning(warning)}\n`)
+    }
 
     // SPA navigation extracts the FIRST <main>…</main> block, so a native route
     // template must hold exactly one <main>. More than one (typically a leaf
@@ -802,11 +1003,14 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<Na
     // SSR component artifacts: .components.json + .factory.ts
     const compJsonStr = (compiled as any).componentsJson ?? '[]'
     if (compJsonStr !== '[]') {
-      emitComponentArtifacts(outPath, compJsonStr, mergedImports, name)
+      const { generatedPaths } = emitComponentArtifacts(outPath, compJsonStr, mergedImports, name)
       outputs.push(
         outPath.replace(/\.jinja$/, '.components.json'),
         outPath.replace(/\.jinja$/, '.factory.ts'),
+        ...generatedPaths,
       )
+    } else {
+      cleanupComponentArtifacts(outPath, name)
     }
 
     // R14 — memoize only what was hashed AND written by an incremental call;

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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-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.61-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.61-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.63-alpha' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.63-alpha but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {

package/runtime/islands/behavior-ssr-loader.ts

@@ -0,0 +1,71 @@
+import { randomUUID } from 'node:crypto'
+import { rmSync, writeFileSync } from 'node:fs'
+import { dirname, relative, resolve } from 'node:path'
+
+export interface BehaviorSsrDependency {
+  sourcePath: string
+  outputPath: string
+}
+
+export interface BehaviorSsrModule {
+  component: string
+  directiveName: string
+  moduleId: string
+  source: string
+  sourcePath: string
+  dependencies?: BehaviorSsrDependency[]
+}
+
+function rewriteBehaviorImports(entry: BehaviorSsrModule): string {
+  if (!entry.dependencies || entry.dependencies.length === 0) return entry.source
+  const dependencyBySource = new Map(
+    entry.dependencies.map((dependency) => [resolve(dependency.sourcePath), dependency.outputPath]),
+  )
+  return entry.source.replace(
+    /(\bfrom\s*['"])([^'"]+)(['"])/g,
+    (statement, before: string, specifier: string, after: string) => {
+      if (!specifier.startsWith('.')) return statement
+      const importBase = resolve(dirname(entry.sourcePath), specifier)
+      const candidates = [
+        importBase,
+        `${importBase}.tsx`,
+        `${importBase}.ts`,
+        resolve(importBase, 'index.tsx'),
+        resolve(importBase, 'index.ts'),
+      ]
+      const dependencyOutput = candidates
+        .map((candidate) => dependencyBySource.get(candidate))
+        .find((candidate) => candidate !== undefined)
+      if (!dependencyOutput) return statement
+      const rewritten = relative(dirname(entry.sourcePath), dependencyOutput).replaceAll('\\', '/')
+      return `${before}${rewritten.startsWith('.') ? rewritten : `./${rewritten}`}${after}`
+    },
+  )
+}
+
+export function emitBehaviorSsrModule(entry: BehaviorSsrModule, outputPath: string): void {
+  const temporaryEntry = `${entry.sourcePath}.brust-behavior-${randomUUID()}.tsx`
+  writeFileSync(temporaryEntry, rewriteBehaviorImports(entry))
+  try {
+    const result = Bun.spawnSync({
+      cmd: [
+        process.execPath,
+        'build',
+        temporaryEntry,
+        '--target=bun',
+        '--format=esm',
+        '--packages=external',
+        `--outfile=${outputPath}`,
+      ],
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `failed to generate SSR behavior module "${entry.component}" (${entry.moduleId}): ${result.stderr.toString()}`,
+      )
+    }
+  } finally {
+    rmSync(temporaryEntry, { force: true })
+  }
+}

package/runtime/md/emit.ts

@@ -16,6 +16,7 @@ import { insertGeneratorMeta, resolveGenerator } from '../generator.ts'
 import {
   bakeDirectivesIfUsed,
   buildChainWrapperSource,
+  cleanupComponentArtifacts,
   countMainTags,
   emitComponentArtifacts,
   extractLucideIcons,
@@ -384,6 +385,8 @@ export async function emitMdTemplates(opts: MdEmitOpts): Promise<{
     const compJsonStr = compiled.componentsJson ?? '[]'
     if (compJsonStr !== '[]') {
       emitComponentArtifacts(outPath, compJsonStr, mergedImports, name)
+    } else {
+      cleanupComponentArtifacts(outPath, name)
     }
 
     // 6. Single idempotent bake pass. Every append below is `includes()`-guarded

package/types/cli/native-routes-emit.d.ts

@@ -1,3 +1,4 @@
+export declare function formatCompilerWarning(warning: string): string;
 /** Gather transitive component sources starting from a page source file.
  *
  * BFS/DFS over local imports reachable from `pageSourcePath`:
@@ -137,6 +138,10 @@ export interface NativeEmitStats {
 }
 /** Clear the incremental memo (test isolation). */
 export declare function resetNativeEmitMemo(): void;
+/** Remove every server-only SSR-component sidecar owned by one route. The
+ * route hash in behavior filenames prevents cleanup from touching another
+ * route's generated module, even when both render the same component. */
+export declare function cleanupComponentArtifacts(jinjaPath: string, routeName: string): void;
 /** 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
@@ -152,6 +157,7 @@ export declare function resetNativeEmitMemo(): void;
  * can carry layout SSR components and need the same sidecar emission. */
 export declare function emitComponentArtifacts(jinjaPath: string, componentsJsonStr: string, pageImports: Map<string, ResolvedImport>, routeName: string): {
     islandIdsFromComponents: string[];
+    generatedPaths: string[];
 };
 export declare function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<NativeEmitStats>;
 /** A resolved import reference, capturing the import FORM so the SSR factory can

package/types/islands/behavior-ssr-loader.d.ts

@@ -0,0 +1,13 @@
+export interface BehaviorSsrDependency {
+    sourcePath: string;
+    outputPath: string;
+}
+export interface BehaviorSsrModule {
+    component: string;
+    directiveName: string;
+    moduleId: string;
+    source: string;
+    sourcePath: string;
+    dependencies?: BehaviorSsrDependency[];
+}
+export declare function emitBehaviorSsrModule(entry: BehaviorSsrModule, outputPath: string): void;