@timber-js/app 0.2.0-alpha.146 → 0.2.0-alpha.148

package/src/routing/manifest-codegen.ts

@@ -0,0 +1,290 @@
+/**
+ * Route manifest codegen — generates virtual module source for the route
+ * manifest, search-params registry, and global schema.
+ *
+ * Extracted from plugins/routing.ts to keep it under the 500-line budget.
+ * See design/18-build-system.md §"Virtual Modules".
+ *
+ * Task: TIM-1071 item 8
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { collectInterceptionRewrites } from './interception.js';
+import type { RouteTree, SegmentNode, RouteFile } from './types.js';
+import { readFileCached } from './file-cache.js';
+
+// ── Single-file conventions ─────────────────────────────────────────────
+// Each entry maps to a node property that holds a single RouteFile.
+// Order matches the original serializeNode output for byte-identical diffs.
+const SINGLE_FILE_KEYS = [
+  'page',
+  'layout',
+  'middleware',
+  'access',
+  'route',
+  'error',
+  'default',
+  'denied',
+  'params',
+] as const;
+
+// ── Record-shaped conventions ───────────────────────────────────────────
+// Each entry maps to a node property that holds Record<string, RouteFile>.
+const RECORD_FILE_KEYS = [
+  'statusFiles',
+  'jsonStatusFiles',
+  'legacyStatusFiles',
+  'metadataRoutes',
+] as const;
+
+const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+// ── Manifest generation ─────────────────────────────────────────────────
+
+/**
+ * Generate the virtual module source for the route manifest.
+ *
+ * The output is a default-exported object containing the serialized route tree.
+ * All file references use absolute paths (required for virtual modules).
+ */
+export function generateManifestModule(tree: RouteTree, viteRoot: string): string {
+  const imports: string[] = [];
+  let importIndex = 0;
+
+  function addImport(file: RouteFile): string {
+    const varName = `_route${importIndex++}`;
+    imports.push(`const ${varName} = () => import("${file.filePath}");`);
+    return varName;
+  }
+
+  function serializeRouteFile(key: string, file: RouteFile, indent: string): string {
+    const v = addImport(file);
+    return `${indent}${key}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} },`;
+  }
+
+  function serializeRouteFileRecord(
+    key: string,
+    record: Record<string, RouteFile>,
+    indent: string
+  ): string | null {
+    const entries = Object.entries(record);
+    if (entries.length === 0) return null;
+    const inner = entries.map(([name, file]) => {
+      const v = addImport(file);
+      return `${indent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`;
+    });
+    return `${indent}${key}: {\n${inner.join(',\n')}\n${indent}},`;
+  }
+
+  function serializeNode(node: SegmentNode, indent: string): string {
+    const nextIndent = indent + '  ';
+    const parts: string[] = [];
+
+    parts.push(`${nextIndent}segmentName: ${JSON.stringify(node.segmentName)},`);
+    parts.push(`${nextIndent}segmentType: ${JSON.stringify(node.segmentType)},`);
+    parts.push(`${nextIndent}urlPath: ${JSON.stringify(node.urlPath)},`);
+
+    if (node.paramName) {
+      parts.push(`${nextIndent}paramName: ${JSON.stringify(node.paramName)},`);
+    }
+
+    if (node.interceptionMarker) {
+      parts.push(`${nextIndent}interceptionMarker: ${JSON.stringify(node.interceptionMarker)},`);
+    }
+    if (node.interceptedSegmentName) {
+      parts.push(
+        `${nextIndent}interceptedSegmentName: ${JSON.stringify(node.interceptedSegmentName)},`
+      );
+    }
+
+    // Single-file conventions — table-driven to avoid copy-paste drift
+    for (const key of SINGLE_FILE_KEYS) {
+      const file = node[key];
+      if (file) {
+        parts.push(serializeRouteFile(key, file, nextIndent));
+      }
+    }
+
+    // searchParams is now a named export from page.tsx, not a separate file.
+    // The page module's searchParams export is loaded via the page's lazy import.
+    // Runtime registration happens in the route loader using the page module.
+
+    // Record-shaped conventions — table-driven
+    for (const key of RECORD_FILE_KEYS) {
+      const record = node[key];
+      if (record) {
+        const line = serializeRouteFileRecord(key, record, nextIndent);
+        if (line) parts.push(line);
+      }
+    }
+
+    // Children
+    if (node.children.length > 0) {
+      const childNodes = node.children.map((c) => serializeNode(c, nextIndent));
+      parts.push(`${nextIndent}children: [\n${childNodes.join(',\n')}\n${nextIndent}],`);
+    } else {
+      parts.push(`${nextIndent}children: [],`);
+    }
+
+    // Parallel slots
+    const slotKeys = Object.keys(node.slots);
+    if (slotKeys.length > 0) {
+      const slotEntries: string[] = [];
+      for (const slotName of slotKeys) {
+        const slotNode = node.slots[slotName]!;
+        slotEntries.push(
+          `${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + '  ')}`
+        );
+      }
+      parts.push(`${nextIndent}slots: {\n${slotEntries.join(',\n')}\n${nextIndent}},`);
+    } else {
+      parts.push(`${nextIndent}slots: {},`);
+    }
+
+    return `${indent}{\n${parts.join('\n')}\n${indent}}`;
+  }
+
+  const rootSerialized = serializeNode(tree.root, '  ');
+
+  let proxyLine = '';
+  if (tree.proxy) {
+    const v = addImport(tree.proxy);
+    proxyLine = `  proxy: { load: ${v}, filePath: ${JSON.stringify(tree.proxy.filePath)} },`;
+  }
+
+  let globalErrorLine = '';
+  if (tree.globalError) {
+    const v = addImport(tree.globalError);
+    globalErrorLine = `  globalError: { load: ${v}, filePath: ${JSON.stringify(tree.globalError.filePath)} },`;
+  }
+
+  const rewrites = collectInterceptionRewrites(tree.root);
+  const rewritesLine =
+    rewrites.length > 0
+      ? `  interceptionRewrites: ${JSON.stringify(rewrites.map((r) => ({ interceptedPattern: r.interceptedPattern, interceptingPrefix: r.interceptingPrefix })))},`
+      : '';
+
+  const code = [
+    '// Auto-generated route manifest — do not edit.',
+    '// Generated by timber-routing plugin.',
+    '',
+    ...imports,
+    '',
+    'const manifest = {',
+    `  viteRoot: ${JSON.stringify(viteRoot)},`,
+    proxyLine,
+    globalErrorLine,
+    rewritesLine,
+    `  root: ${rootSerialized},`,
+    '};',
+    '',
+    'export default manifest;',
+  ]
+    .filter((line) => line !== undefined && line !== '')
+    .join('\n');
+
+  return code;
+}
+
+// ── Search-params registry ──────────────────────────────────────────────
+
+/**
+ * Walk the route tree and collect every page that exports a
+ * `searchParams` definition, then emit a module that statically imports
+ * each export and registers it into the shared search-params registry.
+ */
+export function generateSearchParamsRegistryModule(tree: RouteTree): string {
+  const entries: Array<{ urlPath: string; filePath: string }> = [];
+
+  function walk(node: SegmentNode): void {
+    if (node.page) {
+      if (node.params && fileHasSearchParamsExport(node.params.filePath)) {
+        entries.push({ urlPath: node.urlPath, filePath: node.params.filePath });
+      } else if (fileHasSearchParamsExport(node.page.filePath)) {
+        entries.push({ urlPath: node.urlPath, filePath: node.page.filePath });
+      }
+    }
+    for (const child of node.children) walk(child);
+    for (const slot of Object.values(node.slots)) walk(slot);
+  }
+  walk(tree.root);
+
+  entries.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
+
+  const lines: string[] = [];
+  lines.push('// Auto-generated search-params registry — do not edit.');
+  lines.push('// Generated by timber-routing plugin (TIM-830).');
+  lines.push('');
+  lines.push("import { registerSearchParams } from '@timber-js/app/search-params';");
+  lines.push('');
+
+  entries.forEach((entry, i) => {
+    lines.push(`import { searchParams as r${i} } from ${JSON.stringify(entry.filePath)};`);
+  });
+  lines.push('');
+
+  entries.forEach((entry, i) => {
+    lines.push(`registerSearchParams(${JSON.stringify(entry.urlPath)}, r${i});`);
+  });
+  lines.push('');
+
+  lines.push('export {};');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function fileHasSearchParamsExport(filePath: string): boolean {
+  try {
+    if (!existsSync(filePath)) return false;
+    const content = readFileCached(filePath);
+    return (
+      /export\s+(const|let|var)\s+searchParams\b/.test(content) ||
+      /export\s*\{[^}]*\bsearchParams\b[^}]*\}/.test(content)
+    );
+  } catch {
+    return false;
+  }
+}
+
+// ── Schema module ───────────────────────────────────────────────────────
+
+/**
+ * Generate the virtual:timber-schema module.
+ *
+ * When app/schema.{ts,tsx,js,jsx} exists, generates a module that
+ * imports the schema and resolves its segmentParams codecs into a
+ * bare-name codec map for runtime coercion.
+ */
+export function generateSchemaModule(appDir: string): string {
+  let schemaPath: string | null = null;
+  for (const ext of SCHEMA_EXTENSIONS) {
+    const candidate = join(appDir, `schema${ext}`);
+    if (existsSync(candidate)) {
+      schemaPath = candidate;
+      break;
+    }
+  }
+
+  if (!schemaPath) {
+    return [
+      '// Auto-generated schema loader — no app/schema.ts found.',
+      'export default null;',
+    ].join('\n');
+  }
+
+  return [
+    '// Auto-generated schema loader — do not edit.',
+    '// Generated by timber-routing plugin (TIM-931).',
+    '',
+    `import schema from ${JSON.stringify(schemaPath)};`,
+    `import { resolveSchemaCodecs } from '@timber-js/app/params';`,
+    '',
+    'const globalCodecs = schema?.segmentParams',
+    '  ? resolveSchemaCodecs(schema.segmentParams)',
+    '  : null;',
+    '',
+    'export default globalCodecs;',
+  ].join('\n');
+}

