@timber-js/app 0.2.0-alpha.5 → 0.2.0-alpha.50

package/src/server/access-gate.tsx

@@ -17,6 +17,7 @@ import { DenySignal, RedirectSignal } from './primitives.js';
 import type { AccessGateProps, SlotAccessGateProps, ReactElement } from './tree-builder.js';
 import { withSpan, setSpanAttribute } from './tracing.js';
 import { isDebug } from './debug.js';
+import { rawSegmentParams } from './request-context.js';
 
 // ─── AccessGate ─────────────────────────────────────────────────────────────
 
@@ -35,7 +36,7 @@ import { isDebug } from './debug.js';
  * gets the same data by calling the same cached functions (React.cache dedup).
  */
 export function AccessGate(props: AccessGateProps): ReactElement | Promise<ReactElement> {
-  const { accessFn, params, searchParams, segmentName, verdict, children } = props;
+  const { accessFn, segmentName, verdict, children } = props;
 
   // Fast path: replay pre-computed verdict from the pre-render pass.
   // This is synchronous — Suspense boundaries cannot interfere with the
@@ -52,7 +53,7 @@ export function AccessGate(props: AccessGateProps): ReactElement | Promise<React
 
   // Fallback: call accessFn directly (used by tree-builder.ts which
   // doesn't run a pre-render pass, and for backward compat).
-  return accessGateFallback(accessFn, params, searchParams, segmentName, children);
+  return accessGateFallback(accessFn, segmentName, children);
 }
 
 /**
@@ -61,14 +62,13 @@ export function AccessGate(props: AccessGateProps): ReactElement | Promise<React
  */
 async function accessGateFallback(
   accessFn: AccessGateProps['accessFn'],
-  params: AccessGateProps['params'],
-  searchParams: AccessGateProps['searchParams'],
   segmentName: AccessGateProps['segmentName'],
   children: ReactElement
 ): Promise<ReactElement> {
   await withSpan('timber.access', { 'timber.segment': segmentName ?? 'unknown' }, async () => {
     try {
-      await accessFn({ params, searchParams });
+      const params = await rawSegmentParams();
+      await accessFn({ params });
       await setSpanAttribute('timber.result', 'pass');
     } catch (error: unknown) {
       if (error instanceof DenySignal) {
@@ -96,18 +96,28 @@ async function accessGateFallback(
  * The HTTP status code is unaffected — slot denial is a UI concern, not
  * a protocol concern. The parent layout and sibling slots still render.
  *
+ * DeniedComponent is passed instead of a pre-built element so that
+ * DenySignal.data can be forwarded as the dangerouslyPassData prop
+ * and the slot name can be passed as the slot prop. See TIM-488.
+ *
  * redirect() in slot access.ts is a dev-mode error — redirecting from a
  * slot doesn't make architectural sense.
  */
 export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactElement> {
-  const { accessFn, params, searchParams, deniedFallback, defaultFallback, children } = props;
+  const { accessFn, DeniedComponent, slotName, createElement, defaultFallback, children } = props;
 
   try {
-    await accessFn({ params, searchParams });
+    const params = await rawSegmentParams();
+    await accessFn({ params });
   } catch (error: unknown) {
     // DenySignal → graceful degradation (denied.tsx → default.tsx → null)
+    // Build the denied element dynamically so DenySignal.data is forwarded.
     if (error instanceof DenySignal) {
-      return deniedFallback ?? defaultFallback ?? null;
+      return (
+        buildDeniedFallback(DeniedComponent, slotName, error.data, createElement) ??
+        defaultFallback ??
+        null
+      );
     }
 
     // RedirectSignal in slot access → dev-mode error.
@@ -123,7 +133,11 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
         );
       }
       // In production, treat as a deny — render fallback rather than crash.
-      return deniedFallback ?? defaultFallback ?? null;
+      return (
+        buildDeniedFallback(DeniedComponent, slotName, undefined, createElement) ??
+        defaultFallback ??
+        null
+      );
     }
 
     // Unhandled error — re-throw so error boundaries can catch it.
@@ -141,3 +155,20 @@ export async function SlotAccessGate(props: SlotAccessGateProps): Promise<ReactE
   // Access passed — render slot content.
   return children;
 }
+
+/**
+ * Build the denied fallback element dynamically with DenySignal data.
+ * Returns null if no DeniedComponent is available.
+ */
+function buildDeniedFallback(
+  DeniedComponent: SlotAccessGateProps['DeniedComponent'],
+  slotName: string,
+  data: unknown,
+  createElement: SlotAccessGateProps['createElement']
+): ReactElement | null {
+  if (!DeniedComponent) return null;
+  return createElement(DeniedComponent, {
+    slot: slotName,
+    dangerouslyPassData: data,
+  });
+}

package/src/server/action-client.ts

@@ -295,8 +295,14 @@ export function createActionClient<TCtx = Record<string, never>>(
         // Determine input — either FormData (from useActionState) or direct arg
         let rawInput: unknown;
         if (args.length === 2 && args[1] instanceof FormData) {
-          // Called as (prevState, formData) by React useActionState
+          // Called as (prevState, formData) by React useActionState (with-JS path)
           rawInput = schema ? parseFormData(args[1]) : args[1];
+        } else if (args.length === 1 && args[0] instanceof FormData) {
+          // No-JS path: React's decodeAction binds FormData as the sole argument.
+          // The form POSTs without JavaScript, decodeAction resolves the server
+          // reference and binds the FormData, then executeAction calls fn() with
+          // no additional args — so the bound FormData arrives as args[0].
+          rawInput = schema ? parseFormData(args[0]) : args[0];
         } else {
           // Direct call: action(input)
           rawInput = args[0];

package/src/server/action-encryption.ts

@@ -0,0 +1,144 @@
+/**
+ * Server action bound args encryption utilities.
+ *
+ * Provides key management for the RSC plugin's built-in bound args encryption.
+ * The RSC plugin (@vitejs/plugin-rsc) handles the actual encrypt/decrypt via
+ * AES-256-GCM — this module handles:
+ *
+ * 1. Key sourcing: auto-generated at build time (embedded in bundle), overridable
+ *    via env var for cross-build key sharing (rolling/blue-green deployments)
+ * 2. Build-time key expression generation for the RSC plugin's `defineEncryptionKey`
+ *
+ * Encryption is always on in production. In dev mode, it's on by default
+ * (matching the RSC plugin's behavior) but can be disabled for debugging.
+ *
+ * ## Known Security Considerations
+ *
+ * 1. **defineEncryptionKey is a raw JS expression.** The RSC plugin inlines it
+ *    verbatim into generated code. We only emit the hardcoded string
+ *    `process.env.TIMBER_ACTIONS_ENCRYPTION_KEY` — never user-controlled input.
+ *    If this function is ever extended to accept configurable env var names,
+ *    the expression MUST be validated against a safe pattern.
+ *
+ * 2. **Key material lives in GC-visible JS strings.** `atob()` decodes the key
+ *    into a regular JavaScript string on the V8 heap. JavaScript has no
+ *    `SecureString` or memory-zeroing primitive — this is an inherent platform
+ *    limitation. Acceptable for web server use; would need review for FIPS.
+ *
+ * 3. **TIMBER_ACTIONS_ENCRYPTION_KEY must be set at both build time and runtime.**
+ *    At build time, we validate the key format and emit a runtime expression.
+ *    If the env var is present at build time but missing at runtime, the server
+ *    will crash on first action invocation with an opaque `atob(undefined)` error.
+ *    If the env var is present at runtime but was absent at build time, the RSC
+ *    plugin will have generated its own key and the env var is silently ignored.
+ *
+ * See design/08-forms-and-actions.md §"Security"
+ * See design/13-security.md
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+/** User-facing configuration for action bound args encryption. */
+export interface ActionEncryptionConfig {
+  /**
+   * Disable encryption in dev mode for easier debugging.
+   * Has no effect in production — encryption is always enabled.
+   * Default: false (encryption is on in dev too).
+   */
+  disableInDev?: boolean;
+}
+
+// ─── Key Resolution ───────────────────────────────────────────────────────
+
+/**
+ * Regex for safe `defineEncryptionKey` expressions.
+ *
+ * The RSC plugin inlines this expression verbatim into generated JavaScript.
+ * We restrict it to `process.env.<UPPER_SNAKE_CASE>` to prevent code injection.
+ * See "Known Security Considerations" at the top of this file.
+ */
+const SAFE_KEY_EXPR = /^process\.env\.[A-Z_][A-Z0-9_]*$/;
+
+/**
+ * Build the `defineEncryptionKey` expression for the RSC plugin.
+ *
+ * The RSC plugin accepts a JavaScript expression string that will be
+ * inlined into the encryption runtime module. At runtime, this expression
+ * must evaluate to the base64-encoded encryption key.
+ *
+ * Priority:
+ * 1. `TIMBER_ACTIONS_ENCRYPTION_KEY` env var (for cross-build key sharing
+ *    in rolling/blue-green deployments)
+ * 2. Auto-generated at build time (RSC plugin default — embedded in bundle,
+ *    consistent across all instances of the same build)
+ *
+ * For env var keys, we generate a runtime expression that reads the env var.
+ * For auto-generated keys, we return undefined and let the RSC plugin handle it.
+ */
+export function resolveEncryptionKeyExpression(): string | undefined {
+  // Check for env var override — used for cross-build key sharing where
+  // multiple builds must agree on the same encryption key.
+  const envKey = process.env.TIMBER_ACTIONS_ENCRYPTION_KEY;
+  if (envKey) {
+    // Validate the key format (must be base64-encoded 32-byte key)
+    validateKeyFormat(envKey);
+
+    // Return a runtime expression that reads the env var at startup.
+    // This ensures the key is read at runtime, not embedded in the build.
+    const expr = 'process.env.TIMBER_ACTIONS_ENCRYPTION_KEY';
+
+    // Defense-in-depth: validate the expression matches our safe pattern.
+    // This is redundant today (hardcoded string), but protects against
+    // future refactors that might make the expression configurable.
+    if (!SAFE_KEY_EXPR.test(expr)) {
+      throw new Error(`Unsafe encryption key expression: ${expr}`);
+    }
+
+    return expr;
+  }
+
+  // No override — let the RSC plugin auto-generate a per-build key
+  return undefined;
+}
+
+/**
+ * Determine whether action encryption should be enabled.
+ *
+ * Encryption is always enabled in production. In dev mode, it's enabled
+ * by default but can be disabled via config for debugging.
+ */
+export function shouldEnableEncryption(isDev: boolean, config?: ActionEncryptionConfig): boolean {
+  if (!isDev) return true; // Always on in production
+  if (config?.disableInDev) return false; // Opt-out in dev
+  return true; // On by default in dev too
+}
+
+// ─── Key Validation ───────────────────────────────────────────────────────
+
+/**
+ * Validate that a key string is a valid base64-encoded 256-bit key.
+ * Throws a descriptive error if the key is malformed.
+ */
+export function validateKeyFormat(key: string): void {
+  // Decode base64 and check length (32 bytes = 256 bits)
+  try {
+    const decoded = atob(key);
+    const bytes = decoded.length;
+    if (bytes !== 32) {
+      throw new Error(
+        `TIMBER_ACTIONS_ENCRYPTION_KEY must be a base64-encoded 256-bit (32-byte) key. ` +
+          `Got ${bytes} bytes. Generate one with: ` +
+          `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`
+      );
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('TIMBER_ACTIONS_ENCRYPTION_KEY')) {
+      throw error;
+    }
+    throw new Error(
+      `TIMBER_ACTIONS_ENCRYPTION_KEY is not valid base64. ` +
+        `Generate a key with: ` +
+        `node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`
+    );
+  }
+}

package/src/server/action-handler.ts

@@ -31,6 +31,8 @@ import { handleActionError } from './action-client.js';
 import { enforceBodyLimits, enforceFieldLimit, type BodyLimitsConfig } from './body-limits.js';
 import { parseFormData } from './form-data.js';
 import type { FormFlashData } from './form-flash.js';
+import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
+import { logActionError } from './logger.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -90,6 +92,21 @@ export async function handleActionRequest(
   req: Request,
   config: ActionDispatchConfig
 ): Promise<Response | FormRerender | null> {
+  // Version skew detection — reject actions from stale clients (TIM-446).
+  // On mismatch, return a structured RSC error response that the client
+  // handles by showing a brief "App updated" message and reloading.
+  const skewCheck = checkVersionSkew(req);
+  if (!skewCheck.ok) {
+    const reloadHeaders = new Headers({
+      'Content-Type': RSC_CONTENT_TYPE,
+    });
+    applyReloadHeaders(reloadHeaders);
+    // Return the reload signal as an RSC stream so createFromFetch can
+    // decode it. The client checks X-Timber-Reload before processing.
+    const rscStream = renderToReadableStream({ _versionSkew: true });
+    return new Response(rscStream, { status: 200, headers: reloadHeaders });
+  }
+
   // CSRF validation — reject cross-origin mutation requests.
   const csrfResult = validateCsrf(req, config.csrf);
   if (!csrfResult.ok) {
@@ -177,7 +194,7 @@ async function handleRscAction(
     });
   } catch (error) {
     // Log full error server-side for debugging
-    console.error('[timber] server action error:', error);
+    logActionError({ method: req.method, path: new URL(req.url).pathname, error });
 
     // Return structured error response — ActionError gets its code/data,
     // unexpected errors get sanitized { code: 'INTERNAL_ERROR' }
@@ -293,7 +310,7 @@ async function handleFormAction(
       renderer: config.revalidateRenderer,
     });
   } catch (error) {
-    console.error('[timber] server action error:', error);
+    logActionError({ method: req.method, path: new URL(req.url).pathname, error });
 
     // Return the error as flash data for re-render.
     // handleActionError produces { serverError } for ActionErrors

package/src/server/als-registry.ts

@@ -39,11 +39,25 @@ export interface RequestContextStore {
   /** Original (pre-overlay) frozen headers, kept for overlay merging. */
   originalHeaders: Headers;
   /**
-   * Promise resolving to the route's typed search params (when search-params.ts
-   * exists) or to the raw URLSearchParams. Stored as a Promise so the framework
-   * can later support partial pre-rendering where param resolution is deferred.
+   * Promise resolving to the raw URLSearchParams for the current request.
+   * To get typed parsed params, import a search params definition and
+   * call `.parse(searchParams())`.
    */
-  searchParamsPromise: Promise<URLSearchParams | Record<string, unknown>>;
+  searchParamsPromise: Promise<URLSearchParams>;
+  /**
+   * Raw search string from the request URL (e.g. "?foo=bar&baz=1").
+   * Available synchronously for use in `redirect()` with `preserveSearchParams`.
+   */
+  searchString: string;
+  /**
+   * Promise resolving to the coerced segment params for the current request.
+   * Set by the pipeline after route matching and param coercion, before
+   * middleware and rendering. Pages and layouts read params via
+   * `rawSegmentParams()` instead of receiving them as a prop.
+   *
+   * See design/07-routing.md §"params.ts — Convention File for Typed Params"
+   */
+  segmentParamsPromise?: Promise<Record<string, string | string[]>>;
   /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
   cookieJar: Map<string, CookieEntry>;
   /** Whether the response has flushed (headers committed). */

package/src/server/build-manifest.ts

@@ -95,10 +95,10 @@ export function buildCssLinkTags(cssUrls: string[]): string {
  * into 103 Early Hints responses. This avoids platform-specific 103
  * sending code.
  *
- * Example output: `</assets/root.css>; rel=preload; as=style, </assets/page.css>; rel=preload; as=style`
+ * Example output: `</assets/root.css>; as=style; rel=preload, </assets/page.css>; as=style; rel=preload`
  */
 export function buildLinkHeaders(cssUrls: string[]): string {
-  return cssUrls.map((url) => `<${url}>; rel=preload; as=style`).join(', ');
+  return cssUrls.map((url) => `<${url}>; as=style; rel=preload`).join(', ');
 }
 
 // ─── Font utilities ──────────────────────────────────────────────────────
@@ -153,10 +153,10 @@ export function buildFontPreloadTags(fonts: ManifestFontEntry[]): string {
  *
  * Cloudflare CDN converts Link headers with rel=preload into 103 Early Hints.
  *
- * Example: `</fonts/inter.woff2>; rel=preload; as=font; crossorigin`
+ * Example: `</fonts/inter.woff2>; as=font; rel=preload; crossorigin`
  */
 export function buildFontLinkHeaders(fonts: ManifestFontEntry[]): string {
-  return fonts.map((f) => `<${f.href}>; rel=preload; as=font; crossorigin`).join(', ');
+  return fonts.map((f) => `<${f.href}>; as=font; rel=preload; crossorigin`).join(', ');
 }
 
 // ─── JS chunk utilities ──────────────────────────────────────────────────

package/src/server/compress.ts

@@ -160,15 +160,33 @@ export function compressResponse(request: Request, response: Response): Response
   });
 }
 
-// ─── Gzip (CompressionStream API) ────────────────────────────────────────
+// ─── Gzip (node:zlib with Z_SYNC_FLUSH) ──────────────────────────────────
+//
+// Uses node:zlib's createGzip with Z_SYNC_FLUSH so each chunk is flushed
+// to the output immediately. The Web Platform CompressionStream API buffers
+// internally and does NOT flush per-chunk — this kills streaming because
+// the browser doesn't receive the HTML shell until the gzip stream closes
+// (i.e. after all Suspense boundaries resolve).
+//
+// Z_SYNC_FLUSH adds ~2–5% size overhead vs Z_NO_FLUSH but preserves
+// correct streaming behavior: the shell renders instantly, Suspense
+// fallbacks are visible immediately, and streamed content appears
+// progressively.
+
+import { createGzip, constants } from 'node:zlib';
+import { Readable } from 'node:stream';
 
 /**
- * Compress a ReadableStream with gzip using the Web Platform CompressionStream API.
- * Available in Node 18+, Bun, and Deno — no npm dependency needed.
+ * Compress a ReadableStream with gzip, flushing each chunk immediately.
+ *
+ * Uses node:zlib's createGzip with Z_SYNC_FLUSH to ensure each HTML chunk
+ * (shell, Suspense resolution, RSC payload) is delivered to the browser
+ * as soon as it's available — preserving streaming semantics.
  */
 function compressWithGzip(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
-  const compressionStream = new CompressionStream('gzip');
-  // Cast needed: CompressionStream's WritableStream<BufferSource> type is wider
-  // than ReadableStream's Uint8Array, but Uint8Array is a valid BufferSource.
-  return body.pipeThrough(compressionStream as unknown as TransformStream<Uint8Array, Uint8Array>);
+  const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+  const nodeInput = Readable.fromWeb(body as import('stream/web').ReadableStream);
+  nodeInput.pipe(gzip);
+
+  return Readable.toWeb(gzip) as ReadableStream<Uint8Array>;
 }

package/src/server/debug.ts

@@ -48,7 +48,7 @@
  *
  * This is the ONLY function that should gate client-visible dev behavior:
  * - Dev error pages with stack traces
- * - Detailed Server-Timing response headers
+ * - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
  * - Error messages in action `INTERNAL_ERROR` payloads
  * - Pipeline error handler wiring (Vite overlay)
  *

package/src/server/default-logger.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 {
+      if (isDevMode()) return;
+      const fields = formatDataFields(data);
+      // Use process.stderr.write for consistent output (no extra newline handling)
+      process.stderr.write(`[timber] ${padLevel('ERROR')}  ${msg}${fields}\n`);
+    },
+
+    warn(msg: string, data?: Record<string, unknown>): void {
+      if (isDevMode()) return;
+      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-renderer.ts

@@ -26,6 +26,7 @@ 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';
 
@@ -178,7 +179,7 @@ export async function renderDenyPage(
     searchParams: Object.fromEntries(new URL(req.url).searchParams),
     statusCode: deny.status,
     responseHeaders,
-    headHtml,
+    headHtml: headHtml + flightInitScript(),
     bootstrapScriptContent: clientBootstrap.bootstrapScriptContent,
     rscStream: inlineStream,
   };

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