@rangojs/router 0.4.2 → 0.4.3

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/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,

package/src/cloudflare/tracing.ts

@@ -1,10 +1,11 @@
 /**
  * Cloudflare custom-spans integration.
  *
- * Bridges the router's performance phases (request, middleware, action,
- * loaders, handler, render, ssr) onto Cloudflare Workers custom spans so they show
- * up in the trace waterfall and OpenTelemetry exports next to the platform's
- * automatic spans (KV reads, D1 queries, fetch calls), with correct nesting.
+ * Bridges the router's observable phases (request, middleware, action, loaders,
+ * handler, render, ssr, response, background) onto Cloudflare Workers custom
+ * spans so they show up in the trace waterfall and OpenTelemetry exports next
+ * to the platform's automatic spans (KV reads, D1 queries, fetch calls), with
+ * correct nesting.
  *
  * Usage (Cloudflare preset only):
  *
@@ -27,12 +28,15 @@
  *
  * Span duration note: enterSpan ends a span when its callback's returned value
  * (or promise) settles. For the streaming phases (request/render/ssr) that is at
- * stream CONSTRUCTION, not body-drain. Instrumentation is best-effort and never
- * wraps or buffers the response body, so it cannot regress streaming or latency.
- * A loader/Suspense child that resolves mid-stream therefore keeps a rango.loader
- * span that can extend past its render parent — overlapping spans are valid. Uses
- * only the typed enterSpan API; spans bound work up to stream-handoff, matching
- * the co-emitted perf metric.
+ * stream CONSTRUCTION, not body-drain; rango.response marks that handoff
+ * boundary explicitly (it wraps only response finalization, never the body).
+ * Instrumentation is best-effort and never wraps or buffers the response body,
+ * so it cannot regress streaming or latency. A loader/Suspense child that
+ * resolves mid-stream therefore keeps a rango.loader span that can extend past
+ * its render parent — overlapping spans are valid. Uses only the typed enterSpan
+ * API; spans bound work up to stream-handoff, matching the co-emitted perf
+ * metric. On deployed Workers a rango.response span may report 0 ms (non-I/O
+ * timers are frozen); its position and attributes are the value.
  */
 
 import { _getRequestContext } from "../server/request-context.js";
@@ -91,8 +95,8 @@ const cloudflareSpanRunner: SpanRunner = (name, fn) => {
 /**
  * Create the tracing config for a Cloudflare 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 same slot on any platform
  *   with an OpenTelemetry SDK.

package/src/router/instrument.ts

@@ -5,13 +5,11 @@
  * The router exposes the same work on three surfaces, and the rule is: each
  * surface has exactly one owner here, so they cannot drift.
  *
- *   - observePhase(): a span of work. Co-emits the `debugPerformance` perf
- *     metric (metrics store -> [RSC Perf] timeline + Server-Timing) AND the
- *     platform span (tracing runner -> Cloudflare custom spans / OTel). From one
- *     wrap site, so the span set is always a subset of the perf phases and the
- *     two can't disagree. Phases that meter their own perf metric with a finer
- *     decomposition (request, middleware) pass `metric: false` and get the span
- *     only — still co-located, still one owner per surface.
+ *   - observePhase(): a span of work. From one wrap site, emits the platform
+ *     span (tracing runner -> Cloudflare custom spans / OTel) and, when the
+ *     phase has one, its `debugPerformance` metric (metrics store -> [RSC Perf]
+ *     timeline + Server-Timing). Phases that meter their own perf metric with a
+ *     finer decomposition, or are deliberately span-only, pass `metric: false`.
  *   - observeEvent(): a discrete fact (TelemetrySink): cache decisions,
  *     revalidation decisions, handler errors, timeouts, origin rejections.
  *     Event-shaped, not phase-shaped — derived from the same call sites but a
@@ -85,6 +83,16 @@ function currentRouteName(): string | undefined {
     : undefined;
 }
 
+/**
+ * The detached background lanes wrapped by the rango.background span (the
+ * `rango.background.kind` attribute). One name per task execution boundary.
+ */
+export type BackgroundTaskKind =
+  | "shell-capture"
+  | "document-revalidation"
+  | "loader-revalidation"
+  | "use-cache-revalidation";
+
 /**
  * The router's observable phases. One definition per phase keeps the `rango.*`
  * span names, perf-metric labels, and identifying attributes from spreading
@@ -176,6 +184,43 @@ export const PHASES = {
     tracePhase: "ssr",
     spanName: "rango.ssr",
   } as PhaseSpec,
+
+  /**
+   * One detached background task (waitUntil work that outlives the response):
+   * a PPR shell capture or an SWR background revalidation. The wrapper is the
+   * explanatory parent for everything the task does — the platform's automatic
+   * KV/fetch/cache spans, and (for the revalidation lanes) the re-run's own
+   * rango.* phase spans — so post-handoff work never appears as orphan spans
+   * dangling under an ended foreground phase. `kind` identifies the lane.
+   * Span only (metric:false): the perf timeline is finalized with the
+   * response, so a background metric could never reach it. The shell-capture
+   * lane keeps its INNER phase spans suppressed (derived context strips
+   * _tracing — a capture re-render duplicating the foreground's span set was
+   * the original #670 leak); the revalidation lanes keep theirs, nested here.
+   */
+  background: (kind: BackgroundTaskKind): PhaseSpec => ({
+    metric: false,
+    tracePhase: "background",
+    spanName: "rango.background",
+    attributes: { "rango.background.kind": kind },
+  }),
+
+  /** Final response construction + host handoff: opened AFTER downstream
+   * middleware/core execution returns a Response, wrapping only finalization
+   * (redirect interception/guarding, Server-Timing mutation, final response
+   * selection) and ending immediately before the router handler returns the
+   * response to the host. Handoff-bound, never drain-bound — it must never
+   * read, tee, buffer, or await response.body, so it cannot regress streaming.
+   * At most one per traced request; absent when the request throws before a
+   * response exists. Span only (metric:false) — a co-emitted metric would
+   * circularly mutate the Server-Timing header this phase itself finalizes.
+   * On Cloudflare it may report 0 ms (non-I/O timers are frozen); its position
+   * and attributes (status/mode/body kind, set by the handler) are the value. */
+  response: {
+    metric: false,
+    tracePhase: "response",
+    spanName: "rango.response",
+  } as PhaseSpec,
 } as const;
 
 /** Apply a phase spec's static attributes to a span (the no-op span ignores them). */
