@rangojs/router 0.31.0 → 0.32.0

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

@@ -0,0 +1,313 @@
+/**
+ * Location state on document responses (#1330).
+ *
+ * A client navigation or an action carries server-set location state in its
+ * Flight payload, and a redirect on either becomes a Flight redirect that
+ * carries it too. A document request has no such channel for a 3xx: the
+ * browser follows it with a plain GET. This module carries the state across
+ * that one hop in a short-lived cookie:
+ *
+ * - `carryLocationStateAcrossRedirect` (rsc/request-stages.ts
+ *   finalizeRequestResponse) writes it on a document request's same-origin
+ *   3xx when the request set location state;
+ * - `consumeDocumentLocationState` (rsc/request-stages.ts runRequestPasses)
+ *   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.
+ *
+ * A document that carries location state is per visitor: it is marked
+ * `_documentLocationState`, never stored by the document cache or as a PPR
+ * shell, and leaves with `Cache-Control: private, no-store`
+ * (`markDocumentResponsePrivate`).
+ *
+ * The value is JSON, not Flight: a cookie holds text, and the client merges
+ * it as `history.state` would hold it. `Path=/` because the `__Host-` prefix
+ * (https) requires it, which keeps a sibling subdomain from planting state;
+ * the target pathname inside the value decides who consumes it.
+ */
+
+import {
+  isLocationStateKey,
+  resolveLocationStateEntries,
+  type LocationStateEntry,
+} from "../browser/react/location-state-shared.js";
+import { getRawCookieValue } from "../browser/cookie-name.js";
+import { isExternalRedirect } from "../redirect-origin.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import { mayNeedSSR } from "../rsc/ssr-setup.js";
+import { requestHeaders } from "./request-headers.js";
+import {
+  serializeCookieValue,
+  type RequestContext,
+} from "./request-context.js";
+
+/** Seconds the cookie lives: one redirect hop, never a later visit. */
+const DOCUMENT_LOCATION_STATE_MAX_AGE = 60;
+
+/**
+ * Upper bound of one serialized `Set-Cookie` (name, value and attributes).
+ * Browsers keep at least 4096 bytes per cookie; the margin covers the
+ * attributes some add.
+ */
+const DOCUMENT_LOCATION_STATE_MAX_BYTES = 4000;
+
+const COOKIE_SUFFIX = "-ls";
+
+const PRIVATE_NO_STORE = "private, no-store";
+
+interface CarriedState {
+  /** The pathname of the redirect target, the only request that reads it. */
+  p: string;
+  /** The resolved entries: slot key to value. */
+  s: Record<string, unknown>;
+}
+
+/** The cookie's name for a router: `__Host-` on https. */
+export function documentLocationStateCookieName(
+  stateCookieName: string,
+  secure: boolean,
+): string {
+  return `${secure ? "__Host-" : ""}${stateCookieName}${COOKIE_SUFFIX}`;
+}
+
+function cookieAttributes(secure: boolean): {
+  path: string;
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite: "lax";
+} {
+  return { path: "/", httpOnly: true, secure, sameSite: "lax" };
+}
+
+/**
+ * A document request: one that renders HTML (mayNeedSSR), not a navigation,
+ * an action, a loader fetch or a Flight fetch. Those carry state in their
+ * Flight payload, or are not what the browser shows.
+ */
+function isDocumentRequest(request: Request, url: URL): boolean {
+  return mayNeedSSR(request, url);
+}
+
+function parseCarriedState(raw: string): CarriedState | undefined {
+  try {
+    const parsed: unknown = JSON.parse(decodeURIComponent(raw));
+    if (parsed === null || typeof parsed !== "object") return undefined;
+    const { p, s } = parsed as Partial<CarriedState>;
+    if (typeof p !== "string" || s === null || typeof s !== "object") {
+      return undefined;
+    }
+    return { p, s };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `Sec-Fetch-Dest` values of a request that navigates a browsing context: the
+ * one a browser makes when it follows a document redirect.
+ */
+const NAVIGATION_FETCH_DESTS: ReadonlySet<string> = new Set([
+  "document",
+  "iframe",
+  "frame",
+]);
+
+/**
+ * A request that navigates: the browser shows its response. Where the browser
+ * sends `Sec-Fetch-Dest`, it must name a browsing context. A same-path
+ * `fetch()` with a wildcard `Accept` or a `<link rel=prefetch>` passes
+ * mayNeedSSR but sends `empty`, and must not eat the cookie before the
+ * navigation it was left for. A request without the header (an older
+ * browser, a non-browser client) keeps the mayNeedSSR rule alone.
+ */
+function isNavigationRequest(request: Request): boolean {
+  const dest = requestHeaders(request).get("sec-fetch-dest");
+  return dest === null || NAVIGATION_FETCH_DESTS.has(dest);
+}
+
+/**
+ * Read the cookie a document redirect left for this request: seed
+ * `_locationState` with its slots and clear it. Only a GET document request
+ * of the target pathname that navigates consumes it (the request the browser
+ * makes for a 301/302/303, see isNavigationRequest); any other request, a
+ * form POST to that path or a prefetch of it included, leaves it to its
+ * expiry. A malformed value is cleared and ignored, and only `__rsc_ls_*`
+ * slots are taken from it (the value comes from the browser).
+ */
+export function consumeDocumentLocationState(
+  reqCtx: Pick<RequestContext, "_locationState" | "setCookie">,
+  request: Request,
+  url: URL,
+  stateCookieName: string,
+): void {
+  if (request.method !== "GET") return;
+  if (!isDocumentRequest(request, url)) return;
+  if (!isNavigationRequest(request)) return;
+  const secure = url.protocol === "https:";
+  const name = documentLocationStateCookieName(stateCookieName, secure);
+  const raw = getRawCookieValue(requestHeaders(request).get("cookie"), name);
+  if (raw === null) return;
+  const carried = parseCarriedState(raw);
+  if (carried && carried.p !== url.pathname) return;
+  reqCtx.setCookie(name, "", { ...cookieAttributes(secure), maxAge: 0 });
+  if (!carried) return;
+  const entries: LocationStateEntry[] = [];
+  for (const key of Object.keys(carried.s)) {
+    if (!isLocationStateKey(key)) continue;
+    entries.push({ __rsc_ls_key: key, __rsc_ls_value: carried.s[key] });
+  }
+  if (entries.length === 0) return;
+  reqCtx._locationState = entries;
+}
+
+/** JSON keeps it as it is: what the cookie can carry without change. */
+function isJsonPlain(value: unknown): boolean {
+  if (value === null) return true;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return true;
+    case "number":
+      return Number.isFinite(value);
+    case "object": {
+      if (Array.isArray(value)) return value.every(isJsonPlain);
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) return false;
+      return Object.values(value as Record<string, unknown>).every(
+        (member) => member !== undefined && isJsonPlain(member),
+      );
+    }
+    default:
+      return false;
+  }
+}
+
+function slotNames(state: Record<string, unknown>): string {
+  return Object.keys(state).join(", ");
+}
+
+/**
+ * Write the cookie on a document request's redirect that set location state,
+ * and mark the redirect private. Not for a partial or action request (their
+ * redirect is a Flight payload), an external or cross-origin target (the
+ * cookie would never reach it) or a response that is not a 3xx with a
+ * Location. Returns the response to send: a new one when its headers are
+ * immutable.
+ */
+export function carryLocationStateAcrossRedirect(
+  response: Response,
+  reqCtx: Pick<RequestContext, "_locationState">,
+  request: Request,
+  url: URL,
+  stateCookieName: string,
+): Response {
+  const entries = reqCtx._locationState;
+  if (!entries || entries.length === 0) return response;
+  if (!isDocumentRequest(request, url)) return response;
+  if (response.status < 300 || response.status >= 400) return response;
+  if (isExternalRedirect(response)) return response;
+  const location = response.headers.get("Location");
+  if (!location) return response;
+  let target: URL;
+  try {
+    target = new URL(location, url);
+  } catch {
+    return response;
+  }
+  if (target.origin !== url.origin) return response;
+
+  let state: Record<string, unknown>;
+  try {
+    state = resolveLocationStateEntries(entries);
+  } catch (error) {
+    // A lazy entry's getter threw: the redirect still leaves, without state.
+    console.warn(
+      "[rango] Location state was dropped from a document redirect: " +
+        `resolving it threw (${String(error)}).`,
+    );
+    return response;
+  }
+  if (process.env.NODE_ENV !== "production") {
+    for (const [key, value] of Object.entries(state)) {
+      if (!isJsonPlain(value)) {
+        console.warn(
+          `[rango] Location state "${key}" crosses a document redirect as JSON, ` +
+            "which does not keep this value as it is (a Date, Map, Set, bigint, " +
+            "undefined or class instance). Store plain JSON data in state that a " +
+            "document request redirects with.",
+        );
+      }
+    }
+  }
+
+  const secure = url.protocol === "https:";
+  const name = documentLocationStateCookieName(stateCookieName, secure);
+  let cookie: string;
+  try {
+    cookie = serializeCookieValue(
+      name,
+      JSON.stringify({ p: target.pathname, s: state } satisfies CarriedState),
+      { ...cookieAttributes(secure), maxAge: DOCUMENT_LOCATION_STATE_MAX_AGE },
+    );
+  } catch {
+    console.warn(
+      `[rango] Location state (${slotNames(state)}) was dropped from a document ` +
+        "redirect: it cannot be serialized as JSON.",
+    );
+    return response;
+  }
+  if (cookie.length > DOCUMENT_LOCATION_STATE_MAX_BYTES) {
+    console.warn(
+      `[rango] Location state (${slotNames(state)}) was dropped from a document ` +
+        `redirect: its cookie is ${cookie.length} bytes, over the ` +
+        `${DOCUMENT_LOCATION_STATE_MAX_BYTES}-byte limit. Carry less state, or ` +
+        "an id the target page loads the rest by.",
+    );
+    return response;
+  }
+
+  return withHeaders(response, (headers) => {
+    headers.append("Set-Cookie", cookie);
+    headers.set("Cache-Control", PRIVATE_NO_STORE);
+  });
+}
+
+/**
+ * Apply `write` to the response's headers, or to a copy of the response when
+ * they are immutable (a `Response.redirect()`). A WebSocket upgrade is never
+ * rebuilt and never carries location state.
+ */
+function withHeaders(
+  response: Response,
+  write: (headers: Headers) => void,
+): Response {
+  if (isWebSocketUpgradeResponse(response)) return response;
+  try {
+    write(response.headers);
+    return response;
+  } catch {
+    const copy = new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: new Headers(response.headers),
+    });
+    write(copy.headers);
+    return copy;
+  }
+}
+
+/**
+ * `Cache-Control: private, no-store` on a document that carries location
+ * state, after every middleware: a shared cache must never store or replay
+ * one visitor's state. Returns the response to send.
+ */
+export function markDocumentResponsePrivate(
+  response: Response,
+  reqCtx: Pick<RequestContext, "_documentLocationState">,
+): Response {
+  if (!reqCtx._documentLocationState) return response;
+  return withHeaders(response, (headers) =>
+    headers.set("Cache-Control", PRIVATE_NO_STORE),
+  );
+}

