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

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,27 @@ 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, sourceRoots: string[] = []): 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('/')
+  // F276: a module under a `[build] source_roots` directory (`../shared/x.ts`) is scanned too; any other `..` key is not.
+  const inSourceRoot = (k: string) => sourceRoots.some((r) => k.startsWith(`${r}/`))
+  const rel = [...new Set(modules.flatMap((f) => [toKey(appRoot, f), toKey(real, realpathSync(f))]))].filter((k) => !k.startsWith('..') || inSourceRoot(k)).sort()
+  const { aliases } = readPathAliases(appRoot)
+  const t0 = performance.now()
+  const json = scanLoadWrites(appRoot, rel, aliases.length > 0 ? JSON.stringify(aliases) : undefined, sourceRoots.length > 0 ? sourceRoots : 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 +154,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 +191,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 +226,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/features.ts

@@ -5,7 +5,7 @@
 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'] as const
+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). */
@@ -25,6 +25,10 @@ export function featureOfAttr(attr: string): RuntimeFeature | null | undefined {
     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)-/.test(attr) ? 'basics' : 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, sourceRoots)
   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, 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,
     componentIssue: o.componentIssue,
+    loadWrites,
     runtimeImport: runtimeUrls.core,
     serverOnly: o.serverOnly,
+    sourceRoots: o.sourceRoots,
     cssMaps: css.maps,
   }
   const firstLog: string[] = []
@@ -254,7 +293,7 @@ async function buildInto(
   // 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) {
+  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) }))
   }
@@ -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,8 @@ 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'
+import { RECOGNISED, verifyRecognised } from './recognised'
 
 /** 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
@@ -26,6 +28,9 @@ import { BuildError } from './errors'
 export interface PackageSources {
   scopes: Record<string, Record<string, string>>
   refused: Record<string, Record<string, string>>
+  /** R34.140: packages the compiler recognises by version + hash instead of reading (`recognised.ts`), name → version. A
+   * name is here only when EVERY copy of it the build met verified. */
+  recognised: Record<string, string>
   /** Each written directory (root-relative) → the package's real directory: a bare import in an artifact compiled from
    * a package source resolves from the package, as it does in a real install (not read by the compiler). */
   dirs: Record<string, string>
@@ -219,11 +224,27 @@ export function integrityGaps(sources: { path: string; text: string }[], publish
     // Import specifiers are module names, which bundling replaces; they are checked as imports instead.
     for (const im of new Bun.Transpiler({ loader }).scanImports(s.text)) sk.strings.delete(im.path)
     for (const v of sk.strings) if (!pub.strings.has(v)) gaps.push(`${s.path}: literal ${JSON.stringify(v.startsWith('#') ? v.slice(1) : v).slice(0, 60)}`)
-    for (const v of sk.names) if (!JSX_NAMES.has(v) && !JSX_RUNTIME.test(v) && !KEYWORDS.has(v) && !pub.names.has(v)) gaps.push(`${s.path}: name \`${v}\``)
+    const aliases = importAliases(transpile(s.text, loader), pub.names)
+    for (const v of sk.names) if (!JSX_NAMES.has(v) && !JSX_RUNTIME.test(v) && !KEYWORDS.has(v) && !pub.names.has(v) && !aliases.has(v)) gaps.push(`${s.path}: name \`${v}\``)
   }
   return gaps
 }
 
