@qzsy/vinext 0.1.7

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

@@ -0,0 +1,157 @@
+import { addBasePathToPathname, hasBasePath, stripBasePath } from "../utils/base-path.js";
+import { NEXTJS_DEPLOYMENT_ID_HEADER } from "./headers.js";
+//#region src/server/pages-data-route.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`).
+*/
+const NEXT_DATA_PREFIX = "/_next/data/";
+const NEXT_DATA_SUFFIX = ".json";
+/**
+* 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).
+*/
+function isNextDataPathname(pathname) {
+	return pathname.startsWith(NEXT_DATA_PREFIX) && pathname.endsWith(NEXT_DATA_SUFFIX);
+}
+/**
+* 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)
+*/
+function parseNextDataPathname(pathname, buildId) {
+	if (!buildId) return null;
+	if (!isNextDataPathname(pathname)) return null;
+	const expectedPrefix = `${NEXT_DATA_PREFIX}${buildId}/`;
+	if (!pathname.startsWith(expectedPrefix)) return null;
+	const rest = pathname.slice(expectedPrefix.length, -5);
+	if (rest.length === 0) return null;
+	if (rest === "index") return { pagePathname: "/" };
+	if (rest.endsWith("/index")) return { pagePathname: `/${rest.slice(0, -6)}` };
+	if (rest.startsWith("index/")) return { pagePathname: `/${rest.slice(6)}` };
+	return { pagePathname: `/${rest}` };
+}
+/**
+* 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. *\/ }
+*/
+function buildNextDataJsonResponse(pageProps, safeJsonStringify, init) {
+	return buildNextDataPropsJsonResponse({ pageProps }, safeJsonStringify, init);
+}
+/**
+* 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.
+*/
+function buildNextDataPropsJsonResponse(props, safeJsonStringify, init) {
+	const body = safeJsonStringify(props);
+	return new Response(body, {
+		status: init?.status ?? 200,
+		statusText: init?.statusText,
+		headers: {
+			"Content-Type": "application/json",
+			...init?.headers
+		}
+	});
+}
+/**
+* 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.
+*/
+function buildNextDataNotFoundResponse() {
+	const headers = { "Content-Type": "application/json" };
+	const deploymentId = process.env.__VINEXT_DEPLOYMENT_ID || process.env.NEXT_DEPLOYMENT_ID;
+	if (deploymentId) headers[NEXTJS_DEPLOYMENT_ID_HEADER] = deploymentId;
+	return new Response("{}", {
+		status: 404,
+		headers
+	});
+}
+/**
+* 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.
+*/
+function normalizePagesDataRequest(request, buildId, basePath = "") {
+	const reqUrl = new URL(request.url);
+	const hadBasePath = !!basePath && hasBasePath(reqUrl.pathname, basePath);
+	const dataPathname = basePath ? stripBasePath(reqUrl.pathname, basePath) : reqUrl.pathname;
+	if (!isNextDataPathname(dataPathname)) return {
+		isDataReq: false,
+		request,
+		normalizedPathname: null,
+		search: "",
+		notFoundResponse: null
+	};
+	const dataMatch = buildId ? parseNextDataPathname(dataPathname, buildId) : null;
+	if (!dataMatch) return {
+		isDataReq: false,
+		request,
+		normalizedPathname: null,
+		search: "",
+		notFoundResponse: buildNextDataNotFoundResponse()
+	};
+	const normalizedUrl = new URL(reqUrl);
+	normalizedUrl.pathname = hadBasePath ? addBasePathToPathname(dataMatch.pagePathname, basePath) : dataMatch.pagePathname;
+	return {
+		isDataReq: true,
+		request: new Request(normalizedUrl, request),
+		normalizedPathname: dataMatch.pagePathname,
+		search: reqUrl.search,
+		notFoundResponse: null
+	};
+}
+//#endregion
+export { buildNextDataJsonResponse, buildNextDataNotFoundResponse, buildNextDataPropsJsonResponse, isNextDataPathname, normalizePagesDataRequest, parseNextDataPathname };

