@timber-js/app 0.1.52 → 0.1.53

package/src/client/rsc-fetch.ts

@@ -0,0 +1,234 @@
+/**
+ * RSC Fetch — handles fetching and parsing RSC Flight payloads.
+ *
+ * Extracted from router.ts to keep both files under the 500-line limit.
+ * This module handles:
+ * - Cache-busting URL generation for RSC requests
+ * - Building RSC request headers (Accept, X-Timber-State-Tree)
+ * - Extracting metadata from RSC response headers
+ * - Fetching and decoding RSC payloads
+ *
+ * See design/19-client-navigation.md §"RSC Payload Handling"
+ */
+
+import type { SegmentInfo } from './segment-cache';
+import type { HeadElement } from './head';
+import type { RouterDeps } from './router';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+/** Result of fetching an RSC payload — includes head elements and segment metadata. */
+export 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;
+  /** Segment paths that were skipped by the server (for client-side merging). */
+  skippedSegments: string[] | null;
+}
+
+// ─── Constants ───────────────────────────────────────────────────
+
+export const RSC_CONTENT_TYPE = 'text/x-component';
+
+// ─── URL Helpers ─────────────────────────────────────────────────
+
+/**
+ * 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()}`;
+}
+
+export 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;
+}
+
+// ─── Response Header Extraction ──────────────────────────────────
+
+/**
+ * Extract head elements from the X-Timber-Head response header.
+ * Returns null if the header is missing or malformed.
+ */
+export 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.
+ */
+export 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 skipped segment paths from the X-Timber-Skipped-Segments header.
+ * Returns null if the header is missing or malformed.
+ *
+ * When the server skips sync layouts the client already has cached,
+ * it sends this header listing the skipped segment paths (outermost first).
+ * The client uses this to merge the partial payload with cached segments.
+ */
+export function extractSkippedSegments(response: Response): string[] | null {
+  const header = response.headers.get('X-Timber-Skipped-Segments');
+  if (!header) return null;
+  try {
+    const parsed = JSON.parse(header);
+    return Array.isArray(parsed) ? parsed : null;
+  } 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.
+ */
+export 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;
+  }
+}
+
+// ─── Redirect Error ──────────────────────────────────────────────
+
+/**
+ * Thrown when an RSC payload response contains X-Timber-Redirect header.
+ * Caught in navigate() to trigger a soft router navigation to the redirect target.
+ */
+export class RedirectError extends Error {
+  readonly redirectUrl: string;
+  constructor(url: string) {
+    super(`Server redirect to ${url}`);
+    this.redirectUrl = url;
+  }
+}
+
+// ─── Fetch ───────────────────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export 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;
+    let skippedSegments: 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);
+      skippedSegments = extractSkippedSegments(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, skippedSegments };
+  }
+  // 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),
+    skippedSegments: extractSkippedSegments(response),
+  };
+}

package/src/client/segment-cache.ts

