@timber-js/app 0.2.0-alpha.90 → 0.2.0-alpha.91

package/src/routing/codegen.ts

@@ -9,29 +9,10 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { 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 the page.tsx exports searchParams */
-  hasSearchParams: boolean;
-  /** Absolute path to the page file that exports searchParams (for import paths) */
-  searchParamsPagePath?: string;
-  /** Whether this is an API route (route.ts) vs page route */
-  isApiRoute: boolean;
-}
-
-interface ParamEntry {
-  name: string;
-  type: 'string' | 'string[]' | 'string[] | undefined';
-  /** When a layout/page exports defineParams, the absolute path to that file. */
-  codecFilePath?: string;
-}
+import type { ParamEntry, RouteEntry } from './codegen-types.js';
+import { buildCodecChainType, formatSearchParamsType } from './codegen-shared.js';
+import { formatLinkCatchAllOverloads, formatTypedLinkOverloads } from './link-codegen.js';
 
 /** Options for route map generation. */
 export interface CodegenOptions {
@@ -53,7 +34,7 @@ export interface CodegenOptions {
  */
 export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}): string {
   const routes: RouteEntry[] = [];
-  collectRoutes(tree.root, [], routes);
+  collectRoutes(tree.root, [], [], routes);
 
   // Sort routes alphabetically for deterministic output
   routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -73,20 +54,47 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
 function collectRoutes(
   node: SegmentNode,
   ancestorParams: ParamEntry[],
+  ancestorParamsFiles: string[],
   routes: RouteEntry[]
 ): void {
+  // TIM-834: Identify this segment's own params.ts (if it has a
+  // segmentParams export). Ancestor params.ts files are inherited by
+  // descendant dynamic segments — closest-wins.
+  const ownParamsFile =
+    node.params && fileHasExport(node.params.filePath, 'segmentParams')
+      ? node.params.filePath
+      : undefined;
+
   // Accumulate params from this segment
   const params = [...ancestorParams];
   if (node.paramName) {
-    // Check if layout or page exports a params codec for this segment
-    const codecFile = findParamsExport(node);
+    // Build the codec lookup chain in priority order: own segment first,
+    // then ancestor params.ts files closest-to-this-segment first. The
+    // generated type emits a nested conditional that picks the first
+    // entry in the chain whose `segmentParams` declares this key.
+    const codecFilePaths: string[] = [];
+    if (ownParamsFile) codecFilePaths.push(ownParamsFile);
+    for (let i = ancestorParamsFiles.length - 1; i >= 0; i--) {
+      codecFilePaths.push(ancestorParamsFiles[i]);
+    }
+    // Legacy fallback: layout/page export — only for the OWN segment.
+    // Inheritance does not extend to legacy layout/page exports.
+    if (codecFilePaths.length === 0) {
+      const legacy = findLegacyParamsExport(node);
+      if (legacy) codecFilePaths.push(legacy);
+    }
     params.push({
       name: node.paramName,
       type: paramTypeForSegment(node.segmentType),
-      codecFilePath: codecFile,
+      codecFilePaths: codecFilePaths.length > 0 ? codecFilePaths : undefined,
     });
   }
 
+  // Extend the ancestor chain for descendants of this segment.
+  const nextAncestorFiles = ownParamsFile
+    ? [...ancestorParamsFiles, ownParamsFile]
+    : ancestorParamsFiles;
+
   // Check if this segment is a leaf route (has page or route file)
   const isPage = !!node.page;
   const isApiRoute = !!node.route;
@@ -115,12 +123,12 @@ function collectRoutes(
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutes(child, params, routes);
+    collectRoutes(child, params, nextAncestorFiles, routes);
   }
 
   // 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, routes);
+    collectRoutes(slot, params, nextAncestorFiles, routes);
   }
 }
 
