@timber-js/app 0.2.0-alpha.120 → 0.2.0-alpha.122

package/src/routing/schema-validation.ts

@@ -0,0 +1,149 @@
+/**
+ * Schema key/value validation against the filesystem route tree.
+ *
+ * Runs at codegen time (build + dev) to catch mismatches between
+ * app/schema.ts keys and the actual dynamic segments on disk.
+ *
+ * Design doc: design/41-global-params.md
+ */
+
+import { readFileSync } from 'node:fs';
+import type { RouteTree, SegmentNode } from './types.js';
+import { findSchemaFile, parseExistingSchemaKeys } from '../cli-schema-sync.js';
+import { classifyUrlSegment } from './segment-classify.js';
+
+export interface SchemaWarning {
+  type: 'stale-key' | 'missing-key' | 'bracket-mismatch';
+  key: string;
+  message: string;
+  filesystemKey?: string;
+}
+
+/**
+ * Collect all unique bracket-keyed dynamic segment names from a route tree.
+ * Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+ */
+export function collectDynamicSegmentsFromTree(tree: RouteTree): Set<string> {
+  const segments = new Set<string>();
+  walkTree(tree.root, segments);
+  return segments;
+}
+
+function walkTree(node: SegmentNode, segments: Set<string>): void {
+  if (node.paramName && node.segmentName) {
+    const classified = classifyUrlSegment(node.segmentName);
+    if (classified.kind !== 'static') {
+      segments.add(node.segmentName);
+    }
+  }
+  for (const child of node.children) {
+    walkTree(child, segments);
+  }
+  for (const slot of Object.values(node.slots)) {
+    walkTree(slot, segments);
+  }
+}
+
+/**
+ * Extract the param name from a bracket key.
+ * '[id]' → 'id', '[...slug]' → 'slug', '[[...topic]]' → 'topic'
+ */
+function extractParamName(bracketKey: string): string | null {
+  const seg = classifyUrlSegment(bracketKey);
+  if (seg.kind === 'static') return null;
+  return seg.name;
+}
+
+/**
+ * Validate schema keys against the filesystem route tree.
+ *
+ * Returns warnings for:
+ * - Stale keys: schema keys that don't match any filesystem segment
+ * - Bracket form mismatches: same param name, different bracket form
+ * - Missing keys: filesystem segments not registered in schema (informational)
+ */
+export function validateSchemaAgainstRoutes(tree: RouteTree, appDir: string): SchemaWarning[] {
+  const schemaPath = findSchemaFile(appDir);
+  if (!schemaPath) return [];
+
+  const content = readFileSync(schemaPath, 'utf-8');
+  const schemaKeys = parseExistingSchemaKeys(content);
+
+  if (schemaKeys.length === 0) return [];
+
+  const filesystemSegments = collectDynamicSegmentsFromTree(tree);
+
+  return validateKeys(schemaKeys, filesystemSegments);
+}
+
+/**
+ * Core validation: compare schema keys against filesystem segments.
+ * Exported separately for testing without filesystem dependencies.
+ */
+export function validateKeys(
+  schemaKeys: string[],
+  filesystemSegments: Set<string>
+): SchemaWarning[] {
+  const warnings: SchemaWarning[] = [];
+
+  // Build a map of param name → bracket form for filesystem segments
+  const fsParamToKey = new Map<string, string>();
+  for (const fsKey of filesystemSegments) {
+    const name = extractParamName(fsKey);
+    if (name) {
+      fsParamToKey.set(name, fsKey);
+    }
+  }
+
+  // Build a set of schema param names for the missing-key check
+  const schemaParamNames = new Set<string>();
+
+  for (const schemaKey of schemaKeys) {
+    const schemaParamName = extractParamName(schemaKey);
+    if (!schemaParamName) continue;
+
+    schemaParamNames.add(schemaParamName);
+
+    if (filesystemSegments.has(schemaKey)) {
+      // Exact match — no issue
+      continue;
+    }
+
+    // Check if the param name exists but with a different bracket form
+    const fsKey = fsParamToKey.get(schemaParamName);
+    if (fsKey) {
+      warnings.push({
+        type: 'bracket-mismatch',
+        key: schemaKey,
+        filesystemKey: fsKey,
+        message:
+          `Schema key '${schemaKey}' does not match filesystem bracket form '${fsKey}'. ` +
+          `Update the schema key to '${fsKey}'.`,
+      });
+    } else {
+      warnings.push({
+        type: 'stale-key',
+        key: schemaKey,
+        message:
+          `Schema key '${schemaKey}' does not match any dynamic segment in the filesystem. ` +
+          `Remove it from app/schema.ts or create the corresponding route segment.`,
+      });
+    }
+  }
+
+  // Check for filesystem segments not in schema (informational)
+  for (const fsKey of filesystemSegments) {
+    const name = extractParamName(fsKey);
+    if (name && !schemaParamNames.has(name)) {
+      warnings.push({
+        type: 'missing-key',
+        key: fsKey,
+        message:
+          `Dynamic segment '${fsKey}' has no codec in app/schema.ts (defaults to string). ` +
+          `Run: timber schema sync`,
+      });
+    }
+  }
+
+  return warnings;
+}

