@timber-js/app 0.1.8 → 0.1.10

package/dist/server/route-matcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-matcher.d.ts","sourceRoot":"","sources":["../../src/server/route-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAM9B,6DAA6D;AAC7D,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EACP,QAAQ,GACR,SAAS,GACT,WAAW,GACX,oBAAoB,GACpB,OAAO,GACP,MAAM,GACN,cAAc,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IAC3D,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjD,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAE9C,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAC5C;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,YAAY,GACrB,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,CAEzC;AAsKD,2CAA2C;AAC3C,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,IAAI,EAAE,iBAAiB,CAAC;IACxB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,CAAC;IACnB,0DAA0D;IAC1D,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,YAAY,GACrB,CAAC,QAAQ,EAAE,MAAM,KAAK,kBAAkB,GAAG,IAAI,CAMjD"}
+{"version":3,"file":"route-matcher.d.ts","sourceRoot":"","sources":["../../src/server/route-matcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAM9B,6DAA6D;AAC7D,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EACP,QAAQ,GACR,SAAS,GACT,WAAW,GACX,oBAAoB,GACpB,OAAO,GACP,MAAM,GACN,cAAc,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IAC3D,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjD,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAE9C,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAC5C;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,YAAY,GACrB,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,CAEzC;AA4MD,2CAA2C;AAC3C,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,IAAI,EAAE,iBAAiB,CAAC;IACxB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,IAAI,EAAE,YAAY,CAAC;IACnB,0DAA0D;IAC1D,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,YAAY,GACrB,CAAC,QAAQ,EAAE,MAAM,KAAK,kBAAkB,GAAG,IAAI,CAMjD"}

package/dist/server/rsc-entry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA2EA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AAkpBD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;8BA9hBpD,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AAgiBhD,wBAAiE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA2EA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AA0nBD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;8BAtgBpD,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AAwgBhD,wBAAiE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/src/search-params/create.ts

@@ -8,8 +8,6 @@
  * Design doc: design/09-typescript.md §"Typed searchParams — search-params.ts"
  */
 
-import { useQueryStates as clientUseQueryStates } from '#/client/use-query-states.js';
-
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -290,16 +288,14 @@ function buildDefinition<T extends Record<string, unknown>>(
   }
 
   // ---- useQueryStates ----
-  // Delegates to the 'use client' implementation from use-query-states.ts.
-  //
-  // In the RSC environment: use-query-states.ts is transformed by the RSC
-  //   plugin into a client reference proxy. Calling it throws — correct,
-  //   because hooks can't run during server component rendering.
-  // In SSR: use-query-states.ts is the real nuqs-backed function. Hooks
-  //   work during SSR's renderToReadableStream, so this works correctly.
-  // On the client: same as SSR — the real function is available.
-  function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {
-    return clientUseQueryStates(codecMap, options, Object.freeze({ ...urlKeys })) as [T, SetParams<T>];
+  // This is a placeholder that will be replaced by the client runtime.
+  // At import time in a server context, calling this throws.
+  // The actual implementation wraps nuqs and lives in @timber-js/app/client.
+  function useQueryStates(_options?: QueryStatesOptions): [T, SetParams<T>] {
+    throw new Error(
+      'useQueryStates() can only be called in a client component. ' +
+        'Import from @timber-js/app/client instead.'
+    );
   }
 
   const definition: SearchParamsDefinition<T> = {

package/src/server/error-formatter.ts

@@ -147,18 +147,6 @@ function extractErrorHint(message: string): string | null {
     return 'A component resolved to undefined/null — check default exports and import paths';
   }
 
-  // "Invalid hook call" — hooks called outside React's render context.
-  // In RSC, this typically means a 'use client' component was executed as a
-  // server component instead of being serialized as a client reference.
-  if (message.includes('Invalid hook call')) {
-    return (
-      'A hook was called outside of a React component render. ' +
-      'If this is a \'use client\' component, ensure the directive is at the very top of the file ' +
-      '(before any imports) and that @vitejs/plugin-rsc is loaded correctly. ' +
-      'Barrel re-exports from non-\'use client\' files do not propagate the directive.'
-    );
-  }
-
   return null;
 }
 

package/src/server/route-matcher.ts

@@ -127,6 +127,43 @@ function matchPathname(root: ManifestSegmentNode, pathname: string): RouteMatch
   };
 }
 
