@brust/core 2.0.0-alpha.34 → 2.0.0-alpha.35

package/src/build/cloudflare.ts

@@ -77,7 +77,7 @@ export interface CfBuildCtx {
   /** the FINAL dist dir (`out` is a tmp sibling that is renamed to it): wrangler paths are relative to `<dist>/cf` */
   dist: string
   compiled: Map<string, Compiled>
-  manifest: { components: Record<string, { template: string }>; actions?: { prefix: string; maxBodyBytes: number; maxResponseBytes?: number; crossSite?: 'reject' | 'allow'; stream?: string[]; maxStreamBytes?: number } | null; cache?: CacheRecord }
+  manifest: { components: Record<string, { template: string }>; /** F495 `[server] base_path`: the asset tree is laid out under it. */ base_path?: string; actions?: { prefix: string; maxBodyBytes: number; maxResponseBytes?: number; crossSite?: 'reject' | 'allow'; stream?: string[]; maxStreamBytes?: number } | 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. */
@@ -91,6 +91,9 @@ export interface CfBuildCtx {
   log: (s: string) => void
 }
 
+/** F495: the Worker bundle's `define`: production, and the app's base path baked in for `basePath` of `@brust/core` (cf.ts reads it; a Worker has no build-time env). */
+export const workerDefine = (basePath = ''): Record<string, string> => ({ ...PRODUCTION, 'process.env.BRUST_BASE_PATH': JSON.stringify(basePath) })
+
 /** The resolution conditions of the Worker bundle; the package-resolver probe (`sourceDirPlugin`) must carry the same (F223). */
 export const CF_CONDITIONS = ['workerd', 'worker', 'browser']
 
@@ -288,10 +291,10 @@ export async function buildCloudflare(out: string, ctx: CfBuildCtx, p: CfPrepare
     target: 'browser',
     format: 'esm',
     conditions: CF_CONDITIONS,
-    define: PRODUCTION,
+    define: workerDefine(ctx.manifest.base_path),
     minify: false,
     external: ['node:*', 'cloudflare:*', glueSpec],
-    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)],
+    plugins: [serverOnlyEmptyPlugin(), cssPlugin(ctx.cssMaps ?? new Map(), join(out, 'client'), ctx.manifest.base_path ?? ''), 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')}`)
@@ -303,7 +306,7 @@ export async function buildCloudflare(out: string, ctx: CfBuildCtx, p: CfPrepare
   writeFileSync(appFile, await js[0]!.text())
 
   // 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)
+  if (!ctx.actionsOnly) warnings.push(...layoutAssets(out, cfDir, p.coreVersion, ctx.manifest.base_path ?? '').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) {

package/src/build/compile.ts

@@ -30,6 +30,8 @@ export type ComponentIR = Record<string, any> & {
     exprs?: Record<string, string>
     /** F142 R34.43: the rows of a constant enclosing list (`loops` is then `[null]`). */
     rows_literal?: unknown[]
+    /** F502: the branch condition the server checks per instance before it runs the child's job. */
+    when?: unknown
   }[]
   /** F149: inlined instances whose child job the build may run once (`decls.rs` `BuildEvalInstance`). */
   build_eval_instances?: {

package/src/build/config.ts

@@ -22,6 +22,7 @@ import {
   streamEntryError,
 } from '../actions/prefix'
 import { ADAPTER_NAMES, BUILTINS, installHint } from '../cache-adapter/load'
+import { normalizeBasePath } from '../config'
 import { BuildError } from './errors'
 import { posixOf } from './posix'
 
@@ -108,6 +109,8 @@ export interface BuildConfig {
   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[]
+  /** `[server] base_path` (F495), normalised (`/portal`); `''` = the app is mounted at the root. Baked into every URL brust emits. */
+  basePath: string
 }
 
 const isTable = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v)
@@ -274,7 +277,7 @@ function resolveAlias(file: string, appRoot: string, p: string): string {
   }
 }
 
-function parseActions(file: string, raw: unknown, actionsOnly: boolean): ActionsBuildConfig | null {
+function parseActions(file: string, raw: unknown, actionsOnly: boolean, basePath = ''): ActionsBuildConfig | null {
   if (raw === undefined) return null
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) throw new BuildError('config', `${file}: [actions] must be a table`)
   const t = raw as Record<string, unknown>
@@ -283,12 +286,16 @@ function parseActions(file: string, raw: unknown, actionsOnly: boolean): Actions
     if (typeof t.entry !== 'string' || t.entry.trim() === '') throw new BuildError('config', `${file}: actions.entry must be a non-empty string`)
     entry = t.entry.trim().replace(/^\.\//, '')
   }
-  let prefix = DEFAULT_ACTION_PREFIX
+  // F495: the default prefix lives under the base path, like every URL brust owns.
+  let prefix = `${basePath}${DEFAULT_ACTION_PREFIX}`
   if (t.prefix !== undefined) {
     // `/` is the prefix of an actions-only deployment; a page-only build (base_url, no local app) may name it too.
     const why = prefixError(t.prefix, actionsOnly || t.base_url !== undefined)
     if (why) throw new BuildError('config', `${file}: actions.prefix ${why}`)
     prefix = t.prefix as string
+    // F495: an explicit prefix is used as written, and must itself be under the base path.
+    if (basePath !== '' && prefix !== basePath && !prefix.startsWith(`${basePath}/`))
+      throw new BuildError('config', `${file}: actions.prefix ${JSON.stringify(prefix)} must lie under server.base_path ${JSON.stringify(basePath)}`)
   }
   let maxBodyBytes = DEFAULT_MAX_BODY_BYTES
   if (t.max_body_bytes !== undefined) {
@@ -397,10 +404,20 @@ export function parseSourceRoots(file: string, appRoot: string, raw: unknown): s
   return [...out].sort()
 }
 
+/** `[server] base_path` (F495): the one validator is config.ts's; a bad value is a build error here too. */
+function parseBasePath(file: string, server: unknown): string {
+  if (server === undefined) return ''
+  if (!isTable(server)) throw new BuildError('config', `${file}: [server] must be a table`)
+  if (server.base_path === undefined) return ''
+  const r = normalizeBasePath(server.base_path)
+  if (!r.ok) throw new BuildError('config', `${file}: server.base_path ${r.why}`)
+  return r.value
+}
+
 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: [], sourceRoots: [] }
+  if (!(await f.exists())) return { serverOnly: [], actions: null, cloudflare: null, cache: null, cssGlobal: [], sourceRoots: [], basePath: '' }
   let parsed: unknown
   try {
     parsed = Bun.TOML.parse(await f.text())
@@ -408,17 +425,18 @@ export async function loadBuildConfig(appRoot: string, o: { actionsOnly?: boolea
     throw new BuildError('config', `failed to parse ${file}: ${(e as Error).message}`)
   }
   const root = (parsed ?? {}) as Record<string, unknown>
-  const actions = parseActions(file, root.actions, o.actionsOnly === true)
+  const basePath = parseBasePath(file, root.server)
+  const actions = parseActions(file, root.actions, o.actionsOnly === true, basePath)
   const cloudflare = parseCloudflare(file, appRoot, root.cloudflare)
   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, sourceRoots: [] }
+  if (build === undefined) return { serverOnly: [], actions, cloudflare, cache, cssGlobal, sourceRoots: [], basePath }
   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, sourceRoots }
+  if (so === undefined) return { serverOnly: [], actions, cloudflare, cache, cssGlobal, sourceRoots, basePath }
   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) => posixOf(p.trim()).replace(/^\.\//, '')), actions, cloudflare, cache, cssGlobal, sourceRoots }
+  return { serverOnly: so.map((p: string) => posixOf(p.trim()).replace(/^\.\//, '')), actions, cloudflare, cache, cssGlobal, sourceRoots, basePath }
 }

package/src/build/css.ts

@@ -132,13 +132,17 @@ export function cssUnescape(s: string): string {
   )
 }
 
+/** F495: a URL brust serves itself, `/public/…` or `/_brust/…`, under the app's base path (`<base>/public/…`) or at the root:
+ * written as it is, never a file on this machine. */
+export const brustUrl = (v: string, base = ''): boolean => ['/public/', '/_brust/'].some((p) => v.startsWith(p) || (base !== '' && v.startsWith(`${base}${p}`)))
+
 /** F490: an absolute local path in either spelling: POSIX `/…`, a Windows drive `C:\…` / `C:/…`, or a UNC `\\host\…`. */
 export const localAbsolute = (p: string): boolean => p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p) || p.startsWith('\\\\')
 
 /** F393: a `url()` that is the absolute path of a file on disk (see the `loader` in `buildCss`) becomes a
  * hashed `./<name>-<hex10>.<ext>` client asset at any size. `/public/…` and `/_brust/…` stay as written.
  * F490: on Windows that path is `C:\\…` (CSS-escaped), so the value is unescaped and both spellings are taken. */
-function emitSourceAssets(text: string, assets: { name: string; bytes: Uint8Array }[], suffixed: Map<string, string>): string {
+function emitSourceAssets(text: string, assets: { name: string; bytes: Uint8Array }[], suffixed: Map<string, string>, base = ''): string {
   const emit = (path: string, suffix: string) => {
     const { name, bytes } = hashedAsset(path)
     if (!assets.some((a) => a.name === name)) assets.push({ name, bytes })
@@ -149,7 +153,7 @@ function emitSourceAssets(text: string, assets: { name: string; bytes: Uint8Arra
     if (abs !== undefined) return emit(abs, path.slice(path.search(/[?#]/)))
     const file = cssUnescape(path)
     const ext = extname(file).toLowerCase()
-    if (!localAbsolute(file) || !SERVED_ASSET_EXT.includes(ext) || file.startsWith('/public/') || file.startsWith('/_brust/') || !existsSync(file)) return whole
+    if (!localAbsolute(file) || !SERVED_ASSET_EXT.includes(ext) || brustUrl(file, base) || !existsSync(file)) return whole
     return emit(file, '')
   })
 }
@@ -158,11 +162,11 @@ function emitSourceAssets(text: string, assets: { name: string; bytes: Uint8Arra
  * path and 404 in the browser, so the build fails instead. A leak is a Windows drive or UNC path, or a `/…` path under
  * the app root or the dist dir (`roots`). Any other root URL passes, even one that happens to exist on the build
  * machine (`url(/tmp/x)`, `url(/fonts/x.woff2)`): only the app's own files are known to be local. */
-export function leakedLocalPaths(text: string, roots: string[]): string[] {
+export function leakedLocalPaths(text: string, roots: string[], base = ''): string[] {
   const out: string[] = []
   for (const m of text.matchAll(SOURCE_URL)) {
     const v = cssUnescape(m[2]!)
-    if (v.startsWith('/public/') || v.startsWith('/_brust/') || !localAbsolute(v)) continue
+    if (brustUrl(v, base) || !localAbsolute(v)) continue
     const posix = v.replaceAll('\\', '/')
     const local = !v.startsWith('/') || roots.some((r) => posix === r || posix.startsWith(`${r}/`))
     if (local && !out.includes(v)) out.push(v)
@@ -203,7 +207,7 @@ export async function buildCss(
   dist: string,
   sources: string[],
   minify = true,
-  o: { appRoot?: string; log?: (s: string) => void } = {},
+  o: { appRoot?: string; log?: (s: string) => void; basePath?: string; ownOutput?: string[] } = {},
 ): Promise<CssBuild> {
   const file = new Map<string, string>()
   const maps = new Map<string, Record<string, string>>()
@@ -220,7 +224,9 @@ export async function buildCss(
       if (hit === undefined) via.set(k, (hit = tailwindUse([k]).using.length > 0))
       return hit
     }
-    plugins.push(await loadTailwind(appRoot, tw.using[0]!, uses, o.log))
+    // F501: the output dirs of this app that Tailwind must not scan, as app-root-relative patterns (only those under it).
+    const own = (o.ownOutput ?? []).map((d) => relative(real(appRoot), real(d)).split(sep).join('/')).filter((r) => r !== '' && r !== '..' && !r.startsWith('../') && !isAbsolute(r))
+    plugins.push(await loadTailwind(appRoot, tw.using[0]!, uses, o.log, [...new Set(own)]))
     if (tw.imports.length > 1)
       o.log?.(
         `[brust] warning tailwind @import "tailwindcss" is in ${tw.imports.length} files (${tw.imports.map((f) => relative(appRoot, f)).join(', ')}): each one ships the whole of Tailwind; import it once (e.g. app.css) and use @reference elsewhere`,
@@ -241,7 +247,7 @@ export async function buildCss(
     format: 'esm',
     minify,
     naming: { entry: '[name]-[hash].[ext]', chunk: '[name]-[hash].[ext]', asset: '[name]-[hash].[ext]' },
-    external: ['/public/*', '/_brust/*'],
+    external: ['/public/*', '/_brust/*', ...(o.basePath ? [`${o.basePath}/public/*`, `${o.basePath}/_brust/*`] : [])],
     root: appRoot,
     plugins,
     // F393, verified on Bun 1.4.4 only: its CSS bundler turns an asset under the size threshold into a `data:`
@@ -289,9 +295,9 @@ export async function buildCss(
       `${lines.join('; ')}: brust serves only ${SERVED_ASSET_EXT.join(' ')} from /_brust/client; put the file in public/ and reference it as /public/…`,
     )
   }
-  for (const [i, t] of css) css.set(i, emitSourceAssets(t, assets, suffixed))
+  for (const [i, t] of css) css.set(i, emitSourceAssets(t, assets, suffixed, o.basePath))
   const roots = [appRoot, dist].flatMap((r) => [r, real(r)]).map((r) => r.replaceAll('\\', '/').replace(/\/+$/, '')).filter((r) => r !== '')
-  const leaks = [...css].flatMap(([i, t]) => leakedLocalPaths(t, roots).map((p) => `url(${p}) in ${sources[i]}`))
+  const leaks = [...css].flatMap(([i, t]) => leakedLocalPaths(t, roots, o.basePath).map((p) => `url(${p}) in ${sources[i]}`))
   if (leaks.length > 0)
     throw new BuildError('css-asset-path', `${leaks.join('; ')}: the built CSS would name a file on this machine; reference it relative to the stylesheet or as /public/…`)
   for (const a of assets) writeFileSync(join(dist, 'client', a.name), a.bytes)
@@ -351,9 +357,9 @@ export function tailwindUse(sources: string[]): { using: string[]; imports: stri
  * (`export default Object.freeze({…})`); any other `.css` import is an empty module, because the
  * stylesheet itself is linked by the server (R19.3), never bundled into JS.
  * F411: with `clientDir` (`<dist>/client`), an import of a served asset (`SERVED_ASSET_EXT`: a font, an image) is
- * the string `/_brust/client/<name>-<hex10>.<ext>`, the very file a stylesheet's `url()` of it is rewritten to; the
+ * the string `/_brust/client/<name>-<hex10>.<ext>` (under `basePath`, F495), the very file a stylesheet's `url()` of it is rewritten to; the
  * file is written there, so the URL can be preloaded (`<link rel="preload" as="font" href={font}>`). */
-export function cssPlugin(maps: Map<string, Record<string, string>>, clientDir?: string): BunPlugin {
+export function cssPlugin(maps: Map<string, Record<string, string>>, clientDir?: string, basePath = ''): BunPlugin {
   return {
     name: 'brust-css',
     setup(b) {
@@ -371,7 +377,7 @@ export function cssPlugin(maps: Map<string, Record<string, string>>, clientDir?:
           mkdirSync(clientDir, { recursive: true })
           writeFileSync(to, bytes)
         }
-        return { contents: `export default ${JSON.stringify(`/_brust/client/${name}`)}\n`, loader: 'js' }
+        return { contents: `export default ${JSON.stringify(`${basePath}/_brust/client/${name}`)}\n`, loader: 'js' }
       })
     },
   }

package/src/build/index.ts

@@ -8,8 +8,9 @@ import { createHash } from 'node:crypto'
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path'
-import { BrustRouteError, type FlatRoute, validateRoutes } from '../routes'
-import { type BrowserCtx, setDevBuild, buildActions, buildCacheAdapter, buildClientChunks, buildJobs, buildReactChunks, buildRuntime, nestedOf, storeModules } from './bundle'
+import { BrustRouteError, checkBasePath, type FlatRoute, validateRoutes } from '../routes'
+import { assertRoutesInstallable, type CheckPatterns, nativeCheckPatterns } from './route-conflicts'
+import { type BrowserCtx, brustRoot, setDevBuild, buildActions, buildCacheAdapter, buildClientChunks, buildJobs, buildReactChunks, buildRuntime, nestedOf, storeModules } from './bundle'
 import { runActionsOnly } from './actions-only'
 import { type CfPrepared, buildCloudflare, prepareCloudflare } from './cloudflare'
 import { renderIcons } from './build-icons'
@@ -106,6 +107,8 @@ export async function runBuild(opts: {
   strict?: boolean
   /** The cache key grammar's read-set (static; tests swap it). Default: the addon. */
   exprReads?: ExprReads
+  /** The router's refusal of a pattern set (F496; tests swap it). Default: the addon. */
+  checkPatterns?: CheckPatterns
   /** `--wasm-from-source` (cloudflare only). */
   wasmFromSource?: boolean
   /** `--actions-only` (L16 R16.3): no pages, only the `[actions]` app; with `bun` (default) or `cloudflare`. */
@@ -123,9 +126,11 @@ export async function runBuild(opts: {
   assertSafeOutDir(dist, appRoot, [entry, join(appRoot, 'public')])
   assertReplaceable(dist, opts.force)
   const built = await loadBuildConfig(appRoot, { actionsOnly: opts.actionsOnly === true })
+  // F495: `basePath` of `@brust/core` while the build loads the app's modules (route scan, static render).
+  process.env.BRUST_BASE_PATH = built.basePath
   if (opts.actionsOnly)
     return runActionsOnly({ appRoot, dist, config: built, target: opts.target, wasmFromSource: opts.wasmFromSource === true, statOk, assertSafeOutDir, log: opts.log })
-  const { serverOnly, cloudflare, cache, cssGlobal, sourceRoots } = built
+  const { serverOnly, cloudflare, cache, cssGlobal, sourceRoots, basePath } = 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 =
@@ -138,10 +143,13 @@ export async function runBuild(opts: {
   let leaves: ReturnType<typeof validateRoutes>
   try {
     leaves = validateRoutes(routes)
+    checkBasePath(leaves, basePath)
   } catch (e) {
     if (e instanceof BrustRouteError) throw new BuildError(e.rule, e.message)
     throw e
   }
+  // F496: what the server's router would refuse at `brust start` (a `{*rest}` next to a `{slug}`) fails here.
+  assertRoutesInstallable(leaves, opts.checkPatterns ?? (await nativeCheckPatterns()))
   let actionsEntry: string | null = null
   if (actions) {
     actionsEntry = resolve(appRoot, actions.entry)
@@ -176,7 +184,7 @@ export async function runBuild(opts: {
   // R9.3/R9.4: every reason to refuse a static build, before any write.
   const ssgPlan =
     opts.target === 'static'
-      ? await prepareStatic(leaves, actions !== null, opts.exprReads ?? (await import('../native')).cacheExprReads, opts.log, cache)
+      ? await prepareStatic(leaves, actions !== null, opts.exprReads ?? (await import('../native')).cacheExprReads, opts.log, cache, basePath)
       : null
 
   // Config, @brust/core-cf resolution and the user's wrangler file fail here, before any write.
@@ -190,7 +198,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, appModules, appGraph, serverOnly, actions, actionsEntry, cache, cacheModule, cf, hybrid, cssGlobal, sourceRoots, 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, basePath, 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
@@ -233,6 +241,8 @@ async function buildInto(
     cssGlobal: string[]
     /** `[build] source_roots` (F256): normalised, app-root-relative directories outside the app a relative import may reach. */
     sourceRoots: string[]
+    /** `[server] base_path` (F495), `''` = the root. */
+    basePath: 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). */
@@ -248,13 +258,13 @@ async function buildInto(
   const serverCss = [o.actionsEntry, o.cacheModule].flatMap((f) => (f ? graph.of(f) : []))
   mkdirSync(join(out, 'client'), { recursive: true })
   // Review N3: `brust dev` builds with BRUST_BUILD_MODE=development (as the JS bundles): readable, unminified CSS.
-  const css = await buildCss(out, [...new Set([...[...routeCss.values()].flat(), ...serverCss])], process.env.BRUST_BUILD_MODE !== 'development', { appRoot, log: o.log })
+  const css = await buildCss(out, [...new Set([...[...routeCss.values()].flat(), ...serverCss])], process.env.BRUST_BUILD_MODE !== 'development', { appRoot, log: o.log, basePath: o.basePath, ownOutput: [o.dist, join(appRoot, '.brust')] })
   for (const c of directCss(entry))
     o.log(`[brust] warning css ${relative(appRoot, entry)} imports ${c}: the route entry belongs to no route, so it is linked nowhere; import it from a layout, or list it in [css] global`)
-  const ctx: BrowserCtx = { sourceOf: new Map(), appRoot, serverOnly: o.serverOnly, serverFiles: o.actionsEntry ? [realpathSync(o.actionsEntry)] : [], cssMaps: css.maps, clientDir: join(out, 'client') }
+  const ctx: BrowserCtx = { sourceOf: new Map(), appRoot, serverOnly: o.serverOnly, serverFiles: o.actionsEntry ? [realpathSync(o.actionsEntry)] : [], cssMaps: css.maps, clientDir: join(out, 'client'), basePath: o.basePath }
   // 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}` }
+  const runtimeUrls = { core: `${brustRoot(ctx)}/${runtime.core}`, store: `${brustRoot(ctx)}/${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
@@ -346,10 +356,12 @@ 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), writers)
+  await buildJobs(out, compiled, ctx.sourceOf, appRoot, storeModules(manifest), css.maps, routeRoots, reachedJobs(manifest), writers, o.basePath)
+  // F495: absent without a base path, so an app at the root writes the manifest it always did.
+  if (o.basePath !== '') manifest.base_path = o.basePath
   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, ...o.actions.stream }
+      ? { entry: await buildActions(out, o.actionsEntry, css.maps, o.basePath), prefix: o.actions.prefix, maxBodyBytes: o.actions.maxBodyBytes, maxResponseBytes: o.actions.maxResponseBytes, crossSite: o.actions.crossSite, ...o.actions.stream }
       : null
   if (o.actionsRemote !== null) manifest.actions_remote = { prefix: o.actionsRemote }
   if (o.cache) manifest.cache = await cacheRecord(out, manifest, o.cache, o.cacheModule, css.maps)

package/src/build/manifest.ts

@@ -36,6 +36,9 @@ export interface ChildRecord {
   exprs?: Record<string, string>
   /** F142 R34.43: the list of a `per-row-literal` instance (a constant the compiler read). */
   rows?: unknown[]
+  /** F502: the branch condition (`{truthy}`/`{eq}`/`{not}`/`{all}`/`{any}` over props paths) the server checks per instance before
+   * it runs the child's job: a row whose branch does not render the child gets no job. */
+  when?: unknown
 }
 
 export interface ComponentRecord {
@@ -97,6 +100,8 @@ export interface ManifestJson {
   actions: ActionsRecord | null
   /** L16 R16.3: an actions-only build (no routes, no templates); everything but the prefix is a 404 problem+json. */
   actions_only?: true
+  /** F495 `[server] base_path`: set only for an app mounted under a path. The server answers under it alone and every URL brust owns lies below it. */
+  base_path?: string
   /** L16 R16.4b: a page-only build: no local actions app, `base_url` points at the deployment that has it. */
   actions_remote?: { prefix: string }
   /** `[cache]` (cache adapters); absent without one (the manifest is then byte-identical). */
@@ -315,6 +320,7 @@ export function childRecords(c: Compiled, clientOnly: string[] = []): ChildRecor
     if (inst.literals && Object.keys(inst.literals).length > 0) rec.literals = { ...inst.literals }
     if (inst.exprs && Object.keys(inst.exprs).length > 0) rec.exprs = { ...inst.exprs }
     if (literal) rec.rows = inst.rows_literal
+    if (inst.when !== undefined && inst.when !== null) rec.when = inst.when
     return rec
   })
   for (const id of clientOnly) out.push({ id, instances: 'static', props: {} })

package/src/build/route-conflicts.ts

@@ -0,0 +1,39 @@
+// F496: the server's router refuses some pattern sets (`/{*rest}` next to `/{slug}`); without this the build passes and
+// the first `brust start` fails. The check is the router's own insertion (`routing/routes.rs` `find_pattern_conflict`,
+// through the addon the build already loads): there is no second matcher here.
+import type { FlatRoute } from '../routes'
+import { BuildError } from './errors'
+
+export interface PatternConflict {
+  /** Index into the patterns given of the pattern the router refused. */
+  index: number
+  /** Index of the earlier pattern it conflicts with, when there is one. */
+  withIndex?: number | null
+  /** The router's refusal, as `brust start` would print it. */
+  message: string
+}
+
+export type CheckPatterns = (patterns: string[]) => PatternConflict | null
+
+/** The addon's `checkRoutePatterns` (crates/brust-napi/src/compile.rs `check_route_patterns`). */
+export async function nativeCheckPatterns(): Promise<CheckPatterns> {
+  const { native } = await import('../native')
+  const b = native() as unknown as { checkRoutePatterns?: CheckPatterns }
+  if (typeof b.checkRoutePatterns !== 'function')
+    throw new BuildError('route-conflict', 'the native addon is older than this build (no checkRoutePatterns): rebuild it')
+  return b.checkRoutePatterns.bind(b)
+}
+
+/** Fails the build when the server's router would refuse the leaves' patterns. Catch-all (`*`) leaves never enter the
+ * router, so they are left out, as the server leaves them out. The error names the route ids. */
+export function assertRoutesInstallable(leaves: FlatRoute[], check: CheckPatterns): void {
+  const routed = leaves.filter((l) => !l.catchAll)
+  const found = check(routed.map((l) => l.pattern))
+  if (!found) return
+  const at = routed[found.index]
+  const partner = found.withIndex != null ? routed[found.withIndex] : undefined
+  const who = partner
+    ? `routes ${partner.id} (${partner.pattern}) and ${at?.id} (${at?.pattern}) cannot be installed together`
+    : `route ${at?.id} (${at?.pattern}) cannot be installed`
+  throw new BuildError('route-conflict', `${who}: ${found.message}`)
+}

package/src/build/ssg.ts

@@ -77,7 +77,8 @@ function checkValue(leaf: FlatRoute, i: number, name: string, rest: boolean, v:
 }
 
 /** Plans every page. `params` holds each dynamic route's resolved `ssg.params()` by route id. */
-export function planStatic(leaves: FlatRoute[], params: Map<string, unknown>): StaticPlan {
+/** F495: under `base` (`[server] base_path`) the not-found probe is a path under it, so the app's `*` route answers it rather than the server's plain 404. */
+export function planStatic(leaves: FlatRoute[], params: Map<string, unknown>, base = ''): StaticPlan {
   const pages: PlannedPage[] = []
   const skipped: StaticPlan['skipped'] = []
   let catchAll: FlatRoute | undefined
@@ -133,7 +134,7 @@ export function planStatic(leaves: FlatRoute[], params: Map<string, unknown>): S
     seen.set(key, p)
   }
   if (seen.has('404.html')) throw new BuildError('ssg-params', `${seen.get('404.html')!.path} would overwrite 404.html`)
-  if (catchAll) pages.push({ path: NOT_FOUND_PATH, file: '404.html', routeId: catchAll.id, pattern: catchAll.pattern, expect: 404 })
+  if (catchAll) pages.push({ path: `${base}${NOT_FOUND_PATH}`, file: '404.html', routeId: catchAll.id, pattern: catchAll.pattern, expect: 404 })
   return { pages, skipped, defaultNotFound: catchAll === undefined }
 }
 

package/src/build/static.ts

@@ -28,6 +28,7 @@ export async function prepareStatic(
   reads: ExprReads,
   log: (s: string) => void,
   cache?: Parameters<typeof assertNoCacheBindings>[0],
+  base = '',
 ): Promise<StaticPlan> {
   // L12: `[actions]` makes the output hybrid (static pages + a Pages Worker for the action prefix).
   if (actions) assertNoCacheBindings(cache)
@@ -65,7 +66,7 @@ export async function prepareStatic(
       throw new BuildError('ssg-params', `route ${leaf.id} (${leaf.pattern}) ssg.params() threw: ${(e as Error).message ?? String(e)}`)
     }
   }
-  return planStatic(leaves, params)
+  return planStatic(leaves, params, base)
 }
 
 export interface StaticReport {
@@ -167,7 +168,7 @@ export async function writeStatic(
   const dir = join(dist, 'static')
   rmSync(dir, { recursive: true, force: true })
   const assetsStage = join(dist, '.ssg-assets')
-  const assets = layoutAssets(dist, assetsStage, o.version)
+  const assets = layoutAssets(dist, assetsStage, o.version, (JSON.parse(readFileSync(join(dist, 'manifest.json'), 'utf8')) as { base_path?: string }).base_path ?? '')
   renameSync(join(assetsStage, 'assets'), dir)
   rmSync(assetsStage, { recursive: true, force: true })
   const warnings = [...assets.warnings]

package/src/build/tailwind.ts

@@ -68,8 +68,15 @@ const addCommand = (v: string) => `bun add -d --exact ${TAILWIND_PACKAGES.map((p
 /** The Tailwind plugin of the CSS build, resolved from the app. Missing packages → `tailwind-missing` with the
  * exact install command; versions that differ → one warning through `log` with the command that aligns them.
  * `uses(file)` says whether a stylesheet needs the compiler (it, or a relative `@import` of it, uses Tailwind);
- * other stylesheets stay Bun's. */
-export async function loadTailwind(appRoot: string, usedBy: string, uses: (file: string) => boolean, log?: (s: string) => void): Promise<BunPlugin> {
+ * other stylesheets stay Bun's. `ownOutput`: app-root-relative, `/`-separated directories of brust's own output that no
+ * scan may read (F501). */
+export async function loadTailwind(
+  appRoot: string,
+  usedBy: string,
+  uses: (file: string) => boolean,
+  log?: (s: string) => void,
+  ownOutput: string[] = [],
+): Promise<BunPlugin> {
   const v = tailwindVersions(appRoot)
   const missing = TAILWIND_PACKAGES.filter((p) => versionFrom(p, appRoot) === undefined)
   if (missing.length > 0)
@@ -105,7 +112,10 @@ export async function loadTailwind(appRoot: string, usedBy: string, uses: (file:
         const compiler = await node.compile(css, { base: dirname(a.path), from: a.path, shouldRewriteUrls: true, onDependency: () => {} })
         const root: SourceEntry[] =
           compiler.root === 'none' ? [] : compiler.root === null ? [{ base: appRoot, pattern: '**/*', negated: false }] : [{ ...compiler.root, negated: false }]
-        const scanner = new oxide.Scanner({ sources: [...root, ...compiler.sources] })
+        // F501: brust's own output (the dist dir, `.brust`) is never a source, whatever the ignore files say and whatever
+        // the stylesheet's `source(...)` and `@source` lines add: last, so a stale build can never feed the next one.
+        const own: SourceEntry[] = ownOutput.map((dir) => ({ base: appRoot, pattern: `${dir}/**`, negated: true }))
+        const scanner = new oxide.Scanner({ sources: [...root, ...compiler.sources, ...own] })
         let out = compiler.build(scanner.scan())
         // `@reference "./app.css"` pulls in Tailwind's license banner too; only the file that imports Tailwind ships it
         // (one banner per page, as before)

package/src/build/tsconfig-paths.ts

@@ -3,7 +3,7 @@
 // this module reads out of the app's own `tsconfig.json` / `jsconfig.json`. v1 reads that one file: no `extends`, no
 // `references` (a named fallback below); exact and single-`*` patterns only. The bundler resolves the same specifiers
 // natively; `checkAliasAgreement` fails the build if the two ever disagree.
-import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
 import { dirname, isAbsolute, join, normalize, relative, sep } from 'node:path'
 import { BuildError } from './errors'
 
@@ -26,10 +26,21 @@ export function readPathAliases(appRoot: string): { aliases: PathAlias[]; notes:
   }
   const notes: string[] = []
   const paths = json?.compilerOptions?.paths
-  if (json?.extends !== undefined || json?.references !== undefined)
+  const name = relative(appRoot, file)
+  const hasPaths = !!paths && typeof paths === 'object'
+  // TS semantics: a local `compilerOptions.paths` replaces any inherited `paths`, so beside a local `paths` an `extends`
+  // can only matter through the `baseUrl` it supplies (F497). Without local `paths` the aliases live elsewhere.
+  if (hasPaths ? json?.references !== undefined : json?.extends !== undefined || json?.references !== undefined)
     notes.push(
-      `${relative(appRoot, file)} uses \`${json.extends !== undefined ? 'extends' : 'references'}\`, which brust does not follow: \`paths\` aliases written in another tsconfig stay package imports (put \`paths\` in ${relative(appRoot, file)})`,
+      `${name} uses \`${json.extends !== undefined && !hasPaths ? 'extends' : 'references'}\`, which brust does not follow: \`paths\` aliases written in another tsconfig stay package imports (put \`paths\` in ${name})`,
     )
+  if (hasPaths && json?.extends !== undefined && typeof json.compilerOptions?.baseUrl !== 'string') {
+    const from = inheritedBaseUrlFile(file, json.extends)
+    if (from)
+      notes.push(
+        `\`baseUrl\` comes from ${relative(appRoot, from).split(sep).join('/')}, which brust does not follow: aliases resolve from ${name}'s directory (set \`baseUrl\` in ${name})`,
+      )
+  }
   if (!paths || typeof paths !== 'object') return { aliases: [], notes }
   const base = typeof json.compilerOptions?.baseUrl === 'string' ? json.compilerOptions.baseUrl : '.'
   const aliases: PathAlias[] = []
@@ -52,6 +63,23 @@ export function readPathAliases(appRoot: string): { aliases: PathAlias[]; notes:
   return { aliases, notes }
 }
 
+/** The extended tsconfig that sets `baseUrl`, when `extends` names a relative file (one level, JSONC; a package specifier,
+ * an unreadable file or a file without `baseUrl` is none). */
+function inheritedBaseUrlFile(file: string, extendsValue: unknown): string | null {
+  const refs = Array.isArray(extendsValue) ? extendsValue : [extendsValue]
+  for (const ref of refs) {
+    if (typeof ref !== 'string' || !(ref.startsWith('./') || ref.startsWith('../'))) continue
+    const base = join(dirname(file), ref)
+    const target = [base, `${base}.json`].find((f) => existsSync(f) && statSync(f).isFile())
+    if (!target) continue
+    try {
+      const ext = Bun.JSONC.parse(readFileSync(target, 'utf8')) as { compilerOptions?: { baseUrl?: unknown } } | null
+      if (typeof ext?.compilerOptions?.baseUrl === 'string') return target
+    } catch {}
+  }
+  return null
+}
+
 /** The compiler's answer for every alias import must be the file the bundler resolves the same specifier to. */
 export function checkAliasAgreement(appRoot: string, imports: { from: string; spec: string; target: string }[]): void {
   for (const { from, spec, target } of imports) {