@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.200

package/src/server/deny-renderer.ts

@@ -15,22 +15,33 @@
  * See design/10-error-handling.md §"Status-Code Files"
  */
 
-import { createElement } from 'react';
-import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
-
-import { DenySignal } from './primitives.js';
-import { logRenderError } from './logger.js';
-import { isDebug } from './debug.js';
-import { resolveMetadata, renderMetadataToElements } from './metadata.js';
-import { resolveManifestStatusFile } from './manifest-status-resolver.js';
-import type { ManifestSegmentNode } from './route-matcher.js';
-import type { RouteMatch } from './pipeline.js';
-import type { NavContext } from './ssr-entry.js';
-import type { ClientBootstrapConfig } from './html-injectors.js';
-import type { Metadata } from './types.js';
-
-/** RSC content type for client navigation payload requests. */
-const RSC_CONTENT_TYPE = 'text/x-component';
+import { createElement, Fragment } from 'react';
+import { renderToReadableStream } from '../rsc-runtime/rsc.ts';
+
+import { DenySignal } from './primitives.ts';
+import { appVisibleSearch } from '../shared/rsc-cache-key.ts';
+import { getSlotParamsForClient } from './request-context.ts';
+import { withPublishedParams } from './publish-params.ts';
+import { renderDenyEntry, type DenyEntryShape } from './deny-boundary.ts';
+import { getCookiesForSsr } from './cookie-context.ts';
+import { logRenderError } from './logger.ts';
+import { loadModule } from './safe-load.ts';
+import { isMdxFilePath } from './utils/mdx-file.ts';
+import { isDebug } from './debug.ts';
+import { resolveMetadata, renderMetadataToElements } from './metadata.ts';
+import { headElementsToReact } from './metadata.ts';
+import { resolveStatusFile } from './status-code-resolver.ts';
+import { defaultStatusPageResponse } from './default-status-page.ts';
+import { rscErrorEnvelope } from './rsc-error-envelope.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+import type { RouteMatch } from './pipeline.ts';
+import type { NavContext } from './ssr-bridge-types.ts';
+import { flightInitScript } from './flight-scripts.ts';
+import { getCspNonce } from './csp-nonce.ts';
+import type { ClientBootstrapConfig } from './html-injectors.ts';
+import type { Metadata } from './types.ts';
+import { teeWithErrorPropagation } from './stream-utils.ts';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.ts';
 
 /** Layout component entry for deny page wrapping. */
 export interface LayoutEntry {
@@ -58,12 +69,46 @@ 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' | 'error',
+  filePath: string
+): React.ReactElement {
+  const entry: DenyEntryShape = {
+    component,
+    kind: resolutionKind === 'error' ? 'error' : 'status',
+    isMdx: isMdxFilePath(filePath),
+  };
+  return renderDenyEntry(entry, deny.status, deny.data);
+}
+
+/**
+ * Supplies a replacement for the framework default page at the end of the
+ * chain. Returning `null` keeps the framework default.
+ *
+ * The dev server uses this to substitute its route-listing 404 page. It is a
+ * parameter rather than a check on the produced Response because "the app
+ * authored no status page" is a fact about the *chain*, and inspecting the
+ * result for it (e.g. an empty body) stops being true the moment the chain
+ * grows a real terminal — which is exactly what TIM-1258 did.
+ */
+export type DefaultPageRenderer = (status: number, responseHeaders: Headers) => Response | null;
+
 /**
  * Render a status-code error page for a DenySignal.
  *
  * Resolves the appropriate status-code file from the segment chain based
- * on format preference. Returns an HTML Response (component), JSON Response,
- * or bare fallback Response.
+ * on format preference. Returns an HTML Response (component), a JSON Response,
+ * or the framework default status page.
  */
 export async function renderDenyPage(
   deny: DenySignal,
@@ -74,29 +119,41 @@ export async function renderDenyPage(
   responseHeaders: Headers,
   clientBootstrap: ClientBootstrapConfig,
   createDebugChannelSink: DebugChannelFactory,
-  callSsr: CallSsrFn
+  callSsr: CallSsrFn,
+  defaultPage?: DefaultPageRenderer,
+  firstDeniedIndex = Infinity
 ): Promise<Response> {
+  // Clamp the resolution walk to the denied segment — a status file below
+  // the denial is invisible to the in-tree chain and must not be selected
+  // by the fallback. The denying segment itself IS included (matching
+  // buildDenyPageChain's start-at-i semantics), but its layout is not
+  // (the gate-outside-layout rule from TIM-1074). See TIM-1358.
+  const maxIndex = firstDeniedIndex < Infinity ? firstDeniedIndex : undefined;
+
   // API routes (route.ts) → JSON only, never render components
   if (isApiRoute(segments)) {
-    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders);
+    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders, maxIndex);
     if (jsonResponse) return jsonResponse;
     return bareJsonResponse(deny.status, responseHeaders);
   }
 
   // Page routes → component chain first, JSON fallback only if no component found.
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'component');
+  const resolution = resolveStatusFile(deny.status, segments, 'component', maxIndex);
 
