@rangojs/router 0.32.0 → 0.33.0

package/src/rsc/rsc-rendering.ts

@@ -102,6 +102,7 @@ import { contextGet } from "../context-var.js";
 import { rewriteShellAudience, rewriteTrail } from "../server/rewrite-trail.js";
 import { visitorShellKey } from "./shell-capture-constants.js";
 import { PREFETCH_HEADER } from "../prefetch-markers.js";
+import { isPrefetchKind } from "../router/segment-resolution/prefetch-deferral.js";
 import { WIRE } from "../wire-params.js";
 import {
   isWarmReplace,
@@ -140,6 +141,7 @@ import {
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
   SEGMENT_FRAGMENT_RECOVERY_HEADER,
 } from "../segment-fragments.js";
+import { prefetchScopeOf } from "../router/source-reads.js";
 
 type PprReplayStatus =
   | { outcome: "HIT"; freshness: "fresh" | "stale" }
@@ -361,10 +363,10 @@ type PreparedRender =
       kind: "payload";
       payload: RscPayload;
       /**
-       * The response depends on the source page: an intercept targets the
-       * route, or it carries deferred units (`prefetch: false`).
+       * `x-rsc-prefetch-scope`, when the response depends on the source
+       * page (prefetchScopeOf).
        */
-      sourceScoped: boolean;
+      prefetchScope: string | undefined;
       pprReplayStatus?: PprReplayStatus;
       /** The key a navigation-only heal capture stores under, when one is needed. */
       healKey?: string;
@@ -857,7 +859,7 @@ function* preparePayloadPlan<TEnv>(
       return {
         kind: "payload",
         payload: buildFullPayload(match, ctx, url, reqCtx, handleStore),
-        sourceScoped: false,
+        prefetchScope: undefined,
         pprReplayStatus,
         healKey,
       };
@@ -869,6 +871,7 @@ function* preparePayloadPlan<TEnv>(
     // showed at once, and ran held work again.
     const deferring = result.segments.some((s) => s.deferred);
     if (deferring) reqCtx._payloadDeferred = true;
+    if (result.fromStorage) reqCtx._servedFromStorage = true;
     return {
       kind: "payload",
       payload: {
@@ -898,10 +901,11 @@ function* preparePayloadPlan<TEnv>(
           stateCookieName: ctx.router.resolvedStateCookieName,
         },
       },
-      sourceScoped:
-        result.interceptTargeted === true ||
-        result.sourceHeld === true ||
-        deferring,
+      prefetchScope: prefetchScopeOf(
+        result.interceptTargeted === true || deferring,
+        result.sourceHeld,
+        result.diff.length === 0,
+      ),
       pprReplayStatus,
       healKey,
     };
@@ -925,7 +929,7 @@ function* preparePayloadPlan<TEnv>(
   return {
     kind: "payload",
     payload: buildFullPayload(match, ctx, url, reqCtx, handleStore),
-    sourceScoped: false,
+    prefetchScope: undefined,
   };
 }
 
@@ -1111,7 +1115,7 @@ function renderPreparedRscResponse<TEnv>(
 ): Promise<Response> {
   const { ctx, request, env, url, isPartial, nonce, reqCtx, renderSpan } =
     input;
-  const { payload, pprReplayStatus, sourceScoped } = prepared;
+  const { payload, pprReplayStatus, prefetchScope } = prepared;
   const metricsStore = reqCtx._metricsStore;
 
   const rscHeaders: Record<string, string> = {
@@ -1128,24 +1132,24 @@ function renderPreparedRscResponse<TEnv>(
       serializePprReplayStatus(pprReplayStatus);
   }
   // Tell the client's prefetch cache to scope this response to its source
-  // URL (instead of the default source-agnostic wildcard). A route an
-  // intercept targets renders the modal or the full page depending on the
-  // source, so neither response may be reused from another source: a full
-  // page prefetched where the intercept does not apply would otherwise
-  // serve a later click where it does (#1007). So is a diff a revalidate()
-  // decided from the source page: another page adopting it would keep its
-  // own copy of the segment the answer held (#1331).
-  if (sourceScoped) {
-    rscHeaders["x-rsc-prefetch-scope"] = "source";
+  // (instead of the default source-agnostic wildcard). See prefetchScopeOf.
+  if (prefetchScope !== undefined) {
+    rscHeaders["x-rsc-prefetch-scope"] = prefetchScope;
+    // A shared cache keys a partial by URL and the ids the client holds, not
+    // by its source page (document-cache.ts): stored, a scoped answer would
+    // serve its diff to another page that holds the same ids.
+    reqCtx._payloadSourceScoped = true;
   }
-  // prefetch: false (docs/design/prefetch-false.md, R7). A response that
-  // carries deferred units answers one page's prefetch, and a fill is the
-  // second half of one adoption: neither is reused by a shared cache or the
-  // document cache (which also refuses a payload marked `_payloadDeferred`),
-  // whatever Cache-Control the route set; so is a stale partial render, which
-  // a shared cache keyed by URL must not store or serve. A route with no flag
-  // keeps its headers.
+  // Not reused by a shared cache or the document cache (which also refuses a
+  // payload marked `_payloadDeferred` or `_payloadSourceScoped`), whatever
+  // Cache-Control the route set: a partial scoped to its source page (above);
+  // a response that carries deferred units, which answers one page's prefetch,
+  // and a fill, the second half of one adoption (prefetch: false,
+  // docs/design/prefetch-false.md, R7); and a stale partial render, which a
+  // shared cache keyed by URL must not store or serve. Any other route keeps
+  // its headers.
   if (
+    reqCtx._payloadSourceScoped ||
     reqCtx._payloadDeferred ||
     (isPartial &&
       (reqCtx._requestKind === "fill" ||
@@ -1195,7 +1199,7 @@ function renderPreparedRscResponse<TEnv>(
         },
   );
   // A prefetch whose render reported an error is not kept (#1170).
-  if (reqCtx._requestKind !== "prefetch" || !isPartial) return rendered;
+  if (!isPrefetchKind(reqCtx._requestKind) || !isPartial) return rendered;
   return rendered.then((response) =>
     markPrefetchOnRenderError(response, reqCtx._renderErrors ?? []),
   );
@@ -1735,8 +1739,14 @@ function serveShellHit(
   // request's own context and before the response leaves (the tail runs on a
   // derived context, after an await), so the response goes
   // `private, no-store` and stays out of the document cache
-  // (server/document-location-state.ts).
-  if ((reqCtx._locationState?.length ?? 0) > 0) {
+  // (server/document-location-state.ts). The tail carries exactly this
+  // state: a write during the tail (a loader's, through getRequestContext())
+  // comes after these headers chose the response's caching, so it is not
+  // sent, as the skill documents (skills/hooks/state.md).
+  // Never undefined: attachLocationStateIfPresent would read the tail's
+  // context instead.
+  const tailLocationState = reqCtx._locationState ?? [];
+  if (tailLocationState.length > 0) {
     reqCtx._documentLocationState = true;
   }
   const metricsStore = reqCtx._metricsStore;
@@ -1766,7 +1776,7 @@ function serveShellHit(
       reportCacheError(error, "cache-write", "[ShellServe] retire");
     }
   };
-  /** The first loader pin of the entry that failed to decode (dc-t89). */
+  /** The first loader pin of the entry that failed to decode. */
   let undecodablePin: string | undefined;
 
   const renderTail = async (
@@ -1797,7 +1807,7 @@ function serveShellHit(
       payload.metadata.pathname = entry.pathname ?? url.pathname;
       // The visitor's location state, as a MISS document's payload carries
       // it. The request was marked per visitor above.
-      attachLocationStateIfPresent(payload);
+      attachLocationStateIfPresent(payload, false, tailLocationState);
     }
     // Full Flight render per request: hydration needs the whole payload (there
     // is no Flight-side resume — a React limitation, not ours).
@@ -2061,7 +2071,13 @@ function serveShellHit(
               "the doc record could not supply the handler layer",
             );
           }
-          controller.enqueue(new TextEncoder().encode(shellReloadScript()));
+          // A document redirect's state cookie: this response's headers
+          // cleared it, and the reload must read it again.
+          controller.enqueue(
+            new TextEncoder().encode(
+              shellReloadScript(reqCtx._carriedLocationStateCookie),
+            ),
+          );
           if (tailTiming) {
             tailTiming.outcome = "error";
             tailTiming.completeMs = Math.round(performance.now() - tailT0);
@@ -2087,7 +2103,7 @@ function serveShellHit(
       }
       // A pin that failed to decode left its loader to this request's run:
       // this response hydrated once over a prelude rendered from the
-      // capture's value (dc-t89). Retire the entry once the response is
+      // capture's value. Retire the entry once the response is
       // closed, and back the key off so a pin that keeps failing costs one
       // mismatch per window. No reload: that would cost a second page load.
       if (undecodablePin !== undefined) {

package/src/rsc/server-action.ts

@@ -22,6 +22,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { printServerError } from "../server/print-server-error.js";
+import { runActionBody } from "../server/cookie-store.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { resolveActionRefId } from "../router/is-action.js";
 import { getInterceptSourceHeader } from "../router/navigation-snapshot.js";
@@ -203,7 +204,7 @@ export async function executeServerAction<TEnv>(
 
   try {
     loadedAction = await ctx.loadServerAction(actionId);
-    let data = await loadedAction!.apply(null, args);
+    let data = await runActionBody(() => loadedAction!.apply(null, args));
 
     // Intercept redirect Responses: serializing one as the action returnValue
     // would fail, and revalidation would run needlessly.

package/src/rsc/shell-capture.ts

@@ -552,7 +552,7 @@ const SNAPSHOT_BYTE_ENCODER = new TextEncoder();
 
 /**
  * Warn once per key that the capture's loader pins exceeded the route's
- * `maxSnapshotBytes` cap, so no document shell was stored (dc-t89). Once per
+ * `maxSnapshotBytes` cap, so no document shell was stored. Once per
  * key: the route recaptures every backoff window.
  */
 function warnSnapshotOverCapOnce(
@@ -2603,8 +2603,7 @@ async function captureAndStoreShell(
             throw new Error(`[rango] no shell pin for "${segmentKey}"`);
           }
         } catch (error) {
-          // Unpinned, the loader would run on every HIT over this prelude
-          // (dc-t89): refuse like an encode error.
+          // Unpinned, the loader would run on every HIT over this prelude: refuse like an encode error.
           reqCtx._renderErrors?.push(error);
         }
       }
@@ -2650,7 +2649,7 @@ async function captureAndStoreShell(
     }
 
     // Snapshot size guard: `maxSnapshotBytes` bounds the loader pins, and a
-    // document HIT needs every pin its prelude baked (dc-t89). Over the cap
+    // document HIT needs every pin its prelude baked. Over the cap
     // the entry keeps the navigation half only (the doc record, or nothing:
     // a tombstone that also shadows a build shell) and the attempt refuses.
     // The whole entry is bounded separately below, by the store's limit.
@@ -2897,7 +2896,7 @@ export {
 
 // Exported for unit tests that pin the refused-capture backoff policy directly
 // (dev cap vs production exponential growth, stored-clears, cold-start re-probe),
-// and markCaptureBackoff for serveShellHit (a pin that failed to decode, dc-t89).
+// and markCaptureBackoff for serveShellHit (a pin that failed to decode).
 // These are the same module-level functions the schedule path uses; a test that
 // drove them through a real capture round-trip could not assert the exact window
 // arithmetic without a full cold render.

package/src/rsc/shell-serve.ts

@@ -38,6 +38,7 @@ import {
 import { routerKeyPrefix } from "../cache/cache-key-utils.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { appendMetric } from "../router/metrics.js";
+import { escapeJsonForScript } from "../escape-script.js";
 import type { MetricsStore } from "../server/context.js";
 import { WIRE } from "../wire-params.js";
 
@@ -162,12 +163,22 @@ export function withoutShellMissMarker(request: Request): Request | undefined {
  * the page. window.stop() runs only when it reloads: it keeps the half-sent
  * Flight stream from being closed by DOMContentLoaded, which would throw
  * React's "Connection closed" (#412) before the reload lands.
+ *
+ * `restoreCookie` is the request's `_carriedLocationStateCookie`: the HIT's
+ * headers already cleared the location state cookie a document redirect left
+ * (server/document-location-state.ts), so the script sets it again before it
+ * reloads, and the reload carries the state.
  */
-export function shellReloadScript(): string {
+export function shellReloadScript(restoreCookie?: string): string {
+  const restore =
+    restoreCookie === undefined
+      ? ""
+      : `document.cookie=${escapeJsonForScript(JSON.stringify(restoreCookie))};`;
   return inlineShellScript(
     "(function(){var u=new URL(location.href);" +
       `if(u.searchParams.has(${JSON.stringify(WIRE.shellMiss)}))return;` +
       `u.searchParams.set(${JSON.stringify(WIRE.shellMiss)},"miss");` +
+      restore +
       "try{window.stop()}catch(e){}location.replace(u.href)})()",
   );
 }

package/src/segment-system.tsx

@@ -318,7 +318,7 @@ function wrapDefaultOutletContent(
  * is settled like a flagged one, so the commit shows no fallback. A loader
  * error is left to its read site there, its errorBoundary() fallback riding
  * the throw, as on a navigation: the nearest boundary to the read catches it
- * (#1129, dc-t65). notFound()/redirect() keep their build-time node.
+ * (#1129). notFound()/redirect() keep their build-time node.
  */
 async function buildLoaderStreams(
   loaders: ResolvedSegment[],

package/src/server/context.ts

@@ -126,9 +126,10 @@ export type EntryPropRender = {
   loading?: ReactNode | false;
   /**
    * loading(fallback, { prefetch: false }) with a renderable fallback: a
-   * prefetch defers what the fallback covers while the entry's segment is
-   * new to the client (router/segment-resolution/prefetch-deferral.ts). Set
-   * on both DSL evaluations, whatever `ssr` did to `loading`.
+   * speculative prefetch defers what the fallback covers while the entry's
+   * segment is new to the client
+   * (router/segment-resolution/prefetch-deferral.ts). Set on both DSL
+   * evaluations, whatever `ssr` did to `loading`.
    */
   loadingPrefetch?: false;
   /**
@@ -171,8 +172,8 @@ export type LoaderEntry = {
    */
   bake?: true;
   /**
-   * loader(Def, { prefetch: false }): a prefetch defers this registration
-   * while its segment is new to the client
+   * loader(Def, { prefetch: false }): a speculative prefetch defers this
+   * registration while its segment is new to the client
    * (router/segment-resolution/prefetch-deferral.ts).
    */
   prefetch?: false;
@@ -211,7 +212,10 @@ export type InterceptSegmentsState = {
  * @internal This type is an implementation detail and may change without notice.
  */
 export type InterceptSelectorContext<TEnv = any> = {
-  /** Where the navigation comes from: the intercept source while one is open. */
+  /**
+   * Where the navigation comes from: the intercept source while one is open.
+   * Its `url` never carries a #fragment.
+   */
   from: ServerRouteLocation;
   /** The navigation target. */
   to: ServerRouteLocation;
@@ -1719,6 +1723,33 @@ export function isInsideLoaderBody(loaderId: string): boolean {
   return false;
 }
 
+// The segment of the streamed handler or loader body running here; the
+// walker moves the shared `_currentSegmentId` on without awaiting either.
+const segmentPinALS: AsyncLocalStorage<string | undefined> = ((
+  globalThis as any
+)[Symbol.for("rangojs-router:segment-pin")] ??= new AsyncLocalStorage<
+  string | undefined
+>());
+
+/**
+ * Run `fn` as segment `segmentId`'s code: a handle push, a loader kickoff or
+ * a "use cache" call it makes, before or after an await, files under
+ * `segmentId` (segmentPinOf).
+ */
+export function runAsSegment<R>(segmentId: string | undefined, fn: () => R): R {
+  return segmentPinALS.run(segmentId, fn);
+}
+
+/**
+ * The segment code here runs for: the innermost runAsSegment scope, else
+ * `ctx`'s pin (a handler the walker awaits).
+ */
+export function segmentPinOf(ctx: {
+  _currentSegmentId?: string;
+}): string | undefined {
+  return segmentPinALS.getStore() ?? ctx._currentSegmentId;
+}
+
 // Scope for handle PUSH CALLBACKS (push(() => ...), including async ones).
 // A push callback's value is stored as-is; if it is a promise it is NOT tracked
 // by handleStore.settled and does not block segment resolution, so a

package/src/server/cookie-store.ts

@@ -330,7 +330,8 @@ export function invalidateClientCache(): void {
  *
  * Sets an internal response header the bridge reads. Idempotent within a
  * request. Inert (a dev warning) outside a request context — there is no
- * automatic invalidation to suppress.
+ * automatic invalidation to suppress. It also keeps the state's write part
+ * (runActionBody).
  */
 export function keepClientCache(): void {
   const ctx = _getRequestContext();
@@ -347,6 +348,26 @@ export function keepClientCache(): void {
   ctx._setKeepCacheDirective();
 }
 
+/**
+ * Run a server action's body (the JS call or a no-JS form post), then bump the
+ * rango state's write part for the client that called it: the response's
+ * state `Set-Cookie` keeps the client's timestamp and carries a new write part
+ * (browser/cookie-name.ts). Every later request of every tab and reload sends
+ * the new `X-Rango-State`, so a prefetch or navigation the browser HTTP cache
+ * holds from before the write (a response's own `Cache-Control: max-age`)
+ * misses, while the client's in-memory caches only go stale, as the action
+ * bridge marks them. Bumped however the body ends (returned, threw, or
+ * redirected), since the write may have committed either way, and not after
+ * keepClientCache() or invalidateClientCache() (whose rotation covers it).
+ */
+export async function runActionBody<T>(body: () => T | Promise<T>): Promise<T> {
+  try {
+    return await body();
+  } finally {
+    _getRequestContext()?._rotateStateCookie("write");
+  }
+}
+
 /**
  * Create a CookieStore backed by a RequestContext. Reads go through the
  * context's unguarded `_readCookie()` / `_readCookies()`: cookies() ran the

package/src/server/document-location-state.ts

@@ -14,7 +14,10 @@
  *   reads it on the next GET document request that navigates to the target
  *   pathname (`Sec-Fetch-Dest` a browsing context, where sent), seeds
  *   `_locationState` with its entries (so the render attaches them to the
- *   bootstrap payload, rsc/rsc-rendering.ts) and clears it.
+ *   bootstrap payload, rsc/rsc-rendering.ts) and clears it. A shell HIT that
+ *   degrades into a reload after its headers cleared the cookie sets it
+ *   again from script first (`_carriedLocationStateCookie`), so the reload
+ *   carries the state.
  *
  * A document that carries location state is per visitor: it is marked
  * `_documentLocationState`, never stored by the document cache or as a PPR
@@ -136,7 +139,10 @@ function isNavigationRequest(request: Request): boolean {
  * slots are taken from it (the value comes from the browser).
  */
 export function consumeDocumentLocationState(
-  reqCtx: Pick<RequestContext, "_locationState" | "setCookie">,
+  reqCtx: Pick<
+    RequestContext,
+    "_locationState" | "_carriedLocationStateCookie" | "setCookie"
+  >,
   request: Request,
   url: URL,
   stateCookieName: string,
@@ -159,6 +165,21 @@ export function consumeDocumentLocationState(
   }
   if (entries.length === 0) return;
   reqCtx._locationState = entries;
+  reqCtx._carriedLocationStateCookie = restoreCookieLine(name, raw, secure);
+}
+
+/**
+ * The `document.cookie` line that sets the consumed cookie again, for a
+ * shell HIT that reloads after its headers cleared it (rsc/rsc-rendering.ts
+ * serveShellHit). Script cannot write an `HttpOnly` cookie, so this one is
+ * readable by the page's script for its short life; it carries nothing the
+ * page's payload does not already hold.
+ */
+function restoreCookieLine(name: string, raw: string, secure: boolean): string {
+  return (
+    `${name}=${raw}; Path=/; Max-Age=${DOCUMENT_LOCATION_STATE_MAX_AGE}; ` +
+    `SameSite=Lax${secure ? "; Secure" : ""}`
+  );
 }
 
 /** JSON keeps it as it is: what the cookie can carry without change. */

package/src/server/handle-store.ts

@@ -302,6 +302,8 @@ export interface HandleStore {
    * so a loader that throws or skips its push shows none rather than the
    * record's. A hole's replays go with them. Any other loader's replays stay
    * (a dependency another entry's HIT replayed), and so do restored copies.
+   * A prefetch that defers the loader calls it too (revalidation.ts
+   * resolveOwnerLoaders): no run is made, so none of its placeholders stand.
    */
   settleLoaderRun(loaderId: string): void;