white-label-router 4.0.0 → 5.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 bshack
+
+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

@@ -1,82 +1,129 @@
 # white-label-router
 
-`white-label-router` is a small client-side router built on the browser History API. It maps URL prefixes to functions or view lifecycle objects, intercepts links marked with `data-pushstate`, handles browser back/forward navigation, and can receive navigation requests through a mediator.
+> Turn URLs into application intent without hiding the web platform.
+
+`white-label-router` is a framework-independent TypeScript router for browser and server applications. It progressively enhances real links with the History API in the browser and dispatches explicit request URLs on the server through the same matching, guard, lifecycle, query, focus, and mediator contracts.
+
+[Documentation](https://whitelabeljs.org/docs/router/) · [API reference](https://whitelabeljs.org/api/#router) · [Demo site](https://whitelabeljs.org/)
+
+**Responsibility:** translate navigation into application intent. Nothing more.
+
+## Why it exists
+
+White Label keeps URLs, links, history, and server requests visible rather than replacing them with a proprietary navigation model. Router adds the application boundary around those platform primitives while preserving normal browser behavior whenever enhancement does not apply.
+
+Use it independently or compose it with the rest of White Label:
+
+- [`white-label-mediator`](https://github.com/bshack/white-label-mediator) can publish `router:navigate` intent.
+- [`white-label-model`](https://github.com/bshack/white-label-model) can own state changed by a route.
+- [`white-label-view`](https://github.com/bshack/white-label-view) can own the rendering lifecycle started by a route.
+- [`generator-white-label`](https://github.com/bshack/white-label) demonstrates the complete composition.
+
+The package has no runtime dependency on the other White Label packages.
 
 ## Requirements
 
-- Node.js `^22.18.0` or `>=24.11.0` for installation and development
-- A browser environment with `window.history`, `window.location`, and standard DOM events at runtime
-- Server fallback configuration that serves the application entry page for client-managed URLs
+- Node.js `^22.18.0` or `>=24.11.0` for installation, development, and server execution.
+- npm, Yarn, and pnpm are supported for installation; see [`PACKAGE_MANAGERS.md`](PACKAGE_MANAGERS.md).
+- Browser History API, location, and standard DOM events only when using browser navigation behavior.
+- A directly requestable server route for every public browser route so enhanced links remain meaningful without JavaScript.
 
-## Install and import
+## Install
 
 ```sh
 npm install white-label-router
+# or: yarn add white-label-router
+# or: pnpm add white-label-router
 ```
 
+The same entrypoint is used in browsers and servers:
+
 ```js
 import Router from 'white-label-router';
 ```
 
-## Complete example
+## One route contract, two runtimes
 
-```js
-import Router from 'white-label-router';
+### Browser
 
-class ApplicationRouter extends Router {
-    constructor() {
-        super();
+Omit the URL to dispatch the current browser location and attach browser navigation listeners:
 
-        this.scope = document.querySelector('main');
-        this.routes = {
-            '/products': (scope, location) => {
-                scope.textContent = `Product: ${location.data.url[0] || 'all'}`;
-            },
-            '/account': {
-                title: 'Your account',
-                secure: () => Boolean(window.currentUser),
-                view: {
-                    initialize: (scope, location) => {
-                        scope.textContent = 'Account';
-                        console.log(location.data.query);
-                    },
-                    destroy: () => {
-                        console.log('Leaving account');
-                    }
-                }
-            },
-            defaultRoute: () => {
-                console.log('No configured route matched.');
-            }
-        };
-    }
-}
+```js
+const router = new Router();
+router.routes = {
+    '/products': (_scope, location) => console.log(location.data.url),
+    defaultRoute: () => true
+};
 
-const router = new ApplicationRouter();
+// initialize() dispatches the current URL and returns the router for chaining.
 router.initialize();
 ```
 
-At startup, `initialize()` reads the current path and query string, registers document click and browser `popstate` listeners, and navigates to the matching route.
+### Server
+
+Pass the request URL explicitly. No `window` or `document` is required:
+
+```js
+const router = new Router();
+router.routes = {
+    '/products': (_scope, location) => console.log(location.data.url),
+    defaultRoute: () => true
+};
+router.initialize('/products/42?color=blue');
+```
+
+Browser-only history, click interception, focus, and document-title effects are skipped on the server. Scope mutable routing state per request when appropriate.
+
+## Serverless and function runtimes
+
+Pass the incoming request URL explicitly when Router runs inside a serverless function. The server path uses the same matching, query parsing, guards, and route lifecycle without requiring `window` or `document`.
+
+```js
+const requestUrl = new URL(request.url);
+const router = new Router();
+router.routes = routes;
+router.initialize(`${requestUrl.pathname}${requestUrl.search}`);
+```
+
+Create a request-scoped Router when its location state, mediator, route lifecycle, or other mutable configuration belongs to one invocation. Warm function processes may serve sequential or overlapping requests, so sharing one mutable Router can mix location/lifecycle state unless that process-wide lifetime is intentional.
+
+Router handles **application routing inside the invocation**. It does not replace API Gateway routes, CDN routing, Vercel/Netlify/Cloudflare route configuration, load balancing, authentication infrastructure, or other cloud request plumbing.
+
+The package currently documents Node.js as its supported server runtime. Its DOM-free server path uses standard URL APIs, but that is not a blanket compatibility claim for every edge provider; verify the actual target runtime before deployment.
+
+## Progressive enhancement first
+
+Public navigation should remain a real link:
+
+```html
+<a href="/products/42" data-pushstate>View product 42</a>
+```
+
+`data-pushstate` opts the link into client-side enhancement. Links without it retain native behavior. Modified clicks, non-left clicks, downloads, alternate targets, and cross-origin URLs also remain native.
+
+This preserves keyboard behavior, context menus, no-JavaScript navigation, and crawler discovery. Public routes should have directly requestable URLs that return meaningful HTML and appropriate title, description, canonical, and robots metadata.
 
 ## Define routes
 
-A route may be a function:
+A route can be a function:
 
 ```js
-this.routes = {
+router.routes = {
     '/help': (scope, location) => {
         scope.textContent = `Help page: ${location.url}`;
     }
 };
 ```
 
-Or it may describe a title, security check, and view lifecycle:
+Or an object describing route lifecycle:
 
 ```js
-this.routes = {
+router.routes = {
     '/orders': {
         title: 'Orders',
+        focus: '#orders-title',
         secure(scope, location) {
+            // Guards must return exactly true to allow navigation.
             return Boolean(window.currentUser);
         },
         view: {
@@ -91,85 +138,65 @@ this.routes = {
 };
 ```
 
-The `secure` function must return exactly `true` to allow navigation. When navigation succeeds, the previous route's `destroy()` runs before the next route's `initialize()`.
+`secure()` must return exactly `true` to allow navigation. On a successful route change, the previous route's `destroy()` runs before the next route's `initialize()`.
+
+## Matching
 
-### Route matching behavior
+Routes match complete path boundaries. `/products` matches `/products` and `/products/42`, but not `/products-old`.
 
-Routes match complete path boundaries in object insertion order. For example, `/products` matches `/products` and `/products/42`, but it does not match `/products-old`. Put more specific routes before broader ones:
+When multiple route prefixes match, Router selects the **longest matching route**, so specific routes win without depending on object insertion order:
 
 ```js
-this.routes = {
-    '/products/sale': saleRoute,
+router.routes = {
     '/products': productsRoute,
+    '/products/sale': saleRoute,
     defaultRoute
 };
 ```
 
-If no prefix matches, `defaultRoute` is used when present.
-
-## Navigate from HTML
-
-The router delegates one document-level click listener. Add `data-pushstate` to an anchor to use client-side navigation:
-
-```html
-<a href="/products/42" data-pushstate>
-    <span>View product 42</span>
-</a>
-```
-
-Clicks on nested elements such as the `span` are resolved to the enclosing anchor. Links without `data-pushstate` keep their normal browser behavior.
-
-Modified clicks, non-left clicks, downloads, links targeting another browsing context, and cross-origin URLs also keep their normal browser behavior.
-
-## Navigate from JavaScript
-
-```js
-router.navigate('/products/42', {
-    source: 'featured-products'
-});
-```
-
-The second argument becomes `location.data.mediator`. Unless the call represents a browser `popstate`, successful navigation adds the URL to browser history.
+`/products/sale` selects `saleRoute` even though `/products` was defined first. When no prefix matches, `defaultRoute` runs if configured.
 
-## Location data
+## Location contract
 
-Every route receives the configured `scope` and a location object:
+Routes receive the configured `scope` and a location object:
 
 ```js
 {
     url: '/products/42?color=blue',
     data: {
         url: ['42'],
-        mediator: {
-            source: 'featured-products'
-        },
-        query: {
-            color: 'blue'
-        }
+        mediator: {source: 'featured-products'},
+        query: {color: 'blue'}
     }
 }
 ```
 
-- `url` is the complete route URL.
-- `data.url` contains path segments after the matched route prefix.
-- `data.mediator` contains the object passed to `navigate()` or received from the mediator.
-- `data.query` contains parsed query values.
+`data.url` contains path segments after the matched prefix, `data.query` contains parsed query values, and `data.mediator` contains navigation data supplied programmatically or through the mediator. Values are URI-decoded with standard WHATWG URL APIs; applications must still validate untrusted values.
 
-Path segments and query values are URI-decoded with browser-native URL APIs. Application code must still validate values before using them.
+## Programmatic navigation
 
-## Version 3 migration note
+```js
+const result = router.navigate('/products/42', {
+    source: 'featured-products'
+});
 
-Version 3 changes route matching from unrestricted string prefixes to path boundaries. A route such as `/page2` no longer matches `/page23`. Define `/page23` explicitly if the application previously depended on that behavior.
+// `result` is the router on success or false when navigation is rejected.
+```
 
-## Mediator navigation
+In browsers, successful navigation updates history unless the call represents `popstate`. On servers it dispatches without History API effects.
 
-Assign an EventEmitter-compatible mediator before initialization:
+Calling `navigate()` without a URL dispatches the current browser URL. In a non-browser runtime the safe default is `/`; server applications should normally supply the request URL explicitly.
+
+## Mediator integration
+
+Assign any EventEmitter-compatible mediator that provides `on()` and `removeListener()`:
 
 ```js
 import Mediator from 'white-label-mediator';
 
 const mediator = new Mediator();
-const router = new ApplicationRouter();
+const router = new Router();
+
 router.mediator = mediator;
 router.initialize();
 
@@ -179,68 +206,78 @@ mediator.emit('router:navigate', {
 });
 ```
 
-The complete emitted object is passed to the route as `location.data.mediator`. `destroy()` removes the document, window, and mediator listeners. Repeated listener initialization is idempotent and does not add duplicate listeners.
+The complete event object becomes `location.data.mediator`. `destroy()` removes listeners owned by Router. Repeated listener initialization is idempotent.
+
+## Public API
 
-## Lifecycle
+| Member | Behavior | Returns |
+| --- | --- | --- |
+| `routes` | Ordered route table of functions or lifecycle route objects. | Configuration property; not a method. |
+| `scope` | Application scope passed to route callbacks. | Configuration property; not a method. |
+| `mediator` | Optional EventEmitter-compatible source for `router:navigate`. | Configuration property; not a method. |
+| `initialize(url?)` | Dispatch the browser URL or an explicit server URL and attach applicable listeners. | The same `Router` instance. |
+| `navigate(url?, data?, isPopState?)` | Match and run a route; update browser history when appropriate. | The same `Router` instance on success; `false` for cross-origin browser URLs, rejected guards, or routes without runnable view behavior. |
+| `addListeners()` | Attach browser and optional mediator listeners once. | The same `Router` instance. |
+| `removeListeners()` | Release listeners owned by this router. | The same `Router` instance. |
+| `destroy()` | Release routing listeners. | The same `Router` instance after cleanup. |
+| `parseQueryString(query)` | Decode a query string using `URLSearchParams`. | A plain object containing the last value for each query key. |
+| `setLocationData(data?)` | Rebuild the current route location payload. | `undefined`; updates `locationData` in place. |
+| `applyPageContext(route)` | Update route title/focus context when applicable. | The same `Router` instance. |
+| `eventPushStateClick(event)` | Handle an eligible browser push-state click. | The same `Router` instance after handled navigation; `true` when native/default handling should continue. |
+| `eventPopState()` | Dispatch the current browser history location. | The same `Router` instance. |
 
-| Method | Behavior |
-| --- | --- |
-| `initialize()` | Reads the browser URL, adds listeners, and runs the initial route. |
-| `navigate(url, data, isPopState)` | Matches and runs a route, updates history, and returns the router; returns `false` when blocked or invalid. |
-| `addListeners()` | Adds browser and optional mediator listeners once. |
-| `removeListeners()` | Removes listeners previously added by this router. |
-| `destroy()` | Calls `removeListeners()` and returns the router. |
+## Title and focus
 
-Call `destroy()` when the router is no longer used:
+Object routes can define browser title and focus behavior:
 
 ```js
-router.destroy();
+router.routes = {
+    '/account': {
+        title: 'Account',
+        focus: '#account-title',
+        view: renderAccount
+    }
+};
 ```
 
-## Development
+The default focus selector is `main h1`. Set `focus: false` for an in-page refinement that should preserve current focus. Server runtimes retain `pageTitle` as route state but do not mutate a document or focus target.
 
-```sh
-npm ci
-npm run build
-npm run typecheck
-npm test
-npm run coverage
-npm run audit
-```
+## Browser history behavior
 
-The npm package publishes the compiled `dist` file and this README.
+Initialization dispatches the current URL without adding a duplicate history entry. Back/forward navigation reads `window.location`—including path, query, and hash—even when history state is null or belongs to another application. History state is not treated as the authoritative URL.
 
-## TypeScript development and version 4.0.0 migration
+## TypeScript
 
-Implementation code now uses strict TypeScript. Builds emit JavaScript, source maps with embedded source, and `.d.ts` declarations into `dist`. JavaScript callers can still use the package without compiling TypeScript themselves. JSDoc comments describe parameters, return values, lifecycle behavior, and validation at the implementation, and are retained in declarations.
+Implementation uses strict TypeScript and emits JavaScript, source maps, and declarations into `dist`.
 
 ```ts
-import Router from 'white-label-router';
-
 const router = new Router();
 const greeting: Router.Route = (scope, location) => {
-    console.log(location.data.query.name); // /hello?name=Ada
+    console.log(location.data.query.name);
 };
+
 router.routes['/hello'] = greeting;
 router.initialize();
 ```
 
-`Router.Route` covers function routes and objects with a guard or view lifecycle. `Router.Location` describes decoded URL data, `Router.Navigation` describes mediator payloads, and `Router.Handler` describes a route callback. Browser DOM types are required when compiling a consuming application.
-
-This is a major release because the distribution is now CommonJS emitted by TypeScript, replacing the previous UMD wrapper. CommonJS `require` and the documented ESM imports remain supported. Direct AMD loading or browser script tags that depended on UMD globals must migrate to a browser bundler. Edit `src/*.ts`, then run `npm run build`; do not edit generated `dist` files. The obsolete Babel build dependencies have been removed.
+`Router.Route`, `Router.Location`, `Router.Navigation`, and `Router.Handler` expose the supported contracts. Browser DOM types are present because the same class supports browser scopes and events; server hosts do not need DOM globals at runtime.
 
-### Verification and coverage
+## Development
 
 ```sh
 npm ci --ignore-scripts
+npm run lint
 npm run typecheck
 npm test
 npm run coverage
+npm run audit
 npm pack --dry-run
 ```
 
-`npm test` builds the code, checks TypeScript consumer examples against the emitted declarations, and runs the tests. `npm run coverage` additionally enforces **100% statements, branches, functions, and lines for each implementation file**. Unexecuted implementation files count toward the result; declaration-only files contain no executable code and are excluded. Reports are written to `coverage`, including `lcov.info` for coverage viewers. CI runs the same gate and checks committed build output for drift.
+Tests cover browser behavior, DOM-free server routing, and parity of the shared route contract. Coverage enforces 100% statements, branches, functions, and lines per implementation file. CI builds authored source, uploads generated artifacts for inspection, audits dependencies, packs the package, and verifies the packed public API across npm, Yarn, and pnpm.
+
+Edit `src/*.ts` and regenerate `dist`; do not edit generated files directly.
 
-Tests exercise the compiled JavaScript interface used by downstream callers. Coverage is an execution metric, not proof that all possible inputs or external integrations are correct.
+## Design boundary
 
-To undo this migration, revert its commit and run `npm ci` from the restored lockfile. No npm release, database migration, or production deployment is performed by these development changes.
+Router owns URL-to-intent translation. It intentionally does not own application state, rendering, data loading, authentication policy, or server infrastructure. Real links and server URLs remain the foundation; Router enhances them instead of replacing them.

package/dist/index.d.ts

@@ -16,6 +16,7 @@ type RouteHandler = (scope: Element | null, location: LocationData) => unknown;
 /** An object route can own a function or a view lifecycle. */
 interface RouteObject {
     title?: string;
+    focus?: string | false;
     secure?: RouteHandler;
     view?: RouteHandler | {
         initialize?: RouteHandler;
@@ -26,9 +27,9 @@ type Route = RouteHandler | RouteObject;
 /** Minimal event-bus contract required by the router. */
 interface NavigationMediator {
     on(event: string, callback: (data?: NavigationData) => unknown): unknown;
-    removeListener?(event: string, callback: (data?: NavigationData) => unknown): unknown;
+    removeListener(event: string, callback: (data?: NavigationData) => unknown): unknown;
 }
-/** History API router with ordered path-boundary matching. */
+/** History API router that also dispatches request URLs in non-browser runtimes. */
 declare class Router {
     routes: Record<string, Route>;
     url: string;
@@ -42,64 +43,41 @@ declare class Router {
     boundMediatorNavigate: (data?: NavigationData) => unknown;
     listenersInitialized: boolean;
     locationData: LocationData;
-    /**
-     * Create an instance with its own state and listener references.
-     */
+    /** Create an instance with its own state and listener references. */
     constructor();
+    /** True when browser navigation APIs are available. */
+    private isBrowserRuntime;
+    /** Stable base URL for WHATWG URL parsing in browser and server runtimes. */
+    private getOrigin;
+    /** Read the authoritative browser URL, or retain the supplied server URL. */
+    private getCurrentUrl;
+    /** Normalize browser navigation to a same-origin path, query, and hash. */
+    private normalizeBrowserUrl;
     /**
      * Start this instance and return it for lifecycle chaining.
-     * @returns This instance for chaining.
-     */
-    initialize(): this;
-    /**
-     * Register stable document, history, and optional mediator handlers once.
-     * @returns This instance for chaining.
+     * In a browser the URL is optional and defaults to window.location. On a server pass the request URL.
      */
+    initialize(url?: string): this;
+    /** Register browser and optional mediator handlers once. */
     addListeners(): this;
-    /**
-     * Release owned state and listeners so the instance can leave the application lifecycle.
-     * @returns This instance after cleanup.
-     */
+    /** Release owned state and listeners so the instance can leave the application lifecycle. */
     destroy(): this;
-    /**
-     * Release listeners owned by this instance; subclasses may extend the lifecycle hook.
-     * @returns This instance for chaining.
-     */
+    /** Release listeners owned by this instance; subclasses may extend the lifecycle hook. */
     removeListeners(): this;
-    /**
-     * Intercept eligible same-origin push-state links while preserving normal browser actions.
-     * @param e - Browser event being handled.
-     * @returns True when the browser should handle the event, or this router after interception.
-     */
+    /** Intercept eligible same-origin push-state links while preserving normal browser actions. */
     eventPushStateClick(e: MouseEvent): true | this;
-    /**
-     * Restore browser history state without adding a new history entry.
-     * @param e - Browser event being handled.
-     * @returns This router after restoring the history state.
-     */
-    eventPopState(e: PopStateEvent): this;
-    /**
-     * Decode URL query parameters, keeping the last value for duplicate keys.
-     * @param queryString - Encoded URL query portion.
-     * @returns A record of decoded query names and their final values.
-     */
+    /** Restore browser history state without adding a new history entry. */
+    eventPopState(): this;
+    /** Decode URL query parameters, keeping the last value for duplicate keys. */
     parseQueryString(queryString: string): {
         [k: string]: string;
     };
-    /**
-     * Build decoded path, query, and mediator data for the selected route.
-     * @param mediatorData - Optional caller metadata passed to the route.
-     * @returns No value; locationData is updated in place.
-     */
+    /** Build decoded path, query, and mediator data for the selected route. */
     setLocationData(mediatorData?: NavigationData): void;
-    /**
-     * Select a route, enforce its guard, transition view lifecycles, and update history and title.
-     * @param url - URL or optional adapter argument.
-     * @param mediatorData - Optional caller metadata passed to the route.
-     * @param isPopState - Whether navigation came from browser history.
-     * @returns False when a guard or route rejects navigation; otherwise this router.
-     */
-    navigate(url?: string | false, mediatorData?: NavigationData, isPopState?: boolean): false | this;
+    /** Update page context after a route renders. DOM effects are browser-only. */
+    applyPageContext(route: Route): this;
+    /** Select a route, enforce its guard, transition view lifecycles, and update browser history when available. */
+    navigate(url?: string, mediatorData?: NavigationData, isPopState?: boolean): false | this;
 }
 /** Public route configuration and navigation payload types. */
 declare namespace Router {

package/dist/index.js

@@ -1,5 +1,5 @@
 "use strict";
-/** History API router with ordered path-boundary matching. */
+/** History API router that also dispatches request URLs in non-browser runtimes. */
 class Router {
     routes;
     url;
@@ -13,36 +13,22 @@ class Router {
     boundMediatorNavigate;
     listenersInitialized;
     locationData = { url: '', data: { url: [], mediator: undefined, query: {} } };
-    /**
-     * Create an instance with its own state and listener references.
-     */
+    /** Create an instance with its own state and listener references. */
     constructor() {
-        // placeholder for routes defined when extended
         this.routes = {
             defaultRoute: {
                 view: {
-                    initialize: () => {
-                        return true;
-                    },
-                    destroy: () => {
-                        return true;
-                    }
+                    initialize: () => true,
+                    destroy: () => true
                 }
             }
         };
-        // this will hold the current url
         this.url = '';
-        // this holds the current route
         this.route = null;
-        // can house a container for the router to act upon
         this.scope = null;
-        // this holds the previous route for destorying later
         this.previousRoute = null;
-        // this will hold the page title (not yet supported by browsers)
         this.pageTitle = null;
-        // optional mediator placeholder
         this.mediator = false;
-        // Stable listener references allow destroy() to release browser resources.
         this.boundPushStateClick = this.eventPushStateClick.bind(this);
         this.boundPopState = this.eventPopState.bind(this);
         this.boundMediatorNavigate = (data = {}) => {
@@ -50,86 +36,93 @@ class Router {
         };
         this.listenersInitialized = false;
     }
+    /** True when browser navigation APIs are available. */
+    isBrowserRuntime() {
+        return typeof window !== 'undefined' && typeof document !== 'undefined';
+    }
+    /** Stable base URL for WHATWG URL parsing in browser and server runtimes. */
+    getOrigin() {
+        return this.isBrowserRuntime() ? window.location.origin : 'http://white-label.invalid';
+    }
+    /** Read the authoritative browser URL, or retain the supplied server URL. */
+    getCurrentUrl() {
+        if (!this.isBrowserRuntime()) {
+            return this.url || '/';
+        }
+        return window.location.pathname + window.location.search + (window.location.hash || '');
+    }
+    /** Normalize browser navigation to a same-origin path, query, and hash. */
+    normalizeBrowserUrl(url) {
+        if (!this.isBrowserRuntime()) {
+            return url;
+        }
+        const parsedUrl = new URL(url || '/', window.location.href || `${window.location.origin}/`);
+        if (parsedUrl.origin !== window.location.origin) {
+            return null;
+        }
+        return `${parsedUrl.pathname}${parsedUrl.search}${parsedUrl.hash}`;
+    }
     /**
      * Start this instance and return it for lifecycle chaining.
-     * @returns This instance for chaining.
+     * In a browser the URL is optional and defaults to window.location. On a server pass the request URL.
      */
-    initialize() {
-        //get the url fragment w/query string
-        this.url = window.location.pathname + window.location.search;
-        // set up the events
+    initialize(url) {
+        this.url = url ?? this.getCurrentUrl();
         this.addListeners();
-        // navigate to correct view
-        this.navigate(false, {}, false);
+        this.navigate(undefined, {}, true);
         return this;
     }
-    /**
-     * Register stable document, history, and optional mediator handlers once.
-     * @returns This instance for chaining.
-     */
+    /** Register browser and optional mediator handlers once. */
     addListeners() {
         if (this.listenersInitialized) {
             return this;
         }
-        // Delegate push-state links from one document listener.
-        document.addEventListener('click', this.boundPushStateClick);
-        //bind window popstates
-        window.addEventListener('popstate', this.boundPopState);
-        //listen to a mediator if present
+        if (this.isBrowserRuntime()) {
+            document.addEventListener('click', this.boundPushStateClick);
+            window.addEventListener('popstate', this.boundPopState);
+        }
         if (this.mediator) {
             this.mediator.on('router:navigate', this.boundMediatorNavigate);
         }
         this.listenersInitialized = true;
         return this;
     }
-    /**
-     * Release owned state and listeners so the instance can leave the application lifecycle.
-     * @returns This instance after cleanup.
-     */
+    /** Release owned state and listeners so the instance can leave the application lifecycle. */
     destroy() {
         this.removeListeners();
         return this;
     }
-    /**
-     * Release listeners owned by this instance; subclasses may extend the lifecycle hook.
-     * @returns This instance for chaining.
-     */
+    /** Release listeners owned by this instance; subclasses may extend the lifecycle hook. */
     removeListeners() {
         if (!this.listenersInitialized) {
             return this;
         }
-        // Unbind the same stable listener objects registered by addListeners().
-        document.removeEventListener('click', this.boundPushStateClick);
-        //bind window popstates
-        window.removeEventListener('popstate', this.boundPopState);
-        if (this.mediator && typeof this.mediator.removeListener === 'function') {
+        if (this.isBrowserRuntime()) {
+            document.removeEventListener('click', this.boundPushStateClick);
+            window.removeEventListener('popstate', this.boundPopState);
+        }
+        if (this.mediator) {
             this.mediator.removeListener('router:navigate', this.boundMediatorNavigate);
         }
         this.listenersInitialized = false;
         return this;
     }
-    /**
-     * Intercept eligible same-origin push-state links while preserving normal browser actions.
-     * @param e - Browser event being handled.
-     * @returns True when the browser should handle the event, or this router after interception.
-     */
+    /** Intercept eligible same-origin push-state links while preserving normal browser actions. */
     eventPushStateClick(e) {
-        if (e.defaultPrevented ||
-            (e.button !== undefined && e.button !== 0) ||
-            e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) {
+        if (typeof window === 'undefined') {
+            return true;
+        }
+        if (e.defaultPrevented || (e.button !== undefined && e.button !== 0) || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) {
             return true;
         }
         const eventTarget = e.target;
         const source = eventTarget && (typeof eventTarget.closest === 'function' ? eventTarget : eventTarget.parentElement);
-        const anchor = source && typeof source.closest === 'function'
-            ? source.closest('a[href][data-pushstate]')
-            : null;
+        const anchor = source && typeof source.closest === 'function' ? source.closest('a[href][data-pushstate]') : null;
         if (!anchor) {
             return true;
         }
         const target = anchor.getAttribute('target');
-        if (anchor.hasAttribute('download') ||
-            (target && target.toLowerCase() !== '_self')) {
+        if (anchor.hasAttribute('download') || (target && target.toLowerCase() !== '_self')) {
             return true;
         }
         const location = new URL(anchor.getAttribute('href') || '', window.location.href || `${window.location.origin}/`);
@@ -137,47 +130,31 @@ class Router {
             return true;
         }
         e.preventDefault();
-        // closest() supports nested elements at any depth inside the selected anchor.
         this.url = `${location.pathname}${location.search}${location.hash}`;
-        this.navigate(false, {}, false);
+        this.navigate(undefined, {}, false);
         return this;
     }
-    /**
-     * Restore browser history state without adding a new history entry.
-     * @param e - Browser event being handled.
-     * @returns This router after restoring the history state.
-     */
-    eventPopState(e) {
-        this.url = (e.state || '');
-        this.navigate(false, {}, true);
+    /** Restore browser history state without adding a new history entry. */
+    eventPopState() {
+        if (typeof window === 'undefined') {
+            return this;
+        }
+        this.url = this.getCurrentUrl();
+        this.navigate(undefined, {}, true);
         return this;
     }
-    /**
-     * Decode URL query parameters, keeping the last value for duplicate keys.
-     * @param queryString - Encoded URL query portion.
-     * @returns A record of decoded query names and their final values.
-     */
+    /** Decode URL query parameters, keeping the last value for duplicate keys. */
     parseQueryString(queryString) {
         return Object.fromEntries(new URLSearchParams(queryString));
     }
-    /**
-     * Build decoded path, query, and mediator data for the selected route.
-     * @param mediatorData - Optional caller metadata passed to the route.
-     * @returns No value; locationData is updated in place.
-     */
+    /** Build decoded path, query, and mediator data for the selected route. */
     setLocationData(mediatorData) {
-        const parsedUrl = new URL(this.url, window.location.origin);
+        const parsedUrl = new URL(this.url || '/', this.getOrigin());
         const matchedRoute = this.route && this.route !== 'defaultRoute' ? this.route : '';
-        // this is the object passed to the matching view
         this.locationData = {
             url: this.url,
-            data: {
-                url: [],
-                mediator: mediatorData,
-                query: {}
-            }
+            data: { url: [], mediator: mediatorData, query: {} }
         };
-        // parse out the url data
         this.locationData.data.url = parsedUrl.pathname
             .slice(matchedRoute.length)
             .split('/')
@@ -186,48 +163,66 @@ class Router {
             try {
                 return decodeURIComponent(fragment);
             }
-            catch (error) {
+            catch (_error) {
                 return fragment;
             }
         });
-        //add query string data
         this.locationData.data.query = this.parseQueryString(parsedUrl.search);
     }
-    /**
-     * Select a route, enforce its guard, transition view lifecycles, and update history and title.
-     * @param url - URL or optional adapter argument.
-     * @param mediatorData - Optional caller metadata passed to the route.
-     * @param isPopState - Whether navigation came from browser history.
-     * @returns False when a guard or route rejects navigation; otherwise this router.
-     */
+    /** Update page context after a route renders. DOM effects are browser-only. */
+    applyPageContext(route) {
+        if (typeof route === 'function') {
+            this.pageTitle = null;
+            return this;
+        }
+        this.pageTitle = typeof route.title === 'string' ? route.title : null;
+        if (!this.isBrowserRuntime()) {
+            return this;
+        }
+        if (this.pageTitle) {
+            document.title = this.pageTitle;
+        }
+        if (route.focus !== false) {
+            const target = document.querySelector(route.focus || 'main h1');
+            if (target) {
+                if (!target.hasAttribute('tabindex')) {
+                    target.setAttribute('tabindex', '-1');
+                }
+                target.focus();
+            }
+        }
+        return this;
+    }
+    /** Select a route, enforce its guard, transition view lifecycles, and update browser history when available. */
     navigate(url, mediatorData, isPopState = false) {
-        // allow navigate to use a specified url
-        if (url) {
+        if (url !== undefined) {
             this.url = url;
         }
-        //clean up url for matching
-        this.url = this.url.replace(window.location.origin, '');
-        // reset this to null for new location
+        if (!this.url) {
+            this.url = this.getCurrentUrl();
+        }
+        const normalizedUrl = this.normalizeBrowserUrl(this.url);
+        if (normalizedUrl === null) {
+            return false;
+        }
+        this.url = normalizedUrl;
         this.route = null;
-        const pathname = new URL(this.url, window.location.origin).pathname;
-        // Match complete path segments so /page2 does not also match /page23.
-        for (let route in this.routes) {
-            if (route !== 'defaultRoute' &&
-                (pathname === route || pathname.startsWith(`${route}/`))) {
+        const pathname = new URL(this.url, this.getOrigin()).pathname;
+        for (const route in this.routes) {
+            if (route === 'defaultRoute' || (pathname !== route && !pathname.startsWith(`${route}/`))) {
+                continue;
+            }
+            if (!this.route || route.length > this.route.length) {
                 this.route = route;
-                //stop looping we are done
-                break;
             }
         }
         this.setLocationData(mediatorData);
-        // if a catch all default route is defined execute that when not match is found
         if (!this.route && this.routes.defaultRoute) {
             this.route = 'defaultRoute';
         }
         if (this.route) {
             const selected = this.routes[this.route];
-            if (typeof selected !== 'function' && selected.secure &&
-                selected.secure(this.scope, this.locationData) !== true) {
+            if (typeof selected !== 'function' && selected.secure && selected.secure(this.scope, this.locationData) !== true) {
                 return false;
             }
             const previous = this.previousRoute ? this.routes[this.previousRoute] : undefined;
@@ -239,29 +234,21 @@ class Router {
             }
             else if (typeof selected.view === 'function') {
                 selected.view(this.scope, this.locationData);
-                this.pageTitle = typeof selected.title === 'string' ? selected.title : null;
             }
             else if (selected.view && typeof selected.view.initialize === 'function') {
-                this.pageTitle = typeof selected.title === 'string' ? selected.title : null;
                 selected.view.initialize(this.scope, this.locationData);
             }
             else {
                 return false;
             }
+            this.applyPageContext(selected);
             this.previousRoute = this.route;
         }
-        // make sure to not set pushstate on back button click
-        if (!isPopState) {
-            //set in history the new url
+        if (!isPopState && this.isBrowserRuntime()) {
             window.history.pushState(this.url, this.pageTitle || '', this.url);
         }
-        // since browsers don't support setting the title with pushstate yet
-        if (this.pageTitle) {
-            document.title = this.pageTitle;
-        }
         return this;
     }
 }
-;
 module.exports = Router;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/** Navigation payload, including caller-defined metadata. */\ninterface NavigationData {url?: string; [key: string]: unknown}\n/** URL-derived values supplied to route handlers. */\ninterface LocationData {url: string; data: {url: string[]; mediator: NavigationData | undefined; query: Record<string, string>}}\ntype RouteHandler = (scope: Element | null, location: LocationData) => unknown;\n/** An object route can own a function or a view lifecycle. */\ninterface RouteObject {title?: string; secure?: RouteHandler; view?: RouteHandler | {initialize?: RouteHandler; destroy?: RouteHandler}}\ntype Route = RouteHandler | RouteObject;\n/** Minimal event-bus contract required by the router. */\ninterface NavigationMediator {\n    on(event: string, callback: (data?: NavigationData) => unknown): unknown;\n    removeListener?(event: string, callback: (data?: NavigationData) => unknown): unknown;\n}\n/** History API router with ordered path-boundary matching. */\nclass Router {\n    routes: Record<string, Route>;\n    url: string;\n    route: string | null;\n    scope: Element | null;\n    previousRoute: string | null;\n    pageTitle: string | null;\n    mediator: NavigationMediator | false;\n    boundPushStateClick: (event: MouseEvent) => unknown;\n    boundPopState: (event: PopStateEvent) => unknown;\n    boundMediatorNavigate: (data?: NavigationData) => unknown;\n    listenersInitialized: boolean;\n    locationData: LocationData = {url: '', data: {url: [], mediator: undefined, query: {}}};\n\n    /**\n     * Create an instance with its own state and listener references.\n     */\n    constructor() {\n\n        // placeholder for routes defined when extended\n        this.routes = {\n            defaultRoute: {\n                view: {\n                    initialize: () => {\n                        return true;\n                    },\n                    destroy: () => {\n                        return true;\n                    }\n                }\n            }\n        }\n\n        // this will hold the current url\n        this.url = '';\n\n        // this holds the current route\n        this.route = null;\n\n        // can house a container for the router to act upon\n        this.scope = null;\n\n        // this holds the previous route for destorying later\n        this.previousRoute = null;\n\n        // this will hold the page title (not yet supported by browsers)\n        this.pageTitle = null;\n\n        // optional mediator placeholder\n        this.mediator = false;\n\n        // Stable listener references allow destroy() to release browser resources.\n        this.boundPushStateClick = this.eventPushStateClick.bind(this);\n        this.boundPopState = this.eventPopState.bind(this);\n        this.boundMediatorNavigate = (data = {}) => {\n            this.navigate(data.url, data, false);\n        };\n        this.listenersInitialized = false;\n\n    }\n\n    /**\n     * Start this instance and return it for lifecycle chaining.\n     * @returns This instance for chaining.\n     */\n    initialize() {\n\n        //get the url fragment w/query string\n        this.url = window.location.pathname + window.location.search;\n\n        // set up the events\n        this.addListeners();\n\n        // navigate to correct view\n        this.navigate(false, {}, false);\n\n        return this;\n\n    }\n\n    /**\n     * Register stable document, history, and optional mediator handlers once.\n     * @returns This instance for chaining.\n     */\n    addListeners() {\n\n        if (this.listenersInitialized) {\n            return this;\n        }\n\n        // Delegate push-state links from one document listener.\n        document.addEventListener('click', this.boundPushStateClick);\n\n        //bind window popstates\n        window.addEventListener('popstate', this.boundPopState);\n\n        //listen to a mediator if present\n        if (this.mediator) {\n            this.mediator.on('router:navigate', this.boundMediatorNavigate);\n        }\n\n        this.listenersInitialized = true;\n        return this;\n\n    }\n\n    /**\n     * Release owned state and listeners so the instance can leave the application lifecycle.\n     * @returns This instance after cleanup.\n     */\n    destroy() {\n\n        this.removeListeners();\n\n        return this;\n\n    }\n\n    /**\n     * Release listeners owned by this instance; subclasses may extend the lifecycle hook.\n     * @returns This instance for chaining.\n     */\n    removeListeners() {\n\n        if (!this.listenersInitialized) {\n            return this;\n        }\n\n        // Unbind the same stable listener objects registered by addListeners().\n        document.removeEventListener('click', this.boundPushStateClick);\n\n        //bind window popstates\n        window.removeEventListener('popstate', this.boundPopState);\n\n        if (this.mediator && typeof this.mediator.removeListener === 'function') {\n            this.mediator.removeListener('router:navigate', this.boundMediatorNavigate);\n        }\n\n        this.listenersInitialized = false;\n        return this;\n\n    }\n\n    /**\n     * Intercept eligible same-origin push-state links while preserving normal browser actions.\n     * @param e - Browser event being handled.\n     * @returns True when the browser should handle the event, or this router after interception.\n     */\n    eventPushStateClick(e: MouseEvent) {\n\n        if (\n            e.defaultPrevented ||\n            (e.button !== undefined && e.button !== 0) ||\n            e.metaKey || e.ctrlKey || e.shiftKey || e.altKey\n        ) {\n            return true;\n        }\n\n        const eventTarget = e.target as Element | null;\n        const source = eventTarget && (\n            typeof eventTarget.closest === 'function' ? eventTarget : eventTarget.parentElement\n        );\n        const anchor = source && typeof source.closest === 'function'\n            ? source.closest('a[href][data-pushstate]')\n            : null;\n        if (!anchor) {\n            return true;\n        }\n\n        const target = anchor.getAttribute('target');\n        if (\n            anchor.hasAttribute('download') ||\n            (target && target.toLowerCase() !== '_self')\n        ) {\n            return true;\n        }\n\n        const location = new URL(\n            anchor.getAttribute('href') || '',\n            window.location.href || `${window.location.origin}/`\n        );\n        if (location.origin !== window.location.origin) {\n            return true;\n        }\n\n        e.preventDefault();\n\n        // closest() supports nested elements at any depth inside the selected anchor.\n        this.url = `${location.pathname}${location.search}${location.hash}`;\n\n        this.navigate(false, {}, false);\n\n        return this;\n\n    }\n\n    /**\n     * Restore browser history state without adding a new history entry.\n     * @param e - Browser event being handled.\n     * @returns This router after restoring the history state.\n     */\n    eventPopState(e: PopStateEvent) {\n\n        this.url = (e.state || '');\n\n        this.navigate(false, {}, true);\n\n        return this;\n\n    }\n\n    /**\n     * Decode URL query parameters, keeping the last value for duplicate keys.\n     * @param queryString - Encoded URL query portion.\n     * @returns A record of decoded query names and their final values.\n     */\n    parseQueryString(queryString: string) {\n        return Object.fromEntries(new URLSearchParams(queryString));\n\n    }\n\n    /**\n     * Build decoded path, query, and mediator data for the selected route.\n     * @param mediatorData - Optional caller metadata passed to the route.\n     * @returns No value; locationData is updated in place.\n     */\n    setLocationData(mediatorData?: NavigationData) {\n\n        const parsedUrl = new URL(this.url, window.location.origin);\n        const matchedRoute = this.route && this.route !== 'defaultRoute' ? this.route : '';\n\n        // this is the object passed to the matching view\n        this.locationData = {\n            url: this.url,\n            data: {\n                url: [],\n                mediator: mediatorData,\n                query: {}\n            }\n        };\n\n        // parse out the url data\n        this.locationData.data.url = parsedUrl.pathname\n            .slice(matchedRoute.length)\n            .split('/')\n            .filter(Boolean)\n            .map((fragment) => {\n                try {\n                    return decodeURIComponent(fragment);\n                } catch (error) {\n                    return fragment;\n                }\n            });\n\n        //add query string data\n        this.locationData.data.query = this.parseQueryString(parsedUrl.search);\n\n    }\n\n    /**\n     * Select a route, enforce its guard, transition view lifecycles, and update history and title.\n     * @param url - URL or optional adapter argument.\n     * @param mediatorData - Optional caller metadata passed to the route.\n     * @param isPopState - Whether navigation came from browser history.\n     * @returns False when a guard or route rejects navigation; otherwise this router.\n     */\n    navigate(url?: string | false, mediatorData?: NavigationData, isPopState = false) {\n\n        // allow navigate to use a specified url\n        if (url) {\n            this.url = url;\n        }\n\n        //clean up url for matching\n        this.url = this.url.replace(window.location.origin, '');\n\n        // reset this to null for new location\n        this.route = null;\n\n        const pathname = new URL(this.url, window.location.origin).pathname;\n\n        // Match complete path segments so /page2 does not also match /page23.\n        for (let route in this.routes) {\n\n            if (\n                route !== 'defaultRoute' &&\n                (pathname === route || pathname.startsWith(`${route}/`))\n            ) {\n\n                this.route = route;\n\n                //stop looping we are done\n                break;\n\n            }\n\n        }\n\n        this.setLocationData(mediatorData);\n\n        // if a catch all default route is defined execute that when not match is found\n        if (!this.route && this.routes.defaultRoute) {\n\n            this.route = 'defaultRoute';\n\n        }\n\n        if (this.route) {\n            const selected = this.routes[this.route];\n            if (typeof selected !== 'function' && selected.secure &&\n                selected.secure(this.scope, this.locationData) !== true) {\n                return false;\n            }\n            const previous = this.previousRoute ? this.routes[this.previousRoute] : undefined;\n            if (previous && typeof previous !== 'function' && typeof previous.view === 'object' && previous.view.destroy) {\n                previous.view.destroy(this.scope, this.locationData);\n            }\n            if (typeof selected === 'function') {\n                selected(this.scope, this.locationData);\n            } else if (typeof selected.view === 'function') {\n                selected.view(this.scope, this.locationData);\n                this.pageTitle = typeof selected.title === 'string' ? selected.title : null;\n            } else if (selected.view && typeof selected.view.initialize === 'function') {\n                this.pageTitle = typeof selected.title === 'string' ? selected.title : null;\n                selected.view.initialize(this.scope, this.locationData);\n            } else {\n                return false;\n            }\n            this.previousRoute = this.route;\n        }\n\n        // make sure to not set pushstate on back button click\n        if (!isPopState) {\n            //set in history the new url\n            window.history.pushState(this.url, this.pageTitle || '', this.url);\n        }\n\n        // since browsers don't support setting the title with pushstate yet\n        if (this.pageTitle) {\n            document.title = this.pageTitle;\n        }\n\n        return this;\n\n    }\n\n};\n\n\n/** Public route configuration and navigation payload types. */\nnamespace Router {\n    export type Handler = RouteHandler;\n    export type Route = RouteHandler | RouteObject;\n    export type Location = LocationData;\n    export type Navigation = NavigationData;\n}\nexport = Router;\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["/** Navigation payload, including caller-defined metadata. */\ninterface NavigationData {url?: string; [key: string]: unknown}\n/** URL-derived values supplied to route handlers. */\ninterface LocationData {url: string; data: {url: string[]; mediator: NavigationData | undefined; query: Record<string, string>}}\ntype RouteHandler = (scope: Element | null, location: LocationData) => unknown;\n/** An object route can own a function or a view lifecycle. */\ninterface RouteObject {title?: string; focus?: string | false; secure?: RouteHandler; view?: RouteHandler | {initialize?: RouteHandler; destroy?: RouteHandler}}\ntype Route = RouteHandler | RouteObject;\n/** Minimal event-bus contract required by the router. */\ninterface NavigationMediator {\n    on(event: string, callback: (data?: NavigationData) => unknown): unknown;\n    removeListener(event: string, callback: (data?: NavigationData) => unknown): unknown;\n}\n/** History API router that also dispatches request URLs in non-browser runtimes. */\nclass Router {\n    routes: Record<string, Route>;\n    url: string;\n    route: string | null;\n    scope: Element | null;\n    previousRoute: string | null;\n    pageTitle: string | null;\n    mediator: NavigationMediator | false;\n    boundPushStateClick: (event: MouseEvent) => unknown;\n    boundPopState: (event: PopStateEvent) => unknown;\n    boundMediatorNavigate: (data?: NavigationData) => unknown;\n    listenersInitialized: boolean;\n    locationData: LocationData = {url: '', data: {url: [], mediator: undefined, query: {}}};\n\n    /** Create an instance with its own state and listener references. */\n    constructor() {\n        this.routes = {\n            defaultRoute: {\n                view: {\n                    initialize: () => true,\n                    destroy: () => true\n                }\n            }\n        };\n        this.url = '';\n        this.route = null;\n        this.scope = null;\n        this.previousRoute = null;\n        this.pageTitle = null;\n        this.mediator = false;\n        this.boundPushStateClick = this.eventPushStateClick.bind(this);\n        this.boundPopState = this.eventPopState.bind(this);\n        this.boundMediatorNavigate = (data = {}) => {\n            this.navigate(data.url, data, false);\n        };\n        this.listenersInitialized = false;\n    }\n\n    /** True when browser navigation APIs are available. */\n    private isBrowserRuntime() {\n        return typeof window !== 'undefined' && typeof document !== 'undefined';\n    }\n\n    /** Stable base URL for WHATWG URL parsing in browser and server runtimes. */\n    private getOrigin() {\n        return this.isBrowserRuntime() ? window.location.origin : 'http://white-label.invalid';\n    }\n\n    /** Read the authoritative browser URL, or retain the supplied server URL. */\n    private getCurrentUrl() {\n        if (!this.isBrowserRuntime()) {return this.url || '/';}\n        return window.location.pathname + window.location.search + (window.location.hash || '');\n    }\n\n    /** Normalize browser navigation to a same-origin path, query, and hash. */\n    private normalizeBrowserUrl(url: string) {\n        if (!this.isBrowserRuntime()) {return url;}\n        const parsedUrl = new URL(url || '/', window.location.href || `${window.location.origin}/`);\n        if (parsedUrl.origin !== window.location.origin) {return null;}\n        return `${parsedUrl.pathname}${parsedUrl.search}${parsedUrl.hash}`;\n    }\n\n    /**\n     * Start this instance and return it for lifecycle chaining.\n     * In a browser the URL is optional and defaults to window.location. On a server pass the request URL.\n     */\n    initialize(url?: string) {\n        this.url = url ?? this.getCurrentUrl();\n        this.addListeners();\n        this.navigate(undefined, {}, true);\n        return this;\n    }\n\n    /** Register browser and optional mediator handlers once. */\n    addListeners() {\n        if (this.listenersInitialized) {return this;}\n        if (this.isBrowserRuntime()) {\n            document.addEventListener('click', this.boundPushStateClick);\n            window.addEventListener('popstate', this.boundPopState);\n        }\n        if (this.mediator) {this.mediator.on('router:navigate', this.boundMediatorNavigate);}\n        this.listenersInitialized = true;\n        return this;\n    }\n\n    /** Release owned state and listeners so the instance can leave the application lifecycle. */\n    destroy() {\n        this.removeListeners();\n        return this;\n    }\n\n    /** Release listeners owned by this instance; subclasses may extend the lifecycle hook. */\n    removeListeners() {\n        if (!this.listenersInitialized) {return this;}\n        if (this.isBrowserRuntime()) {\n            document.removeEventListener('click', this.boundPushStateClick);\n            window.removeEventListener('popstate', this.boundPopState);\n        }\n        if (this.mediator) {this.mediator.removeListener('router:navigate', this.boundMediatorNavigate);}\n        this.listenersInitialized = false;\n        return this;\n    }\n\n    /** Intercept eligible same-origin push-state links while preserving normal browser actions. */\n    eventPushStateClick(e: MouseEvent) {\n        if (typeof window === 'undefined') {return true;}\n        if (e.defaultPrevented || (e.button !== undefined && e.button !== 0) || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) {\n            return true;\n        }\n        const eventTarget = e.target as Element | null;\n        const source = eventTarget && (typeof eventTarget.closest === 'function' ? eventTarget : eventTarget.parentElement);\n        const anchor = source && typeof source.closest === 'function' ? source.closest('a[href][data-pushstate]') : null;\n        if (!anchor) {return true;}\n        const target = anchor.getAttribute('target');\n        if (anchor.hasAttribute('download') || (target && target.toLowerCase() !== '_self')) {return true;}\n        const location = new URL(anchor.getAttribute('href') || '', window.location.href || `${window.location.origin}/`);\n        if (location.origin !== window.location.origin) {return true;}\n        e.preventDefault();\n        this.url = `${location.pathname}${location.search}${location.hash}`;\n        this.navigate(undefined, {}, false);\n        return this;\n    }\n\n    /** Restore browser history state without adding a new history entry. */\n    eventPopState() {\n        if (typeof window === 'undefined') {return this;}\n        this.url = this.getCurrentUrl();\n        this.navigate(undefined, {}, true);\n        return this;\n    }\n\n    /** Decode URL query parameters, keeping the last value for duplicate keys. */\n    parseQueryString(queryString: string) {\n        return Object.fromEntries(new URLSearchParams(queryString));\n    }\n\n    /** Build decoded path, query, and mediator data for the selected route. */\n    setLocationData(mediatorData?: NavigationData) {\n        const parsedUrl = new URL(this.url || '/', this.getOrigin());\n        const matchedRoute = this.route && this.route !== 'defaultRoute' ? this.route : '';\n        this.locationData = {\n            url: this.url,\n            data: {url: [], mediator: mediatorData, query: {}}\n        };\n        this.locationData.data.url = parsedUrl.pathname\n            .slice(matchedRoute.length)\n            .split('/')\n            .filter(Boolean)\n            .map((fragment) => {\n                try {return decodeURIComponent(fragment);} catch (_error) {return fragment;}\n            });\n        this.locationData.data.query = this.parseQueryString(parsedUrl.search);\n    }\n\n    /** Update page context after a route renders. DOM effects are browser-only. */\n    applyPageContext(route: Route) {\n        if (typeof route === 'function') {\n            this.pageTitle = null;\n            return this;\n        }\n        this.pageTitle = typeof route.title === 'string' ? route.title : null;\n        if (!this.isBrowserRuntime()) {return this;}\n        if (this.pageTitle) {document.title = this.pageTitle;}\n        if (route.focus !== false) {\n            const target = document.querySelector<HTMLElement>(route.focus || 'main h1');\n            if (target) {\n                if (!target.hasAttribute('tabindex')) {target.setAttribute('tabindex', '-1');}\n                target.focus();\n            }\n        }\n        return this;\n    }\n\n    /** Select a route, enforce its guard, transition view lifecycles, and update browser history when available. */\n    navigate(url?: string, mediatorData?: NavigationData, isPopState = false) {\n        if (url !== undefined) {this.url = url;}\n        if (!this.url) {this.url = this.getCurrentUrl();}\n        const normalizedUrl = this.normalizeBrowserUrl(this.url);\n        if (normalizedUrl === null) {return false;}\n        this.url = normalizedUrl;\n        this.route = null;\n        const pathname = new URL(this.url, this.getOrigin()).pathname;\n        for (const route in this.routes) {\n            if (route === 'defaultRoute' || (pathname !== route && !pathname.startsWith(`${route}/`))) {continue;}\n            if (!this.route || route.length > this.route.length) {this.route = route;}\n        }\n        this.setLocationData(mediatorData);\n        if (!this.route && this.routes.defaultRoute) {this.route = 'defaultRoute';}\n        if (this.route) {\n            const selected = this.routes[this.route]!;\n            if (typeof selected !== 'function' && selected.secure && selected.secure(this.scope, this.locationData) !== true) {\n                return false;\n            }\n            const previous = this.previousRoute ? this.routes[this.previousRoute] : undefined;\n            if (previous && typeof previous !== 'function' && typeof previous.view === 'object' && previous.view.destroy) {\n                previous.view.destroy(this.scope, this.locationData);\n            }\n            if (typeof selected === 'function') {\n                selected(this.scope, this.locationData);\n            } else if (typeof selected.view === 'function') {\n                selected.view(this.scope, this.locationData);\n            } else if (selected.view && typeof selected.view.initialize === 'function') {\n                selected.view.initialize(this.scope, this.locationData);\n            } else {\n                return false;\n            }\n            this.applyPageContext(selected);\n            this.previousRoute = this.route;\n        }\n        if (!isPopState && this.isBrowserRuntime()) {\n            window.history.pushState(this.url, this.pageTitle || '', this.url);\n        }\n        return this;\n    }\n}\n\n/** Public route configuration and navigation payload types. */\nnamespace Router {\n    export type Handler = RouteHandler;\n    export type Route = RouteHandler | RouteObject;\n    export type Location = LocationData;\n    export type Navigation = NavigationData;\n}\nexport = Router;\n"]}

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "white-label-router",
-  "version": "4.0.0",
-  "description": "A simple ES6 JS router",
+  "version": "5.0.0",
+  "description": "Framework-independent TypeScript router for browser, server, and request-scoped Node.js functions with progressive enhancement, guards, and accessible navigation.",
+  "sideEffects": false,
   "main": "dist/index.js",
   "files": [
     "dist",
     "README.md"
   ],
   "engines": {
-    "node": "^22.18.0 || >=24.11.0",
-    "npm": ">=10.0"
+    "node": "^22.18.0 || >=24.11.0"
   },
   "repository": {
     "type": "git",
@@ -18,38 +18,53 @@
   "contributors": [
     {
       "name": "Bill Shackelford",
-      "email": "bshackelford@gmail.com",
       "url": "https://github.com/bshack"
     }
   ],
   "keywords": [
-    "js",
-    "javacript",
+    "javascript",
+    "typescript",
     "router",
-    "es6",
-    "es2015",
-    "delegate"
+    "routing",
+    "client-side-routing",
+    "history-api",
+    "progressive-enhancement",
+    "navigation",
+    "accessibility",
+    "framework-independent",
+    "browser",
+    "node",
+    "server-side",
+    "serverless",
+    "universal"
   ],
   "author": "bshack",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/bshack/white-label-router/issues"
   },
-  "homepage": "https://github.com/bshack/white-label-router#readme",
+  "homepage": "https://whitelabeljs.org/docs/router/",
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && npm run test:types && npm run test:unit",
+    "test": "node --run build && node --run test:types && node --run test:unit",
     "audit": "npm audit --audit-level=high",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:unit": "node --test test/*.test.js",
-    "coverage": "npm run build && npm run test:types && c8 npm run test:unit",
-    "prepack": "npm run build",
-    "test:types": "tsc -p tsconfig.consumer.json"
+    "coverage": "node --run build && node --run test:types && c8 node --run test:unit",
+    "prepare": "node --run build",
+    "test:types": "tsc -p tsconfig.consumer.json",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings=0",
+    "lint:fix": "node --run lint -- --fix"
   },
   "devDependencies": {
     "@types/node": "24.13.3",
     "c8": "12.0.0",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "@babel/core": "8.0.5",
+    "@babel/eslint-parser": "8.0.5",
+    "@babel/preset-typescript": "8.0.1",
+    "@eslint/js": "10.0.1",
+    "eslint": "10.10.0"
   },
   "types": "dist/index.d.ts",
   "c8": {
@@ -70,8 +85,13 @@
     "branches": 100,
     "statements": 100,
     "perFile": true,
-    "exclude": [
-      "**/*.d.ts"
-    ]
+    "exclude": ["**/*.d.ts"]
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
   }
 }