@@ -209,14 +254,15 @@ function recordPhaseMetric(
  * returns a promise both the metric duration and the span end when it settles.
  *
  * This is the ONLY phase primitive: every phase (request/middleware/action/
- * loader/handler/render/ssr) is construction-bound — the span and metric settle
- * when fn's own work completes (for the streaming phases, when the RSC/HTML
- * stream is constructed, NOT when the body drains). Instrumentation is strictly
- * best-effort: it never wraps or buffers the response and adds no work on the
- * streaming path, so it cannot regress response latency or streaming. A loader
- * that resolves while the body streams therefore keeps a rango.loader span that
- * may extend past its render parent — overlapping spans are valid; the loader
- * really did take that long.
+ * loader/handler/render/ssr/response/background) settles when fn's own work
+ * completes. For streaming phases that means when the RSC/HTML stream is
+ * constructed, NOT when the body drains; for response, when finalization hands
+ * the stream to the host. Instrumentation is strictly best-effort: it never
+ * wraps or buffers the response and adds no work on the streaming path, so it
+ * cannot regress response latency or streaming. A loader that resolves while
+ * the body streams therefore keeps a rango.loader span that may extend past its
+ * render parent — overlapping spans are valid; the loader really did take that
+ * long.
  *
  * Reads the metrics store + tracing off the RequestContext ALS, which is active
  * for the WHOLE request — contrast observeEvent, which reads the RouterContext

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

@@ -26,6 +26,7 @@ import {
   _getRequestContext,
   runWithRequestContext,
 } from "../../server/request-context.js";
