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

package/src/plugins/fonts.ts

@@ -36,8 +36,15 @@ const VIRTUAL_LOCAL = '@timber/fonts/local';
 const RESOLVED_GOOGLE = '\0@timber/fonts/google';
 const RESOLVED_LOCAL = '\0@timber/fonts/local';
 
-/** URL path where font CSS is served (dev middleware and prod asset). */
-const FONT_CSS_PATH = '/_timber/fonts/fonts.css';
+/**
+ * Virtual module that exports the combined font CSS string.
+ *
+ * The RSC entry imports this module and inlines it as a <style> tag.
+ * Unlike a config-based approach, this module is loaded lazily (on first
+ * request), so it always has up-to-date font data from the registry.
+ */
+const VIRTUAL_FONT_CSS = 'virtual:timber-font-css';
+const RESOLVED_FONT_CSS = '\0virtual:timber-font-css';
 
 /**
  * Registry of fonts extracted during transform.
@@ -247,6 +254,33 @@ function generateLocalVirtualModule(): string {
   ].join('\n');
 }
 
+/**
+ * Generate CSS for a single extracted font.
+ *
+ * Includes @font-face rules (for local fonts), fallback @font-face,
+ * and the scoped class rule.
+ */
+export function generateFontCss(font: ExtractedFont): string {
+  const cssParts: string[] = [];
+
+  if (font.provider === 'local' && font.localSources) {
+    const faces = generateLocalFontFaces(font.family, font.localSources, font.display);
+    const faceCss = generateFontFaces(faces);
+    if (faceCss) cssParts.push(faceCss);
+  }
+
+  const fallbackCss = generateFallbackCss(font.family);
+  if (fallbackCss) cssParts.push(fallbackCss);
+
+  if (font.variable) {
+    cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
+  } else {
+    cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
+  }
+
+  return cssParts.join('\n\n');
+}
+
 /**
  * Generate the CSS output for all extracted fonts.
  *
@@ -255,27 +289,9 @@ function generateLocalVirtualModule(): string {
  */
 export function generateAllFontCss(registry: FontRegistry): string {
   const cssParts: string[] = [];
-
   for (const font of registry.values()) {
-    // Generate @font-face rules for local fonts
-    if (font.provider === 'local' && font.localSources) {
-      const faces = generateLocalFontFaces(font.family, font.localSources, font.display);
-      const faceCss = generateFontFaces(faces);
-      if (faceCss) cssParts.push(faceCss);
-    }
-
-    // Generate fallback @font-face if metrics are available
-    const fallbackCss = generateFallbackCss(font.family);
-    if (fallbackCss) cssParts.push(fallbackCss);
-
-    // Generate scoped class
-    if (font.variable) {
-      cssParts.push(generateVariableClass(font.className, font.variable, font.fontFamily));
-    } else {
-      cssParts.push(generateFontFamilyClass(font.className, font.fontFamily));
-    }
+    cssParts.push(generateFontCss(font));
   }
-
   return cssParts.join('\n\n');
 }
 
