@timber-js/app 0.1.22 → 0.1.24

package/dist/client/use-params.d.ts

@@ -18,10 +18,11 @@
  * (populated by ssr-entry.ts) to ensure correct per-request isolation
  * across concurrent requests with streaming Suspense.
  *
- * Reactivity: useParams() uses useSyncExternalStore so that components
- * in unchanged layouts (e.g., sidebar items) re-render atomically when
- * params change during client-side navigation. This matches the pattern
- * used by usePathname() and useSearchParams().
+ * Reactivity: On the client, useParams() reads from NavigationContext
+ * which is updated atomically with the RSC tree render. This replaces
+ * the previous useSyncExternalStore approach that suffered from a
+ * timing gap between tree render and store notification — causing
+ * preserved layout components to briefly show stale active state.
  *
  * All mutable state is delegated to client/state.ts for singleton guarantees.
  * See design/18-build-system.md §"Singleton State Registry"
@@ -30,37 +31,40 @@
  */
 import type { Routes } from '#/index.js';
 /**
- * Subscribe to params changes. Called by useSyncExternalStore.
- * Exported for testing — not intended for direct use by app code.
+ * Subscribe to params changes.
+ * Retained for backward compatibility with tests that verify the
+ * subscribe/notify contract. On the client, useParams() reads from
+ * NavigationContext instead.
  */
 export declare function subscribe(callback: () => void): () => void;
 /**
- * Get the current params snapshot (client).
- * Exported for testing — not intended for direct use by app code.
+ * Get the current params snapshot (module-level fallback).
+ * Used by tests and by the hook when called outside a React component.
  */
 export declare function getSnapshot(): Record<string, string | string[]>;
 /**
- * Set the current route params WITHOUT notifying subscribers.
- * Called by the router before renderPayload() so that new components
- * in the RSC tree see the updated params via getSnapshot(), but
- * preserved layout components don't re-render prematurely with
- * {old tree, new params}.
+ * Set the current route params in the module-level store.
  *
- * After the React render commits, the router calls notifyParamsListeners()
- * to trigger re-renders in preserved layouts that read useParams().
+ * Called by the router on each navigation. This updates the fallback
+ * snapshot used by tests and by the hook when called outside a React
+ * component (no NavigationContext available).
+ *
+ * On the client, the primary reactivity path is NavigationContext —
+ * the router calls setNavigationState() then renderRoot() which wraps
+ * the element in NavigationProvider. setCurrentParams is still called
+ * for the module-level fallback.
  *
- * On the client, the segment router calls this on each navigation.
  * During SSR, params are also available via getSsrData().params
- * (ALS-backed), but setCurrentParams is still called for the
- * module-level fallback path.
+ * (ALS-backed).
  */
 export declare function setCurrentParams(params: Record<string, string | string[]>): void;
 /**
- * Notify all useSyncExternalStore subscribers that params have changed.
- * Called by the router AFTER renderPayload() so that preserved layout
- * components re-render only after the new tree is committed — producing
- * an atomic {new tree, new params} update instead of a stale
- * {old tree, new params} intermediate state.
+ * Notify all legacy subscribers that params have changed.
+ *
+ * Retained for backward compatibility with tests. On the client,
+ * the NavigationContext + renderRoot pattern replaces this — params
+ * update atomically with the tree render, so explicit notification
+ * is no longer needed.
  */
 export declare function notifyParamsListeners(): void;
 /**
@@ -69,9 +73,15 @@ export declare function notifyParamsListeners(): void;
  * The optional `_route` argument exists only for TypeScript narrowing —
  * it does not affect the runtime return value.
  *
+ * On the client, reads from NavigationContext (provided by
+ * NavigationProvider in renderRoot). This ensures params update
+ * atomically with the RSC tree — no timing gap.
+ *
  * During SSR, reads from the ALS-backed SSR data context to ensure
- * per-request isolation. On the client, subscribes to the module-level
- * params store via useSyncExternalStore.
+ * per-request isolation across concurrent requests with streaming Suspense.
+ *
+ * When called outside a React component (e.g., in test assertions),
+ * falls back to the module-level snapshot.
  *
  * @overload Typed — when a known route path is passed, returns the
  *   exact params shape from the generated Routes interface.

package/dist/client/use-params.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-params.d.ts","sourceRoot":"","sources":["../../src/client/use-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAQzC;;;GAGG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAE/D;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAEhF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AACjF,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC"}
+{"version":3,"file":"use-params.d.ts","sourceRoot":"","sources":["../../src/client/use-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AASzC;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAE/D;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AACjF,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC"}

package/dist/client/use-pathname.d.ts

@@ -4,17 +4,24 @@
  * Returns the pathname portion of the current URL (e.g. '/dashboard/settings').
  * Updates when client-side navigation changes the URL.
  *
- * This is a thin wrapper over window.location.pathname, provided for
- * Next.js API compatibility (libraries like nuqs import usePathname
- * from next/navigation).
+ * On the client, reads from NavigationContext which is updated atomically
+ * with the RSC tree render. This replaces the previous useSyncExternalStore
+ * approach which only subscribed to popstate events — meaning usePathname()
+ * did NOT re-render on forward navigation (pushState). The context approach
+ * fixes this: pathname updates in the same render pass as the new tree.
  *
  * During SSR, reads the request pathname from the SSR ALS context
  * (populated by ssr-entry.ts) instead of window.location.
+ *
+ * Compatible with Next.js's `usePathname()` from `next/navigation`.
  */
 /**
  * Read the current URL pathname.
  *
- * Compatible with Next.js's `usePathname()` from `next/navigation`.
+ * On the client, reads from NavigationContext (provided by
+ * NavigationProvider in renderRoot). During SSR, reads from the
+ * ALS-backed SSR data context. Falls back to window.location.pathname
+ * when called outside a React component (e.g., in tests).
  */
 export declare function usePathname(): string;
 //# sourceMappingURL=use-pathname.d.ts.map