package/dist/server/pages-default-404.d.ts

@@ -0,0 +1,30 @@
+//#region src/server/pages-default-404.d.ts
+/**
+ * Default 404 HTML body for the Pages Router.
+ *
+ * Used when a Pages Router request does not match any route (and the app has
+ * not supplied a custom `pages/404.tsx`). Mirrors the markup Next.js's
+ * `pages/_error.tsx` produces for a 404 response: a centered status / message
+ * pair plus minified theme CSS and dark-mode media query. The message string
+ * `"This page could not be found."` (note the trailing period) is the
+ * canonical body asserted by Next.js's deploy suite
+ * (`test/e2e/getserversideprops/test/index.test.ts`,
+ * `test/e2e/basepath/error-pages.test.ts`).
+ *
+ * Kept as a hand-rendered HTML literal rather than a React-rendered template
+ * because the Pages Router server entry is invoked from both Workers and the
+ * dev server before any React-renderer wiring is available for this path —
+ * matching the lightweight build-time strategy Next.js uses for its packaged
+ * `_error` static fallback. See:
+ *   .nextjs-ref/packages/next/src/pages/_error.tsx
+ */
+/**
+ * Build the Next.js-compatible default 404 HTML response for the Pages Router.
+ * Content-type is `text/html; charset=utf-8`, matching Next.js's
+ * `pages-handler` 404 response.
+ */
+declare function buildDefaultPagesNotFoundResponse(): Response;
+/** Exported for tests / callers that need the raw HTML body. */
+declare const DEFAULT_PAGES_NOT_FOUND_HTML = "<!DOCTYPE html><html><head><meta charset=\"utf-8\"/><meta name=\"viewport\" content=\"width=device-width\"/><title>404: This page could not be found.</title><meta name=\"next-head-count\" content=\"2\"/><style data-next-hide-fouc=\"true\">body{display:none}</style><noscript data-next-hide-fouc=\"true\"><style>body{display:block}</style></noscript></head><body><div id=\"__next\"><div style=\"font-family:system-ui,&quot;Segoe UI&quot;,Roboto,Helvetica,Arial,sans-serif,&quot;Apple Color Emoji&quot;,&quot;Segoe UI Emoji&quot;;height:100vh;text-align:center;display:flex;flex-direction:column;align-items:center;justify-content:center\"><div style=\"line-height:48px\"><style>body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}</style><h1 class=\"next-error-h1\" style=\"display:inline-block;margin:0 20px 0 0;padding-right:23px;font-size:24px;font-weight:500;vertical-align:top\">404</h1><div style=\"display:inline-block\"><h2 style=\"font-size:14px;font-weight:400;line-height:28px\">This page could not be found.</h2></div></div></div></div></body></html>";
+//#endregion
+export { DEFAULT_PAGES_NOT_FOUND_HTML, buildDefaultPagesNotFoundResponse };

package/dist/server/pages-default-404.js

