@timber-js/app 0.2.0-alpha.7 → 0.2.0-alpha.71

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;
 
@@ -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.

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

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

@@ -5,8 +5,23 @@
  * See design/10-error-handling.md.
  */
 
-import { TimberErrorBoundary } from '#/client/error-boundary.js';
+import { TimberErrorBoundary } from '../client/error-boundary.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
+import { loadModule } from './safe-load.js';
+
+/** MDX/markdown extensions — server components that cannot be passed as function props. */
+const MDX_EXTENSIONS = new Set(['.mdx', '.md']);
+
+/**
+ * Check if a manifest file path ends with an MDX/markdown extension.
+ * MDX components are server components and cannot cross the RSC→client
+ * boundary as function props to TimberErrorBoundary.
+ */
+function isMdxFilePath(filePath: string): boolean {
+  const dotIndex = filePath.lastIndexOf('.');
+  if (dotIndex === -1) return false;
+  return MDX_EXTENSIONS.has(filePath.slice(dotIndex));
+}
 
 /**
  * Wrap an element in error boundaries defined by a route segment.
@@ -15,11 +30,17 @@ import type { ManifestSegmentNode } from './route-matcher.js';
  * 1. Specific status files (e.g., 404.tsx, 500.tsx) — highest priority at runtime
  * 2. Category catch-alls (4xx.tsx, 5xx.tsx)
  * 3. error.tsx — catches anything not matched by status files
+ *
+ * MDX status files are server components and cannot be passed as function
+ * props to TimberErrorBoundary (a 'use client' component). Instead, they
+ * are pre-rendered as elements and passed as fallbackElement. See TIM-503.
  */
 export async function wrapSegmentWithErrorBoundaries(
   segment: ManifestSegmentNode,
   element: React.ReactElement,
-  h: (...args: unknown[]) => React.ReactElement
+  h: (...args: unknown[]) => React.ReactElement,
+  /** When true, skip 4xx error boundaries — deny catching handles them in-tree. See TIM-666. */
+  skipDenyBoundaries = false
 ): Promise<React.ReactElement> {
   // Specific status files (innermost — highest priority at runtime)
   if (segment.statusFiles) {
@@ -27,13 +48,27 @@ export async function wrapSegmentWithErrorBoundaries(
       if (key !== '4xx' && key !== '5xx') {
         const status = parseInt(key, 10);
         if (!isNaN(status)) {
-          const mod = (await file.load()) as Record<string, unknown>;
-          if (mod.default) {
-            element = h(TimberErrorBoundary, {
-              fallbackComponent: mod.default,
-              status,
-              children: element,
-            });
+          // Skip 4xx boundaries when deny catching is active — the deny
+          // page is rendered by AccessGate/PageDenyBoundary instead.
+          if (skipDenyBoundaries && status >= 400 && status <= 499) continue;
+          // .catch: error boundary construction must not fail if the
+          // error page module has a syntax error — skip this boundary.
+          const mod = await loadModule(file).catch(() => null);
+          if (mod?.default) {
+            if (isMdxFilePath(file.filePath)) {
+              // MDX: pre-render as element (server component can't be a function prop)
+              element = h(TimberErrorBoundary, {
+                fallbackElement: h(mod.default as never, { status }),
+                status,
+                children: element,
+              });
+            } else {
+              element = h(TimberErrorBoundary, {
+                fallbackComponent: mod.default,
+                status,
+                children: element,
+              });
+            }
           }
         }
       }
@@ -41,14 +76,24 @@ export async function wrapSegmentWithErrorBoundaries(
 
     // Category catch-alls (4xx.tsx, 5xx.tsx)
     for (const [key, file] of Object.entries(segment.statusFiles)) {
+      if (skipDenyBoundaries && key === '4xx') continue;
       if (key === '4xx' || key === '5xx') {
-        const mod = (await file.load()) as Record<string, unknown>;
-        if (mod.default) {
-          element = h(TimberErrorBoundary, {
-            fallbackComponent: mod.default,
-            status: key === '4xx' ? 400 : 500,
-            children: element,
-          });
+        const mod = await loadModule(file).catch(() => null);
+        if (mod?.default) {
+          const categoryStatus = key === '4xx' ? 400 : 500;
+          if (isMdxFilePath(file.filePath)) {
+            element = h(TimberErrorBoundary, {
+              fallbackElement: h(mod.default as never, {}),
+              status: categoryStatus,
+              children: element,
+            });
+          } else {
+            element = h(TimberErrorBoundary, {
+              fallbackComponent: mod.default,
+              status: categoryStatus,
+              children: element,
+            });
+          }
         }
       }
     }
@@ -56,12 +101,19 @@ export async function wrapSegmentWithErrorBoundaries(
 
   // error.tsx (outermost — catches anything not matched by status files)
   if (segment.error) {
-    const mod = (await segment.error.load()) as Record<string, unknown>;
-    if (mod.default) {
-      element = h(TimberErrorBoundary, {
-        fallbackComponent: mod.default,
-        children: element,
-      });
+    const mod = await loadModule(segment.error).catch(() => null);
+    if (mod?.default) {
+      if (isMdxFilePath(segment.error.filePath)) {
+        element = h(TimberErrorBoundary, {
+          fallbackElement: h(mod.default as never, {}),
+          children: element,
+        });
+      } else {
+        element = h(TimberErrorBoundary, {
+          fallbackComponent: mod.default,
+          children: element,
+        });
+      }
     }
   }
 

package/src/server/fallback-error.ts

@@ -10,10 +10,13 @@
  * exposed to the client (design/13-security.md principle 4).
  */
 
-import type { RouteMatch } from '#/server/pipeline.js';
-import type { ManifestSegmentNode } from '#/server/route-matcher.js';
-import type { ClientBootstrapConfig } from '#/server/html-injectors.js';
-import type { LayoutEntry } from '#/server/deny-renderer.js';
+import type { RouteMatch } from './pipeline.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+import type { ClientBootstrapConfig } from './html-injectors.js';
+import type { LayoutEntry } from './deny-renderer.js';
+import type { GlobalErrorFile } from './rsc-entry/error-renderer.js';
+import { logRenderError } from './logger.js';
+import { loadModule } from './safe-load.js';
 
 /**
  * Render a fallback error page when the render pipeline throws.
@@ -27,25 +30,37 @@ export async function renderFallbackError(
   responseHeaders: Headers,
   isDev: boolean,
   rootSegment: ManifestSegmentNode,
-  clientBootstrap: ClientBootstrapConfig
+  clientBootstrap: ClientBootstrapConfig,
+  globalError?: GlobalErrorFile
 ): Promise<Response> {
   if (isDev) {
     return renderDevErrorPage(error);
   }
   // Lazy import to avoid loading error-renderer in the pipeline module
-  const { renderErrorPage } = await import('#/server/rsc-entry/error-renderer.js');
+  const { renderErrorPage } = await import('./rsc-entry/error-renderer.js');
   const segments = [rootSegment];
   const layoutComponents: LayoutEntry[] = [];
-  if (rootSegment.layout) {
-    const mod = (await rootSegment.layout.load()) as Record<string, unknown>;
-    if (mod.default) {
-      layoutComponents.push({
-        component: mod.default as (...args: unknown[]) => unknown,
-        segment: rootSegment,
-      });
+  // Wrap layout loading in try/catch — if the root layout module itself
+  // crashes (evaluation failure, syntax error, etc.), we still want to
+  // reach renderErrorPage so it can fall through to global-error.tsx
+  // (Tier 2), which renders without any layout wrapping.
+  try {
+    if (rootSegment.layout) {
+      const mod = await loadModule(rootSegment.layout);
+      if (mod.default) {
+        layoutComponents.push({
+          component: mod.default as (...args: unknown[]) => unknown,
+          segment: rootSegment,
+        });
+      }
     }
+  } catch (layoutError) {
+    // Layout failed to load — proceed without it. renderErrorPage will
+    // attempt segment-level error pages (without layout wrapping) and
+    // then fall through to global-error.tsx if those also fail.
+    logRenderError({ method: req.method, path: new URL(req.url).pathname, error: layoutError });
   }
-  const match: RouteMatch = { segments: segments as never, params: {} };
+  const match: RouteMatch = { segments: segments as never, segmentParams: {}, middlewareChain: [] };
   return renderErrorPage(
     error,
     500,
@@ -54,7 +69,8 @@ export async function renderFallbackError(
     req,
     match,
     responseHeaders,
-    clientBootstrap
+    clientBootstrap,
+    globalError
   );
 }
 

package/src/server/flight-injection-state.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared state machine types and transitions for RSC Flight injection.
+ *
+ * Both html-injectors.ts (Web Streams) and node-stream-transforms.ts
+ * (Node.js streams) implement identical state transitions — only the
+ * I/O primitives differ. This module defines the discriminated union
+ * states and the transition map once.
+ *
+ * Valid state flow:
+ *   init → streaming → flushing → done
+ *   (any) → error
+ *
+ * Suffix stripping (</body></html>) is handled by a separate
+ * createMoveSuffixStream / createNodeMoveSuffixTransform upstream
+ * in the pipeline (TIM-530). The flight injector only interleaves
+ * RSC scripts between HTML chunks — no suffix tracking needed.
+ *
+ * Design doc: 02-rendering-pipeline.md
+ */
+
+import type { TransitionMap } from '../utils/state-machine.js';
+
+// ─── States ──────────────────────────────────────────────────────────────────
+
+/** Waiting for first HTML chunk. Pull loop not started. */
+export interface InitState {
+  phase: 'init';
+}
+
+/** HTML chunks flowing, pull loop running. */
+export interface StreamingState {
+  phase: 'streaming';
+}
+
+/** HTML stream done (flush fired). Draining remaining RSC chunks. */
+export interface FlushingState {
+  phase: 'flushing';
+}
+
+/** All streams consumed. Terminal state. */
+export interface DoneState {
+  phase: 'done';
+}
+
+/** Pull loop failed. Terminal state with captured error. */
+export interface ErrorState {
+  phase: 'error';
+  error: unknown;
+}
+
+export type FlightInjectionState =
+  | InitState
+  | StreamingState
+  | FlushingState
+  | DoneState
+  | ErrorState;
+
+// ─── Events ──────────────────────────────────────────────────────────────────
+
+/** First HTML chunk arrived — start the pull loop. */
+export interface FirstChunkEvent {
+  type: 'FIRST_CHUNK';
+}
+
+/** HTML stream finished (flush/end). */
+export interface HtmlDoneEvent {
+  type: 'HTML_DONE';
+}
+
+/** RSC pull loop completed (all chunks read or stream closed). */
+export interface PullDoneEvent {
+  type: 'PULL_DONE';
+}
+
+/** RSC pull loop encountered an error. */
+export interface PullErrorEvent {
+  type: 'PULL_ERROR';
+  error: unknown;
+}
+
+export type FlightInjectionEvent = FirstChunkEvent | HtmlDoneEvent | PullDoneEvent | PullErrorEvent;
+
+// ─── Transitions ─────────────────────────────────────────────────────────────
+
+export const flightInjectionTransitions: TransitionMap<FlightInjectionState, FlightInjectionEvent> =
+  {
+    init: {
+      FIRST_CHUNK: (): StreamingState => ({ phase: 'streaming' }),
+      // Edge case: HTML stream ends immediately (empty body)
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing' }),
+    },
+    streaming: {
+      HTML_DONE: (): FlushingState => ({ phase: 'flushing' }),
+      PULL_DONE: (): StreamingState => ({ phase: 'streaming' }),
+      PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
+    },
+    flushing: {
+      PULL_DONE: (): DoneState => ({ phase: 'done' }),
+      PULL_ERROR: (_s, e): ErrorState => ({ phase: 'error', error: e.error }),
+    },
+  };
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Whether the HTML stream has finished (flush/end fired). */
+export function isHtmlDone(state: FlightInjectionState): boolean {
+  return state.phase === 'flushing' || state.phase === 'done';
+}
+
+/** Whether the RSC pull loop has completed. */
+export function isPullDone(state: FlightInjectionState): boolean {
+  return state.phase === 'done' || state.phase === 'error';
+}

package/src/server/flight-scripts.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared Flight data script generation.
+ *
+ * Both html-injectors.ts (Web Streams / dev) and node-stream-transforms.ts
+ * (Node streams / production) use this module to generate inline `<script>`
+ * tags for RSC Flight data injection.
+ *
+ * The init script goes in `<head>` as part of the HTML shell (guaranteed
+ * to execute before any streaming chunk scripts). Push scripts are emitted
+ * as RSC chunks arrive during streaming.
+ *
+ * See design/02-rendering-pipeline.md, LOCAL-415
+ */
+
+// ─── JSON Escaping ────────────────────────────────────────────────────────
+
+/**
+ * Escape a JSON string for safe embedding inside an HTML `<script>` tag.
+ *
+ * Prevents XSS via `</script>` injection and handles Unicode line/paragraph
+ * separators that are valid JSON but invalid in JS string literals (pre-ES2019).
+ */
+export function htmlEscapeJsonString(str: string): string {
+  return str
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+// ─── Script Generation ────────────────────────────────────────────────────
+
+/** The global variable name used for Flight data on the client. */
+const FLIGHT_VAR = 'self.__timber_f';
+
+/**
+ * Generate the init script that creates the Flight data array.
+ *
+ * This MUST be included in `<head>` (via headHtml) so it executes before
+ * any streaming chunk scripts arrive in `<body>`. The array is created
+ * unconditionally — no `||[]` guard needed in push scripts.
+ *
+ * Also emits the bootstrap signal [0] which tells the client that
+ * Flight data is active for this page.
+ */
+export function flightInitScript(): string {
+  return `<script>${FLIGHT_VAR}=[${htmlEscapeJsonString(JSON.stringify([0]))}]</script>`;
+}
+
+/**
+ * Generate a push script for a Flight data chunk.
+ *
+ * Normally the init script runs first (it's in `<head>`), so
+ * `self.__timber_f` already exists. However, shell-less status pages
+ * (e.g. standalone error pages) may have no `<head>` tag, so the init script
+ * never runs. The `||[]` guard ensures the array is created on first
+ * push if needed, preventing a TypeError. See TIM-559.
+ */
+export function flightChunkScript(data: string): string {
+  const escaped = htmlEscapeJsonString(JSON.stringify([1, data]));
+  return `<script>(${FLIGHT_VAR}=${FLIGHT_VAR}||[]).push(${escaped})</script>`;
+}

package/src/server/flush.ts

@@ -9,6 +9,7 @@
  */
 
 import { DenySignal, RedirectSignal, RenderError } from './primitives.js';
+import { logRenderError } from './logger.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -169,7 +170,7 @@ function handleSignal(error: unknown, responseHeaders: Headers): FlushResult {
   }
 
   // Unknown error → HTTP 500
-  console.error('[timber] Unhandled render-phase error:', error);
+  logRenderError({ method: '', path: '', error });
   return {
     response: new Response(null, {
       status: 500,

package/src/server/form-data.ts

@@ -173,4 +173,80 @@ export const coerce = {
       return undefined;
     }
   },
+
+  /**
+   * Coerce a date string to a Date object.
+   * Handles `<input type="date">` (`"2024-01-15"`), `<input type="datetime-local">`
+   * (`"2024-01-15T10:30"`), and full ISO 8601 strings.
+   * - Valid date string → `Date`
+   * - `""` / `undefined` / `null` → `undefined`
+   * - Invalid date strings → `undefined` (schema validation will catch this)
+   * - Impossible dates that `new Date()` silently normalizes (e.g. Feb 31) → `undefined`
+   */
+  date(value: unknown): Date | undefined {
+    if (value === undefined || value === null || value === '') return undefined;
+    if (value instanceof Date) return value;
+    if (typeof value !== 'string') return undefined;
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) return undefined;
+
+    // Overflow detection: extract Y/M/D from the input string and verify
+    // they match the parsed Date components. new Date('2024-02-31') silently
+    // normalizes to March 2nd — we reject such inputs.
+    const ymdMatch = value.match(/^(\d{4})-(\d{2})-(\d{2})/);
+    if (ymdMatch) {
+      const inputYear = Number(ymdMatch[1]);
+      const inputMonth = Number(ymdMatch[2]);
+      const inputDay = Number(ymdMatch[3]);
+
+      // Use UTC methods for date-only and Z-suffixed strings to avoid
+      // timezone offset shifting the day. For datetime-local (no Z suffix),
+      // the Date constructor parses in local time, so use local methods.
+      const isUTC = value.length === 10 || value.endsWith('Z');
+      const parsedYear = isUTC ? date.getUTCFullYear() : date.getFullYear();
+      const parsedMonth = isUTC ? date.getUTCMonth() + 1 : date.getMonth() + 1;
+      const parsedDay = isUTC ? date.getUTCDate() : date.getDate();
+
+      if (inputYear !== parsedYear || inputMonth !== parsedMonth || inputDay !== parsedDay) {
+        return undefined;
+      }
+    }
+
+    return date;
+  },
+
+  /**
+   * Create a File coercion function with optional size and mime type validation.
+   * Returns the File if valid, `undefined` otherwise.
+   *
+   * ```ts
+   * // Basic — just checks it's a real File
+   * z.preprocess(coerce.file(), z.instanceof(File))
+   *
+   * // With constraints
+   * z.preprocess(
+   *   coerce.file({ maxSize: 5 * 1024 * 1024, accept: ['image/png', 'image/jpeg'] }),
+   *   z.instanceof(File)
+   * )
+   * ```
+   */
+  file(options?: { maxSize?: number; accept?: string[] }): (value: unknown) => File | undefined {
+    return (value: unknown): File | undefined => {
+      if (value === undefined || value === null || value === '') return undefined;
+      if (!(value instanceof File)) return undefined;
+
+      // Empty file input (no selection): browsers submit File with name="" and size=0
+      if (value.size === 0 && value.name === '') return undefined;
+
+      if (options?.maxSize !== undefined && value.size > options.maxSize) {
+        return undefined;
+      }
+
+      if (options?.accept !== undefined && !options.accept.includes(value.type)) {
+        return undefined;
+      }
+
+      return value;
+    };
+  },
 };