@rangojs/router 0.4.2 → 0.5.0

package/dist/types/rsc/stream-idle.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Stream-idle timeout — the enforcement for `timeouts.streamIdleMs` (the
+ * "stream-idle" TimeoutPhase, reserved since the timeout API landed).
+ *
+ * WHY: nothing else bounds a streaming response body's lifetime.
+ * `renderStartMs` only bounds time-to-Response-construction; once the body is
+ * streaming, a single never-settling promise embedded in the payload (a
+ * deferred loader that never resolves, an orphaned ctx.rendered() barrier)
+ * holds the Flight/HTML stream — and the client's connection — open forever.
+ * Deferred HANDLES have a 10s auto-resolve net (defer.ts); loader promises
+ * and everything else have none. Field-observed as multi-second dead
+ * connections only closed by client cancellation.
+ *
+ * SEMANTICS — end-to-end idle flow, deliberately: the watchdog re-arms on
+ * every chunk that flows THROUGH to the client, so "idle" means "no bytes
+ * reached the wire for N ms". A stalled slow client counts as idle the same
+ * as a wedged producer — the two are indistinguishable here without buffering,
+ * and buffering is banned on the streaming path. Pick budgets accordingly
+ * (generous, seconds not millis); the feature is OPT-IN (unset = today's
+ * unbounded behavior, and the `timeout` shorthand deliberately does not apply
+ * to streamIdleMs — see resolveTimeouts).
+ *
+ * ON TRIP: the client-facing stream is errored with a RouterTimeoutError
+ * ("stream-idle") — the host terminates the response visibly (truncated
+ * chunked encoding), which is debuggable, unlike a silent clean close that
+ * would present a half-document as complete. Erroring the transform makes the
+ * pipe cancel its SOURCE, which aborts React's fizz/flight render — but only
+ * when the watchdog's branch is the sole consumer. When an upstream layer
+ * teed or cloned the body first (the document-cache MISS drain,
+ * response-cache clones), the watchdog holds one tee branch: tee semantics
+ * cancel the underlying source only once EVERY branch cancels, so the cache
+ * branch keeps the wedged render alive, bounded only by the platform's
+ * waitUntil budget — exactly as it was before this feature. The client-facing
+ * bound is unconditional; source teardown is best-effort. `onTimeout` does
+ * NOT apply: the response already left the handler, so no replacement
+ * Response can be served — the trip is reported via onError + the
+ * request.timeout telemetry event instead.
+ *
+ * COST: one identity TransformStream hop per chunk, only when the timeout is
+ * enabled. Never buffers, never reads ahead, adds no work when disabled.
+ */
+import { RouterTimeoutError } from "../router/timeout.js";
+/** What the watchdog observed when it tripped. */
+export interface StreamIdleTrip {
+    /** ms since the watchdog armed (response handoff) — the stream's lifetime. */
+    totalMs: number;
+    /** Chunks forwarded before the trip. */
+    chunks: number;
+    /** The error the client-facing stream was terminated with. */
+    error: RouterTimeoutError;
+}
+/**
+ * Wrap `response`'s body in an idle watchdog. Returns a NEW Response with the
+ * same status/headers whose body errors (and cancels the source) once no chunk
+ * has flowed for `idleMs`. Callers gate on isTimeoutEnabled + body presence +
+ * NOT a websocket upgrade (a 101/webSocket response must never be
+ * reconstructed); this function assumes those checks were made. `onTrip` fires
+ * at most once, after the client-facing stream has been errored.
+ */
+export declare function applyStreamIdleTimeout(response: Response, idleMs: number, onTrip: (trip: StreamIdleTrip) => void): Response;

package/dist/types/server/request-context.d.ts

@@ -564,6 +564,12 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * to avoid a second resolveRoute call. Cleared on HMR invalidation.
      */
     _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
