@rangojs/router 0.23.0 → 0.24.1

package/src/router/route-trie-builder.ts

@@ -153,6 +153,31 @@ function sortSuffixParams(node: TrieNode): void {
   }
 }
 
+/**
+ * Give every static-children map in the trie a null prototype, in place, and
+ * return the trie (#1109). The walker indexes `node.s` with raw URL segments,
+ * so a map with Object.prototype would answer `/constructor` or `/__proto__`
+ * with an inherited member. The builder creates null-prototype maps; a trie
+ * that arrives as JSON (the build manifest) or across the dev runner boundary
+ * gets them here. Object.setPrototypeOf keeps a JSON-parsed map's fast
+ * properties, where Object.create(null) starts in dictionary mode.
+ */
+export function nullPrototypeStaticChildren(node: TrieNode): TrieNode {
+  if (node.s) {
+    Object.setPrototypeOf(node.s, null);
+    for (const child of Object.values(node.s)) {
+      nullPrototypeStaticChildren(child);
+    }
+  }
+  if (node.xp) {
+    for (const child of Object.values(node.xp)) {
+      nullPrototypeStaticChildren(child.c);
+    }
+  }
+  if (node.p) nullPrototypeStaticChildren(node.p.c);
+  return node;
+}
+
 /**
  * Insert a route into the trie. Optional params expand into two branches at
  * registration time (skip-first, then present), so each terminal lives at the
@@ -271,7 +296,9 @@ function insertSegments(
   const segment = segments[index];
 
   if (segment.type === "static") {
-    if (!node.s) node.s = {};
+    // Null prototype: a segment named `constructor` or `__proto__` is an own
+    // key, never an inherited member to descend into and write a leaf on.
+    if (!node.s) node.s = Object.create(null) as Record<string, TrieNode>;
     if (!node.s[segment.value]) node.s[segment.value] = {};
     insertSegments(
       node.s[segment.value],

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

@@ -26,6 +26,7 @@
 
 import { isValidElement, type ReactElement } from "react";
 import { isThenable } from "../../handles/is-thenable.js";
+import { assignOwn } from "../../context-var.js";
 import {
   cloneElementWithProps,
   isPlainDataObject,
@@ -178,7 +179,7 @@ async function elideNested(
     for (const key of Object.keys(source)) {
       const r = await elideNested(source[key], seen);
       if (r.state === "rejected") return r;
-      out[key] = r.value;
+      assignOwn(out, key, r.value);
       if (r.value !== source[key]) changed = true;
       result.hasHole ||= r.hasHole;
     }
@@ -301,13 +302,21 @@ export function overlayLoaderContainer(
     // Shape drift (fresh not a plain object): markers fall back to undefined.
     const freshObj = isPlainDataObject(fresh) ? fresh : undefined;
     let out: Record<string, unknown> | undefined;
+    // Own keys only: a key named like an Object.prototype member is data.
+    // The spread copies an own `__proto__` as data, so assigning a recorded
+    // key writes it; a fresh-only key goes through assignOwn.
     for (const key of Object.keys(recorded)) {
-      const next = overlayLoaderContainer(freshObj?.[key], recorded[key]);
+      const next = overlayLoaderContainer(
+        freshObj && Object.hasOwn(freshObj, key) ? freshObj[key] : undefined,
+        recorded[key],
+      );
       if (next !== recorded[key]) (out ??= { ...recorded })[key] = next;
     }
     if (freshObj) {
       for (const key of Object.keys(freshObj)) {
-        if (!(key in recorded)) (out ??= { ...recorded })[key] = freshObj[key];
+        if (!Object.hasOwn(recorded, key)) {
+          assignOwn((out ??= { ...recorded }), key, freshObj[key]);
+        }
       }
     }
     return out ?? recorded;
@@ -341,7 +350,12 @@ function overlayProps(
   const props = recorded.props;
   let changed: Record<string, unknown> | undefined;
   for (const key of Object.keys(props)) {
-    const next = overlayLoaderContainer(freshProps?.[key], props[key]);
+    const next = overlayLoaderContainer(
+      freshProps && Object.hasOwn(freshProps, key)
+        ? freshProps[key]
+        : undefined,
+      props[key],
+    );
     if (next !== props[key]) (changed ??= {})[key] = next;
   }
   return changed ? cloneElementWithProps(recorded, changed) : recorded;

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

@@ -8,10 +8,12 @@
  *
  * Deliberately a LEAF module: loader-mask (the other natural home) imports
  * request-context, so any funnel importing the mask from there inherits that
- * graph. This module imports only is-thenable and react.
+ * graph. This module imports only react and two leaves, is-thenable and
+ * context-var.
  */
 
 import { cloneElement, isValidElement, type ReactElement } from "react";
