brustjs 0.1.0-alpha

package/runtime/mcp/extractor.ts

@@ -0,0 +1,160 @@
+import ts from 'typescript'
+import { tsTypeToJsonSchema, type JsonSchema } from './schema.ts'
+import type { McpManifest, ToolSchema, ResourceSchema } from './manifest.ts'
+import type { ActionDef } from '../actions.ts'
+import type { FlatRoute } from '../routes.ts'
+
+export interface ExtractOptions {
+  /** Files that have 'use server' directive — provided by scanActions. */
+  serverFiles: string[]
+  /** The routes module file (e.g. example/hello-world/routes.tsx). */
+  routesFile: string
+  /** The user's source roots. Reserved for future tsconfig/baseUrl/paths
+   * resolution; currently ignored — pass at least one for forward compat. */
+  sourceRoots: string[]
+  /** Result of `await brust.scanActions(...)` — maps action ids to ActionDef. */
+  actions: ActionDef[]
+  /** Result of `defineRoutes(...)`. */
+  routes: FlatRoute[]
+}
+
+export async function extractMcpManifest(opts: ExtractOptions): Promise<McpManifest> {
+  const program = ts.createProgram({
+    rootNames: [...opts.serverFiles, opts.routesFile],
+    options: {
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      jsx: ts.JsxEmit.Preserve,
+      allowJs: false,
+      noEmit: true,
+      skipLibCheck: true,
+      // Required: TS 5.x collapses string | null to plain string without strict
+      // null checks, which would silently drop the null variant from the schema.
+      strictNullChecks: true,
+    },
+  })
+  const checker = program.getTypeChecker()
+
+  const tools: ToolSchema[] = []
+  const actionIds = new Set(opts.actions.map((a) => a.id))
+
+  for (const serverFile of opts.serverFiles) {
+    const sf = program.getSourceFile(serverFile)
+    if (!sf) continue
+    ts.forEachChild(sf, (node) => {
+      const tool = extractToolFromNode(checker, node, actionIds)
+      if (tool) tools.push(tool)
+    })
+  }
+
+  const resources = extractResources(checker, opts.routes, program.getSourceFile(opts.routesFile))
+
+  // Sort tools/resources alphabetically for stable manifest.
+  tools.sort((a, b) => a.name.localeCompare(b.name))
+  resources.sort((a, b) => a.uriTemplate.localeCompare(b.uriTemplate))
+
+  return { version: 1, tools, resources }
+}
+
+function extractToolFromNode(
+  checker: ts.TypeChecker,
+  node: ts.Node,
+  actionIds: Set<string>,
+): ToolSchema | null {
+  // Case 1: export async function name(req, ...args)
+  if (
+    ts.isFunctionDeclaration(node) &&
+    node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) &&
+    node.name
+  ) {
+    const name = node.name.text
+    if (!actionIds.has(name)) return null
+    return toolFromSignature(checker, name, node.parameters, node.type, getJsdoc(node))
+  }
+  // Case 2: export const name = withMiddleware([...], async (req, ...args) => ...)
+  if (
+    ts.isVariableStatement(node) &&
+    node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+  ) {
+    for (const decl of node.declarationList.declarations) {
+      if (!ts.isIdentifier(decl.name)) continue
+      const name = decl.name.text
+      if (!actionIds.has(name)) continue
+      // Find the function expression inside withMiddleware(...).
+      const init = decl.initializer
+      if (init && ts.isCallExpression(init)) {
+        const fnArg = init.arguments[1]
+        if (fnArg && (ts.isArrowFunction(fnArg) || ts.isFunctionExpression(fnArg))) {
+          return toolFromSignature(checker, name, fnArg.parameters, fnArg.type, getJsdoc(node))
+        }
+      }
+    }
+  }
+  return null
+}
+
+function toolFromSignature(
+  checker: ts.TypeChecker,
+  name: string,
+  parameters: ts.NodeArray<ts.ParameterDeclaration>,
+  returnTypeNode: ts.TypeNode | undefined,
+  description: string | undefined,
+): ToolSchema {
+  // Drop the first parameter (req: BrustRequest).
+  const argParams = parameters.slice(1)
+  const properties: Record<string, JsonSchema> = {}
+  const required: string[] = []
+  const paramOrder: string[] = []
+  for (const p of argParams) {
+    if (!ts.isIdentifier(p.name)) continue
+    const pname = p.name.text
+    paramOrder.push(pname)
+    const t = checker.getTypeAtLocation(p)
+    const schema = tsTypeToJsonSchema(t, { checker }) ?? {}
+    properties[pname] = schema
+    // Rest params (...args) are always optional at the call site — never required.
+    if (!p.questionToken && !p.dotDotDotToken) required.push(pname)
+  }
+  const inputSchema: JsonSchema = { type: 'object', properties }
+  if (required.length > 0) inputSchema.required = required
+
+  let outputSchema: JsonSchema | undefined
+  if (returnTypeNode) {
+    const returnType = checker.getTypeFromTypeNode(returnTypeNode)
+    outputSchema = tsTypeToJsonSchema(returnType, { checker, unwrapPromise: true })
+  }
+
+  return { name, description, inputSchema, outputSchema, paramOrder }
+}
+
+function extractResources(
+  _checker: ts.TypeChecker,
+  routes: FlatRoute[],
+  _routesSourceFile: ts.SourceFile | undefined,
+): ResourceSchema[] {
+  const out: ResourceSchema[] = []
+  for (let i = 0; i < routes.length; i++) {
+    const fr = routes[i]
+    const leaf = fr.chain[fr.chain.length - 1]
+    if (!leaf.loader) continue
+    // outputSchema extraction is best-effort — look up the loader's type via the source file.
+    // Skipped for MVP — leaves outputSchema undefined; MCP still works.
+    out.push({
+      uriTemplate: `brust://${fr.fullPath}`,
+      name: `loader for ${fr.fullPath}`,
+      routeIndex: i,
+    })
+  }
+  return out
+}
+
+function getJsdoc(node: ts.Node): string | undefined {
+  const tags = ts.getJSDocCommentsAndTags(node)
+  if (tags.length === 0) return undefined
+  const first = tags[0]
+  // JSDoc `comment` can be either a string or a NodeArray<JSDocComment> when
+  // inline tags like {@link} are present — ts.getTextOfJSDocComment normalises.
+  if (ts.isJSDoc(first)) return ts.getTextOfJSDocComment(first.comment) ?? undefined
+  return undefined
+}