+    /**
+     * @internal Classified request mode from classifyRequest, read by the
+     * rango.response span tail (rsc/handler.ts) for the rango.response.mode
+     * attribute. Unset when middleware short-circuits before core execution.
+     */
+    _requestMode?: import("../router/request-classification.js").RequestPlan["mode"];
     /**
      * @internal Coarse route-level cache signal for the X-Rango-Cache debug
      * header. Populated by match/matchPartial only when the debug cache signal
@@ -579,7 +585,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhen" | "_pprTransitionDecisions" | "_pprReplayPostMatchReason" | "_cacheStore" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureHandleLiveness" | "_shellCaptureLoaderHandleValues" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_locationState" | "_routeName" | "_prevRouteKey" | "_gateCurrentUrl" | "_gateCurrentParams" | "_gateActionId" | "_gateActionUrl" | "_gateActionResult" | "_gateFormData" | "_inActionRevalidation" | "_reportedErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:

package/dist/types/vercel/tracing.d.ts

@@ -1,12 +1,13 @@
 /**
  * Vercel OpenTelemetry tracing integration.
  *
- * Bridges the router's performance phases (request, middleware, action,
- * loaders, handler, render, ssr) onto OpenTelemetry spans so they show up in
- * Vercel's trace waterfall next to the platform's automatic spans, with correct
- * nesting. Vercel exposes tracing through OpenTelemetry (not a native import-free
- * API like Cloudflare), so this is a thin convenience over `createOTelTracing`:
- * it reads the global OTel tracer that `@vercel/otel`'s `registerOTel()` installs.
+ * Bridges the router's observable phases (request, middleware, action, loaders,
+ * handler, render, ssr, response, background) onto OpenTelemetry spans so they
+ * show up in Vercel's trace waterfall next to the platform's automatic spans,
+ * with correct nesting. Vercel exposes tracing through OpenTelemetry (not a
+ * native import-free API like Cloudflare), so this is a thin convenience over
+ * `createOTelTracing`: it reads the global OTel tracer that `@vercel/otel`'s
+ * `registerOTel()` installs.
  *
  * Usage (vercel preset). A Rango/Vite app does NOT auto-load `instrumentation.ts`
  * the way Next.js does, so export the tracing config from there and import it —
@@ -59,8 +60,8 @@ export interface VercelTracingOptions extends TracingToggleOptions {
 /**
  * Create the tracing config for a Vercel router. Pass the result to
  * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
- * action, loaders, handler, render, and ssr phases; pass `spans` to turn
- * individual phases off.
+ * action, loaders, handler, render, ssr, response, and background phases; pass
+ * `spans` to turn individual phases off.
  *
  * @see createOTelTracing (`@rangojs/router`) for the underlying adapter on any
  *   platform with an OpenTelemetry SDK.

package/dist/vite/index.js

@@ -2530,7 +2530,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.4.2",
+  version: "0.5.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

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

package/skills/observability/SKILL.md

@@ -145,10 +145,39 @@ const router = createRouter({ document: Document, urls: urlpatterns, tracing });
 These factories return a `RouterTracingConfig` for the same `tracing` slot;
 `telemetry` stays independent (events only, no phase spans). Phase spans:
 `rango.request`, `rango.middleware`, `rango.action`, `rango.loader`,
-`rango.render`, `rango.ssr` — the same phases the `debugPerformance` timeline
-shows, co-emitted from one site. Off-platform (no Cloudflare tracing destination
-/ no OTel SDK) every span call is a transparent pass-through, so the request
-behaves as if tracing were off.
+`rango.handler`, `rango.render`, `rango.ssr`, `rango.response`,
+`rango.background`. All share the `PHASES` registry and `observePhase`
+execution boundary with `debugPerformance`; phases with `metric: false` either
+use finer-grained perf rows or, for `response` and `background`, remain
+span-only. Off-platform (no Cloudflare tracing destination / no OTel SDK) every
+span call is a transparent pass-through, so the request behaves as if tracing
+were off.
+
+`rango.response` is the explicit handoff marker: at most one per traced
+request, a direct child of `rango.request`, wrapping only response finalization
+(redirect interception/guarding, `Server-Timing` mutation, final response
+selection) and ending immediately before the handler returns the response to
+the host. It is handoff-bound, never drain-bound — it never reads or awaits
+`response.body`. Attributes: `http.response.status_code`,
+`rango.response.mode` (classified request mode, or `middleware-short-circuit`),
+`rango.response.body_kind` (`stream`/`empty`/`websocket`). For request modes
+that render nothing (fetchable `_rsc_loader`, response routes, middleware
+short-circuits) it shows the trace is complete rather than truncated — those
+requests legitimately have no `rango.render`/`rango.ssr`/`rango.handler` spans.
+On deployed Workers it may read 0 ms (frozen non-I/O timers); its position and
+attributes are the value. Disable per-response billing overhead at volume with
+`spans: { response: false }`.
+
+`rango.background` wraps detached waitUntil work — PPR shell captures and SWR
+background revalidations — that runs after the foreground spans ended. Without
+it, a capture or revalidation shows up as an unexplained wave of orphan
+KV/fetch spans minutes into a trace. `rango.background.kind` names the lane
+(`shell-capture` / `document-revalidation` / `loader-revalidation` /
+`use-cache-revalidation`); the shell-capture lane also carries
+`rango.shell_key`, `rango.background.outcome`, and
+`rango.background.queue_wait_ms` (a capture parked behind the per-isolate
+capture queue reads as span duration, not dead air). Toggle with
+`spans: { background: false }`.
 
 Custom sinks implement `emit(event)`:
 

package/skills/ppr/SKILL.md

@@ -358,14 +358,27 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   falls through to KV on a miss, and promotes the KV hit back into that colo.
   WITHOUT a KV namespace its shell family remains inert: every ppr route stays
   `MISS` forever. The store warns once per isolate — bind KV
-  (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store.
+  (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store. An
+  inert store also stops captures at the gate: the store declares
+  `shellFamilyInert` and the scheduler skips the background render entirely
+  (`skip-inert-store` on the debug event) instead of burning a full capture per
+  MISS whose write could only no-op.
 - Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
   logs one line per capture attempt/skip (outcome, durations, prelude and
   snapshot bytes, backoff state); pass a function to receive each
   `ShellCaptureDebugEvent` instead. `skip-capacity` means the isolate already
   has 32 queued/running captures; the dropped best-effort capture can retry on a
-  later request. In dev, with `debugPerformance` on, the
-  last capture outcome for a key also rides the next document GET's
+  later request. `skip-queue-timeout` means this capture waited 15s behind the
+  active or same-priority work and was dropped before rendering; document-shell
+  captures outrank queued navigation-only snapshots, but never interrupt the
+  active capture — the skip event and the `rango.background` span carry
+  `queuePriority`/`queueAhead` (class and backlog at enqueue) so a parked
+  capture diagnoses itself. A stored attempt reports `bakeWaitMs`: how long the
+  slowest bake source (a top-level pushed handle promise or a bake-lane loader
+  container) held the capture gate — in dev, past 2s, the source is also named
+  once per key in a console warning with the remedies (nest the promise /
+  `cache()` the work / add `loading()`). In dev, with `debugPerformance` on,
+  the last capture outcome for a key also rides the next document GET's
   `Server-Timing` as `ppr-capture;desc="…"`.
 - For deployed Cloudflare tier diagnostics, build with
   `INTERNAL_RANGO_DEBUG=1` and run `wrangler tail`. `[CFCacheStore][shell]`
@@ -621,6 +634,34 @@ capture with identity reads permitted, and the value bakes as a shared
 capture-time copy — mirroring `cache()` semantics (the consumption-lane
 rule; semantic-matrix row PPR3).
 
+### Designing routes for cheap captures (the cost model)
+
+The hole doctrine has a cost corollary that bites silently: **everything that
+bakes is awaited at capture, and that wait recurs on EVERY capture of the
+route**. A top-level pushed handle promise that takes 5s and a Meta promise
+chained 2s further make every capture occupy the per-isolate serialized queue
+for ~7s — while the served response still reads 13ms TTFB, because captures are
+detached. You will not see this cost in any request timing; you see it as slow
+MISS→HIT flips, `skip-queue-timeout` under prefetch pressure, and (in dev, past
+2s) the bake-cost warning naming the source.
+
+Three levers, in preference order:
+
+1. **Nest it** (`{ data: promise }` instead of the promise): the value becomes
+   a hole — per-request, streamed under the consumer's `<Suspense>`, zero
+   capture cost. Choose this whenever the value may be dynamic anyway.
+2. **`cache()` the work inside it**: the value stays baked (shell material,
+   tag-invalidatable), but the capture replays the cached value instead of
+   re-executing the expensive body (mixed-chain). Choose this for shared,
+   expensive-to-compute shell content.
+3. **`loading()` on the entry** (loaders only): moves the loader to the live
+   lane — masked at capture, fresh per serve — at the cost of a fallback in
+   the shell.
+
+Head material (Meta) generally cannot be a hole — the head is shell — so its
+promises bake by design; make them cheap with lever 2. `bakeWaitMs` on the
+capture debug event tells you what each capture actually paid.
+
 ## Execution matrix
 
 | Phase            | MISS (foreground)      | Background capture                                                 | HIT (foreground)                                            |

package/src/browser/prefetch/cache.ts

@@ -10,12 +10,12 @@
  * scopes are in play:
  * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
  *   shape `rangoState\0/target?...`. Shared across all source pages and
- *   invalidated automatically when Rango state bumps (deploy or
- *   server-action invalidation).
+ *   source segment trees; `_rsc_segments` is omitted from this key. Invalidated
+ *   automatically when Rango state bumps (deploy or server-action invalidation).
  * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
  *   — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
- *   (so rotation invalidates source-scoped entries too) plus the source
- *   href (so each originating page gets its own slot). Populated when the
+ *   (so rotation invalidates source-scoped entries too), the source href, and
+ *   the exact source segment tree. Populated when the
  *   server tags a response with `X-RSC-Prefetch-Scope: source` (intercept
  *   modals etc.), OR when a Link opts in with `prefetchKey=":source"` — in
  *   both cases so source-sensitive responses cannot bleed into navigations
@@ -141,7 +141,9 @@ let generation = 0;
  * - Wildcard (source-agnostic): prefix is the Rango state value from
  *   `getRangoState()`. Shared across all source pages. Invalidated
  *   automatically when Rango state bumps (deploy or server-action).
- *   Key shape: `rangoState\0/target?...`.
+ *   `_rsc_segments` is omitted so sibling payloads prefetched from one page
+ *   remain reusable after another prefetched navigation commits. Key shape:
+ *   `rangoState\0/target?...`.
  * - Source-scoped: use `buildSourceKey()`. Key shape:
  *   `rangoState\0sourceHref\0/target?...` — embeds the Rango state so
  *   rotation invalidates source-scoped entries alongside wildcard ones,
@@ -150,12 +152,15 @@ let generation = 0;
  *   `X-RSC-Prefetch-Scope: source` (intercept modals, etc.) or when a
  *   Link opts in via `prefetchKey=":source"`.
  *
- * The `_rsc_segments` query param that travels in the target URL means
- * clients with different mounted segment trees naturally get different
- * keys — so segment-level diffs remain consistent across both scopes.
+ * Source-scoped keys retain `_rsc_segments` because their exact source tree is
+ * part of the opt-in contract. Wildcard responses are source-agnostic by
+ * contract; callers use source scope when a custom revalidation decision makes
+ * the response depend on the current URL or segment tree.
  */
 export function buildPrefetchKey(prefix: string, targetUrl: URL): string {
-  return prefix + "\0" + targetUrl.pathname + targetUrl.search;
+  const normalizedTarget = new URL(targetUrl);
+  normalizedTarget.searchParams.delete("_rsc_segments");
+  return prefix + "\0" + normalizedTarget.pathname + normalizedTarget.search;
 }
 
 /**
@@ -171,7 +176,14 @@ export function buildSourceKey(
   sourceHref: string,
   targetUrl: URL,
 ): string {
-  return buildPrefetchKey(rangoState + "\0" + sourceHref, targetUrl);
+  return (
+    rangoState +
+    "\0" +
+    sourceHref +
+    "\0" +
+    targetUrl.pathname +
+    targetUrl.search
+  );
 }
 
 /**

package/src/cache/cache-runtime.ts

@@ -45,6 +45,7 @@ import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
 import { sortedSearchString } from "./cache-key-utils.js";
 import { encodeKV } from "../encode-kv.js";
 import { runBackground } from "./background-task.js";
+import { observePhase, PHASES } from "../router/instrument.js";
 import {
   normalizeTags,
   recordRequestTags,
@@ -464,32 +465,45 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             // synchronous kickoff; its async continuations inherit it. The
             // DERIVED context goes in, so ambient _handleStore reads inside
             // the body resolve to the isolated store.
-            const scoped = runWithRequestContext(bgCtx, () =>
-              runWithCacheTagScope(() => fn.apply(this, args)),
-            );
-            const freshResult = await scoped.result;
-            bgStopCapture?.();
-            // Merge profile/DSL tags with runtime cacheTag() tags, read after
-            // awaiting so post-await cacheTag() calls are included. Normalize
-            // (drops empty profile tags, matching the invalidate path) + dedupe.
-            const freshTags = [
-              ...new Set(
-                normalizeTags([...(profile.tags ?? []), ...scoped.tags]),
+            //
+            // The span opens inside the request ALS and wraps the WHOLE task —
+            // fn kickoff through the store write — so its platform spans nest
+            // under rango.background and a slow or failing setItem is part of
+            // the traced revalidation, not an untraced tail.
+            await runWithRequestContext(bgCtx, () =>
+              observePhase(
+                PHASES.background("use-cache-revalidation"),
+                async () => {
+                  const scoped = runWithCacheTagScope(() =>
+                    fn.apply(this, args),
+                  );
+                  const freshResult = await scoped.result;
+                  bgStopCapture?.();
+                  // Merge profile/DSL tags with runtime cacheTag() tags, read
+                  // after awaiting so post-await cacheTag() calls are included.
+                  // Normalize (drops empty profile tags, matching the
+                  // invalidate path) + dedupe.
+                  const freshTags = [
+                    ...new Set(
+                      normalizeTags([...(profile.tags ?? []), ...scoped.tags]),
+                    ),
+                  ];
+                  recordRequestTags(freshTags, requestCtx);
+                  const serialized = await serializeResult(freshResult);
+                  if (serialized !== null) {
+                    const encodedHandles = bgCapture?.data
+                      ? await encodeHandles(bgCapture.data)
+                      : undefined;
+                    await store.setItem!(cacheKey, serialized, {
+                      handles: encodedHandles,
+                      ttl: profile.ttl,
+                      swr: profile.swr,
+                      tags: freshTags.length > 0 ? freshTags : undefined,
+                    });
+                  }
+                },
               ),
-            ];
-            recordRequestTags(freshTags, requestCtx);
-            const serialized = await serializeResult(freshResult);
-            if (serialized !== null) {
-              const encodedHandles = bgCapture?.data
-                ? await encodeHandles(bgCapture.data)
-                : undefined;
-              await store.setItem!(cacheKey, serialized, {
-                handles: encodedHandles,
-                ttl: profile.ttl,
-                swr: profile.swr,
-                tags: freshTags.length > 0 ? freshTags : undefined,
-              });
-            }
+            );
           } catch (bgError) {
             bgStopCapture?.();
             // Pass requestCtx explicitly: this runs in a detached background

package/src/cache/cf/cf-cache-store.ts

@@ -267,10 +267,13 @@ interface KVItemEnvelope {
  * @internal
  */
 interface CFShellEnvelope {
-  /** base64-encoded prelude bytes */
-  p: string;
-  /** postponed state JSON, or null (DATA variant — no holes) */
-  po: string | null;
+  /**
+   * base64-encoded prelude bytes. Absent iff `no` (navigationOnly entries
+   * store no document half — ShellCacheEntry.prelude).
+   */
+  p?: string;
+  /** postponed state JSON, or null (DATA variant — no holes). Absent iff `no`. */
+  po?: string | null;
   /** React.version captured at prerender time */
   rv: string;
   /** Build version captured at prerender time (ShellCacheEntry.buildVersion) */
@@ -347,8 +350,14 @@ function isShellEnvelope(value: unknown): value is CFShellEnvelope {
   if (value == null || typeof value !== "object") return false;
   const envelope = value as Partial<CFShellEnvelope>;
   return (
-    typeof envelope.p === "string" &&
-    (envelope.po === null || typeof envelope.po === "string") &&
+    // Document half: required unless the envelope is navigationOnly (`no`),
+    // which stores neither field. Tolerate a legacy navigationOnly envelope
+    // that still carries them.
+    (typeof envelope.p === "string" ||
+      (envelope.p === undefined && envelope.no === true)) &&
+    (envelope.po === null ||
+      typeof envelope.po === "string" ||
+      (envelope.po === undefined && envelope.no === true)) &&
     typeof envelope.rv === "string" &&
     (envelope.bv === undefined || typeof envelope.bv === "string") &&
     typeof envelope.c === "number" &&
@@ -400,6 +409,8 @@ interface KVResponseEnvelope {
 
 export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   readonly supportsPassiveShellReads: true = true;
+  /** True when constructed without KV: the shell family no-ops (see ctor). */
+  readonly shellFamilyInert?: boolean;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -471,6 +482,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     this.keyGenerator = options.keyGenerator;
     this.waitUntil = (fn) => options.ctx.waitUntil(fn());
     this.kv = options.kv;
+    // The shell family requires KV (getShell/putShell no-op without it — see
+    // warnShellFamilyInertOnce). Declaring it lets scheduleShellCapture skip
+    // captures whose write could only no-op instead of burning a background
+    // render per MISS that still occupies the serialized capture queue.
+    this.shellFamilyInert = options.kv ? undefined : true;
     this.onRevalidateTag = options.onRevalidateTag;
     // tagPurge accepts a ready purge function or a credentials object; the
     // object form is normalized through the built-in zone purge client, which
@@ -2083,8 +2099,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         }
 
         const envelope: CFShellEnvelope = {
-          p: entry.prelude,
-          po: entry.postponed,
+          // Presence-keyed: a navigationOnly entry has no document half, and an
+          // omitted key (vs an explicit undefined) also keeps it out of the
+          // serialized JSON.
+          ...(entry.prelude !== undefined ? { p: entry.prelude } : {}),
+          ...(entry.postponed !== undefined ? { po: entry.postponed } : {}),
           rv: entry.reactVersion,
           bv: entry.buildVersion,
           c: entry.createdAt,

package/src/cache/document-cache.ts

@@ -24,6 +24,7 @@ import { mayNeedSSR } from "../rsc/ssr-setup.js";
 import { cacheKeyBase } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
 import { reportCacheError } from "./cache-error.js";
+import { observePhase, PHASES } from "../router/instrument.js";
 import {
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
   SEGMENT_FRAGMENT_RECOVERY_HEADER,
@@ -378,29 +379,44 @@ export function createDocumentCacheMiddleware<TEnv = any>(
 
         runBackground(requestCtx, async () => {
           try {
-            // Re-establish the request-context ALS around the background
-            // re-render: next() re-runs the full handler pipeline, and on
-            // workerd a waitUntil task runs detached from the request's I/O
-            // context, so a handler/component reading getRequestContext() would
-            // otherwise throw. Same fix as the route-level/use-cache background
-            // revalidation paths.
-            const fresh = await runWithRequestContext(requestCtx, () => next());
-            const directives = shouldCacheResponse(fresh);
-
-            if (directives && fresh.body) {
-              // Background revalidation: nothing streams to a client, so drain
-              // the fresh render fully before snapshotting tags (same
-              // render-complete barrier as the miss path).
-              const body = await new Response(fresh.body).arrayBuffer();
-              await store.putResponse!(
-                cacheKey,
-                new Response(body, fresh),
-                directives.sMaxAge!,
-                directives.staleWhileRevalidate,
-                collectRequestTags(requestCtx),
-              );
-              log(`[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`);
-            }
+            // Re-establish the request-context ALS around the whole background
+            // task: next() re-runs the full handler pipeline, and on workerd a
+            // waitUntil task runs detached from the request's I/O context, so a
+            // handler/component reading getRequestContext() would otherwise
+            // throw. Same fix as the route-level/use-cache background
+            // revalidation paths. The rango.background span (kind=
+            // document-revalidation) wraps the re-render AND the store write so
+            // the task's spans — the re-run's own rango.* set and the drain/put
+            // platform spans — nest under one explanatory parent instead of
+            // dangling under the ended foreground phases. Running the put
+            // inside the ALS matches the MISS path, where putResponse already
+            // executes within the foreground request context.
+            await runWithRequestContext(requestCtx, () =>
+              observePhase(
+                PHASES.background("document-revalidation"),
+                async () => {
+                  const fresh = await next();
+                  const directives = shouldCacheResponse(fresh);
+
+                  if (!directives || !fresh.body) return;
+
+                  // Background revalidation: nothing streams to a client, so
+                  // drain the fresh render fully before snapshotting tags
+                  // (same render-complete barrier as the miss path).
+                  const body = await new Response(fresh.body).arrayBuffer();
+                  await store.putResponse!(
+                    cacheKey,
+                    new Response(body, fresh),
+                    directives.sMaxAge!,
+                    directives.staleWhileRevalidate,
+                    collectRequestTags(requestCtx),
+                  );
+                  log(
+                    `[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`,
+                  );
+                },
+              ),
+            );
           } catch (error) {
             // Pass requestCtx explicitly: this runs in a detached waitUntil task
             // where the ALS context is gone, so onError only fires if we hand it

package/src/cache/read-through-swr.ts

@@ -37,13 +37,14 @@ export interface ReadThroughItemConfig<T> {
   /** Execute the underlying function/loader on miss or revalidation */
   execute: () => Promise<T>;
   /**
-   * Optional wrapper applied to execute() ONLY on the background
-   * stale-revalidation path (not the foreground miss, where the caller's context
-   * is already established). Used to re-establish the request-context ALS, which
-   * a detached waitUntil task loses on workerd. Defaults to calling execute()
-   * directly.
+   * Optional wrapper applied to the WHOLE background stale-revalidation task
+   * (execute + serialize + setItem) — not the foreground miss, where the
+   * caller's context is already established. Used to re-establish the
+   * request-context ALS, which a detached waitUntil task loses on workerd,
+   * and to open the rango.background span so the write is covered too.
+   * Defaults to running the task directly.
    */
-  wrapBackground?: (run: () => Promise<T>) => Promise<T>;
+  wrapBackground?: (run: () => Promise<void>) => Promise<void>;
   /** Serialize result for storage. Return null to skip caching. */
   serialize: (data: T) => Promise<string | null>;
   /** Deserialize cached value back to the original type */
@@ -111,20 +112,25 @@ export async function readThroughItem<T>(
 
       // Stale hit — return stale data, revalidate in background
       onStale?.(cached);
+      // The whole task — execute AND serialize/setItem — goes through
+      // wrapBackground so the ALS re-establishment and the rango.background
+      // span cover the write too (a slow or failing store write is part of
+      // the revalidation, not an untraced tail). The foreground miss below
+      // stays unwrapped: its context is already established.
+      const revalidateTask = async () => {
+        const fresh = await execute();
+        const serialized = await serialize(fresh);
+        if (serialized !== null) {
+          await setItem(key, serialized, storeOptions);
+        }
+      };
       runBackground(
         host,
         async () => {
           try {
-            // Re-establish the caller's context (request-context ALS) for the
-            // detached background execution; the foreground miss below calls
-            // execute() directly since its context is already established.
-            const fresh = await (wrapBackground
-              ? wrapBackground(execute)
-              : execute());
-            const serialized = await serialize(fresh);
-            if (serialized !== null) {
-              await setItem(key, serialized, storeOptions);
-            }
+            await (wrapBackground
+              ? wrapBackground(revalidateTask)
+              : revalidateTask());
           } catch (error) {
             reportCacheError(
               error,