@orkestrel/router 0.0.12 → 0.0.14

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

@@ -1,10 +1,10 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
 
 /**
- * The native-override seam — a predicate deciding whether an entry's `meta`
- * ANSWERS a given `match` call, beyond path matching.
+ * Represents the native-override seam — a predicate deciding whether an entry's
+ * `meta` answers a given `match` call, beyond path matching.
  *
  * @typeParam Meta - The entry payload the predicate reads
  *
@@ -14,12 +14,12 @@ import { EmitterInterface } from '@orkestrel/emitter';
  * === requestMethod`), the `Navigator` omits the predicate entirely (every
  * path match always answers). Passed per-call to {@link RouterInterface.match};
  * when omitted, every entry whose path matches is eligible. Total — it never
- * throws (a consumer keeps it pure, per AGENTS §14 guard totality).
+ * throws, so a consumer keeps it pure.
  */
 export declare type AnswerHandler<Meta> = (meta: Meta) => boolean;
 
 /**
- * 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.
@@ -45,22 +45,23 @@ export declare type AnswerHandler<Meta> = (meta: Meta) => boolean;
 export declare function canonicalizePath(path: string): string;
 
 /**
- * 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}
@@ -76,7 +77,7 @@ export declare function canonicalizePath(path: string): string;
 export declare function classifySegment(segment: string, isFinal: boolean): number;
 
 /**
- * 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).
  *
@@ -104,12 +105,12 @@ export declare function classifySegment(segment: string, isFinal: boolean): numb
 export declare function compareSpecificity(a: string, b: string): number;
 
 /**
- * A compiled route path — the anchored regex plus its ordered param names.
+ * Represents a compiled route path — the anchored regex plus its ordered param names.
  *
  * @remarks
- * The once-per-path compile output of `compilePath` (U1 `helpers.ts`):
+ * The once-per-path compile output of `compilePath` (the path compiler in `helpers.ts`):
  * `regex` is anchored (`^…$`) and matches the WHOLE pathname (with an
- * optional trailing slash, §4), and `params` lists each captured segment's
+ * optional trailing slash), and `params` lists each captured segment's
  * name (`:name` or the final `*name`) in order, so a `regex.exec` result's
  * capture groups line up with `params` positionally (the walk `matchPath`
  * performs). Plain data — no behavior.
@@ -120,7 +121,7 @@ export declare interface CompiledPath {
 }
 
 /**
- * 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
@@ -128,7 +129,7 @@ export declare interface CompiledPath {
  * `([^/]+)` 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
@@ -146,942 +147,1073 @@ export declare interface CompiledPath {
  * 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
- *
- * @example
- * ```ts
- * const { regex, params } = compilePath('/users/:id/posts/:slug')
- * params // ['id', 'slug']
- * regex.exec('/users/7/posts/hello') // ['…', '7', 'hello']
- * regex.test('/users/7/posts/hello/') // true — the trailing slash is optional
- *
- * compilePath('/files/*rest').regex.test('/files/a/b.png') // true
- * compilePath('/Users', false).regex.test('/users') // true — case-insensitive
- * ```
- */
-export declare function compilePath(path: string, sensitive?: boolean): CompiledPath;
+ * @throws {@link import('@orkestrel/contract').ContractError} Thrown when a
+     *   `*name` wildcard segment is not the FINAL segment
+     *
+     * @example
+     * ```ts
+     * const { regex, params } = compilePath('/users/:id/posts/:slug')
+     * params // ['id', 'slug']
+     * regex.exec('/users/7/posts/hello') // ['…', '7', 'hello']
+     * regex.test('/users/7/posts/hello/') // true — the trailing slash is optional
+     *
+     * compilePath('/files/*rest').regex.test('/files/a/b.png') // true
+     * compilePath('/Users', false).regex.test('/users') // true — case-insensitive
+     * ```
+     */
+ export declare function compilePath(path: string, sensitive?: boolean): CompiledPath;
 
-/**
- * Compute the registry key for a method-dimensioned dispatcher route.
- *
- * @remarks
- * Combines the route record's HTTP method with the outer entry's canonical
- * path, so registrations that differ only by one trailing slash replace each
- * other while registrations for different methods remain distinct.
- *
- * @param entry - The dispatcher route entry to identify
- * @returns The canonical `METHOD /path` registry key
- *
- * @example
- * ```ts
- * computeDispatchKey({ path: '/health/', meta: { method: 'GET' } }) // 'GET /health'
- * ```
- */
-export declare function computeDispatchKey(entry: RouteEntry<{
-    readonly method: Method;
-}>): string;
+ /**
+  * 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
+  * path, so registrations that differ only by one trailing slash replace each
+  * other while registrations for different methods remain distinct.
+  *
+  * @param entry - The dispatcher route entry to identify
+  * @returns The canonical `METHOD /path` registry key
+  *
+  * @example
+  * ```ts
+  * computeDispatchKey({ path: '/health/', meta: { method: 'GET' } }) // 'GET /health'
+  * ```
+  */
+ export declare function computeDispatchKey(entry: RouteEntry<{
+     readonly method: Method;
+ }>): string;
 
-/**
- * Compute 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
- * {@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
- * 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
- * SPECIFIC and wins — so `/users/me` (`[2, 2]`) beats `/users/:id` (`[2, 1]`)
- * beats `/users/*rest` (`[2, 0]`) regardless of registration order. Two routes
- * that match the SAME concrete pathname necessarily have the same segment
- * count in the common case; {@link compareSpecificity} handles the general
- * case for totality.
- *
- * @param path - The route path pattern (e.g. `/users/:id`)
- * @returns The per-segment specificity tiers, in order
- *
- * @example
- * ```ts
- * computeSpecificity('/users/me') // [2, 2]
- * computeSpecificity('/users/:id') // [2, 1]
- * computeSpecificity('/files/*rest') // [2, 0]
- * computeSpecificity('/a:b') // [2] — literal, not param — the classification fix
- * ```
- */
-export declare function computeSpecificity(path: string): readonly number[];
+ /**
+  * 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 through {@link classifySegment} — the same segment parser
+  * {@link compilePath} uses, so a literal segment that merely contains a `:`
+  * (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
+  * SPECIFIC and wins — so `/users/me` (`[2, 2]`) beats `/users/:id` (`[2, 1]`)
+  * beats `/users/*rest` (`[2, 0]`) regardless of registration order. Two routes
+  * that match the SAME concrete pathname necessarily have the same segment
+  * count in the common case; {@link compareSpecificity} handles the general
+  * case for totality.
+  *
+  * @param path - The route path pattern (for example `/users/:id`)
+  * @returns The per-segment specificity tiers, in order
+  *
+  * @example
+  * ```ts
+  * computeSpecificity('/users/me') // [2, 2]
+  * computeSpecificity('/users/:id') // [2, 1]
+  * computeSpecificity('/files/*rest') // [2, 0]
+  * computeSpecificity('/a:b') // [2] — literal, not param — the classification fix
+  * ```
+  */
+ export declare function computeSpecificity(path: string): readonly number[];
 
-/**
- * Create 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
- * interface.
- *
- * @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
- * @returns A {@link DispatcherInterface}
- *
- * @example
- * ```ts
- * import { createDispatcher } from '@src/core'
- *
- * const dispatcher = createDispatcher<{ readonly userId: string }>({
- * 	routes: [
- * 		{ method: 'GET', path: '/health', handler: () => new Response('ok') },
- * 	],
- * })
- * const response = await dispatcher.handle(new Request('http://x/health'), { userId: 'me' })
- * ```
- */
-export declare function createDispatcher<TState = undefined>(options?: DispatcherOptions<TState>): DispatcherInterface<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
+  * interface.
+  *
+  * @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
+  *   Emitter pattern's `on`/`error` wiring
+  * @returns A {@link DispatcherInterface}
+  *
+  * @example
+  * ```ts
+  * import { createDispatcher } from '@src/core'
+  *
+  * const dispatcher = createDispatcher<{ readonly userId: string }>({
+  * 	routes: [
+  * 		{ method: 'GET', path: '/health', handler: () => new Response('ok') },
+  * 	],
+  * })
+  * const response = await dispatcher.handle(new Request('http://x/health'), { userId: 'me' })
+  * ```
+  */
+ export declare function createDispatcher<TState = undefined>(options?: DispatcherOptions<TState>): DispatcherInterface<TState>;
 
