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

package/src/router/segment-resolution/mask-nested.ts

@@ -0,0 +1,83 @@
+/**
+ * Capture-side nested-thenable masking — the mechanism behind "nested-promise
+ * shape is the liveness declaration" for BOTH bake-lane loader containers
+ * (loader-cache.ts) and pushed handle containers (request-context.ts
+ * createUseFunction).
+ *
+ * Deliberately a LEAF module: request-context needs the mask for handle
+ * pushes, and loader-mask (the other natural home) imports request-context —
+ * importing from there would cycle. This module imports only is-thenable.
+ */
+
+import { isThenable } from "../../handles/is-thenable.js";
+
+/**
+ * A promise that never settles — the masked stand-in for a per-request value
+ * during shell capture. The consuming Suspense subtree suspends forever, so
+ * the static prerender postpones it as a hole instead of baking a per-request
+ * value into the shared shell. The capture abort (`maxWaitMs` in
+ * captureShellHTML) bounds how long the prerender waits before it freezes the
+ * prelude, so this never hangs the request.
+ */
+export function createMaskedLoaderPromise<T = unknown>(): Promise<T> {
+  return new Promise<T>(() => {});
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Deep-copy a container with every NESTED thenable replaced by a masked
+ * (never-resolving) promise. Applied during shell capture to (a) bake-lane
+ * loader containers (loader-cache.ts) and (b) pushed handle containers
+ * (createUseFunction) — the two rango-owned funnels where consumers declare
+ * per-request data by promise SHAPE.
+ *
+ * Why: a nested promise that happened to SETTLE before the capture's quiet
+ * window closed used to bake its value into the SHARED shell (and, for
+ * loaders, the snapshot pinned it for every HIT) — per-request data frozen
+ * and served cross-session (found live: a storefront basket, carrying the
+ * capturing session's basketId/customer identifiers, served to anonymous
+ * visitors). The window waits for the slowest shared material on the page, so
+ * any real data source (a 5ms SQL read, a 200ms basket API) lost the race.
+ * Masking makes the consuming subtree postpone as a hole no matter when the
+ * promise settles: liveness by declaration, not by racing the window.
+ *
+ * Only plain objects/arrays are traversed; other values are leaves. The INPUT
+ * IS NEVER MUTATED — handler-side loader consumption (the consumption-lane
+ * rule, semantic-matrix PPR3) shares the raw container and must keep real
+ * values. Cycles are preserved as cycles in the copy.
+ */
+export function maskNestedContainerThenables(
+  value: unknown,
+  seen: Map<object, unknown> = new Map(),
+): unknown {
+  if (isThenable(value)) return createMaskedLoaderPromise();
+
+  if (Array.isArray(value)) {
+    const cached = seen.get(value);
+    if (cached !== undefined) return cached;
+    const out: unknown[] = new Array(value.length);
+    seen.set(value, out);
+    for (let i = 0; i < value.length; i++) {
+      out[i] = maskNestedContainerThenables(value[i], seen);
+    }
+    return out;
+  }
+
+  if (isPlainObject(value)) {
+    const cached = seen.get(value);
+    if (cached !== undefined) return cached;
+    const out: Record<string, unknown> = {};
+    seen.set(value, out);
+    for (const key of Object.keys(value)) {
+      out[key] = maskNestedContainerThenables(value[key], seen);
+    }
+    return out;
+  }
+
+  return value;
+}

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,6 +486,7 @@ function serveShellHit(
   handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   ssrModule: SSRModule,
   entry: ShellCacheEntry,
+  descriptor: ShellCaptureDescriptor,
 ): Response {
   const preludeBytes = base64ToBytes(entry.prelude);
 
@@ -493,11 +512,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`,
+              );
+            }
+            controller.enqueue(chunk);
+          },
+        }),
+      );
+    }
     return observePhase(PHASES.ssr, () =>
       ssrModule.resumeShellHTML!(rscStream, {
         postponed: entry.postponed,
@@ -541,17 +581,30 @@ 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 (tail instanceof ReadableStream) {
           const reader = tail.getReader();
+          let firstTailChunk = true;
           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`,
+                );
+              }
               controller.enqueue(value);
             }
           } finally {
@@ -577,6 +630,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,8 @@ import {
   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 { isThenable } from "../handles/is-thenable.js";
 import type {
   ShellCacheEntry,
   SegmentCacheStore,
@@ -529,6 +531,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[];
@@ -744,6 +753,28 @@ 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.
+  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);
+    rawCapturePush(handleName, segmentId, masked);
+  };
 
   const derivedCtx: RequestContext = Object.create(reqCtx);
   derivedCtx._handleStore = freshHandleStore;
@@ -1104,6 +1135,7 @@ 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

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

package/src/segment-system.tsx

@@ -17,6 +17,22 @@ import {
   getMemoizedLoaderPromise,
 } 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.
+ */
+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 (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}
+
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
 const ReactViewTransition: any =
@@ -212,6 +228,17 @@ export async function renderSegments(
     rootLayout: RootLayout,
   } = options || {};
 
+  const segDebug = INTERNAL_RANGO_DEBUG && typeof window === "object";
+  const segDebugStart = segDebug ? performance.now() : 0;
+  if (segDebug) {
+    segDebugLog("renderSegments start", {
+      segments: segments.map((s) => `${s.id}:${s.type}`),
+      isAction: !!isAction,
+      forceAwait: !!forceAwait,
+      intercepts: interceptSegments?.length ?? 0,
+    });
+  }
+
   const temporalLazyRefs: Promise<any>[] = [];
   const normalizedSegments = restoreParallelLoaderMarkers(segments);
   const normalizedInterceptSegments = interceptSegments
@@ -273,6 +300,15 @@ export async function renderSegments(
     );
     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),
