@rangojs/router 0.15.1 → 0.17.0

package/dist/testing/vitest.js

@@ -1,6 +1,233 @@
 // src/testing/vitest.ts
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
+
+// src/vite/plugins/use-cache-transform.ts
+import path2 from "node:path";
+
+// src/vite/plugins/expose-id-utils.ts
+import path from "node:path";
+import crypto from "node:crypto";
+function normalizePath(p) {
+  return p.split(path.sep).join("/");
+}
+function hashId(filePath, exportName) {
+  const input = `${filePath}#${exportName}`;
+  const hash = crypto.createHash("sha256").update(input).digest("hex");
+  return `${hash.slice(0, 8)}#${exportName}`;
+}
+
+// src/vite/plugins/use-cache-transform.ts
+var CACHE_RUNTIME_IMPORT = "@rangojs/router/cache-runtime";
+var LAYOUT_TEMPLATE_PATTERN = /\/(layout|template)\.(tsx?|jsx?)$/;
+var USE_CACHE_DIRECTIVE_RE = /^use cache(:\s*[\w-]+)?$/;
+function isUseCacheCandidate(code, id) {
+  return (
+    // Quick bail: no "use cache" in source
+    code.includes("use cache") && // Skip node_modules and virtual modules
+    !id.includes("/node_modules/") && !id.startsWith("\0") && // Only JS/TS files
+    /\.(tsx?|jsx?|mjs)$/.test(id)
+  );
+}
+var rscTransforms = null;
+async function transformUseCache(code, id, options) {
+  if (!rscTransforms) {
+    try {
+      rscTransforms = await import("@vitejs/plugin-rsc/transforms");
+    } catch (error) {
+      options.onTransformsError?.(error);
+      return;
+    }
+  }
+  const { hasDirective, transformWrapExport, transformHoistInlineDirective } = rscTransforms;
+  let ast;
+  try {
+    const { parseAst } = await import("vite");
+    ast = parseAst(code, { lang: "tsx" });
+  } catch {
+    return;
+  }
+  stripNullDirectiveFields(ast);
+  const filePath = normalizePath(path2.relative(options.root, id));
+  const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
+  if (hasDirective(ast.body, "use cache")) {
+    return transformFileLevelUseCache(
+      code,
+      ast,
+      filePath,
+      id,
+      options.isBuild,
+      isLayoutOrTemplate,
+      transformWrapExport,
+      hasDirective
+    );
+  }
+  const functionResult = transformFunctionLevelUseCache(
+    code,
+    ast,
+    filePath,
+    id,
+    options.isBuild,
+    transformHoistInlineDirective
+  );
+  warnOnNearMissDirectives(ast, id, options.warn);
+  if (functionResult) return functionResult;
+}
+async function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport, hasDirective) {
+  const unconfirmedExports = [];
+  const { exportNames, output } = transformWrapExport(code, ast, {
+    runtime: (value, name) => {
+      const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+      return `__rango_registerCachedFunction(${value}, ${JSON.stringify(funcId)}, "default")`;
+    },
+    rejectNonAsyncFunction: false,
+    filter: (name, meta) => {
+      if (name === "default" && isLayoutOrTemplate) return false;
+      if (name.startsWith("$$hoist_")) return false;
+      if (isHoistedServerReferenceRebind(meta.valueNode)) return false;
+      if (functionHasUseServerDirective(meta.valueNode, hasDirective)) {
+        return false;
+      }
+      if (meta.isFunction !== true) {
+        unconfirmedExports.push(name);
+        return false;
+      }
+      return true;
+    }
+  });
+  if (unconfirmedExports.length > 0) {
+    const plural = unconfirmedExports.length > 1;
+    throw new Error(
+      `[rango:use-cache] File-level "use cache" in ${sourceId} only wraps exports that are statically-confirmed functions. ${plural ? "These exports are" : "This export is"} not: ${unconfirmedExports.map((n) => `"${n}"`).join(", ")}. Declare them directly (export async function foo() {} or export const foo = async () => {}). A factory or otherwise statically-indeterminate initializer (export const foo = makeCached(fn)) is rejected even if it returns a function at runtime -- rewrite it as a direct async function, or move non-function exports to a separate module.`
+    );
+  }
+  if (exportNames.length === 0) {
+    const { default: MagicString } = await import("magic-string");
+    const s = new MagicString(code);
+    const directive2 = findFileLevelDirective(ast);
+    if (directive2) {
+      s.overwrite(
+        directive2.start,
+        directive2.end,
+        `/* "use cache" -- wrapped by rango */`
+      );
+      return {
+        code: s.toString(),
+        map: s.generateMap({ source: sourceId, hires: "boundary" })
+      };
+    }
+    return;
+  }
+  output.prepend(
+    `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};
+`
+  );
+  const directive = findFileLevelDirective(ast);
+  if (directive) {
+    output.overwrite(
+      directive.start,
+      directive.end,
+      `/* "use cache" -- wrapped by rango */`
+    );
+  }
+  return {
+    code: output.toString(),
+    map: output.generateMap({ source: sourceId, hires: "boundary" })
+  };
+}
+function transformFunctionLevelUseCache(code, ast, filePath, sourceId, isBuild, transformHoistInlineDirective) {
+  try {
+    const { output, names } = transformHoistInlineDirective(code, ast, {
+      directive: USE_CACHE_DIRECTIVE_RE,
+      runtime: (value, name, meta) => {
+        const funcId = isBuild ? hashId(filePath, name) : `${filePath}#${name}`;
+        const profileMatch = meta.directiveMatch[1];
+        const profileName = profileMatch ? profileMatch.replace(/^:\s*/, "").trim() : "default";
+        return `__rango_registerCachedFunction(${value}, ${JSON.stringify(funcId)}, ${JSON.stringify(profileName)})`;
+      },
+      rejectNonAsyncFunction: false
+    });
+    if (names.length === 0) return;
+    output.prepend(
+      `import { registerCachedFunction as __rango_registerCachedFunction } from ${JSON.stringify(CACHE_RUNTIME_IMPORT)};
+`
+    );
+    return {
+      code: output.toString(),
+      map: output.generateMap({ source: sourceId, hires: "boundary" })
+    };
+  } catch {
+    return;
+  }
+}
+function stripNullDirectiveFields(node) {
+  if (!node || typeof node !== "object") return;
+  const rec = node;
+  if (rec.type === "ExpressionStatement" && typeof rec.directive !== "string") {
+    delete rec.directive;
+  }
+  for (const value of Object.values(rec)) {
+    if (Array.isArray(value)) {
+      for (const item of value) stripNullDirectiveFields(item);
+    } else if (value && typeof value === "object" && "type" in value) {
+      stripNullDirectiveFields(value);
+    }
+  }
+}
+function isHoistedServerReferenceRebind(valueNode) {
+  if (!valueNode || valueNode.type !== "CallExpression") return false;
+  const first = valueNode.arguments[0];
+  return first !== void 0 && first.type === "Identifier" && first.name.startsWith("$$hoist_");
+}
+function functionHasUseServerDirective(valueNode, hasDirective) {
+  if (!valueNode || !("body" in valueNode)) return false;
+  const { body } = valueNode;
+  if (!body || Array.isArray(body) || body.type !== "BlockStatement") {
+    return false;
+  }
+  return hasDirective(
+    body.body,
+    "use server"
+  );
+}
+function findFileLevelDirective(ast) {
+  for (const node of ast.body ?? []) {
+    if (node.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string" && node.expression.value.startsWith("use cache")) {
+      return { start: node.start, end: node.end };
+    }
+  }
+  return null;
+}
+var NEAR_MISS_RE = /^use cache:\s*.+$/;
+function warnOnNearMissDirectives(ast, fileId, warn) {
+  const visit = (node) => {
+    if (!node || typeof node !== "object") return;
+    if (node.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string") {
+      const value = node.expression.value;
+      if (value.startsWith("use cache") && NEAR_MISS_RE.test(value) && !USE_CACHE_DIRECTIVE_RE.test(value)) {
+        const profilePart = value.slice("use cache:".length).trim();
+        warn(
+          `[rango:use-cache] "${value}" in ${fileId} has an invalid profile name "${profilePart}". Profile names must match [a-zA-Z0-9_-]+. This directive will be ignored.`
+        );
+      }
+    }
+    for (const key of Object.keys(node)) {
+      const child = node[key];
+      if (Array.isArray(child)) {
+        for (const item of child) {
+          visit(item);
+        }
+      } else if (child && typeof child === "object" && child.type) {
+        visit(child);
+      }
+    }
+  };
+  for (const node of ast.body ?? []) {
+    visit(node);
+  }
+}
+
+// src/testing/vitest.ts
 function here(relativeFromRoot) {
   return fileURLToPath(new URL(`../../${relativeFromRoot}`, import.meta.url));
 }
