@timber-js/app 0.1.51 → 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/client/stale-reload.ts

@@ -0,0 +1,89 @@
+/**
+ * Stale Client Reference Reload
+ *
+ * When a new deployment ships updated bundles, clients running stale
+ * JavaScript may encounter "Could not find the module" errors during
+ * RSC Flight stream decoding. This happens because the RSC payload
+ * references module IDs from the new bundle that don't exist in the
+ * old client bundle.
+ *
+ * This module detects these specific errors and triggers a full page
+ * reload so the browser fetches the new bundle. A sessionStorage flag
+ * guards against infinite reload loops.
+ *
+ * See: LOCAL-332
+ */
+
+const RELOAD_FLAG_KEY = '__timber_stale_reload';
+
+/**
+ * Check if an error is a stale client reference error from React's
+ * Flight client. These errors have the message pattern:
+ *   "Could not find the module \"<id>\""
+ *
+ * This is thrown by react-server-dom-webpack's client when the RSC
+ * payload references a module ID that doesn't exist in the client's
+ * module map — typically because the server has been redeployed with
+ * new bundle hashes while the client is still running old JavaScript.
+ */
+export function isStaleClientReference(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const msg = error.message;
+  return msg.includes('Could not find the module');
+}
+
+/**
+ * Trigger a full page reload to pick up new bundles.
+ *
+ * Sets a sessionStorage flag before reloading. If the flag is already
+ * set (meaning we already reloaded once for this reason), we don't
+ * reload again — this prevents infinite reload loops if the error
+ * persists after reload (e.g., a genuine bug rather than a stale bundle).
+ *
+ * @returns true if a reload was triggered, false if suppressed (loop guard)
+ */
+export function triggerStaleReload(): boolean {
+  try {
+    // Check if we already reloaded — prevent infinite loop
+    if (sessionStorage.getItem(RELOAD_FLAG_KEY)) {
+      console.warn(
+        '[timber] Stale client reference detected again after reload. ' +
+        'Not reloading to prevent infinite loop. ' +
+        'This may indicate a deployment issue — try a hard refresh.'
+      );
+      return false;
+    }
+
+    // Set the flag before reloading
+    sessionStorage.setItem(RELOAD_FLAG_KEY, '1');
+
+    console.warn(
+      '[timber] Stale client reference detected — the server has been ' +
+      'redeployed with new bundles. Reloading to pick up the new version.'
+    );
+
+    window.location.reload();
+    return true;
+  } catch {
+    // sessionStorage may be unavailable (private browsing, storage full, etc.)
+    // Fall back to reloading without loop protection
+    console.warn(
+      '[timber] Stale client reference detected. Reloading page.'
+    );
+    window.location.reload();
+    return true;
+  }
+}
+
+/**
+ * Clear the stale reload flag. Called on successful bootstrap to reset
+ * the loop guard — if the page loaded successfully, the next stale
+ * reference error should trigger a fresh reload attempt.
+ */
+export function clearStaleReloadFlag(): void {
+  try {
+    sessionStorage.removeItem(RELOAD_FLAG_KEY);
+  } catch {
+    // sessionStorage unavailable — nothing to clear
+  }
+}

package/src/server/compress.ts

@@ -55,11 +55,30 @@ const NO_COMPRESS_STATUSES = new Set([204, 304]);
 export function negotiateEncoding(acceptEncoding: string): 'gzip' | null {
   if (!acceptEncoding) return null;
 
-  // Parse tokens from the Accept-Encoding header (ignore quality values).
-  // e.g. "gzip;q=1.0, br;q=0.8, deflate" → ['gzip', 'br', 'deflate']
-  const tokens = acceptEncoding.split(',').map((s) => s.split(';')[0].trim().toLowerCase());
+  // Parse tokens with quality values from the Accept-Encoding header.
+  // Per RFC 9110 §12.5.3, q=0 means "not acceptable" — the client explicitly
+  // rejects that encoding. Tokens without a q-value default to q=1.
+  // e.g. "gzip;q=1.0, br;q=0" → gzip is acceptable, br is rejected.
+  const parts = acceptEncoding.split(',');
+  for (const part of parts) {
+    const [token, ...params] = part.split(';');
+    const name = token.trim().toLowerCase();
+    if (name !== 'gzip') continue;
+
+    // Check for q=0 (explicitly disabled)
+    let qValue = 1; // default quality is 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';
+  }
 
-  if (tokens.includes('gzip')) return 'gzip';
   return null;
 }