@qzsy/vinext 0.1.7

package/dist/server/app-ppr-fallback-shell.js

@@ -0,0 +1,89 @@
+import { createInlineScriptTag } from "./html.js";
+import { createNavigationRuntimeRscMetadataScript } from "./app-ssr-stream.js";
+//#region src/server/app-ppr-fallback-shell.ts
+const PPR_DYNAMIC_FALLBACK_SHELL_MARKER = "<!--vinext-ppr-dynamic-fallback-shell-->";
+function markAppPprDynamicFallbackShellHtml(html) {
+	return html + PPR_DYNAMIC_FALLBACK_SHELL_MARKER;
+}
+function isAppPprDynamicFallbackShellHtml(html) {
+	return html.includes(PPR_DYNAMIC_FALLBACK_SHELL_MARKER);
+}
+function routeRootParamNames(route) {
+	return new Set(route.rootParamNames ?? []);
+}
+function placeholderForParam(part, paramName) {
+	if (part.endsWith("+")) return [`[...${paramName}]`];
+	if (part.endsWith("*")) return [`[[...${paramName}]]`];
+	return `[${paramName}]`;
+}
+function pushParamValue(segments, value) {
+	if (Array.isArray(value)) {
+		if (value.length === 0) return false;
+		segments.push(...value.map((item) => encodeURIComponent(item)));
+		return true;
+	}
+	if (typeof value !== "string") return false;
+	segments.push(encodeURIComponent(value));
+	return true;
+}
+function createAppPprFallbackShell(route, matchedParams) {
+	return createAppPprFallbackShells(route, matchedParams).at(-1) ?? null;
+}
+function createAppPprFallbackShells(route, matchedParams) {
+	const rootParamNames = routeRootParamNames(route);
+	if (rootParamNames.size === 0) return [];
+	let minKeptParamCount = 0;
+	for (const rootParamName of rootParamNames) {
+		const rootParamIndex = route.params.indexOf(rootParamName);
+		if (rootParamIndex === -1 || matchedParams[rootParamName] === void 0) return [];
+		minKeptParamCount = Math.max(minKeptParamCount, rootParamIndex + 1);
+	}
+	if (minKeptParamCount >= route.params.length) return [];
+	const shells = [];
+	for (let keptParamCount = route.params.length - 1; keptParamCount >= minKeptParamCount; keptParamCount--) {
+		const keptParamNames = new Set(route.params.slice(0, keptParamCount));
+		const fallbackParamNames = route.params.filter((name) => !keptParamNames.has(name));
+		if (fallbackParamNames.length === 0) continue;
+		const fallbackParamNameSet = new Set(fallbackParamNames);
+		const segments = [];
+		const fallbackParams = {};
+		let isValidShell = true;
+		for (const part of route.pattern.split("/").filter(Boolean)) {
+			if (part.startsWith(":")) {
+				const paramName = part.endsWith("+") || part.endsWith("*") ? part.slice(1, -1) : part.slice(1);
+				if (fallbackParamNameSet.has(paramName)) {
+					const placeholder = placeholderForParam(part, paramName);
+					segments.push(...Array.isArray(placeholder) ? placeholder : [placeholder]);
+					fallbackParams[paramName] = placeholder;
+					continue;
+				}
+				const value = matchedParams[paramName];
+				if (!pushParamValue(segments, value)) {
+					isValidShell = false;
+					break;
+				}
+				fallbackParams[paramName] = value;
+				continue;
+			}
+			segments.push(part);
+		}
+		if (!isValidShell) continue;
+		shells.push({
+			fallbackParamNames,
+			pathname: "/" + segments.join("/"),
+			params: fallbackParams
+		});
+	}
+	return shells;
+}
+function rewriteAppPprFallbackShellHtmlNavigation(options) {
+	const metadataScript = createInlineScriptTag(createNavigationRuntimeRscMetadataScript(options.params, {
+		pathname: options.pathname,
+		searchParams: [...options.searchParams.entries()]
+	}));
+	const headCloseIndex = options.html.indexOf("</head>");
+	if (headCloseIndex !== -1) return options.html.slice(0, headCloseIndex) + metadataScript + options.html.slice(headCloseIndex);
+	return metadataScript + options.html;
+}
+//#endregion
+export { createAppPprFallbackShell, createAppPprFallbackShells, isAppPprDynamicFallbackShellHtml, markAppPprDynamicFallbackShellHtml, rewriteAppPprFallbackShellHtmlNavigation };

