@rangojs/router 0.22.0 → 0.23.0

package/dist/bin/rango.js

@@ -210,9 +210,12 @@ var init_codegen = __esm({
 });
 
 // src/build/route-types/scan-filter.ts
-import { join, relative } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 import { readdirSync } from "node:fs";
 import picomatch from "picomatch";
+function isUniversallySkippedScanDir(name) {
+  return name === "node_modules" || name === "dist" || name === "coverage" || name.startsWith(".");
+}
 function findTsFiles(dir, filter) {
   const results = [];
   let entries;
@@ -227,8 +230,9 @@ function findTsFiles(dir, filter) {
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      if (entry.name === "node_modules" || entry.name.startsWith(".") || entry.name === "dist" || entry.name === "build" || entry.name === "coverage")
+      if (isUniversallySkippedScanDir(entry.name) || entry.name === "build") {
         continue;
+      }
       results.push(...findTsFiles(fullPath, filter));
     } else if ((entry.name.endsWith(".ts") || entry.name.endsWith(".tsx") || entry.name.endsWith(".js") || entry.name.endsWith(".jsx")) && !entry.name.includes(".gen.")) {
       if (filter && !filter(fullPath)) continue;
@@ -1032,7 +1036,7 @@ function isRoutableSourceFile(name) {
   return (name.endsWith(".ts") || name.endsWith(".tsx") || name.endsWith(".js") || name.endsWith(".jsx")) && !name.includes(".gen.") && !name.includes(".test.") && !name.includes(".spec.");
 }
 function isExcludedScanDir(name) {
-  return name === "node_modules" || name === "dist" || name === "coverage" || name === "__tests__" || name === "__mocks__" || name.startsWith(".");
+  return isUniversallySkippedScanDir(name) || name === "__tests__" || name === "__mocks__";
 }
 function findCallSiteFilesRecursive(dir, pattern, patternG, stopAtMatchDir, filter, results) {
   let entries;
@@ -1443,6 +1447,7 @@ var init_router_processing = __esm({
   "src/build/route-types/router-processing.ts"() {
     "use strict";
     init_codegen();
+    init_scan_filter();
     init_source_scan();
     init_include_resolution();
     init_per_module_writer();

package/dist/testing/vitest.js

@@ -243,6 +243,22 @@ function resolveFromRouter(spec) {
   }
 }
 var rsdServerEdgePath = resolveFromRouter(RSD_SERVER_EDGE_SPEC);
+var CLIENT_URLS_SOURCE_QUERY = "rango-client-urls-source";
+var CLIENT_ENTRY_RSC_PATH = here("src/client.rsc.tsx").replaceAll(
+  "\\",
+  "/"
+);
+var CLIENT_URLS_INSTALLER_PATH = here(
+  "src/testing/internal/client-urls-projection.ts"
+).replaceAll("\\", "/");
+function clientUrlsProjectionInstall(id) {
+  const source = `${id}${id.includes("?") ? "&" : "?"}${CLIENT_URLS_SOURCE_QUERY}`;
+  return `
+import * as $$RangoClientUrlsSource from ${JSON.stringify(source)};
+import { installClientUrlsProjection as $$rangoInstallClientUrlsProjection } from ${JSON.stringify(CLIENT_URLS_INSTALLER_PATH)};
+$$rangoInstallClientUrlsProjection(${JSON.stringify(`${id}#default`)}, $$RangoClientUrlsSource);
+`;
+}
 function rangoTestAliases(opts = {}) {
   const aliases = [
     // Real impls (index.rsc.ts) for the bare specifier ONLY — exact regex so
@@ -290,8 +306,19 @@ function rangoTestConfig(opts = {}) {
 function rangoUseClientTransform() {
   return {
     name: "rango:testing-use-client",
+    resolveId: {
+      // Before Vite's resolver, which resolves the bare specifier first.
+      order: "pre",
+      handler(source, importer) {
+        if (source === "@rangojs/router/client" && importer?.includes(CLIENT_URLS_SOURCE_QUERY)) {
+          return CLIENT_ENTRY_RSC_PATH;
+        }
+        return void 0;
+      }
+    },
     async transform(code, id) {
       if (id.includes("/node_modules/")) return void 0;
+      if (id.includes(CLIENT_URLS_SOURCE_QUERY)) return void 0;
       if (!code.includes("use client")) return void 0;
       const { parseAstAsync } = await import("vite");
       const { hasDirective, transformDirectiveProxyExport } = await import("@vitejs/plugin-rsc/transforms");
@@ -308,12 +335,15 @@ function rangoUseClientTransform() {
         runtime: (name) => `$$RangoRSD.registerClientReference(() => { throw new Error("client reference " + ${JSON.stringify(name)} + " is not callable on the server"); }, ${JSON.stringify(id)}, ${JSON.stringify(name)})`
       });
       if (!result) return void 0;
-      const { output } = result;
+      const { output, exportNames } = result;
       const rsdHref = rsdServerEdgePath ? pathToFileURL(rsdServerEdgePath).href : RSD_SERVER_EDGE_SPEC;
       output.prepend(
         `import * as $$RangoRSD from ${JSON.stringify(rsdHref)};
 `
       );
+      if (code.includes("clientUrls(") && exportNames.includes("default")) {
+        output.append(clientUrlsProjectionInstall(id));
+      }
       return {
         code: output.toString(),
         map: output.generateMap({ hires: true })

package/dist/types/browser/defer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * One hole of a `prefetch: false` adoption (browser/partial-update.ts
+ * armHoles): the promise every reader of the hole waits on, and what the
+ * router knows of it. The router sets `status` and `value` here; it never
+ * writes React's thenable fields on `promise`.
+ *
+ * Resolve-only: a hole is filled or released (releaseHoles), never rejected.
+ * A failure arrives as a fulfilled value (a loader's error envelope, an
+ * error segment's node).
+ */
+export declare class Defer<T> {
+    status: "pending" | "fulfilled";
+    value: T | undefined;
+    /** A reader has handed React `promise` (readDefer). */
+    read?: boolean;
+    /**
+     * Resolved with a value the router holds (a node), the hole is
+     * "fulfilled" at once. Resolved with a stream (a Flight chunk), its promise
+     * follows the stream, and so does the hole: "fulfilled" with the stream's
+     * value once it arrives, so a reader that mounts after that reads the value
+     * as it would read the chunk Flight marked. A rejected stream leaves the
+     * hole pending; its promise carries the rejection.
+     */
+    resolve: (value: T) => void;
+    readonly promise: Promise<T>;
+}
+/**
+ * The read rule, for a component that reads a hole (Suspender, useLoader).
+ * A hole that has fulfilled and that no reader has handed React is its
+ * value: use() of a promise React has not seen suspends an urgent render
+ * once, and the boundary shows its fallback. Once a reader has handed React
+ * the promise, every read is use() of that promise: React has marked it and
+ * returns its value at once, and a replay of the reader must hand use() the
+ * thenable it read before ("A component was suspended by an uncached
+ * promise"). Either way use() is called once, as at every useLoader read.
+ */
+export declare function readDefer<T>(hole: Defer<T>): T;
+/**
+ * A hole as the loader-streams convention has it: its promise while pending,
+ * its value once fulfilled. Anything else is returned as it is. For an
+ * aggregate, the pending-stream registry, and a node React reads itself (a
+ * segment or slot with no `loading()`): a router component there would be a
+ * fiber the filled page's node does not have, and the next render from the
+ * filled entry would remount the segment. React suspends such a read on the
+ * component above it, which commits nothing until the hole fulfils, so the
+ * value can stand where React read the promise.
+ */
+export declare function asStream(value: unknown): unknown;

package/dist/types/browser/document-revealed.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolves once the document has finished parsing and no Suspense boundary of
+ * it is unrevealed.
+ *
+ * Parsing ends with the stream, but React reveals a streamed boundary in
+ * batches up to 300 ms later (Fizz's $RC marks it `$~` and reveals it from a
+ * timer), so the boundary is still pending at DOMContentLoaded. A transition
+ * then would make React client-render it over its server HTML.
+ *
+ * A reveal rewrites the same comment's data, or React removes the node; a
+ * boundary nested in revealed content joins the document only then, so it
+ * resolves only once a full walk finds none. Polls with setTimeout, not
+ * requestAnimationFrame: a hidden tab never runs rAF, which would hold late
+ * handle pushes and location state until the tab is shown again. A tab hidden
+ * from load still waits: Fizz reveals boundaries from a rAF-gated script.
+ */
+export declare function awaitDocumentRevealed(): Promise<void>;

package/dist/types/browser/event-controller.d.ts

@@ -178,7 +178,13 @@ export interface EventController {
     startNavigation(url: string, options?: NavigateOptionsInternal & {
         skipLoadingState?: boolean;
     }): NavigationHandle;
-    abortNavigation(): void;
+    /**
+     * Abort the pending navigation, and the committed one whose stream is
+     * still open. `pendingOnly` leaves the committed one alone: a page
+     * restored from the back/forward cache is not being left
+     * (navigation-bridge.ts handlePageShow).
+     */
+    abortNavigation(pendingOnly?: boolean): void;
     startAction(actionId: string, args: unknown[], 
     /** Originating history entry key; scopes location-state arbitration. */
     cohort?: string): ActionHandle;

package/dist/types/browser/navigation-transaction.d.ts

@@ -65,6 +65,24 @@ interface BoundCommitOverrides {
     /** No payload follows this commit (CommitOptions.treeless). */
     treeless?: boolean;
 }
+/**
+ * What a commit decided about scroll, in the shape the update that follows
+ * carries it (NavigationUpdate.scroll). A navigation always decides, and "do
+ * not scroll" is a decision (`<Link scroll={false}>`, an intercept): it
+ * replaces a pending one. A commit that is not a navigation decides nothing:
+ * an action refetch into the entry on screen (`storeOnly`) and a cache-only
+ * commit return no `scroll`, and their update leaves a pending decision alone
+ * (react/NavigationProvider.tsx).
+ *
+ * Scar tissue: those two used to answer `scroll: false`. An action refetch
+ * that landed before React committed a navigation then replaced the
+ * navigation's pending scroll with "do not scroll".
+ */
+export interface CommitResult {
+    scroll?: {
+        enabled: boolean | undefined;
+    };
+}
 /**
  * Bound transaction with pre-configured commit options (without segmentIds/segments)
  */
@@ -80,19 +98,15 @@ export interface BoundTransaction {
     readonly transitionGatedOff?: boolean;
     /** Start streaming and get a token to end it when the stream completes */
     startStreaming(): StreamingToken;
-    /** Commit the navigation. Returns the effective scroll option for the caller to handle. */
-    commit(segmentIds: string[], segments: ResolvedSegment[], overrides?: BoundCommitOverrides): {
-        scroll?: boolean;
-    };
+    /** Commit the navigation. Returns its scroll decision, for the update. */
+    commit(segmentIds: string[], segments: ResolvedSegment[], overrides?: BoundCommitOverrides): CommitResult;
 }
 /**
  * Navigation transaction for managing state during navigation
  * Uses the event controller handle for lifecycle management
  */
 interface NavigationTransaction extends Disposable {
-    commit(options: CommitOptions): {
-        scroll?: boolean;
-    };
+    commit(options: CommitOptions): CommitResult;
     with(options: Omit<CommitOptions, "segmentIds" | "segments">): BoundTransaction;
     /** The navigation handle from the event controller */
     handle: NavigationHandle;

package/dist/types/browser/partial-update.d.ts

@@ -2,7 +2,7 @@ import type { NavigationStore, NavigationClient, UpdateSubscriber, ResolvedSegme
 import type { ReactNode } from "react";
 import type { RenderSegmentsOptions } from "../segment-system.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
-import type { NavigationUpdate } from "./types.js";
+import type { NavigationUpdate, RscMetadata } from "./types.js";
 import type { LoaderStore } from "../loader-store.js";
 import { type TransitionWhenActionInput } from "./transition-when.js";
 /**
@@ -30,6 +30,31 @@ export interface PartialUpdateConfig {
     renderSegments: (segments: ResolvedSegment[], options?: RenderSegmentsOptions) => Promise<ReactNode> | ReactNode;
     /** RSC version getter — returns the current version (may change after HMR) */
     getVersion?: () => string | undefined;
+    /**
+     * A fill (`prefetch: false`) lands after its navigation has committed: the
+     * transaction has recorded the entry and handed React the tree, and the
+     * fill hands React no update that would carry what its response holds to
+     * the stores. The bridge that owns navigation supplies the writes, the
+     * ones its own updates make. Without them a redirect is a document
+     * navigation and the rest is dropped.
+     */
+    fill?: {
+        redirect(url: string, state?: Record<string, unknown>): void;
+        /** The location state the server set, to the entry and its readers. */
+        locationState(state: Record<string, unknown>): void;
+        /** What the response's handlers pushed, to the handle store. */
+        handles(metadata: RscMetadata): void;
+        /**
+         * Deliver the navigation state to its readers now. A page built with
+         * holes commits in the task of its click, before the notification of the
+         * click has gone out (event-controller.ts makeDebouncedNotifier), and
+         * React holds that commit where a hole is read with no boundary: without
+         * this useNavigation() reads idle, on the page being left, for the whole
+         * wait. Delivered first, `loading` is on screen when the commit is
+         * handed over, and stays while React holds it, as for a plain click.
+         */
+        flush(): void;
+    };
 }
 /**
  * Options that can override the pre-configured commit settings
@@ -64,12 +89,16 @@ export type UpdateMode = {
     /** Source URL for intercept restore (popstate cache miss) */
     interceptSourceUrl?: string;
     /**
-     * The bridge already presented an optimistic clientUrls() destination
-     * for this navigation: transition-lane commits add
+     * The optimistic clientUrls() destination the bridge presented for
+     * this navigation. Transition-lane commits add
      * OPTIMISTIC_COMMIT_TRANSITION_TYPE so router <ViewTransition>
-     * boundaries do not animate the identical repaint.
+     * boundaries do not animate the identical repaint, and `clear()` runs
+     * once the canonical tree is handed to React: `useOutlet().pending`
+     * ends with that commit, not with a `prefetch: false` fill after it.
      */
-    optimisticPresented?: boolean;
+    presentation?: {
+        clear(): void;
+    };
     /**
      * A router.refresh() (or cross-tab refresh) of the current URL:
      * transition({ when }) sees kind "revalidate", not "replace".

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

@@ -1,8 +1,15 @@
 import { type ReactNode } from "react";
-import type { NavigationStore, NavigationUpdate, NavigationBridge } from "../types.js";
+import type { NavigationStore, NavigationUpdate, NavigationBridge, RscMetadata } from "../types.js";
 import type { EventController } from "../event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../../theme/types.js";
 import { type AppShellRef } from "../app-shell.js";
+/**
+ * Read the handle stream of `metadata` into the event controller and the
+ * entry on screen. The provider's own call for every payload it is handed,
+ * and the one write for a response that hands React nothing (a fill,
+ * browser/partial-update.ts fillHoles).
+ */
+export declare function consumeHandles(metadata: RscMetadata, eventController: EventController, store: NavigationStore): void;
 /**
  * Props for NavigationProvider
  */
@@ -69,8 +76,11 @@ export interface NavigationProviderProps {
      * `settled` resolves once the stream has ended and React has revealed every
      * boundary. Until then location state is `undefined`, as SSR rendered it;
      * then one transition gives the entry's state and changes
-     * HydrationBarrierContext, and the store is released after that commit. A
-     * navigation committed earlier releases the store before its update.
+     * HydrationBarrierContext, and the store is released after that commit
+     * (handle data lands in that release notification). A navigation committed
+     * earlier releases the store before its update, for the whole hold when the
+     * navigation is held: an old-page boundary hydrating meanwhile reads
+     * the destination's values and can mismatch.
      * Absent for a provider mounted on the client.
      */
     hydration?: {

package/dist/types/browser/react/filter-segment-order.d.ts

@@ -1,3 +1,10 @@
+/**
+ * A loader sub-id carries a `D${index}.` marker ("M0L0D1.user"). Non-global,
+ * so `.test` and `.replace` are stateless.
+ */
+export declare const LOADER_SEGMENT_ID: RegExp;
+/** True for a loader sub-id ("M0L0D1.user"), false for a layout/route/slot id. */
+export declare function isLoaderSegmentId(id: string): boolean;
 /**
  * Build the handle-collection segment order from a raw `matched` list.
  *

package/dist/types/browser/response-adapter.d.ts

@@ -6,6 +6,13 @@ type HeaderResult = {
  * Returns { url } if valid, "blocked" if present but invalid origin, null if absent.
  */
 export declare function extractRscHeaderUrl(response: Response, header: string): HeaderResult;
+/**
+ * Run `request` with a signal that `signal` aborts until the request settles,
+ * and only until then. A response that has arrived streams to its end:
+ * aborting a Flight body mid-read rejects every chunk a mounted tree may be
+ * reading. Aborted, the request rejects with `signal.reason`.
+ */
+export declare function abortUntilResponse<T>(signal: AbortSignal | undefined, request: (signal: AbortSignal | undefined) => Promise<T>): Promise<T>;
 /**
  * Empty 200 response that won't choke Flight parsing.
  * Used when a header URL is blocked by origin validation.

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

@@ -277,7 +277,12 @@ export interface HistoryEntryMemory {
 export interface NavigationUpdate {
     root: ReactNode | Promise<ReactNode>;
     metadata: RscMetadata;
-    /** Scroll behavior to apply after React commits this update */
+    /**
+     * The scroll decision of the navigation transaction this update commits,
+     * applied after React commits it. Absent on every update that is not a
+     * navigation's (server action, error, `prefetch: false` fill): such an
+     * update says nothing about scroll, and leaves a pending decision alone.
+     */
     scroll?: {
         /** For back/forward: restore saved position */
         restore?: boolean;
@@ -537,6 +542,12 @@ export interface NavigationStore {
      * probe and write into one historyCache scan for the per-yield streaming path.
      */
     updateCacheHandleDataIfOwned(historyKey: string, handleData: HandleData, ownerInstance: number, stale?: boolean, handlesPending?: boolean): void;
+    /**
+     * The history keys whose entries show the page `historyKey`'s entry shows:
+     * that entry and the copies a shallow navigation made of it, which share its
+     * segments array. `[historyKey]` when it has no entry.
+     */
+    getPageHistoryKeys(historyKey: string): string[];
     markHistoryCacheStale(): void;
     markCacheAsStaleAndBroadcast(): void;
     clearHistoryCache(): void;
@@ -558,13 +569,6 @@ export interface FetchPartialOptions {
     signal?: AbortSignal;
     /** If true, this is a stale cache revalidation request - server should force revalidators */
     staleRevalidation?: boolean;
-    /**
-     * Encoded client-run per-loader revalidation decisions
-     * (clientUrls revalidate() predicates executed in the browser); sent as
-     * X-Rango-Client-Reval and honored only by materialized client-urls loader
-     * stubs. Null/absent = locked server defaults.
-     */
-    clientRevalidation?: string | null;
     interceptSourceUrl?: string;
     /** RSC version for cache invalidation detection */
     version?: string;
@@ -572,6 +576,12 @@ export interface FetchPartialOptions {
     routerId?: string;
     /** If true, this is an HMR refetch - server should invalidate manifest cache */
     hmr?: boolean;
+    /**
+     * The fill request of an adopted prefetch that carried deferred segments
+     * (`prefetch: false`): marked `_rsc_fill`, never answered from or written
+     * to a prefetch cache or the HTTP cache, and it cancels no prefetch.
+     */
+    fill?: boolean;
 }
 /**
  * Result of a partial fetch including stream completion tracking
@@ -644,7 +654,7 @@ export interface NavigationBridgeConfig {
 export type { ResolvedSegment };
 /**
  * Token for tracking an active stream.
- * Call end() when the stream completes.
+ * Call end() when the stream completes. Only the first call counts.
  */
 export interface StreamingToken {
     end(): void;

package/dist/types/browser/validate-redirect-origin.d.ts

@@ -26,3 +26,14 @@ export declare function validateRedirectOrigin(url: string, currentOrigin: strin
  * @returns The normalized URL string on success, or null if blocked.
  */
 export declare function validateExternalRedirect(url: string, currentOrigin: string): string | null;
+/**
+ * The target of a redirect a Flight payload carries (`metadata.redirect`), or
+ * null when the client refuses it. An explicit off-host one
+ * (`redirect(url, { external: true })`) is scheme-validated only:
+ * `external` waives the same-origin check the app opted out of, not scheme
+ * safety. Every other one must stay on this origin.
+ */
+export declare function validatePayloadRedirect(redirect: {
+    url: string;
+    external?: boolean;
+}): string | null;

package/dist/types/build/generate-route-types.d.ts

@@ -1,7 +1,7 @@
 export { extractParamsFromPattern, formatRouteEntry, } from "./route-types/param-extraction.js";
 export { extractRoutesFromSource } from "./route-types/ast-route-extraction.js";
 export { generatePerModuleTypesSource, generateRouteTypesSource, } from "./route-types/codegen.js";
-export { DEFAULT_EXCLUDE_PATTERNS, type ScanFilter, createScanFilter, findTsFiles, } from "./route-types/scan-filter.js";
+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";

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

@@ -1,4 +1,4 @@
-import type { ScanFilter } from "./scan-filter.js";
+import { type ScanFilter } from "./scan-filter.js";
 import { type UnresolvableInclude } from "./include-resolution.js";
 export declare function findNestedRouterConflict(routerFiles: string[]): {
     ancestor: string;

package/dist/types/build/route-types/scan-filter.d.ts

@@ -11,7 +11,21 @@ export declare function createScanFilter(root: string, opts: {
     exclude?: string[];
 }): ScanFilter | undefined;
 /**
- * Recursively find .ts/.tsx files under a directory, skipping node_modules
- * and .gen. files.
+ * Directory names no discovery scan enters: findTsFiles() and the router scans
+ * (findRouterFiles/findHostRouterFiles, router-processing.ts) all build their
+ * skip rule on this, so a file below one is never discovered. Dot-directories
+ * cover a nested git worktree, a tool cache, or a test's working copy of
+ * another app.
+ */
+export declare function isUniversallySkippedScanDir(name: string): boolean;
+/**
+ * Whether a file under `root` sits in a directory every discovery scan skips
+ * (isUniversallySkippedScanDir). The dev route-file watcher uses it to ignore
+ * files discovery would never find. A path outside `root` is false.
+ */
+export declare function isInSkippedScanDir(root: string, absolutePath: string): boolean;
+/**
+ * Recursively find .ts/.tsx files under a directory, skipping the directories
+ * isUniversallySkippedScanDir() names, `build`, and .gen. files.
  */
 export declare function findTsFiles(dir: string, filter?: ScanFilter): string[];

package/dist/types/cache/cf/cf-cache-store.d.ts

@@ -53,6 +53,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private readonly tagPurge?;
     private readonly tagInvalidationTtl?;
     private readonly tagCacheTtl;
+    private readonly kvFallThrough;
     constructor(options: CFCacheStoreOptions<TEnv>);
     /**
      * Warn about a namespace-scoped misconfiguration once per namespace per
@@ -350,7 +351,10 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * dropped and read from the store (SWR recapture scheduling and each mode's
      * invalidation semantics stay with the store read). That read keeps the
      * caller's `tagHints`: cfTagHints may have evicted the key while the memo
-     * still holds it.
+     * still holds it. A shell a tag marker rejects is dropped and read from
+     * the store too, which may hold a capture from after the marker (see
+     * get(), "Tag invalidation"), unless the request's own mask rejected it
+     * (declinesKvFallThrough).
      */
     private readMemoizedShell;
     /**
@@ -577,6 +581,17 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private isL1Invalidated;
+    /**
+     * Whether a rejected L1 copy skips the KV read: always unless the
+     * `kvFallThrough` option is on, and with it on when this request's own
+     * updateTag()/revalidateTag() (its mask, request-tag-mask.ts) rejects an
+     * entry tagged at `taggedAt`. KV holds a newer entry only if something
+     * rendered after this request's invalidation, while the request re-renders
+     * every entry it masked, so the read would add one KV get per masked entry
+     * to that re-render.
+     * @internal
+     */
+    private declinesKvFallThrough;
     /**
      * Synthetic Cache API request for a tag's L1-cached invalidation marker.
      * Unversioned for the same reason as tagMarkerKey; the cache namespace

package/dist/types/cache/cf/cf-cache-types.d.ts

@@ -51,8 +51,11 @@ export interface CFCacheReadDebugEvent {
      * - kv-timeout: the L2/KV read budget fired (read abandoned, NOT a genuine
      *   absence -- distinct from kv-miss so a degradation signal is separable)
      * - tag-invalidated: a live L1/KV entry whose cache tags were invalidated
-     *   after it was written -- treated as a miss so the next render re-populates
-     *   it (the tag-invalidation read path, distinct from a plain miss)
+     *   after it was written -- never served (the tag-invalidation read path,
+     *   distinct from a plain miss). With `kvFallThrough` on, an L1 copy then
+     *   reads L2/KV, so a kv-* event follows unless the request invalidated the
+     *   tag itself; from L2/KV it is a miss and the next render re-populates
+     *   the entry
      * - error: the read threw
      */
     outcome: "l1-fresh" | "l1-stale-revalidate" | "l1-revalidating-guarded" | "match-timeout" | "match-error" | "body-timeout" | "body-error" | "non-200" | "tag-invalidated" | "l1-miss" | "kv-fresh" | "kv-stale" | "kv-stale-suppressed" | "kv-miss" | "kv-timeout" | "error";
@@ -335,6 +338,24 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      * <= 0) to disable and always await KV.
      */
     kvReadTimeoutMs?: number;
+    /**
+     * After `updateTag()`/`revalidateTag()`, a location whose own L1 copy a tag
+     * marker rejects reads KV next, and serves the entry another location (or a
+     * `router.prerender()` warm) wrote after the invalidation, instead of
+     * rendering again. Covers `cache()` records, `"use cache"` results, cached
+     * responses and `ppr` shells. The request that invalidated the tag still
+     * re-renders its own entries without the read.
+     *
+     * Cost: one KV get per rejected copy per location after each invalidation
+     * (150 ms added wait, measured in #1069 locally at 50 ms per KV read on a
+     * document with a shell, a record and one `"use cache"` result, every copy
+     * rejected; not measured on a deployed worker), paid even when KV holds only
+     * the old twin. Worth it where re-rendering costs more than a KV read
+     * (several locations, expensive renders). Needs `kv`; ignored without it.
+     *
+     * Defaults to false: a rejected L1 copy is a miss and the location renders.
+     */
+    kvFallThrough?: boolean;
     /**
      * Per-isolate memos ({@link StoreMemoOptions}), one set per isolate and
      * shared by every CFCacheStore in it. `shellMs` (default 2000) and

package/dist/types/client-urls/client-urls.d.ts

@@ -2,4 +2,4 @@ import type { ClientUrlBuilder, ClientUrlPatterns } from "./types.js";
 import type { ExtractRoutes } from "../urls/type-extraction.js";
 import type { ClientUrlItems } from "./types.js";
 export declare function clientUrls<const TItems extends ClientUrlItems>(builder: ClientUrlBuilder<TItems>): ClientUrlPatterns<ExtractRoutes<TItems>>;
-export type { ClientRevalidateArgs, ClientRevalidateFn, ClientTransitionConfig, ClientUrlBuilder, ClientUrlHelpers, ClientUrlInterceptRecord, ClientUrlItem, ClientUrlItemInput, ClientUrlItems, ClientLayoutFn, ClientPathOptions, ClientUrlLoaderRecord, ClientPathFn, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./types.js";
+export type { ClientTransitionConfig, ClientUrlBuilder, ClientUrlHelpers, ClientUrlInterceptRecord, ClientUrlItem, ClientUrlItemInput, ClientUrlItems, ClientLayoutFn, ClientPathOptions, ClientUrlLoaderRecord, ClientPathFn, ClientUrlPatterns, ClientUrlRouteRecord, ClientUrlUse, } from "./types.js";

package/dist/types/client-urls/hoisted-revalidate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The value the build leaves in place of a clientUrls() `revalidate()`
+ * predicate in the browser and SSR copies of a "use client" module
+ * (vite/plugins/client-urls-revalidate-hoist.ts): the predicate itself moves
+ * to a server module, registered under the same content key
+ * (revalidate-registry.ts). The projection carries the key; the materialized
+ * loader stub calls the registered predicate.
+ */
+export declare const HOISTED_REVALIDATE_KEY = "$$rangoRevalidate";
+export interface HoistedRevalidateRef {
+    readonly $$rangoRevalidate: string;
+}
+export declare function isHoistedRevalidateRef(value: unknown): value is HoistedRevalidateRef;

package/dist/types/client-urls/navigation.d.ts

@@ -46,41 +46,4 @@ export declare function registerClientUrlGroup(definition: ClientUrlPatterns, mo
 export declare function beginClientUrlNavigation(targetUrl: URL, signal: AbortSignal, 
 /** Builds the entry state; called only when the group presents the target. */
 buildState?: () => unknown, decideTransition?: (destination: ClientUrlDestination) => boolean): ClientUrlNavigationPresentation | null;
-/**
- * Run the held clientUrls route's per-loader revalidate() predicates and
- * encode their decisions for the request header. Predicates are CLIENT code
- * (declared in the "use client" definition module); only decisions cross the
- * wire — the synthesized per-loader revalidate() on every materialized stub
- * (server-projection.ts) reads them back by loader $$id.
- *
- * Decisions exist only for the loaders the client currently HOLDS: the local
- * match of currentUrl. They matter when the server would re-evaluate those
- * held loader segments — same-route param/search navs, actions, and stale
- * restores. Cross-route targets render new segments unconditionally, so a
- * decision would be ignored; we still compute against the current route since
- * only its held segments are addressable.
- *
- * Returns null when no group is active, the current location is not a client
- * route, or no predicate produced a decision that differs from the locked
- * default — the server then applies defaults, which is also the behavior for
- * requests that cannot carry decisions (no-JS, PE, prefetch, document loads).
- */
-export declare function collectClientRevalidationDecisions(options: {
-    currentUrl: URL;
-    nextUrl: URL;
-    /**
-     * True only when the decisions ride the action POST itself — the one
-     * request the server evaluates with actionContext (locked default true).
-     * Action-triggered refetch GETs (partial-update terminals) pass false:
-     * the server gives those navigation defaults, and the delta gate below
-     * must diff against the default the SERVER will use, or a force decision
-     * on the refetch would be silently swallowed as "equals default".
-     */
-    actionRequest: boolean;
-    /** Action TRUTH for the predicates' isAction() matcher; may be true on
-     * refetch GETs where actionRequest is false. */
-    isAction: boolean;
-    actionId?: string;
-    stale: boolean;
-}): string | null;
 export declare function clearClientUrlNavigationRegistry(): void;

package/dist/types/client-urls/revalidate-registry.d.ts

@@ -0,0 +1,4 @@
+import type { ShouldRevalidateFn } from "../types.js";
+export declare function registerClientUrlRevalidators(fns: Readonly<Record<string, ShouldRevalidateFn<any, any>>>): void;
+export declare function getClientUrlRevalidator(key: string): ShouldRevalidateFn<any, any> | undefined;
+export declare function clearClientUrlRevalidators(): void;