@brust/core 2.0.0-alpha.15 → 2.0.0-alpha.16

package/src/build/compile.ts

@@ -4,7 +4,7 @@
 // A component several trees reach keeps one compile, chosen by role, not by route order (F75).
 import { realpathSync } from 'node:fs'
 import { relative, sep } from 'node:path'
-import { type CompiledComponent, type CompiledTree, compileTree } from '../../native/index.js'
+import { type CompiledComponent, type CompiledTree, compileTree, scanLoadWrites } from '../../native/index.js'
 import type { FlatRoute, Route } from '../routes'
 import { BuildError } from './errors'
 import { checkAliasAgreement, readPathAliases } from './tsconfig-paths'
@@ -70,6 +70,8 @@ export interface Compiled {
   /** Build-time evaluation module (L2): one thunk per `ir.build_eval` slot. */
   evalTs?: string
   clientJs?: string
+  /** Modules the chunk imports that other chunks share (R34.124): `<name>.js` beside it. */
+  clientModules?: { name: string; code: string }[]
   /** The compiler's diagnostics for this component (`dev.json`, L14). */
   diagnostics?: { class: string; rule: string; message: string; line: number; col: number; remediation: string }[]
 }
@@ -112,6 +114,25 @@ export function replaces(kept: Seen, next: Seen): boolean {
   return next.role > kept.role
 }
 
