@timber-js/app 0.2.0-alpha.22 → 0.2.0-alpha.23

package/dist/server/ssr-render.d.ts

@@ -5,6 +5,17 @@
  * independently of the Vite RSC plugin runtime (which provides
  * createFromReadableStream for decoding RSC streams).
  *
+ * Uses a platform-adaptive rendering strategy:
+ * - **Node.js / Bun**: `renderToPipeableStream` — React pipes HTML chunks
+ *   through Node.js native streams (C++ implementation). Each chunk flows
+ *   through libuv buffers with zero Promise overhead.
+ * - **Cloudflare Workers / Edge**: `renderToReadableStream` — React outputs
+ *   to Web Streams which are V8-native C++ built-ins on these platforms.
+ *
+ * The detection is automatic at runtime. Both paths produce a Web
+ * `ReadableStream<Uint8Array>` so downstream transforms (injectHead,
+ * injectRscPayload, compression) work identically regardless of platform.
+ *
  * Design docs: 02-rendering-pipeline.md §"Single-Pass Rendering",
  *              18-build-system.md §"Entry Files"
  */
@@ -12,24 +23,15 @@ import type { ReactNode } from 'react';
 /**
  * Render a React element tree to a ReadableStream of HTML.
  *
- * Uses renderToReadableStream (NOT renderToString) for streaming SSR.
+ * Automatically selects the optimal rendering path for the platform:
+ * - Node.js/Bun: `renderToPipeableStream` → Node.js native streams → `Readable.toWeb()`
+ * - CF Workers/Edge: `renderToReadableStream` → native Web Streams
+ *
  * The returned stream begins yielding after onShellReady — everything
  * outside <Suspense> boundaries is in the shell.
  *
- * With progressive streaming, the RSC stream is piped directly to SSR
- * without buffering. If deny() was called outside a Suspense boundary,
- * the RSC stream encodes an error in the shell — renderToReadableStream
- * rejects, and the RSC entry catches this to render a deny page with
- * the correct HTTP status code. If deny() was inside Suspense, the shell
- * succeeds (200 committed) and the error streams as an error boundary.
- *
  * @param element - The React element tree decoded from the RSC stream
  * @param options - Optional configuration
- * @param options.bootstrapScriptContent - Inline JS injected by React as a
- *   non-deferred `<script>` in the shell HTML. Executes immediately during
- *   parsing — even while Suspense boundaries are still streaming. Used to
- *   kick off module loading via dynamic `import()` so hydration can start
- *   before the HTML stream closes.
  * @returns A ReadableStream of HTML bytes with hydration markers
  */
 export declare function renderSsrStream(element: ReactNode, options?: {
@@ -42,9 +44,9 @@ export declare function renderSsrStream(element: ReactNode, options?: {
  *
  * During progressive RSC→SSR streaming, errors in Suspense boundaries
  * (e.g. deny() inside Suspense, throws in async components) cause
- * React DOM's renderToReadableStream to error after the shell has been
- * flushed. Without this wrapper, the stream error becomes an unhandled
- * promise rejection that crashes the process.
+ * React DOM's stream to error after the shell has been flushed. Without
+ * this wrapper, the stream error becomes an unhandled promise rejection
+ * that crashes the process.
  *
  * The wrapper catches streaming-phase errors, logs them, and closes
  * the output stream cleanly. The shell (headers, status code, content
@@ -57,11 +59,6 @@ export declare function wrapStreamWithErrorHandling(stream: ReadableStream<Uint8
  * status code and headers from the navigation context.
  *
  * Sets content-type to text/html if not already set by middleware.
- *
- * @param htmlStream - The HTML stream from renderSsrStream
- * @param statusCode - The committed HTTP status code from RSC
- * @param responseHeaders - Response headers from middleware/proxy
- * @returns A Response ready to send to the client
  */
 export declare function buildSsrResponse(htmlStream: ReadableStream<Uint8Array>, statusCode: number, responseHeaders: Headers): Response;
 //# sourceMappingURL=ssr-render.d.ts.map

package/dist/server/ssr-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr-render.d.ts","sourceRoot":"","sources":["../../src/server/ssr-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAmBvC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IAAE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC7F,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAmDrC;AAED;;;;;;;;;;;;GAYG;AACH,2CAA2C;AAC3C,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,UAAU,CAAC,CAkC5B;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,OAAO,GACvB,QAAQ,CASV"}
+{"version":3,"file":"ssr-render.d.ts","sourceRoot":"","sources":["../../src/server/ssr-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AA0DvC;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IAAE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC7F,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAKrC;AAkHD;;;;;;;;;;;;GAYG;AACH,2CAA2C;AAC3C,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,UAAU,CAAC,CA2B5B;AAWD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,OAAO,GACvB,QAAQ,CASV"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.22",
+  "version": "0.2.0-alpha.23",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/server/ssr-render.ts

@@ -5,12 +5,23 @@
  * independently of the Vite RSC plugin runtime (which provides
  * createFromReadableStream for decoding RSC streams).
  *
+ * Uses a platform-adaptive rendering strategy:
+ * - **Node.js / Bun**: `renderToPipeableStream` — React pipes HTML chunks
+ *   through Node.js native streams (C++ implementation). Each chunk flows
+ *   through libuv buffers with zero Promise overhead.
+ * - **Cloudflare Workers / Edge**: `renderToReadableStream` — React outputs
+ *   to Web Streams which are V8-native C++ built-ins on these platforms.
+ *
+ * The detection is automatic at runtime. Both paths produce a Web
+ * `ReadableStream<Uint8Array>` so downstream transforms (injectHead,
+ * injectRscPayload, compression) work identically regardless of platform.
+ *
  * Design docs: 02-rendering-pipeline.md §"Single-Pass Rendering",
  *              18-build-system.md §"Entry Files"
  */
 
 import type { ReactNode } from 'react';
-import { renderToReadableStream } from 'react-dom/server';
+import { renderToReadableStream, renderToPipeableStream } from 'react-dom/server';
 
 import { formatSsrError } from './error-formatter.js';
 
@@ -28,60 +39,167 @@ import { formatSsrError } from './error-formatter.js';
 const NOINDEX_SCRIPT =
   '<script>document.head.appendChild(Object.assign(document.createElement("meta"),{name:"robots",content:"noindex"}))</script>';
 
+// ─── Platform Detection ──────────────────────────────────────────────────────
+//
+// Detect whether we're running on a platform with native Node.js streams.
+// On Node.js/Bun, `node:stream` is backed by C++ (libuv). On Cloudflare
+// Workers, `node:stream` via nodejs_compat is a JS polyfill — Web Streams
+// are the faster path there (V8-native C++ built-ins).
+//
+// We detect once at module load to avoid per-request overhead.
+// The check: process.versions.node exists AND we can import node:stream.
+// Cloudflare Workers with nodejs_compat may polyfill process.versions but
+// the streams won't be native. The Readable.toWeb check confirms native support.
+
+let _useNodeStreams = false;
+let _PassThrough: typeof import('node:stream').PassThrough | null = null;
+let _ReadableToWeb: ((readable: import('node:stream').Readable) => ReadableStream) | null = null;
+
+try {
+  // Dynamic import to avoid bundling node:stream for CF Workers builds.
+  // On Node.js/Bun this resolves to native C++ streams.
+  // On CF Workers this either fails or returns a JS polyfill.
+  const nodeStream = await import('node:stream');
+  if (
+    typeof nodeStream.PassThrough === 'function' &&
+    typeof nodeStream.Readable.toWeb === 'function' &&
+    // Real Node.js — not a polyfill. Polyfills typically don't set
+    // process.release.name to 'node'.
+    typeof process !== 'undefined' &&
+    process.release?.name === 'node'
+  ) {
+    _useNodeStreams = true;
+    _PassThrough = nodeStream.PassThrough;
+    _ReadableToWeb = nodeStream.Readable.toWeb as (
+      readable: import('node:stream').Readable
+    ) => ReadableStream;
+  }
+} catch {
+  // node:stream not available — use Web Streams path
+}
+
 /**
  * Render a React element tree to a ReadableStream of HTML.
  *
- * Uses renderToReadableStream (NOT renderToString) for streaming SSR.
+ * Automatically selects the optimal rendering path for the platform:
+ * - Node.js/Bun: `renderToPipeableStream` → Node.js native streams → `Readable.toWeb()`
+ * - CF Workers/Edge: `renderToReadableStream` → native Web Streams
+ *
  * The returned stream begins yielding after onShellReady — everything
  * outside <Suspense> boundaries is in the shell.
  *
- * With progressive streaming, the RSC stream is piped directly to SSR
- * without buffering. If deny() was called outside a Suspense boundary,
- * the RSC stream encodes an error in the shell — renderToReadableStream
- * rejects, and the RSC entry catches this to render a deny page with
- * the correct HTTP status code. If deny() was inside Suspense, the shell
- * succeeds (200 committed) and the error streams as an error boundary.
- *
  * @param element - The React element tree decoded from the RSC stream
  * @param options - Optional configuration
- * @param options.bootstrapScriptContent - Inline JS injected by React as a
- *   non-deferred `<script>` in the shell HTML. Executes immediately during
- *   parsing — even while Suspense boundaries are still streaming. Used to
- *   kick off module loading via dynamic `import()` so hydration can start
- *   before the HTML stream closes.
  * @returns A ReadableStream of HTML bytes with hydration markers
  */
 export async function renderSsrStream(
   element: ReactNode,
   options?: { bootstrapScriptContent?: string; deferSuspenseFor?: number; signal?: AbortSignal }
+): Promise<ReadableStream<Uint8Array>> {
+  if (_useNodeStreams) {
+    return renderViaPipeableStream(element, options);
+  }
+  return renderViaReadableStream(element, options);
+}
+
+// ─── Node.js Path: renderToPipeableStream ────────────────────────────────────
+//
+// Uses React's Node.js-native API. HTML chunks flow through C++ stream
+// buffers with zero Promise allocations per chunk. The PassThrough stream
+// is converted to a Web ReadableStream via Readable.toWeb() (zero-copy
+// bridge available in Node.js 17+) for compatibility with downstream
+// Web Stream transforms (injectHead, injectRscPayload).
+
+async function renderViaPipeableStream(
+  element: ReactNode,
+  options?: { bootstrapScriptContent?: string; deferSuspenseFor?: number; signal?: AbortSignal }
+): Promise<ReadableStream<Uint8Array>> {
+  const signal = options?.signal;
+  const deferMs = options?.deferSuspenseFor;
+
+  return new Promise<ReadableStream<Uint8Array>>((resolve, reject) => {
+    const passthrough = new _PassThrough!();
+
+    let allReadyResolve: (() => void) | null = null;
+    const allReady = new Promise<void>((r) => {
+      allReadyResolve = r;
+    });
+    // Suppress unhandled rejection if nobody awaits allReady
+    allReady.catch(() => {});
+
+    const { pipe, abort } = renderToPipeableStream(element, {
+      bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
+
+      onShellReady() {
+        // deferSuspenseFor: delay piping so React can resolve fast-completing
+        // Suspense boundaries before we read the shell. When we delay, React
+        // inlines resolved content instead of serializing fallbacks.
+        // See design/05-streaming.md §"deferSuspenseFor"
+        if (deferMs && deferMs > 0) {
+          Promise.race([allReady, new Promise<void>((r) => setTimeout(r, deferMs))]).then(() => {
+            pipe(passthrough);
+            const webStream = _ReadableToWeb!(passthrough) as ReadableStream<Uint8Array>;
+            resolve(wrapStreamWithErrorHandling(webStream, signal));
+          });
+        } else {
+          pipe(passthrough);
+          const webStream = _ReadableToWeb!(passthrough) as ReadableStream<Uint8Array>;
+          resolve(wrapStreamWithErrorHandling(webStream, signal));
+        }
+      },
+
+      onAllReady() {
+        allReadyResolve?.();
+      },
+
+      onShellError(error: unknown) {
+        reject(error);
+      },
+
+      onError(error: unknown) {
+        // Suppress connection abort logging — not an application error.
+        if (isAbortError(error) || signal?.aborted) return;
+        console.error('[timber] SSR render error:', formatSsrError(error));
+      },
+    });
+
+    // Wire up abort signal — cancel React rendering if the client disconnects.
+    if (signal) {
+      if (signal.aborted) {
+        abort();
+      } else {
+        signal.addEventListener('abort', () => abort(), { once: true });
+      }
+    }
+  });
+}
+
+// ─── Web Streams Path: renderToReadableStream ────────────────────────────────
+//
+// Uses React's Web Streams API. On Cloudflare Workers, ReadableStream is a
+// V8-native C++ built-in, making this the fastest path for that platform.
+// On Node.js, Web Streams are a JS reimplementation — slower, but this path
+// is only used as a fallback when Node.js native streams aren't available.
+
+async function renderViaReadableStream(
+  element: ReactNode,
+  options?: { bootstrapScriptContent?: string; deferSuspenseFor?: number; signal?: AbortSignal }
 ): Promise<ReadableStream<Uint8Array>> {
   const signal = options?.signal;
   const stream = await renderToReadableStream(element, {
     bootstrapScriptContent: options?.bootstrapScriptContent || undefined,
     signal,
     onError(error: unknown) {
-      // Suppress logging for connection aborts — the user refreshed or
-      // navigated away, not an application error.
       if (isAbortError(error) || signal?.aborted) return;
       console.error('[timber] SSR render error:', formatSsrError(error));
     },
   });
 
   // Prevent unhandled promise rejection from streaming-phase errors.
-  // React DOM Server exposes `allReady` — a promise that resolves when
-  // ALL content (including Suspense boundaries) has been rendered. If a
-  // streaming-phase error occurs (e.g. React boundary flush failure),
-  // `allReady` rejects independently of the stream. Without this catch,
-  // the rejection becomes an unhandled promise rejection that crashes
-  // the Node.js process.
   stream.allReady.catch(() => {});
 
   // deferSuspenseFor hold: delay the first read so React can resolve
   // fast-completing Suspense boundaries before we read the shell HTML.
-  // renderToReadableStream generates HTML lazily on pull — if we wait
-  // before reading, React resolves pending boundaries and inlines their
-  // content instead of serializing fallbacks. Race allReady against
-  // deferSuspenseFor so we don't wait longer than necessary.
   // See design/05-streaming.md §"deferSuspenseFor"
   const deferMs = options?.deferSuspenseFor;
   if (deferMs && deferMs > 0) {
@@ -91,30 +209,19 @@ export async function renderSsrStream(
     ]);
   }
 
-  // renderToReadableStream resolves after onShellReady by default.
-  // The stream is ready to read — the shell (everything outside
-  // Suspense boundaries) is available. Suspense content streams
-  // into the open connection as it resolves.
-  //
-  // Wrap the stream in an error-resilient transform. With progressive
-  // streaming, errors inside Suspense boundaries (e.g. deny() or throws
-  // in async components) cause React's stream to error during the flush
-  // phase. The onError callback logs the error, but the stream error
-  // would become an unhandled promise rejection and crash the process.
-  // The transform catches these post-shell streaming errors and closes
-  // the stream cleanly — the shell (with correct status code) has
-  // already been sent.
   return wrapStreamWithErrorHandling(stream, signal);
 }
 
+// ─── Shared Utilities ────────────────────────────────────────────────────────
+
 /**
  * Wrap an HTML stream with error handling for the streaming phase.
  *
  * During progressive RSC→SSR streaming, errors in Suspense boundaries
  * (e.g. deny() inside Suspense, throws in async components) cause
- * React DOM's renderToReadableStream to error after the shell has been
- * flushed. Without this wrapper, the stream error becomes an unhandled
- * promise rejection that crashes the process.
+ * React DOM's stream to error after the shell has been flushed. Without
+ * this wrapper, the stream error becomes an unhandled promise rejection
+ * that crashes the process.
  *
  * The wrapper catches streaming-phase errors, logs them, and closes
  * the output stream cleanly. The shell (headers, status code, content
@@ -138,17 +245,10 @@ export function wrapStreamWithErrorHandling(
         }
         controller.enqueue(value);
       } catch (error) {
-        // Connection abort (user refreshed or navigated away) — close
-        // silently without logging. This is not an application error.
         if (isAbortError(error) || signal?.aborted) {
           controller.close();
           return;
         }
-        // Streaming-phase error (e.g. React boundary flush failure,
-        // deny() or throw inside Suspense after flush).
-        // The shell has already been sent with status 200. Inject a
-        // noindex meta tag so search engines don't index this error page,
-        // then close cleanly. See design/05-streaming.md.
         console.error('[timber] SSR streaming error (post-shell):', formatSsrError(error));
         controller.enqueue(encoder.encode(NOINDEX_SCRIPT));
         controller.close();
@@ -162,10 +262,6 @@ export function wrapStreamWithErrorHandling(
 
 /**
  * Check if an error is an abort error (connection closed by client).
- *
- * When the browser aborts a request (page refresh, navigation away),
- * the AbortSignal fires and React/streams throw an AbortError. This
- * is not an application error — suppress it from error boundaries and logs.
  */
 function isAbortError(error: unknown): boolean {
   if (error instanceof DOMException && error.name === 'AbortError') return true;
@@ -178,11 +274,6 @@ function isAbortError(error: unknown): boolean {
  * status code and headers from the navigation context.
  *
  * Sets content-type to text/html if not already set by middleware.
- *
- * @param htmlStream - The HTML stream from renderSsrStream
- * @param statusCode - The committed HTTP status code from RSC
- * @param responseHeaders - Response headers from middleware/proxy
- * @returns A Response ready to send to the client
  */
 export function buildSsrResponse(
   htmlStream: ReadableStream<Uint8Array>,