@qzsy/vinext 0.1.7

package/dist/server/server-action-not-found.js

@@ -0,0 +1,62 @@
+import { NEXTJS_ACTION_NOT_FOUND_HEADER } from "./headers.js";
+import { UnrecognizedActionError } from "../shims/unrecognized-action-error.js";
+//#region src/server/server-action-not-found.ts
+const SERVER_ACTION_NOT_FOUND_DOCS = "https://nextjs.org/docs/messages/failed-to-find-server-action";
+const SERVER_ACTION_NOT_FOUND_BODY = "Server action not found.";
+function getServerActionNotFoundPrefix(actionId) {
+	return `Failed to find Server Action${actionId ? ` "${actionId}"` : ""}.`;
+}
+function getServerActionNotFoundMessage(actionId) {
+	return `${getServerActionNotFoundPrefix(actionId)} This request might be from an older or newer deployment.\nRead more: ${SERVER_ACTION_NOT_FOUND_DOCS}`;
+}
+function getServerActionNotFoundClientMessage(actionId) {
+	return `Server Action "${actionId}" was not found on the server. \nRead more: ${SERVER_ACTION_NOT_FOUND_DOCS}`;
+}
+function getUnknownMessage(error) {
+	if (error instanceof Error) return error.message;
+	return typeof error === "string" ? error : "";
+}
+function isServerActionNotFoundError(error, actionId) {
+	const message = getUnknownMessage(error);
+	if (!message) return false;
+	if (actionId && message.startsWith(getServerActionNotFoundPrefix(actionId))) return true;
+	if (!actionId && message.startsWith("Failed to find Server Action")) return true;
+	if (actionId) {
+		const moduleId = actionId.split("#")[0];
+		if (message.includes(`[vite-rsc] invalid server reference '${actionId}'`) || moduleId && moduleId !== actionId && message.includes(`[vite-rsc] invalid server reference '${moduleId}'`)) return true;
+		if (message.includes(`server reference not found '${actionId}'`) || moduleId && moduleId !== actionId && message.includes(`server reference not found '${moduleId}'`)) return true;
+		return false;
+	}
+	return /\[vite-rsc] invalid server reference '/.test(message) || /server reference not found '/.test(message);
+}
+function createServerActionNotFoundResponse() {
+	return new Response(SERVER_ACTION_NOT_FOUND_BODY, {
+		status: 404,
+		headers: {
+			[NEXTJS_ACTION_NOT_FOUND_HEADER]: "1",
+			"content-type": "text/plain"
+		}
+	});
+}
+function isServerActionNotFoundResponse(response) {
+	return response.headers.get(NEXTJS_ACTION_NOT_FOUND_HEADER) === "1";
+}
+/**
+* Throw an `UnrecognizedActionError` when the server reported the requested
+* server action id as unknown (the `x-nextjs-action-not-found` response
+* header); otherwise return so the caller can keep processing the response.
+*
+* The client-side counterpart of `createServerActionNotFoundResponse`. The
+* typed error lets client `catch` blocks call the public
+* `unstable_isUnrecognizedActionError` predicate to detect client/server
+* deployment skew and recover (typically by reloading the page).
+*
+* Mirrors Next.js, whose server-action reducer throws `UnrecognizedActionError`
+* on this same response header:
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/router-reducer/reducers/server-action-reducer.ts
+*/
+function throwOnServerActionNotFound(response, actionId) {
+	if (isServerActionNotFoundResponse(response)) throw new UnrecognizedActionError(getServerActionNotFoundClientMessage(actionId));
+}
+//#endregion
+export { createServerActionNotFoundResponse, getServerActionNotFoundMessage, isServerActionNotFoundError, throwOnServerActionNotFound };

package/dist/server/server-globals.d.ts

@@ -0,0 +1,4 @@
+//#region src/server/server-globals.d.ts
+declare function installServerGlobals(): void;
+//#endregion
+export { installServerGlobals };

package/dist/server/server-globals.js

