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

package/src/build/css.ts

@@ -0,0 +1,331 @@
+// 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, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import type { BunPlugin } from 'bun'
+import type { FlatRoute } from '../routes'
+import { BuildError } from './errors'
+import { loadTailwind } from './tailwind'
+
+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']
+
+const SOURCE_URL = /url\(\s*(["']?)([^"')]+?)\1\s*\)/g
+
+/** F393: a `url()` that is the absolute path of a file on disk (see the `loader` in `buildCss`) becomes a
+ * hashed `./<name>-<hex10>.<ext>` client asset at any size. `/public/…` and `/_brust/…` stay as written. */
+function emitSourceAssets(text: string, assets: { name: string; bytes: Uint8Array }[], suffixed: Map<string, string>): string {
+  const emit = (path: string, suffix: string) => {
+    const bytes = new Uint8Array(readFileSync(path))
+    const name = `${safeName(basename(path, extname(path)))}-${hex(bytes)}${extname(path).toLowerCase()}`
+    if (!assets.some((a) => a.name === name)) assets.push({ name, bytes })
+    return /^[^\s"'()\\]*$/.test(suffix) ? `url(./${name}${suffix})` : `url("./${name}${suffix.replace(/["\\]/g, '\\$&')}")`
+  }
+  return text.replace(SOURCE_URL, (whole, _q: string, path: string) => {
+    const abs = suffixed.get(path)
+    if (abs !== undefined) return emit(abs, path.slice(path.search(/[?#]/)))
+    const ext = extname(path).toLowerCase()
+    if (!path.startsWith('/') || !SERVED_ASSET_EXT.includes(ext) || path.startsWith('/public/') || path.startsWith('/_brust/') || !existsSync(path)) return whole
+    return emit(path, '')
+  })
+}
+
+/** F393: a `url()` asset with a `?query` / `#fragment` (`?v=3`, `?#iefix`, an SVG font's `#id`) is not given
+ * Bun's path form: a plugin-resolved specifier is printed as written. This plugin resolves such a specifier
+ * itself and records the file it names, so `emitSourceAssets` can copy it and keep the suffix verbatim. The
+ * same text naming two different files (from two importers) fails the build rather than guess. */
+function suffixPlugin(suffixed: Map<string, string>): BunPlugin {
+  return {
+    name: 'brust-css-asset-suffix',
+    setup(b) {
+      b.onResolve({ filter: /\.(?:woff2?|ttf|otf|eot|png|jpe?g|gif|webp|avif|svg|ico)[?#]/i }, (a) => {
+        const at = a.path.search(/[?#]/)
+        const file = a.path.slice(0, at)
+        let abs: string
+        try {
+          abs = file.startsWith('.') || isAbsolute(file) ? resolve(dirname(a.importer), file) : Bun.resolveSync(file, dirname(a.importer))
+        } catch {
+          return undefined
+        }
+        if (!existsSync(abs)) return undefined
+        const have = suffixed.get(a.path)
+        if (have !== undefined && have !== abs) throw new BuildError('css-asset-ambiguous', `url(${a.path}) names ${have} and ${abs}; give them different specifiers`)
+        suffixed.set(a.path, abs)
+        return { path: abs }
+      })
+    },
+  }
+}
+
+/** 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) {
+    // a stylesheet compiles with Tailwind when it, or a relative @import of it, uses Tailwind
+    const via = new Map<string, boolean>()
+    const uses = (f: string) => {
+      const k = real(f)
+      let hit = via.get(k)
+      if (hit === undefined) via.set(k, (hit = tailwindUse([k]).using.length > 0))
+      return hit
+    }
+    plugins.push(await loadTailwind(appRoot, tw.using[0]!, uses, o.log))
+    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 suffixed = new Map<string, string>()
+  plugins.push(suffixPlugin(suffixed))
+  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/*'],
+    root: appRoot,
+    plugins,
+    // F393, verified on Bun 1.4.4 only: its CSS bundler turns an asset under the size threshold into a `data:`
+    // URI whatever `loader: file` says, and `loader: dataurl` does the opposite (the name is inverted): it leaves
+    // the url() as the absolute path of the source file. That path is the marker `emitSourceAssets` copies and
+    // rewrites. Re-check on every Bun upgrade; the F393 tests in test/css.test.ts go red if the quirk changes.
+    // bun-types 1.4.2's `Loader` omits `dataurl`, which the runtime accepts.
+    loader: Object.fromEntries(SERVED_ASSET_EXT.map((e) => [e, 'dataurl'])) as unknown as Bun.BuildConfig['loader'],
+  })
+  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 [i, t] of css) css.set(i, emitSourceAssets(t, assets, suffixed))
+  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 }
+}
+
+/** 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)
+}

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
+}