@orkestrel/router 0.0.12 → 0.0.14

package/dist/src/core/index.js

@@ -1,24 +1,26 @@
+import { ContractError, isFunction, isString, preview } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
-import { isFunction, isString } from "@orkestrel/contract";
 //#region src/core/constants.ts
 /**
-* The complete set of HTTP methods a {@link import('./types.js').Dispatcher}
-* registers routes under — backs the registration guard (`add` rejects any
-* `method` outside this set) and the auto-`OPTIONS` `Allow` derivation.
+* Lists the HTTP methods a {@link import('./types.js').DispatcherInterface} registers
+* routes under, in canonical order — a frozen literal tuple, and the single source the
+* {@link import('./types.js').Method} type, {@link METHODS}, and `parseMethod` are all
+* derived from.
 *
 * @remarks
-* A `ReadonlySet` of the seven {@link import('./types.js').Method} literals:
-* `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`. `HEAD` is
-* included even though it is never required at registration (a `GET` route
-* auto-answers `HEAD`) — it is still a valid method to register explicitly.
+* A frozen tuple of the verbs: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`,
+* `HEAD`, `OPTIONS`. Adding a verb here widens the `Method` type, the
+* {@link METHODS} membership set, and the `parseMethod` narrowing together, so
+* the method set cannot drift between them. Prefer {@link METHODS} for a
+* membership test; use this tuple where order or literal typing matters.
 *
 * @example
 * ```ts
-* METHODS.has('GET') // true
-* METHODS.has('TRACE') // false
+* METHOD_LIST[0] // 'GET'
+* METHOD_LIST.includes('GET') // true
 * ```
 */
