@timber-js/app 0.2.0-alpha.66 → 0.2.0-alpha.68

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 ────────────────────────────────────────
 
@@ -474,15 +476,8 @@ 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);
@@ -492,6 +487,33 @@ export function Link({
         // 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;
+}

package/src/client/navigation-api.ts

@@ -0,0 +1,305 @@
+/**
+ * Navigation API integration — progressive enhancement for client navigation.
+ *
+ * When the Navigation API (`window.navigation`) is available, this module
+ * provides an intercept-based navigation model that replaces the separate
+ * popstate + click handler approach with a single navigate event listener.
+ *
+ * Key benefits:
+ * - Intercepts ALL navigations (link clicks, form submissions, back/forward)
+ * - Built-in AbortSignal per navigation (auto-aborts in-flight fetches)
+ * - Per-entry state via NavigationHistoryEntry.getState()
+ * - navigation.transition for progress tracking
+ *
+ * When unavailable, all functions are no-ops and the History API fallback
+ * in browser-entry.ts handles navigation.
+ *
+ * See design/19-client-navigation.md
+ */
+
+import type { NavigationApi, NavigateEvent } from './navigation-api-types.js';
+import { consumeNavLinkMetadata } from './nav-link-store.js';
+
+// ─── Feature Detection ───────────────────────────────────────────
+
+/**
+ * Returns true if the Navigation API is available in the current environment.
+ * Feature-detected at runtime — no polyfill.
+ */
+export function hasNavigationApi(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    'navigation' in window &&
+    (window as unknown as { navigation: unknown }).navigation != null
+  );
+}
+
+/**
+ * Get the Navigation API instance. Returns null if unavailable.
+ * Uses type assertion — we never import Navigation API types unconditionally.
+ */
+export function getNavigationApi(): NavigationApi | null {
+  if (!hasNavigationApi()) return null;
+  return (window as unknown as { navigation: NavigationApi }).navigation;
+}
+
+// ─── Navigation API Controller ───────────────────────────────────
+
+/**
+ * Callbacks for the Navigation API event handler.
+ *
+ * When the Navigation API intercepts a navigation, it delegates to these
+ * callbacks which run the RSC fetch + render pipeline.
+ */
+export interface NavigationApiCallbacks {
+  /**
+   * Handle a push/replace navigation intercepted by the Navigation API.
+   * This covers both Link <a> clicks (user-initiated, with metadata from
+   * nav-link-store) and external navigations (plain <a> tags, programmatic).
+   * The Navigation API handles the URL update via event.intercept().
+   */
+  onExternalNavigate: (
+    url: string,
+    options: { replace: boolean; signal: AbortSignal; scroll?: boolean }
+  ) => Promise<void>;
+
+  /**
+   * Handle a traversal (back/forward button). The Navigation API intercepts
+   * the traversal and delegates to us for RSC replay/fetch.
+   */
+  onTraverse: (url: string, scrollY: number, signal: AbortSignal) => Promise<void>;
+}
+
+/**
+ * Controller returned by setupNavigationApi. Provides methods to
+ * coordinate between the router and the navigate event listener.
+ */
+export interface NavigationApiController {
+  /**
+   * Set the router-navigating flag. When `true`, the next navigate event
+   * (from pushState/replaceState) is recognized as router-initiated. The
+   * handler still intercepts it — but ties the browser's native loading
+   * state to a deferred promise instead of running the RSC pipeline again.
+   *
+   * This means `navigation.transition` is active for the full duration of
+   * every router-initiated navigation, giving the browser a native loading
+   * indicator (tab spinner, address bar) aligned with the TopLoader.
+   *
+   * Must be called synchronously around pushState/replaceState:
+   *   controller.setRouterNavigating(true);
+   *   history.pushState(...);        // navigate event fires, intercepted
+   *   controller.setRouterNavigating(false);  // flag off, deferred stays open
+   */
+  setRouterNavigating: (value: boolean) => void;
+
+  /**
+   * Resolve the deferred promise created by setRouterNavigating(true),
+   * clearing the browser's native loading state. Call this when the
+   * navigation fully completes — aligned with when the TopLoader's
+   * pendingUrl clears (same finally block in router.navigate).
+   */
+  completeRouterNavigation: () => void;
+
+  /**
+   * Initiate a navigation via the Navigation API (`navigation.navigate()`).
+   * Unlike `history.pushState()`, this fires the navigate event BEFORE
+   * committing the URL — allowing Chrome to show its native loading
+   * indicator while the intercept handler runs.
+   *
+   * Must be called with setRouterNavigating(true) active so the handler
+   * recognizes it as router-initiated and uses the deferred promise.
+   */
+  navigate: (url: string, replace: boolean) => void;
+
+  /**
+   * Save scroll position into the current navigation entry's state.
+   * Uses navigation.updateCurrentEntry() for per-entry scroll storage.
+   */
+  saveScrollPosition: (scrollY: number) => void;
+
+  /**
+   * Check if the Navigation API has an active transition.
+   * Returns the transition object if available, null otherwise.
+   */
+  hasActiveTransition: () => boolean;
+
+  /** Remove the navigate event listener. */
+  cleanup: () => void;
+}
+
+/**
+ * Set up the Navigation API navigate event listener.
+ *
+ * Intercepts same-origin navigations and delegates to the provided callbacks.
+ * Router-initiated navigations (pushState from router.navigate) are detected
+ * via a synchronous flag and NOT intercepted — the router already handles them.
+ *
+ * Returns a controller for coordinating with the router.
+ */
+export function setupNavigationApi(callbacks: NavigationApiCallbacks): NavigationApiController {
+  const nav = getNavigationApi()!;
+
+  let routerNavigating = false;
+
+  // Deferred promise for router-initiated navigations. Created when
+  // setRouterNavigating(true) is called, resolved by completeRouterNavigation().
+  // The navigate event handler intercepts with this promise so the browser's
+  // native loading state (tab spinner) stays active until the navigation
+  // completes — aligned with TopLoader's pendingUrl lifecycle.
+  let routerNavDeferred: { promise: Promise<void>; resolve: () => void } | null = null;
+
+  function handleNavigate(event: NavigateEvent): void {
+    // Skip non-interceptable navigations (cross-origin, etc.)
+    if (!event.canIntercept) return;
+
+    // Skip download requests
+    if (event.downloadRequest) return;
+
+    // Skip hash-only changes — let the browser handle scroll-to-anchor
+    if (event.hashChange) return;
+
+    // Shallow URL updates (e.g., nuqs search param changes). The navigation
+    // only changes the URL — no server round trip needed. Intercept with a
+    // no-op handler so the Navigation API commits the URL change without
+    // triggering a full page navigation (which is the default if we don't
+    // intercept). The info property is the Navigation API's built-in
+    // per-navigation metadata — no side-channel flags needed.
+    const info = event.info as { shallow?: boolean } | null | undefined;
+    if (info?.shallow) {
+      event.intercept({
+        handler: () => Promise.resolve(),
+        focusReset: 'manual',
+        scroll: 'manual',
+      });
+      return;
+    }
+
+    // Skip form submissions with a body (POST/PUT/etc.). These need the
+    // browser's native form handling to send the request body to the server.
+    // Intercepting would convert them into GET RSC navigations, dropping
+    // the form data. Server actions use fetch() directly (not form navigation),
+    // so they are unaffected by this check.
+    if (event.formData) return;
+
+    // Skip cross-origin (defense-in-depth — canIntercept covers this)
+    const destUrl = new URL(event.destination.url);
+    if (destUrl.origin !== location.origin) return;
+
+    // Router-initiated navigation (Link click → router.navigate → pushState).
+    // The router is already running the RSC pipeline — don't run it again.
+    // Instead, intercept with the deferred promise so the browser's native
+    // loading state tracks the navigation's full lifecycle. This aligns the
+    // tab spinner / address bar indicator with the TopLoader.
+    if (routerNavigating && routerNavDeferred) {
+      event.intercept({
+        scroll: 'manual',
+        focusReset: 'manual',
+        handler: () => routerNavDeferred!.promise,
+      });
+      return;
+    }
+
+    // Skip reload navigations — let the browser handle full page reload
+    if (event.navigationType === 'reload') return;
+
+    const url = destUrl.pathname + destUrl.search;
+
+    if (event.navigationType === 'traverse') {
+      // Back/forward button — intercept and delegate to router.
+      // Read scroll position from the destination entry's state.
+      const entryState = event.destination.getState() as
+        | { scrollY?: number; timber?: boolean }
+        | null
+        | undefined;
+      const scrollY = entryState && typeof entryState.scrollY === 'number' ? entryState.scrollY : 0;
+
+      event.intercept({
+        // Manual scroll — we handle scroll restoration ourselves
+        // via afterPaint (same as the History API path).
+        scroll: 'manual',
+        focusReset: 'manual',
+        async handler() {
+          await callbacks.onTraverse(url, scrollY, event.signal);
+        },
+      });
+    } else if (event.navigationType === 'push' || event.navigationType === 'replace') {
+      // Push/replace — either a Link <a> click (with metadata in
+      // nav-link-store) or an external navigation (plain <a>, programmatic).
+      // Consume link metadata if present — tells us scroll preference
+      // and which Link component to track pending state for.
+      const linkMeta = consumeNavLinkMetadata();
+
+      event.intercept({
+        scroll: 'manual',
+        focusReset: 'manual',
+        async handler() {
+          await callbacks.onExternalNavigate(url, {
+            replace: event.navigationType === 'replace',
+            signal: event.signal,
+            scroll: linkMeta?.scroll,
+          });
+        },
+      });
+    }
+  }
+
+  nav.addEventListener('navigate', handleNavigate as EventListener);
+
+  return {
+    setRouterNavigating(value: boolean): void {
+      routerNavigating = value;
+      if (value) {
+        // Create a new deferred promise. The navigate event handler will
+        // intercept and tie the browser's loading state to this promise.
+        let resolve!: () => void;
+        const promise = new Promise<void>((r) => {
+          resolve = r;
+        });
+        routerNavDeferred = { promise, resolve };
+      } else {
+        // Flag off — but DON'T resolve the deferred here. The navigation
+        // is still in flight (RSC fetch + render). completeRouterNavigation()
+        // resolves it when the navigation fully completes.
+        routerNavigating = false;
+      }
+    },
+
+    completeRouterNavigation(): void {
+      if (routerNavDeferred) {
+        routerNavDeferred.resolve();
+        routerNavDeferred = null;
+      }
+    },
+
+    navigate(url: string, replace: boolean): void {
+      // Use navigation.navigate() instead of history.pushState().
+      // This fires the navigate event BEFORE committing the URL,
+      // which lets Chrome show its native loading indicator while
+      // the intercept handler (deferred promise) is pending.
+      // history.pushState() commits the URL synchronously, so Chrome
+      // sees the navigation as already complete and skips the indicator.
+      nav.navigate(url, {
+        history: replace ? 'replace' : 'push',
+      });
+    },
+
+    saveScrollPosition(scrollY: number): void {
+      try {
+        const currentState = (nav.currentEntry?.getState() ?? {}) as Record<string, unknown>;
+        nav.updateCurrentEntry({
+          state: { ...currentState, timber: true, scrollY },
+        });
+      } catch {
+        // Ignore errors — updateCurrentEntry may throw if entry is disposed
+      }
+    },
+
+    hasActiveTransition(): boolean {
+      return nav.transition != null;
+    },
+
+    cleanup(): void {
+      nav.removeEventListener('navigate', handleNavigate as EventListener);
+    },
+  };
+}

