@timber-js/app 0.1.51 → 0.1.53

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

@@ -1 +1 @@
-{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/server/compress.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAc7B,CAAC;AASH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASvE;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,CAiC/E"}
+{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../../src/server/compress.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAc7B,CAAC;AASH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4BvE;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,CAiC/E"}

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

@@ -41,6 +41,13 @@ export interface RouteElementResult {
     segments: ManifestSegmentNode[];
     /** Max deferSuspenseFor hold window across all segments. */
     deferSuspenseFor: number;
+    /**
+     * Segment paths that were skipped because the client already has them cached.
+     * Ordered outermost to innermost. Empty when no segments were skipped.
+     * The client uses this to merge the partial payload with cached segments.
+     * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+     */
+    skippedSegments: string[];
 }
 /**
  * Wraps a DenySignal or RedirectSignal with the layout components loaded

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;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"}
+{"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;IACzB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;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,CAuU7B"}

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":"AA0EA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AAwXD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;8BA5P3C,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA8PhD,wBAAiE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA0EA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AAyXD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;8BA7P3C,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AA+PhD,wBAAiE"}

package/dist/server/rsc-entry/rsc-payload.d.ts

@@ -21,5 +21,5 @@ import type { RenderSignals } from './rsc-stream.js';
  * initial component tree, allowing onError to capture DenySignal/
  * RedirectSignal before we commit the response. See TIM-344.
  */
-export declare function buildRscPayloadResponse(req: Request, rscStream: ReadableStream<Uint8Array>, signals: RenderSignals, segments: ManifestSegmentNode[], layoutComponents: LayoutComponentEntry[], headElements: HeadElement[], match: RouteMatch, responseHeaders: Headers): Promise<Response>;
+export declare function buildRscPayloadResponse(req: Request, rscStream: ReadableStream<Uint8Array>, signals: RenderSignals, segments: ManifestSegmentNode[], layoutComponents: LayoutComponentEntry[], headElements: HeadElement[], match: RouteMatch, responseHeaders: Headers, skippedSegments?: string[]): Promise<Response>;
 //# sourceMappingURL=rsc-payload.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"rsc-payload.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/rsc-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAQrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,YAAY,EAAE,WAAW,EAAE,EAC3B,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,GACvB,OAAO,CAAC,QAAQ,CAAC,CAiFnB"}
+{"version":3,"file":"rsc-payload.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/rsc-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAQrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,oBAAoB,EAAE,EACxC,YAAY,EAAE,WAAW,EAAE,EAC3B,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC,QAAQ,CAAC,CAuFnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "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

@@ -37,12 +37,25 @@ 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());
+  // Parse tokens with quality values. Per RFC 9110 §12.5.3, q=0 means
+  // "not acceptable" — the client explicitly rejects that encoding.
   // Brotli (br) is intentionally not handled at the application level.
-  // At streaming-friendly quality levels (0-4), brotli's ratio advantage over
-  // gzip is marginal, and node:zlib's brotli transform buffers output internally.
-  // CDNs/reverse proxies apply brotli at higher quality levels on cached responses.
-  if (tokens.includes('gzip')) return 'gzip';
+  const parts = acceptEncoding.split(',');
+  for (const part of parts) {
+    const [token, ...params] = part.split(';');
+    const name = token.trim().toLowerCase();
+    if (name !== 'gzip') continue;
+    let qValue = 1;
+    for (const param of params) {
+      const trimmed = param.trim().toLowerCase();
+      if (trimmed.startsWith('q=')) {
+        qValue = parseFloat(trimmed.slice(2));
+        if (Number.isNaN(qValue)) qValue = 1;
+        break;
+      }
+    }
+    if (qValue > 0) return 'gzip';
+  }
   return null;
 }
 

package/src/adapters/nitro.ts

@@ -341,19 +341,20 @@ export function generateNitroEntry(
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
-${manifestImport}import handler, { runWithEarlyHintsSender${waitUntilImport} } from '${serverEntryRelative}'
+${manifestImport}import { defineEventHandler } from 'nitro/h3'
+import handler, { runWithEarlyHintsSender${waitUntilImport} } 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 async (event) => {
+export default defineEventHandler(async (event) => {
   // h3 v2: event.req is the Web Request
   const webRequest = event.req
 ${handlerCall}
   return compressResponse(webRequest, webResponse)
-}
+})
 `;
 }
 

package/src/client/browser-entry.ts

@@ -52,6 +52,7 @@ import {
 import { setupServerLogReplay, setupClientErrorForwarding } from './browser-dev.js';
 import { handleLinkClick, handleLinkHover } from './browser-links.js';
 import { TransitionRoot, transitionRender, navigateTransition } from './transition-root.js';
+import { isStaleClientReference, triggerStaleReload, clearStaleReloadFlag } from './stale-reload.js';
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 
@@ -94,7 +95,17 @@ setServerCallback(async (id: string, args: unknown[]) => {
     return res;
   });
 
-  const decoded = await createFromFetch(response);
+  let decoded: unknown;
+  try {
+    decoded = await createFromFetch(response);
+  } catch (error) {
+    if (isStaleClientReference(error)) {
+      triggerStaleReload();
+      // Return a never-resolving promise to prevent further processing
+      return new Promise(() => {});
+    }
+    throw error;
+  }
 
   // Handle redirect — server encoded the redirect location in the RSC stream
   // instead of returning HTTP 302. Perform a client-side SPA navigation.
@@ -169,25 +180,33 @@ function getScrollY(): number {
  * (scrollHeight > clientHeight). Returns the first match, or null.
  *
  * This heuristic covers the common layout patterns:
- *   <body> → <html-wrapper> → <div class="overflow-y-auto">
- *   <body> → <main class="overflow-y-auto">
+ *   <body> → <root-layout> → <div class="overflow-y-auto">
+ *   <body> → <root-layout> → <main> → <nested-layout overflow-y-auto>
  *
- * We limit depth to avoid expensive full-tree traversals.
+ * 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-2
+ * 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 direct children and their children (depth 2)
+  // 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) {
@@ -425,8 +444,24 @@ function bootstrap(runtimeConfig: typeof config): void {
       // Decode RSC Flight stream using createFromFetch.
       // createFromFetch takes a Promise<Response> and progressively
       // parses the RSC stream as chunks arrive.
-      decodeRsc: (fetchPromise: Promise<Response>) => {
-        return createFromFetch(fetchPromise);
+      //
+      // Wrapped with stale client reference detection: if the server
+      // has been redeployed with new bundles, the RSC payload may
+      // reference module IDs that don't exist in the old client bundle.
+      // We catch "Could not find the module" errors and trigger a full
+      // page reload so the browser fetches the new bundle.
+      decodeRsc: async (fetchPromise: Promise<Response>) => {
+        try {
+          return await createFromFetch(fetchPromise);
+        } catch (error) {
+          if (isStaleClientReference(error)) {
+            triggerStaleReload();
+            // Return a never-resolving promise to prevent further processing
+            // while the page is reloading.
+            return new Promise(() => {});
+          }
+          throw error;
+        }
       },
 
       // Render decoded RSC tree via TransitionRoot's state-based mechanism.
@@ -510,6 +545,13 @@ function bootstrap(runtimeConfig: typeof config): void {
     delete (self as unknown as Record<string, unknown>).__timber_segments;
   }
 
+  // Cache segment elements from the initial RSC payload for client-side
+  // tree merging. This ensures the first client navigation can use partial
+  // payloads — the merger needs cached elements for skipped segments.
+  if (initialElement) {
+    router.cacheElementTree(initialElement);
+  }
+
   // Note: __timber_params is read before hydrateRoot (see above) so that
   // NavigationProvider has correct values during hydration. If the hydration
   // path was skipped (no RSC payload), populate the fallback here.
@@ -614,6 +656,24 @@ function bootstrap(runtimeConfig: typeof config): void {
 
 bootstrap(config);
 
+// Clear the stale reload flag on successful bootstrap. If the page
+// loaded and bootstrapped without hitting a stale reference error,
+// the loop guard should reset so the next stale error gets a fresh
+// reload attempt.
+clearStaleReloadFlag();
+
+// Global error handler for stale client reference errors during hydration.
+// The initial RSC payload is decoded lazily by React via createFromReadableStream.
+// If the payload references a module ID from a newer deployment, the error
+// surfaces as an unhandled rejection during React's render/hydration cycle.
+// This handler catches those errors and triggers a full page reload.
+window.addEventListener('unhandledrejection', (event) => {
+  if (isStaleClientReference(event.reason)) {
+    event.preventDefault();
+    triggerStaleReload();
+  }
+});
+
 // Signal that the client runtime has been initialized.
 // Used by E2E tests to wait for hydration before interacting.
 // We append a <meta name="timber-ready"> tag rather than setting a

package/src/client/router.ts

@@ -7,6 +7,13 @@ import { HistoryStack } from './history';
 import type { HeadElement } from './head';
 import { setCurrentParams } from './use-params.js';
 import { setNavigationState } from './navigation-context.js';
+import {
+  SegmentElementCache,
+  cacheSegmentElements,
+  mergeSegmentTree,
+} from './segment-merger.js';
+import { fetchRscPayload, RedirectError } from './rsc-fetch.js';
+import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -71,16 +78,6 @@ export interface RouterDeps {
   ) => Promise<void>;
 }
 
-/** Result of fetching an RSC payload — includes head elements and segment metadata. */
-interface FetchResult {
-  payload: unknown;
-  headElements: HeadElement[] | null;
-  /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
-  segmentInfo: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
-  params: Record<string, string | string[]> | null;
-}
-
 export interface RouterInstance {
   /** Navigate to a new URL (forward navigation) */
   navigate(url: string, options?: NavigationOptions): Promise<void>;
@@ -107,6 +104,12 @@ export interface RouterInstance {
    * Called on initial hydration with segment info embedded in the HTML.
    */
   initSegmentCache(segments: SegmentInfo[]): void;
+  /**
+   * Cache segment elements from a decoded RSC element tree.
+   * Called on initial hydration to populate the element cache so the
+   * first client navigation can use partial payloads.
+   */
+  cacheElementTree(element: unknown): void;
   /** The segment cache (exposed for tests and <Link> prefetch) */
   segmentCache: SegmentCache;
   /** The prefetch cache (exposed for tests and <Link> prefetch) */
@@ -115,18 +118,6 @@ export interface RouterInstance {
   historyStack: HistoryStack;
 }
 
-/**
- * Thrown when an RSC payload response contains X-Timber-Redirect header.
- * Caught in navigate() to trigger a soft router navigation to the redirect target.
- */
-class RedirectError extends Error {
-  readonly redirectUrl: string;
-  constructor(url: string) {
-    super(`Server redirect to ${url}`);
-    this.redirectUrl = url;
-  }
-}
-
 /**
  * Check if an error is an abort error (connection closed / fetch aborted).
  * Browsers throw DOMException with name 'AbortError' when a fetch is aborted.
@@ -137,168 +128,6 @@ function isAbortError(error: unknown): boolean {
   return false;
 }
 
-// ─── RSC Fetch ───────────────────────────────────────────────────
-
-const RSC_CONTENT_TYPE = 'text/x-component';
-
-/**
- * Generate a short random cache-busting ID (5 chars, a-z0-9).
- * Matches the format Next.js uses for _rsc params.
- */
-function generateCacheBustId(): string {
-  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
-  let id = '';
-  for (let i = 0; i < 5; i++) {
-    id += chars[(Math.random() * 36) | 0];
-  }
-  return id;
-}
-
-/**
- * Append a `_rsc=<id>` query parameter to the URL.
- * Follows Next.js's pattern — prevents CDN/browser from serving cached HTML
- * for RSC navigation requests and signals that this is an RSC fetch.
- */
-function appendRscParam(url: string): string {
-  const separator = url.includes('?') ? '&' : '?';
-  return `${url}${separator}_rsc=${generateCacheBustId()}`;
-}
-
-function buildRscHeaders(
-  stateTree: { segments: string[] } | undefined,
-  currentUrl?: string
-): Record<string, string> {
-  const headers: Record<string, string> = {
-    Accept: RSC_CONTENT_TYPE,
-  };
-  if (stateTree) {
-    headers['X-Timber-State-Tree'] = JSON.stringify(stateTree);
-  }
-  // Send current URL for intercepting route resolution.
-  // The server uses this to determine if an intercepting route should
-  // render instead of the actual target route (modal pattern).
-  // See design/07-routing.md §"Intercepting Routes"
-  if (currentUrl) {
-    headers['X-Timber-URL'] = currentUrl;
-  }
-  return headers;
-}
-
-/**
- * Extract head elements from the X-Timber-Head response header.
- * Returns null if the header is missing or malformed.
- */
-function extractHeadElements(response: Response): HeadElement[] | null {
-  const header = response.headers.get('X-Timber-Head');
-  if (!header) return null;
-  try {
-    return JSON.parse(decodeURIComponent(header));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Extract segment metadata from the X-Timber-Segments response header.
- * Returns null if the header is missing or malformed.
- *
- * Format: JSON array of {path, isAsync} objects describing the rendered
- * segment chain from root to leaf. Used to populate the client-side
- * segment cache for state tree diffing on subsequent navigations.
- */
-function extractSegmentInfo(response: Response): SegmentInfo[] | null {
-  const header = response.headers.get('X-Timber-Segments');
-  if (!header) return null;
-  try {
-    return JSON.parse(header);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Extract route params from the X-Timber-Params response header.
- * Returns null if the header is missing or malformed.
- *
- * Used to populate useParams() after client-side navigation.
- */
-function extractParams(response: Response): Record<string, string | string[]> | null {
-  const header = response.headers.get('X-Timber-Params');
-  if (!header) return null;
-  try {
-    return JSON.parse(header);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Fetch an RSC payload from the server. If a decodeRsc function is provided,
- * the response is decoded into a React element tree via createFromFetch.
- * Otherwise, the raw response text is returned (test mode).
- *
- * Also extracts head elements from the X-Timber-Head response header
- * so the client can update document.title and <meta> tags after navigation.
- */
-async function fetchRscPayload(
-  url: string,
-  deps: RouterDeps,
-  stateTree?: { segments: string[] },
-  currentUrl?: string
-): Promise<FetchResult> {
-  const rscUrl = appendRscParam(url);
-  const headers = buildRscHeaders(stateTree, currentUrl);
-  if (deps.decodeRsc) {
-    // Production path: use createFromFetch for streaming RSC decoding.
-    // createFromFetch takes a Promise<Response> and progressively parses
-    // the RSC Flight stream as chunks arrive.
-    //
-    // Intercept the response to read X-Timber-Head before createFromFetch
-    // consumes the body. Reading headers does NOT consume the body stream.
-    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual' });
-    let headElements: HeadElement[] | null = null;
-    let segmentInfo: SegmentInfo[] | null = null;
-    let params: Record<string, string | string[]> | null = null;
-    const wrappedPromise = fetchPromise.then((response) => {
-      // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
-      // for RSC payload requests instead of a raw 302, because fetch with
-      // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
-      // which crashes createFromFetch when it tries to read the body stream.
-      const redirectLocation =
-        response.headers.get('X-Timber-Redirect') ||
-        (response.status >= 300 && response.status < 400 ? response.headers.get('Location') : null);
-      if (redirectLocation) {
-        throw new RedirectError(redirectLocation);
-      }
-      headElements = extractHeadElements(response);
-      segmentInfo = extractSegmentInfo(response);
-      params = extractParams(response);
-      return response;
-    });
-    // Await so headElements/segmentInfo/params are populated before we return.
-    // Also await the decoded payload — createFromFetch returns a thenable
-    // that resolves to the React element tree.
-    await wrappedPromise;
-    const payload = await deps.decodeRsc(wrappedPromise);
-    return { payload, headElements, segmentInfo, params };
-  }
-  // Test/fallback path: return raw text
-  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual' });
-  // Check for redirect in test path too
-  if (response.status >= 300 && response.status < 400) {
-    const location = response.headers.get('Location');
-    if (location) {
-      throw new RedirectError(location);
-    }
-  }
-  return {
-    payload: await response.text(),
-    headElements: extractHeadElements(response),
-    segmentInfo: extractSegmentInfo(response),
-    params: extractParams(response),
-  };
-}
-
 // ─── Router Factory ──────────────────────────────────────────────
 
 /**
@@ -309,6 +138,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   const segmentCache = new SegmentCache();
   const prefetchCache = new PrefetchCache();
   const historyStack = new HistoryStack();
+  const segmentElementCache = new SegmentElementCache();
 
   let pending = false;
   let pendingUrl: string | null = null;
@@ -343,6 +173,28 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
+  /**
+   * Merge a partial RSC payload with cached segment elements if segments
+   * were skipped, then cache segments from the (merged) payload.
+   * Returns the merged payload ready for rendering.
+   */
+  function mergeAndCachePayload(
+    payload: unknown,
+    skippedSegments: string[] | null | undefined
+  ): unknown {
+    let merged = payload;
+
+    // If segments were skipped, merge the partial payload with cached segments
+    if (skippedSegments && skippedSegments.length > 0) {
+      merged = mergeSegmentTree(payload, skippedSegments, segmentElementCache);
+    }
+
+    // Cache segment elements from the (merged) payload for future merges
+    cacheSegmentElements(merged, segmentElementCache);
+
+    return merged;
+  }
+
   /**
    * Update navigation state (params + pathname) for the next render.
    *
@@ -378,13 +230,17 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       await deps.navigateTransition(pendingUrl, async (wrapPayload) => {
         const result = await perform();
         headElements = result.headElements;
-        return wrapPayload(result.payload);
+        // Merge partial payload with cached segments before wrapping
+        const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+        return wrapPayload(merged);
       });
       return headElements;
     }
     // Fallback: no transition (tests, no React tree)
     const result = await perform();
-    renderPayload(result.payload);
+    // Merge partial payload with cached segments before rendering
+    const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+    renderPayload(merged);
     return result.headElements;
   }
 
@@ -421,6 +277,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           headElements: prefetched.headElements,
           segmentInfo: prefetched.segmentInfo ?? null,
           params: prefetched.params ?? null,
+          skippedSegments: prefetched.skippedSegments ?? null,
         }
       : undefined;
 
@@ -616,15 +473,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Render the piggybacked element tree from a server action response.
       // Updates the current history entry with the fresh payload and applies
       // head elements — same as refresh() but without a server fetch.
+      // Cache segment elements for future partial merges.
       const currentUrl = deps.getCurrentUrl();
+      const merged = mergeAndCachePayload(element, null);
       historyStack.push(currentUrl, {
-        payload: element,
+        payload: merged,
         headElements,
       });
-      renderPayload(element);
+      renderPayload(merged);
       applyHead(headElements);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),
+    cacheElementTree: (element: unknown) => cacheSegmentElements(element, segmentElementCache),
     segmentCache,
     prefetchCache,
     historyStack,