@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

package/src/{search-params/codecs.ts → schema-bridge.ts}

@@ -1,11 +1,21 @@
 /**
- * Built-in codecs and the fromSchema bridge for Standard Schema-compatible
- * validation libraries (Zod, Valibot, ArkType).
+ * Standard Schema bridge — shared helpers for bridging Standard Schema-compatible
+ * validation libraries (Zod, Valibot, ArkType) to the Codec<T> protocol.
  *
- * Design doc: design/09-typescript.md §"The SearchParamCodec Protocol"
+ * This module is the single source of truth for:
+ * - StandardSchemaV1 interface (subset of the Standard Schema spec)
+ * - validateSync() helper
+ * - fromSchema() — bridge from Standard Schema to Codec<T>
+ * - fromArraySchema() — bridge for array-valued codecs
+ *
+ * These are re-exported from @timber-js/app/search-params, @timber-js/app/segment-params,
+ * and @timber-js/app/cookies for convenience. The canonical import is
+ * @timber-js/app/codec.
+ *
+ * Design doc: design/23a-search-params-triage.md §"Unify Codec<T> type"
  */
 
-import type { SearchParamCodec } from './create.js';
+import type { Codec } from './codec.js';
 
 // ---------------------------------------------------------------------------
 // Standard Schema interface (subset)
@@ -15,13 +25,14 @@ import type { SearchParamCodec } from './create.js';
 // We depend only on `~standard.validate` to avoid coupling to any specific lib.
 // ---------------------------------------------------------------------------
 
-interface StandardSchemaV1<Output = unknown> {
+/** Minimal Standard Schema interface for auto-detection. */
+export interface StandardSchemaV1<Output = unknown> {
   '~standard': {
     validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
   };
 }
 
-type StandardSchemaResult<Output> =
+export type StandardSchemaResult<Output> =
   | { value: Output; issues?: undefined }
   | { value?: undefined; issues: ReadonlyArray<{ message: string }> };
 
@@ -30,50 +41,77 @@ type StandardSchemaResult<Output> =
 // ---------------------------------------------------------------------------
 
 /**
- * Zod v4's ~standard.validate() signature includes Promise in the return union
- * to satisfy the Standard Schema spec, but in practice Zod always validates
- * synchronously for the schema types we use. We assert the result is sync and
- * throw if it isn't — search params parsing must be synchronous.
+ * Run a Standard Schema's `~standard.validate()` synchronously.
+ *
+ * Zod v4's signature includes `Promise` in the return union to satisfy the
+ * Standard Schema spec, but in practice Zod always validates synchronously
+ * for the schema types we use. We assert the result is sync and throw if
+ * it isn't — codec parsing must be synchronous.
  */
-function validateSync<Output>(
+export function validateSync<Output>(
   schema: StandardSchemaV1<Output>,
   value: unknown
 ): StandardSchemaResult<Output> {
   const result = schema['~standard'].validate(value);
   if (result instanceof Promise) {
     throw new Error(
-      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported for search params.'
+      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported.'
     );
   }
   return result;
 }
 
 // ---------------------------------------------------------------------------
-// fromSchema — bridge from Standard Schema to SearchParamCodec
+// Type guards
+// ---------------------------------------------------------------------------
+
+/** Check if a value is a Standard Schema object. */
+export function isStandardSchema(value: unknown): value is StandardSchemaV1 {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '~standard' in value &&
+    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'
+  );
+}
+
+/** Check if a value is a Codec (has parse + serialize methods). */
+export function isCodec(value: unknown): value is Codec<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Codec<unknown>).parse === 'function' &&
+    typeof (value as Codec<unknown>).serialize === 'function'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// fromSchema — bridge from Standard Schema to Codec<T>
 // ---------------------------------------------------------------------------
 
 /**
  * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
- * SearchParamCodec.
+ * Codec<T>.
  *
- * Parse: coerces the raw URL string through the schema. On validation failure,
+ * Parse: coerces the raw string through the schema. On validation failure,
  * parses `undefined` to get the schema's default value (the schema should have
  * a `.default()` call). If that also fails, returns `undefined`.
  *
  * Serialize: uses `String()` for primitives, `null` for null/undefined.
  *
  * ```ts
- * import { fromSchema } from '@timber-js/app/search-params'
+ * import { fromSchema } from '@timber-js/app/codec'
  * import { z } from 'zod/v4'
  *
  * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
  * ```
  */
