@rangojs/router 0.0.0-experimental.145 → 0.0.0-experimental.147

package/src/rsc/shell-capture.ts

@@ -20,15 +20,21 @@ import React from "react";
 import { bufferToBase64 } from "../cache/cf/cf-base64.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
+import { enqueueSerializedCapture } from "./capture-queue.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
   runWithRequestContext,
   setRequestContextParams,
+  wireRenderBarrier,
   UNTRACKED_BACKGROUND_TASK,
   type RequestContext,
 } from "../server/request-context.js";
 import { createHandleStore, type HandleStore } from "../server/handle-store.js";
-import { maskNestedContainerThenables } from "../router/segment-resolution/mask-nested.js";
+import {
+  maskNestedContainerThenables,
+  type MaskReport,
+} from "../router/segment-resolution/mask-nested.js";
+import { isInsideLoaderScope } from "../server/context.js";
 import { isThenable } from "../handles/is-thenable.js";
 import type {
   ShellCacheEntry,
@@ -41,6 +47,7 @@ import {
 } from "../router/segment-resolution/loader-snapshot.js";
 import {
   RecordingShellStore,
+  SnapshotOnlySegmentStore,
   getRecordingStore,
 } from "../cache/shell-snapshot.js";
 import type { HandlerContext } from "./handler-context.js";
@@ -599,14 +606,20 @@ export function scheduleShellCapture(
       inFlightCaptures.delete(key);
     }
   };
+  // Serialize capture EXECUTION per isolate (capture-queue.ts): concurrent
+  // captures starve each other's task-quantized quiet windows — one grinding
+  // capture makes the sibling freeze a trivial prelude and store nothing
+  // (rotating eternal-MISS victims on GH runners). The stampede guard above
+  // stays per-key (dedupe while queued); the queue is cross-key.
+  const serializedTask = () => enqueueSerializedCapture(captureTask);
   // The capture's own task must NOT enter reqCtx._pendingBackgroundTasks: the
   // capture drains that list before rendering (the write-barrier ordering edge),
   // and awaiting its own still-running promise would burn the whole barrier
   // deadline on every capture.
