@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/client/navigation-api.ts

@@ -0,0 +1,345 @@
+/**
+ * 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 { isHardNavigating } from './navigation-root.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.navigation != null;
+}
+
+/**
+ * Get the Navigation API instance. Returns null if unavailable.
+ */
+export function getNavigationApi(): Navigation | null {
+  if (!hasNavigationApi()) return null;
+  return window.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) 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; departingUrl?: string }
+  ) => 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>;
+
+  /**
+   * Called when a shallow URL update is intercepted (e.g., nuqs with
+   * shallow: true, or replaceUrl). The URL has already been committed —
+   * this callback syncs NavigationContext.search so useSearchParams()
+   * reflects the new value without a full router navigation.
+   */
+  onShallowNavigate?: (url: string) => 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 — the same finally block in router.navigate
+   * that clears the router's pending store.
+   */
+  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 — the same lifecycle the TopLoader is driven by.
+  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;
+
+    // Hard navigation guard: when the router has triggered a full page
+    // load (500 error, version skew), skip interception entirely so the
+    // browser performs the MPA navigation. Without this guard, setting
+    // window.location.href fires a navigate event that we'd intercept,
+    // running the RSC pipeline again → 500 → window.location.href →
+    // navigate event → infinite loop.
+    // See design/19-client-navigation.md §"Hard Navigation Guard"
+    if (isHardNavigating()) return;
+
+    // Skip download requests
+    if (event.downloadRequest) return;
+
+    // Skip blob: URLs — these are almost always downloads or object-URL
+    // navigations initiated by the host page (e.g., generated files, PDFs).
+    // The RSC pipeline cannot handle them, and intercepting would break
+    // the download/open behavior the host page expects.
+    if (event.destination.url.startsWith('blob:')) 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',
+      });
+      callbacks.onShallowNavigate?.(event.destination.url);
+      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 — a Link <a> click or an external navigation
+      // (plain <a> tag, programmatic).
+
+      // Save the departing page's scroll position BEFORE event.intercept()
+      // commits the URL change. Once intercept() is called, currentEntry
+      // switches to the new (destination) entry — any updateCurrentEntry()
+      // call after that would save to the wrong entry.
+      // See: router.navigate() also calls saveNavigationEntryScroll(), but
+      // for Navigation API <a> click navigations (where Link does NOT call
+      // router.navigate directly), the router's save runs inside the
+      // intercept handler — too late, currentEntry has already switched.
+      try {
+        const currentState = (nav.currentEntry?.getState() ?? {}) as Record<string, unknown>;
+        nav.updateCurrentEntry({
+          state: { ...currentState, timber: true, scrollY: window.scrollY },
+        });
+      } catch {
+        // Ignore — entry may be disposed
+      }
+
+      // Capture the departing URL BEFORE event.intercept() commits the
+      // destination. Once intercept() is called, currentEntry switches and
+      // getCurrentUrl() returns the destination (TIM-1232).
+      const departingUrl = nav.currentEntry?.url
+        ? new URL(nav.currentEntry.url).pathname + new URL(nav.currentEntry.url).search
+        : undefined;
+
+      event.intercept({
+        scroll: 'manual',
+        focusReset: 'manual',
+        async handler() {
+          await callbacks.onExternalNavigate(url + destUrl.hash, {
+            replace: event.navigationType === 'replace',
+            signal: event.signal,
+            scroll: undefined,
+            departingUrl,
+          });
+        },
+      });
+    }
+  }
+
+  nav.addEventListener('navigate', handleNavigate);
+
+  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);
+    },
+  };
+}

package/src/client/navigation-commit.ts

