@timber-js/app 0.2.0-alpha.5 → 0.2.0-alpha.50

package/src/client/router.ts

@@ -6,13 +6,13 @@ import type { SegmentInfo } from './segment-cache';
 import { HistoryStack } from './history';
 import type { HeadElement } from './head';
 import { setCurrentParams } from './use-params.js';
-import { setNavigationState } from './navigation-context.js';
 import {
-  SegmentElementCache,
-  cacheSegmentElements,
-  mergeSegmentTree,
-} from './segment-merger.js';
-import { fetchRscPayload, RedirectError } from './rsc-fetch.js';
+  setNavigationState,
+  getNavigationState,
+  type NavigationState,
+} from './navigation-context.js';
+import { SegmentElementCache, cacheSegmentElements, mergeSegmentTree } from './segment-merger.js';
+import { fetchRscPayload, RedirectError, VersionSkewError } from './rsc-fetch.js';
 import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -35,8 +35,12 @@ export type RscDecoder = (fetchPromise: Promise<Response>) => unknown;
  * Function that renders a decoded RSC element tree into the DOM.
  * In production: reactRoot.render(element).
  * In tests: a no-op or mock.
+ *
+ * Receives the current NavigationState explicitly — no temporal
+ * coupling with setNavigationState/getNavigationState. The renderer
+ * wraps the element in NavigationProvider with this state.
  */
-export type RootRenderer = (element: unknown) => void;
+export type RootRenderer = (element: unknown, navState: NavigationState) => void;
 
 /**
  * Platform dependencies injected for testability. In production these
@@ -68,13 +72,17 @@ export interface RouterDeps {
    *
    * The `perform` callback receives a `wrapPayload` function to wrap the
    * decoded RSC payload with NavigationProvider + NuqsAdapter before
-   * TransitionRoot sets it as the new element.
+   * TransitionRoot sets it as the new element. The `wrapPayload` function
+   * receives the NavigationState explicitly — no temporal coupling with
+   * getNavigationState().
    *
    * If not provided (tests), the router falls back to renderRoot.
    */
   navigateTransition?: (
     pendingUrl: string,
-    perform: (wrapPayload: (payload: unknown) => unknown) => Promise<unknown>
+    perform: (
+      wrapPayload: (payload: unknown, navState: NavigationState) => unknown
+    ) => Promise<unknown>
   ) => Promise<void>;
 }
 
