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

package/src/server/action-client.ts

@@ -184,6 +184,7 @@ async function runActionMiddleware<TCtx>(
 // Re-export parseFormData for use throughout the framework
 import { parseFormData } from './form-data.js';
 import { formatSize } from '#/utils/format.js';
+import { isDebug, isDevMode } from './debug.js';
 
 /**
  * Extract validation errors from a schema error.
@@ -246,12 +247,15 @@ export function handleActionError(error: unknown): ActionResult<never> {
     };
   }
 
-  // In dev, include the message for debugging
-  const isDev = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production';
+  // In dev, include the message for debugging.
+  // Uses isDevMode() — NOT isDebug() — because this data is sent to the
+  // browser. TIMBER_DEBUG must never cause error messages to leak to clients.
+  // See design/13-security.md principle 4: "Errors don't leak."
+  const devMode = isDevMode();
   return {
     serverError: {
       code: 'INTERNAL_ERROR',
-      ...(isDev && error instanceof Error ? { data: { message: error.message } } : {}),
+      ...(devMode && error instanceof Error ? { data: { message: error.message } } : {}),
     },
   };
 }
@@ -291,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];
@@ -413,7 +423,7 @@ export function validated<TInput, TData>(
  * In production, validation errors are only returned to the client.
  */
 function logValidationFailure(errors: ValidationErrors): void {
-  const isDev = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production';
+  const isDev = isDebug();
   if (!isDev) return;
 
   const fields = Object.entries(errors)

package/src/server/debug.ts

@@ -0,0 +1,137 @@
+/**
+ * Runtime debug flag for timber.js.
+ *
+ * Two distinct functions for two distinct security levels:
+ *
+ * ## `isDebug()` — server-side logging only
+ *
+ * Returns true when timber's debug/warning messages should be written to
+ * stderr / the server console. This NEVER affects what is sent to the
+ * client (no error details, no timing headers, no stack traces).
+ *
+ * Active when any of:
+ * - `NODE_ENV !== 'production'` (standard dev mode)
+ * - `TIMBER_DEBUG` env var is set to a truthy value at runtime
+ * - `timber.config.ts` has `debug: true`
+ *
+ * ## `isDevMode()` — client-visible dev behavior
+ *
+ * Returns true ONLY when `NODE_ENV !== 'production'`. This gates anything
+ * that changes what clients can observe:
+ * - Dev error pages with stack traces (fallback-error.ts)
+ * - Detailed Server-Timing headers (pipeline.ts)
+ * - Error messages in action INTERNAL_ERROR payloads (action-client.ts)
+ * - Pipeline error handler wiring (Vite overlay)
+ *
+ * `isDevMode()` is statically replaced in production builds → the guarded
+ * code is tree-shaken to zero bytes. TIMBER_DEBUG cannot enable it.
+ *
+ * Usage:
+ *   In Cloudflare Workers wrangler.toml:
+ *     [vars]
+ *     TIMBER_DEBUG = "1"
+ *
+ *   In Node.js:
+ *     TIMBER_DEBUG=1 node server.js
+ *
+ *   In timber.config.ts:
+ *     export default { debug: true }
+ *
+ * See design/13-security.md for the security taxonomy.
+ * See design/18-build-system.md for build pipeline details.
+ */
+
+// ─── Dev Mode (client-visible) ──────────────────────────────────────────────
+
+/**
+ * Check if the application is running in development mode.
+ *
+ * This is the ONLY function that should gate client-visible dev behavior:
+ * - Dev error pages with stack traces
+ * - Server-Timing mode default (`'detailed'` in dev, `'total'` in prod)
+ * - Error messages in action `INTERNAL_ERROR` payloads
+ * - Pipeline error handler wiring (Vite overlay)
+ *
+ * Returns `process.env.NODE_ENV !== 'production'`, which is statically
+ * replaced by the bundler in production builds. Code guarded by this
+ * function is tree-shaken to zero bytes in production.
+ *
+ * TIMBER_DEBUG does NOT enable this — that would leak server internals
+ * to clients. Use `isDebug()` for server-side-only logging.
+ */
+export function isDevMode(): boolean {
+  return process.env.NODE_ENV !== 'production';
+}
+
+// ─── Debug Flag (server-side logging only) ──────────────────────────────────
+
+/**
+ * Config-level debug override. Set via `setDebugFromConfig()` during
+ * initialization when timber.config.ts has `debug: true`.
+ */
+let _configDebug = false;
+
+/**
+ * Set the debug flag from timber.config.ts.
+ * Called during handler initialization.
+ */
+export function setDebugFromConfig(debug: boolean): void {
+  _configDebug = debug;
+}
+
+/**
+ * Check if timber debug logging is active (server-side only).
+ *
+ * Returns true if ANY of these conditions hold:
+ * - NODE_ENV is not 'production' (standard dev mode)
+ * - TIMBER_DEBUG environment variable is set to a truthy value at runtime
+ * - timber.config.ts has `debug: true`
+ *
+ * This function controls ONLY server-side logging — messages written to
+ * stderr or the server console. It NEVER affects client-visible behavior
+ * (error pages, response headers, action payloads). For client-visible
+ * behavior, use `isDevMode()`.
+ *
+ * The TIMBER_DEBUG check is deliberately written as a dynamic property
+ * access so bundlers cannot statically replace it.
+ */
+export function isDebug(): boolean {
+  // Fast path: dev mode (statically replaced to `true` in dev, `false` in prod)
+  if (process.env.NODE_ENV !== 'production') return true;
+
+  // Config override
+  if (_configDebug) return true;
+
+  // Runtime env var check — uses dynamic access to prevent static replacement.
+  // In production builds, process.env.NODE_ENV is statically replaced, but
+  // TIMBER_DEBUG must survive as a runtime check. The dynamic key access
+  // pattern ensures the bundler treats this as opaque.
+  return _readTimberDebugEnv();
+}
+
+/**
+ * Read TIMBER_DEBUG from the environment at runtime.
+ *
+ * Extracted to a separate function to:
+ * 1. Prevent bundler inlining (cross-module function calls are not inlined)
+ * 2. Handle platforms where `process` may not exist (Cloudflare Workers)
+ * 3. Support globalThis.__TIMBER_DEBUG for programmatic control
+ */
+function _readTimberDebugEnv(): boolean {
+  // globalThis override — useful for programmatic control and testing
+  if ((globalThis as Record<string, unknown>).__TIMBER_DEBUG) return true;
+
+  // process.env — works in Node.js and platforms that polyfill process
+  try {
+    const key = 'TIMBER_DEBUG';
+    const val =
+      typeof process !== 'undefined' && process.env
+        ? (process.env as Record<string, string | undefined>)[key]
+        : undefined;
+    if (val && val !== '0' && val !== 'false') return true;
+  } catch {
+    // process may not exist or env may throw — safe to ignore
+  }
+
+  return false;
+}

package/src/server/deny-renderer.ts

@@ -20,6 +20,7 @@ import { renderToReadableStream } from '#/rsc-runtime/rsc.js';
 
 import { DenySignal } from './primitives.js';
 import { logRenderError } from './logger.js';
+import { isDebug } from './debug.js';
 import { resolveMetadata, renderMetadataToElements } from './metadata.js';
 import { resolveManifestStatusFile } from './manifest-status-resolver.js';
 import type { ManifestSegmentNode } from './route-matcher.js';
@@ -94,7 +95,7 @@ export async function renderDenyPage(
 
   // Dev warning: JSON status file exists but is shadowed by the component chain.
   // This helps developers understand why their .json file isn't being served.
-  if (process.env.NODE_ENV !== 'production') {
+  if (isDebug()) {
     const jsonResolution = resolveManifestStatusFile(deny.status, segments, 'json');
     if (jsonResolution) {
       console.warn(
@@ -133,7 +134,7 @@ export async function renderDenyPage(
       const { component } = layoutsToWrap[i];
       element = h(component, null, element);
     }
-  } else if (process.env.NODE_ENV !== 'production') {
+  } 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.

package/src/server/dev-warnings.ts

@@ -15,6 +15,7 @@
  */
 
 import type { ViteDevServer } from 'vite';
+import { isDebug } from './debug.js';
 
 // ─── Warning IDs ───────────────────────────────────────────────────────────
 
@@ -54,7 +55,7 @@ export function setViteServer(server: ViteDevServer | null): void {
 }
 
 function isDev(): boolean {
-  return process.env.NODE_ENV !== 'production';
+  return isDebug();
 }
 
 /**

package/src/server/html-injectors.ts

@@ -196,15 +196,25 @@ function createFlightInjectionTransform(
   // Once the suffix is stripped, all content is body-level and
   // scripts can safely be drained after any HTML chunk.
   let foundSuffix = false;
+  // Set to true in flush() — once all HTML chunks have been emitted,
+  // there's no need to yield between RSC reads. This eliminates
+  // ~36 macrotask yields per request (18 chunks × 2 yields each)
+  // that were the primary source of SSR overhead vs Next.js.
+  let htmlStreamFinished = false;
 
   // RSC script chunks waiting to be injected at the body level.
   const pending: Uint8Array[] = [];
 
   async function pullLoop(): Promise<void> {
-    // Wait one macrotask so the HTML shell chunk flows through
-    // transform() first. The browser needs the shell HTML before
-    // RSC data script tags arrive.
-    await new Promise<void>((r) => setTimeout(r, 0));
+    // Yield once so the first HTML shell chunk flows through
+    // transform() before we start reading RSC data. Uses
+    // setImmediate (check phase — end of current event loop
+    // iteration) instead of setTimeout(0) (timer phase — next
+    // iteration). Under concurrency, setTimeout(0) yields to
+    // ALL pending timer callbacks from other requests, adding
+    // 1-4ms per yield. setImmediate fires before timers.
+    // Available on both Node.js and Cloudflare Workers.
+    await new Promise<void>((r) => setImmediate(r));
 
     try {
       for (;;) {
@@ -215,10 +225,12 @@ function createFlightInjectionTransform(
         }
         pending.push(value);
         // Yield between reads so HTML chunks get a chance to flow
-        // through transform() first. RSC and HTML are driven by the
-        // same source — each RSC chunk typically produces a
-        // corresponding HTML chunk from SSR.
-        await new Promise<void>((r) => setTimeout(r, 0));
+        // through transform() first — but only while HTML is still
+        // streaming. Once flush() fires (all HTML emitted), drain
+        // remaining RSC chunks without yielding.
+        if (!htmlStreamFinished) {
+          await new Promise<void>((r) => setImmediate(r));
+        }
       }
     } catch (err) {
       pullError = err;
@@ -240,7 +252,11 @@ function createFlightInjectionTransform(
 
   return new TransformStream<Uint8Array, Uint8Array>({
     transform(chunk, controller) {
-      // Start pulling RSC scripts into the buffer (if not started)
+      // Pull-based start: don't begin reading RSC until the first
+      // HTML chunk flows through. This matches Next.js's approach
+      // and ensures the shell HTML is enqueued before any RSC
+      // script tags. Without this, the pull loop starts eagerly
+      // and may read RSC data before the browser has any HTML.
       if (!pullPromise) {
         pullPromise = pullLoop();
       }
@@ -274,7 +290,11 @@ function createFlightInjectionTransform(
       }
     },
     flush(controller) {
-      // HTML stream is done — drain remaining RSC chunks at body level
+      // All HTML chunks have been emitted. Signal the pull loop to
+      // stop yielding between RSC reads — no more HTML to interleave.
+      htmlStreamFinished = true;
+
+      // Drain remaining RSC chunks at body level
       const finish = () => {
         drainPending(controller);
         // Re-emit the suffix at the very end so HTML is well-formed

package/src/server/logger.ts

@@ -10,6 +10,7 @@
 
 import { getTraceStore } from './tracing.js';
 import { formatSsrError } from './error-formatter.js';
+import { isDebug } from './debug.js';
 
 // ─── Logger Interface ─────────────────────────────────────────────────────
 
@@ -103,7 +104,7 @@ export function logMiddlewareShortCircuit(data: {
 export function logMiddlewareError(data: { method: string; path: string; error: unknown }): void {
   if (_logger) {
     _logger.error('unhandled error in middleware phase', withTraceContext(data));
-  } else if (process.env.NODE_ENV !== 'production') {
+  } else if (isDebug()) {
     console.error('[timber] middleware error', data.error);
   }
 }
@@ -112,7 +113,7 @@ export function logMiddlewareError(data: { method: string; path: string; error:
 export function logRenderError(data: { method: string; path: string; error: unknown }): void {
   if (_logger) {
     _logger.error('unhandled render-phase error', withTraceContext(data));
-  } else if (process.env.NODE_ENV !== 'production') {
+  } else if (isDebug()) {
     // No logger configured — fall back to console.error in dev with
     // cleaned-up error messages (vendor paths rewritten, hints added).
     console.error('[timber] render error:', formatSsrError(data.error));
@@ -123,7 +124,7 @@ export function logRenderError(data: { method: string; path: string; error: unkn
 export function logProxyError(data: { error: unknown }): void {
   if (_logger) {
     _logger.error('proxy.ts threw uncaught error', withTraceContext(data));
-  } else if (process.env.NODE_ENV !== 'production') {
+  } else if (isDebug()) {
     console.error('[timber] proxy error', data.error);
   }
 }

package/src/server/pipeline.ts

@@ -117,12 +117,15 @@ export interface PipelineConfig {
    */
   interceptionRewrites?: import('#/routing/interception.js').InterceptionRewrite[];
   /**
-   * Emit Server-Timing header on responses for Chrome DevTools visibility.
-   * Only enable in dev mode — exposes internal timing data.
+   * Control Server-Timing header output.
    *
-   * Default: false (production-safe).
+   * - `'detailed'` — per-phase breakdown (proxy, middleware, render).
+   * - `'total'` — single `total;dur=N` entry (production-safe).
+   * - `false` — no Server-Timing header at all.
+   *
+   * Default: `'total'`.
    */
-  enableServerTiming?: boolean;
+  serverTiming?: 'detailed' | 'total' | false;
   /**
    * Dev pipeline error callback — called when a pipeline phase (proxy,
    * middleware, render) catches an unhandled error. Used to wire the error
@@ -165,7 +168,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
     earlyHints,
     stripTrailingSlash = true,
     slowRequestMs = 3000,
-    enableServerTiming = false,
+    serverTiming = 'total',
     onPipelineError,
   } = config;
 
@@ -216,25 +219,25 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
               // DevSpanProcessor reads this for tree/summary output.
               await setSpanAttribute('http.response.status_code', result.status);
 
-              // Append Server-Timing header.
-              // In dev mode: detailed per-phase breakdown (proxy, middleware, render).
-              // In production: single total duration — safe to expose, no phase names.
+              // Append Server-Timing header based on configured mode.
               // Response.redirect() creates immutable headers, so we must
               // ensure mutability before writing Server-Timing.
-              if (enableServerTiming) {
-                const serverTiming = getServerTimingHeader();
-                if (serverTiming) {
+              if (serverTiming === 'detailed') {
+                // Detailed: per-phase breakdown (proxy, middleware, render).
+                const timingHeader = getServerTimingHeader();
+                if (timingHeader) {
                   result = ensureMutableResponse(result);
-                  result.headers.set('Server-Timing', serverTiming);
+                  result.headers.set('Server-Timing', timingHeader);
                 }
-              } else {
-                // Production: emit total request duration only.
-                // No phase breakdown — prevents information disclosure
-                // while giving browser DevTools useful timing data.
+              } else if (serverTiming === 'total') {
+                // Total only: single `total;dur=N` — no phase names.
+                // Prevents information disclosure while giving browser
+                // DevTools useful timing data.
                 const totalMs = Math.round(performance.now() - startTime);
                 result = ensureMutableResponse(result);
                 result.headers.set('Server-Timing', `total;dur=${totalMs}`);
               }
+              // serverTiming === false: no header at all
 
               return result;
             }
@@ -254,7 +257,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
           return response;
         };
 
-        return enableServerTiming ? runWithTimingCollector(runRequest) : runRequest();
+        return serverTiming === 'detailed' ? runWithTimingCollector(runRequest) : runRequest();
       });
     });
   };
@@ -272,7 +275,7 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       }
       const proxyFn = () => runProxy(proxyExport, req, () => handleRequest(req, method, path));
       return await withSpan('timber.proxy', {}, () =>
-        enableServerTiming ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
+        serverTiming === 'detailed' ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
       );
     } catch (error) {
       // Uncaught proxy.ts error → bare HTTP 500
@@ -421,7 +424,9 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
         setMutableCookieContext(true);
         const middlewareFn = () => runMiddleware(match.middleware!, ctx);
         const middlewareResponse = await withSpan('timber.middleware', {}, () =>
-          enableServerTiming ? withTiming('mw', 'middleware.ts', middlewareFn) : middlewareFn()
+          serverTiming === 'detailed'
+            ? withTiming('mw', 'middleware.ts', middlewareFn)
+            : middlewareFn()
         );
         setMutableCookieContext(false);
         if (middlewareResponse) {
@@ -476,7 +481,9 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       const renderFn = () =>
         render(req, match, responseHeaders, requestHeaderOverlay, interception);
       const response = await withSpan('timber.render', { 'http.route': canonicalPathname }, () =>
-        enableServerTiming ? withTiming('render', 'RSC + SSR render', renderFn) : renderFn()
+        serverTiming === 'detailed'
+          ? withTiming('render', 'RSC + SSR render', renderFn)
+          : renderFn()
       );
       markResponseFlushed();
       return response;
@@ -487,7 +494,14 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
         return new Response(null, { status: error.status });
       }
       // RedirectSignal leaked from render — honour the redirect.
+      // For RSC payload requests, return 204 + X-Timber-Redirect so the
+      // client router can perform a soft SPA redirect (same as middleware path).
       if (error instanceof RedirectSignal) {
+        const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
+        if (isRsc) {
+          responseHeaders.set('X-Timber-Redirect', error.location);
+          return new Response(null, { status: 204, headers: responseHeaders });
+        }
         responseHeaders.set('Location', error.location);
         return new Response(null, { status: error.status, headers: responseHeaders });
       }

package/src/server/primitives.ts

@@ -5,6 +5,7 @@
 
 import type { JsonSerializable } from './types.js';
 import { getWaitUntil as _getWaitUntil } from './waituntil-bridge.js';
+import { isDebug } from './debug.js';
 
 // ─── Dev-mode validation ────────────────────────────────────────────────────
 
@@ -83,7 +84,7 @@ export function findNonSerializable(value: unknown, path = 'data'): string | nul
  * No-op in production.
  */
 function warnIfNotSerializable(data: unknown, callerName: string): void {
-  if (process.env.NODE_ENV === 'production') return;
+  if (!isDebug()) return;
   if (data === undefined) return;
 
   const issue = findNonSerializable(data);

package/src/server/request-context.ts

@@ -13,6 +13,7 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { Routes } from '#/index.js';
 import { requestContextAls, type RequestContextStore, type CookieEntry } from './als-registry.js';
+import { isDebug } from './debug.js';
 
 // Re-export the ALS for framework-internal consumers that need direct access.
 export { requestContextAls };
@@ -117,7 +118,7 @@ export function cookies(): RequestCookies {
     set(name: string, value: string, options?: CookieOptions): void {
       assertMutable(store, 'set');
       if (store.flushed) {
-        if (process.env.NODE_ENV !== 'production') {
+        if (isDebug()) {
           console.warn(
             `[timber] warn: cookies().set('${name}') called after response headers were committed.\n` +
               `  The cookie will NOT be sent. Move cookie mutations to middleware.ts, a server action,\n` +
@@ -146,7 +147,7 @@ export function cookies(): RequestCookies {
     delete(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void {
       assertMutable(store, 'delete');
       if (store.flushed) {
-        if (process.env.NODE_ENV !== 'production') {
+        if (isDebug()) {
           console.warn(
             `[timber] warn: cookies().delete('${name}') called after response headers were committed.\n` +
               `  The cookie will NOT be deleted. Move cookie mutations to middleware.ts, a server action,\n` +

package/src/server/route-element-builder.ts

@@ -352,12 +352,7 @@ export async function buildRouteElement(
     //   same urlPath (e.g., /(marketing) and /(app) both have "/"),
     //   which would cause the wrong cached layout to be reused
     const skip =
-      shouldSkipSegment(
-        segment.urlPath,
-        layoutComponent,
-        isLeaf,
-        clientStateTree ?? null
-      ) &&
+      shouldSkipSegment(segment.urlPath, layoutComponent, isLeaf, clientStateTree ?? null) &&
       hasRenderedLayoutBelow &&
       segment.segmentType !== 'group';
 

package/src/server/rsc-entry/index.ts

@@ -67,6 +67,22 @@ import { buildRscPayloadResponse } from './rsc-payload.js';
 import { renderRscStream } from './rsc-stream.js';
 import { renderSsrResponse } from './ssr-renderer.js';
 import { callSsr } from './ssr-bridge.js';
+import { isDebug, isDevMode, setDebugFromConfig } from '#/server/debug.js';
+
+/**
+ * Resolve the Server-Timing mode from timber.config.ts.
+ *
+ * If the user set `serverTiming` explicitly, use that value.
+ * Otherwise: `'detailed'` in dev, `'total'` in production.
+ */
+function resolveServerTimingMode(
+  config: Record<string, unknown>,
+  isDev: boolean
+): 'detailed' | 'total' | false {
+  const userValue = config.serverTiming as 'detailed' | 'total' | false | undefined;
+  if (userValue !== undefined) return userValue;
+  return isDev ? 'detailed' : 'total';
+}
 
 // Dev-only pipeline error handler, set by the dev server after import.
 // In production this is always undefined — no overhead.
@@ -121,13 +137,31 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     buildManifest: buildManifest as BuildManifest,
   });
 
-  // Dev logging — initialize OTEL-based dev tracing once at handler creation.
-  // In production, isDev is false — no tracing, no overhead.
-  // The DevSpanProcessor handles all formatting and stderr output.
-  const isDev = process.env.NODE_ENV !== 'production';
+  // Initialize debug flag from config before anything else.
+  // This allows timber.config.ts `debug: true` to enable debug logging
+  // in production without the TIMBER_DEBUG env var.
+  if ((runtimeConfig as Record<string, unknown>).debug) {
+    setDebugFromConfig(true);
+  }
+
+  // Two separate flags for two different security levels:
+  //
+  // isDev (isDevMode) — gates client-visible behavior: dev error pages with
+  //   stack traces, detailed Server-Timing headers, error messages in action
+  //   payloads. Statically replaced in production → tree-shaken to zero.
+  //   TIMBER_DEBUG cannot enable this.
+  //
+  // debugEnabled (isDebug) — gates server-side logging only: stderr warnings,
+  //   OTEL dev tracing, console.error fallbacks. TIMBER_DEBUG enables this.
+  //   Never affects what clients see.
+  const isDev = isDevMode();
+  const debugEnabled = isDebug();
   const slowPhaseMs = (runtimeConfig as Record<string, unknown>).slowPhaseMs as number | undefined;
 
-  if (isDev) {
+  // Dev logging — initialize OTEL-based dev tracing once at handler creation.
+  // In production with TIMBER_DEBUG, this enables server-side tracing output
+  // without exposing anything to clients.
+  if (debugEnabled) {
     const devLogMode = resolveLogMode();
     if (devLogMode !== 'quiet') {
       await initDevTracing({ mode: devLogMode, slowPhaseMs });
@@ -186,7 +220,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     // Slow request threshold from timber.config.ts. Default 3000ms, 0 to disable.
     // See design/17-logging.md §"slowRequestMs"
     slowRequestMs: (runtimeConfig as Record<string, unknown>).slowRequestMs as number | undefined,
-    enableServerTiming: isDev,
+    serverTiming: resolveServerTimingMode(runtimeConfig, isDev),
     onPipelineError: isDev
       ? (error: Error, phase: string) => {
           if (_devPipelineErrorHandler) _devPipelineErrorHandler(error, phase);
@@ -330,7 +364,8 @@ async function renderRoute(
     throw error;
   }
 
-  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } = routeResult;
+  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } =
+    routeResult;
 
   // Build head HTML for injection into the SSR output.
   // Collects CSS, fonts, and modulepreload from the build manifest for matched segments.
@@ -347,6 +382,14 @@ async function renderRoute(
     headHtml += buildCssLinkTags(cssUrls);
   }
 
+  // Inline font CSS as a <style> tag — @font-face rules and scoped classes.
+  // The font CSS is set on globalThis by the transformed font file's
+  // side-effect import of virtual:timber-font-css-register.
+  const fontCss = (globalThis as Record<string, unknown>).__timber_font_css as string | undefined;
+  if (fontCss) {
+    headHtml += `<style data-timber-fonts>${fontCss}</style>`;
+  }
+
   const fontEntries = collectRouteFonts(segments, typedManifest);
   if (fontEntries.length > 0) {
     headHtml += buildFontPreloadTags(fontEntries);