package/src/server/actions.ts

@@ -60,21 +60,11 @@ export interface ActionHandlerResult {
 // (the previous module-level global was vulnerable to cross-request pollution).
 
 /**
- * Set the revalidation state for the current action execution.
- * @internal — kept for test compatibility; prefer executeAction() which uses ALS.
+ * Run `fn` inside a revalidation ALS scope.
+ * @internal — for tests that call revalidatePath/Tag directly without executeAction().
  */
-export function _setRevalidationState(state: RevalidationState): void {
-  // Enter ALS scope — this is only used by tests that call revalidatePath/Tag
-  // directly without going through executeAction().
-  revalidationAls.enterWith(state);
-}
-
-/**
- * Clear the revalidation state after action execution.
- * @internal — kept for test compatibility.
- */
-export function _clearRevalidationState(): void {
-  revalidationAls.enterWith(undefined as unknown as RevalidationState);
+export function _runWithRevalidationState<T>(state: RevalidationState, fn: () => T): T {
+  return revalidationAls.run(state, fn);
 }
 
 /**

package/src/server/build-manifest.ts

@@ -35,6 +35,12 @@ export interface BuildManifest {
   modulepreload: Record<string, string[]>;
   /** Map from input file path to font assets used by that module. */
   fonts: Record<string, ManifestFontEntry[]>;
+  /**
+   * Cache-busting hashes for metadata route files (opengraph-image, etc.).
+   * Map from file path (relative to project root) to short content hash.
+   * In dev mode this is empty — a startup nonce is used instead.
+   */
+  metadataRouteHashes?: Record<string, string>;
 }
 
 /** Empty build manifest used in dev mode. */
@@ -43,6 +49,7 @@ export const EMPTY_BUILD_MANIFEST: BuildManifest = {
   js: {},
   modulepreload: {},
   fonts: {},
+  metadataRouteHashes: {},
 };
 
 /** Segment shape expected by collectRouteCss (matches ManifestSegmentNode). */

package/src/server/internal.ts

@@ -114,7 +114,13 @@ export {
   getMetadataRouteAutoLink,
   METADATA_ROUTE_CONVENTIONS,
 } from './metadata-routes.js';
-export type { MetadataRouteInfo, MetadataRouteType } from './metadata-routes.js';
+export type {
+  MetadataRouteInfo,
+  MetadataRouteType,
+  AutoLinkTag,
+  AutoLinkLink,
+  AutoLinkMeta,
+} from './metadata-routes.js';
 
 // ── Server Actions (pipeline internals) ──────────────────────────────────
 export { executeAction, buildNoJsResponse, isRscActionRequest } from './actions.js';

package/src/server/metadata-routes.ts

@@ -29,7 +29,6 @@ export type MetadataRouteType =
   | 'favicon'
   | 'icon'
   | 'opengraph-image'
-  | 'twitter-image'
   | 'apple-icon';
 
 // ─── Convention Table ────────────────────────────────────────────────────────
@@ -84,7 +83,7 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     contentType: 'image/x-icon',
     nestable: false,
     staticExtensions: ['ico'],
-    dynamicExtensions: [],
+    dynamicExtensions: ['ts', 'tsx'],
     servePath: 'favicon.ico',
   },
   'icon': {
@@ -103,14 +102,7 @@ export const METADATA_ROUTE_CONVENTIONS: Record<
     dynamicExtensions: ['ts', 'tsx'],
     servePath: 'opengraph-image',
   },
