@rangojs/router 0.26.0 → 0.26.1

package/dist/bin/rango.js

@@ -1644,7 +1644,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.26.0",
+      version: "0.26.1",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",

package/dist/types/cache/shell-snapshot.d.ts

@@ -199,11 +199,13 @@ export interface ShellLoaderSeedEntry {
  * by loader. A key that does not parse pins nothing.
  *
  * Deserializations run in parallel; a record that fails to decode is skipped
- * (that loader drifts — the pre-snapshot behavior — instead of failing the
- * HIT). Returns undefined when the snapshot carries no loader records, without
- * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
+ * and reported to `onUndecodable`: its loader runs instead, which a document
+ * HIT has already committed a prelude against, so serveShellHit retires the
+ * entry (dc-t89). Returns undefined when the snapshot carries no loader
+ * records, without touching the Flight codec (kept lazy for cold paths and
+ * non-RSC configs).
  */
-export declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[]): Promise<Map<string, ShellLoaderSeedEntry> | undefined>;
+export declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[], onUndecodable?: (key: string) => void): Promise<Map<string, ShellLoaderSeedEntry> | undefined>;
 /** The key of a snapshot's one `handles` record (ShellSnapshotHandlesValue). */
 export declare const SHELL_HANDLES_RECORD_KEY = "handles";
 /**

package/dist/types/router/dev-reload-handoff.d.ts

@@ -0,0 +1,26 @@
+import type { RangoInternal } from "./router-interfaces.js";
+/** The `import.meta.hot` subset this reads. */
+interface RunnerReloadEvents {
+    on(event: "vite:beforeFullReload", listener: () => void): void;
+}
+/**
+ * Mark this module copy dropped on the runner's next full reload.
+ * @internal
+ */
+export declare function watchRunnerReloads(events: RunnerReloadEvents | undefined): void;
+/**
+ * Whether a runner full reload dropped this module copy.
+ * @internal
+ */
+export declare function droppedByRunnerReload(): boolean;
+/**
+ * The router the reload re-created for `routerId`, or undefined when none
+ * registered within DEV_RECREATED_ROUTER_WAIT_MS. Importing `sourceFile`
+ * evaluates it when nothing else is. While the reload's re-import is still
+ * evaluating it, the runner returns the unfinished module (it is in this
+ * copy's import call stack, `cachedRequest` in vite's module-runner), so this
+ * waits for the fresh registry to receive the router.
+ * @internal
+ */
+export declare function routerAfterRunnerReload(routerId: string, sourceFile: string | undefined): Promise<RangoInternal<any, any> | undefined>;
+export {};

package/dist/types/rsc/shell-capture-constants.d.ts

