@timber-js/app 0.2.0-alpha.4 → 0.2.0-alpha.40

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 });
   }
 }

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

@@ -12,10 +12,12 @@ import { logRenderError } from '#/server/logger.js';
 import type { ManifestSegmentNode } from '#/server/route-matcher.js';
 import { DenySignal, RenderError } from '#/server/primitives.js';
 import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
+import { flightInitScript } from '#/server/flight-scripts.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';
 
 /**
@@ -124,10 +126,10 @@ export async function renderErrorPage(
     searchParams: Object.fromEntries(new URL(req.url).searchParams),
     statusCode: status,
     responseHeaders,
-    headHtml: '',
+    headHtml: flightInitScript(),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
     rscStream: inlineStream,
-    cookies: parseCookiesFromHeader(req.headers.get('cookie') ?? ''),
+    cookies: getCookiesForSsr(),
   };
 
   return callSsr(ssrStream, navContext);

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

@@ -20,9 +20,6 @@ export const RSC_CONTENT_TYPE = 'text/x-component';
  * stream that we drain and discard.
  *
  * See design/13-security.md §"Server component source leak"
- *
- * TODO: In the future, expose this debug data to the browser in dev mode
- * for inline error overlays (e.g. component stack traces).
  */
 export function createDebugChannelSink(): { readable: ReadableStream; writable: WritableStream } {
   const sink = new TransformStream();
@@ -34,6 +31,128 @@ export function createDebugChannelSink(): { readable: ReadableStream; writable:
   };
 }
 
+// ─── Debug Channel Collector (dev mode only) ────────────────────────────
+
+/**
+ * Parsed component debug info extracted from the Flight debug channel.
+ *
+ * Contains only component names, environment labels, and stack frames —
+ * never source code or props. See design/13-security.md §"Server source
+ * never reaches the client".
+ */
+export interface DebugComponentEntry {
+  name: string;
+  env: string | null;
+  key: string | null;
+  stack: unknown[] | null;
+}
+
+/**
+ * A debug channel that collects Flight debug rows instead of discarding them.
+ *
+ * Used in dev mode to capture server component tree information for the
+ * Vite error overlay. The collector provides the same `{ readable, writable }`
+ * shape as the discard sink, plus methods to retrieve collected data.
+ *
+ * Security: only component names, environments, and stack frames are
+ * extracted — props and source code are stripped. In production builds,
+ * use `createDebugChannelSink()` instead (this function is never called).
+ */
+export interface DebugChannelCollector {
+  readable: ReadableStream;
+  writable: WritableStream;
+  /** Get the raw collected text from the debug channel. */
+  getCollectedText(): string;
+  /** Get parsed component entries (names, stacks — no props or source). */
+  getComponents(): DebugComponentEntry[];
+}
+
+export function createDebugChannelCollector(): DebugChannelCollector {
+  const chunks: string[] = [];
+  const decoder = new TextDecoder();
+
+  const sink = new TransformStream();
+
+  // Collect chunks from the readable side instead of discarding them.
+  sink.readable
+    .pipeTo(
+      new WritableStream({
+        write(chunk: Uint8Array) {
+          chunks.push(decoder.decode(chunk, { stream: true }));
+        },
+        close() {
+          // Flush any remaining bytes in the decoder
+          const remaining = decoder.decode();
+          if (remaining) chunks.push(remaining);
+        },
+      })
+    )
+    .catch(() => {
+      // Stream abort — request cancelled. Not an error.
+    });
+
+  return {
+    readable: new ReadableStream(), // no commands to send to Flight
+    writable: sink.writable,
+    getCollectedText() {
+      return chunks.join('');
+    },
+    getComponents() {
+      return parseDebugRows(chunks.join(''));
+    },
+  };
+}
+
+/**
+ * Parse React Flight debug rows into component entries.
+ *
+ * The Flight debug channel writes rows in `hexId:json\n` format. Each row
+ * with a JSON object containing a `name` field is a component debug info
+ * entry. Rows without `name` (timing rows, reference rows like `D"$id"`)
+ * are skipped.
+ *
+ * Security: `props` are explicitly stripped from parsed entries — they may
+ * contain rendered output or user data. Only `name`, `env`, `key`, and
+ * `stack` are retained.
+ */
+export function parseDebugRows(text: string): DebugComponentEntry[] {
+  if (!text) return [];
+
+  const entries: DebugComponentEntry[] = [];
+  const lines = text.split('\n');
+
+  for (const line of lines) {
+    if (!line) continue;
+
+    // Flight row format: hexId:payload
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+
+    const payload = line.slice(colonIdx + 1);
+    // Skip non-JSON payloads (e.g., D"$a" reference rows)
+    if (!payload.startsWith('{')) continue;
+
+    try {
+      const parsed = JSON.parse(payload);
+      if (typeof parsed !== 'object' || parsed === null) continue;
+      if (typeof parsed.name !== 'string') continue;
+
+      // Strip props — may contain source-derived data or user data.
+      // Only retain: name, env, key, stack.
+      entries.push({
+        name: parsed.name,
+        env: parsed.env ?? null,
+        key: parsed.key ?? null,
+        stack: Array.isArray(parsed.stack) ? parsed.stack : null,
+      });
+    } catch {
+      // Malformed JSON — skip this row
+    }
+  }
+
+  return entries;
+}
+
 /**
  * Build segment metadata for the X-Timber-Segments response header.
  * Describes the rendered segment chain with async status, enabling