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

package/src/adapters/cloudflare-dev.ts

@@ -0,0 +1,177 @@
+/**
+ * Cloudflare dev-mode bindings via wrangler's getPlatformProxy().
+ *
+ * This Vite plugin starts a local workerd process (via Miniflare) that
+ * emulates Cloudflare bindings (KV, D1, R2, Queues, Durable Objects, etc.)
+ * during development. The proxy env is injected into the request ALS so
+ * `getCloudflareBindings()` works identically in dev and production.
+ *
+ * Design doc: design/35-cloudflare-primitives.md §"Dev Experience"
+ *
+ * Usage:
+ * ```ts
+ * // vite.config.ts
+ * import { timber } from '@timber-js/app'
+ * import { cloudflare } from '@timber-js/app/adapters/cloudflare'
+ * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     timber({ adapter: cloudflare() }),
+ *     cloudflareDevBindings(),
+ *   ],
+ * })
+ * ```
+ *
+ * Requires `wrangler` as a dev dependency. Install it:
+ * ```bash
+ * pnpm add -D wrangler
+ * ```
+ */
+
+import type { Plugin, ViteDevServer } from 'vite';
+import { runWithBindings } from './cloudflare.js';
+
+/**
+ * Dynamically import wrangler. Extracted as a named export so tests
+ * can mock it without needing wrangler installed.
+ * @internal
+ */
+export async function loadWrangler(): Promise<{ getPlatformProxy: (opts: any) => Promise<any> }> {
+  try {
+    return await import('wrangler');
+  } catch {
+    throw new Error(
+      '[timber] Could not import wrangler. ' +
+        'cloudflareDevBindings() requires wrangler as a dev dependency.\n' +
+        'Install it: pnpm add -D wrangler'
+    );
+  }
+}
+
+// ─── Contract ─────────────────────────────────────────────────────────────
+//
+// The dev request wrapper is stored on the ViteDevServer instance using a
+// well-known Symbol. This allows cross-plugin communication without import
+// dependencies — the dev-server plugin checks for this Symbol per-request
+// and wraps the handler call when present.
+//
+// The wrapper type is: <T>(fn: () => T) => T
+// It runs `fn` inside the Cloudflare bindings ALS so getCloudflareBindings()
+// works throughout the request lifecycle.
+
+/**
+ * Symbol key used to store the dev request wrapper on ViteDevServer.
+ *
+ * @internal Exported for testing. The dev-server plugin uses
+ * `Symbol.for('timber:dev-request-wrapper')` directly to avoid
+ * importing from this module.
+ */
+export const DEV_REQUEST_WRAPPER_KEY = Symbol.for('timber:dev-request-wrapper');
+
+/** Options for the Cloudflare dev bindings plugin. */
+export interface CloudflareDevBindingsOptions {
+  /**
+   * Path to the wrangler configuration file.
+   * @default Auto-detected by wrangler (wrangler.jsonc, wrangler.json, wrangler.toml)
+   */
+  configPath?: string;
+
+  /**
+   * Whether to persist binding data (KV, D1, R2) between dev server restarts.
+   *
+   * - `true` — persist in wrangler's default location (`.wrangler/state/`)
+   * - `{ path: string }` — persist in a custom directory
+   * - `false` — start fresh on every restart
+   *
+   * @default true
+   */
+  persist?: boolean | { path: string };
+
+  /**
+   * Wrangler environment to use (for multi-environment configs).
+   * Maps to `[env.<name>]` sections in wrangler.toml / wrangler.jsonc.
+   */
+  environment?: string;
+
+  /**
+   * @internal Override the wrangler loader for testing.
+   * Not part of the public API — may change without notice.
+   */
+  _loadWrangler?: () => Promise<{ getPlatformProxy: (opts: any) => Promise<any> }>;
+}
+
+/**
+ * Vite plugin that provides Cloudflare bindings in dev mode via
+ * wrangler's `getPlatformProxy()`.
+ *
+ * Starts a local workerd process on dev server startup and injects
+ * the proxy env into the per-request ALS. This makes
+ * `getCloudflareBindings()` return real (emulated) bindings during
+ * development — KV, D1, R2, Queues, Durable Objects, and all other
+ * bindings declared in wrangler.jsonc.
+ *
+ * The proxy is automatically disposed when the dev server closes.
+ *
+ * **Requirements:**
+ * - `wrangler` installed as a dev dependency
+ * - A `wrangler.jsonc` (or `wrangler.toml`) with binding declarations
+ *
+ * @example
+ * ```ts
+ * import { cloudflareDevBindings } from '@timber-js/app/adapters/cloudflare/dev'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     timber({ adapter: cloudflare() }),
+ *     cloudflareDevBindings(),
+ *   ],
+ * })
+ * ```
+ */
+export function cloudflareDevBindings(options: CloudflareDevBindingsOptions = {}): Plugin {
+  return {
+    name: 'timber-cloudflare-dev-bindings',
+
+    // Dev mode only — never active during production builds.
+    // See design/35-cloudflare-primitives.md §"Security Considerations":
+    // "Dev bindings are dev-only. apply: 'serve' ensures it never runs
+    //  in production builds."
+    apply: 'serve',
+
+    async configureServer(server: ViteDevServer) {
+      // Dynamic import — wrangler is an optional peer dependency.
+      // Users must install it themselves: `pnpm add -D wrangler`
+      const { getPlatformProxy } = await (options._loadWrangler ?? loadWrangler)();
+
+      // Build getPlatformProxy options from our public API.
+      const proxyOptions: Record<string, unknown> = {
+        persist: options.persist ?? true,
+      };
+      if (options.configPath) {
+        proxyOptions.configPath = options.configPath;
+      }
+      if (options.environment) {
+        proxyOptions.environment = options.environment;
+      }
+
+      const proxy = await getPlatformProxy(proxyOptions);
+
+      // Store a request wrapper on the server instance. The dev-server
+      // plugin checks for this Symbol per-request and wraps the RSC
+      // handler call so getCloudflareBindings() works throughout the
+      // request lifecycle (server components, middleware, server actions).
+      (server as any)[DEV_REQUEST_WRAPPER_KEY] = <T>(fn: () => T): T => {
+        return runWithBindings(proxy.env as Record<string, unknown>, fn);
+      };
+
+      // Dispose the proxy when the dev server closes. This shuts down
+      // the local workerd process started by getPlatformProxy().
+      server.httpServer?.on('close', () => {
+        proxy.dispose().catch(() => {
+          // Disposal errors are non-fatal — the process is shutting down.
+        });
+      });
+    },
+  };
+}