-/**
- * Create a {@link RouterInterface} — the pure path-matching + registry engine
- * shared by the browser `Navigator` and the core `Dispatcher`.
- *
- * @remarks
- * Prefer this over `new Router(...)` at call sites that only need the
- * interface; an entity that OWNS a `Router` internally (like `Dispatcher`)
- * still constructs `new Router(...)` directly.
- *
- * @typeParam Meta - The opaque payload each entry carries and a match returns
- * @param options - Optional initial `entries`, the `sensitive` case toggle
- *   (default `true`), and a `key` dedup identity function
- * @returns A {@link RouterInterface}
- *
- * @example
- * ```ts
- * import { createRouter } from '@src/core'
- *
- * 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' } }
- * ```
- */
-export declare function createRouter<Meta>(options?: RouterOptions<Meta>): RouterInterface<Meta>;
+ /**
+  * Creates a {@link RouterInterface} — the pure path-matching + registry engine
+  * shared by the browser `Navigator` and the core `Dispatcher`.
+  *
+  * @remarks
+  * Prefer this over `new Router(...)` at call sites that only need the
+  * interface; an entity that OWNS a `Router` internally (like `Dispatcher`)
+  * still constructs `new Router(...)` directly.
+  *
+  * @typeParam Meta - The opaque payload each entry carries and a match returns
+  * @param options - Optional initial `entries`, the `sensitive` case toggle
+  *   (default `true`), and a `key` dedup identity function
+  * @returns A {@link RouterInterface}
+  *
+  * @example Register and match
+  * ```ts
+  * 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' })
+  * ```
+  */
+ export declare function createRouter<Meta>(options?: RouterOptions<Meta>): RouterInterface<Meta>;
 
-/**
- * URL-decode one captured param value, 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
- * throws.
- *
- * @param value - The raw captured param value
- * @returns The URL-decoded value, or the raw value when decoding would throw
- *
- * @example
- * ```ts
- * decodeParam('a%2Fb') // 'a/b'
- * decodeParam('100%25') // '100%'
- * decodeParam('%') // '%' — malformed escape stays literal
- * ```
- */
-export declare function decodeParam(value: string): string;
+ /**
+  * 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). Total — never
+  * throws.
+  *
+  * @param value - The raw captured param value
+  * @returns The URL-decoded value, or the raw value when decoding would throw
+  *
+  * @example
+  * ```ts
+  * decodeParam('a%2Fb') // 'a/b'
+  * decodeParam('100%25') // '100%'
+  * decodeParam('%') // '%' — malformed escape stays literal
+  * ```
+  */
+ export declare function decodeParam(value: string): string;
 
-/**
- * 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.
- *
- * @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
- *   `handler` (`isFunction`) and `method` (must be in {@link METHODS}) —
- *   throws `TypeError` 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
- *   `HEAD` route runs the matching `GET` handler and strips the response
- *   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};
- *   `match`/`miss` fire AFTER resolution, before the handler/responder runs.
- *
- * @example
- * ```ts
- * const dispatcher = new Dispatcher<{ readonly userId: string }>()
- * dispatcher.add({
- * 	method: 'GET',
- * 	path: '/users/:id',
- * 	handler: (request, context) => Response.json({ id: context.params.id }),
- * })
- * const response = await dispatcher.handle(new Request('http://x/users/7'), { userId: 'me' })
- * ```
- */
-export declare class Dispatcher<TState = undefined> implements DispatcherInterface<TState> {
-    #private;
-    readonly router: RouterInterface<RouteRecord<TState>>;
-    constructor(options?: DispatcherOptions<TState>);
-    get emitter(): EmitterInterface<DispatcherEventMap>;
-    add<Path extends string>(input: RouteInput<Path, TState>): void;
-    add(inputs: ReadonlyArray<RouteInput<string, TState>>): void;
-    group(prefix: string): DispatchGroupInterface<TState>;
-    match(method: Method, pathname: string): DispatchResult<TState>;
-    handle(request: Request, state: TState): Promise<Response>;
-    destroy(): void;
-}
+ /**
+  * 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
+  * A bare object literal handed straight to {@link import('./types.js').DispatcherInterface}'s
+  * `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 `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 `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`
+  *   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 = defineRoute({
+  * 	method: 'GET',
+  * 	path: '/users/:id',
+  * 	handler: (_request, context) => new Response(context.params.id), // typed string
+  * })
+  * dispatcher.add(input)
+  * ```
+  */
+ export declare function defineRoute<const Path extends string, TState = undefined>(input: RouteInput<Path, TState>): RouteInput<Path, TState>;
 
-/**
- * The `Dispatcher`'s event map (AGENTS §13) — the two dispatch-outcome
- * signals a consumer can observe alongside the return value of `handle`.
- *
- * @remarks
- * - `match` — emitted on every dispatch that resolves to a handler
- *   (including the auto-`HEAD`/auto-`OPTIONS` derived cases): the request
- *   `method` and the winning `pattern`.
- * - `miss` — emitted on every non-matching dispatch: the RAW request
- *   `method` (a plain `string`, not narrowed to {@link Method} — an unknown
- *   verb like `PURGE` is observable here exactly as sent, never coerced),
- *   the raw `pathname`, and which tier missed (`'unmatched'` — nothing
- *   matched the path at all; `'unmethoded'` — the path matched but not the
- *   method, including an unknown verb against a path with other registered
- *   methods).
- */
-export declare type DispatcherEventMap = {
-    readonly match: readonly [method: Method, pattern: string];
-    readonly miss: readonly [method: string, pathname: string, reason: 'unmatched' | 'unmethoded'];
-};
+ /**
+  * 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.
+  * - **Registration boundary guard.** `add` validates each input's
+  *   `handler` (`isFunction`) and `method` (must be in {@link METHODS}) —
+  *   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
+  *   `HEAD` route runs the matching `GET` handler and strips the response
+  *   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.
+  * - **Emitter.** Owns a `#emitter` for {@link DispatcherEventMap};
+  *   `match`/`miss` fire AFTER resolution, before the handler/responder runs.
+  *
+  * @example
+  * ```ts
+  * const dispatcher = new Dispatcher<{ readonly userId: string }>()
+  * dispatcher.add({
+  * 	method: 'GET',
+  * 	path: '/users/:id',
+  * 	handler: (request, context) => Response.json({ id: context.params.id }),
+  * })
+  * const response = await dispatcher.handle(new Request('http://x/users/7'), { userId: 'me' })
+  * ```
+  */
+ export declare class Dispatcher<TState = undefined> implements DispatcherInterface<TState> {
+     #private;
+     constructor(options?: DispatcherOptions<TState>);
+     get router(): RouterInterface<RouteRecord<TState>>;
+     get emitter(): EmitterInterface<DispatcherEventMap>;
+     add<Path extends string>(input: RouteInput<Path, TState>): void;
+     add(inputs: ReadonlyArray<RouteInput<string, TState>>): void;
+     group(prefix: string): DispatchGroupInterface<TState>;
+     match(method: Method, pathname: string): DispatchResult<TState>;
+     handle(request: Request, state: TState): Promise<Response>;
+     destroy(): void;
+ }
 
-/**
- * The fetch-standard, method-dimensioned dispatch entity contract (the §4.5
- * behavioral-interface role for the one-class-per-file `Dispatcher`). Layers
- * HTTP method dispatch and web-standard `Request`/`Response` handling over a
- * single internal `Router<RouteRecord<TState>>`.
- *
- * @typeParam TState - The consumer's opaque per-request state type, threaded
- *   into every {@link RouteContext} (default `undefined` for stateless use)
- *
- * @remarks
- * - `router` — the underlying registry, exposed READONLY for introspection
- *   (the same object `add`/`group`/`match` operate on).
- * - `emitter` — the AGENTS §13 observable surface for {@link DispatcherEventMap}.
- * - `add(input)` / `add(inputs)` — register ONE / MANY {@link RouteInput}s
- *   (§9.2 batch); throws `TypeError` on a malformed registration (a
- *   non-`/`-prefixed path, a non-function handler, or a method outside
- *   {@link import('./constants.js').METHODS}) — the construction/registration
- *   boundary guard (§14); `match`/`handle` hot paths carry zero guards.
- * - `group(prefix)` — a {@link DispatchGroupInterface} scoped under `prefix`.
- * - `match(method, pathname)` — the raw {@link DispatchResult} for a method +
- *   pathname pair, with no `Request`/`Response` involvement — the pure
- *   decision `handle` builds its response from.
- * - `handle(request, state)` — the full dispatch: parses `request.url`,
- *   calls `match`, and either invokes the winning handler (auto-stripping
- *   the body for a derived `HEAD`, auto-answering a derived `OPTIONS` with
- *   the `Allow` set), or invokes the `unmatched`/`unmethoded` responder.
- *   Emits `match`/`miss` accordingly. A handler throw propagates uncaught.
- * - `destroy()` — tears down the `#emitter` (AGENTS §13); the underlying
- *   router is left registered (not cleared) so introspection remains valid
- *   after destroy.
- */
-export declare interface DispatcherInterface<TState = undefined> {
-    readonly router: RouterInterface<RouteRecord<TState>>;
-    readonly emitter: EmitterInterface<DispatcherEventMap>;
-    add<Path extends string>(input: RouteInput<Path, TState>): void;
-    add(inputs: ReadonlyArray<RouteInput<string, TState>>): void;
-    group(prefix: string): DispatchGroupInterface<TState>;
-    match(method: Method, pathname: string): DispatchResult<TState>;
-    handle(request: Request, state: TState): Promise<Response>;
-    destroy(): void;
-}
+ /**
+  * Represents the `Dispatcher`'s event map — the dispatch-outcome
+  * signals a consumer can observe alongside the return value of `handle`.
+  *
+  * @remarks
+  * - `match` — emitted on every dispatch the dispatcher answers, the derived
+  *   `HEAD` and `OPTIONS` cases included: the request `method` and the winning
+  *   `pattern` (for a derived `OPTIONS` answer, the most-specific pattern the
+  *   pathname resolved to).
+  * - `miss` — emitted on every non-matching dispatch: the RAW request
+  *   `method` (a plain `string`, not narrowed to {@link Method} — an unknown
+  *   verb like `PURGE` is observable here exactly as sent, never coerced),
+  *   the raw `pathname`, and which tier missed (`'unmatched'` — nothing
+  *   matched the path at all; `'unmethoded'` — the path matched but not the
+  *   method, including an unknown verb against a path with other registered
+  *   methods).
+  */
+ export declare type DispatcherEventMap = {
+     readonly match: readonly [method: Method, pattern: string];
+     readonly miss: readonly [method: string, pathname: string, status: 'unmatched' | 'unmethoded'];
+ };
 
