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

package/src/plugins/static-build.ts

@@ -2,7 +2,7 @@
  * timber-static-build — Vite sub-plugin for static output mode.
  *
  * When `output: 'static'` is set in timber.config.ts, this plugin:
- * 1. Validates that no dynamic APIs (cookies(), headers()) are used
+ * 1. Validates that no dynamic APIs (getCookies(), getHeaders()) are used
  * 2. When client JavaScript is disabled, rejects 'use client' and 'use server' directives
  * 3. Coordinates build-time rendering of all pages
  *
@@ -10,8 +10,8 @@
  */
 
 import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import { detectFileDirective } from '#/utils/directive-parser.js';
+import type { PluginContext } from '../plugin-context.js';
+import { detectFileDirective } from '../utils/directive-parser.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -29,7 +29,7 @@ export interface StaticOptions {
 }
 
 // ---------------------------------------------------------------------------
-// Detection: dynamic APIs (cookies, headers)
+// Detection: dynamic APIs (getCookies, getHeaders, and legacy cookies/headers)
 // ---------------------------------------------------------------------------
 
 /**
@@ -39,12 +39,14 @@ export interface StaticOptions {
  * We detect both import-level and call-level usage.
  */
 const DYNAMIC_API_PATTERNS: Array<{ pattern: RegExp; name: string }> = [
+  { pattern: /\bgetCookies\s*\(/, name: 'getCookies()' },
+  { pattern: /\bgetHeaders\s*\(/, name: 'getHeaders()' },
   { pattern: /\bcookies\s*\(/, name: 'cookies()' },
   { pattern: /\bheaders\s*\(/, name: 'headers()' },
 ];
 
 /**
- * Detect usage of dynamic per-request APIs (cookies(), headers())
+ * Detect usage of dynamic per-request APIs (getCookies(), getHeaders())
  * that cannot work at build time in static mode.
  *
  * Returns an array of validation errors.
@@ -134,7 +136,7 @@ export function detectDirectives(
  * Run all static mode validations on a source file.
  *
  * Combines:
- * - Dynamic API detection (cookies, headers) — always in static mode
+ * - Dynamic API detection (getCookies, getHeaders) — always in static mode
  * - Directive detection ('use client', 'use server') — only when client JS is disabled
  */
 export function validateStaticMode(
@@ -163,9 +165,6 @@ export function validateStaticMode(
  * - transform: Validates source files for static mode violations
  */
 export function timberStaticBuild(ctx: PluginContext): Plugin {
-  const isStatic = ctx.config.output === 'static';
-  const clientJavascriptDisabled = ctx.clientJavascript.disabled;
-
   return {
     name: 'timber-static-build',
 
@@ -173,10 +172,15 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
      * Validate source files during transform.
      *
      * In static mode, we check every app/ file for:
-     * - Dynamic API usage (cookies(), headers()) → build error
+     * - Dynamic API usage (getCookies(), getHeaders()) → build error
      * - When client JS disabled: 'use client' / 'use server' directives → build error
      */
     transform(code: string, id: string) {
+      // Read ctx.config lazily inside the hook — not at plugin construction
+      // time — so file-based config from timber.config.ts is respected.
+      // See TIM-451.
+      const isStatic = ctx.config.output === 'static';
+
       // Only active in static mode
       if (!isStatic) return null;
 
@@ -189,7 +193,9 @@ export function timberStaticBuild(ctx: PluginContext): Plugin {
       // Only check JS/TS files
       if (!/\.[jt]sx?$/.test(id)) return null;
 
-      const errors = validateStaticMode(code, id, { clientJavascriptDisabled });
+      const errors = validateStaticMode(code, id, {
+        clientJavascriptDisabled: ctx.clientJavascript.disabled,
+      });
 
       if (errors.length > 0) {
         // Format all errors into a single build error message

package/src/routing/codegen.ts

@@ -8,8 +8,8 @@
  * No runtime overhead — purely static type generation.
  */
 
-import { existsSync } from 'node:fs';
-import { join, relative, posix } from 'node:path';
+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. */
@@ -18,10 +18,10 @@ interface RouteEntry {
   urlPath: string;
   /** Accumulated params from all ancestor dynamic segments */
   params: ParamEntry[];
-  /** Whether this route has a co-located search-params.ts */
+  /** Whether the page.tsx exports searchParams */
   hasSearchParams: boolean;
-  /** Absolute path to search-params.ts (for computing relative import paths) */
-  searchParamsAbsPath?: string;
+  /** 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;
 }
@@ -29,15 +29,17 @@ interface RouteEntry {
 interface ParamEntry {
   name: string;
   type: 'string' | 'string[]' | 'string[] | undefined';
+  /** When a layout/page exports defineParams, the absolute path to that file. */
+  codecFilePath?: string;
 }
 
 /** 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;
@@ -51,7 +53,7 @@ export interface CodegenOptions {
  */
 export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}): string {
   const routes: RouteEntry[] = [];
-  collectRoutes(tree.root, [], options.appDir, routes);
+  collectRoutes(tree.root, [], routes);
 
   // Sort routes alphabetically for deterministic output
   routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -71,15 +73,17 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
 function collectRoutes(
   node: SegmentNode,
   ancestorParams: ParamEntry[],
-  appDir: string | undefined,
   routes: RouteEntry[]
 ): void {
   // 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);
     params.push({
       name: node.paramName,
       type: paramTypeForSegment(node.segmentType),
+      codecFilePath: codecFile,
     });
   }
 
@@ -95,13 +99,14 @@ function collectRoutes(
       isApiRoute,
     };
 
-    // Detect co-located search-params.ts
-    if (appDir && isPage) {
-      const segmentDir = resolveSegmentDir(appDir, node);
-      const searchParamsFile = findSearchParamsFile(segmentDir);
-      if (searchParamsFile) {
+    // Detect searchParams export from params.ts (primary) or page.tsx (fallback)
+    if (isPage) {
+      if (node.params && fileHasExport(node.params.filePath, 'searchParams')) {
         entry.hasSearchParams = true;
-        entry.searchParamsAbsPath = searchParamsFile;
+        entry.searchParamsPagePath = node.params.filePath;
+      } else if (node.page && fileHasExport(node.page.filePath, 'searchParams')) {
+        entry.hasSearchParams = true;
+        entry.searchParamsPagePath = node.page.filePath;
       }
     }
 
@@ -110,12 +115,12 @@ function collectRoutes(
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutes(child, params, appDir, routes);
+    collectRoutes(child, params, 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, appDir, routes);
+    collectRoutes(slot, params, routes);
   }
 }
 
@@ -134,33 +139,43 @@ function paramTypeForSegment(segmentType: string): ParamEntry['type'] {
 }
 
 /**
- * Resolve the absolute directory path for a segment node.
+ * Check if a file exports a specific named export.
  *
- * Reconstructs the filesystem path by walking from appDir through
- * the segment names encoded in the urlPath, accounting for groups and slots.
+ * Uses a lightweight regex check — not full AST parsing. The actual type
+ * extraction happens via the TypeScript compiler in the generated .d.ts.
  */
-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('/');
+function fileHasExport(filePath: string, exportName: string): boolean {
+  if (!existsSync(filePath)) return false;
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const e = exportName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return (
+      new RegExp(`export\\s+(const|let|var)\\s+${e}\\b`).test(content) ||
+      new RegExp(`export\\s*\\{[^}]*\\b${e}\\b[^}]*\\}`).test(content)
+    );
+  } catch {
+    return false;
   }
-  // Fallback: construct from urlPath (imprecise for groups, but acceptable)
-  return appDir;
 }
 
 /**
- * Find a search-params.ts file in a directory.
+ * Find which file exports `segmentParams` for a dynamic segment.
+ *
+ * Priority: params.ts (convention file) > layout > page.
+ * params.ts is the canonical location (TIM-508). Layout/page fallback
+ * exists for backward compat during migration.
  */
-function findSearchParamsFile(dirPath: string): string | undefined {
-  for (const ext of ['ts', 'tsx']) {
-    const candidate = join(dirPath, `search-params.${ext}`);
-    if (existsSync(candidate)) {
-      return candidate;
-    }
+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)
+  if (node.layout && fileHasExport(node.layout.filePath, 'segmentParams')) {
+    return node.layout.filePath;
+  }
+  if (node.page && fileHasExport(node.page.filePath, 'segmentParams')) {
+    return node.page.filePath;
   }
   return undefined;
 }
@@ -184,11 +199,11 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
   lines.push('  interface Routes {');
 
   for (const route of routes) {
-    const paramsType = formatParamsType(route.params);
+    const paramsType = formatParamsType(route.params, importBase);
     const searchParamsType = formatSearchParamsType(route, importBase);
 
     lines.push(`    '${route.urlPath}': {`);
-    lines.push(`      params: ${paramsType}`);
+    lines.push(`      segmentParams: ${paramsType}`);
     lines.push(`      searchParams: ${searchParamsType}`);
     lines.push(`    }`);
   }
@@ -200,15 +215,9 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
   // Generate @timber-js/app/server augmentation — typed searchParams() generic
   const pageRoutes = routes.filter((r) => !r.isApiRoute);
 
-  if (pageRoutes.length > 0) {
-    lines.push("declare module '@timber-js/app/server' {");
-    lines.push("  import type { Routes } from '@timber-js/app'");
-    lines.push(
-      "  export function searchParams<R extends keyof Routes>(): Promise<Routes[R]['searchParams']>"
-    );
-    lines.push('}');
-    lines.push('');
-  }
+  // Note: searchParams() always returns Promise<URLSearchParams>.
+  // Typed parsing is done via definition.parse(searchParams()).
+  // No module augmentation needed for @timber-js/app/server.
 
   // Generate overloads for @timber-js/app/client
   const dynamicRoutes = routes.filter((r) => r.params.length > 0);
@@ -223,10 +232,10 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
     // useParams 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, importBase);
+        lines.push(`  export function useSegmentParams(route: '${route.urlPath}'): ${paramsType}`);
       }
-      lines.push('  export function useParams(): Record<string, string | string[]>');
+      lines.push('  export function useSegmentParams(): Record<string, string | string[]>');
       lines.push('');
     }
 
@@ -236,47 +245,95 @@ function formatDeclarationFile(routes: RouteEntry[], importBase?: string): strin
       lines.push('');
     }
 
-    // Typed Link 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('  // Typed Link props per route');
+      lines.push('  // Typed Link overloads — per-route (block 1 / emitted first)');
       lines.push(...formatTypedLinkOverloads(pageRoutes, importBase));
+      lines.push('');
     }
 
     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 {
+function formatParamsType(params: ParamEntry[], importBase?: string): string {
   if (params.length === 0) {
     return '{}';
   }
 
-  const fields = params.map((p) => `${p.name}: ${p.type}`);
+  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}`;
+  });
   return `{ ${fields.join('; ')} }`;
 }
 
 /**
- * Format the params type for Link props.
+ * 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`.
  *
- * See design/07-routing.md §"Typed params and searchParams on <Link>"
+ * Uses DIRECT types (not conditional) to preserve excess property checking.
  */
-function formatLinkParamsType(params: ParamEntry[]): string {
+function formatLinkParamsType(params: ParamEntry[], importBase?: string): string {
   if (params.length === 0) {
     return '{}';
   }
 
   const fields = params.map((p) => {
-    // Single dynamic segments accept string | number for convenience
+    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}`;
   });
@@ -286,13 +343,13 @@ function formatLinkParamsType(params: ParamEntry[]): string {
 /**
  * Format the searchParams type for a route entry.
  *
- * When a search-params.ts exists, we reference its inferred type via an import type.
+ * 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.searchParamsAbsPath) {
-    const absPath = route.searchParamsAbsPath.replace(/\.(ts|tsx)$/, '');
+  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
@@ -300,10 +357,8 @@ function formatSearchParamsType(route: RouteEntry, importBase?: string): string
     } 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`;
+    // 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 '{}';
 }
@@ -338,59 +393,172 @@ function formatUseQueryStatesOverloads(routes: RouteEntry[], importBase?: string
 }
 
 /**
- * Generate typed Link overloads.
+ * 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.
  *
- * 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)
+ * 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.
  *
- * Routes without dynamic segments accept href as a literal string with no params.
- * Routes with dynamic segments require a params prop.
+ * 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 paramsType = formatLinkParamsType(route.params);
+    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) {
-      // 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`);
+      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`);
+      }
     }
-  }
 
-  // Fallback overload for arbitrary string hrefs (escape hatch)
-  lines.push(
-    `  export function Link(props: import('./client/link.js').LinkProps): 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;
 }