@timber-js/app 0.1.37 → 0.1.39

package/dist/plugins/dev-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/plugins/dev-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiC,MAAM,MAAM,CAAC;AAGlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAiChD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAmD1D"}
+{"version":3,"file":"dev-server.d.ts","sourceRoot":"","sources":["../../src/plugins/dev-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiC,MAAM,MAAM,CAAC;AAGlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkChD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAmD1D"}

package/dist/server/compress.d.ts

@@ -0,0 +1,37 @@
+/**
+ * MIME types that benefit from compression.
+ * text/* is handled via prefix matching; these are the specific
+ * application/* and image/* types that are compressible.
+ */
+export declare const COMPRESSIBLE_TYPES: Set<string>;
+/**
+ * Parse Accept-Encoding and return the best supported encoding.
+ * Prefers brotli (br) over gzip. Returns null if no supported encoding.
+ *
+ * We always prefer brotli regardless of quality values because:
+ * 1. Brotli achieves better compression ratios than gzip
+ * 2. All modern browsers that send br in Accept-Encoding support it well
+ * 3. Respecting q-values for br vs gzip adds complexity with no real benefit
+ */
+export declare function negotiateEncoding(acceptEncoding: string): 'br' | 'gzip' | null;
+/**
+ * Determine if a response should be compressed.
+ *
+ * Returns false for:
+ * - Responses without a body (204, 304, null body)
+ * - Already-encoded responses (Content-Encoding set)
+ * - Non-compressible content types (images, binary)
+ * - SSE streams (text/event-stream — must not be buffered)
+ */
+export declare function shouldCompress(response: Response): boolean;
+/**
+ * Compress a Web Response if the client supports it and the content is compressible.
+ *
+ * Returns the original response unchanged if compression is not applicable.
+ * Returns a new Response with the compressed body, Content-Encoding, and Vary headers.
+ *
+ * The body is piped through a compression stream — no buffering of the full response.
+ * This preserves streaming behavior for HTML shell + deferred Suspense chunks.
+ */
+export declare function compressResponse(request: Request, response: Response): Response;
+//# sourceMappingURL=compress.d.ts.map

package/dist/server/compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/server/compress.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAc7B,CAAC;AASH;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAU9E;AAID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAmB1D;AAID;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAmC/E"}

package/dist/server/route-element-builder.d.ts

@@ -62,5 +62,5 @@ export declare class RouteSignalWithContext extends Error {
  * Does NOT serialize to RSC Flight — the caller decides whether to render
  * to a stream or use the element directly (e.g., for action revalidation).
  */
-export declare function buildRouteElement(req: Request, match: RouteMatch, interception?: InterceptionContext): Promise<RouteElementResult>;
+export declare function buildRouteElement(req: Request, match: RouteMatch, interception?: InterceptionContext, clientStateTree?: Set<string> | null): Promise<RouteElementResult>;
 //# sourceMappingURL=route-element-builder.d.ts.map

package/dist/server/route-element-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAO7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAIzD,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,UAAU,GAAG,cAAc;aACnC,gBAAgB,EAAE,oBAAoB,EAAE;aACxC,QAAQ,EAAE,mBAAmB,EAAE;gBAF/B,MAAM,EAAE,UAAU,GAAG,cAAc,EACnC,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,QAAQ,EAAE,mBAAmB,EAAE;CAIlD;AAID;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAyS7B"}
+{"version":3,"file":"route-element-builder.d.ts","sourceRoot":"","sources":["../../src/server/route-element-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAK9D,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAO7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAKzD,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACvC;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3C,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,wFAAwF;IACxF,OAAO,EAAE,KAAK,CAAC,YAAY,CAAC;IAC5B,2CAA2C;IAC3C,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,wDAAwD;IACxD,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,qCAAqC;IACrC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE7B,MAAM,EAAE,UAAU,GAAG,cAAc;aACnC,gBAAgB,EAAE,oBAAoB,EAAE;aACxC,QAAQ,EAAE,mBAAmB,EAAE;gBAF/B,MAAM,EAAE,UAAU,GAAG,cAAc,EACnC,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,QAAQ,EAAE,mBAAmB,EAAE;CAIlD;AAID;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,YAAY,CAAC,EAAE,mBAAmB,EAClC,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAgU7B"}

package/dist/server/rsc-entry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AAsEA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AAwWD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;8BAjPpD,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AAmPhD,wBAAiE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AAuEA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AA+WD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;8BAxPpD,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA0PhD,wBAAiE"}

package/dist/server/state-tree-diff.d.ts

@@ -0,0 +1,43 @@
+/**
+ * State Tree Diffing — Server-side parsing and diffing of X-Timber-State-Tree.
+ *
+ * The client sends X-Timber-State-Tree on navigation requests, listing
+ * the sync segments it has cached. The server diffs this against the
+ * target route's segments to skip re-rendering unchanged sync layouts.
+ *
+ * This is a performance optimization only — NOT a security boundary.
+ * All access.ts files run regardless of the state tree content.
+ * A fabricated state tree can only cause extra rendering work or stale
+ * layouts — never auth bypass.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ * See design/13-security.md §"State tree manipulation"
+ */
+/**
+ * Parse the X-Timber-State-Tree header from a request.
+ *
+ * Returns a Set of segment paths the client has cached, or null if
+ * the header is missing, malformed, or empty. Parsing happens before
+ * renderToReadableStream — not inside the React render pass.
+ *
+ * @returns Set of sync segment paths, or null if no valid state tree
+ */
+export declare function parseClientStateTree(req: Request): Set<string> | null;
+/**
+ * Determine whether a segment's layout rendering can be skipped.
+ *
+ * A segment is skipped when ALL of the following are true:
+ * 1. The client has the segment in its state tree (clientSegments contains urlPath)
+ * 2. The layout is sync (not an async function — async layouts always re-render)
+ * 3. The segment is NOT the leaf (pages are never cached across navigations)
+ *
+ * Access.ts still runs for skipped segments — this is enforced by the caller
+ * (buildRouteElement) which runs all access checks before building the tree.
+ *
+ * @param urlPath - The segment's URL path (e.g., "/", "/dashboard")
+ * @param layoutComponent - The loaded layout component function
+ * @param isLeaf - Whether this is the leaf segment (page segment)
+ * @param clientSegments - Set of paths from X-Timber-State-Tree, or null
+ */
+export declare function shouldSkipSegment(urlPath: string, layoutComponent: ((...args: unknown[]) => unknown) | undefined, isLeaf: boolean, clientSegments: Set<string> | null): boolean;
+//# sourceMappingURL=state-tree-diff.d.ts.map

package/dist/server/state-tree-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-tree-diff.d.ts","sourceRoot":"","sources":["../../src/server/state-tree-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAarE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,SAAS,EAC9D,MAAM,EAAE,OAAO,EACf,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GACjC,OAAO,CAeT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -87,8 +87,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/context-async-hooks": "^2.6.0",
-    "@opentelemetry/sdk-trace-base": "^2.6.0",
-    "nitro": "^3.0.0"
+    "@opentelemetry/sdk-trace-base": "^2.6.0"
   },
   "peerDependencies": {
     "@content-collections/core": "^0.14.0",

package/src/adapters/compress-module.ts

@@ -0,0 +1,108 @@
+// Generated compression module template for self-hosted deployments.
+//
+// This file generates a standalone ESM module (_compress.mjs) that is
+// written to the build output during adapter buildOutput(). It's imported
+// by the Nitro entry and preview server at runtime.
+//
+// Uses CompressionStream (Web API) for gzip and node:zlib for brotli.
+// Cloudflare Workers don't need this — the edge auto-compresses.
+//
+// See design/25-production-deployments.md.
+
+/**
+ * Generate a standalone ESM module that exports compressResponse().
+ *
+ * Written to `_compress.mjs` during buildOutput. Imported by the Nitro entry
+ * and preview server.
+ *
+ * @internal Exported for testing.
+ */
+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, node:zlib for brotli.
+
+import { createBrotliCompress, constants as zlibConstants } from 'node:zlib';
+import { Readable } from 'node:stream';
+
+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',
+]);
+
+const NO_COMPRESS_STATUSES = new Set([204, 304]);
+
+function negotiateEncoding(acceptEncoding) {
+  if (!acceptEncoding) return null;
+  const tokens = acceptEncoding.split(',').map(s => s.split(';')[0].trim().toLowerCase());
+  if (tokens.includes('br')) return 'br';
+  if (tokens.includes('gzip')) return 'gzip';
+  return null;
+}
+
+function shouldCompress(response) {
+  if (!response.body) return false;
+  if (NO_COMPRESS_STATUSES.has(response.status)) return false;
+  if (response.headers.has('Content-Encoding')) return false;
+  const contentType = response.headers.get('Content-Type');
+  if (!contentType) return false;
+  const mimeType = contentType.split(';')[0].trim().toLowerCase();
+  if (mimeType === 'text/event-stream') return false;
+  return COMPRESSIBLE_TYPES.has(mimeType);
+}
+
+function compressWithGzip(body) {
+  return body.pipeThrough(new CompressionStream('gzip'));
+}
+
+function compressWithBrotli(body) {
+  const brotli = createBrotliCompress({
+    params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 4 },
+  });
+  const reader = body.getReader();
+  const pump = async () => {
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) { brotli.end(); return; }
+        if (!brotli.write(value)) {
+          await new Promise(resolve => brotli.once('drain', resolve));
+        }
+      }
+    } catch (err) {
+      brotli.destroy(err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+  pump();
+  return Readable.toWeb(brotli);
+}
+
+export function compressResponse(request, response) {
+  if (!shouldCompress(response)) return response;
+  const acceptEncoding = request.headers.get('Accept-Encoding') || '';
+  const encoding = negotiateEncoding(acceptEncoding);
+  if (!encoding) return response;
+  const compressedBody = encoding === 'br'
+    ? compressWithBrotli(response.body)
+    : compressWithGzip(response.body);
+  const headers = new Headers(response.headers);
+  headers.set('Content-Encoding', encoding);
+  headers.delete('Content-Length');
+  const existingVary = headers.get('Vary');
+  if (existingVary) {
+    if (!existingVary.toLowerCase().includes('accept-encoding')) {
+      headers.set('Vary', existingVary + ', Accept-Encoding');
+    }
+  } else {
+    headers.set('Vary', 'Accept-Encoding');
+  }
+  return new Response(compressedBody, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+`;
+}

package/src/adapters/nitro.ts

@@ -9,6 +9,7 @@ import { writeFile, mkdir, cp } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { join, relative } from 'node:path';
 import type { TimberPlatformAdapter, TimberConfig } from './types';
+import { generateCompressModule } from './compress-module.js';
 // Inlined from server/asset-headers.ts — adapters are loaded by Node at
 // Vite startup time, before Vite's module resolver is available, so cross-
 // directory .ts imports don't resolve.
@@ -198,20 +199,19 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
         await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
       }
 
-      // Copy rsc/ssr build output into the nitro dir so imports stay local
-      // during the Nitro bundling step (avoids broken relative paths in output).
-      await cp(join(buildDir, 'rsc'), join(outDir, 'rsc'), { recursive: true });
-      await cp(join(buildDir, 'ssr'), join(outDir, 'ssr'), { recursive: true }).catch(() => {});
+      // Write the compression helper module for runtime use.
+      // See design/25-production-deployments.md — self-hosted deployments
+      // need application-level compression (Cloudflare handles it at the edge).
+      await writeFile(join(outDir, '_compress.mjs'), generateCompressModule());
 
-      // Generate the Nitro entry point (imports from ./rsc/ within nitro dir)
+      // Generate the Nitro entry point
       const hasManifestInit = !!config.manifestInit;
       const entry = generateNitroEntry(buildDir, outDir, preset, hasManifestInit);
       await writeFile(join(outDir, 'entry.ts'), entry);
 
-      // Run the Nitro build to produce a production-ready server bundle.
-      // The output goes to dist/nitro/.output/server/index.mjs (for node-server preset).
-      // Config is passed programmatically — no nitro.config.ts file needed.
-      await runNitroBuild(outDir, preset, options.nitroConfig);
+      // Generate the Nitro config with static asset cache rules
+      const nitroConfig = generateNitroConfig(preset, options.nitroConfig);
+      await writeFile(join(outDir, 'nitro.config.ts'), nitroConfig);
     },
 
     // Only presets that produce a locally-runnable server get preview().
@@ -252,8 +252,12 @@ export function generateNitroEntry(
   hasManifestInit = false
 ): string {
   // The RSC entry is the main request handler — it exports the fetch handler as default.
-  // rsc/ is copied into the nitro dir so the import is local.
-  const serverEntryRelative = './rsc/index.js';
+  // The Vite RSC plugin outputs it to rsc/index.js.
+  let serverEntryRelative = relative(outDir, join(buildDir, 'rsc', 'index.js'));
+  // Ensure the import path starts with ./ for ESM compatibility
+  if (!serverEntryRelative.startsWith('.')) {
+    serverEntryRelative = './' + serverEntryRelative;
+  }
   const runtimeName = PRESET_CONFIGS[preset].runtimeName;
   const earlyHints = PRESET_CONFIGS[preset].supportsEarlyHints;
 
@@ -278,18 +282,19 @@ export function generateNitroEntry(
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
-${manifestImport}import { defineEventHandler } from 'nitro/h3'
+${manifestImport}import { defineEventHandler, toWebRequest, sendWebResponse } from 'h3'
 import handler, { runWithEarlyHintsSender } from '${serverEntryRelative}'
+import { compressResponse } from './_compress.mjs'
 
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".
 process.env.TIMBER_RUNTIME = '${runtimeName}'
 
 export default defineEventHandler(async (event) => {
-  // h3 v2: event.req is the Web Request
-  const webRequest = event.req
+  const webRequest = toWebRequest(event)
 ${handlerCall}
-  return webResponse
+  const finalResponse = compressResponse(webRequest, webResponse)
+  return sendWebResponse(event, finalResponse)
 })
 `;
 }
@@ -303,7 +308,6 @@ export function generateNitroConfig(
 
   const config: Record<string, unknown> = {
     preset: presetConfig.nitroPreset,
-    entry: './entry.ts',
     output: { dir: presetConfig.outputDir },
     // Static asset cache headers — hashed assets are immutable, others get 1h.
     // See design/25-production-deployments.md §"CDN / Edge Cache"
@@ -319,7 +323,7 @@ export function generateNitroConfig(
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
-import { defineNitroConfig } from 'nitro/config'
+import { defineNitroConfig } from 'nitropack/config'
 
 export default defineNitroConfig(${configJson})
 `;
@@ -368,6 +372,9 @@ if (existsSync(manifestPath)) {
 // Import the RSC handler (default export is the fetch-like handler).
 const { default: handler, runWithEarlyHintsSender } = await import('${rscEntry}');
 
+// Import compression helper for self-hosted response compression.
+const { compressResponse } = await import('./_compress.mjs');
+
 const MIME_TYPES = {
   '.html': 'text/html',
   '.js': 'application/javascript',
@@ -395,10 +402,9 @@ const MIME_TYPES = {
 
 const publicDir = join(__dirname, '${publicDir}');
 const port = parseInt(process.env.PORT || '3000', 10);
-const host = process.env.HOST || process.env.HOSTNAME || 'localhost';
 
 const server = createServer(async (req, res) => {
-  const url = new URL(req.url || '/', \`http://\${host}:\${port}\`);
+  const url = new URL(req.url || '/', \`http://localhost:\${port}\`);
 
   // Try serving static files from the public directory first.
   const filePath = join(publicDir, url.pathname);
@@ -461,10 +467,13 @@ const server = createServer(async (req, res) => {
       ? (links) => { try { res.writeEarlyHints({ link: links }); } catch {} }
       : undefined;
 
-    const webResponse = earlyHintsSender && runWithEarlyHintsSender
+    const rawResponse = earlyHintsSender && runWithEarlyHintsSender
       ? await runWithEarlyHintsSender(earlyHintsSender, () => handler(webRequest))
       : await handler(webRequest);
 
+    // Compress the response for self-hosted deployments.
+    const webResponse = compressResponse(webRequest, rawResponse);
+
     // Write the response back to the Node response.
     res.writeHead(webResponse.status, Object.fromEntries(webResponse.headers.entries()));
 
@@ -490,11 +499,11 @@ const server = createServer(async (req, res) => {
   }
 });
 
-server.listen(port, host, () => {
+server.listen(port, () => {
   console.log();
   console.log('  ⚡ timber preview server running at:');
   console.log();
-  console.log(\`    ➜  http://\${host}:\${port}\`);
+  console.log(\`    ➜  http://localhost:\${port}\`);
   console.log();
 });
 `;
@@ -525,47 +534,6 @@ export function generateNitroPreviewCommand(
   };
 }
 
-/**
- * Run the Nitro production build using the programmatic API.
- * Uses dynamic import so nitro is only loaded at build time.
- * Externalizes the timber RSC/SSR output — those files are pre-built
- * by timber and have internal references that nitro's bundler can't follow.
- */
-async function runNitroBuild(
-  nitroDir: string,
-  preset: NitroPreset,
-  userConfig?: Record<string, unknown>
-): Promise<void> {
-  const presetConfig = PRESET_CONFIGS[preset];
-  const { createNitro, build: nitroBuild, prepare, copyPublicAssets } = await import('nitro');
-
-  const nitro = await createNitro({
-    rootDir: nitroDir,
-    preset: presetConfig.nitroPreset,
-    // Use renderer.entry so Nitro wraps our handler with its server runtime
-    // (HTTP server, static file serving, graceful shutdown, etc.).
-    // Using `entry` directly would bypass the Nitro server runtime.
-    renderer: { entry: join(nitroDir, 'entry.ts') },
-    output: { dir: join(nitroDir, presetConfig.outputDir) },
-    routeRules: {
-      '/assets/**': { headers: { 'Cache-Control': IMMUTABLE_CACHE } },
-    },
-    // Don't bundle the timber RSC/SSR build output — it has its own
-    // internal file references that nitro's bundler can't follow.
-    // Mark them as external so rollup leaves the imports as-is.
-    rollupConfig: {
-      external: [/\.\.\/rsc\//, /\.\/_timber-manifest-init/],
-    },
-    ...presetConfig.extraConfig,
-    ...userConfig,
-  });
-
-  await prepare(nitro);
-  await copyPublicAssets(nitro);
-  await nitroBuild(nitro);
-  await nitro.close();
-}
-
 /** Spawn a Nitro preview process and pipe stdio. */
 function spawnNitroPreview(command: string, args: string[], cwd: string): Promise<void> {
   return new Promise<void>((resolve, reject) => {

package/src/plugins/dev-server.ts

@@ -18,6 +18,7 @@ import { join } from 'node:path';
 import type { PluginContext } from '#/index.js';
 import { setViteServer } from '#/server/dev-warnings.js';
 import { sendErrorToOverlay, classifyErrorPhase, parseFirstAppFrame } from './dev-error-overlay.js';
+import { compressResponse } from '#/server/compress.js';
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -193,8 +194,13 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       // Run the full pipeline
       const webResponse = await handler(webRequest);
 
+      // Compress the response if the client supports it.
+      // In dev mode, compression is always enabled for parity with production.
+      // See design/25-production-deployments.md.
+      const finalResponse = compressResponse(webRequest, webResponse);
+
       // Convert Web Response → Node ServerResponse
-      await sendWebResponse(res, webResponse);
+      await sendWebResponse(res, finalResponse);
     } catch (error) {
       // Pipeline error — classify the phase, send to overlay, respond 500.
       // The dev server remains running for recovery on file fix + HMR.

package/src/server/compress.ts

@@ -0,0 +1,200 @@
+// Response compression for self-hosted deployments (dev server, Nitro preview).
+//
+// Uses CompressionStream (Web Platform API) for gzip and node:zlib for
+// brotli (CompressionStream doesn't support brotli). Cloudflare Workers
+// auto-compress at the edge — this module is only used on Node.js/Bun.
+//
+// See design/25-production-deployments.md.
+
+import { createBrotliCompress, constants as zlibConstants } from 'node:zlib';
+import { Readable } from 'node:stream';
+
+// ─── Constants ────────────────────────────────────────────────────────────
+
+/**
+ * MIME types that benefit from compression.
+ * text/* is handled via prefix matching; these are the specific
+ * application/* and image/* types that are compressible.
+ */
+export 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',
+]);
+
+/**
+ * Status codes that should never be compressed (no body or special semantics).
+ */
+const NO_COMPRESS_STATUSES = new Set([204, 304]);
+
+// ─── Encoding Negotiation ─────────────────────────────────────────────────
+
+/**
+ * Parse Accept-Encoding and return the best supported encoding.
+ * Prefers brotli (br) over gzip. Returns null if no supported encoding.
+ *
+ * We always prefer brotli regardless of quality values because:
+ * 1. Brotli achieves better compression ratios than gzip
+ * 2. All modern browsers that send br in Accept-Encoding support it well
+ * 3. Respecting q-values for br vs gzip adds complexity with no real benefit
+ */
+export function negotiateEncoding(acceptEncoding: string): 'br' | 'gzip' | null {
+  if (!acceptEncoding) return null;
+
+  // Parse tokens from the Accept-Encoding header (ignore quality values).
+  // e.g. "gzip;q=1.0, br;q=0.8, deflate" → ['gzip', 'br', 'deflate']
+  const tokens = acceptEncoding.split(',').map((s) => s.split(';')[0].trim().toLowerCase());
+
+  if (tokens.includes('br')) return 'br';
+  if (tokens.includes('gzip')) return 'gzip';
+  return null;
+}
+
+// ─── Compressibility Check ────────────────────────────────────────────────
+
+/**
+ * Determine if a response should be compressed.
+ *
+ * Returns false for:
+ * - Responses without a body (204, 304, null body)
+ * - Already-encoded responses (Content-Encoding set)
+ * - Non-compressible content types (images, binary)
+ * - SSE streams (text/event-stream — must not be buffered)
+ */
+export function shouldCompress(response: Response): boolean {
+  // No body to compress
+  if (!response.body) return false;
+  if (NO_COMPRESS_STATUSES.has(response.status)) return false;
+
+  // Already compressed
+  if (response.headers.has('Content-Encoding')) return false;
+
+  // Check content type
+  const contentType = response.headers.get('Content-Type');
+  if (!contentType) return false;
+
+  // Extract the MIME type (strip charset and other parameters)
+  const mimeType = contentType.split(';')[0].trim().toLowerCase();
+
+  // SSE must not be compressed — it relies on chunk-by-chunk delivery
+  if (mimeType === 'text/event-stream') return false;
+
+  return COMPRESSIBLE_TYPES.has(mimeType);
+}
+
+// ─── Compression ──────────────────────────────────────────────────────────
+
+/**
+ * Compress a Web Response if the client supports it and the content is compressible.
+ *
+ * Returns the original response unchanged if compression is not applicable.
+ * Returns a new Response with the compressed body, Content-Encoding, and Vary headers.
+ *
+ * The body is piped through a compression stream — no buffering of the full response.
+ * This preserves streaming behavior for HTML shell + deferred Suspense chunks.
+ */
+export function compressResponse(request: Request, response: Response): Response {
+  // Check if response is compressible
+  if (!shouldCompress(response)) return response;
+
+  // Negotiate encoding with the client
+  const acceptEncoding = request.headers.get('Accept-Encoding') ?? '';
+  const encoding = negotiateEncoding(acceptEncoding);
+  if (!encoding) return response;
+
+  // Compress the body stream
+  const compressedBody = encoding === 'br'
+    ? compressWithBrotli(response.body!)
+    : compressWithGzip(response.body!);
+
+  // Build new headers: copy originals, add compression headers, remove Content-Length
+  // (compressed size is unknown until streaming completes).
+  const headers = new Headers(response.headers);
+  headers.set('Content-Encoding', encoding);
+  headers.delete('Content-Length');
+
+  // Append to Vary header (preserve existing Vary values)
+  const existingVary = headers.get('Vary');
+  if (existingVary) {
+    if (!existingVary.toLowerCase().includes('accept-encoding')) {
+      headers.set('Vary', `${existingVary}, Accept-Encoding`);
+    }
+  } else {
+    headers.set('Vary', 'Accept-Encoding');
+  }
+
+  return new Response(compressedBody, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+// ─── Gzip (CompressionStream API) ────────────────────────────────────────
+
+/**
+ * Compress a ReadableStream with gzip using the Web Platform CompressionStream API.
+ * Available in Node 18+, Bun, and Deno — no npm dependency needed.
+ */
+function compressWithGzip(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
+  const compressionStream = new CompressionStream('gzip');
+  // Cast needed: CompressionStream's WritableStream<BufferSource> type is wider
+  // than ReadableStream's Uint8Array, but Uint8Array is a valid BufferSource.
+  return body.pipeThrough(compressionStream as unknown as TransformStream<Uint8Array, Uint8Array>);
+}
+
+// ─── Brotli (node:zlib) ──────────────────────────────────────────────────
+
+/**
+ * Compress a ReadableStream with brotli using node:zlib.
+ *
+ * CompressionStream doesn't support brotli — it only handles gzip and deflate.
+ * We use node:zlib's createBrotliCompress() and bridge between Web streams
+ * and Node streams.
+ */
+function compressWithBrotli(body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
+  const brotli = createBrotliCompress({
+    params: {
+      // Quality 4 balances compression ratio and CPU time for streaming.
+      // Default (11) is too slow for real-time responses.
+      [zlibConstants.BROTLI_PARAM_QUALITY]: 4,
+    },
+  });
+
+  // Pipe the Web ReadableStream into the Node brotli transform.
+  const reader = body.getReader();
+
+  // Pump chunks from the Web ReadableStream into the Node transform.
+  const pump = async (): Promise<void> => {
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          brotli.end();
+          return;
+        }
+        // Write to brotli, wait for drain if buffer is full
+        if (!brotli.write(value)) {
+          await new Promise<void>((resolve) => brotli.once('drain', resolve));
+        }
+      }
+    } catch (err) {
+      brotli.destroy(err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+  // Start pumping (fire and forget — errors propagate via brotli stream)
+  pump();
+
+  // Convert the Node readable (brotli output) to a Web ReadableStream.
+  return Readable.toWeb(brotli) as ReadableStream<Uint8Array>;
+}