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

package/src/rsc/rsc-rendering.ts

@@ -38,12 +38,17 @@ import {
   resolvePprConfig,
   buildShellKey,
   isValidShellHit,
+  hasIntactShellPayload,
   base64ToBytes,
   hasShellFamily,
   warnShellStoreMissingOnce,
   warnPprNonceActiveOnce,
 } from "./shell-serve.js";
 import { contextGet } from "../context-var.js";
+import {
+  resolveSameOriginRedirect,
+  safeSameOriginLanding,
+} from "../redirect-origin.js";
 import { nonce as nonceToken } from "./nonce.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
@@ -160,6 +165,7 @@ async function handleRscRenderingInner<TEnv>(
         ) {
           const descriptor: ShellCaptureDescriptor = {
             key,
+            buildVersion: ctx.version,
             ttl: pprConfig.ttl,
             swr: pprConfig.swr,
             tags: pprConfig.tags,
@@ -173,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.
@@ -413,6 +435,29 @@ async function handleRscRenderingInner<TEnv>(
   return response;
 }
 
+/**
+ * Neutralize the shell-HIT degradation redirect target.
+ *
+ * The inline `location.replace` emitted by serveShellHit when a shell HIT lands
+ * on a URL whose route became redirecting mid-TTL is a document-native redirect
+ * exit that BYPASSES the 3xx chokepoint (guardOutgoingRedirect acts only on 3xx
+ * + Location responses, never a committed 200 body). So it reuses the ONE
+ * same-origin resolver directly: a cross-origin/unparseable/unsafe target
+ * neutralizes to the same safe same-origin landing as redirect-guard.ts
+ * (basename root, or "/" when unset) rather than navigating the user off-host.
+ * A safe same-origin/relative target passes through as its normalized href.
+ */
+export function resolveShellHitRedirectTarget(
+  rawTarget: string,
+  requestOrigin: string,
+  basename: string | undefined,
+): string {
+  return (
+    resolveSameOriginRedirect(rawTarget, requestOrigin) ??
+    safeSameOriginLanding(basename)
+  );
+}
+
 /**
  * Serve a validated shell HIT: commit the composed response NOW — the stored
  * prelude bytes are the first thing on the wire — and run the live tail
@@ -441,6 +486,7 @@ function serveShellHit(
   handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   ssrModule: SSRModule,
   entry: ShellCacheEntry,
+  descriptor: ShellCaptureDescriptor,
 ): Response {
   const preludeBytes = base64ToBytes(entry.prelude);
 
@@ -466,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,
@@ -514,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 {
@@ -535,15 +615,39 @@ function serveShellHit(
           // a shell (capture bails on redirects), so a HIT on a redirecting URL
           // requires the route to have BECOME redirecting within the shell TTL.
           // The 200 + prelude are already committed; degrade to a client-side
-          // replace so the user still lands on the target.
+          // replace so the user still lands on the target. The target is
+          // neutralized first (see resolveShellHitRedirectTarget).
+          const safeTarget = resolveShellHitRedirectTarget(
+            tail.redirect,
+            url.origin,
+            ctx.router.basename,
+          );
           controller.enqueue(
             new TextEncoder().encode(
-              `<script>location.replace(${JSON.stringify(tail.redirect)})</script>`,
+              `<script>location.replace(${JSON.stringify(safeTarget)})</script>`,
             ),
           );
         }
         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,
@@ -327,6 +329,39 @@ function warnCaptureRefusedOnce(key: string, reason: string): void {
   );
 }
 
+/** Keys already warned about untagged bake-lane data baked into the shell. */
+const warnedUntaggedShellBakes = new Set<string>();
+
+/**
+ * Warn once per shell key that a bake-lane loader baked material into the shell
+ * but the capture recorded ZERO tags (no render-collected _requestTags, no
+ * static ppr.tags). Such data is frozen in the shared shell until TTL and is
+ * un-evictable by tag: a server action refreshes the CLIENT only (rotates Rango
+ * state, busts the browser HTTP cache) and never touches the server shell store,
+ * and updateTag()/revalidateTag() cannot drop data that was baked WITHOUT a tag.
+ *
+ * Coarse per-shell-key signal, not per-loader attribution — the tag set is
+ * unioned globally at the write barrier, not tracked per loader, so we cannot
+ * name the offending loader without adding attribution plumbing (deliberately
+ * not done). Dev-only + once-per-key so it never spams production or fires on
+ * every capture.
+ */
+function warnUntaggedShellBakeOnce(key: string): void {
+  if (warnedUntaggedShellBakes.has(key)) return;
+  warnedUntaggedShellBakes.add(key);
+  console.warn(
+    `[rango] Shell capture for "${key}" baked bake-lane loader data into the ` +
+      "shell with NO cache tag. That data is frozen in the shared shell until " +
+      "TTL and cannot be tag-invalidated: a server action refresh touches the " +
+      "client only (not the server shell store), and updateTag() cannot evict " +
+      "data that was baked without a tag.\n" +
+      'Fix: tag the data (cacheTag() / "use cache" / cache({ tags })) so ' +
+      "updateTag() drops the shell, or move the volatile read under a loading() " +
+      "hole so it stays on the live lane and is never baked. See the /ppr skill " +
+      "(node_modules/@rangojs/router/skills/ppr/SKILL.md).",
+  );
+}
+
 export interface FlightCaptureGate {
   /** Identity passthrough of the source stream; feed this to captureShellHTML. */
   stream: ReadableStream<Uint8Array>;
@@ -487,12 +522,22 @@ export function gateFlightForCapture(
  * store, and passed to scheduleShellCapture directly — it is NOT threaded through
  * the request context. `tags` carries the route's OPERATIONAL `ppr.tags`; the
  * capture UNIONS them with the shell's own auto-collected (non-loader) request
- * tags from its derived render (the collected set stays authoritative). `store`
- * is the same store the serve path resolved for its getShell read
- * (requestCtx._cacheStore), so the capture writes where the serve reads.
+ * tags from its derived render (the collected set stays authoritative). That
+ * union happens at the putShell WRITE BARRIER in captureAndStoreShell — after the
+ * capture quiesces — not at stream construction, so a tag recorded after an await
+ * in async shell content is still collected (issue #676). `store` is the same
+ * store the serve path resolved for its getShell read (requestCtx._cacheStore),
+ * so the capture writes where the serve reads.
  */
 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[];
@@ -708,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;
@@ -776,24 +843,18 @@ async function attemptCapture(
       },
     });
 
-    // Shell tags = the non-loader request tags the capture render recorded on its
-    // own fresh _requestTags (loaders are masked, so loader cache tags — which
-    // belong to the holes, not the shell — are correctly excluded), UNIONED with
-    // the middleware's operational `tags` option (descriptor.tags). The collected
-    // set is authoritative; the option only adds tags the render cannot know.
-    const collected = [...derivedCtx._requestTags];
-    const union = new Set<string>([...(descriptor.tags ?? []), ...collected]);
-    const tags = union.size > 0 ? [...union] : undefined;
-
+    // 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,
-        tags,
-      },
+      descriptor,
     );
   });
 }
