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

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,
@@ -543,22 +550,28 @@ export async function executeMiddleware<TEnv>(
     // when neither surface is active.
     let result: Response | void;
     try {
-      result = await observePhase(PHASES.middleware(metricLabel), () =>
-        entry.handler(ctx, wrappedNext),
-      );
-    } catch (error) {
-      // Thrown Response is short-circuit control flow, not an error.
-      // Fall through to the `if (result instanceof Response)` branch below
-      // so stub headers and request-context cookies merge as they do for
-      // an explicit `return new Response(...)`. Real errors propagate.
-      if (error instanceof Response) {
-        result = error;
-      } else {
-        finishMiddleware();
-        throw error;
-      }
+      result = await observePhase(PHASES.middleware(metricLabel), async () => {
+        try {
+          return await entry.handler(ctx, wrappedNext);
+        } catch (error) {
+          // Thrown Response is short-circuit control flow, not an error —
+          // absorb it INSIDE the span so the tracing runner settles the
+          // rango.middleware span as success, not STATUS_ERROR (every auth
+          // redirect would otherwise inflate trace error rates). Returning it
+          // routes through the `if (result instanceof Response)` branch below,
+          // so stub headers and request-context cookies merge identically to an
+          // explicit `return new Response(...)`. Segment handlers already follow
+          // this convention (segment-resolution/helpers.ts keeps result handling
+          // outside the span). Real errors propagate past the span.
+          if (error instanceof Response) return error;
+          throw error;
+        }
+      });
+    } finally {
+      // Settle the middleware own-time metric once on both the success and
+      // error paths (idempotent guard in finishMiddleware).
+      finishMiddleware();
     }
-    finishMiddleware();
 
     // Record post-next() processing time when middleware did work after
     // the downstream chain resolved (e.g. adding headers, logging).
@@ -718,20 +731,21 @@ export async function executeInterceptMiddleware<TEnv>(
       ordinal,
     );
 
-    let result: Response | void;
-    try {
-      result = await observePhase(PHASES.middleware(label), () =>
-        middleware(ctx, guardedNext),
-      );
-    } catch (error) {
-      // Thrown Response is short-circuit control flow, parity with the
-      // explicit-return path below. Real errors propagate.
-      if (error instanceof Response) {
-        result = error;
-      } else {
-        throw error;
-      }
-    }
+    const result: Response | void = await observePhase(
+      PHASES.middleware(label),
+      async () => {
+        try {
+          return await middleware(ctx, guardedNext);
+        } catch (error) {
+          // Thrown Response is short-circuit control flow, parity with the
+          // explicit-return path below. Absorb it INSIDE the span so the tracing
+          // runner settles rango.middleware as success, not STATUS_ERROR (same
+          // reasoning as executeMiddleware's main chain). Real errors propagate.
+          if (error instanceof Response) return error;
+          throw error;
+        }
+      },
+    );
 
     if (result instanceof Response) {
       earlyResponse = result;

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/router-interfaces.ts

@@ -16,6 +16,7 @@ import type { RangoOptions, RootLayoutProps } from "./router-options.js";
 import type { DefaultVars } from "../types/global-namespace.js";
 import type { ResolvedTimeouts, OnTimeoutCallback } from "./timeout.js";
 import type { ResolvedTracing } from "./tracing.js";
+import type { TelemetrySink } from "./telemetry.js";
 
 /**
  * Options passed to router.fetch(), router.match(), and other request entrypoints.
@@ -350,6 +351,14 @@ export interface RangoInternal<
    */
   readonly tracing?: ResolvedTracing;
 
+  /**
+   * Raw telemetry sink from RangoOptions, exposed so handler-level emitters
+   * (rsc/handler.ts timeout/origin/late-handle) can emit WITHOUT the
+   * RouterContext ALS, which only match()/matchPartial() enter. See
+   * observeEvent's emitter list in router/instrument.ts.
+   */
+  readonly telemetry?: TelemetrySink;
+
   /**
    * Whether ?__debug_manifest is allowed in production.
    * Always enabled in development.

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,251 @@
+/**
+ * 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 wrapped in a SETTLED marker — the wrapper remembers
+ *              "this was a promise" so the overlay can rehydrate the shape; a
+ *              PENDING nested promise is a hole, replaced by
+ *              {@link LOADER_HOLE_KEY}. 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),
+ *              hole-marker paths take the fresh run's value (the live hole),
+ *              SETTLED-marker paths become Promise.resolve(pinned) — consumers
+ *              wrote use(data.x) against a promise-shaped container, and
+ *              handing them the raw value throws React #438 on every HIT (the
+ *              storefront PDP regression) — 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
+  );
+}
+
+/**
+ * Marker wrapping the inlined value of a NESTED promise that settled during
+ * capture. The value baked (physics), but the container key was a promise —
+ * the overlay must hand consumers a Promise.resolve(value), not the raw value,
+ * or an unconditional use(data.x) throws React #438 on every HIT. The ROOT
+ * container is never wrapped: loader-cache overlays against the awaited fresh
+ * container value.
+ */
+export const LOADER_SETTLED_KEY = "$rangoLoaderSettled" as const;
+
+export interface LoaderSettledMarker {
+  [LOADER_SETTLED_KEY]: 1;
+  value: unknown;
+  /**
+   * Present when the pinned subtree contains hole markers. Computed once at
+   * capture (elide already visits every node) so the per-HIT overlay never
+   * rescans the pinned structure to pick its rehydration path.
+   */
+  holes?: 1;
+}
+
+export function isLoaderSettledMarker(
+  value: unknown,
+): value is LoaderSettledMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[LOADER_SETTLED_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; hasHole: boolean }
+  | { state: "rejected" };
+
+/**
+ * Deep-elide a settled bake-lane container for recording. Settled nested
+ * promises pin their value behind a settled marker (they baked, but consumers
+ * hold a promise-shaped key); 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).
+ *
+ * The ROOT container promise-chain unwraps with NO marker: loader-cache
+ * overlays against the AWAITED fresh container, so the recorded root must be
+ * the unwrapped structure. Everything below it goes through elideNested.
+ */
+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 }, hasHole: true };
+    }
+    if (probed.state === "rejected") return { state: "rejected" };
+    return elideLoaderContainer(probed.value, seen);
+  }
+  return elideNested(value, seen);
+}
+
+async function elideNested(
+  value: unknown,
+  seen: Set<object>,
+): Promise<ElideResult> {
+  if (isThenable(value)) {
+    const probed = await probeSettled(value);
+    if (probed.state === "pending") {
+      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
+    }
+    if (probed.state === "rejected") return { state: "rejected" };
+    const inner = await elideNested(probed.value, seen);
+    if (inner.state === "rejected") return inner;
+    const marker: LoaderSettledMarker = inner.hasHole
+      ? { [LOADER_SETTLED_KEY]: 1, value: inner.value, holes: 1 }
+      : { [LOADER_SETTLED_KEY]: 1, value: inner.value };
+    return { state: "ok", value: marker, hasHole: inner.hasHole };
+  }
+
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return { state: "ok", value, hasHole: false };
+    seen.add(value);
+    const out: unknown[] = new Array(value.length);
+    let hasHole = false;
+    for (let i = 0; i < value.length; i++) {
+      const r = await elideNested(value[i], seen);
+      if (r.state === "rejected") return r;
+      out[i] = r.value;
+      hasHole ||= r.hasHole;
+    }
+    return { state: "ok", value: out, hasHole };
+  }
+
+  if (isPlainObject(value)) {
+    if (seen.has(value)) return { state: "ok", value, hasHole: false };
+    seen.add(value);
+    const out: Record<string, unknown> = {};
+    let hasHole = false;
+    for (const key of Object.keys(value)) {
+      const r = await elideNested(value[key], seen);
+      if (r.state === "rejected") return r;
+      out[key] = r.value;
+      hasHole ||= r.hasHole;
+    }
+    return { state: "ok", value: out, hasHole };
+  }
+
+  return { state: "ok", value, hasHole: false };
+}
+
+/**
+ * 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 (isLoaderSettledMarker(recorded)) {
+    const pinned = recorded.value;
+    // Deep holes inside a settled container (capture-computed `holes` bit)
+    // need the fresh promise's resolved value to fill them; a fully-pinned
+    // container resolves immediately (the prelude already shows it — never
+    // gate it on fresh latency). A rejecting fresh run degrades holes to
+    // undefined instead of poisoning the pin.
+    if (recorded.holes === 1) {
+      return Promise.resolve(fresh).then(
+        (freshValue) => overlayLoaderContainer(freshValue, pinned),
+        () => overlayLoaderContainer(undefined, pinned),
+      );
+    }
+    return Promise.resolve(overlayLoaderContainer(undefined, pinned));
+  }
+
+  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;
+}