@rangojs/router 0.19.1 → 0.21.0

package/src/server/request-context.ts

@@ -47,6 +47,7 @@ import { type MetricsStore } from "./context.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
+import type { RouterVersions } from "../router-versions.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
 import type { TransitionWhenRecord } from "../router/transition-when.js";
@@ -377,7 +378,7 @@ export interface RequestContext<
 
   /**
    * @internal Loader-family snapshot seed for a shell HIT's tail render:
-   * segment-key -> the capture's elided container (already Flight-deserialized
+   * loader id -> the capture's elided container (already Flight-deserialized
    * by serveShellHit) plus its capture-computed hole bit. resolveLoaderData
    * overlays it onto the fresh run's container (recorded paths pinned,
    * hole-marker paths keep the fresh nested promises) so the payload's baked
@@ -385,7 +386,9 @@ export interface RequestContext<
    * and does not run the loader. Two owners: serveShellHit sets it on the
    * HIT tail's derived context, and matchPartialWithPprReplay sets it on the
    * request context of a PPR partial replay once its doc record hits, and
-   * restores the previous value after the match.
+   * restores the previous value after the match. Read through servedPins
+   * (loader-cache.ts) only: it also decides which of the record's
+   * loader-owned handle pushes stand (loaderPins).
    */
   _shellLoaderSeed?: Map<
     string,
@@ -446,9 +449,7 @@ export interface RequestContext<
      * scope replaces any route-derived cache() scope for the tail's match
      * (resolveShellImplicitCacheScope), and a lookup that does not hit throws
      * ShellRecordUnavailableError instead of resolving segments
-     * (withCacheLookup): a HIT never runs a handler. The record's
-     * loader-owned handle pushes restore as authoritative
-     * (HandleStore.pushRestored): the prelude rendered them.
+     * (withCacheLookup): a HIT never runs a handler.
      */
     docTail?: true;
     /**
@@ -857,6 +858,15 @@ export interface RequestContext<
    *  lookups per router (route-map-builder.ts) */
   _routerId?: string;
 
+  /**
+   * @internal Cache versions of the router serving this request. The cache
+   * factory builds a store per request without knowing the router, so a store
+   * reads its key versions from here, lazily, the same way CFCacheStore
+   * resolves its base URL (getCacheVersions, server/build-version-table.ts).
+   * Unset on a context no router created; a store then uses the build version.
+   */
+  _versions?: RouterVersions;
+
   /**
    * @internal RouteSnapshot from classifyRequest, reused by match/matchPartial
    * to avoid a second resolveRoute call. Cleared on HMR invalidation.
@@ -966,6 +976,7 @@ export type PublicRequestContext<
   | "_tracing"
   | "_basename"
   | "_routerId"
+  | "_versions"
   | "_setStatus"
   | "_rotateStateCookie"
   | "_setKeepCacheDirective"
@@ -1130,8 +1141,13 @@ export interface CreateRequestContextOptions<TEnv> {
   themeConfig?: ResolvedThemeConfig | null;
   /** Resolved rango state cookie name, for the server seat of invalidateClientCache(). */
   stateCookieName?: string;