@@ -153,9 +153,12 @@ export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;
  * `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" | "dynamic" | "loader" | "no-record" | "handles" | "size" | "record-expired" | "invalidated" | "uncacheable";
 /**

package/dist/types/rsc/shell-capture.d.ts

@@ -105,9 +105,8 @@ export declare const DEFAULT_SHELL_ENTRY_MAX_BYTES: number;
  * 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 declare const DEFAULT_PPR_MAX_SNAPSHOT_BYTES: number;
 /**
@@ -165,7 +164,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;
@@ -315,8 +318,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.
      */

package/dist/types/urls/pattern-types.d.ts

@@ -60,12 +60,13 @@ export interface PartialPrerenderProps {
     /**
      * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
      * data snapshot: the bake-lane loader records. The doc record (the handler
-     * layer every HIT replays) is exempt. Over the cap the pins are dropped: the
-     * shell is still stored and every HIT still replays the handler layer, but the
-     * pinned loaders read the live store, so drifted cached content can
-     * hydration-mismatch and be repaired client-side. Reported once per key.
-     * Defaults to 8 MiB. The whole entry is bounded separately by the store's
-     * value limit (Cloudflare KV: 25 MiB); an entry over it is refused.
+     * layer every HIT replays) is exempt. A document HIT is served only from an
+     * entry that holds a pin for every `ssr: false` loader its HTML baked, so
+     * over the cap no document shell is stored: documents render in full
+     * (MISS), and client navigations still replay the handler layer and run
+     * those loaders fresh. Reported once per key. Defaults to 8 MiB. The whole
+     * entry is bounded separately by the store's value limit (Cloudflare KV:
+     * 25 MiB); an entry over it is refused.
      */
     maxSnapshotBytes?: number;
     /**

package/dist/vite/index.js

@@ -7077,7 +7077,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.26.0",
+  version: "0.26.1",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/ppr/SKILL.md

@@ -372,7 +372,8 @@ replay its eligible snapshot. In both cases `matchPartial()`:
 - runs live DSL loaders fresh with their normal `loading()` streaming
   behavior, and serves bake-lane loaders from the pins of a shell captured by a
   document request; a snapshot captured by a navigation alone carries no pins,
-  and its replay runs them fresh (see below);
+  nor does the navigation-only entry a capture over `ppr.maxSnapshotBytes`
+  stores, and their replay runs them fresh (see below);
 - keeps the existing prefetch key, source scope, and in-flight lock unchanged.
 
 This is deliberately invisible to the browser: the response is the same
@@ -382,8 +383,9 @@ snapshot is a shell a document request captured, as on a document HIT: a
 promise-free `ssr: false` loader is served from its pin without running
 (unless the capture marked it to run: see "On a shell HIT"), and one whose
 return holds promises runs with its baked parts overlaid. A snapshot captured
-by a navigation alone carries no pins, and its replay runs them fresh. Loaders
-without `ssr: false` stay live.
+by a navigation alone carries no pins, nor does an entry over
+`ppr.maxSnapshotBytes`, and its replay runs them fresh. Loaders without
+`ssr: false` stay live.
 
 A route's own `cache()` scope — including one inherited from an ancestor, the
 common app-wide storefront shape — COMPOSES with replay instead of disabling
@@ -924,7 +926,9 @@ by a navigation alone carries no pins, and its replay runs these loaders fresh.
   fill the holes — and the recorded baked paths are overlaid onto the fresh
   result, so the payload matches the prelude while the nested promises stream
   fresh. A fresh rejection skips the overlay and goes to the loader's error
-  boundary. Give it its own cache,
+  boundary: on a document HIT the payload then carries the error where the
+  HTML has the baked value, and React renders that part again on the client
+  (one hydration mismatch, the one known residual of a HIT). Give it its own cache,
   `loader(Def, { ssr: false }, () => [cache({ ttl })])`, so that run reads
   through the loader cache.
 
@@ -985,9 +989,12 @@ loader running on the replay awaits it. On a document HIT the page hydrates
 with the shell's copy and the hole's value takes its place after hydration
 ("Handles on a shell HIT" below). An
 `ssr: false` loader is served from the shell only while the entry holds its
-pin: a snapshot captured by a navigation alone carries none, and a shell over
-`ppr.maxSnapshotBytes` drops them. There the loader runs fresh, and its
-pushes are that run's, like its data.
+pin: a snapshot captured by a navigation alone carries none, and a capture
+over `ppr.maxSnapshotBytes` stores the navigation half only, without them.
+There a navigation runs the loader fresh, and its pushes are that run's, like
+its data. A document HIT is served only from an entry that holds a pin for
+every `ssr: false` loader its HTML baked, so a document never hydrates one
+loader's run over HTML rendered from the capture's value.
 
 A `Prerender` + `ppr` page follows the same table. Its handler layer comes
 from the prerendered payload, which never holds a loader push (loaders do not
@@ -997,8 +1004,9 @@ on its own, and a HIT restores them as above (#1057).
 A dependency the route does not register, which an `ssr: false` loader
 awaited at capture outside any live loader, is on neither lane: its settled
 pushes stay as the prelude rendered them, even where a live loader also
-awaits it, while its data is fresh. (They follow the run instead once the
-entry has lost a pin, because the loader that awaits it then runs.) To keep
+awaits it, while its data is fresh. (They follow the run instead when the
+replayed entry has no pin for the loader that awaits it, because that loader
+then runs.) To keep
 its pushes live, declare it as its own `loader()` on the route. A push the
 capture cannot record (one whose value, once settled, holds a promise) marks
 every loader record of the page to run: those bodies then still run on each
@@ -1035,12 +1043,11 @@ Four things follow, in this order of scope:
    inside the `loading()` or `<Suspense>` of a loader that pushes after an
    `await` hydrates clean.
 
-| On the HIT's request                                                                       | In the HIT's HTML      | The client                                        |
-| ------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------- |
-| a handler's push, a pinned `ssr: false` loader's push (`push(promise)` and `.defer()` too) | yes (the shell has it) | hydrates with it                                  |
-| a push by an `ssr: false` loader whose value holds a promise                               | no                     | gets it right after hydration                     |
-| a live-lane loader's push                                                                  | no                     | gets it right after hydration                     |
-| the run of an `ssr: false` loader the shell has no pin for                                 | the capture's push     | hydrates with the capture's, then shows the run's |
+| On the HIT's request                                                                       | In the HIT's HTML      | The client                    |
+| ------------------------------------------------------------------------------------------ | ---------------------- | ----------------------------- |
+| a handler's push, a pinned `ssr: false` loader's push (`push(promise)` and `.defer()` too) | yes (the shell has it) | hydrates with it              |
+| a push by an `ssr: false` loader whose value holds a promise                               | no                     | gets it right after hydration |
+| a live-lane loader's push                                                                  | no                     | gets it right after hydration |
 
 So a title an `ssr: false` loader pushes to `Meta`, promise or not, is in
 every HIT's `<head>`: a crawler and a link preview see it. It bakes with the
@@ -1408,13 +1415,13 @@ path(
 );
 ```
 
