@orkestrel/router 0.0.1

package/dist/src/core/index.js

@@ -0,0 +1,1014 @@
+//#region src/core/constants.ts
+/**
+* The complete set of HTTP methods a {@link import('./types.js').Dispatcher}
+* registers routes under — backs the registration guard (`add` rejects any
+* `method` outside this set) and the auto-`OPTIONS` `Allow` derivation.
+*
+* @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
+* ```
+*/
+var METHODS = Object.freeze(/* @__PURE__ */ new Set([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+]));
+/**
+* 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
+* ```
+*/
+var 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
+* ```
+*/
+var 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
+* ```
+*/
+var TIER_WILDCARD = 0;
+//#endregion
+//#region src/core/helpers.ts
+/**
+* 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
+* ```
+*/
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* 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('') // ''
+* ```
+*/
+function canonicalizePath(path) {
+	return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+}
+/**
+* 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
+* ```
+*/
+function compilePath(path, sensitive = true) {
+	const params = [];
+	const normalized = canonicalizePath(path);
+	const segments = normalized.split("/");
+	const pattern = segments.map((segment, index) => {
+		const isFinal = index === segments.length - 1;
+		if (!isFinal && /^\*[A-Za-z_]\w*/.test(segment)) throw new TypeError(`a wildcard segment ("${segment}") must be the final segment of a path pattern, got "${path}"`);
+		const tier = classifySegment(segment, isFinal);
+		if (tier === 0) {
+			params.push(segment.slice(1));
+			return "(.+)";
+		}
+		if (tier === 1) {
+			const name = /^:([A-Za-z_]\w*)/.exec(segment)?.[1] ?? "";
+			params.push(name);
+			return `([^/]+)${escapeRegExp(segment.slice(1 + name.length))}`;
+		}
+		return escapeRegExp(segment);
+	}).join("/");
+	const suffix = normalized === "/" || normalized === "" ? "" : "/?";
+	const flags = sensitive ? "" : "i";
+	return {
+		regex: new RegExp(`^${pattern}${suffix}$`, flags),
+		params
+	};
+}
+/**
+* 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
+* ```
+*/
+function decodeParam(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+/**
+* 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
+* ```
+*/
+function matchPath(compiled, pathname) {
+	const result = compiled.regex.exec(pathname);
+	if (result === null) return void 0;
+	const params = {};
+	for (let index = 0; index < compiled.params.length; index += 1) {
+		const name = compiled.params[index];
+		const value = result[index + 1];
+		if (name !== void 0 && value !== void 0) params[name] = decodeParam(value);
+	}
+	return Object.freeze(params);
+}
+/**
+* Classify one path segment into its specificity TIER — the SAME syntax
+* {@link compilePath} rewrites: a syntactically valid `:name` head is a PARAM
+* segment, a final `*name` is a WILDCARD segment, everything else (including a
+* literal segment that merely CONTAINS a `:` mid-string, e.g. `a:b`) is a
+* LITERAL segment.
+*
+* @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
+* ```
+*/
+function classifySegment(segment, isFinal) {
+	if (isFinal && /^\*[A-Za-z_]\w*$/.test(segment)) return 0;
+	if (/^:[A-Za-z_]\w*/.test(segment)) return 1;
+	return 2;
+}
+/**
+* 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
+* ```
+*/
+function computeSpecificity(path) {
+	const segments = canonicalizePath(path).split("/");
+	return segments.map((segment, index) => classifySegment(segment, index === segments.length - 1));
+}
+/**
+* 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
+* ```
+*/
+function compareSpecificity(a, b) {
+	const left = computeSpecificity(a);
+	const right = computeSpecificity(b);
+	const length = Math.max(left.length, right.length);
+	for (let index = 0; index < length; index += 1) {
+		const tierA = left[index] ?? -1;
+		const tierB = right[index] ?? -1;
+		if (tierA !== tierB) return tierB - tierA;
+	}
+	return 0;
+}
+/**
+* Narrow a raw `request.method` string into a typed {@link Method} — total,
+* never throws.
+*
+* @remarks
+* Guarded via {@link import('./constants.js').METHODS} (the seven registrable
+* HTTP methods); any other value (an unknown verb, non-uppercase casing)
+* resolves to `undefined` rather than throwing (§14 guard totality). Pure
+* leaf shared by the `Dispatcher`'s `handle` (§5.1 unknown-verb honesty) and
+* anywhere else a raw method string needs narrowing.
+*
+* @param value - The raw `request.method` string to narrow
+* @returns The matching {@link Method}, or `undefined` when `value` is not one
+*   of the seven registrable methods
+*
+* @example
+* ```ts
+* parseMethod('GET') // 'GET'
+* parseMethod('PURGE') // undefined
+* parseMethod('get') // undefined — case-sensitive
+* ```
+*/
+function parseMethod(value) {
+	if (value === "GET" || value === "POST" || value === "PUT" || value === "PATCH" || value === "DELETE" || value === "HEAD" || value === "OPTIONS") return value;
+}
+/**
+* Join a group prefix and a route path into one `/`-prefixed path, normalizing
+* 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'
+* ```
+*/
+function joinPaths(prefix, path) {
+	if (prefix === "") return path.startsWith("/") ? path : `/${path}`;
+	if (path === "") return prefix;
+	return `${prefix.endsWith("/") ? prefix.slice(0, -1) : prefix}${path.startsWith("/") ? path : `/${path}`}`;
+}
+//#endregion
+//#region node_modules/@orkestrel/emitter/dist/src/core/index.js
+/**
+* Extract the own enumerable keys of a mapped object, typed as its key union.
+*
+* @remarks
+* `Object.keys` widens its result to `string[]`, which breaks the key↔value
+* correlation a mapped type (like `EmitterHooks<TMap>`) otherwise guarantees.
+* A `for…in` push into a `keyof`-typed array narrows the result back,
+* type-safely and with no assertion.
+*
+* @typeParam T - The object shape whose keys are extracted.
+* @param object - The object to read keys from.
+* @returns The object's own enumerable keys, typed as `(keyof T)[]`.
+*
+* @example
+* ```ts
+* import { extractKeys } from '@src/core'
+*
+* const hooks = { tick: () => {}, done: () => {} }
+* extractKeys(hooks) // ['tick', 'done']
+* extractKeys({}) // []
+* ```
+*/
+function extractKeys(object) {
+	const collected = [];
+	for (const key in object) collected.push(key);
+	return collected;
+}
+Object.freeze([
+	"null",
+	"boolean",
+	"object",
+	"array",
+	"number",
+	"integer",
+	"string"
+]);
+/** Determine whether a value is callable. */
+function isFunction$1(value) {
+	return typeof value === "function";
+}
+/**
+* A typed synchronous event emitter — the foundational observable primitive of
+* the codebase (AGENTS §13). Stateful entities OWN one as a `#emitter` field and
+* expose it through `readonly emitter`; they never inherit from it.
+*
+* @typeParam TMap - The event map: each event name to the argument tuple its
+*   listeners receive.
+*
+* @remarks
+* - **Synchronous.** `emit` invokes listeners in registration order, in the
+*   current tick.
+* - **Listener isolation.** A throwing listener never stops its siblings: every
+*   listener runs, and a throw is routed to the `error` handler
+*   ({@link EmitterOptions.error}) — never rethrown. Every throwing listener
+*   surfaces (not just the first), and with no `error` handler a throw is swallowed
+*   silently. The `error` handler runs inside its own try/catch, so a throwing
+*   error-handler is swallowed too (anti-recursion — it cannot escape or re-enter).
+* - **Per-event storage.** Listeners live in a per-event `Set`, so every public
+*   method is precisely typed with no assertions.
+* - **Destroyed → no-op.** After `destroy()`, `on` / `once` / `emit` do nothing
+*   and `destroyed` is `true`.
+*
+* @example
+* ```ts
+* type CounterEventMap = {
+* 	tick: readonly [count: number]
+* 	done: readonly []
+* }
+*
+* const emitter = new Emitter<CounterEventMap>({
+* 	on: { done: () => stop() },
+* 	error: (error, event) => log(`listener for ${event} threw`, error),
+* })
+* emitter.on('tick', (count) => render(count))
+* emitter.emit('tick', 1)
+* ```
+*/
+var Emitter = class {
+	#destroyed = false;
+	#listeners = {};
+	#wrappers = {};
+	#error;
+	constructor(options) {
+		const error = options?.error;
+		this.#error = isFunction$1(error) ? error : void 0;
+		const hooks = options?.on;
+		if (hooks !== void 0) this.#wire(hooks);
+	}
+	get destroyed() {
+		return this.#destroyed;
+	}
+	on(event, handler) {
+		if (this.#destroyed) return;
+		(this.#listeners[event] ??= /* @__PURE__ */ new Set()).add(handler);
+	}
+	once(event, handler) {
+		if (this.#destroyed) return;
+		const pending = this.#wrappers[event] ??= /* @__PURE__ */ new Map();
+		const wrapper = (...args) => {
+			this.#listeners[event]?.delete(wrapper);
+			const wrappers = pending.get(handler);
+			wrappers?.delete(wrapper);
+			if (wrappers !== void 0 && wrappers.size === 0) pending.delete(handler);
+			handler(...args);
+		};
+		const wrappers = pending.get(handler) ?? /* @__PURE__ */ new Set();
+		wrappers.add(wrapper);
+		pending.set(handler, wrappers);
+		this.on(event, wrapper);
+	}
+	off(event, handler) {
+		const listeners = this.#listeners[event];
+		const wrappers = this.#wrappers[event];
+		const pending = wrappers?.get(handler);
+		if (pending !== void 0) {
+			for (const wrapper of pending) listeners?.delete(wrapper);
+			wrappers?.delete(handler);
+		}
+		listeners?.delete(handler);
+	}
+	emit(event, ...args) {
+		if (this.#destroyed) return;
+		const listeners = this.#listeners[event];
+		if (listeners === void 0) return;
+		for (const handler of [...listeners]) try {
+			handler(...args);
+		} catch (error) {
+			this.#surface(error, event);
+		}
+	}
+	count(event) {
+		if (event !== void 0) return this.#listeners[event]?.size ?? 0;
+		let total = 0;
+		for (const set of Object.values(this.#listeners)) total += set?.size ?? 0;
+		return total;
+	}
+	clear(event) {
+		if (event !== void 0) {
+			delete this.#listeners[event];
+			delete this.#wrappers[event];
+			return;
+		}
+		this.#listeners = {};
+		this.#wrappers = {};
+	}
+	destroy() {
+		this.#listeners = {};
+		this.#wrappers = {};
+		this.#error = void 0;
+		this.#destroyed = true;
+	}
+	#surface(error, event) {
+		const handler = this.#error;
+		if (handler === void 0) return;
+		try {
+			handler(error, String(event));
+		} catch {}
+	}
+	#wire(hooks) {
+		for (const event of extractKeys(hooks)) {
+			const handler = hooks[event];
+			if (isFunction$1(handler)) this.on(event, handler);
+		}
+	}
+};
+Object.freeze([
+	"null",
+	"boolean",
+	"object",
+	"array",
+	"number",
+	"integer",
+	"string"
+]);
+/** Determine whether a value is a string. */
+function isString(value) {
+	return typeof value === "string";
+}
+/** Determine whether a value is callable. */
+function isFunction(value) {
+	return typeof value === "function";
+}
+//#endregion
+//#region src/core/Group.ts
+/**
+* A prefix-scoped registration handle over a {@link import('./Router.js').Router} —
+* pure string composition (AGENTS §4.2.2), no independent state or storage.
+*
+* @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'
+* ```
+*/
+var Group = class Group {
+	prefix;
+	#parent;
+	constructor(parent, prefix) {
+		this.#parent = parent;
+		this.prefix = prefix;
+	}
+	add(input) {
+		const inputs = Array.isArray(input) ? input : [input];
+		this.#parent.add(inputs.map((entry) => ({
+			...entry,
+			path: joinPaths(this.prefix, entry.path)
+		})));
+	}
+	group(prefix) {
+		return new Group(this.#parent, joinPaths(this.prefix, prefix));
+	}
+};
+//#endregion
+//#region src/core/Router.ts
+/**
+* The path-matching + registry engine — registers `{ path, meta, name? }`
+* entries (compiling each path once) and resolves a concrete pathname to the
+* MOST SPECIFIC matching entry. The shared machine both the `Navigator`
+* (browser) and the `Dispatcher` (core, method-dimensioned) compose.
+*
+* @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' } }
+* ```
+*/
+var Router = class {
+	#entries = [];
+	#compiled = [];
+	#sensitive;
+	#key;
+	#index = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.#sensitive = options?.sensitive ?? true;
+		this.#key = options?.key;
+		if (options?.entries !== void 0) this.add(options.entries);
+	}
+	get count() {
+		return this.#entries.length;
+	}
+	add(input) {
+		const inputs = Array.isArray(input) ? input : [input];
+		for (const entry of inputs) this.#register(entry);
+	}
+	match(pathname, answers) {
+		let best;
+		for (let index = 0; index < this.#entries.length; index += 1) {
+			const entry = this.#entries[index];
+			const compiled = this.#compiled[index];
+			if (entry === void 0 || compiled === void 0) continue;
+			if (answers !== void 0 && !answers(entry.meta)) continue;
+			const params = matchPath(compiled, pathname);
+			if (params === void 0) continue;
+			if (best === void 0 || compareSpecificity(entry.path, best.entry.path) < 0) best = {
+				entry,
+				params
+			};
+		}
+		if (best === void 0) return void 0;
+		return {
+			path: best.entry.path,
+			params: best.params,
+			meta: best.entry.meta,
+			name: best.entry.name
+		};
+	}
+	entries(pathname) {
+		if (pathname === void 0) return [...this.#entries];
+		const out = [];
+		for (let index = 0; index < this.#entries.length; index += 1) {
+			const entry = this.#entries[index];
+			const compiled = this.#compiled[index];
+			if (entry === void 0 || compiled === void 0) continue;
+			if (matchPath(compiled, pathname) !== void 0) out.push(entry);
+		}
+		return out;
+	}
+	group(prefix) {
+		return new Group(this, prefix);
+	}
+	clear() {
+		this.#entries.length = 0;
+		this.#compiled.length = 0;
+		this.#index.clear();
+	}
+	#register(entry) {
+		if (!isString(entry.path) || !entry.path.startsWith("/")) throw new TypeError(`a route path must be a string starting with "/", got ${JSON.stringify(entry.path)}`);
+		const compiled = compilePath(entry.path, this.#sensitive);
+		if (this.#key === void 0) {
+			this.#entries.push(entry);
+			this.#compiled.push(compiled);
+			return;
+		}
+		const key = this.#key(entry);
+		const existing = this.#index.get(key);
+		if (existing !== void 0) {
+			this.#entries[existing] = entry;
+			this.#compiled[existing] = compiled;
+			return;
+		}
+		this.#index.set(key, this.#entries.length);
+		this.#entries.push(entry);
+		this.#compiled.push(compiled);
+	}
+};
+//#endregion
+//#region src/core/DispatchGroup.ts
+/**
+* A prefix-scoped registration handle over a
+* {@link import('./Dispatcher.js').Dispatcher} — the method-dimensioned
+* counterpart of `Group` (`Group.ts`).
+*
+* @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') })
+* ```
+*/
+var DispatchGroup = class DispatchGroup {
+	prefix;
+	#parent;
+	constructor(parent, prefix) {
+		this.#parent = parent;
+		this.prefix = prefix;
+	}
+	add(input) {
+		const inputs = Array.isArray(input) ? input : [input];
+		this.#parent.add(inputs.map((route) => ({
+			...route,
+			path: joinPaths(this.prefix, route.path)
+		})));
+	}
+	group(prefix) {
+		return new DispatchGroup(this.#parent, joinPaths(this.prefix, prefix));
+	}
+};
+//#endregion
+//#region src/core/Dispatcher.ts
+/**
+* The fetch-standard, method-dimensioned dispatch entity — layers HTTP method
+* dispatch and web-standard `Request`/`Response` handling over one internal
+* `Router<RouteRecord<TState>>`. The core machine the eventual server face
+* (§7) and any fetch-native runtime consumes directly.
+*
+* @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' })
+* ```
+*/
+var Dispatcher = class {
+	router;
+	#emitter;
+	#unmatched;
+	#unmethoded;
+	constructor(options) {
+		this.router = new Router({
+			sensitive: options?.sensitive,
+			key: (entry) => `${entry.meta.method} ${canonicalizePath(entry.path)}`
+		});
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#unmatched = options?.unmatched ?? ((_request) => new Response("Not Found", { status: 404 }));
+		this.#unmethoded = options?.unmethoded ?? ((_request, allow) => new Response("Method Not Allowed", {
+			status: 405,
+			headers: { Allow: allow.join(", ") }
+		}));
+		if (options?.routes !== void 0) this.add(options.routes);
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	add(input) {
+		const inputs = Array.isArray(input) ? input : [input];
+		for (const route of inputs) this.#register(route);
+	}
+	group(prefix) {
+		return new DispatchGroup(this, prefix);
+	}
+	match(method, pathname) {
+		const hit = this.router.match(pathname, (meta) => meta.method === method);
+		if (hit !== void 0) return {
+			status: "matched",
+			match: hit
+		};
+		if (method === "HEAD") {
+			const getHit = this.router.match(pathname, (meta) => meta.method === "GET");
+			if (getHit !== void 0) return {
+				status: "matched",
+				match: getHit
+			};
+		}
+		const allow = this.#allow(pathname);
+		if (allow.length === 0) return { status: "unmatched" };
+		return {
+			status: "unmethoded",
+			allow
+		};
+	}
+	async handle(request, state) {
+		const url = new URL(request.url);
+		const pathname = url.pathname;
+		const requested = request.method;
+		const method = parseMethod(requested);
+		if (method === void 0) {
+			const allow = this.#allow(pathname);
+			if (allow.length === 0) {
+				this.#emitter.emit("miss", requested, pathname, "unmatched");
+				return this.#unmatched(request);
+			}
+			this.#emitter.emit("miss", requested, pathname, "unmethoded");
+			return this.#unmethoded(request, allow);
+		}
+		const result = this.match(method, pathname);
+		if (result.status === "matched") return this.#respondMatched(request, state, method, result.match, url);
+		if (result.status === "unmethoded") {
+			if (method === "OPTIONS") return this.#respondAutoOptions(pathname, result.allow);
+			this.#emitter.emit("miss", method, pathname, "unmethoded");
+			return this.#unmethoded(request, result.allow);
+		}
+		this.#emitter.emit("miss", method, pathname, "unmatched");
+		return this.#unmatched(request);
+	}
+	destroy() {
+		this.#emitter.destroy();
+	}
+	#register(input) {
+		if (!isFunction(input.handler)) throw new TypeError(`a route handler must be a function, got ${JSON.stringify(input.handler)}`);
+		if (!isString(input.method) || !METHODS.has(input.method)) throw new TypeError(`a route method must be one of ${[...METHODS].join(", ")}, got ${JSON.stringify(input.method)}`);
+		this.router.add({
+			path: input.path,
+			name: input.name,
+			meta: {
+				method: input.method,
+				handler: input.handler,
+				name: input.name
+			}
+		});
+	}
+	#allow(pathname) {
+		const entries = this.router.entries(pathname);
+		const methods = /* @__PURE__ */ new Set();
+		for (const entry of entries) methods.add(entry.meta.method);
+		if (methods.has("GET")) methods.add("HEAD");
+		return [...methods];
+	}
+	async #respondMatched(request, state, method, match, url) {
+		this.#emitter.emit("match", method, match.path);
+		const context = {
+			params: match.params,
+			pattern: match.path,
+			url,
+			state
+		};
+		const response = await match.meta.handler(request, context);
+		if (method === "HEAD" && match.meta.method === "GET") return new Response(null, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: response.headers
+		});
+		return response;
+	}
+	#respondAutoOptions(pathname, allow) {
+		this.#emitter.emit("match", "OPTIONS", pathname);
+		const headers = new Headers({ Allow: [...allow, "OPTIONS"].join(", ") });
+		return new Response(null, {
+			status: 204,
+			headers
+		});
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* 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' } }
+* ```
+*/
+function createRouter(options) {
+	return new Router(options);
+}
+/**
+* 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' })
+* ```
+*/
+function createDispatcher(options) {
+	return new Dispatcher(options);
+}
+//#endregion
+export { DispatchGroup, Dispatcher, Group, METHODS, Router, TIER_LITERAL, TIER_PARAM, TIER_WILDCARD, canonicalizePath, classifySegment, compareSpecificity, compilePath, computeSpecificity, createDispatcher, createRouter, decodeParam, escapeRegExp, joinPaths, matchPath, parseMethod };
+
+//# sourceMappingURL=index.js.map