-var METHODS = Object.freeze(/* @__PURE__ */ new Set([
+var METHOD_LIST = Object.freeze([
 	"GET",
 	"POST",
 	"PUT",
@@ -26,14 +28,34 @@ var METHODS = Object.freeze(/* @__PURE__ */ new Set([
 	"DELETE",
 	"HEAD",
 	"OPTIONS"
-]));
+]);
 /**
-* Specificity tier for a **literal** path segment (`/users`) — the highest
+* Holds every HTTP method a {@link import('./types.js').DispatcherInterface} registers
+* routes under as a `ReadonlySet` — backs the registration guard (`add` rejects any
+* `method` outside this set) and the auto-`OPTIONS` `Allow` derivation.
+*
+* @remarks
+* A `ReadonlySet` built from {@link METHOD_LIST}, so it carries exactly the
+* {@link import('./types.js').Method} literals: `GET`, `POST`, `PUT`,
+* `PATCH`, `DELETE`, `HEAD`, `OPTIONS`. `HEAD` is included even though it is
+* never required at registration (a `GET` route auto-answers `HEAD`) — it is
+* still a valid method to register explicitly. The element type stays `string`
+* so a raw, unnarrowed `request.method` can be tested directly.
+*
+* @example
+* ```ts
+* METHODS.has('GET') // true
+* METHODS.has('TRACE') // false
+* ```
+*/
+var METHODS = Object.freeze(new Set(METHOD_LIST));
+/**
+* Names the specificity tier for a **literal** path segment (`/users`) — the highest
 * tier, always outranking a param or wildcard segment at the same position.
 *
 * @remarks
-* Consumed by `computeSpecificity` (U1 `helpers.ts`) when ranking candidate
-* matches left-to-right at the earliest differing segment (§4 precedence).
+* Consumed by `computeSpecificity` (the path compiler in `helpers.ts`) when ranking candidate
+* matches left-to-right at the earliest differing segment.
 *
 * @example
 * ```ts
@@ -42,11 +64,11 @@ var METHODS = Object.freeze(/* @__PURE__ */ new Set([
 */
 var TIER_LITERAL = 2;
 /**
-* Specificity tier for a **param** path segment (`:name`) — ranks below a
+* Names the specificity tier for a **param** path segment (`:name`) — ranks below a
 * literal segment and above a wildcard segment at the same position.
 *
 * @remarks
-* Consumed by `computeSpecificity` (U1 `helpers.ts`) alongside {@link TIER_LITERAL}
+* Consumed by `computeSpecificity` (the path compiler in `helpers.ts`) alongside {@link TIER_LITERAL}
 * and {@link TIER_WILDCARD}.
 *
 * @example
@@ -56,12 +78,12 @@ var TIER_LITERAL = 2;
 */
 var TIER_PARAM = 1;
 /**
-* Specificity tier for a **wildcard** path segment (`*name`) — the lowest
+* Names the specificity tier for a **wildcard** path segment (`*name`) — the lowest
 * tier; a wildcard only ever wins against another wildcard shape (an
 * equal-specificity tie resolved by registration order).
 *
 * @remarks
-* Consumed by `computeSpecificity` (U1 `helpers.ts`).
+* Consumed by `computeSpecificity` (the path compiler in `helpers.ts`).
 *
 * @example
 * ```ts
@@ -72,7 +94,7 @@ var TIER_WILDCARD = 0;
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Escape every regex metacharacter in a literal string so it can be embedded
+* Escapes every regex metacharacter in a literal string so it can be embedded
 * inside a larger `RegExp` source without being interpreted as syntax.
 *
 * @remarks
@@ -95,7 +117,7 @@ function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 /**
-* Canonicalize a route path for REGISTRY IDENTITY — strip a single trailing
+* Canonicalizes a route path for registry identity — strips a single trailing
 * slash, except the root `/` (and the empty pattern). The trailing-slash fold
 * {@link compilePath} normalizes a pattern through, so identity agrees with the
 * matcher.
@@ -122,7 +144,8 @@ function canonicalizePath(path) {
 	return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
 }
 /**
-* Compute the registry key for a method-dimensioned dispatcher route.
+* Computes the canonical `METHOD /path` registry key for a method-dimensioned
+* dispatcher route.
 *
 * @remarks
 * Combines the route record's HTTP method with the outer entry's canonical
@@ -141,7 +164,7 @@ function computeDispatchKey(entry) {
 	return `${entry.meta.method} ${canonicalizePath(entry.path)}`;
 }
 /**
-* Compile a route path pattern into an anchored regex and its ordered param
+* Compiles a route path pattern into an anchored regex and its ordered param
 * names.
 *
 * @remarks
@@ -149,7 +172,7 @@ function computeDispatchKey(entry) {
 * `([^/]+)` capture group; the FINAL segment may instead be `*name`, which
 * becomes a `(.+)` capture spanning the REST of the path including slashes — a
 * wildcard segment anywhere but last is a registration-time programmer error
-* and throws `TypeError` (§14 construction/registration boundary). Every regex
+* and throws a `ContractError` at the construction/registration boundary. Every regex
 * metacharacter in a literal segment is escaped first ({@link escapeRegExp}),
 * so a path like `/files/:name.json` matches the `.` literally apart from the
 * param. The regex is anchored (`^…$`), so it matches the whole pathname, not
@@ -167,10 +190,12 @@ function computeDispatchKey(entry) {
 * regex flag, so `/Users` matches `/users`. The pattern's own casing is never
 * altered — only the matching behavior.
 *
-* @param path - The route path pattern (e.g. `/users/:id`, `/files/*rest`)
-* @param sensitive - Case-sensitive matching (default `true`)
+* @param path - The route path pattern (for example `/users/:id`, `/files/*rest`)
+* @param sensitive - If `true`, matching is case-sensitive; if `false`, case is
+*   folded during matching. Default: `true`
 * @returns The {@link CompiledPath} — its `regex` + ordered `params`
-* @throws {TypeError} When a `*name` wildcard segment is not the FINAL segment
+* @throws {@link import('@orkestrel/contract').ContractError} Thrown when a
+*   `*name` wildcard segment is not the FINAL segment
 *
 * @example
 * ```ts
@@ -189,7 +214,14 @@ function compilePath(path, sensitive = true) {
 	const segments = normalized.split("/");
 	const pattern = segments.map((segment, index) => {
 		const isFinal = index === segments.length - 1;
-		if (!isFinal && /^\*[A-Za-z_]\w*/.test(segment)) throw new TypeError(`a wildcard segment ("${segment}") must be the final segment of a path pattern, got "${path}"`);
+		if (!isFinal && /^\*[A-Za-z_]\w*/.test(segment)) throw new ContractError("a wildcard segment must be the final segment of a path pattern", {
+			code: "placement",
+			context: {
+				path: ["path"],
+				limit: `a wildcard only in the final segment, not "${segment}"`,
+				received: preview(path)
+			}
+		});
 		const tier = classifySegment(segment, isFinal);
 		if (tier === 0) {
 			params.push(segment.slice(1));
@@ -210,13 +242,13 @@ function compilePath(path, sensitive = true) {
 	};
 }
 /**
-* URL-decode one captured param value, tolerating a malformed percent-escape —
+* Decodes one captured param value from a URL, tolerating a malformed percent-escape —
 * the decode {@link matchPath} applies to each captured group.
 *
 * @remarks
 * A bad `%` sequence is not a reason to reject an otherwise-matching route, so
 * a `decodeURIComponent` that would throw falls back to the raw value
-* (mirroring the cookie / token boundary readers, AGENTS §14). Total — never
+* (mirroring the cookie / token boundary readers). Total — never
 * throws.
 *
 * @param value - The raw captured param value
@@ -237,7 +269,7 @@ function decodeParam(value) {
 	}
 }
 /**
-* Extract the URL-decoded params a compiled path captures from a concrete
+* Extracts the URL-decoded params a compiled path captures from a concrete
 * pathname, or `undefined` when the pathname does not match.
 *
 * @remarks
@@ -248,7 +280,7 @@ function decodeParam(value) {
 * for a parameterless path). Total — never throws.
 *
 * @param compiled - The {@link CompiledPath} from {@link compilePath}
-* @param pathname - The concrete request pathname to match (e.g. `/users/7`)
+* @param pathname - The concrete request pathname to match (for example `/users/7`)
 * @returns The decoded params on a hit, or `undefined` on a miss
 *
 * @example
@@ -271,22 +303,23 @@ function matchPath(compiled, pathname) {
 	return Object.freeze(params);
 }
 /**
-* Classify one path segment into its specificity TIER — the SAME syntax
-* {@link compilePath} rewrites: a syntactically valid `:name` head is a PARAM
-* segment, a final `*name` is a WILDCARD segment, everything else (including a
-* literal segment that merely CONTAINS a `:` mid-string, e.g. `a:b`) is a
-* LITERAL segment.
+* Classifies one path segment into its specificity tier — the same syntax
+* {@link compilePath} rewrites: a syntactically valid `:name` head is a param
+* segment, a final `*name` is a wildcard segment, and everything else (including a
+* literal segment that merely contains a `:` mid-string, for example `a:b`) is a
+* literal segment.
 *
 * @remarks
 * This is the fix over the old engine's bug: the old classifier ranked any
 * segment `includes(':')` as a param, so a literal segment like `a:b` was
 * mis-tiered even though {@link compilePath} compiles it literally. Sharing one
 * segment parser between compilation and classification keeps the two in
-* agreement (§4 fixes). Pure and total.
+* agreement. Pure and total.
 *
 * @param segment - One `/`-split path segment
-* @param isFinal - Whether `segment` is the last segment of its path (only the
-*   final segment may be classified as a wildcard)
+* @param isFinal - If `true`, `segment` is the path's last segment and may
+*   classify as a wildcard; if `false`, a wildcard-shaped segment classifies as
+*   a literal
 * @returns The segment's specificity tier — {@link import('./constants.js').TIER_LITERAL},
 *   {@link import('./constants.js').TIER_PARAM}, or
 *   {@link import('./constants.js').TIER_WILDCARD}
@@ -305,15 +338,15 @@ function classifySegment(segment, isFinal) {
 	return 2;
 }
 /**
-* Compute a route path's SPECIFICITY VECTOR — the per-segment type ranking
+* Computes a route path's specificity vector — the per-segment type ranking
 * that breaks a tie when several registered routes match the same concrete
 * pathname.
 *
 * @remarks
 * Splits the CANONICALIZED path into segments (on `/`) and maps each to its
-* specificity tier via {@link classifySegment} — the same segment parser
+* specificity tier through {@link classifySegment} — the same segment parser
 * {@link compilePath} uses, so a literal segment that merely contains a `:`
-* (e.g. `a:b`) is correctly tiered as literal rather than param (the old
+* (for example `a:b`) is correctly tiered as literal rather than param (the old
 * engine's bug, fixed here). The standard route-precedence rule compares two
 * matching routes' vectors LEFT-TO-RIGHT: at the first index where the tiers
 * differ, the HIGHER tier (a literal over a param over a wildcard) is MORE
@@ -323,7 +356,7 @@ function classifySegment(segment, isFinal) {
 * count in the common case; {@link compareSpecificity} handles the general
 * case for totality.
 *
-* @param path - The route path pattern (e.g. `/users/:id`)
+* @param path - The route path pattern (for example `/users/:id`)
 * @returns The per-segment specificity tiers, in order
 *
 * @example
@@ -339,7 +372,7 @@ function computeSpecificity(path) {
 	return segments.map((segment, index) => classifySegment(segment, index === segments.length - 1));
 }
 /**
-* Compare two route paths by SPECIFICITY — the comparator that picks the
+* Compares two route paths by specificity — the comparator that picks the
 * most-specific matching route (literal-over-param-over-wildcard,
 * registration-order-independent).
 *
@@ -376,45 +409,20 @@ function compareSpecificity(a, b) {
 	return 0;
 }
 /**
-* Narrow a raw `request.method` string into a typed {@link Method} — total,
-* never throws.
-*
-* @remarks
-* Guarded via {@link import('./constants.js').METHODS} (the seven registrable
-* HTTP methods); any other value (an unknown verb, non-uppercase casing)
-* resolves to `undefined` rather than throwing (§14 guard totality). Pure
-* leaf shared by the `Dispatcher`'s `handle` (§5.1 unknown-verb honesty) and
-* anywhere else a raw method string needs narrowing.
-*
-* @param value - The raw `request.method` string to narrow
-* @returns The matching {@link Method}, or `undefined` when `value` is not one
-*   of the seven registrable methods
-*
-* @example
-* ```ts
-* parseMethod('GET') // 'GET'
-* parseMethod('PURGE') // undefined
-* parseMethod('get') // undefined — case-sensitive
-* ```
-*/
-function parseMethod(value) {
-	if (value === "GET" || value === "POST" || value === "PUT" || value === "PATCH" || value === "DELETE" || value === "HEAD" || value === "OPTIONS") return value;
-}
-/**
-* Join a group prefix and a route path into one `/`-prefixed path, normalizing
+* Joins a group prefix and a route path into one `/`-prefixed path, normalizing
 * duplicate or missing joining slashes.
 *
 * @remarks
 * {@link import('./types.js').GroupInterface} / {@link import('./types.js').DispatchGroupInterface}
 * compose a prefix with each registered entry's path this way — pure string
-* composition (§4.2.2), no independent state. Both a duplicated slash
+* composition, no independent state. Both a duplicated slash
 * (`'/api/'` + `'/users'`) and a missing one (`'/api'` + `'users'`) normalize
 * to a single joining slash. An empty `prefix` returns `path` unchanged (after
 * ensuring a leading slash); an empty `path` returns `prefix` unchanged.
 * Pure and total.
 *
-* @param prefix - The group prefix (e.g. `/api`)
-* @param path - The route path being joined under the prefix (e.g. `/users`)
+* @param prefix - The group prefix (for example `/api`)
+* @param path - The route path being joined under the prefix (for example `/users`)
 * @returns The joined `/`-prefixed path
 *
 * @example
@@ -432,8 +440,8 @@ function joinPaths(prefix, path) {
 	return `${prefix.endsWith("/") ? prefix.slice(0, -1) : prefix}${path.startsWith("/") ? path : `/${path}`}`;
 }
 /**
-* Identity pass-through for a {@link RouteInput} that pins its `Path` generic
-* to the LITERAL registration-site string, so `context.params` types
+* Provides an identity pass-through for a {@link RouteInput} that pins its `Path`
+* generic to the literal registration-site string, so `context.params` types
 * correctly through {@link PathParams} without an explicit type argument.
 *
 * @remarks
@@ -441,26 +449,26 @@ function joinPaths(prefix, path) {
 * `add` already infers `Path` as a literal at that call site — but the moment
 * the object is built through an intermediate binding (a local `const route =
 * { method, path, handler }`) TypeScript widens `path` to `string` unless the
-* binding's own type is pinned. Wrapping the literal in `route(...)` supplies
-* that pin: its `const Path extends string` type parameter infers the NARROW
-* literal from the call, and the function returns its input completely
+* binding's own type is pinned. Wrapping the literal in `defineRoute(...)`
+* supplies that pin: its `const Path extends string` type parameter infers the
+* NARROW literal from the call, and the function returns its input completely
 * unchanged (same reference, no cloning, no validation) — this is a
 * compile-time typing aid only, not a construction step (contrast
 * {@link import('./factories.js')} `create*` entity factories). A
-* heterogeneous `RouteInput[]` built from several `route(...)` calls still
-* widens each element's `Path` to `string` once collected into one array
-* (§14) — the realistic ceiling this helper raises is PER-CALL typing at the
+* heterogeneous `RouteInput[]` built from several `defineRoute(...)` calls
+* still widens each element's `Path` to `string` after collection into one array —
+* the realistic ceiling this helper raises is PER-CALL typing at the
 * registration site, not a stored, still-literal-typed record.
 *
 * @typeParam Path - The route path pattern literal (drives `context.params`
-*   via {@link PathParams})
+*   through {@link PathParams})
 * @typeParam TState - The consumer's opaque per-request state type
 * @param input - The {@link RouteInput} to pass through unchanged
 * @returns `input`, unchanged (same reference)
 *
 * @example
 * ```ts
-* const input = route({
+* const input = defineRoute({
 * 	method: 'GET',
 * 	path: '/users/:id',
 * 	handler: (_request, context) => new Response(context.params.id), // typed string
@@ -468,21 +476,49 @@ function joinPaths(prefix, path) {
 * dispatcher.add(input)
 * ```
 */
-function route(input) {
+function defineRoute(input) {
 	return input;
 }
 //#endregion
+//#region src/core/parsers.ts
+/**
+* Narrows a raw `request.method` string into a typed {@link Method} — total,
+* never throws.
+*
+* @remarks
+* Consults {@link import('./constants.js').METHOD_LIST} (the one home for the
+* registrable HTTP methods), so a verb added there narrows here without
+* a second list to update; any other value (an unknown verb, non-uppercase
+* casing) resolves to `undefined` rather than throwing (total guard behavior).
+* Pure leaf shared by the `Dispatcher`'s `handle` (honest about an unknown verb)
+* and anywhere else a raw method string needs narrowing.
+*
+* @param value - The raw `request.method` string to narrow
+* @returns The matching {@link Method}, or `undefined` when `value` is not a
+*   registrable method
+*
+* @example
+* ```ts
+* parseMethod('GET') // 'GET'
+* parseMethod('PURGE') // undefined
+* parseMethod('get') // undefined — case-sensitive
+* ```
+*/
+function parseMethod(value) {
+	return METHOD_LIST.find((method) => method === value);
+}
+//#endregion
 //#region src/core/Group.ts
 /**
-* A prefix-scoped registration handle over a {@link import('./Router.js').Router} —
-* pure string composition (AGENTS §4.2.2), no independent state or storage.
+* Represents a prefix-scoped registration handle over a {@link import('./Router.js').Router} —
+* pure string composition, no independent state or storage.
 *
 * @typeParam Meta - The entry payload type, matching the owning router
 *
 * @remarks
 * Every `add` composes `entry.path` as `joinPaths(prefix, entry.path)` and
 * forwards to the OWNING router, so grouped routes land in the SAME registry.
-* `group(prefix)` nests, composing prefixes via {@link joinPaths}.
+* `group(prefix)` nests, composing prefixes through {@link joinPaths}.
 *
 * @example
 * ```ts
@@ -515,26 +551,26 @@ var Group = class Group {
 //#endregion
 //#region src/core/Router.ts
 /**
-* The path-matching + registry engine — registers `{ path, meta, name? }`
-* entries (compiling each path once) and resolves a concrete pathname to the
-* MOST SPECIFIC matching entry. The shared machine both the `Navigator`
-* (browser) and the `Dispatcher` (core, method-dimensioned) compose.
+* Represents the path-matching + registry engine — registers `{ path, meta, name? }`
+* entries (compiling each path once) and resolves a concrete pathname to the most
+* specific matching entry. The shared machine both the `Navigator` (browser) and
+* the `Dispatcher` (core, method-dimensioned) compose.
 *
 * @typeParam Meta - The opaque payload each entry carries and a match returns
 *
 * @remarks
-* - **Registration boundary guard (§14).** `add` validates each entry's
-*   `path` — `isString` plus a leading `/` — and throws `TypeError` on a
+* - **Registration boundary guard.** `add` validates each entry's
+*   `path` — `isString` plus a leading `/` — and throws a `ContractError` on a
 *   malformed registration; `match` stays guard-free (the hot path).
 * - **Compile-once.** Each path is compiled exactly once at registration into
 *   a parallel `#compiled` array, so `match` runs only a cached `exec` per
 *   candidate.
-* - **Dedup via `key`.** When `options.key` is set, an entry whose computed
+* - **Dedup through `key`.** When `options.key` is set, an entry whose computed
 *   key already exists REPLACES the prior one IN PLACE (both the `#entries`
 *   and `#compiled` arrays, at the existing index) — last write wins, no
 *   engine rebuild. Omitted ⇒ every entry is kept, even duplicate paths.
 * - **Groups.** `group(prefix)` returns a {@link GroupInterface} that composes
-*   `prefix` onto every entry it registers, nesting via {@link joinPaths}.
+*   `prefix` onto every entry it registers, nesting through {@link joinPaths}.
 *
 * @example
 * ```ts
@@ -603,7 +639,22 @@ var Router = class {
 		this.#index.clear();
 	}
 	#register(entry) {
-		if (!isString(entry.path) || !entry.path.startsWith("/")) throw new TypeError(`a route path must be a string starting with "/", got ${JSON.stringify(entry.path)}`);
+		if (!isString(entry.path)) throw new ContractError("a route path must be a string", {
+			code: "literal",
+			context: {
+				path: ["entry", "path"],
+				limit: "string",
+				received: preview(entry.path)
+			}
+		});
+		if (!entry.path.startsWith("/")) throw new ContractError("a route path must start with \"/\"", {
+			code: "pattern",
+			context: {
+				path: ["entry", "path"],
+				limit: "a \"/\"-prefixed path pattern",
+				received: preview(entry.path)
+			}
+		});
 		const compiled = compilePath(entry.path, this.#sensitive);
 		if (this.#key === void 0) {
 			this.#entries.push(entry);
@@ -625,17 +676,17 @@ var Router = class {
 //#endregion
 //#region src/core/DispatchGroup.ts
 /**
-* A prefix-scoped registration handle over a
-* {@link import('./Dispatcher.js').Dispatcher} — the method-dimensioned
-* counterpart of `Group` (`Group.ts`).
+* Represents a prefix-scoped registration handle over a
+* {@link import('./Dispatcher.js').Dispatcher} — the method-dimensioned counterpart of
+* `Group`.
 *
 * @typeParam TState - The consumer's opaque per-request state type, matching
 *   the owning dispatcher
 *
 * @remarks
-* Every `add` composes `input.path` via {@link joinPaths} against
-* `this.prefix` and forwards to the OWNING dispatcher's `add` (its own §14
-* boundary guard still applies). Pure string composition (§4.2.2) — no
+* Every `add` composes `input.path` through {@link joinPaths} against
+* `this.prefix` and forwards to the OWNING dispatcher's `add` (its own
+* registration boundary guard still applies). Pure string composition — no
 * independent state or storage.
 *
 * @example
@@ -668,20 +719,20 @@ var DispatchGroup = class DispatchGroup {
 //#endregion
 //#region src/core/Dispatcher.ts
 /**
-* The fetch-standard, method-dimensioned dispatch entity — layers HTTP method
-* dispatch and web-standard `Request`/`Response` handling over one internal
-* `Router<RouteRecord<TState>>`. The core machine the eventual server face
-* (§7) and any fetch-native runtime consumes directly.
+* Represents the fetch-standard, method-dimensioned dispatch entity — layers HTTP
+* method dispatch and web-standard `Request`/`Response` handling over one internal
+* `Router<RouteRecord<TState>>`. The core machine the server face and any
+* fetch-native runtime consume directly.
 *
 * @typeParam TState - The consumer's opaque per-request state type
 *
 * @remarks
 * - **Dedup by `method + canonicalizePath`.** The underlying `Router` is
 *   constructed with a `key` function so registering the same method+path
-*   twice REPLACES the prior route in place (§5.1).
-* - **Registration boundary guard (§14).** `add` validates each input's
+*   twice REPLACES the prior route in place.
+* - **Registration boundary guard.** `add` validates each input's
 *   `handler` (`isFunction`) and `method` (must be in {@link METHODS}) —
-*   throws `TypeError` on a malformed registration; path validation is
+*   throws a `ContractError` on a malformed registration; path validation is
 *   delegated to the underlying `Router`'s own guard. `match`/`handle` stay
 *   guard-free.
 * - **Auto-`HEAD` / auto-`OPTIONS`.** A `HEAD` request with no registered
@@ -689,8 +740,8 @@ var DispatchGroup = class DispatchGroup {
 *   body; an `OPTIONS` request with no registered `OPTIONS` route answers
 *   `204` with a derived `Allow` header.
 * - **Handler throws propagate.** `handle` never invents an error boundary —
-*   a handler throw reaches the caller uncaught (§5.1).
-* - **Emitter (§13).** Owns a `#emitter` for {@link DispatcherEventMap};
+*   a handler throw reaches the caller uncaught.
+* - **Emitter.** Owns a `#emitter` for {@link DispatcherEventMap};
 *   `match`/`miss` fire AFTER resolution, before the handler/responder runs.
 *
 * @example
@@ -705,7 +756,7 @@ var DispatchGroup = class DispatchGroup {
 * ```
 */
 var Dispatcher = class {
-	router;
+	#router;
 	#emitter;
 	#unmatched;
 	#unmethoded;
@@ -713,7 +764,7 @@ var Dispatcher = class {
 		const sensitive = options?.sensitive;
 		const on = options?.on;
 		const error = options?.error;
-		this.router = new Router({
+		this.#router = new Router({
 			...sensitive === void 0 ? {} : { sensitive },
 			key: computeDispatchKey
 		});
@@ -725,6 +776,9 @@ var Dispatcher = class {
 		this.#unmethoded = options?.unmethoded;
 		if (options?.routes !== void 0) this.add(options.routes);
 	}
+	get router() {
+		return this.#router;
+	}
 	get emitter() {
 		return this.#emitter;
 	}
@@ -736,13 +790,13 @@ var Dispatcher = class {
 		return new DispatchGroup(this, prefix);
 	}
 	match(method, pathname) {
-		const hit = this.router.match(pathname, (meta) => meta.method === method);
+		const hit = this.#router.match(pathname, (meta) => meta.method === method);
 		if (hit !== void 0) return {
 			status: "matched",
 			match: hit
 		};
 		if (method === "HEAD") {
-			const getHit = this.router.match(pathname, (meta) => meta.method === "GET");
+			const getHit = this.#router.match(pathname, (meta) => meta.method === "GET");
 			if (getHit !== void 0) return {
 				status: "matched",
 				match: getHit
@@ -772,7 +826,10 @@ var Dispatcher = class {
 		const result = this.match(method, pathname);
 		if (result.status === "matched") return this.#respondMatched(request, state, method, result.match, url);
 		if (result.status === "unmethoded") {
-			if (method === "OPTIONS") return this.#respondAutoOptions(pathname, result.allow);
+			if (method === "OPTIONS") {
+				const hit = this.#router.match(pathname);
+				if (hit !== void 0) return this.#respondAutoOptions(hit.path, result.allow);
+			}
 			this.#emitter.emit("miss", method, pathname, "unmethoded");
 			return this.#respondUnmethoded(request, result.allow);
 		}
@@ -783,10 +840,24 @@ var Dispatcher = class {
 		this.#emitter.destroy();
 	}
 	#register(input) {
-		if (!isFunction(input.handler)) throw new TypeError(`a route handler must be a function, got ${JSON.stringify(input.handler)}`);
-		if (!isString(input.method) || !METHODS.has(input.method)) throw new TypeError(`a route method must be one of ${[...METHODS].join(", ")}, got ${JSON.stringify(input.method)}`);
+		if (!isFunction(input.handler)) throw new ContractError("a route handler must be a function", {
+			code: "literal",
+			context: {
+				path: ["input", "handler"],
+				limit: "function",
+				received: preview(input.handler)
+			}
+		});
+		if (!isString(input.method) || !METHODS.has(input.method)) throw new ContractError("a route method must be a registrable HTTP method", {
+			code: "literal",
+			context: {
+				path: ["input", "method"],
+				limit: [...METHODS].join(", "),
+				received: preview(input.method)
+			}
+		});
 		const name = input.name;
-		this.router.add({
+		this.#router.add({
 			path: input.path,
 			...name === void 0 ? {} : { name },
 			meta: {
@@ -797,7 +868,7 @@ var Dispatcher = class {
 		});
 	}
 	#allow(pathname) {
-		const entries = this.router.entries(pathname);
+		const entries = this.#router.entries(pathname);
 		const methods = /* @__PURE__ */ new Set();
 		for (const entry of entries) methods.add(entry.meta.method);
 		if (methods.has("GET")) methods.add("HEAD");
@@ -832,8 +903,8 @@ var Dispatcher = class {
 		});
 		return response;
 	}
-	#respondAutoOptions(pathname, allow) {
-		this.#emitter.emit("match", "OPTIONS", pathname);
+	#respondAutoOptions(pattern, allow) {
+		this.#emitter.emit("match", "OPTIONS", pattern);
 		const headers = new Headers({ Allow: [...allow, "OPTIONS"].join(", ") });
 		return new Response(null, {
 			status: 204,
@@ -844,7 +915,7 @@ var Dispatcher = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a {@link RouterInterface} — the pure path-matching + registry engine
+* Creates a {@link RouterInterface} — the pure path-matching + registry engine
 * shared by the browser `Navigator` and the core `Dispatcher`.
 *
 * @remarks
@@ -857,21 +928,32 @@ var Dispatcher = class {
 *   (default `true`), and a `key` dedup identity function
 * @returns A {@link RouterInterface}
 *
-* @example
+* @example Register and match
 * ```ts
-* import { createRouter } from '@src/core'
+* import { createDispatcher, createRouter } from '@orkestrel/router'
 *
 * const router = createRouter<{ readonly page: string }>()
 * router.add({ path: '/users/:id', meta: { page: 'profile' } })
 * router.match('/users/7') // { path: '/users/:id', params: { id: '7' }, meta: { page: 'profile' } }
+*
+* const dispatcher = createDispatcher<{ readonly userId: string }>({
+* 	routes: [
+* 		{
+* 			method: 'GET',
+* 			path: '/users/:id',
+* 			handler: (_request, context) => Response.json(context.params),
+* 		},
+* 	],
+* })
+* const response = await dispatcher.handle(new Request('http://x/users/7'), { userId: 'me' })
 * ```
 */
 function createRouter(options) {
 	return new Router(options);
 }
 /**
-* Create a {@link DispatcherInterface} — the fetch-standard, method-
-* dimensioned dispatch entity over one internal `Router<RouteRecord<TState>>`.
+* Creates a {@link DispatcherInterface} — the fetch-standard,
+* method-dimensioned dispatch entity over one internal `Router<RouteRecord<TState>>`.
 *
 * @remarks
 * Prefer this over `new Dispatcher(...)` at call sites that only need the
@@ -880,8 +962,8 @@ function createRouter(options) {
 * @typeParam TState - The consumer's opaque per-request state type (default
 *   `undefined` for stateless use)
 * @param options - Optional initial `routes`, the `sensitive` case toggle,
-*   the `unmatched`/`unmethoded` default-responder overrides, and the AGENTS
-*   §13 emitter `on`/`error` wiring
+*   the `unmatched`/`unmethoded` default-responder overrides, and the
+*   Emitter pattern's `on`/`error` wiring
 * @returns A {@link DispatcherInterface}
 *
 * @example
@@ -900,6 +982,6 @@ function createDispatcher(options) {
 	return new Dispatcher(options);
 }
 //#endregion
-export { DispatchGroup, Dispatcher, Group, METHODS, Router, TIER_LITERAL, TIER_PARAM, TIER_WILDCARD, canonicalizePath, classifySegment, compareSpecificity, compilePath, computeDispatchKey, computeSpecificity, createDispatcher, createRouter, decodeParam, escapeRegExp, joinPaths, matchPath, parseMethod, route };
+export { DispatchGroup, Dispatcher, Group, METHODS, METHOD_LIST, Router, TIER_LITERAL, TIER_PARAM, TIER_WILDCARD, canonicalizePath, classifySegment, compareSpecificity, compilePath, computeDispatchKey, computeSpecificity, createDispatcher, createRouter, decodeParam, defineRoute, escapeRegExp, joinPaths, matchPath, parseMethod };
 
 //# sourceMappingURL=index.js.map