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

package/dist/plugins/routing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAgBlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA2D1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAmKxD"}
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAiBlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA0E1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAmLxD"}

package/dist/routing/index.js

@@ -1,3 +1,3 @@
 import { t as classifyUrlSegment } from "../_chunks/segment-classify-BDNn6EzD.js";
-import { a as DEFAULT_PAGE_EXTENSIONS, i as scanRoutes, n as generateRouteMap, o as INTERCEPTION_MARKERS, r as classifySegment, t as collectInterceptionRewrites } from "../_chunks/interception-Dpn_UfAD.js";
+import { a as DEFAULT_PAGE_EXTENSIONS, i as scanRoutes, n as generateRouteMap, o as INTERCEPTION_MARKERS, r as classifySegment, t as collectInterceptionRewrites } from "../_chunks/interception-DRlhJWbu.js";
 export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS, classifySegment, classifyUrlSegment, collectInterceptionRewrites, generateRouteMap, scanRoutes };

package/dist/server/rsc-entry/index.d.ts

@@ -1,3 +1,4 @@
+import 'virtual:timber-search-params-registry';
 import { type DebugComponentEntry } from './helpers.js';
 /**
  * Set the dev pipeline error handler.

package/dist/server/rsc-entry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA4DA,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAoCtB;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,mBAAmB,EAAE,KAAK,IAAI,GACtF,IAAI,CAEN;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAE5E;AAqjBD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAInE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;8BA5SrC,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA8ShD,wBAAiE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AAuBA,OAAO,uCAAuC,CAAC;AA0C/C,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,cAAc,CAAC;AAoCtB;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,mBAAmB,EAAE,KAAK,IAAI,GACtF,IAAI,CAEN;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAE5E;AAqjBD,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAInE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;8BA5SrC,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA8ShD,wBAAiE"}

package/dist/server/ssr-entry.d.ts

@@ -11,6 +11,7 @@
  *
  * Design docs: 18-build-system.md §"Entry Files", 02-rendering-pipeline.md
  */