-  /** Build version, used as the prefix of a server-rotated rango state value. */
-  version?: string;
+  /**
+   * The versions of the router serving this request (resolveRouterVersions).
+   * Stored as `_versions` for the cache stores; `document` is also the prefix
+   * of a server-rotated rango state value, which the browser compares with the
+   * payload's `metadata.version`.
+   */
+  versions?: RouterVersions;
 }
 
 /**
@@ -1159,7 +1175,7 @@ export function createRequestContext<TEnv>(
     build = false,
     themeConfig,
     stateCookieName,
-    version: stateVersion,
+    versions,
   } = options;
   // ctx.request.headers is guarded like headers() (#976); every router read
   // of this request's headers goes through requestHeaders().
@@ -1194,6 +1210,12 @@ export function createRequestContext<TEnv>(
   // Set-Cookie drain (rsc/helpers.ts) run outside any latched funnel scope,
   // where assertCachedHeaderWriteAllowed is a no-op.
   let rawStubHeaders = stubResponse.headers;
+  // Node's util.inspect unwraps this Proxy and calls undici's Headers hook
+  // with the proxy as `this`. That reads `#headersList` and throws (#1000).
+  // Inspect does not consult the get trap, so the hook is an own property of
+  // the target and formats `rawStubHeaders`. Read on each call: setStatus
+  // rebinds that let to a new Headers.
+  const NODE_INSPECT = Symbol.for("nodejs.util.inspect.custom");
   const guardedStubHeaders: Headers = new Proxy(new Headers(), {
     get(_target, prop) {
       const raw = rawStubHeaders;
@@ -1208,6 +1230,22 @@ export function createRequestContext<TEnv>(
       return (value as (...a: unknown[]) => unknown).bind(raw);
     },
   });
+  Object.defineProperty(guardedStubHeaders, NODE_INSPECT, {
+    value(...args: unknown[]): unknown {
+      const hook = (rawStubHeaders as unknown as Record<symbol, unknown>)[
+        NODE_INSPECT
+      ];
+      if (typeof hook === "function") return hook.apply(rawStubHeaders, args);
+      // DOM Headers has forEach and not entries. Node always has the hook above.
+      const listed: Record<string, string> = {};
+      rawStubHeaders.forEach((value, key) => {
+        listed[key] = value;
+      });
+      return listed;
+    },
+    configurable: true,
+    writable: true,
+  });
   const shadowStubHeaders = (res: Response): void => {
     Object.defineProperty(res, "headers", {
       value: guardedStubHeaders,
@@ -1429,7 +1467,7 @@ export function createRequestContext<TEnv>(
       const prevRaw =
         (requestHeaders(request).get("x-rango-state") || null) ??
         getRawCookieValue(cookieHeader, stateCookieName);
-      const value = mintStateValue(stateVersion ?? "0", prevRaw);
+      const value = mintStateValue(versions?.document ?? "0", prevRaw);
       // rawStubHeaders: guard-exempt internal writer — invalidateClientCache()
       // is documented callable from loaders and during shell capture.
       rawStubHeaders.append(
@@ -1505,6 +1543,7 @@ export function createRequestContext<TEnv>(
 
     _handleStore: handleStore,
     _cacheStore: cacheStore,
+    _versions: versions,
     _searchParamsFilter: searchParamsFilter,
     _explicitTaggedStores: explicitTaggedStores,
     _requestTags: new Set<string>(),
@@ -1515,11 +1554,23 @@ export function createRequestContext<TEnv>(
 
     waitUntil(fn: () => Promise<void>): void {
       if (ctx.build) return;
-      // Wrap in Promise.resolve().then(fn) so a SYNCHRONOUS throw in a
+      // A deferred task does not rely on the platform carrying the request's
+      // async context into it. Deployed workerd lost it once ("use cache"
+      // background revalidation, cache-runtime.ts); Node and miniflare never
+      // do, so no local run shows a loss. A cache store builds its key inside
+      // the task and reads the serving router's versions and the request host
+      // from the context: without it the write lands under the whole-build
+      // pair, which no router with its own version reads. So the task
+      // re-enters the context it was scheduled under: the store active then
+      // (a derived context), else this one.
+      const scheduledUnder = requestContextStorage.getStore() ?? ctx;
+      // Wrap in Promise.resolve().then(...) so a SYNCHRONOUS throw in a
       // non-async callback becomes a rejected promise handed to the host's
       // waitUntil (logged as a background failure), instead of escaping into
       // the request flow. Mirrors fireAndForgetWaitUntil's deferral.
-      const task = Promise.resolve().then(fn);
+      const task = Promise.resolve().then(() =>
+        requestContextStorage.run(scheduledUnder, fn),
+      );
       // Track the task promise so the PPR shell capture can settle the
       // foreground's deferred cache writes before its own match/render (the
       // ordering edge; see _pendingBackgroundTasks). The capture task itself

package/src/ssr/entry-preload-priority.ts

@@ -0,0 +1,308 @@
+/**
+ * The client entry's head hint at default fetch priority, after the head chunk
+ * scripts (issue #1025).
+ *
+ * For `bootstrapModules`, Fizz writes `<link rel="modulepreload"
+ * fetchPriority="low">` into the head and claims the URL
+ * (`moduleScriptResources[url] = null`, react-dom 19.3.0
+ * `react-dom-server.edge.production.js:546-565`) before the render starts, so
+ * no `preloadModule`/`preinitModule` call can replace it, and the
+ * `bootstrapModules` entry shape has no priority field. Chromium fetches that
+ * hint at Low, and once it boosts in-viewport images to High after first
+ * layout, the entry queues behind them; the executing end-of-shell module
+ * script reuses the in-flight Low fetch through the module map. Hydration
+ * then waits on a few-hundred-byte file while the head chunk scripts it
+ * imports (High) have long arrived: measured +3.8 s on a priority-honouring
+ * HTTP/2 link at Slow 4G.
+ *
+ * The fix serves that one tag without the attribute, so it fetches at
+ * Chromium's modulepreload default (High), and moves it after the head
+ * chunk scripts. Fizz flushes the bootstrap hint before the head chunk scripts; at
+ * High in that position it took one of HTTP/1.1's six connections ahead of
+ * the react chunk and delayed the last head chunk (hydration +91 ms, LCP
+ * +84 ms measured). After the scripts it is the last High request in the
+ * queue, so it never displaces a chunk hydration also needs. The accepted
+ * cost: an HTTP/2 server that sends equal-priority streams first in, first
+ * out delivers it with the last head chunk instead of before it (text-only
+ * pages +12 to +56 ms measured, against -0.15 to -3.3 s hydration on image
+ * pages; CHANGELOG has the matrix). Everything else about the bootstrap pair
+ * stays Fizz's: the nonce, the executing `id="_R_"` tag, the URL claim that
+ * keeps plugin-rsc's and the preinit hook's calls for the entry inert, and the
+ * PPR prelude/resume behaviour.
+ *
+ * The match is the exact tag Fizz writes for a string `bootstrapModules`
+ * entry (`rel`, `fetchPriority`, `nonce`, `href` in that order), not a
+ * pattern, and only before the first `<body`. A Fizz version that writes it
+ * differently leaves the bytes untouched: the output keeps the Low hint.
+ *
+ * Where the tag goes: right after the run of Fizz resource tags that directly
+ * follows the hint, before the first token that is anything else (`</head>`,
+ * the app's own head children, or body content in a head-less document).
+ * Fizz flushes the head chunk scripts and the bulk preloads straight after
+ * the bootstrap hint (react-dom 19.3.0 `flushCompletedQueues`, `:7321-7325`),
+ * as `<script …></script>` with no body and `<link …/>`; the scan accepts
+ * only those two shapes and stops at any other token without reading into it.
+ * It never searches the app's head content for `</head>` or `<body`: React
+ * does not escape either inside `<script>` or `<style>` text, so a head script
+ * holding the string `"<body>"` once received the tag inside its source and
+ * threw. Fizz escapes `>` in attribute values, so the first `>` ends a tag.
+ * Every insertion point is the boundary between two complete tags; a stream
+ * that ends mid-run, or a run tag longer than {@link MAX_HELD_TAG}, gets the
+ * tag before the unfinished one. Only that one tag is held back while the run
+ * streams; each complete run tag is forwarded as soon as it is scanned.
+ */
+
+const LOW_PRIORITY_ATTR = ' fetchPriority="low"';
+const encoder = new TextEncoder();
+const BODY_OPEN = encoder.encode("<body");
+const LINK_OPEN = encoder.encode("<link");
+const SCRIPT_OPEN = encoder.encode("<script");
+const SCRIPT_CLOSE = encoder.encode("</script>");
+const GT = 0x3e;
+
+/**
+ * Longest run tag held while its end has not arrived. Fizz's chunk scripts
+ * and preload links are a few hundred bytes; past this the tag goes before
+ * the held one, which keeps the per-chunk work bounded.
+ */
+const MAX_HELD_TAG = 8192;
+
+/** React's escapeTextForBrowser: the attribute escaping Fizz applies. */
+function escapeAttr(value: string): string {
+  return value.replace(/["&'<>]/g, (c) =>
+    c === '"'
+      ? "&quot;"
+      : c === "&"
+        ? "&amp;"
+        : c === "'"
+          ? "&#x27;"
+          : c === "<"
+            ? "&lt;"
+            : "&gt;",
+  );
+}
+
+interface EntryHintBytes {
+  low: Uint8Array;
+  auto: Uint8Array;
+}
+
+function entryHintBytes(
+  entryUrl: string,
+  nonce: string | undefined,
+): EntryHintBytes {
+  const tail =
+    (nonce ? ` nonce="${escapeAttr(nonce)}"` : "") +
+    ` href="${escapeAttr(entryUrl)}"/>`;
+  return {
+    low: encoder.encode(`<link rel="modulepreload"${LOW_PRIORITY_ATTR}${tail}`),
+    auto: encoder.encode(`<link rel="modulepreload"${tail}`),
+  };
+}
+
+function indexOfBytes(
+  haystack: Uint8Array,
+  needle: Uint8Array,
+  from = 0,
+): number {
+  const first = needle[0];
+  const last = haystack.length - needle.length;
+  outer: for (let i = from; i <= last; i++) {
+    if (haystack[i] !== first) continue;
+    for (let j = 1; j < needle.length; j++) {
+      if (haystack[i + j] !== needle[j]) continue outer;
+    }
+    return i;
+  }
+  return -1;
+}
+
+/**
+ * Length of the longest suffix of `buf` that is a proper prefix of `needle`:
+ * the bytes a chunk boundary may have split off a match.
+ */
+function partialSuffixLength(buf: Uint8Array, needle: Uint8Array): number {
+  const max = Math.min(buf.length, needle.length - 1);
+  outer: for (let len = max; len > 0; len--) {
+    const start = buf.length - len;
+    for (let j = 0; j < len; j++) {
+      if (buf[start + j] !== needle[j]) continue outer;
+    }
+    return len;
+  }
+  return 0;
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+/** Index of the hint in `buf` when it precedes the first `<body`, else -1. */
+function findHint(buf: Uint8Array, hint: EntryHintBytes): number {
+  const bodyAt = indexOfBytes(buf, BODY_OPEN);
+  return indexOfBytes(bodyAt === -1 ? buf : buf.subarray(0, bodyAt), hint.low);
+}
+
+/**
+ * 1 when `needle` starts at `pos`, 0 when it does not, -1 when `buf` ends
+ * before that can be decided (the available bytes match a prefix).
+ */
+function matchAt(buf: Uint8Array, pos: number, needle: Uint8Array): number {
+  const n = Math.min(needle.length, buf.length - pos);
+  for (let j = 0; j < n; j++) {
+    if (buf[pos + j] !== needle[j]) return 0;
+  }
+  return n === needle.length ? 1 : -1;
+}
+
+/** HTML whitespace, `/` or `>`: the byte that ends a tag name. */
+function endsTagName(byte: number): boolean {
+  return (
+    byte === 0x20 ||
+    byte === 0x09 ||
+    byte === 0x0a ||
+    byte === 0x0c ||
+    byte === 0x0d ||
+    byte === 0x2f ||
+    byte === GT
+  );
+}
+
+interface RunScan {
+  /** The run ended: `at` is the first byte of the token after it. */
+  ended: boolean;
+  /** Insertion point, or the start of the unfinished token when not ended. */
+  at: number;
+}
+
+/**
+ * Skip the run of Fizz resource tags at the start of `buf`: `<link …>` and
+ * `<script …></script>` with nothing between the two tags.
+ */
+function scanRun(buf: Uint8Array): RunScan {
+  let pos = 0;
+  while (pos < buf.length) {
+    const link = matchAt(buf, pos, LINK_OPEN);
+    const script = link === 1 ? 0 : matchAt(buf, pos, SCRIPT_OPEN);
+    if (link !== 1 && script !== 1) {
+      return { ended: link === 0 && script === 0, at: pos };
+    }
+    const nameEnd = pos + (link === 1 ? LINK_OPEN.length : SCRIPT_OPEN.length);
+    if (nameEnd >= buf.length) return { ended: false, at: pos };
+    if (!endsTagName(buf[nameEnd]!)) return { ended: true, at: pos };
+    const gt = buf.indexOf(GT, nameEnd);
+    if (gt === -1) return { ended: false, at: pos };
+    let end = gt + 1;
+    if (script === 1) {
+      const close = matchAt(buf, end, SCRIPT_CLOSE);
+      // An inline script body: the hint goes before the <script, never in it.
+      if (close !== 1) return { ended: close === 0, at: pos };
+      end += SCRIPT_CLOSE.length;
+    }
+    pos = end;
+  }
+  return { ended: false, at: pos };
+}
+
+/** `rest` with `hint` inserted at `at`. */
+function insertAt(rest: Uint8Array, at: number, hint: Uint8Array): Uint8Array {
+  const out = new Uint8Array(rest.length + hint.length);
+  out.set(rest.subarray(0, at), 0);
+  out.set(hint, at);
+  out.set(rest.subarray(at), at + hint.length);
+  return out;
+}
+
+/**
+ * Rewrite a complete document prefix (the PPR shell capture's prelude).
+ * Returns `bytes` unchanged when no hint precedes the first `<body`.
+ */
+export function rewriteEntryPreloadPriority(
+  bytes: Uint8Array,
+  entryUrl: string,
+  nonce?: string,
+): Uint8Array {
+  const hint = entryHintBytes(entryUrl, nonce);
+  const at = findHint(bytes, hint);
+  if (at === -1) return bytes;
+  const rest = bytes.subarray(at + hint.low.length);
+  return concat(
+    bytes.subarray(0, at),
+    insertAt(rest, scanRun(rest).at, hint.auto),
+  );
+}
+
+/**
+ * Streaming form for live SSR: the same rewrite as
+ * {@link rewriteEntryPreloadPriority}, then pass-through. Before the hint is
+ * found, only a chunk tail that may be the start of a split `<body` or hint
+ * tag is held back. After it, complete run tags are forwarded as they are
+ * scanned and only an unfinished one (at most {@link MAX_HELD_TAG} bytes) is
+ * held, so every byte is scanned a bounded number of times. Once the tag is
+ * placed, or once `<body` passes without a hint, chunks are forwarded
+ * untouched and unscanned.
+ */
+export function entryPreloadPriorityTransform(
+  entryUrl: string,
+  nonce?: string,
+): TransformStream<Uint8Array, Uint8Array> {
+  const hint = entryHintBytes(entryUrl, nonce);
+  let carry: Uint8Array | null = null;
+  // The unfinished run tag after the removed hint (possibly empty).
+  let held: Uint8Array | null = null;
+  let done = false;
+  const place = (
+    rest: Uint8Array,
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ): void => {
+    const scan = scanRun(rest);
+    if (scan.ended || rest.length - scan.at > MAX_HELD_TAG) {
+      done = true;
+      held = null;
+      controller.enqueue(insertAt(rest, scan.at, hint.auto));
+      return;
+    }
+    if (scan.at > 0) controller.enqueue(rest.slice(0, scan.at));
+    held = rest.slice(scan.at);
+  };
+  return new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      if (done) {
+        controller.enqueue(chunk);
+        return;
+      }
+      if (held) {
+        place(concat(held, chunk), controller);
+        return;
+      }
+      const buf: Uint8Array = carry ? concat(carry, chunk) : chunk;
+      carry = null;
+      const at = findHint(buf, hint);
+      if (at !== -1) {
+        if (at > 0) controller.enqueue(buf.slice(0, at));
+        place(buf.subarray(at + hint.low.length), controller);
+        return;
+      }
+      if (indexOfBytes(buf, BODY_OPEN) !== -1) {
+        done = true;
+        controller.enqueue(buf);
+        return;
+      }
+      const hold = Math.max(
+        partialSuffixLength(buf, hint.low),
+        partialSuffixLength(buf, BODY_OPEN),
+      );
+      if (hold > 0) carry = buf.slice(buf.length - hold);
+      const out = hold > 0 ? buf.subarray(0, buf.length - hold) : buf;
+      if (out.length > 0) controller.enqueue(out);
+    },
+    flush(controller) {
+      if (carry) controller.enqueue(carry);
+      // The stream ended inside the run: the tag goes before the unfinished one.
+      if (held) controller.enqueue(concat(hint.auto, held));
+    },
+  });
+}