+import { assignOwn } from "../../context-var.js";
 import { isThenable } from "../../handles/is-thenable.js";
 
 /**
@@ -52,7 +54,8 @@ type KeyValidated = { _store?: { validated?: unknown } };
  * keyless child of a static children list (validated at creation) would warn
  * "Each child in a list should have a unique key" once cloned. Pass only the
  * props that change: cloneElement re-parents the element (owner) when its
- * config carries `ref`.
+ * config carries `ref`. cloneElement copies props by assignment, so a prop
+ * key named `__proto__` can't survive a clone; prop copies don't use assignOwn.
  */
 export function cloneElementWithProps(
   element: ReactElement,
@@ -206,8 +209,9 @@ export function maskNestedContainerThenables(
     seen.set(value, out);
     let changed = false;
     for (const key of Object.keys(source)) {
-      out[key] = maskNestedContainerThenables(source[key], seen, report);
-      if (out[key] !== source[key]) changed = true;
+      const masked = maskNestedContainerThenables(source[key], seen, report);
+      assignOwn(out, key, masked);
+      if (masked !== source[key]) changed = true;
     }
     if (changed) return out;
     seen.set(value, value);

package/src/router/segment-resolution/prefetch-deferral.ts

@@ -99,11 +99,8 @@ export interface PrefetchDeferral {
    * not stored and not held. Empty outside a prefetch.
    */
   readonly skipped: ReadonlySet<string>;
-  /**
-   * One of `skipped` is a chain entry: nothing below it runs, so the response
-   * has no content for it, a route cache() record included.
-   */
-  readonly skipsChain: boolean;
+  /** How this request may use the route's cache() record (recordUse). */
+  readonly record: RecordUse;
   /** Segment id of the handler unit this prefetch skipped. */
   deferredUnit?: string;
   /**
@@ -125,6 +122,31 @@ export interface PrefetchDeferral {
   deferredLoaders?: Map<string, DeferredLoader>;
 }
 
+/**
+ * How a request may use the route's cache() record, decided once per match
+ * (planPrefetchDeferral) for the cache middleware.
+ */
+export interface RecordUse {
+  /**
+   * withCacheLookup reads it. False when this prefetch skips a chain unit
+   * (PrefetchDeferral.skipped): the unit takes everything below it, so the
+   * read would replay the record's handle pushes for segments the response
+   * does not carry. Decided from what the client holds, never per tree: a
+   * prefetch that holds the flagged layout reads and writes the record like
+   * any other request.
+   */
+  readonly read: boolean;
+  /** withCacheStore writes it. False where `read` is: the record would be incomplete. */
+  readonly write: boolean;
+  /**
+   * A background re-render of the whole route may write it: the stale-hit
+   * refresh (withBackgroundRevalidation) and the proactive write a partial
+   * response needs (withCacheStore). False for a fill: the re-render runs
+   * the handlers of segments the client holds, which a fill does not run.
+   */
+  readonly refresh: boolean;
+}
+
 /** A loader this prefetch deferred: PrefetchDeferral.deferredLoaders. */
 export interface DeferredLoader {
   /**
@@ -329,7 +351,12 @@ export function planPrefetchDeferral(
       }
     }
   }
-  return { scope, mode, storedFrom, held, skipped, skipsChain };
+  const record: RecordUse = {
+    read: !skipsChain,
+    write: !skipsChain,
+    refresh: mode !== "fill",
+  };
+  return { scope, mode, storedFrom, held, skipped, record };
 }
 
 export function getPrefetchDeferral(
@@ -344,6 +371,30 @@ export function isFillRequest(ctx: HandlerContext<any, any>): boolean {
   return getPrefetchDeferral(ctx)?.mode === "fill";
 }
 
+/**
+ * A fill's whole revalidation rule (R5): send a segment the client does not
+ * hold, keep one it holds, and consult nothing else (no revalidate()
+ * predicate, no params or search comparison, no trace entry). Undefined on
+ * any other request, where revalidation decides. `held` is the set the
+ * deciding site resolves with.
+ */
+export function fillSends(
+  ctx: HandlerContext<any, any>,
+  segmentId: string,
+  held: ReadonlySet<string>,
+): boolean | undefined {
+  return isFillRequest(ctx) ? !held.has(segmentId) : undefined;
+}
+
+const RECORD_OPEN: RecordUse = { read: true, write: true, refresh: true };
+
+/** PrefetchDeferral.record, or all of it open when the match has no plan. */
+export function recordUse(
+  ctx: HandlerContext<any, any> | undefined,
+): RecordUse {
+  return getPrefetchDeferral(ctx)?.record ?? RECORD_OPEN;
+}
+
 /**
  * Register a loader this prefetch deferred, with the segment that registers
  * it and how to start it there (PrefetchDeferral.deferredLoaders). The first
@@ -481,17 +532,6 @@ export function firstUnitCandidate(
   return undefined;
 }
 
-/**
- * This prefetch skips a layout above the route cache's boundary, and with it
- * everything the record below holds: withCacheLookup and withCacheStore leave
- * the record alone for it. Decided per request, from what the client holds:
- * a prefetch of the same tree that holds the layout reads and writes the
- * record like any other request.
- */
-export function defersAboveRecord(ctx: HandlerContext<any, any>): boolean {
-  return getPrefetchDeferral(ctx)?.skipsChain === true;
-}
-
 /**
  * Record the handler unit this prefetch skipped. A `chain` entry takes what
  * the walk reaches after it (PrefetchDeferral.below); a slot is skipped

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

@@ -9,7 +9,10 @@
 import type { ReactNode } from "react";
 import { invariant } from "../../errors";
 import { revalidate } from "../loader-resolution.js";
-import { evaluateRevalidation } from "../revalidation.js";
+import {
+  evaluateRevalidation,
+  type EvaluateRevalidationOptions,
+} from "../revalidation.js";
 import {
   getParallelEntries,
   getParallelSlotEntries,
@@ -38,8 +41,8 @@ import { entryLoadingMasksLoaders } from "./loader-mask.js";
 import {
   defersLoader,
   deferUnit,
+  fillSends,
   getPrefetchDeferral,
-  isFillRequest,
   registerDeferredLoader,
 } from "./prefetch-deferral.js";
 import {
@@ -110,6 +113,28 @@ function emitRevalidationDecision(
   });
 }
 
+/**
+ * Whether a segment the client holds (`held`, the set resolution works on)
+ * renders again. A fill keeps it (prefetch-deferral.ts fillSends): no
+ * revalidate() predicate runs and nothing is traced or observed. Any other
+ * request asks the segment's revalidate() chain, and `onEvaluated` sees that
+ * answer.
+ */
+async function revalidateHeld<TEnv>({
+  held,
+  onEvaluated,
+  ...options
+}: EvaluateRevalidationOptions<TEnv> & {
+  held: ReadonlySet<string>;
+  onEvaluated?: (shouldRevalidate: boolean) => void;
+}): Promise<boolean> {
+  const fill = fillSends(options.context, options.segment.id, held);
+  if (fill !== undefined) return fill;
+  const shouldRevalidate = await evaluateRevalidation(options);
+  onEvaluated?.(shouldRevalidate);
+  return shouldRevalidate;
+}
+
 // ---------------------------------------------------------------------------
 // prefetch: false (prefetch-deferral.ts)
 // ---------------------------------------------------------------------------
@@ -194,7 +219,6 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   }));
 
   const matchedIds = loaderMeta.map((m) => m.segmentId);
-  const fill = isFillRequest(ctx);
 
   const revalidationChecks = await Promise.all(
     loaderMeta.map(
@@ -221,8 +245,6 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               }
               return true;
             }
-            // Fill: a held segment is skipped outright, no predicate runs.
-            if (fill) return false;
 
             const dummySegment: ResolvedSegment = {
               id: segmentId,
@@ -235,7 +257,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               belongsToRoute,
             };
 
-            return await evaluateRevalidation({
+            return await revalidateHeld({
               segment: dummySegment,
               prevParams,
               getPrevSegment: null,
@@ -251,6 +273,7 @@ export async function resolveLoadersWithRevalidation<TEnv>(
               actionContext,
               stale,
               traceSource: "loader",
+              held: clientSegmentIds,
             });
           },
           async () => true,
@@ -704,10 +727,12 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
     // runs: a prefetch sends what the slot declares instead of running its
     // handler.
     let deferred = deferUnit(context, parallelId, "below");
+    // A fill sends exactly the slots the client lacks, ahead of every rule
+    // below (fillSends).
+    const fill = fillSends(context, parallelId, clientSegmentIds);
     let shouldResolve: boolean;
-    if (isFillRequest(context)) {
-      // Fill: only what the client does not hold renders, no predicate runs.
-      shouldResolve = !clientSegmentIds.has(parallelId);
+    if (fill !== undefined) {
+      shouldResolve = fill;
     } else if (deferred) {
       shouldResolve = true;
     } else if (isFullRefetch) {
@@ -880,8 +905,6 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         }
         return true;
       }
-      // Fill: a held segment is skipped outright, no predicate runs.
-      if (isFillRequest(context)) return false;
 
       const dummySegment: ResolvedSegment = {
         id: entry.shortCode,
@@ -900,7 +923,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
       };
 
-      const shouldRevalidate = await evaluateRevalidation({
+      return revalidateHeld({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -917,18 +940,20 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
         stale,
         traceSource:
           entry.type === "route" ? "route-handler" : "layout-handler",
+        held: clientSegmentIds,
+        onEvaluated: (shouldRevalidate) => {
+          emitRevalidationDecision(
+            entry.shortCode,
+            context.pathname,
+            routeKey,
+            shouldRevalidate,
+          );
+          debugLog("segment.revalidate", "entry revalidation decision", {
+            segmentId: entry.shortCode,
+            shouldRevalidate,
+          });
+        },
       });
-      emitRevalidationDecision(
-        entry.shortCode,
-        context.pathname,
-        routeKey,
-        shouldRevalidate,
-      );
-      debugLog("segment.revalidate", "entry revalidation decision", {
-        segmentId: entry.shortCode,
-        shouldRevalidate,
-      });
-      return shouldRevalidate;
     },
     async () => {
       // Only an entry the client lacks (defersUnit). Its handler would
@@ -1308,8 +1333,6 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         }
         return true;
       }
-      // Fill: a held segment is skipped outright, no predicate runs.
-      if (isFillRequest(context)) return false;
 
       const dummySegment: ResolvedSegment = {
         id: orphan.shortCode,
@@ -1323,7 +1346,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
       };
 
-      const shouldRevalidate = await evaluateRevalidation({
+      return revalidateHeld({
         segment: dummySegment,
         prevParams,
         getPrevSegment: null,
@@ -1339,14 +1362,15 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
         actionContext,
         stale,
         traceSource: "orphan-layout",
+        held: clientSegmentIds,
+        onEvaluated: (shouldRevalidate) =>
+          emitRevalidationDecision(
+            orphan.shortCode,
+            context.pathname,
+            routeKey,
+            shouldRevalidate,
+          ),
       });
-      emitRevalidationDecision(
-        orphan.shortCode,
-        context.pathname,
-        routeKey,
-        shouldRevalidate,
-      );
-      return shouldRevalidate;
     },
     async () => {
       // Below a unit a prefetch skipped: the orphan goes with it.

package/src/rsc/full-payload.ts

@@ -14,7 +14,11 @@ import type { HandlerContext } from "./handler-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import type { HandleStore } from "../server/handle-store.js";
 import type { Theme } from "../theme/types.js";
-import { documentCacheStoresRender } from "../cache/document-cache.js";
+import {
+  rendersForSharedAudience,
+  rewriteTrail,
+  visitorUrl,
+} from "../server/rewrite-trail.js";
 import { attachTransitionWhen } from "./attach-transition-when.js";
 import { publicRouteName } from "../route-name.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
@@ -38,7 +42,7 @@ export function buildFullPayload(
 ): RscPayload {
   return {
     metadata: {
-      pathname: url.pathname,
+      pathname: renderedLocation(reqCtx, url).pathname,
       routerId: ctx.router.id,
       basename: ctx.router.basename,
       segments: attachTransitionWhen(m.segments, reqCtx),
@@ -84,6 +88,36 @@ export function buildFullPayload(
   };
 }
 
+/**
+ * The URL a render shows as the page's location (payload `pathname`, the SSR
+ * search and origin seed). For a request middleware rewrote, the visitor's
+ * URL, so the server markup and the hydrating client (which reads the address
+ * bar) agree on `usePathname()` and `useSearchParams()`. A render other
+ * visitors may be served shows `url`, the target, as a direct visit does: a
+ * shell capture, and a render the document cache stores (its key is the
+ * target). A render that shows the visitor's URL marks
+ * `_payloadVisitorLocation`, and the document cache does not store it.
+ */
+export function renderedLocation(
+  reqCtx:
+    | Pick<
+        RequestContext<any>,
+        | "_variables"
+        | "_shellCaptureRun"
+        | "_documentCacheRender"
+        | "_payloadVisitorLocation"
+        | "res"
+      >
+    | undefined,
+  url: URL,
+): URL {
+  if (!reqCtx || !rewriteTrail(reqCtx) || rendersForSharedAudience(reqCtx)) {
+    return url;
+  }
+  reqCtx._payloadVisitorLocation = true;
+  return visitorUrl(reqCtx, url);
+}
+
 /**
  * The theme a document payload carries as `metadata.initialTheme` (the
  * ThemeProvider's first state), read with no identity guard: it is the
@@ -116,9 +150,7 @@ export function payloadInitialTheme(
 ): Theme | undefined {
   const config = reqCtx._themeConfig;
   if (!config) return undefined;
-  if (reqCtx._shellCaptureRun || documentCacheStoresRender(reqCtx)) {
-    return config.defaultTheme;
-  }
+  if (rendersForSharedAudience(reqCtx)) return config.defaultTheme;
   const theme = reqCtx._readTheme();
   if (theme !== config.defaultTheme) reqCtx._payloadVisitorTheme = true;
   return theme;