@qzsy/vinext 0.1.7

package/dist/server/pages-api-route.d.ts

@@ -0,0 +1,83 @@
+import { NextI18nConfig } from "../config/next-config.js";
+import { Route } from "../routing/pages-router.js";
+import { ExecutionContextLike } from "../shims/request-context.js";
+import { PagesReqResRequest, PagesReqResResponse, PagesRequestQuery } from "./pages-node-compat.js";
+
+//#region src/server/pages-api-route.d.ts
+type PagesApiRouteConfig = {
+  runtime?: string;
+  /**
+   * `export const config = { api: { bodyParser: false | { sizeLimit: '4mb' } } }`
+   * — controls whether vinext parses the request body for the route handler.
+   *
+   * `bodyParser: false` is critical for webhook handlers (Stripe, GitHub,
+   * Slack, etc.) that need to read the raw bytes to verify an HMAC
+   * signature. With it set, `req.body` is left undefined and the raw stream
+   * remains available through the Node-readable request object.
+   *
+   * @see https://nextjs.org/docs/pages/building-your-application/routing/api-routes#custom-config
+   */
+  api?: {
+    bodyParser?: boolean | {
+      sizeLimit?: string | number;
+    };
+    responseLimit?: boolean | string | number;
+    /**
+     * `externalResolver: true` declares that the response is sent by an
+     * external resolver (e.g. express/connect proxy middleware) that may
+     * complete after the handler's promise settles. Next.js uses it to
+     * suppress the "API resolved without sending a response" dev warning;
+     * vinext additionally uses it to suppress the auto-`end()` safety net,
+     * which would otherwise resolve an empty response before the external
+     * resolver writes.
+     *
+     * @see https://nextjs.org/docs/pages/building-your-application/routing/api-routes#custom-config
+     */
+    externalResolver?: boolean;
+  };
+};
+type PagesNodeApiRouteHandler = (req: PagesReqResRequest, res: PagesReqResResponse) => unknown;
+type PagesEdgeApiRouteHandler = (request: Request) => Response | Promise<Response>;
+type PagesApiRouteModule = {
+  /**
+   * `export const config = { runtime: 'edge' }` — historical Pages Router form.
+   */
+  config?: PagesApiRouteConfig;
+  /**
+   * `export const runtime = 'edge'` — bare export form. Next.js resolves the
+   * effective runtime as `config.runtime ?? config.config?.runtime`, so a
+   * top-level `runtime` export takes precedence over the nested config form.
+   *
+   * @see https://github.com/vercel/next.js/blob/canary/packages/next/src/build/analysis/get-page-static-info.ts
+   */
+  runtime?: string;
+  default?: PagesNodeApiRouteHandler | PagesEdgeApiRouteHandler;
+};
+type PagesApiRouteMatch = {
+  params: PagesRequestQuery;
+  route: Pick<Route, "pattern"> & {
+    module: PagesApiRouteModule;
+  };
+};
+type HandlePagesApiRouteOptions = {
+  /**
+   * Per-request Cloudflare Workers `ExecutionContext`. When provided, the
+   * API route runs inside `runWithExecutionContext(ctx, ...)` so any
+   * `after()` (or other shim) call inside the handler can reach
+   * `ctx.waitUntil()` via the ALS and keep the isolate alive past the
+   * response. Omit on Node.js dev where no Workers lifecycle exists.
+   */
+  ctx?: ExecutionContextLike;
+  match: PagesApiRouteMatch | null;
+  reportRequestError?: (error: Error, routePattern: string) => void | Promise<void>;
+  request: Request;
+  url: string;
+  nextConfig?: {
+    basePath?: string;
+    i18n?: NextI18nConfig | null;
+    trailingSlash?: boolean;
+  };
+};
+declare function handlePagesApiRoute(options: HandlePagesApiRouteOptions): Promise<Response>;
+//#endregion
+export { PagesApiRouteMatch, handlePagesApiRoute };

package/dist/server/pages-api-route.js

