@rangojs/router 0.4.2 → 0.4.3

package/dist/types/browser/prefetch/cache.d.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
@@ -91,7 +91,9 @@ export declare function isPrefetchCacheDisabled(): boolean;
  * - 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,
@@ -100,9 +102,10 @@ export declare function isPrefetchCacheDisabled(): boolean;
  *   `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 declare function buildPrefetchKey(prefix: string, targetUrl: URL): string;
 /**

package/dist/types/cache/read-through-swr.d.ts

@@ -25,13 +25,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 */

package/dist/types/cloudflare/tracing.d.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 { type RouterTracingConfig, type TracingToggleOptions } from "../router/tracing.js";
 /**
@@ -44,8 +48,8 @@ export type CloudflareTracingOptions = TracingToggleOptions;
 /**
  * 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/dist/types/router/instrument.d.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
@@ -59,6 +57,11 @@ export interface PhaseSpec {
      */
     lazyAttributes?: () => Record<string, string | number | boolean> | 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
@@ -99,6 +102,32 @@ export declare const PHASES: {
     /** SSR HTML render from the RSC stream. Colon-delimited like the other ssr:*
      * setup metrics (ssr:module-load / ssr:stream-mode). */
     readonly ssr: 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.
+     */
+    readonly background: (kind: BackgroundTaskKind) => PhaseSpec;
+    /** 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. */
+    readonly response: PhaseSpec;
 };
 /**
  * Instrument one unit of work: open its span AND (unless `metric: false`) record
@@ -108,14 +137,15 @@ export declare const PHASES: {
  * 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/dist/types/router/telemetry-otel.d.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/dist/types/router/timeout.d.ts

@@ -10,7 +10,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;
 }
 export type TimeoutPhase = "action" | "render-start" | "stream-idle";

package/dist/types/router/tracing.d.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.
@@ -58,17 +75,14 @@ export interface TraceSpan {
  */
 export type SpanRunner = <T>(name: string, fn: (span: TraceSpan) => T) => T;
 /** The router phases that can be wrapped in a span. */
-export type TracePhase = "request" | "middleware" | "action" | "loader" | "handler" | "render" | "ssr";
-/** 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;
-}
+export type TracePhase = "request" | "middleware" | "action" | "loader" | "handler" | "render" | "ssr" | "response" | "background";
+/**
+ * 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 +
  * per-phase span toggles). Extended by OTelTracingOptions,

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

@@ -4,9 +4,30 @@ export declare const MAX_ADMITTED_CAPTURES: number;
 export declare class CaptureQueueFullError extends Error {
     constructor();
 }
+/**
+ * Budget on how long a capture may WAIT in the queue before it is dropped
+ * instead of run. On workerd a queued capture rides the scheduling request's
+ * waitUntil, whose post-response lifetime is bounded (~30s): a capture that
+ * already burned 15s+ parked behind a slow predecessor would start its own
+ * up-to-15s attempt (captureTimeout) with no budget left and risk being
+ * killed mid-store-write. Dropping at the budget is safe — captures are
+ * best-effort by contract, and a later request re-probes the key (the drop
+ * does NOT mark backoff: the route is not doomed, the isolate was busy).
+ * Matches one attempt's SHELL_CAPTURE_MAX_WAIT_MS so wait + attempt fits the
+ * platform budget. Field-observed: a navigation-shell capture parked ~24s
+ * behind a predecessor's two-attempt cycle.
+ */
+export declare const CAPTURE_QUEUE_WAIT_BUDGET_MS: number;
+/** Thrown (async) when the queue wait exceeded the budget; the task never ran. */
+export declare class CaptureQueueWaitTimeoutError extends Error {
+    readonly waitedMs: number;
+    constructor(waitedMs: number);
+}
 /**
  * Run `task` after every previously enqueued capture has settled. Returns a
  * promise for THIS task's completion (rejections propagate to the caller —
  * the queue itself is insulated).
  */
-export declare function enqueueSerializedCapture(task: () => Promise<void>): Promise<void>;
+export declare function enqueueSerializedCapture(task: () => Promise<void>, opts?: {
+    maxQueueWaitMs?: number;
+}): Promise<void>;

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

@@ -125,10 +125,14 @@ export interface ShellCaptureDebugEvent {
      * - skip-backoff: the key is inside its refused-capture backoff window and
      *   the capture was not attempted
      * - skip-capacity: the isolate capture queue is full; a later request may retry
+     * - skip-queue-timeout: the capture waited past CAPTURE_QUEUE_WAIT_BUDGET_MS
+     *   behind other captures and was dropped unrun (no backoff — the route is
+     *   not doomed, the isolate was busy; a later request re-probes). Carries
+     *   queueWaitMs.
      * - backoff: the key entered (or escalated) backoff after a terminal
      *   no-shell — carries the new backoff state
      */
-    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "skip-capacity" | "backoff";
+    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "skip-capacity" | "skip-queue-timeout" | "backoff";
     /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
     attempt?: number;
     /** Wall-clock ms of the whole attempt (barrier + render + drain + put). */
@@ -157,6 +161,8 @@ export interface ShellCaptureDebugEvent {
     backoffFailures?: number;
     /** Ms remaining in the key's backoff window, when one exists. */
     backoffRemainingMs?: number;
+    /** Ms the capture waited in the serialized queue (skip-queue-timeout). */
+    queueWaitMs?: number;
 }
 /**
  * Debug sink for the capture pipeline, mirroring {@link CFCacheDebug}: `true`

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.4.3",
   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.4.3",
   "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)`: