@timber-js/app 0.2.0-alpha.17 → 0.2.0-alpha.171

package/src/client/ssr-data.ts

@@ -41,12 +41,20 @@ export interface SsrData {
   /** The request's route params (e.g. { id: '123' }) */
   params: Record<string, string | string[]>;
   /**
-   * Mutable reference to NavContext for error boundary → RSC communication.
-   * When TimberErrorBoundary catches a DenySignal, it sets
-   * `_navContext._denyHandledByBoundary = true` to prevent the RSC entry
-   * from promoting the denial to page-level. See LOCAL-298.
+   * Mutable reference to NavContext for error boundary → pipeline communication.
+   *
+   * When TimberErrorBoundary catches a DenySignal during SSR, it:
+   * 1. Sets `statusCode` to the deny status (e.g., 403) — so the HTTP
+   *    Response has the correct status code without a re-render.
+   * 2. Sets `_denyHandledByBoundary = true` — so the pipeline skips
+   *    the redundant renderDenyPage() re-render.
+   *
+   * This runs synchronously during Fizz rendering, BEFORE onShellReady,
+   * so the status code is committed before any bytes are sent.
+   *
+   * See TIM-664, design/04-authorization.md §"React.cache Scope in Deny/Error Re-renders"
    */
-  _navContext?: { _denyHandledByBoundary?: boolean };
+  _navContext?: { statusCode?: number; _denyHandledByBoundary?: boolean };
 }
 
 // ─── ALS-Backed Provider ─────────────────────────────────────────

package/src/client/state.ts

@@ -3,7 +3,7 @@
  *
  * ALL mutable module-level state that must have singleton semantics across
  * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,
- * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file
+ * use-segment-params.ts, use-search-params.ts, unload-guard.ts) import from this file
  * and re-export thin wrapper functions.
  *
  * Why: In Vite dev, a module is instantiated separately if reached via different
@@ -50,7 +50,7 @@ export function _setCurrentSsrData(data: SsrData | undefined): void {
   currentSsrData = data;
 }
 
-// ─── Route Params (from use-params.ts) ──────────────────────────────────────
+// ─── Route Params (from use-segment-params.ts) ──────────────────────────────────────
 
 /** Current route params snapshot — replaced (not mutated) on each navigation. */
 export let currentParams: Record<string, string | string[]> = {};

package/src/client/top-loader.tsx

@@ -3,11 +3,11 @@
  *
  * Shows an animated progress bar at the top of the viewport while an RSC
  * navigation is in flight. Injected automatically by the framework into
- * TransitionRoot — users never render this component directly.
+ * NavigationRoot — users never render this component directly.
  *
  * Configuration is via timber.config.ts `topLoader` key. Enabled by default.
  * Users who want a fully custom progress indicator disable the built-in one
