@rangojs/router 0.30.1 → 0.32.0

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/build/generate-route-types.d.ts

@@ -4,5 +4,5 @@ export { generatePerModuleTypesSource, generateRouteTypesSource, } from "./route
 export { DEFAULT_EXCLUDE_PATTERNS, type ScanFilter, createScanFilter, findTsFiles, isInSkippedScanDir, } from "./route-types/scan-filter.js";
 export { writePerModuleRouteTypes, writePerModuleRouteTypesForFile, } from "./route-types/per-module-writer.js";
 export { type UnresolvableReason, type UnresolvableInclude, extractIncludesWithDiagnostics, } from "./route-types/include-resolution.js";
-export { extractUrlsFromRouter, extractBasenameFromRouter, type UrlsExtractionResult, buildCombinedRouteMapForRouterFile, detectUnresolvableIncludes, detectUnresolvableIncludesForUrlsFile, findNestedRouterConflict, formatNestedRouterConflictError, findRouterFiles, findHostRouterFiles, writeCombinedRouteTypes, genFileTsPath, resolveSearchSchemas, } from "./route-types/router-processing.js";
+export { extractUrlsFromRouter, type UrlsExtractionResult, buildCombinedRouteMapForRouterFile, detectUnresolvableIncludes, detectUnresolvableIncludesForUrlsFile, findNestedRouterConflict, formatNestedRouterConflictError, findRouterFiles, findHostRouterFiles, writeCombinedRouteTypes, genFileTsPath, resolveSearchSchemas, } from "./route-types/router-processing.js";
 export { findUrlsVariableNames } from "./route-types/per-module-writer.js";

package/dist/types/build/route-types/include-resolution.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-export type UnresolvableReason = "factory-call" | "dynamic-expression" | "unresolvable-import" | "file-not-found";
+export type UnresolvableReason = "factory-call" | "dynamic-expression" | "unresolvable-import" | "file-not-found" | "unresolvable-basename";
 export interface UnresolvableInclude {
     pathPrefix: string;
     namePrefix: string | null;

package/dist/types/build/route-types/router-processing.d.ts

@@ -30,11 +30,6 @@ export type UrlsExtractionResult = {
  * Returns either a variable name or an inline code block.
  */
 export declare function extractUrlsFromRouter(code: string): UrlsExtractionResult | null;
-/**
- * Extract the `basename` string literal from createRouter({ basename: "..." }).
- * Returns the basename value or undefined if not present.
- */
-export declare function extractBasenameFromRouter(code: string): string | undefined;
 export declare function genFileTsPath(sourceFile: string): string;
 export declare function resolveSearchSchemas(publicRouteNames: string[], runtimeSchemas: Record<string, Record<string, string>> | undefined, sourceFile: string): Record<string, Record<string, string>> | undefined;
 /**
@@ -47,8 +42,9 @@ export declare function buildCombinedRouteMapForRouterFile(routerFilePath: strin
 };
 /**
  * Walk the full include tree starting from a router file and detect
- * all includes that the static parser cannot resolve.
- * Returns an array of diagnostics; empty means fully resolvable.
+ * all includes that the static parser cannot resolve, plus an explicit
+ * createRouter `basename` it cannot read (every pattern would lack the
+ * prefix). Returns an array of diagnostics; empty means fully resolvable.
  */
 export declare function detectUnresolvableIncludes(routerFilePath: string): UnresolvableInclude[];
 /**

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/temp-rsc-server.d.ts

@@ -1,12 +1,14 @@
 /**
  * The discovery temp RSC server: a minimal Vite server whose module runner
  * imports the user's router files. Shared by dev discovery
- * (discovery/dev-server-phase.ts) and build discovery
- * (discovery/build-discovery-phase.ts).
+ * (discovery/dev-server-phase.ts), build discovery
+ * (discovery/build-discovery-phase.ts) and `rango generate --runtime`
+ * (build/runtime-discovery.ts).
  *
  * Sits in src/vite/, not src/vite/discovery/: the loader hook URL below
- * resolves against this module's import.meta.url, and the published bundle
- * (dist/vite/index.js) ships the hook at the same relative path.
+ * resolves against this module's import.meta.url, and the published bundles
+ * (dist/vite/index.js, dist/bin/rango.js) ship the hook at the same relative
+ * path.
  */
 import type { ViteDevServer } from "vite";
 import type { DiscoveryState } from "./discovery/state.js";
@@ -36,4 +38,6 @@ export declare function createTempRscServer(state: DiscoveryState, options?: {
      * shell capture actually runs.
      */
     realSsrEntry?: boolean;
+    /** Caller-specific plugins, appended after the forwarded user plugins. */
+    plugins?: import("vite").Plugin[];
 }): Promise<ViteDevServer>;

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,6 +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` 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
@@ -34,4 +66,4 @@ export interface ForwardedRunnerConfig {
  * replaced the deprecated `esbuild` transform option with `oxc`, so we read and
  * forward `oxc` exclusively — no `esbuild` field is touched.
  */
-export declare function pickForwardedRunnerConfig(config: ResolvedConfig): ForwardedRunnerConfig;
+export declare function pickForwardedRunnerConfig(config: Pick<ResolvedConfig | UserConfig, "resolve" | "define" | "oxc">): ForwardedRunnerConfig;