brustjs 0.1.65-alpha → 0.1.67-alpha

package/package.json

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

package/runtime/cli/ai-opt-in.ts

@@ -0,0 +1,85 @@
+import ts from 'typescript'
+
+/**
+ * Return true only when the entry contains a statically provable
+ * `brust.run({ ..., ai: true })` call through a named import from `brustjs`.
+ */
+export function entryHasLiteralAiOptIn(entry: string): boolean {
+  const program = ts.createProgram({
+    rootNames: [entry],
+    options: {
+      allowJs: true,
+      jsx: ts.JsxEmit.Preserve,
+      noLib: true,
+      noResolve: true,
+      target: ts.ScriptTarget.Latest,
+    },
+  })
+  const source = program.getSourceFile(entry)
+  if (!source) return false
+  const checker = program.getTypeChecker()
+  const brustBindings = new Set<ts.Symbol>()
+
+  for (const statement of source.statements) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      !ts.isStringLiteral(statement.moduleSpecifier) ||
+      statement.moduleSpecifier.text !== 'brustjs'
+    ) {
+      continue
+    }
+    const importClause = statement.importClause
+    if (!importClause || importClause.isTypeOnly) continue
+    const bindings = importClause.namedBindings
+    if (!bindings || !ts.isNamedImports(bindings)) continue
+    for (const element of bindings.elements) {
+      if (element.isTypeOnly) continue
+      if ((element.propertyName ?? element.name).text === 'brust') {
+        const symbol = checker.getSymbolAtLocation(element.name)
+        if (symbol) brustBindings.add(symbol)
+      }
+    }
+  }
+
+  let enabled = false
+  const visit = (node: ts.Node): void => {
+    if (enabled) return
+    const receiver =
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      ts.isIdentifier(node.expression.expression)
+        ? node.expression.expression
+        : undefined
+    const receiverSymbol = receiver ? checker.getSymbolAtLocation(receiver) : undefined
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      node.expression.name.text === 'run' &&
+      receiverSymbol &&
+      brustBindings.has(receiverSymbol)
+    ) {
+      const options = node.arguments[0]
+      if (options && ts.isObjectLiteralExpression(options) && hasLiteralAiTrue(options)) {
+        enabled = true
+        return
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(source)
+  return enabled
+}
+
+function hasLiteralAiTrue(options: ts.ObjectLiteralExpression): boolean {
+  let initializer: ts.Expression | undefined
+  for (const property of options.properties) {
+    if (ts.isSpreadAssignment(property)) return false
+    const name = property.name
+    const propertyName =
+      name && (ts.isIdentifier(name) || ts.isStringLiteral(name)) ? name.text : undefined
+    if (propertyName !== 'ai') continue
+    if (!ts.isPropertyAssignment(property)) return false
+    initializer = property.initializer
+  }
+  return initializer?.kind === ts.SyntaxKind.TrueKeyword
+}

package/runtime/cli/build.ts

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os'
 import path, { isAbsolute, resolve } from 'node:path'
 import type { BunPlugin } from 'bun'
 import { extractAiManifest, writeManifest as writeAiManifest } from '../ai/manifest.ts'
+import { entryHasLiteralAiOptIn } from './ai-opt-in.ts'
 import { emitNativeTemplates } from './native-routes-emit.ts'
 import { nativeShimPlugin } from './native-shim-plugin.ts'
 
@@ -251,14 +252,14 @@ export async function runBuild(args: string[]): Promise<void> {
     process.exit(1)
   }
   const { entry, outDir, target } = parsed
-  const aiEnabled = parsed.ai || process.env.BRUST_AI === '1'
-  if (aiEnabled) process.env.BRUST_AI = '1'
 
   // Entry existence is a runBuild concern (parseArgs stays fs-free/pure).
   if (!existsSync(entry)) {
     console.error(`brust build: no entry file at ${entry}; pass a path or create ./index.ts`)
     process.exit(1)
   }
+  const aiEnabled = parsed.ai || process.env.BRUST_AI === '1' || entryHasLiteralAiOptIn(entry)
+  if (aiEnabled) process.env.BRUST_AI = '1'
   const entryDir = path.dirname(entry)
 
   console.log(`[brust build] entry:  ${entry}`)

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

@@ -4,7 +4,7 @@ import { createRequire } from 'node:module'
 import { dirname, relative, resolve } from 'node:path'
 import { buildDevClientTag } from '../dev/client.ts'
 import {
-  aiScriptTag,
+  injectAiScriptIntoTemplate,
   insertGeneratorMeta,
   insertShellMeta,
   resolveGenerator,
@@ -259,11 +259,8 @@ export function countMainTags(template: string): number {
  *
  * Exported for the md emit step (runtime/md/emit.ts), which bakes the same tag
  * under its `withDevClient` option — md pages render Rust-side too, so without
- * it they never auto-reload in dev.
- *
- * The AI runtime script is injected here as well when BRUST_AI=1. The tag is
- * document-only: the compiler emits a head anchor for full documents, while
- * fragment templates (no head) are left unchanged. */
+ * it they never auto-reload in dev. AI injection is deliberately separate —
+ * production AI must never pull in this reconnect/overlay client. */
 export function injectDevClientIntoTemplate(template: string): string {
   const devTag = buildDevClientTag()
   let out = template
@@ -275,15 +272,6 @@ export function injectDevClientIntoTemplate(template: string): string {
       out += devTag
     }
   }
-  if (process.env.BRUST_AI === '1') {
-    const tag = aiScriptTag()
-    if (!out.includes(tag)) {
-      const headClose = out.indexOf('</head>')
-      if (headClose !== -1) {
-        out = out.slice(0, headClose) + tag + out.slice(headClose)
-      }
-    }
-  }
   return out
 }
 
@@ -1002,10 +990,10 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<Na
     // routes.ts makeFlat (never recomputed here), so native + React documents
     // carry the identical signature. Empty/missing → no-op.
     const withShell = insertShellMeta(withGenerator, r.shellId ?? '')
+    const withDevClient =
+      process.env.BRUST_DEV === '1' ? injectDevClientIntoTemplate(withShell) : withShell
     const template =
-      process.env.BRUST_DEV === '1' || process.env.BRUST_AI === '1'
-        ? injectDevClientIntoTemplate(withShell)
-        : withShell
+      process.env.BRUST_AI === '1' ? injectAiScriptIntoTemplate(withDevClient) : withDevClient
     writeFileSync(outPath, template)
     built.push(name)
     stats.compiled++

package/runtime/dev/coordinator.ts

@@ -8,6 +8,8 @@ export interface CoordinatorDeps {
   }
   buildCss: () => Promise<void>
   buildIslands: () => Promise<void>
+  /** Parse changed JS/TS modules before mutating the live generation. */
+  validateChanges: (paths: string[]) => Promise<void>
   /** Recompile native-route `.jinja` templates from source and reload them into
    * the minijinja env, so `native: true` routes pick up .tsx edits on reload. */
   reEmitJinja: () => Promise<void>
@@ -22,16 +24,72 @@ export interface CoordinatorDeps {
   tui: { appendEvent(line: string): void }
 }
 
-type State = 'idle' | 'building'
+type BuildDomain = 'full' | 'app-css' | 'component-css'
+
+interface PendingBatch {
+  kind: ChangeKind
+  paths: Set<string>
+}
+
+const DOMAIN_PRIORITY: BuildDomain[] = ['full', 'app-css', 'component-css']
 
 export class Coordinator {
-  private state: State = 'idle'
+  private readonly pending = new Map<BuildDomain, PendingBatch>()
+  private drainPromise: Promise<void> | null = null
 
   constructor(private deps: CoordinatorDeps) {}
 
-  async handleChange(ev: { paths: string[]; kind: ChangeKind }): Promise<void> {
-    if (this.state === 'building') return
-    this.state = 'building'
+  handleChange(ev: { paths: string[]; kind: ChangeKind }): Promise<void> {
+    const domain = domainFor(ev.kind)
+    const existing = this.pending.get(domain)
+    if (existing) {
+      for (const path of ev.paths) existing.paths.add(path)
+    } else {
+      this.pending.set(domain, { kind: ev.kind, paths: new Set(ev.paths) })
+    }
+
+    if (!this.drainPromise) {
+      this.startDrain()
+    }
+    return this.drainPromise!
+  }
+
+  private startDrain(): Promise<void> {
+    // Defer ownership by one microtask so the watcher's ordered callbacks for
+    // a mixed debounce window can coalesce into the three bounded domains.
+    const drain = Promise.resolve().then(() => this.drainPending())
+    let tracked!: Promise<void>
+    tracked = drain.finally(() => {
+      if (this.drainPromise !== tracked) return
+      this.drainPromise = null
+      // A callback can enqueue after drainPending observes an empty queue but
+      // before this finalizer runs. Chain its replacement drain so callers of
+      // the finishing drain still wait for all accepted work.
+      if (this.pending.size > 0) return this.startDrain()
+    })
+    this.drainPromise = tracked
+    return tracked
+  }
+
+  private async drainPending(): Promise<void> {
+    while (true) {
+      const event = this.takeNext()
+      if (!event) return
+      await this.runBatch(event)
+    }
+  }
+
+  private takeNext(): { paths: string[]; kind: ChangeKind } | null {
+    for (const domain of DOMAIN_PRIORITY) {
+      const batch = this.pending.get(domain)
+      if (!batch) continue
+      this.pending.delete(domain)
+      return { kind: batch.kind, paths: Array.from(batch.paths) }
+    }
+    return null
+  }
+
+  private async runBatch(ev: { paths: string[]; kind: ChangeKind }): Promise<void> {
     const started = performance.now()
     try {
       await this.deps.broadcast({ type: 'building' })
@@ -46,6 +104,7 @@ export class Coordinator {
         // per-isolate (islands/native-render.ts), so a re-emitted
         // .islands.json sidecar is never re-read by a live worker.
         case 'md':
+          await this.deps.validateChanges(ev.paths)
           // Stale frozen island renders must not survive a source edit.
           this.deps.clearIslandCache?.()
           // Rebuild island CLIENT chunks. The watcher classifies every `.tsx`
@@ -103,12 +162,16 @@ export class Coordinator {
         message: e.message ?? String(e),
         stack: e.stack,
       })
-    } finally {
-      this.state = 'idle'
     }
   }
 }
 
+function domainFor(kind: ChangeKind): BuildDomain {
+  if (kind === 'css') return 'app-css'
+  if (kind === 'component-css') return 'component-css'
+  return 'full'
+}
+
 function formatStart(ev: { paths: string[]; kind: ChangeKind }): string {
   const icon = ev.kind === 'css' ? '⎈' : '⏵'
   const label =

package/runtime/dev/validate-change.ts

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+
+const LOADERS = new Map<string, 'ts' | 'tsx' | 'js' | 'jsx'>([
+  ['.ts', 'ts'],
+  ['.tsx', 'tsx'],
+  ['.js', 'js'],
+  ['.jsx', 'jsx'],
+])
+
+export async function validateChangedModules(paths: string[]): Promise<void> {
+  const diagnostics: string[] = []
+  for (const filePath of paths) {
+    const loader = LOADERS.get(path.extname(filePath).toLowerCase())
+    if (!loader || !existsSync(filePath)) continue
+    const transpiler = new Bun.Transpiler({ loader, target: 'bun' })
+    try {
+      transpiler.transformSync(readFileSync(filePath, 'utf8'))
+    } catch (error) {
+      diagnostics.push(`${filePath}: ${diagnosticMessage(error)}`)
+    }
+  }
+  if (diagnostics.length > 0) {
+    throw new Error(`Invalid changed module syntax:\n${diagnostics.join('\n')}`)
+  }
+}
+
+function diagnosticMessage(error: unknown): string {
+  if (error && typeof error === 'object' && 'message' in error) {
+    return String((error as { message: unknown }).message)
+  }
+  return String(error)
+}

package/runtime/dev/watcher.ts

@@ -6,6 +6,7 @@ export type ChangeKind = 'ts' | 'css' | 'component-css' | 'html' | 'islands' | '
 const IGNORE_DIR_SEGMENTS = new Set(['node_modules', '.git', '.brust', 'dist'])
 const TS_RE = /\.(tsx?|jsx?)$/
 const TEST_RE = /\.test\.(tsx?|jsx?)$/
+const KIND_PRIORITY: ChangeKind[] = ['islands', 'ts', 'md', 'html', 'css', 'component-css']
 
 /** Classify a changed path. Returns null when the path should be ignored.
  * `root` is used to compute the relative path for ignore-segment matching.
@@ -83,26 +84,38 @@ export interface Watcher {
   close(): void
 }
 
-/** Watch `root` recursively. Emits one `onChange` call per debounce window
- * with paths classified by the dominant kind. Mixed-kind windows pick
- * by priority: islands > ts > html > css (islands trigger a full restart
- * that subsumes the others). */
+/** Internal — exposed for deterministic callback-contract tests. */
+export function _testDispatchChanges(
+  paths: string[],
+  opts: Pick<CreateWatcherOptions, 'root' | 'hasMdRoutes' | 'onChange'>,
+): void {
+  const grouped = new Map<ChangeKind, Set<string>>()
+  for (const p of paths) {
+    const kind = classifyPath(p, opts.root, opts.hasMdRoutes ?? true)
+    if (kind === null) continue
+    let group = grouped.get(kind)
+    if (!group) {
+      group = new Set()
+      grouped.set(kind, group)
+    }
+    group.add(p)
+  }
+  for (const kind of KIND_PRIORITY) {
+    const group = grouped.get(kind)
+    if (group && group.size > 0) {
+      opts.onChange({ paths: Array.from(group), kind })
+    }
+  }
+}
+
+/** Watch `root` recursively. Emits one `onChange` call for every distinct kind
+ * retained in a debounce window. Priority orders delivery; it never discards
+ * lower-priority kinds from a mixed window. */
 export function createWatcher(opts: CreateWatcherOptions): Watcher {
   const debounceMs = opts.debounceMs ?? 50
-  const kindPriority: ChangeKind[] = ['islands', 'ts', 'md', 'html', 'css', 'component-css']
 
   const coalesce = _testCoalesce(debounceMs, (paths) => {
-    const kinds = new Set<ChangeKind>()
-    const keep: string[] = []
-    for (const p of paths) {
-      const k = classifyPath(p, opts.root, opts.hasMdRoutes ?? true)
-      if (k === null) continue
-      kinds.add(k)
-      keep.push(p)
-    }
-    if (keep.length === 0) return
-    const dominant = kindPriority.find((k) => kinds.has(k))!
-    opts.onChange({ paths: keep, kind: dominant })
+    _testDispatchChanges(paths, opts)
   })
 
   const fsWatcher: FSWatcher = watch(opts.root, { recursive: true }, (_event, filename) => {

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

package/runtime/index.ts

@@ -869,6 +869,7 @@ export const brust = {
         ;(native as any).configureDevMode?.(true)
         const { createWatcher } = await import('./dev/watcher.ts')
         const { Coordinator } = await import('./dev/coordinator.ts')
+        const { validateChangedModules } = await import('./dev/validate-change.ts')
         const { broadcast } = await import('./dev/ws-channel.ts')
         const { Tui } = await import('./dev/tui.ts')
         const { terminateAll: termWorkers, spawnAll: spawnWorkers } = await import(
@@ -909,6 +910,7 @@ export const brust = {
             },
           },
           reEmitJinja,
+          validateChanges: validateChangedModules,
           // Wipe the Rust-side island ISR cache on every render-affecting reload
           // so a frozen island render never survives a `.tsx` edit in dev.
           clearIslandCache: () => {

package/runtime/render/stream.ts

@@ -66,6 +66,7 @@ export interface RenderBranchStreamingArgs {
 }
 
 const encoder = new TextEncoder()
+const decoder = new TextDecoder()
 
 /** JSON.stringify the per-chunk meta. Defaults match the renderToString
  * path so single-chunk responses keep their existing wire shape. */
@@ -122,6 +123,18 @@ function concatBuffers(parts: Uint8Array[], withBootstrap: boolean): Uint8Array
   return out
 }
 
+function injectOrPrependDevClient(body: Uint8Array, snippet: string | null): Uint8Array {
+  if (!snippet) return body
+  if (decoder.decode(body).toLowerCase().includes('</head>')) {
+    return injectDevClient(body, snippet)
+  }
+  const snippetBytes = encoder.encode(snippet)
+  const out = new Uint8Array(snippetBytes.length + body.length)
+  out.set(snippetBytes, 0)
+  out.set(body, snippetBytes.length)
+  return out
+}
+
 export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<void> {
   const { element, view, workerId, napi, errorBoundary } = args
   const slot = args.slot ?? 0
@@ -304,11 +317,12 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
         onShellError(err) {
           try {
             const html = renderToString(createElement(errorBoundary, { error: err as Error }))
+            const body = injectOrPrependDevClient(encoder.encode(html), getDevClientSnippet())
             const meta = makeMeta({ status: 500, streaming: false })
             mode = 'done'
             ;(async () => {
               try {
-                const len = encodeFirstChunk(view, meta, encoder.encode(html))
+                const len = encodeFirstChunk(view, meta, body)
                 await napi.renderChunkFinal(workerId, slot, len, view)
                 finalSent = true
                 resolve()
@@ -318,6 +332,23 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             })()
           } catch (e2) {
             console.error('[brust] errorBoundary threw during shell error:', e2)
+            const devSnippet = getDevClientSnippet()
+            if (devSnippet) {
+              const meta = makeMeta({ status: 500, streaming: false })
+              const html = `<!doctype html><html><head>${devSnippet}</head><body>Internal Server Error</body></html>`
+              mode = 'done'
+              ;(async () => {
+                try {
+                  const len = encodeFirstChunk(view, meta, encoder.encode(html))
+                  await napi.renderChunkFinal(workerId, slot, len, view)
+                  finalSent = true
+                  resolve()
+                } catch (e) {
+                  reject(e)
+                }
+              })()
+              return
+            }
             const meta = makeMeta({
               status: 500,
               streaming: false,

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

@@ -71,11 +71,8 @@ export declare function countMainTags(template: string): number;
  *
  * Exported for the md emit step (runtime/md/emit.ts), which bakes the same tag
  * under its `withDevClient` option — md pages render Rust-side too, so without
- * it they never auto-reload in dev.
- *
- * The AI runtime script is injected here as well when BRUST_AI=1. The tag is
- * document-only: the compiler emits a head anchor for full documents, while
- * fragment templates (no head) are left unchanged. */
+ * it they never auto-reload in dev. AI injection is deliberately separate —
+ * production AI must never pull in this reconnect/overlay client. */
 export declare function injectDevClientIntoTemplate(template: string): string;
 /** Bake the directive runtime loader into a native template iff it uses any
  * x-data directive. Idempotent. Wrapped in {% raw %} for symmetry with the islands

package/types/dev/coordinator.d.ts

@@ -7,6 +7,8 @@ export interface CoordinatorDeps {
     };
     buildCss: () => Promise<void>;
     buildIslands: () => Promise<void>;
+    /** Parse changed JS/TS modules before mutating the live generation. */
+    validateChanges: (paths: string[]) => Promise<void>;
     /** Recompile native-route `.jinja` templates from source and reload them into
      * the minijinja env, so `native: true` routes pick up .tsx edits on reload. */
     reEmitJinja: () => Promise<void>;
@@ -24,10 +26,15 @@ export interface CoordinatorDeps {
 }
 export declare class Coordinator {
     private deps;
-    private state;
+    private readonly pending;
+    private drainPromise;
     constructor(deps: CoordinatorDeps);
     handleChange(ev: {
         paths: string[];
         kind: ChangeKind;
     }): Promise<void>;
+    private startDrain;
+    private drainPending;
+    private takeNext;
+    private runBatch;
 }

package/types/dev/validate-change.d.ts

@@ -0,0 +1 @@
+export declare function validateChangedModules(paths: string[]): Promise<void>;

package/types/dev/watcher.d.ts

@@ -26,9 +26,10 @@ export interface CreateWatcherOptions {
 export interface Watcher {
     close(): void;
 }
-/** Watch `root` recursively. Emits one `onChange` call per debounce window
- * with paths classified by the dominant kind. Mixed-kind windows pick
- * by priority: islands > ts > html > css (islands trigger a full restart
- * that subsumes the others). */
+/** Internal — exposed for deterministic callback-contract tests. */
+export declare function _testDispatchChanges(paths: string[], opts: Pick<CreateWatcherOptions, 'root' | 'hasMdRoutes' | 'onChange'>): void;
+/** Watch `root` recursively. Emits one `onChange` call for every distinct kind
+ * retained in a debounce window. Priority orders delivery; it never discards
+ * lower-priority kinds from a mixed window. */
 export declare function createWatcher(opts: CreateWatcherOptions): Watcher;
 export {};