@timber-js/app 0.2.0-alpha.5 → 0.2.0-alpha.50

package/src/server/request-context.ts

@@ -10,10 +10,9 @@
  * See design/29-cookies.md for cookie mutation semantics.
  */
 
-import { createHmac, timingSafeEqual } from 'node:crypto';
-import type { Routes } from '#/index.js';
 import { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';
 import { isDebug } from './debug.js';
+import { _setRawSearchParamsFn } from '#/search-params/define.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
@@ -22,30 +21,6 @@ export { requestContextAls };
 // the ALS context persists for the entire request lifecycle including
 // async stream consumption by React's renderToReadableStream.
 
-// ─── Cookie Signing Secrets ──────────────────────────────────────────────
-
-/**
- * Module-level cookie signing secrets. Index 0 is the newest (used for signing).
- * All entries are tried for verification (key rotation support).
- *
- * Set by the framework at startup via `setCookieSecrets()`.
- * See design/29-cookies.md §"Signed Cookies"
- */
-let _cookieSecrets: string[] = [];
-
-/**
- * Configure the cookie signing secrets.
- *
- * Called by the framework during server initialization with values from
- * `cookies.secret` or `cookies.secrets` in timber.config.ts.
- *
- * The first secret (index 0) is used for signing new cookies.
- * All secrets are tried for verification (supports key rotation).
- */
-export function setCookieSecrets(secrets: string[]): void {
-  _cookieSecrets = secrets.filter(Boolean);
-}
-
 // ─── Public API ───────────────────────────────────────────────────────────
 
 /**
@@ -109,12 +84,6 @@ export function cookies(): RequestCookies {
       return map.size;
     },
 
-    getSigned(name: string): string | undefined {
-      const raw = map.get(name);
-      if (!raw || _cookieSecrets.length === 0) return undefined;
-      return verifySignedCookie(raw, _cookieSecrets);
-    },
-
     set(name: string, value: string, options?: CookieOptions): void {
       assertMutable(store, 'set');
       if (store.flushed) {
@@ -127,21 +96,10 @@ export function cookies(): RequestCookies {
         }
         return;
       }
-      let storedValue = value;
-      if (options?.signed) {
-        if (_cookieSecrets.length === 0) {
-          throw new Error(
-            `[timber] cookies().set('${name}', ..., { signed: true }) requires ` +
-              `cookies.secret or cookies.secrets in timber.config.ts.`
-          );
-        }
-        storedValue = signCookieValue(value, _cookieSecrets[0]);
-      }
       const opts = { ...DEFAULT_COOKIE_OPTIONS, ...options };
-      store.cookieJar.set(name, { name, value: storedValue, options: opts });
-      // Read-your-own-writes: update the parsed cookies map with the signed value
-      // so getSigned() can verify it in the same request
-      map.set(name, storedValue);
+      store.cookieJar.set(name, { name, value, options: opts });
+      // Read-your-own-writes: update the parsed cookies map
+      map.set(name, value);
     },
 
     delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {
@@ -190,41 +148,107 @@ export function cookies(): RequestCookies {
 }
 
 /**
- * Returns a Promise resolving to the current request's search params.
+ * Returns a Promise resolving to the current request's raw URLSearchParams.
+ *
+ * For typed, parsed search params, import the definition from params.ts
+ * and call `.load()` or `.parse()`:
  *
- * In `page.tsx`, `middleware.ts`, and `access.ts` the framework pre-parses the
- * route's `search-params.ts` definition and the Promise resolves to the typed
- * object. In all other server component contexts it resolves to raw
- * `URLSearchParams`.
+ * ```ts
+ * import { searchParams } from './params'
+ * const parsed = await searchParams.load()
+ * ```
  *
- * Returned as a Promise to match the `params` prop convention and to allow
- * future partial pre-rendering support where param resolution may be deferred.
+ * Or explicitly:
+ *
+ * ```ts
+ * import { rawSearchParams } from '@timber-js/app/server'
+ * import { searchParams } from './params'
+ * const parsed = searchParams.parse(await rawSearchParams())
+ * ```
  *
  * Throws if called outside a request context.
  */
-export function searchParams<R extends keyof Routes>(): Promise<Routes[R]['searchParams']>;
-export function searchParams(): Promise<URLSearchParams | Record<string, unknown>>;
-export function searchParams(): Promise<URLSearchParams | Record<string, unknown>> {
+export function rawSearchParams(): Promise<URLSearchParams> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] searchParams() called outside of a request context. ' +
+      '[timber] rawSearchParams() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
   return store.searchParamsPromise;
 }
 
