@bakery-framework/core 2.0.0-alpha.9 → 2.0.0-rc.1

package/src/handlers/assets/nm.ts

@@ -18,20 +18,20 @@ export class NMHandler extends Handler {
    *
    * **The literal path wins whenever it exists, and the order is the whole
    * point.** `Bun.build` resolves a directory or package entry itself, with
-   * *browser* conditions — which is what picks `vue`'s `esm-bundler` build over
+   * *browser* conditions, which is what picks `vue`'s `esm-bundler` build over
    * the CJS one behind its `node` condition. `Bun.resolveSync` has no such
    * knob: it answers with Bun's own server conditions. Resolving here first and
    * handing `Bun.build` the concrete file therefore silently downgraded every
-   * package with a `browser`/`node` split — `/_nm/vue` came back as
+   * package with a `browser`/`node` split: `/_nm/vue` came back as
    * `index.mjs` re-exporting `vue.cjs.js`, and the browser then rejected
    * `import { Fragment } from 'vue'`.
    *
    * So the literal path goes first whenever it is on disk, and `resolveSync` is
    * the second candidate rather than the first. It is still needed, for two
-   * distinct cases: a public subpath that does not match the physical layout —
+   * distinct cases: a public subpath that does not match the physical layout,
    * `@vue-material/core` maps `"./utils"` to `./dist/utils/index.js`, so the
    * documented `@vue-material/core/utils` has no `utils` directory to find and
-   * used to 500 — and a package whose root is declared *only* through
+   * used to 500, and a package whose root is declared *only* through
    * `exports`, where `Bun.build` on the directory answers `ModuleNotFound`
    * because it looks for `main`/`module` and finds neither.
    *
@@ -65,15 +65,15 @@ export class NMHandler extends Handler {
    * **Why this does not call `getStatic`.** `getStatic` is the single writer of
    * the containment + `.forbidden` pair, and three of the four handlers its doc
    * comment names now go through it. This one cannot, and the reason is not
-   * the root (it takes a `roots` argument) — it is that `getStatic` answers
+   * the root (it takes a `roots` argument): it is that `getStatic` answers
    * "is there a plain file literally at this path", and `/_nm/` deliberately
    * asks a different question: what would an importer of this specifier get?
    * `resolveEntry` answers it, applying the package's `exports` map, and
-   * `Bun.build` then does directory-index resolution on whatever survives — so
+   * `Bun.build` then does directory-index resolution on whatever survives, so
    * `/_nm/pkg/sub` reaches `pkg/sub/index.js`, which is precisely what the
    * import map's `"<pkg>/": "/_nm/<pkg>/"` prefix entry (`utils/http/dom.ts`)
    * produces for an extensionless subpath import. `getStatic` returns `null`
-   * for that path — it is a directory — so routing through it would turn every
+   * for that path (it is a directory), so routing through it would turn every
    * extensionless subpath import into a 204. `nm.test.ts` pins both halves of
    * that divergence.
    *

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'
@@ -22,7 +22,7 @@ export class StaticHandler extends Handler {
     // without the router gate. `matchBlockedCached` makes the overlap cost a
     // per-request map hit rather than a second pair of glob matches.
     // One read of the config getter: `blocked` and the serve root come from
-    // the same snapshot — getStatic's default `roots` would re-read it.
+    // the same snapshot. GetStatic's default `roots` would re-read it.
     const cfg = Bakery.config
     if (matchBlockedCached(cfg.blocked, path)) {
       return response.error('Forbidden', 403)
@@ -54,33 +54,76 @@ export class DefaultErrorHandler extends ErrorHandler {
   /**
    * This is the fallback for every path with no more specific error handler,
    * so it renders through the inherited `publicBody` like the rest of the
-   * error surface — `errorBody` carries the thrown error's stack (that is
+   * 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/assets/ts.ts

@@ -46,15 +46,15 @@ export class TSHandler extends DynamicHandler {
     //
     // The route is named because this branch was unreachable until
     // `compileText` stopped throwing past it, and a nameless "Compilation
-    // Failed" is only half an answer: the diagnostic — file, line, column,
-    // source line — goes to the log as `compLog.COMPILE_FAIL`, and the two
+    // Failed" is only half an answer: the diagnostic (file, line, column,
+    // source line) goes to the log as `compLog.COMPILE_FAIL`, and the two
     // have to be joinable. Naming it discloses nothing a client did not
     // already send: `info.path` is what it asked for. In production
     // `publicBody` replaces the whole 5xx body anyway.
     return cached || response.error(`Compilation Failed: ${info.path}`, 500)
   }
 
-  /** Compile seam — ts.test.ts substitutes it to exercise the failure branch. */
+  /** Compile seam, ts.test.ts substitutes it to exercise the failure branch. */
   static compileRoute(file: fs.AbsolutePath): Promise<string | null> {
     return compile(file)
   }

package/src/handlers/assets/tsx.ts

@@ -59,7 +59,7 @@ async function sharedHandler(
   const modulePath = fs.resolve(Bakery.serveRoot, filePath)
   const params = info.getParams(path) || {}
   markDevFile(params, filePath)
-  // Redacted before it becomes page data — see `publicErrorData`. The params
+  // Redacted before it becomes page data. See `publicErrorData`. The params
   // are both substituted into the render and injected as `__PAGE_PARAMS__`.
   // `errorData` is undefined for an ordinary page; Object.assign ignores that.
   const finalParams = Object.assign(

package/src/handlers/assets/virtual-asset.ts

@@ -46,7 +46,7 @@ export class VirtualAssetHandler extends Handler {
       async function bundleClient() {
         // Bundled, not merely transpiled: these are browser entry points, and
         // the browser cannot resolve the relative imports a transpile leaves
-        // behind — they resolve against the page URL, return the HTML
+        // behind, they resolve against the page URL, return the HTML
         // fallback, and fail strict MIME checking for module scripts.
         const built = await bundleModule(masterPath as fs.AbsolutePath)
         return built.success && built.content ? built.content : null

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

@@ -35,7 +35,7 @@ export function getDynamicRoute(path: string): Handler.Dynamic.Route | null {
     if (optionalMatch) {
       if (i !== last) return null
       params.push(optionalMatch[1])
-      // The whole segment — separator included — is optional, so the pattern
+      // The whole segment (separator included) is optional, so the pattern
       // is assembled below rather than pushed here: `docs/[...slug!]` has to
       // match `/docs` itself, which `/docs/(.*)` cannot.
       catchAll = true
@@ -46,14 +46,14 @@ export function getDynamicRoute(path: string): Handler.Dynamic.Route | null {
     const catchAllMatch = segment.match(RX_CATCHALL)
     if (catchAllMatch) {
       // Only terminal: a segment after `[...x]` has no unambiguous meaning
-      // (which segments belong to the rest?), so the file stays inert — the
+      // (which segments belong to the rest?), so the file stays inert, the
       // same behavior it had before catch-alls existed.
       if (i !== last) return null
       params.push(catchAllMatch[1])
       // `.+` rather than `.*`: the catch-all requires at least one segment,
       // so `docs/[...slug]` does not shadow a `docs/index` sibling for
       // `/docs` itself. `[...slug!]` is the spelling that opts into the
-      // bare directory — and an index sibling still wins there, because
+      // bare directory, and an index sibling still wins there, because
       // static discovery runs before dynamic in `resolveRouteFile`.
       mappedPaths.push('(.+)')
       catchAll = true
@@ -115,7 +115,7 @@ export namespace Route {
 // namespace for its nested classes; `const RouteData = { Info: class {} }`
 // provides only the value, and every one of those type references stops
 // resolving.
-// biome-ignore lint/complexity/noStaticOnlyClass: also a type namespace — see above
+// biome-ignore lint/complexity/noStaticOnlyClass: also a type namespace. See above
 export class RouteData {
   static Info = class Info {
     readonly params: string[]
@@ -157,7 +157,7 @@ export class RouteData {
       const boundParams: MapOf<string | string[]> = {}
       for (let i = 0; i < this.params.length; i++) {
         const value = match[i + 1]
-        // The catch-all is always terminal, so it is always the last param —
+        // The catch-all is always terminal, so it is always the last param,
         // and it binds as the *segments*, not the joined string: every
         // consumer was calling `.split('/')` on it anyway, and the joined
         // form silently conflated `/docs/a%2Fb` with `/docs/a/b`. A bare
@@ -214,7 +214,7 @@ export namespace Handler {
  * Keyed by class identity rather than stored as a `${name}_cache` dynamic
  * property: the getter runs several times per request, and the template
  * string + megamorphic property lookup showed up in profiles. A `Map` (not
- * `WeakMap`) is fine — handler classes live for the process.
+ * `WeakMap`) is fine: handler classes live for the process.
  */
 const handlerCaches = new Map<any, HandlerCache<string, Route.Info>>()
 
@@ -246,13 +246,29 @@ export class Handler {
    * source file by being handed a path that looks like one, and applying the
    * deny-list to them made `/api/manifest.json` a 403 no config could undo.
    *
-   * Deny by default: anything that does not opt out — including a plugin's
-   * handler — keeps the check. This is the single source of truth for that
+   * Deny by default: anything that does not opt out (including a plugin's
+   * handler) keeps the check. This is the single source of truth for that
    * question; `router.ts` gates its request-path check on it, and
    * `DynamicHandler.resolveRoute` gates the resolved-file check on it.
    */
   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/$dynamic.ts

@@ -22,7 +22,7 @@ const dynamicCaches = new Map<any, HandlerCache<RegExp, Route.Info>>()
  *
  * The suffix makes Bun's module registry treat every edit as a new module,
  * which is what lets an edited route (a `.ts` API handler, a `.tsx` page) take
- * the cheap dev path — route-cache flush plus browser reload — instead of the
+ * the cheap dev path (route-cache flush plus browser reload) instead of the
  * full process restart it used to force. It also costs a stat and a string
  * alloc per request and permanently retains each superseded module: acceptable
  * in DEV, pure waste in PROD where route files cannot change. So PROD imports
@@ -31,7 +31,7 @@ const dynamicCaches = new Map<any, HandlerCache<RegExp, Route.Info>>()
  * operationally since PROD runs no watcher.
  *
  * `&& !TEST` is load-bearing: `init.ts` defaults `PROD` to true whenever
- * `--dev` is absent, and `bun test` loads init via the CLI package's tests — so
+ * `--dev` is absent, and `bun test` loads init via the CLI package's tests, so
  * a bare `PROD` gate flipped mid-suite and broke the reload tests in files
  * loaded after it, while passing in isolation.
  *
@@ -40,8 +40,8 @@ const dynamicCaches = new Map<any, HandlerCache<RegExp, Route.Info>>()
  * `docs/getting-started/first-app.md`.
  *
  * One implementation on purpose. `ApiHandler` and `TSXHandler`/`TSXErrorHandler`
- * both need it, and they carried a byte-identical copy each — including this
- * reasoning — which is two places for the `!TEST` clause to be dropped from.
+ * both need it, and they carried a byte-identical copy each (including this
+ * reasoning), which is two places for the `!TEST` clause to be dropped from.
  */
 export function bustInDev(file: fs.AbsolutePath): fs.AbsolutePath {
   if (import.meta.env.PROD && !import.meta.env.TEST) return file
@@ -58,7 +58,7 @@ export class DynamicHandler extends Handler {
   }
 
   static get dynamicCache(): HandlerCache<RegExp, Route.Info> {
-    // Same per-class Map pattern as `Handler.cache` — see the comment there.
+    // Same per-class Map pattern as `Handler.cache`. See the comment there.
     let cache = dynamicCaches.get(this)
     if (!cache) {
       cache = new HandlerCache()
@@ -88,7 +88,7 @@ export class DynamicHandler extends Handler {
     if (this.cache.has(hostKey(path))) return true
     // The dynamic half of the line above. A dynamic route is never written to
     // `this.cache`, so without this every request to one ran `resolveRoute`
-    // twice — once here and once in `handle` — and each run is two globbing
+    // twice (once here and once in `handle`), and each run is two globbing
     // `getRoute` scans. `findDynamicRoute` is a regex test per cached route
     // plus one stat for the match, and a hit here implies `resolveRoute` is
     // about to be truthy too: it consults the same cache and returns that
@@ -107,7 +107,7 @@ export class DynamicHandler extends Handler {
     // A broken route module is a server fault, not a missing route: `null`
     // means 404 to every caller, so after logging the file for context the
     // failure is rethrown. `extractErrorData` turns the throw into a 500 whose
-    // `errorBody` carries the stack — shown in DEV, redacted by `publicBody`
+    // `errorBody` carries the stack: shown in DEV, redacted by `publicBody`
     // in PROD. Only the genuinely-missing cases below return null.
     const [error, mod] = await Try.catch(import(file))
     if (error) {
@@ -137,13 +137,13 @@ export class DynamicHandler extends Handler {
       // Cheapest filter first. `valid` is a stat and `isForbidden` walks every
       // directory between the file and the root doing an existsSync at each
       // level, and both ran for every cached route before anything asked
-      // whether the route even matched the path — so a miss cost one tree-walk
+      // whether the route even matched the path, so a miss cost one tree-walk
       // per entry and a hit cost one per entry ahead of the match. The regex is
       // pure and all four filters still `continue`, so a matching-but-rejected
       // entry does not shadow a later one; `$dynamic.test.ts` pins that.
       if (!info.getParams(path)) continue
       // Every single-segment route outranks every catch-all, whatever order
-      // the cache filled in — so catch-alls are set aside, and their stat and
+      // the cache filled in, so catch-alls are set aside, and their stat and
       // tree-walk filters run only after the loop finds no specific match.
       if (info.catchAll) {
         ;(deferred ??= []).push(info)
@@ -151,20 +151,20 @@ export class DynamicHandler extends Handler {
       }
       if (!info.valid) continue
       // `filePath` is already `fs.resolve`d by the Info constructor; resolving
-      // it again here re-normalised an identical string.
+      // it again here re-normalized an identical string.
       if (!info.filePath!.startsWith(`${root}/`)) continue
       if (fs.isForbidden(info.filePath!, root)) continue
       return info
     }
     if (deferred) {
       // A real file always beats a catch-all, whatever handler would serve
-      // it: when the requested path names an existing file — literally, or
+      // it: when the requested path names an existing file, literally, or
       // through a compiled extension like `provides.ts` at `/provides.js`
-      // (see `servedSourceExists`) — every catch-all declines so the file's
-      // own handler (possibly lower-priority — CSS falls all the way to
+      // (see `servedSourceExists`) (every catch-all declines so the file's
+      // own handler (possibly lower-priority) CSS falls all the way to
       // StaticHandler) gets asked. A handful of stats, paid only when a
       // catch-all is about to answer. `getCatchAllRoute` applies the same
-      // rule on the discovery path; the two must agree — including the
+      // rule on the discovery path; the two must agree, including the
       // containment clamp: `root + path` is unresolved, so a `..` in the
       // path would have `statSync` resolve it outside the root and turn this
       // into an existence probe. See the comment there.
@@ -219,7 +219,7 @@ export class DynamicHandler extends Handler {
    *
    * The deny-list is matched against the *request path* in `router.ts`, but
    * `routeGlobs` deliberately answers a request with a file of a different
-   * extension — `/schema.css` and `/schema` both resolve to `schema.ts` via
+   * extension: `/schema.css` and `/schema` both resolve to `schema.ts` via
    * stem+ext substitution. So the router's check was being asked about a
    * string that named no file: it said "not blocked", and `TSHandler`
    * compiled and served the very file the default list exists to protect.
@@ -228,26 +228,64 @@ export class DynamicHandler extends Handler {
    *
    * Re-running the check against what actually resolved is the fix. It is
    * gated on `servesFiles` so route-only handlers keep their exemption, and
-   * it wraps every branch — cached, static, dynamic, catch-all — rather than
+   * it wraps every branch (cached, static, dynamic, catch-all), rather than
    * each return point, so a future branch cannot forget it.
    */
   static resolveRoute(path: string): Promise<Route.Info | null>
   static async resolveRoute(path: string) {
-    const info = await this.resolveRouteFile(path)
-    if (!info) return null
+    return this.checkBlocked(await this.resolveRouteFile(path))
+  }
 
+  /**
+   * Resolve `path` to a **literal file only**, never a dynamic or catch-all
+   * match.
+   *
+   * For the error handlers, which look up `error` and `error-<code>` pages by
+   * name. Asking the ordinary resolver for those was wrong twice over.
+   *
+   * **It served the wrong page.** `resolveRoute` falls through to dynamic
+   * matching, so an app with a root `[...slug].tsx` had every error page
+   * claimed by the catch-all, and `/blog/[id].tsx` answered a 404 under
+   * `/blog` by rendering a post with `id = 'error'`. An error page is a file
+   * an application put there on purpose; nothing about it should be pattern
+   * matched.
+   *
+   * **And it was most of the cost of a 404.** `DynamicErrorHandler` walks the
+   * path prefixes, so a miss ran two full resolutions per segment: each one a
+   * glob scan plus an `isForbidden` tree-walk, and each one guaranteed to fail
+   * for an app with no error pages. That is why a 404 cost ten to thirty times
+   * a served page and grew with depth: 64 segments measured at over ten
+   * seconds. Static-only makes each probe one glob and no dynamic scan.
+   */
+  protected static resolveStaticRoute(path: string): Promise<Route.Info | null>
+  protected static async resolveStaticRoute(path: string) {
+    return this.checkBlocked(await this.resolveRouteFile(path, true))
+  }
+
+  /**
+   * The deny-list check both resolvers end in.
+   *
+   * Extracted rather than repeated: it is the clause that stops a resolved
+   * *file* from being served when the request path alone looked innocent (see
+   * `resolveRouteFile`'s note), and two copies is two places for it to be
+   * dropped from.
+   */
+  private static checkBlocked(info: Route.Info | null) {
+    if (!info) return null
     if (
       this.servesFiles &&
       matchBlockedCached(Bakery.config.blocked, `/${info.path}`)
     ) {
       return null
     }
-
     return info
   }
 
-  protected static resolveRouteFile(path: string): Promise<Route.Info | null>
-  protected static async resolveRouteFile(path: string) {
+  protected static resolveRouteFile(
+    path: string,
+    staticOnly?: boolean,
+  ): Promise<Route.Info | null>
+  protected static async resolveRouteFile(path: string, staticOnly = false) {
     const cached = this.getCachedRoute(path)
     if (cached) return cached
 
@@ -269,10 +307,15 @@ export class DynamicHandler extends Handler {
       return this.cacheStaticRoute(path, staticInfo)
     }
 
+    // A literal file was all that was asked for. The dynamic passes below are
+    // not merely skipped as an optimization: for an error page they would be
+    // wrong, and `resolveStaticRoute` says why.
+    if (staticOnly) return null
+
     // `findDynamicRoute` already required `valid` and `!isForbidden` against
     // `Bakery.serveRoot` before returning, so wrapping it in
-    // `validateCachedRoute` — which asserts exactly those two, against exactly
-    // that root — re-ran a stat and a directory tree-walk on a value that had
+    // `validateCachedRoute` (which asserts exactly those two, against exactly
+    // that root) re-ran a stat and a directory tree-walk on a value that had
     // just passed both, and its eviction branch was unreachable from here.
     // `getCachedRoute` still needs the wrapper; entries read from `this.cache`
     // have not been checked.

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

@@ -17,7 +17,7 @@ const DEFAULT_ERROR: Handler.Error.Data = {
  *
  * The copy is the point, not the convenience. `extractErrorData` assigns the
  * getter's result to a local and then *mutates* it, which is safe only while
- * every `this` it runs under hands back a new object — a plain
+ * every `this` it runs under hands back a new object: a plain
  * `= DEFAULT_ERROR` would let any caller write the process-wide default's
  * fields. Both `ErrorHandler` and `DynamicErrorHandler` need the getter and
  * they sit in different class hierarchies, so neither can inherit it from the
@@ -32,7 +32,7 @@ function defaultErrorData(): Handler.Error.Data {
  * route lookup, and the 404 for a path that resolves to nothing.
  *
  * `HTMLHandler`, `TSXHandler` and the Vue plugin's handler render three
- * different file formats and their bodies genuinely differ — but all three
+ * different file formats and their bodies genuinely differ, but all three
  * reach them this way. `errors` is `undefined` for an ordinary page, and
  * `DEFAULT_ERROR` exists only on the error subclasses, so the fallback stays
  * `undefined` for the ordinary handlers. `DynamicErrorHandler.resolveRoute`
@@ -63,7 +63,7 @@ export async function beginPageRoute(
  * whatever error data gets merged in, and it names the route-relative path.
  * `HTMLHandler` used to set it after the merge and `TSXHandler` before, which
  * comes out the same today only because `publicErrorData` never emits a
- * `__file` key — two orderings for one rule is what makes it look like the
+ * `__file` key: two orderings for one rule is what makes it look like the
  * order might matter. It does not; this is the order, and `params` is the
  * object because TSX also feeds that same object to `injectIfHtml`.
  */
@@ -96,7 +96,7 @@ export class HandlerError extends Error {
 }
 
 export class ErrorHandler extends Handler {
-  /** A fresh copy every read — see `defaultErrorData`. */
+  /** A fresh copy every read. See `defaultErrorData`. */
   static get DEFAULT_ERROR() {
     return defaultErrorData()
   }
@@ -132,7 +132,7 @@ export class ErrorHandler extends Handler {
   /**
    * The part of `error` that may cross the wire.
    *
-   * `extractErrorData` puts `error.stack` into `errorBody` deliberately — that
+   * `extractErrorData` puts `error.stack` into `errorBody` deliberately: that
    * is what reaches the server log, and losing it would be a regression. But
    * the same field was being handed straight to the client: a `SQLiteError`
    * from a failed query answered a 500 with the failing statement, the table
@@ -155,13 +155,13 @@ export class ErrorHandler extends Handler {
    * `BuildMessage` (a syntax error) and `ResolveMessage` (an import that
    * resolves to nothing) are what the transpiler and the module resolver throw,
    * and neither is `instanceof Error`. They used to reach the `is.object`
-   * branch below, which reads only `errorCode`/`errorText`/`errorBody` — none
-   * of which a diagnostic has — and so returned the untouched default. A typo
+   * branch below, which reads only `errorCode`/`errorText`/`errorBody` (none
+   * of which a diagnostic has), and so returned the untouched default. A typo
    * in a route file, the single most common server-side failure there is,
    * answered `An unexpected error occurred.` in development as well as in
    * production.
    *
-   * Recognised by shape rather than by constructor: the classes are not
+   * Recognized by shape rather than by constructor: the classes are not
    * exported, and both report zero own enumerable keys, so a string `message`
    * on a non-`Error` object is the only tell. The error-data keys are checked
    * first by the caller, so a record that carries those still takes its own
@@ -180,8 +180,8 @@ export class ErrorHandler extends Handler {
       return {
         ...this.DEFAULT_ERROR,
         errorText: error.message,
-        // `errorDetail` is `error.stack` whenever there is one — so the common
-        // case is untouched — and falls back to the aggregated sub-diagnostics
+        // `errorDetail` is `error.stack` whenever there is one (so the common
+        // case is untouched), and falls back to the aggregated sub-diagnostics
         // for the stackless `AggregateError` that `import()`ing a broken `.tsx`
         // throws, where `String(error)` was a summary count and nothing else.
         errorBody: errorDetail(error) || String(error),
@@ -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),
       }
     }
 
@@ -204,7 +213,7 @@ export class ErrorHandler extends Handler {
         errorObj.errorText !== undefined ||
         errorObj.errorBody !== undefined
 
-      // Authored error data wins, `message` or no `message` — the branch order
+      // Authored error data wins, `message` or no `message`, the branch order
       // and its semantics are unchanged for everything that ever reached it.
       if (!authored && this.isDiagnostic(error)) {
         return {
@@ -232,7 +241,7 @@ export class ErrorHandler extends Handler {
 
 export class DynamicErrorHandler extends DynamicHandler {
   /**
-   * The same fresh copy `ErrorHandler.DEFAULT_ERROR` hands back — see
+   * The same fresh copy `ErrorHandler.DEFAULT_ERROR` hands back. See
    * `defaultErrorData`. Declared again rather than inherited because this
    * class descends from `DynamicHandler`, not from `ErrorHandler`.
    */
@@ -270,9 +279,12 @@ export class DynamicErrorHandler extends DynamicHandler {
 
       const defsPage = `${prefix}/error`
       const codePage = `${prefix}/error-${errors.errorCode}`
+      // `resolveStaticRoute`, never `resolveRoute`: an error page is a file by
+      // name, and letting the dynamic matcher answer meant a root catch-all
+      // claimed every one of them. See the note on that method.
       const routeInfo =
-        (await super.resolveRoute(codePage)) ||
-        (await super.resolveRoute(defsPage))
+        (await super.resolveStaticRoute(codePage)) ||
+        (await super.resolveStaticRoute(defsPage))
       if (routeInfo) return routeInfo
     }
 
@@ -286,14 +298,14 @@ export class DynamicErrorHandler extends DynamicHandler {
  * `ErrorHandler.publicBody` is the rule; this is it applied to a whole record,
  * for the handlers that hand error data to a *template* rather than rendering
  * a string themselves. `HTMLErrorHandler` and `TSXErrorHandler` merge the
- * record into their page params, and those params reach the document twice —
+ * record into their page params, and those params reach the document twice,
  * through `{{...}}` substitution and through the `window.__PAGE_PARAMS__`
  * script `DOMTools.params` injects into every page. The second path is why
  * redacting in the template was never enough: an `error.html` that never
  * mentions `errorBody` still published the stack, absolute source paths and
  * all, to any anonymous request in production.
  *
- * `errorText` is deliberately untouched — `DefaultErrorHandler` shows it in
+ * `errorText` is deliberately untouched: `DefaultErrorHandler` shows it in
  * its heading in every mode, and one rule in one place beats two that drift.
  */
 export function publicErrorData(error: Handler.Error.Data): Handler.Error.Data {

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

@@ -11,7 +11,7 @@ import { Handler } from './$base'
  * else. `JsonResponseData` is the framework's one-envelope idiom (convention
  * 7) and `processResponse` already renders it with its own `status`, so an
  * `ApiHandler` route returning `response.json.error(401, …)` answered 401
- * while the identical line in a middleware did not — the value was not a
+ * while the identical line in a middleware did not: the value was not a
  * `Response`, so the chain ignored it and the request carried on.
  *
  * Widening further, to "anything truthy", is the tempting version and is
@@ -30,8 +30,8 @@ function isMiddlewareResult(value: unknown): value is MiddlewareResult {
 /**
  * Per-request slot for the response produced during `canHandle`, so `handle`
  * can return it without re-running the chain. This was previously a static
- * field, which meant two concurrent requests could swap responses — including
- * each other's `Set-Cookie` headers — at any `await` boundary.
+ * field, which meant two concurrent requests could swap responses (including
+ * each other's `Set-Cookie` headers) at any `await` boundary.
  */
 const pending = new WeakMap<Request, MiddlewareResult>()
 
@@ -60,13 +60,13 @@ export class MiddlewareHandler extends Handler {
       return cached
     }
 
-    // One config read for both `onRequest` and the middleware chain — same
+    // One config read for both `onRequest` and the middleware chain: same
     // request, same host store, so the snapshot cannot go stale mid-call.
     const config = Bakery.config
     const intercepted = await config.onRequest(req!)
     if (intercepted) {
       // `|| undefined` used to sit here, and `injectIfHtml` returns null for
-      // anything that is not HTML — so a plain-text 403 from `onRequest`
+      // anything that is not HTML, so a plain-text 403 from `onRequest`
       // vanished and the request carried on. Inject when it is HTML, keep the
       // original otherwise, exactly as the middleware chain below does.
       return (await injectIfHtml(intercepted)) || intercepted
@@ -91,7 +91,7 @@ export class MiddlewareHandler extends Handler {
 
     // An envelope is JSON by construction, so it skips injection rather than
     // paying `DOMTools.isHTML` to be told so. `processResponse` reads its
-    // `status` and serialises it.
+    // `status` and serializes it.
     if (data instanceof JsonResponseData) return data
 
     const injectedRes = await injectIfHtml(data!)