@bakery-framework/core 2.0.0-alpha.1 → 2.0.0-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/core",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0-alpha.11",
   "description": "Bakery framework core: handlers, router, config, session, caches, logger, compiler.",
   "keywords": [
     "bakery",
@@ -68,6 +68,6 @@
     "!src/tests"
   ],
   "engines": {
-    "bun": ">=1.3.14"
+    "bun": ">=1.4.0"
   }
 }

package/src/compiler/tsconfig-sync.ts

@@ -61,6 +61,13 @@ const PROJECT_DIR = fs.resolve(APP_DIR, '.cache/tsconfig')
  * Before this existed, one config covered everything and `Bun.hash()` in a
  * client file typechecked clean and failed in the browser.
  *
+ * The includes overlap the app's own tsconfig, and that is fine *because
+ * nothing references these projects*: each is a standalone projection of one
+ * concern, pointed at directly (`tsc -p .cache/tsconfig/client.json`), and
+ * subtracting the app's include would gut them into projects that check
+ * nothing. What must never come back is the `references` wiring that composed
+ * them with the app project — see {@link syncTSConfigProjects}.
+ *
  * Globs are app-relative here and rewritten to be relative to the generated
  * file, which sits two levels down.
  */
@@ -322,22 +329,81 @@ function mapPaths(paths: MapOf<string[]>): MapOf<string[]> {
 }
 
 /**
- * The app's root tsconfig with `references` set, and nothing else touched.
+ * A `references` entry the generator wrote in a previous release, as opposed
+ * to one the developer owns. Ours always pointed into `.cache/tsconfig/`, and
+ * nothing else has a reason to: `.cache/` is the disposable runtime directory,
+ * and every project inside it is regenerated on boot.
+ */
+const RE_GENERATED_REF = /^(\.[\\/])?\.cache[\\/]tsconfig[\\/]/
+
+function isGeneratedReference(entry: unknown): boolean {
+  if (typeof entry !== 'object' || entry === null) return false
+  const path = (entry as { path?: unknown }).path
+  return typeof path === 'string' && RE_GENERATED_REF.test(path)
+}
+
+/**
+ * The root config with the generator's own `references` removed, or `null`
+ * when there is nothing to repair.
+ *
+ * Until 2026-08-27 `syncTSConfigProjects` *added* those references, wiring the
+ * generated projects into the app's project graph. That glue is what broke
+ * `tsc -p <app>` for every consumer who had booted once. Measured directly
+ * (TypeScript 6.0.3):
+ *
+ * - `tsc -p` verifies every referenced project whenever the referencing
+ *   program has input files of its own: a reference to a non-composite
+ *   project is TS6306 and to a `noEmit` one TS6310 — **even when the
+ *   referenced project's include is disjoint from the root's, and even when
+ *   it matches zero files**. No include shape survives.
+ * - Each root file a referenced project also claims is redirected to that
+ *   project's declaration output, which `noEmit` guarantees was never built:
+ *   TS6305, once per overlapping file — `src/**`, `server.config.ts`, every
+ *   `.tsx` page.
+ *
+ * The generated projects extend `noEmit` bases and rely on
+ * `allowImportingTsExtensions`, so they are unbuildable by design. Making them
+ * `composite` instead would trade the errors above for a `tsc -b` build-order
+ * requirement no consumer runs — and TS6305 would still fire for any root file
+ * importing into one while unbuilt. The only reference shape `tsc -p`
+ * tolerates from a root that has files of its own is no reference at all, so
+ * the projects stand alone now and this strips what previous releases wrote.
+ *
+ * Everything the developer owns is preserved: only entries into
+ * `.cache/tsconfig/` are removed, a real project reference (say `../shared`)
+ * stays, and the `references` key itself survives unless the generator wrote
+ * every entry in it.
+ *
+ * Pure, and exported, so the repair can be tested without a function that
+ * writes to `process.cwd()`. The property that matters is negative — *no key
+ * the developer wrote is lost* — which a shape assertion on the source cannot
+ * check.
+ */
+export function stripGeneratedReferences(
+  current: Record<string, unknown>,
+): Record<string, unknown> | null {
+  const refs = current.references
+  if (!Array.isArray(refs)) return null
+
+  const kept = refs.filter(entry => !isGeneratedReference(entry))
+  if (kept.length === refs.length) return null
+
+  const repaired = { ...current }
+  if (kept.length) repaired.references = kept
+  else delete repaired.references
+  return repaired
+}
+
+/**
+ * The root config written when the app has none at all.
  *
- * Pure, and exported, so the merge can be tested without a function that writes
- * to `process.cwd()`. The property that matters is negative — *no key the
- * developer wrote is lost* — which is the kind of thing a shape assertion on the
- * source cannot check.
+ * The generated projects do not help Bun's runtime — it reads
+ * `compilerOptions.jsx*` from the root `tsconfig.json` and follows `extends`
+ * only into a relative path, never a package specifier — so the file this
+ * writes has to carry the JSX options itself, inline, exactly as the
+ * scaffolder spells them.
  */