+// Eagerly register rawSearchParams with the search-params module so
+// searchParams.load() can call it synchronously without a dynamic import.
+// Dynamic imports lose ALS context in React's RSC Flight renderer,
+// breaking rawSearchParams() in parallel slot pages. See TIM-523.
+_setRawSearchParamsFn(rawSearchParams);
+
 /**
- * Replace the search params Promise for the current request with one that
- * resolves to the typed parsed result from the route's search-params.ts.
- * Called by the framework before rendering the page — not for app code.
+ * Returns a Promise resolving to the current request's coerced segment params.
+ *
+ * Segment params are set by the pipeline after route matching and param
+ * coercion (via params.ts codecs). When no params.ts exists, values are
+ * raw strings. When codecs are defined, values are already coerced
+ * (e.g., `id` is a `number` if `defineSegmentParams({ id: z.coerce.number() })`).
+ *
+ * This is the primary way page and layout components access route params:
+ *
+ * ```ts
+ * import { rawSegmentParams } from '@timber-js/app/server'
+ *
+ * export default async function Page() {
+ *   const { slug } = await rawSegmentParams()
+ *   // ...
+ * }
+ * ```
+ *
+ * Throws if called outside a request context.
  */
-export function setParsedSearchParams(parsed: Record<string, unknown>): void {
+export function rawSegmentParams(): Promise<Record<string, string | string[]>> {
   const store = requestContextAls.getStore();
-  if (store) {
-    store.searchParamsPromise = Promise.resolve(parsed);
+  if (!store) {
+    throw new Error(
+      '[timber] rawSegmentParams() called outside of a request context. ' +
+        'It can only be used in middleware, access checks, server components, and server actions.'
+    );
   }
+  if (!store.segmentParamsPromise) {
+    throw new Error(
+      '[timber] rawSegmentParams() called before route matching completed. ' +
+        'Segment params are not available until after the route is matched.'
+    );
+  }
+  return store.segmentParamsPromise;
+}
+
+/**
+ * Set the segment params promise on the current request context.
+ * Called by the pipeline after route matching and param coercion.
+ *
+ * @internal — framework use only
+ */
+export function setSegmentParams(params: Record<string, string | string[]>): void {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error('[timber] setSegmentParams() called outside of a request context.');
+  }
+  store.segmentParamsPromise = Promise.resolve(params);
+}
+
+/**
+ * Returns the raw search string from the current request URL (e.g. "?foo=bar").
+ * Synchronous — safe for use in `redirect()` which throws synchronously.
+ *
+ * Returns empty string if called outside a request context (non-throwing for
+ * use in redirect's optional preserveSearchParams path).
+ *
+ * @internal — used by redirect() for preserveSearchParams support.
+ */
+export function getRequestSearchString(): string {
+  const store = requestContextAls.getStore();
+  return store?.searchString ?? '';
 }
 
 // ─── Types ────────────────────────────────────────────────────────────────
@@ -257,12 +281,6 @@ export interface CookieOptions {
   sameSite?: 'strict' | 'lax' | 'none';
   /** Partitioned (CHIPS) — isolate cookie per top-level site. Default: false. */
   partitioned?: boolean;
-  /**
-   * Sign the cookie value with HMAC-SHA256 for integrity verification.
-   * Requires `cookies.secret` or `cookies.secrets` in timber.config.ts.
-   * See design/29-cookies.md §"Signed Cookies".
-   */
-  signed?: boolean;
 }
 
 const DEFAULT_COOKIE_OPTIONS: CookieOptions = {
@@ -287,14 +305,6 @@ export interface RequestCookies {
   getAll(): Array<{ name: string; value: string }>;
   /** Number of cookies. */
   readonly size: number;
-  /**
-   * Get a signed cookie value, verifying its HMAC-SHA256 signature.
-   * Returns undefined if the cookie is missing, the signature is invalid,
-   * or no secrets are configured. Never throws.
-   *
-   * See design/29-cookies.md §"Signed Cookies"
-   */
-  getSigned(name: string): string | undefined;
   /** Set a cookie. Only available in mutable contexts (middleware, actions, route handlers). */
   set(name: string, value: string, options?: CookieOptions): void;
   /** Delete a cookie. Only available in mutable contexts. */
@@ -316,11 +326,13 @@ export interface RequestCookies {
  */
 export function runWithRequestContext<T>(req: Request, fn: () => T): T {
   const originalCopy = new Headers(req.headers);
+  const parsedUrl = new URL(req.url);
   const store: RequestContextStore = {
     headers: freezeHeaders(req.headers),
     originalHeaders: originalCopy,
     cookieHeader: req.headers.get('cookie') ?? '',
-    searchParamsPromise: Promise.resolve(new URL(req.url).searchParams),
+    searchParamsPromise: Promise.resolve(parsedUrl.searchParams),
+    searchString: parsedUrl.search,
     cookieJar: new Map(),
     flushed: false,
     mutableContext: false,
@@ -354,6 +366,35 @@ export function markResponseFlushed(): void {
   }
 }
 
+/**
+ * Build a Map of cookie name → value reflecting the current request's
+ * read-your-own-writes state. Includes incoming cookies plus any
+ * mutations from cookies().set() / cookies().delete() in the same request.
+ *
+ * Used by SSR renderers to populate NavContext.cookies so that
+ * useCookie()'s server snapshot matches the actual response state.
+ *
+ * See design/29-cookies.md §"Read-Your-Own-Writes"
+ * See design/triage/TIM-441-cookie-api-triage.md §4
+ */
+export function getCookiesForSsr(): Map<string, string> {
+  const store = requestContextAls.getStore();
+  if (!store) {
+    throw new Error('[timber] getCookiesForSsr() called outside of a request context.');
+  }
+
+  // Trigger lazy parsing if not yet done
+  if (!store.parsedCookies) {
+    store.parsedCookies = parseCookieHeader(store.cookieHeader);
+  }
+
+  // The parsedCookies map already reflects read-your-own-writes:
+  // - cookies().set() updates the map via map.set(name, value)
+  // - cookies().delete() removes from the map via map.delete(name)
+  // Return a copy so callers can't mutate the internal map.
+  return new Map(store.parsedCookies);
+}
+
 /**
  * Collect all Set-Cookie headers from the cookie jar.
  * Called by the framework at flush time to apply cookies to the response.
@@ -467,47 +508,6 @@ function parseCookieHeader(header: string): Map<string, string> {
   return map;
 }
 
-// ─── Cookie Signing ──────────────────────────────────────────────────────
-
-/**
- * Sign a cookie value with HMAC-SHA256.
- * Returns `value.hex_signature`.
- */
-function signCookieValue(value: string, secret: string): string {
-  const signature = createHmac('sha256', secret).update(value).digest('hex');
-  return `${value}.${signature}`;
-}
-
-/**
- * Verify a signed cookie value against an array of secrets.
- * Returns the original value if any secret produces a matching signature,
- * or undefined if none match. Uses timing-safe comparison.
- *
- * The signed format is `value.hex_signature` — split at the last `.`.
- */
-function verifySignedCookie(raw: string, secrets: string[]): string | undefined {
-  const lastDot = raw.lastIndexOf('.');
-  if (lastDot <= 0 || lastDot === raw.length - 1) return undefined;
-
-  const value = raw.slice(0, lastDot);
-  const signature = raw.slice(lastDot + 1);
-
-  // Hex-encoded SHA-256 is always 64 chars
-  if (signature.length !== 64) return undefined;
-
-  const signatureBuffer = Buffer.from(signature, 'hex');
-  // If the hex decode produced fewer bytes, the signature was not valid hex
-  if (signatureBuffer.length !== 32) return undefined;
-
-  for (const secret of secrets) {
-    const expected = createHmac('sha256', secret).update(value).digest();
-    if (timingSafeEqual(expected, signatureBuffer)) {
-      return value;
-    }
-  }
-  return undefined;
-}
-
 /** Serialize a CookieEntry into a Set-Cookie header value. */
 function serializeCookieEntry(entry: CookieEntry): string {
   const parts = [`${entry.name}=${entry.value}`];

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

@@ -28,12 +28,24 @@ import { DenySignal, RedirectSignal } from './primitives.js';
 import { AccessGate } from './access-gate.js';
 import { resolveSlotElement } from './slot-resolver.js';
 import { SegmentProvider } from '#/client/segment-context.js';
-import { setParsedSearchParams } from './request-context.js';
-import type { SearchParamsDefinition } from '#/search-params/create.js';
+
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
 import type { InterceptionContext } from './pipeline.js';
 import { shouldSkipSegment } from './state-tree-diff.js';
 
+// ─── Param Coercion Error ─────────────────────────────────────────────────
+
+/**
+ * Thrown when a defineSegmentParams codec's parse() fails.
+ * The pipeline catches this and responds with 404.
+ */
+export class ParamCoercionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ParamCoercionError';
+  }
+}
+
 // ─── Types ────────────────────────────────────────────────────────────────
 
 /** Head element for client-side metadata updates. */
@@ -84,6 +96,64 @@ export class RouteSignalWithContext extends Error {
   }
 }
 
+// ─── Module Processing Helpers ─────────────────────────────────────────────
+
+/**
+ * Reject the legacy `generateMetadata` export with a helpful migration message.
+ * Throws if the module exports `generateMetadata` instead of `metadata`.
+ */
+function rejectLegacyGenerateMetadata(mod: Record<string, unknown>, filePath: string): void {
+  if ('generateMetadata' in mod) {
+    throw new Error(
+      `${filePath}: "generateMetadata" is not a valid export. ` +
+        `Export an async function named "metadata" instead.\n\n` +
+        `  // Before\n` +
+        `  export async function generateMetadata({ params }) { ... }\n\n` +
+        `  // After\n` +
+        `  export async function metadata() { ... }`
+    );
+  }
+}
+
+/**
+ * Extract and resolve metadata from a module (layout or page).
+ * Handles both static metadata objects and async metadata functions.
+ * Returns the resolved Metadata, or null if none exported.
+ *
+ * Metadata functions no longer receive { params } — they access params
+ * via rawSegmentParams() from ALS, same as page/layout components.
+ */
+async function extractMetadata(
+  mod: Record<string, unknown>,
+  segment: ManifestSegmentNode
+): Promise<Metadata | null> {
+  if (typeof mod.metadata === 'function') {
+    type MetadataFn = () => Promise<Metadata>;
+    return (
+      (await withSpan(
+        'timber.metadata',
+        { 'timber.segment': segment.segmentName ?? segment.urlPath },
+        () => (mod.metadata as MetadataFn)()
+      )) ?? null
+    );
+  }
+  if (mod.metadata) {
+    return mod.metadata as Metadata;
+  }
+  return null;
+}
+
+/**
+ * Extract `deferSuspenseFor` from a module and return the maximum
+ * of the current value and the module's value.
+ */
+function extractDeferSuspenseFor(mod: Record<string, unknown>, current: number): number {
+  if (typeof mod.deferSuspenseFor === 'number' && mod.deferSuspenseFor > current) {
+    return mod.deferSuspenseFor;
+  }
+  return current;
+}
+
 // ─── Builder ──────────────────────────────────────────────────────────────
 
 /**
@@ -104,9 +174,6 @@ export async function buildRouteElement(
 ): Promise<RouteElementResult> {
   const segments = match.segments as unknown as ManifestSegmentNode[];
 
-  // Params are passed as a Promise to match Next.js 15+ convention.
-  const paramsPromise = Promise.resolve(match.params);
-
   // Load all modules along the segment chain
   const metadataEntries: Array<{ metadata: Metadata; isPage: boolean }> = [];
   const layoutComponents: LayoutComponentEntry[] = [];
@@ -126,87 +193,34 @@ export async function buildRouteElement(
           segment,
         });
       }
-      // Reject legacy generateMetadata export — use `export async function metadata()` instead
-      if ('generateMetadata' in mod) {
-        const filePath = segment.layout.filePath ?? segment.urlPath;
-        throw new Error(
-          `${filePath}: "generateMetadata" is not a valid export. ` +
-            `Export an async function named "metadata" instead.\n\n` +
-            `  // Before\n` +
-            `  export async function generateMetadata({ params }) { ... }\n\n` +
-            `  // After\n` +
-            `  export async function metadata({ params }) { ... }`
-        );
-      }
-      // Unified metadata export: static object or async function
-      if (typeof mod.metadata === 'function') {
-        type MetadataFn = (props: Record<string, unknown>) => Promise<Metadata>;
-        const generated = await withSpan(
-          'timber.metadata',
-          { 'timber.segment': segment.segmentName ?? segment.urlPath },
-          () => (mod.metadata as MetadataFn)({ params: paramsPromise })
-        );
-        if (generated) {
-          metadataEntries.push({ metadata: generated, isPage: false });
-        }
-      } else if (mod.metadata) {
-        metadataEntries.push({ metadata: mod.metadata as Metadata, isPage: false });
-      }
-      // deferSuspenseFor hold window — max across all segments
-      if (typeof mod.deferSuspenseFor === 'number' && mod.deferSuspenseFor > deferSuspenseFor) {
-        deferSuspenseFor = mod.deferSuspenseFor;
+
+      // Param coercion is handled in the pipeline (Stage 2c) before
+      // middleware and rendering. See coerceSegmentParams() in pipeline.ts.
+
+      rejectLegacyGenerateMetadata(mod, segment.layout.filePath ?? segment.urlPath);
+      const layoutMetadata = await extractMetadata(mod, segment);
+      if (layoutMetadata) {
+        metadataEntries.push({ metadata: layoutMetadata, isPage: false });
       }
+      deferSuspenseFor = extractDeferSuspenseFor(mod, deferSuspenseFor);
     }
 
     // Load page (leaf segment only)
     if (isLeaf && segment.page) {
-      // Load and apply search-params.ts definition before rendering so
-      // searchParams() from @timber-js/app/server returns parsed typed values.
-      if (segment.searchParams) {
-        const spMod = (await segment.searchParams.load()) as {
-          default?: SearchParamsDefinition<Record<string, unknown>>;
-        };
-        if (spMod.default) {
-          const rawSearchParams = new URL(req.url).searchParams;
-          const parsed = spMod.default.parse(rawSearchParams);
-          setParsedSearchParams(parsed);
-        }
-      }
-
       const mod = (await segment.page.load()) as Record<string, unknown>;
+
+      // Param coercion is handled in the pipeline (Stage 2c) before
+      // middleware and rendering. See coerceSegmentParams() in pipeline.ts.
+
       if (mod.default) {
         PageComponent = mod.default as (...args: unknown[]) => unknown;
       }
-      // Reject legacy generateMetadata export — use `export async function metadata()` instead
-      if ('generateMetadata' in mod) {
-        const filePath = segment.page.filePath ?? segment.urlPath;
-        throw new Error(
-          `${filePath}: "generateMetadata" is not a valid export. ` +
-            `Export an async function named "metadata" instead.\n\n` +
-            `  // Before\n` +
-            `  export async function generateMetadata({ params }) { ... }\n\n` +
-            `  // After\n` +
-            `  export async function metadata({ params }) { ... }`
-        );
-      }
-      // Unified metadata export: static object or async function
-      if (typeof mod.metadata === 'function') {
-        type MetadataFn = (props: Record<string, unknown>) => Promise<Metadata>;
-        const generated = await withSpan(
-          'timber.metadata',
-          { 'timber.segment': segment.segmentName ?? segment.urlPath },
-          () => (mod.metadata as MetadataFn)({ params: paramsPromise })
-        );
-        if (generated) {
-          metadataEntries.push({ metadata: generated, isPage: true });
-        }
-      } else if (mod.metadata) {
-        metadataEntries.push({ metadata: mod.metadata as Metadata, isPage: true });
-      }
-      // deferSuspenseFor hold window — max across all segments
-      if (typeof mod.deferSuspenseFor === 'number' && mod.deferSuspenseFor > deferSuspenseFor) {
-        deferSuspenseFor = mod.deferSuspenseFor;
+      rejectLegacyGenerateMetadata(mod, segment.page.filePath ?? segment.urlPath);
+      const pageMetadata = await extractMetadata(mod, segment);
+      if (pageMetadata) {
+        metadataEntries.push({ metadata: pageMetadata, isPage: true });
       }
+      deferSuspenseFor = extractDeferSuspenseFor(mod, deferSuspenseFor);
     }
   }
 
@@ -227,7 +241,7 @@ export async function buildRouteElement(
     if (segment.access) {
       const accessMod = (await segment.access.load()) as Record<string, unknown>;
       const accessFn = accessMod.default as
-        | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
+        | ((ctx: { params: Record<string, string | string[]> }) => unknown)
         | undefined;
       if (accessFn) {
         try {
@@ -236,7 +250,7 @@ export async function buildRouteElement(
             { 'timber.segment': segment.segmentName ?? 'unknown' },
             async () => {
               try {
-                await accessFn({ params: match.params, searchParams: {} });
+                await accessFn({ params: match.params });
                 await setSpanAttribute('timber.result', 'pass');
                 accessVerdicts.set(si, 'pass');
               } catch (error) {
@@ -302,10 +316,7 @@ export async function buildRouteElement(
     );
   };
 
-  let element = h(TracedPage, {
-    params: paramsPromise,
-    searchParams: {},
-  });
+  let element = h(TracedPage, {});
 
   // Build a lookup of layout components by segment for O(1) access.
   const layoutBySegment = new Map(
@@ -352,12 +363,7 @@ export async function buildRouteElement(
     //   same urlPath (e.g., /(marketing) and /(app) both have "/"),
     //   which would cause the wrong cached layout to be reused
     const skip =
-      shouldSkipSegment(
-        segment.urlPath,
-        layoutComponent,
-        isLeaf,
-        clientStateTree ?? null
-      ) &&
+      shouldSkipSegment(segment.urlPath, layoutComponent, isLeaf, clientStateTree ?? null) &&
       hasRenderedLayoutBelow &&
       segment.segmentType !== 'group';
 
@@ -385,13 +391,11 @@ export async function buildRouteElement(
     if (segment.access) {
       const accessMod = (await segment.access.load()) as Record<string, unknown>;
       const accessFn = accessMod.default as
-        | ((ctx: { params: Record<string, string | string[]>; searchParams: unknown }) => unknown)
+        | ((ctx: { params: Record<string, string | string[]> }) => unknown)
         | undefined;
       if (accessFn) {
         element = h(AccessGate, {
           accessFn,
-          params: match.params,
-          searchParams: {},
           segmentName: segment.segmentName,
           verdict: accessVerdicts.get(i),
           children: element,
@@ -408,7 +412,6 @@ export async function buildRouteElement(
         slotProps[slotName] = await resolveSlotElement(
           slotNode as ManifestSegmentNode,
           match,
-          paramsPromise,
           h,
           interception
         );
@@ -417,39 +420,28 @@ export async function buildRouteElement(
       const segmentPath = segment.urlPath.split('/');
       const parallelRouteKeys = Object.keys(segment.slots ?? {});
 
-      // Wrap the layout component in an OTEL span.
-      // For route groups, urlPath is "/" (groups don't add URL segments), so
-      // include the directory name to distinguish e.g. "layout /(pre-release)"
-      // from the root "layout /".
-      const segmentForSpan = segment;
-      const layoutComponentForSpan = layoutComponent;
-      const segmentLabel =
-        segmentForSpan.segmentType === 'group'
-          ? `${segmentForSpan.urlPath === '/' ? '' : segmentForSpan.urlPath}/${segmentForSpan.segmentName}`
-          : segmentForSpan.urlPath;
-      const TracedLayout = async (props: Record<string, unknown>) => {
-        return withSpan('timber.layout', { 'timber.segment': segmentLabel }, () =>
-          (layoutComponentForSpan as (props: Record<string, unknown>) => unknown)(props)
-        );
-      };
-
-      // segmentId uniquely identifies this segment for client-side element
-      // caching. For route groups, urlPath is shared with the parent (both "/"),
-      // so we include the group name to distinguish them. Without this, the
-      // segment merger's element cache would conflate root and group elements.
+      // For route groups, urlPath is shared with the parent (both "/"),
+      // so include the group name to distinguish them. Used for both OTEL
+      // span labels and client-side element caching (segmentId).
       const segmentId =
         segment.segmentType === 'group'
           ? `${segment.urlPath === '/' ? '' : segment.urlPath}/${segment.segmentName}`
           : segment.urlPath;
 
+      // Wrap the layout component in an OTEL span
+      const layoutComponentRef = layoutComponent;
+      const TracedLayout = async (props: Record<string, unknown>) => {
+        return withSpan('timber.layout', { 'timber.segment': segmentId }, () =>
+          (layoutComponentRef as (props: Record<string, unknown>) => unknown)(props)
+        );
+      };
+
       element = h(SegmentProvider, {
         segments: segmentPath,
         segmentId,
         parallelRouteKeys,
         children: h(TracedLayout, {
           ...slotProps,
-          params: paramsPromise,
-          searchParams: {},
           children: element,
         }),
       });

package/src/server/route-handler.ts

@@ -9,6 +9,7 @@
  */
 
 import type { RouteContext } from './types.js';
+import { logRouteError } from './logger.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -122,7 +123,7 @@ async function runHandler(handler: RouteHandler, ctx: RouteContext): Promise<Res
     const res = await handler(ctx);
     return mergeResponseHeaders(res, ctx.headers);
   } catch (error) {
-    console.error('[timber] Uncaught error in route.ts handler:', error);
+    logRouteError({ method: ctx.req.method, path: new URL(ctx.req.url).pathname, error });
     return new Response(null, { status: 500 });
   }
 }