+/**
+ * F230 (closes F219): scans the app's modules once for writes into another app module's exports (`LABELS.a = …`,
+ * `list.push(…)` through an import) and returns the JSON every `compileTree` of the build reads: a component whose
+ * compiled code reads such an export falls back to React (`module-written`). `modules` are absolute paths.
+ */
+export function scanAppWrites(appRoot: string, modules: string[], log: (s: string) => void): string {
+  // Keyed as `compileApp` names a file to the compiler (relative to `appRoot`), plus the real-path spelling (as
+  // `routeRoots`), so an import resolves to the same key either way.
+  const real = realpathSync(appRoot)
+  const toKey = (base: string, f: string) => relative(base, f).split(sep).join('/')
+  const rel = [...new Set(modules.flatMap((f) => [toKey(appRoot, f), toKey(real, realpathSync(f))]))].filter((k) => !k.startsWith('..')).sort()
+  const { aliases } = readPathAliases(appRoot)
+  const t0 = performance.now()
+  const json = scanLoadWrites(appRoot, rel, aliases.length > 0 ? JSON.stringify(aliases) : undefined)
+  const ms = performance.now() - t0
+  if (process.env.BRUST_BUILD_TIMINGS) log(`[brust] scan load-time writes: ${rel.length} modules in ${ms.toFixed(1)} ms`)
+  return json
+}
+
 export function compileApp(opts: {
   appRoot: string
   leaves: FlatRoute[]
@@ -131,11 +152,16 @@ export function compileApp(opts: {
   slotValues?: Record<string, unknown>
   /** F153c: the package sources this build wrote (`pkg-src.ts`); absent = package imports are islands. */
   packages?: PackageSources
+  /** F256: `[build] source_roots`, normalised and relative to the app root (`../shared`). */
+  sourceRoots?: string[]
+  /** F230: `scanAppWrites`'s result; absent = no module is refused for a load-time write. */
+  loadWrites?: string
 }): { 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
   const packagesJson = opts.packages ? JSON.stringify(opts.packages) : undefined
+  const sourceRoots = opts.sourceRoots && opts.sourceRoots.length > 0 ? opts.sourceRoots : undefined
   // The Rust side keys each map by its path relative to the app root (`/`-separated), like an import resolves.
   const { aliases, notes } = readPathAliases(appRoot)
   for (const n of notes) opts.log(`warning tsconfig-paths ${n}`)
@@ -163,7 +189,7 @@ export function compileApp(opts: {
     let rootId = rootIdOfFile.get(file)
     if (!rootId) {
       const rel = relative(appRoot, file)
-      const tree = compileTree(rel, appRoot, opts.runtimeImport, opts.serverOnly, slotValuesJson, cssModules, iconSvgsJson, routeRoots, pathAliasesJson, packagesJson)
+      const tree = compileTree(rel, appRoot, opts.runtimeImport, opts.serverOnly, slotValuesJson, cssModules, iconSvgsJson, routeRoots, pathAliasesJson, packagesJson, sourceRoots, opts.loadWrites)
       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).
@@ -198,6 +224,7 @@ export function compileApp(opts: {
       serverTs: c.serverTs,
       evalTs: c.evalTs,
       clientJs: c.clientJs,
+      clientModules: c.clientModules?.length ? c.clientModules : undefined,
       diagnostics: c.diagnostics.map((d) => ({ class: d.class, rule: d.rule, message: d.message, line: d.line, col: d.col, remediation: d.remediation })),
     })
   }

package/src/build/config.ts

@@ -1,9 +1,11 @@
 // Build-time settings from `brust.toml` `[build]` (the runtime sections are `../config.ts`):
 //   [build]
 //   server_only = ["lib/server", "@acme/db"]   # import prefixes / app-root-relative paths
+//   source_roots = ["../shared"]                # F256: directories besides the app a relative import may reach (monorepo)
 // `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 { statSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
 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'
@@ -76,6 +78,8 @@ export interface BuildConfig {
   cache: CacheBuildConfig | null
   /** `[css] global` (L19, R19.1): app-root-relative stylesheets every route links first, in order. */
   cssGlobal: string[]
+  /** `[build] source_roots` (F256): directories outside the app a relative import may reach, normalised and relative to the app root (`../shared`). Empty = the app only. */
+  sourceRoots: string[]
 }
 
 const isTable = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v)
@@ -306,10 +310,43 @@ function parseCss(file: string, raw: unknown): string[] {
   return g.map((p: string) => p.trim())
 }
 
+/**
+ * `[build] source_roots` (F256): extra directories, relative to the app root, that a relative import may reach besides
+ * the app itself (`../shared` in a monorepo). Each is normalised (`../a/../shared` = `../shared`), must exist and be a
+ * directory, and confines imports the way the app root does: lexically, so `../shared/../secret` is outside it.
+ * An entry inside the app adds nothing and is dropped; the app root itself or an ancestor of it is refused (F272). Returns the roots that lie outside, `/`-separated.
+ */
+export function parseSourceRoots(file: string, appRoot: string, raw: unknown): string[] {
+  if (raw === undefined) return []
+  if (!Array.isArray(raw) || raw.some((p) => typeof p !== 'string' || p.trim() === '' || p.includes('\0')))
+    throw new BuildError('config', `${file}: build.source_roots must be an array of non-empty strings (paths relative to the app root)`)
+  const out = new Set<string>()
+  for (const p of raw as string[]) {
+    if (isAbsolute(p.trim())) throw new BuildError('config', `${file}: build.source_roots entry ${JSON.stringify(p)} must be relative to the app root`)
+    const abs = resolve(appRoot, p.trim())
+    let dir = false
+    try {
+      dir = statSync(abs).isDirectory()
+    } catch {}
+    if (!dir) throw new BuildError('config', `${file}: build.source_roots entry ${JSON.stringify(p)} (${abs}) is not an existing directory`)
+    if (abs === resolve(abs, '..')) throw new BuildError('config', `${file}: build.source_roots entry ${JSON.stringify(p)} is the filesystem root`)
+    const rel = relative(appRoot, abs).split(sep).join('/')
+    // F272: the app root or an ancestor of it (`.`, `..`, `../..`) contains every import the app can make, so it would
+    // switch F243's confinement off for that whole level; name the directory that is actually shared instead.
+    if (rel === '' || rel.split('/').every((seg) => seg === '..'))
+      throw new BuildError(
+        'config',
+        `${file}: build.source_roots entry ${JSON.stringify(p)} is the app root or a directory that contains it, which would allow every relative import; list the shared directory itself (e.g. "../shared")`,
+      )
+    if (rel === '..' || rel.startsWith('../')) out.add(rel)
+  }
+  return [...out].sort()
+}
+
 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, cssGlobal: [] }
+  if (!(await f.exists())) return { serverOnly: [], actions: null, cloudflare: null, cache: null, cssGlobal: [], sourceRoots: [] }
   let parsed: unknown
   try {
     parsed = Bun.TOML.parse(await f.text())
@@ -322,11 +359,12 @@ export async function loadBuildConfig(appRoot: string, o: { actionsOnly?: boolea
   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, cssGlobal }
+  if (build === undefined) return { serverOnly: [], actions, cloudflare, cache, cssGlobal, sourceRoots: [] }
   if (build === null || typeof build !== 'object' || Array.isArray(build)) throw new BuildError('config', `${file}: [build] must be a table`)
+  const sourceRoots = parseSourceRoots(file, appRoot, (build as Record<string, unknown>).source_roots)
   const so = (build as Record<string, unknown>).server_only
-  if (so === undefined) return { serverOnly: [], actions, cloudflare, cache, cssGlobal }
+  if (so === undefined) return { serverOnly: [], actions, cloudflare, cache, cssGlobal, sourceRoots }
   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, cssGlobal }
+  return { serverOnly: so.map((p: string) => p.trim().replace(/^\.\//, '')), actions, cloudflare, cache, cssGlobal, sourceRoots }
 }

package/src/build/esm-resolve.ts

@@ -5,21 +5,50 @@
 // 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.
-import { join } from 'node:path'
+// 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>()
 
-// argv: [target, entry, spec, define 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.
+/** 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] = process.argv.slice(1)
+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), files: { [entry]: source },
+  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
@@ -29,15 +58,113 @@ await Bun.build({
 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> = {}): string {
+export function resolveNative(spec: string, from: string, target: ResolveTarget, define: Record<string, string> = {}, opts: ResolveOpts = {}): string {
   const defs = JSON.stringify(define)
-  const key = `${target}\0${from}\0${spec}\0${defs}`
+  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 r = Bun.spawnSync([process.execPath, '-e', PROBE, target, join(from, '__brust_resolve__.ts'), spec, defs], { cwd: from, stdout: 'pipe', stderr: 'pipe' })
+  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() : ''
-  const path = out !== '' ? out : Bun.resolveSync(spec, from)
+  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/index.ts

@@ -14,7 +14,7 @@ import { type CfPrepared, buildCloudflare, prepareCloudflare } from './cloudflar
 import { renderIcons } from './build-icons'
 import { evaluateBuildSlots } from './build-eval'
 import { preparePackageSources } from './pkg-src'
-import { type Compiled, compileApp } from './compile'
+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'
@@ -112,7 +112,7 @@ export async function runBuild(opts: {
   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 } = built
+  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 =
@@ -121,7 +121,7 @@ export async function runBuild(opts: {
   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, componentIssue } = await scanRoutes(entry, appRoot)
+  const { routes, componentFile, componentIssue, appModules, appGraph } = await scanRoutes(entry, appRoot)
   let leaves: ReturnType<typeof validateRoutes>
   try {
     leaves = validateRoutes(routes)
@@ -173,7 +173,7 @@ export async function runBuild(opts: {
   rmSync(tmp, { recursive: true, force: true })
   mkdirSync(tmp, { recursive: true })
   try {
-    await buildInto(tmp, { dev: opts.dev === true, appRoot, entry, dist, leaves, componentFile, componentIssue, serverOnly, actions, actionsEntry, cache, cacheModule, cf, hybrid, cssGlobal, actionsRemote: remote?.prefix ?? null, 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
@@ -206,6 +206,10 @@ async function buildInto(
     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). */
@@ -216,6 +220,8 @@ async function buildInto(
     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). */
@@ -238,13 +244,46 @@ async function buildInto(
   // The runtime first: its hashed URL is the `runtimeImport` every client chunk is compiled with.
   const runtime = await buildRuntime(out, ctx)
   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)
+  // 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,
     componentIssue: o.componentIssue,
+    loadWrites,
     runtimeImport: runtimeUrls.core,
     serverOnly: o.serverOnly,
+    sourceRoots: o.sourceRoots,
     cssMaps: css.maps,
   }
   const firstLog: string[] = []
@@ -281,7 +320,7 @@ async function buildInto(
   mkdirSync(join(out, 'jinja'), { recursive: true })
   for (const c of compiled.values()) writeFileSync(join(out, 'jinja', `${c.id}.jinja`), c.jinja)
 
-  const chunks = new Map([...(await buildClientChunks(out, compiled, ctx, runtimeUrls)), ...(await buildReactChunks(out, compiled, ctx, runtimeUrls, routeRoots))])
+  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)
@@ -290,7 +329,7 @@ async function buildInto(
     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))
+  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, css.maps), prefix: o.actions.prefix, maxBodyBytes: o.actions.maxBodyBytes, maxResponseBytes: o.actions.maxResponseBytes, crossSite: o.actions.crossSite }

package/src/build/pkg-src.ts

@@ -19,6 +19,7 @@ import { createHash } from 'node:crypto'
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join, posix, relative, resolve, sep } from 'node:path'
 import { BuildError } from './errors'