package/src/client/navigation-context.ts

@@ -218,3 +218,23 @@ export function PendingNavigationProvider({
   }
   return createElement(ctx.Provider, { value }, children);
 }
+
+// ---------------------------------------------------------------------------
+// Navigation API transition state (optional progressive enhancement)
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if the browser's Navigation API has an active transition.
+ *
+ * When the Navigation API is available and a navigation has been intercepted
+ * via event.intercept(), `navigation.transition` is non-null until the
+ * handler resolves. This provides browser-native progress tracking that
+ * can be used alongside the existing pendingUrl mechanism.
+ *
+ * Returns false when Navigation API is unavailable or no transition is active.
+ */
+export function hasNativeNavigationTransition(): boolean {
+  if (typeof window === 'undefined') return false;
+  const nav = (window as unknown as { navigation?: { transition?: unknown } }).navigation;
+  return nav?.transition != null;
+}

package/src/client/nuqs-adapter.tsx

@@ -20,6 +20,7 @@ import {
   type unstable_AdapterOptions as AdapterOptions,
 } from 'nuqs/adapters/custom';
 import { getRouter } from './router-ref.js';
+import { getNavigationApi } from './navigation-api.js';
 
 // ─── Adapter Hook ─────────────────────────────────────────────────
 
@@ -59,9 +60,21 @@ function useTimberAdapter(_watchKeys: string[]): AdapterInterface {
 
       if (options.shallow) {
         // Shallow: update URL only, no server roundtrip.
-        const method =
-          options.history === 'push' ? window.history.pushState : window.history.replaceState;
-        method.call(window.history, window.history.state, '', url.toString());
+        // When Navigation API is available, use navigation.navigate() with
+        // info: { shallow: true } so the navigate event handler knows to
+        // skip interception. Without this, the navigate event fired by
+        // history.pushState/replaceState would trigger a full RSC fetch.
+        const nav = getNavigationApi();
+        if (nav) {
+          nav.navigate(url.toString(), {
+            history: options.history === 'push' ? 'push' : 'replace',
+            info: { shallow: true },
+          });
+        } else {
+          const method =
+            options.history === 'push' ? window.history.pushState : window.history.replaceState;
+          method.call(window.history, window.history.state, '', url.toString());
+        }
 
         // Update local state to reflect the new URL
         setSearchParams(new URLSearchParams(url.search));