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

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]
@@ -176,6 +177,10 @@ export async function writeStatic(
     o.log(w)
   }
   for (const w of assets.warnings) o.log(w)
+  // F506: a static host serves the files as it likes; brust's trailing-slash policy applies to `brust start` only.
+  const ts = (JSON.parse(readFileSync(join(dist, 'manifest.json'), 'utf8')) as { trailing_slash?: string }).trailing_slash
+  if (ts !== undefined && ts !== 'strict')
+    warn(`warning trailing-slash-static server.trailing_slash = ${JSON.stringify(ts)} does not apply to --target static: the static host decides how a path ending in '/' is served`)
 
   // R9.4: [cache] does not apply to static files, so the render must not need its adapter (a Redis
   // that is not running at build time): the render reads a manifest without `cache`, and the dist

package/src/build/tailwind.ts

@@ -68,8 +68,14 @@ 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`: absolute directories of brust's own output that no scan may read (F501, F505). */
+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 +111,13 @@ 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 dirs, `.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.
+        // F505: each directory is the BASE of its own negation (verified: oxide honours a negated entry whose base differs
+        // from the scanned root, a base outside the root, a base that does not exist yet, and a name with glob characters
+        // such as `dist[1]`, none of which a pattern relative to the app root would survive).
+        const own: SourceEntry[] = ownOutput.map((dir) => ({ base: dir, pattern: '**/*', 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) {

package/src/cache-adapter/conformance.ts

@@ -129,6 +129,48 @@ export function runConformance(make: () => CacheAdapter | Promise<CacheAdapter>,
       expect((await s.get(k2)).page).not.toBeNull()
     })
 
+    if (caps.invalidate !== false) test('F493: prefix + path drops that prefix\'s page only', async () => {
+      const { s } = await store()
+      const [a, b, none] = [key(), key(), key()]
+      await s.set(a, page('a'), meta({ path: '/x', prefix: 'a.test' }))
+      await s.set(b, page('b'), meta({ path: '/x', prefix: 'b.test' }))
+      await s.set(none, page('n'), meta({ path: '/x', prefix: '' }))
+      await s.invalidate({ prefix: 'a.test', path: '/x' })
+      expect((await s.get(a)).page).toBeNull()
+      expect((await s.get(b)).page).not.toBeNull()
+      expect((await s.get(none)).page).not.toBeNull()
+      // `''` is exact: it matches the entry with no prefix only.
+      await s.invalidate({ prefix: '', path: '/x' })
+      expect((await s.get(none)).page).toBeNull()
+      expect((await s.get(b)).page).not.toBeNull()
+    })
+
+    if (caps.invalidate !== false) test('F493: prefix + tags drops that prefix\'s tagged pages; the other prefix stays tagged', async () => {
+      const { s } = await store()
+      const [a, b, a2] = [key(), key(), key()]
+      await s.set(a, page('a'), meta({ tags: ['page'], path: '/p', prefix: 'a.test' }))
+      await s.set(b, page('b'), meta({ tags: ['page'], path: '/p', prefix: 'b.test' }))
+      await s.set(a2, page('a2'), meta({ tags: ['other'], path: '/q', prefix: 'a.test' }))
+      await s.invalidate({ prefix: 'a.test', tags: ['page'] })
+      expect((await s.get(a)).page).toBeNull()
+      expect((await s.get(b)).page).not.toBeNull()
+      expect((await s.get(a2)).page).not.toBeNull()
+      await s.invalidate({ tags: ['page'] })
+      expect((await s.get(b)).page).toBeNull()
+    })
+
+    if (caps.invalidate !== false) test('F493: prefix alone drops every page of that prefix', async () => {
+      const { s } = await store()
+      const [a1, a2, b] = [key(), key(), key()]
+      await s.set(a1, page('1'), meta({ path: '/x', prefix: 'a.test' }))
+      await s.set(a2, page('2'), meta({ tags: ['t'], path: '/y', prefix: 'a.test' }))
+      await s.set(b, page('b'), meta({ path: '/x', prefix: 'b.test' }))
+      await s.invalidate({ prefix: 'a.test' })
+      expect((await s.get(a1)).page).toBeNull()
+      expect((await s.get(a2)).page).toBeNull()
+      expect((await s.get(b)).page).not.toBeNull()
+    })
+
     test('key invalidation is a store no-op', async () => {
       const { s } = await store()
       const k = key()
@@ -168,6 +210,41 @@ export function runConformance(make: () => CacheAdapter | Promise<CacheAdapter>,
       })
     }
 
+    if (caps.guard) {
+      test('F493: a set whose stamp predates an invalidation of its prefix is refused; another prefix lands', async () => {
+        const { a, s } = await store()
+        const [k, other] = [key(), key()]
+        // A path of its own: a store's namespace may outlive one case (an earlier case's path marker must not refuse it).
+        const path = `/${k}`
+        const g = await s.get(k)
+        await s.invalidate({ prefix: 'a.test' })
+        await a.broadcast?.publish({ prefix: 'a.test' }, 'conf')
+        expect(await s.set(k, page('stale'), meta({ path, prefix: 'a.test', stamp: g.stamp }))).toBe(false)
+        expect((await s.get(k)).page).toBeNull()
+        expect(await s.set(other, page('b'), meta({ path, prefix: 'b.test', stamp: g.stamp }))).toBe(true)
+        const g2 = await s.get(k)
+        expect(await s.set(k, page('fresh'), meta({ path, prefix: 'a.test', stamp: g2.stamp }))).toBe(true)
+      })
+    }
+
+    test('F493: the broadcast carries prefix in its args', async () => {
+      const a = await fresh()
+      if (!a.broadcast?.subscribe && !a.broadcast?.since) return
+      const args = { prefix: 'a.test', path: '/b' }
+      if (a.broadcast.subscribe) {
+        const got: InvalidationEvent[] = []
+        const stop = await a.broadcast.subscribe(e => got.push(e), () => {})
+        const seq = await a.broadcast.publish(args, 'o1')
+        await until('delivery', () => got.length === 1)
+        expect(got[0]).toEqual({ seq, origin: 'o1', args })
+        await stop()
+      } else {
+        const base = (await a.broadcast.since!(0)).seq
+        await a.broadcast.publish(args, 'o1')
+        expect((await a.broadcast.since!(base)).events.map(e => e.args)).toEqual([args])
+      }
+    })
+
     test('publish seqs strictly increase; get().stamp is the last seq (one space)', async () => {
       const a = await fresh()
       if (!a.broadcast) return

package/src/cache-adapter/memory.ts

@@ -32,6 +32,8 @@ interface Entry {
   tags: string[]
   method: string
   path: string
+  /** The route-cache key prefix (F493); `''` = none. */
+  prefix: string
   entryStamp: number | null
   storedAt: number
   expiresAt: number
@@ -57,6 +59,42 @@ export type MemoryAdapter = CacheAdapter & { store: CacheStore; __test: MemoryAd
 
 const pathName = (method: string | undefined, path: string) => `${method ?? 'GET'} ${path}`
 
+// Marker names (F493: scoped by prefix, so one prefix's invalidation refuses only that prefix's stale
+// writes). A prefix is JSON-quoted: self-delimiting, so names of different prefixes never meet.
+const tagName = (t: string) => `t:${t}`
+const pName = (m: string | undefined, p: string) => `p:${pathName(m, p)}`
+const px = (prefix: string) => `px:${JSON.stringify(prefix)}`
+const ptName = (prefix: string, t: string) => `pt:${JSON.stringify(prefix)}${t}`
+const ppName = (prefix: string, m: string | undefined, p: string) => `pp:${JSON.stringify(prefix)}${pathName(m, p)}`
+
+/** The marker names an invalidation raises. `{ prefix }` alone ignores `method` (conservative). */
+function invalidationNames(a: InvalidateArgs): string[] {
+  const tags = a.tags ?? []
+  const pre = a.prefix
+  if (pre === undefined) return [...tags.map(tagName), ...(a.path !== undefined ? [pName(a.method, a.path)] : [])]
+  if (!tags.length && a.path === undefined) return [px(pre)]
+  return [...tags.map(t => ptName(pre, t)), ...(a.path !== undefined ? [ppName(pre, a.method, a.path)] : [])]
+}
+
+/** Every marker name that covers an entry. */
+function entryNames(e: { tags: string[]; method: string; path: string; prefix: string }): string[] {
+  return [
+    ...e.tags.map(tagName),
+    pName(e.method, e.path),
+    px(e.prefix),
+    ...e.tags.map(t => ptName(e.prefix, t)),
+    ppName(e.prefix, e.method, e.path),
+  ]
+}
+
+/** Does `a` delete `e`? (`key` alone deletes nothing: the store holds pages only.) */
+function covers(a: InvalidateArgs, e: Entry): boolean {
+  if (a.prefix !== undefined && e.prefix !== a.prefix) return false
+  const tags = a.tags ?? []
+  if (!tags.length && a.path === undefined) return a.prefix !== undefined && (a.method === undefined || a.method === e.method)
+  return e.tags.some(t => tags.includes(t)) || (a.path !== undefined && pathName(e.method, e.path) === pathName(a.method, a.path))
+}
+
 export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
   const mode = o.broadcast ?? 'push'
   const ringCap = o.ring ?? 1024
@@ -64,8 +102,7 @@ export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
   const maxBodyBytes = o.maxBodyBytes ?? 8_388_608
   const now = o.now ?? Date.now
   const entries = new Map<string, Entry>()
-  const tagSeq = new Map<string, number>()
-  const pathSeq = new Map<string, number>()
+  const nameSeq = new Map<string, number>()
   let seq = 0
   // Drawn on first use: a Workers module may not make random values at global scope.
   let genValue: string | null = null
@@ -86,10 +123,8 @@ export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
     fail = false
     return true
   }
-  const raise = (m: Map<string, number>, k: string, s: number) => m.set(k, Math.max(m.get(k) ?? 0, s))
   const mark = (args: InvalidateArgs, s: number) => {
-    for (const t of args.tags ?? []) raise(tagSeq, t, s)
-    if (args.path !== undefined) raise(pathSeq, pathName(args.method, args.path), s)
+    for (const n of invalidationNames(args)) nameSeq.set(n, Math.max(nameSeq.get(n) ?? 0, s))
   }
 
   const store: CacheStore = {
@@ -113,10 +148,10 @@ export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
     async set(key: string, page: StoredPage, meta: SetMeta): Promise<boolean> {
       if (failing()) throw new Error('memory adapter: injected failure')
       if (page.body.length > maxBodyBytes) return false
+      const prefix = meta.prefix ?? ''
       if (meta.stamp !== null) {
         const s = meta.stamp
-        const stale = (m: Map<string, number>, k: string) => (m.get(k) ?? 0) > s
-        if (meta.tags.some(t => stale(tagSeq, t)) || stale(pathSeq, pathName(meta.method, meta.path))) return false
+        if (entryNames({ ...meta, prefix }).some(n => (nameSeq.get(n) ?? 0) > s)) return false
       }
       const at = now()
       entries.set(key, {
@@ -124,6 +159,7 @@ export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
         tags: [...meta.tags],
         method: meta.method,
         path: meta.path,
+        prefix,
         entryStamp: meta.stamp,
         storedAt: at,
         expiresAt: at + meta.ttlMs,
@@ -140,11 +176,7 @@ export function memoryAdapter(o: MemoryAdapterOptions = {}): MemoryAdapter {
       // L7b: the marker first, at the seq the matching publish will take (seq + 1), so a set whose
       // stamp was read before this call is refused from now on; then the delete.
       mark(args, seq + 1)
-      const tags = new Set(args.tags ?? [])
-      const p = args.path === undefined ? null : pathName(args.method, args.path)
-      for (const [k, e] of entries) {
-        if (e.tags.some(t => tags.has(t)) || (p !== null && pathName(e.method, e.path) === p)) entries.delete(k)
-      }
+      for (const [k, e] of entries) if (covers(args, e)) entries.delete(k)
     },
   }
 

package/src/cache-adapter/types.ts

@@ -21,6 +21,11 @@ export interface SetMeta {
   tags: string[]
   method: string
   path: string
+  /**
+   * The entry's evaluated route-cache key prefix (`''` = none), for `invalidate({ prefix })` (F493).
+   * Absent only from callers older than F493: treat it as `''`.
+   */
+  prefix?: string
   /** The `stamp` the lookup returned (read before the render); `null` = unguarded write. */
   stamp: number | null
 }
@@ -45,7 +50,8 @@ export interface CacheStore {
   /**
    * Shared-side delete by tags/path (`key` is a no-op: the store holds pages only). Records the
    * invalidation marker BEFORE deleting, so a concurrent stale `set` is refused even before the
-   * publish (ruling L7b).
+   * publish (ruling L7b). With `prefix` (F493) only entries whose `SetMeta.prefix` equals it are
+   * deleted (`{ prefix }` alone: every page of that prefix); entries of other prefixes stay.
    */
   invalidate(args: InvalidateArgs): Promise<void>
   readonly maxBodyBytes: number

package/src/cache.ts

@@ -9,8 +9,19 @@ import { type InvalidateArgs, type InvalidateResult, cacheInvalidate } from './n
 export type { ComponentCacheOptions } from './cache-core'
 
 const NO_SERVER = 'cache.invalidate needs a running server (call it inside `brust start`)'
+/** Same text as brust-core `PREFIX_WITH_KEY` (the Rust hosts refuse it too). */
+export const PREFIX_WITH_KEY = 'cache.invalidate: `prefix` narrows page entries; `key` names a job entry — call them separately'
+
+/** F493: `prefix` is a string and never comes with `key`. Throws a TypeError otherwise. */
+export function checkInvalidateArgs(args: InvalidateArgs): void {
+  const prefix = (args as { prefix?: unknown } | null | undefined)?.prefix
+  if (prefix === undefined) return
+  if (typeof prefix !== 'string') throw new TypeError(`cache.invalidate: \`prefix\` must be a string (got ${prefix === null ? 'null' : typeof prefix})`)
+  if (args.key !== undefined) throw new TypeError(PREFIX_WITH_KEY)
+}
 
 function invalidate(args: InvalidateArgs): InvalidateResult {
+  checkInvalidateArgs(args)
   let r: InvalidateResult
   try {
     r = cacheInvalidate(args)

package/src/cf.ts

@@ -2,6 +2,9 @@
 // Same names as `index.ts` minus what needs a host process: no `run`, no `loadConfig`. `cache.invalidate` goes through
 // the CF bundle's napi stub to the runtime the wasm glue installed at start (`server-handlers` `install`).
 export { buildTime } from './build-time'
+
+/** F495 `[server] base_path` (see index.ts). The Cloudflare build bakes the manifest's value into the Worker bundle (`process.env.BRUST_BASE_PATH` is a `define`), `''` at the root. */
+export const basePath: string = typeof process === 'undefined' ? '' : (process.env.BRUST_BASE_PATH ?? '')
 export { navigate } from './navigate'
 export type { NavErrorDetail, NavLoadDetail, NavigateOptions, NavSuccessDetail, NavTrigger } from './navigate'
 export { cache } from './cache'

package/src/config.ts

@@ -1,8 +1,8 @@
 // Runtime configuration (spec §8). Precedence, high → low:
 //   env (BRUST_ADDR / BRUST_PORT / BRUST_WORKERS / BRUST_RENDER_SLOTS / BRUST_DRAIN_TIMEOUT_MS /
-//        BRUST_BOOT_TIMEOUT_MS / BRUST_CALL_TIMEOUT_MS / BRUST_SLOT_BYTES / BRUST_MAX_LOADER_RESPONSE_BYTES)
+//        BRUST_BOOT_TIMEOUT_MS / BRUST_CALL_TIMEOUT_MS / BRUST_SLOT_BYTES / BRUST_MAX_LOADER_RESPONSE_BYTES / BRUST_STATS)
 //   > CLI flags (`brust start --port/--workers`) and `run({ config })`
-//   > brust.toml ([server] address / port / max_loader_response_bytes, [workers] count / slot_bytes, [cors], [actions] base_url / credentials)
+//   > brust.toml ([server] address / port / base_path / stats / stats_token / max_loader_response_bytes, [workers] count / slot_bytes, [cors], [actions] base_url / credentials)
 //   > defaults (localhost, 1337, availableParallelism(), 1, 10000, 30000, 30000, 262144, 8388608).
 // L16 R16.1: `actionsBaseUrl` follows env (BRUST_ACTIONS_BASE_URL) > run({ config }) > toml `[actions] base_url`.
 // `cors` has no env layer; `run({ config: { cors } })` replaces a toml `[cors]` as a whole (never merged), and
@@ -24,6 +24,20 @@ export interface CorsConfig {
   maxAgeSeconds?: number
 }
 
+/** F507 `[server] stats`: who may read `/_brust/cache/stats`. */
+export const STATS_MODES = ['off', 'public', 'token'] as const
+export type StatsMode = (typeof STATS_MODES)[number]
+/** F507 `[server] stats_token`: an env reference only, never the secret itself (like `[cache.redis] url`). */
+const STATS_TOKEN_REF = /^env:[A-Za-z_][A-Za-z0-9_]*$/
+
+/** Why `[server] stats` / `stats_token` (or `run({ config })`) are wrong, or `undefined`. The secret never appears in the message. */
+function statsError(mode: unknown, token: unknown, where: string): string | undefined {
+  if (mode !== undefined && !STATS_MODES.includes(mode as StatsMode)) return `${where}stats must be one of ${STATS_MODES.join(', ')} (got ${JSON.stringify(mode)})`
+  if (token !== undefined && (typeof token !== 'string' || !STATS_TOKEN_REF.test(token)))
+    return `${where}stats_token must be "env:NAME" (a literal token is refused: it would sit in a file)`
+  return undefined
+}
+
 export interface BrustConfig {
   host: string
   port: number
@@ -43,6 +57,19 @@ export interface BrustConfig {
   maxLoaderResponseBytes: number
   /** `run({ config: { cors } })` over brust.toml `[cors]` (a whole-object replace); absent = CORS off. No env layer. */
   cors?: CorsConfig
+  /** F495 `[server] base_path` / `run({ config: { basePath } })`: the path the app is mounted under on a shared origin (`/portal`; `''` = the
+   * root), absent when nothing set it. A build setting too (`brust build` bakes it into the manifest): `brust start` refuses a manifest
+   * built for another one, and with none set serves the one the manifest names. */
+  basePath?: string
+  /** F506 `[server] trailing_slash` / `run({ config: { trailingSlash } })`: what a page request whose path ends in `/` gets — `strict` (matched
+   * as written, the default), `redirect` (GET/HEAD answer 308 to the path without it, query kept) or `ignore` (the slash is dropped before
+   * matching). A build setting too (baked into the manifest): `brust start` refuses a manifest built with another one. */
+  trailingSlash?: TrailingSlash
+  /** F507 `[server] stats` / `run({ config: { stats } })`: who may read `/_brust/cache/stats` (`off` = 404, `public`, `token` = a bearer
+   * token). Absent = `off` for `brust start`, `public` under `brust dev`. */
+  stats?: StatsMode
+  /** F507 `[server] stats_token` / `run({ config: { statsToken } })`: `"env:NAME"`, the variable that holds the bearer token (`stats = "token"` only). */
+  statsToken?: string
   /** L16 R16.1: the origin the browser `client()` calls (page script `__BRUST_ACTION_BASE__`); absent = same origin. */
   actionsBaseUrl?: string
   /** L16 R16.2: the client's default `RequestInit.credentials` (`__BRUST_ACTION_CREDENTIALS__`); absent = `same-origin`. */
@@ -52,6 +79,29 @@ export interface BrustConfig {
 /** What `run({ config })` / `loadConfig`'s `cli` accepts: any setting, and `cors: null` to turn a toml `[cors]` off. */
 export type ConfigOverrides = Omit<Partial<BrustConfig>, 'cors'> & { cors?: (Omit<CorsConfig, 'credentials'> & { credentials?: boolean }) | null }
 
+/** F506: the `[server] trailing_slash` values. */
+export const TRAILING_SLASH = ['strict', 'redirect', 'ignore'] as const
+export type TrailingSlash = (typeof TRAILING_SLASH)[number]
+
+/** F506: `[server] trailing_slash`, validated; the reason it is refused otherwise. */
+export function checkTrailingSlash(raw: unknown): { ok: true; value: TrailingSlash } | { ok: false; why: string } {
+  if (typeof raw === 'string' && (TRAILING_SLASH as readonly string[]).includes(raw)) return { ok: true, value: raw as TrailingSlash }
+  return { ok: false, why: `must be one of ${TRAILING_SLASH.map((v) => JSON.stringify(v)).join(', ')} (got ${JSON.stringify(raw)})` }
+}
+
+/** F495: `[server] base_path`, validated: `/seg[/seg…]`, no trailing `/`, each segment `[A-Za-z0-9._~-]+` (not `.`/`..`), the
+ * same alphabet as the actions prefix, so it needs no percent-encoding anywhere it is printed. `""` and `"/"` mean the
+ * root (`""`). Returns the value, or the reason it is refused. */
+export function normalizeBasePath(raw: unknown): { ok: true; value: string } | { ok: false; why: string } {
+  if (typeof raw !== 'string') return { ok: false, why: `must be a string (got ${JSON.stringify(raw)})` }
+  if (raw === '' || raw === '/') return { ok: true, value: '' }
+  if (!raw.startsWith('/')) return { ok: false, why: `must start with '/' (got ${JSON.stringify(raw)})` }
+  if (raw.endsWith('/')) return { ok: false, why: `must not end with '/' (got ${JSON.stringify(raw)})` }
+  if (raw.slice(1).split('/').some((seg) => !/^[A-Za-z0-9._~-]+$/.test(seg) || seg === '.' || seg === '..'))
+    return { ok: false, why: `segments must be [A-Za-z0-9._~-]+ and not '.'/'..' (got ${JSON.stringify(raw)})` }
+  return { ok: true, value: raw }
+}
+
 export class BrustConfigError extends Error {
   override name = 'BrustConfigError'
   constructor(
@@ -99,6 +149,11 @@ export async function loadConfig(cwd: string = process.cwd(), cli: ConfigOverrid
   checkCli(cli)
   // cli (validated, normalised) over toml as a whole object (R10.2); `null` = off.
   const cors = cli.cors === undefined ? fromToml.cors : cli.cors === null ? undefined : checkCors(cli.cors, 'config.cors', null, false)
+  // F507: the two keys belong together, wherever each one came from.
+  const stats = env.stats ?? cli.stats ?? fromToml.stats
+  const statsToken = cli.statsToken ?? fromToml.statsToken
+  if (stats === 'token' && statsToken === undefined) throw new BrustConfigError('stats = "token" needs stats_token = "env:NAME" (the variable that holds the bearer token)', null)
+  if (statsToken !== undefined && stats !== 'token') throw new BrustConfigError('stats_token is used only with stats = "token"', null)
   return {
     host: env.host ?? cli.host ?? fromToml.host ?? DEFAULTS.host,
     port: env.port ?? cli.port ?? fromToml.port ?? DEFAULTS.port,
@@ -112,6 +167,10 @@ export async function loadConfig(cwd: string = process.cwd(), cli: ConfigOverrid
     maxLoaderResponseBytes: env.maxLoaderResponseBytes ?? cli.maxLoaderResponseBytes ?? fromToml.maxLoaderResponseBytes ?? DEFAULTS.maxLoaderResponseBytes,
     ioThreads: env.ioThreads ?? cli.ioThreads,
     ...(cors ? { cors } : {}),
+    ...pick('basePath', cli.basePath ?? fromToml.basePath),
+    ...pick('trailingSlash', cli.trailingSlash ?? fromToml.trailingSlash),
+    ...pick('stats', stats),
+    ...pick('statsToken', statsToken),
     ...pick('actionsBaseUrl', env.actionsBaseUrl ?? cli.actionsBaseUrl ?? fromToml.actionsBaseUrl),
     ...pick('actionsCredentials', cli.actionsCredentials ?? fromToml.actionsCredentials),
   }
@@ -150,6 +209,17 @@ function checkCli(cli: ConfigOverrides): void {
   check('ioThreads', cli.ioThreads, 1, MAX_IO_THREADS)
   check('slotBytes', cli.slotBytes, MIN_SLOT_BYTES, MAX_SLOT_BYTES)
   check('maxLoaderResponseBytes', cli.maxLoaderResponseBytes, MIN_LOADER_RESPONSE_BYTES, MAX_LOADER_RESPONSE_BYTES)
+  if (cli.basePath !== undefined) {
+    const r = normalizeBasePath(cli.basePath)
+    if (!r.ok) throw new BrustConfigError(`config.basePath ${r.why}`, null)
+    cli.basePath = r.value
+  }
+  if (cli.trailingSlash !== undefined) {
+    const r = checkTrailingSlash(cli.trailingSlash)
+    if (!r.ok) throw new BrustConfigError(`config.trailingSlash ${r.why}`, null)
+  }
+  const badStats = statsError(cli.stats, cli.statsToken, 'config.')
+  if (badStats) throw new BrustConfigError(badStats, null)
   if (cli.actionsBaseUrl !== undefined) {
     const why = baseUrlError(cli.actionsBaseUrl)
     if (why) throw new BrustConfigError(`config.actionsBaseUrl ${why}`, null)
@@ -176,6 +246,20 @@ function fromTomlTable(parsed: unknown, file: string): Partial<BrustConfig> {
   if ('server' in root) {
     const server = table(root.server, '[server]', file)
     const { port, address } = server
+    if (server.base_path !== undefined) {
+      const r = normalizeBasePath(server.base_path)
+      if (!r.ok) throw new BrustConfigError(`${file}: server.base_path ${r.why}`, file)
+      out.basePath = r.value
+    }
+    if (server.trailing_slash !== undefined) {
+      const r = checkTrailingSlash(server.trailing_slash)
+      if (!r.ok) throw new BrustConfigError(`${file}: server.trailing_slash ${r.why}`, file)
+      out.trailingSlash = r.value
+    }
+    const bad = statsError(server.stats, server.stats_token, `${file}: server.`)
+    if (bad) throw new BrustConfigError(bad, file)
+    if (server.stats !== undefined) out.stats = server.stats as StatsMode
+    if (server.stats_token !== undefined) out.statsToken = server.stats_token as string
     const cap = tomlInt(server.max_loader_response_bytes, 'server.max_loader_response_bytes', MIN_LOADER_RESPONSE_BYTES, MAX_LOADER_RESPONSE_BYTES, file)
     if (cap !== undefined) out.maxLoaderResponseBytes = cap
     if (port !== undefined) {
@@ -292,6 +376,11 @@ function fromEnv(): Partial<BrustConfig> {
   out.slotBytes = envInt('BRUST_SLOT_BYTES', MIN_SLOT_BYTES, MAX_SLOT_BYTES, `an integer in ${MIN_SLOT_BYTES}..${MAX_SLOT_BYTES}`)
   out.maxLoaderResponseBytes = envInt('BRUST_MAX_LOADER_RESPONSE_BYTES', MIN_LOADER_RESPONSE_BYTES, MAX_LOADER_RESPONSE_BYTES, `an integer in ${MIN_LOADER_RESPONSE_BYTES}..${MAX_LOADER_RESPONSE_BYTES}`)
   out.ioThreads = envInt('BRUST_WORKER_THREADS', 1, MAX_IO_THREADS, `an integer in 1..${MAX_IO_THREADS}`)
+  const stats = process.env.BRUST_STATS
+  if (stats !== undefined && stats !== '') {
+    if (!STATS_MODES.includes(stats as StatsMode)) throw new BrustConfigError(`BRUST_STATS must be one of ${STATS_MODES.join(', ')} (got ${JSON.stringify(stats)})`, null)
+    out.stats = stats as StatsMode
+  }
   const base = process.env.BRUST_ACTIONS_BASE_URL
   if (base !== undefined && base !== '') {
     const why = baseUrlError(base)

package/src/dev/bun.ts

@@ -77,9 +77,9 @@ function pumpLines(stream: ReadableStream<Uint8Array> | null | undefined, onLine
 }
 
 /** L19/L21 dev swap: the built stylesheets of the old and the new generation, paired by source stem
- * (`<stem>-<hex10>.css`), as `/_brust/client/<old>` → `/_brust/client/<new>`. `null` when the pairing is not
+ * (`<stem>-<hex10>.css`), as `<base>/_brust/client/<old>` → `<base>/_brust/client/<new>`. `null` when the pairing is not
  * one-to-one (a stylesheet was added or removed, or two sources share a stem): the page must reload. */
-export function cssSwapMap(oldDir: string, newDir: string): Record<string, string> | null {
+export function cssSwapMap(oldDir: string, newDir: string, base = ''): Record<string, string> | null {
   const byStem = (dir: string) => {
     const m = new Map<string, string>()
     let files: string[] = []
@@ -101,7 +101,7 @@ export function cssSwapMap(oldDir: string, newDir: string): Record<string, strin
   for (const [stem, f] of a) {
     const g = b.get(stem)
     if (g === undefined) return null
-    if (g !== f) map[`/_brust/client/${f}`] = `/_brust/client/${g}`
+    if (g !== f) map[`${base}/_brust/client/${f}`] = `${base}/_brust/client/${g}`
   }
   return map
 }
@@ -123,6 +123,8 @@ export async function runBunDev(o: BunDevOptions): Promise<number> {
   const mode = tuiMode(out, env)
   const tui = new Tui(out, mode.interactive, mode.color)
   const cfg = await loadConfig(appRoot, o.port !== undefined ? { port: o.port } : {})
+  // F495: `[server] base_path`: the dev channel (`<base>/_brust/dev/*`) and the app's own URLs live under it, so two apps behind one path proxy can both run.
+  const base = cfg.basePath ?? ''
   const workers = o.workers ?? 1
   const devRoot = join(appRoot, '.brust', 'dev')
   rmSync(devRoot, { recursive: true, force: true })
@@ -165,7 +167,7 @@ export async function runBunDev(o: BunDevOptions): Promise<number> {
   }
 
   const proxy: DevProxy = startProxy(
-    { hostname: cfg.host, port: cfg.port, token: devToken },
+    { hostname: cfg.host, port: cfg.port, token: devToken, basePath: base },
     {
       gen: () => gen,
       state: () => state,
@@ -175,7 +177,7 @@ export async function runBunDev(o: BunDevOptions): Promise<number> {
       actionsPrefix: () => prefixOf(active),
       onRequest(r) {
         tui.log(`${r.method} ${r.path} ${r.status} ${r.ms}ms${r.cache ? ` ${r.cache}` : ''}`)
-        if (!r.path.startsWith('/_brust/')) {
+        if (!r.path.startsWith(`${base}/_brust/`)) {
           const rendered = (r.trace as { rendered?: string[] } | null)?.rendered
           last = { method: r.method, path: r.path, status: r.status, ...(rendered ? { tiers: tierCounts(rendered, devMeta() as Parameters<typeof tierCounts>[1]) } : {}) }
           publish()
@@ -303,7 +305,7 @@ export async function runBunDev(o: BunDevOptions): Promise<number> {
     state = 'ready'
     diag = null
     // A stylesheet-only edit (L19/L21): the pages keep their DOM and swap their brust CSS links.
-    const swap = cssOnly && old ? cssSwapMap(old.dir, child.dir) : null
+    const swap = cssOnly && old ? cssSwapMap(old.dir, child.dir, base) : null
     if (swap) {
       proxy.broadcast({ type: 'css-swap', gen, map: swap })
       tui.log(`[brust] css rebuilt (${Object.keys(swap).length} stylesheet${Object.keys(swap).length === 1 ? '' : 's'} swapped, no reload)`)

package/src/dev/client.ts

@@ -78,7 +78,10 @@ function handle(m) {
 }
 
 function connect() {
-  const ws = new WebSocket((location.protocol === 'https:' ? 'wss://' : 'ws://') + location.host + '/_brust/dev/ws')
+  // F495: the socket lives next to this script (<base>/_brust/dev/ws), wherever the app is mounted.
+  const wsUrl = new URL('ws', import.meta.url)
+  wsUrl.protocol = wsUrl.protocol === 'https:' ? 'wss:' : 'ws:'
+  const ws = new WebSocket(wsUrl)
   ws.onopen = () => {
     delay = 150
   }

package/src/dev/devtools.ts

@@ -109,17 +109,19 @@ class BrustDevtools extends HTMLElement {
   }
 
   private async loadMeta(): Promise<void> {
-    try { this.meta = (await (await fetch('/_brust/dev/meta')).json()) as DevMeta } catch { this.meta = null }
+    try { this.meta = (await (await fetch(new URL('meta', import.meta.url))).json()) as DevMeta } catch { this.meta = null }
     this.paintIndicator()
     if (!this.panel.hidden) this.render()
   }
 
   private async loadEntries(): Promise<void> {
-    try { this.entries = ((await (await fetch('/_brust/dev/traces')).json()) as { traces: Entry[] }).traces } catch { this.entries = [] }
+    try { this.entries = ((await (await fetch(new URL('traces', import.meta.url))).json()) as { traces: Entry[] }).traces } catch { this.entries = [] }
   }
 
   private connect(): void {
-    const ws = new WebSocket(`${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}/_brust/dev/ws`)
+    const wsUrl = new URL('ws', import.meta.url)
+    wsUrl.protocol = wsUrl.protocol === 'https:' ? 'wss:' : 'ws:'
+    const ws = new WebSocket(wsUrl)
     ws.onmessage = (e) => {
       const m = JSON.parse(e.data as string) as { type: string; gen?: number; state?: BuildState['state']; diag?: BuildState['diag'] }
       if (m.type === 'hello') this.build = { state: m.state ?? 'ready', gen: m.gen ?? 0, diag: m.diag ?? null }