+import { RELATIVE_SPEC } from './esm-resolve'
 
 /** What the compiler reads (`AnalyzeOptions.packages`): per importing scope (`""` = the app, else the root-relative
  * directory of a written package), each bare specifier → the root-relative path of its written entry source, or the
@@ -353,9 +354,11 @@ function writePackage(appRoot: string, dir: string, budget: { bytes: number }):
       // The JSX transform's own runtime import (the transpiler adds it), and React itself.
       if (NEVER(im.path)) continue
       if (im.kind === 'dynamic-import' || im.kind === 'require-call' || im.kind === 'require-resolve') return { ok: false, reason: `${f.path} has a ${im.kind} (${im.path})` }
-      if (im.path.startsWith('./') || im.path.startsWith('../')) {
+      if (RELATIVE_SPEC.test(im.path)) {
         const base = posix.normalize(posix.join(posix.dirname(f.path), im.path))
-        const hit = [base, `${base}.tsx`, `${base}.ts`, `${base}/index.tsx`, `${base}/index.ts`].find((c) => have.has(c))
+        // `.` and `..` name a directory (F244): only its index answers, never a sibling file of the same name.
+        const dirOnly = im.path === '.' || im.path === '..'
+        const hit = [...(dirOnly ? [] : [base, `${base}.tsx`, `${base}.ts`]), posix.join(base, 'index.tsx'), posix.join(base, 'index.ts')].find((c) => have.has(c))
         if (hit) imported.add(hit)
         else return { ok: false, reason: `${f.path} imports ${im.path}, which the source map does not carry` }
       } else if (im.path.startsWith('/') || /^[a-z]+:/i.test(im.path)) return { ok: false, reason: `${f.path} imports ${im.path}` }

package/src/build/scan.ts

@@ -10,7 +10,7 @@ import { installServerOnlyRuntime } from './server-only'
 export async function scanRoutes(
   entryFile: string,
   appRoot?: string,
-): Promise<{ routes: Route[]; componentFile: Map<Function, string>; componentIssue: Map<Function, string> }> {
+): Promise<{ routes: Route[]; componentFile: Map<Function, string>; componentIssue: Map<Function, string>; appModules: string[]; appGraph: Map<string, string[]> }> {
   // biome-ignore lint/suspicious/noExplicitAny: an arbitrary user module
   let mod: any
   installServerOnlyRuntime() // `server-only` resolves to an empty module: a loader may import server-only code
@@ -31,6 +31,8 @@ export async function scanRoutes(
   const transpiler = new Bun.Transpiler({ loader: 'tsx' })
   const inRoot = (f: string) => f.startsWith(root + sep) && !f.split(sep).includes('node_modules')
   const visited = new Set<string>()
+  // F230: each in-root module's in-root static imports (absolute paths), for the island chunks' load-time writers.
+  const appGraph = new Map<string, string[]>()
   // Post-order: a file's imports are mapped before the file itself, and the first file to claim a function
   // keeps it, so the module that defines a Component beats a barrel that re-exports it.
   const visit = async (file: string): Promise<void> => {
@@ -58,6 +60,7 @@ export async function scanRoutes(
       if (inRoot(dep)) deps.push(dep)
       else if (dep.endsWith('.tsx')) await note(dep, dep.split(sep).includes('node_modules') ? 'in node_modules' : `outside the app root ${root}`)
     }
+    appGraph.set(file, deps)
     for (const dep of deps) await visit(dep)
     if (!file.endsWith('.tsx')) return
     const m = await import(file)
@@ -79,5 +82,7 @@ export async function scanRoutes(
   await visit(entryFile)
   // A function reachable as a default somewhere is fine; only an unmapped one keeps its explanation.
   for (const f of componentFile.keys()) componentIssue.delete(f)
-  return { routes, componentFile, componentIssue }
+  // F230: every app module of the static graph (`.ts`/`.tsx` inside the root, outside node_modules), for the scan of
+  // load-time writes into another module's exports (`scanLoadWrites`).
+  return { routes, componentFile, componentIssue, appModules: [...visited].filter(inRoot), appGraph }
 }

package/src/cli.ts

@@ -6,7 +6,6 @@ import { BuildError, runBuild } from './build'
 import { runBunDev } from './dev/bun'
 import { runDev } from './dev'
 import { run } from './run'
-import { shadcnInit, spawnRunner } from './shadcn/init'
 
 const USAGE = `usage:
   brust build [entry=routes.tsx] [--out-dir dist] [--force] [--target bun|cloudflare|static] [--actions-only] [--strict] [--wasm-from-source] [--dev]
@@ -135,6 +134,8 @@ export async function main(argv: string[]): Promise<void> {
   if (cmd === 'shadcn') {
     const [sub, ...components] = positionals
     if (sub !== 'init') usage(`shadcn takes a subcommand: init (got ${sub === undefined ? 'none' : JSON.stringify(sub)})`)
+    // F252: loaded here, so no other command pays for it (it pulls in tsconfig-paths)
+    const { shadcnInit, spawnRunner } = await import('./shadcn/init')
     const code = await shadcnInit({
       root: process.cwd(),
       components,

package/src/dev/bun.ts

@@ -10,7 +10,8 @@ import { type Diag, parseBuildError, parseWarnings } from './diag'
 import { tierCounts } from './devtools-data'
 import { type DevProxy, startProxy } from './proxy'
 import { HOTKEYS, Tui, type TuiOut, tuiMode } from './tui'
-import { defaultIgnored, watchLoop } from './watch'
+import { loadBuildConfig } from '../build/config'
+import { broadRootWarnings, defaultIgnored, watchLoop } from './watch'
 
 export interface BunDevOptions {
   appRoot: string
@@ -290,8 +291,12 @@ export async function runBunDev(o: BunDevOptions): Promise<number> {
 
   const isCss = (rel: string) => rel.startsWith('public/') && rel.endsWith('.css')
 
+  // F273: `[build] source_roots` are watched too (a bad config is the build's error to report, not the watcher's)
+  const extraRoots = await loadBuildConfig(appRoot).then((c) => c.sourceRoots.map((r) => resolve(appRoot, r)), () => [] as string[])
+  for (const w of broadRootWarnings(extraRoots, appRoot)) tui.log(w)
   const loop = watchLoop({
     root: appRoot,
+    extraRoots,
     ignored: (rel) => defaultIgnored(rel, 'dist'),
     debounceMs: DEBOUNCE_MS,
     async run(changed) {

package/src/dev/watch.ts

@@ -2,8 +2,8 @@
 // ONE run at a time, and every change that arrives while a run is in flight is kept for the next
 // run (post-mortem 8f29c26: an edit during a rebuild was dropped). `run` receives the app-relative
 // paths that changed since the previous run started.
-import { type FSWatcher, statSync, watch } from 'node:fs'
-import { join, sep } from 'node:path'
+import { type FSWatcher, readdirSync, statSync, watch } from 'node:fs'
+import { join, relative, resolve, sep } from 'node:path'
 
 export interface WatchLoop {
   /** Queue a run as if `rel` changed (the `r` hotkey, tests). */
