@rangojs/router 0.23.0 → 0.24.0

package/src/server/handle-store.ts

@@ -5,6 +5,7 @@ import {
 } from "./context.js";
 import { holdsThenable } from "../router/segment-resolution/mask-nested.js";
 import { pushedByKey } from "../handles/pushed-by.js";
+import { defineSlot } from "./slot-accessors.js";
 
 /**
  * Handle data structure: handleName -> segmentId -> entries[]
@@ -394,6 +395,34 @@ export interface HandleStore {
   ): void;
 }
 
+/**
+ * settled and fullySettled: shared descriptors (slot-accessors.ts) that call
+ * the store's closure in SETTLEMENT_SLOT with the lane they wait for.
+ */
+const SETTLEMENT_SLOT: unique symbol = Symbol("rango.handleStore.settlement");
+
+type SettlementSlot = { [SETTLEMENT_SLOT]: (full: boolean) => Promise<void> };
+
+const SETTLEMENT_ACCESSORS: Record<
+  "settled" | "fullySettled",
+  PropertyDescriptor
+> = {
+  settled: {
+    get(this: SettlementSlot): Promise<void> {
+      return this[SETTLEMENT_SLOT](false);
+    },
+    enumerable: true,
+    configurable: true,
+  },
+  fullySettled: {
+    get(this: SettlementSlot): Promise<void> {
+      return this[SETTLEMENT_SLOT](true);
+    },
+    enumerable: true,
+    configurable: true,
+  },
+};
+
 /**
  * Create a new HandleStore instance.
  *
@@ -774,7 +803,9 @@ export function createHandleStore(): HandleStore {
     });
   }
 
-  return {
+  // Data members only: the accessors are SETTLEMENT_ACCESSORS.
+  const store: Omit<HandleStore, "settled" | "fullySettled"> &
+    ThisType<HandleStore> = {
     track<T>(promise: Promise<T>): Promise<T> {
       inflightCount++;
       return trackSettlement(promise, () => {
@@ -793,22 +824,6 @@ export function createHandleStore(): HandleStore {
       sealInternal();
     },
 
-    get settled(): Promise<void> {
-      if (sealed && inflightCount === 0) return Promise.resolve();
-      return new Promise<void>((resolve) => {
-        drainWaiters.push(resolve);
-      });
-    },
-
-    get fullySettled(): Promise<void> {
-      if (sealed && inflightCount === 0 && auxInflightCount === 0) {
-        return Promise.resolve();
-      }
-      return new Promise<void>((resolve) => {
-        fullDrainWaiters.push(resolve);
-      });
-    },
-
     push(
       handleName: string,
       segmentId: string,
@@ -1213,4 +1228,20 @@ export function createHandleStore(): HandleStore {
       signalEmission();
     },
   };
+  // settled: the handler lane drained; fullySettled: the auxiliary lane too.
+  defineSlot(store, SETTLEMENT_SLOT, (full: boolean): Promise<void> => {
+    if (sealed && inflightCount === 0 && (!full || auxInflightCount === 0)) {
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      (full ? fullDrainWaiters : drainWaiters).push(resolve);
+    });
+  });
+  Object.defineProperty(store, "settled", SETTLEMENT_ACCESSORS.settled);
+  Object.defineProperty(
+    store,
+    "fullySettled",
+    SETTLEMENT_ACCESSORS.fullySettled,
+  );
+  return store as HandleStore;
 }

package/src/server/request-context.ts

@@ -12,6 +12,7 @@
 
 import { AsyncLocalStorage } from "node:async_hooks";
 import { parseCookiesFromHeader } from "./cookie-parse.js";
+import { defineHidden, defineSlot, slotAccessor } from "./slot-accessors.js";
 import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { CookieOptions } from "../router/middleware.js";
 import {
@@ -31,6 +32,7 @@ import type {
 import type { Handle } from "../handle.js";
 import {
   type ContextVar,
+  assignOwn,
   contextGet,
   contextSet,
   isNonCacheable,
@@ -94,6 +96,10 @@ import {
   type ExecutionStart,
 } from "../cache/invalidation-order.js";
 import { invariant } from "../errors.js";
+import {
+  defineRequestRewrittenFrom,
+  defineRewrittenFrom,
+} from "./rewrite-trail.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
 export interface RenderForegroundCursor {
@@ -729,6 +735,14 @@ export interface RequestContext<
    */
   _requestKind?: "prefetch" | "fill";
 