-export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {
+export function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
   return {
     parse(value: string | string[] | undefined): T {
-      // For array inputs, take the last value (consistent with URLSearchParams.get())
-      const input = Array.isArray(value) ? value[value.length - 1] : value;
+      // For array inputs (duplicate query keys), use the first value.
+      // Browsers and URLSearchParams.get() return the first occurrence.
+      const input = Array.isArray(value) ? value[0] : value;
 
       // Try parsing the raw value
       const result = validateSync(schema, input);
@@ -101,7 +139,7 @@ export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T>
 }
 
 // ---------------------------------------------------------------------------
-// fromArraySchema — bridge for array-valued search params
+// fromArraySchema — bridge for array-valued codecs
 // ---------------------------------------------------------------------------
 
 /**
@@ -109,13 +147,13 @@ export function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T>
  * and repeated query keys (`?tag=a&tag=b`).
  *
  * ```ts
- * import { fromArraySchema } from '@timber-js/app/search-params'
+ * import { fromArraySchema } from '@timber-js/app/codec'
  * import { z } from 'zod/v4'
  *
  * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
  * ```
  */
-export function fromArraySchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {
+export function fromArraySchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
   return {
     parse(value: string | string[] | undefined): T {
       // Coerce single string to array for array schemas

package/src/search-params/define.ts

@@ -0,0 +1,538 @@
+/**
+ * defineSearchParams — factory for SearchParamsDefinition<T>.
+ *
+ * Creates a typed, composable definition for a route's search parameters.
+ * Accepts both SearchParamCodec values and Standard Schema objects (Zod,
+ * Valibot, ArkType) with auto-detection. Supports URL key aliasing via
+ * withUrlKey(), default-omission serialization, and composition via
+ * .extend() / .pick().
+ *
+ * Design doc: design/23-search-params.md §"defineSearchParams — The Factory"
+ */
+
+import { useQueryStates as clientUseQueryStates } from '../client/use-query-states.js';
+import { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+import type { Codec } from '../codec.js';
+
+// Server-only reference for .get() — avoids pulling server ALS into client bundles.
+// In client environments, .get() throws before reaching this code path.
+//
+// IMPORTANT: This is set eagerly via _setGetSearchParamsFn() at server startup
+// (called from request-context.ts module initialization). It must NOT use
+// dynamic `await import()` at call time because the async microtask from the
+// dynamic import loses AsyncLocalStorage context in React's RSC Flight renderer,
+// breaking getSearchParams() in parallel slot pages. See TIM-523.
+let _getSearchParamsFn: (() => URLSearchParams) | undefined;
+
+/**
+ * Register the getSearchParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export function _setGetSearchParamsFn(fn: () => URLSearchParams): void {
+  _getSearchParamsFn = fn;
+}
+
+function getSearchParamsFromAls(): URLSearchParams {
+  if (!_getSearchParamsFn) {
+    throw new Error(
+      '[timber] searchParams.get() is only available on the server. ' +
+        'Use searchParams.useQueryStates() on the client.'
+    );
+  }
+  return _getSearchParamsFn();
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A codec that converts between URL string values and typed values.
+ *
+ * nuqs parsers implement this interface natively — no adapter needed.
+ * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected
+ * by defineSearchParams and wrapped via fromSchema.
+ */
+export interface SearchParamCodec<T> extends Codec<T> {
+  /** Optional URL key alias, set by withUrlKey(). */
+  urlKey?: string;
+}
+
+/** A codec with a URL key alias attached via withUrlKey(). */
+export interface SearchParamCodecWithUrlKey<T> extends SearchParamCodec<T> {
+  urlKey: string;
+}
+
+/** Infer the output type of a codec. */
+export type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;
+
+/** Map of property names to codecs. */
+export type CodecMap<T extends Record<string, unknown>> = {
+  [K in keyof T]: SearchParamCodec<T[K]>;
+};
+
+/** Options for useQueryStates setter. */
+export interface SetParamsOptions {
+  /** Update URL without server roundtrip (default: false). */
+  shallow?: boolean;
+  /** Scroll to top after update (default: true). */
+  scroll?: boolean;
+  /** 'push' (default) or 'replace' for history state. */
+  history?: 'push' | 'replace';
+}
+
+/** Setter function returned by useQueryStates. */
+export type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;
+
+/** Options for useQueryStates hook. */
+export interface QueryStatesOptions {
+  /** Update URL without server roundtrip (default: false). */
+  shallow?: boolean;
+  /** Scroll to top after update (default: true). */
+  scroll?: boolean;
+  /** 'push' (default) or 'replace' for history state. */
+  history?: 'push' | 'replace';
+}
+
+/**
+ * A fully typed, composable search params definition.
+ *
+ * Returned by defineSearchParams(). Carries a phantom _type property
+ * for build-time type extraction.
+ */
+export interface SearchParamsDefinition<T extends Record<string, unknown>> {
+  /** Parse raw URL search params into typed values. */
+  parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;
+  /** Parse a Promise of URLSearchParams (e.g., from the ALS `searchParams()` API). */
+  parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;
+
+  /**
+   * Get typed search params from the current request context (ALS-backed).
+   *
+   * Server-only, sync. Reads getSearchParams() from ALS and parses through codecs.
+   * Throws on client.
+   *
+   * ```tsx
+   * // app/products/page.tsx
+   * import { searchParams } from './params'
+   * export default function Page() {
+   *   const { page, category } = searchParams.get()
+   * }
+   * ```
+   */
+  get(): T;
+
+  /** Client hook — reads current URL params and returns typed values + setter. */
+  useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];
+
+  /** Extend with additional codecs or Standard Schema objects. */
+  extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(
+    codecs: U
+  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }>;
+
+  /** Pick a subset of keys. Preserves codecs and aliases. */
+  pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;
+
+  /** Serialize values to a query string (no leading '?'), omitting defaults. */
+  serialize(values: Partial<T>): string;
+
+  /** Build a full path with query string, omitting defaults. */
+  href(pathname: string, values: Partial<T>): string;
+
+  /** Build a URLSearchParams instance, omitting defaults. */
+  toSearchParams(values: Partial<T>): URLSearchParams;
+
+  /** Read-only codec map for spreading into .extend(). */
+  codecs: { [K in keyof T]: SearchParamCodec<T[K]> };
+
+  /** Read-only URL key alias map. Maps property names to URL query parameter keys. */
+  readonly urlKeys: Readonly<Record<string, string>>;
+
+  /**
+   * Phantom property for build-time type extraction.
+   * Never set at runtime — exists only in the type system.
+   */
+  readonly _type?: T;
+}
+
+// StandardSchemaV1 is imported from schema-bridge.ts — single source of truth.
+// Re-export for consumers that import it from this module.
+export type { StandardSchemaV1 } from '../schema-bridge.js';
+
+// ---------------------------------------------------------------------------
+// Type-level helpers
+// ---------------------------------------------------------------------------
+
+/** Infer the output type from either a SearchParamCodec or a StandardSchemaV1. */
+export type InferField<V> =
+  V extends SearchParamCodec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;
+
+/** Acceptable field value for defineSearchParams: a codec or a Standard Schema. */
+export type SearchParamField<T = unknown> = SearchParamCodec<T> | StandardSchemaV1<T>;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert URLSearchParams or a plain record to a normalized record
+ * where repeated keys produce arrays.
+ */
+function normalizeRaw(
+  raw: URLSearchParams | Record<string, string | string[] | undefined>
+): Record<string, string | string[] | undefined> {
+  if (raw instanceof URLSearchParams) {
+    const result: Record<string, string | string[] | undefined> = {};
+    for (const key of new Set(raw.keys())) {
+      const values = raw.getAll(key);
+      result[key] = values.length === 1 ? values[0] : values;
+    }
+    return result;
+  }
+  return raw;
+}
+
+/**
+ * Compute the serialized default value for a codec. Used for
+ * default-omission: when serialize(value) === serialize(parse(undefined)),
+ * the field is omitted from the URL.
+ */
+function getDefaultSerialized<T>(codec: SearchParamCodec<T>): string | null {
+  return codec.serialize(codec.parse(undefined));
+}
+
+// isStandardSchema and isCodec are imported from schema-bridge.ts.
+
+/**
+ * Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema
+ * objects and wraps them with fromSchema. Reads .urlKey from codecs.
+ */
+function resolveField(
+  fieldName: string,
+  value: SearchParamField
+): { codec: SearchParamCodec<unknown>; urlKey?: string } {
+  // Check for codec first (codecs may also have '~standard' if they're nuqs parsers)
+  if (isCodec(value)) {
+    return { codec: value, urlKey: value.urlKey };
+  }
+
+  // Auto-detect Standard Schema
+  if (isStandardSchema(value)) {
+    return { codec: fromSchema(value) };
+  }
+
+  throw new Error(
+    `[timber] defineSearchParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +
+      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +
+      `(Zod, Valibot, ArkType).`
+  );
+}
+
+/**
+ * Validate that all codecs handle absent params (parse(undefined) doesn't throw).
+ * Catches schemas that throw on missing input. `undefined` and `null` are both
+ * valid defaults — `undefined` is correct for optional fields (e.g., `z.string().optional()`).
+ */
+function validateDefaults(codecMap: Record<string, SearchParamCodec<unknown>>): void {
+  for (const [key, codec] of Object.entries(codecMap)) {
+    try {
+      codec.parse(undefined);
+    } catch {
+      throw new Error(
+        `[timber] defineSearchParams: field '${key}' throws when the param is absent.\n` +
+          `  Search params are optional — the URL might not contain ?${key}=anything.\n` +
+          `  Add .default() or .optional() to your schema, or wrap with withDefault().`
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a SearchParamsDefinition from a map of codecs and/or Standard Schema
+ * objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType
+ * schemas with auto-detection.
+ *
+ * ```ts
+ * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'
+ * import { parseAsString, parseAsStringEnum } from 'nuqs'
+ * import { z } from 'zod/v4'
+ *
+ * export const searchParams = defineSearchParams({
+ *   page: z.coerce.number().int().min(1).default(1),     // Standard Schema — auto-wrapped
+ *   q: withUrlKey(parseAsString, 'search'),                // nuqs codec with URL alias
+ *   sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),
+ * })
+ * ```
+ */
+/**
+ * Overload: accept a Standard Schema object schema (e.g., z.object({...})).
+ *
+ * The schema must have a `.shape` property whose values are themselves
+ * Standard Schema objects. Each shape property becomes a field codec
+ * via fromSchema().
+ *
+ * ```ts
+ * const searchParams = defineSearchParams(
+ *   z.object({ page: z.coerce.number().default(1), q: z.string().optional() })
+ * )
+ * ```
+ */
+export function defineSearchParams<T extends Record<string, unknown>>(
+  schema: StandardSchemaV1<T> & { shape: Record<string, StandardSchemaV1<unknown>> }
+): SearchParamsDefinition<T>;
+
+/**
+ * Overload: accept a map of codecs and/or Standard Schema objects.
+ */
+export function defineSearchParams<C extends Record<string, SearchParamField>>(
+  codecs: C
+): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }>;
+
+export function defineSearchParams(
+  codecsOrSchema:
+    | Record<string, SearchParamField>
+    | (StandardSchemaV1<unknown> & { shape: Record<string, StandardSchemaV1<unknown>> })
+): SearchParamsDefinition<Record<string, unknown>> {
+  // Detect Standard Schema object with .shape (e.g., z.object(...))
+  if (isStandardSchema(codecsOrSchema) && hasShape(codecsOrSchema)) {
+    const fieldCodecs: Record<string, SearchParamField> = {};
+    for (const [key, fieldSchema] of Object.entries(codecsOrSchema.shape)) {
+      if (isStandardSchema(fieldSchema)) {
+        fieldCodecs[key] = fieldSchema;
+      } else {
+        throw new Error(
+          `[timber] defineSearchParams: field '${key}' in schema.shape is not a Standard Schema. ` +
+            `All shape properties must be Standard Schema objects (Zod, Valibot, ArkType).`
+        );
+      }
+    }
+    return defineSearchParamsFromMap(fieldCodecs);
+  }
+
+  return defineSearchParamsFromMap(codecsOrSchema as Record<string, SearchParamField>);
+}
+
+/** Check if a schema has a .shape property with object-type values. */
+function hasShape(schema: unknown): schema is { shape: Record<string, unknown> } {
+  return (
+    typeof schema === 'object' &&
+    schema !== null &&
+    'shape' in schema &&
+    typeof (schema as { shape: unknown }).shape === 'object' &&
+    (schema as { shape: unknown }).shape !== null
+  );
+}
+
+function defineSearchParamsFromMap(
+  codecs: Record<string, SearchParamField>
+): SearchParamsDefinition<Record<string, unknown>> {
+  const resolvedCodecs: Record<string, SearchParamCodec<unknown>> = {};
+  const urlKeys: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(codecs)) {
+    const resolved = resolveField(key, value as SearchParamField);
+    resolvedCodecs[key] = resolved.codec;
+    if (resolved.urlKey) {
+      urlKeys[key] = resolved.urlKey;
+    }
+  }
+
+  // Validate that all codecs handle absent params
+  validateDefaults(resolvedCodecs);
+
+  return buildDefinition(resolvedCodecs as unknown as CodecMap<Record<string, unknown>>, urlKeys);
+}
+
+// ---------------------------------------------------------------------------
+// Internal: build the definition object
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal: build a SearchParamsDefinition from a typed codec map and url keys.
+ */
+function buildDefinition<T extends Record<string, unknown>>(
+  codecMap: CodecMap<T>,
+  urlKeys: Record<string, string>
+): SearchParamsDefinition<T> {
+  // Pre-compute default serialized values for omission check
+  const defaultSerialized: Record<string, string | null> = {};
+  for (const key of Object.keys(codecMap)) {
+    defaultSerialized[key] = getDefaultSerialized(codecMap[key as keyof T]);
+  }
+
+  function getUrlKey(prop: string): string {
+    return urlKeys[prop] ?? prop;
+  }
+
+  // ---- parse ----
+  function parseSync(raw: URLSearchParams | Record<string, string | string[] | undefined>): T {
+    const normalized = normalizeRaw(raw);
+    const result: Record<string, unknown> = {};
+
+    for (const prop of Object.keys(codecMap)) {
+      const urlKey = getUrlKey(prop);
+      const rawValue = normalized[urlKey];
+      result[prop] = (codecMap[prop as keyof T] as SearchParamCodec<unknown>).parse(rawValue);
+    }
+
+    return result as T;
+  }
+
+  // Overloaded parse: sync when given raw params, async when given a Promise.
+  // This enables the ergonomic pattern: await def.parse(searchParams())
+  function parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;
+  function parse(
+    raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>
+  ): Promise<T>;
+  function parse(
+    raw:
+      | URLSearchParams
+      | Record<string, string | string[] | undefined>
+      | Promise<URLSearchParams | Record<string, string | string[] | undefined>>
+  ): T | Promise<T> {
+    if (raw instanceof Promise) {
+      return raw.then(parseSync);
+    }
+    return parseSync(raw);
+  }
+
+  // ---- serialize ----
+  function serialize(values: Partial<T>): string {
+    const parts: string[] = [];
+
+    for (const prop of Object.keys(codecMap)) {
+      if (!(prop in values)) continue;
+      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;
+      const serialized = codec.serialize(values[prop as keyof T] as unknown);
+
+      // Omit if serialized value matches the default
+      if (serialized === defaultSerialized[prop]) continue;
+      if (serialized === null) continue;
+
+      parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);
+    }
+
+    return parts.join('&');
+  }
+
+  // ---- href ----
+  function href(pathname: string, values: Partial<T>): string {
+    const qs = serialize(values);
+    return qs ? `${pathname}?${qs}` : pathname;
+  }
+
+  // ---- toSearchParams ----
+  function toSearchParams(values: Partial<T>): URLSearchParams {
+    const usp = new URLSearchParams();
+
+    for (const prop of Object.keys(codecMap)) {
+      if (!(prop in values)) continue;
+      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;
+      const serialized = codec.serialize(values[prop as keyof T] as unknown);
+
+      if (serialized === defaultSerialized[prop]) continue;
+      if (serialized === null) continue;
+
+      usp.set(getUrlKey(prop), serialized);
+    }
+
+    return usp;
+  }
+
+  // ---- extend ----
+  function extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(
+    newCodecs: U
+  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }> {
+    type Combined = T & { [K in keyof U]: InferField<U[K]> };
+
+    // Resolve any Standard Schema objects in the extension
+    const resolvedNewCodecs: Record<string, SearchParamCodec<unknown>> = {};
+    const newUrlKeys: Record<string, string> = {};
+    for (const [key, value] of Object.entries(newCodecs)) {
+      const resolved = resolveField(key, value as SearchParamField);
+      resolvedNewCodecs[key] = resolved.codec;
+      if (resolved.urlKey) {
+        newUrlKeys[key] = resolved.urlKey;
+      }
+    }
+
+    const combinedCodecs = {
+      ...codecMap,
+      ...resolvedNewCodecs,
+    } as unknown as CodecMap<Combined>;
+
+    // Merge URL keys: base keys + new codec urlKeys from withUrlKey
+    const combinedUrlKeys: Record<string, string> = { ...urlKeys, ...newUrlKeys };
+
+    return buildDefinition<Combined>(combinedCodecs, combinedUrlKeys);
+  }
+
+  // ---- pick ----
+  function pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>> {
+    const pickedCodecs: Record<string, SearchParamCodec<unknown>> = {};
+    const pickedUrlKeys: Record<string, string> = {};
+
+    for (const key of keys) {
+      pickedCodecs[key] = codecMap[key] as SearchParamCodec<unknown>;
+      if (key in urlKeys) {
+        pickedUrlKeys[key] = urlKeys[key];
+      }
+    }
+
+    return buildDefinition<Pick<T, K>>(
+      pickedCodecs as unknown as CodecMap<Pick<T, K>>,
+      pickedUrlKeys
+    );
+  }
+
+  // ---- useQueryStates ----
+  // Delegates to the 'use client' implementation from use-query-states.ts.
+  //
+  // In the RSC environment: use-query-states.ts is transformed by the RSC
+  //   plugin into a client reference proxy. Calling it throws — correct,
+  //   because hooks can't run during server component rendering.
+  // In SSR: use-query-states.ts is the real nuqs-backed function. Hooks
+  //   work during SSR's renderToReadableStream, so this works correctly.
+  // On the client: same as SSR — the real function is available.
+  function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {
+    return clientUseQueryStates(codecMap, options, Object.freeze({ ...urlKeys })) as [
+      T,
+      SetParams<T>,
+    ];
+  }
+
+  // ---- get ----
+  // ALS-backed: reads getSearchParams() from the current request context
+  // and parses through codecs. Server-only, sync.
+  function get(): T {
+    if (typeof window !== 'undefined') {
+      throw new Error(
+        '[timber] searchParams.get() is server-only. ' +
+          'Use searchParams.useQueryStates() on the client.'
+      );
+    }
+    const raw = getSearchParamsFromAls();
+    return parseSync(raw);
+  }
+
+  const definition: SearchParamsDefinition<T> = {
+    parse,
+    get,
+    useQueryStates,
+    extend,
+    pick,
+    serialize,
+    href,
+    toSearchParams,
+    codecs: codecMap,
+    urlKeys: Object.freeze({ ...urlKeys }),
+  };
+
+  return definition;
+}