@timber-js/app 0.2.0-alpha.12 → 0.2.0-alpha.121

package/dist/routing/types.d.ts

@@ -3,6 +3,23 @@
  *
  * The route tree is built by scanning the app/ directory and recognizing
  * file conventions (page.*, layout.*, middleware.ts, access.ts, route.ts, etc.).
+ *
+ * **Single shape, two specializations** (TIM-848):
+ *
+ * `SegmentNode<TFile>` is the one canonical in-memory shape for the
+ * timber route tree. The same interface is used at build time (with
+ * `TFile = RouteFile`) and at request time (with `TFile = ManifestFile`,
+ * see `server/route-matcher.ts`). Walkers parameterized over `TFile`
+ * work on either, eliminating the previous duplication between
+ * `SegmentNode` (Map-based) and `ManifestSegmentNode` (object-based).
+ *
+ * Keyed groups (`slots`, `statusFiles`, `jsonStatusFiles`,
+ * `legacyStatusFiles`, `metadataRoutes`) are plain `Record<string, …>`
+ * objects rather than `Map`s so that the build-time tree can be
+ * serialized into the virtual route manifest with no shape transform.
+ *
+ * See design/07-routing.md §"Route Tree Shape" and design/18-build-system.md
+ * §"Route Manifest Shape".
  */
 /** Segment type classification */
 export type SegmentType = 'static' | 'dynamic' | 'catch-all' | 'optional-catch-all' | 'group' | 'slot' | 'intercepting' | 'private';
@@ -15,15 +32,31 @@ export type SegmentType = 'static' | 'dynamic' | 'catch-all' | 'optional-catch-a
 export type InterceptionMarker = '(.)' | '(..)' | '(...)' | '(..)(..)';
 /** All recognized interception markers, ordered longest-first for parsing. */
 export declare const INTERCEPTION_MARKERS: InterceptionMarker[];
-/** A single file discovered in a route segment */
+/**
+ * A single file discovered in a route segment at build time.
+ *
+ * The runtime equivalent (`ManifestFile`, defined in
+ * `server/route-matcher.ts`) replaces `extension` with a lazy `load`
+ * function. Walkers that only need `filePath` are parameterized over
+ * `TFile` and accept either.
+ */
 export interface RouteFile {
     /** Absolute path to the file */
     filePath: string;
     /** File extension without leading dot (e.g. "tsx", "ts", "mdx") */
     extension: string;
 }
