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

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!)

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

@@ -4,7 +4,7 @@ import { fs } from '../../utils'
  * Route mounts: map a URL prefix onto a directory outside the app's serve root.
  *
  * Handlers resolve files under `Bakery.serveRoot`, so a plugin wanting to serve
- * its own pages or client assets had no choice but to hand-roll it — reading
+ * its own pages or client assets had no choice but to hand-roll it: reading
  * files itself, bundling on the fly, and reimplementing the caching and
  * containment the handler pipeline already does. `DashboardHandler` is the
  * worked example of that cost.
@@ -17,7 +17,7 @@ import { fs } from '../../utils'
  * the search dir *and* the root, so traversal cannot escape it.
  */
 export interface RouteMount {
-  /** URL prefix, leading slash, no trailing slash — e.g. `/_dashboard`. */
+  /** URL prefix, leading slash, no trailing slash, e.g. `/_dashboard`. */
   prefix: string
   /** Absolute directory the prefix resolves against. */
   dir: fs.AbsolutePath

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

@@ -1,4 +1,5 @@
 import { LRUCache } from '../../cache/lru'
+import { hostKey } from '../../core/bakery'
 import type { Handler } from './$base'
 
 /**
@@ -51,8 +52,8 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
    * `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
+   * 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.
    *
@@ -98,7 +99,7 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
    * `canHandle` without the microtask hop when the answer is synchronous.
    *
    * Most canHandles are plain predicates, and `await`ing their boolean cost a
-   * microtask hop (~426ns) per probe, 2–4 probes per request. Returns a
+   * microtask hop (~426ns) per probe, 2 to 4 probes per request. Returns a
    * boolean for a sync answer and the promise itself for an async one, so
    * callers only `await` a value that is actually a promise:
    *
@@ -126,8 +127,17 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
   // must not run twice. That constraint is what the branching encodes.
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: cache-path + side-effect-sensitive probe loop
   async resolve(path: string, req?: Request, ...rest: any[]) {
-    const host = req?.__hostname || ''
-    const pathId = `${this.id}:${host}:${path}`
+    // The **resolved** host, not the header. `__hostname` is whatever arrived
+    // in `Host`, and `routeCache` is one bounded LRU shared by every tenant, so
+    // a client varying that header minted an entry per spelling and walked the
+    // real hosts' entries out of the cache for as long as it kept asking. The
+    // file cache carried the same bug and was fixed; this one kept it.
+    //
+    // `hostKey` resolves through the multi-host config the way every other
+    // per-tenant key does, so an unknown or unconfigured host collapses to a
+    // single entry instead of one per spelling. The shape is unchanged when
+    // there is no host: `hostKey` returns the bare path.
+    const pathId = `${this.id}:${hostKey(path)}`
     const cached: any = HandlerMap.routeCache.get(pathId)
 
     // Only tracked once there is a cache hit to skip past. Middleware has
@@ -138,7 +148,7 @@ export class HandlerMap<T extends typeof Handler = typeof Handler> extends Map<
     if (cached) {
       probed = new Set()
       // A cache hit skips every handler above the cached one. Ask the
-      // gatekeepers that outrank it first — the same handlers, in the same
+      // gatekeepers that outrank it first: the same handlers, in the same
       // order, a cold resolve would have reached before the cached one.
       const rank = this.order().get(cached) ?? Number.POSITIVE_INFINITY
       for (const gate of this.gatekeepers()) {

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

@@ -15,14 +15,14 @@ export type RouteScanOptions = {
 }
 
 // `[!.]` keeps catch-alls (`[...name]`) out of the single-param globs: they
-// are matched separately, and last — a catch-all is the weakest route form,
+// are matched separately, and last. A catch-all is the weakest route form,
 // consulted only after specific files, single-param siblings and child-index
 // descent have all missed.
 const catchAllGlob = (ext: string) => new Bun.Glob(`[[]...*${ext || '.*'}`)
 
 // The single-param route forms, in the order they are tried: `[name].ext`
 // first, then the literal-asterisk `*.ext`. Built here rather than twice inside
-// `routeGlobs` — the `dynamicOnly` branch and the combined branch returned
+// `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
@@ -33,22 +33,22 @@ const catchAllGlob = (ext: string) => new Bun.Glob(`[[]...*${ext || '.*'}`)
 // 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
+// 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
+// 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.
+// `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 || '.*'}`),
@@ -88,8 +88,7 @@ const routeGlobs = (
  * The catch-all fallback for one directory level: `dir/[...name].ext`,
  * containment-checked like every other candidate. Skipped for `staticOnly`
  * (the caller wants a literal file), and it *yields to any real file*: when
- * the request's remaining segments name an existing file under `dir` —
- * whatever its extension — the catch-all declines, so a lower-priority
+ * the request's remaining segments name an existing file under `dir` ( * whatever its extension) the catch-all declines, so a lower-priority
  * handler (TSHandler, StaticHandler) can serve the file itself. A directory
  * is not a file and does not trigger the yield. `findDynamicRoute` applies
  * the same rule on the cached path; the two must agree.
@@ -102,7 +101,7 @@ const routeGlobs = (
  * `provides.ts` at `/teacher/provides` and `/teacher/provides.js`, so neither
  * spelling named a file on disk and a Vue catch-all above it (priority 58 vs
  * 50) served HTML to a browser that asked for a module. The probe now also
- * tries the registered dynamic extensions against the extensionless base —
+ * tries the registered dynamic extensions against the extensionless base:
  * the same mapping the serving handlers apply, read from the live registry so
  * a plugin's extension (`.vue`) counts without core naming it.
  *
@@ -118,7 +117,7 @@ export function servedSourceExists(target: string): boolean {
     try {
       exts = (handler as { config?: { ext?: unknown } }).config?.ext
     } catch {
-      // A config getter that needs state this process lacks — a handler with
+      // A config getter that needs state this process lacks: a handler with
       // no ext table cannot claim a source file either way.
       continue
     }
@@ -147,13 +146,13 @@ async function getCatchAllRoute(
     const target = fs.resolve(dir, restSegments.join('/'))
     // Stat only inside `dir`. A rest containing `..` resolves outside it, and
     // statting there would make this yield a boolean existence probe for any
-    // path on the filesystem — the 404-vs-render difference is observable.
-    // URL parsing normalises `..` and `%2e%2e` away, so no HTTP request
+    // path on the filesystem: the 404-vs-render difference is observable.
+    // URL parsing normalizes `..` and `%2e%2e` away, so no HTTP request
     // reaches here with one; this closes the door for any caller that skips
-    // that normalisation. An escape skips the yield rather than refusing, so
+    // that normalization. An escape skips the yield rather than refusing, so
     // the catch-all answers exactly as it did before the yield rule existed.
     // `dir` comes from `fs.resolve`, so the separator-suffixed prefix test is
-    // exact — plain `startsWith(dir)` would also accept a sibling directory
+    // exact: plain `startsWith(dir)` would also accept a sibling directory
     // whose name merely begins with it.
     if (
       (target === dir || target.startsWith(`${dir}/`)) &&
@@ -169,7 +168,7 @@ async function getCatchAllRoute(
 
   // A bare-directory request (`/docs` with no index) reaches here with no
   // rest segments, and only the `[...name!]` spelling opted into claiming
-  // it — the plain form keeps requiring at least one segment.
+  // it: the plain form keeps requiring at least one segment.
   if (!restSegments.length && !info.optionalCatchAll) return null
 
   return info
@@ -183,7 +182,7 @@ export async function getRoute(
   root?: fs.AbsolutePath,
   options: RouteScanOptions = {},
 ): Promise<Handler.Route.Info | null> {
-  // Both used to default to `Bakery.serveRoot` independently — two reads of
+  // Both used to default to `Bakery.serveRoot` independently. Two reads of
   // the config getter (an AsyncLocalStorage getStore each) when a caller
   // omits both. One read now covers whichever is missing; the values are
   // unchanged.
@@ -234,7 +233,7 @@ export async function getRoute(
     // statement is `isForbidden(dir, root)` with these exact arguments, and its
     // `null` reaches the same `return null` this function ends on. Checking
     // here as well made every level of a nested route pay two identical
-    // directory tree-walks — and `isForbidden` walks from the file to the root
+    // directory tree-walks, and `isForbidden` walks from the file to the root
     // doing an existsSync at each level, so that is the most expensive thing
     // this function does. `src/tests/forbidden.test.ts` pins both branches.
     if (first !== 'index') {
@@ -246,7 +245,7 @@ export async function getRoute(
     // `first === 'index'` is the bare-directory request (`/docs` arrives here
     // as an injected 'index' segment, after no index file matched). The plain
     // `[...name]` pattern requires at least one rest segment and cannot claim
-    // it; `[...name!]` exists to — `getCatchAllRoute` tells them apart.
+    // it; `[...name!]` exists to: `getCatchAllRoute` tells them apart.
     if (!options.staticOnly) {
       return await getCatchAllRoute(
         ext,
@@ -263,7 +262,7 @@ export async function getRoute(
     if (route) return route
 
     // The walk above descends one real segment at a time and dead-ends when
-    // the next directory does not exist — which for a catch-all request
+    // the next directory does not exist, which for a catch-all request
     // (`/docs/a/b/c` against `docs/[...slug].tsx`) is the common case. Each
     // level unwinds through here, so the deepest existing directory gets the
     // first chance to claim the rest.

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

@@ -4,14 +4,13 @@ import { fs } from '../../utils/fs'
 import { resolveMount } from './$mounts'
 
 /**
- * Literal file resolution — the static counterpart to `getRoute`.
+ * Literal file resolution: the static counterpart to `getRoute`.
  *
  * `getRoute` answers "which file backs this *route*", with extensionless URLs,
  * dynamic `[id]` segments and glob scanning. This answers the simpler question
  * "which file is at this path, and am I allowed to serve it".
  *
- * It exists because four handlers were each spelling that out themselves —
- * StaticHandler, PublicHandler, ImageHandler and NMHandler — in four slightly
+ * It exists because four handlers were each spelling that out themselves ( * StaticHandler, PublicHandler, ImageHandler and NMHandler) in four slightly
  * different ways, and only some of them checked everything. Once route mounts
  * arrived the drift got worse: a mount-aware StaticHandler sitting next to a
  * mount-blind PublicHandler is the kind of inconsistency that turns into a bug
@@ -19,7 +18,7 @@ import { resolveMount } from './$mounts'
  *
  * **Three of those four go through this; NMHandler does not, on purpose.** Its
  * entry point is resolved by `Bun.build`, not by the filesystem, so
- * `/_nm/pkg/sub` legitimately means `pkg/sub/index.js` — a path this function
+ * `/_nm/pkg/sub` legitimately means `pkg/sub/index.js`: a path this function
  * answers `null` for, because it is a directory. It therefore repeats the
  * containment test and calls `fs.isForbidden` itself; the reasoning, and the
  * test that pins the divergence, are in `handlers/assets/nm.ts`. It is the one
@@ -43,7 +42,7 @@ export interface StaticTarget {
  * mounted plugin cannot be traversed out of.
  *
  * Roots are tried in order, and a root that fails containment is skipped
- * rather than aborting — mirroring ImageHandler, which legitimately looks in
+ * rather than aborting: mirroring ImageHandler, which legitimately looks in
  * both the serve root and the public root.
  */
 export async function getStatic(
@@ -64,23 +63,23 @@ export async function getStatic(
     const file = fs.resolve(root, candidate.relative)
 
     // Two checks, not one: the prefix test catches a resolved path that
-    // escaped the root, and isForbidden additionally honours `.forbidden`
-    // markers. It does *not* apply the blocked globs — `Bakery.config.blocked`
+    // escaped the root, and isForbidden additionally honors `.forbidden`
+    // markers. It does *not* apply the blocked globs: `Bakery.config.blocked`
     // is matched against the request path in `router.ts` and again in
-    // `handlers/assets/static.ts`, never against a resolved file path — so a
-    // caller reaching for `getStatic` as a one-stop authorisation check is
+    // `handlers/assets/static.ts`, never against a resolved file path, so a
+    // caller reaching for `getStatic` as a one-stop authorization check is
     // getting containment and `.forbidden` only.
     //
-    // Containment stays first — nothing stats a path that escaped the root.
+    // Containment stays first: nothing stats a path that escaped the root.
     // After that the order is by cost: `isForbidden` walks every directory
     // between the file and the root, so running it before the existence check
-    // paid for a whole tree-walk on every candidate that simply is not there —
+    // paid for a whole tree-walk on every candidate that simply is not there,
     // which is most of them, since a miss here is how each root in the list,
     // and every extensionless probe, gets ruled out. All checks are pure and
     // all `continue`, so the candidate chosen is unchanged.
     //
     // One stat answers both questions. This used to be `fs.exists` (a stat)
-    // then `fs.isDir` (which is `fs.exists` plus a second stat of its own) —
+    // then `fs.isDir` (which is `fs.exists` plus a second stat of its own):
     // up to three stats per candidate at ~28us each on Bun/Windows. A failed
     // stat means "nothing servable here" and falls through to the next
     // candidate, exactly as the exists check did.

package/src/handlers/routes/api.ts

@@ -46,19 +46,19 @@ export class ApiHandler extends DynamicHandler {
     if (result !== null && result !== undefined) return result
 
     // Two different faults used to share one bare 404, and neither channel
-    // named the file — so "No response from handler" sent the developer
+    // named the file, so "No response from handler" sent the developer
     // hunting for a route that was sitting on disk the whole time.
     //
     // `null` and `undefined` are what tell them apart, and the split is exact
     // rather than incidental: `DynamicHandler.executeModule` *throws* when the
     // import fails (that is the 500 path), returns a literal `null` for
     // "module loaded, no `default`", and otherwise returns whatever the
-    // handler produced — `undefined` when it produced nothing.
+    // handler produced, `undefined` when it produced nothing.
     if (result === null) {
       // A 500, not a 404: the route resolved, the file exists, and the server
       // could not answer with it. That is a server fault, and the message says
-      // what to add. PROD still redacts it — `publicBody` replaces any 5xx
-      // body — so naming the file here discloses nothing to a client.
+      // what to add. PROD still redacts it (`publicBody` replaces any 5xx
+      // body), so naming the file here discloses nothing to a client.
       handlerLog.API_NO_DEFAULT({ file: filePath })
       return response.error(
         `API route has no export default: ${info.path}`,
@@ -88,7 +88,7 @@ export class ApiErrorHandler extends ErrorHandler {
 
   static handle(_p: string, _r: Request, error: Handler.Error.Data) {
     // `publicBody`, not `errorBody`: in production the latter is the stack of
-    // whatever threw. The full trace still reaches the log — `handleRequestError`
+    // whatever threw. The full trace still reaches the log: `handleRequestError`
     // passes the unredacted data to `config.onError` before this runs.
     return response.json.error(error.errorCode, ErrorHandler.publicBody(error))
   }

package/src/handlers/routes/html.ts

@@ -78,8 +78,8 @@ async function sharedHandler(
   // through `{{...}}` *and* through the `__PAGE_PARAMS__` script injected
   // into every page, so the raw stack was published in PROD even by a
   // template that never mentioned it. Guarded because `errorData` is
-  // `undefined` for an ordinary page — `DEFAULT_ERROR` only exists on the
-  // error handler — and the spread below tolerates that where the helper,
+  // `undefined` for an ordinary page (`DEFAULT_ERROR` only exists on the
+  // error handler), and the spread below tolerates that where the helper,
   // deliberately strict about the shape it redacts, does not.
   // Annotated because `beginPageRoute` hands back real `Handler.Error.Data`
   // where this used to read an untyped `(this as any).DEFAULT_ERROR`: the

package/src/handlers/routes/proxy.ts

@@ -63,7 +63,7 @@ export class ProxyHandler extends Handler {
 
     const resHeaders = new Headers(proxyRes.headers)
     // Bun already decompressed the body, so the upstream's content-encoding is
-    // wrong — and so is its content-length, which described the compressed size.
+    // wrong, and so is its content-length, which described the compressed size.
     resHeaders.delete('content-encoding')
     resHeaders.delete('content-length')
     return new Response(proxyRes.body, {

package/src/logger/clients.ts

@@ -1,12 +1,12 @@
 /**
  * WebSocket clients subscribed to the live log stream.
  *
- * `LiveReloadHandler` owns membership — it adds a socket on
+ * `LiveReloadHandler` owns membership: it adds a socket on
  * `subscribe_logger` and removes it on close. Consumers (the dashboard's
  * log broadcast, the analytics `activeLoggers` gauge) only read.
  *
  * This lives in core rather than a plugin deliberately: it used to be
  * defined in `plugins/analytics/core`, which made core import from a
- * plugin — a backwards edge that blocks packaging core on its own.
+ * plugin, a backwards edge that blocks packaging core on its own.
  */
 export const connectedLoggers = new Set<any>()

package/src/logger/logger.ts

@@ -46,7 +46,7 @@ export function setLogCallback(cb: (entry: LoggerEntry) => void) {
  *
  * Three call sites used to spell this as `Promise.try(() =>
  * onLogCallback?.(…)).catch(() => {})`, which allocated two promises and
- * scheduled a microtask for *every* line — including every line logged while
+ * scheduled a microtask for *every* line, including every line logged while
  * no sink was registered at all. `Try` swallows a synchronous throw and a
  * rejected promise alike (see `utils/isomorphic/try.ts`) without allocating
  * anything on the synchronous path, which is the only path a sink typed
@@ -61,7 +61,7 @@ function emit(entry: LoggerEntry): void {
 }
 
 // Hoisted: both were rebuilt on every call, and neither depends on the input.
-// The colour table is a 23-property literal and the pattern a regex literal,
+// The color table is a 23-property literal and the pattern a regex literal,
 // so a process logging steadily paid for both on every line.
 const COLORS: MapOf<string> = {
   r: '\x1b[31m', // Red
@@ -299,7 +299,7 @@ type Messages<T extends MapOf<string>> = {
 const RX_PARAM = /\{([^}]+)\}/g
 
 type ParsedMessage = {
-  /** The string this was parsed from — the cache's validity check. */
+  /** The string this was parsed from: the cache's validity check. */
   raw: string
   level: LogLevels
   template: string
@@ -332,7 +332,7 @@ export function messageLogger<T extends MapOf<string>>(
   targetMsgs: T,
 ) {
   /**
-   * One entry per *declared* key, so it is bounded by the message table — the
+   * One entry per *declared* key, so it is bounded by the message table: the
    * tables in `serve-log.ts` are literals of a dozen-odd entries each.
    * Undeclared props are deliberately left uncached: the trap fabricates a
    * message for those, and a caller reading arbitrary property names off the