@timber-js/app 0.2.0-alpha.186 → 0.2.0-alpha.188

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/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';

package/src/server/metadata-collector.ts

@@ -0,0 +1,115 @@
+/**
+ * Render-time metadata resolution components.
+ *
+ * MetadataCollector runs below AccessGate for each segment, collecting
+ * metadata entries into a request-scoped array. MetadataHead runs at
+ * the page level, merging all collected entries and rendering Float-
+ * hoisted head elements.
+ *
+ * This structural approach replaces the eager pre-render metadata
+ * resolution: a denied segment's AccessGate prevents MetadataCollector
+ * from rendering, so metadata() never executes for denied segments.
+ * No `firstDeniedIndex` bookkeeping needed.
+ *
+ * See TIM-1363, design/16-metadata.md.
+ */
+
+import { createElement, Fragment } from 'react';
+import type { ReactNode } from 'react';
+
+import { requestContextAls } from './als-registry.js';
+import type { Metadata } from './types.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+import { withSpan } from './tracing.js';
+import { resolveMetadata, renderMetadataToElements, headElementsToReact } from './metadata.js';
+import type { SegmentMetadataEntry } from './metadata.js';
+import { collectMetadataRouteHeadElements } from './metadata-routes.js';
+
+// ─── Request-scoped metadata entry store ────────────────────────────────
+
+function getMetadataEntries(): SegmentMetadataEntry[] {
+  const store = requestContextAls.getStore();
+  if (!store) return [];
+  store._metadataEntries ??= [];
+  return store._metadataEntries;
+}
+
+// ─── MetadataCollector ──────────────────────────────────────────────────
+
+export interface MetadataCollectorProps {
+  metadataExport: Metadata | (() => Promise<Metadata>);
+  segmentName: string;
+  isPage: boolean;
+  onSettled?: () => void;
+  children: ReactNode;
+}
+
+/**
+ * Async server component that collects one segment's metadata during
+ * render. Placed between AccessGate and the layout/page. When
+ * AccessGate denies, this component never renders, so dynamic
+ * metadata() never executes for denied segments (TIM-1027).
+ *
+ * Static metadata objects are pushed synchronously (no side effects).
+ * Dynamic metadata functions are awaited with OTEL tracing.
+ */
+export async function MetadataCollector(props: MetadataCollectorProps): Promise<ReactNode> {
+  const { metadataExport, segmentName, isPage, onSettled, children } = props;
+
+  try {
+    let metadata: Metadata | null = null;
+    if (typeof metadataExport === 'function') {
+      metadata =
+        (await withSpan('timber.metadata', { 'timber.segment': segmentName }, () =>
+          (metadataExport as () => Promise<Metadata>)()
+        )) ?? null;
+    } else {
+      metadata = metadataExport;
+    }
+
+    if (metadata) {
+      getMetadataEntries().push({ metadata, isPage });
+    }
+
+    return children;
+  } finally {
+    onSettled?.();
+  }
+}
+
+// ─── MetadataHead ───────────────────────────────────────────────────────
+
+export interface MetadataHeadProps {
+  segments: ManifestSegmentNode[];
+  requestUrl: string;
+  metadataRouteHashes?: Record<string, string>;
+  children: ReactNode;
+}
+
+/**
+ * Server component at the page level. Reads all metadata entries
+ * collected by MetadataCollector components above it, merges them,
+ * auto-links metadata routes, and renders Float-hoisted head elements.
+ *
+ * Placed as a sibling of the page element inside a Fragment so the
+ * Float elements are always at the page segment level (re-rendered
+ * on every SPA navigation, never skipped by segment tree diffing).
+ */
+export function MetadataHead(props: MetadataHeadProps): ReactNode {
+  const { segments, requestUrl, metadataRouteHashes, children } = props;
+  const entries = getMetadataEntries();
+  const resolved = resolveMetadata(entries);
+  const headElements = renderMetadataToElements(resolved);
+
+  const autoLinked = collectMetadataRouteHeadElements(
+    segments,
+    Infinity,
+    resolved,
+    new URL(requestUrl),
+    metadataRouteHashes
+  );
+  headElements.push(...autoLinked);
+
+  const metadataElement = headElementsToReact(headElements);
+  return createElement(Fragment, null, metadataElement, children);
+}

package/src/server/param-coercion.ts

