@timber-js/app 0.1.37 → 0.1.39

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) {

package/src/server/state-tree-diff.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 function parseClientStateTree(req: Request): Set<string> | null {
+  const header = req.headers.get('X-Timber-State-Tree');
+  if (!header) return null;
+
+  try {
+    const parsed = JSON.parse(header) as { segments?: unknown };
+    if (!Array.isArray(parsed.segments) || parsed.segments.length === 0) {
+      return null;
+    }
+    return new Set(parsed.segments as string[]);
+  } catch {
+    return 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 function shouldSkipSegment(
+  urlPath: string,
+  layoutComponent: ((...args: unknown[]) => unknown) | undefined,
+  isLeaf: boolean,
+  clientSegments: Set<string> | null
+): boolean {
+  // No state tree → full render (initial load, refresh, etc.)
+  if (!clientSegments) return false;
+
+  // Leaf segments (pages) are never skipped
+  if (isLeaf) return false;
+
+  // No layout → nothing to skip
+  if (!layoutComponent) return false;
+
+  // Async layouts always re-render (they may depend on request context)
+  if (layoutComponent.constructor?.name === 'AsyncFunction') return false;
+
+  // Skip if the client already has this segment cached
+  return clientSegments.has(urlPath);
+}