@rangojs/router 0.31.0 → 0.33.0

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

@@ -31,6 +31,7 @@ import type { RoutineTrace } from "../rsc/routine-plan.js";
 import type { ActionContinuation } from "../rsc/server-action.js";
 import type { ShellCaptureState } from "../rsc/shell-capture.js";
 import type { FormActionOutcome } from "../rsc/progressive-enhancement.js";
+import { type RequestKind } from "../router/segment-resolution/prefetch-deferral.js";
 import { type ExecutionStart } from "../cache/invalidation-order.js";
 export interface RenderForegroundCursor {
     mode: RenderMode;
@@ -119,8 +120,12 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     setStatus(status: number): void;
     /** @internal Set status bypassing cache-exec guard (for framework error handling) */
     _setStatus(status: number): void;
-    /** @internal Rotate the rango state cookie (server seat of invalidateClientCache). */
-    _rotateStateCookie(): void;
+    /**
+     * @internal Rotate the rango state cookie: its timestamp (the server seat of
+     * invalidateClientCache), or with `"write"` only its write part (a server
+     * action without a directive, cookie-store.ts runActionBody).
+     */
+    _rotateStateCookie(part?: "write"): void;
     /** @internal Set the keepClientCache() directive header on the response. */
     _setKeepCacheDirective(): void;
     /**
@@ -532,11 +537,28 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _payloadDeferred?: boolean;
     /**
-     * @internal What the request says it is: a `<Link>` prefetch or a fill
-     * (`prefetch: false`), read once at creation
-     * (segment-resolution/prefetch-deferral.ts requestKind).
+     * @internal Set by the RSC handler when a partial response carries an
+     * `x-rsc-prefetch-scope` (router/source-reads.ts prefetchScopeOf): its diff
+     * is right for its source page, or a group of them, only. The document
+     * cache keys a partial without its source, so it does not store that
+     * response, whatever Cache-Control it ends up with.
+     */
+    _payloadSourceScoped?: boolean;
+    /**
+     * @internal Set when the answer has nothing live in it, so nothing in it can
+     * fail after the 200's headers left: the document cache middleware on a
+     * fresh HIT, and the RSC handler when the partial match came from storage
+     * (MatchResult.fromStorage). finalizeRequestResponse (rsc/request-stages.ts)
+     * sends such a prefetch the router's prefetch Cache-Control.
+     */
+    _servedFromStorage?: boolean;
+    /**
+     * @internal What the request says it is: a speculative `<Link>` prefetch,
+     * an intent prefetch (hover, `prefetch()`) or a fill (`prefetch: false`),
+     * read once at creation (segment-resolution/prefetch-deferral.ts
+     * requestKind).
      */
-    _requestKind?: "prefetch" | "fill";
+    _requestKind?: RequestKind;
     /**
      * @internal Set when a render shows the visitor's URL of a rewritten
      * request: the payload or SSR seed (renderedLocation, rsc/full-payload.ts)
@@ -547,12 +569,27 @@ 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.
+     * Call it from middleware, a handler or an action. A loader's call
+     * (through `getRequestContext()`) is not supported: the payload takes the
+     * state before loaders settle, so the write may be dropped, and a PPR
+     * shell HIT never sends it.
+     *
+     * 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 +599,22 @@ 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;
+    /**
+     * @internal The `document.cookie` line that re-creates the location state
+     * cookie this request consumed (server/document-location-state.ts). The
+     * consuming response clears the cookie in its headers; a shell HIT that
+     * degrades into a reload after those headers left writes this line first
+     * (rsc/shell-serve.ts shellReloadScript), so the reload reads the state
+     * again.
+     */
+    _carriedLocationStateCookie?: string;
     /**
      * The matched route name, if the route has an explicit name.
      * Undefined before route matching or for unnamed routes.
@@ -795,7 +848,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" | "_payloadSourceScoped" | "_servedFromStorage" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_documentLocationState" | "_carriedLocationStateCookie" | "_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/e2e/server.d.ts

@@ -11,7 +11,13 @@ export interface RunCliHandle {
      */
     exitCode: Promise<number | null>;
     findPort: (timeoutMs?: number) => Promise<number>;
-    kill: () => void;
+    /**
+     * Stop the process and what it spawned (the whole process group). SIGTERM by
+     * default; `stopServer` escalates to SIGKILL for a process that outlives the
+     * wait.
+     */
+    kill: (signal?: NodeJS.Signals) => void;
+    readonly pid: number | undefined;
     stdout: () => string;
     stderr: () => string;
 }