-/**
- * Options for `createDispatcher` — initial routes, case sensitivity, the two
- * default-responder overrides, and the AGENTS §13 emitter wiring.
- *
- * @typeParam TState - The consumer's opaque per-request state type
- *
- * @remarks
- * - `routes` — the initial route inputs to register, equivalent to a bare
- *   `createDispatcher()` followed by `add(routes)`. Omitted ⇒ no routes.
- * - `sensitive` — forwarded to the underlying `Router` (default `true`, §4).
- * - `unmatched` — the responder invoked when nothing matches the pathname at
- *   all (default: a `404` `Response`).
- * - `unmethoded` — the responder invoked when the pathname matches but not
- *   the method, given the derived `Allow` set (default: a `405` `Response`
- *   with an `Allow` header).
- * - `on` — initial `DispatcherEventMap` listeners (AGENTS §8/§13).
- * - `error` — the emitter's own listener-error handler (AGENTS §13),
- *   forwarded alongside `on`.
- */
-export declare interface DispatcherOptions<TState> {
-    readonly routes?: ReadonlyArray<RouteInput<string, TState>>;
-    readonly sensitive?: boolean;
-    readonly unmatched?: (request: Request) => Response | Promise<Response>;
-    readonly unmethoded?: (request: Request, allow: readonly Method[]) => Response | Promise<Response>;
-    readonly on?: EmitterHooks<DispatcherEventMap>;
-    readonly error?: EmitterErrorHandler;
-}
+ /**
+  * Represents the fetch-standard, method-dimensioned dispatch entity contract (the
+  * behavioral-interface role for the one-class-per-file `Dispatcher`). Layers
+  * HTTP method dispatch and web-standard `Request`/`Response` handling over a
+  * single internal `Router<RouteRecord<TState>>`.
+  *
+  * @typeParam TState - The consumer's opaque per-request state type, threaded
+  *   into every {@link RouteContext} (default `undefined` for stateless use)
+  *
+  * @remarks
+  * Registration is the guarded boundary: `add` throws on a malformed registration,
+  * while the `match` and `handle` hot paths carry no guard of their own.
+  */
+ export declare interface DispatcherInterface<TState = undefined> {
+     /**
+      * Holds the underlying registry, exposed readonly for introspection — the same
+      * object `add`, `group`, and `match` operate on.
+      */
+     readonly router: RouterInterface<RouteRecord<TState>>;
+     /** Holds the observable surface for {@link DispatcherEventMap}. */
+     readonly emitter: EmitterInterface<DispatcherEventMap>;
+     /**
+      * Registers one route input, or many in one call (batch registration); throws a
+      * `ContractError` on a malformed registration.
+      *
+      * @remarks
+      * A registration is malformed when its path is not `/`-prefixed, its handler is not
+      * a function, or its method sits outside {@link import('./constants.js').METHODS}.
+      * Path validation is delegated to the underlying router's own guard.
+      */
+     add<Path extends string>(input: RouteInput<Path, TState>): void;
+     add(inputs: ReadonlyArray<RouteInput<string, TState>>): void;
+     /** Returns a prefix-scoped registration handle over this dispatcher. */
+     group(prefix: string): DispatchGroupInterface<TState>;
+     /**
+      * Decides the raw {@link DispatchResult} for a method and pathname pair, with no
+      * `Request` or `Response` involvement — the pure decision `handle` builds its
+      * response from.
+      */
+     match(method: Method, pathname: string): DispatchResult<TState>;
+     /**
+      * Runs the full dispatch: parses the request URL, matches, and invokes either the
+      * winning handler or the `unmatched`/`unmethoded` responder.
+      *
+      * @remarks
+      * A derived `HEAD` runs the matching `GET` handler with the response body stripped,
+      * and a derived `OPTIONS` answers with the `Allow` set. Emits `match` or `miss`
+      * accordingly. A handler throw propagates uncaught.
+      */
+     handle(request: Request, state: TState): Promise<Response>;
+     /**
+      * Tears down the emitter; the underlying router is left registered rather than
+      * cleared, so introspection stays valid afterwards.
+      */
+     destroy(): void;
+ }
 
-/**
- * A prefix-scoped registration handle over a
- * {@link import('./Dispatcher.js').Dispatcher} — the method-dimensioned
- * counterpart of `Group` (`Group.ts`).
- *
- * @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
- * independent state or storage.
- *
- * @example
- * ```ts
- * import { Dispatcher } from '@src/core'
- *
- * const dispatcher = new Dispatcher()
- * const api = dispatcher.group('/api')
- * api.add({ method: 'GET', path: '/users', handler: () => new Response('ok') })
- * ```
- */
-export declare class DispatchGroup<TState> implements DispatchGroupInterface<TState> {
-    #private;
-    readonly prefix: string;
-    constructor(parent: DispatcherInterface<TState>, prefix: string);
-    add<Path extends string>(input: RouteInput<Path, TState>): void;
-    add(inputs: ReadonlyArray<RouteInput<string, TState>>): void;
-    group(prefix: string): DispatchGroupInterface<TState>;
-}
+ /**
+  * Represents the options for `createDispatcher` — initial routes, case sensitivity, the
+  * default-responder overrides, and the Emitter pattern's wiring.
+  *
+  * @typeParam TState - The consumer's opaque per-request state type
+  *
+  * @remarks
+  * - `routes` — the initial route inputs to register, equivalent to a bare
+  *   `createDispatcher()` followed by `add(routes)`. Omitted ⇒ no routes.
+  * - `sensitive` — forwarded to the underlying `Router` (default `true`).
+  * - `unmatched` — the responder invoked when nothing matches the pathname at
+  *   all (default: a `404` `Response`).
+  * - `unmethoded` — the responder invoked when the pathname matches but not
+  *   the method, given the derived `Allow` set (default: a `405` `Response`
+  *   with an `Allow` header).
+  * - `on` — initial `DispatcherEventMap` listeners (the Emitter pattern's
+  *   similar-surface pin).
+  * - `error` — the emitter's own listener-error handler, forwarded alongside
+  *   `on`.
+  */
+ export declare interface DispatcherOptions<TState> {
+     readonly routes?: ReadonlyArray<RouteInput<string, TState>>;
+     readonly sensitive?: boolean;
+     readonly unmatched?: (request: Request) => Response | Promise<Response>;
+     readonly unmethoded?: (request: Request, allow: readonly Method[]) => Response | Promise<Response>;
+     readonly on?: EmitterHooks<DispatcherEventMap>;
+     readonly error?: EmitterErrorHandler;
+ }
 
-/**
- * A prefix-scoped registration handle over a {@link DispatcherInterface} —
- * the method-dimensioned counterpart of {@link GroupInterface}.
- *
- * @typeParam TState - The consumer's opaque per-request state type, matching
- *   the owning dispatcher
- *
- * @remarks
- * - `prefix` — the path prefix this group prepends to every route it
- *   registers (and to every nested group's own prefix).
- * - `add(input)` / `add(inputs)` — register ONE / MANY {@link RouteInput}s on
- *   the OWNING dispatcher, each input's `path` composed as
- *   `prefix + input.path` (§9.2 batch, mirroring
- *   {@link DispatcherInterface.add}).
- * - `group(prefix)` — a nested group whose prefix is `this.prefix + prefix`.
- */
-export declare interface DispatchGroupInterface<TState> {
-    readonly prefix: string;
-    add<Path extends string>(input: RouteInput<Path, TState>): void;
-    add(inputs: ReadonlyArray<RouteInput<string, TState>>): void;
-    group(prefix: string): DispatchGroupInterface<TState>;
-}
+ /**
+  * 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` 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
+  * ```ts
+  * import { Dispatcher } from '@src/core'
+  *
+  * const dispatcher = new Dispatcher()
+  * const api = dispatcher.group('/api')
+  * api.add({ method: 'GET', path: '/users', handler: () => new Response('ok') })
+  * ```
+  */
+ export declare class DispatchGroup<TState> implements DispatchGroupInterface<TState> {
+     #private;
+     readonly prefix: string;
+     constructor(parent: DispatcherInterface<TState>, prefix: string);
+     add<Path extends string>(input: RouteInput<Path, TState>): void;
+     add(inputs: ReadonlyArray<RouteInput<string, TState>>): void;
+     group(prefix: string): DispatchGroupInterface<TState>;
+ }
 