@@ -0,0 +1,75 @@
+import "./server-globals.js";
+import { runWithExecutionContext } from "../shims/request-context.js";
+import { NextRequest } from "../shims/server.js";
+import { internalServerErrorResponse } from "./http-error-responses.js";
+import { cloneRequestWithUrl } from "./request-pipeline.js";
+import { mergeRouteParamsIntoQuery, parseQueryString, urlQueryToSearchParams } from "../utils/query.js";
+import { PagesBodyParseError } from "./pages-media-type.js";
+import { isEdgeApiRuntime } from "./edge-api-runtime.js";
+import { resolveBodyParserConfig } from "./pages-body-parser-config.js";
+import { createPagesReqRes, parsePagesApiBody } from "./pages-node-compat.js";
+//#region src/server/pages-api-route.ts
+function resolveModuleRuntime(module) {
+	return module.runtime ?? module.config?.runtime;
+}
+function buildPagesApiQuery(url, params) {
+	return mergeRouteParamsIntoQuery(parseQueryString(url), params);
+}
+function createEdgeApiRequest(request, url, params) {
+	const resolvedUrl = new URL(request.url);
+	resolvedUrl.search = urlQueryToSearchParams(buildPagesApiQuery(url, params)).toString();
+	const resolvedUrlString = resolvedUrl.toString();
+	return resolvedUrlString === request.url ? request : cloneRequestWithUrl(request, resolvedUrlString);
+}
+function isEdgeApiRouteModule(module) {
+	return typeof module.default === "function" && isEdgeApiRuntime(resolveModuleRuntime(module));
+}
+function isNodeApiRouteModule(module) {
+	return typeof module.default === "function" && !isEdgeApiRuntime(resolveModuleRuntime(module));
+}
+async function handlePagesApiRoute(options) {
+	if (options.ctx) return runWithExecutionContext(options.ctx, () => _handlePagesApiRoute(options));
+	return _handlePagesApiRoute(options);
+}
+async function _handlePagesApiRoute(options) {
+	if (!options.match) return new Response("404 - API route not found", { status: 404 });
+	const { route, params } = options.match;
+	try {
+		if (isEdgeApiRouteModule(route.module)) {
+			const nextRequest = new NextRequest(createEdgeApiRequest(options.request, options.url, params), options.nextConfig ? { nextConfig: {
+				basePath: options.nextConfig.basePath,
+				i18n: options.nextConfig.i18n ?? void 0,
+				trailingSlash: options.nextConfig.trailingSlash
+			} } : void 0);
+			const response = await route.module.default(nextRequest);
+			if (response instanceof Response) return response;
+			throw new Error("Edge API route did not return a Response");
+		}
+		if (!isNodeApiRouteModule(route.module)) return new Response("API route does not export a default function", { status: 500 });
+		const query = buildPagesApiQuery(options.url, params);
+		const bodyParserConfig = resolveBodyParserConfig(route.module.config);
+		const { req, res, responsePromise } = createPagesReqRes({
+			body: bodyParserConfig.enabled ? await parsePagesApiBody(options.request, bodyParserConfig.sizeLimit) : void 0,
+			query,
+			request: options.request,
+			url: options.url
+		});
+		let resWasPiped = false;
+		res.once("pipe", () => {
+			resWasPiped = true;
+		});
+		const externalResolver = route.module.config?.api?.externalResolver || false;
+		await route.module.default(req, res);
+		if (!externalResolver && !resWasPiped && !res.headersSent) res.end();
+		return await responsePromise;
+	} catch (error) {
+		if (error instanceof PagesBodyParseError) return new Response(error.message, {
+			status: error.statusCode,
+			statusText: error.message
+		});
+		options.reportRequestError?.(error instanceof Error ? error : new Error(String(error)), route.pattern);
+		return internalServerErrorResponse();
+	}
+}
+//#endregion
+export { handlePagesApiRoute };

package/dist/server/pages-asset-tags.d.ts

