@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

package/src/server/default-logger.ts

@@ -0,0 +1,99 @@
+/**
+ * DefaultLogger — human-readable stderr logging when no custom logger is configured.
+ *
+ * Ships as the fallback so production deployments always have error visibility,
+ * even without an `instrumentation.ts` logger export. Output is one line per
+ * event, designed for `fly logs`, `kubectl logs`, Cloudflare dashboard tails, etc.
+ *
+ * Format:
+ *   [timber] ERROR  message  key=value key=value  trace_id=4bf92f35
+ *   [timber] WARN   message  key=value key=value  trace_id=4bf92f35
+ *   [timber] INFO   message  method=GET path=/dashboard status=200 durationMs=43  trace_id=4bf92f35
+ *
+ * Behavior:
+ * - Suppressed entirely in dev mode (dev logging handles all output)
+ * - `debug` suppressed unless TIMBER_DEBUG is set
+ * - Replaced entirely when a custom logger is set via `setLogger()`
+ *
+ * See design/17-logging.md §"DefaultLogger"
+ */
+
+import { isDevMode, isDebug } from './debug.js';
+import { formatSsrError } from './error-formatter.js';
+import type { TimberLogger } from './logger.js';
+
+/**
+ * Format data fields as `key=value` pairs for human-readable output.
+ * - `error` key is serialized via formatSsrError for stack trace cleanup
+ * - `trace_id` is truncated to 8 chars for readability (full ID in OTEL)
+ * - Other values are stringified inline
+ */
+function formatDataFields(data?: Record<string, unknown>): string {
+  if (!data) return '';
+
+  const parts: string[] = [];
+  let traceId: string | undefined;
+
+  for (const [key, value] of Object.entries(data)) {
+    if (key === 'trace_id') {
+      // Defer trace_id to the end
+      traceId = typeof value === 'string' ? value : String(value);
+      continue;
+    }
+    if (key === 'error') {
+      // Serialize errors with formatSsrError for clean output
+      parts.push(`error=${formatSsrError(value)}`);
+      continue;
+    }
+    if (value === undefined || value === null) continue;
+    parts.push(`${key}=${value}`);
+  }
+
+  // trace_id always last, truncated to 8 chars for readability
+  if (traceId) {
+    parts.push(`trace_id=${traceId.slice(0, 8)}`);
+  }
+
+  return parts.length > 0 ? '  ' + parts.join('  ') : '';
+}
+
+/** Pad level string to fixed width for alignment. */
+function padLevel(level: string): string {
+  return level.padEnd(5);
+}
+
+export function createDefaultLogger(): TimberLogger {
+  return {
+    error(msg: string, data?: Record<string, unknown>): void {
+      // Errors are ALWAYS logged, including dev mode. Suppressing errors
+      // in dev causes silent 500s with no stack trace, making route.ts
+      // and render errors impossible to debug. See TIM-555.
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('ERROR')}  ${msg}${fields}\n`);
+    },
+
+    warn(msg: string, data?: Record<string, unknown>): void {
+      // Warnings are always logged — same rationale as errors.
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('WARN')}  ${msg}${fields}\n`);
+    },
+
+    info(msg: string, data?: Record<string, unknown>): void {
+      // info is suppressed by default — per-request lines are too noisy
+      // without a custom logger. Enable with TIMBER_DEBUG.
+      if (isDevMode()) return;
+      if (!isDebug()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('INFO')}  ${msg}${fields}\n`);
+    },
+
+    debug(msg: string, data?: Record<string, unknown>): void {
+      // debug is suppressed in dev (dev logger handles it) and in
+      // production unless TIMBER_DEBUG is explicitly set.
+      if (isDevMode()) return;
+      if (!isDebug()) return;
+      const fields = formatDataFields(data);
+      process.stderr.write(`[timber] ${padLevel('DEBUG')}  ${msg}${fields}\n`);
+    },
+  };
+}

package/src/server/deny-boundary.ts

@@ -0,0 +1,218 @@
+/**
+ * Deny boundary subsystem — the in-tree DenySignal flow.
+ *
+ * Three things live together here because they form a single flow:
+ *
+ * 1. **Chain construction** (`buildDenyPageChain`) — walks the matched
+ *    segment chain at element-tree build time and produces a list of
+ *    `DenyPageEntry` records ordered by specificity (specific status →
+ *    category catch-all → `error.tsx`).
+ *
+ * 2. **Runtime matching** (`renderMatchingDenyPage`) — picks the first
+ *    chain entry whose status filter matches the thrown DenySignal and
+ *    returns a React element for the matching component. Used by
+ *    `AccessGate` and `PageDenyBoundary` when they catch a deny.
+ *
+ * 3. **The page boundary itself** (`PageDenyBoundary`) — the async server
+ *    component that wraps a server-component page, calls it, and catches
+ *    `DenySignal` so the deny page renders in-tree (no throw reaches
+ *    React Flight, single render pass).
+ *
+ * Plus the ALS helpers (`setDenyStatus` / `getDenyStatus`) the boundary
+ * uses to thread the matched status code back to the pipeline so the
+ * HTTP status reflects the deny.
+ *
+ * Folded into one module from the former `deny-page-resolver.ts` and
+ * `page-deny-boundary.tsx` (TIM-853) — the names were misleading and the
+ * three pieces only made sense together.
+ *
+ * See design/04-authorization.md, design/10-error-handling.md, TIM-666.
+ */
+
+import { createElement } from 'react';
+
+import { requestContextAls } from './als-registry.js';
+import { DenySignal } from './primitives.js';
+import { loadModule } from './safe-load.js';
+import { withSpan } from './tracing.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/** A single entry in the deny page fallback chain. */
+export interface DenyPageEntry {
+  /** Status code filter: specific (403), category (400 = any 4xx), or null (catch-all). */
+  status: number | null;
+  /** The component to render (server or client — both work). */
+  component: (...args: unknown[]) => unknown;
+}
+
+// ─── Chain Construction ──────────────────────────────────────────────────
+
+/**
+ * Build the deny page fallback chain from the segment chain.
+ *
+ * Walks segments from `startIndex` outward (toward root) and collects
+ * 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
+ *
+ * Each segment is checked in this order. The chain is ordered so the
+ * FIRST match wins at catch time.
+ */
+export async function buildDenyPageChain(
+  segments: ManifestSegmentNode[],
+  startIndex: number
+): Promise<DenyPageEntry[]> {
+  const chain: DenyPageEntry[] = [];
+
+  // Pass 1: Status files (specific + category) across ALL segments.
+  // These have higher priority than error.tsx — a root 4xx.tsx should
+  // match before a leaf error.tsx. Walking inner → outer ensures the
+  // nearest match wins within each priority tier.
+  for (let i = startIndex; i >= 0; i--) {
+    const segment = segments[i];
+    if (!segment.statusFiles) continue;
+
+    // Specific status files (403.tsx, 404.tsx, etc.)
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (key !== '4xx' && key !== '5xx') {
+        const status = parseInt(key, 10);
+        if (!isNaN(status)) {
+          const mod = await loadModule(file).catch(() => null);
+          if (mod?.default) {
+            chain.push({ status, component: mod.default as (...args: unknown[]) => unknown });
+          }
+        }
+      }
+    }
+
+    // Category catch-alls (4xx.tsx, 5xx.tsx)
+    for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (key === '4xx' || key === '5xx') {
+        const mod = await loadModule(file).catch(() => null);
+        if (mod?.default) {
+          const categoryStatus = key === '4xx' ? 400 : 500;
+          chain.push({
+            status: categoryStatus,
+            component: mod.default as (...args: unknown[]) => unknown,
+          });
+        }
+      }
+    }
+  }
+
+  // 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.
+  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 });
+      }
+    }
+  }
+
+  return chain;
+}
+
+// ─── Runtime Matcher ──────────────────────────────────────────────────────
+
+/**
+ * Find the first deny page in the chain that matches the given status code.
+ * Returns a React element for the matching component, or null if no match.
+ */
+export function renderMatchingDenyPage(
+  chain: DenyPageEntry[],
+  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 });
+    }
+    if (entry.status === 400 && status >= 400 && status <= 499) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+    if (entry.status === 500 && status >= 500 && status <= 599) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+    if (entry.status === null) {
+      return h(entry.component, { status, dangerouslyPassData: data });
+    }
+  }
+  return null;
+}
+
+// ─── Page Boundary ────────────────────────────────────────────────────────
+
+/**
+ * Async server component that wraps a page call with DenySignal catching.
+ *
+ * Calls the page component as an async function (the same thing React
+ * Flight does internally), awaits it, and catches DenySignal. On catch,
+ * renders the matching deny page in-tree. On success, returns the page's
+ * rendered output normally.
+ *
+ * Client component pages ('use client') are NOT wrapped — they can't call
+ * deny() (server-only API) and must go through createElement normally.
+ *
+ * No error reaches React Flight — the Flight stream is clean, SSR succeeds,
+ * and the entire request uses a single renderToReadableStream call.
+ */
+export async function PageDenyBoundary({
+  Page,
+  route,
+  denyPages,
+}: {
+  /** The page server component function. */
+  Page: (...args: unknown[]) => unknown;
+  /** Route path for OTEL tracing. */
+  route: string;
+  /** Deny page fallback chain from the segment chain. */
+  denyPages: DenyPageEntry[];
+}): Promise<React.ReactElement> {
+  try {
+    // Call the page as an async function — same as React Flight does.
+    // Wrap in OTEL span for tracing (replaces the TracedPage wrapper).
+    const result = await withSpan('timber.page', { 'timber.route': route }, () => Page({}));
+    return result as React.ReactElement;
+  } catch (error: unknown) {
+    if (error instanceof DenySignal) {
+      const denyElement = renderMatchingDenyPage(denyPages, error.status, error.data);
+      if (denyElement) {
+        setDenyStatus(error.status);
+        return denyElement;
+      }
+    }
+    // Non-deny errors (RedirectSignal, runtime errors) propagate normally.
+    throw error;
+  }
+}
+
+// ─── ALS Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Set the deny status in the request context ALS.
+ * Called from AccessGate / PageDenyBoundary when a DenySignal is caught.
+ * The pipeline reads this after render to set the HTTP status code.
+ */
+export function setDenyStatus(status: number): void {
+  const store = requestContextAls.getStore();
+  if (store) {
+    store.denyStatus = status;
+  }
+}
+
+/**
+ * Read the deny status from the request context ALS.
+ * Returns undefined if no deny was caught during render.
+ */
+export function getDenyStatus(): number | undefined {
+  return requestContextAls.getStore()?.denyStatus;
+}

package/src/server/deny-renderer.ts

@@ -16,18 +16,22 @@
  */
 
 import { createElement } from 'react';
-import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
+import { renderToReadableStream } from '../rsc-runtime/rsc.js';
 
 import { DenySignal } from './primitives.js';
 import { logRenderError } from './logger.js';
+import { loadModule } from './safe-load.js';
 import { isDebug } from './debug.js';
+import { escapeHtml } from './utils/escape-html.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
-import { resolveManifestStatusFile } from './manifest-status-resolver.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';
@@ -84,7 +88,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 +100,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 +112,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,9 +120,6 @@ 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, {
@@ -126,23 +127,14 @@ export async function renderDenyPage(
     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.'
-    );
+  // 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)
@@ -170,15 +162,15 @@ export async function renderDenyPage(
     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: headHtml + flightInitScript(),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
     rscStream: inlineStream,
   };
@@ -199,14 +191,14 @@ export async function renderDenyPageAsRsc(
   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,22 +207,17 @@ 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);
-    }
+  // 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, {
@@ -263,7 +250,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 +259,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 +281,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,8 +100,8 @@ 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
@@ -94,7 +110,7 @@ export interface EarlyHintOptions {
  * 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 +119,35 @@ 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
   for (const url of collectRouteCss(segments, manifest)) {
-    add(formatLinkHeader({ href: url, rel: 'preload', as: 'style' }));
+    add(url, 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 +155,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' }));
     }
   }