@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

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

@@ -11,30 +11,156 @@
 'use client';
 
 import { useQueryStates as nuqsUseQueryStates } from 'nuqs';
-import type { SingleParser } from 'nuqs';
+import type { MultiParser } from 'nuqs';
 import type {
   SearchParamCodec,
   SearchParamsDefinition,
   SetParams,
   QueryStatesOptions,
-} from '#/search-params/create.js';
-import { getSearchParams } from '#/search-params/registry.js';
+} from '../search-params/define.ts';
+import { parseTotal } from '../search-params/parse-total.ts';
+import { serializedEqual } from '../search-params/serialize-equal.ts';
 
 // ─── 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.
+ * Bridge a timber SearchParamCodec to a nuqs-compatible MultiParser.
  *
  * 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, through `parseTotal` — the same
+ * entry point server-side `parse()` uses, so the hook and the server agree
+ * on what an absent param means (a bare nuqs parser answers `null`, not
+ * `undefined`; TIM-1350). 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.
+ *
+ * A `null` absent-value is NOT registered as the nuqs default. nuqs
+ * already represents an absent key as `null`, so the hook reads the same
+ * value either way — but registering it makes `clearOnDefault` fire on
+ * `setParams({ q: null })` and delete the key before the bridged
+ * `serialize` runs. For a codec that encodes `null` as a real query value
+ * (`serialize(null) === 'none'`), that silently disagrees with
+ * `buildSearchParams({ q: null })`, which writes it. Same reasoning as
+ * `getDefaultSerialized` on the server: a codec with no value for an
+ * absent param has no default to register.
  */
