@brust/core 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/build/esm-resolve.ts

@@ -0,0 +1,170 @@
+// F189: `Bun.resolveSync` answers the CJS `main` of a package that has both (recharts: `main` is a CJS build, `module`
+// the ES build), so a package resolved from a directory the bundler does not walk (a package's own, for what its source
+// imports) became a second, CJS copy beside the ESM one every other island imports. Re-implementing the bundler's
+// choice drifts (conditions per target, the `browser` field, `development`, `module` before `import`), so this asks
+// the bundler itself: a throwaway `Bun.build` of a virtual file placed in `from` that imports `spec`, with the same
+// `target`; the first module the build loads from outside that file is the answer. Equal to the native pick by
+// construction. It runs in a child process: a `Bun.build` started inside a plugin callback of another build deadlocks.
+// Anything it cannot resolve falls back to `Bun.resolveSync`, which is today's answer, and says so (F222).
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, sep } from 'node:path'
+import { BuildError } from './errors'
+
+/** A specifier relative to its importer: `./x`, `../x` and the bare `.` / `..` (a directory). The one test every resolver path uses (F218, F244). */
+export const RELATIVE_SPEC = /^\.\.?(\/|$)/
+
+export type ResolveTarget = 'bun' | 'browser'
+
+/** What a build besides `target` and `define` tells the bundler about resolution, and where the probe runs. */
+export interface ResolveOpts {
+  /** The build's `conditions` (`--target cloudflare`: workerd, worker, browser). Part of the answer, so part of the key. */
+  conditions?: string[]
+  /** The app root: the probe's working directory (F221) and the home of the cross-build cache (F224). */
+  appRoot?: string
+  /** Kills a probe that does not answer; default `RESOLVE_TIMEOUT_MS`. */
+  timeoutMs?: number
+  /** Where a fallback is named (F222); default: a `warning` line on stderr. */
+  warn?: (message: string) => void
+}
+
+/** `BRUST_RESOLVE_TIMEOUT_MS` or 30 s: a healthy probe answers in well under a second. */
+export const RESOLVE_TIMEOUT_MS = Number(process.env.BRUST_RESOLVE_TIMEOUT_MS) > 0 ? Number(process.env.BRUST_RESOLVE_TIMEOUT_MS) : 30_000
+
+const cache = new Map<string, string>()
+
+/** Forgets the in-process answers and warnings (tests; the disk cache stays). */
+export function clearResolveCache(): void {
+  cache.clear()
+  warned.clear()
+  disks.clear()
+}
+
+// argv: [target, entry, spec, define JSON, conditions JSON]; prints the resolved path. The define is the build's own:
+// `NODE_ENV` flips Bun's `development` condition, so a probe without it picks another file than the build does. The
+// same goes for `conditions`.
+const PROBE = `
+const [target, entry, spec, define, conditions] = process.argv.slice(1)
+const source = 'import ' + JSON.stringify(spec) + '\\n'
+let found
+await Bun.build({
+  entrypoints: [entry], target, write: false, define: JSON.parse(define), conditions: JSON.parse(conditions), files: { [entry]: source },
+  plugins: [{ name: 'o', setup(b) { b.onLoad({ filter: /./ }, (a) => {
+    if (a.path === entry) return { contents: source, loader: 'ts' }
+    found ??= a.path
+    return { contents: '', loader: 'js' }
+  }) } }],
+})
+if (found) process.stdout.write(found)
+`
+
+const defaultWarn = (m: string) => console.warn(`warning resolve-fallback ${m}`)
+const warned = new Set<string>()
+
+/** `spec` as the bundler of `target` resolves it from the directory `from`. */
+export function resolveNative(spec: string, from: string, target: ResolveTarget, define: Record<string, string> = {}, opts: ResolveOpts = {}): string {
+  const defs = JSON.stringify(define)
+  const conds = JSON.stringify(opts.conditions ?? [])
+  const key = `${target}\0${from}\0${spec}\0${defs}\0${conds}`
+  const hit = cache.get(key)
+  if (hit !== undefined) return hit
+  const disk = opts.appRoot !== undefined ? diskCache(opts.appRoot, `${target}\0${defs}\0${conds}`) : undefined
+  const saved = disk?.get(`${from}\0${spec}`, from)
+  if (saved !== undefined) {
+    cache.set(key, saved)
+    return saved
+  }
+  const timeout = opts.timeoutMs ?? RESOLVE_TIMEOUT_MS
+  const r = Bun.spawnSync([process.execPath, '-e', PROBE, target, join(from, '__brust_resolve__.ts'), spec, defs, conds], { cwd: opts.appRoot ?? from, stdout: 'pipe', stderr: 'pipe', timeout, killSignal: 'SIGKILL' })
+  const out = r.exitCode === 0 ? r.stdout.toString() : ''
+  let path = out
+  if (path === '') {
+    // The probe did not answer: today's answer (`Bun.resolveSync`) stands, and the build output says why.
+    const why = r.exitCode === null || r.signalCode ? `the probe did not answer within ${timeout} ms` : r.exitCode !== 0 ? `the probe failed (${r.stderr.toString().trim().split('\n')[0] || `exit ${r.exitCode}`})` : 'the probe resolved nothing'
+    // F242: `Bun.resolveSync` answers with the bun/node conditions. For a browser-target build (client chunks, the Worker)
+    // that can be a node-only build of the package, so it is not an answer there.
+    if (target === 'browser') throw new BuildError('resolve-fallback', `cannot resolve "${spec}" from ${from} for a browser-target build: ${why}; the runtime resolver would pick the bun/node conditions, so there is no fallback`)
+    path = Bun.resolveSync(spec, from)
+    const msg = `${spec} from ${from} (${target}): ${why}; used Bun.resolveSync -> ${path}`
+    if (!warned.has(msg)) {
+      warned.add(msg)
+      ;(opts.warn ?? defaultWarn)(msg)
+    }
+  } else disk?.set(`${from}\0${spec}`, path, from)
+  cache.set(key, path)
+  return path
+}
+
+// F224: a probe is a child process plus a `Bun.build`: ~100-300 ms each, once per (package dir, specifier) in a build,
+// and again in every build. The answers are kept across builds in `<appRoot>/.brust/resolve-cache.json`, valid for one
+// lockfile and one Bun, per (target, define, conditions); an entry is dropped when its file is gone or the nearest
+// `package.json` above it changed (a linked workspace package edits without touching the lockfile).
+interface Saved { path: string; pkg: string; mtime: number; from: string; fromMtime: number }
+const LOCKS = ['bun.lock', 'bun.lockb', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock']
+const disks = new Map<string, DiskCache | null>()
+
+class DiskCache {
+  private entries: Record<string, Saved> = {}
+  constructor(private file: string, private salt: string, private appRoot: string) {
+    try {
+      const j = JSON.parse(readFileSync(file, 'utf8'))
+      if (j.salt === salt) this.entries = j.entries ?? {}
+    } catch {}
+  }
+  get(k: string, from: string): string | undefined {
+    const e = this.entries[k]
+    if (!e) return undefined
+    try {
+      // F245: the file is trusted as written, so every answer is re-validated: it must lie inside the app or in a
+      // `node_modules`, and still be a file; else the entry is dropped and the probe asks again.
+      const [fromPkg, fromMtime] = nearestPackageJson(from)
+      if (this.plausible(e.path) && statSync(e.path).isFile() && (e.pkg === '' || statSync(e.pkg).mtimeMs === e.mtime) && e.from === fromPkg && e.fromMtime === fromMtime) return e.path
+    } catch {}
+    delete this.entries[k]
+    return undefined
+  }
+  set(k: string, path: string, from: string): void {
+    const [pkg, mtime] = nearestPackageJson(dirname(path))
+    const [fromPkg, fromMtime] = nearestPackageJson(from)
+    this.entries[k] = { path, pkg, mtime, from: fromPkg, fromMtime }
+    try {
+      mkdirSync(dirname(this.file), { recursive: true })
+      const tmp = `${this.file}.${process.pid}.tmp`
+      writeFileSync(tmp, JSON.stringify({ salt: this.salt, entries: this.entries }))
+      renameSync(tmp, this.file)
+    } catch {}
+  }
+  private plausible(path: string): boolean {
+    return path.startsWith(this.appRoot + sep) || path.split(sep).includes('node_modules')
+  }
+}
+
+/** The nearest `package.json` at or above `dir` and its mtime (`['', 0]` when there is none). */
+function nearestPackageJson(dir: string): [string, number] {
+  for (let d = dir; ; d = dirname(d)) {
+    const p = join(d, 'package.json')
+    if (existsSync(p)) return [p, statSync(p).mtimeMs]
+    if (dirname(d) === d) return ['', 0]
+  }
+}
+
+/** The cache for this app and (target, define, conditions), or none when no lockfile pins the install. */
+function diskCache(appRoot: string, scope: string): DiskCache | undefined {
+  const id = `${appRoot}\0${scope}`
+  const have = disks.get(id)
+  if (have !== undefined) return have ?? undefined
+  let lock: string | undefined
+  for (let d = appRoot; lock === undefined; d = dirname(d)) {
+    lock = LOCKS.map((l) => join(d, l)).find((f) => existsSync(f))
+    if (dirname(d) === d) break
+  }
+  let made: DiskCache | null = null
+  if (lock !== undefined) {
+    try {
+      const salt = createHash('sha256').update(Bun.version).update(readFileSync(lock)).update(scope).digest('hex')
+      made = new DiskCache(join(appRoot, '.brust', `resolve-cache-${createHash('sha256').update(scope).digest('hex').slice(0, 8)}.json`), salt, appRoot)
+    } catch {}
+  }
+  disks.set(id, made)
+  return made ?? undefined
+}

package/src/build/features.ts

@@ -0,0 +1,114 @@
+// Which client-runtime feature modules a component needs (L33, R35.2). The compiler's output is the source of truth:
+// a native component's template carries one `x-*` attribute per directive it uses, a react-tier component is an island.
+// The set is written per component into the manifest; the server unions it over a route's components and links the
+// core plus exactly those modules. `packages/runtime-dom/README.md` ("Feature modules") owns the module list and the rule.
+import { BuildError } from './errors'
+
+/** Feature modules of `@brust/runtime-dom/features/*` the browser build ships, in load order. */
+export const RUNTIME_FEATURES = ['basics', 'if', 'for', 'model', 'html', 'island', 'collection'] as const
+export type RuntimeFeature = (typeof RUNTIME_FEATURES)[number]
+
+/** Directive attribute → the module that binds it. `null`: handled by the core (host, props, inert-markup marker). */
+export function featureOfAttr(attr: string): RuntimeFeature | null | undefined {
+  switch (attr) {
+    case 'x-data':
+    case 'x-props':
+    case 'x-props-bind':
+    case 'x-raw':
+      return null
+    case 'x-text':
+    case 'x-show':
+    case 'x-ref':
+      return 'basics'
+    case 'x-if':
+    case 'x-for':
+    case 'x-model':
+    case 'x-html':
+      return attr.slice(2) as RuntimeFeature
+    case 'x-collection-root':
+    case 'x-collection-item':
+    case 'x-collection-use':
+      return 'collection'
+    default:
+      return /^x-(bind|on|prop)-/.test(attr) ? 'basics' : undefined
+  }
+}
+
+/** The template with every jinja tag (`{{ … }}`, `{% … %}`, `{# … #}`) replaced by a space, string literals inside them
+ * read as strings: a printed value such as shadcn's `has-[>svg]:px-3` (a folded class, F149) holds a `>` or a quote that
+ * would otherwise end the element's tag early and hide the directives after it. A directive is never inside a jinja tag. */
+export function withoutJinja(template: string): string {
+  let out = ''
+  let i = 0
+  while (i < template.length) {
+    const open = template.indexOf('{', i)
+    const kind = open < 0 ? '' : template[open + 1]
+    if (open < 0) {
+      out += template.slice(i)
+      break
+    }
+    if (kind !== '{' && kind !== '%' && kind !== '#') {
+      out += template.slice(i, open + 1)
+      i = open + 1
+      continue
+    }
+    out += template.slice(i, open)
+    const close = kind === '{' ? '}}' : `${kind}}`
+    let j = open + 2
+    let quote = ''
+    for (; j < template.length; j++) {
+      const ch = template[j]!
+      if (quote) {
+        if (ch === '\\') j++
+        else if (ch === quote) quote = ''
+      } else if (kind !== '#' && (ch === '"' || ch === "'")) quote = ch
+      else if (template.startsWith(close, j)) break
+    }
+    out += ' '
+    i = j + close.length
+  }
+  return out
+}
+
+/** The `x-*` attribute names on the elements of a template (tags only: prose that mentions `x-for` binds nothing). */
+export function directiveAttrs(template: string): Set<string> {
+  const out = new Set<string>()
+  template = withoutJinja(template)
+  for (const tag of template.matchAll(/<[a-zA-Z][\w-]*((?:[^>"']|"[^"]*"|'[^']*')*)>/g))
+    for (const a of tag[1]!.matchAll(/(?:^|\s)(x-[a-z][a-z0-9-]*)(?==|\s|$|\/)/g)) out.add(a[1]!)
+  return out
+}
+
+/**
+ * The feature modules `template` needs, sorted in load order (`react` = the component is an island: `island`).
+ * An `x-*` attribute no module binds is a build error (a compiler that learned a directive before the runtime did):
+ * never a silent no-op in the browser.
+ */
+export function featuresOf(id: string, template: string, react: boolean): RuntimeFeature[] {
+  const need = new Set<RuntimeFeature>()
+  if (react) need.add('island')
+  for (const attr of directiveAttrs(template)) {
+    const f = featureOfAttr(attr)
+    if (f === undefined) throw new BuildError('runtime-feature-missing', `${id}: the template uses ${attr}, which no client runtime feature binds`)
+    if (f !== null) need.add(f)
+  }
+  return RUNTIME_FEATURES.filter((f) => need.has(f))
+}
+
+/** Matches the `/_brust/<file>` URL of `file` in a built chunk's text. */
+const mentions = (text: string, file: string) => text.includes(`/_brust/${file}`)
+
+/**
+ * Whether the built client file `entry` (`client/<file>`) imports the store module `storeFile`, directly or through the
+ * shared `chunk-*.js` files it imports. A component whose chunk does gets `store` in its features: the page preloads
+ * the module (the chunk imports it itself, so it has no script tag).
+ */
+export function importsStore(read: (rel: string) => string | undefined, entry: string, storeFile: string, seen = new Set<string>()): boolean {
+  if (seen.has(entry)) return false
+  seen.add(entry)
+  const text = read(entry)
+  if (text === undefined) return false
+  if (mentions(text, storeFile)) return true
+  for (const m of text.matchAll(/(?:from|import)\s*"\.\/([^"]+\.js)"/g)) if (importsStore(read, `client/${m[1]}`, storeFile, seen)) return true
+  return false
+}

package/src/build/index.ts

@@ -4,16 +4,25 @@
 // edited by hand. An out dir that could hold the app's own sources, or a non-empty one that is not
 // a previous brust dist (no `manifest.json` / `.brust` marker; `--force` overrides), is refused
 // before anything is written or removed.
-import { cpSync, existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path'
-import { BrustRouteError, validateRoutes } from '../routes'
-import { type BrowserCtx, buildActions, buildClientChunks, buildJobs, buildReactChunks, buildRuntime, storeModules } from './bundle'
-import { compileApp } from './compile'
-import { type ActionsBuildConfig, loadBuildConfig } from './config'
+import { BrustRouteError, type FlatRoute, validateRoutes } from '../routes'
+import { type BrowserCtx, setDevBuild, buildActions, buildCacheAdapter, buildClientChunks, buildJobs, buildReactChunks, buildRuntime, nestedOf, storeModules } from './bundle'
+import { runActionsOnly } from './actions-only'
+import { type CfPrepared, buildCloudflare, prepareCloudflare } from './cloudflare'
+import { renderIcons } from './build-icons'
+import { evaluateBuildSlots } from './build-eval'
+import { preparePackageSources } from './pkg-src'
+import { type Compiled, compileApp, scanAppWrites } from './compile'
+import { buildCss, CssGraph, directCss, resolveGlobals, routeCssSources } from './css'
+import { type ActionsBuildConfig, type CacheBuildConfig, loadBuildConfig } from './config'
 import { BuildError } from './errors'
-import { writeManifest } from './manifest'
+import { importsStore } from './features'
+import { type CacheRecord, type ManifestJson, needsWorkers, reachedJobs, tierOf, writeManifest } from './manifest'
 import { scanRoutes } from './scan'
+import { type ExprReads, prepareStatic, writeStatic } from './static'
+import { writeStaticWorker } from './static-worker'
 
 export { BuildError } from './errors'
 
@@ -79,17 +88,40 @@ export async function runBuild(opts: {
   outDir: string
   /** Replace a non-empty out dir even without a previous build's marker. */
   force?: boolean
+  /** `cloudflare` also writes `<out>/cf/` (M4-CF); `static` also writes `<out>/static/` (gaps round
+   * L9); default `bun` = the unchanged build. */
+  target?: 'bun' | 'cloudflare' | 'static'
+  /** `--strict` (static): a loader that reads the request fails the build. */
+  strict?: boolean
+  /** The cache key grammar's read-set (static; tests swap it). Default: the addon. */
+  exprReads?: ExprReads
+  /** `--wasm-from-source` (cloudflare only). */
+  wasmFromSource?: boolean
+  /** `--actions-only` (L16 R16.3): no pages, only the `[actions]` app; with `bun` (default) or `cloudflare`. */
+  actionsOnly?: boolean
+  /** `brust build --dev` (L14, used by `brust dev`): also writes `dev.json` and builds the client runtime with `__BRUST_DEV__`. */
+  dev?: boolean
   log: (s: string) => void
 }): Promise<void> {
+  setDevBuild(opts.dev === true)
   const appRoot = resolve(opts.appRoot)
   const entry = resolve(appRoot, opts.entry)
   const dist = resolve(appRoot, opts.outDir)
   assertSafeOutDir(dist, appRoot, [entry, join(appRoot, 'public')])
   assertReplaceable(dist, opts.force)
-  const { serverOnly, actions } = await loadBuildConfig(appRoot)
+  const built = await loadBuildConfig(appRoot, { actionsOnly: opts.actionsOnly === true })
+  if (opts.actionsOnly)
+    return runActionsOnly({ appRoot, dist, config: built, target: opts.target, wasmFromSource: opts.wasmFromSource === true, statOk, assertSafeOutDir, log: opts.log })
+  const { serverOnly, cloudflare, cache, cssGlobal, sourceRoots } = built
+  // L16 R16.4b: `[actions]` with a `base_url` and no actions file (the default name, not one written in the toml)
+  // is a page-only build: the app is deployed elsewhere, so nothing is bundled or mounted here.
+  const remote =
+    built.actions !== null && built.actions.baseUrl !== undefined && !built.actions.entryExplicit && !statOk(resolve(appRoot, built.actions.entry)) ? built.actions : null
+  const actions = remote ? null : built.actions
+  if (actions?.prefix === '/') throw new BuildError('config', 'actions.prefix "/" is only for an actions-only build (brust build --actions-only) or a page-only build that points at one')
 
   // Everything that can fail on the app's own input runs before a byte is written.
-  const { routes, componentFile } = await scanRoutes(entry)
+  const { routes, componentFile, componentIssue, appModules, appGraph } = await scanRoutes(entry, appRoot, sourceRoots)
   let leaves: ReturnType<typeof validateRoutes>
   try {
     leaves = validateRoutes(routes)
@@ -114,7 +146,26 @@ export async function runBuild(opts: {
       }
     }
   }
-  assertSafeOutDir(dist, appRoot, [...componentFile.values(), ...(actionsEntry ? [actionsEntry] : [])])
+  let cacheModule: string | null = null
+  if (cache?.module !== undefined) {
+    cacheModule = resolve(appRoot, cache.module)
+    const rel = relative(appRoot, cacheModule)
+    if (isAbsolute(cache.module) || rel === '..' || rel.startsWith('../') || isAbsolute(rel) || !statOk(cacheModule)) {
+      throw new BuildError('cache', `cache.module ${cache.module} is not a file inside the app`)
+    }
+  }
+  assertSafeOutDir(dist, appRoot, [...componentFile.values(), ...(actionsEntry ? [actionsEntry] : []), ...(cacheModule ? [cacheModule] : [])])
+
+  // R9.3/R9.4: every reason to refuse a static build, before any write.
+  const ssgPlan =
+    opts.target === 'static'
+      ? await prepareStatic(leaves, actions !== null, opts.exprReads ?? (await import('../native')).cacheExprReads, opts.log, cache)
+      : null
+
+  // Config, @brust/core-cf resolution and the user's wrangler file fail here, before any write.
+  // L12: a static build with `[actions]` also builds the Cloudflare worker (its Pages `_worker.js`).
+  const hybrid = ssgPlan !== null && actions !== null
+  const cf = opts.target === 'cloudflare' || hybrid ? await prepareCloudflare(appRoot, cloudflare, { fromSource: opts.wasmFromSource === true, env: process.env }) : null
 
   // Sibling of `dist` (same filesystem: the final rename is atomic), fixed name (no random bytes in
   // anything the bundler sees).
@@ -122,7 +173,13 @@ export async function runBuild(opts: {
   rmSync(tmp, { recursive: true, force: true })
   mkdirSync(tmp, { recursive: true })
   try {
-    await buildInto(tmp, { appRoot, entry, dist, leaves, componentFile, serverOnly, actions, actionsEntry, log: opts.log })
+    await buildInto(tmp, { dev: opts.dev === true, appRoot, entry, dist, leaves, componentFile, componentIssue, appModules, appGraph, serverOnly, actions, actionsEntry, cache, cacheModule, cf, hybrid, cssGlobal, sourceRoots, actionsRemote: remote?.prefix ?? null, log: opts.log })
+    if (ssgPlan) {
+      // Rendered from the finished temp dist, so a failed render leaves the previous dist untouched.
+      const version: string = (await Bun.file(join(import.meta.dir, '../../package.json')).json()).version
+      await writeStatic(tmp, { entry, appRoot, plan: ssgPlan, version, strict: opts.strict === true, log: opts.log, shownDir: join(dist, 'static') })
+      if (hybrid && cf && actions) writeStaticWorker(tmp, actions, cf, opts.log)
+    }
     rmSync(join(tmp, '.stage'), { recursive: true, force: true })
     if (existsSync(dist)) {
       const old = join(dirname(dist), `.${basename(dist)}.brust-old`)
@@ -140,48 +197,172 @@ export async function runBuild(opts: {
 async function buildInto(
   out: string,
   o: {
+    /** Write `dev.json` (L14). */
+    dev: boolean
     appRoot: string
     entry: string
     /** The final dist dir (`index.js` points at the entry relative to it). */
     dist: string
     leaves: ReturnType<typeof validateRoutes>
     componentFile: Map<Function, string>
+    componentIssue: Map<Function, string>
+    /** F230: every app module of the route entry's static import graph (absolute paths). */
+    appModules: string[]
+    /** F230: each app module's in-root static imports (absolute paths). */
+    appGraph: Map<string, string[]>
     serverOnly: string[]
     actions: ActionsBuildConfig | null
     /** Absolute path of the actions entry (null when `[actions]` is off). */
     actionsEntry: string | null
+    cache: CacheBuildConfig | null
+    /** Absolute path of a custom cache adapter module. */
+    cacheModule: string | null
+    cf: CfPrepared | null
+    /** `[css] global` as written (app-root relative). */
+    cssGlobal: string[]
+    /** `[build] source_roots` (F256): normalised, app-root-relative directories outside the app a relative import may reach. */
+    sourceRoots: string[]
+    /** L16 R16.4b: the prefix of an actions app deployed elsewhere (a page-only build); absent = a local app or none. */
+    actionsRemote: string | null
+    /** `--target static` with `[actions]`: the worker is built without the cache (static pages are never cached). */
+    hybrid: boolean
     log: (s: string) => void
   },
 ): Promise<void> {
   const { appRoot, entry, leaves } = o
-  const ctx: BrowserCtx = { sourceOf: new Map(), appRoot, serverOnly: o.serverOnly, serverFiles: o.actionsEntry ? [realpathSync(o.actionsEntry)] : [] }
+  // L19: every stylesheet first, so each JS build below reads one set of CSS Module class maps.
+  const graph = new CssGraph()
+  const chainFiles = (l: FlatRoute) => l.chain.flatMap((n) => (n.Component && o.componentFile.has(n.Component) ? [o.componentFile.get(n.Component)!] : []))
+  const routeCss = routeCssSources(leaves, chainFiles, resolveGlobals(appRoot, o.cssGlobal), graph)
+  const serverCss = [o.actionsEntry, o.cacheModule].flatMap((f) => (f ? graph.of(f) : []))
+  mkdirSync(join(out, 'client'), { recursive: true })
+  // Review N3: `brust dev` builds with BRUST_BUILD_MODE=development (as the JS bundles): readable, unminified CSS.
+  const css = await buildCss(out, [...new Set([...[...routeCss.values()].flat(), ...serverCss])], process.env.BRUST_BUILD_MODE !== 'development', { appRoot, log: o.log })
+  for (const c of directCss(entry))
+    o.log(`[brust] warning css ${relative(appRoot, entry)} imports ${c}: the route entry belongs to no route, so it is linked nowhere; import it from a layout, or list it in [css] global`)
+  const ctx: BrowserCtx = { sourceOf: new Map(), appRoot, serverOnly: o.serverOnly, serverFiles: o.actionsEntry ? [realpathSync(o.actionsEntry)] : [], cssMaps: css.maps }
   // The runtime first: its hashed URL is the `runtimeImport` every client chunk is compiled with.
   const runtime = await buildRuntime(out, ctx)
-  const { compiled, routeComponent } = compileApp({
+  const runtimeUrls = { core: `/_brust/${runtime.core}`, store: `/_brust/${runtime.store}` }
+  // F230: one scan per build for load-time writes into another app module's exports; every compile reads it.
+  const loadWrites = scanAppWrites(appRoot, o.appModules, o.log, o.sourceRoots)
+  // Where a React island renders, the load-time writers run first: every one in the SSR jobs bundle (server code the
+  // worker runs anyway); in an island's browser chunk only a writer of a module that island's code imports (Mellow F1:
+  // a writer is often a server-side setup module), with a warning.
+  const scanned = JSON.parse(loadWrites) as { writers: [string, string[]][] }
+  const real = (f: string) => {
+    try {
+      return realpathSync(f)
+    } catch {
+      return f
+    }
+  }
+  const writes = scanned.writers.map(([w, mods]) => ({ file: real(resolve(appRoot, w)), mods: new Set(mods.map((m) => real(resolve(appRoot, m)))) }))
+  const writers = [...new Set(writes.map((w) => w.file))]
+  const appGraph = new Map([...o.appGraph].map(([f, deps]) => [real(f), deps.map(real)]))
+  const writersFor = (c: Compiled, files: string[]): string[] => {
+    if (writes.length === 0) return []
+    const reached = new Set<string>()
+    const stack = files.map(real)
+    while (stack.length > 0) {
+      const f = stack.pop()!
+      if (reached.has(f)) continue
+      reached.add(f)
+      stack.push(...(appGraph.get(f) ?? []))
+    }
+    const out = writes.filter((w) => [...w.mods].some((m) => reached.has(m)))
+    for (const w of out)
+      o.log(`[brust] warning load-writer-in-client ${relative(appRoot, w.file)} is imported into the browser chunk of the React island ${c.id}: it changes ${[...w.mods].filter((m) => reached.has(m)).map((m) => relative(appRoot, m)).join(', ')} when it loads, and the island reads that module (F230). Its code ships to the browser: keep secrets and server-only code out of it, or write the value in the module that declares it`)
+    return [...new Set(out.map((w) => w.file))]
+  }
+  const compileOpts = {
     appRoot,
     leaves,
     componentFile: o.componentFile,
-    runtimeImport: `/_brust/${runtime}`,
+    componentIssue: o.componentIssue,
+    loadWrites,
+    runtimeImport: runtimeUrls.core,
     serverOnly: o.serverOnly,
-    log: o.log,
-  })
+    sourceRoots: o.sourceRoots,
+    cssMaps: css.maps,
+  }
+  const firstLog: string[] = []
+  let { compiled, routeComponent } = compileApp({ ...compileOpts, log: (l) => firstLog.push(l) })
+  // F153c: the packages the app imports components from are compiled from their source when they publish it (and
+  // it matches what they publish); the app is compiled again with those sources. A refused package stays the island.
+  // F197: and the packages a helper is imported from, when the compiler asked to prove one plain.
+  const external = [...new Set([...compiled.values()].flatMap((c) => [...(c.ir.external ? [c.ir.external.source] : []), ...((c.ir.package_requests ?? []) as string[])]))]
+  const packages = preparePackageSources(appRoot, external)
+  if (Object.keys(packages.scopes).length > 0 || Object.keys(packages.recognised).length > 0) {
+    firstLog.length = 0
+    ;({ compiled, routeComponent } = compileApp({ ...compileOpts, packages, log: (l) => firstLog.push(l) }))
+  }
+  // L23: lucide icons the compiler could inline are rendered here (react-dom/server); L2: slots that read
+  // nothing request- or time-dependent are computed once, here. The app is compiled again with both (an icon with
+  // no markup stays the L22 island; a slot with a value is a literal: no job, no worker). The first compile's
+  // warnings describe icons that are inline now, so when icons were rendered only the last compile's are shown.
+  const hasIcons = [...compiled.values()].some((c) => (c.ir.icon_requests ?? []).length > 0)
+  const iconSvgs = hasIcons ? await renderIcons(compiled, appRoot, o.log) : undefined
+  const slotValues = await evaluateBuildSlots(out, compiled, ctx.sourceOf, appRoot, o.log)
+  const hasSlots = Object.keys(slotValues).length > 0
+  if (hasIcons || hasSlots) {
+    if (!hasIcons) firstLog.forEach((l) => o.log(l))
+    ;({ compiled, routeComponent } = compileApp({ ...compileOpts, packages, iconSvgs, iconsFinal: hasIcons, slotValues, log: hasIcons ? o.log : () => {} }))
+  } else firstLog.forEach((l) => o.log(l))
+
+  // F158 (R34.69/70): the compiler makes a caller of a route component fall back to React, so none is a revive host;
+  // if one is, the compiler missed it, and the build stops rather than let request data near the revive.
+  const routeRoots: ReadonlySet<string> = new Set(routeComponent.values())
+  for (const id of routeRoots) {
+    if (nestedOf(compiled, id) !== undefined) throw new BuildError('revive-host-route-root', `${id} is a page or layout and also receives lowered JSX children from a caller; this is a compiler bug (F158), please report it`)
+  }
 
   mkdirSync(join(out, 'jinja'), { recursive: true })
   for (const c of compiled.values()) writeFileSync(join(out, 'jinja', `${c.id}.jinja`), c.jinja)
 
-  const runtimeUrl = `/_brust/${runtime}`
-  const chunks = new Map([...(await buildClientChunks(out, compiled, ctx, runtimeUrl)), ...(await buildReactChunks(out, compiled, ctx, runtimeUrl))])
-  const manifest = writeManifest({ leaves, routeComponent, compiled, runtime, chunks })
-  await buildJobs(out, compiled, ctx.sourceOf, appRoot, storeModules(manifest))
+  const chunks = new Map([...(await buildClientChunks(out, compiled, ctx, runtimeUrls)), ...(await buildReactChunks(out, compiled, ctx, runtimeUrls, routeRoots, writersFor))])
+  const manifest = writeManifest({ leaves, routeComponent, compiled, runtime: { core: runtime.core, features: { ...runtime.features, store: runtime.store } }, chunks })
+  // L33: a component whose chunk imports the store module (directly or through a shared chunk) has the page preload it.
+  const readClient = (rel: string) => (existsSync(join(out, rel)) ? readFileSync(join(out, rel), 'utf8') : undefined)
+  for (const rec of Object.values(manifest.components)) if (rec.client && importsStore(readClient, rec.client, runtime.store)) rec.features.push('store')
+  for (const r of manifest.routes) {
+    const files = [...new Set((routeCss.get(r.id) ?? []).flatMap((s) => (css.file.has(s) ? [css.file.get(s)!] : [])))]
+    if (files.length > 0) r.css = files
+  }
+  await buildJobs(out, compiled, ctx.sourceOf, appRoot, storeModules(manifest), css.maps, routeRoots, reachedJobs(manifest), writers)
   manifest.actions =
     o.actions && o.actionsEntry
-      ? { entry: await buildActions(out, o.actionsEntry), prefix: o.actions.prefix, maxBodyBytes: o.actions.maxBodyBytes, maxResponseBytes: o.actions.maxResponseBytes, crossSite: o.actions.crossSite }
+      ? { entry: await buildActions(out, o.actionsEntry, css.maps), prefix: o.actions.prefix, maxBodyBytes: o.actions.maxBodyBytes, maxResponseBytes: o.actions.maxResponseBytes, crossSite: o.actions.crossSite }
       : null
+  if (o.actionsRemote !== null) manifest.actions_remote = { prefix: o.actionsRemote }
+  if (o.cache) manifest.cache = await cacheRecord(out, manifest, o.cache, o.cacheModule, css.maps)
+  manifest.needs_workers = needsWorkers(manifest)
   writeFileSync(join(out, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+  if (o.dev) writeFileSync(join(out, 'dev.json'), `${JSON.stringify(devJson(appRoot, compiled), null, 2)}\n`)
   writeFileSync(join(out, MARKER), 'generated by `brust build`: this directory is replaced on every build\n')
 
   const pub = join(appRoot, 'public')
   if (existsSync(pub)) cpSync(pub, join(out, 'public'), { recursive: true })
+  if (o.cf) {
+    const warnings = await buildCloudflare(
+      out,
+      {
+        appRoot,
+        entry,
+        dist: o.dist,
+        compiled,
+        manifest: o.hybrid ? { ...manifest, cache: undefined } : manifest,
+        sourceOf: ctx.sourceOf,
+        actionsEntry: o.actionsEntry,
+        cacheModule: o.hybrid ? null : o.cacheModule,
+        cacheGetTimeoutMs: o.hybrid ? undefined : o.cache?.getTimeoutMs,
+        cssMaps: css.maps,
+        log: o.log,
+      },
+      o.cf,
+    )
+    for (const w of warnings) o.log(w)
+  }
   const entryRel = relative(o.dist, entry)
   writeFileSync(
     join(out, 'index.js'),
@@ -197,3 +378,66 @@ async function buildInto(
     ].join('\n'),
   )
 }
+
+/** `dev.json` (L14, R14.2): component id → source file, tier, the react reason, diagnostics. Only `brust build --dev` writes it. */
+export function devJson(appRoot: string, compiled: Map<string, Compiled>): { version: 1; components: Record<string, DevComponent> } {
+  const components: Record<string, DevComponent> = {}
+  for (const c of compiled.values()) {
+    const tier = tierOf(c.ir)
+    const t = c.ir.tier
+    components[c.id] = {
+      file: relative(appRoot, c.file),
+      tier,
+      ...(tier === 'react' && t && typeof t === 'object' && 'React' in t ? { reason: String((t as { React: { reason: string } }).React.reason) } : {}),
+      diagnostics: (c.diagnostics ?? []).map((d) => ({ class: d.class, rule: d.rule, line: d.line, col: d.col, message: d.message, remediation: d.remediation })),
+    }
+  }
+  return { version: 1, components }
+}
+
+export interface DevComponent {
+  file: string
+  tier: 'static' | 'native' | 'react'
+  /** Why the compiler chose the react tier (the IR's `React.reason`). */
+  reason?: string
+  diagnostics: { class: string; rule: string; line: number; col: number; message: string; remediation: string }[]
+}
+
+/** `manifest.cache` (R7, R8): the custom module bundled for the worker, the native defaults, and the
+ * build id every L2 key carries. */
+async function cacheRecord(out: string, manifest: ManifestJson, c: CacheBuildConfig, moduleAbs: string | null, cssMaps: Map<string, Record<string, string>>): Promise<CacheRecord> {
+  const module = moduleAbs ? await buildCacheAdapter(out, moduleAbs, cssMaps) : undefined
+  return {
+    adapter: c.adapter,
+    ...(module ? { module } : {}),
+    ...(c.broadcast ? { broadcast: c.broadcast, broadcastOptions: c.broadcastOptions ?? {} } : {}),
+    options: c.options,
+    namespace: c.namespace,
+    getTimeoutMs: c.getTimeoutMs ?? 50,
+    maxBodyBytes: c.maxBodyBytes,
+    epochIntervalMs: c.epochIntervalMs,
+    buildId: computeBuildId(out, manifest),
+  }
+}
+
+/** R7: the first 16 hex chars of sha256 over the manifest (without `cache`), every `jinja/*.jinja`
+ * (by name), `jobs.js` and `actions.js` when present: a rebuild of the same app keeps it, any change
+ * to what renders a page moves it (a deploy never serves an older build's L2 bodies). */
+export function computeBuildId(out: string, manifest: ManifestJson): string {
+  const h = new Bun.CryptoHasher('sha256')
+  const { cache: _, ...rest } = manifest
+  h.update(JSON.stringify(rest))
+  const jinja = join(out, 'jinja')
+  for (const f of (existsSync(jinja) ? readdirSync(jinja) : []).filter((f) => f.endsWith('.jinja')).sort()) {
+    h.update(`\0${f}\0`)
+    h.update(readFileSync(join(jinja, f)))
+  }
+  for (const f of ['jobs.js', 'actions.js']) {
+    const p = join(out, f)
+    if (existsSync(p)) {
+      h.update(`\0${f}\0`)
+      h.update(readFileSync(p))
+    }
+  }
+  return h.digest('hex').slice(0, 16)
+}