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

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

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

@@ -45,15 +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;
+  });
+
+  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 })),
+  ]);
 
-  // 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.
-  await new Promise<void>((r) => setTimeout(r, 0));
+  // 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;
@@ -72,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

@@ -17,17 +17,24 @@ import { DenySignal, RedirectSignal, RenderError } from '#/server/primitives.js'
 import { checkAndWarnRscPropError } from '#/server/rsc-prop-warnings.js';
 
 import { createDebugChannelSink, isAbortError } from './helpers.js';
+import { isDebug } from '#/server/debug.js';
 
 /**
  * Mutable signal state captured during RSC rendering.
  *
  * 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 {
@@ -66,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,
@@ -97,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 (
-            process.env.NODE_ENV !== 'production' &&
-            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 " +

package/src/server/rsc-entry/ssr-renderer.ts

@@ -156,12 +156,19 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
   try {
     const ssrResponse = await callSsr(ssrStream, navContext);
 
-    // Signal promotion: yield one tick so async component rejections
-    // propagate to the RSC onError callback, then check if any signals
-    // were captured during rendering inside Suspense boundaries.
-    // The Response hasn't been sent yet — it's an unconsumed stream.
+    // Signal promotion: check if any signals were captured during rendering
+    // inside Suspense boundaries. If no signals are present yet, yield one
+    // microtask so async component rejections propagate to the RSC onError
+    // callback before we commit the response.
+    //
+    // When signals are already captured (onSignal already fired), skip the
+    // yield entirely — react immediately. Uses queueMicrotask instead of
+    // setTimeout(0) for the fallback to avoid yielding to the full event
+    // loop (timers phase).
     // See design/05-streaming.md §"deferSuspenseFor and the Hold Window"
-    await new Promise<void>((r) => setTimeout(r, 0));
+    if (!signals.redirectSignal && !signals.denySignal && !signals.renderError) {
+      await new Promise<void>((r) => queueMicrotask(r));
+    }
 
     const promoted = checkCapturedSignals(/* skipHandledDeny */ true);
     if (promoted) {

package/src/server/rsc-prop-warnings.ts

@@ -16,6 +16,8 @@
  * Task: TIM-358
  */
 
+import { isDebug } from './debug.js';
+
 // ─── Types ────────────────────────────────────────────────────────────────
 
 export interface NonSerializableTypeInfo {
@@ -165,7 +167,7 @@ export function formatRscPropWarning(
  * @returns true if a warning was emitted
  */
 export function checkAndWarnRscPropError(error: unknown, requestPath: string): boolean {
-  if (process.env.NODE_ENV === 'production') return false;
+  if (!isDebug()) return false;
   if (!(error instanceof Error)) return false;
 
   const info = detectNonSerializableType(error.message);

package/src/server/ssr-entry.ts

@@ -14,10 +14,20 @@
 
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import config from 'virtual:timber-config';
-import { createFromReadableStream } from '#/rsc-runtime/ssr.js';
+import {
+  createFromReadableStream,
+  createFromNodeStream,
+  hasNodeStreamDecode,
+} from '#/rsc-runtime/ssr.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-import { renderSsrStream, buildSsrResponse } from './ssr-render.js';
+import {
+  renderSsrStream,
+  renderSsrNodeStream,
+  nodeReadableToWeb,
+  useNodeStreams,
+  buildSsrResponse,
+} from './ssr-render.js';
 import { formatSsrError } from './error-formatter.js';
 import { SsrStreamError } from './primitives.js';
 import { injectHead, injectRscPayload } from './html-injectors.js';
@@ -26,6 +36,41 @@ import { withSpan } from './tracing.js';
 import { setCurrentParams } from '#/client/use-params.js';
 import { registerSsrDataProvider, type SsrData } from '#/client/ssr-data.js';
 
+// Pre-import Node.js stream modules at module load time — not per-request.
+// Dynamic imports of node-stream-transforms and node:stream/promises were
+// costing 3-17ms per request due to module resolution overhead.
+let _nodeStreamImports: {
+  createNodeHeadInjector: typeof import('./node-stream-transforms.js').createNodeHeadInjector;
+  createNodeFlightInjector: typeof import('./node-stream-transforms.js').createNodeFlightInjector;
+  createNodeErrorHandler: typeof import('./node-stream-transforms.js').createNodeErrorHandler;
+  pipeline: typeof import('node:stream/promises').pipeline;
+  PassThrough: typeof import('node:stream').PassThrough;
+  ReadableFromWeb: (
+    webStream: import('stream/web').ReadableStream
+  ) => import('node:stream').Readable;
+} | null = null;
+
+if (useNodeStreams) {
+  try {
+    const [transforms, streamPromises, stream] = await Promise.all([
+      import('./node-stream-transforms.js'),
+      import('node:stream/promises'),
+      import('node:stream'),
+    ]);
+    _nodeStreamImports = {
+      createNodeHeadInjector: transforms.createNodeHeadInjector,
+      createNodeFlightInjector: transforms.createNodeFlightInjector,
+      createNodeErrorHandler: transforms.createNodeErrorHandler,
+      pipeline: streamPromises.pipeline,
+      PassThrough: stream.PassThrough,
+      ReadableFromWeb: (webStream: import('stream/web').ReadableStream) =>
+        stream.Readable.fromWeb(webStream) as import('node:stream').Readable,
+    };
+  } catch {
+    // Fall back to Web Streams path
+  }
+}
+
 // ─── SSR Data ALS ─────────────────────────────────────────────────────────
 //
 // Per-request SSR data stored in AsyncLocalStorage, ensuring correct
@@ -137,7 +182,25 @@ export async function handleSsr(
       // createFromReadableStream resolves client component references
       // (from "use client" modules) using the SSR environment's module
       // map, importing the actual components for server-side rendering.
-      const element = createFromReadableStream(rscStream) as React.ReactNode;
+      const _s0 = performance.now();
+      // eslint-disable-next-line no-console
+      console.log(
+        `[diag] nodeImports=${!!_nodeStreamImports} nodeStreamDecode=${hasNodeStreamDecode} rscStream=${rscStream?.constructor?.name}`
+      );
+      // Decode the RSC stream into a React element tree.
+      // On Node.js: convert Web ReadableStream → Node Readable → createFromNodeStream
+      //   (eliminates Promise-per-chunk overhead from Web Streams reader)
+      // On Workers: createFromReadableStream (Web Streams are V8-native C++ there)
+      let element: React.ReactNode;
+      if (hasNodeStreamDecode && _nodeStreamImports) {
+        const nodeRscStream = _nodeStreamImports.ReadableFromWeb(
+          rscStream as import('stream/web').ReadableStream
+        );
+        element = createFromNodeStream(nodeRscStream) as React.ReactNode;
+      } else {
+        element = createFromReadableStream(rscStream) as React.ReactNode;
+      }
+      const _s1 = performance.now();
 
       // Wrap with a server-safe nuqs adapter so that 'use client' components
       // that call nuqs hooks (useQueryStates, useQueryState) can SSR correctly.
@@ -145,12 +208,76 @@ export async function handleSsr(
       // over after hydration. This provider supplies the request's search params
       // as a static snapshot so nuqs renders the right initial values on the server.
       const wrappedElement = withNuqsSsrAdapter(navContext.searchParams, element);
+      const _s2 = performance.now();
 
       // Render to HTML stream (waits for onShellReady).
       // Pass bootstrapScriptContent so React injects a non-deferred <script>
       // in the shell HTML. This executes immediately during parsing — even
       // while Suspense boundaries are still streaming — triggering module
       // loading via dynamic import() so hydration can start early.
+      //
+      // Two paths based on platform:
+      // - Node.js: renderToPipeableStream → Node Transform pipeline → Readable.toWeb() → Response
+      //   Entire pipeline stays in C++ native streams until the Response boundary.
+      // - Workers: renderToReadableStream → Web TransformStream pipeline → Response
+      //   Web Streams are V8-native C++ built-ins on Workers.
+      if (_nodeStreamImports) {
+        // Node.js fast path: full pipeline in native streams
+        const {
+          createNodeHeadInjector,
+          createNodeFlightInjector,
+          createNodeErrorHandler,
+          pipeline,
+          PassThrough,
+        } = _nodeStreamImports;
+
+        const _s3 = performance.now();
+        let nodeHtmlStream: import('node:stream').Readable;
+        try {
+          nodeHtmlStream = await renderSsrNodeStream(wrappedElement, {
+            bootstrapScriptContent: navContext.bootstrapScriptContent || undefined,
+            deferSuspenseFor: navContext.deferSuspenseFor,
+            signal: navContext.signal,
+          });
+        } catch (renderError) {
+          console.error(
+            '[timber] SSR shell failed from RSC stream error:',
+            formatSsrError(renderError)
+          );
+          throw new SsrStreamError(
+            'SSR renderToReadableStream failed due to RSC stream error',
+            renderError
+          );
+        }
+
+        // Build Node.js Transform pipeline: errorHandler → headInjector → flightInjector → gzip
+        const errorHandler = createNodeErrorHandler(navContext.signal);
+        const headInjector = createNodeHeadInjector(navContext.headHtml);
+        const flightInjector = createNodeFlightInjector(navContext.rscStream);
+
+        // Pipe through the chain. pipeline() handles backpressure and error propagation.
+        // The last stream in the chain is the output — convert to Web ReadableStream
+        // only at the Response boundary.
+        // Note: gzip compression is still handled by compressResponse() in the Nitro
+        // entry via Web Streams CompressionStream. Moving it into this Node.js pipeline
+        // requires the request headers (Accept-Encoding) which NavContext doesn't carry.
+        // TODO: pass request headers through NavContext to enable inline Node.js gzip.
+        const output = new PassThrough();
+        pipeline(nodeHtmlStream, errorHandler, headInjector, flightInjector, output).catch(() => {
+          // Pipeline errors are handled by errorHandler transform
+        });
+
+        const _s4 = performance.now();
+        // eslint-disable-next-line no-console
+        console.log(
+          `[ssr-perf] decode=${(_s1 - _s0).toFixed(1)}ms nuqs=${(_s2 - _s1).toFixed(1)}ms imports=${(_s3 - _s2).toFixed(1)}ms renderToPipeable=${(_s4 - _s3).toFixed(1)}ms pipeline=${(performance.now() - _s4).toFixed(1)}ms total=${(performance.now() - _s0).toFixed(1)}ms`
+        );
+
+        const webStream = nodeReadableToWeb(output);
+        return buildSsrResponse(webStream, navContext.statusCode, navContext.responseHeaders);
+      }
+
+      // Web Streams path (CF Workers / fallback)
       let htmlStream: ReadableStream<Uint8Array>;
       try {
         htmlStream = await renderSsrStream(wrappedElement, {
@@ -159,11 +286,6 @@ export async function handleSsr(
           signal: navContext.signal,
         });
       } catch (renderError) {
-        // SSR shell rendering failed — the RSC stream contained an error
-        // that wasn't caught by any error boundary in the decoded tree.
-        // Wrap in SsrStreamError so the RSC entry can handle it without
-        // re-executing server components via renderDenyPage.
-        // See LOCAL-293.
         console.error(
           '[timber] SSR shell failed from RSC stream error:',
           formatSsrError(renderError)