@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

package/src/rsc/response-route-handler.ts

@@ -27,15 +27,10 @@ import {
   finalizeResponse,
   isCacheableStatus,
   buildRouteMiddlewareEntries,
-  mergeStubHeadersAndFinalize,
+  rewrapResponseRouteResponse,
 } from "./helpers.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 import { stringifyJsonRouteResult } from "./json-route-result.js";
-import {
-  EXTERNAL_REDIRECT_MARKER,
-  isExternalRedirect,
-  markExternalRedirect,
-} from "../redirect-origin.js";
 
 export interface ResponseRouteMatch {
   responseType: string;
@@ -104,48 +99,17 @@ export async function handleResponseRoute<TEnv>(
   const callHandler = async () => {
     const errorCtx = { request, url, env };
 
-    // Re-wrap a handler-returned Response through createResponseWithMergedHeaders
-    // so that stub headers (cookies, custom headers set via ctx.header()) are included.
-    // Use Headers (not Record<string, string>) to preserve duplicate entries like Set-Cookie.
-    const rewrapResponse = (result: Response) => {
-      // 204/205/304 are NOT short-circuited — they're valid for the Response
-      // constructor and must honor ctx.setStatus() overrides. Only upgrade
-      // responses (status 101 / `webSocket` property) bypass reconstruction.
-      if (isWebSocketUpgradeResponse(result)) {
-        return mergeStubHeadersAndFinalize(result);
-      }
-      const headers = new Headers();
-      result.headers.forEach((value, key) => {
-        // Never copy the reserved external-redirect marker off a handler result.
-        // It is not a trust signal -- the opt-in is the out-of-band brand below
-        // -- and a proxy-style route returning an attacker-controlled upstream
-        // response must not let a forged value ride through to the browser.
-        if (key.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
-        if (key.toLowerCase() === "set-cookie") {
-          headers.append(key, value);
-        } else {
-          headers.set(key, value);
-        }
-      });
-      const rewrapped = createResponseWithMergedHeaders(result.body, {
-        status: result.status,
-        headers,
-      });
-      // Transfer the out-of-band external brand only when the handler result is
-      // genuinely branded (a real redirect(url, { external: true })). A proxied
-      // upstream Response is never branded, so an attacker cannot opt a response
-      // route's redirect out of the same-origin guard by injecting the header.
-      if (isExternalRedirect(result)) {
-        markExternalRedirect(rewrapped);
-      }
-      return rewrapped;
-    };
-
     try {
-      const result = await (preview.handler as Function)(responseHandlerCtx);
+      let result: unknown;
+      try {
+        result = await (preview.handler as Function)(responseHandlerCtx);
+      } catch (error) {
+        if (!(error instanceof Response)) throw error;
+        result = error;
+      }
 
       if (result instanceof Response) {
-        return rewrapResponse(result);
+        return rewrapResponseRouteResponse(result);
       }
 
       // Handled before the MIME lookup (json is also a RESPONSE_TYPE_MIME key).

package/src/rsc/rsc-rendering.ts

@@ -17,7 +17,8 @@ import {
 } from "../cache/shell-snapshot.js";
 import { appendMetric } from "../router/metrics.js";
 import { observePhase, PHASES } from "../router/instrument.js";
-import { getSSRSetup, isRscRequest } from "./ssr-setup.js";
+import type { TraceSpan } from "../router/tracing.js";
+import { getSSRSetup, createSsrHtmlStage, isRscRequest } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
 import type { SSRModule } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
@@ -26,11 +27,15 @@ import {
   createSimpleRedirectResponse,
   attachLocationStateIfPresent,
 } from "./helpers.js";
+import { renderRscFlightStage, renderRscResponse } from "./render-pipeline.js";
 import type { HandlerContext } from "./handler-context.js";
 import { gateTransitions } from "./transition-gate.js";
 import { buildFullPayload } from "./full-payload.js";
 import {
   scheduleShellCapture,
+  resolveShellCaptureDebugSink,
+  takeCaptureDebugEventForTiming,
+  describeShellCaptureEvent,
   type ShellCaptureDescriptor,
 } from "./shell-capture.js";
 import {
@@ -43,7 +48,12 @@ import {
   hasShellFamily,
   warnShellStoreMissingOnce,
   warnPprNonceActiveOnce,
+  describeShellTailTiming,
+  publishShellTailTiming,
+  takeShellTailTimingForServerTiming,
+  type ShellTailTiming,
 } from "./shell-serve.js";
+import { lookupBuildShell } from "./shell-build-manifest.js";
 import { contextGet } from "../context-var.js";
 import {
   resolveSameOriginRedirect,
@@ -68,7 +78,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 observePhase(PHASES.render, (span) =>
     handleRscRenderingInner(
       ctx,
       request,
@@ -77,6 +87,7 @@ export function handleRscRendering<TEnv>(
       isPartial,
       handleStore,
       nonce,
+      span,
     ),
   );
 }
@@ -89,6 +100,7 @@ async function handleRscRenderingInner<TEnv>(
   isPartial: boolean,
   handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   nonce: string | undefined,
+  renderSpan: TraceSpan,
 ): Promise<Response> {
   const reqCtx = getRequestContext();
 
@@ -120,7 +132,8 @@ async function handleRscRenderingInner<TEnv>(
     !isPartial &&
     request.method === "GET" &&
     !url.searchParams.has("__prerender_collect") &&
-    !isRscRequest(request, url, false)
+    !isRscRequest(request, url, false) &&
+    !reqCtx._dynamic
   ) {
     const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry);
     if (pprConfig) {
@@ -139,6 +152,45 @@ async function handleRscRenderingInner<TEnv>(
       const activeNonce = nonce ?? contextGet(reqCtx._variables, nonceToken);
       const store = reqCtx._cacheStore;
       const key = buildShellKey(url);
+      // Dev Server-Timing mirror (issue #651): a capture runs AFTER its
+      // triggering response committed, so its outcome can only ride a LATER
+      // response's header. When the metrics surface is active
+      // (debugPerformance), fold the buffered terminal capture event for this
+      // key into THIS request's Server-Timing as `ppr-capture;dur=<attempt
+      // ms>;desc="<outcome + sizes + waits>"`. Consuming (read-and-clear)
+      // keeps one capture = one report. Dev-only: the buffer is only written
+      // in dev (see takeCaptureDebugEventForTiming), and production folds the
+      // whole branch away.
+      if (process.env.NODE_ENV !== "production" && reqCtx._metricsStore) {
+        const lastCapture = takeCaptureDebugEventForTiming(key);
+        if (lastCapture) {
+          appendMetric(
+            reqCtx._metricsStore,
+            "ppr:capture",
+            performance.now(),
+            lastCapture.attemptMs ?? 0,
+            undefined,
+            // attemptMs already rides as this entry's dur — drop it from desc.
+            describeShellCaptureEvent({ ...lastCapture, attemptMs: undefined }),
+          );
+        }
+        // Same mirror for the previous HIT's tail: its per-stage numbers
+        // (seed/match/handover/first-html/complete) finished after that
+        // response's headers were committed, so they ride THIS request's
+        // Server-Timing as `ppr:tail;dur=<complete ms>`.
+        const lastTail = takeShellTailTimingForServerTiming(key);
+        if (lastTail) {
+          appendMetric(
+            reqCtx._metricsStore,
+            "ppr:tail",
+            performance.now(),
+            lastTail.completeMs ?? 0,
+            undefined,
+            // completeMs already rides as this entry's dur — drop it from desc.
+            describeShellTailTiming({ ...lastTail, completeMs: undefined }),
+          );
+        }
+      }
       if (activeNonce !== undefined) {
         // Declared intent that cannot be honored deserves a diagnostic (unlike an
         // undeclared route, which is silent): a ppr route gated off by an active
@@ -169,16 +221,67 @@ async function handleRscRenderingInner<TEnv>(
             ttl: pprConfig.ttl,
             swr: pprConfig.swr,
             tags: pprConfig.tags,
+            captureTimeout: pprConfig.captureTimeout,
             store,
             debug: INTERNAL_RANGO_DEBUG,
+            maxSnapshotBytes: pprConfig.maxSnapshotBytes,
+            // The resolver owns the whole policy: option wins, the
+            // INTERNAL_RANGO_DEBUG env flag lights the events up when no
+            // option is set, an explicit `false` stays off.
+            debugSink: resolveShellCaptureDebugSink(
+              ctx.router.debugShellCapture,
+            ),
+          };
+          // One serve funnel for BOTH entry sources (runtime store hit below,
+          // build-manifest hit further down): schedule the background
+          // recapture when asked, then commit the composed response.
+          const serveHit = (
+            entry: ShellCacheEntry,
+            revalidate: boolean | undefined,
+          ): Response => {
+            if (revalidate) {
+              scheduleShellCapture(
+                ctx,
+                request,
+                env,
+                url,
+                reqCtx,
+                ssrModule,
+                descriptor,
+              );
+            }
+            return serveShellHit(
+              ctx,
+              request,
+              env,
+              url,
+              reqCtx,
+              handleStore,
+              ssrModule,
+              entry,
+              descriptor,
+            );
           };
           let cached: Awaited<ReturnType<typeof store.getShell>> = null;
+          const shellReadStart = reqCtx._metricsStore ? performance.now() : 0;
           try {
             cached = await store.getShell(key);
           } catch (error) {
             // A failing store read degrades to axis 1 (MISS), never a 500.
             reportCacheError(error, "cache-read", "[ShellServe] getShell");
           }
+          if (reqCtx._metricsStore) {
+            // Raw store outcome (pre-validity-gates), so a version-mismatch
+            // lifecycle miss is still distinguishable from a store miss.
+            appendMetric(
+              reqCtx._metricsStore,
+              "ppr:shell-read",
+              shellReadStart,
+              performance.now() - shellReadStart,
+              undefined,
+              cached ? "hit" : "miss",
+            );
+          }
           if (cached && isValidShellHit(cached.entry, ctx.version)) {
             if (!hasIntactShellPayload(cached.entry)) {
               // Corrupt stored payload (undecodable prelude / unparseable
@@ -196,30 +299,45 @@ async function handleRscRenderingInner<TEnv>(
             } else {
               // Stale (SWR) hit: serve the stale shell now, recapture in the
               // background (stampede-guarded + backoff inside scheduleShellCapture).
-              if (cached.shouldRevalidate) {
-                scheduleShellCapture(
-                  ctx,
-                  request,
-                  env,
-                  url,
-                  reqCtx,
-                  ssrModule,
-                  descriptor,
-                );
-              }
-              return serveShellHit(
-                ctx,
-                request,
-                env,
-                url,
-                reqCtx,
-                handleStore,
-                ssrModule,
-                cached.entry,
-                descriptor,
-              );
+              return serveHit(cached.entry, cached.shouldRevalidate);
             }
           }
+          // Build-time shell read-through (producer B, #699): on a runtime
+          // store MISS (or an invalid/corrupt runtime entry), a Prerender+ppr
+          // route's shell was already produced at `vite build` — serve it
+          // through the SAME serveShellHit, so the first-ever request after a
+          // deploy is a HIT with zero runtime capture. lookupBuildShell owns
+          // every gate (search-less request, versions, integrity, tag
+          // markers) and fails to null — the ordinary MISS path below takes
+          // over. Past ppr.ttl the baked entry still serves but a runtime
+          // recapture is scheduled: SWR is the UPGRADE path from build entry
+          // to fresher runtime entry (the runtime store read above wins once
+          // the capture lands).
+          const buildHit = await lookupBuildShell(
+            url,
+            ctx.version,
+            store,
+            // Dev: no build manifest exists; producer B runs on demand via
+            // the dev server's /__rsc_shell endpoint for PRERENDERED routes
+            // only (production's exact candidate set). Folded away in
+            // production builds (NODE_ENV is a compile-time constant).
+            process.env.NODE_ENV !== "production"
+              ? {
+                  isPrerenderRoute:
+                    reqCtx._classifiedRoute?.matched?.pr === true,
+                  routeName: reqCtx._classifiedRoute?.routeKey,
+                  ttl: pprConfig.ttl,
+                  swr: pprConfig.swr,
+                  tags: pprConfig.tags,
+                  maxSnapshotBytes: pprConfig.maxSnapshotBytes,
+                  captureTimeout: pprConfig.captureTimeout,
+                }
+              : undefined,
+          );
+          if (buildHit) {
+            // Past ppr.ttl: still serve the baked entry, recapture upgrades it.
+            return serveHit(buildHit.entry, buildHit.stale);
+          }
           // MISS (no entry, invalid reactVersion, or store read failure): axis 1
           // + a background capture scheduled once the response is known servable.
           pprMiss = { descriptor, ssrModule };
@@ -240,8 +358,12 @@ async function handleRscRenderingInner<TEnv>(
       if (match.redirect) {
         // Partial request: use X-RSC-Redirect header so the client can
         // perform SPA navigation. A raw 308 would be auto-followed by
-        // fetch, hitting the target without _rsc_partial.
-        return createSimpleRedirectResponse(match.redirect);
+        // fetch, hitting the target without _rsc_partial. Resolve the
+        // target server-side (same open-redirect policy as 3xx).
+        return createSimpleRedirectResponse(match.redirect, {
+          requestOrigin: url.origin,
+          basename: ctx.router.basename,
+        });
       }
 
       payload = buildFullPayload(match, ctx, url, reqCtx, handleStore);
@@ -335,76 +457,64 @@ async function handleRscRenderingInner<TEnv>(
 
   const metricsStore = reqCtx._metricsStore;
 
-  // Serialize to RSC stream
-  const rscSerializeStart = performance.now();
-  const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-    onError: (error: unknown) => {
-      ctx.callOnError(error, "rendering", { request, url, env });
-    },
-  });
-  const rscSerializeDur = performance.now() - rscSerializeStart;
-  // This measures synchronous stream creation, not end-to-end stream consumption.
-  appendMetric(
-    metricsStore,
-    "rsc-serialize",
-    rscSerializeStart,
-    rscSerializeDur,
-  );
-
-  if (isRscRequest(request, url, isPartial)) {
-    // render:total is recorded by the observePhase wrapper around this function.
-    const rscHeaders: Record<string, string> = {
-      "content-type": "text/x-component;charset=utf-8",
-      vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
-      // Router identity, so the client can verify pre-decode (before importing
-      // chunks) that this content payload belongs to its app and refuse a
-      // foreign one (cache/proxy/bug). Control-only reload/redirect responses
-      // are deliberately NOT stamped. See browser/response-adapter.ts.
-      "X-RSC-Router-Id": ctx.router.id,
-    };
-    // Tell the client's prefetch cache to scope this response to its source
-    // URL (instead of the default source-agnostic wildcard). Intercept
-    // responses depend on the source page matching an intercept rule, so
-    // they must not be reused for navigations from other sources.
-    if (hasInterceptSlots) {
-      rscHeaders["x-rsc-prefetch-scope"] = "source";
-    }
-    // Enable browser HTTP caching for prefetch responses only.
-    // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
-    // non-intercept context (intercept responses depend on source page),
-    // and a configured cache-control value (false disables caching).
-    const isPrefetch = request.headers.has("X-Rango-Prefetch");
-    if (isPrefetch && isPartial && !hasInterceptSlots) {
-      const cc = ctx.router.prefetchCacheControl;
-      if (cc) {
-        rscHeaders["cache-control"] = cc;
-      }
+  const rscHeaders: Record<string, string> = {
+    "content-type": "text/x-component;charset=utf-8",
+    vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
+    // Router identity, so the client can verify pre-decode (before importing
+    // chunks) that this content payload belongs to its app and refuse a
+    // foreign one (cache/proxy/bug). Control-only reload/redirect responses
+    // are deliberately NOT stamped. See browser/response-adapter.ts.
+    "X-RSC-Router-Id": ctx.router.id,
+  };
+  // Tell the client's prefetch cache to scope this response to its source
+  // URL (instead of the default source-agnostic wildcard). Intercept
+  // responses depend on the source page matching an intercept rule, so
+  // they must not be reused for navigations from other sources.
+  if (hasInterceptSlots) {
+    rscHeaders["x-rsc-prefetch-scope"] = "source";
+  }
+  // Enable browser HTTP caching for prefetch responses only.
+  // Requires X-Rango-Prefetch header (sent by Link prefetch fetch),
+  // non-intercept context (intercept responses depend on source page),
+  // and a configured cache-control value (false disables caching).
+  const isPrefetch = request.headers.has("X-Rango-Prefetch");
+  if (isPrefetch && isPartial && !hasInterceptSlots) {
+    const cc = ctx.router.prefetchCacheControl;
+    if (cc) {
+      rscHeaders["cache-control"] = cc;
     }
-    return createResponseWithMergedHeaders(rscStream, {
-      headers: rscHeaders,
-    });
   }
 
-  // Delegate to SSR for HTML response (reuse early setup if available)
-  const [ssrModule, streamMode] = await getSSRSetup(
-    ctx,
-    request,
-    env,
-    url,
-    metricsStore,
-  );
-
-  // 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, () =>
-    ssrModule.renderHTML(rscStream, {
-      nonce,
-      streamMode,
-    }),
+  const isFlightResponse = isRscRequest(request, url, isPartial);
+  const stageTracking = {
+    mode: isPartial ? ("partial" as const) : ("full" as const),
+    routeKey: reqCtx._routeName,
+    span: renderSpan,
+  };
+  const response = await renderRscResponse(
+    {
+      ctx,
+      request,
+      env,
+      url,
+      payload,
+      init: { headers: rscHeaders },
+      tracking: stageTracking,
+    },
+    isFlightResponse
+      ? undefined
+      : {
+          html: createSsrHtmlStage({
+            ctx,
+            request,
+            env,
+            url,
+            metricsStore,
+            render: { nonce },
+            init: { headers: { "content-type": "text/html;charset=utf-8" } },
+          }),
+        },
   );
-  const response = createResponseWithMergedHeaders(htmlStream, {
-    headers: { "content-type": "text/html;charset=utf-8" },
-  });
 
   // --- Axis 2: PPR shell CAPTURE on MISS (background task; see design doc) ---
   // The ppr route missed its shell above. Schedule the background capture only
@@ -414,7 +524,7 @@ async function handleRscRenderingInner<TEnv>(
   // page via router.match() under a derived context (fresh handle store,
   // _shellCaptureRun: true) — middleware never re-runs; it already ran for this
   // request and guarding is serve-time.
-  if (pprMiss) {
+  if (pprMiss && !reqCtx._dynamic) {
     if (
       response.status === 200 &&
       (response.headers.get("content-type") ?? "").includes("text/html")
@@ -489,12 +599,27 @@ function serveShellHit(
   descriptor: ShellCaptureDescriptor,
 ): Response {
   const preludeBytes = base64ToBytes(entry.prelude);
+  // Per-stage tail timing for the dev `ppr:tail` Server-Timing mirror. Dev
+  // only (NODE_ENV folds the branch away in production builds); offsets are
+  // relative to this commit point.
+  const tailTiming: ShellTailTiming | null =
+    process.env.NODE_ENV !== "production"
+      ? {
+          key: descriptor.key,
+          outcome: "complete",
+          preludeBytes: preludeBytes.length,
+        }
+      : null;
+  const tailT0 = tailTiming ? performance.now() : 0;
 
   const renderTail = async (
     activeCtx: RequestContext<any>,
   ): Promise<ReadableStream<Uint8Array> | { redirect: string }> => {
     const matchStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
     const match = await ctx.router.match(request, { env });
+    if (tailTiming) {
+      tailTiming.matchMs = Math.round(performance.now() - tailT0);
+    }
     if (INTERNAL_RANGO_DEBUG) {
       console.log(
         `[Server][ppr] shell HIT: tail match done +${Math.round(performance.now() - matchStart)}ms (abs ${Math.round(performance.now())}, started ${Math.round(matchStart)})`,
@@ -518,11 +643,18 @@ function serveShellHit(
     }
     // Full Flight render per request: hydration needs the whole payload (there
     // is no Flight-side resume — a React limitation, not ours).
-    let rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-      onError: (error: unknown) => {
-        ctx.callOnError(error, "rendering", { request, url, env });
+    const flightStage = renderRscFlightStage({
+      ctx,
+      request,
+      env,
+      url,
+      payload,
+      tracking: {
+        mode: "full",
+        routeKey: activeCtx._routeName,
       },
     });
+    let rscStream = flightStage.stream;
     // Timing tap: when does the Flight render produce its FIRST byte? Compared
     // with the eager-inject/first-tail logs this proves whether hydration-start
     // latency is genuine server work (loaders) or stream plumbing holding
@@ -579,15 +711,57 @@ function serveShellHit(
       // hole-marker paths keep the fresh run's live nested promises.
       const seedStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
       const loaderSeed = await buildShellLoaderSeed(entry.snapshot);
+      if (tailTiming) {
+        tailTiming.seedMs = Math.round(performance.now() - tailT0);
+      }
       if (INTERNAL_RANGO_DEBUG) {
         console.log(
           `[Server][ppr] shell HIT: loader seed built +${Math.round(performance.now() - seedStart)}ms (abs ${Math.round(performance.now())})`,
         );
       }
       if (loaderSeed) seededCtx._shellLoaderSeed = loaderSeed;
+      // Shell fast path (serve side): when the capture recorded the implicit
+      // doc segment record and the handler layer declared no liveness, arm the
+      // implicit scope on the seeded context — the tail match's cache lookup
+      // then HITs the SeededShellStore's doc entry and the whole handler layer
+      // is REPLAYED, not re-executed (loaders still run fresh via
+      // resolveFreshLoadersAndYield; per-request payload metadata is rebuilt
+      // by buildFullPayload as always). A route with handler-live holes, a
+      // route-derived cache scope, or a missing/corrupt record degrades to
+      // the full tail (handler re-run — today's behavior) automatically.
+      if (!entry.handlerLiveHoles) {
+        seededCtx._shellImplicitCache = {
+          ttl: descriptor.ttl,
+          swr: descriptor.swr,
+        };
+        if (INTERNAL_RANGO_DEBUG) {
+          console.log(
+            `[Server][ppr] shell HIT: fast path armed (implicit doc cache) (abs ${Math.round(performance.now())})`,
+          );
+        }
+      } else if (INTERNAL_RANGO_DEBUG) {
+        console.log(
+          `[Server][ppr] shell HIT: fast path declined — handler-live holes; tail re-runs handlers (abs ${Math.round(performance.now())})`,
+        );
+      }
+      // Fragment splice (issue #700): cache/prerender-store hits inside THIS
+      // tail render emit their stored segment fragments verbatim into the
+      // payload; the SSR resume pass and browser hydration expand them
+      // (segment-fragments.ts). Tail-only: the flag lives on the derived
+      // context so it can never leak into a capture render (which serializes
+      // segments and must see real elements).
+      seededCtx._shellFragmentPayload = true;
       return runWithRequestContext(seededCtx, () => renderTail(seededCtx));
     }
-    return renderTail(reqCtx);
+    // No snapshot (e.g. a producer B entry whose capture hit only the
+    // prerender store): still a shell-HIT tail, so arm the fragment splice on
+    // a derived context — the tail's prerender-store/cache hits (if any) then
+    // splice; a route with neither serves exactly as before. Derived, never
+    // the shared reqCtx: scheduleShellCapture derives the capture context from
+    // reqCtx and the flag must not be inherited there.
+    const fragmentCtx: RequestContext<any> = Object.create(reqCtx);
+    fragmentCtx._shellFragmentPayload = true;
+    return runWithRequestContext(fragmentCtx, () => renderTail(fragmentCtx));
   })();
   // The stream below is the only consumer; pre-attach a no-op catch so a tail
   // failure before the stream is pulled never surfaces as an unhandled rejection.
@@ -604,6 +778,9 @@ function serveShellHit(
       }
       try {
         const tail = await tailPromise;
+        if (tailTiming) {
+          tailTiming.handoverMs = Math.round(performance.now() - tailT0);
+        }
         if (INTERNAL_RANGO_DEBUG) {
           console.log(
             `[Server][ppr] shell HIT: tail stream handed over +${Math.round(performance.now() - serveStart)}ms (abs ${Math.round(performance.now())})`,
@@ -617,18 +794,31 @@ function serveShellHit(
             for (;;) {
               const { done, value } = await reader.read();
               if (done) break;
-              if (INTERNAL_RANGO_DEBUG && firstTailChunk) {
+              if (firstTailChunk) {
                 firstTailChunk = false;
-                console.log(
-                  `[Server][ppr] shell HIT: first tail chunk on the wire +${Math.round(performance.now() - serveStart)}ms (abs ${Math.round(performance.now())})`,
-                );
+                if (tailTiming) {
+                  tailTiming.firstHtmlMs = Math.round(
+                    performance.now() - tailT0,
+                  );
+                }
+                if (INTERNAL_RANGO_DEBUG) {
+                  console.log(
+                    `[Server][ppr] shell HIT: first tail chunk on the wire +${Math.round(performance.now() - serveStart)}ms (abs ${Math.round(performance.now())})`,
+                  );
+                }
+              }
+              if (tailTiming || INTERNAL_RANGO_DEBUG) {
+                tailBytes += value.length;
               }
-              if (INTERNAL_RANGO_DEBUG) tailBytes += value.length;
               controller.enqueue(value);
             }
           } finally {
             reader.releaseLock();
           }
+          if (tailTiming) {
+            tailTiming.completeMs = Math.round(performance.now() - tailT0);
+            tailTiming.tailBytes = tailBytes;
+          }
           // Bounds the post-header work Server-Timing structurally cannot see:
           // the HIT commits headers at the flush, so ALL live-tail time (match,
           // loaders, Flight, resume) happens inside the response body. This
@@ -655,7 +845,12 @@ function serveShellHit(
               `<script>location.replace(${JSON.stringify(safeTarget)})</script>`,
             ),
           );
+          if (tailTiming) {
+            tailTiming.outcome = "redirect";
+            tailTiming.completeMs = Math.round(performance.now() - tailT0);
+          }
         }
+        if (tailTiming) publishShellTailTiming(tailTiming);
         controller.close();
       } catch (error) {
         // Self-heal on a failed tail: the pre-commit gates (isValidShellHit +
@@ -676,6 +871,11 @@ function serveShellHit(
           ssrModule,
           descriptor,
         );
+        if (tailTiming) {
+          tailTiming.outcome = "error";
+          tailTiming.completeMs = Math.round(performance.now() - tailT0);
+          publishShellTailTiming(tailTiming);
+        }
         controller.error(error);
       }
     },