@orkestrel/router 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @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.
+
+## Install
+
+```sh
+npm install @orkestrel/router
+```
+
+## Requirements
+
+- Node.js >= 24
+- ESM-only (no CommonJS build)
+- Server and browser environments both supported
+
+## Status
+
+The public API is under design and not yet implemented — this package
+currently ships no runtime code. This README will gain an install snippet,
+usage examples, and a guide link once the design lands.
+
+## Package
+
+Published as three environment-scoped entry points per the `exports` field in
+`package.json`: a shared core, `./browser`, and `./server`.
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).

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

@@ -0,0 +1,62 @@
+import type { NavigatorEventMap, NavigatorInterface, NavigatorOptions } from './types.js';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { RouteEntry, RouterInterface, RouterMatch } from '@src/core';
+/**
+ * The headless History/hash navigation entity — composes one core
+ * `Router<RouteEntry<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` /
+ * `outlet` — the consumer owns rendering.
+ *
+ * @typeParam Meta - The opaque per-route payload a match carries back
+ *
+ * @remarks
+ * - **One shared engine.** Each `route.path` is registered on the SAME
+ *   `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).
+ * - **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
+ *   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
+ *   that resolves after its navigation was superseded (`signal.aborted`) is
+ *   discarded, same as a `false`/rejected verdict. A guard throw routes to
+ *   the `error` handler and vetoes. `stop()`/`destroy()` also abort the
+ *   pending handle.
+ * - **Hash vs history mode.** Hash mode (`history: false`, the default) binds
+ *   `hashchange`; history mode (`history: true`) binds `popstate` and, when
+ *   `intercept` is set, same-origin `<a>` click interception (a plain
+ *   left-click with no modifier keys, `target`, or `download` attribute).
+ *
+ * @example
+ * ```ts
+ * const navigator = new Navigator<{ readonly title: string }>({
+ * 	routes: [
+ * 		{ path: '/users/:id', meta: { title: 'User' } },
+ * 		{ path: '/tokens', meta: { title: 'Tokens' } },
+ * 	],
+ * })
+ * navigator.emitter.on('navigate', (match) => (document.title = match.meta.title))
+ * navigator.start() // resolves the current hash now, and on every hashchange
+ * navigator.navigate('/tokens')
+ * ```
+ */
+export declare class Navigator<Meta> implements NavigatorInterface<Meta> {
+    #private;
+    constructor(options: NavigatorOptions<Meta>);
+    get router(): RouterInterface<RouteEntry<Meta>>;
+    get emitter(): EmitterInterface<NavigatorEventMap<Meta>>;
+    get active(): RouterMatch<Meta> | undefined;
+    start(): void;
+    stop(): void;
+    navigate(path: string): void;
+    match(path: string): RouterMatch<Meta> | undefined;
+    destroy(): void;
+}

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

@@ -0,0 +1,33 @@
+import type { NavigatorInterface, NavigatorOptions } from './types.js';
+/**
+ * Create a {@link NavigatorInterface} — the headless History/hash navigation
+ * entity composing one core `Router<RouteEntry<Meta>>`.
+ *
+ * @remarks
+ * Prefer this over `new Navigator(...)` at call sites that only need the
+ * interface.
+ *
+ * @typeParam Meta - The opaque per-route payload a match carries back
+ * @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
+ *   `on`/`error` wiring
+ * @returns A live {@link NavigatorInterface} handle — call `start()` to begin
+ *   dispatching
+ *
+ * @example
+ * ```ts
+ * import { createNavigator } from '@src/browser'
+ *
+ * const navigator = createNavigator({
+ * 	routes: [
+ * 		{ path: '/users/:id', meta: { title: 'User' } },
+ * 		{ path: '/tokens', meta: { title: 'Tokens' } },
+ * 	],
+ * 	on: { navigate: (match) => (document.title = match.meta.title) },
+ * })
+ * navigator.start()
+ * ```
+ */
+export declare function createNavigator<Meta>(options: NavigatorOptions<Meta>): NavigatorInterface<Meta>;

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

@@ -0,0 +1,76 @@
+/**
+ * Extract the `/`-prefixed pathname from a `location.hash` value — strip 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'`
+ * — 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'`)
+ * @returns The `/`-prefixed pathname to match, or `''` for an empty / non-`#/` hash
+ *
+ * @example
+ * ```ts
+ * extractHashPath('#/users/7?x') // '/users/7'
+ * extractHashPath('#/tokens') // '/tokens'
+ * extractHashPath('') // '' — the Navigator falls back
+ * extractHashPath('#other') // '' — not a `#/` route hash
+ * ```
+ */
+export declare function extractHashPath(hash: string): string;
+/**
+ * Resolve 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.
+ *
+ * @remarks
+ * Hash mode (`history: false`) reads `location.hash` through
+ * {@link extractHashPath}. History mode (`history: true`) reads
+ * `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.
+ *
+ * @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 base - The history-mode path prefix to strip (ignored in hash mode;
+ *   omit for no prefix)
+ * @returns The `/`-prefixed pathname to match
+ *
+ * @example
+ * ```ts
+ * resolveLocationPath({ hash: '#/users/7', pathname: '/' }, false) // '/users/7'
+ * resolveLocationPath({ hash: '', pathname: '/app/users/7' }, true, '/app') // '/users/7'
+ * resolveLocationPath({ hash: '', pathname: '/app' }, true, '/app') // '/'
+ * resolveLocationPath({ hash: '', pathname: '/other/users' }, true, '/app') // '/other/users'
+ * ```
+ */
+export declare function resolveLocationPath(location: Pick<Location, 'hash' | 'pathname'>, history: boolean, base?: string): string;
+/**
+ * Find the nearest enclosing `<a>` element a DOM event originated from, by
+ * walking its composed path — the pure lookup behind history-mode link
+ * interception.
+ *
+ * @remarks
+ * Uses `event.composedPath()` (not `event.target`) so a click on a styled
+ * child INSIDE an anchor (an icon, a span) still resolves to the anchor.
+ * Total — never throws; returns `undefined` when no anchor is found on the
+ * path.
+ *
+ * @param event - The DOM event to search (typically a `click`)
+ * @returns The nearest enclosing `HTMLAnchorElement`, or `undefined`
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('click', (event) => {
+ * 	const anchor = findAnchor(event)
+ * 	if (anchor !== undefined) console.log(anchor.href)
+ * })
+ * ```
+ */
+export declare function findAnchor(event: Event): HTMLAnchorElement | undefined;

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

@@ -0,0 +1,4 @@
+export type * from './types.js';
+export * from './helpers.js';
+export * from './Navigator.js';
+export * from './factories.js';