@timber-js/app 0.2.0-alpha.34 → 0.2.0-alpha.35

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,62 @@ 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({ params }) { ... }`
+    );
+  }
+}
+
+/**
+ * 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.
+ */
+async function extractMetadata(
+  mod: Record<string, unknown>,
+  segment: ManifestSegmentNode,
+  paramsPromise: Promise<Record<string, string | string[]>>
+): Promise<Metadata | null> {
+  if (typeof mod.metadata === 'function') {
+    type MetadataFn = (props: Record<string, unknown>) => Promise<Metadata>;
+    return (
+      (await withSpan(
+        'timber.metadata',
+        { 'timber.segment': segment.segmentName ?? segment.urlPath },
+        () => (mod.metadata as MetadataFn)({ params: paramsPromise })
+      )) ?? 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 ──────────────────────────────────────────────────────────────
 
 /**
@@ -126,87 +194,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, paramsPromise);
+      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, paramsPromise);
+      if (pageMetadata) {
+        metadataEntries.push({ metadata: pageMetadata, isPage: true });
       }
+      deferSuspenseFor = extractDeferSuspenseFor(mod, deferSuspenseFor);
     }
   }
 
@@ -227,7 +242,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 +251,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) {
@@ -304,7 +319,6 @@ export async function buildRouteElement(
 
   let element = h(TracedPage, {
     params: paramsPromise,
-    searchParams: {},
   });
 
   // Build a lookup of layout components by segment for O(1) access.
@@ -380,13 +394,12 @@ 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,
@@ -412,31 +425,22 @@ 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,
@@ -444,7 +448,6 @@ export async function buildRouteElement(
         children: h(TracedLayout, {
           ...slotProps,
           params: paramsPromise,
-          searchParams: {},
           children: element,
         }),
       });

package/src/server/route-matcher.ts

@@ -50,14 +50,14 @@ export interface ManifestSegmentNode {
   middleware?: ManifestFile;
   access?: ManifestFile;
   route?: ManifestFile;
+  /** params.ts — isomorphic convention file for segmentParams + searchParams definitions. */
+  params?: ManifestFile;
   error?: ManifestFile;
   default?: ManifestFile;
   denied?: ManifestFile;
-  searchParams?: ManifestFile;
   statusFiles?: Record<string, ManifestFile>;
   jsonStatusFiles?: Record<string, ManifestFile>;
   legacyStatusFiles?: Record<string, ManifestFile>;
-  prerender?: ManifestFile;
   /** Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.) keyed by base name */
   metadataRoutes?: Record<string, ManifestFile>;
 

package/src/server/rsc-entry/error-renderer.ts

@@ -15,7 +15,8 @@ import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
 import { renderDenyPage } from '#/server/deny-renderer.js';
 import type { LayoutEntry } from '#/server/deny-renderer.js';
 import type { NavContext } from '#/server/ssr-entry.js';
-import { createDebugChannelSink, parseCookiesFromHeader } from './helpers.js';
+import { createDebugChannelSink } from './helpers.js';
+import { getCookiesForSsr } from '#/server/request-context.js';
 import { callSsr } from './ssr-bridge.js';
 
 /**
@@ -127,7 +128,7 @@ export async function renderErrorPage(
     headHtml: '',
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
     rscStream: inlineStream,
-    cookies: parseCookiesFromHeader(req.headers.get('cookie') ?? ''),
+    cookies: getCookiesForSsr(),
   };
 
   return callSsr(ssrStream, navContext);

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

@@ -47,7 +47,11 @@ import { buildClientScripts } from '#/server/html-injectors.js';
 import type { InterceptionContext, PipelineConfig, RouteMatch } from '#/server/pipeline.js';
 import { createPipeline } from '#/server/pipeline.js';
 import { DenySignal, RedirectSignal } from '#/server/primitives.js';
-import { buildRouteElement, RouteSignalWithContext } from '#/server/route-element-builder.js';
+import {
+  buildRouteElement,
+  RouteSignalWithContext,
+  ParamCoercionError,
+} from '#/server/route-element-builder.js';
 import type { ManifestSegmentNode } from '#/server/route-matcher.js';
 import { createMetadataRouteMatcher, createRouteMatcher } from '#/server/route-matcher.js';
 import { initDevTracing } from '#/server/tracing.js';
@@ -112,13 +116,15 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
   // See design/17-logging.md §"register() — Server Startup"
   await loadInstrumentation(loadUserInstrumentation);
 
-  // Initialize cookie signing secrets from config (design/29-cookies.md §"Signed Cookies")
-  const cookieSecrets = (runtimeConfig as Record<string, unknown>).cookieSecrets as
-    | string[]
+  // Initialize deployment ID for version skew detection (TIM-446).
+  // The manifest init module sets globalThis.__TIMBER_DEPLOYMENT_ID__ at startup.
+  // In dev mode this is undefined — skew checks are skipped.
+  const deploymentId = (globalThis as Record<string, unknown>).__TIMBER_DEPLOYMENT_ID__ as
+    | string
     | undefined;
-  if (cookieSecrets?.length) {
-    const { setCookieSecrets } = await import('#/server/request-context.js');
-    setCookieSecrets(cookieSecrets);
+  if (deploymentId) {
+    const { setDeploymentId } = await import('#/server/version-skew.js');
+    setDeploymentId(deploymentId);
   }
 
   const matchRoute = createRouteMatcher(manifest);
@@ -211,7 +217,8 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
         responseHeaders,
         clientBootstrap,
         clientJsDisabled,
-        interception
+        interception,
+        manifest.root
       );
     },
     renderNoMatch: async (req: Request, responseHeaders: Headers) => {
@@ -304,7 +311,8 @@ async function renderRoute(
   responseHeaders: Headers,
   clientBootstrap: ClientBootstrapConfig,
   clientJsDisabled: boolean,
-  interception?: InterceptionContext
+  interception?: InterceptionContext,
+  rootSegment?: ManifestSegmentNode
 ): Promise<Response> {
   const segments = match.segments as unknown as ManifestSegmentNode[];
   const leaf = segments[segments.length - 1];
@@ -359,9 +367,16 @@ async function renderRoute(
         return buildRedirectResponse(_req, signal, responseHeaders);
       }
     }
-    // No PageComponent found
+    // Param coercion failed — render the custom 404 page (status files / not-found).
+    // Previously returned a bare Response(null, { status: 404 }) which bypassed
+    // custom not-found pages. Now routes through renderNoMatchPage so apps with
+    // 404.tsx / not-found status files render their custom page.
+    if (error instanceof ParamCoercionError) {
+      return renderNoMatchPage(_req, rootSegment!, responseHeaders, clientBootstrap);
+    }
+    // No PageComponent found — same treatment as param coercion: render custom 404.
     if (error instanceof Error && error.message.startsWith('No page component')) {
-      return new Response(null, { status: 404 });
+      return renderNoMatchPage(_req, rootSegment!, responseHeaders, clientBootstrap);
     }
     throw error;
   }

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

@@ -155,8 +155,8 @@ export async function buildRscPayloadResponse(
     responseHeaders.set('X-Timber-Skipped-Segments', JSON.stringify(skippedSegments));
   }
 
-  // Send route params so the client can populate useParams() after
-  // SPA navigation. Without this, useParams() returns {}.
+  // Send route params so the client can populate useSegmentParams() after
+  // SPA navigation. Without this, useSegmentParams() returns {}.
   if (Object.keys(match.params).length > 0) {
     responseHeaders.set('X-Timber-Params', JSON.stringify(match.params));
   }

package/src/server/rsc-entry/ssr-renderer.ts

@@ -26,8 +26,8 @@ import {
   buildSegmentInfo,
   createDebugChannelSink,
   isAbortError,
-  parseCookiesFromHeader,
 } from './helpers.js';
+import { getCookiesForSsr } from '#/server/request-context.js';
 import { renderErrorPage } from './error-renderer.js';
 import { callSsr } from './ssr-bridge.js';
 import type { RenderSignals } from './rsc-stream.js';
@@ -92,8 +92,8 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
     ? ''
     : `<script>self.__timber_segments=${JSON.stringify(buildSegmentInfo(segments, layoutComponents))}</script>`;
 
-  // Embed route params in HTML so useParams() works on initial hydration.
-  // Without this, useParams() returns {} until the first client navigation.
+  // Embed route params in HTML so useSegmentParams() works on initial hydration.
+  // Without this, useSegmentParams() returns {} until the first client navigation.
   const paramsScript =
     clientJsDisabled || Object.keys(match.params).length === 0
       ? ''
@@ -111,7 +111,7 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
     rscStream: clientJsDisabled ? undefined : inlineStream,
     deferSuspenseFor: deferSuspenseFor > 0 ? deferSuspenseFor : undefined,
     signal: req.signal,
-    cookies: parseCookiesFromHeader(req.headers.get('cookie') ?? ''),
+    cookies: getCookiesForSsr(),
   };
 
   // Helper: check if render-phase signals were captured and return the