+/** R34.142 (W1b): `import { X as Y } from './sibling'` names the same binding as `X` under a local name. A bundler resolves
+ * the binding to the sibling's declaration, so `Y` is not in the published file; `X` is. `Y` is dropped from the name check
+ * ONLY for a RELATIVE import DECLARATION at the start of a line (a sibling of the same package, bundled in) whose imported name `X` the published file has.
+ * An alias of anything else stays a name difference. */
+function importAliases(js: string, pubNames: Set<string>): Set<string> {
+  const out = new Set<string>()
+  for (const m of js.matchAll(/^import\s*\{([^}]*)\}\s*from\s*["'](\.[^"']*)["']/gm)) {
+    for (const item of m[1]!.split(',')) {
+      const parts = item.trim().split(/\s+as\s+/)
+      if (parts.length === 2 && /^[A-Za-z_$][\w$]*$/.test(parts[1]!) && pubNames.has(parts[0]!)) out.add(parts[1]!)
+    }
+  }
+  return out
+}
+
 
 /** The `local as exported` pairs of the `export { … }` clauses of transpiled JS (`x` alone is `x as x`). */
 function exportPairs(js: string): Set<string> {
@@ -353,9 +374,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}` }
@@ -398,6 +421,20 @@ function writePackage(appRoot: string, dir: string, budget: { bytes: number }):
   return { ok: true, dir: outRel, entry: posix.join(outRel, (entrySrc ?? barrel)!.path), imports: [...bare].sort() }
 }
 
+/** The verified version of the pinned package at `dir` (`RECOGNISED`), `null` when its version or entry bytes differ. */
+function recognisedVersion(name: string, dir: string): string | null {
+  try {
+    const pj = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as Record<string, unknown>
+    const entryRel = esmEntry(pj)
+    if (!entryRel) return null
+    const entry = join(dir, entryRel)
+    if (!statSync(entry).isFile()) return null
+    return verifyRecognised(name, pj.version, readFileSync(entry))
+  } catch {
+    return null
+  }
+}
+
 /**
  * Writes the sources of every package `specs` reaches from the app (and of every package those sources import),
  * and returns the resolution map for the compiler. The directory is rebuilt from nothing on every call.
@@ -417,7 +454,8 @@ export function preparePackageSources(appRoot: string, specs: Iterable<string>):
   rmSync(join(root, PKG_SRC_DIR), { recursive: true, force: true })
   mkdirSync(join(root, PKG_SRC_DIR), { recursive: true })
   if (!realpathSync(join(root, PKG_SRC_DIR)).startsWith(root + sep)) throw new BuildError('package-source', `${PKG_SRC_DIR} resolves outside the app root (a link?); remove it and build again`)
-  const out: PackageSources = { scopes: {}, refused: {}, dirs: {} }
+  const out: PackageSources = { scopes: {}, refused: {}, dirs: {}, recognised: {} }
+  const recognisedBad = new Set<string>()
   writtenDirs.clear()
   const byDir = new Map<string, Outcome>()
   const budget = { bytes: 0 }
@@ -443,6 +481,14 @@ export function preparePackageSources(appRoot: string, specs: Iterable<string>):
       continue
     }
     let o = byDir.get(dir)
+    if (!o && Object.hasOwn(RECOGNISED, name)) {
+      // R34.140: not read: pinned by version and hash. The refusal stays (its imports stay islands where nothing recognises them).
+      const v = recognisedVersion(name, dir)
+      if (v) out.recognised[name] ??= v
+      else recognisedBad.add(name)
+      o = { ok: false, reason: v ? `recognised by the compiler (${name}@${v}), not read` : `${name} is not the pinned release the compiler recognises` }
+      byDir.set(dir, o)
+    }
     if (!o) {
       try {
         o = byDir.size >= LIMITS.packages ? { ok: false, reason: `more than ${LIMITS.packages} packages` } : writePackage(root, dir, budget)
@@ -461,6 +507,7 @@ export function preparePackageSources(appRoot: string, specs: Iterable<string>):
     if (o.ok) (out.scopes[scope] ??= {})[spec] = o.entry
     else refuse(o.reason)
   }
+  for (const n of recognisedBad) delete out.recognised[n]
   mkdirSync(join(root, PKG_SRC_DIR), { recursive: true })
   writeFileSync(join(root, PKG_SRC_DIR, 'index.json'), `${JSON.stringify(out, null, 2)}\n`)
   return out

package/src/build/recognised.ts

@@ -0,0 +1,19 @@
+// Packages the compiler RECOGNISES by what they are rather than reading their source (R34.140). A recognised package is
+// pinned: the installed package.json `version` AND the SHA-256 of its published ESM entry must be one of the pairs below.
+// Any other version, or the same version with another byte in the entry, is not recognised (its import stays the React
+// island it is without it). The compiler is told only the package name and the verified version (`index.json#recognised`).
+import { createHash } from 'node:crypto'
+
+/** package name → published version → SHA-256 (hex) of the file `module` / `exports['.'].import` names. */
+export const RECOGNISED: Record<string, Record<string, string>> = {
+  // `createCollection` (the 3-tuple form roving focus, accordion, menus and slider use) of the 1.2.0 release
+  '@radix-ui/react-collection': { '1.2.0': '52a6719c7c1a7a5202ab5ae58bb552f0d7853965a0833cf0e71749ac580e349f' },
+}
+
+/** The verified version of `name` when `version` and the bytes of its ESM `entry` are a pinned pair; else `null`. */
+export function verifyRecognised(name: string, version: unknown, entryBytes: Uint8Array): string | null {
+  const pins = RECOGNISED[name]
+  if (!pins || typeof version !== 'string' || !Object.hasOwn(pins, version)) return null
+  const sha = createHash('sha256').update(entryBytes).digest('hex')
+  return sha === pins[version] ? version : null
+}