@timber-js/app 0.2.0-alpha.145 → 0.2.0-alpha.147

package/src/routing/codegen.ts

@@ -48,7 +48,7 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
   const hasSchema = options.hasSchema ?? detectSchema(options.appDir);
 
   const routes: RouteEntry[] = [];
-  collectRoutes(tree.root, [], [], '', routes, hasSchema);
+  collectRoutes(tree.root, [], [], '', routes, hasSchema, false);
 
   // Sort routes alphabetically for deterministic output
   routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -82,7 +82,8 @@ function collectRoutes(
   ancestorParamsFiles: string[],
   parentTreePath: string,
   routes: RouteEntry[],
-  hasSchema: boolean
+  hasSchema: boolean,
+  insideSlot: boolean
 ): void {
   // Build the tree path (includes groups, slots — uniquely identifies this segment).
   // Root node has empty segmentName, producing treePath = ''.
@@ -156,6 +157,7 @@ function collectRoutes(
       params: resolvedParams,
       hasSearchParams: false,
       isApiRoute,
+      isSlotRoute: insideSlot,
       hasSchema,
     };
 
@@ -175,15 +177,63 @@ function collectRoutes(
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutes(child, params, nextAncestorFiles, treePath, routes, hasSchema);
+    collectRoutes(child, params, nextAncestorFiles, treePath, routes, hasSchema, insideSlot);
   }
 
   // Recurse into slots (they share the parent's URL path, but may have their own pages)
   for (const slot of Object.values(node.slots)) {
-    collectRoutes(slot, params, nextAncestorFiles, treePath, routes, hasSchema);
+    collectRoutes(slot, params, nextAncestorFiles, treePath, routes, hasSchema, true);
   }
 }
 
+/**
+ * Dedupe route entries by urlPath for urlPath-keyed emissions (the Routes
+ * interface, useQueryStates overloads, and typed Link variants).
+ *
+ * Parallel-slot pages share their parent's urlPath; emitting one entry per
+ * slot page produced duplicate interface keys (TS2300/TS2717 under
+ * skipLibCheck:false) and duplicate overloads. The non-slot entry is the
+ * canonical one; when only slot entries exist (parent has no page), the
+ * lexicographically smallest segmentPath wins so output is independent of
+ * slot scan order. A slot's searchParams definition is carried onto the
+ * merged entry when the canonical entry has none — never silently dropped.
+ *
+ * segmentPath-keyed emissions (getSegmentParams, useSegmentParams,
+ * TimberSegmentParams) must NOT use this — segmentPaths are already unique
+ * and slot entries feed those APIs directly.
+ */
+function dedupeRoutesByUrlPath(routes: RouteEntry[]): RouteEntry[] {
+  const byPath = new Map<string, RouteEntry>();
+  for (const route of routes) {
+    const existing = byPath.get(route.urlPath);
+    if (!existing) {
+      byPath.set(route.urlPath, route);
+      continue;
+    }
+
+    let winner = existing;
+    let loser = route;
+    const routeWins =
+      (existing.isSlotRoute && !route.isSlotRoute) ||
+      (!!existing.isSlotRoute === !!route.isSlotRoute &&
+        route.segmentPath.localeCompare(existing.segmentPath) < 0);
+    if (routeWins) {
+      winner = route;
+      loser = existing;
+    }
+
+    if (!winner.hasSearchParams && loser.hasSearchParams) {
+      winner = {
+        ...winner,
+        hasSearchParams: true,
+        searchParamsPagePath: loser.searchParamsPagePath,
+      };
+    }
+    byPath.set(route.urlPath, winner);
+  }
+  return [...byPath.values()];
+}
+
 /**
  * Determine the TypeScript type for a segment's param.
  */
@@ -366,10 +416,14 @@ function formatDeclarationFile(
     lines.push('');
   }
 
