@rangojs/router 0.27.0 → 0.28.0

package/dist/bin/rango.js

@@ -1644,7 +1644,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "@rangojs/router",
-      version: "0.27.0",
+      version: "0.28.0",
       description: "Django-inspired RSC router with composable URL patterns",
       keywords: [
         "react",

package/dist/types/__internal.d.ts

@@ -53,7 +53,13 @@ export type { CachedEntryData, CacheGetResult, SerializedSegmentData, CacheDefau
  * @internal
  * Router context for AsyncLocalStorage.
  */
-export type { RouterContext, RevalidationContext, InterceptResult, } from "./router/router-context.js";
+export type { RouterContext, InterceptResult, } from "./router/router-context.js";
+/**
+ * @internal
+ * The request side of a revalidating resolution pass (RouterContext's
+ * revalidating resolvers take it).
+ */
+export type { ResolutionPassInput } from "./router/segment-resolution/resolution-pass.js";
 /**
  * @internal
  * Route match context during pipeline processing.

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

@@ -207,7 +207,8 @@ export interface EventController {
     startAction(actionId: string, args: unknown[], 
     /** Originating history entry key; scopes location-state arbitration. */
     cohort?: string): ActionHandle;
-    abortAllActions(): void;
+    /** Abort every action in flight except `except` (an ActionHandle id). */
+    abortAllActions(except?: string): void;
     getState(): DerivedNavigationState;
     getActionState(actionId: string): TrackedActionState;
     getLocation(): NavigationLocation;

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

@@ -21,15 +21,9 @@ export declare function hasLocationState(state: unknown): boolean;
  */
 export declare function pushHistoryWithIdx(state: Record<string, unknown> | null, url: string, replace: boolean): void;
 /**
- * The forced-MISS reload marker (`SHELL_MISS_PARAM` in rsc/shell-serve.ts,
- * which the browser bundle must not import): a degraded PPR shell HIT
- * reloads the page with it, and the server renders a marked request like a
- * cache miss.
- */
-export declare const SHELL_MISS_MARKER: string;
-/**
- * Drop the forced-MISS marker from the address bar at boot, keeping the
- * history entry's state (initBrowserApp calls it before any location read).
+ * Drop the forced-MISS marker (`WIRE.shellMiss`, rsc/shell-serve.ts) from the
+ * address bar at boot, keeping the history entry's state (initBrowserApp
+ * calls it before any location read).
  * Left in place, a refresh or a shared link would stay off the shell and the
  * app's search params would carry it. The server strips the same marker from
  * the request before rendering (shell-serve.ts withoutShellMissMarker), so

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

@@ -24,16 +24,18 @@ export declare function liveHandleDataForCache(eventController: Pick<EventContro
  * Options for generating a history key
  */
 export interface HistoryKeyOptions {
-    /** If true, append :intercept suffix to differentiate intercept entries */
+    /** Key an intercept entry (apart from the plain entry for the URL). */
     intercept?: boolean;
+    /** The page the intercept was opened over (history.state.sourceUrl). */
+    interceptSource?: string;
 }
 /**
- * Generate a cache key from a URL.
- * Uses pathname + search (query params) directly as the key.
- * Hash fragments (#) are excluded since they don't affect server data.
+ * Generate a cache key from a URL: pathname + search. Hash fragments (#) are
+ * excluded since they don't affect server data.
  *
- * For intercept routes, append `:intercept` suffix to cache them separately
- * from non-intercept versions of the same URL.
+ * An intercept entry is keyed `<url>:intercept:<source>`: its cached tree
+ * includes the page under the intercept. hasInterceptCache relies on the
+ * `:intercept:` separator.
  */
 export declare function generateHistoryKey(url?: string, options?: HistoryKeyOptions): string;
 /**

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

@@ -26,8 +26,8 @@ export declare function loaderParentId(id: string): string;
  * 2. Place each parallel slot id (contains ".@") immediately after its
  *    parent layout/route id. Raw segment-resolution emission order does NOT
  *    guarantee this: route-mounted parallels are resolved/pushed BEFORE the
- *    route handler's segment is appended (see fresh.ts:resolveSegment for
- *    routes, and revalidation.ts ~915-919), so matched can read
+ *    route handler's segment is appended (see resolveSegment in
+ *    segment-resolution/revalidation.ts), so matched can read
  *    `[..., R0.@panel, R0]`. collectHandleData consumes segmentOrder verbatim
  *    with later-wins semantics, so without normalization the route handler's
  *    Meta would override the slot's more-specific Meta — backwards.

package/dist/types/browser/segment-reconciler.d.ts

@@ -62,10 +62,12 @@ export interface ReconcileResult {
  */
 export declare function reconcileSegments(input: ReconcileInput): ReconcileResult;
 /**
- * Reconcile error segments with cached segments.
+ * Reconcile an error-boundary response with cached segments.
  *
- * For error responses, the server returns the error boundary segment.
- * This function overlays error segments onto the full cached tree,
- * preserving sibling layouts that aren't in the error parent chain.
+ * The server returns the error boundary segment and, above it, what the
+ * action's revalidation re-ran (rsc/server-action.ts). This function overlays
+ * them onto the full cached tree, preserving sibling layouts that aren't in
+ * the error parent chain. The error segment replaces its cached copy; every
+ * other segment merges as an action's does (mergeCached).
  */
 export declare function reconcileErrorSegments(cachedSegments: ResolvedSegment[], errorSegments: ResolvedSegment[]): ReconcileResult;

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

@@ -558,7 +558,8 @@ export interface NavigationStore {
          */
         handlesPending?: boolean;
     } | undefined;
-    hasHistoryCache(historyKey: string): boolean;
+    /** Whether an intercept entry is cached for the plain `historyKey`, from any source page. */
+    hasInterceptCache(historyKey: string): boolean;
     /**
      * Update only the handleData (and optionally the stale / handlesPending flags)
      * of an existing cache entry. When a flag is omitted the entry's current value

package/dist/types/browser/wire-protocol.d.ts

@@ -0,0 +1,25 @@
+/** The parameters of a partial request: a navigation, a prefetch or a JS server action. */
+export interface PartialRequestInit {
+    /** A JS server action's id: written as `_rsc_action` in place of `_rsc_partial`. */
+    action?: string;
+    /** The mounted segment ids the server diffs against. */
+    segmentIds: readonly string[];
+    /**
+     * An empty `segmentIds`: "send" writes `_rsc_segments=` (navigation,
+     * action), "omit" leaves it out (prefetch). The prefetch cache keys carry
+     * the difference.
+     */
+    emptySegments: "send" | "omit";
+    stale?: boolean;
+    version?: string;
+    routerId?: string;
+    rewriteTarget?: string;
+    fill?: boolean;
+}
+/**
+ * Writes the partial-request parameters onto `url` in the one order every
+ * sender uses. Navigation and prefetch cache keys are built from the result
+ * (prefetch/cache.ts), so a navigation adopts a prefetch only while both
+ * write identically: browser/__tests__/wire-urls.test.ts pins the strings.
+ */
+export declare function writePartialParams(url: URL, init: PartialRequestInit): URL;

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

@@ -97,8 +97,10 @@ export declare const KEY_PART_PREFIX = "key:";
  * (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).
+ * (#974) and, for a route record key, the scope's own part: without a
+ * `key()` of its own, its default key (or its store's keyGenerator result,
+ * #970); with one, the default key's request kind (`doc`, `partial` or
+ * `intercept:<intercept>`, routeRecordKind in cache-scope.ts).
  *
  * Key scheme invariant (#975). A `key()` result is often request input,
  * and a record key has no route or scope discriminator (the store reads
@@ -124,9 +126,13 @@ export declare const KEY_PART_PREFIX = "key:";
  * 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.
+ * (a `key:` prefix, or no `:` at all) and its value. A request kind part is
+ * a default key's prefix without the URL after it, so it never equals a
+ * default key part; a keyGenerator part can equal it (`doc`) only when the
+ * keyGenerator returns a constant, which already gives every URL one record.
+ * 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.

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

@@ -14,16 +14,23 @@ import { type ExecutionStart } from "./tag-invalidation.js";
 import { type OwnedPushDelivery } from "./handle-snapshot.js";
 import type { RequestContext } from "../server/request-context.js";
 type CacheKeyFn = NonNullable<PartialCacheOptions["key"]>;
+/**
+ * A route record that answered. `restoreHandles` is set when the lookup left
+ * the handle restore to its caller (lookupRouteDetailed `deferHandles`),
+ * which names the segments it sends (handle-snapshot.ts restoreHandles).
+ */
+export interface CachedRouteHit {
+    segments: ResolvedSegment[];
+    shouldRevalidate: boolean;
+    restoreHandles?: (sentIds: ReadonlySet<string>) => Promise<void>;
+}
 /**
  * Discriminated outcome of a route cache lookup — see
  * {@link CacheScope.lookupRouteDetailed} for what each status licenses.
  */
 export type CacheRouteLookupOutcome = {
     status: "hit";
-    result: {
-        segments: ResolvedSegment[];
-        shouldRevalidate: boolean;
-    };
+    result: CachedRouteHit;
 } | {
     status: "miss" | "bypass" | "error";
 };
@@ -187,14 +194,18 @@ export declare class CacheScope {
      * 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:`).
+     * cache() one record: a `key()` replaces the default key's URL part, 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: its `key()`
+     * replaces the URL part, and its store's keyGenerator does not run. It
+     * appends `kind` instead (routeRecordKind): the `key()` decides which
+     * requests of one kind share a record, never that a document, a
+     * navigation and an intercept navigation do. 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:`, which passes no `kind`: a response route answers every
+     * request alike).
      *
      * Each `key()` result lives on the request context (`_resolvedCacheKeys`),
      * by function: it runs once per request whatever the default key
@@ -205,7 +216,7 @@ 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, partitionedPrefix?: string): Promise<string>;
+    resolveKeyFrom(defaultKey: string, partitionedPrefix?: string, kind?: string): Promise<string>;
     /**
      * @internal The request partition of a ppr route's shell under this scope
      * (resolveShellPartition): its partition parts (resolvePartitionParts),
@@ -285,14 +296,14 @@ 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 intercept - The intercept an intercept navigation selected
+     *   (interceptRecordKey): its record has its own key
      * @param ownedPushes - What the record is to each loader's handle pushes
      *   (withCacheLookup: loader-cache.ts loaderPins), called on a hit
+     * @param deferHandles - Restore no handle value here: the caller calls the
+     *   hit's `restoreHandles` once it decided which segments it sends
      */
-    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean, ownedPushes?: () => OwnedPushDelivery): Promise<{
-        segments: ResolvedSegment[];
-        shouldRevalidate: boolean;
-    } | null>;
+    lookupRoute(pathname: string, params: Record<string, string>, intercept?: string, ownedPushes?: () => OwnedPushDelivery, deferHandles?: boolean): Promise<CachedRouteHit | null>;
     /**
      * @internal lookupRoute with a discriminated outcome. The PPR replay
      * composition (withCacheLookup) may substitute the seeded doc record ONLY on
@@ -311,7 +322,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>, intercept?: string, ownedPushes?: () => OwnedPushDelivery, deferHandles?: boolean): 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.
@@ -341,13 +352,14 @@ export declare class CacheScope {
      * @param pathname - URL pathname for cache key generation
      * @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 intercept - The intercept an intercept navigation selected
+     *   (interceptRecordKey): its record has its own 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, start?: ExecutionStart): Promise<void>;
+    cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], intercept?: string, start?: ExecutionStart): Promise<void>;
 }
 /**
  * @internal The request partition of a ppr route's shell: with a route
@@ -392,7 +404,7 @@ export declare function createShellImplicitDocScope(marker: ShellImplicitCacheMa
  * normal partial navigation replay), substitute an implicit doc-level scope
  * so withCacheLookup/withCacheStore treat the WHOLE matched route as a
  * cache() boundary — the shell entry IS a cache() of the handler layer, with
- * loaders as the live carve-outs (resolveFreshLoadersAndYield).
+ * loaders as the live carve-outs (serveStoredSegments).
  *
  * A document HIT tail (`docTail`) always gets the implicit scope: it replays
  * the shell's own record and never consults a route-derived scope, whose

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

@@ -38,13 +38,13 @@ export declare const CACHE_REVALIDATING_AT_HEADER = "x-edge-cache-revalidating-a
  * re-arm re-puts the full window and restarts CF's retention clock, pinning a
  * perpetually-stale entry (one whose background revalidation keeps failing) past
  * its intended hard-expiry indefinitely. Mirrors the KVSegmentEnvelope `e`
- * field and the remaining-ttl math in promoteSegmentToL1/promoteItemToL1.
+ * field and the remaining-ttl math in promoteToL1.
  * @internal
  */
 export declare const CACHE_EXPIRES_AT_HEADER = "x-edge-cache-expires-at";
 /**
  * Header stashing the route author's original Cache-Control on L1 document
- * entries. putResponse/promoteResponseToL1 overwrite Cache-Control with a long
+ * entries. putResponse/promoteToL1 overwrite Cache-Control with a long
  * `max-age` so the CF Cache API retains the entry across the whole SWR window;
  * getResponse restores this original value before serving so the client and any
  * upstream CDN see the author's intended directive, not the internal edge TTL.

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

@@ -145,7 +145,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * the faulty per-colo entry ONLY when that fall-through found no good copy.
      *
      * The conditional evict is the load-bearing detail: when KV DOES serve a copy,
-     * kvGet* has already scheduled a same-key promote (`cache.put`); an eager
+     * readKv has already scheduled a same-key promote (`cache.put`); an eager
      * `cache.delete` here would race that put with no CF Cache API ordering
      * guarantee and could clobber the freshly-restored entry. So in that case we
      * lean on #558's heal-by-overwrite (the non-suppressed fall-through promotes /
@@ -164,7 +164,10 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     private healCorruptL1;
     /**
      * Re-put a stale L1 entry marked REVALIDATING, so concurrent requests serve it
-     * without each triggering a revalidation. Shared by get()/getItem().
+     * without each triggering a revalidation (readL1). A JSON family re-puts its
+     * parsed body as a string, without a status text as set() writes it; the
+     * document re-puts a clone (`source`) whose original body still streams to
+     * the client.
      *
      * The write is NON-BLOCKING (waitUntil) and best-effort by design:
      * - It runs in waitUntil, so it never adds the put latency to the served stale
@@ -185,20 +188,6 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private markRevalidating;
-    /**
-     * Document-tier counterpart of markRevalidating for getResponse's herd guard.
-     * The segment/item tiers JSON-parse the body, so they re-put with a string
-     * body; document bodies are streamed verbatim, so we re-put with a CLONED
-     * response body (`response.clone()`) supplied by the caller -- the original
-     * body still streams to the client while the marker carries the clone. Same
-     * REVALIDATING status header, same revalidating-at stamp, same
-     * remainingCacheControl re-put math as markRevalidating, so the document tier
-     * suppresses concurrent revalidation for the identical MAX_REVALIDATION_INTERVAL
-     * window the segment tier does. Best-effort and non-blocking: a failed marker
-     * write must not affect the served stale read.
-     * @internal
-     */
-    private markResponseRevalidating;
     /**
      * Guard the segment tier against a `keyGenerator` that returns a key colliding
      * with a reserved tag-marker namespace: `__tag__/` (the KV marker key) or
@@ -212,17 +201,29 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     private isReservedSegmentKey;
     /**
-     * Get cached entry data by key.
-     *
-     * Handles SWR atomically:
+     * Get cached entry data by key (readL1). On L1 miss, falls back to KV (L2)
+     * if configured; KV hits are promoted to L1 in the background.
+     */
+    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
+    /**
+     * The family's debug sink for one read; the document family is outside the
+     * debug surface (op is only get/getItem). Undefined when debug is off, so
+     * the hot path allocates no event.
+     * @internal
+     */
+    private debugSink;
+    /**
+     * The L1 read of a family, which handles SWR atomically:
      * - If stale and not already revalidating, marks as REVALIDATING and returns shouldRevalidate: true
      * - If already REVALIDATING (and recent), returns shouldRevalidate: false
      * - If fresh, returns shouldRevalidate: false
      *
-     * On L1 miss, falls back to KV (L2) if configured.
-     * KV hits are promoted to L1 in the background.
+     * Every degraded L1 read falls through to KV (readKv). The family methods
+     * return it unwrapped: an async wrapper adds two promises and two microtask
+     * ticks to every read.
+     * @internal
      */
-    get(key: string): Promise<CacheGetResult | null | CacheReadError>;
+    private readL1;
     /**
      * Store entry data with TTL and optional SWR window.
      * Resolves once the L1 write lands, per the SegmentCacheStore.set contract
@@ -236,9 +237,9 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     delete(key: string): Promise<boolean>;
     /**
-     * Get a cached Response by key (for document-level caching).
-     * Returns the response and whether it should be revalidated (SWR).
-     * Falls back to KV (L2) on L1 miss.
+     * Get a cached Response by key (for document-level caching): see readL1.
+     * Its body streams to the client unread, outside the debug surface. Falls
+     * back to KV (L2) on L1 miss.
      */
     getResponse(key: string): Promise<{
         response: Response;
@@ -258,7 +259,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
     /**
      * Get a cached function result by key.
-     * Follows the same SWR pattern as get() for segment caching.
+     * Follows the same SWR pattern as get() for segment caching (readL1).
      * Falls back to KV (L2) on L1 miss.
      */
     getItem(key: string): Promise<CacheItemResult | null>;
@@ -351,7 +352,7 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * caller's `tagHints`: cfTagHints may have evicted the key while the memo
      * still holds it. A shell a tag marker rejects is dropped and read from
      * the store too, which may hold a capture from after the marker (see
-     * get(), "Tag invalidation"), unless the request's own mask rejected it
+     * readL1(), "Tag invalidation"), unless the request's own mask rejected it
      * (declinesKvFallThrough).
      */
     private readMemoizedShell;
@@ -538,15 +539,6 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private skipUncacheableTagSet;
-    /**
-     * Merge the internal tag headers onto an existing Headers instance. The
-     * from-scratch paths spread tagHeaderEntries() into an object-literal init;
-     * the document put/promote paths build a Headers first, so they .set() each
-     * entry instead — except `Cache-Tag`, which is APPENDED: a document author
-     * may have set their own Cache-Tag, and clobbering it would break their CDN
-     * purging. Append produces the comma-merged list CF expects.
-     */
-    private setTagHeaders;
     /** Read an entry's tags/taggedAt back from its headers. */
     private readTagInfo;
     /**
@@ -780,12 +772,27 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
     /** invalidateTags' marker writes, tag purge, and hooks. */
     private writeTagInvalidation;
     /**
-     * KV fallback for segment cache reads.
-     * Returns null if KV is not configured, entry is missing, or expired.
-     * Promotes hits to L1 via waitUntil.
+     * The KV (L2) read behind an L1 miss, for every family: a missing,
+     * timed-out, corrupt (kvGetOrEvict reports and evicts it), expired or
+     * tag-invalidated envelope is a miss, a read failure is the family's read
+     * error, and a hit is promoted to L1 in the background.
+     *
+     * A degraded L1 fall-through (body-timeout / non-200) passes
+     * `suppressRevalidate`: KV has no REVALIDATING herd guard, so N concurrent
+     * degraded reads would otherwise each spawn a render exactly when the colo
+     * is already struggling. The stale data is still served and promoted; only
+     * the revalidation is withheld.
+     * @internal
+     */
+    private readKv;
+    /**
+     * Promote a KV hit to L1 in the background, under its remaining ttl, with
+     * its deadlines (so a promoted entry that later goes stale re-puts with the
+     * correct remaining ttl, see set()) and its tags (so it stays
+     * tag-invalidatable). The family builds the entry (toL1).
      * @internal
      */
-    private kvGetSegment;
+    private promoteToL1;
     /**
      * Write segment data to KV.
      *
@@ -794,29 +801,4 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private kvSetSegment;
-    /**
-     * Promote segment data from KV to L1 Cache API.
-     * @internal
-     */
-    private promoteSegmentToL1;
-    /**
-     * KV fallback for function cache reads.
-     * @internal
-     */
-    private kvGetItem;
-    /**
-     * Promote function cache data from KV to L1.
-     * @internal
-     */
-    private promoteItemToL1;
-    /**
-     * KV fallback for document cache reads.
-     * @internal
-     */
-    private kvGetResponse;
-    /**
-     * Promote document cache data from KV to L1.
-     * @internal
-     */
-    private promoteResponseToL1;
 }

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

@@ -37,7 +37,7 @@ export declare function kvKeyDigest(value: string): Promise<string>;
  * of restarting it -- copying set()'s original full-window max-age would reset
  * CF's retention clock on every re-arm and pin a perpetually-stale entry forever.
  * An entry lacking a valid deadline (legacy/tampered) floors to max-age=1, so it
- * hard-expires in ~1s and self-heals via KV. Mirrors promoteSegmentToL1's math.
+ * hard-expires in ~1s and self-heals via KV. Mirrors promoteToL1's math.
  * @internal
  */
 export declare function remainingCacheControl(headers: Headers, now: number): string;

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

@@ -31,7 +31,7 @@ export declare function decodeHandleValue<T>(encoded: string): Promise<T | null>
  *
  * DSL-loader pushes stay out of the CACHE WRITE: a HIT runs loaders exactly
  * as an uncached render of the same request would (cache-lookup.ts
- * resolveFreshLoadersAndYield), so replaying a recorded copy would duplicate
+ * serveStoredSegments), so replaying a recorded copy would duplicate
  * the live push. Handler pushes, including
  * handler-invoked ctx.use(Loader) bodies (skipped with their handler on a
  * HIT), are kept. The store tags loader pushes by array position at push