-  (captureTask as { [UNTRACKED_BACKGROUND_TASK]?: boolean })[
+  (serializedTask as { [UNTRACKED_BACKGROUND_TASK]?: boolean })[
     UNTRACKED_BACKGROUND_TASK
   ] = true;
-  runBackground(reqCtx, captureTask);
+  runBackground(reqCtx, serializedTask);
 }
 
 /**
@@ -701,6 +714,18 @@ async function runShellCapture(
   return "no-shell";
 }
 
+/** Fold the capture's handle-liveness record into the entry flag (true | undefined). */
+function handlerLayerIsLive(
+  liveness: RequestContext["_shellCaptureHandleLiveness"],
+): true | undefined {
+  if (!liveness) return undefined;
+  return liveness.holes ||
+    liveness.pendingPushes > 0 ||
+    liveness.handlerInvokedLoader
+    ? true
+    : undefined;
+}
+
 /**
  * One capture attempt in a DERIVED request context.
  *
@@ -720,6 +745,9 @@ async function runShellCapture(
  *   - _shellCaptureRun: true — the switch loaders/cookies/headers guards read.
  *   - _metricsStore: undefined so the capture never appends to the foreground's
  *     (already-finalized) metrics.
+ *   - _renderBarrier family: an own barrier wired to the fresh handle store
+ *     (wireRenderBarrier), plus _treeHasStreaming/deadlock-guard resets — the
+ *     capture's rendered() lifecycle is its own, not the foreground's.
  *
  * The capture is MIXED-CHAIN: its match() behaves like a normal render with
  * respect to the segment cache — cache()'d segments replay from ring 3, UNCACHED
@@ -751,6 +779,74 @@ async function attemptCapture(
   // attempt (the retry re-checks; already-settled promises are free).
   await settleTrackedBackgroundTasks(reqCtx, SHELL_CAPTURE_WRITE_BARRIER_MS);
 
+  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(
+    reqCtx,
+    descriptor,
+  );
+
+  return runWithRequestContext(derivedCtx, async () => {
+    const match = await ctx.router.match(request, { env });
+    // A route that redirects has no shell to capture — bail (no store write, no
+    // retry: a redirect is deterministic).
+    if (match.redirect) return "redirect";
+
+    setRequestContextParams(match.params, match.routeName);
+
+    const payload = buildFullPayload(
+      match,
+      ctx,
+      url,
+      derivedCtx,
+      freshHandleStore,
+    );
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", { request, url, env });
+      },
+    });
+
+    // Pass the descriptor with its STATIC ppr.tags unchanged. The shell's own
+    // render-recorded tags are snapshotted at the putShell WRITE BARRIER inside
+    // captureAndStoreShell, not here: a tag recorded AFTER an await in async shell
+    // content (and tags propagated by async cache()/"use cache" reads) lands after
+    // this synchronous construction point, so snapshotting here dropped it — the
+    // shell-tag snapshot must sit behind the quiesce gate (issue #676).
+    return captureAndStoreShell(
+      ssrModule,
+      rscStream,
+      freshHandleStore,
+      derivedCtx,
+      descriptor,
+    );
+  });
+}
+
+/**
+ * The derived capture context and its fresh (mask-funneled) handle store,
+ * shared by BOTH shell producers: the runtime background capture
+ * (attemptCapture, producer A) and the build-time prerender shell capture
+ * (prerender/build-shell-capture.ts, producer B — issue #699). One
+ * implementation so the capture semantics — the nested-thenable mask funnel,
+ * handler-liveness bookkeeping, snapshot recording, the implicit doc-cache
+ * scope — cannot drift between producers.
+ */
+export interface CaptureContextDerivation {
+  derivedCtx: RequestContext;
+  freshHandleStore: HandleStore;
+}
+
+/**
+ * Derive the capture request context from a base context. Producer A passes
+ * the foreground request's post-middleware context (the derived context
+ * inherits its variables/env/cookie machinery through the prototype);
+ * producer B passes a synthetic build-request context created by
+ * createRequestContext over the build env, with a fresh MemorySegmentCacheStore
+ * as `_cacheStore` so the recording/snapshot machinery arms identically.
+ */
+export function deriveShellCaptureContext(
+  reqCtx: RequestContext<any>,
+  descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">,
+): CaptureContextDerivation {
   const freshHandleStore = createHandleStore();
   freshHandleStore.onError = reqCtx._handleStore.onError;
   // Shape = liveness for handles, exactly as for bake-lane loader containers
@@ -764,21 +860,83 @@ async function attemptCapture(
   // the store exists only for this capture attempt, so every push wrapper
   // (setupLoaderAccess, createUseFunction, prerender) inherits the policy and
   // the foreground store is untouched.
+  // Shell fast path bookkeeping on the same funnel:
+  //  - handleLiveness: a nested thenable in a push made OUTSIDE a DSL loader
+  //    scope (attribution read synchronously at push time — handler bodies,
+  //    handler-invoked ctx.use(loader) callbacks, defers) declares
+  //    handler-layer per-request data. Its mask is a hole only a handler
+  //    re-run can fill, so the entry must not serve handler-free
+  //    (ShellCacheEntry.handlerLiveHoles). Still-pending top-level handler
+  //    pushes at the putShell barrier count too — their liveness is unknowable.
+  //  - loaderScopedPushValues: DSL-loader pushes re-run fresh on every HIT, so
+  //    their captured values must NOT enter a segment record's handle snapshot
+  //    (replay would duplicate the fresh push, and their masked nested
+  //    promises would stall the Flight handle encode to its timeout). The set
+  //    rides the derived context (_shellCaptureLoaderHandleValues) and is
+  //    applied ONLY at the captureHandles cache-write call site — every other
+  //    getDataForSegment consumer (the render-barrier snapshot, prerender)
+  //    sees every push.
+  const handleLiveness = {
+    holes: false,
+    pendingPushes: 0,
+    handlerInvokedLoader: false,
+  };
+  const loaderScopedPushValues = new WeakSet<object>();
   const rawCapturePush = freshHandleStore.push.bind(freshHandleStore);
   freshHandleStore.push = (
     handleName: string,
     segmentId: string,
     value: unknown,
   ) => {
-    const masked = isThenable(value)
-      ? value.then((v: unknown) => maskNestedContainerThenables(v))
-      : maskNestedContainerThenables(value);
+    const pushedInLoaderScope = isInsideLoaderScope();
+    // Single walk: the mask reports whether it masked any nested thenable
+    // (the liveness declaration) while building the capture copy.
+    const maskWithLiveness = (v: unknown): unknown => {
+      const report: MaskReport = { thenable: false };
+      const masked = maskNestedContainerThenables(v, undefined, report);
+      if (!pushedInLoaderScope && report.thenable) {
+        handleLiveness.holes = true;
+      }
+      return masked;
+    };
+    let masked: unknown;
+    if (isThenable(value)) {
+      if (!pushedInLoaderScope) {
+        handleLiveness.pendingPushes++;
+        const settle = () => handleLiveness.pendingPushes--;
+        value.then(settle, settle);
+      }
+      masked = value.then(maskWithLiveness);
+    } else {
+      masked = maskWithLiveness(value);
+    }
+    if (pushedInLoaderScope && typeof masked === "object" && masked !== null) {
+      loaderScopedPushValues.add(masked);
+    }
     rawCapturePush(handleName, segmentId, masked);
   };
 
   const derivedCtx: RequestContext = Object.create(reqCtx);
   derivedCtx._handleStore = freshHandleStore;
+  // Own render barrier, closure-bound to the derived ctx and the fresh store
+  // (issue #684, plan 009). Without this every _renderBarrier* read fell
+  // through the prototype to the foreground's ALREADY-RESOLVED barrier: a
+  // bake-lane loader's `await ctx.rendered()` resolved instantly and
+  // ctx.use(handle) read the FOREGROUND handle snapshot — foreground
+  // per-request handle data could bake into the shared shell. wireRenderBarrier
+  // also resets _treeHasStreaming (recomputed for the capture's tree) and the
+  // deadlock-guard fields as own properties.
+  wireRenderBarrier(derivedCtx, freshHandleStore);
+  derivedCtx._shellCaptureLoaderHandleValues = loaderScopedPushValues;
   derivedCtx._requestTags = new Set<string>();
+  // Own explicit-store registry: cache-store resolutions during the capture
+  // (the implicit scope's SnapshotOnlySegmentStore, any per-capture explicit
+  // store instance) must NOT register into the handler-lifetime
+  // _explicitTaggedStores set — a capture-ephemeral store pinned there would
+  // trip the partial-tag-store warning on every later updateTag() and retain
+  // the whole capture snapshot in memory. Capture registrations die with this
+  // context; module-singleton stores stay registered by normal renders.
+  derivedCtx._explicitTaggedStores = new Set();
   derivedCtx._transitionWhen = [];
   derivedCtx._shellCaptureRun = true;
   derivedCtx._metricsStore = undefined;
@@ -812,6 +970,7 @@ async function attemptCapture(
   // forwarding to the parent so the write persists and the worker stays alive),
   // then captureAndStoreShell awaits them before draining. Reads that HIT are
   // recorded synchronously during the render and need none of this.
+  derivedCtx._shellCaptureHandleLiveness = handleLiveness;
   if (reqCtx._cacheStore) {
     const recordingStore = new RecordingShellStore(reqCtx._cacheStore);
     derivedCtx._cacheStore = recordingStore;
@@ -820,43 +979,20 @@ async function attemptCapture(
       recordingStore.trackWrite(p);
       reqCtx.waitUntil(() => p);
     };
+    // Shell fast path (capture side): the implicit doc-cache scope makes the
+    // capture's match write ALL matched non-loader segments as one doc-keyed
+    // segment record — into the snapshot only (SnapshotOnlySegmentStore), so
+    // the record dies with the shell entry and the next capture's lookup
+    // still misses (handlers re-run on recapture). Routes deriving their own
+    // cache scope are untouched (resolveShellImplicitCacheScope).
+    derivedCtx._shellImplicitCache = {
+      ttl: descriptor.ttl,
+      swr: descriptor.swr,
+      store: new SnapshotOnlySegmentStore(recordingStore),
+    };
   }
 
-  return runWithRequestContext(derivedCtx, async () => {
-    const match = await ctx.router.match(request, { env });
-    // A route that redirects has no shell to capture — bail (no store write, no
-    // retry: a redirect is deterministic).
-    if (match.redirect) return "redirect";
-
-    setRequestContextParams(match.params, match.routeName);
-
-    const payload = buildFullPayload(
-      match,
-      ctx,
-      url,
-      derivedCtx,
-      freshHandleStore,
-    );
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-      onError: (error: unknown) => {
-        ctx.callOnError(error, "rendering", { request, url, env });
-      },
-    });
-
-    // Pass the descriptor with its STATIC ppr.tags unchanged. The shell's own
-    // render-recorded tags are snapshotted at the putShell WRITE BARRIER inside
-    // captureAndStoreShell, not here: a tag recorded AFTER an await in async shell
-    // content (and tags propagated by async cache()/"use cache" reads) lands after
-    // this synchronous construction point, so snapshotting here dropped it — the
-    // shell-tag snapshot must sit behind the quiesce gate (issue #676).
-    return captureAndStoreShell(
-      ssrModule,
-      rscStream,
-      freshHandleStore,
-      derivedCtx,
-      descriptor,
-    );
-  });
+  return { derivedCtx, freshHandleStore };
 }
 
 /**
@@ -1142,6 +1278,14 @@ async function captureAndStoreShell(
           // ShellCacheEntry.initialTheme.
           initialTheme: reqCtx.theme,
           snapshot,
+          // Handler-layer liveness folded at the barrier: nested thenables in
+          // handler-scoped pushes, handler pushes still pending (liveness
+          // unknowable), or a handler-invoked loader execution — any of them
+          // refuses the FAST PATH, not the capture. See
+          // _shellCaptureHandleLiveness.
+          handlerLiveHoles: handlerLayerIsLive(
+            reqCtx._shellCaptureHandleLiveness,
+          ),
           createdAt: Date.now(),
         };
         await store.putShell(
@@ -1172,8 +1316,15 @@ async function captureAndStoreShell(
   }
 }
 
-// Exported for unit tests that drive the capture core directly.
-export { runShellCapture, captureAndStoreShell };
+// Exported for unit tests that drive the capture core directly, and — with the
+// cold-graph retry pieces — for producer B (prerender/build-shell-capture.ts),
+// which mirrors the runtime capture's retry-in-place with the same delay.
+export {
+  runShellCapture,
+  captureAndStoreShell,
+  delay,
+  SHELL_CAPTURE_RETRY_DELAY_MS,
+};
 
 // Exported for unit tests that pin the refused-capture backoff policy directly
 // (dev cap vs production exponential growth, stored-clears, cold-start re-probe).

package/src/segment-fragments.ts

@@ -0,0 +1,124 @@
+/**
+ * Segment Flight-fragment envelopes (PPR fast-path payload splice, issue #700).
+ *
+ * On a shell-HIT tail, replayed (baked) segments do NOT round-trip through the
+ * server codec (deserialize -> re-serialize) per request. The stored RSC
+ * fragment STRINGS ride the outgoing payload verbatim inside these envelopes
+ * — the outer Flight render copies a string instead of re-serializing a whole
+ * element tree — and the CONSUMER expands each envelope through its own Flight
+ * deserializer: the SSR resume pass (ssr/ssr-root.tsx) and browser hydration
+ * (browser/rsc-router.tsx). Each fragment is its own row space, decoded
+ * independently, exactly like the segment codec's per-record decode — so
+ * there is no Flight row-id collision or shared-row dedupe hazard.
+ *
+ * Envelopes appear ONLY on fields that hold ReactNodes (component / layout /
+ * loading). A plain object is never a valid ReactNode, so the marker cannot
+ * collide with legitimate segment content; loader data fields (consumer data,
+ * any shape) are never enveloped.
+ *
+ * This module is shared client/server code (browser + SSR + RSC import it) —
+ * it must stay dependency-free: no plugin-rsc, no request-context.
+ */
+
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * One RSC-encoded fragment traveling inside an RscPayload segment field.
+ * `f` is the stored Flight document (segment-codec output) for that field.
+ */
+export interface SegmentFlightFragment {
+  __rangoFragment: 1;
+  f: string;
+}
+
+/** Wrap a stored fragment string for the wire. */
+export function segmentFragment(encoded: string): SegmentFlightFragment {
+  return { __rangoFragment: 1, f: encoded };
+}
+
+/** True iff `value` is a fragment envelope (see collision note in the header). */
+export function isSegmentFragment(
+  value: unknown,
+): value is SegmentFlightFragment {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __rangoFragment?: unknown }).__rangoFragment === 1 &&
+    typeof (value as { f?: unknown }).f === "string"
+  );
+}
+
+/**
+ * A consumer-side Flight deserializer: the browser's or the SSR runtime's
+ * createFromReadableStream (each resolves client references through its own
+ * module map, exactly as it does for the outer payload stream). Non-generic
+ * so both environments' generic createFromReadableStream signatures assign
+ * directly.
+ */
+export type FragmentDecoder = (
+  stream: ReadableStream<Uint8Array>,
+) => Promise<unknown>;
+
+/** One-chunk byte stream over an encoded fragment (local: this module must not
+ *  import segment-codec, which pulls plugin-rsc into client bundles). */
+function fragmentToStream(encoded: string): ReadableStream<Uint8Array> {
+  const bytes = new TextEncoder().encode(encoded);
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+/** The segment fields that may carry an envelope (ReactNode fields only). */
+const FRAGMENT_FIELDS = ["component", "layout", "loading"] as const;
+
+/**
+ * Expand every fragment envelope in `segments` IN PLACE via `decode`,
+ * in parallel. A payload with no envelopes (every non-shell-HIT payload) costs
+ * one synchronous field scan. A failing fragment decode rejects the whole
+ * expansion: the caller's payload promise rejects, which on the SSR side
+ * errors the HIT tail (serveShellHit then schedules the healing recapture) —
+ * the same posture as a parseable-but-mismatched postponed blob.
+ */
+export async function expandSegmentFragments(
+  segments: ResolvedSegment[] | undefined,
+  decode: FragmentDecoder,
+): Promise<void> {
+  if (!segments || segments.length === 0) return;
+  const decodes: Promise<void>[] = [];
+  for (const segment of segments) {
+    for (const field of FRAGMENT_FIELDS) {
+      const value = segment[field];
+      if (isSegmentFragment(value)) {
+        // Promise.resolve() adoption is load-bearing: some deserializers
+        // (react-server-dom's Flight client) return a THENABLE Chunk whose
+        // .then returns undefined — chaining directly would push undefined
+        // into the barrier and Promise.all would not wait for the decode.
+        decodes.push(
+          Promise.resolve(decode(fragmentToStream(value.f))).then((node) => {
+            segment[field] = node as ResolvedSegment[typeof field];
+          }),
+        );
+      }
+    }
+  }
+  if (decodes.length > 0) await Promise.all(decodes);
+}
+
+/**
+ * True when any segment carries an unexpanded envelope. Cheap scan used by
+ * consumers that only need to know whether an expansion pass is required.
+ */
+export function hasSegmentFragments(
+  segments: ResolvedSegment[] | undefined,
+): boolean {
+  if (!segments) return false;
+  for (const segment of segments) {
+    for (const field of FRAGMENT_FIELDS) {
+      if (isSegmentFragment(segment[field])) return true;
+    }
+  }
+  return false;
+}

package/src/segment-system.tsx

@@ -18,14 +18,20 @@ import {
 } from "./segment-loader-promise.js";
 
 /**
- * Client-only debug log for the segment tree build. Gated on the baked flag
- * AND `typeof window` (renderSegments also runs during SSR/RSC, which must
- * stay silent). Timestamped so tree-build steps line up with the
- * `[Browser][boot]` sequence around hydrateRoot.
+ * Debug log for the segment tree build, gated on the baked flag. Runs on BOTH
+ * sides now, environment-tagged: `[Browser][segments]` lines up with the
+ * `[Browser][boot]` sequence around hydrateRoot; `[Server][segments]` exposes
+ * the SSR/RSC tree-build stalls (blocking loader awaits during fizz are what
+ * dominate MISS TTFB) that used to be invisible because the logs were
+ * window-gated. Server lines have no request correlation — segment-system is
+ * shared client code and cannot import request-context (node:async_hooks
+ * would enter the browser bundle) — so on a busy server, correlate by
+ * timestamp + segment ids.
  */
 function segDebugLog(msg: string, details?: Record<string, unknown>): void {
-  if (!(INTERNAL_RANGO_DEBUG && typeof window === "object")) return;
-  const prefix = `[Browser][segments] ${msg} @ ${Math.round(performance.now())}ms`;
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const env = typeof window === "object" ? "[Browser]" : "[Server]";
+  const prefix = `${env}[segments] ${msg} @ ${Math.round(performance.now())}ms`;
   if (details) {
     console.log(prefix, details);
     return;
@@ -228,7 +234,7 @@ export async function renderSegments(
     rootLayout: RootLayout,
   } = options || {};
 
-  const segDebug = INTERNAL_RANGO_DEBUG && typeof window === "object";
+  const segDebug = INTERNAL_RANGO_DEBUG;
   const segDebugStart = segDebug ? performance.now() : 0;
   if (segDebug) {
     segDebugLog("renderSegments start", {
@@ -299,15 +305,7 @@ export async function renderSegments(
       `Expected layout, route, error, or notFound segment, got ${node.segment.type}`,
     );
     const { component, id, params, loading } = node.segment;
-
-    if (segDebug) {
-      segDebugLog(`segment ${id}`, {
-        type: node.segment.type,
-        loaders: node.loaders.map((l) => l.loaderId).filter(Boolean),
-        hasLoading: loading !== undefined && loading !== null,
-        parallel: node.parallel.map((p) => p.id),
-      });
-    }
+    const segNodeStart = segDebug ? performance.now() : 0;
 
     // Param-agnostic keys are opt-in via the transition() DSL (see
     // inTransitionScope above). A route (and its route-owned layouts) inside a
@@ -350,7 +348,13 @@ export async function renderSegments(
 
     let resolvedComponent = component;
     if (isAction && component instanceof Promise) {
+      const componentAwaitStart = segDebug ? performance.now() : 0;
       resolvedComponent = await component;
+      if (segDebug) {
+        segDebugLog(`segment ${id}: component awaited (action)`, {
+          ms: Math.round(performance.now() - componentAwaitStart),
+        });
+      }
     }
 
     let nodeContent: ReactNode = null;
@@ -367,9 +371,16 @@ export async function renderSegments(
       // suspends on mount inside the content still reveals a fallback (it is not
       // pre-resolved).
       const contentPromise = getMemoizedContentPromise(resolvedComponent);
-      const loadingContent: Promise<ReactNode> | ReactNode = forceAwait
-        ? await contentPromise
-        : contentPromise;
+      let loadingContent: Promise<ReactNode> | ReactNode = contentPromise;
+      if (forceAwait) {
+        const contentAwaitStart = segDebug ? performance.now() : 0;
+        loadingContent = await contentPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: content awaited (forceAwait)`, {
+            ms: Math.round(performance.now() - contentAwaitStart),
+          });
+        }
+      }
       nodeContent = createElement(RouteContentWrapper, {
         key: `suspense-loading-${id}`,
         content: loadingContent,
@@ -492,10 +503,19 @@ export async function renderSegments(
           ms: Math.round(performance.now() - layoutAwaitStart),
         });
       }
+      const decodeStart = segDebug ? performance.now() : 0;
       const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
         layoutLoaderIds,
       );
+      if (segDebug) {
+        const decodeMs = Math.round(performance.now() - decodeStart);
+        if (decodeMs > 0) {
+          segDebugLog(`segment ${id}: loader results decoded`, {
+            ms: decodeMs,
+          });
+        }
+      }
 
       if (parallelOwnedLoaders.length > 0) {
         const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
@@ -568,6 +588,16 @@ export async function renderSegments(
         children: content,
       });
     }
+
+    if (segDebug) {
+      segDebugLog(`segment ${id} built`, {
+        type: node.segment.type,
+        ms: Math.round(performance.now() - segNodeStart),
+        loaders: node.loaders.map((l) => l.loaderId).filter(Boolean),
+        hasLoading: loading !== undefined && loading !== null,
+        parallel: node.parallel.map((p) => p.id),
+      });
+    }
   }
 
   const errorBoundaryWrapped = createElement(RootErrorBoundary, {