@@ -0,0 +1,78 @@
+//#region src/server/pages-asset-tags.d.ts
+/**
+ * Pages Router SSR asset-tag helpers.
+ *
+ * Builds the `<link rel="modulepreload">`, `<link rel="stylesheet">`, and
+ * `<script type="module">` tags injected into the SSR HTML response.
+ *
+ * Extracted from `entries/pages-server-entry.ts` so the logic is
+ * unit-testable and lives in a normal typed module rather than a codegen
+ * template string.
+ */
+/**
+ * Resolve the effective SSR manifest: prefer the caller-supplied object (dev
+ * or test) and fall back to the Worker-embedded `globalThis.__VINEXT_SSR_MANIFEST__`
+ * injected by `vinext:cloudflare-build` at build time.
+ */
+declare function resolveSsrManifest(manifest: Record<string, string[]> | null | undefined): Record<string, string[]> | null;
+/**
+ * Look up the asset-file list for a module ID in the SSR manifest.
+ *
+ * The manifest keys may use relative paths while callers supply absolute
+ * paths, so a suffix-match fallback is used when an exact-key lookup fails.
+ */
+declare function getManifestFilesForModule(manifest: Record<string, string[]> | null | undefined, moduleId: string | null | undefined): string[] | null;
+/**
+ * Find the first `.js` file in the manifest for `moduleId` and return the URL it
+ * is actually SERVED from. Used to resolve the client-navigation / hydration URL
+ * for the matched page or the `_app` module (it is `import()`ed on the client),
+ * so it must point at the served location: `assetPrefix` replaces `basePath` for
+ * asset URLs. SSR-manifest values are base-anchored; re-anchor under any
+ * configured `assetPrefix` (default `""` keeps the legacy `"/" + file`).
+ */
+declare function resolveClientModuleUrl(manifest: Record<string, string[]> | null | undefined, moduleId: string | null | undefined, basePath?: string, assetPrefix?: string, _deploymentId?: string): string | undefined;
+type CollectAssetTagsOptions = {
+  /**
+   * SSR manifest mapping module file paths to their associated asset list.
+   * When empty/null the Worker-embedded `__VINEXT_SSR_MANIFEST__` is used.
+   */
+  manifest: Record<string, string[]> | null | undefined;
+  /**
+   * Module IDs whose assets should be injected (page + `_app`). When empty
+   * all manifest assets are injected.
+   */
+  moduleIds: (string | null | undefined)[]; /** Script nonce for CSP. */
+  scriptNonce?: string;
+  /**
+   * When `false` (default), page scripts are emitted with the `defer`
+   * attribute mirroring Next.js's `experimental.disableOptimizedLoading`
+   * default.
+   */
+  disableOptimizedLoading: boolean;
+  /**
+   * Configured `basePath` / `assetPrefix`. SSR-manifest values are base-anchored
+   * (needed for the lazy-chunk membership test), but the EMITTED href must point
+   * where the asset is actually served — `assetPrefix` replaces `basePath` for
+   * asset URLs. Default `""` (both unset) keeps the legacy `"/" + value` href.
+   */
+  basePath?: string;
+  assetPrefix?: string;
+  deploymentId?: string;
+};
+/**
+ * Build the HTML `<link>` and `<script>` tag string for the SSR response.
+ *
+ * Mirrors Next.js `_document` behaviour:
+ * - CSS files → `<link rel="stylesheet">`.
+ * - JS files → `<link rel="modulepreload">` + `<script type="module" defer>`.
+ * - Lazy chunks (behind `React.lazy` / `next/dynamic`) are skipped.
+ * - The Worker-embedded client-entry bootstrap (`__VINEXT_CLIENT_ENTRY__`) is
+ *   injected first so hydration starts as early as possible.
+ * - Shared framework / vinext runtime chunks are always included alongside
+ *   page-specific chunks.
+ *
+ * Extracted from `entries/pages-server-entry.ts`.
+ */
+declare function collectAssetTags(options: CollectAssetTagsOptions): string;
+//#endregion
+export { collectAssetTags, getManifestFilesForModule, resolveClientModuleUrl, resolveSsrManifest };