@@ -75,19 +75,24 @@ export type OwnedPushDelivery = (loaderId: string) => RecordAuthority;
  * owner. Neither claims its loader, so the loader's own cache() HIT still
  * delivers (the pushes holding a promise a restored copy lets through, or its
  * entry's pushes in a placeholder's place).
+ *
+ * `sent` (a partial request) names the segments the response sends. Any
+ * other segment is kept with its handler's values, as on a live walk: only
+ * its loaders' copies are restored, which follow their loader as above.
  */
-export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, owned?: OwnedPushDelivery): void;
+export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, owned?: OwnedPushDelivery, sent?: ReadonlySet<string>): 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.
+ * boundary-scoped scope serves; `sent` is restoreHandles'. 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>;
+}, owned: OwnedPushDelivery | undefined, keepIds?: ReadonlySet<string>, sent?: 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/segment-codec.d.ts

@@ -37,6 +37,20 @@ export declare function rscDeserialize<T>(encoded: string | undefined): Promise<
  * Returns null only on serialization failure.
  */
 export declare function serializeResult(value: unknown, onError?: (error: unknown) => void): Promise<string | null>;
+/** The Flight encode of a value and a decoded copy of it (teeResult). */
+export interface TeedResult {
+    /** The copy: settles when the root row arrives; later rows stream in. */
+    decoded: Promise<unknown>;
+    /** The whole encoded text, or null when the stream failed. */
+    serialized: Promise<string | null>;
+}
+/**
+ * Encode `value` once and decode a copy of it as the encode streams, so a
+ * "use cache" miss renders the copy as a hit renders a stored entry, and
+ * stores the same bytes. Null when the encode could not start.
+ */
+export declare function teeResult(value: unknown, onError?: (error: unknown) => void): TeedResult | null;
+export declare function isUnsupportedValueError(error: unknown): boolean;
 /**
  * RSC-deserialize a cached result string.
  * Counterpart to serializeResult() — always receives a non-empty string.

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

@@ -210,7 +210,7 @@ export declare function buildShellLoaderSeed(snapshot: ShellSnapshotRecord[], on
 export declare const SHELL_HANDLES_RECORD_KEY = "handles";
 /**
  * The `handles` record of a prerender-served entry, which a HIT tail restores
- * after the prerender store's handles (cache-lookup.ts yieldFromStore), or
+ * after the prerender store's handles (cache-lookup.ts decodeStoredEntry), or
  * undefined: an entry with a doc record, or one written before the record
  * existed (v0.21), which serves as it did.
  */

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