@@ -0,0 +1,38 @@
+//#region src/server/pages-default-404.ts
+/**
+* Default 404 HTML body for the Pages Router.
+*
+* Used when a Pages Router request does not match any route (and the app has
+* not supplied a custom `pages/404.tsx`). Mirrors the markup Next.js's
+* `pages/_error.tsx` produces for a 404 response: a centered status / message
+* pair plus minified theme CSS and dark-mode media query. The message string
+* `"This page could not be found."` (note the trailing period) is the
+* canonical body asserted by Next.js's deploy suite
+* (`test/e2e/getserversideprops/test/index.test.ts`,
+* `test/e2e/basepath/error-pages.test.ts`).
+*
+* Kept as a hand-rendered HTML literal rather than a React-rendered template
+* because the Pages Router server entry is invoked from both Workers and the
+* dev server before any React-renderer wiring is available for this path —
+* matching the lightweight build-time strategy Next.js uses for its packaged
+* `_error` static fallback. See:
+*   .nextjs-ref/packages/next/src/pages/_error.tsx
+*/
+const STATUS = 404;
+const MESSAGE = "This page could not be found.";
+const HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width"/><title>${STATUS}: ${MESSAGE}</title><meta name="next-head-count" content="2"/><style data-next-hide-fouc="true">body{display:none}</style><noscript data-next-hide-fouc="true"><style>body{display:block}</style></noscript></head><body><div id="__next"><div style="font-family:system-ui,&quot;Segoe UI&quot;,Roboto,Helvetica,Arial,sans-serif,&quot;Apple Color Emoji&quot;,&quot;Segoe UI Emoji&quot;;height:100vh;text-align:center;display:flex;flex-direction:column;align-items:center;justify-content:center"><div style="line-height:48px"><style>body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}</style><h1 class="next-error-h1" style="display:inline-block;margin:0 20px 0 0;padding-right:23px;font-size:24px;font-weight:500;vertical-align:top">${STATUS}</h1><div style="display:inline-block"><h2 style="font-size:14px;font-weight:400;line-height:28px">${MESSAGE}</h2></div></div></div></div></body></html>`;
+/**
+* Build the Next.js-compatible default 404 HTML response for the Pages Router.
+* Content-type is `text/html; charset=utf-8`, matching Next.js's
+* `pages-handler` 404 response.
+*/
+function buildDefaultPagesNotFoundResponse() {
+	return new Response(HTML, {
+		status: STATUS,
+		headers: { "Content-Type": "text/html; charset=utf-8" }
+	});
+}
+/** Exported for tests / callers that need the raw HTML body. */
+const DEFAULT_PAGES_NOT_FOUND_HTML = HTML;
+//#endregion
+export { DEFAULT_PAGES_NOT_FOUND_HTML, buildDefaultPagesNotFoundResponse };

package/dist/server/pages-dev-module-url.d.ts

@@ -0,0 +1,4 @@
+//#region src/server/pages-dev-module-url.d.ts
+declare function createPagesDevModuleUrl(viteRoot: string, moduleFilePath: string, viteBase: string): string;
+//#endregion
+export { createPagesDevModuleUrl };

package/dist/server/pages-dev-module-url.js

