@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/routing/codegen.ts

@@ -9,38 +9,28 @@
  */
 
 import { existsSync } from 'node:fs';
-import { join, relative, posix } from 'node:path';
-import type { RouteTree, SegmentNode } from './types.js';
-
-/** A single route entry extracted from the segment tree. */
-interface RouteEntry {
-  /** URL path pattern (e.g. "/products/[id]") */
-  urlPath: string;
-  /** Accumulated params from all ancestor dynamic segments */
-  params: ParamEntry[];
-  /** Whether this route has a co-located search-params.ts */
-  hasSearchParams: boolean;
-  /** Absolute path to search-params.ts (for computing relative import paths) */
-  searchParamsAbsPath?: string;
-  /** Whether this is an API route (route.ts) vs page route */
-  isApiRoute: boolean;
-}
-
-interface ParamEntry {
-  name: string;
-  type: 'string' | 'string[]' | 'string[] | undefined';
-}
+import { join, relative } from 'node:path';
+import type { RouteTree, SegmentNode } from './types.ts';
+import type { ParamEntry, RouteEntry } from './codegen-types.ts';
+import { buildSchemaParamType } from './codegen-shared.ts';
+import { effectiveUrlSegment, type UrlSegmentIdentity } from './segment-classify.ts';
+import { formatLinkCatchAllOverloads, formatTypedLinkOverloads } from './link-codegen.ts';
 
 /** Options for route map generation. */
 export interface CodegenOptions {
-  /** Absolute path to the app/ directory. Required for search-params.ts detection. */
+  /** Absolute path to the app/ directory. Required for page searchParams detection. */
   appDir?: string;
   /**
    * Absolute path to the directory where the .d.ts file will be written.
-   * Used to compute correct relative import paths for search-params.ts files.
+   * Used to compute correct relative import paths for page files.
    * Defaults to appDir when not provided (preserves backward compat for tests).
    */
   outputDir?: string;
+  /**
+   * Whether a global schema (app/schema.ts) exists.
+   * Auto-detected from appDir when not explicitly set.
+   */
+  hasSchema?: boolean;
 }
 
 /**
@@ -50,8 +40,11 @@ export interface CodegenOptions {
  * interface that maps every route path to its params and searchParams shape.
  */
 export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}): string {
+  // Auto-detect schema from appDir when not explicitly set
+  const hasSchema = options.hasSchema ?? detectSchema(options.appDir);
+
   const routes: RouteEntry[] = [];
-  collectRoutes(tree.root, [], options.appDir, routes);
+  collectRoutes(tree.root, [], '', routes, hasSchema, false);
 
   // Sort routes alphabetically for deterministic output
   routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -59,7 +52,18 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
   // When outputDir differs from appDir, import paths must be relative to outputDir
   const importBase = options.outputDir ?? options.appDir;
 
-  return formatDeclarationFile(routes, importBase);
+  return formatDeclarationFile(routes, importBase, hasSchema, options.appDir);
+}
+
+/** Schema file extensions to check, in priority order. */
+const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
+
+/**
+ * Detect whether app/schema.{ts,tsx,js,jsx} exists.
+ */
+function detectSchema(appDir: string | undefined): boolean {
+  if (!appDir) return false;
+  return SCHEMA_EXTENSIONS.some((ext) => existsSync(join(appDir, `schema${ext}`)));
 }
 
 /**
@@ -71,15 +75,32 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
 function collectRoutes(
   node: SegmentNode,
   ancestorParams: ParamEntry[],
-  appDir: string | undefined,
-  routes: RouteEntry[]
+  parentTreePath: string,
+  routes: RouteEntry[],
+  hasSchema: boolean,
+  insideSlot: boolean,
+  insideIntercepting = false
 ): void {
-  // Accumulate params from this segment
+  // Build the tree path (includes groups, slots — uniquely identifies this segment).
+  // Root node has empty segmentName, producing treePath = ''.
+  const treePath = node.segmentName ? `${parentTreePath}/${node.segmentName}` : parentTreePath;
+  // Accumulate params from this segment.
+  //
+  // The segment is read through `effectiveUrlSegment` for the same reason the
+  // runtime coercer is: an intercepting node's own `segmentType` is
+  // 'intercepting' and its `paramName` is unset — the param it binds lives in
+  // the intercepted name (`(.)[albumSlug]` → `[albumSlug]`). Reading the node
+  // directly emitted `{}` for a segment the router does bind and coerce, so
+  // the types disagreed with the values for every intercepting page with a
+  // dynamic intercepted segment, and for its descendants, which lost the
+  // ancestor param too.
+  const urlSegment = effectiveUrlSegment(node);
   const params = [...ancestorParams];
-  if (node.paramName) {
+  if (urlSegment.paramName) {
     params.push({
-      name: node.paramName,
-      type: paramTypeForSegment(node.segmentType),
+      name: urlSegment.paramName,
+      bracketName: bracketNameForSegment(urlSegment),
+      type: paramTypeForSegment(urlSegment.segmentType),
     });
   }
 
@@ -87,41 +108,104 @@ function collectRoutes(
   const isPage = !!node.page;
   const isApiRoute = !!node.route;
 
-  if (isPage || isApiRoute) {
+  // A segment that hosts code but is not itself addressable — a layout,
+  // middleware, or access check above the leaf — still gets a `$segment`
+  // module, so `getSegmentParams(SEGMENT_PATH)` is callable from it and needs
+  // a matching typed overload. Emitting only leaves left those call sites on
+  // the broad `Record<string, string | string[]>` signature, which since
+  // TIM-1342 (which deleted `defineSegmentParams`) is their ONLY typed path.
+  // design/41-global-params.md's Type Summary promises layouts and middleware
+  // exact accumulated params.
+  //
+  // `isRoutable: false` keeps them out of the urlPath-keyed emissions — the
+  // `Routes` interface and `<Link>` variants — where they would publish a URL
+  // that no request can reach. They belong only to the segmentPath-keyed
+  // APIs: `getSegmentParams`, `useSegmentParams`, `TimberSegmentParams`.
+  const hostsCode = !!node.layout || !!node.middleware || !!node.access;
+
+  if (isPage || isApiRoute || hostsCode) {
     const entry: RouteEntry = {
       urlPath: node.urlPath,
-      params: [...params],
-      hasSearchParams: false,
+      segmentPath: treePath || '/',
+      params,
       isApiRoute,
+      isRoutable: isPage || isApiRoute,
+      isSlotRoute: insideSlot,
+      isInterceptingRoute: insideIntercepting,
+      hasSchema,
     };
 
-    // Detect co-located search-params.ts
-    if (appDir && isPage) {
-      const segmentDir = resolveSegmentDir(appDir, node);
-      const searchParamsFile = findSearchParamsFile(segmentDir);
-      if (searchParamsFile) {
-        entry.hasSearchParams = true;
-        entry.searchParamsAbsPath = searchParamsFile;
-      }
-    }
-
     routes.push(entry);
   }
 
-  // Recurse into children
+  // Recurse into children. An intercepting subtree is flagged, and the flag is
+  // sticky — the descendants are where the false URLs are. See
+  // `RouteEntry.isInterceptingRoute` for what the flag drops and why dedupe
+  // alone was not enough.
   for (const child of node.children) {
-    collectRoutes(child, params, appDir, routes);
+    const childIntercepting = insideIntercepting || child.segmentType === 'intercepting';
+    collectRoutes(child, params, treePath, routes, hasSchema, insideSlot, childIntercepting);
   }
 
   // Recurse into slots (they share the parent's URL path, but may have their own pages)
-  for (const [, slot] of node.slots) {
-    collectRoutes(slot, params, appDir, routes);
+  for (const slot of Object.values(node.slots)) {
+    collectRoutes(slot, params, treePath, routes, hasSchema, true, insideIntercepting);
+  }
+}
+
+/**
+ * Dedupe route entries by urlPath for urlPath-keyed emissions (the Routes
+ * interface and typed Link variants).
+ *
+ * Parallel-slot pages share their parent's urlPath; emitting one entry per
+ * slot page produced duplicate interface keys (TS2300/TS2717 under
+ * skipLibCheck:false) and duplicate overloads. The non-slot entry is the
+ * canonical one; when only slot entries exist (parent has no page), the
+ * lexicographically smallest segmentPath wins so output is independent of
+ * slot scan order.
+ *
+ * The loser is discarded outright. It used to donate its `searchParams`
+ * definition to the winner, because a slot could carry one the parent page
+ * lacked; since TIM-1343 no route entry carries a searchParams definition at
+ * all, there is nothing left to merge.
+ *
+ * segmentPath-keyed emissions (getSegmentParams, useSegmentParams,
+ * TimberSegmentParams) must NOT use this — segmentPaths are already unique
+ * and slot entries feed those APIs directly.
+ */
+function dedupeRoutesByUrlPath(routes: RouteEntry[]): RouteEntry[] {
+  const byPath = new Map<string, RouteEntry>();
+  for (const route of routes) {
+    const existing = byPath.get(route.urlPath);
+    if (!existing) {
+      byPath.set(route.urlPath, route);
+      continue;
+    }
+
+    const routeWins =
+      (existing.isSlotRoute && !route.isSlotRoute) ||
+      (!!existing.isSlotRoute === !!route.isSlotRoute &&
+        route.segmentPath.localeCompare(existing.segmentPath) < 0);
+    byPath.set(route.urlPath, routeWins ? route : existing);
   }
+  return [...byPath.values()];
 }
 
 /**
  * Determine the TypeScript type for a segment's param.
  */
