vinext 1.0.0-beta.8 → 1.0.0

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

@@ -0,0 +1,43 @@
+import { VinextResponseStageCacheability, VinextResponseStageTransport } from "./multi-stage.js";
+import { PagesRenderOptions } from "./pages-request-pipeline.js";
+//#region src/server/worker-stages.d.ts
+export declare const PAGES_RESPONSE_STAGE_PROTOCOL_VERSION = 4;
+export declare const PAGES_RESPONSE_STAGE_POLICY_OWNER_HEADER = "x-vinext-pages-response-stage-policy-owner";
+export type PagesResponseStagePolicyOwner = "request-time" | "static";
+type PagesResponseStageEnvelope = {
+  buildId: string | null;
+  cacheability: VinextResponseStageCacheability;
+  protocolVersion: typeof PAGES_RESPONSE_STAGE_PROTOCOL_VERSION;
+  /** Host is explicit because multi-tenant/domain-i18n renders vary by it. */
+  requestHost: string;
+  /** Complete response-header snapshot installed before Pages user code runs. */
+  stagedHeaders: Array<[string, string]> | null;
+};
+/** Serializable Pages page render delegated to a cacheable Worker stage. */
+type PagesPageResponseStageProps = PagesResponseStageEnvelope & {
+  kind: "pages-page";
+  renderOptions: PagesRenderOptions | null;
+  resolvedUrl: string;
+};
+/** Serializable Pages API dispatch delegated to a cacheable Worker stage. */
+type PagesApiResponseStageProps = PagesResponseStageEnvelope & {
+  apiUrl: string;
+  kind: "pages-api";
+};
+/** Authenticated staged-worker path discovery delegated outside the shared cache. */
+type PagesPrerenderDiscoveryStageProps = PagesResponseStageEnvelope & {
+  kind: "pages-prerender-discovery";
+};
+/** Serializable description of work delegated to a cacheable Worker stage. */
+export type WorkerResponseStageProps = PagesApiResponseStageProps | PagesPageResponseStageProps | PagesPrerenderDiscoveryStageProps;
+/**
+ * Host-owned transport for invoking a response stage.
+ *
+ * Core request pipelines decide what may be shared and provide the complete
+ * serialized render identity here. Response-only middleware/config state is
+ * carried in the props so Pages user code observes the same pre-handler
+ * response as Next.js.
+ */
+export type DispatchWorkerResponseStage = VinextResponseStageTransport<WorkerResponseStageProps>;
+export declare function isPagesResponseStageProps(value: unknown): value is WorkerResponseStageProps;
+//#endregion

package/dist/server/worker-stages.js

@@ -0,0 +1,25 @@
+//#region src/server/worker-stages.ts
+const PAGES_RESPONSE_STAGE_PROTOCOL_VERSION = 4;
+const PAGES_RESPONSE_STAGE_POLICY_OWNER_HEADER = "x-vinext-pages-response-stage-policy-owner";
+function isSerializedHeaders(value) {
+	return Array.isArray(value) && value.every((entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && typeof entry[1] === "string");
+}
+function isResponseStageCacheability(value) {
+	if (!value || typeof value !== "object") return false;
+	const cacheability = value;
+	return (cacheability.probeMode === null || cacheability.probeMode === "probe" || cacheability.probeMode === "identity") && (cacheability.policyHeaders === null || Array.isArray(cacheability.policyHeaders) && cacheability.policyHeaders.every((entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string" && typeof entry[1] === "string")) && (cacheability.representation === void 0 || cacheability.representation === "app-route" || cacheability.representation === "html" || cacheability.representation === "pages-data" || cacheability.representation === "rsc-full" || cacheability.representation === "rsc-loading-shell") && typeof cacheability.resolvedRoutePathname === "string" && cacheability.resolvedRoutePathname.startsWith("/");
+}
+function isPagesResponseStageProps(value) {
+	if (!value || typeof value !== "object") return false;
+	const props = value;
+	if (props.protocolVersion !== 4 || props.buildId !== null && typeof props.buildId !== "string" || !isResponseStageCacheability(props.cacheability) || typeof props.requestHost !== "string" || props.requestHost.length === 0 || props.stagedHeaders !== null && !isSerializedHeaders(props.stagedHeaders)) return false;
+	if (props.kind === "pages-api") return typeof props.apiUrl === "string";
+	if (props.kind === "pages-prerender-discovery") return true;
+	if (props.kind !== "pages-page" || typeof props.resolvedUrl !== "string") return false;
+	if (props.renderOptions === null) return true;
+	if (!props.renderOptions || typeof props.renderOptions !== "object") return false;
+	const options = props.renderOptions;
+	return (options.isDataReq === void 0 || typeof options.isDataReq === "boolean") && (options.renderErrorPageOnMiss === void 0 || typeof options.renderErrorPageOnMiss === "boolean") && (options.originalUrl === void 0 || typeof options.originalUrl === "string");
+}
+//#endregion
+export { PAGES_RESPONSE_STAGE_POLICY_OWNER_HEADER, PAGES_RESPONSE_STAGE_PROTOCOL_VERSION, isPagesResponseStageProps };

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

@@ -1,5 +1,5 @@
-import { VINEXT_STATIC_FILE_HEADER } from "./headers.js";
 import { notFoundStaticAssetResponse } from "./http-error-responses.js";
+import { readStaticFileSignal } from "./static-file-signal.js";
 //#region src/server/worker-utils.ts
 /**
 * Shared utilities for Cloudflare Worker entries.
@@ -83,7 +83,7 @@ function mergeHeaders(response, extraHeaders, statusOverride) {
 	});
 }
 async function resolveStaticAssetSignal(signalResponse, options) {
-	const signal = signalResponse.headers.get(VINEXT_STATIC_FILE_HEADER);
+	const signal = readStaticFileSignal(signalResponse);
 	if (!signal) return null;
 	let assetPath = "/";
 	try {
@@ -92,10 +92,10 @@ async function resolveStaticAssetSignal(signalResponse, options) {
 		assetPath = signal;
 	}
 	const extraHeaders = buildHeaderRecord(signalResponse, [
-		VINEXT_STATIC_FILE_HEADER,
 		"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