@brust/core 2.0.0-alpha.3 → 2.0.0-alpha.4

package/src/actions/load.ts

@@ -14,7 +14,8 @@ export function mountActions(app: unknown, prefix: string, what = 'actions entry
     throw new Error(
       `${what}: build the app with new Elysia({ adapter: brust() }) — import { brust } from '@brust/core/elysia'`,
     )
-  return new Elysia({ adapter: brust(), prefix }).use(app)
+  // L16 R16.4: the root prefix of an actions-only build is no prefix at all (`prefix: '/'` would double the slash).
+  return new Elysia({ adapter: brust(), ...(prefix === '/' ? {} : { prefix }) }).use(app)
 }
 
 export async function loadActionsApp(file: string, prefix: string): Promise<AnyElysia> {

package/src/actions/prefix.ts

@@ -5,8 +5,10 @@ export const DEFAULT_MAX_RESPONSE_BYTES = 8_388_608
 export const MAX_ACTION_BYTES = 67_108_864
 const SEG = /^[A-Za-z0-9._~-]+$/
 
-/** Why `p` cannot be the actions prefix, or null. Segment-safe like the server's match. */
-export function prefixError(p: unknown): string | null {
+/** Why `p` cannot be the actions prefix, or null. Segment-safe like the server's match. `root`: an actions-only
+ * build (L16 R16.4) may mount at `/`; a normal build never may (its page routes would be unreachable). */
+export function prefixError(p: unknown, root = false): string | null {
+  if (root && p === '/') return null
   if (typeof p !== 'string' || !p.startsWith('/') || p.length < 2 || p.endsWith('/'))
     return `must start with '/', be longer than '/' and have no trailing '/' (got ${JSON.stringify(p)})`
   const segs = p.slice(1).split('/')
@@ -21,3 +23,23 @@ export function prefixError(p: unknown): string | null {
     return `${p} is reserved for the server's own /_brust/ paths`
   return null
 }
+
+/** L16 R16.1: `base_url` is an absolute http(s) origin: scheme, host, optional port; no path, query, fragment or userinfo. */
+export function baseUrlError(v: unknown): string | null {
+  if (typeof v !== 'string' || !/^https?:\/\//.test(v))
+    return `must be an absolute http(s) origin such as https://api.example.com (got ${JSON.stringify(v)})`
+  let u: URL
+  try {
+    u = new URL(v)
+  } catch {
+    return `is not a valid URL (got ${JSON.stringify(v)})`
+  }
+  const authority = v.replace(/^https?:\/\//, '')
+  if (u.search !== '' || u.hash !== '' || u.username !== '' || u.password !== '' || /[/?#@\\\s]/.test(authority))
+    return `must be an origin only: no path, query, fragment or credentials (got ${JSON.stringify(v)})`
+  return null
+}
+
+/** L16 R16.2: the default `RequestInit.credentials` of the browser client. */
+export const ACTION_CREDENTIALS = ['same-origin', 'include', 'omit'] as const
+export type ActionCredentials = (typeof ACTION_CREDENTIALS)[number]

package/src/actions-bridge.ts

@@ -22,7 +22,7 @@ export interface FetchRequest {
   method: string
   url: string
   headers: [string, string][]
-  /** `{heap: n}` (F82): more than 262144 bytes, fetched with `takeFetchBody(slot)`. */
+  /** `{heap: n}` (F82): more than 262144 bytes (`ACTION_INLINE_BODY_BYTES`, independent of the slot size), fetched with `takeFetchBody(slot)`. */
   body: { text: string } | { b64: string } | { heap: number } | null
   req: LoaderReq
 }
@@ -139,7 +139,7 @@ export const noActions = async (_: Request): Promise<Response> =>
   new Response('brust: actions are not configured in this worker', { status: 500, headers: { 'content-type': 'text/plain; charset=utf-8' } })
 
 /** The `fetch` call (makeDispatch). Never rejects, never writes JSON: every outcome is a frame. A body of
- * more than 262144 bytes arrives by `io.takeBody` (A1 `{heap}`); a response that does not fit the slot leaves
+ * more than 262144 bytes (`ACTION_INLINE_BODY_BYTES`, not the slot size) arrives by `io.takeBody` (A1 `{heap}`); a response that does not fit the slot leaves
  * by `io.putReply` with only status/headers/`heap` in the slot (F82), unless it exceeds `max_response_bytes`. */
 export async function runFetch(requestJson: string, view: Uint8Array, slot: number, slots: number, io: HeapIo = nativeHeapIo): Promise<number> {
   const a = app

package/src/browser.ts

@@ -1,7 +1,9 @@
+/// <reference path="./css-modules.d.ts" />
 // `@brust/core` under the `browser` export condition (and what every browser bundle of
 // `brust build` resolves the package root to): only the side-effect-free pieces. No `run`, no
 // config, no napi addon — a react island may import `cache` from the package root.
 import { cacheComponent } from './cache-core'
+export { buildTime } from './build-time'
 import type { InvalidateArgs, InvalidateResult } from './native'
 
 function invalidate(_args: InvalidateArgs): InvalidateResult {
@@ -26,4 +28,4 @@ export {
   Outlet,
   redirect,
 } from './routes'
-export type { ComponentType, FlatRoute, HttpErrorOpts, HttpErrorTrigger, LoaderCtx, LoaderReq, Route, RouteCacheConfig, Verdict } from './routes'
+export type { ComponentType, FlatRoute, HttpErrorOpts, HttpErrorTrigger, LoaderCtx, LoaderReq, Route, RouteCacheConfig, RouteSsgConfig, Verdict } from './routes'

package/src/build/actions-only.ts

@@ -0,0 +1,86 @@
+// `brust build --actions-only` (gaps round L16, R16.3/R16.4): a dist with NO page routes: the actions app behind
+// the same Rust admission (method gate, body caps, `Content-Encoding`, the cross-site guard, CORS), every other
+// path a 404 problem+json. With `--target cloudflare` it also writes `<out>/cf/`: a Worker serving only actions
+// (no Static Assets). The routes entry is neither read nor required.
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { buildActions } from './bundle'
+import { type CfPrepared, buildCloudflare, prepareCloudflare } from './cloudflare'
+import type { ActionsBuildConfig, BuildConfig } from './config'
+import { BuildError } from './errors'
+import { MANIFEST_VERSION, type ManifestJson } from './manifest'
+
+const MARKER = '.brust'
+
+export async function runActionsOnly(o: {
+  appRoot: string
+  dist: string
+  config: BuildConfig
+  target: 'bun' | 'cloudflare' | 'static' | undefined
+  wasmFromSource: boolean
+  statOk: (p: string) => boolean
+  assertSafeOutDir: (dist: string, appRoot: string, keep: string[]) => void
+  log: (s: string) => void
+}): Promise<void> {
+  const { appRoot, dist, config } = o
+  const actions: ActionsBuildConfig | null = config.actions
+  if (!actions) throw new BuildError('actions-only', '--actions-only needs an [actions] table in brust.toml')
+  if (o.target === 'static') throw new BuildError('actions-only', '--actions-only builds no pages: it cannot be combined with --target static')
+  const entry = resolve(appRoot, actions.entry)
+  const rel = relative(appRoot, entry)
+  if (isAbsolute(actions.entry) || rel === '..' || rel.startsWith('../') || isAbsolute(rel) || !o.statOk(entry))
+    throw new BuildError('actions-entry', `actions.entry ${actions.entry} is not a file inside the app`)
+  o.assertSafeOutDir(dist, appRoot, [entry])
+  if (config.cache) o.log('[brust] actions-only: [cache] and route options do not apply (ignored)')
+  if (actions.baseUrl !== undefined) o.log('[brust] actions-only: [actions] base_url is for the pages that call these actions (ignored here)')
+  const cf: CfPrepared | null = o.target === 'cloudflare' ? await prepareCloudflare(appRoot, config.cloudflare, { fromSource: o.wasmFromSource, env: process.env }) : null
+
+  const tmp = join(dirname(dist), `.${basename(dist)}.brust-tmp`)
+  rmSync(tmp, { recursive: true, force: true })
+  mkdirSync(tmp, { recursive: true })
+  try {
+    const manifest: ManifestJson = {
+      version: MANIFEST_VERSION,
+      routes: [],
+      components: {},
+      assets: { runtime: '' },
+      jobs_module: 'jobs.js',
+      actions: { entry: await buildActions(tmp, entry), prefix: actions.prefix, maxBodyBytes: actions.maxBodyBytes, maxResponseBytes: actions.maxResponseBytes, crossSite: actions.crossSite },
+      actions_only: true,
+    }
+    mkdirSync(join(tmp, 'jinja'), { recursive: true })
+    writeFileSync(join(tmp, 'jobs.js'), '// generated by `brust build --actions-only`: no pages, so no jobs\nexport default {}\n')
+    writeFileSync(join(tmp, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+    writeFileSync(join(tmp, MARKER), 'generated by `brust build`: this directory is replaced on every build\n')
+    writeFileSync(
+      join(tmp, 'index.js'),
+      [
+        '// generated by `brust build --actions-only` — `bun dist/index.js` serves the actions (do not edit)',
+        "process.env.BRUST_PREBUILT = '1'",
+        'process.env.BRUST_DIST_DIR = import.meta.dir',
+        "const { run } = await import('@brust/core')",
+        'await run()',
+        '',
+      ].join('\n'),
+    )
+    if (cf) {
+      const warnings = await buildCloudflare(
+        tmp,
+        { appRoot, entry, dist, compiled: new Map(), manifest, sourceOf: new Map(), actionsEntry: entry, actionsOnly: true, log: o.log },
+        cf,
+      )
+      for (const w of warnings) o.log(w)
+    }
+    rmSync(join(tmp, '.stage'), { recursive: true, force: true })
+    if (existsSync(dist)) {
+      const old = join(dirname(dist), `.${basename(dist)}.brust-old`)
+      rmSync(old, { recursive: true, force: true })
+      renameSync(dist, old)
+      renameSync(tmp, dist)
+      rmSync(old, { recursive: true, force: true })
+    } else renameSync(tmp, dist)
+  } catch (e) {
+    rmSync(tmp, { recursive: true, force: true })
+    throw e
+  }
+}

package/src/build/build-eval.ts

@@ -0,0 +1,199 @@
+// Build-time evaluation of precompute slots (L2, G4/H1). The compiler marks the slots that read
+// nothing request- or time-dependent (`ir.build_eval`) and emits one thunk per slot (`evalTs`).
+// Here they are bundled once, run in a Bun subprocess (`TZ=UTC`, a timeout per slot, JSON-only
+// values, a size cap) and the results go back to the compiler as slot -> literal overrides: the
+// slot, and a job left with no slots, disappear. A pure helper that fails keeps its job with a
+// `build-eval` warning; a failing `buildTime(…)` is a build error (the user asked for it).
+import { join } from 'node:path'
+import type { BunPlugin } from 'bun'
+import { type SourceOf, PRODUCTION, sourceDirPlugin, stage, write } from './bundle'
+import type { Compiled } from './compile'
+import { BuildError } from './errors'
+
+const V1 = { timeoutMs: 2_000, capBytes: 64 * 1024 }
+const BUILD_TIME = { timeoutMs: 10_000, capBytes: 256 * 1024 }
+
+interface Candidate {
+  key: string
+  bt: boolean
+  where: string
+}
+
+/** The runner the subprocess executes: loads the bundle, guards the sources of nondeterminism,
+ * and prints `S <i>` before and `R <i> <json>` / `E <i> <message>` after each slot. */
+const RUNNER = `
+const mod = await import(process.argv[2])
+const start = Number(process.argv[3])
+const slots = mod.default
+const deny = (what) => () => { throw new Error('build-eval: ' + what + ' is not allowed (it differs between runs)') }
+const RealDate = globalThis.Date
+globalThis.Date = new Proxy(RealDate, {
+  construct(t, a) { if (a.length === 0) deny('new Date()')(); return Reflect.construct(t, a) },
+  apply() { deny('Date()')() },
+  get(t, p, r) { if (p === 'now') deny('Date.now()')(); return Reflect.get(t, p, r) },
+})
+Math.random = deny('Math.random()')
+if (globalThis.performance) globalThis.performance.now = deny('performance.now()')
+if (globalThis.crypto) { for (const k of ['randomUUID', 'getRandomValues']) { try { globalThis.crypto[k] = deny('crypto.' + k + '()') } catch {} } }
+globalThis.fetch = deny('fetch()')
+const out = (l) => process.stdout.write(l + '\\n')
+const env = process.env
+try { Object.defineProperty(process, 'env', { configurable: true, get: deny('process.env') }) } catch {}
+const enc = (v, path) => {
+  if (v === null || typeof v === 'boolean' || typeof v === 'string') return v
+  if (typeof v === 'number') { if (!Number.isFinite(v)) throw new Error('not JSON: ' + path + ' is ' + v); return v }
+  if (Array.isArray(v)) return v.map((x, i) => { if (x === undefined && !(i in v)) throw new Error('not JSON: sparse array at ' + path); return enc(x, path + '[' + i + ']') })
+  if (typeof v === 'object' && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null)) {
+    return { $: Object.keys(v).map((k) => { if (v[k] === undefined) throw new Error('not JSON: ' + path + '.' + k + ' is undefined'); return [k, enc(v[k], path + '.' + k)] }) }
+  }
+  throw new Error('not JSON: ' + path + ' is ' + (v === undefined ? 'undefined' : typeof v === 'object' ? (v.constructor && v.constructor.name) : typeof v))
+}
+for (let i = start; i < slots.length; i++) {
+  out('S ' + i)
+  try {
+    const v = await slots[i].fn()
+    out('R ' + i + ' ' + JSON.stringify(enc(v, 'value')))
+  } catch (e) {
+    out('E ' + i + ' ' + String(e && e.message ? e.message : e).split('\\n')[0])
+  }
+}
+`
+
+/** The evaluator sees an explicit allowlist, never the build host's environment: `process.env`,
+ * `Bun.env` and `import.meta.env` all read from it, however they are spelled. */
+function evalEnv(): Record<string, string> {
+  const env: Record<string, string> = { TZ: 'UTC', NODE_ENV: 'production' }
+  for (const k of ['PATH', 'HOME']) if (process.env[k] !== undefined) env[k] = process.env[k]!
+  return env
+}
+
+type Outcome = { ok: true; value: unknown } | { ok: false; reason: string }
+
+/** Runs slots `[0, n)` of `entry` one after the other, restarting the subprocess after a timeout or crash. */
+async function runAll(entry: string, runner: string, cands: Candidate[], cwd: string): Promise<Outcome[]> {
+  const out: (Outcome | undefined)[] = new Array(cands.length).fill(undefined)
+  let next = 0
+  while (next < cands.length) {
+    const proc = Bun.spawn([process.execPath, runner, entry, String(next)], { cwd, env: evalEnv(), stdout: 'pipe', stderr: 'pipe' })
+    const reader = (proc.stdout as ReadableStream<Uint8Array>).getReader()
+    const dec = new TextDecoder()
+    let buf = ''
+    let current = -1
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let timedOut = false
+    const arm = (i: number) => {
+      clearTimeout(timer)
+      const limit = cands[i]!.bt ? BUILD_TIME.timeoutMs : V1.timeoutMs
+      timer = setTimeout(() => {
+        timedOut = true
+        proc.kill('SIGKILL')
+      }, limit)
+    }
+    const line = (l: string) => {
+      const m = /^([SRE]) (\d+)(?: (.*))?$/.exec(l)
+      if (!m) return
+      const i = Number(m[2])
+      if (m[1] === 'S') {
+        current = i
+        arm(i)
+        return
+      }
+      clearTimeout(timer)
+      const cap = cands[i]!.bt ? BUILD_TIME.capBytes : V1.capBytes
+      if (m[1] === 'E') out[i] = { ok: false, reason: m[3] ?? 'threw' }
+      else if ((m[3] ?? '').length > cap) out[i] = { ok: false, reason: `value is larger than ${cap / 1024} KiB` }
+      else out[i] = { ok: true, value: JSON.parse(m[3]!) }
+      next = i + 1
+      current = -1
+    }
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buf += dec.decode(value, { stream: true })
+      let nl: number
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        line(buf.slice(0, nl))
+        buf = buf.slice(nl + 1)
+      }
+    }
+    clearTimeout(timer)
+    await proc.exited
+    if (current >= 0) {
+      const limit = (cands[current]!.bt ? BUILD_TIME.timeoutMs : V1.timeoutMs) / 1000
+      const stderr = (await new Response(proc.stderr as ReadableStream).text()).trim().split('\n')[0]
+      out[current] = { ok: false, reason: timedOut ? `timed out after ${limit} s` : `the evaluator exited${stderr ? `: ${stderr}` : ''}` }
+      next = current + 1
+    } else if (next < cands.length && !out[next]) {
+      // Exited before reporting anything (the bundle failed to load).
+      const stderr = (await new Response(proc.stderr as ReadableStream).text()).trim().split('\n').slice(0, 3).join(' | ')
+      for (let i = next; i < cands.length; i++) out[i] = { ok: false, reason: `the evaluator could not start${stderr ? `: ${stderr}` : ''}` }
+      next = cands.length
+    }
+  }
+  return out as Outcome[]
+}
+
+/** `@brust/core` inside the evaluator is the side-effect-free `buildTime` module, not the server. */
+function corePlugin(appRoot: string): BunPlugin {
+  return {
+    name: 'brust-eval-core',
+    setup(b) {
+      b.onResolve({ filter: /^@brust\/core$/ }, () => ({ path: Bun.resolveSync('@brust/core/build-time', appRoot) }))
+    },
+  }
+}
+
+/** Evaluates every build-time slot of `compiled`; returns `key -> encoded JSON value` for those that
+ * succeeded. Throws a `BuildError` for a failing `buildTime(…)`; logs `warning build-eval` for a
+ * pure helper that fails (its job stays). */
+export async function evaluateBuildSlots(
+  dist: string,
+  compiled: Map<string, Compiled>,
+  sourceOf: SourceOf,
+  appRoot: string,
+  log: (s: string) => void,
+): Promise<Record<string, unknown>> {
+  // `BRUST_BUILD_EVAL=0` turns evaluation off (every slot stays a job): the reference for dual runs.
+  if (process.env.BRUST_BUILD_EVAL === '0') return {}
+  const cands: Candidate[] = []
+  const imports: string[] = []
+  const entries: string[] = []
+  for (const c of compiled.values()) {
+    const slots = (c.ir.build_eval ?? []) as { key: string; build_time: boolean; line: number; col: number }[]
+    if (c.evalTs === undefined || slots.length === 0) continue
+    const file = join(dist, '.stage', 'eval', `${c.id}.eval.ts`)
+    write(file, c.evalTs)
+    stage(sourceOf, file, c)
+    const n = imports.length
+    imports.push(`import { slots as s${n} } from ${JSON.stringify(file)}`)
+    for (const s of slots) {
+      const where = `${c.file.slice(appRoot.length + 1)}:${s.line}:${s.col}`
+      cands.push({ key: s.key, bt: s.build_time, where })
+      entries.push(`  { fn: s${n}[${JSON.stringify(s.key)}] },`)
+    }
+  }
+  if (cands.length === 0) return {}
+  const entry = join(dist, '.stage', 'eval-entry.ts')
+  write(entry, `${imports.join('\n')}\nexport default [\n${entries.join('\n')}\n]\n`)
+  const res = await Bun.build({
+    entrypoints: [entry],
+    target: 'bun',
+    format: 'esm',
+    define: PRODUCTION,
+    plugins: [corePlugin(appRoot), sourceDirPlugin(sourceOf, appRoot)],
+  })
+  if (!res.success) throw new BuildError('build-eval', `cannot bundle the build-time evaluation: ${res.logs.map(String).join('\n')}`)
+  const bundle = join(dist, '.stage', 'eval.js')
+  write(bundle, await res.outputs[0]!.text())
+  const runner = join(dist, '.stage', 'eval-run.js')
+  write(runner, RUNNER)
+  const results = await runAll(bundle, runner, cands, appRoot)
+  const values: Record<string, unknown> = {}
+  results.forEach((r, i) => {
+    const c = cands[i]!
+    if (r.ok) values[c.key] = r.value
+    else if (c.bt) throw new BuildError('build-time', `${c.where} buildTime(…) failed at build: ${r.reason}`)
+    else log(`warning build-eval ${c.where} not evaluated at build, the job stays: ${r.reason}`)
+  })
+  return values
+}

package/src/build/build-icons.ts

@@ -0,0 +1,69 @@
+// lucide-react icons rendered at build time (L23). The compiler records an `IconRequest` for every
+// icon it could inline; here each is rendered with `react-dom/server` (the app's own React and the
+// installed lucide-react, so the markup is exactly what React would produce for that version),
+// dynamic props rendered as sentinels the compiler lowers back to attributes. The result goes back
+// with the next compile (`iconSvgs`). An icon that cannot be rendered keeps the L22 island.
+import type { Compiled } from './compile'
+
+interface Request {
+  key: string
+  source: string
+  export: string
+  props: Record<string, unknown>
+  dynamic: string[]
+  provider: Record<string, unknown>
+  line: number
+  col: number
+}
+
+const sentinel = (name: string) => `__BRUST_ICON_${name}__`
+
+export interface IconMarkup {
+  /** Dynamic props rendered as sentinels. */
+  svg: string
+  /** The same icon with the dynamic props absent: React's default for an `undefined` prop. */
+  base: string
+}
+
+export async function renderIcons(compiled: Map<string, Compiled>, appRoot: string, log: (s: string) => void): Promise<Record<string, IconMarkup>> {
+  const all: { c: Compiled; r: Request }[] = []
+  for (const c of compiled.values()) for (const r of (c.ir.icon_requests ?? []) as Request[]) all.push({ c, r })
+  if (all.length === 0) return {}
+  // One React for the icon module and the renderer: both resolve from the app.
+  const resolveFrom = (spec: string, from: string) => Bun.resolveSync(spec, from)
+  const server = await import(resolveFrom('react-dom/server', appRoot))
+  const react = await import(resolveFrom('react', appRoot))
+  const out: Record<string, IconMarkup> = {}
+  const mods = new Map<string, Record<string, unknown>>()
+  for (const { c, r } of all) {
+    const where = `${c.file.slice(appRoot.length + 1)}:${r.line}:${r.col}`
+    try {
+      let mod = mods.get(r.source)
+      if (!mod) {
+        mod = (await import(resolveFrom(r.source, appRoot))) as Record<string, unknown>
+        mods.set(r.source, mod)
+      }
+      const Comp = mod[r.export] as unknown
+      if (typeof Comp !== 'function' && (typeof Comp !== 'object' || Comp === null)) throw new Error(`${r.source} has no export \`${r.export}\``)
+      const render = (dynamic: Record<string, unknown>): string => {
+        let el = react.createElement(Comp, { ...r.props, ...dynamic })
+        if (Object.keys(r.provider).length > 0) {
+          const Provider = mod.LucideProvider
+          if (!Provider) throw new Error(`${r.source} has no LucideProvider (the installed lucide-react predates it)`)
+          el = react.createElement(Provider, r.provider, el)
+        }
+        const markup: string = server.renderToStaticMarkup(el)
+        if (!markup.startsWith('<svg') || !markup.endsWith('</svg>')) throw new Error('it does not render an <svg>')
+        if (/NaN|undefined/.test(markup)) throw new Error('a dynamic prop is combined with another (for example absoluteStrokeWidth with a dynamic size)')
+        return markup
+      }
+      const svg = render(Object.fromEntries(r.dynamic.map((d) => [d, sentinel(d)])))
+      for (const d of r.dynamic) if (!svg.includes(sentinel(d))) throw new Error(`prop \`${d}\` does not reach the markup`)
+      // `size={undefined}` renders React's default (or the provider's value): render that too.
+      out[r.key] = { svg, base: r.dynamic.length > 0 ? render({}) : svg }
+    } catch (e) {
+      log(`warning icon-render ${where} ${r.export} from ${r.source} stays a React island: ${e instanceof Error ? e.message : String(e)}`)
+    }
+  }
+  return out
+}

package/src/build/bundle.ts

@@ -12,11 +12,19 @@ import { builtinModules } from 'node:module'
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import type { BunPlugin } from 'bun'
 import type { Compiled } from './compile'
+import { cssPlugin } from './css'
 import { BuildError } from './errors'
 
 const REACT_EXTERNALS = ['react', 'react/*', 'react-dom', 'react-dom/*']
-/** Production React (and the production JSX transform: `react/jsx-runtime`, never `jsxDEV`). */
-export const PRODUCTION = { 'process.env.NODE_ENV': JSON.stringify('production') }
+/** Production React (and the production JSX transform: `react/jsx-runtime`, never `jsxDEV`). `brust dev` builds set
+ * `BRUST_BUILD_MODE=development` for readable errors and hydration diffs (R13.4); `brust build` never does. */
+export const PRODUCTION: Record<string, string> = { 'process.env.NODE_ENV': JSON.stringify(process.env.BRUST_BUILD_MODE === 'development' ? 'development' : 'production'), __BRUST_DEV__: 'false' }
+
+/** `brust build --dev` (L14, R14.3): the client runtime exposes its live instances on a dev global. `__BRUST_DEV__` is a
+ * define, `false` in every other build, so the minifier removes the dev code from production bundles. */
+export function setDevBuild(dev: boolean): void {
+  PRODUCTION.__BRUST_DEV__ = dev ? 'true' : 'false'
+}
 
 const matchesExternal = (spec: string, external: string[]) =>
   // A trailing `*` is a prefix (`elysia/*`, `node:*`, `cloudflare:*`): the generated CF entry imports `cloudflare:workers`.
@@ -34,6 +42,8 @@ export interface BrowserCtx {
   serverOnly: string[]
   /** Real paths of server-only files (the actions entry, R8): a browser import of one is refused. */
   serverFiles?: string[]
+  /** L19: CSS Module class maps for `cssPlugin` (absent: no CSS was built). */
+  cssMaps?: Map<string, Record<string, string>>
 }
 
 /** Resolution for staged artifacts (`importer` = a staged file registered in `sourceOf`): relative
@@ -146,7 +156,7 @@ function serverOnlyPlugin(ctx: BrowserCtx, violations: string[]): BunPlugin {
 }
 
 const hex = (s: string) => createHash('sha256').update(s).digest('hex').slice(0, 10)
-const write = (file: string, text: string) => {
+export const write = (file: string, text: string) => {
   mkdirSync(dirname(file), { recursive: true })
   writeFileSync(file, text)
 }
@@ -166,7 +176,7 @@ async function browserBuild(
   try {
     res = await Bun.build({
       ...config,
-      plugins: [serverOnlyPlugin(ctx, violations), ...(config.plugins ?? [])],
+      plugins: [serverOnlyPlugin(ctx, violations), cssPlugin(ctx.cssMaps ?? new Map()), ...(config.plugins ?? [])],
       target: 'browser',
       format: 'esm',
       minify: true,
@@ -262,13 +272,22 @@ export async function buildClientChunks(dist: string, compiled: Map<string, Comp
 }
 
 /** Registers a written artifact (by its path and its real path: the importer Bun reports). */
-function stage(sourceOf: SourceOf, file: string, c: Compiled): void {
+export function stage(sourceOf: SourceOf, file: string, c: Compiled): void {
   sourceOf.set(file, c.file)
   sourceOf.set(realpathSync(file), c.file)
 }
 
 const isReact = (c: Compiled) => typeof c.ir.tier === 'object' && c.ir.tier !== null && 'React' in c.ir.tier
 
+/** The `import` line that brings a react-tier component's code in as `local`: its own module, or
+ * for a package export (L22) the export itself. */
+export function componentImport(c: Compiled, local: string): string {
+  const ext = c.ir.external
+  if (!ext) return `import ${local} from ${JSON.stringify(c.file)}`
+  const from = JSON.stringify(ext.source)
+  return ext.export === 'default' ? `import ${local} from ${from}` : `import { ${JSON.stringify(ext.export).replace(/^"|"$/g, '')} as ${local} } from ${from}`
+}
+
 /** The island entry of a react-tier component: registers `(host, props) => …` under its id. A
  * `client_only` component was never server-rendered (its host is empty), so it mounts with
  * `createRoot`; hydrating it would fail (React #418). Everything else hydrates the SSR markup. */
@@ -278,7 +297,7 @@ export function islandShim(c: Compiled): string {
     ? ['createRoot', `createRoot(host, { identifierPrefix: ${JSON.stringify(c.id)} }).render(createElement(Comp, props))`]
     : ['hydrateRoot', `hydrateRoot(host, createElement(Comp, props), { identifierPrefix: ${JSON.stringify(c.id)} })`]
   return (
-    `import { ${api} } from 'react-dom/client'\nimport { createElement } from 'react'\nimport Comp from ${JSON.stringify(c.file)}\n` +
+    `import { ${api} } from 'react-dom/client'\nimport { createElement } from 'react'\n${componentImport(c, 'Comp')}\n` +
     `;((globalThis as any).__brustIslands ||= []).push([${JSON.stringify(c.id)}, (host: Element, props: any) => { ${mount} }])\n` +
     `;(globalThis as any).__brustIslandReady?.()\n`
   )
@@ -335,8 +354,8 @@ const ACTIONS_EXTERNALS = [...JOBS_EXTERNALS, 'elysia', 'elysia/*', '@elysia/*']
 
 /** `dist/actions.js` (M3-F E1): the actions entry for the worker (`target: 'bun'`). No `define`: Elysia
  * and app code read NODE_ENV at runtime (run.ts sets production). */
-export async function buildActions(dist: string, entry: string): Promise<string> {
-  const res = await Bun.build({ entrypoints: [entry], target: 'bun', format: 'esm', external: ACTIONS_EXTERNALS, plugins: [workerStorePlugin] })
+export async function buildActions(dist: string, entry: string, cssMaps: Map<string, Record<string, string>> = new Map()): Promise<string> {
+  const res = await Bun.build({ entrypoints: [entry], target: 'bun', format: 'esm', external: ACTIONS_EXTERNALS, plugins: [cssPlugin(cssMaps), workerStorePlugin] })
   if (!res.success) throw new BuildError('bundle', `actions: ${res.logs.map(String).join('\n')}`)
   write(join(dist, 'actions.js'), await res.outputs[0]!.text())
   return 'actions.js'
@@ -344,8 +363,8 @@ export async function buildActions(dist: string, entry: string): Promise<string>
 
 /** `dist/cache-adapter.js` (cache adapters R8): a custom adapter module for the worker (`target: 'bun'`), with
  * the actions externals so it shares the app's dependencies. */
-export async function buildCacheAdapter(dist: string, entry: string): Promise<string> {
-  const res = await Bun.build({ entrypoints: [entry], target: 'bun', format: 'esm', external: ACTIONS_EXTERNALS })
+export async function buildCacheAdapter(dist: string, entry: string, cssMaps: Map<string, Record<string, string>> = new Map()): Promise<string> {
+  const res = await Bun.build({ entrypoints: [entry], target: 'bun', format: 'esm', external: ACTIONS_EXTERNALS, plugins: [cssPlugin(cssMaps)] })
   if (!res.success) throw new BuildError('bundle', `cache adapter: ${res.logs.map(String).join('\n')}`)
   write(join(dist, 'cache-adapter.js'), await res.outputs[0]!.text())
   return 'cache-adapter.js'
@@ -353,7 +372,14 @@ export async function buildCacheAdapter(dist: string, entry: string): Promise<st
 
 /** `dist/jobs.js` (`target: 'bun'`, React and `@brust/core` external): default export
  * `{ [componentId]: { precompute?, ssr? } }`; `ssr` only for react-tier, non-client_only components. */
-export async function buildJobs(dist: string, compiled: Map<string, Compiled>, sourceOf: SourceOf, appRoot: string, stores: string[] = []): Promise<void> {
+export async function buildJobs(
+  dist: string,
+  compiled: Map<string, Compiled>,
+  sourceOf: SourceOf,
+  appRoot: string,
+  stores: string[] = [],
+  cssMaps: Map<string, Record<string, string>> = new Map(),
+): Promise<void> {
   const imports: string[] = ["import { createElement } from 'react'", "import { renderToString } from 'react-dom/server'"]
   const entries: string[] = []
   const storePaths = [...new Set(stores)].sort()
@@ -374,7 +400,7 @@ export async function buildJobs(dist: string, compiled: Map<string, Compiled>, s
       fns.push(`precompute: j${n}.precompute`)
     }
     if (isReact(c) && !c.ir.tier.React.client_only) {
-      imports.push(`import C${n} from ${JSON.stringify(c.file)}`)
+      imports.push(componentImport(c, `C${n}`))
       // Ruling 2bf3775a (R1): the island's component id prefixes React's useId on BOTH sides
       // (the shim's hydrateRoot passes the same prefix), so ids differ across islands.
       fns.push(`ssr: (props: any) => renderToString(createElement(C${n}, props), { identifierPrefix: ${JSON.stringify(c.id)} })`)
@@ -390,7 +416,7 @@ export async function buildJobs(dist: string, compiled: Map<string, Compiled>, s
     format: 'esm',
     define: PRODUCTION,
     external: JOBS_EXTERNALS,
-    plugins: [workerStorePlugin, sourceDirPlugin(sourceOf, appRoot, JOBS_EXTERNALS)],
+    plugins: [cssPlugin(cssMaps), workerStorePlugin, sourceDirPlugin(sourceOf, appRoot, JOBS_EXTERNALS)],
   })
   if (!res.success) throw new BuildError('bundle', `jobs: ${res.logs.map(String).join('\n')}`)
   write(join(dist, 'jobs.js'), await res.outputs[0]!.text())

package/src/build/cf-assets.ts

@@ -21,8 +21,10 @@ export function isHashed(file: string): boolean {
 
 const segOk = (s: string) => s !== '' && !s.startsWith('.') && SEG.test(s)
 
-/** `client/<file>.js|.css`: `is_safe_island_filename` / `is_safe_css_filename`. */
-const clientOk = (f: string) => segOk(f) && !f.includes('..') && (f.endsWith('.js') || f.endsWith('.css'))
+/** `client/<file>.js|.css`: `is_safe_island_filename` / `is_safe_css_filename`, plus the fonts and images a
+ * stylesheet references (`is_safe_client_asset_filename`, L19). */
+const CLIENT_EXT = /\.(js|css|woff2|woff|ttf|otf|eot|png|jpg|jpeg|gif|webp|avif|svg|ico)$/
+const clientOk = (f: string) => segOk(f) && !f.includes('..') && CLIENT_EXT.test(f)
 
 function walk(dir: string, rel = ''): string[] {
   const out: string[] = []

package/src/build/cf-entry.ts

@@ -28,6 +28,8 @@ export interface CfEntryInput {
   entry: string
   jobsEntry: string
   actionsEntry: string | null
+  /** L16: no pages: the routes module and the jobs module are not imported; the handlers serve an empty route table. */
+  actionsOnly?: boolean
   prefix: string
   manifestPath: string
   templatesPath: string
@@ -41,16 +43,18 @@ export function cfEntrySource(i: CfEntryInput): string {
   const q = JSON.stringify
   const actions = i.actionsEntry !== null
   const c = i.cache ?? null
+  const pages = i.actionsOnly !== true
   return `${[
     '// generated by `brust build --target cloudflare` — do not edit (M4-CF spec §4)',
-    `import * as R from ${q(i.entry)}`,
-    `import J, * as JM from ${q(i.jobsEntry)}`,
+    ...(pages ? [`import * as R from ${q(i.entry)}`, `import J, * as JM from ${q(i.jobsEntry)}`] : []),
     ...(actions ? [`import A from ${q(i.actionsEntry)}`] : []),
     `import M from ${q(i.manifestPath)}`,
     `import T from ${q(i.templatesPath)}`,
     `import { fetchInScope, flattenRoutes, jsonCall, makeHandlers, noActions } from "@brust/core/server-handlers"`,
     ...(actions ? ['import { mountActions } from "@brust/core/server-handlers/actions"'] : []),
-    'const h = makeHandlers({ leaves: flattenRoutes(R.routes ?? R.default).leaves, jobs: J, manifest: M, stores: JM.stores ?? {} })',
+    pages
+      ? 'const h = makeHandlers({ leaves: flattenRoutes(R.routes ?? R.default).leaves, jobs: J, manifest: M, stores: JM.stores ?? {} })'
+      : 'const h = makeHandlers({ leaves: [], jobs: {}, manifest: M, stores: {} })',
     ...(actions ? [`const app = mountActions(A, ${q(i.prefix)}).compile() // startup-phase compile (R9)`] : []),
     'export const loader = jsonCall(h.loader)',
     'export const jobs = jsonCall(h.jobs)',

package/src/build/cf-wrangler.ts

@@ -20,6 +20,8 @@ export interface MergeOpts {
   /** worker-build entry, relative to `worker/` (core-cf `brust.main`) */
   main: string
   version: string
+  /** L16: an actions-only Worker has no Static Assets (and no ASSETS binding). */
+  noAssets?: boolean
 }
 
 const OWNED = ['main', 'assets', 'compatibility_date', 'no_bundle', 'find_additional_modules', 'base_dir', 'rules', 'build', 'site']
@@ -106,7 +108,7 @@ export function mergeWrangler(user: UserWrangler, o: MergeOpts): { config: Json;
     ...(name !== undefined ? { name } : {}),
     main: `worker/${o.main}`,
     compatibility_date: o.compatibilityDate,
-    assets: { directory: 'assets', binding: 'ASSETS', run_worker_first: false, html_handling: 'none', not_found_handling: 'none' },
+    ...(o.noAssets ? {} : { assets: { directory: 'assets', binding: 'ASSETS', run_worker_first: false, html_handling: 'none', not_found_handling: 'none' } }),
     ...Object.fromEntries(Object.entries(rest).filter(([k]) => k !== 'name')),
   }
   return { config, warnings }