@rangojs/router 0.19.0 → 0.20.0

package/src/cache/cache-tag.ts

@@ -17,11 +17,19 @@ import {
 } from "../server/request-context.js";
 import {
   getCurrentLoaderBodyId,
+  getLoaderRunIdentity,
   getLoaderBodyTags,
   isInsideLoaderScope,
+  useCacheLoaderIdentityError,
   type LoaderIdentityRead,
   type LoaderIdentityReadVerb,
+  type LoaderRunIdentity,
 } from "../server/context.js";
+import {
+  getCacheExecScope,
+  isInsideIdentityExempt,
+  type CacheExecScope,
+} from "./cache-exec-scope.js";
 import type { ExecutionStart } from "./tag-invalidation.js";
 
 const cacheTagStorage = new AsyncLocalStorage<Set<string>>();
@@ -481,6 +489,102 @@ export function recordedIdentityRead(
   return undefined;
 }
 
+/**
+ * Loader value identity (#1011). Each loader execution's value promise maps to
+ * its LoaderRunIdentity (server/context.ts); a loader-cache binding's value
+ * carries its reads on its recorded-tag set instead (tagLoaderValue,
+ * markIdentityRead). On globalThis like identityReads: the executor that
+ * tracks a value and the reader that checks it must share the map.
+ */
+const loaderRuns: WeakMap<object, LoaderRunIdentity> = ((globalThis as any)[
+  Symbol.for("rangojs-router:loader-runs")
+] ??= new WeakMap());
+
+/**
+ * `value` is the promise of the execution `run` records, started by the
+ * current execution (if any), which reads it. Both loader runners call it
+ * (loader-resolution.ts createLoaderExecutor, request-context.ts
+ * createUseFunction).
+ */
+export function trackLoaderRun(value: object, run: LoaderRunIdentity): void {
+  loaderRuns.set(value, run);
+  linkLoaderRun(value);
+}
+
+/** The current loader execution reads `value`: its record links the value's. */
+function linkLoaderRun(value: object): void {
+  const reader = getLoaderRunIdentity();
+  const run = loaderRuns.get(value);
+  if (reader && run && reader !== run) (reader.reads ??= new Set()).add(run);
+}
+
+/**
+ * The identity read behind a loader value: its execution's or one it read
+ * (nearest first), or the one its recorded-tag set links to.
+ */
+function loaderValueIdentityRead(
+  value: object,
+): LoaderIdentityRead | undefined {
+  const root = loaderRuns.get(value);
+  if (root) {
+    const queue = [root];
+    const seen = new Set<LoaderRunIdentity>();
+    for (let i = 0; i < queue.length; i++) {
+      const run = queue[i]!;
+      if (seen.has(run)) continue;
+      seen.add(run);
+      if (run.read) return run.read;
+      for (const linked of run.reads ?? []) queue.push(linked);
+    }
+  }
+  const tags = loaderValueTags.get(value);
+  return tags && recordedIdentityRead(tags);
+}
+
+/**
+ * A ctx.use(Loader) or getRequestContext().use(Loader) read that returns an
+ * already-started value (the request memo, a loader cache() binding's value).
+ * The current loader execution, if any, links it (it reads the value).
+ * Inside a "use cache" body the value is refused when its execution read
+ * request identity, as a body entered there would have been
+ * (guardIdentityRead). The check runs once the value settles, so a read the
+ * body makes after an await counts. Each enclosing execution also notes the
+ * value, and checks it again after encoding its result
+ * (assertLoaderReadsClean): a read that settles after the value (a nested
+ * promise in it) then fails the write instead.
+ */
+export function readStartedLoaderValue<T>(
+  value: Promise<T>,
+  loaderId: string,
+): Promise<T> {
+  linkLoaderRun(value);
+  const scope = getCacheExecScope();
+  if (!scope || isInsideIdentityExempt()) return value;
+  for (let s: CacheExecScope | undefined = scope; s; s = s.parent) {
+    (s.loaderReads ??= new Map()).set(value, loaderId);
+  }
+  const checked = value.then((resolved) => {
+    assertLoaderValueClean(value, loaderId);
+    return resolved;
+  });
+  // A read the body never awaits must not crash the process as an unhandled
+  // rejection; the write check (assertLoaderReadsClean) still refuses it.
+  checked.catch(() => {});
+  return checked;
+}
+
+/** Throw when a loader value `scope` read carries an identity read. */
+export function assertLoaderReadsClean(scope: CacheExecScope): void {
+  for (const [value, loaderId] of scope.loaderReads ?? []) {
+    assertLoaderValueClean(value, loaderId);
+  }
+}
+
+function assertLoaderValueClean(value: object, loaderId: string): void {
+  const read = loaderValueIdentityRead(value);
+  if (read) throw useCacheLoaderIdentityError(read, loaderId);
+}
+
 /** `root` and every set it links to, transitively. */
 function linkedSets(root: Set<string>): Set<Set<string>> {
   const seen = new Set<Set<string>>();

package/src/router/loader-resolution.ts

@@ -15,8 +15,10 @@ import {
   linkValueTags,
   loaderTagSetsArmed,
   markTagSetStart,
+  readStartedLoaderValue,
   readValueTags,
   tagLoaderValue,
+  trackLoaderRun,
 } from "../cache/cache-tag.js";
 import { executionStart } from "../cache/tag-invalidation.js";
 import type {
@@ -57,8 +59,10 @@ import {
   assertNonCacheableReadAllowed,
   isInsideLoaderScope,
   runInsideLoaderBodyScope,
+  runInsideLoaderRun,
   isInsidePushCallbackScope,
   runInsidePushCallbackScope,
+  type LoaderRunIdentity,
 } from "../server/context.js";
 import { debugLog } from "./logging.js";
 
@@ -479,7 +483,9 @@ function createLoaderExecutor<TEnv>(
     const memo = bound || loaderPromises.get(loader.$$id);
     if (memo) {
       if (recordTags) readValueTags(memo);
-      return memo;
+      // A "use cache" body reading it refuses an identity read the run made
+      // (#1011): the body ran outside the cached function, unguarded.
+      return readStartedLoaderValue(memo, loader.$$id);
     }
 
     // Get loader function - either from loader object or fetchable registry
@@ -724,8 +730,10 @@ function createLoaderExecutor<TEnv>(
     // BAKED copy in every shared artifact (cache(), "use cache", the PPR
     // shell). The cache() guard permits its identity reads; a "use cache"
     // body it was entered in and a PPR capture do not (server/context.ts
-    // guardIdentityRead).
+    // guardIdentityRead), and a "use cache" body that reads the value after
+    // another reader started it refuses what `identity` recorded (#1011).
 
+    const identity: LoaderRunIdentity = { loaderId: loader.$$id };
     const recordedTags = recordTags ? new Set<string>() : undefined;
     // A loader-cache write that stores or reads this value gates on the
     // earliest start behind it (#977, earliestRecordedStart).
@@ -736,7 +744,10 @@ function createLoaderExecutor<TEnv>(
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
       Promise.resolve(
         runInsideLoaderBodyScope(
-          () => loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+          () =>
+            runInsideLoaderRun(identity, () =>
+              loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+            ),
           loader.$$id,
           recordedTags,
         ),
@@ -747,6 +758,7 @@ function createLoaderExecutor<TEnv>(
         runEndStore?.settleLoaderRun(loader.$$id);
       }),
     );
+    trackLoaderRun(promise, identity);
     if (recordedTags) {
       tagLoaderValue(promise, recordedTags);
       readValueTags(promise);

package/src/router/segment-resolution/loader-cache.ts

@@ -96,6 +96,7 @@ import {
   linkRecordedTags,
   markIdentityRead,
   markTagSetStart,
+  readStartedLoaderValue,
   readValueTags,
   recordedIdentityRead,
   recordLoaderTags,
@@ -591,7 +592,7 @@ function executeLoaderData<TEnv>(
         // useLoader.
         linkLoaderTags(item.$$id);
         readValueTags(cached);
-        return cached;
+        return readStartedLoaderValue(cached, item.$$id);
       }
       return originalUse(item);
     }) as typeof ctx.use;

package/src/server/context.ts

@@ -1131,18 +1131,91 @@ const IDENTITY_READ_RECORDER_KEY = Symbol.for(
  * (cache-tag.ts recordedIdentityRead), so both orders fail the same way.
  * Response directives do not record: a key cannot make a skipped body's side
  * effect reach a HIT.
+ *
+ * The read also lands on the execution's LoaderRunIdentity (#1011), which
+ * every execution has, from either loader runner (runInsideLoaderRun).
  */
 export function recordLoaderIdentityRead(
   surface: string,
   verb: LoaderIdentityReadVerb = "called",
 ): void {
   if (isInsideIdentityExempt()) return;
+  const run = loaderRunALS.getStore();
+  if (run && run.read === undefined) {
+    run.read = { surface, verb, bodyId: run.loaderId };
+  }
   const recorder = (globalThis as Record<symbol, unknown>)[
     IDENTITY_READ_RECORDER_KEY
   ] as ((surface: string, verb: LoaderIdentityReadVerb) => void) | undefined;
   recorder?.(surface, verb);
 }
 
+/**
+ * One loader execution's request-identity record (#1011): the first identity
+ * read its body made, and the executions whose values it read with
+ * ctx.use(Loader). Every execution has one; the recorded-tag sets that carry
+ * the same reads for a loader cache() fill (cache-tag.ts) exist only in a
+ * request that binds one.
+ *
+ * A "use cache" function that reads a loader's value through the request
+ * memo (a handler, the route's loader() binding or a parent layout's started
+ * it first) does not run the body, so guardIdentityRead never sees the read.
+ * Scar: the entry, keyed without the cookie, stored the first visitor's value
+ * and served it to the next. cache-tag.ts readStartedLoaderValue refuses such
+ * a value through this record.
+ */
+export interface LoaderRunIdentity {
+  readonly loaderId: string;
+  read?: LoaderIdentityRead;
+  reads?: Set<LoaderRunIdentity>;
+}
+
+// Its own scope, not a LoaderBodyScope field: the request-context runner
+// (request-context.ts createUseFunction) records reads too, but does not
+// enter a loader body scope, whose cache() exemption it never had.
+const loaderRunALS: AsyncLocalStorage<LoaderRunIdentity> = ((globalThis as any)[
+  Symbol.for("rangojs-router:loader-run-identity")
+] ??= new AsyncLocalStorage<LoaderRunIdentity>());
+
+/**
+ * Run a loader body with `run` as its identity record: both loader runners
+ * (loader-resolution.ts createLoaderExecutor, request-context.ts
+ * createUseFunction) enter it around the loader function.
+ */
+export function runInsideLoaderRun<T>(run: LoaderRunIdentity, fn: () => T): T {
+  return loaderRunALS.run(run, fn);
+}
+
+/** The innermost loader execution's identity record (runInsideLoaderRun). */
+export function getLoaderRunIdentity(): LoaderRunIdentity | undefined {
+  return loaderRunALS.getStore();
+}
+
+/**
+ * The error a "use cache" function's read of a loader value fails with when
+ * the loader's execution, or one whose value it read, made `read` (#1011).
+ * Worded like guardIdentityRead's "use cache" refusal, naming the loaders.
+ */
+export function useCacheLoaderIdentityError(
+  read: LoaderIdentityRead,
+  loaderId: string,
+): Error {
+  const bodyId = read.bodyId ?? loaderId;
+  const source =
+    bodyId === loaderId
+      ? `Loader "${loaderId}" ${read.verb} it, and the cached function reads that loader's value`
+      : `Loader "${bodyId}" ${read.verb} it, and the cached function reads loader "${loaderId}", whose value is built from it`;
+  return new Error(
+    `${read.surface} cannot be ${read.verb} inside a "use cache" function. ` +
+      `${source}. The loader ran outside the function (a handler or a ` +
+      `loader() binding started it first), but its value becomes part of ` +
+      `what the function returns, and the cache key does not include it, so ` +
+      `the first caller's value would be stored and served to later callers. ` +
+      `Read the loader before calling the cached function and pass the value ` +
+      `in as an argument so it becomes part of the cache key.`,
+  );
+}
+
 /** The error a loader cache() fill with no declared key fails with (#972). */
 export function loaderCacheIdentityError(
   read: LoaderIdentityRead,
@@ -1344,7 +1417,8 @@ export function runInsideLoaderScope<T>(fn: () => T): T {
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
  * never trip the cache() guard — a route cache() never stores loader values.
  * A "use cache" body the loader was entered in still refuses them
- * (guardIdentityRead).
+ * (guardIdentityRead); one that reads the value later refuses what the run
+ * recorded (runInsideLoaderRun, cache-tag.ts readStartedLoaderValue).
  */
 export function runInsideLoaderBodyScope<T>(
   fn: () => T,

package/src/server/request-context.ts

@@ -64,7 +64,10 @@ import {
   assertCachedHeaderWriteAllowed,
   assertNonCacheableReadAllowed,
   clearPprHeaderScope,
+  runInsideLoaderRun,
+  type LoaderRunIdentity,
 } from "./context.js";
+import { readStartedLoaderValue, trackLoaderRun } from "../cache/cache-tag.js";
 import {
   guardRawCookieRead,
   guardRequestHeaders,
@@ -1859,8 +1862,11 @@ export function createUseFunction<TEnv>(
 
     const loader = item as LoaderDefinition<any, any>;
 
-    if (loaderPromises.has(loader.$$id)) {
-      return loaderPromises.get(loader.$$id);
+    const memo = loaderPromises.get(loader.$$id);
+    if (memo) {
+      // Same refusal as the handler ctx.use memo hit (#1011): a "use cache"
+      // body reading a value whose run read request identity.
+      return readStartedLoaderValue(memo, loader.$$id);
     }
 
     let loaderFn = loader.fn;
@@ -1947,9 +1953,11 @@ export function createUseFunction<TEnv>(
     // (observePhase), so a loader resolved via this base request-context ctx.use
     // co-emits the "loader:<id>" perf metric AND the "rango.loader" span — no
     // drift between the two ctx.use implementations.
+    const run: LoaderRunIdentity = { loaderId: loader.$$id };
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
-      Promise.resolve(loaderFn(loaderCtx)),
+      Promise.resolve(runInsideLoaderRun(run, () => loaderFn(loaderCtx))),
     );
+    trackLoaderRun(promise, run);
 
     loaderPromises.set(loader.$$id, promise);
 

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));
+    },
+  });
+}