@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.151

package/dist/client/top-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"top-loader.d.ts","sourceRoot":"","sources":["../../src/client/top-loader.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA2F7F"}
+{"version":3,"file":"top-loader.d.ts","sourceRoot":"","sources":["../../src/client/top-loader.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CA6F7F"}

package/dist/client/use-cookie.d.ts

@@ -22,6 +22,18 @@ export interface ClientCookieOptions {
     secure?: boolean;
 }
 export type CookieSetter = (value: string, options?: ClientCookieOptions) => void;
+/** Parse a cookie name from document.cookie. */
+export declare function getCookieValue(name: string): string | undefined;
+/** Serialize options into a cookie string suffix. */
+export declare function serializeOptions(options?: ClientCookieOptions): string;
+/**
+ * Notify useCookie subscribers that a cookie value changed.
+ * Called by defineCookie's imperative client .set()/.delete() methods
+ * so mounted useCookie() consumers re-render.
+ *
+ * @internal — framework use only
+ */
+export declare function notifyCookieChange(name: string): void;
 /**
  * Reactive hook for reading/writing a client-side cookie.
  *

package/dist/client/use-cookie.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-cookie.d.ts","sourceRoot":"","sources":["../../src/client/use-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,yCAAyC;IACzC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;AA0ClF;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,mBAAmB,GACnC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC,CAmChF"}
+{"version":3,"file":"use-cookie.d.ts","sourceRoot":"","sources":["../../src/client/use-cookie.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,yCAAyC;IACzC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,IAAI,CAAC;AASlF,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM/D;AAED,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAWtE;AAUD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAErD;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,mBAAmB,GACnC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC,CAoDhF"}

package/dist/client/use-link-status.d.ts

@@ -1,5 +1,5 @@
 export interface LinkStatus {
-    pending: boolean;
+    isPending: boolean;
 }
 /**
  * React context provided by <Link>. Holds the pending status
@@ -7,10 +7,10 @@ export interface LinkStatus {
  */
 export declare const LinkStatusContext: import("react").Context<LinkStatus>;
 /**
- * Returns `{ pending: true }` while the nearest parent `<Link>` component's
+ * Returns `{ isPending: true }` while the nearest parent `<Link>` component's
  * navigation is in flight. Must be used inside a `<Link>` component's children.
  *
- * Unlike `useNavigationPending()` which is global, this hook is scoped to
+ * Unlike `usePendingNavigation()` which is global, this hook is scoped to
  * the nearest parent `<Link>` — only the link the user clicked shows pending.
  *
  * ```tsx
@@ -18,8 +18,8 @@ export declare const LinkStatusContext: import("react").Context<LinkStatus>;
  * import { Link, useLinkStatus } from '@timber-js/app/client'
  *
  * function Hint() {
- *   const { pending } = useLinkStatus()
- *   return <span className={pending ? 'opacity-50' : ''} />
+ *   const { isPending } = useLinkStatus()
+ *   return <span className={isPending ? 'opacity-50' : ''} />
  * }
  *
  * export function NavLink({ href, children }) {

package/dist/client/use-link-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-link-status.d.ts","sourceRoot":"","sources":["../../src/client/use-link-status.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,qCAAgD,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}
+{"version":3,"file":"use-link-status.d.ts","sourceRoot":"","sources":["../../src/client/use-link-status.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,qCAAkD,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}

package/dist/client/use-pathname.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-pathname.d.ts","sourceRoot":"","sources":["../../src/client/use-pathname.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAoBpC"}
+{"version":3,"file":"use-pathname.d.ts","sourceRoot":"","sources":["../../src/client/use-pathname.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAqBpC"}

package/dist/client/use-pending-navigation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns true while an RSC navigation is in flight.
+ *
+ * Reads from the router's external pending store via useSyncExternalStore.
+ * Only components that call this hook re-render when pending state
+ * changes — no full-tree re-render.
+ *
+ * ```tsx
+ * 'use client'
+ * import { usePendingNavigation } from '@timber-js/app/client'
+ *
+ * export function NavBar() {
+ *   const isPending = usePendingNavigation()
+ *   return (
+ *     <nav className={isPending ? 'opacity-50' : ''}>
+ *       <Link href="/dashboard">Dashboard</Link>
+ *     </nav>
+ *   )
+ * }
+ * ```
+ */
+export declare function usePendingNavigation(): boolean;
+//# sourceMappingURL=use-pending-navigation.d.ts.map

package/dist/client/use-pending-navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-pending-navigation.d.ts","sourceRoot":"","sources":["../../src/client/use-pending-navigation.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C"}

package/dist/client/use-query-states.d.ts

@@ -7,7 +7,7 @@
  *
  * Design doc: design/23-search-params.md §"Codec Bridge"
  */
-import type { SearchParamCodec, SearchParamsDefinition, SetParams, QueryStatesOptions } from '#/search-params/create.js';
+import type { SearchParamCodec, SearchParamsDefinition, SetParams, QueryStatesOptions } from '../search-params/define.js';
 /**
  * Read and write typed search params from/to the URL.
  *

package/dist/client/use-query-states.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-query-states.d.ts","sourceRoot":"","sources":["../../src/client/use-query-states.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAoCnC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,aAAa,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,MAAM,EAClE,QAAQ,CAAC,EAAE,kBAAkB,EAC7B,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAyDnB;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,UAAU,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACpC,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAIrD"}
+{"version":3,"file":"use-query-states.d.ts","sourceRoot":"","sources":["../../src/client/use-query-states.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EACV,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAoCpC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,aAAa,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,MAAM,EAClE,QAAQ,CAAC,EAAE,kBAAkB,EAC7B,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACzC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CA+DnB;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,UAAU,EAAE,sBAAsB,CAAC,CAAC,CAAC,GACpC,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAIrD"}

package/dist/client/use-router.d.ts

@@ -20,7 +20,7 @@
  *
  * For loading UI during navigation, use:
  * - useLinkStatus()          — per-link pending indicator (inside <Link>)
- * - useNavigationPending()   — global navigation pending state
+ * - usePendingNavigation()   — global navigation pending state
  */
 export interface AppRouterInstance {
     /** Navigate to a URL, pushing a new history entry */

package/dist/client/use-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-router.d.ts","sourceRoot":"","sources":["../../src/client/use-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,6DAA6D;IAC7D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,sDAAsD;IACtD,OAAO,IAAI,IAAI,CAAC;IAChB,+BAA+B;IAC/B,IAAI,IAAI,IAAI,CAAC;IACb,kCAAkC;IAClC,OAAO,IAAI,IAAI,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,IAAI,iBAAiB,CA8C7C"}
+{"version":3,"file":"use-router.d.ts","sourceRoot":"","sources":["../../src/client/use-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACzD,6DAA6D;IAC7D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,sDAAsD;IACtD,OAAO,IAAI,IAAI,CAAC;IAChB,+BAA+B;IAC/B,IAAI,IAAI,IAAI,CAAC;IACb,kCAAkC;IAClC,OAAO,IAAI,IAAI,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,IAAI,iBAAiB,CAgD7C"}

package/dist/client/use-search-params.d.ts

@@ -4,9 +4,17 @@
  * Returns a read-only URLSearchParams instance reflecting the current
  * URL's query string. Updates when client-side navigation changes the URL.
  *
- * This is a thin wrapper over window.location.search, provided for
- * Next.js API compatibility (libraries like nuqs import useSearchParams
- * from next/navigation).
+ * On the client, reads from NavigationContext which is updated atomically
+ * with the RSC tree render during full navigations, AND by
+ * syncShallowSearch() for shallow URL updates (nuqs shallow: true,
+ * replaceUrl, or any external pushState/replaceState that changes the
+ * query string). See router-init.ts.
+ *
+ * This replaces the previous useSyncExternalStore approach which read
+ * window.location.search directly — causing React to detect external
+ * store tearing during transitions and fall back to synchronous rendering
+ * (renderRootSync instead of renderRootConcurrent), blocking the main
+ * thread and freezing animations.
  *
  * Unlike Next.js's ReadonlyURLSearchParams, this returns a standard
  * URLSearchParams. Mutation methods (set, delete, append) work on the
@@ -15,8 +23,7 @@
  * During SSR, reads the request search params from the SSR ALS context
  * (populated by ssr-entry.ts) instead of window.location.
  *
- * All mutable state is delegated to client/state.ts for singleton guarantees.
- * See design/18-build-system.md §"Singleton State Registry"
+ * Compatible with Next.js's `useSearchParams()` from `next/navigation`.
  */
 /**
  * Read the current URL search params.

package/dist/client/use-search-params.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-search-params.d.ts","sourceRoot":"","sources":["../../src/client/use-search-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA+CH;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAMjD"}
+{"version":3,"file":"use-search-params.d.ts","sourceRoot":"","sources":["../../src/client/use-search-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAeH;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAkBjD"}

package/dist/client/{use-params.d.ts → use-segment-params.d.ts}

@@ -7,7 +7,7 @@
  *
  * Two layers of type narrowing work together:
  * 1. The generic overload here uses the Routes interface directly —
- *    `useParams<R>()` returns `Routes[R]['params']`.
+ *    `useParams<R>()` returns `Routes[R]['segmentParams']`.
  * 2. Build-time codegen generates per-route string-literal overloads
  *    in the .d.ts file for IDE autocomplete (see routing/codegen.ts).
  *
@@ -29,7 +29,7 @@
  *
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
-import type { Routes } from '#/index.js';
+import type { Routes } from '../index.js';
 /**
  * Subscribe to params changes.
  * Retained for backward compatibility with tests that verify the
@@ -83,10 +83,12 @@ export declare function notifyParamsListeners(): void;
  * When called outside a React component (e.g., in test assertions),
  * falls back to the module-level snapshot.
  *
- * @overload Typed — when a known route path is passed, returns the
+ * @overload Typed — when a known segment path is passed, returns the
  *   exact params shape from the generated Routes interface.
  * @overload Fallback — returns the generic params record.
  */
-export declare function useParams<R extends keyof Routes>(route: R): Routes[R]['params'];
-export declare function useParams(route?: string): Record<string, string | string[]>;
-//# sourceMappingURL=use-params.d.ts.map
+export declare function useSegmentParams<R extends keyof Routes>(segmentPath: R): Routes[R] extends {
+    segmentParams: infer P;
+} ? P : Record<string, string | string[]>;
+export declare function useSegmentParams(segmentPath?: string): Record<string, string | string[]>;
+//# sourceMappingURL=use-segment-params.d.ts.map

package/dist/client/use-segment-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-segment-params.d.ts","sourceRoot":"","sources":["../../src/client/use-segment-params.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAS1C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAG1D;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAE/D;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,MAAM,EACrD,WAAW,EAAE,CAAC,GACb,MAAM,CAAC,CAAC,CAAC,SAAS;IAAE,aAAa,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;AACxF,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC"}

package/dist/codec.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @timber-js/app/codec — Shared codec protocol and Standard Schema bridge.
+ *
+ * The canonical import path for codec primitives shared across search params,
+ * route params, and cookies.
+ *
+ * Design doc: design/23a-search-params-triage.md §"Unify Codec<T> type"
+ */
+/**
+ * A codec that converts between string values and typed values.
+ *
+ * The canonical protocol shared across search params, cookies, and
+ * any future timber feature that needs string ↔ typed conversion.
+ */
+export interface Codec<T> {
+    /** String → typed value. Receives undefined when the value is absent. */
+    parse(value: string | string[] | undefined): T;
+    /** Typed value → string. Return null to omit/clear. */
+    serialize(value: T): string | null;
+}
+/**
+ * Marker interface for codecs designed for catch-all segments (`[...slug]`).
+ * These codecs expect `string[]` input from the router.
+ */
+export interface CatchAllCodec<T> extends Codec<T> {
+    readonly __catchAll: true;
+}
+/**
+ * Marker interface for codecs designed for optional catch-all segments (`[[...slug]]`).
+ * These codecs expect `string[] | undefined` input from the router.
+ */
+export interface OptionalCatchAllCodec<T> extends Codec<T> {
+    readonly __catchAll: true;
+    readonly __optional: true;
+}
+/**
+ * Recursive JSON-serializable type. The canonical definition for data that
+ * can safely cross the RSC → client boundary.
+ *
+ * Previously exported from both @timber-js/app/server and @timber-js/app/client.
+ * Moved here so there is exactly one canonical import path.
+ */
+export type JsonSerializable = string | number | boolean | null | JsonSerializable[] | {
+    [key: string]: JsonSerializable;
+};
+export { fromArraySchema, } from './schema-bridge.js';
+export type { StandardSchemaV1, StandardSchemaResult } from './schema-bridge.js';
+export declare const codec: {
+    readonly string: {
+        parse(value: string | string[] | undefined): string;
+        serialize(value: string): string | null;
+    };
+    readonly integer: {
+        parse(value: string | string[] | undefined): number;
+        serialize(value: number): string | null;
+    };
+    readonly slug: {
+        parse(value: string | string[] | undefined): string;
+        serialize(value: string): string | null;
+    };
+    readonly stringArray: {
+        __catchAll: true;
+        parse(value: string | string[] | undefined): string[];
+        serialize(value: string[]): string | null;
+    };
+    readonly catchAll: <T>(inner: Codec<T>) => CatchAllCodec<T[]>;
+    readonly optionalCatchAll: <T>(inner: Codec<T>) => OptionalCatchAllCodec<T[] | undefined>;
+};
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;GAKG;AACH,MAAM,WAAW,KAAK,CAAC,CAAC;IACtB,yEAAyE;IACzE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,CAAC,CAAC;IAC/C,uDAAuD;IACvD,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,gBAAgB,EAAE,GAClB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAIxC,OAAO,EAEL,eAAe,GAIhB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAIjF,eAAO,MAAM,KAAK;;qBAED,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM;yBAGlC,MAAM,GAAG,MAAM,GAAG,IAAI;;;qBAM1B,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM;yBAMlC,MAAM,GAAG,MAAM,GAAG,IAAI;;;qBAM1B,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM;yBAOlC,MAAM,GAAG,MAAM,GAAG,IAAI;;;;qBAO1B,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE;yBAIpC,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI;;wBAKlC,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,KAAG,aAAa,CAAC,CAAC,EAAE,CAAC;gCAgB/B,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,KAAG,qBAAqB,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC;CAepE,CAAC"}

package/dist/codec.js

@@ -0,0 +1,75 @@
+import { t as fromArraySchema } from "./_chunks/schema-bridge-BY3QLBL7.js";
+//#region src/codec.ts
+var codec = {
+	string: {
+		parse(value) {
+			return Array.isArray(value) ? value.join("/") : value ?? "";
+		},
+		serialize(value) {
+			return value;
+		}
+	},
+	integer: {
+		parse(value) {
+			const str = Array.isArray(value) ? value[0] : value;
+			const n = Number(str);
+			if (!Number.isInteger(n)) throw new Error(`Expected integer, got '${str}'`);
+			return n;
+		},
+		serialize(value) {
+			return String(value);
+		}
+	},
+	slug: {
+		parse(value) {
+			const str = Array.isArray(value) ? value[0] : value;
+			if (!str || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(str)) throw new Error(`Invalid slug: '${str}'`);
+			return str;
+		},
+		serialize(value) {
+			return value;
+		}
+	},
+	stringArray: {
+		__catchAll: true,
+		parse(value) {
+			if (Array.isArray(value)) return value;
+			return value ? [value] : [];
+		},
+		serialize(value) {
+			return value.join("/");
+		}
+	},
+	catchAll(inner) {
+		return {
+			__catchAll: true,
+			parse(value) {
+				const arr = Array.isArray(value) ? value : value !== void 0 ? [value] : [];
+				if (arr.length === 0) throw new Error("Catch-all segment requires at least one value");
+				return arr.map((item) => inner.parse(item));
+			},
+			serialize(value) {
+				return value.map((item) => inner.serialize(item)).join("/");
+			}
+		};
+	},
+	optionalCatchAll(inner) {
+		return {
+			__catchAll: true,
+			__optional: true,
+			parse(value) {
+				const arr = Array.isArray(value) ? value : value !== void 0 ? [value] : [];
+				if (arr.length === 0) return void 0;
+				return arr.map((item) => inner.parse(item));
+			},
+			serialize(value) {
+				if (!value || value.length === 0) return null;
+				return value.map((item) => inner.serialize(item)).join("/");
+			}
+		};
+	}
+};
+//#endregion
+export { codec, fromArraySchema };
+
+//# sourceMappingURL=codec.js.map

package/dist/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","names":[],"sources":["../src/codec.ts"],"sourcesContent":["/**\n * @timber-js/app/codec — Shared codec protocol and Standard Schema bridge.\n *\n * The canonical import path for codec primitives shared across search params,\n * route params, and cookies.\n *\n * Design doc: design/23a-search-params-triage.md §\"Unify Codec<T> type\"\n */\n\n// ─── Codec protocol ──────────────────────────────────────────────────────\n\n/**\n * A codec that converts between string values and typed values.\n *\n * The canonical protocol shared across search params, cookies, and\n * any future timber feature that needs string ↔ typed conversion.\n */\nexport interface Codec<T> {\n  /** String → typed value. Receives undefined when the value is absent. */\n  parse(value: string | string[] | undefined): T;\n  /** Typed value → string. Return null to omit/clear. */\n  serialize(value: T): string | null;\n}\n\n/**\n * Marker interface for codecs designed for catch-all segments (`[...slug]`).\n * These codecs expect `string[]` input from the router.\n */\nexport interface CatchAllCodec<T> extends Codec<T> {\n  readonly __catchAll: true;\n}\n\n/**\n * Marker interface for codecs designed for optional catch-all segments (`[[...slug]]`).\n * These codecs expect `string[] | undefined` input from the router.\n */\nexport interface OptionalCatchAllCodec<T> extends Codec<T> {\n  readonly __catchAll: true;\n  readonly __optional: true;\n}\n\n/**\n * Recursive JSON-serializable type. The canonical definition for data that\n * can safely cross the RSC → client boundary.\n *\n * Previously exported from both @timber-js/app/server and @timber-js/app/client.\n * Moved here so there is exactly one canonical import path.\n */\nexport type JsonSerializable =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonSerializable[]\n  | { [key: string]: JsonSerializable };\n\n// ─── Standard Schema bridge ──────────────────────────────────────────────\n\nexport {\n  // fromSchema,\n  fromArraySchema,\n  // validateSync,\n  // isStandardSchema,\n  // isCodec,\n} from './schema-bridge.js';\nexport type { StandardSchemaV1, StandardSchemaResult } from './schema-bridge.js';\n\n// ─── Built-in segment param codecs ───────────────────────────────────────\n\nexport const codec = {\n  string: {\n    parse(value: string | string[] | undefined): string {\n      return Array.isArray(value) ? value.join('/') : (value ?? '');\n    },\n    serialize(value: string): string | null {\n      return value;\n    },\n  } satisfies Codec<string>,\n\n  integer: {\n    parse(value: string | string[] | undefined): number {\n      const str = Array.isArray(value) ? value[0] : value;\n      const n = Number(str);\n      if (!Number.isInteger(n)) throw new Error(`Expected integer, got '${str}'`);\n      return n;\n    },\n    serialize(value: number): string | null {\n      return String(value);\n    },\n  } satisfies Codec<number>,\n\n  slug: {\n    parse(value: string | string[] | undefined): string {\n      const str = Array.isArray(value) ? value[0] : value;\n      if (!str || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(str)) {\n        throw new Error(`Invalid slug: '${str}'`);\n      }\n      return str;\n    },\n    serialize(value: string): string | null {\n      return value;\n    },\n  } satisfies Codec<string>,\n\n  stringArray: {\n    __catchAll: true as const,\n    parse(value: string | string[] | undefined): string[] {\n      if (Array.isArray(value)) return value;\n      return value ? [value] : [];\n    },\n    serialize(value: string[]): string | null {\n      return value.join('/');\n    },\n  } satisfies CatchAllCodec<string[]>,\n\n  catchAll<T>(inner: Codec<T>): CatchAllCodec<T[]> {\n    return {\n      __catchAll: true as const,\n      parse(value: string | string[] | undefined): T[] {\n        const arr = Array.isArray(value) ? value : value !== undefined ? [value] : [];\n        if (arr.length === 0) {\n          throw new Error('Catch-all segment requires at least one value');\n        }\n        return arr.map((item) => inner.parse(item));\n      },\n      serialize(value: T[]): string | null {\n        return value.map((item) => inner.serialize(item)).join('/');\n      },\n    };\n  },\n\n  optionalCatchAll<T>(inner: Codec<T>): OptionalCatchAllCodec<T[] | undefined> {\n    return {\n      __catchAll: true as const,\n      __optional: true as const,\n      parse(value: string | string[] | undefined): T[] | undefined {\n        const arr = Array.isArray(value) ? value : value !== undefined ? [value] : [];\n        if (arr.length === 0) return undefined;\n        return arr.map((item) => inner.parse(item));\n      },\n      serialize(value: T[] | undefined): string | null {\n        if (!value || value.length === 0) return null;\n        return value.map((item) => inner.serialize(item)).join('/');\n      },\n    };\n  },\n} as const;\n"],"mappings":";;AAqEA,IAAa,QAAQ;CACnB,QAAQ;EACN,MAAM,OAA8C;GAClD,OAAO,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,GAAG,IAAK,SAAS;EAC5D;EACA,UAAU,OAA8B;GACtC,OAAO;EACT;CACF;CAEA,SAAS;EACP,MAAM,OAA8C;GAClD,MAAM,MAAM,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK;GAC9C,MAAM,IAAI,OAAO,GAAG;GACpB,IAAI,CAAC,OAAO,UAAU,CAAC,GAAG,MAAM,IAAI,MAAM,0BAA0B,IAAI,EAAE;GAC1E,OAAO;EACT;EACA,UAAU,OAA8B;GACtC,OAAO,OAAO,KAAK;EACrB;CACF;CAEA,MAAM;EACJ,MAAM,OAA8C;GAClD,MAAM,MAAM,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK;GAC9C,IAAI,CAAC,OAAO,CAAC,6BAA6B,KAAK,GAAG,GAChD,MAAM,IAAI,MAAM,kBAAkB,IAAI,EAAE;GAE1C,OAAO;EACT;EACA,UAAU,OAA8B;GACtC,OAAO;EACT;CACF;CAEA,aAAa;EACX,YAAY;EACZ,MAAM,OAAgD;GACpD,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO;GACjC,OAAO,QAAQ,CAAC,KAAK,IAAI,CAAC;EAC5B;EACA,UAAU,OAAgC;GACxC,OAAO,MAAM,KAAK,GAAG;EACvB;CACF;CAEA,SAAY,OAAqC;EAC/C,OAAO;GACL,YAAY;GACZ,MAAM,OAA2C;IAC/C,MAAM,MAAM,MAAM,QAAQ,KAAK,IAAI,QAAQ,UAAU,KAAA,IAAY,CAAC,KAAK,IAAI,CAAC;IAC5E,IAAI,IAAI,WAAW,GACjB,MAAM,IAAI,MAAM,+CAA+C;IAEjE,OAAO,IAAI,KAAK,SAAS,MAAM,MAAM,IAAI,CAAC;GAC5C;GACA,UAAU,OAA2B;IACnC,OAAO,MAAM,KAAK,SAAS,MAAM,UAAU,IAAI,CAAC,EAAE,KAAK,GAAG;GAC5D;EACF;CACF;CAEA,iBAAoB,OAAyD;EAC3E,OAAO;GACL,YAAY;GACZ,YAAY;GACZ,MAAM,OAAuD;IAC3D,MAAM,MAAM,MAAM,QAAQ,KAAK,IAAI,QAAQ,UAAU,KAAA,IAAY,CAAC,KAAK,IAAI,CAAC;IAC5E,IAAI,IAAI,WAAW,GAAG,OAAO,KAAA;IAC7B,OAAO,IAAI,KAAK,SAAS,MAAM,MAAM,IAAI,CAAC;GAC5C;GACA,UAAU,OAAuC;IAC/C,IAAI,CAAC,SAAS,MAAM,WAAW,GAAG,OAAO;IACzC,OAAO,MAAM,KAAK,SAAS,MAAM,UAAU,IAAI,CAAC,EAAE,KAAK,GAAG;GAC5D;EACF;CACF;AACF"}