+/**
+ * Derive the bracket key for schema/codegen lookup.
+ * For bare segments like `[id]` this is the segmentName itself.
+ * For affixed segments like `img-[id].png` this is `[id]` — the bare bracket form.
+ */
+function bracketNameForSegment(node: UrlSegmentIdentity): string {
+  if (node.paramPrefix || node.paramSuffix) {
+    return `[${node.paramName}]`;
+  }
+  return node.segmentName;
+}
+
 function paramTypeForSegment(segmentType: string): ParamEntry['type'] {
   switch (segmentType) {
     case 'catch-all':
@@ -134,41 +218,71 @@ function paramTypeForSegment(segmentType: string): ParamEntry['type'] {
 }
 
 /**
- * Resolve the absolute directory path for a segment node.
+ * Emit the schema-based type exports: TimberSegmentParams, TimberRoute,
+ * AllSegmentParams, RoutesWithParams.
+ *
+ * These types use InferCodecType references so they stay in sync with
+ * the schema without hardcoding resolved types.
  *
- * Reconstructs the filesystem path by walking from appDir through
- * the segment names encoded in the urlPath, accounting for groups and slots.
+ * Design doc: design/41-global-params.md §Codegen Output
  */
-function resolveSegmentDir(appDir: string, node: SegmentNode): string {
-  // The node's page/route file path gives us the actual directory
-  const file = node.page ?? node.route;
-  if (file) {
-    // The file is in the segment directory — go up one level
-    const parts = file.filePath.split('/');
-    parts.pop(); // remove filename
-    return parts.join('/');
-  }
-  // Fallback: construct from urlPath (imprecise for groups, but acceptable)
-  return appDir;
-}
+function formatSchemaTypes(routes: RouteEntry[]): string[] {
+  const lines: string[] = [];
 
-/**
- * Find a search-params.ts file in a directory.
- */
-function findSearchParamsFile(dirPath: string): string | undefined {
-  for (const ext of ['ts', 'tsx']) {
-    const candidate = join(dirPath, `search-params.${ext}`);
-    if (existsSync(candidate)) {
-      return candidate;
+  lines.push('/** Union of all valid route patterns. */');
+  lines.push('export type TimberRoute = keyof TimberSegmentParams;');
+  lines.push('');
+  lines.push('/** Maps each segment path to its accumulated segment params. */');
+  lines.push('export interface TimberSegmentParams {');
+
+  for (const route of routes) {
+    if (route.params.length === 0) {
+      lines.push(`  '${route.segmentPath}': {};`);
+    } else {
+      lines.push(`  '${route.segmentPath}': {`);
+      for (const p of route.params) {
+        lines.push(`    ${p.name}: ${buildSchemaParamType(p)};`);
+      }
+      lines.push('  };');
     }
   }
-  return undefined;
+
+  lines.push('}');
+  lines.push('');
+
+  // AllSegmentParams — flat union of all param types across all routes
+  lines.push('/** All segment params (union of all route params). */');
+  lines.push('export type AllSegmentParams = {');
+  lines.push(
+    '  [K in keyof TimberSegmentParams as TimberSegmentParams[K] extends Record<string, never>'
+  );
+  lines.push('    ? never');
+  lines.push('    : K]: TimberSegmentParams[K];');
+  lines.push('} extends infer U');
+  lines.push('  ? { [K in keyof U[keyof U]]: U[keyof U][K] }');
+  lines.push('  : never;');
+  lines.push('');
+
+  // RoutesWithParams — filter routes by required param keys
+  lines.push(
+    '/** Filters TimberRoute to routes whose accumulated params include all listed keys. */'
+  );
+  lines.push('export type RoutesWithParams<K extends keyof AllSegmentParams> = {');
+  lines.push('  [R in TimberRoute]: K extends keyof TimberSegmentParams[R] ? R : never;');
+  lines.push('}[TimberRoute];');
+
+  return lines;
 }
 
 /**
  * Format the collected routes into a TypeScript declaration file.
  */
-function formatDeclarationFile(routes: RouteEntry[], importBase?: string): string {
+function formatDeclarationFile(
+  routes: RouteEntry[],
+  importBase?: string,
+  hasSchema?: boolean,
+  appDir?: string
+): string {
   const lines: string[] = [];
 
   lines.push('// This file is auto-generated by timber.js route map codegen.');
@@ -180,217 +294,220 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
   // (removing exports like bindUseQueryStates that aren't listed here).
   lines.push('export {};');
   lines.push('');
+
+  if (hasSchema) {
+    // Schema-based codegen: import schema and InferCodecType
+    // Compute the schema import path relative to the output directory
+    const schemaImport =
+      appDir && importBase
+        ? './' + relative(importBase, join(appDir, 'schema')).replace(/\\/g, '/')
+        : '../app/schema';
+    lines.push(`import type schema from '${schemaImport}';`);
+    lines.push("import type { InferCodecType, SegmentParamCodec } from '@timber-js/app/params';");
+    lines.push('');
+    // Collect all unique bracket keys from routes for key validation
+    const allBracketKeys = new Set<string>();
+    for (const route of routes) {
+      for (const p of route.params) {
+        allBracketKeys.add(p.bracketName);
+      }
+    }
+
+    // Augment the ValidDynamicSegmentKeysRegistry so defineSchema constrains keys
+    // to known filesystem segments. Unknown keys produce inline TS errors.
+    if (allBracketKeys.size > 0) {
+      lines.push("declare module '@timber-js/app/params' {");
+      lines.push('  interface ValidDynamicSegmentKeysRegistry {');
+      for (const key of [...allBracketKeys].sort()) {
+        lines.push(`    ${JSON.stringify(key)}: true;`);
+      }
+      lines.push('  }');
+      lines.push('}');
+      lines.push('');
+    }
+    // Guard: detect when the schema or params imports silently degraded to
+    // `any` because TypeScript could not resolve the import specifier.
+    // In a .d.ts an unresolved import does NOT error — every downstream
+    // type silently becomes `any`, which satisfies every assertion. Only
+    // an explicit IsAny check catches it.
+    lines.push('type _IsAny<T> = 0 extends 1 & T ? true : false;');
+    lines.push('type _AssertSchemaNotAny<_T extends false = _IsAny<typeof schema>> = true;');
+    lines.push('type _AssertCodecTypeNotAny<_T extends false = _IsAny<SegmentParamCodec>> = true;');
+    lines.push('');
+    // Type-level validation: each schema value must be a Codec or Standard Schema.
+    // Running `pnpm run typecheck` will surface errors for invalid values.
+    lines.push('type _AssertSchemaValues = {');
+    lines.push(
+      "  [K in keyof typeof schema['segmentParams']]: typeof schema['segmentParams'][K] extends SegmentParamCodec ? true : ['Error: value for', K, 'is not a valid Codec or Standard Schema'];"
+    );
+    lines.push('};');
+    // Generic constraint enforces that all values are `true` — if any value is
+    // an error tuple, TS reports a real diagnostic instead of silently computing it.
+    lines.push(
+      'type _EnforceSchemaValues<_T extends Record<string, true> = _AssertSchemaValues> = true;'
+    );
+    lines.push('');
+  }
+
+  // urlPath-keyed emissions use the deduped list (slot pages share their
+  // parent's urlPath); segmentPath-keyed emissions below keep all entries.
+  //
+  // Intercepting subtrees are dropped outright rather than deduped: their
+  // computed urlPath is not a route any request can reach, so a path that
+  // happens NOT to collide with a real one would otherwise be published as a
+  // real route. See `RouteEntry.isInterceptingRoute`.
+  const uniqueByUrlPath = dedupeRoutesByUrlPath(
+    routes.filter((r) => r.isRoutable && !r.isInterceptingRoute)
+  );
+
   lines.push("declare module '@timber-js/app' {");
   lines.push('  interface Routes {');
 
-  for (const route of routes) {
-    const paramsType = formatParamsType(route.params);
-    const searchParamsType = formatSearchParamsType(route, importBase);
+  // TIM-1343: no `searchParams` member. With `params.ts` gone there is no
+  // convention file to read a definition from, so the framework has nothing
+  // to type it with — and an always-`{}` member is a claim that every route
+  // has no search params, which is false. Search-param types now come from
+  // the definition object itself, wherever the app chooses to keep it.
+  for (const route of uniqueByUrlPath) {
+    const paramsType = formatParamsType(route.params, hasSchema);
 
     lines.push(`    '${route.urlPath}': {`);
-    lines.push(`      params: ${paramsType}`);
-    lines.push(`      searchParams: ${searchParamsType}`);
+    lines.push(`      segmentParams: ${paramsType}`);
     lines.push(`    }`);
   }
 
   lines.push('  }');
+
+  // When a global schema exists, emit segment param types inside the
+  // @timber-js/app module augmentation so that declare module blocks
+  // for @timber-js/app/server and @timber-js/app/client can reference
+  // AllSegmentParams via `import type { AllSegmentParams } from '@timber-js/app'`.
+  if (hasSchema) {
+    lines.push('');
+    lines.push(...formatSchemaTypes(routes).map((l) => `  ${l}`));
+  }
+
   lines.push('}');
   lines.push('');
 
-  // Generate @timber-js/app/server augmentation — typed searchParams() generic
-  const pageRoutes = routes.filter((r) => !r.isApiRoute);
+  // useQueryStates + typed Link are urlPath-keyed → deduped list.
+  const pageRoutes = uniqueByUrlPath.filter((r) => !r.isApiRoute);
+  // getSegmentParams / useSegmentParams are segmentPath-keyed → full list,
+  // so slot segments keep their own typed overloads.
+  const dynamicRoutes = routes.filter((r) => r.params.length > 0);
 
-  if (pageRoutes.length > 0) {
+  // Generate @timber-js/app/server augmentation — typed getSegmentParams
+  if (dynamicRoutes.length > 0) {
     lines.push("declare module '@timber-js/app/server' {");
-    lines.push("  import type { Routes } from '@timber-js/app'");
+    if (hasSchema) {
+      lines.push("  import type { AllSegmentParams } from '@timber-js/app'");
+    }
+    for (const route of dynamicRoutes) {
+      const paramsType = formatParamsType(route.params, hasSchema);
+      lines.push(
+        `  export function getSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`
+      );
+    }
     lines.push(
-      "  export function searchParams<R extends keyof Routes>(): Promise<Routes[R]['searchParams']>"
+      hasSchema
+        ? '  export function getSegmentParams(): Partial<AllSegmentParams>'
+        : '  export function getSegmentParams(): Record<string, string | string[]>'
     );
     lines.push('}');
     lines.push('');
   }
 
   // Generate overloads for @timber-js/app/client
-  const dynamicRoutes = routes.filter((r) => r.params.length > 0);
 
   if (dynamicRoutes.length > 0 || pageRoutes.length > 0) {
     lines.push("declare module '@timber-js/app/client' {");
-    lines.push(
-      "  import type { SearchParamsDefinition, SetParams, QueryStatesOptions, SearchParamCodec } from '@timber-js/app/search-params'"
-    );
+    lines.push("  import type { SearchParamsDefinition } from '@timber-js/app/search-params'");
+    if (hasSchema) {
+      lines.push("  import type { AllSegmentParams } from '@timber-js/app'");
+    }
     lines.push('');
 
-    // useParams overloads
+    // useSegmentParams overloads
     if (dynamicRoutes.length > 0) {
       for (const route of dynamicRoutes) {
-        const paramsType = formatParamsType(route.params);
-        lines.push(`  export function useParams(route: '${route.urlPath}'): ${paramsType}`);
+        const paramsType = formatParamsType(route.params, hasSchema);
+        lines.push(
+          `  export function useSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`
+        );
       }
-      lines.push('  export function useParams(): Record<string, string | string[]>');
+      lines.push(
+        hasSchema
+          ? '  export function useSegmentParams(): Partial<AllSegmentParams>'
+          : '  export function useSegmentParams(): Record<string, string | string[]>'
+      );
       lines.push('');
     }
 
-    // useQueryStates overloads
+    // Typed Link overloads — per-route with DIRECT types (no conditionals).
+    // Direct types preserve TypeScript's excess property checking.
+    //
+    // TIM-832: per-route and catch-all are emitted as TWO separate
+    // augmentation blocks. Per TS's merging rule "later overload sets
+    // ordered first", the catch-all block (declared SECOND in this file)
+    // ends up FIRST in the merged call-signature list at resolution time,
+    // which puts the per-route block LAST — so its error message is the
+    // one TypeScript reports when no overload matches. This gives users a
+    // clear prop-mismatch error (e.g. "'string | undefined' is not
+    // assignable to 'string | number' on id") instead of the old
+    // confusing "Type 'string' is not assignable to type 'never'" cascade.
     if (pageRoutes.length > 0) {
-      lines.push(...formatUseQueryStatesOverloads(pageRoutes, importBase));
+      lines.push('  // Typed Link overloads — per-route (block 1 / emitted first)');
+      lines.push(...formatTypedLinkOverloads(pageRoutes, hasSchema));
       lines.push('');
     }
 
-    // Typed Link overloads
-    if (pageRoutes.length > 0) {
-      lines.push('  // Typed Link props per route');
-      lines.push(...formatTypedLinkOverloads(pageRoutes, importBase));
-    }
-
     lines.push('}');
     lines.push('');
   }
 
+  // TIM-832: catch-all block — emitted as a SEPARATE `declare module`
+  // augmentation so TS's "later overload set first" rule orders it ahead
+  // of the per-route block above at resolution time, leaving per-route as
+  // the "last overload" whose error TypeScript reports.
+  lines.push("declare module '@timber-js/app/client' {");
+  lines.push("  import type { SearchParamsDefinition } from '@timber-js/app/search-params'");
+  lines.push('');
+  lines.push(...formatLinkCatchAllOverloads());
+  lines.push('}');
+  lines.push('');
+
   return lines.join('\n');
 }
 
 /**
  * Format the params type for a route entry.
  */
-function formatParamsType(params: ParamEntry[]): string {
-  if (params.length === 0) {
-    return '{}';
-  }
-
-  const fields = params.map((p) => `${p.name}: ${p.type}`);
-  return `{ ${fields.join('; ')} }`;
-}
-
-/**
- * Format the params type for Link props.
- *
- * Link params accept `string | number` for single dynamic segments
- * (convenience — values are stringified at runtime). Catch-all and
- * optional catch-all remain `string[]` / `string[] | undefined`.
- *
- * See design/07-routing.md §"Typed params and searchParams on <Link>"
- */
-function formatLinkParamsType(params: ParamEntry[]): string {
+function formatParamsType(params: ParamEntry[], hasSchema?: boolean): string {
   if (params.length === 0) {
     return '{}';
   }
 
+  // Without a schema a URL segment is an uninterpreted string — that IS
+  // its type. Per-segment codec chains used to narrow it here; TIM-1342
+  // deleted them along with params.ts.
   const fields = params.map((p) => {
-    // Single dynamic segments accept string | number for convenience
-    const type = p.type === 'string' ? 'string | number' : p.type;
-    return `${p.name}: ${type}`;
+    const codecType = hasSchema ? buildSchemaParamType(p) : p.type;
+    return `${p.name}: ${codecType}`;
   });
   return `{ ${fields.join('; ')} }`;
 }
 
-/**
- * Format the searchParams type for a route entry.
- *
- * When a search-params.ts exists, we reference its inferred type via an import type.
- * The import path is relative to `importBase` (the directory where the .d.ts will be
- * written). When importBase is undefined, falls back to a bare relative path.
- */
-function formatSearchParamsType(route: RouteEntry, importBase?: string): string {
-  if (route.hasSearchParams && route.searchParamsAbsPath) {
-    const absPath = route.searchParamsAbsPath.replace(/\.(ts|tsx)$/, '');
-    let importPath: string;
-    if (importBase) {
-      // Make the path relative to the output directory, converted to posix separators
-      importPath = './' + relative(importBase, absPath).replace(/\\/g, '/');
-    } else {
-      importPath = './' + posix.basename(absPath);
-    }
-    // Use (typeof import('...'))[' default'] instead of import('...').default
-    // because with moduleResolution:"bundler", import('...').default is treated as
-    // a namespace member access which doesn't work for default exports.
-    return `(typeof import('${importPath}'))['default'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
-  }
-  return '{}';
-}
-
-/**
- * Generate useQueryStates overloads.
- *
- * For each page route:
- * - Routes with search-params.ts get a typed overload returning the inferred T
- * - Routes without search-params.ts get an overload returning [{}, SetParams<{}>]
- *
- * A fallback overload for standalone codecs (existing API) is emitted last.
- */
-function formatUseQueryStatesOverloads(routes: RouteEntry[], importBase?: string): string[] {
-  const lines: string[] = [];
-
-  for (const route of routes) {
-    const searchParamsType = route.hasSearchParams
-      ? formatSearchParamsType(route, importBase)
-      : '{}';
-    lines.push(
-      `  export function useQueryStates<R extends '${route.urlPath}'>(route: R, options?: QueryStatesOptions): [${searchParamsType}, SetParams<${searchParamsType}>]`
-    );
-  }
-
-  // Fallback: standalone codecs (existing API)
-  lines.push(
-    '  export function useQueryStates<T extends Record<string, unknown>>(codecs: { [K in keyof T]: SearchParamCodec<T[K]> }, options?: QueryStatesOptions): [T, SetParams<T>]'
-  );
-
-  return lines;
-}
-
-/**
- * Generate typed Link overloads.
- *
- * For each page route, we generate a Link function overload that:
- * - Constrains href to the route pattern
- * - Types the params prop based on dynamic segments
- * - Types the searchParams prop based on search-params.ts (if present)
- *
- * Routes without dynamic segments accept href as a literal string with no params.
- * Routes with dynamic segments require a params prop.
- */
-function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): string[] {
-  const lines: string[] = [];
-
-  for (const route of routes) {
-    const hasDynamicParams = route.params.length > 0;
-    const paramsType = formatLinkParamsType(route.params);
-    const searchParamsType = route.hasSearchParams
-      ? formatSearchParamsType(route, importBase)
-      : null;
-
-    if (hasDynamicParams) {
-      // Route with dynamic segments — params prop required
-      const spProp = searchParamsType
-        ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
-        : `searchParams?: never`;
-      lines.push(
-        `  export function Link(props: Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {`
-      );
-      lines.push(`    href: '${route.urlPath}'`);
-      lines.push(`    params: ${paramsType}`);
-      lines.push(`    ${spProp}`);
-      lines.push(`    prefetch?: boolean; scroll?: boolean; children?: import('react').ReactNode`);
-      lines.push(`  }): import('react').JSX.Element`);
-    } else {
-      // Static route — no params needed
-      const spProp = searchParamsType
-        ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
-        : `searchParams?: never`;
-      lines.push(
-        `  export function Link(props: Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {`
-      );
-      lines.push(`    href: '${route.urlPath}'`);
-      lines.push(`    params?: never`);
-      lines.push(`    ${spProp}`);
-      lines.push(`    prefetch?: boolean; scroll?: boolean; children?: import('react').ReactNode`);
-      lines.push(`  }): import('react').JSX.Element`);
-    }
-  }
-
-  // Fallback overload for arbitrary string hrefs (escape hatch)
-  lines.push(
-    `  export function Link(props: import('./client/link.js').LinkProps): import('react').JSX.Element`
-  );
-
-  return lines;
-}
+// TIM-1341: `useQueryStates` no longer has a route-string form, so the
+// generated `.d.ts` emits no overloads for it. Its source signature —
+// `useQueryStates(codecs, options?)` — is fully generic over the codec map
+// and needs no per-route augmentation. Reaching another route's codecs is
+// done by importing that route's `searchParams` definition from its
+// `params.ts` and calling `definition.useQueryStates()`, which is typed by
+// inference and cannot fail at runtime on an unpopulated registry.
+// See design/23-search-params.md §"Client Access".
+
+// Link overload formatters and helpers (`formatTypedLinkOverloads`,
+// `formatLinkCatchAllOverloads`, `formatLinkParamsType`,
+// `buildResolvedPattern`, `LINK_BASE_PROPS_TYPE`) were extracted to
+// `./link-codegen.ts` (TIM-835) to keep this file under the 500-line
+// cap. They are imported at the top of this file.