@@ -134,21 +142,40 @@ function isAbortError(error: unknown): boolean {
  * Create a router instance. In production, called once at app hydration
  * with real browser APIs. In tests, called with mock dependencies.
  */
+/**
+ * Router navigation phase — discriminated union replacing scattered
+ * `pending` + `pendingUrl` boolean flags.
+ *
+ * - `idle`: No navigation in flight. The committed params/pathname
+ *   are current.
+ * - `navigating`: A fetch or render is in progress. `targetUrl` is
+ *   the destination being navigated to.
+ */
+export type RouterPhase = { phase: 'idle' } | { phase: 'navigating'; targetUrl: string };
+
 export function createRouter(deps: RouterDeps): RouterInstance {
   const segmentCache = new SegmentCache();
   const prefetchCache = new PrefetchCache();
   const historyStack = new HistoryStack();
   const segmentElementCache = new SegmentElementCache();
 
-  let pending = false;
-  let pendingUrl: string | null = null;
+  let routerPhase: RouterPhase = { phase: 'idle' };
   const pendingListeners = new Set<(pending: boolean) => void>();
 
   function setPending(value: boolean, url?: string): void {
-    const newPendingUrl = value && url ? url : null;
-    if (pending === value && pendingUrl === newPendingUrl) return;
-    pending = value;
-    pendingUrl = newPendingUrl;
+    const next: RouterPhase =
+      value && url ? { phase: 'navigating', targetUrl: url } : { phase: 'idle' };
+    // Skip no-op updates
+    if (
+      routerPhase.phase === next.phase &&
+      (routerPhase.phase === 'idle' ||
+        (routerPhase.phase === 'navigating' &&
+          next.phase === 'navigating' &&
+          routerPhase.targetUrl === next.targetUrl))
+    ) {
+      return;
+    }
+    routerPhase = next;
     // Notify external store listeners (non-React consumers).
     // React-facing pending state is handled by useOptimistic in
     // TransitionRoot via navigateTransition — not this function.
@@ -167,9 +194,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   }
 
   /** Render a decoded RSC payload into the DOM if a renderer is available. */
-  function renderPayload(payload: unknown): void {
+  function renderPayload(payload: unknown, navState: NavigationState): void {
     if (deps.renderRoot) {
-      deps.renderRoot(payload);
+      deps.renderRoot(payload, navState);
     }
   }
 
@@ -198,32 +225,34 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   /**
    * Update navigation state (params + pathname) for the next render.
    *
-   * Sets both the module-level fallback (for tests and SSR) and the
-   * navigation context state (read by renderRoot to wrap the element
-   * in NavigationProvider). The context update is atomic with the tree
-   * render — both are passed to reactRoot.render() in the same call.
+   * Sets the module-level fallback (for tests and SSR) and the
+   * globalThis bridge, then returns the NavigationState so callers
+   * can pass it explicitly to renderRoot/wrapPayload — eliminating
+   * temporal coupling with getNavigationState().
    */
   function updateNavigationState(
     params: Record<string, string | string[]> | null | undefined,
     url: string
-  ): void {
+  ): NavigationState {
     const resolvedParams = params ?? {};
     // Module-level fallback for tests (no NavigationProvider) and SSR
     setCurrentParams(resolvedParams);
-    // Navigation context — read by renderRoot to wrap the RSC element
+    // globalThis bridge — kept for backward compat
     const pathname = url.startsWith('http') ? new URL(url).pathname : url.split('?')[0] || '/';
-    setNavigationState({ params: resolvedParams, pathname });
+    const navState: NavigationState = { params: resolvedParams, pathname };
+    setNavigationState(navState);
+    return navState;
   }
 
   /**
    * Render a payload via navigateTransition (production) or renderRoot (tests).
-   * The perform callback should fetch data, update state, and return the payload.
-   * In production, the entire callback runs inside a React transition with
-   * useOptimistic for the pending URL. In tests, the payload is rendered directly.
+   * The perform callback should fetch data, update state, and return the
+   * FetchResult plus the NavigationState (so it can be passed explicitly
+   * to wrapPayload/renderRoot without temporal coupling).
    */
   async function renderViaTransition(
     url: string,
-    perform: () => Promise<FetchResult>
+    perform: () => Promise<FetchResult & { navState: NavigationState }>
   ): Promise<HeadElement[] | null> {
     if (deps.navigateTransition) {
       let headElements: HeadElement[] | null = null;
@@ -239,7 +268,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           headElements: result.headElements,
           params: result.params,
         });
-        return wrapPayload(merged);
+        // Pass navState explicitly — wrapPayload wraps element in
+        // NavigationProvider with this state, no getNavigationState() needed.
+        return wrapPayload(merged, result.navState);
       });
       return headElements;
     }
@@ -253,7 +284,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       headElements: result.headElements,
       params: result.params,
     });
-    renderPayload(merged);
+    renderPayload(merged, result.navState);
     return result.headElements;
   }
 
