@rangojs/router 0.31.0 → 0.32.0

package/dist/bin/rango.js

@@ -1762,7 +1762,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.31.0",
+      version: "0.32.0",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",
@@ -9859,10 +9859,11 @@ var init_temp_rsc_server = __esm({
 // src/vite/utils/forward-user-plugins.ts
 var forward_user_plugins_exports = {};
 __export(forward_user_plugins_exports, {
+  isFrameworkPlugin: () => isFrameworkPlugin,
   pickForwardedRunnerConfig: () => pickForwardedRunnerConfig,
   selectForwardableResolvePlugins: () => selectForwardableResolvePlugins
 });
-function isDenied(name) {
+function isFrameworkPlugin(name) {
   return name.startsWith("vite:") || name === "rsc" || name.startsWith("rsc:") || name.startsWith("@rangojs/router") || name.startsWith("@cloudflare/vite-plugin") || name.startsWith("vite-plugin-cloudflare");
 }
 function isForwardable(p) {
@@ -9886,7 +9887,7 @@ function selectForwardableResolvePlugins(plugins) {
   const forwarded = [];
   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));
   }
@@ -9934,9 +9935,11 @@ import { basename, resolve as resolve4 } from "node:path";
 import { existsSync as existsSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "node:fs";
 async function discoverAndWriteRouteTypes(opts) {
   let loadConfigFromFile;
+  let resolveConfig;
   try {
     const vite = await import("vite");
     loadConfigFromFile = vite.loadConfigFromFile;
+    resolveConfig = vite.resolveConfig;
   } catch {
     throw new Error(
       "Runtime discovery requires 'vite'. Install it with: pnpm add -D vite"
@@ -9952,7 +9955,11 @@ async function discoverAndWriteRouteTypes(opts) {
   const { createTempRscServer: createTempRscServer2 } = await Promise.resolve().then(() => (init_temp_rsc_server(), temp_rsc_server_exports));
   const { createDiscoveryState: createDiscoveryState2 } = await Promise.resolve().then(() => (init_state(), state_exports));
   const { discoverClientUrlProjections: discoverClientUrlProjections2 } = await Promise.resolve().then(() => (init_client_urls_projection(), client_urls_projection_exports));
-  const { pickForwardedRunnerConfig: pickForwardedRunnerConfig2, selectForwardableResolvePlugins: selectForwardableResolvePlugins2 } = await Promise.resolve().then(() => (init_forward_user_plugins(), forward_user_plugins_exports));
+  const {
+    isFrameworkPlugin: isFrameworkPlugin2,
+    pickForwardedRunnerConfig: pickForwardedRunnerConfig2,
+    selectForwardableResolvePlugins: selectForwardableResolvePlugins2
+  } = await Promise.resolve().then(() => (init_forward_user_plugins(), forward_user_plugins_exports));
   const entryPath = resolve4(opts.entry);
   const state = createDiscoveryState2(entryPath, void 0);
   state.projectRoot = opts.root;
@@ -9966,9 +9973,32 @@ async function discoverAndWriteRouteTypes(opts) {
       );
       if (loaded) {
         state.userRunnerConfig = pickForwardedRunnerConfig2(loaded.config);
-        state.userResolvePlugins = selectForwardableResolvePlugins2(
-          await flattenPluginOptions(loaded.config.plugins)
-        );
+        const userPlugins = (await flattenPluginOptions(loaded.config.plugins)).filter((p) => !isFrameworkPlugin2(p.name ?? ""));
+        try {
+          const resolved2 = await resolveConfig(
+            {
+              ...loaded.config,
+              root: opts.root,
+              configFile: false,
+              plugins: userPlugins
+            },
+            "serve",
+            "development"
+          );
+          state.userResolvePlugins = selectForwardableResolvePlugins2(
+            resolved2.plugins
+          );
+        } catch (err) {
+          console.warn(
+            `[rango] Could not resolve the Vite config (${err?.message ?? err}); forwarding its resolver plugins without their config hooks. rango() and rsc() are left out of that resolve, so a plugin that needs the rsc environment fails there`
+          );
+          const serveEnv = { command: "serve", mode: "development" };
+          state.userResolvePlugins = selectForwardableResolvePlugins2(
+            userPlugins.filter(
+              (p) => typeof p.apply === "function" ? p.apply(loaded.config, serveEnv) : p.apply !== "build"
+            )
+          );
+        }
       }
     } catch (err) {
       console.warn(

package/dist/types/browser/history-state.d.ts

@@ -35,8 +35,9 @@ export declare function stripShellMissMarker(): void;
  * the server rendered this document without them. One pass before hydration
  * (initBrowserApp; renderRoute's `hydrate` mode), so no reader needs to know
  * the page began as a document load, and a slot nobody reads is removed too.
- * No server-set state exists yet to lose: a document response carries none
- * (rsc-rendering.ts attaches it to partial payloads only).
+ * Server-set state is not lost to it: the state a document response carries
+ * is merged after this pass (applyDocumentLocationState), so a `~r` slot the
+ * server set for this load survives this load and no later one.
  *
  * A slot is recognised by its key alone (the `~r` suffix): at start-up the
  * module that defines it may not be loaded.
@@ -46,6 +47,16 @@ export declare function stripShellMissMarker(): void;
  * is a full page for later Back/Forward.
  */
 export declare function clearLocationStateOnDocumentLoad(): void;
+/**
+ * Merge the location state a document response carried (its bootstrap
+ * payload's `metadata.locationState`, server/document-location-state.ts)
+ * into the entry the document loaded on. Start-up runs it after
+ * clearLocationStateOnDocumentLoad and the version is set, before the entry
+ * is committed for readers (initBrowserApp; renderRoute's `hydrate` mode),
+ * so readers get it once they have hydrated, as stored state. Only typed
+ * slots are taken.
+ */
+export declare function applyDocumentLocationState(locationState: Record<string, unknown> | undefined): void;
 /**
  * Merge server-set location state into the current history entry and return
  * the entry state written. Readers see it when the caller commits it

package/dist/types/browser/react/Link.d.ts

@@ -66,23 +66,20 @@ export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorEle
      * keyed on Rango state + target URL. This is correct for routes whose
      * response shape doesn't depend on where the user navigates from.
      *
-     * Set `":source"` when this Link's response would legitimately differ
-     * based on the source page — typically when the target route (or one
-     * of its layouts) uses a custom `revalidate()` handler that reads
-     * `currentUrl` / `currentParams`, and the wildcard entry would
-     * therefore serve the wrong diff to a navigation from a different
-     * source.
+     * Set `":source"` to scope every prefetch of this Link to the page that
+     * sent it, when its response would differ by source page in a way the
+     * server cannot see.
      *
-     * A route an intercept targets is scoped to the source automatically
-     * (server-side `x-rsc-prefetch-scope: source`), whether or not the
-     * intercept applies from this page: the modal and the full page are
-     * both source-specific. Every other route stays shared, so `":source"`
-     * is only needed for custom revalidation logic.
+     * The server scopes a prefetch to its source automatically
+     * (`x-rsc-prefetch-scope: source`) when an intercept targets the route,
+     * whether or not it applies from this page (the modal and the full page
+     * are both source-specific), and when a `revalidate()` of the target
+     * read `currentParams`, `currentUrl` or `fromRouteName` and kept the
+     * segment: that diff is the source page's (#1331). Every other response
+     * stays shared.
      *
      * @example
      * ```tsx
-     * // Route uses a `revalidate()` that branches on currentUrl — opt in
-     * // so prefetches don't bleed across source pages.
      * <Link to="/dashboard" prefetch="hover" prefetchKey=":source" />
      * ```
      */

package/dist/types/browser/react/location-state-shared.d.ts

@@ -269,7 +269,8 @@ export declare function isLocationStateDefinition(value: unknown): value is Loca
  */
 export declare function isLocationStateEntry(value: unknown): value is LocationStateEntry;
 /**
- * Resolve state entries into a flat object for history.state
+ * Resolve state entries into a flat object for history.state. One slot per
+ * definition: a later entry of the same definition replaces an earlier one.
  */
 export declare function resolveLocationStateEntries(entries: LocationStateEntry[]): Record<string, unknown>;
 export {};

package/dist/types/cache/document-cache-policy.d.ts

@@ -12,7 +12,7 @@ export interface CacheDirectives {
 /**
  * Check if response should be cached based on Cache-Control headers
  */
-export declare function shouldCacheResponse(response: Response, requestCtx?: Pick<RequestContext, "_payloadVisitorTheme" | "_payloadDeferred" | "_payloadVisitorLocation">): CacheDirectives | null;
+export declare function shouldCacheResponse(response: Response, requestCtx?: Pick<RequestContext, "_payloadVisitorTheme" | "_payloadDeferred" | "_payloadVisitorLocation" | "_documentLocationState">): CacheDirectives | null;
 /**
  * Whether this cache will store the response the current render produces, as
  * far as the render can tell: the middleware runs it (a MISS or a stale

package/dist/types/route-definition/redirect.d.ts

@@ -9,6 +9,11 @@ import type { LocationStateEntry } from "../browser/react/location-state-shared.
  * Supports an optional state parameter to carry location state through the
  * redirect. On the target page, state can be read via useLocationState()
  * (use { flash: true } in createLocationState for read-once flash messages).
+ * On a client navigation or action the state travels in the redirect's
+ * payload. On a document request (a page load, a no-JS form post) it travels
+ * in a one-shot cookie the target's document request reads and clears, as
+ * JSON: give it plain JSON data there. `{ external: true }` carries none.
+ * Two entries of the same definition keep only the last.
  *
  * @param url - The URL to redirect to
  * @param statusOrOptions - HTTP status code (default: 302) or options object

package/dist/types/router/middleware-types.d.ts

@@ -56,6 +56,12 @@ export interface MiddlewareContext<TEnv = any, TParams = Record<string, string |
      */
     readonly theme?: Theme;
     setTheme?: (theme: Theme) => void;
+    /**
+     * Attach location state entries to this response (see the handler
+     * context's `setLocationState`). Entries accumulate across definitions;
+     * for one definition the last write wins. Set it here rather than in a
+     * handler on a `ppr` route: a shell HIT runs no handler.
+     */
     setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
     /** Global route names only; see {@link GlobalReverseFunction}. */
     reverse: GlobalReverseFunction<DefaultReverseRouteMap>;

package/dist/types/rsc/helpers.d.ts

@@ -95,10 +95,12 @@ export declare function interceptRedirectForPartial(response: Response, createRe
 /**
  * Attach location state set during a request to a payload's metadata.
  * No-op if no location state was set. Callers must ensure payload.metadata
- * is populated (the non-null assertion holds for the partial/action payloads
- * that reach this helper).
+ * is populated. A `document` payload (a page load's or a no-JS form post's
+ * bootstrap payload) that carries state marks the request
+ * `_documentLocationState`: it is the visitor's, so no shared cache keeps it
+ * (server/document-location-state.ts).
  */
-export declare function attachLocationStateIfPresent(payload: RscPayload): void;
+export declare function attachLocationStateIfPresent(payload: RscPayload, document?: boolean): void;
 /**
  * Only cache successful responses. Non-200 statuses (errors, redirects) are
  * not cached -- notFound() produces 500 in response routes, and explicit

package/dist/types/rsc/request-stages.d.ts

@@ -36,6 +36,8 @@ export interface StageRouter<TEnv = unknown> {
     readonly telemetry?: TelemetrySink;
     readonly timeouts?: ResolvedTimeouts;
     readonly onTimeout?: OnTimeoutCallback<TEnv>;
+    /** Names the cookie location state crosses a document redirect in. */
+    readonly resolvedStateCookieName: string;
 }
 /** Report an error through the router's onError. */
 export type ReportError<TEnv = unknown> = (error: unknown, phase: ErrorPhase, context: InvokeOnErrorContext<TEnv>) => void;

package/dist/types/server/document-location-state.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { type RequestContext } from "./request-context.js";
+/** The cookie's name for a router: `__Host-` on https. */
+export declare function documentLocationStateCookieName(stateCookieName: string, secure: boolean): string;
+/**
+ * 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 declare function consumeDocumentLocationState(reqCtx: Pick<RequestContext, "_locationState" | "setCookie">, request: Request, url: URL, stateCookieName: string): void;
+/**
+ * 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 declare function carryLocationStateAcrossRedirect(response: Response, reqCtx: Pick<RequestContext, "_locationState">, request: Request, url: URL, stateCookieName: string): Response;
+/**
+ * `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 declare function markDocumentResponsePrivate(response: Response, reqCtx: Pick<RequestContext, "_documentLocationState">): Response;

package/dist/types/server/request-context.d.ts

@@ -547,12 +547,22 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     /**
      * 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
@@ -562,6 +572,13 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
     /** @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.
@@ -795,7 +812,7 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureState" | "_shellImplicitCache" | "_shellLoaderSeed" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_shellFragmentPayload" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_reportedErrors" | "_throwers" | "_printedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_handlerTiming" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureState" | "_shellImplicitCache" | "_shellLoaderSeed" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_shellFragmentPayload" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_documentLocationState" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_reportedErrors" | "_throwers" | "_printedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_handlerTiming" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:

package/dist/types/testing/render-route.d.ts

@@ -185,6 +185,23 @@ 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

package/dist/types/testing/serve-shell-request.d.ts

@@ -229,6 +229,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.

package/dist/types/types/handler-context.d.ts

@@ -274,9 +274,16 @@ export type HandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch extends Sear
      */
     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
@@ -390,6 +397,14 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
      * 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/dist/types/types/segments.d.ts

@@ -274,6 +274,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/dist/types/vite/utils/forward-user-plugins.d.ts

@@ -1,4 +1,34 @@
 import type { Plugin, ResolvedConfig, UserConfig } from "vite";
+/**
+ * Whether a user plugin must NOT be forwarded into the discovery temp server.
+ *
+ * Framework-owned plugins are matched precisely -- by exact name or a
+ * namespaced prefix -- rather than by a loose substring/word prefix, so an
+ * unrelated user resolver named e.g. `rsc-paths` or `cloudflare-kv-alias` is
+ * still forwarded (it would otherwise reproduce issue #500).
+ *
+ * - `vite:*`               Vite core + official plugins (incl.
+ *                          @vitejs/plugin-react's `vite:react-*`). The temp
+ *                          server already provides its own core; forwarding
+ *                          these would duplicate or conflict with it.
+ * - `rsc` / `rsc:*`        @vitejs/plugin-rsc. createTempRscServer instantiates
+ *                          its own rsc() plugin; forwarding would duplicate it.
+ *                          Matched exactly (`rsc`) or by the `rsc:` namespace --
+ *                          NOT every `rsc`-prefixed name.
+ * - `@rangojs/router*`     Our own plugins. The discovery plugin spawns the
+ *                          temp server, so forwarding would recurse infinitely.
+ * - `@cloudflare/vite-plugin*` / @cloudflare/vite-plugin (emits the scoped
+ *   `vite-plugin-cloudflare*`  `@cloudflare/vite-plugin` and unscoped
+ *                          `vite-plugin-cloudflare` / `vite-plugin-cloudflare:*`).
+ *                          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.
+ */
+export declare function isFrameworkPlugin(name: string): boolean;
 /**
  * Pick the user's resolution plugins from the resolved plugin list, denylist
  * framework-owned plugins, keep only those with resolution hooks, and strip
@@ -20,8 +50,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

package/dist/vite/index.js

@@ -7146,7 +7146,7 @@ function resolveVersionsFrom(table, routerId2) {
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.31.0",
+  version: "0.32.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -14666,7 +14666,7 @@ function bundleScanPhase(s, context, bundle) {
 }
 
 // src/vite/utils/forward-user-plugins.ts
-function isDenied(name) {
+function isFrameworkPlugin(name) {
   return name.startsWith("vite:") || name === "rsc" || name.startsWith("rsc:") || name.startsWith("@rangojs/router") || name.startsWith("@cloudflare/vite-plugin") || name.startsWith("vite-plugin-cloudflare");
 }
 var IMPORT_REWRITE_PLUGINS = /* @__PURE__ */ new Set([
@@ -14693,7 +14693,7 @@ function selectForwardableResolvePlugins(plugins) {
   const forwarded = [];
   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));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/comparison/references/framework-comparison.md

@@ -558,8 +558,9 @@ analog but operates on loader/query reload, not RSC-segment render.
 
 `<Link prefetch="hover|viewport|render|adaptive|none">` (default: the router's
 `defaultPrefetch`, `"none"` in development and `"viewport"` in production), plus
-`prefetchKey` (`":source"` scopes a prefetch to the originating page for routes
-whose response branches on `currentUrl`). Intercepted plain `<a href>` elements
+`prefetchKey` (`":source"` scopes a prefetch to the originating page; the
+router does so itself for an intercept target and for a `revalidate()` that
+read the source page and kept a segment). Intercepted plain `<a href>` elements
 inside the router basename follow the same default; common static-resource
 extensions are excluded unless `data-prefetch="true"` identifies an application
 route, and `data-prefetch="false"` or `"none"` opts out unsafe GET links. A

package/skills/document-cache/SKILL.md

@@ -228,6 +228,11 @@ suffixes are still appended.
   (`rango-state-fresh` by default), so it is not stored. A stale entry's
   background re-run sets no fresh-reads cookie (no visitor made that
   invalidation), so its invalidation does not keep the refreshed page out.
+- A document that carries location state (`ctx.setLocationState()`, or the
+  one-shot cookie a document redirect left for it): it is the visitor's, so it
+  is not stored, leaves `private, no-store`, and a request that arrives with
+  that cookie, or whose earlier middleware set state, is not answered from a
+  stored entry (see `/hooks` `state.md`, "State on a document response")
 - Non-200 responses
 - A 200 whose render reported an error: a component that threw after the
   response started streaming, such as an async server component whose fetch