@orkestrel/router 0.0.12 → 0.0.14

package/README.md

@@ -1,9 +1,14 @@
 # @orkestrel/router
 
-A typed request router for the `@orkestrel` line — the first `@orkestrel`
-package to ship both server and browser environments alongside its shared
-core. Built to sit beside `@orkestrel/contract` (validation) and
-`@orkestrel/emitter` (observable lifecycle), reusing both as it takes shape.
+> The typed request router: a path-matching engine (`Router`) that compiles route patterns,
+> extracts URL-decoded params, and resolves the most specific match, with a fetch-standard,
+> method-dimensioned dispatcher (`Dispatcher`), a headless History or hash `Navigator`, and a
+> `node:http` adapter all composing that same engine.
+
+Register routes on a `Router`, or hand them to a `Dispatcher` where they are
+method-dimensioned; reach for `createNavigator` in the browser and `createListener` behind
+`node:http`. Part of the `@orkestrel` line, built on `@orkestrel/contract` for validation,
+`@orkestrel/emitter` for the observable surface, and `@orkestrel/abort` for cancellation.
 
 ## Install
 
@@ -13,8 +18,8 @@ npm install @orkestrel/router
 
 ## Requirements
 
-- Node.js >= 24
-- ESM-only (no CommonJS build)
+- Node.js >= 22.12.0
+- ESM and CommonJS for the core and `./server` entries; the `./browser` entry is ESM only.
 - Server and browser environments both supported
 
 ## Usage