package/dist/server/app-prerender-endpoints.d.ts

@@ -0,0 +1,18 @@
+import { RootParams } from "../shims/root-params.js";
+
+//#region src/server/app-prerender-endpoints.d.ts
+type GenerateStaticParams = (args: {
+  params: RootParams;
+}) => unknown;
+type AppPrerenderStaticParamsMap = Record<string, GenerateStaticParams | null | undefined>;
+type AppPrerenderRootParamNamesMap = Record<string, readonly string[] | undefined>;
+type HandleAppPrerenderEndpointOptions = {
+  isPrerenderEnabled?: () => boolean;
+  loadPagesRoutes?: () => Promise<unknown>;
+  pathname: string;
+  rootParamNamesByPattern?: AppPrerenderRootParamNamesMap;
+  staticParamsMap: AppPrerenderStaticParamsMap;
+};
+declare function handleAppPrerenderEndpoint(request: Request, options: HandleAppPrerenderEndpointOptions): Promise<Response | null>;
+//#endregion
+export { AppPrerenderRootParamNamesMap, AppPrerenderStaticParamsMap, handleAppPrerenderEndpoint };

package/dist/server/app-prerender-endpoints.js

@@ -0,0 +1,94 @@
+import "./headers.js";
+import { notFoundResponse } from "./http-error-responses.js";
+import { callAppPrerenderStaticParams } from "./app-prerender-static-params.js";
+//#region src/server/app-prerender-endpoints.ts
+const JSON_HEADERS = { "content-type": "application/json" };
+async function handleAppPrerenderEndpoint(request, options) {
+	if (options.pathname === "/__vinext/prerender/static-params") return handleStaticParamsEndpoint(request, options);
+	if (options.pathname === "/__vinext/prerender/pages-static-paths") {
+		if (!options.loadPagesRoutes) return null;
+		return handlePagesStaticPathsEndpoint(request, options);
+	}
+	return null;
+}
+async function handleStaticParamsEndpoint(request, options) {
+	if (!isEnabled(options)) return notFoundResponse();
+	const url = new URL(request.url);
+	const pattern = url.searchParams.get("pattern");
+	if (!pattern) return new Response("missing pattern", { status: 400 });
+	const generateStaticParams = options.staticParamsMap[pattern];
+	if (typeof generateStaticParams !== "function") return jsonNullResponse();
+	try {
+		return jsonResponse(await callAppPrerenderStaticParams({
+			fn: generateStaticParams,
+			params: parseParentParams(url.searchParams.get("parentParams")),
+			pattern,
+			rootParamNamesByPattern: options.rootParamNamesByPattern ?? {}
+		}));
+	} catch (error) {
+		return jsonResponse({ error: String(error) }, 500);
+	}
+}
+async function handlePagesStaticPathsEndpoint(request, options) {
+	if (!isEnabled(options)) return notFoundResponse();
+	const url = new URL(request.url);
+	const pattern = url.searchParams.get("pattern");
+	if (!pattern) return new Response("missing pattern", { status: 400 });
+	try {
+		const getStaticPaths = findPageRoute(await options.loadPagesRoutes?.(), pattern)?.module?.getStaticPaths;
+		if (typeof getStaticPaths !== "function") return jsonNullResponse();
+		return jsonResponse(await getStaticPaths({
+			locales: parseLocales(url.searchParams.get("locales")),
+			defaultLocale: url.searchParams.get("defaultLocale") ?? ""
+		}));
+	} catch (error) {
+		return jsonResponse({ error: String(error) }, 500);
+	}
+}
+function isEnabled(options) {
+	return options.isPrerenderEnabled?.() ?? false;
+}
+function jsonResponse(body, status = 200) {
+	return new Response(JSON.stringify(body), {
+		headers: JSON_HEADERS,
+		status
+	});
+}
+function jsonNullResponse() {
+	return new Response("null", {
+		headers: JSON_HEADERS,
+		status: 200
+	});
+}
+function parseParentParams(raw) {
+	if (!raw) return {};
+	const value = JSON.parse(raw);
+	if (!isPlainObject(value)) return {};
+	const params = {};
+	for (const [key, paramValue] of Object.entries(value)) if (typeof paramValue === "string" || paramValue === void 0 || isStringArray(paramValue)) params[key] = paramValue;
+	return params;
+}
+function parseLocales(raw) {
+	if (!raw) return [];
+	const value = JSON.parse(raw);
+	if (!Array.isArray(value)) return [];
+	return value.filter((locale) => typeof locale === "string");
+}
+function findPageRoute(value, pattern) {
+	if (!Array.isArray(value)) return void 0;
+	for (const route of value) if (isPageRoute(route) && route.pattern === pattern) return route;
+}
+function isPageRoute(value) {
+	if (!isPlainObject(value) || typeof value.pattern !== "string") return false;
+	if (value.module === void 0) return true;
+	if (!isPlainObject(value.module)) return false;
+	return value.module.getStaticPaths === void 0 || typeof value.module.getStaticPaths === "function";
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+//#endregion
+export { handleAppPrerenderEndpoint };

package/dist/server/app-prerender-static-params.d.ts

@@ -0,0 +1,30 @@
+import { RootParams } from "../shims/root-params.js";
+
+//#region src/server/app-prerender-static-params.d.ts
+type GenerateStaticParamsFunction = (input: {
+  params: RootParams;
+}) => unknown;
+/**
+ * Build a prerender `generateStaticParams` resolver for one route pattern.
+ *
+ * `sources` may mix eager functions (layout `generateStaticParams`, which stay
+ * eagerly imported) and lazy `{ load }` page sources (code-split page modules).
+ * Lazy sources are imported once on first invocation. The returned resolver:
+ *
+ *  - returns `null` when, after resolving every source, no `generateStaticParams`
+ *    export exists for the pattern — the sentinel the prerender driver uses to
+ *    skip the route (or error under `output: export`);
+ *  - otherwise composes all sources into the cartesian set of param objects.
+ *
+ * Returns `null` (no resolver) only when the pattern has zero sources at all.
+ */
+declare function createAppPrerenderStaticParamsResolver(sources: readonly unknown[], rootParamNames?: readonly string[]): GenerateStaticParamsFunction | null;
+type CallAppPrerenderStaticParamsOptions = {
+  fn: GenerateStaticParamsFunction;
+  params: RootParams;
+  pattern: string;
+  rootParamNamesByPattern: Record<string, readonly string[] | undefined>;
+};
+declare function callAppPrerenderStaticParams(options: CallAppPrerenderStaticParamsOptions): Promise<unknown>;
+//#endregion
+export { callAppPrerenderStaticParams, createAppPrerenderStaticParamsResolver };

package/dist/server/app-prerender-static-params.js

@@ -0,0 +1,81 @@
+import { isUnknownRecord } from "../utils/record.js";
+import { pickRootParams, runWithRootParamsScope } from "../shims/root-params.js";
+//#region src/server/app-prerender-static-params.ts
+function isGenerateStaticParamsFunction(value) {
+	return typeof value === "function";
+}
+function isLazyStaticParamsSource(value) {
+	return typeof value === "object" && value !== null && "load" in value && typeof value.load === "function";
+}
+function isRootParams(value) {
+	return isUnknownRecord(value);
+}
+/**
+* Build a prerender `generateStaticParams` resolver for one route pattern.
+*
+* `sources` may mix eager functions (layout `generateStaticParams`, which stay
+* eagerly imported) and lazy `{ load }` page sources (code-split page modules).
+* Lazy sources are imported once on first invocation. The returned resolver:
+*
+*  - returns `null` when, after resolving every source, no `generateStaticParams`
+*    export exists for the pattern — the sentinel the prerender driver uses to
+*    skip the route (or error under `output: export`);
+*  - otherwise composes all sources into the cartesian set of param objects.
+*
+* Returns `null` (no resolver) only when the pattern has zero sources at all.
+*/
+function createAppPrerenderStaticParamsResolver(sources, rootParamNames) {
+	const usableSources = sources.filter((source) => isGenerateStaticParamsFunction(source) || isLazyStaticParamsSource(source));
+	if (usableSources.length === 0) return null;
+	const filterRootParams = (params) => pickRootParams(params, rootParamNames ?? []);
+	let resolvedFns = null;
+	let resolvePromise = null;
+	const resolveFns = () => {
+		if (resolvedFns) return Promise.resolve(resolvedFns);
+		if (!resolvePromise) resolvePromise = (async () => {
+			resolvedFns = (await Promise.all(usableSources.map(async (source) => {
+				if (isGenerateStaticParamsFunction(source)) return source;
+				const mod = await source.load();
+				const fn = mod && typeof mod === "object" ? mod.generateStaticParams : void 0;
+				return isGenerateStaticParamsFunction(fn) ? fn : null;
+			}))).filter((fn) => fn !== null);
+			return resolvedFns;
+		})();
+		return resolvePromise;
+	};
+	return async (input) => {
+		const fns = await resolveFns();
+		if (fns.length === 0) return null;
+		if (fns.length === 1) {
+			const single = fns[0];
+			return runWithRootParamsScope(filterRootParams(input.params), async () => {
+				const result = await single(input);
+				if (!Array.isArray(result)) return [];
+				for (const item of result) if (!isRootParams(item)) return [];
+				return result;
+			});
+		}
+		let paramSets = [input.params];
+		for (const generateStaticParams of fns) {
+			const nextParamSets = [];
+			for (const parentParams of paramSets) {
+				const result = await runWithRootParamsScope(filterRootParams(parentParams), async () => generateStaticParams({ params: parentParams }));
+				if (!Array.isArray(result)) return [];
+				for (const item of result) {
+					if (!isRootParams(item)) return [];
+					nextParamSets.push({
+						...parentParams,
+						...item
+					});
+				}
+			}
+			paramSets = nextParamSets;
+		}
+		return paramSets;
+	};
+}
+async function callAppPrerenderStaticParams(options) {
+	return runWithRootParamsScope(pickRootParams(options.params, options.rootParamNamesByPattern[options.pattern]), () => options.fn({ params: options.params }));
+}
+//#endregion
+export { callAppPrerenderStaticParams, createAppPrerenderStaticParamsResolver };

package/dist/server/app-render-dependency.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from "react";
+
+//#region src/server/app-render-dependency.d.ts
+type AppRenderDependency = {
+  promise: Promise<void>;
+  release: () => void;
+};
+declare function registerAppElementRenderDependencies(elements: Readonly<Record<string, unknown>>, dependenciesByElementId: ReadonlyMap<string, AppRenderDependency>): void;
+declare function releaseAppElementRenderDependency(elements: Readonly<Record<string, unknown>>, elementId: string): void;
+declare function createAppRenderDependency(): AppRenderDependency;
+declare function renderAfterAppDependencies(children: ReactNode, dependencies: readonly AppRenderDependency[]): ReactNode;
+declare function renderWithAppDependencyBarrier(children: ReactNode, dependency: AppRenderDependency): ReactNode;
+//#endregion
+export { AppRenderDependency, createAppRenderDependency, registerAppElementRenderDependencies, releaseAppElementRenderDependency, renderAfterAppDependencies, renderWithAppDependencyBarrier };

package/dist/server/app-render-dependency.js

@@ -0,0 +1,41 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/server/app-render-dependency.tsx
+const appElementRenderDependencies = /* @__PURE__ */ new WeakMap();
+function registerAppElementRenderDependencies(elements, dependenciesByElementId) {
+	if (dependenciesByElementId.size === 0) return;
+	appElementRenderDependencies.set(elements, dependenciesByElementId);
+}
+function releaseAppElementRenderDependency(elements, elementId) {
+	appElementRenderDependencies.get(elements)?.get(elementId)?.release();
+}
+function createAppRenderDependency() {
+	let released = false;
+	let resolve;
+	return {
+		promise: new Promise((promiseResolve) => {
+			resolve = promiseResolve;
+		}),
+		release() {
+			if (released) return;
+			released = true;
+			resolve();
+		}
+	};
+}
+function renderAfterAppDependencies(children, dependencies) {
+	if (dependencies.length === 0) return children;
+	async function AwaitAppRenderDependencies() {
+		await Promise.all(dependencies.map((dependency) => dependency.promise));
+		return children;
+	}
+	return /* @__PURE__ */ jsx(AwaitAppRenderDependencies, {});
+}
+function renderWithAppDependencyBarrier(children, dependency) {
+	function ReleaseAppRenderDependency() {
+		dependency.release();
+		return null;
+	}
+	return /* @__PURE__ */ jsxs(Fragment, { children: [children, /* @__PURE__ */ jsx(ReleaseAppRenderDependency, {})] });
+}
+//#endregion
+export { createAppRenderDependency, registerAppElementRenderDependencies, releaseAppElementRenderDependency, renderAfterAppDependencies, renderWithAppDependencyBarrier };

package/dist/server/app-request-context.d.ts

@@ -0,0 +1,20 @@
+import { NavigationContext } from "../shims/navigation-context-state.js";
+//#region src/server/app-request-context.d.ts
+/**
+ * Set navigation context in the ALS-backed store. "use client" components
+ * rendered during SSR need the pathname/searchParams/params but the SSR
+ * environment has a separate module instance of next/navigation.
+ *
+ * Clearing nav context (ctx === null) also clears root params.
+ */
+declare function setAppNavigationContext(ctx: NavigationContext | null): void;
+/**
+ * Clear all per-request ALS state owned by the App Router handler.
+ * Must be called before returning a non-page response (redirect, public
+ * file proxy, etc.) to prevent state leaking between requests on Workers.
+ *
+ * Clears: headers, navigation context, root params.
+ */
+declare function clearAppRequestContext(): void;
+//#endregion
+export { clearAppRequestContext, setAppNavigationContext };

package/dist/server/app-request-context.js

@@ -0,0 +1,29 @@
+import { setHeadersContext } from "../shims/headers.js";
+import { setNavigationContext } from "../shims/navigation-context-state.js";
+import "../shims/navigation-server.js";
+import { setRootParams } from "../shims/root-params.js";
+//#region src/server/app-request-context.ts
+/**
+* Set navigation context in the ALS-backed store. "use client" components
+* rendered during SSR need the pathname/searchParams/params but the SSR
+* environment has a separate module instance of next/navigation.
+*
+* Clearing nav context (ctx === null) also clears root params.
+*/
+function setAppNavigationContext(ctx) {
+	setNavigationContext(ctx);
+	if (ctx === null) setRootParams(null);
+}
+/**
+* Clear all per-request ALS state owned by the App Router handler.
+* Must be called before returning a non-page response (redirect, public
+* file proxy, etc.) to prevent state leaking between requests on Workers.
+*
+* Clears: headers, navigation context, root params.
+*/
+function clearAppRequestContext() {
+	setHeadersContext(null);
+	setAppNavigationContext(null);
+}
+//#endregion
+export { clearAppRequestContext, setAppNavigationContext };

package/dist/server/app-route-handler-cache.d.ts

@@ -0,0 +1,46 @@
+import { NextI18nConfig } from "../config/next-config.js";
+import { ISRCacheEntry } from "./isr-cache.js";
+import { HeadersAccessPhase } from "../shims/headers.js";
+import { RouteHandlerMiddlewareContext } from "./app-route-handler-response.js";
+import { AppRouteDebugLogger, AppRouteDynamicUsageFn, AppRouteHandlerFunction, AppRouteParams, MarkAppRouteDynamicUsageFn, RouteHandlerCacheSetter } from "./app-route-handler-execution.js";
+
+//#region src/server/app-route-handler-cache.d.ts
+type RouteHandlerCacheGetter = (key: string) => Promise<ISRCacheEntry | null>;
+type RouteHandlerBackgroundRegenerator = (key: string, renderFn: () => Promise<void>) => void;
+type RouteHandlerRevalidationContextRunner = (renderFn: () => Promise<void>) => Promise<void>;
+type ReadAppRouteHandlerCacheOptions = {
+  basePath?: string;
+  buildPageCacheTags: (pathname: string, extraTags: string[]) => string[];
+  cleanPathname: string;
+  clearRequestContext: () => void;
+  consumeDynamicUsage: AppRouteDynamicUsageFn;
+  dynamicConfig?: string;
+  getCollectedFetchTags: () => string[];
+  handlerFn: AppRouteHandlerFunction;
+  i18n?: NextI18nConfig | null;
+  trailingSlash?: boolean;
+  isAutoHead: boolean;
+  isrDebug?: AppRouteDebugLogger;
+  isrGet: RouteHandlerCacheGetter;
+  isrRouteKey: (pathname: string) => string;
+  isrSet: RouteHandlerCacheSetter;
+  markDynamicUsage: MarkAppRouteDynamicUsageFn;
+  middlewareContext: RouteHandlerMiddlewareContext; /** `null` for non-dynamic routes. See `AppRouteHandlerFunction` for details. */
+  params: AppRouteParams | null;
+  requestUrl: string;
+  revalidateSearchParams: URLSearchParams;
+  expireSeconds?: number;
+  revalidateSeconds: number;
+  routePattern: string;
+  runInRevalidationContext: RouteHandlerRevalidationContextRunner;
+  scheduleBackgroundRegeneration: RouteHandlerBackgroundRegenerator;
+  setHeadersAccessPhase: (phase: HeadersAccessPhase) => HeadersAccessPhase;
+  setNavigationContext: (context: {
+    pathname: string;
+    searchParams: URLSearchParams;
+    params: AppRouteParams;
+  } | null) => void;
+};
+declare function readAppRouteHandlerCacheResponse(options: ReadAppRouteHandlerCacheOptions): Promise<Response | null>;
+//#endregion
+export { readAppRouteHandlerCacheResponse };

package/dist/server/app-route-handler-cache.js

@@ -0,0 +1,78 @@
+import { makeThenableParams } from "../shims/thenable-params.js";
+import { applyRouteHandlerMiddlewareContext, assertSupportedAppRouteHandlerResponse, buildAppRouteCacheValue, buildRouteHandlerCachedResponse } from "./app-route-handler-response.js";
+import { markKnownDynamicAppRoute } from "./app-route-handler-runtime.js";
+import { runAppRouteHandler } from "./app-route-handler-execution.js";
+//#region src/server/app-route-handler-cache.ts
+const EMPTY_PARAMS = Object.freeze({});
+function getCachedAppRouteValue(entry) {
+	return entry?.value.value && entry.value.value.kind === "APP_ROUTE" ? entry.value.value : null;
+}
+async function readAppRouteHandlerCacheResponse(options) {
+	const routeKey = options.isrRouteKey(options.cleanPathname);
+	try {
+		const cached = await options.isrGet(routeKey);
+		const cachedValue = getCachedAppRouteValue(cached);
+		if (cachedValue && !cached?.isStale) {
+			options.isrDebug?.("HIT (route)", options.cleanPathname);
+			options.clearRequestContext();
+			return applyRouteHandlerMiddlewareContext(buildRouteHandlerCachedResponse(cachedValue, {
+				cacheState: "HIT",
+				cacheControl: cached?.value.cacheControl,
+				expireSeconds: options.expireSeconds,
+				isHead: options.isAutoHead,
+				revalidateSeconds: options.revalidateSeconds
+			}), options.middlewareContext);
+		}
+		if (cached?.isStale && cachedValue) {
+			const staleValue = cachedValue;
+			const revalidateSearchParams = new URLSearchParams(options.revalidateSearchParams);
+			options.scheduleBackgroundRegeneration(routeKey, async () => {
+				await options.runInRevalidationContext(async () => {
+					options.setNavigationContext({
+						pathname: options.cleanPathname,
+						searchParams: revalidateSearchParams,
+						params: options.params ?? EMPTY_PARAMS
+					});
+					const { dynamicUsedInHandler, response } = await runAppRouteHandler({
+						basePath: options.basePath,
+						consumeDynamicUsage: options.consumeDynamicUsage,
+						dynamicConfig: options.dynamicConfig,
+						handlerFn: options.handlerFn,
+						i18n: options.i18n,
+						trailingSlash: options.trailingSlash,
+						markDynamicUsage: options.markDynamicUsage,
+						params: options.params === null ? null : makeThenableParams(options.params),
+						request: new Request(options.requestUrl, { method: "GET" }),
+						routePattern: options.routePattern,
+						setHeadersAccessPhase: options.setHeadersAccessPhase
+					});
+					options.setNavigationContext(null);
+					assertSupportedAppRouteHandlerResponse(response);
+					if (dynamicUsedInHandler) {
+						markKnownDynamicAppRoute(options.routePattern);
+						options.isrDebug?.("route regen skipped (dynamic usage)", options.cleanPathname);
+						return;
+					}
+					const routeTags = options.buildPageCacheTags(options.cleanPathname, options.getCollectedFetchTags());
+					const routeCacheValue = await buildAppRouteCacheValue(response);
+					await options.isrSet(routeKey, routeCacheValue, options.revalidateSeconds, routeTags, options.expireSeconds);
+					options.isrDebug?.("route regen complete", routeKey);
+				});
+			});
+			options.isrDebug?.("STALE (route)", options.cleanPathname);
+			options.clearRequestContext();
+			return applyRouteHandlerMiddlewareContext(buildRouteHandlerCachedResponse(staleValue, {
+				cacheState: "STALE",
+				cacheControl: cached.value.cacheControl,
+				expireSeconds: options.expireSeconds,
+				isHead: options.isAutoHead,
+				revalidateSeconds: options.revalidateSeconds
+			}), options.middlewareContext);
+		}
+	} catch (routeCacheError) {
+		console.error("[vinext] ISR route cache read error:", routeCacheError);
+	}
+	return null;
+}
+//#endregion
+export { readAppRouteHandlerCacheResponse };

package/dist/server/app-route-handler-dispatch.d.ts

@@ -0,0 +1,49 @@
+import { NextI18nConfig } from "../config/next-config.js";
+import { ISRCacheEntry } from "./isr-cache.js";
+import { RouteHandlerMiddlewareContext } from "./app-route-handler-response.js";
+import { AppRouteHandlerModule } from "./app-route-handler-policy.js";
+import { AppRouteDebugLogger, AppRouteParams, RouteHandlerCacheSetter } from "./app-route-handler-execution.js";
+
+//#region src/server/app-route-handler-dispatch.d.ts
+type AppRouteHandlerDispatchRoute = {
+  pattern: string;
+  routeHandler: AppRouteHandlerModule;
+  routeSegments: string[];
+};
+type RouteHandlerCacheGetter = (key: string) => Promise<ISRCacheEntry | null>;
+type RouteHandlerBackgroundRegenerationErrorContext = {
+  routerKind: "App Router";
+  routePath: string;
+  routeType: "route";
+};
+type RouteHandlerBackgroundRegenerator = (key: string, renderFn: () => Promise<void>, errorContext?: RouteHandlerBackgroundRegenerationErrorContext) => void;
+type DispatchAppRouteHandlerOptions = {
+  basePath?: string;
+  cleanPathname: string;
+  clearRequestContext: () => void;
+  draftModeSecret: string;
+  expireSeconds?: number;
+  i18n?: NextI18nConfig | null;
+  isDevelopment?: boolean;
+  isProduction?: boolean;
+  isrDebug?: AppRouteDebugLogger;
+  isrGet: RouteHandlerCacheGetter;
+  isrRouteKey: (pathname: string) => string;
+  isrSet: RouteHandlerCacheSetter;
+  trailingSlash?: boolean;
+  middlewareContext: RouteHandlerMiddlewareContext;
+  middlewareRequestHeaders?: Headers | null;
+  /**
+   * `null` for non-dynamic routes, matching Next.js semantics. The dispatch
+   * layer threads this through to the handler context unchanged so user code
+   * (`params ? await params : null`) resolves to `null`.
+   */
+  params: AppRouteParams | null;
+  request: Request;
+  route: AppRouteHandlerDispatchRoute;
+  scheduleBackgroundRegeneration: RouteHandlerBackgroundRegenerator;
+  searchParams: URLSearchParams;
+};
+declare function dispatchAppRouteHandler(options: DispatchAppRouteHandlerOptions): Promise<Response>;
+//#endregion
+export { dispatchAppRouteHandler };