@@ -372,20 +388,32 @@ export function timberFonts(ctx: PluginContext): Plugin {
     name: 'timber-fonts',
 
     /**
-     * Resolve `@timber/fonts/google` and `@timber/fonts/local` to virtual modules.
+     * Resolve `@timber/fonts/google`, `@timber/fonts/local`,
+     * and `virtual:timber-font-css` virtual modules.
      */
     resolveId(id: string) {
       if (id === VIRTUAL_GOOGLE) return RESOLVED_GOOGLE;
       if (id === VIRTUAL_LOCAL) return RESOLVED_LOCAL;
+      if (id === VIRTUAL_FONT_CSS) return RESOLVED_FONT_CSS;
       return null;
     },
 
     /**
      * Return generated source for font virtual modules.
+     *
+     * `virtual:timber-font-css` exports the combined @font-face CSS
+     * as a string. The RSC entry imports it and inlines a <style> tag.
+     * Because this is loaded lazily (on first request), the font
+     * registry is always populated by the time it's needed.
      */
     load(id: string) {
       if (id === RESOLVED_GOOGLE) return generateGoogleVirtualModule(registry);
       if (id === RESOLVED_LOCAL) return generateLocalVirtualModule();
+
+      if (id === RESOLVED_FONT_CSS) {
+        const css = generateAllFontCss(registry);
+        return `export default ${JSON.stringify(css)};`;
+      }
       return null;
     },
 
@@ -412,14 +440,8 @@ export function timberFonts(ctx: PluginContext): Plugin {
           return;
         }
 
-        // Serve generated font CSS
-        if (requestedFilename === 'fonts.css') {
-          const css = generateAllFontCss(registry);
-          res.setHeader('Content-Type', 'text/css');
-          res.setHeader('Cache-Control', 'no-cache');
-          res.end(css);
-          return;
-        }
+        // Font CSS is now injected via Vite's CSS pipeline (virtual:timber-font-css modules).
+        // This middleware only serves font binary files (woff2, etc.).
 
         // Find the matching font file in the registry
         for (const font of registry.values()) {
@@ -578,10 +600,6 @@ export function timberFonts(ctx: PluginContext): Plugin {
       }
 
       if (transformedCode !== code) {
-        // Mark that fonts are in use so the RSC entry injects a <link> tag.
-        if (registry.size > 0 && !ctx.fontCssUrl) {
-          ctx.fontCssUrl = FONT_CSS_PATH;
-        }
         return { code: transformedCode, map: null };
       }
 
@@ -627,15 +645,8 @@ export function timberFonts(ctx: PluginContext): Plugin {
         }
       }
 
-      // Emit the combined font CSS as an asset
-      const fontCss = generateAllFontCss(registry);
-      if (fontCss) {
-        this.emitFile({
-          type: 'asset',
-          fileName: '_timber/fonts/fonts.css',
-          source: fontCss,
-        });
-      }
+      // Font CSS is emitted by Vite's CSS pipeline via virtual:timber-font-css modules.
+      // We only need to emit font binary files and update the build manifest here.
 
       if (!ctx.buildManifest) return;
 

package/src/server/action-client.ts

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

package/src/server/pipeline.ts

@@ -487,7 +487,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/response-cache.ts

@@ -10,10 +10,11 @@
  *    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.
+ * Cache keys are compound: pathname + search + isRscPayload + Vary'd headers.
+ * Only GET requests are cached. Responses with Set-Cookie, Cache-Control:
+ * no-store/private, or error/redirect status codes are never cached.
+ * 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.
  */
@@ -65,16 +66,11 @@ interface CacheEntry {
   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;
+  /**
+   * The Vary header value from the original response, if any.
+   * Used to build variant-aware cache keys for subsequent requests.
+   */
+  vary: string | null;
 }
 
 // ─── LRU Cache ─────────────────────────────────────────────────────────────
@@ -154,6 +150,59 @@ export interface ResponseCache {
   clear(): void;
 }
 
+// ─── Cache-Control parsing ─────────────────────────────────────────────────
+
+/**
+ * Check if a Cache-Control header value contains directives that forbid
+ * storing the response in a shared cache. We check for `no-store` and
+ * `private` — both indicate the response must not be reused.
+ *
+ * This is intentionally simple: we don't parse `max-age`, `s-maxage`,
+ * `must-revalidate`, etc. This is a short-TTL render cache, not an HTTP
+ * cache — we just need to respect explicit "don't cache this" signals.
+ */
+function hasCacheControlNoStore(headerValue: string | null): boolean {
+  if (!headerValue) return false;
+  // Split on comma, trim whitespace, check for no-store or private directives.
+  // Case-insensitive per HTTP spec.
+  const lower = headerValue.toLowerCase();
+  return lower.includes('no-store') || lower.includes('private');
+}
+
+// ─── Vary header handling ──────────────────────────────────────────────────
+
+/**
+ * Parse a Vary header value into a sorted list of header names.
+ * Returns null if there is no Vary header or it's empty.
+ * Returns ['*'] if Vary: * (meaning the response varies on everything —
+ * effectively uncacheable).
+ */
+function parseVaryHeader(headerValue: string | null): string[] | null {
+  if (!headerValue) return null;
+  const trimmed = headerValue.trim();
+  if (trimmed === '') return null;
+  if (trimmed === '*') return ['*'];
+
+  // Split on comma, normalize to lowercase, sort for deterministic keys
+  return trimmed
+    .split(',')
+    .map((h) => h.trim().toLowerCase())
+    .filter((h) => h.length > 0)
+    .sort();
+}
+
+/**
+ * Build a Vary-aware suffix for the cache key. For each header name in the
+ * Vary list, append the request's value for that header. This ensures that
+ * requests with different Accept-Language (for example) get different cache
+ * entries.
+ */
+function buildVarySuffix(req: Request, varyHeaders: string[]): string {
+  return varyHeaders.map((h) => `${h}=${req.headers.get(h) ?? ''}`).join('&');
+}
+
+// ─── Factory ───────────────────────────────────────────────────────────────
+
 /**
  * Create a response cache with singleflight deduplication and LRU caching.
  */
@@ -161,7 +210,22 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
   const lru = new LruCache(config.maxSize, config.ttlMs);
   const singleflight = createSingleflight();
 
+  /**
+   * Known Vary headers per path. When a response includes a Vary header,
+   * we store the parsed header names so that subsequent requests to the
+   * same path can include the Vary'd header values in their cache key
+   * BEFORE rendering (i.e., on cache lookup, not just after the first
+   * render). This avoids the "first request always misses" problem for
+   * Vary'd responses.
+   */
+  const knownVaryHeaders = new Map<string, string[]>();
+
   function buildCacheKey(req: Request, isRscPayload: boolean): string | null {
+    // Never cache non-GET requests. POST/PUT/DELETE have side effects and
+    // may carry per-request state (e.g., form flash data via ALS) that makes
+    // the rendered output unique even for the same URL.
+    if (req.method !== 'GET') return null;
+
     // When publicOnly is true, skip caching for authenticated requests
     if (config.publicOnly) {
       if (req.headers.has('Cookie') || req.headers.has('Authorization')) {
@@ -170,13 +234,30 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
     }
 
     const url = new URL(req.url);
-    return `${req.method}:${url.pathname}:${isRscPayload ? 'rsc' : 'html'}`;
+    // Include search params in the cache key. Pages that use searchParams
+    // (e.g., ?sort=asc, ?page=2) produce different output per query string.
+    let key = `${url.pathname}${url.search}:${isRscPayload ? 'rsc' : 'html'}`;
+
+    // If we've seen a Vary header for this path before, include the varied
+    // request header values in the key so different variants get different
+    // cache entries.
+    const pathKey = `${url.pathname}:${isRscPayload ? 'rsc' : 'html'}`;
+    const varyHeaders = knownVaryHeaders.get(pathKey);
+    if (varyHeaders) {
+      if (varyHeaders[0] === '*') {
+        // Vary: * means the response varies on everything — uncacheable
+        return null;
+      }
+      key += ':' + buildVarySuffix(req, varyHeaders);
+    }
+
+    return key;
   }
 
   /**
    * 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.
+   * Responses with Set-Cookie headers, Cache-Control: no-store/private,
+   * error/redirect status codes, or Vary: * are never cached.
    */
   function isCacheable(response: Response): boolean {
     // Don't cache error responses
@@ -188,6 +269,14 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
     // Don't cache responses with Set-Cookie (user-specific state)
     if (response.headers.has('Set-Cookie')) return false;
 
+    // Respect Cache-Control: no-store and private directives.
+    // If the application explicitly says "don't cache this," we obey.
+    if (hasCacheControlNoStore(response.headers.get('Cache-Control'))) return false;
+
+    // Vary: * means the response varies on everything — don't cache
+    const vary = parseVaryHeader(response.headers.get('Vary'));
+    if (vary && vary[0] === '*') return false;
+
     // Only cache responses with a body
     if (!response.body) return false;
 
@@ -196,13 +285,27 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
 
   /** Construct a fresh Response from a cache entry (each caller gets their own). */
   function responseFromEntry(entry: CacheEntry): Response {
+    // Null-body statuses (204, 304) cannot have a body per HTTP spec.
+    // The Response constructor throws if you pass a body with these statuses.
+    const isNullBody = entry.status === 204 || entry.status === 304;
     // slice(0) creates a copy so each caller owns their buffer
-    return new Response(entry.body.slice(0), {
+    return new Response(isNullBody ? null : entry.body.slice(0), {
       status: entry.status,
       headers: entry.headers,
     });
   }
 
+  /**
+   * Record the Vary header from a response so future requests to the same
+   * path include varied header values in their cache key.
+   */
+  function recordVaryHeaders(pathKey: string, response: Response): void {
+    const vary = parseVaryHeader(response.headers.get('Vary'));
+    if (vary) {
+      knownVaryHeaders.set(pathKey, vary);
+    }
+  }
+
   return {
     async getOrRender(
       req: Request,
@@ -211,7 +314,9 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
     ): Promise<Response> {
       const cacheKey = buildCacheKey(req, isRscPayload);
 
-      // No cache key = skip caching entirely
+      // No cache key = skip caching and singleflight entirely.
+      // This covers POST requests, authenticated requests (publicOnly),
+      // and Vary: * responses.
       if (cacheKey === null) {
         return renderFn();
       }
@@ -223,18 +328,41 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
       }
 
       // 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 () => {
+      // We buffer the response body into an ArrayBuffer so ALL callers —
+      // including the singleflight leader — get independent copies.
+      // This fixes the body-loss bug where the leader consumed the body
+      // and concurrent waiters got an empty response.
+      const result: CacheEntry | null = await singleflight.do(cacheKey, async () => {
         const response = await renderFn();
 
+        // Record Vary headers for future cache key construction
+        const url = new URL(req.url);
+        const pathKey = `${url.pathname}:${isRscPayload ? 'rsc' : 'html'}`;
+        recordVaryHeaders(pathKey, response);
+
         if (!isCacheable(response)) {
-          return { response, entry: null };
+          // Buffer the body even for non-cacheable responses so the
+          // singleflight leader and all concurrent waiters each get
+          // an independent copy. Without this, the leader consumes
+          // the body stream and waiters get an empty response.
+          const body = await response.arrayBuffer();
+          const headers: [string, string][] = [];
+          response.headers.forEach((value, key) => {
+            headers.push([key, value]);
+          });
+          // Return as a CacheEntry shape but DON'T store in LRU.
+          // Callers construct Responses from this, but it won't be
+          // reused for future requests.
+          return {
+            body,
+            status: response.status,
+            headers,
+            createdAt: Date.now(),
+            vary: response.headers.get('Vary'),
+          };
         }
 
         // 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) => {
@@ -246,24 +374,28 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
           status: response.status,
           headers,
           createdAt: Date.now(),
+          vary: response.headers.get('Vary'),
         };
 
-        lru.set(cacheKey, entry);
+        // Re-check the cache key now that we know the Vary headers.
+        // The initial key may not have included Vary'd header values
+        // if this was the first request to this path. Rebuild the key
+        // with the now-known Vary headers for correct LRU storage.
+        const updatedKey = buildCacheKey(req, isRscPayload);
+        if (updatedKey) {
+          lru.set(updatedKey, entry);
+        }
 
-        return { response: null, entry };
+        return 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;
+      if (result === null) {
+        // Shouldn't happen — singleflight always returns a result.
+        // Defensive fallback: re-render.
+        return renderFn();
       }
 
-      return responseFromEntry(result.entry!);
+      return responseFromEntry(result);
     },
 
     get size() {
@@ -272,6 +404,7 @@ export function createResponseCache(config: ResolvedResponseCacheConfig): Respon
 
     clear() {
       lru.clear();
+      knownVaryHeaders.clear();
     },
   };
 }

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

@@ -23,6 +23,8 @@ import config from 'virtual:timber-config';
 import buildManifest from 'virtual:timber-build-manifest';
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import loadUserInstrumentation from 'virtual:timber-instrumentation';
+// @ts-expect-error — virtual module provided by timber-fonts plugin
+import fontCss from 'virtual:timber-font-css';
 
 import type { FormRerender } from '#/server/action-handler.js';
 import { handleActionRequest, isActionRequest } from '#/server/action-handler.js';
@@ -368,7 +370,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.
@@ -385,11 +388,11 @@ async function renderRoute(
     headHtml += buildCssLinkTags(cssUrls);
   }
 
-  // Inject font CSS stylesheet — pure CSS, no JS needed.
-  // The URL is set by the timber-fonts plugin when fonts are registered.
-  const fontCssUrl = (config as { fontCssUrl?: string | null }).fontCssUrl;
-  if (fontCssUrl) {
-    headHtml += `<link rel="stylesheet" href="${fontCssUrl}">`;
+  // Inline font CSS as a <style> tag — @font-face rules and scoped classes.
+  // The virtual:timber-font-css module is loaded lazily, so the font registry
+  // is always populated by the time we get here (no timing issues).
+  if (fontCss) {
+    headHtml += `<style data-timber-fonts>${fontCss}</style>`;
   }
 
   const fontEntries = collectRouteFonts(segments, typedManifest);

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

@@ -45,18 +45,45 @@ export async function buildRscPayloadResponse(
   skippedSegments?: string[]
 ): Promise<Response> {
   // Read the first chunk from the RSC stream before committing headers.
+  // Race the first read against signal detection — if an async component
+  // throws a RedirectSignal or DenySignal, the onError callback fires
+  // signals.onSignal() and we can react immediately without waiting for
+  // the full macrotask queue.
+  //
+  // The rejection chain for an async-wrapped page component:
+  //   1. PageComponent throws RedirectSignal
+  //   2. withSpan catches and re-throws (microtask 1)
+  //   3. TracedPage promise rejects (microtask 2)
+  //   4. React Flight rejection handler → onError (microtask 3+)
+  //
+  // Promise.race reacts the instant onError fires, eliminating the
+  // per-request setTimeout(0) macrotask delay for the common case
+  // (no signal). A 50ms ceiling timeout guards against edge cases
+  // where onError never fires.
   const reader = rscStream.getReader();
-  const firstRead = await reader.read();
+  const signalDetected = new Promise<void>((resolve) => {
+    signals.onSignal = resolve;
+  });
 
-  // Yield to the microtask queue so that async component rejections
-  // (e.g. an async-wrapped page component that throws redirect())
-  // 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.
-  //
-  // 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));
+  type RaceResult =
+    | { type: 'data'; chunk: ReadableStreamReadResult<Uint8Array> }
+    | { type: 'signal' };
+
+  const first: RaceResult = await Promise.race([
+    reader.read().then((chunk) => ({ type: 'data' as const, chunk })),
+    signalDetected.then(() => ({ type: 'signal' as const })),
+  ]);
+
+  // If data arrived first, still check signals — they may have fired
+  // concurrently. Also do a final ceiling timeout check for edge cases
+  // where the signal fires just after the first read resolves.
+  if (first.type === 'data' && !signals.redirectSignal && !signals.denySignal) {
+    // Brief yield to let any in-flight microtask rejections complete.
+    await new Promise<void>((r) => setTimeout(r, 0));
+  }
+
+  // Detach the callback — no longer needed after this point.
+  signals.onSignal = undefined;
 
   // Check for redirect/deny signals detected during initial rendering
   const trackedRedirect = signals.redirectSignal as RedirectSignal | null;
@@ -75,6 +102,11 @@ export async function buildRscPayloadResponse(
     );
   }
 
+  // Extract the first chunk from the race result.
+  // If the signal won the race, read the first chunk now (the stream
+  // was already cancelled above, but we need a firstRead shape below).
+  const firstRead = first.type === 'data' ? first.chunk : await reader.read();
+
   // Reconstruct the stream: prepend the buffered first chunk,
   // then continue piping from the original reader.
   const patchedStream = new ReadableStream<Uint8Array>({

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

@@ -24,11 +24,17 @@ import { isDebug } from '#/server/debug.js';
  *
  * Signals fire asynchronously via `onError` during stream consumption.
  * The first signal of each type wins — subsequent signals are ignored.
+ *
+ * `onSignal` is an optional callback fired when a DenySignal or
+ * RedirectSignal is captured. Consumers use it with Promise.race to
+ * react immediately instead of polling with setTimeout/queueMicrotask.
  */
 export interface RenderSignals {
   denySignal: DenySignal | null;
   redirectSignal: RedirectSignal | null;
   renderError: { error: unknown; status: number } | null;
+  /** Callback fired when a redirect or deny signal is captured in onError. */
+  onSignal?: () => void;
 }
 
 export interface RscStreamResult {
@@ -67,11 +73,13 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           if (isAbortError(error) || req.signal?.aborted) return;
           if (error instanceof DenySignal) {
             signals.denySignal = error;
+            signals.onSignal?.();
             // Return structured digest for client-side error boundaries
             return JSON.stringify({ type: 'deny', status: error.status, data: error.data });
           }
           if (error instanceof RedirectSignal) {
             signals.redirectSignal = error;
+            signals.onSignal?.();
             return JSON.stringify({
               type: 'redirect',
               location: error.location,
@@ -98,11 +106,7 @@ export function renderRscStream(element: React.ReactElement, req: Request): RscS
           // directive isn't at the very top of the file, or the component is
           // re-exported through a barrel file without 'use client'.
           // See LOCAL-297.
-          if (
-            isDebug() &&
-            error instanceof Error &&
-            error.message.includes('Invalid hook call')
-          ) {
+          if (isDebug() && error instanceof Error && error.message.includes('Invalid hook call')) {
             console.error(
               '[timber] A React hook was called during RSC rendering. This usually means a ' +
                 "'use client' component is being executed as a server component instead of " +