@timber-js/app 0.2.0-alpha.32 → 0.2.0-alpha.34

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;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"}
+{"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,CAuHX;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,CA8BlB"}

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":"AA0FA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AAoZD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;8BAtQ3C,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AAwQhD,wBAAiE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA2FA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AAkaD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;8BApR3C,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AAsRhD,wBAAiE"}

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

@@ -1 +1 @@
-{"version":3,"file":"ssr-renderer.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/ssr-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAYrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,UAAU,gBAAgB;IACxB,GAAG,EAAE,OAAO,CAAC;IACb,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACtC,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,KAAK,EAAE,UAAU,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,qBAAqB,CAAC;IACvC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsKjF"}
+{"version":3,"file":"ssr-renderer.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/ssr-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAYrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD,UAAU,gBAAgB;IACxB,GAAG,EAAE,OAAO,CAAC;IACb,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACtC,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,gBAAgB,EAAE,oBAAoB,EAAE,CAAC;IACzC,KAAK,EAAE,UAAU,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,qBAAqB,CAAC;IACvC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqLjF"}

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

@@ -53,6 +53,28 @@ export interface NavContext {
      * to a page-level deny. See LOCAL-298.
      */
     _denyHandledByBoundary?: boolean;
+    /**
+     * Mutable: SSR timing data populated by handleSsr().
+     * Read by the RSC entry to record sub-phase Server-Timing entries
+     * when `serverTiming: 'detailed'` is configured.
+     *
+     * This bridges the RSC→SSR environment boundary: the SSR entry populates
+     * these fields, the RSC entry reads them after callSsr() returns.
+     */
+    _ssrTimings?: {
+        /** Time to decode RSC stream (createFromReadableStream/createFromNodeStream) */
+        decodeMs: number;
+        /** Time for Fizz to render the shell (onShellReady) */
+        shellMs: number;
+        /** Time for pipe() to flush shell bytes to the output stream */
+        pipeMs: number;
+        /** Time to set up Node.js Transform pipeline / Web Stream transforms */
+        pipelineMs: number;
+        /** Total SSR time (decode → response ready) */
+        totalMs: number;
+        /** Whether the Node.js native stream path was used */
+        nodeStreams: boolean;
+    };
 }
 /**
  * Handle SSR: decode an RSC stream and render it to hydration-ready HTML.

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;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,CAyJnB;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;IAEjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE;QACZ,gFAAgF;QAChF,QAAQ,EAAE,MAAM,CAAC;QACjB,uDAAuD;QACvD,OAAO,EAAE,MAAM,CAAC;QAChB,gEAAgE;QAChE,MAAM,EAAE,MAAM,CAAC;QACf,wEAAwE;QACxE,UAAU,EAAE,MAAM,CAAC;QACnB,+CAA+C;QAC/C,OAAO,EAAE,MAAM,CAAC;QAChB,sDAAsD;QACtD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAuJnB;AAED,eAAe,SAAS,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"ssr-render.d.ts","sourceRoot":"","sources":["../../src/server/ssr-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAqEvC;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IAAE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC7F,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAErC;AAED,wEAAwE;AACxE,eAAO,MAAM,cAAc,SAAkB,CAAC;AAU9C;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IAAE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC7F,OAAO,CAAC,OAAO,aAAa,EAAE,QAAQ,CAAC,CAyDzC;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,aAAa,EAAE,QAAQ,GACvC,cAAc,CAAC,UAAU,CAAC,CAE5B;AA0CD;;;;;;;;;;;;GAYG;AACH,2CAA2C;AAC3C,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,UAAU,CAAC,CA2B5B;AAWD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,OAAO,GACvB,QAAQ,CASV"}
+{"version":3,"file":"ssr-render.d.ts","sourceRoot":"","sources":["../../src/server/ssr-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAqEvC;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IAAE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC7F,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAErC;AAED,wEAAwE;AACxE,eAAO,MAAM,cAAc,SAAkB,CAAC;AAU9C;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,SAAS,EAClB,OAAO,CAAC,EAAE;IAAE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC7F,OAAO,CAAC,OAAO,aAAa,EAAE,QAAQ,CAAC,CAkDzC;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,aAAa,EAAE,QAAQ,GACvC,cAAc,CAAC,UAAU,CAAC,CAE5B;AA0CD;;;;;;;;;;;;GAYG;AACH,2CAA2C;AAC3C,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,UAAU,CAAC,CA2B5B;AAWD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,EACtC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,OAAO,GACvB,QAAQ,CASV"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.32",
+  "version": "0.2.0-alpha.34",
   "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

@@ -26,7 +26,7 @@ export function generateCompressModule(): string {
 // 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 } from 'node:zlib';
+import { createGzip, constants } from 'node:zlib';
 
 const COMPRESSIBLE_TYPES = new Set([
   'text/html', 'text/css', 'text/plain', 'text/xml', 'text/javascript',
@@ -82,7 +82,10 @@ function compressWithGzip(body) {
   //          Node Readable → Readable.toWeb() → Web ReadableStream
   try {
     const nodeReadable = Readable.fromWeb(body);
-    const gzip = createGzip();
+    // 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 {

package/src/client/browser-entry.ts

@@ -159,7 +159,17 @@ setServerCallback(async (id: string, args: unknown[]) => {
  * Hydrates the server-rendered HTML with React, then initializes
  * client-side navigation for SPA transitions.
  */
