@timber-js/app 0.2.0-alpha.208 → 0.2.0-alpha.209

package/src/server/default-logger.ts

@@ -11,7 +11,8 @@
  *   [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)
+ * - `info` and `debug` suppressed in dev mode (dev logging handles them);
+ *   `warn` and `error` are always written (TIM-555)
  * - `debug` suppressed unless TIMBER_DEBUG is set
  * - Replaced entirely when a custom logger is set via `setLogger()`
  *

package/src/server/deny-boundary.ts

@@ -39,8 +39,9 @@ import { ErrorReconstituter } from '../client/error-reconstituter.tsx';
 import type { SerializableError } from '../client/error-reconstituter.tsx';
 import { StatusPageMarker } from '../client/status-page-marker.tsx';
 import { requestContextAls } from './als-registry.ts';
-import { isDenySignal, DenySignal } from './primitives.ts';
-import { loadModule } from './safe-load.ts';
+import { DenySignal } from './primitives.ts';
+import { isDenySignal } from './signal-identity.ts';
+import { loadFallbackModule } from './pipeline-helpers.ts';
 import type { ManifestLoader } from './safe-load.ts';
 import { withSpan } from './tracing.ts';
 import { isValidElementType, type LoadedComponent } from './utils/element-type.ts';
@@ -136,8 +137,12 @@ export type DenyPlacement =
  *
  * See TIM-1356.
  */
