@rangojs/router 0.8.0 → 0.10.0

package/src/client-urls/types.ts

@@ -87,12 +87,12 @@ export interface ClientUrlLoaderRecord {
   /** Client-run per-loader revalidation predicates; empty = locked defaults. */
   readonly revalidate: readonly ClientRevalidateFn[];
   /**
-   * loader(Def, { stream: "navigation" }): document renders await this loader
-   * before first flush (see {@link LoaderOptions}). Projected into the server
-   * tree, where the per-isSSR entry stamping applies — client navigations
-   * stream regardless.
+   * loader(Def, { ssr: false }): document renders await this loader before
+   * first flush (see {@link LoaderOptions}). Projected into the server tree,
+   * where the per-isSSR entry stamping applies — client navigations stream
+   * regardless.
    */
-  readonly stream?: "navigation";
+  readonly ssr?: false;
 }
 
 /**
@@ -141,13 +141,14 @@ export interface ClientUrlHelpers {
    * revalidate() only — a CLIENT-RUN per-loader predicate; its decision (not
    * the function) is sent with the revalidation request.
    *
-   * Pass `{ stream: "navigation" }` to await this loader before first flush
-   * on DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders
-   * whose data, handle pushes, or thrown notFound()/redirect() must be in the
-   * SSR'd HTML. Per-loader: a dynamic sibling keeps streaming. Under a
-   * `ppr` group route the flag BAKES: the loader executes at shell capture
-   * and its settled return freezes into the shell (nested promises stay
-   * live holes).
+   * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
+   * false }) — to await this loader before first flush on DOCUMENT requests
+   * (see {@link LoaderOptions}): the opt-in for loaders whose data, handle
+   * pushes, or thrown notFound()/redirect() must be in the SSR'd HTML.
+   * Per-loader: a streaming sibling keeps streaming. Under a `ppr` group
+   * route the flag BAKES: the loader executes at shell capture and its
+   * settled return freezes into the shell (nested promises stay live
+   * holes).
    */
   readonly loader: <TData>(
     definition: LoaderDefinition<TData>,

package/src/client.tsx

@@ -49,6 +49,8 @@ function renderSlotContent(segment: ResolvedSegment | null): ReactNode {
     <LoaderBoundary
       loaderDataPromise={segment.loaderDataPromise!}
       loaderIds={segment.loaderIds!}
+      loaderStreams={segment.loaderStreams}
+      awaitedLoaderIds={segment.awaitedLoaderIds}
       fallback={segment.loading}
       outletKey={segment.id + "-loader"}
       outletContent={null}

package/src/outlet-context.ts

@@ -18,6 +18,15 @@ export interface OutletContextValue {
    * the resolved `loaderData` record.
    */
   loaderStreams?: Record<string, unknown>;
+  /**
+   * Loader $$ids on this segment that the render awaited before first flush
+   * (loader(Def, { ssr: false })). Dev-diagnostic input only: useLoader uses
+   * it to warn when a read still suspends during SSR on a render that awaited
+   * flagged loaders (ssr-suspension-warning.ts). Present only on streaming
+   * lanes with flagged loaders (document and shell-capture renders); absent
+   * on forceAwait/action lanes.
+   */
+  awaitedLoaderIds?: readonly string[];
   parent?: OutletContextValue | null;
   /** Loading component for Suspense fallback (from segment's loading() definition) */
   loading?: ReactNode;

package/src/outlet-provider.tsx

@@ -13,6 +13,7 @@ export function OutletProvider({
   segment,
   loaderData,
   loaderStreams,
+  awaitedLoaderIds,
   pending = false,
   children,
 }: {
@@ -21,6 +22,7 @@ export function OutletProvider({
   segment?: ResolvedSegment;
   loaderData?: Record<string, any>;
   loaderStreams?: Record<string, unknown>;
+  awaitedLoaderIds?: readonly string[];
   pending?: boolean;
   children: ReactNode;
 }): ReactNode {
@@ -34,6 +36,7 @@ export function OutletProvider({
       segment,
       loaderData,
       loaderStreams,
+      awaitedLoaderIds,
       pending,
       parent: parentContext,
       loading: segment?.loading,
@@ -44,6 +47,7 @@ export function OutletProvider({
       segment,
       loaderData,
       loaderStreams,
+      awaitedLoaderIds,
       pending,
       parentContext,
     ],

package/src/route-content-wrapper.tsx

@@ -129,6 +129,9 @@ export interface LoaderBoundaryProps {
    * the children; useLoader suspends per loader at the read site.
    */
   loaderStreams?: Record<string, unknown>;
+  /** Dev-diagnostic input for the SSR suspension warning — see
+   *  OutletContextValue.awaitedLoaderIds. Rides the streams lane only. */
+  awaitedLoaderIds?: readonly string[];
   fallback?: ReactNode;
   outletKey: string;
   outletContent: ReactNode;
@@ -141,6 +144,7 @@ export function LoaderBoundary({
   loaderDataPromise,
   loaderIds,
   loaderStreams,
+  awaitedLoaderIds,
   fallback,
   outletKey,
   outletContent,
@@ -154,6 +158,7 @@ export function LoaderBoundary({
         loaderDataPromise={loaderDataPromise}
         loaderIds={loaderIds}
         loaderStreams={loaderStreams}
+        awaitedLoaderIds={awaitedLoaderIds}
         outletKey={outletKey}
         outletContent={outletContent}
         segment={segment}
@@ -187,6 +192,7 @@ function LoaderResolver({
   loaderDataPromise,
   loaderIds,
   loaderStreams,
+  awaitedLoaderIds,
   outletKey,
   outletContent,
   segment,
@@ -201,6 +207,7 @@ function LoaderResolver({
         segment={segment}
         parallel={parallel}
         loaderStreams={loaderStreams}
+        awaitedLoaderIds={awaitedLoaderIds}
       >
         {children}
       </OutletProvider>

package/src/route-definition/dsl-helpers.ts

@@ -807,8 +807,12 @@ const loader: RouteHelpers<any, any>["loader"] = (
     "loader() received two use() callbacks. Pass loader(Def, options, use) or loader(Def, use).",
   );
   invariant(
-    optionsGiven?.stream === undefined || optionsGiven.stream === "navigation",
-    `loader() stream must be "navigation" (got ${JSON.stringify(optionsGiven?.stream)}). Omit it to stream on every render.`,
+    (optionsGiven as { stream?: unknown } | undefined)?.stream === undefined,
+    "loader() stream was replaced: use loader(Def, { ssr: false }) — the same knob as loading(fallback, { ssr: false }) — to await the loader before first flush on document requests.",
+  );
+  invariant(
+    optionsGiven?.ssr === undefined || typeof optionsGiven.ssr === "boolean",
+    `loader() ssr must be a boolean (got ${JSON.stringify(optionsGiven?.ssr)}). Omit it (or pass true) to stream on every render.`,
   );
 
   const name = `${ctx.namespace}.$${store.getNextIndex("loader")}`;
@@ -820,7 +824,7 @@ const loader: RouteHelpers<any, any>["loader"] = (
   const loaderEntry: LoaderEntry = {
     loader: loaderDef,
     revalidate: [] as ShouldRevalidateFn<any, any>[],
-    ...(optionsGiven?.stream === "navigation" && ctx.isSSR
+    ...(optionsGiven?.ssr === false && ctx.isSSR
       ? { awaitBeforeFlush: true as const }
       : {}),
   };

package/src/route-definition/helpers-types.ts

@@ -310,13 +310,14 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   return <div>{data.name}</div>;
    * }
    * ```
-   * Pass `{ stream: "navigation" }` to await this loader before first flush on
-   * DOCUMENT requests (see {@link LoaderOptions}) — the opt-in for loaders whose
-   * data, handle pushes, or thrown notFound()/redirect() must be in the SSR'd
-   * HTML. Per-loader: a dynamic sibling in the same segment keeps streaming.
+   * Pass `{ ssr: false }` — the same knob as loading(fallback, { ssr:
+   * false }) — to await this loader before first flush on DOCUMENT requests
+   * (see {@link LoaderOptions}): the opt-in for loaders whose data, handle
+   * pushes, or thrown notFound()/redirect() must be in the SSR'd HTML.
+   * Per-loader: a streaming sibling in the same segment keeps streaming.
    *
    * ```typescript
-   * loader(ProductLoader, { stream: "navigation" }, () => [cache()]),
+   * loader(ProductLoader, { ssr: false }, () => [cache()]),
    * loader(RecommendationsLoader),  // still streams behind loading()
    * ```
    *

package/src/router/loader-resolution.ts

@@ -572,7 +572,7 @@ function createLoaderExecutor<TEnv>(
         }
 
         // awaitBeforeFlush cycle: segment resolution awaits this loader
-        // (loader(Def, { stream: "navigation" })), the barrier awaits segment
+        // (loader(Def, { ssr: false })), the barrier awaits segment
         // resolution, and rendered() awaits the barrier — waiting here can
         // never complete. Fail fast with the cause instead of hanging the
         // document render. Only document renders populate the set (the flag is
@@ -581,10 +581,10 @@ function createLoaderExecutor<TEnv>(
         if (reqCtx._awaitBeforeFlushLoaderIds?.has(currentLoaderId)) {
           throw new Error(
             `Deadlock: loader "${currentLoaderId}" is registered with ` +
-              `stream: "navigation", so the document render awaits it before ` +
+              `ssr: false, so the document render awaits it before ` +
               `the render barrier resolves — ctx.rendered() (and the ` +
               `ctx.get(handle) read it gates) can never settle here. Drop ` +
-              `stream: "navigation" on this loader or move the handle read to ` +
+              `ssr: false on this loader or move the handle read to ` +
               `a component.`,
           );
         }

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

@@ -11,6 +11,7 @@ import {
   getParallelEntries,
   getParallelSlotEntries,
   type EntryData,
+  type LoaderEntry,
 } from "../../server/context";
 import type {
   HandlerContext,
@@ -45,6 +46,37 @@ import {
   latchPprHeaderScopeForEntries,
 } from "../../server/context.js";
 
+/**
+ * Register flagged loader $$ids on the request context and return their
+ * indices. Must run BEFORE kickoff: rendered() checks the set to fail
+ * fast on the barrier cycle (resolution awaits the loader, the barrier
+ * awaits resolution).
+ */
+function registerAwaitBeforeFlushIds(loaderEntries: LoaderEntry[]): number[] {
+  const awaitedIndices: number[] = [];
+  for (let i = 0; i < loaderEntries.length; i++) {
+    if (loaderEntries[i]!.awaitBeforeFlush) awaitedIndices.push(i);
+  }
+  if (awaitedIndices.length > 0) {
+    const reqCtx = _getRequestContext();
+    if (reqCtx) {
+      reqCtx._awaitBeforeFlushLoaderIds ??= new Set();
+      for (const i of awaitedIndices) {
+        reqCtx._awaitBeforeFlushLoaderIds.add(loaderEntries[i]!.loader.$$id);
+      }
+    }
+  }
+  return awaitedIndices;
+}
+
+function stampAwaitBeforeFlush(
+  loaderEntry: LoaderEntry,
+): { awaitBeforeFlush: true } | Record<string, never> {
+  return loaderEntry.awaitBeforeFlush === true
+    ? { awaitBeforeFlush: true as const }
+    : {};
+}
+
 // ---------------------------------------------------------------------------
 // Fresh path (full match, no revalidation)
 // ---------------------------------------------------------------------------
@@ -104,7 +136,7 @@ export async function resolveLoaders<TEnv>(
   const errorContext = buildLoaderErrorContext(ctx);
 
   if (emitStreaming) {
-    // awaitBeforeFlush (loader(Def, { stream: "navigation" })): document
+    // awaitBeforeFlush (loader(Def, { ssr: false })): document
     // renders await these loaders before returning, so their data is settled,
     // their handle pushes beat the barrier snapshot, and a thrown notFound()'s
     // status write deterministically precedes Response construction. The ids
@@ -112,23 +144,12 @@ export async function resolveLoaders<TEnv>(
     // the set to fail fast on the barrier cycle (segment resolution awaits the
     // loader, the barrier awaits segment resolution, rendered() awaits the
     // barrier), and the loader body can call rendered() before the await below
-    // is reached. Skipped during shell capture: LIVE-lane loaders are masked
-    // with never-resolving promises there (loader-mask.ts) and would hang.
-    const awaitedIndices: number[] = [];
-    if (!isShellCaptureActive()) {
-      for (let i = 0; i < loaderEntries.length; i++) {
-        if (loaderEntries[i]!.awaitBeforeFlush) awaitedIndices.push(i);
-      }
-    }
-    if (awaitedIndices.length > 0) {
-      const reqCtx = _getRequestContext();
-      if (reqCtx) {
-        reqCtx._awaitBeforeFlushLoaderIds ??= new Set();
-        for (const i of awaitedIndices) {
-          reqCtx._awaitBeforeFlushLoaderIds.add(loaderEntries[i]!.loader.$$id);
-        }
-      }
-    }
+    // is reached.
+    //
+    // Shell-capture renders await too: flagged loaders BAKE at capture
+    // (loader-mask masks only LIVE-lane loaders). Capture must await them so
+    // bake-lane handle pushes land in the prelude.
+    const awaitedIndices = registerAwaitBeforeFlushIds(loaderEntries);
 
     // Streaming loaders: promises kick off now, settle during RSC serialization.
     const segments = loaderEntries.map((loaderEntry, i) => {
@@ -142,13 +163,17 @@ export async function resolveLoaders<TEnv>(
         component: null,
         params: ctx.params,
         loaderId: loader.$$id,
+        // Stamped on document AND capture renders: segment-system's
+        // value-delivery await and the dev SSR-suspension diagnostic both
+        // key off it.
+        ...stampAwaitBeforeFlush(loaderEntry),
         loaderData: deps.wrapLoaderPromise(
           runInsideLoaderScope(() =>
             resolveLoaderData(
               loaderEntry,
               ctx,
               ctx.pathname,
-              // The bake key rides for flagged loaders too: stream:"navigation"
+              // The bake key rides for flagged loaders too: ssr:false
               // bakes at capture regardless of the entry's loading() lane
               // (loader-cache.ts capture branch) and its HIT-tail seed
               // overlay needs the same key.
@@ -188,6 +213,11 @@ export async function resolveLoaders<TEnv>(
   // collapsing the whole entry and discarding successful sibling data, and
   // (2) leave the other in-flight raw promises without a .catch, producing
   // unhandled rejections. Mirrors the loading path and intercept-resolution.
+  //
+  // Flagged loaders still get awaitBeforeFlush stamped: auto-raise and
+  // settled-value delivery key off the field, and this path already paid
+  // the pre-flush await.
+  registerAwaitBeforeFlushIds(loaderEntries);
   const pendingLoaderData = loaderEntries.map((loaderEntry, i) => {
     const { loader } = loaderEntry;
     const segmentId = `${shortCode}D${i}.${loader.$$id}`;
@@ -224,6 +254,7 @@ export async function resolveLoaders<TEnv>(
       component: null,
       params: ctx.params,
       loaderId: loader.$$id,
+      ...stampAwaitBeforeFlush(loaderEntry),
       loaderData: pending.wrapped,
       belongsToRoute,
     };

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

@@ -159,7 +159,7 @@ export function resolveLoaderData<TEnv>(
   if (isShellCaptureActive(reqCtx)) {
     // Capture lane, per LOADER (not per entry):
     //
-    // - `stream: "navigation"` (awaitBeforeFlush) — the BAKE lane. The flag's
+    // - `ssr: false` (awaitBeforeFlush) — the BAKE lane. The flag's
     //   document promise is "this loader's data is in the HTML before first
     //   flush"; under ppr the pre-flush HTML IS the frozen prelude, so the
     //   loader executes at capture and its SETTLED return bakes into the

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

@@ -44,7 +44,7 @@ export { createMaskedLoaderPromise } from "./mask-nested.js";
 /**
  * Entry-level lane input for an entry's loaders under PPR (the loading()
  * value; docs/design/loader-container-bake.md). The CAPTURE decision itself
- * is per LOADER in loader-cache.ts: a `stream: "navigation"`
+ * is per LOADER in loader-cache.ts: an `ssr: false`
  * (awaitBeforeFlush) loader BAKES at capture regardless of this value — the
  * flag's document promise ("data in the HTML before first flush") maps to
  * the frozen prelude — while every other loader is LIVE (masked at capture,

package/src/router.ts

@@ -1167,11 +1167,16 @@ export function createRouter<TEnv = any>(
         | null = null;
 
       return async (request: Request, input: RouterRequestInput<TEnv> = {}) => {
+        const requestedDiscoveryEpoch = request.headers.get(
+          DEV_DISCOVERY_PROBE_HEADER,
+        );
         if (
           devDiscoveryEpoch !== undefined &&
-          request.headers.get(DEV_DISCOVERY_PROBE_HEADER) ===
-            String(devDiscoveryEpoch)
+          requestedDiscoveryEpoch !== null
         ) {
+          // A stale generation must still answer as a probe. Rendering the app
+          // on an epoch mismatch makes the readiness loop overlap full renders
+          // with workerd reloads and can exhaust the dev server heap.
           return new Response(null, {
             headers: {
               [DEV_DISCOVERY_EPOCH_HEADER]: String(devDiscoveryEpoch),

package/src/rsc/handler.ts

@@ -45,7 +45,7 @@ import {
   handleResponseRoute,
   type ResponseRouteMatch,
 } from "./response-route-handler.js";
-import { generateNonce, nonce as nonceToken } from "./nonce.js";
+import { nonce as nonceToken, resolveProviderNonce } from "./nonce.js";
 import { VERSION } from "@rangojs/router:version";
 import type { ErrorPhase } from "../types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
@@ -456,12 +456,12 @@ export function createRSCHandler<
       }
     }
 
-    // Resolve nonce if provider is set
+    // Resolve nonce if provider is set. false/"" normalize to undefined —
+    // the per-request opt-out (resolveProviderNonce).
     const nonceStart = performance.now();
     let nonce: string | undefined;
     if (nonceProvider) {
-      const result = await nonceProvider(request, env);
-      nonce = result === true ? generateNonce() : result;
+      nonce = resolveProviderNonce(await nonceProvider(request, env));
     }
     const nonceDur = performance.now() - nonceStart;
 

package/src/rsc/nonce.ts

@@ -25,6 +25,22 @@ import { createVar } from "../context-var.js";
  */
 export const nonce: ContextVar<string> = createVar<string>();
 
+/**
+ * Normalize a NonceProvider return value to the nonce the request runs with.
+ * `true` auto-generates; `false` and the empty string are the per-request
+ * opt-out and normalize to undefined — without this, a falsy string would be
+ * threaded as-is into the render: never written to the token (`if (nonce)`)
+ * yet still `!== undefined` for the ppr shell gate (rsc-rendering.ts
+ * activeNonce), pinning a ppr route to axis 1 with no way to opt a request
+ * out while keeping the provider for the rest of the app.
+ */
+export function resolveProviderNonce(
+  result: string | boolean,
+): string | undefined {
+  if (result === true) return generateNonce();
+  return result === false || result === "" ? undefined : result;
+}
+
 /**
  * Generate a cryptographic nonce for CSP.
  * Returns a 16-byte random value encoded as base64.

package/src/rsc/rsc-rendering.ts

@@ -155,6 +155,7 @@ function createShellCaptureDescriptor(
   ctx: HandlerContext<any>,
   key: string,
   searchSeed: string,
+  originSeed: string,
   pprConfig: ResolvedPprConfig,
   store: SegmentCacheStore<any>,
   navigationOnly?: true,
@@ -162,6 +163,11 @@ function createShellCaptureDescriptor(
   return {
     key,
     searchSeed,
+    // Derived from the same request URL as the key (the callers compute
+    // both next to each other, so they cannot drift): seeding the origin
+    // keeps origin-dependent static markup (Link's data-external)
+    // identical across capture, resume, and browser hydration.
+    originSeed,
     buildVersion: ctx.version,
     ttl: pprConfig.ttl,
     swr: pprConfig.swr,
@@ -519,6 +525,7 @@ function* shellServePlan<TEnv>(
     ctx,
     key,
     shellSearchSeed(url, reqCtx._searchParamsFilter),
+    url.origin,
     pprConfig,
     store,
   );
@@ -1004,6 +1011,7 @@ function scheduleNavigationShellCapture<TEnv>(
       partialCaptureKey ??
         buildNavigationShellKey(url, reqCtx._searchParamsFilter),
       shellSearchSeed(url, reqCtx._searchParamsFilter),
+      url.origin,
       pprConfig,
       store,
       true,
@@ -1524,6 +1532,8 @@ function serveShellHit(
         // The shell key's own search — identical to the capture seed for
         // this key, so the resume tree matches the captured tree.
         search: shellSearchSeed(url, reqCtx._searchParamsFilter),
+        // The HIT request's origin — same host as the capture's (key-scoped).
+        origin: url.origin,
       }),
     );
   };

package/src/rsc/shell-capture.ts

@@ -45,7 +45,10 @@ import {
   maskNestedContainerThenables,
   type MaskReport,
 } from "../router/segment-resolution/mask-nested.js";
-import { isInsideLoaderScope } from "../server/context.js";
+import {
+  getCurrentLoaderBodyId,
+  isInsideLoaderScope,
+} from "../server/context.js";
 import { isThenable } from "../handles/is-thenable.js";
 import type {
   ShellCacheEntry,
@@ -917,6 +920,15 @@ export interface ShellCaptureDescriptor {
    * Omitted (build-time bare-pathname captures) = search-less, same as "".
    */
   searchSeed?: string;
+  /**
+   * The scheduling request's origin, seeding the capture render's SSR store
+   * location. Shell keys are host-scoped, so the resume pass's request
+   * agrees modulo protocol drift; the seed keeps origin-dependent static
+   * markup (Link's data-external) identical across capture, resume, and
+   * browser hydration. Omitted (build-time host-agnostic captures) falls
+   * back to the internal host.
+   */
+  originSeed?: string;
   /**
    * The RSC handler's build version (HandlerContext.version), stamped into the
    * stored entry as ShellCacheEntry.buildVersion — the serve-side
@@ -1494,6 +1506,15 @@ export function deriveShellCaptureContext(
   //    applied ONLY at the captureHandles cache-write call site — every other
   //    getDataForSegment consumer (the render-barrier snapshot, prerender)
   //    sees every push.
+  //    EXCEPTION — bake-lane { ssr: false } loaders: they execute at capture
+  //    and never re-run on a HIT, so neither exclusion rationale applies. The
+  //    capture awaits them (fresh.ts), their pushes are in the captured HTML
+  //    (<head> title/meta, useHandle echoes), and the stored snapshot MUST
+  //    carry the same values or HIT hydration mismatches against its own
+  //    prelude (server text present, client handle empty). Only their
+  //    settled, thenable-free pushes qualify — a deferred (thenable) push or
+  //    one with masked nested promises keeps the exclusion so the handle
+  //    encode cannot stall on a never-resolving mask.
   const handleLiveness = {
     holes: false,
     pendingPushes: 0,
@@ -1509,11 +1530,13 @@ export function deriveShellCaptureContext(
     const pushedInLoaderScope = isInsideLoaderScope();
     // Single walk: the mask reports whether it masked any nested thenable
     // (the liveness declaration) while building the capture copy.
+    let maskedNestedThenable = false;
     const maskWithLiveness = (v: unknown): unknown => {
       const report: MaskReport = { thenable: false };
       const masked = maskNestedContainerThenables(v, undefined, report);
-      if (!pushedInLoaderScope && report.thenable) {
-        handleLiveness.holes = true;
+      if (report.thenable) {
+        maskedNestedThenable = true;
+        if (!pushedInLoaderScope) handleLiveness.holes = true;
       }
       return masked;
     };
@@ -1525,11 +1548,30 @@ export function deriveShellCaptureContext(
         value.then(settle, settle);
       }
       masked = value.then(maskWithLiveness);
+      // Deferred (thenable) loader pushes always keep the exclusion — the
+      // bake-lane carve-out below is for settled values only.
+      if (pushedInLoaderScope) {
+        loaderScopedPushValues.add(masked as object);
+      }
     } else {
       masked = maskWithLiveness(value);
-    }
-    if (pushedInLoaderScope && typeof masked === "object" && masked !== null) {
-      loaderScopedPushValues.add(masked);
+      if (
+        pushedInLoaderScope &&
+        typeof masked === "object" &&
+        masked !== null
+      ) {
+        // Bake-lane { ssr: false } loader pushes are shell material (see the
+        // funnel comment above): keep them IN the stored snapshot when
+        // settled and thenable-free; everything else stays excluded.
+        const bodyLoaderId = getCurrentLoaderBodyId();
+        const baked =
+          bodyLoaderId !== undefined &&
+          !maskedNestedThenable &&
+          derivedCtx._awaitBeforeFlushLoaderIds?.has(bodyLoaderId) === true;
+        if (!baked) {
+          loaderScopedPushValues.add(masked);
+        }
+      }
     }
     rawCapturePush(handleName, segmentId, masked);
   };
@@ -1767,6 +1809,7 @@ async function captureAndStoreShell(
           // The shell key's own search seeds the capture render's store —
           // static-part search reads bake what the key names.
           search: capture.searchSeed,
+          origin: capture.originSeed,
         }),
       );
     } catch (error) {

package/src/rsc/ssr-setup.ts

@@ -120,6 +120,10 @@ export function createSsrHtmlStage<TEnv>(
           ...options.render,
           streamMode,
           search: options.url.search,
+          // origin: same out-of-band channel — seeds the SSR store location
+          // so origin-dependent markup (Link's data-external) agrees with the
+          // browser's window.location across hydration.
+          origin: options.url.origin,
         }),
       ...(options.init && { init: options.init }),
     };

package/src/rsc/types.ts

@@ -187,6 +187,12 @@ export interface SSRRenderOptions {
    * search; see ShellCaptureOptions.search in the SSR entry).
    */
   search?: string;
+  /**
+   * The live request's origin (`url.origin`), seeding the SSR store
+   * location so origin-dependent markup (Link's data-external) agrees with
+   * the browser across hydration. Absent on host-agnostic build captures.
+   */
+  origin?: string;
 }
 
 /**
@@ -208,7 +214,12 @@ export interface SSRModule {
    */
   captureShellHTML?: (
     rscStream: ReadableStream<Uint8Array>,
-    options: { quiesce: Promise<void>; maxWaitMs?: number; search?: string },
+    options: {
+      quiesce: Promise<void>;
+      maxWaitMs?: number;
+      search?: string;
+      origin?: string;
+    },
   ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
 
   /**
@@ -221,7 +232,12 @@ export interface SSRModule {
    */
   resumeShellHTML?: (
     rscStream: ReadableStream<Uint8Array>,
-    options: { postponed: string | null; nonce?: string; search?: string },
+    options: {
+      postponed: string | null;
+      nonce?: string;
+      search?: string;
+      origin?: string;
+    },
   ) => Promise<ReadableStream<Uint8Array>>;
 }
 
@@ -260,12 +276,16 @@ export interface HandlerCacheConfig {
 
 /**
  * Nonce provider function type.
- * Can return a nonce string, or true to auto-generate one.
+ * Return a nonce string to use verbatim, `true` to auto-generate one, or
+ * `false` (or an empty string) to serve THIS request without a nonce — the
+ * per-request opt-out for apps that nonce globally but declare `ppr` on some
+ * routes: a shell is shared per host+URL and can never bake a per-request
+ * nonce, so a ppr route only captures when its requests opt out here.
  */
 export type NonceProvider<TEnv = unknown> = (
   request: Request,
   env: TEnv,
-) => string | true | Promise<string | true>;
+) => string | boolean | Promise<string | boolean>;
 
 /**
  * Options for creating an RSC handler