@@ -0,0 +1,35 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/server/server-globals.ts
+/**
+* Server runtime global setup shared by vinext's generated server entries.
+*
+* This module intentionally runs its installer at import time. Generated entry
+* modules import user pages and layouts as static dependencies, so any global
+* correction that must happen before user module evaluation has to live in a
+* side-effect dependency. A runtime function call from the generated entry
+* body would run after static user imports have already evaluated.
+*/
+function clearBrowserGlobal(name) {
+	const descriptor = Object.getOwnPropertyDescriptor(globalThis, name);
+	if (!descriptor && typeof Reflect.get(globalThis, name) === "undefined") return;
+	if (!descriptor) Object.defineProperty(globalThis, name, {
+		configurable: true,
+		value: void 0,
+		writable: true
+	});
+	else if (descriptor.configurable) Reflect.deleteProperty(globalThis, name);
+	else Reflect.set(globalThis, name, void 0);
+	if (typeof Reflect.get(globalThis, name) !== "undefined") throw new Error(`[vinext] Server runtime exposes a non-removable \`${name}\` global. This breaks Next.js SSR semantics where browser globals must be absent.`);
+}
+function installServerGlobals() {
+	clearBrowserGlobal("window");
+	clearBrowserGlobal("document");
+	if (typeof Reflect.get(globalThis, "AsyncLocalStorage") === "undefined") Object.defineProperty(globalThis, "AsyncLocalStorage", {
+		configurable: true,
+		value: AsyncLocalStorage,
+		writable: true
+	});
+}
+installServerGlobals();
+//#endregion
+export { installServerGlobals };

package/dist/server/skip-cache-proof.d.ts

@@ -0,0 +1,61 @@
+import { ArtifactCompatibilityEnvelope, ArtifactCompatibilityEvaluationOptions } from "./artifact-compatibility.js";
+import { StaticLayoutArtifactReuseDecision } from "./cache-proof.js";
+import { ClientReuseManifestEntry, ClientReuseManifestEntryRejection, ClientReuseManifestParseResult, ClientReuseManifestRejection, ClientReuseManifestSkipDisposition, ClientReuseManifestTraceFields } from "./client-reuse-manifest.js";
+import { createStaticLayoutClientReuseArtifactCompatibility, createStaticLayoutClientReusePayloadHash, createStaticLayoutClientReuseRouteId } from "./static-layout-client-reuse-proof.js";
+
+//#region src/server/skip-cache-proof.d.ts
+type SkipCacheInvalidationProof = Readonly<{
+  kind: "invalidated";
+  invalidationEpoch: string | null;
+}> | Readonly<{
+  kind: "unknown";
+}> | Readonly<{
+  kind: "valid";
+}>;
+type SkipCacheArtifactProof = Readonly<{
+  compatibility: ArtifactCompatibilityEnvelope;
+  invalidation: SkipCacheInvalidationProof;
+  payloadHash: string | null;
+}>;
+type SkipCacheCrossCheckAcceptanceCode = "SKIP_CACHE_CROSS_CHECK_PASSED";
+type SkipCacheCrossCheckVerified = Readonly<{
+  code: SkipCacheCrossCheckAcceptanceCode;
+  entryId: string;
+  fields: ClientReuseManifestTraceFields;
+  kind: "verified";
+  skipDisposition: ClientReuseManifestSkipDisposition;
+}>;
+type SkipCacheCrossCheckRejected = Readonly<{
+  kind: "rejected";
+  rejection: ClientReuseManifestEntryRejection;
+  skipDisposition: ClientReuseManifestSkipDisposition;
+}>;
+type SkipCacheCrossCheckResult = SkipCacheCrossCheckRejected | SkipCacheCrossCheckVerified;
+type CrossCheckClientReuseManifestEntryWithCacheInput = Readonly<{
+  artifact: SkipCacheArtifactProof;
+  cacheDecision: StaticLayoutArtifactReuseDecision | null;
+  entry: ClientReuseManifestEntry;
+}> & ArtifactCompatibilityEvaluationOptions;
+type ClientReuseSkipTransportPlan = Readonly<{
+  entryRejections: readonly ClientReuseManifestEntryRejection[];
+  kind: "renderAndSend";
+  manifestRejection?: ClientReuseManifestRejection;
+  skipDisposition: ClientReuseManifestSkipDisposition;
+  skipIneligibleEntryIds: readonly string[];
+  skippedEntryIds: readonly string[];
+}> | Readonly<{
+  entryRejections: readonly ClientReuseManifestEntryRejection[];
+  kind: "skip";
+  skipDisposition: ClientReuseManifestSkipDisposition;
+  skipIneligibleEntryIds: readonly string[];
+  skippedEntryIds: readonly string[];
+}>;
+type CreateClientReuseSkipTransportPlanInput = Readonly<{
+  manifest: ClientReuseManifestParseResult;
+  maxWireEntriesToVerify?: number;
+  verifyEntry: (entry: ClientReuseManifestEntry) => SkipCacheCrossCheckResult;
+}>;
+declare function crossCheckClientReuseManifestEntryWithCache(input: CrossCheckClientReuseManifestEntryWithCacheInput): SkipCacheCrossCheckResult;
+declare function createClientReuseSkipTransportPlan(input: CreateClientReuseSkipTransportPlanInput): ClientReuseSkipTransportPlan;
+//#endregion
+export { SkipCacheInvalidationProof, createClientReuseSkipTransportPlan, createStaticLayoutClientReuseArtifactCompatibility, createStaticLayoutClientReusePayloadHash, createStaticLayoutClientReuseRouteId, crossCheckClientReuseManifestEntryWithCache };

