brustjs 0.1.64-alpha → 0.1.65-alpha

package/runtime/ai/refs.ts

@@ -0,0 +1,87 @@
+import { onBeforeNavigate } from '../navigation/store.ts'
+
+export type Ref = `e${number}`
+export type ActionTarget = Ref | string
+
+export interface BrustError {
+  code:
+    | 'stale-ref'
+    | 'not-found'
+    | 'ambiguous'
+    | 'timeout'
+    | 'disabled'
+    | 'nav-failed'
+    | 'bad-input'
+  message: string
+  hint?: string
+}
+
+export interface ErrorResult {
+  ok: false
+  error: BrustError
+}
+
+const elementRefs = new WeakMap<Element, Ref>()
+let refElements = new Map<Ref, WeakRef<Element>>()
+let nextRef = 1
+let generation = 0
+
+export function mintRef(element: Element): Ref {
+  const existing = elementRefs.get(element)
+  if (existing && refElements.get(existing)?.deref() === element) return existing
+  const ref = `e${nextRef++}` as Ref
+  elementRefs.set(element, ref)
+  refElements.set(ref, new WeakRef(element))
+  return ref
+}
+
+export function bumpRefGeneration(): void {
+  generation += 1
+  refElements = new Map()
+}
+
+export function refGeneration(): number {
+  return generation
+}
+
+function error(code: BrustError['code'], message: string, hint?: string): ErrorResult {
+  return { ok: false, error: { code, message, ...(hint ? { hint } : {}) } }
+}
+
+export function resolveTarget(
+  target: ActionTarget,
+  root: ParentNode = document,
+): Element | ErrorResult {
+  if (typeof target !== 'string' || target.length === 0) {
+    return error('bad-input', 'target must be a non-empty ref or CSS selector')
+  }
+  if (/^e\d+$/.test(target)) {
+    const element = refElements.get(target as Ref)?.deref()
+    if (!element?.isConnected) {
+      return error('stale-ref', `ref ${target} is no longer valid`, 're-run Brust.struct()')
+    }
+    return element
+  }
+  let matches: Element[]
+  try {
+    matches = Array.from(root.querySelectorAll(target))
+  } catch {
+    return error('bad-input', `invalid CSS selector: ${target}`)
+  }
+  if (matches.length === 0) return error('not-found', `no element matches selector: ${target}`)
+  if (matches.length > 1) {
+    return error('ambiguous', `selector matches ${matches.length} elements: ${target}`)
+  }
+  return matches[0]!
+}
+
+// Invalidate snapshot refs as soon as a navigation begins. A failed navigation
+// may leave the same DOM in place, but the public contract deliberately makes
+// every navigation attempt a generation boundary.
+onBeforeNavigate(() => bumpRefGeneration())
+
+export function __resetRefsForTest(): void {
+  bumpRefGeneration()
+  generation = 0
+  nextRef = 1
+}

package/runtime/ai/struct.ts

@@ -0,0 +1,168 @@
+import { getNavState, type NavPhase } from '../navigation/store.ts'
+import { mintRef, resolveTarget, type ErrorResult, type Ref } from './refs.ts'
+
+export interface Field {
+  ref: Ref
+  name: string
+  type: string
+  value: string | null
+  required: boolean
+  options?: Array<{ value: string; label: string }>
+}
+
+export interface PageStruct {
+  url: string
+  path: string
+  title: string
+  shellId: string
+  nav: { phase: NavPhase }
+  outline: Array<{ level: number; text: string }>
+  links: Array<{ ref: Ref; href: string; text: string; external: boolean; current: boolean }>
+  buttons: Array<{
+    ref: Ref
+    text: string
+    disabled: boolean
+    kind: 'button' | 'submit' | 'x-on-click'
+  }>
+  forms: Array<{
+    ref: Ref
+    name: string | null
+    action: string | null
+    method: string
+    fields: Field[]
+  }>
+  inputs: Field[]
+  islands: Array<{ ref: Ref; name: string; hydrated: boolean }>
+  behaviors: Array<{ ref: Ref; name: string }>
+}
+
+export interface StructOptions {
+  within?: Ref | string
+  maxText?: number
+}
+
+type FieldElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
+
+function isIgnored(element: Element): boolean {
+  return element.closest('[data-ai-ignore]') !== null
+}
+
+function all<T extends Element>(root: ParentNode, selector: string): T[] {
+  const found = Array.from(root.querySelectorAll<T>(selector))
+  if (root instanceof Element && root.matches(selector)) found.unshift(root as T)
+  return found.filter((element) => !isIgnored(element))
+}
+
+function label(element: Element, maxText: number): string {
+  const raw =
+    element.getAttribute('aria-label') ?? element.getAttribute('title') ?? element.textContent ?? ''
+  const text = raw.replace(/\s+/g, ' ').trim()
+  return text.length > maxText ? text.slice(0, maxText) : text
+}
+
+function field(element: FieldElement): Field {
+  const redacted =
+    (element instanceof HTMLInputElement && element.type === 'password') ||
+    element.hasAttribute('data-ai-redact')
+  const value = redacted
+    ? null
+    : element instanceof HTMLSelectElement && element.multiple
+      ? Array.from(element.selectedOptions)
+          .map((option) => option.value)
+          .join(',')
+      : element.value
+  const options =
+    element instanceof HTMLSelectElement
+      ? Array.from(element.options).map((option) => ({ value: option.value, label: option.text }))
+      : undefined
+  return {
+    ref: mintRef(element),
+    name: element.name || element.getAttribute('x-model') || '',
+    type:
+      element instanceof HTMLInputElement
+        ? element.type
+        : element instanceof HTMLSelectElement
+          ? 'select'
+          : 'textarea',
+    value,
+    required: element.required,
+    ...(options ? { options } : {}),
+  }
+}
+
+export async function struct(options: StructOptions = {}): Promise<PageStruct | ErrorResult> {
+  let root: ParentNode = document
+  if (options.within) {
+    const resolved = resolveTarget(options.within)
+    if (!(resolved instanceof Element)) return resolved
+    root = resolved
+  }
+  const maxText = Math.max(0, options.maxText ?? 200)
+  const origin = location.origin
+  const forms = all<HTMLFormElement>(root, 'form')
+  const links = all<HTMLAnchorElement>(root, 'a[href]').map((anchor) => {
+    const url = new URL(anchor.href, location.href)
+    return {
+      ref: mintRef(anchor),
+      href: anchor.href,
+      text: label(anchor, maxText),
+      external: url.origin !== origin,
+      current: anchor.getAttribute('aria-current') === 'page',
+    }
+  })
+  const buttonElements = all<HTMLElement>(
+    root,
+    'button, input[type="button"], input[type="submit"], [x-on-click]',
+  )
+  const buttons = [...new Set(buttonElements)].map((button) => ({
+    ref: mintRef(button),
+    text:
+      button instanceof HTMLInputElement
+        ? button.value || label(button, maxText)
+        : label(button, maxText),
+    disabled: 'disabled' in button && Boolean((button as HTMLButtonElement).disabled),
+    kind: ((button.matches('button') && (button as HTMLButtonElement).type === 'submit') ||
+    button.matches('input[type="submit"]')
+      ? 'submit'
+      : button.matches('button, input[type="button"]')
+        ? 'button'
+        : 'x-on-click') as 'button' | 'submit' | 'x-on-click',
+  }))
+  const standalone = all<FieldElement>(root, 'input, textarea, select').filter(
+    (element) => !element.form,
+  )
+  return {
+    url: location.href,
+    path: location.pathname,
+    title: document.title,
+    shellId: document.querySelector('meta[name="brust-shell"]')?.getAttribute('content') ?? '',
+    nav: { phase: getNavState().phase },
+    outline: all<HTMLHeadingElement>(root, 'h1, h2, h3').map((heading) => ({
+      level: Number(heading.tagName.slice(1)),
+      text: label(heading, maxText),
+    })),
+    links,
+    buttons,
+    forms: forms.map((formElement) => ({
+      ref: mintRef(formElement),
+      name:
+        formElement.getAttribute('data-ai-name') ||
+        formElement.getAttribute('name') ||
+        formElement.id ||
+        null,
+      action: formElement.getAttribute('action'),
+      method: (formElement.getAttribute('method') || 'get').toLowerCase(),
+      fields: all<FieldElement>(formElement, 'input, textarea, select').map(field),
+    })),
+    inputs: standalone.map(field),
+    islands: all<HTMLElement>(root, '[data-brust-island]').map((island) => ({
+      ref: mintRef(island),
+      name: island.getAttribute('data-brust-island') ?? '',
+      hydrated: island.hasAttribute('data-brust-hydrated'),
+    })),
+    behaviors: all<HTMLElement>(root, '[x-data]').map((behavior) => ({
+      ref: mintRef(behavior),
+      name: behavior.getAttribute('x-data') ?? '',
+    })),
+  }
+}

package/runtime/cli/build.ts

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module'
 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 { emitNativeTemplates } from './native-routes-emit.ts'
 import { nativeShimPlugin } from './native-shim-plugin.ts'
 
@@ -146,6 +147,7 @@ export interface ParsedArgs {
   ssg: boolean // --ssg — prerender static routes after the build
   ssgOut: string | null // --ssg-out value (absolute); null → <outDir>/static computed later
   generatorVersion: boolean // false ⇔ --no-generator-version (name-only generator tag)
+  ai: boolean // --ai — enable the AI runtime + document injection
 }
 
 /** Parse `brust build` argv. Pure (no fs access, no process.exit) so it's
@@ -157,6 +159,7 @@ export function parseArgs(args: string[]): ParsedArgs {
   let ssg = false
   let ssgOut: string | undefined
   let generatorVersion = true
+  let ai = false
 
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
@@ -181,6 +184,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       ssg = true
     } else if (a === '--no-generator-version') {
       generatorVersion = false
+    } else if (a === '--ai') {
+      ai = true
     } else if (a === '--ssg-out') {
       ssgOut = args[++i]
       if (!ssgOut) {
@@ -218,7 +223,23 @@ export function parseArgs(args: string[]): ParsedArgs {
   }
   const ssgOutPath = ssgOut ? (isAbsolute(ssgOut) ? ssgOut : resolve(cwd, ssgOut)) : null
 
-  return { entry: entryPath, outDir: outPath, target, ssg, ssgOut: ssgOutPath, generatorVersion }
+  return {
+    entry: entryPath,
+    outDir: outPath,
+    target,
+    ssg,
+    ssgOut: ssgOutPath,
+    generatorVersion,
+    ai,
+  }
+}
+
+export function buildBanner(aiEnabled: boolean): string {
+  return (
+    `process.env.BRUST_PREBUILT = '1';\n` +
+    `process.env.BRUST_DIST_DIR = import.meta.dir;\n` +
+    (aiEnabled ? `process.env.BRUST_AI ??= '1';\n` : '')
+  )
 }
 
 export async function runBuild(args: string[]): Promise<void> {
@@ -230,6 +251,8 @@ 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)) {
@@ -319,6 +342,22 @@ export async function runBuild(args: string[]): Promise<void> {
     loadedRoutes = routes
   }
 
+  // 2.85. AI manifest — extract the route metadata alongside the MCP manifest
+  // and persist it in both dist/ and cwd/.brust/ so dev/source and prebuilt
+  // runtime paths can read the same artifact.
+  {
+    const routes = (loadedRoutes ?? []) as Parameters<typeof extractAiManifest>[0]
+    const manifest = extractAiManifest(routes)
+    const manifestPath = path.join(outDir, '.brust', 'ai-manifest.json')
+    await writeAiManifest(outDir, manifest)
+    console.log(`[brust build] ai:      ${manifest.pages.length} page(s) → ${manifestPath}`)
+    const localManifestDir = path.join(process.cwd(), '.brust')
+    if (path.resolve(localManifestDir) !== path.resolve(outDir)) {
+      await mkdir(localManifestDir, { recursive: true })
+      await writeAiManifest(localManifestDir, manifest)
+    }
+  }
+
   // 2.9. md routes — emit `Md_*.jinja` into <outDir>/jinja BEFORE the island
   // build so islands used only from md content join the chunk scan, and write
   // the frozen `md-manifest.json` next to BOTH jinja dirs (dist root for the
@@ -350,6 +389,7 @@ export async function runBuild(args: string[]): Promise<void> {
       flatRoutes: loadedRoutes,
       outDir: jinjaDir,
       withDevClient: false,
+      aiEnabled,
       manifestDirs: [outDir, path.join(process.cwd(), '.brust')],
       // Build is fatal on a deleted md file — a silent skip would ship a dist
       // with the route registered but its template missing (dev paths default
@@ -376,7 +416,7 @@ export async function runBuild(args: string[]): Promise<void> {
     ((loadedRoutes ?? []) as { chain?: Array<{ ssg?: { fallback?: string } }> }[]).some(
       (r) => r.chain?.at(-1)?.ssg?.fallback === 'client',
     )
-  if (islandMap.size > 0 || needsFallbackRuntime) {
+  if (islandMap.size > 0 || needsFallbackRuntime || aiEnabled) {
     const islandsOutDir = path.join(outDir, 'islands')
     const result = await buildIslands(islandMap, {
       outDir: islandsOutDir,
@@ -532,8 +572,7 @@ export async function runBuild(args: string[]): Promise<void> {
   // actions codegen: `defineActions(...)` actions register via the app entry's
   // `import { actions } from './actions'` → `brust.run({ actions })` path, which
   // the bundled entry already carries.
-  const banner =
-    `process.env.BRUST_PREBUILT = '1';\n` + `process.env.BRUST_DIST_DIR = import.meta.dir;\n`
+  const banner = buildBanner(aiEnabled)
 
   const result = await Bun.build({
     entrypoints: [entry],

package/runtime/cli/dev.ts

@@ -11,12 +11,14 @@ interface ParsedArgs {
   entry: string
   port: number | undefined
   generatorVersion: boolean
+  ai: boolean
 }
 
 function parseArgs(args: string[]): ParsedArgs {
   let entry: string | undefined
   let port: number | undefined
   let generatorVersion = true
+  let ai = false
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
     if (a === '--port') {
@@ -32,6 +34,8 @@ function parseArgs(args: string[]): ParsedArgs {
       }
     } else if (a === '--no-generator-version') {
       generatorVersion = false
+    } else if (a === '--ai') {
+      ai = true
     } else if (a.startsWith('--port=')) {
       port = parseInt(a.slice('--port='.length), 10)
     } else if (a.startsWith('-')) {
@@ -54,12 +58,13 @@ function parseArgs(args: string[]): ParsedArgs {
     console.error(`brust dev: no entry file at ${entryPath}; pass a path or create ./index.ts`)
     process.exit(1)
   }
-  return { entry: entryPath, port, generatorVersion }
+  return { entry: entryPath, port, generatorVersion, ai }
 }
 
 export async function runDev(args: string[]): Promise<void> {
   const { entry, port, generatorVersion } = parseArgs(args)
   process.env.BRUST_DEV = '1'
+  process.env.BRUST_AI = '1'
   if (port !== undefined) process.env.BRUST_PORT = String(port)
 
   // Bake the generator decision BEFORE the first emit — emitters and the boot

package/runtime/cli/help.ts

@@ -65,6 +65,10 @@ export const COMMANDS: CommandDef[] = [
         flag: '--no-generator-version',
         desc: 'Drop the version from the generator meta tag + X-Powered-By header (the name stays)',
       },
+      {
+        flag: '--ai',
+        desc: 'Enable the AI runtime chunk + manifest wiring in production builds',
+      },
     ],
     notes: [
       'Markdown pages: routes mounted with mdRoutes(<contentDir>) compile to native',
@@ -83,6 +87,10 @@ export const COMMANDS: CommandDef[] = [
         flag: '--no-generator-version',
         desc: 'Drop the version from the generator meta tag + X-Powered-By header (the name stays)',
       },
+      {
+        flag: '--ai',
+        desc: 'Enable the AI runtime wiring explicitly (dev already enables it)',
+      },
     ],
   },
   {

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

@@ -3,7 +3,12 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync
 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 {
+  aiScriptTag,
+  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'
@@ -254,15 +259,32 @@ 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. */
+ * 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 function injectDevClientIntoTemplate(template: string): string {
-  const tag = buildDevClientTag()
-  if (template.includes(tag)) return template // idempotent across re-emits
-  const headClose = template.indexOf('</head>')
-  if (headClose !== -1) {
-    return template.slice(0, headClose) + tag + template.slice(headClose)
+  const devTag = buildDevClientTag()
+  let out = template
+  if (!out.includes(devTag)) {
+    const headClose = out.indexOf('</head>')
+    if (headClose !== -1) {
+      out = out.slice(0, headClose) + devTag + out.slice(headClose)
+    } else {
+      out += devTag
+    }
   }
-  return template + tag
+  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
 }
 
 /** Bake the directive runtime loader into a native template iff it uses any
@@ -981,7 +1003,9 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<Na
     // carry the identical signature. Empty/missing → no-op.
     const withShell = insertShellMeta(withGenerator, r.shellId ?? '')
     const template =
-      process.env.BRUST_DEV === '1' ? injectDevClientIntoTemplate(withShell) : withShell
+      process.env.BRUST_DEV === '1' || process.env.BRUST_AI === '1'
+        ? injectDevClientIntoTemplate(withShell)
+        : withShell
     writeFileSync(outPath, template)
     built.push(name)
     stats.compiled++

package/runtime/config.ts

@@ -14,6 +14,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
@@ -89,6 +91,7 @@ export async function loadConfig(
     host,
     port,
     workers,
+    ai: process.env.BRUST_AI === '1',
     cacheMaxEntries: fromToml.cacheMaxEntries,
     cachePageMaxEntries: fromToml.cachePageMaxEntries,
     cacheSyncUrl: fromEnv.cacheSyncUrl ?? fromToml.cacheSyncUrl,

package/runtime/generator.ts

@@ -15,6 +15,20 @@ export interface GeneratorStrings {
   header: string
 }
 
+/** Full browser entry tag for the AI runtime chunk. */
+export function aiScriptTag(): string {
+  return '<script type="module" src="/_brust/ai.js"></script>'
+}
+
+/** Insert the AI runtime tag immediately before the first `</head>`.
+ * Document-only: fragment templates with no head are left unchanged. */
+export function injectAiScriptIntoTemplate(template: string): string {
+  const at = template.indexOf('</head>')
+  if (at === -1) return template
+  const tag = aiScriptTag()
+  return template.slice(0, at) + tag + template.slice(at)
+}
+
 /** 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. */