+import 'virtual:timber-search-params-registry';
 /**
  * Navigation context passed from the RSC environment to SSR.
  *

package/dist/server/ssr-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA8EH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE;QACZ,gFAAgF;QAChF,QAAQ,EAAE,MAAM,CAAC;QACjB,uDAAuD;QACvD,OAAO,EAAE,MAAM,CAAC;QAChB,gEAAgE;QAChE,MAAM,EAAE,MAAM,CAAC;QACf,wEAAwE;QACxE,UAAU,EAAE,MAAM,CAAC;QACnB,+CAA+C;QAC/C,OAAO,EAAE,MAAM,CAAC;QAChB,sDAAsD;QACtD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAuLnB;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,uCAAuC,CAAC;AA2E/C;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE;QACZ,gFAAgF;QAChF,QAAQ,EAAE,MAAM,CAAC;QACjB,uDAAuD;QACvD,OAAO,EAAE,MAAM,CAAC;QAChB,gEAAgE;QAChE,MAAM,EAAE,MAAM,CAAC;QACf,wEAAwE;QACxE,UAAU,EAAE,MAAM,CAAC;QACnB,+CAA+C;QAC/C,OAAO,EAAE,MAAM,CAAC;QAChB,sDAAsD;QACtD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAuLnB;AAED,eAAe,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.89",
+  "version": "0.2.0-alpha.90",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -110,6 +110,11 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
+    "typecheck": "tsgo --noEmit",
+    "prepublishOnly": "pnpm run build"
+  },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.6.1",
@@ -152,9 +157,5 @@
   },
   "engines": {
     "node": ">=22.12.0"
-  },
-  "scripts": {
-    "build": "vite build --config vite.lib.config.ts && tsc --emitDeclarationOnly --project tsconfig.json --outDir dist",
-    "typecheck": "tsgo --noEmit"
   }
-}
+}

package/src/client/browser-entry/index.ts

@@ -29,6 +29,11 @@
 
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
+// TIM-830: Populate the search-params registry eagerly so <Link> on the
+// client can serialize flat `Partial<T>` values synchronously during
+// render and click handlers. Side-effect-only import.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import 'virtual:timber-search-params-registry';
 
 import { setClientDeploymentId } from '../rsc-fetch.js';
 import {

package/src/client/index.ts

@@ -10,9 +10,6 @@
 export type { RenderErrorDigest } from './types';
 
 // Navigation
-import type { JSX } from 'react';
-import type { SearchParamsDefinition } from '../search-params/define.js';
-import type { LinkBaseProps } from './link';
 export { Link, interpolateParams, resolveHref, validateLinkHref, buildLinkProps } from './link';
 export { mergePreservedSearchParams } from '../shared/merge-search-params.js';
 export type { LinkProps, LinkPropsWithHref, LinkPropsWithParams, LinkBaseProps } from './link';
@@ -20,75 +17,48 @@ export type { LinkSegmentParams, OnNavigateHandler, OnNavigateEvent } from './li
 
 // ─── LinkFunction (originally declared here for module augmentation) ───
 //
-// The codegen emits `declare module '@timber-js/app/client' { interface
-// LinkFunction { ... } }` to add per-route call signatures. TypeScript
-// interface merging via module augmentation only merges with interfaces
-// that are ORIGINALLY DECLARED in the augmented module — a re-exported
-// type binding (`export type { LinkFunction } from './link'`) creates a
-// distinct, unmergeable name. So `LinkFunction` and its supporting
-// `ExternalHref` type must live here, not in `./link.tsx`. The `Link`
-// const in `./link.tsx` imports this interface as a type-only import.
-// See TIM-624.
-
-/**
- * Href types accepted by the catch-all (non-route) call signature.
- *
- * - External protocols: https://, http://, mailto:, tel:, ftp://
- * - Hash-only and query-only links: #section, ?param=value
- * - Computed `string` variables (non-literal)
- *
- * Internal path literals like "/typo-route" do NOT match — they must
- * be a known route (from codegen) or stored in a `string` variable.
- * This catches wrong hrefs at the type level.
- */
-type ExternalHref =
-  | `http://${string}`
-  | `https://${string}`
-  | `mailto:${string}`
-  | `tel:${string}`
-  | `ftp://${string}`
-  | `//${string}`
-  | `#${string}`
-  | `?${string}`;
-
-/**
- * Callable interface for the Link component.
- *
- * Two kinds of call signatures:
- * 1. Per-route (added by codegen via interface merging): DIRECT types
- *    for segmentParams — preserves TypeScript excess property checking.
- * 2. Catch-all (below): accepts external hrefs and computed `string`
- *    variables. Does NOT accept internal path literals — those must
- *    match a known route from the codegen.
- */
+// The codegen emits TWO augmentations of this interface:
+//
+//   1. Per-route call signatures — `href: '/products/[id]'` with direct
+//      `segmentParams`/`searchParams` types.
+//   2. Catch-all call signatures — `ExternalHref` + computed `string`
+//      variable hrefs.
+//
+// Both live in the codegen output (NOT here). Overload ORDER matters
+// for error UX, and TypeScript's declaration-merging rule "later overload
+// sets ordered first" means that whichever augmentation block is
+// declared LATER in the codegen file ends up FIRST in the merged call-
+// signature list — and therefore the EARLIER block ends up LAST, which
+// is the overload whose error message TypeScript reports when no
+// overload matches.
+//
+// We want the PER-ROUTE overloads to be the error-reporting ones when
+// a user passes a known literal `href` with a mistyped segmentParam.
+// So the codegen emits them FIRST and the catch-all SECOND. That way
+// a call like:
+//
+//   <Link href="/products/[id]" segmentParams={{ id: maybeUndef }} />
+//
+// reports the actual mismatch (`'string | undefined' is not assignable
+// to 'string | number'` on `id`) instead of the notorious "Type 'string'
+// is not assignable to type 'never'" cascade that the old fixed
+// catch-all produced (TIM-832, sibling of TIM-830 / TIM-624).
+//
+// The interface is kept as an empty placeholder here so:
+// - module augmentation has a base interface to merge into
+// - `link.tsx` can `import type { LinkFunction }` and use it as the
+//   cast target for the `Link` const (an empty interface accepts any
+//   non-nullable value, so the cast is valid even without codegen run)
+// - NO call signatures live here — in a fresh checkout where codegen
+//   hasn't run yet, invoking `<Link>` is deliberately a type error,
+//   which surfaces "codegen hasn't run" rather than a misleading
+//   structural type mismatch.
+//
+// See TIM-624 (original typed Link), TIM-830 (flat searchParams), and
+// TIM-832 (this restructure for overload error UX).
 export interface LinkFunction {
-  // External links (literal protocol hrefs)
-  (
-    props: LinkBaseProps & {
-      href: ExternalHref;
-      segmentParams?: never;
-      searchParams?: {
-        definition: SearchParamsDefinition<Record<string, unknown>>;
-        values: Record<string, unknown>;
-      };
-    }
-  ): JSX.Element;
-  // Computed/variable href (non-literal string) — e.g. href={myVar}
-  // `string extends H` is true only when H is the wide `string` type,
-  // not a specific literal. Template literal hrefs like `/blog/${slug}`
-  // are handled by resolved-pattern signatures in the codegen.
-  <H extends string>(
-    props: string extends H
-      ? LinkBaseProps & {
-          href: H;
-          segmentParams?: Record<string, string | number | string[]>;
-          searchParams?: {
-            definition: SearchParamsDefinition<Record<string, unknown>>;
-            values: Record<string, unknown>;
-          };
-        }
-      : never
-  ): JSX.Element;
+  // intentionally empty — call signatures are provided via codegen
+  // augmentation in `.timber/timber-routes.d.ts`.
 }
 export { usePendingNavigation } from './use-pending-navigation';
 export { useLinkStatus, LinkStatusContext } from './use-link-status';