-/** A node in the segment tree */
-export interface SegmentNode {
+/**
+ * A node in the segment tree.
+ *
+ * Generic over `TFile` so the same interface describes both the
+ * build-time tree (`SegmentNode<RouteFile>`, the default) and the
+ * runtime manifest tree (`SegmentNode<ManifestFile>`, aliased as
+ * `ManifestSegmentNode`). All keyed groups use `Record` (not `Map`)
+ * so the build-time tree serializes to the virtual route manifest
+ * with no shape transform.
+ */
+export interface SegmentNode<TFile = RouteFile> {
     /** The raw directory name (e.g. "dashboard", "[id]", "(auth)", "@sidebar") */
     segmentName: string;
     /** Classified segment type */
@@ -39,37 +72,56 @@ export interface SegmentNode {
      * E.g., for "(.)photo" this is "photo".
      */
     interceptedSegmentName?: string;
-    page?: RouteFile;
-    layout?: RouteFile;
-    middleware?: RouteFile;
-    access?: RouteFile;
-    route?: RouteFile;
-    error?: RouteFile;
-    default?: RouteFile;
+    page?: TFile;
+    layout?: TFile;
+    middleware?: TFile;
+    access?: TFile;
+    route?: TFile;
+    /**
+     * params.ts — isomorphic convention file exporting segmentParams and/or searchParams.
+     * Discovered by the scanner like middleware.ts and access.ts.
+     * See design/07-routing.md §"params.ts Convention File"
+     */
+    params?: TFile;
+    error?: TFile;
+    default?: TFile;
     /** Status-code files: 4xx.tsx, 5xx.tsx, {status}.tsx (component format) */
-    statusFiles?: Map<string, RouteFile>;
+    statusFiles?: Record<string, TFile>;
     /** JSON status-code files: 4xx.json, 5xx.json, {status}.json */
-    jsonStatusFiles?: Map<string, RouteFile>;
+    jsonStatusFiles?: Record<string, TFile>;
     /** denied.tsx — slot-only denial rendering */
-    denied?: RouteFile;
+    denied?: TFile;
     /** Legacy compat: not-found.tsx (maps to 404), forbidden.tsx (403), unauthorized.tsx (401) */
-    legacyStatusFiles?: Map<string, RouteFile>;
-    /** prerender.ts — signals build-time pre-rendering for this segment's shell */
-    prerender?: RouteFile;
-    /** search-params.ts — typed search params definition for this route */
-    searchParams?: RouteFile;
+    legacyStatusFiles?: Record<string, TFile>;
     /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
-    metadataRoutes?: Map<string, RouteFile>;
-    children: SegmentNode[];
+    metadataRoutes?: Record<string, TFile>;
+    children: SegmentNode<TFile>[];
     /** Parallel route slots (keyed by slot name without @) */
-    slots: Map<string, SegmentNode>;
+    slots: Record<string, SegmentNode<TFile>>;
 }
-/** The full route tree output from the scanner */
-export interface RouteTree {
+/**
+ * The full route tree output from the scanner (or the root of the
+ * runtime route manifest, when `TFile = ManifestFile`).
+ *
+ * Generic so the same wrapper carries app-root metadata for both
+ * shapes. The runtime manifest extends this with `viteRoot` (see
+ * `ManifestRoot` in `server/route-matcher.ts`).
+ */
+export interface RouteTree<TFile = RouteFile> {
     /** The root segment node (representing app/) */
-    root: SegmentNode;
+    root: SegmentNode<TFile>;
     /** All discovered proxy.ts files (should be at most one, in app/) */
-    proxy?: RouteFile;
+    proxy?: TFile;
+    /**
+     * Global error page: app/global-error.{tsx,ts,jsx,js}
+     *
+     * Rendered as a standalone full-page replacement (no layout wrapping)
+     * when no segment-level error file is found. SSR-only render path.
+     * Must provide its own <html> and <body>.
+     *
+     * See design/10-error-handling.md §"Tier 2 — Global Error Page"
+     */
+    globalError?: TFile;
 }
 /** Configuration passed to the scanner */
 export interface ScannerConfig {

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kCAAkC;AAClC,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,oBAAoB,GACpB,OAAO,GACP,MAAM,GACN,cAAc,GACd,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAEvE,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,EAAyC,CAAC;AAE/F,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAGhC,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACrC,gEAAgE;IAChE,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACzC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,8FAA8F;IAC9F,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC3C,+EAA+E;IAC/E,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uEAAuE;IACvE,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,sFAAsF;IACtF,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAGxC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,0DAA0D;IAC1D,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACjC;AAED,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,IAAI,EAAE,WAAW,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,8BAA8B;AAC9B,eAAO,MAAM,uBAAuB,UAA6B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routing/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,kCAAkC;AAClC,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,SAAS,GACT,WAAW,GACX,oBAAoB,GACpB,OAAO,GACP,MAAM,GACN,cAAc,GACd,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAEvE,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,EAAE,kBAAkB,EAAyC,CAAC;AAE/F;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,SAAS;IAC5C,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAGhC,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,UAAU,CAAC,EAAE,KAAK,CAAC;IACnB,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;;OAIG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACpC,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACxC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,8FAA8F;IAC9F,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAE1C,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAGvC,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;IAC/B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;CAC3C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS,CAAC,KAAK,GAAG,SAAS;IAC1C,gDAAgD;IAChD,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;IACzB,qEAAqE;IACrE,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC;CACrB;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,8BAA8B;AAC9B,eAAO,MAAM,uBAAuB,UAA6B,CAAC"}

package/dist/routing/walkers.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared route-tree walkers (TIM-848).
+ *
+ * Tiny helpers that walk a `SegmentNode<TFile>` tree generically. Both the
+ * build-time tree (`SegmentNode<RouteFile>`) and the runtime manifest
+ * tree (`SegmentNode<ManifestFile>`) flow through these helpers because
+ * the walker only reads the structural fields shared by both shapes
+ * (`children`, `slots`, `page`, `route`, `urlPath`).
+ *
+ * Before this module, three near-identical `collectRoutes` functions
+ * lived in `plugins/dev-404-page.ts`, `plugins/build-report.ts`, and
+ * `routing/codegen.ts`. The codegen one is special-purpose (it
+ * accumulates `ParamEntry[]` and resolves codec chains) and stays
+ * local; the other two now share `collectLeafRoutes` from this file.
+ */
+import type { SegmentNode } from './types.js';
+/** A leaf route discovered while walking the segment tree. */
+export interface LeafRoute<TFile> {
+    /** URL path of the leaf (root is "/"). */
+    urlPath: string;
+    /** Segment chain from root to this leaf, inclusive. */
+    segments: SegmentNode<TFile>[];
+    /** The page file at this leaf, if any. */
+    page?: TFile;
+    /** The route handler file at this leaf, if any. */
+    route?: TFile;
+}
+/** Options for `collectLeafRoutes`. */
+export interface CollectLeafRoutesOptions {
+    /**
+     * If true, recurse into parallel slots and emit slot leaves alongside
+     * the main route tree. Defaults to `false` because slots render
+     * alongside their parent at the same URL and are not separately
+     * URL-addressable. The build report excludes slots; route-listing
+     * UIs that want to show "all leaves with a page handler" can opt in.
+     */
+    includeSlots?: boolean;
+}
+/**
+ * Walk a segment tree and collect every leaf with a `page` or `route`
+ * handler. Generic over `TFile` so it works on both the build-time
+ * scanner output and the runtime manifest tree.
+ *
+ * - Pages and route handlers at the same URL produce two distinct
+ *   entries (the build report deduplicates by URL afterward).
+ * - Parallel slots are skipped unless `includeSlots: true` (slots
+ *   share their parent's URL and are not addressable on their own).
+ * - Result is sorted by `urlPath` for deterministic output.
+ */
+export declare function collectLeafRoutes<TFile>(root: SegmentNode<TFile>, options?: CollectLeafRoutesOptions): LeafRoute<TFile>[];
+//# sourceMappingURL=walkers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"walkers.d.ts","sourceRoot":"","sources":["../../src/routing/walkers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,8DAA8D;AAC9D,MAAM,WAAW,SAAS,CAAC,KAAK;IAC9B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;IAC/B,0CAA0C;IAC1C,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,mDAAmD;IACnD,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,uCAAuC;AACvC,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EACxB,OAAO,GAAE,wBAA6B,GACrC,SAAS,CAAC,KAAK,CAAC,EAAE,CAMpB"}

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

@@ -10,5 +10,5 @@
  * Keep this as thin pass-through re-exports — the value is the single choke
  * point, not abstraction.
  */
-export { renderToReadableStream, loadServerAction, decodeReply, decodeAction, } from '@vitejs/plugin-rsc/rsc';
+export { renderToReadableStream, loadServerAction, decodeReply, decodeAction, encryptActionBoundArgs, decryptActionBoundArgs, } from '@vitejs/plugin-rsc/rsc';
 //# sourceMappingURL=rsc.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"rsc.d.ts","sourceRoot":"","sources":["../../src/rsc-runtime/rsc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,YAAY,GACb,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"rsc.d.ts","sourceRoot":"","sources":["../../src/rsc-runtime/rsc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC"}

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

@@ -10,4 +10,16 @@
  * point, not abstraction.
  */
 export { createFromReadableStream } from '@vitejs/plugin-rsc/ssr';
+/**
+ * Decode an RSC Flight stream from a Node.js Readable.
+ *
+ * Uses the vendored createFromNodeStream which reads via Node.js native
+ * streams (C++ libuv) instead of Web ReadableStream (JS Promise per chunk).
+ *
+ * Returns null if createFromNodeStream isn't available (CF Workers, etc),
+ * signaling the caller to use createFromReadableStream instead.
+ */
+export declare function createFromNodeStream(stream: import('node:stream').Readable): React.ReactNode | null;
+/** Whether the Node.js stream RSC decode path is available. */
+export declare const hasNodeStreamDecode: boolean;
 //# sourceMappingURL=ssr.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ssr.d.ts","sourceRoot":"","sources":["../../src/rsc-runtime/ssr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"ssr.d.ts","sourceRoot":"","sources":["../../src/rsc-runtime/ssr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAiClE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,aAAa,EAAE,QAAQ,GACrC,KAAK,CAAC,SAAS,GAAG,IAAI,CAGxB;AAED,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,SAAiC,CAAC"}

package/dist/schema-bridge.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Standard Schema bridge — shared helpers for bridging Standard Schema-compatible
+ * validation libraries (Zod, Valibot, ArkType) to the Codec<T> protocol.
+ *
+ * This module is the single source of truth for:
+ * - StandardSchemaV1 interface (subset of the Standard Schema spec)
+ * - validateSync() helper
+ * - fromSchema() — bridge from Standard Schema to Codec<T>
+ * - fromArraySchema() — bridge for array-valued codecs
+ *
+ * These are re-exported from @timber-js/app/search-params, @timber-js/app/segment-params,
+ * and @timber-js/app/cookies for convenience. The canonical import is
+ * @timber-js/app/codec.
+ *
+ * Design doc: design/23a-search-params-triage.md §"Unify Codec<T> type"
+ */
+import type { Codec } from './codec.js';
+/** Minimal Standard Schema interface for auto-detection. */
+export interface StandardSchemaV1<Output = unknown> {
+    '~standard': {
+        validate(value: unknown): StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    };
+}
+export type StandardSchemaResult<Output> = {
+    value: Output;
+    issues?: undefined;
+} | {
+    value?: undefined;
+    issues: ReadonlyArray<{
+        message: string;
+    }>;
+};
+/**
+ * Run a Standard Schema's `~standard.validate()` synchronously.
+ *
+ * Zod v4's signature includes `Promise` in the return union to satisfy the
+ * Standard Schema spec, but in practice Zod always validates synchronously
+ * for the schema types we use. We assert the result is sync and throw if
+ * it isn't — codec parsing must be synchronous.
+ */
+export declare function validateSync<Output>(schema: StandardSchemaV1<Output>, value: unknown): StandardSchemaResult<Output>;
+/** Check if a value is a Standard Schema object. */
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/** Check if a value is a Codec (has parse + serialize methods). */
+export declare function isCodec(value: unknown): value is Codec<unknown>;
+/**
+ * Bridge a Standard Schema-compatible schema (Zod, Valibot, ArkType) to a
+ * Codec<T>.
+ *
+ * Parse: coerces the raw string through the schema. On validation failure,
+ * parses `undefined` to get the schema's default value (the schema should have
+ * a `.default()` call). If that also fails, returns `undefined`.
+ *
+ * Serialize: uses `String()` for primitives, `null` for null/undefined.
+ *
+ * ```ts
+ * import { fromSchema } from '@timber-js/app/codec'
+ * import { z } from 'zod/v4'
+ *
+ * const pageCodec = fromSchema(z.coerce.number().int().min(1).default(1))
+ * ```
+ */
+export declare function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T>;
+/**
+ * Bridge a Standard Schema for array values. Handles both single strings
+ * and repeated query keys (`?tag=a&tag=b`).
+ *
+ * ```ts
+ * import { fromArraySchema } from '@timber-js/app/codec'
+ * import { z } from 'zod/v4'
+ *
+ * const tagsCodec = fromArraySchema(z.array(z.string()).default([]))
+ * ```
+ */
+export declare function fromArraySchema<T>(schema: StandardSchemaV1<T>): Codec<T>;
+//# sourceMappingURL=schema-bridge.d.ts.map

package/dist/schema-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-bridge.d.ts","sourceRoot":"","sources":["../src/schema-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAUxC,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB,CAAC,MAAM,GAAG,OAAO;IAChD,WAAW,EAAE;QACX,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;KAChG,CAAC;CACH;AAED,MAAM,MAAM,oBAAoB,CAAC,MAAM,IACnC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACrC;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAMtE;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EACjC,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAChC,KAAK,EAAE,OAAO,GACb,oBAAoB,CAAC,MAAM,CAAC,CAQ9B;AAMD,oDAAoD;AACpD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAO1E;AAED,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAO/D;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CA6BnE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAmCxE"}

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

@@ -0,0 +1,157 @@
+/**
+ * defineSearchParams — factory for SearchParamsDefinition<T>.
+ *
+ * Creates a typed, composable definition for a route's search parameters.
+ * Accepts both SearchParamCodec values and Standard Schema objects (Zod,
+ * Valibot, ArkType) with auto-detection. Supports URL key aliasing via
+ * withUrlKey(), default-omission serialization, and composition via
+ * .extend() / .pick().
+ *
+ * Design doc: design/23-search-params.md §"defineSearchParams — The Factory"
+ */
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+import type { Codec } from '../codec.js';
+/**
+ * Register the getSearchParams function. Called once at module load time
+ * from request-context.ts to avoid dynamic import at call time.
+ * @internal
+ */
+export declare function _setGetSearchParamsFn(fn: () => URLSearchParams): void;
+/**
+ * A codec that converts between URL string values and typed values.
+ *
+ * nuqs parsers implement this interface natively — no adapter needed.
+ * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected
+ * by defineSearchParams and wrapped via fromSchema.
+ */
+export interface SearchParamCodec<T> extends Codec<T> {
+    /** Optional URL key alias, set by withUrlKey(). */
+    urlKey?: string;
+}
+/** A codec with a URL key alias attached via withUrlKey(). */
+export interface SearchParamCodecWithUrlKey<T> extends SearchParamCodec<T> {
+    urlKey: string;
+}
+/** Infer the output type of a codec. */
+export type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;
+/** Map of property names to codecs. */
+export type CodecMap<T extends Record<string, unknown>> = {
+    [K in keyof T]: SearchParamCodec<T[K]>;
+};
+/** Options for useQueryStates setter. */
+export interface SetParamsOptions {
+    /** Update URL without server roundtrip (default: false). */
+    shallow?: boolean;
+    /** Scroll to top after update (default: true). */
+    scroll?: boolean;
+    /** 'push' (default) or 'replace' for history state. */
+    history?: 'push' | 'replace';
+}
+/** Setter function returned by useQueryStates. */
+export type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;
+/** Options for useQueryStates hook. */
+export interface QueryStatesOptions {
+    /** Update URL without server roundtrip (default: false). */
+    shallow?: boolean;
+    /** Scroll to top after update (default: true). */
+    scroll?: boolean;
+    /** 'push' (default) or 'replace' for history state. */
+    history?: 'push' | 'replace';
+}
+/**
+ * A fully typed, composable search params definition.
+ *
+ * Returned by defineSearchParams(). Carries a phantom _type property
+ * for build-time type extraction.
+ */
+export interface SearchParamsDefinition<T extends Record<string, unknown>> {
+    /** Parse raw URL search params into typed values. */
+    parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;
+    /** Parse a Promise of URLSearchParams (e.g., from the ALS `searchParams()` API). */
+    parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;
+    /**
+     * Get typed search params from the current request context (ALS-backed).
+     *
+     * Server-only, sync. Reads getSearchParams() from ALS and parses through codecs.
+     * Throws on client.
+     *
+     * ```tsx
+     * // app/products/page.tsx
+     * import { searchParams } from './params'
+     * export default function Page() {
+     *   const { page, category } = searchParams.get()
+     * }
+     * ```
+     */
+    get(): T;
+    /** Client hook — reads current URL params and returns typed values + setter. */
+    useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];
+    /** Extend with additional codecs or Standard Schema objects. */
+    extend<U extends Record<string, SearchParamCodec<unknown> | StandardSchemaV1<unknown>>>(codecs: U): SearchParamsDefinition<T & {
+        [K in keyof U]: InferField<U[K]>;
+    }>;
+    /** Pick a subset of keys. Preserves codecs and aliases. */
+    pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;
+    /** Serialize values to a query string (no leading '?'), omitting defaults. */
+    serialize(values: Partial<T>): string;
+    /** Build a full path with query string, omitting defaults. */
+    href(pathname: string, values: Partial<T>): string;
+    /** Build a URLSearchParams instance, omitting defaults. */
+    toSearchParams(values: Partial<T>): URLSearchParams;
+    /** Read-only codec map for spreading into .extend(). */
+    codecs: {
+        [K in keyof T]: SearchParamCodec<T[K]>;
+    };
+    /** Read-only URL key alias map. Maps property names to URL query parameter keys. */
+    readonly urlKeys: Readonly<Record<string, string>>;
+    /**
+     * Phantom property for build-time type extraction.
+     * Never set at runtime — exists only in the type system.
+     */
+    readonly _type?: T;
+}
+export type { StandardSchemaV1 } from '../schema-bridge.js';
+/** Infer the output type from either a SearchParamCodec or a StandardSchemaV1. */
+export type InferField<V> = V extends SearchParamCodec<infer T> ? T : V extends StandardSchemaV1<infer T> ? T : never;
+/** Acceptable field value for defineSearchParams: a codec or a Standard Schema. */
+export type SearchParamField<T = unknown> = SearchParamCodec<T> | StandardSchemaV1<T>;
+/**
+ * Create a SearchParamsDefinition from a map of codecs and/or Standard Schema
+ * objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType
+ * schemas with auto-detection.
+ *
+ * ```ts
+ * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'
+ * import { parseAsString, parseAsStringEnum } from 'nuqs'
+ * import { z } from 'zod/v4'
+ *
+ * export const searchParams = defineSearchParams({
+ *   page: z.coerce.number().int().min(1).default(1),     // Standard Schema — auto-wrapped
+ *   q: withUrlKey(parseAsString, 'search'),                // nuqs codec with URL alias
+ *   sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),
+ * })
+ * ```
+ */
+/**
+ * Overload: accept a Standard Schema object schema (e.g., z.object({...})).
+ *
+ * The schema must have a `.shape` property whose values are themselves
+ * Standard Schema objects. Each shape property becomes a field codec
+ * via fromSchema().
+ *
+ * ```ts
+ * const searchParams = defineSearchParams(
+ *   z.object({ page: z.coerce.number().default(1), q: z.string().optional() })
+ * )
+ * ```
+ */
+export declare function defineSearchParams<T extends Record<string, unknown>>(schema: StandardSchemaV1<T> & {
+    shape: Record<string, StandardSchemaV1<unknown>>;
+}): SearchParamsDefinition<T>;
+/**
+ * Overload: accept a map of codecs and/or Standard Schema objects.
+ */
+export declare function defineSearchParams<C extends Record<string, SearchParamField>>(codecs: C): SearchParamsDefinition<{
+    [K in keyof C]: InferField<C[K]>;
+}>;
+//# sourceMappingURL=define.d.ts.map

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

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

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

@@ -1,8 +1,5 @@
-export type { SearchParamCodec, InferCodec, SearchParamsDefinition, SetParams, SetParamsOptions, QueryStatesOptions, SearchParamsOptions, } from './create.js';
-export { createSearchParams } from './create.js';
-export { fromSchema, fromArraySchema } from './codecs.js';
-export { parseAsString, parseAsInteger, parseAsFloat, parseAsBoolean, parseAsStringEnum, parseAsStringLiteral, withDefault, } from './builtin-codecs.js';
-export { registerSearchParams, getSearchParams } from './registry.js';
-export type { AnalyzeResult, AnalyzeError } from './analyze.js';
-export { analyzeSearchParams, formatAnalyzeError } from './analyze.js';
+export type { SearchParamCodec, SearchParamCodecWithUrlKey, InferCodec, InferField, CodecMap, SearchParamsDefinition, SetParams, SetParamsOptions, QueryStatesOptions, StandardSchemaV1, } from './define.js';
+export { defineSearchParams } from './define.js';
+export { withDefault, withUrlKey } from './wrappers.js';
+export { registerSearchParams, getSearchParamsDefinition } from './registry.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search-params/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,gBAAgB,EAChB,UAAU,EACV,sBAAsB,EACtB,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG1D,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGtE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/search-params/index.ts"],"names":[],"mappings":"AAMA,YAAY,EACV,gBAAgB,EAChB,0BAA0B,EAC1B,UAAU,EACV,UAAU,EACV,QAAQ,EACR,sBAAsB,EACtB,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAMjD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGxD,OAAO,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC"}