package/dist/server/pages-asset-tags.js

@@ -0,0 +1,126 @@
+import { appendDeploymentIdQuery } from "../utils/deployment-id.js";
+import { createNonceAttribute } from "./html.js";
+import { assetServingUrlFromBaseAnchored } from "../utils/manifest-paths.js";
+//#region src/server/pages-asset-tags.ts
+/**
+* Pages Router SSR asset-tag helpers.
+*
+* Builds the `<link rel="modulepreload">`, `<link rel="stylesheet">`, and
+* `<script type="module">` tags injected into the SSR HTML response.
+*
+* Extracted from `entries/pages-server-entry.ts` so the logic is
+* unit-testable and lives in a normal typed module rather than a codegen
+* template string.
+*/
+/**
+* Resolve the effective SSR manifest: prefer the caller-supplied object (dev
+* or test) and fall back to the Worker-embedded `globalThis.__VINEXT_SSR_MANIFEST__`
+* injected by `vinext:cloudflare-build` at build time.
+*/
+function resolveSsrManifest(manifest) {
+	if (manifest && Object.keys(manifest).length > 0) return manifest;
+	return (typeof globalThis !== "undefined" ? globalThis.__VINEXT_SSR_MANIFEST__ : null) ?? null;
+}
+/**
+* Look up the asset-file list for a module ID in the SSR manifest.
+*
+* The manifest keys may use relative paths while callers supply absolute
+* paths, so a suffix-match fallback is used when an exact-key lookup fails.
+*/
+function getManifestFilesForModule(manifest, moduleId) {
+	if (!manifest || !moduleId) return null;
+	const files = manifest[moduleId];
+	if (files) return files;
+	for (const key in manifest) if (moduleId.endsWith("/" + key) || moduleId === key) return manifest[key];
+	return null;
+}
+/**
+* Find the first `.js` file in the manifest for `moduleId` and return the URL it
+* is actually SERVED from. Used to resolve the client-navigation / hydration URL
+* for the matched page or the `_app` module (it is `import()`ed on the client),
+* so it must point at the served location: `assetPrefix` replaces `basePath` for
+* asset URLs. SSR-manifest values are base-anchored; re-anchor under any
+* configured `assetPrefix` (default `""` keeps the legacy `"/" + file`).
+*/
+function resolveClientModuleUrl(manifest, moduleId, basePath = "", assetPrefix = "", _deploymentId) {
+	const files = getManifestFilesForModule(resolveSsrManifest(manifest), moduleId);
+	if (!files) return void 0;
+	for (let i = 0; i < files.length; i++) {
+		const file = files[i];
+		if (!file || !file.endsWith(".js")) continue;
+		return assetServingUrlFromBaseAnchored(file, basePath, assetPrefix);
+	}
+}
+/**
+* Build the HTML `<link>` and `<script>` tag string for the SSR response.
+*
+* Mirrors Next.js `_document` behaviour:
+* - CSS files → `<link rel="stylesheet">`.
+* - JS files → `<link rel="modulepreload">` + `<script type="module" defer>`.
+* - Lazy chunks (behind `React.lazy` / `next/dynamic`) are skipped.
+* - The Worker-embedded client-entry bootstrap (`__VINEXT_CLIENT_ENTRY__`) is
+*   injected first so hydration starts as early as possible.
+* - Shared framework / vinext runtime chunks are always included alongside
+*   page-specific chunks.
+*
+* Extracted from `entries/pages-server-entry.ts`.
+*/
+function collectAssetTags(options) {
+	const m = resolveSsrManifest(options.manifest);
+	const tags = [];
+	const seen = /* @__PURE__ */ new Set();
+	const nonceAttr = createNonceAttribute(options.scriptNonce);
+	const deferAttr = options.disableOptimizedLoading ? "" : " defer";
+	const basePath = options.basePath ?? "";
+	const assetPrefix = options.assetPrefix ?? "";
+	const href = (value) => {
+		const url = assetServingUrlFromBaseAnchored(value, basePath, assetPrefix);
+		return value.endsWith(".js") ? url : appendDeploymentIdQuery(url, options.deploymentId);
+	};
+	const lazyChunks = typeof globalThis !== "undefined" && globalThis.__VINEXT_LAZY_CHUNKS__ || null;
+	const lazySet = lazyChunks && lazyChunks.length > 0 ? new Set(lazyChunks) : null;
+	if (typeof globalThis !== "undefined" && globalThis.__VINEXT_CLIENT_ENTRY__) {
+		const entry = globalThis.__VINEXT_CLIENT_ENTRY__;
+		seen.add(entry);
+		tags.push("<link rel=\"modulepreload\"" + nonceAttr + " href=\"" + href(entry) + "\" />");
+		tags.push("<script type=\"module\"" + deferAttr + nonceAttr + " src=\"" + href(entry) + "\" crossorigin><\/script>");
+	}
+	if (m) {
+		const allFiles = [];
+		const moduleIds = options.moduleIds;
+		if (moduleIds && moduleIds.length > 0) {
+			for (let mi = 0; mi < moduleIds.length; mi++) {
+				const id = moduleIds[mi];
+				const files = getManifestFilesForModule(m, id);
+				if (files) for (let fi = 0; fi < files.length; fi++) allFiles.push(files[fi]);
+			}
+			for (const key in m) {
+				const vals = m[key];
+				if (!vals) continue;
+				for (let vi = 0; vi < vals.length; vi++) {
+					const file = vals[vi];
+					const basename = file.split("/").pop() || "";
+					if (basename.startsWith("framework-") || basename.startsWith("vinext-") || basename.includes("vinext-client-entry") || basename.includes("vinext-app-browser-entry")) allFiles.push(file);
+				}
+			}
+		} else for (const akey in m) {
+			const avals = m[akey];
+			if (avals) for (let ai = 0; ai < avals.length; ai++) allFiles.push(avals[ai]);
+		}
+		for (let ti = 0; ti < allFiles.length; ti++) {
+			let tf = allFiles[ti];
+			if (tf.charAt(0) === "/") tf = tf.slice(1);
+			if (seen.has(tf)) continue;
+			seen.add(tf);
+			if (tf.endsWith(".css")) tags.push("<link rel=\"stylesheet\"" + nonceAttr + " href=\"" + href(tf) + "\" />");
+			else if (tf.endsWith(".js")) {
+				if (lazySet && lazySet.has(tf)) continue;
+				tags.push("<link rel=\"modulepreload\"" + nonceAttr + " href=\"" + href(tf) + "\" />");
+				tags.push("<script type=\"module\"" + deferAttr + nonceAttr + " src=\"" + href(tf) + "\" crossorigin><\/script>");
+			}
+		}
+	}
+	return tags.join("\n  ");
+}
+//#endregion
+export { collectAssetTags, getManifestFilesForModule, resolveClientModuleUrl, resolveSsrManifest };