package/dist/server/skip-cache-proof.js

@@ -0,0 +1,168 @@
+import { ARTIFACT_COMPATIBILITY_PROOF_FIELDS, evaluateArtifactCompatibility } from "./artifact-compatibility.js";
+import { createClientReusePayloadHash } from "./client-reuse-manifest.js";
+import { createStaticLayoutClientReuseArtifactCompatibility, createStaticLayoutClientReusePayloadHash, createStaticLayoutClientReuseRouteId } from "./static-layout-client-reuse-proof.js";
+//#region src/server/skip-cache-proof.ts
+function createDisabledSkipDisposition() {
+	return {
+		code: "SKIP_MODEL_DISABLED",
+		enabled: false,
+		mode: "renderAndSend"
+	};
+}
+function createStaticLayoutSkipDisposition(skippedEntryIds) {
+	return {
+		code: "SKIP_STATIC_LAYOUT_VERIFIED",
+		enabled: true,
+		mode: "skipStaticLayout",
+		skippedEntryIds: [...skippedEntryIds]
+	};
+}
+function rejectSkipCacheCrossCheck(entry, code, fields = {}) {
+	return {
+		kind: "rejected",
+		rejection: {
+			code,
+			entryId: entry.id,
+			fields
+		},
+		skipDisposition: createDisabledSkipDisposition()
+	};
+}
+function collectArtifactCompatibilityProofMismatches(artifactCompatibility, proofCompatibility) {
+	const mismatchedFields = [];
+	for (const field of ARTIFACT_COMPATIBILITY_PROOF_FIELDS) if (artifactCompatibility[field] !== proofCompatibility[field]) mismatchedFields.push(field);
+	return mismatchedFields;
+}
+function isExactArtifactCompatibility(artifactCompatibility, entryCompatibility) {
+	return collectArtifactCompatibilityProofMismatches(artifactCompatibility, entryCompatibility).length === 0;
+}
+function assertNever(value) {
+	throw new Error(`Unhandled skip/cache proof state: ${String(value)}`);
+}
+function createRenderAndSendPlan(options) {
+	return {
+		kind: "renderAndSend",
+		entryRejections: options.entryRejections ?? [],
+		...options.manifestRejection ? { manifestRejection: options.manifestRejection } : {},
+		skipDisposition: createDisabledSkipDisposition(),
+		skipIneligibleEntryIds: options.skipIneligibleEntryIds ?? [],
+		skippedEntryIds: []
+	};
+}
+function createVerificationBudgetExceededRejection(totalWireEntries, maxWireEntriesToVerify) {
+	return {
+		code: "SKIP_VERIFICATION_BUDGET_EXCEEDED",
+		fields: {
+			totalWireEntries,
+			maxWireEntriesToVerify
+		}
+	};
+}
+function crossCheckInvalidationProof(entry, invalidation) {
+	switch (invalidation.kind) {
+		case "valid": return null;
+		case "unknown": return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_INVALIDATION_UNKNOWN");
+		case "invalidated": return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_INVALIDATED", { invalidationEpoch: invalidation.invalidationEpoch });
+		default: return assertNever(invalidation);
+	}
+}
+function crossCheckClientReuseManifestEntryWithCache(input) {
+	const { cacheDecision, entry } = input;
+	if (cacheDecision === null) return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_PROOF_MISSING");
+	if (cacheDecision.kind === "fallback") return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_PROOF_REJECTED", {
+		cacheProofCode: cacheDecision.fallback.code,
+		cacheProofMode: cacheDecision.fallback.mode,
+		cacheProofScope: cacheDecision.fallback.scope
+	});
+	const { proof } = cacheDecision;
+	if (entry.kind !== "layout" || proof.reuseClass !== "static-layout") return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_REUSE_CLASS_UNSUPPORTED", {
+		entryKind: entry.kind,
+		reuseClass: proof.reuseClass
+	});
+	if (entry.id !== proof.candidateOutput.layoutId) return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_ENTRY_ID_MISMATCH", {
+		cacheEntryId: proof.candidateOutput.layoutId,
+		manifestEntryId: entry.id
+	});
+	const artifactProofMismatches = collectArtifactCompatibilityProofMismatches(input.artifact.compatibility, proof.candidateArtifactCompatibility);
+	if (artifactProofMismatches.length > 0) return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_ARTIFACT_PROOF_MISMATCH", { mismatchedFields: artifactProofMismatches });
+	const artifactCompatibility = evaluateArtifactCompatibility(input.artifact.compatibility, entry.artifactCompatibility, { compatibilityMap: input.compatibilityMap });
+	if (artifactCompatibility.kind === "unknown") return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_ARTIFACT_COMPATIBILITY_UNKNOWN", {
+		compatibilityFallback: artifactCompatibility.fallback,
+		reason: artifactCompatibility.reason
+	});
+	if (artifactCompatibility.kind === "incompatible") return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_ARTIFACT_COMPATIBILITY_INCOMPATIBLE", {
+		compatibilityFallback: artifactCompatibility.fallback,
+		reason: artifactCompatibility.reason
+	});
+	if (entry.variantCacheKey !== proof.variant.cacheKey) return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_VARIANT_MISMATCH", {
+		cacheVariantCacheKeyHash: createClientReusePayloadHash(proof.variant.cacheKey),
+		entryVariantCacheKeyHash: createClientReusePayloadHash(entry.variantCacheKey)
+	});
+	if (input.artifact.payloadHash === null) return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_PAYLOAD_HASH_MISSING");
+	if (entry.payloadHash !== input.artifact.payloadHash) return rejectSkipCacheCrossCheck(entry, "SKIP_CACHE_PAYLOAD_HASH_MISMATCH", {
+		cachePayloadHash: input.artifact.payloadHash,
+		entryPayloadHash: entry.payloadHash
+	});
+	const invalidationRejection = crossCheckInvalidationProof(entry, input.artifact.invalidation);
+	if (invalidationRejection) return invalidationRejection;
+	const skipDisposition = isExactArtifactCompatibility(input.artifact.compatibility, entry.artifactCompatibility) ? createStaticLayoutSkipDisposition([entry.id]) : createDisabledSkipDisposition();
+	return {
+		kind: "verified",
+		code: "SKIP_CACHE_CROSS_CHECK_PASSED",
+		entryId: entry.id,
+		fields: {
+			entryKind: entry.kind,
+			reuseClass: proof.reuseClass,
+			variantCacheKeyHash: createClientReusePayloadHash(proof.variant.cacheKey)
+		},
+		skipDisposition
+	};
+}
+function createClientReuseSkipTransportPlan(input) {
+	const { manifest } = input;
+	if (manifest.kind === "absent") return createRenderAndSendPlan({});
+	if (manifest.kind === "rejected") return createRenderAndSendPlan({ manifestRejection: manifest.rejection });
+	const maxWireEntriesToVerify = input.maxWireEntriesToVerify ?? 8;
+	if (!Number.isSafeInteger(maxWireEntriesToVerify) || maxWireEntriesToVerify < 0) throw new RangeError("maxWireEntriesToVerify must be a non-negative safe integer");
+	const totalWireEntries = manifest.manifest.entries.length + manifest.entryRejections.length;
+	if (totalWireEntries > maxWireEntriesToVerify) return createRenderAndSendPlan({
+		entryRejections: manifest.entryRejections,
+		manifestRejection: createVerificationBudgetExceededRejection(totalWireEntries, maxWireEntriesToVerify)
+	});
+	const skippedEntryIds = [];
+	const skipIneligibleEntryIds = [];
+	const entryRejections = [...manifest.entryRejections];
+	for (const entry of manifest.manifest.entries) {
+		const verification = input.verifyEntry(entry);
+		if (verification.kind === "rejected") {
+			entryRejections.push(verification.rejection);
+			continue;
+		}
+		if (verification.entryId !== entry.id) {
+			entryRejections.push({
+				code: "SKIP_CACHE_ENTRY_ID_MISMATCH",
+				entryId: entry.id,
+				fields: {
+					verifierEntryId: verification.entryId,
+					manifestEntryId: entry.id
+				}
+			});
+			continue;
+		}
+		if (verification.skipDisposition.enabled) skippedEntryIds.push(entry.id);
+		else skipIneligibleEntryIds.push(entry.id);
+	}
+	if (skippedEntryIds.length === 0) return createRenderAndSendPlan({
+		entryRejections,
+		skipIneligibleEntryIds
+	});
+	return {
+		kind: "skip",
+		entryRejections,
+		skipDisposition: createStaticLayoutSkipDisposition(skippedEntryIds),
+		skipIneligibleEntryIds,
+		skippedEntryIds
+	};
+}
+//#endregion
+export { createClientReuseSkipTransportPlan, createStaticLayoutClientReuseArtifactCompatibility, createStaticLayoutClientReusePayloadHash, createStaticLayoutClientReuseRouteId, crossCheckClientReuseManifestEntryWithCache };