-/**
- * The outcome of {@link DispatcherInterface.match} — a discriminated union
- * over the three dispatch tiers: a full hit, a path-matches-but-method-
- * doesn't (405 territory), or nothing matched at all (404 territory).
- *
- * @typeParam TState - The consumer's opaque per-request state type
- *
- * @remarks
- * - `'matched'` — carries the winning {@link RouterMatch} (its `meta` is a
- *   {@link RouteRecord}).
- * - `'unmethoded'` — the pathname matched at least one entry but none for
- *   the requested method; `allow` is the derived `Allow` method set (from
- *   `router.entries(pathname)`).
- * - `'unmatched'` — no registered pattern matches the pathname at all.
- */
-export declare type DispatchResult<TState> = {
-    readonly status: 'matched';
-    readonly match: RouterMatch<RouteRecord<TState>>;
-} | {
-    readonly status: 'unmethoded';
-    readonly allow: readonly Method[];
-} | {
-    readonly status: 'unmatched';
-};
+ /**
+  * Represents a prefix-scoped registration handle over a {@link DispatcherInterface} —
+  * the method-dimensioned counterpart of {@link GroupInterface}.
+  *
+  * @typeParam TState - The consumer's opaque per-request state type, matching
+  *   the owning dispatcher
+  *
+  * @remarks
+  * Nesting composes prefixes left to right with no depth limit.
+  */
+ export declare interface DispatchGroupInterface<TState> {
+     /**
+      * Holds the path prefix this group prepends to every route it registers, and to
+      * every nested group's own prefix.
+      */
+     readonly prefix: string;
+     /**
+      * Registers one route input, or many in one call, on the owning dispatcher with this
+      * group's prefix composed onto each path.
+      *
+      * @remarks
+      * Batch registration mirrors {@link DispatcherInterface.add}, and the owning
+      * dispatcher's own registration guard still applies.
+      */
+     add<Path extends string>(input: RouteInput<Path, TState>): void;
+     add(inputs: ReadonlyArray<RouteInput<string, TState>>): void;
+     /** Returns a nested group whose prefix is this prefix followed by the given one. */
+     group(prefix: string): DispatchGroupInterface<TState>;
+ }
 
-/**
- * Escape every regex metacharacter in a literal string so it can be embedded
- * inside a larger `RegExp` source without being interpreted as syntax.
- *
- * @remarks
- * {@link compilePath} escapes the literal segments of a route pattern with this
- * before splicing in `:name` / `*name` capture groups, so a path like
- * `/files/:name.json` matches the `.` literally rather than as "any character".
- * Pure and total — never throws.
- *
- * @param value - The literal string to escape
- * @returns `value` with every regex metacharacter backslash-escaped
- *
- * @example
- * ```ts
- * escapeRegExp('a.b+c') // 'a\\.b\\+c'
- * new RegExp(`^${escapeRegExp('a.b')}$`).test('a.b') // true
- * new RegExp(`^${escapeRegExp('a.b')}$`).test('axb') // false
- * ```
- */
-export declare function escapeRegExp(value: string): string;
+ /**
+  * Represents the outcome of {@link DispatcherInterface.match} — a discriminated
+  * union over the dispatch tiers: a full hit, a path that matches with no route for
+  * the method (405 territory), or nothing matched at all (404 territory).
+  *
+  * @typeParam TState - The consumer's opaque per-request state type
+  *
+  * @remarks
+  * - `'matched'` — carries the winning {@link RouterMatch} (its `meta` is a
+  *   {@link RouteRecord}).
+  * - `'unmethoded'` — the pathname matched at least one entry but none for
+  *   the requested method; `allow` is the derived `Allow` method set (from
+  *   `router.entries(pathname)`).
+  * - `'unmatched'` — no registered pattern matches the pathname at all.
+  */
+ export declare type DispatchResult<TState> = {
+     readonly status: 'matched';
+     readonly match: RouterMatch<RouteRecord<TState>>;
+ } | {
+     readonly status: 'unmethoded';
+     readonly allow: readonly Method[];
+ } | {
+     readonly status: 'unmatched';
+ };
 
-/**
- * A prefix-scoped registration handle over a {@link import('./Router.js').Router} —
- * pure string composition (AGENTS §4.2.2), 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}.
- *
- * @example
- * ```ts
- * import { Router } from '@src/core'
- *
- * const router = new Router<{ readonly page: string }>()
- * const api = router.group('/api')
- * api.add({ path: '/users', meta: { page: 'list' } })
- * router.match('/api/users')?.path // '/api/users'
- * ```
- */
-export declare class Group<Meta> implements GroupInterface<Meta> {
-    #private;
-    readonly prefix: string;
-    constructor(parent: RouterInterface<Meta>, prefix: string);
-    add(entry: RouteEntry<Meta>): void;
-    add(entries: ReadonlyArray<RouteEntry<Meta>>): void;
-    group(prefix: string): GroupInterface<Meta>;
-}
+ /**
+  * Escapes every regex metacharacter in a literal string so it can be embedded
+  * inside a larger `RegExp` source without being interpreted as syntax.
+  *
+  * @remarks
+  * {@link compilePath} escapes the literal segments of a route pattern with this
+  * before splicing in `:name` / `*name` capture groups, so a path like
+  * `/files/:name.json` matches the `.` literally rather than as "any character".
+  * Pure and total — never throws.
+  *
+  * @param value - The literal string to escape
+  * @returns `value` with every regex metacharacter backslash-escaped
+  *
+  * @example
+  * ```ts
+  * escapeRegExp('a.b+c') // 'a\\.b\\+c'
+  * new RegExp(`^${escapeRegExp('a.b')}$`).test('a.b') // true
+  * new RegExp(`^${escapeRegExp('a.b')}$`).test('axb') // false
+  * ```
+  */
+ export declare function escapeRegExp(value: string): string;
 
-/**
- * A prefix-scoped registration handle over a {@link RouterInterface} — pure
- * string composition (§4.2.2), no independent state or storage.
- *
- * @typeParam Meta - The entry payload type, matching the owning router
- *
- * @remarks
- * - `prefix` — the path prefix this group prepends to every entry it
- *   registers (and to every nested group's own prefix).
- * - `add(entry)` / `add(entries)` — register ONE / MANY entries on the
- *   OWNING router, each entry's `path` composed as `prefix + entry.path`
- *   (§9.2 batch, mirroring {@link RouterInterface.add}).
- * - `group(prefix)` — a nested group whose prefix is `this.prefix + prefix`;
- *   nesting composes prefixes left to right with no depth limit.
- */
-export declare interface GroupInterface<Meta> {
-    readonly prefix: string;
-    add(entry: RouteEntry<Meta>): void;
-    add(entries: ReadonlyArray<RouteEntry<Meta>>): void;
-    group(prefix: string): GroupInterface<Meta>;
-}
+ /**
+  * 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 through {@link joinPaths}.
+  *
+  * @example
+  * ```ts
+  * import { Router } from '@src/core'
+  *
+  * const router = new Router<{ readonly page: string }>()
+  * const api = router.group('/api')
+  * api.add({ path: '/users', meta: { page: 'list' } })
+  * router.match('/api/users')?.path // '/api/users'
+  * ```
+  */
+ export declare class Group<Meta> implements GroupInterface<Meta> {
+     #private;
+     readonly prefix: string;
+     constructor(parent: RouterInterface<Meta>, prefix: string);
+     add(entry: RouteEntry<Meta>): void;
+     add(entries: ReadonlyArray<RouteEntry<Meta>>): void;
+     group(prefix: string): GroupInterface<Meta>;
+ }
 
-/**
- * The identifier CONTINUATION characters after the first — mirrors the
- * runtime classifier's `[A-Za-z0-9_]*` tail class.
- */
-export declare type IdentifierChar = IdentifierStartChar | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+ /**
+  * Represents a prefix-scoped registration handle over a {@link RouterInterface} — pure
+  * string composition, no independent state or storage.
+  *
+  * @typeParam Meta - The entry payload type, matching the owning router
+  *
+  * @remarks
+  * Nesting composes prefixes left to right with no depth limit.
+  */
+ export declare interface GroupInterface<Meta> {
+     /**
+      * Holds the path prefix this group prepends to every entry it registers, and to
+      * every nested group's own prefix.
+      */
+     readonly prefix: string;
+     /**
+      * Registers one entry, or many in one call, on the owning router with this group's
+      * prefix composed onto each path.
+      *
+      * @remarks
+      * Batch registration mirrors {@link RouterInterface.add}, and the owning router's own
+      * registration guard still applies.
+      */
+     add(entry: RouteEntry<Meta>): void;
+     add(entries: ReadonlyArray<RouteEntry<Meta>>): void;
+     /** Returns a nested group whose prefix is this prefix followed by the given one. */
+     group(prefix: string): GroupInterface<Meta>;
+ }
 
