lit-navigation-router 0.2.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2021 Google LLC. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE.md

@@ -0,0 +1,168 @@
+# Provenance
+
+This is a fork of **`@lit-labs/router`**, which is not a standalone repository —
+it lives inside the `lit/lit` monorepo at `packages/labs/router`.
+
+| | |
+|---|---|
+| Upstream | https://github.com/lit/lit/tree/main/packages/labs/router |
+| Upstream version | `@lit-labs/router@0.1.4` (latest published at fork time) |
+| Upstream commit | `c42ee1e96b8fd61f7256f61d715daef572e76e52` |
+| Forked | 2026-07-31 |
+| Licence | BSD-3-Clause — unchanged, see `LICENSE` |
+
+Original copyright **Google LLC**, retained verbatim in `LICENSE` and in every
+per-file header. BSD-3-Clause requires retention of the copyright notice, the
+conditions and the disclaimer — it does *not* require a modification notice
+(that is Apache-2.0 §4(b)). Modified files carry one anyway, as a courtesy to
+anyone diffing against upstream.
+
+Published as `lit-navigation-router`. Deliberately *not* named
+`@lit-labs/router` — that name belongs to the Lit team, and a fork
+masquerading as upstream would be worse than useless when debugging. This
+package is not affiliated with or endorsed by Google or the Lit team; the
+reference to Lit describes what it is for.
+
+In the source repository (not the published tarball), `UPSTREAM-README.md` and
+`UPSTREAM-CHANGELOG.md` are upstream's, kept verbatim for reference, and
+`.upstream-commit` records the fork point.
+
+## Why fork
+
+Upstream `Router` intercepts navigation with a global click listener plus
+`popstate`, and commits with `history.pushState()`. That has a structural
+flaw: `pushState` is synchronous and `popstate` fires *after* the URL has
+already moved, but `Routes.goto()` awaits `route.enter()` before swapping the
+outlet. The URL leads and the outlet lags, which leaves two sources of truth.
+
+In arcsync that produced a run of bugs with one root cause — the outgoing route
+re-rendering with stale params, and quick successive navigations committing in
+whichever order their `enter()` hooks happened to resolve:
+
+- `VanLandinghamLabs/arcsync#258` — direct load of `/markdown/:id` degraded to a demo route
+- `VanLandinghamLabs/arcsync#632` — route commits landed in chunk-download order
+- `VanLandinghamLabs/arcsync#640` — a route re-entered its own loader
+- Tracking issue: `VanLandinghamLabs/arcsync#648`
+
+Upstream's own source carries the matching TODO, removed in this fork because
+it is now answered:
+
+> `// TODO (justinfagnani): do we need to detect when goto() is called while a previous goto() call is still pending?`
+
+## Changes from upstream
+
+### `src/router.ts` — rewritten on the Navigation API
+
+- Listens for `navigate` on `window.navigation` and calls
+  `navigateEvent.intercept({handler})`. The browser commits the URL and holds
+  the navigation un-finished while `goto()` runs, so URL and outlet move
+  together.
+- Threads `navigateEvent.signal` into `goto()` so a superseded navigation
+  stands down instead of racing.
+- Covers navigation the legacy path could not see at all: `navigation.navigate()`,
+  `history.pushState()`, and traversals — not just anchor clicks and popstate.
+- Skips what isn't ours: `!canIntercept`, `hashChange`, `downloadRequest`,
+  form submissions, and cross-origin destinations.
+- New `interceptOptions` field forwards `focusReset` / `scroll` to `intercept()`.
+- **The legacy click/popstate path is deleted.** Ten review rounds found
+  divergences between it and `_onNavigate`, and every one was in the click
+  handler — structural, not luck: `_onNavigate` reads a decision the browser
+  already made, while the click handler re-derived it, re-implementing the
+  rules for choosing a navigable, the fragment-navigation predicate and the
+  modifier-key rules. Each round found another place the re-implementation and
+  the spec disagreed. On an engine without the API links become ordinary full
+  page loads (slower, not broken, for a server that serves the shell on every
+  route); `supportsNavigationApi()` is exported so an app can detect it.
+
+### `src/routes.ts` — behavioural changes
+
+- `hostDisconnected` removes the `lit-routes-connected` listener that
+  `hostConnected` adds. Upstream leaves it, so a host that is disconnected and
+  reconnected (a `repeat()` reorder, a tab swap) ends up with two sibling
+  controllers registered as each other's child — a real `_childRoutes` cycle,
+  which turns `goto()`'s propagation loop and any recursive walk into a stack
+  overflow. `_supersede()` also carries a visited set as defence in depth.
+
+- `goto(pathname, options?)` accepts `options.signal`; an aborted signal after
+  `enter()` resolves makes `goto()` return without committing.
+- **Per-controller last-goto-wins counter.** The signal alone is not enough: a
+  child controller mounts as a *result* of its parent's render, so its first
+  `goto()` comes from `_onRoutesConnected` — after the parent's navigation has
+  already finished, holding a signal that will never abort. Without the counter
+  a slow first child load commits over a newer one. This also keeps `Routes`
+  correct standalone, with no `Router` and no Navigation API involved.
+- Child `goto()`s stay **unawaited** (as upstream) and, like upstream, are given
+  **no abort signal** — the parent commits before children run, so a child
+  handed an aborted signal stands down with no newer `goto()` to correct it and
+  the nested outlet sticks. A child with no route for the new tail (the outgoing
+  branch, mid-swap) is skipped structurally via `hasRouteFor`, so a genuine
+  `enter()` rejection still surfaces rather than being swallowed. An
+  earlier revision awaited them to make `navigation.finished` cover the whole
+  tree; that was wrong twice over — at that point `requestUpdate()` has not run,
+  so `_childRoutes` still holds the *outgoing* branch, and awaiting it both
+  gated the parent's outlet swap on an `enter()` for a tail that child would
+  never render, and let its `No route found` throw strand the parent entirely.
+  Nested supersession is the counter's job, not the await's.
+- New `hasRouteFor(pathname)`, used by `Router` to decline what it cannot
+  render.
+
+### Known limits
+
+- `navigation.finished` covers the top-level route, not nested ones. Making it
+  cover the tree needs awaiting the children the navigation is moving *to*,
+  which means awaiting past `requestUpdate()` and the host's update cycle — a
+  materially bigger change than it looks.
+- `hasRouteFor()` is a no-op for apps that configure a root `fallback`, since
+  every path then matches. That is the app's stated intent, but it means the
+  "decline what we cannot render" fix does not reach that configuration.
+- `goto()` still ignores the query string (upstream limitation), so a GET form
+  whose action matches a route is intercepted and loses its query.
+- The `seen` set in `_supersede()` is defence in depth and unpinned **by
+  construction**: since `hostDisconnected` removes its listener, no test can
+  build a `_childRoutes` cycle any more.
+- A child skipped because it cannot render the new tail keeps its previously
+  *committed* outlet — it is superseded (no in-flight navigation can commit)
+  but not cleared, so it goes on rendering the route the URL has left. Upstream
+  had the same end state by a different route (`No route found` threw before
+  any state changed). Clearing it needs `_currentRoute` reset plus a host
+  update, which is a behaviour change rather than a bug fix.
+
+### Build and tests
+
+Upstream's package is wired into the lit monorepo (wireit, `@lit-internal/scripts`,
+`treemirror`, `../../tests`). This fork replaces that with plain `tsc` + Web Test
+Runner so it stands alone. Test changes:
+
+- Imports rewritten from `@lit-labs/router/*` to relative paths.
+- `stripExpressionComments` reimplemented locally (`src/test/test-helpers.ts`)
+  in place of the monorepo-internal `@lit-labs/testing`.
+- `chai` → `@open-wc/testing` (browser-native ESM).
+- Two `(r: RouteConfig)` annotations added in `router_test.ts` (upstream relied
+  on monorepo-wide inference). **Otherwise upstream's 6 tests are unmodified and
+  pass**, which is the main evidence that the rewrite preserves behaviour.
+- 14 new tests in `src/test/navigation_test.ts` cover the Navigation API path.
+  The first asserts the suite is actually running against `window.navigation`
+  rather than silently falling back — without it the rest would pass against the
+  legacy path and prove nothing. It is kept as a guard for the day this
+  package's requirement changes.
+
+## Verified
+
+`npm test` → 20 passed (6 upstream + 14 new), Chromium via Playwright.
+
+Run `npm run clean` before a mutation check: the build is `composite`/
+`incremental`, and a stale `development/` can contain a hunk's comment without
+its code, greening the suite against output that lacks the change.
+
+## Merging upstream later
+
+`.upstream-commit` in the repository records the fork point. To pull upstream
+changes:
+
+```sh
+git clone --depth 1 --filter=blob:none --sparse https://github.com/lit/lit.git
+cd lit && git sparse-checkout set packages/labs/router
+```
+
+then diff `packages/labs/router/src` against this repo's `src`. Only
+`router.ts` and `goto()` in `routes.ts` diverge meaningfully.