package/src/server/request-context.ts

@@ -680,12 +680,22 @@ export interface RequestContext<
   /**
    * Attach location state entries to the current response.
    *
-   * For partial (SPA) requests, the state is included in the RSC payload
-   * metadata and merged into history.pushState on the client. For redirect
-   * responses, the state travels through the redirect payload so the target
-   * page can read it via useLocationState.
+   * For a client navigation or an action, the state is included in the RSC
+   * payload metadata and merged into the entry's history.state on the
+   * client. For a document request (a page load, a no-JS form post), it rides
+   * the document's bootstrap payload and is merged into the entry when the
+   * client starts; readers get it once the page has hydrated. For a redirect,
+   * the state travels with the redirect: in its Flight payload on a
+   * navigation or action, in a one-shot cookie the target's document request
+   * reads on a document request. A document that carries state is sent
+   * `Cache-Control: private, no-store` and never stored by the document cache
+   * or as a PPR shell.
    *
-   * Multiple calls accumulate entries.
+   * Multiple calls accumulate entries across definitions. For one definition
+   * the last write wins: two entries of the same definition share its slot
+   * in history.state, so a later call (or a later entry in one array)
+   * replaces an earlier one. To combine writes, make the state an array and
+   * write it once.
    *
    * @example
    * ```typescript
@@ -697,6 +707,14 @@ export interface RequestContext<
   /** @internal Accumulated location state entries */
   _locationState?: LocationStateEntry[];
 
