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

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

@@ -2,7 +2,7 @@
 //   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)
 //   > 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 / 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
@@ -43,6 +43,10 @@ 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
   /** 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 +56,19 @@ 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 }
 
+/** 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(
@@ -112,6 +129,7 @@ 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('actionsBaseUrl', env.actionsBaseUrl ?? cli.actionsBaseUrl ?? fromToml.actionsBaseUrl),
     ...pick('actionsCredentials', cli.actionsCredentials ?? fromToml.actionsCredentials),
   }
@@ -150,6 +168,11 @@ 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.actionsBaseUrl !== undefined) {
     const why = baseUrlError(cli.actionsBaseUrl)
     if (why) throw new BrustConfigError(`config.actionsBaseUrl ${why}`, null)
@@ -176,6 +199,11 @@ 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
+    }
     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) {

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 }

package/src/dev/proxy.ts

@@ -61,13 +61,15 @@ export const WS_PATH = '/_brust/dev/ws'
 export const DEVTOOLS_PATH = '/_brust/dev/devtools.js'
 export const TRACES_PATH = '/_brust/dev/traces'
 export const META_PATH = '/_brust/dev/meta'
-const scriptTag = (gen: number) => `<script type="module" src="${CLIENT_PATH}?g=${gen}"></script><script type="module" src="${DEVTOOLS_PATH}"></script>`
+/** F495: the dev channel's URLs for an app mounted under `base` (`''` = the root): the page's scripts and the WebSocket connect under it. */
+export const devPaths = (base = '') => ({ client: `${base}${CLIENT_PATH}`, ws: `${base}${WS_PATH}`, devtools: `${base}${DEVTOOLS_PATH}`, traces: `${base}${TRACES_PATH}`, meta: `${base}${META_PATH}` })
+const scriptTag = (gen: number, base = '') => `<script type="module" src="${devPaths(base).client}?g=${gen}"></script><script type="module" src="${devPaths(base).devtools}"></script>`
 
 const esc = (s: string) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c] as string)
 
 /** `html` with the dev client script before `</head>` (else at the end). */
