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

package/src/cache/shell-snapshot.ts

@@ -110,6 +110,19 @@ export class RecordingShellStore<
     this.writes.push(p);
   }
 
+  /**
+   * Record a segment-family write into the snapshot WITHOUT touching the inner
+   * store. The shell fast path's implicit doc-cache scope writes through this
+   * (via {@link SnapshotOnlySegmentStore}): the recorded doc entry must ride
+   * ONLY inside the shell entry — a passthrough write would leave a doc-keyed
+   * entry in the real store that the NEXT capture's lookup would hit, replaying
+   * the previous generation's segments instead of re-running handlers (breaking
+   * SWR recapture freshness).
+   */
+  recordSegmentWrite(key: string, data: CachedEntryData): void {
+    this.record("segment", key, data);
+  }
+
   /**
    * Await the tracked deferred writes so their records are present before drain.
    * Drains ITERATIVELY: a write task can schedule a NESTED write (the ring-3
@@ -245,6 +258,40 @@ export function getRecordingStore<TEnv>(
   return store instanceof RecordingShellStore ? store : undefined;
 }
 
+/**
+ * The store the shell fast path's IMPLICIT doc-cache scope resolves during a
+ * capture: reads pass through the recording store (a real-store hit is
+ * recorded, exactly like any capture read), but segment WRITES are recorded
+ * into the snapshot only — see {@link RecordingShellStore.recordSegmentWrite}
+ * for why passthrough would break SWR recapture. Routes with their OWN
+ * cache() config never see this store (their scope resolves the app-level
+ * recording store and keeps today's record-and-write behavior).
+ */
+export class SnapshotOnlySegmentStore<
+  TEnv = unknown,
+> implements SegmentCacheStore<TEnv> {
+  constructor(private readonly recording: RecordingShellStore<TEnv>) {}
+
+  get defaults(): SegmentCacheStore<TEnv>["defaults"] {
+    return this.recording.defaults;
+  }
+  get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"] {
+    return this.recording.keyGenerator;
+  }
+
+  async get(key: string): Promise<CacheGetResult | null> {
+    return this.recording.get(key);
+  }
+
+  async set(key: string, data: CachedEntryData): Promise<void> {
+    this.recording.recordSegmentWrite(key, data);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.recording.delete(key);
+  }
+}
+
 /**
  * Materialize the loader-family seed from a shell snapshot for a HIT's tail
  * render: Flight-deserialize each recorded (promise-elided) bake-lane

package/src/cache/types.ts

@@ -225,10 +225,13 @@ export interface CacheItemResult {
  * One entry carries BOTH artifacts a resume needs — the rendered HTML prelude
  * and React's postponed state — because the pair is version- and
  * generation-coupled and must never be mixed across a React upgrade or a build
- * change. The reactVersion field is the read-time gate that enforces that: the
- * shell-cache middleware treats an entry whose reactVersion differs from the
- * running React as a miss (the postponed blob is build-coupled and cannot be
- * resumed by a different React).
+ * change. The reactVersion and buildVersion fields are the read-time gates that
+ * enforce both halves: isValidShellHit (rsc/shell-serve.ts) treats an entry
+ * whose reactVersion differs from the running React, or whose buildVersion
+ * differs from the running build, as a miss (the postponed blob encodes hole
+ * positions against one exact tree; resuming it against a different React or a
+ * different app build tree-mismatches inside resume(), AFTER the 200 + prelude
+ * are committed — an unrecoverable broken serve).
  */
 export interface ShellCacheEntry {
   /** Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing). */
@@ -240,6 +243,17 @@ export interface ShellCacheEntry {
   postponed: string | null;
   /** React.version captured at prerender time; the read-time invalidation gate. */
   reactVersion: string;
+  /**
+   * Build version captured at prerender time (the RSC handler's `version` —
+   * the `@rangojs/router:version` build stamp by default, bumped per build and
+   * on dev RSC-module edits). The second read-time gate: a persistent shared
+   * store (KV/runtime-cache) survives deploys, and an app-code change that
+   * keeps the same React version would otherwise leave a stale-build
+   * prelude+postponed live under the same key. Optional only for entries
+   * stored before the field existed — those are treated as a miss and the
+   * recapture re-stamps them (pre-release, no compat shim).
+   */
+  buildVersion?: string;
   /**
    * The initialTheme the CAPTURE render was built with (the derived context's
    * reqCtx.theme). The resume tail must render ThemeProvider with the SAME
@@ -266,6 +280,19 @@ export interface ShellCacheEntry {
    * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
    */
   snapshot?: ShellSnapshotRecord[];
+  /**
+   * True when the capture's HANDLER layer declared per-request liveness: a
+   * handle pushed OUTSIDE a DSL loader scope carried a nested thenable (the
+   * capture mask turns it into a never-filling hole), such a push was still
+   * pending when the entry was written, or a handler-invoked loader
+   * (ctx.use(loader) from a handler body — the consumption lane, #672)
+   * executed during the capture. The serve tail then must NOT take the
+   * handler-free fast path (the implicit doc-cache hit): only a handler
+   * re-run can mint that hole's live promise or refresh that consumed value.
+   * DSL-loader pushes never set this — loaders re-run fresh on every HIT, so
+   * their holes always fill.
+   */
+  handlerLiveHoles?: boolean;
   /** Epoch ms when the shell was captured. */
   createdAt: number;
 }

package/src/cache/vercel/vercel-cache-store.ts

@@ -177,6 +177,8 @@ interface VercelShellEnvelope {
   po: string | null;
   /** React.version at capture. */
   rv: string;
+  /** Build version at capture (ShellCacheEntry.buildVersion). */
+  bv?: string;
   /** createdAt (ms since epoch). */
   c: number;
   /** staleAt (ms since epoch). */
@@ -776,6 +778,7 @@ export class VercelCacheStore<
         prelude: env.p,
         postponed: env.po,
         reactVersion: env.rv,
+        buildVersion: env.bv,
         initialTheme: env.i,
         snapshot: env.sn,
         createdAt: env.c,
@@ -805,6 +808,7 @@ export class VercelCacheStore<
         p: entry.prelude,
         po: entry.postponed,
         rv: entry.reactVersion,
+        bv: entry.buildVersion,
         c: entry.createdAt,
         s: staleAt,
         e: expiresAt,
@@ -1091,7 +1095,7 @@ export class VercelCacheStore<
 
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
-    const { p, po, rv, c, s, e, t, i, sn } = raw;
+    const { p, po, rv, bv, c, s, e, t, i, sn } = raw;
     if (typeof p !== "string" || typeof rv !== "string") return null;
     if (po !== null && typeof po !== "string") return null;
     if (typeof c !== "number") return null;
@@ -1100,6 +1104,7 @@ export class VercelCacheStore<
       p,
       po: po as string | null,
       rv,
+      bv: typeof bv === "string" ? bv : undefined,
       c,
       s,
       e,

package/src/deps/ssr.ts

@@ -1 +1,4 @@
-export { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
+export {
+  createFromReadableStream,
+  setOnClientReference,
+} from "@vitejs/plugin-rsc/ssr";

package/src/router/loader-resolution.ts

@@ -430,6 +430,22 @@ function createLoaderExecutor<TEnv>(
     // nested deps inherit isDslLoader=false only when the CHAIN started in a
     // handler; a chain started by the segment funnel stays DSL (the loader
     // scope ALS survives the body's awaits).
+    // Shell fast path eligibility: a HANDLER-invoked loader executing during a
+    // capture is handler-layer dynamism — on a handler-free (replayed) HIT it
+    // would never re-run, freezing its consumption-lane value (#672's "fresh
+    // per serve" slot shape). Mark the capture; the entry declines the fast
+    // path and keeps the full tail. DSL loaders re-run on every HIT and never
+    // set this.
+    if (!isDslLoader) {
+      const captureCtx = _getRequestContext();
+      if (
+        captureCtx?._shellCaptureRun &&
+        captureCtx._shellCaptureHandleLiveness
+      ) {
+        captureCtx._shellCaptureHandleLiveness.handlerInvokedLoader = true;
+      }
+    }
+
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
       Promise.resolve(
         runInsideLoaderBodyScope(

package/src/router/match-api.ts

@@ -1,4 +1,8 @@
-import { CacheScope, createCacheScope } from "../cache/cache-scope.js";
+import {
+  CacheScope,
+  createCacheScope,
+  resolveShellImplicitCacheScope,
+} from "../cache/cache-scope.js";
 import { RouteNotFoundError } from "../errors";
 import {
   createErrorInfo,
@@ -180,7 +184,10 @@ export async function createMatchContextForFull<TEnv>(
     },
     isSameRouteNavigation: false,
     interceptResult: null,
-    cacheScope: snapshot.cacheScope,
+    // Shell fast path: a capture or an eligible HIT tail may substitute an
+    // implicit doc-level scope (marker-gated; a route-derived scope wins).
+    // Full matches only — partial navigations never serve a shell.
+    cacheScope: resolveShellImplicitCacheScope(snapshot.cacheScope),
     isIntercept: false,
     actionContext: undefined,
     isAction: false,

package/src/router/match-handlers.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { sanitizeError } from "../errors";
 import type { ErrorInfo, ErrorPhase, MatchResult } from "../types";
 import type {
@@ -291,7 +292,13 @@ export function createMatchHandlers<TEnv = any>(
           });
           emitter.start();
 
+          const ctxBuildStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
           const result = await createMatchContextForFull(request, env);
+          if (INTERNAL_RANGO_DEBUG) {
+            console.log(
+              `[Server][match] context built +${Math.round(performance.now() - ctxBuildStart)}ms (abs ${Math.round(performance.now())})`,
+            );
+          }
 
           if ("type" in result && result.type === "redirect") {
             emitter.end(0, false);
@@ -310,7 +317,13 @@ export function createMatchHandlers<TEnv = any>(
           try {
             const state = createPipelineState();
             const pipeline = createMatchPartialPipeline(ctx, state);
+            const pipeStart = INTERNAL_RANGO_DEBUG ? performance.now() : 0;
             const matchResult = await collectMatchResult(pipeline, ctx, state);
+            if (INTERNAL_RANGO_DEBUG) {
+              console.log(
+                `[Server][match] pipeline collected +${Math.round(performance.now() - pipeStart)}ms (abs ${Math.round(performance.now())})`,
+              );
+            }
             if (hasTelemetry || cacheSignalEnabled) {
               const signalSegments = buildSignal(ctx.routeKey, state);
               recordSignalIfEnabled(signalSegments);

package/src/router/segment-resolution/loader-cache.ts

@@ -36,7 +36,10 @@ import {
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
-import { overlayLoaderContainer } from "./loader-snapshot.js";
+import {
+  maskNestedContainerThenables,
+  overlayLoaderContainer,
+} from "./loader-snapshot.js";
 import { recordRequestTags } from "../../cache/cache-tag.js";
 import {
   isShellCaptureActive,
@@ -162,8 +165,21 @@ export function resolveLoaderData<TEnv>(
     // never as an unhandled rejection that can kill the worker before the
     // drain probes this record.
     containerPromise.catch(() => {});
-    reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, containerPromise);
-    return containerPromise;
+    // Nested-promise SHAPE is the liveness declaration: mask nested thenables
+    // in the capture's copy of the container so the consuming subtree
+    // postpones as a hole no matter when the promise settles, elide records a
+    // HOLE marker, and every HIT streams the fresh value. Without this, a
+    // nested promise that settled before the quiet window baked its value into
+    // the SHARED shell and the snapshot pinned it for every visitor
+    // (per-request basket data served cross-session, found live). The raw
+    // container is untouched: handler-side ctx.use consumption (the
+    // consumption-lane rule, semantic-matrix PPR3) keeps real values.
+    const maskedPromise = containerPromise.then((container: unknown) =>
+      maskNestedContainerThenables(container),
+    );
+    maskedPromise.catch(() => {});
+    reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, maskedPromise);
+    return maskedPromise;
   }
 
   if (bakeSegmentKey) {

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

@@ -36,17 +36,10 @@ export function isShellCaptureActive(
   return reqCtx?._shellCaptureRun === true;
 }
 
-/**
- * A promise that never settles — the masked stand-in for a loader's 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>(() => {});
-}
+// createMaskedLoaderPromise moved to the leaf module mask-nested.ts (shared
+// with the handle-push funnel in request-context, which cannot import THIS
+// module without a cycle). Re-exported to keep the mask API in one place.
+export { createMaskedLoaderPromise } from "./mask-nested.js";
 
 /**
  * Lane decision for an entry's loaders under PPR (the loading() value decides;

package/src/router/segment-resolution/loader-snapshot.ts

@@ -8,12 +8,14 @@
  * payload byte-identical to that frozen prelude, the capture pins the container
  * in the shell snapshot:
  *
- *   - elide:   deep-walk the settled container; a SETTLED nested promise baked
- *              its value (physics: it won the quiet window), so it is pinned as
- *              that value wrapped in a SETTLED marker — the wrapper remembers
- *              "this was a promise" so the overlay can rehydrate the shape; a
- *              PENDING nested promise is a hole, replaced by
- *              {@link LOADER_HOLE_KEY}. The result is promise-free and
+ *   - elide:   deep-walk the settled container; a PENDING nested promise is a
+ *              hole, replaced by {@link LOADER_HOLE_KEY} — and since
+ *              loader-cache masks every nested thenable at capture
+ *              ({@link maskNestedContainerThenables}), nested promises are
+ *              ALWAYS pending here for new captures. The SETTLED-marker branch
+ *              below is legacy: it fires only if a settled thenable reaches
+ *              elide anyway, and the overlay keeps decoding SETTLED markers
+ *              from pre-mask snapshots. The result is promise-free and
  *              Flight-serializable.
  *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
  *              the live nested promises), then the recorded container is laid
@@ -28,6 +30,12 @@
 
 import { isThenable } from "../../handles/is-thenable.js";
 
+// Capture-side nested-thenable masking lives in the LEAF module mask-nested.ts
+// (request-context also needs it for handle pushes and cannot import through
+// loader-mask without a cycle). Re-exported here so loader-cache and the unit
+// tests keep one import site for the snapshot family.
+export { maskNestedContainerThenables } from "./mask-nested.js";
+
 /**
  * Marker object standing in for a pending nested promise in a recorded loader
  * container. Shape-checked (not identity-checked) because the record round-trips

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

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ */
+/**
+ * Optional single-walk report for maskNestedContainerThenables: `thenable`
+ * flips true when the walk masked at least one thenable. The shell fast path
+ * reads it at handle-push time — a pushed container with a nested thenable
+ * declares per-request data, and a shell entry whose HANDLER layer made such
+ * a declaration cannot be served handler-free (the hole would never fill).
+ * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ */
+export interface MaskReport {
+  thenable: boolean;
+}
+
+export function maskNestedContainerThenables(
+  value: unknown,
+  seen: Map<object, unknown> = new Map(),
+  report?: MaskReport,
+): unknown {
+  if (isThenable(value)) {
+    if (report) report.thenable = true;
+    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, report);
+    }
+    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, report);
+    }
+    return out;
+  }
+
+  return value;
+}