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

package/src/build/cf-assets.ts

@@ -21,8 +21,10 @@ export function isHashed(file: string): boolean {
 
 const segOk = (s: string) => s !== '' && !s.startsWith('.') && SEG.test(s)
 
-/** `client/<file>.js|.css`: `is_safe_island_filename` / `is_safe_css_filename`. */
-const clientOk = (f: string) => segOk(f) && !f.includes('..') && (f.endsWith('.js') || f.endsWith('.css'))
+/** `client/<file>.js|.css`: `is_safe_island_filename` / `is_safe_css_filename`, plus the fonts and images a
+ * stylesheet references (`is_safe_client_asset_filename`, L19). */
+const CLIENT_EXT = /\.(js|css|woff2|woff|ttf|otf|eot|png|jpg|jpeg|gif|webp|avif|svg|ico)$/
+const clientOk = (f: string) => segOk(f) && !f.includes('..') && CLIENT_EXT.test(f)
 
 function walk(dir: string, rel = ''): string[] {
   const out: string[] = []

package/src/build/cf-entry.ts

@@ -28,6 +28,8 @@ export interface CfEntryInput {
   entry: string
   jobsEntry: string
   actionsEntry: string | null
+  /** L16: no pages: the routes module and the jobs module are not imported; the handlers serve an empty route table. */
+  actionsOnly?: boolean
   prefix: string
   manifestPath: string
   templatesPath: string
@@ -41,16 +43,18 @@ export function cfEntrySource(i: CfEntryInput): string {
   const q = JSON.stringify
   const actions = i.actionsEntry !== null
   const c = i.cache ?? null
+  const pages = i.actionsOnly !== true
   return `${[
     '// generated by `brust build --target cloudflare` — do not edit (M4-CF spec §4)',
-    `import * as R from ${q(i.entry)}`,
-    `import J, * as JM from ${q(i.jobsEntry)}`,
+    ...(pages ? [`import * as R from ${q(i.entry)}`, `import J, * as JM from ${q(i.jobsEntry)}`] : []),
     ...(actions ? [`import A from ${q(i.actionsEntry)}`] : []),
     `import M from ${q(i.manifestPath)}`,
     `import T from ${q(i.templatesPath)}`,
     `import { fetchInScope, flattenRoutes, jsonCall, makeHandlers, noActions } from "@brust/core/server-handlers"`,
     ...(actions ? ['import { mountActions } from "@brust/core/server-handlers/actions"'] : []),
-    'const h = makeHandlers({ leaves: flattenRoutes(R.routes ?? R.default).leaves, jobs: J, manifest: M, stores: JM.stores ?? {} })',
+    pages
+      ? 'const h = makeHandlers({ leaves: flattenRoutes(R.routes ?? R.default).leaves, jobs: J, manifest: M, stores: JM.stores ?? {} })'
+      : 'const h = makeHandlers({ leaves: [], jobs: {}, manifest: M, stores: {} })',
     ...(actions ? [`const app = mountActions(A, ${q(i.prefix)}).compile() // startup-phase compile (R9)`] : []),
     'export const loader = jsonCall(h.loader)',
     'export const jobs = jsonCall(h.jobs)',

package/src/build/cf-wrangler.ts

@@ -20,6 +20,8 @@ export interface MergeOpts {
   /** worker-build entry, relative to `worker/` (core-cf `brust.main`) */
   main: string
   version: string
+  /** L16: an actions-only Worker has no Static Assets (and no ASSETS binding). */
+  noAssets?: boolean
 }
 
 const OWNED = ['main', 'assets', 'compatibility_date', 'no_bundle', 'find_additional_modules', 'base_dir', 'rules', 'build', 'site']
@@ -106,7 +108,7 @@ export function mergeWrangler(user: UserWrangler, o: MergeOpts): { config: Json;
     ...(name !== undefined ? { name } : {}),
     main: `worker/${o.main}`,
     compatibility_date: o.compatibilityDate,
-    assets: { directory: 'assets', binding: 'ASSETS', run_worker_first: false, html_handling: 'none', not_found_handling: 'none' },
+    ...(o.noAssets ? {} : { assets: { directory: 'assets', binding: 'ASSETS', run_worker_first: false, html_handling: 'none', not_found_handling: 'none' } }),
     ...Object.fromEntries(Object.entries(rest).filter(([k]) => k !== 'name')),
   }
   return { config, warnings }

package/src/build/cloudflare.ts

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

package/src/build/compile.ts

@@ -2,10 +2,13 @@
 // `compileTree` (analysis + lowering of its whole tree). `Err` = build error; fallback and
 // warning diagnostics are logged; `outlet-outside-layout` is raised here (contract 5).
 // A component several trees reach keeps one compile, chosen by role, not by route order (F75).
-import { relative } from 'node:path'
-import { type CompiledComponent, type CompiledTree, compileTree } from '../../native/index.js'
+import { readFileSync, realpathSync } from 'node:fs'
+import { dirname, relative, sep } from 'node:path'
+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'
+import type { PackageSources } from './pkg-src'
 
 /** `ComponentIR` as the compiler serialises it (snake_case), with the fields that are absent
  * when default (`ir/mod.rs`) normalised. The build reads it; it never rewrites it. */
@@ -17,13 +20,44 @@ export type ComponentIR = Record<string, any> & {
   tier: any
   // biome-ignore lint/suspicious/noExplicitAny: IR JSON
   jobs: any[]
-  instances: { child_id: string; k: number; loops: (string | null)[]; props: Record<string, string | null> }[]
+  instances: {
+    child_id: string
+    k: number
+    loops: (string | null)[]
+    props: Record<string, string | null>
+    literals?: Record<string, unknown>
+    exprs?: Record<string, string>
+    /** F142 R34.43: the rows of a constant enclosing list (`loops` is then `[null]`). */
+    rows_literal?: unknown[]
+  }[]
+  /** F149: inlined instances whose child job the build may run once (`decls.rs` `BuildEvalInstance`). */
+  build_eval_instances?: {
+    key: string
+    child_id: string
+    k: number
+    inputs: Record<string, unknown>
+    outputs: string[]
+    stubs?: { source: string; code: string }[]
+    /** R34.96: the job modules fused into the child's job, which it imports (`FusedEvalJob`). */
+    fused?: { child_id: string; stubs?: { source: string; code: string }[] }[]
+    line: number
+    col: number
+  }[]
   use_id_slots: number
   uses_outlet: boolean
   needs_worker: boolean
   /** `useStore(handle)` bindings (`decls.rs` `StoreUse`); `resolved` = `StoreRef`, `null` when
    * unresolved (the component falls back). `module` is root-relative (C3). */
   stores?: { handle: string; resolved: { name: string; module: string } | null }[]
+  /** A package export rendered as a React island (L22): `source` is then not a file. */
+  external?: { source: string; export: string; member?: string[] }
+  /** A component compiled from a package source and written in app code as a package import (F188): the published
+   * export a React island or revive hook imports instead of the source. */
+  dist?: { source: string; export: string; member?: string[] }
+  /** The binding a React island imports this component by from `source` (absent: the default export). */
+  export?: string
+  /** Child components; `nested` is set when this file passes lowered JSX children to that child, an island (shadcn S1). */
+  children?: { id: string | null; nested?: string[]; x?: string[]; holes?: string[]; [field: string]: unknown }[]
 }
 
 export interface Compiled {
@@ -33,11 +67,23 @@ export interface Compiled {
   ir: ComponentIR
   jinja: string
   serverTs?: string
+  /** Build-time evaluation module (L2): one thunk per `ir.build_eval` slot. */
+  evalTs?: string
   clientJs?: string
+  /** F362 PR2: `clientJs` importing every imported list as written; the build uses it when a module in
+   * `projectedModules` is still in the client graph through another importer (`bundle.ts` `buildClientChunks`). */
+  clientJsWhole?: string
+  /** F362 PR2: data modules (app-root-relative) whose imported list `clientJs` declares projected instead of importing. */
+  projectedModules?: 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; file?: string | null }[]
 }
 
 type Diag = NonNullable<CompiledTree['error']>
-const where = (file: string, d: Diag) => `${file}:${d.line}:${d.col}`
+/** `file:line:col`; a finding raised in another module than the component it is reported on names that module (F395). */
+const where = (file: string, d: Diag) => `${d.file ?? file}:${d.line}:${d.col}`
 
 /** How a tree reached a component (F75). A route root's props are fixed, so after F70 it may drop
  * the row links a parent elsewhere drives; a child that no parent in its tree links may have no
@@ -74,15 +120,61 @@ 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[]
   componentFile: Map<Function, string>
+  /** Why a Component the scan saw has no file (named export only, outside the root); optional. */
+  componentIssue?: Map<Function, string>
   runtimeImport: string
   serverOnly: string[]
+  /** L20: every CSS Module's class map by absolute source path; `styles.x` folds to the literal class. */
+  cssMaps?: Map<string, Record<string, string>>
   log: (s: string) => void
+  /** SVG markup the build rendered for lucide icon requests (L23), by `ir.icon_requests[].key`. */
+  iconSvgs?: Record<string, { svg: string; base: string }>
+  /** The compile after icons were rendered (even if none could be): icons still components are judged as islands. */
+  iconsFinal?: boolean
+  /** Values the build computed for `ir.build_eval` slots, by key (L2): the slots become literals. */
+  slotValues?: Record<string, unknown>
+  /** 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}`)
+  const pathAliasesJson = aliases.length > 0 ? JSON.stringify(aliases) : undefined
+  const cssModules = Object.fromEntries([...(opts.cssMaps ?? [])].map(([abs, map]) => [relative(realpathSync(appRoot), abs).split(sep).join('/'), map]))
   const seen = new Map<string, Seen>()
   const rootIdOfFile = new Map<string, string>()
   const routeComponent = new Map<string, string>()
@@ -90,17 +182,22 @@ export function compileApp(opts: {
   const nodes = new Map<string, Route>()
   for (const l of leaves) l.chain.forEach((r, i) => r.Component && nodes.set(l.chainIds[i]!, r))
 
+  // F158 (R34.69): the route components (pages and layouts) take request data as props, so the compiler never hands
+  // them lowered JSX from a caller. Keyed like an import resolves: relative to the app root, `/`-separated.
+  const rootRel = (f: string) => relative(appRoot, f).split(sep).join('/')
+  const routeRoots = [...new Set([...nodes.values()].flatMap((r) => componentFile.get(r.Component!) ?? []).flatMap((f) => [rootRel(f), relative(realpathSync(appRoot), realpathSync(f)).split(sep).join('/')]))]
+
   for (const [routeId, route] of nodes) {
     const file = componentFile.get(route.Component!)
     if (!file)
       throw new BuildError(
         'component-source',
-        `${route.Component!.name || '(anonymous)'} is not a default import of a .tsx file (route ${routeId})`,
+        `${opts.componentIssue?.get(route.Component!) ?? `${route.Component!.name || '(anonymous)'} is not the default export of a .tsx file in the import graph`} (route ${routeId})`,
       )
     let rootId = rootIdOfFile.get(file)
     if (!rootId) {
       const rel = relative(appRoot, file)
-      const tree = compileTree(rel, appRoot, opts.runtimeImport, opts.serverOnly)
+      const tree = compileTree(rel, appRoot, opts.runtimeImport, opts.serverOnly, slotValuesJson, cssModules, iconSvgsJson, 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).
@@ -122,6 +219,7 @@ export function compileApp(opts: {
     for (const d of c.diagnostics)
       if (d.class === 'fallback' || d.class === 'warning') opts.log(`warning ${d.rule} ${where(c.source, d)} ${d.message}`)
     const ir = JSON.parse(c.ir) as ComponentIR
+    if (ir.alias_imports?.length) checkAliasAgreement(appRoot, ir.alias_imports)
     ir.use_id_slots ??= 0
     ir.uses_outlet ??= false
     ir.instances ??= []
@@ -132,9 +230,21 @@ export function compileApp(opts: {
       ir,
       jinja: c.jinja,
       serverTs: c.serverTs,
+      evalTs: c.evalTs,
       clientJs: c.clientJs,
+      clientJsWhole: c.clientJsWhole ?? undefined,
+      projectedModules: c.projectedModules?.length ? c.projectedModules : undefined,
+      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, file: d.file })),
     })
   }
+  // A package export has no file of its own: bare imports in its island entries resolve from a
+  // component that uses it (the first one in build order).
+  for (const c of compiled.values()) {
+    if (!c.ir.external) continue
+    const user = [...compiled.values()].find((p) => !p.ir.external && (p.ir.children ?? []).some((ref: { id: string | null }) => ref.id === c.id))
+    c.file = user?.file ?? c.file
+  }
   for (const [routeId, route] of nodes) {
     const rootId = routeComponent.get(routeId)!
     if (compiled.get(rootId)!.ir.uses_outlet && !route.children)
@@ -143,5 +253,152 @@ export function compileApp(opts: {
         `${route.Component!.name || rootId} renders <Outlet/> but route ${routeId} has no children`,
       )
   }
+  checkLayoutContexts(leaves, compiled, routeComponent)
   return { compiled, routeComponent }
 }
+
+/** Script modules only (`.ts/.tsx/.js/.jsx/.mjs/.cjs/.mts/.cts`), judged on the RESOLVED file (a dotted basename like `./theme.context`
+ * resolves to theme.context.tsx; a stylesheet, JSON or asset resolves to itself): those never read a context. */
+const SCRIPT = /\.[cm]?[jt]sx?$/
+
+let importScanner: InstanceType<typeof Bun.Transpiler> | undefined
+/** The module specifiers `file` imports or re-exports (`undefined`: unreadable or unparsable). */
+function moduleSpecs(file: string): string[] | undefined {
+  try {
+    importScanner ??= new Bun.Transpiler({ loader: 'tsx' })
+    return importScanner.scanImports(readFileSync(file, 'utf8')).map((i) => i.path)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * F437 (module-level rule): whether the island `file` imports ANY binding (a hook, the context, a helper) from a module that
+ * declares a context a layout above provides, directly or through re-exporting modules (followed transitively, each app file
+ * once). A relative specifier that cannot be resolved, or a barrel that cannot be read, is refused too.
+ */
+function importsProvidedModule(
+  file: string,
+  provided: { file: string; layout: string; contexts: string[] }[],
+): { spec: string; via?: string; hit: { file: string; layout: string; contexts: string[] } } | undefined {
+  const real = (f: string) => {
+    try {
+      return realpathSync(f)
+    } catch {
+      return f
+    }
+  }
+  const resolve = (spec: string, from: string) => {
+    try {
+      return real(Bun.resolveSync(spec, dirname(from)))
+    } catch {
+      return undefined
+    }
+  }
+  const unfollowable = { file: '', layout: '(unresolved re-export)', contexts: ['?'] }
+  type Hit = { file: string; layout: string; contexts: string[] }
+  // The app modules `from` imports or re-exports, followed transitively (a barrel behind barrels) with a visited set.
+  const reach = (from: string, visited: Set<string>): { hit: Hit; via: string } | undefined => {
+    const specs = moduleSpecs(from)
+    if (specs === undefined) return { hit: unfollowable, via: from }
+    for (const spec of specs) {
+      const target = resolve(spec, from)
+      if (target === undefined) {
+        if (spec.startsWith('.')) return { hit: unfollowable, via: from }
+        continue
+      }
+      if (!SCRIPT.test(target)) continue
+      const hit = provided.find((p) => p.file === target)
+      if (hit) return { hit, via: from }
+      if (target.includes(`${sep}node_modules${sep}`) || visited.has(target)) continue
+      visited.add(target)
+      const deeper = reach(target, visited)
+      if (deeper) return deeper
+    }
+    return undefined
+  }
+  for (const spec of moduleSpecs(file) ?? []) {
+    const target = resolve(spec, file)
+    if (target === undefined) {
+      if (spec.startsWith('.')) return { spec, hit: unfollowable }
+      continue
+    }
+    if (!SCRIPT.test(target)) continue
+    const direct = provided.find((p) => p.file === target)
+    if (direct) return { spec, hit: direct }
+    if (target.includes(`${sep}node_modules${sep}`)) continue
+    const found = reach(target, new Set([file, target]))
+    if (found) return { spec, via: relative(dirname(file), target), hit: found.hit }
+  }
+  return undefined
+}
+
+/**
+ * F437: a component the compiler refused to lower because it reads a context imported from another module
+ * (`useContext(Ctx)`, `ir.foreign_ctx_reads`) ships as a React island, and an island's SSR and `hydrateRoot` render it
+ * alone, without the Providers a layout above its route renders: it would paint the `createContext` default where React
+ * paints the layout's value. Refused here, by name, conservatively: a Provider anywhere in the layout's compiled tree
+ * (`ir.provides` of the layout or of any component it renders) declared in a file counts as providing every context that
+ * file declares, so a read of ANY binding imported from that file is refused (an alias, `export { A as B }`, a re-export of
+ * the file's own context cannot slip by). A context nobody provides still reads its default, which is React's own answer.
+ * Native resolution of an imported context is F439.
+ */
+function checkLayoutContexts(leaves: FlatRoute[], compiled: Map<string, Compiled>, routeComponent: Map<string, string>): void {
+  const real = (f: string) => {
+    try {
+      return realpathSync(f)
+    } catch {
+      return f
+    }
+  }
+  for (const leaf of leaves) {
+    const provided: { file: string; layout: string; contexts: string[] }[] = []
+    for (const id of leaf.chainIds) {
+      const rootId = routeComponent.get(id)
+      const root = rootId === undefined ? undefined : compiled.get(rootId)
+      if (!root) continue
+      // The tree of this route's component: the layouts above it provided `provided` so far.
+      if (provided.length > 0) {
+        const stack = [root.id]
+        const done = new Set<string>()
+        while (stack.length > 0) {
+          const c = compiled.get(stack.pop()!)
+          if (!c || done.has(c.id)) continue
+          done.add(c.id)
+          for (const [src, name] of (c.ir.foreign_ctx_reads ?? []) as [string, string][]) {
+            let from: string
+            try {
+              from = real(Bun.resolveSync(src, dirname(c.file)))
+            } catch {
+              continue
+            }
+            const hit = provided.find((p) => p.file === from)
+            if (hit)
+              throw new BuildError(
+                'island-layout-context',
+                `${c.ir.source} reads the context \`${name}\` (useContext) that the layout ${hit.layout} provides, but this component renders as a React island, and an island does not see its layout's Provider (it would paint the createContext default). Workaround: pass the value to the page through its loader (a prop), or render the Provider inside this component's own tree. Native resolution of an imported context is F439.`,
+              )
+          }
+          const viaModule = c.ir.tier && typeof c.ir.tier === 'object' && 'React' in c.ir.tier ? importsProvidedModule(c.file, provided) : undefined
+          if (viaModule)
+            throw new BuildError(
+              'island-layout-context',
+              `${c.ir.source} renders as a React island and imports ${viaModule.spec}${viaModule.via ? ` (through ${viaModule.via})` : ''}, a module that declares the context \`${viaModule.hit.contexts.join('`, `')}\` which the layout ${viaModule.hit.layout} provides: an island does not see its layout's Provider (it would paint the createContext default), and a hook or helper of that module may read it. Workaround: pass the value to the page through its loader (a prop), or render the Provider inside this component's own tree. Native resolution of an imported context is F439.`,
+            )
+          for (const ch of (c.ir.children ?? []) as { id: string | null }[]) if (ch.id) stack.push(ch.id)
+        }
+      }
+      // Every Provider the layout's compiled tree renders (the layout itself or a component it calls), by declaring file.
+      const stack = [root.id]
+      const done = new Set<string>()
+      while (stack.length > 0) {
+        const c = compiled.get(stack.pop()!)
+        if (!c || done.has(c.id)) continue
+        done.add(c.id)
+        if ((c.ir.provides ?? []).length > 0)
+          provided.push({ file: real(c.file), layout: root.ir.source, contexts: (c.ir.provides as { context: string }[]).map((p) => p.context.replace(/_m[0-9a-f]{8}$/, '')) })
+        for (const ch of (c.ir.children ?? []) as { id: string | null }[]) if (ch.id) stack.push(ch.id)
+      }
+    }
+  }
+}