@@ -38,23 +43,21 @@ const dispatcher = createDispatcher<{ readonly userId: string }>({
 const response = await dispatcher.handle(new Request('http://x/users/7'), { userId: 'me' })
 ```
 
-`Router` is the shared registry-and-match engine — literal-over-param-over-wildcard
-precedence, trailing-slash folding, and tolerant percent-decoding — that both `Dispatcher`
-(fetch-standard, method-dimensioned) and the browser `Navigator` compose. Path params are
-inferred at the type level from the literal pattern via `PathParams`, and `route()` pins a
-`RouteInput`'s path so literal inference survives across call sites. The `./browser` entry
-adds `createNavigator` for headless History/hash navigation; the `./server` entry adds
-`buildRequest` / `sendResponse` / `createListener` for `node:http`.
+Path params are inferred at the type level from the literal pattern through the
+`PathParams` type, and the `defineRoute` function pins a `RouteInput`'s path so literal
+inference survives across call sites. The `./browser` entry adds the `createNavigator`
+function for headless History or hash navigation; the `./server` entry adds the
+`buildRequest`, `sendResponse`, and `createListener` functions for `node:http`.
 
 ## Guide
 
 For the full surface — the core `Router`, the `Dispatcher`, the browser `Navigator`, and the
 `node:http` server adapter — see
-[`guides/src/router.md`](guides/src/router.md).
+[`guides/router.md`](guides/router.md).
 
 ## Package
 
-Published as three environment-scoped entry points per the `exports` field in
+Published as environment-scoped entry points per the `exports` field in
 `package.json`: a shared core, `./browser`, and `./server`.
 
 ## License

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

@@ -1,33 +1,33 @@
-import { EmitterErrorHandler } from '@orkestrel/emitter';
-import { EmitterHooks } from '@orkestrel/emitter';
-import { EmitterInterface } from '@orkestrel/emitter';
-import { RouteEntry } from '@orkestrel/router';
-import { RouterInterface } from '@orkestrel/router';
-import { RouterMatch } from '@orkestrel/router';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { RouteEntry } from '@orkestrel/router';
+import type { RouterInterface } from '@orkestrel/router';
+import type { RouterMatch } from '@orkestrel/router';
 
 /**
- * Compute the registry key for a browser navigation route.
+ * Computes the canonical path key a `Navigator` registers a browser navigation
+ * route under.
  *
  * @remarks
- * Projects the nested route's path through the core engine's canonical
- * trailing-slash identity, so `/users` and `/users/` replace one another in
- * the Navigator's shared Router.
+ * Projects the route's path through the core engine's canonical trailing-slash
+ * identity, so `/users` and `/users/` replace one another in the Navigator's
+ * shared Router. The entry's `meta` payload is never read, so any payload type
+ * is accepted.
  *
- * @param entry - The outer Router entry carrying the Navigator route
- * @returns The nested route's canonical path
+ * @param entry - The Router entry carrying the Navigator route
+ * @returns The route's canonical path
  *
  * @example
  * ```ts
- * computeNavigationKey({ path: '/users/', meta: { path: '/users/' } }) // '/users'
+ * computeNavigationKey({ path: '/users/', meta: {} }) // '/users'
  * ```
  */
-export declare function computeNavigationKey(entry: RouteEntry<{
-    readonly path: string;
-}>): string;
+export declare function computeNavigationKey(entry: RouteEntry<unknown>): string;
 
 /**
- * Create a {@link NavigatorInterface} — the headless History/hash navigation
- * entity composing one core `Router<RouteEntry<Meta>>`.
+ * Creates a {@link NavigatorInterface} — the headless History/hash navigation
+ * entity composing one core `Router<Meta>`.
  *
  * @remarks
  * Prefer this over `new Navigator(...)` at call sites that only need the
@@ -37,7 +37,7 @@ export declare function computeNavigationKey(entry: RouteEntry<{
  * @param options - The `routes` to register, the `history` toggle (default
  *   `false`, hash mode), an optional `base` (history mode), an optional
  *   `fallback` path, an optional `guard` hook, opt-in link `intercept`
- *   (history mode), the `sensitive` case toggle, and the AGENTS §13 emitter
+ *   (history mode), the `sensitive` case toggle, and the Emitter pattern's
  *   `on`/`error` wiring
  * @returns A live {@link NavigatorInterface} handle — call `start()` to begin
  *   dispatching
@@ -59,17 +59,17 @@ export declare function computeNavigationKey(entry: RouteEntry<{
 export declare function createNavigator<Meta>(options: NavigatorOptions<Meta>): NavigatorInterface<Meta>;
 
 /**
- * Extract the `/`-prefixed pathname from a `location.hash` value — strip the
+ * Extracts the `/`-prefixed pathname from a `location.hash` value — strips the
  * leading `#` (keeping the route's own leading `/`) and any `?query` suffix.
  *
  * @remarks
- * The grammar this package matches everywhere is `/`-prefixed (§4 path
- * grammar), so a hash-mode location's `'#/users/7?x'` becomes `'/users/7'`
+ * The grammar this package matches everywhere is `/`-prefixed, so a hash-mode
+ * location's `'#/users/7?x'` becomes `'/users/7'`
  * — a hash pattern is expected to start `'#/'`; anything else (an empty hash,
  * or one that does not begin `'#/'`) yields `''` (the `Navigator` then falls
  * back). Total — never throws.
  *
- * @param hash - The raw `window.location.hash` value (e.g. `'#/users/7?x'`)
+ * @param hash - The raw `window.location.hash` value (for example `'#/users/7?x'`)
  * @returns The `/`-prefixed pathname to match, or `''` for an empty / non-`#/` hash
  *
  * @example
@@ -83,7 +83,7 @@ export declare function createNavigator<Meta>(options: NavigatorOptions<Meta>):
 export declare function extractHashPath(hash: string): string;
 
 /**
- * Find the nearest enclosing `<a>` element a DOM event originated from, by
+ * Finds the nearest enclosing `<a>` element a DOM event originated from, by
  * walking its composed path — the pure lookup behind history-mode link
  * interception.
  *
@@ -107,10 +107,10 @@ export declare function extractHashPath(hash: string): string;
 export declare function findAnchor(event: Event): HTMLAnchorElement | undefined;
 
 /**
- * The headless History/hash navigation entity — composes one core
- * `Router<RouteEntry<Meta>>`, resolving the current location on `start()` and
+ * Represents the headless History/hash navigation entity — composes one core
+ * `Router<Meta>`, resolving the current location on `start()` and
  * every subsequent navigation event, tracking `active`, and emitting
- * `navigate` through the core {@link Emitter} (AGENTS §13). No `render` /
+ * `navigate` through the core {@link Emitter}. No `render` /
  * `outlet` — the consumer owns rendering.
  *
  * @typeParam Meta - The opaque per-route payload a match carries back
@@ -120,14 +120,13 @@ export declare function findAnchor(event: Event): HTMLAnchorElement | undefined;
  *   `Router` machine the core `Dispatcher` composes, keyed for dedup by its
  *   {@link canonicalizePath} (last write wins, replace-in-place) — literal-
  *   over-param precedence, trailing-slash insensitivity, and
- *   `:param`/`*wildcard` extraction all come from that one engine (AGENTS
- *   §21).
+ *   `:param`/`*wildcard` extraction all come from that one shared engine.
  * - **Resolve pipeline.** Compute the `/`-prefixed pathname to match
  *   ({@link resolveLocationPath}) → {@link match} it → on a miss, match the
  *   `fallback` through the SAME engine → a fallback that ALSO matches nothing
  *   aborts any pending guarded navigation (a miss SUPERSEDES it, same as a
- *   newer navigation) and leaves `active` `undefined`, emitting nothing
- *   (§21-honest: no phantom match is fabricated) → the optional `guard` may
+ *   newer navigation) and leaves `active` `undefined`, emitting nothing —
+ *   honest to the one-shared-engine rule: no phantom match is fabricated → the optional `guard` may
  *   veto → on a verdict, `active` is set and `navigate` emitted.
  * - **Supersede-safe guard.** Every navigation mints an `@orkestrel/abort`
  *   handle, aborting the PREVIOUS navigation's handle first; a guard verdict
@@ -156,7 +155,7 @@ export declare function findAnchor(event: Event): HTMLAnchorElement | undefined;
 declare class Navigator_2<Meta> implements NavigatorInterface<Meta> {
     #private;
     constructor(options: NavigatorOptions<Meta>);
-    get router(): RouterInterface<RouteEntry<Meta>>;
+    get router(): RouterInterface<Meta>;
     get emitter(): EmitterInterface<NavigatorEventMap<Meta>>;
     get active(): RouterMatch<Meta> | undefined;
     start(): void;
@@ -168,7 +167,7 @@ declare class Navigator_2<Meta> implements NavigatorInterface<Meta> {
 export { Navigator_2 as Navigator }
 
 /**
- * The `Navigator`'s event map (AGENTS §13) — the single `navigate` signal a
+ * Represents the `Navigator`'s event map — the single `navigate` signal a
  * consumer observes.
  *
  * @typeParam Meta - The opaque per-route payload the resolved match carries
@@ -177,53 +176,70 @@ export { Navigator_2 as Navigator }
  * `navigate` fires once per successful resolution (start, hashchange/popstate,
  * `navigate()`, link interception) — never for a vetoed or superseded navigation
  * ({@link NavigatorOptions.guard}), and never when a miss's fallback also
- * misses (§21-honest: `active` is left `undefined`, nothing emitted).
+ * misses — honest to the one-shared-engine rule: `active` is left `undefined`, nothing emitted.
  */
 export declare type NavigatorEventMap<Meta> = {
     readonly navigate: readonly [match: RouterMatch<Meta>];
 };
 
 /**
- * The headless History/hash navigation entity contract (the §4.5 behavioral-
- * interface role for the one-class-per-file `Navigator`). Composes a core
- * `Router<RouteEntry<Meta>>`, resolves the current location on `start()` and
- * on every subsequent navigation event, tracks `active`, and emits
- * `navigate` through the AGENTS §13 {@link EmitterInterface}.
+ * Represents the headless History/hash navigation entity contract (the
+ * behavioral-interface role for the one-class-per-file `Navigator`). Composes a core
+ * `Router<Meta>`, resolves the current location on `start()` and on every subsequent
+ * navigation event, tracks `active`, and emits `navigate` through the
+ * {@link EmitterInterface}.
  *
  * @typeParam Meta - The opaque per-route payload a match carries back
  *
  * @remarks
- * - `router` — the underlying registry, exposed READONLY for introspection
- *   (the same object routes were registered on).
- * - `emitter` — the AGENTS §13 observable surface for {@link NavigatorEventMap}.
- * - `active` — the currently-resolved {@link RouterMatch}, or `undefined`
- *   before the first resolve (or when a miss's fallback also misses).
- * - `start()` — begin listening (`hashchange` in hash mode; `popstate` +
- *   optional link interception in history mode) and resolve the current
- *   location now. Idempotent — a second call is a no-op.
- * - `stop()` — stop listening. Idempotent.
- * - `navigate(path)` — navigate programmatically: sets `location.hash` (hash
- *   mode) or calls `history.pushState` (history mode), then resolves. A
- *   no-op hash navigation (already the active hash) resolves directly, since
- *   no `hashchange` would otherwise fire.
- * - `match(path)` — a PURE lookup through the underlying `Router`: no
- *   location read, no fallback, no guard, no emit.
- * - `destroy()` — `stop()` plus tear down the `#emitter` (AGENTS §13).
+ * Rendering stays outside this contract: a consumer subscribes to `navigate` and
+ * renders whatever the resolved match names.
  */
 export declare interface NavigatorInterface<Meta> {
-    readonly router: RouterInterface<RouteEntry<Meta>>;
+    /**
+     * Holds the underlying registry, exposed readonly for introspection — the same
+     * object the routes were registered on.
+     */
+    readonly router: RouterInterface<Meta>;
+    /** Holds the observable surface for {@link NavigatorEventMap}. */
     readonly emitter: EmitterInterface<NavigatorEventMap<Meta>>;
+    /**
+     * Holds the resolved {@link RouterMatch}, or `undefined` before the first resolve
+     * and whenever a miss's fallback also misses.
+     */
     readonly active: RouterMatch<Meta> | undefined;
+    /**
+     * Begins listening and resolves the current location — idempotent, so a second call
+     * is a no-op.
+     *
+     * @remarks
+     * Hash mode binds `hashchange`; history mode binds `popstate` and, where `intercept`
+     * is set, same-origin link interception.
+     */
     start(): void;
+    /** Stops listening and aborts any pending guard — idempotent. */
     stop(): void;
+    /**
+     * Navigates programmatically — sets `location.hash` in hash mode or calls
+     * `history.pushState` in history mode, then resolves.
+     *
+     * @remarks
+     * A hash navigation to the active hash resolves directly, because no `hashchange`
+     * would otherwise fire.
+     */
     navigate(path: string): void;
+    /**
+     * Looks one path up through the underlying `Router` — a pure lookup with no location
+     * read, no fallback, no guard, and no emit.
+     */
     match(path: string): RouterMatch<Meta> | undefined;
+    /** Stops listening and tears down the emitter. */
     destroy(): void;
 }
 
 /**
- * Options for `createNavigator` — the `routes` to dispatch between, the
- * navigation substrate, the optional guard hook, and the AGENTS §13 emitter
+ * Represents the options for `createNavigator` — the `routes` to dispatch between, the
+ * navigation substrate, the optional guard hook, and the Emitter pattern's
  * wiring.
  *
  * @typeParam Meta - The opaque payload each route may carry
@@ -240,20 +256,21 @@ export declare interface NavigatorInterface<Meta> {
  * - `fallback` — the route PATTERN to resolve when the current location
  *   matches NOTHING. Omitted ⇒ the first route's path. A `fallback` that
  *   itself matches no registered route leaves `active` `undefined` and emits
- *   nothing (§21-honest: no phantom match is fabricated).
+ *   nothing — honest to the one-shared-engine rule: no phantom match is fabricated.
  * - `guard` — `(to, from, signal) => boolean | Promise<boolean>`, called
  *   before a navigation commits; a `false`/rejected verdict, or one arriving
  *   after the navigation was SUPERSEDED (`signal.aborted`), is discarded —
  *   `active` stays unchanged and nothing is emitted. `signal` fires when a
  *   NEWER navigation starts (or on `stop`/`destroy`), so a slow async guard
  *   can cancel its own work off it. A throw routes to the `error` handler
- *   below and vetoes the navigation.
+ *   described later in this list and vetoes the navigation.
  * - `intercept` — opt-in same-origin `<a>` click interception (history mode
  *   only): a plain left-click on a same-origin link with no modifier keys,
  *   no `target`, and no `download` attribute is intercepted into `navigate`.
  * - `sensitive` — forwarded to the underlying `Router` (default `true`).
- * - `on` — initial `NavigatorEventMap` listeners (AGENTS §8/§13).
- * - `error` — the emitter's listener-error handler (AGENTS §13); ALSO the
+ * - `on` — initial `NavigatorEventMap` listeners (the Emitter pattern's
+ *   similar-surface pin).
+ * - `error` — the emitter's listener-error handler; ALSO the
  *   handler a thrown {@link guard} routes to (the Navigator's own pipeline,
  *   not a listener throw, so it is surfaced through the same channel).
  */
@@ -270,7 +287,7 @@ export declare interface NavigatorOptions<Meta> {
 }
 
 /**
- * Resolve the `/`-prefixed pathname to match for the CURRENT location, in
+ * Resolves the `/`-prefixed pathname to match for the current location, in
  * either navigation mode — the one seam `extractHashPath` (hash mode) and
  * history-mode base-stripping share.
  *
@@ -280,12 +297,12 @@ export declare interface NavigatorOptions<Meta> {
  * `location.pathname` and strips a leading `base` prefix when one is
  * configured: `base` itself maps to the root `'/'`; a pathname that is not
  * under `base` is returned unchanged (a base mismatch is not this helper's
- * concern — the `Navigator`'s match then simply misses). Total — never throws.
+ * concern — the `Navigator`'s match then misses). Total — never throws.
  *
  * @param location - The `hash` + `pathname` pair to resolve from (accepts a
  *   real `Location` or any object shaped the same, for pure unit testing)
- * @param history - The navigation substrate: `false` for hash mode, `true`
- *   for history mode
+ * @param history - If `true`, the pathname is read from `location.pathname`
+ *   with `base` stripped; if `false`, it is read from `location.hash`
  * @param base - The history-mode path prefix to strip (ignored in hash mode;
  *   omit for no prefix)
  * @returns The `/`-prefixed pathname to match

package/dist/src/browser/index.js

@@ -1,39 +1,41 @@
 import { canonicalizePath, createRouter, joinPaths } from "../core/index.js";
 import { createAbort } from "@orkestrel/abort";
 import { Emitter } from "@orkestrel/emitter";
-import { isFunction, isString } from "@orkestrel/contract";
+import { ContractError, isFunction, isString, preview } from "@orkestrel/contract";
 //#region src/browser/helpers.ts
 /**
-* Compute the registry key for a browser navigation route.
+* Computes the canonical path key a `Navigator` registers a browser navigation
+* route under.
 *
 * @remarks
-* Projects the nested route's path through the core engine's canonical
-* trailing-slash identity, so `/users` and `/users/` replace one another in
-* the Navigator's shared Router.
+* Projects the route's path through the core engine's canonical trailing-slash
+* identity, so `/users` and `/users/` replace one another in the Navigator's
+* shared Router. The entry's `meta` payload is never read, so any payload type
+* is accepted.
 *
-* @param entry - The outer Router entry carrying the Navigator route
-* @returns The nested route's canonical path
+* @param entry - The Router entry carrying the Navigator route
+* @returns The route's canonical path
 *
 * @example
 * ```ts
-* computeNavigationKey({ path: '/users/', meta: { path: '/users/' } }) // '/users'
+* computeNavigationKey({ path: '/users/', meta: {} }) // '/users'
 * ```
 */
 function computeNavigationKey(entry) {
-	return canonicalizePath(entry.meta.path);
+	return canonicalizePath(entry.path);
 }
 /**
-* Extract the `/`-prefixed pathname from a `location.hash` value — strip the
+* Extracts the `/`-prefixed pathname from a `location.hash` value — strips the
 * leading `#` (keeping the route's own leading `/`) and any `?query` suffix.
 *
 * @remarks
-* The grammar this package matches everywhere is `/`-prefixed (§4 path
-* grammar), so a hash-mode location's `'#/users/7?x'` becomes `'/users/7'`
+* The grammar this package matches everywhere is `/`-prefixed, so a hash-mode
+* location's `'#/users/7?x'` becomes `'/users/7'`
 * — a hash pattern is expected to start `'#/'`; anything else (an empty hash,
 * or one that does not begin `'#/'`) yields `''` (the `Navigator` then falls
 * back). Total — never throws.
 *
-* @param hash - The raw `window.location.hash` value (e.g. `'#/users/7?x'`)
+* @param hash - The raw `window.location.hash` value (for example `'#/users/7?x'`)
 * @returns The `/`-prefixed pathname to match, or `''` for an empty / non-`#/` hash
 *
 * @example
@@ -51,7 +53,7 @@ function extractHashPath(hash) {
 	return queryIndex === -1 ? withoutHash : withoutHash.slice(0, queryIndex);
 }
 /**
-* Resolve the `/`-prefixed pathname to match for the CURRENT location, in
+* Resolves the `/`-prefixed pathname to match for the current location, in
 * either navigation mode — the one seam `extractHashPath` (hash mode) and
 * history-mode base-stripping share.
 *
@@ -61,12 +63,12 @@ function extractHashPath(hash) {
 * `location.pathname` and strips a leading `base` prefix when one is
 * configured: `base` itself maps to the root `'/'`; a pathname that is not
 * under `base` is returned unchanged (a base mismatch is not this helper's
-* concern — the `Navigator`'s match then simply misses). Total — never throws.
+* concern — the `Navigator`'s match then misses). Total — never throws.
 *
 * @param location - The `hash` + `pathname` pair to resolve from (accepts a
 *   real `Location` or any object shaped the same, for pure unit testing)
-* @param history - The navigation substrate: `false` for hash mode, `true`
-*   for history mode
+* @param history - If `true`, the pathname is read from `location.pathname`
+*   with `base` stripped; if `false`, it is read from `location.hash`
 * @param base - The history-mode path prefix to strip (ignored in hash mode;
 *   omit for no prefix)
 * @returns The `/`-prefixed pathname to match
@@ -89,7 +91,7 @@ function resolveLocationPath(location, history, base) {
 	return pathname;
 }
 /**
-* Find the nearest enclosing `<a>` element a DOM event originated from, by
+* Finds the nearest enclosing `<a>` element a DOM event originated from, by
 * walking its composed path — the pure lookup behind history-mode link
 * interception.
 *
@@ -116,10 +118,10 @@ function findAnchor(event) {
 //#endregion
 //#region src/browser/Navigator.ts
 /**
-* The headless History/hash navigation entity — composes one core
-* `Router<RouteEntry<Meta>>`, resolving the current location on `start()` and
+* Represents the headless History/hash navigation entity — composes one core
+* `Router<Meta>`, resolving the current location on `start()` and
 * every subsequent navigation event, tracking `active`, and emitting
-* `navigate` through the core {@link Emitter} (AGENTS §13). No `render` /
+* `navigate` through the core {@link Emitter}. No `render` /
 * `outlet` — the consumer owns rendering.
 *
 * @typeParam Meta - The opaque per-route payload a match carries back
@@ -129,14 +131,13 @@ function findAnchor(event) {
 *   `Router` machine the core `Dispatcher` composes, keyed for dedup by its
 *   {@link canonicalizePath} (last write wins, replace-in-place) — literal-
 *   over-param precedence, trailing-slash insensitivity, and
-*   `:param`/`*wildcard` extraction all come from that one engine (AGENTS
-*   §21).
+*   `:param`/`*wildcard` extraction all come from that one shared engine.
 * - **Resolve pipeline.** Compute the `/`-prefixed pathname to match
 *   ({@link resolveLocationPath}) → {@link match} it → on a miss, match the
 *   `fallback` through the SAME engine → a fallback that ALSO matches nothing
 *   aborts any pending guarded navigation (a miss SUPERSEDES it, same as a
-*   newer navigation) and leaves `active` `undefined`, emitting nothing
-*   (§21-honest: no phantom match is fabricated) → the optional `guard` may
+*   newer navigation) and leaves `active` `undefined`, emitting nothing —
+*   honest to the one-shared-engine rule: no phantom match is fabricated → the optional `guard` may
 *   veto → on a verdict, `active` is set and `navigate` emitted.
 * - **Supersede-safe guard.** Every navigation mints an `@orkestrel/abort`
 *   handle, aborting the PREVIOUS navigation's handle first; a guard verdict
@@ -171,16 +172,36 @@ var Navigator = class {
 	#guard;
 	#error;
 	#intercept;
-	#hashListener;
-	#popListener;
+	#listener;
 	#clickListener;
 	#active;
 	#started = false;
 	#current;
 	constructor(options) {
-		if (options.guard !== void 0 && !isFunction(options.guard)) throw new TypeError(`a navigator guard must be a function, got ${JSON.stringify(options.guard)}`);
-		if (options.fallback !== void 0 && !isString(options.fallback)) throw new TypeError(`a navigator fallback must be a string, got ${JSON.stringify(options.fallback)}`);
-		if (options.base !== void 0 && !isString(options.base)) throw new TypeError(`a navigator base must be a string, got ${JSON.stringify(options.base)}`);
+		if (options.guard !== void 0 && !isFunction(options.guard)) throw new ContractError("a navigator guard must be a function when defined", {
+			code: "literal",
+			context: {
+				path: ["options", "guard"],
+				limit: "function or undefined",
+				received: preview(options.guard)
+			}
+		});
+		if (options.fallback !== void 0 && !isString(options.fallback)) throw new ContractError("a navigator fallback must be a string when defined", {
+			code: "literal",
+			context: {
+				path: ["options", "fallback"],
+				limit: "string or undefined",
+				received: preview(options.fallback)
+			}
+		});
+		if (options.base !== void 0 && !isString(options.base)) throw new ContractError("a navigator base must be a string when defined", {
+			code: "literal",
+			context: {
+				path: ["options", "base"],
+				limit: "string or undefined",
+				received: preview(options.base)
+			}
+		});
 		this.#history = options.history ?? false;
 		this.#base = options.base;
 		this.#intercept = options.intercept ?? false;
@@ -191,17 +212,12 @@ var Navigator = class {
 			...options.error === void 0 ? {} : { error: options.error }
 		});
 		this.#router = createRouter({
-			entries: options.routes.map((route) => ({
-				path: route.path,
-				meta: route,
-				...route.name === void 0 ? {} : { name: route.name }
-			})),
+			entries: options.routes,
 			...options.sensitive === void 0 ? {} : { sensitive: options.sensitive },
 			key: computeNavigationKey
 		});
 		this.#fallback = options.fallback ?? options.routes[0]?.path;
-		this.#hashListener = this.#resolve.bind(this);
-		this.#popListener = this.#resolve.bind(this);
+		this.#listener = this.#resolve.bind(this);
 		this.#clickListener = this.#intercepted.bind(this);
 	}
 	get router() {
@@ -216,9 +232,9 @@ var Navigator = class {
 	start() {
 		if (this.#started) return;
 		this.#started = true;
-		if (!this.#history) window.addEventListener("hashchange", this.#hashListener);
+		if (!this.#history) window.addEventListener("hashchange", this.#listener);
 		else {
-			window.addEventListener("popstate", this.#popListener);
+			window.addEventListener("popstate", this.#listener);
 			if (this.#intercept) document.addEventListener("click", this.#clickListener);
 		}
 		this.#resolve();
@@ -226,9 +242,9 @@ var Navigator = class {
 	stop() {
 		if (!this.#started) return;
 		this.#started = false;
-		if (!this.#history) window.removeEventListener("hashchange", this.#hashListener);
+		if (!this.#history) window.removeEventListener("hashchange", this.#listener);
 		else {
-			window.removeEventListener("popstate", this.#popListener);
+			window.removeEventListener("popstate", this.#listener);
 			if (this.#intercept) document.removeEventListener("click", this.#clickListener);
 		}
 		this.#current?.abort();
@@ -245,14 +261,7 @@ var Navigator = class {
 		this.#resolve();
 	}
 	match(path) {
-		const hit = this.#router.match(path);
-		if (hit === void 0) return void 0;
-		return {
-			path: hit.path,
-			params: hit.params,
-			meta: hit.meta.meta,
-			...hit.meta.name === void 0 ? {} : { name: hit.meta.name }
-		};
+		return this.#router.match(path);
 	}
 	destroy() {
 		this.stop();
@@ -327,8 +336,8 @@ var Navigator = class {
 //#endregion
 //#region src/browser/factories.ts
 /**
-* Create a {@link NavigatorInterface} — the headless History/hash navigation
-* entity composing one core `Router<RouteEntry<Meta>>`.
+* Creates a {@link NavigatorInterface} — the headless History/hash navigation
+* entity composing one core `Router<Meta>`.
 *
 * @remarks
 * Prefer this over `new Navigator(...)` at call sites that only need the
@@ -338,7 +347,7 @@ var Navigator = class {
 * @param options - The `routes` to register, the `history` toggle (default
 *   `false`, hash mode), an optional `base` (history mode), an optional
 *   `fallback` path, an optional `guard` hook, opt-in link `intercept`
-*   (history mode), the `sensitive` case toggle, and the AGENTS §13 emitter
+*   (history mode), the `sensitive` case toggle, and the Emitter pattern's
 *   `on`/`error` wiring
 * @returns A live {@link NavigatorInterface} handle — call `start()` to begin
 *   dispatching