@@ -94,9 +321,34 @@ function rangoUseClientTransform() {
     }
   };
 }
+function rangoUseCacheTransform() {
+  let root = process.cwd();
+  return {
+    name: "rango:testing-use-cache",
+    enforce: "post",
+    configResolved(config) {
+      root = config.root;
+    },
+    async transform(code, id) {
+      if (!isUseCacheCandidate(code, id)) return void 0;
+      return transformUseCache(code, id, {
+        root,
+        isBuild: false,
+        warn: (message) => this.warn(message),
+        onTransformsError: (error) => {
+          throw new Error(
+            `rangoUseCacheTransform: @vitejs/plugin-rsc/transforms failed to load, so "use cache" functions in ${id} would run unwrapped.`,
+            { cause: error }
+          );
+        }
+      });
+    }
+  };
+}
 export {
   rangoInlineDeps,
   rangoTestAliases,
   rangoTestConfig,
+  rangoUseCacheTransform,
   rangoUseClientTransform
 };

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

@@ -22,6 +22,12 @@ interface CommitOptions {
     cacheOnly?: boolean;
     /** Server-set location state to merge into history.pushState */
     serverState?: Record<string, unknown>;
+    /**
+     * Back/forward: history is already at this entry. Its state (scroll key,
+     * location state, idx) stays as the browser restored it; serverState is
+     * merged in. The page left was saved by handleTraversalStart.
+     */
+    traversal?: boolean;
 }
 /**
  * Options that can override the pre-configured commit settings

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

@@ -2,6 +2,17 @@ import type { NavigationStore, NavigationClient, UpdateSubscriber, ResolvedSegme
 import type { ReactNode } from "react";
 import type { RenderSegmentsOptions } from "../segment-system.js";
 import type { BoundTransaction } from "./navigation-transaction.js";
+import type { NavigationUpdate } from "./types.js";
+export declare function shouldStartViewTransition(segments: ResolvedSegment[]): boolean;
+/**
+ * Transition commit. Every held commit announces the loader streams the
+ * committed tree is still receiving (loader-store.ts announcePendingStreams)
+ * so held useLoader readers pin isLoading:true until this transition lands;
+ * settled/cached segments make it a no-op. Urgent commits call onUpdate
+ * 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;
 /**
  * Configuration for creating a partial updater
  */

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

