@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/server/deny-renderer.ts

@@ -19,7 +19,10 @@ import { createElement, Fragment } from 'react';
 import { renderToReadableStream } from '../rsc-runtime/rsc.js';
 
 import { DenySignal } from './primitives.js';
-import { renderDenyEntry, type DenyPageEntry } from './deny-boundary.js';
+import { appVisibleSearch } from '../shared/rsc-cache-key.js';
+import { getSlotParamsForClient } from './request-context.js';
+import { withPublishedParams } from './publish-params.js';
+import { renderDenyEntry, type DenyEntryShape } from './deny-boundary.js';
 import { getCookiesForSsr } from './cookie-context.js';
 import { logRenderError } from './logger.js';
 import { loadModule } from './safe-load.js';
@@ -28,6 +31,8 @@ import { isDebug } from './debug.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
 import { headElementsToReact } from './metadata.js';
 import { resolveStatusFile } from './status-code-resolver.js';
+import { defaultStatusPageResponse } from './default-status-page.js';
+import { rscErrorEnvelope } from '../shared/rsc-error-envelope.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';
 import type { NavContext } from './ssr-bridge-types.js';
@@ -35,9 +40,7 @@ import { flightInitScript } from './flight-scripts.js';
 import type { ClientBootstrapConfig } from './html-injectors.js';
 import type { Metadata } from './types.js';
 import { teeWithErrorPropagation } from './stream-utils.js';