@@ -0,0 +1,197 @@
+/**
+ * What it means for a page to be "current" on the client.
+ *
+ * One module owns every write that makes a navigation's destination the
+ * current page, and the read that describes the current page back to the
+ * server. Keeping them together is the point: `X-Timber-State-Tree` is
+ * derived from the segment cache, so the thing that publishes and the thing
+ * that reports have to agree about when a page becomes current.
+ *
+ * See design/19-client-navigation.md §"State Update Invariants".
+ */
+
+import { buildSegmentTree, type SegmentCache } from './segment-cache.js';
+import type { HistoryStack } from './history.js';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.js';
+import type { ParamsSource } from '../shared/payload-root.js';
+import { setNavigationState, type NavigationState } from './navigation-context.js';
+
+/** Everything a commit needs to describe the page it makes current. */
+export interface NavigationCommitInput {
+  payload: unknown;
+  /** The params that payload published — replayed with it on popstate. */
+  params: ParamsSource;
+  /**
+   * The rendered chain's metadata, or null/undefined when this commit
+   * carries none at all — a revalidation payload, or a history entry
+   * stored before the channel existed.
+   *
+   * An empty *array* is a different statement from an absent one: the
+   * server rendered a route with no layout-bearing segments (a layoutless
+   * app — the missing-root-layout check is a warning, not an error), so
+   * the correct tree is the empty one. Collapsing the two left the
+   * departing route's tree in place, which `treePaths` then reported as
+   * mounted — enough to select an intercepting rewrite whose slot is not
+   * on screen (TIM-1282).
+   */
+  segmentInfo?: SegmentInfo[] | null;
+  /** When true, clear the segment cache if segmentInfo is absent
+   *  (popstate replay for entries without layout metadata). */
+  clearSegmentCacheOnEmpty?: boolean;
+  /**
+   * HTTP status of the response this navigation rendered, when it came from a
+   * fetch. Omitted by replays, which re-publish a tree already judged.
+   *
+   * An error response rendered a status page, and a status page replaces a
+   * subtree: the deny page lands at the segment owning the matched file and
+   * nothing below it mounts. `segmentInfo` nonetheless describes the whole
+   * chain the payload was built against — it must, because the merge point is
+   * chosen out of it — so the cache has to be told not to learn from this one.
+   *
+   * Enforced here rather than at the call sites because there are three of
+   * them (`performNavigationFetch`, `refresh()`, and uncached traversal, the
+   * last two through `fetchCommitAndRender`) and only one had the check.
+   * See TIM-1356.
+   */
+  status?: number;
+}
+
+/**
+ * A navigation's destination, split into what a render needs and what a
+ * commit publishes.
+ */
+export interface PreparedNavigation {
+  /** The state the incoming tree renders with. Pure — safe before winning. */
+  navState: NavigationState;
+  /** Publishes the destination. Call only once the render has won. */
+  commit: () => void;
+}
+
+export interface NavigationCommitter {
+  prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation;
+  currentStateTree(): StateTree | undefined;
+  updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void;
+}
+
+/**
+ * Derive the navigation state (pathname + search) a URL renders with.
+ *
+ * Pure: publishing it — the module-level fallback for tests and SSR, and the
+ * globalThis bridge — is `prepareNavigation`'s commit, which runs only once
+ * the render is known to have won (TIM-1301). Callers pass the returned value
+ * explicitly to renderRoot/wrapPayload, so a render never depends on the
+ * publish having happened first.
+ */
+export function deriveNavigationState(url: string): NavigationState {
+  // Params are not part of it. They travel with the payload and are published
+  // by the one client-owned `ParamsProvider` as the new tree renders, which is
+  // also what clears the previous route's — a route with no params of its own
+  // still publishes an empty record (TIM-1294/TIM-1297, and the clearing
+  // requirement from TIM-1285).
+  const parsed = new URL(url, 'http://localhost');
+  return { pathname: parsed.pathname || '/', search: parsed.search };
+}
+
+export function createNavigationCommitter(deps: {
+  segmentCache: SegmentCache;
+  historyStack: HistoryStack;
+  /** Read at call time — the router's `clientSegmentCache` opt-in. */
+  clientSegmentCache: () => boolean | undefined;
+}): NavigationCommitter {
+  const { segmentCache, historyStack } = deps;
+
+  /**
+   * Update the segment cache from server-provided segment metadata.
+   *
+   * Runs whether or not `clientSegmentCache` is enabled: the tree is also
+   * where the mounted tree paths come from, and those cross on every
+   * navigation. What the flag gates is which parts get serialized — see
+   * `currentStateTree`.
+   */
+  function updateSegmentCache(segmentInfo: SegmentInfo[] | null | undefined): void {
+    if (!segmentInfo || segmentInfo.length === 0) return;
+    const tree = buildSegmentTree(segmentInfo);
+    if (tree) {
+      segmentCache.set('/', tree);
+    }
+  }
+
+  return {
+    updateSegmentCache,
+
+    /**
+     * The X-Timber-State-Tree to send with the next RSC request.
+     *
+     * Two different things travel on one header. `segments`/`slots` are the
+     * caching opt-in and are omitted unless `clientSegmentCache` is on.
+     * `treePaths` is how the server learns which route is actually mounted,
+     * which stops being derivable from the address bar as soon as a modal is
+     * open — so it crosses regardless (TIM-1282). Undefined when there is
+     * nothing to say, so a no-op header never enters the `_rsc` cache key.
+     *
+     * Reads what the last *committed* navigation published, so a superseded
+     * navigation's destination can never end up describing the mounted tree
+     * (TIM-1301).
+     */
+    currentStateTree(): StateTree | undefined {
+      const tree = segmentCache.serializeStateTree();
+      if (deps.clientSegmentCache()) return tree;
+      return tree.treePaths ? { segments: [], treePaths: tree.treePaths } : undefined;
+    },
+
+    /**
+     * Prepare all navigation-owned state for a new page — without publishing
+     * any of it. Every code path that changes the "current page" must go
+     * through this function, which is what makes "forgot a field" impossible
+     * by construction.
+     *
+     * Returns the destination's `NavigationState`, which is a pure function of
+     * the URL and is what the incoming tree is *rendered* with, plus a
+     * `commit` thunk that performs the writes that make a page current:
+     * 1. Segment cache — update from server-provided segment metadata
+     * 2. Navigation state — pathname/search for usePathname/useSearchParams
+     * 3. History stack — store the payload for instant back/forward replay
+     *
+     * Nothing is written until `commit()` runs, and on a transitioned
+     * navigation it runs only once the transition is known to have won — see
+     * `renderViaTransition` and `NavigationRoot`. A navigation superseded
+     * while its payload was in flight never calls it, so the cache, the
+     * pathname the client reports and the history stack all keep describing
+     * the route still on screen (TIM-1301).
+     *
+     * Callers with state of their own to publish — the address bar, the
+     * client's record of the mounted tree — wrap this thunk rather than
+     * commit beside it, so there stays exactly one moment at which a page
+     * becomes current.
+     */
+    prepareNavigation(url: string, opts: NavigationCommitInput): PreparedNavigation {
+      const navState = deriveNavigationState(url);
+
+      // A tree rendered by an error response is not one to cache — see
+      // `status` on NavigationCommitInput. Normalized here, once, so no fetch
+      // caller can forget it; the history entry records the same thing, or a
+      // traversal back to this URL would replay the metadata this drops.
+      const cacheable = opts.status === undefined || opts.status < 400;
+      const segmentInfo = cacheable ? opts.segmentInfo : [];
+
+      return {
+        navState,
+        commit() {
+          if (segmentInfo && segmentInfo.length > 0) {
+            updateSegmentCache(segmentInfo);
+          } else if (segmentInfo?.length === 0 || opts.clearSegmentCacheOnEmpty) {
+            segmentCache.clear();
+          }
+
+          setNavigationState(navState);
+
+          historyStack.push(url, {
+            payload: opts.payload,
+            params: opts.params,
+            segmentInfo,
+          });
+        },
+      };
+    },
+  };
+}