package/dist/server/pages-body-parser-config.d.ts

@@ -0,0 +1,59 @@
+//#region src/server/pages-body-parser-config.d.ts
+/**
+ * Resolve the Pages Router `api.bodyParser` config from a route module export.
+ *
+ * Next.js API routes can opt out of automatic body parsing or raise the
+ * default 1 MB size limit:
+ *
+ *   export const config = { api: { bodyParser: false } };
+ *   export const config = { api: { bodyParser: { sizeLimit: '4mb' } } };
+ *
+ * `bodyParser: false` is critical for webhook handlers (Stripe, GitHub,
+ * Slack, etc.) that must read the raw request bytes to verify an HMAC
+ * signature. Silently parsing the body would consume the stream and break
+ * signature verification — usually failing closed, sometimes failing open.
+ *
+ * @see https://nextjs.org/docs/pages/building-your-application/routing/api-routes#custom-config
+ * @see Next.js: packages/next/src/server/api-utils/node/api-resolver.ts
+ *
+ * The format of `sizeLimit` mirrors what Next.js accepts via the `bytes`
+ * package: a number of bytes, or a string with a unit suffix
+ * (`"500b"`, `"100kb"`, `"4mb"`, `"1gb"`).
+ */
+/**
+ * Default Pages Router API body size limit, matching Next.js.
+ */
+declare const DEFAULT_PAGES_API_BODY_SIZE_LIMIT: number;
+/**
+ * Resolved bodyParser configuration. When `enabled` is `false`, the body
+ * MUST be passed through to the handler as a raw stream (or left unparsed
+ * with `req.body === undefined`), so user code can read it itself.
+ */
+type ResolvedBodyParserConfig = {
+  enabled: false;
+} | {
+  enabled: true;
+  sizeLimit: number;
+};
+/**
+ * Parse a Next.js-style `sizeLimit` string (e.g. `"4mb"`, `"100kb"`, `"1gb"`)
+ * or numeric byte value into a number of bytes. Returns `undefined` for
+ * inputs that can't be parsed — callers should fall back to the default.
+ *
+ * Matches the format accepted by Next.js (the `bytes` package); we
+ * implement it inline to avoid pulling a dependency for a tiny parser.
+ */
+declare function parseSizeLimit(value: string | number | undefined): number | undefined;
+/**
+ * Read the resolved `bodyParser` config from a route module's `config`
+ * export. Defaults to enabled with the 1 MB Next.js default.
+ */
+declare function resolveBodyParserConfig(moduleConfig: {
+  api?: {
+    bodyParser?: boolean | {
+      sizeLimit?: string | number;
+    };
+  };
+} | undefined, defaultSizeLimit?: number): ResolvedBodyParserConfig;
+//#endregion
+export { DEFAULT_PAGES_API_BODY_SIZE_LIMIT, parseSizeLimit, resolveBodyParserConfig };