package/src/client/link.tsx

@@ -27,6 +27,7 @@ import {
   type MouseEvent as ReactMouseEvent,
 } from 'react';
 import type { SearchParamsDefinition } from '../search-params/define.js';
+import { getSearchParamsDefinition } from '../search-params/registry.js';
 import type { LinkFunction } from './index.js';
 import { classifyUrlSegment, type UrlSegment } from '../routing/segment-classify.js';
 import { LinkStatusContext } from './use-link-status.js';
@@ -128,6 +129,26 @@ export type LinkSegmentParams<T> = {
 // augmentation merging — only originally-declared interfaces do.
 // See TIM-624.
 
+// ─── searchParams prop shapes ────────────────────────────────────
+//
+// Per-route Link overloads (emitted by codegen) pass the flat values shape:
+//     searchParams={{ page: 2, q: 'boots' }}
+// The framework looks up the route's SearchParamsDefinition from the
+// search-params registry at runtime (see TIM-830).
+//
+// The catch-all overload in client/index.ts (external/computed hrefs)
+// additionally accepts the legacy wrapped shape:
+//     searchParams={{ definition: def, values: { page: 2 } }}
+// because there is no way to look up a definition from a computed string.
+//
+// `resolveHref` discriminates at runtime by presence of a `definition` key.
+type WrappedSearchParamsProp = {
+  definition: SearchParamsDefinition<Record<string, unknown>>;
+  values: Record<string, unknown>;
+};
+type FlatSearchParamsProp = Record<string, unknown>;
+type LinkSearchParamsProp = WrappedSearchParamsProp | FlatSearchParamsProp;
+
 /**
  * Runtime-only loose props used internally by the Link implementation.
  * Not exposed to callers — the public API uses LinkFunction.
@@ -135,20 +156,14 @@ export type LinkSegmentParams<T> = {
 interface LinkRuntimeProps extends LinkBaseProps {
   href: string;
   segmentParams?: Record<string, string | number | string[]>;
-  searchParams?: {
-    definition: SearchParamsDefinition<Record<string, unknown>>;
-    values: Record<string, unknown>;
-  };
+  searchParams?: LinkSearchParamsProp;
 }
 
 // Legacy exports for backward compat (used by buildLinkProps, tests, etc.)
 export type LinkPropsWithHref = LinkBaseProps & {
   href: string;
   segmentParams?: never;
-  searchParams?: {
-    definition: SearchParamsDefinition<Record<string, unknown>>;
-    values: Record<string, unknown>;
-  };
+  searchParams?: LinkSearchParamsProp;
 };
 export type LinkPropsWithParams = LinkRuntimeProps & {
   segmentParams: Record<string, string | number | string[]>;
@@ -296,13 +311,19 @@ export function interpolateParams(
  * - searchParams serialization via SearchParamsDefinition
  * - Validation that searchParams and inline query strings are exclusive
  */
+/**
+ * Runtime discriminator: treat `searchParams` as the legacy wrapped shape
+ * only when it literally has a `definition` key. Everything else is the
+ * flat `Partial<T>` values shape (TIM-830).
+ */
+function isWrappedSearchParamsProp(sp: LinkSearchParamsProp): sp is WrappedSearchParamsProp {
+  return 'definition' in sp;
+}
+
 export function resolveHref(
   href: string,
   params?: Record<string, string | number | string[]>,
-  searchParams?: {
-    definition: SearchParamsDefinition<Record<string, unknown>>;
-    values: Record<string, unknown>;
-  }
+  searchParams?: LinkSearchParamsProp
 ): string {
   let resolvedPath = href;
 
@@ -321,7 +342,36 @@ export function resolveHref(
       );
     }
 
-    const qs = searchParams.definition.serialize(searchParams.values);
+    let definition: SearchParamsDefinition<Record<string, unknown>> | undefined;
+    let values: Record<string, unknown>;
+
+    if (isWrappedSearchParamsProp(searchParams)) {
+      // Legacy wrapped shape — used by the catch-all overload for
+      // computed/external hrefs where no route lookup is possible.
+      definition = searchParams.definition;
+      values = searchParams.values;
+    } else {
+      // Flat shape (TIM-830): look up the definition from the runtime
+      // registry using the un-interpolated href pattern (e.g. '/products/[id]').
+      // The search-params registry is populated eagerly at startup by the
+      // virtual:timber-search-params-registry module generated by the
+      // timber-routing Vite plugin.
+      definition = getSearchParamsDefinition(href) as
+        | SearchParamsDefinition<Record<string, unknown>>
+        | undefined;
+      values = searchParams;
+      if (!definition) {
+        throw new Error(
+          `<Link> received a flat searchParams object for href "${href}", but no ` +
+            `SearchParamsDefinition is registered for that route. ` +
+            `Either the route does not export \`searchParams\` from its \`params.ts\`/\`page.tsx\`, ` +
+            `or the search-params registry module was not loaded. ` +
+            `For external or computed hrefs, pass the legacy \`{ definition, values }\` shape instead.`
+        );
+      }
+    }
+
+    const qs = definition.serialize(values);
     if (qs) {
       resolvedPath = `${resolvedPath}?${qs}`;
     }
@@ -343,10 +393,7 @@ interface LinkOutputProps {
 export function buildLinkProps(
   props: Pick<LinkPropsWithHref, 'href'> & {
     params?: Record<string, string | number | string[]>;
-    searchParams?: {
-      definition: SearchParamsDefinition<Record<string, unknown>>;
-      values: Record<string, unknown>;
-    };
+    searchParams?: LinkSearchParamsProp;
   }
 ): LinkOutputProps {
   const resolvedHref = resolveHref(props.href, props.params, props.searchParams);

package/src/plugins/routing.ts

@@ -10,6 +10,7 @@
 
 import type { Plugin, ViteDevServer } from 'vite';
 import { writeFile, mkdir } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { scanRoutes } from '../routing/scanner.js';
 import { generateRouteMap } from '../routing/codegen.js';
@@ -29,6 +30,21 @@ import type { PluginContext } from '../plugin-context.js';
 const VIRTUAL_MODULE_ID = 'virtual:timber-route-manifest';
 const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
 
+// TIM-830: Search-params registry virtual module.
+//
+// Statically imports the `searchParams` named export from every page
+// that exports one, and registers each definition into the shared
+// search-params registry keyed by the un-interpolated route pattern
+// (e.g. '/products/[id]'). This lets `<Link>` serialize flat
+// `Partial<T>` values at runtime without callers importing the
+// definition at the call site.
+//
+// The imports are STATIC (`import { searchParams as r0 } from '...'`)
+// so Vite/Rolldown tree-shakes each page's component body out of the
+// registry chunk — only the `searchParams` named export is pulled in.
+const SEARCH_PARAMS_REGISTRY_ID = 'virtual:timber-search-params-registry';
+const RESOLVED_SEARCH_PARAMS_REGISTRY_ID = `\0${SEARCH_PARAMS_REGISTRY_ID}`;
+
 /**
  * File convention names we track for changes that require manifest regeneration.
  */
@@ -155,6 +171,14 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return RESOLVED_VIRTUAL_ID;
       }
 
+      // TIM-830: Search-params registry virtual module
+      if (
+        cleanId === SEARCH_PARAMS_REGISTRY_ID ||
+        cleanId.endsWith(`/${SEARCH_PARAMS_REGISTRY_ID}`)
+      ) {
+        return RESOLVED_SEARCH_PARAMS_REGISTRY_ID;
+      }
+
       return null;
     },
 
@@ -165,14 +189,22 @@ export function timberRouting(ctx: PluginContext): Plugin {
      * with absolute import paths for all file references.
      */
     load(id: string) {
-      if (id !== RESOLVED_VIRTUAL_ID) return null;
+      if (id === RESOLVED_VIRTUAL_ID) {
+        // If routeTree hasn't been built yet (shouldn't happen), scan now
+        if (!ctx.routeTree) {
+          rescan();
+        }
+        return generateManifestModule(ctx.routeTree!, ctx.root);
+      }
 
-      // If routeTree hasn't been built yet (shouldn't happen), scan now
-      if (!ctx.routeTree) {
-        rescan();
+      if (id === RESOLVED_SEARCH_PARAMS_REGISTRY_ID) {
+        if (!ctx.routeTree) {
+          rescan();
+        }
+        return generateSearchParamsRegistryModule(ctx.routeTree!);
       }
 
-      return generateManifestModule(ctx.routeTree!, ctx.root);
+      return null;
     },
 
     /**
@@ -259,9 +291,11 @@ function invalidateManifest(server: ViteDevServer): void {
     const env = server.environments[envName];
     if (!env?.moduleGraph) continue;
 
-    const mod = env.moduleGraph.getModuleById(RESOLVED_VIRTUAL_ID);
-    if (mod) {
-      env.moduleGraph.invalidateModule(mod);
+    for (const virtualId of [RESOLVED_VIRTUAL_ID, RESOLVED_SEARCH_PARAMS_REGISTRY_ID]) {
+      const mod = env.moduleGraph.getModuleById(virtualId);
+      if (mod) {
+        env.moduleGraph.invalidateModule(mod);
+      }
     }
   }
 
@@ -269,6 +303,81 @@ function invalidateManifest(server: ViteDevServer): void {
   server.hot.send({ type: 'full-reload' });
 }
 
+/**
+ * TIM-830: 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.
+ *
+ * Keys use the un-interpolated route pattern (e.g. '/products/[id]') so
+ * <Link> can look up the definition from the original `href` prop before
+ * segmentParams are interpolated.
+ */
+function generateSearchParamsRegistryModule(tree: RouteTree): string {
+  const entries: Array<{ urlPath: string; filePath: string }> = [];
+
+  function walk(node: SegmentNode): void {
+    // params.ts is the canonical location for `export const searchParams`;
+    // page.tsx is the legacy fallback (see codegen.ts `collectRoutes`).
+    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 node.slots) walk(slot);
+  }
+  walk(tree.root);
+
+  // Deterministic order for stable output / snapshots
+  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('');
+
+  // Static imports — Vite/Rolldown tree-shakes the page component body out
+  // of this chunk, leaving only the `searchParams` named export.
+  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('');
+
+  // Exporting an empty object keeps the module a real ESM module even
+  // when there are zero entries (no top-level imports in that case).
+  lines.push('export {};');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Lightweight check for a `searchParams` named export. Mirrors
+ * `fileHasExport('searchParams')` in routing/codegen.ts so we stay
+ * in sync with what the type codegen detects.
+ */
+function fileHasSearchParamsExport(filePath: string): boolean {
+  try {
+    if (!existsSync(filePath)) return false;
+    const content = readFileSync(filePath, 'utf-8');
+    return (
+      /export\s+(const|let|var)\s+searchParams\b/.test(content) ||
+      /export\s*\{[^}]*\bsearchParams\b[^}]*\}/.test(content)
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Generate the virtual module source code for the route manifest.
  *