@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.81

package/src/server/deny-page-resolver.ts

@@ -0,0 +1,154 @@
+/**
+ * Deny Page Resolver — resolves status-code file components for in-tree deny handling.
+ *
+ * When AccessGate or PageDenyBoundary catches a DenySignal, they need to
+ * render the matching deny page (403.tsx, 4xx.tsx, error.tsx) as a normal
+ * element in the React tree. This module resolves the deny page chain from
+ * the segment chain — a list of fallback components ordered by specificity.
+ *
+ * The chain is built during buildRouteElement and passed as a prop to
+ * AccessGate and PageDenyBoundary. At catch time, the first matching
+ * component is rendered.
+ *
+ * See design/10-error-handling.md §"Status-Code Files", TIM-666.
+ */
+
+import { createElement } from 'react';
+
+import type { ManifestSegmentNode } from './route-matcher.js';
+import { loadModule } from './safe-load.js';
+import { requestContextAls } from './als-registry.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;
+}
+
+// ─── Resolver ─────────────────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ─── 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;
+}
+
+// ─── ALS Helper ───────────────────────────────────────────────────────────
+
+/**
+ * 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,21 @@
  */
 
 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 { 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 { 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';
@@ -108,7 +111,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 +119,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 +126,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 +161,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,
+    params: match.segmentParams,
     searchParams: Object.fromEntries(new URL(req.url).searchParams),
     statusCode: deny.status,
     responseHeaders,
-    headHtml,
+    headHtml: headHtml + flightInitScript(),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
     rscStream: inlineStream,
   };
@@ -206,7 +197,7 @@ export async function renderDenyPageAsRsc(
     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 +206,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, {
@@ -272,7 +258,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');

package/src/server/dev-holding-server.ts

@@ -0,0 +1,185 @@
+/**
+ * Dev holding server — serves a loading page while Vite initializes.
+ *
+ * When `timber dev` (or `vite dev`) starts, Vite takes several seconds
+ * to initialize all plugins, scan routes, and boot the RSC environment.
+ * During this window, the port is unbound and browsers get
+ * ERR_CONNECTION_REFUSED.
+ *
+ * This module creates a lightweight HTTP server that binds the port
+ * immediately and serves a branded holding page with auto-refresh.
+ * Once Vite is ready, the holding server is closed and Vite's server
+ * takes over the port.
+ *
+ * The holding server is started in rootSync's config() hook (the
+ * earliest Vite plugin lifecycle point where we know the port) and
+ * closed in timber-dev-server's configureServer() hook (the last
+ * plugin, right before Vite calls server.listen()).
+ *
+ * Browser requests (Accept: text/html) get the HTML holding page.
+ * API requests (Accept: application/json) get a 503 JSON response.
+ * All responses include Retry-After: 1.
+ *
+ * See design/21-dev-server.md, TIM-665.
+ */
+
+import http from 'node:http';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface HoldingServer {
+  /**
+   * Start listening on the given port.
+   * Returns the actual bound port (useful when port is 0 for OS assignment).
+   */
+  listen(port: number): Promise<number>;
+
+  /** Gracefully close the server and stop accepting connections. */
+  close(): Promise<void>;
+}
+
+// ─── Holding Page HTML ────────────────────────────────────────────────────
+
+/**
+ * Minimal self-contained HTML holding page.
+ *
+ * Matches the timber.js docs site theme:
+ * - Light mode: warm stone/grain background, timber/bark text
+ * - Dark mode: stone-900 background, stone-200 text
+ * - 🪵 timber.js branding
+ *
+ * Uses meta-refresh (1s) for auto-reload — works without JavaScript.
+ * Inline CSS only, no external dependencies.
+ */
+const HOLDING_PAGE_HTML = [
+  '<!DOCTYPE html>',
+  '<html lang="en">',
+  '<head>',
+  '  <meta charset="utf-8">',
+  '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+  '  <meta http-equiv="refresh" content="2">',
+  '  <title>timber — starting...</title>',
+  '  <style>',
+  '    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }',
+  '    body {',
+  '      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;',
+  '      background: #fafaf9;',
+  '      color: #44403c;',
+  '      display: flex;',
+  '      align-items: center;',
+  '      justify-content: center;',
+  '      min-height: 100vh;',
+  '      -webkit-font-smoothing: antialiased;',
+  '    }',
+  '    @media (prefers-color-scheme: dark) {',
+  '      body { background: #1c1917; color: #e7e5e4; }',
+  '      .message { color: #a8a29e; }',
+  '      .spinner { border-color: #57534e; border-top-color: #a1887f; }',
+  '      .logo { color: #e7e5e4; }',
+  '    }',
+  '    .container { text-align: center; padding: 2rem; }',
+  '    .logo {',
+  '      font-size: 1.5rem;',
+  '      font-weight: 700;',
+  '      letter-spacing: -0.02em;',
+  '      color: #5c3d2e;',
+  '      margin-bottom: 1.5rem;',
+  '    }',
+  '    .message {',
+  '      font-size: 0.95rem;',
+  '      color: #78716c;',
+  '      margin-bottom: 2rem;',
+  '    }',
+  '    .spinner {',
+  '      width: 24px;',
+  '      height: 24px;',
+  '      border: 2.5px solid #d7ccc8;',
+  '      border-top-color: #6d4c41;',
+  '      border-radius: 50%;',
+  '      animation: spin 0.8s linear infinite;',
+  '      margin: 0 auto;',
+  '    }',
+  '    @keyframes spin { to { transform: rotate(360deg); } }',
+  '  </style>',
+  '</head>',
+  '<body>',
+  '  <div class="container">',
+  '    <div class="logo">\u{1FAB5} timber.js</div>',
+  '    <p class="message">Dev server starting&hellip;</p>',
+  '    <div class="spinner"></div>',
+  '  </div>',
+  '</body>',
+  '</html>',
+].join('\n');
+
+// ─── Factory ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a holding HTTP server that serves a loading page during startup.
+ *
+ * Usage (inside Vite plugin):
+ * ```ts
+ * // In config() hook — earliest point where port is known
+ * const holding = createHoldingServer();
+ * holding.listen(config.server?.port ?? 5173);
+ *
+ * // In last plugin's configureServer() — wrap listen for seamless handoff
+ * const originalListen = server.listen.bind(server);
+ * server.listen = async (...args) => {
+ *   await holding.close();
+ *   return originalListen(...args);
+ * };
+ * ```
+ */
+export function createHoldingServer(): HoldingServer {
+  const server = http.createServer((req, res) => {
+    const accept = req.headers.accept ?? '';
+
+    // API requests: JSON 503
+    if (accept.includes('application/json') && !accept.includes('text/html')) {
+      res.writeHead(503, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Retry-After': '1',
+        'Cache-Control': 'no-store',
+      });
+      res.end(
+        JSON.stringify({
+          error: 'Service Unavailable',
+          message: 'timber dev server is starting — please retry shortly',
+        })
+      );
+      return;
+    }
+
+    // Browser and other requests: HTML holding page
+    res.writeHead(503, {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Retry-After': '1',
+      'Cache-Control': 'no-store',
+    });
+    res.end(HOLDING_PAGE_HTML);
+  });
+
+  return {
+    listen(port: number): Promise<number> {
+      return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, () => {
+          server.removeListener('error', reject);
+          const addr = server.address();
+          const boundPort = typeof addr === 'object' && addr ? addr.port : port;
+          resolve(boundPort);
+        });
+      });
+    },
+
+    close(): Promise<void> {
+      return new Promise((resolve, reject) => {
+        server.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    },
+  };
+}

package/src/server/dev-warnings.ts

@@ -25,7 +25,6 @@ export const WarningId = {
   REDIRECT_IN_SUSPENSE: 'REDIRECT_IN_SUSPENSE',
   REDIRECT_IN_ACCESS: 'REDIRECT_IN_ACCESS',
   STATIC_REQUEST_API: 'STATIC_REQUEST_API',
-  CACHE_REQUEST_PROPS: 'CACHE_REQUEST_PROPS',
   SLOW_SLOT_NO_SUSPENSE: 'SLOW_SLOT_NO_SUSPENSE',
 } as const;
 
@@ -111,7 +110,7 @@ export function warnSuspenseWrappingChildren(layoutFile: string): void {
     'warn',
     `Layout at ${layoutFile} wraps {children} in <Suspense>. ` +
       'This prevents child pages from setting HTTP status codes. ' +
-      'Use useNavigationPending() for loading states instead.'
+      'Use usePendingNavigation() for loading states instead.'
   );
 }
 
