@rangojs/router 0.22.1 → 0.23.0

package/src/router/match-middleware/cache-lookup.ts

@@ -99,6 +99,10 @@ import { observeEvent } from "../instrument.js";
 import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
 import { treeHasStreaming } from "./segment-resolution.js";
 import { loaderPins } from "../segment-resolution/loader-cache.js";
+import {
+  defersAboveRecord,
+  isFillRequest,
+} from "../segment-resolution/prefetch-deferral.js";
 import type { PrerenderStore, PrerenderEntry } from "../../prerender/store.js";
 import {
   isStoredEntryStale,
@@ -342,15 +346,18 @@ async function* yieldFromStore<TEnv>(
   const paramsChanged =
     !ctx.isFullMatch && !paramsEqual(ctx.matched.params, ctx.prevParams);
   const resendRouteSegments = replaceable === true && ctx.isAction;
+  // A fill (prefetch-deferral.ts) keeps every segment the client holds.
+  const fill = isFillRequest(ctx.handlerContext);
   for (const segment of segments) {
     if (
       !ctx.isFullMatch &&
-      !paramsChanged &&
       ctx.clientSegmentSet.has(segment.id) &&
-      !(
-        resendRouteSegments &&
-        (segment.type === "route" || segment.belongsToRoute === true)
-      )
+      (fill ||
+        (!paramsChanged &&
+          !(
+            resendRouteSegments &&
+            (segment.type === "route" || segment.belongsToRoute === true)
+          )))
     ) {
       keepClientSegment(segment);
     }
@@ -725,7 +732,15 @@ export function withCacheLookup<TEnv>(
       throw new ShellRecordUnavailableError(tailMarker.fixedDocKey);
     }
 
-    if (ctx.isAction || !ctx.cacheScope?.enabled) {
+    // A prefetch that defers a layout above the boundary (prefetch: false)
+    // emits nothing the record holds: reading it would replay the handle
+    // pushes of segments the response does not carry. withCacheStore skips
+    // the write for the same request.
+    if (
+      ctx.isAction ||
+      !ctx.cacheScope?.enabled ||
+      defersAboveRecord(ctx.handlerContext)
+    ) {
       yield* source;
       if (ms) {
         ms.metrics.push({
@@ -897,6 +912,7 @@ export function withCacheLookup<TEnv>(
 
     yield* liveSegments;
 
+    const fill = isFillRequest(ctx.handlerContext);
     for (const segment of cacheResult.segments) {
       if (!ctx.clientSegmentSet.has(segment.id)) {
         if (isTraceActive()) {
@@ -919,6 +935,13 @@ export function withCacheLookup<TEnv>(
         continue;
       }
 
+      // A fill (prefetch-deferral.ts) skips a held segment outright.
+      if (fill) {
+        keepClientSegment(segment);
+        yield segment;
+        continue;
+      }
+
       const entryInfo = entryRevalidateMap?.get(segment.id);
 
       const searchChanged = ctx.prevUrl.search !== ctx.url.search;

package/src/router/match-middleware/cache-store.ts

@@ -114,6 +114,10 @@ import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 import { rerenderAndCacheRoute } from "./background-revalidation.js";
+import {
+  defersAboveRecord,
+  isFillRequest,
+} from "../segment-resolution/prefetch-deferral.js";
 
 /**
  * Creates cache store middleware
@@ -149,11 +153,15 @@ export function withCacheStore<TEnv>(
     // segments were collected into allSegments either way).
     recordShellCaptureDocRecord(ctx, state, allSegments);
 
+    // prefetch: false (prefetch-deferral.ts). A prefetch that deferred a
+    // layout above the boundary did not read the record (withCacheLookup)
+    // and could only write an incomplete one.
     if (
       !ctx.cacheScope?.enabled ||
       ctx.isAction ||
       state.cacheHit ||
-      ctx.request.method !== "GET"
+      ctx.request.method !== "GET" ||
+      defersAboveRecord(ctx.handlerContext)
     ) {
       if (ms) {
         ms.metrics.push({
@@ -192,6 +200,14 @@ export function withCacheStore<TEnv>(
         cacheScope.covers(s.id, s.namespace),
     );
 
+    // A fill renders what the client is missing and nothing else. When that
+    // is everything the record covers, it writes like any other request.
+    // When the client holds part of it, the write would be partial, and the
+    // proactive re-render below would run handlers a fill must not run. The
+    // stale-hit refresh skips a fill for the same reason
+    // (withBackgroundRevalidation).
+    if (hasNullComponents && isFillRequest(ctx.handlerContext)) return;
+
     const requestCtx = getRequestContext();
     if (!requestCtx) return;
 

package/src/router/match-result.ts

@@ -108,6 +108,7 @@
  *   4. Render slot content if slots present
  */
 import type { MatchResult, ResolvedSegment } from "../types.js";
+import { isPlaceholder } from "../types/segments.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
 import { debugLog } from "./logging.js";
 import { appendMetric } from "./metrics.js";
@@ -229,12 +230,23 @@ export function buildMatchResult<TEnv>(
     allIds = [...new Set(allIds)];
 
     // One pass over allSegments: keep renderable segments and collect the
-    // handler-ran ids (resolvedIds) together.
+    // ids that ran (resolvedIds) together. A partial match resolves only the
+    // loaders it runs (revalidation.ts), so each loader segment here ran:
+    // the browser replaces that loader's handle pushes, and keeps those of a
+    // loader it skipped (handles/pushed-by.ts).
     const clientIdSet = new Set(ctx.clientSegmentIds);
     segmentsToRender = [];
     resolvedIds = [];
     for (const s of allSegments) {
-      if (s._handlerRan) resolvedIds.push(s.id);
+      // A deferred loader (prefetch: false) did not run in this response:
+      // its pushes arrive with the fill, which lists it then.
+      if (s._handlerRan || (s.type === "loader" && !isPlaceholder(s))) {
+        resolvedIds.push(s.id);
+      }
+      // A deferred unit (prefetch: false) has a null component and is sent:
+      // only a segment the client does not hold is ever deferred, and
+      // deferral reads these same ids (prefetch-deferral.ts
+      // PrefetchDeferral.held), not the set the match forces renders with.
       if (
         s.component !== null ||
         s.type === "loader" ||

package/src/router/navigation-snapshot.ts

@@ -1,3 +1,4 @@
+import { isLoaderSegmentId } from "../browser/react/filter-segment-order.js";
 import { requestHeaders } from "../server/request-headers.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 
@@ -145,7 +146,7 @@ export async function resolveNavigation(
 
   const filteredSegmentIds = clientSegmentIds.filter((id) => {
     if (id.includes(".@")) return false;
-    if (/D\d+\./.test(id)) return false;
+    if (isLoaderSegmentId(id)) return false;
     return true;
   });
 

package/src/router/segment-resolution/fresh.ts

@@ -164,17 +164,19 @@ export async function resolveLoaders<TEnv>(
         // key off it.
         ...stampAwaitBeforeFlush(loaderEntry),
         loaderData: deps.wrapLoaderPromise(
-          runInsideLoaderScope(() =>
-            resolveLoaderData(
-              loaderEntry,
-              ctx,
-              ctx.pathname,
-              // The bake key rides for flagged loaders too: ssr:false
-              // bakes at capture regardless of the entry's loading() lane
-              // (loader-cache.ts capture branch) and its HIT-tail seed
-              // overlay needs the same key.
-              bakeLane || loaderEntry.bake === true ? segmentId : null,
-            ),
+          runInsideLoaderScope(
+            () =>
+              resolveLoaderData(
+                loaderEntry,
+                ctx,
+                ctx.pathname,
+                // The bake key rides for flagged loaders too: ssr:false
+                // bakes at capture regardless of the entry's loading() lane
+                // (loader-cache.ts capture branch) and its HIT-tail seed
+                // overlay needs the same key.
+                bakeLane || loaderEntry.bake === true ? segmentId : null,
+              ),
+            loader.$$id,
           ),
           entry,
           segmentId,
@@ -216,13 +218,15 @@ export async function resolveLoaders<TEnv>(
     const { loader } = loaderEntry;
     const segmentId = `${shortCode}D${i}.${loader.$$id}`;
     const wrapped = deps.wrapLoaderPromise(
-      runInsideLoaderScope(() =>
-        resolveLoaderData(
-          loaderEntry,
-          ctx,
-          ctx.pathname,
-          bakeLane || loaderEntry.bake === true ? segmentId : null,
-        ),
+      runInsideLoaderScope(
+        () =>
+          resolveLoaderData(
+            loaderEntry,
+            ctx,
+            ctx.pathname,
+            bakeLane || loaderEntry.bake === true ? segmentId : null,
+          ),
+        loader.$$id,
       ),
       entry,
       segmentId,

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

@@ -118,6 +118,7 @@ import {
   isShellCaptureActive,
   createMaskedLoaderPromise,
 } from "./loader-mask.js";
+import { loaderOwner } from "./prefetch-deferral.js";
 // Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
 // import segment-resolution but never use loader caching.
 let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
@@ -658,7 +659,7 @@ function executeLoaderData<TEnv>(
   // Handle pushes: the store and the owning segment are read synchronously
   // at kickoff, as createLoaderExecutor does for the body's own pushes.
   const handleStore = _getRequestContext()?._handleStore;
-  const owningSegmentId = internal._currentSegmentId;
+  const owningSegmentId = loaderOwner(ctx, loaderId);
   // Record only pushes from THIS loader's body and the loaders it awaits via
   // ctx.use: the handler and sibling loaders push into the same store
   // concurrently. A dependency can still run on a HIT for another reader

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

@@ -18,6 +18,7 @@ import {
   _getRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
+import { isRenderableLoading } from "../../types/boundaries.js";
 
 /**
  * True when the current render is the active PPR shell capture and route loaders
@@ -38,12 +39,13 @@ export function isShellCaptureActive(
 export { createMaskedLoaderPromise } from "./mask-nested.js";
 
 /**
- * True when the entry's loading() is renderable (mirrors segment-system's
- * isRenderableLoading). Not the lane decision (lane rule: see
+ * True when the entry's loading() is renderable (the shared
+ * isRenderableLoading, types/boundaries.ts, that segment-system gates on).
+ * Not the lane decision (lane rule: see
  * resolveLoaderData, loader-cache.ts): callers only use it to decide whether
  * an unflagged loader's segment key rides as the bake/seed key, which is inert
  * at capture.
  */
 export function entryLoadingMasksLoaders(loading: unknown): boolean {
-  return loading !== undefined && loading !== null && loading !== false;
+  return isRenderableLoading(loading);
 }