@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

package/src/client/rsc-fetch.ts

@@ -23,7 +23,7 @@ export interface FetchResult {
   headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
+  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
   params: Record<string, string | string[]> | null;
   /** Segment paths that were skipped by the server (for client-side merging). */
   skippedSegments: string[] | null;
@@ -58,6 +58,43 @@ function appendRscParam(url: string): string {
   return `${url}${separator}_rsc=${generateCacheBustId()}`;
 }
 
+// ─── Deployment ID ───────────────────────────────────────────────
+
+/**
+ * The client's deployment ID, set at bootstrap from the runtime config.
+ * Sent with every RSC/action request for version skew detection.
+ * Null in dev mode. See TIM-446.
+ */
+let clientDeploymentId: string | null = null;
+
+/** Set the client deployment ID. Called once at bootstrap. */
+export function setClientDeploymentId(id: string | null): void {
+  clientDeploymentId = id;
+}
+
+/** Get the client deployment ID. */
+export function getClientDeploymentId(): string | null {
+  return clientDeploymentId;
+}
+
+// ─── Reload Signal ───────────────────────────────────────────────
+
+/** Header name used by the server to signal a version skew reload. */
+export const RELOAD_HEADER = 'X-Timber-Reload';
+
+/** Header name for the client's deployment ID. */
+export const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';
+
+/**
+ * Check if a response signals a version skew reload.
+ * Triggers a full page reload if the server indicates the client is stale.
+ */
+export function checkReloadSignal(response: Response): boolean {
+  return response.headers.get(RELOAD_HEADER) === '1';
+}
+
+// ─── Header Builder ──────────────────────────────────────────────
+
 export function buildRscHeaders(
   stateTree: { segments: string[] } | undefined,
   currentUrl?: string
@@ -75,6 +112,13 @@ export function buildRscHeaders(
   if (currentUrl) {
     headers['X-Timber-URL'] = currentUrl;
   }
+  // Send deployment ID for version skew detection (TIM-446).
+  // The server compares this against the current build's ID.
+  // On mismatch, the server signals a reload instead of returning
+  // an RSC payload with mismatched module references.
+  if (clientDeploymentId) {
+    headers[DEPLOYMENT_ID_HEADER] = clientDeploymentId;
+  }
   return headers;
 }
 
@@ -135,7 +179,7 @@ export function extractSkippedSegments(response: Response): string[] | null {
  * Extract route params from the X-Timber-Params response header.
  * Returns null if the header is missing or malformed.
  *
- * Used to populate useParams() after client-side navigation.
+ * Used to populate useSegmentParams() after client-side navigation.
  */
 export function extractParams(response: Response): Record<string, string | string[]> | null {
   const header = response.headers.get('X-Timber-Params');
@@ -161,6 +205,36 @@ export class RedirectError extends Error {
   }
 }
 
+/**
+ * Thrown when the server signals a version skew (X-Timber-Reload header).
+ * Caught in navigate() to trigger a full page reload via triggerStaleReload().
+ * See TIM-446.
+ */
+export class VersionSkewError extends Error {
+  constructor() {
+    super('Version skew detected — server has been redeployed');
+  }
+}
+
+/**
+ * Thrown when the server returns an error for an RSC payload request.
+ * The server sends X-Timber-Error header and a JSON body instead of a
+ * broken RSC stream for any RenderError (4xx or 5xx). Caught in
+ * navigate() to trigger a hard navigation so the server can render
+ * the error page as HTML.
+ *
+ * See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+ */
+export class ServerErrorResponse extends Error {
+  readonly status: number;
+  readonly url: string;
+  constructor(status: number, url: string) {
+    super(`Server error ${status} during navigation to ${url}`);
+    this.status = status;
+    this.url = url;
+  }
+}
+
 // ─── Fetch ───────────────────────────────────────────────────────
 
 /**
@@ -175,7 +249,8 @@ export async function fetchRscPayload(
   url: string,
   deps: RouterDeps,
   stateTree?: { segments: string[] },
-  currentUrl?: string
+  currentUrl?: string,
+  signal?: AbortSignal
 ): Promise<FetchResult> {
   const rscUrl = appendRscParam(url);
   const headers = buildRscHeaders(stateTree, currentUrl);
@@ -186,12 +261,18 @@ export async function fetchRscPayload(
     //
     // Intercept the response to read X-Timber-Head before createFromFetch
     // consumes the body. Reading headers does NOT consume the body stream.
-    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual' });
+    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
     let headElements: HeadElement[] | null = null;
     let segmentInfo: SegmentInfo[] | null = null;
     let params: Record<string, string | string[]> | null = null;
     let skippedSegments: string[] | null = null;
     const wrappedPromise = fetchPromise.then((response) => {
+      // Version skew detection (TIM-446): if the server signals a reload,
+      // throw VersionSkewError so the caller (router navigate) can trigger
+      // a full page reload via triggerStaleReload().
+      if (checkReloadSignal(response)) {
+        throw new VersionSkewError();
+      }
       // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
       // for RSC payload requests instead of a raw 302, because fetch with
       // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
@@ -202,6 +283,13 @@ export async function fetchRscPayload(
       if (redirectLocation) {
         throw new RedirectError(redirectLocation);
       }
+      // Detect server error responses. The server returns X-Timber-Error header
+      // with a JSON body instead of a broken RSC stream for any RenderError
+      // (4xx or 5xx). Hard-navigate so the server renders the error page as HTML.
+      // See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+      if (response.headers.get('X-Timber-Error') === '1') {
+        throw new ServerErrorResponse(response.status, url);
+      }
       headElements = extractHeadElements(response);
       segmentInfo = extractSegmentInfo(response);
       params = extractParams(response);
@@ -216,7 +304,7 @@ export async function fetchRscPayload(
     return { payload, headElements, segmentInfo, params, skippedSegments };
   }
   // Test/fallback path: return raw text
-  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual' });
+  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
   // Check for redirect in test path too
   if (response.status >= 300 && response.status < 400) {
     const location = response.headers.get('Location');

package/src/client/segment-cache.ts

@@ -11,7 +11,7 @@ export interface PrefetchResult {
   headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo?: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
+  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
   params?: Record<string, string | string[]> | null;
   /** Segment paths skipped by the server (for client-side merging). */
   skippedSegments?: string[] | null;

package/src/client/segment-context.ts

@@ -52,7 +52,12 @@ interface SegmentProviderProps {
  * Wraps each layout to provide segment position context.
  * Injected by rsc-entry.ts during element tree construction.
  */
-export function SegmentProvider({ segments, segmentId: _segmentId, parallelRouteKeys, children }: SegmentProviderProps) {
+export function SegmentProvider({
+  segments,
+  segmentId: _segmentId,
+  parallelRouteKeys,
+  children,
+}: SegmentProviderProps) {
   const value = useMemo(
     () => ({ segments, parallelRouteKeys }),
     // segments and parallelRouteKeys are static per layout — they don't change

package/src/client/segment-merger.ts

@@ -186,10 +186,7 @@ function walkChildren(children: ReactNode, out: CachedSegmentEntry[]): void {
  * Cache all segment subtrees from a fully-rendered RSC element tree.
  * Call this after every full RSC payload render (navigate, refresh, hydration).
  */
-export function cacheSegmentElements(
-  element: unknown,
-  cache: SegmentElementCache
-): void {
+export function cacheSegmentElements(element: unknown, cache: SegmentElementCache): void {
   const segments = extractSegments(element);
   for (const entry of segments) {
     cache.set(entry.segmentPath, entry);
@@ -208,10 +205,7 @@ export function cacheSegmentElements(
  */
 type TreePath = Array<{ element: ReactElement; childIndex: number }>;
 
-function findSegmentProviderPath(
-  node: ReactElement,
-  targetPath?: string
-): TreePath | null {
+function findSegmentProviderPath(node: ReactElement, targetPath?: string): TreePath | null {
   const children = (node.props as { children?: ReactNode }).children;
   if (children == null) return null;
 

package/src/client/segment-outlet.tsx

@@ -0,0 +1,86 @@
+/**
+ * SegmentOutlet — client component boundary at each layout segment.
+ *
+ * Replaces the post-hoc tree walking in segment-merger.ts with an explicit
+ * client component at each segment boundary. Each outlet:
+ *
+ * 1. Knows its own segment path (prop from the server)
+ * 2. Caches its children in a ref across navigations
+ * 3. When `keepCurrent` is true (partial navigation, this segment skipped),
+ *    returns the previously cached children — layout state is preserved
+ * 4. When `keepCurrent` is false (full navigation or this segment changed),
+ *    stores and renders the new children
+ *
+ * This eliminates the need for client-side element tree walking, which
+ * breaks on real RSC trees due to opaque client component lazy refs,
+ * Suspense thenables, and AccessGate wrappers.
+ *
+ * Architecture is similar to Next.js's `<LayoutRouter>` client component —
+ * each layout boundary is an explicit client component that manages its
+ * own subtree. See design/19-client-navigation.md.
+ *
+ * Security: This is a performance optimization only. The server always
+ * runs all access.ts files regardless of segment skipping. A fabricated
+ * keepCurrent prop can only cause stale layouts — never auth bypass.
+ * See design/13-security.md §"State tree manipulation".
+ */
+
+'use client';
+
+import { useRef, type ReactNode } from 'react';
+
+export interface SegmentOutletProps {
+  /**
+   * Unique identifier for this segment. For normal segments this is the
+   * urlPath (e.g., "/", "/dashboard"). For route groups this includes the
+   * group name (e.g., "/(marketing)") to distinguish siblings that share
+   * the same urlPath. Must match the segmentId used in state-tree-diff.ts.
+   */
+  segmentPath: string;
+
+  /**
+   * When true, the outlet returns its previously cached children instead
+   * of rendering the new children prop. Set by the server when this
+   * segment was skipped (the client already has the layout mounted).
+   *
+   * On the first render (SSR/hydration), this is always false — there's
+   * no cached content yet. On subsequent partial navigations, the server
+   * sets this to true for segments it skipped rendering.
+   */
+  keepCurrent?: boolean;
+
+  /** The segment's React subtree (layout + inner content). */
+  children: ReactNode;
+}
+
+/**
+ * Client component boundary at each layout segment in the element tree.
+ *
+ * On full navigation: receives new children, stores them, renders them.
+ * On partial navigation (keepCurrent=true): ignores children prop,
+ * returns previously stored content — React reconciles the same elements,
+ * preserving all client component state in the layout subtree.
+ *
+ * React preserves the ref across `reactRoot.render()` calls because:
+ * - SegmentOutlet has a stable type (client component module reference)
+ * - It appears at the same tree position on every navigation
+ * - React reconciles same-type, same-position → instance preserved
+ */
+export function SegmentOutlet({
+  segmentPath: _segmentPath,
+  keepCurrent = false,
+  children,
+}: SegmentOutletProps) {
+  // Store content in a ref to avoid triggering re-renders on cache updates.
+  // The ref persists across reactRoot.render() calls because React reconciles
+  // the same component type at the same tree position.
+  const contentRef = useRef<ReactNode>(null);
+
+  if (!keepCurrent) {
+    // Full render or this segment was re-rendered — store and render new content
+    contentRef.current = children;
+  }
+  // else: keepCurrent=true — return previously cached content
+
+  return contentRef.current;
+}

package/src/client/ssr-data.ts

@@ -41,12 +41,20 @@ export interface SsrData {
   /** The request's route params (e.g. { id: '123' }) */
   params: Record<string, string | string[]>;
   /**
-   * Mutable reference to NavContext for error boundary → RSC communication.
-   * When TimberErrorBoundary catches a DenySignal, it sets
-   * `_navContext._denyHandledByBoundary = true` to prevent the RSC entry
-   * from promoting the denial to page-level. See LOCAL-298.
+   * Mutable reference to NavContext for error boundary → pipeline communication.
+   *
+   * When TimberErrorBoundary catches a DenySignal during SSR, it:
+   * 1. Sets `statusCode` to the deny status (e.g., 403) — so the HTTP
+   *    Response has the correct status code without a re-render.
+   * 2. Sets `_denyHandledByBoundary = true` — so the pipeline skips
+   *    the redundant renderDenyPage() re-render.
+   *
+   * This runs synchronously during Fizz rendering, BEFORE onShellReady,
+   * so the status code is committed before any bytes are sent.
+   *
+   * See TIM-664, design/04-authorization.md §"React.cache Scope in Deny/Error Re-renders"
    */
-  _navContext?: { _denyHandledByBoundary?: boolean };
+  _navContext?: { statusCode?: number; _denyHandledByBoundary?: boolean };
 }
 
 // ─── ALS-Backed Provider ─────────────────────────────────────────

package/src/client/stale-reload.ts

@@ -16,6 +16,16 @@
 
 const RELOAD_FLAG_KEY = '__timber_stale_reload';
 
+/**
+ * In-memory fallback counter for environments where sessionStorage is
+ * unavailable (private browsing, storage full, extension interference).
+ * Incremented each time triggerStaleReload() falls into the catch path.
+ * If the counter exceeds 0 on a subsequent call, the reload is suppressed
+ * to prevent an infinite loop. Resets naturally on page load (module
+ * re-evaluates) and can be manually reset via clearStaleReloadFlag().
+ */
+let memoryReloadCount = 0;
+
 /**
  * Check if an error is a stale client reference error from React's
  * Flight client. These errors have the message pattern:
@@ -32,6 +42,34 @@ export function isStaleClientReference(error: unknown): boolean {
   return msg.includes('Could not find the module') || msg.includes('client reference not found');
 }
 
+/**
+ * Check if an error is a chunk load failure from a dynamic import.
+ *
+ * After a deployment, old chunk filenames no longer exist. When the client
+ * tries to dynamically import a chunk that's been replaced, the browser
+ * throws one of these errors:
+ *
+ * - Chromium: "Failed to fetch dynamically imported module: <url>"
+ * - Firefox: "error loading dynamically imported module: <url>"
+ * - Safari: "Importing a module script failed."
+ * - Vite/Rollup: "Unable to preload CSS for <url>"
+ *
+ * See TIM-446
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const msg = error.message.toLowerCase();
+  return (
+    msg.includes('failed to fetch dynamically imported module') ||
+    msg.includes('error loading dynamically imported module') ||
+    msg.includes('importing a module script failed') ||
+    msg.includes('unable to preload css') ||
+    // Webpack-style chunk load errors (unlikely in Vite but defensive)
+    msg.includes('loading chunk') ||
+    msg.includes('loading css chunk')
+  );
+}
+
 /**
  * Trigger a full page reload to pick up new bundles.
  *
@@ -48,8 +86,8 @@ export function triggerStaleReload(): boolean {
     if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {
       console.warn(
         '[timber] Stale client reference detected again after reload. ' +
-        'Not reloading to prevent infinite loop. ' +
-        'This may indicate a deployment issue — try a hard refresh.'
+          'Not reloading to prevent infinite loop. ' +
+          'This may indicate a deployment issue — try a hard refresh.'
       );
       return false;
     }
@@ -59,16 +97,38 @@ export function triggerStaleReload(): boolean {
 
     console.warn(
       '[timber] Stale client reference detected — the server has been ' +
-      'redeployed with new bundles. Reloading to pick up the new version.'
+        'redeployed with new bundles. Reloading to pick up the new version.'
     );
 
     window.location.reload();
     return true;
   } catch {
-    // sessionStorage may be unavailable (private browsing, storage full, etc.)
-    // Fall back to reloading without loop protection
+    // sessionStorage unavailable (private browsing, storage full, etc.)
+    // Use document.cookie as a reload-persistent fallback loop guard.
+    // Module-level memoryReloadCount resets on every reload, so it can't
+    // detect cross-reload loops. Cookies persist across reloads and are
+    // available even when sessionStorage is blocked (TIM-576).
+    const cookieFlag = document.cookie.includes(RELOAD_FLAG_KEY + '=1');
+    if (cookieFlag || memoryReloadCount > 0) {
+      console.warn(
+        '[timber] Stale client reference detected again after reload. ' +
+          'Not reloading to prevent infinite loop. ' +
+          'This may indicate a deployment issue — try a hard refresh.'
+      );
+      return false;
+    }
+
+    memoryReloadCount++;
+    // Set a short-lived cookie (60s) as the persistent loop guard.
+    // It auto-expires so it won't block future legitimate reloads.
+    try {
+      document.cookie = `${RELOAD_FLAG_KEY}=1; max-age=60; path=/; SameSite=Lax`;
+    } catch {
+      // Cookie API unavailable — proceed anyway, memoryReloadCount guards same-page loops
+    }
     console.warn(
-      '[timber] Stale client reference detected. Reloading page.'
+      '[timber] Stale client reference detected — the server has been ' +
+        'redeployed with new bundles. Reloading to pick up the new version.'
     );
     window.location.reload();
     return true;
@@ -81,9 +141,16 @@ export function triggerStaleReload(): boolean {
  * reference error should trigger a fresh reload attempt.
  */
 export function clearStaleReloadFlag(): void {
+  memoryReloadCount = 0;
   try {
     sessionStorage.removeItem(RELOAD_FLAG_KEY);
   } catch {
     // sessionStorage unavailable — nothing to clear
   }
+  // Also clear the cookie fallback
+  try {
+    document.cookie = `${RELOAD_FLAG_KEY}=; max-age=0; path=/; SameSite=Lax`;
+  } catch {
+    // Cookie API unavailable
+  }
 }

package/src/client/top-loader.tsx

@@ -3,7 +3,7 @@
  *
  * Shows an animated progress bar at the top of the viewport while an RSC
  * navigation is in flight. Injected automatically by the framework into
- * TransitionRoot — users never render this component directly.
+ * NavigationRoot — users never render this component directly.
  *
  * Configuration is via timber.config.ts `topLoader` key. Enabled by default.
  * Users who want a fully custom progress indicator disable the built-in one
@@ -28,7 +28,7 @@
 'use client';
 
 import { useState, createElement } from 'react';
-import { usePendingNavigationUrl } from './navigation-context.js';
+import { usePendingNavigationUrl, hasNativeNavigationTransition } from './navigation-context.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -39,7 +39,7 @@ export interface TopLoaderConfig {
   color?: string;
   /** Bar height in pixels. Default: 3. */
   height?: number;
-  /** Show subtle glow/shadow effect. Default: true. */
+  /** Show subtle glow/shadow effect. Default: false. */
   shadow?: boolean;
   /** Delay in ms before showing the bar. Default: 0. */
   delay?: number;
@@ -51,7 +51,7 @@ export interface TopLoaderConfig {
 
 const DEFAULT_COLOR = '#2299DD';
 const DEFAULT_HEIGHT = 3;
-const DEFAULT_SHADOW = true;
+const DEFAULT_SHADOW = false;
 const DEFAULT_DELAY = 0;
 const DEFAULT_Z_INDEX = 1600;
 
@@ -97,7 +97,7 @@ function ensureKeyframes(): void {
 // ─── Component ───────────────────────────────────────────────────
 
 /**
- * Internal top-loader component. Injected by TransitionRoot.
+ * Internal top-loader component. Injected by NavigationRoot.
  *
  * Reads pending navigation state from PendingNavigationContext.
  * Phase transitions are derived synchronously during render:
@@ -112,7 +112,15 @@ function ensureKeyframes(): void {
  */
 export function TopLoader({ config }: { config?: TopLoaderConfig }): React.ReactElement | null {
   const pendingUrl = usePendingNavigationUrl();
-  const isPending = pendingUrl !== null;
+  // Navigation is pending when either:
+  // 1. Our React-based pending URL is set (standard path), OR
+  // 2. The Navigation API has an active transition (external navigations
+  //    intercepted by the navigate event that haven't completed yet).
+  // In practice these are almost always in sync — the Navigation API
+  // transition is active while our pendingUrl is set. This check ensures
+  // the top-loader also shows for external navigations caught by the
+  // Navigation API before our React state updates.
+  const isPending = pendingUrl !== null || hasNativeNavigationTransition();
 
   const color = config?.color ?? DEFAULT_COLOR;
   const height = config?.height ?? DEFAULT_HEIGHT;
@@ -183,18 +191,19 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
   };
 
   // Clean up the finishing phase when the finish animation completes.
-  const handleAnimationEnd = phase === 'finishing'
-    ? (e: React.AnimationEvent) => {
-        if (e.animationName === FINISH_KEYFRAMES) {
-          setPhase('hidden');
+  const handleAnimationEnd =
+    phase === 'finishing'
+      ? (e: React.AnimationEvent) => {
+          if (e.animationName === FINISH_KEYFRAMES) {
+            setPhase('hidden');
+          }
         }
-      }
-    : undefined;
+      : undefined;
 
   return createElement(
     'div',
     {
-      style: containerStyle,
+      'style': containerStyle,
       'aria-hidden': 'true',
       'data-timber-top-loader': '',
     },

package/src/client/use-navigation-pending.ts

@@ -1,7 +1,7 @@
 // useNavigationPending — returns true while an RSC navigation is in flight.
 // See design/19-client-navigation.md §"useNavigationPending()"
 //
-// Reads from PendingNavigationContext (provided by TransitionRoot) so the
+// Reads from PendingNavigationContext (provided by NavigationRoot) so the
 // pending state shows immediately (urgent update) and clears atomically
 // with the new tree (same startTransition commit).
 

package/src/client/use-params.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).
  *
@@ -30,7 +30,7 @@
  * Design doc: design/09-typescript.md §"Typed Routes"
  */
 
-import type { Routes } from '#/index.js';
+import type { Routes } from '../index.js';
 import { getSsrData } from './ssr-data.js';
 import { currentParams, _setCurrentParams, paramsListeners } from './state.js';
 import { useNavigationContext } from './navigation-context.js';
@@ -119,9 +119,11 @@ export function notifyParamsListeners(): void {
  *   exact params shape from the generated Routes interface.
  * @overload Fallback — returns the generic params record.
  */
-export function useParams<R extends keyof Routes>(route: R): Routes[R]['params'];
-export function useParams(route?: string): Record<string, string | string[]>;
-export function useParams(_route?: string): Record<string, string | string[]> {
+export function useSegmentParams<R extends keyof Routes>(
+  route: R
+): Routes[R] extends { segmentParams: infer P } ? P : Record<string, string | string[]>;
+export function useSegmentParams(route?: string): Record<string, string | string[]>;
+export function useSegmentParams(_route?: string): Record<string, string | string[]> {
   // Try reading from NavigationContext (client-side, inside React tree).
   // During SSR, no NavigationProvider is mounted, so this returns null.
   // When called outside a React component, useContext throws — caught below.

package/src/client/use-query-states.ts

@@ -17,8 +17,8 @@ import type {
   SearchParamsDefinition,
   SetParams,
   QueryStatesOptions,
-} from '#/search-params/create.js';
-import { getSearchParams } from '#/search-params/registry.js';
+} from '../search-params/define.js';
+import { getSearchParams } from '../search-params/registry.js';
 
 // ─── Codec Bridge ─────────────────────────────────────────────────
 

package/src/codec.ts

@@ -0,0 +1,34 @@
+/**
+ * @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"
+ */
+
+// ─── Codec protocol ──────────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ─── Standard Schema bridge ──────────────────────────────────────────────
+
+export {
+  fromSchema,
+  fromArraySchema,
+  validateSync,
+  isStandardSchema,
+  isCodec,
+} from './schema-bridge.js';
+export type { StandardSchemaV1, StandardSchemaResult } from './schema-bridge.js';