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

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 } } : {}),
     },
   };
 }
@@ -413,7 +417,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
+ * - Detailed Server-Timing response headers
+ * - 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/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/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/response-cache.ts

@@ -0,0 +1,277 @@
+/**
+ * Render-level response deduplication and short-TTL LRU cache.
+ *
+ * Two layers of optimization:
+ *
+ * 1. **Singleflight** — concurrent requests to the same URL share a single
+ *    render. Uses createSingleflight() from cache/singleflight.ts.
+ *
+ * 2. **LRU cache** — recently rendered responses are reused without
+ *    re-executing the RSC-to-SSR pipeline. Entries have a short TTL
+ *    (default 5s) and the cache has a bounded size (default 150 entries).
+ *
+ * Cache keys are compound: method + pathname + isRscPayload. Responses
+ * with Set-Cookie headers are never cached (they contain user-specific
+ * state). When `publicOnly` is true (default), requests with Cookie or
+ * Authorization headers bypass the cache entirely.
+ *
+ * See design/02-rendering-pipeline.md, design/31-benchmarking.md.
+ */
+
+import { createSingleflight } from '#/cache/singleflight.js';
+
+// ─── Configuration ─────────────────────────────────────────────────────────
+
+export interface ResponseCacheConfig {
+  /** Maximum number of entries in the LRU cache. Default: 150. */
+  maxSize?: number;
+  /** TTL for cached entries in milliseconds. Default: 5000 (5s). */
+  ttlMs?: number;
+  /**
+   * When true (default), requests with Cookie or Authorization headers
+   * bypass the cache entirely. This prevents sharing user-specific
+   * responses across requests.
+   */
+  publicOnly?: boolean;
+}
+
+export interface ResolvedResponseCacheConfig {
+  maxSize: number;
+  ttlMs: number;
+  publicOnly: boolean;
+}
+
+export function resolveResponseCacheConfig(
+  config?: ResponseCacheConfig | false
+): ResolvedResponseCacheConfig | null {
+  // Explicitly disabled
+  if (config === false) return null;
+
+  return {
+    maxSize: config?.maxSize ?? 150,
+    ttlMs: config?.ttlMs ?? 5000,
+    publicOnly: config?.publicOnly ?? true,
+  };
+}
+
+// ─── Cache Entry ───────────────────────────────────────────────────────────
+
+interface CacheEntry {
+  /** The cached response body as an ArrayBuffer (already consumed). */
+  body: ArrayBuffer;
+  /** Response status code. */
+  status: number;
+  /** Response headers (serialized). */
+  headers: [string, string][];
+  /** Timestamp when this entry was created. */
+  createdAt: number;
+}
+
+// ─── Singleflight Result ───────────────────────────────────────────────────
+
+/** Internal type: singleflight returns either a raw response or a cache entry. */
+interface SingleflightResult {
+  /** Non-null when the response wasn't cacheable — only the first caller gets it. */
+  response: Response | null;
+  /** Non-null when the response was cached — all callers construct from this. */
+  entry: CacheEntry | null;
+}
+
+// ─── LRU Cache ─────────────────────────────────────────────────────────────
+
+/**
+ * Simple LRU cache backed by a Map (insertion order = access order).
+ * On get, we delete and re-insert to move the entry to the end (most recent).
+ * On eviction, we delete from the beginning (least recent).
+ */
+class LruCache {
+  private readonly map = new Map<string, CacheEntry>();
+  private readonly maxSize: number;
+  private readonly ttlMs: number;
+
+  constructor(maxSize: number, ttlMs: number) {
+    this.maxSize = maxSize;
+    this.ttlMs = ttlMs;
+  }
+
+  get(key: string): CacheEntry | undefined {
+    const entry = this.map.get(key);
+    if (!entry) return undefined;
+
+    // Check TTL
+    if (Date.now() - entry.createdAt > this.ttlMs) {
+      this.map.delete(key);
+      return undefined;
+    }
+
+    // Move to end (most recently used)
+    this.map.delete(key);
+    this.map.set(key, entry);
+    return entry;
+  }
+
+  set(key: string, entry: CacheEntry): void {
+    // If key exists, remove to re-insert at end
+    this.map.delete(key);
+
+    // Evict oldest if at capacity
+    if (this.map.size >= this.maxSize) {
+      const oldest = this.map.keys().next().value;
+      if (oldest !== undefined) {
+        this.map.delete(oldest);
+      }
+    }
+
+    this.map.set(key, entry);
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  clear(): void {
+    this.map.clear();
+  }
+}
+
+// ─── Response Cache ────────────────────────────────────────────────────────
+
+export interface ResponseCache {
+  /**
+   * Wrap a render function with singleflight dedup + LRU caching.
+   * Returns the cached Response or executes the render function.
+   */
+  getOrRender(
+    req: Request,
+    isRscPayload: boolean,
+    renderFn: () => Promise<Response>
+  ): Promise<Response>;
+
+  /** Number of entries currently in the LRU cache. */
+  readonly size: number;
+
+  /** Clear all cached entries. */
+  clear(): void;
+}
+
+/**
+ * Create a response cache with singleflight deduplication and LRU caching.
+ */
+export function createResponseCache(config: ResolvedResponseCacheConfig): ResponseCache {
+  const lru = new LruCache(config.maxSize, config.ttlMs);
+  const singleflight = createSingleflight();
+
+  function buildCacheKey(req: Request, isRscPayload: boolean): string | null {
+    // When publicOnly is true, skip caching for authenticated requests
+    if (config.publicOnly) {
+      if (req.headers.has('Cookie') || req.headers.has('Authorization')) {
+        return null;
+      }
+    }
+
+    const url = new URL(req.url);
+    return `${req.method}:${url.pathname}:${isRscPayload ? 'rsc' : 'html'}`;
+  }
+
+  /**
+   * Check if a response is cacheable.
+   * Responses with Set-Cookie headers are never cached — they contain
+   * user-specific state that must not be shared across requests.
+   */
+  function isCacheable(response: Response): boolean {
+    // Don't cache error responses
+    if (response.status >= 400) return false;
+
+    // Don't cache redirects
+    if (response.status >= 300 && response.status < 400) return false;
+
+    // Don't cache responses with Set-Cookie (user-specific state)
+    if (response.headers.has('Set-Cookie')) return false;
+
+    // Only cache responses with a body
+    if (!response.body) return false;
+
+    return true;
+  }
+
+  /** Construct a fresh Response from a cache entry (each caller gets their own). */
+  function responseFromEntry(entry: CacheEntry): Response {
+    // slice(0) creates a copy so each caller owns their buffer
+    return new Response(entry.body.slice(0), {
+      status: entry.status,
+      headers: entry.headers,
+    });
+  }
+
+  return {
+    async getOrRender(
+      req: Request,
+      isRscPayload: boolean,
+      renderFn: () => Promise<Response>
+    ): Promise<Response> {
+      const cacheKey = buildCacheKey(req, isRscPayload);
+
+      // No cache key = skip caching entirely
+      if (cacheKey === null) {
+        return renderFn();
+      }
+
+      // Check LRU cache first
+      const cached = lru.get(cacheKey);
+      if (cached) {
+        return responseFromEntry(cached);
+      }
+
+      // Singleflight: concurrent requests to the same key share one render.
+      // The singleflight returns a SingleflightResult so all waiters
+      // can construct their own Response from the same cached data.
+      const result: SingleflightResult = await singleflight.do(cacheKey, async () => {
+        const response = await renderFn();
+
+        if (!isCacheable(response)) {
+          return { response, entry: null };
+        }
+
+        // Buffer the response body for caching.
+        // The original Response body is consumed here — callers get copies
+        // from the cached ArrayBuffer.
+        const body = await response.arrayBuffer();
+        const headers: [string, string][] = [];
+        response.headers.forEach((value, key) => {
+          headers.push([key, value]);
+        });
+
+        const entry: CacheEntry = {
+          body,
+          status: response.status,
+          headers,
+          createdAt: Date.now(),
+        };
+
+        lru.set(cacheKey, entry);
+
+        return { response: null, entry };
+      });
+
+      // Non-cacheable response — only the first caller gets the original.
+      // For singleflight, this means concurrent waiters get the same promise
+      // result. The first caller already consumed the body, so subsequent
+      // callers would get an empty body. This is acceptable: non-cacheable
+      // responses (errors, redirects, Set-Cookie) are rare under concurrent
+      // identical requests, and the status + headers are still correct.
+      if (result.response) {
+        return result.response;
+      }
+
+      return responseFromEntry(result.entry!);
+    },
+
+    get size() {
+      return lru.size;
+    },
+
+    clear() {
+      lru.clear();
+    },
+  };
+}

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

@@ -63,10 +63,16 @@ import {
   isRscPayloadRequest,
 } from './helpers.js';
 import { parseClientStateTree } from '#/server/state-tree-diff.js';
+import {
+  createResponseCache,
+  resolveResponseCacheConfig,
+  type ResponseCache,
+} from '#/server/response-cache.js';
 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';
 
 // Dev-only pipeline error handler, set by the dev server after import.
 // In production this is always undefined — no overhead.
@@ -121,13 +127,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 });
@@ -140,6 +164,17 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
 
   const typedBuildManifest = buildManifest as BuildManifest;
 