@@ -14,7 +14,36 @@ export interface WatchLoop {
   idle(): Promise<void>
 }
 
-export function watchLoop(o: { root: string; ignored: (rel: string) => boolean; debounceMs: number; run: (changed: Set<string>) => Promise<void> }): WatchLoop {
+/** F273: a source root holding more files than this gets a warning (a root that broad slows every rebuild check). */
+export const ROOT_FILE_WARN = 5_000
+
+/** Files under `dir` (skipping dependency/VCS dirs), counting stops once past `limit`. */
+export function countFiles(dir: string, limit: number): number {
+  let n = 0
+  const walk = (d: string): void => {
+    let ents: import('node:fs').Dirent[]
+    try {
+      ents = readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of ents) {
+      if (n > limit) return
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk(join(d, e.name))
+      } else n++
+    }
+  }
+  walk(dir)
+  return n
+}
+
+/** Warning lines for source roots broader than `ROOT_FILE_WARN` files; `roots` are absolute. */
+export function broadRootWarnings(roots: string[], appRoot: string, limit = ROOT_FILE_WARN): string[] {
+  return roots.flatMap((r) => (countFiles(r, limit) > limit ? [`[brust] warning: source root ${relative(appRoot, r) || r} holds more than ${limit} files; watching it slows every change check. Point source_roots at a narrower directory`] : []))
+}
+
+export function watchLoop(o: { root: string; /** F273: `[build] source_roots`, absolute: watched too; their changes are reported app-relative (`../shared/x.ts`). */ extraRoots?: string[]; ignored: (rel: string) => boolean; debounceMs: number; run: (changed: Set<string>) => Promise<void> }): WatchLoop {
   let pending = new Set<string>()
   let timer: ReturnType<typeof setTimeout> | undefined
   let running = false
@@ -44,24 +73,36 @@ export function watchLoop(o: { root: string; ignored: (rel: string) => boolean;
     clearTimeout(timer)
     timer = setTimeout(() => void pump(), o.debounceMs)
   }
-  const watcher: FSWatcher = watch(o.root, { recursive: true }, (_ev, name) => {
+  const onEvent = (base: string) => (_ev: string, name: string | null) => {
     if (!name) return
-    const rel = String(name).split(sep).join('/')
+    const abs = join(base, String(name))
+    const rel = (base === o.root ? String(name) : relative(o.root, abs)).split(sep).join('/')
     if (o.ignored(rel)) return
     // A directory's own event is metadata noise (reading a dir bumps its atime, which FSEvents reports): a real
     // change inside it reports the file itself. A path that no longer exists is a delete, which counts.
     try {
-      if (statSync(join(o.root, rel)).isDirectory()) return
+      if (statSync(abs).isDirectory()) return
     } catch {}
     queue(rel)
-  })
+  }
+  const watchers: FSWatcher[] = [watch(o.root, { recursive: true }, onEvent(o.root))]
+  for (const r of o.extraRoots ?? []) {
+    const abs = resolve(r)
+    // a root inside the app is already watched; one that cannot be watched must not stop the session
+    if (abs === o.root || abs.startsWith(o.root + sep)) continue
+    try {
+      watchers.push(watch(abs, { recursive: true }, onEvent(abs)))
+    } catch (e) {
+      console.error(`[brust] cannot watch source root ${abs}: ${(e as Error).message}`)
+    }
+  }
   return {
     trigger: (rel = '.') => queue(rel),
     close() {
       closed = true
       clearTimeout(timer)
       pending.clear()
-      watcher.close()
+      for (const w of watchers) w.close()
       for (const w of idleWaiters.splice(0)) w()
     },
     idle: () => (!running && pending.size === 0 ? Promise.resolve() : new Promise<void>((r) => idleWaiters.push(r))),