-export declare type IdentifierHead<S extends string> = S extends `${infer Head}${infer Tail}` ? Head extends IdentifierStartChar ? TakeIdentifierTail<Tail, Head> : '' : '';
+ /**
+  * Names the identifier continuation characters after the first — mirrors the
+  * runtime classifier's `[A-Za-z0-9_]*` tail class.
+  */
+ export declare type IdentifierChar = IdentifierStartChar | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
 
-/**
- * The identifier START characters an identifier-grammar param name may
- * begin with — mirrors the runtime classifier's `[A-Za-z_]` head class
- * (`classifySegment` / `compilePath`, `helpers.ts`).
- */
-export declare type IdentifierStartChar = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '_';
+ /**
+  * Captures the identifier at the front of a string literal, or an empty string when the
+  * literal does not begin with an identifier-start char.
+  *
+  * @typeParam S - The string literal to read the head from
+  *
+  * @remarks
+  * The type-level mirror of the runtime head match anchored on an identifier-start char:
+  * an {@link IdentifierStartChar} opens the run and {@link TakeIdentifierTail} consumes
+  * the rest of it.
+  */
+ export declare type IdentifierHead<S extends string> = S extends `${infer Head}${infer Tail}` ? Head extends IdentifierStartChar ? TakeIdentifierTail<Tail, Head> : '' : '';
 
-/**
- * Join 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
- * (`'/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`)
- * @returns The joined `/`-prefixed path
- *
- * @example
- * ```ts
- * joinPaths('/api', '/users') // '/api/users'
- * joinPaths('/api/', '/users') // '/api/users'
- * joinPaths('/api', 'users') // '/api/users'
- * joinPaths('', '/users') // '/users'
- * joinPaths('/api', '') // '/api'
- * ```
- */
-export declare function joinPaths(prefix: string, path: string): string;
+ /**
+  * Names the identifier start characters an identifier-grammar param name may begin
+  * with — mirrors the runtime classifier's `[A-Za-z_]` head class, the one
+  * `classifySegment` and `compilePath` share.
+  */
+ export declare type IdentifierStartChar = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '_';
 
-/**
- * Extract the URL-decoded params a compiled path captures from a concrete
- * pathname, or `undefined` when the pathname does not match.
- *
- * @remarks
- * Runs the {@link CompiledPath} `regex` against `pathname` (a single `exec`); a
- * miss returns `undefined`. On a hit it walks `params` POSITIONALLY — the
- * `n`-th param name pairs with the `n`-th capture group — and URL-decodes each
- * value with {@link decodeParam}. Returns a frozen `name → value` record (empty
- * 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`)
- * @returns The decoded params on a hit, or `undefined` on a miss
- *
- * @example
- * ```ts
- * const compiled = compilePath('/users/:id')
- * matchPath(compiled, '/users/7') // { id: '7' }
- * matchPath(compiled, '/users/a%2Fb') // { id: 'a/b' } — decoded
- * matchPath(compiled, '/posts/7') // undefined
- * ```
- */
-export declare function matchPath(compiled: CompiledPath, pathname: string): Readonly<Record<string, string>> | undefined;
+ /**
+  * 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, 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 (for example `/api`)
+  * @param path - The route path being joined under the prefix (for example `/users`)
+  * @returns The joined `/`-prefixed path
+  *
+  * @example
+  * ```ts
+  * joinPaths('/api', '/users') // '/api/users'
+  * joinPaths('/api/', '/users') // '/api/users'
+  * joinPaths('/api', 'users') // '/api/users'
+  * joinPaths('', '/users') // '/users'
+  * joinPaths('/api', '') // '/api'
+  * ```
+  */
+ export declare function joinPaths(prefix: string, path: string): string;
 
-/**
- * The seven HTTP methods a {@link DispatcherInterface} dimensions dispatch
- * over — the value-level counterpart is {@link import('./constants.js').METHODS}.
- *
- * @remarks
- * `HEAD` is a valid explicit registration even though a `GET` route already
- * auto-answers `HEAD` (§5.1 dispatch semantics) — an explicit `HEAD` handler
- * always takes precedence over the derived one.
- */
-export declare type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+ /**
+  * Extracts the URL-decoded params a compiled path captures from a concrete
+  * pathname, or `undefined` when the pathname does not match.
+  *
+  * @remarks
+  * Runs the {@link CompiledPath} `regex` against `pathname` (a single `exec`); a
+  * miss returns `undefined`. On a hit it walks `params` POSITIONALLY — the
+  * `n`-th param name pairs with the `n`-th capture group — and URL-decodes each
+  * value with {@link decodeParam}. Returns a frozen `name → value` record (empty
+  * for a parameterless path). Total — never throws.
+  *
+  * @param compiled - The {@link CompiledPath} from {@link compilePath}
+  * @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
+  * ```ts
+  * const compiled = compilePath('/users/:id')
+  * matchPath(compiled, '/users/7') // { id: '7' }
+  * matchPath(compiled, '/users/a%2Fb') // { id: 'a/b' } — decoded
+  * matchPath(compiled, '/posts/7') // undefined
+  * ```
+  */
+ export declare function matchPath(compiled: CompiledPath, pathname: string): Readonly<Record<string, string>> | undefined;
 
-/**
- * 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.
- *
- * @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.
- *
- * @example
- * ```ts
- * METHODS.has('GET') // true
- * METHODS.has('TRACE') // false
- * ```
- */
-export declare const METHODS: ReadonlySet<string>;
+ /**
+  * Names the HTTP methods a {@link DispatcherInterface} dimensions dispatch over —
+  * derived from {@link import('./constants.js').METHOD_LIST}, whose membership
+  * counterpart is {@link import('./constants.js').METHODS}.
+  *
+  * @remarks
+  * Resolves to `'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' |
+  * 'OPTIONS'`. Deriving the union from the constant keeps one home for the
+  * method set: a verb added there widens this type, the membership set, and the
+  * `parseMethod` narrowing together. `HEAD` is a valid explicit registration
+  * even though a `GET` route already auto-answers `HEAD` — an explicit
+  * `HEAD` handler always takes precedence over the derived one.
+  */
+ export declare type Method = (typeof METHOD_LIST)[number];
 
-/**
- * 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
- * ```
- */
-export declare function parseMethod(value: string): Method | undefined;
+ /**
+  * 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 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
+  * METHOD_LIST[0] // 'GET'
+  * METHOD_LIST.includes('GET') // true
+  * ```
+  */
+ export declare const METHOD_LIST: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 
-/**
- * Extracts `{ name: string }` param records from a path pattern at the type
- * level — the typed half of the path grammar (§4).
- *
- * @typeParam Path - A route path pattern literal (`/users/:id/posts/:slug`,
- *   `/files/*rest`, or a parameterless literal path)
- *
- * @remarks
- * A `:name` segment contributes `{ name: string }`; a trailing `*name`
- * wildcard (the grammar's only allowed wildcard position) contributes
- * `{ name: string }` capturing the rest of the path; a parameterless pattern
- * resolves to an empty record. Built over {@link PathParamsRaw} and flattened
- * through an identity-mapped type so editor hovers show the resolved shape
- * (`{ id: string; slug: string }`) rather than an unresolved intersection.
- *
- * @example
- * ```ts
- * type A = PathParams<'/users/:id/posts/:slug'> // { readonly id: string; readonly slug: string }
- * type B = PathParams<'/files/*rest'>            // { readonly rest: string }
- * type C = PathParams<'/health'>                 // Record<string, never>
- * ```
- */
-export declare type PathParams<Path extends string> = {
-    readonly [K in keyof PathParamsRaw<Path>]: PathParamsRaw<Path>[K];
-};
+ /**
+  * 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
+  * ```
+  */
+ export declare const METHODS: ReadonlySet<string>;
 
-/**
- * Recursive, unflattened param extraction for {@link PathParams} — walks a
- * path pattern segment by segment (split on `/`), extracting each segment's
- * {@link SegmentParam} contribution and intersecting the rest.
- *
- * @typeParam Path - The path pattern literal being decomposed
- *
- * @remarks
- * Splits `Path` at its first `/` into `Segment` + `Rest`, intersects
- * `SegmentParam<Segment>` with the recursive walk of `Rest`, and — once no
- * further `/` remains — resolves the final segment's own `SegmentParam`
- * directly. `SegmentParam` mirrors the runtime `classifySegment` grammar
- * exactly: a `:name` HEAD (identifier-char run, stopping at the first
- * non-identifier char) captures a param; a segment whose `:` is not at the
- * segment START (`a:b`) contributes nothing (the classification fix, §4); a
- * final `*name` wildcard captures the rest-of-path param the same way. A
- * fully parameterless `Path` resolves to `unknown` here (the intersection
- * identity every non-capturing segment contributes) — {@link PathParams}
- * flattens that down to a clean empty record. This type is exported so
- * {@link PathParams} (which flattens it into a clean mapped type for IDE
- * hovers) has a documented, testable recursive step; consumers reach for the
- * flattened {@link PathParams} form, never this raw recursion.
- */
-export declare type PathParamsRaw<Path extends string> = string extends Path ? Readonly<Record<string, string>> : Path extends `${infer Segment}/${infer Rest}` ? SegmentParam<Segment> & PathParamsRaw<Rest> : SegmentParam<Path>;
+ /**
+  * 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
+  * ```
+  */
+ export declare function parseMethod(value: string): Method | undefined;
 
