@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.40

package/src/client/browser-entry.ts

@@ -47,12 +47,24 @@ import {
   NavigationProvider,
   getNavigationState,
   setNavigationState,
+  type NavigationState,
 } from './navigation-context.js';
 import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
 // browser-links.ts removed — Link components own their click/hover handlers directly.
 // See LOCAL-340.
 import { TransitionRoot, transitionRender, navigateTransition } from './transition-root.js';
-import { isStaleClientReference, triggerStaleReload, clearStaleReloadFlag } from './stale-reload.js';
+import {
+  isStaleClientReference,
+  isChunkLoadError,
+  triggerStaleReload,
+  clearStaleReloadFlag,
+} from './stale-reload.js';
+import {
+  setClientDeploymentId,
+  getClientDeploymentId,
+  DEPLOYMENT_ID_HEADER,
+  RELOAD_HEADER,
+} from './rsc-fetch.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -81,14 +93,28 @@ setServerCallback(async (id: string, args: unknown[]) => {
   let hasRedirect = false;
   let headElementsJson: string | null = null;
 
+  // Build action request headers. Include deployment ID for version
+  // skew detection (TIM-446) — the server rejects stale actions gracefully.
+  const actionHeaders: Record<string, string> = {
+    'Accept': 'text/x-component',
+    'x-rsc-action': id,
+  };
+  const actionDeploymentId = getClientDeploymentId();
+  if (actionDeploymentId) {
+    actionHeaders[DEPLOYMENT_ID_HEADER] = actionDeploymentId;
+  }
+
   const response = fetch(window.location.href, {
     method: 'POST',
-    headers: {
-      'Accept': 'text/x-component',
-      'x-rsc-action': id,
-    },
+    headers: actionHeaders,
     body,
   }).then((res) => {
+    // Version skew detection (TIM-446): if the server signals a reload,
+    // trigger a full page load to pick up the new deployment.
+    if (res.headers.get(RELOAD_HEADER) === '1') {
+      window.location.reload();
+      throw new Error('Version skew detected — reloading page');
+    }
     hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
     hasRedirect = res.headers.get('X-Timber-Redirect') != null;
     headElementsJson = res.headers.get('X-Timber-Head');
@@ -155,7 +181,17 @@ setServerCallback(async (id: string, args: unknown[]) => {
  * Hydrates the server-rendered HTML with React, then initializes
  * client-side navigation for SPA transitions.
  */
-/** Read scroll position from window or scroll containers. */
+/**
+ * Read the current scroll position.
+ *
+ * Checks window scroll first, then explicit `data-timber-scroll-restoration`
+ * containers. With segment tree merging, shared layouts are reconciled in
+ * place via `cloneElement` — React preserves their DOM and scroll state
+ * naturally. We don't need to auto-detect overflow containers; only
+ * explicitly marked containers are tracked.
+ *
+ * See design/19-client-navigation.md §"Overflow Scroll Containers".
+ */
 function getScrollY(): number {
   if (window.scrollY || document.documentElement.scrollTop || document.body.scrollTop) {
     return window.scrollY || document.documentElement.scrollTop || document.body.scrollTop;
@@ -163,74 +199,24 @@ function getScrollY(): number {
   for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
     if ((el as HTMLElement).scrollTop > 0) return (el as HTMLElement).scrollTop;
   }
-  // Auto-detect: if window isn't scrolled, check for overflow containers.
-  // Common pattern: layouts use a scrollable div (overflow-y: auto/scroll)
-  // inside a fixed-height parent (h-screen). In this case window.scrollY is
-  // always 0 and the real scroll position lives on the overflow container.
-  const container = findOverflowContainer();
-  if (container && container.scrollTop > 0) return container.scrollTop;
   return 0;
 }
 
-/**
- * Find the primary overflow scroll container in the document.
- *
- * Walks direct children of body and their immediate children looking for
- * an element with overflow-y: auto|scroll that is actually scrollable
- * (scrollHeight > clientHeight). Returns the first match, or null.
- *
- * This heuristic covers the common layout patterns:
- *   <body> → <root-layout> → <div class="overflow-y-auto">
- *   <body> → <root-layout> → <main> → <nested-layout overflow-y-auto>
- *
- * We limit depth to 3 to avoid expensive full-tree traversals while still
- * reaching nested layout scroll containers (e.g., parallel route layouts
- * inside a root layout's <main> element).
- *
- * DIVERGENCE FROM NEXT.JS: Next.js's ScrollAndFocusHandler scrolls only
- * document.documentElement.scrollTop — it does NOT handle overflow containers.
- * Layouts using h-screen + overflow-y-auto have the same scroll bug in Next.js.
- * This heuristic is a deliberate improvement. The tradeoff is fragility: depth-3
- * traversal may miss deeply nested containers or match the wrong element.
- * See design/19-client-navigation.md §"Overflow Scroll Containers".
- */
-function findOverflowContainer(): HTMLElement | null {
-  const candidates: HTMLElement[] = [];
-  // Check body's descendants up to depth 3. Depth 3 covers the common case:
-  //   <body> → <root-layout-div> → <main> → <overflow-container>
-  // React context providers (SegmentProvider, NavigationProvider) don't add
-  // DOM elements, so depth 3 from body reaches nested layout scroll containers.
-  for (const child of document.body.children) {
-    candidates.push(child as HTMLElement);
-    for (const grandchild of child.children) {
-      candidates.push(grandchild as HTMLElement);
-      for (const greatGrandchild of grandchild.children) {
-        candidates.push(greatGrandchild as HTMLElement);
-      }
-    }
-  }
-  for (const el of candidates) {
-    if (!(el instanceof HTMLElement)) continue;
-    const style = getComputedStyle(el);
-    const overflowY = style.overflowY;
-    if (
-      (overflowY === 'auto' || overflowY === 'scroll') &&
-      el.scrollHeight > el.clientHeight
-    ) {
-      return el;
-    }
-  }
-  return null;
-}
-
 function bootstrap(runtimeConfig: typeof config): void {
   const _config = runtimeConfig;
 
-  // Take manual control of scroll restoration. React's render() on the
-  // document root resets scroll during DOM reconciliation, so the browser's
-  // native scroll restoration (scrollRestoration = 'auto') doesn't work —
-  // the browser restores scroll, then React's commit resets it to 0.
-  // We save/restore scroll positions explicitly in the history stack.
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // In dev mode this is null — skew checks are skipped.
+  const deploymentId = (_config as Record<string, unknown>).deploymentId as string | null;
+  if (deploymentId) {
+    setClientDeploymentId(deploymentId);
+  }
+
+  // Take manual control of scroll restoration. Even though segment tree
+  // merging preserves shared layout DOM via cloneElement (so React doesn't
+  // reset scroll on those elements), the root-level reactRoot.render() with
+  // a new element tree can still cause scroll resets on the document during
+  // reconciliation. Manual control ensures consistent behavior.
   window.history.scrollRestoration = 'manual';
 
   // Hydrate the React tree from the RSC payload.
@@ -246,6 +232,12 @@ function bootstrap(runtimeConfig: typeof config): void {
   // For subsequent navigations, it's fetched from the server.
   type FlightSegment = [isBootstrap: 0] | [isData: 1, data: string];
 
+  // __timber_f is initialized in <head> via flightInitScript() (see
+  // flight-scripts.ts). It should always exist by the time this module
+  // runs. Defensive fallback kept for safety.
+  if (!(self as unknown as Record<string, unknown>).__timber_f) {
+    (self as unknown as Record<string, FlightSegment[]>).__timber_f = [];
+  }
   const timberChunks = (self as unknown as Record<string, FlightSegment[]>).__timber_f;
 
   let _reactRoot: Root | null = null;
@@ -347,7 +339,7 @@ function bootstrap(runtimeConfig: typeof config): void {
 
     // ── Initialize navigation state BEFORE hydration ───────────────────
     // Read server-embedded params and set navigation state so that
-    // useParams() and usePathname() return correct values during hydration.
+    // useSegmentParams() and usePathname() return correct values during hydration.
     // This must happen before hydrateRoot so the NavigationProvider
     // wrapping the element has the right values on the initial render.
     const earlyParams = (self as unknown as Record<string, unknown>).__timber_params;
@@ -381,7 +373,10 @@ function bootstrap(runtimeConfig: typeof config): void {
       element as React.ReactNode
     );
     const wrapped = createElement(TimberNuqsAdapter, null, withNav);
-    const rootElement = createElement(TransitionRoot, { initial: wrapped, topLoaderConfig: _config.topLoader });
+    const rootElement = createElement(TransitionRoot, {
+      initial: wrapped,
+      topLoaderConfig: _config.topLoader,
+    });
     _reactRoot = hydrateRoot(document, rootElement, {
       // Suppress recoverable hydration errors from deny/error signals
       // inside Suspense boundaries. The server already handled these
@@ -420,23 +415,20 @@ function bootstrap(runtimeConfig: typeof config): void {
       pushState: (data, unused, url) => window.history.pushState(data, unused, url),
       replaceState: (data, unused, url) => window.history.replaceState(data, unused, url),
       scrollTo: (x, y) => {
+        // Scroll the document viewport.
         window.scrollTo(x, y);
         document.documentElement.scrollTop = y;
         document.body.scrollTop = y;
-        // Also scroll any element explicitly marked as a scroll container.
+        // Scroll any element explicitly marked as a scroll container.
+        // With segment tree merging, shared layouts (sidebars, nav bars)
+        // are reconciled in place via cloneElement — React preserves their
+        // DOM and scroll state naturally. We no longer auto-detect overflow
+        // containers, which previously found the wrong element (e.g.,
+        // scrolling a sidebar instead of the main content area).
+        // Use `data-timber-scroll-restoration` to opt in specific containers.
         for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
           (el as HTMLElement).scrollTop = y;
         }
-        // Auto-detect overflow containers for layouts that scroll inside
-        // a fixed-height wrapper (e.g., h-screen + overflow-y-auto).
-        // In these layouts, window.scrollY is always 0 and the real scroll
-        // lives on the overflow container. Without this, forward navigation
-        // between pages that share a layout with parallel route slots won't
-        // scroll to top — the router's window.scrollTo(0,0) is a no-op.
-        const container = findOverflowContainer();
-        if (container) {
-          container.scrollTop = y;
-        }
       },
       getCurrentUrl: () => window.location.pathname + window.location.search,
       getScrollY,
@@ -471,8 +463,10 @@ function bootstrap(runtimeConfig: typeof config): void {
       // For navigation renders (navigate, refresh, popstate-with-fetch),
       // navigateTransition is used instead — it wraps the entire navigation
       // in a React transition with useOptimistic for the pending URL.
-      renderRoot: (element: unknown) => {
-        const navState = getNavigationState();
+      //
+      // navState is passed explicitly by the router — no temporal coupling
+      // with getNavigationState().
+      renderRoot: (element: unknown, navState: NavigationState) => {
         const withNav = createElement(
           NavigationProvider,
           { value: navState },
@@ -488,13 +482,11 @@ function bootstrap(runtimeConfig: typeof config): void {
       // commits (atomic with the new tree + params).
       //
       // The perform callback receives a wrapPayload function that wraps the
-      // decoded RSC payload with NavigationProvider + NuqsAdapter — this must
-      // happen inside the transition so the NavigationProvider reads the
-      // UPDATED navigation state (set by the router inside perform).
+      // decoded RSC payload with NavigationProvider + NuqsAdapter. navState
+      // is passed explicitly by the router — no getNavigationState() needed.
       navigateTransition: (pendingUrl: string, perform) => {
         return navigateTransition(pendingUrl, async () => {
-          const payload = await perform((rawPayload: unknown) => {
-            const navState = getNavigationState();
+          const payload = await perform((rawPayload: unknown, navState: NavigationState) => {
             const withNav = createElement(
               NavigationProvider,
               { value: navState },
@@ -586,7 +578,6 @@ function bootstrap(runtimeConfig: typeof config): void {
     scrollTimer = setTimeout(() => {
       const state = window.history.state;
       if (state && typeof state === 'object') {
-        // Use getScrollY to capture scroll from overflow containers too.
         window.history.replaceState({ ...state, scrollY: getScrollY() }, '');
       }
     }, 100);
@@ -655,8 +646,21 @@ clearStaleReloadFlag();
 // If the payload references a module ID from a newer deployment, the error
 // surfaces as an unhandled rejection during React's render/hydration cycle.
 // This handler catches those errors and triggers a full page reload.
+//
+// Also catches chunk load failures (dynamic import of missing assets after
+// a deployment) — these surface as "Failed to fetch dynamically imported module"
+// or "Loading chunk <name> failed" errors. See TIM-446.
 window.addEventListener('unhandledrejection', (event) => {
-  if (isStaleClientReference(event.reason)) {
+  if (isStaleClientReference(event.reason) || isChunkLoadError(event.reason)) {
+    event.preventDefault();
+    triggerStaleReload();
+  }
+});
+
+// Also catch synchronous errors from chunk loads (some browsers throw
+// TypeError synchronously instead of via unhandled rejection).
+window.addEventListener('error', (event) => {
+  if (isChunkLoadError(event.error)) {
     event.preventDefault();
     triggerStaleReload();
   }

package/src/client/error-boundary.tsx

@@ -65,7 +65,16 @@ type ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;
 
 export interface TimberErrorBoundaryProps {
   /** The component to render when an error is caught. */
-  fallbackComponent: (...args: unknown[]) => ReactNode;
+  fallbackComponent?: (...args: unknown[]) => ReactNode;
+  /**
+   * Pre-rendered fallback element. Used for MDX status files which are server
+   * components and cannot be passed as function props across the RSC→client
+   * boundary. When set, rendered directly instead of calling fallbackComponent.
+   *
+   * See design/10-error-handling.md §"Status-Code File Variants" — MDX status
+   * files are server components by default (zero client JS).
+   */
+  fallbackElement?: ReactNode;
   /**
    * Status code filter. If set, only catches errors matching this status.
    * 400 = any 4xx, 500 = any 5xx, specific number = exact match.
@@ -162,6 +171,14 @@ export class TimberErrorBoundary extends Component<
       }
     }
 
+    // Pre-rendered fallback element (MDX status files) — render directly.
+    // MDX components are server components that cannot be passed as function
+    // props across the RSC→client boundary. Instead, they are pre-rendered
+    // as elements in the RSC environment and passed here as fallbackElement.
+    if (this.props.fallbackElement != null) {
+      return this.props.fallbackElement;
+    }
+
     // Render the fallback component with the right props shape.
     if (parsed?.type === 'deny') {
       return createElement(this.props.fallbackComponent as never, {

package/src/client/index.ts

@@ -5,6 +5,7 @@ export type { JsonSerializable, RenderErrorDigest } from './types';
 
 // Navigation
 export { Link, interpolateParams, resolveHref, validateLinkHref, buildLinkProps } from './link';
+export { mergePreservedSearchParams } from '#/shared/merge-search-params.js';
 export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams } from './link';
 export type { OnNavigateHandler, OnNavigateEvent } from './link';
 export { createRouter } from './router';
@@ -12,6 +13,7 @@ export type {
   RouterInstance,
   NavigationOptions,
   RouterDeps,
+  RouterPhase,
   RscDecoder,
   RootRenderer,
 } from './router';
@@ -42,7 +44,7 @@ export { useActionState, useFormAction, useFormErrors } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 
 // Params
-export { useParams, setCurrentParams } from './use-params';
+export { useSegmentParams, setCurrentParams } from './use-params';
 
 // Navigation context (framework-internal, used by browser-entry for atomic updates)
 export { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context';
@@ -55,6 +57,13 @@ export { useQueryStates, bindUseQueryStates } from './use-query-states';
 export { useCookie } from './use-cookie';
 export type { ClientCookieOptions, CookieSetter } from './use-cookie';
 
+// Register the client cookie module with defineCookie's lazy reference.
+// This runs at module load time in the client/SSR environment, wiring up
+// the useCookie hook without a top-level import in define-cookie.ts.
+import * as _useCookieMod from './use-cookie.js';
+import { _registerUseCookieModule } from '#/cookies/define-cookie.js';
+_registerUseCookieModule(_useCookieMod);
+
 // SSR data (framework-internal, used by ssr-entry to provide request data to hooks)
 export { setSsrData, clearSsrData, getSsrData } from './ssr-data';
 export type { SsrData } from './ssr-data';

package/src/client/link.tsx

@@ -19,9 +19,27 @@
 // - searchParams and inline query string are mutually exclusive
 
 import type { AnchorHTMLAttributes, ReactNode, MouseEvent as ReactMouseEvent } from 'react';
-import type { SearchParamsDefinition } from '#/search-params/create.js';
+import type { SearchParamsDefinition } from '#/search-params/define.js';
 import { LinkStatusProvider } from './link-status-provider.js';
 import { getRouterOrNull } from './router-ref.js';
+import { getSsrData } from './ssr-data.js';
+import { mergePreservedSearchParams } from '#/shared/merge-search-params.js';
+
+// ─── Current Search Params ────────────────────────────────────────
+
+/**
+ * Read the current URL's search string without requiring a React hook.
+ * On the client, reads window.location.search. During SSR, reads from
+ * the request context (getSsrData). Returns empty string if unavailable.
+ */
+function getCurrentSearch(): string {
+  if (typeof window !== 'undefined') return window.location.search;
+  const data = getSsrData();
+  if (!data) return '';
+  const sp = new URLSearchParams(data.searchParams);
+  const str = sp.toString();
+  return str ? `?${str}` : '';
+}
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -42,6 +60,20 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
    * Set to false for tabbed interfaces where content changes within a fixed layout.
    */
   scroll?: boolean;
+  /**
+   * Preserve search params from the current URL across navigation.
+   *
+   * - `true` — preserve ALL current search params (target params take precedence)
+   * - `string[]` — preserve only the named params (e.g. `['private', 'token']`)
+   *
+   * Useful for route-group gating where a search param (e.g. `?private=access`)
+   * must persist across internal navigations. The target href's own search params
+   * always take precedence over preserved ones.
+   *
+   * During SSR, reads search params from the request context. On the client,
+   * reads from the current URL and updates reactively when the URL changes.
+   */
+  preserveSearchParams?: true | string[];
   /**
    * Called before client-side navigation commits. Call `e.preventDefault()`
    * to cancel the default navigation — the caller is then responsible for
@@ -61,7 +93,7 @@ interface LinkBaseProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'h
  */
 export interface LinkPropsWithHref extends LinkBaseProps {
   href: string;
-  params?: never;
+  segmentParams?: never;
   /**
    * Typed search params — serialized via the route's SearchParamsDefinition.
    * Mutually exclusive with an inline query string in href.
@@ -73,9 +105,9 @@ export interface LinkPropsWithHref extends LinkBaseProps {
 }
 
 /**
- * Link with a route pattern + params for interpolation.
- * e.g. <Link href="/products/[id]" params={{ id: "123" }}>
- *      <Link href="/products/[id]" params={{ id: 123 }}>
+ * Link with a route pattern + segmentParams for interpolation.
+ * e.g. <Link href="/products/[id]" segmentParams={{ id: "123" }}>
+ *      <Link href="/products/[id]" segmentParams={{ id: 123 }}>
  */
 export interface LinkPropsWithParams extends LinkBaseProps {
   /** Route pattern with dynamic segments (e.g. "/products/[id]") */
@@ -85,7 +117,7 @@ export interface LinkPropsWithParams extends LinkBaseProps {
    * Single dynamic segments accept string | number (numbers are stringified).
    * Catch-all segments accept string[].
    */
-  params: Record<string, string | number | string[]>;
+  segmentParams: Record<string, string | number | string[]>;
   /**
    * Typed search params — serialized via the route's SearchParamsDefinition.
    */
@@ -303,22 +335,34 @@ function shouldInterceptClick(
  * its own click handling.
  *
  * Supports typed routes via codegen overloads. At runtime:
- * - `params` prop interpolates dynamic segments in the href pattern
+ * - `segmentParams` prop interpolates dynamic segments in the href pattern
  * - `searchParams` prop serializes query parameters via a SearchParamsDefinition
  */
 export function Link({
   href,
   prefetch,
   scroll,
-  params,
+  segmentParams,
   searchParams,
+  preserveSearchParams,
   onNavigate,
   onClick: userOnClick,
   onMouseEnter: userOnMouseEnter,
   children,
   ...rest
 }: LinkProps) {
-  const { href: resolvedHref } = buildLinkProps({ href, params, searchParams });
+  const { href: baseHref } = buildLinkProps({ href, params: segmentParams, searchParams });
+
+  // Preserve search params from the current URL when requested.
+  // useSearchParams() works during both SSR (reads from request context)
+  // and on the client (reads from window.location, reactive to URL changes).
+  // We read current search params directly to avoid unconditional hook calls.
+  // On the client, window.location.search is always current; during SSR,
+  // getSsrData() provides the request's search params.
+  const resolvedHref = preserveSearchParams
+    ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+    : baseHref;
+
   const internal = isInternalHref(resolvedHref);
 
   // ─── Click handler ───────────────────────────────────────────
@@ -335,7 +379,11 @@ export function Link({
         // Call onNavigate if provided — allows caller to cancel
         if (onNavigate) {
           let prevented = false;
-          onNavigate({ preventDefault: () => { prevented = true; } });
+          onNavigate({
+            preventDefault: () => {
+              prevented = true;
+            },
+          });
           if (prevented) {
             event.preventDefault();
             return;
@@ -347,20 +395,31 @@ export function Link({
 
         event.preventDefault();
         const shouldScroll = scroll !== false;
-        void router.navigate(resolvedHref, { scroll: shouldScroll });
+
+        // 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
 
   // ─── Hover prefetch ──────────────────────────────────────────
-  const handleMouseEnter = internal && prefetch
-    ? (event: ReactMouseEvent<HTMLAnchorElement>) => {
-        userOnMouseEnter?.(event);
-        const router = getRouterOrNull();
-        if (router) {
-          router.prefetch(resolvedHref);
+  const handleMouseEnter =
+    internal && prefetch
+      ? (event: ReactMouseEvent<HTMLAnchorElement>) => {
+          userOnMouseEnter?.(event);
+          const router = getRouterOrNull();
+          if (router) {
+            // Re-merge preserved search params at hover time for fresh prefetch URL
+            const prefetchHref = preserveSearchParams
+              ? mergePreservedSearchParams(baseHref, getCurrentSearch(), preserveSearchParams)
+              : resolvedHref;
+            router.prefetch(prefetchHref);
+          }
         }
-      }
-    : userOnMouseEnter;
+      : userOnMouseEnter;
 
   return (
     <a {...rest} href={resolvedHref} onClick={handleClick} onMouseEnter={handleMouseEnter}>

package/src/client/navigation-context.ts

@@ -5,7 +5,7 @@
  *
  * Holds the current route params and pathname, updated atomically
  * with the RSC tree on each navigation. This replaces the previous
- * useSyncExternalStore approach for useParams() and usePathname(),
+ * useSyncExternalStore approach for useSegmentParams() and usePathname(),
  * which suffered from a timing gap: the new tree could commit before
  * the external store re-renders fired, causing a frame where both
  * old and new active states were visible simultaneously.
@@ -90,7 +90,7 @@ function getOrCreateContext(): React.Context<NavigationState | null> | undefined
 /**
  * Read the navigation context. Returns null during SSR (no provider)
  * or in the RSC environment (no context available).
- * Internal — used by useParams() and usePathname().
+ * Internal — used by useSegmentParams() and usePathname().
  */
 export function useNavigationContext(): NavigationState | null {
   const ctx = getOrCreateContext();