vinext 1.0.0-beta.9 → 1.0.0

package/dist/server/worker-utils.d.ts

@@ -1,10 +1,9 @@
 //#region src/server/worker-utils.d.ts
-declare function finalizeMissingStaticAssetResponse(response: Response, missingBuildAsset: boolean): Response;
-declare function mergeHeaders(response: Response, extraHeaders: Record<string, string | string[]>, statusOverride?: number): Response;
-declare function resolveStaticAssetSignal(signalResponse: Response, options: {
+export declare function finalizeMissingStaticAssetResponse(response: Response, missingBuildAsset: boolean): Response;
+export declare function mergeHeaders(response: Response, extraHeaders: Record<string, string | string[]>, statusOverride?: number): Response;
+export declare function resolveStaticAssetSignal(signalResponse: Response, options: {
   fetchAsset(path: string): Promise<Response>;
 }): Promise<Response | null>;
 /** Retarget a Worker asset request without dropping its conditional/range fields. */
-declare function createStaticAssetRequest(assetPath: string, sourceRequest: Request): Request;
-//#endregion
-export { createStaticAssetRequest, finalizeMissingStaticAssetResponse, mergeHeaders, resolveStaticAssetSignal };
+export declare function createStaticAssetRequest(assetPath: string, sourceRequest: Request): Request;
+//#endregion

package/dist/server/worker-utils.js

@@ -94,7 +94,8 @@ async function resolveStaticAssetSignal(signalResponse, options) {
 	const extraHeaders = buildHeaderRecord(signalResponse, [
 		"content-encoding",
 		"content-length",
-		"content-type"
+		"content-type",
+		"transfer-encoding"
 	]);
 	cancelResponseBody(signalResponse);
 	const assetResponse = await options.fetchAsset(assetPath);

package/dist/server/workers-tracing.d.ts

@@ -0,0 +1,17 @@
+import { FrameworkTracingIntegration } from "./framework-tracer.js";
+//#region src/server/workers-tracing.d.ts
+export type WorkersTracingException = string | {
+  name: string;
+  message: string;
+  stack?: string;
+};
+export type WorkersTracingSpan = {
+  readonly isTraced: boolean;
+  recordException?(exception: WorkersTracingException): void;
+  setAttribute(key: string, value: boolean | number | string): void;
+};
+export type WorkersTracing = {
+  enterSpan<T>(name: string, callback: (span: WorkersTracingSpan) => T): T;
+};
+export declare function createWorkersTracingIntegration(tracing: WorkersTracing): FrameworkTracingIntegration;
+//#endregion

package/dist/server/workers-tracing.js

@@ -0,0 +1,27 @@
+//#region src/server/workers-tracing.ts
+function normalizeException(error) {
+	if (typeof error === "string") return error;
+	if (error instanceof Error) return {
+		message: error.message,
+		name: error.name,
+		...error.stack ? { stack: error.stack } : {}
+	};
+	return String(error);
+}
+function createWorkersTracingIntegration(tracing) {
+	const backendSpan = (span) => ({
+		recordException: (error) => span.recordException?.(normalizeException(error)),
+		setAttribute: (key, value) => span.setAttribute(key, value)
+	});
+	return {
+		id: "cloudflare-workers",
+		enterSpan(descriptor, callback) {
+			return tracing.enterSpan(descriptor.name, (span) => {
+				for (const [key, value] of Object.entries(descriptor.attributes)) span.setAttribute(key, value);
+				return callback(backendSpan(span));
+			});
+		}
+	};
+}
+//#endregion
+export { createWorkersTracingIntegration };

package/dist/shims/amp.d.ts

@@ -9,11 +9,10 @@
  * Check if the current page is being served as AMP.
  * Always returns false — AMP is not supported.
  */
-declare function useAmp(): boolean;
+export declare function useAmp(): boolean;
 /**
  * Check if AMP is enabled for the current page.
  * Always returns false.
  */
-declare function isInAmpMode(): boolean;
-//#endregion
-export { isInAmpMode, useAmp };
+export declare function isInAmpMode(): boolean;
+//#endregion

package/dist/shims/app-router-scroll-state.d.ts

@@ -1,17 +1,16 @@
 //#region src/shims/app-router-scroll-state.d.ts
-type AppRouterScrollIntent = Readonly<{
+export type AppRouterScrollIntent = Readonly<{
   commitId: number | null;
   hash: string | null;
   headElements: ReadonlySet<Element> | null;
   id: number;
   targetHoistedInHead: boolean;
 }>;
-declare function beginAppRouterScrollIntent(hash: string | null): AppRouterScrollIntent;
-declare function clearAppRouterScrollIntent(): void;
-declare function getPendingAppRouterScrollIntent(): AppRouterScrollIntent | null;
-declare function isLatestAppRouterScrollIntent(expected: AppRouterScrollIntent | null | undefined): boolean;
-declare function claimAppRouterScrollIntentForCommit(expected: AppRouterScrollIntent | null | undefined, commitId: number): void;
-declare function markAppRouterScrollIntentHeadHoisted(expected: AppRouterScrollIntent | null | undefined, commitId: number): void;
-declare function consumeAppRouterScrollIntent(expected: AppRouterScrollIntent | null | undefined, commitId?: number): AppRouterScrollIntent | null;
-//#endregion
-export { AppRouterScrollIntent, beginAppRouterScrollIntent, claimAppRouterScrollIntentForCommit, clearAppRouterScrollIntent, consumeAppRouterScrollIntent, getPendingAppRouterScrollIntent, isLatestAppRouterScrollIntent, markAppRouterScrollIntentHeadHoisted };
+export declare function beginAppRouterScrollIntent(hash: string | null): AppRouterScrollIntent;
+export declare function clearAppRouterScrollIntent(): void;
+export declare function getPendingAppRouterScrollIntent(): AppRouterScrollIntent | null;
+export declare function isLatestAppRouterScrollIntent(expected: AppRouterScrollIntent | null | undefined): boolean;
+export declare function claimAppRouterScrollIntentForCommit(expected: AppRouterScrollIntent | null | undefined, commitId: number): void;
+export declare function markAppRouterScrollIntentHeadHoisted(expected: AppRouterScrollIntent | null | undefined, commitId: number): void;
+export declare function consumeAppRouterScrollIntent(expected: AppRouterScrollIntent | null | undefined, commitId?: number): AppRouterScrollIntent | null;
+//#endregion

package/dist/shims/app-router-scroll.d.ts

@@ -1,6 +1,6 @@
 import * as React$1 from "react";
 //#region src/shims/app-router-scroll.d.ts
-declare class AppRouterScrollTargetInner extends React$1.Component<{
+export declare class AppRouterScrollTargetInner extends React$1.Component<{
   children: React$1.ReactNode;
   commitId: number | null;
 }> {
@@ -12,12 +12,11 @@ declare class AppRouterScrollTargetInner extends React$1.Component<{
   componentWillUnmount(): void;
   render(): React$1.ReactNode;
 }
-declare function AppRouterScrollCommitProvider({ children, commitId }: {
+export declare function AppRouterScrollCommitProvider({ children, commitId }: {
   children?: React$1.ReactNode;
   commitId: number | null;
 }): React$1.JSX.Element;
-declare function AppRouterScrollTarget({ children }: {
+export declare function AppRouterScrollTarget({ children }: {
   children: React$1.ReactNode;
 }): React$1.JSX.Element;
-//#endregion
-export { AppRouterScrollCommitProvider, AppRouterScrollTarget, AppRouterScrollTargetInner };
+//#endregion

package/dist/shims/app-router-scroll.js

@@ -133,8 +133,9 @@ function AppRouterScrollCommitProvider({ children, commitId }) {
 	});
 }
 function AppRouterScrollTarget({ children }) {
+	const commitId = React$1.useContext(AppRouterScrollCommitContext);
 	return /* @__PURE__ */ jsx(AppRouterScrollTargetInner, {
-		commitId: React$1.useContext(AppRouterScrollCommitContext),
+		commitId,
 		children
 	});
 }

package/dist/shims/app.d.ts

@@ -1,6 +1,6 @@
 import React, { ComponentType } from "react";
 //#region src/shims/app.d.ts
-type AppProps<P = any> = {
+export type AppProps<P = any> = {
   Component: ComponentType<P> & {
     getInitialProps?: (ctx: any) => any;
   };
@@ -13,7 +13,7 @@ type AppProps<P = any> = {
  * The context passed to `App.getInitialProps`. Mirrors Next.js's
  * `AppContextType` from `packages/next/src/shared/lib/utils.ts`.
  */
-type AppContext = {
+export type AppContext = {
   Component: ComponentType<any> & {
     getInitialProps?: (ctx: any) => any;
   };
@@ -25,14 +25,13 @@ type AppContext = {
  * The initial props shape returned by `App.getInitialProps`. Mirrors
  * Next.js's `AppInitialProps` from `packages/next/src/shared/lib/utils.ts`.
  */
-type AppInitialProps<PageProps = any> = {
+export type AppInitialProps<PageProps = any> = {
   pageProps: PageProps;
 };
 declare function appGetInitialProps({ Component, ctx }: AppContext): Promise<AppInitialProps>;
-declare class App<P = any, CP = any, S = any> extends React.Component<P & AppProps<CP>, S> {
+export default class App<P = any, CP = any, S = any> extends React.Component<P & AppProps<CP>, S> {
   static origGetInitialProps: typeof appGetInitialProps;
   static getInitialProps: typeof appGetInitialProps;
   render(): React.ReactElement;
 }
-//#endregion
-export { AppContext, AppInitialProps, AppProps, App as default };
+//#endregion

package/dist/shims/before-interactive-context.d.ts

@@ -15,7 +15,7 @@ import React from "react";
  * (`(self.__next_s=...).push(...)`). An entry has `src` set for external
  * scripts and `innerHTML` set for inline scripts (never both).
  */
-type BeforeInteractiveInlineScript = {
+export type BeforeInteractiveInlineScript = {
   /** Optional id attribute. */
   id?: string;
   /** External script URL. Set for src beforeInteractive scripts. */
@@ -35,8 +35,7 @@ type BeforeInteractiveInlineScript = {
    */
   attributes?: Record<string, string | boolean>;
 };
-type RegisterBeforeInteractiveInlineScript = (script: BeforeInteractiveInlineScript) => void;
-declare const BeforeInteractiveContext: React.Context<RegisterBeforeInteractiveInlineScript | null>;
-declare function useBeforeInteractiveRegister(): RegisterBeforeInteractiveInlineScript | null;
-//#endregion
-export { BeforeInteractiveContext, BeforeInteractiveInlineScript, RegisterBeforeInteractiveInlineScript, useBeforeInteractiveRegister };
+export type RegisterBeforeInteractiveInlineScript = (script: BeforeInteractiveInlineScript) => void;
+export declare const BeforeInteractiveContext: React.Context<RegisterBeforeInteractiveInlineScript | null>;
+export declare function useBeforeInteractiveRegister(): RegisterBeforeInteractiveInlineScript | null;
+//#endregion

package/dist/shims/cache-callable-runtime.d.ts

@@ -1,3 +1,4 @@
+import { VinextCacheFunctionInvocation } from "../server/multi-stage.js";
 import { RegisterCachedFunctionOptions } from "./cache-runtime.js";
 //#region src/shims/cache-callable-runtime.d.ts
 declare const CACHE_CAPTURE_TYPE = "use-cache-captures";
@@ -5,7 +6,46 @@ type CacheCaptureEnvelope = {
   type: typeof CACHE_CAPTURE_TYPE;
   encrypted: string | PromiseLike<string>;
 };
-declare function encryptCacheCaptures(captures: unknown[]): CacheCaptureEnvelope;
-declare function registerCachedFunction<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, id: string, variant: string, options: RegisterCachedFunctionOptions): (...args: TArgs) => Promise<TResult>;
-//#endregion
-export { encryptCacheCaptures, registerCachedFunction };
+/**
+ * Flight serializes a promise as its resolved value and drops its own fields.
+ * Next.js params are promises that also expose their resolved fields, and the
+ * cache key is built from those fields, so the payload carries each such
+ * promise's fields next to the arguments and decoding assigns them back.
+ */
+type EncodedCacheArguments = {
+  args: unknown[];
+  thenableObjects: EncodedThenableObject[];
+};
+/**
+ * Flight writes each object once, so `promise` decodes to the same promise as
+ * every other reference to it, including ones inside resolved values, and the
+ * fields share references with the arguments. The fields build the cache key;
+ * the resolved value can differ: the params proxy hides params named like
+ * promise or React fields (`value`, `status`) from its own keys but still
+ * resolves to them.
+ */
+type EncodedThenableObject = {
+  fields: Record<string, unknown>;
+  promise: PromiseLike<unknown>;
+};
+export declare function encryptCacheCaptures(captures: unknown[]): CacheCaptureEnvelope;
+/**
+ * What to do when a read would run a getter: `reject` throws
+ * `UnreplayableCacheArgumentsError`, `skip` leaves the getter unread.
+ */
+type GetterHandling = "reject" | "skip";
+/**
+ * Collect the own fields of every promise-augmented object in the arguments,
+ * including ones inside resolved promise values. The arguments are passed to
+ * Flight as they are, so Flight keeps their shared references and cycles.
+ * With `getters: "reject"`, throws `UnreplayableCacheArgumentsError` when the
+ * arguments hold a getter; with `"skip"`, promise fields behind a getter are
+ * not recorded.
+ */
+export declare function encodeCacheArguments(args: unknown[], getters?: GetterHandling): Promise<EncodedCacheArguments>;
+/** Restore the promise fields that `encodeCacheArguments` captured before Flight encoding. */
+export declare function decodeCacheArguments(value: unknown): unknown[];
+export declare function registerCachedFunction<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, id: string, variant: string, options: RegisterCachedFunctionOptions): (...args: TArgs) => Promise<TResult>;
+/** Load and invoke one transformed cache function through its server-reference identity. */
+export declare function invokeCacheFunction(invocation: VinextCacheFunctionInvocation, loadServerAction: (id: string) => Promise<unknown>): Promise<void>;
+//#endregion

package/dist/shims/cache-callable-runtime.js

@@ -1,30 +1,190 @@
-import { registerCachedFunction as registerCachedFunction$1 } from "./cache-runtime.js";
+import { isThenableObject, isUseCacheFunction, registerCachedFunction as registerCachedFunction$1 } from "./cache-runtime.js";
 import { decryptActionBoundArgs, encryptActionBoundArgs } from "@vitejs/plugin-rsc/utils/encryption-runtime";
 //#region src/shims/cache-callable-runtime.ts
 const CACHE_CAPTURE_TYPE = "use-cache-captures";
 function encryptCacheCaptures(captures) {
 	return {
 		type: CACHE_CAPTURE_TYPE,
-		encrypted: encryptActionBoundArgs(captures)
+		encrypted: encryptCaptures(captures)
 	};
 }
 async function decryptCacheCaptures(value) {
 	if (!isCacheCaptureEnvelope(value)) return;
-	const captures = await decryptActionBoundArgs(Promise.resolve(value.encrypted));
-	if (!Array.isArray(captures)) throw new Error("Invalid cache capture payload");
-	return captures;
+	return decryptCacheArguments(value.encrypted);
+}
+async function encryptCaptures(captures) {
+	return encryptActionBoundArgs(await encodeCacheArguments(captures, "skip"));
+}
+async function encryptCacheArguments(args) {
+	return encryptActionBoundArgs(await encodeCacheArguments(args));
+}
+async function decryptCacheArguments(encrypted) {
+	return decodeCacheArguments(await decryptActionBoundArgs(Promise.resolve(encrypted)));
+}
+function isThenable(value) {
+	return "then" in value && typeof value.then === "function";
+}
+function isPlainRecord(value) {
+	const prototype = Object.getPrototypeOf(value);
+	return (prototype === Object.prototype || prototype === null) && !("$$typeof" in value);
+}
+/**
+* The arguments hold a getter. Flight reads it again while serializing, and a
+* getter can return a different value, such as a new promise, on every read,
+* so the recorded promise fields may not match what Flight serializes.
+*/
+var UnreplayableCacheArgumentsError = class extends Error {
+	constructor() {
+		super("Cache function arguments with getters cannot be replayed");
+	}
+};
+/**
+* The own entries of `value` that Flight serializes: every index below an
+* array's `length`, including holes and non-enumerable indices, as
+* `JSON.stringify` reads them, and the enumerable own keys of anything else.
+* A getter, own or inherited through an array hole, is never run.
+*/
+function ownEntries(value, getters) {
+	const keys = Array.isArray(value) ? Array.from({ length: value.length }, (_, index) => String(index)) : Object.keys(value);
+	const entries = [];
+	for (const key of keys) {
+		if (readsGetter(value, key)) {
+			if (getters === "reject") throw new UnreplayableCacheArgumentsError();
+			continue;
+		}
+		entries.push([key, Reflect.get(value, key)]);
+	}
+	return entries;
+}
+/**
+* Whether reading `key` from `value` runs a getter. An array hole reads
+* through the prototype chain, which can hold an indexed data property or
+* accessor. A setter-only accessor reads as `undefined` without running code.
+*/
+function readsGetter(value, key) {
+	for (let target = value; target !== null; target = Reflect.getPrototypeOf(target)) {
+		const descriptor = Reflect.getOwnPropertyDescriptor(target, key);
+		if (descriptor) return typeof descriptor.get === "function";
+	}
+	return false;
+}
+/** Members of the values Flight serializes recursively, which can hold params. */
+function flightMembers(value, getters) {
+	if (value instanceof Map) return [...value].flat();
+	if (value instanceof Set) return [...value];
+	if (isThenableObject(value) || Array.isArray(value) || isPlainRecord(value)) return ownEntries(value, getters).map(([, member]) => member);
+	return [];
+}
+/**
+* Collect the own fields of every promise-augmented object in the arguments,
+* including ones inside resolved promise values. The arguments are passed to
+* Flight as they are, so Flight keeps their shared references and cycles.
+* With `getters: "reject"`, throws `UnreplayableCacheArgumentsError` when the
+* arguments hold a getter; with `"skip"`, promise fields behind a getter are
+* not recorded.
+*/
+async function encodeCacheArguments(args, getters = "reject") {
+	const settled = /* @__PURE__ */ new Map();
+	for (;;) {
+		const thenableObjects = [];
+		const unsettled = [];
+		const visited = /* @__PURE__ */ new Set();
+		const pending = [args];
+		while (pending.length > 0) {
+			const value = pending.pop();
+			if (typeof value !== "object" || value === null || visited.has(value)) continue;
+			visited.add(value);
+			const children = flightMembers(value, getters);
+			if (isThenableObject(value)) {
+				const fields = Object.fromEntries(ownEntries(value, getters));
+				thenableObjects.push({
+					fields,
+					promise: value
+				});
+			}
+			if (isThenable(value)) {
+				const result = settled.get(value);
+				if (!result) unsettled.push(value);
+				else if (result.status === "fulfilled") children.push(result.value);
+			}
+			for (const child of children) pending.push(child);
+		}
+		if (unsettled.length === 0) return {
+			args,
+			thenableObjects
+		};
+		const results = await Promise.allSettled(unsettled);
+		unsettled.forEach((thenable, index) => settled.set(thenable, results[index]));
+	}
+}
+/** Restore the promise fields that `encodeCacheArguments` captured before Flight encoding. */
+function decodeCacheArguments(value) {
+	if (typeof value !== "object" || value === null || !("args" in value) || !Array.isArray(value.args) || !("thenableObjects" in value) || !Array.isArray(value.thenableObjects)) throw new Error("Invalid cache function arguments");
+	adoptFlightThenables(value);
+	for (const thenableObject of value.thenableObjects) {
+		if (!isEncodedThenableObject(thenableObject)) throw new Error("Invalid cache function arguments");
+		Object.assign(thenableObject.promise, thenableObject.fields);
+	}
+	return value.args;
+}
+function isEncodedThenableObject(value) {
+	if (typeof value !== "object" || value === null || !isPlainRecord(value)) return false;
+	const { fields, promise } = value;
+	return typeof fields === "object" && fields !== null && isPlainRecord(fields) && promise instanceof Promise;
+}
+/**
+* Flight decodes promises as React chunks whose own fields are React's
+* internal state. Adopt them into native promises, which have no own fields,
+* so key serialization sees a promise exactly as the original call did.
+* Flight shares one chunk between references to the same promise, so each
+* chunk is adopted once, including references inside resolved values.
+*/
+function adoptFlightThenables(value, adopted = /* @__PURE__ */ new WeakMap()) {
+	if (typeof value !== "object" || value === null) return value;
+	if (adopted.has(value)) return adopted.get(value);
+	if (isThenable(value)) {
+		const promise = Promise.resolve(value).then((resolved) => adoptFlightThenables(resolved, adopted));
+		promise.catch(() => {});
+		adopted.set(value, promise);
+		return promise;
+	}
+	if (value instanceof Map) {
+		adopted.set(value, value);
+		const entries = [...value];
+		value.clear();
+		for (const [key, item] of entries) value.set(adoptFlightThenables(key, adopted), adoptFlightThenables(item, adopted));
+		return value;
+	}
+	if (value instanceof Set) {
+		adopted.set(value, value);
+		const items = [...value];
+		value.clear();
+		for (const item of items) value.add(adoptFlightThenables(item, adopted));
+		return value;
+	}
+	if (!Array.isArray(value) && !isPlainRecord(value)) return value;
+	adopted.set(value, value);
+	for (const key of Object.keys(value)) Reflect.set(value, key, adoptFlightThenables(Reflect.get(value, key), adopted));
+	return value;
 }
 function isCacheCaptureEnvelope(value) {
 	if (typeof value !== "object" || value === null) return false;
 	if (!("type" in value) || value.type !== CACHE_CAPTURE_TYPE || !("encrypted" in value)) return false;
 	const encrypted = value.encrypted;
-	return typeof encrypted === "string" || typeof encrypted === "object" && encrypted !== null && "then" in encrypted && typeof encrypted.then === "function";
+	return typeof encrypted === "string" || typeof encrypted === "object" && encrypted !== null && isThenable(encrypted);
 }
 function registerCachedFunction(fn, id, variant, options) {
 	return registerCachedFunction$1(fn, id, variant, {
 		...options,
-		decryptCaptures: decryptCacheCaptures
+		decryptCaptures: decryptCacheCaptures,
+		encodeInvocationArgs: encryptCacheArguments
 	});
 }
+/** Load and invoke one transformed cache function through its server-reference identity. */
+async function invokeCacheFunction(invocation, loadServerAction) {
+	const fn = await loadServerAction(invocation.referenceId);
+	if (!isUseCacheFunction(fn)) throw new Error(`Server reference ${invocation.referenceId} is not a cache function`);
+	await fn(...await decryptCacheArguments(invocation.encryptedArgs));
+}
 //#endregion
-export { encryptCacheCaptures, registerCachedFunction };
+export { decodeCacheArguments, encodeCacheArguments, encryptCacheCaptures, invokeCacheFunction, registerCachedFunction };

package/dist/shims/cache-for-request.d.ts

@@ -52,6 +52,5 @@
  *   factories. Async factories that reject have their cache cleared, allowing retry.
  * @returns A function with the same return type that caches the result per request.
  */
-declare function cacheForRequest<T>(factory: () => T): () => T;
-//#endregion
-export { cacheForRequest };
+export declare function cacheForRequest<T>(factory: () => T): () => T;
+//#endregion

package/dist/shims/cache-handler.d.ts

@@ -1,13 +1,13 @@
 import { RenderObservation } from "../server/cache-proof.js";
 //#region src/shims/cache-handler.d.ts
-type CacheHandlerValue = {
+export type CacheHandlerValue = {
   lastModified: number;
   age?: number;
   cacheState?: string;
   cacheControl?: CacheControlMetadata;
   value: IncrementalCacheValue | null;
 };
-type CacheControlMetadata = {
+export type CacheControlMetadata = {
   revalidate: number | false;
   expire?: number;
   /**
@@ -17,8 +17,8 @@ type CacheControlMetadata = {
    */
   stale?: number;
 };
-type IncrementalCacheValue = CachedFetchValue | CachedAppPageValue | CachedPagesValue | CachedRouteValue | CachedRedirectValue | CachedImageValue;
-type CachedFetchValue = {
+export type IncrementalCacheValue = CachedFetchValue | CachedAppPageValue | CachedPagesValue | CachedRouteValue | CachedRedirectValue | CachedImageValue;
+export type CachedFetchValue = {
   kind: "FETCH";
   data: {
     headers: Record<string, string>;
@@ -29,16 +29,23 @@ type CachedFetchValue = {
   tags?: string[];
   revalidate: number | false;
 };
-type CachedAppPageValue = {
+export type CachedAppPageValue = {
   kind: "APP_PAGE";
   html: string;
   rscData: ArrayBuffer | undefined;
   headers: Record<string, string | string[]> | undefined;
   postponed: string | undefined;
+  /**
+   * Set by a read-only adapter whose entries are build-time prerenders. A
+   * prerender that reads the query is skipped as dynamic, so such an entry
+   * serves every query without a render observation, as Next.js serves its
+   * static output.
+   */
+  prerendered?: true;
   renderObservation?: RenderObservation;
   status: number | undefined;
 };
-type CachedPagesValue = {
+export type CachedPagesValue = {
   kind: "PAGES";
   html: string;
   pageData: object;
@@ -46,30 +53,30 @@ type CachedPagesValue = {
   headers: Record<string, string | string[]> | undefined;
   status: number | undefined;
 };
-type CachedRouteValue = {
+export type CachedRouteValue = {
   kind: "APP_ROUTE";
   body: ArrayBuffer;
   status: number;
   headers: Record<string, string | string[]>;
 };
-type CachedRedirectValue = {
+export type CachedRedirectValue = {
   kind: "REDIRECT";
   props: object;
 };
-type CachedImageValue = {
+export type CachedImageValue = {
   kind: "IMAGE";
   etag: string;
   buffer: ArrayBuffer;
   extension: string;
   revalidate?: number;
 };
-type CacheHandlerContext = {
+export type CacheHandlerContext = {
   dev?: boolean;
   maxMemoryCacheSize?: number;
   revalidatedTags?: string[];
   [key: string]: unknown;
 };
-type CacheHandler = {
+export type CacheHandler = {
   get(key: string, ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
   set(key: string, data: IncrementalCacheValue | null, ctx?: Record<string, unknown>): Promise<void>;
   revalidateTag(tags: string | string[], durations?: {
@@ -77,7 +84,7 @@ type CacheHandler = {
   }): Promise<void>;
   resetRequestCache?(): void;
 };
-declare class NoOpCacheHandler implements CacheHandler {
+export declare class NoOpCacheHandler implements CacheHandler {
   get(_key: string, _ctx?: Record<string, unknown>): Promise<CacheHandlerValue | null>;
   set(_key: string, _data: IncrementalCacheValue | null, _ctx?: Record<string, unknown>): Promise<void>;
   revalidateTag(_tags: string | string[], _durations?: {
@@ -87,7 +94,7 @@ declare class NoOpCacheHandler implements CacheHandler {
 type MemoryCacheHandlerOptions = Pick<CacheHandlerContext, "maxMemoryCacheSize"> & {
   cacheMaxMemorySize?: number;
 };
-declare class MemoryCacheHandler implements CacheHandler {
+export declare class MemoryCacheHandler implements CacheHandler {
   private store;
   private tagRevalidatedAt;
   private readonly maxMemoryCacheSize;
@@ -102,10 +109,16 @@ declare class MemoryCacheHandler implements CacheHandler {
   revalidateTag(tags: string | string[]): Promise<void>;
   resetRequestCache(): void;
 }
-declare function configureMemoryCacheHandler(options?: MemoryCacheHandlerOptions): void;
-declare function setDataCacheHandler(handler: CacheHandler): void;
-declare function getDataCacheHandler(): CacheHandler;
-declare function setCacheHandler(handler: CacheHandler): void;
-declare function getCacheHandler(): CacheHandler;
-//#endregion
-export { CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, setCacheHandler, setDataCacheHandler };
+export declare function configureMemoryCacheHandler(options?: MemoryCacheHandlerOptions): void;
+export declare function setDataCacheHandler(handler: CacheHandler): void;
+/**
+ * Lazily keep the first declaratively configured handler shared across
+ * duplicated stage modules. Imperative setters remain able to replace it.
+ */
+export declare function registerDataCacheHandler(factory: () => CacheHandler): void;
+/** Register a lightweight proxy that imports the configured handler on first use. */
+export declare function registerLazyDataCacheHandler(load: () => Promise<void>): void;
+export declare function getDataCacheHandler(): CacheHandler;
+export declare function setCacheHandler(handler: CacheHandler): void;
+export declare function getCacheHandler(): CacheHandler;
+//#endregion