-/**
- * 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
- * A bare object literal handed straight to {@link import('./types.js').DispatcherInterface}'s
- * `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
- * 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
- * registration site, not a stored, still-literal-typed record.
- *
- * @typeParam Path - The route path pattern literal (drives `context.params`
- *   via {@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({
- * 	method: 'GET',
- * 	path: '/users/:id',
- * 	handler: (_request, context) => new Response(context.params.id), // typed string
- * })
- * dispatcher.add(input)
- * ```
- */
-export declare function route<const Path extends string, TState = undefined>(input: RouteInput<Path, TState>): RouteInput<Path, TState>;
+ /**
+  * Extracts `{ name: string }` param records from a path pattern at the type
+  * level — the typed half of the path grammar.
+  *
+  * @typeParam Path - A route path pattern literal (`/users/:id/posts/:slug`,
+  *   `/files/*rest`, or a parameterless literal path)
+  *
+  * @remarks
+  * A `:name` segment contributes `{ name: string }`; a trailing `*name`
+  * wildcard (the grammar's only allowed wildcard position) contributes
+  * `{ name: string }` capturing the rest of the path; a parameterless pattern
+  * resolves to an empty record. Built over {@link PathParamsRaw} and flattened
+  * through an identity-mapped type so editor hovers show the resolved shape
+  * (`{ id: string; slug: string }`) rather than an unresolved intersection.
+  *
+  * @example
+  * ```ts
+  * type A = PathParams<'/users/:id/posts/:slug'> // { readonly id: string; readonly slug: string }
+  * type B = PathParams<'/files/*rest'>            // { readonly rest: string }
+  * type C = PathParams<'/health'>                 // Record<string, never>
+  * ```
+  */
+ export declare type PathParams<Path extends string> = {
+     readonly [K in keyof PathParamsRaw<Path>]: PathParamsRaw<Path>[K];
+ };
 
-/**
- * The ambient context a {@link RouteHandler} receives alongside the raw
- * `Request` — decoded params, the winning pattern, the parsed URL, and the
- * consumer's opaque per-request state.
- *
- * @typeParam Path - The route path pattern the handler was registered under
- *   (drives the typed shape of `params` via {@link PathParams})
- * @typeParam TState - The consumer's opaque per-request state type
- *
- * @remarks
- * - `params` — the decoded param record, typed from `Path` via
- *   {@link PathParams} (empty for a parameterless path).
- * - `pattern` — the winning REGISTERED pattern (matches
- *   {@link RouterMatch.path}), useful for logging/metrics.
- * - `url` — the request URL, already parsed once by the dispatcher.
- * - `state` — the consumer's per-request payload (logger, session, DI bag),
- *   threaded opaquely through `handle()` — the router never inspects it.
- */
-export declare interface RouteContext<Path extends string = string, TState = undefined> {
-    readonly params: PathParams<Path>;
-    readonly pattern: string;
-    readonly url: URL;
-    readonly state: TState;
-}
+ /**
+  * Performs recursive, unflattened param extraction for {@link PathParams} — walks a
+  * path pattern segment by segment (split on `/`), extracting each segment's
+  * {@link SegmentParam} contribution and intersecting the rest.
+  *
+  * @typeParam Path - The path pattern literal being decomposed
+  *
+  * @remarks
+  * Splits `Path` at its first `/` into `Segment` + `Rest`, intersects
+  * `SegmentParam<Segment>` with the recursive walk of `Rest`, and — after no
+  * further `/` remains — resolves the final segment's own `SegmentParam`
+  * directly. `SegmentParam` mirrors the runtime `classifySegment` grammar
+  * exactly: a `:name` HEAD (identifier-char run, stopping at the first
+  * non-identifier char) captures a param; a segment whose `:` is not at the
+  * segment START (`a:b`) contributes nothing (the classification fix); a
+  * final `*name` wildcard captures the rest-of-path param the same way. A
+  * fully parameterless `Path` resolves to `unknown` here (the intersection
+  * identity every non-capturing segment contributes) — {@link PathParams}
+  * flattens that down to a clean empty record. This type is exported so
+  * {@link PathParams} (which flattens it into a clean mapped type for IDE
+  * hovers) has a documented, testable recursive step; consumers reach for the
+  * flattened {@link PathParams} form, never this raw recursion.
+  */
+ export declare type PathParamsRaw<Path extends string> = string extends Path ? Readonly<Record<string, string>> : Path extends `${infer Segment}/${infer Rest}` ? SegmentParam<Segment> & PathParamsRaw<Rest> : SegmentParam<Path>;
 
-/**
- * One registered route in a {@link RouterInterface} — the `path` pattern plus
- * the opaque `meta` payload to return on a match, with an optional `name`.
- *
- * @typeParam Meta - The payload to carry on a match (opaque to the engine —
- *   a route handler + method on the `Dispatcher`, a component/loader
- *   reference on the `Navigator`)
- *
- * @remarks
- * - `path` — the `/`-prefixed route path pattern (`/users/:id`); compiled
- *   once at registration.
- * - `meta` — the opaque payload returned (as {@link RouterMatch.meta}) when
- *   this entry is the most-specific match. The engine never inspects it —
- *   the consumer's {@link AnswerHandler} predicate (the override seam)
- *   decides eligibility from it.
- * - `name` — an optional route identifier, carried through onto a match for
- *   consumers that build named links or debug output.
- */
-export declare interface RouteEntry<Meta> {
-    readonly path: string;
-    readonly meta: Meta;
-    readonly name?: string;
-}
+ /**
+  * Represents the ambient context a {@link RouteHandler} receives alongside the raw
+  * `Request` — decoded params, the winning pattern, the parsed URL, and the
+  * consumer's opaque per-request state.
+  *
+  * @typeParam Path - The route path pattern the handler was registered under
+  *   (drives the typed shape of `params` through {@link PathParams})
+  * @typeParam TState - The consumer's opaque per-request state type
+  *
+  * @remarks
+  * - `params` — the decoded param record, typed from `Path` through
+  *   {@link PathParams} (empty for a parameterless path).
+  * - `pattern` — the winning REGISTERED pattern (matches
+  *   {@link RouterMatch.path}), useful for logging/metrics.
+  * - `url` — the request URL, already parsed once by the dispatcher.
+  * - `state` — the consumer's per-request payload (logger, session, DI bag),
+  *   threaded opaquely through `handle()` — the router never inspects it.
+  */
+ export declare interface RouteContext<Path extends string = string, TState = undefined> {
+     readonly params: PathParams<Path>;
+     readonly pattern: string;
+     readonly url: URL;
+     readonly state: TState;
+ }
 
-/**
- * A route handler — receives the raw fetch `Request` plus its typed
- * {@link RouteContext} and returns (or resolves) a fetch `Response`.
- *
- * @typeParam Path - The route path pattern the handler is registered under
- * @typeParam TState - The consumer's opaque per-request state type
- *
- * @remarks
- * A handler throw propagates to the caller of `dispatcher.handle` — the
- * dispatcher never invents an error boundary; mapping throws to responses is
- * the consuming server's policy (§5.1).
- */
-export declare type RouteHandler<Path extends string = string, TState = undefined> = (request: Request, context: RouteContext<Path, TState>) => Response | Promise<Response>;
+ /**
+  * Represents one registered route in a {@link RouterInterface} — the `path` pattern plus
+  * the opaque `meta` payload to return on a match, with an optional `name`.
+  *
+  * @typeParam Meta - The payload to carry on a match (opaque to the engine —
+  *   a route handler + method on the `Dispatcher`, a component/loader
+  *   reference on the `Navigator`)
+  *
+  * @remarks
+  * - `path` — the `/`-prefixed route path pattern (`/users/:id`); compiled
+  *   once at registration.
+  * - `meta` — the opaque payload returned (as {@link RouterMatch.meta}) when
+  *   this entry is the most-specific match. The engine never inspects it —
+  *   the consumer's {@link AnswerHandler} predicate (the override seam)
+  *   decides eligibility from it.
+  * - `name` — an optional route identifier, carried through onto a match for
+  *   consumers that build named links or debug output.
+  */
+ export declare interface RouteEntry<Meta> {
+     readonly path: string;
+     readonly meta: Meta;
+     readonly name?: string;
+ }
 
