@qzsy/vinext 0.1.7

package/dist/server/app-rsc-cache-busting.js

@@ -0,0 +1,206 @@
+import { NEXT_ROUTER_PREFETCH_HEADER, NEXT_ROUTER_SEGMENT_PREFETCH_HEADER, NEXT_ROUTER_STATE_TREE_HEADER, NEXT_URL_HEADER, VINEXT_CLIENT_REUSE_MANIFEST_HEADER, VINEXT_INTERCEPTION_CONTEXT_HEADER, VINEXT_MOUNTED_SLOTS_HEADER, VINEXT_RSC_RENDER_MODE_HEADER } from "./headers.js";
+import { fnv1a64 } from "../utils/hash.js";
+import { parseAppRscRenderMode } from "./app-rsc-render-mode.js";
+import { applyDeploymentIdHeader } from "../utils/deployment-id.js";
+//#region src/server/app-rsc-cache-busting.ts
+/**
+* RSC cache-busting hashes cover the headers that make an RSC payload vary.
+* Client-side variant headers must survive transit through CDNs and reverse
+* proxies; stripping them changes the server hash and turns stale URLs into
+* repeated canonicalization redirects.
+*/
+const VINEXT_RSC_CACHE_BUSTING_SEARCH_PARAM = "_rsc";
+const VINEXT_RSC_COMPATIBILITY_ID_HEADER = "X-Vinext-RSC-Compatibility-Id";
+const VINEXT_RSC_CONTENT_TYPE = "text/x-component";
+const VINEXT_RSC_VARY_HEADER = [
+	"RSC",
+	"Accept",
+	NEXT_ROUTER_STATE_TREE_HEADER,
+	NEXT_ROUTER_PREFETCH_HEADER,
+	NEXT_ROUTER_SEGMENT_PREFETCH_HEADER,
+	NEXT_URL_HEADER,
+	VINEXT_INTERCEPTION_CONTEXT_HEADER,
+	VINEXT_MOUNTED_SLOTS_HEADER,
+	VINEXT_RSC_RENDER_MODE_HEADER
+].join(", ");
+const CACHE_BUSTING_DIGEST_BYTES = 12;
+const textEncoder = new TextEncoder();
+function encodeBase64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function normalizeHeaderValue(value) {
+	return value ?? "0";
+}
+function normalizeCompatibilityId(value) {
+	return value && value.length > 0 ? value : null;
+}
+function getVinextRscCompatibilityId() {
+	return normalizeCompatibilityId(process.env.__VINEXT_RSC_COMPATIBILITY_ID);
+}
+function applyRscCompatibilityIdHeader(headers, compatibilityId = getVinextRscCompatibilityId()) {
+	const normalized = normalizeCompatibilityId(compatibilityId);
+	if (normalized) headers.set(VINEXT_RSC_COMPATIBILITY_ID_HEADER, normalized);
+	else headers.delete(VINEXT_RSC_COMPATIBILITY_ID_HEADER);
+}
+function isRscCompatibilityIdCompatible(responseCompatibilityId, clientCompatibilityId = getVinextRscCompatibilityId()) {
+	const normalizedResponseCompatibilityId = normalizeCompatibilityId(responseCompatibilityId);
+	const normalizedClientCompatibilityId = normalizeCompatibilityId(clientCompatibilityId);
+	return normalizedClientCompatibilityId === null || normalizedResponseCompatibilityId !== null && normalizedResponseCompatibilityId === normalizedClientCompatibilityId;
+}
+function resolveHardNavigationTargetFromRscResponse(responseUrl, currentHref, origin) {
+	if (!responseUrl) return currentHref;
+	const parsed = new URL(responseUrl, origin);
+	stripRscCacheBustingSearchParam(parsed);
+	const origUrl = new URL(currentHref, origin);
+	let pathname = stripRscSuffix(parsed.pathname);
+	if (origUrl.pathname.length > 1 && origUrl.pathname.endsWith("/") && !pathname.endsWith("/")) pathname += "/";
+	let hardNavigationTarget = pathname + parsed.search;
+	if (origUrl.hash) hardNavigationTarget += origUrl.hash;
+	return hardNavigationTarget;
+}
+function resolveRscCompatibilityNavigationDecision(options) {
+	if (isRscCompatibilityIdCompatible(options.responseCompatibilityId, options.clientCompatibilityId)) return { kind: "compatible" };
+	return {
+		hardNavigationTarget: resolveHardNavigationTargetFromRscResponse(options.responseUrl, options.currentHref, options.origin),
+		kind: "hard-navigate"
+	};
+}
+function normalizeRenderModeHeaderValue(value) {
+	const renderMode = parseAppRscRenderMode(value);
+	return renderMode === "navigation" ? null : renderMode;
+}
+function createCacheBustingInput(headers, options = {}) {
+	const values = [
+		headers.get(NEXT_ROUTER_PREFETCH_HEADER),
+		headers.get(NEXT_ROUTER_SEGMENT_PREFETCH_HEADER),
+		headers.get(NEXT_ROUTER_STATE_TREE_HEADER),
+		headers.get(NEXT_URL_HEADER),
+		headers.get(VINEXT_INTERCEPTION_CONTEXT_HEADER),
+		headers.get(VINEXT_MOUNTED_SLOTS_HEADER),
+		...options.includeRenderModeHeader === false ? [] : [normalizeRenderModeHeaderValue(headers.get(VINEXT_RSC_RENDER_MODE_HEADER))]
+	];
+	if (values.every((value) => value === null)) return null;
+	return values.map(normalizeHeaderValue).join(",");
+}
+async function sha256CacheBustingHash(input) {
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", textEncoder.encode(input));
+	return encodeBase64Url(new Uint8Array(digest).subarray(0, CACHE_BUSTING_DIGEST_BYTES));
+}
+function computeLegacyRscCacheBustingSearchParam(headers) {
+	const input = createCacheBustingInput(headers);
+	return input === null ? "" : fnv1a64(input);
+}
+async function computePreviousRscCacheBustingSearchParam(headers) {
+	const input = createCacheBustingInput(headers, { includeRenderModeHeader: false });
+	if (input === null) return null;
+	return sha256CacheBustingHash(input);
+}
+function computePreviousLegacyRscCacheBustingSearchParam(headers) {
+	const input = createCacheBustingInput(headers, { includeRenderModeHeader: false });
+	return input === null ? null : fnv1a64(input);
+}
+function getSearchPairsWithoutRscCacheBusting(url) {
+	return (url.search.startsWith("?") ? url.search.slice(1) : url.search).split("&").filter((pair) => pair.length > 0 && !isRscCacheBustingSearchPair(pair));
+}
+function isRscCacheBustingSearchPair(pair) {
+	const separatorIndex = pair.indexOf("=");
+	const rawKey = separatorIndex === -1 ? pair : pair.slice(0, separatorIndex);
+	try {
+		return decodeURIComponent(rawKey.replaceAll("+", " ")) === VINEXT_RSC_CACHE_BUSTING_SEARCH_PARAM;
+	} catch {
+		return rawKey === VINEXT_RSC_CACHE_BUSTING_SEARCH_PARAM;
+	}
+}
+/**
+* Detect the internal RSC cache-busting search param using the same
+* encoding-aware matching as `stripRscCacheBustingSearchParam`
+* (`isRscCacheBustingSearchPair`). The two share a single matcher so a guard
+* built on this helper and the stripper can never disagree on which pairs
+* count as `_rsc`, including encoded-key edge cases like `%5Frsc`.
+*/
+function hasRscCacheBustingSearchParam(url) {
+	return (url.search.startsWith("?") ? url.search.slice(1) : url.search).split("&").some((pair) => pair.length > 0 && isRscCacheBustingSearchPair(pair));
+}
+async function computeRscCacheBustingSearchParam(headers) {
+	const input = createCacheBustingInput(headers);
+	if (input === null) return "";
+	return sha256CacheBustingHash(input);
+}
+function setRscCacheBustingSearchParam(url, hash) {
+	const pairs = getSearchPairsWithoutRscCacheBusting(url);
+	pairs.push(hash.length > 0 ? `${VINEXT_RSC_CACHE_BUSTING_SEARCH_PARAM}=${hash}` : VINEXT_RSC_CACHE_BUSTING_SEARCH_PARAM);
+	url.search = `?${pairs.join("&")}`;
+}
+function stripRscCacheBustingSearchParam(url) {
+	const pairs = getSearchPairsWithoutRscCacheBusting(url);
+	url.search = pairs.length > 0 ? `?${pairs.join("&")}` : "";
+}
+/**
+* Remove a trailing `.rsc` suffix from a pathname. Returns the pathname
+* unchanged when the suffix is absent.
+*/
+function stripRscSuffix(pathname) {
+	return pathname.endsWith(".rsc") ? pathname.slice(0, -4) : pathname;
+}
+function createRscRequestHeaders(options = {}) {
+	const headers = new Headers({
+		Accept: VINEXT_RSC_CONTENT_TYPE,
+		["RSC"]: "1"
+	});
+	applyDeploymentIdHeader(headers);
+	if (options.interceptionContext !== void 0 && options.interceptionContext !== null) headers.set(VINEXT_INTERCEPTION_CONTEXT_HEADER, options.interceptionContext);
+	if (options.mountedSlotsHeader !== void 0 && options.mountedSlotsHeader !== null) headers.set(VINEXT_MOUNTED_SLOTS_HEADER, options.mountedSlotsHeader);
+	if (options.clientReuseManifestHeader !== void 0 && options.clientReuseManifestHeader !== null) headers.set(VINEXT_CLIENT_REUSE_MANIFEST_HEADER, options.clientReuseManifestHeader);
+	const renderMode = options.renderMode ?? "navigation";
+	if (renderMode !== "navigation") headers.set(VINEXT_RSC_RENDER_MODE_HEADER, renderMode);
+	return headers;
+}
+function toRscRequestPath(href) {
+	const hashIndex = href.indexOf("#");
+	return hashIndex === -1 ? href : href.slice(0, hashIndex);
+}
+async function createRscRequestUrl(href, headers) {
+	const url = new URL(toRscRequestPath(href), "http://vinext.local");
+	setRscCacheBustingSearchParam(url, await computeRscCacheBustingSearchParam(headers));
+	return `${url.pathname}${url.search}`;
+}
+function createServerActionRequestUrl(href) {
+	const hashIndex = href.indexOf("#");
+	const beforeHash = hashIndex === -1 ? href : href.slice(0, hashIndex);
+	const url = new URL(beforeHash, "http://vinext.local");
+	return `${url.pathname}${url.search}`;
+}
+async function createRscRedirectLocation(location, request) {
+	const requestUrl = new URL(request.url);
+	const destinationUrl = new URL(location, requestUrl);
+	if (destinationUrl.origin !== requestUrl.origin) return destinationUrl.toString();
+	const rscPath = await createRscRequestUrl(`${destinationUrl.pathname}${destinationUrl.search}`, request.headers);
+	return `${destinationUrl.origin}${rscPath}`;
+}
+async function resolveInvalidRscCacheBustingRequest(options) {
+	if (!options.isRscRequest || options.request.method !== "GET" && options.request.method !== "HEAD") return null;
+	const url = new URL(options.request.url);
+	const actualHash = url.searchParams.get(VINEXT_RSC_CACHE_BUSTING_SEARCH_PARAM);
+	const expectedHash = await computeRscCacheBustingSearchParam(options.request.headers);
+	if (actualHash === null && expectedHash === "") return null;
+	const acceptedHashes = new Set([expectedHash]);
+	if (actualHash !== null && actualHash !== expectedHash) {
+		acceptedHashes.add(computeLegacyRscCacheBustingSearchParam(options.request.headers));
+		if (normalizeRenderModeHeaderValue(options.request.headers.get("X-Vinext-Rsc-Render-Mode")) === null) {
+			const previousHash = await computePreviousRscCacheBustingSearchParam(options.request.headers);
+			const previousLegacyHash = computePreviousLegacyRscCacheBustingSearchParam(options.request.headers);
+			if (previousHash !== null) acceptedHashes.add(previousHash);
+			if (previousLegacyHash !== null) acceptedHashes.add(previousLegacyHash);
+		}
+	}
+	if (actualHash !== null && acceptedHashes.has(actualHash)) return null;
+	setRscCacheBustingSearchParam(url, expectedHash);
+	return new Response(null, {
+		status: 307,
+		headers: { Location: `${url.pathname}${url.search}` }
+	});
+}
+//#endregion
+export { VINEXT_RSC_CACHE_BUSTING_SEARCH_PARAM, VINEXT_RSC_COMPATIBILITY_ID_HEADER, VINEXT_RSC_CONTENT_TYPE, VINEXT_RSC_RENDER_MODE_HEADER, VINEXT_RSC_VARY_HEADER, applyRscCompatibilityIdHeader, computeRscCacheBustingSearchParam, createRscRedirectLocation, createRscRequestHeaders, createRscRequestUrl, createServerActionRequestUrl, getVinextRscCompatibilityId, hasRscCacheBustingSearchParam, isRscCompatibilityIdCompatible, resolveHardNavigationTargetFromRscResponse, resolveInvalidRscCacheBustingRequest, resolveRscCompatibilityNavigationDecision, setRscCacheBustingSearchParam, stripRscCacheBustingSearchParam, stripRscSuffix };

