@wavelengthusaf/client-router 0.0.7 → 0.1.0

package/README.md

@@ -7,18 +7,31 @@ A lightweight, native TypeScript web components router for modern web applicatio
 - [Getting Started](#getting-started)
   - [Prerequisites](#prerequisites)
   - [Installation](#installation)
-  - [Husky Setup](#husky-setup)
-- [Adding to Your Project](#adding-to-your-project)
+- [Use in Your Application](#use-in-your-application)
 - [Usage](#usage)
   - [HTML Template Approach](#html-template-approach)
   - [TypeScript Approach](#typescript-approach)
+  - [Router Lifecycle](#router-lifecycle)
+  - [Direct Router Scoping](#direct-router-scoping)
 - [API Reference](#api-reference)
   - [`<wavelength-router>` Attributes](#wavelength-router-attributes)
   - [`<wavelength-route>` Attributes](#wavelength-route-attributes)
   - [RouteContext](#routecontext)
   - [RouteGuard](#routeguard)
+  - [Route-Level Error Handling](#route-level-error-handling)
+  - [Navigation Lifecycle Events](#navigation-lifecycle-events)
   - [Programmatic Navigation](#programmatic-navigation)
+  - [Route Preloading](#route-preloading)
+  - [Focus Management](#focus-management)
+  - [Shadow DOM Navigation](#shadow-dom-navigation)
+  - [Injected Browser Environment](#injected-browser-environment)
+  - [Matching Utilities](#matching-utilities)
 - [Best Practices](#best-practices)
+- [Contributing and Local Development](#contributing-and-local-development)
+  - [Repository Setup](#repository-setup)
+  - [Husky Setup](#husky-setup)
+  - [Development Commands](#development-commands)
+  - [CI/CD Expectations](#cicd-expectations)
 
 ---
 
@@ -26,43 +39,20 @@ A lightweight, native TypeScript web components router for modern web applicatio
 
 ### Prerequisites
 
-- Node.js 18+ and npm
+- Node.js 24+ and npm
 - A modern browser with native web components support
 
 ### Installation
 
-Clone the repository and install dependencies:
-
-```bash
-git clone https://github.com/your-org/wavelength-router.git
-cd wavelength-router
-npm install
-```
-
-### Husky Setup
-
-This project uses Husky to run linting and tests before each commit. If you're setting up the project for the first time or if Husky hooks aren't working, initialize it with:
-
-```bash
-npm run prepare
-```
-
-Or manually initialize:
+Install the package in your application:
 
 ```bash
-npx husky init
+npm install @wavelengthusaf/client-router
 ```
 
-This ensures that before every commit, Husky will:
-
-1. Run unit tests via `npm run test`
-2. Run ESLint and Prettier via `npm run lint`
-
-If either fails, the commit will be blocked.
-
 ---
 
-## Adding to Your Project
+## Use in Your Application
 
 ### Option 1: npm Package (Published)
 
@@ -79,20 +69,6 @@ Then import the elements in your entry point:
 import '@wavelengthusaf/client-router';
 ```
 
-### Option 2: Local Development
-
-For local development or testing changes:
-
-```bash
-npm run build
-```
-
-This compiles TypeScript to `dist/`. Then in your consuming project:
-
-```typescript
-import '@wavelengthusaf/client-router';
-```
-
 ---
 
 ## Usage
@@ -113,15 +89,14 @@ Use the custom elements directly in your HTML. This is ideal for simpler applica
     <title>My App</title>
   </head>
   <body>
-    <!-- Navigation -->
-    <nav>
-      <a href="/">Home</a>
-      <a href="/about">About</a>
-      <a href="/users/123">User Profile</a>
-    </nav>
-
-    <!-- Router Container - renders matched route component here -->
+    <!-- Router Container - owns navigation and renders matched pages -->
     <wavelength-router>
+      <nav aria-label="Main navigation">
+        <a href="/">Home</a>
+        <a href="/about">About</a>
+        <a href="/users/123">User Profile</a>
+      </nav>
+
       <wavelength-route path="/" component="home-page"></wavelength-route>
       <wavelength-route path="/about" component="about-page"></wavelength-route>
       <wavelength-route
@@ -177,12 +152,18 @@ Use the custom elements directly in your HTML. This is ideal for simpler applica
 </html>
 ```
 
+`<wavelength-router>` delegates links from its own Light DOM and open Shadow
+DOM descendants. Keep declarative navigation inside the router, outside the
+rendered page outlet. Links outside the router intentionally retain native
+browser navigation; external controls can call `router.navigate(path)`.
+
 #### How It Works
 
-1. `<wavelength-router>` acts as the router container and outlet
-2. It scans for `<wavelength-route>` children and extracts route definitions
-3. When the URL changes, the router matches the path and mounts the corresponding component
-4. The component is rendered inside the `<wavelength-router>` element
+1. `<wavelength-router>` collects route declarations from its Light DOM and
+   open Shadow DOM descendants.
+2. It preserves those declarations and mounts the matching component in a
+   separate internal Light DOM outlet.
+3. Routes are matched in declaration order, so place a wildcard route last.
 
 ---
 
@@ -197,113 +178,126 @@ import { Router } from '@wavelengthusaf/client-router';
 import type {
   RouteContext,
   RouteDefinition,
-  RouteGuard,
 } from '@wavelengthusaf/client-router';
 
-// Define your page components
-class HomePage extends HTMLElement {
-  connectedCallback() {
-    this.innerHTML = '<h1>Welcome Home</h1>';
-  }
-}
-
-class AboutPage extends HTMLElement {
-  connectedCallback() {
-    this.innerHTML = '<h1>About Us</h1>';
-  }
-}
-
-class UserPage extends HTMLElement {
-  connectedCallback() {
-    const userId = this.routeContext?.routeParams?.userId;
-    this.innerHTML = `<h1>User Profile</h1><p>User ID: ${userId}</p>`;
-  }
-}
-
-// Register components
-customElements.define('home-page', HomePage);
-customElements.define('about-page', AboutPage);
-customElements.define('user-page', UserPage);
+const mountElement =
+  (tag: string) =>
+  (container: HTMLElement, context: RouteContext): void => {
+    const page = document.createElement(tag) as HTMLElement & {
+      routeContext?: RouteContext;
+    };
+    page.routeContext = context;
+    container.appendChild(page);
+  };
 
-// Define routes using RouteDefinition objects
 const routes: RouteDefinition[] = [
   {
     path: '/',
     routeComponent: {
-      mount(container: HTMLElement, context: RouteContext) {
-        const element = document.createElement('home-page') as HTMLElement & {
-          routeContext?: RouteContext;
-        };
-        element.routeContext = context;
-        container.appendChild(element);
-      },
-      unmount() {
-        // Optional cleanup
-      },
-    },
-  },
-  {
-    path: '/about',
-    routeComponent: {
-      mount(container: HTMLElement, context: RouteContext) {
-        const element = document.createElement('about-page') as HTMLElement & {
-          routeContext?: RouteContext;
-        };
-        element.routeContext = context;
-        container.appendChild(element);
-      },
+      mount: mountElement('home-page'),
     },
   },
   {
     path: '/users/:userId',
     routeComponent: {
-      mount(container: HTMLElement, context: RouteContext) {
-        const element = document.createElement('user-page') as HTMLElement & {
-          routeContext?: RouteContext;
-        };
-        element.routeContext = context;
-        container.appendChild(element);
-      },
+      mount: mountElement('user-page'),
     },
   },
 ];
 
-// Create and start the router
+const outlet = document.querySelector<HTMLElement>('#app')!;
 const router = new Router(routes, {
-  outlet: document.getElementById('app')!, // Container element
-  hashMode: false, // Use hash routing (optional)
+  outlet,
+  hashMode: false, // History API mode; use true for #/path URLs.
 });
 
 router.start();
 ```
 
+Use `Router` directly when the host application owns its outlet, route
+definitions, and lifecycle. It is also useful in tests because browser globals
+can be supplied through the optional third constructor argument.
+
 #### RouteDefinition Structure
 
 Each route requires:
 
 - `path`: The URL path pattern (supports `:param` syntax for dynamic segments)
 - `routeComponent`: An object with a `mount` function (and optional `unmount`)
+- `beforeEach`: Optional route-specific navigation guard
 
 ```typescript
 interface RouteDefinition {
   path: string; // e.g., '/users/:id' or '/products/:category/:id'
   routeComponent: {
-    mount(container: HTMLElement, context: RouteContext): void;
+    mount: (
+      container: HTMLElement,
+      context: RouteContext,
+    ) => void | Promise<void>;
     unmount?(): void; // Optional cleanup function
   };
+  beforeEach?: RouteGuard;
 }
 ```
 
+### Router Lifecycle
+
+Call `start()` after the outlet exists. Call `destroy()` when the host is
+removed or replaced; it removes navigation listeners and runs the active
+route's optional `unmount()` hook.
+
+```typescript
+const router = new Router(routes, { outlet });
+router.start();
+
+window.addEventListener('pagehide', () => router.destroy(), { once: true });
+```
+
+Each navigation clears the outlet, runs the prior route's `unmount()`, and then
+calls the next route's `mount(outlet, context)`.
+
+`mount()` may return a promise. The router waits to mark that route complete
+until the promise resolves. If a newer navigation begins first, the older mount
+is treated as cancelled: it cannot become active or emit a completion event,
+and its optional `unmount()` runs when its promise settles. Route components
+should use their own `AbortController` for work that must be stopped before a
+promise settles.
+
+### Direct Router Scoping
+
+By default, a direct `Router` listens on its injected `document`. For a nested
+router or a router inside Shadow DOM, `eventTarget` and `navigationRoot` are
+required: without both, multiple document-level routers can handle the same
+composed navigation event. Scope them to the containing host:
+
+```typescript
+const host = document.querySelector<HTMLElement>('#account-router')!;
+const outlet = host.querySelector<HTMLElement>('[data-outlet]')!;
+
+const router = new Router(routes, {
+  outlet,
+  eventTarget: host,
+  navigationRoot: host,
+});
+router.start();
+```
+
+Using the same containing element for `eventTarget` and `navigationRoot`
+prevents an outer router from acting on links owned by a nested router. A
+top-level direct router may omit these options when document-wide navigation is
+intended.
+
 ---
 
 ## API Reference
 
 ### `<wavelength-router>` Attributes
 
-| Attribute   | Type   | Description                                             |
-| ----------- | ------ | ------------------------------------------------------- |
-| `hash-mode` | flag   | Enable hash-based routing (`#/path`) instead of history |
-| `guard`     | string | Name of a global guard function on `window`             |
+| Attribute        | Type                        | Description                                             |
+| ---------------- | --------------------------- | ------------------------------------------------------- |
+| `hash-mode`      | flag                        | Enable hash-based routing (`#/path`) instead of history |
+| `guard`          | string                      | Name of a global guard function on `window`             |
+| `focus-strategy` | `none`, `outlet`, `heading` | Focus target after navigation; defaults to `none`       |
 
 #### Example with Hash Mode
 
@@ -316,12 +310,23 @@ interface RouteDefinition {
 
 URL becomes: `https://example.com/#/profile`
 
+Hash-mode query strings are supported. For `#/profile?tab=security`, the route
+matches `/profile` and `routeContext.query.get('tab')` is `security`.
+External route-hash changes are observed automatically. Hash routes use the
+`#/path` form, so ordinary fragments such as `href="#details"` retain native
+in-page scrolling behavior. Same-origin absolute links ending in `#/path` are
+also normalized as hash routes.
+
 ### `<wavelength-route>` Attributes
 
-| Attribute   | Type   | Description                                      |
-| ----------- | ------ | ------------------------------------------------ |
-| `path`      | string | URL path pattern (supports `:param` syntax)      |
-| `component` | string | Custom element tag name to render for this route |
+| Attribute   | Type   | Description                                        |
+| ----------- | ------ | -------------------------------------------------- |
+| `path`      | string | URL path pattern (supports `:param` syntax)        |
+| `component` | string | Custom element tag name to render for this route   |
+| `guard`     | string | Optional route-specific guard function on `window` |
+
+Changing any route attribute on a connected route automatically rebuilds the
+router's definitions.
 
 #### Path Patterns
 
@@ -348,12 +353,10 @@ interface RouteContext {
 
 ```typescript
 class MyPage extends HTMLElement {
-  static get routeContext(): RouteContext | undefined {
-    return (this as unknown as { routeContext?: RouteContext }).routeContext;
-  }
+  public routeContext?: RouteContext;
 
-  connectedCallback() {
-    const ctx = MyPage.routeContext;
+  public connectedCallback(): void {
+    const ctx = this.routeContext;
     if (ctx) {
       console.log('Current path:', ctx.path);
       console.log('User ID:', ctx.routeParams.userId);
@@ -365,7 +368,9 @@ class MyPage extends HTMLElement {
 
 ### RouteGuard
 
-Navigation guards allow you to intercept and redirect navigation. Define a guard function and reference it via the `guard` attribute.
+Navigation guards allow you to intercept and redirect navigation. Define a
+guard function and reference it via the `guard` attribute on
+`<wavelength-router>` or a specific `<wavelength-route>`.
 
 ```typescript
 // Define guard on window (required for HTML approach)
@@ -383,16 +388,53 @@ type NextCallback = (redirect?: string) => void;
     next(); // Allow navigation
   }
 };
+
+(window as unknown as Record<string, unknown>).permissionGuard = (
+  to: RouteContext,
+  next: NextCallback,
+) => {
+  const user = getCurrentUser();
+
+  if (!user?.permissions.includes('billing:read')) {
+    next('/forbidden');
+    return;
+  }
+
+  next();
+};
 ```
 
 ```html
 <wavelength-router guard="authGuard">
   <wavelength-route path="/" component="home-page"></wavelength-route>
   <wavelength-route
-    path="/protected"
-    component="protected-page"
+    path="/billing"
+    component="billing-page"
+    guard="permissionGuard"
   ></wavelength-route>
   <wavelength-route path="/login" component="login-page"></wavelength-route>
+  <wavelength-route
+    path="/forbidden"
+    component="forbidden-page"
+  ></wavelength-route>
+</wavelength-router>
+```
+
+The router-level guard runs before a matched route's guard. If either guard
+redirects, later guards and the matched component mount are skipped for that
+navigation.
+
+Use a route-level guard when only one route or route group needs a specific
+permission check:
+
+```html
+<wavelength-router>
+  <wavelength-route path="/" component="home-page"></wavelength-route>
+  <wavelength-route
+    path="/reports"
+    component="reports-page"
+    guard="reportsGuard"
+  ></wavelength-route>
 </wavelength-router>
 ```
 
@@ -401,12 +443,108 @@ type NextCallback = (redirect?: string) => void;
 1. Guard receives `RouteContext` with destination path
 2. Guard calls `next()` to allow navigation or `next('/redirect-path')` to redirect
 
+Guards may call `next()` asynchronously. If another navigation starts first,
+the older continuation is ignored so it cannot replace the newer route. If a
+route's `guard` attribute changes while connected, `<wavelength-router>`
+rebuilds its route definitions automatically.
+
+For a direct `Router`, pass a global guard as `beforeEach`, or attach a
+route-specific guard to an individual route definition:
+
+```typescript
+const routes: RouteDefinition[] = [
+  {
+    path: '/billing',
+    routeComponent: { mount: mountElement('billing-page') },
+    beforeEach: permissionGuard,
+  },
+];
+
+const router = new Router(routes, {
+  outlet,
+  beforeEach: (context, next) => {
+    if (context.path.startsWith('/protected') && !getCurrentUser()) {
+      next('/login');
+      return;
+    }
+
+    next();
+  },
+});
+```
+
+### Route-Level Error Handling
+
+Pass `onError` to a direct `Router` to handle route matching, guard, mount, and
+unmount failures in one place. The hook receives the thrown value, its phase,
+and the matched `RouteContext` when one exists. It works in both Light and
+Shadow DOM because it is independent of event retargeting.
+
+```typescript
+import type { RouteErrorDetail } from '@wavelengthusaf/client-router';
+
+const router = new Router(routes, {
+  outlet,
+  onError: ({ error, phase, context }: RouteErrorDetail) => {
+    reportRouteError(error, { phase, path: context?.path });
+
+    if (phase === 'mount') {
+      outlet.textContent = 'Sorry, this page could not be loaded.';
+    }
+  },
+});
+```
+
+The phases are `match`, `guard`, `mount`, and `unmount`. Supplying `onError`
+handles synchronous guard and mount errors so the router remains started.
+Unmount errors are reported and do not prevent the next route from mounting.
+Without a hook, synchronous guard and mount errors retain their normal thrown
+behavior. `wavelength-route-error` is dispatched in all cases.
+
+### Navigation Lifecycle Events
+
+The router emits composed, bubbling events for each navigation. Listen on the
+`<wavelength-router>` itself, an ancestor, or the configured `eventTarget` of a
+direct `Router`. They are useful for loading indicators, telemetry, and error
+reporting without coupling page components to router internals.
+
+| Event                       | When it fires                                            | `detail`                           |
+| --------------------------- | -------------------------------------------------------- | ---------------------------------- |
+| `wavelength-route-start`    | A route is matched, before its guard or component mounts | `{ path, context }`                |
+| `wavelength-route-complete` | The matched component has mounted successfully           | `{ path, context }`                |
+| `wavelength-route-error`    | Route matching, a guard, mount, or unmount fails         | `{ path, context?, error, phase }` |
+
+`context` is the normal `RouteContext`. A redirect starts a new navigation for
+its destination and therefore emits completion only for the destination route.
+
+```typescript
+import type { RouteLifecycleEventDetail } from '@wavelengthusaf/client-router';
+
+document.addEventListener('wavelength-route-start', (event: Event) => {
+  const { context } = (event as CustomEvent<RouteLifecycleEventDetail>).detail;
+  loadingIndicator.show(context?.path);
+});
+
+document.addEventListener('wavelength-route-complete', () => {
+  loadingIndicator.hide();
+});
+
+document.addEventListener('wavelength-route-error', (event: Event) => {
+  const { error, path } = (event as CustomEvent<RouteLifecycleEventDetail>)
+    .detail;
+  reportNavigationError(path, error);
+});
+```
+
 ### Programmatic Navigation
 
 The router provides navigation methods:
 
 ```typescript
-const routerElement = document.querySelector('wavelength-router');
+import type { RouterElement } from '@wavelengthusaf/client-router';
+
+const routerElement =
+  document.querySelector<RouterElement>('wavelength-router')!;
 
 // Navigate to a new path (adds to history)
 routerElement.navigate('/about');
@@ -416,6 +554,235 @@ routerElement.replace('/new-page');
 
 // Go back in history
 routerElement.back();
+
+// Rescan routes after dynamically attaching an open shadow root
+routerElement.refresh();
+```
+
+The same methods are available on a `Router` instance. Prefer `replace()` for
+post-login or canonicalization redirects when the previous URL should not
+remain in browser history. Programmatic navigation accepts only valid
+same-origin HTTP(S) paths; external and malformed targets are ignored.
+
+### Route Preloading
+
+Use the application-controlled `preload` hook to prepare resources for likely
+next pages. The router calls it for eligible same-origin route links on hover
+and keyboard focus, and it receives the matched `RouteContext`. Preloading
+never delays navigation.
+
+```typescript
+const router = new Router(routes, {
+  outlet,
+  preload: async (context) => {
+    await pageResourceCache.load(context.path, context.query);
+  },
+});
+```
+
+`router.preload('/reports?range=month')` starts the same work explicitly.
+`router.getPreloadStatus(path)` returns `idle`, `preloading`, `ready`, or
+`failed`. Pending and successful paths are deduplicated; a failed preload is
+retried by the next explicit call, hover, or focus. A preload failure does not
+affect route navigation or `onError` handling.
+
+For declarative routing, configure the property before or after connection:
+
+```typescript
+import type { RouterElement } from '@wavelengthusaf/client-router';
+
+const routerElement =
+  document.querySelector<RouterElement>('wavelength-router')!;
+routerElement.preloader = async (context) => {
+  await pageResourceCache.load(context.path, context.query);
+};
+
+// Start the same preload work explicitly.
+routerElement.preload('/reports?range=month');
+
+// Read the current status: idle, preloading, ready, or failed.
+const status = routerElement.getPreloadStatus('/reports?range=month');
+```
+
+The preload machine is intentionally scoped per `Router`. It retains useful
+pending work across ordinary navigations; route components should use their own
+`AbortController` for resource work that must be cancelled.
+
+### Focus Management
+
+Routing removes the previous page from the outlet. Configure focus management
+when a page change should be announced to keyboard and screen-reader users.
+
+```html
+<wavelength-router focus-strategy="heading">
+  <wavelength-route path="/" component="home-page"></wavelength-route>
+</wavelength-router>
+```
+
+`heading` focuses the first `h1` or level-one ARIA heading in the newly mounted
+page, adding `tabindex="-1"` when needed. `outlet` focuses the render outlet
+itself. If a Light DOM or open Shadow DOM heading is rendered asynchronously,
+the router waits up to five seconds before focusing. Both strategies work
+across Light DOM and open Shadow DOM. For targets that become ready later,
+dispatch `wavelength-focus-ready` as the component-owned focus handoff.
+
+An open root attached after navigation cannot be discovered by mutation
+observation alone. When its focus target is ready, dispatch a composed
+`wavelength-focus-ready` event from that target:
+
+```typescript
+heading.dispatchEvent(
+  new CustomEvent('wavelength-focus-ready', {
+    bubbles: true,
+    composed: true,
+  }),
+);
+```
+
+For a closed root, include the target in the event detail; this is an explicit
+component-to-router handoff and does not require exposing the root:
+
+```typescript
+heading.dispatchEvent(
+  new CustomEvent('wavelength-focus-ready', {
+    bubbles: true,
+    composed: true,
+    detail: { target: heading },
+  }),
+);
+```
+
+Direct `Router` users can also supply a callback for application-specific
+targets:
+
+```typescript
+const router = new Router(routes, {
+  outlet,
+  focusStrategy: (currentOutlet) =>
+    currentOutlet.querySelector<HTMLElement>('[data-route-focus]'),
+});
+```
+
+The callback should return a focusable element. Use `focusStrategy: 'none'` to
+retain the default behavior.
+
+Closed Shadow DOM is intentionally private. Components that render their focus
+target asynchronously in a closed root should focus that target themselves
+when it is ready.
+
+### Shadow DOM Navigation
+
+Links inside the router's Light DOM and open Shadow DOM descendants are
+intercepted automatically. Route declarations may also live in open Shadow DOM
+descendants of the router. Each nested router owns navigation from its own DOM
+subtree.
+
+Modified clicks, downloads, and links targeting another browsing context keep
+their native browser behavior. Same-document fragment links such as
+`href="#details"` also retain native scrolling behavior. The router handles
+only valid same-origin HTTP(S) destinations.
+
+```typescript
+const shell = document.querySelector('app-shell')!;
+const shadowRoot = shell.attachShadow({ mode: 'open' });
+shadowRoot.innerHTML = '<a href="/settings">Settings</a>';
+// The router resolves this link through the event's composed path.
+```
+
+If an open root is attached after the router connects, add its route
+declarations and then call `refresh()` so the router can scan and observe it:
+
+```typescript
+import type { RouterElement } from '@wavelengthusaf/client-router';
+
+const router = document.querySelector<RouterElement>('wavelength-router')!;
+const routeHost = document.querySelector('route-declarations')!;
+const shadowRoot = routeHost.attachShadow({ mode: 'open' });
+shadowRoot.innerHTML =
+  '<wavelength-route path="/reports" component="reports-page"></wavelength-route>';
+
+router.refresh();
+```
+
+Closed Shadow DOM intentionally hides its internal links from event delegation.
+Dispatch a composed `wavelength-navigate` event from the closed-root component
+instead:
+
+```typescript
+button.addEventListener('click', () => {
+  button.dispatchEvent(
+    new CustomEvent('wavelength-navigate', {
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+      detail: { path: '/account' },
+    }),
+  );
+});
+```
+
+Set `detail.replace` to `true` to replace the current history entry. Nested
+routers handle navigation only for their own DOM subtree.
+
+Closed roots also cannot be scanned for `<wavelength-route>` declarations.
+Their owning component can register definitions explicitly, then unregister
+them when it disconnects:
+
+```typescript
+import { RouteElement, RouterElement } from '@wavelengthusaf/client-router';
+import type { RouteDefinition } from '@wavelengthusaf/client-router';
+
+const router = this.closest<RouterElement>('wavelength-router')!;
+const definitions: RouteDefinition[] = Array.from(
+  this.#closedRoot.querySelectorAll<RouteElement>('wavelength-route'),
+).flatMap((route) => {
+  const definition = route.toDefinition({ document });
+  return definition ? [definition] : [];
+});
+
+this.#unregisterRoutes = router.registerRoutes(definitions);
+
+// In disconnectedCallback():
+this.#unregisterRoutes?.();
+```
+
+Registered definitions preserve their registration order and are inserted before
+the first declarative wildcard (`path="*"`). This keeps a declarative fallback
+from making closed-root routes unreachable. Registration captures a snapshot;
+to change closed-root definitions, unregister and register the new array.
+
+### Injected Browser Environment
+
+Direct `Router` instances accept optional `window` and `document` dependencies
+as their third constructor argument. This is useful for an iframe, a test DOM,
+or an application that needs to avoid implicit global browser access.
+
+```typescript
+const frame = document.querySelector('iframe')!;
+const router = new Router(
+  routes,
+  { outlet },
+  {
+    window: frame.contentWindow!,
+    document: frame.contentDocument!,
+  },
+);
+```
+
+### Matching Utilities
+
+`compileRoute()` and `matchRoute()` are exported for applications that need to
+inspect the same route patterns without mounting a router.
+
+```typescript
+import { compileRoute, matchRoute } from '@wavelengthusaf/client-router';
+
+const compiledRoutes = routes.map(compileRoute);
+const match = matchRoute(compiledRoutes, '/users/42');
+
+if (match) {
+  console.log(match.routeParams.userId); // "42"
+}
 ```
 
 ---
@@ -529,15 +896,50 @@ routeComponent: {
 
 ---
 
-## Development
+## Contributing and Local Development
+
+This section is for contributors working in this repository. Application users
+only need the package-installation steps above.
+
+### Repository Setup
+
+```bash
+git clone git@gitlab.wavelengthusaf.com:common-components/client-router.git
+cd wavelength-router
+npm install
+```
+
+Contributors should use Node.js 24 or newer. The GitLab pipeline runs on Node
+24 because it is the current LTS baseline for this project; Node 26 is still a
+Current release. This is documented project policy rather than an install-time
+constraint, because `package.json` does not currently declare an `engines`
+field.
+
+### Husky Setup
+
+Husky runs the repository's tests and lint checks before commits. It runs during
+`npm install`; if hooks need to be restored manually, run:
 
 ```bash
+npm run prepare
+```
+
+### Development Commands
+
+```bash
+# Type check
+npm run type-check
+
 # Run tests
 npm run test
 
 # Run tests with coverage
 npm run test -- --coverage
 
+# Run native-browser integration tests (install Chromium once with
+# `npx playwright install chromium`)
+npm run test:browser
+
 # Lint and format
 npm run lint
 npm run prettier
@@ -545,10 +947,31 @@ npm run prettier
 # Build for production
 npm run build
 
+# Build Storybook
+npm run build-storybook
+
 # Run Storybook for component development
 npm run storybook
 ```
 
+### CI/CD Expectations
+
+GitLab CI installs dependencies, builds the package, runs TypeScript checking,
+linting, unit tests, native-browser integration tests, and security checks.
+Before opening a merge request, run the same local regression set when feasible:
+
+```bash
+npm run type-check
+npm run lint
+npm run test
+npm run test:browser
+npm run build
+```
+
+Publishing to npm is tag-only. The publish job runs for semantic version tags,
+verifies the package build, skips versions already present on npm, and requires
+the `NPM_AUTH_TOKEN` CI variable.
+
 ---
 
 ## License