@rangojs/router 0.17.0 → 0.19.0

package/src/server/request-headers.ts

@@ -0,0 +1,134 @@
+/**
+ * The guarded `ctx.request.headers` (#976) and the router's raw reads.
+ *
+ * The Request the router hands to user code (handler, middleware and loader
+ * `ctx.request`, `getRequestContext().request`) carries an own `headers`
+ * getter that shadows the prototype's and runs the identity guard
+ * (cookie-store.ts guardRequestHeaders). A Proxy around the Request is not an
+ * option: `fetch(request)`, `new Request(request)` and `request.clone()` read
+ * the platform's internal slots, which a Proxy does not have. The own getter
+ * keeps the object a real Request, and those operations never call it.
+ */
+
+/** The Headers each shadowed request's getter returns. */
+const RAW_HEADERS = new WeakMap<Request, Headers>();
+
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+
+/**
+ * Set while the platform or a request facade reads a shadowed request's
+ * headers for itself, not for user code (runUnguarded).
+ */
+let unguarded = false;
+
+function runUnguarded<T>(fn: () => T): T {
+  const outer = unguarded;
+  unguarded = true;
+  try {
+    return fn();
+  } finally {
+    unguarded = outer;
+  }
+}
+
+/**
+ * A request's headers, past the guard. The rule: router code never reads a
+ * request's headers through the getter, only through this, so the guard sees
+ * user reads alone. Several router reads run inside the scopes the guard
+ * refuses (the state cookie rotation at a ppr capture, match's HMR marker,
+ * a store's cf-ray inside a "use cache" body, telemetry inside a loader
+ * fill); the rest follow the rule so a new call site cannot drift into one.
+ */
+export function requestHeaders(request: Request): Headers {
+  return RAW_HEADERS.get(request) ?? request.headers;
+}
+
+/**
+ * Shadow `request.headers` with an own, non-enumerable getter that calls
+ * `beforeRead` and returns the request's own Headers (stable per request, so
+ * a header set through it stays visible to every reader). Idempotent. Leaves
+ * the request as is when `headers` is a non-configurable own property (a
+ * runtime that defines it per instance). Three inherited members are
+ * shadowed with it:
+ *
+ * - `clone()` returns a clone shadowed the same way. A plain clone was a
+ *   Request without the getter, so `ctx.request.clone().headers` read the
+ *   visitor's headers past the guard. (`new Request(ctx.request)` still
+ *   returns a plain Request: the constructor cannot be intercepted.)
+ * - `_request`, on a lazy srvx NodeRequest (what @vitejs/plugin-rsc's Node
+ *   dev and preview servers and the vercel-output launcher hand the
+ *   router), runs unguarded: it builds the platform Request on first use
+ *   from `this.headers`, for clone() and the body readers. Through the
+ *   getter, a clone() inside a cache() boundary threw as a user read. It
+ *   stays lazy, so a request whose body srvx reads from its buffered
+ *   `rawBody` never builds one.
+ * - Node's util.inspect hook runs unguarded: undici's inspect reads
+ *   `this.headers`, so `console.log(ctx.request)` inside a "use cache" body
+ *   threw. A log is not a read into a shared entry.
+ */
+export function shadowRequestHeaders(
+  request: Request,
+  beforeRead: () => void,
+): Request {
+  if (RAW_HEADERS.has(request)) return request;
+  const own = Object.getOwnPropertyDescriptor(request, "headers");
+  if (own && !own.configurable) return request;
+  const lazy = inheritedGetter(request, "_request");
+  if (lazy) {
+    Object.defineProperty(request, "_request", {
+      get(this: Request): unknown {
+        return runUnguarded(() => lazy.call(this));
+      },
+      configurable: true,
+    });
+  }
+  const raw = request.headers;
+  RAW_HEADERS.set(request, raw);
+  Object.defineProperty(request, "headers", {
+    get(): Headers {
+      if (!unguarded) beforeRead();
+      return raw;
+    },
+    enumerable: false,
+    configurable: true,
+  });
+  const clone = request.clone;
+  defineMethod(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(
+      request,
+      INSPECT,
+      function (this: Request, ...args: unknown[]) {
+        return runUnguarded(() => inspect.apply(this, args));
+      },
+    );
+  }
+  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,
+  key: string,
+): (() => unknown) | undefined {
+  for (let o = Object.getPrototypeOf(target); o; o = Object.getPrototypeOf(o)) {
+    const found = Object.getOwnPropertyDescriptor(o, key);
+    if (found) return found.get;
+  }
+  return undefined;
+}