@@ -159,18 +167,13 @@ function fileHasExport(filePath: string, exportName: string): boolean {
 }
 
 /**
- * Find which file exports `segmentParams` for a dynamic segment.
+ * Find a legacy `segmentParams` export on layout.tsx or page.tsx.
  *
- * Priority: params.ts (convention file) > layout > page.
- * params.ts is the canonical location (TIM-508). Layout/page fallback
- * exists for backward compat during migration.
+ * Backward-compat shim: TIM-508 made params.ts the canonical location
+ * for `segmentParams`. Layout/page exports are still accepted for the
+ * OWN segment only (not inherited by descendants — see TIM-834).
  */
-function findParamsExport(node: SegmentNode): string | undefined {
-  // params.ts convention file — primary location
-  if (node.params && fileHasExport(node.params.filePath, 'segmentParams')) {
-    return node.params.filePath;
-  }
-  // Fallback: layout or page export (legacy, will be removed)
+function findLegacyParamsExport(node: SegmentNode): string | undefined {
   if (node.layout && fileHasExport(node.layout.filePath, 'segmentParams')) {
     return node.layout.filePath;
   }
@@ -290,79 +293,12 @@ function formatParamsType(params: ParamEntry[], importBase?: string): string {
   }
 
   const fields = params.map((p) => {
-    if (p.codecFilePath) {
-      // Use the codec's inferred type from the layout/page file
-      const absPath = p.codecFilePath.replace(/\.(ts|tsx)$/, '');
-      let importPath: string;
-      if (importBase) {
-        importPath = './' + relative(importBase, absPath).replace(/\\/g, '/');
-      } else {
-        importPath = './' + posix.basename(absPath);
-      }
-      // Extract T from the 'segmentParams' named export's ParamsDefinition<T>
-      const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/segment-params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;
-      return `${p.name}: ${codecType}`;
-    }
-    return `${p.name}: ${p.type}`;
+    const codecType = buildCodecChainType(p, importBase, p.type);
+    return `${p.name}: ${codecType}`;
   });
   return `{ ${fields.join('; ')} }`;
 }
 
-/**
- * Format the params type for Link overloads.
- *
- * 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`.
- *
- * Uses DIRECT types (not conditional) to preserve excess property checking.
- */
-function formatLinkParamsType(params: ParamEntry[], importBase?: string): string {
-  if (params.length === 0) {
-    return '{}';
-  }
-
-  const fields = params.map((p) => {
-    if (p.codecFilePath) {
-      const absPath = p.codecFilePath.replace(/\.(ts|tsx)$/, '');
-      let importPath: string;
-      if (importBase) {
-        importPath = './' + relative(importBase, absPath).replace(/\\/g, '/');
-      } else {
-        importPath = './' + posix.basename(absPath);
-      }
-      const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/segment-params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;
-      return `${p.name}: ${codecType}`;
-    }
-    const type = p.type === 'string' ? 'string | number' : p.type;
-    return `${p.name}: ${type}`;
-  });
-  return `{ ${fields.join('; ')} }`;
-}
-
-/**
- * Format the searchParams type for a route entry.
- *
- * When a page.tsx exports searchParams, 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.searchParamsPagePath) {
-    const absPath = route.searchParamsPagePath.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);
-    }
-    // Extract the type from the named 'searchParams' export of the page module.
-    return `(typeof import('${importPath}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
-  }
-  return '{}';
-}
-
 /**
  * Generate useQueryStates overloads.
  *
@@ -392,173 +328,8 @@ function formatUseQueryStatesOverloads(routes: RouteEntry[], importBase?: string
   return lines;
 }
 
-/**
- * Build a TypeScript template literal pattern for a dynamic route.
- * e.g. '/products/[id]'        → '/products/${string}'
- *      '/blog/[...slug]'       → '/blog/${string}'
- *      '/docs/[[...path]]'     → '/docs/${string}' (also matches /docs)
- *      '/[org]/[repo]'         → '/${string}/${string}'
- */
-function buildResolvedPattern(route: RouteEntry): string | null {
-  const parts = route.urlPath.split('/');
-  const templateParts = parts.map((part) => {
-    if (part.startsWith('[[...') && part.endsWith(']]')) {
-      // Optional catch-all — matches any trailing path
-      return '${string}';
-    }
-    if (part.startsWith('[...') && part.endsWith(']')) {
-      // Catch-all — matches one or more segments
-      return '${string}';
-    }
-    if (part.startsWith('[') && part.endsWith(']')) {
-      // Dynamic segment
-      return '${string}';
-    }
-    return part;
-  });
-  return templateParts.join('/');
-}
-
-/** Shared Link base-props type literal used in every emitted call signature. */
-const LINK_BASE_PROPS_TYPE =
-  "Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }";
-
-/**
- * TIM-832: Catch-all call signatures for `<Link>` — external hrefs and
- * computed `string` variables. Emitted from codegen in a SEPARATE
- * `declare module` block (declared AFTER the per-route block) so the TS
- * "later overload set ordered first" rule places these catch-all
- * signatures ahead of per-route in resolution order, leaving per-route
- * as the final overload whose error message is reported on failure.
- *
- * The conditional `string extends H ? ... : never` protection preserves
- * TIM-624's guarantee that unknown internal path literals don't match
- * the catch-all — typos like `<Link href="/typo" />` still error.
- */
-function formatLinkCatchAllOverloads(): string[] {
-  const lines: string[] = [];
-  const baseProps = LINK_BASE_PROPS_TYPE;
-
-  // TIM-830: the catch-all signatures accept EITHER the legacy
-  // `{ definition, values }` wrapper OR a flat `Record<string, unknown>`
-  // values object. External/computed hrefs can't be looked up in the
-  // runtime registry, so the wrapped form is still the reliable path;
-  // the flat form is kept permissive for callers migrating from typed-
-  // route hrefs to computed strings. `resolveHref` discriminates at
-  // runtime via the presence of a `definition` key.
-  const catchAllSearchParams =
-    '{ definition: SearchParamsDefinition<Record<string, unknown>>; values: Record<string, unknown> } | Record<string, unknown>';
-
-  // ExternalHref inlined here rather than referenced as an exported
-  // alias so the generated .d.ts stands alone without source imports.
-  const externalHref =
-    '`http://${string}` | `https://${string}` | `mailto:${string}` | `tel:${string}` | `ftp://${string}` | `//${string}` | `#${string}` | `?${string}`';
-
-  lines.push('  // Typed Link overloads — catch-all (block 2 / emitted second)');
-  lines.push('  interface LinkFunction {');
-
-  // (1) External/literal-protocol hrefs.
-  lines.push(`    (props: ${baseProps} & {`);
-  lines.push(`      href: ${externalHref}`);
-  lines.push(`      segmentParams?: never`);
-  lines.push(`      searchParams?: ${catchAllSearchParams}`);
-  lines.push(`    }): import('react').JSX.Element`);
-
-  // (2) Computed/variable href — non-literal `string` only.
-  // `string extends H` is true only when H is the wide `string` type,
-  // not a specific literal. Literal internal paths (typos) that don't
-  // match any per-route signature collapse to `never` here, but since
-  // this block is NOT the "last overload" at resolution time, TS
-  // instead reports the error from the per-route block — which now
-  // says `Type '"/typo"' is not assignable to type '"/products/[id]"'`
-  // or similar per-route-specific guidance.
-  lines.push(`    <H extends string>(`);
-  lines.push(`      props: string extends H`);
-  lines.push(`        ? ${baseProps} & {`);
-  lines.push(`            href: H`);
-  lines.push(`            segmentParams?: Record<string, string | number | string[]>`);
-  lines.push(`            searchParams?: ${catchAllSearchParams}`);
-  lines.push(`          }`);
-  lines.push(`        : never`);
-  lines.push(`    ): import('react').JSX.Element`);
-
-  lines.push('  }');
-  return lines;
-}
-
-/**
- * Generate typed per-route Link call signatures via LinkFunction
- * interface merging.
- *
- * Each call signature uses DIRECT types (not conditional types) for
- * segmentParams, preserving TypeScript's excess property checking.
- * Interface merging is the only reliable way to add "overloads" via
- * module augmentation — function overloads can't be augmented.
- *
- * TIM-832: this function emits ONLY the per-route block. The catch-all
- * block is emitted separately by `formatLinkCatchAllOverloads` inside a
- * second `declare module` so TS overload ordering reports per-route
- * errors (see `formatDeclarationFile`).
- */
-function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): string[] {
-  const lines: string[] = [];
-  const baseProps = LINK_BASE_PROPS_TYPE;
-
-  lines.push('  interface LinkFunction {');
-  for (const route of routes) {
-    const hasDynamicParams = route.params.length > 0;
-    const paramsProp = hasDynamicParams
-      ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}`
-      : 'segmentParams?: never';
-
-    const searchParamsType = route.hasSearchParams
-      ? formatSearchParamsType(route, importBase)
-      : null;
-    // TIM-830: the per-route pattern signature (href: '/products/[id]')
-    // uses a FLAT `Partial<T>` shape — the registry is keyed by the
-    // un-interpolated pattern, which matches `href` here exactly.
-    const patternSearchParamsProp = searchParamsType
-      ? `searchParams?: Partial<${searchParamsType}>`
-      : 'searchParams?: never';
-
-    // TIM-832: For dynamic routes, emit the resolved-template signature
-    // FIRST and the pattern signature SECOND. The TS overload resolution
-    // order is top-to-bottom, and TS reports the error from the LAST
-    // overload tried on a failed call. For a user who passes the literal
-    // pattern href (`href="/products/[id]"`) and mistyped segmentParams,
-    // we want the PATTERN signature's error (which names the specific
-    // `segmentParams` shape like `{ id: string | number }`) to be the one
-    // TS reports — so the pattern must come LAST.
-    //
-    // TIM-830: the resolved-template signature keeps the legacy WRAPPED
-    // `{ definition, values }` shape. The runtime registry is keyed by
-    // the un-interpolated pattern (e.g. '/products/[id]'), so a flat
-    // lookup for an already-interpolated href like '/products/42' would
-    // fail. Flat values only work on the pattern signature below where
-    // `href` is the pattern itself. Callers using a resolved-template
-    // href must pass the definition inline, same as the external/
-    // computed catch-all signature.
-    if (hasDynamicParams) {
-      const templatePattern = buildResolvedPattern(route);
-      if (templatePattern) {
-        const resolvedSearchParamsProp = searchParamsType
-          ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
-          : 'searchParams?: never';
-        lines.push(`    (props: ${baseProps} & {`);
-        lines.push(`      href: \`${templatePattern}\``);
-        lines.push(`      segmentParams?: never`);
-        lines.push(`      ${resolvedSearchParamsProp}`);
-        lines.push(`    }): import('react').JSX.Element`);
-      }
-    }
-
-    lines.push(`    (props: ${baseProps} & {`);
-    lines.push(`      href: '${route.urlPath}'`);
-    lines.push(`      ${paramsProp}`);
-    lines.push(`      ${patternSearchParamsProp}`);
-    lines.push(`    }): import('react').JSX.Element`);
-  }
-  lines.push('  }');
-
-  return lines;
-}
+// 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.