@@ -273,6 +304,17 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
+  /**
+   * Schedule scroll restoration after the next paint and fire the
+   * scroll-restored event. Used by navigate, popstate, and refresh.
+   */
+  function restoreScrollAfterPaint(scrollY: number): void {
+    afterPaint(() => {
+      deps.scrollTo(0, scrollY);
+      window.dispatchEvent(new Event('timber:scroll-restored'));
+    });
+  }
+
   /**
    * Core navigation logic shared between the transition and fallback paths.
    * Fetches the RSC payload, updates all state, and returns the result.
@@ -280,7 +322,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   async function performNavigationFetch(
     url: string,
     options: { replace: boolean }
-  ): Promise<FetchResult> {
+  ): Promise<FetchResult & { navState: NavigationState }> {
     // Check prefetch cache first. PrefetchResult has optional segmentInfo/params
     // fields — normalize to null for FetchResult compatibility.
     const prefetched = prefetchCache.consume(url);
@@ -320,10 +362,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     // Update the segment cache with the new route's segment tree.
     updateSegmentCache(result.segmentInfo);
 
-    // Update navigation state (params + pathname) before rendering.
-    updateNavigationState(result.params, url);
+    // Update navigation state and capture it for explicit passing.
+    const navState = updateNavigationState(result.params, url);
 
-    return result;
+    return { ...result, navState };
   }
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
@@ -354,15 +396,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Scroll-to-top on forward navigation, or restore captured position
       // for scroll={false}. React's render() on the document root can reset
       // scroll during DOM reconciliation, so all scroll must be actively managed.
-      afterPaint(() => {
-        if (scroll) {
-          deps.scrollTo(0, 0);
-        } else {
-          deps.scrollTo(0, currentScrollY);
-        }
-        window.dispatchEvent(new Event('timber:scroll-restored'));
-      });
+      restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
     } catch (error) {
+      // Version skew — server has been redeployed. Trigger full page reload
+      // so the browser fetches the new bundle. See TIM-446.
+      if (error instanceof VersionSkewError) {
+        // Import triggerStaleReload dynamically to avoid circular deps
+        // and keep the reload logic centralized with its loop guard.
+        const { triggerStaleReload } = await import('./stale-reload.js');
+        triggerStaleReload();
+        // Return a never-resolving promise — page is reloading.
+        return new Promise(() => {}) as never;
+      }
       // Server-side redirect during RSC fetch → soft router navigation.
       if (error instanceof RedirectError) {
         setPending(false);
@@ -388,8 +433,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         const result = await fetchRscPayload(currentUrl, deps);
         // History push handled by renderViaTransition (stores merged payload)
         updateSegmentCache(result.segmentInfo);
-        updateNavigationState(result.params, currentUrl);
-        return result;
+        const navState = updateNavigationState(result.params, currentUrl);
+        return { ...result, navState };
       });
 
       applyHead(headElements);
@@ -406,13 +451,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
     if (entry && entry.payload !== null) {
       // Replay cached payload — no server roundtrip
-      updateNavigationState(entry.params, url);
-      renderPayload(entry.payload);
+      const navState = updateNavigationState(entry.params, url);
+      renderPayload(entry.payload, navState);
       applyHead(entry.headElements);
-      afterPaint(() => {
-        deps.scrollTo(0, scrollY);
-        window.dispatchEvent(new Event('timber:scroll-restored'));
-      });
+      restoreScrollAfterPaint(scrollY);
     } else {
       // No cached payload — fetch from server.
       // This happens when navigating back to the initial SSR'd page
@@ -421,19 +463,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       setPending(true, url);
       try {
         const headElements = await renderViaTransition(url, async () => {
-          const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
+          const stateTree = segmentCache.serializeStateTree(
+            segmentElementCache.getMergeablePaths()
+          );
           const result = await fetchRscPayload(url, deps, stateTree);
           updateSegmentCache(result.segmentInfo);
-          updateNavigationState(result.params, url);
+          const navState = updateNavigationState(result.params, url);
           // History push handled by renderViaTransition (stores merged payload)
-          return result;
+          return { ...result, navState };
         });
 
         applyHead(headElements);
-        afterPaint(() => {
-          deps.scrollTo(0, scrollY);
-          window.dispatchEvent(new Event('timber:scroll-restored'));
-        });
+        restoreScrollAfterPaint(scrollY);
       } finally {
         setPending(false);
       }
@@ -465,8 +506,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     navigate,
     refresh,
     handlePopState,
-    isPending: () => pending,
-    getPendingUrl: () => pendingUrl,
+    isPending: () => routerPhase.phase === 'navigating',
+    getPendingUrl: () => (routerPhase.phase === 'navigating' ? routerPhase.targetUrl : null),
     onPendingChange(listener) {
       pendingListeners.add(listener);
       return () => pendingListeners.delete(listener);
@@ -483,7 +524,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         payload: merged,
         headElements,
       });
-      renderPayload(merged);
+      // Revalidation doesn't change params/pathname — preserve current state.
+      // DO NOT call updateNavigationState(null, ...) here: that normalizes
+      // params to {}, clearing dynamic route params on every action response.
+      const navState = getNavigationState();
+      renderPayload(merged, navState);
       applyHead(headElements);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),

package/src/client/rsc-fetch.ts

@@ -23,7 +23,7 @@ export interface FetchResult {
   headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
+  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
   params: Record<string, string | string[]> | null;
   /** Segment paths that were skipped by the server (for client-side merging). */
   skippedSegments: string[] | null;