-  'twitter-image': {
-    type: 'twitter-image',
-    contentType: 'image/*',
-    nestable: true,
-    staticExtensions: ['png', 'jpg'],
-    dynamicExtensions: ['ts', 'tsx'],
-    servePath: 'twitter-image',
-  },
+
   'apple-icon': {
     type: 'apple-icon',
     contentType: 'image/*',
@@ -225,26 +217,59 @@ export function getMetadataRouteServePath(type: MetadataRouteType): string {
   throw new Error(`[timber] Unknown metadata route type: ${type}`);
 }
 
+const METADATA_SERVE_PATHS = new Set(
+  Object.values(METADATA_ROUTE_CONVENTIONS).map((c) => c.servePath)
+);
+
+export function isMetadataRouteServePath(pathname: string): boolean {
+  const lastSegment = pathname.slice(pathname.lastIndexOf('/') + 1);
+  return METADATA_SERVE_PATHS.has(lastSegment);
+}
+
+/** A <link> auto-link tag. */
+export interface AutoLinkLink {
+  tag: 'link';
+  rel: string;
+  href: string;
+  type?: string;
+}
+
+/** A <meta> auto-link tag. */
+export interface AutoLinkMeta {
+  tag: 'meta';
+  property?: string;
+  name?: string;
+  content: string;
+}
+
+export type AutoLinkTag = AutoLinkLink | AutoLinkMeta;
+
 /**
  * Get the auto-link tags to inject into <head> for metadata route files
  * discovered in a segment.
  *
+ * Returns link tags for icon/apple-icon/manifest, and meta tags for
+ * opengraph-image (emits both og:image and twitter:image). Returns null
+ * for types that don't auto-link (favicon, sitemap, robots).
+ *
  * @param type - The metadata route type
  * @param href - The resolved URL path to the metadata route
- * @returns An object with tag/attrs for the <head>, or null if no auto-link
+ * @returns Tag descriptor(s) for the <head>, or null if no auto-link
  */
-export function getMetadataRouteAutoLink(
-  type: MetadataRouteType,
-  href: string
-): { rel: string; href: string; type?: string } | null {
+export function getMetadataRouteAutoLink(type: MetadataRouteType, href: string): AutoLinkTag[] {
   switch (type) {
     case 'icon':
-      return { rel: 'icon', href };
+      return [{ tag: 'link', rel: 'icon', href }];
     case 'apple-icon':
-      return { rel: 'apple-touch-icon', href };
+      return [{ tag: 'link', rel: 'apple-touch-icon', href }];
     case 'manifest':
-      return { rel: 'manifest', href };
+      return [{ tag: 'link', rel: 'manifest', href }];
+    case 'opengraph-image':
+      return [
+        { tag: 'meta', property: 'og:image', content: href },
+        { tag: 'meta', name: 'twitter:image', content: href },
+      ];
     default:
-      return null;
+      return [];
   }
 }

package/src/server/pipeline-phases.ts

@@ -232,6 +232,7 @@ export async function handleRequest(
           return await serveStaticMetadataFile(metaMatch);
         }
 
+        setSegmentParams(metaMatch.segmentParams);
         const mod = await loadModule<{ default?: MetadataHandler }>(metaMatch.file);
         if (typeof mod.default !== 'function') {
           if (isDebug()) {
@@ -247,6 +248,13 @@ export async function handleRequest(
         // outer Server-Timing writer can append without hitting an
         // immutable header bag (e.g. user returns Response.redirect()).
         if (handlerResult instanceof Response) {
+          if (method === 'HEAD') {
+            return new Response(null, {
+              status: handlerResult.status,
+              statusText: handlerResult.statusText,
+              headers: new Headers(handlerResult.headers),
+            });
+          }
           return cloneWithMutableHeaders(handlerResult);
         }
         // Otherwise, serialize based on content type. The type discriminator

package/src/server/request-context.ts

@@ -23,10 +23,6 @@ import { isDebug } from './debug.js';
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
 
-// No fallback needed — we use enterWith() instead of run() to ensure
-// the ALS context persists for the entire request lifecycle including
-// async stream consumption by React's renderToReadableStream.
-
 // ─── Public API ───────────────────────────────────────────────────────────
 
 /**

package/src/server/route-element-builder.ts

@@ -17,14 +17,22 @@
  */
 
 import { createElement } from 'react';
+import { randomUUID } from 'node:crypto';
 
 import { withSpan } from './tracing.js';
 import type { RouteMatch } from './pipeline.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
-import type { HeadElement as MetadataHeadElement } from './metadata.js';
 import type { Metadata } from './types.js';
 import { METADATA_ROUTE_CONVENTIONS, getMetadataRouteAutoLink } from './metadata-routes.js';
+
+// In dev mode, use a per-startup nonce for metadata route cache busting
+// instead of per-file content hashes (avoids rehashing on every request).
+let _devNonce: string | undefined;
+function getDevNonce(): string {
+  _devNonce ??= randomUUID().slice(0, 8);
+  return _devNonce;
+}
 import { DenySignal, RedirectSignal } from './primitives.js';
 import { AccessGate } from './access-gate.js';
 import {
@@ -215,7 +223,8 @@ export async function buildRouteElement(
   req: Request,
   match: RouteMatch,
   interception?: InterceptionContext,
-  clientStateTree?: Set<string> | null
+  clientStateTree?: Set<string> | null,
+  metadataRouteHashes?: Record<string, string>
 ): Promise<RouteElementResult> {
   const segments = match.segments;
 
@@ -309,8 +318,20 @@ export async function buildRouteElement(
   const resolvedMetadata = resolveMetadata(metadataEntries);
   const headElements = renderMetadataToElements(resolvedMetadata);
 
-  // Auto-link metadata route files (icon, apple-icon, manifest) from segments.
+  // Auto-link metadata route files (icon, apple-icon, manifest, opengraph-image).
+  // opengraph-image emits both og:image and twitter:image (no separate twitter-image convention).
+  // Skip OG auto-linking when the user already declared images in metadata.
   // See design/16-metadata.md §"Auto-Linking"
+  const hasUserOgImage = Boolean(resolvedMetadata.openGraph?.images);
+  const requestUrl = new URL(req.url);
+  const requestPathname = requestUrl.pathname;
+  // In dev mode, use the request origin so OG URLs resolve to localhost.
+  // In production, use metadataBase (the canonical domain).
+  const ogBase =
+    process.env.NODE_ENV !== 'production'
+      ? new URL(requestUrl.origin)
+      : resolvedMetadata.metadataBase;
+
   for (const segment of segments) {
     if (!segment.metadataRoutes) continue;
     for (const baseName of Object.keys(segment.metadataRoutes)) {
@@ -318,14 +339,39 @@ export async function buildRouteElement(
       if (!convention) continue;
       // Non-nestable routes only auto-link from root
       if (!convention.nestable && segment.urlPath !== '/') continue;
-      // Build the href: segment urlPath + serve path
-      const prefix = segment.urlPath === '/' ? '' : segment.urlPath;
-      const href = `${prefix}/${convention.servePath}`;
-      const autoLink = getMetadataRouteAutoLink(convention.type, href);
-      if (autoLink) {
-        const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };
-        if (autoLink.type) attrs.type = autoLink.type;
-        headElements.push({ tag: 'link', attrs } as MetadataHeadElement);
+      // Skip auto-linking if user already declared the image in metadata
+      if (convention.type === 'opengraph-image' && hasUserOgImage) continue;
+      // Build the href using the actual request path (not the pattern with [param]).
+      // For nestable routes, the metadata route sits under the same resolved path
+      // as the page. For root-only routes, use '/'.
+      const resolvedPrefix = convention.nestable
+        ? requestPathname === '/'
+          ? ''
+          : requestPathname
+        : '';
+      let href = `${resolvedPrefix}/${convention.servePath}`;
+      // Append cache-bust query param for image metadata routes
+      if (convention.type === 'opengraph-image') {
+        const metaFile = segment.metadataRoutes[baseName];
+        const fileHash = metaFile?.filePath ? metadataRouteHashes?.[metaFile.filePath] : undefined;
+        const cacheBust = fileHash ?? getDevNonce();
+        href = `${href}?${cacheBust}`;
+      }
+      // Resolve to absolute URL for og:image/twitter:image (social crawlers need full URLs)
+      if (ogBase && convention.type === 'opengraph-image') {
+        href = new URL(href, ogBase).toString();
+      }
+      for (const autoLink of getMetadataRouteAutoLink(convention.type, href)) {
+        if (autoLink.tag === 'link') {
+          const attrs: Record<string, string> = { rel: autoLink.rel, href: autoLink.href };
+          if (autoLink.type) attrs.type = autoLink.type;
+          headElements.push({ tag: 'link', attrs });
+        } else {
+          const attrs: Record<string, string> = { content: autoLink.content };
+          if (autoLink.property) attrs.property = autoLink.property;
+          if (autoLink.name) attrs.name = autoLink.name;
+          headElements.push({ tag: 'meta', attrs });
+        }
       }
     }
   }

package/src/server/route-matcher.ts

@@ -121,73 +121,105 @@ export interface MetadataRouteMatch {
    * that should be served from disk rather than executed as a handler.
    */
   isStatic: boolean;
+  /** Extracted segment params from dynamic segments in the URL prefix. */
+  segmentParams: Record<string, string | string[]>;
+}
+
+// Reverse lookup: serve path → convention base name
+const SERVE_PATH_TO_CONVENTION = new Map<string, string>();
+for (const [baseName, convention] of Object.entries(METADATA_ROUTE_CONVENTIONS)) {
+  SERVE_PATH_TO_CONVENTION.set(convention.servePath, baseName);
 }
 
 /**
  * Create a metadata route matcher from a manifest.
  *
- * Walks the segment tree and builds a map from serve paths to handler modules.
- * Metadata routes are matched by exact pathname (e.g., /sitemap.xml, /blog/sitemap.xml).
+ * Uses dynamic tree matching to resolve metadata routes, supporting
+ * dynamic segments like /docs/[slug]/opengraph-image.
  *
  * See design/16-metadata.md §"Metadata Routes"
  */
 export function createMetadataRouteMatcher(
   manifest: ManifestRoot
 ): (pathname: string) => MetadataRouteMatch | null {
-  // Build a static lookup map: pathname → match info
-  const routeMap = new Map<string, MetadataRouteMatch>();
-  collectMetadataRoutes(manifest.root, routeMap);
+  return (pathname: string) => matchMetadataPathname(manifest.root, pathname);
+}
+
+/**
+ * Match a pathname against metadata routes in the segment tree.
+ *
+ * Checks if the last URL part is a known metadata route serve path,
+ * then walks the tree to find the segment that owns the route.
+ */
+function matchMetadataPathname(
+  root: ManifestSegmentNode,
+  pathname: string
+): MetadataRouteMatch | null {
+  const parts = pathname === '/' ? [] : pathname.slice(1).split('/');
+  if (parts.length === 0) return null;
+
+  const lastPart = parts[parts.length - 1];
+  const baseName = SERVE_PATH_TO_CONVENTION.get(lastPart);
+  if (!baseName) return null;
+
+  const convention = METADATA_ROUTE_CONVENTIONS[baseName];
+  if (!convention) return null;
+
+  // The prefix parts identify which segment owns this metadata route.
+  // For root-level routes (e.g. /sitemap.xml), prefix is empty → root segment.
+  const prefixParts = parts.slice(0, -1);
+
+  let segment: ManifestSegmentNode;
+  let params: Record<string, string | string[]>;
+
+  if (prefixParts.length === 0) {
+    segment = root;
+    params = {};
+  } else {
+    const result = matchUrlParts(root, prefixParts, { requireTerminal: false });
+    if (!result) return null;
+    segment = result.chain[result.chain.length - 1];
+    params = result.params;
+  }
+
+  // Non-nestable routes (robots, manifest, favicon) only serve from root
+  if (!convention.nestable && segment !== root) return null;
 
-  return (pathname: string) => routeMap.get(pathname) ?? null;
+  const file = findMetadataRouteInSegment(segment, baseName);
+  if (!file) return null;
+
+  const ext = file.filePath.slice(file.filePath.lastIndexOf('.') + 1);
+  const isStatic = isStaticMetadataExtension(baseName, ext);
+  const contentType = isStatic
+    ? resolveStaticContentType(convention.contentType, ext)
+    : convention.contentType;
+
+  return {
+    type: convention.type,
+    contentType,
+    file,
+    segment,
+    isStatic,
+    segmentParams: params,
+  };
 }
 
 /**
- * Recursively collect metadata routes from the segment tree into a lookup map.
+ * Find a metadata route file in a segment, including transparent group children.
+ * Groups don't add URL depth, so their metadata routes are reachable at the parent's path.
  */
-function collectMetadataRoutes(
+function findMetadataRouteInSegment(
   node: ManifestSegmentNode,
-  map: Map<string, MetadataRouteMatch>
-): void {
-  if (node.metadataRoutes) {
-    for (const [baseName, file] of Object.entries(node.metadataRoutes)) {
-      const convention = METADATA_ROUTE_CONVENTIONS[baseName];
-      if (!convention) continue;
-
-      // Non-nestable routes (robots, manifest, favicon) only serve from root
-      if (!convention.nestable && node.urlPath !== '/') continue;
-
-      // Build the serve pathname: segment urlPath + serve path
-      const prefix = node.urlPath === '/' ? '' : node.urlPath;
-      const pathname = `${prefix}/${convention.servePath}`;
-
-      // Determine if this is a static file based on its extension.
-      // Static files (.xml, .txt, .png, .ico, etc.) are served from disk.
-      // Dynamic files (.ts, .tsx) export a handler function.
-      const ext = file.filePath.slice(file.filePath.lastIndexOf('.') + 1);
-      const isStatic = isStaticMetadataExtension(baseName, ext);
-
-      // Resolve generic content types (e.g. image/*) to concrete MIME types
-      // based on the file extension for static files.
-      const contentType = isStatic
-        ? resolveStaticContentType(convention.contentType, ext)
-        : convention.contentType;
-
-      map.set(pathname, {
-        type: convention.type,
-        contentType,
-        file,
-        segment: node,
-        isStatic,
-      });
-    }
+  baseName: string
+): ManifestFile | null {
+  if (node.metadataRoutes?.[baseName]) {
+    return node.metadataRoutes[baseName];
   }
-
   for (const child of node.children) {
-    collectMetadataRoutes(child, map);
-  }
-
-  // Also check inside group segments (they're transparent for URL paths)
-  for (const slotNode of Object.values(node.slots)) {
-    collectMetadataRoutes(slotNode, map);
+    if (child.segmentType === 'group') {
+      const found = findMetadataRouteInSegment(child, baseName);
+      if (found) return found;
+    }
   }
+  return null;
 }

package/src/server/rsc-entry/index.ts

@@ -444,7 +444,13 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       // AccessGate → getSegmentParams() throws because segmentParams
       // is never set. See TIM-667.
       setSegmentParams(revalidateMatch.segmentParams);
-      const routeResult = await buildRouteElement(revalidateReq, revalidateMatch);
+      const routeResult = await buildRouteElement(
+        revalidateReq,
+        revalidateMatch,
+        undefined,
+        null,
+        (buildManifest as BuildManifest).metadataRouteHashes
+      );
       return {
         element: routeResult.element,
         headElements: routeResult.headElements,

package/src/server/rsc-entry/render-route.ts

@@ -108,7 +108,13 @@ export async function renderRoute(
   let routeResult;
   const _buildStart = performance.now();
   try {
-    routeResult = await buildRouteElement(req, match, interception, clientStateTree);
+    routeResult = await buildRouteElement(
+      req,
+      match,
+      interception,
+      clientStateTree,
+      buildManifest.metadataRouteHashes
+    );
   } catch (error) {
     // Param coercion failed — render the custom 404 page (status files / not-found).
     // Previously returned a bare Response(null, { status: 404 }) which bypassed

package/src/server/ssr-entry.ts

@@ -18,6 +18,12 @@ import config from 'virtual:timber-config';
 // during SSR can serialize flat `Partial<T>` values via registry lookup.
 // @ts-expect-error — virtual module provided by timber-routing plugin
 import 'virtual:timber-search-params-registry';
+// TIM-949: Populate the codec registry so server-rendered <Link> components
+// use codec.serialize() instead of String() fallback for URL interpolation.
+// @ts-expect-error — virtual module provided by timber-routing plugin
+import schemaCodecs from 'virtual:timber-schema';
+import { setLinkCodecs } from '../params/codec-registry.js';
+setLinkCodecs(schemaCodecs);
 import {
   createFromReadableStream,
   createFromNodeStream,