@timber-js/app 0.2.0-alpha.41 → 0.2.0-alpha.42

package/dist/_chunks/{wrappers-C6J0nNji.js → define-TK8C1M3x.js}

@@ -1,4 +1,4 @@
-import { n as useQueryStates } from "./use-query-states-BvW0TKDn.js";
+import { n as useQueryStates } from "./use-query-states-wEXY2JQB.js";
 //#region src/search-params/codecs.ts
 /**
 * Zod v4's ~standard.validate() signature includes Promise in the return union
@@ -85,8 +85,16 @@ function fromArraySchema(schema) {
 * Design doc: design/23-search-params.md §"defineSearchParams — The Factory"
 */
 var _rawSearchParams;
-async function getRawSearchParams() {
-	if (!_rawSearchParams) _rawSearchParams = (await import("./request-context-BxYIJM24.js").then((n) => n.l)).rawSearchParams;
+/**
+* Register the rawSearchParams function. Called once at module load time
+* from request-context.ts to avoid dynamic import at call time.
+* @internal
+*/
+function _setRawSearchParamsFn(fn) {
+	_rawSearchParams = fn;
+}
+function getRawSearchParams() {
+	if (!_rawSearchParams) throw new Error("[timber] searchParams.load() is only available on the server. Use searchParams.useQueryStates() on the client.");
 	return _rawSearchParams();
 }
 /**
@@ -266,66 +274,6 @@ function buildDefinition(codecMap, urlKeys) {
 	};
 }
 //#endregion
-//#region src/search-params/wrappers.ts
-/**
-* Wrap a nullable codec with a default value. When the inner codec returns
-* null, the default is used instead. The output type becomes non-nullable.
-*
-* Works with any codec — nuqs parsers, custom codecs, fromSchema results.
-*
-* ```ts
-* import { parseAsInteger } from 'nuqs'
-* import { withDefault } from '@timber-js/app/search-params'
-*
-* const page = withDefault(parseAsInteger, 1)
-* // page.parse(undefined) → 1 (not null)
-* // page.parse('5') → 5
-* ```
-*/
-function withDefault(codec, defaultValue) {
-	return {
-		parse(value) {
-			const result = codec.parse(value);
-			return result === null ? defaultValue : result;
-		},
-		serialize(value) {
-			return codec.serialize(value);
-		}
-	};
-}
-/**
-* Attach a URL key alias to a codec. The alias determines what query
-* parameter key is used in the URL, while the TypeScript property name
-* stays descriptive.
-*
-* Aliases travel with codecs through object spread composition — when
-* you spread a bundle containing aliased codecs into defineSearchParams,
-* the aliases come along automatically.
-*
-* ```ts
-* import { parseAsString } from 'nuqs'
-* import { withUrlKey } from '@timber-js/app/search-params'
-*
-* export const searchable = {
-*   q: withUrlKey(parseAsString, 'search'),
-*   // ?search=shoes → { q: 'shoes' }
-* }
-* ```
-*
-* Composes with withDefault:
-* ```ts
-* import { parseAsInteger } from 'nuqs'
-* withUrlKey(withDefault(parseAsInteger, 1), 'p')
-* ```
-*/
-function withUrlKey(codec, urlKey) {
-	return {
-		parse: codec.parse.bind(codec),
-		serialize: codec.serialize.bind(codec),
-		urlKey
-	};
-}
-//#endregion
-export { fromSchema as a, fromArraySchema as i, withUrlKey as n, defineSearchParams as r, withDefault as t };
+export { fromSchema as i, defineSearchParams as n, fromArraySchema as r, _setRawSearchParamsFn as t };
 
-//# sourceMappingURL=wrappers-C6J0nNji.js.map
+//# sourceMappingURL=define-TK8C1M3x.js.map

package/dist/_chunks/define-TK8C1M3x.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-TK8C1M3x.js","names":[],"sources":["../../src/search-params/codecs.ts","../../src/search-params/define.ts"],"sourcesContent":["/**\n * Built-in codecs and the fromSchema bridge for Standard Schema-compatible\n * validation libraries (Zod, Valibot, ArkType).\n *\n * Design doc: design/09-typescript.md §\"The SearchParamCodec Protocol\"\n */\n\nimport type { SearchParamCodec } from './define.js';\n\n// ---------------------------------------------------------------------------\n// Standard Schema interface (subset)\n//\n// Standard Schema (https://github.com/standard-schema/standard-schema) defines\n// a minimal interface that Zod ≥3.24, Valibot ≥1.0, and ArkType all implement.\n// We depend only on `~standard.validate` to avoid coupling to any specific lib.\n// ---------------------------------------------------------------------------\n\ninterface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;\n  };\n}\n\ntype StandardSchemaResult<Output> =\n  | { value: Output; issues?: undefined }\n  | { value?: undefined; issues: ReadonlyArray<{ message: string }> };\n\n// ---------------------------------------------------------------------------\n// Sync validate helper\n// ---------------------------------------------------------------------------\n\n/**\n * Zod v4's ~standard.validate() signature includes Promise in the return union\n * to satisfy the Standard Schema spec, but in practice Zod always validates\n * synchronously for the schema types we use. We assert the result is sync and\n * throw if it isn't — search params parsing must be synchronous.\n */\nfunction validateSync<Output>(\n  schema: StandardSchemaV1<Output>,\n  value: unknown\n): StandardSchemaResult<Output> {\n  const result = schema['~standard'].validate(value);\n  if (result instanceof Promise) {\n    throw new Error(\n      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported for search params.'\n    );\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// fromSchema — bridge from Standard Schema to SearchParamCodec\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a\n * SearchParamCodec.\n *\n * Parse: coerces the raw URL string through the schema. On validation failure,\n * parses `undefined` to get the schema's default value (the schema should have\n * a `.default()` call). If that also fails, returns `undefined`.\n *\n * Serialize: uses `String()` for primitives, `null` for null/undefined.\n *\n * ```ts\n * import { fromSchema } from '@timber-js/app/search-params'\n * import { z } from 'zod/v4'\n *\n * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))\n * ```\n */\nexport function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // For array inputs, take the last value (consistent with URLSearchParams.get())\n      const input = Array.isArray(value) ? value[value.length - 1] : value;\n\n      // Try parsing the raw value\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try parsing undefined to get the default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      // No default available — return undefined (codec design choice)\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      return String(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// fromArraySchema — bridge for array-valued search params\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema for array values. Handles both single strings\n * and repeated query keys (`?tag=a&tag=b`).\n *\n * ```ts\n * import { fromArraySchema } from '@timber-js/app/search-params'\n * import { z } from 'zod/v4'\n *\n * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))\n * ```\n */\nexport function fromArraySchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Coerce single string to array for array schemas\n      let input: unknown = value;\n      if (typeof value === 'string') {\n        input = [value];\n      } else if (value === undefined) {\n        input = undefined;\n      }\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try undefined for default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      if (Array.isArray(value)) {\n        return value.length === 0 ? null : value.join(',');\n      }\n      return String(value);\n    },\n  };\n}\n","/**\n * defineSearchParams — factory for SearchParamsDefinition<T>.\n *\n * Creates a typed, composable definition for a route's search parameters.\n * Accepts both SearchParamCodec values and Standard Schema objects (Zod,\n * Valibot, ArkType) with auto-detection. Supports URL key aliasing via\n * withUrlKey(), default-omission serialization, and composition via\n * .extend() / .pick().\n *\n * Design doc: design/23-search-params.md §\"defineSearchParams — The Factory\"\n */\n\nimport { useQueryStates as clientUseQueryStates } from '#/client/use-query-states.js';\nimport { fromSchema } from './codecs.js';\nimport type { Codec } from '#/codec.js';\n\n// Server-only reference for .load() — avoids pulling server ALS into client bundles.\n// In client environments, .load() throws before reaching this code path.\n//\n// IMPORTANT: This is set eagerly via _setRawSearchParamsFn() at server startup\n// (called from request-context.ts module initialization). It must NOT use\n// dynamic `await import()` at call time because the async microtask from the\n// dynamic import loses AsyncLocalStorage context in React's RSC Flight renderer,\n// breaking rawSearchParams() in parallel slot pages. See TIM-523.\nlet _rawSearchParams: (() => Promise<URLSearchParams>) | undefined;\n\n/**\n * Register the rawSearchParams function. Called once at module load time\n * from request-context.ts to avoid dynamic import at call time.\n * @internal\n */\nexport function _setRawSearchParamsFn(fn: () => Promise<URLSearchParams>): void {\n  _rawSearchParams = fn;\n}\n\nfunction getRawSearchParams(): Promise<URLSearchParams> {\n  if (!_rawSearchParams) {\n    throw new Error(\n      '[timber] searchParams.load() is only available on the server. ' +\n        'Use searchParams.useQueryStates() on the client.'\n    );\n  }\n  return _rawSearchParams();\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A codec that converts between URL string values and typed values.\n *\n * nuqs parsers implement this interface natively — no adapter needed.\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected\n * by defineSearchParams and wrapped via fromSchema.\n */\nexport interface SearchParamCodec<T> extends Codec<T> {\n  /** Optional URL key alias, set by withUrlKey(). */\n  urlKey?: string;\n}\n\n/** A codec with a URL key alias attached via withUrlKey(). */\nexport interface SearchParamCodecWithUrlKey<T> extends SearchParamCodec<T> {\n  urlKey: string;\n}\n\n/** Infer the output type of a codec. */\nexport type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;\n\n/** Map of property names to codecs. */\nexport type CodecMap<T extends Record<string, unknown>> = {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n};\n\n/** Options for useQueryStates setter. */\nexport interface SetParamsOptions {\n  /** Update URL without server roundtrip (default: false). */\n  shallow?: boolean;\n  /** Scroll to top after update (default: true). */\n  scroll?: boolean;\n  /** 'push' (default) or 'replace' for history state. */\n  history?: 'push' | 'replace';\n}\n\n/** Setter function returned by useQueryStates. */\nexport type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;\n\n/** Options for useQueryStates hook. */\nexport interface QueryStatesOptions {\n  /** Update URL without server roundtrip (default: false). */\n  shallow?: boolean;\n  /** Scroll to top after update (default: true). */\n  scroll?: boolean;\n  /** 'push' (default) or 'replace' for history state. */\n  history?: 'push' | 'replace';\n}\n\n/**\n * A fully typed, composable search params definition.\n *\n * Returned by defineSearchParams(). Carries a phantom _type property\n * for build-time type extraction.\n */\nexport interface SearchParamsDefinition<T extends Record<string, unknown>> {\n  /** Parse raw URL search params into typed values. */\n  parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n  /** Parse a Promise of URLSearchParams (e.g., from the ALS `searchParams()` API). */\n  parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;\n\n  /**\n   * Load typed search params from the current request context (ALS-backed).\n   *\n   * Server-only — reads rawSearchParams() from ALS and parses through codecs.\n   * Throws on client. Eliminates the naming conflict between the definition\n   * export and the server helper.\n   *\n   * ```tsx\n   * // app/products/page.tsx\n   * import { searchParams } from './params'\n   * export default async function Page() {\n   *   const { page, category } = await searchParams.load()\n   * }\n   * ```\n   */\n  load(): Promise<T>;\n\n  /** Client hook — reads current URL params and returns typed values + setter. */\n  useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];\n\n  /** Extend with additional codecs or Standard Schema objects. */\n  extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(\n    codecs: U\n  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }>;\n\n  /** Pick a subset of keys. Preserves codecs and aliases. */\n  pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;\n\n  /** Serialize values to a query string (no leading '?'), omitting defaults. */\n  serialize(values: Partial<T>): string;\n\n  /** Build a full path with query string, omitting defaults. */\n  href(pathname: string, values: Partial<T>): string;\n\n  /** Build a URLSearchParams instance, omitting defaults. */\n  toSearchParams(values: Partial<T>): URLSearchParams;\n\n  /** Read-only codec map for spreading into .extend(). */\n  codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n\n  /** Read-only URL key alias map. Maps property names to URL query parameter keys. */\n  readonly urlKeys: Readonly<Record<string, string>>;\n\n  /**\n   * Phantom property for build-time type extraction.\n   * Never set at runtime — exists only in the type system.\n   */\n  readonly _type?: T;\n}\n\n// ---------------------------------------------------------------------------\n// Standard Schema interface (subset)\n//\n// Standard Schema (https://github.com/standard-schema/standard-schema) defines\n// a minimal interface that Zod ≥3.24, Valibot ≥1.0, and ArkType all implement.\n// We check for the '~standard' property to auto-detect schemas.\n// ---------------------------------------------------------------------------\n\n/** Minimal Standard Schema interface for auto-detection. */\nexport interface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(\n      value: unknown\n    ):\n      | { value: Output; issues?: undefined }\n      | { value?: undefined; issues: ReadonlyArray<{ message: string }> }\n      | Promise<\n          | { value: Output; issues?: undefined }\n          | { value?: undefined; issues: ReadonlyArray<{ message: string }> }\n        >;\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Type-level helpers\n// ---------------------------------------------------------------------------\n\n/** Infer the output type from either a SearchParamCodec or a StandardSchemaV1. */\nexport type InferField<V> =\n  V extends SearchParamCodec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;\n\n/** Acceptable field value for defineSearchParams: a codec or a Standard Schema. */\nexport type SearchParamField<T = unknown> = SearchParamCodec<T> | StandardSchemaV1<T>;\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Convert URLSearchParams or a plain record to a normalized record\n * where repeated keys produce arrays.\n */\nfunction normalizeRaw(\n  raw: URLSearchParams | Record<string, string | string[] | undefined>\n): Record<string, string | string[] | undefined> {\n  if (raw instanceof URLSearchParams) {\n    const result: Record<string, string | string[] | undefined> = {};\n    for (const key of new Set(raw.keys())) {\n      const values = raw.getAll(key);\n      result[key] = values.length === 1 ? values[0] : values;\n    }\n    return result;\n  }\n  return raw;\n}\n\n/**\n * Compute the serialized default value for a codec. Used for\n * default-omission: when serialize(value) === serialize(parse(undefined)),\n * the field is omitted from the URL.\n */\nfunction getDefaultSerialized<T>(codec: SearchParamCodec<T>): string | null {\n  return codec.serialize(codec.parse(undefined));\n}\n\n/** Check if a value is a Standard Schema object. */\nfunction isStandardSchema(value: unknown): value is StandardSchemaV1 {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    '~standard' in value &&\n    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'\n  );\n}\n\n/** Check if a value is a SearchParamCodec. */\nfunction isCodec(value: unknown): value is SearchParamCodec<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as SearchParamCodec<unknown>).parse === 'function' &&\n    typeof (value as SearchParamCodec<unknown>).serialize === 'function'\n  );\n}\n\n/**\n * Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema\n * objects and wraps them with fromSchema. Reads .urlKey from codecs.\n */\nfunction resolveField(\n  fieldName: string,\n  value: SearchParamField\n): { codec: SearchParamCodec<unknown>; urlKey?: string } {\n  // Check for codec first (codecs may also have '~standard' if they're nuqs parsers)\n  if (isCodec(value)) {\n    return { codec: value, urlKey: value.urlKey };\n  }\n\n  // Auto-detect Standard Schema\n  if (isStandardSchema(value)) {\n    return { codec: fromSchema(value) };\n  }\n\n  throw new Error(\n    `[timber] defineSearchParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n      `(Zod, Valibot, ArkType).`\n  );\n}\n\n/**\n * Validate that all codecs handle absent params (parse(undefined) doesn't throw).\n * Catches schemas that throw on missing input. `undefined` and `null` are both\n * valid defaults — `undefined` is correct for optional fields (e.g., `z.string().optional()`).\n */\nfunction validateDefaults(codecMap: Record<string, SearchParamCodec<unknown>>): void {\n  for (const [key, codec] of Object.entries(codecMap)) {\n    try {\n      codec.parse(undefined);\n    } catch {\n      throw new Error(\n        `[timber] defineSearchParams: field '${key}' throws when the param is absent.\\n` +\n          `  Search params are optional — the URL might not contain ?${key}=anything.\\n` +\n          `  Add .default() or .optional() to your schema, or wrap with withDefault().`\n      );\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a SearchParamsDefinition from a map of codecs and/or Standard Schema\n * objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType\n * schemas with auto-detection.\n *\n * ```ts\n * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'\n * import { parseAsString, parseAsStringEnum } from 'nuqs'\n * import { z } from 'zod/v4'\n *\n * export const searchParams = defineSearchParams({\n *   page: z.coerce.number().int().min(1).default(1),     // Standard Schema — auto-wrapped\n *   q: withUrlKey(parseAsString, 'search'),                // nuqs codec with URL alias\n *   sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),\n * })\n * ```\n */\nexport function defineSearchParams<C extends Record<string, SearchParamField>>(\n  codecs: C\n): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }> {\n  type T = { [K in keyof C]: InferField<C[K]> };\n\n  const resolvedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n  const urlKeys: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(codecs)) {\n    const resolved = resolveField(key, value as SearchParamField);\n    resolvedCodecs[key] = resolved.codec;\n    if (resolved.urlKey) {\n      urlKeys[key] = resolved.urlKey;\n    }\n  }\n\n  // Validate that all codecs handle absent params\n  validateDefaults(resolvedCodecs);\n\n  return buildDefinition<T>(resolvedCodecs as unknown as CodecMap<T>, urlKeys);\n}\n\n// ---------------------------------------------------------------------------\n// Internal: build the definition object\n// ---------------------------------------------------------------------------\n\n/**\n * Internal: build a SearchParamsDefinition from a typed codec map and url keys.\n */\nfunction buildDefinition<T extends Record<string, unknown>>(\n  codecMap: CodecMap<T>,\n  urlKeys: Record<string, string>\n): SearchParamsDefinition<T> {\n  // Pre-compute default serialized values for omission check\n  const defaultSerialized: Record<string, string | null> = {};\n  for (const key of Object.keys(codecMap)) {\n    defaultSerialized[key] = getDefaultSerialized(codecMap[key as keyof T]);\n  }\n\n  function getUrlKey(prop: string): string {\n    return urlKeys[prop] ?? prop;\n  }\n\n  // ---- parse ----\n  function parseSync(raw: URLSearchParams | Record<string, string | string[] | undefined>): T {\n    const normalized = normalizeRaw(raw);\n    const result: Record<string, unknown> = {};\n\n    for (const prop of Object.keys(codecMap)) {\n      const urlKey = getUrlKey(prop);\n      const rawValue = normalized[urlKey];\n      result[prop] = (codecMap[prop as keyof T] as SearchParamCodec<unknown>).parse(rawValue);\n    }\n\n    return result as T;\n  }\n\n  // Overloaded parse: sync when given raw params, async when given a Promise.\n  // This enables the ergonomic pattern: await def.parse(searchParams())\n  function parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n  function parse(\n    raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n  ): Promise<T>;\n  function parse(\n    raw:\n      | URLSearchParams\n      | Record<string, string | string[] | undefined>\n      | Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n  ): T | Promise<T> {\n    if (raw instanceof Promise) {\n      return raw.then(parseSync);\n    }\n    return parseSync(raw);\n  }\n\n  // ---- serialize ----\n  function serialize(values: Partial<T>): string {\n    const parts: string[] = [];\n\n    for (const prop of Object.keys(codecMap)) {\n      if (!(prop in values)) continue;\n      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n      const serialized = codec.serialize(values[prop as keyof T] as unknown);\n\n      // Omit if serialized value matches the default\n      if (serialized === defaultSerialized[prop]) continue;\n      if (serialized === null) continue;\n\n      parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);\n    }\n\n    return parts.join('&');\n  }\n\n  // ---- href ----\n  function href(pathname: string, values: Partial<T>): string {\n    const qs = serialize(values);\n    return qs ? `${pathname}?${qs}` : pathname;\n  }\n\n  // ---- toSearchParams ----\n  function toSearchParams(values: Partial<T>): URLSearchParams {\n    const usp = new URLSearchParams();\n\n    for (const prop of Object.keys(codecMap)) {\n      if (!(prop in values)) continue;\n      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n      const serialized = codec.serialize(values[prop as keyof T] as unknown);\n\n      if (serialized === defaultSerialized[prop]) continue;\n      if (serialized === null) continue;\n\n      usp.set(getUrlKey(prop), serialized);\n    }\n\n    return usp;\n  }\n\n  // ---- extend ----\n  function extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(\n    newCodecs: U\n  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }> {\n    type Combined = T & { [K in keyof U]: InferField<U[K]> };\n\n    // Resolve any Standard Schema objects in the extension\n    const resolvedNewCodecs: Record<string, SearchParamCodec<unknown>> = {};\n    const newUrlKeys: Record<string, string> = {};\n    for (const [key, value] of Object.entries(newCodecs)) {\n      const resolved = resolveField(key, value as SearchParamField);\n      resolvedNewCodecs[key] = resolved.codec;\n      if (resolved.urlKey) {\n        newUrlKeys[key] = resolved.urlKey;\n      }\n    }\n\n    const combinedCodecs = {\n      ...codecMap,\n      ...resolvedNewCodecs,\n    } as unknown as CodecMap<Combined>;\n\n    // Merge URL keys: base keys + new codec urlKeys from withUrlKey\n    const combinedUrlKeys: Record<string, string> = { ...urlKeys, ...newUrlKeys };\n\n    return buildDefinition<Combined>(combinedCodecs, combinedUrlKeys);\n  }\n\n  // ---- pick ----\n  function pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>> {\n    const pickedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n    const pickedUrlKeys: Record<string, string> = {};\n\n    for (const key of keys) {\n      pickedCodecs[key] = codecMap[key] as SearchParamCodec<unknown>;\n      if (key in urlKeys) {\n        pickedUrlKeys[key] = urlKeys[key];\n      }\n    }\n\n    return buildDefinition<Pick<T, K>>(\n      pickedCodecs as unknown as CodecMap<Pick<T, K>>,\n      pickedUrlKeys\n    );\n  }\n\n  // ---- useQueryStates ----\n  // Delegates to the 'use client' implementation from use-query-states.ts.\n  //\n  // In the RSC environment: use-query-states.ts is transformed by the RSC\n  //   plugin into a client reference proxy. Calling it throws — correct,\n  //   because hooks can't run during server component rendering.\n  // In SSR: use-query-states.ts is the real nuqs-backed function. Hooks\n  //   work during SSR's renderToReadableStream, so this works correctly.\n  // On the client: same as SSR — the real function is available.\n  function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {\n    return clientUseQueryStates(codecMap, options, Object.freeze({ ...urlKeys })) as [\n      T,\n      SetParams<T>,\n    ];\n  }\n\n  // ---- load ----\n  // ALS-backed: reads rawSearchParams() from the current request context\n  // and parses through codecs. Server-only — throws on client.\n  async function load(): Promise<T> {\n    if (typeof window !== 'undefined') {\n      throw new Error(\n        '[timber] searchParams.load() is server-only. ' +\n          'Use searchParams.useQueryStates() on the client.'\n      );\n    }\n    const raw = await getRawSearchParams();\n    return parseSync(raw);\n  }\n\n  const definition: SearchParamsDefinition<T> = {\n    parse,\n    load,\n    useQueryStates,\n    extend,\n    pick,\n    serialize,\n    href,\n    toSearchParams,\n    codecs: codecMap,\n    urlKeys: Object.freeze({ ...urlKeys }),\n  };\n\n  return definition;\n}\n"],"mappings":";;;;;;;;AAqCA,SAAS,aACP,QACA,OAC8B;CAC9B,MAAM,SAAS,OAAO,aAAa,SAAS,MAAM;AAClD,KAAI,kBAAkB,QACpB,OAAM,IAAI,MACR,sGACD;AAEH,QAAO;;;;;;;;;;;;;;;;;;;AAwBT,SAAgB,WAAc,QAAkD;AAC9E,QAAO;EACL,MAAM,OAAyC;GAK7C,MAAM,SAAS,aAAa,QAHd,MAAM,QAAQ,MAAM,GAAG,MAAM,MAAM,SAAS,KAAK,MAGrB;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,gBAAgB,aAAa,QAAQ,KAAA,EAAU;AACrD,OAAI,CAAC,cAAc,OACjB,QAAO,cAAc;;EAOzB,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAET,UAAO,OAAO,MAAM;;EAEvB;;;;;;;;;;;;;AAkBH,SAAgB,gBAAmB,QAAkD;AACnF,QAAO;EACL,MAAM,OAAyC;GAE7C,IAAI,QAAiB;AACrB,OAAI,OAAO,UAAU,SACnB,SAAQ,CAAC,MAAM;YACN,UAAU,KAAA,EACnB,SAAQ,KAAA;GAGV,MAAM,SAAS,aAAa,QAAQ,MAAM;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,gBAAgB,aAAa,QAAQ,KAAA,EAAU;AACrD,OAAI,CAAC,cAAc,OACjB,QAAO,cAAc;;EAMzB,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAET,OAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MAAM,WAAW,IAAI,OAAO,MAAM,KAAK,IAAI;AAEpD,UAAO,OAAO,MAAM;;EAEvB;;;;;;;;;;;;;;;AC/HH,IAAI;;;;;;AAOJ,SAAgB,sBAAsB,IAA0C;AAC9E,oBAAmB;;AAGrB,SAAS,qBAA+C;AACtD,KAAI,CAAC,iBACH,OAAM,IAAI,MACR,iHAED;AAEH,QAAO,kBAAkB;;;;;;AA+J3B,SAAS,aACP,KAC+C;AAC/C,KAAI,eAAe,iBAAiB;EAClC,MAAM,SAAwD,EAAE;AAChE,OAAK,MAAM,OAAO,IAAI,IAAI,IAAI,MAAM,CAAC,EAAE;GACrC,MAAM,SAAS,IAAI,OAAO,IAAI;AAC9B,UAAO,OAAO,OAAO,WAAW,IAAI,OAAO,KAAK;;AAElD,SAAO;;AAET,QAAO;;;;;;;AAQT,SAAS,qBAAwB,OAA2C;AAC1E,QAAO,MAAM,UAAU,MAAM,MAAM,KAAA,EAAU,CAAC;;;AAIhD,SAAS,iBAAiB,OAA2C;AACnE,QACE,OAAO,UAAU,YACjB,UAAU,QACV,eAAe,SACf,OAAQ,MAA2B,cAAc,aAAa;;;AAKlE,SAAS,QAAQ,OAAoD;AACnE,QACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAAoC,UAAU,cACtD,OAAQ,MAAoC,cAAc;;;;;;AAQ9D,SAAS,aACP,WACA,OACuD;AAEvD,KAAI,QAAQ,MAAM,CAChB,QAAO;EAAE,OAAO;EAAO,QAAQ,MAAM;EAAQ;AAI/C,KAAI,iBAAiB,MAAM,CACzB,QAAO,EAAE,OAAO,WAAW,MAAM,EAAE;AAGrC,OAAM,IAAI,MACR,uCAAuC,UAAU,uJAGlD;;;;;;;AAQH,SAAS,iBAAiB,UAA2D;AACnF,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,CACjD,KAAI;AACF,QAAM,MAAM,KAAA,EAAU;SAChB;AACN,QAAM,IAAI,MACR,uCAAuC,IAAI,gGACoB,IAAI,yFAEpE;;;;;;;;;;;;;;;;;;;;AA0BP,SAAgB,mBACd,QAC8D;CAG9D,MAAM,iBAA4D,EAAE;CACpE,MAAM,UAAkC,EAAE;AAE1C,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,EAAE;EACjD,MAAM,WAAW,aAAa,KAAK,MAA0B;AAC7D,iBAAe,OAAO,SAAS;AAC/B,MAAI,SAAS,OACX,SAAQ,OAAO,SAAS;;AAK5B,kBAAiB,eAAe;AAEhC,QAAO,gBAAmB,gBAA0C,QAAQ;;;;;AAU9E,SAAS,gBACP,UACA,SAC2B;CAE3B,MAAM,oBAAmD,EAAE;AAC3D,MAAK,MAAM,OAAO,OAAO,KAAK,SAAS,CACrC,mBAAkB,OAAO,qBAAqB,SAAS,KAAgB;CAGzE,SAAS,UAAU,MAAsB;AACvC,SAAO,QAAQ,SAAS;;CAI1B,SAAS,UAAU,KAAyE;EAC1F,MAAM,aAAa,aAAa,IAAI;EACpC,MAAM,SAAkC,EAAE;AAE1C,OAAK,MAAM,QAAQ,OAAO,KAAK,SAAS,EAAE;GAExC,MAAM,WAAW,WADF,UAAU,KAAK;AAE9B,UAAO,QAAS,SAAS,MAA+C,MAAM,SAAS;;AAGzF,SAAO;;CAST,SAAS,MACP,KAIgB;AAChB,MAAI,eAAe,QACjB,QAAO,IAAI,KAAK,UAAU;AAE5B,SAAO,UAAU,IAAI;;CAIvB,SAAS,UAAU,QAA4B;EAC7C,MAAM,QAAkB,EAAE;AAE1B,OAAK,MAAM,QAAQ,OAAO,KAAK,SAAS,EAAE;AACxC,OAAI,EAAE,QAAQ,QAAS;GAEvB,MAAM,aADQ,SAAS,MACE,UAAU,OAAO,MAA4B;AAGtE,OAAI,eAAe,kBAAkB,MAAO;AAC5C,OAAI,eAAe,KAAM;AAEzB,SAAM,KAAK,GAAG,mBAAmB,UAAU,KAAK,CAAC,CAAC,GAAG,mBAAmB,WAAW,GAAG;;AAGxF,SAAO,MAAM,KAAK,IAAI;;CAIxB,SAAS,KAAK,UAAkB,QAA4B;EAC1D,MAAM,KAAK,UAAU,OAAO;AAC5B,SAAO,KAAK,GAAG,SAAS,GAAG,OAAO;;CAIpC,SAAS,eAAe,QAAqC;EAC3D,MAAM,MAAM,IAAI,iBAAiB;AAEjC,OAAK,MAAM,QAAQ,OAAO,KAAK,SAAS,EAAE;AACxC,OAAI,EAAE,QAAQ,QAAS;GAEvB,MAAM,aADQ,SAAS,MACE,UAAU,OAAO,MAA4B;AAEtE,OAAI,eAAe,kBAAkB,MAAO;AAC5C,OAAI,eAAe,KAAM;AAEzB,OAAI,IAAI,UAAU,KAAK,EAAE,WAAW;;AAGtC,SAAO;;CAIT,SAAS,OACP,WACkE;EAIlE,MAAM,oBAA+D,EAAE;EACvE,MAAM,aAAqC,EAAE;AAC7C,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,UAAU,EAAE;GACpD,MAAM,WAAW,aAAa,KAAK,MAA0B;AAC7D,qBAAkB,OAAO,SAAS;AAClC,OAAI,SAAS,OACX,YAAW,OAAO,SAAS;;AAY/B,SAAO,gBARgB;GACrB,GAAG;GACH,GAAG;GACJ,EAG+C;GAAE,GAAG;GAAS,GAAG;GAAY,CAEZ;;CAInE,SAAS,KAAiC,GAAG,MAA+C;EAC1F,MAAM,eAA0D,EAAE;EAClE,MAAM,gBAAwC,EAAE;AAEhD,OAAK,MAAM,OAAO,MAAM;AACtB,gBAAa,OAAO,SAAS;AAC7B,OAAI,OAAO,QACT,eAAc,OAAO,QAAQ;;AAIjC,SAAO,gBACL,cACA,cACD;;CAYH,SAAS,iBAAe,SAAiD;AACvE,SAAO,eAAqB,UAAU,SAAS,OAAO,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC;;CAS/E,eAAe,OAAmB;AAChC,MAAI,OAAO,WAAW,YACpB,OAAM,IAAI,MACR,gGAED;AAGH,SAAO,UADK,MAAM,oBAAoB,CACjB;;AAgBvB,QAb8C;EAC5C;EACA;EACA,gBAAA;EACA;EACA;EACA;EACA;EACA;EACA,QAAQ;EACR,SAAS,OAAO,OAAO,EAAE,GAAG,SAAS,CAAC;EACvC"}

package/dist/_chunks/{define-cookie-BmKbSyp0.js → define-cookie-k9btcEfI.js}

@@ -43,12 +43,12 @@ function defineCookie(name, options) {
 		options: resolvedOptions,
 		codec,
 		async getCookie() {
-			const { cookies } = await import("./request-context-BxYIJM24.js").then((n) => n.l);
+			const { cookies } = await import("./request-context-0h-6Voad.js").then((n) => n.l);
 			const raw = cookies().get(name);
 			return codec.parse(raw);
 		},
 		async setCookie(value) {
-			const { cookies } = await import("./request-context-BxYIJM24.js").then((n) => n.l);
+			const { cookies } = await import("./request-context-0h-6Voad.js").then((n) => n.l);
 			const serialized = codec.serialize(value);
 			if (serialized === null) cookies().delete(name, {
 				path: resolvedOptions.path,
@@ -57,7 +57,7 @@ function defineCookie(name, options) {
 			else cookies().set(name, serialized, resolvedOptions);
 		},
 		async deleteCookie() {
-			const { cookies } = await import("./request-context-BxYIJM24.js").then((n) => n.l);
+			const { cookies } = await import("./request-context-0h-6Voad.js").then((n) => n.l);
 			cookies().delete(name, {
 				path: resolvedOptions.path,
 				domain: resolvedOptions.domain
@@ -90,4 +90,4 @@ function defineCookie(name, options) {
 //#endregion
 export { defineCookie as n, _registerUseCookieModule as t };
 
-//# sourceMappingURL=define-cookie-BmKbSyp0.js.map
+//# sourceMappingURL=define-cookie-k9btcEfI.js.map

package/dist/_chunks/{define-cookie-BmKbSyp0.js.map → define-cookie-k9btcEfI.js.map}

@@ -1 +1 @@
-{"version":3,"file":"define-cookie-BmKbSyp0.js","names":[],"sources":["../../src/cookies/define-cookie.ts"],"sourcesContent":["/**\n * defineCookie — typed cookie definitions.\n *\n * Bundles name + codec + options into a reusable CookieDefinition<T>\n * with async .getCookie(), .setCookie(), .deleteCookie() server methods\n * and a sync .useCookie() client hook.\n *\n * Server methods are async to future-proof the API for v2 features\n * (signed cookies via crypto.subtle, encrypted cookies, external stores).\n *\n * Reuses the SearchParamCodec protocol via fromSchema() bridge.\n * Validation on read returns the codec default (never throws).\n *\n * IMPORTANT: This module must NOT have top-level value imports from either\n * server or client modules. Server methods lazy-import request-context;\n * useCookie() lazy-imports use-cookie. This ensures:\n * - Client bundles don't pull in ALS/server code\n * - RSC bundles don't pull in useSyncExternalStore/client code\n * - Tree-shaking is not required for correctness\n *\n * See design/29-cookies.md §\"Typed Cookies with Schema Validation\"\n */\n\nimport type { CookieOptions } from '#/server/request-context.js';\nimport type { ClientCookieOptions } from '#/client/use-cookie.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\nimport type { Codec } from '#/codec.js';\n\n/**\n * A codec that converts between string cookie values and typed values.\n * Type alias for the shared Codec<T> protocol.\n */\nexport type CookieCodec<T> = Codec<T>;\n\n/** Options for defineCookie: codec + CookieOptions merged. */\nexport interface DefineCookieOptions<T> extends CookieOptions {\n  /** Codec for parsing/serializing the cookie value. */\n  codec: CookieCodec<T>;\n}\n\n/** A fully typed cookie definition with server and client methods. */\nexport interface CookieDefinition<T> {\n  /** The cookie name. */\n  readonly name: string;\n  /** The resolved cookie options (without codec). */\n  readonly options: CookieOptions;\n  /** The codec used for parsing/serializing. */\n  readonly codec: CookieCodec<T>;\n\n  /** Server: read the typed value from the current request. */\n  getCookie(): Promise<T>;\n  /** Server: set the typed value on the response. */\n  setCookie(value: T): Promise<void>;\n  /** Server: delete the cookie. */\n  deleteCookie(): Promise<void>;\n\n  /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */\n  useCookie(): [T, (value: T) => void, () => void];\n}\n\n// ─── Lazy Module References ───────────────────────────────────────────────\n//\n// These are resolved on first use, not at module load time. This prevents\n// the server module graph from pulling in client code and vice versa.\n// The dynamic import() in server methods is natural (they're async).\n// For useCookie() (sync), we cache the module reference after first load.\n\nlet _useCookieModule: typeof import('#/client/use-cookie.js') | undefined;\n\nfunction getUseCookieModule(): typeof import('#/client/use-cookie.js') {\n  if (!_useCookieModule) {\n    // In the client/SSR environment, this module is already in the module\n    // graph (imported by the client entry). The throw is a safeguard —\n    // if useCookie() is somehow called before the module is available,\n    // the developer gets a clear error instead of a silent failure.\n    throw new Error(\n      '[timber] defineCookie().useCookie() requires @timber-js/app/client to be loaded. ' +\n        'This hook can only be used in client components.'\n    );\n  }\n  return _useCookieModule;\n}\n\n/**\n * Register the client cookie module. Called by the client entry to wire\n * up the lazy reference without a top-level import.\n *\n * @internal — framework use only\n */\nexport function _registerUseCookieModule(mod: typeof import('#/client/use-cookie.js')): void {\n  _useCookieModule = mod;\n}\n\n// ─── Factory ──────────────────────────────────────────────────────────────\n\n/**\n * Define a typed cookie.\n *\n * ```ts\n * import { defineCookie } from '@timber-js/app/cookies';\n * import { fromSchema } from '@timber-js/app/search-params';\n * import { z } from 'zod/v4';\n *\n * export const themeCookie = defineCookie('theme', {\n *   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n *\n * // Server\n * const theme = await themeCookie.getCookie();\n * await themeCookie.setCookie('dark');\n *\n * // Client\n * const [theme, setTheme] = themeCookie.useCookie();\n * ```\n */\nexport function defineCookie<T>(\n  name: string,\n  options: DefineCookieOptions<T>\n): CookieDefinition<T> {\n  const { codec, ...cookieOpts } = options;\n  const resolvedOptions: CookieOptions = { ...cookieOpts };\n\n  return {\n    name,\n    options: resolvedOptions,\n    codec,\n\n    async getCookie(): Promise<T> {\n      const { cookies } = await import('#/server/request-context.js');\n      const jar = cookies();\n      const raw = jar.get(name);\n      return codec.parse(raw);\n    },\n\n    async setCookie(value: T): Promise<void> {\n      const { cookies } = await import('#/server/request-context.js');\n      const serialized = codec.serialize(value);\n      if (serialized === null) {\n        cookies().delete(name, {\n          path: resolvedOptions.path,\n          domain: resolvedOptions.domain,\n        });\n      } else {\n        cookies().set(name, serialized, resolvedOptions);\n      }\n    },\n\n    async deleteCookie(): Promise<void> {\n      const { cookies } = await import('#/server/request-context.js');\n      cookies().delete(name, {\n        path: resolvedOptions.path,\n        domain: resolvedOptions.domain,\n      });\n    },\n\n    useCookie(): [T, (value: T) => void, () => void] {\n      const { useCookie: useRawCookie } = getUseCookieModule();\n\n      // Extract client-safe options (no httpOnly — client cookies can't be httpOnly)\n      const clientOpts: ClientCookieOptions = {\n        path: resolvedOptions.path,\n        domain: resolvedOptions.domain,\n        maxAge: resolvedOptions.maxAge,\n        expires: resolvedOptions.expires,\n        sameSite: resolvedOptions.sameSite,\n        secure: resolvedOptions.secure,\n      };\n\n      const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);\n      const parsed = codec.parse(raw);\n\n      const setTyped = (value: T): void => {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          deleteRaw();\n        } else {\n          setRaw(serialized);\n        }\n      };\n\n      return [parsed, setTyped, deleteRaw];\n    },\n  };\n}\n"],"mappings":";AAqEA,IAAI;AAEJ,SAAS,qBAA8D;AACrE,KAAI,CAAC,iBAKH,OAAM,IAAI,MACR,oIAED;AAEH,QAAO;;;;;;;;AAST,SAAgB,yBAAyB,KAAoD;AAC3F,oBAAmB;;;;;;;;;;;;;;;;;;;;;;;;AA2BrB,SAAgB,aACd,MACA,SACqB;CACrB,MAAM,EAAE,OAAO,GAAG,eAAe;CACjC,MAAM,kBAAiC,EAAE,GAAG,YAAY;AAExD,QAAO;EACL;EACA,SAAS;EACT;EAEA,MAAM,YAAwB;GAC5B,MAAM,EAAE,YAAY,MAAM,OAAO,iCAAA,MAAA,MAAA,EAAA,EAAA;GAEjC,MAAM,MADM,SAAS,CACL,IAAI,KAAK;AACzB,UAAO,MAAM,MAAM,IAAI;;EAGzB,MAAM,UAAU,OAAyB;GACvC,MAAM,EAAE,YAAY,MAAM,OAAO,iCAAA,MAAA,MAAA,EAAA,EAAA;GACjC,MAAM,aAAa,MAAM,UAAU,MAAM;AACzC,OAAI,eAAe,KACjB,UAAS,CAAC,OAAO,MAAM;IACrB,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACzB,CAAC;OAEF,UAAS,CAAC,IAAI,MAAM,YAAY,gBAAgB;;EAIpD,MAAM,eAA8B;GAClC,MAAM,EAAE,YAAY,MAAM,OAAO,iCAAA,MAAA,MAAA,EAAA,EAAA;AACjC,YAAS,CAAC,OAAO,MAAM;IACrB,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACzB,CAAC;;EAGJ,YAAiD;GAC/C,MAAM,EAAE,WAAW,iBAAiB,oBAAoB;GAYxD,MAAM,CAAC,KAAK,QAAQ,aAAa,aAAa,MATN;IACtC,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACxB,QAAQ,gBAAgB;IACxB,SAAS,gBAAgB;IACzB,UAAU,gBAAgB;IAC1B,QAAQ,gBAAgB;IACzB,CAE8D;GAC/D,MAAM,SAAS,MAAM,MAAM,IAAI;GAE/B,MAAM,YAAY,UAAmB;IACnC,MAAM,aAAa,MAAM,UAAU,MAAM;AACzC,QAAI,eAAe,KACjB,YAAW;QAEX,QAAO,WAAW;;AAItB,UAAO;IAAC;IAAQ;IAAU;IAAU;;EAEvC"}
+{"version":3,"file":"define-cookie-k9btcEfI.js","names":[],"sources":["../../src/cookies/define-cookie.ts"],"sourcesContent":["/**\n * defineCookie — typed cookie definitions.\n *\n * Bundles name + codec + options into a reusable CookieDefinition<T>\n * with async .getCookie(), .setCookie(), .deleteCookie() server methods\n * and a sync .useCookie() client hook.\n *\n * Server methods are async to future-proof the API for v2 features\n * (signed cookies via crypto.subtle, encrypted cookies, external stores).\n *\n * Reuses the SearchParamCodec protocol via fromSchema() bridge.\n * Validation on read returns the codec default (never throws).\n *\n * IMPORTANT: This module must NOT have top-level value imports from either\n * server or client modules. Server methods lazy-import request-context;\n * useCookie() lazy-imports use-cookie. This ensures:\n * - Client bundles don't pull in ALS/server code\n * - RSC bundles don't pull in useSyncExternalStore/client code\n * - Tree-shaking is not required for correctness\n *\n * See design/29-cookies.md §\"Typed Cookies with Schema Validation\"\n */\n\nimport type { CookieOptions } from '#/server/request-context.js';\nimport type { ClientCookieOptions } from '#/client/use-cookie.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\nimport type { Codec } from '#/codec.js';\n\n/**\n * A codec that converts between string cookie values and typed values.\n * Type alias for the shared Codec<T> protocol.\n */\nexport type CookieCodec<T> = Codec<T>;\n\n/** Options for defineCookie: codec + CookieOptions merged. */\nexport interface DefineCookieOptions<T> extends CookieOptions {\n  /** Codec for parsing/serializing the cookie value. */\n  codec: CookieCodec<T>;\n}\n\n/** A fully typed cookie definition with server and client methods. */\nexport interface CookieDefinition<T> {\n  /** The cookie name. */\n  readonly name: string;\n  /** The resolved cookie options (without codec). */\n  readonly options: CookieOptions;\n  /** The codec used for parsing/serializing. */\n  readonly codec: CookieCodec<T>;\n\n  /** Server: read the typed value from the current request. */\n  getCookie(): Promise<T>;\n  /** Server: set the typed value on the response. */\n  setCookie(value: T): Promise<void>;\n  /** Server: delete the cookie. */\n  deleteCookie(): Promise<void>;\n\n  /** Client: React hook for reading/writing this cookie. Returns [value, setter, deleter]. */\n  useCookie(): [T, (value: T) => void, () => void];\n}\n\n// ─── Lazy Module References ───────────────────────────────────────────────\n//\n// These are resolved on first use, not at module load time. This prevents\n// the server module graph from pulling in client code and vice versa.\n// The dynamic import() in server methods is natural (they're async).\n// For useCookie() (sync), we cache the module reference after first load.\n\nlet _useCookieModule: typeof import('#/client/use-cookie.js') | undefined;\n\nfunction getUseCookieModule(): typeof import('#/client/use-cookie.js') {\n  if (!_useCookieModule) {\n    // In the client/SSR environment, this module is already in the module\n    // graph (imported by the client entry). The throw is a safeguard —\n    // if useCookie() is somehow called before the module is available,\n    // the developer gets a clear error instead of a silent failure.\n    throw new Error(\n      '[timber] defineCookie().useCookie() requires @timber-js/app/client to be loaded. ' +\n        'This hook can only be used in client components.'\n    );\n  }\n  return _useCookieModule;\n}\n\n/**\n * Register the client cookie module. Called by the client entry to wire\n * up the lazy reference without a top-level import.\n *\n * @internal — framework use only\n */\nexport function _registerUseCookieModule(mod: typeof import('#/client/use-cookie.js')): void {\n  _useCookieModule = mod;\n}\n\n// ─── Factory ──────────────────────────────────────────────────────────────\n\n/**\n * Define a typed cookie.\n *\n * ```ts\n * import { defineCookie } from '@timber-js/app/cookies';\n * import { fromSchema } from '@timber-js/app/search-params';\n * import { z } from 'zod/v4';\n *\n * export const themeCookie = defineCookie('theme', {\n *   codec: fromSchema(z.enum(['light', 'dark', 'system']).default('system')),\n *   httpOnly: false,\n *   maxAge: 60 * 60 * 24 * 365,\n * });\n *\n * // Server\n * const theme = await themeCookie.getCookie();\n * await themeCookie.setCookie('dark');\n *\n * // Client\n * const [theme, setTheme] = themeCookie.useCookie();\n * ```\n */\nexport function defineCookie<T>(\n  name: string,\n  options: DefineCookieOptions<T>\n): CookieDefinition<T> {\n  const { codec, ...cookieOpts } = options;\n  const resolvedOptions: CookieOptions = { ...cookieOpts };\n\n  return {\n    name,\n    options: resolvedOptions,\n    codec,\n\n    async getCookie(): Promise<T> {\n      const { cookies } = await import('#/server/request-context.js');\n      const jar = cookies();\n      const raw = jar.get(name);\n      return codec.parse(raw);\n    },\n\n    async setCookie(value: T): Promise<void> {\n      const { cookies } = await import('#/server/request-context.js');\n      const serialized = codec.serialize(value);\n      if (serialized === null) {\n        cookies().delete(name, {\n          path: resolvedOptions.path,\n          domain: resolvedOptions.domain,\n        });\n      } else {\n        cookies().set(name, serialized, resolvedOptions);\n      }\n    },\n\n    async deleteCookie(): Promise<void> {\n      const { cookies } = await import('#/server/request-context.js');\n      cookies().delete(name, {\n        path: resolvedOptions.path,\n        domain: resolvedOptions.domain,\n      });\n    },\n\n    useCookie(): [T, (value: T) => void, () => void] {\n      const { useCookie: useRawCookie } = getUseCookieModule();\n\n      // Extract client-safe options (no httpOnly — client cookies can't be httpOnly)\n      const clientOpts: ClientCookieOptions = {\n        path: resolvedOptions.path,\n        domain: resolvedOptions.domain,\n        maxAge: resolvedOptions.maxAge,\n        expires: resolvedOptions.expires,\n        sameSite: resolvedOptions.sameSite,\n        secure: resolvedOptions.secure,\n      };\n\n      const [raw, setRaw, deleteRaw] = useRawCookie(name, clientOpts);\n      const parsed = codec.parse(raw);\n\n      const setTyped = (value: T): void => {\n        const serialized = codec.serialize(value);\n        if (serialized === null) {\n          deleteRaw();\n        } else {\n          setRaw(serialized);\n        }\n      };\n\n      return [parsed, setTyped, deleteRaw];\n    },\n  };\n}\n"],"mappings":";AAqEA,IAAI;AAEJ,SAAS,qBAA8D;AACrE,KAAI,CAAC,iBAKH,OAAM,IAAI,MACR,oIAED;AAEH,QAAO;;;;;;;;AAST,SAAgB,yBAAyB,KAAoD;AAC3F,oBAAmB;;;;;;;;;;;;;;;;;;;;;;;;AA2BrB,SAAgB,aACd,MACA,SACqB;CACrB,MAAM,EAAE,OAAO,GAAG,eAAe;CACjC,MAAM,kBAAiC,EAAE,GAAG,YAAY;AAExD,QAAO;EACL;EACA,SAAS;EACT;EAEA,MAAM,YAAwB;GAC5B,MAAM,EAAE,YAAY,MAAM,OAAO,iCAAA,MAAA,MAAA,EAAA,EAAA;GAEjC,MAAM,MADM,SAAS,CACL,IAAI,KAAK;AACzB,UAAO,MAAM,MAAM,IAAI;;EAGzB,MAAM,UAAU,OAAyB;GACvC,MAAM,EAAE,YAAY,MAAM,OAAO,iCAAA,MAAA,MAAA,EAAA,EAAA;GACjC,MAAM,aAAa,MAAM,UAAU,MAAM;AACzC,OAAI,eAAe,KACjB,UAAS,CAAC,OAAO,MAAM;IACrB,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACzB,CAAC;OAEF,UAAS,CAAC,IAAI,MAAM,YAAY,gBAAgB;;EAIpD,MAAM,eAA8B;GAClC,MAAM,EAAE,YAAY,MAAM,OAAO,iCAAA,MAAA,MAAA,EAAA,EAAA;AACjC,YAAS,CAAC,OAAO,MAAM;IACrB,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACzB,CAAC;;EAGJ,YAAiD;GAC/C,MAAM,EAAE,WAAW,iBAAiB,oBAAoB;GAYxD,MAAM,CAAC,KAAK,QAAQ,aAAa,aAAa,MATN;IACtC,MAAM,gBAAgB;IACtB,QAAQ,gBAAgB;IACxB,QAAQ,gBAAgB;IACxB,SAAS,gBAAgB;IACzB,UAAU,gBAAgB;IAC1B,QAAQ,gBAAgB;IACzB,CAE8D;GAC/D,MAAM,SAAS,MAAM,MAAM,IAAI;GAE/B,MAAM,YAAY,UAAmB;IACnC,MAAM,aAAa,MAAM,UAAU,MAAM;AACzC,QAAI,eAAe,KACjB,YAAW;QAEX,QAAO,WAAW;;AAItB,UAAO;IAAC;IAAQ;IAAU;IAAU;;EAEvC"}

package/dist/_chunks/{error-boundary-BAN3751q.js → error-boundary-B9vT_YK_.js}

@@ -208,4 +208,4 @@ function statusMatches(boundaryStatus, errorStatus) {
 //#endregion
 export { _setCachedSearch as a, cachedSearch as c, globalRouter as d, setSsrData as i, cachedSearchParams as l, clearSsrData as n, _setCurrentParams as o, getSsrData as r, _setGlobalRouter as s, TimberErrorBoundary as t, currentParams as u };
 
-//# sourceMappingURL=error-boundary-BAN3751q.js.map
+//# sourceMappingURL=error-boundary-B9vT_YK_.js.map

package/dist/_chunks/{error-boundary-BAN3751q.js.map → error-boundary-B9vT_YK_.js.map}

@@ -1 +1 @@
-{"version":3,"file":"error-boundary-BAN3751q.js","names":[],"sources":["../../src/client/state.ts","../../src/client/ssr-data.ts","../../src/client/error-boundary.tsx"],"sourcesContent":["/**\n * Centralized client singleton state registry.\n *\n * ALL mutable module-level state that must have singleton semantics across\n * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,\n * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file\n * and re-export thin wrapper functions.\n *\n * Why: In Vite dev, a module is instantiated separately if reached via different\n * import paths (e.g., relative `./foo.js` vs barrel `@timber-js/app/client`).\n * By centralizing all mutable state in a single module that is always reached\n * through the same dependency chain (barrel → wrapper → state.ts), we guarantee\n * a single instance of every piece of shared state.\n *\n * DO NOT import this file from outside client/. Server code must never depend\n * on client state. The barrel (client/index.ts) is the public entry point.\n *\n * See design/18-build-system.md §\"Module Singleton Strategy\" and\n * §\"Singleton State Registry\".\n */\n\nimport type { RouterInstance } from './router.js';\nimport type { SsrData } from './ssr-data.js';\n\n// ─── Router (from router-ref.ts) ──────────────────────────────────────────\n\n/** The global router singleton — set once during bootstrap. */\nexport let globalRouter: RouterInstance | null = null;\n\nexport function _setGlobalRouter(router: RouterInstance | null): void {\n  globalRouter = router;\n}\n\n// ─── SSR Data Provider (from ssr-data.ts) ──────────────────────────────────\n\n/**\n * ALS-backed SSR data provider. When registered, getSsrData() reads from\n * this function (ALS store) instead of module-level currentSsrData.\n */\nexport let ssrDataProvider: (() => SsrData | undefined) | undefined;\n\nexport function _setSsrDataProvider(provider: (() => SsrData | undefined) | undefined): void {\n  ssrDataProvider = provider;\n}\n\n/** Fallback SSR data for tests and environments without ALS. */\nexport let currentSsrData: SsrData | undefined;\n\nexport function _setCurrentSsrData(data: SsrData | undefined): void {\n  currentSsrData = data;\n}\n\n// ─── Route Params (from use-params.ts) ──────────────────────────────────────\n\n/** Current route params snapshot — replaced (not mutated) on each navigation. */\nexport let currentParams: Record<string, string | string[]> = {};\n\nexport function _setCurrentParams(params: Record<string, string | string[]>): void {\n  currentParams = params;\n}\n\n/** Listeners notified when currentParams changes. */\nexport const paramsListeners = new Set<() => void>();\n\n// ─── Search Params Cache (from use-search-params.ts) ────────────────────────\n\n/** Cached search string — avoids reparsing when URL hasn't changed. */\nexport let cachedSearch = '';\nexport let cachedSearchParams = new URLSearchParams();\n\nexport function _setCachedSearch(search: string, params: URLSearchParams): void {\n  cachedSearch = search;\n  cachedSearchParams = params;\n}\n\n// ─── Unload Guard (from unload-guard.ts) ─────────────────────────────────────\n\n/** Whether the page is currently being unloaded. */\nexport let unloading = false;\n\nexport function _setUnloading(value: boolean): void {\n  unloading = value;\n}\n","/**\n * SSR Data — per-request state for client hooks during server-side rendering.\n *\n * RSC and SSR are separate Vite module graphs (see design/18-build-system.md),\n * so the RSC environment's request-context ALS is not visible to SSR modules.\n * This module provides getter/setter functions that ssr-entry.ts uses to\n * populate per-request data for React's render.\n *\n * Request isolation: On the server, ssr-entry.ts registers an ALS-backed\n * provider via registerSsrDataProvider(). getSsrData() reads from the ALS\n * store, ensuring correct per-request data even when Suspense boundaries\n * resolve asynchronously across concurrent requests. The module-level\n * setSsrData/clearSsrData functions are kept as a fallback for tests\n * and environments without ALS.\n *\n * IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only\n * APIs, as it's imported by 'use client' hooks that are bundled for the browser.\n * The ALS instance lives in ssr-entry.ts (server-only); this module only holds\n * a reference to the provider function.\n *\n * All mutable state is delegated to client/state.ts for singleton guarantees.\n * See design/18-build-system.md §\"Singleton State Registry\"\n */\n\nimport {\n  ssrDataProvider,\n  currentSsrData,\n  _setSsrDataProvider,\n  _setCurrentSsrData,\n} from './state.js';\n\n// ─── Types ────────────────────────────────────────────────────────\n\nexport interface SsrData {\n  /** The request's URL pathname (e.g. '/dashboard/settings') */\n  pathname: string;\n  /** The request's search params as a plain record */\n  searchParams: Record<string, string>;\n  /** The request's cookies as name→value pairs */\n  cookies: Map<string, string>;\n  /** The request's route params (e.g. { id: '123' }) */\n  params: Record<string, string | string[]>;\n  /**\n   * Mutable reference to NavContext for error boundary → RSC communication.\n   * When TimberErrorBoundary catches a DenySignal, it sets\n   * `_navContext._denyHandledByBoundary = true` to prevent the RSC entry\n   * from promoting the denial to page-level. See LOCAL-298.\n   */\n  _navContext?: { _denyHandledByBoundary?: boolean };\n}\n\n// ─── ALS-Backed Provider ─────────────────────────────────────────\n//\n// Server-side code (ssr-entry.ts) registers a provider that reads\n// from AsyncLocalStorage. This avoids importing node:async_hooks\n// in this browser-bundled module.\n//\n// Module singleton guarantee: In Vite's SSR environment, both\n// ssr-entry.ts (via #/client/ssr-data.js) and client component hooks\n// (via @timber-js/app/client) must resolve to the SAME module instance\n// of this file. The timber-shims plugin ensures this by remapping\n// @timber-js/app/client → src/client/index.ts in the SSR environment.\n// Without this remap, @timber-js/app/client resolves to dist/ (via\n// package.json exports), creating a split where registerSsrDataProvider\n// writes to one instance but getSsrData reads from another.\n// See timber-shims plugin resolveId for details.\n\n/**\n * Register an ALS-backed SSR data provider. Called once at module load\n * by ssr-entry.ts to wire up per-request data via AsyncLocalStorage.\n *\n * When registered, getSsrData() reads from the provider (ALS store)\n * instead of module-level state, ensuring correct isolation for\n * concurrent requests with streaming Suspense.\n */\nexport function registerSsrDataProvider(provider: () => SsrData | undefined): void {\n  _setSsrDataProvider(provider);\n}\n\n// ─── Module-Level Fallback ────────────────────────────────────────\n//\n// Used by tests and as a fallback when no ALS provider is registered.\n\n/**\n * Set the SSR data for the current request via module-level state.\n *\n * In production, ssr-entry.ts uses ALS (runWithSsrData) instead.\n * This function is retained for tests and as a fallback.\n */\nexport function setSsrData(data: SsrData): void {\n  _setCurrentSsrData(data);\n}\n\n/**\n * Clear the SSR data after rendering completes.\n *\n * In production, ALS scope handles cleanup automatically.\n * This function is retained for tests and as a fallback.\n */\nexport function clearSsrData(): void {\n  _setCurrentSsrData(undefined);\n}\n\n/**\n * Read the current request's SSR data. Returns undefined when called\n * outside an SSR render (i.e. on the client after hydration).\n *\n * Prefers the ALS-backed provider when registered (server-side),\n * falling back to module-level state (tests, legacy).\n *\n * Used by client hooks' server snapshot functions.\n */\nexport function getSsrData(): SsrData | undefined {\n  if (ssrDataProvider) {\n    return ssrDataProvider();\n  }\n  return currentSsrData;\n}\n","'use client';\n\n/**\n * Framework-injected React error boundary.\n *\n * Catches errors thrown by children and renders a fallback component\n * with the appropriate props based on error type:\n *   - DenySignal (4xx) → { status, dangerouslyPassData }\n *   - RenderError (5xx) → { error, digest, reset }\n *   - Unhandled error → { error, digest: null, reset }\n *\n * The `status` prop controls which errors this boundary catches:\n *   - Specific code (e.g. 403) → only that status\n *   - Category (400) → any 4xx\n *   - Category (500) → any 5xx\n *   - Omitted → catches everything (error.tsx behavior)\n *\n * See design/10-error-handling.md §\"Status-Code Files\"\n */\n\nimport { Component, createElement, type ReactNode } from 'react';\nimport { getSsrData } from './ssr-data.js';\n\n// ─── Page Unload Detection ───────────────────────────────────────────────────\n// Track whether the page is being unloaded (user refreshed or navigated away).\n// When this is true, error boundaries suppress activation — the error is from\n// the aborted connection, not an application error.\nlet _isUnloading = false;\nif (typeof window !== 'undefined') {\n  window.addEventListener('beforeunload', () => {\n    _isUnloading = true;\n  });\n  window.addEventListener('pagehide', () => {\n    _isUnloading = true;\n  });\n}\n\n// ─── Digest Types ────────────────────────────────────────────────────────────\n\n/** Structured digest returned by RSC onError for DenySignal. */\ninterface DenyDigest {\n  type: 'deny';\n  status: number;\n  data: unknown;\n}\n\n/** Structured digest returned by RSC onError for RenderError. */\ninterface RenderErrorDigest {\n  type: 'render-error';\n  code: string;\n  data: unknown;\n  status: number;\n}\n\n/** Structured digest returned by RSC onError for RedirectSignal. */\ninterface RedirectDigest {\n  type: 'redirect';\n  location: string;\n  status: number;\n}\n\ntype ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;\n\n// ─── Props & State ───────────────────────────────────────────────────────────\n\nexport interface TimberErrorBoundaryProps {\n  /** The component to render when an error is caught. */\n  fallbackComponent?: (...args: unknown[]) => ReactNode;\n  /**\n   * Pre-rendered fallback element. Used for MDX status files which are server\n   * components and cannot be passed as function props across the RSC→client\n   * boundary. When set, rendered directly instead of calling fallbackComponent.\n   *\n   * See design/10-error-handling.md §\"Status-Code File Variants\" — MDX status\n   * files are server components by default (zero client JS).\n   */\n  fallbackElement?: ReactNode;\n  /**\n   * Status code filter. If set, only catches errors matching this status.\n   * 400 = any 4xx, 500 = any 5xx, specific number = exact match.\n   */\n  status?: number;\n  /**\n   * When true, catching a DenySignal sets _denyHandledByBoundary on the\n   * nav context to prevent page-level deny promotion. Only slot catch-all\n   * boundaries should set this — segment boundaries (403.tsx, 4xx.tsx,\n   * error.tsx) must NOT, otherwise normal page denies get swallowed.\n   */\n  isSlotBoundary?: boolean;\n  children: ReactNode;\n}\n\ninterface TimberErrorBoundaryState {\n  hasError: boolean;\n  error: Error | null;\n}\n\n// ─── Component ───────────────────────────────────────────────────────────────\n\nexport class TimberErrorBoundary extends Component<\n  TimberErrorBoundaryProps,\n  TimberErrorBoundaryState\n> {\n  constructor(props: TimberErrorBoundaryProps) {\n    super(props);\n    this.state = { hasError: false, error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): TimberErrorBoundaryState {\n    // Suppress error boundaries during page unload (refresh/navigate away).\n    // The aborted connection causes React's streaming hydration to error,\n    // but the page is about to be replaced — showing an error boundary\n    // would be a jarring flash for the user.\n    if (_isUnloading) {\n      return { hasError: false, error: null };\n    }\n\n    return { hasError: true, error };\n  }\n\n  componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {\n    // Reset error state when children change (e.g. client-side navigation).\n    // Without this, navigating from one error page to another keeps the\n    // stale error — getDerivedStateFromError doesn't re-fire for new children.\n    if (this.state.hasError && prevProps.children !== this.props.children) {\n      this.setState({ hasError: false, error: null });\n    }\n  }\n\n  /** Reset the error state so children re-render. */\n  private reset = () => {\n    this.setState({ hasError: false, error: null });\n  };\n\n  render(): ReactNode {\n    if (!this.state.hasError || !this.state.error) {\n      return this.props.children;\n    }\n\n    const error = this.state.error;\n    const parsed = parseDigest(error);\n\n    // RedirectSignal errors must propagate through all error boundaries\n    // so the SSR shell fails and the pipeline catch block can produce a\n    // proper HTTP redirect response. See design/04-authorization.md.\n    if (parsed?.type === 'redirect') {\n      throw error;\n    }\n\n    // If this boundary has a status filter, check whether the error matches.\n    // Non-matching errors re-throw so an outer boundary can catch them.\n    if (this.props.status != null) {\n      const errorStatus = getErrorStatus(parsed, error);\n      if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) {\n        // Re-throw: this boundary doesn't handle this error.\n        throw error;\n      }\n    }\n\n    // Report DenySignal handling to prevent page-level promotion — but only\n    // for slot boundaries. Segment boundaries (403.tsx, 4xx.tsx, error.tsx)\n    // must NOT set this flag, otherwise normal page/hold-window denies get\n    // swallowed as 200 with boundary HTML instead of the intended 4xx.\n    // Runs here in render() (not getDerivedStateFromError) so the status\n    // filter has already been applied — non-matching boundaries re-threw above.\n    // See LOCAL-298.\n    if (parsed?.type === 'deny' && this.props.isSlotBoundary) {\n      const ssrData = getSsrData();\n      if (ssrData?._navContext) {\n        ssrData._navContext._denyHandledByBoundary = true;\n      }\n    }\n\n    // Pre-rendered fallback element (MDX status files) — render directly.\n    // MDX components are server components that cannot be passed as function\n    // props across the RSC→client boundary. Instead, they are pre-rendered\n    // as elements in the RSC environment and passed here as fallbackElement.\n    if (this.props.fallbackElement != null) {\n      return this.props.fallbackElement;\n    }\n\n    // Render the fallback component with the right props shape.\n    if (parsed?.type === 'deny') {\n      return createElement(this.props.fallbackComponent as never, {\n        status: parsed.status,\n        dangerouslyPassData: parsed.data,\n      });\n    }\n\n    // 5xx / RenderError / unhandled error\n    const digest =\n      parsed?.type === 'render-error' ? { code: parsed.code, data: parsed.data } : null;\n\n    return createElement(this.props.fallbackComponent as never, {\n      error,\n      digest,\n      reset: this.reset,\n    });\n  }\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\n/**\n * Parse the structured digest from the error.\n * React sets `error.digest` from the string returned by RSC's onError.\n */\nfunction parseDigest(error: Error): ParsedDigest | null {\n  const raw = (error as { digest?: string }).digest;\n  if (typeof raw !== 'string') return null;\n  try {\n    const parsed = JSON.parse(raw);\n    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {\n      return parsed as ParsedDigest;\n    }\n  } catch {\n    // Not JSON — legacy or unknown digest format\n  }\n  return null;\n}\n\n/**\n * Extract the HTTP status code from a parsed digest or error message.\n * Falls back to message pattern matching for errors without a digest.\n */\nfunction getErrorStatus(parsed: ParsedDigest | null, error: Error): number | null {\n  if (parsed?.type === 'deny') return parsed.status;\n  if (parsed?.type === 'render-error') return parsed.status;\n  if (parsed?.type === 'redirect') return parsed.status;\n\n  // Fallback: parse DenySignal message pattern for errors that lost their digest\n  const match = error.message.match(/^Access denied with status (\\d+)$/);\n  if (match) return parseInt(match[1], 10);\n\n  // Unhandled errors are implicitly 500\n  return 500;\n}\n\n/**\n * Check whether an error's status matches the boundary's status filter.\n * Category markers (400, 500) match any status in that range.\n */\nfunction statusMatches(boundaryStatus: number, errorStatus: number): boolean {\n  // Category catch-all: 400 matches any 4xx, 500 matches any 5xx\n  if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;\n  if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;\n  // Exact match\n  return boundaryStatus === errorStatus;\n}\n"],"mappings":";;;AA2BA,IAAW,eAAsC;AAEjD,SAAgB,iBAAiB,QAAqC;AACpE,gBAAe;;;;;;AASjB,IAAW;;AAOX,IAAW;AAEX,SAAgB,mBAAmB,MAAiC;AAClE,kBAAiB;;;AAMnB,IAAW,gBAAmD,EAAE;AAEhE,SAAgB,kBAAkB,QAAiD;AACjF,iBAAgB;;;AASlB,IAAW,eAAe;AAC1B,IAAW,qBAAqB,IAAI,iBAAiB;AAErD,SAAgB,iBAAiB,QAAgB,QAA+B;AAC9E,gBAAe;AACf,sBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACiBvB,SAAgB,WAAW,MAAqB;AAC9C,oBAAmB,KAAK;;;;;;;;AAS1B,SAAgB,eAAqB;AACnC,oBAAmB,KAAA,EAAU;;;;;;;;;;;AAY/B,SAAgB,aAAkC;AAChD,KAAI,gBACF,QAAO,iBAAiB;AAE1B,QAAO;;;;;;;;;;;;;;;;;;;;;ACzFT,IAAI,eAAe;AACnB,IAAI,OAAO,WAAW,aAAa;AACjC,QAAO,iBAAiB,sBAAsB;AAC5C,iBAAe;GACf;AACF,QAAO,iBAAiB,kBAAkB;AACxC,iBAAe;GACf;;AAiEJ,IAAa,sBAAb,cAAyC,UAGvC;CACA,YAAY,OAAiC;AAC3C,QAAM,MAAM;AACZ,OAAK,QAAQ;GAAE,UAAU;GAAO,OAAO;GAAM;;CAG/C,OAAO,yBAAyB,OAAwC;AAKtE,MAAI,aACF,QAAO;GAAE,UAAU;GAAO,OAAO;GAAM;AAGzC,SAAO;GAAE,UAAU;GAAM;GAAO;;CAGlC,mBAAmB,WAA2C;AAI5D,MAAI,KAAK,MAAM,YAAY,UAAU,aAAa,KAAK,MAAM,SAC3D,MAAK,SAAS;GAAE,UAAU;GAAO,OAAO;GAAM,CAAC;;;CAKnD,cAAsB;AACpB,OAAK,SAAS;GAAE,UAAU;GAAO,OAAO;GAAM,CAAC;;CAGjD,SAAoB;AAClB,MAAI,CAAC,KAAK,MAAM,YAAY,CAAC,KAAK,MAAM,MACtC,QAAO,KAAK,MAAM;EAGpB,MAAM,QAAQ,KAAK,MAAM;EACzB,MAAM,SAAS,YAAY,MAAM;AAKjC,MAAI,QAAQ,SAAS,WACnB,OAAM;AAKR,MAAI,KAAK,MAAM,UAAU,MAAM;GAC7B,MAAM,cAAc,eAAe,QAAQ,MAAM;AACjD,OAAI,eAAe,QAAQ,CAAC,cAAc,KAAK,MAAM,QAAQ,YAAY,CAEvE,OAAM;;AAWV,MAAI,QAAQ,SAAS,UAAU,KAAK,MAAM,gBAAgB;GACxD,MAAM,UAAU,YAAY;AAC5B,OAAI,SAAS,YACX,SAAQ,YAAY,yBAAyB;;AAQjD,MAAI,KAAK,MAAM,mBAAmB,KAChC,QAAO,KAAK,MAAM;AAIpB,MAAI,QAAQ,SAAS,OACnB,QAAO,cAAc,KAAK,MAAM,mBAA4B;GAC1D,QAAQ,OAAO;GACf,qBAAqB,OAAO;GAC7B,CAAC;EAIJ,MAAM,SACJ,QAAQ,SAAS,iBAAiB;GAAE,MAAM,OAAO;GAAM,MAAM,OAAO;GAAM,GAAG;AAE/E,SAAO,cAAc,KAAK,MAAM,mBAA4B;GAC1D;GACA;GACA,OAAO,KAAK;GACb,CAAC;;;;;;;AAUN,SAAS,YAAY,OAAmC;CACtD,MAAM,MAAO,MAA8B;AAC3C,KAAI,OAAO,QAAQ,SAAU,QAAO;AACpC,KAAI;EACF,MAAM,SAAS,KAAK,MAAM,IAAI;AAC9B,MAAI,UAAU,OAAO,WAAW,YAAY,OAAO,OAAO,SAAS,SACjE,QAAO;SAEH;AAGR,QAAO;;;;;;AAOT,SAAS,eAAe,QAA6B,OAA6B;AAChF,KAAI,QAAQ,SAAS,OAAQ,QAAO,OAAO;AAC3C,KAAI,QAAQ,SAAS,eAAgB,QAAO,OAAO;AACnD,KAAI,QAAQ,SAAS,WAAY,QAAO,OAAO;CAG/C,MAAM,QAAQ,MAAM,QAAQ,MAAM,oCAAoC;AACtE,KAAI,MAAO,QAAO,SAAS,MAAM,IAAI,GAAG;AAGxC,QAAO;;;;;;AAOT,SAAS,cAAc,gBAAwB,aAA8B;AAE3E,KAAI,mBAAmB,IAAK,QAAO,eAAe,OAAO,eAAe;AACxE,KAAI,mBAAmB,IAAK,QAAO,eAAe,OAAO,eAAe;AAExE,QAAO,mBAAmB"}
+{"version":3,"file":"error-boundary-B9vT_YK_.js","names":[],"sources":["../../src/client/state.ts","../../src/client/ssr-data.ts","../../src/client/error-boundary.tsx"],"sourcesContent":["/**\n * Centralized client singleton state registry.\n *\n * ALL mutable module-level state that must have singleton semantics across\n * the client bundle lives here. Individual modules (router-ref.ts, ssr-data.ts,\n * use-params.ts, use-search-params.ts, unload-guard.ts) import from this file\n * and re-export thin wrapper functions.\n *\n * Why: In Vite dev, a module is instantiated separately if reached via different\n * import paths (e.g., relative `./foo.js` vs barrel `@timber-js/app/client`).\n * By centralizing all mutable state in a single module that is always reached\n * through the same dependency chain (barrel → wrapper → state.ts), we guarantee\n * a single instance of every piece of shared state.\n *\n * DO NOT import this file from outside client/. Server code must never depend\n * on client state. The barrel (client/index.ts) is the public entry point.\n *\n * See design/18-build-system.md §\"Module Singleton Strategy\" and\n * §\"Singleton State Registry\".\n */\n\nimport type { RouterInstance } from './router.js';\nimport type { SsrData } from './ssr-data.js';\n\n// ─── Router (from router-ref.ts) ──────────────────────────────────────────\n\n/** The global router singleton — set once during bootstrap. */\nexport let globalRouter: RouterInstance | null = null;\n\nexport function _setGlobalRouter(router: RouterInstance | null): void {\n  globalRouter = router;\n}\n\n// ─── SSR Data Provider (from ssr-data.ts) ──────────────────────────────────\n\n/**\n * ALS-backed SSR data provider. When registered, getSsrData() reads from\n * this function (ALS store) instead of module-level currentSsrData.\n */\nexport let ssrDataProvider: (() => SsrData | undefined) | undefined;\n\nexport function _setSsrDataProvider(provider: (() => SsrData | undefined) | undefined): void {\n  ssrDataProvider = provider;\n}\n\n/** Fallback SSR data for tests and environments without ALS. */\nexport let currentSsrData: SsrData | undefined;\n\nexport function _setCurrentSsrData(data: SsrData | undefined): void {\n  currentSsrData = data;\n}\n\n// ─── Route Params (from use-params.ts) ──────────────────────────────────────\n\n/** Current route params snapshot — replaced (not mutated) on each navigation. */\nexport let currentParams: Record<string, string | string[]> = {};\n\nexport function _setCurrentParams(params: Record<string, string | string[]>): void {\n  currentParams = params;\n}\n\n/** Listeners notified when currentParams changes. */\nexport const paramsListeners = new Set<() => void>();\n\n// ─── Search Params Cache (from use-search-params.ts) ────────────────────────\n\n/** Cached search string — avoids reparsing when URL hasn't changed. */\nexport let cachedSearch = '';\nexport let cachedSearchParams = new URLSearchParams();\n\nexport function _setCachedSearch(search: string, params: URLSearchParams): void {\n  cachedSearch = search;\n  cachedSearchParams = params;\n}\n\n// ─── Unload Guard (from unload-guard.ts) ─────────────────────────────────────\n\n/** Whether the page is currently being unloaded. */\nexport let unloading = false;\n\nexport function _setUnloading(value: boolean): void {\n  unloading = value;\n}\n","/**\n * SSR Data — per-request state for client hooks during server-side rendering.\n *\n * RSC and SSR are separate Vite module graphs (see design/18-build-system.md),\n * so the RSC environment's request-context ALS is not visible to SSR modules.\n * This module provides getter/setter functions that ssr-entry.ts uses to\n * populate per-request data for React's render.\n *\n * Request isolation: On the server, ssr-entry.ts registers an ALS-backed\n * provider via registerSsrDataProvider(). getSsrData() reads from the ALS\n * store, ensuring correct per-request data even when Suspense boundaries\n * resolve asynchronously across concurrent requests. The module-level\n * setSsrData/clearSsrData functions are kept as a fallback for tests\n * and environments without ALS.\n *\n * IMPORTANT: This module must NOT import node:async_hooks or any Node.js-only\n * APIs, as it's imported by 'use client' hooks that are bundled for the browser.\n * The ALS instance lives in ssr-entry.ts (server-only); this module only holds\n * a reference to the provider function.\n *\n * All mutable state is delegated to client/state.ts for singleton guarantees.\n * See design/18-build-system.md §\"Singleton State Registry\"\n */\n\nimport {\n  ssrDataProvider,\n  currentSsrData,\n  _setSsrDataProvider,\n  _setCurrentSsrData,\n} from './state.js';\n\n// ─── Types ────────────────────────────────────────────────────────\n\nexport interface SsrData {\n  /** The request's URL pathname (e.g. '/dashboard/settings') */\n  pathname: string;\n  /** The request's search params as a plain record */\n  searchParams: Record<string, string>;\n  /** The request's cookies as name→value pairs */\n  cookies: Map<string, string>;\n  /** The request's route params (e.g. { id: '123' }) */\n  params: Record<string, string | string[]>;\n  /**\n   * Mutable reference to NavContext for error boundary → RSC communication.\n   * When TimberErrorBoundary catches a DenySignal, it sets\n   * `_navContext._denyHandledByBoundary = true` to prevent the RSC entry\n   * from promoting the denial to page-level. See LOCAL-298.\n   */\n  _navContext?: { _denyHandledByBoundary?: boolean };\n}\n\n// ─── ALS-Backed Provider ─────────────────────────────────────────\n//\n// Server-side code (ssr-entry.ts) registers a provider that reads\n// from AsyncLocalStorage. This avoids importing node:async_hooks\n// in this browser-bundled module.\n//\n// Module singleton guarantee: In Vite's SSR environment, both\n// ssr-entry.ts (via #/client/ssr-data.js) and client component hooks\n// (via @timber-js/app/client) must resolve to the SAME module instance\n// of this file. The timber-shims plugin ensures this by remapping\n// @timber-js/app/client → src/client/index.ts in the SSR environment.\n// Without this remap, @timber-js/app/client resolves to dist/ (via\n// package.json exports), creating a split where registerSsrDataProvider\n// writes to one instance but getSsrData reads from another.\n// See timber-shims plugin resolveId for details.\n\n/**\n * Register an ALS-backed SSR data provider. Called once at module load\n * by ssr-entry.ts to wire up per-request data via AsyncLocalStorage.\n *\n * When registered, getSsrData() reads from the provider (ALS store)\n * instead of module-level state, ensuring correct isolation for\n * concurrent requests with streaming Suspense.\n */\nexport function registerSsrDataProvider(provider: () => SsrData | undefined): void {\n  _setSsrDataProvider(provider);\n}\n\n// ─── Module-Level Fallback ────────────────────────────────────────\n//\n// Used by tests and as a fallback when no ALS provider is registered.\n\n/**\n * Set the SSR data for the current request via module-level state.\n *\n * In production, ssr-entry.ts uses ALS (runWithSsrData) instead.\n * This function is retained for tests and as a fallback.\n */\nexport function setSsrData(data: SsrData): void {\n  _setCurrentSsrData(data);\n}\n\n/**\n * Clear the SSR data after rendering completes.\n *\n * In production, ALS scope handles cleanup automatically.\n * This function is retained for tests and as a fallback.\n */\nexport function clearSsrData(): void {\n  _setCurrentSsrData(undefined);\n}\n\n/**\n * Read the current request's SSR data. Returns undefined when called\n * outside an SSR render (i.e. on the client after hydration).\n *\n * Prefers the ALS-backed provider when registered (server-side),\n * falling back to module-level state (tests, legacy).\n *\n * Used by client hooks' server snapshot functions.\n */\nexport function getSsrData(): SsrData | undefined {\n  if (ssrDataProvider) {\n    return ssrDataProvider();\n  }\n  return currentSsrData;\n}\n","'use client';\n\n/**\n * Framework-injected React error boundary.\n *\n * Catches errors thrown by children and renders a fallback component\n * with the appropriate props based on error type:\n *   - DenySignal (4xx) → { status, dangerouslyPassData }\n *   - RenderError (5xx) → { error, digest, reset }\n *   - Unhandled error → { error, digest: null, reset }\n *\n * The `status` prop controls which errors this boundary catches:\n *   - Specific code (e.g. 403) → only that status\n *   - Category (400) → any 4xx\n *   - Category (500) → any 5xx\n *   - Omitted → catches everything (error.tsx behavior)\n *\n * See design/10-error-handling.md §\"Status-Code Files\"\n */\n\nimport { Component, createElement, type ReactNode } from 'react';\nimport { getSsrData } from './ssr-data.js';\n\n// ─── Page Unload Detection ───────────────────────────────────────────────────\n// Track whether the page is being unloaded (user refreshed or navigated away).\n// When this is true, error boundaries suppress activation — the error is from\n// the aborted connection, not an application error.\nlet _isUnloading = false;\nif (typeof window !== 'undefined') {\n  window.addEventListener('beforeunload', () => {\n    _isUnloading = true;\n  });\n  window.addEventListener('pagehide', () => {\n    _isUnloading = true;\n  });\n}\n\n// ─── Digest Types ────────────────────────────────────────────────────────────\n\n/** Structured digest returned by RSC onError for DenySignal. */\ninterface DenyDigest {\n  type: 'deny';\n  status: number;\n  data: unknown;\n}\n\n/** Structured digest returned by RSC onError for RenderError. */\ninterface RenderErrorDigest {\n  type: 'render-error';\n  code: string;\n  data: unknown;\n  status: number;\n}\n\n/** Structured digest returned by RSC onError for RedirectSignal. */\ninterface RedirectDigest {\n  type: 'redirect';\n  location: string;\n  status: number;\n}\n\ntype ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;\n\n// ─── Props & State ───────────────────────────────────────────────────────────\n\nexport interface TimberErrorBoundaryProps {\n  /** The component to render when an error is caught. */\n  fallbackComponent?: (...args: unknown[]) => ReactNode;\n  /**\n   * Pre-rendered fallback element. Used for MDX status files which are server\n   * components and cannot be passed as function props across the RSC→client\n   * boundary. When set, rendered directly instead of calling fallbackComponent.\n   *\n   * See design/10-error-handling.md §\"Status-Code File Variants\" — MDX status\n   * files are server components by default (zero client JS).\n   */\n  fallbackElement?: ReactNode;\n  /**\n   * Status code filter. If set, only catches errors matching this status.\n   * 400 = any 4xx, 500 = any 5xx, specific number = exact match.\n   */\n  status?: number;\n  /**\n   * When true, catching a DenySignal sets _denyHandledByBoundary on the\n   * nav context to prevent page-level deny promotion. Only slot catch-all\n   * boundaries should set this — segment boundaries (403.tsx, 4xx.tsx,\n   * error.tsx) must NOT, otherwise normal page denies get swallowed.\n   */\n  isSlotBoundary?: boolean;\n  children: ReactNode;\n}\n\ninterface TimberErrorBoundaryState {\n  hasError: boolean;\n  error: Error | null;\n}\n\n// ─── Component ───────────────────────────────────────────────────────────────\n\nexport class TimberErrorBoundary extends Component<\n  TimberErrorBoundaryProps,\n  TimberErrorBoundaryState\n> {\n  constructor(props: TimberErrorBoundaryProps) {\n    super(props);\n    this.state = { hasError: false, error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): TimberErrorBoundaryState {\n    // Suppress error boundaries during page unload (refresh/navigate away).\n    // The aborted connection causes React's streaming hydration to error,\n    // but the page is about to be replaced — showing an error boundary\n    // would be a jarring flash for the user.\n    if (_isUnloading) {\n      return { hasError: false, error: null };\n    }\n\n    return { hasError: true, error };\n  }\n\n  componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {\n    // Reset error state when children change (e.g. client-side navigation).\n    // Without this, navigating from one error page to another keeps the\n    // stale error — getDerivedStateFromError doesn't re-fire for new children.\n    if (this.state.hasError && prevProps.children !== this.props.children) {\n      this.setState({ hasError: false, error: null });\n    }\n  }\n\n  /** Reset the error state so children re-render. */\n  private reset = () => {\n    this.setState({ hasError: false, error: null });\n  };\n\n  render(): ReactNode {\n    if (!this.state.hasError || !this.state.error) {\n      return this.props.children;\n    }\n\n    const error = this.state.error;\n    const parsed = parseDigest(error);\n\n    // RedirectSignal errors must propagate through all error boundaries\n    // so the SSR shell fails and the pipeline catch block can produce a\n    // proper HTTP redirect response. See design/04-authorization.md.\n    if (parsed?.type === 'redirect') {\n      throw error;\n    }\n\n    // If this boundary has a status filter, check whether the error matches.\n    // Non-matching errors re-throw so an outer boundary can catch them.\n    if (this.props.status != null) {\n      const errorStatus = getErrorStatus(parsed, error);\n      if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) {\n        // Re-throw: this boundary doesn't handle this error.\n        throw error;\n      }\n    }\n\n    // Report DenySignal handling to prevent page-level promotion — but only\n    // for slot boundaries. Segment boundaries (403.tsx, 4xx.tsx, error.tsx)\n    // must NOT set this flag, otherwise normal page/hold-window denies get\n    // swallowed as 200 with boundary HTML instead of the intended 4xx.\n    // Runs here in render() (not getDerivedStateFromError) so the status\n    // filter has already been applied — non-matching boundaries re-threw above.\n    // See LOCAL-298.\n    if (parsed?.type === 'deny' && this.props.isSlotBoundary) {\n      const ssrData = getSsrData();\n      if (ssrData?._navContext) {\n        ssrData._navContext._denyHandledByBoundary = true;\n      }\n    }\n\n    // Pre-rendered fallback element (MDX status files) — render directly.\n    // MDX components are server components that cannot be passed as function\n    // props across the RSC→client boundary. Instead, they are pre-rendered\n    // as elements in the RSC environment and passed here as fallbackElement.\n    if (this.props.fallbackElement != null) {\n      return this.props.fallbackElement;\n    }\n\n    // Render the fallback component with the right props shape.\n    if (parsed?.type === 'deny') {\n      return createElement(this.props.fallbackComponent as never, {\n        status: parsed.status,\n        dangerouslyPassData: parsed.data,\n      });\n    }\n\n    // 5xx / RenderError / unhandled error\n    const digest =\n      parsed?.type === 'render-error' ? { code: parsed.code, data: parsed.data } : null;\n\n    return createElement(this.props.fallbackComponent as never, {\n      error,\n      digest,\n      reset: this.reset,\n    });\n  }\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\n/**\n * Parse the structured digest from the error.\n * React sets `error.digest` from the string returned by RSC's onError.\n */\nfunction parseDigest(error: Error): ParsedDigest | null {\n  const raw = (error as { digest?: string }).digest;\n  if (typeof raw !== 'string') return null;\n  try {\n    const parsed = JSON.parse(raw);\n    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {\n      return parsed as ParsedDigest;\n    }\n  } catch {\n    // Not JSON — legacy or unknown digest format\n  }\n  return null;\n}\n\n/**\n * Extract the HTTP status code from a parsed digest or error message.\n * Falls back to message pattern matching for errors without a digest.\n */\nfunction getErrorStatus(parsed: ParsedDigest | null, error: Error): number | null {\n  if (parsed?.type === 'deny') return parsed.status;\n  if (parsed?.type === 'render-error') return parsed.status;\n  if (parsed?.type === 'redirect') return parsed.status;\n\n  // Fallback: parse DenySignal message pattern for errors that lost their digest\n  const match = error.message.match(/^Access denied with status (\\d+)$/);\n  if (match) return parseInt(match[1], 10);\n\n  // Unhandled errors are implicitly 500\n  return 500;\n}\n\n/**\n * Check whether an error's status matches the boundary's status filter.\n * Category markers (400, 500) match any status in that range.\n */\nfunction statusMatches(boundaryStatus: number, errorStatus: number): boolean {\n  // Category catch-all: 400 matches any 4xx, 500 matches any 5xx\n  if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;\n  if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;\n  // Exact match\n  return boundaryStatus === errorStatus;\n}\n"],"mappings":"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"}

package/dist/_chunks/{request-context-BxYIJM24.js → request-context-0h-6Voad.js}

@@ -1,6 +1,7 @@
 import { n as __exportAll } from "./chunk-DYhsFzuS.js";
 import { t as isDebug } from "./debug-ECi_61pb.js";
 import { r as requestContextAls } from "./als-registry-Ba7URUIn.js";
+import { t as _setRawSearchParamsFn } from "./define-TK8C1M3x.js";
 //#region src/server/request-context.ts
 /**
 * Request Context — per-request ALS store for headers() and cookies().
@@ -155,6 +156,7 @@ function rawSearchParams() {
 	if (!store) throw new Error("[timber] rawSearchParams() called outside of a request context. It can only be used in middleware, access checks, server components, and server actions.");
 	return store.searchParamsPromise;
 }
+_setRawSearchParamsFn(rawSearchParams);
 /**
 * Returns a Promise resolving to the current request's coerced segment params.
 *
@@ -351,4 +353,4 @@ function serializeCookieEntry(entry) {
 //#endregion
 export { headers as a, rawSegmentParams as c, setMutableCookieContext as d, setSegmentParams as f, getSetCookieHeaders as i, request_context_exports as l, cookies as n, markResponseFlushed as o, getRequestSearchString as r, rawSearchParams as s, applyRequestHeaderOverlay as t, runWithRequestContext as u };
 
-//# sourceMappingURL=request-context-BxYIJM24.js.map
+//# sourceMappingURL=request-context-0h-6Voad.js.map

package/dist/_chunks/request-context-0h-6Voad.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context-0h-6Voad.js","names":[],"sources":["../../src/server/request-context.ts"],"sourcesContent":["/**\n * Request Context — per-request ALS store for headers() and cookies().\n *\n * Follows the same pattern as tracing.ts: a module-level AsyncLocalStorage\n * instance, public accessor functions that throw outside request scope,\n * and a framework-internal `runWithRequestContext()` to establish scope.\n *\n * See design/04-authorization.md §\"AccessContext does not include cookies or headers\"\n * and design/11-platform.md §\"AsyncLocalStorage\".\n * See design/29-cookies.md for cookie mutation semantics.\n */\n\nimport { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';\nimport { isDebug } from './debug.js';\nimport { _setRawSearchParamsFn } from '#/search-params/define.js';\n\n// Re-export the ALS for framework-internal consumers that need direct access.\nexport { requestContextAls };\n\n// No fallback needed — we use enterWith() instead of run() to ensure\n// the ALS context persists for the entire request lifecycle including\n// async stream consumption by React's renderToReadableStream.\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Returns a read-only view of the current request's headers.\n *\n * Available in middleware, access checks, server components, and server actions.\n * Throws if called outside a request context (security principle #2: no global fallback).\n */\nexport function headers(): ReadonlyHeaders {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] headers() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return store.headers;\n}\n\n/**\n * Returns a cookie accessor for the current request.\n *\n * Available in middleware, access checks, server components, and server actions.\n * Throws if called outside a request context (security principle #2: no global fallback).\n *\n * Read methods (.get, .has, .getAll) are always available and reflect\n * read-your-own-writes from .set() calls in the same request.\n *\n * Mutation methods (.set, .delete, .clear) are only available in mutable\n * contexts (middleware.ts, server actions, route.ts handlers). Calling them\n * in read-only contexts (access.ts, server components) throws.\n *\n * See design/29-cookies.md\n */\nexport function cookies(): RequestCookies {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] cookies() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n\n  // Parse cookies lazily on first access\n  if (!store.parsedCookies) {\n    store.parsedCookies = parseCookieHeader(store.cookieHeader);\n  }\n\n  const map = store.parsedCookies;\n  return {\n    get(name: string): string | undefined {\n      return map.get(name);\n    },\n    has(name: string): boolean {\n      return map.has(name);\n    },\n    getAll(): Array<{ name: string; value: string }> {\n      return Array.from(map.entries()).map(([name, value]) => ({ name, value }));\n    },\n    get size(): number {\n      return map.size;\n    },\n\n    set(name: string, value: string, options?: CookieOptions): void {\n      assertMutable(store, 'set');\n      if (store.flushed) {\n        if (isDebug()) {\n          console.warn(\n            `[timber] warn: cookies().set('${name}') called after response headers were committed.\\n` +\n              `  The cookie will NOT be sent. Move cookie mutations to middleware.ts, a server action,\\n` +\n              `  or a route.ts handler.`\n          );\n        }\n        return;\n      }\n      const opts = { ...DEFAULT_COOKIE_OPTIONS, ...options };\n      store.cookieJar.set(name, { name, value, options: opts });\n      // Read-your-own-writes: update the parsed cookies map\n      map.set(name, value);\n    },\n\n    delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {\n      assertMutable(store, 'delete');\n      if (store.flushed) {\n        if (isDebug()) {\n          console.warn(\n            `[timber] warn: cookies().delete('${name}') called after response headers were committed.\\n` +\n              `  The cookie will NOT be deleted. Move cookie mutations to middleware.ts, a server action,\\n` +\n              `  or a route.ts handler.`\n          );\n        }\n        return;\n      }\n      const opts: CookieOptions = {\n        ...DEFAULT_COOKIE_OPTIONS,\n        ...options,\n        maxAge: 0,\n        expires: new Date(0),\n      };\n      store.cookieJar.set(name, { name, value: '', options: opts });\n      // Remove from read view\n      map.delete(name);\n    },\n\n    clear(): void {\n      assertMutable(store, 'clear');\n      if (store.flushed) return;\n      // Delete every incoming cookie\n      for (const name of Array.from(map.keys())) {\n        store.cookieJar.set(name, {\n          name,\n          value: '',\n          options: { ...DEFAULT_COOKIE_OPTIONS, maxAge: 0, expires: new Date(0) },\n        });\n      }\n      map.clear();\n    },\n\n    toString(): string {\n      return Array.from(map.entries())\n        .map(([name, value]) => `${name}=${value}`)\n        .join('; ');\n    },\n  };\n}\n\n/**\n * Returns a Promise resolving to the current request's raw URLSearchParams.\n *\n * For typed, parsed search params, import the definition from params.ts\n * and call `.load()` or `.parse()`:\n *\n * ```ts\n * import { searchParams } from './params'\n * const parsed = await searchParams.load()\n * ```\n *\n * Or explicitly:\n *\n * ```ts\n * import { rawSearchParams } from '@timber-js/app/server'\n * import { searchParams } from './params'\n * const parsed = searchParams.parse(await rawSearchParams())\n * ```\n *\n * Throws if called outside a request context.\n */\nexport function rawSearchParams(): Promise<URLSearchParams> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] rawSearchParams() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return store.searchParamsPromise;\n}\n\n// Eagerly register rawSearchParams with the search-params module so\n// searchParams.load() can call it synchronously without a dynamic import.\n// Dynamic imports lose ALS context in React's RSC Flight renderer,\n// breaking rawSearchParams() in parallel slot pages. See TIM-523.\n_setRawSearchParamsFn(rawSearchParams);\n\n/**\n * Returns a Promise resolving to the current request's coerced segment params.\n *\n * Segment params are set by the pipeline after route matching and param\n * coercion (via params.ts codecs). When no params.ts exists, values are\n * raw strings. When codecs are defined, values are already coerced\n * (e.g., `id` is a `number` if `defineSegmentParams({ id: z.coerce.number() })`).\n *\n * This is the primary way page and layout components access route params:\n *\n * ```ts\n * import { rawSegmentParams } from '@timber-js/app/server'\n *\n * export default async function Page() {\n *   const { slug } = await rawSegmentParams()\n *   // ...\n * }\n * ```\n *\n * Throws if called outside a request context.\n */\nexport function rawSegmentParams(): Promise<Record<string, string | string[]>> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] rawSegmentParams() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  if (!store.segmentParamsPromise) {\n    throw new Error(\n      '[timber] rawSegmentParams() called before route matching completed. ' +\n        'Segment params are not available until after the route is matched.'\n    );\n  }\n  return store.segmentParamsPromise;\n}\n\n/**\n * Set the segment params promise on the current request context.\n * Called by the pipeline after route matching and param coercion.\n *\n * @internal — framework use only\n */\nexport function setSegmentParams(params: Record<string, string | string[]>): void {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] setSegmentParams() called outside of a request context.');\n  }\n  store.segmentParamsPromise = Promise.resolve(params);\n}\n\n/**\n * Returns the raw search string from the current request URL (e.g. \"?foo=bar\").\n * Synchronous — safe for use in `redirect()` which throws synchronously.\n *\n * Returns empty string if called outside a request context (non-throwing for\n * use in redirect's optional preserveSearchParams path).\n *\n * @internal — used by redirect() for preserveSearchParams support.\n */\nexport function getRequestSearchString(): string {\n  const store = requestContextAls.getStore();\n  return store?.searchString ?? '';\n}\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\n/**\n * Read-only Headers interface. The standard Headers class is mutable;\n * this type narrows it to read-only methods. The underlying object is\n * still a Headers instance, but user code should not mutate it.\n */\nexport type ReadonlyHeaders = Pick<\n  Headers,\n  'get' | 'has' | 'entries' | 'keys' | 'values' | 'forEach' | typeof Symbol.iterator\n>;\n\n/** Options for setting a cookie. See design/29-cookies.md. */\nexport interface CookieOptions {\n  /** Domain scope. Default: omitted (current domain only). */\n  domain?: string;\n  /** URL path scope. Default: '/'. */\n  path?: string;\n  /** Expiration date. Mutually exclusive with maxAge. */\n  expires?: Date;\n  /** Max age in seconds. Mutually exclusive with expires. */\n  maxAge?: number;\n  /** Prevent client-side JS access. Default: true. */\n  httpOnly?: boolean;\n  /** Only send over HTTPS. Default: true. */\n  secure?: boolean;\n  /** Cross-site request policy. Default: 'lax'. */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** Partitioned (CHIPS) — isolate cookie per top-level site. Default: false. */\n  partitioned?: boolean;\n}\n\nconst DEFAULT_COOKIE_OPTIONS: CookieOptions = {\n  path: '/',\n  httpOnly: true,\n  secure: true,\n  sameSite: 'lax',\n};\n\n/**\n * Cookie accessor returned by `cookies()`.\n *\n * Read methods are always available. Mutation methods throw in read-only\n * contexts (access.ts, server components).\n */\nexport interface RequestCookies {\n  /** Get a cookie value by name. Returns undefined if not present. */\n  get(name: string): string | undefined;\n  /** Check if a cookie exists. */\n  has(name: string): boolean;\n  /** Get all cookies as an array of { name, value } pairs. */\n  getAll(): Array<{ name: string; value: string }>;\n  /** Number of cookies. */\n  readonly size: number;\n  /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */\n  set(name: string, value: string, options?: CookieOptions): void;\n  /** Delete a cookie. Only available in mutable contexts. */\n  delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;\n  /** Delete all cookies. Only available in mutable contexts. */\n  clear(): void;\n  /** Serialize cookies as a Cookie header string. */\n  toString(): string;\n}\n\n// ─── Framework-Internal Helpers ───────────────────────────────────────────\n\n/**\n * Run a callback within a request context. Used by the pipeline to establish\n * per-request ALS scope so that `headers()` and `cookies()` work.\n *\n * @param req - The incoming Request object.\n * @param fn - The function to run within the request context.\n */\nexport function runWithRequestContext<T>(req: Request, fn: () => T): T {\n  const originalCopy = new Headers(req.headers);\n  const parsedUrl = new URL(req.url);\n  const store: RequestContextStore = {\n    headers: freezeHeaders(req.headers),\n    originalHeaders: originalCopy,\n    cookieHeader: req.headers.get('cookie') ?? '',\n    searchParamsPromise: Promise.resolve(parsedUrl.searchParams),\n    searchString: parsedUrl.search,\n    cookieJar: new Map(),\n    flushed: false,\n    mutableContext: false,\n  };\n  return requestContextAls.run(store, fn);\n}\n\n/**\n * Enable cookie mutation for the current context. Called by the framework\n * when entering middleware.ts, server actions, or route.ts handlers.\n *\n * See design/29-cookies.md §\"Context Tracking\"\n */\nexport function setMutableCookieContext(mutable: boolean): void {\n  const store = requestContextAls.getStore();\n  if (store) {\n    store.mutableContext = mutable;\n  }\n}\n\n/**\n * Mark the response as flushed (headers committed). After this point,\n * cookie mutations log a warning instead of throwing.\n *\n * See design/29-cookies.md §\"Streaming Constraint: Post-Flush Cookie Warning\"\n */\nexport function markResponseFlushed(): void {\n  const store = requestContextAls.getStore();\n  if (store) {\n    store.flushed = true;\n  }\n}\n\n/**\n * Build a Map of cookie name → value reflecting the current request's\n * read-your-own-writes state. Includes incoming cookies plus any\n * mutations from cookies().set() / cookies().delete() in the same request.\n *\n * Used by SSR renderers to populate NavContext.cookies so that\n * useCookie()'s server snapshot matches the actual response state.\n *\n * See design/29-cookies.md §\"Read-Your-Own-Writes\"\n * See design/triage/TIM-441-cookie-api-triage.md §4\n */\nexport function getCookiesForSsr(): Map<string, string> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] getCookiesForSsr() called outside of a request context.');\n  }\n\n  // Trigger lazy parsing if not yet done\n  if (!store.parsedCookies) {\n    store.parsedCookies = parseCookieHeader(store.cookieHeader);\n  }\n\n  // The parsedCookies map already reflects read-your-own-writes:\n  // - cookies().set() updates the map via map.set(name, value)\n  // - cookies().delete() removes from the map via map.delete(name)\n  // Return a copy so callers can't mutate the internal map.\n  return new Map(store.parsedCookies);\n}\n\n/**\n * Collect all Set-Cookie headers from the cookie jar.\n * Called by the framework at flush time to apply cookies to the response.\n *\n * Returns an array of serialized Set-Cookie header values.\n */\nexport function getSetCookieHeaders(): string[] {\n  const store = requestContextAls.getStore();\n  if (!store) return [];\n  return Array.from(store.cookieJar.values()).map(serializeCookieEntry);\n}\n\n/**\n * Apply middleware-injected request headers to the current request context.\n *\n * Called by the pipeline after middleware.ts runs. Merges overlay headers\n * on top of the original request headers so downstream code (access.ts,\n * server components, server actions) sees them via `headers()`.\n *\n * The original request headers are never mutated — a new frozen Headers\n * object is created with the overlay applied on top.\n *\n * See design/07-routing.md §\"Request Header Injection\"\n */\nexport function applyRequestHeaderOverlay(overlay: Headers): void {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] applyRequestHeaderOverlay() called outside of a request context.');\n  }\n\n  // Check if the overlay has any headers — skip if empty\n  let hasOverlay = false;\n  overlay.forEach(() => {\n    hasOverlay = true;\n  });\n  if (!hasOverlay) return;\n\n  // Merge: start with original headers, overlay on top\n  const merged = new Headers(store.originalHeaders);\n  overlay.forEach((value, key) => {\n    merged.set(key, value);\n  });\n  store.headers = freezeHeaders(merged);\n}\n\n// ─── Read-Only Headers ────────────────────────────────────────────────────\n\nconst MUTATING_METHODS = new Set(['set', 'append', 'delete']);\n\n/**\n * Wrap a Headers object in a Proxy that throws on mutating methods.\n * Object.freeze doesn't work on Headers (native internal slots), so we\n * intercept property access and reject set/append/delete at runtime.\n *\n * Read methods (get, has, entries, etc.) must be bound to the underlying\n * Headers instance because they access private #headersList slots.\n */\nfunction freezeHeaders(source: Headers): Headers {\n  const copy = new Headers(source);\n  return new Proxy(copy, {\n    get(target, prop) {\n      if (typeof prop === 'string' && MUTATING_METHODS.has(prop)) {\n        return () => {\n          throw new Error(\n            `[timber] headers() returns a read-only Headers object. ` +\n              `Calling .${prop}() is not allowed. ` +\n              `Use ctx.requestHeaders in middleware to inject headers for downstream components.`\n          );\n        };\n      }\n      const value = Reflect.get(target, prop);\n      // Bind methods to the real Headers instance so private slot access works\n      if (typeof value === 'function') {\n        return value.bind(target);\n      }\n      return value;\n    },\n  });\n}\n\n// ─── Cookie Helpers ───────────────────────────────────────────────────────\n\n/** Throw if cookie mutation is attempted in a read-only context. */\nfunction assertMutable(store: RequestContextStore, method: string): void {\n  if (!store.mutableContext) {\n    throw new Error(\n      `[timber] cookies().${method}() cannot be called in this context.\\n` +\n        `  Set cookies in middleware.ts, server actions, or route.ts handlers.`\n    );\n  }\n}\n\n/**\n * Parse a Cookie header string into a Map of name → value pairs.\n * Follows RFC 6265 §4.2.1: cookies are semicolon-separated key=value pairs.\n */\nfunction parseCookieHeader(header: string): Map<string, string> {\n  const map = new Map<string, string>();\n  if (!header) return map;\n\n  for (const pair of header.split(';')) {\n    const eqIndex = pair.indexOf('=');\n    if (eqIndex === -1) continue;\n    const name = pair.slice(0, eqIndex).trim();\n    const value = pair.slice(eqIndex + 1).trim();\n    if (name) {\n      map.set(name, value);\n    }\n  }\n\n  return map;\n}\n\n/** Serialize a CookieEntry into a Set-Cookie header value. */\nfunction serializeCookieEntry(entry: CookieEntry): string {\n  const parts = [`${entry.name}=${entry.value}`];\n  const opts = entry.options;\n\n  if (opts.domain) parts.push(`Domain=${opts.domain}`);\n  if (opts.path) parts.push(`Path=${opts.path}`);\n  if (opts.expires) parts.push(`Expires=${opts.expires.toUTCString()}`);\n  if (opts.maxAge !== undefined) parts.push(`Max-Age=${opts.maxAge}`);\n  if (opts.httpOnly) parts.push('HttpOnly');\n  if (opts.secure) parts.push('Secure');\n  if (opts.sameSite) {\n    parts.push(`SameSite=${opts.sameSite.charAt(0).toUpperCase()}${opts.sameSite.slice(1)}`);\n  }\n  if (opts.partitioned) parts.push('Partitioned');\n\n  return parts.join('; ');\n}\n"],"mappings":"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"}

package/dist/_chunks/{segment-context-C6byCyZU.js → segment-context-DBn-nrMN.js}

@@ -66,4 +66,4 @@ function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, c
 //#endregion
 export { useSegmentContext as n, mergePreservedSearchParams as r, SegmentProvider as t };
 
-//# sourceMappingURL=segment-context-C6byCyZU.js.map
+//# sourceMappingURL=segment-context-DBn-nrMN.js.map

package/dist/_chunks/{segment-context-C6byCyZU.js.map → segment-context-DBn-nrMN.js.map}

@@ -1 +1 @@
-{"version":3,"file":"segment-context-C6byCyZU.js","names":[],"sources":["../../src/shared/merge-search-params.ts","../../src/client/segment-context.ts"],"sourcesContent":["/**\n * Shared utility for merging preserved search params into a target URL.\n *\n * Used by both <Link> (client) and redirect() (server). Extracted to a shared\n * module to avoid importing client code ('use client') from server modules.\n */\n\n/**\n * Merge preserved search params from the current URL into a target href.\n *\n * When `preserve` is `true`, all current search params are merged.\n * When `preserve` is a `string[]`, only the named params are merged.\n *\n * The target href's own search params take precedence — preserved params\n * are only added if the target doesn't already define them.\n *\n * @param targetHref - The resolved target href (may already contain query string)\n * @param currentSearch - The current URL's search string (e.g. \"?private=access&page=2\")\n * @param preserve - `true` to preserve all, or `string[]` to preserve specific params\n * @returns The target href with preserved search params merged in\n */\nexport function mergePreservedSearchParams(\n  targetHref: string,\n  currentSearch: string,\n  preserve: true | string[]\n): string {\n  const currentParams = new URLSearchParams(currentSearch);\n  if (currentParams.size === 0) return targetHref;\n\n  // Split target into path and existing query\n  const qIdx = targetHref.indexOf('?');\n  const targetPath = qIdx >= 0 ? targetHref.slice(0, qIdx) : targetHref;\n  const targetParams = new URLSearchParams(qIdx >= 0 ? targetHref.slice(qIdx + 1) : '');\n\n  // Collect params to preserve (that aren't already in the target)\n  const merged = new URLSearchParams(targetParams);\n  for (const [key, value] of currentParams) {\n    // Only preserve if: (a) not already in target, and (b) included in preserve list\n    if (!targetParams.has(key)) {\n      if (preserve === true || preserve.includes(key)) {\n        merged.append(key, value);\n      }\n    }\n  }\n\n  const qs = merged.toString();\n  return qs ? `${targetPath}?${qs}` : targetPath;\n}\n","/**\n * Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.\n *\n * Each layout in the segment tree is wrapped with a SegmentProvider that stores\n * the URL segments from root to the current layout level. The hooks read this\n * context to determine which child segments are active below the calling layout.\n *\n * The context value is intentionally minimal: just the segment path array and\n * parallel route keys. No internal cache details are exposed.\n *\n * Design docs: design/19-client-navigation.md, design/14-ecosystem.md\n */\n\n'use client';\n\nimport { createContext, useContext, createElement, useMemo } from 'react';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface SegmentContextValue {\n  /** URL segments from root to this layout (e.g. ['', 'dashboard', 'settings']) */\n  segments: string[];\n  /** Parallel route slot keys available at this layout level (e.g. ['sidebar', 'modal']) */\n  parallelRouteKeys: string[];\n}\n\n// ─── Context ─────────────────────────────────────────────────────\n\nconst SegmentContext = createContext<SegmentContextValue | null>(null);\n\n/** Read the segment context. Returns null if no provider is above this component. */\nexport function useSegmentContext(): SegmentContextValue | null {\n  return useContext(SegmentContext);\n}\n\n// ─── Provider ────────────────────────────────────────────────────\n\ninterface SegmentProviderProps {\n  segments: string[];\n  /**\n   * Unique identifier for this segment, used by the client-side segment\n   * merger for element caching. For route groups this includes the group\n   * name (e.g., \"/(marketing)\") since groups share their parent's urlPath.\n   * Falls back to the reconstructed path from `segments` if not provided.\n   */\n  segmentId?: string;\n  parallelRouteKeys: string[];\n  children: React.ReactNode;\n}\n\n/**\n * Wraps each layout to provide segment position context.\n * Injected by rsc-entry.ts during element tree construction.\n */\nexport function SegmentProvider({\n  segments,\n  segmentId: _segmentId,\n  parallelRouteKeys,\n  children,\n}: SegmentProviderProps) {\n  const value = useMemo(\n    () => ({ segments, parallelRouteKeys }),\n    // segments and parallelRouteKeys are static per layout — they don't change\n    // across navigations. The layout's position in the tree is fixed.\n    // Intentionally using derived keys — segments/parallelRouteKeys are static per layout\n    [segments.join('/'), parallelRouteKeys.join(',')]\n  );\n  return createElement(SegmentContext.Provider, { value }, children);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,2BACd,YACA,eACA,UACQ;CACR,MAAM,gBAAgB,IAAI,gBAAgB,cAAc;AACxD,KAAI,cAAc,SAAS,EAAG,QAAO;CAGrC,MAAM,OAAO,WAAW,QAAQ,IAAI;CACpC,MAAM,aAAa,QAAQ,IAAI,WAAW,MAAM,GAAG,KAAK,GAAG;CAC3D,MAAM,eAAe,IAAI,gBAAgB,QAAQ,IAAI,WAAW,MAAM,OAAO,EAAE,GAAG,GAAG;CAGrF,MAAM,SAAS,IAAI,gBAAgB,aAAa;AAChD,MAAK,MAAM,CAAC,KAAK,UAAU,cAEzB,KAAI,CAAC,aAAa,IAAI,IAAI;MACpB,aAAa,QAAQ,SAAS,SAAS,IAAI,CAC7C,QAAO,OAAO,KAAK,MAAM;;CAK/B,MAAM,KAAK,OAAO,UAAU;AAC5B,QAAO,KAAK,GAAG,WAAW,GAAG,OAAO;;;;;;;;;;;;;;;;AClBtC,IAAM,iBAAiB,cAA0C,KAAK;;AAGtE,SAAgB,oBAAgD;AAC9D,QAAO,WAAW,eAAe;;;;;;AAsBnC,SAAgB,gBAAgB,EAC9B,UACA,WAAW,YACX,mBACA,YACuB;CACvB,MAAM,QAAQ,eACL;EAAE;EAAU;EAAmB,GAItC,CAAC,SAAS,KAAK,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC,CAClD;AACD,QAAO,cAAc,eAAe,UAAU,EAAE,OAAO,EAAE,SAAS"}
+{"version":3,"file":"segment-context-DBn-nrMN.js","names":[],"sources":["../../src/shared/merge-search-params.ts","../../src/client/segment-context.ts"],"sourcesContent":["/**\n * Shared utility for merging preserved search params into a target URL.\n *\n * Used by both <Link> (client) and redirect() (server). Extracted to a shared\n * module to avoid importing client code ('use client') from server modules.\n */\n\n/**\n * Merge preserved search params from the current URL into a target href.\n *\n * When `preserve` is `true`, all current search params are merged.\n * When `preserve` is a `string[]`, only the named params are merged.\n *\n * The target href's own search params take precedence — preserved params\n * are only added if the target doesn't already define them.\n *\n * @param targetHref - The resolved target href (may already contain query string)\n * @param currentSearch - The current URL's search string (e.g. \"?private=access&page=2\")\n * @param preserve - `true` to preserve all, or `string[]` to preserve specific params\n * @returns The target href with preserved search params merged in\n */\nexport function mergePreservedSearchParams(\n  targetHref: string,\n  currentSearch: string,\n  preserve: true | string[]\n): string {\n  const currentParams = new URLSearchParams(currentSearch);\n  if (currentParams.size === 0) return targetHref;\n\n  // Split target into path and existing query\n  const qIdx = targetHref.indexOf('?');\n  const targetPath = qIdx >= 0 ? targetHref.slice(0, qIdx) : targetHref;\n  const targetParams = new URLSearchParams(qIdx >= 0 ? targetHref.slice(qIdx + 1) : '');\n\n  // Collect params to preserve (that aren't already in the target)\n  const merged = new URLSearchParams(targetParams);\n  for (const [key, value] of currentParams) {\n    // Only preserve if: (a) not already in target, and (b) included in preserve list\n    if (!targetParams.has(key)) {\n      if (preserve === true || preserve.includes(key)) {\n        merged.append(key, value);\n      }\n    }\n  }\n\n  const qs = merged.toString();\n  return qs ? `${targetPath}?${qs}` : targetPath;\n}\n","/**\n * Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.\n *\n * Each layout in the segment tree is wrapped with a SegmentProvider that stores\n * the URL segments from root to the current layout level. The hooks read this\n * context to determine which child segments are active below the calling layout.\n *\n * The context value is intentionally minimal: just the segment path array and\n * parallel route keys. No internal cache details are exposed.\n *\n * Design docs: design/19-client-navigation.md, design/14-ecosystem.md\n */\n\n'use client';\n\nimport { createContext, useContext, createElement, useMemo } from 'react';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface SegmentContextValue {\n  /** URL segments from root to this layout (e.g. ['', 'dashboard', 'settings']) */\n  segments: string[];\n  /** Parallel route slot keys available at this layout level (e.g. ['sidebar', 'modal']) */\n  parallelRouteKeys: string[];\n}\n\n// ─── Context ─────────────────────────────────────────────────────\n\nconst SegmentContext = createContext<SegmentContextValue | null>(null);\n\n/** Read the segment context. Returns null if no provider is above this component. */\nexport function useSegmentContext(): SegmentContextValue | null {\n  return useContext(SegmentContext);\n}\n\n// ─── Provider ────────────────────────────────────────────────────\n\ninterface SegmentProviderProps {\n  segments: string[];\n  /**\n   * Unique identifier for this segment, used by the client-side segment\n   * merger for element caching. For route groups this includes the group\n   * name (e.g., \"/(marketing)\") since groups share their parent's urlPath.\n   * Falls back to the reconstructed path from `segments` if not provided.\n   */\n  segmentId?: string;\n  parallelRouteKeys: string[];\n  children: React.ReactNode;\n}\n\n/**\n * Wraps each layout to provide segment position context.\n * Injected by rsc-entry.ts during element tree construction.\n */\nexport function SegmentProvider({\n  segments,\n  segmentId: _segmentId,\n  parallelRouteKeys,\n  children,\n}: SegmentProviderProps) {\n  const value = useMemo(\n    () => ({ segments, parallelRouteKeys }),\n    // segments and parallelRouteKeys are static per layout — they don't change\n    // across navigations. The layout's position in the tree is fixed.\n    // Intentionally using derived keys — segments/parallelRouteKeys are static per layout\n    [segments.join('/'), parallelRouteKeys.join(',')]\n  );\n  return createElement(SegmentContext.Provider, { value }, children);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,2BACd,YACA,eACA,UACQ;CACR,MAAM,gBAAgB,IAAI,gBAAgB,cAAc;AACxD,KAAI,cAAc,SAAS,EAAG,QAAO;CAGrC,MAAM,OAAO,WAAW,QAAQ,IAAI;CACpC,MAAM,aAAa,QAAQ,IAAI,WAAW,MAAM,GAAG,KAAK,GAAG;CAC3D,MAAM,eAAe,IAAI,gBAAgB,QAAQ,IAAI,WAAW,MAAM,OAAO,EAAE,GAAG,GAAG;CAGrF,MAAM,SAAS,IAAI,gBAAgB,aAAa;AAChD,MAAK,MAAM,CAAC,KAAK,UAAU,cAEzB,KAAI,CAAC,aAAa,IAAI,IAAI;MACpB,aAAa,QAAQ,SAAS,SAAS,IAAI,CAC7C,QAAO,OAAO,KAAK,MAAM;;CAK/B,MAAM,KAAK,OAAO,UAAU;AAC5B,QAAO,KAAK,GAAG,WAAW,GAAG,OAAO;;;;;;;;;;;;;;;;AClBtC,IAAM,iBAAiB,cAA0C,KAAK;;AAGtE,SAAgB,oBAAgD;AAC9D,QAAO,WAAW,eAAe;;;;;;AAsBnC,SAAgB,gBAAgB,EAC9B,UACA,WAAW,YACX,mBACA,YACuB;CACvB,MAAM,QAAQ,eACL;EAAE;EAAU;EAAmB,GAItC,CAAC,SAAS,KAAK,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC,CAClD;AACD,QAAO,cAAc,eAAe,UAAU,EAAE,OAAO,EAAE,SAAS"}

package/dist/_chunks/{stale-reload-C0ValzG7.js → stale-reload-4L-_skC7.js}

@@ -44,4 +44,4 @@ function triggerStaleReload() {
 //#endregion
 export { triggerStaleReload };
 
-//# sourceMappingURL=stale-reload-C0ValzG7.js.map
+//# sourceMappingURL=stale-reload-4L-_skC7.js.map

package/dist/_chunks/{stale-reload-C0ValzG7.js.map → stale-reload-4L-_skC7.js.map}

@@ -1 +1 @@
-{"version":3,"file":"stale-reload-C0ValzG7.js","names":[],"sources":["../../src/client/stale-reload.ts"],"sourcesContent":["/**\n * Stale Client Reference Reload\n *\n * When a new deployment ships updated bundles, clients running stale\n * JavaScript may encounter \"Could not find the module\" errors during\n * RSC Flight stream decoding. This happens because the RSC payload\n * references module IDs from the new bundle that don't exist in the\n * old client bundle.\n *\n * This module detects these specific errors and triggers a full page\n * reload so the browser fetches the new bundle. A sessionStorage flag\n * guards against infinite reload loops.\n *\n * See: LOCAL-332\n */\n\nconst RELOAD_FLAG_KEY = '__timber_stale_reload';\n\n/**\n * Check if an error is a stale client reference error from React's\n * Flight client. These errors have the message pattern:\n *   \"Could not find the module \\\"<id>\\\"\"\n *\n * This is thrown by react-server-dom-webpack's client when the RSC\n * payload references a module ID that doesn't exist in the client's\n * module map — typically because the server has been redeployed with\n * new bundle hashes while the client is still running old JavaScript.\n */\nexport function isStaleClientReference(error: unknown): boolean {\n  if (!(error instanceof Error)) return false;\n  const msg = error.message;\n  return msg.includes('Could not find the module') || msg.includes('client reference not found');\n}\n\n/**\n * Check if an error is a chunk load failure from a dynamic import.\n *\n * After a deployment, old chunk filenames no longer exist. When the client\n * tries to dynamically import a chunk that's been replaced, the browser\n * throws one of these errors:\n *\n * - Chromium: \"Failed to fetch dynamically imported module: <url>\"\n * - Firefox: \"error loading dynamically imported module: <url>\"\n * - Safari: \"Importing a module script failed.\"\n * - Vite/Rollup: \"Unable to preload CSS for <url>\"\n *\n * See TIM-446\n */\nexport function isChunkLoadError(error: unknown): boolean {\n  if (!(error instanceof Error)) return false;\n  const msg = error.message.toLowerCase();\n  return (\n    msg.includes('failed to fetch dynamically imported module') ||\n    msg.includes('error loading dynamically imported module') ||\n    msg.includes('importing a module script failed') ||\n    msg.includes('unable to preload css') ||\n    // Webpack-style chunk load errors (unlikely in Vite but defensive)\n    msg.includes('loading chunk') ||\n    msg.includes('loading css chunk')\n  );\n}\n\n/**\n * Trigger a full page reload to pick up new bundles.\n *\n * Sets a sessionStorage flag before reloading. If the flag is already\n * set (meaning we already reloaded once for this reason), we don't\n * reload again — this prevents infinite reload loops if the error\n * persists after reload (e.g., a genuine bug rather than a stale bundle).\n *\n * @returns true if a reload was triggered, false if suppressed (loop guard)\n */\nexport function triggerStaleReload(): boolean {\n  try {\n    // Check if we already reloaded — prevent infinite loop\n    if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {\n      console.warn(\n        '[timber] Stale client reference detected again after reload. ' +\n          'Not reloading to prevent infinite loop. ' +\n          'This may indicate a deployment issue — try a hard refresh.'\n      );\n      return false;\n    }\n\n    // Set the flag before reloading\n    sessionStorage.setItem(RELOAD_FLAG_KEY, '1');\n\n    console.warn(\n      '[timber] Stale client reference detected — the server has been ' +\n        'redeployed with new bundles. Reloading to pick up the new version.'\n    );\n\n    window.location.reload();\n    return true;\n  } catch {\n    // sessionStorage may be unavailable (private browsing, storage full, etc.)\n    // Fall back to reloading without loop protection\n    console.warn('[timber] Stale client reference detected. Reloading page.');\n    window.location.reload();\n    return true;\n  }\n}\n\n/**\n * Clear the stale reload flag. Called on successful bootstrap to reset\n * the loop guard — if the page loaded successfully, the next stale\n * reference error should trigger a fresh reload attempt.\n */\nexport function clearStaleReloadFlag(): void {\n  try {\n    sessionStorage.removeItem(RELOAD_FLAG_KEY);\n  } catch {\n    // sessionStorage unavailable — nothing to clear\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,IAAM,kBAAkB;;;;;;;;;;;AAwDxB,SAAgB,qBAA8B;AAC5C,KAAI;AAEF,MAAI,eAAe,QAAQ,gBAAgB,EAAE;AAC3C,WAAQ,KACN,kKAGD;AACD,UAAO;;AAIT,iBAAe,QAAQ,iBAAiB,IAAI;AAE5C,UAAQ,KACN,oIAED;AAED,SAAO,SAAS,QAAQ;AACxB,SAAO;SACD;AAGN,UAAQ,KAAK,4DAA4D;AACzE,SAAO,SAAS,QAAQ;AACxB,SAAO"}
+{"version":3,"file":"stale-reload-4L-_skC7.js","names":[],"sources":["../../src/client/stale-reload.ts"],"sourcesContent":["/**\n * Stale Client Reference Reload\n *\n * When a new deployment ships updated bundles, clients running stale\n * JavaScript may encounter \"Could not find the module\" errors during\n * RSC Flight stream decoding. This happens because the RSC payload\n * references module IDs from the new bundle that don't exist in the\n * old client bundle.\n *\n * This module detects these specific errors and triggers a full page\n * reload so the browser fetches the new bundle. A sessionStorage flag\n * guards against infinite reload loops.\n *\n * See: LOCAL-332\n */\n\nconst RELOAD_FLAG_KEY = '__timber_stale_reload';\n\n/**\n * Check if an error is a stale client reference error from React's\n * Flight client. These errors have the message pattern:\n *   \"Could not find the module \\\"<id>\\\"\"\n *\n * This is thrown by react-server-dom-webpack's client when the RSC\n * payload references a module ID that doesn't exist in the client's\n * module map — typically because the server has been redeployed with\n * new bundle hashes while the client is still running old JavaScript.\n */\nexport function isStaleClientReference(error: unknown): boolean {\n  if (!(error instanceof Error)) return false;\n  const msg = error.message;\n  return msg.includes('Could not find the module') || msg.includes('client reference not found');\n}\n\n/**\n * Check if an error is a chunk load failure from a dynamic import.\n *\n * After a deployment, old chunk filenames no longer exist. When the client\n * tries to dynamically import a chunk that's been replaced, the browser\n * throws one of these errors:\n *\n * - Chromium: \"Failed to fetch dynamically imported module: <url>\"\n * - Firefox: \"error loading dynamically imported module: <url>\"\n * - Safari: \"Importing a module script failed.\"\n * - Vite/Rollup: \"Unable to preload CSS for <url>\"\n *\n * See TIM-446\n */\nexport function isChunkLoadError(error: unknown): boolean {\n  if (!(error instanceof Error)) return false;\n  const msg = error.message.toLowerCase();\n  return (\n    msg.includes('failed to fetch dynamically imported module') ||\n    msg.includes('error loading dynamically imported module') ||\n    msg.includes('importing a module script failed') ||\n    msg.includes('unable to preload css') ||\n    // Webpack-style chunk load errors (unlikely in Vite but defensive)\n    msg.includes('loading chunk') ||\n    msg.includes('loading css chunk')\n  );\n}\n\n/**\n * Trigger a full page reload to pick up new bundles.\n *\n * Sets a sessionStorage flag before reloading. If the flag is already\n * set (meaning we already reloaded once for this reason), we don't\n * reload again — this prevents infinite reload loops if the error\n * persists after reload (e.g., a genuine bug rather than a stale bundle).\n *\n * @returns true if a reload was triggered, false if suppressed (loop guard)\n */\nexport function triggerStaleReload(): boolean {\n  try {\n    // Check if we already reloaded — prevent infinite loop\n    if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {\n      console.warn(\n        '[timber] Stale client reference detected again after reload. ' +\n          'Not reloading to prevent infinite loop. ' +\n          'This may indicate a deployment issue — try a hard refresh.'\n      );\n      return false;\n    }\n\n    // Set the flag before reloading\n    sessionStorage.setItem(RELOAD_FLAG_KEY, '1');\n\n    console.warn(\n      '[timber] Stale client reference detected — the server has been ' +\n        'redeployed with new bundles. Reloading to pick up the new version.'\n    );\n\n    window.location.reload();\n    return true;\n  } catch {\n    // sessionStorage may be unavailable (private browsing, storage full, etc.)\n    // Fall back to reloading without loop protection\n    console.warn('[timber] Stale client reference detected. Reloading page.');\n    window.location.reload();\n    return true;\n  }\n}\n\n/**\n * Clear the stale reload flag. Called on successful bootstrap to reset\n * the loop guard — if the page loaded successfully, the next stale\n * reference error should trigger a fresh reload attempt.\n */\nexport function clearStaleReloadFlag(): void {\n  try {\n    sessionStorage.removeItem(RELOAD_FLAG_KEY);\n  } catch {\n    // sessionStorage unavailable — nothing to clear\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,IAAM,kBAAkB;;;;;;;;;;;AAwDxB,SAAgB,qBAA8B;AAC5C,KAAI;AAEF,MAAI,eAAe,QAAQ,gBAAgB,EAAE;AAC3C,WAAQ,KACN,kKAGD;AACD,UAAO;;AAIT,iBAAe,QAAQ,iBAAiB,IAAI;AAE5C,UAAQ,KACN,oIAED;AAED,SAAO,SAAS,QAAQ;AACxB,SAAO;SACD;AAGN,UAAQ,KAAK,4DAA4D;AACzE,SAAO,SAAS,QAAQ;AACxB,SAAO"}

package/dist/_chunks/{tracing-CuXiCP5p.js → tracing-JI4cYUdz.js}

@@ -184,4 +184,4 @@ async function getOtelTraceId() {
 //#endregion
 export { getTraceStore as a, setSpanAttribute as c, withSpan as d, getOtelTraceId as i, spanId as l, addSpanEventSync as n, replaceTraceId as o, generateTraceId as r, runWithTraceId as s, addSpanEvent as t, traceId as u };
 
-//# sourceMappingURL=tracing-CuXiCP5p.js.map
+//# sourceMappingURL=tracing-JI4cYUdz.js.map

package/dist/_chunks/{tracing-CuXiCP5p.js.map → tracing-JI4cYUdz.js.map}

@@ -1 +1 @@
-{"version":3,"file":"tracing-CuXiCP5p.js","names":[],"sources":["../../src/server/tracing.ts"],"sourcesContent":["/**\n * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.\n *\n * traceId() is always available in server code (middleware, access, components, actions).\n * Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,\n * or a crypto.randomUUID()-derived fallback otherwise.\n *\n * See design/17-logging.md §\"trace_id is Always Set\"\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { traceAls, type TraceStore } from './als-registry.js';\n\n// Re-export the TraceStore type for public API consumers.\nexport type { TraceStore } from './als-registry.js';\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Returns the current request's trace ID — always a 32-char lowercase hex string.\n *\n * With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).\n * Without OTEL: crypto.randomUUID() with hyphens stripped.\n *\n * Throws if called outside a request context (no ALS store).\n */\nexport function traceId(): string {\n  const store = traceAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] traceId() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return store.traceId;\n}\n\n/**\n * Returns the current OTEL span ID if available, undefined otherwise.\n */\nexport function spanId(): string | undefined {\n  return traceAls.getStore()?.spanId;\n}\n\n// ─── Framework-Internal Helpers ───────────────────────────────────────────\n\n/**\n * Generate a 32-char lowercase hex ID from crypto.randomUUID().\n * Same format as OTEL trace IDs — zero-friction upgrade path.\n */\nexport function generateTraceId(): string {\n  return randomUUID().replace(/-/g, '');\n}\n\n/**\n * Run a callback within a trace context. Used by the pipeline to establish\n * per-request ALS scope.\n */\nexport function runWithTraceId<T>(id: string, fn: () => T): T {\n  return traceAls.run({ traceId: id }, fn);\n}\n\n/**\n * Replace the trace ID in the current ALS store. Used when OTEL creates\n * a root span and we want to switch from the UUID fallback to the real\n * OTEL trace ID.\n */\nexport function replaceTraceId(newTraceId: string, newSpanId?: string): void {\n  const store = traceAls.getStore();\n  if (store) {\n    store.traceId = newTraceId;\n    store.spanId = newSpanId;\n  }\n}\n\n/**\n * Update the span ID in the current ALS store. Used when entering a new\n * OTEL span to keep log–trace correlation accurate.\n */\nexport function updateSpanId(newSpanId: string | undefined): void {\n  const store = traceAls.getStore();\n  if (store) {\n    store.spanId = newSpanId;\n  }\n}\n\n/**\n * Get the current trace store, or undefined if outside a request context.\n * Framework-internal — use traceId()/spanId() in user code.\n */\nexport function getTraceStore(): TraceStore | undefined {\n  return traceAls.getStore();\n}\n\n// ─── Dev-Mode OTEL Auto-Init ─────────────────────────────────────────────\n\n/**\n * Initialize a minimal OTEL SDK in dev mode so spans are recorded and\n * fed to the DevSpanProcessor for dev log output.\n *\n * If the user already configured an OTEL SDK in register(), we add\n * our DevSpanProcessor alongside theirs. If no SDK is configured,\n * we create a BasicTracerProvider with our processor.\n *\n * Only called in dev mode — zero overhead in production.\n */\nexport async function initDevTracing(\n  config: import('./dev-logger.js').DevLoggerConfig\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const { DevSpanProcessor } = await import('./dev-span-processor.js');\n  const { BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base');\n  const { AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks');\n  const processor = new DevSpanProcessor(config);\n\n  // Register a context manager so OTEL can propagate the active span\n  // across async boundaries. Without this, startActiveSpan can't make\n  // spans \"active\" — child spans get random trace IDs and getActiveSpan()\n  // returns undefined.\n  const contextManager = new AsyncLocalStorageContextManager();\n  contextManager.enable();\n  api.context.setGlobalContextManager(contextManager);\n\n  // Create a minimal TracerProvider with our DevSpanProcessor.\n  // If the user also configures an SDK in register(), their provider\n  // will coexist — the global provider set last wins for new tracers,\n  // but our processor captures all spans from the timber.js tracer.\n  const provider = new BasicTracerProvider({\n    spanProcessors: [processor],\n  });\n  api.trace.setGlobalTracerProvider(provider);\n\n  // Reset cached tracer so next getTracer() picks up the new provider\n  _tracer = undefined;\n}\n\n// ─── OTEL Span Helpers ───────────────────────────────────────────────────\n\n/**\n * Attempt to get the @opentelemetry/api tracer. Returns undefined if the\n * package is not installed or no SDK is registered.\n *\n * timber.js depends on @opentelemetry/api as the vendor-neutral interface.\n * The API is a no-op by default — spans are only emitted when the developer\n * initializes an SDK in register().\n */\nlet _otelApi: typeof import('@opentelemetry/api') | null | undefined;\n\nasync function getOtelApi(): Promise<typeof import('@opentelemetry/api') | null> {\n  if (_otelApi === undefined) {\n    try {\n      _otelApi = await import('@opentelemetry/api');\n    } catch {\n      _otelApi = null;\n    }\n  }\n  return _otelApi;\n}\n\n/** OTEL tracer instance, lazily created. */\nlet _tracer: import('@opentelemetry/api').Tracer | null | undefined;\n\n/**\n * Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.\n */\nexport async function getTracer(): Promise<import('@opentelemetry/api').Tracer | null> {\n  if (_tracer === undefined) {\n    const api = await getOtelApi();\n    if (api) {\n      _tracer = api.trace.getTracer('timber.js');\n    } else {\n      _tracer = null;\n    }\n  }\n  return _tracer;\n}\n\n/**\n * Run a function within an OTEL span. If OTEL is not available, runs the function\n * directly without any span overhead.\n *\n * Automatically:\n * - Creates the span as a child of the current context\n * - Updates the ALS span ID for log–trace correlation\n * - Ends the span when the function completes\n * - Records exceptions on error\n */\nexport async function withSpan<T>(\n  name: string,\n  attributes: Record<string, string | number | boolean>,\n  fn: () => T | Promise<T>\n): Promise<T> {\n  const tracer = await getTracer();\n  if (!tracer) {\n    return fn();\n  }\n\n  const api = (await getOtelApi())!;\n  return tracer.startActiveSpan(name, { attributes }, async (span) => {\n    const prevSpanId = spanId();\n    updateSpanId(span.spanContext().spanId);\n    try {\n      const result = await fn();\n      span.setStatus({ code: api.SpanStatusCode.OK });\n      return result;\n    } catch (error) {\n      span.setStatus({ code: api.SpanStatusCode.ERROR });\n      if (error instanceof Error) {\n        span.recordException(error);\n      }\n      throw error;\n    } finally {\n      span.end();\n      updateSpanId(prevSpanId);\n    }\n  });\n}\n\n/**\n * Set an attribute on the current active span (if any).\n * Used for setting span attributes after span creation (e.g. timber.result on access spans).\n */\nexport async function setSpanAttribute(\n  key: string,\n  value: string | number | boolean\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.setAttribute(key, value);\n  }\n}\n\n/**\n * Add a span event to the current active span (if any).\n * Used for timber.cache HIT/MISS events — recorded as span events, not child spans.\n */\nexport async function addSpanEvent(\n  name: string,\n  attributes?: Record<string, string | number | boolean>\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.addEvent(name, attributes);\n  }\n}\n\n/**\n * Fire-and-forget span event — no await, no microtask overhead.\n *\n * Used on the cache hot path where awaiting addSpanEvent creates an\n * unnecessary microtask per cache operation. If OTEL is not loaded yet,\n * the event is silently dropped (acceptable for diagnostics).\n *\n * See TIM-370 for perf motivation.\n */\nexport function addSpanEventSync(\n  name: string,\n  attributes?: Record<string, string | number | boolean>\n): void {\n  // Fast path: if OTEL API hasn't been loaded yet, skip entirely.\n  // _otelApi is undefined (not yet loaded), null (failed to load), or the module.\n  if (!_otelApi) return;\n\n  const activeSpan = _otelApi.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.addEvent(name, attributes);\n  }\n}\n\n/**\n * Try to extract the OTEL trace ID from the current active span context.\n * Returns undefined if OTEL is not active or no span exists.\n */\nexport async function getOtelTraceId(): Promise<{ traceId: string; spanId: string } | undefined> {\n  const api = await getOtelApi();\n  if (!api) return undefined;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (!activeSpan) return undefined;\n\n  const ctx = activeSpan.spanContext();\n  // OTEL uses \"0000000000000000\" as invalid trace IDs\n  if (!ctx.traceId || ctx.traceId === '00000000000000000000000000000000') {\n    return undefined;\n  }\n\n  return { traceId: ctx.traceId, spanId: ctx.spanId };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,UAAkB;CAChC,MAAM,QAAQ,SAAS,UAAU;AACjC,KAAI,CAAC,MACH,OAAM,IAAI,MACR,mJAED;AAEH,QAAO,MAAM;;;;;AAMf,SAAgB,SAA6B;AAC3C,QAAO,SAAS,UAAU,EAAE;;;;;;AAS9B,SAAgB,kBAA0B;AACxC,QAAO,YAAY,CAAC,QAAQ,MAAM,GAAG;;;;;;AAOvC,SAAgB,eAAkB,IAAY,IAAgB;AAC5D,QAAO,SAAS,IAAI,EAAE,SAAS,IAAI,EAAE,GAAG;;;;;;;AAQ1C,SAAgB,eAAe,YAAoB,WAA0B;CAC3E,MAAM,QAAQ,SAAS,UAAU;AACjC,KAAI,OAAO;AACT,QAAM,UAAU;AAChB,QAAM,SAAS;;;;;;;AAQnB,SAAgB,aAAa,WAAqC;CAChE,MAAM,QAAQ,SAAS,UAAU;AACjC,KAAI,MACF,OAAM,SAAS;;;;;;AAQnB,SAAgB,gBAAwC;AACtD,QAAO,SAAS,UAAU;;;;;;;;;;AAyD5B,IAAI;AAEJ,eAAe,aAAkE;AAC/E,KAAI,aAAa,KAAA,EACf,KAAI;AACF,aAAW,MAAM,OAAO;SAClB;AACN,aAAW;;AAGf,QAAO;;;AAIT,IAAI;;;;AAKJ,eAAsB,YAAiE;AACrF,KAAI,YAAY,KAAA,GAAW;EACzB,MAAM,MAAM,MAAM,YAAY;AAC9B,MAAI,IACF,WAAU,IAAI,MAAM,UAAU,YAAY;MAE1C,WAAU;;AAGd,QAAO;;;;;;;;;;;;AAaT,eAAsB,SACpB,MACA,YACA,IACY;CACZ,MAAM,SAAS,MAAM,WAAW;AAChC,KAAI,CAAC,OACH,QAAO,IAAI;CAGb,MAAM,MAAO,MAAM,YAAY;AAC/B,QAAO,OAAO,gBAAgB,MAAM,EAAE,YAAY,EAAE,OAAO,SAAS;EAClE,MAAM,aAAa,QAAQ;AAC3B,eAAa,KAAK,aAAa,CAAC,OAAO;AACvC,MAAI;GACF,MAAM,SAAS,MAAM,IAAI;AACzB,QAAK,UAAU,EAAE,MAAM,IAAI,eAAe,IAAI,CAAC;AAC/C,UAAO;WACA,OAAO;AACd,QAAK,UAAU,EAAE,MAAM,IAAI,eAAe,OAAO,CAAC;AAClD,OAAI,iBAAiB,MACnB,MAAK,gBAAgB,MAAM;AAE7B,SAAM;YACE;AACR,QAAK,KAAK;AACV,gBAAa,WAAW;;GAE1B;;;;;;AAOJ,eAAsB,iBACpB,KACA,OACe;CACf,MAAM,MAAM,MAAM,YAAY;AAC9B,KAAI,CAAC,IAAK;CAEV,MAAM,aAAa,IAAI,MAAM,eAAe;AAC5C,KAAI,WACF,YAAW,aAAa,KAAK,MAAM;;;;;;AAQvC,eAAsB,aACpB,MACA,YACe;CACf,MAAM,MAAM,MAAM,YAAY;AAC9B,KAAI,CAAC,IAAK;CAEV,MAAM,aAAa,IAAI,MAAM,eAAe;AAC5C,KAAI,WACF,YAAW,SAAS,MAAM,WAAW;;;;;;;;;;;AAazC,SAAgB,iBACd,MACA,YACM;AAGN,KAAI,CAAC,SAAU;CAEf,MAAM,aAAa,SAAS,MAAM,eAAe;AACjD,KAAI,WACF,YAAW,SAAS,MAAM,WAAW;;;;;;AAQzC,eAAsB,iBAA2E;CAC/F,MAAM,MAAM,MAAM,YAAY;AAC9B,KAAI,CAAC,IAAK,QAAO,KAAA;CAEjB,MAAM,aAAa,IAAI,MAAM,eAAe;AAC5C,KAAI,CAAC,WAAY,QAAO,KAAA;CAExB,MAAM,MAAM,WAAW,aAAa;AAEpC,KAAI,CAAC,IAAI,WAAW,IAAI,YAAY,mCAClC;AAGF,QAAO;EAAE,SAAS,IAAI;EAAS,QAAQ,IAAI;EAAQ"}
+{"version":3,"file":"tracing-JI4cYUdz.js","names":[],"sources":["../../src/server/tracing.ts"],"sourcesContent":["/**\n * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.\n *\n * traceId() is always available in server code (middleware, access, components, actions).\n * Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,\n * or a crypto.randomUUID()-derived fallback otherwise.\n *\n * See design/17-logging.md §\"trace_id is Always Set\"\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { traceAls, type TraceStore } from './als-registry.js';\n\n// Re-export the TraceStore type for public API consumers.\nexport type { TraceStore } from './als-registry.js';\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Returns the current request's trace ID — always a 32-char lowercase hex string.\n *\n * With OTEL: the real OTEL trace ID (matches Jaeger/Honeycomb/Datadog).\n * Without OTEL: crypto.randomUUID() with hyphens stripped.\n *\n * Throws if called outside a request context (no ALS store).\n */\nexport function traceId(): string {\n  const store = traceAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] traceId() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return store.traceId;\n}\n\n/**\n * Returns the current OTEL span ID if available, undefined otherwise.\n */\nexport function spanId(): string | undefined {\n  return traceAls.getStore()?.spanId;\n}\n\n// ─── Framework-Internal Helpers ───────────────────────────────────────────\n\n/**\n * Generate a 32-char lowercase hex ID from crypto.randomUUID().\n * Same format as OTEL trace IDs — zero-friction upgrade path.\n */\nexport function generateTraceId(): string {\n  return randomUUID().replace(/-/g, '');\n}\n\n/**\n * Run a callback within a trace context. Used by the pipeline to establish\n * per-request ALS scope.\n */\nexport function runWithTraceId<T>(id: string, fn: () => T): T {\n  return traceAls.run({ traceId: id }, fn);\n}\n\n/**\n * Replace the trace ID in the current ALS store. Used when OTEL creates\n * a root span and we want to switch from the UUID fallback to the real\n * OTEL trace ID.\n */\nexport function replaceTraceId(newTraceId: string, newSpanId?: string): void {\n  const store = traceAls.getStore();\n  if (store) {\n    store.traceId = newTraceId;\n    store.spanId = newSpanId;\n  }\n}\n\n/**\n * Update the span ID in the current ALS store. Used when entering a new\n * OTEL span to keep log–trace correlation accurate.\n */\nexport function updateSpanId(newSpanId: string | undefined): void {\n  const store = traceAls.getStore();\n  if (store) {\n    store.spanId = newSpanId;\n  }\n}\n\n/**\n * Get the current trace store, or undefined if outside a request context.\n * Framework-internal — use traceId()/spanId() in user code.\n */\nexport function getTraceStore(): TraceStore | undefined {\n  return traceAls.getStore();\n}\n\n// ─── Dev-Mode OTEL Auto-Init ─────────────────────────────────────────────\n\n/**\n * Initialize a minimal OTEL SDK in dev mode so spans are recorded and\n * fed to the DevSpanProcessor for dev log output.\n *\n * If the user already configured an OTEL SDK in register(), we add\n * our DevSpanProcessor alongside theirs. If no SDK is configured,\n * we create a BasicTracerProvider with our processor.\n *\n * Only called in dev mode — zero overhead in production.\n */\nexport async function initDevTracing(\n  config: import('./dev-logger.js').DevLoggerConfig\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const { DevSpanProcessor } = await import('./dev-span-processor.js');\n  const { BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base');\n  const { AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks');\n  const processor = new DevSpanProcessor(config);\n\n  // Register a context manager so OTEL can propagate the active span\n  // across async boundaries. Without this, startActiveSpan can't make\n  // spans \"active\" — child spans get random trace IDs and getActiveSpan()\n  // returns undefined.\n  const contextManager = new AsyncLocalStorageContextManager();\n  contextManager.enable();\n  api.context.setGlobalContextManager(contextManager);\n\n  // Create a minimal TracerProvider with our DevSpanProcessor.\n  // If the user also configures an SDK in register(), their provider\n  // will coexist — the global provider set last wins for new tracers,\n  // but our processor captures all spans from the timber.js tracer.\n  const provider = new BasicTracerProvider({\n    spanProcessors: [processor],\n  });\n  api.trace.setGlobalTracerProvider(provider);\n\n  // Reset cached tracer so next getTracer() picks up the new provider\n  _tracer = undefined;\n}\n\n// ─── OTEL Span Helpers ───────────────────────────────────────────────────\n\n/**\n * Attempt to get the @opentelemetry/api tracer. Returns undefined if the\n * package is not installed or no SDK is registered.\n *\n * timber.js depends on @opentelemetry/api as the vendor-neutral interface.\n * The API is a no-op by default — spans are only emitted when the developer\n * initializes an SDK in register().\n */\nlet _otelApi: typeof import('@opentelemetry/api') | null | undefined;\n\nasync function getOtelApi(): Promise<typeof import('@opentelemetry/api') | null> {\n  if (_otelApi === undefined) {\n    try {\n      _otelApi = await import('@opentelemetry/api');\n    } catch {\n      _otelApi = null;\n    }\n  }\n  return _otelApi;\n}\n\n/** OTEL tracer instance, lazily created. */\nlet _tracer: import('@opentelemetry/api').Tracer | null | undefined;\n\n/**\n * Get the timber.js OTEL tracer. Returns null if @opentelemetry/api is not available.\n */\nexport async function getTracer(): Promise<import('@opentelemetry/api').Tracer | null> {\n  if (_tracer === undefined) {\n    const api = await getOtelApi();\n    if (api) {\n      _tracer = api.trace.getTracer('timber.js');\n    } else {\n      _tracer = null;\n    }\n  }\n  return _tracer;\n}\n\n/**\n * Run a function within an OTEL span. If OTEL is not available, runs the function\n * directly without any span overhead.\n *\n * Automatically:\n * - Creates the span as a child of the current context\n * - Updates the ALS span ID for log–trace correlation\n * - Ends the span when the function completes\n * - Records exceptions on error\n */\nexport async function withSpan<T>(\n  name: string,\n  attributes: Record<string, string | number | boolean>,\n  fn: () => T | Promise<T>\n): Promise<T> {\n  const tracer = await getTracer();\n  if (!tracer) {\n    return fn();\n  }\n\n  const api = (await getOtelApi())!;\n  return tracer.startActiveSpan(name, { attributes }, async (span) => {\n    const prevSpanId = spanId();\n    updateSpanId(span.spanContext().spanId);\n    try {\n      const result = await fn();\n      span.setStatus({ code: api.SpanStatusCode.OK });\n      return result;\n    } catch (error) {\n      span.setStatus({ code: api.SpanStatusCode.ERROR });\n      if (error instanceof Error) {\n        span.recordException(error);\n      }\n      throw error;\n    } finally {\n      span.end();\n      updateSpanId(prevSpanId);\n    }\n  });\n}\n\n/**\n * Set an attribute on the current active span (if any).\n * Used for setting span attributes after span creation (e.g. timber.result on access spans).\n */\nexport async function setSpanAttribute(\n  key: string,\n  value: string | number | boolean\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.setAttribute(key, value);\n  }\n}\n\n/**\n * Add a span event to the current active span (if any).\n * Used for timber.cache HIT/MISS events — recorded as span events, not child spans.\n */\nexport async function addSpanEvent(\n  name: string,\n  attributes?: Record<string, string | number | boolean>\n): Promise<void> {\n  const api = await getOtelApi();\n  if (!api) return;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.addEvent(name, attributes);\n  }\n}\n\n/**\n * Fire-and-forget span event — no await, no microtask overhead.\n *\n * Used on the cache hot path where awaiting addSpanEvent creates an\n * unnecessary microtask per cache operation. If OTEL is not loaded yet,\n * the event is silently dropped (acceptable for diagnostics).\n *\n * See TIM-370 for perf motivation.\n */\nexport function addSpanEventSync(\n  name: string,\n  attributes?: Record<string, string | number | boolean>\n): void {\n  // Fast path: if OTEL API hasn't been loaded yet, skip entirely.\n  // _otelApi is undefined (not yet loaded), null (failed to load), or the module.\n  if (!_otelApi) return;\n\n  const activeSpan = _otelApi.trace.getActiveSpan();\n  if (activeSpan) {\n    activeSpan.addEvent(name, attributes);\n  }\n}\n\n/**\n * Try to extract the OTEL trace ID from the current active span context.\n * Returns undefined if OTEL is not active or no span exists.\n */\nexport async function getOtelTraceId(): Promise<{ traceId: string; spanId: string } | undefined> {\n  const api = await getOtelApi();\n  if (!api) return undefined;\n\n  const activeSpan = api.trace.getActiveSpan();\n  if (!activeSpan) return undefined;\n\n  const ctx = activeSpan.spanContext();\n  // OTEL uses \"0000000000000000\" as invalid trace IDs\n  if (!ctx.traceId || ctx.traceId === '00000000000000000000000000000000') {\n    return undefined;\n  }\n\n  return { traceId: ctx.traceId, spanId: ctx.spanId };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,UAAkB;CAChC,MAAM,QAAQ,SAAS,UAAU;AACjC,KAAI,CAAC,MACH,OAAM,IAAI,MACR,mJAED;AAEH,QAAO,MAAM;;;;;AAMf,SAAgB,SAA6B;AAC3C,QAAO,SAAS,UAAU,EAAE;;;;;;AAS9B,SAAgB,kBAA0B;AACxC,QAAO,YAAY,CAAC,QAAQ,MAAM,GAAG;;;;;;AAOvC,SAAgB,eAAkB,IAAY,IAAgB;AAC5D,QAAO,SAAS,IAAI,EAAE,SAAS,IAAI,EAAE,GAAG;;;;;;;AAQ1C,SAAgB,eAAe,YAAoB,WAA0B;CAC3E,MAAM,QAAQ,SAAS,UAAU;AACjC,KAAI,OAAO;AACT,QAAM,UAAU;AAChB,QAAM,SAAS;;;;;;;AAQnB,SAAgB,aAAa,WAAqC;CAChE,MAAM,QAAQ,SAAS,UAAU;AACjC,KAAI,MACF,OAAM,SAAS;;;;;;AAQnB,SAAgB,gBAAwC;AACtD,QAAO,SAAS,UAAU;;;;;;;;;;AAyD5B,IAAI;AAEJ,eAAe,aAAkE;AAC/E,KAAI,aAAa,KAAA,EACf,KAAI;AACF,aAAW,MAAM,OAAO;SAClB;AACN,aAAW;;AAGf,QAAO;;;AAIT,IAAI;;;;AAKJ,eAAsB,YAAiE;AACrF,KAAI,YAAY,KAAA,GAAW;EACzB,MAAM,MAAM,MAAM,YAAY;AAC9B,MAAI,IACF,WAAU,IAAI,MAAM,UAAU,YAAY;MAE1C,WAAU;;AAGd,QAAO;;;;;;;;;;;;AAaT,eAAsB,SACpB,MACA,YACA,IACY;CACZ,MAAM,SAAS,MAAM,WAAW;AAChC,KAAI,CAAC,OACH,QAAO,IAAI;CAGb,MAAM,MAAO,MAAM,YAAY;AAC/B,QAAO,OAAO,gBAAgB,MAAM,EAAE,YAAY,EAAE,OAAO,SAAS;EAClE,MAAM,aAAa,QAAQ;AAC3B,eAAa,KAAK,aAAa,CAAC,OAAO;AACvC,MAAI;GACF,MAAM,SAAS,MAAM,IAAI;AACzB,QAAK,UAAU,EAAE,MAAM,IAAI,eAAe,IAAI,CAAC;AAC/C,UAAO;WACA,OAAO;AACd,QAAK,UAAU,EAAE,MAAM,IAAI,eAAe,OAAO,CAAC;AAClD,OAAI,iBAAiB,MACnB,MAAK,gBAAgB,MAAM;AAE7B,SAAM;YACE;AACR,QAAK,KAAK;AACV,gBAAa,WAAW;;GAE1B;;;;;;AAOJ,eAAsB,iBACpB,KACA,OACe;CACf,MAAM,MAAM,MAAM,YAAY;AAC9B,KAAI,CAAC,IAAK;CAEV,MAAM,aAAa,IAAI,MAAM,eAAe;AAC5C,KAAI,WACF,YAAW,aAAa,KAAK,MAAM;;;;;;AAQvC,eAAsB,aACpB,MACA,YACe;CACf,MAAM,MAAM,MAAM,YAAY;AAC9B,KAAI,CAAC,IAAK;CAEV,MAAM,aAAa,IAAI,MAAM,eAAe;AAC5C,KAAI,WACF,YAAW,SAAS,MAAM,WAAW;;;;;;;;;;;AAazC,SAAgB,iBACd,MACA,YACM;AAGN,KAAI,CAAC,SAAU;CAEf,MAAM,aAAa,SAAS,MAAM,eAAe;AACjD,KAAI,WACF,YAAW,SAAS,MAAM,WAAW;;;;;;AAQzC,eAAsB,iBAA2E;CAC/F,MAAM,MAAM,MAAM,YAAY;AAC9B,KAAI,CAAC,IAAK,QAAO,KAAA;CAEjB,MAAM,aAAa,IAAI,MAAM,eAAe;AAC5C,KAAI,CAAC,WAAY,QAAO,KAAA;CAExB,MAAM,MAAM,WAAW,aAAa;AAEpC,KAAI,CAAC,IAAI,WAAW,IAAI,YAAY,mCAClC;AAGF,QAAO;EAAE,SAAS,IAAI;EAAS,QAAQ,IAAI;EAAQ"}

package/dist/_chunks/{use-query-states-BvW0TKDn.js → use-query-states-wEXY2JQB.js}

@@ -106,4 +106,4 @@ function bindUseQueryStates(definition) {
 //#endregion
 export { registerSearchParams as i, useQueryStates$1 as n, getSearchParams as r, bindUseQueryStates as t };
 
-//# sourceMappingURL=use-query-states-BvW0TKDn.js.map
+//# sourceMappingURL=use-query-states-wEXY2JQB.js.map

package/dist/_chunks/{use-query-states-BvW0TKDn.js.map → use-query-states-wEXY2JQB.js.map}

@@ -1 +1 @@
-{"version":3,"file":"use-query-states-BvW0TKDn.js","names":[],"sources":["../../src/search-params/registry.ts","../../src/client/use-query-states.ts"],"sourcesContent":["/**\n * Runtime registry for route-scoped search params definitions.\n *\n * When a route's modules load, the framework registers its search-params\n * definition here. useQueryStates('/route') resolves codecs from this map.\n *\n * Design doc: design/23-search-params.md §\"Runtime: Registration at Route Load\"\n */\n\nimport type { SearchParamsDefinition } from './define.js';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst registry = new Map<string, SearchParamsDefinition<any>>();\n\n/**\n * Register a route's search params definition.\n * Called by the generated route manifest loader when a route's modules load.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerSearchParams(route: string, definition: SearchParamsDefinition<any>): void {\n  registry.set(route, definition);\n}\n\n/**\n * Look up a route's search params definition.\n * Returns undefined if the route hasn't been loaded yet.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function getSearchParams(route: string): SearchParamsDefinition<any> | undefined {\n  return registry.get(route);\n}\n","/**\n * useQueryStates — client-side hook for URL-synced search params.\n *\n * Delegates to nuqs for URL synchronization, batching, React 19 transitions,\n * and throttled URL writes. Bridges timber's SearchParamCodec protocol to\n * nuqs-compatible parsers.\n *\n * Design doc: design/23-search-params.md §\"Codec Bridge\"\n */\n\n'use client';\n\nimport { useQueryStates as nuqsUseQueryStates } from 'nuqs';\nimport type { SingleParser } from 'nuqs';\nimport type {\n  SearchParamCodec,\n  SearchParamsDefinition,\n  SetParams,\n  QueryStatesOptions,\n} from '#/search-params/define.js';\nimport { getSearchParams } from '#/search-params/registry.js';\n\n// ─── Codec Bridge ─────────────────────────────────────────────────\n\n/**\n * Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.\n *\n * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }\n * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }\n */\nfunction bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {\n  return {\n    parse: (v: string) => codec.parse(v),\n    serialize: (v: T) => codec.serialize(v) ?? '',\n    defaultValue: codec.parse(undefined) as T,\n    eq: (a: T, b: T) => codec.serialize(a) === codec.serialize(b),\n  };\n}\n\n/**\n * Bridge an entire codec map to nuqs-compatible parsers.\n */\nfunction bridgeCodecs<T extends Record<string, unknown>>(codecs: {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n}) {\n  const result: Record<string, SingleParser<unknown> & { defaultValue: unknown }> = {};\n  for (const key of Object.keys(codecs)) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    result[key] = bridgeCodec(codecs[key as keyof T]) as any;\n  }\n  return result as { [K in keyof T]: SingleParser<T[K]> & { defaultValue: T[K] } };\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────\n\n/**\n * Read and write typed search params from/to the URL.\n *\n * Delegates to nuqs internally. The timber nuqs adapter (auto-injected in\n * browser-entry.ts) handles RSC navigation on non-shallow updates.\n *\n * Usage:\n * ```ts\n * // Via a SearchParamsDefinition\n * const [params, setParams] = definition.useQueryStates()\n *\n * // Standalone with inline codecs\n * const [params, setParams] = useQueryStates({\n *   page: fromSchema(z.coerce.number().int().min(1).default(1)),\n * })\n * ```\n */\nexport function useQueryStates<T extends Record<string, unknown>>(\n  codecsOrRoute: { [K in keyof T]: SearchParamCodec<T[K]> } | string,\n  _options?: QueryStatesOptions,\n  urlKeys?: Readonly<Record<string, string>>\n): [T, SetParams<T>] {\n  // Route-string overload: resolve codecs from the registry\n  let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n  let resolvedUrlKeys = urlKeys;\n  if (typeof codecsOrRoute === 'string') {\n    const definition = getSearchParams(codecsOrRoute);\n    if (!definition) {\n      throw new Error(\n        `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +\n          `Either the route has no search-params.ts file, or it hasn't been loaded yet. ` +\n          `For cross-route usage, import the definition explicitly.`\n      );\n    }\n    codecs = definition.codecs as { [K in keyof T]: SearchParamCodec<T[K]> };\n    resolvedUrlKeys = definition.urlKeys;\n  } else {\n    codecs = codecsOrRoute;\n  }\n\n  const bridged = bridgeCodecs(codecs);\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const nuqsOptions: any = {};\n  if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {\n    nuqsOptions.urlKeys = resolvedUrlKeys;\n  }\n\n  let values: Record<string, unknown>;\n  let setValues: Function;\n  try {\n    [values, setValues] = nuqsUseQueryStates(bridged, nuqsOptions);\n  } catch (err) {\n    if (\n      err instanceof Error &&\n      /Invalid hook call|cannot be called|Cannot read properties of null/i.test(err.message)\n    ) {\n      throw new Error(\n        'useQueryStates is a client component hook and cannot be called outside a React component. ' +\n          'Use definition.parse(searchParams) in server components instead.'\n      );\n    }\n    throw err;\n  }\n\n  // Wrap the nuqs setter to match timber's SetParams<T> signature.\n  // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.\n  // timber's setter accepts Partial<T> with optional SetParamsOptions.\n  const setParams: SetParams<T> = (partial, setOptions?) => {\n    const nuqsSetOptions: Record<string, unknown> = {};\n    if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;\n    if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;\n    if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    void setValues(partial as any, nuqsSetOptions);\n  };\n\n  return [values as T, setParams];\n}\n\n// ─── Definition binding ───────────────────────────────────────────\n\n/**\n * Create a useQueryStates binding for a SearchParamsDefinition.\n * This is used internally by SearchParamsDefinition.useQueryStates().\n */\nexport function bindUseQueryStates<T extends Record<string, unknown>>(\n  definition: SearchParamsDefinition<T>\n): (options?: QueryStatesOptions) => [T, SetParams<T>] {\n  return (options?: QueryStatesOptions) => {\n    return useQueryStates<T>(definition.codecs, options, definition.urlKeys);\n  };\n}\n"],"mappings":";;AAYA,IAAM,2BAAW,IAAI,KAA0C;;;;;AAO/D,SAAgB,qBAAqB,OAAe,YAA+C;AACjG,UAAS,IAAI,OAAO,WAAW;;;;;;AAQjC,SAAgB,gBAAgB,OAAwD;AACtF,QAAO,SAAS,IAAI,MAAM;;;;;;;;;;;;;;;;;;;ACC5B,SAAS,YAAe,OAAmE;AACzF,QAAO;EACL,QAAQ,MAAc,MAAM,MAAM,EAAE;EACpC,YAAY,MAAS,MAAM,UAAU,EAAE,IAAI;EAC3C,cAAc,MAAM,MAAM,KAAA,EAAU;EACpC,KAAK,GAAM,MAAS,MAAM,UAAU,EAAE,KAAK,MAAM,UAAU,EAAE;EAC9D;;;;;AAMH,SAAS,aAAgD,QAEtD;CACD,MAAM,SAA4E,EAAE;AACpF,MAAK,MAAM,OAAO,OAAO,KAAK,OAAO,CAEnC,QAAO,OAAO,YAAY,OAAO,KAAgB;AAEnD,QAAO;;;;;;;;;;;;;;;;;;;AAsBT,SAAgB,iBACd,eACA,UACA,SACmB;CAEnB,IAAI;CACJ,IAAI,kBAAkB;AACtB,KAAI,OAAO,kBAAkB,UAAU;EACrC,MAAM,aAAa,gBAAgB,cAAc;AACjD,MAAI,CAAC,WACH,OAAM,IAAI,MACR,mBAAmB,cAAc,uLAGlC;AAEH,WAAS,WAAW;AACpB,oBAAkB,WAAW;OAE7B,UAAS;CAGX,MAAM,UAAU,aAAa,OAAO;CAGpC,MAAM,cAAmB,EAAE;AAC3B,KAAI,mBAAmB,OAAO,KAAK,gBAAgB,CAAC,SAAS,EAC3D,aAAY,UAAU;CAGxB,IAAI;CACJ,IAAI;AACJ,KAAI;AACF,GAAC,QAAQ,aAAa,eAAmB,SAAS,YAAY;UACvD,KAAK;AACZ,MACE,eAAe,SACf,qEAAqE,KAAK,IAAI,QAAQ,CAEtF,OAAM,IAAI,MACR,6JAED;AAEH,QAAM;;CAMR,MAAM,aAA2B,SAAS,eAAgB;EACxD,MAAM,iBAA0C,EAAE;AAClD,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAC3E,MAAI,YAAY,WAAW,KAAA,EAAW,gBAAe,SAAS,WAAW;AACzE,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAEtE,YAAU,SAAgB,eAAe;;AAGhD,QAAO,CAAC,QAAa,UAAU;;;;;;AASjC,SAAgB,mBACd,YACqD;AACrD,SAAQ,YAAiC;AACvC,SAAO,iBAAkB,WAAW,QAAQ,SAAS,WAAW,QAAQ"}
+{"version":3,"file":"use-query-states-wEXY2JQB.js","names":[],"sources":["../../src/search-params/registry.ts","../../src/client/use-query-states.ts"],"sourcesContent":["/**\n * Runtime registry for route-scoped search params definitions.\n *\n * When a route's modules load, the framework registers its search-params\n * definition here. useQueryStates('/route') resolves codecs from this map.\n *\n * Design doc: design/23-search-params.md §\"Runtime: Registration at Route Load\"\n */\n\nimport type { SearchParamsDefinition } from './define.js';\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst registry = new Map<string, SearchParamsDefinition<any>>();\n\n/**\n * Register a route's search params definition.\n * Called by the generated route manifest loader when a route's modules load.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function registerSearchParams(route: string, definition: SearchParamsDefinition<any>): void {\n  registry.set(route, definition);\n}\n\n/**\n * Look up a route's search params definition.\n * Returns undefined if the route hasn't been loaded yet.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function getSearchParams(route: string): SearchParamsDefinition<any> | undefined {\n  return registry.get(route);\n}\n","/**\n * useQueryStates — client-side hook for URL-synced search params.\n *\n * Delegates to nuqs for URL synchronization, batching, React 19 transitions,\n * and throttled URL writes. Bridges timber's SearchParamCodec protocol to\n * nuqs-compatible parsers.\n *\n * Design doc: design/23-search-params.md §\"Codec Bridge\"\n */\n\n'use client';\n\nimport { useQueryStates as nuqsUseQueryStates } from 'nuqs';\nimport type { SingleParser } from 'nuqs';\nimport type {\n  SearchParamCodec,\n  SearchParamsDefinition,\n  SetParams,\n  QueryStatesOptions,\n} from '#/search-params/define.js';\nimport { getSearchParams } from '#/search-params/registry.js';\n\n// ─── Codec Bridge ─────────────────────────────────────────────────\n\n/**\n * Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.\n *\n * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }\n * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }\n */\nfunction bridgeCodec<T>(codec: SearchParamCodec<T>): SingleParser<T> & { defaultValue: T } {\n  return {\n    parse: (v: string) => codec.parse(v),\n    serialize: (v: T) => codec.serialize(v) ?? '',\n    defaultValue: codec.parse(undefined) as T,\n    eq: (a: T, b: T) => codec.serialize(a) === codec.serialize(b),\n  };\n}\n\n/**\n * Bridge an entire codec map to nuqs-compatible parsers.\n */\nfunction bridgeCodecs<T extends Record<string, unknown>>(codecs: {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n}) {\n  const result: Record<string, SingleParser<unknown> & { defaultValue: unknown }> = {};\n  for (const key of Object.keys(codecs)) {\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    result[key] = bridgeCodec(codecs[key as keyof T]) as any;\n  }\n  return result as { [K in keyof T]: SingleParser<T[K]> & { defaultValue: T[K] } };\n}\n\n// ─── Hook ─────────────────────────────────────────────────────────\n\n/**\n * Read and write typed search params from/to the URL.\n *\n * Delegates to nuqs internally. The timber nuqs adapter (auto-injected in\n * browser-entry.ts) handles RSC navigation on non-shallow updates.\n *\n * Usage:\n * ```ts\n * // Via a SearchParamsDefinition\n * const [params, setParams] = definition.useQueryStates()\n *\n * // Standalone with inline codecs\n * const [params, setParams] = useQueryStates({\n *   page: fromSchema(z.coerce.number().int().min(1).default(1)),\n * })\n * ```\n */\nexport function useQueryStates<T extends Record<string, unknown>>(\n  codecsOrRoute: { [K in keyof T]: SearchParamCodec<T[K]> } | string,\n  _options?: QueryStatesOptions,\n  urlKeys?: Readonly<Record<string, string>>\n): [T, SetParams<T>] {\n  // Route-string overload: resolve codecs from the registry\n  let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n  let resolvedUrlKeys = urlKeys;\n  if (typeof codecsOrRoute === 'string') {\n    const definition = getSearchParams(codecsOrRoute);\n    if (!definition) {\n      throw new Error(\n        `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +\n          `Either the route has no search-params.ts file, or it hasn't been loaded yet. ` +\n          `For cross-route usage, import the definition explicitly.`\n      );\n    }\n    codecs = definition.codecs as { [K in keyof T]: SearchParamCodec<T[K]> };\n    resolvedUrlKeys = definition.urlKeys;\n  } else {\n    codecs = codecsOrRoute;\n  }\n\n  const bridged = bridgeCodecs(codecs);\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const nuqsOptions: any = {};\n  if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) {\n    nuqsOptions.urlKeys = resolvedUrlKeys;\n  }\n\n  let values: Record<string, unknown>;\n  let setValues: Function;\n  try {\n    [values, setValues] = nuqsUseQueryStates(bridged, nuqsOptions);\n  } catch (err) {\n    if (\n      err instanceof Error &&\n      /Invalid hook call|cannot be called|Cannot read properties of null/i.test(err.message)\n    ) {\n      throw new Error(\n        'useQueryStates is a client component hook and cannot be called outside a React component. ' +\n          'Use definition.parse(searchParams) in server components instead.'\n      );\n    }\n    throw err;\n  }\n\n  // Wrap the nuqs setter to match timber's SetParams<T> signature.\n  // nuqs's setter accepts Partial<Nullable<Values>> | UpdaterFn | null.\n  // timber's setter accepts Partial<T> with optional SetParamsOptions.\n  const setParams: SetParams<T> = (partial, setOptions?) => {\n    const nuqsSetOptions: Record<string, unknown> = {};\n    if (setOptions?.shallow !== undefined) nuqsSetOptions.shallow = setOptions.shallow;\n    if (setOptions?.scroll !== undefined) nuqsSetOptions.scroll = setOptions.scroll;\n    if (setOptions?.history !== undefined) nuqsSetOptions.history = setOptions.history;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    void setValues(partial as any, nuqsSetOptions);\n  };\n\n  return [values as T, setParams];\n}\n\n// ─── Definition binding ───────────────────────────────────────────\n\n/**\n * Create a useQueryStates binding for a SearchParamsDefinition.\n * This is used internally by SearchParamsDefinition.useQueryStates().\n */\nexport function bindUseQueryStates<T extends Record<string, unknown>>(\n  definition: SearchParamsDefinition<T>\n): (options?: QueryStatesOptions) => [T, SetParams<T>] {\n  return (options?: QueryStatesOptions) => {\n    return useQueryStates<T>(definition.codecs, options, definition.urlKeys);\n  };\n}\n"],"mappings":";;AAYA,IAAM,2BAAW,IAAI,KAA0C;;;;;AAO/D,SAAgB,qBAAqB,OAAe,YAA+C;AACjG,UAAS,IAAI,OAAO,WAAW;;;;;;AAQjC,SAAgB,gBAAgB,OAAwD;AACtF,QAAO,SAAS,IAAI,MAAM;;;;;;;;;;;;;;;;;;;ACC5B,SAAS,YAAe,OAAmE;AACzF,QAAO;EACL,QAAQ,MAAc,MAAM,MAAM,EAAE;EACpC,YAAY,MAAS,MAAM,UAAU,EAAE,IAAI;EAC3C,cAAc,MAAM,MAAM,KAAA,EAAU;EACpC,KAAK,GAAM,MAAS,MAAM,UAAU,EAAE,KAAK,MAAM,UAAU,EAAE;EAC9D;;;;;AAMH,SAAS,aAAgD,QAEtD;CACD,MAAM,SAA4E,EAAE;AACpF,MAAK,MAAM,OAAO,OAAO,KAAK,OAAO,CAEnC,QAAO,OAAO,YAAY,OAAO,KAAgB;AAEnD,QAAO;;;;;;;;;;;;;;;;;;;AAsBT,SAAgB,iBACd,eACA,UACA,SACmB;CAEnB,IAAI;CACJ,IAAI,kBAAkB;AACtB,KAAI,OAAO,kBAAkB,UAAU;EACrC,MAAM,aAAa,gBAAgB,cAAc;AACjD,MAAI,CAAC,WACH,OAAM,IAAI,MACR,mBAAmB,cAAc,uLAGlC;AAEH,WAAS,WAAW;AACpB,oBAAkB,WAAW;OAE7B,UAAS;CAGX,MAAM,UAAU,aAAa,OAAO;CAGpC,MAAM,cAAmB,EAAE;AAC3B,KAAI,mBAAmB,OAAO,KAAK,gBAAgB,CAAC,SAAS,EAC3D,aAAY,UAAU;CAGxB,IAAI;CACJ,IAAI;AACJ,KAAI;AACF,GAAC,QAAQ,aAAa,eAAmB,SAAS,YAAY;UACvD,KAAK;AACZ,MACE,eAAe,SACf,qEAAqE,KAAK,IAAI,QAAQ,CAEtF,OAAM,IAAI,MACR,6JAED;AAEH,QAAM;;CAMR,MAAM,aAA2B,SAAS,eAAgB;EACxD,MAAM,iBAA0C,EAAE;AAClD,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAC3E,MAAI,YAAY,WAAW,KAAA,EAAW,gBAAe,SAAS,WAAW;AACzE,MAAI,YAAY,YAAY,KAAA,EAAW,gBAAe,UAAU,WAAW;AAEtE,YAAU,SAAgB,eAAe;;AAGhD,QAAO,CAAC,QAAa,UAAU;;;;;;AASjC,SAAgB,mBACd,YACqD;AACrD,SAAQ,YAAiC;AACvC,SAAO,iBAAkB,WAAW,QAAQ,SAAS,WAAW,QAAQ"}

package/dist/_chunks/wrappers-C9XPg7-U.js

@@ -0,0 +1,63 @@
+//#region src/search-params/wrappers.ts
+/**
+* Wrap a nullable codec with a default value. When the inner codec returns
+* null, the default is used instead. The output type becomes non-nullable.
+*
+* Works with any codec — nuqs parsers, custom codecs, fromSchema results.
+*
+* ```ts
+* import { parseAsInteger } from 'nuqs'
+* import { withDefault } from '@timber-js/app/search-params'
+*
+* const page = withDefault(parseAsInteger, 1)
+* // page.parse(undefined) → 1 (not null)
+* // page.parse('5') → 5
+* ```
+*/
+function withDefault(codec, defaultValue) {
+	return {
+		parse(value) {
+			const result = codec.parse(value);
+			return result === null ? defaultValue : result;
+		},
+		serialize(value) {
+			return codec.serialize(value);
+		}
+	};
+}
+/**
+* Attach a URL key alias to a codec. The alias determines what query
+* parameter key is used in the URL, while the TypeScript property name
+* stays descriptive.
+*
+* Aliases travel with codecs through object spread composition — when
+* you spread a bundle containing aliased codecs into defineSearchParams,
+* the aliases come along automatically.
+*
+* ```ts
+* import { parseAsString } from 'nuqs'
+* import { withUrlKey } from '@timber-js/app/search-params'
+*
+* export const searchable = {
+*   q: withUrlKey(parseAsString, 'search'),
+*   // ?search=shoes → { q: 'shoes' }
+* }
+* ```
+*
+* Composes with withDefault:
+* ```ts
+* import { parseAsInteger } from 'nuqs'
+* withUrlKey(withDefault(parseAsInteger, 1), 'p')
+* ```
+*/
+function withUrlKey(codec, urlKey) {
+	return {
+		parse: codec.parse.bind(codec),
+		serialize: codec.serialize.bind(codec),
+		urlKey
+	};
+}
+//#endregion
+export { withUrlKey as n, withDefault as t };
+
+//# sourceMappingURL=wrappers-C9XPg7-U.js.map

package/dist/_chunks/wrappers-C9XPg7-U.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrappers-C9XPg7-U.js","names":[],"sources":["../../src/search-params/wrappers.ts"],"sourcesContent":["/**\n * Codec wrappers — withDefault and withUrlKey.\n *\n * These are timber-specific utilities that work with any SearchParamCodec.\n * For actual codecs (string, integer, boolean, etc.), use nuqs parsers\n * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.\n *\n * Design doc: design/23-search-params.md\n */\n\nimport type { SearchParamCodec, SearchParamCodecWithUrlKey } from './define.js';\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. When the inner codec returns\n * null, the default is used instead. The output type becomes non-nullable.\n *\n * Works with any codec — nuqs parsers, custom codecs, fromSchema results.\n *\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * import { withDefault } from '@timber-js/app/search-params'\n *\n * const page = withDefault(parseAsInteger, 1)\n * // page.parse(undefined) → 1 (not null)\n * // page.parse('5') → 5\n * ```\n */\nexport function withDefault<T>(\n  codec: SearchParamCodec<T | null>,\n  defaultValue: T\n): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      const result = codec.parse(value);\n      return result === null ? defaultValue : result;\n    },\n    serialize(value: T): string | null {\n      return codec.serialize(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// withUrlKey\n// ---------------------------------------------------------------------------\n\n/**\n * Attach a URL key alias to a codec. The alias determines what query\n * parameter key is used in the URL, while the TypeScript property name\n * stays descriptive.\n *\n * Aliases travel with codecs through object spread composition — when\n * you spread a bundle containing aliased codecs into defineSearchParams,\n * the aliases come along automatically.\n *\n * ```ts\n * import { parseAsString } from 'nuqs'\n * import { withUrlKey } from '@timber-js/app/search-params'\n *\n * export const searchable = {\n *   q: withUrlKey(parseAsString, 'search'),\n *   // ?search=shoes → { q: 'shoes' }\n * }\n * ```\n *\n * Composes with withDefault:\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * withUrlKey(withDefault(parseAsInteger, 1), 'p')\n * ```\n */\nexport function withUrlKey<T>(\n  codec: SearchParamCodec<T>,\n  urlKey: string\n): SearchParamCodecWithUrlKey<T> {\n  return {\n    parse: codec.parse.bind(codec),\n    serialize: codec.serialize.bind(codec),\n    urlKey,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA+BA,SAAgB,YACd,OACA,cACqB;AACrB,QAAO;EACL,MAAM,OAAyC;GAC7C,MAAM,SAAS,MAAM,MAAM,MAAM;AACjC,UAAO,WAAW,OAAO,eAAe;;EAE1C,UAAU,OAAyB;AACjC,UAAO,MAAM,UAAU,MAAM;;EAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCH,SAAgB,WACd,OACA,QAC+B;AAC/B,QAAO;EACL,OAAO,MAAM,MAAM,KAAK,MAAM;EAC9B,WAAW,MAAM,UAAU,KAAK,MAAM;EACtC;EACD"}

package/dist/cache/index.js

@@ -1,4 +1,4 @@
-import { n as addSpanEventSync } from "../_chunks/tracing-CuXiCP5p.js";
+import { n as addSpanEventSync } from "../_chunks/tracing-JI4cYUdz.js";
 //#region src/cache/redis-handler.ts
 var KEY_PREFIX = "timber:cache:";
 var TAG_PREFIX = "timber:tag:";

package/dist/client/error-boundary.js

@@ -1,4 +1,4 @@
 "use client";
 "use client";
-import { t as TimberErrorBoundary } from "../_chunks/error-boundary-BAN3751q.js";
+import { t as TimberErrorBoundary } from "../_chunks/error-boundary-B9vT_YK_.js";
 export { TimberErrorBoundary };

package/dist/client/index.js

@@ -1,9 +1,9 @@
 "use client";
 import { n as __exportAll } from "../_chunks/chunk-DYhsFzuS.js";
-import { n as useSegmentContext, r as mergePreservedSearchParams, t as SegmentProvider } from "../_chunks/segment-context-C6byCyZU.js";
-import { a as _setCachedSearch, c as cachedSearch, d as globalRouter, i as setSsrData, l as cachedSearchParams, n as clearSsrData, o as _setCurrentParams, r as getSsrData, s as _setGlobalRouter, t as TimberErrorBoundary, u as currentParams } from "../_chunks/error-boundary-BAN3751q.js";
-import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-BvW0TKDn.js";
-import { t as _registerUseCookieModule } from "../_chunks/define-cookie-BmKbSyp0.js";
+import { n as useQueryStates, t as bindUseQueryStates } from "../_chunks/use-query-states-wEXY2JQB.js";
+import { n as useSegmentContext, r as mergePreservedSearchParams, t as SegmentProvider } from "../_chunks/segment-context-DBn-nrMN.js";
+import { a as _setCachedSearch, c as cachedSearch, d as globalRouter, i as setSsrData, l as cachedSearchParams, n as clearSsrData, o as _setCurrentParams, r as getSsrData, s as _setGlobalRouter, t as TimberErrorBoundary, u as currentParams } from "../_chunks/error-boundary-B9vT_YK_.js";
+import { t as _registerUseCookieModule } from "../_chunks/define-cookie-k9btcEfI.js";
 import React, { cloneElement, createContext, createElement, isValidElement, useActionState as useActionState$1, useContext, useSyncExternalStore, useTransition } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/client/use-link-status.ts
@@ -1105,7 +1105,7 @@ function createRouter(deps) {
 			restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
 		} catch (error) {
 			if (error instanceof VersionSkewError) {
-				const { triggerStaleReload } = await import("../_chunks/stale-reload-C0ValzG7.js");
+				const { triggerStaleReload } = await import("../_chunks/stale-reload-4L-_skC7.js");
 				triggerStaleReload();
 				return new Promise(() => {});
 			}

package/dist/cookies/index.js

@@ -1,2 +1,2 @@
-import { n as defineCookie } from "../_chunks/define-cookie-BmKbSyp0.js";
+import { n as defineCookie } from "../_chunks/define-cookie-k9btcEfI.js";
 export { defineCookie };

package/dist/params/index.js

@@ -1,4 +1,5 @@
-import { a as fromSchema, i as fromArraySchema, n as withUrlKey, r as defineSearchParams, t as withDefault } from "../_chunks/wrappers-C6J0nNji.js";
+import { i as fromSchema, n as defineSearchParams, r as fromArraySchema } from "../_chunks/define-TK8C1M3x.js";
+import { n as withUrlKey, t as withDefault } from "../_chunks/wrappers-C9XPg7-U.js";
 //#region src/params/define.ts
 function isStandardSchema(value) {
 	return typeof value === "object" && value !== null && "~standard" in value && typeof value["~standard"]?.validate === "function";

package/dist/params/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/params/define.ts"],"sourcesContent":["/**\n * defineParams — factory for typed route param coercion.\n *\n * Creates a ParamsDefinition that coerces raw string params from the\n * URL into typed values. Used by exporting from layout.tsx (segment-level)\n * or page.tsx (fallback).\n *\n * Reuses the shared Codec<T> protocol with Standard Schema auto-detection,\n * same pattern as defineSearchParams. Runtime constraints are stricter:\n * - serialize must return string (not null — path segments can't be omitted)\n * - parse throwing → 404 (invalid param value)\n *\n * Design doc: design/07a-route-params-triage.md\n */\n\nimport type { Codec } from '#/codec.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Infer the output type from a Codec or StandardSchemaV1. */\nexport type InferParamField<V> =\n  V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;\n\n/** Acceptable field value for defineParams: a Codec or a Standard Schema. */\nexport type ParamField<T = unknown> = Codec<T> | StandardSchemaV1<T>;\n\n/**\n * A typed route params definition.\n *\n * Returned by defineParams(). Provides parse (string → typed) and\n * serialize (typed → string) for each declared param.\n */\nexport interface ParamsDefinition<T extends Record<string, unknown>> {\n  /** Parse raw string params into typed values. Throws on invalid values. */\n  parse(raw: Record<string, string | string[]>): T;\n\n  /** Serialize typed values back to strings for URL construction. */\n  serialize(values: T): Record<string, string>;\n\n  /** Read-only codec map. */\n  codecs: { [K in keyof T]: Codec<T[K]> };\n}\n\n// ---------------------------------------------------------------------------\n// Standard Schema interface (subset — same as in search-params/define.ts)\n// ---------------------------------------------------------------------------\n\ninterface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(\n      value: unknown\n    ):\n      | { value: Output; issues?: undefined }\n      | { value?: undefined; issues: ReadonlyArray<{ message: string }> }\n      | Promise<\n          | { value: Output; issues?: undefined }\n          | { value?: undefined; issues: ReadonlyArray<{ message: string }> }\n        >;\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nfunction isStandardSchema(value: unknown): value is StandardSchemaV1 {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    '~standard' in value &&\n    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'\n  );\n}\n\nfunction isCodec(value: unknown): value is Codec<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as Codec<unknown>).parse === 'function' &&\n    typeof (value as Codec<unknown>).serialize === 'function'\n  );\n}\n\n/**\n * Validate sync for Standard Schema (same helper as search-params/codecs.ts).\n */\nfunction validateSync<Output>(\n  schema: StandardSchemaV1<Output>,\n  value: unknown\n):\n  | { value: Output; issues?: undefined }\n  | { value?: undefined; issues: ReadonlyArray<{ message: string }> } {\n  const result = schema['~standard'].validate(value);\n  if (result instanceof Promise) {\n    throw new Error(\n      '[timber] defineParams: schema returned a Promise — only sync schemas are supported.'\n    );\n  }\n  return result;\n}\n\n/**\n * Wrap a Standard Schema into a Codec for route params.\n *\n * Unlike fromSchema for search params:\n * - Parse throws on failure (no fallback to default)\n * - Serialize returns string (not null)\n */\nfunction fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Route params are always strings (single segment) or string[] (catch-all)\n      const input = Array.isArray(value) ? value : value;\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // For route params, parse failure means the param is invalid → throw\n      const messages = result.issues.map((i) => i.message).join(', ');\n      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      // Catch-all segments produce arrays — join with '/' for path reconstruction\n      if (Array.isArray(value)) {\n        return value.join('/');\n      }\n      return String(value);\n    },\n  };\n}\n\n/**\n * Resolve a field value to a Codec. Auto-detects Standard Schema objects.\n */\nfunction resolveField(fieldName: string, value: ParamField): Codec<unknown> {\n  if (isCodec(value)) {\n    return value;\n  }\n\n  if (isStandardSchema(value)) {\n    return fromParamSchema(fieldName, value);\n  }\n\n  throw new Error(\n    `[timber] defineParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n      `(Zod, Valibot, ArkType).`\n  );\n}\n\n/**\n * Validate that no codec's serialize returns null.\n * Route params are structural — they must produce a valid path segment.\n */\nfunction validateSerialize(codecMap: Record<string, Codec<unknown>>): void {\n  for (const [key, codec] of Object.entries(codecMap)) {\n    // Test serialize with a sample parsed value to check for null\n    // We can't exhaustively test, but we can check that serialize(parse(\"test\"))\n    // doesn't return null for a basic input.\n    try {\n      const testValue = codec.parse('test');\n      const serialized = codec.serialize(testValue);\n      if (serialized === null) {\n        throw new Error(\n          `[timber] defineParams: field '${key}' codec.serialize() returned null.\\n` +\n            `  Route params are path segments — they cannot be omitted.\\n` +\n            `  Ensure serialize() always returns a string.`\n        );\n      }\n    } catch (e) {\n      // parse('test') may throw for strict codecs (e.g., number-only).\n      // That's fine — it means the codec validates. We only care about\n      // serialize returning null, which we can't test without a valid value.\n      if (e instanceof Error && e.message.includes('returned null')) {\n        throw e;\n      }\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.\n *\n * ```ts\n * // app/products/[id]/layout.tsx\n * import { defineParams } from '@timber-js/app/params'\n * import { z } from 'zod/v4'\n *\n * export const params = defineParams({\n *   id: z.coerce.number().int().positive(),\n * })\n *\n * export default function Layout({ children }) { return children }\n * ```\n */\nexport function defineSegmentParams<C extends Record<string, ParamField>>(\n  codecs: C\n): ParamsDefinition<{ [K in keyof C]: InferParamField<C[K]> }> {\n  type T = { [K in keyof C]: InferParamField<C[K]> };\n\n  const resolvedCodecs: Record<string, Codec<unknown>> = {};\n\n  for (const [key, value] of Object.entries(codecs)) {\n    resolvedCodecs[key] = resolveField(key, value as ParamField);\n  }\n\n  // Validate that serialize doesn't return null\n  validateSerialize(resolvedCodecs);\n\n  // ---- parse ----\n  function parse(raw: Record<string, string | string[]>): T {\n    const result: Record<string, unknown> = {};\n\n    for (const [key, codec] of Object.entries(resolvedCodecs)) {\n      const rawValue = raw[key];\n      // Route params are always present (the route matched)\n      result[key] = codec.parse(rawValue);\n    }\n\n    return result as T;\n  }\n\n  // ---- serialize ----\n  function serialize(values: T): Record<string, string> {\n    const result: Record<string, string> = {};\n\n    for (const [key, codec] of Object.entries(resolvedCodecs)) {\n      const serialized = codec.serialize(values[key as keyof T] as unknown);\n      if (serialized === null) {\n        throw new Error(\n          `[timber] params.serialize: field '${key}' serialized to null. ` +\n            `Route params must produce a valid path segment.`\n        );\n      }\n      result[key] = serialized;\n    }\n\n    return result;\n  }\n\n  const definition: ParamsDefinition<T> = {\n    parse,\n    serialize,\n    codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },\n  };\n\n  return definition;\n}\n"],"mappings":";;AAmEA,SAAS,iBAAiB,OAA2C;AACnE,QACE,OAAO,UAAU,YACjB,UAAU,QACV,eAAe,SACf,OAAQ,MAA2B,cAAc,aAAa;;AAIlE,SAAS,QAAQ,OAAyC;AACxD,QACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAAyB,UAAU,cAC3C,OAAQ,MAAyB,cAAc;;;;;AAOnD,SAAS,aACP,QACA,OAGoE;CACpE,MAAM,SAAS,OAAO,aAAa,SAAS,MAAM;AAClD,KAAI,kBAAkB,QACpB,OAAM,IAAI,MACR,sFACD;AAEH,QAAO;;;;;;;;;AAUT,SAAS,gBAAmB,WAAmB,QAAuC;AACpF,QAAO;EACL,MAAM,OAAyC;GAI7C,MAAM,SAAS,aAAa,QAFd,MAAM,QAAQ,MAAM,GAAG,QAAQ,MAEH;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,WAAW,OAAO,OAAO,KAAK,MAAM,EAAE,QAAQ,CAAC,KAAK,KAAK;AAC/D,SAAM,IAAI,MAAM,mBAAmB,UAAU,qBAAqB,WAAW;;EAG/E,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAGT,OAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MAAM,KAAK,IAAI;AAExB,UAAO,OAAO,MAAM;;EAEvB;;;;;AAMH,SAAS,aAAa,WAAmB,OAAmC;AAC1E,KAAI,QAAQ,MAAM,CAChB,QAAO;AAGT,KAAI,iBAAiB,MAAM,CACzB,QAAO,gBAAgB,WAAW,MAAM;AAG1C,OAAM,IAAI,MACR,iCAAiC,UAAU,uJAG5C;;;;;;AAOH,SAAS,kBAAkB,UAAgD;AACzE,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,CAIjD,KAAI;EACF,MAAM,YAAY,MAAM,MAAM,OAAO;AAErC,MADmB,MAAM,UAAU,UAAU,KAC1B,KACjB,OAAM,IAAI,MACR,iCAAiC,IAAI,+IAGtC;UAEI,GAAG;AAIV,MAAI,aAAa,SAAS,EAAE,QAAQ,SAAS,gBAAgB,CAC3D,OAAM;;;;;;;;;;;;;;;;;;AAyBd,SAAgB,oBACd,QAC6D;CAG7D,MAAM,iBAAiD,EAAE;AAEzD,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,CAC/C,gBAAe,OAAO,aAAa,KAAK,MAAoB;AAI9D,mBAAkB,eAAe;CAGjC,SAAS,MAAM,KAA2C;EACxD,MAAM,SAAkC,EAAE;AAE1C,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,eAAe,EAAE;GACzD,MAAM,WAAW,IAAI;AAErB,UAAO,OAAO,MAAM,MAAM,SAAS;;AAGrC,SAAO;;CAIT,SAAS,UAAU,QAAmC;EACpD,MAAM,SAAiC,EAAE;AAEzC,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,eAAe,EAAE;GACzD,MAAM,aAAa,MAAM,UAAU,OAAO,KAA2B;AACrE,OAAI,eAAe,KACjB,OAAM,IAAI,MACR,qCAAqC,IAAI,uEAE1C;AAEH,UAAO,OAAO;;AAGhB,SAAO;;AAST,QANwC;EACtC;EACA;EACA,QAAQ;EACT"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/params/define.ts"],"sourcesContent":["/**\n * defineParams — factory for typed route param coercion.\n *\n * Creates a ParamsDefinition that coerces raw string params from the\n * URL into typed values. Used by exporting from layout.tsx (segment-level)\n * or page.tsx (fallback).\n *\n * Reuses the shared Codec<T> protocol with Standard Schema auto-detection,\n * same pattern as defineSearchParams. Runtime constraints are stricter:\n * - serialize must return string (not null — path segments can't be omitted)\n * - parse throwing → 404 (invalid param value)\n *\n * Design doc: design/07a-route-params-triage.md\n */\n\nimport type { Codec } from '#/codec.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Infer the output type from a Codec or StandardSchemaV1. */\nexport type InferParamField<V> =\n  V extends Codec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;\n\n/** Acceptable field value for defineParams: a Codec or a Standard Schema. */\nexport type ParamField<T = unknown> = Codec<T> | StandardSchemaV1<T>;\n\n/**\n * A typed route params definition.\n *\n * Returned by defineParams(). Provides parse (string → typed) and\n * serialize (typed → string) for each declared param.\n */\nexport interface ParamsDefinition<T extends Record<string, unknown>> {\n  /** Parse raw string params into typed values. Throws on invalid values. */\n  parse(raw: Record<string, string | string[]>): T;\n\n  /** Serialize typed values back to strings for URL construction. */\n  serialize(values: T): Record<string, string>;\n\n  /** Read-only codec map. */\n  codecs: { [K in keyof T]: Codec<T[K]> };\n}\n\n// ---------------------------------------------------------------------------\n// Standard Schema interface (subset — same as in search-params/define.ts)\n// ---------------------------------------------------------------------------\n\ninterface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(\n      value: unknown\n    ):\n      | { value: Output; issues?: undefined }\n      | { value?: undefined; issues: ReadonlyArray<{ message: string }> }\n      | Promise<\n          | { value: Output; issues?: undefined }\n          | { value?: undefined; issues: ReadonlyArray<{ message: string }> }\n        >;\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nfunction isStandardSchema(value: unknown): value is StandardSchemaV1 {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    '~standard' in value &&\n    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'\n  );\n}\n\nfunction isCodec(value: unknown): value is Codec<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as Codec<unknown>).parse === 'function' &&\n    typeof (value as Codec<unknown>).serialize === 'function'\n  );\n}\n\n/**\n * Validate sync for Standard Schema (same helper as search-params/codecs.ts).\n */\nfunction validateSync<Output>(\n  schema: StandardSchemaV1<Output>,\n  value: unknown\n):\n  | { value: Output; issues?: undefined }\n  | { value?: undefined; issues: ReadonlyArray<{ message: string }> } {\n  const result = schema['~standard'].validate(value);\n  if (result instanceof Promise) {\n    throw new Error(\n      '[timber] defineParams: schema returned a Promise — only sync schemas are supported.'\n    );\n  }\n  return result;\n}\n\n/**\n * Wrap a Standard Schema into a Codec for route params.\n *\n * Unlike fromSchema for search params:\n * - Parse throws on failure (no fallback to default)\n * - Serialize returns string (not null)\n */\nfunction fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Route params are always strings (single segment) or string[] (catch-all)\n      const input = Array.isArray(value) ? value : value;\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // For route params, parse failure means the param is invalid → throw\n      const messages = result.issues.map((i) => i.message).join(', ');\n      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      // Catch-all segments produce arrays — join with '/' for path reconstruction\n      if (Array.isArray(value)) {\n        return value.join('/');\n      }\n      return String(value);\n    },\n  };\n}\n\n/**\n * Resolve a field value to a Codec. Auto-detects Standard Schema objects.\n */\nfunction resolveField(fieldName: string, value: ParamField): Codec<unknown> {\n  if (isCodec(value)) {\n    return value;\n  }\n\n  if (isStandardSchema(value)) {\n    return fromParamSchema(fieldName, value);\n  }\n\n  throw new Error(\n    `[timber] defineParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n      `(Zod, Valibot, ArkType).`\n  );\n}\n\n/**\n * Validate that no codec's serialize returns null.\n * Route params are structural — they must produce a valid path segment.\n */\nfunction validateSerialize(codecMap: Record<string, Codec<unknown>>): void {\n  for (const [key, codec] of Object.entries(codecMap)) {\n    // Test serialize with a sample parsed value to check for null\n    // We can't exhaustively test, but we can check that serialize(parse(\"test\"))\n    // doesn't return null for a basic input.\n    try {\n      const testValue = codec.parse('test');\n      const serialized = codec.serialize(testValue);\n      if (serialized === null) {\n        throw new Error(\n          `[timber] defineParams: field '${key}' codec.serialize() returned null.\\n` +\n            `  Route params are path segments — they cannot be omitted.\\n` +\n            `  Ensure serialize() always returns a string.`\n        );\n      }\n    } catch (e) {\n      // parse('test') may throw for strict codecs (e.g., number-only).\n      // That's fine — it means the codec validates. We only care about\n      // serialize returning null, which we can't test without a valid value.\n      if (e instanceof Error && e.message.includes('returned null')) {\n        throw e;\n      }\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a ParamsDefinition from a map of codecs and/or Standard Schema objects.\n *\n * ```ts\n * // app/products/[id]/layout.tsx\n * import { defineParams } from '@timber-js/app/params'\n * import { z } from 'zod/v4'\n *\n * export const params = defineParams({\n *   id: z.coerce.number().int().positive(),\n * })\n *\n * export default function Layout({ children }) { return children }\n * ```\n */\nexport function defineSegmentParams<C extends Record<string, ParamField>>(\n  codecs: C\n): ParamsDefinition<{ [K in keyof C]: InferParamField<C[K]> }> {\n  type T = { [K in keyof C]: InferParamField<C[K]> };\n\n  const resolvedCodecs: Record<string, Codec<unknown>> = {};\n\n  for (const [key, value] of Object.entries(codecs)) {\n    resolvedCodecs[key] = resolveField(key, value as ParamField);\n  }\n\n  // Validate that serialize doesn't return null\n  validateSerialize(resolvedCodecs);\n\n  // ---- parse ----\n  function parse(raw: Record<string, string | string[]>): T {\n    const result: Record<string, unknown> = {};\n\n    for (const [key, codec] of Object.entries(resolvedCodecs)) {\n      const rawValue = raw[key];\n      // Route params are always present (the route matched)\n      result[key] = codec.parse(rawValue);\n    }\n\n    return result as T;\n  }\n\n  // ---- serialize ----\n  function serialize(values: T): Record<string, string> {\n    const result: Record<string, string> = {};\n\n    for (const [key, codec] of Object.entries(resolvedCodecs)) {\n      const serialized = codec.serialize(values[key as keyof T] as unknown);\n      if (serialized === null) {\n        throw new Error(\n          `[timber] params.serialize: field '${key}' serialized to null. ` +\n            `Route params must produce a valid path segment.`\n        );\n      }\n      result[key] = serialized;\n    }\n\n    return result;\n  }\n\n  const definition: ParamsDefinition<T> = {\n    parse,\n    serialize,\n    codecs: resolvedCodecs as { [K in keyof T]: Codec<T[K]> },\n  };\n\n  return definition;\n}\n"],"mappings":";;;AAmEA,SAAS,iBAAiB,OAA2C;AACnE,QACE,OAAO,UAAU,YACjB,UAAU,QACV,eAAe,SACf,OAAQ,MAA2B,cAAc,aAAa;;AAIlE,SAAS,QAAQ,OAAyC;AACxD,QACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAAyB,UAAU,cAC3C,OAAQ,MAAyB,cAAc;;;;;AAOnD,SAAS,aACP,QACA,OAGoE;CACpE,MAAM,SAAS,OAAO,aAAa,SAAS,MAAM;AAClD,KAAI,kBAAkB,QACpB,OAAM,IAAI,MACR,sFACD;AAEH,QAAO;;;;;;;;;AAUT,SAAS,gBAAmB,WAAmB,QAAuC;AACpF,QAAO;EACL,MAAM,OAAyC;GAI7C,MAAM,SAAS,aAAa,QAFd,MAAM,QAAQ,MAAM,GAAG,QAAQ,MAEH;AAC1C,OAAI,CAAC,OAAO,OACV,QAAO,OAAO;GAIhB,MAAM,WAAW,OAAO,OAAO,KAAK,MAAM,EAAE,QAAQ,CAAC,KAAK,KAAK;AAC/D,SAAM,IAAI,MAAM,mBAAmB,UAAU,qBAAqB,WAAW;;EAG/E,UAAU,OAAyB;AACjC,OAAI,UAAU,QAAQ,UAAU,KAAA,EAC9B,QAAO;AAGT,OAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MAAM,KAAK,IAAI;AAExB,UAAO,OAAO,MAAM;;EAEvB;;;;;AAMH,SAAS,aAAa,WAAmB,OAAmC;AAC1E,KAAI,QAAQ,MAAM,CAChB,QAAO;AAGT,KAAI,iBAAiB,MAAM,CACzB,QAAO,gBAAgB,WAAW,MAAM;AAG1C,OAAM,IAAI,MACR,iCAAiC,UAAU,uJAG5C;;;;;;AAOH,SAAS,kBAAkB,UAAgD;AACzE,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,CAIjD,KAAI;EACF,MAAM,YAAY,MAAM,MAAM,OAAO;AAErC,MADmB,MAAM,UAAU,UAAU,KAC1B,KACjB,OAAM,IAAI,MACR,iCAAiC,IAAI,+IAGtC;UAEI,GAAG;AAIV,MAAI,aAAa,SAAS,EAAE,QAAQ,SAAS,gBAAgB,CAC3D,OAAM;;;;;;;;;;;;;;;;;;AAyBd,SAAgB,oBACd,QAC6D;CAG7D,MAAM,iBAAiD,EAAE;AAEzD,MAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,CAC/C,gBAAe,OAAO,aAAa,KAAK,MAAoB;AAI9D,mBAAkB,eAAe;CAGjC,SAAS,MAAM,KAA2C;EACxD,MAAM,SAAkC,EAAE;AAE1C,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,eAAe,EAAE;GACzD,MAAM,WAAW,IAAI;AAErB,UAAO,OAAO,MAAM,MAAM,SAAS;;AAGrC,SAAO;;CAIT,SAAS,UAAU,QAAmC;EACpD,MAAM,SAAiC,EAAE;AAEzC,OAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,eAAe,EAAE;GACzD,MAAM,aAAa,MAAM,UAAU,OAAO,KAA2B;AACrE,OAAI,eAAe,KACjB,OAAM,IAAI,MACR,qCAAqC,IAAI,uEAE1C;AAEH,UAAO,OAAO;;AAGhB,SAAO;;AAST,QANwC;EACtC;EACA;EACA,QAAQ;EACT"}

package/dist/search-params/define.d.ts

@@ -10,6 +10,12 @@
  * Design doc: design/23-search-params.md §"defineSearchParams — The Factory"
  */
 import type { Codec } from '#/codec.js';
+/**
+ * Register the rawSearchParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export declare function _setRawSearchParamsFn(fn: () => Promise<URLSearchParams>): void;
 /**
  * A codec that converts between URL string values and typed values.
  *

package/dist/search-params/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/search-params/define.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/search-params/define.ts"],"names":[],"mappings":"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"}

package/dist/search-params/index.js

@@ -1,3 +1,4 @@
-import { i as registerSearchParams, r as getSearchParams } from "../_chunks/use-query-states-BvW0TKDn.js";
-import { a as fromSchema, i as fromArraySchema, n as withUrlKey, r as defineSearchParams, t as withDefault } from "../_chunks/wrappers-C6J0nNji.js";
+import { i as registerSearchParams, r as getSearchParams } from "../_chunks/use-query-states-wEXY2JQB.js";
+import { i as fromSchema, n as defineSearchParams, r as fromArraySchema } from "../_chunks/define-TK8C1M3x.js";
+import { n as withUrlKey, t as withDefault } from "../_chunks/wrappers-C9XPg7-U.js";
 export { defineSearchParams, fromArraySchema, fromSchema, getSearchParams, registerSearchParams, withDefault, withUrlKey };

package/dist/server/index.js

@@ -2,10 +2,10 @@ import { n as isDevMode, t as isDebug } from "../_chunks/debug-ECi_61pb.js";
 import { a as warnDenyAfterFlush, c as warnRedirectInAccess, d as warnSlowSlotWithoutSuspense, f as warnStaticRequestApi, i as warnCacheRequestProps, l as warnRedirectInSlotAccess, n as WarningId, o as warnDenyInSuspense, p as warnSuspenseWrappingChildren, r as setViteServer, s as warnDynamicApiInStaticBuild, t as formatSize, u as warnRedirectInSuspense } from "../_chunks/format-cX7wzEp2.js";
 import { i as getMetadataRouteServePath, n as classifyMetadataRoute, r as getMetadataRouteAutoLink, t as METADATA_ROUTE_CONVENTIONS } from "../_chunks/metadata-routes-BU684ls2.js";
 import { a as timingAls, i as revalidationAls, n as formFlashAls, s as waitUntilAls, t as earlyHintsSenderAls } from "../_chunks/als-registry-Ba7URUIn.js";
-import { a as headers, c as rawSegmentParams, d as setMutableCookieContext, f as setSegmentParams, i as getSetCookieHeaders, n as cookies, o as markResponseFlushed, r as getRequestSearchString, s as rawSearchParams, t as applyRequestHeaderOverlay, u as runWithRequestContext } from "../_chunks/request-context-BxYIJM24.js";
-import { r as mergePreservedSearchParams } from "../_chunks/segment-context-C6byCyZU.js";
-import { a as getTraceStore, c as setSpanAttribute, d as withSpan, i as getOtelTraceId, l as spanId, o as replaceTraceId, r as generateTraceId, s as runWithTraceId, t as addSpanEvent, u as traceId } from "../_chunks/tracing-CuXiCP5p.js";
-import "../_chunks/error-boundary-BAN3751q.js";
+import { a as headers, c as rawSegmentParams, d as setMutableCookieContext, f as setSegmentParams, i as getSetCookieHeaders, n as cookies, o as markResponseFlushed, r as getRequestSearchString, s as rawSearchParams, t as applyRequestHeaderOverlay, u as runWithRequestContext } from "../_chunks/request-context-0h-6Voad.js";
+import { r as mergePreservedSearchParams } from "../_chunks/segment-context-DBn-nrMN.js";
+import { a as getTraceStore, c as setSpanAttribute, d as withSpan, i as getOtelTraceId, l as spanId, o as replaceTraceId, r as generateTraceId, s as runWithTraceId, t as addSpanEvent, u as traceId } from "../_chunks/tracing-JI4cYUdz.js";
+import "../_chunks/error-boundary-B9vT_YK_.js";
 import { readFile } from "node:fs/promises";
 import "react";
 //#region src/server/waituntil-bridge.ts

package/dist/server/request-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.41",
+  "version": "0.2.0-alpha.42",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/search-params/define.ts

@@ -14,17 +14,31 @@ import { useQueryStates as clientUseQueryStates } from '#/client/use-query-state
 import { fromSchema } from './codecs.js';
 import type { Codec } from '#/codec.js';
 
-// Lazy import for .load() — avoids pulling server ALS into client bundles.
-// The import is resolved at call time, not at module load time.
-// In client environments, .load() throws before reaching the import.
+// Server-only reference for .load() — avoids pulling server ALS into client bundles.
+// In client environments, .load() throws before reaching this code path.
+//
+// IMPORTANT: This is set eagerly via _setRawSearchParamsFn() 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 rawSearchParams() in parallel slot pages. See TIM-523.
 let _rawSearchParams: (() => Promise<URLSearchParams>) | undefined;
-async function getRawSearchParams(): Promise<URLSearchParams> {
+
+/**
+ * Register the rawSearchParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export function _setRawSearchParamsFn(fn: () => Promise<URLSearchParams>): void {
+  _rawSearchParams = fn;
+}
+
+function getRawSearchParams(): Promise<URLSearchParams> {
   if (!_rawSearchParams) {
-    // Dynamic import to avoid circular dependency and client bundle pollution.
-    // request-context.ts is server-only; this path is never reached on the client
-    // because load() throws first (see below).
-    const mod = await import('#/server/request-context.js');
-    _rawSearchParams = mod.rawSearchParams;
+    throw new Error(
+      '[timber] searchParams.load() is only available on the server. ' +
+        'Use searchParams.useQueryStates() on the client.'
+    );
   }
   return _rawSearchParams();
 }

package/src/server/request-context.ts

@@ -12,6 +12,7 @@
 
 import { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';
 import { isDebug } from './debug.js';
+import { _setRawSearchParamsFn } from '#/search-params/define.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
@@ -178,6 +179,12 @@ export function rawSearchParams(): Promise<URLSearchParams> {
   return store.searchParamsPromise;
 }
 
+// Eagerly register rawSearchParams with the search-params module so
+// searchParams.load() can call it synchronously without a dynamic import.
+// Dynamic imports lose ALS context in React's RSC Flight renderer,
+// breaking rawSearchParams() in parallel slot pages. See TIM-523.
+_setRawSearchParamsFn(rawSearchParams);
+
 /**
  * Returns a Promise resolving to the current request's coerced segment params.
  *

package/dist/_chunks/request-context-BxYIJM24.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"request-context-BxYIJM24.js","names":[],"sources":["../../src/server/request-context.ts"],"sourcesContent":["/**\n * Request Context — per-request ALS store for headers() and cookies().\n *\n * Follows the same pattern as tracing.ts: a module-level AsyncLocalStorage\n * instance, public accessor functions that throw outside request scope,\n * and a framework-internal `runWithRequestContext()` to establish scope.\n *\n * See design/04-authorization.md §\"AccessContext does not include cookies or headers\"\n * and design/11-platform.md §\"AsyncLocalStorage\".\n * See design/29-cookies.md for cookie mutation semantics.\n */\n\nimport { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';\nimport { isDebug } from './debug.js';\n\n// Re-export the ALS for framework-internal consumers that need direct access.\nexport { requestContextAls };\n\n// No fallback needed — we use enterWith() instead of run() to ensure\n// the ALS context persists for the entire request lifecycle including\n// async stream consumption by React's renderToReadableStream.\n\n// ─── Public API ───────────────────────────────────────────────────────────\n\n/**\n * Returns a read-only view of the current request's headers.\n *\n * Available in middleware, access checks, server components, and server actions.\n * Throws if called outside a request context (security principle #2: no global fallback).\n */\nexport function headers(): ReadonlyHeaders {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] headers() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return store.headers;\n}\n\n/**\n * Returns a cookie accessor for the current request.\n *\n * Available in middleware, access checks, server components, and server actions.\n * Throws if called outside a request context (security principle #2: no global fallback).\n *\n * Read methods (.get, .has, .getAll) are always available and reflect\n * read-your-own-writes from .set() calls in the same request.\n *\n * Mutation methods (.set, .delete, .clear) are only available in mutable\n * contexts (middleware.ts, server actions, route.ts handlers). Calling them\n * in read-only contexts (access.ts, server components) throws.\n *\n * See design/29-cookies.md\n */\nexport function cookies(): RequestCookies {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] cookies() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n\n  // Parse cookies lazily on first access\n  if (!store.parsedCookies) {\n    store.parsedCookies = parseCookieHeader(store.cookieHeader);\n  }\n\n  const map = store.parsedCookies;\n  return {\n    get(name: string): string | undefined {\n      return map.get(name);\n    },\n    has(name: string): boolean {\n      return map.has(name);\n    },\n    getAll(): Array<{ name: string; value: string }> {\n      return Array.from(map.entries()).map(([name, value]) => ({ name, value }));\n    },\n    get size(): number {\n      return map.size;\n    },\n\n    set(name: string, value: string, options?: CookieOptions): void {\n      assertMutable(store, 'set');\n      if (store.flushed) {\n        if (isDebug()) {\n          console.warn(\n            `[timber] warn: cookies().set('${name}') called after response headers were committed.\\n` +\n              `  The cookie will NOT be sent. Move cookie mutations to middleware.ts, a server action,\\n` +\n              `  or a route.ts handler.`\n          );\n        }\n        return;\n      }\n      const opts = { ...DEFAULT_COOKIE_OPTIONS, ...options };\n      store.cookieJar.set(name, { name, value, options: opts });\n      // Read-your-own-writes: update the parsed cookies map\n      map.set(name, value);\n    },\n\n    delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {\n      assertMutable(store, 'delete');\n      if (store.flushed) {\n        if (isDebug()) {\n          console.warn(\n            `[timber] warn: cookies().delete('${name}') called after response headers were committed.\\n` +\n              `  The cookie will NOT be deleted. Move cookie mutations to middleware.ts, a server action,\\n` +\n              `  or a route.ts handler.`\n          );\n        }\n        return;\n      }\n      const opts: CookieOptions = {\n        ...DEFAULT_COOKIE_OPTIONS,\n        ...options,\n        maxAge: 0,\n        expires: new Date(0),\n      };\n      store.cookieJar.set(name, { name, value: '', options: opts });\n      // Remove from read view\n      map.delete(name);\n    },\n\n    clear(): void {\n      assertMutable(store, 'clear');\n      if (store.flushed) return;\n      // Delete every incoming cookie\n      for (const name of Array.from(map.keys())) {\n        store.cookieJar.set(name, {\n          name,\n          value: '',\n          options: { ...DEFAULT_COOKIE_OPTIONS, maxAge: 0, expires: new Date(0) },\n        });\n      }\n      map.clear();\n    },\n\n    toString(): string {\n      return Array.from(map.entries())\n        .map(([name, value]) => `${name}=${value}`)\n        .join('; ');\n    },\n  };\n}\n\n/**\n * Returns a Promise resolving to the current request's raw URLSearchParams.\n *\n * For typed, parsed search params, import the definition from params.ts\n * and call `.load()` or `.parse()`:\n *\n * ```ts\n * import { searchParams } from './params'\n * const parsed = await searchParams.load()\n * ```\n *\n * Or explicitly:\n *\n * ```ts\n * import { rawSearchParams } from '@timber-js/app/server'\n * import { searchParams } from './params'\n * const parsed = searchParams.parse(await rawSearchParams())\n * ```\n *\n * Throws if called outside a request context.\n */\nexport function rawSearchParams(): Promise<URLSearchParams> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] rawSearchParams() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  return store.searchParamsPromise;\n}\n\n/**\n * Returns a Promise resolving to the current request's coerced segment params.\n *\n * Segment params are set by the pipeline after route matching and param\n * coercion (via params.ts codecs). When no params.ts exists, values are\n * raw strings. When codecs are defined, values are already coerced\n * (e.g., `id` is a `number` if `defineSegmentParams({ id: z.coerce.number() })`).\n *\n * This is the primary way page and layout components access route params:\n *\n * ```ts\n * import { rawSegmentParams } from '@timber-js/app/server'\n *\n * export default async function Page() {\n *   const { slug } = await rawSegmentParams()\n *   // ...\n * }\n * ```\n *\n * Throws if called outside a request context.\n */\nexport function rawSegmentParams(): Promise<Record<string, string | string[]>> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error(\n      '[timber] rawSegmentParams() called outside of a request context. ' +\n        'It can only be used in middleware, access checks, server components, and server actions.'\n    );\n  }\n  if (!store.segmentParamsPromise) {\n    throw new Error(\n      '[timber] rawSegmentParams() called before route matching completed. ' +\n        'Segment params are not available until after the route is matched.'\n    );\n  }\n  return store.segmentParamsPromise;\n}\n\n/**\n * Set the segment params promise on the current request context.\n * Called by the pipeline after route matching and param coercion.\n *\n * @internal — framework use only\n */\nexport function setSegmentParams(params: Record<string, string | string[]>): void {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] setSegmentParams() called outside of a request context.');\n  }\n  store.segmentParamsPromise = Promise.resolve(params);\n}\n\n/**\n * Returns the raw search string from the current request URL (e.g. \"?foo=bar\").\n * Synchronous — safe for use in `redirect()` which throws synchronously.\n *\n * Returns empty string if called outside a request context (non-throwing for\n * use in redirect's optional preserveSearchParams path).\n *\n * @internal — used by redirect() for preserveSearchParams support.\n */\nexport function getRequestSearchString(): string {\n  const store = requestContextAls.getStore();\n  return store?.searchString ?? '';\n}\n\n// ─── Types ────────────────────────────────────────────────────────────────\n\n/**\n * Read-only Headers interface. The standard Headers class is mutable;\n * this type narrows it to read-only methods. The underlying object is\n * still a Headers instance, but user code should not mutate it.\n */\nexport type ReadonlyHeaders = Pick<\n  Headers,\n  'get' | 'has' | 'entries' | 'keys' | 'values' | 'forEach' | typeof Symbol.iterator\n>;\n\n/** Options for setting a cookie. See design/29-cookies.md. */\nexport interface CookieOptions {\n  /** Domain scope. Default: omitted (current domain only). */\n  domain?: string;\n  /** URL path scope. Default: '/'. */\n  path?: string;\n  /** Expiration date. Mutually exclusive with maxAge. */\n  expires?: Date;\n  /** Max age in seconds. Mutually exclusive with expires. */\n  maxAge?: number;\n  /** Prevent client-side JS access. Default: true. */\n  httpOnly?: boolean;\n  /** Only send over HTTPS. Default: true. */\n  secure?: boolean;\n  /** Cross-site request policy. Default: 'lax'. */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** Partitioned (CHIPS) — isolate cookie per top-level site. Default: false. */\n  partitioned?: boolean;\n}\n\nconst DEFAULT_COOKIE_OPTIONS: CookieOptions = {\n  path: '/',\n  httpOnly: true,\n  secure: true,\n  sameSite: 'lax',\n};\n\n/**\n * Cookie accessor returned by `cookies()`.\n *\n * Read methods are always available. Mutation methods throw in read-only\n * contexts (access.ts, server components).\n */\nexport interface RequestCookies {\n  /** Get a cookie value by name. Returns undefined if not present. */\n  get(name: string): string | undefined;\n  /** Check if a cookie exists. */\n  has(name: string): boolean;\n  /** Get all cookies as an array of { name, value } pairs. */\n  getAll(): Array<{ name: string; value: string }>;\n  /** Number of cookies. */\n  readonly size: number;\n  /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */\n  set(name: string, value: string, options?: CookieOptions): void;\n  /** Delete a cookie. Only available in mutable contexts. */\n  delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;\n  /** Delete all cookies. Only available in mutable contexts. */\n  clear(): void;\n  /** Serialize cookies as a Cookie header string. */\n  toString(): string;\n}\n\n// ─── Framework-Internal Helpers ───────────────────────────────────────────\n\n/**\n * Run a callback within a request context. Used by the pipeline to establish\n * per-request ALS scope so that `headers()` and `cookies()` work.\n *\n * @param req - The incoming Request object.\n * @param fn - The function to run within the request context.\n */\nexport function runWithRequestContext<T>(req: Request, fn: () => T): T {\n  const originalCopy = new Headers(req.headers);\n  const parsedUrl = new URL(req.url);\n  const store: RequestContextStore = {\n    headers: freezeHeaders(req.headers),\n    originalHeaders: originalCopy,\n    cookieHeader: req.headers.get('cookie') ?? '',\n    searchParamsPromise: Promise.resolve(parsedUrl.searchParams),\n    searchString: parsedUrl.search,\n    cookieJar: new Map(),\n    flushed: false,\n    mutableContext: false,\n  };\n  return requestContextAls.run(store, fn);\n}\n\n/**\n * Enable cookie mutation for the current context. Called by the framework\n * when entering middleware.ts, server actions, or route.ts handlers.\n *\n * See design/29-cookies.md §\"Context Tracking\"\n */\nexport function setMutableCookieContext(mutable: boolean): void {\n  const store = requestContextAls.getStore();\n  if (store) {\n    store.mutableContext = mutable;\n  }\n}\n\n/**\n * Mark the response as flushed (headers committed). After this point,\n * cookie mutations log a warning instead of throwing.\n *\n * See design/29-cookies.md §\"Streaming Constraint: Post-Flush Cookie Warning\"\n */\nexport function markResponseFlushed(): void {\n  const store = requestContextAls.getStore();\n  if (store) {\n    store.flushed = true;\n  }\n}\n\n/**\n * Build a Map of cookie name → value reflecting the current request's\n * read-your-own-writes state. Includes incoming cookies plus any\n * mutations from cookies().set() / cookies().delete() in the same request.\n *\n * Used by SSR renderers to populate NavContext.cookies so that\n * useCookie()'s server snapshot matches the actual response state.\n *\n * See design/29-cookies.md §\"Read-Your-Own-Writes\"\n * See design/triage/TIM-441-cookie-api-triage.md §4\n */\nexport function getCookiesForSsr(): Map<string, string> {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] getCookiesForSsr() called outside of a request context.');\n  }\n\n  // Trigger lazy parsing if not yet done\n  if (!store.parsedCookies) {\n    store.parsedCookies = parseCookieHeader(store.cookieHeader);\n  }\n\n  // The parsedCookies map already reflects read-your-own-writes:\n  // - cookies().set() updates the map via map.set(name, value)\n  // - cookies().delete() removes from the map via map.delete(name)\n  // Return a copy so callers can't mutate the internal map.\n  return new Map(store.parsedCookies);\n}\n\n/**\n * Collect all Set-Cookie headers from the cookie jar.\n * Called by the framework at flush time to apply cookies to the response.\n *\n * Returns an array of serialized Set-Cookie header values.\n */\nexport function getSetCookieHeaders(): string[] {\n  const store = requestContextAls.getStore();\n  if (!store) return [];\n  return Array.from(store.cookieJar.values()).map(serializeCookieEntry);\n}\n\n/**\n * Apply middleware-injected request headers to the current request context.\n *\n * Called by the pipeline after middleware.ts runs. Merges overlay headers\n * on top of the original request headers so downstream code (access.ts,\n * server components, server actions) sees them via `headers()`.\n *\n * The original request headers are never mutated — a new frozen Headers\n * object is created with the overlay applied on top.\n *\n * See design/07-routing.md §\"Request Header Injection\"\n */\nexport function applyRequestHeaderOverlay(overlay: Headers): void {\n  const store = requestContextAls.getStore();\n  if (!store) {\n    throw new Error('[timber] applyRequestHeaderOverlay() called outside of a request context.');\n  }\n\n  // Check if the overlay has any headers — skip if empty\n  let hasOverlay = false;\n  overlay.forEach(() => {\n    hasOverlay = true;\n  });\n  if (!hasOverlay) return;\n\n  // Merge: start with original headers, overlay on top\n  const merged = new Headers(store.originalHeaders);\n  overlay.forEach((value, key) => {\n    merged.set(key, value);\n  });\n  store.headers = freezeHeaders(merged);\n}\n\n// ─── Read-Only Headers ────────────────────────────────────────────────────\n\nconst MUTATING_METHODS = new Set(['set', 'append', 'delete']);\n\n/**\n * Wrap a Headers object in a Proxy that throws on mutating methods.\n * Object.freeze doesn't work on Headers (native internal slots), so we\n * intercept property access and reject set/append/delete at runtime.\n *\n * Read methods (get, has, entries, etc.) must be bound to the underlying\n * Headers instance because they access private #headersList slots.\n */\nfunction freezeHeaders(source: Headers): Headers {\n  const copy = new Headers(source);\n  return new Proxy(copy, {\n    get(target, prop) {\n      if (typeof prop === 'string' && MUTATING_METHODS.has(prop)) {\n        return () => {\n          throw new Error(\n            `[timber] headers() returns a read-only Headers object. ` +\n              `Calling .${prop}() is not allowed. ` +\n              `Use ctx.requestHeaders in middleware to inject headers for downstream components.`\n          );\n        };\n      }\n      const value = Reflect.get(target, prop);\n      // Bind methods to the real Headers instance so private slot access works\n      if (typeof value === 'function') {\n        return value.bind(target);\n      }\n      return value;\n    },\n  });\n}\n\n// ─── Cookie Helpers ───────────────────────────────────────────────────────\n\n/** Throw if cookie mutation is attempted in a read-only context. */\nfunction assertMutable(store: RequestContextStore, method: string): void {\n  if (!store.mutableContext) {\n    throw new Error(\n      `[timber] cookies().${method}() cannot be called in this context.\\n` +\n        `  Set cookies in middleware.ts, server actions, or route.ts handlers.`\n    );\n  }\n}\n\n/**\n * Parse a Cookie header string into a Map of name → value pairs.\n * Follows RFC 6265 §4.2.1: cookies are semicolon-separated key=value pairs.\n */\nfunction parseCookieHeader(header: string): Map<string, string> {\n  const map = new Map<string, string>();\n  if (!header) return map;\n\n  for (const pair of header.split(';')) {\n    const eqIndex = pair.indexOf('=');\n    if (eqIndex === -1) continue;\n    const name = pair.slice(0, eqIndex).trim();\n    const value = pair.slice(eqIndex + 1).trim();\n    if (name) {\n      map.set(name, value);\n    }\n  }\n\n  return map;\n}\n\n/** Serialize a CookieEntry into a Set-Cookie header value. */\nfunction serializeCookieEntry(entry: CookieEntry): string {\n  const parts = [`${entry.name}=${entry.value}`];\n  const opts = entry.options;\n\n  if (opts.domain) parts.push(`Domain=${opts.domain}`);\n  if (opts.path) parts.push(`Path=${opts.path}`);\n  if (opts.expires) parts.push(`Expires=${opts.expires.toUTCString()}`);\n  if (opts.maxAge !== undefined) parts.push(`Max-Age=${opts.maxAge}`);\n  if (opts.httpOnly) parts.push('HttpOnly');\n  if (opts.secure) parts.push('Secure');\n  if (opts.sameSite) {\n    parts.push(`SameSite=${opts.sameSite.charAt(0).toUpperCase()}${opts.sameSite.slice(1)}`);\n  }\n  if (opts.partitioned) parts.push('Partitioned');\n\n  return parts.join('; ');\n}\n"],"mappings":"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"}

package/dist/_chunks/wrappers-C6J0nNji.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"wrappers-C6J0nNji.js","names":[],"sources":["../../src/search-params/codecs.ts","../../src/search-params/define.ts","../../src/search-params/wrappers.ts"],"sourcesContent":["/**\n * Built-in codecs and the fromSchema bridge for Standard Schema-compatible\n * validation libraries (Zod, Valibot, ArkType).\n *\n * Design doc: design/09-typescript.md §\"The SearchParamCodec Protocol\"\n */\n\nimport type { SearchParamCodec } from './define.js';\n\n// ---------------------------------------------------------------------------\n// Standard Schema interface (subset)\n//\n// Standard Schema (https://github.com/standard-schema/standard-schema) defines\n// a minimal interface that Zod ≥3.24, Valibot ≥1.0, and ArkType all implement.\n// We depend only on `~standard.validate` to avoid coupling to any specific lib.\n// ---------------------------------------------------------------------------\n\ninterface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;\n  };\n}\n\ntype StandardSchemaResult<Output> =\n  | { value: Output; issues?: undefined }\n  | { value?: undefined; issues: ReadonlyArray<{ message: string }> };\n\n// ---------------------------------------------------------------------------\n// Sync validate helper\n// ---------------------------------------------------------------------------\n\n/**\n * Zod v4's ~standard.validate() signature includes Promise in the return union\n * to satisfy the Standard Schema spec, but in practice Zod always validates\n * synchronously for the schema types we use. We assert the result is sync and\n * throw if it isn't — search params parsing must be synchronous.\n */\nfunction validateSync<Output>(\n  schema: StandardSchemaV1<Output>,\n  value: unknown\n): StandardSchemaResult<Output> {\n  const result = schema['~standard'].validate(value);\n  if (result instanceof Promise) {\n    throw new Error(\n      '[timber] fromSchema: schema returned a Promise — only sync schemas are supported for search params.'\n    );\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// fromSchema — bridge from Standard Schema to SearchParamCodec\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a\n * SearchParamCodec.\n *\n * Parse: coerces the raw URL string through the schema. On validation failure,\n * parses `undefined` to get the schema's default value (the schema should have\n * a `.default()` call). If that also fails, returns `undefined`.\n *\n * Serialize: uses `String()` for primitives, `null` for null/undefined.\n *\n * ```ts\n * import { fromSchema } from '@timber-js/app/search-params'\n * import { z } from 'zod/v4'\n *\n * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))\n * ```\n */\nexport function fromSchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // For array inputs, take the last value (consistent with URLSearchParams.get())\n      const input = Array.isArray(value) ? value[value.length - 1] : value;\n\n      // Try parsing the raw value\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try parsing undefined to get the default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      // No default available — return undefined (codec design choice)\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      return String(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// fromArraySchema — bridge for array-valued search params\n// ---------------------------------------------------------------------------\n\n/**\n * Bridge a Standard Schema for array values. Handles both single strings\n * and repeated query keys (`?tag=a&tag=b`).\n *\n * ```ts\n * import { fromArraySchema } from '@timber-js/app/search-params'\n * import { z } from 'zod/v4'\n *\n * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))\n * ```\n */\nexport function fromArraySchema<T>(schema: StandardSchemaV1<T>): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      // Coerce single string to array for array schemas\n      let input: unknown = value;\n      if (typeof value === 'string') {\n        input = [value];\n      } else if (value === undefined) {\n        input = undefined;\n      }\n\n      const result = validateSync(schema, input);\n      if (!result.issues) {\n        return result.value;\n      }\n\n      // On failure, try undefined for default\n      const defaultResult = validateSync(schema, undefined);\n      if (!defaultResult.issues) {\n        return defaultResult.value;\n      }\n\n      return undefined as T;\n    },\n\n    serialize(value: T): string | null {\n      if (value === null || value === undefined) {\n        return null;\n      }\n      if (Array.isArray(value)) {\n        return value.length === 0 ? null : value.join(',');\n      }\n      return String(value);\n    },\n  };\n}\n","/**\n * defineSearchParams — factory for SearchParamsDefinition<T>.\n *\n * Creates a typed, composable definition for a route's search parameters.\n * Accepts both SearchParamCodec values and Standard Schema objects (Zod,\n * Valibot, ArkType) with auto-detection. Supports URL key aliasing via\n * withUrlKey(), default-omission serialization, and composition via\n * .extend() / .pick().\n *\n * Design doc: design/23-search-params.md §\"defineSearchParams — The Factory\"\n */\n\nimport { useQueryStates as clientUseQueryStates } from '#/client/use-query-states.js';\nimport { fromSchema } from './codecs.js';\nimport type { Codec } from '#/codec.js';\n\n// Lazy import for .load() — avoids pulling server ALS into client bundles.\n// The import is resolved at call time, not at module load time.\n// In client environments, .load() throws before reaching the import.\nlet _rawSearchParams: (() => Promise<URLSearchParams>) | undefined;\nasync function getRawSearchParams(): Promise<URLSearchParams> {\n  if (!_rawSearchParams) {\n    // Dynamic import to avoid circular dependency and client bundle pollution.\n    // request-context.ts is server-only; this path is never reached on the client\n    // because load() throws first (see below).\n    const mod = await import('#/server/request-context.js');\n    _rawSearchParams = mod.rawSearchParams;\n  }\n  return _rawSearchParams();\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A codec that converts between URL string values and typed values.\n *\n * nuqs parsers implement this interface natively — no adapter needed.\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected\n * by defineSearchParams and wrapped via fromSchema.\n */\nexport interface SearchParamCodec<T> extends Codec<T> {\n  /** Optional URL key alias, set by withUrlKey(). */\n  urlKey?: string;\n}\n\n/** A codec with a URL key alias attached via withUrlKey(). */\nexport interface SearchParamCodecWithUrlKey<T> extends SearchParamCodec<T> {\n  urlKey: string;\n}\n\n/** Infer the output type of a codec. */\nexport type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;\n\n/** Map of property names to codecs. */\nexport type CodecMap<T extends Record<string, unknown>> = {\n  [K in keyof T]: SearchParamCodec<T[K]>;\n};\n\n/** Options for useQueryStates setter. */\nexport interface SetParamsOptions {\n  /** Update URL without server roundtrip (default: false). */\n  shallow?: boolean;\n  /** Scroll to top after update (default: true). */\n  scroll?: boolean;\n  /** 'push' (default) or 'replace' for history state. */\n  history?: 'push' | 'replace';\n}\n\n/** Setter function returned by useQueryStates. */\nexport type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;\n\n/** Options for useQueryStates hook. */\nexport interface QueryStatesOptions {\n  /** Update URL without server roundtrip (default: false). */\n  shallow?: boolean;\n  /** Scroll to top after update (default: true). */\n  scroll?: boolean;\n  /** 'push' (default) or 'replace' for history state. */\n  history?: 'push' | 'replace';\n}\n\n/**\n * A fully typed, composable search params definition.\n *\n * Returned by defineSearchParams(). Carries a phantom _type property\n * for build-time type extraction.\n */\nexport interface SearchParamsDefinition<T extends Record<string, unknown>> {\n  /** Parse raw URL search params into typed values. */\n  parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n  /** Parse a Promise of URLSearchParams (e.g., from the ALS `searchParams()` API). */\n  parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;\n\n  /**\n   * Load typed search params from the current request context (ALS-backed).\n   *\n   * Server-only — reads rawSearchParams() from ALS and parses through codecs.\n   * Throws on client. Eliminates the naming conflict between the definition\n   * export and the server helper.\n   *\n   * ```tsx\n   * // app/products/page.tsx\n   * import { searchParams } from './params'\n   * export default async function Page() {\n   *   const { page, category } = await searchParams.load()\n   * }\n   * ```\n   */\n  load(): Promise<T>;\n\n  /** Client hook — reads current URL params and returns typed values + setter. */\n  useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];\n\n  /** Extend with additional codecs or Standard Schema objects. */\n  extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(\n    codecs: U\n  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }>;\n\n  /** Pick a subset of keys. Preserves codecs and aliases. */\n  pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;\n\n  /** Serialize values to a query string (no leading '?'), omitting defaults. */\n  serialize(values: Partial<T>): string;\n\n  /** Build a full path with query string, omitting defaults. */\n  href(pathname: string, values: Partial<T>): string;\n\n  /** Build a URLSearchParams instance, omitting defaults. */\n  toSearchParams(values: Partial<T>): URLSearchParams;\n\n  /** Read-only codec map for spreading into .extend(). */\n  codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n\n  /** Read-only URL key alias map. Maps property names to URL query parameter keys. */\n  readonly urlKeys: Readonly<Record<string, string>>;\n\n  /**\n   * Phantom property for build-time type extraction.\n   * Never set at runtime — exists only in the type system.\n   */\n  readonly _type?: T;\n}\n\n// ---------------------------------------------------------------------------\n// Standard Schema interface (subset)\n//\n// Standard Schema (https://github.com/standard-schema/standard-schema) defines\n// a minimal interface that Zod ≥3.24, Valibot ≥1.0, and ArkType all implement.\n// We check for the '~standard' property to auto-detect schemas.\n// ---------------------------------------------------------------------------\n\n/** Minimal Standard Schema interface for auto-detection. */\nexport interface StandardSchemaV1<Output = unknown> {\n  '~standard': {\n    validate(\n      value: unknown\n    ):\n      | { value: Output; issues?: undefined }\n      | { value?: undefined; issues: ReadonlyArray<{ message: string }> }\n      | Promise<\n          | { value: Output; issues?: undefined }\n          | { value?: undefined; issues: ReadonlyArray<{ message: string }> }\n        >;\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Type-level helpers\n// ---------------------------------------------------------------------------\n\n/** Infer the output type from either a SearchParamCodec or a StandardSchemaV1. */\nexport type InferField<V> =\n  V extends SearchParamCodec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;\n\n/** Acceptable field value for defineSearchParams: a codec or a Standard Schema. */\nexport type SearchParamField<T = unknown> = SearchParamCodec<T> | StandardSchemaV1<T>;\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Convert URLSearchParams or a plain record to a normalized record\n * where repeated keys produce arrays.\n */\nfunction normalizeRaw(\n  raw: URLSearchParams | Record<string, string | string[] | undefined>\n): Record<string, string | string[] | undefined> {\n  if (raw instanceof URLSearchParams) {\n    const result: Record<string, string | string[] | undefined> = {};\n    for (const key of new Set(raw.keys())) {\n      const values = raw.getAll(key);\n      result[key] = values.length === 1 ? values[0] : values;\n    }\n    return result;\n  }\n  return raw;\n}\n\n/**\n * Compute the serialized default value for a codec. Used for\n * default-omission: when serialize(value) === serialize(parse(undefined)),\n * the field is omitted from the URL.\n */\nfunction getDefaultSerialized<T>(codec: SearchParamCodec<T>): string | null {\n  return codec.serialize(codec.parse(undefined));\n}\n\n/** Check if a value is a Standard Schema object. */\nfunction isStandardSchema(value: unknown): value is StandardSchemaV1 {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    '~standard' in value &&\n    typeof (value as StandardSchemaV1)['~standard']?.validate === 'function'\n  );\n}\n\n/** Check if a value is a SearchParamCodec. */\nfunction isCodec(value: unknown): value is SearchParamCodec<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as SearchParamCodec<unknown>).parse === 'function' &&\n    typeof (value as SearchParamCodec<unknown>).serialize === 'function'\n  );\n}\n\n/**\n * Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema\n * objects and wraps them with fromSchema. Reads .urlKey from codecs.\n */\nfunction resolveField(\n  fieldName: string,\n  value: SearchParamField\n): { codec: SearchParamCodec<unknown>; urlKey?: string } {\n  // Check for codec first (codecs may also have '~standard' if they're nuqs parsers)\n  if (isCodec(value)) {\n    return { codec: value, urlKey: value.urlKey };\n  }\n\n  // Auto-detect Standard Schema\n  if (isStandardSchema(value)) {\n    return { codec: fromSchema(value) };\n  }\n\n  throw new Error(\n    `[timber] defineSearchParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n      `(Zod, Valibot, ArkType).`\n  );\n}\n\n/**\n * Validate that all codecs handle absent params (parse(undefined) doesn't throw).\n * Catches schemas that throw on missing input. `undefined` and `null` are both\n * valid defaults — `undefined` is correct for optional fields (e.g., `z.string().optional()`).\n */\nfunction validateDefaults(codecMap: Record<string, SearchParamCodec<unknown>>): void {\n  for (const [key, codec] of Object.entries(codecMap)) {\n    try {\n      codec.parse(undefined);\n    } catch {\n      throw new Error(\n        `[timber] defineSearchParams: field '${key}' throws when the param is absent.\\n` +\n          `  Search params are optional — the URL might not contain ?${key}=anything.\\n` +\n          `  Add .default() or .optional() to your schema, or wrap with withDefault().`\n      );\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a SearchParamsDefinition from a map of codecs and/or Standard Schema\n * objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType\n * schemas with auto-detection.\n *\n * ```ts\n * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'\n * import { parseAsString, parseAsStringEnum } from 'nuqs'\n * import { z } from 'zod/v4'\n *\n * export const searchParams = defineSearchParams({\n *   page: z.coerce.number().int().min(1).default(1),     // Standard Schema — auto-wrapped\n *   q: withUrlKey(parseAsString, 'search'),                // nuqs codec with URL alias\n *   sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),\n * })\n * ```\n */\nexport function defineSearchParams<C extends Record<string, SearchParamField>>(\n  codecs: C\n): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }> {\n  type T = { [K in keyof C]: InferField<C[K]> };\n\n  const resolvedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n  const urlKeys: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(codecs)) {\n    const resolved = resolveField(key, value as SearchParamField);\n    resolvedCodecs[key] = resolved.codec;\n    if (resolved.urlKey) {\n      urlKeys[key] = resolved.urlKey;\n    }\n  }\n\n  // Validate that all codecs handle absent params\n  validateDefaults(resolvedCodecs);\n\n  return buildDefinition<T>(resolvedCodecs as unknown as CodecMap<T>, urlKeys);\n}\n\n// ---------------------------------------------------------------------------\n// Internal: build the definition object\n// ---------------------------------------------------------------------------\n\n/**\n * Internal: build a SearchParamsDefinition from a typed codec map and url keys.\n */\nfunction buildDefinition<T extends Record<string, unknown>>(\n  codecMap: CodecMap<T>,\n  urlKeys: Record<string, string>\n): SearchParamsDefinition<T> {\n  // Pre-compute default serialized values for omission check\n  const defaultSerialized: Record<string, string | null> = {};\n  for (const key of Object.keys(codecMap)) {\n    defaultSerialized[key] = getDefaultSerialized(codecMap[key as keyof T]);\n  }\n\n  function getUrlKey(prop: string): string {\n    return urlKeys[prop] ?? prop;\n  }\n\n  // ---- parse ----\n  function parseSync(raw: URLSearchParams | Record<string, string | string[] | undefined>): T {\n    const normalized = normalizeRaw(raw);\n    const result: Record<string, unknown> = {};\n\n    for (const prop of Object.keys(codecMap)) {\n      const urlKey = getUrlKey(prop);\n      const rawValue = normalized[urlKey];\n      result[prop] = (codecMap[prop as keyof T] as SearchParamCodec<unknown>).parse(rawValue);\n    }\n\n    return result as T;\n  }\n\n  // Overloaded parse: sync when given raw params, async when given a Promise.\n  // This enables the ergonomic pattern: await def.parse(searchParams())\n  function parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n  function parse(\n    raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n  ): Promise<T>;\n  function parse(\n    raw:\n      | URLSearchParams\n      | Record<string, string | string[] | undefined>\n      | Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n  ): T | Promise<T> {\n    if (raw instanceof Promise) {\n      return raw.then(parseSync);\n    }\n    return parseSync(raw);\n  }\n\n  // ---- serialize ----\n  function serialize(values: Partial<T>): string {\n    const parts: string[] = [];\n\n    for (const prop of Object.keys(codecMap)) {\n      if (!(prop in values)) continue;\n      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n      const serialized = codec.serialize(values[prop as keyof T] as unknown);\n\n      // Omit if serialized value matches the default\n      if (serialized === defaultSerialized[prop]) continue;\n      if (serialized === null) continue;\n\n      parts.push(`${encodeURIComponent(getUrlKey(prop))}=${encodeURIComponent(serialized)}`);\n    }\n\n    return parts.join('&');\n  }\n\n  // ---- href ----\n  function href(pathname: string, values: Partial<T>): string {\n    const qs = serialize(values);\n    return qs ? `${pathname}?${qs}` : pathname;\n  }\n\n  // ---- toSearchParams ----\n  function toSearchParams(values: Partial<T>): URLSearchParams {\n    const usp = new URLSearchParams();\n\n    for (const prop of Object.keys(codecMap)) {\n      if (!(prop in values)) continue;\n      const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n      const serialized = codec.serialize(values[prop as keyof T] as unknown);\n\n      if (serialized === defaultSerialized[prop]) continue;\n      if (serialized === null) continue;\n\n      usp.set(getUrlKey(prop), serialized);\n    }\n\n    return usp;\n  }\n\n  // ---- extend ----\n  function extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(\n    newCodecs: U\n  ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }> {\n    type Combined = T & { [K in keyof U]: InferField<U[K]> };\n\n    // Resolve any Standard Schema objects in the extension\n    const resolvedNewCodecs: Record<string, SearchParamCodec<unknown>> = {};\n    const newUrlKeys: Record<string, string> = {};\n    for (const [key, value] of Object.entries(newCodecs)) {\n      const resolved = resolveField(key, value as SearchParamField);\n      resolvedNewCodecs[key] = resolved.codec;\n      if (resolved.urlKey) {\n        newUrlKeys[key] = resolved.urlKey;\n      }\n    }\n\n    const combinedCodecs = {\n      ...codecMap,\n      ...resolvedNewCodecs,\n    } as unknown as CodecMap<Combined>;\n\n    // Merge URL keys: base keys + new codec urlKeys from withUrlKey\n    const combinedUrlKeys: Record<string, string> = { ...urlKeys, ...newUrlKeys };\n\n    return buildDefinition<Combined>(combinedCodecs, combinedUrlKeys);\n  }\n\n  // ---- pick ----\n  function pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>> {\n    const pickedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n    const pickedUrlKeys: Record<string, string> = {};\n\n    for (const key of keys) {\n      pickedCodecs[key] = codecMap[key] as SearchParamCodec<unknown>;\n      if (key in urlKeys) {\n        pickedUrlKeys[key] = urlKeys[key];\n      }\n    }\n\n    return buildDefinition<Pick<T, K>>(\n      pickedCodecs as unknown as CodecMap<Pick<T, K>>,\n      pickedUrlKeys\n    );\n  }\n\n  // ---- useQueryStates ----\n  // Delegates to the 'use client' implementation from use-query-states.ts.\n  //\n  // In the RSC environment: use-query-states.ts is transformed by the RSC\n  //   plugin into a client reference proxy. Calling it throws — correct,\n  //   because hooks can't run during server component rendering.\n  // In SSR: use-query-states.ts is the real nuqs-backed function. Hooks\n  //   work during SSR's renderToReadableStream, so this works correctly.\n  // On the client: same as SSR — the real function is available.\n  function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {\n    return clientUseQueryStates(codecMap, options, Object.freeze({ ...urlKeys })) as [\n      T,\n      SetParams<T>,\n    ];\n  }\n\n  // ---- load ----\n  // ALS-backed: reads rawSearchParams() from the current request context\n  // and parses through codecs. Server-only — throws on client.\n  async function load(): Promise<T> {\n    if (typeof window !== 'undefined') {\n      throw new Error(\n        '[timber] searchParams.load() is server-only. ' +\n          'Use searchParams.useQueryStates() on the client.'\n      );\n    }\n    const raw = await getRawSearchParams();\n    return parseSync(raw);\n  }\n\n  const definition: SearchParamsDefinition<T> = {\n    parse,\n    load,\n    useQueryStates,\n    extend,\n    pick,\n    serialize,\n    href,\n    toSearchParams,\n    codecs: codecMap,\n    urlKeys: Object.freeze({ ...urlKeys }),\n  };\n\n  return definition;\n}\n","/**\n * Codec wrappers — withDefault and withUrlKey.\n *\n * These are timber-specific utilities that work with any SearchParamCodec.\n * For actual codecs (string, integer, boolean, etc.), use nuqs parsers\n * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.\n *\n * Design doc: design/23-search-params.md\n */\n\nimport type { SearchParamCodec, SearchParamCodecWithUrlKey } from './define.js';\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. When the inner codec returns\n * null, the default is used instead. The output type becomes non-nullable.\n *\n * Works with any codec — nuqs parsers, custom codecs, fromSchema results.\n *\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * import { withDefault } from '@timber-js/app/search-params'\n *\n * const page = withDefault(parseAsInteger, 1)\n * // page.parse(undefined) → 1 (not null)\n * // page.parse('5') → 5\n * ```\n */\nexport function withDefault<T>(\n  codec: SearchParamCodec<T | null>,\n  defaultValue: T\n): SearchParamCodec<T> {\n  return {\n    parse(value: string | string[] | undefined): T {\n      const result = codec.parse(value);\n      return result === null ? defaultValue : result;\n    },\n    serialize(value: T): string | null {\n      return codec.serialize(value);\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// withUrlKey\n// ---------------------------------------------------------------------------\n\n/**\n * Attach a URL key alias to a codec. The alias determines what query\n * parameter key is used in the URL, while the TypeScript property name\n * stays descriptive.\n *\n * Aliases travel with codecs through object spread composition — when\n * you spread a bundle containing aliased codecs into defineSearchParams,\n * the aliases come along automatically.\n *\n * ```ts\n * import { parseAsString } from 'nuqs'\n * import { withUrlKey } from '@timber-js/app/search-params'\n *\n * export const searchable = {\n *   q: withUrlKey(parseAsString, 'search'),\n *   // ?search=shoes → { q: 'shoes' }\n * }\n * ```\n *\n * Composes with withDefault:\n * ```ts\n * import { parseAsInteger } from 'nuqs'\n * withUrlKey(withDefault(parseAsInteger, 1), 'p')\n * ```\n */\nexport function withUrlKey<T>(\n  codec: SearchParamCodec<T>,\n  urlKey: string\n): SearchParamCodecWithUrlKey<T> {\n  return {\n    parse: codec.parse.bind(codec),\n    serialize: codec.serialize.bind(codec),\n    urlKey,\n  };\n}\n"],"mappings":"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"}