package/dist/server/pages-body-parser-config.js

@@ -0,0 +1,77 @@
+//#region src/server/pages-body-parser-config.ts
+/**
+* Resolve the Pages Router `api.bodyParser` config from a route module export.
+*
+* Next.js API routes can opt out of automatic body parsing or raise the
+* default 1 MB size limit:
+*
+*   export const config = { api: { bodyParser: false } };
+*   export const config = { api: { bodyParser: { sizeLimit: '4mb' } } };
+*
+* `bodyParser: false` is critical for webhook handlers (Stripe, GitHub,
+* Slack, etc.) that must read the raw request bytes to verify an HMAC
+* signature. Silently parsing the body would consume the stream and break
+* signature verification — usually failing closed, sometimes failing open.
+*
+* @see https://nextjs.org/docs/pages/building-your-application/routing/api-routes#custom-config
+* @see Next.js: packages/next/src/server/api-utils/node/api-resolver.ts
+*
+* The format of `sizeLimit` mirrors what Next.js accepts via the `bytes`
+* package: a number of bytes, or a string with a unit suffix
+* (`"500b"`, `"100kb"`, `"4mb"`, `"1gb"`).
+*/
+/**
+* Default Pages Router API body size limit, matching Next.js.
+*/
+const DEFAULT_PAGES_API_BODY_SIZE_LIMIT = 1 * 1024 * 1024;
+const SIZE_UNITS = {
+	b: 1,
+	kb: 1024,
+	mb: 1024 * 1024,
+	gb: 1024 * 1024 * 1024,
+	tb: 1024 * 1024 * 1024 * 1024
+};
+/**
+* Parse a Next.js-style `sizeLimit` string (e.g. `"4mb"`, `"100kb"`, `"1gb"`)
+* or numeric byte value into a number of bytes. Returns `undefined` for
+* inputs that can't be parsed — callers should fall back to the default.
+*
+* Matches the format accepted by Next.js (the `bytes` package); we
+* implement it inline to avoid pulling a dependency for a tiny parser.
+*/
+function parseSizeLimit(value) {
+	if (value === void 0 || value === null) return void 0;
+	if (typeof value === "number") return Number.isFinite(value) && value >= 0 ? value : void 0;
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim().toLowerCase();
+	if (!trimmed) return void 0;
+	const match = /^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb|tb)?$/.exec(trimmed);
+	if (!match) return void 0;
+	const amount = Number.parseFloat(match[1]);
+	if (!Number.isFinite(amount) || amount < 0) return void 0;
+	const multiplier = SIZE_UNITS[match[2] ?? "b"];
+	if (multiplier === void 0) return void 0;
+	return Math.floor(amount * multiplier);
+}
+/**
+* Read the resolved `bodyParser` config from a route module's `config`
+* export. Defaults to enabled with the 1 MB Next.js default.
+*/
+function resolveBodyParserConfig(moduleConfig, defaultSizeLimit = DEFAULT_PAGES_API_BODY_SIZE_LIMIT) {
+	const bodyParser = moduleConfig?.api?.bodyParser;
+	if (bodyParser === false) return { enabled: false };
+	if (bodyParser === void 0 || bodyParser === true) return {
+		enabled: true,
+		sizeLimit: defaultSizeLimit
+	};
+	if (typeof bodyParser === "object" && bodyParser !== null) return {
+		enabled: true,
+		sizeLimit: parseSizeLimit(bodyParser.sizeLimit) ?? defaultSizeLimit
+	};
+	return {
+		enabled: true,
+		sizeLimit: defaultSizeLimit
+	};
+}
+//#endregion
+export { DEFAULT_PAGES_API_BODY_SIZE_LIMIT, parseSizeLimit, resolveBodyParserConfig };

