brustjs 0.1.64-alpha → 0.1.66-alpha

package/runtime/md/emit.ts

@@ -12,7 +12,7 @@
 
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
-import { insertGeneratorMeta, resolveGenerator } from '../generator.ts'
+import { injectAiScriptIntoTemplate, insertGeneratorMeta, resolveGenerator } from '../generator.ts'
 import {
   bakeDirectivesIfUsed,
   buildChainWrapperSource,
@@ -66,6 +66,9 @@ export interface MdEmitOpts {
    * BRUST_DEV injection — md pages render Rust-side and never pass through the
    * React renderer's dev-client injection). */
   withDevClient?: boolean
+  /** Bake the AI runtime tag into document-style md templates. Fragments skip
+   * the injection entirely. */
+  aiEnabled?: boolean
   /** What to do when a route's md file no longer exists on disk (deleted after
    * the route table was built). emitMdTemplates serves BOTH `brust build` and
    * the dev re-emit, and the two must diverge here:
@@ -400,6 +403,7 @@ export async function emitMdTemplates(opts: MdEmitOpts): Promise<{
     }
     final = bakeDirectivesIfUsed(final, hasDirectives)
     if (opts.withDevClient) final = injectDevClientIntoTemplate(final)
+    if (!opts.withDevClient && opts.aiEnabled) final = injectAiScriptIntoTemplate(final)
     writeFileSync(outPath, final)
   }
 

package/runtime/render/inject-ai-client.ts

@@ -0,0 +1,38 @@
+const ENC = new TextEncoder()
+
+/** Splice `snippet` into `body` immediately before the first `</head>`
+ * (case-insensitive on the four ASCII letters only). Returns the original body
+ * untouched if `snippet` is null/empty or if `</head>` is absent.
+ *
+ * AI pages are document-only: fragment templates skip this injection entirely. */
+export function injectAiClient(body: Uint8Array, snippet: string | null): Uint8Array {
+  if (!snippet) return body
+  const pos = findHeadCloseTag(body)
+  if (pos < 0) return body
+  const tagBytes = ENC.encode(snippet)
+  const out = new Uint8Array(body.length + tagBytes.length)
+  out.set(body.subarray(0, pos), 0)
+  out.set(tagBytes, pos)
+  out.set(body.subarray(pos), pos + tagBytes.length)
+  return out
+}
+
+function findHeadCloseTag(body: Uint8Array): number {
+  const LT = 0x3c,
+    SL = 0x2f,
+    GT = 0x3e
+  for (let i = 0, max = body.length - 6; i < max; i++) {
+    if (body[i] !== LT || body[i + 1] !== SL) continue
+    if (!isLetter(body[i + 2], 0x48)) continue
+    if (!isLetter(body[i + 3], 0x45)) continue
+    if (!isLetter(body[i + 4], 0x41)) continue
+    if (!isLetter(body[i + 5], 0x44)) continue
+    if (body[i + 6] !== GT) continue
+    return i
+  }
+  return -1
+}
+
+function isLetter(b: number, u: number): boolean {
+  return b === u || b === (u | 0x20)
+}

package/runtime/render/stream.ts

@@ -7,6 +7,7 @@ import { Writable } from 'node:stream'
 import { IslandUsedContext, createIslandUsedBox } from '../islands/island.tsx'
 import { ISLANDS_IMPORTMAP_AND_BOOTSTRAP } from '../islands/importmap.ts'
 import { injectCssLink } from './inject-css-link.ts'
+import { injectAiClient } from './inject-ai-client.ts'
 import { getCssHrefs, getCssHrefsForRoute } from '../css.ts'
 import { injectDevClient } from './inject-dev-client.ts'
 import { injectActionPrefix, getActionPrefixSnippet } from './inject-action-prefix.ts'
@@ -14,6 +15,7 @@ import { injectBrustStore, buildStoreScripts } from './inject-store.ts'
 import { getDevClientSnippet } from '../dev/inject.ts'
 import { getGeneratorMeta, injectGeneratorMeta } from './inject-generator.ts'
 import { injectShellMeta, shellMetaTag } from './inject-shell-meta.ts'
+import { aiScriptTag } from '../generator.ts'
 
 export interface RenderBranchStreamingArgs {
   element: ReactNode
@@ -64,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. */
@@ -120,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
@@ -184,6 +199,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             body = injectGeneratorMeta(body, getGeneratorMeta())
             body = injectShellMeta(body, args.shellId ?? '')
             body = injectDevClient(body, getDevClientSnippet())
+            body = injectAiClient(body, process.env.BRUST_AI === '1' ? aiScriptTag() : null)
             body = injectActionPrefix(body, getActionPrefixSnippet())
             body = injectBrustStore(body, args.storeSnapshot ?? null)
             const meta = makeMeta({
@@ -246,6 +262,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
               .map((h) => `<link rel="stylesheet" href="${h}">`)
               .join('')
             const devTag = getDevClientSnippet() ?? ''
+            const aiTag = process.env.BRUST_AI === '1' ? aiScriptTag() : ''
             const prefixTag = getActionPrefixSnippet() ?? ''
             const storeTag = buildStoreScripts(args.storeSnapshot ?? null)
             const genTag = getGeneratorMeta() ?? ''
@@ -253,6 +270,7 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
             if (
               linkTagsStr.length > 0 ||
               devTag.length > 0 ||
+              aiTag.length > 0 ||
               prefixTag.length > 0 ||
               storeTag.length > 0 ||
               genTag.length > 0 ||
@@ -261,9 +279,10 @@ export function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<
               const prepend = encoder.encode(
                 genTag + shellTag + linkTagsStr + prefixTag + devTag + storeTag,
               )
-              const out = new Uint8Array(flushed.length + prepend.length)
-              out.set(flushed, 0)
-              out.set(prepend, flushed.length)
+              const out = new Uint8Array(prepend.length + aiTag.length + flushed.length)
+              out.set(prepend, 0)
+              out.set(encoder.encode(aiTag), prepend.length)
+              out.set(flushed, prepend.length + aiTag.length)
               flushed = out
             }
             const meta = makeMeta({ status: successStatus, streaming: true, headers: extraHeaders })
@@ -298,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()
@@ -312,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/ai/manifest.d.ts

@@ -0,0 +1,17 @@
+import type { FlatRoute } from '../routes.ts';
+export interface AiPageEntry {
+    path: string;
+    params: string[];
+    catchAll: boolean;
+    kind: 'react' | 'native' | 'md';
+    shellId: string;
+    title?: string;
+    description?: string;
+}
+export interface AiManifest {
+    version: 1;
+    pages: AiPageEntry[];
+}
+export declare function extractAiManifest(routes: FlatRoute[]): AiManifest;
+export declare function writeManifest(cwd: string, manifest: AiManifest): Promise<void>;
+export declare function readManifest(cwd: string): Promise<AiManifest | null>;

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

@@ -71,7 +71,11 @@ 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. */
+ * 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. */
 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/config.d.ts

@@ -10,6 +10,8 @@ export interface BrustConfig {
     cacheMaxEntries?: number;
     /** L2 page-cache capacity (entries). Undefined → Rust default of 1000. */
     cachePageMaxEntries?: number;
+    /** AI runtime toggle from BRUST_AI. Dev mode enables it separately. */
+    ai?: boolean;
     /** R9 cross-process cache invalidation: redis/dragonfly URL. Absent →
      * feature disabled (current single-process behavior). */
     cacheSyncUrl?: string;

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 {};

package/types/generator.d.ts

@@ -4,6 +4,11 @@ export interface GeneratorStrings {
     /** X-Powered-By value, e.g. `brust/0.1.48-alpha` */
     header: string;
 }
+/** Full browser entry tag for the AI runtime chunk. */
+export declare function aiScriptTag(): string;
+/** Insert the AI runtime tag immediately before the first `</head>`.
+ * Document-only: fragment templates with no head are left unchanged. */
+export declare function injectAiScriptIntoTemplate(template: string): string;
 /** Build the resolved strings. Version comes from the brustjs package.json
  * (readVersion never throws — "unknown" degrades to name-only, never a crash).
  * The version is sanitized to attr/header-safe bytes; semver chars only. */

package/types/index.d.ts

@@ -183,6 +183,8 @@ export declare const brust: {
         /** Optional global CORS policy — see {@link CorsOptions}. Threaded to
          * serve() like `actionPrefix`. */
         cors?: CorsOptions;
+        /** AI runtime toggle. Dev mode enables it automatically. */
+        ai?: boolean;
         /** Overrides merged into the underlying `serve()` call (main thread). */
         serve?: Partial<Omit<ServeOptions, "entry" | "actions" | "mcp">>;
         /** Per-worker SAB size in bytes. Default 256 KB. */

package/types/islands/build.d.ts

@@ -18,6 +18,14 @@ export interface BuildIslandsOptions {
      * on the output filename (X.module.css + X.tsx → both X.js). */
     plugins?: BunPlugin[];
 }
+export interface BuildAiRuntimeOptions {
+    /** Override the output directory. Default: `<cwd>/.brust/islands`. */
+    outDir?: string;
+    /** Override the browser entry file. Default: `runtime/ai/index.ts`. */
+    entryFile?: string;
+    /** Build plugins passed straight to `Bun.build` for the AI runtime chunk. */
+    plugins?: BunPlugin[];
+}
 /** Scan a routes entry file for `<Island component={X} />` usage and derive the
  * island chunk list (componentName → absolute source path). Replaces the old
  * static config-file lookup — the chunk set is derived from source.
@@ -46,4 +54,5 @@ export declare function scanIslandChunks(routesEntryFile: string, extraIslands?:
 /** Build the runtime chunks + all island chunks + bootstrap. Returns the
  * absolute output directory; caller passes it to `brust.configureIslandsDir`. */
 export declare function buildIslands(islands: Map<string, string>, options?: BuildIslandsOptions): Promise<IslandsBuildResult>;
+export declare function buildAiRuntime(options?: BuildAiRuntimeOptions): Promise<string | null>;
 export declare function buildOne(entrypoints: string[], outdir: string, naming: string, external: string[], plugins?: BunPlugin[]): Promise<void>;

package/types/md/emit.d.ts

@@ -27,6 +27,9 @@ export interface MdEmitOpts {
      * BRUST_DEV injection — md pages render Rust-side and never pass through the
      * React renderer's dev-client injection). */
     withDevClient?: boolean;
+    /** Bake the AI runtime tag into document-style md templates. Fragments skip
+     * the injection entirely. */
+    aiEnabled?: boolean;
     /** What to do when a route's md file no longer exists on disk (deleted after
      * the route table was built). emitMdTemplates serves BOTH `brust build` and
      * the dev re-emit, and the two must diverge here:

package/types/render/inject-ai-client.d.ts

@@ -0,0 +1,6 @@
+/** Splice `snippet` into `body` immediately before the first `</head>`
+ * (case-insensitive on the four ASCII letters only). Returns the original body
+ * untouched if `snippet` is null/empty or if `</head>` is absent.
+ *
+ * AI pages are document-only: fragment templates skip this injection entirely. */
+export declare function injectAiClient(body: Uint8Array, snippet: string | null): Uint8Array;