+  /**
+   * @internal Set when a document's payload carries location state
+   * (rsc/rsc-rendering.ts, rsc/progressive-enhancement.ts), a shell HIT's
+   * included. The document is per visitor: the document cache refuses it,
+   * and it leaves `private, no-store` (server/document-location-state.ts).
+   */
+  _documentLocationState?: boolean;
+
   /**
    * The matched route name, if the route has an explicit name.
    * Undefined before route matching or for unnamed routes.
@@ -1006,6 +1024,7 @@ export type PublicRequestContext<
   | "_requestKind"
   | "_payloadVisitorLocation"
   | "_locationState"
+  | "_documentLocationState"
   | "_routeName"
   | "_prevRouteKey"
   | "_visitorMoved"

package/src/testing/dispatch.ts

@@ -177,6 +177,8 @@ interface DispatchableRouter<TEnv> {
   onTimeout?: OnTimeoutCallback<TEnv>;
   findMatch: ClassifyRequestDeps<TEnv>["findMatch"];
   basename?: string;
+  /** The rango state cookie name (RangoInternal field). */
+  resolvedStateCookieName: string;
   cache?:
     | {
         enabled?: boolean;
@@ -292,6 +294,7 @@ export async function dispatch<TEnv = any>(
       telemetry: router.telemetry,
       timeouts: router.timeouts,
       onTimeout: router.onTimeout,
+      resolvedStateCookieName: router.resolvedStateCookieName,
     },
     callOnError: stages.createErrorReporter<TEnv>(router),
     // A response-route handler's own throw is serialized into the same typed

package/src/testing/render-route.tsx

@@ -116,6 +116,7 @@ import {
 } from "../browser/react/location-state-shared.js";
 import {
   buildHistoryState,
+  applyDocumentLocationState,
   clearLocationStateOnDocumentLoad,
   pushHistoryWithIdx,
   resolveNavigationState,
@@ -274,6 +275,25 @@ export interface RenderRouteOptions {
   locationState?: ReadonlyArray<
     readonly [LocationStateDefinition<any, any>, unknown]
   >;
+  /**
+   * Location state the document response carries, as `[def, value]` pairs:
+   * what a handler, middleware or no-JS form action set with
+   * `ctx.setLocationState()` (or a document redirect carried) for this page
+   * load. Merged into the entry at start-up as initBrowserApp merges the
+   * bootstrap payload's: after `locationState` and, with `hydrate: true`,
+   * after the `clearOnReload` pass, so a `clearOnReload` slot given here is
+   * applied. With `hydrate: true` a reader hydrates as `undefined` and gets
+   * the value once the root has hydrated.
+   *
+   * @example
+   * await renderRoute([{ path: "/", Component: FlashBanner }], {
+   *   hydrate: true,
+   *   documentLocationState: [[FlashMessage, { text: "Payment declined" }]],
+   * });
+   */
+  documentLocationState?: ReadonlyArray<
+    readonly [LocationStateDefinition<any, any>, unknown]
+  >;
   /**
    * Handles to seed by REFERENCE, for components that read handle output via
    * `useHandle(SomeHandle)` (e.g. a client `Breadcrumbs` trail). Each entry is
@@ -510,6 +530,19 @@ export interface TestRouterHandle {
 /** Result of renderRoute: RTL's render result plus the router handle. */
 export type RenderRouteResult = RenderResult & { router: TestRouterHandle };
 
+/** `[def, value]` seeds as `history.state` slots, each def keyed. */
+function locationStateSlots(
+  seeds:
+    | ReadonlyArray<readonly [LocationStateDefinition<any, any>, unknown]>
+    | undefined,
+): Record<string, unknown> {
+  const slots: Record<string, unknown> = {};
+  for (const [def, value] of seeds ?? []) {
+    slots[withLocationStateKey(def).__rsc_ls_key] = value;
+  }
+  return slots;
+}
+
 /** Result of renderRoute with `hydrate: true`. */
 export type RenderRouteHydrateResult = RenderRouteResult & {
   /** The HTML the server pass produced, as placed in the container. */
@@ -743,14 +776,15 @@ export async function renderRoute(
     // The tree has no app version (its bridge reports none), so a seed needs
     // none either. Reset what an initBrowserApp in the same file may have left.
     setLocationStateVersion(undefined);
-    const stateObj: Record<string, unknown> = {};
-    for (const [def, value] of options.locationState ?? []) {
-      stateObj[withLocationStateKey(def).__rsc_ls_key] = value;
-    }
-    window.history.replaceState(stateObj, "");
+    window.history.replaceState(locationStateSlots(options.locationState), "");
     // Hydrate mode is a document load of the seeded entry: run start-up's
-    // step (initBrowserApp), not a copy of it.
+    // steps (initBrowserApp), not a copy of them.
     if (options.hydrate) clearLocationStateOnDocumentLoad();
+    if (options.documentLocationState) {
+      applyDocumentLocationState(
+        locationStateSlots(options.documentLocationState),
+      );
+    }
   }
 
   const resolve = (pathname: string): ResolvedMatch => {

package/src/testing/run-revalidate.ts

@@ -121,7 +121,11 @@ export async function runRevalidate<TEnv = any>(
     belongsToRoute: opts.belongsToRoute ?? true,
   };
   const fns = Array.isArray(fn) ? fn : [fn];
-  return runWithRequestContext(ctx as never, () =>
+  // evaluateRevalidation marks the context it decides on (_sourceHeld); a
+  // caller's own context leaves the run as it came in.
+  const own = opts.context as Record<string, unknown> | undefined;
+  const ownHadMark = own !== undefined && "_sourceHeld" in own;
+  const decision = runWithRequestContext(ctx as never, () =>
     evaluateRevalidation({
       segment,
       prevParams: currentParams,
@@ -146,4 +150,10 @@ export async function runRevalidate<TEnv = any>(
       stale: opts.stale ?? false,
     }),
   );
+  if (own === undefined || ownHadMark) return decision;
+  try {
+    return await decision;
+  } finally {
+    delete own._sourceHeld;
+  }
 }

package/src/testing/serve-shell-request.ts

@@ -269,6 +269,15 @@ export interface ServeShellRequestResult {
    * hydrates without it.
    */
   readPayloadFormState(): Promise<unknown>;
+  /**
+   * The payload's location state as the browser reads it: the slots
+   * (`Def.__rsc_ls_key` to value) a document's start-up merges into its
+   * entry (or a navigation's commit, for a `partial` request). Undefined when
+   * the payload carries none (or no Flight was rendered). A redirect carries
+   * a document request's state in a `Set-Cookie` instead: pass that cookie
+   * on the request of its target to read what the target's payload carries.
+   */
+  readLocationState(): Promise<Record<string, unknown> | undefined>;
   /**
    * For an `action` request, the call's answer as the browser reads it: its
    * result and the `revalidationError` its loaders' reruns report.
@@ -806,6 +815,13 @@ export async function serveShellRequest<TEnv = any>(
       }>(flight);
       return payload.formState;
     },
+    async readLocationState() {
+      if (!flight) return undefined;
+      const payload = await decodePayload<{
+        metadata?: { locationState?: Record<string, unknown> };
+      }>(flight);
+      return payload.metadata?.locationState;
+    },
     async readAction() {
       return flight ? decodeAction(flight) : undefined;
     },

package/src/types/handler-context.ts

@@ -381,9 +381,16 @@ export type HandlerContext<
    */
   setTheme?: (theme: Theme) => void;
   /**
-   * Attach location state entries to this response.
-   * State is delivered to the client via history.pushState and accessible
-   * through the useLocationState() hook.
+   * Attach location state entries to this response, for the useLocationState()
+   * hook to read on the entry this response renders. A client navigation
+   * delivers it with its payload; a document load (a link from outside the
+   * app, a no-JS form post) with its bootstrap payload, once the page has
+   * hydrated; a redirect carries it to its target (in a one-shot cookie on a
+   * document request). A document carrying it is sent
+   * `Cache-Control: private, no-store`.
+   *
+   * Entries accumulate across definitions; for one definition the last write
+   * wins (an earlier entry of it is replaced, not merged).
    *
    * @example
    * ```typescript
@@ -510,6 +517,14 @@ export type InternalHandlerContext<
    * request is a fill. See router/segment-resolution/prefetch-deferral.ts.
    */
   _prefetchDeferral?: import("../router/segment-resolution/prefetch-deferral.js").PrefetchDeferral;
+  /**
+   * @internal A revalidate() predicate that read the source page
+   * (`currentParams`, `currentUrl`, `fromRouteName`) kept a held segment, so
+   * this match's diff is right for that source only (#1331). Set by
+   * evaluateRevalidation (router/revalidation.ts); match-result.ts turns it
+   * into `sourceHeld`, which scopes a prefetch of the response to its source.
+   */
+  _sourceHeld?: true;
   /**
    * @internal DSL loaders registered and not started, by `$$id`: a prefetch
    * deferred them, or a pass that skips loaders (`skipLoaders`) did not run

package/src/types/segments.ts

@@ -299,6 +299,12 @@ export interface MatchResult {
    * source, so the RSC handler scopes its prefetch entry to it (#1007).
    */
   interceptTargeted?: true;
+  /**
+   * Set on a partial match when a revalidate() predicate read the source page
+   * and kept a held segment: the diff is that source's. The RSC handler
+   * scopes its prefetch entry to it, like `interceptTargeted` (#1331).
+   */
+  sourceHeld?: true;
   /**
    * Redirect URL for trailing slash normalization.
    * When set, the RSC handler should return a 308 redirect to this URL

package/src/vite/utils/forward-user-plugins.ts

@@ -24,8 +24,12 @@ import type { Plugin, ResolvedConfig, UserConfig } from "vite";
  *                          Forwarding re-inits workerd, defeating the Node temp
  *                          server. Matched specifically so a scoped user resolver
  *                          like `@cloudflare/kv-alias` is still forwarded.
+ *
+ * `rango generate --runtime` drops these before it resolves the user's config,
+ * so rango()'s configResolved (which writes the static gen files) and the
+ * Cloudflare plugin's config hooks never run there.
  */
-function isDenied(name: string): boolean {
+export function isFrameworkPlugin(name: string): boolean {
   return (
     name.startsWith("vite:") ||
     name === "rsc" ||
@@ -78,6 +82,9 @@ function isForwardable(p: Plugin): boolean {
  * matcher, held in closure) is already populated. Forwarding only the
  * resolution hooks therefore preserves correct resolution while avoiding a
  * second `buildStart`/`configureServer`/`config` lifecycle in the temp server.
+ * `rango generate --runtime` has no main server: it resolves the user config
+ * itself, without the framework plugins (see isFrameworkPlugin), so there a
+ * forwarded plugin's config hooks see no `rsc` environment.
  *
  * `enforce` and `applyToEnvironment` are preserved so ordering and per-environment
  * gating match the real pipeline.
@@ -85,7 +92,8 @@ function isForwardable(p: Plugin): boolean {
  * `apply` is intentionally dropped. Vite filters plugins by `apply` against the
  * command during config resolution, so the `config.plugins` we read here is
  * already command-filtered by the main server (build: `apply: "build"` +
- * unconditional; dev: `apply: "serve"` + unconditional). The discovery temp
+ * unconditional; dev: `apply: "serve"` + unconditional; `rango generate
+ * --runtime` resolves as serve). The discovery temp
  * server is always created with `createServer` (`command === "serve"`), so a
  * forwarded `apply: "build"` plugin would be filtered straight back out -- even
  * during a production build, where build-only resolvers are exactly what
@@ -117,7 +125,7 @@ export function selectForwardableResolvePlugins(
   const forwarded: Plugin[] = [];
   for (const p of plugins) {
     const name = p?.name;
-    if (!name || isDenied(name)) continue;
+    if (!name || isFrameworkPlugin(name)) continue;
     if (!isForwardable(p)) continue;
     forwarded.push(stripToResolutionHooks(p));
   }
@@ -139,8 +147,8 @@ export interface ForwardedRunnerConfig {
 /**
  * Extract the data-only config slice to mirror into the discovery temp server.
  * `alias` is included here so callers no longer need to thread it separately.
- * Accepts the unresolved config too: `rango generate --runtime` must not
- * resolve it (that runs rango()'s configResolved, which writes gen files).
+ * Accepts the unresolved config too: `rango generate --runtime` passes the
+ * config file's own values, without what plugin `config` hooks add.
  *
  * `tsconfigPaths` is forwarded so Vite 8's native tsconfig `paths` resolution
  * (a top-level `resolve` flag, off by default) reaches the temp server. The