-  // No component status file — try JSON chain before bare fallback
+  // No component status file — try JSON chain, then the framework default page.
   if (!resolution) {
-    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders);
+    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders, maxIndex);
     if (jsonResponse) return jsonResponse;
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+    return (
+      defaultPage?.(deny.status, responseHeaders) ??
+      defaultStatusPageResponse(deny.status, responseHeaders)
+    );
   }
 
   // Dev warning: JSON status file exists but is shadowed by the component chain.
   // 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 ` +
@@ -107,83 +164,112 @@ export async function renderDenyPage(
     }
   }
 
-  // Load the status-code page component
-  const mod = (await resolution.file.load()) as Record<string, unknown>;
-  if (!mod.default) {
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+  // Load the status-code page component. A file that resolved but exports no
+  // default — or whose module fails to import or evaluate — is not a usable
+  // component match: continue down the documented chain (JSON, then framework
+  // default) rather than returning an empty body or letting the loader's
+  // rejection escape request handling. Mirrors buildDenyPageChain and the
+  // error-file resolver, which both swallow the load failure.
+  const mod = await loadModule(resolution.file).catch(() => null);
+  if (!mod?.default) {
+    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders, maxIndex);
+    if (jsonResponse) return jsonResponse;
+    return (
+      defaultPage?.(deny.status, responseHeaders) ??
+      defaultStatusPageResponse(deny.status, responseHeaders)
+    );
   }
 
   const ErrorPageComponent = mod.default as (...args: unknown[]) => unknown;
   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