@@ -179,7 +178,7 @@ export function warnRedirectInAccess(accessFile: string, line?: number): void {
 }
 
 /**
- * Warn when cookies() or headers() is called during a static build.
+ * Warn when getCookies() or getHeaders() is called during a static build.
  *
  * In output: 'static' mode, there is no per-request context — these APIs
  * read build-time values only. This is almost always a mistake.
@@ -197,33 +196,8 @@ export function warnStaticRequestApi(api: 'cookies' | 'headers', file: string):
   );
 }
 
-/**
- * Warn when a "use cache" component receives request-specific props.
- *
- * Cached components should not depend on per-request data — a userId or
- * sessionId in the props means the cache will either be ineffective
- * (key per user) or dangerous (serve one user's data to another).
- *
- * @param componentName - Name of the cached component
- * @param propName - Name of the suspicious prop
- * @param file - Relative path to the component file
- * @param line - Line number
- */
-export function warnCacheRequestProps(
-  componentName: string,
-  propName: string,
-  file: string,
-  line?: number
-): void {
-  const location = line ? `${file}:${line}` : file;
-  emitOnce(
-    WarningId.CACHE_REQUEST_PROPS,
-    `${componentName}:${propName}:${location}`,
-    'warn',
-    `Cached component ${componentName} receives prop "${propName}" which appears request-specific. ` +
-      'Cached components should not depend on per-request data.'
-  );
-}
+// NOTE: warnCacheRequestProps removed — 'use cache' directive is a future feature.
+// See design/06-caching.md.
 
 /**
  * Warn when a parallel slot resolves slowly without a <Suspense> wrapper.
@@ -245,25 +219,6 @@ export function warnSlowSlotWithoutSuspense(slotName: string, durationMs: number
   );
 }
 
-// ─── Legacy aliases ─────────────────────────────────────────────────────────
-
-/** @deprecated Use warnStaticRequestApi instead */
-export const warnDynamicApiInStaticBuild = warnStaticRequestApi;
-
-/** @deprecated Use warnRedirectInAccess instead */
-export function warnRedirectInSlotAccess(slotName: string): void {
-  warnRedirectInAccess(`${slotName}/access.ts`);
-}
-
-/** @deprecated Use warnDenyInSuspense / warnRedirectInSuspense instead */
-export function warnDenyAfterFlush(signal: 'deny' | 'redirect'): void {
-  if (signal === 'deny') {
-    warnDenyInSuspense('unknown');
-  } else {
-    warnRedirectInSuspense('unknown');
-  }
-}
-
 // ─── Testing ────────────────────────────────────────────────────────────────
 
 /**

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' }));
     }
   }