@rangojs/router 0.25.0 → 0.26.1

package/src/router.ts

@@ -132,6 +132,10 @@ import {
   resolvePrefetchCacheSize,
   resolvePrefetchConcurrency,
 } from "./router/prefetch-limits.js";
+import {
+  droppedByRunnerReload,
+  routerAfterRunnerReload,
+} from "./router/dev-reload-handoff.js";
 
 // Re-export public types and values from extracted modules
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
@@ -170,7 +174,6 @@ export function createRouter<TEnv = any>(
     $$routeNames: staticRouteNames,
     $$sourceFile: injectedSourceFile,
     nonce,
-    version,
     prefetchCacheTTL: prefetchCacheTTLOption,
     prefetchCacheSize: prefetchCacheSizeOption,
     prefetchConcurrency: prefetchConcurrencyOption,
@@ -771,7 +774,7 @@ export function createRouter<TEnv = any>(
   // handler's overlay read makes (resolvePrerenderVersion), so the keys agree.
   const prerenderTrigger = createPrerenderTrigger<TEnv, {}>({
     routerId,
-    resolveVersion: () => resolvePrerenderVersion(routerId, version),
+    resolveVersion: () => resolvePrerenderVersion(routerId),
     isDev: isDevEnvironment,
     isViteDevServer,
     ensureManifest: () => ensureRouterManifest(routerId),
@@ -803,7 +806,7 @@ export function createRouter<TEnv = any>(
         {},
         {
           ...prerenderDeps,
-          versions: resolveRouterVersions(routerId, version),
+          versions: resolveRouterVersions(routerId),
         },
         undefined,
         isPassthrough,
@@ -812,7 +815,7 @@ export function createRouter<TEnv = any>(
         true,
       ),
     // A warm goes through router.fetch's handler: the one createRouter's own
-    // cache, nonce and version configure. An entry that passes them to
+    // cache and nonce configure. An entry that passes them to
     // createRSCHandler itself is not what a warm runs.
     resolveCacheConfig: (env, ctx) =>
       typeof cache === "function" ? cache(env, ctx) : cache,
@@ -1222,9 +1225,6 @@ export function createRouter<TEnv = any>(
     // Expose nonce provider for fetch
     nonce,
 
-    // Expose version for fetch
-    version,
-
     // Expose urlpatterns for runtime manifest generation
     get urlpatterns() {
       return storedUrlPatterns ?? undefined;
@@ -1278,6 +1278,18 @@ export function createRouter<TEnv = any>(
           });
         }
 
+        // Dev: a runner full reload dropped this router's module copy
+        // (router/dev-reload-handoff.ts, #1186).
+        if (process.env.NODE_ENV !== "production" && droppedByRunnerReload()) {
+          const reloaded = await routerAfterRunnerReload(
+            routerId,
+            __sourceFile,
+          );
+          if (reloaded && reloaded !== router) {
+            return reloaded.fetch(request, input);
+          }
+        }
+
         // Trigger lazy import of per-router manifest data before route matching.
         // No-op if data is already loaded or no loader is registered.
         await ensureRouterManifest(routerId);
@@ -1292,7 +1304,6 @@ export function createRouter<TEnv = any>(
             router: router as any,
             cache,
             nonce,
-            version,
           }) as (
             request: Request,
             input: RouterRequestInput<TEnv>,

package/src/rsc/handler.ts

@@ -165,12 +165,8 @@ export function createRSCHandler<
   TRoutes extends Record<string, string> = Record<string, string>,
 >(options: CreateRSCHandlerOptions<TEnv, TRoutes>) {
   const { router, nonce: nonceProvider } = options;
-  // A consumer-set version (this option, else createRouter({ version })) is
-  // used for both; otherwise the router's own pair from the build.
-  const versions = resolveRouterVersions(
-    router.id,
-    options.version ?? router.version,
-  );
+  // The router's own pair from the build.
+  const versions = resolveRouterVersions(router.id);
   // Everything the handler itself versions is tied to the HTML a tab holds:
   // payload metadata (what the browser echoes as `_rsc_v`), the reload check,
   // shell stamping and gating, the rango state value. The data version is only
@@ -548,7 +544,7 @@ export function createRSCHandler<
         resolvedPrerender = {
           config: prerenderConfig,
           routerId: router.id,
-          version: resolvePrerenderVersion(router.id, router.version),
+          version: resolvePrerenderVersion(router.id),
         };
       }
     }

package/src/rsc/rsc-rendering.ts

@@ -56,6 +56,7 @@ import { buildFullPayload, payloadLocation } from "./full-payload.js";
 import {
   capShellWindow,
   lastStoredCaptureSeq,
+  markCaptureBackoff,
   scheduleShellCapture,
   resolveShellCaptureDebugSink,
   takeCaptureDebugEventForTiming,
@@ -1804,13 +1805,14 @@ async function isSettled(value: unknown): Promise<boolean> {
 }
 
 /**
- * Evict a shell whose doc record cannot be replayed. The store has no shell
- * delete, so the entry is overwritten with a tombstone: a navigationOnly
- * entry with no document half and no snapshot, which document serving
- * treats as a MISS (shellServePlan, the build shell included) and partial
- * replay as `no-segment-snapshot`. The recapture overwrites it with a sound
- * entry. Only for a broken entry: a snapshot read that was merely slow
- * (`snapshotFailure: "unavailable"`) leaves the entry alone.
+ * Evict a shell whose doc record cannot be replayed, or one with a loader pin
+ * that failed to decode. The store has no shell delete, so the entry is
+ * overwritten with a tombstone: a navigationOnly entry with no document half
+ * and no snapshot, which document serving treats as a MISS (shellServePlan,
+ * the build shell included) and partial replay as `no-segment-snapshot`. The
+ * recapture overwrites it with a sound entry. Only for a broken entry: a
+ * snapshot read that was merely slow (`snapshotFailure: "unavailable"`)
+ * leaves the entry alone.
  */
 async function degradeUnreplayableShell(
   descriptor: ShellCaptureDescriptor,
@@ -1878,6 +1880,21 @@ function serveShellHit(
   const tailT0 = tailTiming ? performance.now() : 0;
   const scheduleRecapture = (): void =>
     scheduleShellCapture(ctx, request, env, url, reqCtx, ssrModule, descriptor);
+  /** Report a broken entry, then tombstone and recapture it. Never throws. */
+  const retireEntry = async (reason: string): Promise<void> => {
+    reportCacheError(
+      new Error(`shell entry for "${descriptor.key}": ${reason}`),
+      "cache-read",
+      "[ShellServe] retire",
+    );
+    try {
+      await degradeUnreplayableShell(descriptor, entry, scheduleRecapture);
+    } catch (error) {
+      reportCacheError(error, "cache-write", "[ShellServe] retire");
+    }
+  };
+  /** The first loader pin of the entry that failed to decode (dc-t89). */
+  let undecodablePin: string | undefined;
 
   const createTailContext = (): RequestContext<any> => {
     const tailCtx: RequestContext<any> = Object.create(reqCtx);
@@ -2016,7 +2033,11 @@ function serveShellHit(
     const seedStart =
       INTERNAL_RANGO_DEBUG || tailTiming ? performance.now() : 0;
     const loaderSeed =
-      records.length > 0 ? await buildShellLoaderSeed(records) : undefined;
+      records.length > 0
+        ? await buildShellLoaderSeed(records, (key) => {
+            undecodablePin ??= key;
+          })
+        : undefined;
     if (tailTiming) {
       const seededAt = performance.now();
       tailTiming.seedMs = Math.round(seededAt - tailT0);
@@ -2179,10 +2200,8 @@ function serveShellHit(
           // snapshot read was only slow stays, and the next request reads it
           // again.
           if ((await document.snapshotFailure) !== "unavailable") {
-            await degradeUnreplayableShell(
-              descriptor,
-              entry,
-              scheduleRecapture,
+            await retireEntry(
+              "the doc record could not supply the handler layer",
             );
           }
           controller.enqueue(new TextEncoder().encode(shellReloadScript()));
@@ -2207,6 +2226,19 @@ function serveShellHit(
         }
         publishTailTiming(tailTiming, metricsStore, request, url);
         controller.error(error);
+        return;
+      }
+      // A pin that failed to decode left its loader to this request's run:
+      // this response hydrated once over a prelude rendered from the
+      // capture's value (dc-t89). Retire the entry once the response is
+      // closed, and back the key off so a pin that keeps failing costs one
+      // mismatch per window. No reload: that would cost a second page load.
+      if (undecodablePin !== undefined) {
+        const pin = undecodablePin;
+        markCaptureBackoff(descriptor.key);
+        reqCtx.waitUntil(() =>
+          retireEntry(`the loader pin "${pin}" failed to decode`),
+        );
       }
     },
   });

package/src/rsc/shell-capture-constants.ts

@@ -208,13 +208,17 @@ export const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25_000;
  * (ShellCaptureDebugEvent.refusal, `caches.refusal` on a `router.prerender()`
  * result): `identity` (a request-scoped read: cookies(), headers(), the
  * theme, a `{ cache: false }` variable), `dynamic` (`ctx.dynamic()`),
- * `loader` (a `{ ssr: false }` loader rejected, or settled with
- * redirect()/notFound()), `no-record` (no doc record: the route's cache()
- * refused the write, or the handler output failed), `handles` (a pushed
+ * `loader` (a `{ ssr: false }` loader rejected, settled with
+ * redirect()/notFound(), or a promise it pushed rejected),
+ * `no-record` (no doc record: the route's cache() refused the write, or the
+ * handler output failed), `handles` (a pushed
  * handle value did not finish encoding), `size` (over the store's value
- * limit), `record-expired` (the route cache() record the capture wrote ran
- * out first), `invalidated` (a tag of the shell was invalidated after the
- * capture started), `uncacheable` (the store cannot hold the entry).
+ * limit, or `ssr: false` loader pins over `ppr.maxSnapshotBytes`: a
+ * navigation-only entry was stored in place of the document shell),
+ * `record-expired` (the route cache() record
+ * the capture wrote ran out first), `invalidated` (a tag of the shell was
+ * invalidated after the capture started), `uncacheable` (the store cannot
+ * hold the entry).
  */
 export type ShellCaptureRefusal =
   | "identity"

package/src/rsc/shell-capture.ts

@@ -508,6 +508,11 @@ function refuse(
   return "refused";
 }
 
+/** A bake-lane loader's promise push, as a refusal names it. */
+function describeLoaderPromisePush(push: LoaderPromisePush): string {
+  return `the promise the loader "${push.loaderId}" pushed to the handle "${push.handleName}"`;
+}
+
 /** The no-shell cause for handler output that missed the capture deadline. */
 const HANDLER_OUTPUT_TIMEOUT_REASON: string =
   "the handler output (a promise it passes or pushes, or an async server " +
@@ -537,9 +542,8 @@ export const DEFAULT_SHELL_ENTRY_MAX_BYTES: number = 25 * 1024 * 1024;
  * while still fitting any sane pinned-ring payload. Applied ONLY in
  * captureAndStoreShell (the single defaulting site — resolvePprConfig passes
  * the option through undefaulted), so every producer and direct caller gets
- * the same policy. The doc record is exempt; over the cap the other records
- * are dropped (shell still stored and replayed; the pins' loaders read the
- * live store — see PartialPrerenderProps.maxSnapshotBytes).
+ * the same policy. The doc record is exempt; over the cap only the
+ * navigation half is stored (see PartialPrerenderProps.maxSnapshotBytes).
  */
 export const DEFAULT_PPR_MAX_SNAPSHOT_BYTES: number = 8 * 1024 * 1024;
 
@@ -548,12 +552,8 @@ const SNAPSHOT_BYTE_ENCODER = new TextEncoder();
 
 /**
  * Warn once per key that the capture's loader pins exceeded the route's
- * `maxSnapshotBytes` cap and were dropped. The shell entry is still stored
- * with its doc record and every HIT replays the handler layer; only the
- * pinned loaders lose their captured values, so their cached data can drift
- * from the frozen prelude and hydration repairs it client-side. Once per
- * key: the same page recaptures on every TTL roll and would otherwise
- * re-warn forever.
+ * `maxSnapshotBytes` cap, so no document shell was stored (dc-t89). Once per
+ * key: the route recaptures every backoff window.
  */
 function warnSnapshotOverCapOnce(
   key: string,
@@ -565,14 +565,10 @@ function warnSnapshotOverCapOnce(
     key,
     () =>
       `[rango] Shell capture for "${key}" recorded ${snapshotBytes} bytes of ` +
-      `loader pins, over the ${capBytes}-byte cap — the pins were dropped and ` +
-      "the shell was stored with its doc record only. HITs still replay the " +
-      "handler layer, but ssr: false loaders now read the live store: if " +
-      "their data drifts before the shell's TTL, hydration repairs the " +
-      "mismatch client-side. Raise the cap via the route's ppr option " +
-      "({ maxSnapshotBytes }) if the entry still fits your store's value limit " +
-      "(Cloudflare KV: 25 MiB per value), or shrink the cache()'d data the " +
-      "loaders read.",
+      `ssr: false loader pins, over the ${capBytes}-byte cap: the document ` +
+      "shell was not stored; raise maxSnapshotBytes or shrink the ssr: false " +
+      "data. Documents of this route are a MISS until then; client " +
+      "navigations still replay its handler layer.",
   );
 }
 
@@ -678,7 +674,11 @@ export interface ShellCaptureDebugEvent {
   preludeBytes?: number;
   /** Serialized snapshot size in UTF-8 bytes. Absent when nothing was recorded. */
   snapshotBytes?: number;
-  /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
+  /**
+   * True when the loader pins exceeded maxSnapshotBytes: no document shell
+   * was stored, only a navigation-only entry (the doc record, or a tombstone
+   * for a prerender-served capture). The outcome is `refused`, refusal `size`.
+   */
   snapshotSkipped?: boolean;
   /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
   untaggedBake?: true;
@@ -1048,8 +1048,8 @@ export interface ShellCaptureDescriptor {
   captureTimeout?: number;
   store?: SegmentCacheStore<any>;
   /**
-   * Cap (serialized UTF-8 bytes) on the entry's capture data snapshot; over it
-   * the snapshot is skipped and the shell stored without it (reported once per
+   * Cap (serialized UTF-8 bytes) on the entry's loader pins; over it only the
+   * navigation half is stored and the attempt refuses (reported once per
    * key). Absent = DEFAULT_PPR_MAX_SNAPSHOT_BYTES, applied in
    * captureAndStoreShell — the single defaulting site.
    */
@@ -1667,8 +1667,9 @@ export type CaptureRecordOutcome =
  * component showed one value in the prelude and another on every HIT.
  *
  * Order, all bounded by the one capture deadline (`ppr.captureTimeout`):
- * top-level handle promises, the handler pushes' nested promises, and the
- * bake-lane loader containers settle first (the record encodes the handles
+ * top-level handle promises (a bake-lane loader's pushed promises among
+ * them, #1182), the handler pushes' nested promises, and the bake-lane
+ * loader containers settle first (the record encodes the handles
  * a HIT restores, and its handle encode has its own 5s timeout that must
  * never be the one that fires); then the capture's onResponse callbacks fire
  * with a synthetic 200 (the implicit doc scope's cacheRoute, an explicit
@@ -1711,7 +1712,33 @@ export async function settleCaptureRecord(
   if (!settled.done) {
     if (refuseOnCaptureGuard(capture.key, derivedCtx))
       return { kind: "refused", refusal: guardRefusal(derivedCtx) };
-    return { kind: "timeout", reason: HANDLER_OUTPUT_TIMEOUT_REASON };
+    const pending = derivation.loaderPromisePushes.find(
+      (p) => p.state === "pending",
+    );
+    return {
+      kind: "timeout",
+      reason: pending
+        ? `${describeLoaderPromisePush(pending)} did not settle within ppr.captureTimeout`
+        : HANDLER_OUTPUT_TIMEOUT_REASON,
+    };
+  }
+  // A rejected value must not bake, and the record's encode would fail on
+  // it anyway: refuse before the write starts. A guard trip in that promise
+  // names the read instead.
+  const rejected = derivation.loaderPromisePushes.find(
+    (p) => p.state === "rejected",
+  );
+  if (rejected) {
+    if (refuseOnCaptureGuard(capture.key, derivedCtx))
+      return { kind: "refused", refusal: guardRefusal(derivedCtx) };
+    warnCaptureRefusedOnce(
+      capture.key,
+      `${describeLoaderPromisePush(rejected)} rejected during capture; a ` +
+        "failed value must not bake into the shared shell. Catch it and push " +
+        "a fallback, or push it from a loader without ssr: false.",
+      PPR_LANE_HINT,
+    );
+    return { kind: "refused", refusal: "loader" };
   }
 
   const callbacks = derivedCtx._onResponseCallbacks?.splice(0) ?? [];
@@ -2006,6 +2033,20 @@ export interface CaptureContextDerivation {
    * record encodes its handles, so that encode never races a pending value.
    */
   handlerPushesSettled: () => Promise<void>;
+  /**
+   * Every promise a bake-lane loader body pushed (#1182), in push order.
+   * The record-first step waits for them (they are in the recorded cut) and
+   * names the loader and the handle of one that rejects or misses the
+   * deadline.
+   */
+  loaderPromisePushes: readonly LoaderPromisePush[];
+}
+
+/** A promise a bake-lane loader pushed at capture, owned by that loader. */
+export interface LoaderPromisePush {
+  loaderId: string;
+  handleName: string;
+  state: "pending" | "fulfilled" | "rejected";
 }
 
 /**
@@ -2041,30 +2082,35 @@ export function deriveShellCaptureContext(
   //    masked), their pushes are in the captured HTML (<head> title/meta,
   //    useHandle echoes), and a HIT does not run a promise-free bake-lane
   //    loader (loader-cache.ts), so the stored record carries them: each
-  //    settled, thenable-free push from a loader body keeps that loader as
-  //    `owner` (HandleStore.push), the record stores it
+  //    push from a loader body whose value, once settled, is thenable-free
+  //    keeps that loader as `owner` (HandleStore.push), the record stores it
   //    (CachedEntryData.handleOwners), and a replay that serves the loader
-  //    from its pin restores it through pushRestored (restoreHandles). Those
-  //    copies stand: a promise-carrying bake-lane loader that runs on the
-  //    replay reads the store, so its settled pushes (and those replayed
-  //    inside its body) are dropped and only its thenable ones are added. A
-  //    loader the replay does not serve from a pin is a hole: one the route
-  //    also runs on the live lane, or one whose pin the entry lost. Its run
-  //    replaces its copies (pushPlaceholder, #936), those of the
-  //    dependencies it awaits included (they are credited to it). Nested
-  //    thenables stay masked (the promise shape is the liveness
-  //    declaration, mask-nested.ts). A deferred (thenable) push,
-  //    one with masked nested promises, or one outside a loader body (a
-  //    loader-cache replay names its loader: pushReplayed below) stays
-  //    tagged (HandleStore.push loaderPush) so the
-  //    handle encode cannot stall on a never-resolving mask. A tagged push
-  //    is out of the record (captureHandles) and out of the capture's own
-  //    render (resolvedHandleStream `recordedOnly`, issue #1035): the
-  //    prelude is rendered from what the record keeps, which is what a HIT
-  //    hydrates with. The loader records then carry `runs: 1` so a HIT runs
-  //    those bodies for them, and what they push reaches the client after
+  //    from its pin restores it through pushRestored (restoreHandles). A
+  //    pushed promise (push(promise), .defer()) is judged by its settled
+  //    value, as push(await promise) would be (#1182): the record-first step
+  //    waits for it under the capture deadline, and one that rejects or
+  //    misses the deadline refuses the capture. Those copies stand: a
+  //    promise-carrying bake-lane loader that runs on the replay reads the
+  //    store, so its pushes that settle thenable-free (and those replayed
+  //    inside its body) are dropped and only the ones holding a promise are
+  //    added. A loader the replay does not serve from a pin is a hole: one
+  //    the route also runs on the live lane, or one whose pin the entry
+  //    lost. Its run replaces its copies (pushPlaceholder, #936), those of
+  //    the dependencies it awaits included (they are credited to it). Nested
+  //    thenables stay masked (the promise shape is the liveness declaration,
+  //    mask-nested.ts). A push whose settled value holds a masked nested
+  //    promise, one credited to a live-lane body, or one no body or replay
+  //    names (a loader-cache replay names its loader: pushReplayed below)
+  //    stays tagged (HandleStore.push loaderPush) so the handle encode cannot
+  //    stall on a never-resolving mask. A tagged push is out of the record
+  //    (captureHandles) and out of the capture's own render
+  //    (resolvedHandleStream `recordedOnly`, issue #1035): the prelude is
+  //    rendered from what the record keeps, which is what a HIT hydrates
+  //    with. The loader records then carry `runs: 1` so a HIT runs those
+  //    bodies for them, and what they push reaches the client after
   //    hydration (HandleStore.freezeDocumentSnapshot).
   const handlerPushSettles: Promise<void>[] = [];
+  const loaderPromisePushes: LoaderPromisePush[] = [];
   // A replay (a loader-cache HIT, loader-cache.ts replayLoaderHandles, or a
   // route cache() record's owned values, restoreHandles) re-pushes a loader's
   // recorded values through pushReplayed or pushPlaceholder, which call
@@ -2118,39 +2164,62 @@ export function deriveShellCaptureContext(
       if (report.thenable) maskedNestedThenable = true;
       return masked;
     };
+    // The loader the push is credited to (see the funnel comment above). A
+    // push under a live-lane loader's body, at any depth, is that hole's
+    // output: its live run replaces it on a HIT and a navigation. Otherwise
+    // the first loader around the push that the route registers decides: a
+    // bake-lane one keeps the push under the innermost body, and a
+    // dependency on neither lane is walked past. A replay of a hole's push
+    // is that hole's, unless a live-lane body around it takes it first.
+    const live = liveLaneOwner();
+    const bodyLoaderId = live ?? getCurrentLoaderBodyId() ?? replayOwner;
     let masked: unknown;
-    let loaderPush = true;
     let owner: string | undefined;
-    if (isThenable(value)) {
-      // Deferred (thenable) loader pushes always keep the tag — the
-      // carve-out below is for settled values only. Promise.resolve first: a
-      // loader cache() entry replays a deferred push as the thenable Flight
-      // decoded it to, whose then() returns nothing, and the slot was
-      // `undefined` (the empty element of issue #1035).
-      masked = Promise.resolve(value).then(mask);
-    } else {
+    if (!isThenable(value)) {
       masked = mask(value);
-      if (!maskedNestedThenable) {
-        // A settled, thenable-free push from a loader body is shell
-        // material (see the funnel comment above): only bake-lane loaders
-        // and the loaders they await run at capture, and a HIT does not run
-        // a promise-free bake-lane loader (loader-cache.ts), so the record
-        // keeps the push under the loader that made it. A push under a
-        // live-lane loader's body, at any depth, is that hole's output: it
-        // is credited to the hole, whose live run replaces it on a HIT and
-        // a navigation. The first loader around the push that the route
-        // registers decides: a bake-lane one keeps the push under the
-        // innermost body, and a dependency on neither lane is walked past. A
-        // replay of a hole's push is that hole's, unless a live-lane body
-        // around it takes it first.
-        const bodyLoaderId =
-          liveLaneOwner() ?? getCurrentLoaderBodyId() ?? replayOwner;
-        loaderPush = bodyLoaderId === undefined;
-        if (!loaderPush) owner = bodyLoaderId;
-      }
+      if (!maskedNestedThenable) owner = bodyLoaderId;
+    } else if (live === undefined && bodyLoaderId !== undefined) {
+      // Owned now, judged by its settled value (funnel comment above).
+      // Promise.resolve first: a loader cache() entry replays a deferred
+      // push as the thenable Flight decoded it to, whose then() returns
+      // nothing (issue #1035). The retag runs inside the slot's own then(),
+      // so it lands before the wait on it (settleCaptureRecord) resumes and
+      // the record encodes. The state handler is attached now, which also
+      // marks a rejection as handled.
+      const slot: Promise<unknown> = Promise.resolve(value).then((settled) => {
+        const judged = mask(settled);
+        if (maskedNestedThenable) {
+          freshHandleStore.unrecordPush(handleName, segmentId, slot);
+          derivedCtx._shellCaptureUnrecordedLoaderPush = true;
+        }
+        return judged;
+      });
+      const push: LoaderPromisePush = {
+        loaderId: bodyLoaderId,
+        handleName,
+        state: "pending",
+      };
+      slot.then(
+        () => {
+          push.state = "fulfilled";
+        },
+        () => {
+          push.state = "rejected";
+        },
+      );
+      loaderPromisePushes.push(push);
+      masked = slot;
+      owner = bodyLoaderId;
+    } else {
+      // A hole's promise, or one no body or replay names: tagged. Nothing
+      // awaits the slot at capture, so its rejection is handled here.
+      const tagged = Promise.resolve(value).then(mask);
+      tagged.catch(() => {});
+      masked = tagged;
     }
     // A push the record cannot keep reaches a HIT only from a live run of
     // its loader, so the loader records ask for one (runs: 1).
+    const loaderPush = owner === undefined;
     if (loaderPush) derivedCtx._shellCaptureUnrecordedLoaderPush = true;
     rawCapturePush(handleName, segmentId, masked, loaderPush, owner);
   };
@@ -2271,6 +2340,7 @@ export function deriveShellCaptureContext(
     freshHandleStore,
     handlerPushesSettled: () =>
       Promise.all(handlerPushSettles).then(() => undefined),
+    loaderPromisePushes,
   };
 }
 
@@ -2481,10 +2551,13 @@ async function captureAndStoreShell(
                 runs,
               },
             });
+          } else {
+            throw new Error(`[rango] no shell pin for "${segmentKey}"`);
           }
-        } catch {
-          // Codec import failed: leave it unpinned (it drifts on a HIT, the
-          // pre-snapshot behavior) rather than failing the capture.
+        } catch (error) {
+          // Unpinned, the loader would run on every HIT over this prelude
+          // (dc-t89): refuse like an encode error.
+          reqCtx._renderErrors?.push(error);
         }
       }
     }
@@ -2528,12 +2601,11 @@ async function captureAndStoreShell(
       snapshot = kept;
     }
 
-    // Snapshot size guard (issue #651): `maxSnapshotBytes` bounds the loader
-    // pins; over it they are dropped and the entry keeps its doc record, so
-    // every HIT still replays the handler layer (the pins' loaders then run
-    // on the HIT: documented drift, repaired client-side). The doc record is
-    // exempt: without it a HIT could not serve at all. The whole entry is
-    // bounded separately below, by the store's value limit.
+    // Snapshot size guard: `maxSnapshotBytes` bounds the loader pins, and a
+    // document HIT needs every pin its prelude baked (dc-t89). Over the cap
+    // the entry keeps the navigation half only (the doc record, or nothing:
+    // a tombstone that also shadows a build shell) and the attempt refuses.
+    // The whole entry is bounded separately below, by the store's limit.
     if (snapshot.length > 0) {
       const docRecord =
         docKey !== undefined
@@ -2554,9 +2626,10 @@ async function captureAndStoreShell(
         stats.snapshotSkipped = true;
       }
     }
+    const navigationOnly = capture.navigationOnly || stats.snapshotSkipped;
     // Exempt from maxSnapshotBytes: the HIT needs it for its HTML and
     // hydration data to match.
-    if (prerenderHandles) {
+    if (prerenderHandles && !navigationOnly) {
       snapshot.push({
         family: "handles",
         key: SHELL_HANDLES_RECORD_KEY,
@@ -2605,8 +2678,8 @@ async function captureAndStoreShell(
     // JSON head as an escaped string.
     const entryBytes = estimateShellEntryBytes({
       // A navigation-only entry stores no document half.
-      preludeBytes: capture.navigationOnly ? 0 : result.prelude.length,
-      postponed: capture.navigationOnly ? undefined : result.postponed,
+      preludeBytes: navigationOnly ? 0 : result.prelude.length,
+      postponed: navigationOnly ? undefined : result.postponed,
       snapshot,
       tags: shellTags,
       docKey: storedDocKey,
@@ -2642,7 +2715,7 @@ async function captureAndStoreShell(
           // consumes only snapshot/docKey), so storing it would ride every KV
           // write/read as dead weight — the prerender still ran above as the
           // completeness arbiter and sanity gate, its output is dropped here.
-          ...(capture.navigationOnly
+          ...(navigationOnly
             ? {}
             : {
                 // bytesToBase64 encodes the view's own region, so a prelude
@@ -2665,7 +2738,7 @@ async function captureAndStoreShell(
           // looks the record up by this key (serveShellHit fixedDocKey);
           // undefined only for a prerender-served entry.
           docKey: storedDocKey,
-          navigationOnly: capture.navigationOnly,
+          navigationOnly: navigationOnly || undefined,
           createdAt: captureStartedAt,
         };
         // Capped to the route record the capture used: the policy the
@@ -2753,8 +2826,9 @@ async function captureAndStoreShell(
     }
     // A shell was captured (ordinary store I/O failure is reported, not retried).
     // An acknowledged invalidation rejection returned `refused` above so the
-    // scheduler backs the key off instead of recapturing on every request.
-    return "stored";
+    // scheduler backs the key off instead of recapturing on every request, as
+    // does an over-cap entry: no document shell was stored.
+    return stats.snapshotSkipped ? refuse(stats, "size") : "stored";
   } finally {
     // Stop the hop loop for the pathological never-quiets path (quiesce never
     // fired, capture returned via maxWaitMs). On the normal path the loop already
@@ -2774,7 +2848,8 @@ export {
 };
 
 // Exported for unit tests that pin the refused-capture backoff policy directly
-// (dev cap vs production exponential growth, stored-clears, cold-start re-probe).
+// (dev cap vs production exponential growth, stored-clears, cold-start re-probe),
+// and markCaptureBackoff for serveShellHit (a pin that failed to decode, dc-t89).
 // These are the same module-level functions the schedule path uses; a test that
 // drove them through a real capture round-trip could not assert the exact window
 // arithmetic without a full cold render.