+  // urlPath-keyed emissions use the deduped list (slot pages share their
+  // parent's urlPath); segmentPath-keyed emissions below keep all entries.
+  const uniqueByUrlPath = dedupeRoutesByUrlPath(routes);
+
   lines.push("declare module '@timber-js/app' {");
   lines.push('  interface Routes {');
 
-  for (const route of routes) {
+  for (const route of uniqueByUrlPath) {
     const paramsType = formatParamsType(route.params, importBase, hasSchema);
     const searchParamsType = formatSearchParamsType(route, importBase);
 
@@ -393,7 +447,10 @@ function formatDeclarationFile(
   lines.push('}');
   lines.push('');
 
-  const pageRoutes = routes.filter((r) => !r.isApiRoute);
+  // useQueryStates + typed Link are urlPath-keyed → deduped list.
+  const pageRoutes = uniqueByUrlPath.filter((r) => !r.isApiRoute);
+  // getSegmentParams / useSegmentParams are segmentPath-keyed → full list,
+  // so slot segments keep their own typed overloads.
   const dynamicRoutes = routes.filter((r) => r.params.length > 0);
 
   // Generate @timber-js/app/server augmentation — typed getSegmentParams

package/src/routing/scanner.ts

@@ -177,44 +177,26 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
 
     // Page-extension conventions (page, layout, error, default, denied)
     if (PAGE_EXT_CONVENTIONS.has(name) && extSet.has(ext)) {
-      const file: RouteFile = { filePath: fullPath, extension: ext };
-      switch (name) {
-        case 'page':
-          node.page = file;
-          break;
-        case 'layout':
-          node.layout = file;
-          break;
-        case 'error':
-          node.error = file;
-          break;
-        case 'default':
-          node.default = file;
-          break;
-        case 'denied':
-          node.denied = file;
-          break;
+      const key = name as 'page' | 'layout' | 'error' | 'default' | 'denied';
+      const existing = node[key];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
       }
+      node[key] = { filePath: fullPath, extension: ext };
       continue;
     }
 
-    // Fixed conventions (middleware, access, route) — always .ts or .tsx
-    if (FIXED_CONVENTIONS.has(name) && /\.?[jt]sx?$/.test(ext)) {
-      const file: RouteFile = { filePath: fullPath, extension: ext };
-      switch (name) {
-        case 'middleware':
-          node.middleware = file;
-          break;
-        case 'access':
-          node.access = file;
-          break;
-        case 'route':
-          node.route = file;
-          break;
-        case 'params':
-          node.params = file;
-          break;
+    // Fixed conventions (middleware, access, route, params) — only
+    // .ts/.tsx/.js/.jsx, never pageExtensions like .mdx. The regex is
+    // anchored: mts/cts/mjs/cjs (and stray tail matches like `.foots`)
+    // are NOT recognized. See design/07-routing.md §"Page Extensions".
+    if (FIXED_CONVENTIONS.has(name) && /^[jt]sx?$/.test(ext)) {
+      const key = name as 'middleware' | 'access' | 'route' | 'params';
+      const existing = node[key];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
       }
+      node[key] = { filePath: fullPath, extension: ext };
       continue;
     }
 
@@ -233,6 +215,10 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       if (!node.statusFiles) {
         node.statusFiles = {};
       }
+      const existing = node.statusFiles[name];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
+      }
       node.statusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
@@ -242,6 +228,10 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       if (!node.legacyStatusFiles) {
         node.legacyStatusFiles = {};
       }
+      const existing = node.legacyStatusFiles[name];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
+      }
       node.legacyStatusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
@@ -249,6 +239,8 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
     // Metadata route files (sitemap.ts, robots.ts, icon.tsx, opengraph-image.tsx, etc.)
     // Both static (.xml, .txt, .png, .ico, etc.) and dynamic (.ts, .tsx) files are recognized.
     // When both exist for the same base name, dynamic takes precedence.
+    // Two files of the SAME kind (static+static or dynamic+dynamic) are a
+    // build error — picking one by readdir order is platform-dependent.
     // See design/16-metadata.md §"Metadata Routes"
     const metaInfo = classifyMetadataRoute(entry);
     if (metaInfo) {
@@ -257,11 +249,13 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       }
       const existing = node.metadataRoutes[name];
       if (existing) {
-        // Dynamic > static precedence: only overwrite if the new file is dynamic
-        // or the existing file is static (dynamic always wins).
         const existingIsDynamic = isDynamicMetadataExtension(name, existing.extension);
         const newIsDynamic = isDynamicMetadataExtension(name, ext);
-        if (newIsDynamic || !existingIsDynamic) {
+        if (existingIsDynamic === newIsDynamic) {
+          throwDuplicateConvention(name, existing.filePath, fullPath);
+        }
+        // Dynamic > static precedence: overwrite only when the new file is dynamic.
+        if (newIsDynamic) {
           node.metadataRoutes[name] = { filePath: fullPath, extension: ext };
         }
       } else {
@@ -281,6 +275,26 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
   }
 }
 
+/**
+ * Throw a build error for two files claiming the same convention slot in
+ * one segment (e.g. page.tsx + page.jsx). Which file readdir returns first
+ * is platform-dependent (APFS sorts entries, ext4 does not) — silently
+ * picking one would let macOS dev and Linux CI serve different
+ * implementations of the same route.
+ */
+function throwDuplicateConvention(
+  convention: string,
+  firstPath: string,
+  secondPath: string
+): never {
+  throw new Error(
+    `Build error: duplicate '${convention}' files in the same route segment.\n` +
+      `  File 1: ${firstPath}\n` +
+      `  File 2: ${secondPath}\n` +
+      `Each segment may define '${convention}' at most once. Remove one of the files.`
+  );
+}
+
 /**
  * Recursively scan child directories and build the segment tree.
  */
@@ -359,57 +373,60 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
  * Two route groups like (auth)/login/page.tsx and (marketing)/login/page.tsx both claim
  * /login — the scanner must detect and reject this at build time.
  *
- * Parallel slots are excluded from collision detection — they intentionally coexist at
- * the same URL path as their parent (that's the whole point of parallel routes).
+ * Each parallel slot is validated as its OWN collision space: a slot's pages
+ * intentionally share URL paths with the parent tree (that's the point of
+ * parallel routes), but two route groups INSIDE one slot claiming the same
+ * URL — e.g. @side/(a)/x/page.tsx + @side/(b)/x/page.tsx — still collide.
  */
 function validateRouteGroupCollisions(root: SegmentNode): void {
   // Map from urlPath → { filePath, source } for the first page/route seen at that path
-  const seen = new Map<string, { filePath: string; segmentPath: string }>();
-  collectRoutableLeaves(root, seen, '', false);
+  collectRoutableLeaves(root, new Map(), '');
 }
 
 /**
  * Walk the segment tree and collect all routable leaves (page or route files),
- * throwing on collision. Slots are tracked in their own collision space since
- * they are parallel routes that intentionally share URL paths with their parent.
+ * throwing on collision. Each slot recurses with a FRESH collision map —
+ * slots are parallel routes that intentionally share URL paths with their
+ * parent tree, but collisions within a single slot are real errors.
  */
 function collectRoutableLeaves(
   node: SegmentNode,
   seen: Map<string, { filePath: string; segmentPath: string }>,
-  segmentPath: string,
-  insideSlot: boolean
+  segmentPath: string
 ): void {
+  // Intercepting routes are resolved by the slot resolver, not URL matching,
+  // and their computed urlPaths intentionally mirror other routes (e.g. two
+  // interceptors in one slot both produce /gallery/[id]). Skip them entirely.
+  if (node.segmentType === 'intercepting') return;
+
   const currentPath = segmentPath
     ? `${segmentPath}/${node.segmentName}`
     : node.segmentName || '(root)';
 
-  // Only check collisions for non-slot pages — slots intentionally share URL paths
-  if (!insideSlot) {
-    const routableFile = node.page ?? node.route;
-    if (routableFile) {
-      const existing = seen.get(node.urlPath);
-      if (existing) {
-        throw new Error(
-          `Build error: route collision — multiple route groups produce a page/route at the same URL path.\n` +
-            `  URL path: ${node.urlPath}\n` +
-            `  File 1:   ${existing.filePath} (via ${existing.segmentPath})\n` +
-            `  File 2:   ${routableFile.filePath} (via ${currentPath})\n` +
-            `Each URL path must map to exactly one page or route handler. ` +
-            `Rename or move one of the conflicting files.`
-        );
-      }
-      seen.set(node.urlPath, { filePath: routableFile.filePath, segmentPath: currentPath });
+  const routableFile = node.page ?? node.route;
+  if (routableFile) {
+    const existing = seen.get(node.urlPath);
+    if (existing) {
+      throw new Error(
+        `Build error: route collision — multiple route groups produce a page/route at the same URL path.\n` +
+          `  URL path: ${node.urlPath}\n` +
+          `  File 1:   ${existing.filePath} (via ${existing.segmentPath})\n` +
+          `  File 2:   ${routableFile.filePath} (via ${currentPath})\n` +
+          `Each URL path must map to exactly one page or route handler. ` +
+          `Rename or move one of the conflicting files.`
+      );
     }
+    seen.set(node.urlPath, { filePath: routableFile.filePath, segmentPath: currentPath });
   }
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutableLeaves(child, seen, currentPath, insideSlot);
+    collectRoutableLeaves(child, seen, currentPath);
   }
 
-  // Recurse into slots — each slot is its own parallel route space
+  // Recurse into slots — each slot gets a fresh map (its own collision space)
   for (const slotNode of Object.values(node.slots)) {
-    collectRoutableLeaves(slotNode, seen, currentPath, true);
+    collectRoutableLeaves(slotNode, new Map(), currentPath);
   }
 }
 

package/src/server/action-handler.ts

@@ -35,6 +35,7 @@ import {
 } from './sensitive-fields.js';
 import type { FormFlashData } from './form-flash.js';
 import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
+import { encodeHeadHeader, HEAD_HEADER } from '../shared/head-header.js';
 import { logActionError } from './logger.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
@@ -299,9 +300,16 @@ async function handleRscAction(
       _tree: result.revalidation.element,
     };
     headers['X-Timber-Revalidation'] = '1';
-    // Forward head elements as JSON so the client can update <head>.
+    // Forward head elements (percent-encoded JSON) so the client can update
+    // <head>. Raw JSON.stringify is NOT safe here: header values must be
+    // ByteStrings, so a title with an em dash or emoji would make
+    // `new Response(...)` throw — a 500 after the action's mutation already
+    // committed, dropping Set-Cookie too. See TIM-1058.
     if (result.revalidation.headElements.length > 0) {
-      headers['X-Timber-Head'] = JSON.stringify(result.revalidation.headElements);
+      const encodedHead = encodeHeadHeader(result.revalidation.headElements);
+      if (encodedHead !== null) {
+        headers[HEAD_HEADER] = encodedHead;
+      }
     }
   } else {
     payload = result.actionResult;

package/src/server/actions.ts

@@ -18,6 +18,7 @@ import { getCacheHandler } from '../cache/handler-store';
 import { DenySignal, RedirectSignal } from './primitives';
 import { withSpan } from './tracing';
 import { revalidationAls, type RevalidationState } from './als-registry.js';
+import type { HeadElementPayload } from '../shared/head-header.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -25,8 +26,8 @@ import { revalidationAls, type RevalidationState } from './als-registry.js';
 export interface RevalidationResult {
   /** React element tree (pre-serialization — passed to renderToReadableStream). */
   element: unknown;
-  /** Resolved head elements for metadata. */
-  headElements: unknown[];
+  /** Resolved head elements for metadata (forwarded via X-Timber-Head). */
+  headElements: HeadElementPayload[];
 }
 
 /** Renderer function that builds a React element tree for a given path. */

package/src/server/compress.ts

@@ -174,7 +174,7 @@ export function compressResponse(request: Request, response: Response): Response
 // progressively.
 
 import { createGzip, constants } from 'node:zlib';
-import { Readable } from 'node:stream';
+import { Readable, pipeline } from 'node:stream';
 
 /**
  * Compress a ReadableStream with gzip, flushing each chunk immediately.
@@ -186,7 +186,16 @@ import { Readable } from 'node:stream';
 function compressWithGzip(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
   const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
   const nodeInput = Readable.fromWeb(body as import('stream/web').ReadableStream);
-  nodeInput.pipe(gzip);
+
+  // pipeline() instead of bare pipe(): pipe() does not forward source errors,
+  // so an erroring body (streaming route handler, dropped upstream fetch)
+  // would emit an unhandled 'error' event and crash the process. pipeline()
+  // destroys gzip on source error — the returned web stream rejects — and
+  // tears down nodeInput when the consumer cancels the web stream, which
+  // cancels the source body via fromWeb. The error reaches the consumer
+  // through the web stream; the callback only marks it handled at the Node
+  // layer.
+  pipeline(nodeInput, gzip, () => {});
 
   return Readable.toWeb(gzip) as ReadableStream<Uint8Array>;
 }

package/src/server/cookie-context.ts

@@ -195,6 +195,11 @@ export function getCookieJar(): RequestCookies {
         maxAge: 0,
         expires: new Date(0),
       };
+      // delete() is a jar entry point like set() — caller-supplied
+      // path/domain are serialized verbatim into the Set-Cookie header,
+      // so they must pass the same attribute-injection guard. See
+      // design/29-cookies.md §"Cookie Attribute Validation" (TIM-1026).
+      assertValidCookieOptions(opts);
       store.cookieJar.set(name, { name, value: '', options: opts });
       // Remove from read view
       map.delete(name);
@@ -460,6 +465,12 @@ function setRaw(
   // the cookie jar / RYW map.
   assertValidCookieName(name);
   assertValidCookieValue(name, value);
+  // Options get the same entry-point guard as set()/delete(). For the
+  // setFromHeaders path this can only fire on attributes parseSetCookie
+  // cannot produce (it splits on `;` and normalizes Max-Age/SameSite),
+  // but setRaw is the jar entry point — the invariant lives here, not in
+  // the caller. See design/29-cookies.md §"Cookie Attribute Validation".
+  assertValidCookieOptions(options);
   store.cookieJar.set(name, { name, value, options });
   // Deletion cookies (Max-Age=0) should not appear in the read map.
   if (options.maxAge === 0) {

package/src/server/cookie-parsing.ts

@@ -110,15 +110,27 @@ export function parseSetCookie(
       case 'domain':
         options.domain = val;
         break;
-      case 'max-age':
-        options.maxAge = Number(val);
+      case 'max-age': {
+        // RFC 6265 §5.2.2: a non-numeric Max-Age is ignored, not fatal.
+        // Dropping NaN/Infinity here keeps this parser total and keeps
+        // `Max-Age=NaN` out of the serialized Set-Cookie header.
+        const maxAge = Number(val);
+        if (Number.isFinite(maxAge)) options.maxAge = maxAge;
         break;
+      }
       case 'expires':
         options.expires = new Date(val);
         break;
-      case 'samesite':
-        options.sameSite = val.toLowerCase() as 'strict' | 'lax' | 'none';
+      case 'samesite': {
+        // Unknown SameSite values are ignored (browsers treat them as
+        // unspecified) so forwarding a quirky upstream header via
+        // setFromHeaders never trips the entry-point validator.
+        const sameSite = val.toLowerCase();
+        if (sameSite === 'strict' || sameSite === 'lax' || sameSite === 'none') {
+          options.sameSite = sameSite;
+        }
         break;
+      }
       case 'secure':
         options.secure = true;
         break;

package/src/server/deny-boundary.ts

@@ -31,10 +31,14 @@
 
 import { createElement } from 'react';
 
+import { ErrorReconstituter } from '../client/error-reconstituter.js';
+import type { SerializableError } from '../client/error-reconstituter.js';
 import { requestContextAls } from './als-registry.js';
 import { DenySignal } from './primitives.js';
 import { loadModule } from './safe-load.js';
+import { LEGACY_FILE_TO_STATUS } from './status-code-resolver.js';
 import { withSpan } from './tracing.js';
+import { isMdxFilePath } from './utils/mdx-file.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
@@ -45,6 +49,15 @@ export interface DenyPageEntry {
   status: number | null;
   /** The component to render (server or client — both work). */
   component: (...args: unknown[]) => unknown;
+  /**
+   * How the entry matched: a status-code file (404.tsx/4xx.tsx), a legacy
+   * compat file (not-found.tsx/forbidden.tsx/unauthorized.tsx), or the
+   * error.tsx catch-all. error.tsx entries render with their documented
+   * { error, digest, reset } contract, not bare deny props. See TIM-1081.
+   */
+  kind: 'status' | 'legacy' | 'error';
+  /** MDX files are server components — rendered with plain props, never ErrorReconstituter. */
+  isMdx: boolean;
 }
 
 // ─── Chain Construction ──────────────────────────────────────────────────
@@ -56,10 +69,14 @@ export interface DenyPageEntry {
  * status-code file components in fallback order:
  * 1. Specific status files (403.tsx, 404.tsx) — exact match
  * 2. Category catch-alls (4xx.tsx) — matches any 4xx
- * 3. error.tsx — catches everything
+ * 3. Legacy compat files (not-found.tsx → 404, forbidden.tsx → 403,
+ *    unauthorized.tsx → 401) — exact match
+ * 4. error.tsx — catches everything
  *
  * Each segment is checked in this order. The chain is ordered so the
- * FIRST match wins at catch time.
+ * FIRST match wins at catch time. This mirrors resolveStatusFile's 4xx
+ * component chain (status-code-resolver.ts) — the two walks must stay in
+ * sync or in-tree and re-render deny paths resolve different files.
  */
 export async function buildDenyPageChain(
   segments: ManifestSegmentNode[],
@@ -82,7 +99,12 @@ export async function buildDenyPageChain(
         if (!isNaN(status)) {
           const mod = await loadModule(file).catch(() => null);
           if (mod?.default) {
-            chain.push({ status, component: mod.default as (...args: unknown[]) => unknown });
+            chain.push({
+              status,
+              component: mod.default as (...args: unknown[]) => unknown,
+              kind: 'status',
+              isMdx: isMdxFilePath(file.filePath),
+            });
           }
         }
       }
@@ -97,21 +119,50 @@ export async function buildDenyPageChain(
           chain.push({
             status: categoryStatus,
             component: mod.default as (...args: unknown[]) => unknown,
+            kind: 'status',
+            isMdx: isMdxFilePath(file.filePath),
           });
         }
       }
     }
   }
 
-  // Pass 2: error.tsx files — lowest priority catch-all.
-  // Only added AFTER all status files so they never shadow a specific
-  // or category status file from an ancestor segment.
+  // Pass 2: legacy compat files (not-found.tsx → 404, forbidden.tsx → 403,
+  // unauthorized.tsx → 401). Lower priority than status files (a root
+  // 4xx.tsx beats a leaf not-found.tsx) but higher than error.tsx — the
+  // same ordering as resolveStatusFile's resolve4xx. See TIM-1081.
+  for (let i = startIndex; i >= 0; i--) {
+    const segment = segments[i];
+    if (!segment.legacyStatusFiles) continue;
+    for (const [name, status] of Object.entries(LEGACY_FILE_TO_STATUS)) {
+      const file = segment.legacyStatusFiles[name];
+      if (!file) continue;
+      const mod = await loadModule(file).catch(() => null);
+      if (mod?.default) {
+        chain.push({
+          status,
+          component: mod.default as (...args: unknown[]) => unknown,
+          kind: 'legacy',
+          isMdx: isMdxFilePath(file.filePath),
+        });
+      }
+    }
+  }
+
+  // Pass 3: error.tsx files — lowest priority catch-all.
+  // Only added AFTER all status and legacy files so they never shadow a
+  // more specific file from an ancestor segment.
   for (let i = startIndex; i >= 0; i--) {
     const segment = segments[i];
     if (segment.error) {
       const mod = await loadModule(segment.error).catch(() => null);
       if (mod?.default) {
-        chain.push({ status: null, component: mod.default as (...args: unknown[]) => unknown });
+        chain.push({
+          status: null,
+          component: mod.default as (...args: unknown[]) => unknown,
+          kind: 'error',
+          isMdx: isMdxFilePath(segment.error.filePath),
+        });
       }
     }
   }
@@ -130,25 +181,67 @@ export function renderMatchingDenyPage(
   status: number,
   data: unknown
 ): React.ReactElement | null {
-  const h = createElement as (...args: unknown[]) => React.ReactElement;
-
   for (const entry of chain) {
     if (entry.status === status) {
-      return h(entry.component, { status, dangerouslyPassData: data });
+      return renderDenyEntry(entry, status, data);
     }
     if (entry.status === 400 && status >= 400 && status <= 499) {
-      return h(entry.component, { status, dangerouslyPassData: data });
+      return renderDenyEntry(entry, status, data);
     }
     if (entry.status === 500 && status >= 500 && status <= 599) {
-      return h(entry.component, { status, dangerouslyPassData: data });
+      return renderDenyEntry(entry, status, data);
     }
     if (entry.status === null) {
-      return h(entry.component, { status, dangerouslyPassData: data });
+      return renderDenyEntry(entry, status, data);
     }
   }
   return null;
 }
 
+/**
+ * Build the element for a matched deny chain entry with the props contract
+ * the file's convention documents:
+ *
+ * - Status-code and legacy files: { status, dangerouslyPassData }
+ * - error.tsx (TSX): { error, digest, reset } via ErrorReconstituter, plus
+ *   { status, dangerouslyPassData } for dual-shape implementations. Without
+ *   the Error prop, any error.tsx written per the docs (reading
+ *   error.message) crashes — turning a clean deny(404) into a 500. TIM-1081.
+ * - error.mdx: plain { status } — server component, static content.
+ */
+export function renderDenyEntry(
+  entry: DenyPageEntry,
+  status: number,
+  data: unknown
+): React.ReactElement {
+  const h = createElement as (...args: unknown[]) => React.ReactElement;
+
+  if (entry.kind !== 'error') {
+    return h(entry.component, { status, dangerouslyPassData: data });
+  }
+
+  // MDX error pages receive plain props — no Error serialization possible.
+  if (entry.isMdx) {
+    return h(entry.component, { status });
+  }
+
+  // The message is derived solely from the status code (already on the
+  // wire) — safe to cross the RSC→client boundary in production. No stack,
+  // no user data. See design/13-security.md §"Errors don't leak".
+  const serializableDeny: SerializableError = {
+    message: `Access denied with status ${status}`,
+    name: 'DenySignal',
+  };
+  return h(ErrorReconstituter, {
+    error: serializableDeny,
+    digest: null,
+    reset: undefined,
+    component: entry.component,
+    status,
+    dangerouslyPassData: data,
+  });
+}
+
 // ─── Page Boundary ────────────────────────────────────────────────────────
 
 /**