@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.180

package/src/client/rsc-fetch.ts

@@ -12,18 +12,24 @@
  */
 
 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. */
+/** Result of fetching an RSC payload — includes segment metadata. */
 export interface FetchResult {
   payload: unknown;
-  headElements: HeadElement[] | null;
+  /**
+   * Promise that settles when the RSC decode completes or fails.
+   * The payload thenable is NOT awaited before returning (for streaming),
+   * so callers must monitor this to catch async decode errors
+   * (truncated streams, Flight parse failures) that would otherwise
+   * become unhandled rejections.
+   */
+  decodePromise: Promise<void> | 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(). */
+  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
   params: Record<string, string | string[]> | null;
   /** Segment paths that were skipped by the server (for client-side merging). */
   skippedSegments: string[] | null;
@@ -52,12 +58,54 @@ function generateCacheBustId(): string {
  * 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.
+ *
+ * Strips any #fragment before appending — fragments are client-only and
+ * fetch() discards them, so _rsc would land inside the hash and be lost.
  */
 function appendRscParam(url: string): string {
-  const separator = url.includes('?') ? '&' : '?';
-  return `${url}${separator}_rsc=${generateCacheBustId()}`;
+  const hashIndex = url.indexOf('#');
+  const urlWithoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+  const separator = urlWithoutHash.includes('?') ? '&' : '?';
+  return `${urlWithoutHash}${separator}_rsc=${generateCacheBustId()}`;
+}
+
+// ─── Deployment ID ───────────────────────────────────────────────
+
+/**
+ * The client's deployment ID, set at bootstrap from the runtime config.
+ * Sent with every RSC/action request for version skew detection.
+ * Null in dev mode. See TIM-446.
+ */
+let clientDeploymentId: string | null = null;
+
+/** Set the client deployment ID. Called once at bootstrap. */
+export function setClientDeploymentId(id: string | null): void {
+  clientDeploymentId = id;
 }
 
+/** Get the client deployment ID. */
+export function getClientDeploymentId(): string | null {
+  return clientDeploymentId;
+}
+
+// ─── Reload Signal ───────────────────────────────────────────────
+
+/** Header name used by the server to signal a version skew reload. */
+export const RELOAD_HEADER = 'X-Timber-Reload';
+
+/** Header name for the client's deployment ID. */
+export const DEPLOYMENT_ID_HEADER = 'X-Timber-Deployment-Id';
+
+/**
+ * Check if a response signals a version skew reload.
+ * Triggers a full page reload if the server indicates the client is stale.
+ */
+export function checkReloadSignal(response: Response): boolean {
+  return response.headers.get(RELOAD_HEADER) === '1';
+}
+
+// ─── Header Builder ──────────────────────────────────────────────
+
 export function buildRscHeaders(
   stateTree: { segments: string[] } | undefined,
   currentUrl?: string
@@ -75,22 +123,26 @@ export function buildRscHeaders(
   if (currentUrl) {
     headers['X-Timber-URL'] = currentUrl;
   }
+  // Send deployment ID for version skew detection (TIM-446).
+  // The server compares this against the current build's ID.
+  // On mismatch, the server signals a reload instead of returning
+  // an RSC payload with mismatched module references.
+  if (clientDeploymentId) {
+    headers[DEPLOYMENT_ID_HEADER] = clientDeploymentId;
+  }
   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;
+/** Dev-only warning for malformed framework headers. Tree-shaken in production. */
+function warnMalformedHeader(headerName: string, raw: string): void {
+  if (process.env.NODE_ENV !== 'production') {
+    const preview = raw.length > 200 ? raw.slice(0, 200) + '…' : raw;
+    console.warn(
+      `[timber] Malformed ${headerName} header \u2014 JSON.parse failed. ` +
+        `This indicates a framework bug or header corruption. Raw (first 200 chars): ${preview}`
+    );
   }
 }
 
@@ -98,7 +150,7 @@ export function extractHeadElements(response: Response): HeadElement[] | 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
+ * Format: JSON array of {path, isRequestDependent} 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.
  */
@@ -108,6 +160,7 @@ export function extractSegmentInfo(response: Response): SegmentInfo[] | null {
   try {
     return JSON.parse(header);
   } catch {
+    warnMalformedHeader('X-Timber-Segments', header);
     return null;
   }
 }
@@ -127,6 +180,7 @@ export function extractSkippedSegments(response: Response): string[] | null {
     const parsed = JSON.parse(header);
     return Array.isArray(parsed) ? parsed : null;
   } catch {
+    warnMalformedHeader('X-Timber-Skipped-Segments', header);
     return null;
   }
 }
@@ -135,7 +189,7 @@ export function extractSkippedSegments(response: Response): string[] | 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.
+ * Used to populate useSegmentParams() after client-side navigation.
  */
 export function extractParams(response: Response): Record<string, string | string[]> | null {
   const header = response.headers.get('X-Timber-Params');
@@ -143,6 +197,7 @@ export function extractParams(response: Response): Record<string, string | strin
   try {
     return JSON.parse(header);
   } catch {
+    warnMalformedHeader('X-Timber-Params', header);
     return null;
   }
 }
@@ -161,21 +216,97 @@ export class RedirectError extends Error {
   }
 }
 
+/**
+ * Thrown when the server signals a version skew (X-Timber-Reload header).
+ * Caught in navigate() to trigger a full page reload.
+ * See TIM-446.
+ */
+export class VersionSkewError extends Error {
+  constructor() {
+    super('Version skew detected — server has been redeployed');
+  }
+}
+
+/**
+ * Thrown when the server returns an error for an RSC payload request.
+ * The server sends X-Timber-Error header and a JSON body instead of a
+ * broken RSC stream for any RenderError (4xx or 5xx). Caught in
+ * navigate() to trigger a hard navigation so the server can render
+ * the error page as HTML.
+ *
+ * See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+ */
+export class ServerErrorResponse extends Error {
+  readonly status: number;
+  readonly url: string;
+  constructor(status: number, url: string) {
+    super(`Server error ${status} during navigation to ${url}`);
+    this.status = status;
+    this.url = url;
+  }
+}
+
+// ─── Stream Completion Tracking ───────────────────────────────────
+
+/**
+ * Wrap a response body stream to track when it's fully consumed.
+ * Returns a new body that passes all chunks through unchanged, plus
+ * a `done` promise that resolves when the last chunk is read (or
+ * rejects if the stream errors).
+ *
+ * Used to keep React transitions open for the full RSC stream
+ * duration — createFromFetch's thenable resolves on shell arrival,
+ * but we need stream completion for useOptimistic pending state.
+ */
+function trackStreamCompletion(body: ReadableStream<Uint8Array>): {
+  body: ReadableStream<Uint8Array>;
+  done: Promise<void>;
+} {
+  let resolveDone!: () => void;
+  let rejectDone!: (e: unknown) => void;
+  const done = new Promise<void>((res, rej) => {
+    resolveDone = res;
+    rejectDone = rej;
+  });
+
+  const reader = body.getReader();
+  const tracked = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          controller.close();
+          resolveDone();
+        } else {
+          controller.enqueue(result.value);
+        }
+      } catch (error) {
+        controller.error(error);
+        rejectDone(error);
+      }
+    },
+    cancel(reason) {
+      reader.cancel(reason);
+      resolveDone();
+    },
+  });
+
+  return { body: tracked, done };
+}
+
 // ─── 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