+      });
+    }
+
     // Param-agnostic keys are opt-in via the transition() DSL (see
     // inTransitionScope above). A route (and its route-owned layouts) inside a
     // transition scope drops the param from its key, so navigating between two
@@ -403,10 +439,25 @@ export async function renderSegments(
 
     if (loading !== undefined && loading !== null) {
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
+      let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
+      if (forceAwait || isAction) {
+        const awaitStart = segDebug ? performance.now() : 0;
+        boundaryLoaderData = await loaderDataPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: loaders awaited (forceAwait/action)`, {
+            loaderIds,
+            ms: Math.round(performance.now() - awaitStart),
+          });
+        }
+      } else if (segDebug) {
+        segDebugLog(
+          `segment ${id}: streaming loaders via LoaderBoundary (suspense)`,
+          { loaderIds },
+        );
+      }
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
-        loaderDataPromise:
-          forceAwait || isAction ? await loaderDataPromise : loaderDataPromise,
+        loaderDataPromise: boundaryLoaderData,
         loaderIds,
         fallback: loading,
         outletKey: key,
@@ -430,7 +481,17 @@ export async function renderSegments(
       );
 
       const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
+      // No loading() on this segment, so its loader data cannot stream behind
+      // a Suspense fallback — the tree build BLOCKS here until the data
+      // arrives. On the initial document this await runs before hydrateRoot.
+      const layoutAwaitStart = segDebug ? performance.now() : 0;
       const resolvedData = await buildLoaderPromise(layoutLoaders);
+      if (segDebug) {
+        segDebugLog(`segment ${id}: layout loaders awaited (blocking)`, {
+          loaderIds: layoutLoaderIds,
+          ms: Math.round(performance.now() - layoutAwaitStart),
+        });
+      }
       const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
         layoutLoaderIds,
@@ -463,10 +524,27 @@ export async function renderSegments(
 
           p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
           const aggregated = getMemoizedLoaderPromise(ownedLoaders);
-          p.loaderDataPromise =
-            (forceAwait || isAction) && aggregated instanceof Promise
-              ? await aggregated
-              : aggregated;
+          if ((forceAwait || isAction) && aggregated instanceof Promise) {
+            const parallelAwaitStart = segDebug ? performance.now() : 0;
+            p.loaderDataPromise = await aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders awaited (forceAwait/action)`,
+                {
+                  loaderIds: p.loaderIds,
+                  ms: Math.round(performance.now() - parallelAwaitStart),
+                },
+              );
+            }
+          } else {
+            p.loaderDataPromise = aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders streaming (suspense)`,
+                { loaderIds: p.loaderIds },
+              );
+            }
+          }
         }
       }
 
@@ -524,6 +602,12 @@ export async function renderSegments(
     });
   }
 
+  if (segDebug) {
+    segDebugLog("renderSegments complete", {
+      ms: Math.round(performance.now() - segDebugStart),
+    });
+  }
+
   return result;
 }
 

package/src/ssr/index.tsx

@@ -1,5 +1,6 @@
 import React from "react";
 import { createSsrRootComponent } from "./ssr-root.js";
+import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
 import type { ErrorPhase } from "../types.js";
 
 /**
@@ -594,7 +595,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
 export function createShellResumeHandler<TEnv = unknown>(
   deps: SSRDependencies<TEnv>,
 ) {
-  const { createFromReadableStream, injectRSCPayload, resume, onError } = deps;
+  const { createFromReadableStream, resume, onError } = deps;
 
   /**
    * @param rscStream - Fresh full Flight stream for this request.
@@ -609,11 +610,12 @@ export function createShellResumeHandler<TEnv = unknown>(
     try {
       if (postponed === null) {
         // DATA variant: the stored prelude is the complete shell. No fizz runs;
-        // feed injectRSCPayload a minimal HTML stream so its flush appends the
-        // fresh Flight payload scripts after the shell. The stream must emit at
-        // least one chunk — see createDataVariantHtmlStream.
+        // the eager injector pumps the fresh Flight payload scripts without
+        // needing an HTML chunk to trigger it (the stock injector deadlocked on
+        // a chunkless stream — see createDataVariantHtmlStream, kept for the
+        // batching invariant's sake).
         return createDataVariantHtmlStream().pipeThrough(
-          injectRSCPayload(rscStream, { nonce }),
+          injectRSCPayloadEager(rscStream, { nonce }),
         );
       }
 
@@ -640,7 +642,14 @@ export function createShellResumeHandler<TEnv = unknown>(
         nonce,
       });
 
-      return resumed.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
+      // EAGER injection (resume-only): the stored prelude — a complete document
+      // through </body></html> — is already on the wire ahead of this stream,
+      // so a Flight <script> is valid as the first tail byte. The stock
+      // injector waits for the first fizz chunk, which only appears when the
+      // first hole's loaders resolve — parking the whole hydration payload
+      // (root row included) behind the slowest live loader. See
+      // inject-rsc-eager.ts for the measured failure mode.
+      return resumed.pipeThrough(injectRSCPayloadEager(rscStream2, { nonce }));
     } catch (error) {
       reportRenderError(onError, error);
       throw error;