@@ -19,6 +25,15 @@ export declare function runCli(options: {
     command: string;
     label?: string;
 } & SpawnOptions): RunCliHandle;
+/**
+ * Stop a server started by `runCli` and wait for its whole process group to
+ * exit: SIGTERM to the group, then SIGKILL (and a log naming the pid) for a
+ * process that outlives the wait, so a leaked server is visible rather than
+ * left holding its port.
+ */
+export declare function stopServer(server: RunCliHandle, options?: {
+    exitWaitMs?: number;
+}): Promise<void>;
 export declare function tailOutput(text: string, maxChars?: number): string;
 export declare function createIsolatedViteCacheDir(cwd: string, projectName: string, mode: "dev" | "build" | undefined): string;
 export declare function waitForReady(url: string, getOutput?: () => {

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

@@ -35,6 +35,16 @@
  *     not modeled). navigate(url, { streamUntil }) gives the navigation a
  *     response stream that stays open past the commit (isStreaming).
  *     useAction().state stays idle: no action runs.
+ *   - prefetch(url) keeps a page as a prefetch made now carries it, and
+ *     action() lands a server action's response: the page on screen
+ *     re-renders with its post-write loader data, and, without
+ *     `keepClientCache`, production's store marks every history entry and
+ *     prefetch stale (browser/navigation-store.ts). A navigate(url) to a
+ *     prefetched page commits the prefetch's data; when an action made it
+ *     stale, the page then revalidates once the navigation settled, in the
+ *     lane production's Back uses (useNavigation() idle), with the loader
+ *     data current then. The prefetch request, its decode and the HTTP cache
+ *     are e2e territory.
  *   - A spec's transition({ when }) decides every commit with production's
  *     browser decision: navigate() and useRouter().push model kind "push",
  *     useRouter().replace kind "replace", refresh() kind "revalidate", and a
@@ -49,8 +59,8 @@
  *     written there, and another page is on screen, its page is restored
  *     from the history cache, with the handle values it had, as production's
  *     restore is; otherwise the tree keeps its location. A stale entry's
- *     revalidation, a restore that fetches, a server action's state, a
- *     redirect's and an intercept's are e2e territory.
+ *     revalidation on Back, a restore that fetches, a server action's
+ *     location state, a redirect's and an intercept's are e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
@@ -185,6 +195,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
@@ -403,6 +430,60 @@ export interface TestRouterHandle {
      * transition({ when }) decides it with kind "revalidate" (`to` is `from`).
      */
     refresh(): Promise<void>;
+    /**
+     * Prefetch `url`, as a `<Link>` hover or viewport trigger does: the page is
+     * kept with the loader data its response would carry now (the render-time
+     * seeds, `options.loaders` merged over). A later `navigate(url)` without
+     * `loaders` commits that data, whatever the seeds are by then.
+     *
+     * The prefetch is stamped with production's stale epoch
+     * (browser/prefetch/cache.ts): an `action()` without `keepClientCache`
+     * makes it stale. A click on a stale prefetch commits it at once, then the
+     * page revalidates once the navigation settled (its `streamUntil` ended),
+     * in Back's stale-revalidation lane: `useNavigation().state` stays "idle"
+     * and `isNavigating` reads true while its request is open, `useLinkStatus`
+     * shows no pending state, and the commit runs through commitInTransition
+     * with kind "revalidate", reading the loader data current then. A newer
+     * navigation aborts it.
+     *
+     * @example
+     * router.prefetch("/cart"); // carries count 2
+     * await router.action({ loaders: [[BasketLoader, { count: 3 }]] });
+     * await router.navigate("/cart"); // count 2, at once
+     * await waitFor(() => expect(count()).toBe("3")); // revalidated
+     */
+    prefetch(url: string, options?: Pick<RenderRouteOptions, "loaders">): void;
+    /**
+     * Land a server action's response on the page on screen. `loaders` are the
+     * loader values after the action's write: they become the data every
+     * later response carries, and the page on screen re-renders with them in
+     * the action lane (commitInTransition, kind "action", unless
+     * transition({ when }) gates it off). Without `keepClientCache`,
+     * production's store then marks every history entry and every prefetch
+     * stale (`markCacheAsStaleAndBroadcast()`), as the action bridge does:
+     * nothing is flushed and the state cookie is not rotated.
+     * `keepClientCache: true` is the `keepClientCache()` directive: caches stay
+     * fresh. The action's own lifecycle (`useAction()`), its follow-up and its
+     * redirect are e2e territory.
+     */
+    action(options?: Pick<RenderRouteOptions, "loaders"> & {
+        keepClientCache?: boolean;
+    }): Promise<void>;
+    /**
+     * The background revalidations a click on a stale prefetch started, in
+     * order: the page's pathname and search, and the segment ids the request
+     * holds, as production's bridge plans them
+     * (navigation-bridge.ts scheduleStalePrefetchRevalidation). A click on a
+     * fresh prefetch, or after a `keepClientCache` action, starts none.
+     *
+     * @example
+     * await router.navigate("/cart"); // a stale prefetch
+     * await waitFor(() => expect(router.revalidations()).toHaveLength(1));
+     */
+    revalidations(): ReadonlyArray<{
+        url: string;
+        segmentIds: string[];
+    }>;
     /** The current committed pathname. */
     pathname(): string;
     /** The current committed params. */

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

@@ -65,9 +65,12 @@ export interface ServeShellRequestOptions<TEnv = any> {
      * (default none), advertising fragment passthrough. The replay decision is
      * `result.replayStatus`.
      *
-     * `prefetch: true` sends it as a `<Link>` prefetch does (the
-     * `X-Rango-Prefetch` header), so `prefetch: false` loaders and `loading()`
-     * entries are deferred: `result.readDeferred()` lists them. `fill: true`
+     * `prefetch: true` sends the speculative kind a viewport or render
+     * `<Link>` prefetch sends (`X-Rango-Prefetch: 1`), so `prefetch: false`
+     * loaders and `loading()` entries are deferred: `result.readDeferred()`
+     * lists them. A hover's or `prefetch()`'s intent prefetch defers nothing;
+     * serve it with `prefetch: true` and `headers: { "X-Rango-Prefetch":
+     * "intent" }`, which `prefetch: true` leaves as given. `fill: true`
      * sends the request the browser follows an adopted prefetch with
      * (`_rsc_fill`): pass the ids the prefetch delivered, without the deferred
      * ones, as `segments`, and the same URL as `from`. `interceptSource` sends
@@ -229,6 +232,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,16 @@ 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 only for pages with equal values of what the
+     * kept decisions read (#1331). Set by evaluateRevalidation
+     * (router/revalidation.ts) and the stored-entry keep
+     * (match-middleware/cache-lookup.ts); match-result.ts turns it into
+     * `sourceHeld`, which scopes a prefetch of the response to that group.
+     */
+    _sourceHeld?: import("../router/source-reads.js").SourceHeld;
     /**
      * @internal DSL loaders registered and not started, by `$$id`: a prefetch
      * deferred them, or a pass that skips loaders (`skipLoaders`) did not run
@@ -534,7 +551,7 @@ export type IsActionFn = (...actions: ActionRef[]) => boolean;
 export type ShouldRevalidateFn<TParams = GenericParams, TEnv = any> = (args: {
     /** Route params from the page being navigated away from. */
     currentParams: TParams;
-    /** Full URL of the page being navigated away from. */
+    /** Full URL of the page being navigated away from, without its #fragment. */
     currentUrl: URL;
     /** Route params for the navigation target. */
     nextParams: TParams;

package/dist/types/types/loader-types.d.ts

@@ -182,10 +182,13 @@ export type LoaderFn<T, TParams = Record<string, string | undefined>, TEnv = Def
 export type LoaderOptions = {
     ssr?: boolean;
     /**
-     * `prefetch: false` keeps this loader out of prefetches. A `<Link>`
-     * prefetch (a partial request with `X-Rango-Prefetch`) does not execute it;
-     * the payload marks it deferred. A document request and a navigation with
-     * no prefetch to adopt run it as usual.
+     * `prefetch: false` keeps this loader out of speculative prefetches. A
+     * viewport or render `<Link>` prefetch (a partial request with
+     * `X-Rango-Prefetch: 1`) does not execute it; the payload marks it
+     * deferred. A hover prefetch and `useRouter().prefetch()`
+     * (`X-Rango-Prefetch: intent`) count as intent to click and run it, so a
+     * click after a hover needs no follow-up request. A document request and a
+     * navigation with no prefetch to adopt run it as usual.
      *
      * A deferred loader never blocks the navigation that adopts the prefetch:
      * it behaves like a loader that is still streaming. Its own `<Suspense>`

package/dist/types/types/segments.d.ts

@@ -147,7 +147,6 @@ export interface ResolvedSegment {
     layoutName?: string;
     parallelName?: string;
     loaderId?: string;
-    _inherited?: boolean;
     loaderData?: any;
     /**
      * True when this loader was awaited before first flush
@@ -274,6 +273,24 @@ 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 right for the pages with equal values
+     * of what it read. The RSC handler scopes its prefetch entry to that group,
+     * or to the source page when the predicate read `currentUrl` (#1331).
+     */
+    sourceHeld?: import("../router/source-reads.js").SourceHeld;
+    /**
+     * Set on a partial match whose answer has nothing live in it: the cache
+     * lookup served it (a cache() record, a Prerender entry, a shell replay's
+     * record, not a stale cache() record or stale overlay entry), it sends a
+     * segment, every segment it
+     * sends is one that lookup decoded, and no loader ran. A stored segment
+     * cannot fail after the headers left, since every writer refuses a failed
+     * render; a live segment or a loader can. The RSC handler marks the request
+     * `_servedFromStorage` from it.
+     */
+    fromStorage?: true;
     /**
      * Redirect URL for trailing slash normalization.
      * When set, the RSC handler should return a 308 redirect to this URL

package/dist/types/urls/path-helper-types.d.ts

@@ -161,9 +161,10 @@ export type PathHelpers<TEnv> = {
      * freezes into the shell (nested promises stay live holes) — the pre-flush
      * promise applied to the prelude.
      *
-     * Pass `{ prefetch: false }` to keep the loader out of prefetches: a
-     * prefetch skips it and the click that adopts the prefetch fetches it in
-     * one follow-up request (see {@link LoaderOptions}). Only on a segment the
+     * Pass `{ prefetch: false }` to keep the loader out of speculative
+     * prefetches (viewport, render): such a prefetch skips it and the click
+     * that adopts it fetches it in one follow-up request; a hover prefetch runs
+     * it (see {@link LoaderOptions}). Only on a segment the
      * client does not have yet: a loader the client already holds runs in the
      * prefetch when it revalidates.
      */
@@ -172,8 +173,9 @@ export type PathHelpers<TEnv> = {
      * Attach a loading component to the current route/layout.
      *
      * `{ ssr: false }` skips the fallback on document requests. `{ prefetch:
-     * false }` keeps what the fallback covers out of prefetches, when this
-     * entry's segment is new to the client: the entry's handler, its loaders,
+     * false }` keeps what the fallback covers out of viewport and render
+     * prefetches (a hover prefetch runs it), when this entry's segment is new
+     * to the client: the entry's handler, its loaders,
      * its orphan layouts and parallel slots and, for a layout, every deeper
      * entry. The click that adopts the prefetch shows the fallback and fetches
      * them in one follow-up request, which reads cache() and "use cache" as

package/dist/types/vite/temp-rsc-server.d.ts

@@ -7,8 +7,8 @@
  *
  * Sits in src/vite/, not src/vite/discovery/: the loader hook URL below
  * 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.
+ * (dist/vite/index.js, and the CLI's code-split chunks in dist/bin/) ship the
+ * hook at the same relative path.
  */
 import type { ViteDevServer } from "vite";
 import type { DiscoveryState } from "./discovery/state.js";

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