@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.61

package/dist/server/prerender.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"prerender.d.ts","sourceRoot":"","sources":["../../src/server/prerender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAEpF;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD,MAAM,WAAW,uBAAuB;IACtC,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACpF,wBAAwB;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,GAAG,uBAAuB,CAsBpF;AAMD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,2BAA2B,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,EAClB,iBAAiB,EAAE,OAAO,EAC1B,QAAQ,CAAC,EAAE,OAAO,GACjB,mBAAmB,GAAG,IAAI,CAc5B"}

package/dist/server/response-cache.d.ts

@@ -1,53 +0,0 @@
-/**
- * Render-level response deduplication and short-TTL LRU cache.
- *
- * Two layers of optimization:
- *
- * 1. **Singleflight** — concurrent requests to the same URL share a single
- *    render. Uses createSingleflight() from cache/singleflight.ts.
- *
- * 2. **LRU cache** — recently rendered responses are reused without
- *    re-executing the RSC-to-SSR pipeline. Entries have a short TTL
- *    (default 5s) and the cache has a bounded size (default 150 entries).
- *
- * Cache keys are compound: method + pathname + isRscPayload. Responses
- * with Set-Cookie headers are never cached (they contain user-specific
- * state). When `publicOnly` is true (default), requests with Cookie or
- * Authorization headers bypass the cache entirely.
- *
- * See design/02-rendering-pipeline.md, design/31-benchmarking.md.
- */
-export interface ResponseCacheConfig {
-    /** Maximum number of entries in the LRU cache. Default: 150. */
-    maxSize?: number;
-    /** TTL for cached entries in milliseconds. Default: 5000 (5s). */
-    ttlMs?: number;
-    /**
-     * When true (default), requests with Cookie or Authorization headers
-     * bypass the cache entirely. This prevents sharing user-specific
-     * responses across requests.
-     */
-    publicOnly?: boolean;
-}
-export interface ResolvedResponseCacheConfig {
-    maxSize: number;
-    ttlMs: number;
-    publicOnly: boolean;
-}
-export declare function resolveResponseCacheConfig(config?: ResponseCacheConfig | false): ResolvedResponseCacheConfig | null;
-export interface ResponseCache {
-    /**
-     * Wrap a render function with singleflight dedup + LRU caching.
-     * Returns the cached Response or executes the render function.
-     */
-    getOrRender(req: Request, isRscPayload: boolean, renderFn: () => Promise<Response>): Promise<Response>;
-    /** Number of entries currently in the LRU cache. */
-    readonly size: number;
-    /** Clear all cached entries. */
-    clear(): void;
-}
-/**
- * Create a response cache with singleflight deduplication and LRU caching.
- */
-export declare function createResponseCache(config: ResolvedResponseCacheConfig): ResponseCache;
-//# sourceMappingURL=response-cache.d.ts.map

package/dist/server/response-cache.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"response-cache.d.ts","sourceRoot":"","sources":["../../src/server/response-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,wBAAgB,0BAA0B,CACxC,MAAM,CAAC,EAAE,mBAAmB,GAAG,KAAK,GACnC,2BAA2B,GAAG,IAAI,CASpC;AAoFD,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,WAAW,CACT,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,OAAO,EACrB,QAAQ,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GAChC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,gCAAgC;IAChC,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,2BAA2B,GAAG,aAAa,CAqHtF"}

package/src/client/link-status-provider.tsx

@@ -1,30 +0,0 @@
-'use client';
-
-// LinkStatusProvider — client component that provides per-link pending status
-// via React context. Used inside <Link> to power useLinkStatus().
-//
-// Reads pendingUrl from PendingNavigationContext (provided by TransitionRoot).
-// The pending URL is set as an URGENT update at navigation start (shows
-// immediately) and cleared inside startTransition when the new tree commits
-// (atomic with params/pathname). This eliminates both:
-// 1. The delay before showing the spinner (urgent update, not deferred)
-// 2. The gap between spinner disappearing and active state updating (same commit)
-
-import type { ReactNode } from 'react';
-import { LinkStatusContext, type LinkStatus } from './use-link-status.js';
-import { usePendingNavigationUrl } from './navigation-context.js';
-
-const NOT_PENDING: LinkStatus = { pending: false };
-const IS_PENDING: LinkStatus = { pending: true };
-
-/**
- * Client component that reads the pending URL from PendingNavigationContext
- * and provides a scoped LinkStatusContext to children. Renders no extra DOM —
- * just a context provider around children.
- */
-export function LinkStatusProvider({ href, children }: { href: string; children?: ReactNode }) {
-  const pendingUrl = usePendingNavigationUrl();
-  const status = pendingUrl === href ? IS_PENDING : NOT_PENDING;
-
-  return <LinkStatusContext.Provider value={status}>{children}</LinkStatusContext.Provider>;
-}