-/** Read scroll position from window or scroll containers. */
+/**
+ * Read the current scroll position.
+ *
+ * Checks window scroll first, then explicit `data-timber-scroll-restoration`
+ * containers. With segment tree merging, shared layouts are reconciled in
+ * place via `cloneElement` — React preserves their DOM and scroll state
+ * naturally. We don't need to auto-detect overflow containers; only
+ * explicitly marked containers are tracked.
+ *
+ * See design/19-client-navigation.md §"Overflow Scroll Containers".
+ */
 function getScrollY(): number {
   if (window.scrollY || document.documentElement.scrollTop || document.body.scrollTop) {
     return window.scrollY || document.documentElement.scrollTop || document.body.scrollTop;
@@ -167,71 +177,17 @@ function getScrollY(): number {
   for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
     if ((el as HTMLElement).scrollTop > 0) return (el as HTMLElement).scrollTop;
   }
-  // Auto-detect: if window isn't scrolled, check for overflow containers.
-  // Common pattern: layouts use a scrollable div (overflow-y: auto/scroll)
-  // inside a fixed-height parent (h-screen). In this case window.scrollY is
-  // always 0 and the real scroll position lives on the overflow container.
-  const container = findOverflowContainer();
-  if (container && container.scrollTop > 0) return container.scrollTop;
   return 0;
 }
 
-/**
- * Find the primary overflow scroll container in the document.
- *
- * Walks direct children of body and their immediate children looking for
- * an element with overflow-y: auto|scroll that is actually scrollable
- * (scrollHeight > clientHeight). Returns the first match, or null.
- *
- * This heuristic covers the common layout patterns:
- *   <body> → <root-layout> → <div class="overflow-y-auto">
- *   <body> → <root-layout> → <main> → <nested-layout overflow-y-auto>
- *
- * We limit depth to 3 to avoid expensive full-tree traversals while still
- * reaching nested layout scroll containers (e.g., parallel route layouts
- * inside a root layout's <main> element).
- *
- * DIVERGENCE FROM NEXT.JS: Next.js's ScrollAndFocusHandler scrolls only
- * document.documentElement.scrollTop — it does NOT handle overflow containers.
- * Layouts using h-screen + overflow-y-auto have the same scroll bug in Next.js.
- * This heuristic is a deliberate improvement. The tradeoff is fragility: depth-3
- * traversal may miss deeply nested containers or match the wrong element.
- * See design/19-client-navigation.md §"Overflow Scroll Containers".
- */
-function findOverflowContainer(): HTMLElement | null {
-  const candidates: HTMLElement[] = [];
-  // Check body's descendants up to depth 3. Depth 3 covers the common case:
-  //   <body> → <root-layout-div> → <main> → <overflow-container>
-  // React context providers (SegmentProvider, NavigationProvider) don't add
-  // DOM elements, so depth 3 from body reaches nested layout scroll containers.
-  for (const child of document.body.children) {
-    candidates.push(child as HTMLElement);
-    for (const grandchild of child.children) {
-      candidates.push(grandchild as HTMLElement);
-      for (const greatGrandchild of grandchild.children) {
-        candidates.push(greatGrandchild as HTMLElement);
-      }
-    }
-  }
-  for (const el of candidates) {
-    if (!(el instanceof HTMLElement)) continue;
-    const style = getComputedStyle(el);
-    const overflowY = style.overflowY;
-    if ((overflowY === 'auto' || overflowY === 'scroll') && el.scrollHeight > el.clientHeight) {
-      return el;
-    }
-  }
-  return null;
-}
-
 function bootstrap(runtimeConfig: typeof config): void {
   const _config = runtimeConfig;
 
-  // Take manual control of scroll restoration. React's render() on the
-  // document root resets scroll during DOM reconciliation, so the browser's
-  // native scroll restoration (scrollRestoration = 'auto') doesn't work —
-  // the browser restores scroll, then React's commit resets it to 0.
-  // We save/restore scroll positions explicitly in the history stack.
+  // Take manual control of scroll restoration. Even though segment tree
+  // merging preserves shared layout DOM via cloneElement (so React doesn't
+  // reset scroll on those elements), the root-level reactRoot.render() with
+  // a new element tree can still cause scroll resets on the document during
+  // reconciliation. Manual control ensures consistent behavior.
   window.history.scrollRestoration = 'manual';
 
   // Hydrate the React tree from the RSC payload.
@@ -247,6 +203,21 @@ function bootstrap(runtimeConfig: typeof config): void {
   // For subsequent navigations, it's fetched from the server.
   type FlightSegment = [isBootstrap: 0] | [isData: 1, data: string];
 
+  // On streaming pages, the browser entry module may load before the RSC
+  // payload scripts arrive. The <script id="_R_"> tag is in the shell (flushed
+  // on onShellReady), but the RSC bootstrap script `(self.__timber_f=...).push([0])`
+  // is injected by the flight injector AFTER Suspense resolution scripts.
+  // If the module import resolves before those scripts execute, __timber_f
+  // will be undefined.
+  //
+  // Fix: if __timber_f isn't available yet, pre-initialize it so the RSC
+  // bootstrap script's `(self.__timber_f=self.__timber_f||[]).push([0])` finds
+  // our array and pushes into it. This avoids a race condition that causes
+  // the browser entry to fall through to createRoot() (no hydration) on
+  // streaming pages.
+  if (!(self as unknown as Record<string, unknown>).__timber_f) {
+    (self as unknown as Record<string, FlightSegment[]>).__timber_f = [];
+  }
   const timberChunks = (self as unknown as Record<string, FlightSegment[]>).__timber_f;
 
   let _reactRoot: Root | null = null;
@@ -424,23 +395,20 @@ function bootstrap(runtimeConfig: typeof config): void {
       pushState: (data, unused, url) => window.history.pushState(data, unused, url),
       replaceState: (data, unused, url) => window.history.replaceState(data, unused, url),
       scrollTo: (x, y) => {
+        // Scroll the document viewport.
         window.scrollTo(x, y);
         document.documentElement.scrollTop = y;
         document.body.scrollTop = y;
-        // Also scroll any element explicitly marked as a scroll container.
+        // Scroll any element explicitly marked as a scroll container.
+        // With segment tree merging, shared layouts (sidebars, nav bars)
+        // are reconciled in place via cloneElement — React preserves their
+        // DOM and scroll state naturally. We no longer auto-detect overflow
+        // containers, which previously found the wrong element (e.g.,
+        // scrolling a sidebar instead of the main content area).
+        // Use `data-timber-scroll-restoration` to opt in specific containers.
         for (const el of document.querySelectorAll('[data-timber-scroll-restoration]')) {
           (el as HTMLElement).scrollTop = y;
         }
-        // Auto-detect overflow containers for layouts that scroll inside
-        // a fixed-height wrapper (e.g., h-screen + overflow-y-auto).
-        // In these layouts, window.scrollY is always 0 and the real scroll
-        // lives on the overflow container. Without this, forward navigation
-        // between pages that share a layout with parallel route slots won't
-        // scroll to top — the router's window.scrollTo(0,0) is a no-op.
-        const container = findOverflowContainer();
-        if (container) {
-          container.scrollTop = y;
-        }
       },
       getCurrentUrl: () => window.location.pathname + window.location.search,
       getScrollY,
@@ -590,7 +558,6 @@ function bootstrap(runtimeConfig: typeof config): void {
     scrollTimer = setTimeout(() => {
       const state = window.history.state;
       if (state && typeof state === 'object') {
-        // Use getScrollY to capture scroll from overflow containers too.
         window.history.replaceState({ ...state, scrollY: getScrollY() }, '');
       }
     }, 100);

package/src/server/compress.ts

@@ -160,15 +160,33 @@ export function compressResponse(request: Request, response: Response): Response
   });
 }
 
-// ─── Gzip (CompressionStream API) ────────────────────────────────────────
+// ─── Gzip (node:zlib with Z_SYNC_FLUSH) ──────────────────────────────────
+//
+// Uses node:zlib's createGzip with Z_SYNC_FLUSH so each chunk is flushed
+// to the output immediately. The Web Platform CompressionStream API buffers
+// internally and does NOT flush per-chunk — this kills streaming because
+// the browser doesn't receive the HTML shell until the gzip stream closes
+// (i.e. after all Suspense boundaries resolve).
+//
+// Z_SYNC_FLUSH adds ~2–5% size overhead vs Z_NO_FLUSH but preserves
+// correct streaming behavior: the shell renders instantly, Suspense
+// fallbacks are visible immediately, and streamed content appears
+// progressively.
+
+import { createGzip, constants } from 'node:zlib';
+import { Readable } from 'node:stream';
 
 /**
- * Compress a ReadableStream with gzip using the Web Platform CompressionStream API.
- * Available in Node 18+, Bun, and Deno — no npm dependency needed.
+ * Compress a ReadableStream with gzip, flushing each chunk immediately.
+ *
+ * Uses node:zlib's createGzip with Z_SYNC_FLUSH to ensure each HTML chunk
+ * (shell, Suspense resolution, RSC payload) is delivered to the browser
+ * as soon as it's available — preserving streaming semantics.
  */
 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>);
+  const gzip = createGzip({ flush: constants.Z_SYNC_FLUSH });
+  const nodeInput = Readable.fromWeb(body as import('stream/web').ReadableStream);
+  nodeInput.pipe(gzip);
+
+  return Readable.toWeb(gzip) as ReadableStream<Uint8Array>;
 }

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