package/src/adapters/cloudflare.ts

@@ -31,8 +31,27 @@ function generateHeadersFile(): string {
 // can access KV, D1, DO, R2, Queues, etc. via getCloudflareBindings().
 // No global fallback — if called outside a request, it throws.
 // See design/11-platform.md §"Platform Target" and design/25-production-deployments.md.
-
-const bindingsAls = new AsyncLocalStorage<Record<string, unknown>>();
+//
+// The ALS is stored on globalThis via Symbol.for so it survives Vite's
+// module instance split in dev mode. The Vite host process (where
+// cloudflareDevBindings → runWithBindings runs) and the RSC module runner
+// (where getCloudflareBindings runs) load separate instances of this file,
+// each with their own module-level variables. globalThis + Symbol.for
+// ensures both share the same ALS — same pattern React uses for
+// Symbol.for('react.element').
+
+const BINDINGS_ALS_KEY = Symbol.for('timber:cf-bindings-als');
+
+function getBindingsAls(): AsyncLocalStorage<Record<string, unknown>> {
+  let als = (globalThis as any)[BINDINGS_ALS_KEY] as
+    | AsyncLocalStorage<Record<string, unknown>>
+    | undefined;
+  if (!als) {
+    als = new AsyncLocalStorage<Record<string, unknown>>();
+    (globalThis as any)[BINDINGS_ALS_KEY] = als;
+  }
+  return als;
+}
 
 /**
  * Get Cloudflare Worker bindings for the current request.
@@ -55,10 +74,8 @@ const bindingsAls = new AsyncLocalStorage<Record<string, unknown>>();
  * }
  * ```
  */
-export function getCloudflareBindings<
-  T extends Record<string, unknown> = Record<string, unknown>,
->(): T {
-  const env = bindingsAls.getStore();
+export function getCloudflareBindings<T = Record<string, unknown>>(): T {
+  const env = getBindingsAls().getStore();
   if (!env) {
     throw new Error(
       'getCloudflareBindings() called outside a Cloudflare Workers request context. ' +
@@ -74,7 +91,85 @@ export function getCloudflareBindings<
  * @internal Used by wrapWithExecutionContext.
  */
 export function runWithBindings<T>(env: Record<string, unknown>, fn: () => T): T {
-  return bindingsAls.run(env, fn);
+  return getBindingsAls().run(env, fn);
+}
+
+// ─── Binding configuration types ──────────────────────────────────────────────
+// Declarative binding config that maps to wrangler.jsonc binding sections.
+// See design/35-cloudflare-primitives.md §"Binding Declarations in Adapter Config".
+
+/** KV namespace binding. `id` defaults to `''` (filled in by wrangler or dashboard). */
+export interface CloudflareKVBinding {
+  name: string;
+  id?: string;
+}
+
+/** D1 database binding. `database_id` is required (from Cloudflare dashboard). */
+export interface CloudflareD1Binding {
+  name: string;
+  database_id: string;
+}
+
+/** R2 bucket binding. `bucket_name` must match the bucket created in Cloudflare. */
+export interface CloudflareR2Binding {
+  name: string;
+  bucket_name: string;
+}
+
+/** Queue producer binding. `queue` is the queue name in Cloudflare. */
+export interface CloudflareQueueProducer {
+  name: string;
+  queue: string;
+}
+
+/** Queue consumer declaration. Attached to the worker, not a binding name. */
+export interface CloudflareQueueConsumer {
+  queue: string;
+  max_batch_size?: number;
+  max_retries?: number;
+  dead_letter_queue?: string;
+}
+
+/** Durable Object binding. `script_name` is for external DO references. */
+export interface CloudflareDurableObjectBinding {
+  name: string;
+  class_name: string;
+  script_name?: string;
+}
+
+/**
+ * Declarative Cloudflare bindings configuration.
+ *
+ * These are converted to the appropriate wrangler.jsonc sections
+ * (`kv_namespaces`, `d1_databases`, `r2_buckets`, `queues`, `durable_objects`).
+ * The `wrangler` escape hatch overrides any generated binding sections
+ * if there's a conflict.
+ *
+ * @example
+ * ```ts
+ * cloudflare({
+ *   bindings: {
+ *     kv: [{ name: 'TIMBER_CACHE' }],
+ *     d1: [{ name: 'MY_DB', database_id: 'xxxx' }],
+ *     r2: [{ name: 'MY_BUCKET', bucket_name: 'my-bucket' }],
+ *     queues: {
+ *       producers: [{ name: 'EMAIL_QUEUE', queue: 'email-queue' }],
+ *       consumers: [{ queue: 'email-queue', max_batch_size: 10 }],
+ *     },
+ *     durableObjects: [{ name: 'MY_DO', class_name: 'MyDurableObject' }],
+ *   },
+ * })
+ * ```
+ */
+export interface CloudflareBindings {
+  kv?: CloudflareKVBinding[];
+  d1?: CloudflareD1Binding[];
+  r2?: CloudflareR2Binding[];
+  queues?: {
+    producers?: CloudflareQueueProducer[];
+    consumers?: CloudflareQueueConsumer[];
+  };
+  durableObjects?: CloudflareDurableObjectBinding[];
 }
 
 /** Options for the Cloudflare Workers adapter. */
@@ -91,11 +186,42 @@ export interface CloudflareAdapterOptions {
    */
   compatibilityFlags?: string[];
 
+  /**
+   * Declarative Cloudflare bindings. Generates the appropriate
+   * `kv_namespaces`, `d1_databases`, `r2_buckets`, `queues`, and
+   * `durable_objects` sections in wrangler.jsonc.
+   *
+   * If both `bindings` and `wrangler` specify the same section,
+   * `wrangler` wins (it's the escape hatch).
+   */
+  bindings?: CloudflareBindings;
+
   /**
    * Custom wrangler.jsonc fields to merge.
-   * Overrides generated values.
+   * Overrides generated values (including bindings-generated sections).
    */
   wrangler?: Record<string, unknown>;
+
+  /**
+   * Path to a module that exports additional Worker handlers (queue, scheduled, email, etc.).
+   * The module is imported in the generated `_worker.js` and its named exports are
+   * spread into the default export alongside `fetch`.
+   *
+   * The module receives `(batch/event, env, ctx)` — standard Cloudflare handler signatures.
+   * It does NOT have access to timber's request pipeline (no ALS, no getCloudflareBindings).
+   * Use `env` directly for bindings.
+   *
+   * @example
+   * ```ts
+   * // timber.config.ts
+   * adapter: cloudflare({ workerHandlers: './src/worker-handlers.ts' })
+   *
+   * // src/worker-handlers.ts
+   * export async function queue(batch, env) { ... }
+   * export async function scheduled(controller, env, ctx) { ... }
+   * ```
+   */
+  workerHandlers?: string;
 }
 
 /**
@@ -151,9 +277,35 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
         await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
       }
 
+      // Compile optional worker handlers (queue, scheduled, etc.)
+      // Uses Vite's build API to bundle the TypeScript source into ESM.
+      let hasWorkerHandlers = false;
+      if (options.workerHandlers) {
+        const handlersEntry = join(process.cwd(), options.workerHandlers);
+        const { build: viteBuild } = await import('vite');
+        await viteBuild({
+          configFile: false,
+          logLevel: 'info',
+          build: {
+            lib: {
+              entry: handlersEntry,
+              formats: ['es'],
+              fileName: () => '_worker-handlers.js',
+            },
+            outDir,
+            emptyOutDir: false,
+            minify: false,
+            rollupOptions: {
+              external: [/^node:/],
+            },
+          },
+        });
+        hasWorkerHandlers = true;
+      }
+
       // Generate the Workers entry point
       const hasManifestInit = !!config.manifestInit;
-      const workerEntry = generateWorkerEntry(outDir, outDir, hasManifestInit);
+      const workerEntry = generateWorkerEntry(outDir, outDir, hasManifestInit, hasWorkerHandlers);
       await writeFile(join(outDir, '_worker.js'), workerEntry);
 
       // Generate wrangler.jsonc
@@ -184,12 +336,12 @@ export function cloudflare(options: CloudflareAdapterOptions = {}): TimberPlatfo
 export function wrapWithExecutionContext(
   adapter: TimberPlatformAdapter,
   handler: (req: Request) => Promise<Response>
-): ExportedHandler<Record<string, unknown>> {
+): CfExportedHandler<Record<string, unknown>> {
   return {
     async fetch(
       request: Request,
       env: Record<string, unknown>,
-      ctx: ExecutionContext
+      ctx: CfExecutionContext
     ): Promise<Response> {
       // Bind the adapter's waitUntil to the Workers execution context
       const originalWaitUntil = adapter.waitUntil;
@@ -214,7 +366,8 @@ export function wrapWithExecutionContext(
 export function generateWorkerEntry(
   buildDir: string,
   outDir: string,
-  hasManifestInit = false
+  hasManifestInit = false,
+  hasWorkerHandlers = false
 ): string {
   // The RSC entry is the main request handler — it exports the fetch handler as default.
   // The Vite RSC plugin outputs it to rsc/index.js.
@@ -229,20 +382,171 @@ export function generateWorkerEntry(
   // ESM guarantees imports are evaluated in order.
   const manifestImport = hasManifestInit ? "import './_timber-manifest-init.js'\n" : '';
 
+  // Optional additional Worker handlers (queue, scheduled, email, etc.)
+  // Compiled by buildOutput via Vite's build API into _worker-handlers.js.
+  // The module's named exports are spread into the default export alongside fetch.
+  const handlersImport = hasWorkerHandlers
+    ? "import * as workerHandlers from './_worker-handlers.js'\n"
+    : '';
+  const handlersSpread = hasWorkerHandlers ? '  ...workerHandlers,\n' : '';
+
   return `// Generated by @timber-js/app/adapters/cloudflare
 // Do not edit — this file is regenerated on each build.
 
+import { AsyncLocalStorage } from 'node:async_hooks'
 ${manifestImport}import handler from '${rscEntryRelative}'
-
+${handlersImport}
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
 globalThis.process ??= { env: {} }
 process.env.TIMBER_RUNTIME = 'cloudflare'
 
-export default { fetch: handler }
+// Bind Cloudflare env to ALS so getCloudflareBindings() works at runtime.
+// Uses the same Symbol.for key as getCloudflareBindings() reads from.
+const ALS_KEY = Symbol.for('timber:cf-bindings-als')
+let bindingsAls = globalThis[ALS_KEY]
+if (!bindingsAls) {
+  bindingsAls = new AsyncLocalStorage()
+  globalThis[ALS_KEY] = bindingsAls
+}
+
+export default {
+${handlersSpread}  async fetch(request, env, ctx) {
+    return bindingsAls.run(env, () => handler(request))
+  }
+}
 `;
 }
 
+/** Wrangler binding sections generated from `CloudflareBindings`. */
+export interface WranglerBindingsConfig {
+  kv_namespaces?: Array<{ binding: string; id: string }>;
+  d1_databases?: Array<{ binding: string; database_id: string }>;
+  r2_buckets?: Array<{ binding: string; bucket_name: string }>;
+  queues?: {
+    producers?: Array<{ binding: string; queue: string }>;
+    consumers?: Array<Record<string, unknown>>;
+  };
+  durable_objects?: {
+    bindings: Array<Record<string, string>>;
+  };
+}
+
+/**
+ * Convert declarative `CloudflareBindings` into wrangler.jsonc binding sections.
+ *
+ * Maps:
+ * - `kv`             → `kv_namespaces`
+ * - `d1`             → `d1_databases`
+ * - `r2`             → `r2_buckets`
+ * - `queues`         → `queues` (producers + consumers)
+ * - `durableObjects` → `durable_objects`
+ *
+ * Empty arrays are omitted from the output.
+ *
+ * @internal Exported for testing.
+ */
+export function generateBindingsConfig(
+  bindings: CloudflareBindings | undefined
+): WranglerBindingsConfig {
+  if (!bindings) return {};
+
+  const result: WranglerBindingsConfig = {};
+
+  // KV namespaces
+  if (bindings.kv && bindings.kv.length > 0) {
+    result.kv_namespaces = bindings.kv.map((kv) => ({
+      binding: kv.name,
+      id: kv.id ?? '',
+    }));
+  }
+
+  // D1 databases
+  if (bindings.d1 && bindings.d1.length > 0) {
+    result.d1_databases = bindings.d1.map((d1) => ({
+      binding: d1.name,
+      database_id: d1.database_id,
+    }));
+  }
+
+  // R2 buckets
+  if (bindings.r2 && bindings.r2.length > 0) {
+    result.r2_buckets = bindings.r2.map((r2) => ({
+      binding: r2.name,
+      bucket_name: r2.bucket_name,
+    }));
+  }
+
+  // Queues (producers and/or consumers)
+  if (bindings.queues) {
+    const queues: Record<string, unknown> = {};
+    if (bindings.queues.producers && bindings.queues.producers.length > 0) {
+      queues.producers = bindings.queues.producers.map((p) => ({
+        binding: p.name,
+        queue: p.queue,
+      }));
+    }
+    if (bindings.queues.consumers && bindings.queues.consumers.length > 0) {
+      queues.consumers = bindings.queues.consumers.map((c) => {
+        const consumer: Record<string, unknown> = { queue: c.queue };
+        if (c.max_batch_size !== undefined) consumer.max_batch_size = c.max_batch_size;
+        if (c.max_retries !== undefined) consumer.max_retries = c.max_retries;
+        if (c.dead_letter_queue !== undefined) consumer.dead_letter_queue = c.dead_letter_queue;
+        return consumer;
+      });
+    }
+    if (Object.keys(queues).length > 0) {
+      result.queues = queues;
+    }
+  }
+
+  // Durable Objects
+  if (bindings.durableObjects && bindings.durableObjects.length > 0) {
+    result.durable_objects = {
+      bindings: bindings.durableObjects.map((dobj) => {
+        const entry: Record<string, string> = {
+          name: dobj.name,
+          class_name: dobj.class_name,
+        };
+        if (dobj.script_name) entry.script_name = dobj.script_name;
+        return entry;
+      }),
+    };
+  }
+
+  return result;
+}
+
+/**
+ * One-level deep merge: for each key in `override`, if both the base and
+ * override values are plain objects (not arrays, not null), merge their
+ * keys with override winning on conflicts. Everything else (primitives,
+ * arrays, null) is replaced outright — matching the intuitive behavior
+ * where `kv_namespaces: [...]` replaces fully but
+ * `durable_objects: { migrations }` merges with generated `bindings`.
+ */
+function shallowDeepMerge(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>
+): Record<string, unknown> {
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    const baseVal = result[key];
+    const overVal = override[key];
+    if (isPlainObject(baseVal) && isPlainObject(overVal)) {
+      result[key] = { ...baseVal, ...overVal };
+    } else {
+      result[key] = overVal;
+    }
+  }
+  return result;
+}
+
+/** True for `{}` literals — false for arrays, null, Date, etc. */
+function isPlainObject(val: unknown): val is Record<string, unknown> {
+  return val !== null && typeof val === 'object' && !Array.isArray(val);
+}
+
 /** @internal Exported for testing. */
 export function generateWranglerConfig(
   config: TimberConfig,
@@ -267,12 +571,20 @@ export function generateWranglerConfig(
     },
   };
 
-  // Merge user overrides
+  // Layer 1: merge bindings-generated sections into base
+  const bindingsConfig = generateBindingsConfig(options.bindings);
+  const merged = { ...base, ...bindingsConfig };
+
+  // Layer 2: wrangler escape hatch with deep merge for nested plain objects.
+  // A shallow spread would replace entire sections like durable_objects and
+  // queues — e.g. adding migrations via wrangler would drop the generated
+  // durable_objects.bindings. Deep merge preserves generated keys while
+  // letting wrangler override on actual key-level conflicts.
   if (options.wrangler) {
-    return { ...base, ...options.wrangler };
+    return shallowDeepMerge(merged, options.wrangler);
   }
 
-  return base;
+  return merged;
 }
 
 // ─── Preview ─────────────────────────────────────────────────────────────────
@@ -310,16 +622,18 @@ function spawnPreviewProcess(command: string, args: string[], cwd: string): Prom
 }
 
 // ─── Cloudflare Workers type stubs ───────────────────────────────────────────
-// Minimal type declarations so this file compiles without @cloudflare/workers-types.
-// In production builds, users install @cloudflare/workers-types themselves.
-
-declare global {
-  interface ExecutionContext {
-    waitUntil(promise: Promise<unknown>): void;
-    passThroughOnException(): void;
-  }
+// Local type declarations so this file compiles without @cloudflare/workers-types.
+// These are NOT declared globally — that would clash with @cloudflare/workers-types
+// when users install it. Instead, they're module-scoped and used only within
+// this file's function signatures.
+
+/** @internal Minimal stub — use @cloudflare/workers-types for full types. */
+export interface CfExecutionContext {
+  waitUntil(promise: Promise<unknown>): void;
+  passThroughOnException(): void;
+}
 
-  interface ExportedHandler<Env = Record<string, unknown>> {
-    fetch?(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> | Response;
-  }
+/** @internal Minimal stub — use @cloudflare/workers-types for full types. */
+export interface CfExportedHandler<Env = Record<string, unknown>> {
+  fetch?(request: Request, env: Env, ctx: CfExecutionContext): Promise<Response> | Response;
 }

package/src/adapters/compress-module.ts

@@ -22,9 +22,11 @@
 export function generateCompressModule(): string {
   return `// Generated by @timber-js/app — response compression for self-hosted deployments.
 // Do not edit — this file is regenerated on each build.
-// Uses CompressionStream (Web API) for gzip. Brotli is left to CDNs/reverse
-// proxies — at streaming quality levels its ratio advantage is marginal and
-// node:zlib buffers output internally, breaking streaming.
+// Uses node:zlib createGzip() (C++ native) on Node.js, falls back to
+// CompressionStream (Web API) on other runtimes. Brotli is left to CDNs/reverse
+// proxies — at streaming quality levels its ratio advantage is marginal.
+import { Readable } from 'node:stream';
+import { createGzip, constants } from 'node:zlib';
 
 const COMPRESSIBLE_TYPES = new Set([
   'text/html', 'text/css', 'text/plain', 'text/xml', 'text/javascript',
@@ -71,7 +73,25 @@ function shouldCompress(response) {
 }
 
 function compressWithGzip(body) {
-  return body.pipeThrough(new CompressionStream('gzip'));
+  // Use node:zlib (C++ native) for gzip compression. The Web Streams
+  // CompressionStream works but every chunk crosses the JS/Promise boundary.
+  // node:zlib.createGzip() compresses entirely in C++ with zero per-chunk
+  // Promise overhead.
+  //
+  // Convert: Web ReadableStream → Node Readable → pipe through gzip →
+  //          Node Readable → Readable.toWeb() → Web ReadableStream
+  try {
+    const nodeReadable = Readable.fromWeb(body);
+    // Z_SYNC_FLUSH ensures each chunk is flushed immediately so the browser
+    // receives the HTML shell before Suspense boundaries resolve. Without it,
+    // gzip buffers internally and breaks streaming.
+    const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+    const compressed = nodeReadable.pipe(gzip);
+    return Readable.toWeb(compressed);
+  } catch {
+    // Fallback: CompressionStream (CF Workers, or if node:stream unavailable)
+    return body.pipeThrough(new CompressionStream('gzip'));
+  }
 }
 
 export function compressResponse(request, response) {