package/src/ssr/index.tsx

@@ -2,6 +2,10 @@ import React from "react";
 import { createSsrRootComponent, deserializeSsrPayload } from "./ssr-root.js";
 import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
 import { runWithPreinitNonce } from "./preinit-client-references.js";
+import {
+  entryPreloadPriorityTransform,
+  rewriteEntryPreloadPriority,
+} from "./entry-preload-priority.js";
 import {
   POST_QUIESCE_TASK_HOPS,
   SHELL_CAPTURE_MAX_WAIT_MS,
@@ -189,6 +193,7 @@ export interface SSRDependencies<TEnv = unknown> {
    * undefined keeps the inline bootstrap verbatim, so a custom SSR entry that
    * never installed the preinit hook cannot drift into the half-converted
    * state on upgrade (the generated entry always passes an explicit value).
+   * Any other value throws when the handler is created.
    */
   headScripts?: HeadScriptsOption;
 
@@ -521,9 +526,23 @@ const MISSING_BOOTSTRAP_MSG =
  * getClientEntryUrl only counts under an explicit `headScripts: "preinit"` —
  * any other headScripts keeps the inline path, so its presence alone is a
  * misconfiguration worth flagging rather than silently ignoring.
+ * An unknown headScripts value throws: a custom SSR entry bypasses the
+ * rango({ headScripts }) check in getVirtualEntrySSR, and a typo such as
+ * "prenit" would otherwise run the inline path as if it were "preload".
+ * undefined stays valid (see {@link resolveBootstrap}).
  */
 function assertBootstrapDeps(deps: SSRDependencies): void {
-  const preinit = deps.headScripts === "preinit";
+  const { headScripts } = deps;
+  if (
+    headScripts !== undefined &&
+    headScripts !== "preinit" &&
+    headScripts !== "preload"
+  ) {
+    throw new Error(
+      `[ssr] headScripts must be "preinit" or "preload", received ${JSON.stringify(headScripts)}`,
+    );
+  }
+  const preinit = headScripts === "preinit";
   if (deps.getClientEntryUrl && !preinit) {
     console.warn(
       '[ssr] getClientEntryUrl is ignored without headScripts: "preinit"; ' +
@@ -550,13 +569,18 @@ type BootstrapOptions = Pick<
  * `headScripts: "preinit"`, getClientEntryUrl() (sync — nothing to race)
  * short-circuits to bootstrapModules, and inline content that is exactly
  * `import("<entry-url>")` converts to the URL. React then emits a
- * `<link rel="modulepreload" fetchpriority="low">` hint in the head plus the
- * executing `<script type="module" src async>` at end of shell — the entry
- * fetch starts with the first flushed bytes instead of when the parser reaches
- * an opaque inline script that only reveals the URL once executed. Fizz stamps
- * the request nonce on both tags, and under PPR both land in the stored
- * prelude; on resume React has already cleared the bootstrap fields from the
- * postponed state, so nothing re-emits. The conversion is an explicit opt-in:
+ * `<link rel="modulepreload">` hint in the head plus the executing
+ * `<script type="module" src async>` at end of shell — the entry fetch starts
+ * with the first flushed bytes instead of when the parser reaches an opaque
+ * inline script that only reveals the URL once executed. Fizz writes that hint
+ * with `fetchPriority="low"` ahead of the head chunk scripts; the handlers
+ * serve it without the attribute after the head chunk scripts
+ * (entry-preload-priority.ts, issue #1025), because at Low the entry queued
+ * behind in-viewport images and gated hydration (+3.8 s measured on a
+ * prioritising HTTP/2 link). Fizz stamps the request nonce on both tags, and
+ * under PPR both land in the stored prelude; on resume React has already
+ * cleared the bootstrap fields from the postponed state, so nothing re-emits.
+ * The conversion is an explicit opt-in:
  * undefined headScripts (a custom SSR entry that predates the option, which
  * also never installed the preinit hook) keeps the inline bootstrap
  * byte-for-byte — converting by default would break CSPs that allowlist the
@@ -746,8 +770,15 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         await htmlStream.allReady;
       }
 
+      // The entry's Fizz hint at default priority, after the head chunk
+      // scripts (entry-preload-priority.ts).
+      const entryUrl = bootstrap.bootstrapModules?.[0];
+      const html = entryUrl
+        ? htmlStream.pipeThrough(entryPreloadPriorityTransform(entryUrl, nonce))
+        : htmlStream;
+
       // Inject RSC payload into HTML as <script nonce="...">__FLIGHT_DATA__</script>
-      return htmlStream.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
+      return html.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
     } catch (error) {
       reportRenderError(onError, error);
       throw error;
@@ -952,6 +983,12 @@ export function createShellCaptureHandler<TEnv = unknown>(
         const result = await prerenderPromise;
         prelude = await readStreamToUint8Array(result.prelude);
         postponed = result.postponed;
+        // Same hint rewrite as renderHTML, applied to the stored prelude; a
+        // resume never re-emits the bootstrap pair (Fizz clears it).
+        const entryUrl = bootstrap.bootstrapModules?.[0];
+        if (entryUrl) {
+          prelude = rewriteEntryPreloadPriority(prelude, entryUrl);
+        }
       } catch (error) {
         // Identity match: swallow ONLY our own deliberate abort
         // (error === abortReason). Not error.name — capture aborts before this

package/src/ssr/preinit-client-references.ts

@@ -81,11 +81,23 @@ export function runWithPreinitNonce<T>(
  *
  * Known trades (deliberate, measured neutral-to-positive on the e2e apps —
  * PR #694 has the Lighthouse/hydration numbers):
- * - Fetch priority: an executing async module script fetches at Chromium's
- *   async-script priority, below a bare modulepreload hint; preinitModule
- *   forwards no fetchPriority (react-dom's public API drops it — only
- *   `preinit` forwards it). Execution-overlap is bought with hint priority,
- *   the same trade Next.js ships via ReactDOM.preinit.
+ * - Fetch priority: Chromium gives a parser-inserted `async` module script
+ *   initial priority High: below the render-blocking stylesheet (Highest),
+ *   and alongside the LCP image once Chromium boosts the in-viewport image to
+ *   High (#1021). Every head chunk gets the same priority: the shared
+ *   dependency chunks (react, router, entry.rsc and the bundler runtime) and
+ *   every client-component chunk. The entry itself is a Fizz bootstrapModules
+ *   hint, not a preinit (Fizz claims its URL, so this hook's call for it is
+ *   inert); the handlers serve that hint at default priority, High as well,
+ *   after these scripts (entry-preload-priority.ts, #1025).
+ *   Lowering the chunks to `fetchpriority="low"` was measured and rejected
+ *   (#1021; Chromium 153, 20 interleaved runs per variant and cell). On pages
+ *   with images above the fold the Low chunks queue behind the boosted
+ *   images: hydration came 206 to 6407 ms later on HTTP/1.1 and 65 to 642 ms
+ *   later on HTTP/2. The one gain, FCP -136 ms, needed an image-free page
+ *   with 35 KB of render-blocking CSS on HTTP/1.1 Slow 4G, and hydration was
+ *   still 98 ms later there. `headScripts: "preload"` is the way to get Low
+ *   chunk fetches.
  * - Build only: plugin-rsc's dev load path reports `js: []` per reference, so
  *   dev documents have no head chunk scripts — a client module whose module
  *   scope assumes body-parsed DOM can break in production only. The

package/src/ssr/ssr-root.tsx

@@ -7,7 +7,10 @@ import {
 } from "../browser/react/filter-segment-order.js";
 import { ThemeProvider } from "../theme/ThemeProvider.js";
 import { NonceContext } from "../browser/react/nonce-context.js";
-import { NavigationStoreContext } from "../browser/react/context.js";
+import {
+  LocationStateContext,
+  NavigationStoreContext,
+} from "../browser/react/context.js";
 import type { NavigationStoreContextValue } from "../browser/react/context.js";
 import type { HandleData } from "../browser/types.js";
 import type { ResolvedSegment } from "../types.js";
@@ -119,11 +122,17 @@ function createSsrEventController(opts: {
     flushRouteState: () => {},
     setHandleData: () => {},
     getHandleState: () => handleState,
+    freezeHydrationHandleState: () => {},
+    // The server render is the state the document is rendered with.
+    getHydrationHandleState: () => undefined,
     setRouteSegmentIds: () => {},
     setParams: (nextParams) => {
       params = nextParams;
     },
     getParams: () => params,
+    commitLocationState: () => {},
+    getLocationState: () => undefined,
+    takeTreelessLocationState: () => false,
     setLocation: () => {},
     startNavigation: () => {
       throw new Error("Navigation not supported during SSR");
@@ -294,7 +303,7 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
     };
 
     // Build content tree from segments.
-    // Order must match NavigationProvider: NavigationStoreContext > NonceContext > ThemeProvider > content
+    // Order must match NavigationProvider: NavigationStoreContext > LocationStateContext > NonceContext > ThemeProvider > content
     // Memoize like payload/handles above: renderSegments is async, so
     // React.use() on a fresh promise suspends and replays SsrRoot, which
     // would re-run the entire segment-tree build on every initial render.
@@ -324,10 +333,13 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
       <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
     );
 
-    // Wrap with NavigationStoreContext for useNavigation hook
+    // Wrap with NavigationStoreContext for useNavigation hook. The server has
+    // no history entry: location state is undefined, as readers hydrate.
     return (
       <NavigationStoreContext.Provider value={ssrContextValue!}>
-        {content}
+        <LocationStateContext.Provider value={undefined}>
+          {content}
+        </LocationStateContext.Provider>
       </NavigationStoreContext.Provider>
     );
   };