package/dist/server/app-rsc-embedded-chunks.d.ts

@@ -0,0 +1,8 @@
+//#region src/server/app-rsc-embedded-chunks.d.ts
+declare const RSC_EMBEDDED_BINARY_CHUNK = 3;
+type RscEmbeddedChunk = string | [typeof RSC_EMBEDDED_BINARY_CHUNK, string];
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function decodeRscEmbeddedChunk(chunk: RscEmbeddedChunk): Uint8Array;
+declare function concatUint8Arrays(chunks: readonly Uint8Array[]): Uint8Array<ArrayBuffer>;
+//#endregion
+export { RSC_EMBEDDED_BINARY_CHUNK, RscEmbeddedChunk, bytesToBase64, concatUint8Arrays, decodeRscEmbeddedChunk };

package/dist/server/app-rsc-embedded-chunks.js

@@ -0,0 +1,32 @@
+//#region src/server/app-rsc-embedded-chunks.ts
+const RSC_EMBEDDED_BINARY_CHUNK = 3;
+const BASE64_CHUNK_SIZE = 32768;
+const textEncoder = new TextEncoder();
+function bytesToBase64(bytes) {
+	let binary = "";
+	for (let offset = 0; offset < bytes.byteLength; offset += BASE64_CHUNK_SIZE) binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_CHUNK_SIZE));
+	return btoa(binary);
+}
+function base64ToBytes(base64) {
+	const binary = atob(base64);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}
+function decodeRscEmbeddedChunk(chunk) {
+	if (typeof chunk === "string") return textEncoder.encode(chunk);
+	return base64ToBytes(chunk[1]);
+}
+function concatUint8Arrays(chunks) {
+	let totalLength = 0;
+	for (const chunk of chunks) totalLength += chunk.byteLength;
+	const result = new Uint8Array(totalLength);
+	let offset = 0;
+	for (const chunk of chunks) {
+		result.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return result;
+}
+//#endregion
+export { RSC_EMBEDDED_BINARY_CHUNK, bytesToBase64, concatUint8Arrays, decodeRscEmbeddedChunk };

package/dist/server/app-rsc-error-handler.d.ts

@@ -0,0 +1,20 @@
+//#region src/server/app-rsc-error-handler.d.ts
+type ReportRequestError = (error: Error, requestInfo: {
+  path: string;
+  method: string;
+  headers: Record<string, string>;
+}, errorContext: {
+  routerKind: "App Router";
+  routePath: string;
+  routeType: "render";
+}) => void;
+/**
+ * Build a per-request RSC error handler that extracts request metadata from
+ * the incoming Web `Request`, wires it into a `createRscOnErrorHandler` call,
+ * and binds the configured `reportRequestError` reporter.
+ *
+ * Pure factory: takes all deps explicitly — no closure over module-level state.
+ */
+declare function createAppRscOnErrorHandler(reportRequestError: ReportRequestError, request: Request, pathname: string, routePath: string): (error: unknown) => string | undefined;
+//#endregion
+export { createAppRscOnErrorHandler };

package/dist/server/app-rsc-error-handler.js

@@ -0,0 +1,28 @@
+import { createRscOnErrorHandler } from "./app-rsc-errors.js";
+//#region src/server/app-rsc-error-handler.ts
+/**
+* Build a per-request RSC error handler that extracts request metadata from
+* the incoming Web `Request`, wires it into a `createRscOnErrorHandler` call,
+* and binds the configured `reportRequestError` reporter.
+*
+* Pure factory: takes all deps explicitly — no closure over module-level state.
+*/
+function createAppRscOnErrorHandler(reportRequestError, request, pathname, routePath) {
+	const requestHeaders = Object.fromEntries(request.headers.entries());
+	const requestInfo = {
+		path: pathname,
+		method: request.method,
+		headers: requestHeaders
+	};
+	return createRscOnErrorHandler({
+		errorContext: {
+			routerKind: "App Router",
+			routePath: routePath || pathname,
+			routeType: "render"
+		},
+		reportRequestError,
+		requestInfo
+	});
+}
+//#endregion
+export { createAppRscOnErrorHandler };

package/dist/server/app-rsc-errors.d.ts

@@ -0,0 +1,40 @@
+//#region src/server/app-rsc-errors.d.ts
+type RscRequestInfo = {
+  path: string;
+  method: string;
+  headers: Record<string, string>;
+};
+type RscErrorContext = {
+  routerKind: "App Router";
+  routePath: string;
+  routeType: "render";
+};
+type RscErrorReporter = (error: Error, requestInfo: RscRequestInfo, errorContext: RscErrorContext) => void;
+type CreateRscOnErrorHandlerOptions = {
+  errorContext: RscErrorContext | null;
+  nodeEnv?: string;
+  reportRequestError: RscErrorReporter;
+  requestInfo: RscRequestInfo | null;
+};
+declare function hasDigest(error: unknown): error is {
+  digest: unknown;
+};
+/**
+ * vinext's mirror of Next.js's `getDigestForWellKnownError`: returns the digest
+ * string only when the error is a genuine control-flow signal — a redirect,
+ * notFound/HTTP-access fallback, bail-out-to-client-side-rendering, or
+ * dynamic-server-usage throw. Any other digest (e.g. a hashed digest stamped on
+ * a real error, or an obfuscated digest transported from a nested boundary)
+ * returns undefined so the caller still reports it as a real error. Mere
+ * presence of a `digest` field is NOT enough — that conflation swallowed a class
+ * of server render errors with no instrumentation/telemetry.
+ */
+declare function getDigestForWellKnownError(error: unknown): string | undefined;
+/**
+ * djb2 hash matching Next.js's string-hash package for RSC error digests.
+ */
+declare function errorDigest(input: string): string;
+declare function sanitizeErrorForClient(error: unknown, nodeEnv?: string | undefined): unknown;
+declare function createRscOnErrorHandler(options: CreateRscOnErrorHandlerOptions): (error: unknown) => string | undefined;
+//#endregion
+export { createRscOnErrorHandler, errorDigest, getDigestForWellKnownError, hasDigest, sanitizeErrorForClient };

package/dist/server/app-rsc-errors.js

@@ -0,0 +1,60 @@
+import { isNavigationSignalError } from "../utils/navigation-signal.js";
+import { resolveAppPageSpecialError } from "./app-page-execution.js";
+//#region src/server/app-rsc-errors.ts
+function hasDigest(error) {
+	return Boolean(error && typeof error === "object" && "digest" in error);
+}
+const BAILOUT_TO_CSR_DIGEST = "BAILOUT_TO_CLIENT_SIDE_RENDERING";
+const DYNAMIC_SERVER_USAGE_DIGEST = "DYNAMIC_SERVER_USAGE";
+/**
+* vinext's mirror of Next.js's `getDigestForWellKnownError`: returns the digest
+* string only when the error is a genuine control-flow signal — a redirect,
+* notFound/HTTP-access fallback, bail-out-to-client-side-rendering, or
+* dynamic-server-usage throw. Any other digest (e.g. a hashed digest stamped on
+* a real error, or an obfuscated digest transported from a nested boundary)
+* returns undefined so the caller still reports it as a real error. Mere
+* presence of a `digest` field is NOT enough — that conflation swallowed a class
+* of server render errors with no instrumentation/telemetry.
+*/
+function getDigestForWellKnownError(error) {
+	if (!hasDigest(error)) return;
+	const digest = String(error.digest);
+	if (isNavigationSignalError(error) || digest === BAILOUT_TO_CSR_DIGEST || digest === DYNAMIC_SERVER_USAGE_DIGEST) return digest;
+}
+function getThrownValueMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function getThrownValueStack(error) {
+	return error instanceof Error ? error.stack || "" : "";
+}
+/**
+* djb2 hash matching Next.js's string-hash package for RSC error digests.
+*/
+function errorDigest(input) {
+	let hash = 5381;
+	for (let i = input.length - 1; i >= 0; i--) hash = hash * 33 ^ input.charCodeAt(i);
+	return (hash >>> 0).toString();
+}
+function sanitizeErrorForClient(error, nodeEnv = process.env.NODE_ENV) {
+	if (resolveAppPageSpecialError(error)) return error;
+	if (nodeEnv !== "production") return error;
+	const sanitized = /* @__PURE__ */ new Error("An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error.");
+	sanitized.digest = errorDigest(getThrownValueMessage(error) + getThrownValueStack(error));
+	return sanitized;
+}
+function createRscOnErrorHandler(options) {
+	return (error) => {
+		const nodeEnv = options.nodeEnv ?? process.env.NODE_ENV;
+		const wellKnownDigest = getDigestForWellKnownError(error);
+		if (wellKnownDigest !== void 0) return wellKnownDigest;
+		if (nodeEnv !== "production" && error instanceof Error && error.message.includes("Only plain objects, and a few built-ins, can be passed to Client Components")) {
+			console.error("[vinext] RSC serialization error: a non-plain object was passed from a Server Component to a Client Component.\n\nCommon causes:\n  * Passing a module namespace (import * as X) directly as a prop.\n    Unlike Next.js (webpack), Vite produces real ESM module namespace objects\n    which are not serializable. Fix: pass individual values instead,\n    e.g. <Comp value={module.value} />\n  * Passing a class instance (new Foo()) as a prop.\n    Fix: convert to a plain object, e.g. { id: foo.id, name: foo.name }\n  * Passing a Date, Map, or Set. Use .toISOString(), [...map.entries()], etc.\n  * Passing Object.create(null). Use { ...obj } to restore a prototype.\n\nOriginal error:", error.message);
+			return;
+		}
+		if (options.requestInfo && options.errorContext && error) options.reportRequestError(error instanceof Error ? error : new Error(getThrownValueMessage(error)), options.requestInfo, options.errorContext);
+		if (hasDigest(error)) return String(error.digest);
+		if (nodeEnv === "production" && error) return errorDigest(getThrownValueMessage(error) + getThrownValueStack(error));
+	};
+}
+//#endregion
+export { createRscOnErrorHandler, errorDigest, getDigestForWellKnownError, hasDigest, sanitizeErrorForClient };

package/dist/server/app-rsc-handler.d.ts

@@ -0,0 +1,201 @@
+import { NextHeader, NextI18nConfig, NextRedirect, NextRewrite } from "../config/next-config.js";
+import { ImageConfig } from "./image-optimization.js";
+import { ClientReuseManifestParseResult } from "./client-reuse-manifest.js";
+import { RootParams } from "../shims/root-params.js";
+import { AppMiddlewareContext, ApplyAppMiddlewareResult } from "./app-middleware.js";
+import { AppRscRenderMode } from "./app-rsc-render-mode.js";
+import { AppPagePprFallbackCacheShell } from "./app-ppr-fallback-shell.js";
+import { AppPrerenderRootParamNamesMap, AppPrerenderStaticParamsMap } from "./app-prerender-endpoints.js";
+import { ReactFormState } from "react-dom/client";
+
+//#region src/server/app-rsc-handler.d.ts
+type AppPageParams = Record<string, string | string[]>;
+type StaticParamsMap = AppPrerenderStaticParamsMap;
+type RootParamNamesMap = AppPrerenderRootParamNamesMap;
+type AppRscMiddlewareContext = AppMiddlewareContext;
+type RunAppMiddlewareOptions = {
+  cleanPathname: string;
+  context: AppRscMiddlewareContext;
+  isDataRequest: boolean;
+  request: Request;
+};
+type AppRscHandlerRoute = {
+  __loadPage?: unknown;
+  __loadRouteHandler?: unknown;
+  isDynamic: boolean;
+  params?: readonly string[];
+  page?: unknown;
+  pattern: string;
+  rootParamNames?: readonly string[];
+  routeHandler?: unknown;
+  routeSegments: readonly string[];
+};
+type AppRscRouteMatch<TRoute> = {
+  params: AppPageParams;
+  route: TRoute;
+};
+type DispatchMatchedPageOptions<TRoute> = {
+  clientReuseManifest: ClientReuseManifestParseResult;
+  cleanPathname: string;
+  displayPathname: string;
+  formState: ReactFormState | null;
+  actionError?: unknown;
+  actionFailed?: boolean;
+  handlerStart: number;
+  interceptionContext: string | null;
+  isProgressiveActionRender: boolean;
+  isRscRequest: boolean;
+  middlewareContext: AppRscMiddlewareContext;
+  mountedSlotsHeader: string | null;
+  params: AppPageParams;
+  pprFallbackCacheShells?: readonly {
+    fallbackParamNames: readonly string[];
+    params: AppPageParams;
+    pathname: string;
+  }[] | null;
+  pprFallbackShell?: {
+    fallbackParamNames: readonly string[];
+    routePattern: string;
+  };
+  renderedConcreteUrlPaths?: ReadonlySet<string>;
+  skipStaticParamsValidation?: boolean;
+  staticParamsValidationParams?: AppPageParams;
+  rootParams?: RootParams;
+  request: Request;
+  route: TRoute;
+  scriptNonce?: string;
+  searchParams: URLSearchParams;
+  renderMode: AppRscRenderMode;
+};
+type DispatchMatchedRouteHandlerOptions<TRoute> = {
+  cleanPathname: string;
+  middlewareContext: AppRscMiddlewareContext;
+  /**
+   * `null` for non-dynamic routes. Mirrors Next.js' route handler context
+   * shape: user code that does `params ? await params : null` resolves to
+   * `null` for routes without dynamic segments. Dynamic routes receive the
+   * matched params object.
+   */
+  params: AppPageParams | null;
+  request: Request;
+  route: TRoute;
+  searchParams: URLSearchParams;
+};
+type HandleProgressiveActionRequestOptions = {
+  actionId: string | null;
+  cleanPathname: string;
+  contentType: string;
+  middlewareContext: AppRscMiddlewareContext;
+  request: Request;
+};
+/**
+ * Side-effect headers captured during a progressive (no-JS) server action's
+ * non-redirect execution. Forwarded onto the page render response so that
+ * `cookies().set(...)` and revalidation kinds reach the browser. See
+ * `app-server-action-execution.ts` and issue #1483 for the full rationale.
+ */
+type ProgressiveActionSideEffects = {
+  pendingCookies: string[];
+  draftCookie: string | null | undefined; /** Numeric revalidation kind: `0` (none), `1` (static+dynamic), etc. */
+  revalidationKind: number;
+};
+type ProgressiveActionFormStateResult = ({
+  formState: ReactFormState | null;
+  kind: "form-state";
+} & ProgressiveActionSideEffects) | ({
+  actionError: unknown;
+  actionFailed: true;
+  formState: null;
+  kind: "form-state";
+} & ProgressiveActionSideEffects);
+type HandleServerActionRequestOptions = {
+  actionId: string | null;
+  cleanPathname: string;
+  contentType: string;
+  interceptionContext: string | null;
+  isRscRequest: boolean;
+  middlewareContext: AppRscMiddlewareContext;
+  mountedSlotsHeader: string | null;
+  request: Request;
+  searchParams: URLSearchParams;
+};
+type RenderNotFoundOptions<TRoute> = {
+  isRscRequest: boolean;
+  matchedParams?: AppPageParams;
+  middlewareContext: AppRscMiddlewareContext;
+  request: Request;
+  route: TRoute | null;
+  scriptNonce?: string;
+};
+type RenderPagesFallbackOptions = {
+  allowRscDocumentFallback?: boolean;
+  appRouteMatch?: {
+    route: {
+      isDynamic: boolean;
+      pattern: string;
+    };
+  } | null;
+  isDataRequest?: boolean;
+  isRscRequest: boolean;
+  matchKind?: "dynamic" | "static";
+  middlewareContext: AppRscMiddlewareContext;
+  pathname?: string;
+  pagesDataRequest?: Request | null;
+  request: Request;
+  url: URL;
+};
+type NavigationContextValue = {
+  params: AppPageParams;
+  pathname: string;
+  searchParams: URLSearchParams;
+};
+type CreateAppRscHandlerOptions<TRoute extends AppRscHandlerRoute> = {
+  basePath: string;
+  buildId: string | null;
+  clearRequestContext: () => void;
+  configHeaders: NextHeader[];
+  configRedirects: NextRedirect[];
+  configRewrites: {
+    afterFiles: NextRewrite[];
+    beforeFiles: NextRewrite[];
+    fallback: NextRewrite[];
+  };
+  draftModeSecret: string;
+  dispatchMatchedPage: (options: DispatchMatchedPageOptions<TRoute>) => Promise<Response>;
+  dispatchMatchedRouteHandler: (options: DispatchMatchedRouteHandlerOptions<TRoute>) => Promise<Response>;
+  /**
+   * Hydrate a matched route's lazily-loaded page/route-handler modules before
+   * any synchronous read of `route.page` / `route.routeHandler`. Idempotent and
+   * dedup'd. Provided by the generated RSC entry; absent in older entries.
+   */
+  ensureRouteLoaded?: (route: TRoute) => unknown;
+  ensureInstrumentation?: () => Promise<void>;
+  /**
+   * Register cache adapters configured via the vinext() `cache` option. Wired
+   * from the generated RSC entry (which can import `virtual:vinext-cache-adapters`)
+   * so config-driven cache handlers apply to App Router on EVERY runtime — the
+   * Node server and dev included, not just the Cloudflare worker entry.
+   */
+  registerCacheAdapters: (env?: Record<string, unknown>) => void;
+  handleProgressiveActionRequest?: (options: HandleProgressiveActionRequestOptions) => Promise<Response | ProgressiveActionFormStateResult | null>;
+  handleMetadataRouteRequest?: (cleanPathname: string) => Promise<Response | null>;
+  createPprFallbackShells?: (route: Pick<AppRscHandlerRoute, "params" | "pattern" | "rootParamNames">, params: AppPageParams) => AppPagePprFallbackCacheShell[];
+  handleServerActionRequest?: (options: HandleServerActionRequestOptions) => Promise<Response | null>;
+  i18nConfig: NextI18nConfig | null;
+  imageConfig?: ImageConfig;
+  isDev: boolean;
+  loadPrerenderPagesRoutes?: () => Promise<unknown>;
+  matchRoute: (pathname: string) => AppRscRouteMatch<TRoute> | null;
+  runMiddleware?: (options: RunAppMiddlewareOptions) => Promise<ApplyAppMiddlewareResult>;
+  publicFiles: ReadonlySet<string>;
+  renderNotFound: (options: RenderNotFoundOptions<TRoute>) => Promise<Response | null>;
+  renderPagesFallback?: (options: RenderPagesFallbackOptions) => Promise<Response | null>;
+  rootParamNamesByPattern?: RootParamNamesMap;
+  setNavigationContext: (context: NavigationContextValue) => void;
+  staticParamsMap: StaticParamsMap;
+  trailingSlash: boolean;
+  validateDevRequestOrigin?: (request: Request) => Response | null;
+};
+declare function createAppRscHandler<TRoute extends AppRscHandlerRoute>(options: CreateAppRscHandlerOptions<TRoute>): (request: Request, ctx: unknown) => Promise<Response>;
+//#endregion
+export { createAppRscHandler };