@rangojs/router 0.0.0-experimental.127 → 0.0.0-experimental.129

package/dist/vite/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.127",
+  "version": "0.0.0-experimental.129",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/observability/SKILL.md

@@ -95,6 +95,31 @@ const router = createRouter({
 });
 ```
 
+On **Cloudflare Workers**, use `createCloudflareTracing` for the `tracing` slot
+instead — it emits the same phases as native Cloudflare custom spans (in the
+Workers trace waterfall, next to the automatic KV/D1/fetch spans), with no
+`@opentelemetry/api` dependency:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  tracing: createCloudflareTracing(), // all phases on by default
+  // tracing: createCloudflareTracing({ spans: { ssr: false } }), // toggle phases
+});
+```
+
+Both 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.
+
 Custom sinks implement `emit(event)`:
 
 ```typescript
@@ -112,7 +137,8 @@ const router = createRouter({
 ```
 
 Events include `request.start/end/error`, `loader.start/end/error`,
-`handler.error`, `cache.decision`, and `revalidation.decision`.
+`handler.error`, `cache.decision`, `revalidation.decision`, `request.timeout`,
+and `request.origin-rejected`.
 
 ## Debugging revalidation and stale data
 

package/skills/router-setup/SKILL.md

@@ -488,6 +488,18 @@ const router = createRouter({
 });
 ```
 
+```typescript
+// On Cloudflare Workers, swap the tracing factory for native custom spans
+// (no @opentelemetry/api dependency); the telemetry slot is unchanged.
+import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  tracing: createCloudflareTracing(), // { spans: { ssr: false } } to toggle phases
+});
+```
+
 ```typescript
 // Custom sink
 const router = createRouter({

package/src/cloudflare/tracing.ts

@@ -2,9 +2,9 @@
  * Cloudflare custom-spans integration.
  *
  * Bridges the router's performance phases (request, middleware, action,
- * loaders, 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 parent-child nesting.
+ * 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.
  *
  * Usage (Cloudflare preset only):
  *
@@ -25,14 +25,17 @@
  * request behaves exactly as if tracing were off. Whether spans are actually
  * recorded is governed by the `observability`/tracing block in wrangler config.
  *
- * Span duration note: a phase span ends when its callback's returned value (or
- * promise) settles, which for the streaming phases (request/render/ssr) is when
- * the Response or HTML/RSC stream is *constructed*, not when the body finishes
- * draining. Loader/Suspense work that settles while the body streams therefore
- * extends past the parent span's end, and platform spans emitted during that
- * drain (deferred SSR, waitUntil-scheduled cache writes) are siblings of the
- * automatic request span rather than children of rango.*. Phase spans bound
- * setup-to-stream-handoff; they are not a full request-duration measure.
+ * Span duration note: enterSpan ends a span when its callback's returned value
+ * (or promise) settles. The streaming phases (request/render/ssr/middleware) are
+ * wrapped (in instrument.ts) so their callback awaits the response body's drain
+ * before settling — the constructed Response is handed to the client immediately,
+ * but the callback (hence the SPAN) stays open until the body finishes draining.
+ * So these spans cover the full streamed request and loader/Suspense children
+ * that resolve mid-stream nest under a still-open parent. This uses only the
+ * typed enterSpan API; no startActiveSpan/end. The perf METRICS (render:total,
+ * the middleware own-time, handler:total) stay construction-bound — they ship in
+ * the Server-Timing header, flushed before drain — so a span reads at least as
+ * long as its same-named metric, the difference being post-construction streaming.
  */
 
 import { _getRequestContext } from "../server/request-context.js";
@@ -92,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, render, and ssr phases; pass `spans` to turn individual
- * phases off.
+ * action, loaders, handler, render, and ssr 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

@@ -35,13 +35,16 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
 import { getRouterContext } from "./router-context.js";
 import { resolveSink, safeEmit, type TelemetryEvent } from "./telemetry.js";
 import { appendMetric } from "./metrics.js";
+import { type MetricsStore } from "../server/context.js";
 import {
   NOOP_TRACE_SPAN,
   traceSpan,
   runThenSettle,
   type TracePhase,
   type TraceSpan,
+  type ResolvedTracing,
 } from "./tracing.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
 /**
  * Perf-metric boundary for a phase, or `false` for span-only. `false` means the
@@ -63,6 +66,25 @@ export interface PhaseSpec {
   spanName: string;
   /** Span attributes set automatically when the span opens. */
   attributes?: Record<string, string | number | boolean>;
+  /**
+   * Span attributes resolved AFTER the wrapped work runs (so they can read state
+   * that only exists once the work is underway, e.g. the matched route name).
+   * Applied for streaming phases once fn has constructed its value. Return
+   * undefined to add nothing.
+   */
+  lazyAttributes?: () => Record<string, string | number | boolean> | undefined;
+}
+
+/**
+ * The matched route name for the current request, or undefined when there is no
+ * named route (unmatched / auto-generated). Shared by the render phase's metric
+ * label and its rango.route span attribute so the two can't disagree.
+ */
+function currentRouteName(): string | undefined {
+  const routeName = _getRequestContext()?._routeName;
+  return routeName && !isAutoGeneratedRouteName(routeName)
+    ? routeName
+    : undefined;
 }
 
 /**
@@ -112,6 +134,18 @@ export const PHASES = {
     attributes: { "rango.loader_id": id },
   }),
 
+  /** One segment route/layout handler execution (the component/handler that
+   * produces a segment). Span only — the perf metric (handler:<id>) is owned by
+   * the legacy track() at the same call site, so observePhase here adds the
+   * rango.handler span without double-recording. `id` is the segment id, carried
+   * as the rango.segment_id attribute to match the handler:<id> perf row. */
+  handler: (id: string): PhaseSpec => ({
+    metric: false,
+    tracePhase: "handler",
+    spanName: "rango.handler",
+    attributes: { "rango.segment_id": id },
+  }),
+
   /** Whole render phase: match + serialize + SSR. The metric label is resolved
    * lazily at record time (after match has set the route name) so the perf
    * timeline shows WHICH route rendered: `render:total:<routeName>`, falling back
@@ -119,14 +153,20 @@ export const PHASES = {
   render: {
     metric: {
       label: () => {
-        const routeName = _getRequestContext()?._routeName;
-        return routeName && !isAutoGeneratedRouteName(routeName)
-          ? `render:total:${routeName}`
-          : "render:total";
+        const routeName = currentRouteName();
+        return routeName ? `render:total:${routeName}` : "render:total";
       },
     },
     tracePhase: "render",
     spanName: "rango.render",
+    // Tag the render span with the matched route so the Cloudflare/OTel waterfall
+    // shows WHICH route rendered (rango.render + rango.route=index), resolved
+    // after match has run. Kept an attribute (not baked into the span name) so the
+    // span name stays low-cardinality and aggregatable across routes.
+    lazyAttributes: () => {
+      const routeName = currentRouteName();
+      return routeName ? { "rango.route": routeName } : undefined;
+    },
   } as PhaseSpec,
 
   /** SSR HTML render from the RSC stream. Colon-delimited like the other ssr:*
@@ -138,6 +178,29 @@ export const PHASES = {
   } as PhaseSpec,
 } as const;
 
+/** Apply a phase spec's static attributes to a span (the no-op span ignores them). */
+function applyAttributes(
+  span: TraceSpan,
+  attributes: Record<string, string | number | boolean>,
+): void {
+  for (const key in attributes) span.setAttribute(key, attributes[key]);
+}
+
+/**
+ * Record a phase's perf metric for the interval [start, now]. The label may be
+ * lazy (resolved here, e.g. render:total needs the route name that match sets
+ * partway through the wrapped work).
+ */
+function recordPhaseMetric(
+  store: MetricsStore,
+  metric: Exclude<PhaseMetric, false>,
+  start: number,
+): void {
+  const label =
+    typeof metric.label === "function" ? metric.label() : metric.label;
+  appendMetric(store, label, start, performance.now() - start, metric.depth);
+}
+
 /**
  * Instrument one unit of work: open its span AND (unless `metric: false`) record
  * its perf metric, from a single wrap site. fn is invoked exactly once with the
@@ -145,6 +208,12 @@ export const PHASES = {
  * unchanged and thrown errors / rejected promises propagate unchanged. When fn
  * returns a promise both the metric duration and the span end when it settles.
  *
+ * This is the boundary for NON-streaming phases (action, loader): both the span
+ * and the metric settle when their own work completes. Streaming phases (request,
+ * middleware, render, ssr) use observeRequestPhase / observeStreamingPhase, where
+ * the SPAN is held open until body-drain (valid tree) while the perf metric is
+ * still recorded at construction (Server-Timing parity).
+ *
  * Reads the metrics store + tracing off the RequestContext ALS, which is active
  * for the WHOLE request — contrast observeEvent, which reads the RouterContext
  * ALS (entered later, during match).
@@ -166,7 +235,7 @@ export function observePhase<T>(
   const wrapped: (span: TraceSpan) => T =
     attributes && tracing
       ? (span) => {
-          for (const key in attributes) span.setAttribute(key, attributes[key]);
+          applyAttributes(span, attributes);
           return fn(span);
         }
       : fn;
@@ -182,13 +251,196 @@ export function observePhase<T>(
   // failed loader/render still shows its timing in the perf report (parity with
   // the old track().finally() path it replaced).
   const start = performance.now();
-  return runThenSettle(runSpan, () => {
-    // The label may be lazy (resolved at record time, e.g. render:total needs the
-    // route name that match sets partway through the wrapped work).
-    const label =
-      typeof metric.label === "function" ? metric.label() : metric.label;
-    appendMetric(store, label, start, performance.now() - start, metric.depth);
+  return runThenSettle(runSpan, () => recordPhaseMetric(store, metric, start));
+}
+
+/**
+ * Re-stream `response`'s body through a pass-through that fires `onDrain` exactly
+ * once when the body finishes — on natural end, a stream error, or a client
+ * cancel (so a span can never leak on an aborted response). A bodyless response
+ * fires immediately. Only used while instrumentation is active, so the per-chunk
+ * relay cost never touches an untraced request.
+ */
+function instrumentResponseDrain(
+  response: Response,
+  onDrain: () => void,
+): Response {
+  // WS-upgrade responses (status 101 / workerd `webSocket` property) must never
+  // be reconstructed: `new Response(body, { status: 101 })` throws and a copy
+  // drops the non-standard webSocket handoff (the invariant every other Response
+  // reconstruction site honors). A bodyless response has nothing to drain.
+  const source = response.body;
+  if (!source || isWebSocketUpgradeResponse(response)) {
+    onDrain();
+    return response;
+  }
+  let fired = false;
+  const fire = (): void => {
+    if (fired) return;
+    fired = true;
+    onDrain();
+  };
+  const reader = source.getReader();
+  const wrapped = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          controller.close();
+          fire();
+          return;
+        }
+        controller.enqueue(value);
+      } catch (error) {
+        controller.error(error);
+        fire();
+      }
+    },
+    cancel(reason) {
+      fire();
+      return reader.cancel(reason);
+    },
   });
