brustjs 0.1.63-alpha → 0.1.65-alpha

package/README.md

@@ -114,6 +114,11 @@ Click either one — both update. [See it live](https://brust.assetsart.com/) ·
   **resources** at `/_brust/mcp`; `tools/call` runs through the same validation
   and middleware as HTTP, so agents drive the app without scraping.
   → [Agents](https://brust.assetsart.com/docs/agents)
+- **Browser-native AI runtime** — `window.Brust` lets an agent inspect routes
+  and the rendered page, act through real DOM events, and navigate with
+  framework-aware settling. It is automatic in dev and opt-in for production,
+  with no client cost while disabled.
+  → [Agents](https://brust.assetsart.com/docs/agents#driving-the-ui--windowbrust)
 - Plus: nested routes + dynamic params, typed loaders, request-scoped
   middleware, SPA-style navigation, SSE & WebSockets as first-class route
   shapes, response + ISR caches, Tailwind v4 + CSS Modules, static
@@ -155,6 +160,7 @@ brustjs build <entry> --out-dir D # prebuilt ./dist/ — run from the project (b
                   --target <auto|all|TARGET[,…]> # which native binary to bundle (default: auto = host platform)
                   --ssg [--ssg-out D]   # prerender static routes (incl. markdown pages) to HTML
                                         # + per-route SPA payloads — client-side nav works statically
+                  --ai                  # include window.Brust + its route manifest in production
 brustjs new   <name>              # scaffold a project (partial — see Status)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brustjs",
-  "version": "0.1.63-alpha",
+  "version": "0.1.65-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.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"
+    "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"
   },
   "peerDependencies": {
     "react": "^19.2.6",

package/runtime/ai/actions.ts

@@ -0,0 +1,271 @@
+import { settleAfterAction } from './navigate.ts'
+import { resolveTarget, type ActionTarget, type ErrorResult } from './refs.ts'
+
+export interface CapturedError {
+  message: string
+  stack?: string
+}
+
+export interface ActionResult {
+  ok: true
+  navigated: boolean
+  url: string
+  errors: CapturedError[]
+}
+
+type ActionResponse = ActionResult | ErrorResult
+type Fillable = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | HTMLElement
+
+const activeCaptures = new Set<CapturedError[]>()
+let consoleWrapped = false
+let listenerWindow: Window | null = null
+
+function captured(value: unknown): CapturedError {
+  if (value instanceof Error)
+    return { message: value.message, ...(value.stack ? { stack: value.stack } : {}) }
+  return { message: typeof value === 'string' ? value : String(value) }
+}
+
+function record(value: unknown): void {
+  const entry = captured(value)
+  for (const errors of activeCaptures) errors.push(entry)
+}
+
+function beginCapture(): CapturedError[] {
+  if (!consoleWrapped) {
+    consoleWrapped = true
+    const original = console.error.bind(console)
+    console.error = (...args: unknown[]) => {
+      record(args.length === 1 ? args[0] : args.map((arg) => captured(arg).message).join(' '))
+      original(...args)
+    }
+  }
+  if (listenerWindow !== window) {
+    listenerWindow = window
+    window.addEventListener('error', (event) => record(event.error ?? event.message))
+    window.addEventListener('unhandledrejection', (event) => record(event.reason))
+  }
+  const errors: CapturedError[] = []
+  activeCaptures.add(errors)
+  return errors
+}
+
+function badInput(message: string, hint?: string): ErrorResult {
+  return { ok: false, error: { code: 'bad-input', message, ...(hint ? { hint } : {}) } }
+}
+
+function prepare(target: ActionTarget): Element | ErrorResult {
+  const element = resolveTarget(target)
+  if ('ok' in element) return element
+  element.scrollIntoView?.({ block: 'center', inline: 'center' })
+  return element
+}
+
+async function result(beforeUrl: string, errors: CapturedError[]): Promise<ActionResponse> {
+  const settleError = await settleAfterAction()
+  activeCaptures.delete(errors)
+  if (settleError) return settleError
+  return { ok: true, navigated: location.href !== beforeUrl, url: location.href, errors }
+}
+
+function event(name: string, EventType: typeof Event = Event): Event {
+  return new EventType(name, { bubbles: true, cancelable: true })
+}
+
+export async function click(target: ActionTarget): Promise<ActionResponse> {
+  const element = prepare(target)
+  if ('ok' in element) return element
+  const before = location.href
+  const errors = beginCapture()
+  const Pointer = globalThis.PointerEvent ?? MouseEvent
+  element.dispatchEvent(event('pointerdown', Pointer))
+  element.dispatchEvent(event('pointerup', Pointer))
+  element.dispatchEvent(event('click', MouseEvent))
+  return result(before, errors)
+}
+
+export async function focus(target: ActionTarget): Promise<ActionResponse> {
+  const element = prepare(target)
+  if ('ok' in element) return element
+  const before = location.href
+  if (!(element instanceof HTMLElement)) return badInput('focus target is not an HTMLElement')
+  const errors = beginCapture()
+  element.focus()
+  return result(before, errors)
+}
+
+export async function blur(target: ActionTarget): Promise<ActionResponse> {
+  const element = prepare(target)
+  if ('ok' in element) return element
+  const before = location.href
+  if (!(element instanceof HTMLElement)) return badInput('blur target is not an HTMLElement')
+  const errors = beginCapture()
+  element.blur()
+  return result(before, errors)
+}
+
+function setNativeValue(element: Fillable, value: string): ErrorResult | null {
+  if (element.isContentEditable) {
+    element.textContent = value
+    return null
+  }
+  const prototype =
+    element instanceof HTMLInputElement
+      ? HTMLInputElement.prototype
+      : element instanceof HTMLTextAreaElement
+        ? HTMLTextAreaElement.prototype
+        : element instanceof HTMLSelectElement
+          ? HTMLSelectElement.prototype
+          : null
+  const setter = prototype && Object.getOwnPropertyDescriptor(prototype, 'value')?.set
+  if (!setter) return badInput('fill target is not an input, textarea, select, or contenteditable')
+  setter.call(element, value)
+  return null
+}
+
+async function fillElement(element: Element, value: string): Promise<ErrorResult | null> {
+  if (!(element instanceof HTMLElement)) return badInput('fill target is not an HTMLElement')
+  const error = setNativeValue(element, value)
+  if (error) return error
+  element.dispatchEvent(event('input', InputEvent))
+  element.dispatchEvent(event('change'))
+  return null
+}
+
+export async function fill(target: ActionTarget, value: unknown): Promise<ActionResponse> {
+  const element = prepare(target)
+  if ('ok' in element) return element
+  if (typeof value !== 'string' && typeof value !== 'number') {
+    return badInput('fill value must be a string or number')
+  }
+  const before = location.href
+  const errors = beginCapture()
+  const error = await fillElement(element, String(value))
+  if (error) {
+    activeCaptures.delete(errors)
+    return error
+  }
+  return result(before, errors)
+}
+
+function findForm(nameOrRef: string): HTMLFormElement | ErrorResult {
+  if (/^e\d+$/.test(nameOrRef)) {
+    const resolved = resolveTarget(nameOrRef)
+    if ('ok' in resolved) return resolved
+    return resolved instanceof HTMLFormElement ? resolved : badInput(`${nameOrRef} is not a form`)
+  }
+  const matches = Array.from(document.forms).filter(
+    (candidate) =>
+      candidate.getAttribute('data-ai-name') === nameOrRef ||
+      candidate.name === nameOrRef ||
+      candidate.id === nameOrRef,
+  )
+  if (matches.length === 0) {
+    const resolved = resolveTarget(nameOrRef)
+    if ('ok' in resolved) return resolved
+    return resolved instanceof HTMLFormElement
+      ? resolved
+      : badInput(`${nameOrRef} does not resolve to a form`)
+  }
+  if (matches.length > 1) {
+    return {
+      ok: false,
+      error: { code: 'ambiguous', message: `multiple forms named: ${nameOrRef}` },
+    }
+  }
+  return matches[0]!
+}
+
+export async function form(
+  nameOrRef: string,
+  values: Record<string, unknown>,
+  options: { submit?: boolean } = {},
+): Promise<ActionResponse> {
+  const formElement = findForm(nameOrRef)
+  if ('ok' in formElement) return formElement
+  if (!values || typeof values !== 'object' || Array.isArray(values)) {
+    return badInput('form values must be an object')
+  }
+  const fields = Array.from(formElement.elements).filter(
+    (element): element is HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement =>
+      element instanceof HTMLInputElement ||
+      element instanceof HTMLTextAreaElement ||
+      element instanceof HTMLSelectElement,
+  )
+  const errors = beginCapture()
+  const available = [...new Set(fields.map((field) => field.name).filter(Boolean))]
+  for (const [name, value] of Object.entries(values)) {
+    const matching = fields.filter((field) => field.name === name)
+    if (matching.length === 0) {
+      activeCaptures.delete(errors)
+      return badInput(`unknown form field: ${name}`, `available fields: ${available.join(', ')}`)
+    }
+    const field = matching[0]!
+    if (
+      field instanceof HTMLInputElement &&
+      (field.type === 'checkbox' || field.type === 'radio')
+    ) {
+      const checked = typeof value === 'boolean' ? value : String(value) === field.value
+      const descriptor = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'checked')
+      descriptor?.set?.call(field, checked)
+      field.dispatchEvent(event('input', InputEvent))
+      field.dispatchEvent(event('change'))
+    } else {
+      const error = await fillElement(field, String(value ?? ''))
+      if (error) {
+        activeCaptures.delete(errors)
+        return error
+      }
+    }
+  }
+  const before = location.href
+  if (options.submit !== false) formElement.requestSubmit()
+  return result(before, errors)
+}
+
+export async function press(target: ActionTarget, key: string): Promise<ActionResponse> {
+  const element = prepare(target)
+  if ('ok' in element) return element
+  if (!key) return badInput('key must be a non-empty string')
+  const before = location.href
+  const errors = beginCapture()
+  for (const type of ['keydown', 'keypress', 'keyup']) {
+    element.dispatchEvent(new KeyboardEvent(type, { key, bubbles: true, cancelable: true }))
+  }
+  return result(before, errors)
+}
+
+export async function select(target: ActionTarget, valueOrLabel: string): Promise<ActionResponse> {
+  const element = prepare(target)
+  if ('ok' in element) return element
+  if (!(element instanceof HTMLSelectElement)) return badInput('select target is not a select')
+  const option = Array.from(element.options).find(
+    (candidate) => candidate.value === valueOrLabel || candidate.text === valueOrLabel,
+  )
+  if (!option) return badInput(`select option not found: ${valueOrLabel}`)
+  const before = location.href
+  const errors = beginCapture()
+  const error = setNativeValue(element, option.value)
+  if (error) {
+    activeCaptures.delete(errors)
+    return error
+  }
+  element.dispatchEvent(event('input', InputEvent))
+  element.dispatchEvent(event('change'))
+  return result(before, errors)
+}
+
+export async function check(target: ActionTarget, checked: boolean): Promise<ActionResponse> {
+  const element = prepare(target)
+  if ('ok' in element) return element
+  if (!(element instanceof HTMLInputElement) || !['checkbox', 'radio'].includes(element.type)) {
+    return badInput('check target is not a checkbox or radio input')
+  }
+  const before = location.href
+  const errors = beginCapture()
+  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'checked')?.set
+  setter?.call(element, checked)
+  element.dispatchEvent(event('input', InputEvent))
+  element.dispatchEvent(event('change'))
+  return result(before, errors)
+}

package/runtime/ai/index.ts

@@ -0,0 +1,90 @@
+/** Browser-only AI agent runtime. This standalone entry deliberately imports
+ * neither runtime/index.ts nor runtime/routes.ts: both pull server/React code
+ * into a browser bundle. Keep this module family React-free.
+ */
+import packageJson from '../../package.json' with { type: 'json' }
+import * as actions from './actions.ts'
+import { back, navigate, reload } from './navigate.ts'
+import { pages } from './pages.ts'
+import { struct } from './struct.ts'
+import type { BrustError, ErrorResult } from './refs.ts'
+
+type PublicMethod = (...args: never[]) => unknown
+
+function envelope<T extends PublicMethod>(method: T): (...args: Parameters<T>) => Promise<unknown> {
+  return async (...args: Parameters<T>) => {
+    try {
+      return await method(...args)
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause)
+      return {
+        ok: false,
+        error: { code: 'bad-input', message },
+      } satisfies ErrorResult
+    }
+  }
+}
+
+function disabled(): Promise<ErrorResult> {
+  return Promise.resolve({ ok: false, error: { code: 'disabled', message: 'P2' } })
+}
+
+export interface BrustRuntime {
+  version: { api: 1; brust: string }
+  pages: ReturnType<typeof envelope<typeof pages>>
+  struct: ReturnType<typeof envelope<typeof struct>>
+  action: {
+    click: ReturnType<typeof envelope<typeof actions.click>>
+    focus: ReturnType<typeof envelope<typeof actions.focus>>
+    blur: ReturnType<typeof envelope<typeof actions.blur>>
+    fill: ReturnType<typeof envelope<typeof actions.fill>>
+    form: ReturnType<typeof envelope<typeof actions.form>>
+    press: ReturnType<typeof envelope<typeof actions.press>>
+    select: ReturnType<typeof envelope<typeof actions.select>>
+    check: ReturnType<typeof envelope<typeof actions.check>>
+  }
+  navigate: ReturnType<typeof envelope<typeof navigate>>
+  back: ReturnType<typeof envelope<typeof back>>
+  reload: ReturnType<typeof envelope<typeof reload>>
+  wait: typeof disabled
+  state: typeof disabled
+  nav: typeof disabled
+  api: { list: typeof disabled; call: typeof disabled }
+  errors: typeof disabled
+}
+
+export function createBrustRuntime(): BrustRuntime {
+  return {
+    version: { api: 1, brust: packageJson.version },
+    pages: envelope(pages),
+    struct: envelope(struct),
+    action: {
+      click: envelope(actions.click),
+      focus: envelope(actions.focus),
+      blur: envelope(actions.blur),
+      fill: envelope(actions.fill),
+      form: envelope(actions.form),
+      press: envelope(actions.press),
+      select: envelope(actions.select),
+      check: envelope(actions.check),
+    },
+    navigate: envelope(navigate),
+    back: envelope(back),
+    reload: envelope(reload),
+    wait: disabled,
+    state: disabled,
+    nav: disabled,
+    api: { list: disabled, call: disabled },
+    errors: disabled,
+  }
+}
+
+declare global {
+  interface Window {
+    Brust: BrustRuntime
+  }
+}
+
+if (typeof window !== 'undefined') window.Brust = createBrustRuntime()
+
+export type { BrustError }