+import { observePhase, PHASES } from "../instrument.js";
 import { sortedRouteParams } from "../../cache/cache-key-utils.js";
 import {
   resolveTtl,
@@ -328,7 +329,17 @@ function executeLoaderData<TEnv>(
       setItem: (k, v, o) => store.setItem!(k, v, o),
       key,
       execute: () => runMiss(loaderEntry.loader),
-      wrapBackground: (run) => runWithRequestContext(requestCtxForExecute, run),
+      // The rango.background span (kind=loader-revalidation) wraps the WHOLE
+      // stale revalidation — the re-execution AND the serialize/setItem write
+      // (read-through-swr routes the full task through wrapBackground) — so
+      // the loader's rango.loader span, its fetch/KV platform spans, and the
+      // store write all nest under one explanatory parent instead of dangling
+      // under the ended foreground phases. Inside runWithRequestContext so
+      // observePhase can read tracing on workerd (ALS detaches in waitUntil).
+      wrapBackground: (run) =>
+        runWithRequestContext(requestCtxForExecute, () =>
+          observePhase(PHASES.background("loader-revalidation"), run),
+        ),
       serialize: (d) => codec.serializeResult(d),
       deserialize: (v) => codec.deserializeResult(v),
       storeOptions: { ttl, swr, tags },

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

@@ -33,6 +33,7 @@ import {
   isTraceActive,
 } from "../logging.js";
 import { resolveLoaderData } from "./loader-cache.js";
+import { entryLoadingMasksLoaders } from "./loader-mask.js";
 import {
   handleHandlerResult,
   warnOnStreamedResponse,
@@ -206,6 +207,15 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   // onError/loader.error. isPartial flags the reporting phase accordingly.
   const errorContext = { ...buildLoaderErrorContext(ctx), isPartial: true };
 
+  // PPR lane decision, same rule as the fresh funnel (fresh.ts): an entry
+  // without renderable loading() puts its loaders on the BAKE lane. The key
+  // must thread through EVERY resolveLoaderData funnel — omitting it here made
+  // a capture-active context whole-container-mask every loader on this path
+  // (a never-settling promise for a loader that should have executed).
+  // Outside capture the key only activates the _shellLoaderSeed overlay,
+  // which document-only serveShellHit seeds — inert for partial requests.
+  const bakeLane = !entryLoadingMasksLoaders(entry.loading);
+
   const loadersToRun = revalidationChecks.filter((c) => c.shouldRun);
   const segments: ResolvedSegment[] = loadersToRun.map(
     ({ loaderEntry, loader, segmentId, index }) => ({
@@ -218,7 +228,12 @@ export async function resolveLoadersWithRevalidation<TEnv>(
       loaderId: loader.$$id,
       loaderData: deps.wrapLoaderPromise(
         runInsideLoaderScope(() =>
-          resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+          resolveLoaderData(
+            loaderEntry,
+            ctx,
+            ctx.pathname,
+            bakeLane ? segmentId : null,
+          ),
         ),
         entry,
         segmentId,

package/src/router/telemetry-otel.ts

@@ -6,10 +6,10 @@
  *   - createOTelTracing(tracer): the OTel adapter for the `tracing` SLOT — the
  *     canonical phase-span layer. It bridges observePhase's callback boundary
  *     onto OTel's callback-bound `startActiveSpan`, so the router's phase spans
- *     (rango.request/middleware/loader/render/ssr) nest by async context and the
- *     loader's own OTel spans (db/fetch) land under rango.loader. This is the
- *     OTel equivalent of createCloudflareTracing — pass it to
- *     `createRouter({ tracing })`.
+ *     (rango.request/middleware/action/loader/handler/render/ssr/response/
+ *     background) nest by async context and the loader's own OTel spans
+ *     (db/fetch) land under rango.loader. This is the OTel equivalent of
+ *     createCloudflareTracing — pass it to `createRouter({ tracing })`.
  *
  *   - createOTelSink(tracer): the OTel adapter for the `telemetry` SLOT — a
  *     TelemetrySink for the EVENT-shaped facts (handler errors, cache decisions,

package/src/router/timeout.ts

@@ -11,7 +11,18 @@ export interface RouterTimeouts {
   actionMs?: number;
   /** Timeout for initial render/response production (ms). */
   renderStartMs?: number;
-  /** Timeout for idle streaming after render starts (ms). Reserved for PR 2. */
+  /**
+   * Timeout for idle streaming after the response is handed off (ms): when no
+   * chunk flows to the client for this long, the body stream is errored with a
+   * RouterTimeoutError ("stream-idle") and the source render is canceled —
+   * bounding hangs from never-settling promises embedded in the payload.
+   * END-TO-END semantics: a stalled slow client counts as idle the same as a
+   * wedged producer, so pick generous budgets (seconds). Opt-in (unset =
+   * unbounded, and the `timeout` shorthand deliberately does not apply);
+   * onTimeout does NOT fire — no replacement Response can be served
+   * mid-stream — the trip reports via onError + the request.timeout event.
+   * Enforcement: rsc/stream-idle.ts, wired at the handler's response tail.
+   */
   streamIdleMs?: number;
 }
 

package/src/router/tracing.ts

@@ -1,11 +1,12 @@
 /**
  * Span tracing hook (platform-agnostic).
  *
- * The core router emits its existing performance phases (request, middleware, action,
- * loaders, render, ssr) as spans by calling traceSpan() at a small set of
- * execution boundaries. When no tracing is configured the call is a direct
- * pass-through: fn is invoked with a no-op span, with no wrapper and no
- * allocation, so a non-traced request behaves exactly as before.
+ * The core router emits its observable phases (request, middleware, action,
+ * loaders, handler, render, ssr, response, background) as spans by calling
+ * traceSpan() at a small set of execution boundaries. When no tracing is
+ * configured the call is a direct pass-through: fn is invoked with a no-op
+ * span, with no wrapper and no allocation, so a non-traced request behaves
+ * exactly as before.
  *
  * A platform integration supplies a SpanRunner that wraps fn in a real span.
  * Two runners ship: the Cloudflare one (createCloudflareTracing in
@@ -29,7 +30,10 @@
  * useLoader, plus the fetchable path), rango.handler (span-only, one per segment
  * route/layout handler execution; the handler:<id> perf metric is owned by the
  * track() at the call site), rango.render (render:total:<route>; normal AND
- * action-revalidation renders), rango.ssr (ssr:render-html).
+ * action-revalidation renders), rango.ssr (ssr:render-html), rango.response
+ * (span-only; final response construction + host handoff — the explicit
+ * stream-handoff marker), and rango.background (span-only; detached work, see
+ * below).
  *
  * Span-duration caveat (best-effort, never buffers): a span ends when its
  * callback's value (or promise) settles. For the streaming phases (request,
@@ -40,6 +44,19 @@
  * rango.loader span that can extend past its render parent; overlapping spans are
  * valid (the loader really did take that long). Phase spans bound the work up to
  * stream-handoff, which is also what the co-emitted perf metric measures.
+ * rango.response makes that handoff boundary explicit: it wraps only response
+ * finalization (redirect interception/guarding, Server-Timing mutation, final
+ * response selection) after downstream execution returns, ending immediately
+ * before the handler returns the Response to the host. It is handoff-bound,
+ * never drain-bound — it never reads, tees, or awaits response.body, and it is
+ * absent when the request throws before a response exists.
+ *
+ * rango.background wraps DETACHED work (waitUntil tasks that outlive the
+ * response): PPR shell captures and SWR background revalidations. It is the
+ * explanatory parent for spans those tasks produce after the foreground
+ * phases ended — without it, post-handoff work reads as orphan spans dangling
+ * under an ended parent. See PHASES.background (instrument.ts) for the lane
+ * kinds and per-lane inner-span policy.
  *
  * Both shipped runners (Cloudflare, OTel) keep the core agnostic: the
  * platform-specific bridge lives at the edge behind the SpanRunner contract.
@@ -68,18 +85,17 @@ export type TracePhase =
   | "loader"
   | "handler"
   | "render"
-  | "ssr";
+  | "ssr"
+  | "response"
+  | "background";
 
-/** Per-phase span toggles. Omitted phases default to enabled. */
-export interface TracePhaseToggles {
-  request?: boolean;
-  middleware?: boolean;
-  action?: boolean;
-  loader?: boolean;
-  handler?: boolean;
-  render?: boolean;
-  ssr?: boolean;
-}
+/**
+ * Per-phase span toggles. Omitted phases default to enabled. Derived from
+ * TracePhase so a new phase cannot be silently missing here — the other phase
+ * lists in this file (ALL_PHASES_ON, resolveTracing) are exhaustiveness-checked
+ * by their Record<TracePhase, boolean> annotations.
+ */
+export type TracePhaseToggles = Partial<Record<TracePhase, boolean>>;
 
 /**
  * The option pair shared by every tracing factory (enabled master switch +
@@ -125,6 +141,8 @@ const ALL_PHASES_ON: Record<TracePhase, boolean> = {
   handler: true,
   render: true,
   ssr: true,
+  response: true,
+  background: true,
 };
 
 /**
@@ -153,6 +171,8 @@ export function resolveTracing(
           handler: spans.handler ?? true,
           render: spans.render ?? true,
           ssr: spans.ssr ?? true,
+          response: spans.response ?? true,
+          background: spans.background ?? true,
         }
       : ALL_PHASES_ON,
   };