+/**
+ * An effective child flattened through group segments.
+ * Includes the chain of group nodes that must be added to the segments
+ * array before the child itself (to preserve the group → child nesting
+ * that the renderer expects).
+ */
+interface EffectiveChild {
+  child: ManifestSegmentNode;
+  groupChain: ManifestSegmentNode[];
+}
+
+/**
+ * Collect effective children by flattening through group segments.
+ *
+ * Groups are transparent for URL matching — their non-group descendants
+ * are returned with the chain of group nodes that lead to them. This
+ * allows the caller to apply priority ordering (static > dynamic > ...)
+ * across all groups uniformly instead of per-group.
+ */
+function collectEffectiveChildren(
+  node: ManifestSegmentNode,
+  groupChain: ManifestSegmentNode[] = []
+): EffectiveChild[] {
+  const result: EffectiveChild[] = [];
+  for (const child of node.children) {
+    if (child.segmentType === 'group') {
+      // Look through the group — its children become effective children
+      // with this group prepended to their chain
+      const nested = collectEffectiveChildren(child, [...groupChain, child]);
+      result.push(...nested);
+    } else {
+      result.push({ child, groupChain });
+    }
+  }
+  return result;
+}
+
 /**
  * Recursively match URL segments against the segment tree.
  *
@@ -136,8 +173,10 @@ function matchPathname(root: ManifestSegmentNode, pathname: string): RouteMatch
  *   3. Catch-all segments ([...param])
  *   4. Optional catch-all segments ([[...param]])
  *
- * Groups are transparent — they don't consume URL segments but their
- * children are checked as if they were direct children of the parent.
+ * Groups are transparent — they don't consume URL segments. Children
+ * are flattened through groups so that priority ordering applies across
+ * all groups uniformly (a static in group A always beats a dynamic in
+ * group B, regardless of group ordering).
  */
 function matchSegments(
   node: ManifestSegmentNode,
@@ -163,11 +202,12 @@ function matchSegments(
       }
     }
 