package/runtime/ai/manifest.ts

@@ -0,0 +1,68 @@
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+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[]
+}
+
+type FlatRouteLeaf = FlatRoute['chain'][number] & { __mdSource?: unknown }
+
+const MANIFEST_PATH = '.brust/ai-manifest.json'
+
+export function extractAiManifest(routes: FlatRoute[]): AiManifest {
+  const pages = routes
+    .map((r): AiPageEntry => {
+      const leaf = r.chain[r.chain.length - 1] as FlatRouteLeaf | undefined
+      const path = r.fullPath
+      const params = Array.from(path.matchAll(/\{(\*?)([^}]+)\}/g), (m) => m[2])
+      const kind: AiPageEntry['kind'] = leaf?.__mdSource
+        ? 'md'
+        : r.nativeTemplate
+          ? 'native'
+          : 'react'
+      return {
+        path,
+        params,
+        catchAll: r.notFound === true,
+        kind,
+        shellId: r.shellId,
+      }
+    })
+    .sort((a, b) => a.path.localeCompare(b.path))
+  return { version: 1, pages }
+}
+
+export async function writeManifest(cwd: string, manifest: AiManifest): Promise<void> {
+  const path = join(cwd, MANIFEST_PATH)
+  await mkdir(join(cwd, '.brust'), { recursive: true })
+  await Bun.write(path, JSON.stringify(manifest, null, 2))
+}
+
+export async function readManifest(cwd: string): Promise<AiManifest | null> {
+  const path = join(cwd, MANIFEST_PATH)
+  const file = Bun.file(path)
+  if (!(await file.exists())) return null
+  const text = await file.text()
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (e) {
+    throw new Error(`ai-manifest.json is malformed: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (!parsed || typeof parsed !== 'object' || (parsed as { version?: unknown }).version !== 1) {
+    throw new Error(`ai-manifest.json version mismatch (expected 1)`)
+  }
+  return parsed as AiManifest
+}

package/runtime/ai/navigate.ts

@@ -0,0 +1,157 @@
+import { navigate as brustNavigate } from '../navigation/navigate.ts'
+import { _getNavigator, getNavState, subscribe } from '../navigation/store.ts'
+import { struct, type PageStruct } from './struct.ts'
+import type { ErrorResult } from './refs.ts'
+
+export interface NavigateOptions {
+  struct?: boolean
+  timeout?: number
+}
+
+export interface NavResult {
+  ok: true
+  url: string
+  status: 'spa' | 'full-load' | 'external'
+  struct?: PageStruct
+}
+
+function failure(code: 'timeout' | 'nav-failed', message: string, hint?: string): ErrorResult {
+  return { ok: false, error: { code, message, ...(hint ? { hint } : {}) } }
+}
+
+function allIslandsRegistered(): boolean {
+  return document.querySelector('[data-brust-island]:not([data-brust-hydrated])') === null
+}
+
+// One paint tick. requestAnimationFrame alone is NOT a safe await: hidden and
+// backgrounded tabs (exactly where agent-driven browsers run) pause rAF
+// indefinitely, so every settle would hang. Race it against a short timer —
+// whichever fires first is "the page had a chance to react".
+function nextTick(): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, 50)
+    requestAnimationFrame(() => {
+      clearTimeout(timer)
+      resolve()
+    })
+  })
+}
+
+async function waitForHydration(timeout: number): Promise<ErrorResult | null> {
+  const started = performance.now()
+  while (!allIslandsRegistered()) {
+    if (performance.now() - started >= timeout) {
+      return failure('timeout', `navigation did not hydrate within ${timeout}ms`)
+    }
+    await nextTick()
+  }
+  return null
+}
+
+async function waitForTerminal(timeout: number): Promise<ErrorResult | null> {
+  const current = getNavState()
+  if (current.phase === 'error') {
+    return failure('nav-failed', current.error?.message ?? 'navigation failed')
+  }
+  if (current.phase === 'success' || current.phase === 'idle') return null
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      off()
+      resolve(failure('timeout', `navigation did not settle within ${timeout}ms`))
+    }, timeout)
+    const off = subscribe((state) => {
+      if (state.phase === 'loading') return
+      clearTimeout(timer)
+      off()
+      resolve(
+        state.phase === 'error'
+          ? failure('nav-failed', state.error?.message ?? 'navigation failed')
+          : null,
+      )
+    })
+  })
+}
+
+async function finish(
+  status: NavResult['status'],
+  options: NavigateOptions,
+  url = location.href,
+): Promise<NavResult | ErrorResult> {
+  const timeout = options.timeout ?? 10_000
+  if (status === 'spa') {
+    const terminalError = await waitForTerminal(timeout)
+    if (terminalError) return terminalError
+    const hydrationError = await waitForHydration(timeout)
+    if (hydrationError) return hydrationError
+  }
+  const result: NavResult = { ok: true, url, status }
+  if (options.struct && status === 'spa') {
+    const snapshot = await struct()
+    if ('ok' in snapshot && snapshot.ok === false) return snapshot
+    result.struct = snapshot
+  }
+  return result
+}
+
+export async function navigate(
+  path: string,
+  options: NavigateOptions = {},
+): Promise<NavResult | ErrorResult> {
+  const destination = new URL(path, location.href)
+  if (destination.origin !== location.origin) {
+    const response = await finish('external', options, destination.href)
+    setTimeout(() => location.assign(destination.href), 0)
+    return response
+  }
+  const hasSpaNavigator = _getNavigator() !== null
+  if (!hasSpaNavigator) {
+    const response = await finish('full-load', options, destination.href)
+    setTimeout(() => location.assign(destination.href), 0)
+    return response
+  }
+  await brustNavigate(destination.href)
+  // Bootstrap leaves the store in loading when it selected a full-document
+  // load; a committed SPA swap updates its path and terminal phase to success.
+  const state = getNavState()
+  const fullLoad = state.phase === 'loading' && state.path !== destination.pathname
+  return finish(fullLoad ? 'full-load' : 'spa', options)
+}
+
+async function browserHistoryAction(
+  run: () => void,
+  options: NavigateOptions = {},
+): Promise<NavResult | ErrorResult> {
+  const before = location.href
+  run()
+  await Promise.resolve()
+  await nextTick()
+  if (location.href === before && getNavState().phase !== 'loading') {
+    return finish('spa', options)
+  }
+  const state = getNavState()
+  const canonicalPath = location.pathname.length > 1 ? location.pathname.replace(/\/+$/, '') : '/'
+  const status = state.path === canonicalPath ? 'spa' : 'full-load'
+  return finish(status, options)
+}
+
+export function back(options?: NavigateOptions): Promise<NavResult | ErrorResult> {
+  return browserHistoryAction(() => history.back(), options)
+}
+
+export function reload(options?: NavigateOptions): Promise<NavResult | ErrorResult> {
+  return finish('full-load', options ?? {}).then((response) => {
+    setTimeout(() => location.reload(), 0)
+    return response
+  })
+}
+
+export async function settleAfterAction(timeout = 10_000): Promise<ErrorResult | null> {
+  await Promise.resolve()
+  await nextTick()
+  if (getNavState().phase === 'loading') {
+    const navError = await waitForTerminal(timeout)
+    if (navError) return navError
+    return waitForHydration(timeout)
+  }
+  return null
+}

package/runtime/ai/pages.ts

@@ -0,0 +1,49 @@
+import type { ErrorResult } from './refs.ts'
+
+export interface PageEntry {
+  path: string
+  params: string[]
+  catchAll: boolean
+  kind: 'react' | 'native' | 'md'
+  shellId: string
+  title?: string
+  description?: string
+}
+
+interface AiManifest {
+  version: 1
+  pages: PageEntry[]
+}
+
+let pagesPromise: Promise<PageEntry[] | ErrorResult> | null = null
+
+function notFound(message: string): ErrorResult {
+  return {
+    ok: false,
+    error: {
+      code: 'not-found',
+      message,
+      hint: 'ai manifest not served — is the ai flag enabled?',
+    },
+  }
+}
+
+export function pages(): Promise<PageEntry[] | ErrorResult> {
+  if (!pagesPromise) {
+    pagesPromise = fetch('/_brust/ai/manifest.json', { headers: { Accept: 'application/json' } })
+      .then(async (response) => {
+        if (!response.ok) return notFound(`ai manifest request failed with HTTP ${response.status}`)
+        const manifest = (await response.json()) as Partial<AiManifest>
+        if (manifest.version !== 1 || !Array.isArray(manifest.pages)) {
+          return notFound('ai manifest has an unsupported shape')
+        }
+        return manifest.pages
+      })
+      .catch((cause) => notFound(`ai manifest request failed: ${String(cause)}`))
+  }
+  return pagesPromise
+}
+
+export function __resetPagesForTest(): void {
+  pagesPromise = null
+}