-/**
- * One route registration input for {@link DispatcherInterface.add} — the
- * method-dimensioned counterpart of {@link RouteEntry}.
- *
- * @typeParam Path - The route path pattern literal (drives the typed
- *   `handler`'s `context.params` via {@link PathParams})
- * @typeParam TState - The consumer's opaque per-request state type
- *
- * @remarks
- * - `method` — the HTTP method this route answers.
- * - `path` — the `/`-prefixed route path pattern.
- * - `handler` — the {@link RouteHandler} invoked on a match.
- * - `name` — an optional route identifier, carried through onto a
- *   {@link RouterMatch}.
- */
-export declare interface RouteInput<Path extends string = string, TState = undefined> {
-    readonly method: Method;
-    readonly path: Path;
-    readonly handler: RouteHandler<Path, TState>;
-    readonly name?: string;
-}
+ /**
+  * Receives the raw fetch `Request` plus its typed {@link RouteContext} and returns (or resolves)
+  * a fetch `Response`.
+  *
+  * @typeParam Path - The route path pattern the handler is registered under
+  * @typeParam TState - The consumer's opaque per-request state type
+  *
+  * @remarks
+  * A handler throw propagates to the caller of `dispatcher.handle` — the
+  * dispatcher never invents an error boundary; mapping throws to responses is
+  * the consuming server's policy.
+  */
+ export declare type RouteHandler<Path extends string = string, TState = undefined> = (request: Request, context: RouteContext<Path, TState>) => Response | Promise<Response>;
 
-/**
- * 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
- *   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
- *   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}.
- *
- * @example
- * ```ts
- * const router = new Router<{ readonly page: string }>()
- * router.add({ path: '/users/:id', meta: { page: 'profile' } })
- * router.match('/users/7') // { path: '/users/:id', params: { id: '7' }, meta: { page: 'profile' } }
- * ```
- */
-export declare class Router<Meta> implements RouterInterface<Meta> {
-    #private;
-    constructor(options?: RouterOptions<Meta>);
-    get count(): number;
-    add(entry: RouteEntry<Meta>): void;
-    add(entries: ReadonlyArray<RouteEntry<Meta>>): void;
-    match(pathname: string, answers?: AnswerHandler<Meta>): RouterMatch<Meta> | undefined;
-    entries(): ReadonlyArray<RouteEntry<Meta>>;
-    entries(pathname: string): ReadonlyArray<RouteEntry<Meta>>;
-    group(prefix: string): GroupInterface<Meta>;
-    clear(): void;
-}
+ /**
+  * Represents one route registration input for {@link DispatcherInterface.add} — the
+  * method-dimensioned counterpart of {@link RouteEntry}.
+  *
+  * @typeParam Path - The route path pattern literal (drives the typed
+  *   `handler`'s `context.params` through {@link PathParams})
+  * @typeParam TState - The consumer's opaque per-request state type
+  *
+  * @remarks
+  * - `method` — the HTTP method this route answers.
+  * - `path` — the `/`-prefixed route path pattern.
+  * - `handler` — the {@link RouteHandler} invoked on a match.
+  * - `name` — an optional route identifier, carried through onto a
+  *   {@link RouterMatch}.
+  */
+ export declare interface RouteInput<Path extends string = string, TState = undefined> {
+     readonly method: Method;
+     readonly path: Path;
+     readonly handler: RouteHandler<Path, TState>;
+     readonly name?: string;
+ }
 
-/**
- * The `meta` payload a {@link DispatcherInterface} stores in its underlying
- * `Router` — what {@link RouterInterface.match} returns as
- * {@link RouterMatch.meta} on a dispatch hit.
- *
- * @typeParam TState - The consumer's opaque per-request state type
- *
- * @remarks
- * The handler is typed over `string` (not the original literal `Path`) at
- * storage — path-specific param typing is recovered at the call site through
- * {@link RouteInput}'s generic `Path`, not preserved in the stored record.
- */
-export declare interface RouteRecord<TState> {
-    readonly method: Method;
-    readonly handler: RouteHandler<string, TState>;
-    readonly name?: string;
-}
+ /**
+  * 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.** `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 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 through {@link joinPaths}.
+  *
+  * @example
+  * ```ts
+  * const router = new Router<{ readonly page: string }>()
+  * router.add({ path: '/users/:id', meta: { page: 'profile' } })
+  * router.match('/users/7') // { path: '/users/:id', params: { id: '7' }, meta: { page: 'profile' } }
+  * ```
+  */
+ export declare class Router<Meta> implements RouterInterface<Meta> {
+     #private;
+     constructor(options?: RouterOptions<Meta>);
+     get count(): number;
+     add(entry: RouteEntry<Meta>): void;
+     add(entries: ReadonlyArray<RouteEntry<Meta>>): void;
+     match(pathname: string, answers?: AnswerHandler<Meta>): RouterMatch<Meta> | undefined;
+     entries(): ReadonlyArray<RouteEntry<Meta>>;
+     entries(pathname: string): ReadonlyArray<RouteEntry<Meta>>;
+     group(prefix: string): GroupInterface<Meta>;
+     clear(): void;
+ }
 
-/**
- * The path-matching + registry engine contract (the §4.5 behavioral-interface
- * role for the one-class-per-file `Router`). Registers `{ path, meta, name? }`
- * entries (compiling each path once) and resolves a concrete pathname to the
- * MOST SPECIFIC matching entry — a literal segment beats a param beats a
- * wildcard at the earliest differing segment, registration-order-independent
- * (§4). The shared engine both the `Navigator` (browser) and the `Dispatcher`
- * (core, method-dimensioned) compose.
- *
- * @typeParam Meta - The opaque payload each entry carries and a match returns
- *
- * @remarks
- * - `count` — the number of registered entries.
- * - `add(entry)` / `add(entries)` — register ONE / MANY entries (§9.2 batch);
- *   each path is compiled once here. When constructed with a `key` option,
- *   an entry whose key already exists replaces the prior one in place;
- *   otherwise every entry is kept, even duplicate paths.
- * - `match(pathname, answers?)` — the MOST-SPECIFIC matching entry as a
- *   {@link RouterMatch} (its winning `path`, decoded `params`, `meta`, and
- *   `name`), or `undefined`. The optional {@link AnswerHandler} predicate
- *   filters candidates by `meta` first; omitted ⇒ every path match is
- *   eligible.
- * - `entries()` — ALL registered entries in registration order.
- * - `entries(pathname)` — only entries whose path matches `pathname` (the
- *   §9 plural accessor's filtered form; backs a consumer's allow/405 set).
- * - `group(prefix)` — a {@link GroupInterface} scoped under `prefix`; entries
- *   added through the group are registered on this same router with `prefix`
- *   prepended to each path.
- * - `clear()` — drop every entry (§10), leaving the router reusable.
- */
-export declare interface RouterInterface<Meta> {
-    readonly count: number;
-    add(entry: RouteEntry<Meta>): void;
-    add(entries: ReadonlyArray<RouteEntry<Meta>>): void;
-    match(pathname: string, answers?: AnswerHandler<Meta>): RouterMatch<Meta> | undefined;
-    entries(): ReadonlyArray<RouteEntry<Meta>>;
-    entries(pathname: string): ReadonlyArray<RouteEntry<Meta>>;
-    group(prefix: string): GroupInterface<Meta>;
-    clear(): void;
-}
+ /**
+  * Represents the `meta` payload a {@link DispatcherInterface} stores in its underlying
+  * `Router` — what {@link RouterInterface.match} returns as
+  * {@link RouterMatch.meta} on a dispatch hit.
+  *
+  * @typeParam TState - The consumer's opaque per-request state type
+  *
+  * @remarks
+  * The handler is typed over `string` (not the original literal `Path`) at
+  * storage — path-specific param typing is recovered at the call site through
+  * {@link RouteInput}'s generic `Path`, not preserved in the stored record.
+  */
+ export declare interface RouteRecord<TState> {
+     readonly method: Method;
+     readonly handler: RouteHandler<string, TState>;
+     readonly name?: string;
+ }
 