+  return new Response(wrapped, response);
+}
+
+/**
+ * Shared engine for the streaming phases (request, middleware, render, ssr). It
+ * opens the span, runs fn, records the phase's perf metric at CONSTRUCTION (so it
+ * still reaches the Server-Timing header / [RSC Perf] table, both built before
+ * the body drains), hands the constructed value to the caller via a side channel
+ * (streaming preserved), then holds the span open until `drain` resolves. The
+ * SPAN therefore ends at body-drain — keeping the trace tree valid (a loader
+ * child that resolves mid-stream ends before its parent) — while the perf metric
+ * stays the construction work-time. `onDeliver` lets the request phase instrument
+ * the final body before handing it back; `onError` lets it release the barrier on
+ * failure. Fire-and-forget: the value reaches the caller via the returned
+ * promise, so the span promise's rejection is swallowed (already surfaced there).
+ */
+function runDrainBoundPhase<R>(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => R | Promise<R>,
+  tracing: ResolvedTracing | undefined,
+  store: MetricsStore | undefined,
+  drain: Promise<void>,
+  onDeliver: (value: R) => R,
+  onError?: () => void,
+): Promise<R> {
+  let deliver!: (value: R) => void;
+  let reject!: (error: unknown) => void;
+  const delivered = new Promise<R>((res, rej) => {
+    deliver = res;
+    reject = rej;
+  });
+
+  const start = performance.now();
+  const attributes = spec.attributes;
+  const metric = spec.metric;
+  const record = (): void => {
+    if (store && metric !== false) recordPhaseMetric(store, metric, start);
+  };
+  const spanCallback = async (span: TraceSpan): Promise<void> => {
+    if (attributes && tracing) applyAttributes(span, attributes);
+    let value: R;
+    try {
+      value = await fn(span);
+    } catch (error) {
+      record(); // a failed phase still shows its (construction) timing
+      onError?.();
+      reject(error);
+      throw error; // settle the span with the error, at construction
+    }
+    // Late attributes (e.g. rango.route) — resolved now that the work has run,
+    // so they can read state like the matched route name that match sets midway.
+    const lazy =
+      tracing && spec.lazyAttributes ? spec.lazyAttributes() : undefined;
+    if (lazy) applyAttributes(span, lazy);
+    record(); // construction-bound metric, before the response/header is built
+    deliver(onDeliver(value));
+    await drain; // hold the span open until the response body drains
+  };
+
+  traceSpan(tracing, spec.tracePhase, spec.spanName, spanCallback).catch(
+    () => {},
+  );
+  return delivered;
+}
+
+/**
+ * The request phase (rango.request, metric:false). Owns the drain barrier: it
+ * runs fn to construct the final Response, instruments that Response's body so
+ * the barrier resolves at drain, hands the Response to the caller immediately
+ * (streaming preserved), and holds the span open until the body drains. Every
+ * streaming inner phase awaits the same barrier (via observeStreamingPhase), so
+ * the request/middleware/render/ssr chain ends at body-drain together and the
+ * trace tree is valid (no child span outlives its parent). The perf metrics
+ * (render:total, …) are recorded at construction so they still reach the
+ * Server-Timing header; only the SPANS are drain-bound. ctx.waitUntil holds the
+ * worker alive until drain so the span end runs. Pass-through when no surface is
+ * active.
+ */
+export function observeRequestPhase(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => Promise<Response>,
+): Promise<Response> {
+  const reqCtx = _getRequestContext();
+  const store = reqCtx?._metricsStore;
+  const tracing = reqCtx?._tracing;
+
+  if ((!store && !tracing) || !reqCtx) return fn(NOOP_TRACE_SPAN);
+
+  let resolveDrain!: () => void;
+  const finalDrain = new Promise<void>((resolve) => {
+    resolveDrain = resolve;
+  });
+  reqCtx._finalDrain = finalDrain;
+
+  // Keep the worker alive until the body drains, so the drain-bound span end
+  // (and the inner phases' settle) runs before the runtime can reclaim it.
+  const ec = reqCtx.executionContext;
+  if (typeof ec?.waitUntil === "function") ec.waitUntil(finalDrain);
+
+  return runDrainBoundPhase<Response>(
+    spec,
+    fn,
+    tracing,
+    store,
+    finalDrain,
+    (response) => instrumentResponseDrain(response, resolveDrain),
+    resolveDrain, // release the barrier if fn fails before constructing a body
+  );
+}
+
+/**
+ * A streaming inner phase (rango.middleware / render / ssr). Its SPAN settles
+ * when the request's final response body drains (the barrier owned by
+ * observeRequestPhase), not when fn returns the constructed stream — so
+ * loader/Suspense children that resolve mid-stream nest under a still-open
+ * parent. fn's result is delivered at construction (streaming preserved) and the
+ * perf metric is recorded at construction (Server-Timing parity). Falls back to
+ * observePhase (construction-bound span) when there is no barrier — a
+ * non-streaming request, or instrumentation off.
+ */
+export function observeStreamingPhase<R>(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => R | Promise<R>,
+): Promise<R> {
+  const reqCtx = _getRequestContext();
+  const store = reqCtx?._metricsStore;
+  const tracing = reqCtx?._tracing;
+  const finalDrain = reqCtx?._finalDrain;
+
+  if ((!store && !tracing) || !finalDrain) {
+    return Promise.resolve(observePhase(spec, fn));
+  }
+  return runDrainBoundPhase<R>(
+    spec,
+    fn,
+    tracing,
+    store,
+    finalDrain,
+    (value) => value,
+  );
 }
 
 /**

package/src/router/middleware.ts

@@ -19,7 +19,7 @@ import {
 } from "../redirect-origin.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { appendMetric, createMetricsStore } from "./metrics.js";
-import { observePhase, PHASES } from "./instrument.js";
+import { observeStreamingPhase, PHASES } from "./instrument.js";
 import { stripInternalParams } from "./handler-context.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
@@ -487,7 +487,7 @@ export async function executeMiddleware<TEnv>(
     // when neither surface is active.
     let result: Response | void;
     try {
-      result = await observePhase(PHASES.middleware(metricLabel), () =>
+      result = await observeStreamingPhase(PHASES.middleware(metricLabel), () =>
         entry.handler(ctx, wrappedNext),
       );
     } catch (error) {
@@ -664,7 +664,7 @@ export async function executeInterceptMiddleware<TEnv>(
 
     let result: Response | void;
     try {
-      result = await observePhase(PHASES.middleware(label), () =>
+      result = await observeStreamingPhase(PHASES.middleware(label), () =>
         middleware(ctx, guardedNext),
       );
     } catch (error) {

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

@@ -30,6 +30,7 @@ import {
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
 import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+import { observePhase, PHASES } from "../instrument.js";
 import {
   track,
   RangoContext,
@@ -258,7 +259,9 @@ export async function resolveSegment<TEnv>(
         !context.build && entry.liveHandler ? entry.liveHandler : entry.handler;
       const doneRouteHandler = track(`handler:${entry.id}`, 2);
       if (entry.loading) {
-        const result = handleHandlerResult(handler(context));
+        const result = handleHandlerResult(
+          observePhase(PHASES.handler(entry.id), () => handler(context)),
+        );
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, entry.id);
           result.finally(doneRouteHandler).catch(() => {});
@@ -280,7 +283,9 @@ export async function resolveSegment<TEnv>(
           component = result;
         }
       } else {
-        component = handleHandlerResult(await handler(context));
+        component = handleHandlerResult(
+          await observePhase(PHASES.handler(entry.id), () => handler(context)),
+        );
         doneRouteHandler();
       }
     }
@@ -505,7 +510,11 @@ export async function resolveParallelEntry<TEnv>(
         parallelEntry.loading !== undefined && parallelEntry.loading !== false;
       if (hasLoadingFallback) {
         const result =
-          typeof handler === "function" ? handler(context) : handler;
+          typeof handler === "function"
+            ? observePhase(PHASES.handler(`${parallelEntry.id}.${slot}`), () =>
+                handler(context),
+              )
+            : handler;
         if (result instanceof Promise) {
           result.finally(doneParallelHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
@@ -527,7 +536,12 @@ export async function resolveParallelEntry<TEnv>(
         }
       } else {
         component =
-          typeof handler === "function" ? await handler(context) : handler;
+          typeof handler === "function"
+            ? await observePhase(
+                PHASES.handler(`${parallelEntry.id}.${slot}`),
+                () => handler(context),
+              )
+            : handler;
         doneParallelHandler();
       }
     }

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

@@ -23,6 +23,7 @@ import type { ResolvedSegment, ErrorInfo, HandlerContext } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
+import { observePhase, PHASES } from "../instrument.js";
 import type { TelemetrySink } from "../telemetry.js";
 import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
@@ -130,11 +131,15 @@ export async function resolveLayoutComponent<TEnv>(
   entry: EntryData,
   context: HandlerContext<any, TEnv>,
 ): Promise<ReactNode> {
-  const component = await tryStaticHandler(entry, entry.shortCode);
-  if (component !== undefined) return component;
-  return typeof entry.handler === "function"
-    ? handleHandlerResult(await entry.handler(context))
-    : (entry.handler as ReactNode);
+  // rango.handler span for this layout/cache handler (the perf metric is owned
+  // by the track("handler:<id>") at the call site; this adds the span only).
+  return observePhase(PHASES.handler(entry.id), async () => {
+    const component = await tryStaticHandler(entry, entry.shortCode);
+    if (component !== undefined) return component;
+    return typeof entry.handler === "function"
+      ? handleHandlerResult(await entry.handler(context))
+      : (entry.handler as ReactNode);
+  });
 }
 
 // ---------------------------------------------------------------------------

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

@@ -43,7 +43,7 @@ import {
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
-import { observeEvent } from "../instrument.js";
+import { observeEvent, observePhase, PHASES } from "../instrument.js";
 import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
 import {
   track,
@@ -793,12 +793,16 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
           ? routeEntry.liveHandler
           : routeEntry.handler;
       if (!routeEntry.loading) {
-        const result = handleHandlerResult(await handler(context));
+        const result = handleHandlerResult(
+          await observePhase(PHASES.handler(entry.id), () => handler(context)),
+        );
         doneHandler();
         return result;
       }
       if (!actionContext) {
-        const result = handleHandlerResult(handler(context));
+        const result = handleHandlerResult(
+          observePhase(PHASES.handler(entry.id), () => handler(context)),
+        );
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, routeEntry.id);
           result.finally(doneHandler).catch(() => {});
@@ -822,7 +826,9 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       debugLog("segment.action", "resolving action route with awaited value", {
         entryId: entry.id,
       });
-      const actionResult = handleHandlerResult(await handler(context));
+      const actionResult = handleHandlerResult(
+        await observePhase(PHASES.handler(entry.id), () => handler(context)),
+      );
       doneHandler();
       return {
         content: Promise.resolve(actionResult),

package/src/router/tracing.ts

@@ -26,16 +26,23 @@
  * metered directly), rango.middleware (span-only incl. intercept middleware;
  * pre/post metered directly), rango.action (action:<id>; server-action
  * execution, JS + no-JS/PE), rango.loader (loader:<id>; single metering site at
- * useLoader, plus the fetchable path), rango.render (render:total:<route>; normal AND
+ * 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).
  *
- * Span-duration caveat: a span ends when its callback's value (or promise)
- * settles. For the streaming phases (request/render/ssr) that is when the
- * Response / HTML / RSC stream is constructed, NOT when the body finishes
- * draining. Loader/Suspense work that settles during stream drain extends past
- * the parent span's end, so parent durations under-report streamed time and a
- * rango.loader child can end after its parent. This is the streaming + end-on-
- * settle contract, not a defect; phase spans bound setup-to-stream-handoff.
+ * Streaming-phase span lifetime: a span ends when its callback's value (or
+ * promise) settles. The streaming phases (request, middleware, render, ssr) are
+ * wrapped by observeRequestPhase / observeStreamingPhase (instrument.ts), whose
+ * callback hands the constructed Response/stream to the caller immediately
+ * (streaming preserved) but then awaits a request-scoped drain barrier, so the
+ * SPAN ends when the response BODY finishes draining, not at stream construction.
+ * That keeps span durations covering the real streamed work and the trace tree
+ * valid: a loader/Suspense child that resolves while the body streams ends before
+ * its now-drain-bound parent. The co-emitted perf METRIC (render:total, …) is
+ * still recorded at construction — it ships in the Server-Timing header, flushed
+ * before the body drains — so a streaming span legitimately reads longer than its
+ * same-named metric by the time the body spent streaming after construction.
  *
  * Both shipped runners (Cloudflare, OTel) keep the core agnostic: the
  * platform-specific bridge lives at the edge behind the SpanRunner contract.
@@ -62,6 +69,7 @@ export type TracePhase =
   | "middleware"
   | "action"
   | "loader"
+  | "handler"
   | "render"
   | "ssr";
 
@@ -71,6 +79,7 @@ export interface TracePhaseToggles {
   middleware?: boolean;
   action?: boolean;
   loader?: boolean;
+  handler?: boolean;
   render?: boolean;
   ssr?: boolean;
 }
@@ -107,6 +116,7 @@ const ALL_PHASES_ON: Record<TracePhase, boolean> = {
   middleware: true,
   action: true,
   loader: true,
+  handler: true,
   render: true,
   ssr: true,
 };
@@ -134,6 +144,7 @@ export function resolveTracing(
           middleware: spans.middleware ?? true,
           action: spans.action ?? true,
           loader: spans.loader ?? true,
+          handler: spans.handler ?? true,
           render: spans.render ?? true,
           ssr: spans.ssr ?? true,
         }

package/src/rsc/handler.ts

@@ -82,7 +82,12 @@ import {
   appendMetric,
   buildMetricsTiming,
 } from "../router/metrics.js";
-import { observePhase, observeEvent, PHASES } from "../router/instrument.js";
+import {
+  observePhase,
+  observeRequestPhase,
+  observeEvent,
+  PHASES,
+} from "../router/instrument.js";
 import {
   startSSRSetup,
   getSSRSetup,
@@ -496,11 +501,14 @@ export function createRSCHandler<
     // The "rango.request" span is opened inside the request context so the
     // Cloudflare runner can read executionContext.tracing, and so every nested
     // phase span (and the platform's automatic KV/D1/fetch spans) nests under
-    // it. metric:false — handler:total is metered directly below (a grand total
-    // incl. the pre-context bootstrap timings, finer than a single wrap). When
-    // tracing is off this is a direct pass-through.
+    // it. observeRequestPhase owns the drain barrier: it instruments the final
+    // response body so this span (and the streaming inner phases) stay open
+    // until the body drains, keeping the tree valid. metric:false — handler:total
+    // is metered directly below (a grand total incl. the pre-context bootstrap
+    // timings) and stays construction-bound (it ships as a Server-Timing header,
+    // flushed before drain). When no surface is active this is a pass-through.
     return runWithRequestContext(requestContext, () =>
-      observePhase(PHASES.request, async (span) => {
+      observeRequestPhase(PHASES.request, async (span) => {
         span.setAttribute("http.method", request.method);
         // The matched route template is not known until match() runs later, so
         // emit the concrete path as url.path (low-level), NOT http.route — the

package/src/rsc/rsc-rendering.ts

@@ -11,7 +11,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { appendMetric } from "../router/metrics.js";
-import { observePhase, PHASES } from "../router/instrument.js";
+import { observeStreamingPhase, PHASES } from "../router/instrument.js";
 import { getSSRSetup, isRscRequest } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
 import type { MatchResult } from "../types.js";
@@ -36,7 +36,7 @@ export function handleRscRendering<TEnv>(
   // same boundary (match -> serialize -> SSR), so the two surfaces agree.
   // Loaders kicked off during matching nest under the span; the SSR HTML pass
   // below opens "rango.ssr" the same way.
-  return observePhase(PHASES.render, () =>
+  return observeStreamingPhase(PHASES.render, () =>
     handleRscRenderingInner(
       ctx,
       request,
@@ -248,7 +248,7 @@ async function handleRscRenderingInner<TEnv>(
 
   // ssr-render-html metric + rango.ssr span from one boundary. render:total is
   // recorded by the observePhase wrapper around this function.
-  const htmlStream = await observePhase(PHASES.ssr, () =>
+  const htmlStream = await observeStreamingPhase(PHASES.ssr, () =>
     ssrModule.renderHTML(rscStream, {
       nonce,
       streamMode,

package/src/rsc/server-action.ts

@@ -20,7 +20,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { appendMetric } from "../router/metrics.js";
-import { observePhase, PHASES } from "../router/instrument.js";
+import { observeStreamingPhase, PHASES } from "../router/instrument.js";
 import type { RscPayload } from "./types.js";
 import {
   hasBodyContent,
@@ -270,7 +270,7 @@ export function revalidateAfterAction<TEnv>(
   // "render:total" AND opens "rango.render" from one boundary covering
   // matchPartial -> serialize, so the revalidation loaders' rango.loader spans
   // nest under a rango.render parent instead of dangling at the request root.
-  return observePhase(PHASES.render, () =>
+  return observeStreamingPhase(PHASES.render, () =>
     revalidateAfterActionInner(
       ctx,
       request,

package/src/server/request-context.ts

@@ -368,6 +368,16 @@ export interface RequestContext<
   /** @internal Resolved platform phase-span tracing for this request (Cloudflare or OTel) */
   _tracing?: ResolvedTracing;
 
+  /**
+   * @internal Drain barrier for streaming phase spans. The request phase
+   * (observeRequestPhase) sets this to a promise that resolves when the final
+   * response body finishes draining; the streaming inner phases
+   * (observeStreamingPhase: middleware/render/ssr) await it so their span AND
+   * perf metric end at body-drain rather than at stream construction. Undefined
+   * when neither the perf store nor tracing is active (no instrumentation).
+   */
+  _finalDrain?: Promise<void>;
+
   /** @internal Router basename for this request (used by redirect()) */
   _basename?: string;