@@ -1,5 +1,5 @@
 /**
- * Props for ScrollRestoration component
+ * Props for `<Html.ScrollRestoration />`.
  */
 export interface ScrollRestorationProps {
     /**
@@ -20,10 +20,10 @@ export interface ScrollRestorationProps {
      * const byPathname = (location) => location.pathname;
      *
      * // Restore based on pathname (same URL = same scroll)
-     * <ScrollRestoration getKey={byPathname} />
+     * <Html.ScrollRestoration getKey={byPathname} />
      *
      * // Restore based on unique history entry (default)
-     * // <ScrollRestoration /> — omit getKey to use location.key
+     * // <Html.ScrollRestoration /> — omit getKey to use location.key
      * ```
      */
     getKey?: (location: {
@@ -34,7 +34,7 @@ export interface ScrollRestorationProps {
     }) => string;
 }
 /**
- * ScrollRestoration component
+ * Public as `Html.ScrollRestoration` (`@rangojs/router/client`).
  *
  * Enables scroll position restoration across navigations:
  * - Saves scroll positions to sessionStorage
@@ -51,7 +51,7 @@ export interface ScrollRestorationProps {
  *   return (
  *     <html>
  *       <body>
- *         <ScrollRestoration />
+ *         <Html.ScrollRestoration />
  *         {children}
  *       </body>
  *     </html>
@@ -63,7 +63,7 @@ export declare function ScrollRestoration({ getKey }: ScrollRestorationProps): n
 /**
  * Hook to initialize scroll restoration
  *
- * Alternative to the ScrollRestoration component for more control.
+ * Alternative to `<Html.ScrollRestoration />` for more control.
  *
  * @example
  * ```tsx

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

@@ -126,7 +126,7 @@ export interface RangoProps {
  *
  * @example
  * ```tsx
- * import { initBrowserApp, Rango } from "rsc-router/browser";
+ * import { initBrowserApp, Rango } from "@rangojs/router/browser";
  * import { rscStream } from "rsc-html-stream/client";
  * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
  *

package/dist/types/browser/scroll-restoration.d.ts

@@ -84,6 +84,13 @@ export declare function scrollToTop(): void;
  * - Ensures new history entry has a key
  */
 export declare function handleNavigationStart(): void;
+/**
+ * Handle scroll for a back/forward traversal, at popstate before anything
+ * renders: save the page being left under ITS key (history has already moved,
+ * so saveCurrentScrollPosition would use the destination's key) and track the
+ * destination as the displayed entry.
+ */
+export declare function handleTraversalStart(): void;
 /**
  * Handle scroll after navigation completes.
  * @param options.restore - If true, restore saved position (for popstate)

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

@@ -22,10 +22,27 @@
  * registration below wires assertNotInsideCacheExec to this scope without
  * taint.ts importing it.
  */
+/**
+ * One "use cache" execution. Identity matters: the execution's handle capture
+ * (cache-runtime.ts) records only pushes from its own chain, including cached
+ * functions it calls (`parent` links them), not concurrent pushes into the
+ * same request store.
+ */
+export interface CacheExecScope {
+    readonly parent?: CacheExecScope;
+}
 /**
  * Run fn with the "use cache" execution scope active. Continuations spawned
  * from fn's synchronous kickoff inherit the scope; parallel chains do not.
+ * Pass `scope` (createCacheExecScope) to test membership with
+ * isInCacheExecChain.
  */
-export declare function runWithCacheExecScope<T>(fn: () => T): T;
+export declare function runWithCacheExecScope<T>(fn: () => T, scope?: CacheExecScope): T;
+/** A scope nested in the calling chain's current one, if any. */
+export declare function createCacheExecScope(): CacheExecScope;
 /** True when the calling async chain is inside a "use cache" body. */
 export declare function isInsideCacheExecScope(): boolean;
+/** The calling chain's innermost "use cache" scope, if any. */
+export declare function getCacheExecScope(): CacheExecScope | undefined;
+/** True when the calling async chain runs inside `scope`, at any depth. */
+export declare function isInCacheExecChain(scope: CacheExecScope): boolean;

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

@@ -44,11 +44,36 @@ export type CacheRouteLookupOutcome = {
  */
 export declare class CacheScope {
     private readonly defaultKeyPrefix?;
+    /**
+     * @internal shortCode of the outermost cache() entry of this scope's
+     * enabled chain (createCacheScope). Entries above it are live: their
+     * segments are not stored and resolve fresh on a hit (withCacheLookup).
+     * Undefined covers the whole matched chain (the implicit shell doc scope,
+     * a ppr route).
+     */
+    readonly boundary?: string | undefined;
     readonly config: PartialCacheOptions | false;
     readonly parent: CacheScope | null;
     /** Explicit store from cache() options, if specified */
     private readonly explicitStore;
-    constructor(config: PartialCacheOptions | false, parent?: CacheScope | null, defaultKeyPrefix?: "doc" | undefined);
+    constructor(config: PartialCacheOptions | false, parent?: CacheScope | null, defaultKeyPrefix?: "doc" | undefined, 
+    /**
+     * @internal shortCode of the outermost cache() entry of this scope's
+     * enabled chain (createCacheScope). Entries above it are live: their
+     * segments are not stored and resolve fresh on a hit (withCacheLookup).
+     * Undefined covers the whole matched chain (the implicit shell doc scope,
+     * a ppr route).
+     */
+    boundary?: string | undefined);
+    /**
+     * @internal Whether a segment belongs to this scope's cache entry. ShortCodes are
+     * hierarchical (server/context.ts getShortCode: parent shortCode + include
+     * scope + type letter + counter), so the boundary's subtree is every id that
+     * extends the boundary shortCode at a non-digit (`C1` must not claim `C10`).
+     * Intercept slot segments ride the target route's entry wherever the
+     * intercept is declared.
+     */
+    covers(id: string, namespace?: string): boolean;
     /**
      * Whether caching is enabled for this scope
      */
@@ -127,8 +152,10 @@ export declare class CacheScope {
      * @param pathname - URL pathname for cache key generation
      * @param params - Route params for cache key generation
      * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+     * @param claimLoaderPushes - The handler context's _claimLoaderPushes, for
+     *   restoreHandles' loader-owned values
      */
-    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean): Promise<{
+    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean, claimLoaderPushes?: (loaderId: string) => boolean): Promise<{
         segments: ResolvedSegment[];
         shouldRevalidate: boolean;
     } | null>;
@@ -150,7 +177,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): Promise<CacheRouteLookupOutcome>;
+    lookupRouteDetailed(pathname: string, params: Record<string, string>, isIntercept?: boolean, claimLoaderPushes?: (loaderId: string) => 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.
@@ -179,11 +206,13 @@ export declare class CacheScope {
     cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], isIntercept?: boolean): Promise<void>;
 }
 /**
- * Create a cache scope from entry's cache config
+ * Create a cache scope from entry's cache config. `shortCode` is the cache()
+ * entry's: a scope nested in an enabled parent keeps the parent's boundary
+ * (one entry covers both), any other opens its own at this entry.
  */
 export declare function createCacheScope(config: {
     options: PartialCacheOptions | false;
-} | undefined, parent?: CacheScope | null): CacheScope | null;
+} | undefined, parent?: CacheScope | null, shortCode?: string): CacheScope | null;
 type ShellImplicitCacheMarker = NonNullable<RequestContext["_shellImplicitCache"]>;
 /**
  * Mint the implicit doc-level scope for a `_shellImplicitCache` marker: key

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

@@ -7,17 +7,55 @@
  */
 import type { HandleStore } from "../server/handle-store.js";
 import type { SegmentHandleData } from "./types.js";