-/**
- * One matched route — the winning entry's PATTERN, decoded params, `meta`
- * payload, and optional `name`.
- *
- * @typeParam Meta - The payload the winning entry carries
- *
- * @remarks
- * What {@link RouterInterface.match} returns on a hit (`undefined` on a
- * miss). `path` is the winning entry's REGISTERED PATTERN (not the concrete
- * pathname that was matched) — useful for consumers that need to know which
- * route fired. `params` is a frozen `name → value` record (empty for a
- * parameterless path), each value URL-decoded with a malformed `%` escape
- * tolerated as a literal (§4, never throws). Plain data — no behavior.
- */
-export declare interface RouterMatch<Meta> {
-    readonly path: string;
-    readonly params: Readonly<Record<string, string>>;
-    readonly meta: Meta;
-    readonly name?: string;
-}
+ /**
+  * Represents the path-matching + registry engine contract (the behavioral-interface
+  * role for the one-class-per-file `Router`). Registers `{ path, meta, name? }`
+  * entries (compiling each path once) and resolves a concrete pathname to the most
+  * specific matching entry — a literal segment beats a param beats a wildcard at the
+  * earliest differing segment, registration-order-independent. The shared engine 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 is the guarded boundary and matching is the hot path: `add` validates
+  * each entry and throws, while `match` carries no guard of its own.
+  */
+ export declare interface RouterInterface<Meta> {
+     /** Holds the number of registered entries. */
+     readonly count: number;
+     /**
+      * Registers one entry, or many in one call (batch registration), compiling each path
+      * once; throws a `ContractError` on a malformed path.
+      *
+      * @remarks
+      * When the router was constructed with a `key` option, an entry whose key already
+      * exists replaces the prior one in place; otherwise every entry is kept, even a
+      * duplicate path.
+      */
+     add(entry: RouteEntry<Meta>): void;
+     add(entries: ReadonlyArray<RouteEntry<Meta>>): void;
+     /**
+      * Resolves the most-specific matching entry for a pathname, or `undefined` when
+      * nothing matches.
+      *
+      * @remarks
+      * A hit is a {@link RouterMatch} carrying the winning `path`, the decoded `params`,
+      * the `meta` payload, and the optional `name`. The optional {@link AnswerHandler}
+      * predicate filters candidates by `meta` first; omitted, every path match is eligible.
+      */
+     match(pathname: string, answers?: AnswerHandler<Meta>): RouterMatch<Meta> | undefined;
+     /**
+      * Lists every registered entry in registration order, or only those whose path
+      * matches a given pathname.
+      *
+      * @remarks
+      * The filtered form is the plural accessor's second shape, and it backs a consumer's
+      * allow set for a 405 answer.
+      */
+     entries(): ReadonlyArray<RouteEntry<Meta>>;
+     entries(pathname: string): ReadonlyArray<RouteEntry<Meta>>;
+     /**
+      * Returns a prefix-scoped registration handle over this router.
+      *
+      * @remarks
+      * Entries added through the group are registered on this same router with `prefix`
+      * prepended to each path.
+      */
+     group(prefix: string): GroupInterface<Meta>;
+     /** Drops every entry, leaving the router reusable. */
+     clear(): void;
+ }
 
-/**
- * Options for `createRouter` — an optional initial entry set, the case-
- * sensitivity toggle, and the dedup identity function.
- *
- * @typeParam Meta - The entry payload type
- *
- * @remarks
- * - `entries` — the initial `{ path, meta, name? }` entries to register (each
- *   path compiled once), equivalent to a bare `createRouter()` followed by
- *   `add(entries)`. Omitted ⇒ an empty router.
- * - `sensitive` — case-sensitive path matching (default `true`, §4). Set
- *   `false` to fold case during matching (`/Users` matches `/users`);
- *   registered patterns are never case-folded in storage, only in matching.
- * - `key` — an optional dedup identity function computed per entry
- *   (`RouteEntry<Meta> → string`). When provided, registering an entry whose
- *   key already exists REPLACES the prior entry in place (last write wins,
- *   no engine rebuild) instead of adding a second candidate. Omitted ⇒ every
- *   registered entry is kept, even duplicate paths.
- */
-export declare interface RouterOptions<Meta> {
-    readonly entries?: ReadonlyArray<RouteEntry<Meta>>;
-    readonly sensitive?: boolean;
-    readonly key?: (entry: RouteEntry<Meta>) => string;
-}
+ /**
+  * Represents one matched route — the winning entry's registered pattern, its decoded
+  * params, its `meta` payload, and its optional `name`.
+  *
+  * @typeParam Meta - The payload the winning entry carries
+  *
+  * @remarks
+  * What {@link RouterInterface.match} returns on a hit (`undefined` on a
+  * miss). `path` is the winning entry's REGISTERED PATTERN (not the concrete
+  * pathname that was matched) — useful for consumers that need to know which
+  * route fired. `params` is a frozen `name → value` record (empty for a
+  * parameterless path), each value URL-decoded with a malformed `%` escape
+  * tolerated as a literal, never throws. Plain data — no behavior.
+  */
+ export declare interface RouterMatch<Meta> {
+     readonly path: string;
+     readonly params: Readonly<Record<string, string>>;
+     readonly meta: Meta;
+     readonly name?: string;
+ }
 
-export declare type SegmentParam<Segment extends string> = Segment extends `:${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : {
-    readonly [K in Name]: string;
-} : unknown : Segment extends `*${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : {
-    readonly [K in Name]: string;
-} : unknown : unknown;
+ /**
+  * Represents the options for `createRouter` — an optional initial entry set, the
+  * case-sensitivity toggle, and the dedup identity function.
+  *
+  * @typeParam Meta - The entry payload type
+  *
+  * @remarks
+  * - `entries` — the initial `{ path, meta, name? }` entries to register (each
+  *   path compiled once), equivalent to a bare `createRouter()` followed by
+  *   `add(entries)`. Omitted ⇒ an empty router.
+  * - `sensitive` — case-sensitive path matching (default `true`). Set
+  *   `false` to fold case during matching (`/Users` matches `/users`);
+  *   registered patterns are never case-folded in storage, only in matching.
+  * - `key` — an optional dedup identity function computed per entry
+  *   (`RouteEntry<Meta> → string`). When provided, registering an entry whose
+  *   key already exists REPLACES the prior entry in place (last write wins,
+  *   no engine rebuild) instead of adding a second candidate. Omitted ⇒ every
+  *   registered entry is kept, even duplicate paths.
+  */
+ export declare interface RouterOptions<Meta> {
+     readonly entries?: ReadonlyArray<RouteEntry<Meta>>;
+     readonly sensitive?: boolean;
+     readonly key?: (entry: RouteEntry<Meta>) => string;
+ }
 
-export declare type TakeIdentifierTail<S extends string, Acc extends string> = S extends `${infer Head}${infer Tail}` ? Head extends IdentifierChar ? TakeIdentifierTail<Tail, `${Acc}${Head}`> : Acc : Acc;
+ /**
+  * Contributes one path segment's type-level param record — the type-level mirror of
+  * the runtime `classifySegment` and `compilePath` segment parser.
+  *
+  * @typeParam Segment - One `/`-split path segment literal
+  *
+  * @remarks
+  * A `:` head followed by an identifier captures that identifier, stopping at the first
+  * non-identifier char, so `:name.json` captures only `name`. A segment whose `:` is not
+  * at the segment start (`a:b`) is literal and captures nothing — the classification fix
+  * this type mirrors. A `*name` segment, valid only as the grammar's final segment,
+  * captures the identifier the same way. A non-capturing segment resolves to `unknown`
+  * (the intersection identity) rather than `Record<string, never>` — an index-signature
+  * type intersected with a later `{ id: string }` would otherwise conflict (`string` is
+  * not assignable to the index signature's `never`); {@link PathParams} normalizes the
+  * eventual `unknown` (parameterless) result down to a clean empty record.
+  */
+ export declare type SegmentParam<Segment extends string> = Segment extends `:${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : {
+     readonly [K in Name]: string;
+ } : unknown : Segment extends `*${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : {
+     readonly [K in Name]: string;
+ } : unknown : unknown;
 
-/**
- * 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).
- *
- * @example
- * ```ts
- * TIER_LITERAL > TIER_PARAM // true
- * ```
- */
-export declare const TIER_LITERAL = 2;
+ /**
+  * Consumes the identifier-continuation run at the front of a string literal, char by
+  * char, appending each onto the accumulator.
+  *
+  * @typeParam S - The string literal whose front is being consumed
+  * @typeParam Acc - The identifier characters taken so far
+  *
+  * @remarks
+  * Stops (returning `Acc` unchanged) at the first non-identifier char or at the end of
+  * the string, so the accumulator holds exactly the leading {@link IdentifierChar} run.
+  */
+ export declare type TakeIdentifierTail<S extends string, Acc extends string> = S extends `${infer Head}${infer Tail}` ? Head extends IdentifierChar ? TakeIdentifierTail<Tail, `${Acc}${Head}`> : Acc : Acc;
 
-/**
- * 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}
- * and {@link TIER_WILDCARD}.
- *
- * @example
- * ```ts
- * TIER_PARAM > TIER_WILDCARD // true
- * ```
- */
-export declare const TIER_PARAM = 1;
+ /**
+  * 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` (the path compiler in `helpers.ts`) when ranking candidate
+  * matches left-to-right at the earliest differing segment.
+  *
+  * @example
+  * ```ts
+  * TIER_LITERAL > TIER_PARAM // true
+  * ```
+  */
+ export declare const TIER_LITERAL = 2;
 
-/**
- * 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`).
- *
- * @example
- * ```ts
- * TIER_WILDCARD // 0
- * ```
- */
-export declare const TIER_WILDCARD = 0;
+ /**
+  * 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` (the path compiler in `helpers.ts`) alongside {@link TIER_LITERAL}
+  * and {@link TIER_WILDCARD}.
+  *
+  * @example
+  * ```ts
+  * TIER_PARAM > TIER_WILDCARD // true
+  * ```
+  */
+ export declare const TIER_PARAM = 1;
+
+ /**
+  * 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` (the path compiler in `helpers.ts`).
+  *
+  * @example
+  * ```ts
+  * TIER_WILDCARD // 0
+  * ```
+  */
+ export declare const TIER_WILDCARD = 0;
 
-export { }
+ export { }