-    // Check optional catch-all children (they can match zero segments)
-    for (const child of node.children) {
+    // Check optional catch-all children (direct and through groups)
+    const effective = collectEffectiveChildren(node);
+    for (const { child, groupChain } of effective) {
       if (child.segmentType === 'optional-catch-all') {
         if (child.page || child.route) {
-          segments.push(child);
+          segments.push(...groupChain, child);
           // Zero segments → param is undefined (not set), matching Next.js semantics
           return true;
         }
@@ -180,35 +220,33 @@ function matchSegments(
 
   const part = parts[index];
 
-  // Try children in priority order
+  // Flatten children through groups so priority ordering applies globally
+  // across all groups, not per-group.
+  const effective = collectEffectiveChildren(node);
 
   // 1. Static segments
-  for (const child of node.children) {
+  for (const { child, groupChain } of effective) {
     if (child.segmentType === 'static' && child.segmentName === part) {
+      segments.push(...groupChain);
       if (matchSegments(child, parts, index + 1, segments, params)) {
         return true;
       }
+      // Backtrack group chain
+      segments.length -= groupChain.length;
     }
   }
 
-  // 2. Group segments (transparent — recurse without consuming)
-  for (const child of node.children) {
-    if (child.segmentType === 'group') {
-      if (matchSegments(child, parts, index, segments, params)) {
-        return true;
-      }
-    }
-  }
-
-  // 3. Dynamic segments ([param])
-  for (const child of node.children) {
+  // 2. Dynamic segments ([param])
+  for (const { child, groupChain } of effective) {
     if (child.segmentType === 'dynamic' && child.paramName) {
+      segments.push(...groupChain);
       const prevParam = params[child.paramName];
       params[child.paramName] = part;
       if (matchSegments(child, parts, index + 1, segments, params)) {
         return true;
       }
       // Backtrack
+      segments.length -= groupChain.length;
       if (prevParam !== undefined) {
         params[child.paramName] = prevParam;
       } else {
@@ -217,24 +255,24 @@ function matchSegments(
     }
   }
 
-  // 4. Catch-all segments ([...param])
-  for (const child of node.children) {
+  // 3. Catch-all segments ([...param])
+  for (const { child, groupChain } of effective) {
     if (child.segmentType === 'catch-all' && child.paramName) {
       if (child.page || child.route) {
         const remaining = parts.slice(index);
-        segments.push(child);
+        segments.push(...groupChain, child);
         params[child.paramName] = remaining;
         return true;
       }
     }
   }
 
-  // 5. Optional catch-all segments ([[...param]])
-  for (const child of node.children) {
+  // 4. Optional catch-all segments ([[...param]])
+  for (const { child, groupChain } of effective) {
     if (child.segmentType === 'optional-catch-all' && child.paramName) {
       if (child.page || child.route) {
         const remaining = parts.slice(index);
-        segments.push(child);
+        segments.push(...groupChain, child);
         params[child.paramName] = remaining;
         return true;
       }

package/src/server/rsc-entry/index.ts

@@ -409,30 +409,6 @@ async function renderRoute(
               status: error.status,
             });
           }
-          // Dev diagnostic: detect "Invalid hook call" errors which indicate
-          // a 'use client' component is being executed during RSC rendering
-          // instead of being serialized as a client reference. This happens when
-          // the RSC plugin's transform doesn't detect the directive — e.g., the
-          // directive isn't at the very top of the file, or the component is
-          // re-exported through a barrel file without 'use client'.
-          // See LOCAL-297.
-          if (
-            process.env.NODE_ENV !== 'production' &&
-            error instanceof Error &&
-            error.message.includes('Invalid hook call')
-          ) {
-            console.error(
-              '[timber] A React hook was called during RSC rendering. This usually means a ' +
-                "'use client' component is being executed as a server component instead of " +
-                'being serialized as a client reference.\n\n' +
-                'Common causes:\n' +
-                "  1. The 'use client' directive is not the FIRST statement in the file (before any imports)\n" +
-                "  2. The component is re-exported through a barrel file (index.ts) that lacks 'use client'\n" +
-                '  3. @vitejs/plugin-rsc is not loaded or is misconfigured\n\n' +
-                `Request: ${_req.method} ${new URL(_req.url).pathname}`
-            );
-          }
-
           // Track unhandled errors for pre-flush handling (500 status)
           if (!renderError) {
             renderError = { error, status: 500 };

package/dist/_chunks/use-query-states-Dd9PVu-L.js

@@ -1,102 +0,0 @@
-import { useQueryStates } from "nuqs";
-//#region src/search-params/registry.ts
-var registry = /* @__PURE__ */ new Map();
-/**
-* Register a route's search params definition.
-* Called by the generated route manifest loader when a route's modules load.
-*/
-function registerSearchParams(route, definition) {
-	registry.set(route, definition);
-}
-/**
-* Look up a route's search params definition.
-* Returns undefined if the route hasn't been loaded yet.
-*/
-function getSearchParams(route) {
-	return registry.get(route);
-}
-//#endregion
-//#region src/client/use-query-states.ts
-/**
-* useQueryStates — client-side hook for URL-synced search params.
-*
-* Delegates to nuqs for URL synchronization, batching, React 19 transitions,
-* and throttled URL writes. Bridges timber's SearchParamCodec protocol to
-* nuqs-compatible parsers.
-*
-* Design doc: design/23-search-params.md §"Codec Bridge"
-*/
-/**
-* Bridge a timber SearchParamCodec to a nuqs-compatible SingleParser.
-*
-* nuqs parsers: { parse(string) → T|null, serialize?(T) → string, eq?, defaultValue? }
-* timber codecs: { parse(string|string[]|undefined) → T, serialize(T) → string|null }
-*/
-function bridgeCodec(codec) {
-	return {
-		parse: (v) => codec.parse(v),
-		serialize: (v) => codec.serialize(v) ?? "",
-		defaultValue: codec.parse(void 0),
-		eq: (a, b) => codec.serialize(a) === codec.serialize(b)
-	};
-}
-/**
-* Bridge an entire codec map to nuqs-compatible parsers.
-*/
-function bridgeCodecs(codecs) {
-	const result = {};
-	for (const key of Object.keys(codecs)) result[key] = bridgeCodec(codecs[key]);
-	return result;
-}
-/**
-* Read and write typed search params from/to the URL.
-*
-* Delegates to nuqs internally. The timber nuqs adapter (auto-injected in
-* browser-entry.ts) handles RSC navigation on non-shallow updates.
-*
-* Usage:
-* ```ts
-* // Via a SearchParamsDefinition
-* const [params, setParams] = definition.useQueryStates()
-*
-* // Standalone with inline codecs
-* const [params, setParams] = useQueryStates({
-*   page: fromSchema(z.coerce.number().int().min(1).default(1)),
-* })
-* ```
-*/
-function useQueryStates$1(codecsOrRoute, _options, urlKeys) {
-	let codecs;
-	let resolvedUrlKeys = urlKeys;
-	if (typeof codecsOrRoute === "string") {
-		const definition = getSearchParams(codecsOrRoute);
-		if (!definition) throw new Error(`useQueryStates('${codecsOrRoute}'): no search params registered for this route. Either the route has no search-params.ts file, or it hasn't been loaded yet. For cross-route usage, import the definition explicitly.`);
-		codecs = definition.codecs;
-		resolvedUrlKeys = definition.urlKeys;
-	} else codecs = codecsOrRoute;
-	const bridged = bridgeCodecs(codecs);
-	const nuqsOptions = {};
-	if (resolvedUrlKeys && Object.keys(resolvedUrlKeys).length > 0) nuqsOptions.urlKeys = resolvedUrlKeys;
-	const [values, setValues] = useQueryStates(bridged, nuqsOptions);
-	const setParams = (partial, setOptions) => {
-		const nuqsSetOptions = {};
-		if (setOptions?.shallow !== void 0) nuqsSetOptions.shallow = setOptions.shallow;
-		if (setOptions?.scroll !== void 0) nuqsSetOptions.scroll = setOptions.scroll;
-		if (setOptions?.history !== void 0) nuqsSetOptions.history = setOptions.history;
-		setValues(partial, nuqsSetOptions);
-	};
-	return [values, setParams];
-}
-/**
-* Create a useQueryStates binding for a SearchParamsDefinition.
-* This is used internally by SearchParamsDefinition.useQueryStates().
-*/
-function bindUseQueryStates(definition) {
-	return (options) => {
-		return useQueryStates$1(definition.codecs, options, definition.urlKeys);
-	};
-}
-//#endregion
-export { registerSearchParams as i, useQueryStates$1 as n, getSearchParams as r, bindUseQueryStates as t };
-
-//# sourceMappingURL=use-query-states-Dd9PVu-L.js.map

package/dist/_chunks/use-query-states-Dd9PVu-L.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-query-states-Dd9PVu-L.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 './create.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/create.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  const [values, setValues] = nuqsUseQueryStates(bridged, nuqsOptions);\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,MAAM,CAAC,QAAQ,aAAa,eAAmB,SAAS,YAAY;CAKpE,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"}