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

package/src/dev/bun.ts

@@ -9,6 +9,7 @@ import { loadConfig } from '../config'
 import { type Diag, parseBuildError, parseWarnings } from './diag'
 import { tierCounts } from './devtools-data'
 import { type DevProxy, startProxy } from './proxy'
+import { openCommand } from './open'
 import { HOTKEYS, Tui, type TuiOut, tuiMode } from './tui'
 import { loadBuildConfig } from '../build/config'
 import { broadRootWarnings, changeLine, defaultIgnored, watchLoop } from './watch'
@@ -76,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[] = []
@@ -100,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
 }
@@ -122,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 })
@@ -164,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,
@@ -174,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()
@@ -302,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)`)
@@ -373,13 +376,14 @@ export async function runBunDev(o: BunDevOptions): Promise<number> {
       for (const k of b.toString()) {
         if (k === 'q' || k === '\x03') void stop()
         else if (k === 'r') proxy.broadcast({ type: 'reload' })
-        else if (k === 'o') Bun.spawn([process.platform === 'darwin' ? 'open' : 'xdg-open', url], { stdout: 'ignore', stderr: 'ignore' })
+        else if (k === 'o') Bun.spawn(openCommand(url), { stdout: 'ignore', stderr: 'ignore' })
         else if (k === 'w') for (const w of warnings.length ? warnings : ['no warnings']) tui.log(`warning ${w}`)
         else if (k === 'c') tui.clear()
       }
     })
     ;(out as unknown as NodeJS.WriteStream).on?.('resize', () => tui.resize())
   }
+  // F485 P12: on Windows Ctrl+C (SIGINT) reaches this handler; SIGTERM handlers rarely fire and a kill ends the process without a drain.
   process.on('SIGINT', () => void stop())
   process.on('SIGTERM', () => void stop())
 

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/open.ts

@@ -0,0 +1,7 @@
+// F485 P7: the command that opens `url` in the default browser (dev hotkey `o`). Argv array, no shell string.
+export function openCommand(url: string, platform: string = process.platform): string[] {
+  if (platform === 'darwin') return ['open', url]
+  // cmd parses `&` in a URL as a separator: fine for the internal localhost URL this is called with.
+  if (platform === 'win32') return ['cmd', '/c', 'start', '', url] // the empty string is `start`'s window title slot
+  return ['xdg-open', url]
+}

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/dev.ts

@@ -1,7 +1,8 @@
 // `brust dev [entry] --target cloudflare [-- <wrangler args>]` (M4-CF R10): build, run `wrangler dev` on the
 // generated project, rebuild + restart wrangler on a source change. No HMR. Each build runs in a child
 // process: a failed build keeps the old wrangler, and module caches never leak between builds.
-import { join, relative, resolve } from 'node:path'
+import { delimiter, join, relative, resolve } from 'node:path'
+import { posixOf } from './build/posix'
 import { BuildError } from './build/errors'
 import { loadBuildConfig } from './build/config'
 import { broadRootWarnings, defaultIgnored, type WatchLoop, watchLoop } from './dev/watch'
@@ -21,7 +22,7 @@ const DEBOUNCE_MS = 300
 function wranglerBin(appRoot: string): string {
   const fake = process.env.BRUST_WRANGLER
   if (fake) return fake
-  const found = Bun.which('wrangler', { PATH: `${join(appRoot, 'node_modules', '.bin')}:${process.env.PATH ?? ''}` })
+  const found = Bun.which('wrangler', { PATH: `${join(appRoot, 'node_modules', '.bin')}${delimiter}${process.env.PATH ?? ''}` })
   if (!found) throw new BuildError('cf-dev', 'wrangler not found (bun add -d wrangler)')
   return found
 }
@@ -71,7 +72,7 @@ export async function runDev(o: DevOptions): Promise<number> {
   const loop: WatchLoop = watchLoop({
     root: appRoot,
     extraRoots,
-    ignored: (rel) => defaultIgnored(rel, relative(appRoot, dist)),
+    ignored: (rel) => defaultIgnored(rel, posixOf(relative(appRoot, dist))),
     debounceMs: DEBOUNCE_MS,
     async run() {
       o.log('[brust] change detected; rebuilding')
@@ -91,6 +92,7 @@ export async function runDev(o: DevOptions): Promise<number> {
     loop.close()
     void stopChild().then(() => exitCode(0))
   }
+  // F485 P12: on Windows Ctrl+C (SIGINT) reaches this handler; SIGTERM handlers rarely fire and a kill ends the process without a drain.
   process.on('SIGINT', stop)
   process.on('SIGTERM', stop)
   return done

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/launcher-watch.ts

@@ -0,0 +1,45 @@
+// F488: on Windows a kill of the `bun run start` wrapper (TerminateProcess; no process groups) takes the `.bin/brust.exe` shim down with it
+// but not the server below: it keeps the port, the app dir and the inherited pipes. Probe on windows-latest (PR #428): wrapper -> shim ->
+// server, and after a plain wrapper kill the shim is gone while the server lives. The shim is the server's direct parent, so the server
+// watches `process.ppid`: when that dies it drains like Ctrl+C. Started at boot, synchronously: no process table, nothing awaited.
+// (A PowerShell table read awaited before `ready` cost seconds per start and broke 5 s static builds; the lead ruled it out.)
+// POSIX never watches (platform gate): a POSIX supervisor signals the server directly.
+
+/** `process.kill(pid, 0)` throws ESRCH when the process is gone; EPERM means it exists. */
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+export interface LauncherWatchOptions {
+  /** Runs once, when the parent is gone. */
+  onGone: (pid: number) => void
+  platform?: NodeJS.Platform
+  ppid?: number
+  alive?: (pid: number) => boolean
+  intervalMs?: number
+  log?: (line: string) => void
+}
+
+/** Windows only. Returns the watched pid (undefined: nothing watched) and a `stop`. The timer is unref'd: it never holds the process open. */
+export function watchLauncher(opts: LauncherWatchOptions): { pid: number | undefined; stop: () => void } {
+  const none = { pid: undefined, stop: () => {} }
+  if ((opts.platform ?? process.platform) !== 'win32') return none
+  const ppid = opts.ppid ?? process.ppid
+  const alive = opts.alive ?? pidAlive
+  if (!ppid || !alive(ppid)) {
+    ;(opts.log ?? console.error)(`[brust] launcher (pid ${ppid}) is already gone at boot: not watching it`)
+    return none
+  }
+  const timer = setInterval(() => {
+    if (alive(ppid)) return
+    clearInterval(timer)
+    opts.onGone(ppid)
+  }, opts.intervalMs ?? 1000)
+  timer.unref()
+  return { pid: ppid, stop: () => clearInterval(timer) }
+}

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

@@ -11,6 +11,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { type BrustConfig, type ConfigOverrides, loadConfig } from './config'
+import { watchLauncher } from './launcher-watch'
 import { beginDrain, localAddr, type StartOptions, type StreamOptions, startServer, untilReady } from './native'
 import { DEFAULT_MAX_LOADER_RESPONSE_BYTES } from './worker'
 
@@ -34,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
 }
@@ -80,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[] = []
 
@@ -110,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
@@ -191,9 +207,20 @@ export async function run(opts: RunOptions = {}): Promise<void> {
   }
   process.on('uncaughtException', onFatal('uncaught exception'))
   process.on('unhandledRejection', onFatal('unhandled rejection'))
+  // F485 P12: on Windows Ctrl+C (SIGINT) drains; SIGTERM handlers rarely fire and a kill ends the process without a drain (POSIX-only).
   process.on('SIGINT', () => onSignal(130))
   process.on('SIGTERM', () => onSignal(143))
 
+  // F488 (Windows only): a killed `bun run start` wrapper takes the shim (our parent) down but leaves this process running; drain when the
+  // parent is gone (same path as Ctrl+C). Synchronous, nothing awaited. Not for a one-shot (`opts.onReady`: a static render that exits itself).
+  if (!opts.onReady)
+    watchLauncher({
+      onGone: (pid) => {
+        if (exiting) return
+        console.error(`[brust] launcher (pid ${pid}) exited: shutting down`)
+        onSignal(130)
+      },
+    })
   try {
     await untilReady(cfg.bootTimeoutMs)
   } catch (e) {