@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/client/rsc-fetch.ts

@@ -11,55 +11,291 @@
  * 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';
+import {
+  rscCacheKey,
+  recordLookup,
+  randomRscCacheKey,
+  RSC_KEY_PARAM,
+} from '../shared/rsc-cache-key.ts';
+import type { RscManifest, RscManifestEntry } from '../shared/rsc-manifest.ts';
+import {
+  splitPayloadRoot,
+  readPublishedParams,
+  type PublishedParams,
+} from '../shared/payload-root.ts';
+import { normalizeBasePath, stripBasePath, withBasePath } from '../shared/base-path.ts';
+import { rscPayloadPath } from '../shared/rsc-payload-path.ts';
+import type { SegmentInfo, StateTree } from '../shared/segment-info.ts';
+import { TIMBER_ERROR_HEADER } from '../shared/rsc-error-envelope.ts';
+import { RSC_CONTENT_TYPE, isRscContentType } from '../shared/rsc-media-type.ts';
+import type { RouterDeps } from './router-types.ts';
 
 // ─── 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 {
+  /** The renderable tree, split off the payload root. */
   payload: unknown;
-  headElements: HeadElement[] | null;
+  /**
+   * The params the same payload published beside that tree.
+   *
+   * Not a separate channel: both fields come out of one `splitPayloadRoot`
+   * call on one decoded root, so a response cannot deliver a tree and another
+   * route's params. They used to arrive on their own header, which is how a
+   * navigation could render one route and publish another's (TIM-1285,
+   * TIM-1294).
+   */
+  params: PublishedParams | Promise<PublishedParams>;
+  /**
+   * 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(). */
-  params: Record<string, string | string[]> | null;
   /** Segment paths that were skipped by the server (for client-side merging). */
   skippedSegments: string[] | null;
 }
 
-// ─── Constants ───────────────────────────────────────────────────
+// ─── URL Helpers ─────────────────────────────────────────────────
 
-export const RSC_CONTENT_TYPE = 'text/x-component';
+/**
+ * Append a `_rsc=<key>` query parameter to the URL (TIM-1268).
+ *
+ * The key is a deterministic hash of the RSC request headers, so identical
+ * requests share a URL and the payload becomes cacheable. It also keeps the
+ * document and the payload on different URLs, so a shared cache cannot
+ * return HTML for an RSC request (or vice versa) even where `Vary` is
+ * opt-in configuration rather than default behaviour — Cloudflare and
+ * CloudFront both. See GHSA-wfc6-r584-vfw7, design/13-security.md.
+ *
+ * The origin recomputes this key from the received headers and refuses to
+ * let a mismatched response be shared-cached, so a caller cannot claim
+ * another client's key while sending its own headers.
+ *
+ * Falls back to a random value when no key can be derived — `crypto.subtle`
+ * is absent in non-secure browsing contexts (plain `http://` on a LAN
+ * address). Dropping the parameter instead would put the payload back on
+ * the document URL, where a query-keyed cache that ignores `Vary` could
+ * store a Flight response under `/about` and serve it to an HTML
+ * navigation. The random parameter this feature replaced did separate those
+ * representations, and the fallback must not be worse than what it
+ * replaced. The origin cannot verify a random key, so it refuses to
+ * share-cache the response — which is exactly the old behaviour, where a
+ * unique URL was never a cache hit anyway.
+ *
+ * Strips any #fragment before appending — fragments are client-only and
+ * fetch() discards them, so _rsc would land inside the hash and be lost.
+ */
+async function appendRscParam(url: string, headers: Record<string, string>): Promise<string> {
+  const hashIndex = url.indexOf('#');
+  const urlWithoutHash = hashIndex === -1 ? url : url.slice(0, hashIndex);
+  const key = (await rscCacheKey(recordLookup(headers))) ?? randomRscCacheKey();
+  const separator = urlWithoutHash.includes('?') ? '&' : '?';
+  return `${urlWithoutHash}${separator}${RSC_KEY_PARAM}=${key}`;
+}
 
