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

package/src/handlers/assets/image.ts

@@ -7,7 +7,40 @@ import { response } from '../../utils/http'
 import { Handler, type Route } from '../core/$base'
 import { getStatic } from '../core/$static'
 
-const IS_IMAGE_REGEX = /(.*)\/(.*)(;(\d+))?\.(png|jpg|jpeg|webp|gif|bmp)$/i
+/**
+ * Does this path name an image?
+ *
+ * **`[^/]*`, not `.*`, and the difference is a denial of service.** This read
+ * `/(.*)\\/(.*)(;(\\d+))?\\.(png|…)$/`, whose two greedy groups could each match
+ * the separator, so every `/` in the path doubled the ways the engine could
+ * split it. The work is superlinear and it is paid by paths that do **not**
+ * match, because a failing match is the one that has to try every split before
+ * it can say no, and `canHandle` runs on every route-cache miss, above the
+ * handlers that serve ordinary pages.
+ *
+ * Measured on Bun 1.4.0, one call, path of `/` + `a/` × n + `x.txt`:
+ *
+ *   slashes   chars      old          new
+ *        64     134      0.98 ms      0.00091 ms
+ *       128     262      7.05 ms      0.00146 ms
+ *       256     518     63.88 ms      0.00272 ms
+ *       512    1030    512.55 ms      0.00564 ms
+ *
+ * One unauthenticated request with a 1 KB path stalled the event loop for half
+ * a second, and the rate limiter cannot help at one request per second. A
+ * filename cannot contain a separator, so the second group never should have
+ * been able to: bounding it removes the ambiguity and the cost with it.
+ *
+ * The captures are gone because nothing read them: `canHandle` only calls
+ * `.test()`, and `IMAGE_CAPTURE` below is what parses the parts. The trailing
+ * `(;(\\d+))?` was dead for the same reason: `.*` already covered `;800`.
+ *
+ * Equivalence is not an argument from reading: old and new agree on a 40-path
+ * corpus and on 200,000 random strings over the alphabet that makes the shapes
+ * interesting ([ab/.;1png-_]), with zero disagreements. `image.test.ts` keeps
+ * both halves.
+ */
+const IS_IMAGE_REGEX = /\/[^/]*\.(?:png|jpg|jpeg|webp|gif|bmp)$/i
 const IMAGE_CAPTURE = /^(.+?)([^/;.]+)(?:;(\d+))?\.([a-zA-Z0-9]+)$/i
 
 export class ImageHandler extends Handler {
@@ -53,7 +86,7 @@ export class ImageHandler extends Handler {
     const rel = `${dir.slice(1)}/${name}.${ext}`
 
     // This handler outranks PublicHandler, so the containment and `.forbidden`
-    // checks must still apply — otherwise a protected image under public/ is
+    // checks must still apply: otherwise a protected image under public/ is
     // served anyway, despite PublicHandler correctly refusing it. getStatic
     // carries those checks so all the file-serving handlers share one spelling.
     const resolved = await getStatic(`/${rel}`, [
@@ -87,7 +120,7 @@ export class ImageHandler extends Handler {
       const cacheDir = fs.resolve(Bakery.cacheDir, 'images')
       // Key on the resolved source, not the request path. The path carries the
       // caller's raw `;NNN` size suffix *before* clamping, so `;16`, `;17`, `;18`…
-      // each produced a distinct id and re-encoded the whole source to WebP —
+      // each produced a distinct id and re-encoded the whole source to WebP:
       // an unbounded cache and unbounded CPU from one image URL.
       const imageCacheId = Bun.hash(hostKey(source)).toString(36)
 

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.