-| Field              | Default | Notes                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                                                                                                                                                                                                                                                                            |
-| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                                                                                                                                                                                                                                                                  |
-| `tags`             | —       | operational tags UNIONED with the tags the capture collects — see "Invalidation" below                                                                                                                                                                                                                                                                                                                      |
-| `maxSnapshotBytes` | 8 MiB   | cap on the loader pins in the entry's snapshot (the bake-lane loader records). The recorded handler layer is exempt. Over the cap the pins are dropped and the shell is stored with its handler layer (warned once per key); bake-lane loaders then run on every replay and read the live store, their handle pushes come from that run like their data, and drift from the prelude is repaired client-side |
-| `captureTimeout`   | 15000ms | ONE capture deadline: the handler layer settling (promises it passes or pushes, async server components, loaders it awaits), bake-lane loaders, and the prerender; a capture that misses it stores nothing rather than a partial shell                                                                                                                                                                      |
+| Field              | Default | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ttl`              | `300`   | shell freshness window in seconds (`ppr: true` uses the default)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `swr`              | —       | stale window: serve the stale shell + background recapture                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `tags`             | —       | operational tags UNIONED with the tags the capture collects — see "Invalidation" below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `maxSnapshotBytes` | 8 MiB   | cap on the loader pins in the entry's snapshot (the bake-lane loader records). The recorded handler layer is exempt. A document HIT is served only from an entry that holds a pin for every `ssr: false` loader its HTML baked, so over the cap no document shell is stored: the entry keeps the handler layer only, documents are a MISS (full SSR, no hydration error, no remount), client navigations still replay the handler layer and run the bake-lane loaders fresh, and the URL backs off like a refused capture. Warned once per key: "the document shell was not stored; raise maxSnapshotBytes or shrink the ssr: false data" |
+| `captureTimeout`   | 15000ms | ONE capture deadline: the handler layer settling (promises it passes or pushes, async server components, loaders it awaits), bake-lane loaders, and the prerender; a capture that misses it stores nothing rather than a partial shell                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 A shell never outlives the route `cache()` entry it was captured from: under
 a route `cache()`, the shell is fresh no longer than that entry is (at most

package/src/cache/shell-snapshot.ts

@@ -405,12 +405,15 @@ const PIN_KEY_PREFIX = /^[^D.]*D\d+\./;
  * by loader. A key that does not parse pins nothing.
  *
  * Deserializations run in parallel; a record that fails to decode is skipped
- * (that loader drifts — the pre-snapshot behavior — instead of failing the
- * HIT). Returns undefined when the snapshot carries no loader records, without
- * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
+ * and reported to `onUndecodable`: its loader runs instead, which a document
+ * HIT has already committed a prelude against, so serveShellHit retires the
+ * entry (dc-t89). Returns undefined when the snapshot carries no loader
+ * records, without touching the Flight codec (kept lazy for cold paths and
+ * non-RSC configs).
  */
 export async function buildShellLoaderSeed(
   snapshot: ShellSnapshotRecord[],
+  onUndecodable?: (key: string) => void,
 ): Promise<Map<string, ShellLoaderSeedEntry> | undefined> {
   const loaderRecords: ShellSnapshotRecord[] = [];
   for (const rec of snapshot) {
@@ -441,6 +444,7 @@ export async function buildShellLoaderSeed(
             },
           ];
         } catch {
+          onUndecodable?.(rec.key);
           return null;
         }
       },

package/src/router/dev-reload-handoff.ts

@@ -0,0 +1,73 @@
+import type { RangoInternal } from "./router-interfaces.js";
+
+/**
+ * Dev only (#1186). A runner full reload clears its evaluated modules while a
+ * request may still be loading them, splitting it across two router copies
+ * whose registries disagree. A router of a dropped copy hands its requests to
+ * the router the reload re-created. docs/manifests.md, "A request the reload
+ * split".
+ */
+let runnerReloaded = false;
+
+/**
+ * Bound on the wait for the re-created router. cloudflare-basic's entry took
+ * about 5 s to re-evaluate after the optimizer's `invalidateAll`.
+ */
+const DEV_RECREATED_ROUTER_WAIT_MS = 10_000;
+const DEV_RECREATED_ROUTER_POLL_MS = 20;
+
+/** The `import.meta.hot` subset this reads. */
+interface RunnerReloadEvents {
+  on(event: "vite:beforeFullReload", listener: () => void): void;
+}
+
+/**
+ * Mark this module copy dropped on the runner's next full reload.
+ * @internal
+ */
+export function watchRunnerReloads(
+  events: RunnerReloadEvents | undefined,
+): void {
+  events?.on("vite:beforeFullReload", () => {
+    runnerReloaded = true;
+  });
+}
+
+if (process.env.NODE_ENV !== "production") {
+  watchRunnerReloads(import.meta.hot);
+}
+
+/**
+ * Whether a runner full reload dropped this module copy.
+ * @internal
+ */
+export function droppedByRunnerReload(): boolean {
+  return runnerReloaded;
+}
+
+/**
+ * The router the reload re-created for `routerId`, or undefined when none
+ * registered within DEV_RECREATED_ROUTER_WAIT_MS. Importing `sourceFile`
+ * evaluates it when nothing else is. While the reload's re-import is still
+ * evaluating it, the runner returns the unfinished module (it is in this
+ * copy's import call stack, `cachedRequest` in vite's module-runner), so this
+ * waits for the fresh registry to receive the router.
+ * @internal
+ */
+export async function routerAfterRunnerReload(
+  routerId: string,
+  sourceFile: string | undefined,
+): Promise<RangoInternal<any, any> | undefined> {
+  if (!sourceFile) return undefined;
+  await import(/* @vite-ignore */ sourceFile);
+  const { RouterRegistry } = await import("./router-registry.js");
+  const deadline = Date.now() + DEV_RECREATED_ROUTER_WAIT_MS;
+  let router = RouterRegistry.get(routerId);
+  while (!router && Date.now() < deadline) {
+    await new Promise((resolve) =>
+      setTimeout(resolve, DEV_RECREATED_ROUTER_POLL_MS),
+    );
+    router = RouterRegistry.get(routerId);
+  }
+  return router;
+}

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";
@@ -1274,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);

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

@@ -213,9 +213,12 @@ export const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25_000;
  * `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