package/README.md

@@ -0,0 +1,120 @@
+# lit-navigation-router
+
+A router for Lit, built on the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API).
+
+Fork of [`@lit-labs/router`](https://github.com/lit/lit/tree/main/packages/labs/router)
+— see [NOTICE.md](./NOTICE.md) for provenance, licence and the full list of
+changes. Not affiliated with or endorsed by Google or the Lit team.
+
+```sh
+npm i lit-navigation-router
+```
+
+## Why
+
+Upstream commits navigation with `history.pushState()` and reacts to `popstate`,
+but swaps the outlet only after awaiting `route.enter()`. The URL therefore
+leads and the outlet lags, so the route being left re-renders with stale params
+and two quick navigations can commit out of order.
+
+`navigateEvent.intercept()` removes that: the browser commits the URL and holds
+the navigation un-finished while the handler runs, and aborts
+`navigateEvent.signal` when a newer navigation supersedes this one.
+
+## Usage
+
+Identical to upstream:
+
+```ts
+import {Router} from 'lit-navigation-router/router.js';
+
+class MyApp extends LitElement {
+  private _router = new Router(this, [
+    {path: '/', render: () => html`<h1>Home</h1>`},
+    {
+      path: '/item/:id',
+      enter: async () => {
+        await import('./item-view.js'); // awaited before the outlet swaps
+        return true;
+      },
+      render: ({id}) => html`<item-view .id=${id}></item-view>`,
+    },
+  ]);
+
+  render() {
+    return html`${this._router.outlet()}`;
+  }
+}
+```
+
+Two additions:
+
+```ts
+// Forwarded to navigateEvent.intercept()
+this._router.interceptOptions = {scroll: 'manual', focusReset: 'manual'};
+
+// goto() takes an abort signal; Router passes navigateEvent.signal for you
+await routes.goto('/item/1', {signal});
+```
+
+## Browser support — please read
+
+This router **requires the Navigation API**. There is no legacy fallback.
+
+The API is Baseline **Newly** Available (January 2026: Chrome/Edge, Safari 26.2,
+Firefox 147). Baseline **Widely** Available is not until roughly mid-2028, so
+older engines are still in the wild.
+
+On an engine without it, `Router` renders the current route on load but does not
+intercept navigation — every link becomes an ordinary full page load. If your
+server serves the app shell on every route that is slower, not broken. If it
+does not, those links 404.
+
+**One case is genuinely broken, not just slow.** If you navigate
+programmatically with `history.pushState()` + `router.goto()`, nothing listens
+for the resulting `popstate` — so Back moves the URL while the outlet stays put,
+which is the URL/outlet split this fork exists to eliminate. Apps using that
+pattern should gate on `supportsNavigationApi()` rather than accept the
+degradation.
+
+`supportsNavigationApi()` is exported so you can detect this at boot:
+
+```ts
+import {supportsNavigationApi} from 'lit-navigation-router/router.js';
+
+if (!supportsNavigationApi()) {
+  showUpgradePrompt();
+}
+```
+
+If you need real pre-2026 support, pair this with a Navigation API polyfill
+rather than a second router: one decision path, with compatibility isolated in
+a layer whose whole job is spec accuracy.
+
+## `URLPattern`
+
+Route patterns are compiled with `URLPattern`, which this package uses from the
+global scope and does **not** polyfill — same as upstream. Every engine that has
+the Navigation API also has `URLPattern`, so if the support check above passes
+you need nothing. If you support older engines anyway, load
+[`urlpattern-polyfill`](https://www.npmjs.com/package/urlpattern-polyfill)
+before the router:
+
+```ts
+import {URLPattern} from 'urlpattern-polyfill';
+if (!globalThis.URLPattern) {
+  (globalThis as {URLPattern?: unknown}).URLPattern = URLPattern;
+}
+```
+
+The published types do not depend on it — `URLPatternRouteConfig.pattern` is
+typed structurally, so a consumer build never needs the polyfill's types.
+
+## Develop
+
+```sh
+npm install
+npm run build        # tsc → development/
+npm test             # Web Test Runner (Chromium via Playwright)
+npm run check-types
+```

package/development/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+export * from './routes.js';
+export { Router, supportsNavigationApi } from './router.js';
+export type { InterceptOptions } from './router.js';
+//# sourceMappingURL=index.d.ts.map

package/development/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAC,MAAM,EAAE,qBAAqB,EAAC,MAAM,aAAa,CAAC;AAC1D,YAAY,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC"}

package/development/index.js

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+export * from './routes.js';
+export { Router, supportsNavigationApi } from './router.js';
+//# sourceMappingURL=index.js.map

package/development/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAC,MAAM,EAAE,qBAAqB,EAAC,MAAM,aAAa,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2021 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\nexport * from './routes.js';\nexport {Router, supportsNavigationApi} from './router.js';\nexport type {InterceptOptions} from './router.js';\n"]}

package/development/router.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * Modifications Copyright 2026 VanLandingham Labs, same license.
+ * Rebuilt on the Navigation API; see NOTICE.md.
+ */
+import { Routes } from './routes.js';
+/** The subset of `NavigationInterceptOptions` this router forwards. */
+export interface InterceptOptions {
+    focusReset?: 'after-transition' | 'manual';
+    scroll?: 'after-transition' | 'manual';
+}
+/**
+ * True when the Navigation API is available — Baseline Newly Available since
+ * January 2026 (Chrome/Edge, Safari 26.2, Firefox 147).
+ *
+ * This router **requires** it. Exported so an app can detect an unsupported
+ * engine at boot and say so, rather than leaving the user to notice that every
+ * link reloads the page.
+ */
+export declare const supportsNavigationApi: () => boolean;
+/**
+ * A root-level router that intercepts navigation via the Navigation API.
+ *
+ * This class extends Routes so that it can also have a route configuration.
+ *
+ * There should only be one Router instance on a page, since the Router
+ * installs a global listener. Nested routes should be configured with the
+ * `Routes` class.
+ *
+ * ## Why the Navigation API
+ *
+ * Upstream intercepted navigation with a global click listener plus `popstate`
+ * and committed with `history.pushState()`. That is structurally racy:
+ * `pushState` is synchronous and `popstate` fires *after* the URL has already
+ * moved, but `goto()` awaits `route.enter()` before swapping the outlet. The
+ * URL leads and the outlet lags, leaving two sources of truth — the outgoing
+ * route re-renders with stale params, and two quick navigations commit in
+ * whatever order their `enter()` hooks happen to resolve.
+ *
+ * `navigateEvent.intercept({handler})` collapses that. The browser commits the
+ * URL and holds the navigation un-finished while the handler runs, and it
+ * aborts `navigateEvent.signal` when a newer navigation supersedes this one —
+ * which `goto()` honours, so a superseded route can no longer win the outlet.
+ *
+ * ## No legacy fallback
+ *
+ * An earlier version of this fork kept upstream's click/popstate path for
+ * pre-2026 engines. It was removed deliberately. Ten review rounds found
+ * divergences between the two paths and **every one was in the click handler**,
+ * never in this one — which is structural, not luck: this handler reads a
+ * decision the browser has already made, while the click handler had to
+ * re-derive it, re-implementing the rules for choosing a navigable, the
+ * fragment-navigation predicate, and the modifier-key rules. Each round found
+ * another place where the re-implementation and the spec disagreed.
+ *
+ * On an engine without the API, links fall back to ordinary full page loads.
+ * For an app whose server serves the shell on every route that still works —
+ * it is slower, not broken — and `supportsNavigationApi()` lets you detect it.
+ * If real pre-2026 support is ever needed, use a Navigation API polyfill: one
+ * decision path, with compatibility isolated in a layer whose whole job is
+ * spec accuracy.
+ */
+export declare class Router extends Routes {
+    /**
+     * Options forwarded to `navigateEvent.intercept()`. Leaving these unset
+     * gives the browser's default scroll and focus handling.
+     */
+    interceptOptions?: InterceptOptions;
+    private _listening;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Handles same-document navigation from every source at once: anchor clicks,
+     * `navigation.navigate()`, `history.pushState()`, and back/forward.
+     */
+    private _onNavigate;
+}
+//# sourceMappingURL=router.d.ts.map

package/development/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AAwBnC,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,kBAAkB,GAAG,QAAQ,CAAC;IAC3C,MAAM,CAAC,EAAE,kBAAkB,GAAG,QAAQ,CAAC;CACxC;AAgBD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,QAAO,OAEgB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBAAa,MAAO,SAAQ,MAAM;IAChC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC,OAAO,CAAC,UAAU,CAAS;IAElB,aAAa;IAwBb,gBAAgB;IAQzB;;;OAGG;IACH,OAAO,CAAC,WAAW,CAmDjB;CACH"}

package/development/router.js

@@ -0,0 +1,154 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * Modifications Copyright 2026 VanLandingham Labs, same license.
+ * Rebuilt on the Navigation API; see NOTICE.md.
+ */
+import { Routes } from './routes.js';
+// We cache the origin since it can't change
+const origin = location.origin || location.protocol + '//' + location.host;
+const getNavigation = () => window.navigation;
+/**
+ * True when the Navigation API is available — Baseline Newly Available since
+ * January 2026 (Chrome/Edge, Safari 26.2, Firefox 147).
+ *
+ * This router **requires** it. Exported so an app can detect an unsupported
+ * engine at boot and say so, rather than leaving the user to notice that every
+ * link reloads the page.
+ */
+export const supportsNavigationApi = () => typeof window !== 'undefined' &&
+    typeof getNavigation()?.addEventListener === 'function';
+/**
+ * A root-level router that intercepts navigation via the Navigation API.
+ *
+ * This class extends Routes so that it can also have a route configuration.
+ *
+ * There should only be one Router instance on a page, since the Router
+ * installs a global listener. Nested routes should be configured with the
+ * `Routes` class.
+ *
+ * ## Why the Navigation API
+ *
+ * Upstream intercepted navigation with a global click listener plus `popstate`
+ * and committed with `history.pushState()`. That is structurally racy:
+ * `pushState` is synchronous and `popstate` fires *after* the URL has already
+ * moved, but `goto()` awaits `route.enter()` before swapping the outlet. The
+ * URL leads and the outlet lags, leaving two sources of truth — the outgoing
+ * route re-renders with stale params, and two quick navigations commit in
+ * whatever order their `enter()` hooks happen to resolve.
+ *
+ * `navigateEvent.intercept({handler})` collapses that. The browser commits the
+ * URL and holds the navigation un-finished while the handler runs, and it
+ * aborts `navigateEvent.signal` when a newer navigation supersedes this one —
+ * which `goto()` honours, so a superseded route can no longer win the outlet.
+ *
+ * ## No legacy fallback
+ *
+ * An earlier version of this fork kept upstream's click/popstate path for
+ * pre-2026 engines. It was removed deliberately. Ten review rounds found
+ * divergences between the two paths and **every one was in the click handler**,
+ * never in this one — which is structural, not luck: this handler reads a
+ * decision the browser has already made, while the click handler had to
+ * re-derive it, re-implementing the rules for choosing a navigable, the
+ * fragment-navigation predicate, and the modifier-key rules. Each round found
+ * another place where the re-implementation and the spec disagreed.
+ *
+ * On an engine without the API, links fall back to ordinary full page loads.
+ * For an app whose server serves the shell on every route that still works —
+ * it is slower, not broken — and `supportsNavigationApi()` lets you detect it.
+ * If real pre-2026 support is ever needed, use a Navigation API polyfill: one
+ * decision path, with compatibility isolated in a layer whose whole job is
+ * spec accuracy.
+ */
+export class Router extends Routes {
+    /**
+     * Options forwarded to `navigateEvent.intercept()`. Leaving these unset
+     * gives the browser's default scroll and focus handling.
+     */
+    interceptOptions;
+    _listening = false;
+    hostConnected() {
+        super.hostConnected();
+        // Gated on the exported predicate, not on `navigation !== undefined`:
+        // a stub or partial polyfill under that name would otherwise make this
+        // branch throw out of connectedCallback while `supportsNavigationApi()`
+        // told the app it was unsupported — and then even the initial render below
+        // would not run.
+        if (supportsNavigationApi()) {
+            getNavigation().addEventListener('navigate', this._onNavigate);
+            this._listening = true;
+        }
+        // Kick off routed rendering by going to the current URL. Done even without
+        // the API: a full page load still renders the right route, which is what
+        // makes the unsupported-engine degradation "slow" rather than "blank".
+        // Surfaced rather than left as a bare unhandled rejection, matching the
+        // convention in routes.ts: on an engine without the API this is the *only*
+        // rendering path, and a deep link with no matching route throws here.
+        void this.goto(window.location.pathname).catch((err) => {
+            queueMicrotask(() => {
+                throw err;
+            });
+        });
+    }
+    hostDisconnected() {
+        super.hostDisconnected();
+        if (this._listening) {
+            getNavigation()?.removeEventListener('navigate', this._onNavigate);
+            this._listening = false;
+        }
+    }
+    /**
+     * Handles same-document navigation from every source at once: anchor clicks,
+     * `navigation.navigate()`, `history.pushState()`, and back/forward.
+     */
+    _onNavigate = (e) => {
+        // Not ours to handle: anything the browser says cannot be intercepted,
+        // fragment-only moves, downloads, and POST form submissions.
+        if (!e.canIntercept || e.hashChange || e.downloadRequest !== null) {
+            return;
+        }
+        if (e.formData) {
+            return;
+        }
+        // Reloads must stay reloads. `canIntercept` is true for them, so without
+        // this `location.reload()` silently degrades to re-running goto() on the
+        // same path — the document is never replaced, breaking the standard
+        // "new version available, reload" escape hatch. (It would also disagree
+        // with the browser's own refresh button, which is not interceptable.)
+        if (e.navigationType === 'reload') {
+            return;
+        }
+        // `rel="external"` is a convention this router honours — it is not defined
+        // by HTML or by the Navigation API, so the browser will not decline these
+        // for us. Best-effort: `sourceElement` is not in every engine, and is
+        // absent for programmatic navigation.
+        if (e.sourceElement?.getAttribute?.('rel') === 'external') {
+            return;
+        }
+        const url = new URL(e.destination.url);
+        if (url.origin !== origin) {
+            return;
+        }
+        // Only intercept what we can actually render. `canIntercept` is true for
+        // any same-origin URL, including cross-document ones — so without this a
+        // link to a server-rendered page, an export endpoint, or a GET form
+        // (whose `formData` is null) gets swallowed: the URL commits, goto()
+        // throws "No route found", and the address bar is left pointing somewhere
+        // the outlet never went. Declining lets the browser do the real
+        // navigation, which is the correct outcome.
+        if (!this.hasRouteFor(url.pathname)) {
+            return;
+        }
+        e.intercept({
+            ...this.interceptOptions,
+            handler: async () => {
+                // `e.signal` aborts if another navigation starts before this handler
+                // resolves; goto() checks it after `enter()` and stands down.
+                await this.goto(url.pathname, { signal: e.signal });
+            },
+        });
+    };
+}
+//# sourceMappingURL=router.js.map

package/development/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @license\n * Copyright 2021 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n *\n * Modifications Copyright 2026 VanLandingham Labs, same license.\n * Rebuilt on the Navigation API; see NOTICE.md.\n */\n\nimport {Routes} from './routes.js';\n\n// We cache the origin since it can't change\nconst origin = location.origin || location.protocol + '//' + location.host;\n\n/**\n * The slice of `NavigateEvent` this router reads. Declared locally rather than\n * typing the handler `any`: these properties *are* the correctness boundary, so\n * a typo like `hashchange` for `hashChange` would silently disable a filter\n * forever. Names verified against Chromium's `NavigateEvent.prototype`.\n */\ninterface NavigateEventLike {\n  readonly canIntercept: boolean;\n  readonly hashChange: boolean;\n  readonly downloadRequest: string | null;\n  readonly formData: FormData | null;\n  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';\n  readonly signal: AbortSignal;\n  readonly destination: {readonly url: string};\n  /** Not in every engine yet; used only as a best-effort `rel` check. */\n  readonly sourceElement?: Element | null;\n  intercept(options: InterceptOptions & {handler?: () => Promise<void>}): void;\n}\n\n/** The subset of `NavigationInterceptOptions` this router forwards. */\nexport interface InterceptOptions {\n  focusReset?: 'after-transition' | 'manual';\n  scroll?: 'after-transition' | 'manual';\n}\n\ninterface NavigationLike {\n  addEventListener(\n    type: 'navigate',\n    listener: (e: NavigateEventLike) => void\n  ): void;\n  removeEventListener(\n    type: 'navigate',\n    listener: (e: NavigateEventLike) => void\n  ): void;\n}\n\nconst getNavigation = (): NavigationLike | undefined =>\n  (window as unknown as {navigation?: NavigationLike}).navigation;\n\n/**\n * True when the Navigation API is available — Baseline Newly Available since\n * January 2026 (Chrome/Edge, Safari 26.2, Firefox 147).\n *\n * This router **requires** it. Exported so an app can detect an unsupported\n * engine at boot and say so, rather than leaving the user to notice that every\n * link reloads the page.\n */\nexport const supportsNavigationApi = (): boolean =>\n  typeof window !== 'undefined' &&\n  typeof getNavigation()?.addEventListener === 'function';\n\n/**\n * A root-level router that intercepts navigation via the Navigation API.\n *\n * This class extends Routes so that it can also have a route configuration.\n *\n * There should only be one Router instance on a page, since the Router\n * installs a global listener. Nested routes should be configured with the\n * `Routes` class.\n *\n * ## Why the Navigation API\n *\n * Upstream intercepted navigation with a global click listener plus `popstate`\n * and committed with `history.pushState()`. That is structurally racy:\n * `pushState` is synchronous and `popstate` fires *after* the URL has already\n * moved, but `goto()` awaits `route.enter()` before swapping the outlet. The\n * URL leads and the outlet lags, leaving two sources of truth — the outgoing\n * route re-renders with stale params, and two quick navigations commit in\n * whatever order their `enter()` hooks happen to resolve.\n *\n * `navigateEvent.intercept({handler})` collapses that. The browser commits the\n * URL and holds the navigation un-finished while the handler runs, and it\n * aborts `navigateEvent.signal` when a newer navigation supersedes this one —\n * which `goto()` honours, so a superseded route can no longer win the outlet.\n *\n * ## No legacy fallback\n *\n * An earlier version of this fork kept upstream's click/popstate path for\n * pre-2026 engines. It was removed deliberately. Ten review rounds found\n * divergences between the two paths and **every one was in the click handler**,\n * never in this one — which is structural, not luck: this handler reads a\n * decision the browser has already made, while the click handler had to\n * re-derive it, re-implementing the rules for choosing a navigable, the\n * fragment-navigation predicate, and the modifier-key rules. Each round found\n * another place where the re-implementation and the spec disagreed.\n *\n * On an engine without the API, links fall back to ordinary full page loads.\n * For an app whose server serves the shell on every route that still works —\n * it is slower, not broken — and `supportsNavigationApi()` lets you detect it.\n * If real pre-2026 support is ever needed, use a Navigation API polyfill: one\n * decision path, with compatibility isolated in a layer whose whole job is\n * spec accuracy.\n */\nexport class Router extends Routes {\n  /**\n   * Options forwarded to `navigateEvent.intercept()`. Leaving these unset\n   * gives the browser's default scroll and focus handling.\n   */\n  interceptOptions?: InterceptOptions;\n\n  private _listening = false;\n\n  override hostConnected() {\n    super.hostConnected();\n    // Gated on the exported predicate, not on `navigation !== undefined`:\n    // a stub or partial polyfill under that name would otherwise make this\n    // branch throw out of connectedCallback while `supportsNavigationApi()`\n    // told the app it was unsupported — and then even the initial render below\n    // would not run.\n    if (supportsNavigationApi()) {\n      getNavigation()!.addEventListener('navigate', this._onNavigate);\n      this._listening = true;\n    }\n    // Kick off routed rendering by going to the current URL. Done even without\n    // the API: a full page load still renders the right route, which is what\n    // makes the unsupported-engine degradation \"slow\" rather than \"blank\".\n    // Surfaced rather than left as a bare unhandled rejection, matching the\n    // convention in routes.ts: on an engine without the API this is the *only*\n    // rendering path, and a deep link with no matching route throws here.\n    void this.goto(window.location.pathname).catch((err) => {\n      queueMicrotask(() => {\n        throw err;\n      });\n    });\n  }\n\n  override hostDisconnected() {\n    super.hostDisconnected();\n    if (this._listening) {\n      getNavigation()?.removeEventListener('navigate', this._onNavigate);\n      this._listening = false;\n    }\n  }\n\n  /**\n   * Handles same-document navigation from every source at once: anchor clicks,\n   * `navigation.navigate()`, `history.pushState()`, and back/forward.\n   */\n  private _onNavigate = (e: NavigateEventLike) => {\n    // Not ours to handle: anything the browser says cannot be intercepted,\n    // fragment-only moves, downloads, and POST form submissions.\n    if (!e.canIntercept || e.hashChange || e.downloadRequest !== null) {\n      return;\n    }\n    if (e.formData) {\n      return;\n    }\n\n    // Reloads must stay reloads. `canIntercept` is true for them, so without\n    // this `location.reload()` silently degrades to re-running goto() on the\n    // same path — the document is never replaced, breaking the standard\n    // \"new version available, reload\" escape hatch. (It would also disagree\n    // with the browser's own refresh button, which is not interceptable.)\n    if (e.navigationType === 'reload') {\n      return;\n    }\n\n    // `rel=\"external\"` is a convention this router honours — it is not defined\n    // by HTML or by the Navigation API, so the browser will not decline these\n    // for us. Best-effort: `sourceElement` is not in every engine, and is\n    // absent for programmatic navigation.\n    if (e.sourceElement?.getAttribute?.('rel') === 'external') {\n      return;\n    }\n\n    const url = new URL(e.destination.url);\n    if (url.origin !== origin) {\n      return;\n    }\n\n    // Only intercept what we can actually render. `canIntercept` is true for\n    // any same-origin URL, including cross-document ones — so without this a\n    // link to a server-rendered page, an export endpoint, or a GET form\n    // (whose `formData` is null) gets swallowed: the URL commits, goto()\n    // throws \"No route found\", and the address bar is left pointing somewhere\n    // the outlet never went. Declining lets the browser do the real\n    // navigation, which is the correct outcome.\n    if (!this.hasRouteFor(url.pathname)) {\n      return;\n    }\n\n    e.intercept({\n      ...this.interceptOptions,\n      handler: async () => {\n        // `e.signal` aborts if another navigation starts before this handler\n        // resolves; goto() checks it after `enter()` and stands down.\n        await this.goto(url.pathname, {signal: e.signal});\n      },\n    });\n  };\n}\n"]}