package/dist/server/socket-error-backstop.d.ts

@@ -0,0 +1,34 @@
+//#region src/server/socket-error-backstop.d.ts
+/**
+ * Pure predicate: returns the peer-disconnect code when `err` carries
+ * one of `ECONNRESET` / `EPIPE` / `ECONNABORTED`, otherwise `undefined`.
+ * Exported for unit testing in isolation (no process-state mutation).
+ */
+declare function peerDisconnectCode(err: unknown): string | undefined;
+/**
+ * Pure predicate: returns `true` when `err` is a benign failure from a
+ * dynamic `import()` of a static asset URL — the "URL dependency" pattern
+ * that Next.js tolerates at build time. Two shapes are recognised:
+ *
+ *   - `ERR_UNKNOWN_FILE_EXTENSION`: the asset resolved on disk but is not an
+ *     ES module (e.g. a co-located `./style.css`). The error message ends in
+ *     the offending extension in quotes: `... extension ".css" for /path`.
+ *   - `ERR_MODULE_NOT_FOUND`: the asset URL did not resolve (the chunk lives
+ *     in `dist/server/` but the source asset does not). Node attaches the
+ *     unresolved specifier on `err.url`; we match only when it points at a
+ *     static-asset extension.
+ *
+ * Anything outside this allow-list (including missing `.js`/`.mjs`/`.ts`
+ * modules with no extension) returns `false` so real bugs still crash.
+ * Exported for unit testing in isolation.
+ */
+declare function isBenignAssetImportError(err: unknown): boolean;
+/**
+ * Test-only: returns whether the backstop has been installed in this
+ * process. Used by the unit test to assert idempotent install via the
+ * Symbol.for guard. Not part of the public API.
+ */
+declare function isSocketErrorBackstopInstalled(): boolean;
+declare function installSocketErrorBackstop(): void;
+//#endregion
+export { installSocketErrorBackstop, isBenignAssetImportError, isSocketErrorBackstopInstalled, peerDisconnectCode };

