@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/dist/_chunks/{use-query-states-DFvWd-EA.js → use-query-states-BbU5Ge1V.js}

@@ -1,5 +1,21 @@
-import { t as getSearchParamsDefinition } from "./registry-DbJPKoBp.js";
 import { useQueryStates } from "nuqs";
+//#region src/search-params/parse-total.ts
+function hasParseServerSide(codec) {
+	return typeof codec.parseServerSide === "function";
+}
+/**
+* Parse a raw URL value through a codec, using the codec's total entry
+* point when it publishes one.
+*
+* Returns `T`, from both branches. A `null` for an absent param is part of
+* the codec's own `T` — see TotalCodec above — so this signature does not
+* widen it, and a caller that must handle "no value" (`withDefault`) sees
+* it because `T` carries it.
+*/
+function parseTotal(codec, raw) {
+	return hasParseServerSide(codec) ? codec.parseServerSide(raw) : codec.parse(raw);
+}
+//#endregion
 //#region src/client/use-query-states.ts
 /**
 * useQueryStates — client-side hook for URL-synced search params.
@@ -23,30 +39,43 @@ function unwrapNuqsValue(value) {
 	return value;
 }
 /**
-* Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.
+* Bridge a timber SearchParamCodec to a nuqs-compatible MultiParser.
 *
 * nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }
 * timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }
 *
-* The defaultValue is computed eagerly. Codecs are documented to return a
-* default rather than throw, but a throwing codec must not crash every
-* component that mounts the hook — treat its default as undefined and let
-* its error surface from server-side parse() instead.
+* The defaultValue is computed eagerly, through `parseTotal` — the same
+* entry point server-side `parse()` uses, so the hook and the server agree
+* on what an absent param means (a bare nuqs parser answers `null`, not
+* `undefined`; TIM-1350). Codecs are documented to return a default rather
+* than throw, but a throwing codec must not crash every component that
+* mounts the hook — treat its default as undefined and let its error
+* surface from server-side parse() instead.
+*
+* A `null` absent-value is NOT registered as the nuqs default. nuqs
+* already represents an absent key as `null`, so the hook reads the same
+* value either way — but registering it makes `clearOnDefault` fire on
+* `setParams({ q: null })` and delete the key before the bridged
+* `serialize` runs. For a codec that encodes `null` as a real query value
+* (`serialize(null) === 'none'`), that silently disagrees with
+* `buildSearchParams({ q: null })`, which writes it. Same reasoning as
+* `getDefaultSerialized` on the server: a codec with no value for an
+* absent param has no default to register.
 */
 function bridgeCodec(codec) {
-	let defaultValue;
+	let absent;
 	try {
-		defaultValue = codec.parse(void 0);
+		absent = parseTotal(codec, void 0);
 	} catch {
-		defaultValue = void 0;
+		absent = void 0;
 	}
-	return {
-		parse: (v) => wrapNuqsValue(codec.parse(v)),
+	const parser = {
+		type: "multi",
+		parse: (v) => wrapNuqsValue(parseTotal(codec, v.length === 1 ? v[0] : [...v])),
 		serialize: (v) => {
 			const value = unwrapNuqsValue(v);
-			return value === void 0 ? "" : codec.serialize(value) ?? "";
+			return [value === void 0 ? "" : codec.serialize(value) ?? ""];
 		},
-		defaultValue: wrapNuqsValue(defaultValue),
 		eq: (a, b) => {
 			if (a === b) return true;
 			try {
@@ -56,6 +85,23 @@ function bridgeCodec(codec) {
 			}
 		}
 	};
+	if (absent !== null) parser.defaultValue = wrapNuqsValue(absent);
+	return parser;
+}
+/**
+* Collect `withUrlKey` aliases off a codec map.
+*
+* `withUrlKey(codec, 'q')` returns a codec carrying `urlKey: 'q'`, so the map
+* alone is enough to reconstruct the aliases — `defineSearchParams` builds its
+* own `urlKeys` from exactly this property.
+*/
+function deriveUrlKeys(codecs) {
+	const result = {};
+	for (const key of Object.keys(codecs)) {
+		const alias = codecs[key]?.urlKey;
+		if (alias) result[key] = alias;
+	}
+	return result;
 }
 /**
 * Bridge an entire codec map to nuqs-compatible parsers.
@@ -73,7 +119,7 @@ function bridgeCodecs(codecs) {
 *
 * Usage:
 * ```ts
-* // Via a SearchParamsDefinition
+* // Via a SearchParamsDefinition imported from the route's params.ts
 * const [params, setParams] = definition.useQueryStates()
 *
 * // Standalone with inline codecs
@@ -81,22 +127,24 @@ function bridgeCodecs(codecs) {
 *   page: fromSchema(z.coerce.number().int().min(1).default(1)),
 * })
 * ```
+*
+* There is deliberately no route-string form (`useQueryStates('/products')`).
+* Importing the definition from `params.ts` is the documented way to reach
+* another route's codecs — it needs no runtime registry lookup and so has no
+* "not registered yet" failure mode. See design/23-search-params.md
+* §"Client Access".
 */
-function useQueryStates$1(codecsOrRoute, _options, urlKeys) {
-	let codecs;
-	let resolvedUrlKeys = urlKeys;
-	if (typeof codecsOrRoute === "string") {
-		const definition = getSearchParamsDefinition(codecsOrRoute);
-		if (!definition) throw new Error(`useQueryStates('${codecsOrRoute}'): no search params registered for this route. Either the route has no search-params.ts file, or it hasn't been loaded yet. For cross-route usage, import the definition explicitly.`);
-		codecs = definition.codecs;
-		resolvedUrlKeys = definition.urlKeys;
-	} else codecs = codecsOrRoute;
+function useQueryStates$1(codecs, _options, urlKeys) {
 	const bridged = bridgeCodecs(codecs);
 	const nuqsOptions = {};
 	if (_options?.shallow !== void 0) nuqsOptions.shallow = _options.shallow;
 	if (_options?.scroll !== void 0) nuqsOptions.scroll = _options.scroll;
 	if (_options?.history !== void 0) nuqsOptions.history = _options.history;
-	if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) nuqsOptions.urlKeys = resolvedUrlKeys;
+	const resolvedUrlKeys = {
+		...deriveUrlKeys(codecs),
+		...urlKeys
+	};
+	if (Object.keys(resolvedUrlKeys).length > 0) nuqsOptions.urlKeys = resolvedUrlKeys;
 	let values;
 	let setValues;
 	try {
@@ -149,6 +197,6 @@ function bindUseQueryStates(definition) {
 	};
 }
 //#endregion
-export { useQueryStates$1 as n, bindUseQueryStates as t };
+export { useQueryStates$1 as n, parseTotal as r, bindUseQueryStates as t };
 
-//# sourceMappingURL=use-query-states-DFvWd-EA.js.map
+//# sourceMappingURL=use-query-states-BbU5Ge1V.js.map

package/dist/_chunks/use-query-states-BbU5Ge1V.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-query-states-BbU5Ge1V.js","names":[],"sources":["../../src/search-params/parse-total.ts","../../src/client/use-query-states.ts"],"sourcesContent":["/**\n * parseTotal — invoke a codec over the FULL raw domain.\n *\n * `SearchParamCodec.parse` is documented to be total over\n * `string | string[] | undefined`, because that is exactly what a URL\n * hands it: a param can be absent (`undefined`) or repeated (`string[]`).\n * Timber's own codecs and the Standard Schema bridges honour that.\n *\n * nuqs parsers do not. Their `parse` expects a **present scalar string** —\n * nuqs checks presence itself before ever calling it — so `parseAsBoolean`\n * and `parseAsIsoDate` threw a render-phase 500 on an absent param and\n * `parseAsString` returned an array on a repeated one (TIM-1350).\n *\n * nuqs ships the missing adapter: every parser builder exposes\n * `parseServerSide(value: string | string[] | undefined)`, which maps\n * absent → `null` (or the parser's `withDefault` value), takes the FIRST\n * entry of a repeated param (matching `URLSearchParams.get()`), and wraps\n * the inner `parse` so a throw becomes `null`. That is precisely timber's\n * domain, so we call it in preference to `parse` rather than hand-rolling\n * a second normalization that could disagree with the client hook.\n *\n * Feature detection, not an instanceof check: any codec MAY publish\n * `parseServerSide` to declare \"this is my total entry point\" — it is an\n * optional member of `SearchParamCodec` — and a codec that does not is\n * assumed already total and called through `parse`. Timber codecs and\n * schema bridges take the second branch untouched; several of them rely on\n * `parse(undefined)` to produce their default.\n *\n * **Search params only.** Segment params (`server/param-coercion.ts`) call\n * `codec.parse` directly and must keep doing so: their domain is a value\n * the router matched, never absent, and a codec that REJECTS one is how a\n * route produces a 404. Routing a rejection through nuqs's `safeParse`\n * would turn that 404 into a silent `null` param. The two domains differ\n * in what \"no value\" means, not just in plumbing. Cookies are a third\n * domain (`cookies/define-cookie.ts`) and are likewise untouched.\n *\n * `parseServerSide` carries a `@deprecated` tag in nuqs (it steers users to\n * loaders, which timber does not use). It remains public, typed and\n * exercised; `tests/nuqs-codec-boundary.test.ts` asserts totality for every\n * parser through timber's own API, so a nuqs release that drops it fails\n * loudly rather than silently reinstating the 500s.\n *\n * Design doc: design/23-search-params.md §\"nuqs parsers, made total\"\n */\n\nimport type { Codec } from '../codec.js';\n\n/**\n * A codec that publishes a total entry point over the raw URL domain.\n *\n * The return is `T`, not `T | null`: this is the entry point timber calls,\n * so whatever it answers IS the field's type. A `null` for an absent param\n * belongs in `T` — a bare nuqs parser is a codec of `string | null`, and\n * `parseAsInteger.withDefault(1)` is a codec of `number`, because nuqs\n * narrows its own `parseServerSide` return to `NonNullable<T>`. Declaring\n * `T | null` here would let a codec annotated `SearchParamCodec<string>`\n * hand back `null` under a non-nullable type (TIM-1350 review).\n */\nexport interface TotalCodec<T> {\n  parseServerSide(value: string | string[] | undefined): T;\n}\n\nfunction hasParseServerSide<T>(codec: Codec<T>): codec is Codec<T> & TotalCodec<T> {\n  return typeof (codec as Partial<TotalCodec<T>>).parseServerSide === 'function';\n}\n\n/**\n * Parse a raw URL value through a codec, using the codec's total entry\n * point when it publishes one.\n *\n * Returns `T`, from both branches. A `null` for an absent param is part of\n * the codec's own `T` — see TotalCodec above — so this signature does not\n * widen it, and a caller that must handle \"no value\" (`withDefault`) sees\n * it because `T` carries it.\n */\nexport function parseTotal<T>(codec: Codec<T>, raw: string | string[] | undefined): T {\n  return hasParseServerSide(codec) ? codec.parseServerSide(raw) : codec.parse(raw);\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 { MultiParser } from 'nuqs';\nimport type {\n  SearchParamCodec,\n  SearchParamsDefinition,\n  SetParams,\n  QueryStatesOptions,\n} from '../search-params/define.js';\nimport { parseTotal } from '../search-params/parse-total.js';\n\n// ─── Codec Bridge ─────────────────────────────────────────────────\n\n// nuqs's parser contract conflates values timber codecs distinguish:\n// parse() returning null means \"unparseable, substitute defaultValue\",\n// and undefined entries are skipped entirely. Timber codecs can\n// legitimately produce both — bare z.string() yields undefined for absent\n// params (implicit optionality), and a codec may map a present value to\n// null. Wrap those two values in sentinels across the nuqs boundary and\n// unwrap them before handing values back to the caller, so the client\n// hook returns exactly what server-side parse() returns.\n// Unique object references compared by identity — a codec can never\n// produce these from URL input, so user-controlled strings cannot collide\n// with them (unlike string sentinels), and unlike Symbols they survive\n// nuqs's internal string coercion without throwing.\nconst NULL_SENTINEL: object = { timberSentinel: 'null' };\nconst UNDEFINED_SENTINEL: object = { timberSentinel: 'undefined' };\n\nfunction wrapNuqsValue(value: unknown): unknown {\n  if (value === null) return NULL_SENTINEL;\n  if (value === undefined) return UNDEFINED_SENTINEL;\n  return value;\n}\n\nfunction unwrapNuqsValue(value: unknown): unknown {\n  if (value === NULL_SENTINEL) return null;\n  if (value === UNDEFINED_SENTINEL) return undefined;\n  return value;\n}\n\n/**\n * Bridge a timber SearchParamCodec to a nuqs-compatible MultiParser.\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 *\n * The defaultValue is computed eagerly, through `parseTotal` — the same\n * entry point server-side `parse()` uses, so the hook and the server agree\n * on what an absent param means (a bare nuqs parser answers `null`, not\n * `undefined`; TIM-1350). Codecs are documented to return a default rather\n * than throw, but a throwing codec must not crash every component that\n * mounts the hook — treat its default as undefined and let its error\n * surface from server-side parse() instead.\n *\n * A `null` absent-value is NOT registered as the nuqs default. nuqs\n * already represents an absent key as `null`, so the hook reads the same\n * value either way — but registering it makes `clearOnDefault` fire on\n * `setParams({ q: null })` and delete the key before the bridged\n * `serialize` runs. For a codec that encodes `null` as a real query value\n * (`serialize(null) === 'none'`), that silently disagrees with\n * `buildSearchParams({ q: null })`, which writes it. Same reasoning as\n * `getDefaultSerialized` on the server: a codec with no value for an\n * absent param has no default to register.\n */\nfunction bridgeCodec<T>(codec: SearchParamCodec<T>): MultiParser<T> & { defaultValue: T } {\n  let absent: unknown;\n  try {\n    absent = parseTotal(codec, undefined);\n  } catch {\n    absent = undefined;\n  }\n\n  const parser = {\n    // `multi`, so nuqs reads the key with `searchParams.getAll()` and hands\n    // us EVERY value. A single parser reads `.get()` — the first value only\n    // — which is not the domain a timber codec is defined over. The server\n    // parses `?tags=a&tags=b` as `['a','b']`; a single parser made the hook\n    // answer `['a']` for the same URL, under a declared `string[]` that\n    // admitted no such disagreement (TIM-1352). Scalar codecs are unaffected:\n    // they receive the array and take `value[0]`, exactly as they do on the\n    // server, so first-value-wins is preserved through the same code path\n    // rather than through nuqs's reader.\n    //\n    // nuqs never calls this with an empty array — `isAbsentFromUrl` treats\n    // `[]` as absent and answers `defaultValue` directly — which is what\n    // keeps the absent case agreeing with the server's `undefined`.\n    //\n    // Reading every value is only half of it: the values must arrive in the\n    // SAME SHAPE the server would have produced, or the divergence just\n    // moves. `normalizeRaw` (search-params/define.ts) collapses a\n    // single-valued key to a bare string and keeps an array only for a\n    // repeated one, so this mirrors that rule exactly. Handing a codec\n    // `['3']` where the server hands it `'3'` breaks every codec whose\n    // `parse` is written for the scalar case — which is most hand-written\n    // ones, contract or no contract.\n    type: 'multi' as const,\n    // Through parseTotal, not codec.parse. nuqs's own `.withDefault(d)`\n    // overrides ONLY `parseServerSide`, so `parseAsInteger.withDefault(1)`\n    // on `?page=abc` returned 1 from the server and null from the hook —\n    // a divergence the declared non-nullable `number` did not admit.\n    parse: (v: readonly string[]) =>\n      wrapNuqsValue(parseTotal(codec, v.length === 1 ? v[0] : [...v])),\n    serialize: (v: unknown) => {\n      const value = unwrapNuqsValue(v);\n      // Delegate null to the codec — some codecs encode null as a real\n      // query value. undefined has no encoding; nuqs requires a string.\n      //\n      // ONE element, always. A multi parser may return several — nuqs\n      // appends one key per entry — but `Codec.serialize` returns a single\n      // string by construction, so timber cannot emit repeated keys here\n      // any more than `buildSearchParams` can. Widening that protocol is\n      // TIM-1353. Wrapping the same string keeps the URL the hook writes\n      // byte-identical to the one `buildSearchParams` writes.\n      return [value === undefined ? '' : (codec.serialize(value as T) ?? '')];\n    },\n    eq: (a: unknown, b: unknown) => {\n      if (a === b) return true;\n      try {\n        return (\n          codec.serialize(unwrapNuqsValue(a) as T) === codec.serialize(unwrapNuqsValue(b) as T)\n        );\n      } catch {\n        return false;\n      }\n    },\n  } as MultiParser<T> & { defaultValue: T };\n\n  if (absent !== null) parser.defaultValue = wrapNuqsValue(absent) as T;\n  return parser;\n}\n\n/**\n * Collect `withUrlKey` aliases off a codec map.\n *\n * `withUrlKey(codec, 'q')` returns a codec carrying `urlKey: 'q'`, so the map\n * alone is enough to reconstruct the aliases — `defineSearchParams` builds its\n * own `urlKeys` from exactly this property.\n */\nfunction deriveUrlKeys(codecs: Record<string, SearchParamCodec<unknown>>): Record<string, string> {\n  const result: Record<string, string> = {};\n  for (const key of Object.keys(codecs)) {\n    const alias = codecs[key]?.urlKey;\n    if (alias) result[key] = alias;\n  }\n  return result;\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, MultiParser<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]: MultiParser<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 imported from the route's params.ts\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 *\n * There is deliberately no route-string form (`useQueryStates('/products')`).\n * Importing the definition from `params.ts` is the documented way to reach\n * another route's codecs — it needs no runtime registry lookup and so has no\n * \"not registered yet\" failure mode. See design/23-search-params.md\n * §\"Client Access\".\n */\nexport function useQueryStates<T extends Record<string, unknown>>(\n  codecs: { [K in keyof T]: SearchParamCodec<T[K]> },\n  _options?: QueryStatesOptions,\n  urlKeys?: Readonly<Record<string, string>>\n): [T, SetParams<T>] {\n  const bridged = bridgeCodecs(codecs);\n\n  // Forward hook-level options (shallow, scroll, history) to nuqs.\n  // These become the default for all setter calls from this hook instance.\n  // Per-call options in setParams(values, opts) override these defaults.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const nuqsOptions: any = {};\n  if (_options?.shallow !== undefined) nuqsOptions.shallow = _options.shallow;\n  if (_options?.scroll !== undefined) nuqsOptions.scroll = _options.scroll;\n  if (_options?.history !== undefined) nuqsOptions.history = _options.history;\n  // `withUrlKey` attaches the alias to the codec itself — that is the design's\n  // \"URL keys travel with codecs\" principle — so the aliases are derivable\n  // here and must be, for the inline codec-map form: nobody passes `urlKeys`\n  // on that path, and without this an aliased bundle silently read and wrote\n  // the property name instead of the alias. `bindUseQueryStates` still passes\n  // the definition's precomputed map, which wins on conflict; it is built from\n  // these same codecs, so the two agree by construction rather than by luck.\n  const resolvedUrlKeys = { ...deriveUrlKeys(codecs), ...urlKeys };\n  if (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  // Unwrap the null/undefined sentinels the bridge injected (see Codec\n  // Bridge above) so callers see exactly what server-side parse() returns.\n  // Copy-on-write preserves the identity of nuqs's memoized values object\n  // when nothing needs unwrapping.\n  let normalized = values;\n  for (const key of Object.keys(bridged)) {\n    const value = normalized[key];\n    if (value === NULL_SENTINEL || value === UNDEFINED_SENTINEL) {\n      if (normalized === values) normalized = { ...values };\n      normalized[key] = unwrapNuqsValue(value);\n    }\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    // nuqs's update loop skips undefined entries and treats null as a\n    // key deletion before serialize runs. Timber semantics:\n    //   - setParams({ q: undefined }) must clear ?q= (absent = undefined),\n    //     so explicit undefined maps to a null deletion.\n    //   - setParams({ q: null }) clears the key only when the codec encodes\n    //     null as \"omit\" (serialize(null) === null). If the codec encodes\n    //     null as a real query value, forward the sentinel so the bridged\n    //     serialize writes it — matching definition.serialize({ q: null }).\n    let forwarded: Record<string, unknown> = partial;\n    for (const key of Object.keys(partial)) {\n      const value = partial[key as keyof T];\n      if (value === undefined) {\n        if (forwarded === partial) forwarded = { ...partial };\n        forwarded[key] = null;\n      } else if (value === null) {\n        let encoded: string | null = null;\n        try {\n          encoded = codecs[key as keyof T]?.serialize(null as T[keyof T]) ?? null;\n        } catch {\n          // Codec can't serialize null — treat as a deletion.\n        }\n        if (encoded !== null) {\n          if (forwarded === partial) forwarded = { ...partial };\n          forwarded[key] = NULL_SENTINEL;\n        }\n      }\n    }\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    void setValues(forwarded as any, nuqsSetOptions);\n  };\n\n  return [normalized 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":";;AA8DA,SAAS,mBAAsB,OAAoD;CACjF,OAAO,OAAQ,MAAiC,oBAAoB;AACtE;;;;;;;;;;AAWA,SAAgB,WAAc,OAAiB,KAAuC;CACpF,OAAO,mBAAmB,KAAK,IAAI,MAAM,gBAAgB,GAAG,IAAI,MAAM,MAAM,GAAG;AACjF;;;;;;;;;;;;ACzCA,IAAM,gBAAwB,EAAE,gBAAgB,OAAO;AACvD,IAAM,qBAA6B,EAAE,gBAAgB,YAAY;AAEjE,SAAS,cAAc,OAAyB;CAC9C,IAAI,UAAU,MAAM,OAAO;CAC3B,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,OAAO;AACT;AAEA,SAAS,gBAAgB,OAAyB;CAChD,IAAI,UAAU,eAAe,OAAO;CACpC,IAAI,UAAU,oBAAoB,OAAO,KAAA;CACzC,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAS,YAAe,OAAkE;CACxF,IAAI;CACJ,IAAI;EACF,SAAS,WAAW,OAAO,KAAA,CAAS;CACtC,QAAQ;EACN,SAAS,KAAA;CACX;CAEA,MAAM,SAAS;EAuBb,MAAM;EAKN,QAAQ,MACN,cAAc,WAAW,OAAO,EAAE,WAAW,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;EACjE,YAAY,MAAe;GACzB,MAAM,QAAQ,gBAAgB,CAAC;GAU/B,OAAO,CAAC,UAAU,KAAA,IAAY,KAAM,MAAM,UAAU,KAAU,KAAK,EAAG;EACxE;EACA,KAAK,GAAY,MAAe;GAC9B,IAAI,MAAM,GAAG,OAAO;GACpB,IAAI;IACF,OACE,MAAM,UAAU,gBAAgB,CAAC,CAAM,MAAM,MAAM,UAAU,gBAAgB,CAAC,CAAM;GAExF,QAAQ;IACN,OAAO;GACT;EACF;CACF;CAEA,IAAI,WAAW,MAAM,OAAO,eAAe,cAAc,MAAM;CAC/D,OAAO;AACT;;;;;;;;AASA,SAAS,cAAc,QAA2E;CAChG,MAAM,SAAiC,CAAC;CACxC,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAAG;EACrC,MAAM,QAAQ,OAAO,IAAI,EAAE;EAC3B,IAAI,OAAO,OAAO,OAAO;CAC3B;CACA,OAAO;AACT;;;;AAKA,SAAS,aAAgD,QAEtD;CACD,MAAM,SAA2E,CAAC;CAClF,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,GAElC,OAAO,OAAO,YAAY,OAAO,IAAe;CAElD,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,iBACd,QACA,UACA,SACmB;CACnB,MAAM,UAAU,aAAa,MAAM;CAMnC,MAAM,cAAmB,CAAC;CAC1B,IAAI,UAAU,YAAY,KAAA,GAAW,YAAY,UAAU,SAAS;CACpE,IAAI,UAAU,WAAW,KAAA,GAAW,YAAY,SAAS,SAAS;CAClE,IAAI,UAAU,YAAY,KAAA,GAAW,YAAY,UAAU,SAAS;CAQpE,MAAM,kBAAkB;EAAE,GAAG,cAAc,MAAM;EAAG,GAAG;CAAQ;CAC/D,IAAI,OAAO,KAAK,eAAe,CAAC,CAAC,SAAS,GACxC,YAAY,UAAU;CAGxB,IAAI;CACJ,IAAI;CACJ,IAAI;EACF,CAAC,QAAQ,aAAa,eAAmB,SAAS,WAAW;CAC/D,SAAS,KAAK;EACZ,IACE,eAAe,SACf,qEAAqE,KAAK,IAAI,OAAO,GAErF,MAAM,IAAI,MACR,4JAEF;EAEF,MAAM;CACR;CAMA,IAAI,aAAa;CACjB,KAAK,MAAM,OAAO,OAAO,KAAK,OAAO,GAAG;EACtC,MAAM,QAAQ,WAAW;EACzB,IAAI,UAAU,iBAAiB,UAAU,oBAAoB;GAC3D,IAAI,eAAe,QAAQ,aAAa,EAAE,GAAG,OAAO;GACpD,WAAW,OAAO,gBAAgB,KAAK;EACzC;CACF;CAKA,MAAM,aAA2B,SAAS,eAAgB;EACxD,MAAM,iBAA0C,CAAC;EACjD,IAAI,YAAY,YAAY,KAAA,GAAW,eAAe,UAAU,WAAW;EAC3E,IAAI,YAAY,WAAW,KAAA,GAAW,eAAe,SAAS,WAAW;EACzE,IAAI,YAAY,YAAY,KAAA,GAAW,eAAe,UAAU,WAAW;EAS3E,IAAI,YAAqC;EACzC,KAAK,MAAM,OAAO,OAAO,KAAK,OAAO,GAAG;GACtC,MAAM,QAAQ,QAAQ;GACtB,IAAI,UAAU,KAAA,GAAW;IACvB,IAAI,cAAc,SAAS,YAAY,EAAE,GAAG,QAAQ;IACpD,UAAU,OAAO;GACnB,OAAO,IAAI,UAAU,MAAM;IACzB,IAAI,UAAyB;IAC7B,IAAI;KACF,UAAU,OAAO,IAAe,EAAE,UAAU,IAAkB,KAAK;IACrE,QAAQ,CAER;IACA,IAAI,YAAY,MAAM;KACpB,IAAI,cAAc,SAAS,YAAY,EAAE,GAAG,QAAQ;KACpD,UAAU,OAAO;IACnB;GACF;EACF;EAEA,UAAe,WAAkB,cAAc;CACjD;CAEA,OAAO,CAAC,YAAiB,SAAS;AACpC;;;;;AAQA,SAAgB,mBACd,YACqD;CACrD,QAAQ,YAAiC;EACvC,OAAO,iBAAkB,WAAW,QAAQ,SAAS,WAAW,OAAO;CACzE;AACF"}

package/dist/_chunks/use-segment-params-C4r4BD9T.js

@@ -0,0 +1,398 @@
+import { t as resolveSegmentParams } from "./slot-params-BCTmZkQB.js";
+import { a as _setCurrentParams, d as currentParams, f as currentSlotParams, n as getSsrData, o as _setCurrentSlotParams } from "./ssr-data-14MXm7Pj.js";
+import { n as getRouterOrNull } from "./router-ref-DuYuV_0Q.js";
+import "./segment-context-CjOlyB8Y.js";
+import React, { createElement, useSyncExternalStore } from "react";
+//#region src/client/use-pending-navigation.ts
+function subscribe(onStoreChange) {
+	const router = getRouterOrNull();
+	if (!router) return () => {};
+	return router.onPendingChange(onStoreChange);
+}
+function getSnapshot() {
+	const router = getRouterOrNull();
+	return router ? router.isPending() : false;
+}
+var getServerSnapshot = getSnapshot;
+/**
+* Returns true while an RSC navigation is in flight.
+*
+* Reads from the router's external pending store via useSyncExternalStore.
+* Only components that call this hook re-render when pending state
+* changes — no full-tree re-render.
+*
+* ```tsx
+* 'use client'
+* import { usePendingNavigation } from '@timber-js/app/client'
+*
+* export function NavBar() {
+*   const isPending = usePendingNavigation()
+*   return (
+*     <nav className={isPending ? 'opacity-50' : ''}>
+*       <Link href="/dashboard">Dashboard</Link>
+*     </nav>
+*   )
+* }
+* ```
+*/
+function usePendingNavigation() {
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+//#endregion
+//#region src/client/navigation-context.ts
+/**
+* NavigationContext — React context for navigation state.
+*
+* Holds the current pathname and search, updated atomically with the RSC
+* tree on each navigation. This replaces the previous useSyncExternalStore
+* approach for usePathname() and useSearchParams(), which suffered from a
+* timing gap: the new tree could commit before the external store
+* re-renders fired, causing a frame where both old and new active states
+* were visible simultaneously.
+*
+* Segment params are NOT here — see the note on NavigationState below.
+*
+* By wrapping the RSC payload element in NavigationProvider inside
+* renderRoot(), the context value and the element tree are passed to
+* reactRoot.render() in the same call — atomic by construction.
+* All consumers (usePathname, useSearchParams) see the new values in the
+* same render pass as the new tree.
+*
+* During SSR, no NavigationProvider is mounted. Hooks fall back to
+* the ALS-backed getSsrData() for per-request isolation.
+*
+* IMPORTANT: createContext and useContext are NOT available in the RSC
+* environment (React Server Components use a stripped-down React).
+* The context is lazily initialized on first access, and all functions
+* that depend on these APIs are safe to call from any environment —
+* they return null or no-op when the APIs aren't available.
+*
+* SINGLETON GUARANTEE: All shared mutable state uses globalThis via
+* Symbol.for keys. The RSC client bundler can duplicate this module
+* across chunks (browser-entry graph + client-reference graph). With
+* ESM output, each chunk gets its own module scope — module-level
+* variables would create separate singleton instances per chunk.
+* globalThis guarantees a single instance regardless of duplication.
+*
+* This workaround will be removed when Rolldown ships `format: 'app'`
+* (module registry format that deduplicates like webpack/Turbopack).
+* See design/27-chunking-strategy.md.
+*
+* See design/19-client-navigation.md §"NavigationContext"
+*/
+/**
+* The context is created lazily to avoid calling createContext at module
+* level. In the RSC environment, React.createContext doesn't exist —
+* calling it at import time would crash the server.
+*
+* Context instances are stored on globalThis (NOT in module-level
+* variables) because the ESM bundler can duplicate this module across
+* chunks. Module-level variables would create separate instances per
+* chunk — the provider in NavigationRoot (index chunk) would use
+* context A while the consumer in usePendingNavigation (shared chunk)
+* reads from context B. globalThis guarantees a single instance.
+*
+* See design/27-chunking-strategy.md §"Singleton Safety"
+*/
+var NAV_CTX_KEY = Symbol.for("__timber_nav_ctx");
+function getOrCreateContext$1() {
+	const existing = globalThis[NAV_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext === "function") {
+		const ctx = React.createContext(null);
+		globalThis[NAV_CTX_KEY] = ctx;
+		return ctx;
+	}
+}
+/**
+* Read the navigation context. Returns null during SSR (no provider)
+* or in the RSC environment (no context available).
+* Internal — used by usePathname() and useSearchParams().
+*/
+function useNavigationContext() {
+	const ctx = getOrCreateContext$1();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
+}
+/**
+* Wraps children with NavigationContext.Provider.
+*
+* Used in browser-entry.ts renderRoot to wrap the RSC payload element
+* so that navigation state updates atomically with the tree render.
+*/
+function NavigationProvider({ value, children }) {
+	const ctx = getOrCreateContext$1();
+	if (!ctx) return children;
+	return createElement(ctx.Provider, { value }, children);
+}
+/**
+* Navigation state communicated between the router and renderRoot.
+*
+* The router calls setNavigationState() before renderRoot(). The
+* renderRoot callback reads via getNavigationState() to create the
+* NavigationProvider with the correct params/pathname.
+*
+* This is NOT used by hooks directly — hooks read from React context.
+*
+* Stored on globalThis (like the context instances above) because the
+* router lives in one chunk while renderRoot lives in another. Module-
+* level variables would be separate per chunk.
+*/
+var NAV_STATE_KEY = Symbol.for("__timber_nav_state");
+function _getNavStateStore() {
+	const g = globalThis;
+	if (!g[NAV_STATE_KEY]) g[NAV_STATE_KEY] = { current: {
+		pathname: "/",
+		search: ""
+	} };
+	return g[NAV_STATE_KEY];
+}
+function setNavigationState(state) {
+	_getNavStateStore().current = state;
+}
+function getNavigationState() {
+	return _getNavStateStore().current;
+}
+/**
+* There was a second React context here — `PendingNavigationContext`, holding
+* the in-flight navigation URL, provided by `NavigationRoot` out of a
+* `useState` — plus a `usePendingNavigationUrl()` reader for it. Both are gone
+* (TIM-1307).
+*
+* Nothing read them. `usePendingNavigation()` (use-pending-navigation.ts) and
+* `TopLoader` both subscribe to the router's external pending store via
+* `useSyncExternalStore`: sync priority, immune to transition entanglement,
+* and cleared by `runNavigation`'s supersession-guarded `finally` (TIM-1034).
+* The context was a parallel representation of the same fact that no consumer
+* ever migrated to, and one that could not even agree with the store — a
+* navigation superseded by a cached popstate replay left its URL set until the
+* next full navigation, because the staleness guard skipped the clear and no
+* other path touched it.
+*
+* One representation, and it is the router's. See
+* design/19-client-navigation.md §"How Pending State Works".
+*/
+//#endregion
+//#region src/client/top-loader.tsx
+/**
+* TopLoader — Built-in progress bar for client navigations.
+*
+* Shows an animated progress bar at the top of the viewport while an RSC
+* navigation is in flight. Injected automatically by the framework into
+* NavigationRoot — users never render this component directly.
+*
+* Configuration is via timber.config.ts `topLoader` key. Enabled by default.
+* Users who want a fully custom progress indicator disable the built-in one
+* (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.
+*
+* Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
+* width over ~30s using ease-out timing. When navigation completes, the bar
+* snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).
+*
+* Phase transitions are derived synchronously during render (React's
+* getDerivedStateFromProps pattern) — no useEffect needed for state tracking.
+* The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.
+*
+* When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar
+* stays invisible during the delay period. If navigation finishes before the
+* delay, the bar was never visible so the finish transition is also invisible.
+*
+* See design/19-client-navigation.md §"usePendingNavigation()"
+* See LOCAL-336 for design decisions.
+*/
+//#endregion
+//#region src/client/navigation-root.tsx
+var NAV_TRANSITION_KEY = Symbol.for("__timber_nav_transition_counter");
+function getTransitionCounter() {
+	const g = globalThis;
+	const existing = g[NAV_TRANSITION_KEY];
+	if (!existing) {
+		const created = {
+			id: 0,
+			waiters: /* @__PURE__ */ new Set()
+		};
+		g[NAV_TRANSITION_KEY] = created;
+		return created;
+	}
+	existing.waiters ??= /* @__PURE__ */ new Set();
+	return existing;
+}
+/** Bump the counter and wake everything waiting on an older transition. */
+function bumpTransitionCounter() {
+	const counter = getTransitionCounter();
+	counter.id += 1;
+	for (const wake of [...counter.waiters]) wake();
+	return counter.id;
+}
+/**
+* Invalidate all in-flight navigation transitions. Any navigateTransition()
+* call whose perform() has not yet committed will reject with AbortError
+* instead of committing its element.
+*
+* Called by the router when a render supersedes in-flight navigations
+* WITHOUT going through navigateTransition() — the cached popstate replay
+* renders via transitionRender(), which doesn't bump the counter, so a
+* stale forward navigation's setElement would otherwise pass the
+* `counter.id !== transId` guard and commit the forward page over the
+* replayed back page (TIM-1022).
+*/
+function supersedeNavigationTransitions() {
+	bumpTransitionCounter();
+}
+/**
+* Module-level flag indicating a hard (MPA) navigation is in progress.
+*
+* When true:
+* - NavigationRoot throws an unresolved thenable to suspend forever,
+*   preventing React from rendering children during page teardown
+*   (avoids "Rendered more hooks" crashes).
+* - The Navigation API handler skips interception, letting the browser
+*   perform a full page load (prevents infinite loops where
+*   window.location.href → navigate event → router.navigate → 500 →
+*   window.location.href → ...).
+*
+* Uses globalThis for singleton guarantee across chunks (same pattern
+* as NavigationContext). See design/19-client-navigation.md §"Singleton
+* Guarantee via globalThis".
+*/
+var HARD_NAV_KEY = Symbol.for("__timber_hard_navigating");
+function getHardNavStore() {
+	const g = globalThis;
+	if (!g[HARD_NAV_KEY]) g[HARD_NAV_KEY] = { value: false };
+	return g[HARD_NAV_KEY];
+}
+/**
+* Set the hard-navigating flag. Call this BEFORE setting
+* window.location.href or window.location.reload() to prevent:
+* 1. React from rendering children during page teardown
+* 2. Navigation API from intercepting the hard navigation
+*/
+function setHardNavigating(value) {
+	getHardNavStore().value = value;
+}
+//#endregion
+//#region src/client/params-context.ts
+/**
+* Segment params context — the one channel params use to reach the browser.
+*
+* Params ride the RSC payload's root row as a sibling of the tree
+* (`{ tree, params, slotParams }`), rather than in four side channels that
+* raced to seed them: a response header, an inline script, and two build-time
+* manifest fields all previously carried the same record, each with its own
+* `JSON.stringify` (TIM-1294).
+*
+* Riding the payload is what makes them *typed*. `defineSchema` takes any
+* `Codec<T>`, so a coerced param is whatever the codec returned — a `Date`, a
+* `bigint` — and `JSON.stringify` either flattened it to a string or threw
+* mid-response. React Flight carries those values natively, so the client
+* reads the value the server produced instead of a lossy copy of it. See
+* design/41-global-params.md §"Transport".
+*
+* **The client owns the provider.** There is exactly one `ParamsProvider` in
+* the browser's tree, rendered by `PayloadRoot` above the point where a
+* partial navigation splices the new payload into the retained tree. It has to
+* be there and it has to be alone: a provider *inside* the payload lands below
+* the retained region, whose own root is the departing route's provider, so
+* every reader in a skipped layout resolves to the departing record and no
+* amount of wrapping above it helps (TIM-1297).
+*
+* Ordering still holds without a bootstrap contract, for the same reason it
+* did when the provider was in the tree: a provider renders before its own
+* descendants by construction, so `useSegmentParams()` is correct during
+* hydration without anything having to run before `hydrateRoot()`.
+*/
+/**
+* SINGLETON GUARANTEE: globalThis + `Symbol.for`, the same pattern as
+* `NavigationContext` and `SegmentUpdateContext`.
+*
+* The RSC client bundler can duplicate a module across chunks, and with ESM
+* output each chunk gets its own module scope — so a bare `createContext` at
+* module level yields one context per chunk. This module is now reached from
+* *both* graphs: `PayloadRoot` is imported by the browser entry, while
+* `useParamsContext()` arrives through the client-reference graph with the
+* app's own components. A duplicate would put the provider on instance A and
+* every reader on instance B, so `useContext` returns `null` and every
+* `useSegmentParams()` call silently falls back to the module snapshot.
+*
+* This module was the one client context without the guard — harmless while
+* the provider travelled inside the payload, in the same graph as its readers,
+* and load-bearing the moment the client started rendering it (TIM-1297).
+*
+* The React APIs are reached through the namespace rather than named imports,
+* for the same reason `segment-update-context.ts` and `navigation-context.ts`
+* do it: React's `react-server` export provides neither `createContext` nor
+* `useContext`, and a *named* ESM import of a missing export fails at module
+* instantiation — before any feature check could run. This module is reachable
+* from every entry a Server Component imports, so the named form crashed
+* those entries outright (codex, PR #992; originally reproduced against
+* `@timber-js/app/segment-params`, an entry point since deleted by TIM-1342 —
+* the hazard is unchanged for the entries that remain).
+*
+* See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
+*/
+var PARAMS_CTX_KEY = Symbol.for("__timber_params_ctx");
+function getOrCreateContext() {
+	const store = globalThis;
+	const existing = store[PARAMS_CTX_KEY];
+	if (existing !== void 0) return existing;
+	if (typeof React.createContext !== "function") return;
+	const ctx = React.createContext(null);
+	store[PARAMS_CTX_KEY] = ctx;
+	return ctx;
+}
+var ParamsContext = getOrCreateContext();
+/**
+* Read the params provided by the tree. Returns null when no provider is
+* above the caller — a component rendered outside a timber route, a
+* `useSegmentParams()` call from outside React entirely, or any component
+* during SSR (where the params reach the hook through the ALS-backed SSR data
+* context instead, and there is no client-owned tree to hold a provider).
+*/
+function useParamsContext() {
+	return React.useContext(ParamsContext);
+}
+//#endregion
+//#region src/client/use-segment-params.ts
+/**
+* Set the current route params in the module-level store.
+*
+* Called by the router on each navigation. This updates the fallback
+* snapshot used by tests and by the hook when called outside a React
+* component (no NavigationContext available).
+*
+* On the client, the primary reactivity path is NavigationContext —
+* the router calls setNavigationState() then renderRoot() which wraps
+* the element in NavigationProvider. setCurrentParams is still called
+* for the module-level fallback.
+*
+* During SSR, params are also available via getSsrData().params
+* (ALS-backed).
+*/
+function setCurrentParams(params) {
+	_setCurrentParams(params);
+}
+/**
+* Set the per-slot params snapshot in the module-level store.
+*
+* Paired with `setCurrentParams`: the router calls both on every navigation,
+* including with `null` when a response carries no slot params, so a slot's
+* params from the *previous* route cannot be read on the next one. Fill and
+* serve are paired; so are fill and clear. See TIM-1285.
+*/
+function setCurrentSlotParams(slotParams) {
+	_setCurrentSlotParams(slotParams);
+}
+function useSegmentParams(segmentPath) {
+	try {
+		const paramsContext = useParamsContext();
+		if (paramsContext !== null) return resolveSegmentParams(paramsContext.params, paramsContext.slotParams, segmentPath);
+	} catch {}
+	const ssrData = getSsrData();
+	if (ssrData) return resolveSegmentParams(ssrData.params, ssrData.slotParams, segmentPath);
+	return resolveSegmentParams(currentParams, currentSlotParams, segmentPath);
+}
+//#endregion
+export { supersedeNavigationTransitions as a, setNavigationState as c, setHardNavigating as i, useNavigationContext as l, setCurrentSlotParams as n, NavigationProvider as o, useSegmentParams as r, getNavigationState as s, setCurrentParams as t, usePendingNavigation as u };
+
+//# sourceMappingURL=use-segment-params-C4r4BD9T.js.map