+  /**
+   * @internal Set when a render shows the visitor's URL of a rewritten
+   * request: the payload or SSR seed (renderedLocation, rsc/full-payload.ts)
+   * or a `ctx.rewrittenFrom` read (server/rewrite-trail.ts). The document
+   * cache does not store that response: it is keyed by the target.
+   */
+  _payloadVisitorLocation?: boolean;
+
   /**
    * Attach location state entries to the current response.
    *
@@ -1030,6 +1044,7 @@ export type PublicRequestContext<
   | "_payloadVisitorTheme"
   | "_payloadDeferred"
   | "_requestKind"
+  | "_payloadVisitorLocation"
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
@@ -1087,6 +1102,60 @@ export const UNTRACKED_BACKGROUND_TASK: unique symbol = Symbol.for(
 // AsyncLocalStorage instance for request context
 const requestContextStorage = new AsyncLocalStorage<RequestContext<any>>();
 
+// The request context's accessors: shared descriptors (slot-accessors.ts).
+const RES_SLOT: unique symbol = Symbol("rango.requestContext.res");
+const RENDER_BARRIER_SLOT: unique symbol = Symbol(
+  "rango.requestContext.renderBarrier",
+);
+
+const RES_DESCRIPTOR: PropertyDescriptor = {
+  ...slotAccessor(RES_SLOT, true),
+  set(_: Response): void {
+    throw new Error(
+      "ctx.res is read-only. Use ctx.header() to set response headers, or cookies() for cookie mutations.",
+    );
+  },
+};
+
+// getRequestContext().theme is the visitor's cookie, guarded like cookies()
+// (#971); before it was a plain read that a ppr shell, a cache() entry or a
+// "use cache" entry stored for every visitor. Non-enumerable like the
+// handler ctx.theme (handler-context.ts THEME_DESCRIPTOR): serializing the
+// context (React dev debug info) must not count as a read. The guard reads
+// the ambient context, as cookies() does, and falls back to the receiver.
+const REQUEST_THEME_DESCRIPTOR: PropertyDescriptor = {
+  get(this: RequestContext<any>): Theme | undefined {
+    return readGuardedTheme(this, "getRequestContext().theme");
+  },
+  enumerable: false,
+  configurable: true,
+};
+
+// A fresh context enumerates _renderBarrier like its other fields (the
+// fetchable-loader ctx spreads it, loader-fetch.ts); a derived one never did.
+const RENDER_BARRIER_DESCRIPTOR: PropertyDescriptor = slotAccessor(
+  RENDER_BARRIER_SLOT,
+  true,
+);
+const DERIVED_RENDER_BARRIER_DESCRIPTOR: PropertyDescriptor = {
+  ...RENDER_BARRIER_DESCRIPTOR,
+  enumerable: false,
+};
+
+/**
+ * Define `ctx.res` as an own accessor that reads `get`. Assigning it throws
+ * the read-only error. A context derived from another (Object.create) gets
+ * its own response this way; copying the descriptor would read the
+ * prototype's slot.
+ */
+export function bindRes(
+  ctx: RequestContext<any, any>,
+  get: () => Response,
+): void {
+  defineSlot(ctx, RES_SLOT, get);
+  Object.defineProperty(ctx, "res", RES_DESCRIPTOR);
+}
+
 /**
  * Capture the current async context (RequestContext._runAtRequestEntry), taken
  * on handler entry before any router scope, so a nested dispatch (a
@@ -1416,10 +1485,10 @@ export function createRequestContext<TEnv>(
     }
     const result: Record<string, string> = {};
     for (const key of Object.keys(parsed)) {
-      if (!deleted.has(key)) result[key] = parsed[key];
+      if (!deleted.has(key)) assignOwn(result, key, parsed[key]);
     }
     for (const [k, v] of mutations) {
-      if (v !== null) result[k] = v;
+      if (v !== null) assignOwn(result, k, v);
     }
     return result;
   };
@@ -1465,7 +1534,11 @@ export function createRequestContext<TEnv>(
   const cleanUrl = stripInternalParams(url);
   const originalUrl = new URL(request.url);
 
-  const ctx: RequestContext<TEnv> = {
+  // Data members only: the accessors and hidden members are defined after it.
+  const fields: Omit<
+    RequestContext<TEnv>,
+    "res" | "_renderBarrier" | "_readTheme" | "_readCookie" | "_readCookies"
+  > = {
     env,
     request,
     url: cleanUrl,
@@ -1496,15 +1569,6 @@ export function createRequestContext<TEnv>(
     }) as RequestContext<TEnv>["set"],
     params: {} as Record<string, string>,
 
-    get res(): Response {
-      return stubResponse;
-    },
-    set res(_: Response) {
-      throw new Error(
-        "ctx.res is read-only. Use ctx.header() to set response headers, or cookies() for cookie mutations.",
-      );
-    },
-
     // The visitor's cookies, guarded like cookies() (#976): before, a plain
     // read that a ppr shell, a cache() entry or a "use cache" entry stored
     // for every visitor.
@@ -1518,10 +1582,6 @@ export function createRequestContext<TEnv>(
       return effectiveCookies();
     },
 
-    // Non-enumerable, defined after this literal.
-    _readCookie: effectiveCookie,
-    _readCookies: effectiveCookies,
-
     setCookie(name: string, value: string, options?: CookieOptions): void {
       assertNotInsideCacheExec(ctx, "setCookie");
       stubResponse.headers.append(
@@ -1710,8 +1770,6 @@ export function createRequestContext<TEnv>(
       this._onResponseCallbacks.push(callback);
     },
 
-    // theme: a guarded, non-enumerable getter defined after this literal.
-    _readTheme: getTheme,
     setTheme: themeConfig
       ? (theme: Theme) => {
           assertNotInsideCacheExec(ctx, "setTheme");
@@ -1737,14 +1795,15 @@ export function createRequestContext<TEnv>(
     _renderDiagnosticsEnabled: undefined,
     _handlerStart: undefined,
 
-    _renderBarrier: null as any,
     _resolveRenderBarrier: null as any,
     _renderBarrierSegmentOrder: undefined,
 
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
+  const ctx = fields as RequestContext<TEnv>;
 
-  wireRenderBarrier(ctx, handleStore);
+  bindRes(ctx, () => stubResponse);
+  wireRenderBarrier(ctx, handleStore, RENDER_BARRIER_DESCRIPTOR);
 
   ctx.use = createUseFunction({
     handleStore,
@@ -1752,41 +1811,70 @@ export function createRequestContext<TEnv>(
     getContext: () => ctx,
   });
 
-  // getRequestContext().theme is the visitor's cookie, guarded like cookies()
-  // (#971); before it was a plain read that a ppr shell, a cache() entry or a
-  // "use cache" entry stored for every visitor. Non-enumerable like the
-  // handler ctx.theme (handler-context.ts THEME_DESCRIPTOR): serializing the
-  // context (React dev debug info) must not count as a read. The guard reads
-  // the ambient context, as cookies() does, and falls back to the receiver.
-  // _readTheme is the unguarded read: non-enumerable too, so a spread copy of
-  // the context (the fetchable-loader ctx, loader-fetch.ts) cannot carry it.
-  // The same holds for the unguarded cookie reads (#976).
-  Object.defineProperties(ctx, {
-    theme: {
-      get(this: RequestContext<TEnv>): Theme | undefined {
-        return readGuardedTheme(this, "getRequestContext().theme");
-      },
-      enumerable: false,
-      configurable: true,
-    },
-    _readTheme: { enumerable: false },
-    _readCookie: { enumerable: false },
-    _readCookies: { enumerable: false },
-  });
+  // theme: REQUEST_THEME_DESCRIPTOR. _readTheme is the unguarded read:
+  // non-enumerable too, so a spread copy of the context (the fetchable-loader
+  // ctx, loader-fetch.ts) cannot carry it. The same holds for the unguarded
+  // cookie reads (#976). Added here, not flipped from enumerable: changing an
+  // existing property's attributes costs V8 a map copy per request.
+  Object.defineProperty(ctx, "theme", REQUEST_THEME_DESCRIPTOR);
+  defineRequestRewrittenFrom(ctx);
+  defineHidden(ctx, "_readTheme", getTheme);
+  defineHidden(ctx, "_readCookie", effectiveCookie);
+  defineHidden(ctx, "_readCookies", effectiveCookies);
 
   (ctx as any)[NOCACHE_SYMBOL] = true;
   // Non-enumerable: a self-reference would make the context circular for
   // JSON.stringify, spreads and React's dev debug-info serialization of props.
-  Object.defineProperty(ctx, "_requestRoot", {
-    value: ctx,
-    enumerable: false,
-    configurable: true,
-    writable: true,
-  });
+  defineHidden(ctx, "_requestRoot", ctx);
   ctx._requestStart = executionStart();
   return ctx;
 }
 
+/**
+ * Move a request context to a rewrite target for the next pass of the
+ * request (rsc/rewrite-passes.ts, `throw rewrite()`). The context object
+ * stays the same, so what the visitor's pass set is still there: variables
+ * (the rewrite trail among them), the response stub (status, headers,
+ * cookies), location state, theme, `dynamic()`, metrics, request tags,
+ * onResponse callbacks, the handle store.
+ *
+ * Moved to the target: the request (`rawUrl`, the visitor's `_rsc*` params
+ * included), url, originalUrl, pathname, searchParams and the request kind.
+ * Cleared for the target's match: params, route name, reverse, the
+ * classified route, the request mode, and the document cache's render mark
+ * (its middleware runs again for the target). The loader memo behind
+ * `getRequestContext().use()` is new: a loader that middleware started in
+ * the visitor's pass read the visitor's URL. A pass never renders before it
+ * rewrites: router/middleware.ts refuses a rewrite thrown after a next()
+ * unless that next() rejected with a Rewrite (a downstream middleware
+ * rewrote before its own next()), so there is no render state to reset.
+ */
+export function rebaseRequestContext(
+  ctx: RequestContext<any>,
+  request: Request,
+  rawUrl: URL,
+): void {
+  const cleanUrl = stripInternalParams(rawUrl);
+  ctx.request = guardRequestHeaders(request);
+  ctx.url = cleanUrl;
+  ctx.originalUrl = rawUrl;
+  ctx.pathname = cleanUrl.pathname;
+  ctx.searchParams = cleanUrl.searchParams;
+  ctx._requestKind = requestKind(request, rawUrl);
+  ctx.params = {};
+  ctx._routeName = undefined;
+  ctx.routeName = undefined;
+  ctx.reverse = createReverseFunction(getGlobalRouteMap(), undefined, {});
+  ctx._classifiedRoute = undefined;
+  ctx._requestMode = undefined;
+  ctx._documentCacheRender = undefined;
+  ctx.use = createUseFunction({
+    handleStore: ctx._handleStore,
+    loaderPromises: new Map(),
+    getContext: () => ctx,
+  });
+}
+
 /**
  * Wire a fresh render barrier onto `ctx`, closure-bound to THIS ctx and THIS
  * handle store. Called by createRequestContext for every fresh context, and by
@@ -1803,10 +1891,14 @@ export function createRequestContext<TEnv>(
  * read the foreground's handle snapshot; the capture's fresh `_handleStore`
  * was invisible, so foreground per-request handle data could bake into the
  * shared shell.
+ *
+ * A derived context's `_renderBarrier` is non-enumerable (the default
+ * descriptor); a fresh context's is enumerable like its other fields.
  */
 export function wireRenderBarrier(
   ctx: RequestContext<any, any>,
   handleStore: HandleStore,
+  descriptor: PropertyDescriptor = DERIVED_RENDER_BARRIER_DESCRIPTOR,
 ): void {
   // Reset the whole barrier family as OWN properties. No-op for a fresh
   // context; for the derived capture context this shadows the foreground's
@@ -1853,25 +1945,23 @@ export function wireRenderBarrier(
     }
     if (resolveBarrier) resolveBarrier();
   };
