@rangojs/router 0.19.1 → 0.21.0

package/dist/bin/rango.js

@@ -1599,14 +1599,33 @@ var init_merge_full_manifests = __esm({
   }
 });
 
+// src/router-versions.ts
+var DEFAULT_ROUTER_VERSIONS_KEY;
+var init_router_versions = __esm({
+  "src/router-versions.ts"() {
+    "use strict";
+    DEFAULT_ROUTER_VERSIONS_KEY = "*";
+  }
+});
+
 // src/vite/plugins/virtual-entries.ts
 function getVirtualVersionContent(version) {
-  return `export const VERSION = ${JSON.stringify(version)};`;
-}
-var VIRTUAL_ENTRY_BROWSER, VIRTUAL_IDS;
+  return [
+    `export const VERSION = ${JSON.stringify(version)};`,
+    `export const ROUTER_VERSIONS = undefined;`
+  ].join("\n");
+}
+function getVirtualBuildVersionContent() {
+  return [
+    `export const ROUTER_VERSIONS = ${ROUTER_VERSIONS_PLACEHOLDER};`,
+    `export const VERSION = ROUTER_VERSIONS[${JSON.stringify(DEFAULT_ROUTER_VERSIONS_KEY)}][1];`
+  ].join("\n");
+}
+var VIRTUAL_ENTRY_BROWSER, VIRTUAL_IDS, ROUTER_VERSIONS_PLACEHOLDER;
 var init_virtual_entries = __esm({
   "src/vite/plugins/virtual-entries.ts"() {
     "use strict";
+    init_router_versions();
     VIRTUAL_ENTRY_BROWSER = `
 import {
   createFromReadableStream,
@@ -1660,6 +1679,7 @@ initializeApp().catch(console.error);
       rsc: "virtual:rsc-router/entry.rsc.js",
       version: "@rangojs/router:version"
     };
+    ROUTER_VERSIONS_PLACEHOLDER = "__RANGO_ROUTER_VERSIONS__";
   }
 });
 
@@ -1772,8 +1792,7 @@ function getClientModuleSignature(source) {
   };
 }
 function createVersionPlugin() {
-  const buildVersion = Date.now().toString(16);
-  let currentVersion = buildVersion;
+  let currentVersion = Date.now().toString(16);
   let isDev = false;
   let server = null;
   let resolvedCacheDir;
@@ -1793,13 +1812,6 @@ function createVersionPlugin() {
   return {
     name: "@rangojs/router:version",
     enforce: "pre",
-    // The build-time shell capture phase (producer B, #699) stamps entries
-    // with THIS instance's version — the value folded into the shipped worker
-    // — never the discovery temp server's own version-plugin value (a
-    // different Date.now() stamp that would fail the serve-side gate).
-    api: {
-      getBuildVersion: () => currentVersion
-    },
     configResolved(config) {
       isDev = config.command === "serve";
       resolvedCacheDir = config.cacheDir ? String(config.cacheDir).replace(/\\/g, "/") : void 0;
@@ -1821,7 +1833,7 @@ function createVersionPlugin() {
     },
     load(id) {
       if (id === "\0" + VIRTUAL_IDS.version) {
-        return getVirtualVersionContent(currentVersion);
+        return isDev ? getVirtualVersionContent(currentVersion) : getVirtualBuildVersionContent();
       }
       return null;
     },
@@ -2150,7 +2162,7 @@ if (command === "generate") {
 Modes:
   (default)   Static parser with error on unresolvable includes
   --runtime   Vite-based runtime discovery (100% coverage)
-              Requires vite and @vitejs/plugin-rsc
+              Requires vite
   --static    Static parser, accept partial output with warnings
 
 Options:

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

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import type { NavigationLocation, NavigateOptionsInternal, TrackedActionState, InflightAction, RscMetadata, HandleData, StreamingToken } from "./types.js";
+import { type LocationStateSnapshot } from "./react/location-state-shared.js";
 /**
  * Phase of a navigation operation
  */
@@ -196,6 +197,23 @@ export interface EventController {
      */
     resolvedIds?: string[]): void;
     getHandleState(): HandleState;
+    /**
+     * Keep the current handle state as the one the document's HTML was rendered
+     * with. initBrowserApp calls it before hydrateRoot, once the document's
+     * handle snapshot is applied.
+     */
+    freezeHydrationHandleState(): void;
+    /**
+     * The handle state the document's HTML was rendered with, once the live
+     * state has moved on from it; undefined while the live state is still that
+     * state (nothing changed since the freeze, or nothing was frozen: a tree
+     * that was mounted, an SSR pass). A render React is hydrating reads it
+     * (useHandle), whenever its boundary hydrates: the late handle channel
+     * (rsc-router.tsx) waits for the root to hydrate, not for a `<Suspense>`
+     * boundary that hydrates after it, and by then the live state can hold
+     * values that boundary's HTML does not (issue #1035).
+     */
+    getHydrationHandleState(): HandleState | undefined;
     /**
      * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
      * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.
@@ -206,6 +224,20 @@ export interface EventController {
     setRouteSegmentIds(matched: string[]): void;
     setParams(params: Record<string, string>): void;
     getParams(): Record<string, string>;
+    /**
+     * Record the committed history entry's location state from `entryState`:
+     * the state object the commit pushed, restored or merged into the entry,
+     * so the entry and its readers have one source. Notifies nobody:
+     * NavigationProvider takes the snapshot with the entry's payload
+     * (LocationStateContext). `treeless` marks a commit no payload follows (a
+     * shallow navigation, a commit that keeps every segment, an action's
+     * state): the provider takes it with this commit's state notification, in
+     * the batch of the location.
+     */
+    commitLocationState(entryState: unknown, treeless?: boolean): void;
+    getLocationState(): LocationStateSnapshot;
+    /** True once after a `treeless` commit. */
+    takeTreelessLocationState(): boolean;
     getCurrentNavigation(): NavigationEntry | null;
     getInflightActions(): Map<string, ActionEntry>;
     /** Whether any concurrent actions have occurred (shared across all handles) */

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

@@ -37,8 +37,20 @@ export declare const SHELL_MISS_MARKER: string;
  */
 export declare function stripShellMissMarker(): void;
 /**
- * Merge server-set location state into the current history entry.
- * Replaces the current history state and dispatches notification event
- * so useLocationState hooks re-read from history.state.
+ * Remove the `clearOnReload` slots of the entry a document load starts on:
+ * 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).
+ *
+ * A slot is recognised by its key alone (the `~r` suffix): at start-up the
+ * module that defines it may not be loaded.
  */
-export declare function mergeLocationState(locationState: Record<string, unknown>): void;
+export declare function clearLocationStateOnDocumentLoad(): 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
+ * (EventController.commitLocationState).
+ */
+export declare function mergeLocationState(locationState: Record<string, unknown>): Record<string, unknown>;

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

@@ -36,6 +36,11 @@ interface CommitOptions {
      * partial updater reuses it instead of deciding again.
      */
     transitionGatedOff?: boolean;
+    /**
+     * No payload follows this commit: every segment is kept and the tree on
+     * screen stays (EventController.commitLocationState).
+     */
+    treeless?: boolean;
 }
 /**
  * Options that can override the pre-configured commit settings
@@ -57,6 +62,8 @@ interface BoundCommitOverrides {
     serverState?: Record<string, unknown>;
     /** The committed route's name (payload metadata), remembered per history entry. */
     routeName?: string;
+    /** No payload follows this commit (CommitOptions.treeless). */
+    treeless?: boolean;
 }
 /**
  * Bound transaction with pre-configured commit options (without segmentIds/segments)

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

@@ -7,7 +7,9 @@
  * cache keys responses by (URL, X-Rango-State value).
  *
  * Value format: `{buildVersion}:{invalidationTimestamp}`
- * - Build version changes on deploy, busting all cached prefetches at boot.
+ * - Build version: the router's document version. It changes when a deploy
+ *   changes the router's server code or the client assets, busting all cached
+ *   prefetches at boot; a deploy that changes neither keeps them.
  * - Timestamp rotates on invalidation (server action, invalidateClientCache).
  *
  * Storage is a session cookie named by the server-resolved name passed to

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

@@ -2,6 +2,7 @@ import { type Context } from "react";
 import type { NavigationStore, NavigateOptionsInternal } from "../types.js";
 import type { EventController } from "../event-controller.js";
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
+import type { LocationStateSnapshot } from "./location-state-shared.js";
 /**
  * Navigation context value provided by NavigationProvider
  *
@@ -55,3 +56,13 @@ export interface NavigationStoreContextValue {
  * Use useNavigation hook for reactive state access.
  */
 export declare const NavigationStoreContext: Context<NavigationStoreContextValue | null>;
+/**
+ * The location state of the history entry whose tree is on screen, for
+ * useLocationState. NavigationProvider holds it as React state next to the
+ * payload and sets both in one update, so a render sees an entry's state
+ * exactly when it sees that entry's tree: a transition React holds renders
+ * the destination's value, an urgent render of the content still on screen
+ * (a reader mounting there included) the value of the entry being left
+ * (#1029). Undefined on the server and outside a provider.
+ */
+export declare const LocationStateContext: Context<LocationStateSnapshot>;

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

@@ -9,12 +9,82 @@ export interface LocationStateEntry {
     readonly __rsc_ls_value: unknown;
     readonly __rsc_ls_lazy?: boolean;
 }
+/** Prefix of every typed location-state slot in `history.state`. */
+export declare const LOCATION_STATE_KEY_PREFIX: string;
+export declare function isLocationStateKey(key: string): boolean;
+/**
+ * `clearOnReload` is part of a slot's KEY (`<key>~r`); the value is always
+ * stored raw. Slots outlive deploys, so nothing that reads one may depend on a
+ * stored format: a definition without the option reads the plain key and never
+ * sees such a slot.
+ *
+ * An injected key ends in `#<ExportName>` (expose-id-utils.ts makeStubId; only
+ * identifier exports are keyed) and "~" cannot occur in an identifier, so no
+ * file or export name produces a suffix. withLocationStateKey rejects it.
+ */
+export declare const LOCATION_STATE_KEY_SUFFIX_SEPARATOR: string;
+export declare const CLEAR_ON_RELOAD_KEY_SUFFIX: string;
+/**
+ * @internal The version the document loaded under (rsc-router.tsx
+ * initBrowserApp). Deliberately not getAppVersion(): a dev HMR bump moves that
+ * one inside a running session (bridge.updateVersion), and the state that
+ * session wrote must stay readable until the next document load.
+ */
+export declare function setLocationStateVersion(version: string | undefined): void;
+/**
+ * The state of a `{ state }` snapshot when its location state may be read:
+ * an object recorded under the client's version. Without a snapshot, the
+ * current entry (`window.history` is a `{ state }`), and nothing on the
+ * server.
+ */
+export declare function readableLocationState(location?: {
+    readonly state: unknown;
+} | undefined): Record<string, unknown> | undefined;
+/**
+ * One history entry's location state as useLocationState readers receive it:
+ * its typed slots and plain `state`, or undefined when it holds none.
+ */
+export type LocationStateSnapshot = Readonly<Record<string, unknown>> | undefined;
+/**
+ * The snapshot of `entryState`: the state object a commit pushes, restores or
+ * merges into its history entry. Only state recorded under the client's
+ * version is in it (readableLocationState).
+ *
+ * The snapshot is a React context value, so identity decides who re-renders.
+ * It is `previous` itself when every slot holds the value `previous` holds:
+ * an entry without state after another, a primitive carried over, or the
+ * object a reader got from `previous` passed back by the navigation. Any
+ * other value is new, equal content included: a link clicked twice announces
+ * its state twice (a flash message, a scroll target). A new value is a
+ * structured clone, as history.state holds it, so a reader never shares an
+ * object with the caller of the navigation.
+ */
+export declare function locationStateSnapshot(entryState: unknown, previous?: LocationStateSnapshot): LocationStateSnapshot;
+/**
+ * Record the client's version on a state object that carries location state
+ * and no record yet. A client without a version (a renderRoute tree) writes
+ * none.
+ */
+export declare function stampLocationState(state: Record<string, unknown>): void;
+/**
+ * `entryState` plus `additions`, recorded under the client's version. The
+ * record is per entry, so location state another version left there is dropped
+ * first, with its record: under the new one it would be readable again. Router
+ * bookkeeping (idx, scroll key, intercept) is kept.
+ */
+export declare function addLocationState(entryState: unknown, additions?: Record<string, unknown>): Record<string, unknown>;
 /**
  * Options for createLocationState
  */
 export interface LocationStateOptions {
     /** When true, the state is cleared from history after first read (flash message pattern) */
     flash?: boolean;
+    /**
+     * When true, the state does not survive a document load of its entry (a
+     * refresh, a back/forward that loads the document): the server rendered
+     * without it. Not together with `flash`.
+     */
+    clearOnReload?: boolean;
 }
 type LocationStateUnsafeFn = (...args: never[]) => unknown;
 type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
@@ -116,13 +186,16 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
     (...args: TArgs): LocationStateEntry;
     /**
      * Injected by Vite plugin - do not set manually. Unit tests without the
-     * plugin use withLocationStateKey() from @rangojs/router/testing.
+     * plugin use withLocationStateKey() from @rangojs/router/testing. Reads back
+     * as the slot's key in `history.state`: the injected key plus the
+     * `clearOnReload` suffix.
      */
     __rsc_ls_key: string;
     /** Whether this state auto-clears after first read */
     readonly __rsc_ls_flash: boolean;
     /**
-     * Read the current value from history.state.
+     * Read the current value from history.state. State the entry holds from
+     * another version of the app (an older build) reads as undefined.
      *
      * Returns undefined during SSR (no `window`). To stay hydration-safe, do
      * NOT call read() inline during the initial render — the server returns
@@ -145,13 +218,14 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
     /**
      * Statically write the value into the current history entry under this
      * definition's key, preserving any other keys already on history.state
-     * (e.g. router bookkeeping, other LocationState slots).
+     * (e.g. router bookkeeping, other LocationState slots). Location state
+     * another version of the app left on the entry is dropped.
      *
-     * This is the non-reactive counterpart to read(): it does not dispatch any
-     * event, so components reading via useLocationState() will NOT re-render
-     * until the next navigation/popstate. Use it when you only need the value
-     * to be there on the next read() or on the next mount (including after
-     * back/forward and hard refresh of the same entry).
+     * This is the non-reactive counterpart to read(): it changes the history
+     * entry and nothing a useLocationState() reader shows, whether the reader
+     * is mounted now or mounts later. read() returns the value at once; a
+     * reader gets it when the entry is next restored: back/forward to it, or
+     * (unless the definition sets `clearOnReload`) a hard refresh of it.
      *
      * Client-only: throws when called on the server (no history available).
      */
@@ -161,8 +235,8 @@ export interface LocationStateDefinition<TArgs extends unknown[], TState> {
      * leaving any other keys on history.state untouched. Idempotent: removing
      * a slot that isn't present is a no-op.
      *
-     * Same non-reactive semantics as write(): no event is dispatched, so
-     * useLocationState() readers will NOT re-render until the next navigation.
+     * Same non-reactive semantics as write(): useLocationState() readers keep
+     * the value until the entry is next restored.
      *
      * Client-only: throws when called on the server (no history available).
      */

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

@@ -1,10 +1,15 @@
 import { type LocationStateDefinition } from "./location-state-shared.js";
 export { createLocationState, isLocationStateEntry, resolveLocationStateEntries, type LocationStateEntry, type LocationStateDefinition, type LocationStateOptions, } from "./location-state-shared.js";
 /**
- * Hook to read location state from history.state
+ * Hook to read the location state of the history entry on screen
+ *
+ * A reader sees an entry's state together with that entry's tree: on a
+ * navigation the value changes in the React commit that brings the
+ * destination, so content a pending navigation keeps on screen keeps the
+ * state of the entry being left, for a reader that mounts there too (#1029).
  *
  * Behavior depends on the definition:
- * - Normal state: persists across navigations, reactive to popstate
+ * - Normal state: persists across navigations and back/forward
  * - Flash state (created with { flash: true }): read once, cleared after paint
  *
  * Overloaded:

package/dist/types/browser/react/subscribe-to-nothing.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `subscribe` for a useSyncExternalStore whose snapshot nothing notifies: the
+ * hook is there for its server snapshot (useLocationState, useHandle), or the
+ * value only changes with a render (Link's non-adaptive prefetch strategy).
+ * One function, so its identity is stable across renders and hooks.
+ */
+export declare const subscribeToNothing: () => () => void;

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

@@ -286,11 +286,10 @@ export declare class CacheScope {
      * @param pathname - URL pathname for cache key generation
      * @param params - Route params for cache key generation
      * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
-     * @param ownedPushes - How restoreHandles delivers the record's
-     *   loader-owned values (withCacheLookup: the handler context's
-     *   _claimLoaderPushes, and on a document HIT tail the owners it restores)
+     * @param ownedPushes - What the record is to each loader's handle pushes
+     *   (withCacheLookup: loader-cache.ts loaderPins), called on a hit
      */
-    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean, ownedPushes?: OwnedPushDelivery): Promise<{
+    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean, ownedPushes?: () => OwnedPushDelivery): Promise<{
         segments: ResolvedSegment[];
         shouldRevalidate: boolean;
     } | null>;
@@ -312,7 +311,7 @@ export declare class CacheScope {
      * A corrupt entry that was evicted reads as `miss`: the store was consulted
      * and holds nothing servable, which is the post-eviction truth.
      */
-    lookupRouteDetailed(pathname: string, params: Record<string, string>, isIntercept?: boolean, ownedPushes?: OwnedPushDelivery): Promise<CacheRouteLookupOutcome>;
+    lookupRouteDetailed(pathname: string, params: Record<string, string>, isIntercept?: boolean, ownedPushes?: () => OwnedPushDelivery): Promise<CacheRouteLookupOutcome>;
     /**
      * Record this scope's segment-DSL cache({ tags }) into the request tag union
      * synchronously, under the same gate cacheRoute() uses for a write.

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

@@ -21,7 +21,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private readonly namespace?;
     private readonly explicitBaseUrl?;
     private readonly waitUntil?;
-    private readonly version?;
+    /** The `version` option: used for every versioned family when set. */
+    private readonly explicitVersion?;
     private readonly edgeLookupTimeoutMs;
     private readonly edgeReadTimeoutMs;
     private readonly kvReadTimeoutMs;
@@ -327,9 +328,12 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * on the same context) read their markers as before.
      */
     private recordShellHit;
-    /** The isolate marker memo's key for a tag: markers are per namespace and version. */
+    /**
+     * The isolate marker memo's key for a tag: markers are per namespace, and
+     * shared by every version (tagMarkerKey).
+     */
     private markerMemoKey;
-    /** The memo key: one per namespace, build version, base URL, and shell key. */
+    /** The memo key: one per namespace, document version, base URL, and shell key. */
     private shellMemoKey;
     /**
      * Serve a memoized shell (shell-memo.ts). The tag-marker check is the only
@@ -400,9 +404,16 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private kvReadShellDocument;
     /** Promote a valid KV shell into the per-colo Cache API tier. */
     private promoteShellToL1;
+    private shellRequest;
+    private shellKVKey;
     /**
      * Convert string key to Request object for CF Cache API.
-     * Includes version in URL if specified (for cache invalidation on code changes).
+     *
+     * `family` picks the version in the URL path, so a version change misses:
+     * `"data"` for segment entries and `fn:` items (cached RSC data, valid while
+     * the router's server code is unchanged), `"document"` for `doc:` responses
+     * and `shell2:` shells (their bytes carry asset URLs and the handler
+     * version), `null` for tag markers, which apply to every version.
      * @internal
      */
     private keyToRequest;
@@ -477,7 +488,13 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private kvGetOrEvict;
-    /** KV key for a tag's invalidation marker. */
+    /**
+     * KV key for a tag's invalidation marker. Unversioned: a content-hash
+     * version can come back (deploy A, deploy B, roll back to A), and a marker
+     * written while B was live has to be visible to A's entries. The staleness
+     * check compares the marker time with the entry's taggedAt and nothing else
+     * (isGloballyInvalidated), so one marker per tag serves every version.
+     */
     private tagMarkerKey;
     /**
      * Header entries carrying an entry's tags (JSON-encoded, comma-safe) and the
@@ -554,7 +571,11 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private isL1Invalidated;
-    /** Synthetic Cache API request for a tag's L1-cached invalidation marker. */
+    /**
+     * Synthetic Cache API request for a tag's L1-cached invalidation marker.
+     * Unversioned for the same reason as tagMarkerKey; the cache namespace
+     * (getCache) still scopes it.
+     */
     private tagMarkerRequest;
     /**
      * Read a tag's latest invalidation timestamp (or null if never invalidated)

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

@@ -276,11 +276,19 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      */
     tagCacheTtl?: number;
     /**
-     * Cache version string override. When this changes, all cached entries are
-     * effectively invalidated (new keys won't match old entries).
+     * Cache version string override. When set, this exact value prefixes every
+     * versioned key the store writes (`v/{version}/...`), for cached data and
+     * stored HTML alike; changing it makes every earlier entry unreachable.
      *
-     * Defaults to the auto-generated VERSION from the `@rangojs/router:version` virtual module.
-     * Only set this if you need a custom versioning strategy.
+     * Leave it unset for the default: the store keys with the versions of the
+     * router serving the request. Segment entries and `"use cache"` items use
+     * the router's data version; document responses and PPR shells use its
+     * document version (see `createRouter({ version })`). Those are computed
+     * from the router's built code, so a deploy that does not change the router
+     * keeps its entries.
+     *
+     * Tag invalidation markers are never versioned: an invalidation applies to
+     * the entries of every version, including one that comes back in a rollback.
      */
     version?: string;
     /**

package/dist/types/cache/handle-snapshot.d.ts

@@ -6,7 +6,7 @@
  * during segment resolution and stored alongside cached segments.
  */
 import type { ResolvedSegment } from "../types.js";
-import type { HandleStore } from "../server/handle-store.js";
+import type { HandleStore, RecordAuthority } from "../server/handle-store.js";
 import type { HandleOwners, SegmentHandleData } from "./types.js";
 type HandleRecord = Record<string, SegmentHandleData>;
 /**
@@ -44,52 +44,25 @@ export declare function decodeHandleValue<T>(encoded: string): Promise<T | null>
 export declare function captureHandles(segments: ResolvedSegment[], handleStore: HandleStore): Record<string, SegmentHandleData>;
 /** The owners of captureHandles' values; undefined when none is owned. */
 export declare function captureHandleOwners(segments: ResolvedSegment[], handleStore: HandleStore): HandleOwners | undefined;
-/** How restoreHandles delivers a record's loader-owned values. */
-export interface OwnedPushDelivery {
-    /**
-     * Asked once per owner delivered through pushReplayed
-     * (setupLoaderAccess _claimLoaderPushes); an owner it refuses is skipped.
-     */
-    claim?: (loaderId: string) => boolean;
-    /**
-     * A PPR shell's record (capture, document HIT tail, navigation replay): the
-     * loaders the route runs on the live lane (liveLaneLoaderIds), marked on
-     * the store (HandleStore.markLiveLane). A hole's values are replayed
-     * unclaimed, so its own cache() HIT redelivers its entry's pushes in their
-     * place (HandleStore.redeliverReplays), and its run ending without a push
-     * drops them (HandleStore.settleLoaderRun).
-     */
-    liveLane?: ReadonlySet<string>;
-    /**
-     * A document HIT tail: every owner outside `liveLane` goes through
-     * pushRestored and stands, unclaimed.
-     */
-    restore?: boolean;
-}
+/**
+ * What the record being restored is to each loader's handle pushes on this
+ * request (HandleStore RecordAuthority). Built by loaderPins (loader-cache.ts)
+ * over the pins resolveLoaderData serves a loader's value from, so a value
+ * and its record copies get one answer.
+ */
+export type OwnedPushDelivery = (loaderId: string) => RecordAuthority;
 /**
  * Restore handle data from a cached snapshot into the handle store.
  * Used when serving cached segments to replay their handle data: a route
  * cache() record owns its segments' arrays, so it REPLACES them.
  *
  * A segment with `owners` is replaced with empty arrays and re-pushed in
- * recorded order, an owned value through pushReplayed: if the owning loader
- * runs (a client navigation replaying a ppr route's cache() record runs its
- * `ssr: false` loaders), its live pushes replace the recorded ones in place
- * instead of appending a second copy. `owned.claim` is asked once per
- * owner, so the loader's own cache() HIT does not replay its pushes a second
- * time (loader-cache.ts replayLoaderHandles). A record without owners
- * restores as a plain replay.
- *
- * `owned.restore`: a document HIT tail restoring the shell's doc record
- * (withCacheLookup). A bake-lane owner's values are the prelude's, so they go
- * through pushRestored and stand: a run of that loader on the HIT (a
- * promise-carrying `ssr: false` loader, one whose record asks for a run)
- * reads the store, and its settled pushes are dropped, not swapped in.
- * Nothing is claimed, so the loader's own cache() HIT still replays the
- * pushes the record could not keep (the thenable ones pushRestored lets
- * through). A loader the route also runs on the live lane is a hole: its
- * values keep pushReplayed, unclaimed, and its live run replaces them
- * (#936), even inside a restored loader's body (`owned.liveLane`).
+ * recorded order. A loader-owned value stands (pushRestored) where `owned`
+ * says the record supplies that loader's value too ("pin", "copies"), and is
+ * a placeholder (pushPlaceholder) everywhere else: without `owned`, every
+ * owner. Neither claims its loader, so the loader's own cache() HIT still
+ * delivers (the thenable pushes a restored copy lets through, or its entry's
+ * pushes in a placeholder's place).
  */
 export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, owned?: OwnedPushDelivery): void;
 /**
@@ -99,14 +72,27 @@ export declare function restoreHandles(handles: Record<string, SegmentHandleData
  * restoreHandles would wipe those. `segmentId` redirects every value to one
  * segment (the caller's).
  *
- * Owner-keyed groups (useCacheRecordKey, `${seq}:${loaderId}`) are a loader's
- * pushes, which reach the page once per request: `claim` (setupLoaderAccess
- * _claimLoaderPushes) skips a loader that already ran or was replayed in this
- * request, and a claimed loader that runs later replaces its replayed values
- * (HandleStore.pushReplayed). `${seq}:` groups are the function's own pushes.
- * A key without ":" is a segment id (records written before owner keys) and
- * replays unchanged. A loader's own cache() replays through loader-cache.ts
- * replayLoaderHandles.
+ * The replay of every cached unit that records by owner: a "use cache"
+ * function (useCacheRecordKey) and a loader's own cache() (loader-cache.ts
+ * recordOwnerKey, with `unitLoader` the cached loader).
+ *
+ * A `${seq}:${loaderId}` group is that loader's pushes, which reach the page
+ * once per request: `claim` (setupLoaderAccess _claimLoaderPushes) is asked
+ * once per loader and skips one that already ran or was replayed in this
+ * request; a claimed loader that runs later replaces its replayed values
+ * (HandleStore.pushReplayed). A group without an owner (`${seq}:`, or a key
+ * without ":" from a record written before owner keys, which is a segment
+ * id) is the unit's own: `unitLoader`'s, or no loader's for a function,
+ * whose pushes are plain.
+ *
+ * The claimed loaders' placeholders give way to this delivery
+ * (HandleStore.replacePlaceholders), `unitLoader`'s even when the entry
+ * recorded no push for it: the entry stands for that loader's run.
+ *
+ * No `claim` means the caller's pushes are diverted off the page (a stale
+ * refresh: cache-runtime.ts refreshView, setupLoaderAccess
+ * _runLoaderIsolated): every group is delivered, into the diverting capture,
+ * and the page's placeholders stay, or the page would lose the push.
  */
-export declare function appendHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, segmentId?: string, claim?: (loaderId: string) => boolean): void;
+export declare function appendHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, segmentId: string | undefined, claim: ((loaderId: string) => boolean) | undefined, unitLoader?: string): void;
 export {};

package/dist/types/cache/index.d.ts

@@ -8,3 +8,5 @@ export { TRACKING_SEARCH_PARAMS, type CacheSearchParams, } from "./search-params
 export { CacheScope, createCacheScope } from "./cache-scope.js";
 export { createDocumentCacheMiddleware, type DocumentCacheOptions, } from "./document-cache.js";
 export type { CacheErrorCategory } from "./cache-error.js";
+export { getCacheVersions } from "../server/build-version-table.js";
+export type { RouterVersions } from "../router-versions.js";