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

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-wrangler.ts

@@ -1,8 +1,9 @@
 // `wrangler.jsonc` for `dist/cf/` (M4-CF R5, R6, R7): the user's app-root config merged with the keys brust owns.
 // Pure apart from `readUserWrangler`. Never adds an `account_id`; copies one only if the user wrote it.
 import { existsSync } from 'node:fs'
-import { isAbsolute, join, relative } from 'node:path'
+import { isAbsolute, join } from 'node:path'
 import { BuildError } from './errors'
+import { relPosix } from './posix'
 
 type Json = Record<string, unknown>
 export interface UserWrangler {
@@ -49,7 +50,7 @@ export function workerNameOf(pkgName: string): string {
 }
 
 function rebase(o: MergeOpts, p: string): string {
-  return isAbsolute(p) ? p : relative(o.cfDir, join(o.appRoot, p))
+  return isAbsolute(p) ? p : relPosix(o.cfDir, join(o.appRoot, p))
 }
 
 function assertNoAssetsBinding(v: unknown, path: string): void {

package/src/build/cloudflare.ts

@@ -5,6 +5,7 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import { builtinModules } from 'node:module'
 import { dirname, join, relative } from 'node:path'
+import { relPosix } from './posix'
 import type { BunPlugin } from 'bun'
 import { BrustConfigError, type CorsConfig, loadCors } from '../config'
 import { layoutAssets } from './cf-assets'
@@ -76,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. */
@@ -90,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']
 
@@ -102,7 +106,7 @@ function cfGuard(appRoot: string, violations: string[]): BunPlugin {
     name: 'brust-cf-guard',
     setup(b) {
       b.onResolve({ filter: /^bun(:.*)?$/ }, (a) => {
-        violations.push(`${relative(appRoot, a.importer) || a.importer} imports ${a.path}`)
+        violations.push(`${relPosix(appRoot, a.importer) || a.importer} imports ${a.path}`)
         return { path: a.path, external: true }
       })
       b.onResolve({ filter: /^[a-z_]+(\/[a-z_/]+)?$/ }, (a) => (BUILTINS.has(a.path) ? { path: `node:${a.path}`, external: true } : undefined))
@@ -117,7 +121,7 @@ function cfAlias(alias: Record<string, string>, sourceOf: SourceOf): BunPlugin {
     setup(b) {
       if (Object.keys(alias).length === 0) return
       b.onResolve({ filter: /.*/ }, (a) => {
-        if (a.importer === '' || a.importer.includes('/node_modules/')) return undefined
+        if (a.importer === '' || /[\\/]node_modules[\\/]/.test(a.importer)) return undefined
         let abs: string
         try {
           abs = Bun.resolveSync(a.path, dirname(sourceOf.get(a.importer) ?? a.importer))
@@ -287,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')}`)
@@ -302,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

@@ -4,6 +4,7 @@
 // A component several trees reach keeps one compile, chosen by role, not by route order (F75).
 import { readFileSync, realpathSync } from 'node:fs'
 import { dirname, relative, sep } from 'node:path'
+import { nativeOf, relPosix } from './posix'
 import { type CompiledComponent, type CompiledTree, compileTree, scanLoadWrites } from '../../native/index.js'
 import type { FlatRoute, Route } from '../routes'
 import { BuildError } from './errors'
@@ -29,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?: {
@@ -196,7 +199,7 @@ export function compileApp(opts: {
       )
     let rootId = rootIdOfFile.get(file)
     if (!rootId) {
-      const rel = relative(appRoot, file)
+      const rel = relPosix(appRoot, file) // G5: the Rust resolver assumes `/`
       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()) {
@@ -226,7 +229,7 @@ export function compileApp(opts: {
     ir.stores ??= []
     compiled.set(c.id, {
       id: c.id,
-      file: `${appRoot}/${c.source}`,
+      file: nativeOf(`${appRoot}/${c.source}`), // the spelling Bun.resolveSync returns: these are Map keys and `===` operands
       ir,
       jinja: c.jinja,
       serverTs: c.serverTs,

package/src/build/config.ts

@@ -22,7 +22,9 @@ 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'
 
 // [actions] (opt-in, ruling R6): present table => actions on. Both byte caps cross napi as u32 (F82: 1..64 MiB / 256 KiB..64 MiB).
 //   [actions]
@@ -107,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)
@@ -273,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>
@@ -282,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) {
@@ -396,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())
@@ -407,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) => 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

@@ -122,9 +122,27 @@ const ASSET_FILE = /\.(?:woff2?|ttf|otf|eot|png|jpe?g|gif|webp|avif|svg|ico)$/i
 
 const SOURCE_URL = /url\(\s*(["']?)([^"')]+?)\1\s*\)/g
 
+/** A `url()` value as the file system spells it: CSS escapes undone (Bun prints a Windows path as `C:\\Users\\…`). */
+/** CSS Syntax 4.3.7: an escaped code point that is zero, a surrogate or above U+10FFFF is U+FFFD (never a RangeError). */
+const cssCodePoint = (n: number): number => (n === 0 || n > 0x10ffff || (n >= 0xd800 && n <= 0xdfff) ? 0xfffd : n)
+
+export function cssUnescape(s: string): string {
+  return s.replace(/\\(?:([0-9a-fA-F]{1,6})\s?|([^\n0-9a-fA-F]))/g, (_m, h: string | undefined, c: string | undefined) =>
+    h !== undefined ? String.fromCodePoint(cssCodePoint(Number.parseInt(h, 16))) : c!,
+  )
+}
+
+/** 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. */
-function emitSourceAssets(text: string, assets: { name: string; bytes: Uint8Array }[], suffixed: Map<string, string>): string {
+ * 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>, base = ''): string {
   const emit = (path: string, suffix: string) => {
     const { name, bytes } = hashedAsset(path)
     if (!assets.some((a) => a.name === name)) assets.push({ name, bytes })
@@ -133,12 +151,29 @@ function emitSourceAssets(text: string, assets: { name: string; bytes: Uint8Arra
   return text.replace(SOURCE_URL, (whole, _q: string, path: string) => {
     const abs = suffixed.get(path)
     if (abs !== undefined) return emit(abs, path.slice(path.search(/[?#]/)))
-    const ext = extname(path).toLowerCase()
-    if (!path.startsWith('/') || !SERVED_ASSET_EXT.includes(ext) || path.startsWith('/public/') || path.startsWith('/_brust/') || !existsSync(path)) return whole
-    return emit(path, '')
+    const file = cssUnescape(path)
+    const ext = extname(file).toLowerCase()
+    if (!localAbsolute(file) || !SERVED_ASSET_EXT.includes(ext) || brustUrl(file, base) || !existsSync(file)) return whole
+    return emit(file, '')
   })
 }
 
+/** F490 fail closed: a `url()` left in the built CSS that still names a file on this machine would ship the machine's
+ * 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[], base = ''): string[] {
+  const out: string[] = []
+  for (const m of text.matchAll(SOURCE_URL)) {
+    const v = cssUnescape(m[2]!)
+    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)
+  }
+  return out
+}
+
 /** F393: a `url()` asset with a `?query` / `#fragment` (`?v=3`, `?#iefix`, an SVG font's `#id`) is not given
  * Bun's path form: a plugin-resolved specifier is printed as written. This plugin resolves such a specifier
  * itself and records the file it names, so `emitSourceAssets` can copy it and keep the suffix verbatim. The
@@ -172,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>>()
@@ -189,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`,
@@ -210,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:`
@@ -258,7 +295,11 @@ 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, 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)
   for (const [i, src] of sources.entries()) {
     let text = css.get(i)
@@ -316,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) {
@@ -336,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/esm-resolve.ts

@@ -10,6 +10,7 @@ import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join, sep } from 'node:path'
 import { BuildError } from './errors'
+import { nativeOf } from './posix'
 
 /** A specifier relative to its importer: `./x`, `../x` and the bare `.` / `..` (a directory). The one test every resolver path uses (F218, F244). */
 export const RELATIVE_SPEC = /^\.\.?(\/|$)/
@@ -46,11 +47,14 @@ export function clearResolveCache(): void {
 const PROBE = `
 const [target, entry, spec, define, conditions] = process.argv.slice(1)
 const source = 'import ' + JSON.stringify(spec) + '\\n'
+// F490: on Windows the virtual entry comes back to onLoad as C:/…/__brust_resolve__.ts while argv spells it C:\\…, so
+// the two compare in one spelling; else the entry itself was taken for the answer.
+const entryPosix = entry.replaceAll('\\\\', '/')
 let found
 await Bun.build({
   entrypoints: [entry], target, write: false, define: JSON.parse(define), conditions: JSON.parse(conditions), files: { [entry]: source },
   plugins: [{ name: 'o', setup(b) { b.onLoad({ filter: /./ }, (a) => {
-    if (a.path === entry) return { contents: source, loader: 'ts' }
+    if (a.path.replaceAll('\\\\', '/') === entryPosix) return { contents: source, loader: 'ts' }
     found ??= a.path
     return { contents: '', loader: 'js' }
   }) } }],
@@ -77,7 +81,8 @@ export function resolveNative(spec: string, from: string, target: ResolveTarget,
   const timeout = opts.timeoutMs ?? RESOLVE_TIMEOUT_MS
   const r = Bun.spawnSync([process.execPath, '-e', PROBE, target, join(from, '__brust_resolve__.ts'), spec, defs, conds], { cwd: opts.appRoot ?? from, stdout: 'pipe', stderr: 'pipe', timeout, killSignal: 'SIGKILL' })
   const out = r.exitCode === 0 ? r.stdout.toString() : ''
-  let path = out
+  // F490: one spelling out of the resolver, the platform's (a file system path; POSIX: unchanged).
+  let path = nativeOf(out)
   if (path === '') {
     // The probe did not answer: today's answer (`Bun.resolveSync`) stands, and the build output says why.
     const why = r.exitCode === null || r.signalCode ? `the probe did not answer within ${timeout} ms` : r.exitCode !== 0 ? `the probe failed (${r.stderr.toString().trim().split('\n')[0] || `exit ${r.exitCode}`})` : 'the probe resolved nothing'

package/src/build/index.ts

@@ -5,11 +5,12 @@
 // a previous brust dist (no `manifest.json` / `.brust` marker; `--force` overrides), is refused
 // before anything is written or removed.
 import { createHash } from 'node:crypto'
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+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'
@@ -19,6 +20,8 @@ import { type Compiled, compileApp, scanAppWrites } from './compile'
 import { buildCss, CssGraph, directCss, resolveGlobals, routeCssSources } from './css'
 import { type ActionsBuildConfig, type CacheBuildConfig, loadBuildConfig } from './config'
 import { BuildError } from './errors'
+import { escapes, relPosix } from './posix'
+import { swapDist } from './swap'
 import { importsStore } from './features'
 import { type CacheRecord, type ManifestJson, needsWorkers, reachedJobs, tierOf, writeManifest } from './manifest'
 import { scanRoutes } from './scan'
@@ -83,6 +86,14 @@ function statOk(p: string): boolean {
   }
 }
 
+function realRoot(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
 export async function runBuild(opts: {
   appRoot: string
   entry: string
@@ -96,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`. */
@@ -105,15 +118,19 @@ export async function runBuild(opts: {
   log: (s: string) => void
 }): Promise<void> {
   setDevBuild(opts.dev === true)
-  const appRoot = resolve(opts.appRoot)
+  // The app root is the real path: Windows keeps a symlinked cwd as the link, and `relative(link, file)` across drives is
+  // an absolute path that every `join(appRoot, rel)` then glues onto the link (N2). POSIX cwd is already real.
+  const appRoot = realRoot(resolve(opts.appRoot))
   const entry = resolve(appRoot, opts.entry)
   const dist = resolve(appRoot, opts.outDir)
   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 =
@@ -126,15 +143,18 @@ 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)
     const rel = relative(appRoot, actionsEntry)
-    if (isAbsolute(actions.entry) || rel === '..' || rel.startsWith('../') || isAbsolute(rel) || !statOk(actionsEntry)) {
+    if (isAbsolute(actions.entry) || escapes(rel) || !statOk(actionsEntry)) {
       throw new BuildError('actions-entry', `actions.entry ${actions.entry} is not a file inside the app`)
     }
     // F470: a route under the prefix answers GET and HEAD of its own paths, the actions app everything else there. The
@@ -155,7 +175,7 @@ export async function runBuild(opts: {
   if (cache?.module !== undefined) {
     cacheModule = resolve(appRoot, cache.module)
     const rel = relative(appRoot, cacheModule)
-    if (isAbsolute(cache.module) || rel === '..' || rel.startsWith('../') || isAbsolute(rel) || !statOk(cacheModule)) {
+    if (isAbsolute(cache.module) || escapes(rel) || !statOk(cacheModule)) {
       throw new BuildError('cache', `cache.module ${cache.module} is not a file inside the app`)
     }
   }
@@ -164,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.
@@ -178,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
@@ -186,13 +206,7 @@ export async function runBuild(opts: {
       if (hybrid && cf && actions) writeStaticWorker(tmp, actions, cf, opts.log)
     }
     rmSync(join(tmp, '.stage'), { recursive: true, force: true })
-    if (existsSync(dist)) {
-      const old = join(dirname(dist), `.${basename(dist)}.brust-old`)
-      rmSync(old, { recursive: true, force: true })
-      renameSync(dist, old)
-      renameSync(tmp, dist)
-      rmSync(old, { recursive: true, force: true })
-    } else renameSync(tmp, dist)
+    swapDist(tmp, dist)
   } catch (e) {
     rmSync(tmp, { recursive: true, force: true })
     throw e
@@ -227,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). */
@@ -242,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
@@ -277,12 +293,12 @@ async function buildInto(
     }
     const out = writes.filter((w) => [...w.mods].some((m) => reached.has(m)))
     for (const w of out) {
-      const mods = [...w.mods].filter((m) => reached.has(m)).map((m) => relative(appRoot, m)).join(', ')
-      o.log(`[brust] warning load-writer-in-client ${relative(appRoot, w.file)} is imported into the browser chunk of the React island ${c.id}: it changes ${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`)
+      const mods = [...w.mods].filter((m) => reached.has(m)).map((m) => relPosix(appRoot, m)).join(', ')
+      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, `${relative(appRoot, w.file)} is loaded into the React island ${c.id} because it is judged to write ${mods} when it loads: F230 load writes`)
+        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`)
     }
     return [...new Set(out.map((w) => w.file))]
   }
@@ -340,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)
@@ -376,7 +394,7 @@ async function buildInto(
     )
     for (const w of warnings) o.log(w)
   }
-  const entryRel = relative(o.dist, entry)
+  const entryRel = relPosix(o.dist, entry) // `/`-spelled: a dist built on Windows runs on Linux (join() below re-spells it)
   writeFileSync(
     join(out, 'index.js'),
     [
@@ -399,7 +417,7 @@ export function devJson(appRoot: string, compiled: Map<string, Compiled>): { ver
     const tier = tierOf(c.ir)
     const t = c.ir.tier
     components[c.id] = {
-      file: relative(appRoot, c.file),
+      file: relPosix(appRoot, c.file),
       tier,
       ...(tier === 'react' && t && typeof t === 'object' && 'React' in t ? { reason: String((t as { React: { reason: string } }).React.reason) } : {}),
       diagnostics: (c.diagnostics ?? []).map((d) => ({ class: d.class, rule: d.rule, line: d.line, col: d.col, message: d.message, remediation: d.remediation })),