+  defineSlot(ctx, RENDER_BARRIER_SLOT, (): Promise<void> => {
+    const p = barrierResolved
+      ? Promise.resolve()
+      : new Promise<void>((resolve) => {
+          resolveBarrier = resolve;
+        });
+    Object.defineProperty(ctx, "_renderBarrier", {
+      value: p,
+      writable: false,
+      configurable: false,
+    });
+    return p;
+  });
   // defineProperty, not assignment: on a derived context the prototype's
   // _renderBarrier may already be a non-writable data property (the getter
   // pins it after first access), which would reject a plain assignment.
-  Object.defineProperty(ctx, "_renderBarrier", {
-    get() {
-      const p = barrierResolved
-        ? Promise.resolve()
-        : new Promise<void>((resolve) => {
-            resolveBarrier = resolve;
-          });
-      Object.defineProperty(ctx, "_renderBarrier", {
-        value: p,
-        writable: false,
-        configurable: false,
-      });
-      return p;
-    },
-    configurable: true,
-  });
+  Object.defineProperty(ctx, "_renderBarrier", descriptor);
 }
 
 // Capture the Max-Age value so it can be parsed numerically. A leading zero
@@ -2103,6 +2193,7 @@ export function createUseFunction<TEnv>(
         );
       },
     };