package/dist/client/use-pathname.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-pathname.d.ts","sourceRoot":"","sources":["../../src/client/use-pathname.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAuBH;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}
+{"version":3,"file":"use-pathname.d.ts","sourceRoot":"","sources":["../../src/client/use-pathname.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAoBpC"}

package/dist/cookies/index.js

@@ -1,7 +1,7 @@
 import "../_chunks/als-registry-c0AGnbqS.js";
 import { n as cookies } from "../_chunks/request-context-C69VW4xS.js";
-import "../_chunks/ssr-data-B2yikEEB.js";
-import { t as useCookie } from "../_chunks/use-cookie-D5aS4slY.js";
+import "../_chunks/ssr-data-DLnbYpj1.js";
+import { t as useCookie } from "../_chunks/use-cookie-dDbpCTx-.js";
 //#region src/cookies/define-cookie.ts
 /**
 * defineCookie — typed cookie definitions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/browser-entry.ts

@@ -50,6 +50,7 @@ import { applyHeadElements } from './head.js';
 import { TimberNuqsAdapter } from './nuqs-adapter.js';
 import { isPageUnloading } from './unload-guard.js';
 import { ON_NAVIGATE_KEY } from './link-navigate-interceptor.js';
+import { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -275,10 +276,33 @@ function bootstrap(runtimeConfig: typeof config): void {
     // it's safe to create the router before reactRoot is assigned.
     initRouter();
 
+    // ── Initialize navigation state BEFORE hydration ───────────────────
+    // Read server-embedded params and set navigation state so that
+    // useParams() 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;
+    if (earlyParams && typeof earlyParams === 'object') {
+      setCurrentParams(earlyParams as Record<string, string | string[]>);
+      setNavigationState({
+        params: earlyParams as Record<string, string | string[]>,
+        pathname: window.location.pathname,
+      });
+      delete (self as unknown as Record<string, unknown>).__timber_params;
+    } else {
+      setNavigationState({
+        params: {},
+        pathname: window.location.pathname,
+      });
+    }
+
     // Hydrate on document — the root layout renders the full <html> tree,
     // so React owns the entire document from the root.
-    // Wrap with TimberNuqsAdapter so useQueryStates works out of the box.
-    const wrapped = createElement(TimberNuqsAdapter, null, element as React.ReactNode);
+    // Wrap with NavigationProvider (for atomic useParams/usePathname) and
+    // TimberNuqsAdapter (for nuqs context).
+    const navState = getNavigationState();
+    const withNav = createElement(NavigationProvider, { value: navState }, element as React.ReactNode);
+    const wrapped = createElement(TimberNuqsAdapter, null, withNav);
     reactRoot = hydrateRoot(document, wrapped, {
       // Suppress recoverable hydration errors from deny/error signals
       // inside Suspense boundaries. The server already handled these
@@ -336,11 +360,22 @@ function bootstrap(runtimeConfig: typeof config): void {
       },
 
       // Render decoded RSC tree into the hydrated React root.
-      // Wrap with TimberNuqsAdapter to maintain nuqs context across navigations.
-      // Reads `reactRoot` from the outer closure — assigned after hydrateRoot().
+      // Wraps with NavigationProvider (for atomic useParams/usePathname updates)
+      // and TimberNuqsAdapter (for nuqs context). Reads `reactRoot` and
+      // navigation state from closures — both set before this callback fires.
+      //
+      // The router calls setNavigationState() before renderRoot(), so
+      // getNavigationState() returns the new params/pathname. By wrapping
+      // the element in NavigationProvider here, the context value and the
+      // RSC tree are passed to reactRoot.render() in the same call —
+      // making the update atomic. Preserved layout components that call
+      // useParams() or usePathname() re-render in the same pass as the
+      // new tree, preventing the dual-active-state flash.
       renderRoot: (element: unknown) => {
         if (reactRoot) {
-          const wrapped = createElement(TimberNuqsAdapter, null, element as React.ReactNode);
+          const navState = getNavigationState();
+          const withNav = createElement(NavigationProvider, { value: navState }, element as React.ReactNode);
+          const wrapped = createElement(TimberNuqsAdapter, null, withNav);
           reactRoot.render(wrapped);
         }
       },
@@ -384,11 +419,16 @@ function bootstrap(runtimeConfig: typeof config): void {
     delete (self as unknown as Record<string, unknown>).__timber_segments;
   }
 
-  // Populate useParams() from server-embedded route params.
-  // Without this, useParams() returns {} until the first client navigation.
-  const timberParams = (self as unknown as Record<string, unknown>).__timber_params;
-  if (timberParams && typeof timberParams === 'object') {
-    setCurrentParams(timberParams as Record<string, string | string[]>);
+  // Note: __timber_params is read before hydrateRoot (see above) so that
+  // NavigationProvider has correct values during hydration. If the hydration
+  // path was skipped (no RSC payload), populate the fallback here.
+  const lateTimberParams = (self as unknown as Record<string, unknown>).__timber_params;
+  if (lateTimberParams && typeof lateTimberParams === 'object') {
+    setCurrentParams(lateTimberParams as Record<string, string | string[]>);
+    setNavigationState({
+      params: lateTimberParams as Record<string, string | string[]>,
+      pathname: window.location.pathname,
+    });
     delete (self as unknown as Record<string, unknown>).__timber_params;
   }
 

package/src/client/index.ts

@@ -44,6 +44,10 @@ export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from '.
 // Params
 export { useParams, setCurrentParams } from './use-params';
 
+// Navigation context (framework-internal, used by browser-entry for atomic updates)
+export { NavigationProvider, NavigationContext, getNavigationState, setNavigationState } from './navigation-context';
+export type { NavigationState } from './navigation-context';
+
 // Query states (URL-synced search params)
 export { useQueryStates, bindUseQueryStates } from './use-query-states';
 

package/src/client/navigation-context.ts

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ *
+ * 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
+ * same render pass as the new tree.
+ *
+ * During SSR, no NavigationProvider is mounted. Hooks fall back to
+ * the ALS-backed getSsrData() for per-request isolation.
+ *
+ * See design/19-client-navigation.md §"Navigation Flow"
+ */
+
+import { createContext, useContext, createElement, type ReactNode } from 'react';
+
+// ---------------------------------------------------------------------------
+// Context type and creation
+// ---------------------------------------------------------------------------
+
+export interface NavigationState {
+  params: Record<string, string | string[]>;
+  pathname: string;
+}
+
+/**
+ * The context value is null when no provider is mounted (SSR).
+ * On the client, NavigationProvider always wraps the tree.
+ */
+export const NavigationContext = createContext<NavigationState | null>(null);
+
+/**
+ * Read the navigation context. Returns null during SSR (no provider).
+ * Internal — used by useParams() and usePathname().
+ */
+export function useNavigationContext(): NavigationState | null {
+  return useContext(NavigationContext);
+}
+
+// ---------------------------------------------------------------------------
+// Provider component
+// ---------------------------------------------------------------------------
+
+export interface NavigationProviderProps {
+  value: NavigationState;
+  children?: ReactNode;
+}
+
+/**
+ * Wraps children with NavigationContext.Provider.
+ *
+ * Used in browser-entry.ts renderRoot to wrap the RSC payload element
+ * so that navigation state updates atomically with the tree render.
+ */
+export function NavigationProvider({ value, children }: NavigationProviderProps): React.ReactElement {
+  return createElement(NavigationContext.Provider, { value }, children);
+}
+
+// ---------------------------------------------------------------------------
+// Module-level state for renderRoot to read
+// ---------------------------------------------------------------------------
+
+/**
+ * Module-level navigation state. Updated by the router before calling
+ * renderRoot(). The renderRoot callback reads this to create the
+ * NavigationProvider with the correct values.
+ *
+ * This is NOT used by hooks directly — hooks read from React context.
+ * This exists only as a communication channel between the router
+ * (which knows the new nav state) and renderRoot (which wraps the element).
+ */
+let _currentNavState: NavigationState = { params: {}, pathname: '/' };
+
+export function setNavigationState(state: NavigationState): void {
+  _currentNavState = state;
+}
+
+export function getNavigationState(): NavigationState {
+  return _currentNavState;
+}

package/src/client/router.ts

@@ -5,7 +5,8 @@ import { SegmentCache, PrefetchCache, buildSegmentTree } from './segment-cache';
 import type { SegmentInfo } from './segment-cache';
 import { HistoryStack } from './history';
 import type { HeadElement } from './head';
-import { setCurrentParams, notifyParamsListeners } from './use-params.js';
+import { setCurrentParams } from './use-params.js';
+import { setNavigationState } from './navigation-context.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -324,9 +325,26 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
-  /** Update useParams() with route params from the server response. */
-  function updateParams(params: Record<string, string | string[]> | null | undefined): void {
-    setCurrentParams(params ?? {});
+  /**
+   * 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.
+   */
+  function updateNavigationState(
+    params: Record<string, string | string[]> | null | undefined,
+    url: string
+  ): void {
+    const resolvedParams = params ?? {};
+    // Module-level fallback for tests (no NavigationProvider) and SSR
+    setCurrentParams(resolvedParams);
+    // Navigation context — read by renderRoot to wrap the RSC element
+    const pathname = url.startsWith('http')
+      ? new URL(url).pathname
+      : url.split('?')[0] || '/';
+    setNavigationState({ params: resolvedParams, pathname });
   }
 
   /** Apply head elements (title, meta tags) to the DOM if available. */
@@ -393,19 +411,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // header reflects the currently mounted segments.
       updateSegmentCache(result.segmentInfo);
 
-      // Update the params snapshot before rendering so new components in the
-      // RSC tree see the correct params via getSnapshot(). Subscriber
-      // notification is deferred until after renderPayload() so preserved
-      // layouts don't re-render with {old tree, new params}.
-      updateParams(result.params);
-
-      // Render the decoded RSC tree into the DOM.
+      // Update navigation state (params + pathname) before rendering.
+      // The renderRoot callback reads this state and wraps the RSC element
+      // in NavigationProvider — so the context value and the element tree
+      // are passed to reactRoot.render() in the same call, making the
+      // update atomic. Preserved layouts see new params in the same render
+      // pass as the new tree, preventing the dual-active-row flash.
+      updateNavigationState(result.params, url);
       renderPayload(result.payload);
 
-      // Now notify useParams() subscribers — preserved layout components
-      // re-render after the new tree is committed, seeing {new tree, new params}.
-      notifyParamsListeners();
-
       // Update document.title and <meta> tags with the new page's metadata
       applyHead(result.headElements);
 
@@ -464,12 +478,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Update segment cache with fresh segment info from full render
       updateSegmentCache(result.segmentInfo);
 
-      // Update params snapshot before rendering (see navigate() for rationale)
-      updateParams(result.params);
-
-      // Render the fresh RSC tree, then notify params subscribers
+      // Atomic update — see navigate() for rationale on NavigationProvider.
+      updateNavigationState(result.params, currentUrl);
       renderPayload(result.payload);
-      notifyParamsListeners();
       applyHead(result.headElements);
     } finally {
       setPending(false);
@@ -484,9 +495,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
     if (entry && entry.payload !== null) {
       // Replay cached payload — no server roundtrip
-      updateParams(entry.params);
+      updateNavigationState(entry.params, url);
       renderPayload(entry.payload);
-      notifyParamsListeners();
       applyHead(entry.headElements);
       afterPaint(() => {
         deps.scrollTo(0, scrollY);
@@ -502,14 +512,13 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         const stateTree = segmentCache.serializeStateTree();
         const result = await fetchRscPayload(url, deps, stateTree);
         updateSegmentCache(result.segmentInfo);
-        updateParams(result.params);
+        updateNavigationState(result.params, url);
         historyStack.push(url, {
           payload: result.payload,
           headElements: result.headElements,
           params: result.params,
         });
         renderPayload(result.payload);
-        notifyParamsListeners();
         applyHead(result.headElements);
         afterPaint(() => {
           deps.scrollTo(0, scrollY);

package/src/client/use-params.ts

@@ -18,10 +18,11 @@
  * (populated by ssr-entry.ts) to ensure correct per-request isolation
  * across concurrent requests with streaming Suspense.
  *
- * Reactivity: useParams() uses useSyncExternalStore so that components
- * in unchanged layouts (e.g., sidebar items) re-render atomically when
- * params change during client-side navigation. This matches the pattern
- * used by usePathname() and useSearchParams().
+ * Reactivity: On the client, useParams() reads from NavigationContext
+ * which is updated atomically with the RSC tree render. This replaces
+ * the previous useSyncExternalStore approach that suffered from a
+ * timing gap between tree render and store notification — causing
+ * preserved layout components to briefly show stale active state.
  *
  * All mutable state is delegated to client/state.ts for singleton guarantees.
  * See design/18-build-system.md §"Singleton State Registry"
@@ -29,18 +30,20 @@
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
 
-import { useSyncExternalStore } from 'react';
 import type { Routes } from '#/index.js';
 import { getSsrData } from './ssr-data.js';
 import { currentParams, _setCurrentParams, paramsListeners } from './state.js';
+import { useNavigationContext } from './navigation-context.js';
 
 // ---------------------------------------------------------------------------
-// Module-level subscribe/notify pattern — state lives in state.ts
+// Module-level subscribe/notify pattern — kept for backward compat and tests
 // ---------------------------------------------------------------------------
 
 /**
- * Subscribe to params changes. Called by useSyncExternalStore.
- * Exported for testing — not intended for direct use by app code.
+ * Subscribe to params changes.
+ * Retained for backward compatibility with tests that verify the
+ * subscribe/notify contract. On the client, useParams() reads from
+ * NavigationContext instead.
  */
 export function subscribe(callback: () => void): () => void {
   paramsListeners.add(callback);
@@ -48,51 +51,43 @@ export function subscribe(callback: () => void): () => void {
 }
 
 /**
- * Get the current params snapshot (client).
- * Exported for testing — not intended for direct use by app code.
+ * Get the current params snapshot (module-level fallback).
+ * Used by tests and by the hook when called outside a React component.
  */
 export function getSnapshot(): Record<string, string | string[]> {
   return currentParams;
 }
 
-/**
- * Get the server-side params snapshot (SSR).
- * Falls back to the module-level currentParams if no SSR context
- * is available (shouldn't happen, but defensive).
- */
-function getServerSnapshot(): Record<string, string | string[]> {
-  return getSsrData()?.params ?? currentParams;
-}
-
 // ---------------------------------------------------------------------------
 // Framework API — called by the segment router on each navigation
 // ---------------------------------------------------------------------------
 
 /**
- * Set the current route params WITHOUT notifying subscribers.
- * Called by the router before renderPayload() so that new components
- * in the RSC tree see the updated params via getSnapshot(), but
- * preserved layout components don't re-render prematurely with
- * {old tree, new params}.
+ * Set the current route params in the module-level store.
+ *
+ * Called by the router on each navigation. This updates the fallback
+ * snapshot used by tests and by the hook when called outside a React
+ * component (no NavigationContext available).
  *
- * After the React render commits, the router calls notifyParamsListeners()
- * to trigger re-renders in preserved layouts that read useParams().
+ * On the client, the primary reactivity path is NavigationContext —
+ * the router calls setNavigationState() then renderRoot() which wraps
+ * the element in NavigationProvider. setCurrentParams is still called
+ * for the module-level fallback.
  *
- * On the client, the segment router calls this on each navigation.
  * During SSR, params are also available via getSsrData().params
- * (ALS-backed), but setCurrentParams is still called for the
- * module-level fallback path.
+ * (ALS-backed).
  */
 export function setCurrentParams(params: Record<string, string | string[]>): void {
   _setCurrentParams(params);
 }
 
 /**
- * Notify all useSyncExternalStore subscribers that params have changed.
- * Called by the router AFTER renderPayload() so that preserved layout
- * components re-render only after the new tree is committed — producing
- * an atomic {new tree, new params} update instead of a stale
- * {old tree, new params} intermediate state.
+ * Notify all legacy subscribers that params have changed.
+ *
+ * Retained for backward compatibility with tests. On the client,
+ * the NavigationContext + renderRoot pattern replaces this — params
+ * update atomically with the tree render, so explicit notification
+ * is no longer needed.
  */
 export function notifyParamsListeners(): void {
   for (const listener of paramsListeners) {
@@ -110,9 +105,15 @@ export function notifyParamsListeners(): void {
  * The optional `_route` argument exists only for TypeScript narrowing —
  * it does not affect the runtime return value.
  *
+ * On the client, reads from NavigationContext (provided by
+ * NavigationProvider in renderRoot). This ensures params update
+ * atomically with the RSC tree — no timing gap.
+ *
  * During SSR, reads from the ALS-backed SSR data context to ensure
- * per-request isolation. On the client, subscribes to the module-level
- * params store via useSyncExternalStore.
+ * per-request isolation across concurrent requests with streaming Suspense.
+ *
+ * When called outside a React component (e.g., in test assertions),
+ * falls back to the module-level snapshot.
  *
  * @overload Typed — when a known route path is passed, returns the
  *   exact params shape from the generated Routes interface.
@@ -121,25 +122,20 @@ export function notifyParamsListeners(): void {
 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[]> {
-  // useSyncExternalStore handles both client and SSR:
-  // - Client: calls getSnapshot() → reads currentParams from state.ts
-  // - SSR: calls getServerSnapshot() → reads from ALS-backed getSsrData()
-  //
-  // We must always call the hook (Rules of Hooks — no conditional hook calls).
-  // React picks the right snapshot function based on the environment.
-  //
-  // When called outside a React component (e.g., in test assertions),
-  // useSyncExternalStore throws because there's no dispatcher. In that case,
-  // fall back to reading the snapshot directly.
+  // 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.
   try {
-    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    const navContext = useNavigationContext();
+    if (navContext !== null) {
+      return navContext.params;
+    }
   } catch {
-    // No React dispatcher available — return the best available snapshot.
-    // This path is hit when useParams() is called outside a component,
-    // e.g. in test assertions that verify the current params value.
-    // Use getServerSnapshot() because it checks the ALS-backed SSR context
-    // first (request-isolated), falling back to module-level currentParams
-    // only when no SSR context exists (client-side / tests).
-    return getServerSnapshot();
+    // No React dispatcher available (called outside a component).
+    // Fall through to module-level snapshot below.
   }
+
+  // SSR path: read from ALS-backed SSR data context.
+  // Falls back to module-level currentParams for tests.
+  return getSsrData()?.params ?? currentParams;
 }