@timber-js/app 0.2.0-alpha.192 → 0.2.0-alpha.194

package/dist/plugins/request-dep/index.d.ts

@@ -23,11 +23,11 @@
  * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '../../plugin-context.js';
-import { type ModuleFacts } from './analysis.js';
-export type { ModuleFacts } from './analysis.js';
-export { analyzeModule, usedSources } from './analysis.js';
-export { createOriginResolver } from './origin.js';
+import type { PluginContext } from '../../plugin-context.ts';
+import { type ModuleFacts } from './analysis.ts';
+export type { ModuleFacts } from './analysis.ts';
+export { analyzeModule, usedSources } from './analysis.ts';
+export { createOriginResolver } from './origin.ts';
 export declare function isFrameworkModule(id: string): boolean;
 export interface ReachabilityInput {
     factsMap: ReadonlyMap<string, ModuleFacts>;

package/dist/plugins/request-dep/origin.d.ts

@@ -15,7 +15,7 @@
  *
  * See design/19-client-navigation.md §"Why the slot comparison ignores the query".
  */
-import type { ModuleFacts } from './analysis.js';
+import type { ModuleFacts } from './analysis.ts';
 /** Every specifier the classifier recognises without resolving it. */
 export declare const FRAMEWORK_SOURCES: ReadonlySet<string>;
 export type Origin = 

package/dist/plugins/routing.d.ts

@@ -8,6 +8,6 @@
  * Design docs: 18-build-system.md §"Virtual Modules", 07-routing.md
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '../plugin-context.js';
+import type { PluginContext } from '../plugin-context.ts';
 export declare function timberRouting(ctx: PluginContext): Plugin;
 //# sourceMappingURL=routing.d.ts.map

package/dist/plugins/routing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAYlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA+C1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwRxD"}
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAYlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAoD1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwRxD"}

package/dist/plugins/server-bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-bundle.d.ts","sourceRoot":"","sources":["../../src/plugins/server-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAqCnC,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAuK7C"}
+{"version":3,"file":"server-bundle.d.ts","sourceRoot":"","sources":["../../src/plugins/server-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AA4CnC,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAuK7C"}

package/dist/plugins/shims.d.ts

@@ -14,7 +14,7 @@
  * Design doc: 18-build-system.md §"Shim Map"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '../plugin-context.js';
+import type { PluginContext } from '../plugin-context.ts';
 /**
  * Map from @timber-js/app/<subpath> to relative src/ file paths.
  *

package/dist/plugins/shims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/plugins/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAsB1D;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAqBlD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EA6BhD,CAAC;AA2CF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAkPvD"}
+{"version":3,"file":"shims.d.ts","sourceRoot":"","sources":["../../src/plugins/shims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAsB1D;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAqBlD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EA6BhD,CAAC;AA2CF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAmOvD"}

package/dist/plugins/static-build.d.ts

@@ -8,16 +8,16 @@
  * Design doc: design/11-platform.md §"static output mode"
  */
 import type { Plugin } from 'vite';
-import type { PluginContext } from '../plugin-context.js';
-import type { StaticPageEntry, StaticRedirectEntry } from '../server/static-generator.js';
-import type { RscManifest } from '../shared/rsc-manifest.js';
-import { type FsIdentity } from '../adapters/fs-identity.js';
+import type { PluginContext } from '../plugin-context.ts';
+import type { StaticPageEntry, StaticRedirectEntry } from '../server/static-generator.ts';
+import type { RscManifest } from '../shared/rsc-manifest.ts';
+import { type FsIdentity } from '../adapters/fs-identity.ts';
 /**
  * A single entry in the RSC manifest injected into static HTML.
  * Maps an unhashed `/_rsc/*.rsc` path to its hashed URL, with
  * optional route params inlined to avoid a sidecar fetch.
  */
-export type { RscManifestEntry, RscManifest } from '../shared/rsc-manifest.js';
+export type { RscManifestEntry, RscManifest } from '../shared/rsc-manifest.ts';
 export interface StaticValidationError {
     type: 'dynamic-api';
     file: string;

package/dist/routing/codegen-shared.d.ts

@@ -5,7 +5,7 @@
  * Extracted from `codegen.ts` so `link-codegen.ts` can use the same
  * helpers without a cyclic import.
  */
-import type { ParamEntry } from './codegen-types.js';
+import type { ParamEntry } from './codegen-types.ts';
 /**
  * Compute a relative import specifier for a codec/page file, stripping
  * the .ts/.tsx extension and resolving against the codegen output dir.

package/dist/routing/codegen-write.d.ts

@@ -14,7 +14,7 @@
  *
  * Design docs: 09-typescript.md §"Typed Routes", 18-build-system.md
  */
-import type { RouteTree } from './types.js';
+import type { RouteTree } from './types.ts';
 /**
  * Path (relative to the project root) of the generated route map declaration
  * file, and the name of the root file that `/// <reference>`s it.

package/dist/routing/codegen.d.ts

@@ -7,7 +7,7 @@
  * This runs at build time and in dev (regenerated on file changes).
  * No runtime overhead — purely static type generation.
  */
-import type { RouteTree } from './types.js';
+import type { RouteTree } from './types.ts';
 /** Options for route map generation. */
 export interface CodegenOptions {
     /** Absolute path to the app/ directory. Required for page searchParams detection. */

package/dist/routing/collision-probe.d.ts

@@ -40,7 +40,7 @@
  *
  * See design/07-routing.md §"Comparing Routes by the URLs They Match".
  */
-import type { SegmentNode } from './types.js';
+import type { SegmentNode } from './types.ts';
 /** One page-or-route-bearing node in a collision space. */
 export interface ProbeLeaf {
     /** The file that serves it — what the error message names. */

package/dist/routing/collision-spaces.d.ts

@@ -10,7 +10,7 @@
  *
  * See design/07-routing.md §"Route Collisions".
  */
-import type { SegmentNode } from './types.js';
+import type { SegmentNode } from './types.ts';
 /**
  * Validate that no two pages/routes in one collision space answer the same URL.
  *

package/dist/routing/convention-lint.d.ts

@@ -16,7 +16,7 @@
  *
  * Design doc: 07-routing.md, 10-error-handling.md
  */
-import type { RouteTree } from './types.js';
+import type { RouteTree } from './types.ts';
 export interface ConventionWarning {
     /** Warning ID for deduplication and filtering. */
     id: string;

package/dist/routing/convention-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"convention-lint.d.ts","sourceRoot":"","sources":["../../src/routing/convention-lint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAa,SAAS,EAAe,MAAM,YAAY,CAAC;AAapE,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CA2BpF;AA8UD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAe1E;AAUD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAkCR"}
+{"version":3,"file":"convention-lint.d.ts","sourceRoot":"","sources":["../../src/routing/convention-lint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAa,SAAS,EAAe,MAAM,YAAY,CAAC;AAapE,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAqCpF;AAscD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAe1E;AAUD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAkCR"}

package/dist/routing/index.d.ts

@@ -1,14 +1,14 @@
-export { scanRoutes } from './scanner.js';
-export { generateRouteMap } from './codegen.js';
-export type { CodegenOptions } from './codegen.js';
-export type { RouteTree, SegmentNode, SegmentType, RouteFile, ScannerConfig, InterceptionMarker, } from './types.js';
-export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
-export { collectInterceptionRewrites } from './interception.js';
-export type { InterceptionRewrite } from './interception.js';
-export { classifyUrlSegment, classifySegment } from './segment-classify.js';
-export type { UrlSegment, SegmentClassification } from './segment-classify.js';
-export { collectLeafRoutes } from './walkers.js';
-export type { LeafRoute, CollectLeafRoutesOptions } from './walkers.js';
-export { validateSchemaAgainstRoutes, collectDynamicSegmentsFromTree, } from './schema-validation.js';
-export type { SchemaWarning } from './schema-validation.js';
+export { scanRoutes } from './scanner.ts';
+export { generateRouteMap } from './codegen.ts';
+export type { CodegenOptions } from './codegen.ts';
+export type { RouteTree, SegmentNode, SegmentType, RouteFile, ScannerConfig, InterceptionMarker, } from './types.ts';
+export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.ts';
+export { collectInterceptionRewrites } from './interception.ts';
+export type { InterceptionRewrite } from './interception.ts';
+export { classifyUrlSegment, classifySegment } from './segment-classify.ts';
+export type { UrlSegment, SegmentClassification } from './segment-classify.ts';
+export { collectLeafRoutes } from './walkers.ts';
+export type { LeafRoute, CollectLeafRoutesOptions } from './walkers.ts';
+export { validateSchemaAgainstRoutes, collectDynamicSegmentsFromTree, } from './schema-validation.ts';
+export type { SchemaWarning } from './schema-validation.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/routing/index.js

@@ -1,5 +1,5 @@
-import { n as collectInterceptionRewrites, t as scanRoutes } from "../_chunks/scanner-CAietmj4.js";
+import { n as scanRoutes, r as collectInterceptionRewrites } from "../_chunks/scanner-BRIOmHE2.js";
 import { a as INTERCEPTION_MARKERS, i as DEFAULT_PAGE_EXTENSIONS, n as classifyUrlSegment, t as classifySegment } from "../_chunks/segment-classify-C539Pa2O.js";
-import { n as generateRouteMap } from "../_chunks/file-cache-DmX7OqZP.js";
-import { n as collectDynamicSegmentsFromTree, r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "../_chunks/walkers-BsVLmD1S.js";
+import { n as generateRouteMap } from "../_chunks/file-cache-Dw6BJPG7.js";
+import { n as collectDynamicSegmentsFromTree, r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "../_chunks/walkers-uCu3WW6_.js";
 export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS, classifySegment, classifyUrlSegment, collectDynamicSegmentsFromTree, collectInterceptionRewrites, collectLeafRoutes, generateRouteMap, scanRoutes, validateSchemaAgainstRoutes };

package/dist/routing/interception.d.ts

@@ -16,7 +16,7 @@
  *
  * See design/07-routing.md §"Intercepting Routes"
  */
-import type { SegmentNode, InterceptionMarker } from './types.js';
+import type { SegmentNode, InterceptionMarker } from './types.ts';
 /** Fields shared by both interception shapes. */
 interface InterceptionRewriteBase {
     /**

package/dist/routing/interception.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interception.d.ts","sourceRoot":"","sources":["../../src/routing/interception.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAa,MAAM,YAAY,CAAC;AAQ7E,iDAAiD;AACjD,UAAU,uBAAuB;IAC/B;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,uBAAuB,GAAG,2BAA2B,CAAC;AAExF;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAwB,SAAQ,uBAAuB;IACtE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,2BAA4B,SAAQ,uBAAuB;IAC1E,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAC5C,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,SAAS,WAAW,CAAC,KAAK,CAAC,EAAE,GACtC,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAuBjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,WAAW,GAAG,mBAAmB,EAAE,CAIpF;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAOrE;AAwPD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAEpF;AA4WD;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,kBAAkB,EAC1B,sBAAsB,EAAE,MAAM,GAC7B,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAOhG"}
+{"version":3,"file":"interception.d.ts","sourceRoot":"","sources":["../../src/routing/interception.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAa,MAAM,YAAY,CAAC;AAQ7E,iDAAiD;AACjD,UAAU,uBAAuB;IAC/B;;;OAGG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,uBAAuB,GAAG,2BAA2B,CAAC;AAExF;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAwB,SAAQ,uBAAuB;IACtE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,2BAA4B,SAAQ,uBAAuB;IAC1E,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAC5C,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,SAAS,WAAW,CAAC,KAAK,CAAC,EAAE,GACtC,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAuBjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,WAAW,GAAG,mBAAmB,EAAE,CAIpF;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAOrE;AA4RD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAEpF;AA6WD;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,kBAAkB,EAC1B,sBAAsB,EAAE,MAAM,GAC7B,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAOhG"}

package/dist/routing/link-codegen.d.ts

@@ -22,7 +22,7 @@
  * the discriminated union ends up LAST in resolution order — the
  * overload TS reports against on failure.
  */
-import type { ParamEntry, RouteEntry } from './codegen-types.js';
+import type { ParamEntry, RouteEntry } from './codegen-types.ts';
 /**
  * The `searchParams` prop type, emitted identically on every Link variant
  * — per-route pattern, resolved template, and catch-all.

package/dist/routing/manifest-codegen.d.ts

@@ -7,7 +7,7 @@
  *
  * Task: TIM-1071 item 8
  */
-import type { RouteTree } from './types.js';
+import type { RouteTree } from './types.ts';
 /**
  * Generate the virtual module source for the route manifest.
  *

package/dist/routing/scanner.d.ts

@@ -7,7 +7,20 @@
  * timber.js file conventions. Does NOT handle request matching — this
  * is discovery only.
  */
-import type { RouteTree, ScannerConfig } from './types.js';
+import type { RouteTree, ScannerConfig } from './types.ts';
+/**
+ * Whether a basename + extension pair is a route-convention file the
+ * framework itself imports: page/layout/error/default/denied and
+ * global-error on pageExtensions, middleware/access/route/proxy on
+ * .ts/.tsx/.js/.jsx only, and status-code files (404, 4xx, …) on
+ * pageExtensions or .json — mirroring this scanner's own recognition
+ * rules per family.
+ *
+ * Exported for the analyze classifier so its provisional classification
+ * (design/47 §2) derives from the scanner's real conventions instead of
+ * a duplicate list that can drift.
+ */
+export declare function isRouteConventionFile(base: string, ext: string, pageExtensions?: readonly string[]): boolean;
 /**
  * Scan the app/ directory and build the route tree.
  *

package/dist/routing/scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/routing/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,SAAS,EAIT,aAAa,EAEd,MAAM,YAAY,CAAC;AA2BpB;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,SAAS,CAsDhF"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/routing/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,SAAS,EAIT,aAAa,EAEd,MAAM,YAAY,CAAC;AA2BpB;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,cAAc,GAAE,SAAS,MAAM,EAA4B,GAC1D,OAAO,CAMT;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,SAAS,CAsDhF"}

package/dist/routing/schema-validation.d.ts

@@ -6,7 +6,7 @@
  *
  * Design doc: design/41-global-params.md
  */
-import type { RouteTree } from './types.js';
+import type { RouteTree } from './types.ts';
 export interface SchemaWarning {
     type: 'stale-key' | 'missing-key' | 'bracket-mismatch';
     key: string;

package/dist/routing/segment-classify.d.ts

@@ -21,7 +21,7 @@
  *
  * See design/07-routing.md §"Route Segments"
  */
-import type { InterceptionMarker, SegmentType } from './types.js';
+import type { InterceptionMarker, SegmentType } from './types.ts';
 export type UrlSegment = {
     kind: 'static';
     value: string;

package/dist/routing/segment-codegen.d.ts

@@ -7,7 +7,7 @@
  *
  * Design doc: design/41-global-params.md §The $segment Module
  */
-import type { RouteTree } from './types.js';
+import type { RouteTree } from './types.ts';
 /** Info carried per directory for type generation. */
 export interface SegmentInfo {
     /** The URL route pattern (groups and slots stripped). e.g. '/[artistSlug]/[year]' */

package/dist/routing/segment-keys.d.ts

@@ -21,7 +21,7 @@
  * `ManifestSegmentNode` (request time) — keys depend only on the
  * URL path and the segment classification, never on file payloads.
  */
-import type { CoercedParams } from '../shared/param-value.js';
+import type { CoercedParams } from '../shared/param-value.ts';
 export interface SegmentKeyInput {
     urlPath: string;
     segmentName?: string;

package/dist/routing/slot-placement.d.ts

@@ -8,7 +8,7 @@
  *
  * See design/07-routing.md §"Parallel Routes".
  */
-import type { SegmentNode } from './types.js';
+import type { SegmentNode } from './types.ts';
 /**
  * Reject every parallel slot that no renderer reaches.
  *

package/dist/routing/walkers.d.ts

@@ -13,7 +13,7 @@
  * accumulates `ParamEntry[]` and resolves codec chains) and stays
  * local; the other two now share `collectLeafRoutes` from this file.
  */
-import type { SegmentNode } from './types.js';
+import type { SegmentNode } from './types.ts';
 /** A leaf route discovered while walking the segment tree. */
 export interface LeafRoute<TFile> {
     /** URL path of the leaf (root is "/"). */

package/dist/rsc-runtime/transforms.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Transforms Adapter — Re-exports from @vitejs/plugin-rsc/transforms.
+ *
+ * This module insulates the rest of the framework from direct imports of
+ * @vitejs/plugin-rsc. The plugin is pre-1.0 and its API surface will change.
+ * By routing all transform-helper imports through this single file, a
+ * breaking upstream change only requires updating one place.
+ *
+ * Keep this as thin pass-through re-exports — the value is the single choke
+ * point, not abstraction.
+ */
+export { hasDirective } from '@vitejs/plugin-rsc/transforms';
+//# sourceMappingURL=transforms.d.ts.map

package/dist/rsc-runtime/transforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms.d.ts","sourceRoot":"","sources":["../../src/rsc-runtime/transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/schema-bridge.d.ts

@@ -23,7 +23,7 @@
  *
  * Design doc: design/23a-search-params-triage.md §"Unify Codec<T> type"
  */
-import type { Codec } from './codec.js';
+import type { Codec } from './codec.ts';
 /** Minimal Standard Schema interface for auto-detection. */
 export interface StandardSchemaV1<Output = unknown> {
     '~standard': {

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

@@ -9,8 +9,8 @@
  *
  * Design doc: design/23-search-params.md §"defineSearchParams — The Factory"
  */
-import type { StandardSchemaV1 } from '../schema-bridge.js';
-import type { Codec } from '../codec.js';
+import type { StandardSchemaV1 } from '../schema-bridge.ts';
+import type { Codec } from '../codec.ts';
 /**
  * A codec that converts between URL string values and typed values.
  *
@@ -153,7 +153,7 @@ export interface SearchParamsDefinition<T extends Record<string, unknown>> {
      */
     readonly _type?: T;
 }
-export type { StandardSchemaV1 } from '../schema-bridge.js';
+export type { StandardSchemaV1 } from '../schema-bridge.ts';
 /**
  * Extract a Standard Schema's declared *input* type from its optional
  * `~standard.types` property (part of the Standard Schema spec; Zod, Valibot,

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

@@ -1,4 +1,4 @@
-export type { SearchParamCodec, SearchParamCodecWithUrlKey, TotalSearchParamCodec, InferCodec, InferField, CodecMap, SearchParamsDefinition, SetParams, SetParamsOptions, QueryStatesOptions, StandardSchemaV1, } from './define.js';
-export { defineSearchParams } from './define.js';
-export { withDefault, withUrlKey } from './wrappers.js';
+export type { SearchParamCodec, SearchParamCodecWithUrlKey, TotalSearchParamCodec, InferCodec, InferField, CodecMap, SearchParamsDefinition, SetParams, SetParamsOptions, QueryStatesOptions, StandardSchemaV1, } from './define.ts';
+export { defineSearchParams } from './define.ts';
+export { withDefault, withUrlKey } from './wrappers.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/search-params/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/search-params/define.ts","../../src/search-params/wrappers.ts"],"sourcesContent":["/**\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, isStandardSchema, isCodec } from '../schema-bridge.js';\nimport type { StandardSchemaV1 } from '../schema-bridge.js';\nimport type { Codec } from '../codec.js';\n// Server-only reference for .get() — avoids pulling server ALS into client\n// bundles. In client environments, .get() throws before reaching this code\n// path. The slot lives in its own leaf module so that `request-context.ts`\n// can register the getter without importing this file, which would drag\n// `nuqs` into every server entry (TIM-1298). See shared/als-slots.ts.\nimport { getSearchParamsFromAls } from '../shared/als-slots.js';\nimport { parseTotal } from './parse-total.js';\nimport { serializedEqual } from './serialize-equal.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A codec that converts between URL string values and typed values.\n *\n * `parse` receives the RAW url value: `string | string[] | undefined`.\n * A codec must be TOTAL over that domain — return a default rather than\n * throwing on an absent or repeated param.\n *\n * A codec whose own `parse` covers only a PRESENT, SINGLE-VALUED param\n * may publish `parseServerSide` instead, and timber calls that. nuqs\n * parsers do exactly this, which is how they become total here: absent →\n * `null` (or their `withDefault` value), repeated → the first value, and\n * a throw from the inner parse → `null`. See\n * design/23-search-params.md §'nuqs parsers, made total',\n * `parse-total.ts`, and tests/nuqs-codec-boundary.test.ts (TIM-1350).\n *\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected\n * by defineSearchParams and wrapped via fromSchema; those ARE total\n * through `parse` and are called that way.\n */\nexport interface SearchParamCodec<T> extends Omit<Codec<T>, 'serialize'> {\n  /**\n   * Typed value → URL string(s). Return `null` to omit/clear.\n   *\n   * A codec MAY return `string[]` to emit repeated keys (`?tag=a&tag=b`).\n   * `buildSearchParams` appends one `key=value` entry per array element;\n   * the nuqs bridge forwards the array to nuqs, which does the same.\n   * Codecs that always produce a single value return a plain string.\n   *\n   * Wider than `Codec<T>.serialize` (`string | null`) because search params\n   * have a repeated-key concept that cookies and segment params do not.\n   */\n  serialize(value: T): string | string[] | null;\n  /** Optional URL key alias, set by withUrlKey(). */\n  urlKey?: string;\n  /**\n   * Optional TOTAL entry point over `string | string[] | undefined`,\n   * preferred over `parse` wherever timber invokes a codec. Declared here\n   * so the protocol is typed rather than duck-checked at each wrapper:\n   * anything that reconstructs a codec has to carry it, and a wrapper\n   * cannot carry a property the interface does not admit.\n   *\n   * It returns `T`, not `T | null`. This is the entry point timber calls,\n   * so whatever it returns IS the field's type — admitting a `null` the\n   * field type did not carry would let `SearchParamCodec<string>` produce\n   * `null` for an absent param under a non-nullable annotation. A codec\n   * whose absent-case answer is `null` declares that in `T`, exactly as a\n   * bare nuqs parser does: `parseAsString` is a `SearchParamCodec<string |\n   * null>` here, never a `SearchParamCodec<string>`.\n   *\n   * nuqs parser builders satisfy this. See parse-total.ts.\n   */\n  parseServerSide?(value: string | string[] | undefined): T;\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   * Get typed search params from the current request context (ALS-backed).\n   *\n   * Server-only, sync. Reads getSearchParams() from ALS and parses through codecs.\n   * Throws on client.\n   *\n   * ```tsx\n   * // app/products/page.tsx\n   * import { searchParams } from './search-params'\n   * export default function Page() {\n   *   const { page, category } = searchParams.get()\n   * }\n   * ```\n   */\n  get(): 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, SearchParamField>>(\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  /**\n   * Serialize values to a query string (no leading '?'), omitting defaults\n   * and applying `withUrlKey` aliases. This is the value to pass to\n   * `<Link searchParams={...}>`.\n   *\n   * Returns a **string**, not a `URLSearchParams`. A `<Link>` prop crosses\n   * the RSC Flight boundary, and `URLSearchParams` is iterable — React\n   * serializes it as an entries array, which arrives as `[['pg','2'], …]`\n   * and renders as `?0=pg&0=2`. A string survives intact.\n   */\n  buildSearchParams(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  /** 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// StandardSchemaV1 is imported from schema-bridge.ts — single source of truth.\n// Re-export for consumers that import it from this module.\nexport type { StandardSchemaV1 } from '../schema-bridge.js';\n\n// ---------------------------------------------------------------------------\n// Type-level helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract a Standard Schema's declared *input* type from its optional\n * `~standard.types` property (part of the Standard Schema spec; Zod, Valibot,\n * and ArkType all declare it at the type level). Falls back to `never` when\n * the schema doesn't declare types (e.g. hand-written schemas): with no\n * metadata we can't know whether the schema handles `undefined`, so InferField\n * widens conservatively rather than risk a type lie.\n */\ntype InferSchemaInput<V> = V extends { '~standard': { types?: infer TS } }\n  ? [NonNullable<TS>] extends [{ input: infer I }]\n    ? I\n    : never\n  : never;\n\n/**\n * Infer the output type from either a SearchParamCodec or a StandardSchemaV1.\n *\n * A codec publishing `parseServerSide` is read through THAT signature, not\n * through `parse` — it is the entry point timber actually calls, and it is\n * the one that tells the truth about absent input. A bare `parseAsString`\n * declares `parse(value: string): string` but answers `null` for a missing\n * param, so the field is `string | null`; `parseAsInteger.withDefault(1)`\n * narrows its own `parseServerSide` to `NonNullable<number>` and the field\n * stays `number`. Reading `parse` instead produced a non-nullable type for\n * a nullable field (TIM-1350).\n *\n * The match is structural, not nuqs-specific: any codec declaring that\n * signature opts into being read through it, which is exactly the contract\n * `parseTotal` applies at runtime. The two must stay in step — a type\n * inferred from `parse` while the runtime calls `parseServerSide` is the\n * lie this branch exists to remove.\n *\n * Schemas whose input type rejects `undefined` (e.g. bare `z.string()`, whose\n * input is `string`) are implicitly optional: the URL might not contain the\n * param, and fromSchema returns `undefined` when the schema rejects absent\n * input and has no default. The output type widens to `T | undefined` so the\n * type doesn't lie. Schemas that accept `undefined` input (`.optional()`,\n * `.default()`) keep their declared output type.\n *\n * Limitation: `z.coerce.*` schemas declare input `unknown`, which accepts\n * `undefined` at the type level — so a coerce schema without `.default()`\n * keeps its narrow output type even though absent input yields `undefined`\n * at runtime. Add `.default()` to coerce schemas for accurate types.\n */\nexport type InferField<V> = V extends {\n  parseServerSide(value: string | string[] | undefined): infer R;\n}\n  ? R\n  : V extends SearchParamCodec<infer T>\n    ? T\n    : V extends StandardSchemaV1<infer T>\n      ? undefined extends InferSchemaInput<V>\n        ? T\n        : T | undefined\n      : never;\n\n/**\n * A codec whose total entry point is `parseServerSide`, even when `parse`\n * has a narrower signature. nuqs multi parsers (`parseAsNativeArrayOf`) have\n * `parse(value: readonly string[])` — too narrow for `SearchParamCodec`'s\n * `parse(string | string[] | undefined)` — but their `parseServerSide`\n * covers the full domain. Timber never calls `parse` directly on these;\n * `parseTotal` always reaches `parseServerSide` first (TIM-1355).\n */\nexport interface TotalSearchParamCodec<T> {\n  parseServerSide(value: string | string[] | undefined): T;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  parse(...args: any[]): any;\n  serialize(value: T): string | string[] | null;\n  urlKey?: string;\n}\n\n/** Acceptable field value for defineSearchParams: a codec, a total codec, or a Standard Schema. */\nexport type SearchParamField<T = unknown> =\n  | SearchParamCodec<T>\n  | TotalSearchParamCodec<T>\n  | 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> = Object.create(null);\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 *\n * Goes through `parseTotal` for the same reason request-time parsing does:\n * a nuqs parser's own `parse` throws on absent input, and this is the\n * absent case by construction.\n *\n * **A codec with no value for an absent param has no default to omit**,\n * and `null` is returned rather than `serialize(null)`. Serializing it\n * makes the \"no value\" case collide with a real one: `parseAsInteger`\n * serializes `null` as the string `'null'`, so `buildSearchParams({ q:\n * 'null' })` would silently drop a legitimate value (before TIM-1350 the\n * absent parse was `undefined` and the swallowed input was the string\n * `'undefined'` — same defect, a less likely input). Nothing is lost:\n * `buildSearchParams` already skips a field whose `serialize` returns\n * `null`, so a codec that encodes \"no value\" as an omission behaves\n * identically, and one that encodes it as a real query value now writes\n * it instead of dropping it.\n *\n * Codecs are documented to return a default rather than throw, but a\n * hand-written codec that throws on absent input must not turn definition\n * into a crash — treat its default as null (nothing to omit). `serialize`\n * is inside the try for the same reason.\n *\n * Typed `SearchParamCodec<unknown>` rather than generic on purpose: the\n * absent-input value is whatever the codec's total entry point returns,\n * which for a nuqs parser is `T | null` while its `serialize` declares\n * `T`. Widening to `unknown` states that honestly instead of casting.\n */\nfunction getDefaultSerialized(codec: SearchParamCodec<unknown>): string | string[] | null {\n  try {\n    const absent = parseTotal(codec, undefined);\n    return absent === null || absent === undefined ? null : codec.serialize(absent);\n  } catch {\n    return null;\n  }\n}\n\n// isStandardSchema and isCodec are imported from schema-bridge.ts.\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 *\n * The returned codec is typed as `SearchParamCodec<unknown>` because the\n * codec map uses that type. At runtime, the value may be a `Codec<T>` from\n * `fromSchema` (whose serialize returns `string | null`) or a nuqs parser\n * (whose serialize returns `string | string[] | null`). Both are safe\n * because `buildSearchParams` handles the union.\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    const urlKey = (value as SearchParamCodec<unknown>).urlKey;\n    return { codec: value as SearchParamCodec<unknown>, urlKey };\n  }\n\n  // Auto-detect Standard Schema. Schemas that reject undefined input and\n  // have no default are implicitly optional: fromSchema returns undefined\n  // for absent params, and InferField widens the output type to\n  // T | undefined. design/23-search-params.md §\"Implicit Optionality\"\n  if (isStandardSchema(value)) {\n    return { codec: fromSchema(value) as SearchParamCodec<unknown> };\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// 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 */\n/**\n * Overload: accept a Standard Schema object schema (e.g., z.object({...})).\n *\n * The schema must have a `.shape` property whose values are themselves\n * Standard Schema objects. Each shape property becomes a field codec\n * via fromSchema().\n *\n * ```ts\n * const searchParams = defineSearchParams(\n *   z.object({ page: z.coerce.number().default(1), q: z.string().optional() })\n * )\n * ```\n */\nexport function defineSearchParams<\n  S extends StandardSchemaV1<Record<string, unknown>> & {\n    shape: Record<string, StandardSchemaV1<unknown>>;\n  },\n>(\n  schema: S\n): SearchParamsDefinition<{ [K in keyof S['shape'] & string]: InferField<S['shape'][K]> }>;\n\n/**\n * Overload: accept a map of codecs and/or Standard Schema objects.\n */\nexport function defineSearchParams<C extends Record<string, SearchParamField>>(\n  codecs: C\n): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }>;\n\nexport function defineSearchParams(\n  codecsOrSchema:\n    | Record<string, SearchParamField>\n    | (StandardSchemaV1<unknown> & { shape: Record<string, StandardSchemaV1<unknown>> })\n): SearchParamsDefinition<Record<string, unknown>> {\n  // Detect Standard Schema object with .shape (e.g., z.object(...))\n  if (isStandardSchema(codecsOrSchema) && hasShape(codecsOrSchema)) {\n    const fieldCodecs: Record<string, SearchParamField> = {};\n    for (const [key, fieldSchema] of Object.entries(codecsOrSchema.shape)) {\n      if (isStandardSchema(fieldSchema)) {\n        fieldCodecs[key] = fieldSchema;\n      } else {\n        throw new Error(\n          `[timber] defineSearchParams: field '${key}' in schema.shape is not a Standard Schema. ` +\n            `All shape properties must be Standard Schema objects (Zod, Valibot, ArkType).`\n        );\n      }\n    }\n    return defineSearchParamsFromMap(fieldCodecs);\n  }\n\n  return defineSearchParamsFromMap(codecsOrSchema as Record<string, SearchParamField>);\n}\n\n/** Check if a schema has a .shape property with object-type values. */\nfunction hasShape(schema: unknown): schema is { shape: Record<string, unknown> } {\n  return (\n    typeof schema === 'object' &&\n    schema !== null &&\n    'shape' in schema &&\n    typeof (schema as { shape: unknown }).shape === 'object' &&\n    (schema as { shape: unknown }).shape !== null\n  );\n}\n\nfunction defineSearchParamsFromMap(\n  codecs: Record<string, SearchParamField>\n): SearchParamsDefinition<Record<string, unknown>> {\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  return buildDefinition(resolvedCodecs as unknown as CodecMap<Record<string, unknown>>, 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 | 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] = parseTotal(codecMap[prop as keyof T] as SearchParamCodec<unknown>, 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  // ---- buildSearchParams ----\n  //\n  // Returns a query string. It used to have a URLSearchParams-returning\n  // sibling (`toSearchParams`) that `<Link>` consumed; that shape cannot\n  // cross the RSC Flight boundary (see the interface docstring), and having\n  // two methods produce the same query two ways was a drift waiting to\n  // happen. One method now.\n  function buildSearchParams(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\n      // TIM-1354: serialize may not be total over null — nuqs parsers like\n      // parseAsIsoDate throw TypeError on null (null.toISOString()). Catch\n      // TypeError and omit, matching what setParams does on the client.\n      // Only TypeError — a deliberate throw (redirect(), notFound()) from a\n      // codec's serialize must propagate, not be silently swallowed.\n      let serialized: string | string[] | null;\n      try {\n        serialized = codec.serialize(values[prop as keyof T] as unknown);\n      } catch (error) {\n        if (error instanceof TypeError) continue;\n        throw error;\n      }\n\n      if (serialized === null) continue;\n      // Omit if serialized value matches the default\n      if (serializedEqual(serialized, defaultSerialized[prop])) continue;\n\n      // TIM-1353: string[] → repeated keys (?tag=a&tag=b)\n      const urlKey = encodeURIComponent(getUrlKey(prop));\n      if (Array.isArray(serialized)) {\n        for (const entry of serialized) {\n          parts.push(`${urlKey}=${encodeURIComponent(entry)}`);\n        }\n      } else {\n        parts.push(`${urlKey}=${encodeURIComponent(serialized)}`);\n      }\n    }\n\n    return parts.join('&');\n  }\n\n  // ---- href ----\n  function href(pathname: string, values: Partial<T>): string {\n    const qs = buildSearchParams(values);\n    return qs ? `${pathname}?${qs}` : pathname;\n  }\n\n  // ---- extend ----\n  function extend<U extends Record<string, SearchParamField>>(\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      // Explicit guard — TypeScript prevents this, but JS callers and\n      // casts reach here, and \"Cannot read properties of undefined\n      // (reading 'serialize')\" is no help (TIM-1066).\n      if (!(key in codecMap)) {\n        throw new Error(\n          `[timber] pick('${key}'): unknown key. ` +\n            `Available keys: ${Object.keys(codecMap)\n              .map((k) => `'${k}'`)\n              .join(', ')}.`\n        );\n      }\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  // ---- get ----\n  // ALS-backed: reads getSearchParams() from the current request context\n  // and parses through codecs. Server-only, sync.\n  function get(): T {\n    if (typeof window !== 'undefined') {\n      throw new Error(\n        '[timber] searchParams.get() is server-only. ' +\n          'Use searchParams.useQueryStates() on the client.'\n      );\n    }\n    const raw = getSearchParamsFromAls();\n    return parseSync(raw);\n  }\n\n  const definition: SearchParamsDefinition<T> = {\n    parse,\n    get,\n    useQueryStates,\n    extend,\n    pick,\n    href,\n    buildSearchParams,\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 {\n  InferField,\n  SearchParamCodec,\n  SearchParamCodecWithUrlKey,\n  SearchParamField,\n} from './define.js';\nimport { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.js';\nimport { parseTotal } from './parse-total.js';\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. The output type becomes\n * non-nullable, and the wrapper is TOTAL over `string | string[] |\n * undefined` even when the inner codec is not.\n *\n * The default is substituted for `null` — the documented \"no value\"\n * answer — and for `undefined`, which is what an implicitly-optional\n * Standard Schema field and a bare `parseAsString` produce for an absent\n * param. Substituting only for `null` left a field typed non-nullable\n * `string` holding `undefined` (TIM-1350).\n *\n * The inner codec is invoked through `parseTotal`, so a nuqs parser gets\n * its own normalization (absent → null, repeated → first value, inner\n * throw → null) before either check applies. That is what makes\n * `withDefault(parseAsBoolean, false)` total; the wrapper itself does NOT\n * catch. A throw from a codec is a deliberate signal — `fromSchema` throws\n * on an async schema, and an app codec may `redirect()` or `notFound()` on\n * a value it refuses — and swallowing it would convert a loud failure into\n * a permanently-default field. design/09 §\"The SearchParamCodec Protocol\":\n * a codec that throws bubbles as a render-phase error, by design.\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 *\n * The signature strips BOTH nullish constituents from the result, not just\n * `null`, because the runtime substitutes for both. An implicitly-optional\n * schema field is a `SearchParamCodec<string | undefined>`, and wrapping it\n * used to yield `SearchParamCodec<string | undefined>` — a field the\n * wrapper guarantees is always present, still typed as maybe-absent.\n */\nexport function withDefault<T>(\n  codec: SearchParamCodec<T | null | undefined>,\n  defaultValue: NonNullable<T>\n): SearchParamCodec<NonNullable<T>> {\n  // A wrapper that rebuilds a codec from two methods drops everything else\n  // the codec carries. `withUrlKey` lost `parseServerSide` that way; this\n  // one lost `urlKey`, so `withDefault(withUrlKey(parseAsInteger, 'p'), 1)`\n  // silently read `?page=` instead of `?p=`. Carry it explicitly rather\n  // than spreading: this wrapper's own `parse` IS the total entry point,\n  // and re-publishing the inner `parseServerSide` would let `parseTotal`\n  // reach past it and skip the default entirely.\n  const wrapped: SearchParamCodec<NonNullable<T>> = {\n    parse(value: string | string[] | undefined): NonNullable<T> {\n      const result = parseTotal(codec, value);\n      return result === null || result === undefined ? defaultValue : result;\n    },\n    serialize(value: NonNullable<T>): string | string[] | null {\n      return codec.serialize(value);\n    },\n  };\n  if (codec.urlKey !== undefined) wrapped.urlKey = codec.urlKey;\n  return wrapped;\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<F extends SearchParamField>(\n  codecOrSchema: F,\n  urlKey: string\n): SearchParamCodecWithUrlKey<InferField<F>> {\n  type T = InferField<F>;\n  // Auto-detect Standard Schema (Zod, Valibot, ArkType) and wrap. Schemas\n  // that reject undefined input are implicitly optional — fromSchema returns\n  // undefined for absent params, and InferField widens the type to include\n  // undefined. design/23-search-params.md §\"Implicit Optionality\"\n  const codec: SearchParamCodec<T> = isCodec(codecOrSchema)\n    ? (codecOrSchema as SearchParamCodec<T>)\n    : isStandardSchema(codecOrSchema)\n      ? (fromSchema(codecOrSchema) as SearchParamCodec<T>)\n      : (codecOrSchema as SearchParamCodec<T>);\n  // Carry the total entry point, bound like the other two methods. A\n  // codec's totality lives in a THIRD property, `parseServerSide` (see\n  // parse-total.ts); picking only `parse`/`serialize` silently produced a\n  // non-total alias, so `withUrlKey(parseAsBoolean, 'b')` threw on an\n  // absent param while the bare parser did not (TIM-1350).\n  //\n  // Bound explicitly rather than spread: a spread copies own enumerable\n  // properties only, so a class-based codec — whose `parse` and\n  // `serialize` this wrapper already reaches through the prototype —\n  // would have kept its methods and lost exactly the one that makes it\n  // total. Three properties, one rule, no dependence on how the inner\n  // codec was constructed.\n  const wrapped: SearchParamCodecWithUrlKey<T> = {\n    parse: codec.parse.bind(codec),\n    serialize: codec.serialize.bind(codec),\n    urlKey,\n  };\n  if (typeof codec.parseServerSide === 'function') {\n    wrapped.parseServerSide = codec.parseServerSide.bind(codec);\n  }\n  return wrapped;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAwRA,SAAS,aACP,KAC+C;CAC/C,IAAI,eAAe,iBAAiB;EAClC,MAAM,SAAwD,OAAO,OAAO,IAAI;EAChF,KAAK,MAAM,OAAO,IAAI,IAAI,IAAI,KAAK,CAAC,GAAG;GACrC,MAAM,SAAS,IAAI,OAAO,GAAG;GAC7B,OAAO,OAAO,OAAO,WAAW,IAAI,OAAO,KAAK;EAClD;EACA,OAAO;CACT;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAS,qBAAqB,OAA4D;CACxF,IAAI;EACF,MAAM,SAAS,WAAW,OAAO,KAAA,CAAS;EAC1C,OAAO,WAAW,QAAQ,WAAW,KAAA,IAAY,OAAO,MAAM,UAAU,MAAM;CAChF,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;;AAcA,SAAS,aACP,WACA,OACuD;CAEvD,IAAI,QAAQ,KAAK,GAEf,OAAO;EAAE,OAAO;EAAoC,QADpC,MAAoC;CACO;CAO7D,IAAI,iBAAiB,KAAK,GACxB,OAAO,EAAE,OAAO,WAAW,KAAK,EAA+B;CAGjE,MAAM,IAAI,MACR,uCAAuC,UAAU,sJAGnD;AACF;AAmDA,SAAgB,mBACd,gBAGiD;CAEjD,IAAI,iBAAiB,cAAc,KAAK,SAAS,cAAc,GAAG;EAChE,MAAM,cAAgD,CAAC;EACvD,KAAK,MAAM,CAAC,KAAK,gBAAgB,OAAO,QAAQ,eAAe,KAAK,GAClE,IAAI,iBAAiB,WAAW,GAC9B,YAAY,OAAO;OAEnB,MAAM,IAAI,MACR,uCAAuC,IAAI,0HAE7C;EAGJ,OAAO,0BAA0B,WAAW;CAC9C;CAEA,OAAO,0BAA0B,cAAkD;AACrF;;AAGA,SAAS,SAAS,QAA+D;CAC/E,OACE,OAAO,WAAW,YAClB,WAAW,QACX,WAAW,UACX,OAAQ,OAA8B,UAAU,YAC/C,OAA8B,UAAU;AAE7C;AAEA,SAAS,0BACP,QACiD;CACjD,MAAM,iBAA4D,CAAC;CACnE,MAAM,UAAkC,CAAC;CAEzC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,GAAG;EACjD,MAAM,WAAW,aAAa,KAAK,KAAyB;EAC5D,eAAe,OAAO,SAAS;EAC/B,IAAI,SAAS,QACX,QAAQ,OAAO,SAAS;CAE5B;CAEA,OAAO,gBAAgB,gBAAgE,OAAO;AAChG;;;;AASA,SAAS,gBACP,UACA,SAC2B;CAE3B,MAAM,oBAA8D,CAAC;CACrE,KAAK,MAAM,OAAO,OAAO,KAAK,QAAQ,GACpC,kBAAkB,OAAO,qBAAqB,SAAS,IAAe;CAGxE,SAAS,UAAU,MAAsB;EACvC,OAAO,QAAQ,SAAS;CAC1B;CAGA,SAAS,UAAU,KAAyE;EAC1F,MAAM,aAAa,aAAa,GAAG;EACnC,MAAM,SAAkC,CAAC;EAEzC,KAAK,MAAM,QAAQ,OAAO,KAAK,QAAQ,GAAG;GAExC,MAAM,WAAW,WADF,UAAU,IACG;GAC5B,OAAO,QAAQ,WAAW,SAAS,OAA+C,QAAQ;EAC5F;EAEA,OAAO;CACT;CAQA,SAAS,MACP,KAIgB;EAChB,IAAI,eAAe,SACjB,OAAO,IAAI,KAAK,SAAS;EAE3B,OAAO,UAAU,GAAG;CACtB;CASA,SAAS,kBAAkB,QAA4B;EACrD,MAAM,QAAkB,CAAC;EAEzB,KAAK,MAAM,QAAQ,OAAO,KAAK,QAAQ,GAAG;GACxC,IAAI,EAAE,QAAQ,SAAS;GACvB,MAAM,QAAQ,SAAS;GAOvB,IAAI;GACJ,IAAI;IACF,aAAa,MAAM,UAAU,OAAO,KAA2B;GACjE,SAAS,OAAO;IACd,IAAI,iBAAiB,WAAW;IAChC,MAAM;GACR;GAEA,IAAI,eAAe,MAAM;GAEzB,IAAI,gBAAgB,YAAY,kBAAkB,KAAK,GAAG;GAG1D,MAAM,SAAS,mBAAmB,UAAU,IAAI,CAAC;GACjD,IAAI,MAAM,QAAQ,UAAU,GAC1B,KAAK,MAAM,SAAS,YAClB,MAAM,KAAK,GAAG,OAAO,GAAG,mBAAmB,KAAK,GAAG;QAGrD,MAAM,KAAK,GAAG,OAAO,GAAG,mBAAmB,UAAU,GAAG;EAE5D;EAEA,OAAO,MAAM,KAAK,GAAG;CACvB;CAGA,SAAS,KAAK,UAAkB,QAA4B;EAC1D,MAAM,KAAK,kBAAkB,MAAM;EACnC,OAAO,KAAK,GAAG,SAAS,GAAG,OAAO;CACpC;CAGA,SAAS,OACP,WACkE;EAIlE,MAAM,oBAA+D,CAAC;EACtE,MAAM,aAAqC,CAAC;EAC5C,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,GAAG;GACpD,MAAM,WAAW,aAAa,KAAK,KAAyB;GAC5D,kBAAkB,OAAO,SAAS;GAClC,IAAI,SAAS,QACX,WAAW,OAAO,SAAS;EAE/B;EAUA,OAAO,gBAA0B;GAP/B,GAAG;GACH,GAAG;EAM4B,GAAgB;GAFC,GAAG;GAAS,GAAG;EAEhB,CAAe;CAClE;CAGA,SAAS,KAAiC,GAAG,MAA+C;EAC1F,MAAM,eAA0D,CAAC;EACjE,MAAM,gBAAwC,CAAC;EAE/C,KAAK,MAAM,OAAO,MAAM;GAItB,IAAI,EAAE,OAAO,WACX,MAAM,IAAI,MACR,kBAAkB,IAAI,mCACD,OAAO,KAAK,QAAQ,CAAC,CACrC,KAAK,MAAM,IAAI,EAAE,EAAE,CAAC,CACpB,KAAK,IAAI,EAAE,EAClB;GAEF,aAAa,OAAO,SAAS;GAC7B,IAAI,OAAO,SACT,cAAc,OAAO,QAAQ;EAEjC;EAEA,OAAO,gBACL,cACA,aACF;CACF;CAWA,SAAS,iBAAe,SAAiD;EACvE,OAAO,eAAqB,UAAU,SAAS,OAAO,OAAO,EAAE,GAAG,QAAQ,CAAC,CAAC;CAI9E;CAKA,SAAS,MAAS;EAChB,IAAI,OAAO,WAAW,aACpB,MAAM,IAAI,MACR,8FAEF;EAGF,OAAO,UADK,uBACK,CAAG;CACtB;CAcA,OAAO;EAXL;EACA;EACA,gBAAA;EACA;EACA;EACA;EACA;EACA,QAAQ;EACR,SAAS,OAAO,OAAO,EAAE,GAAG,QAAQ,CAAC;CAGhC;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACvmBA,SAAgB,YACd,OACA,cACkC;CAQlC,MAAM,UAA4C;EAChD,MAAM,OAAsD;GAC1D,MAAM,SAAS,WAAW,OAAO,KAAK;GACtC,OAAO,WAAW,QAAQ,WAAW,KAAA,IAAY,eAAe;EAClE;EACA,UAAU,OAAiD;GACzD,OAAO,MAAM,UAAU,KAAK;EAC9B;CACF;CACA,IAAI,MAAM,WAAW,KAAA,GAAW,QAAQ,SAAS,MAAM;CACvD,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,WACd,eACA,QAC2C;CAM3C,MAAM,QAA6B,QAAQ,aAAa,IACnD,gBACD,iBAAiB,aAAa,IAC3B,WAAW,aAAa,IACxB;CAaP,MAAM,UAAyC;EAC7C,OAAO,MAAM,MAAM,KAAK,KAAK;EAC7B,WAAW,MAAM,UAAU,KAAK,KAAK;EACrC;CACF;CACA,IAAI,OAAO,MAAM,oBAAoB,YACnC,QAAQ,kBAAkB,MAAM,gBAAgB,KAAK,KAAK;CAE5D,OAAO;AACT"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/search-params/define.ts","../../src/search-params/wrappers.ts"],"sourcesContent":["/**\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.ts';\nimport { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.ts';\nimport type { StandardSchemaV1 } from '../schema-bridge.ts';\nimport type { Codec } from '../codec.ts';\n// Server-only reference for .get() — avoids pulling server ALS into client\n// bundles. In client environments, .get() throws before reaching this code\n// path. The slot lives in its own leaf module so that `request-context.ts`\n// can register the getter without importing this file, which would drag\n// `nuqs` into every server entry (TIM-1298). See shared/als-slots.ts.\nimport { getSearchParamsFromAls } from '../shared/als-slots.ts';\nimport { parseTotal } from './parse-total.ts';\nimport { serializedEqual } from './serialize-equal.ts';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A codec that converts between URL string values and typed values.\n *\n * `parse` receives the RAW url value: `string | string[] | undefined`.\n * A codec must be TOTAL over that domain — return a default rather than\n * throwing on an absent or repeated param.\n *\n * A codec whose own `parse` covers only a PRESENT, SINGLE-VALUED param\n * may publish `parseServerSide` instead, and timber calls that. nuqs\n * parsers do exactly this, which is how they become total here: absent →\n * `null` (or their `withDefault` value), repeated → the first value, and\n * a throw from the inner parse → `null`. See\n * design/23-search-params.md §'nuqs parsers, made total',\n * `parse-total.ts`, and tests/nuqs-codec-boundary.test.ts (TIM-1350).\n *\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected\n * by defineSearchParams and wrapped via fromSchema; those ARE total\n * through `parse` and are called that way.\n */\nexport interface SearchParamCodec<T> extends Omit<Codec<T>, 'serialize'> {\n  /**\n   * Typed value → URL string(s). Return `null` to omit/clear.\n   *\n   * A codec MAY return `string[]` to emit repeated keys (`?tag=a&tag=b`).\n   * `buildSearchParams` appends one `key=value` entry per array element;\n   * the nuqs bridge forwards the array to nuqs, which does the same.\n   * Codecs that always produce a single value return a plain string.\n   *\n   * Wider than `Codec<T>.serialize` (`string | null`) because search params\n   * have a repeated-key concept that cookies and segment params do not.\n   */\n  serialize(value: T): string | string[] | null;\n  /** Optional URL key alias, set by withUrlKey(). */\n  urlKey?: string;\n  /**\n   * Optional TOTAL entry point over `string | string[] | undefined`,\n   * preferred over `parse` wherever timber invokes a codec. Declared here\n   * so the protocol is typed rather than duck-checked at each wrapper:\n   * anything that reconstructs a codec has to carry it, and a wrapper\n   * cannot carry a property the interface does not admit.\n   *\n   * It returns `T`, not `T | null`. This is the entry point timber calls,\n   * so whatever it returns IS the field's type — admitting a `null` the\n   * field type did not carry would let `SearchParamCodec<string>` produce\n   * `null` for an absent param under a non-nullable annotation. A codec\n   * whose absent-case answer is `null` declares that in `T`, exactly as a\n   * bare nuqs parser does: `parseAsString` is a `SearchParamCodec<string |\n   * null>` here, never a `SearchParamCodec<string>`.\n   *\n   * nuqs parser builders satisfy this. See parse-total.ts.\n   */\n  parseServerSide?(value: string | string[] | undefined): T;\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   * Get typed search params from the current request context (ALS-backed).\n   *\n   * Server-only, sync. Reads getSearchParams() from ALS and parses through codecs.\n   * Throws on client.\n   *\n   * ```tsx\n   * // app/products/page.tsx\n   * import { searchParams } from './search-params'\n   * export default function Page() {\n   *   const { page, category } = searchParams.get()\n   * }\n   * ```\n   */\n  get(): 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, SearchParamField>>(\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  /**\n   * Serialize values to a query string (no leading '?'), omitting defaults\n   * and applying `withUrlKey` aliases. This is the value to pass to\n   * `<Link searchParams={...}>`.\n   *\n   * Returns a **string**, not a `URLSearchParams`. A `<Link>` prop crosses\n   * the RSC Flight boundary, and `URLSearchParams` is iterable — React\n   * serializes it as an entries array, which arrives as `[['pg','2'], …]`\n   * and renders as `?0=pg&0=2`. A string survives intact.\n   */\n  buildSearchParams(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  /** 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// StandardSchemaV1 is imported from schema-bridge.ts — single source of truth.\n// Re-export for consumers that import it from this module.\nexport type { StandardSchemaV1 } from '../schema-bridge.ts';\n\n// ---------------------------------------------------------------------------\n// Type-level helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract a Standard Schema's declared *input* type from its optional\n * `~standard.types` property (part of the Standard Schema spec; Zod, Valibot,\n * and ArkType all declare it at the type level). Falls back to `never` when\n * the schema doesn't declare types (e.g. hand-written schemas): with no\n * metadata we can't know whether the schema handles `undefined`, so InferField\n * widens conservatively rather than risk a type lie.\n */\ntype InferSchemaInput<V> = V extends { '~standard': { types?: infer TS } }\n  ? [NonNullable<TS>] extends [{ input: infer I }]\n    ? I\n    : never\n  : never;\n\n/**\n * Infer the output type from either a SearchParamCodec or a StandardSchemaV1.\n *\n * A codec publishing `parseServerSide` is read through THAT signature, not\n * through `parse` — it is the entry point timber actually calls, and it is\n * the one that tells the truth about absent input. A bare `parseAsString`\n * declares `parse(value: string): string` but answers `null` for a missing\n * param, so the field is `string | null`; `parseAsInteger.withDefault(1)`\n * narrows its own `parseServerSide` to `NonNullable<number>` and the field\n * stays `number`. Reading `parse` instead produced a non-nullable type for\n * a nullable field (TIM-1350).\n *\n * The match is structural, not nuqs-specific: any codec declaring that\n * signature opts into being read through it, which is exactly the contract\n * `parseTotal` applies at runtime. The two must stay in step — a type\n * inferred from `parse` while the runtime calls `parseServerSide` is the\n * lie this branch exists to remove.\n *\n * Schemas whose input type rejects `undefined` (e.g. bare `z.string()`, whose\n * input is `string`) are implicitly optional: the URL might not contain the\n * param, and fromSchema returns `undefined` when the schema rejects absent\n * input and has no default. The output type widens to `T | undefined` so the\n * type doesn't lie. Schemas that accept `undefined` input (`.optional()`,\n * `.default()`) keep their declared output type.\n *\n * Limitation: `z.coerce.*` schemas declare input `unknown`, which accepts\n * `undefined` at the type level — so a coerce schema without `.default()`\n * keeps its narrow output type even though absent input yields `undefined`\n * at runtime. Add `.default()` to coerce schemas for accurate types.\n */\nexport type InferField<V> = V extends {\n  parseServerSide(value: string | string[] | undefined): infer R;\n}\n  ? R\n  : V extends SearchParamCodec<infer T>\n    ? T\n    : V extends StandardSchemaV1<infer T>\n      ? undefined extends InferSchemaInput<V>\n        ? T\n        : T | undefined\n      : never;\n\n/**\n * A codec whose total entry point is `parseServerSide`, even when `parse`\n * has a narrower signature. nuqs multi parsers (`parseAsNativeArrayOf`) have\n * `parse(value: readonly string[])` — too narrow for `SearchParamCodec`'s\n * `parse(string | string[] | undefined)` — but their `parseServerSide`\n * covers the full domain. Timber never calls `parse` directly on these;\n * `parseTotal` always reaches `parseServerSide` first (TIM-1355).\n */\nexport interface TotalSearchParamCodec<T> {\n  parseServerSide(value: string | string[] | undefined): T;\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  parse(...args: any[]): any;\n  serialize(value: T): string | string[] | null;\n  urlKey?: string;\n}\n\n/** Acceptable field value for defineSearchParams: a codec, a total codec, or a Standard Schema. */\nexport type SearchParamField<T = unknown> =\n  | SearchParamCodec<T>\n  | TotalSearchParamCodec<T>\n  | 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> = Object.create(null);\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 *\n * Goes through `parseTotal` for the same reason request-time parsing does:\n * a nuqs parser's own `parse` throws on absent input, and this is the\n * absent case by construction.\n *\n * **A codec with no value for an absent param has no default to omit**,\n * and `null` is returned rather than `serialize(null)`. Serializing it\n * makes the \"no value\" case collide with a real one: `parseAsInteger`\n * serializes `null` as the string `'null'`, so `buildSearchParams({ q:\n * 'null' })` would silently drop a legitimate value (before TIM-1350 the\n * absent parse was `undefined` and the swallowed input was the string\n * `'undefined'` — same defect, a less likely input). Nothing is lost:\n * `buildSearchParams` already skips a field whose `serialize` returns\n * `null`, so a codec that encodes \"no value\" as an omission behaves\n * identically, and one that encodes it as a real query value now writes\n * it instead of dropping it.\n *\n * Codecs are documented to return a default rather than throw, but a\n * hand-written codec that throws on absent input must not turn definition\n * into a crash — treat its default as null (nothing to omit). `serialize`\n * is inside the try for the same reason.\n *\n * Typed `SearchParamCodec<unknown>` rather than generic on purpose: the\n * absent-input value is whatever the codec's total entry point returns,\n * which for a nuqs parser is `T | null` while its `serialize` declares\n * `T`. Widening to `unknown` states that honestly instead of casting.\n */\nfunction getDefaultSerialized(codec: SearchParamCodec<unknown>): string | string[] | null {\n  try {\n    const absent = parseTotal(codec, undefined);\n    return absent === null || absent === undefined ? null : codec.serialize(absent);\n  } catch {\n    return null;\n  }\n}\n\n// isStandardSchema and isCodec are imported from schema-bridge.ts.\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 *\n * The returned codec is typed as `SearchParamCodec<unknown>` because the\n * codec map uses that type. At runtime, the value may be a `Codec<T>` from\n * `fromSchema` (whose serialize returns `string | null`) or a nuqs parser\n * (whose serialize returns `string | string[] | null`). Both are safe\n * because `buildSearchParams` handles the union.\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    const urlKey = (value as SearchParamCodec<unknown>).urlKey;\n    return { codec: value as SearchParamCodec<unknown>, urlKey };\n  }\n\n  // Auto-detect Standard Schema. Schemas that reject undefined input and\n  // have no default are implicitly optional: fromSchema returns undefined\n  // for absent params, and InferField widens the output type to\n  // T | undefined. design/23-search-params.md §\"Implicit Optionality\"\n  if (isStandardSchema(value)) {\n    return { codec: fromSchema(value) as SearchParamCodec<unknown> };\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// 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 */\n/**\n * Overload: accept a Standard Schema object schema (e.g., z.object({...})).\n *\n * The schema must have a `.shape` property whose values are themselves\n * Standard Schema objects. Each shape property becomes a field codec\n * via fromSchema().\n *\n * ```ts\n * const searchParams = defineSearchParams(\n *   z.object({ page: z.coerce.number().default(1), q: z.string().optional() })\n * )\n * ```\n */\nexport function defineSearchParams<\n  S extends StandardSchemaV1<Record<string, unknown>> & {\n    shape: Record<string, StandardSchemaV1<unknown>>;\n  },\n>(\n  schema: S\n): SearchParamsDefinition<{ [K in keyof S['shape'] & string]: InferField<S['shape'][K]> }>;\n\n/**\n * Overload: accept a map of codecs and/or Standard Schema objects.\n */\nexport function defineSearchParams<C extends Record<string, SearchParamField>>(\n  codecs: C\n): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }>;\n\nexport function defineSearchParams(\n  codecsOrSchema:\n    | Record<string, SearchParamField>\n    | (StandardSchemaV1<unknown> & { shape: Record<string, StandardSchemaV1<unknown>> })\n): SearchParamsDefinition<Record<string, unknown>> {\n  // Detect Standard Schema object with .shape (e.g., z.object(...))\n  if (isStandardSchema(codecsOrSchema) && hasShape(codecsOrSchema)) {\n    const fieldCodecs: Record<string, SearchParamField> = {};\n    for (const [key, fieldSchema] of Object.entries(codecsOrSchema.shape)) {\n      if (isStandardSchema(fieldSchema)) {\n        fieldCodecs[key] = fieldSchema;\n      } else {\n        throw new Error(\n          `[timber] defineSearchParams: field '${key}' in schema.shape is not a Standard Schema. ` +\n            `All shape properties must be Standard Schema objects (Zod, Valibot, ArkType).`\n        );\n      }\n    }\n    return defineSearchParamsFromMap(fieldCodecs);\n  }\n\n  return defineSearchParamsFromMap(codecsOrSchema as Record<string, SearchParamField>);\n}\n\n/** Check if a schema has a .shape property with object-type values. */\nfunction hasShape(schema: unknown): schema is { shape: Record<string, unknown> } {\n  return (\n    typeof schema === 'object' &&\n    schema !== null &&\n    'shape' in schema &&\n    typeof (schema as { shape: unknown }).shape === 'object' &&\n    (schema as { shape: unknown }).shape !== null\n  );\n}\n\nfunction defineSearchParamsFromMap(\n  codecs: Record<string, SearchParamField>\n): SearchParamsDefinition<Record<string, unknown>> {\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  return buildDefinition(resolvedCodecs as unknown as CodecMap<Record<string, unknown>>, 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 | 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] = parseTotal(codecMap[prop as keyof T] as SearchParamCodec<unknown>, 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  // ---- buildSearchParams ----\n  //\n  // Returns a query string. It used to have a URLSearchParams-returning\n  // sibling (`toSearchParams`) that `<Link>` consumed; that shape cannot\n  // cross the RSC Flight boundary (see the interface docstring), and having\n  // two methods produce the same query two ways was a drift waiting to\n  // happen. One method now.\n  function buildSearchParams(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\n      // TIM-1354: serialize may not be total over null — nuqs parsers like\n      // parseAsIsoDate throw TypeError on null (null.toISOString()). Catch\n      // TypeError and omit, matching what setParams does on the client.\n      // Only TypeError — a deliberate throw (redirect(), notFound()) from a\n      // codec's serialize must propagate, not be silently swallowed.\n      let serialized: string | string[] | null;\n      try {\n        serialized = codec.serialize(values[prop as keyof T] as unknown);\n      } catch (error) {\n        if (error instanceof TypeError) continue;\n        throw error;\n      }\n\n      if (serialized === null) continue;\n      // Omit if serialized value matches the default\n      if (serializedEqual(serialized, defaultSerialized[prop])) continue;\n\n      // TIM-1353: string[] → repeated keys (?tag=a&tag=b)\n      const urlKey = encodeURIComponent(getUrlKey(prop));\n      if (Array.isArray(serialized)) {\n        for (const entry of serialized) {\n          parts.push(`${urlKey}=${encodeURIComponent(entry)}`);\n        }\n      } else {\n        parts.push(`${urlKey}=${encodeURIComponent(serialized)}`);\n      }\n    }\n\n    return parts.join('&');\n  }\n\n  // ---- href ----\n  function href(pathname: string, values: Partial<T>): string {\n    const qs = buildSearchParams(values);\n    return qs ? `${pathname}?${qs}` : pathname;\n  }\n\n  // ---- extend ----\n  function extend<U extends Record<string, SearchParamField>>(\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      // Explicit guard — TypeScript prevents this, but JS callers and\n      // casts reach here, and \"Cannot read properties of undefined\n      // (reading 'serialize')\" is no help (TIM-1066).\n      if (!(key in codecMap)) {\n        throw new Error(\n          `[timber] pick('${key}'): unknown key. ` +\n            `Available keys: ${Object.keys(codecMap)\n              .map((k) => `'${k}'`)\n              .join(', ')}.`\n        );\n      }\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  // ---- get ----\n  // ALS-backed: reads getSearchParams() from the current request context\n  // and parses through codecs. Server-only, sync.\n  function get(): T {\n    if (typeof window !== 'undefined') {\n      throw new Error(\n        '[timber] searchParams.get() is server-only. ' +\n          'Use searchParams.useQueryStates() on the client.'\n      );\n    }\n    const raw = getSearchParamsFromAls();\n    return parseSync(raw);\n  }\n\n  const definition: SearchParamsDefinition<T> = {\n    parse,\n    get,\n    useQueryStates,\n    extend,\n    pick,\n    href,\n    buildSearchParams,\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 {\n  InferField,\n  SearchParamCodec,\n  SearchParamCodecWithUrlKey,\n  SearchParamField,\n} from './define.ts';\nimport { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.ts';\nimport { parseTotal } from './parse-total.ts';\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. The output type becomes\n * non-nullable, and the wrapper is TOTAL over `string | string[] |\n * undefined` even when the inner codec is not.\n *\n * The default is substituted for `null` — the documented \"no value\"\n * answer — and for `undefined`, which is what an implicitly-optional\n * Standard Schema field and a bare `parseAsString` produce for an absent\n * param. Substituting only for `null` left a field typed non-nullable\n * `string` holding `undefined` (TIM-1350).\n *\n * The inner codec is invoked through `parseTotal`, so a nuqs parser gets\n * its own normalization (absent → null, repeated → first value, inner\n * throw → null) before either check applies. That is what makes\n * `withDefault(parseAsBoolean, false)` total; the wrapper itself does NOT\n * catch. A throw from a codec is a deliberate signal — `fromSchema` throws\n * on an async schema, and an app codec may `redirect()` or `notFound()` on\n * a value it refuses — and swallowing it would convert a loud failure into\n * a permanently-default field. design/09 §\"The SearchParamCodec Protocol\":\n * a codec that throws bubbles as a render-phase error, by design.\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 *\n * The signature strips BOTH nullish constituents from the result, not just\n * `null`, because the runtime substitutes for both. An implicitly-optional\n * schema field is a `SearchParamCodec<string | undefined>`, and wrapping it\n * used to yield `SearchParamCodec<string | undefined>` — a field the\n * wrapper guarantees is always present, still typed as maybe-absent.\n */\nexport function withDefault<T>(\n  codec: SearchParamCodec<T | null | undefined>,\n  defaultValue: NonNullable<T>\n): SearchParamCodec<NonNullable<T>> {\n  // A wrapper that rebuilds a codec from two methods drops everything else\n  // the codec carries. `withUrlKey` lost `parseServerSide` that way; this\n  // one lost `urlKey`, so `withDefault(withUrlKey(parseAsInteger, 'p'), 1)`\n  // silently read `?page=` instead of `?p=`. Carry it explicitly rather\n  // than spreading: this wrapper's own `parse` IS the total entry point,\n  // and re-publishing the inner `parseServerSide` would let `parseTotal`\n  // reach past it and skip the default entirely.\n  const wrapped: SearchParamCodec<NonNullable<T>> = {\n    parse(value: string | string[] | undefined): NonNullable<T> {\n      const result = parseTotal(codec, value);\n      return result === null || result === undefined ? defaultValue : result;\n    },\n    serialize(value: NonNullable<T>): string | string[] | null {\n      return codec.serialize(value);\n    },\n  };\n  if (codec.urlKey !== undefined) wrapped.urlKey = codec.urlKey;\n  return wrapped;\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<F extends SearchParamField>(\n  codecOrSchema: F,\n  urlKey: string\n): SearchParamCodecWithUrlKey<InferField<F>> {\n  type T = InferField<F>;\n  // Auto-detect Standard Schema (Zod, Valibot, ArkType) and wrap. Schemas\n  // that reject undefined input are implicitly optional — fromSchema returns\n  // undefined for absent params, and InferField widens the type to include\n  // undefined. design/23-search-params.md §\"Implicit Optionality\"\n  const codec: SearchParamCodec<T> = isCodec(codecOrSchema)\n    ? (codecOrSchema as SearchParamCodec<T>)\n    : isStandardSchema(codecOrSchema)\n      ? (fromSchema(codecOrSchema) as SearchParamCodec<T>)\n      : (codecOrSchema as SearchParamCodec<T>);\n  // Carry the total entry point, bound like the other two methods. A\n  // codec's totality lives in a THIRD property, `parseServerSide` (see\n  // parse-total.ts); picking only `parse`/`serialize` silently produced a\n  // non-total alias, so `withUrlKey(parseAsBoolean, 'b')` threw on an\n  // absent param while the bare parser did not (TIM-1350).\n  //\n  // Bound explicitly rather than spread: a spread copies own enumerable\n  // properties only, so a class-based codec — whose `parse` and\n  // `serialize` this wrapper already reaches through the prototype —\n  // would have kept its methods and lost exactly the one that makes it\n  // total. Three properties, one rule, no dependence on how the inner\n  // codec was constructed.\n  const wrapped: SearchParamCodecWithUrlKey<T> = {\n    parse: codec.parse.bind(codec),\n    serialize: codec.serialize.bind(codec),\n    urlKey,\n  };\n  if (typeof codec.parseServerSide === 'function') {\n    wrapped.parseServerSide = codec.parseServerSide.bind(codec);\n  }\n  return wrapped;\n}\n"],"mappings":"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"}

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

@@ -7,7 +7,7 @@
  *
  * Design doc: design/23-search-params.md
  */
-import type { InferField, SearchParamCodec, SearchParamCodecWithUrlKey, SearchParamField } from './define.js';
+import type { InferField, SearchParamCodec, SearchParamCodecWithUrlKey, SearchParamField } from './define.ts';
 /**
  * Wrap a nullable codec with a default value. The output type becomes
  * non-nullable, and the wrapper is TOTAL over `string | string[] |

package/dist/server/access-gate.d.ts

@@ -12,7 +12,7 @@
  *
  * See design/04-authorization.md and design/02-rendering-pipeline.md §"AccessGate"
  */
-import type { AccessGateProps, SlotAccessGateProps } from './tree-builder.js';
+import type { AccessGateProps, SlotAccessGateProps } from './tree-builder.ts';
 import type { ReactNode } from 'react';
 /**
  * Framework-injected access gate for segments.