+    defineRewrittenFrom(loaderCtx, ctx);
     // "use cache" keys it by route, like the request ctx it reads (#940).
     (loaderCtx as any)[NOCACHE_SYMBOL] = true;
 

package/src/server/request-headers.ts

@@ -10,6 +10,8 @@
  * keeps the object a real Request, and those operations never call it.
  */
 
+import { defineHidden } from "./slot-accessors.js";
+
 /** The Headers each shadowed request's getter returns. */
 const RAW_HEADERS = new WeakMap<Request, Headers>();
 
@@ -93,12 +95,12 @@ export function shadowRequestHeaders(
     configurable: true,
   });
   const clone = request.clone;
-  defineMethod(request, "clone", function (this: Request): Request {
+  defineHidden(request, "clone", function (this: Request): Request {
     return shadowRequestHeaders(clone.call(this), beforeRead);
   });
   const inspect = (request as unknown as Record<symbol, unknown>)[INSPECT];
   if (typeof inspect === "function") {
-    defineMethod(
+    defineHidden(
       request,
       INSPECT,
       function (this: Request, ...args: unknown[]) {
@@ -109,18 +111,6 @@ export function shadowRequestHeaders(
   return request;
 }
 
-function defineMethod(
-  target: object,
-  key: PropertyKey,
-  value: (...args: never[]) => unknown,
-): void {
-  Object.defineProperty(target, key, {
-    value,
-    configurable: true,
-    writable: true,
-  });
-}
-
 /** The getter `key` resolves to on `target`'s prototype chain, if any. */
 function inheritedGetter(
   target: object,

package/src/server/rewrite-trail.ts

@@ -0,0 +1,190 @@
+/**
+ * The URLs a rewritten request moved through (`throw rewrite()`), and what
+ * each context sees of them.
+ *
+ * One source: the trail lives in the request's variables under a token no
+ * user code can reach, so a middleware cannot reset the loop count. The
+ * visitor's URL is its first entry (`ctx.rewrittenFrom`); the hops are its
+ * length minus one.
+ */
+
+import { contextGet, contextSet, createVar } from "../context-var.js";
+import { RewriteLoopError } from "../errors.js";
+import { documentCacheStoresRender } from "../cache/document-cache-policy.js";
+import { guardIdentityRead, type IdentityReadWording } from "./context.js";
+import { stripInternalParams } from "../router/internal-params.js";
+import type { RequestContext } from "./request-context.js";
+
+/** Most rewrites one request may take; the next one is a RewriteLoopError. */
+export const MAX_REWRITE_HOPS = 5;
+
+/** Clean hrefs, the visitor's first. */
+const REWRITE_TRAIL = createVar<readonly string[]>();
+
+type TrailContext = Pick<RequestContext<any>, "_variables">;
+
+function pathKey(url: URL): string {
+  return url.pathname + url.search;
+}
+
+/** The trail of a rewritten request; undefined when nothing rewrote. */
+export function rewriteTrail(
+  reqCtx: TrailContext | undefined,
+): readonly string[] | undefined {
+  return reqCtx?._variables
+    ? (contextGet(reqCtx._variables, REWRITE_TRAIL) as
+        | readonly string[]
+        | undefined)
+    : undefined;
+}
+
+/**
+ * Count one hop from `from` to `to` (clean URLs) and return its number.
+ * Throws RewriteLoopError past {@link MAX_REWRITE_HOPS}, or when `to` is the
+ * URL the request is on (pathname and search).
+ */
+export function recordRewriteHop(
+  reqCtx: TrailContext,
+  from: URL,
+  to: URL,
+): number {
+  const trail = [...(rewriteTrail(reqCtx) ?? [from.href]), to.href];
+  const hops = trail.length - 1;
+  if (pathKey(to) === pathKey(from) || hops > MAX_REWRITE_HOPS) {
+    throw new RewriteLoopError(
+      trail.map((href) => pathKey(new URL(href))),
+      MAX_REWRITE_HOPS,
+    );
+  }
+  contextSet(reqCtx._variables, REWRITE_TRAIL, trail);
+  return hops;
+}
+
+type AudienceContext = Pick<
+  RequestContext<any>,
+  "_shellCaptureRun" | "_documentCacheRender" | "res"
+>;
+
+/**
+ * A render other visitors may be served: a PPR shell capture, or a render
+ * the document cache stores (its response opted in before next()). It shows
+ * what a direct visit to its URL shows: no visitor theme, no visitor URL.
+ */
+export function rendersForSharedAudience(reqCtx: AudienceContext): boolean {
+  return reqCtx._shellCaptureRun === true || documentCacheStoresRender(reqCtx);
+}
+
+/**
+ * The URL the visitor is on: the first URL of a rewritten request, else
+ * `url` with the internal `_rsc*` params stripped. A reload the router asks
+ * the browser for points here.
+ */
+export function visitorUrl(reqCtx: TrailContext | undefined, url: URL): URL {
+  const first = rewriteTrail(reqCtx)?.[0];
+  return first ? new URL(first) : stripInternalParams(url);
+}
+
+const REWRITTEN_FROM_FIX =
+  "It is the visitor's URL, which the shared entry would serve to every " +
+  "visitor. Read it in middleware and pass what the page needs through a " +
+  "variable the cache key covers.";
+
+const REWRITTEN_FROM_READ: IdentityReadWording = {
+  verb: "read",
+  fix: {
+    useCache:
+      "ctx.rewrittenFrom is not in the cache key. Read it before the cached " +
+      "function and pass it in as an argument.",
+    cacheScope: REWRITTEN_FROM_FIX,
+    capture: REWRITTEN_FROM_FIX,
+    warning: REWRITTEN_FROM_FIX,
+  },
+};
+
+/**
+ * Who reads `rewrittenFrom`: "render" for the contexts a render reads
+ * (handler, loader, response route, getRequestContext()), "middleware" for a
+ * middleware ctx, which runs once per request and is never stored.
+ */
+export type RewrittenFromReader = "render" | "middleware";
+
+/**
+ * The read behind every `ctx.rewrittenFrom`. Guarded like cookies(): inside
+ * a `cache()` boundary or a `"use cache"` function it throws, and a loader's
+ * own `cache()` fill records it. A render other visitors may be served sees
+ * `undefined`, as on a direct visit; any other render that sees the visitor's
+ * URL marks `_payloadVisitorLocation`, so the document cache does not store
+ * it.
+ */
+function readRewrittenFrom(
+  reqCtx: RequestContext<any> | undefined,
+  reader: RewrittenFromReader,
+): string | undefined {
+  if (!reqCtx) return undefined;
+  if (reader === "render" && rendersForSharedAudience(reqCtx)) {
+    return undefined;
+  }
+  guardIdentityRead(reqCtx, "ctx.rewrittenFrom", REWRITTEN_FROM_READ);
+  const href = rewriteTrail(reqCtx)?.[0];
+  if (href && reader === "render") reqCtx._payloadVisitorLocation = true;
+  return href;
+}
+
+/** Each context's own copy of the URL, kept while the visitor URL holds. */
+const COPIES = new WeakMap<object, URL>();
+/** The request context a handler/loader/middleware ctx reads through. */
+const SOURCES = new WeakMap<object, RequestContext<any> | undefined>();
+const READERS = new WeakMap<object, RewrittenFromReader>();
+
+function copyFor(holder: object, href: string | undefined): URL | undefined {
+  if (!href) return undefined;
+  const memo = COPIES.get(holder);
+  if (memo && memo.href === href) return memo;
+  const copy = new URL(href);
+  COPIES.set(holder, copy);
+  return copy;
+}
+
+/**
+ * Non-enumerable, like `ctx.theme`: serializing a ctx (React's dev debug
+ * info) must not count as a read.
+ */
+const SCOPED_DESCRIPTOR: PropertyDescriptor = {
+  get(this: object): URL | undefined {
+    const href = readRewrittenFrom(
+      SOURCES.get(this),
+      READERS.get(this) ?? "render",
+    );
+    return copyFor(this, href);
+  },
+  enumerable: false,
+  configurable: true,
+};
+
+const REQUEST_DESCRIPTOR: PropertyDescriptor = {
+  get(this: RequestContext<any>): URL | undefined {
+    return copyFor(this, readRewrittenFrom(this, "render"));
+  },
+  enumerable: false,
+  configurable: true,
+};
+
+/**
+ * Define `ctx.rewrittenFrom` on a handler, loader, response-route or
+ * middleware ctx, read through `source` (the request context it belongs
+ * to). Each ctx gets its own copy of the URL.
+ */
+export function defineRewrittenFrom(
+  ctx: object,
+  source: RequestContext<any> | undefined,
+  reader: RewrittenFromReader = "render",
+): void {
+  SOURCES.set(ctx, source);
+  if (reader !== "render") READERS.set(ctx, reader);
+  Object.defineProperty(ctx, "rewrittenFrom", SCOPED_DESCRIPTOR);
+}
+
+/** Define `rewrittenFrom` on a request context, read through itself. */
+export function defineRequestRewrittenFrom(ctx: RequestContext<any>): void {
+  Object.defineProperty(ctx, "rewrittenFrom", REQUEST_DESCRIPTOR);
+}