-export function inject(html: string, gen: number, trace: unknown | null = null): string {
-  const tag = scriptTag(gen) + (trace ? traceTag(trace) : '')
+export function inject(html: string, gen: number, trace: unknown | null = null, base = ''): string {
+  const tag = scriptTag(gen, base) + (trace ? traceTag(trace) : '')
   const i = html.search(/<\/head\s*>/i)
   return i >= 0 ? html.slice(0, i) + tag + html.slice(i) : html + tag
 }
@@ -93,8 +95,8 @@ export function decodeTrace(h: string | null): unknown | null {
 }
 
 /** A small HTML page (so even a plain-text 5xx or "no child yet" carries the client script). */
-function htmlPage(status: number, title: string, body: string, gen: number, trace: unknown | null = null): Response {
-  const html = `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title>${scriptTag(gen)}${trace ? traceTag(trace) : ''}</head><body style="font:14px ui-monospace,monospace;padding:24px"><h1>${esc(title)}</h1><pre style="white-space:pre-wrap">${esc(body)}</pre></body></html>`
+function htmlPage(status: number, title: string, body: string, gen: number, trace: unknown | null = null, base = ''): Response {
+  const html = `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title>${scriptTag(gen, base)}${trace ? traceTag(trace) : ''}</head><body style="font:14px ui-monospace,monospace;padding:24px"><h1>${esc(title)}</h1><pre style="white-space:pre-wrap">${esc(body)}</pre></body></html>`
   return new Response(html, { status, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' } })
 }
 
@@ -136,7 +138,9 @@ function devtoolsBundle(): Promise<string> {
 /** The trace a proxied response carried (read by `onRequest`; the header itself never reaches the browser). */
 const traceOf = new WeakMap<Response, unknown>()
 
-export function startProxy(o: { hostname: string; port: number; allowedHosts?: string; token: string }, view: DevView): DevProxy {
+export function startProxy(o: { hostname: string; port: number; allowedHosts?: string; token: string; basePath?: string }, view: DevView): DevProxy {
+  const base = o.basePath ?? ''
+  const P = devPaths(base)
   const traces: TraceEntry[] = []
   let seq = 0
   const allowed = allowedHosts(o.hostname, o.allowedHosts ?? process.env.BRUST_DEV_ALLOWED_HOSTS)
@@ -155,7 +159,7 @@ export function startProxy(o: { hostname: string; port: number; allowedHosts?: s
     const port = view.upstream()
     if (port === null) {
       const d = view.diag()
-      return htmlPage(503, d ? `brust dev: ${d.rule}` : 'brust dev: building…', d?.raw ?? 'The first build is running. This page reloads when it is ready.', gen)
+      return htmlPage(503, d ? `brust dev: ${d.rule}` : 'brust dev: building…', d?.raw ?? 'The first build is running. This page reloads when it is ready.', gen, null, base)
     }
     const headers = new Headers(req.headers)
     // The token only this proxy knows: whatever a browser sent under that name is overwritten.
@@ -174,13 +178,13 @@ export function startProxy(o: { hostname: string; port: number; allowedHosts?: s
         // biome-ignore lint/suspicious/noExplicitAny: Bun's fetch option
       } as any)
     } catch (e) {
-      return htmlPage(502, 'brust dev: the server is not reachable', String((e as Error).message ?? e), gen)
+      return htmlPage(502, 'brust dev: the server is not reachable', String((e as Error).message ?? e), gen, null, base)
     }
     const out = new Headers(res.headers)
     // The trace never reaches the browser as a header: it travels in the page (`#__brust_trace`) and `/_brust/dev/traces`.
     const trace = decodeTrace(res.headers.get('x-brust-dev'))
     out.delete('x-brust-dev')
-    const isAction = req.method !== 'GET' && req.method !== 'HEAD' ? true : url.pathname.startsWith('/_brust/action')
+    const isAction = req.method !== 'GET' && req.method !== 'HEAD' ? true : url.pathname.startsWith(`${base}/_brust/action`)
     if (trace || isAction) {
       traces.push({ id: ++seq, at: Date.now(), kind: trace ? 'page' : 'action', method: req.method, path: url.pathname + url.search, status: res.status, ms: Math.round(performance.now() - t0), trace })
       if (traces.length > MAX_TRACES) traces.shift()
@@ -195,9 +199,9 @@ export function startProxy(o: { hostname: string; port: number; allowedHosts?: s
     if (req.method === 'HEAD' || res.status === 204 || res.status === 304) return new Response(null, { status: res.status, headers: out })
     if (/text\/html/i.test(type)) {
       out.set('content-type', type)
-      return tag(new Response(inject(await res.text(), gen, trace), { status: res.status, headers: out }))
+      return tag(new Response(inject(await res.text(), gen, trace, base), { status: res.status, headers: out }))
     }
-    if (doc && res.status >= 500) return tag(htmlPage(res.status, `${res.status} ${res.statusText || 'server error'}`, await res.text(), gen, trace))
+    if (doc && res.status >= 500) return tag(htmlPage(res.status, `${res.status} ${res.statusText || 'server error'}`, await res.text(), gen, trace, base))
     return tag(new Response(res.body, { status: res.status, headers: out }))
   }
 
@@ -216,17 +220,17 @@ export function startProxy(o: { hostname: string; port: number; allowedHosts?: s
       // DNS rebinding: a page on evil.example whose name resolves to 127.0.0.1 would otherwise read the app and the
       // source paths in build errors. Only the dev server's own names are answered.
       if (!allowed.has(hostName(req.headers.get('host') ?? ''))) return new Response('brust dev: unexpected Host header (set BRUST_DEV_ALLOWED_HOSTS to allow it)', { status: 421 })
-      if (url.pathname === WS_PATH && !sameOriginOrNone(req.headers.get('origin'), req.headers.get('host'))) return new Response('brust dev: cross-origin WebSocket refused', { status: 403 })
-      if (url.pathname === WS_PATH) return srv.upgrade(req, { data: undefined }) ? undefined : new Response('websocket expected', { status: 426 })
-      if (url.pathname === TRACES_PATH) return Response.json({ traces }, { headers: { 'cache-control': 'no-store' } })
-      if (url.pathname === META_PATH) return Response.json(view.meta() ?? {}, { headers: { 'cache-control': 'no-store' } })
-      if (url.pathname === DEVTOOLS_PATH) {
+      if (url.pathname === P.ws && !sameOriginOrNone(req.headers.get('origin'), req.headers.get('host'))) return new Response('brust dev: cross-origin WebSocket refused', { status: 403 })
+      if (url.pathname === P.ws) return srv.upgrade(req, { data: undefined }) ? undefined : new Response('websocket expected', { status: 426 })
+      if (url.pathname === P.traces) return Response.json({ traces }, { headers: { 'cache-control': 'no-store' } })
+      if (url.pathname === P.meta) return Response.json(view.meta() ?? {}, { headers: { 'cache-control': 'no-store' } })
+      if (url.pathname === P.devtools) {
         return devtoolsBundle().then(
           (js) => new Response(js, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } }),
           (e: Error) => new Response(e.message, { status: 500 }),
         )
       }
-      if (url.pathname === CLIENT_PATH) return new Response(DEV_CLIENT_JS, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } })
+      if (url.pathname === P.client) return new Response(DEV_CLIENT_JS, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } })
       const t0 = performance.now()
       const res = await forward(req)
       view.onRequest({ method: req.method, path: url.pathname + url.search, status: res.status, ms: Math.round(performance.now() - t0), cache: res.headers.get('x-brust-cache'), trace: traceOf.get(res) ?? null })

package/src/index.ts

@@ -2,6 +2,11 @@
 /// <reference path="./assets.d.ts" />
 // `@brust/core`: the app-facing API.
 export { buildTime } from './build-time'
+
+/** F495 `[server] base_path`: the path the app is mounted under (`/portal`), `''` at the root. Read-only: build URLs with it
+ * (`${basePath}/_brust/…` is brust's own; every URL you write is already the real one). Set from the manifest (`brust start`) or the
+ * config (`brust build`) before the app's modules load. */
+export const basePath: string = process.env.BRUST_BASE_PATH ?? ''
 export { clearNavigationCache, navigate } from './navigate'
 export type { NavErrorDetail, NavLoadDetail, NavigateOptions, NavSuccessDetail, NavTrigger } from './navigate'
 export { cache } from './cache'

package/src/native.ts

@@ -10,6 +10,13 @@ export interface InvalidateArgs {
   tags?: string[]
   path?: string
   method?: string
+  /**
+   * F493: narrow the page invalidation to entries whose evaluated route-cache `prefix` equals this
+   * string exactly (`''` = routes with no prefix). With `path`: that path of that prefix; with
+   * `tags`: that prefix's tagged pages (the job cache is not touched); alone: every page of that
+   * prefix. Not with `key`.
+   */
+  prefix?: string
 }
 export interface InvalidateResult {
   l1Removed: number

package/src/routes.ts

@@ -166,6 +166,19 @@ export function checkCatchAlls(leaves: FlatRoute[]): void {
     throw new BrustRouteError(`more than one '*' route (${all.map((l) => l.id).join(', ')}): M2 allows one root catch-all`, 'duplicate-catch-all')
 }
 
+/** F495: with `[server] base_path` every route is a real URL path under it (`/portal`, `/portal/orders/{id}`): a pattern
+ * outside the base would never be reached, because the server answers 404 for any path outside it. The root `'*'` stays
+ * (it becomes "anything under the base no route matched"). Named error `route-outside-base-path`, listing the ids. */
+export function checkBasePath(leaves: FlatRoute[], basePath: string): void {
+  if (basePath === '') return
+  const outside = leaves.filter((l) => !l.catchAll && l.pattern !== basePath && !l.pattern.startsWith(`${basePath}/`))
+  if (outside.length > 0)
+    throw new BrustRouteError(
+      `routes outside server.base_path ${JSON.stringify(basePath)}: ${outside.map((l) => `${l.id} (${l.pattern})`).join(', ')}; write every route with the base (nest them under { path: ${JSON.stringify(basePath)}, children })`,
+      'route-outside-base-path',
+    )
+}
+
 /** Placeholder for the child route slot inside a layout. The compiler replaces `<Outlet/>`
  * imported from `@brust/core/routes`; rendered by React directly it is empty. */
 export function Outlet(): null {

package/src/run.ts

@@ -35,6 +35,8 @@ export interface RunManifest {
   actions_remote?: { prefix: string } | null
   /** `[cache]`: the server's L2 settings (the workers load the adapter itself). */
   cache?: { adapter: string; getTimeoutMs: number; maxBodyBytes: number; namespace: string; buildId: string } | null
+  /** F495: the `[server] base_path` the build baked in; absent = the app is at the root. */
+  base_path?: string
   /** F165: `false` = no route can call a worker; absent (older manifests) = the pool is needed. */
   needs_workers?: boolean
 }
@@ -81,6 +83,15 @@ function actionsClient(cfg: BrustConfig, m: RunManifest): NonNullable<StartOptio
   return { ...(prefix ? { prefix } : {}), ...(cfg.actionsBaseUrl !== undefined ? { baseUrl: cfg.actionsBaseUrl } : {}), ...(credentials ? { credentials } : {}) }
 }
 
+/** F495: the message when the config names a base path that is not the one the manifest was built for (`base-path-mismatch`), else
+ * null. A config that sets none is fine: the manifest's own is what the server answers under. */
+export function basePathMismatch(cfg: Pick<BrustConfig, 'basePath'>, m: Pick<RunManifest, 'base_path'>): string | null {
+  const built = m.base_path ?? ''
+  if (cfg.basePath === undefined || cfg.basePath === built) return null
+  const show = (p: string) => (p === '' ? 'the root' : JSON.stringify(p))
+  return `base-path-mismatch: server.base_path is ${show(cfg.basePath)} but this build is for ${show(built)}; the base path is baked in at build time, so rebuild (brust build)`
+}
+
 /** Every worker's response buffer, kept reachable until the process exits (see run()). */
 const workerBuffers: SharedArrayBuffer[] = []
 
@@ -111,6 +122,10 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     fail((e as Error).message)
   }
 
+  const mismatch = basePathMismatch(cfg, m)
+  if (mismatch) fail(mismatch)
+  // `basePath` of `@brust/core` in the app's modules (the workers inherit the env).
+  process.env.BRUST_BASE_PATH = m.base_path ?? ''
   if (m.actions_remote && cfg.actionsBaseUrl === undefined)
     fail('this build has no local actions app: set [actions] base_url (or BRUST_ACTIONS_BASE_URL) to the deployment that serves them')
   const version: string = (await Bun.file(join(import.meta.dir, '../package.json')).json()).version