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

package/src/build/cf-assets.ts

@@ -37,8 +37,10 @@ function walk(dir: string, rel = ''): string[] {
 }
 
 /** Copies the admissible files of `<out>/client` and `<out>/public` into `<cfDir>/assets/...`; returns the
- * asset-relative paths (`_brust/client/x.js`, `public/img/a.png`) and writes `assets/_headers`. */
-export function layoutAssets(out: string, cfDir: string, version: string): { files: string[]; warnings: string[] } {
+ * asset-relative paths (`_brust/client/x.js`, `public/img/a.png`) and writes `assets/_headers`. F495: an app under a base path
+ * (`/portal`) lays them out under it (`portal/_brust/client/x.js`), so the platform serves the very URLs the pages name. */
+export function layoutAssets(out: string, cfDir: string, version: string, base = ''): { files: string[]; warnings: string[] } {
+  const under = base === '' ? '' : `${base.slice(1)}/`
   const assets = join(cfDir, 'assets')
   mkdirSync(assets, { recursive: true })
   const files: string[] = []
@@ -51,32 +53,32 @@ export function layoutAssets(out: string, cfDir: string, version: string): { fil
   const client = join(out, 'client')
   if (existsSync(client))
     for (const f of walk(client)) {
-      if (!f.includes('/') && clientOk(f)) copy(join(client, f), `_brust/client/${f}`)
+      if (!f.includes('/') && clientOk(f)) copy(join(client, f), `${under}_brust/client/${f}`)
       else warnings.push(`[brust] assets: client/${f} is not served natively; skipped`)
     }
   const pub = join(out, 'public')
   if (existsSync(pub))
     for (const f of walk(pub)) {
-      if (f.split('/').every(segOk)) copy(join(pub, f), `public/${f}`)
+      if (f.split('/').every(segOk)) copy(join(pub, f), `${under}public/${f}`)
       else warnings.push(`[brust] assets: public/${f} has a name the native host would not serve; skipped`)
     }
-  const h = headersFile(files, version)
+  const h = headersFile(files, version, base)
   warnings.push(...h.warnings)
   writeFileSync(join(assets, '_headers'), h.text)
   return { files, warnings }
 }
 
-export function headersFile(files: string[], version: string): { text: string; warnings: string[] } {
+export function headersFile(files: string[], version: string, base = ''): { text: string; warnings: string[] } {
   const warnings: string[] = []
   const rules: string[] = [
     `/*\n  X-Content-Type-Options: nosniff\n  X-Powered-By: brust/${version}`,
-    `/_brust/client/*\n  Cache-Control: ${IMMUTABLE}`,
+    `${base}/_brust/client/*\n  Cache-Control: ${IMMUTABLE}`,
   ]
-  const pub = files.filter((f) => f.startsWith('public/'))
+  const pub = files.filter((f) => f.startsWith(`${base === '' ? '' : `${base.slice(1)}/`}public/`))
   if (rules.length + pub.length <= MAX_RULES)
     for (const f of pub) rules.push(`/${f}\n  Cache-Control: ${isHashed(f) ? IMMUTABLE : PUBLIC_DEFAULT}`)
   else if (pub.length > 0) {
-    rules.push(`/public/*\n  Cache-Control: ${PUBLIC_DEFAULT}`)
+    rules.push(`${base}/public/*\n  Cache-Control: ${PUBLIC_DEFAULT}`)
     warnings.push(`[brust] assets: ${pub.length} public files exceed the 100-rule _headers limit; one /public/* max-age=3600 rule (no per-file immutable)`)
   }
   return { text: `${rules.join('\n\n')}\n`, warnings }

package/src/build/cf-workerd.ts

@@ -0,0 +1,63 @@
+// F482: the newest `compatibility_date` the app's installed workerd runs. `wrangler dev` (and so `brust dev --target
+// cloudflare`) refuses a date newer than that, while the default date is the @brust/core-cf build date, which can be newer.
+// workerd's npm package carries its own answer: `lib/main.js` exports `compatibilityDate` (the date part of its version,
+// `1.YYYYMMDD.n`). Read statically (the package is never imported).
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+export interface WorkerdDate {
+  /** `YYYY-MM-DD`: the newest compatibility date this workerd supports. */
+  date: string
+  version: string
+  /** The package directory it was read from. */
+  dir: string
+}
+
+/** The directory of package `name` as Node resolves it from `from`: the nearest `node_modules/<name>` up the tree
+ * (package managers that nest, like pnpm, keep a package's own dependencies beside its real directory). */
+function findPackage(name: string, from: string): string | null {
+  for (let dir = from; ; dir = dirname(dir)) {
+    const p = join(dir, 'node_modules', name)
+    if (existsSync(join(p, 'package.json'))) return realpathSync(p)
+    if (dirname(dir) === dir) return null
+  }
+}
+
+const readJson = (file: string): { version?: unknown } | null => {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as { version?: unknown }
+  } catch {
+    return null
+  }
+}
+
+/** The compatibility date of the workerd in package directory `dir`, or null when it cannot be told. */
+function dateOf(dir: string): WorkerdDate | null {
+  const version = String(readJson(join(dir, 'package.json'))?.version ?? '')
+  let main = ''
+  try {
+    const f = join(dir, 'lib', 'main.js')
+    if (statSync(f).isFile()) main = readFileSync(f, 'utf8')
+  } catch {}
+  const exported = /\bcompatibilityDate\s*=\s*"(\d{4}-\d{2}-\d{2})"/.exec(main)?.[1]
+  const v = /^1\.(\d{4})(\d{2})(\d{2})\./.exec(version)
+  const date = exported ?? (v ? `${v[1]}-${v[2]}-${v[3]}` : undefined)
+  return date ? { date, version, dir } : null
+}
+
+/** The workerd the app's wrangler runs: wrangler → miniflare → workerd, each resolved from the real directory of the one
+ * before it (so a nested install is the right copy); else a `workerd` the app resolves itself; else null. */
+export function installedWorkerd(appRoot: string): WorkerdDate | null {
+  let from = appRoot
+  for (const name of ['wrangler', 'miniflare']) {
+    const dir = findPackage(name, from)
+    if (!dir) {
+      from = ''
+      break
+    }
+    from = dir
+  }
+  const viaWrangler = from ? findPackage('workerd', from) : null
+  const dir = viaWrangler ?? findPackage('workerd', appRoot)
+  return dir ? dateOf(dir) : null
+}

package/src/build/cloudflare.ts

@@ -14,6 +14,7 @@ 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 { installedWorkerd } from './cf-workerd'
 import { MANIFEST_VERSION } from './manifest'
 import { exposePlugin, PRODUCTION, type SourceOf, sourceDirPlugin } from './bundle'
 import type { Compiled } from './compile'
@@ -42,9 +43,25 @@ const DEFAULT_CFG: CloudflareBuildConfig = { name: undefined, compatibilityDate:
 
 /** Everything that can fail on the app's own input or install, before a byte is written (index.ts rule). */
 export async function prepareCloudflare(appRoot: string, cfg: CloudflareBuildConfig | null, flags: CfFlags): Promise<CfPrepared> {
-  const core = resolveCoreCf({ appRoot, fromSource: flags.fromSource, env: flags.env })
+  const resolved = resolveCoreCf({ appRoot, fromSource: flags.fromSource, env: flags.env })
   const user = await readUserWrangler(appRoot)
-  const warnings = [...core.warnings]
+  const warnings = [...resolved.warnings]
+  // F482: the default date is the core's build date, bounded by what the installed workerd runs (wrangler dev refuses a newer
+  // one). An explicit date is used as written, with a warning when it outruns workerd. Not resolvable: today's behaviour.
+  const workerd = installedWorkerd(appRoot)
+  let core = resolved
+  if (cfg?.compatibilityDate !== undefined) {
+    if (workerd && cfg.compatibilityDate > workerd.date)
+      warnings.push(
+        `[brust] warning cf-compat-date compatibility_date ${cfg.compatibilityDate} in brust.toml is newer than ${workerd.date}, the newest the installed workerd ${workerd.version} runs: \`wrangler dev\` and \`brust dev --target cloudflare\` will not start; lower it or upgrade wrangler`,
+      )
+  } else if (workerd && workerd.date < resolved.meta.compatibilityDate) {
+    if (workerd.date >= CF_MIN_COMPAT_DATE) core = { ...resolved, meta: { ...resolved.meta, compatibilityDate: workerd.date } }
+    else
+      warnings.push(
+        `[brust] warning cf-compat-date the installed workerd ${workerd.version} runs dates only up to ${workerd.date}, older than ${CF_MIN_COMPAT_DATE}, the oldest brust supports: the build keeps ${resolved.meta.compatibilityDate}, but \`wrangler dev\` will not start; upgrade wrangler`,
+      )
+  }
   try {
     const toml = Bun.file(join(appRoot, 'brust.toml'))
     if (await toml.exists()) {
@@ -77,7 +94,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 +108,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 +308,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 +323,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 { checkTrailingSlash, normalizeBasePath, type TrailingSlash } from '../config'
 import { BuildError } from './errors'
 import { posixOf } from './posix'
 
@@ -108,6 +109,10 @@ 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
+  /** `[server] trailing_slash` (F506), baked into the manifest; `strict` (the default) = the path is matched as written. */
+  trailingSlash: TrailingSlash
 }
 
 const isTable = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v)
@@ -274,7 +279,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 +288,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 +406,28 @@ 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
+}
+
+/** `[server] trailing_slash` (F506): the one validator is config.ts's; a bad value is a build error here too. */
+function parseTrailingSlash(file: string, server: unknown): TrailingSlash {
+  if (!isTable(server) || server.trailing_slash === undefined) return 'strict'
+  const r = checkTrailingSlash(server.trailing_slash)
+  if (!r.ok) throw new BuildError('config', `${file}: server.trailing_slash ${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: '', trailingSlash: 'strict' }
   let parsed: unknown
   try {
     parsed = Bun.TOML.parse(await f.text())
@@ -408,17 +435,19 @@ 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 trailingSlash = parseTrailingSlash(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, trailingSlash }
   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, trailingSlash }
   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, trailingSlash }
 }

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/F505: brust's own output dirs, as real absolute paths: each is the base of its own negation in the scan.
+    const own = [...new Set((o.ownOutput ?? []).map(real))]
+    plugins.push(await loadTailwind(appRoot, tw.using[0]!, uses, o.log, 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, trailingSlash } = 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, trailingSlash, 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,10 @@ 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
+    /** `[server] trailing_slash` (F506); `strict` = the default (not written). */
+    trailingSlash: import('../config').TrailingSlash
     /** 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 +260,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, '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
@@ -287,8 +299,10 @@ async function buildInto(
       o.log(`[brust] warning load-writer-in-client ${relPosix(appRoot, w.file)} is imported into the browser chunk of the React island ${c.id}: it changes ${mods} 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`)
       // F480: a server-only import reached through this writer names the chain in `server-only-in-client`.
       ctx.loadWriters ??= new Map()
-      if (!ctx.loadWriters.has(w.file))
-        ctx.loadWriters.set(w.file, `${relPosix(appRoot, w.file)} is loaded into the React island ${c.id} because it is judged to write ${mods} when it loads: F230 load writes`)
+      const lw = ctx.loadWriters.get(w.file) ?? { rel: relPosix(appRoot, w.file), islands: [], writes: [] }
+      if (!lw.islands.includes(c.id)) lw.islands.push(c.id)
+      for (const m of mods.split(', ')) if (!lw.writes.includes(m)) lw.writes.push(m)
+      ctx.loadWriters.set(w.file, lw)
     }
     return [...new Set(out.map((w) => w.file))]
   }
@@ -346,10 +360,14 @@ 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
+  // F506: absent when strict (the default), so an app that sets nothing writes the manifest it always did.
+  if (o.trailingSlash !== 'strict') manifest.trailing_slash = o.trailingSlash
   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,10 @@ 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
+  /** F506 `[server] trailing_slash`: set only when it is not `strict` (`redirect` | `ignore`). */
+  trailing_slash?: 'redirect' | 'ignore'
   /** 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 +322,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 }
 }