-function bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {
-  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),
-  };
+function bridgeCodec<T>(codec: SearchParamCodec<T>): MultiParser<T> & { defaultValue: T } {
+  let absent: unknown;
+  try {
+    absent = parseTotal(codec, undefined);
+  } catch {
+    absent = undefined;
+  }
+
+  const parser = {
+    // `multi`, so nuqs reads the key with `searchParams.getAll()` and hands
+    // us EVERY value. A single parser reads `.get()` — the first value only
+    // — which is not the domain a timber codec is defined over. The server
+    // parses `?tags=a&tags=b` as `['a','b']`; a single parser made the hook
+    // answer `['a']` for the same URL, under a declared `string[]` that
+    // admitted no such disagreement (TIM-1352). Scalar codecs are unaffected:
+    // they receive the array and take `value[0]`, exactly as they do on the
+    // server, so first-value-wins is preserved through the same code path
+    // rather than through nuqs's reader.
+    //
+    // nuqs never calls this with an empty array — `isAbsentFromUrl` treats
+    // `[]` as absent and answers `defaultValue` directly — which is what
+    // keeps the absent case agreeing with the server's `undefined`.
+    //
+    // Reading every value is only half of it: the values must arrive in the
+    // SAME SHAPE the server would have produced, or the divergence just
+    // moves. `normalizeRaw` (search-params/define.ts) collapses a
+    // single-valued key to a bare string and keeps an array only for a
+    // repeated one, so this mirrors that rule exactly. Handing a codec
+    // `['3']` where the server hands it `'3'` breaks every codec whose
+    // `parse` is written for the scalar case — which is most hand-written
+    // ones, contract or no contract.
+    type: 'multi' as const,
+    // Through parseTotal, not codec.parse. nuqs's own `.withDefault(d)`
+    // overrides ONLY `parseServerSide`, so `parseAsInteger.withDefault(1)`
+    // on `?page=abc` returned 1 from the server and null from the hook —
+    // a divergence the declared non-nullable `number` did not admit.
+    parse: (v: readonly string[]) =>
+      wrapNuqsValue(parseTotal(codec, v.length === 1 ? v[0] : [...v])),
+    serialize: (v: unknown) => {
+      const value = unwrapNuqsValue(v);
+      if (value === undefined) return [''];
+      // TIM-1354: catch TypeError from codecs whose serialize is not total
+      // over null (e.g. parseAsIsoDate.serialize(null) → null.toISOString()).
+      // Only TypeError — deliberate signals must not be swallowed.
+      let result: string | string[] | null;
+      try {
+        result = codec.serialize(value as T);
+      } catch (error) {
+        if (error instanceof TypeError) return [''];
+        throw error;
+      }
+      // TIM-1353: pass through string[] from codecs that emit repeated
+      // keys. nuqs multi parsers append one key=value per array element.
+      if (Array.isArray(result)) return result;
+      return [result ?? ''];
+    },
+    eq: (a: unknown, b: unknown) => {
+      if (a === b) return true;
+      try {
+        return serializedEqual(
+          codec.serialize(unwrapNuqsValue(a) as T),
+          codec.serialize(unwrapNuqsValue(b) as T)
+        );
+      } catch {
+        return false;
+      }
+    },
+  } as MultiParser<T> & { defaultValue: T };
+
+  if (absent !== null) parser.defaultValue = wrapNuqsValue(absent) as T;
+  return parser;
+}
+
+/**
+ * Collect `withUrlKey` aliases off a codec map.
+ *
+ * `withUrlKey(codec, 'q')` returns a codec carrying `urlKey: 'q'`, so the map
+ * alone is enough to reconstruct the aliases — `defineSearchParams` builds its
+ * own `urlKeys` from exactly this property.
+ */
+function deriveUrlKeys(codecs: Record<string, SearchParamCodec<unknown>>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const key of Object.keys(codecs)) {
+    const alias = codecs[key]?.urlKey;
+    if (alias) result[key] = alias;
+  }
+  return result;
 }
 
 /**
@@ -43,12 +169,12 @@ function bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { default
 function bridgeCodecs<T extends Record<string, unknown>>(codecs: {
   [K in keyof T]: SearchParamCodec<T[K]>;
 }) {
-  const result: Record<string, SingleParser<unknown> & { defaultValue: unknown }> = {};
+  const result: Record<string, MultiParser<unknown> & { defaultValue: unknown }> = {};
   for (const key of Object.keys(codecs)) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     result[key] = bridgeCodec(codecs[key as keyof T]) as any;
   }
-  return result as { [K in keyof T]: SingleParser<T[K]> & { defaultValue: T[K] } };
+  return result as { [K in keyof T]: MultiParser<T[K]> & { defaultValue: T[K] } };
 }
 
 // ─── Hook ─────────────────────────────────────────────────────────
@@ -61,7 +187,7 @@ function bridgeCodecs<T extends Record<string, unknown>>(codecs: {
  *
  * Usage:
  * ```ts
- * // Via a SearchParamsDefinition
+ * // Via a SearchParamsDefinition imported from the route's params.ts
  * const [params, setParams] = definition.useQueryStates()
  *
  * // Standalone with inline codecs
@@ -69,35 +195,37 @@ function bridgeCodecs<T extends Record<string, unknown>>(codecs: {
  *   page: fromSchema(z.coerce.number().int().min(1).default(1)),
  * })
  * ```
+ *
+ * There is deliberately no route-string form (`useQueryStates('/products')`).
+ * Importing the definition from `params.ts` is the documented way to reach
+ * another route's codecs — it needs no runtime registry lookup and so has no
+ * "not registered yet" failure mode. See design/23-search-params.md
+ * §"Client Access".
  */
 export function useQueryStates<T extends Record<string, unknown>>(
-  codecsOrRoute: { [K in keyof T]: SearchParamCodec<T[K]> } | string,
+  codecs: { [K in keyof T]: SearchParamCodec<T[K]> },
   _options?: QueryStatesOptions,
   urlKeys?: Readonly<Record<string, string>>
 ): [T, SetParams<T>] {
-  // Route-string overload: resolve codecs from the registry
-  let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };
-  let resolvedUrlKeys = urlKeys;
-  if (typeof codecsOrRoute === 'string') {
-    const definition = getSearchParams(codecsOrRoute);
-    if (!definition) {
-      throw new Error(
-        `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +
-          `Either the route has no search-params.ts file, or it hasn't been loaded yet. ` +
-          `For cross-route usage, import the definition explicitly.`
-      );
-    }
-    codecs = definition.codecs as { [K in keyof T]: SearchParamCodec<T[K]> };
-    resolvedUrlKeys = definition.urlKeys;
-  } else {
-    codecs = codecsOrRoute;
-  }
-
   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 (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {
+  if (_options?.shallow !== undefined) nuqsOptions.shallow = _options.shallow;
+  if (_options?.scroll !== undefined) nuqsOptions.scroll = _options.scroll;
+  if (_options?.history !== undefined) nuqsOptions.history = _options.history;
+  // `withUrlKey` attaches the alias to the codec itself — that is the design's
+  // "URL keys travel with codecs" principle — so the aliases are derivable
+  // here and must be, for the inline codec-map form: nobody passes `urlKeys`
+  // on that path, and without this an aliased bundle silently read and wrote
+  // the property name instead of the alias. `bindUseQueryStates` still passes
+  // the definition's precomputed map, which wins on conflict; it is built from
+  // these same codecs, so the two agree by construction rather than by luck.
+  const resolvedUrlKeys = { ...deriveUrlKeys(codecs), ...urlKeys };
+  if (Object.keys(resolvedUrlKeys).length > 0) {
     nuqsOptions.urlKeys = resolvedUrlKeys;
   }
 
@@ -118,6 +246,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 +267,40 @@ 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 | string[] | null = null;
+        try {
+          const raw = codecs[key as keyof T]?.serialize(null as T[keyof T]);
+          // string[] is non-null, but an empty array carries no value
+          encoded = raw === null ? null : Array.isArray(raw) ? (raw.length > 0 ? raw : null) : raw;
+        } 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

@@ -14,22 +14,35 @@
  * In timber, navigation calls reactRoot.render() which is a root-level
  * render — startTransition has no effect on root renders.
  *
- * Navigation state (params, pathname) is delivered atomically via
+ * Navigation state (pathname, search) is delivered atomically via
  * NavigationContext embedded in the element tree passed to
  * reactRoot.render(). See design/19-client-navigation.md §"NavigationContext".
  *
  * 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 { getRouterOrNull } from './router-ref.ts';
+import { validateNavigationHref } from '../shared/href-validation.ts';
+
+/** Options for `push` and `replace`. */
+export interface NavigateOptions {
+  /** Set to false to keep the scroll position instead of scrolling to top. */
+  scroll?: boolean;
+  /**
+   * View transition types to add to this navigation, beside the router's own
+   * `navigation-forward`. See `NavigationOptions.transitionTypes` — they must
+   * go here rather than in a `startTransition` around the call.
+   */
+  transitionTypes?: readonly string[];
+}
 
 export interface AppRouterInstance {
   /** Navigate to a URL, pushing a new history entry */
-  push(href: string, options?: { scroll?: boolean }): void;
+  push(href: string, options?: NavigateOptions): void;
   /** Navigate to a URL, replacing the current history entry */
-  replace(href: string, options?: { scroll?: boolean }): void;
+  replace(href: string, options?: NavigateOptions): void;
   /** Refresh the current page (re-fetch RSC payload) */
   refresh(): void;
   /** Navigate back in history */
@@ -59,7 +72,8 @@ export interface AppRouterInstance {
  */
 export function useRouter(): AppRouterInstance {
   return {
-    push(href: string, options?: { scroll?: boolean }) {
+    push(href: string, options?: NavigateOptions) {
+      validateNavigationHref(href);
       const router = getRouterOrNull();
       if (!router) {
         if (process.env.NODE_ENV === 'development') {
@@ -69,9 +83,13 @@ export function useRouter(): AppRouterInstance {
         }
         return;
       }
-      void router.navigate(href, { scroll: options?.scroll });
+      void router.navigate(href, {
+        scroll: options?.scroll,
+        transitionTypes: options?.transitionTypes,
+      });
     },
-    replace(href: string, options?: { scroll?: boolean }) {
+    replace(href: string, options?: NavigateOptions) {
+      validateNavigationHref(href);
       const router = getRouterOrNull();
       if (!router) {
         if (process.env.NODE_ENV === 'development') {
@@ -79,7 +97,11 @@ export function useRouter(): AppRouterInstance {
         }
         return;
       }
-      void router.navigate(href, { scroll: options?.scroll, replace: true });
+      void router.navigate(href, {
+        scroll: options?.scroll,
+        replace: true,
+        transitionTypes: options?.transitionTypes,
+      });
     },
     refresh() {
       const router = getRouterOrNull();

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

@@ -4,53 +4,31 @@
  * 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).
+ * One unconditional read of NavigationContext, on every side (TIM-1425):
+ *
+ * - In the browser, the provider is updated atomically with the RSC tree
+ *   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.
+ * - During SSR, the wrapper chain mounts the same provider carrying the
+ *   request's RAW query string (TIM-1424), so repeated keys
+ *   (`?tag=a&tag=b`) survive — the collapsed record the ALS context holds
+ *   cannot represent them.
+ * - In the RSC environment, this module is never evaluated — the shims plugin
+ *   resolves next/navigation to navigation-rsc.ts (TIM-1420).
  *
  * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
  * URLSearchParams. Mutation methods (set, delete, append) work on the
  * local copy but do NOT affect the URL — use the router or nuqs for that.
  *
- * 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 { 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}` : '';
-}
+import { getSsrData } from './ssr-data.ts';
+import { useNavigationContext } from './navigation-context.ts';
+import { cachedSearch, cachedSearchParams, _setCachedSearch } from './state.ts';
 
-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 +37,31 @@ 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.
  *
+ * Throws when no NavigationProvider is above the caller.
+ *
  * 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();
+  const nav = useNavigationContext();
+  if (nav === null) {
+    throw new Error(
+      '[timber] useSearchParams() was called outside the timber app tree ' +
+        '(no NavigationProvider found). In tests, render the component ' +
+        'inside the timber providers.'
+    );
+  }
+  // On the server, return a fresh instance per call. The module-level cache
+  // below exists to give client code stable identity for effect deps; on the
+  // server it would be shared mutable state across concurrent requests
+  // (design/13-security.md, "no global fallback state"). Both halves of the
+  // check matter: `window` is absent in a plain Node SSR render, and
+  // getSsrData() catches SSR environments that do define `window` (handleSsr
+  // always runs inside the ALS scope). Pinned by tests/ssr-provider-hooks.test.ts.
+  if (typeof window === 'undefined' || getSsrData()) {
+    return new URLSearchParams(nav.search);
+  }
+  return getSearchParams(nav.search);
 }

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

@@ -0,0 +1,69 @@
+/**
+ * useParams() — client-side hook for accessing route params.
+ *
+ * Returns the dynamic route parameters for the current URL.
+ * When called with a route pattern argument, TypeScript narrows
+ * the return type to the exact params shape for that route.
+ *
+ * Two layers of type narrowing work together:
+ * 1. The generic overload here uses the Routes interface directly —
+ *    `useParams<R>()` returns `Routes[R]['segmentParams']`.
+ * 2. Build-time codegen generates per-route string-literal overloads
+ *    in the .d.ts file for IDE autocomplete (see routing/codegen.ts).
+ *
+ * When the Routes interface is empty (no codegen yet), the generic
+ * overload has `keyof Routes = never`, so only the fallback matches.
+ *
+ * One unconditional read of ParamsContext, on every side (TIM-1425):
+ *
+ * - In the browser, `PayloadRoot` publishes the payload's params above the
+ *   merge point on every render path. Params update atomically with the RSC
+ *   tree — no timing gap (TIM-1294, TIM-1297).
+ * - During SSR, the wrapper chain mounts the same `PayloadRoot`, fed the
+ *   `params` half of `splitPayloadRoot(root)` — the identical derivation
+ *   the browser performs at hydration (TIM-1424).
+ * - In the RSC environment, this module is never evaluated — the shims plugin
+ *   resolves next/navigation to navigation-rsc.ts (TIM-1420).
+ * - Called outside a component entirely, React itself throws its
+ *   invalid-hook-call error.
+ *
+ * The module-level subscribe/notify machinery and the `currentParams`
+ * snapshot that used to back a fourth fallback tier are gone (TIM-1425):
+ * the provider is unconditional on every render path, so nothing read them.
+ *
+ * Design doc: design/09-typescript.md §"Typed Routes"
+ */
+
+import type { CoercedParams } from '../shared/param-value.ts';
+import type { Routes } from '../index.ts';
+import { resolveSegmentParams } from '../shared/slot-params.ts';
+import { useParamsContext } from './params-context.ts';
+
+/**
+ * Read the current route's dynamic params.
+ *
+ * The optional `_route` argument exists only for TypeScript narrowing —
+ * it does not affect the runtime return value.
+ *
+ * Throws when no `PayloadRoot` is above the caller (a component rendered
+ * outside the timber app — in tests, render inside the timber providers).
+ *
+ * @overload Typed — when a known segment path is passed, returns the
+ *   exact params shape from the generated Routes interface.
+ * @overload Fallback — returns the generic params record.
+ */
+export function useSegmentParams<R extends keyof Routes>(
+  segmentPath: R
+): Routes[R] extends { segmentParams: infer P } ? P : CoercedParams;
+export function useSegmentParams(segmentPath?: string): CoercedParams;
+export function useSegmentParams(segmentPath?: string): CoercedParams {
+  const paramsContext = useParamsContext();
+  if (paramsContext === null) {
+    throw new Error(
+      '[timber] useSegmentParams() was called outside the timber app tree ' +
+        '(no params provider found). In tests, render the component inside ' +
+        'the timber providers.'
+    );
+  }
+  return resolveSegmentParams(paramsContext.params, paramsContext.slotParams, segmentPath);
+}

package/src/client/use-selected-layout-segment.ts

@@ -22,8 +22,8 @@
 
 'use client';
 
-import { useSegmentContext } from './segment-context.js';
-import { usePathname } from './use-pathname.js';
+import { useSegmentContext } from './segment-context.ts';
+import { usePathname } from './use-pathname.ts';
 
 /**
  * Split a pathname into URL segments.