package/src/plugins/dynamic-transform.ts

@@ -1,161 +0,0 @@
-/**
- * timber-dynamic-transform — Vite sub-plugin for 'use dynamic' directive.
- *
- * Detects `'use dynamic'` directives in server component function bodies
- * and transforms them into `markDynamic()` runtime calls. The directive
- * declares a dynamic boundary — the component and its subtree opt out of
- * the pre-rendered shell and render per-request.
- *
- * - In `output: 'static'` mode, `'use dynamic'` is a build error.
- * - In standard SSR routes (no prerender.ts), the directive is a no-op
- *   (everything is already per-request), but the transform still runs
- *   so the runtime can skip unnecessary work.
- *
- * Design doc: design/15-future-prerendering.md §"'use dynamic'"
- */
-
-import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import { findFunctionsWithDirective, containsDirective } from '#/utils/directive-parser.js';
-
-// ---------------------------------------------------------------------------
-// Detection
-// ---------------------------------------------------------------------------
-
-/**
- * Quick check: does this source file contain 'use dynamic' anywhere?
- * Used as a fast bail-out before doing expensive AST parsing.
- */
-export function containsUseDynamic(code: string): boolean {
-  return containsDirective(code, 'use dynamic');
-}
-
-// ---------------------------------------------------------------------------
-// Transform
-// ---------------------------------------------------------------------------
-
-interface TransformResult {
-  code: string;
-  map?: null;
-}
-
-/**
- * Find function declarations/expressions containing 'use dynamic' and
- * transform them into markDynamic() calls.
- *
- * Input:
- * ```tsx
- * export default async function AddToCartButton({ productId }) {
- *   'use dynamic'
- *   const user = await getUser()
- *   return <button>Add to cart</button>
- * }
- * ```
- *
- * Output:
- * ```tsx
- * import { markDynamic as __markDynamic } from '@timber-js/app/runtime';
- * export default async function AddToCartButton({ productId }) {
- *   __markDynamic();
- *   const user = await getUser()
- *   return <button>Add to cart</button>
- * }
- * ```
- *
- * The markDynamic() call registers the component boundary as dynamic
- * at render time. The pre-render pass uses this to know which subtrees
- * to skip and leave as holes for per-request rendering.
- */
-export function transformUseDynamic(code: string): TransformResult | null {
-  if (!containsUseDynamic(code)) return null;
-
-  const functions = findFunctionsWithDirective(code, 'use dynamic');
-  if (functions.length === 0) return null;
-
-  // Replace directive strings with __markDynamic() calls, processing
-  // from end to start to preserve source offsets
-  let result = code;
-  for (const fn of functions) {
-    // Replace the directive in the body content
-    const cleanBody = fn.bodyContent.replace(/['"]use dynamic['"];?/, '__markDynamic();');
-    // Reconstruct: replace the body content between braces
-    result = result.slice(0, fn.bodyStart) + cleanBody + result.slice(fn.bodyEnd);
-  }
-
-  // Add the import at the top
-  result = `import { markDynamic as __markDynamic } from '@timber-js/app/runtime';\n` + result;
-
-  return { code: result, map: null };
-}
-
-// ---------------------------------------------------------------------------
-// Static mode validation
-// ---------------------------------------------------------------------------
-
-/**
- * In `output: 'static'` mode, `'use dynamic'` is a build error.
- * Static mode renders everything at build time — there is no per-request
- * rendering to opt into.
- */
-export function validateNoDynamicInStaticMode(
-  code: string
-): { message: string; line?: number } | null {
-  if (!containsUseDynamic(code)) return null;
-
-  const functions = findFunctionsWithDirective(code, 'use dynamic');
-  if (functions.length === 0) return null;
-
-  return {
-    message:
-      `'use dynamic' cannot be used in static mode (output: 'static'). ` +
-      `Static mode renders all content at build time — there is no per-request rendering. ` +
-      `Remove the directive or switch to output: 'server'.`,
-    line: functions[functions.length - 1].directiveLine, // First occurrence (sorted descending)
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Vite Plugin
-// ---------------------------------------------------------------------------
-
-/**
- * Create the timber-dynamic-transform Vite plugin.
- *
- * In server mode: transforms 'use dynamic' into markDynamic() calls.
- * In static mode: rejects 'use dynamic' as a build error.
- */
-export function timberDynamicTransform(ctx: PluginContext): Plugin {
-  const isStatic = ctx.config.output === 'static';
-
-  return {
-    name: 'timber-dynamic-transform',
-
-    transform(code: string, id: string) {
-      // Skip node_modules
-      if (id.includes('node_modules')) return null;
-
-      // Only check files in the app directory
-      if (!id.includes('/app/') && !id.startsWith('app/')) return null;
-
-      // Only check JS/TS files
-      if (!/\.[jt]sx?$/.test(id)) return null;
-
-      // Quick bail-out
-      if (!containsUseDynamic(code)) return null;
-
-      // In static mode, 'use dynamic' is a build error
-      if (isStatic) {
-        const error = validateNoDynamicInStaticMode(code);
-        if (error) {
-          this.error(
-            `[timber] Static mode error in ${id}${error.line ? `:${error.line}` : ''}: ${error.message}`
-          );
-        }
-        return null;
-      }
-
-      // In server mode, transform the directive
-      return transformUseDynamic(code);
-    },
-  };
-}

package/src/search-params/analyze.ts

@@ -1,192 +0,0 @@
-/**
- * Static analyzability checker for search-params.ts files.
- *
- * Validates that a search-params.ts file's default export is statically
- * analyzable — a createSearchParams() call or a chain of .extend()/.pick()
- * calls on a SearchParamsDefinition.
- *
- * Non-analyzable files produce a hard build error with a diagnostic.
- *
- * Design doc: design/09-typescript.md §"Static Analyzability"
- */
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** Result of analyzing a search-params.ts file. */
-export interface AnalyzeResult {
-  /** Whether the file is statically analyzable. */
-  valid: boolean;
-  /** Error details when valid is false. */
-  error?: AnalyzeError;
-}
-
-/** Diagnostic error for non-analyzable search-params.ts. */
-export interface AnalyzeError {
-  /** Absolute file path. */
-  filePath: string;
-  /** Description of the non-analyzable expression. */
-  expression: string;
-  /** Suggested fix. */
-  suggestion: string;
-}
-
-// ---------------------------------------------------------------------------
-// AST-free source analysis
-//
-// We use a lightweight regex-based approach to validate the structure of the
-// default export. This avoids requiring a TypeScript compiler instance at
-// build time for the initial validation pass. The full type extraction
-// (reading T from SearchParamsDefinition<T>) still happens via the TypeScript
-// compiler in the codegen step — this module just validates the *shape*.
-// ---------------------------------------------------------------------------
-
-/**
- * Patterns that indicate a valid default export:
- *
- * 1. `export default createSearchParams(...)`
- * 2. `export default someVar.extend(...)`
- * 3. `export default someVar.pick(...)`
- * 4. `export default someVar.extend(...).extend(...)`  (chained)
- * 5. `export default someVar.extend(...).pick(...)`    (chained)
- * 6. `export default createSearchParams(...).extend(...)`
- *
- * Invalid patterns:
- * - `export default someFunction(...)` (arbitrary factory)
- * - `export default condition ? a : b` (runtime conditional)
- * - `export default variable` (opaque reference without call)
- */
-
-/**
- * Analyze a search-params.ts file source for static analyzability.
- *
- * @param source - The file content as a string
- * @param filePath - Absolute path to the file (for diagnostics)
- */
-export function analyzeSearchParams(source: string, filePath: string): AnalyzeResult {
-  // Strip comments to avoid false matches
-  const stripped = stripComments(source);
-
-  // Find the default export
-  const defaultExport = extractDefaultExport(stripped);
-
-  if (!defaultExport) {
-    return {
-      valid: false,
-      error: {
-        filePath,
-        expression: '(no default export found)',
-        suggestion:
-          'search-params.ts must have a default export. Use: export default createSearchParams({ ... })',
-      },
-    };
-  }
-
-  // Validate the expression
-  if (isValidExpression(defaultExport.trim())) {
-    return { valid: true };
-  }
-
-  return {
-    valid: false,
-    error: {
-      filePath,
-      expression: defaultExport.trim(),
-      suggestion:
-        'The default export must be a createSearchParams() call, or a chain of ' +
-        '.extend() / .pick() calls on a SearchParamsDefinition. Arbitrary factory ' +
-        'functions and runtime conditionals are not supported.',
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/** Strip single-line and multi-line comments from source. */
-function stripComments(source: string): string {
-  // Remove multi-line comments
-  let result = source.replace(/\/\*[\s\S]*?\*\//g, '');
-  // Remove single-line comments
-  result = result.replace(/\/\/.*$/gm, '');
-  return result;
-}
-
-/**
- * Extract the expression from `export default <expr>`.
- *
- * Handles both:
- *   export default createSearchParams(...)
- *   export default expr\n (terminated by newline or semicolon before next statement)
- */
-function extractDefaultExport(source: string): string | undefined {
-  // Match `export default` followed by the expression
-  const match = source.match(
-    /export\s+default\s+([\s\S]+?)(?:;|\n(?=export|import|const|let|var|function|class|type|interface|declare))/
-  );
-  if (match) {
-    return match[1];
-  }
-
-  // Fallback: match everything after `export default` to end of file
-  const fallback = source.match(/export\s+default\s+([\s\S]+)$/);
-  if (fallback) {
-    return fallback[1].replace(/;\s*$/, '');
-  }
-
-  return undefined;
-}
-
-/**
- * Check if an expression is a valid statically-analyzable pattern.
- *
- * Valid patterns:
- * - Starts with `createSearchParams(`
- * - Contains `.extend(` or `.pick(` chains (possibly starting with createSearchParams or a variable)
- * - A variable identifier followed by chaining
- */
-function isValidExpression(expr: string): boolean {
-  // Normalize whitespace
-  const normalized = expr.replace(/\s+/g, ' ').trim();
-
-  // Pattern 1: starts with createSearchParams(
-  if (normalized.startsWith('createSearchParams(')) {
-    return true;
-  }
-
-  // Pattern 2: chain ending with .extend(...) or .pick(...)
-  // This covers: someVar.extend(...), createSearchParams(...).extend(...).pick(...), etc.
-  if (/\.(extend|pick)\s*\(/.test(normalized)) {
-    // Reject ternaries and other conditional patterns
-    if (/\?/.test(normalized) && /:/.test(normalized)) {
-      return false;
-    }
-    // Reject function declarations/expressions
-    if (/^\s*(function|=>|\()/.test(normalized)) {
-      return false;
-    }
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Format an AnalyzeError into a human-readable build error message.
- */
-export function formatAnalyzeError(error: AnalyzeError): string {
-  return [
-    `[timber] Non-analyzable search-params.ts`,
-    ``,
-    `  File: ${error.filePath}`,
-    `  Expression: ${error.expression}`,
-    ``,
-    `  ${error.suggestion}`,
-    ``,
-    `  The framework must be able to statically extract the type from your`,
-    `  search-params.ts at build time. Dynamic values, conditionals, and`,
-    `  arbitrary factory functions prevent this analysis.`,
-  ].join('\n');
-}

package/src/search-params/builtin-codecs.ts

@@ -1,228 +0,0 @@
-/**
- * Built-in search param codecs for common types.
- *
- * These provide zero-dependency alternatives to nuqs parsers for the most
- * common cases: strings, integers, floats, booleans, and string enums.
- *
- * All codecs implement SearchParamCodec<T | null> — returning null when the
- * param is absent or unparseable. Use withDefault() to replace null with a
- * concrete fallback value.
- *
- * Design doc: design/23-search-params.md §"Identified Gaps" #1
- * Task: TIM-362
- */
-
-import type { SearchParamCodec } from './create.js';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Normalize array inputs to a single string (last value wins, matching
- * URLSearchParams.get() semantics). Returns undefined if absent or empty.
- */
-function normalizeInput(value: string | string[] | undefined): string | undefined {
-  if (Array.isArray(value)) {
-    return value.length > 0 ? value[value.length - 1] : undefined;
-  }
-  return value;
-}
-
-// ---------------------------------------------------------------------------
-// parseAsString
-// ---------------------------------------------------------------------------
-
-/**
- * String codec. Returns the raw string value, or null if absent.
- *
- * ```ts
- * import { parseAsString } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ q: parseAsString })
- * // ?q=shoes → { q: 'shoes' }
- * // (absent) → { q: null }
- * ```
- */
-export const parseAsString: SearchParamCodec<string | null> = {
-  parse(value: string | string[] | undefined): string | null {
-    const v = normalizeInput(value);
-    return v !== undefined ? v : null;
-  },
-  serialize(value: string | null): string | null {
-    return value;
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsInteger
-// ---------------------------------------------------------------------------
-
-/**
- * Integer codec. Parses a base-10 integer, or returns null if absent or
- * not a valid integer. Rejects floats, NaN, Infinity, and non-numeric strings.
- *
- * ```ts
- * import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ page: withDefault(parseAsInteger, 1) })
- * // ?page=2 → { page: 2 }
- * // ?page=abc → { page: 1 }
- * // (absent) → { page: 1 }
- * ```
- */
-export const parseAsInteger: SearchParamCodec<number | null> = {
-  parse(value: string | string[] | undefined): number | null {
-    const v = normalizeInput(value);
-    if (v === undefined || v === '') return null;
-    const n = Number(v);
-    if (!Number.isFinite(n) || !Number.isInteger(n)) return null;
-    return n;
-  },
-  serialize(value: number | null): string | null {
-    return value === null ? null : String(value);
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsFloat
-// ---------------------------------------------------------------------------
-
-/**
- * Float codec. Parses a finite number, or returns null if absent or invalid.
- * Rejects NaN and Infinity.
- *
- * ```ts
- * import { parseAsFloat, withDefault } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ price: withDefault(parseAsFloat, 0) })
- * ```
- */
-export const parseAsFloat: SearchParamCodec<number | null> = {
-  parse(value: string | string[] | undefined): number | null {
-    const v = normalizeInput(value);
-    if (v === undefined || v === '') return null;
-    const n = Number(v);
-    if (!Number.isFinite(n)) return null;
-    return n;
-  },
-  serialize(value: number | null): string | null {
-    return value === null ? null : String(value);
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsBoolean
-// ---------------------------------------------------------------------------
-
-/**
- * Boolean codec. Accepts "true"/"1" as true, "false"/"0" as false.
- * Returns null for absent or unrecognized values.
- *
- * ```ts
- * import { parseAsBoolean, withDefault } from '@timber-js/app/search-params'
- *
- * const def = createSearchParams({ debug: withDefault(parseAsBoolean, false) })
- * // ?debug=true → { debug: true }
- * // ?debug=0 → { debug: false }
- * ```
- */
-export const parseAsBoolean: SearchParamCodec<boolean | null> = {
-  parse(value: string | string[] | undefined): boolean | null {
-    const v = normalizeInput(value);
-    if (v === undefined) return null;
-    if (v === 'true' || v === '1') return true;
-    if (v === 'false' || v === '0') return false;
-    return null;
-  },
-  serialize(value: boolean | null): string | null {
-    return value === null ? null : String(value);
-  },
-};
-
-// ---------------------------------------------------------------------------
-// parseAsStringEnum
-// ---------------------------------------------------------------------------
-
-/**
- * String enum codec. Accepts only values in the provided list.
- * Returns null for absent or invalid values.
- *
- * ```ts
- * import { parseAsStringEnum, withDefault } from '@timber-js/app/search-params'
- *
- * const sortCodec = withDefault(
- *   parseAsStringEnum(['price', 'name', 'date']),
- *   'date'
- * )
- * ```
- */
-export function parseAsStringEnum<T extends string>(
-  values: readonly T[]
-): SearchParamCodec<T | null> {
-  const allowed = new Set<string>(values);
-  return {
-    parse(value: string | string[] | undefined): T | null {
-      const v = normalizeInput(value);
-      if (v === undefined) return null;
-      return allowed.has(v) ? (v as T) : null;
-    },
-    serialize(value: T | null): string | null {
-      return value;
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// parseAsStringLiteral
-// ---------------------------------------------------------------------------
-
-/**
- * String literal codec. Functionally identical to parseAsStringEnum but
- * accepts `as const` tuples for narrower type inference.
- *
- * ```ts
- * import { parseAsStringLiteral } from '@timber-js/app/search-params'
- *
- * const sizes = ['sm', 'md', 'lg', 'xl'] as const
- * const codec = parseAsStringLiteral(sizes)
- * // Type: SearchParamCodec<'sm' | 'md' | 'lg' | 'xl' | null>
- * ```
- */
-export function parseAsStringLiteral<const T extends readonly string[]>(
-  values: T
-): SearchParamCodec<T[number] | null> {
-  // Delegates to parseAsStringEnum — same runtime behavior, different type
-  return parseAsStringEnum<T[number]>(values);
-}
-
-// ---------------------------------------------------------------------------
-// withDefault
-// ---------------------------------------------------------------------------
-
-/**
- * Wrap a nullable codec with a default value. When the inner codec returns
- * null, the default is used instead. The output type becomes non-nullable.
- *
- * ```ts
- * import { parseAsInteger, withDefault } from '@timber-js/app/search-params'
- *
- * const page = withDefault(parseAsInteger, 1)
- * // page.parse(undefined) → 1 (not null)
- * // page.parse('5') → 5
- * ```
- */
-export function withDefault<T>(
-  codec: SearchParamCodec<T | null>,
-  defaultValue: T
-): SearchParamCodec<T> {
-  return {
-    parse(value: string | string[] | undefined): T {
-      const result = codec.parse(value);
-      return result === null ? defaultValue : result;
-    },
-    serialize(value: T): string | null {
-      return codec.serialize(value);
-    },
-  };
-}