-// ─── URL Helpers ─────────────────────────────────────────────────
+// ─── 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;
+}
+
+// ─── Base Path ───────────────────────────────────────────────────
+
+/**
+ * The deployment base path (Vite's resolved `base`), normalized.
+ * Set at bootstrap from `virtual:timber-config`; `'/'` unless the app is
+ * deployed under a sub-path. See design/11-platform.md, TIM-1261.
+ *
+ * **The base is applied in exactly one place: at fetch time**
+ * (`toStaticRscUrl`). The static build writes the RSC manifest with
+ * root-relative keys *and* root-relative URLs, so the generated site stays
+ * relocatable and there is no second copy of the base to drift from this one.
+ */
+let basePath = '/';
+
+/** Set the deployment base path. Called once at bootstrap. */
+export function setBasePath(base: string | undefined): void {
+  basePath = normalizeBasePath(base);
+}
+
+/** Get the normalized deployment base path. @internal Exported for testing. */
+export function getBasePath(): string {
+  return basePath;
+}
+
+// ─── Static Mode ────────────────────────────────────────────────
+
+/**
+ * When true, RSC fetches use _rsc/*.rsc file URLs instead of
+ * the route URL with Accept headers. Static hosts ignore Accept
+ * headers, so the client must fetch the pre-generated .rsc files
+ * directly. Set at bootstrap from virtual:timber-config output mode.
+ */
+let staticMode = false;
+
+export function setStaticMode(enabled: boolean): void {
+  staticMode = enabled;
+}
+
+export function isStaticMode(): boolean {
+  return staticMode;
+}
 
 /**
- * Generate a short random cache-busting ID (5 chars, a-z0-9).
- * Matches the format Next.js uses for _rsc params.
+ * RSC manifest mapping unhashed → content-hashed `.rsc` URLs. Populated from
+ * `window.__TIMBER_RSC_MANIFEST__` (injected into HTML during static
+ * generation). Shape shared with the static build that writes it — see
+ * `shared/rsc-manifest.ts`. See TIM-1254.
  */
