@rangojs/router 0.18.0 → 0.19.0

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

@@ -41,6 +41,12 @@ export interface RscMetadata {
     resolvedIds?: string[];
     /** Merged route params from the matched route */
     params?: Record<string, string>;
+    /**
+     * The matched route's name (include name prefix applied), when the route is
+     * named. The browser keeps it per history entry for transition({ when })'s
+     * `from.routeName` / `to.routeName` (browser/transition-when.ts).
+     */
+    routeName?: string;
     /**
      * State of named slots for this route match
      * Key is slot name (e.g., "@modal"), value is slot state
@@ -246,6 +252,17 @@ export interface SegmentState {
     currentUrl: string;
     currentSegmentIds: string[];
 }
+/**
+ * What the router remembers about one history entry for transition({ when })
+ * (NavigationStore.rememberDisplayedEntry).
+ *
+ * @internal This type is an implementation detail and may change without notice.
+ */
+export interface HistoryEntryMemory {
+    readonly routeName: string | undefined;
+    /** The entry's `history.state` as last recorded. */
+    readonly state: unknown;
+}
 /**
  * Navigation update emitted when UI should re-render
  *
@@ -265,11 +282,51 @@ export interface NavigationUpdate {
     };
 }
 /**
- * State value for navigate/Link
- * - LocationStateEntry[]: Type-safe state entries (recommended)
- * - unknown: Plain state format (object or getter function)
+ * Plain object accepted as {@link PlainHistoryState}. The `any` string index
+ * admits interface-typed values (an `unknown` index would reject interfaces,
+ * which carry no implicit index signature). The `never` members reject:
+ * - a single typed entry (`GridState(value)` without the array) — its
+ *   `__rsc_ls_*` fields would be spread onto history.state and
+ *   `useLocationState(GridState)` would read `undefined`;
+ * - functions, including a location-state definition passed uncalled
+ *   (`Symbol.hasInstance` comes from `Function.prototype`), which throw
+ *   `DataCloneError`;
+ * - arrays and other iterables (`Symbol.iterator`), so an array must match the
+ *   typed-entry or plain-array member instead;
+ * - built-ins tagged with `Symbol.toStringTag` (`Promise`, `WeakMap`,
+ *   `WeakSet`), which throw `DataCloneError`. The cloneable tagged ones
+ *   (`Map`, `Set`, `ArrayBuffer`, typed arrays) have their own members.
+ *
+ * Members are not checked: a function, symbol, or React element inside a
+ * plain object still compiles, as does a top-level `ReactElement` or DOM node
+ * (an object with none of the keys above).
+ */
+export interface PlainHistoryObject {
+    readonly [key: string]: any;
+    readonly __rsc_ls_key?: never;
+    readonly __rsc_ls_value?: never;
+    readonly __rsc_ls_lazy?: never;
+    readonly [Symbol.iterator]?: never;
+    readonly [Symbol.hasInstance]?: never;
+    readonly [Symbol.toStringTag]?: never;
+}
+/**
+ * Plain (untyped) navigation state, stored under `history.state.state` and
+ * read with `useLocationState<T>()`. A structured-clone-safe value: primitives,
+ * arrays, `Map`/`Set`, `ArrayBuffer`, typed arrays, and plain objects. Excludes
+ * functions, symbols, `Promise`/`WeakMap`/`WeakSet`, and objects carrying
+ * `__rsc_ls_*` keys (a typed entry passed without its array). Arrays, `Map`,
+ * and `Set` are checked element by element; plain object members are not
+ * checked (see {@link PlainHistoryObject}).
  */
-export type HistoryState = import("./react/location-state-shared.js").LocationStateEntry[] | unknown;
+export type PlainHistoryState = string | number | boolean | bigint | null | undefined | readonly PlainHistoryState[] | ReadonlyMap<PlainHistoryState, PlainHistoryState> | ReadonlySet<PlainHistoryState> | ArrayBuffer | ArrayBufferView | PlainHistoryObject;
+/**
+ * State value for `router.push()` / `router.replace()` / `<Link state>`.
+ * - `readonly LocationStateEntry[]`: typed entries from `createLocationState()`
+ *   definitions, e.g. `[GridState({ count: 3 })]` (recommended)
+ * - {@link PlainHistoryState}: plain structured-clone-safe state
+ */
+export type HistoryState = readonly import("./react/location-state-shared.js").LocationStateEntry[] | PlainHistoryState;
 /**
  * Options for navigation operations
  */
@@ -295,6 +352,22 @@ export interface NavigateOptions {
      * ```
      */
     revalidate?: boolean;
+    /**
+     * Set to `false` to present this navigation without a transition: the
+     * commit is urgent and every `<ViewTransition>` class resolves to `"none"`,
+     * the same result as a `transition({ when })` predicate returning `false`.
+     * No `when` predicate is called. Back/forward, action and revalidation
+     * commits are unaffected (they are not started by this call).
+     *
+     * @default true (the route's transition config applies)
+     *
+     * @example
+     * ```tsx
+     * router.push("/photos/2", { transition: false });
+     * <Link to="/photos/2" transition={false}>Next</Link>
+     * ```
+     */
+    transition?: boolean;
     /**
      * State to pass to history.pushState/replaceState
      * Accessible via useLocationState() hook.
@@ -316,14 +389,21 @@ export interface NavigateOptions {
      * // Plain static state
      * navigate("/product", { state: { from: "list" } });
      *
-     * // Plain just-in-time state
-     * navigate("/product", { state: () => ({ from: window.location.pathname }) });
+     * // Compile errors (and a dev-mode runtime error for untyped callers):
+     * navigate("/product", { state: ProductState(p) }); // entry without the array
+     * navigate("/product", { state: [ProductState] }); // definition not called
      * ```
      */
     state?: HistoryState;
 }
-/** @internal Extended options used only within the navigation bridge */
-export interface NavigateOptionsInternal extends NavigateOptions {
+/**
+ * @internal Extended options used only within the navigation bridge. `state`
+ * is widened to `unknown`: the redirect lanes pass state already resolved to
+ * a flat `history.state` record, and in dev Link passes an uncalled
+ * definition through to resolveNavigationState's check.
+ */
+export interface NavigateOptionsInternal extends Omit<NavigateOptions, "state"> {
+    state?: unknown;
     /** Skip segment cache (used by redirect-with-state to force re-render) */
     _skipCache?: boolean;
 }
@@ -402,6 +482,21 @@ export interface NavigationStore {
     setSegmentIds(ids: string[]): void;
     getHistoryKey(): string;
     setHistoryKey(key: string): void;
+    /**
+     * Per-history-entry memory for transition({ when }) sources: record the
+     * entry on screen (keyed by its `history.state.key`) with its current
+     * `history.state` and, when given, its route name (kept from the last
+     * record otherwise; every push/replace creates a new key, so a stale name
+     * never carries to another entry). Called after every commit, restore and
+     * state merge.
+     */
+    rememberDisplayedEntry(routeName?: string): void;
+    /**
+     * The memory of the entry on screen, or of `entryKey`. At popstate
+     * history.state already belongs to the destination, so back/forward reads
+     * the entry being LEFT from here. In-memory only: empty after a reload.
+     */
+    getHistoryEntryMemory(entryKey?: string): HistoryEntryMemory | undefined;
     /** Monotonic token of the most recently committed navigation. */
     getNavInstance(): number;
     cacheSegmentsForHistory(historyKey: string, segments: ResolvedSegment[], handleData?: HandleData): void;
@@ -517,7 +612,7 @@ export interface ServerActionBridgeConfig {
  * Navigation bridge for handling client-side navigation
  */
 export interface NavigationBridge {
-    navigate(url: string, options?: NavigateOptions): Promise<void>;
+    navigate(url: string, options?: NavigateOptionsInternal): Promise<void>;
     refresh(): Promise<void>;
     handlePopstate(): Promise<void>;
     registerLinkInterception(): () => void;

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

@@ -93,6 +93,14 @@ export declare function generateManifestFull<TEnv>(urlpatterns: UrlPatterns<TEnv
      * EntryData map built below is local; this is the only seam that surfaces it.
      */
     collectClientFallbackRef?: (refKey: string) => void;
+    /**
+     * Fail on an invalid transition({ when }): a non-function, or a plain
+     * (server) function where a client reference is required. Only the Vite
+     * plugin's discovery passes it: it evaluates the tree in the react-server
+     * graph, the one place a "use client" import is told apart from a server
+     * function (transition-when-ref.ts).
+     */
+    validateTransitionWhen?: boolean;
 }): Promise<FullManifest>;
 /**
  * Generate TypeScript code for the manifest

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

@@ -1,8 +1,10 @@
 /**
  * Background Task Runner
  *
- * Unified helper for scheduling async work via waitUntil.
- * When waitUntil is unavailable, falls back to blocking or skipping.
+ * Unified helper for scheduling async work via waitUntil, and the two bounded
+ * waits the PPR shell capture puts on background work (raceDeadline,
+ * settleGrowing). When waitUntil is unavailable, falls back to blocking or
+ * skipping.
  */
 interface WaitUntilHost {
     waitUntil?: (fn: () => Promise<void>) => void;
@@ -18,4 +20,24 @@ interface WaitUntilHost {
  * @returns A promise when blocking fallback is used, void otherwise.
  */
 export declare function runBackground(host: WaitUntilHost | null | undefined, task: () => Promise<void>, blockWhenNoWaitUntil?: boolean): Promise<void> | void;
+/**
+ * Race `work` against an absolute deadline (epoch ms), keeping its value. The
+ * losing work is not cancelled (a router match has no abort signal) and its
+ * late rejection is swallowed. The timer is unref'd, so a pending deadline
+ * never keeps a Node dev process alive.
+ */
+export declare function raceDeadline<T>(work: Promise<T>, deadline: number): Promise<{
+    done: true;
+    value: T;
+} | {
+    done: false;
+}>;
+/**
+ * Wait until every promise in `list` has settled, including ones appended
+ * while waiting (a settled write can schedule a nested one: cacheRoute
+ * schedules its store.set in a second waitUntil), or until `deadline` (epoch
+ * ms). Resolves true when the list drained, false at the deadline. Never
+ * mutates `list`: a later call waits for what is still pending.
+ */
+export declare function settleGrowing(list: readonly Promise<unknown>[], deadline: number): Promise<boolean>;
 export {};

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

@@ -31,6 +31,37 @@
 export interface CacheExecScope {
     readonly parent?: CacheExecScope;
 }
+/**
+ * Run a callback whose identity reads never reach a shared entry, so
+ * guardIdentityRead (server/context.ts) lets them through and records
+ * nothing (#976):
+ *
+ * - a cache's own decisions and metadata: a `key()`, a store `keyGenerator`
+ *   (cache-policy.ts resolveCacheKey), a `condition()` (cache-scope.ts
+ *   conditionAllows, loader-cache.ts) and a `tags()` function
+ *   (cache-policy.ts resolveTagsOption). The value picks the entry, whether
+ *   one is used, or how it is invalidated; it is never rendered. Reading the
+ *   request there is the documented way to partition an entry;
+ * - the router's `onError` (router/error-handling.ts invokeOnError): it
+ *   observes, and a render error can reach it inside a capture or a cached
+ *   scope.
+ *
+ * Scar: a ppr capture resolves its doc record key, and the record's tags,
+ * again under the capture context; once `ctx.request.headers` was guarded, a
+ * keyGenerator or tags() reading it refused every capture of the route.
+ *
+ * The exemption is async-local, so it would follow everything the callback
+ * starts. A "use cache" body (runWithCacheExecScope), a loader body
+ * (server/context.ts runInsideLoaderBodyScope) and a segment funnel
+ * (getContext().runWithStore) end it on entry (endIdentityExempt). Scar: a
+ * key() that awaited a "use cache" function reading cookies() stored the
+ * first visitor's cookie and served it to the next.
+ */
+export declare function runIdentityExempt<T>(fn: () => T): T;
+/** True inside runIdentityExempt, and not in a scope started from it. */
+export declare function isInsideIdentityExempt(): boolean;
+/** Run `fn` with the identity exemption ended (see runIdentityExempt). */
+export declare function endIdentityExempt<T>(fn: () => T): T;
 /**
  * Run fn with the "use cache" execution scope active. Continuations spawned
  * from fn's synchronous kickoff inherit the scope; parallel chains do not.

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

@@ -42,17 +42,48 @@ export declare function sortedRouteParams(params: Record<string, string> | undef
  */
 export declare function cacheKeyBase(host: string, pathname: string, searchParams?: URLSearchParams, params?: Record<string, string>, filter?: SearchParamsFilter): string;
 /**
- * The record key, or shell partition, of nested keyed cache() scopes (#970)
- * from its parts, outermost first: the chain's `key()` results and, for an
- * inner scope without its own `key()`, that scope's default key
- * (CacheScope.resolveKeyFrom). One part is returned raw, so a single keyed
- * scope keeps its key byte for byte. Two or more are joined by `|`, each
- * URI-encoded (like partitionShellKey, rsc/shell-capture-constants.ts): an
- * encoded part holds no `|`, so every tuple maps to its own key, of any
- * depth. Raw, `("a|b", "c")` and `("a", "b|c")` named one record. A composed
- * key holds no `:` either, so a single raw result with one (a prefixed
- * `tier:...`, a `doc:` default key) never equals it; an unprefixed raw result
- * can. Shared with the testing helper `shellCacheKey`, which composes a
- * nested partition the same way.
+ * 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,
+ * loader-cache.ts loaderKeyFromResult).
  */
-export declare function composeCacheKeys(parts: readonly string[]): string;
+export declare const KEY_PART_PREFIX = "key:";
+/**
+ * A cache() record key, or ppr shell partition, from its parts
+ * (CacheScope.resolveKeyFrom, CacheScope.resolvePartition): the `key()`
+ * results of the scope's cache() chain, outermost first, then its default
+ * parts: the keyGenerator results of enclosing scopes on another store
+ * (#974) and, for a record key under a scope without its own `key()`, its
+ * default key (or its store's keyGenerator result, #970).
+ *
+ * Key scheme invariant (#975). A `key()` result is often request input,
+ * and a record key has no route or scope discriminator (the store reads
+ * `store.get(key)`), so a result that equals another record's key writes
+ * one route's content under the other's entry. Before #975 a single
+ * `key()` result was stored raw: the header value `doc:localhost/pricing`
+ * named /pricing's default-keyed record, and `gold|doc%3Alocalhost%2Fpricing`
+ * named gold's nested /pricing record (#970). So every part is encoded:
+ *
+ * - a `key()` part is `key:` plus `encodeURIComponent(result)`: it starts
+ *   with `key:` and holds no `|` and no other `:`;
+ * - a default part is `encodeURIComponent(value)`: it holds no `:` or `|`;
+ *   an enclosing store's keyGenerator result equal to the default key is an
+ *   empty part, so each store keeps its position (CacheScope
+ *   positionalParts);
+ * - one `key()` part is the key; two or more parts are joined by `|`,
+ *   `key()` parts first;
+ * - a lone default part stays raw: with no `key()` on the chain the record
+ *   key is the default key or the store's keyGenerator result, unchanged.
+ *
+ * Why nothing collides: the router's default keys (`doc:`, `partial:`,
+ * `intercept:`, `response:<type>:`) never start with `key:` and hold a `:`.
+ * A namespaced `key()` result starts with `key:` and holds no `|`. A
+ * composed key holds a `|` and either starts with `key:` or holds no `:`.
+ * Among composed keys, splitting on `|` recovers each part, a part's kind
+ * (a `key:` prefix, or no `:` at all) and its value. Pinned by the collision
+ * probe in src/cache/__tests__/cache-scope-chain.test.ts. A keyGenerator
+ * result is the store's own namespace, as before.
+ *
+ * Shared with the testing helper `shellCacheKey`, so a test builds the
+ * production partition.
+ */
+export declare function composeCacheKeys(keyResults: readonly string[], defaultParts?: readonly string[]): string;

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

@@ -71,6 +71,6 @@ export declare function computeExpiration(ttlSeconds: number, swrSeconds?: numbe
     staleAt: number;
     expiresAt: number;
 };
-export declare function resolveCacheKey(keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined, store: SegmentCacheStore | null, defaultKey: string, _label: string): Promise<string>;
+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;
 export declare function resolveCacheStore(explicitStore: SegmentCacheStore | undefined): SegmentCacheStore | null;

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

@@ -40,6 +40,13 @@ export { isCachedFunction };
  * identical arg sets.
  */
 export declare function replyToCacheKey(encoded: string | FormData): Promise<string>;
+/**
+ * @internal Reset this module's per-isolate state: the in-flight leaders a
+ * follower would join for up to IN_FLIGHT_LEADER_MAX_WAIT_MS, and the
+ * once-per-function warnings. Tests only (testing/serve-shell-request.ts
+ * resetShellTestState), never while a request is in flight.
+ */
+export declare function resetCacheRuntimeForTests(): void;
 /**
  * Register a function as a cached function.
  * Called by the Vite transform for each "use cache" function.

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

@@ -10,8 +10,9 @@
 import type { PartialCacheOptions } from "../types.js";
 import type { ResolvedSegment } from "../types.js";
 import type { SegmentCacheStore } from "./types.js";
+import { type ExecutionStart } from "./tag-invalidation.js";
+import { type OwnedPushDelivery } from "./handle-snapshot.js";
 import type { RequestContext } from "../server/request-context.js";
-export declare function resolveCacheTags(config: PartialCacheOptions | false, ctx: RequestContext | undefined): string[] | undefined;
 type CacheKeyFn = NonNullable<PartialCacheOptions["key"]>;
 /**
  * Discriminated outcome of a route cache lookup — see
@@ -53,6 +54,19 @@ export declare class CacheScope {
      * a ppr route).
      */
     readonly boundary?: string | undefined;
+    /**
+     * Awaited on every lookup HIT: the implicit doc scope's marker `onHit`
+     * (createShellImplicitDocScope), which arms a partial replay's bake-lane
+     * loader pins before the route's loaders resolve.
+     */
+    private readonly onHit?;
+    /**
+     * The record key of the implicit doc scope of a document HIT tail
+     * (createShellImplicitDocScope): the shell entry's own `docKey`, used as
+     * is. Not a `key()`, which would be namespaced (#975) and miss the
+     * record.
+     */
+    private readonly fixedKey?;
     readonly config: PartialCacheOptions | false;
     readonly parent: CacheScope | null;
     /** Explicit store from cache() options, if specified */
@@ -69,6 +83,29 @@ export declare class CacheScope {
     readonly keyFns: readonly CacheKeyFn[];
     /** Whether this scope's own config sets `key()` (the last of keyFns). */
     private readonly hasOwnKey;
+    /**
+     * The `condition()` predicates gating this scope, outermost first: every
+     * cache() on the parent chain that sets one, this scope's last (#974). A
+     * read or write needs all of them to allow it (conditionAllows). Before,
+     * only the innermost config's predicate ran, so an outer condition()
+     * refusing a request still let a nested cache() read and write.
+     */
+    private readonly conditions;
+    /**
+     * The `tags` options of this scope and every cache() on the parent chain,
+     * outermost first (#974): a nested record carries them all (resolveTags),
+     * so `updateTag(outerTag)` evicts it and the shells built from it.
+     */
+    private readonly tagOptions;
+    /**
+     * The enclosing enabled scopes without a `key()` of their own whose
+     * `store` option differs from this scope's, outermost first: a store
+     * keyGenerator of theirs partitions this scope's records too (#974,
+     * resolvePartitionParts). On the same store the keyGenerator already
+     * applies through this scope's own default key, or its own `key()`
+     * overrides it (#970).
+     */
+    private readonly storeScopes;
     constructor(config: PartialCacheOptions | false, parent?: CacheScope | null, defaultKeyPrefix?: "doc" | undefined, 
     /**
      * @internal shortCode of the outermost cache() entry of this scope's
@@ -77,7 +114,20 @@ export declare class CacheScope {
      * Undefined covers the whole matched chain (the implicit shell doc scope,
      * a ppr route).
      */
-    boundary?: string | undefined);
+    boundary?: string | undefined, 
+    /**
+     * Awaited on every lookup HIT: the implicit doc scope's marker `onHit`
+     * (createShellImplicitDocScope), which arms a partial replay's bake-lane
+     * loader pins before the route's loaders resolve.
+     */
+    onHit?: (() => void | Promise<void>) | undefined, 
+    /**
+     * The record key of the implicit doc scope of a document HIT tail
+     * (createShellImplicitDocScope): the shell entry's own `docKey`, used as
+     * is. Not a `key()`, which would be namespaced (#975) and miss the
+     * record.
+     */
+    fixedKey?: string | undefined);
     /**
      * @internal Whether a segment belongs to this scope's cache entry. ShortCodes are
      * hierarchical (server/context.ts getShortCode: parent shortCode + include
@@ -130,17 +180,21 @@ export declare class CacheScope {
      * request: a ppr route's shell partition (resolvePartition) and the record
      * lookup share the `key()` runs, and a rejection is shared too.
      *
-     * With `key()` functions on the chain (keyFns) the parts are their results,
-     * outermost first, composed by composeCacheKeys (a single part raw), so a
-     * nested cache() keys its records within the enclosing partition (#970).
-     * A scope whose own config sets no `key()` appends its own default key
-     * (resolveDefaultKey). Reusing the outer `key()` result alone would give
-     * every route under the inner cache() one record: a `key()` replaces the
-     * whole default key, so an outer key that names no route (`tier:gold`)
-     * would make `/a` HIT `/b`'s record. A scope with its own `key()` adds no
-     * default key: a `key()` is a full override, and no keyGenerator runs.
-     * Without `key()` on the chain it is resolveDefaultKey alone. With one but
-     * no request context it rejects (keyWithoutContextError).
+     * With partition parts on the chain (resolvePartitionParts: the `key()`
+     * results, and the keyGenerator results of enclosing scopes on another
+     * store), they are composed by composeCacheKeys, which namespaces every
+     * `key()` result (#975), so a nested cache() keys its records within the
+     * enclosing partition (#970, #974). A scope whose own config sets no
+     * `key()` appends its own default key (resolveDefaultKey). Reusing the
+     * outer `key()` result alone would give every route under the inner
+     * cache() one record: a `key()` replaces the whole default key, so an
+     * outer key that names no route (`tier:gold`) would make `/a` HIT `/b`'s
+     * record. A scope with its own `key()` adds no default key: a `key()` is a
+     * full override, and its store's keyGenerator does not run. With no
+     * partition part it is resolveDefaultKey alone. With a `key()` on the
+     * chain but no request context it rejects (keyWithoutContextError).
+     * `partitionedPrefix` prefixes a key built from partition parts only (the
+     * response family's `response:`).
      *
      * Each `key()` result lives on the request context (`_resolvedCacheKeys`),
      * by function: it runs once per request whatever the default key
@@ -151,20 +205,30 @@ export declare class CacheScope {
      * itself: a `key()` calling `cookies()` would trip the capture guard there,
      * and a capture must store the partition its request resolved.
      */
-    resolveKeyFrom(defaultKey: string): Promise<string>;
+    resolveKeyFrom(defaultKey: string, partitionedPrefix?: string): Promise<string>;
     /**
      * @internal The request partition of a ppr route's shell under this scope
-     * (resolveShellPartition): the chain's `key()` results, composed like the
-     * record key but without the default key, which the URL-based shell key
-     * already carries. A scope without its own `key()` whose store has a
-     * keyGenerator adds that result when it differs from the `doc` default
-     * key, as an unkeyed scope's partition always did: the record is split by
-     * it, so the shell must be too. Undefined (synchronously, with no work)
-     * when nothing can partition; null when nothing does.
+     * (resolveShellPartition): its partition parts (resolvePartitionParts),
+     * composed like the record key but without the default key, which the
+     * URL-based shell key already carries. A scope without its own `key()`
+     * whose store has a keyGenerator adds that result when it differs from the
+     * `doc` default key, as an unkeyed scope's partition always did: the
+     * record is split by it, so the shell must be too. Undefined
+     * (synchronously, with no work) when nothing can partition; null when
+     * nothing does.
      */
     resolvePartition(pathname: string, params: Record<string, string> | undefined): Promise<string | null> | undefined;
-    /** The chain's `key()` results, each once per request (memoizedKey). */
-    private resolveKeyResults;
+    /** Whether a partition part can apply: a `key()` or a store scope above. */
+    private get mayPartition();
+    /**
+     * The parts partitioning this scope's records, outermost first: the
+     * chain's `key()` results (each once per request, memoizedKey) and the
+     * keyGenerator result of each enclosing scope on another store (once per
+     * keyGenerator, #974), null where it is `defaultKey`. The callers keep those
+     * positions (positionalParts): a result equal to the default key
+     * partitions nothing only when every one does (#970).
+     */
+    private resolvePartitionParts;
     /**
      * This scope's store keyGenerator result for `defaultKey` (once per request
      * and default key), else `defaultKey` (resolveCacheKey).
@@ -192,11 +256,11 @@ export declare class CacheScope {
      */
     get isShellImplicitDocScope(): boolean;
     /**
-     * Evaluate the cache `condition` predicate. Returns false (skip the cache
-     * operation) when the predicate returns false or throws; returns true when
-     * there is no condition or no request context to evaluate it against.
-     */
-    /**
+     * Evaluate the cache `condition` predicates of this scope and every
+     * enclosing cache() (`conditions`, #974), outermost first. Returns false
+     * (skip the cache operation) when one returns false or throws; returns
+     * true when there is none or no request context to evaluate them against.
+     *
      * One WRITE decision per (scope, request), memoized on the request context.
      * A capture render has TWO writers consulting the same predicate — the
      * explicit tier's cacheRoute and the snapshot-only doc record gate
@@ -208,6 +272,12 @@ export declare class CacheScope {
      * at the replay gate was the round-2 regression.
      */
     private readonly writeConditionMemo;
+    /**
+     * Evaluate the cache `condition` predicate. Returns false (skip the cache
+     * operation) when the predicate returns false or throws; returns true when
+     * there is no condition or no request context to evaluate it against. A
+     * write decision is memoized (writeConditionMemo).
+     */
     private conditionAllows;
     /**
      * Lookup cached segments for a route (single cache entry per request).
@@ -216,10 +286,11 @@ 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 claimLoaderPushes - The handler context's _claimLoaderPushes, for
-     *   restoreHandles' loader-owned values
+     * @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)
      */
-    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean, claimLoaderPushes?: (loaderId: string) => boolean): Promise<{
+    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean, ownedPushes?: OwnedPushDelivery): Promise<{
         segments: ResolvedSegment[];
         shouldRevalidate: boolean;
     } | null>;
@@ -241,7 +312,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, claimLoaderPushes?: (loaderId: string) => boolean): 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.
@@ -257,6 +328,12 @@ export declare class CacheScope {
      * (the tag union is a Set), so the duplicate record in cacheRoute is harmless.
      */
     recordTags(requestCtx: RequestContext | undefined): void;
+    /**
+     * @internal The `tags` of this scope and every enclosing cache()
+     * (`tagOptions`, #974), static and function forms, for `ctx`: the tags its
+     * records carry. Undefined when none resolve (a disabled scope has none).
+     */
+    resolveTags(ctx: RequestContext | undefined): string[] | undefined;
     /**
      * Cache all segments for a route (non-blocking via waitUntil)
      * Single cache entry per route request.
@@ -266,14 +343,19 @@ export declare class CacheScope {
      * @param params - Route params for cache key generation
      * @param segments - All resolved segments to cache
      * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+     * @param start - Where the render of `segments` started: the record is not
+     *   written when one of its tags was invalidated since (#977,
+     *   predatesInvalidation). A shell capture's doc record passes none: it
+     *   lives only in the shell entry, which putShell gates by its own start.
      */
-    cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], isIntercept?: boolean): Promise<void>;
+    cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], isIntercept?: boolean, start?: ExecutionStart): Promise<void>;
 }
 /**
  * @internal The request partition of a ppr route's shell: with a route
  * cache() scope, its CacheScope.resolvePartition (the chain's `key()`
- * results, composed, plus a keyGenerator's contribution for a scope without
- * its own `key()` (#970)); with none, the app store's keyGenerator result
+ * results, namespaced and composed (#975), plus the keyGenerator results of
+ * 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.
  * Resolves to null when the partition is the default key itself (a

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

@@ -11,6 +11,13 @@
  */
 import { type RequestContext } from "../server/request-context.js";
 import { type LoaderIdentityRead } from "../server/context.js";