package/dist/server/pages-data-route.d.ts

@@ -0,0 +1,121 @@
+//#region src/server/pages-data-route.d.ts
+/**
+ * Helpers for the Pages Router `/_next/data/{buildId}/{...page}.json` endpoint.
+ *
+ * Next.js uses this endpoint for client-side navigations in the Pages Router:
+ * `next/link` and `router.push()` fetch `pageProps` from this URL instead of
+ * doing a full HTML navigation. The server must:
+ *   1. Match the URL pattern and extract the page pathname (with the buildId
+ *      and `.json` extension removed, locale prefix preserved).
+ *   2. Normalize the URL BEFORE middleware runs so middleware sees the page
+ *      path (e.g. `/about`) rather than the raw `/_next/data/.../about.json`.
+ *   3. Invoke the same `getServerSideProps` / `getStaticProps` machinery as
+ *      the HTML page and serialize the resulting props as a JSON envelope:
+ *      `{ pageProps: ... }` with `Content-Type: application/json`.
+ *
+ * Ported from Next.js:
+ *   - `packages/next/src/server/normalizers/request/next-data.ts` — prefix/suffix matcher.
+ *   - `packages/next/src/server/base-server.ts` (`handleNextDataRequest`) — pipeline normalization.
+ *   - `packages/next/src/server/render.tsx` — JSON envelope emission (`isNextDataRequest`).
+ */
+type NextDataMatch = {
+  /**
+   * The normalized page pathname (with leading slash, no trailing slash,
+   * `.json` stripped, buildId stripped). For locale-prefixed requests like
+   * `/_next/data/<buildId>/en/about.json` this is `/en/about` — locale
+   * handling is done downstream by the existing `resolvePagesI18nRequest`
+   * pipeline so this helper does not need to know about i18n config.
+   */
+  pagePathname: string;
+};
+/**
+ * Returns true if the pathname looks like a `_next/data` request, regardless
+ * of buildId. Used by the request pipeline to short-circuit before middleware
+ * even when the buildId is wrong (so we can still return a 404 JSON response).
+ */
+declare function isNextDataPathname(pathname: string): boolean;
+/**
+ * Parse `/_next/data/<buildId>/<...page>.json` and return the normalized page
+ * pathname. Returns `null` if the pathname does not match the pattern or if
+ * the buildId segment does not match the server's buildId.
+ *
+ * The returned `pagePathname` is the page route path Next.js would render for
+ * the equivalent HTML navigation — including any locale prefix, which is then
+ * stripped by `resolvePagesI18nRequest` downstream.
+ *
+ * `/_next/data/<buildId>/about.json`         → `/about`
+ * `/_next/data/<buildId>/en/about.json`      → `/en/about`
+ * `/_next/data/<buildId>/index.json`         → `/`
+ * `/_next/data/<buildId>/en.json`            → `/en`
+ * `/_next/data/<wrong-id>/about.json`        → null
+ * `/_next/data/<buildId>/about`              → null  (missing .json suffix)
+ */
+declare function parseNextDataPathname(pathname: string, buildId: string): NextDataMatch | null;
+/**
+ * Build the JSON envelope returned by `/_next/data/<buildId>/<page>.json`.
+ * Mirrors Next.js' `RenderResult(JSON.stringify(props))` path in
+ * `packages/next/src/server/render.tsx` (search for `isNextDataRequest`).
+ *
+ * The envelope is the outer `props` object the React tree would receive:
+ *   { pageProps: {...}, /* optional locale data, redirect markers, etc. *\/ }
+ */
+declare function buildNextDataJsonResponse(pageProps: Record<string, unknown>, safeJsonStringify: (value: unknown) => string, init?: ResponseInit): Response;
+/**
+ * Build a `_next/data` JSON response from the full Pages props object returned
+ * through `_app.getInitialProps`. Next.js serializes the same outer props
+ * object that would be passed to `<App />`, so custom app-level props remain
+ * siblings of `pageProps` in the data envelope.
+ */
+declare function buildNextDataPropsJsonResponse(props: Record<string, unknown>, safeJsonStringify: (value: unknown) => string, init?: ResponseInit): Response;
+/**
+ * Build the 404 response Next.js returns for an unknown `_next/data` page.
+ * Next.js renders this as a normal 404 page, but the body shape that clients
+ * see for a missing page-data endpoint is the literal string `"{ }"` for the
+ * body and a 404 status with `application/json` so client-side hard-navigation
+ * fallback fires (see `__N_SSP` handling in `router.ts`).
+ *
+ * We match Next.js' behavior: 404 status + JSON content type. The body is an
+ * empty JSON object so clients that blindly call `res.json()` do not throw
+ * before checking the status code.
+ */
+declare function buildNextDataNotFoundResponse(): Response;
+type NormalizePagesDataRequestResult = {
+  isDataReq: false;
+  request: Request;
+  normalizedPathname: null;
+  search: "";
+  notFoundResponse: null;
+} | {
+  isDataReq: false;
+  request: Request;
+  normalizedPathname: null;
+  search: "";
+  notFoundResponse: Response;
+} | {
+  isDataReq: true;
+  request: Request;
+  normalizedPathname: string;
+  search: string;
+  notFoundResponse: null;
+};
+/**
+ * Detect and normalize `/_next/data/<buildId>/<page>.json` requests in one
+ * place so the Pages Router pipeline and middleware shim do not need to know
+ * about the data-endpoint protocol.
+ *
+ * Returns:
+ * - `isDataReq: false, notFoundResponse: null` — not a data request.
+ * - `isDataReq: false, notFoundResponse: Response` — looks like a data URL but
+ *   the buildId does not match; callers should return `notFoundResponse`
+ *   immediately so stale clients fall back to a hard navigation.
+ * - `isDataReq: true` — valid data request; `request` is re-pointed at the
+ *   normalized page path, `normalizedPathname` carries the bare page path, and
+ *   `search` carries the original query string for callers that need to
+ *   preserve it.
+ *
+ * Extracted from `entries/pages-server-entry.ts` so both `renderPage` and
+ * `runMiddleware` share a single implementation.
+ */
+declare function normalizePagesDataRequest(request: Request, buildId: string | null, basePath?: string): NormalizePagesDataRequestResult;
+//#endregion
+export { buildNextDataJsonResponse, buildNextDataNotFoundResponse, buildNextDataPropsJsonResponse, isNextDataPathname, normalizePagesDataRequest, parseNextDataPathname };