package/src/routing/scanner.ts

@@ -22,19 +22,7 @@ import { classifySegment } from './segment-classify.js';
 import { DEFAULT_PAGE_EXTENSIONS } from './types.js';
 import { classifyMetadataRoute, isDynamicMetadataExtension } from '../server/metadata-routes.js';
 import { swallow } from '../server/logger.js';
-
-/**
- * Pattern matching encoded path delimiters that must be rejected during route discovery.
- * %2F / %2f (forward slash) and %5C / %5c (backslash) can cause route collisions
- * when decoded. See design/13-security.md §"Encoded separators rejected".
- */
-const ENCODED_SEPARATOR_PATTERN = /%(?:2[fF]|5[cC])/;
-
-/**
- * Pattern matching encoded null bytes (%00) that must be rejected.
- * See design/13-security.md §"Null bytes rejected".
- */
-const ENCODED_NULL_PATTERN = /%00/;
+import { ENCODED_SEPARATOR_RE, NULL_BYTE_RE } from '../server/canonicalize.js';
 
 /**
  * File convention names that use pageExtensions (can be .tsx, .ts, .jsx, .js, .mdx, etc.)
@@ -177,44 +165,26 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
 
     // Page-extension conventions (page, layout, error, default, denied)
     if (PAGE_EXT_CONVENTIONS.has(name) && extSet.has(ext)) {
-      const file: RouteFile = { filePath: fullPath, extension: ext };
-      switch (name) {
-        case 'page':
-          node.page = file;
-          break;
-        case 'layout':
-          node.layout = file;
-          break;
-        case 'error':
-          node.error = file;
-          break;
-        case 'default':
-          node.default = file;
-          break;
-        case 'denied':
-          node.denied = file;
-          break;
+      const key = name as 'page' | 'layout' | 'error' | 'default' | 'denied';
+      const existing = node[key];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
       }
+      node[key] = { filePath: fullPath, extension: ext };
       continue;
     }
 
-    // Fixed conventions (middleware, access, route) — always .ts or .tsx
-    if (FIXED_CONVENTIONS.has(name) && /\.?[jt]sx?$/.test(ext)) {
-      const file: RouteFile = { filePath: fullPath, extension: ext };
-      switch (name) {
-        case 'middleware':
-          node.middleware = file;
-          break;
-        case 'access':
-          node.access = file;
-          break;
-        case 'route':
-          node.route = file;
-          break;
-        case 'params':
-          node.params = file;
-          break;
+    // Fixed conventions (middleware, access, route, params) — only
+    // .ts/.tsx/.js/.jsx, never pageExtensions like .mdx. The regex is
+    // anchored: mts/cts/mjs/cjs (and stray tail matches like `.foots`)
+    // are NOT recognized. See design/07-routing.md §"Page Extensions".
+    if (FIXED_CONVENTIONS.has(name) && /^[jt]sx?$/.test(ext)) {
+      const key = name as 'middleware' | 'access' | 'route' | 'params';
+      const existing = node[key];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
       }
+      node[key] = { filePath: fullPath, extension: ext };
       continue;
     }
 
@@ -233,6 +203,10 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       if (!node.statusFiles) {
         node.statusFiles = {};
       }
+      const existing = node.statusFiles[name];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
+      }
       node.statusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
@@ -242,6 +216,10 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       if (!node.legacyStatusFiles) {
         node.legacyStatusFiles = {};
       }
+      const existing = node.legacyStatusFiles[name];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
+      }
       node.legacyStatusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
@@ -249,6 +227,8 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
     // Metadata route files (sitemap.ts, robots.ts, icon.tsx, opengraph-image.tsx, etc.)
     // Both static (.xml, .txt, .png, .ico, etc.) and dynamic (.ts, .tsx) files are recognized.
     // When both exist for the same base name, dynamic takes precedence.
+    // Two files of the SAME kind (static+static or dynamic+dynamic) are a
+    // build error — picking one by readdir order is platform-dependent.
     // See design/16-metadata.md §"Metadata Routes"
     const metaInfo = classifyMetadataRoute(entry);
     if (metaInfo) {
@@ -257,11 +237,13 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       }
       const existing = node.metadataRoutes[name];
       if (existing) {
-        // Dynamic > static precedence: only overwrite if the new file is dynamic
-        // or the existing file is static (dynamic always wins).
         const existingIsDynamic = isDynamicMetadataExtension(name, existing.extension);
         const newIsDynamic = isDynamicMetadataExtension(name, ext);
-        if (newIsDynamic || !existingIsDynamic) {
+        if (existingIsDynamic === newIsDynamic) {
+          throwDuplicateConvention(name, existing.filePath, fullPath);
+        }
+        // Dynamic > static precedence: overwrite only when the new file is dynamic.
+        if (newIsDynamic) {
           node.metadataRoutes[name] = { filePath: fullPath, extension: ext };
         }
       } else {
@@ -281,6 +263,26 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
   }
 }
 
+/**
+ * Throw a build error for two files claiming the same convention slot in
+ * one segment (e.g. page.tsx + page.jsx). Which file readdir returns first
+ * is platform-dependent (APFS sorts entries, ext4 does not) — silently
+ * picking one would let macOS dev and Linux CI serve different
+ * implementations of the same route.
+ */
+function throwDuplicateConvention(
+  convention: string,
+  firstPath: string,
+  secondPath: string
+): never {
+  throw new Error(
+    `Build error: duplicate '${convention}' files in the same route segment.\n` +
+      `  File 1: ${firstPath}\n` +
+      `  File 2: ${secondPath}\n` +
+      `Each segment may define '${convention}' at most once. Remove one of the files.`
+  );
+}
+
 /**
  * Recursively scan child directories and build the segment tree.
  */