@@ -0,0 +1,15 @@
+import path from "node:path";
+//#region src/server/pages-dev-module-url.ts
+function normalizeBase(base) {
+	if (!base || base === "/") return "/";
+	return `/${base.replace(/^\/+|\/+$/g, "")}/`;
+}
+function encodeModulePath(modulePath) {
+	return encodeURI(modulePath).replace(/%5B/gi, "[").replace(/%5D/gi, "]").replace(/\?/g, "%3F").replace(/#/g, "%23");
+}
+function createPagesDevModuleUrl(viteRoot, moduleFilePath, viteBase) {
+	const relativePath = (/^[A-Za-z]:[\\/]/.test(viteRoot) ? path.win32 : path).relative(viteRoot, moduleFilePath).replace(/\\/g, "/");
+	return normalizeBase(viteBase) + encodeModulePath(relativePath);
+}
+//#endregion
+export { createPagesDevModuleUrl };

package/dist/server/pages-document-initial-props.d.ts

@@ -0,0 +1,77 @@
+import React, { ComponentType, ReactNode } from "react";
+
+//#region src/server/pages-document-initial-props.d.ts
+declare function loadUserDocumentInitialProps(DocumentComponent: ComponentType): Promise<Record<string, unknown> | null>;
+/** Options accepted by a `ctx.renderPage()` call (Pages Router contract). */
+type RenderPageEnhancers = {
+  enhanceApp?: (App: ComponentType<{
+    children?: ReactNode;
+  }>) => any;
+  enhanceComponent?: (Comp: ComponentType<unknown>) => any;
+};
+type DocumentRenderPageInput = {
+  /** The user `_document` component (may define `getInitialProps`). */DocumentComponent: ComponentType | null;
+  /**
+   * Build the page React tree with optional App/Component enhancers applied.
+   * Callers MUST NOT apply `withScriptNonce` themselves — this helper owns the
+   * nonce responsibility so the prod and dev paths stay symmetric.
+   */
+  enhancePageElement?: ((opts: RenderPageEnhancers) => ReactNode) | undefined; /** Render a React tree to a UTF-8 byte stream (prod/dev specific). */
+  renderToReadableStream: (element: React.ReactElement) => Promise<ReadableStream<Uint8Array>>; /** Render the document `styles` element to an HTML string. */
+  renderStylesToString: (element: React.ReactElement) => Promise<string>; /** Per-request CSP nonce applied to the enhanced page tree, if any. */
+  scriptNonce?: string | undefined; /** Extra `DocumentContext` fields (pathname/query/asPath). */
+  context?: Record<string, unknown> | undefined;
+};
+/**
+ * Run a user `_document.getInitialProps()` with a `ctx.renderPage()` that
+ * applies optional `enhanceApp` / `enhanceComponent` wrappers around the page
+ * React tree, mirroring Next.js's Pages Router contract.
+ *
+ * Used by CSS-in-JS libraries (styled-components, emotion) to wrap the
+ * App/Component tree so styles can be collected during SSR. Shared between the
+ * prod (`pages-page-response.ts`) and dev (`dev-server.ts`) SSR pipelines so
+ * the `getInitialProps` + `renderPage` contract lives in one place.
+ *
+ * @see .nextjs-ref/packages/next/src/server/render.tsx (search `renderPage`)
+ *
+ * Result of attempting the renderPage contract:
+ *   - `skipped`  — `getInitialProps` was NOT invoked (no override, or no
+ *                  `enhancePageElement` wired up). Callers should run the
+ *                  normal `loadUserDocumentInitialProps` fast path, which may
+ *                  invoke `getInitialProps` itself.
+ *   - `rendered` — `renderPage` produced the body. `bodyHtml` is the rendered
+ *                  page string, `stylesHTML` the rendered `styles`, `docProps`
+ *                  the remaining props to spread onto `<Document>`, and `head`
+ *                  the head nodes returned by `getInitialProps` (forward them to
+ *                  `setDocumentInitialHead()` — do NOT call
+ *                  `callDocumentGetInitialProps()` as well).
+ */
+type RunDocumentRenderPageResult = {
+  status: "skipped";
+} | {
+  status: "rendered";
+  bodyHtml: string;
+  stylesHTML: string;
+  docProps: Record<string, unknown>;
+  head: ReactNode[];
+};
+/**
+ * Run a user `_document.getInitialProps()` with a `ctx.renderPage()` that
+ * applies optional `enhanceApp` / `enhanceComponent` wrappers around the page
+ * React tree, mirroring Next.js's Pages Router contract.
+ *
+ * Used by CSS-in-JS libraries (styled-components, emotion) to wrap the
+ * App/Component tree so styles can be collected during SSR. Shared between the
+ * prod (`pages-page-response.ts`) and dev (`dev-server.ts`) SSR pipelines so
+ * the `getInitialProps` + `renderPage` contract lives in one place.
+ *
+ * `getInitialProps` is invoked at most once here. When this returns `rendered`,
+ * callers MUST treat that as the single invocation and must not call
+ * `loadUserDocumentInitialProps` again. Errors intentionally propagate to the
+ * Pages Router's normal error-page pipeline, matching Next.js.
+ *
+ * @see .nextjs-ref/packages/next/src/server/render.tsx (search `renderPage`)
+ */
+declare function runDocumentRenderPage(input: DocumentRenderPageInput): Promise<RunDocumentRenderPageResult>;
+//#endregion
+export { RenderPageEnhancers, loadUserDocumentInitialProps, runDocumentRenderPage };

package/dist/server/pages-document-initial-props.js

@@ -0,0 +1,109 @@
+import { withScriptNonce } from "../shims/script-nonce-context.js";
+import Document from "../shims/document.js";
+import { readStreamAsText } from "../utils/text-stream.js";
+import React from "react";
+//#region src/server/pages-document-initial-props.ts
+/**
+* Pages Router `_document.tsx` `getInitialProps` helper.
+*
+* Next.js's `pages/_document.tsx` may override
+* `static async getInitialProps(ctx)` to inject extra props onto the
+* Document element (the classic pattern is
+* `await Document.getInitialProps(ctx)` + spread, see Next.js's
+* `test/e2e/async-modules/pages/_document.jsx`). The SSR pipeline invokes
+* that hook and then renders the Document with the resolved props:
+*
+*   <Document {...htmlProps} {...docProps} />
+*
+* Reference:
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/server/render.tsx
+* (search for `loadDocumentInitialProps` and `documentElement`).
+*
+* `runDocumentRenderPage()` supplies `renderPage`, `defaultGetInitialProps`,
+* and the request pathname/query/asPath fields needed by the common upstream
+* pattern:
+*
+*   static async getInitialProps(ctx) {
+*     const initialProps = await Document.getInitialProps(ctx)
+*     return { ...initialProps, docValue }
+*   }
+*
+* The standalone `loadUserDocumentInitialProps()` compatibility path supplies
+* an empty default render result because it is only used after the body has
+* already been produced. Request-only fields such as req/res remain outside
+* that compatibility helper.
+*
+* Returns `null` when the user did not override the base shim (the static
+* `getInitialProps` reference still points at the shim's stub) so callers
+* skip the spread and render the bare Document element on the fast path.
+*
+* Errors from a user `getInitialProps` propagate to the caller. Next.js's
+* `loadGetInitialProps` does not catch — a throw becomes a 500 — and vinext
+* matches that contract so user bugs surface as the loud failures Next.js
+* apps already debug against.
+*/
+const BASE_GET_INITIAL_PROPS = Document.getInitialProps;
+async function loadUserDocumentInitialProps(DocumentComponent) {
+	const getInitialProps = DocumentComponent.getInitialProps;
+	if (typeof getInitialProps !== "function") return null;
+	if (getInitialProps === BASE_GET_INITIAL_PROPS) return null;
+	const result = await getInitialProps({ defaultGetInitialProps: async () => ({ html: "" }) });
+	return result && typeof result === "object" ? result : null;
+}
+/**
+* Run a user `_document.getInitialProps()` with a `ctx.renderPage()` that
+* applies optional `enhanceApp` / `enhanceComponent` wrappers around the page
+* React tree, mirroring Next.js's Pages Router contract.
+*
+* Used by CSS-in-JS libraries (styled-components, emotion) to wrap the
+* App/Component tree so styles can be collected during SSR. Shared between the
+* prod (`pages-page-response.ts`) and dev (`dev-server.ts`) SSR pipelines so
+* the `getInitialProps` + `renderPage` contract lives in one place.
+*
+* `getInitialProps` is invoked at most once here. When this returns `rendered`,
+* callers MUST treat that as the single invocation and must not call
+* `loadUserDocumentInitialProps` again. Errors intentionally propagate to the
+* Pages Router's normal error-page pipeline, matching Next.js.
+*
+* @see .nextjs-ref/packages/next/src/server/render.tsx (search `renderPage`)
+*/
+async function runDocumentRenderPage(input) {
+	const DocCtor = input.DocumentComponent;
+	if (!DocCtor || typeof DocCtor.getInitialProps !== "function") return { status: "skipped" };
+	if (DocCtor.getInitialProps === BASE_GET_INITIAL_PROPS) return { status: "skipped" };
+	if (!input.enhancePageElement) return { status: "skipped" };
+	const enhancePageElement = input.enhancePageElement;
+	const renderPage = async (opts = {}) => {
+		const wrapped = withScriptNonce(enhancePageElement(typeof opts === "function" ? { enhanceComponent: opts } : opts), input.scriptNonce);
+		return {
+			html: await readStreamAsText(await input.renderToReadableStream(wrapped)),
+			head: []
+		};
+	};
+	const docInitialProps = await DocCtor.getInitialProps({
+		renderPage,
+		defaultGetInitialProps: async (ctx) => {
+			const result = await ctx.renderPage({ enhanceApp: (App) => (props) => React.createElement(App, props) });
+			return {
+				html: result.html,
+				head: result.head ?? [],
+				styles: void 0
+			};
+		},
+		...input.context
+	});
+	const { html: _html, head: rawHead, styles: _styles, ...docProps } = docInitialProps ?? {};
+	const head = Array.isArray(rawHead) ? rawHead : [];
+	if (!docInitialProps || typeof docInitialProps.html !== "string") throw new Error(`"${DocCtor.displayName ?? DocCtor.name ?? "Document"}.getInitialProps()" should resolve to an object with a "html" prop set with a valid html string`);
+	let stylesHTML = "";
+	if (docInitialProps.styles != null) stylesHTML = await input.renderStylesToString(React.createElement(React.Fragment, null, docInitialProps.styles));
+	return {
+		status: "rendered",
+		bodyHtml: docInitialProps.html,
+		stylesHTML,
+		docProps,
+		head
+	};
+}
+//#endregion
+export { loadUserDocumentInitialProps, runDocumentRenderPage };

package/dist/server/pages-get-initial-props.d.ts

@@ -0,0 +1,67 @@
+//#region src/server/pages-get-initial-props.d.ts
+type PagesGetInitialPropsContext = {
+  req?: unknown;
+  res?: unknown;
+  err?: unknown;
+  pathname?: string;
+  query?: Record<string, unknown>;
+  asPath?: string;
+  locale?: string;
+  locales?: string[];
+  defaultLocale?: string;
+} & Record<string, unknown>;
+declare function hasPagesGetInitialProps(component: unknown): boolean;
+declare function isResponseSent(res: unknown): boolean;
+declare function loadPagesGetInitialProps(component: unknown, context: PagesGetInitialPropsContext): Promise<Record<string, unknown> | null>;
+/**
+ * Decision returned by {@link loadDevAppInitialProps}.
+ *
+ * - `skip`: the custom `App` has no `getInitialProps`; the caller renders with
+ *   its existing props unchanged.
+ * - `response-sent`: `_app.getInitialProps` ended the response itself (wrote
+ *   headers / body); the caller must stop and not render.
+ * - `render`: the caller should render with the returned `pageProps` /
+ *   `renderProps`.
+ */
+type DevAppInitialPropsResult = {
+  kind: "skip";
+} | {
+  kind: "response-sent";
+} | {
+  kind: "render";
+  pageProps: Record<string, unknown>;
+  renderProps: Record<string, unknown> & {
+    pageProps: unknown;
+  };
+};
+type DevAppInitialPropsContext = {
+  appComponent: unknown;
+  /**
+   * Builds the `AppTree` element passed to `getInitialProps`. Injected so this
+   * module stays free of React; the dev SSR handler supplies the real
+   * `React.createElement` closure.
+   */
+  appTree: (appTreeProps: Record<string, unknown>) => unknown;
+  component: unknown;
+  req: unknown;
+  res: unknown;
+  pathname: string;
+  query: Record<string, unknown>;
+  asPath: string;
+  locale?: string;
+  locales?: string[];
+  defaultLocale?: string;
+};
+/**
+ * Run the custom `App`'s `getInitialProps` for the dev SSR render path and
+ * return a decision the caller applies.
+ *
+ * This is the dev-server counterpart to the production page-data resolver's
+ * app-initial-props loading. It is invoked lazily — only when a request is
+ * actually going to render (cache miss / on-demand revalidation), never on an
+ * ISR cache HIT/STALE that serves cached HTML verbatim — so userland `App`
+ * data code does not run on the cache hot path.
+ */
+declare function loadDevAppInitialProps(ctx: DevAppInitialPropsContext): Promise<DevAppInitialPropsResult>;
+//#endregion
+export { DevAppInitialPropsContext, DevAppInitialPropsResult, hasPagesGetInitialProps, isResponseSent, loadDevAppInitialProps, loadPagesGetInitialProps };

package/dist/server/pages-get-initial-props.js

@@ -0,0 +1,92 @@
+//#region src/server/pages-get-initial-props.ts
+function isObjectLike(value) {
+	return typeof value === "object" && value !== null || typeof value === "function";
+}
+function isPagesGetInitialProps(value) {
+	return typeof value === "function";
+}
+function getObjectProperty(target, property) {
+	if (!isObjectLike(target)) return void 0;
+	return Reflect.get(target, property);
+}
+function getDisplayName(component) {
+	const displayName = getObjectProperty(component, "displayName");
+	if (typeof displayName === "string" && displayName.length > 0) return displayName;
+	const name = getObjectProperty(component, "name");
+	if (typeof name === "string" && name.length > 0) return name;
+	return "Component";
+}
+function getInitialPropsFn(component) {
+	const getInitialProps = getObjectProperty(component, "getInitialProps");
+	return isPagesGetInitialProps(getInitialProps) ? getInitialProps : null;
+}
+function hasPagesGetInitialProps(component) {
+	return getInitialPropsFn(component) !== null;
+}
+function isResponseSent(res) {
+	return getObjectProperty(res, "headersSent") === true || getObjectProperty(res, "writableEnded") === true;
+}
+function isPropsObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeInitialPropsValue(value) {
+	if (value === void 0) return "undefined";
+	if (value === null) return "null";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return `${value}`;
+	if (typeof value === "symbol") return value.description ? `Symbol(${value.description})` : "Symbol()";
+	if (typeof value === "function") return `[function ${getDisplayName(value)}]`;
+	return Object.prototype.toString.call(value);
+}
+async function loadPagesGetInitialProps(component, context) {
+	const getInitialProps = getInitialPropsFn(component);
+	if (!getInitialProps) return null;
+	const result = await Promise.resolve(getInitialProps.call(component, context));
+	if (isResponseSent(context.res)) return isPropsObject(result) ? result : {};
+	if (!isPropsObject(result)) throw new Error(`"${getDisplayName(component)}.getInitialProps()" should resolve to an object. But found "${describeInitialPropsValue(result)}" instead.`);
+	return result;
+}
+/**
+* Run the custom `App`'s `getInitialProps` for the dev SSR render path and
+* return a decision the caller applies.
+*
+* This is the dev-server counterpart to the production page-data resolver's
+* app-initial-props loading. It is invoked lazily — only when a request is
+* actually going to render (cache miss / on-demand revalidation), never on an
+* ISR cache HIT/STALE that serves cached HTML verbatim — so userland `App`
+* data code does not run on the cache hot path.
+*/
+async function loadDevAppInitialProps(ctx) {
+	if (!hasPagesGetInitialProps(ctx.appComponent)) return { kind: "skip" };
+	const initialProps = await loadPagesGetInitialProps(ctx.appComponent, {
+		AppTree: ctx.appTree,
+		Component: ctx.component,
+		router: {
+			pathname: ctx.pathname,
+			query: ctx.query,
+			asPath: ctx.asPath
+		},
+		ctx: {
+			req: ctx.req,
+			res: ctx.res,
+			pathname: ctx.pathname,
+			query: ctx.query,
+			asPath: ctx.asPath,
+			locale: ctx.locale,
+			locales: ctx.locales,
+			defaultLocale: ctx.defaultLocale
+		}
+	});
+	if (isResponseSent(ctx.res)) return { kind: "response-sent" };
+	const initialPageProps = isPropsObject(initialProps) ? initialProps.pageProps : void 0;
+	return {
+		kind: "render",
+		pageProps: isPropsObject(initialPageProps) ? initialPageProps : {},
+		renderProps: isPropsObject(initialProps) ? {
+			...initialProps,
+			pageProps: initialPageProps
+		} : { pageProps: initialPageProps }
+	};
+}
+//#endregion
+export { hasPagesGetInitialProps, isResponseSent, loadDevAppInitialProps, loadPagesGetInitialProps };