- * (`topLoader: { enabled: false }`) and use `useNavigationPending()` directly.
+ * (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.
  *
  * Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
  * width over ~30s using ease-out timing. When navigation completes, the bar
@@ -21,14 +21,14 @@
  * stays invisible during the delay period. If navigation finishes before the
  * delay, the bar was never visible so the finish transition is also invisible.
  *
- * See design/19-client-navigation.md §"useNavigationPending()"
+ * See design/19-client-navigation.md §"usePendingNavigation()"
  * See LOCAL-336 for design decisions.
  */
 
 'use client';
 
 import { useState, createElement } from 'react';
-import { usePendingNavigationUrl } from './navigation-context.js';
+import { usePendingNavigation } from './use-pending-navigation.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -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;
 
@@ -97,7 +97,7 @@ function ensureKeyframes(): void {
 // ─── Component ───────────────────────────────────────────────────
 
 /**
- * Internal top-loader component. Injected by TransitionRoot.
+ * Internal top-loader component. Injected by NavigationRoot.
  *
  * Reads pending navigation state from PendingNavigationContext.
  * Phase transitions are derived synchronously during render:
@@ -111,8 +111,10 @@ function ensureKeyframes(): void {
  * (getDerivedStateFromProps pattern) or triggered by DOM events.
  */
 export function TopLoader({ config }: { config?: TopLoaderConfig }): React.ReactElement | null {
-  const pendingUrl = usePendingNavigationUrl();
-  const isPending = pendingUrl !== null;
+  // Read pending state from the router's external store via
+  // useSyncExternalStore (inside usePendingNavigation). Only this
+  // component re-renders when pending changes — no full-tree re-render.
+  const isPending = usePendingNavigation();
 
   const color = config?.color ?? DEFAULT_COLOR;
   const height = config?.height ?? DEFAULT_HEIGHT;

package/src/client/use-cookie.ts

@@ -9,7 +9,9 @@
  */
 
 import { useSyncExternalStore } from 'react';
+import { parseCookie, stringifySetCookie } from 'cookie';
 import { getSsrData } from './ssr-data.js';
+import { assertValidCookieName } from '../cookies/validation.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -38,26 +40,31 @@ type Listener = () => void;
 const listeners = new Map<string, Set<Listener>>();
 
 /** Parse a cookie name from document.cookie. */
-function getCookieValue(name: string): string | undefined {
+export function getCookieValue(name: string): string | undefined {
   if (typeof document === 'undefined') return undefined;
-  const match = document.cookie.match(
-    new RegExp('(?:^|;\\s*)' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\s*=\\s*([^;]*)')
-  );
-  return match ? decodeURIComponent(match[1]) : undefined;
+  const cookies = parseCookie(document.cookie);
+  return cookies[name];
 }
 
 /** Serialize options into a cookie string suffix. */
-function serializeOptions(options?: ClientCookieOptions): string {
+export function serializeOptions(options?: ClientCookieOptions): string {
   if (!options) return '; Path=/; SameSite=Lax';
-  const parts: string[] = [];
-  parts.push(`Path=${options.path ?? '/'}`);
-  if (options.domain) parts.push(`Domain=${options.domain}`);
-  if (options.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);
-  if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
   const sameSite = options.sameSite ?? 'lax';
-  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
-  if (options.secure) parts.push('Secure');
-  return '; ' + parts.join('; ');
+  // Build a Set-Cookie string via the cookie package, then strip the
+  // `__placeholder__=` name=value prefix to get just the attributes.
+  const full = stringifySetCookie({
+    name: '__placeholder__',
+    value: '',
+    path: options.path ?? '/',
+    domain: options.domain,
+    maxAge: options.maxAge,
+    expires: options.expires,
+    sameSite,
+    secure: options.secure,
+  });
+  // Strip everything up to and including the first "; "
+  const idx = full.indexOf('; ');
+  return idx >= 0 ? full.slice(idx) : '';
 }
 
 /** Notify all subscribers for a given cookie name. */
@@ -68,6 +75,17 @@ function notify(name: string): void {
   }
 }
 
+/**
+ * Notify useCookie subscribers that a cookie value changed.
+ * Called by defineCookie's imperative client .set()/.delete() methods
+ * so mounted useCookie() consumers re-render.
+ *
+ * @internal — framework use only
+ */
+export function notifyCookieChange(name: string): void {
+  notify(name);
+}
+
 // ─── Hook ─────────────────────────────────────────────────────────────────
 
 /**
@@ -99,12 +117,39 @@ export function useCookie(
   };
 
   const getSnapshot = (): string | undefined => getCookieValue(name);
-  const getServerSnapshot = (): string | undefined => getSsrData()?.cookies.get(name);
+  const getServerSnapshot = (): string | undefined => {
+    // During SSR, read the ALS-backed request cookies.
+    const ssrData = getSsrData();
+    if (ssrData) return ssrData.cookies.get(name);
+    // During client hydration there is no SSR data (it lives in the server's
+    // module graph), but React still calls getServerSnapshot. document.cookie
+    // holds the same cookies the server rendered with, so reading it here
+    // keeps the hydration render consistent with the server HTML.
+    // See design/29-cookies.md §"SSR Hydration".
+    return getCookieValue(name);
+  };
 
   const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 
+  // Validate the name once per hook instance — names are typically
+  // stable string literals, so this catches the bug at first render
+  // rather than on every write. Throws via `assertValidCookieName` with
+  // a precise error if the name violates RFC 7230 token rules.
+  assertValidCookieName(name);
+
   const setCookie: CookieSetter = (newValue: string, options?: ClientCookieOptions) => {
+    if (typeof newValue !== 'string') {
+      throw new Error(
+        `[timber] useCookie(${JSON.stringify(name)}): value must be a string, got ${typeof newValue}.\n` +
+          `  To store a JSON-serializable value, use defineCookie + jsonCookieCodec from\n` +
+          `  '@timber-js/app/cookies' and call its useCookie() hook instead.`
+      );
+    }
     const merged = { ...defaultOptions, ...options };
+    // Auto-encode mirrors the server's `cookies().set()` contract:
+    // values are URL-encoded on write, URL-decoded on read, so the
+    // logical bytes round-trip losslessly. See design/29-cookies.md
+    // §"Encoding Contract".
     document.cookie = `${name}=${encodeURIComponent(newValue)}${serializeOptions(merged)}`;
     notify(name);
   };

package/src/client/use-link-status.ts

@@ -1,26 +1,26 @@
 'use client';
 
-// useLinkStatus — returns { pending: true } while the nearest parent <Link>'s
+// useLinkStatus — returns { isPending: true } while the nearest parent <Link>'s
 // navigation is in flight. No arguments — scoped via React context.
 // See design/19-client-navigation.md §"useLinkStatus()"
 
 import { useContext, createContext } from 'react';
 
 export interface LinkStatus {
-  pending: boolean;
+  isPending: boolean;
 }
 
 /**
  * React context provided by <Link>. Holds the pending status
  * for that specific link's navigation.
  */
-export const LinkStatusContext = createContext<LinkStatus>({ pending: false });
+export const LinkStatusContext = createContext<LinkStatus>({ isPending: false });
 
 /**
- * Returns `{ pending: true }` while the nearest parent `<Link>` component's
+ * Returns `{ isPending: true }` while the nearest parent `<Link>` component's
  * navigation is in flight. Must be used inside a `<Link>` component's children.
  *
- * Unlike `useNavigationPending()` which is global, this hook is scoped to
+ * Unlike `usePendingNavigation()` which is global, this hook is scoped to
  * the nearest parent `<Link>` — only the link the user clicked shows pending.
  *
  * ```tsx
@@ -28,8 +28,8 @@ export const LinkStatusContext = createContext<LinkStatus>({ pending: false });
  * import { Link, useLinkStatus } from '@timber-js/app/client'
  *
  * function Hint() {
- *   const { pending } = useLinkStatus()
- *   return <span className={pending ? 'opacity-50' : ''} />
+ *   const { isPending } = useLinkStatus()
+ *   return <span className={isPending ? 'opacity-50' : ''} />
  * }
  *
  * export function NavLink({ href, children }) {

package/src/client/use-pathname.ts

@@ -31,6 +31,7 @@ export function usePathname(): string {
   // Try reading from NavigationContext (client-side, inside React tree).
   // During SSR, no NavigationProvider is mounted, so this returns null.
   try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path
     const navContext = useNavigationContext();
     if (navContext !== null) {
       return navContext.pathname;

package/src/client/use-pending-navigation.ts

@@ -0,0 +1,40 @@
+import { useSyncExternalStore } from 'react';
+import { getRouterOrNull } from './router-ref.js';
+
+function subscribe(onStoreChange: () => void): () => void {
+  const router = getRouterOrNull();
+  if (!router) return () => {};
+  return router.onPendingChange(onStoreChange);
+}
+
+function getSnapshot(): boolean {
+  const router = getRouterOrNull();
+  return router ? router.isPending() : false;
+}
+
+const getServerSnapshot = getSnapshot;
+
+/**
+ * Returns true while an RSC navigation is in flight.
+ *
+ * Reads from the router's external pending store via useSyncExternalStore.
+ * Only components that call this hook re-render when pending state
+ * changes — no full-tree re-render.
+ *
+ * ```tsx
+ * 'use client'
+ * import { usePendingNavigation } from '@timber-js/app/client'
+ *
+ * export function NavBar() {
+ *   const isPending = usePendingNavigation()
+ *   return (
+ *     <nav className={isPending ? 'opacity-50' : ''}>
+ *       <Link href="/dashboard">Dashboard</Link>
+ *     </nav>
+ *   )
+ * }
+ * ```
+ */
+export function usePendingNavigation(): boolean {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

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

@@ -17,24 +17,76 @@ import type {
   SearchParamsDefinition,
   SetParams,
   QueryStatesOptions,
-} from '#/search-params/create.js';
-import { getSearchParams } from '#/search-params/registry.js';
+} from '../search-params/define.js';
+import { getSearchParamsDefinition } from '../search-params/registry.js';
 
 // ─── Codec Bridge ─────────────────────────────────────────────────
 
+// nuqs's parser contract conflates values timber codecs distinguish:
+// parse() returning null means "unparseable, substitute defaultValue",
+// and undefined entries are skipped entirely. Timber codecs can
+// legitimately produce both — bare z.string() yields undefined for absent
+// params (implicit optionality), and a codec may map a present value to
+// null. Wrap those two values in sentinels across the nuqs boundary and
+// unwrap them before handing values back to the caller, so the client
+// hook returns exactly what server-side parse() returns.
+// Unique object references compared by identity — a codec can never
+// produce these from URL input, so user-controlled strings cannot collide
+// with them (unlike string sentinels), and unlike Symbols they survive
+// nuqs's internal string coercion without throwing.
+const NULL_SENTINEL: object = { timberSentinel: 'null' };
+const UNDEFINED_SENTINEL: object = { timberSentinel: 'undefined' };
+
+function wrapNuqsValue(value: unknown): unknown {
+  if (value === null) return NULL_SENTINEL;
+  if (value === undefined) return UNDEFINED_SENTINEL;
+  return value;
+}
+
+function unwrapNuqsValue(value: unknown): unknown {
+  if (value === NULL_SENTINEL) return null;
+  if (value === UNDEFINED_SENTINEL) return undefined;
+  return value;
+}
+
 /**
  * Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.
  *
  * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }
  * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }
+ *
+ * The defaultValue is computed eagerly. Codecs are documented to return a
+ * default rather than throw, but a throwing codec must not crash every
+ * component that mounts the hook — treat its default as undefined and let
+ * its error surface from server-side parse() instead.
  */
 function bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {
+  let defaultValue: unknown;
+  try {
+    defaultValue = codec.parse(undefined);
+  } catch {
+    defaultValue = undefined;
+  }
   return {
-    parse: (v: string) => codec.parse(v),
-    serialize: (v: T) => codec.serialize(v) ?? '',
-    defaultValue: codec.parse(undefined) as T,
-    eq: (a: T, b: T) => codec.serialize(a) === codec.serialize(b),
-  };
+    parse: (v: string) => wrapNuqsValue(codec.parse(v)),
+    serialize: (v: unknown) => {
+      const value = unwrapNuqsValue(v);
+      // Delegate null to the codec — some codecs encode null as a real
+      // query value. undefined has no encoding; nuqs requires a string.
+      return value === undefined ? '' : (codec.serialize(value as T) ?? '');
+    },
+    defaultValue: wrapNuqsValue(defaultValue),
+    eq: (a: unknown, b: unknown) => {
+      if (a === b) return true;
+      try {
+        return (
+          codec.serialize(unwrapNuqsValue(a) as T) === codec.serialize(unwrapNuqsValue(b) as T)
+        );
+      } catch {
+        return false;
+      }
+    },
+  } as SingleParser<T> & { defaultValue: T };
 }
 
 /**
@@ -79,7 +131,7 @@ export function useQueryStates<T extends Record<string, unknown>>(
   let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };
   let resolvedUrlKeys = urlKeys;
   if (typeof codecsOrRoute === 'string') {
-    const definition = getSearchParams(codecsOrRoute);
+    const definition = getSearchParamsDefinition(codecsOrRoute);
     if (!definition) {
       throw new Error(
         `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +
@@ -95,8 +147,14 @@ export function useQueryStates<T extends Record<string, unknown>>(
 
   const bridged = bridgeCodecs(codecs);
 
+  // Forward hook-level options (shallow, scroll, history) to nuqs.
+  // These become the default for all setter calls from this hook instance.
+  // Per-call options in setParams(values, opts) override these defaults.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const nuqsOptions: any = {};
+  if (_options?.shallow !== undefined) nuqsOptions.shallow = _options.shallow;
+  if (_options?.scroll !== undefined) nuqsOptions.scroll = _options.scroll;
+  if (_options?.history !== undefined) nuqsOptions.history = _options.history;
   if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {
     nuqsOptions.urlKeys = resolvedUrlKeys;
   }
@@ -118,6 +176,19 @@ export function useQueryStates<T extends Record<string, unknown>>(
     throw err;
   }
 
+  // Unwrap the null/undefined sentinels the bridge injected (see Codec
+  // Bridge above) so callers see exactly what server-side parse() returns.
+  // Copy-on-write preserves the identity of nuqs's memoized values object
+  // when nothing needs unwrapping.
+  let normalized = values;
+  for (const key of Object.keys(bridged)) {
+    const value = normalized[key];
+    if (value === NULL_SENTINEL || value === UNDEFINED_SENTINEL) {
+      if (normalized === values) normalized = { ...values };
+      normalized[key] = unwrapNuqsValue(value);
+    }
+  }
+
   // Wrap the nuqs setter to match timber's SetParams<T> signature.
   // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.
   // timber's setter accepts Partial<T> with optional SetParamsOptions.
@@ -126,11 +197,38 @@ export function useQueryStates<T extends Record<string, unknown>>(
     if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;
     if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;
     if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;
+    // nuqs's update loop skips undefined entries and treats null as a
+    // key deletion before serialize runs. Timber semantics:
+    //   - setParams({ q: undefined }) must clear ?q= (absent = undefined),
+    //     so explicit undefined maps to a null deletion.
+    //   - setParams({ q: null }) clears the key only when the codec encodes
+    //     null as "omit" (serialize(null) === null). If the codec encodes
+    //     null as a real query value, forward the sentinel so the bridged
+    //     serialize writes it — matching definition.serialize({ q: null }).
+    let forwarded: Record<string, unknown> = partial;
+    for (const key of Object.keys(partial)) {
+      const value = partial[key as keyof T];
+      if (value === undefined) {
+        if (forwarded === partial) forwarded = { ...partial };
+        forwarded[key] = null;
+      } else if (value === null) {
+        let encoded: string | null = null;
+        try {
+          encoded = codecs[key as keyof T]?.serialize(null as T[keyof T]) ?? null;
+        } catch {
+          // Codec can't serialize null — treat as a deletion.
+        }
+        if (encoded !== null) {
+          if (forwarded === partial) forwarded = { ...partial };
+          forwarded[key] = NULL_SENTINEL;
+        }
+      }
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    void setValues(partial as any, nuqsSetOptions);
+    void setValues(forwarded as any, nuqsSetOptions);
   };
 
-  return [values as T, setParams];
+  return [normalized as T, setParams];
 }
 
 // ─── Definition binding ───────────────────────────────────────────

package/src/client/use-router.ts

@@ -20,10 +20,11 @@
  *
  * For loading UI during navigation, use:
  * - useLinkStatus()          — per-link pending indicator (inside <Link>)
- * - useNavigationPending()   — global navigation pending state
+ * - usePendingNavigation()   — global navigation pending state
  */
 
 import { getRouterOrNull } from './router-ref.js';
+import { validateNavigationHref } from '../shared/href-validation.js';
 
 export interface AppRouterInstance {
   /** Navigate to a URL, pushing a new history entry */
@@ -60,6 +61,7 @@ export interface AppRouterInstance {
 export function useRouter(): AppRouterInstance {
   return {
     push(href: string, options?: { scroll?: boolean }) {
+      validateNavigationHref(href);
       const router = getRouterOrNull();
       if (!router) {
         if (process.env.NODE_ENV === 'development') {
@@ -72,6 +74,7 @@ export function useRouter(): AppRouterInstance {
       void router.navigate(href, { scroll: options?.scroll });
     },
     replace(href: string, options?: { scroll?: boolean }) {
+      validateNavigationHref(href);
       const router = getRouterOrNull();
       if (!router) {
         if (process.env.NODE_ENV === 'development') {

package/src/client/use-search-params.ts

@@ -4,9 +4,17 @@
  * Returns a read-only URLSearchParams instance reflecting the current
  * URL's query string. Updates when client-side navigation changes the URL.
  *
- * This is a thin wrapper over window.location.search, provided for
- * Next.js API compatibility (libraries like nuqs import useSearchParams
- * from next/navigation).
+ * On the client, reads from NavigationContext which is updated atomically
+ * with the RSC tree render during full navigations, AND by
+ * syncShallowSearch() for shallow URL updates (nuqs shallow: true,
+ * replaceUrl, or any external pushState/replaceState that changes the
+ * query string). See router-init.ts.
+ *
+ * This replaces the previous useSyncExternalStore approach which read
+ * window.location.search directly — causing React to detect external
+ * store tearing during transitions and fall back to synchronous rendering
+ * (renderRootSync instead of renderRootConcurrent), blocking the main
+ * thread and freezing animations.
  *
  * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
  * URLSearchParams. Mutation methods (set, delete, append) work on the
@@ -15,42 +23,14 @@
  * During SSR, reads the request search params from the SSR ALS context
  * (populated by ssr-entry.ts) instead of window.location.
  *
- * All mutable state is delegated to client/state.ts for singleton guarantees.
- * See design/18-build-system.md §"Singleton State Registry"
+ * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 
-import { useSyncExternalStore } from 'react';
 import { getSsrData } from './ssr-data.js';
+import { useNavigationContext } from './navigation-context.js';
 import { cachedSearch, cachedSearchParams, _setCachedSearch } from './state.js';
 
-function getSearch(): 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}` : '';
-}
-
-function getServerSearch(): string {
-  const data = getSsrData();
-  if (!data) return '';
-  const sp = new URLSearchParams(data.searchParams);
-  const str = sp.toString();
-  return str ? `?${str}` : '';
-}
-
-function subscribe(callback: () => void): () => void {
-  window.addEventListener('popstate', callback);
-  return () => window.removeEventListener('popstate', callback);
-}
-
-// Cache the last search string and its parsed URLSearchParams to avoid
-// creating a new object on every render when the URL hasn't changed.
-// State lives in client/state.ts for singleton guarantees.
-
-function getSearchParams(): URLSearchParams {
-  const search = getSearch();
+function getSearchParams(search: string): URLSearchParams {
   if (search !== cachedSearch) {
     const params = new URLSearchParams(search);
     _setCachedSearch(search, params);
@@ -59,20 +39,27 @@ function getSearchParams(): URLSearchParams {
   return cachedSearchParams;
 }
 
-function getServerSearchParams(): URLSearchParams {
-  const data = getSsrData();
-  return data ? new URLSearchParams(data.searchParams) : new URLSearchParams();
-}
-
 /**
  * Read the current URL search params.
  *
  * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 export function useSearchParams(): URLSearchParams {
-  // useSyncExternalStore needs a primitive snapshot for comparison.
-  // We use the raw search string as the snapshot, then return the
-  // parsed URLSearchParams.
-  useSyncExternalStore(subscribe, getSearch, getServerSearch);
-  return typeof window !== 'undefined' ? getSearchParams() : getServerSearchParams();
+  try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks -- conditional on environment, not render path
+    const navContext = useNavigationContext();
+    if (navContext !== null) {
+      return getSearchParams(navContext.search);
+    }
+  } catch {
+    // No React dispatcher available (called outside a component).
+  }
+
+  // SSR path: read from ALS-backed SSR data context.
+  const ssrData = getSsrData();
+  if (ssrData) return new URLSearchParams(ssrData.searchParams);
+
+  // Final fallback: window.location (tests, edge cases).
+  if (typeof window !== 'undefined') return getSearchParams(window.location.search);
+  return new URLSearchParams();
 }