package/dist/server/socket-error-backstop.js

@@ -0,0 +1,200 @@
+//#region src/server/socket-error-backstop.ts
+/**
+* Process-level backstop for peer-disconnect errors that escape
+* per-connection / per-request error guards.
+*
+* Three real call sites in vinext that hit this:
+*   - `fromWeb(fetch().body).pipe(res)` in proxyExternalRewriteNode.
+*   - Streaming surfaces inside `@vitejs/plugin-rsc` with their own
+*     pipe topology (destinations aren't inbound connection sockets).
+*   - Outbound sockets created by middleware `fetch()`.
+*
+* Node's `pipe()` re-emits source errors onto the destination when
+* the destination has no `'error'` listener, throwing synchronously
+* inside a `nextTick` callback. The throw escapes to
+* `uncaughtException`, where this listener filters it.
+*
+* Filters strictly on peer-disconnect codes (ECONNRESET / EPIPE /
+* ECONNABORTED) plus benign static-asset `import()` rejections (see
+* `isBenignAssetImportError`), and synchronously re-throws everything
+* else, preserving Node's default crash semantics for genuine bugs.
+* This is more conservative than Next.js's equivalent
+* (`router-server.ts`'s log-only handler), which silently swallows
+* every uncaught — vinext keeps real bugs surfacing.
+*
+* **Installed at module load.** Earlier iterations tried to gate
+* install via Vite's `config()` hook (`command === "serve"`) so it
+* was strictly dev-only, but the hook didn't fire reliably in
+* vite-plus's lifecycle — install was silently skipped. The
+* connection-level guard from #911 confirms `configureServer`-tied
+* lifecycle hooks are timing-fragile too. Module-load install is
+* the only place reliably observed to fire (verified via the
+* `VINEXT_DEBUG_SOCKET_ERRORS` marker).
+*
+* **Prerender check is dynamic, not install-time.** Prerender (in
+* `build/prerender.ts` and `build/run-prerender.ts`) calls
+* `startProdServer()` from inside `vinext build` to render pages
+* against a real HTTP server. User `fetch()` calls during prerender
+* hit external APIs that can drop connections; absorbing those would
+* silently produce corrupt prerendered output instead of crashing
+* the build. Prerender already sets `VINEXT_PRERENDER=1` for its
+* own purposes — the listener checks it at fire time and re-throws
+* unconditionally when set, acting as if no listener were installed.
+* Doing the check at install time wouldn't work: `index.ts` loads at
+* Vite plugin import, well before prerender starts, so by the time
+* `VINEXT_PRERENDER` is set the listener has already been installed
+* (we cannot uninstall and re-install per phase).
+*
+* Side-effect of the unconditional re-throw during prerender: an
+* orchestrator-induced ECONNRESET (e.g. the prerender's own HTTP
+* client aborting a stuck route fetch) will surface the build crash
+* as `Error: read ECONNRESET` rather than the underlying route
+* failure. Acceptable trade-off — a hung prerender route is itself
+* a build problem worth surfacing — but the resulting stack will
+* point at the disconnect, not the cause. Set
+* `VINEXT_DEBUG_SOCKET_ERRORS=1` to log peer-disconnect codes if
+* you need to disambiguate.
+*
+* **Test skip is install-time.** Vitest workers that import
+* `index.ts` directly should never have the listener installed —
+* peer-disconnect errors during test runs should surface normally.
+* `process.env.VITEST === "true"` is set by Vitest in every worker;
+* `NODE_ENV === "test"` covers other test runners that follow the
+* standard convention.
+*
+* **Listener ordering.** `index.ts` is imported synchronously at the
+* top of every user's `vite.config.ts`, so vinext's listener registers
+* before most user / tooling listeners (Sentry, OpenTelemetry,
+* structured logging). For peer-disconnect codes the early-return is
+* fine. For non-peer-disconnect errors the synchronous re-throw still
+* crashes the process with the original stack, but listeners
+* registered after vinext don't observe the event. Users who need
+* crash-reporter visibility for non-peer-disconnect errors must
+* register their handler before importing vinext.
+*
+* **Symbol.for caveat.** `Symbol.for("vinext.socketErrorBackstop")`
+* is process-global, so if two different vinext versions are loaded
+* in the same process the first to evaluate wins and the second's
+* filter rules silently don't apply.
+*
+* Set `VINEXT_DEBUG_SOCKET_ERRORS=1` to log a one-line marker each
+* time the listener absorbs an error.
+*/
+const SOCKET_BACKSTOP_FLAG = Symbol.for("vinext.socketErrorBackstop");
+/**
+* Pure predicate: returns the peer-disconnect code when `err` carries
+* one of `ECONNRESET` / `EPIPE` / `ECONNABORTED`, otherwise `undefined`.
+* Exported for unit testing in isolation (no process-state mutation).
+*/
+function peerDisconnectCode(err) {
+	const code = err?.code;
+	return code === "ECONNRESET" || code === "EPIPE" || code === "ECONNABORTED" ? code : void 0;
+}
+const STATIC_ASSET_IMPORT_EXTENSIONS = new Set([
+	".css",
+	".scss",
+	".sass",
+	".less",
+	".styl",
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".svg",
+	".webp",
+	".avif",
+	".ico",
+	".bmp",
+	".woff",
+	".woff2",
+	".ttf",
+	".otf",
+	".eot",
+	".txt",
+	".md",
+	".csv",
+	".xml",
+	".pdf",
+	".wasm"
+]);
+/**
+* Pure predicate: returns `true` when `err` is a benign failure from a
+* dynamic `import()` of a static asset URL — the "URL dependency" pattern
+* that Next.js tolerates at build time. Two shapes are recognised:
+*
+*   - `ERR_UNKNOWN_FILE_EXTENSION`: the asset resolved on disk but is not an
+*     ES module (e.g. a co-located `./style.css`). The error message ends in
+*     the offending extension in quotes: `... extension ".css" for /path`.
+*   - `ERR_MODULE_NOT_FOUND`: the asset URL did not resolve (the chunk lives
+*     in `dist/server/` but the source asset does not). Node attaches the
+*     unresolved specifier on `err.url`; we match only when it points at a
+*     static-asset extension.
+*
+* Anything outside this allow-list (including missing `.js`/`.mjs`/`.ts`
+* modules with no extension) returns `false` so real bugs still crash.
+* Exported for unit testing in isolation.
+*/
+function isBenignAssetImportError(err) {
+	if (err === null || typeof err !== "object") return false;
+	const code = err.code;
+	if (code === "ERR_UNKNOWN_FILE_EXTENSION") {
+		const message = err.message ?? "";
+		const match = /extension\s+"([^"]+)"/.exec(message);
+		return match != null && STATIC_ASSET_IMPORT_EXTENSIONS.has(match[1].toLowerCase());
+	}
+	if (code === "ERR_MODULE_NOT_FOUND") {
+		const url = err.url;
+		if (typeof url !== "string") return false;
+		const pathname = url.split("?", 1)[0].split("#", 1)[0];
+		const dot = pathname.lastIndexOf(".");
+		if (dot === -1) return false;
+		return STATIC_ASSET_IMPORT_EXTENSIONS.has(pathname.slice(dot).toLowerCase());
+	}
+	return false;
+}
+/**
+* Test-only: returns whether the backstop has been installed in this
+* process. Used by the unit test to assert idempotent install via the
+* Symbol.for guard. Not part of the public API.
+*/
+function isSocketErrorBackstopInstalled() {
+	return Boolean(process[SOCKET_BACKSTOP_FLAG]);
+}
+function installSocketErrorBackstop() {
+	const proc = process;
+	if (proc[SOCKET_BACKSTOP_FLAG]) return;
+	if (process.env.VITEST === "true" || process.env.NODE_ENV === "test") return;
+	proc[SOCKET_BACKSTOP_FLAG] = true;
+	const debug = process.env.VINEXT_DEBUG_SOCKET_ERRORS === "1";
+	if (debug) console.warn("[vinext] socket-error backstop installed");
+	const absorbBenignAssetImport = (reason, kind) => {
+		if (!isBenignAssetImportError(reason)) return false;
+		if (debug) {
+			const code = reason?.code;
+			console.warn(`[vinext] absorbed ${kind} ${code} (asset URL import)`);
+		}
+		return true;
+	};
+	process.on("uncaughtException", (err) => {
+		if (absorbBenignAssetImport(err, "uncaughtException")) return;
+		if (process.env.VINEXT_PRERENDER === "1") throw err;
+		const code = peerDisconnectCode(err);
+		if (code) {
+			if (debug) console.warn(`[vinext] absorbed uncaughtException ${code}`);
+			return;
+		}
+		throw err;
+	});
+	process.on("unhandledRejection", (reason) => {
+		if (absorbBenignAssetImport(reason, "unhandledRejection")) return;
+		if (process.env.VINEXT_PRERENDER === "1") throw reason;
+		const code = peerDisconnectCode(reason);
+		if (code) {
+			if (debug) console.warn(`[vinext] absorbed unhandledRejection ${code}`);
+			return;
+		}
+		throw reason;
+	});
+}
+//#endregion
+export { installSocketErrorBackstop, isBenignAssetImportError, isSocketErrorBackstopInstalled, peerDisconnectCode };

