@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/src/server/deny-renderer.ts

@@ -15,19 +15,26 @@
  * See design/10-error-handling.md §"Status-Code Files"
  */
 
-import { createElement } from 'react';
-import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
+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 { getCookiesForSsr } from './cookie-context.js';
 import { logRenderError } from './logger.js';
+import { loadModule } from './safe-load.js';
+import { isMdxFilePath } from './utils/mdx-file.js';
 import { isDebug } from './debug.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
-import { resolveManifestStatusFile } from './manifest-status-resolver.js';
+import { headElementsToReact } from './metadata.js';
+import { resolveStatusFile } from './status-code-resolver.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
 import type { RouteMatch } from './pipeline.js';
-import type { NavContext } from './ssr-entry.js';
+import type { NavContext } from './ssr-bridge-types.js';
+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';
@@ -58,6 +65,29 @@ function isApiRoute(segments: ReadonlyArray<ManifestSegmentNode>): boolean {
   return !!leaf?.route;
 }
 
+/**
+ * Build the deny page element for a resolved status file with the correct
+ * props contract for the file's convention. Delegates to renderDenyEntry
+ * (deny-boundary.ts) so the in-tree and re-render deny paths render
+ * identical elements — in particular, error.tsx serving a deny gets
+ * { error, digest, reset } via ErrorReconstituter, not bare deny props.
+ * See TIM-1081.
+ */
+function buildDenyElement(
+  deny: DenySignal,
+  component: (...args: unknown[]) => unknown,
+  resolutionKind: 'exact' | 'category' | 'legacy' | 'error',
+  filePath: string
+): React.ReactElement {
+  const entry: DenyPageEntry = {
+    status: deny.status,
+    component,
+    kind: resolutionKind === 'error' ? 'error' : resolutionKind === 'legacy' ? 'legacy' : 'status',
+    isMdx: isMdxFilePath(filePath),
+  };
+  return renderDenyEntry(entry, deny.status, deny.data);
+}
+
 /**
  * Render a status-code error page for a DenySignal.
  *
@@ -84,7 +114,7 @@ export async function renderDenyPage(
   }
 
   // Page routes → component chain first, JSON fallback only if no component found.
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'component');
+  const resolution = resolveStatusFile(deny.status, segments, 'component');
 
   // No component status file — try JSON chain before bare fallback
   if (!resolution) {
@@ -96,7 +126,7 @@ export async function renderDenyPage(
   // Dev warning: JSON status file exists but is shadowed by the component chain.
   // This helps developers understand why their .json file isn't being served.
   if (isDebug()) {
-    const jsonResolution = resolveManifestStatusFile(deny.status, segments, 'json');
+    const jsonResolution = resolveStatusFile(deny.status, segments, 'json');
     if (jsonResolution) {
       console.warn(
         `[timber] ${jsonResolution.file.filePath} exists but is shadowed by ` +
@@ -108,7 +138,7 @@ export async function renderDenyPage(
   }
 
   // Load the status-code page component
-  const mod = (await resolution.file.load()) as Record<string, unknown>;
+  const mod = await loadModule(resolution.file);
   if (!mod.default) {
     return new Response(null, { status: deny.status, headers: responseHeaders });
   }
@@ -116,71 +146,57 @@ export async function renderDenyPage(
   const ErrorPageComponent = mod.default as (...args: unknown[]) => unknown;
   const h = createElement as (...args: unknown[]) => React.ReactElement;
 
-  // Check shell opt-out: export const shell = false
-  const shellEnabled = mod.shell !== false;
-
-  // 4xx status-code pages receive { status, dangerouslyPassData }
-  // per design/10-error-handling.md §"Status-Code File Props"
-  let element = h(ErrorPageComponent, {
-    status: deny.status,
-    dangerouslyPassData: deny.data,
-  });
-
-  // Wrap in layouts unless shell is explicitly disabled
-  if (shellEnabled) {
-    const resolvedSegments = new Set(segments.slice(0, resolution.segmentIndex + 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);
-    }
-  } else if (isDebug()) {
-    // Dev-mode: warn if shell=false might conflict with Suspense
-    // The actual Suspense boundary check happens at render time in the pipeline.
-    // This is a preemptive log for developer awareness.
-    console.warn(
-      `[timber] Status-code file ${resolution.file.filePath} exports shell = false. ` +
-        'If deny() fires inside a Suspense boundary, layouts are already committed and ' +
-        'cannot be unwrapped. The shell opt-out will be ignored in that case.'
-    );
+  // 4xx status-code pages receive { status, dangerouslyPassData }; an
+  // error.tsx match gets { error, digest, reset } via ErrorReconstituter.
+  // See design/10-error-handling.md §"Status-Code File Props" and TIM-1081.
+  let element = buildDenyElement(
+    deny,
+    ErrorPageComponent,
+    resolution.kind,
+    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));
+  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);
   }
 
-  // Build head HTML from error page metadata (if any)
-  let headHtml = '';
+  // Embed metadata as React elements in the tree — React 19 Float hoists
+  // them into <head> during SSR. See TIM-1151.
   if (mod.metadata) {
     const resolvedMeta = resolveMetadata([{ metadata: mod.metadata as Metadata, isPage: true }]);
     const headElements = renderMetadataToElements(resolvedMeta);
-    for (const el of headElements) {
-      if (el.tag === 'title' && el.content) {
-        headHtml += `<title>${escapeHtml(el.content)}</title>`;
-      } else if (el.attrs) {
-        const attrs = Object.entries(el.attrs)
-          .map(([k, v]) => `${k}="${escapeHtml(v)}"`)
-          .join(' ');
-        headHtml += `<${el.tag} ${attrs}>`;
-      }
-    }
+    const metaEl = headElementsToReact(headElements);
+    element = h(Fragment, null, metaEl, element);
   }
 
   // Render the error page to a fresh RSC Flight stream.
   const rscStream = renderToReadableStream(element, {
+    signal: req.signal,
     onError(error: unknown) {
       logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
     },
     debugChannel: createDebugChannelSink(),
   });
 
-  const [ssrStream, inlineStream] = rscStream.tee();
+  const [ssrStream, inlineStream] = teeWithErrorPropagation(rscStream);
 
   const navContext: NavContext = {
     pathname: new URL(req.url).pathname,
-    params: match.params,
+    segmentParams: match.segmentParams,
     searchParams: Object.fromEntries(new URL(req.url).searchParams),
     statusCode: deny.status,
     responseHeaders,
-    headHtml,
+    headHtml: flightInitScript(),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
     rscStream: inlineStream,
+    signal: req.signal,
+    cookies: getCookiesForSsr(),
   };
 
   return callSsr(ssrStream, navContext);
@@ -196,17 +212,18 @@ export async function renderDenyPageAsRsc(
   deny: DenySignal,
   segments: ManifestSegmentNode[],
   layoutComponents: LayoutEntry[],
+  req: Request,
   responseHeaders: Headers,
   createDebugChannelSink: DebugChannelFactory
 ): Promise<Response> {
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'component');
+  const resolution = resolveStatusFile(deny.status, segments, 'component');
 
   if (!resolution) {
     responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
     return new Response(null, { status: deny.status, headers: responseHeaders });
   }
 
-  const mod = (await resolution.file.load()) as Record<string, unknown>;
+  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 });
@@ -215,25 +232,23 @@ export async function renderDenyPageAsRsc(
   const ErrorPageComponent = mod.default as (...args: unknown[]) => unknown;
   const h = createElement as (...args: unknown[]) => React.ReactElement;
 
-  // Check shell opt-out
-  const shellEnabled = mod.shell !== false;
-
-  let element = h(ErrorPageComponent, {
-    status: deny.status,
-    dangerouslyPassData: deny.data,
-  });
-
-  // Wrap in layouts unless shell is explicitly disabled
-  if (shellEnabled) {
-    const resolvedSegments = new Set(segments.slice(0, resolution.segmentIndex + 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);
-    }
+  let element = buildDenyElement(
+    deny,
+    ErrorPageComponent,
+    resolution.kind,
+    resolution.file.filePath
+  );
+
+  // Always wrap in layout shell.
+  const resolvedSegments = new Set(segments.slice(0, resolution.segmentIndex + 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, {
+    signal: req.signal,
     onError(error: unknown) {
       console.error('[timber] Error page RSC render error:', error);
     },
@@ -241,7 +256,6 @@ export async function renderDenyPageAsRsc(
   });
 
   responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
-  responseHeaders.set('Vary', 'Accept');
   return new Response(rscStream, {
     status: deny.status,
     headers: responseHeaders,
@@ -263,7 +277,7 @@ async function renderDenyPageJson(
   segments: ManifestSegmentNode[],
   responseHeaders: Headers
 ): Promise<Response | null> {
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
+  const resolution = resolveStatusFile(deny.status, segments, 'json');
 
   if (!resolution) {
     return null;
@@ -272,7 +286,7 @@ 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 resolution.file.load()) as Record<string, unknown>;
+  const mod = await loadModule(resolution.file);
   const jsonContent = mod.default ?? mod;
 
   responseHeaders.set('content-type', 'application/json; charset=utf-8');
@@ -294,10 +308,4 @@ function bareJsonResponse(status: number, responseHeaders: Headers): Response {
   });
 }
 
-function escapeHtml(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
+// escapeHtml imported from server/utils/escape-html.ts

package/src/server/dev-source-map.ts

@@ -0,0 +1,31 @@
+/**
+ * Dev-only error source-mapping bridge.
+ *
+ * Stores a callback that rewrites an error's stack trace using the Vite
+ * dev server's module graph. Set by the RSC entry on startup (via
+ * setDevSourceMapHandler), consumed by error renderers before generating
+ * error pages.
+ *
+ * In production, the callback is never set — all calls are no-ops.
+ *
+ * See TIM-811.
+ */
+
+let _sourceMapError: ((error: Error) => void) | undefined;
+
+/**
+ * Set the source-map callback. Called once during dev server initialization.
+ */
+export function setSourceMapCallback(fn: (error: Error) => void): void {
+  _sourceMapError = fn;
+}
+
+/**
+ * Source-map an error's stack trace in-place if the callback is available.
+ * No-op in production or before the dev server initializes.
+ */
+export function sourceMapError(error: unknown): void {
+  if (_sourceMapError && error instanceof Error) {
+    _sourceMapError(error);
+  }
+}