package/src/server.ts

@@ -48,6 +48,10 @@ export {
 // Component utilities (used internally for server/client boundary checks)
 export { isClientComponent, assertClientComponent } from "./component-utils.js";
 
+// transition({ when }) strict validation: the generated routes-manifest module
+// enables it in the app's RSC realm (see transition-when-ref.ts).
+export { enableTransitionWhenValidation } from "./transition-when-ref.js";
+
 // Client URL projection registry (Vite discovery/bootstrap bridge)
 export {
   clearClientUrlProjections,

package/src/ssr/index.tsx

@@ -2,7 +2,11 @@ import React from "react";
 import { createSsrRootComponent, deserializeSsrPayload } from "./ssr-root.js";
 import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
 import { runWithPreinitNonce } from "./preinit-client-references.js";
-import { SHELL_CAPTURE_MAX_WAIT_MS } from "../rsc/shell-capture-constants.js";
+import {
+  POST_QUIESCE_TASK_HOPS,
+  SHELL_CAPTURE_MAX_WAIT_MS,
+} from "../rsc/shell-capture-constants.js";
+import { isThenable } from "../handles/is-thenable.js";
 import type { ErrorPhase } from "../types.js";
 import type { HeadScriptsOption } from "../vite/plugin-types.js";
 
@@ -237,28 +241,64 @@ export interface SSRDependencies<TEnv = unknown> {
 }
 
 /**
- * Fixed number of macrotask hops between `quiesce` resolving and the abort. These
- * give React's fizz worker turns to flush the settled shell into the prelude and
- * mark still-pending boundaries as POSTPONED (rather than errored) before
- * controller.abort() lands. Not a wall-clock wait.
- *
- * Why 16 and not the original 2: under the REPLAY-ONLY capture model
- * (docs/design/ppr-shell-resume.md), the capture Flight render serializes ring-3
- * cached segments that are ALREADY serialized, so it emits the whole shell payload
- * in the first tick and the gate declares quiesce almost immediately (~a few ms).
- * On the old fresh-execution path the Flight dribbled out as handlers ran, so
- * Flight-quiet effectively meant "the shell has rendered" and 2 hops sufficed.
- *
- * Hops alone are NOT render-readiness: fizz cannot emit even <html> until the
- * payload root settles, which waits on every referenced client-module LOAD —
- * real module-runner I/O in dev (100ms+ cold), which no fixed count of near-
- * zero-cost task hops can buy. captureShellHTML therefore awaits the payload-
- * settled signal (SsrRootOptions.onPayloadSettled, deadline-bounded) between
- * quiesce and these hops; the hops then only flush the settled tree and mark
- * pending boundaries POSTPONED. Still task-based (masked loaders never emit,
- * so more hops never lets a hole settle). Bounded by maxWaitMs end to end.
+ * One set per running capture, collecting the client-reference module loads
+ * requested while it runs (captureClientLoads). The Flight client resolves a
+ * client component used as an element type lazily, so the payload settles
+ * while its module is still loading, and a shell that renders it outside any
+ * Suspense boundary cannot complete until the load does. On the
+ * cloudflare-basic build a cold load (the module, its imports, its CSS
+ * virtual) settled at +890.1ms, after the payload (+873.4ms) and 1ms before
+ * the abort, and uninstrumented builds lost that race (issue #949). The
+ * Flight client asks the loader again for every import row, even for a
+ * module another render is already loading, so a capture sees each load it
+ * needs; one a concurrent render requests meanwhile is collected too and is
+ * the same bounded I/O. The sets are per capture, their contents isolate-wide:
+ * a load that never settles can only hold the captures running when it was
+ * requested, each until its deadline.
  */
-const POST_QUIESCE_TASK_HOPS = 16;
+const activeCaptureClientLoads = new Set<Set<PromiseLike<unknown>>>();
+
+/** The loader wrapper {@link captureClientLoads} last installed. */
+let recordingClientReferenceLoader: ((id: string) => unknown) | undefined;
+
+/**
+ * Start collecting the client-reference loads requested during a capture;
+ * call the returned `stop` when the capture ends. Wraps plugin-rsc's SSR
+ * loader (`globalThis.__vite_rsc_client_require__`, which
+ * `__vite_rsc_require__` reads per call) on the first capture, so an isolate
+ * that never captures keeps the bare loader. Wraps again when another wrapper
+ * replaced this one (the build shell phase bridges hashed ids the same way,
+ * vite/discovery/shell-prerender-phase.ts). Collects nothing without the
+ * loader.
+ */
+function captureClientLoads(): {
+  loads: Set<PromiseLike<unknown>>;
+  stop: () => void;
+} {
+  const g = globalThis as {
+    __vite_rsc_client_require__?: (id: string) => unknown;
+  };
+  const load = g.__vite_rsc_client_require__;
+  if (typeof load === "function" && load !== recordingClientReferenceLoader) {
+    recordingClientReferenceLoader = (id) => {
+      const loading = load(id);
+      // plugin-rsc memoizes one promise per id and the Flight client stamps
+      // status "fulfilled" on it once loaded: a warm module is not collected.
+      if (
+        activeCaptureClientLoads.size > 0 &&
+        isThenable(loading) &&
+        (loading as { status?: string }).status !== "fulfilled"
+      ) {
+        for (const loads of activeCaptureClientLoads) loads.add(loading);
+      }
+      return loading;
+    };
+    g.__vite_rsc_client_require__ = recordingClientReferenceLoader;
+  }
+  const loads = new Set<PromiseLike<unknown>>();
+  activeCaptureClientLoads.add(loads);
+  return { loads, stop: () => activeCaptureClientLoads.delete(loads) };
+}
 
 /**
  * Route an SSR error through the deps.onError notification callback with the
@@ -421,6 +461,13 @@ interface ShellCaptureOptions {
    * refuses to store the shell (issue #915).
    */
   onError?: (error: unknown) => void;
+  /**
+   * Called with React's errorInfo for each task still pending when the
+   * capture's own abort froze the prelude; its componentStack is computed
+   * when read. The dev no-shell warning prints the stacks: one of them is what
+   * suspended above <body> (issue #941).
+   */
+  onAbortedTask?: (errorInfo: { componentStack?: string } | undefined) => void;
 }
 
 /**
@@ -761,12 +808,13 @@ export function createShellCaptureHandler<TEnv = unknown>(
     const deadline = (await isDebuggerAttached())
       ? { promise: new Promise<void>(() => {}), cancel: () => {} }
       : createCancelableTimeout(maxWaitMs);
+    const clientLoads = captureClientLoads();
     try {
       // No nonce (nonce'd requests never reach capture); no formState.
-      // payloadSettled: fires when the Flight payload root settles — i.e.
-      // every client-module load the payload references completed and fizz
-      // can actually emit the tree. The abort below gates on it (bounded by
-      // the same deadline): Flight byte-quiet alone is NOT render-readiness.
+      // payloadSettled: fires when the Flight payload root settles and fizz
+      // can emit the tree. The abort below gates on it and on the
+      // client-reference loads in flight in the isolate (bounded by the same
+      // deadline): Flight byte-quiet alone is NOT render-readiness.
       let settlePayload!: () => void;
       const payloadSettled = new Promise<void>((resolve) => {
         settlePayload = resolve;
@@ -823,8 +871,9 @@ export function createShellCaptureHandler<TEnv = unknown>(
         // render errors are NOT our sentinel and still surface through
         // deps.onError, the same channel renderHTML uses. See
         // docs/design/ppr-shell-resume.md.
-        onError: (error: unknown) => {
+        onError: (error: unknown, errorInfo?: { componentStack?: string }) => {
           if (error === abortReason) {
+            opts.onAbortedTask?.(errorInfo);
             return;
           }
           opts.onError?.(error);
@@ -846,25 +895,34 @@ export function createShellCaptureHandler<TEnv = unknown>(
       // shell that never goes quiet (a root postpone / hung handle).
       await Promise.race([opts.quiesce, deadline.promise]);
       // Then wait for fizz RENDER-READINESS, bounded by the same deadline:
-      // the payload root settles only after every client-module load the
-      // payload references completed (real module-runner I/O in dev; 100ms+
-      // on a cold graph). Flight byte-quiet does NOT imply this — a fully
+      // the payload root settles, then the client-reference module loads the
+      // capture started settle — a client component used as an element type
+      // resolves lazily, after the payload (real module-runner I/O in dev;
+      // 100ms+ on a cold graph). Flight byte-quiet does NOT imply this — a fully
       // REPLAYED (prerendered) route's Flight stream finishes in ~1-3ms and
       // an abort taken on quiet-plus-task-hops alone landed BEFORE fizz could
       // emit <html>, freezing a zero-byte prelude: the eternal-MISS shape
       // this route class showed on every cold graph (dev cold boots, GH
       // runners) while ordinary routes — whose live handler execution keeps
-      // Flight noisy long enough — never hit it. Masked-loader holes do not
-      // block payload settlement (they postpone below the root), so this
-      // await costs a genuinely hole-y shell nothing; a payload that NEVER
-      // settles (hung handles) degrades at the deadline exactly as before.
-      // A prerender that SETTLES first (early success or a hard rejection)
-      // ends the wait immediately — fizz is already done either way.
+      // Flight noisy long enough — never hit it. Holes the payload carries
+      // block neither wait (masked live loaders and loader-nested promises postpone
+      // below the root and load no module; the Flight input stays frozen),
+      // so this await costs a genuinely hole-y shell nothing; a payload that
+      // NEVER settles (hung handles) degrades at the deadline exactly as
+      // before. A prerender that SETTLES first (early success or a hard
+      // rejection) ends the wait immediately — fizz is already done either
+      // way.
       const prerenderSettled = prerenderPromise.then(
         () => {},
         () => {},
       );
-      await Promise.race([payloadSettled, prerenderSettled, deadline.promise]);
+      // The capture's loads all started when their import rows were parsed,
+      // before the Flight input froze.
+      await Promise.race([
+        payloadSettled.then(() => Promise.allSettled(clientLoads.loads)),
+        prerenderSettled,
+        deadline.promise,
+      ]);
       // Fixed task hops before the abort: give React's fizz worker turns to flush
       // the now-complete shell and mark the still-pending boundaries as POSTPONED
       // rather than errored. Deterministic (the byte set is already frozen and
@@ -923,6 +981,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
       };
     } finally {
       deadline.cancel();
+      clientLoads.stop();
     }
   };
 }

package/src/ssr/ssr-root.tsx

@@ -189,14 +189,15 @@ export interface SsrRootOptions {
   nonce?: string;
   /**
    * Fires once when the Flight payload root settles (resolve OR reject) — the
-   * signal that every client-module load the payload references completed and
-   * fizz can start emitting the tree. The capture pass gates its abort on
-   * this: a fully REPLAYED (prerendered) route's Flight stream goes
-   * byte-quiet in ~1-3ms, but fizz cannot render even <html> until the
-   * module loads finish (real module-runner I/O in dev; 100ms+ on a cold
-   * graph), so an abort gated on Flight quiet alone fires first and freezes
-   * a zero-byte prelude. Masked-loader holes do NOT block this signal —
-   * they postpone below the root.
+   * signal that fizz can start emitting the tree. A client component used as
+   * an element type resolves lazily, so its module load can still be in
+   * flight (captureShellHTML waits for those separately, issue #949). The
+   * capture pass gates its abort on this: a fully REPLAYED (prerendered)
+   * route's Flight stream goes byte-quiet in ~1-3ms, but fizz cannot render
+   * even <html> until the module loads finish (real module-runner I/O in dev;
+   * 100ms+ on a cold graph), so an abort gated on Flight quiet alone fires
+   * first and freezes a zero-byte prelude. Masked-loader holes do NOT block
+   * this signal — they postpone below the root.
    */
   onPayloadSettled?: () => void;
   /**

package/src/testing/dispatch.ts

@@ -627,9 +627,9 @@ export async function dispatch<TEnv = any>(
       const manifestEntry = preview?.manifestEntry;
       if (manifestEntry) {
         // Lazy so the testing barrel's eager graph stays plugin-rsc-free (see the
-        // import note above): the leaf takes createCacheScope/resolveCacheTags as
-        // INJECTED deps so it never imports plugin-rsc; we hand it the lazily
-        // imported pair here, only once a response route actually matched.
+        // import note above): the leaf takes createCacheScope as an INJECTED
+        // dep so it never imports plugin-rsc; we hand it the lazily imported
+        // builder here, only once a response route actually matched.
         const cacheScopeMod = await import("../cache/cache-scope.js");
         const { serveResponseRouteWithCache } =
           await import("../rsc/response-cache-serve.js");
@@ -645,10 +645,7 @@ export async function dispatch<TEnv = any>(
           responseType: responseType as string,
           url,
           executeHandler,
-          deps: {
-            createCacheScope: cacheScopeMod.createCacheScope,
-            resolveCacheTags: cacheScopeMod.resolveCacheTags,
-          },
+          deps: { createCacheScope: cacheScopeMod.createCacheScope },
         });
         if (cached !== undefined) return cached;
       }

package/src/testing/e2e/index.ts

@@ -53,6 +53,7 @@ export {
   SHELL_STATUS_HEADER,
   type PprReplayBypassReason,
   type PprReplayStatus,
+  type ShellCachePartition,
   type ShellStatus,
   type ShellStatusTarget,
 } from "../shell-status.js";

package/src/testing/flight.entry.ts

@@ -18,6 +18,11 @@
  * element tree, so you can assert typed prop fidelity across the client boundary
  * (a `Date` comes back a `Date`) and detect inlined-vs-island. Serialize +
  * deserialize only — no hydration/interaction (that is the e2e tier).
+ *
+ * `serveShellRequest` serves one request through the router's production
+ * handler, so a `ppr` route's MISS runs the real shell capture and a later
+ * request is a real HIT; only the HTML step is stubbed. `resetShellTestState`
+ * clears the per-isolate PPR state between tests.
  */
 
 export {
@@ -50,3 +55,12 @@ export type {
   RenderHandlerResult,
   StateCookieSeed,
 } from "./render-handler.js";
+
+export {
+  serveShellRequest,
+  resetShellTestState,
+} from "./serve-shell-request.js";
+export type {
+  ServeShellRequestOptions,
+  ServeShellRequestResult,
+} from "./serve-shell-request.js";

package/src/testing/index.ts

@@ -49,6 +49,8 @@ export type {
 
 export { runTransitionWhen } from "./run-transition-when.js";
 export type {
+  RunTransitionWhenAction,
+  RunTransitionWhenLocation,
   RunTransitionWhenOptions,
   RunTransitionWhenResult,
 } from "./run-transition-when.js";
@@ -91,12 +93,15 @@ export {
 export type {
   PprReplayBypassReason,
   PprReplayStatus,
+  ShellCachePartition,
   ShellStatus,
   ShellStatusTarget,
 } from "./shell-status.js";
 
 export { collectHandle } from "./collect-handle.js";
 
+export { withLocationStateKey } from "./location-state-key.js";
+
 export {
   diffGeneratedRoutes,
   assertGeneratedRoutesMatch,

package/src/testing/internal/action-id.ts

@@ -0,0 +1,25 @@
+import { resolveActionRefId } from "../../router/is-action.js";
+
+/**
+ * The id a testing primitive's `action` option names: a single imported
+ * server action (its `$id ?? $$id`, as the action boundary derives it) or a
+ * raw actionId string. A function without either id throws, naming the
+ * primitive.
+ */
+export function resolveTestActionId(
+  action: ((...args: never[]) => unknown) | string | undefined,
+  primitive: string,
+): string | undefined {
+  if (action === undefined) return undefined;
+  if (typeof action === "string") return action;
+  const id = resolveActionRefId(action);
+  if (id === undefined) {
+    throw new Error(
+      `${primitive}: \`action\` must be a single imported server action ` +
+        "(carrying its build-injected id) or an actionId string. The passed " +
+        "function has no $id/$$id — outside a built app, pass the id string " +
+        'your predicate should match (e.g. "src/actions/cart.ts#addToCart").',
+    );
+  }
+  return id;
+}

package/src/testing/internal/context.ts

@@ -250,7 +250,7 @@ export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
   locationState: Record<string, unknown>;
 } {
   return {
-    cookies: { ...ctx.cookies() },
+    cookies: ctx._readCookies(),
     locationState: resolveLocationStateEntries(ctx._locationState ?? []),
   };
 }

package/src/testing/location-state-key.ts

@@ -0,0 +1,45 @@
+import {
+  peekLocationStateKey,
+  type LocationStateDefinition,
+} from "../browser/react/location-state-shared.js";
+
+// Typed history.state slots must carry this prefix: buildHistoryState spreads
+// only `__rsc_ls_*` keys onto history.state (history-state.ts).
+const KEY_PREFIX = "__rsc_ls_";
+
+let syntheticKeyCounter = 0;
+
+/**
+ * Assign a location-state key to a `createLocationState()` definition in a unit
+ * test that runs without the rango Vite plugin (which injects the key in dev
+ * and build). Outside production, a definition without a key throws on first
+ * use (`MyState(value)`, `useLocationState(MyState)`, `.read()`).
+ *
+ * - `withLocationStateKey(GridState, "GridState")` sets `__rsc_ls_GridState`
+ *   (a name that already starts with `__rsc_ls_` is used as-is).
+ * - Without a name, a key already set (by the plugin or an earlier call) is
+ *   kept; otherwise the definition gets a synthetic `__rsc_ls_test_<n>` key,
+ *   which then stays on it.
+ *
+ * Returns the definition.
+ *
+ * @example
+ * ```ts
+ * import { withLocationStateKey } from "@rangojs/router/testing";
+ * import { GridState } from "../src/location-states";
+ *
+ * withLocationStateKey(GridState);
+ * ```
+ */
+export function withLocationStateKey<
+  TDefinition extends LocationStateDefinition<any, any>,
+>(definition: TDefinition, name?: string): TDefinition {
+  if (name !== undefined) {
+    definition.__rsc_ls_key = name.startsWith(KEY_PREFIX)
+      ? name
+      : KEY_PREFIX + name;
+  } else if (!peekLocationStateKey(definition)) {
+    definition.__rsc_ls_key = `${KEY_PREFIX}test_${syntheticKeyCounter++}`;
+  }
+  return definition;
+}

package/src/testing/render-handler.ts

@@ -338,7 +338,7 @@ export async function renderHandler<TEnv = any>(
     }
   });
 
-  const cookies = { ...reqCtx.cookies() };
+  const cookies = reqCtx._readCookies();
   const responseSource = didThrow
     ? thrown
     : out instanceof Response