@rangojs/router 0.0.0-experimental.144 → 0.0.0-experimental.146

package/src/rsc/rsc-rendering.ts

@@ -38,6 +38,7 @@ import {
   resolvePprConfig,
   buildShellKey,
   isValidShellHit,
+  hasIntactShellPayload,
   base64ToBytes,
   hasShellFamily,
   warnShellStoreMissingOnce,
@@ -164,6 +165,7 @@ async function handleRscRenderingInner<TEnv>(
         ) {
           const descriptor: ShellCaptureDescriptor = {
             key,
+            buildVersion: ctx.version,
             ttl: pprConfig.ttl,
             swr: pprConfig.swr,
             tags: pprConfig.tags,
@@ -177,30 +179,46 @@ async function handleRscRenderingInner<TEnv>(
             // A failing store read degrades to axis 1 (MISS), never a 500.
             reportCacheError(error, "cache-read", "[ShellServe] getShell");
           }
-          if (cached && isValidShellHit(cached.entry)) {
-            // Stale (SWR) hit: serve the stale shell now, recapture in the
-            // background (stampede-guarded + backoff inside scheduleShellCapture).
-            if (cached.shouldRevalidate) {
-              scheduleShellCapture(
+          if (cached && isValidShellHit(cached.entry, ctx.version)) {
+            if (!hasIntactShellPayload(cached.entry)) {
+              // Corrupt stored payload (undecodable prelude / unparseable
+              // postponed): a store-layer fault worth a diagnostic, unlike the
+              // silent version-mismatch lifecycle misses above. Degrade to MISS
+              // — pprMiss below schedules the recapture that overwrites it.
+              reportCacheError(
+                new Error(
+                  `corrupt shell entry for "${key}": prelude/postponed failed ` +
+                    "the integrity check; serving axis 1 and recapturing",
+                ),
+                "cache-read",
+                "[ShellServe] getShell",
+              );
+            } 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 serveShellHit(
-              ctx,
-              request,
-              env,
-              url,
-              reqCtx,
-              handleStore,
-              ssrModule,
-              cached.entry,
-            );
           }
           // MISS (no entry, invalid reactVersion, or store read failure): axis 1
           // + a background capture scheduled once the response is known servable.
@@ -468,13 +486,20 @@ function serveShellHit(
   handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   ssrModule: SSRModule,
   entry: ShellCacheEntry,
+  descriptor: ShellCaptureDescriptor,
 ): Response {
   const preludeBytes = base64ToBytes(entry.prelude);
 
   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 (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)})`,
+      );
+    }
     if (match.redirect) return { redirect: match.redirect };
     setRequestContextParams(match.params, match.routeName);
     const payload = buildFullPayload(match, ctx, url, activeCtx, handleStore);
@@ -493,11 +518,32 @@ function serveShellHit(
     }
     // Full Flight render per request: hydration needs the whole payload (there
     // is no Flight-side resume — a React limitation, not ours).
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+    let rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
       onError: (error: unknown) => {
         ctx.callOnError(error, "rendering", { request, url, env });
       },
     });
+    // 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
+    // ready bytes back.
+    if (INTERNAL_RANGO_DEBUG) {
+      const tapStart = performance.now();
+      let first = false;
+      rscStream = rscStream.pipeThrough(
+        new TransformStream({
+          transform(chunk, controller) {
+            if (!first) {
+              first = true;
+              console.log(
+                `[Server][ppr] flight render: first chunk +${Math.round(performance.now() - tapStart)}ms (abs ${Math.round(performance.now())})`,
+              );
+            }
+            controller.enqueue(chunk);
+          },
+        }),
+      );
+    }
     return observePhase(PHASES.ssr, () =>
       ssrModule.resumeShellHTML!(rscStream, {
         postponed: entry.postponed,
@@ -531,8 +577,38 @@ function serveShellHit(
       // decode into a seed Map for the resolveLoaderData overlay, so the
       // payload's baked container bytes match the frozen prelude while the
       // 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 (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())})`,
+        );
+      }
       return runWithRequestContext(seededCtx, () => renderTail(seededCtx));
     }
     return renderTail(reqCtx);
@@ -541,22 +617,51 @@ function serveShellHit(
   // failure before the stream is pulled never surfaces as an unhandled rejection.
   tailPromise.catch(() => {});
 
+  const serveStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
   const body = new ReadableStream<Uint8Array>({
     async start(controller) {
       controller.enqueue(preludeBytes);
+      if (INTERNAL_RANGO_DEBUG) {
+        console.log(
+          `[Server][ppr] shell HIT: prelude enqueued (${preludeBytes.length}b) +${Math.round(performance.now() - serveStart)}ms`,
+        );
+      }
       try {
         const tail = await tailPromise;
+        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())})`,
+          );
+        }
         if (tail instanceof ReadableStream) {
           const reader = tail.getReader();
+          let firstTailChunk = true;
+          let tailBytes = 0;
           try {
             for (;;) {
               const { done, value } = await reader.read();
               if (done) break;
+              if (INTERNAL_RANGO_DEBUG && 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 (INTERNAL_RANGO_DEBUG) tailBytes += value.length;
               controller.enqueue(value);
             }
           } finally {
             reader.releaseLock();
           }
+          // 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
+          // line plus the [Server][segments] build logs narrate that window.
+          if (INTERNAL_RANGO_DEBUG) {
+            console.log(
+              `[Server][ppr] shell HIT: tail complete +${Math.round(performance.now() - serveStart)}ms (${tailBytes}b)`,
+            );
+          }
         } else {
           // Defensive, near-unreachable: a redirecting match cannot have captured
           // a shell (capture bails on redirects), so a HIT on a redirecting URL
@@ -577,6 +682,24 @@ function serveShellHit(
         }
         controller.close();
       } catch (error) {
+        // Self-heal on a failed tail: the pre-commit gates (isValidShellHit +
+        // hasIntactShellPayload) cannot catch a parseable-but-mismatched
+        // postponed blob or a hard render error above the holes — those throw
+        // here, AFTER the 200 + prelude flushed, and would otherwise re-fail on
+        // every request until the entry ages out (nothing else evicts it).
+        // Recapturing overwrites the entry with one the current server
+        // produced. A client disconnect mid-stream also lands here and
+        // schedules a spurious-but-idempotent recapture — bounded by the
+        // stampede guard + backoff inside scheduleShellCapture.
+        scheduleShellCapture(
+          ctx,
+          request,
+          env,
+          url,
+          reqCtx,
+          ssrModule,
+          descriptor,
+        );
         controller.error(error);
       }
     },

package/src/rsc/shell-capture.ts

@@ -28,6 +28,12 @@ import {
   type RequestContext,
 } from "../server/request-context.js";
 import { createHandleStore, type HandleStore } from "../server/handle-store.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,
   SegmentCacheStore,
@@ -39,6 +45,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";
@@ -529,6 +536,13 @@ export function gateFlightForCapture(
  */
 export interface ShellCaptureDescriptor {
   key: string;
+  /**
+   * The RSC handler's build version (HandlerContext.version), stamped into the
+   * stored entry as ShellCacheEntry.buildVersion — the serve-side
+   * isValidShellHit gate compares it against the running build so a persistent
+   * store can never resume a stale build's postponed blob.
+   */
+  buildVersion: string;
   ttl?: number;
   swr?: number;
   tags?: string[];
@@ -692,6 +706,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.
  *
@@ -744,10 +770,85 @@ async function attemptCapture(
 
   const freshHandleStore = createHandleStore();
   freshHandleStore.onError = reqCtx._handleStore.onError;
+  // Shape = liveness for handles, exactly as for bake-lane loader containers
+  // (mask-nested.ts): nested thenables in a pushed handle container are
+  // per-request by declaration, so the CAPTURE's copy masks them — the
+  // consuming boundary postpones as a hole regardless of settle timing,
+  // instead of a fast-settling nested value baking into the shared shell. A
+  // TOP-LEVEL promise push keeps its documented bake contract (awaited
+  // pre-SSR, gate held open for it), but the container it RESOLVES to gets
+  // the same nested masking. Wrapping THIS store's push is the single funnel:
+  // 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 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;
+  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;
@@ -781,6 +882,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;
@@ -789,6 +891,17 @@ 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 () => {
@@ -1104,12 +1217,21 @@ async function captureAndStoreShell(
           prelude: bufferToBase64(result.prelude.slice().buffer as ArrayBuffer),
           postponed: result.postponed,
           reactVersion: React.version,
+          buildVersion: capture.buildVersion,
           // The theme this capture's payload was built with (buildFullPayload
           // reads reqCtx.theme off the derived context). The serve tail replays
           // it so the resume tree matches the frozen prelude — see
           // 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(

package/src/rsc/shell-serve.ts

@@ -75,13 +75,44 @@ export function buildShellKey(url: URL): string {
 }
 
 /**
- * React version captured at prerender time is the invalidation gate: a stored
- * shell whose reactVersion differs from the running React cannot be resumed (the
- * postponed blob is build-coupled), so it is treated as a miss — the recapture
- * overwrites the same key and the entry otherwise ages out via TTL.
+ * Version gates for a stored shell: reactVersion AND buildVersion must both
+ * match the running server. The postponed blob encodes hole positions against
+ * one exact tree, so resuming it under a different React OR a different app
+ * build tree-mismatches inside resume() — after the 200 + prelude committed,
+ * with no recovery. Either mismatch is a miss: the recapture overwrites the
+ * same key (self-healing) and the entry otherwise ages out via TTL. An entry
+ * with no buildVersion (stored before the field existed) is a miss for the
+ * same reason — its build is unknown, so it cannot be proven resumable.
  */
-export function isValidShellHit(entry: ShellCacheEntry): boolean {
-  return entry.reactVersion === React.version;
+export function isValidShellHit(
+  entry: ShellCacheEntry,
+  buildVersion: string,
+): boolean {
+  return (
+    entry.reactVersion === React.version && entry.buildVersion === buildVersion
+  );
+}
+
+/**
+ * Payload integrity gate, run BEFORE the HIT response commits: a stored entry
+ * whose prelude is not decodable base64 or whose postponed blob is not
+ * parseable JSON would otherwise throw AFTER the 200 + full static prelude
+ * flushed (`serveShellHit` decodes at stream construction, `resumeShellHTML`
+ * parses in the tail) — the client gets a visually complete page that never
+ * hydrates, re-served on every request until the entry ages out (no eviction
+ * path exists; failure schedules no recapture by itself). Checking here turns
+ * a corrupt entry (store-layer fault) into a plain MISS the recapture
+ * overwrites. Cost: one duplicate decode/parse per HIT, sub-ms against a
+ * prelude flush that dominates the path.
+ */
+export function hasIntactShellPayload(entry: ShellCacheEntry): boolean {
+  try {
+    base64ToBytes(entry.prelude);
+    if (entry.postponed !== null) JSON.parse(entry.postponed);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 /** Decode a base64 prelude back into bytes for stream composition. */

package/src/segment-loader-promise.ts

@@ -1,4 +1,5 @@
 import type { ResolvedSegment } from "./types.js";
+import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
 
 /**
  * Cache of aggregate Promise.all results keyed on the first loader's
@@ -83,6 +84,23 @@ export function buildLoaderPromise(loaders: ResolvedSegment[]): Promise<any[]> {
   if (loaders.length === 0) {
     return Promise.resolve([]);
   }
+  // Debug tap (browser only): log when each PENDING loader promise settles —
+  // i.e. when its data actually lands from the flight stream — independent of
+  // when the tree build awaits it. `.then(cb, cb)` observes on a branch, so
+  // rejections still propagate to the real consumers untouched.
+  if (INTERNAL_RANGO_DEBUG && IS_BROWSER) {
+    const tapStart = performance.now();
+    for (const loader of loaders) {
+      if (loader.loaderData instanceof Promise) {
+        const settle = (outcome: string) => () =>
+          console.log(
+            `[Browser][segments] loader ${loader.loaderId} ${outcome} @ ${Math.round(performance.now())}ms`,
+            { msSinceRequested: Math.round(performance.now() - tapStart) },
+          );
+        loader.loaderData.then(settle("settled"), settle("rejected"));
+      }
+    }
+  }
   return Promise.all(
     loaders.map((loader) =>
       loader.loaderData instanceof Promise