-async function loadChainComponent(file: ManifestLoader): Promise<LoadedComponent | null> {
-  const mod = await loadModule(file).catch(() => null);
+async function loadChainComponent(
+  file: ManifestLoader,
+  req: Request,
+  segments: ManifestSegmentNode[]
+): Promise<LoadedComponent | null> {
+  const mod = await loadFallbackModule(file, req, segments);
   return isValidElementType(mod?.default) ? mod.default : null;
 }
 
@@ -159,7 +164,8 @@ async function loadChainComponent(file: ManifestLoader): Promise<LoadedComponent
 export async function buildDenyPageChain(
   segments: ManifestSegmentNode[],
   startIndex: number,
-  segmentKeys: string[]
+  segmentKeys: string[],
+  req: Request
 ): Promise<DenyPageEntry[]> {
   const chain: DenyPageEntry[] = [];
 
@@ -176,7 +182,7 @@ export async function buildDenyPageChain(
       if (key !== '4xx' && key !== '5xx') {
         const status = parseInt(key, 10);
         if (!isNaN(status)) {
-          const component = await loadChainComponent(file);
+          const component = await loadChainComponent(file, req, segments);
           if (component) {
             chain.push({
               status,
@@ -193,7 +199,7 @@ export async function buildDenyPageChain(
     // Category catch-alls (4xx.tsx, 5xx.tsx)
     for (const [key, file] of Object.entries(segment.statusFiles)) {
       if (key === '4xx' || key === '5xx') {
-        const component = await loadChainComponent(file);
+        const component = await loadChainComponent(file, req, segments);
         if (component) {
           const categoryStatus = key === '4xx' ? 400 : 500;
           chain.push({
@@ -214,7 +220,7 @@ export async function buildDenyPageChain(
   for (let i = startIndex; i >= 0; i--) {
     const segment = segments[i];
     if (segment.error) {
-      const component = await loadChainComponent(segment.error);
+      const component = await loadChainComponent(segment.error, req, segments);
       if (component) {
         chain.push({
           status: null,
@@ -394,11 +400,17 @@ function renderDenyPage(
  * Otherwise it throws — annotated with `ownerKey` when an ancestor owns the
  * file, bare when nothing matched at all.
  *
- * `setDenyStatus` runs on the hoist path too, and must run *before* the
- * throw: on the document path the hoisted row fails the Fizz shell and the
- * re-render fallback serves the page, and the ALS status is what the
- * pipeline commits for it. The RSC payload path never reads it — a Flight
- * payload response is always 200 and the row itself carries the deny (TIM-1495).
+ * `setDenyStatus` runs on the hoist path too, *before* the throw, for one
+ * case. Normally Flight's `onError` captures the rethrown signal within the
+ * renderer's promotion cap, and the pipeline renders the deny page with
+ * `deny.status` — the recorded status goes unread. When the signal lands
+ * after the cap but within the detection window that follows, the renderer
+ * discards it (never promoted) and streams the document it already has;
+ * `getDenyStatus()`, read once as the renderer returns, gives that document
+ * the deny's 4xx instead of a 200. A deny later than that commits 200. Pinned by
+ * `tests/late-hoisted-deny-status.test.ts`. The RSC payload path never
+ * reads it — a Flight payload response is always 200 and the row itself
+ * carries the deny (TIM-1495).
  *
  * Either branch leaves part of the matched chain unmounted — hoisting sends
  * the render to a boundary that discards everything below it, and a layout

package/src/server/deny-renderer.ts

@@ -20,12 +20,11 @@ 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 { loadFallbackModule, reportRenderError } from './pipeline-helpers.ts';
 import { isDebug } from './debug.ts';
 import { resolveMetadata, renderMetadataToElements } from './metadata.ts';
 import { headElementsToReact } from './metadata.ts';
@@ -33,8 +32,9 @@ 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 { renderJsonStatusFile } from './json-status-response.ts';
 import type { RouteMatch } from './pipeline.ts';
-import type { NavContext } from './ssr-bridge-types.ts';
+import type { NavContext, SsrRenderResult } from './ssr-bridge-types.ts';
 import { flightInitScript } from './flight-scripts.ts';
 import { getCspNonce } from './csp-nonce.ts';
 import type { ClientBootstrapConfig } from './html-injectors.ts';
@@ -52,15 +52,7 @@ export interface LayoutEntry {
 export type CallSsrFn = (
   rscStream: ReadableStream<Uint8Array>,
   navContext: NavContext
-) => Promise<Response>;
-
-/**
- * Check if the leaf segment is an API route (has route.ts).
- */
-function isApiRoute(segments: ReadonlyArray<ManifestSegmentNode>): boolean {
-  const leaf = segments[segments.length - 1];
-  return !!leaf?.route;
-}
+) => Promise<SsrRenderResult>;
 
 /**
  * Build the deny page element for a resolved status file with the correct
@@ -121,19 +113,21 @@ export async function renderDenyPage(
   // (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, maxIndex);
-    if (jsonResponse) return jsonResponse;
-    return bareJsonResponse(deny.status, responseHeaders);
-  }
-
-  // Page routes → component chain first, JSON fallback only if no component found.
+  // Page routes → component chain first, JSON fallback only if no component
+  // found. A route.ts chain never reaches here: the deny fallback answers it
+  // in JSON before choosing a page renderer.
   const resolution = resolveStatusFile(deny.status, segments, 'component', maxIndex);
 
   // No component status file — try JSON chain, then the framework default page.
   if (!resolution) {
-    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders, maxIndex);
+    const jsonResponse = await renderJsonStatusFile(
+      req,
+      deny.status,
+      segments,
+      responseHeaders,
+      maxIndex,
+      deny.data
+    );
     if (jsonResponse) return jsonResponse;
     return (
       defaultPage?.(deny.status, responseHeaders) ??
@@ -159,11 +153,18 @@ export async function renderDenyPage(
   // 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);
+  // rejection escape request handling. `loadFallbackModule` reports the load
+  // failure, as it does for every status and error page load.
+  const mod = await loadFallbackModule(resolution.file, req, segments);
   if (!mod?.default) {
-    const jsonResponse = await renderDenyPageJson(deny, segments, responseHeaders, maxIndex);
+    const jsonResponse = await renderJsonStatusFile(
+      req,
+      deny.status,
+      segments,
+      responseHeaders,
+      maxIndex,
+      deny.data
+    );
     if (jsonResponse) return jsonResponse;
     return (
       defaultPage?.(deny.status, responseHeaders) ??
@@ -209,21 +210,17 @@ export async function renderDenyPage(
   const rscStream = renderToReadableStream(withPublishedParams(element), {
     signal: req.signal,
     onError(error: unknown) {
-      logRenderError({ method: req.method, path: new URL(req.url).pathname, error });
+      reportRenderError(error, req, { segments });
     },
   });
 
   const [ssrStream, inlineStream] = teeWithErrorPropagation(rscStream);
 
-  const slotParams = getSlotParamsForClient();
-
   const denyUrl = new URL(req.url);
   const nonce = getCspNonce();
   const navContext: NavContext = {
     pathname: denyUrl.pathname,
     search: appVisibleSearch(denyUrl).search,
-    segmentParams: match.segmentParams,
-    slotParams,
     statusCode: deny.status,
     responseHeaders,
     headHtml: flightInitScript(nonce),
@@ -241,7 +238,7 @@ export async function renderDenyPage(
     // 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);
+    return (await callSsr(ssrStream, navContext)).response;
   } catch (renderError) {
     logRenderError({ method: req.method, path: new URL(req.url).pathname, error: renderError });
     return defaultStatusPageResponse(deny.status, responseHeaders);
@@ -283,7 +280,7 @@ export async function renderDenyPageAsRsc(
     return denyHardNavigateResponse(deny.status, responseHeaders);
   }
 
-  const mod = await loadModule(resolution.file).catch(() => null);
+  const mod = await loadFallbackModule(resolution.file, req, segments);
   if (!mod?.default) {
     return denyHardNavigateResponse(deny.status, responseHeaders);
   }
@@ -310,7 +307,7 @@ export async function renderDenyPageAsRsc(
   const rscStream = renderToReadableStream(withPublishedParams(element), {
     signal: req.signal,
     onError(error: unknown) {
-      console.error('[timber] Error page RSC render error:', error);
+      reportRenderError(error, req);
     },
   });
 
@@ -325,68 +322,4 @@ export async function renderDenyPageAsRsc(
   });
 }
 
-// ─── JSON Rendering ─────────────────────────────────────────────────────────
-
-/**
- * Render a JSON status-code file for a DenySignal.
- *
- * JSON status files are returned verbatim with Content-Type: application/json.
- * No React rendering pipeline, no layout wrapping.
- *
- * Returns null if no JSON status file is found (caller should use bare JSON fallback).
- */
-async function renderDenyPageJson(
-  deny: DenySignal,
-  segments: ManifestSegmentNode[],
-  responseHeaders: Headers,
-  maxIndex?: number
-): Promise<Response | null> {
-  const resolution = resolveStatusFile(deny.status, segments, 'json', maxIndex);
-
-  if (!resolution) {
-    return null;
-  }
-
-  // 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.
-  // 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, { dangerouslyPassData }) 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 data 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');
-  return new Response(JSON.stringify(jsonContent), {
-    status: deny.status,
-    headers: responseHeaders,
-  });
-}
-
-/**
- * Return a bare JSON error response when no JSON status file exists.
- * This is the framework default for JSON format requests.
- */
-function bareJsonResponse(status: number, responseHeaders: Headers): Response {
-  responseHeaders.set('content-type', 'application/json; charset=utf-8');
-  return new Response(JSON.stringify({ error: true, status }), {
-    status,
-    headers: responseHeaders,
-  });
-}
-
 // escapeHtml imported from server/utils/escape-html.ts

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

@@ -61,10 +61,14 @@ export interface ErrorBoundaryProps {
   children: ReactNode;
 }
 
-/** How to load a route file's module. Only `default` is read. */
+/**
+ * How to load a route file's module. Only `default` is read. The server
+ * injects `loadFallbackModule`, which reports a failed load and returns
+ * `null`, so a broken status or error page is never skipped silently.
+ */
 type BoundaryModuleLoader<TFile> = (
   file: TFile
-) => { default?: unknown } | Promise<{ default?: unknown }>;
+) => { default?: unknown } | null | Promise<{ default?: unknown } | null>;
 
 /** Everything the walk needs from its host environment. */
 export interface ErrorBoundaryWrapConfig<TFile, TElement> {
@@ -98,7 +102,7 @@ async function loadBoundaryComponent<TFile>(
   file: TFile,
   loadModule: BoundaryModuleLoader<TFile>
 ): Promise<LoadedComponent | null> {
-  let mod: { default?: unknown };
+  let mod: { default?: unknown } | null;
   try {
     mod = await loadModule(file);
   } catch {

package/src/server/fallback-error.ts

@@ -8,21 +8,26 @@
  * In production: attempts to render root error pages (500.tsx / 5xx.tsx /
  * error.tsx) via the normal RSC → SSR pipeline. Stack traces are never
  * exposed to the client (design/13-security.md principle 4).
+ *
+ * A route.ts match, in dev or production, gets the API route's JSON format
+ * instead: the `500.json` / `5xx.json` chain, then the bare
+ * `{"error": true, "status": 500}` body. That is the same format its denies
+ * use (design/10-error-handling.md §"JSON Error Pages").
  */
 
 import type { RouteMatch } from './pipeline.ts';
-import type { ManifestSegmentNode } from './route-matcher.ts';
+import { isApiRouteChain, type ManifestSegmentNode } from './route-matcher.ts';
 import type { ClientBootstrapConfig } from './html-injectors.ts';
 import type { LayoutEntry } from './deny-renderer.ts';
 import type { GlobalErrorFile } from './rsc-entry/error-renderer.ts';
 import { swallow } from './logger.ts';
-import { logRenderError } from './logger.ts';
+import { reportRenderError } from './pipeline-helpers.ts';
 import { loadModule } from './safe-load.ts';
-import { sourceMapError } from './dev-source-map.ts';
 
 /**
  * Render a fallback error page when the render pipeline throws.
  *
+ * For a route.ts match: the JSON status chain.
  * In dev: styled HTML with error details.
  * In prod: renders root error pages via renderErrorPage.
  */
@@ -30,6 +35,7 @@ export async function renderFallbackError(
   error: unknown,
   req: Request,
   responseHeaders: Headers,
+  match: RouteMatch | undefined,
   isDev: boolean,
   rootSegment: ManifestSegmentNode,
   clientBootstrap: ClientBootstrapConfig,
@@ -37,9 +43,13 @@ export async function renderFallbackError(
   projectRoot?: string,
   hmrOptions?: import('../dev-tools/dev-page-shell.ts').DevErrorHmrOptions
 ): Promise<Response> {
-  // Source-map the error's stack trace in dev mode so the error page
-  // shows original source positions. See TIM-811.
-  sourceMapError(error);
+  // An API consumer never gets a page, including the dev error page. The dev
+  // overlay still shows the error; it is fed by onPipelineError, not by this
+  // response.
+  if (match && isApiRouteChain(match.segments)) {
+    const { renderJsonStatusResponse } = await import('./json-status-response.ts');
+    return renderJsonStatusResponse(req, 500, match.segments, responseHeaders);
+  }
 
   if (isDev) {
     return renderDevErrorPage(error, projectRoot, hmrOptions);
@@ -66,16 +76,21 @@ export async function renderFallbackError(
     // 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 });
+    reportRenderError(layoutError, req, { segments: match?.segments });
   }
-  const match: RouteMatch = { segments, segmentParams: {}, middlewareChain: [] };
+  const rootMatch: RouteMatch = {
+    segments,
+    segmentParams: {},
+    rawSegmentParams: {},
+    middlewareChain: [],
+  };
   return renderErrorPage(
     error,
     500,
     segments,
     layoutComponents,
     req,
-    match,
+    rootMatch,
     responseHeaders,
     clientBootstrap,
     globalError
@@ -102,8 +117,8 @@ export async function renderDevErrorPage(
 
   let html: string;
   try {
-    // Dynamic import — keeps dev-error-page.ts and its transitive deps
-    // (dev-error-overlay.ts, @jridgewell/trace-mapping) out of production bundles.
+    // Dynamic import — keeps dev-tools/error-page.ts and its transitive deps
+    // (dev-tools/overlay.ts, dev-tools/terminal.ts) out of production bundles.
     const { generateDevErrorPage } = await import('../dev-tools/error-page.ts');
     html = generateDevErrorPage(err, 'render', root, hmrOptions);
     // Inject Vite client script so the error overlay fires when HMR connects.

package/src/server/flight-scripts.ts

@@ -15,7 +15,7 @@
  * See design/02-rendering-pipeline.md, LOCAL-415
  */
 
-import { nonceAttr } from './csp-nonce.ts';
+import { nonceAttr } from './render-utils.ts';
 
 // ─── JSON Escaping ────────────────────────────────────────────────────────
 

package/src/server/head-response.ts

@@ -16,10 +16,10 @@
  *
  * The pipeline applies this at its single exit so every response shape is
  * covered — page render, API route, metadata route, deny page, error page,
- * proxy short-circuit. The two unit-level producers that are also reachable as
- * standalone functions (`handleRouteRequest`, `handleApiRoute`) call it too, so
- * each honours HEAD on its own; they share this implementation rather than
- * repeating it, and applying it twice is a no-op.
+ * proxy short-circuit. The unit-level producer that is also reachable as a
+ * standalone function (`handleRouteRequest`) calls it too, so it honours HEAD
+ * on its own; it shares this implementation rather than repeating it, and
+ * applying it twice is a no-op.
  */
 
 /**

package/src/server/html-injector-core.ts

@@ -33,7 +33,7 @@ import {
   type FlightInjectionState,
   type FlightInjectionEvent,
 } from './flight-injection-state.ts';
-import { withTimeout, RenderTimeoutError } from './render-timeout.ts';
+import { withTimeout, RenderTimeoutError, resolveRenderTimeoutMs } from './render-timeout.ts';
 
 // ─── Encoders / Constants ────────────────────────────────────────────────────
 
@@ -384,7 +384,7 @@ export class FlightInjectorCore {
 
   constructor(rscStream: ReadableStream<Uint8Array>, options: FlightInjectorOptions = {}) {
     this.rscReader = rscStream.getReader();
-    this.timeoutMs = (options.renderTimeoutMs ?? 30_000) || 120_000;
+    this.timeoutMs = resolveRenderTimeoutMs(options.renderTimeoutMs);
     this.errorSignal = options.errorSignal;
     this.nonce = options.nonce;
     this.machine = createMachine<FlightInjectionState, FlightInjectionEvent>({

package/src/server/html-injectors.ts

@@ -31,7 +31,7 @@ import {
   suffixFlush,
 } from './html-injector-core.ts';
 import { flightChunkScript } from './flight-scripts.ts';
-import { withTimeout, RenderTimeoutError } from './render-timeout.ts';
+import { withTimeout, RenderTimeoutError, resolveRenderTimeoutMs } from './render-timeout.ts';
 import { createTickCoalescer } from './coalesce-tick.ts';
 
 // ─── Buffered Transform ──────────────────────────────────────────────────────
@@ -207,9 +207,7 @@ export function createInlinedRscStream(
 ): ReadableStream<Uint8Array> {
   const rscReader = rscStream.getReader();
   const decoder = new TextDecoder('utf-8', { fatal: true });
-  // When renderTimeoutMs is 0 ("disabled"), enforce a safety ceiling
-  // so a stalled RSC stream can't hang the connection forever.
-  const timeoutMs = (renderTimeoutMs ?? 30_000) || 120_000;
+  const timeoutMs = resolveRenderTimeoutMs(renderTimeoutMs);
 
   return new ReadableStream<Uint8Array>({
     async pull(controller) {

package/src/server/index.ts

@@ -30,10 +30,6 @@ export {
   type DenyOptions,
   type RedirectOptions,
 } from './primitives.ts';
-// RenderError removed from public exports per TIM-724.
-// Use deny({ status: 500, data: ... }) instead. RenderError stays in
-// #server-internal for pipeline catch logic.
-export type { RenderErrorDigest } from './primitives.ts';
 // JsonSerializable moved to @timber-js/app/codec as the single canonical path.
 // Re-export removed per TIM-721.
 

package/src/server/instrumentation.ts

@@ -29,11 +29,18 @@ export interface InstrumentationRequestInfo {
 }
 
 export interface InstrumentationErrorContext {
-  /** Which pipeline phase the error occurred in. */
-  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route';
+  /**
+   * Which pipeline phase the error occurred in. `'setup'` is route setup
+   * between `proxy.ts` and `middleware.ts`: route matching and segment-param
+   * coercion (e.g. an `app/schema.ts` codec returning a value a param cannot
+   * hold). `'handler'` is `middleware.ts`; `'route'` is a `route.ts` handler
+   * or its `access.ts`, or a metadata route handler. design/17 §"Which errors
+   * reach it" lists every error that is reported, and those that are not.
+   */
+  phase: 'proxy' | 'setup' | 'handler' | 'render' | 'action' | 'route';
   /** The route pattern: '/dashboard/projects/[id]' */
   routePath: string;
-  /** Type of route that was matched. */
+  /** Type of route that was matched. A metadata route reports as `'route'`. */
   routeType: 'page' | 'route' | 'action';
   /** Always set — OTEL trace ID or UUID fallback. */
   traceId: string;

package/src/server/internal.ts

@@ -27,8 +27,7 @@ export { getCookie, getSetCookieHeaders } from './cookie-context.ts';
 export { coerce } from './form-data.ts';
 
 // ── Signal classes (instanceof targets for pipeline catch logic) ──────────
-export { DenySignal, RedirectSignal, RenderError } from './primitives.ts';
-export type { RenderErrorDigest } from './primitives.ts';
+export { DenySignal, RedirectSignal } from './primitives.ts';
 
 // ── Pipeline ─────────────────────────────────────────────────────────────
 export { createPipeline } from './pipeline.ts';
@@ -78,10 +77,6 @@ export type {
   SlotDeniedKind,
 } from './status-code-resolver.ts';
 
-// ── CSRF Protection ──────────────────────────────────────────────────────
-export { validateCsrf } from './csrf.ts';
-export type { CsrfConfig, CsrfResult } from './csrf.ts';
-
 // ── Body Limits ──────────────────────────────────────────────────────────
 export { parseBodySize, enforceBodyLimits, DEFAULT_LIMITS } from './body-limits.ts';
 export type { BodyLimitsConfig, BodyLimitResult, BodyKind } from './body-limits.ts';

package/src/server/json-status-response.ts

@@ -0,0 +1,105 @@
+/**
+ * JSON status responses — the status-code chain for API consumers.
+ *
+ * `{status}.json` → `{category}.json`, leaf → root, then the bare
+ * `{"error": true, "status": N}` body. No React, so the route.ts path and
+ * the pipeline's fallback renderer can use it without loading the RSC
+ * runtime.
+ *
+ * See design/10-error-handling.md §"JSON Error Pages".
+ */
+
+import { isDebug } from './debug.ts';
+import { loadFallbackModule } from './pipeline-helpers.ts';
+import { resolveStatusFile } from './status-code-resolver.ts';
+import type { ManifestSegmentNode } from './route-matcher.ts';
+
+/**
+ * Render the JSON status chain for `status` — `{status}.json` →
+ * `{category}.json`, leaf → root — ending in the bare
+ * `{"error": true, "status": N}` body when no file resolves.
+ *
+ * This is the one API-route error format (design/10-error-handling.md
+ * §"Format Selection for deny()"). A deny from `access.ts` or a handler, and
+ * an error the pipeline answers for a route.ts match, all end here.
+ *
+ * `droppedData` is a deny()'s data. It is only read to warn that a static
+ * JSON file cannot carry it.
+ */
+export async function renderJsonStatusResponse(
+  req: Request,
+  status: number,
+  segments: ManifestSegmentNode[],
+  responseHeaders: Headers,
+  maxIndex?: number,
+  droppedData?: unknown
+): Promise<Response> {
+  return (
+    (await renderJsonStatusFile(req, status, segments, responseHeaders, maxIndex, droppedData)) ??
+    bareJsonResponse(status, responseHeaders)
+  );
+}
+
+/**
+ * Render a JSON status-code file for `status`.
+ *
+ * JSON status files are returned verbatim with Content-Type: application/json.
+ * No React rendering pipeline, no layout wrapping.
+ *
+ * Returns null if no JSON status file is found (caller should use bare JSON fallback).
+ */
+export async function renderJsonStatusFile(
+  req: Request,
+  status: number,
+  segments: ManifestSegmentNode[],
+  responseHeaders: Headers,
+  maxIndex?: number,
+  droppedData?: unknown
+): Promise<Response | null> {
+  const resolution = resolveStatusFile(status, segments, 'json', maxIndex);
+
+  if (!resolution) {
+    return null;
+  }
+
+  // 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.
+  // A .json status file that fails to load (reported) 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, { dangerouslyPassData }) 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 data prop. See
+  // design/10-error-handling.md §"Status-Code File Variants".
+  if (isDebug() && droppedData !== undefined) {
+    console.warn(
+      `[timber] 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 loadFallbackModule(resolution.file, req, segments);
+  if (!mod) return null;
+  const jsonContent = mod.default ?? mod;
+
+  responseHeaders.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify(jsonContent), {
+    status,
+    headers: responseHeaders,
+  });
+}
+
+/**
+ * Return a bare JSON error response when no JSON status file exists.
+ * This is the framework default for JSON format requests.
+ */
+function bareJsonResponse(status: number, responseHeaders: Headers): Response {
+  responseHeaders.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify({ error: true, status }), {
+    status,
+    headers: responseHeaders,
+  });
+}