-
-/** RSC content type for client navigation payload requests. */
-const RSC_CONTENT_TYPE = 'text/x-component';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 
 /** Layout component entry for deny page wrapping. */
 export interface LayoutEntry {
@@ -79,8 +82,7 @@ function buildDenyElement(
   resolutionKind: 'exact' | 'category' | 'error',
   filePath: string
 ): React.ReactElement {
-  const entry: DenyPageEntry = {
-    status: deny.status,
+  const entry: DenyEntryShape = {
     component,
     kind: resolutionKind === 'error' ? 'error' : 'status',
     isMdx: isMdxFilePath(filePath),
@@ -88,12 +90,24 @@ function buildDenyElement(
   return renderDenyEntry(entry, deny.status, deny.data);
 }
 
+/**
+ * Supplies a replacement for the framework default page at the end of the
+ * chain. Returning `null` keeps the framework default.
+ *
+ * The dev server uses this to substitute its route-listing 404 page. It is a
+ * parameter rather than a check on the produced Response because "the app
+ * authored no status page" is a fact about the *chain*, and inspecting the
+ * result for it (e.g. an empty body) stops being true the moment the chain
+ * grows a real terminal — which is exactly what TIM-1258 did.
+ */
+export type DefaultPageRenderer = (status: number, responseHeaders: Headers) => Response | null;
+
 /**
  * Render a status-code error page for a DenySignal.
  *
  * Resolves the appropriate status-code file from the segment chain based
- * on format preference. Returns an HTML Response (component), JSON Response,
- * or bare fallback Response.
+ * on format preference. Returns an HTML Response (component), a JSON Response,
+ * or the framework default status page.
  */
 export async function renderDenyPage(
   deny: DenySignal,
@@ -104,23 +118,35 @@ export async function renderDenyPage(
   responseHeaders: Headers,
   clientBootstrap: ClientBootstrapConfig,
   createDebugChannelSink: DebugChannelFactory,
-  callSsr: CallSsrFn
+  callSsr: CallSsrFn,
+  defaultPage?: DefaultPageRenderer,
+  firstDeniedIndex = Infinity
 ): Promise<Response> {
+  // Clamp the resolution walk to the denied segment — a status file below
+  // the denial is invisible to the in-tree chain and must not be selected
+  // by the fallback. The denying segment itself IS included (matching
+  // buildDenyPageChain's start-at-i semantics), but its layout is not
+  // (the gate-outside-layout rule from TIM-1074). See TIM-1358.
+  const maxIndex = firstDeniedIndex < Infinity ? firstDeniedIndex : undefined;
+
   // API routes (route.ts) → JSON only, never render components
   if (isApiRoute(segments)) {
-    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders);
+    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders, maxIndex);
     if (jsonResponse) return jsonResponse;
     return bareJsonResponse(deny.status, responseHeaders);
   }
 
   // Page routes → component chain first, JSON fallback only if no component found.
-  const resolution = resolveStatusFile(deny.status, segments, 'component');
+  const resolution = resolveStatusFile(deny.status, segments, 'component', maxIndex);
 
-  // No component status file — try JSON chain before bare fallback
+  // No component status file — try JSON chain, then the framework default page.
   if (!resolution) {
-    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders);
+    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders, maxIndex);
     if (jsonResponse) return jsonResponse;
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+    return (
+      defaultPage?.(deny.status, responseHeaders) ??
+      defaultStatusPageResponse(deny.status, responseHeaders)
+    );
   }
 
   // Dev warning: JSON status file exists but is shadowed by the component chain.
@@ -137,10 +163,20 @@ export async function renderDenyPage(
     }
   }
 
-  // Load the status-code page component
-  const mod = await loadModule(resolution.file);
-  if (!mod.default) {
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+  // Load the status-code page component. A file that resolved but exports no
+  // default — or whose module fails to import or evaluate — is not a usable
+  // component match: continue down the documented chain (JSON, then framework
+  // default) rather than returning an empty body or letting the loader's
+  // rejection escape request handling. Mirrors buildDenyPageChain and the
+  // error-file resolver, which both swallow the load failure.
+  const mod = await loadModule(resolution.file).catch(() => null);
+  if (!mod?.default) {
+    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders, maxIndex);
+    if (jsonResponse) return jsonResponse;
+    return (
+      defaultPage?.(deny.status, responseHeaders) ??
+      defaultStatusPageResponse(deny.status, responseHeaders)
+    );
   }
 
   const ErrorPageComponent = mod.default as (...args: unknown[]) => unknown;
@@ -156,10 +192,12 @@ export async function renderDenyPage(
     resolution.file.filePath
   );
 
-  // Always wrap in layout shell.
-  // NOTE: Shell opt-out (export const shell = false) is a future feature
-  // pending a proper design doc. See design backlog.
-  const resolvedSegments = new Set(segments.slice(0, resolution.segmentIndex + 1));
+  // Wrap in layout shell, clamped so a denied segment's layout never
+  // executes — the gate-outside-layout rule from TIM-1074. The denied
+  // segment's layout was loaded into `layoutComponents` but must not
+  // appear in the fallback response. See TIM-1358.
+  const layoutCeiling = Math.min(resolution.segmentIndex, firstDeniedIndex - 1);
+  const resolvedSegments = new Set(segments.slice(0, layoutCeiling + 1));
   const layoutsToWrap = layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
   for (let i = layoutsToWrap.length - 1; i >= 0; i--) {
     const { component } = layoutsToWrap[i];
@@ -176,7 +214,7 @@ export async function renderDenyPage(
   }
 
   // Render the error page to a fresh RSC Flight stream.
-  const rscStream = renderToReadableStream(element, {
+  const rscStream = renderToReadableStream(withPublishedParams(element), {
     signal: req.signal,
     onError(error: unknown) {
       logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
@@ -186,10 +224,13 @@ export async function renderDenyPage(
 
   const [ssrStream, inlineStream] = teeWithErrorPropagation(rscStream);
 
+  const slotParams = getSlotParamsForClient();
+
   const navContext: NavContext = {
     pathname: new URL(req.url).pathname,
     segmentParams: match.segmentParams,
-    searchParams: Object.fromEntries(new URL(req.url).searchParams),
+    searchParams: Object.fromEntries(appVisibleSearch(new URL(req.url)).params),
+    slotParams,
     statusCode: deny.status,
     responseHeaders,
     headHtml: flightInitScript(),
@@ -199,7 +240,32 @@ export async function renderDenyPage(
     cookies: getCookiesForSsr(),
   };
 
-  return callSsr(ssrStream, navContext);
+  try {
+    // `await` inside the try on purpose — see the same note in
+    // rsc-entry/error-renderer.ts. A status page that crashes during SSR
+    // ends in the framework default page, not a blank body: the pipeline's
+    // own deny fallback catches this and can only produce an empty response,
+    // and a crashing 404.tsx is exactly when the reader has nothing else to
+    // go on (TIM-1258).
+    return await callSsr(ssrStream, navContext);
+  } catch (renderError) {
+    logRenderError({ method: req.method, path: new URL(req.url).pathname, error: renderError });
+    return defaultStatusPageResponse(deny.status, responseHeaders);
+  }
+}
+
+/**
+ * Terminal fallback for a client-navigation deny with no status-code file.
+ *
+ * The HTML path answers this case with the framework default page, but a
+ * client-navigation response cannot carry HTML — the Flight decoder would
+ * choke on it. Emit the hard-navigate envelope instead: the client abandons
+ * SPA navigation and the resulting document request renders that same default
+ * page. Before TIM-1258 this returned an empty Flight body, which the decoder
+ * hit as a malformed stream.
+ */
+function denyHardNavigateResponse(status: number, responseHeaders: Headers): Response {
+  return rscErrorEnvelope(status, responseHeaders);
 }
 
 /**
@@ -214,19 +280,19 @@ export async function renderDenyPageAsRsc(
   layoutComponents: LayoutEntry[],
   req: Request,
   responseHeaders: Headers,
-  createDebugChannelSink: DebugChannelFactory
+  createDebugChannelSink: DebugChannelFactory,
+  firstDeniedIndex = Infinity
 ): Promise<Response> {
-  const resolution = resolveStatusFile(deny.status, segments, 'component');
+  const maxIndex = firstDeniedIndex < Infinity ? firstDeniedIndex : undefined;
+  const resolution = resolveStatusFile(deny.status, segments, 'component', maxIndex);
 
   if (!resolution) {
-    responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+    return denyHardNavigateResponse(deny.status, responseHeaders);
   }
 
-  const mod = await loadModule(resolution.file);
-  if (!mod.default) {
-    responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+  const mod = await loadModule(resolution.file).catch(() => null);
+  if (!mod?.default) {
+    return denyHardNavigateResponse(deny.status, responseHeaders);
   }
 
   const ErrorPageComponent = mod.default as (...args: unknown[]) => unknown;
@@ -239,15 +305,16 @@ export async function renderDenyPageAsRsc(
     resolution.file.filePath
   );
 
-  // Always wrap in layout shell.
-  const resolvedSegments = new Set(segments.slice(0, resolution.segmentIndex + 1));
+  // Wrap in layout shell, clamped to exclude denied segment layouts. TIM-1358.
+  const layoutCeiling = Math.min(resolution.segmentIndex, firstDeniedIndex - 1);
+  const resolvedSegments = new Set(segments.slice(0, layoutCeiling + 1));
   const layoutsToWrap = layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
   for (let i = layoutsToWrap.length - 1; i >= 0; i--) {
     const { component } = layoutsToWrap[i];
     element = h(component, null, element);
   }
 
-  const rscStream = renderToReadableStream(element, {
+  const rscStream = renderToReadableStream(withPublishedParams(element), {
     signal: req.signal,
     onError(error: unknown) {
       console.error('[timber] Error page RSC render error:', error);
@@ -275,9 +342,10 @@ export async function renderDenyPageAsRsc(
 async function renderDenyPageJson(
   deny: DenySignal,
   segments: ManifestSegmentNode[],
-  responseHeaders: Headers
+  responseHeaders: Headers,
+  maxIndex?: number
 ): Promise<Response | null> {
-  const resolution = resolveStatusFile(deny.status, segments, 'json');
+  const resolution = resolveStatusFile(deny.status, segments, 'json', maxIndex);
 
   if (!resolution) {
     return null;
@@ -286,7 +354,11 @@ async function renderDenyPageJson(
   // JSON status files are loaded as modules that export the JSON content.
   // The manifest's load() imports the .json file, which Vite handles as a
   // default export of the parsed JSON object.
-  const mod = await loadModule(resolution.file);
+  // A .json status file that fails to load is not a usable match — return
+  // null so the caller continues to the framework default rather than
+  // rejecting out of the chain.
+  const mod = await loadModule(resolution.file).catch(() => null);
+  if (!mod) return null;
   const jsonContent = mod.default ?? mod;
 
   responseHeaders.set('content-type', 'application/json; charset=utf-8');

package/src/server/error-boundary-wrapper.ts

@@ -1,106 +1,193 @@
 /**
- * Error boundary wrapper — wraps a React element in error boundaries from a route segment.
+ * Error boundary wrapper — wraps a React element in the error boundaries
+ * declared by a route segment (`{status}.tsx`, `4xx.tsx`/`5xx.tsx`, `error.tsx`).
  *
- * Extracted to allow reuse by both rsc-entry.ts and route-element-builder.ts.
- * See design/10-error-handling.md.
+ * This is the single implementation of that walk. It is driven by both
+ * construction sites:
+ *
+ *   - `route-element-builder.ts` / `slot-resolver.ts` — the request-time
+ *     renderer, walking the runtime manifest (`SegmentNode<ManifestFile>`).
+ *   - `tree-builder.ts` — the build-time tree walker
+ *     (`SegmentNode<RouteFile>`), with its loader and `createElement` injected.
+ *
+ * `errorBoundaryComponent` is injected rather than imported: `TimberErrorBoundary`
+ * is a `'use client'` module, and importing it here would pull client code into
+ * every consumer — including `tree-builder.ts`, which the server barrel reaches.
+ * `tests/use-client-pipeline.test.ts` walks the import graph to enforce this.
+ *
+ * See design/10-error-handling.md §"Status-Code File Variants".
  */
 
-import { TimberErrorBoundary } from '../client/error-boundary.js';
-import type { ManifestSegmentNode } from './route-matcher.js';
-import { loadModule } from './safe-load.js';
+import type { ReactNode } from 'react';
+import type { SegmentNode } from '../routing/types.js';
+import { isValidElementType, type LoadedComponent } from './utils/element-type.js';
 import { isMdxFilePath } from './utils/mdx-file.js';
 
+/** The minimum a route file must carry for the walk: a path to classify as MDX. */
+interface BoundaryFile {
+  filePath: string;
+}
+
 /**
- * Wrap an element in error boundaries defined by a route segment.
+ * Framework-injected error boundary wrapper.
+ * Wraps content with status-code error boundary handling.
  *
- * Processing order (innermost to outermost):
- * 1. Specific status files (e.g., 404.tsx, 500.tsx) — highest priority at runtime
- * 2. Category catch-alls (4xx.tsx, 5xx.tsx)
- * 3. error.tsx — catches anything not matched by status files
+ * Field types must agree with `TimberErrorBoundaryProps` in
+ * `client/error-boundary.tsx`. The two are kept structurally compatible by
+ * convention rather than by direct type import — this is the server-side
+ * construction site and may not import types from a 'use client' module.
+ */
+export interface ErrorBoundaryProps {
+  /** The component to render when an error is caught (TSX status files). */
+  fallbackComponent?: LoadedComponent;
+  /** Pre-rendered fallback element (MDX status files — see TIM-503). */
+  fallbackElement?: ReactNode;
+  /** Status code filter: 400 = any 4xx, 500 = any 5xx, specific number = exact match. */
+  status?: number;
+  /**
+   * Segment key of the segment that declared this boundary. An in-tree deny
+   * catch site that matched a file it may not render in place re-throws with
+   * that file's owning key on the signal; boundaries whose key differs
+   * decline, so the deny page lands at its owner rather than at the first
+   * boundary the throw happens to pass. Unset for slot boundaries and for
+   * construction sites with no deny chains — an unkeyed boundary declines
+   * every owner-addressed deny. See TIM-1356.
+   */
+  segmentKey?: string;
+  children: ReactNode;
+}
+
+/** How to load a route file's module. Only `default` is read. */
+type BoundaryModuleLoader<TFile> = (
+  file: TFile
+) => { default?: unknown } | Promise<{ default?: unknown }>;
+
+/** Everything the walk needs from its host environment. */
+export interface ErrorBoundaryWrapConfig<TFile, TElement> {
+  /** `React.createElement` or an equivalent element factory. */
+  createElement: (type: unknown, props: object) => TElement;
+  /** Loads a route file's module. Failures skip the boundary — see below. */
+  loadModule: BoundaryModuleLoader<TFile>;
+  /**
+   * The error boundary component to instantiate (`TimberErrorBoundary`, or a
+   * host-specific stand-in). Injected — see the module docstring.
+   */
+  errorBoundaryComponent: unknown;
+  /** When true, skip 4xx error boundaries — deny catching handles them in-tree. See TIM-666. */
+  skipDenyBoundaries?: boolean;
+  /** Segment key stamped on every boundary this walk creates. See `ErrorBoundaryProps`. */
+  segmentKey?: string;
+}
+
+/**
+ * Load a status/error file's component, or `null` if the boundary should be skipped.
+ *
+ * Two ways to get `null`, both deliberate:
+ *   - the module fails to load (syntax error in the error page) — building an
+ *     error boundary must not itself throw, so the boundary is skipped (TIM-584);
+ *   - the default export is not a valid React component type, which would
+ *     otherwise crash inside `createElement`.
+ */
+async function loadBoundaryComponent<TFile>(
+  file: TFile,
+  loadModule: BoundaryModuleLoader<TFile>
+): Promise<LoadedComponent | null> {
+  let mod: { default?: unknown };
+  try {
+    mod = await loadModule(file);
+  } catch {
+    return null;
+  }
+  return isValidElementType(mod?.default) ? mod.default : null;
+}
+
+/**
+ * Wrap `element` in one error boundary rendering `Component` on failure.
  *
  * MDX status files are server components and cannot be passed as function
- * props to TimberErrorBoundary (a 'use client' component). Instead, they
- * are pre-rendered as elements and passed as fallbackElement. See TIM-503.
+ * props to `TimberErrorBoundary` (a 'use client' component). They are
+ * pre-rendered as elements and passed as `fallbackElement` instead. See TIM-503.
+ *
+ * @param status      boundary status filter — omitted entirely for `error.tsx`
+ * @param fallbackProps props handed to an MDX fallback when it is pre-rendered
  */
-export async function wrapSegmentWithErrorBoundaries(
-  segment: ManifestSegmentNode,
-  element: React.ReactElement,
-  h: (...args: unknown[]) => React.ReactElement,
-  /** When true, skip 4xx error boundaries — deny catching handles them in-tree. See TIM-666. */
-  skipDenyBoundaries = false
-): Promise<React.ReactElement> {
-  // Specific status files (innermost — highest priority at runtime)
+function wrapInBoundary<TFile extends BoundaryFile, TElement extends ReactNode>(
+  element: TElement,
+  Component: LoadedComponent,
+  file: TFile,
+  status: number | undefined,
+  fallbackProps: object,
+  config: ErrorBoundaryWrapConfig<TFile, TElement>
+): TElement {
+  const props: ErrorBoundaryProps = isMdxFilePath(file.filePath)
+    ? { fallbackElement: config.createElement(Component, fallbackProps), children: element }
+    : { fallbackComponent: Component, children: element };
+  if (status !== undefined) props.status = status;
+  if (config.segmentKey !== undefined) props.segmentKey = config.segmentKey;
+  return config.createElement(config.errorBoundaryComponent, props);
+}
+
+/**
+ * Wrap an element in the error boundaries declared by a route segment.
+ *
+ * Wrapping is applied inside-out — the last wrap produces the outermost
+ * boundary — so the processing order below is innermost to outermost:
+ *
+ * 1. Specific status files (e.g. `404.tsx`, `503.tsx`) — highest priority at runtime
+ * 2. Category catch-alls (`4xx.tsx`, `5xx.tsx`)
+ * 3. `error.tsx` — catches anything not matched by a status file
+ *
+ * The order is load-bearing: it decides which boundary catches a given throw.
+ *
+ * See design/10-error-handling.md §"Format-Aware Fallback Chains".
+ */
+export async function wrapSegmentWithErrorBoundaries<
+  TFile extends BoundaryFile,
+  TElement extends ReactNode,
+>(
+  segment: SegmentNode<TFile>,
+  element: TElement,
+  config: ErrorBoundaryWrapConfig<TFile, TElement>
+): Promise<TElement> {
+  const { loadModule, skipDenyBoundaries = false } = config;
+
   if (segment.statusFiles) {
+    // Specific status files (innermost — highest priority at runtime)
     for (const [key, file] of Object.entries(segment.statusFiles)) {
-      if (key !== '4xx' && key !== '5xx') {
-        const status = parseInt(key, 10);
-        if (!isNaN(status)) {
-          // Skip 4xx boundaries when deny catching is active — the deny
-          // page is rendered by AccessGate/PageDenyBoundary instead.
-          if (skipDenyBoundaries && status >= 400 && status <= 499) continue;
-          // .catch: error boundary construction must not fail if the
-          // error page module has a syntax error — skip this boundary.
-          const mod = await loadModule(file).catch(() => null);
-          if (mod?.default) {
-            if (isMdxFilePath(file.filePath)) {
-              // MDX: pre-render as element (server component can't be a function prop)
-              element = h(TimberErrorBoundary, {
-                fallbackElement: h(mod.default as never, { status }),
-                status,
-                children: element,
-              });
-            } else {
-              element = h(TimberErrorBoundary, {
-                fallbackComponent: mod.default,
-                status,
-                children: element,
-              });
-            }
-          }
-        }
+      if (key === '4xx' || key === '5xx') continue;
+      const status = parseInt(key, 10);
+      if (isNaN(status)) continue;
+      // Skip 4xx boundaries when deny catching is active — the deny
+      // page is rendered by AccessGate/PageDenyBoundary instead.
+      if (skipDenyBoundaries && status >= 400 && status <= 499) continue;
+
+      const Component = await loadBoundaryComponent(file, loadModule);
+      if (Component) {
+        element = wrapInBoundary(element, Component, file, status, { status }, config);
       }
     }
 
     // Category catch-alls (4xx.tsx, 5xx.tsx)
     for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (key !== '4xx' && key !== '5xx') continue;
       if (skipDenyBoundaries && key === '4xx') continue;
-      if (key === '4xx' || key === '5xx') {
-        const mod = await loadModule(file).catch(() => null);
-        if (mod?.default) {
-          const categoryStatus = key === '4xx' ? 400 : 500;
-          if (isMdxFilePath(file.filePath)) {
-            element = h(TimberErrorBoundary, {
-              fallbackElement: h(mod.default as never, {}),
-              status: categoryStatus,
-              children: element,
-            });
-          } else {
-            element = h(TimberErrorBoundary, {
-              fallbackComponent: mod.default,
-              status: categoryStatus,
-              children: element,
-            });
-          }
-        }
+
+      const Component = await loadBoundaryComponent(file, loadModule);
+      if (Component) {
+        const categoryStatus = key === '4xx' ? 400 : 500;
+        element = wrapInBoundary(element, Component, file, categoryStatus, {}, config);
       }
     }
   }
 
-  // error.tsx (outermost — catches anything not matched by status files)
+  // error.tsx (outermost — catches anything not matched by status files).
+  // error.tsx/error.mdx receives { error, digest, reset } props from the
+  // boundary at catch time; MDX error files are pre-rendered without them
+  // (they're static content).
   if (segment.error) {
-    const mod = await loadModule(segment.error).catch(() => null);
-    if (mod?.default) {
-      if (isMdxFilePath(segment.error.filePath)) {
-        element = h(TimberErrorBoundary, {
-          fallbackElement: h(mod.default as never, {}),
-          children: element,
-        });
-      } else {
-        element = h(TimberErrorBoundary, {
-          fallbackComponent: mod.default,
-          children: element,
-        });
-      }
+    const Component = await loadBoundaryComponent(segment.error, loadModule);
+    if (Component) {
+      element = wrapInBoundary(element, Component, segment.error, undefined, {}, config);
     }
   }
 

package/src/server/head-response.ts

@@ -0,0 +1,54 @@
+/**
+ * HEAD body stripping — RFC 9110 §9.3.2.
+ *
+ * "The HEAD method is identical to GET except that the server MUST NOT send
+ * content in the response." The headers, however, must be the ones the
+ * corresponding GET would have produced — which is why timber renders the
+ * route in full and discards the body here rather than short-circuiting the
+ * render. Content-Type, Content-Length, Set-Cookie, cache directives and
+ * everything else ride through untouched.
+ *
+ * Node's `ServerResponse` happens to discard writes for HEAD, so the wire is
+ * usually correct even without this. That is a property of one adapter, not of
+ * the `Response` object: static generation, the Cloudflare and Nitro adapters,
+ * tests, and anything calling the pipeline handler as a function all observe
+ * the `Response` directly and saw the full body before TIM-1324.
+ *
+ * The pipeline applies this at its single exit so every response shape is
+ * covered — page render, API route, metadata route, deny page, error page,
+ * proxy short-circuit. The two unit-level producers that are also reachable as
+ * standalone functions (`handleRouteRequest`, `handleApiRoute`) call it too, so
+ * each honours HEAD on its own; they share this implementation rather than
+ * repeating it, and applying it twice is a no-op.
+ */
+
+/**
+ * Return a bodyless copy of `response` when `method` is HEAD.
+ *
+ * A no-op for every other method and for responses that already carry no body
+ * (204, 304, redirects), so callers do not need to pre-check either.
+ *
+ * The discarded stream is cancelled: an SSR render that reached this point has
+ * a live producer attached, and dropping the reference without cancelling
+ * leaks it for the lifetime of the render (design/13-security.md A4).
+ */
+export function stripHeadBody(response: Response, method: string): Response {
+  if (method.toUpperCase() !== 'HEAD') return response;
+  const body = response.body;
+  if (body === null) return response;
+
+  // `cancel()` rejects if the stream is already errored and throws
+  // synchronously if it is locked — neither is actionable here, the body is
+  // being discarded either way.
+  try {
+    body.cancel().catch(() => {});
+  } catch {
+    /* stream already locked or disturbed */
+  }
+
+  return new Response(null, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}

package/src/server/index.ts

@@ -10,7 +10,7 @@ export type { RouteContext } from './types';
 export type { Metadata, MetadataRoute, MetadataHandler, MetadataResult } from './types';
 
 // Request Context — ALS-backed accessors (all sync)
-// Prefer defineSearchParams().get() and defineSegmentParams().get() for typed access.
+// Prefer defineSearchParams().get() and getSegmentParams(SEGMENT_PATH) for typed access.
 // Design doc: design/04-authorization.md §"AccessContext does not include cookies or headers"
 export { getHeaders, getSegmentParams } from './request-context';
 export type { ReadonlyHeaders } from './request-context';
@@ -65,5 +65,3 @@ export { revalidatePath, revalidateTag } from './actions';
 export { getTraceId, getSpanId, withSpan, addSpanEvent } from './tracing';
 
 // Segment params types — re-exported for convenience.
-// defineSegmentParams itself lives at @timber-js/app/segment-params.
-export type { ParamsDefinition, InferParamField, ParamField } from '../segment-params/define.js';

package/src/server/internal.ts

@@ -66,12 +66,12 @@ export type {
   TreeBuilderConfig,
   TreeBuildResult,
   LoadedModule,
-  LoadedComponent,
   ModuleLoader,
   AccessGateProps,
   SlotAccessGateProps,
-  ErrorBoundaryProps,
 } from './tree-builder.js';
+export type { LoadedComponent } from './utils/element-type.js';
+export type { ErrorBoundaryProps } from './error-boundary-wrapper.js';
 
 // ── Access Gates ─────────────────────────────────────────────────────────
 export { AccessGate, SlotAccessGate } from './access-gate.js';