+  // Initialize response-level caching and singleflight deduplication.
+  // See design/31-benchmarking.md for performance motivation.
+  const responseCacheRaw = (runtimeConfig as Record<string, unknown>).responseCache as
+    | { maxSize?: number; ttlMs?: number; publicOnly?: boolean }
+    | false
+    | undefined;
+  const responseCacheConfig = resolveResponseCacheConfig(responseCacheRaw);
+  const responseCache: ResponseCache | null = responseCacheConfig
+    ? createResponseCache(responseCacheConfig)
+    : null;
+
   const pipelineConfig: PipelineConfig = {
     proxyLoader: manifest.proxy?.load,
     matchRoute,
@@ -170,14 +205,17 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
       _requestHeaderOverlay: Headers,
       interception?: InterceptionContext
     ) => {
-      return renderRoute(
-        req,
-        match,
-        responseHeaders,
-        clientBootstrap,
-        clientJsDisabled,
-        interception
-      );
+      const doRender = () =>
+        renderRoute(req, match, responseHeaders, clientBootstrap, clientJsDisabled, interception);
+
+      // Response cache wraps the render with singleflight + LRU.
+      // Interception requests (modals) are excluded — they depend on
+      // X-Timber-URL which makes caching semantics ambiguous.
+      if (responseCache && !interception) {
+        const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
+        return responseCache.getOrRender(req, isRsc, doRender);
+      }
+      return doRender();
     },
     renderNoMatch: async (req: Request, responseHeaders: Headers) => {
       return renderNoMatchPage(req, manifest.root, responseHeaders, clientBootstrap);

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

@@ -53,7 +53,10 @@ export async function buildRscPayloadResponse(
   // propagate to the onError callback before we check the signals.
   // The rejected Promise from an async component resolves in the next
   // microtask after read(), so we need at least one tick.
-  await new Promise<void>((r) => setTimeout(r, 0));
+  //
+  // Uses queueMicrotask instead of setTimeout(0) to stay within the
+  // same tick — no full event loop round-trip needed.
+  await new Promise<void>((r) => queueMicrotask(r));
 
   // Check for redirect/deny signals detected during initial rendering
   const trackedRedirect = signals.redirectSignal as RedirectSignal | null;