package/src/routing/link-codegen.ts

@@ -0,0 +1,262 @@
+/**
+ * Typed `<Link>` codegen — interface augmentation generation.
+ *
+ * Extracted from `codegen.ts` to keep that file under the project's
+ * 500-line cap. This module owns everything that emits the
+ * `interface LinkFunction { ... }` augmentation blocks in the generated
+ * `.timber/timber-routes.d.ts`.
+ *
+ * Two augmentation blocks are emitted:
+ *
+ * 1. **Per-route discriminated union** (`formatTypedLinkOverloads`) —
+ *    one call signature whose props is a union keyed on `href`. TS
+ *    narrows by literal href and reports prop errors against the
+ *    matched variant. See TIM-835 and `design/09-typescript.md`.
+ *
+ * 2. **Catch-all overloads** (`formatLinkCatchAllOverloads`) — external
+ *    href literals (`http://`, `mailto:`, etc.) and a computed-string
+ *    `<H extends string>` signature for runtime-computed paths.
+ *
+ * Block ordering is critical for error UX: per-route is emitted FIRST
+ * so that, after TS's "later overload set ordered first" merge rule,
+ * the discriminated union ends up LAST in resolution order — the
+ * overload TS reports against on failure.
+ */
+
+import type { ParamEntry, RouteEntry } from './codegen-types.js';
+import { buildCodecChainType, formatSearchParamsType } from './codegen-shared.js';
+
+/** Shared Link base-props type literal used in every emitted call signature. */
+export const LINK_BASE_PROPS_TYPE =
+  "Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }";
+
+/**
+ * Build a TypeScript template literal pattern for a dynamic route.
+ * e.g. '/products/[id]'        → '/products/${string}'
+ *      '/blog/[...slug]'       → '/blog/${string}'
+ *      '/docs/[[...path]]'     → '/docs/${string}' (also matches /docs)
+ *      '/[org]/[repo]'         → '/${string}/${string}'
+ */
+export function buildResolvedPattern(route: RouteEntry): string | null {
+  const parts = route.urlPath.split('/');
+  const templateParts = parts.map((part) => {
+    if (part.startsWith('[[...') && part.endsWith(']]')) {
+      // Optional catch-all — matches any trailing path
+      return '${string}';
+    }
+    if (part.startsWith('[...') && part.endsWith(']')) {
+      // Catch-all — matches one or more segments
+      return '${string}';
+    }
+    if (part.startsWith('[') && part.endsWith(']')) {
+      // Dynamic segment
+      return '${string}';
+    }
+    return part;
+  });
+  return templateParts.join('/');
+}
+
+/**
+ * Format the segmentParams type for Link overloads.
+ *
+ * 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`.
+ *
+ * When the segment's params chain (TIM-834) declares a typed codec, the
+ * inferred type from the codec wins via a nested conditional.
+ */
+export function formatLinkParamsType(params: ParamEntry[], importBase?: string): string {
+  if (params.length === 0) {
+    return '{}';
+  }
+
+  const fields = params.map((p) => {
+    const fallback = p.type === 'string' ? 'string | number' : p.type;
+    const codecType = buildCodecChainType(p, importBase, fallback);
+    return `${p.name}: ${codecType}`;
+  });
+  return `{ ${fields.join('; ')} }`;
+}
+
+/**
+ * Catch-all call signatures for `<Link>` — external hrefs and computed
+ * `string` variables. Emitted from codegen in a SEPARATE
+ * `declare module` block (declared AFTER the per-route block) so the TS
+ * "later overload set ordered first" rule places these catch-all
+ * signatures ahead of per-route in resolution order, leaving per-route
+ * as the final overload whose error message is reported on failure.
+ *
+ * The conditional `string extends H ? ... : never` protection preserves
+ * TIM-624's guarantee that unknown internal path literals don't match
+ * the catch-all — typos like `<Link href="/typo" />` still error.
+ */
+export function formatLinkCatchAllOverloads(): string[] {
+  const lines: string[] = [];
+  const baseProps = LINK_BASE_PROPS_TYPE;
+
+  // TIM-830: the catch-all signatures accept EITHER the legacy
+  // `{ definition, values }` wrapper OR a flat `Record<string, unknown>`
+  // values object. External/computed hrefs can't be looked up in the
+  // runtime registry, so the wrapped form is still the reliable path;
+  // the flat form is kept permissive for callers migrating from typed-
+  // route hrefs to computed strings. `resolveHref` discriminates at
+  // runtime via the presence of a `definition` key.
+  const catchAllSearchParams =
+    '{ definition: SearchParamsDefinition<Record<string, unknown>>; values: Record<string, unknown> } | Record<string, unknown>';
+
+  // ExternalHref inlined here rather than referenced as an exported
+  // alias so the generated .d.ts stands alone without source imports.
+  const externalHref =
+    '`http://${string}` | `https://${string}` | `mailto:${string}` | `tel:${string}` | `ftp://${string}` | `//${string}` | `#${string}` | `?${string}`';
+
+  lines.push('  // Typed Link overloads — catch-all (block 2 / emitted second)');
+  lines.push('  interface LinkFunction {');
+
+  // (1) External/literal-protocol hrefs.
+  lines.push(`    (props: ${baseProps} & {`);
+  lines.push(`      href: ${externalHref}`);
+  lines.push(`      segmentParams?: never`);
+  lines.push(`      searchParams?: ${catchAllSearchParams}`);
+  lines.push(`    }): import('react').JSX.Element`);
+
+  // (2) Computed/variable href — non-literal `string` only.
+  // `string extends H` is true only when H is the wide `string` type,
+  // not a specific literal. Literal internal paths (typos) that don't
+  // match any per-route signature collapse to `never` here, but since
+  // this block is NOT the "last overload" at resolution time, TS
+  // instead reports the error from the per-route block — which now
+  // says `Type '"/typo"' is not assignable to type '"/products/[id]"'`
+  // or similar per-route-specific guidance.
+  lines.push(`    <H extends string>(`);
+  lines.push(`      props: string extends H`);
+  lines.push(`        ? ${baseProps} & {`);
+  lines.push(`            href: H`);
+  lines.push(`            segmentParams?: Record<string, string | number | string[]>`);
+  lines.push(`            searchParams?: ${catchAllSearchParams}`);
+  lines.push(`          }`);
+  lines.push(`        : never`);
+  lines.push(`    ): import('react').JSX.Element`);
+
+  lines.push('  }');
+  return lines;
+}
+
+/**
+ * Generate typed per-route Link call signatures via LinkFunction
+ * interface merging.
+ *
+ * TIM-835: This emits a SINGLE call signature whose props is a
+ * discriminated union keyed on `href`. TypeScript narrows the union by
+ * the literal `href` at the call site, then checks the rest of the
+ * props against the matched variant. When `segmentParams` or
+ * `searchParams` is wrong, TS reports the error against the matched
+ * variant — naming the user's actual `href` and the offending field.
+ *
+ * Before TIM-835, this function emitted N separate per-route overloads
+ * (one per route, sometimes two for dynamic routes). When ALL overloads
+ * failed, TS would pick an arbitrary failed overload (heuristically the
+ * "last tried") to render the diagnostic, often pointing at a route
+ * completely unrelated to the one the user wrote. The discriminated
+ * union sidesteps overload-resolution heuristics entirely.
+ *
+ * Open property shapes (`Record<string, unknown>` instead of `never`)
+ * for `segmentParams` on routes that don't declare them keep generic
+ * `LinkProps`-spreading wrappers compiling. (Aligned with TIM-833.)
+ *
+ * TIM-832: this function still emits the per-route block FIRST and the
+ * catch-all block follows, so per-route remains the LAST overload set in
+ * resolution order — the one TS reports against on failure. With a
+ * discriminated union there is only one call signature in this block,
+ * so the resolved-template-vs-pattern ordering reduces to placing the
+ * pattern variant before the resolved-template variant inside the union.
+ */
+export function formatTypedLinkOverloads(routes: RouteEntry[], importBase?: string): string[] {
+  const lines: string[] = [];
+  const baseProps = LINK_BASE_PROPS_TYPE;
+
+  // Build the union variants. Each route contributes one variant for the
+  // pattern href (e.g. '/products/[id]') and, for dynamic routes, an
+  // additional variant for the resolved-template href (e.g.
+  // `/products/${string}`).
+  //
+  // The PATTERN variant must be listed BEFORE the resolved-template
+  // variant for the same route so that when the user writes the literal
+  // pattern href (`<Link href="/products/[id]" />`), TS narrows to the
+  // pattern variant (which carries the typed `segmentParams` shape)
+  // rather than the looser resolved-template variant. Without this
+  // ordering, TS would silently match the resolved-template variant
+  // first — swallowing typed-segmentParams type errors.
+  const variants: string[] = [];
+  for (const route of routes) {
+    const hasDynamicParams = route.params.length > 0;
+    // For routes with no dynamic params, accept an absent OR open-shape
+    // segmentParams. `Record<string, unknown>` keeps generic spreads
+    // compiling and gives a readable error if a non-object is passed.
+    const paramsProp = hasDynamicParams
+      ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}`
+      : 'segmentParams?: Record<string, unknown>';
+
+    const searchParamsType = route.hasSearchParams
+      ? formatSearchParamsType(route, importBase)
+      : null;
+    // TIM-830: pattern href uses the FLAT `Partial<T>` shape — the
+    // runtime registry is keyed by the un-interpolated pattern.
+    //
+    // TIM-835: when the route has NO searchParams definition, use
+    // `Record<string, never>` (forbids any keys) instead of
+    // `Record<string, unknown>` so passing unexpected query params is a
+    // type error. Generic-spread compatibility is preserved by the
+    // matching open shape on `segmentParams` (which is the prop users
+    // typically forward through wrapper components).
+    const patternSearchParamsProp = searchParamsType
+      ? `searchParams?: Partial<${searchParamsType}>`
+      : 'searchParams?: Record<string, never>';
+
+    // Pattern variant FIRST (more specific).
+    variants.push(
+      `${baseProps} & { href: '${route.urlPath}'; ${paramsProp}; ${patternSearchParamsProp} }`
+    );
+
+    // Resolved-template variant SECOND (looser, matches interpolated hrefs).
+    if (hasDynamicParams) {
+      const templatePattern = buildResolvedPattern(route);
+      if (templatePattern) {
+        // TIM-830: resolved-template href keeps the WRAPPED
+        // `{ definition, values }` shape — the registry can't be looked
+        // up by an already-interpolated href.
+        const resolvedSearchParamsProp = searchParamsType
+          ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
+          : 'searchParams?: Record<string, never>';
+        // TIM-835: `Record<string, never>` for segmentParams forbids ANY
+        // provided keys on the resolved-template variant. Without this,
+        // the resolved-template would shadow the pattern variant for
+        // literal pattern hrefs (`<Link href="/products/[id]" segmentParams={...} />`)
+        // because both variants accept the literal `'/products/[id]'`
+        // and the looser variant would silently swallow segmentParams
+        // type errors.
+        variants.push(
+          `${baseProps} & { href: \`${templatePattern}\`; segmentParams?: Record<string, never>; ${resolvedSearchParamsProp} }`
+        );
+      }
+    }
+  }
+
+  lines.push('  interface LinkFunction {');
+  if (variants.length === 0) {
+    // No page routes — emit nothing. The catch-all block in the second
+    // augmentation still provides external/computed-string signatures.
+    lines.push('  }');
+    return lines;
+  }
+  lines.push('    (');
+  lines.push('      props:');
+  for (const variant of variants) {
+    lines.push(`        | (${variant})`);
+  }
+  lines.push(`    ): import('react').JSX.Element`);
+  lines.push('  }');
+
+  return lines;
+}