@@ -18,7 +18,7 @@
  */
 
 import { Transform } from 'node:stream';
-import { createGzip } from 'node:zlib';
+import { createGzip, constants } from 'node:zlib';
 
 // ─── Head Injection ──────────────────────────────────────────────────────────
 
@@ -124,18 +124,23 @@ export function createNodeFlightInjector(
   const rscReader = rscStream.getReader();
   const decoder = new TextDecoder('utf-8', { fatal: true });
 
-  let pullPromise: Promise<void> | null = null;
   let donePulling = false;
   let pullError: unknown = null;
   let foundSuffix = false;
   let htmlStreamFinished = false;
-  const pending: Buffer[] = [];
-
-  // Emit bootstrap signal
-  const bootstrap = `<script>(self.__timber_f=self.__timber_f||[]).push(${htmlEscapeJsonString(JSON.stringify([0]))})</script>`;
-  pending.push(Buffer.from(bootstrap, 'utf-8'));
-
+  // Reference to the transform instance, set on first transform() call.
+  // Used by pullLoop to push RSC chunks directly to the output without
+  // waiting for HTML chunks to trigger drainPending.
+  let transformRef: Transform | null = null;
+
+  // pullLoop reads RSC chunks and pushes them directly to the transform
+  // output as <script> tags. This ensures RSC data is delivered to the
+  // browser as soon as it's available — not deferred until the next HTML
+  // chunk. Critical for streaming: the shell RSC payload must arrive
+  // with the shell HTML so hydration can start before Suspense resolves.
   async function pullLoop(): Promise<void> {
+    // Yield once so the first transform() call can set transformRef and
+    // emit the bootstrap signal before we start pushing data chunks.
     await new Promise<void>((r) => setImmediate(r));
     try {
       for (;;) {
@@ -146,7 +151,12 @@ export function createNodeFlightInjector(
         }
         const decoded = decoder.decode(value, { stream: true });
         const escaped = htmlEscapeJsonString(JSON.stringify([1, decoded]));
-        pending.push(Buffer.from(`<script>self.__timber_f.push(${escaped})</script>`, 'utf-8'));
+        const scriptBuf = Buffer.from(`<script>self.__timber_f.push(${escaped})</script>`, 'utf-8');
+        // Push directly to the transform output — don't wait for an
+        // HTML chunk to trigger drainPending.
+        if (transformRef) {
+          transformRef.push(scriptBuf);
+        }
         if (!htmlStreamFinished) {
           await new Promise<void>((r) => setImmediate(r));
         }
@@ -157,25 +167,21 @@ export function createNodeFlightInjector(
     }
   }
 
-  function drainPending(transform: Transform): void {
-    while (pending.length > 0) {
-      transform.push(pending.shift()!);
-    }
-    if (pullError) {
-      transform.destroy(pullError instanceof Error ? pullError : new Error(String(pullError)));
-      pullError = null;
-    }
-  }
-
   return new Transform({
     transform(chunk: Buffer, _encoding, callback) {
-      if (!pullPromise) {
-        pullPromise = pullLoop();
+      if (!transformRef) {
+        transformRef = this;
+        // Emit bootstrap signal with the first HTML chunk (the shell).
+        // This must arrive before any data chunks.
+        const bootstrap = `<script>(self.__timber_f=self.__timber_f||[]).push(${htmlEscapeJsonString(JSON.stringify([0]))})</script>`;
+        this.push(Buffer.from(bootstrap, 'utf-8'));
+        // Start the pull loop — it will push RSC data chunks directly
+        // to the transform output as they arrive from the RSC stream.
+        pullLoop();
       }
 
       if (foundSuffix) {
         this.push(chunk);
-        if (pending.length > 0) drainPending(this);
         callback();
         return;
       }
@@ -187,7 +193,6 @@ export function createNodeFlightInjector(
         const before = text.slice(0, idx);
         const after = text.slice(idx + suffix.length);
         if (before) this.push(Buffer.from(before, 'utf-8'));
-        if (pending.length > 0) drainPending(this);
         if (after) this.push(Buffer.from(after, 'utf-8'));
       } else {
         this.push(chunk);
@@ -198,7 +203,10 @@ export function createNodeFlightInjector(
       htmlStreamFinished = true;
 
       const finish = () => {
-        drainPending(this);
+        if (pullError) {
+          this.destroy(pullError instanceof Error ? pullError : new Error(String(pullError)));
+          return;
+        }
         if (foundSuffix) {
           this.push(suffixBuf);
         }
@@ -209,10 +217,16 @@ export function createNodeFlightInjector(
         finish();
         return;
       }
-      if (!pullPromise) {
-        pullPromise = pullLoop();
-      }
-      pullPromise.then(finish);
+      // Wait for the RSC stream to finish before closing.
+      // pullLoop is already running and pushing directly.
+      const waitForPull = () => {
+        if (donePulling || pullError) {
+          finish();
+        } else {
+          setImmediate(waitForPull);
+        }
+      };
+      waitForPull();
     },
   });
 }
@@ -311,5 +325,9 @@ export function createNodeGzipCompressor(
     responseHeaders.set('vary', 'Accept-Encoding');
   }
 
-  return createGzip();
+  // Z_SYNC_FLUSH ensures each chunk is flushed to the output immediately.
+  // Without it, gzip buffers internally and the browser doesn't receive
+  // the HTML shell until the gzip stream closes — breaking streaming.
+  // ~2–5% size overhead vs Z_NO_FLUSH but preserves correct streaming.
+  return createGzip({ flush: constants.Z_SYNC_FLUSH });
 }

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

@@ -68,6 +68,7 @@ import { renderRscStream } from './rsc-stream.js';
 import { renderSsrResponse } from './ssr-renderer.js';
 import { callSsr } from './ssr-bridge.js';
 import { isDebug, isDevMode, setDebugFromConfig } from '#/server/debug.js';
+import { recordTiming } from '#/server/server-timing.js';
 
 /**
  * Resolve the Server-Timing mode from timber.config.ts.
@@ -325,6 +326,7 @@ async function renderRoute(
   // Build the React element tree — loads modules, runs access checks,
   // resolves metadata. DenySignal/RedirectSignal propagate for HTTP handling.
   let routeResult;
+  const _buildStart = performance.now();
   try {
     routeResult = await buildRouteElement(_req, match, interception, clientStateTree);
   } catch (error) {
@@ -364,6 +366,13 @@ async function renderRoute(
     throw error;
   }
 
+  const _buildEnd = performance.now();
+  recordTiming({
+    name: 'build',
+    dur: Math.round(_buildEnd - _buildStart),
+    desc: 'build element tree',
+  });
+
   const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } =
     routeResult;
 
@@ -416,7 +425,13 @@ async function renderRoute(
   }
 
   // Render to RSC Flight stream with signal tracking.
+  const _rscStart = performance.now();
   const { rscStream, signals } = renderRscStream(element, _req);
+  recordTiming({
+    name: 'rsc-init',
+    dur: Math.round(performance.now() - _rscStart),
+    desc: 'RSC stream init',
+  });
 
   // Synchronous redirect — redirect() in access.ts or a non-async component
   // throws during renderToReadableStream creation. Return HTTP redirect.

package/src/server/rsc-entry/ssr-renderer.ts

@@ -31,6 +31,7 @@ import {
 import { renderErrorPage } from './error-renderer.js';
 import { callSsr } from './ssr-bridge.js';
 import type { RenderSignals } from './rsc-stream.js';
+import { recordTiming } from '#/server/server-timing.js';
 
 interface SsrRenderOptions {
   req: Request;
@@ -156,6 +157,21 @@ export async function renderSsrResponse(opts: SsrRenderOptions): Promise<Respons
   try {
     const ssrResponse = await callSsr(ssrStream, navContext);
 
+    // Record SSR sub-phase timings for Server-Timing header (detailed mode).
+    // These are populated by handleSsr() in the SSR environment and passed
+    // back via navContext._ssrTimings across the RSC→SSR boundary.
+    if (navContext._ssrTimings) {
+      const t = navContext._ssrTimings;
+      recordTiming({ name: 'ssr-decode', dur: t.decodeMs, desc: 'RSC Flight decode' });
+      recordTiming({ name: 'ssr-shell', dur: t.shellMs, desc: 'Fizz onShellReady' });
+      recordTiming({ name: 'ssr-pipeline', dur: t.pipelineMs, desc: 'stream transforms' });
+      recordTiming({
+        name: 'ssr-total',
+        dur: t.totalMs,
+        desc: t.nodeStreams ? 'SSR (Node streams)' : 'SSR (Web Streams)',
+      });
+    }
+
     // Signal promotion: check if any signals were captured during rendering
     // inside Suspense boundaries. If no signals are present yet, yield one
     // microtask so async component rejections propagate to the RSC onError

package/src/server/ssr-entry.ts

@@ -126,6 +126,29 @@ export interface NavContext {
    * to a page-level deny. See LOCAL-298.
    */
   _denyHandledByBoundary?: boolean;
+
+  /**
+   * Mutable: SSR timing data populated by handleSsr().
+   * Read by the RSC entry to record sub-phase Server-Timing entries
+   * when `serverTiming: 'detailed'` is configured.
+   *
+   * This bridges the RSC→SSR environment boundary: the SSR entry populates
+   * these fields, the RSC entry reads them after callSsr() returns.
+   */
+  _ssrTimings?: {
+    /** Time to decode RSC stream (createFromReadableStream/createFromNodeStream) */
+    decodeMs: number;
+    /** Time for Fizz to render the shell (onShellReady) */
+    shellMs: number;
+    /** Time for pipe() to flush shell bytes to the output stream */
+    pipeMs: number;
+    /** Time to set up Node.js Transform pipeline / Web Stream transforms */
+    pipelineMs: number;
+    /** Total SSR time (decode → response ready) */
+    totalMs: number;
+    /** Whether the Node.js native stream path was used */
+    nodeStreams: boolean;
+  };
 }
 
 /**
@@ -182,11 +205,8 @@ export async function handleSsr(
       // createFromReadableStream resolves client component references
       // (from "use client" modules) using the SSR environment's module
       // map, importing the actual components for server-side rendering.
-      const _s0 = performance.now();
-      // eslint-disable-next-line no-console
-      console.log(
-        `[diag] nodeImports=${!!_nodeStreamImports} nodeStreamDecode=${hasNodeStreamDecode} rscStream=${rscStream?.constructor?.name}`
-      );
+      const _ssrStart = performance.now();
+
       // 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)
@@ -200,21 +220,13 @@ export async function handleSsr(
       } else {
         element = createFromReadableStream(rscStream) as React.ReactNode;
       }
-      const _s1 = performance.now();
+      const _decodeEnd = performance.now();
 
       // Wrap with a server-safe nuqs adapter so that 'use client' components
       // that call nuqs hooks (useQueryStates, useQueryState) can SSR correctly.
-      // The client-side TimberNuqsAdapter (injected by browser-entry.ts) takes
-      // over after hydration. This provider supplies the request's search params
-      // as a static snapshot so nuqs renders the right initial values on the server.
       const wrappedElement = withNuqsSsrAdapter(navContext.searchParams, element);
-      const _s2 = performance.now();
 
       // Render to HTML stream (waits for onShellReady).
-      // Pass bootstrapScriptContent so React injects a non-deferred <script>
-      // in the shell HTML. This executes immediately during parsing — even
-      // while Suspense boundaries are still streaming — triggering module
-      // loading via dynamic import() so hydration can start early.
       //
       // Two paths based on platform:
       // - Node.js: renderToPipeableStream → Node Transform pipeline → Readable.toWeb() → Response
@@ -231,7 +243,6 @@ export async function handleSsr(
           PassThrough,
         } = _nodeStreamImports;
 
-        const _s3 = performance.now();
         let nodeHtmlStream: import('node:stream').Readable;
         try {
           nodeHtmlStream = await renderSsrNodeStream(wrappedElement, {
@@ -249,29 +260,27 @@ export async function handleSsr(
             renderError
           );
         }
+        const _renderEnd = performance.now();
 
-        // Build Node.js Transform pipeline: errorHandler → headInjector → flightInjector → gzip
         const errorHandler = createNodeErrorHandler(navContext.signal);
         const headInjector = createNodeHeadInjector(navContext.headHtml);
         const flightInjector = createNodeFlightInjector(navContext.rscStream);
 
-        // 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.
-        // 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
         });
+        const _pipelineEnd = performance.now();
 
-        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`
-        );
+        // Record SSR sub-timings for Server-Timing header (detailed mode).
+        navContext._ssrTimings = {
+          decodeMs: Math.round(_decodeEnd - _ssrStart),
+          shellMs: Math.round(_renderEnd - _decodeEnd),
+          pipeMs: 0, // pipe() timing is inside renderSsrNodeStream
+          pipelineMs: Math.round(_pipelineEnd - _renderEnd),
+          totalMs: Math.round(_pipelineEnd - _ssrStart),
+          nodeStreams: true,
+        };
 
         const webStream = nodeReadableToWeb(output);
         return buildSsrResponse(webStream, navContext.statusCode, navContext.responseHeaders);
@@ -296,10 +305,22 @@ export async function handleSsr(
         );
       }
 
+      const _renderEnd = performance.now();
+
       // Inject metadata into <head>, then interleave RSC payload chunks
       // into the body as they arrive from the tee'd RSC stream.
       let outputStream = injectHead(htmlStream, navContext.headHtml);
       outputStream = injectRscPayload(outputStream, navContext.rscStream);
+      const _pipelineEnd = performance.now();
+
+      navContext._ssrTimings = {
+        decodeMs: Math.round(_decodeEnd - _ssrStart),
+        shellMs: Math.round(_renderEnd - _decodeEnd),
+        pipeMs: 0,
+        pipelineMs: Math.round(_pipelineEnd - _renderEnd),
+        totalMs: Math.round(_pipelineEnd - _ssrStart),
+        nodeStreams: false,
+      };
 
       // Build and return the Response.
       return buildSsrResponse(outputStream, navContext.statusCode, navContext.responseHeaders);