@@ -35,9 +35,19 @@
  * request, is neither joined nor written (#973, #977): see
  * predatesInvalidation, and docs/design/caching.md "Read-your-own-writes".
  */
+import { type RequestContext } from "../server/request-context.js";
 import type { SegmentCacheStore } from "./types.js";
 import { type ExecutionStart } from "./invalidation-order.js";
 export { executionStart, invalidatedSince, markResponseStart, type ExecutionStart, } from "./invalidation-order.js";
+/**
+ * Run a stale entry's background refresh on the visitor's request context: a
+ * "use cache" function's (cache-runtime.ts) or a cached loader's
+ * (loader-cache.ts). No visitor made the invalidations in it, so they set no
+ * fresh-reads cookie, as in a stale cache() HIT's re-render or a document
+ * cache entry's re-run, whose passes take a sink's no-op writer
+ * (server/render-pass.ts).
+ */
+export declare function runAsBackgroundRefresh<T>(ctx: RequestContext, fn: () => T): T;
 /**
  * The write gate of every cache execution (#977): whether one of `tags` was
  * invalidated after the execution that produced the value started.

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

@@ -11,9 +11,11 @@ export declare const NOCACHE_SYMBOL: unique symbol;
  */
 export declare function isTainted(value: unknown): boolean;
 /**
- * Symbol stamped on tainted ctx objects PASSED AS ARGUMENTS to a "use cache"
- * function during its execution. ctx.set(), ctx.header(), etc. check this
- * flag and throw if present — those side effects are lost on cache hit.
+ * Symbol stamped on tainted handler and middleware ctx objects PASSED AS
+ * ARGUMENTS to a "use cache" function during its execution. ctx.set(),
+ * ctx.header(), etc. check this flag and throw if present — those side
+ * effects are lost on cache hit. A request context passed as an argument is
+ * not stamped (registerCachedFunction in cache-runtime.ts).
  *
  * Argument objects only. Ambient access (cookies()/headers() and ctx methods
  * reached via getRequestContext()) is guarded by the AsyncLocalStorage scope