@rangojs/router 0.0.0-experimental.141 → 0.0.0-experimental.142

package/src/router/match-result.ts

@@ -201,17 +201,23 @@ export function buildMatchResult<TEnv>(
 
   let allIds: string[];
   let segmentsToRender: ResolvedSegment[];
+  let resolvedIds: string[];
 
   if (ctx.isFullMatch) {
+    // One pass over allSegments: dedup by id (segmentsToRender + allIds) while
+    // collecting every id for resolvedIds, which keeps duplicates unlike allIds.
     const seen = new Set<string>();
     segmentsToRender = [];
+    allIds = [];
+    resolvedIds = [];
     for (const s of allSegments) {
+      resolvedIds.push(s.id);
       if (!seen.has(s.id)) {
         seen.add(s.id);
         segmentsToRender.push(s);
+        allIds.push(s.id);
       }
     }
-    allIds = segmentsToRender.map((s) => s.id);
   } else {
     allIds = ctx.interceptResult
       ? ctx.clientSegmentIds.length > 0
@@ -221,11 +227,21 @@ export function buildMatchResult<TEnv>(
 
     allIds = [...new Set(allIds)];
 
+    // One pass over allSegments: keep renderable segments and collect the
+    // handler-ran ids (resolvedIds) together.
     const clientIdSet = new Set(ctx.clientSegmentIds);
-    segmentsToRender = allSegments.filter(
-      (s) =>
-        s.component !== null || s.type === "loader" || !clientIdSet.has(s.id),
-    );
+    segmentsToRender = [];
+    resolvedIds = [];
+    for (const s of allSegments) {
+      if (s._handlerRan) resolvedIds.push(s.id);
+      if (
+        s.component !== null ||
+        s.type === "loader" ||
+        !clientIdSet.has(s.id)
+      ) {
+        segmentsToRender.push(s);
+      }
+    }
   }
 
   const { segments: dedupedSegments, removedIds } = deduplicateLoaderSegments(
@@ -236,20 +252,24 @@ export function buildMatchResult<TEnv>(
   const matchedIds =
     removedIds.size > 0 ? allIds.filter((id) => !removedIds.has(id)) : allIds;
 
-  const resolvedIds = ctx.isFullMatch
-    ? allSegments.map((s) => s.id)
-    : allSegments.filter((s) => s._handlerRan).map((s) => s.id);
-
-  const cleanedSegments = dedupedSegments.map((s) => {
-    if (s._handlerRan === undefined) return s;
-    const { _handlerRan: _drop, ...rest } = s;
-    return rest as ResolvedSegment;
-  });
+  // One pass over dedupedSegments: strip the internal _handlerRan marker and
+  // collect the diff ids (id is unchanged by the strip) together.
+  const cleanedSegments: ResolvedSegment[] = [];
+  const diff: string[] = [];
+  for (const s of dedupedSegments) {
+    if (s._handlerRan === undefined) {
+      cleanedSegments.push(s);
+    } else {
+      const { _handlerRan: _drop, ...rest } = s;
+      cleanedSegments.push(rest as ResolvedSegment);
+    }
+    diff.push(s.id);
+  }
 
   return {
     segments: cleanedSegments,
     matched: matchedIds,
-    diff: cleanedSegments.map((s) => s.id),
+    diff,
     resolvedIds,
     params: ctx.matched.params,
     routeName: ctx.routeKey,

package/src/router/middleware.ts

@@ -186,7 +186,15 @@ export function createMiddlewareContext<TEnv>(
     search?: Record<string, unknown>,
   ) => string,
 ): MiddlewareContext<TEnv> {
-  const url = stripInternalParams(new URL(request.url));
+  // Reuse the request context's clean URL when available. Each middleware still
+  // gets its OWN URL clone (a middleware may mutate ctx.url / ctx.searchParams),
+  // but cloning the already-clean URL is cheaper than re-parsing + re-stripping
+  // request.url per middleware. Fall back to parsing when no ALS context.
+  const reqCtx = _getRequestContext();
+  const ctxUrl = reqCtx?.url;
+  const url = ctxUrl
+    ? new URL(ctxUrl)
+    : stripInternalParams(new URL(request.url));
 
   // Track the initial response to detect pre/post-next() phase.
   // Before next(): responseHolder.response === initialResponse (the stub).
@@ -217,12 +225,11 @@ export function createMiddlewareContext<TEnv>(
     return responseHolder.response;
   };
 
-  // Capture reqCtx once: the request-scoped platform fields
+  // reqCtx captured once above: the request-scoped platform fields
   // (originalUrl, executionContext, waitUntil) are immutable per request,
   // so snapshotting beats re-reading ALS on every access. The lazy getters
   // below (routeName, theme, setTheme) stay lazy because those can change
   // during `await next()`.
-  const reqCtx = _getRequestContext();
   return {
     request,
     url,

package/src/router/request-classification.ts

@@ -150,6 +150,23 @@ export async function classifyRequest<TEnv = any>(
   const pathname = url.pathname;
   const isAction =
     request.headers.has("rsc-action") || url.searchParams.has("_rsc_action");
+  const isLoaderFetch = url.searchParams.has("_rsc_loader");
+  const isPartialReq = url.searchParams.has("_rsc_partial");
+  const contentType = request.headers.get("content-type") || "";
+  const isFormSubmission =
+    contentType.includes("multipart/form-data") ||
+    contentType.includes("application/x-www-form-urlencoded");
+  const isPeRender = request.method === "POST" && !isAction && isFormSubmission;
+
+  // A plain document request (full-render mode) is the only mode that renders
+  // through match() with isSSR:true; every other mode (action, loader, PE,
+  // partial) renders — if at all — through the non-SSR matchPartial() path.
+  // Resolve the manifest under the flag the eventual render will use so
+  // createMatchContextForFull can reuse this snapshot instead of re-resolving.
+  // Response routes ignore isSSR entirely (they short-circuit before match),
+  // so the flag is moot for them. Mode detection below reuses these booleans.
+  const willFullRender =
+    !isAction && !isLoaderFetch && !isPartialReq && !isPeRender;
 
   const clientVersion = url.searchParams.get("_rsc_v");
   if (
@@ -191,6 +208,7 @@ export async function classifyRequest<TEnv = any>(
   const result = await resolveRoute<TEnv>(pathname, {
     findMatch: deps.findMatch,
     lite: true,
+    isSSR: willFullRender,
   });
 
   if (!result) {
@@ -231,7 +249,6 @@ export async function classifyRequest<TEnv = any>(
 
   const actionId =
     request.headers.get("rsc-action") || url.searchParams.get("_rsc_action");
-  const isLoaderFetch = url.searchParams.has("_rsc_loader");
 
   const hasVariants =
     snapshot.matched.negotiateVariants &&
@@ -246,15 +263,11 @@ export async function classifyRequest<TEnv = any>(
     return { mode: "loader", route: snapshot };
   }
 
-  const contentType = request.headers.get("content-type") || "";
-  const isFormSubmission =
-    contentType.includes("multipart/form-data") ||
-    contentType.includes("application/x-www-form-urlencoded");
-  if (request.method === "POST" && !isAction && isFormSubmission) {
+  if (isPeRender) {
     return { mode: "pe-render", route: snapshot };
   }
 
-  if (url.searchParams.has("_rsc_partial")) {
+  if (isPartialReq) {
     return { mode: "partial-render", route: snapshot, negotiated };
   }
 

package/src/router/route-snapshot.ts

@@ -48,6 +48,15 @@ export interface RouteSnapshot<TEnv = any> {
   isPassthrough: boolean;
   /** Response type for non-RSC routes (e.g. "application/json") */
   responseType?: string;
+  /**
+   * The isSSR flag the manifest was resolved with. Recorded so consumers can
+   * decide whether the snapshot is reusable: a snapshot resolved with isSSR
+   * differs (loading({ ssr: false }) entries) and is cached under a different
+   * manifest partition, so the full (document) path only reuses an isSSR:true
+   * snapshot and the partial path only reuses a non-isSSR one. Undefined on
+   * inline snapshots (redirect / not-found) that are never reused.
+   */
+  isSSR?: boolean;
 }
 
 export type ResolveRouteResult<TEnv = any> =
@@ -177,6 +186,7 @@ export async function resolveRoute<TEnv = any>(
       cacheScope,
       isPassthrough,
       responseType,
+      isSSR,
     },
   };
 }

package/src/router/segment-resolution/fresh.ts

@@ -19,7 +19,10 @@ import type {
 } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { resolveLoaderData } from "./loader-cache.js";
-import { isShellCaptureActive } from "./loader-mask.js";
+import {
+  isShellCaptureActive,
+  entryLoadingMasksLoaders,
+} from "./loader-mask.js";
 import {
   handleHandlerResult,
   tryStaticHandler,
@@ -62,7 +65,7 @@ export async function resolveLoaders<TEnv>(
   const loadingDisabled = hasLoading && entry.loading === false;
 
   // Emit the streaming (non-awaiting) loader shape when loading is enabled OR
-  // during a PPR shell capture. In capture, loaders are masked with
+  // during a PPR shell capture. In capture, LIVE-lane loaders are masked with
   // never-resolving promises (loader-mask.ts); the loading-disabled branch below
   // AWAITS the loader promises, which would hang the capture render's match()
   // forever on those masked promises. Forcing the streaming shape lets match()
@@ -71,6 +74,14 @@ export async function resolveLoaders<TEnv>(
   // loading-disabled entries consult it), so normal requests are unchanged.
   const emitStreaming = !loadingDisabled || isShellCaptureActive();
 
+  // PPR lane decision for this entry's loaders (loader-container-bake): an
+  // entry WITHOUT renderable loading() puts its loaders on the BAKE lane —
+  // executed at capture (container bakes, nested pending promises hole at the
+  // consumer's Suspense) and overlay-pinned from the shell snapshot on a HIT.
+  // Renderable loading() keeps the LIVE lane (masked at capture, always
+  // fresh). Computed per entry; resolveLoaderData applies the policy.
+  const bakeLane = !entryLoadingMasksLoaders(entry.loading);
+
   // Error context for wrapLoaderPromise: without it, a throwing DSL loader never
   // fires createRouter({ onError }) (phase "loader") nor emits the loader.error
   // telemetry event — wrapLoaderPromise only builds the onError/telemetry path
@@ -93,7 +104,12 @@ export async function resolveLoaders<TEnv>(
         loaderId: loader.$$id,
         loaderData: deps.wrapLoaderPromise(
           runInsideLoaderScope(() =>
-            resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+            resolveLoaderData(
+              loaderEntry,
+              ctx,
+              ctx.pathname,
+              bakeLane ? segmentId : null,
+            ),
           ),
           entry,
           segmentId,
@@ -122,7 +138,12 @@ export async function resolveLoaders<TEnv>(
     const segmentId = `${shortCode}D${i}.${loader.$$id}`;
     const wrapped = deps.wrapLoaderPromise(
       runInsideLoaderScope(() =>
-        resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+        resolveLoaderData(
+          loaderEntry,
+          ctx,
+          ctx.pathname,
+          bakeLane ? segmentId : null,
+        ),
       ),
       entry,
       segmentId,

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

@@ -23,6 +23,7 @@ import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import {
   getRequestContext,
+  _getRequestContext,
   runWithRequestContext,
 } from "../../server/request-context.js";
 import { sortedRouteParams } from "../../cache/cache-key-utils.js";
@@ -35,6 +36,7 @@ import {
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
+import { overlayLoaderContainer } from "./loader-snapshot.js";
 import { recordRequestTags } from "../../cache/cache-tag.js";
 import {
   isShellCaptureActive,
@@ -130,17 +132,64 @@ export function resolveLoaderData<TEnv>(
   loaderEntry: LoaderEntry,
   ctx: HandlerContext<any, TEnv>,
   pathname: string,
+  bakeSegmentKey?: string | null,
 ): Promise<any> {
-  // PPR shell capture: never execute the loader. Its slot gets a never-resolving
-  // promise so the Suspense subtree postpones (a hole). Gate here — the single
-  // funnel every loader segment path routes through (fresh resolveLoaders,
-  // cache-hit resolveLoadersOnly, revalidation resolveLoadersOnlyWithRevalidation)
-  // — so no loader fn runs and no loader-cache getItem/setItem round-trip happens
-  // during capture. See loader-mask.ts and docs/design/ppr-shell-resume.md.
-  if (isShellCaptureActive()) {
-    return createMaskedLoaderPromise();
+  // One ALS read serves the capture check, the record registration, and the
+  // seed lookup — this runs for every loader on every request.
+  const reqCtx = _getRequestContext();
+  // PPR shell capture policy — gated here, the single funnel every loader
+  // segment path routes through (fresh resolveLoaders, cache-hit
+  // resolveLoadersOnly, revalidation resolveLoadersOnlyWithRevalidation).
+  //
+  // Two lanes (docs/design/loader-container-bake.md):
+  // - LIVE lane (entry has renderable loading(); no `bakeSegmentKey`): never
+  //   execute during capture. The slot gets a never-resolving promise so the
+  //   LoaderBoundary postpones (a hole). See loader-mask.ts.
+  // - BAKE lane (no renderable loading(); callers pass `bakeSegmentKey`):
+  //   execute during capture exactly like axis 1 — the settled container bakes
+  //   into the prelude, nested pending promises postpone at the consumer's own
+  //   Suspense. The container promise is registered on the derived context so
+  //   captureAndStoreShell pins it into the snapshot's loader family; on a
+  //   shell HIT the recorded container is overlaid onto the fresh run so the
+  //   payload matches the frozen prelude byte-for-byte.
+  if (isShellCaptureActive(reqCtx)) {
+    if (!bakeSegmentKey) {
+      return createMaskedLoaderPromise();
+    }
+    const containerPromise = executeLoaderData(loaderEntry, ctx, pathname);
+    // Pre-attach a no-op catch: a bake-lane rejection during capture must
+    // surface through the drain's refusal (and the wrapper's error boundary),
+    // never as an unhandled rejection that can kill the worker before the
+    // drain probes this record.
+    containerPromise.catch(() => {});
+    reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, containerPromise);
+    return containerPromise;
   }
 
+  if (bakeSegmentKey) {
+    const seed = reqCtx?._shellLoaderSeed;
+    if (seed && seed.has(bakeSegmentKey)) {
+      const recorded = seed.get(bakeSegmentKey);
+      // HIT tail: run fresh (only the loader body can mint the live nested
+      // promises), then pin the recorded paths over it. A fresh REJECTION here
+      // skips the overlay and flows to the per-loader error boundary — the
+      // payload then diverges from the prelude (same residual class as uncached
+      // nondeterminism in shell material).
+      return executeLoaderData(loaderEntry, ctx, pathname).then(
+        (fresh: unknown) => overlayLoaderContainer(fresh, recorded),
+      );
+    }
+  }
+
+  return executeLoaderData(loaderEntry, ctx, pathname);
+}
+
+/** The pre-policy loader execution: cache read-through or plain ctx.use. */
+function executeLoaderData<TEnv>(
+  loaderEntry: LoaderEntry,
+  ctx: HandlerContext<any, TEnv>,
+  pathname: string,
+): Promise<any> {
   const cacheConfig = loaderEntry.cache;
 
   // No cache config or disabled — run fresh (zero overhead path)

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

@@ -18,7 +18,10 @@
  * `resolveLoaderData`, fresh.ts `resolveLoaders`).
  */
 
-import { _getRequestContext } from "../../server/request-context.js";
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../../server/request-context.js";
 
 /**
  * True when the current render is the active PPR shell capture and route loaders
@@ -27,8 +30,10 @@ import { _getRequestContext } from "../../server/request-context.js";
  * runWithRequestContext), so it is accurate at the loader resolution sites, which
  * run synchronously inside the pipeline's context frame.
  */
-export function isShellCaptureActive(): boolean {
-  return _getRequestContext()?._shellCaptureRun === true;
+export function isShellCaptureActive(
+  reqCtx: RequestContext<any> | undefined = _getRequestContext(),
+): boolean {
+  return reqCtx?._shellCaptureRun === true;
 }
 
 /**
@@ -42,3 +47,21 @@ export function isShellCaptureActive(): boolean {
 export function createMaskedLoaderPromise<T = unknown>(): Promise<T> {
   return new Promise<T>(() => {});
 }
+
+/**
+ * Lane decision for an entry's loaders under PPR (the loading() value decides;
+ * docs/design/loader-container-bake.md):
+ *
+ * - RENDERABLE loading() (the LoaderBoundary Suspense fallback) — the LIVE
+ *   lane: masked at capture, guaranteed fresh on every serve. Returns true.
+ * - No loading() (absent, or explicitly `false`, incl. `loading(x, { ssr:
+ *   false })` under the SSR manifest) — the BAKE lane: the loader executes
+ *   during capture, its settled container bakes, nested pending promises hole
+ *   at the consumer's own Suspense. Returns false.
+ *
+ * Mirrors segment-system's isRenderableLoading so the mask decision and the
+ * tree's boundary placement can never disagree.
+ */
+export function entryLoadingMasksLoaders(loading: unknown): boolean {
+  return loading !== undefined && loading !== null && loading !== false;
+}

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

@@ -0,0 +1,170 @@
+/**
+ * Loader-family capture snapshot: elide + overlay for bake-lane loader
+ * containers (docs/design/loader-container-bake.md).
+ *
+ * A loader on an entry with NO renderable loading() executes during shell
+ * capture; its settled container bakes into the prelude while every promise
+ * still pending at the quiet window postpones as a hole. To keep a HIT's fresh
+ * payload byte-identical to that frozen prelude, the capture pins the container
+ * in the shell snapshot:
+ *
+ *   - elide:   deep-walk the settled container; a SETTLED nested promise baked
+ *              its value (physics: it won the quiet window), so it is pinned as
+ *              that value; a PENDING nested promise is a hole, replaced by
+ *              {@link LOADER_HOLE_MARKER}. The result is promise-free and
+ *              Flight-serializable.
+ *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
+ *              the live nested promises), then the recorded container is laid
+ *              over it: recorded paths win (they are what the prelude froze),
+ *              marker paths take the fresh run's value (the live hole), and
+ *              fresh-only paths pass through (they cannot contradict prelude
+ *              bytes that never rendered them).
+ */
+
+import { isThenable } from "../../handles/is-thenable.js";
+
+/**
+ * Marker object standing in for a pending nested promise in a recorded loader
+ * container. Shape-checked (not identity-checked) because the record round-trips
+ * through Flight serialization and a JSON-embedding store envelope.
+ */
+export const LOADER_HOLE_KEY = "$rangoLoaderHole" as const;
+
+export interface LoaderHoleMarker {
+  [LOADER_HOLE_KEY]: 1;
+}
+
+export function isLoaderHoleMarker(value: unknown): value is LoaderHoleMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[LOADER_HOLE_KEY] === 1
+  );
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Probe whether a promise is already settled without waiting for it: races it
+ * against an immediately-resolved sentinel across two microtask hops (then
+ * chaining means a resolved inner value needs one extra hop to surface).
+ * Returns the settled state, or "pending" if it has not settled by then.
+ */
+async function probeSettled(
+  p: PromiseLike<unknown>,
+): Promise<
+  | { state: "fulfilled"; value: unknown }
+  | { state: "rejected" }
+  | { state: "pending" }
+> {
+  const PENDING = Symbol("pending");
+  // Two sentinel hops: Promise.resolve(p) adoption costs a microtask, so a
+  // single-hop sentinel would misreport an already-fulfilled promise as pending.
+  const sentinel = Promise.resolve()
+    .then(() => undefined)
+    .then(() => PENDING as unknown);
+  try {
+    const raced = await Promise.race([Promise.resolve(p), sentinel]);
+    if (raced === PENDING) return { state: "pending" };
+    return { state: "fulfilled", value: raced };
+  } catch {
+    return { state: "rejected" };
+  }
+}
+
+export type ElideResult =
+  | { state: "ok"; value: unknown }
+  | { state: "rejected" };
+
+/**
+ * Deep-elide a settled bake-lane container for recording. Settled nested
+ * promises are inlined (they baked); pending ones become hole markers; a
+ * REJECTED nested promise poisons the record (error UI must never bake into a
+ * shared shell) — the caller refuses the capture. Only plain objects/arrays are
+ * traversed; anything else (Date, Map, class instance) is a pinned leaf.
+ * Cycles are cut as pinned references (best effort — Flight rejects true
+ * cycles later regardless).
+ */
+export async function elideLoaderContainer(
+  value: unknown,
+  seen: Set<object> = new Set(),
+): Promise<ElideResult> {
+  if (isThenable(value)) {
+    const probed = await probeSettled(value);
+    if (probed.state === "pending") {
+      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 } };
+    }
+    if (probed.state === "rejected") return { state: "rejected" };
+    return elideLoaderContainer(probed.value, seen);
+  }
+
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return { state: "ok", value };
+    seen.add(value);
+    const out: unknown[] = new Array(value.length);
+    for (let i = 0; i < value.length; i++) {
+      const r = await elideLoaderContainer(value[i], seen);
+      if (r.state === "rejected") return r;
+      out[i] = r.value;
+    }
+    return { state: "ok", value: out };
+  }
+
+  if (isPlainObject(value)) {
+    if (seen.has(value)) return { state: "ok", value };
+    seen.add(value);
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value)) {
+      const r = await elideLoaderContainer(value[key], seen);
+      if (r.state === "rejected") return r;
+      out[key] = r.value;
+    }
+    return { state: "ok", value: out };
+  }
+
+  return { state: "ok", value };
+}
+
+/**
+ * Overlay a recorded (elided) container onto the fresh run's container for a
+ * shell HIT. Recorded wins per path; hole markers take the fresh value (the
+ * live nested promise); fresh-only object keys pass through. Where the shapes
+ * disagree structurally, recorded wins wholesale — it is what the prelude
+ * froze, and parity beats freshness inside the shell.
+ */
+export function overlayLoaderContainer(
+  fresh: unknown,
+  recorded: unknown,
+): unknown {
+  if (isLoaderHoleMarker(recorded)) return fresh;
+
+  if (Array.isArray(recorded)) {
+    const freshArr = Array.isArray(fresh) ? fresh : [];
+    return recorded.map((item, i) => overlayLoaderContainer(freshArr[i], item));
+  }
+
+  if (isPlainObject(recorded)) {
+    if (!isPlainObject(fresh)) {
+      // Shape drift: still honor markers (holes fall back to undefined).
+      const out: Record<string, unknown> = {};
+      for (const key of Object.keys(recorded)) {
+        out[key] = overlayLoaderContainer(undefined, recorded[key]);
+      }
+      return out;
+    }
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(recorded)) {
+      out[key] = overlayLoaderContainer(fresh[key], recorded[key]);
+    }
+    for (const key of Object.keys(fresh)) {
+      if (!(key in out)) out[key] = fresh[key];
+    }
+    return out;
+  }
+
+  return recorded;
+}

package/src/rsc/nonce.ts

@@ -8,11 +8,20 @@ import { createVar } from "../context-var.js";
 /**
  * Typed ContextVar token for CSP nonce.
  *
- * Use this to access the nonce in middleware or handlers:
+ * Use this to READ the nonce in middleware or handlers:
  * ```ts
  * import { nonce } from "@rangojs/router";
  * const value = ctx.get(nonce); // string | undefined
  * ```
+ *
+ * Supply the nonce via the `createRouter({ nonce })` provider, not by writing
+ * this token yourself. The provider value is threaded into the router's SSR
+ * machinery (NonceContext/useNonce, Scripts/MetaTags attributes, the inlined
+ * Flight payload scripts) AND sets this token. A direct `ctx.set(nonce, value)`
+ * in middleware runs AFTER the SSR nonce is resolved: the value is readable via
+ * `ctx.get(nonce)` and gates PPR shell capture (a per-request nonce must never
+ * bake into a shared shell), but the router will not apply it to its own
+ * scripts — useNonce() stays undefined for that request.
  */
 export const nonce: ContextVar<string> = createVar<string>();