@@ -305,17 +307,17 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
     // Reject directories with encoded path delimiters or null bytes.
     // These can cause route collisions when decoded at the URL boundary.
     // See design/13-security.md §"Encoded separators rejected" and §"Null bytes rejected".
-    if (ENCODED_SEPARATOR_PATTERN.test(entry)) {
+    if (ENCODED_SEPARATOR_RE.test(entry)) {
       throw new Error(
-        `Build error: directory name contains an encoded path delimiter (%%2F or %%5C).\n` +
+        `Build error: directory name contains an encoded path delimiter (%2F or %5C).\n` +
           `  Directory: ${fullPath}\n` +
           `Encoded separators in directory names cause route collisions when decoded. ` +
           `Rename the directory to remove the encoded delimiter.`
       );
     }
-    if (ENCODED_NULL_PATTERN.test(entry)) {
+    if (NULL_BYTE_RE.test(entry)) {
       throw new Error(
-        `Build error: directory name contains an encoded null byte (%%00).\n` +
+        `Build error: directory name contains an encoded null byte (%00).\n` +
           `  Directory: ${fullPath}\n` +
           `Encoded null bytes in directory names are not allowed. ` +
           `Rename the directory to remove the null byte encoding.`
@@ -359,57 +361,60 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
  * Two route groups like (auth)/login/page.tsx and (marketing)/login/page.tsx both claim
  * /login — the scanner must detect and reject this at build time.
  *
- * Parallel slots are excluded from collision detection — they intentionally coexist at
- * the same URL path as their parent (that's the whole point of parallel routes).
+ * Each parallel slot is validated as its OWN collision space: a slot's pages
+ * intentionally share URL paths with the parent tree (that's the point of
+ * parallel routes), but two route groups INSIDE one slot claiming the same
+ * URL — e.g. @side/(a)/x/page.tsx + @side/(b)/x/page.tsx — still collide.
  */
 function validateRouteGroupCollisions(root: SegmentNode): void {
   // Map from urlPath → { filePath, source } for the first page/route seen at that path
-  const seen = new Map<string, { filePath: string; segmentPath: string }>();
-  collectRoutableLeaves(root, seen, '', false);
+  collectRoutableLeaves(root, new Map(), '');
 }
 
 /**
  * Walk the segment tree and collect all routable leaves (page or route files),
- * throwing on collision. Slots are tracked in their own collision space since
- * they are parallel routes that intentionally share URL paths with their parent.
+ * throwing on collision. Each slot recurses with a FRESH collision map —
+ * slots are parallel routes that intentionally share URL paths with their
+ * parent tree, but collisions within a single slot are real errors.
  */
 function collectRoutableLeaves(
   node: SegmentNode,
   seen: Map<string, { filePath: string; segmentPath: string }>,
-  segmentPath: string,
-  insideSlot: boolean
+  segmentPath: string
 ): void {
+  // Intercepting routes are resolved by the slot resolver, not URL matching,
+  // and their computed urlPaths intentionally mirror other routes (e.g. two
+  // interceptors in one slot both produce /gallery/[id]). Skip them entirely.
+  if (node.segmentType === 'intercepting') return;
+
   const currentPath = segmentPath
     ? `${segmentPath}/${node.segmentName}`
     : node.segmentName || '(root)';
 
-  // Only check collisions for non-slot pages — slots intentionally share URL paths
-  if (!insideSlot) {
-    const routableFile = node.page ?? node.route;
-    if (routableFile) {
-      const existing = seen.get(node.urlPath);
-      if (existing) {
-        throw new Error(
-          `Build error: route collision — multiple route groups produce a page/route at the same URL path.\n` +
-            `  URL path: ${node.urlPath}\n` +
-            `  File 1:   ${existing.filePath} (via ${existing.segmentPath})\n` +
-            `  File 2:   ${routableFile.filePath} (via ${currentPath})\n` +
-            `Each URL path must map to exactly one page or route handler. ` +
-            `Rename or move one of the conflicting files.`
-        );
-      }
-      seen.set(node.urlPath, { filePath: routableFile.filePath, segmentPath: currentPath });
+  const routableFile = node.page ?? node.route;
+  if (routableFile) {
+    const existing = seen.get(node.urlPath);
+    if (existing) {
+      throw new Error(
+        `Build error: route collision — multiple route groups produce a page/route at the same URL path.\n` +
+          `  URL path: ${node.urlPath}\n` +
+          `  File 1:   ${existing.filePath} (via ${existing.segmentPath})\n` +
+          `  File 2:   ${routableFile.filePath} (via ${currentPath})\n` +
+          `Each URL path must map to exactly one page or route handler. ` +
+          `Rename or move one of the conflicting files.`
+      );
     }
+    seen.set(node.urlPath, { filePath: routableFile.filePath, segmentPath: currentPath });
   }
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutableLeaves(child, seen, currentPath, insideSlot);
+    collectRoutableLeaves(child, seen, currentPath);
   }
 
-  // Recurse into slots — each slot is its own parallel route space
+  // Recurse into slots — each slot gets a fresh map (its own collision space)
   for (const slotNode of Object.values(node.slots)) {
-    collectRoutableLeaves(slotNode, seen, currentPath, true);
+    collectRoutableLeaves(slotNode, new Map(), currentPath);
   }
 }
 

package/src/routing/schema-validation.ts

@@ -7,7 +7,7 @@
  * Design doc: design/41-global-params.md
  */
 
-import { readFileSync } from 'node:fs';
+import { readFileCached } from './file-cache.js';
 import type { RouteTree, SegmentNode } from './types.js';
 import { findSchemaFile, parseExistingSchemaKeys } from '../cli-schema-sync.js';
 import { classifyUrlSegment } from './segment-classify.js';
@@ -66,7 +66,7 @@ export function validateSchemaAgainstRoutes(tree: RouteTree, appDir: string): Sc
   const schemaPath = findSchemaFile(appDir);
   if (!schemaPath) return [];
 
-  const content = readFileSync(schemaPath, 'utf-8');
+  const content = readFileCached(schemaPath);
   const schemaKeys = parseExistingSchemaKeys(content);
 
   if (schemaKeys.length === 0) return [];

package/src/schema-bridge.ts

@@ -85,6 +85,63 @@ export function isCodec(value: unknown): value is Codec<unknown> {
   );
 }
 
+// ---------------------------------------------------------------------------
+// fromParamSchema — bridge from Standard Schema to Codec<T> for route params
+// ---------------------------------------------------------------------------
+
+/**
+ * Bridge a Standard Schema to a Codec for route params.
+ * Parse throws on failure (invalid param → 404). Serialize returns string.
+ */
+export function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      const result = validateSync(schema, value);
+      if (!result.issues) {
+        return result.value;
+      }
+      const messages = result.issues.map((i) => i.message).join(', ');
+      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);
+    },
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) return null;
+      if (Array.isArray(value)) return value.join('/');
+      return String(value);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// resolveCodecOrSchema — generic resolver for any codec-or-schema field
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a field value to a Codec. Accepts Codec<T>, StandardSchemaV1<T>,
+ * or (for route params) auto-wraps via fromParamSchema.
+ *
+ * @param fieldName - used in error messages
+ * @param value - the codec or schema to resolve
+ * @param mode - 'param' uses fromParamSchema (throws on parse failure),
+ *               'search' uses fromSchema (falls back to default on failure)
+ */
+export function resolveCodecOrSchema(
+  fieldName: string,
+  value: unknown,
+  mode: 'param' | 'search' = 'search'
+): Codec<unknown> {
+  if (isCodec(value)) return value;
+  if (isStandardSchema(value)) {
+    return mode === 'param'
+      ? fromParamSchema(fieldName, value)
+      : (fromSchema(value) as Codec<unknown>);
+  }
+  throw new Error(
+    `[timber] Field '${fieldName}' is not a valid codec or Standard Schema. ` +
+      `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +
+      `(Zod, Valibot, ArkType).`
+  );
+}
+
 // ---------------------------------------------------------------------------
 // fromSchema — bridge from Standard Schema to Codec<T>
 // ---------------------------------------------------------------------------
@@ -119,13 +176,17 @@ export function fromSchema<T>(schema: StandardSchemaV1<T>): Codec<T> {
         return result.value;
       }
 
-      // On failure, try parsing undefined to get the default
+      // On failure, try parsing undefined to get the default.
+      // Re-validate each time so factory defaults (e.g. .default(() => []))
+      // produce fresh values.
       const defaultResult = validateSync(schema, undefined);
       if (!defaultResult.issues) {
         return defaultResult.value;
       }
 
-      // No default available — return undefined (codec design choice)
+      // No default available — return undefined (codec design choice).
+      // Callers like defineSearchParams validate this at definition time
+      // via validateSchemaDefaults() to catch it early.
       return undefined as T;
     },