@orkestrel/router 0.0.1 → 0.0.3

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

@@ -1,8 +1,1067 @@
-export type * from './types.js';
-export * from './constants.js';
-export * from './helpers.js';
-export * from './Dispatcher.js';
-export * from './DispatchGroup.js';
-export * from './Group.js';
-export * from './Router.js';
-export * from './factories.js';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+
+/**
+ * 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
+ *
+ * @remarks
+ * The single seam the philosophy's "one engine, native overrides" principle
+ * hangs on: the `Dispatcher` passes a method-check (`(record) => record.method
+ * === 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).
+ */
+export declare type AnswerHandler<Meta> = (meta: Meta) => boolean;
+
+/**
+ * Canonicalize a route path for REGISTRY IDENTITY — strip 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.
+ *
+ * @remarks
+ * Mirrors {@link compilePath}'s trailing-slash folding: `/users/` canonicalizes
+ * to `/users` (the two compile to the same regex and match the same
+ * pathnames), while the root `/` and the empty `''` are EXEMPT (a bare `/`
+ * already matches `/`; stripping it would break that). Pure and total — a path
+ * without a trailing slash returns unchanged.
+ *
+ * @param path - The route path pattern
+ * @returns The canonical path (one trailing slash removed, except `/` and `''`)
+ *
+ * @example
+ * ```ts
+ * canonicalizePath('/users/') // '/users'
+ * canonicalizePath('/users') // '/users'
+ * canonicalizePath('/') // '/'
+ * canonicalizePath('') // ''
+ * ```
+ */
+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.
+ *
+ * @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.
+ *
+ * @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)
+ * @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}
+ *
+ * @example
+ * ```ts
+ * classifySegment(':id', true) // 1 — TIER_PARAM
+ * classifySegment('*rest', true) // 0 — TIER_WILDCARD
+ * classifySegment('a:b', true) // 2 — TIER_LITERAL — the old bug's regression case
+ * classifySegment('users', false) // 2 — TIER_LITERAL
+ * ```
+ */
+export declare function classifySegment(segment: string, isFinal: boolean): number;
+
+/**
+ * Compare two route paths by SPECIFICITY — the comparator that picks the
+ * most-specific matching route (literal-over-param-over-wildcard,
+ * registration-order-independent).
+ *
+ * @remarks
+ * Compares the two paths' {@link computeSpecificity} vectors LEFT-TO-RIGHT and
+ * returns a standard `Array.sort` ordering: a NEGATIVE number when `a` is MORE
+ * specific than `b` (so a descending-specificity sort puts `a` first),
+ * positive when `b` is more specific, `0` when neither out-ranks the other
+ * across the compared segments. At the first index where the tiers differ,
+ * the higher tier wins; if one vector is a prefix of the other (different
+ * segment counts), the LONGER, more-segmented path is treated as more
+ * specific (a missing segment ranks below any real one).
+ *
+ * @param a - The first route path
+ * @param b - The second route path
+ * @returns A negative number when `a` is more specific, positive when `b` is, else `0`
+ *
+ * @example
+ * ```ts
+ * compareSpecificity('/users/me', '/users/:id') // negative — literal wins
+ * compareSpecificity('/users/:id', '/users/*rest') // negative — param beats wildcard
+ * compareSpecificity('/users/:id', '/users/:id') // 0 — equal specificity
+ * ```
+ */
+export declare function compareSpecificity(a: string, b: string): number;
+
+/**
+ * A compiled route path — the anchored regex plus its ordered param names.
+ *
+ * @remarks
+ * The once-per-path compile output of `compilePath` (U1 `helpers.ts`):
+ * `regex` is anchored (`^…$`) and matches the WHOLE pathname (with an
+ * optional trailing slash, §4), 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.
+ */
+export declare interface CompiledPath {
+    readonly regex: RegExp;
+    readonly params: readonly string[];
+}
+
+/**
+ * Compile a route path pattern into an anchored regex and its ordered param
+ * names.
+ *
+ * @remarks
+ * Splits the CANONICALIZED path into segments. Each `:name` segment becomes a
+ * `([^/]+)` 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
+ * 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
+ * a prefix.
+ *
+ * **Trailing slash is INSENSITIVE** (Express's `strict: false` default): a
+ * single trailing slash on the request path is OPTIONAL, so `/users` matches
+ * both `/users` and `/users/`, and `/users/:id` matches both `/users/me` and
+ * `/users/me/`. This is NOT prefix matching — a deeper path is still a
+ * distinct segment, so `/api` does not match `/api/users`. The ROOT `/` (and
+ * the empty pattern `''`) are EXEMPT — they are not stripped, so `/` stays
+ * `^/$` and `''` stays `^$`.
+ *
+ * `sensitive` (default `true`) controls case folding: `false` adds the `i`
+ * 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`)
+ * @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;
+
+/**
+ * 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[];
+
+/**
+ * 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>;
+
+/**
+ * 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>;
+
+/**
+ * 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;
+
+/**
+ * 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: readonly 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 `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'];
+};
+
+/**
+ * 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: readonly 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;
+}
+
+/**
+ * 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?: readonly 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 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: readonly RouteInput<string, TState>[]): void;
+    group(prefix: string): DispatchGroupInterface<TState>;
+}
+
+/**
+ * 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: readonly 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';
+};
+
+/**
+ * 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;
+
+/**
+ * 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: readonly RouteEntry<Meta>[]): void;
+    group(prefix: string): GroupInterface<Meta>;
+}
+
+/**
+ * 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: readonly 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';
+
+export declare type IdentifierHead<S extends string> = S extends `${infer Head}${infer Tail}` ? Head extends IdentifierStartChar ? TakeIdentifierTail<Tail, Head> : '' : '';
+
+/**
+ * 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' | '_';
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+/**
+ * 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';
+
+/**
+ * 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>;
+
+/**
+ * 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;
+
+/**
+ * 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];
+};
+
+/**
+ * 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>;
+
+/**
+ * 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>;
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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>;
+
+/**
+ * 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;
+}
+
+/**
+ * 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: readonly RouteEntry<Meta>[]): void;
+    match(pathname: string, answers?: AnswerHandler<Meta>): RouterMatch<Meta> | undefined;
+    entries(): readonly RouteEntry<Meta>[];
+    entries(pathname: string): readonly RouteEntry<Meta>[];
+    group(prefix: string): GroupInterface<Meta>;
+    clear(): void;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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: readonly RouteEntry<Meta>[]): void;
+    match(pathname: string, answers?: AnswerHandler<Meta>): RouterMatch<Meta> | undefined;
+    entries(): readonly RouteEntry<Meta>[];
+    entries(pathname: string): readonly RouteEntry<Meta>[];
+    group(prefix: string): GroupInterface<Meta>;
+    clear(): void;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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?: readonly RouteEntry<Meta>[];
+    readonly sensitive?: boolean;
+    readonly key?: (entry: RouteEntry<Meta>) => 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;
+
+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 **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;
+
+/**
+ * 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;
+
+/**
+ * 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;
+
+export { }