+import type { ExecutionStart } from "./tag-invalidation.js";
+/**
+ * Call `fn` outside any "use cache" tag scope: detached work a cached body
+ * schedules (a stale entry's background refresh) records nothing onto the
+ * entry being filled.
+ */
+export declare function outsideCacheTagScope<T>(fn: () => T): T;
 /**
  * Arm the record tag owners for `ctx`: its match resolved a cache scope, so
  * it can write a route cache() record (match-api.ts). A capture's or
@@ -148,17 +155,30 @@ export declare function markIdentityRead(set: Set<string>, read: LoaderIdentityR
 export declare function recordedIdentityRead(root: Set<string>): LoaderIdentityRead | undefined;
 /** `root`'s tags plus those of every set it links to, transitively. */
 export declare function flattenRecordedTags(root: Set<string>): Set<string>;
+/** Record where the execution recording into `set` started. */
+export declare function markTagSetStart(set: Set<string>, start: ExecutionStart): void;
+/**
+ * The earliest start among `root` and every set it links to: a value built
+ * from another execution's value is as old as the oldest of them. A
+ * loader-cache write gates on it (loader-cache.ts), because the loader value
+ * it stores can be a run a reader started before the binding executed, and
+ * the values that run read can be older still.
+ */
+export declare function earliestRecordedStart(root: Set<string>): ExecutionStart | undefined;
 /**
- * Run a function within a cache tag scope. Any cacheTag() calls inside `fn`
- * accumulate into the returned Set.
+ * Run a function within a cache tag scope. Any cacheTag() calls inside `fn`,
+ * and the tags a nested "use cache" call records (recordOwnedTags, #980),
+ * accumulate into the returned Set and every scope enclosing it
+ * (scopeParents).
  *
  * The returned Set is the LIVE reference - the caller must await `result`
  * before reading `tags`, because an async cached function may call cacheTag()
- * after an await boundary.
+ * after an await boundary. Pass `tagSet` to re-enter an execution's scope
+ * (its result's Flight encode, #980); it keeps the parent it opened under.
  *
  * @internal Used by cache-runtime.ts to wrap "use cache" execution.
  */
-export declare function runWithCacheTagScope<T>(fn: () => T): {
+export declare function runWithCacheTagScope<T>(fn: () => T, tagSet?: Set<string>): {
     result: T;
     tags: Set<string>;
 };