+  );
+
+  // Wrap in layout shell, clamped so a denied segment's layout never
+  // executes — the gate-outside-layout rule from TIM-1074. The denied
+  // segment's layout was loaded into `layoutComponents` but must not
+  // appear in the fallback response. See TIM-1358.
+  const layoutCeiling = Math.min(resolution.segmentIndex, firstDeniedIndex - 1);
+  const resolvedSegments = new Set(segments.slice(0, layoutCeiling + 1));
+  const layoutsToWrap = layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
+  for (let i = layoutsToWrap.length - 1; i >= 0; i--) {
+    const { component } = layoutsToWrap[i];
+    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, {
+  const rscStream = renderToReadableStream(withPublishedParams(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 slotParams = getSlotParamsForClient();
+
+  const denyUrl = new URL(req.url);
+  const nonce = getCspNonce();
   const navContext: NavContext = {
-    pathname: new URL(req.url).pathname,
-    params: match.params,
-    searchParams: Object.fromEntries(new URL(req.url).searchParams),
+    pathname: denyUrl.pathname,
+    search: appVisibleSearch(denyUrl).search,
+    segmentParams: match.segmentParams,
+    slotParams,
     statusCode: deny.status,
     responseHeaders,
-    headHtml,
+    headHtml: flightInitScript(nonce),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
+    nonce,
     rscStream: inlineStream,
+    signal: req.signal,
+    cookies: getCookiesForSsr(),
   };
 
-  return callSsr(ssrStream, navContext);
+  try {
+    // `await` inside the try on purpose — see the same note in
+    // rsc-entry/error-renderer.ts. A status page that crashes during SSR
+    // ends in the framework default page, not a blank body: the pipeline's
+    // own deny fallback catches this and can only produce an empty response,
+    // and a crashing 404.tsx is exactly when the reader has nothing else to
+    // go on (TIM-1258).
+    return await callSsr(ssrStream, navContext);
+  } catch (renderError) {
+    logRenderError({ method: req.method, path: new URL(req.url).pathname, error: renderError });
+    return defaultStatusPageResponse(deny.status, responseHeaders);
+  }
+}
+
+/**
+ * Terminal fallback for a client-navigation deny with no status-code file.
+ *
+ * The HTML path answers this case with the framework default page, but a
+ * client-navigation response cannot carry HTML — the Flight decoder would
+ * choke on it. Emit the hard-navigate envelope instead: the client abandons
+ * SPA navigation and the resulting document request renders that same default
+ * page. Before TIM-1258 this returned an empty Flight body, which the decoder
+ * hit as a malformed stream.
+ */
+function denyHardNavigateResponse(status: number, responseHeaders: Headers): Response {
+  return rscErrorEnvelope(status, responseHeaders);
 }
 
 /**
@@ -196,44 +282,44 @@ export async function renderDenyPageAsRsc(
   deny: DenySignal,
   segments: ManifestSegmentNode[],
   layoutComponents: LayoutEntry[],
+  req: Request,
   responseHeaders: Headers,
-  createDebugChannelSink: DebugChannelFactory
+  createDebugChannelSink: DebugChannelFactory,
+  firstDeniedIndex = Infinity
 ): Promise<Response> {
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'component');
+  const maxIndex = firstDeniedIndex < Infinity ? firstDeniedIndex : undefined;
+  const resolution = resolveStatusFile(deny.status, segments, 'component', maxIndex);
 
   if (!resolution) {
-    responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+    return denyHardNavigateResponse(deny.status, responseHeaders);
   }
 
-  const mod = (await resolution.file.load()) as Record<string, unknown>;
-  if (!mod.default) {
-    responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
-    return new Response(null, { status: deny.status, headers: responseHeaders });
+  const mod = await loadModule(resolution.file).catch(() => null);
+  if (!mod?.default) {
+    return denyHardNavigateResponse(deny.status, responseHeaders);
   }
 
   const ErrorPageComponent = mod.default as (...args: unknown[]) => unknown;
   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
+  );
+
+  // Wrap in layout shell, clamped to exclude denied segment layouts. TIM-1358.
+  const layoutCeiling = Math.min(resolution.segmentIndex, firstDeniedIndex - 1);
+  const resolvedSegments = new Set(segments.slice(0, layoutCeiling + 1));
+  const layoutsToWrap = layoutComponents.filter((lc) => resolvedSegments.has(lc.segment));
+  for (let i = layoutsToWrap.length - 1; i >= 0; i--) {
+    const { component } = layoutsToWrap[i];
+    element = h(component, null, element);
   }
 
-  const rscStream = renderToReadableStream(element, {
+  const rscStream = renderToReadableStream(withPublishedParams(element), {
+    signal: req.signal,
     onError(error: unknown) {
       console.error('[timber] Error page RSC render error:', error);
     },
@@ -241,9 +327,12 @@ export async function renderDenyPageAsRsc(
   });
 
   responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
-  responseHeaders.set('Vary', 'Accept');
+  // 200, like every Flight payload response: the deny is the page in the body, and
+  // the client router — the only reader of this status — renders what it is
+  // sent. See design/04-authorization.md §"Status codes on the RSC payload
+  // path" (TIM-1495).
   return new Response(rscStream, {
-    status: deny.status,
+    status: 200,
     headers: responseHeaders,
   });
 }
@@ -261,9 +350,10 @@ export async function renderDenyPageAsRsc(
 async function renderDenyPageJson(
   deny: DenySignal,
   segments: ManifestSegmentNode[],
-  responseHeaders: Headers
+  responseHeaders: Headers,
+  maxIndex?: number
 ): Promise<Response | null> {
-  const resolution = resolveManifestStatusFile(deny.status, segments, 'json');
+  const resolution = resolveStatusFile(deny.status, segments, 'json', maxIndex);
 
   if (!resolution) {
     return null;
@@ -272,7 +362,24 @@ 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>;
+  // A .json status file that fails to load is not a usable match — return
+  // null so the caller continues to the framework default rather than
+  // rejecting out of the chain.
+  // Dev warning: deny(status, data) carries data but JSON status files are
+  // static bodies — the data is silently dropped. The same deny() would
+  // deliver the data to a .tsx file's dangerouslyPassData prop. See
+  // design/10-error-handling.md §"Status-Code File Variants".
+  if (isDebug() && deny.data !== undefined) {
+    console.warn(
+      `[timber] deny(${deny.status}, data) resolved to ${resolution.file.filePath}, ` +
+        `which is a static JSON file. The data argument is dropped — JSON status files ` +
+        `are returned verbatim with no interpolation. If you need the data in the ` +
+        `response, use a .tsx status file or a route handler (route.ts).`
+    );
+  }
+
+  const mod = await loadModule(resolution.file).catch(() => null);
+  if (!mod) return null;
   const jsonContent = mod.default ?? mod;
 
   responseHeaders.set('content-type', 'application/json; charset=utf-8');
@@ -294,10 +401,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

@@ -18,7 +18,8 @@
  * Design doc: 02-rendering-pipeline.md §"Early Hints (103)"
  */
 
-import { earlyHintsSenderAls } from './als-registry.js';
+import { earlyHintsSenderAls } from './als-registry.ts';
+import { swallow } from './logger.ts';
 
 /** 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

@@ -19,8 +19,8 @@ import {
   collectRouteCss,
   collectRouteFonts,
   collectRouteModulepreloads,
-} from './build-manifest.js';
-import type { BuildManifest } from './build-manifest.js';
+} from './build-manifest.ts';
+import type { BuildManifest } from './build-manifest.ts';
 
 /** Minimal segment shape needed for early hint collection. */
 interface SegmentWithFiles {
@@ -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' }));
     }
   }