@@ -58,6 +58,43 @@ function appendRscParam(url: string): string {
   return `${url}${separator}_rsc=${generateCacheBustId()}`;
 }
 
+// ─── Deployment ID ───────────────────────────────────────────────
+
+/**
+ * The client's deployment ID, set at bootstrap from the runtime config.
+ * Sent with every RSC/action request for version skew detection.
+ * Null in dev mode. See TIM-446.
+ */
+let clientDeploymentId: string | null = null;
+
+/** Set the client deployment ID. Called once at bootstrap. */
+export function setClientDeploymentId(id: string | null): void {
+  clientDeploymentId = id;
+}
+
+/** Get the client deployment ID. */
+export function getClientDeploymentId(): string | null {
+  return clientDeploymentId;
+}
+
+// ─── Reload Signal ───────────────────────────────────────────────
+
+/** Header name used by the server to signal a version skew reload. */
+export const RELOAD_HEADER = 'X-Timber-Reload';
+
+/** Header name for the client's deployment ID. */
+export const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';
+
+/**
+ * Check if a response signals a version skew reload.
+ * Triggers a full page reload if the server indicates the client is stale.
+ */
+export function checkReloadSignal(response: Response): boolean {
+  return response.headers.get(RELOAD_HEADER) === '1';
+}
+
+// ─── Header Builder ──────────────────────────────────────────────
+
 export function buildRscHeaders(
   stateTree: { segments: string[] } | undefined,
   currentUrl?: string
@@ -75,6 +112,13 @@ export function buildRscHeaders(
   if (currentUrl) {
     headers['X-Timber-URL'] = currentUrl;
   }
+  // Send deployment ID for version skew detection (TIM-446).
+  // The server compares this against the current build's ID.
+  // On mismatch, the server signals a reload instead of returning
+  // an RSC payload with mismatched module references.
+  if (clientDeploymentId) {
+    headers[DEPLOYMENT_ID_HEADER] = clientDeploymentId;
+  }
   return headers;
 }
 
@@ -135,7 +179,7 @@ export function extractSkippedSegments(response: Response): string[] | null {
  * Extract route params from the X-Timber-Params response header.
  * Returns null if the header is missing or malformed.
  *
- * Used to populate useParams() after client-side navigation.
+ * Used to populate useSegmentParams() after client-side navigation.
  */
 export function extractParams(response: Response): Record<string, string | string[]> | null {
   const header = response.headers.get('X-Timber-Params');
@@ -161,6 +205,17 @@ export class RedirectError extends Error {
   }
 }
 
+/**
+ * Thrown when the server signals a version skew (X-Timber-Reload header).
+ * Caught in navigate() to trigger a full page reload via triggerStaleReload().
+ * See TIM-446.
+ */
+export class VersionSkewError extends Error {
+  constructor() {
+    super('Version skew detected — server has been redeployed');
+  }
+}
+
 // ─── Fetch ───────────────────────────────────────────────────────
 
 /**
@@ -192,6 +247,12 @@ export async function fetchRscPayload(
     let params: Record<string, string | string[]> | null = null;
     let skippedSegments: string[] | null = null;
     const wrappedPromise = fetchPromise.then((response) => {
+      // Version skew detection (TIM-446): if the server signals a reload,
+      // throw VersionSkewError so the caller (router navigate) can trigger
+      // a full page reload via triggerStaleReload().
+      if (checkReloadSignal(response)) {
+        throw new VersionSkewError();
+      }
       // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
       // for RSC payload requests instead of a raw 302, because fetch with
       // redirect: "manual" turns 302s into opaque redirects (status 0, null body)

package/src/client/segment-cache.ts

@@ -11,7 +11,7 @@ export interface PrefetchResult {
   headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo?: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
+  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
   params?: Record<string, string | string[]> | null;
   /** Segment paths skipped by the server (for client-side merging). */
   skippedSegments?: string[] | null;

package/src/client/segment-context.ts

@@ -52,7 +52,12 @@ interface SegmentProviderProps {
  * Wraps each layout to provide segment position context.
  * Injected by rsc-entry.ts during element tree construction.
  */
-export function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }: SegmentProviderProps) {
+export function SegmentProvider({
+  segments,
+  segmentId: _segmentId,
+  parallelRouteKeys,
+  children,
+}: SegmentProviderProps) {
   const value = useMemo(
     () => ({ segments, parallelRouteKeys }),
     // segments and parallelRouteKeys are static per layout — they don't change

package/src/client/segment-merger.ts

@@ -186,10 +186,7 @@ function walkChildren(children: ReactNode, out: CachedSegmentEntry[]): void {
  * Cache all segment subtrees from a fully-rendered RSC element tree.
  * Call this after every full RSC payload render (navigate, refresh, hydration).
  */
-export function cacheSegmentElements(
-  element: unknown,
-  cache: SegmentElementCache
-): void {
+export function cacheSegmentElements(element: unknown, cache: SegmentElementCache): void {
   const segments = extractSegments(element);
   for (const entry of segments) {
     cache.set(entry.segmentPath, entry);
@@ -208,10 +205,7 @@ export function cacheSegmentElements(
  */
 type TreePath = Array<{ element: ReactElement; childIndex: number }>;
 
-function findSegmentProviderPath(
-  node: ReactElement,
-  targetPath?: string
-): TreePath | null {
+function findSegmentProviderPath(node: ReactElement, targetPath?: string): TreePath | null {
   const children = (node.props as { children?: ReactNode }).children;
   if (children == null) return null;
 

package/src/client/stale-reload.ts

@@ -32,6 +32,34 @@ export function isStaleClientReference(error: unknown): boolean {
   return msg.includes('Could not find the module') || msg.includes('client reference not found');
 }
 
+/**
+ * Check if an error is a chunk load failure from a dynamic import.
+ *
+ * After a deployment, old chunk filenames no longer exist. When the client
+ * tries to dynamically import a chunk that's been replaced, the browser
+ * throws one of these errors:
+ *
+ * - Chromium: "Failed to fetch dynamically imported module: <url>"
+ * - Firefox: "error loading dynamically imported module: <url>"
+ * - Safari: "Importing a module script failed."
+ * - Vite/Rollup: "Unable to preload CSS for <url>"
+ *
+ * See TIM-446
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const msg = error.message.toLowerCase();
+  return (
+    msg.includes('failed to fetch dynamically imported module') ||
+    msg.includes('error loading dynamically imported module') ||
+    msg.includes('importing a module script failed') ||
+    msg.includes('unable to preload css') ||
+    // Webpack-style chunk load errors (unlikely in Vite but defensive)
+    msg.includes('loading chunk') ||
+    msg.includes('loading css chunk')
+  );
+}
+
 /**
  * Trigger a full page reload to pick up new bundles.
  *
@@ -48,8 +76,8 @@ export function triggerStaleReload(): boolean {
     if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {
       console.warn(
         '[timber] Stale client reference detected again after reload. ' +
-        'Not reloading to prevent infinite loop. ' +
-        'This may indicate a deployment issue — try a hard refresh.'
+          'Not reloading to prevent infinite loop. ' +
+          'This may indicate a deployment issue — try a hard refresh.'
       );
       return false;
     }
@@ -59,7 +87,7 @@ export function triggerStaleReload(): boolean {
 
     console.warn(
       '[timber] Stale client reference detected — the server has been ' +
-      'redeployed with new bundles. Reloading to pick up the new version.'
+        'redeployed with new bundles. Reloading to pick up the new version.'
     );
 
     window.location.reload();
@@ -67,9 +95,7 @@ export function triggerStaleReload(): boolean {
   } catch {
     // sessionStorage may be unavailable (private browsing, storage full, etc.)
     // Fall back to reloading without loop protection
-    console.warn(
-      '[timber] Stale client reference detected. Reloading page.'
-    );
+    console.warn('[timber] Stale client reference detected. Reloading page.');
     window.location.reload();
     return true;
   }

package/src/client/top-loader.tsx

@@ -39,7 +39,7 @@ export interface TopLoaderConfig {
   color?: string;
   /** Bar height in pixels. Default: 3. */
   height?: number;
-  /** Show subtle glow/shadow effect. Default: true. */
+  /** Show subtle glow/shadow effect. Default: false. */
   shadow?: boolean;
   /** Delay in ms before showing the bar. Default: 0. */
   delay?: number;
@@ -51,7 +51,7 @@ export interface TopLoaderConfig {
 
 const DEFAULT_COLOR = '#2299DD';
 const DEFAULT_HEIGHT = 3;
-const DEFAULT_SHADOW = true;
+const DEFAULT_SHADOW = false;
 const DEFAULT_DELAY = 0;
 const DEFAULT_Z_INDEX = 1600;
 
@@ -183,18 +183,19 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
   };
 
   // Clean up the finishing phase when the finish animation completes.
-  const handleAnimationEnd = phase === 'finishing'
-    ? (e: React.AnimationEvent) => {
-        if (e.animationName === FINISH_KEYFRAMES) {
-          setPhase('hidden');
+  const handleAnimationEnd =
+    phase === 'finishing'
+      ? (e: React.AnimationEvent) => {
+          if (e.animationName === FINISH_KEYFRAMES) {
+            setPhase('hidden');
+          }
         }
-      }
-    : undefined;
+      : undefined;
 
   return createElement(
     'div',
     {
-      style: containerStyle,
+      'style': containerStyle,
       'aria-hidden': 'true',
       'data-timber-top-loader': '',
     },

package/src/client/transition-root.tsx

@@ -62,7 +62,13 @@ let _navigateTransition:
  * Non-navigation renders:
  *   transitionRender(newWrappedElement);
  */
-export function TransitionRoot({ initial, topLoaderConfig }: { initial: ReactNode; topLoaderConfig?: TopLoaderConfig }): ReactNode {
+export function TransitionRoot({
+  initial,
+  topLoaderConfig,
+}: {
+  initial: ReactNode;
+  topLoaderConfig?: TopLoaderConfig;
+}): ReactNode {
   const [element, setElement] = useState<ReactNode>(initial);
   const [pendingUrl, setPendingUrl] = useState<string | null>(null);
   const [, startTransition] = useTransition();

package/src/client/use-params.ts

@@ -119,9 +119,9 @@ export function notifyParamsListeners(): void {
  *   exact params shape from the generated Routes interface.
  * @overload Fallback — returns the generic params record.
  */
-export function useParams<R extends keyof Routes>(route: R): Routes[R]['params'];
-export function useParams(route?: string): Record<string, string | string[]>;
-export function useParams(_route?: string): Record<string, string | string[]> {
+export function useSegmentParams<R extends keyof Routes>(route: R): Routes[R]['params'];
+export function useSegmentParams(route?: string): Record<string, string | string[]>;
+export function useSegmentParams(_route?: string): Record<string, string | string[]> {
   // Try reading from NavigationContext (client-side, inside React tree).
   // During SSR, no NavigationProvider is mounted, so this returns null.
   // When called outside a React component, useContext throws — caught below.

package/src/client/use-query-states.ts

@@ -17,7 +17,7 @@ import type {
   SearchParamsDefinition,
   SetParams,
   QueryStatesOptions,
-} from '#/search-params/create.js';
+} from '#/search-params/define.js';
 import { getSearchParams } from '#/search-params/registry.js';
 
 // ─── Codec Bridge ─────────────────────────────────────────────────

package/src/codec.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared codec protocol for parsing and serializing string values.
+ *
+ * Used by both search params and cookies. Any object with parse + serialize
+ * methods satisfies this interface. nuqs parsers are valid codecs natively.
+ *
+ * Design doc: design/23a-search-params-triage.md §"Unify Codec<T> type"
+ */
+
+/**
+ * A codec that converts between string values and typed values.
+ *
+ * The canonical protocol shared across search params, cookies, and
+ * any future timber feature that needs string ↔ typed conversion.
+ */
+export interface Codec<T> {
+  /** String → typed value. Receives undefined when the value is absent. */
+  parse(value: string | string[] | undefined): T;
+  /** Typed value → string. Return null to omit/clear. */
+  serialize(value: T): string | null;
+}