-function generateCacheBustId(): string {
-  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
-  let id = '';
-  for (let i = 0; i < 5; i++) {
-    id += chars[(Math.random() * 36) | 0];
+let rscManifest: RscManifest | null = null;
+
+function getRscManifest(): RscManifest | null {
+  if (rscManifest) return rscManifest;
+  if (typeof window !== 'undefined' && (window as any).__TIMBER_RSC_MANIFEST__) {
+    rscManifest = (window as any).__TIMBER_RSC_MANIFEST__;
   }
-  return id;
+  return rscManifest;
+}
+
+/** @internal Exported for testing. */
+export function setRscManifest(manifest: RscManifest | null): void {
+  rscManifest = manifest;
+}
+
+/** A resolved static payload target: the URL to fetch, and how it was resolved. */
+interface StaticRscTarget {
+  /** Fetchable URL — base-prefixed. */
+  url: string;
+  /**
+   * True when the RSC manifest supplied a content-hashed filename. The hash
+   * guarantees freshness, so no `_rsc` cache key is appended (TIM-1254).
+   */
+  hashed: boolean;
 }
 
 /**
- * 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.
+ * Resolve a route URL to the `_rsc/*.rsc` file to fetch. The naming rule is
+ * `shared/rsc-payload-path.ts`, shared with the build that writes the files.
+ *
+ * When an RSC manifest is available (hashed filenames from TIM-1254),
+ * the manifest is consulted to resolve to the hashed path.
+ *
+ *   /           → /_rsc/index.rsc (or /_rsc/index-B7YxEKdN.rsc with manifest)
+ *   /about      → /_rsc/about/index.rsc (or /_rsc/about/index-C8ZzFLfO.rsc)
+ *   /blog/hello → /_rsc/blog/hello/index.rsc
+ *
+ * The manifest is written and read in route space (no base prefix), so the
+ * base is applied here — once, on the way out. See client/base-path.ts.
  */
-function appendRscParam(url: string): string {
-  const separator = url.includes('?') ? '&' : '?';
-  return `${url}${separator}_rsc=${generateCacheBustId()}`;
+function toStaticRscUrl(url: string): StaticRscTarget {
+  const unhashed = toUnhashedRscUrl(url);
+  const hashedUrl = manifestLookup(unhashed);
+  return { url: withBasePath(basePath, hashedUrl ?? unhashed), hashed: hashedUrl !== null };
 }
 
+/**
+ * Compute the unhashed `_rsc/*.rsc` path for a route URL.
+ *
+ * Returns a **route-space** path: the deployment base is stripped from the
+ * incoming URL and is NOT re-applied, because this value doubles as the RSC
+ * manifest key, and the manifest is base-less. `toStaticRscUrl` applies the
+ * base to whatever is actually fetched.
+ *
+ * @internal Exported for testing.
+ */
+export function toUnhashedRscUrl(url: string): string {
+  const hashIndex = url.indexOf('#');
+  const queryIndex = url.indexOf('?');
+  const hashEnd = hashIndex === -1 ? url.length : hashIndex;
+  const queryEnd = queryIndex === -1 ? url.length : queryIndex;
+  const end = Math.min(hashEnd, queryEnd);
+  let pathname = stripBasePath(basePath, url.slice(0, end));
+  // Strip trailing slash (unless root) to match static build output naming
+  if (pathname.length > 1 && pathname.endsWith('/')) {
+    pathname = pathname.slice(0, -1);
+  }
+  return rscPayloadPath(pathname);
+}
+
+/**
+ * Look up a key in the RSC manifest, falling back to percent-decoded
+ * lookup for encoded browser URLs. Returns the entry or null.
+ */
+function manifestEntry(key: string): RscManifestEntry | null {
+  const manifest = getRscManifest();
+  if (!manifest) return null;
+  if (manifest[key]) return manifest[key];
+  try {
+    const decoded = decodeURIComponent(key);
+    if (decoded !== key && manifest[decoded]) return manifest[decoded];
+  } catch {
+    // Malformed percent sequence (e.g. /100%.rsc) — skip decoded lookup
+  }
+  return null;
+}
+
+/**
+ * Look up the hashed URL for an unhashed RSC path.
+ */
+function manifestLookup(key: string): string | null {
+  return manifestEntry(key)?.url ?? null;
+}
+
+// The manifest used to inline each route's params, because a generated
+// `.rsc` file carries no response headers and the header channel therefore
+// did not exist on the static path (TIM-1255, TIM-1285). The `.rsc` file now
+// carries them itself — they are props inside the payload — so the static
+// path needs no special case at all.
+
+// ─── 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 ──────────────────────────────────────────────
+
+/**
+ * Build the headers for an RSC payload request.
+ *
+ * **Every header added here is hashed into the payload URL** as the `_rsc`
+ * cache key (see `rscCacheKey`), and URLs are logged by proxies, CDNs, and
+ * origin access logs. So: no credentials, no session identifiers, no
+ * user-supplied content. `fnv1aHash` is a cache-key hash, not a KDF — a
+ * low-entropy secret would be recoverable from the URL by brute force.
+ * Authentication already travels on cookies, which are not part of this
+ * object and never enter the key.
+ */
 export function buildRscHeaders(
-  stateTree: { segments: string[] } | undefined,
+  stateTree: StateTree | undefined,
   currentUrl?: string
 ): Record<string, string> {
   const headers: Record<string, string> = {
@@ -75,22 +311,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 +338,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 +348,7 @@ export function extractSegmentInfo(response: Response): SegmentInfo[] | null {
   try {
     return JSON.parse(header);
   } catch {
+    warnMalformedHeader('X-Timber-Segments', header);
     return null;
   }
 }
@@ -127,22 +368,7 @@ export function extractSkippedSegments(response: Response): string[] | null {
     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 {
+    warnMalformedHeader('X-Timber-Skipped-Segments', header);
     return null;
   }
 }
@@ -161,37 +387,159 @@ 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;
+  }
+}
+
+/**
+ * Thrown when the RSC fetch response has a Content-Type that is not
+ * text/x-component — e.g., a static asset (image, CSS, JS) served
+ * for a same-origin URL that isn't a route. The response body is
+ * cancelled immediately (headers-only cost). Caught in navigate()
+ * to trigger a hard navigation; caught in prefetch() to store a
+ * negative cache entry so click hard-navigates without a second fetch.
+ *
+ * See TIM-1231.
+ */
+export class NonRscResponse extends Error {
+  readonly url: string;
+  constructor(url: string) {
+    super(`Non-RSC response for ${url}`);
+    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).
+ *
+ * createFromFetch's thenable resolves on shell arrival, but callers need to
+ * know when the stream is fully decoded: that is what `navigateTransition`'s
+ * returned promise means, and what the router's pending store, the Navigation
+ * API deferred and `<Link>`'s `isPending` are all timed against.
+ */
+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);
+  // In static mode, fetch the pre-generated _rsc/*.rsc file directly
+  // instead of the route URL with Accept headers. Static hosts ignore
+  // Accept headers, so the route URL would return HTML.
+  const staticTarget = staticMode ? toStaticRscUrl(url) : null;
+  const fetchTarget = staticTarget ? staticTarget.url : url;
+  // Static hosts resolve neither partial payloads nor intercepting routes,
+  // so neither the state tree nor the source URL is sent — and neither may
+  // fragment the cache key of a file that does not vary on them.
+  const headers = staticMode
+    ? buildRscHeaders(undefined, undefined)
+    : buildRscHeaders(stateTree, currentUrl);
+  // Skip the cache key when the manifest supplies a content-hashed
+  // URL — the hash itself guarantees freshness, and the param would defeat
+  // the immutable cache headers on /_rsc/* (TIM-1254).
+  const rscUrl = staticTarget?.hashed ? fetchTarget : await appendRscParam(fetchTarget, headers);
+  // Deriving the cache key is async (SubtleCrypto), so the fetch is no
+  // longer issued in the same tick as the call. A navigation superseded
+  // during that window would otherwise still hit the network with an
+  // already-aborted signal.
+  signal?.throwIfAborted();
   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
+    // 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 +550,90 @@ 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(TIMBER_ERROR_HEADER) === '1') {
+        throw new ServerErrorResponse(response.status, url);
+      }
+      // Content-Type guard: reject non-RSC responses before createFromFetch
+      // tries to parse the body as Flight data.
+      // In static mode, accept octet-stream/text/plain/absent content-type
+      // (static hosts serve .rsc files with these), but still reject 404s
+      // and text/html (missing .rsc file → host returns 404 page or SPA
+      // HTML fallback). See TIM-1231, TIM-1243, TIM-1247.
+      if (staticMode) {
+        const contentType = response.headers.get('content-type');
+        if (
+          !response.ok ||
+          (contentType && contentType.split(';')[0].trim().toLowerCase() === 'text/html')
+        ) {
+          response.body?.cancel();
+          throw new NonRscResponse(url);
+        }
+      } else {
+        if (!isRscContentType(response.headers.get('content-type'))) {
+          response.body?.cancel();
+          throw new NonRscResponse(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 — that is what the navigation
+      // promise resolving means, and what keeps the pending store set.
+      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 is 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 root = deps.decodeRsc(wrappedPromise);
+    // One split, one root: the tree and the params it was rendered with come
+    // apart here and nowhere else, so nothing downstream has to keep them
+    // paired by hand.
+    const { tree: payload, params } = splitPayloadRoot(root);
+    // Combine stream completion with payload error propagation.
+    // streamDone marks the end of the RSC stream, which is what the
+    // navigation promise resolves on. 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(root).then(() => {}, reject);
+    });
+    payloadError.catch(() => {});
+    const decodePromise = Promise.race([streamDone, payloadError]);
+    // Mark handled, like payloadError above. The same rejection reaches the
+    // router through `payload`, and a navigation that recovers by hard
+    // navigating (version skew, non-RSC response) hangs deliberately and never
+    // awaits this one — leaving it to surface as an unhandled rejection.
+    decodePromise.catch(() => {});
+    return {
+      payload,
+      params,
+      decodePromise,
+      segmentInfo,
+      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');
@@ -224,11 +641,33 @@ export async function fetchRscPayload(
       throw new RedirectError(location);
     }
   }
+  // Server error guard (same as production path above).
+  if (response.headers.get(TIMBER_ERROR_HEADER) === '1') {
+    throw new ServerErrorResponse(response.status, url);
+  }
+  // Content-Type guard (same as production path above). See TIM-1231, TIM-1243, TIM-1247.
+  if (staticMode) {
+    const fallbackContentType = response.headers.get('content-type');
+    if (
+      !response.ok ||
+      (fallbackContentType &&
+        fallbackContentType.split(';')[0].trim().toLowerCase() === 'text/html')
+    ) {
+      response.body?.cancel();
+      throw new NonRscResponse(url);
+    }
+  } else {
+    if (!isRscContentType(response.headers.get('content-type'))) {
+      response.body?.cancel();
+      throw new NonRscResponse(url);
+    }
+  }
+  // Test/fallback path: raw text carries no payload root, so no params.
   return {
     payload: await response.text(),
-    headElements: extractHeadElements(response),
+    params: readPublishedParams(undefined),
+    decodePromise: null,
     segmentInfo: extractSegmentInfo(response),
-    params: extractParams(response),
     skippedSegments: extractSkippedSegments(response),
   };
 }