package/dist/server/static-file-cache.d.ts

@@ -0,0 +1,56 @@
+//#region src/server/static-file-cache.d.ts
+/** Content-type lookup for static assets. Shared with prod-server.ts. */
+declare const CONTENT_TYPES: Record<string, string>;
+/** A servable file variant with pre-computed response headers. */
+type FileVariant = {
+  /** Absolute file path (used for streaming large files). */path: string; /** Uncompressed or encoded byte size for buffer-threshold decisions. */
+  size: number; /** Pre-computed response headers. */
+  headers: Record<string, string>; /** In-memory buffer for small files (below BUFFER_THRESHOLD). */
+  buffer?: Buffer;
+};
+type StaticFileEntry = {
+  /** Weak ETag for conditional request matching. */etag: string; /** Pre-computed headers for 304 Not Modified response. */
+  notModifiedHeaders: Record<string, string>; /** Original file variant (uncompressed). */
+  original: FileVariant; /** Brotli precompressed variant, if .br file exists. */
+  br?: FileVariant; /** Gzip precompressed variant, if .gz file exists. */
+  gz?: FileVariant; /** Zstandard precompressed variant, if .zst file exists. */
+  zst?: FileVariant;
+};
+/**
+ * In-memory cache of static file metadata, populated once at server startup.
+ *
+ * Usage:
+ *   const cache = await StaticFileCache.create(clientDir);
+ *   const entry = cache.lookup("/_next/static/app-abc123.js");
+ *   // entry.br?.headers, entry.original.headers, etc.
+ */
+declare class StaticFileCache {
+  private readonly entries;
+  private constructor();
+  /**
+   * Scan the client directory and build the cache.
+   *
+   * Gracefully handles non-existent directories (returns an empty cache).
+   */
+  static create(clientDir: string): Promise<StaticFileCache>;
+  /**
+   * Look up cached metadata for a URL pathname.
+   *
+   * Returns undefined if the file is not in the cache. The root path "/"
+   * always returns undefined — index.html is served by SSR/RSC.
+   */
+  lookup(pathname: string): StaticFileEntry | undefined;
+}
+/**
+ * Extract a stable weak ETag from a Vite hashed filename (e.g. `app-DqZc3R4n.js`).
+ * The hash is a content hash computed by the bundler — deterministic across
+ * identical builds regardless of filesystem timestamps.
+ *
+ * Must be a weak validator (W/) because the same tag is shared across
+ * content-encoded variants (original, .br, .gz, .zst) which are byte-different.
+ * Returns null if the filename doesn't contain a recognizable hash suffix,
+ * so the caller can fall back to mtime-based ETags.
+ */
+declare function etagFromFilenameHash(relativePath: string, ext: string): string | null;
+//#endregion
+export { CONTENT_TYPES, StaticFileCache, etagFromFilenameHash };