@@ -1,6 +1,6 @@
 /**
- * Segment param coercion — runs the matched route's `params.ts` codecs
- * over the raw matcher output before middleware and rendering.
+ * Segment param coercion — runs the app/schema.ts codecs over the raw
+ * matcher output before middleware and rendering.
  *
  * Lifted out of `pipeline-phases.ts` (TIM-853) so the coercer can be
  * imported directly by other entry points (the action-dispatch wrapper,
@@ -18,7 +18,6 @@ import { effectiveUrlSegment } from '../routing/segment-classify.js';
 import { toBracketKey } from '../params/resolve-schema.js';
 import type { RouteMatch } from './pipeline.js';
 import { normalizeParamValue } from '../shared/param-value.js';
-import { loadModule } from './safe-load.js';
 import { ParamCoercionError } from './route-element-builder.js';
 import { isDebug } from './debug.js';
 
@@ -112,16 +111,24 @@ export function coerceSlotParams(
 /**
  * Run segment param coercion on the matched route's segments.
  *
- * When `globalCodecs` is provided (from app/schema.ts), uses the global
- * codec map keyed by bare param name. Otherwise falls back to loading
- * per-segment params.ts modules.
+ * Codecs come from `app/schema.ts` and nowhere else (TIM-1342 completed
+ * design/41-global-params.md migration step 9). A route with no schema, or
+ * a param the schema does not declare, keeps its raw string — which is the
+ * honest type for an uninterpreted URL segment.
  *
  * Throws ParamCoercionError if any codec fails (→ 404).
  *
  * This runs BEFORE middleware, so ctx.segmentParams is already typed.
  * See design/07-routing.md §"Where Coercion Runs"
  * See design/41-global-params.md §"Pipeline Integration"
+ *
+ * Stays `async` with nothing to await: it is injected as a
+ * `CoerceSegmentParamsFn` into the revalidation renderer and the action
+ * middleware runner, both of which await it. Narrowing the return type to
+ * `void` would break those contracts and remove a microtask boundary the
+ * pipeline's ordering has always had, for no gain.
  */
+// eslint-disable-next-line @typescript-eslint/require-await -- see above
 export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
   const globalCodecs = _globalCodecs;
   // Unconditionally install a null-prototype target so the invariant
@@ -178,60 +185,5 @@ export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
       // inside would report the second as the first.
       mergeTarget[key] = normalizeParamValue(parsed, key);
     }
-    return;
-  }
-
-  // Legacy path: per-segment params.ts coercion
-  for (const segment of match.segments) {
-    // Only process segments that have a params.ts convention file
-    if (!segment.params) continue;
-
-    let mod: Record<string, unknown>;
-    try {
-      mod = await loadModule(segment.params);
-    } catch (err) {
-      const message = `Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`;
-      if (isDebug()) {
-        console.warn(
-          `[timber] Param coercion error: ${message}\n` +
-            `  Segment: ${segment.segmentName}\n` +
-            `  Params file: ${segment.params}`
-        );
-      }
-      throw new ParamCoercionError(message);
-    }
-
-    const segmentParamsDef = mod.segmentParams as
-      | { parse(raw: Record<string, string | string[]>): Record<string, unknown> }
-      | undefined;
-
-    if (!segmentParamsDef || typeof segmentParamsDef.parse !== 'function') continue;
-
-    let coerced: Record<string, unknown>;
-    try {
-      coerced = segmentParamsDef.parse(match.segmentParams) as Record<string, unknown>;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      if (isDebug()) {
-        const rawKeys = Object.keys(match.segmentParams).join(', ');
-        console.warn(
-          `[timber] Param codec rejected values for segment "${segment.segmentName}"\n` +
-            `  Error: ${message}\n` +
-            `  Available raw params: { ${rawKeys} }\n` +
-            `  Params file: ${segment.params}\n` +
-            `  Hint: this usually means a codec threw for the raw URL value.\n` +
-            `  Check that the regex/schema accepts the actual path segment string.`
-        );
-      }
-      throw new ParamCoercionError(message);
-    }
-
-    // Normalize outside the catch, for the same reason as above. `__proto__`
-    // is skipped here as well as inside `normalizeParamValue`, because this
-    // loop assigns into `mergeTarget` directly.
-    for (const key of Object.keys(coerced)) {
-      if (key === '__proto__') continue;
-      mergeTarget[key] = normalizeParamValue(coerced[key], key);
-    }
   }
 }

package/src/server/pipeline-helpers.ts

@@ -15,6 +15,7 @@ import { callOnRequestError } from './instrumentation.js';
 import { getTraceId } from './tracing.js';
 import { RedirectSignal } from './primitives.js';
 import type { ProxyConfig } from './pipeline.js';
+import { isRscRequest } from '../shared/rsc-media-type.js';
 
 // ─── Prototype-Pollution-Safe Sanitizer ────────────────────────────────────
 
