@timber-js/app 0.2.0-alpha.67 → 0.2.0-alpha.69

package/dist/server/route-element-builder.d.ts

@@ -18,6 +18,16 @@ import type { RouteMatch } from './pipeline.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import { DenySignal, RedirectSignal } from './primitives.js';
 import type { InterceptionContext } from './pipeline.js';
+/**
+ * Detect whether a component is a React client reference.
+ * Client references have $$typeof set to Symbol.for('react.client.reference')
+ * by registerClientReference() in the React Flight server runtime.
+ *
+ * Used to skip OTEL tracing wrappers that would call the component as a
+ * function. Client components must go through createElement only — they are
+ * serialized as references in the RSC Flight stream, not executed on the server.
+ */
+export declare function isClientReference(component: unknown): boolean;
 /**
  * Thrown when a defineSegmentParams codec's parse() fails.
  * The pipeline catches this and responds with 404.

package/dist/server/route-element-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAM7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAMzD;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAID,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,UAAU,GAAG,cAAc;aACnC,gBAAgB,EAAE,oBAAoB,EAAE;aACxC,QAAQ,EAAE,mBAAmB,EAAE;gBAF/B,MAAM,EAAE,UAAU,GAAG,cAAc,EACnC,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,QAAQ,EAAE,mBAAmB,EAAE;CAIlD;AA8DD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACnC,OAAO,CAAC,kBAAkB,CAAC,CA6R7B"}
+{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAM7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAezD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,CAM7D;AAID;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAID,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,UAAU,GAAG,cAAc;aACnC,gBAAgB,EAAE,oBAAoB,EAAE;aACxC,QAAQ,EAAE,mBAAmB,EAAE;gBAF/B,MAAM,EAAE,UAAU,GAAG,cAAc,EACnC,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,QAAQ,EAAE,mBAAmB,EAAE;CAIlD;AA8DD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAiT7B"}

package/dist/server/slot-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"slot-resolver.d.ts","sourceRoot":"","sources":["../../src/server/slot-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,KAAK,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,KAAK,CAAC,YAAY,CAAC;AAmHlE;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,UAAU,EACjB,CAAC,EAAE,eAAe,EAClB,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CA+FpC"}
+{"version":3,"file":"slot-resolver.d.ts","sourceRoot":"","sources":["../../src/server/slot-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,KAAK,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,KAAK,CAAC,YAAY,CAAC;AAmHlE;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,UAAU,EACjB,CAAC,EAAE,eAAe,EAClB,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAgGpC"}

package/dist/server/ssr-wrappers.d.ts

@@ -8,7 +8,7 @@
  * Radix UI that rely on useId() internally.
  *
  * The client tree (browser-entry.ts) wraps the RSC element with:
- *   TransitionRoot → PendingNavigationProvider → Fragment(TopLoader, ...) →
+ *   NavigationRoot → PendingNavigationProvider → Fragment(TopLoader, ...) →
  *     TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider → element
  *
  * The SSR tree must produce the same component boundaries. These wrappers
@@ -25,7 +25,7 @@ import { type ReactNode } from 'react';
  * on both sides.
  *
  * Client tree (browser-entry.ts):
- *   TransitionRoot
+ *   NavigationRoot
  *     → PendingNavigationProvider
  *       → Fragment(TopLoader, element)
  *         → TimberNuqsAdapter
@@ -34,7 +34,7 @@ import { type ReactNode } from 'react';
  *               → [RSC element]
  *
  * SSR tree (this function):
- *   SsrTransitionRoot
+ *   SsrNavigationRoot
  *     → SsrPendingProvider
  *       → Fragment(SsrTopLoader, element)
  *         → SsrNuqsWrapper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.67",
+  "version": "0.2.0-alpha.69",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -88,11 +88,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.6.1",
@@ -131,5 +126,9 @@
   },
   "engines": {
     "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/client/browser-entry.ts

@@ -59,11 +59,12 @@ import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.
 // browser-links.ts removed — Link components own their click/hover handlers directly.
 // See LOCAL-340.
 import {
-  TransitionRoot,
+  NavigationRoot,
   transitionRender,
   navigateTransition,
   installDeferredNavigation,
-} from './transition-root.js';
+  setHardNavigating,
+} from './navigation-root.js';
 import {
   isStaleClientReference,
   isChunkLoadError,
@@ -76,6 +77,11 @@ import {
   DEPLOYMENT_ID_HEADER,
   RELOAD_HEADER,
 } from './rsc-fetch.js';
+import {
+  hasNavigationApi,
+  setupNavigationApi,
+  type NavigationApiController,
+} from './navigation-api.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -152,7 +158,10 @@ setServerCallback(async (id: string, args: unknown[]) => {
       const router = getRouter();
       void router.navigate(wrapper._redirect);
     } catch {
-      // Router not yet initialized — fall back to full navigation
+      // Router not yet initialized — fall back to full navigation.
+      // Set hard-navigating flag to prevent Navigation API interception
+      // and React from rendering during page teardown. See TIM-626.
+      setHardNavigating(true);
       window.location.href = wrapper._redirect;
     }
     return undefined;
@@ -257,6 +266,12 @@ function bootstrap(runtimeConfig: typeof config): void {
   // Assigned inside initRouter() which is called in both branches.
   let router!: RouterInstance;
 
+  // Navigation API controller — initialized when the API is available.
+  // Declared here (before the hydration if/else) because initRouter()
+  // is called from runPreHydration() inside both branches, and it
+  // assigns to this variable. Must be in scope before first use.
+  let navApiController: NavigationApiController | null = null;
+
   if (timberChunks) {
     const encoder = new TextEncoder();
 
@@ -402,10 +417,10 @@ function bootstrap(runtimeConfig: typeof config): void {
     // Hydrate on document — the root layout renders the full <html> tree,
     // so React owns the entire document from the root.
     // Wrap with NavigationProvider (for atomic useParams/usePathname),
-    // TimberNuqsAdapter (for nuqs context), and TransitionRoot (for
+    // TimberNuqsAdapter (for nuqs context), and NavigationRoot (for
     // transition-based rendering during client navigation).
     //
-    // TransitionRoot holds the element in React state and updates via
+    // NavigationRoot holds the element in React state and updates via
     // startTransition, so React keeps old UI visible while new Suspense
     // boundaries resolve during navigation. See design/05-streaming.md.
     const navState = getNavigationState();
@@ -415,7 +430,7 @@ function bootstrap(runtimeConfig: typeof config): void {
       element as React.ReactNode
     );
     const wrapped = createElement(TimberNuqsAdapter, null, withNav);
-    const rootElement = createElement(TransitionRoot, {
+    const rootElement = createElement(NavigationRoot, {
       initial: wrapped,
       topLoaderConfig: _config.topLoader,
     });
@@ -459,13 +474,13 @@ function bootstrap(runtimeConfig: typeof config): void {
     // Instead, installDeferredNavigation sets up one-shot callbacks so the
     // first navigateTransition/transitionRender call creates the root on
     // `document` with the navigated content. After that initial render,
-    // TransitionRoot's real startTransition-based callbacks take over.
+    // NavigationRoot's real startTransition-based callbacks take over.
     //
     // This also fixes TIM-580 (navigation from SSR-only pages) because the
-    // deferred callbacks ensure TransitionRoot is mounted before the first
+    // deferred callbacks ensure NavigationRoot is mounted before the first
     // navigation completes.
     installDeferredNavigation((initial) => {
-      const rootElement = createElement(TransitionRoot, {
+      const rootElement = createElement(NavigationRoot, {
         initial,
         topLoaderConfig: _config.topLoader,
       });
@@ -478,12 +493,18 @@ function bootstrap(runtimeConfig: typeof config): void {
   // Extracted into a function so both the hydration and createRoot paths
   // can call it. Must run before hydrateRoot so useRouter() works during
   // the initial render. renderRoot uses transitionRender which is set
-  // by the TransitionRoot component during hydration.
+  // by the NavigationRoot component during hydration.
   function initRouter(): void {
+    // Feature-detect Navigation API. When available, the navigate event
+    // replaces popstate for back/forward and catches external navigations.
+    // See design/19-client-navigation.md §"Navigation API Integration"
+    const useNavApi = hasNavigationApi();
+
     const deps: RouterDeps = {
       fetch: (url, init) => window.fetch(url, init),
       pushState: (data, unused, url) => window.history.pushState(data, unused, url),
       replaceState: (data, unused, url) => window.history.replaceState(data, unused, url),
+      navigationApiActive: useNavApi,
       scrollTo: (x, y) => {
         // Scroll the document viewport.
         window.scrollTo(x, y);
@@ -526,7 +547,7 @@ function bootstrap(runtimeConfig: typeof config): void {
         }
       },
 
-      // Render decoded RSC tree via TransitionRoot's state-based mechanism.
+      // Render decoded RSC tree via NavigationRoot's state-based mechanism.
       // Used for non-navigation renders (popstate cached replay, applyRevalidation).
       // Wraps with NavigationProvider + TimberNuqsAdapter.
       //
@@ -584,6 +605,37 @@ function bootstrap(runtimeConfig: typeof config): void {
 
     router = createRouter(deps);
     setGlobalRouter(router);
+
+    // Set up Navigation API integration after router is created.
+    // The navigate event listener delegates to router.navigate and
+    // router.handlePopState for external navigations and traversals.
+    if (useNavApi) {
+      navApiController = setupNavigationApi({
+        onExternalNavigate: async (url, { replace, signal, scroll }) => {
+          // Navigation intercepted by the Navigation API. Covers both
+          // Link <a> clicks (user-initiated) and external navigations.
+          // The Navigation API handles the URL update via intercept(),
+          // so pass _skipHistory to avoid double pushState.
+          await router.navigate(url, {
+            replace,
+            scroll,
+            _signal: signal,
+            _skipHistory: true,
+          });
+        },
+        onTraverse: async (url, scrollY, signal) => {
+          // Back/forward — delegate to the router's popstate handler.
+          await router.handlePopState(url, scrollY, signal);
+        },
+      });
+
+      // Wire the router-navigating flag into RouterDeps.
+      // This must be done after setupNavigationApi returns the controller.
+      deps.setRouterNavigating = (v) => navApiController!.setRouterNavigating(v);
+      deps.saveNavigationEntryScroll = (y) => navApiController!.saveScrollPosition(y);
+      deps.completeRouterNavigation = () => navApiController!.completeRouterNavigation();
+      deps.navigationNavigate = (url, replace) => navApiController!.navigate(url, replace);
+    }
   }
 
   // ── Pre-hydration sequence ──────────────────────────────────────────
@@ -619,9 +671,17 @@ function bootstrap(runtimeConfig: typeof config): void {
     headElements: null, // SSR already set the correct head
   });
 
-  // Initialize history.state with scrollY for the initial entry.
-  // This ensures back navigation to the initial page restores scroll correctly.
-  window.history.replaceState({ timber: true, scrollY: 0 }, '');
+  // Initialize scroll state for the initial entry.
+  // When Navigation API is available, use per-entry state.
+  // Otherwise fall back to history.state.
+  // Note: navApiController is assigned inside initRouter() which runs
+  // synchronously before this point via runPreHydration().
+  const navApi = navApiController as NavigationApiController | null;
+  if (navApi) {
+    navApi.saveScrollPosition(0);
+  } else {
+    window.history.replaceState({ timber: true, scrollY: 0 }, '');
+  }
 
   // Populate the segment cache from server-embedded segment metadata.
   // This enables state tree diffing from the very first client navigation.
@@ -653,27 +713,40 @@ function bootstrap(runtimeConfig: typeof config): void {
   }
 
   // Register popstate handler for back/forward navigation.
+  // When Navigation API is active, the navigate event covers traversals —
+  // popstate is a no-op. When unavailable, popstate handles back/forward.
+  //
   // Use pathname+search (not full href) to match the URL format used by
   // navigate() — Link hrefs are relative paths like "/scroll-test/page-a".
   // Read scrollY from history.state — the browser maintains per-entry state
   // so duplicate URLs in history each have their own scroll position.
   window.addEventListener('popstate', () => {
+    // Navigation API handles traversals via the navigate event.
+    if (navApiController) return;
+
     const state = window.history.state;
     const scrollY = state && typeof state.scrollY === 'number' ? state.scrollY : 0;
     void router.handlePopState(window.location.pathname + window.location.search, scrollY);
   });
 
-  // Keep history.state.scrollY up to date as the user scrolls.
+  // Keep scroll position up to date as the user scrolls.
   // This ensures that when the user presses back/forward, the departing
   // page's scroll position is already saved in its history entry.
-  // Debounced to avoid excessive replaceState calls during smooth scrolling.
+  // When Navigation API is available, uses per-entry state via
+  // navigation.updateCurrentEntry(). Otherwise falls back to history.state.
+  // Debounced to avoid excessive state updates during smooth scrolling.
   let scrollTimer: ReturnType<typeof setTimeout>;
   function saveScrollPosition(): void {
     clearTimeout(scrollTimer);
     scrollTimer = setTimeout(() => {
-      const state = window.history.state;
-      if (state && typeof state === 'object') {
-        window.history.replaceState({ ...state, scrollY: getScrollY() }, '');
+      const y = getScrollY();
+      if (navApiController) {
+        navApiController.saveScrollPosition(y);
+      } else {
+        const state = window.history.state;
+        if (state && typeof state === 'object') {
+          window.history.replaceState({ ...state, scrollY: y }, '');
+        }
       }
     }, 100);
   }

package/src/client/history.ts

@@ -23,20 +23,42 @@ export interface HistoryEntry {
  * On forward navigation, the new page's payload is pushed onto the stack.
  * On popstate, the cached payload is replayed instantly.
  *
- * Scroll positions are stored in history.state (browser History API),
- * not in this stack — see design/19-client-navigation.md §Scroll Restoration.
+ * Supports two keying modes:
+ * - **URL-keyed** (default): entries keyed by pathname + search.
+ *   Used with the History API fallback.
+ * - **Entry-key + URL**: when the Navigation API is available,
+ *   entries can also be stored by Navigation entry key for
+ *   disambiguation of duplicate URLs in the history stack.
+ *   Falls back to URL lookup when entry key is not found.
+ *
+ * Scroll positions are stored in history.state or Navigation API entry
+ * state, not in this stack — see design/19-client-navigation.md §Scroll Restoration.
  *
  * Entries persist for the session duration (no expiry) and are cleared
  * when the tab is closed — matching browser back-button behavior.
  */
 export class HistoryStack {
   private entries = new Map<string, HistoryEntry>();
+  /** Entries keyed by Navigation API entry key for duplicate URL disambiguation. */
+  private entryKeyMap = new Map<string, HistoryEntry>();
 
-  push(url: string, entry: HistoryEntry): void {
+  push(url: string, entry: HistoryEntry, entryKey?: string): void {
     this.entries.set(url, entry);
+    if (entryKey) {
+      this.entryKeyMap.set(entryKey, entry);
+    }
   }
 
-  get(url: string): HistoryEntry | undefined {
+  /**
+   * Get an entry. When an entry key is provided (Navigation API),
+   * tries the entry-key map first for accurate disambiguation of
+   * duplicate URLs, then falls back to URL lookup.
+   */
+  get(url: string, entryKey?: string): HistoryEntry | undefined {
+    if (entryKey) {
+      const byKey = this.entryKeyMap.get(entryKey);
+      if (byKey) return byKey;
+    }
     return this.entries.get(url);
   }
 

package/src/client/link-pending-store.ts

@@ -14,8 +14,8 @@
  * 1. Link click handler: setLinkForCurrentNavigation(instance) →
  *    resets previous link (urgent), sets new link pending (urgent),
  *    stores setter + increments navId
- * 2. TransitionRoot startTransition: captures navId, does async work
- * 3. TransitionRoot commit: resetLinkPending(capturedNavId) →
+ * 2. NavigationRoot startTransition: captures navId, does async work
+ * 3. NavigationRoot commit: resetLinkPending(capturedNavId) →
  *    calls setter(IDLE) inside the transition (batched, atomic with tree)
  *    Only clears if navId matches (prevents stale T1 from clearing T2's link)
  *
@@ -96,7 +96,7 @@ export function getCurrentNavId(): number {
 
 /**
  * Reset the current link's pending state to IDLE, but only if the navId
- * matches. Called inside TransitionRoot's startTransition after the async
+ * matches. Called inside NavigationRoot's startTransition after the async
  * work completes — the setter call is a transition update, so it commits
  * atomically with the new tree.
  *

package/src/client/link.tsx

@@ -39,6 +39,8 @@ import {
   PENDING_LINK_STATUS,
   type LinkPendingInstance,
 } from './link-pending-store.js';
+import { setNavLinkMetadata } from './nav-link-store.js';
+import { hasNavigationApi } from './navigation-api.js';
 
 // ─── Current Search Params ────────────────────────────────────────
 
@@ -407,7 +409,7 @@ export function Link({
   // setter is invoked during navigation — zero other links re-render.
   //
   // Eager show: click handler calls setLinkStatus(PENDING) directly (urgent).
-  // Atomic clear: TransitionRoot calls resetLinkPending(navId) inside
+  // Atomic clear: NavigationRoot calls resetLinkPending(navId) inside
   // startTransition — batched with the new tree commit.
   //
   // See design/19-client-navigation.md §"Per-Link Pending State"
@@ -474,24 +476,44 @@ export function Link({
         const router = getRouterOrNull();
         if (!router) return; // SSR or pre-hydration — fall through to browser nav
 
-        event.preventDefault();
         const shouldScroll = scroll !== false;
 
-        // Re-merge preserved search params at click time to pick up any
-        // URL changes since render (e.g. from other navigations or pushState).
-        const navHref = preserveSearchParams
-          ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
-          : resolvedHref;
-
         // Eagerly show pending state on this link (urgent update, immediate).
         // Only this Link re-renders — all other Links are unaffected.
         setLinkStatus(PENDING_LINK_STATUS);
 
-        // Register this link in the pending store so TransitionRoot can
+        // Register this link in the pending store so NavigationRoot can
         // reset it to IDLE inside startTransition (atomic with new tree).
         // Also resets any previous pending link to IDLE.
         setLinkForCurrentNavigation(linkInstanceRef.current);
 
+        // When Navigation API is active, let the <a> click propagate
+        // naturally — do NOT call preventDefault(). The navigate event
+        // handler intercepts it and runs the RSC pipeline. This is a
+        // user-initiated navigation, so Chrome shows the native loading
+        // indicator (tab spinner). Metadata (scroll, link instance) is
+        // passed via nav-link-store so the handler can configure the nav.
+        //
+        // Without Navigation API (fallback), preventDefault and drive
+        // navigation through the router as before.
+        if (hasNavigationApi()) {
+          setNavLinkMetadata({
+            scroll: shouldScroll,
+            linkInstance: linkInstanceRef.current,
+          });
+          // Don't preventDefault — let the <a> click fire the navigate event
+          return;
+        }
+
+        // History API fallback — prevent default and navigate via router
+        event.preventDefault();
+
+        // Re-merge preserved search params at click time to pick up any
+        // URL changes since render (e.g. from other navigations or pushState).
+        const navHref = preserveSearchParams
+          ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+          : resolvedHref;
+
         void router.navigate(navHref, { scroll: shouldScroll });
       }
     : userOnClick; // External links — just pass through user's onClick

package/src/client/nav-link-store.ts

@@ -0,0 +1,47 @@
+/**
+ * Navigation Link Store — passes per-link metadata from Link's onClick
+ * to the Navigation API's navigate event handler.
+ *
+ * When the Navigation API is active, Link does NOT call event.preventDefault()
+ * or router.navigate(). Instead it stores metadata (scroll option, link
+ * pending instance) here, and lets the <a> click propagate naturally.
+ * The navigate event handler reads this metadata to configure the RSC
+ * navigation with the correct options.
+ *
+ * This store is consumed once per navigation — after reading, the metadata
+ * is cleared. If no metadata is present (e.g., a plain <a> tag without
+ * our Link component), the navigate handler uses default options.
+ *
+ * See design/19-client-navigation.md §"Navigation API Integration"
+ */
+
+import type { LinkPendingInstance } from './link-pending-store.js';
+
+export interface NavLinkMetadata {
+  /** Whether to scroll to top after navigation. Default: true. */
+  scroll: boolean;
+  /** The Link's pending state instance for per-link status tracking. */
+  linkInstance: LinkPendingInstance | null;
+}
+
+let pendingMetadata: NavLinkMetadata | null = null;
+
+/**
+ * Store metadata from Link's onClick for the next navigate event.
+ * Called synchronously in the click handler — the navigate event
+ * fires synchronously after onClick returns.
+ */
+export function setNavLinkMetadata(metadata: NavLinkMetadata): void {
+  pendingMetadata = metadata;
+}
+
+/**
+ * Consume the stored metadata. Returns null if no Link onClick
+ * preceded this navigation (e.g., plain <a> tag, programmatic nav).
+ * Clears the store after reading.
+ */
+export function consumeNavLinkMetadata(): NavLinkMetadata | null {
+  const metadata = pendingMetadata;
+  pendingMetadata = null;
+  return metadata;
+}

package/src/client/navigation-api-types.ts

@@ -0,0 +1,112 @@
+/**
+ * Ambient type declarations for the Navigation API.
+ *
+ * The Navigation API is not yet in TypeScript's standard lib. These types
+ * are used internally via type assertions — we never import Navigation API
+ * types unconditionally. Progressive enhancement only: the API is feature-
+ * detected at runtime.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API
+ */
+
+// ─── Navigation Entry ────────────────────────────────────────────
+
+export interface NavigationHistoryEntry {
+  readonly key: string;
+  readonly id: string;
+  readonly url: string | null;
+  readonly index: number;
+  readonly sameDocument: boolean;
+  getState(): unknown;
+  addEventListener(type: string, listener: EventListener): void;
+  removeEventListener(type: string, listener: EventListener): void;
+}
+
+// ─── Navigation Destination ──────────────────────────────────────
+
+export interface NavigationDestination {
+  readonly url: string;
+  readonly key: string | null;
+  readonly id: string | null;
+  readonly index: number;
+  readonly sameDocument: boolean;
+  getState(): unknown;
+}
+
+// ─── Navigate Event ──────────────────────────────────────────────
+
+export interface NavigateEvent extends Event {
+  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
+  readonly destination: NavigationDestination;
+  readonly canIntercept: boolean;
+  readonly userInitiated: boolean;
+  readonly hashChange: boolean;
+  readonly signal: AbortSignal;
+  readonly formData: FormData | null;
+  readonly downloadRequest: string | null;
+  readonly info: unknown;
+  intercept(options?: NavigateInterceptOptions): void;
+  scroll(): void;
+}
+
+export interface NavigateInterceptOptions {
+  handler?: () => Promise<void>;
+  focusReset?: 'after-transition' | 'manual';
+  scroll?: 'after-transition' | 'manual';
+}
+
+// ─── Navigation Transition ───────────────────────────────────────
+
+export interface NavigationTransition {
+  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
+  readonly from: NavigationHistoryEntry;
+  readonly finished: Promise<void>;
+}
+
+// ─── Navigation Result ───────────────────────────────────────────
+
+export interface NavigationResult {
+  committed: Promise<NavigationHistoryEntry>;
+  finished: Promise<NavigationHistoryEntry>;
+}
+
+// ─── Navigation Interface ────────────────────────────────────────
+
+export interface NavigationApi {
+  readonly currentEntry: NavigationHistoryEntry | null;
+  readonly transition: NavigationTransition | null;
+  readonly canGoBack: boolean;
+  readonly canGoForward: boolean;
+  entries(): NavigationHistoryEntry[];
+  navigate(url: string, options?: NavigationNavigateOptions): NavigationResult;
+  reload(options?: NavigationReloadOptions): NavigationResult;
+  traverseTo(key: string, options?: NavigationOptions): NavigationResult;
+  back(options?: NavigationOptions): NavigationResult;
+  forward(options?: NavigationOptions): NavigationResult;
+  updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
+  addEventListener(type: 'navigate', listener: (event: NavigateEvent) => void): void;
+  addEventListener(type: 'navigatesuccess', listener: (event: Event) => void): void;
+  addEventListener(type: 'navigateerror', listener: (event: Event) => void): void;
+  addEventListener(type: 'currententrychange', listener: (event: Event) => void): void;
+  addEventListener(type: string, listener: EventListener): void;
+  removeEventListener(type: string, listener: EventListener): void;
+}
+
+export interface NavigationNavigateOptions {
+  state?: unknown;
+  history?: 'auto' | 'push' | 'replace';
+  info?: unknown;
+}
+
+export interface NavigationReloadOptions {
+  state?: unknown;
+  info?: unknown;
+}
+
+export interface NavigationOptions {
+  info?: unknown;
+}
+
+export interface NavigationUpdateCurrentEntryOptions {
+  state: unknown;
+}