@timber-js/app 0.1.38 → 0.1.40

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.38",
+  "version": "0.1.40",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

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, readFile, 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,6 +199,11 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
         await writeFile(join(outDir, '_timber-manifest-init.js'), config.manifestInit);
       }
 
+      // 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());
+
       // 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 });
@@ -258,6 +264,7 @@ export function generateNitroEntry(
   buildDir: string,
   outDir: string,
   preset: NitroPreset,
+  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.
@@ -286,6 +293,7 @@ export function generateNitroEntry(
 
 import { defineEventHandler } from 'nitro/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".
@@ -295,7 +303,7 @@ export default defineEventHandler(async (event) => {
   // h3 v2: event.req is the Web Request
   const webRequest = event.req
 ${handlerCall}
-  return webResponse
+  return compressResponse(webRequest, webResponse)
 })
 `;
 }
@@ -374,6 +382,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',
@@ -467,10 +478,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()));
 

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>;
+}

package/src/server/route-element-builder.ts

@@ -32,6 +32,7 @@ import { setParsedSearchParams } from './request-context.js';
 import type { SearchParamsDefinition } from '#/search-params/create.js';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
 import type { InterceptionContext } from './pipeline.js';
+import { shouldSkipSegment } from './state-tree-diff.js';
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
@@ -91,7 +92,8 @@ export class RouteSignalWithContext extends Error {
 export async function buildRouteElement(
   req: Request,
   match: RouteMatch,
-  interception?: InterceptionContext
+  interception?: InterceptionContext,
+  clientStateTree?: Set<string> | null
 ): Promise<RouteElementResult> {
   const segments = match.segments as unknown as ManifestSegmentNode[];
 
@@ -308,8 +310,32 @@ export async function buildRouteElement(
   //   1. Error boundaries (status files + error.tsx)
   //   2. Layout component — wraps children + parallel slots
   //   3. SegmentProvider — records position for useSelectedLayoutSegment
+  //
+  // When clientStateTree is provided (from X-Timber-State-Tree header on
+  // client navigation), sync layouts the client already has are skipped.
+  // Access.ts already ran for ALL segments in the pre-render loop above.
+  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
   for (let i = segments.length - 1; i >= 0; i--) {
     const segment = segments[i];
+    const isLeaf = i === segments.length - 1;
+    const layoutComponent = layoutBySegment.get(segment);
+
+    // Check if this segment's layout can be skipped for partial rendering.
+    // Skipped segments: no layout wrapping, no error boundaries, no slots,
+    // no AccessGate in element tree (access already ran pre-render).
+    const skip = shouldSkipSegment(
+      segment.urlPath,
+      layoutComponent,
+      isLeaf,
+      clientStateTree ?? null
+    );
+
+    if (skip) {
+      // Skip this segment entirely — the client uses its cached version.
+      // Access.ts already ran in the pre-render loop (security guarantee).
+      // Metadata was already resolved above (head elements are correct).
+      continue;
+    }
 
     // Wrap with error boundaries from this segment (inside layout).
     element = await wrapSegmentWithErrorBoundaries(segment, element, h);
@@ -335,7 +361,6 @@ export async function buildRouteElement(
     }
 
     // Wrap with layout if this segment has one — traced with OTEL span
-    const layoutComponent = layoutBySegment.get(segment);
     if (layoutComponent) {
       // Resolve parallel slots for this layout
       const slotProps: Record<string, unknown> = {};

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

@@ -59,6 +59,7 @@ import {
   escapeHtml,
   isRscPayloadRequest,
 } from './helpers.js';
+import { parseClientStateTree } from '#/server/state-tree-diff.js';
 import { buildRscPayloadResponse } from './rsc-payload.js';
 import { renderRscStream } from './rsc-stream.js';
 import { renderSsrResponse } from './ssr-renderer.js';
@@ -268,11 +269,18 @@ async function renderRoute(
     return handleApiRoute(_req, match, segments, responseHeaders);
   }
 
+  // Parse X-Timber-State-Tree for RSC payload requests (client navigation).
+  // The state tree lists sync segments the client has cached — the server
+  // skips re-rendering those layouts for a smaller, faster RSC payload.
+  // Only used for RSC requests — HTML requests always get a full render.
+  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+  const clientStateTree = isRscPayloadRequest(_req) ? parseClientStateTree(_req) : null;
+
   // Build the React element tree — loads modules, runs access checks,
   // resolves metadata. DenySignal/RedirectSignal propagate for HTTP handling.
   let routeResult;
   try {
-    routeResult = await buildRouteElement(_req, match, interception);
+    routeResult = await buildRouteElement(_req, match, interception, clientStateTree);
   } catch (error) {
     // RouteSignalWithContext wraps DenySignal/RedirectSignal with layout context
     if (error instanceof RouteSignalWithContext) {