@@ -125,8 +126,7 @@ export function buildRedirectResponse(
   req: Request,
   headers: Headers
 ): Response {
-  const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-  if (isRsc) {
+  if (isRscRequest(req)) {
     headers.set('X-Timber-Redirect', signal.location);
     return new Response(null, { status: 204, headers });
   }

package/src/server/pipeline-outcome.ts

@@ -27,6 +27,7 @@ import { markResponseFlushed } from './request-context.js';
 import { RedirectSignal, DenySignal } from './primitives.js';
 import { isDebug } from './debug.js';
 import { rscErrorEnvelope } from '../shared/rsc-error-envelope.js';
+import { isRscRequest } from '../shared/rsc-media-type.js';
 import type { PipelineConfig, RouteMatch } from './pipeline.js';
 
 // ─── Helpers ───────────────────────────────────────────────────────────────
@@ -141,7 +142,7 @@ export async function outcomeToResponse(
       // Signal the error via X-Timber-Error so the client hard-navigates
       // to the server-rendered error page instead of feeding HTML to the
       // Flight decoder (which crashes with "enqueueModel is not a function").
-      const isRsc = (ctx.req.headers.get('Accept') ?? '').includes('text/x-component');
+      const isRsc = isRscRequest(ctx.req);
 
       if (outcome.phase === 'proxy') {
         logProxyError({ error: outcome.error });

package/src/server/pipeline-phases.ts

@@ -39,6 +39,7 @@ import type { InterceptionContext, PipelineConfig, RouteMatch } from './pipeline
 import type { MetadataHandler, MetadataRoute, MiddlewareContext } from './types.js';
 import { swallow } from './logger.js';
 import { isDebug } from './debug.js';
+import { isRscRequest } from '../shared/rsc-media-type.js';
 
 interface RenderContext {
   canonicalPathname: string;
@@ -367,8 +368,8 @@ export async function handleRequest(
   // deployment ID matches the current build. On mismatch, signal the
   // client to do a full page reload instead of returning an RSC payload
   // that references mismatched module IDs.
-  const isRscRequest = (req.headers.get('Accept') ?? '').includes('text/x-component');
-  if (isRscRequest) {
+  const isRsc = isRscRequest(req);
+  if (isRsc) {
     const skewCheck = checkVersionSkew(req);
     if (!skewCheck.ok) {
       const reloadHeaders = new Headers();
@@ -386,7 +387,7 @@ export async function handleRequest(
   // to prevent spoofing from plain HTML navigations or raw HTTP clients.
   // The header value must be a valid relative pathname — reject schemes,
   // authority, and control characters. Canonicalize before matching.
-  if (isRscRequest && config.interceptionRewrites?.length) {
+  if (isRsc && config.interceptionRewrites?.length) {
     const rawSourceUrl = req.headers.get('X-Timber-URL');
     const validatedSourceUrl = rawSourceUrl
       ? validateInterceptionHeader(rawSourceUrl, stripTrailingSlash)
@@ -511,7 +512,7 @@ export async function handleRequest(
     | { route?: unknown; page?: unknown }
     | undefined;
   const isApiRoute = leafSegment?.route && !leafSegment?.page;
-  if (config.earlyHints && !isRscRequest && !isApiRoute) {
+  if (config.earlyHints && !isRsc && !isApiRoute) {
     try {
       await config.earlyHints(match, req, responseHeaders);
     } catch (err) {
@@ -520,8 +521,8 @@ export async function handleRequest(
   }
 
   // Stage 2c: Param coercion (before middleware)
-  // Load params.ts modules from matched segments and coerce raw string
-  // params through defineSegmentParams codecs. Coercion failure → 404
+  // Coerce raw string params through the app/schema.ts codecs.
+  // Coercion failure → 404
   // (middleware never runs). See design/07-routing.md §"Where Coercion Runs"
   //
   // Snapshot raw params before coercion — slot resolution needs the
@@ -540,9 +541,8 @@ export async function handleRequest(
           `[timber] Param coercion failed for ${method} ${canonicalPathname} — responding with 404\n` +
             `  Matched segments: ${segmentChain}\n` +
             `  Error: ${error.message}\n` +
-            `  This usually means a params.ts codec rejected the URL params.\n` +
-            `  Check that all fields in defineSegmentParams() are optional for params\n` +
-            `  that don't appear at every route depth (e.g. year, month, day).`
+            `  This usually means a codec in app/schema.ts rejected the URL value.\n` +
+            `  Check the codec for the bracket key of the segment named above.`
         );
       }
       // For API routes (route.ts), return a bare 404 — not an HTML page.

package/src/server/primitives.ts

@@ -113,6 +113,31 @@ export class DenySignal extends Error {
   readonly status: number;
   readonly data: JsonSerializable | undefined;
 
+  /**
+   * Segment key of the segment that owns the deny page matched for this
+   * signal — set by a framework catch site that matched an entry it may not
+   * render at its own position, and re-threw so the boundary at the owning
+   * segment renders it instead.
+   *
+   * Written only by the three in-tree catch sites (`PageDenyBoundary`,
+   * `TracedLayout`, `AccessGate`), never by user code. Two readers depend on
+   * it: `TimberErrorBoundary`, which declines any deny whose `ownerKey` is
+   * not its own `segmentKey`, and `buildRscPayloadResponse`, which keeps
+   * streaming instead of re-rendering when it is set.
+   *
+   * See design/04-authorization.md §"Where a Deny Page Renders", TIM-1356.
+   */
+  ownerKey?: string;
+
+  /**
+   * When true, the pipeline must respond with `rscErrorEnvelope` so the
+   * client hard-navigates instead of attempting to render a deny page
+   * from the RSC payload. Set by AccessGate when a skipped segment
+   * denies — rendering the deny page in-tree would appear inside the
+   * client's cached layout chrome (TIM-1074). See TIM-1363.
+   */
+  _hardNavigate?: boolean;
+
   constructor(status: number, data?: JsonSerializable) {
     super(`Access denied with status ${status}`);
     this.name = 'DenySignal';