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

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/node-stream-transforms.ts

@@ -0,0 +1,315 @@
+/**
+ * Node.js native stream transforms for SSR HTML post-processing.
+ *
+ * These are Node.js Transform stream equivalents of the Web Stream
+ * transforms in html-injectors.ts. Used on Node.js/Bun where native
+ * streams (C++ backed) are faster than Web Streams (JS reimplementation).
+ *
+ * The transforms are pure string operations on HTML chunks — the same
+ * logic as the Web Stream versions, just wrapped in Node.js Transform
+ * instead of Web TransformStream.
+ *
+ * Architecture:
+ *   renderToPipeableStream → pipe(errorHandler) → pipe(headInjector)
+ *     → pipe(flightInjector) → Readable.toWeb() → Response
+ *
+ * All chunks stay in C++ Node.js stream buffers until the final
+ * Readable.toWeb() conversion for the Response body.
+ */
+
+import { Transform } from 'node:stream';
+import { createGzip } from 'node:zlib';
+
+// ─── Head Injection ──────────────────────────────────────────────────────────
+
+/**
+ * Node.js Transform that injects HTML content before </head>.
+ *
+ * Equivalent to injectHead() in html-injectors.ts. Streams chunks
+ * through immediately, keeping only a small trailing buffer to handle
+ * </head> split across chunk boundaries.
+ */
+export function createNodeHeadInjector(headHtml: string): Transform {
+  if (!headHtml) {
+    return new Transform({
+      transform(chunk, _enc, cb) {
+        cb(null, chunk);
+      },
+    });
+  }
+
+  const target = '</head>';
+  const tailLen = target.length - 1;
+  let injected = false;
+  let tail = '';
+
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      if (injected) {
+        callback(null, chunk);
+        return;
+      }
+
+      const text = tail + chunk.toString('utf-8');
+      const tagIndex = text.indexOf(target);
+
+      if (tagIndex !== -1) {
+        const before = text.slice(0, tagIndex);
+        const after = text.slice(tagIndex);
+        this.push(Buffer.from(before + headHtml + after, 'utf-8'));
+        injected = true;
+        tail = '';
+        callback();
+      } else {
+        const safeEnd = Math.max(0, text.length - tailLen);
+        if (safeEnd > 0) {
+          this.push(Buffer.from(text.slice(0, safeEnd), 'utf-8'));
+        }
+        tail = text.slice(safeEnd);
+        callback();
+      }
+    },
+    flush(callback) {
+      if (!injected && tail) {
+        this.push(Buffer.from(tail, 'utf-8'));
+      }
+      callback();
+    },
+  });
+}
+
+// ─── RSC Flight Injection ────────────────────────────────────────────────────
+
+/**
+ * Escape a string for safe embedding inside a `<script>` tag within
+ * a JSON-encoded value. Same as htmlEscapeJsonString in html-injectors.ts.
+ */
+function htmlEscapeJsonString(str: string): string {
+  return str
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/**
+ * Node.js Transform that merges RSC script tags into the HTML stream.
+ *
+ * Equivalent to injectRscPayload() in html-injectors.ts. Combines
+ * createInlinedRscStream + createFlightInjectionTransform into a single
+ * Node.js Transform.
+ *
+ * 1. Strips `</body></html>` from the shell so all subsequent content
+ *    is at `<body>` level.
+ * 2. Reads RSC chunks from the provided ReadableStream and injects them
+ *    as `<script>` tags after HTML chunks.
+ * 3. Re-emits `</body></html>` at the very end.
+ *
+ * The RSC stream is a Web ReadableStream (from the tee'd RSC Flight
+ * stream). We read from it using the Web API — this is the one bridge
+ * point between Web Streams and Node.js streams in the pipeline.
+ */
+export function createNodeFlightInjector(
+  rscStream: ReadableStream<Uint8Array> | undefined
+): Transform {
+  if (!rscStream) {
+    return new Transform({
+      transform(chunk, _enc, cb) {
+        cb(null, chunk);
+      },
+    });
+  }
+
+  const suffix = '</body></html>';
+  const suffixBuf = Buffer.from(suffix, 'utf-8');
+  const rscReader = rscStream.getReader();
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+
+  let pullPromise: Promise<void> | null = null;
+  let donePulling = false;
+  let pullError: unknown = null;
+  let foundSuffix = false;
+  let htmlStreamFinished = false;
+  const pending: Buffer[] = [];
+
+  // Emit bootstrap signal
+  const bootstrap = `<script>(self.__timber_f=self.__timber_f||[]).push(${htmlEscapeJsonString(JSON.stringify([0]))})</script>`;
+  pending.push(Buffer.from(bootstrap, 'utf-8'));
+
+  async function pullLoop(): Promise<void> {
+    await new Promise<void>((r) => setImmediate(r));
+    try {
+      for (;;) {
+        const { done, value } = await rscReader.read();
+        if (done) {
+          donePulling = true;
+          return;
+        }
+        const decoded = decoder.decode(value, { stream: true });
+        const escaped = htmlEscapeJsonString(JSON.stringify([1, decoded]));
+        pending.push(Buffer.from(`<script>self.__timber_f.push(${escaped})</script>`, 'utf-8'));
+        if (!htmlStreamFinished) {
+          await new Promise<void>((r) => setImmediate(r));
+        }
+      }
+    } catch (err) {
+      pullError = err;
+      donePulling = true;
+    }
+  }
+
+  function drainPending(transform: Transform): void {
+    while (pending.length > 0) {
+      transform.push(pending.shift()!);
+    }
+    if (pullError) {
+      transform.destroy(pullError instanceof Error ? pullError : new Error(String(pullError)));
+      pullError = null;
+    }
+  }
+
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      if (!pullPromise) {
+        pullPromise = pullLoop();
+      }
+
+      if (foundSuffix) {
+        this.push(chunk);
+        if (pending.length > 0) drainPending(this);
+        callback();
+        return;
+      }
+
+      const text = chunk.toString('utf-8');
+      const idx = text.indexOf(suffix);
+      if (idx !== -1) {
+        foundSuffix = true;
+        const before = text.slice(0, idx);
+        const after = text.slice(idx + suffix.length);
+        if (before) this.push(Buffer.from(before, 'utf-8'));
+        if (pending.length > 0) drainPending(this);
+        if (after) this.push(Buffer.from(after, 'utf-8'));
+      } else {
+        this.push(chunk);
+      }
+      callback();
+    },
+    flush(callback) {
+      htmlStreamFinished = true;
+
+      const finish = () => {
+        drainPending(this);
+        if (foundSuffix) {
+          this.push(suffixBuf);
+        }
+        callback();
+      };
+
+      if (donePulling) {
+        finish();
+        return;
+      }
+      if (!pullPromise) {
+        pullPromise = pullLoop();
+      }
+      pullPromise.then(finish);
+    },
+  });
+}
+
+// ─── Error Handling ──────────────────────────────────────────────────────────
+
+const NOINDEX_SCRIPT =
+  '<script>document.head.appendChild(Object.assign(document.createElement("meta"),{name:"robots",content:"noindex"}))</script>';
+
+/**
+ * Node.js Transform that catches post-shell streaming errors.
+ *
+ * Equivalent to wrapStreamWithErrorHandling() in ssr-render.ts.
+ * Catches errors from React's streaming phase (deny/throw inside Suspense
+ * after the shell has flushed) and closes the stream cleanly.
+ */
+export function createNodeErrorHandler(signal?: AbortSignal): Transform {
+  const transform = new Transform({
+    transform(chunk, _encoding, callback) {
+      callback(null, chunk);
+    },
+  });
+
+  transform.on('error', (error) => {
+    const isAbort =
+      (error instanceof DOMException && error.name === 'AbortError') ||
+      (error instanceof Error && error.name === 'AbortError') ||
+      signal?.aborted;
+
+    if (isAbort) {
+      transform.end();
+      return;
+    }
+
+    console.error('[timber] SSR streaming error (post-shell):', error.message || error);
+    transform.push(Buffer.from(NOINDEX_SCRIPT, 'utf-8'));
+    transform.end();
+  });
+
+  return transform;
+}
+
+// ─── Compression ─────────────────────────────────────────────────────────────
+
+const COMPRESSIBLE_TYPES = new Set([
+  'text/html',
+  'text/css',
+  'text/plain',
+  'text/xml',
+  'text/javascript',
+  'text/x-component',
+  'application/json',
+  'application/javascript',
+  'application/xml',
+  'application/xhtml+xml',
+  'application/rss+xml',
+  'application/atom+xml',
+  'image/svg+xml',
+]);
+
+/**
+ * Create a Node.js gzip Transform using native node:zlib.
+ *
+ * Uses `createGzip()` which is backed by C++ zlib — significantly faster
+ * than the Web Streams `CompressionStream` API (which is a JS wrapper
+ * around the same zlib but with per-chunk Promise overhead).
+ *
+ * Returns null if the response shouldn't be compressed (wrong content type,
+ * client doesn't accept gzip, already encoded, etc.).
+ */
+export function createNodeGzipCompressor(
+  requestHeaders: Headers,
+  responseHeaders: Headers
+): Transform | null {
+  // Check Accept-Encoding
+  const acceptEncoding = requestHeaders.get('accept-encoding') || '';
+  if (!acceptEncoding.includes('gzip')) return null;
+
+  // Check content type is compressible
+  const contentType = responseHeaders.get('content-type') || '';
+  const mimeType = contentType.split(';')[0].trim().toLowerCase();
+  if (!COMPRESSIBLE_TYPES.has(mimeType)) return null;
+
+  // Don't double-compress
+  if (responseHeaders.has('content-encoding')) return null;
+
+  // Set response headers for gzip
+  responseHeaders.set('content-encoding', 'gzip');
+  responseHeaders.delete('content-length');
+  const existingVary = responseHeaders.get('vary');
+  if (existingVary) {
+    if (!existingVary.toLowerCase().includes('accept-encoding')) {
+      responseHeaders.set('vary', existingVary + ', Accept-Encoding');
+    }
+  } else {
+    responseHeaders.set('vary', 'Accept-Encoding');
+  }
+
+  return createGzip();
+}

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