package/src/server/early-hints-sender.ts

@@ -19,6 +19,7 @@
  */
 
 import { earlyHintsSenderAls } from './als-registry.js';
+import { swallow } from './logger.js';
 
 /** Function that sends Link header values as a 103 Early Hints response. */
 export type EarlyHintsSenderFn = (links: string[]) => void;
@@ -47,7 +48,7 @@ export function sendEarlyHints103(links: string[]): void {
   if (!sender) return;
   try {
     sender(links);
-  } catch {
-    // Sending 103 is best-effort — failure never blocks the request.
+  } catch (err) {
+    swallow(err, 'early hints 103 send failed');
   }
 }

package/src/server/early-hints.ts

@@ -58,15 +58,31 @@ export interface EarlyHint {
 /**
  * Format a single EarlyHint as a Link header value.
  *
+ * Attribute order: `as` before `rel` to match Cloudflare CDN's cached
+ * Early Hints format. Cloudflare caches Link headers from 200 responses
+ * and re-emits them as 103 Early Hints on subsequent requests. If our
+ * attribute order differs from Cloudflare's cached copy, the browser
+ * sees two preload headers for the same URL (different attribute order)
+ * and warns "Preload was ignored." Matching the order ensures the
+ * browser deduplicates them correctly.
+ *
  * Examples:
- *   `</styles/root.css>; rel=preload; as=style`
- *   `</fonts/inter.woff2>; rel=preload; as=font; crossorigin=anonymous`
+ *   `</styles/root.css>; as=style; rel=preload`
+ *   `</fonts/inter.woff2>; as=font; rel=preload; crossorigin=anonymous`
  *   `</_timber/client.js>; rel=modulepreload`
  *   `<https://fonts.googleapis.com>; rel=preconnect`
  */
 export function formatLinkHeader(hint: EarlyHint): string {
+  // For preload hints, emit `as` before `rel` to match Cloudflare's
+  // cached header format and avoid duplicate preload warnings.
+  if (hint.as !== undefined) {
+    let value = `<${hint.href}>; as=${hint.as}; rel=${hint.rel}`;
+    if (hint.crossOrigin !== undefined) value += `; crossorigin=${hint.crossOrigin}`;
+    if (hint.fetchPriority !== undefined) value += `; fetchpriority=${hint.fetchPriority}`;
+    return value;
+  }
+  // For modulepreload / preconnect (no `as`), emit rel first.
   let value = `<${hint.href}>; rel=${hint.rel}`;
-  if (hint.as !== undefined) value += `; as=${hint.as}`;
   if (hint.crossOrigin !== undefined) value += `; crossorigin=${hint.crossOrigin}`;
   if (hint.fetchPriority !== undefined) value += `; fetchpriority=${hint.fetchPriority}`;
   return value;
@@ -84,17 +100,11 @@ export interface EarlyHintOptions {
  * Collect all Link header strings for a matched route's segment chain.
  *
  * Walks the build manifest to emit hints for:
- * - CSS stylesheets (rel=preload; as=style)
- * - Font assets (rel=preload; as=font; crossorigin)
+ * - CSS stylesheets (as=style; rel=preload)
+ * - Font assets (as=font; rel=preload; crossorigin)
  * - JS modulepreload hints (rel=modulepreload) — unless skipJs is set
  *
- * Also emits global CSS from the `_global` manifest key. Route files
- * are server components that don't appear in the client bundle, so
- * per-route CSS keying doesn't work with the RSC plugin. The `_global`
- * key contains all CSS assets from the client build — fine for early
- * hints since they're just prefetch signals.
- *
- * Returns formatted Link header strings, deduplicated, root → leaf order.
+ * Returns formatted Link header strings, deduplicated by URL, root → leaf order.
  * Returns an empty array in dev mode (manifest is empty).
  */
 export function collectEarlyHintHeaders(
@@ -103,30 +113,30 @@ export function collectEarlyHintHeaders(
   options?: EarlyHintOptions
 ): string[] {
   const result: string[] = [];
-  const seen = new Set<string>();
+  // Dedup by URL (href), not by full formatted header string.
+  // Different code paths can produce the same URL with different attribute
+  // ordering, which would bypass a full-string dedup and produce duplicate
+  // Link headers that trigger browser "preload was ignored" warnings.
+  const seenUrls = new Set<string>();
 
-  const add = (header: string) => {
-    if (!seen.has(header)) {
-      seen.add(header);
+  const add = (url: string, header: string) => {
+    if (!seenUrls.has(url)) {
+      seenUrls.add(url);
       result.push(header);
     }
   };
 
-  // Per-route CSS — rel=preload; as=style
+  // Per-route CSS — as=style; rel=preload
+  // The HTML <head> also contains a matching <link rel="preload" as="style">
+  // tag so browsers can deduplicate the 103 hint against the HTML tag.
   for (const url of collectRouteCss(segments, manifest)) {
-    add(formatLinkHeader({ href: url, rel: 'preload', as: 'style' }));
-  }
-
-  // Global CSS — all CSS assets from the client bundle.
-  // Covers CSS that the RSC plugin injects via data-rsc-css-href,
-  // which isn't keyed to route segments in our manifest.
-  for (const url of manifest.css['_global'] ?? []) {
-    add(formatLinkHeader({ href: url, rel: 'preload', as: 'style' }));
+    add(url, formatLinkHeader({ href: url, rel: 'preload', as: 'style' }));
   }
 
-  // Fonts — rel=preload; as=font; crossorigin (crossorigin required per spec)
+  // Fonts — as=font; rel=preload; crossorigin (crossorigin required per spec)
   for (const font of collectRouteFonts(segments, manifest)) {
     add(
+      font.href,
       formatLinkHeader({ href: font.href, rel: 'preload', as: 'font', crossOrigin: 'anonymous' })
     );
   }
@@ -134,7 +144,7 @@ export function collectEarlyHintHeaders(
   // JS chunks — rel=modulepreload (skip when client JS is disabled)
   if (!options?.skipJs) {
     for (const url of collectRouteModulepreloads(segments, manifest)) {
-      add(formatLinkHeader({ href: url, rel: 'modulepreload' }));
+      add(url, formatLinkHeader({ href: url, rel: 'modulepreload' }));
     }
   }
 

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

@@ -5,8 +5,10 @@
  * See design/10-error-handling.md.
  */
 
-import { TimberErrorBoundary } from '#/client/error-boundary.js';
+import { TimberErrorBoundary } from '../client/error-boundary.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
+import { loadModule } from './safe-load.js';
+import { isMdxFilePath } from './utils/mdx-file.js';
 
 /**
  * Wrap an element in error boundaries defined by a route segment.
@@ -15,11 +17,17 @@ import type { ManifestSegmentNode } from './route-matcher.js';
  * 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
+ *
+ * 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.
  */
 export async function wrapSegmentWithErrorBoundaries(
   segment: ManifestSegmentNode,
   element: React.ReactElement,
-  h: (...args: unknown[]) => 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)
   if (segment.statusFiles) {
@@ -27,13 +35,27 @@ export async function wrapSegmentWithErrorBoundaries(
       if (key !== '4xx' && key !== '5xx') {
         const status = parseInt(key, 10);
         if (!isNaN(status)) {
-          const mod = (await file.load()) as Record<string, unknown>;
-          if (mod.default) {
-            element = h(TimberErrorBoundary, {
-              fallbackComponent: mod.default,
-              status,
-              children: element,
-            });
+          // 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,
+              });
+            }
           }
         }
       }
@@ -41,14 +63,24 @@ export async function wrapSegmentWithErrorBoundaries(
 
     // Category catch-alls (4xx.tsx, 5xx.tsx)
     for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (skipDenyBoundaries && key === '4xx') continue;
       if (key === '4xx' || key === '5xx') {
-        const mod = (await file.load()) as Record<string, unknown>;
-        if (mod.default) {
-          element = h(TimberErrorBoundary, {
-            fallbackComponent: mod.default,
-            status: key === '4xx' ? 400 : 500,
-            children: element,
-          });
+        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,
+            });
+          }
         }
       }
     }
@@ -56,12 +88,19 @@ export async function wrapSegmentWithErrorBoundaries(
 
   // error.tsx (outermost — catches anything not matched by status files)
   if (segment.error) {
-    const mod = (await segment.error.load()) as Record<string, unknown>;
-    if (mod.default) {
-      element = h(TimberErrorBoundary, {
-        fallbackComponent: mod.default,
-        children: element,
-      });
+    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,
+        });
+      }
     }
   }