@orkestrel/middleware 0.0.19 → 0.0.20

package/dist/src/server/index.d.ts

@@ -1,10 +1,10 @@
-import { Encoding } from '@orkestrel/server';
-import { FileHandle } from 'node:fs/promises';
+import type { Encoding } from '@orkestrel/server';
+import type { FileHandle } from 'node:fs/promises';
 import { HTTPError } from '@orkestrel/server';
-import { MiddlewareHandler } from '@orkestrel/server';
-import { MultipartBody } from '@orkestrel/middleware';
-import { MultipartFile } from '@orkestrel/middleware';
-import { MultipartState } from '@orkestrel/middleware';
+import type { MiddlewareHandler } from '@orkestrel/server';
+import type { MultipartBody } from '@orkestrel/middleware';
+import type { MultipartFile } from '@orkestrel/middleware';
+import type { MultipartState } from '@orkestrel/middleware';
 
 /**
  * Describes one in-memory asset representation returned by an {@link AssetSourceInterface}.
@@ -23,7 +23,7 @@ export declare interface Asset {
  * Configures `createAssets` — in-memory identity/Brotli asset serving.
  *
  * @remarks
- * - `source` — the required in-memory asset reader. It MUST answer a bounded
+ * - `source` — the required in-memory asset reader. It must answer a bounded
  *   key set and return `undefined` for every key outside it, because
  *   `createAssets` retains every successful result for the factory's lifetime
  *   and evicts nothing. A `source` that synthesizes a representation for an
@@ -40,12 +40,12 @@ export declare interface AssetOptions {
  * @remarks
  * A successful result is cached by `createAssets`; later source changes do
  * not alter that path's response. A miss may be read again on a later request.
- * `read` therefore owes a BOUNDED key set: that cache retains every
+ * `read` therefore owes a bounded key set: that cache retains every
  * successful result for the factory's lifetime and evicts nothing.
  */
 export declare interface AssetSourceInterface {
     /**
-     * Reads one asset representation.
+     * Reads one identity or Brotli asset representation for a validated relative key.
      *
      * @param path - The validated relative asset path
      * @returns The asset, or `undefined` when the path is absent
@@ -136,12 +136,11 @@ export declare function computeFileETag(size: number, mtimeMs: number): string;
 export declare function createAssets<TState>(options: AssetOptions): MiddlewareHandler<TState>;
 
 /**
- * Compresses response bodies through `node:zlib` — the node-bound sibling of
- * the core face's `CompressionStream`-feature-detected `createCompression`,
- * guaranteed available on any Node runtime rather than dependent on the
- * WHATWG `CompressionStream` global. Ships as a SEPARATE package entry point
- * (`@orkestrel/middleware/server`) from the core face's `createCompression`,
- * so the shared name is unambiguous per consumer import path.
+ * Compresses response bodies through `node:zlib`, guaranteed on any Node runtime rather
+ * than dependent on the WHATWG `CompressionStream` global. This battery is the
+ * node-bound sibling of the core face's feature-detected `createCompression`, and it
+ * ships from a separate package entry point (`@orkestrel/middleware/server`) so the
+ * shared name is unambiguous per consumer import path.
  *
  * @remarks
  * Peer-type limitation, the same one the core face carries: the shipped
@@ -178,7 +177,7 @@ export declare function createCompression<TState>(options?: NodeCompressionOptio
  * {@link MultipartError} this battery's parser throws is re-thrown as an
  * {@link HTTPError} carrying the same status/message, so `createBoundary`
  * (or any HTTPError-aware renderer) maps it correctly without depending on
- * this node face's error type. Fail-closed on the DOWNSTREAM handler too: if
+ * this node face's error type. Fail-closed on the downstream handler too: if
  * `next()` throws, every still-`'staged'` uploaded file is unlinked
  * (best-effort) before the error is re-thrown, so an unhandled downstream
  * failure never leaks temp files. A normal return leaves staged files
@@ -200,16 +199,16 @@ export declare function createCompression<TState>(options?: NodeCompressionOptio
 export declare function createMultipart<TState extends MultipartState>(options?: MultipartOptions): MiddlewareHandler<TState>;
 
 /**
- * Serves static files from `options.root` over `node:fs` — the node-bound
- * static-file battery.
+ * Serves static files from `options.root` over `node:fs` — the node-bound static-file
+ * battery, answering conditional, ranged, and SPA-fallback requests.
  *
  * @remarks
- * Containment is enforced on CANONICAL paths, not merely the lexically
+ * Containment is enforced on canonical paths, not merely the lexically
  * resolved one: `options.root` is canonicalized once (memoized) and every
  * request's candidate path is re-canonicalized (`fs.realpath`) before it is
  * served, so a symlink whose target escapes `root` is refused (falls through
  * to `next()`) even though the lexical path resolved inside `root`. A
- * symlink that resolves to a target still INSIDE `root` is unaffected and
+ * symlink that resolves to a target still inside `root` is unaffected and
  * still serves normally. A dangling symlink (`realpath` throws `ENOENT`) or
  * any other `realpath` failure is treated as a miss — this battery never
  * throws or 500s on a symlink surprise. On a streamed response (a 200 or 206
@@ -246,31 +245,31 @@ export declare function createStatic<TState>(options: StaticOptions): Middleware
  */
 export declare function createUploadedFile(input: UploadedFile): UploadedFile;
 
-/** Names the MIME type served when a file extension has no known mapping. */
+/** Names `'application/octet-stream'`, the MIME type served when a file extension has no known mapping. */
 export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
 
-/** Holds `createMultipart`'s default maximum field-part count. */
+/** Holds `100`, `createMultipart`'s default maximum field-part count. */
 export declare const DEFAULT_MULTIPART_FIELD_COUNT = 100;
 
-/** Holds `createMultipart`'s default per-field byte-size cap. */
+/** Holds `65_536`, `createMultipart`'s default per-field byte-size cap. */
 export declare const DEFAULT_MULTIPART_FIELD_SIZE = 65536;
 
-/** Holds `createMultipart`'s default maximum file-part count. */
+/** Holds `10`, `createMultipart`'s default maximum file-part count. */
 export declare const DEFAULT_MULTIPART_FILE_COUNT = 10;
 
-/** Holds `createMultipart`'s default per-file byte-size cap. */
+/** Holds `10_485_760`, `createMultipart`'s default per-file byte-size cap. */
 export declare const DEFAULT_MULTIPART_FILE_SIZE = 10485760;
 
-/** Holds `createMultipart`'s default combined request-body byte-size cap. */
+/** Holds `52_428_800`, `createMultipart`'s default combined request-body byte-size cap. */
 export declare const DEFAULT_MULTIPART_TOTAL = 52428800;
 
-/** Names `createStatic`'s default policy for a path carrying a dotfile segment. */
+/** Names `'ignore'`, `createStatic`'s default policy for a path carrying a dotfile segment. */
 export declare const DEFAULT_STATIC_DOTFILES: NonNullable<StaticOptions['dotfiles']>;
 
-/** Names `createStatic`'s `fallback: true` default excluded path prefix. */
+/** Names `'/api'`, `createStatic`'s `fallback: true` default excluded path prefix. */
 export declare const DEFAULT_STATIC_FALLBACK_EXCLUDE = "/api";
 
-/** Names `createStatic`'s default directory-index filename. */
+/** Names `'index.html'`, `createStatic`'s default directory-index filename. */
 export declare const DEFAULT_STATIC_INDEX = "index.html";
 
 /**
@@ -316,11 +315,11 @@ export declare function extractMultipartBoundary(contentType: string | null): st
 
 /**
  * Checks whether `child` is `parent` itself or lies inside it on-disk — the
- * FILESYSTEM containment predicate `createStatic` applies to `fs.realpath`
+ * filesystem containment predicate `createStatic` applies to `fs.realpath`
  * output (never to a URL pathname — that is {@link isUnderPath}'s job).
  *
  * @remarks
- * Argument order is `(child, parent)` — deliberately the OPPOSITE conceptual
+ * Argument order is `(child, parent)` — deliberately the opposite conceptual
  * order from {@link isUnderPath}`(pathname, prefix)`, so a call site cannot
  * casually swap one predicate in for the other. Built on `path.relative`,
  * this is separator-correct on both POSIX (`/`) and win32 (`\`) — unlike a
@@ -384,7 +383,7 @@ export declare function isMultipartError(value: unknown): value is MultipartErro
  *
  * @remarks
  * Normalizes superscript digits (`¹²³` → `123`) first, strips trailing dots
- * and spaces (Windows drops them), takes the STEM before the first `.`,
+ * and spaces (Windows drops them), takes the stem before the first `.`,
  * upper-cases it, and tests it against {@link RESERVED_DEVICE_NAMES}
  * (`CON PRN AUX NUL COM1-9 LPT1-9`) — an exact-stem match only, so
  * `console.js` and `nullable.css` are never flagged.
@@ -402,7 +401,7 @@ export declare function isMultipartError(value: unknown): value is MultipartErro
 export declare function isReservedDeviceName(segment: string): boolean;
 
 /**
- * Checks whether `pathname` is `prefix` itself or lies under it on a SEGMENT
+ * Checks whether `pathname` is `prefix` itself or lies under it on a segment
  * boundary — the shared under-path test `resolveStaticPath`'s prefix strip
  * and `createStatic`'s SPA-fallback `exclude` both apply, so `exclude:
  * '/api'` matches `/api` and `/api/x` but never `/apifoo`.
@@ -476,13 +475,16 @@ export declare function moveUploadedFile(file: UploadedFile, destination: string
  */
 export declare const MULTIPART_ERROR_BRAND: unique symbol;
 
-/** Holds the maximum bytes a single multipart part's header block may occupy before it is malformed. */
+/** Holds `16_384`, the maximum bytes a single multipart part's header block may occupy before it is malformed. */
 export declare const MULTIPART_MAX_HEADER_BLOCK = 16384;
 
-/** Holds the maximum bytes scanned before the first multipart boundary is found before it is malformed. */
+/** Holds `65_536`, the maximum bytes scanned before the first multipart boundary is found before it is malformed. */
 export declare const MULTIPART_MAX_PREAMBLE = 65536;
 
-/** Holds the HTTP status `createMultipart` renders for each {@link MultipartErrorCode}. */
+/**
+ * Holds the HTTP status `createMultipart` renders for each {@link MultipartErrorCode}:
+ * `'limit'` is 413, `'malformed'` is 400, and `'rejected'` is 415.
+ */
 export declare const MULTIPART_STATUS: Readonly<Record<MultipartErrorCode, number>>;
 
 /**
@@ -520,7 +522,7 @@ export declare class MultipartError extends HTTPError {
 export declare type MultipartErrorCode = 'limit' | 'malformed' | 'rejected';
 
 /**
- * Describes the per-category size/count caps `createMultipart` enforces MID-STREAM — the
+ * Describes the per-category size/count caps `createMultipart` enforces mid-stream — the
  * effective limits, every documented default already applied.
  *
  * @remarks
@@ -576,7 +578,7 @@ export declare interface MultipartLimitsInput {
  *
  * @remarks
  * - `limits` — see {@link MultipartLimitsInput}.
- * - `allowed` — a MIME allow-list validated against SNIFFED (not merely
+ * - `allowed` — a MIME allow-list validated against sniffed (not merely
  *   declared) bytes; an empty array allows nothing. Omitted ⇒ no type
  *   rejection.
  * - `directory` — the directory staged files are written to; defaults to
@@ -589,8 +591,8 @@ export declare interface MultipartOptions {
 }
 
 /**
- * Lists the content-codings the node face's `createCompression` offers — the two
- * `node:zlib` guarantees on every Node runtime, so this face never
+ * Lists `['gzip', 'deflate']`, the content-codings the node face's `createCompression`
+ * offers — what `node:zlib` guarantees on every Node runtime, so this face never
  * feature-detects.
  */
 export declare const NODE_COMPRESSION_ENCODINGS: readonly Encoding[];
@@ -619,30 +621,30 @@ export declare interface NodeCompressionOptions {
  *
  * @remarks
  * Reads `request.body` chunk by chunk through its `ReadableStream` reader —
- * NEVER buffers the whole body — enforcing every {@link MultipartLimits} cap
+ * never buffers the whole body — enforcing every {@link MultipartLimits} cap
  * the instant it is exceeded (reading stops, every already-staged temp file
  * is deleted, throws {@link MultipartError} with code `'limit'`). Each file
  * part streams to `join(directory, randomUUID())` — the client's declared
- * filename is METADATA ONLY, never a path component. A field OR file part
+ * filename is metadata only, never a path component. A field or file part
  * named `__proto__` / `constructor` / `prototype` is silently skipped and
  * never keyed onto the returned {@link MultipartBody} (a skipped file's
  * staged temp file is unlinked immediately, since it can never be
  * referenced). A file part with an empty declared filename (`filename=""`)
- * AND a zero-byte body — the browser convention for an unselected optional
+ * and a zero-byte body — the browser convention for an unselected optional
  * `<input type="file">` — is a silent no-op: its temp file is unlinked, it is
  * never counted against the `file.count` limit, and it never runs the
  * `allowed` check. A malformed
  * structure (missing/unterminated boundary, nameless part, an oversized
  * header block, or a preamble exceeding {@link MULTIPART_MAX_PREAMBLE} before
  * the first boundary) throws with code `'malformed'`. A file is accepted
- * against the configured `allowed` MIME list iff its SNIFFED bytes detect a
+ * against the configured `allowed` MIME list exactly when its sniffed bytes detect a
  * type present in the list — sniff-authoritative, independent of whether the
  * declared `Content-Type` matches (that agreement is exposed separately as
  * `validated`); otherwise throws with code `'rejected'`. A
  * request abort mid-upload triggers the same fail-closed cleanup as a limit
  * breach. Returns `undefined` for a non-multipart request (untouched).
  *
- * Staging defaults to a process-owned directory created ONCE (lazily,
+ * Staging defaults to a process-owned directory created once (lazily,
  * memoized across calls) with `mkdtemp` under `os.tmpdir()` and locked to
  * mode `0o700`; `options.directory` overrides it.
  *
@@ -753,7 +755,7 @@ export declare function resolveMultipartLimits(limits: MultipartLimitsInput | un
  * fallback.
  *
  * @remarks
- * `GET` and `HEAD` are both eligible, and resolve the SAME shell: `HEAD` is
+ * `GET` and `HEAD` are both eligible, and resolve the same shell: `HEAD` is
  * defined as `GET` without a body (RFC 9110 §9.3.2), so a navigation probe
  * that answered `404` while its `GET` answered `200` would report a resource
  * the very next request serves.
@@ -775,14 +777,14 @@ export declare function resolveMultipartLimits(limits: MultipartLimitsInput | un
 export declare function resolveStaticFallbackPath(root: string, index: string, exclude: string, method: string, pathname: string, accept: string): string | undefined;
 
 /**
- * Resolves a request pathname to an on-disk path UNDER `root`, or `undefined`
+ * Resolves a request pathname to an on-disk path under `root`, or `undefined`
  * when it cannot — the traversal guard, whose algorithm and order are exact:
  * strip `prefix` on a segment boundary → `decodeURIComponent` (a
  * malformed escape refuses, never throws) → reject a NUL byte → strip the
- * leading path separator FIRST (so a leading `..` survives `normalize` as a
- * genuine climbing segment) → `normalize` → refuse any Windows reserved-
- * device-name segment ({@link isReservedDeviceName}) → `resolve` and require
- * the result under `root`.
+ * leading path separator first (so a leading `..` survives `normalize` as a
+ * genuine climbing segment) → `normalize` → refuse any Windows
+ * reserved-device-name segment ({@link isReservedDeviceName}) → `resolve` and
+ * require the result under `root`.
  *
  * @param root - The absolute root directory every result must resolve under
  * @param prefix - An optional URL path prefix stripped on a segment boundary
@@ -802,14 +804,14 @@ export declare function resolveStaticPath(root: string, prefix: string | undefin
  * Configures `createStatic` — node `fs`-backed static file serving.
  *
  * @remarks
- * - `root` — the directory every request resolves under, resolved once at
- *   construction. REQUIRED.
+ * - `root` — the required directory every request resolves under, resolved
+ *   once at construction.
  * - `prefix` — a URL path prefix stripped (on a segment boundary) before
  *   resolving under `root`.
  * - `index` — the filename served for a directory hit and by the SPA
  *   fallback; defaults to {@link DEFAULT_STATIC_INDEX}. The fallback serves
- *   it whatever `dotfiles` is set to, because this path is operator-
- *   configured rather than request-derived.
+ *   it whatever `dotfiles` is set to, because this path is
+ *   operator-configured rather than request-derived.
  * - `dotfiles` — the policy for a path with a dotfile segment: `'ignore'`
  *   (falls through to `next()`), `'deny'` (403), or `'allow'` (serves it);
  *   defaults to {@link DEFAULT_STATIC_DOTFILES}.
@@ -818,7 +820,7 @@ export declare function resolveStaticPath(root: string, prefix: string | undefin
  * - `fallback` — SPA fallback: `false` (default, off), `true` (on, excluding
  *   {@link DEFAULT_STATIC_FALLBACK_EXCLUDE}), or `{ exclude }` for a custom
  *   excluded prefix. An eligible `GET` or `HEAD` navigation miss answers with
- *   `index` through the SAME handle-`fstat` header block a directly requested
+ *   `index` through the same handle-`fstat` header block a directly requested
  *   file answers through, so `cache`, `etag`, conditional revalidation,
  *   `HEAD`, and ranges are identical on both routes; `index` reaches the
  *   client through this route whatever `dotfiles` is set to.
@@ -842,7 +844,7 @@ export declare interface StaticOptions {
  * response body routes through.
  *
  * @remarks
- * PULL-driven, not push-driven: the underlying node stream's async iterator
+ * Pull-driven, not push-driven: the underlying node stream's async iterator
  * is only advanced (`iterator.next()`) from inside `pull(controller)`, which
  * the web `ReadableStream` invokes exactly when its internal queue has room
  * for more data. Exactly one disk chunk is read and enqueued per `pull` —
@@ -911,13 +913,13 @@ export declare function unlinkStagedFiles(body: MultipartBody): Promise<void>;
  *
  * @remarks
  * - `field` — the multipart field name the file was submitted under.
- * - `name` — the client-declared filename (METADATA ONLY — never used to
+ * - `name` — the client-declared filename (metadata only — never used to
  *   build a filesystem path).
  * - `size` — the file's byte size.
- * - `mime` — the SNIFFED (magic-byte-detected) MIME type when a signature
+ * - `mime` — the sniffed (magic-byte-detected) MIME type when a signature
  *   matches; otherwise the part's declared `Content-Type`; otherwise
  *   {@link DEFAULT_CONTENT_TYPE}. Read `validated` to tell which.
- * - `validated` — `true` when a signature matched AND the sniffed type equals
+ * - `validated` — `true` when a signature matched and the sniffed type equals
  *   the declared `Content-Type`, so `mime` is the sniffed fact. `false` means
  *   `mime` may be the client-declared value.
  * - `status` — see {@link UploadStatus}.

package/dist/src/server/index.js

@@ -9,7 +9,10 @@ import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 import { DEFAULT_COMPRESSION_THRESHOLD, compressResponse } from "../core/index.js";
 //#region src/server/constants.ts
-/** Holds the HTTP status `createMultipart` renders for each {@link MultipartErrorCode}. */
+/**
+* Holds the HTTP status `createMultipart` renders for each {@link MultipartErrorCode}:
+* `'limit'` is 413, `'malformed'` is 400, and `'rejected'` is 415.
+*/
 var MULTIPART_STATUS = Object.freeze({
 	limit: 413,
 	malformed: 400,
@@ -22,33 +25,33 @@ var MULTIPART_STATUS = Object.freeze({
 * which would mint an unequal symbol per copy.
 */
 var MULTIPART_ERROR_BRAND = Symbol.for("@orkestrel/middleware.MultipartError");
-/** Names `createStatic`'s default directory-index filename. */
+/** Names `'index.html'`, `createStatic`'s default directory-index filename. */
 var DEFAULT_STATIC_INDEX = "index.html";
-/** Names `createStatic`'s `fallback: true` default excluded path prefix. */
+/** Names `'/api'`, `createStatic`'s `fallback: true` default excluded path prefix. */
 var DEFAULT_STATIC_FALLBACK_EXCLUDE = "/api";
-/** Names `createStatic`'s default policy for a path carrying a dotfile segment. */
+/** Names `'ignore'`, `createStatic`'s default policy for a path carrying a dotfile segment. */
 var DEFAULT_STATIC_DOTFILES = "ignore";
 /**
-* Lists the content-codings the node face's `createCompression` offers — the two
-* `node:zlib` guarantees on every Node runtime, so this face never
+* Lists `['gzip', 'deflate']`, the content-codings the node face's `createCompression`
+* offers — what `node:zlib` guarantees on every Node runtime, so this face never
 * feature-detects.
 */
 var NODE_COMPRESSION_ENCODINGS = Object.freeze(["gzip", "deflate"]);
-/** Names the MIME type served when a file extension has no known mapping. */
+/** Names `'application/octet-stream'`, the MIME type served when a file extension has no known mapping. */
 var DEFAULT_CONTENT_TYPE = "application/octet-stream";
-/** Holds `createMultipart`'s default per-file byte-size cap. */
+/** Holds `10_485_760`, `createMultipart`'s default per-file byte-size cap. */
 var DEFAULT_MULTIPART_FILE_SIZE = 10485760;
-/** Holds `createMultipart`'s default maximum file-part count. */
+/** Holds `10`, `createMultipart`'s default maximum file-part count. */
 var DEFAULT_MULTIPART_FILE_COUNT = 10;
-/** Holds `createMultipart`'s default per-field byte-size cap. */
+/** Holds `65_536`, `createMultipart`'s default per-field byte-size cap. */
 var DEFAULT_MULTIPART_FIELD_SIZE = 65536;
-/** Holds `createMultipart`'s default maximum field-part count. */
+/** Holds `100`, `createMultipart`'s default maximum field-part count. */
 var DEFAULT_MULTIPART_FIELD_COUNT = 100;
-/** Holds `createMultipart`'s default combined request-body byte-size cap. */
+/** Holds `52_428_800`, `createMultipart`'s default combined request-body byte-size cap. */
 var DEFAULT_MULTIPART_TOTAL = 52428800;
-/** Holds the maximum bytes a single multipart part's header block may occupy before it is malformed. */
+/** Holds `16_384`, the maximum bytes a single multipart part's header block may occupy before it is malformed. */
 var MULTIPART_MAX_HEADER_BLOCK = 16384;
-/** Holds the maximum bytes scanned before the first multipart boundary is found before it is malformed. */
+/** Holds `65_536`, the maximum bytes scanned before the first multipart boundary is found before it is malformed. */
 var MULTIPART_MAX_PREAMBLE = 65536;
 /**
 * Lists the Windows reserved device-name stems (CVE-2025-27210) — matched
@@ -167,7 +170,7 @@ function isMultipartError(value) {
 //#endregion
 //#region src/server/helpers.ts
 /**
-* Checks whether `pathname` is `prefix` itself or lies under it on a SEGMENT
+* Checks whether `pathname` is `prefix` itself or lies under it on a segment
 * boundary — the shared under-path test `resolveStaticPath`'s prefix strip
 * and `createStatic`'s SPA-fallback `exclude` both apply, so `exclude:
 * '/api'` matches `/api` and `/api/x` but never `/apifoo`.
@@ -192,7 +195,7 @@ function isUnderPath(pathname, prefix) {
 * fallback.
 *
 * @remarks
-* `GET` and `HEAD` are both eligible, and resolve the SAME shell: `HEAD` is
+* `GET` and `HEAD` are both eligible, and resolve the same shell: `HEAD` is
 * defined as `GET` without a body (RFC 9110 §9.3.2), so a navigation probe
 * that answered `404` while its `GET` answered `200` would report a resource
 * the very next request serves.
@@ -220,11 +223,11 @@ function resolveStaticFallbackPath(root, index, exclude, method, pathname, accep
 }
 /**
 * Checks whether `child` is `parent` itself or lies inside it on-disk — the
-* FILESYSTEM containment predicate `createStatic` applies to `fs.realpath`
+* filesystem containment predicate `createStatic` applies to `fs.realpath`
 * output (never to a URL pathname — that is {@link isUnderPath}'s job).
 *
 * @remarks
-* Argument order is `(child, parent)` — deliberately the OPPOSITE conceptual
+* Argument order is `(child, parent)` — deliberately the opposite conceptual
 * order from {@link isUnderPath}`(pathname, prefix)`, so a call site cannot
 * casually swap one predicate in for the other. Built on `path.relative`,
 * this is separator-correct on both POSIX (`/`) and win32 (`\`) — unlike a
@@ -247,14 +250,14 @@ function isContainedPath(child, parent) {
 	return rel.length > 0 && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
 }
 /**
-* Resolves a request pathname to an on-disk path UNDER `root`, or `undefined`
+* Resolves a request pathname to an on-disk path under `root`, or `undefined`
 * when it cannot — the traversal guard, whose algorithm and order are exact:
 * strip `prefix` on a segment boundary → `decodeURIComponent` (a
 * malformed escape refuses, never throws) → reject a NUL byte → strip the
-* leading path separator FIRST (so a leading `..` survives `normalize` as a
-* genuine climbing segment) → `normalize` → refuse any Windows reserved-
-* device-name segment ({@link isReservedDeviceName}) → `resolve` and require
-* the result under `root`.
+* leading path separator first (so a leading `..` survives `normalize` as a
+* genuine climbing segment) → `normalize` → refuse any Windows
+* reserved-device-name segment ({@link isReservedDeviceName}) → `resolve` and
+* require the result under `root`.
 *
 * @param root - The absolute root directory every result must resolve under
 * @param prefix - An optional URL path prefix stripped on a segment boundary
@@ -323,7 +326,7 @@ async function resolveContainedRealPath(candidate, rootReal) {
 *
 * @remarks
 * Normalizes superscript digits (`¹²³` → `123`) first, strips trailing dots
-* and spaces (Windows drops them), takes the STEM before the first `.`,
+* and spaces (Windows drops them), takes the stem before the first `.`,
 * upper-cases it, and tests it against {@link RESERVED_DEVICE_NAMES}
 * (`CON PRN AUX NUL COM1-9 LPT1-9`) — an exact-stem match only, so
 * `console.js` and `nullable.css` are never flagged.
@@ -642,7 +645,7 @@ async function unlinkStagedFiles(body) {
 * response body routes through.
 *
 * @remarks
-* PULL-driven, not push-driven: the underlying node stream's async iterator
+* Pull-driven, not push-driven: the underlying node stream's async iterator
 * is only advanced (`iterator.next()`) from inside `pull(controller)`, which
 * the web `ReadableStream` invokes exactly when its internal queue has room
 * for more data. Exactly one disk chunk is read and enqueued per `pull` —
@@ -979,30 +982,30 @@ var MultipartParser = class MultipartParser {
 *
 * @remarks
 * Reads `request.body` chunk by chunk through its `ReadableStream` reader —
-* NEVER buffers the whole body — enforcing every {@link MultipartLimits} cap
+* never buffers the whole body — enforcing every {@link MultipartLimits} cap
 * the instant it is exceeded (reading stops, every already-staged temp file
 * is deleted, throws {@link MultipartError} with code `'limit'`). Each file
 * part streams to `join(directory, randomUUID())` — the client's declared
-* filename is METADATA ONLY, never a path component. A field OR file part
+* filename is metadata only, never a path component. A field or file part
 * named `__proto__` / `constructor` / `prototype` is silently skipped and
 * never keyed onto the returned {@link MultipartBody} (a skipped file's
 * staged temp file is unlinked immediately, since it can never be
 * referenced). A file part with an empty declared filename (`filename=""`)
-* AND a zero-byte body — the browser convention for an unselected optional
+* and a zero-byte body — the browser convention for an unselected optional
 * `<input type="file">` — is a silent no-op: its temp file is unlinked, it is
 * never counted against the `file.count` limit, and it never runs the
 * `allowed` check. A malformed
 * structure (missing/unterminated boundary, nameless part, an oversized
 * header block, or a preamble exceeding {@link MULTIPART_MAX_PREAMBLE} before
 * the first boundary) throws with code `'malformed'`. A file is accepted
-* against the configured `allowed` MIME list iff its SNIFFED bytes detect a
+* against the configured `allowed` MIME list exactly when its sniffed bytes detect a
 * type present in the list — sniff-authoritative, independent of whether the
 * declared `Content-Type` matches (that agreement is exposed separately as
 * `validated`); otherwise throws with code `'rejected'`. A
 * request abort mid-upload triggers the same fail-closed cleanup as a limit
 * breach. Returns `undefined` for a non-multipart request (untouched).
 *
-* Staging defaults to a process-owned directory created ONCE (lazily,
+* Staging defaults to a process-owned directory created once (lazily,
 * memoized across calls) with `mkdtemp` under `os.tmpdir()` and locked to
 * mode `0o700`; `options.directory` overrides it.
 *
@@ -1123,16 +1126,16 @@ function createAssets(options) {
 	};
 }
 /**
-* Serves static files from `options.root` over `node:fs` — the node-bound
-* static-file battery.
+* Serves static files from `options.root` over `node:fs` — the node-bound static-file
+* battery, answering conditional, ranged, and SPA-fallback requests.
 *
 * @remarks
-* Containment is enforced on CANONICAL paths, not merely the lexically
+* Containment is enforced on canonical paths, not merely the lexically
 * resolved one: `options.root` is canonicalized once (memoized) and every
 * request's candidate path is re-canonicalized (`fs.realpath`) before it is
 * served, so a symlink whose target escapes `root` is refused (falls through
 * to `next()`) even though the lexical path resolved inside `root`. A
-* symlink that resolves to a target still INSIDE `root` is unaffected and
+* symlink that resolves to a target still inside `root` is unaffected and
 * still serves normally. A dangling symlink (`realpath` throws `ENOENT`) or
 * any other `realpath` failure is treated as a miss — this battery never
 * throws or 500s on a symlink surprise. On a streamed response (a 200 or 206
@@ -1328,7 +1331,7 @@ function createStatic(options) {
 * {@link MultipartError} this battery's parser throws is re-thrown as an
 * {@link HTTPError} carrying the same status/message, so `createBoundary`
 * (or any HTTPError-aware renderer) maps it correctly without depending on
-* this node face's error type. Fail-closed on the DOWNSTREAM handler too: if
+* this node face's error type. Fail-closed on the downstream handler too: if
 * `next()` throws, every still-`'staged'` uploaded file is unlinked
 * (best-effort) before the error is re-thrown, so an unhandled downstream
 * failure never leaks temp files. A normal return leaves staged files
@@ -1367,12 +1370,11 @@ function createMultipart(options = {}) {
 	};
 }
 /**
-* Compresses response bodies through `node:zlib` — the node-bound sibling of
-* the core face's `CompressionStream`-feature-detected `createCompression`,
-* guaranteed available on any Node runtime rather than dependent on the
-* WHATWG `CompressionStream` global. Ships as a SEPARATE package entry point
-* (`@orkestrel/middleware/server`) from the core face's `createCompression`,
-* so the shared name is unambiguous per consumer import path.
+* Compresses response bodies through `node:zlib`, guaranteed on any Node runtime rather
+* than dependent on the WHATWG `CompressionStream` global. This battery is the
+* node-bound sibling of the core face's feature-detected `createCompression`, and it
+* ships from a separate package entry point (`@orkestrel/middleware/server`) so the
+* shared name is unambiguous per consumer import path.
 *
 * @remarks
 * Peer-type limitation, the same one the core face carries: the shipped