@@ -542,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;
 
@@ -553,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,
@@ -570,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.",
   );
 }
 
@@ -683,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;
@@ -1053,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.
    */
@@ -2556,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);
         }
       }
     }
@@ -2603,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
@@ -2629,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,
@@ -2680,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,
@@ -2717,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
@@ -2740,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
@@ -2828,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
@@ -2849,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.

package/src/urls/pattern-types.ts

@@ -66,12 +66,13 @@ export interface PartialPrerenderProps {
   /**
    * Upper bound (serialized UTF-8 bytes) on the loader pins in the capture
    * data snapshot: the bake-lane loader records. The doc record (the handler
-   * layer every HIT replays) is exempt. Over the cap the pins are dropped: the
-   * shell is still stored and every HIT still replays the handler layer, but the
-   * pinned loaders read the live store, so drifted cached content can
-   * hydration-mismatch and be repaired client-side. Reported once per key.
-   * Defaults to 8 MiB. The whole entry is bounded separately by the store's
-   * value limit (Cloudflare KV: 25 MiB); an entry over it is refused.
+   * layer every HIT replays) is exempt. A document HIT is served only from an
+   * entry that holds a pin for every `ssr: false` loader its HTML baked, so
+   * over the cap no document shell is stored: documents render in full
+   * (MISS), and client navigations still replay the handler layer and run
+   * those loaders fresh. Reported once per key. Defaults to 8 MiB. The whole
+   * entry is bounded separately by the store's value limit (Cloudflare KV:
+   * 25 MiB); an entry over it is refused.
    */
   maxSnapshotBytes?: number;
   /**