@@ -13,6 +13,8 @@ export interface PrefetchResult {
   segmentInfo?: SegmentInfo[] | null;
   /** Route params from X-Timber-Params header for populating useParams(). */
   params?: Record<string, string | string[]> | null;
+  /** Segment paths skipped by the server (for client-side merging). */
+  skippedSegments?: string[] | null;
 }
 
 /**

package/src/client/segment-merger.ts

@@ -0,0 +1,297 @@
+/**
+ * Segment Merger — client-side tree merging for partial RSC payloads.
+ *
+ * When the server skips rendering sync layouts (because the client already
+ * has them cached), the RSC payload is missing outer segment wrappers.
+ * This module reconstructs the full element tree by splicing the partial
+ * payload into cached segment subtrees.
+ *
+ * The approach:
+ * 1. After each full RSC payload render, walk the decoded element tree
+ *    and cache each segment's subtree (identified by SegmentProvider boundaries)
+ * 2. When a partial payload arrives, wrap it with cached segment elements
+ *    using React.cloneElement to preserve component identity
+ *
+ * React.cloneElement preserves the element's `type` — React sees the same
+ * component at the same tree position and reconciles (preserving state)
+ * rather than remounting. This is how layout state survives navigations.
+ *
+ * Design docs: 19-client-navigation.md §"Navigation Reconciliation"
+ * Security: access.ts runs on the server regardless of skipping — this
+ *           is a performance optimization only. See 13-security.md.
+ */
+
+import { cloneElement, isValidElement, type ReactElement, type ReactNode } from 'react';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+/**
+ * A cached segment entry. Stores the full subtree rooted at a SegmentProvider
+ * and the path through the tree to the next SegmentProvider (or leaf).
+ */
+export interface CachedSegmentEntry {
+  /** The segment's URL path (e.g., "/", "/dashboard") */
+  segmentPath: string;
+  /** The SegmentProvider element for this segment */
+  element: ReactElement;
+}
+
+// ─── Segment Element Cache ───────────────────────────────────────
+
+/**
+ * Cache of React element subtrees per segment path.
+ * Updated after each navigation with the full decoded RSC element tree.
+ */
+export class SegmentElementCache {
+  private entries = new Map<string, CachedSegmentEntry>();
+
+  get(segmentPath: string): CachedSegmentEntry | undefined {
+    return this.entries.get(segmentPath);
+  }
+
+  set(segmentPath: string, entry: CachedSegmentEntry): void {
+    this.entries.set(segmentPath, entry);
+  }
+
+  has(segmentPath: string): boolean {
+    return this.entries.has(segmentPath);
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+}
+
+// ─── SegmentProvider Detection ───────────────────────────────────
+
+/**
+ * Check if a React element is a SegmentProvider by looking for the
+ * `segments` prop (an array of path segments). This is the only
+ * component that receives this prop shape.
+ */
+export function isSegmentProvider(element: unknown): element is ReactElement {
+  if (!isValidElement(element)) return false;
+  const props = element.props as Record<string, unknown>;
+  return Array.isArray(props.segments);
+}
+
+/**
+ * Extract the segment path from a SegmentProvider element.
+ * The `segments` prop is an array like ["", "dashboard", "settings"].
+ * The path is reconstructed as "/" + segments.filter(Boolean).join("/").
+ */
+export function getSegmentPath(element: ReactElement): string {
+  const segments = (element.props as { segments: string[] }).segments;
+  const filtered = segments.filter(Boolean);
+  return filtered.length === 0 ? '/' : '/' + filtered.join('/');
+}
+
+// ─── Tree Walking ────────────────────────────────────────────────
+
+/**
+ * Walk a React element tree and extract all SegmentProvider boundaries.
+ * Returns an ordered list of segment entries from outermost to innermost.
+ *
+ * This only finds SegmentProviders along the main children path — it does
+ * not descend into parallel routes/slots (those are separate subtrees).
+ */
+export function extractSegments(element: unknown): CachedSegmentEntry[] {
+  const segments: CachedSegmentEntry[] = [];
+  walkForSegments(element, segments);
+  return segments;
+}
+
+function walkForSegments(node: unknown, out: CachedSegmentEntry[]): void {
+  if (!isValidElement(node)) return;
+
+  // Use a local binding to avoid TypeScript narrowing issues with
+  // isSegmentProvider's type predicate on the same variable.
+  const el: ReactElement = node as ReactElement;
+  const props = el.props as Record<string, unknown>;
+
+  if (isSegmentProvider(node)) {
+    out.push({
+      segmentPath: getSegmentPath(el),
+      element: el,
+    });
+    // Continue walking into children to find nested segments
+    walkChildren(props.children as ReactNode, out);
+    return;
+  }
+
+  // Not a SegmentProvider — walk children looking for one
+  walkChildren(props.children as ReactNode, out);
+}
+
+function walkChildren(children: ReactNode, out: CachedSegmentEntry[]): void {
+  if (children == null) return;
+
+  if (Array.isArray(children)) {
+    for (const child of children) {
+      walkForSegments(child, out);
+    }
+  } else {
+    walkForSegments(children, out);
+  }
+}
+
+// ─── Cache Population ────────────────────────────────────────────
+
+/**
+ * Cache all segment subtrees from a fully-rendered RSC element tree.
+ * Call this after every full RSC payload render (navigate, refresh, hydration).
+ */
+export function cacheSegmentElements(
+  element: unknown,
+  cache: SegmentElementCache
+): void {
+  const segments = extractSegments(element);
+  for (const entry of segments) {
+    cache.set(entry.segmentPath, entry);
+  }
+}
+
+// ─── Tree Merging ────────────────────────────────────────────────
+
+/**
+ * Find a SegmentProvider nested in the children of a React element.
+ * Returns the path of elements from the given element down to the
+ * SegmentProvider, enabling reconstruction via cloneElement.
+ *
+ * The path is an array of [element, childIndex] pairs. childIndex is -1
+ * for single-child (non-array) props.children.
+ */
+type TreePath = Array<{ element: ReactElement; childIndex: number }>;
+
+function findSegmentProviderPath(
+  node: ReactElement,
+  targetPath?: string
+): TreePath | null {
+  const children = (node.props as { children?: ReactNode }).children;
+  if (children == null) return null;
+
+  if (Array.isArray(children)) {
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i];
+      if (!isValidElement(child)) continue;
+
+      if (isSegmentProvider(child)) {
+        if (!targetPath || getSegmentPath(child) === targetPath) {
+          return [{ element: node, childIndex: i }];
+        }
+      }
+
+      const deeper = findSegmentProviderPath(child, targetPath);
+      if (deeper) {
+        return [{ element: node, childIndex: i }, ...deeper];
+      }
+    }
+  } else if (isValidElement(children)) {
+    if (isSegmentProvider(children)) {
+      if (!targetPath || getSegmentPath(children) === targetPath) {
+        return [{ element: node, childIndex: -1 }];
+      }
+    }
+
+    const deeper = findSegmentProviderPath(children, targetPath);
+    if (deeper) {
+      return [{ element: node, childIndex: -1 }, ...deeper];
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Replace a nested SegmentProvider within a cached element tree with
+ * new content. Uses cloneElement along the path to produce a new tree
+ * with preserved component identity at every level except the replaced node.
+ *
+ * @param cachedElement The cached SegmentProvider element for this segment
+ * @param newInnerContent The new React element to splice in at the inner segment position
+ * @param innerSegmentPath The path of the inner segment to replace (optional — replaces first found)
+ * @returns New element tree with the inner segment replaced
+ */
+export function replaceInnerSegment(
+  cachedElement: ReactElement,
+  newInnerContent: ReactNode,
+  innerSegmentPath?: string
+): ReactElement {
+  const path = findSegmentProviderPath(cachedElement, innerSegmentPath);
+
+  if (!path || path.length === 0) {
+    // No inner SegmentProvider found — the cached element's children
+    // IS the leaf content. Replace children directly.
+    return cloneElement(cachedElement, {}, newInnerContent);
+  }
+
+  // Reconstruct bottom-up: replace the innermost element first, then
+  // clone each ancestor with the updated child.
+  let replacement: ReactNode = newInnerContent;
+
+  for (let i = path.length - 1; i >= 0; i--) {
+    const { element, childIndex } = path[i];
+
+    if (childIndex === -1) {
+      // Single child — replace it
+      replacement = cloneElement(element, {}, replacement);
+    } else {
+      // Array children — replace the specific index
+      const children = (element.props as { children: ReactNode[] }).children;
+      const newChildren = [...children];
+      newChildren[childIndex] = replacement;
+      replacement = cloneElement(element, {}, ...newChildren);
+    }
+  }
+
+  return replacement as ReactElement;
+}
+
+/**
+ * Merge a partial RSC payload with cached segment elements.
+ *
+ * When the server skips segments, the partial payload starts from the
+ * first non-skipped segment. This function wraps it with cached elements
+ * for the skipped segments, producing a full tree that React can
+ * reconcile with the mounted tree (preserving layout state).
+ *
+ * @param partialPayload The RSC payload element (may be partial)
+ * @param skippedSegments Ordered list of segment paths that were skipped (outermost first)
+ * @param cache The segment element cache
+ * @returns The merged full element tree, or the partial payload if merging isn't possible
+ */
+export function mergeSegmentTree(
+  partialPayload: unknown,
+  skippedSegments: string[],
+  cache: SegmentElementCache
+): unknown {
+  if (!isValidElement(partialPayload)) return partialPayload;
+  if (skippedSegments.length === 0) return partialPayload;
+
+  // Build from outermost to innermost: each skipped segment's cached
+  // element wraps the next, with the partial payload at the center.
+  let result: ReactNode = partialPayload;
+
+  // Process from innermost skipped segment to outermost
+  for (let i = skippedSegments.length - 1; i >= 0; i--) {
+    const segmentPath = skippedSegments[i];
+    const cached = cache.get(segmentPath);
+
+    if (!cached) {
+      // No cached element for this segment — can't merge.
+      // This shouldn't happen (server only skips segments the client
+      // has cached), but if it does, return the partial payload as-is.
+      return partialPayload;
+    }
+
+    // Replace the inner content of the cached segment with our current result.
+    // The inner content is either the next SegmentProvider or the page.
+    result = replaceInnerSegment(cached.element, result);
+  }
+
+  return result;
+}

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

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

@@ -55,24 +55,23 @@ export function parseClientStateTree(req: Request): Set<string> | null {
  * @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
+  urlPath: string,
+  layoutComponent: ((...args: unknown[]) => unknown) | undefined,
+  isLeaf: boolean,
+  clientSegments: Set<string> | null
 ): boolean {
-  // DISABLED: Server-side segment skipping is not safe without client-side
-  // tree merging. When the server omits a layout from the RSC payload, the
-  // client receives a tree with a different structure (no SegmentProvider,
-  // no layout wrapper). React sees a different component tree shape and
-  // re-mounts everything — destroying DOM state (input values, focus,
-  // scroll position) in layouts that should have been preserved.
-  //
-  // The correct fix requires client-side tree merging: the router must
-  // splice the partial RSC response into the existing cached tree, only
-  // replacing changed segments. Until that's implemented, always render
-  // the full tree. RSC naturally handles this efficiently — client
-  // components are sent as references, not re-serialized.
-  //
-  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
-  return false;
+  // 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);
 }