@@ -878,11 +939,25 @@ async function captureAndStoreShell(
   const refuseOnGuardTrip = (): "refused" | undefined => {
     const fnName = reqCtx._shellCaptureGuardTripped;
     if (!fnName) return undefined;
+    // Name the recorded source instead of hardcoding a lane. Under the
+    // consumption-lane rule, handler-INVOKED loader bodies are exempt from
+    // the guard (their value is a baked shared copy, mirroring cache()), so a
+    // trip can only come from a bake-lane SEGMENT loader or from non-loader
+    // handler/render code — the old blanket "bake-lane loader" attribution
+    // sent a live-lane debugging session down the wrong lane (issue #672).
+    const loaderId = reqCtx._shellCaptureGuardTrippedLoaderId;
+    const origin = loaderId
+      ? `segment loader "${loaderId}"`
+      : "handler/render code (no loader body was executing)";
     warnCaptureRefusedOnce(
       capture.key,
-      `a bake-lane loader (a loader on an entry with no loading()) called ${fnName}() during capture. ` +
-        "Identity must not bake into a shared shell. Give that loader's entry a loading() boundary " +
-        "(the live lane, exempt from the guard) or move the identity-dependent part into a nested promise.",
+      `${origin} called ${fnName}() during capture. Identity must not bake into a shared shell. ` +
+        "For a segment loader (bake lane, no loading()): give its entry a loading() boundary " +
+        "(the live lane, masked at capture) or move the identity-dependent part into a nested " +
+        "promise. For handler/render code: keep the value live by consuming a loader " +
+        'client-side (useLoader in a "use client" component). Note: `await ctx.use(loader)` ' +
+        "inside a HANDLER is exempt from this guard — its value bakes into the shared shell " +
+        "as a capture-time copy, mirroring cache() semantics (the consumption-lane rule).",
     );
     return "refused";
   };
@@ -981,6 +1056,10 @@ async function captureAndStoreShell(
     // gate above already returned no-shell) or postponed under an ANCESTOR
     // boundary (it is a hole; omitting the record keeps it live).
     const loaderRecords = reqCtx._shellCaptureLoaderRecords;
+    // Set once a bake-lane loader settles with real (non-hole) material: its data
+    // is frozen into the shell prelude regardless of whether snapshot
+    // serialization succeeds. Drives the untagged-bake dev warning below.
+    let bakedLoaderMaterial = false;
     if (loaderRecords && loaderRecords.size > 0) {
       // The codec import is deferred past the elide probes: a rejected record
       // refuses and a never-settled record is omitted WITHOUT touching Flight
@@ -1001,6 +1080,9 @@ async function captureAndStoreShell(
         // The container itself never settled: it is a hole (under an ancestor
         // boundary) or the trivial-prelude gate already fired. Omit — no pin.
         if (isLoaderHoleMarker(elided.value)) continue;
+        // Past the hole check: this container settled with real material that
+        // bakes into the shell prelude (independent of the snapshot pin below).
+        bakedLoaderMaterial = true;
         try {
           // serializeResult (not rscSerialize): null is a valid container and
           // must round-trip; serializeResult preserves it through Flight.
@@ -1021,6 +1103,28 @@ async function captureAndStoreShell(
       }
     }
 
+    // Shell tags snapshot at the WRITE BARRIER, not at stream construction: by
+    // here the capture has quiesced and the deferred cache writes were awaited, so
+    // tags recorded AFTER an await in async shell content (and by async
+    // cache()/"use cache" reads propagating through recordRequestTags) are
+    // included — issue #676. Loaders are masked, so loader cache tags — which
+    // belong to the holes, not the shell — never execute during capture and cannot
+    // contribute. Union with the route's static ppr.tags (capture.tags); the
+    // collected set is authoritative, the option only adds what the render cannot
+    // know.
+    const collected = [...reqCtx._requestTags];
+    const union = new Set<string>([...(capture.tags ?? []), ...collected]);
+    const shellTags = union.size > 0 ? [...union] : undefined;
+
+    // Untagged-bake diagnostic: a bake-lane loader froze mutable data into the
+    // shell but nothing tags the entry, so it is un-invalidatable except by TTL —
+    // a read-your-own-writes gap on the document channel (an action refresh skips
+    // the server shell; updateTag cannot drop untagged data). Coarse per-shell-key
+    // signal; dev-only and once-per-key so it never spams production.
+    if (isDevMode() && bakedLoaderMaterial && shellTags === undefined) {
+      warnUntaggedShellBakeOnce(capture.key);
+    }
+
     const store = capture.store ?? reqCtx._cacheStore;
     if (store?.putShell) {
       try {
@@ -1031,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
@@ -1044,7 +1149,7 @@ async function captureAndStoreShell(
           entry,
           capture.ttl,
           capture.swr,
-          capture.tags,
+          shellTags,
         );
       } catch (error) {
         // Best-effort: a failed put must never throw out of the background task.

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