@timber-js/app 0.2.0-alpha.27 → 0.2.0-alpha.29

package/dist/rsc-runtime/ssr.d.ts

@@ -10,4 +10,16 @@
  * point, not abstraction.
  */
 export { createFromReadableStream } from '@vitejs/plugin-rsc/ssr';
+/**
+ * Decode an RSC Flight stream from a Node.js Readable.
+ *
+ * Uses the vendored createFromNodeStream which reads via Node.js native
+ * streams (C++ libuv) instead of Web ReadableStream (JS Promise per chunk).
+ *
+ * Returns null if createFromNodeStream isn't available (CF Workers, etc),
+ * signaling the caller to use createFromReadableStream instead.
+ */
+export declare function createFromNodeStream(stream: import('node:stream').Readable): React.ReactNode | null;
+/** Whether the Node.js stream RSC decode path is available. */
+export declare const hasNodeStreamDecode: boolean;
 //# sourceMappingURL=ssr.d.ts.map

package/dist/rsc-runtime/ssr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr.d.ts","sourceRoot":"","sources":["../../src/rsc-runtime/ssr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"ssr.d.ts","sourceRoot":"","sources":["../../src/rsc-runtime/ssr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAiClE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,aAAa,EAAE,QAAQ,GACrC,KAAK,CAAC,SAAS,GAAG,IAAI,CAGxB;AAED,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,SAAiC,CAAC"}

package/dist/server/node-stream-transforms.d.ts

@@ -51,4 +51,15 @@ export declare function createNodeFlightInjector(rscStream: ReadableStream<Uint8
  * after the shell has flushed) and closes the stream cleanly.
  */
 export declare function createNodeErrorHandler(signal?: AbortSignal): Transform;
+/**
+ * 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 declare function createNodeGzipCompressor(requestHeaders: Headers, responseHeaders: Headers): Transform | null;
 //# sourceMappingURL=node-stream-transforms.d.ts.map

package/dist/server/node-stream-transforms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-stream-transforms.d.ts","sourceRoot":"","sources":["../../src/server/node-stream-transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxC;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA+ClE;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,GAChD,SAAS,CAyGX;AAOD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAwBtE"}
+{"version":3,"file":"node-stream-transforms.d.ts","sourceRoot":"","sources":["../../src/server/node-stream-transforms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA+ClE;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,GAChD,SAAS,CAyGX;AAOD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAwBtE;AAoBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,OAAO,EACvB,eAAe,EAAE,OAAO,GACvB,SAAS,GAAG,IAAI,CA0BlB"}

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

@@ -1 +1 @@
-{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmCH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAgInB;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA0EH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAqJnB;AAED,eAAe,SAAS,CAAC"}

package/package.json

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

package/src/rsc-runtime/ssr.ts

@@ -11,3 +11,53 @@
  */
 
 export { createFromReadableStream } from '@vitejs/plugin-rsc/ssr';
+
+// ─── Node.js Stream Path ─────────────────────────────────────────────────────
+//
+// On Node.js, createFromNodeStream reads RSC Flight data from a Node.js
+// Readable (C++ backed) instead of a Web ReadableStream (JS reimplementation).
+// Eliminates Promise-per-chunk overhead on the SSR decode path.
+//
+// The plugin only exports createFromReadableStream (via client.edge.js).
+// createFromNodeStream lives in the vendored client.node.js. We import it
+// directly and wire up the same serverConsumerManifest the plugin uses.
+
+import { createServerConsumerManifest } from '@vitejs/plugin-rsc/ssr';
+
+type CreateFromNodeStreamFn = (
+  stream: import('node:stream').Readable,
+  manifest: ReturnType<typeof createServerConsumerManifest>,
+  options?: Record<string, unknown>
+) => React.ReactNode;
+
+let _createFromNodeStream: CreateFromNodeStreamFn | null = null;
+
+try {
+  if (typeof process !== 'undefined' && process.release?.name === 'node') {
+    const clientNode = await import('@vitejs/plugin-rsc/vendor/react-server-dom/client.node');
+    if (typeof clientNode.createFromNodeStream === 'function') {
+      _createFromNodeStream = clientNode.createFromNodeStream;
+    }
+  }
+} catch {
+  // Not available — fall back to createFromReadableStream
+}
+
+/**
+ * Decode an RSC Flight stream from a Node.js Readable.
+ *
+ * Uses the vendored createFromNodeStream which reads via Node.js native
+ * streams (C++ libuv) instead of Web ReadableStream (JS Promise per chunk).
+ *
+ * Returns null if createFromNodeStream isn't available (CF Workers, etc),
+ * signaling the caller to use createFromReadableStream instead.
+ */
+export function createFromNodeStream(
+  stream: import('node:stream').Readable
+): React.ReactNode | null {
+  if (!_createFromNodeStream) return null;
+  return _createFromNodeStream(stream, createServerConsumerManifest());
+}
+
+/** Whether the Node.js stream RSC decode path is available. */
+export const hasNodeStreamDecode = _createFromNodeStream !== null;

package/src/rsc-runtime/vendor-types.d.ts

@@ -0,0 +1,7 @@
+declare module '@vitejs/plugin-rsc/vendor/react-server-dom/client.node' {
+  export function createFromNodeStream(
+    stream: import('node:stream').Readable,
+    manifest: unknown,
+    options?: Record<string, unknown>
+  ): React.ReactNode;
+}

package/src/server/node-stream-transforms.ts

@@ -18,6 +18,7 @@
  */
 
 import { Transform } from 'node:stream';
+import { createGzip } from 'node:zlib';
 
 // ─── Head Injection ──────────────────────────────────────────────────────────
 
@@ -253,3 +254,62 @@ export function createNodeErrorHandler(signal?: AbortSignal): Transform {
 
   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/ssr-entry.ts

@@ -14,7 +14,11 @@
 
 // @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 {
@@ -32,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
@@ -144,7 +183,19 @@ export async function handleSsr(
       // (from "use client" modules) using the SSR environment's module
       // map, importing the actual components for server-side rendering.
       const _s0 = performance.now();
-      const element = createFromReadableStream(rscStream) as React.ReactNode;
+      // 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
@@ -166,11 +217,15 @@ export async function handleSsr(
       //   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 (useNodeStreams) {
+      if (_nodeStreamImports) {
         // Node.js fast path: full pipeline in native streams
-        const { createNodeHeadInjector, createNodeFlightInjector, createNodeErrorHandler } =
-          await import('./node-stream-transforms.js');
-        const { pipeline } = await import('node:stream/promises');
+        const {
+          createNodeHeadInjector,
+          createNodeFlightInjector,
+          createNodeErrorHandler,
+          pipeline,
+          PassThrough,
+        } = _nodeStreamImports;
 
         const _s3 = performance.now();
         let nodeHtmlStream: import('node:stream').Readable;
@@ -191,7 +246,7 @@ export async function handleSsr(
           );
         }
 
-        // Build Node.js Transform pipeline: errorHandler → headInjector → flightInjector
+        // Build Node.js Transform pipeline: errorHandler → headInjector → flightInjector → gzip
         const errorHandler = createNodeErrorHandler(navContext.signal);
         const headInjector = createNodeHeadInjector(navContext.headHtml);
         const flightInjector = createNodeFlightInjector(navContext.rscStream);
@@ -199,7 +254,10 @@ export async function handleSsr(
         // 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.
-        const { PassThrough } = await import('node:stream');
+        // 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
@@ -207,7 +265,9 @@ export async function handleSsr(
 
         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`);
+        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);