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

package/src/build/cloudflare.ts

@@ -14,6 +14,7 @@ import { type CacheNeed, mergeWrangler, readUserWrangler, renderWrangler, type U
 import { type CloudflareBuildConfig, CF_MIN_COMPAT_DATE } from './config'
 import { PRODUCTION, type SourceOf, sourceDirPlugin } from './bundle'
 import type { Compiled } from './compile'
+import { cssPlugin } from './css'
 import { BuildError } from './errors'
 import type { CacheRecord } from './manifest'
 import { BUILTINS as CACHE_BUILTINS } from '../cache-adapter/load'
@@ -76,10 +77,14 @@ export interface CfBuildCtx {
   manifest: { components: Record<string, { template: string }>; actions?: { prefix: string; maxBodyBytes: number; maxResponseBytes?: number; crossSite?: 'reject' | 'allow' } | null; cache?: CacheRecord }
   sourceOf: SourceOf
   actionsEntry: string | null
+  /** L16 R16.3: an actions-only Worker: no pages (no routes entry, no jobs, no templates), no Static Assets. */
+  actionsOnly?: boolean
   /** A custom cache adapter's source module (absolute). */
   cacheModule?: string | null
   /** `[cache] get_timeout_ms` as written (absent → the Workers default, 100). */
   cacheGetTimeoutMs?: number
+  /** L19: CSS Module class maps (the worker reads the same map as the browser). */
+  cssMaps?: Map<string, Record<string, string>>
   log: (s: string) => void
 }
 
@@ -124,7 +129,7 @@ function cfAlias(alias: Record<string, string>, sourceOf: SourceOf): BunPlugin {
 /** The CF bundle's stand-in for the napi addon (`native.ts` `require('../native/index.js')`, R8): every call
  * fails loudly, since a Worker has no addon. */
 function cfNativeStub(handlersPath: string): BunPlugin {
-  const names = ['startServer', 'registerWorker', 'untilReady', 'beginDrain', 'cacheInvalidate', 'cacheStats', 'localAddr', 'planJobs', 'takeFetchBody', 'putFetchReply', 'cacheReplay', 'cacheL2Count', 'cacheClear']
+  const names = ['startServer', 'registerWorker', 'untilReady', 'beginDrain', 'cacheInvalidate', 'cacheStats', 'localAddr', 'planJobs', 'planJobsBuf', 'takeFetchBody', 'putFetchReply', 'cacheReplay', 'cacheL2Count', 'cacheClear']
   return {
     name: 'brust-cf-native',
     setup(b) {
@@ -166,7 +171,7 @@ function cfEntryCache(c: CacheRecord, customModule: string | null) {
 }
 
 /** R2/R10: which Cloudflare bindings the configured cache needs (`[cache.cloudflare]` keys land in the adapter's options), or null. */
-export function cacheNeeds(c: CacheRecord | undefined): CacheNeed | null {
+export function cacheNeeds(c: Pick<CacheRecord, 'adapter' | 'broadcast' | 'options' | 'broadcastOptions'> | undefined): CacheNeed | null {
   if (!c) return null
   const opt = (o: Record<string, unknown> | undefined, k: string) => (typeof o?.[k] === 'string' ? (o[k] as string) : undefined)
   const all = [c.options, c.broadcastOptions]
@@ -191,7 +196,7 @@ plugin({
 const m = await import(${JSON.stringify(app)})
 const bad = []
 for (const k of ['loader', 'jobs', 'action', 'install']) if (typeof m[k] !== 'function') bad.push(k + ' is not a function')
-if (typeof m.MANIFEST !== 'string' || JSON.parse(m.MANIFEST).version !== 1) bad.push('MANIFEST.version !== 1')
+if (typeof m.MANIFEST !== 'string' || JSON.parse(m.MANIFEST).version !== 2) bad.push('MANIFEST.version !== 2')
 if (typeof m.CONFIG !== 'string' || JSON.parse(m.CONFIG).abi !== 1) bad.push('CONFIG.abi !== 1')
 if (typeof m.TEMPLATES !== 'object' || m.TEMPLATES === null) bad.push('TEMPLATES is not an object')
 const r = await m.loader('{}')
@@ -247,11 +252,11 @@ export async function buildCloudflare(out: string, ctx: CfBuildCtx, p: CfPrepare
   const jobsEntry = join(out, '.stage', 'jobs.ts')
   writeFileSync(
     entryPath,
-    cfEntrySource({ entry: ctx.entry, jobsEntry, actionsEntry: a ? ctx.actionsEntry : null, prefix: a?.prefix ?? '', manifestPath: join(out, 'manifest.json'), templatesPath, config, cache: entryCache, doClass }),
+    cfEntrySource({ entry: ctx.entry, jobsEntry, actionsOnly: ctx.actionsOnly === true, actionsEntry: a ? ctx.actionsEntry : null, prefix: a?.prefix ?? '', manifestPath: join(out, 'manifest.json'), templatesPath, config, cache: entryCache, doClass }),
   )
   // Bare imports of the generated files resolve from the app root (an --out-dir outside the app has no node_modules above it).
   // (registered by absolute AND real path: the bundler reports the real one, e.g. /private/var on macOS)
-  for (const f of [entryPath, jobsEntry]) {
+  for (const f of ctx.actionsOnly ? [entryPath] : [entryPath, jobsEntry]) {
     ctx.sourceOf.set(f, ctx.entry)
     ctx.sourceOf.set(realpathSync(f), ctx.entry)
   }
@@ -269,7 +274,7 @@ export async function buildCloudflare(out: string, ctx: CfBuildCtx, p: CfPrepare
     define: PRODUCTION,
     minify: false,
     external: ['node:*', 'cloudflare:*', glueSpec],
-    plugins: [cfGuard(ctx.appRoot, violations), cfAlias(p.cfg.alias, ctx.sourceOf), cfNativeStub(Bun.resolveSync('@brust/core/server-handlers', ctx.appRoot)), cfStorePlugin(ctx.appRoot), sourceDirPlugin(ctx.sourceOf, ctx.appRoot, ['node:*', 'cloudflare:*'])],
+    plugins: [cssPlugin(ctx.cssMaps ?? new Map()), cfGuard(ctx.appRoot, violations), cfAlias(p.cfg.alias, ctx.sourceOf), cfNativeStub(Bun.resolveSync('@brust/core/server-handlers', ctx.appRoot)), cfStorePlugin(ctx.appRoot), sourceDirPlugin(ctx.sourceOf, ctx.appRoot, ['node:*', 'cloudflare:*'])],
   })
   if (violations.length > 0) throw new BuildError('cf-unsupported', `${[...new Set(violations)].join('\n')}\nthese modules do not exist on Cloudflare Workers; swap them with [cloudflare] alias`)
   if (!res.success) throw new BuildError('bundle', `cloudflare: ${res.logs.map(String).join('\n')}`)
@@ -280,8 +285,8 @@ export async function buildCloudflare(out: string, ctx: CfBuildCtx, p: CfPrepare
   mkdirSync(appDir, { recursive: true })
   writeFileSync(appFile, await js[0]!.text())
 
-  const assets = layoutAssets(out, cfDir, p.coreVersion)
-  warnings.push(...assets.warnings)
+  // An actions-only Worker has no pages and so no Static Assets (no `assets` binding in its wrangler.jsonc either).
+  if (!ctx.actionsOnly) warnings.push(...layoutAssets(out, cfDir, p.coreVersion).warnings)
   const compatibilityDate = p.cfg.compatibilityDate ?? p.core.meta.compatibilityDate
   if (compatibilityDate < CF_MIN_COMPAT_DATE) throw new BuildError('config', `compatibility_date ${compatibilityDate} is older than ${CF_MIN_COMPAT_DATE}`)
   if (doClass) {
@@ -292,7 +297,7 @@ export async function buildCloudflare(out: string, ctx: CfBuildCtx, p: CfPrepare
       `// generated by brust build --target cloudflare (do not edit)\nexport * from "./${p.core.meta.main}"\nexport { default } from "./${p.core.meta.main}"\nexport { BrustCacheDO } from "./${appRel}"\n`,
     )
   }
-  const merged = mergeWrangler(p.user, { appRoot: ctx.appRoot, cfDir: join(ctx.dist, 'cf'), name: p.cfg.name, pkgName: p.pkgName, compatibilityDate, main: doClass ? 'main.js' : p.core.meta.main, version: p.coreVersion })
+  const merged = mergeWrangler(p.user, { appRoot: ctx.appRoot, cfDir: join(ctx.dist, 'cf'), name: p.cfg.name, pkgName: p.pkgName, compatibilityDate, main: doClass ? 'main.js' : p.core.meta.main, version: p.coreVersion, ...(ctx.actionsOnly ? { noAssets: true } : {}) })
   warnings.push(...merged.warnings)
   writeFileSync(join(cfDir, 'wrangler.jsonc'), renderWrangler(merged.config))
 

package/src/build/compile.ts

@@ -2,7 +2,8 @@
 // `compileTree` (analysis + lowering of its whole tree). `Err` = build error; fallback and
 // warning diagnostics are logged; `outlet-outside-layout` is raised here (contract 5).
 // A component several trees reach keeps one compile, chosen by role, not by route order (F75).
-import { relative } from 'node:path'
+import { realpathSync } from 'node:fs'
+import { relative, sep } from 'node:path'
 import { type CompiledComponent, type CompiledTree, compileTree } from '../../native/index.js'
 import type { FlatRoute, Route } from '../routes'
 import { BuildError } from './errors'
@@ -17,13 +18,22 @@ export type ComponentIR = Record<string, any> & {
   tier: any
   // biome-ignore lint/suspicious/noExplicitAny: IR JSON
   jobs: any[]
-  instances: { child_id: string; k: number; loops: (string | null)[]; props: Record<string, string | null> }[]
+  instances: {
+    child_id: string
+    k: number
+    loops: (string | null)[]
+    props: Record<string, string | null>
+    literals?: Record<string, unknown>
+    exprs?: Record<string, string>
+  }[]
   use_id_slots: number
   uses_outlet: boolean
   needs_worker: boolean
   /** `useStore(handle)` bindings (`decls.rs` `StoreUse`); `resolved` = `StoreRef`, `null` when
    * unresolved (the component falls back). `module` is root-relative (C3). */
   stores?: { handle: string; resolved: { name: string; module: string } | null }[]
+  /** A package export rendered as a React island (L22): `source` is then not a file. */
+  external?: { source: string; export: string }
 }
 
 export interface Compiled {
@@ -33,7 +43,11 @@ export interface Compiled {
   ir: ComponentIR
   jinja: string
   serverTs?: string
+  /** Build-time evaluation module (L2): one thunk per `ir.build_eval` slot. */
+  evalTs?: string
   clientJs?: string
+  /** The compiler's diagnostics for this component (`dev.json`, L14). */
+  diagnostics?: { class: string; rule: string; message: string; line: number; col: number; remediation: string }[]
 }
 
 type Diag = NonNullable<CompiledTree['error']>
@@ -78,11 +92,25 @@ export function compileApp(opts: {
   appRoot: string
   leaves: FlatRoute[]
   componentFile: Map<Function, string>
+  /** Why a Component the scan saw has no file (named export only, outside the root); optional. */
+  componentIssue?: Map<Function, string>
   runtimeImport: string
   serverOnly: string[]
+  /** L20: every CSS Module's class map by absolute source path; `styles.x` folds to the literal class. */
+  cssMaps?: Map<string, Record<string, string>>
   log: (s: string) => void
+  /** SVG markup the build rendered for lucide icon requests (L23), by `ir.icon_requests[].key`. */
+  iconSvgs?: Record<string, { svg: string; base: string }>
+  /** The compile after icons were rendered (even if none could be): icons still components are judged as islands. */
+  iconsFinal?: boolean
+  /** Values the build computed for `ir.build_eval` slots, by key (L2): the slots become literals. */
+  slotValues?: Record<string, unknown>
 }): { compiled: Map<string, Compiled>; routeComponent: Map<string, string> } {
   const { appRoot, leaves, componentFile } = opts
+  const iconSvgsJson = opts.iconsFinal ? JSON.stringify({ final: true, svgs: opts.iconSvgs ?? {} }) : undefined
+  const slotValuesJson = opts.slotValues && Object.keys(opts.slotValues).length > 0 ? JSON.stringify(opts.slotValues) : undefined
+  // The Rust side keys each map by its path relative to the app root (`/`-separated), like an import resolves.
+  const cssModules = Object.fromEntries([...(opts.cssMaps ?? [])].map(([abs, map]) => [relative(realpathSync(appRoot), abs).split(sep).join('/'), map]))
   const seen = new Map<string, Seen>()
   const rootIdOfFile = new Map<string, string>()
   const routeComponent = new Map<string, string>()
@@ -95,12 +123,12 @@ export function compileApp(opts: {
     if (!file)
       throw new BuildError(
         'component-source',
-        `${route.Component!.name || '(anonymous)'} is not a default import of a .tsx file (route ${routeId})`,
+        `${opts.componentIssue?.get(route.Component!) ?? `${route.Component!.name || '(anonymous)'} is not the default export of a .tsx file in the import graph`} (route ${routeId})`,
       )
     let rootId = rootIdOfFile.get(file)
     if (!rootId) {
       const rel = relative(appRoot, file)
-      const tree = compileTree(rel, appRoot, opts.runtimeImport, opts.serverOnly)
+      const tree = compileTree(rel, appRoot, opts.runtimeImport, opts.serverOnly, slotValuesJson, cssModules, iconSvgsJson)
       if (tree.error) throw new BuildError(tree.error.rule, `${where(rel, tree.error)} ${tree.error.message}`)
       for (const [i, c] of tree.components.entries()) {
         // A lowering Error that came back as a diagnostic is a build error too (contract 9).
@@ -132,9 +160,18 @@ export function compileApp(opts: {
       ir,
       jinja: c.jinja,
       serverTs: c.serverTs,
+      evalTs: c.evalTs,
       clientJs: c.clientJs,
+      diagnostics: c.diagnostics.map((d) => ({ class: d.class, rule: d.rule, message: d.message, line: d.line, col: d.col, remediation: d.remediation })),
     })
   }
+  // A package export has no file of its own: bare imports in its island entries resolve from a
+  // component that uses it (the first one in build order).
+  for (const c of compiled.values()) {
+    if (!c.ir.external) continue
+    const user = [...compiled.values()].find((p) => !p.ir.external && (p.ir.children ?? []).some((ref: { id: string | null }) => ref.id === c.id))
+    c.file = user?.file ?? c.file
+  }
   for (const [routeId, route] of nodes) {
     const rootId = routeComponent.get(routeId)!
     if (compiled.get(rootId)!.ir.uses_outlet && !route.children)

package/src/build/config.ts

@@ -4,13 +4,16 @@
 // `server_only` is the app config `serverOnly` of the compiler spec (§8.2): the compiler refuses
 // such an import in client code, and every browser bundle refuses to include it.
 import { join } from 'node:path'
-import { DEFAULT_ACTION_PREFIX, DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_RESPONSE_BYTES, MAX_ACTION_BYTES, prefixError } from '../actions/prefix'
+import { ACTION_CREDENTIALS, type ActionCredentials, DEFAULT_ACTION_PREFIX, DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_RESPONSE_BYTES, MAX_ACTION_BYTES, baseUrlError, prefixError } from '../actions/prefix'
 import { ADAPTER_NAMES, BUILTINS, installHint } from '../cache-adapter/load'
 import { BuildError } from './errors'
 
 // [actions] (opt-in, ruling R6): present table => actions on. Both byte caps cross napi as u32 (F82: 1..64 MiB / 256 KiB..64 MiB).
 //   [actions]
 //   entry = "actions.ts"   prefix = "/_brust/action"   max_body_bytes = 1048576  max_response_bytes = 8388608   cross_site = "reject" | "allow" (F87)
+//   base_url = "https://api.example.com"  credentials = "same-origin" | "include" | "omit"   (L16: the browser client's target; runtime settings, validated here too)
+// `prefix = "/"` is accepted only for an actions-only build (L16 R16.4).
+// `ACTION_INLINE_BODY_BYTES` (Rust): the inline/heap threshold of an action body, independent of the response slot size (`slotBytes`).
 const MIN_RESPONSE_BYTES = 262_144
 
 export interface ActionsBuildConfig {
@@ -19,6 +22,11 @@ export interface ActionsBuildConfig {
   maxBodyBytes: number
   maxResponseBytes: number
   crossSite: 'reject' | 'allow'
+  /** `[actions] base_url`; with no actions file present the build is page-only (L16 R16.4b). */
+  baseUrl: string | undefined
+  credentials: ActionCredentials
+  /** `entry` was written in brust.toml (a missing file is then an error, never a page-only build). */
+  entryExplicit: boolean
 }
 
 // [cloudflare] (M4-CF; only read by `--target cloudflare`, validated always so errors surface early):
@@ -66,6 +74,8 @@ export interface BuildConfig {
   actions: ActionsBuildConfig | null
   cloudflare: CloudflareBuildConfig | null
   cache: CacheBuildConfig | null
+  /** `[css] global` (L19, R19.1): app-root-relative stylesheets every route links first, in order. */
+  cssGlobal: string[]
 }
 
 const isTable = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v)
@@ -232,7 +242,7 @@ function resolveAlias(file: string, appRoot: string, p: string): string {
   }
 }
 
-function parseActions(file: string, raw: unknown): ActionsBuildConfig | null {
+function parseActions(file: string, raw: unknown, actionsOnly: boolean): ActionsBuildConfig | null {
   if (raw === undefined) return null
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) throw new BuildError('config', `${file}: [actions] must be a table`)
   const t = raw as Record<string, unknown>
@@ -243,7 +253,8 @@ function parseActions(file: string, raw: unknown): ActionsBuildConfig | null {
   }
   let prefix = DEFAULT_ACTION_PREFIX
   if (t.prefix !== undefined) {
-    const why = prefixError(t.prefix)
+    // `/` is the prefix of an actions-only deployment; a page-only build (base_url, no local app) may name it too.
+    const why = prefixError(t.prefix, actionsOnly || t.base_url !== undefined)
     if (why) throw new BuildError('config', `${file}: actions.prefix ${why}`)
     prefix = t.prefix as string
   }
@@ -266,15 +277,39 @@ function parseActions(file: string, raw: unknown): ActionsBuildConfig | null {
     if (t.cross_site !== 'reject' && t.cross_site !== 'allow') throw new BuildError('config', `${file}: actions.cross_site must be "reject" or "allow"`)
     crossSite = t.cross_site
   }
-  return { entry, prefix, maxBodyBytes, maxResponseBytes, crossSite }
+  let baseUrl: string | undefined
+  if (t.base_url !== undefined) {
+    const why = baseUrlError(t.base_url)
+    if (why) throw new BuildError('config', `${file}: actions.base_url ${why}`)
+    baseUrl = t.base_url as string
+  }
+  let credentials: ActionCredentials = 'same-origin'
+  if (t.credentials !== undefined) {
+    if (typeof t.credentials !== 'string' || !ACTION_CREDENTIALS.includes(t.credentials as ActionCredentials))
+      throw new BuildError('config', `${file}: actions.credentials must be one of ${ACTION_CREDENTIALS.join(', ')} (got ${JSON.stringify(t.credentials)})`)
+    credentials = t.credentials as ActionCredentials
+  }
+  return { entry, prefix, maxBodyBytes, maxResponseBytes, crossSite, baseUrl, credentials, entryExplicit: t.entry !== undefined }
 }
 
 const DEFAULT_ENTRY = 'actions.ts'
 
-export async function loadBuildConfig(appRoot: string): Promise<BuildConfig> {
+/** `[css]`: only `global`, a list of `.css` files relative to the app root (checked to exist by the build). */
+function parseCss(file: string, raw: unknown): string[] {
+  if (raw === undefined) return []
+  if (!isTable(raw)) throw new BuildError('config', `${file}: [css] must be a table`)
+  for (const k of Object.keys(raw)) if (k !== 'global') throw new BuildError('config', `${file}: unknown key css.${k} (allowed: global)`)
+  const g = raw.global
+  if (g === undefined) return []
+  if (!Array.isArray(g) || g.some((p) => typeof p !== 'string' || !p.trim().endsWith('.css')))
+    throw new BuildError('config', `${file}: css.global must be an array of .css paths (relative to the app root)`)
+  return g.map((p: string) => p.trim())
+}
+
+export async function loadBuildConfig(appRoot: string, o: { actionsOnly?: boolean } = {}): Promise<BuildConfig> {
   const file = join(appRoot, 'brust.toml')
   const f = Bun.file(file)
-  if (!(await f.exists())) return { serverOnly: [], actions: null, cloudflare: null, cache: null }
+  if (!(await f.exists())) return { serverOnly: [], actions: null, cloudflare: null, cache: null, cssGlobal: [] }
   let parsed: unknown
   try {
     parsed = Bun.TOML.parse(await f.text())
@@ -282,15 +317,16 @@ export async function loadBuildConfig(appRoot: string): Promise<BuildConfig> {
     throw new BuildError('config', `failed to parse ${file}: ${(e as Error).message}`)
   }
   const root = (parsed ?? {}) as Record<string, unknown>
-  const actions = parseActions(file, root.actions)
+  const actions = parseActions(file, root.actions, o.actionsOnly === true)
   const cloudflare = parseCloudflare(file, appRoot, root.cloudflare)
   const cache = await parseCache(file, appRoot, root.cache)
+  const cssGlobal = parseCss(file, root.css)
   const build = root.build
-  if (build === undefined) return { serverOnly: [], actions, cloudflare, cache }
+  if (build === undefined) return { serverOnly: [], actions, cloudflare, cache, cssGlobal }
   if (build === null || typeof build !== 'object' || Array.isArray(build)) throw new BuildError('config', `${file}: [build] must be a table`)
   const so = (build as Record<string, unknown>).server_only
-  if (so === undefined) return { serverOnly: [], actions, cloudflare, cache }
+  if (so === undefined) return { serverOnly: [], actions, cloudflare, cache, cssGlobal }
   if (!Array.isArray(so) || so.some((p) => typeof p !== 'string' || p.trim() === ''))
     throw new BuildError('config', `${file}: build.server_only must be an array of non-empty strings`)
-  return { serverOnly: so.map((p: string) => p.trim().replace(/^\.\//, '')), actions, cloudflare, cache }
+  return { serverOnly: so.map((p: string) => p.trim().replace(/^\.\//, '')), actions, cloudflare, cache, cssGlobal }
 }

package/src/build/css.ts

@@ -0,0 +1,286 @@
+// CSS for `brust build` (gaps round L19, R19.1-R19.4): which stylesheets each route links, one
+// minified content-hashed `client/<stem>-<hex10>.css` per source file, the class maps of CSS
+// Modules, and the one plugin every JS build uses so no JS build ever emits CSS.
+//
+// - A route's CSS: `[css] global` first, then every `.css` import reachable from its chain files
+//   (root layout → page), depth-first in import order, first occurrence wins.
+// - CSS Modules: one in-process Bun.build of every source (a JS entry per file), so one set of class
+//   names serves the server (jobs.js), the browser chunks and the Cloudflare worker alike.
+// - Relative `url()` fonts and images are emitted next to the CSS as `client/<name>-<hex10>.<ext>`;
+//   absolute `/public/*` and `/_brust/*` stay as written.
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import type { BunPlugin } from 'bun'
+import type { FlatRoute } from '../routes'
+import { BuildError } from './errors'
+
+const hex = (b: string | Uint8Array) => createHash('sha256').update(b).digest('hex').slice(0, 10)
+const real = (p: string) => {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+const isCss = (p: string) => p.endsWith('.css')
+const isModule = (p: string) => p.endsWith('.module.css')
+/** A name the static rules serve (`[A-Za-z0-9_.-]`, no leading dot). */
+const safeName = (s: string) => s.replace(/[^A-Za-z0-9_.-]/g, '_').replace(/^\.+/, '_')
+
+/** The stylesheets one source file reaches through static and dynamic imports, in order, real paths. Source
+ * files outside node_modules are followed; a `.css` import (an app file or a package's CSS) is
+ * collected, never followed (its `@import`s are the CSS bundler's). */
+export class CssGraph {
+  private memo = new Map<string, string[]>()
+  private active = new Set<string>()
+  private transpilers = new Map<string, InstanceType<typeof Bun.Transpiler>>()
+
+  of(file: string): string[] {
+    const f = real(file)
+    const hit = this.memo.get(f)
+    if (hit) return hit
+    if (this.active.has(f)) return [] // an import cycle: the outer visit already lists what follows
+    this.active.add(f)
+    const out: string[] = []
+    const add = (c: string) => {
+      if (!out.includes(c)) out.push(c)
+    }
+    const loader = /\.(tsx|ts|jsx|js|mjs)$/.exec(f)?.[1]
+    let src = ''
+    try {
+      src = loader ? readFileSync(f, 'utf8') : ''
+    } catch {}
+    if (loader && src) {
+      const l = loader === 'mjs' ? 'js' : (loader as 'tsx' | 'ts' | 'jsx' | 'js')
+      let t = this.transpilers.get(l)
+      if (!t) this.transpilers.set(l, (t = new Bun.Transpiler({ loader: l })))
+      for (const imp of t.scanImports(src)) {
+        // A dynamic import() is walked too (review N4): its CSS is linked eagerly for the route, so a
+        // lazily loaded component is styled on first paint and its CSS Modules are built.
+        if (imp.kind !== 'import-statement' && imp.kind !== 'dynamic-import') continue
+        let dep: string
+        try {
+          dep = real(Bun.resolveSync(imp.path, dirname(f)))
+        } catch {
+          continue // unresolvable: the JS build reports it
+        }
+        if (isCss(dep)) add(dep)
+        else if (!dep.split(sep).includes('node_modules')) for (const c of this.of(dep)) add(c)
+      }
+    }
+    this.active.delete(f)
+    this.memo.set(f, out)
+    return out
+  }
+}
+
+/** R19.1: every route's ordered source stylesheets (real paths), by route id. `chainFiles` maps a leaf to
+ * its chain's component files, root layout first. */
+export function routeCssSources(leaves: FlatRoute[], chainFiles: (l: FlatRoute) => string[], globals: string[], graph = new CssGraph()): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  for (const leaf of leaves) {
+    const list: string[] = [...globals]
+    for (const file of chainFiles(leaf)) for (const c of graph.of(file)) if (!list.includes(c)) list.push(c)
+    out.set(leaf.id, list)
+  }
+  return out
+}
+
+/** `[css] global` resolved: each a `.css` file inside the app. */
+export function resolveGlobals(appRoot: string, globals: string[]): string[] {
+  return globals.map((g) => {
+    const abs = resolve(appRoot, g)
+    const rel = relative(appRoot, abs)
+    if (isAbsolute(g) || rel.startsWith('..') || isAbsolute(rel) || !existsSync(abs)) throw new BuildError('css', `css.global ${g} is not a file inside the app`)
+    return real(abs)
+  })
+}
+
+export interface CssBuild {
+  /** source (real path) → `client/<stem>-<hex10>.css`; absent when the file emits no CSS. */
+  file: Map<string, string>
+  /** `.module.css` source (real path) → its class map. */
+  maps: Map<string, Record<string, string>>
+}
+
+const CLASS = /\.(-?[_a-zA-Z][_a-zA-Z0-9-]*)/g
+
+/** The asset types `static_rules::is_safe_client_asset_filename` serves from `/_brust/client/` (review N1). */
+export const SERVED_ASSET_EXT = ['.woff2', '.woff', '.ttf', '.otf', '.eot', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.svg', '.ico']
+
+/** R19.2/R19.4: builds every source stylesheet (one JS entry each) into `<dist>/client/`. `minify`
+ * is off only for a development build (`brust dev`, review N3). */
+export async function buildCss(
+  dist: string,
+  sources: string[],
+  minify = true,
+  o: { appRoot?: string; log?: (s: string) => void } = {},
+): Promise<CssBuild> {
+  const file = new Map<string, string>()
+  const maps = new Map<string, Record<string, string>>()
+  if (sources.length === 0) return { file, maps }
+  const appRoot = o.appRoot ?? process.cwd()
+  const tw = tailwindUse(sources)
+  const plugins: BunPlugin[] = []
+  if (tw.using.length > 0) {
+    plugins.push(await loadTailwind(appRoot, tw.using[0]!))
+    if (tw.imports.length > 1)
+      o.log?.(
+        `[brust] warning tailwind @import "tailwindcss" is in ${tw.imports.length} files (${tw.imports.map((f) => relative(appRoot, f)).join(', ')}): each one ships the whole of Tailwind; import it once (e.g. app.css) and use @reference elsewhere`,
+      )
+  }
+  const stage = join(dist, '.stage', 'css')
+  mkdirSync(stage, { recursive: true })
+  const entries = sources.map((src, i) => {
+    const e = join(stage, `s${i}.js`)
+    writeFileSync(e, isModule(src) ? `export { default } from ${JSON.stringify(src)}\n` : `import ${JSON.stringify(src)}\n`)
+    return e
+  })
+  const res = await Bun.build({
+    entrypoints: entries,
+    target: 'browser',
+    format: 'esm',
+    minify,
+    naming: { entry: '[name]-[hash].[ext]', chunk: '[name]-[hash].[ext]', asset: '[name]-[hash].[ext]' },
+    external: ['/public/*', '/_brust/*'],
+    // L21: Tailwind's content detection scans the app (bun-plugin-tailwind reads `root`).
+    root: appRoot,
+    plugins,
+  })
+  if (!res.success) throw new BuildError('css', res.logs.map(String).join('\n'))
+  // Assets a stylesheet references (fonts, images): `<name>-<hex10>.<ext>`, references rewritten.
+  const rename = new Map<string, string>()
+  const assets: { name: string; bytes: Uint8Array }[] = []
+  const css = new Map<number, string>()
+  const js = new Map<number, string>()
+  const unserved: string[] = []
+  for (const o of res.outputs) {
+    const name = basename(o.path)
+    const entry = /^s(\d+)-[^-.]+\.(css|js)$/.exec(name)
+    if (entry) {
+      ;(entry[2] === 'css' ? css : js).set(Number(entry[1]), await o.text())
+      continue
+    }
+    const m = /^(.*)-[^-.]+(\.[^.]+)$/.exec(name)
+    if (!m) throw new BuildError('css', `unexpected output ${name}`)
+    const ext = m[2]!.toLowerCase()
+    if (!SERVED_ASSET_EXT.includes(ext)) {
+      unserved.push(name)
+      continue
+    }
+    const bytes = new Uint8Array(await o.arrayBuffer())
+    const to = `${safeName(m[1]!)}-${hex(bytes)}${ext}`
+    rename.set(name, to)
+    assets.push({ name: to, bytes })
+  }
+  // Fail closed (review N1): an asset the server would not serve from /_brust/client would 404.
+  if (unserved.length > 0) {
+    const lines = unserved.map((name) => {
+      const by = sources.filter((_, i) => css.get(i)?.includes(name))
+      const [, stem, ext] = /^(.*)-[^-.]+(\.[^.]+)$/.exec(name)!
+      return `${stem}${ext} (url() in ${by.join(', ') || 'a stylesheet'})`
+    })
+    throw new BuildError(
+      'css-asset-type',
+      `${lines.join('; ')}: brust serves only ${SERVED_ASSET_EXT.join(' ')} from /_brust/client; put the file in public/ and reference it as /public/…`,
+    )
+  }
+  for (const a of assets) writeFileSync(join(dist, 'client', a.name), a.bytes)
+  for (const [i, src] of sources.entries()) {
+    let text = css.get(i)
+    if (text !== undefined && text.trim() !== '') {
+      for (const [from, to] of rename) text = text.split(from).join(to)
+      const stem = safeName(basename(src).replace(/\.css$/, ''))
+      const out = `${stem}-${hex(text)}.css`
+      writeFileSync(join(dist, 'client', out), text)
+      file.set(src, `client/${out}`)
+    }
+    if (!isModule(src)) continue
+    const mod = join(stage, `map${i}.mjs`)
+    writeFileSync(mod, js.get(i) ?? 'export default {}')
+    const map = { ...((await import(mod)).default as Record<string, string>) }
+    // R19.4: every class the map hands out exists in the CSS it ships with.
+    const have = new Set([...(text ?? '').matchAll(CLASS)].map((x) => x[1]!))
+    for (const [k, v] of Object.entries(map))
+      for (const cls of v.split(/\s+/).filter(Boolean))
+        if (!have.has(cls)) throw new BuildError('css', `${src}: class ${k} maps to ${cls}, which is not in the emitted CSS`)
+    maps.set(src, map)
+  }
+  return { file, maps }
+}
+
+// ---- Tailwind CSS v4 (gaps round L21, R21.1) ----
+
+/** A stylesheet that needs the Tailwind compiler. */
+const TAILWIND_USE = /@import\s+(?:url\(\s*)?["']tailwindcss(?:\/[^"']*)?["']|@apply\b|@reference\b|@theme\b|@plugin\b/
+const TAILWIND_IMPORT = /@import\s+(?:url\(\s*)?["']tailwindcss["']/
+const CSS_IMPORT = /@import\s+(?:url\(\s*)?["'](\.{1,2}\/[^"']+)["']/g
+
+/** Which sources (or the relative `@import`s they pull in) use Tailwind, and which `@import "tailwindcss"`. */
+export function tailwindUse(sources: string[]): { using: string[]; imports: string[] } {
+  const using: string[] = []
+  const imports: string[] = []
+  const seen = new Set<string>()
+  const visit = (f: string) => {
+    if (seen.has(f)) return
+    seen.add(f)
+    let text = ''
+    try {
+      text = readFileSync(f, 'utf8')
+    } catch {
+      return
+    }
+    if (TAILWIND_USE.test(text)) using.push(f)
+    if (TAILWIND_IMPORT.test(text)) imports.push(f)
+    for (const m of text.matchAll(CSS_IMPORT)) visit(resolve(dirname(f), m[1]!))
+  }
+  for (const s of sources) visit(s)
+  return { using, imports }
+}
+
+/** `bun-plugin-tailwind`, resolved from the app (R21.1: `tailwindcss@4` and the plugin are the app's own dev
+ * dependencies). Missing → `tailwind-missing` with the exact install command. */
+export async function loadTailwind(appRoot: string, usedBy: string): Promise<BunPlugin> {
+  const missing = ['tailwindcss', 'bun-plugin-tailwind'].filter((p) => {
+    try {
+      Bun.resolveSync(`${p}/package.json`, appRoot)
+      return false
+    } catch {
+      return true
+    }
+  })
+  if (missing.length > 0)
+    throw new BuildError(
+      'tailwind-missing',
+      `${relative(appRoot, usedBy)} uses Tailwind CSS, but ${missing.join(' and ')} ${missing.length > 1 ? 'are' : 'is'} not installed in the app: run \`bun add -d tailwindcss@4 bun-plugin-tailwind\``,
+    )
+  return (await import(Bun.resolveSync('bun-plugin-tailwind', appRoot))).default as BunPlugin
+}
+
+/** R19.4: the one CSS plugin of every JS build. A `.module.css` import is its class map
+ * (`export default Object.freeze({…})`); any other `.css` import is an empty module, because the
+ * stylesheet itself is linked by the server (R19.3), never bundled into JS. */
+export function cssPlugin(maps: Map<string, Record<string, string>>): BunPlugin {
+  return {
+    name: 'brust-css',
+    setup(b) {
+      b.onLoad({ filter: /\.css$/ }, (a) => {
+        if (!isModule(a.path)) return { contents: '', loader: 'js' }
+        const map = maps.get(real(a.path))
+        if (!map) throw new Error(`${a.path} is imported by code the build did not reach from a route; import it from a route's component files`)
+        return { contents: `export default Object.freeze(${JSON.stringify(map)})\n`, loader: 'js' }
+      })
+    },
+  }
+}
+
+/** Direct `.css` imports of `file` (the route entry: linked to no route, so the build warns). */
+export function directCss(file: string): string[] {
+  const src = readFileSync(file, 'utf8')
+  const t = new Bun.Transpiler({ loader: file.endsWith('.tsx') ? 'tsx' : 'ts' })
+  return t
+    .scanImports(src)
+    .filter((i) => i.kind === 'import-statement' && i.path.endsWith('.css'))
+    .map((i) => i.path)
+}