@timber-js/app 0.1.51 → 0.1.53

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

@@ -61,6 +61,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[];
 }
 
 /**
@@ -305,6 +312,10 @@ export async function buildRouteElement(
     layoutComponents.map(({ component, segment }) => [segment, component])
   );
 
+  // Track which segments were skipped for the X-Timber-Skipped-Segments header.
+  // The client uses this to merge the partial payload with its cached segments.
+  const skippedSegments: string[] = [];
+
   // Wrap from innermost (leaf) to outermost (root), processing every
   // segment in the chain. Each segment may contribute:
   //   1. Error boundaries (status files + error.tsx)
@@ -334,6 +345,8 @@ export async function buildRouteElement(
       // 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).
+      // Record for X-Timber-Skipped-Segments header (outermost first, so prepend).
+      skippedSegments.unshift(segment.urlPath);
       continue;
     }
 
@@ -413,5 +426,6 @@ export async function buildRouteElement(
     layoutComponents,
     segments,
     deferSuspenseFor,
+    skippedSegments,
   };
 }

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

@@ -330,7 +330,7 @@ async function renderRoute(
     throw error;
   }
 
-  const { element, headElements, layoutComponents, deferSuspenseFor } = routeResult;
+  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } = routeResult;
 
   // Build head HTML for injection into the SSR output.
   // Collects CSS, fonts, and modulepreload from the build manifest for matched segments.
@@ -434,7 +434,8 @@ async function renderRoute(
       layoutComponents,
       headElements,
       match,
-      responseHeaders
+      responseHeaders,
+      skippedSegments
     );
   }
 

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

@@ -41,7 +41,8 @@ export async function buildRscPayloadResponse(
   layoutComponents: LayoutComponentEntry[],
   headElements: HeadElement[],
   match: RouteMatch,
-  responseHeaders: Headers
+  responseHeaders: Headers,
+  skippedSegments?: string[]
 ): Promise<Response> {
   // Read the first chunk from the RSC stream before committing headers.
   const reader = rscStream.getReader();
@@ -113,6 +114,12 @@ export async function buildRscPayloadResponse(
   const segmentInfo = buildSegmentInfo(segments, layoutComponents);
   responseHeaders.set('X-Timber-Segments', JSON.stringify(segmentInfo));
 
+  // Send skipped segments so the client can merge the partial RSC payload
+  // with its cached segment elements. See design/19-client-navigation.md.
+  if (skippedSegments && skippedSegments.length > 0) {
+    responseHeaders.set('X-Timber-Skipped-Segments', JSON.stringify(skippedSegments));
+  }
+
   // Send route params so the client can populate useParams() after
   // SPA navigation. Without this, useParams() returns {}.
   if (Object.keys(match.params).length > 0) {