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

package/src/client/navigation-context.ts

@@ -3,17 +3,19 @@
 /**
  * NavigationContext — React context for navigation state.
  *
- * 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(),
- * 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.
+ * Holds the current pathname and search, updated atomically with the RSC
+ * tree on each navigation. This replaces the previous useSyncExternalStore
+ * approach for usePathname() and useSearchParams(), 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.
+ *
+ * Segment params are NOT here — see the note on NavigationState below.
  *
  * By wrapping the RSC payload element in NavigationProvider inside
  * renderRoot(), the context value and the element tree are passed to
  * reactRoot.render() in the same call — atomic by construction.
- * All consumers (useParams, usePathname) see the new values in the
+ * All consumers (usePathname, useSearchParams) see the new values in the
  * same render pass as the new tree.
  *
  * During SSR, no NavigationProvider is mounted. Hooks fall back to
@@ -40,14 +42,25 @@
  */
 
 import React, { createElement, type ReactNode } from 'react';
+import type { SlotParamsRecord } from '../shared/slot-params.js';
 
 // ---------------------------------------------------------------------------
 // Context type
 // ---------------------------------------------------------------------------
 
+/**
+ * What the browser knows about the current location.
+ *
+ * Params are deliberately absent: they are a property of the tree the server
+ * rendered, not of the address bar, and they now travel inside the payload as
+ * the payload root. Keeping a copy here meant the router had to thread
+ * the record from a response header into context on every path — navigation,
+ * traversal, prefetch, revalidation — and each of those was a place to drop it
+ * (TIM-1294).
+ */
 export interface NavigationState {
-  params: Record<string, string | string[]>;
   pathname: string;
+  search: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -62,8 +75,8 @@ export interface NavigationState {
  * Context instances are stored on globalThis (NOT in module-level
  * variables) because the ESM bundler can duplicate this module across
  * chunks. Module-level variables would create separate instances per
- * chunk — the provider in TransitionRoot (index chunk) would use
- * context A while the consumer in LinkStatusProvider (shared chunk)
+ * chunk — the provider in NavigationRoot (index chunk) would use
+ * context A while the consumer in usePendingNavigation (shared chunk)
  * reads from context B. globalThis guarantees a single instance.
  *
  * See design/27-chunking-strategy.md §"Singleton Safety"
@@ -71,7 +84,6 @@ export interface NavigationState {
 
 // Symbol keys for globalThis storage — prevents collisions with user code
 const NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');
-const PENDING_CTX_KEY = Symbol.for('__timber_pending_nav_ctx');
 
 function getOrCreateContext(): React.Context<NavigationState | null> | undefined {
   const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as
@@ -90,13 +102,14 @@ 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 usePathname() and useSearchParams().
  */
 export function useNavigationContext(): NavigationState | null {
   const ctx = getOrCreateContext();
   if (!ctx) return null;
   // useContext may not exist in the RSC environment — caller wraps in try/catch
   if (typeof React.useContext !== 'function') return null;
+  // eslint-disable-next-line rules-of-hooks -- conditional on environment, not render path
   return React.useContext(ctx);
 }
 
@@ -149,7 +162,7 @@ const NAV_STATE_KEY = Symbol.for('__timber_nav_state');
 function _getNavStateStore(): { current: NavigationState } {
   const g = globalThis as Record<symbol, unknown>;
   if (!g[NAV_STATE_KEY]) {
-    g[NAV_STATE_KEY] = { current: { params: {}, pathname: '/' } };
+    g[NAV_STATE_KEY] = { current: { pathname: '/', search: '' } };
   }
   return g[NAV_STATE_KEY] as { current: NavigationState };
 }
@@ -163,57 +176,25 @@ export function getNavigationState(): NavigationState {
 }
 
 // ---------------------------------------------------------------------------
-// Pending Navigation Context (same module for singleton guarantee)
+// Pending navigation state lives in the router, not here
 // ---------------------------------------------------------------------------
 
 /**
- * Separate context for the in-flight navigation URL. Provided by
- * TransitionRoot (urgent useState), consumed by LinkStatusProvider
- * and useNavigationPending.
+ * There was a second React context here — `PendingNavigationContext`, holding
+ * the in-flight navigation URL, provided by `NavigationRoot` out of a
+ * `useState` — plus a `usePendingNavigationUrl()` reader for it. Both are gone
+ * (TIM-1307).
  *
- * Uses globalThis via Symbol.for for the same reason as NavigationContext
- * above — the bundler may duplicate this module across chunks, and module-
- * level variables would create separate context instances.
- */
-
-function getOrCreatePendingContext(): React.Context<string | null> | undefined {
-  const existing = (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] as
-    | React.Context<string | null>
-    | undefined;
-  if (existing !== undefined) return existing;
-  if (typeof React.createContext === 'function') {
-    const ctx = React.createContext<string | null>(null);
-    (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] = ctx;
-    return ctx;
-  }
-  return undefined;
-}
-
-/**
- * Read the pending navigation URL from context.
- * Returns null during SSR (no provider) or in the RSC environment.
- */
-export function usePendingNavigationUrl(): string | null {
-  const ctx = getOrCreatePendingContext();
-  if (!ctx) return null;
-  if (typeof React.useContext !== 'function') return null;
-  return React.useContext(ctx);
-}
-
-/**
- * Provider for the pending navigation URL. Wraps children with
- * the pending context Provider.
+ * Nothing read them. `usePendingNavigation()` (use-pending-navigation.ts) and
+ * `TopLoader` both subscribe to the router's external pending store via
+ * `useSyncExternalStore`: sync priority, immune to transition entanglement,
+ * and cleared by `runNavigation`'s supersession-guarded `finally` (TIM-1034).
+ * The context was a parallel representation of the same fact that no consumer
+ * ever migrated to, and one that could not even agree with the store — a
+ * navigation superseded by a cached popstate replay left its URL set until the
+ * next full navigation, because the staleness guard skipped the clear and no
+ * other path touched it.
+ *
+ * One representation, and it is the router's. See
+ * design/19-client-navigation.md §"How Pending State Works".
  */
-export function PendingNavigationProvider({
-  value,
-  children,
-}: {
-  value: string | null;
-  children?: ReactNode;
-}): React.ReactElement {
-  const ctx = getOrCreatePendingContext();
-  if (!ctx) {
-    return children as React.ReactElement;
-  }
-  return createElement(ctx.Provider, { value }, children);
-}