@rangojs/router 0.21.0 → 0.22.1

package/dist/bin/rango.js

@@ -1571,6 +1571,11 @@ function mergeFullManifests(manifests) {
         manifest.passthroughRoutes,
         overwrittenRoutes
       ),
+      onDemandRoutes: mergeRouteList(
+        merged.onDemandRoutes,
+        manifest.onDemandRoutes,
+        overwrittenRoutes
+      ),
       responseTypeRoutes: mergeRouteRecord(
         merged.responseTypeRoutes,
         manifest.responseTypeRoutes,
@@ -1653,6 +1658,12 @@ async function initializeApp() {
   // is the default; createRouter({ strictMode: false }) ships the opt-out in the
   // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
   const { strictMode, initialPayload } = await initBrowserApp({ rscStream, deps });
+  // Set only on a document a no-JS useActionState POST rendered: React needs
+  // the server's form state to hydrate the hook without resetting it. A state
+  // Flight could not carry rejects: hydrate without it, as before.
+  const formState = await Promise.resolve(initialPayload.formState).catch(
+    () => undefined
+  );
 
   if (import.meta.hot) {
     const { startDevDiscoveryHandshake } = await import(
@@ -1667,7 +1678,8 @@ async function initializeApp() {
   const app = createElement(Rango);
   hydrateRoot(
     document,
-    strictMode === false ? app : createElement(StrictMode, null, app)
+    strictMode === false ? app : createElement(StrictMode, null, app),
+    formState ? { formState } : undefined
   );
 }
 

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

@@ -102,6 +102,15 @@ export interface HandleState {
     segmentOrder: string[];
     routeSegmentIds: string[];
 }
+/**
+ * What the document's HTML was rendered with, kept for the hydration window
+ * (EventController.lockHydration).
+ */
+export interface HydrationSnapshot {
+    state: DerivedNavigationState;
+    params: Record<string, string>;
+    handles: HandleState;
+}
 /**
  * Result from starting a navigation
  * Implements Disposable for use with `using` keyword
@@ -198,22 +207,30 @@ 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.
+     * Open the hydration window. Until releaseHydrationLock(), getHandleState()
+     * returns the state the document's HTML was rendered with, and handle writes
+     * (setHandleData, setRouteSegmentIds) wait in order. initBrowserApp opens it
+     * before hydrateRoot, once the document's handle snapshot is applied: a hook
+     * reading the handle state when its boundary hydrates, however late, reads
+     * what SSR rendered (issue #1035).
+     */
+    lockHydration(): void;
+    /**
+     * While the hydration window is open, the state the document's HTML was
+     * rendered with; undefined once it closes. A router hook's first render
+     * reads it: a component hydrating in a boundary that streamed in late
+     * renders what SSR rendered, even after a navigation or an action started.
+     * The hook's effect then catches up with the live state, and its
+     * subscription stays live, so pending UI is not held back.
      */
-    freezeHydrationHandleState(): void;
+    getHydrationSnapshot(): HydrationSnapshot | undefined;
     /**
-     * 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).
+     * Close the hydration window: apply the writes that waited, in order, and
+     * notify handle subscribers. NavigationProvider calls it after the commit
+     * that made React hydrate every boundary still dehydrated (its barrier).
+     * Idempotent.
      */
-    getHydrationHandleState(): HandleState | undefined;
+    releaseHydrationLock(): void;
     /**
      * Update ONLY `routeSegmentIds` (what `useSegments` reads) from `matched`,
      * leaving `data` and `segmentOrder` (what `useHandle` collects over) untouched.

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

@@ -1,4 +1,5 @@
 import type { NavigationStore, ResolvedSegment, HandleData } from "./types.js";
+import type { EventController } from "./event-controller.js";
 /**
  * Clone the handleData CONTAINERS (the handle-name map and each segment map) so
  * a cache entry is decoupled from the live map that eventController mutates — it
@@ -11,6 +12,14 @@ import type { NavigationStore, ResolvedSegment, HandleData } from "./types.js";
  * non-serializable bucket contents (React elements, functions, etc.).
  */
 export declare function cloneHandleData(handleData: HandleData): HandleData;
+/**
+ * Handle data to write into the history cache for the page on screen. During
+ * the hydration window getHandleState() is the document snapshot while late
+ * pushes sit queued in the controller (they are already in the cache entry,
+ * written by rsc-router), so writing the snapshot back would drop them; the
+ * entry's own data is the live view then.
+ */
+export declare function liveHandleDataForCache(eventController: Pick<EventController, "getHandleState" | "getHydrationSnapshot">, store: Pick<NavigationStore, "getCachedSegments">, historyKey: string): HandleData;
 /**
  * Options for generating a history key
  */

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

@@ -3,6 +3,7 @@ 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 { LoaderStore } from "../loader-store.js";
 import { type TransitionWhenActionInput } from "./transition-when.js";
 /**
  * Hold/animate decision for a commit: a non-intercept segment carries a
@@ -18,7 +19,7 @@ export declare function shouldStartViewTransition(segments: readonly ResolvedSeg
  * directly: nothing is held there, a reader of a pending stream suspends to
  * its fallback. Also used by renderRoute's navigate() (testing/render-route.tsx).
  */
-export declare function commitInTransition(onUpdate: UpdateSubscriber, segments: readonly ResolvedSegment[], update: NavigationUpdate, transitionTypes: readonly string[]): void;
+export declare function commitInTransition(loaders: LoaderStore, onUpdate: UpdateSubscriber, segments: readonly ResolvedSegment[], update: NavigationUpdate, transitionTypes: readonly string[]): void;
 /**
  * Configuration for creating a partial updater
  */

package/dist/types/browser/prefetch/default-strategy.d.ts

@@ -2,30 +2,26 @@
  * Router-wide default prefetch strategy (client seat).
  *
  * The server resolves `createRouter({ defaultPrefetch })` once at router init
- * (router/prefetch-default.ts) and ships it in initial payload metadata; the
- * browser entry applies it here before hydration — same lifecycle as
- * `initPrefetchCache` / `setPrefetchConcurrency`. Every `<Link>` without an
- * explicit `prefetch` prop and every eligible intercepted plain anchor that has
- * not opted out with `data-prefetch="false"` or `data-prefetch="none"` uses it.
- * Containers use the same `false`/`none` vocabulary via
- * `data-prefetch-scope`.
- *
- * The module initial value must equal the server resolver's environment default:
- * `"none"` in development and `"viewport"` in production. During SSR this
- * module is never initialized from metadata, so keeping both seats aligned also
- * gives metadata-less payloads the documented behavior.
+ * (router/prefetch-default.ts) and ships it in initial payload metadata. The
+ * router store carries it to its readers: `<Link>` reads
+ * `NavigationStoreContext.defaultPrefetch`, and delegated plain anchors get it
+ * from the navigation bridge. Every `<Link>` without an explicit `prefetch`
+ * prop and every eligible intercepted plain anchor that has not opted out with
+ * `data-prefetch="false"` or `data-prefetch="none"` uses it. Containers use the
+ * same `false`/`none` vocabulary via `data-prefetch-scope`.
  */
 import type { PrefetchStrategy } from "../../router/prefetch-default.js";
-/** Reset module state between tests that replace browser media globals. */
-export declare function resetAdaptiveStrategyForTesting(): void;
 /**
- * Apply the server-resolved default strategy. Called once at browser app init
- * from payload metadata; also used by tests to reset state.
+ * The default for a payload without `defaultPrefetch`: the server resolver's
+ * environment default (`"none"` in development, `"viewport"` in production),
+ * mirrored without pulling router-layer code into the client bundle. NODE_ENV
+ * is folded by the app build.
+ */
+export declare const ENVIRONMENT_DEFAULT_PREFETCH: PrefetchStrategy;
+/**
+ * Resolve adaptive to the strategy for the current input capability. Called
+ * when a prefetch is armed or triggered, never during render.
  */
-export declare function setDefaultPrefetchStrategy(strategy: PrefetchStrategy): void;
-/** Current default strategy for Links and delegated plain anchors. */
-export declare function getDefaultPrefetchStrategy(): PrefetchStrategy;
-/** Resolve adaptive to the strategy for the current input capability. */
 export declare function resolveAdaptiveStrategy(strategy: PrefetchStrategy): PrefetchStrategy;
 /** Subscribe to changes in the input capability used by adaptive prefetch. */
 export declare function subscribeToAdaptiveStrategyChange(listener: () => void): () => void;

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

@@ -63,6 +63,19 @@ export interface NavigationProviderProps {
      * it to seed a nonce so components calling useNonce() can be exercised.
      */
     nonce?: string;
+    /**
+     * The document this provider hydrates (initBrowserApp; renderRoute with
+     * `hydrate: true`), whose store EventController.lockHydration locked.
+     * `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.
+     * Absent for a provider mounted on the client.
+     */
+    hydration?: {
+        settled: Promise<void>;
+    };
 }
 /**
  * Navigation provider component
@@ -85,4 +98,4 @@ export interface NavigationProviderProps {
  * />
  * ```
  */
-export declare function NavigationProvider({ store, eventController, initialPayload, bridge, themeConfig, initialTheme, warmupEnabled, version, basename, appShellRef, nonce, }: NavigationProviderProps): ReactNode;
+export declare function NavigationProvider({ store, eventController, initialPayload, bridge, themeConfig, initialTheme, warmupEnabled, version, basename, appShellRef, nonce, hydration, }: NavigationProviderProps): ReactNode;

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

@@ -48,6 +48,12 @@ export interface NavigationStoreContextValue {
     basename: string | undefined;
     /** Router default from this instance's initial payload. */
     defaultPrefetch?: PrefetchStrategy;
+    /**
+     * The document's origin, fixed for its lifetime. Link compares absolute
+     * hrefs against it (data-external) and useLinkStatus resolves link targets
+     * with it.
+     */
+    origin: string | undefined;
 }
 /**
  * React context for navigation store
@@ -66,3 +72,11 @@ export declare const NavigationStoreContext: Context<NavigationStoreContextValue
  * (#1029). Undefined on the server and outside a provider.
  */
 export declare const LocationStateContext: Context<LocationStateSnapshot>;
+/**
+ * Read by no component. NavigationProvider changes its value in a transition so
+ * that React hydrates every boundary still dehydrated beneath it before that
+ * commit: React hydrates a dehydrated boundary first when a provider above it
+ * changes, and nothing re-renders for a value nobody reads. See
+ * NavigationProviderProps.hydration.
+ */
+export declare const HydrationBarrierContext: Context<number>;

package/dist/types/browser/rsc-router.d.ts

@@ -95,6 +95,12 @@ export interface BrowserAppContext {
      * prefetch TTL are document-lifetime too (see AppShell).
      */
     appShellRef?: import("./app-shell.js").AppShellRef;
+    /**
+     * Resolves when the document's stream has ended and every Suspense boundary
+     * in it has been revealed. NavigationProvider closes the hydration window
+     * then (NavigationProviderProps.hydration).
+     */
+    documentRevealed: Promise<void>;
 }
 /**
  * Initialize the browser app. Must be called before rendering Rango.
@@ -131,13 +137,18 @@ export interface RangoProps {
  * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
  *
  * async function main() {
- *   await initBrowserApp({ rscStream, deps: rscBrowser });
+ *   const { initialPayload } = await initBrowserApp({ rscStream, deps: rscBrowser });
+ *   // Rejects when the action's state is not Flight-serializable.
+ *   const formState = await Promise.resolve(initialPayload.formState).catch(
+ *     () => undefined,
+ *   );
  *
  *   hydrateRoot(
  *     document,
  *     <React.StrictMode>
  *       <Rango />
- *     </React.StrictMode>
+ *     </React.StrictMode>,
+ *     formState ? { formState } : undefined
  *   );
  * }
  * main();

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

@@ -1,4 +1,5 @@
 import type { ReactNode, ComponentType } from "react";
+import type { ReactFormState } from "react-dom/client";
 import type { ResolvedSegment, SlotState } from "../types.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import type { RenderSegmentsOptions } from "../segment-system.js";
@@ -9,6 +10,11 @@ import type { RenderSegmentsOptions } from "../segment-system.js";
 export interface RscPayload<TMetadata = RscMetadata> {
     metadata?: TMetadata;
     returnValue?: ActionResult;
+    /**
+     * Form state of a PE POST document, for hydrateRoot's `formState` option.
+     * Rejects when the action's state is not Flight-serializable.
+     */
+    formState?: Promise<ReactFormState>;
 }
 /**
  * Handle data structure: handleName -> segmentId -> entries[]
@@ -406,6 +412,8 @@ export interface NavigateOptionsInternal extends Omit<NavigateOptions, "state">
     state?: unknown;
     /** Skip segment cache (used by redirect-with-state to force re-render) */
     _skipCache?: boolean;
+    /** Server redirects already followed by this navigation chain (0 for a user navigation) */
+    _redirectHops?: number;
 }
 /**
  * Options for useRouter push/replace methods.
@@ -476,6 +484,8 @@ export type StateListener = () => void;
  * EventController owns the public navigation lifecycle exposed by hooks.
  */
 export interface NavigationStore {
+    /** Client loader data for useLoader / useFetchLoader (loader-store.ts). */
+    readonly loaders: import("../loader-store.js").LoaderStore;
     getSegmentState(): SegmentState;
     setPath(path: string): void;
     setCurrentUrl(url: string): void;

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

@@ -37,6 +37,8 @@ export interface GeneratedManifest {
     prerenderRoutes?: string[];
     /** Route names wrapped with Passthrough() (live handler for runtime fallback) */
     passthroughRoutes?: string[];
+    /** Route names opted into on-demand prerender (Prerender(..., { onDemand })) */
+    onDemandRoutes?: string[];
     /** Route name → response type for non-RSC routes */
     responseTypeRoutes?: Record<string, string>;
     /** Route name -> search schema descriptor for typed URL helpers */

package/dist/types/cache/background-task.d.ts

@@ -6,6 +6,7 @@
  * settleGrowing). When waitUntil is unavailable, falls back to blocking or
  * skipping.
  */
+import type { ExecutionContext } from "../types/request-scope.js";
 interface WaitUntilHost {
     waitUntil?: (fn: () => Promise<void>) => void;
 }
@@ -40,4 +41,25 @@ export declare function raceDeadline<T>(work: Promise<T>, deadline: number): Pro
  * mutates `list`: a later call waits for what is still pending.
  */
 export declare function settleGrowing(list: readonly Promise<unknown>[], deadline: number): Promise<boolean>;
+/** Macrotask turns `awaitLaterMillisecond` waits at most. */
+export declare const LATER_MILLISECOND_MAX_TURNS = 10;
+/**
+ * Yield until `Date.now()` passes `since`, so a store's whole-millisecond tag
+ * gate (putShell vs an invalidation made just before) sees a later
+ * millisecond. Bounded: on Cloudflare the clock stands still between I/O
+ * events, so an unbounded wait could hang. At the bound the caller proceeds
+ * and a store may refuse the write, which its result reports.
+ */
+export declare function awaitLaterMillisecond(since: number, maxTurns?: number): Promise<void>;
+/** An ExecutionContext that keeps every promise handed to `waitUntil`. */
+export interface CollectingExecutionContext extends ExecutionContext {
+    readonly tasks: Promise<unknown>[];
+}
+/**
+ * Wrap the caller's ExecutionContext (or none) so a caller can wait for the
+ * request's background work: the deferred cache writes, the shell capture, a
+ * store's own writes. Every other member reads through to `inner`, bound to
+ * it (workerd's methods reject a foreign `this`).
+ */
+export declare function createCollectingExecutionContext(inner?: ExecutionContext): CollectingExecutionContext;
 export {};

package/dist/types/cache/cache-key-utils.d.ts

@@ -6,6 +6,7 @@
  * Used by cache-runtime, cache-scope, document-cache, and loader-cache.
  */
 import type { SearchParamsFilter } from "./search-params-filter.js";
+export declare function isReservedSearchParam(key: string): boolean;
 /**
  * Build a sorted, deterministic query string from URLSearchParams,
  * excluding the router's reserved params (see isReservedSearchParam).
@@ -27,11 +28,40 @@ export declare function sortedSearchString(searchParams: URLSearchParams, filter
  */
 export declare function sortedRouteParams(params: Record<string, string> | undefined): string;
 /**
- * Host-namespaced cache key base: `${host}${pathname}[:params][?search]`.
+ * THE ROUTER RULE (#1065). A key that names one router's output for a host
+ * and path starts with the router part, `{encodeURIComponent(routerId)}@`. A
+ * key that names a function and its arguments, or a tag, does not.
  *
- * The ONE composition of the host-namespacing rule, shared by the segment tier
- * (cache-scope.ts) and the document tier (document-cache.ts) so the rule cannot
- * drift between them. Host prefixing matters because VercelCacheStore /
+ * - With the part: PPR shells and the build-shell manifest (buildShellKey,
+ *   buildShellManifestKey); route cache() records, the document cache and
+ *   response routes (cacheKeyBase); a loader's own cache() entry; a
+ *   `"use cache"` entry of a call that takes a ctx (a ctx is one router's:
+ *   its variables, env and reverse() map).
+ * - Without: a `"use cache"` entry of plain arguments or a bare Request
+ *   (requestArgKey); tag markers; a key the app builds itself
+ *   (`cache({ key })`, a `keyGenerator`).
+ *
+ * Why: a host and path do not name a router. A `hostOverride` cookie picks
+ * the router and forwards the request unmodified, and a `router.prerender()`
+ * warm requests whatever origin it resolved, so two routers on one store
+ * built one key and read each other's entry.
+ *
+ * The id (router.ts) has to be the same in every isolate and in build-time
+ * discovery: an explicit `id` and the injected `$$id` are, the `router_{n}`
+ * fallback is for a single router only (discover-routers.ts warns about
+ * more). Encoded, the id holds no `@` or `/`, and a host holds no `@`, so a
+ * key has a router part exactly when its first `@` comes before its first
+ * `/`: no id can be chosen to spell another router's key.
+ */
+export declare function routerKeyPrefix(routerId: string): string;
+/**
+ * Key base of one router's output (the router rule, routerKeyPrefix):
+ * `${routerId}@${host}${pathname}[:params][?search]`.
+ *
+ * The ONE composition of the namespacing rule, shared by the segment tier
+ * (cache-scope.ts), the document tier (document-cache.ts), the response tier
+ * (rsc/response-cache-serve.ts) and the loader cache so the rule cannot drift
+ * between them. Host prefixing matters because VercelCacheStore /
  * MemorySegmentCacheStore key by the raw string (only CFCacheStore adds host
  * internally) -- on a single function serving multiple domains an
  * un-namespaced key bleeds tenant A's cached response to tenant B.
@@ -40,7 +70,22 @@ export declare function sortedRouteParams(params: Record<string, string> | undef
  * invalidates every persisted cache entry on upgrade. Callers append their own
  * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
  */
-export declare function cacheKeyBase(host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;
+export declare function cacheKeyBase(routerId: string, host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;
+/**
+ * cacheKeyBase for the request context `ctx`. rsc/handler.ts sets `_routerId`
+ * before the request scope opens and derived contexts inherit it, so a served
+ * request always has one. Only a hand-built context has none (a unit test,
+ * the runLoader / renderHandler primitives): its key has no router part,
+ * which no router's key equals (routerKeyPrefix).
+ */
+export declare function requestKeyBase(ctx: {
+    readonly _routerId?: string;
+} | null | undefined, host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;
+/**
+ * The `"use cache"` key part of a bare Request argument: its URL, with no
+ * router part (the router rule, routerKeyPrefix).
+ */
+export declare function requestArgKey(url: URL, filter?: SearchParamsFilter): string;
 /**
  * The prefix of a `key()` result's part in a record key (#975), and of a
  * loader's own `key()` result after its `loader:<id>:` namespace (#1009,

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

@@ -7,6 +7,14 @@
  */
 import type { CacheDefaults, SegmentCacheStore } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
+/**
+ * How long a follower trusts an in-flight leader before evicting it and
+ * running fresh. High enough that a slow-but-healthy upstream never triggers
+ * duplicate work (a legitimate cached call taking >15s is already pathological);
+ * low enough to bound the blast radius of a wedged leader to seconds, not the
+ * isolate lifetime. Aligned with SHELL_CAPTURE_MAX_WAIT_MS.
+ */
+export declare const IN_FLIGHT_LEADER_MAX_WAIT_MS = 15000;
 /**
  * Default TTL for route-level cache() DSL and loader cache.
  * Applied when neither the cache options nor the store defaults specify a TTL.
@@ -73,4 +81,13 @@ export declare function computeExpiration(ttlSeconds: number, swrSeconds?: numbe
 };
 export declare function resolveCacheKey(keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined, store: SegmentCacheStore | null, defaultKey: string): Promise<string>;
 export declare function resolveTagsOption<TEnv>(tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined, ctx: RequestContext<TEnv> | undefined, label: string): string[] | undefined;
+/**
+ * Normalize a resolved tags array so the WRITE path matches the invalidate path:
+ * updateTag()/revalidateTag()/cacheTag() all drop empty/whitespace-only tags via
+ * normalizeTag(). Without this, an empty tag attached at write time would enter
+ * the store index but could never be invalidated (the verbs normalize it away),
+ * and on CFCacheStore would also cost a wasted KV marker read per request.
+ * Returns undefined when nothing usable remains, keeping the entry header-free.
+ */
+export declare function normalizeTagList(tags: string[]): string[] | undefined;
 export declare function resolveCacheStore(explicitStore: SegmentCacheStore | undefined): SegmentCacheStore | null;

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

@@ -356,7 +356,7 @@ export declare class CacheScope {
  * enclosing scopes on another store (#974) and of a scope without its own
  * `key()` (#970)); with none, the app store's keyGenerator result
  * given the document default key. Undefined (synchronously, with no work)
- * when neither applies: the shell key stays host + path + filtered search.
+ * when neither applies: the shell key stays unpartitioned (buildShellKey).
  * Resolves to null when the partition is the default key itself (a
  * keyGenerator that returns it unchanged): that partitions nothing, so the
  * shell stays unpartitioned and keeps its build shell. The shell's key, its

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

@@ -3,7 +3,7 @@ declare global {
         readonly default: Cache;
     }
 }
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
+import type { CacheStoreScope, SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, ShellDocumentRead, ShellDocumentReadOptions, CacheReadError } from "../types.js";
 import { type RequestContext } from "../../server/request-context.js";
 import { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS } from "./cf-cache-constants.js";
 export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, };
@@ -43,6 +43,12 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private readonly kv?;
     /** True when constructed without KV: no durable tag history (see ctor). */
     readonly tagHistoryInert?: boolean;
+    /**
+     * SegmentCacheStore.scope: with KV every colo's L1 miss reads the same L2
+     * entry ("global"); without it entries live in one colo's Cache API
+     * ("local"), purge mode included (a purge evicts, it stores nothing).
+     */
+    readonly scope: CacheStoreScope;
     private readonly onRevalidateTag?;
     private readonly tagPurge?;
     private readonly tagInvalidationTtl?;

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

@@ -31,11 +31,14 @@ export interface DocumentCacheOptions<TEnv = any> {
     /**
      * Custom cache key generator.
      *
-     * Replaces the default `host + pathname + search` key entirely. On a
-     * multi-domain deployment served by one function you MUST include `url.host`
-     * (or an equivalent tenant discriminator) yourself — the default key is
-     * host-namespaced, but a custom generator's output is used verbatim, so
-     * omitting host bleeds one hostname's cached response to another.
+     * Replaces the default `router id + host + pathname + search` key entirely.
+     * On a multi-domain deployment served by one function you MUST include
+     * `url.host` (or an equivalent tenant discriminator) yourself — the default
+     * key is host-namespaced, but a custom generator's output is used verbatim,
+     * so omitting host bleeds one hostname's cached response to another. The
+     * same goes for the router: two routers that share a cache store and can
+     * serve one host and path (a `hostOverride` cookie) need a generator that
+     * tells them apart.
      */
     keyGenerator?: (url: URL) => string;
     /**

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

@@ -44,6 +44,18 @@ 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;
+/**
+ * captureHandles and captureHandleOwners cut down to the handle arrays that
+ * hold an owned value, each whole (its unowned values too, in place), so
+ * restoreHandles rebuilds exactly those arrays over a store that already
+ * holds the rest. A prerender-served shell capture stores this: the
+ * prerender store restores the handler pushes on a HIT, and the loader
+ * pushes have no other record (shell-capture.ts captureAndStoreShell).
+ */
+export declare function captureOwnedHandles(handleStore: HandleStore): {
+    handles: HandleRecord;
+    owners?: HandleOwners;
+};
 /**
  * What the record being restored is to each loader's handle pushes on this
  * request (HandleStore RecordAuthority). Built by loaderPins (loader-cache.ts)
@@ -65,6 +77,17 @@ export type OwnedPushDelivery = (loaderId: string) => RecordAuthority;
  * pushes in a placeholder's place).
  */
 export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, owned?: OwnedPushDelivery): void;
+/**
+ * Serve a doc record's handles: set its authority over the loaders' pushes
+ * (with or without a handles blob: a pinned loader whose capture pushed
+ * nothing has no copy, and its run must still add no settled push), then
+ * decode and restoreHandles. `keepIds` limits the restore to the segments a
+ * boundary-scoped scope serves. A decode failure skips the restore.
+ */
+export declare function restoreRecordHandles(handleStore: HandleStore, record: {
+    handles?: string;
+    handleOwners?: HandleOwners;
+}, owned: OwnedPushDelivery | undefined, keepIds?: ReadonlySet<string>): Promise<void>;
 /**
  * Append recorded handle pushes to the store, in recorded order, via push()
  * so active captures and loader-scope tagging see them like live pushes. For

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

@@ -1,4 +1,4 @@
-export type { SegmentCacheStore, CachedEntryData, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, SerializedSegmentData, SegmentHandleData, CacheReadError, } from "./types.js";
+export type { SegmentCacheStore, CacheStoreScope, CachedEntryData, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry, SerializedSegmentData, SegmentHandleData, CacheReadError, } from "./types.js";
 export { CACHE_READ_ERROR } from "./types.js";
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 export type { StoreMemoOptions } from "./shell-memo.js";

package/dist/types/cache/invalidation-order.d.ts

@@ -8,6 +8,20 @@ export interface ExecutionStart {
     readonly seq: number;
     readonly at: number;
 }
+/**
+ * The `taggedAt` / `ta` stamp a store writes on a tagged data entry: the start
+ * of the execution that produced the value (`startedAt`), so a marker written
+ * while it ran rejects the entry on read (#1068). Write time when the writer
+ * knows no start. Never later than now: a start from a skewed clock must not
+ * stamp the future, which would make the entry look newer than every marker.
+ */
+export declare function entryStamp(startedAt: number | undefined): number;
+/** The stamp of a data entry: `entryStamp` for a tagged entry, none otherwise. */
+export declare function taggedStamp(tags: readonly string[] | undefined, startedAt: number | undefined): number | undefined;
+/** Mark the execution start behind a Response handed to putResponse. */
+export declare function markResponseStart(response: Response, start: ExecutionStart): Response;
+/** The start a writer marked on `response`, if any. */
+export declare function responseStartedAt(response: Response): number | undefined;
 /** Record an execution's start, before it reads its data. */
 export declare function executionStart(): ExecutionStart;
 /**

package/dist/types/cache/memory-segment-store.d.ts

@@ -4,7 +4,7 @@
  * Simple in-memory implementation of SegmentCacheStore.
  * Uses globalThis to survive HMR in development.
  */
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry } from "./types.js";
+import type { CacheStoreScope, SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
 /**
  * Options for MemorySegmentCacheStore
@@ -70,6 +70,25 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
      * ```
      */
     maxEntries?: number;
+    /**
+     * Where an entry this store writes can be read; what `router.prerender()`
+     * checks before warming a route. Defaults to `"local"`: the maps live in one
+     * process, and the router cannot tell one long-running server from several
+     * replicas or serverless instances, so a warm into it is refused in
+     * production. Set `"global"` only when exactly one process serves the app
+     * (a single Node server); a warm then reports `warmed`. Under the Vite dev
+     * server a `"local"` instance already counts as shared.
+     *
+     * Like `defaults` and `keyGenerator`, the scope is per instance: two
+     * instances with the same `name` share their maps but each declares its own
+     * scope. Keep them identical.
+     *
+     * @example
+     * ```typescript
+     * const store = new MemorySegmentCacheStore({ scope: "global" });
+     * ```
+     */
+    scope?: CacheStoreScope;
 }
 /**
  * In-memory segment cache store.
@@ -106,6 +125,13 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
  * ```
  */
 export declare class MemorySegmentCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    /**
+     * SegmentCacheStore.scope: "local" unless `options.scope` says otherwise, so
+     * router.prerender() refuses to warm into these maps in production. Under
+     * the Vite dev server the gate counts a "local" instance as shared
+     * (store-scope.ts resolveWarmStoreScope).
+     */
+    readonly scope: CacheStoreScope;
     readonly supportsPassiveShellReads: true;
     private cache;
     private responseCache;
@@ -151,6 +177,12 @@ export declare class MemorySegmentCacheStore<TEnv = unknown> implements SegmentC
     } | null>;
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated">;
     isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    /**
+     * A tag invalidated in a millisecond after the write's execution started
+     * (#1068). Strictly after: the start's own millisecond is ambiguous, and
+     * invalidation-order.ts orders those exactly.
+     */
+    private invalidatedAfter;
     private tagsInvalidatedSince;
     invalidateTags(tags: string[]): Promise<void>;
     private registerTags;