+  currentUrl?: string,
+  signal?: AbortSignal
 ): Promise<FetchResult> {
   const rscUrl = appendRscParam(url);
   const headers = buildRscHeaders(stateTree, currentUrl);
@@ -184,14 +315,24 @@ export async function fetchRscPayload(
     // 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
+    // Intercept the response to read segment metadata 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;
+    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
     let segmentInfo: SegmentInfo[] | null = null;
     let params: Record<string, string | string[]> | null = null;
     let skippedSegments: string[] | null = null;
+    // Track when the full RSC body stream is consumed (not just shell).
+    // Initialized to resolved for bodyless responses; overwritten when
+    // the response has a body.
+    let streamDone: Promise<void> = Promise.resolve();
+
     const wrappedPromise = fetchPromise.then((response) => {
+      // Version skew detection (TIM-446): if the server signals a reload,
+      // throw VersionSkewError so the caller (router navigate) can trigger
+      // a full page reload.
+      if (checkReloadSignal(response)) {
+        throw new VersionSkewError();
+      }
       // 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)
@@ -202,21 +343,61 @@ export async function fetchRscPayload(
       if (redirectLocation) {
         throw new RedirectError(redirectLocation);
       }
-      headElements = extractHeadElements(response);
+      // Detect server error responses. The server returns X-Timber-Error header
+      // with a JSON body instead of a broken RSC stream for any RenderError
+      // (4xx or 5xx). Hard-navigate so the server renders the error page as HTML.
+      // See design/10-error-handling.md §"Error Page Rendering for Client Navigation"
+      if (response.headers.get('X-Timber-Error') === '1') {
+        throw new ServerErrorResponse(response.status, url);
+      }
+      // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload
+      // as React elements — React 19 Float handles them. See TIM-1151.
       segmentInfo = extractSegmentInfo(response);
       params = extractParams(response);
       skippedSegments = extractSkippedSegments(response);
+
+      // Wrap the body to track full stream consumption. createFromFetch's
+      // thenable resolves when the root model (shell) arrives, but we need
+      // to know when ALL chunks are read so the React transition stays
+      // open for the full streaming duration (keeps useOptimistic alive).
+      if (response.body) {
+        const tracked = trackStreamCompletion(response.body);
+        streamDone = tracked.done;
+        streamDone.catch(() => {}); // prevent unhandled rejection
+        return new Response(tracked.body, {
+          headers: response.headers,
+          status: response.status,
+        });
+      }
       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 headers so segmentInfo/params are populated.
     await wrappedPromise;
-    const payload = await deps.decodeRsc(wrappedPromise);
-    return { payload, headElements, segmentInfo, params, skippedSegments };
+    // Start decoding but do NOT await — return the in-progress thenable.
+    // React can render a Flight thenable directly: it suspends on unresolved
+    // parts and progressively renders as chunks arrive, spreading work across
+    // frames instead of blocking the main thread in one burst.
+    const payload = deps.decodeRsc(wrappedPromise);
+    // Combine stream completion with payload error propagation.
+    // streamDone keeps the transition open for the full RSC stream
+    // duration (useOptimistic pending state). payloadError propagates
+    // decode failures (stale client references, Flight parse errors)
+    // so the router's catch block can trigger recovery (stale reload).
+    const payloadError = new Promise<void>((_, reject) => {
+      Promise.resolve(payload).then(() => {}, reject);
+    });
+    payloadError.catch(() => {});
+    const decodePromise = Promise.race([streamDone, payloadError]);
+    return {
+      payload,
+      decodePromise,
+      segmentInfo,
+      params,
+      skippedSegments,
+    };
   }
   // Test/fallback path: return raw text
-  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual' });
+  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
   // Check for redirect in test path too
   if (response.status >= 300 && response.status < 400) {
     const location = response.headers.get('Location');
@@ -226,7 +407,7 @@ export async function fetchRscPayload(
   }
   return {
     payload: await response.text(),
-    headElements: extractHeadElements(response),
+    decodePromise: null,
     segmentInfo: extractSegmentInfo(response),
     params: extractParams(response),
     skippedSegments: extractSkippedSegments(response),

package/src/client/segment-cache.ts

@@ -1,17 +1,14 @@
 // Segment Cache — stores the mounted segment tree and prefetched payloads
 // See design/19-client-navigation.md for architecture details.
 
-import type { HeadElement } from './head';
-
 // ─── Types ───────────────────────────────────────────────────────
 
-/** A prefetched RSC result with optional head elements and segment metadata. */
+/** A prefetched RSC result with optional segment metadata. */
 export interface PrefetchResult {
   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(). */
+  /** Route params from X-Timber-Params header for populating useSegmentParams(). */
   params?: Record<string, string | string[]> | null;
   /** Segment paths skipped by the server (for client-side merging). */
   skippedSegments?: string[] | null;
@@ -26,10 +23,20 @@ export interface SegmentNode {
   segment: string;
   /** The RSC flight payload for this segment (opaque to the cache) */
   payload: unknown;
-  /** Whether the segment is async (async layouts always re-render on navigation) */
-  isAsync: boolean;
+  /**
+   * Whether the segment/slot is request-dependent (calls getHeaders,
+   * getSearchParams, cookies, etc.). Request-dependent segments always
+   * re-render on navigation. For segments, this is still based on the
+   * AsyncFunction heuristic (to be replaced separately). For slots,
+   * this is taint-tracked via ALS.
+   */
+  isRequestDependent: boolean;
   /** Child segments keyed by segment path */
   children: Map<string, SegmentNode>;
+  /** Parallel route slots keyed by slot path (e.g., "/@sidebar") */
+  slots?: Map<string, SegmentNode>;
+  /** Whether this slot's access.ts denied on its last render. */
+  denied?: boolean;
 }
 
 /**
@@ -38,6 +45,7 @@ export interface SegmentNode {
  */
 export interface StateTree {
   segments: string[];
+  slots?: string[];
 }
 
 // ─── Segment Cache ───────────────────────────────────────────────
@@ -82,10 +90,16 @@ export class SegmentCache {
    */
   serializeStateTree(mergeableFilter?: Set<string>): StateTree {
     const segments: string[] = [];
+    const slots: string[] = [];
     if (this.root) {
       collectSyncSegments(this.root, segments, mergeableFilter);
+      collectSyncSlots(this.root, slots);
     }
-    return { segments };
+    const tree: StateTree = { segments };
+    if (slots.length > 0) {
+      tree.slots = slots;
+    }
+    return tree;
   }
 }
 
@@ -95,7 +109,7 @@ function collectSyncSegments(
   out: string[],
   mergeableFilter?: Set<string>
 ): void {
-  if (!node.isAsync && (!mergeableFilter || mergeableFilter.has(node.segment))) {
+  if (!node.isRequestDependent && (!mergeableFilter || mergeableFilter.has(node.segment))) {
     out.push(node.segment);
   }
   for (const child of node.children.values()) {
@@ -103,6 +117,22 @@ function collectSyncSegments(
   }
 }
 
+/** Recursively collect cacheable slot paths from the tree */
+function collectSyncSlots(node: SegmentNode, out: string[]): void {
+  if (node.slots) {
+    for (const slot of node.slots.values()) {
+      // Exclude request-dependent slots (they must re-render every nav)
+      // and denied slots (their cached content is denial fallback, not real content)
+      if (!slot.isRequestDependent && !slot.denied) {
+        out.push(slot.segment);
+      }
+    }
+  }
+  for (const child of node.children.values()) {
+    collectSyncSlots(child, out);
+  }
+}
+
 // ─── Segment Tree Builder ────────────────────────────────────────
 
 /**
@@ -111,7 +141,17 @@ function collectSyncSegments(
  */
 export interface SegmentInfo {
   path: string;
-  isAsync: boolean;
+  /** Outlet key — includes route group name when applicable (e.g., "/(marketing)"). */
+  segmentId?: string;
+  isRequestDependent: boolean;
+  /** True for parallel route slot entries. Slots are keyed by their slot path (e.g., "/@sidebar"). */
+  slot?: boolean;
+  /** Parent segment path for slot entries. Used to attach the slot to the correct SegmentNode. */
+  parentSegment?: string;
+  /** True when the slot's access.ts denied on this render. Denied slots are excluded from the state tree. */
+  denied?: boolean;
+  /** True when the slot was skipped (cached content reused). Payloads with skipped slots are not replayable. */
+  skipped?: boolean;
 }
 
 /**
@@ -129,32 +169,66 @@ export function buildSegmentTree(segments: SegmentInfo[]): SegmentNode | undefin
   // Need at least a root segment to build a tree
   if (segments.length === 0) return undefined;
 
-  // Exclude the leaf (page) — pages always re-render on navigation.
-  // Only layouts are cached in the segment tree.
-  const layouts = segments.length > 1 ? segments.slice(0, -1) : segments;
+  // Separate slot entries from segment entries. Slots are attached to
+  // their parent segment node after the main chain is built.
+  const segmentEntries: SegmentInfo[] = [];
+  const slotEntries: SegmentInfo[] = [];
+  for (const info of segments) {
+    if (info.slot) {
+      slotEntries.push(info);
+    } else {
+      segmentEntries.push(info);
+    }
+  }
 
+  // Build the main segment chain.
   let root: SegmentNode | undefined;
   let parent: SegmentNode | undefined;
+  const nodeById = new Map<string, SegmentNode>();
 
-  for (const info of layouts) {
+  for (const info of segmentEntries) {
+    const id = info.segmentId ?? info.path;
     const node: SegmentNode = {
-      segment: info.path,
+      segment: id,
       payload: null,
-      isAsync: info.isAsync,
+      isRequestDependent: info.isRequestDependent,
       children: new Map(),
     };
 
+    nodeById.set(id, node);
+
     if (!root) {
       root = node;
     }
 
     if (parent) {
-      parent.children.set(info.path, node);
+      parent.children.set(id, node);
     }
 
     parent = node;
   }
 
+  // Attach slot entries to their parent segment nodes.
+  for (const slotInfo of slotEntries) {
+    const parentId = slotInfo.parentSegment;
+    const parentNode = parentId ? nodeById.get(parentId) : root;
+    if (!parentNode) continue;
+
+    const slotId = slotInfo.segmentId ?? slotInfo.path;
+    const slotNode: SegmentNode = {
+      segment: slotId,
+      payload: null,
+      isRequestDependent: slotInfo.isRequestDependent,
+      children: new Map(),
+      denied: slotInfo.denied,
+    };
+
+    if (!parentNode.slots) {
+      parentNode.slots = new Map();
+    }
+    parentNode.slots.set(slotId, slotNode);
+  }
+
   return root;
 }