-export interface HandleCapture {
+/**
+ * Scoping for one capture of a cached unit (a loader's own cache(),
+ * loader-cache.ts; a "use cache" function, cache-runtime.ts) that runs
+ * concurrently with live pushes into the same store.
+ */
+export interface HandleCaptureOptions {
+    /** Push-time predicate; a rejected push is not recorded by this capture. */
+    accept?: () => boolean;
+    /**
+     * Recorded pushes do not reach the store. A stale hit's background
+     * revalidation: the foreground already replayed the entry's pushes, so the
+     * fresh body's pushes belong only to the refreshed entry.
+     */
+    divert?: boolean;
+    /**
+     * Record key for an accepted push, in place of its segment id. A loader's
+     * own cache() (loader-cache.ts recordOwnerKey) and "use cache"
+     * (useCacheRecordKey) group pushes by the loader body that made them.
+     */
+    key?: () => string;
+}
+/**
+ * HandleStore.pushReplayed, attributed to `loaderId` for the record key of an
+ * enclosing "use cache" MISS: an outer cached function records an inner HIT's
+ * replayed loader pushes under that loader, not as its own.
+ */
+export declare function replayLoaderPush(handleStore: HandleStore, handleName: string, segmentId: string, value: unknown, loaderId: string): void;
+/**
+ * Record key for a "use cache" capture: run-length groups `${seq}:${owner}`,
+ * so the HIT (handle-snapshot.ts appendHandles) delivers each loader's pushes
+ * at most once per request. The owner is the loader whose body, entered
+ * inside this execution via ctx.use, made the push; empty for the function's
+ * own pushes and those of cached functions it calls. Groups keep push order
+ * across owners. Create at call time: the caller's loader body is the
+ * function's own scope.
+ */
+export declare function useCacheRecordKey(): () => string;
+export interface HandleCapture extends HandleCaptureOptions {
     data: Record<string, SegmentHandleData>;
 }
 /**
- * Start capturing handle pushes for a cached function execution.
+ * Start capturing handle pushes for a cached function or cached loader
+ * execution (`options`: see HandleCaptureOptions).
  *
  * Concurrency-safe: multiple overlapping captures on the same
  * HandleStore are independent. Each capture registers a token in a
  * Set; stopping removes it. No ordering requirement (LIFO not needed).
  */
-export declare function startHandleCapture(handleStore: HandleStore): {
+export declare function startHandleCapture(handleStore: HandleStore, options?: HandleCaptureOptions): {
     capture: HandleCapture;
     stop: () => void;
 };

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

@@ -7,11 +7,18 @@
  */
 import type { ResolvedSegment } from "../types.js";
 import type { HandleStore } from "../server/handle-store.js";
-import type { SegmentHandleData } from "./types.js";
+import type { HandleOwners, SegmentHandleData } from "./types.js";
 type HandleRecord = Record<string, SegmentHandleData>;
-export declare function encodeHandles(handles: HandleRecord): Promise<string>;
+/**
+ * `onError` reaches the Flight encode (see serializeResult). A cache writer
+ * passes the collector it gives the value's encode, so a handle value that
+ * fails to encode (a rejected pushed promise) refuses the whole entry like a
+ * failed value does; prerender (prerender-match.ts) passes one too and
+ * hands the error to its prerender.onError policy.
+ */
+export declare function encodeHandles(handles: HandleRecord, onError?: (error: unknown) => void): Promise<string>;
 export declare function decodeHandles(encoded: string): Promise<HandleRecord | null>;
-export declare function encodeHandleValue(value: unknown): Promise<string>;
+export declare function encodeHandleValue(value: unknown, onError?: (error: unknown) => void): Promise<string>;
 /**
  * Decode a Flight-encoded handle-data string. Returns null on any decode
  * failure so the caller can skip handle restore without discarding valid
@@ -22,18 +29,51 @@ export declare function decodeHandleValue<T>(encoded: string): Promise<T | null>
  * Capture handle data for a set of segments from the handle store.
  * Used when caching segments to preserve their handle data.
  *
- * `exclude` (shell captures: RequestContext._shellCaptureLoaderHandleValues)
- * drops DSL-loader-scoped push values from the CACHE WRITE only: loaders
- * re-run fresh on every HIT, so replaying their captured values would
- * duplicate the fresh push — and their masked nested promises would stall the
- * Flight handle encode to its timeout. Threaded as an explicit argument so
- * every other getDataForSegment consumer (the render-barrier snapshot,
- * prerender) provably sees every push.
+ * 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
+ * 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
+ * time, so primitive values are covered. A PPR shell capture untags the
+ * settled bake-lane pushes its record keeps (shell-capture.ts) and gives
+ * them an owner (captureHandleOwners). Only this call site passes
+ * excludeLoaderPushes; every other getDataForSegment consumer (the
+ * render-barrier snapshot, prerender) sees every push.
  */
-export declare function captureHandles(segments: ResolvedSegment[], handleStore: HandleStore, exclude?: WeakSet<object>): Record<string, SegmentHandleData>;
+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;
 /**
  * Restore handle data from a cached snapshot into the handle store.
- * Used when serving cached segments to replay their handle data.
+ * Used when serving cached segments to replay their handle data: a route
+ * cache() record owns its segments' arrays, so it REPLACES them.
+ *
+ * A segment with `owners` is replaced with empty arrays and re-pushed in
+ * recorded order, an owned value through pushReplayed: the owning loader
+ * re-runs on the HIT (loaders stay live), and its live pushes replace the
+ * recorded ones in place instead of appending a second copy. `claim`
+ * (setupLoaderAccess _claimLoaderPushes) is asked once per owner, so the
+ * loader's own cache() HIT does not replay its pushes a second time
+ * (loader-cache.ts replayLoaderHandles); an owner it refuses is skipped. A
+ * record without owners restores as a plain replay.
+ */
+export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, owners?: HandleOwners, claim?: (loaderId: string) => boolean): 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
+ * a cached unit that shares its segments with live pushes ("use cache");
+ * restoreHandles would wipe those. `segmentId` redirects every value to one
+ * segment (the caller's).
+ *
+ * Owner-keyed groups (useCacheRecordKey, `${seq}:${loaderId}`) are a loader's
+ * pushes, which reach the page once per request: `claim` (setupLoaderAccess
+ * _claimLoaderPushes) skips a loader that already ran or was replayed in this
+ * request, and a claimed loader that runs later replaces its replayed values
+ * (HandleStore.pushReplayed). `${seq}:` groups are the function's own pushes.
+ * A key without ":" is a segment id (records written before owner keys) and
+ * replays unchanged. A loader's own cache() replays through loader-cache.ts
+ * replayLoaderHandles.
  */
-export declare function restoreHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore): void;
+export declare function appendHandles(handles: Record<string, SegmentHandleData>, handleStore: HandleStore, segmentId?: string, claim?: (loaderId: string) => boolean): void;
 export {};

package/dist/types/cache/segment-codec.d.ts

@@ -23,7 +23,7 @@ export declare function stringToStream(str: string): ReadableStream<Uint8Array>;
  * For contexts where null is a valid result (loader caching, "use cache"),
  * use serializeResult() instead which preserves null through RSC Flight.
  */
-export declare function rscSerialize(value: unknown): Promise<string | undefined>;
+export declare function rscSerialize(value: unknown, onError?: (error: unknown) => void): Promise<string | undefined>;
 /**
  * RSC-deserialize a value from a stored string.
  */
@@ -36,7 +36,7 @@ export declare function rscDeserialize<T>(encoded: string | undefined): Promise<
  *
  * Returns null only on serialization failure.
  */
-export declare function serializeResult(value: unknown): Promise<string | null>;
+export declare function serializeResult(value: unknown, onError?: (error: unknown) => void): Promise<string | null>;
 /**
  * RSC-deserialize a cached result string.
  * Counterpart to serializeResult() — always receives a non-empty string.
@@ -52,8 +52,15 @@ export declare const deserializeComponent: (encoded: string) => Promise<unknown>
  * Serialize segments for storage.
  * Each segment's component, layout, loading, and loaderData are RSC-serialized.
  * Metadata is preserved as-is.
+ *
+ * `onError` goes to every Flight encode. A component that throws while
+ * encoding (e.g. an async server component in the tree) does not reject the
+ * encode: Flight reports it through onError and writes an error row
+ * (`1:E{...}`) that throws when the decoded tree renders. cacheRoute and the
+ * prerender producers (prerender-match.ts) pass it to refuse such an entry;
+ * without it the encode is unchanged.
  */
-export declare function serializeSegments(segments: ResolvedSegment[]): Promise<SerializedSegmentData[]>;
+export declare function serializeSegments(segments: ResolvedSegment[], onError?: (error: unknown) => void): Promise<SerializedSegmentData[]>;
 /**
  * Build ResolvedSegments that carry the STORED fragment strings verbatim
  * instead of decoding them (PPR fast-path payload splice, issue #700; see

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

@@ -1,7 +1,7 @@
 /**
  * Taint symbol for request-scoped objects.
  *
- * Objects branded with NOCACHE_SYMBOL (ctx, env, req) are excluded from
+ * Objects branded with NOCACHE_SYMBOL (ctx objects) are excluded from
  * "use cache" cache keys and trigger handle capture mode so that side
  * effects (breadcrumbs, metadata) are recorded and replayed on cache hit.
  */