package/runtime/mcp/manifest.ts

@@ -0,0 +1,50 @@
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { JsonSchema } from './schema.ts'
+
+export interface ToolSchema {
+  name: string
+  description?: string
+  inputSchema: JsonSchema
+  outputSchema?: JsonSchema
+  paramOrder: string[]
+}
+
+export interface ResourceSchema {
+  uriTemplate: string
+  name: string
+  description?: string
+  outputSchema?: JsonSchema
+  routeIndex: number
+}
+
+export interface McpManifest {
+  version: 1
+  tools: ToolSchema[]
+  resources: ResourceSchema[]
+}
+
+const MANIFEST_PATH = '.brust/mcp-manifest.json'
+
+export async function writeManifest(cwd: string, m: McpManifest): Promise<void> {
+  const path = join(cwd, MANIFEST_PATH)
+  await mkdir(join(cwd, '.brust'), { recursive: true })
+  await Bun.write(path, JSON.stringify(m, null, 2))
+}
+
+export async function readManifest(cwd: string): Promise<McpManifest | null> {
+  const path = join(cwd, MANIFEST_PATH)
+  const f = Bun.file(path)
+  if (!(await f.exists())) return null
+  const text = await f.text()
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (e) {
+    throw new Error(`mcp-manifest.json is malformed: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (!parsed || typeof parsed !== 'object' || (parsed as McpManifest).version !== 1) {
+    throw new Error(`mcp-manifest.json version mismatch (expected 1)`)
+  }
+  return parsed as McpManifest
+}

package/runtime/mcp/schema.ts

@@ -0,0 +1,124 @@
+import ts from 'typescript'
+
+export interface JsonSchema {
+  type?: string | string[]
+  properties?: Record<string, JsonSchema>
+  required?: string[]
+  items?: JsonSchema
+  prefixItems?: JsonSchema[]
+  minItems?: number
+  maxItems?: number
+  additionalProperties?: JsonSchema | boolean
+  anyOf?: JsonSchema[]
+  enum?: unknown[]
+  format?: string
+}
+
+export interface ToJsonSchemaOptions {
+  unwrapPromise?: boolean
+  checker?: ts.TypeChecker // required for object/property iteration
+}
+
+export function tsTypeToJsonSchema(
+  type: ts.Type,
+  opts: ToJsonSchemaOptions = {},
+): JsonSchema | undefined {
+  const flags = type.flags
+  // Unwrap Promise<T> at the top level when asked.
+  if (opts.unwrapPromise) {
+    const inner = unwrapPromise(type, opts.checker)
+    if (inner === null) return undefined // Promise<void>
+    if (inner !== undefined) return tsTypeToJsonSchema(inner, { ...opts, unwrapPromise: false })
+  }
+  // void → undefined (caller treats as "no schema")
+  if (flags & ts.TypeFlags.Void) return undefined
+  // any/unknown
+  if (flags & ts.TypeFlags.Any || flags & ts.TypeFlags.Unknown) return {}
+  // null
+  if (flags & ts.TypeFlags.Null || flags & ts.TypeFlags.Undefined) return { type: 'null' }
+  // string literal
+  if (flags & ts.TypeFlags.StringLiteral)
+    return { type: 'string', enum: [(type as ts.StringLiteralType).value] }
+  // number literal
+  if (flags & ts.TypeFlags.NumberLiteral)
+    return { type: 'number', enum: [(type as ts.NumberLiteralType).value] }
+  // boolean literal
+  if (flags & ts.TypeFlags.BooleanLiteral) {
+    const v = (type as any).intrinsicName === 'true'
+    return { type: 'boolean', enum: [v] }
+  }
+  if (flags & ts.TypeFlags.String) return { type: 'string' }
+  if (flags & ts.TypeFlags.Number) return { type: 'number' }
+  if (flags & ts.TypeFlags.Boolean) return { type: 'boolean' }
+  // Union
+  if (type.isUnion()) {
+    return {
+      anyOf: type.types
+        .map((t) => tsTypeToJsonSchema(t, opts))
+        .filter((x): x is JsonSchema => x !== undefined),
+    }
+  }
+  // Date special case
+  const symbol = type.getSymbol()
+  if (symbol?.name === 'Date') return { type: 'string', format: 'date-time' }
+  // Array / Tuple / Object
+  if (opts.checker) {
+    if (opts.checker.isArrayType?.(type)) {
+      const args = opts.checker.getTypeArguments(type as ts.TypeReference)
+      const inner = args[0]
+      return { type: 'array', items: tsTypeToJsonSchema(inner, opts) ?? {} }
+    }
+    // Tuple
+    if (opts.checker.isTupleType?.(type)) {
+      const args = opts.checker.getTypeArguments(type as ts.TypeReference) ?? []
+      const target = (type as any).target
+      return {
+        type: 'array',
+        prefixItems: args.map((t: ts.Type) => tsTypeToJsonSchema(t, opts) ?? {}),
+        minItems: target?.minLength ?? args.length,
+        maxItems: args.length,
+      }
+    }
+    // Object: enumerate properties (or Record-like via string index signature)
+    if (flags & ts.TypeFlags.Object) {
+      const props = type.getProperties()
+      const stringIndex = type.getStringIndexType()
+      if (props.length === 0 && stringIndex) {
+        return { type: 'object', additionalProperties: tsTypeToJsonSchema(stringIndex, opts) ?? {} }
+      }
+      const properties: Record<string, JsonSchema> = {}
+      const required: string[] = []
+      for (const p of props) {
+        const decl = p.declarations?.[0]
+        if (!decl) continue
+        const propType = opts.checker.getTypeOfSymbolAtLocation(p, decl)
+        const propSchema = tsTypeToJsonSchema(propType, opts)
+        if (propSchema) {
+          properties[p.name] = propSchema
+          if (!(p.flags & ts.SymbolFlags.Optional)) {
+            required.push(p.name)
+          }
+        }
+      }
+      const out: JsonSchema = { type: 'object', properties }
+      if (required.length > 0) out.required = required
+      return out
+    }
+  }
+  // Fallback: any (loses info but agent still works)
+  return {}
+}
+
+function unwrapPromise(type: ts.Type, checker?: ts.TypeChecker): ts.Type | null | undefined {
+  // Returns: ts.Type unwrapped; null = unwrap result is void; undefined = not a Promise.
+  // getPromisedTypeOfPromise exists at runtime on every supported TS 5.x but is
+  // absent from the public TypeChecker typings — cast to access without losing
+  // strict-mode coverage elsewhere.
+  if (!checker) return undefined
+  const inner = (
+    checker as unknown as { getPromisedTypeOfPromise(t: ts.Type): ts.Type | undefined }
+  ).getPromisedTypeOfPromise(type)
+  if (inner === undefined) return undefined
+  if (inner.flags & ts.TypeFlags.Void) return null
+  return inner
+}

package/runtime/mcp/server.ts

@@ -0,0 +1,250 @@
+import type { ActionDef } from '../actions.ts'
+import type { FlatRoute, BrustRequest } from '../routes.ts'
+import type { McpManifest } from './manifest.ts'
+
+export interface McpServerOptions {
+  manifest: McpManifest
+  actions: ActionDef[]
+  routes: FlatRoute[]
+  packageVersion?: string
+}
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0'
+  id?: number | string | null
+  method: string
+  params?: unknown
+}
+
+interface JsonRpcSuccess<T> {
+  jsonrpc: '2.0'
+  id: number | string | null
+  result: T
+}
+
+interface JsonRpcError {
+  jsonrpc: '2.0'
+  id: number | string | null
+  error: { code: number; message: string; data?: unknown }
+}
+
+export interface McpServer {
+  handleRequest(jsonRpcBody: string, req: BrustRequest): Promise<string>
+}
+
+export function makeMcpServer(opts: McpServerOptions): McpServer {
+  return {
+    async handleRequest(jsonRpcBody, req): Promise<string> {
+      let rpc: JsonRpcRequest
+      try {
+        rpc = JSON.parse(jsonRpcBody)
+      } catch {
+        return makeError(null, -32700, 'Parse error')
+      }
+      if (rpc.jsonrpc !== '2.0' || typeof rpc.method !== 'string') {
+        return makeError(rpc.id ?? null, -32600, 'Invalid Request')
+      }
+      switch (rpc.method) {
+        case 'initialize':
+          return handleInitialize(rpc, opts)
+        case 'notifications/initialized':
+          return '' // No response for notifications.
+        case 'tools/list':
+          return handleToolsList(rpc, opts)
+        case 'tools/call':
+          return handleToolsCall(rpc, opts, req)
+        case 'resources/list':
+          return handleResourcesList(rpc, opts)
+        case 'resources/read':
+          return handleResourcesRead(rpc, opts, req)
+        case 'prompts/list':
+          return makeResult(rpc.id ?? null, { prompts: [] })
+        case 'prompts/get':
+          return makeError(rpc.id ?? null, -32601, 'no prompts configured')
+        case 'logging/setLevel':
+          // Accept the level; no notifications emitted (SSE deferred).
+          return makeResult(rpc.id ?? null, {})
+        case 'notifications/roots/list_changed':
+          // No-op accept (it's a notification, no response).
+          return ''
+        default:
+          return makeError(rpc.id ?? null, -32601, `method not found: ${rpc.method}`)
+      }
+    },
+  }
+}
+
+function handleInitialize(rpc: JsonRpcRequest, opts: McpServerOptions): string {
+  return makeResult(rpc.id ?? null, {
+    protocolVersion: '2025-06-18',
+    capabilities: {
+      tools: {},
+      resources: {},
+      prompts: {},
+      logging: {},
+      // roots is a client capability; not declared by server.
+    },
+    serverInfo: {
+      name: 'brust',
+      version: opts.packageVersion ?? '0.1.0',
+    },
+  })
+}
+
+async function handleToolsList(rpc: JsonRpcRequest, opts: McpServerOptions): Promise<string> {
+  const tools = opts.manifest.tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+    outputSchema: t.outputSchema,
+  }))
+  return makeResult(rpc.id ?? null, { tools })
+}
+
+async function handleToolsCall(
+  rpc: JsonRpcRequest,
+  opts: McpServerOptions,
+  req: BrustRequest,
+): Promise<string> {
+  const params = rpc.params as { name?: string; arguments?: Record<string, unknown> } | undefined
+  if (!params || typeof params.name !== 'string') {
+    return makeError(rpc.id ?? null, -32602, 'tools/call: name required')
+  }
+  const tool = opts.manifest.tools.find((t) => t.name === params.name)
+  if (!tool) {
+    return makeError(rpc.id ?? null, -32601, `unknown tool: ${params.name}`)
+  }
+  const action = opts.actions.find((a) => a.id === params.name)
+  if (!action) {
+    return makeError(rpc.id ?? null, -32603, `action not registered: ${params.name}`)
+  }
+  // Map { argsObject } → positional args via paramOrder.
+  const args = (tool.paramOrder ?? []).map((k) => params.arguments?.[k])
+
+  // Run through middleware chain (same shape as actionBranch).
+  const { composeChain } = await import('../routes.ts')
+  const terminal = async () => {
+    try {
+      const result = await action.fn(req, ...args)
+      return {
+        status: 200,
+        body: result === undefined ? '' : JSON.stringify(result),
+        contentType: 'application/json; charset=utf-8',
+      }
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err))
+      return {
+        status: 500,
+        body: JSON.stringify({ error: { message: e.message, name: e.name } }),
+        contentType: 'application/json; charset=utf-8',
+      }
+    }
+  }
+  const chain = composeChain(req, action.middleware, terminal)
+  const response = await chain()
+  if (response.status >= 400) {
+    return makeResult(rpc.id ?? null, {
+      content: [{ type: 'text', text: response.body }],
+      isError: true,
+    })
+  }
+  return makeResult(rpc.id ?? null, {
+    content: [{ type: 'text', text: response.body || '' }],
+    isError: false,
+  })
+}
+
+async function handleResourcesList(rpc: JsonRpcRequest, opts: McpServerOptions): Promise<string> {
+  const resources = opts.manifest.resources.map((r) => ({
+    uri: r.uriTemplate,
+    name: r.name,
+    description: r.description,
+    mimeType: 'application/json',
+  }))
+  return makeResult(rpc.id ?? null, { resources })
+}
+
+async function handleResourcesRead(
+  rpc: JsonRpcRequest,
+  opts: McpServerOptions,
+  req: BrustRequest,
+): Promise<string> {
+  const params = rpc.params as { uri?: string } | undefined
+  if (!params || typeof params.uri !== 'string') {
+    return makeError(rpc.id ?? null, -32602, 'resources/read: uri required')
+  }
+  // Strip the brust:// scheme.
+  const prefix = 'brust://'
+  if (!params.uri.startsWith(prefix)) {
+    return makeError(rpc.id ?? null, -32602, `unsupported URI scheme: ${params.uri}`)
+  }
+  const requestedPath = params.uri.slice(prefix.length)
+
+  // Match against the routes. matchUriPath does the {param} capture that the
+  // manifest's pre-computed ResourceSchema.routeIndex cannot do alone — both
+  // index spaces stay aligned because the extractor builds resources in the
+  // same opts.routes order the server consumes, so a divergence would mean
+  // routes were rebuilt without a matching brust.buildMcpManifest call.
+  const match = matchUriPath(requestedPath, opts.routes)
+  if (!match) {
+    return makeError(rpc.id ?? null, -32601, `no route matches URI ${params.uri}`)
+  }
+  const route = opts.routes[match.routeIndex]
+  const leaf = route.chain[route.chain.length - 1]
+  if (!leaf.loader) {
+    return makeError(rpc.id ?? null, -32603, `route ${route.fullPath} has no loader`)
+  }
+  try {
+    const data = await leaf.loader({ params: match.params, path: requestedPath, req })
+    return makeResult(rpc.id ?? null, {
+      contents: [
+        {
+          uri: params.uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(data),
+        },
+      ],
+    })
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return makeError(rpc.id ?? null, -32603, `loader error: ${msg}`)
+  }
+}
+
+interface UriMatch {
+  routeIndex: number
+  params: Record<string, string>
+}
+
+function matchUriPath(requestedPath: string, routes: FlatRoute[]): UriMatch | null {
+  // Simple param matching: split both into segments and match.
+  const reqSegs = requestedPath.split('/').filter((s) => s.length > 0)
+  for (let i = 0; i < routes.length; i++) {
+    const fr = routes[i]
+    const routeSegs = fr.fullPath.split('/').filter((s) => s.length > 0)
+    if (reqSegs.length !== routeSegs.length) continue
+    const params: Record<string, string> = {}
+    let matched = true
+    for (let j = 0; j < reqSegs.length; j++) {
+      const rseg = routeSegs[j]
+      if (rseg.startsWith('{') && rseg.endsWith('}')) {
+        params[rseg.slice(1, -1)] = reqSegs[j]
+      } else if (rseg !== reqSegs[j]) {
+        matched = false
+        break
+      }
+    }
+    if (matched) return { routeIndex: i, params }
+  }
+  return null
+}
+
+export function makeResult(id: number | string | null, result: unknown): string {
+  const resp: JsonRpcSuccess<unknown> = { jsonrpc: '2.0', id, result }
+  return JSON.stringify(resp)
+}
+
+export function makeError(id: number | string | null, code: number, message: string): string {
+  const resp: JsonRpcError = { jsonrpc: '2.0', id, error: { code, message } }
+  return JSON.stringify(resp)
+}

package/runtime/render/inject-css-link.ts

@@ -0,0 +1,59 @@
+const ENC = new TextEncoder()
+
+/** Set to true on the first miss; suppresses subsequent warnings so a
+ * misconfigured Layout doesn't flood logs. Test helper resets this. */
+let warned = false
+
+/** @internal — used by the unit test suite to reset the warn-once flag. */
+export function _resetWarnedForTests(): void {
+  warned = false
+}
+
+/** Splice `<link rel="stylesheet" href="...">` tags into `body` immediately
+ * before the first occurrence of `</head>` (case-insensitive). Returns the
+ * original body untouched if `hrefs` is empty or if `</head>` is absent
+ * (warns once in the latter case). Renderer calls this on the first chunk
+ * only — see spec §"SSR <link> injection". */
+export function injectCssLink(body: Uint8Array, hrefs: readonly string[]): Uint8Array {
+  if (hrefs.length === 0) return body
+  const pos = findHeadCloseTag(body)
+  if (pos < 0) {
+    if (!warned) {
+      console.warn('[brust] css: no </head> in first chunk; <link> not injected')
+      warned = true
+    }
+    return body
+  }
+  const tags = hrefs.map((h) => `<link rel="stylesheet" href="${h}">`).join('')
+  const tagsBytes = ENC.encode(tags)
+  const out = new Uint8Array(body.length + tagsBytes.length)
+  out.set(body.subarray(0, pos), 0)
+  out.set(tagsBytes, pos)
+  out.set(body.subarray(pos), pos + tagsBytes.length)
+  return out
+}
+
+/** Byte-level scan for `</head>` (case-insensitive on the four letters).
+ * Returns the byte offset of the `<` or -1 if not found. */
+function findHeadCloseTag(body: Uint8Array): number {
+  // Target bytes: `<` `/` H E A D `>`  — 7 bytes total.
+  // We only case-fold the four ASCII letters; the angle/slash bytes are exact.
+  const LT = 0x3c // <
+  const SL = 0x2f // /
+  const 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 // H/h
+    if (!isLetter(body[i + 3], 0x45)) continue // E/e
+    if (!isLetter(body[i + 4], 0x41)) continue // A/a
+    if (!isLetter(body[i + 5], 0x44)) continue // D/d
+    if (body[i + 6] !== GT) continue
+    return i
+  }
+  return -1
+}
+
+/** Returns true if `b` matches the upper-case letter `u` (b === u || b === u|0x20). */
+function isLetter(b: number, u: number): boolean {
+  return b === u || b === (u | 0x20)
+}

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

@@ -0,0 +1,49 @@
+const ENC = new TextEncoder()
+
+let warned = false
+
+/** @internal — used by tests to reset the warn-once flag. */
+export function _resetWarnedForTests(): void {
+  warned = false
+}
+
+/** 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. */
+export function injectDevClient(body: Uint8Array, snippet: string | null): Uint8Array {
+  if (!snippet) return body
+  const pos = findHeadCloseTag(body)
+  if (pos < 0) {
+    if (!warned) {
+      console.warn('[brust] dev: no </head> in first chunk; dev-client <script> not injected')
+      warned = true
+    }
+    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)
+}