-export function mergeRootConfig(
-  current: Record<string, unknown> | null,
-  references: { path: string }[],
-): Record<string, unknown> {
-  // Spread first so `references` is the only key this owns.
-  if (current) return { ...current, references }
-
-  // No root config at all. The generated projects do not help Bun's runtime, so
-  // the one this writes has to carry the JSX options itself.
+export function defaultRootConfig(): Record<string, unknown> {
   return {
     extends: '@bakery-framework/core/tsconfig.server.json',
     compilerOptions: {
@@ -345,58 +411,63 @@ export function mergeRootConfig(
       jsxFactory: 'createElement',
       jsxFragmentFactory: 'Fragment',
     },
-    references,
   }
 }
 
 /**
- * Generate the project configs and add `references` to the app's root tsconfig.
+ * Generate the project configs, and keep the app's root tsconfig viable —
+ * created with the runtime JSX options when the app has none, and stripped of
+ * the `references` a previous release wrote into it.
  *
  * Separate from `syncTSConfigPaths` because an app can reasonably want one and
  * not the other: the paths sync has existed for a long time and rewrites a file
  * people keep in git, while this owns a directory nobody edits.
  *
- * **It used to replace the root config with a references-only stub, and that
- * silently broke every `.tsx` page in the app.** The reasoning was tidy — the
- * generated projects carry the JSX options, so the root does not need them — and
- * it was wrong about *who reads the root*. `tsc` follows `references`; **Bun's
- * runtime does not.** Bun reads `compilerOptions.jsx*` from the root
- * `tsconfig.json` and nothing else, so a references-only root means pages get
- * transpiled against the automatic JSX runtime instead of Bakery's
- * `createElement`.
- *
- * The symptom is worse than the 500 that mistake usually produces. Measured on a
- * scratch app: `GET /` answered **200** with
- * `{"type":"html","props":{…},"_owner":null,"_store":{}}` — a React element tree,
- * JSON-encoded, because the handler received an object where it expects a
- * `SafeHtml` string. Nothing logs, nothing throws, the status is fine.
+ * **The generated projects are standalone on purpose; the root config does not
+ * reference them.** They exist for direct invocation against the one concern
+ * each covers: `vue-tsc -p .cache/tsconfig/vue.json` is the only way an SFC
+ * typechecks at all, `tsc -p .cache/tsconfig/client.json` proves browser code
+ * clean of `Bun.*`, and a plugin's project carries its own ambients the same
+ * way. Their `include` deliberately overlaps the app's own project — they are
+ * alternate projections of the same files, used *instead of* the root for
+ * their slice, never composed with it. Wiring them in as `references` broke
+ * `tsc -p <app>` for any consumer who had booted once (TS6305/6306/6310 — the
+ * measurements are on {@link stripGeneratedReferences}), and what the wiring
+ * bought was less than it looked: tsserver routes a file to the project whose
+ * `include` claims it, so for everything a scaffolded root claims — `src/**`,
+ * `server.config.ts`, `orm/**` — the reference walk never ran anyway.
  *
- * So the root is now *merged*, not replaced: every key the developer wrote stays,
- * and only `references` is ours. That also settles the contradiction with the
- * scaffolder, which writes those JSX options under a comment saying to keep them
- * — and with the three documentation pages that repeat it.
+ * Two earlier lessons still bind the root-config half. It used to be
+ * *replaced* with a references-only stub, which silently broke every `.tsx`
+ * page: Bun's runtime reads `compilerOptions.jsx*` from the root and does not
+ * follow `references`, so pages transpiled against the automatic JSX runtime
+ * and `GET /` answered 200 with a JSON-encoded React element tree. Hence
+ * {@link defaultRootConfig} when no root exists, and surgical repair — never
+ * wholesale rewrite — when one does. And a boot that dirties git every time
+ * trains people to ignore the diff, so an already-clean root is not rewritten.
  */
 export async function syncTSConfigProjects(): Promise<void> {
   try {
     const written = await writeProjects(buildPaths())
 
-    const references = written.map(name => ({
-      path: `./.cache/tsconfig/${name}.json`,
-    }))
-
     const current = fs.exists(APP_CONFIG_PATH)
       ? parseJSONC(await Bun.file(APP_CONFIG_PATH).text())
       : null
 
-    // Only rewrite when the reference set actually changed. The root config is
-    // committed, and a dev boot that dirties git every time trains people to
-    // ignore the diff.
-    if (current && Bun.deepEquals(current.references, references)) return
+    if (!current) {
+      await Bun.write(
+        APP_CONFIG_PATH,
+        `${JSON.stringify(defaultRootConfig(), null, 2)}\n`,
+      )
+      serveLog.TSCONFIG_PROJECTS_WRITTEN({ count: String(written.length) })
+      return
+    }
 
-    const root = mergeRootConfig(current, references)
+    const repaired = stripGeneratedReferences(current)
+    if (!repaired) return
 
-    await Bun.write(APP_CONFIG_PATH, `${JSON.stringify(root, null, 2)}\n`)
-    serveLog.TSCONFIG_PROJECTS_WRITTEN({ count: String(written.length) })
+    await Bun.write(APP_CONFIG_PATH, `${JSON.stringify(repaired, null, 2)}\n`)
+    serveLog.TSCONFIG_REFERENCES_REMOVED()
   } catch (err: any) {
     serveLog.UNHANDLED_ERR({
       error: `TSConfig project sync error: ${errorMsg(err)}`,

package/src/core/index.ts

@@ -4,6 +4,10 @@ import { Case, is, Math2, match, Try } from '../utils/common'
 import { encodeSSE, response, sse } from '../utils/http'
 import Bakery, { getHostname, hostKey, hostStore } from './bakery'
 import { getConfig, NOOP } from './config'
+// `./context` is already in this barrel's graph — line 5 reaches it through
+// `./bakery`, which re-exports `hostStore` from exactly here — so naming it
+// adds no module edge, only a name.
+import { getFrameworkVersion } from './context'
 import { createElement, Fragment, html } from './jsx'
 
 export const defineConfig = <T extends AppConfig>(config: T): T => config
@@ -63,6 +67,19 @@ export {
   encodeSSE,
   Fragment,
   getConfig,
+  /**
+   * The version of `@bakery-framework/core` itself, read from its own manifest.
+   *
+   * **Not the app's version**, which is what `import.meta.env.BAKERY_VERSION`
+   * and `getAppVersion()` report — the compiler reads those from
+   * `<cwd>/package.json`, so in an application they answer with the
+   * application's number. The name is a long-standing misnomer and this is the
+   * one that means what "Bakery version" sounds like it means.
+   *
+   * Exported because a plugin rendering framework chrome has no other way to
+   * ask. The dashboard's footer showed a hardcoded `v3` for want of it.
+   */
+  getFrameworkVersion,
   // Multi-host helpers. Documented in docs/configuration/multi-host.md, and
   // the only reason `./core/bakery` had to be a subpath of its own.
   getHostname,

package/src/core/init.ts

@@ -27,40 +27,43 @@ const getArgValue = (name: string) => {
 const threadId = process.env.THREAD_ID ?? getArgValue('--thread-id') ?? '0'
 
 /**
- * An accessor pair, not a bare getter.
+ * The mode flags are **strings on `process.env`** — `'1'` for true, `''` for
+ * false. They were booleans behind an accessor pair until Bun 1.4.
  *
- * These are `process.env` properties, and a getter with no setter is readonly:
- * in strict-mode ESM an assignment to one throws
- * `TypeError: Attempted to assign to readonly property`. `threads.ts` assigns
- * `THREAD_ID = '0'` on the single-worker/clamped path (deliberately not
- * `THREAD_WORKER` — a cluster of one must keep full-size caches). When the
- * assignment was getter-only it was wrapped in `Try(...)`, so the throw was
- * swallowed and the flags never moved — `reusePort`, the per-worker cache
- * scaling and the startup banner all silently read the master's values. The
- * `Try(...)` was what made a dead code path look deliberate.
+ * **Bun 1.4.0 rejects accessor descriptors on `process.env` outright.**
+ * `Object.defineProperty(process.env, 'X', { get })` throws
+ * `ERR_INVALID_OBJECT_DEFINE_PROPERTY`. This block runs at import time in every
+ * entry, so the whole framework died on `import` under current Bun — a
+ * scaffolded app could not reach step 2 of its own quick start. Data
+ * descriptors are accepted and coerce anyway (`{ value: false }` reads back as
+ * `"false"`), so a boolean here is no longer expressible at all; and
+ * `import.meta.env === process.env` in Bun, so there is no second object to put
+ * one on.
+ *
+ * **`'1'` / `''`, never `'true'` / `'false'`.** Truthiness has to survive the
+ * coercion: `"false"` is a truthy string, so every `if (import.meta.env.DEV)`
+ * in the codebase would have inverted silently rather than failed. `''` also
+ * keeps the key *present* — `'PROD' in process.env` stays true — which is what
+ * separates "explicitly not production" from "never booted", a distinction
+ * `utils/http/authorize.ts` depends on to fail closed.
+ *
+ * Plain assignment, so `threads.ts` can still assign `THREAD_ID = '0'` on the
+ * single-worker/clamped path (deliberately not `THREAD_WORKER` — a cluster of
+ * one must keep full-size caches). That assignment is why these were an
+ * accessor *pair* rather than a bare getter: a getter with no setter is
+ * readonly, the assignment threw, and the throw was swallowed by a `Try(...)`
+ * that made a dead code path look deliberate.
  */
-const accessor = (initial: any) => {
-  let value = initial
-  return {
-    get: () => value,
-    set: (next: any) => {
-      value = next
-    },
-    enumerable: true,
-    configurable: true,
-  }
-}
+const flag = (on: boolean) => (on ? '1' : '')
 
-Object.defineProperties(process.env, {
-  DEV: accessor(isDev),
-  TEST: accessor(isTest),
-  PROD: accessor(!isDev && !hasDevWorkerArg),
-  WORKER: accessor(hasDevWorkerArg || isThreadWorker),
-  DEV_WORKER: accessor(hasDevWorkerArg),
-  THREAD_WORKER: accessor(isThreadWorker),
-  THREAD_ID: accessor(threadId),
-  MODE: accessor(mode),
-})
+process.env.DEV = flag(isDev)
+process.env.TEST = flag(isTest)
+process.env.PROD = flag(!isDev && !hasDevWorkerArg)
+process.env.WORKER = flag(hasDevWorkerArg || isThreadWorker)
+process.env.DEV_WORKER = flag(hasDevWorkerArg)
+process.env.THREAD_WORKER = flag(isThreadWorker)
+process.env.THREAD_ID = threadId
+process.env.MODE = mode
 
 /**
  * "This process is the worker of a *development* server."

package/src/global.d.ts

@@ -342,13 +342,31 @@ declare global {
   // `ImportMeta.env` with its own incompatible shape, which is TS2687/TS2717 —
   // suppressed, like everything else in a .d.ts, by skipLibCheck.
   interface ImportMetaEnv {
-    readonly DEV: boolean
-    readonly PROD: boolean
-    readonly WORKER: boolean
-    readonly DEV_WORKER: boolean
-    readonly THREAD_WORKER: boolean
+    // `'1'` or `''`, not `true` or `false`. These live on `process.env`, and
+    // Bun 1.4 stopped accepting accessor descriptors there — a boolean is no
+    // longer expressible on that object at all, since data descriptors coerce
+    // too. See the encoding block in `core/init.ts`.
+    //
+    // Typed as the literal pair rather than `string` on purpose: it makes
+    // `import.meta.env.PROD !== false` a *compile* error. That comparison was
+    // real, in the dashboard's fail-closed gate, and under the string encoding
+    // it is true for every value including the `''` a development server sets —
+    // so the gate would have denied on loopback in development while still
+    // reading as correct. A type that only said `string` would not have caught
+    // it either.
+    //
+    // In a **browser** bundle these are real booleans: `compiler.ts` substitutes
+    // `JSON.stringify(!!import.meta.env.DEV)` at build time, so the literal
+    // `true`/`false` is inlined and this declaration is a slight lie there. It
+    // is the harmless direction — both encodings agree on truthiness, which is
+    // all client code tests — and the server is where the mistakes happen.
+    readonly DEV: '1' | ''
+    readonly PROD: '1' | ''
+    readonly WORKER: '1' | ''
+    readonly DEV_WORKER: '1' | ''
+    readonly THREAD_WORKER: '1' | ''
     readonly THREAD_ID: string
-    readonly TEST: boolean
+    readonly TEST: '1' | ''
     readonly MODE: 'production' | 'development' | 'dev-worker' | 'thread-worker'
     // `readonly SERVE_ROOT: string` was declared here. Nothing defines it —
     // not init.ts, not the compiler's `defines` — and nothing reads it, so any

package/src/handlers/assets/static.ts

@@ -2,7 +2,7 @@ import { Bakery, hostKey } from '../../core/bakery'
 import { matchBlockedCached } from '../../core/context'
 import { toHash } from '../../utils'
 import { fs } from '../../utils/fs'
-import { response } from '../../utils/http'
+import { injectBrand, response } from '../../utils/http'
 import { Handler } from '../core/$base'
 import { ErrorHandler } from '../core/$error'
 import { getStatic } from '../core/$static'
@@ -57,30 +57,73 @@ export class DefaultErrorHandler extends ErrorHandler {
    * error surface — `errorBody` carries the thrown error's stack (that is
    * what the log wants), and handing it to the client verbatim gave any
    * anonymous request source paths and query text in PROD.
+   *
+   * Two pages, split on the same gate `publicBody` uses, failing the same
+   * direction: only an explicit DEV gets the diagnostics page, so an
+   * indeterminate mode discloses nothing. DEV keeps the branded title, the
+   * body in a `<pre>`, and the requester/date footer — and `processResponse`
+   * injects the import map and live reload into it like any page, which is
+   * what makes the overlay work on an error. The production page is the
+   * status line and the public body, nothing else: the footer echoed the
+   * requester's own IP and a server timestamp to anyone who triggered an
+   * error, and the page is branded with `injectBrand` because the injected
+   * import map names every installed package — see the note on the export.
    */
   static handle(_path: string, req: Request, error?: Handler.Error.Data) {
-    const ip = Bakery.server?.requestIP(req)?.address || 'Unknown'
-    const date = new Date().toDateString()
-
     error ||= this.DEFAULT_ERROR
 
+    // No separator without text to separate — an empty-message denial used to
+    // render `<h1>403 - </h1>`. Same rule for the body below: empty renders
+    // as no element, not as a dangling `<pre></pre>`.
+    const heading = Bun.escapeHTML(
+      error.errorText
+        ? `${error.errorCode} - ${error.errorText}`
+        : `${error.errorCode}`,
+    )
+    const body = this.publicBody(error)
+
+    if (import.meta.env.DEV) {
+      const ip = Bakery.server?.requestIP(req)?.address || 'Unknown'
+      const date = new Date().toDateString()
+
+      const errorPage = `
+        <!DOCTYPE html>
+        <html lang="en">
+          <head>
+            <meta charset="UTF-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+            <title>Error ${error.errorCode} | Bakery 🚀</title>
+          </head>
+          <body style="margin: 2rem; font-family: sans-serif;">
+            <h1>${heading}</h1>
+            ${body ? `<pre>${Bun.escapeHTML(body)}</pre>` : ''}
+            <hr />
+            <small>${Bun.escapeHTML(date)} - ${Bun.escapeHTML(ip)}</small>
+          </body>
+        </html>
+      `
+
+      return response.html(errorPage, error.errorCode)
+    }
+
+    // `<p>`, not `<pre>`: outside DEV the body is prose by construction —
+    // `publicBody` replaces a 5xx stack with the generic sentence, and a 4xx
+    // body is authored text.
     const errorPage = `
       <!DOCTYPE html>
       <html lang="en">
         <head>
           <meta charset="UTF-8" />
           <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-          <title>Error ${error.errorCode} | Bakery 🚀</title>
+          <title>Error ${error.errorCode}</title>
         </head>
         <body style="margin: 2rem; font-family: sans-serif;">
-          <h1>${Bun.escapeHTML(`${error.errorCode} - ${error.errorText}`)}</h1>
-          <pre>${Bun.escapeHTML(this.publicBody(error))}</pre>
-          <hr />
-          <small>${Bun.escapeHTML(date)} - ${Bun.escapeHTML(ip)}</small>
+          <h1>${heading}</h1>
+          ${body ? `<p>${Bun.escapeHTML(body)}</p>` : ''}
         </body>
       </html>
     `
 
-    return response.html(errorPage, error.errorCode)
+    return injectBrand(response.html(errorPage, error.errorCode))
   }
 }

package/src/handlers/core/$base.ts

@@ -253,6 +253,23 @@ export class Handler {
    */
   static servesFiles = true
 
+  /**
+   * The URL prefix this handler owns as a complete user-facing surface —
+   * `'/_dashboard'`, `'/_db'` — or `null` for the ordinary case of a handler
+   * that answers by extension or content rather than by prefix.
+   *
+   * This exists so one surface can ask whether another is mounted without
+   * probing it. The dashboard used to detect the explorer by calling every
+   * registered handler's `canHandle('/_db')` with a control path to exclude
+   * the priority-0 catch-all — it worked, and the `as any` it needed was the
+   * tell that the registry could not say what a handler serves. A declaration
+   * is that answer. It is deliberately *not* consulted by routing: `canHandle`
+   * stays the authority on requests, so a stale or missing namespace can
+   * misdescribe a handler to the dashboard nav but can never misroute a
+   * request.
+   */
+  static namespace: string | null = null
+
   protected constructor() {}
 
   static get cache(): HandlerCache<string, Route.Info> {

package/src/handlers/core/$error.ts

@@ -193,7 +193,16 @@ export class ErrorHandler extends Handler {
         ...this.DEFAULT_ERROR,
         errorCode: error.status,
         errorText: error.statusText,
-        errorBody: `${error.status}: "${error.statusText}"`,
+        // The reason-phrase is optional — `new Response(null, { status })`
+        // leaves it `''`, and the framework's own forbidden-path denial is
+        // exactly that shape — so the quoting is conditional: a synthesized
+        // `403: ""` rendered a literal quoted empty string on the error page.
+        // The bare status, not `''`, because this string is also the default
+        // `onError` log line (`403 at /path`); an empty body would log
+        // ` at /path`.
+        errorBody: error.statusText
+          ? `${error.status}: "${error.statusText}"`
+          : String(error.status),
       }
     }
 

package/src/handlers/core/$registry.ts

@@ -30,11 +30,16 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
     }
   }
 
-  set(handlerClass: any, priority: number = 10): this {
-    super.set(handlerClass, priority)
+  /** Drop the derived views. Every mutation has to call this, not just `set`. */
+  private invalidate(): void {
     this.cachedList = null
     this.cachedGates = null
     this.cachedOrder = null
+  }
+
+  set(handlerClass: any, priority: number = 10): this {
+    super.set(handlerClass, priority)
+    this.invalidate()
     return this
   }
 
@@ -42,6 +47,30 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
     return this.set(handlerClass, priority)
   }
 
+  /**
+   * `delete` and `clear` invalidate too, and neither used to.
+   *
+   * `list()` memoizes the sorted handler array and only `set` cleared it, so a
+   * removed handler stayed in the list — and therefore stayed *in the request
+   * pipeline* — until something happened to add one. Registration is
+   * add-only in a served process, which is why this never bit: it is reachable
+   * only by code that unregisters, and the first thing to do that was a test.
+   *
+   * A cache that survives the removal of its input is wrong regardless of who
+   * currently calls it, and "nothing removes handlers today" is a property of
+   * the callers rather than of this class.
+   */
+  override delete(handlerClass: any): boolean {
+    const removed = super.delete(handlerClass)
+    if (removed) this.invalidate()
+    return removed
+  }
+
+  override clear(): void {
+    super.clear()
+    this.invalidate()
+  }
+
   list(): T[] {
     if (this.cachedList) {
       return this.cachedList

package/src/handlers/core/$routing.ts

@@ -21,15 +21,37 @@ export type RouteScanOptions = {
 const catchAllGlob = (ext: string) => new Bun.Glob(`[[]...*${ext || '.*'}`)
 
 // The single-param route forms, in the order they are tried: `[name].ext`
-// first, then the escaped-literal `*.ext`. Built here rather than twice inside
+// first, then the literal-asterisk `*.ext`. Built here rather than twice inside
 // `routeGlobs` — the `dynamicOnly` branch and the combined branch returned
 // character-identical pairs, and the two must stay in step or a route form
 // resolves under one caller and not the other. A function, not a hoisted
 // constant: `ext` varies per handler, and `staticOnly` returns before it needs
 // them at all.
-const dynamicGlobs = (ext: string) => [
+//
+// **The literal asterisk is a character class, `[*]`, never the escape `\*`.**
+// A backslash is the obvious spelling and is unusable on Windows, where `\` is
+// a path separator: Bun read `\*.*` as a drive-absolute pattern, ignored the
+// `cwd` in `GETFILE` entirely, and matched files at `C:\`. A route lookup under
+// a serve root six levels down returned `C:\$WINRE_BACKUP_PARTITION.MARKER`,
+// and `fs.isForbidden` — whose walk is bounded by `startsWith(root)` — waved it
+// through because an out-of-root path skipped the loop and answered "allowed".
+// That clamp now fails closed, so this is belt and braces; both halves are
+// pinned, and neither test can see the other's bug.
+//
+// Measured with a scan whose cwd was a temp directory holding one file: `[*]`
+// yields nothing, `\*` yields four files from the drive root. The escape is
+// also unreachable on Windows in the direction it was meant for — `*` is a
+// reserved character in a Windows filename, so a route file literally named
+// `*.ts` can only exist on POSIX, where both spellings match it identically
+// (verified on Linux). The character class costs nothing and means the same
+// thing on both platforms.
+//
+// Exported only as a test seam: with the clamp in place no test driving
+// `getRoute` can tell the two spellings apart — verified by reverting this line
+// and watching all 17 pass — so the pattern has to be asserted directly.
+export const dynamicGlobs = (ext: string) => [
   new Bun.Glob(`[[][!.]*${ext || '.*'}`),
-  new Bun.Glob(`\\*${ext || '.*'}`),
+  new Bun.Glob(`[*]${ext || '.*'}`),
 ]
 
 const routeGlobs = (

package/src/handlers/routes/api.ts

@@ -2,6 +2,7 @@ import { Bakery } from '../../core/bakery'
 import { handlerLog } from '../../logger/serve-log'
 import { FileSystem } from '../../utils/fs'
 import { checkCsrf, response } from '../../utils/http'
+import { parsedUrl } from '../../utils/http/url'
 import type { Handler } from '../core/$base'
 import { bustInDev, DynamicHandler } from '../core/$dynamic'
 import { ErrorHandler } from '../core/$error'
@@ -29,8 +30,7 @@ export class ApiHandler extends DynamicHandler {
   static async handle(path: string, req: Request) {
     // State-changing methods must be same-origin. SameSite=Lax alone does not
     // cover this: a cross-site form POST is a CORS-simple request.
-    const url: URL = (req as any).__parsedUrl || new URL(req.url)
-    const csrf = checkCsrf(req, url)
+    const csrf = checkCsrf(req, parsedUrl(req))
     if (csrf) return response.json.error(403, csrf) as unknown as Response
 
     const info = await this.resolveRoute(path)

package/src/handlers/routes/proxy.ts

@@ -1,6 +1,7 @@
 import { Bakery } from '../../core/bakery'
 import { handlerLog } from '../../logger'
 import { response } from '../../utils/http'
+import { parsedUrl } from '../../utils/http/url'
 import { Handler } from '../core/$base'
 
 export class ProxyHandler extends Handler {
@@ -30,7 +31,7 @@ export class ProxyHandler extends Handler {
         baseTarget +
         (trailingPath.startsWith('/') ? '' : '/') +
         trailingPath +
-        ((req as any).__parsedUrl || new URL(req.url)).search
+        parsedUrl(req).search
       break
     }
 

package/src/logger/serve-log.ts

@@ -27,6 +27,12 @@ const serveMsgs = {
     'I Synced %ytsconfig.json%* paths with %yserver.config.ts%*!',
   TSCONFIG_PROJECTS_WRITTEN:
     'I Wrote %y{count}%* tsconfig project(s) to %y.cache/tsconfig/%*',
+  // One-time repair. Previous releases wired the generated projects into the
+  // app's tsconfig.json as `references`, which broke `tsc -p <app>`
+  // (TS6305/6306/6310). Named so the rewrite of a tracked file comes with a
+  // line saying why it happened.
+  TSCONFIG_REFERENCES_REMOVED:
+    'I Removed generated %yreferences%* from %ytsconfig.json%* — the %y.cache/tsconfig/%* projects are standalone, and referencing them broke %ytsc -p%*',
   // A plugin asking for a project name that is taken. Named rather than
   // silent: the symptom otherwise is one plugin's types quietly not applying,
   // discovered much later and blamed on the wrong thing.

package/src/plugins/types.ts

@@ -6,11 +6,13 @@ export type ValidResponses = Handler.Response
 /**
  * A TypeScript project a plugin contributes to the app.
  *
- * Written to `.cache/tsconfig/<name>.json` on every dev boot and referenced
- * from the app's root `tsconfig.json`, so the editor typechecks each file under
- * the project that owns it. Regenerated rather than committed: it is derived
- * from the plugin list and the app's config, and `.cache/` is the disposable
- * half of the two runtime directories.
+ * Written to `.cache/tsconfig/<name>.json` on every dev boot, as a standalone
+ * project invoked directly (`vue-tsc -p .cache/tsconfig/vue.json`). It is
+ * deliberately *not* referenced from the app's root `tsconfig.json` — a
+ * `references` entry to an unbuilt `noEmit` project makes `tsc -p <app>` fail
+ * (TS6305/6306/6310; see `compiler/tsconfig-sync.ts`). Regenerated rather
+ * than committed: it is derived from the plugin list and the app's config, and
+ * `.cache/` is the disposable half of the two runtime directories.
  */
 export interface PluginTsProject {
   /** File name under `.cache/tsconfig/`, and the project's identity. */

package/src/router.ts

@@ -19,6 +19,7 @@ import {
   withStatus,
 } from './utils/http'
 import { applyCors, preflightResponse } from './utils/http/cors'
+import { parsedUrl } from './utils/http/url'
 
 /**
  * Resolve a WebSocket upgrade, refusing cross-origin handshakes first.
@@ -39,7 +40,7 @@ export async function upgradeWebsocket(
   req: Request,
   path: string,
 ): Promise<boolean | undefined> {
-  const url: URL = (req as any).__parsedUrl || new URL(req.url)
+  const url = parsedUrl(req)
   const denied = checkWebSocketOrigin(req, url)
   if (denied) {
     serveLog.WEBSOCKET_ERR({
@@ -85,10 +86,9 @@ export function handleRequest(
   req: Request,
 ): Handler.Response | MixedPromise<symbol>
 export async function handleRequest(req: Request) {
-  // worker.ts parses and attaches this before calling in; the fallback keeps
-  // direct callers (tests, embedders) working.
-  const url: URL = (req as any).__parsedUrl || new URL(req.url)
-  ;(req as any).__parsedUrl = url
+  // Shared with worker.ts, which has already asked for the same parse; a
+  // direct caller (test, embedder) gets it parsed here instead.
+  const url = parsedUrl(req)
   const path = url.pathname
 
   // One read of the config getter, not three: `Bakery.serveRoot` walks

package/src/utils/fs.ts

@@ -395,6 +395,35 @@ export namespace FileSystem {
     let curr = safeResolve(pathToCheck)
     const normalizedRoot = safeResolve(root)
 
+    // A path outside `root` is forbidden, and this is the clause that says so.
+    //
+    // The walk below is bounded by `curr.startsWith(normalizedRoot)`, so an
+    // out-of-root path skipped the loop body entirely and fell through to
+    // `return false` — "not forbidden". That is a guard failing *open* on the
+    // one input it most needs to refuse, and it made every caller that relied
+    // on this for containment (all of them: `constants.ts` said so in as many
+    // words) incapable of catching an escape.
+    //
+    // Not theoretical. `$routing.ts` builds its route globs with `\*` to mean a
+    // literal asterisk; on Windows a backslash is a path *separator*, so Bun
+    // read the pattern as drive-absolute, ignored `cwd`, and matched files at
+    // `C:\`. `getRoute` resolved one, asked this function, was told "allowed",
+    // and returned an `Info` pointing six levels above the serve root. The glob
+    // is fixed too, but the glob was only how it was reached — a resolved file
+    // outside the root has to be refused here whatever produced it.
+    //
+    // The separator suffix matters: a bare `startsWith` would also accept a
+    // sibling directory whose name merely begins with the root's. A root that
+    // is already a filesystem root ends in `/` and must not gain a second one —
+    // `C://` matches nothing, which would make every path under `C:/` read as
+    // an escape. `fs.test.ts` drives both through its root corpus.
+    const rootPrefix = normalizedRoot.endsWith('/')
+      ? normalizedRoot
+      : `${normalizedRoot}/`
+    if (curr !== normalizedRoot && !curr.startsWith(rootPrefix)) {
+      return true
+    }
+
     const store = hostStore.getStore()
     const seen = store ? (store.forbiddenProbes ??= new Map()) : null
 

package/src/utils/http/authorize.ts

@@ -0,0 +1,136 @@
+/**
+ * The request-predicate half of plugin authorization.
+ *
+ * One implementation, deliberately in core, for the same reason
+ * `credential.ts` is here: the dashboard, db-explorer and analytics plugins
+ * each need this guard, and per-plugin copies of security code drift. These
+ * three had already drifted — one coerced its predicate's return with
+ * `Boolean`, one gated on `!DEV` where the others read `PROD`, one swallowed a
+ * `getClientIp` throw into an empty string and carried on. Each divergence is
+ * resolved below toward the fail-closed reading, and each is marked as a
+ * decision rather than left to look like a style choice.
+ *
+ * It owns *only* the predicate — no logins, no sessions, no backoff. The shared
+ * key path is `credential.ts`; a plugin that offers both doors composes them.
+ *
+ * `getClientIp` is imported from `./ip` directly, never through this
+ * directory's barrel or `@bakery-framework/core`: a core module that reaches for a
+ * barrel closes an import cycle, which is how 67 tests once failed with
+ * `ReferenceError: Cannot access 'Logger' before initialization`.
+ */
+
+import { getClientIp } from './ip'
+
+/**
+ * A host application's access predicate. Returning `true` admits; returning
+ * anything else, or throwing, denies (convention 2).
+ *
+ * The framework authenticates nobody. The application, which already knows who
+ * its users are, supplies this.
+ */
+export type AuthorizeFn = (req: Request) => boolean | Promise<boolean>
+
+/**
+ * Addresses only, never hostnames. Module-private: neither plugin copy
+ * exported it, and the membership test is the whole of the useful surface.
+ *
+ * `'localhost'` used to be a member, back when the request's *hostname* was
+ * compared against this set as well. A peer address is never the string
+ * `localhost`, and accepting it meant `X-Forwarded-For: localhost` counted as
+ * loopback under `trustProxy` — and, worse, that `new URL(req.url).hostname`
+ * did too. Bun builds that from the client's own `Host` header and
+ * `DEFAULT_HOST` is 0.0.0.0, so any peer on the LAN could send
+ * `Host: localhost` and be handed a database browser.
+ */
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1'])
+
+/** True when the request came from this machine. */
+export function isLoopback(req: Request): boolean {
+  // The peer address is the only evidence here the client does not choose.
+  //
+  // DECISION (divergence 3): a throw returns `false` immediately rather than
+  // falling through with `ip = ''`. `getClientIp` reads config and the live
+  // server, either of which may be absent (tests, early boot). The two spell
+  // the same answer today, because `LOOPBACK.has('')` is false — but only by
+  // coincidence, and the fall-through invites a later edit that adds a second
+  // source of evidence below this line and silently consults it on the
+  // indeterminate path. Returning here says the answer is settled: no address
+  // means no evidence, and per convention 2 an indeterminate answer is a
+  // denial, not a reason to ask something the requester controls.
+  try {
+    return LOOPBACK.has(getClientIp(req))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The default when an application configures no predicate: loopback in
+ * development, nobody in production. Forgetting to configure a plugin
+ * therefore cannot expose it to the internet.
+ */
+export function defaultAuthorize(req: Request): boolean {
+  // DECISION (divergence 2): gate on `PROD`, not `!DEV`, and read it at call
+  // time — the mode flags are accessors on `process.env` (`core/init.ts`), so
+  // they are process state and tests flip them.
+  //
+  // The two spellings look interchangeable because `init.ts` derives them as
+  // complements (`PROD = !isDev && !--dev-worker`). They are not, because they
+  // are *independently settable* accessors and the test fixtures set them one
+  // at a time: `asDev` flips `DEV` alone and leaves the ambient `PROD` — which
+  // under `bun test` is `true` — in place. In that state `!DEV` admits a
+  // loopback caller and `PROD` denies, so `PROD` is both the fail-closed
+  // reading and the one that literally names the condition it means, rather
+  // than inferring production from the absence of development.
+  //
+  // Hence a test for the *positive* development marker rather than a truthiness
+  // test on `PROD`, which is the one place a bare `PROD` gate would be weaker
+  // than `!DEV`. The flags do not exist until `core/init.ts` has run, and
+  // `if (undefined)` falls straight through to the loopback check — so an
+  // uninitialised process would open the door an initialised production one
+  // keeps shut. Unset is not evidence of development; it is no evidence at all.
+  //
+  // This read `PROD !== false` while the flags were real booleans. Bun 1.4
+  // rejects accessor descriptors on `process.env`, so they are `'1'`/`''`
+  // strings now (see `core/init.ts`) — and `!== false` is true for *every*
+  // string, including the `''` a development server sets, so the gate would
+  // have denied on loopback in development while still looking correct.
+  // `DEV === '1'` is the same statement in the encoding that survives: only a
+  // booted development server sets it, and production (`''`) and never-booted
+  // (`undefined`) both fail it.
+  //
+  // `isLoopback` would very likely deny on its own there, having no config or
+  // server to read an address from. That is a second line of defence, not this
+  // one's excuse: a guard should not depend on another guard's failure mode.
+  if (import.meta.env.DEV !== '1') return false
+  return isLoopback(req)
+}
+
+/** The configured predicate, or the fail-closed default. */
+export function resolveAuthorize(fn?: AuthorizeFn): AuthorizeFn {
+  return fn ?? defaultAuthorize
+}
+
+/**
+ * Run a predicate without letting a broken one grant access. Guard semantics
+ * per convention 2: the *authorizer* may throw or answer nonsense, and the
+ * answer to any indeterminate state is denial.
+ */
+export async function isAuthorized(
+  authorize: AuthorizeFn,
+  req: Request,
+): Promise<boolean> {
+  try {
+    // DECISION (divergence 1): `=== true`, never `Boolean(...)`. The predicate
+    // comes from application code and `AuthorizeFn`'s return type is only
+    // advice — an untyped, transpiled or `as any` predicate can hand back
+    // anything. `Boolean` admits every truthy non-boolean, so a check that
+    // answers with a status string denies on `""` and *grants* on `"no"`, and
+    // one that answers with a count grants on any non-zero. Admission is the
+    // expensive direction to get wrong; require the exact affirmative.
+    return (await authorize(req)) === true
+  } catch {
+    // A predicate that throws is indeterminate, and indeterminate is denied.
+    return false
+  }
+}

package/src/utils/http/body.ts

@@ -1,4 +1,5 @@
 import type { MapOf } from '../../types'
+import { parsedUrl } from './url'
 
 export async function processBody(req: Request): Promise<MapOf<any>> {
   const getParsedBody = async (): Promise<MapOf<any>> => {
@@ -18,8 +19,7 @@ export async function processBody(req: Request): Promise<MapOf<any>> {
 }
 
 function getBodyFromURI(req: Request): MapOf<any> {
-  const url = (req as any).__parsedUrl || new URL(req.url)
-  const searchParams = url.searchParams
+  const searchParams = parsedUrl(req).searchParams
   return Object.fromEntries(searchParams.entries())
 }
 

package/src/utils/http/etag.ts

@@ -231,6 +231,33 @@ export namespace ETag {
       if (conditionalRes) return conditionalRes
     }
 
+    // Range handling itself lives in Bun.serve, not here: any Response whose
+    // body is a *path-backed* BunFile is sliced by the runtime — 206 with
+    // Content-Range on a satisfiable single range, 416 past EOF — including
+    // the negotiated compressed variants above (the range then addresses the
+    // encoded bytes, which is what RFC 9110 says a range means). What the
+    // runtime does not do is advertise: a plain 200 or a HEAD said nothing,
+    // so players that probe HEAD for `Accept-Ranges` before attempting seeks
+    // never tried. Advertised here because this is the one funnel every
+    // file-serving handler's BunFile passes through, and only here — an
+    // in-memory Blob or a `sendText` string body ignores Range entirely
+    // (served whole, 200), which is why `.name` gates the claim.
+    //
+    // Skipped when Bun's own range path is about to answer (a GET carrying
+    // `Range`): that path appends its own `Accept-Ranges: bytes` to the
+    // 206/416, and setting it here too emitted `bytes, bytes`. The trade,
+    // measured on Bun 1.4.0: a GET whose Range is malformed or multipart is
+    // served whole with no advertisement from either side — acceptable,
+    // since a client that already sent `Range` is not the one this probe
+    // header exists for. HEAD ignores `Range` and gets the header even when
+    // one is present.
+    if (
+      resolvedFile.name &&
+      !(req && req.method === 'GET' && req.headers.has('range'))
+    ) {
+      headers['Accept-Ranges'] = 'bytes'
+    }
+
     return new Response(resolvedFile, { headers })
   }
 

package/src/utils/http/html.ts

@@ -4,7 +4,18 @@ import { Try } from '../common/try'
 import { DOMTools, headBodyCache } from './dom'
 import { ETag } from './etag'
 
-function injectBrand(res: Response) {
+/**
+ * Mark `res` as already carrying the head/body injects, so `injectIfHtml` —
+ * and therefore `processResponse`, which every response funnels through —
+ * hands it back untouched.
+ *
+ * Exported for the one caller that means "never", not "already":
+ * `DefaultErrorHandler` brands its production error page so the import map is
+ * not spliced into it. That map names every installed package — an inventory
+ * of the app's module layout — and the page carries no scripts for it (or the
+ * client bundle) to serve anyway.
+ */
+export function injectBrand(res: Response) {
   return Object.defineProperty(res, '__injected__', {
     value: true,
     enumerable: false,

package/src/utils/http/index.ts

@@ -1,3 +1,4 @@
+export * from './authorize'
 export * from './body'
 export * from './credential'
 export * from './csrf'
@@ -8,3 +9,4 @@ export * from './html'
 export * from './ip'
 export * from './response'
 export * from './sse'
+export * from './url'

package/src/utils/http/url.ts

@@ -0,0 +1,35 @@
+/**
+ * The request's parsed URL, parsed at most once.
+ *
+ * Why memoize at all: `new URL` measures ~1.7µs, and the router, the body
+ * parser and the proxy handler all want the same parse of the same request —
+ * so the parse was hoisted into the server's `fetch` in `packages/cli/src/worker.ts`
+ * and shared.
+ *
+ * Why a `WeakMap` rather than the property it replaces. The memo used to be
+ * `(req as any).__parsedUrl`: two writers, six readers across three packages,
+ * every reader spelled `(req as any).__parsedUrl || new URL(req.url)` so that
+ * it silently re-parsed whenever the writer had not run first. That is a
+ * writer/reader ordering hazard with no way to observe it going wrong — a
+ * missed write costs microseconds, not correctness, so nothing ever fails.
+ * One function collapses both roles: there is no ordering left to get wrong,
+ * no `any` cast anywhere, and no writer to forget. The map also keeps the
+ * framework from mutating a `Request` object it does not own — a caller's
+ * `Request` goes in and comes back unchanged — and holds its keys weakly, so
+ * an entry dies with the request rather than needing eviction (convention 6).
+ *
+ * There is deliberately no setter. Nothing outside this module needs to say
+ * what a request's URL is; `req.url` already does.
+ */
+
+const cache = new WeakMap<Request, URL>()
+
+/** The parsed `req.url`, cached per request. */
+export function parsedUrl(req: Request): URL {
+  const cached = cache.get(req)
+  if (cached) return cached
+
+  const url = new URL(req.url)
+  cache.set(req, url)
+  return url
+}