vinext 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/server/http-conditional.d.ts

@@ -0,0 +1,22 @@
+//#region src/server/http-conditional.d.ts
+/**
+ * Test an If-None-Match field value against a current entity tag.
+ *
+ * RFC 9110 requires weak comparison for If-None-Match: a weak and strong
+ * validator with the same opaque tag compare equal.
+ */
+declare function matchesIfNoneMatch(ifNoneMatch: string | undefined, etag: string): boolean;
+/** Test an If-Match field using Next.js's weak/strong-equivalent comparison. */
+declare function matchesIfMatch(ifMatch: string | undefined, etag: string | undefined): boolean;
+type StaticConditionalHeaders = {
+  cacheControl?: string | string[];
+  ifMatch?: string | string[];
+  ifUnmodifiedSince?: string | string[];
+  ifNoneMatch?: string | string[];
+  ifModifiedSince?: string | string[];
+};
+type StaticPreconditionResult = "proceed" | "not-modified" | "precondition-failed";
+/** Evaluate static representation preconditions in RFC 9110 section 13.2.2 order. */
+declare function evaluateStaticPreconditions(headers: StaticConditionalHeaders, method: string | undefined, etag: string | undefined, mtimeMs: number): StaticPreconditionResult;
+//#endregion
+export { StaticPreconditionResult, evaluateStaticPreconditions, matchesIfMatch, matchesIfNoneMatch };

package/dist/server/http-conditional.js

@@ -0,0 +1,117 @@
+import { parseHttpDate } from "./http-date.js";
+//#region src/server/http-conditional.ts
+/**
+* Test an If-None-Match field value against a current entity tag.
+*
+* RFC 9110 requires weak comparison for If-None-Match: a weak and strong
+* validator with the same opaque tag compare equal.
+*/
+function matchesIfNoneMatch(ifNoneMatch, etag) {
+	if (!ifNoneMatch) return false;
+	const current = parseEntityTag(etag, 0);
+	if (!current || current.end !== etag.length) return false;
+	const currentOpaqueTag = etag.slice(current.opaqueStart, current.opaqueEnd);
+	let index = skipOptionalWhitespace(ifNoneMatch, 0);
+	if (ifNoneMatch[index] === "*") return skipOptionalWhitespace(ifNoneMatch, index + 1) === ifNoneMatch.length;
+	let matched = false;
+	let sawTag = false;
+	while (index < ifNoneMatch.length) {
+		if (ifNoneMatch[index] === ",") {
+			index = skipOptionalWhitespace(ifNoneMatch, index + 1);
+			continue;
+		}
+		const candidate = parseEntityTag(ifNoneMatch, index);
+		if (!candidate) return false;
+		sawTag = true;
+		matched ||= ifNoneMatch.slice(candidate.opaqueStart, candidate.opaqueEnd) === currentOpaqueTag;
+		index = skipOptionalWhitespace(ifNoneMatch, candidate.end);
+		if (index === ifNoneMatch.length) break;
+		if (ifNoneMatch[index] !== ",") return false;
+		index = skipOptionalWhitespace(ifNoneMatch, index + 1);
+	}
+	return sawTag && matched;
+}
+/** Test an If-Match field using Next.js's weak/strong-equivalent comparison. */
+function matchesIfMatch(ifMatch, etag) {
+	if (!ifMatch) return false;
+	let index = skipOptionalWhitespace(ifMatch, 0);
+	if (ifMatch[index] === "*") return skipOptionalWhitespace(ifMatch, index + 1) === ifMatch.length;
+	if (!etag) return false;
+	const current = parseEntityTag(etag, 0);
+	if (!current || current.end !== etag.length) return false;
+	const currentOpaqueTag = etag.slice(current.opaqueStart, current.opaqueEnd);
+	let matched = false;
+	let sawTag = false;
+	while (index < ifMatch.length) {
+		if (ifMatch[index] === ",") {
+			index = skipOptionalWhitespace(ifMatch, index + 1);
+			continue;
+		}
+		const candidate = parseEntityTag(ifMatch, index);
+		if (!candidate) return false;
+		sawTag = true;
+		matched ||= ifMatch.slice(candidate.opaqueStart, candidate.opaqueEnd) === currentOpaqueTag;
+		index = skipOptionalWhitespace(ifMatch, candidate.end);
+		if (index === ifMatch.length) break;
+		if (ifMatch[index] !== ",") return false;
+		index = skipOptionalWhitespace(ifMatch, index + 1);
+	}
+	return sawTag && matched;
+}
+function parseEntityTag(value, start) {
+	let index = start;
+	const weak = value.startsWith("W/", index);
+	if (weak) index += 2;
+	if (value[index] !== "\"") return null;
+	const opaqueStart = ++index;
+	while (index < value.length && value[index] !== "\"") {
+		const code = value.charCodeAt(index);
+		if (!(code === 33 || code >= 35 && code <= 126 || code >= 128 && code <= 255)) return null;
+		index++;
+	}
+	if (value[index] !== "\"") return null;
+	return {
+		weak,
+		opaqueStart,
+		opaqueEnd: index,
+		end: index + 1
+	};
+}
+function skipOptionalWhitespace(value, start) {
+	let index = start;
+	while (value[index] === " " || value[index] === "	") index++;
+	return index;
+}
+/** Evaluate static representation preconditions in RFC 9110 section 13.2.2 order. */
+function evaluateStaticPreconditions(headers, method, etag, mtimeMs) {
+	const ifMatch = joinHeader(headers.ifMatch);
+	if (ifMatch !== void 0) {
+		if (!matchesIfMatch(ifMatch, etag)) return "precondition-failed";
+	} else {
+		const ifUnmodifiedSince = joinHeader(headers.ifUnmodifiedSince);
+		if (ifUnmodifiedSince) {
+			const unmodifiedSinceMs = parseHttpDate(ifUnmodifiedSince);
+			if (Number.isFinite(unmodifiedSinceMs) && Number.isFinite(mtimeMs) && Math.floor(mtimeMs / 1e3) > Math.floor(unmodifiedSinceMs / 1e3)) return "precondition-failed";
+		}
+	}
+	const ifNoneMatch = joinHeader(headers.ifNoneMatch);
+	if (ifNoneMatch !== void 0) {
+		if (!(ifNoneMatch.trim() === "*" || etag !== void 0 && matchesIfNoneMatch(ifNoneMatch, etag))) return "proceed";
+		if (method !== "GET" && method !== "HEAD") return "precondition-failed";
+		const cacheControl = joinHeader(headers.cacheControl);
+		return cacheControl && /(?:^|,)\s*no-cache\s*(?:,|$)/i.test(cacheControl) ? "proceed" : "not-modified";
+	}
+	if (method !== "GET" && method !== "HEAD") return "proceed";
+	const cacheControl = joinHeader(headers.cacheControl);
+	if (cacheControl && /(?:^|,)\s*no-cache\s*(?:,|$)/i.test(cacheControl)) return "proceed";
+	const ifModifiedSince = joinHeader(headers.ifModifiedSince);
+	if (!ifModifiedSince) return "proceed";
+	const modifiedSinceMs = parseHttpDate(ifModifiedSince);
+	if (!Number.isFinite(modifiedSinceMs)) return "proceed";
+	return Number.isFinite(mtimeMs) && Math.floor(mtimeMs / 1e3) <= Math.floor(modifiedSinceMs / 1e3) ? "not-modified" : "proceed";
+}
+function joinHeader(value) {
+	return Array.isArray(value) ? value.join(", ") : value;
+}
+//#endregion
+export { evaluateStaticPreconditions, matchesIfMatch, matchesIfNoneMatch };

package/dist/server/http-date.d.ts

@@ -0,0 +1,5 @@
+//#region src/server/http-date.d.ts
+/** Parse only the three HTTP-date wire formats accepted by RFC 9110. */
+declare function parseHttpDate(value: string): number;
+//#endregion
+export { parseHttpDate };

package/dist/server/http-date.js

@@ -0,0 +1,73 @@
+//#region src/server/http-date.ts
+const IMF_FIXDATE_RE = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+const RFC850_DATE_RE = /^(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\d{2})-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+const ASCTIME_DATE_RE = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (?: (\d)|(\d{2})) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/;
+const WEEKDAY_INDEX = {
+	Sun: 0,
+	Sunday: 0,
+	Mon: 1,
+	Monday: 1,
+	Tue: 2,
+	Tuesday: 2,
+	Wed: 3,
+	Wednesday: 3,
+	Thu: 4,
+	Thursday: 4,
+	Fri: 5,
+	Friday: 5,
+	Sat: 6,
+	Saturday: 6
+};
+const MONTH_INDEX = {
+	Jan: 0,
+	Feb: 1,
+	Mar: 2,
+	Apr: 3,
+	May: 4,
+	Jun: 5,
+	Jul: 6,
+	Aug: 7,
+	Sep: 8,
+	Oct: 9,
+	Nov: 10,
+	Dec: 11
+};
+/** Parse only the three HTTP-date wire formats accepted by RFC 9110. */
+function parseHttpDate(value) {
+	const imf = IMF_FIXDATE_RE.exec(value);
+	if (imf) return timestampFromHttpDateParts(imf[1], imf[2], imf[3], imf[4], imf[5], imf[6], imf[7]);
+	const rfc850 = RFC850_DATE_RE.exec(value);
+	if (rfc850) {
+		const now = /* @__PURE__ */ new Date();
+		let year = now.getUTCFullYear() - now.getUTCFullYear() % 100 + Number(rfc850[4]);
+		const candidateTimestamp = timestampForRfc850YearWindow(rfc850[2], rfc850[3], String(year), rfc850[5], rfc850[6], rfc850[7]);
+		const fiftyYearsFromNow = new Date(now);
+		fiftyYearsFromNow.setUTCFullYear(now.getUTCFullYear() + 50);
+		if (candidateTimestamp > fiftyYearsFromNow.getTime()) year -= 100;
+		return timestampFromHttpDateParts(rfc850[1], rfc850[2], rfc850[3], String(year), rfc850[5], rfc850[6], rfc850[7]);
+	}
+	const asctime = ASCTIME_DATE_RE.exec(value);
+	if (asctime) return timestampFromHttpDateParts(asctime[1], asctime[3] || asctime[4], asctime[2], asctime[8], asctime[5], asctime[6], asctime[7]);
+	return NaN;
+}
+function timestampForRfc850YearWindow(dayValue, monthValue, yearValue, hourValue, minuteValue, secondValue) {
+	const date = /* @__PURE__ */ new Date(0);
+	date.setUTCFullYear(Number(yearValue), MONTH_INDEX[monthValue], Number(dayValue));
+	date.setUTCHours(Number(hourValue), Number(minuteValue), Number(secondValue), 0);
+	return date.getTime();
+}
+function timestampFromHttpDateParts(weekday, dayValue, monthValue, yearValue, hourValue, minuteValue, secondValue) {
+	const day = Number(dayValue);
+	const month = MONTH_INDEX[monthValue];
+	const year = Number(yearValue);
+	const hour = Number(hourValue);
+	const minute = Number(minuteValue);
+	const second = Number(secondValue);
+	const date = /* @__PURE__ */ new Date(0);
+	date.setUTCFullYear(year, month, day);
+	date.setUTCHours(hour, minute, second, 0);
+	if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month || date.getUTCDate() !== day || date.getUTCHours() !== hour || date.getUTCMinutes() !== minute || date.getUTCSeconds() !== second || weekday !== void 0 && date.getUTCDay() !== WEEKDAY_INDEX[weekday]) return NaN;
+	return date.getTime();
+}
+//#endregion
+export { parseHttpDate };

package/dist/server/http-error-responses.d.ts

@@ -19,6 +19,7 @@
 type ErrorResponseInit = {
   headers?: HeadersInit;
 };
+declare function sanitizeMethodNotAllowedHeaders(headers: Headers, allowedMethods: string): void;
 /**
  * Build a 400 Bad Request plain-text response.
  *
@@ -88,4 +89,4 @@ declare function payloadTooLargeResponse(): Response;
  */
 declare function internalServerErrorResponse(message?: string, init?: ErrorResponseInit): Response;
 //#endregion
-export { badRequestResponse, forbiddenResponse, internalServerErrorResponse, methodNotAllowedResponse, notFoundResponse, notFoundStaticAssetResponse, payloadTooLargeResponse };
+export { badRequestResponse, forbiddenResponse, internalServerErrorResponse, methodNotAllowedResponse, notFoundResponse, notFoundStaticAssetResponse, payloadTooLargeResponse, sanitizeMethodNotAllowedHeaders };

package/dist/server/http-error-responses.js

@@ -1,4 +1,16 @@
 //#region src/server/http-error-responses.ts
+const METHOD_NOT_ALLOWED_BODY_HEADERS = [
+	"content-encoding",
+	"content-length",
+	"content-range",
+	"content-type",
+	"transfer-encoding"
+];
+function sanitizeMethodNotAllowedHeaders(headers, allowedMethods) {
+	for (const name of METHOD_NOT_ALLOWED_BODY_HEADERS) headers.delete(name);
+	headers.set("Allow", allowedMethods);
+	headers.set("Content-Type", "text/plain; charset=utf-8");
+}
 /**
 * Build a 400 Bad Request plain-text response.
 *
@@ -74,7 +86,7 @@ function notFoundStaticAssetResponse() {
 */
 function methodNotAllowedResponse(allowedMethods, init) {
 	const headers = new Headers(init?.headers);
-	headers.set("Allow", allowedMethods);
+	sanitizeMethodNotAllowedHeaders(headers, allowedMethods);
 	return new Response("Method Not Allowed", {
 		status: 405,
 		headers
@@ -102,4 +114,4 @@ function internalServerErrorResponse(message, init) {
 	});
 }
 //#endregion
-export { badRequestResponse, forbiddenResponse, internalServerErrorResponse, methodNotAllowedResponse, notFoundResponse, notFoundStaticAssetResponse, payloadTooLargeResponse };
+export { badRequestResponse, forbiddenResponse, internalServerErrorResponse, methodNotAllowedResponse, notFoundResponse, notFoundStaticAssetResponse, payloadTooLargeResponse, sanitizeMethodNotAllowedHeaders };

package/dist/server/http-range.d.ts

@@ -0,0 +1,25 @@
+//#region src/server/http-range.d.ts
+type ByteRange = {
+  kind: "ignore";
+} | {
+  kind: "unsatisfiable";
+} | {
+  kind: "range";
+  start: number;
+  end: number;
+};
+/**
+ * Parse a single bytes range. Unsupported range units, malformed values, and
+ * multipart ranges are ignored, which RFC 9110 permits servers to do.
+ */
+declare function parseByteRange(value: string | undefined, size: number): ByteRange;
+/**
+ * If-Range requires strong entity-tag comparison. Date validators are matched
+ * at HTTP-date (whole-second) precision because filesystem mtimes are finer,
+ * and allow a range when the representation has not changed since that date.
+ * Vinext's static ETags are currently weak, so its emitted Last-Modified value
+ * is the validator that can enable a range response on a later request.
+ */
+declare function ifRangeAllowsRange(value: string | undefined, etag: string, mtimeMs: number): boolean;
+//#endregion
+export { ByteRange, ifRangeAllowsRange, parseByteRange };

package/dist/server/http-range.js

@@ -0,0 +1,67 @@
+import { parseHttpDate } from "./http-date.js";
+//#region src/server/http-range.ts
+/**
+* Parse a single bytes range. Unsupported range units, malformed values, and
+* multipart ranges are ignored, which RFC 9110 permits servers to do.
+*/
+function parseByteRange(value, size) {
+	if (!value || value.slice(0, 6).toLowerCase() !== "bytes=") return { kind: "ignore" };
+	const spec = value.slice(6).trim();
+	if (spec.includes(",")) return { kind: "ignore" };
+	const match = /^(\d*)-(\d*)$/.exec(spec);
+	if (!match || !match[1] && !match[2]) return { kind: "ignore" };
+	if (!match[1]) {
+		const suffixLength = parseDecimalInteger(match[2]);
+		if (suffixLength === "overflow") {
+			if (size === 0) return { kind: "unsatisfiable" };
+			return {
+				kind: "range",
+				start: 0,
+				end: size - 1
+			};
+		}
+		if (suffixLength === 0 || size === 0) return { kind: "unsatisfiable" };
+		return {
+			kind: "range",
+			start: Math.max(size - suffixLength, 0),
+			end: size - 1
+		};
+	}
+	const start = parseDecimalInteger(match[1]);
+	const requestedEnd = match[2] ? parseDecimalInteger(match[2]) : size - 1;
+	if (start === "overflow") return { kind: "unsatisfiable" };
+	if (requestedEnd === "overflow") {
+		if (start >= size) return { kind: "unsatisfiable" };
+		return {
+			kind: "range",
+			start,
+			end: size - 1
+		};
+	}
+	if (start >= size || requestedEnd < start) return { kind: "unsatisfiable" };
+	return {
+		kind: "range",
+		start,
+		end: Math.min(requestedEnd, size - 1)
+	};
+}
+/**
+* If-Range requires strong entity-tag comparison. Date validators are matched
+* at HTTP-date (whole-second) precision because filesystem mtimes are finer,
+* and allow a range when the representation has not changed since that date.
+* Vinext's static ETags are currently weak, so its emitted Last-Modified value
+* is the validator that can enable a range response on a later request.
+*/
+function ifRangeAllowsRange(value, etag, mtimeMs) {
+	if (!value) return true;
+	const trimmed = value.trim();
+	if (trimmed.startsWith("\"") || trimmed.startsWith("W/")) return !trimmed.startsWith("W/") && !etag.startsWith("W/") && trimmed === etag;
+	const timestamp = parseHttpDate(trimmed);
+	return Number.isFinite(timestamp) && Math.floor(mtimeMs / 1e3) * 1e3 <= timestamp;
+}
+function parseDecimalInteger(value) {
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) ? parsed : "overflow";
+}
+//#endregion
+export { ifRangeAllowsRange, parseByteRange };

package/dist/server/image-optimization.d.ts

@@ -44,14 +44,17 @@ declare function isImageOptimizationPath(pathname: string): boolean;
  * Controls SVG handling and security headers for the image endpoint.
  */
 type ImageConfig = {
-  /** Allowed device widths. Defaults to Next.js device sizes. */deviceSizes?: number[]; /** Allowed fixed-image widths. Defaults to Next.js image sizes. */
+  /** Allowed device widths. Defaults to Next.js device sizes. */
+  deviceSizes?: number[];
+  /** Allowed fixed-image widths. Defaults to Next.js image sizes. */
   imageSizes?: number[];
   /**
    * Allowed output qualities. When unset, any quality from 1-100 is permitted
    * (matches Next.js: an unset `images.qualities` is not restricted to a single
    * value). When set, only the listed qualities are accepted.
    */
-  qualities?: number[]; /** Allow SVG through the image optimization endpoint. Default: false. */
+  qualities?: number[];
+  /** Allow SVG through the image optimization endpoint. Default: false. */
   dangerouslyAllowSVG?: boolean;
   /**
    * Allow image optimization for hostnames that resolve to private IP addresses.
@@ -62,8 +65,10 @@ type ImageConfig = {
    * there is no active server-side SSRF vector — the flag is consumed client-side
    * via the image shim instead.
    */
-  dangerouslyAllowLocalIP?: boolean; /** Content-Disposition header value. Default: "inline". */
-  contentDispositionType?: "inline" | "attachment"; /** Content-Security-Policy header value. Default: "script-src 'none'; frame-src 'none'; sandbox;" */
+  dangerouslyAllowLocalIP?: boolean;
+  /** Content-Disposition header value. Default: "inline". */
+  contentDispositionType?: "inline" | "attachment";
+  /** Content-Security-Policy header value. Default: "script-src 'none'; frame-src 'none'; sandbox;" */
   contentSecurityPolicy?: string;
 };
 /**
@@ -117,7 +122,9 @@ declare function isSafeImageContentType(contentType: string | null, dangerouslyA
  * Workers provide these callbacks to adapt their specific bindings.
  */
 type ImageHandlers = {
-  /** Fetch the source image from storage (e.g., Cloudflare ASSETS binding). */fetchAsset: (path: string, request: Request) => Promise<Response>; /** Optional: Transform the image (resize, format, quality). */
+  /** Fetch the source image from storage (e.g., Cloudflare ASSETS binding). */
+  fetchAsset: (path: string, request: Request) => Promise<Response>;
+  /** Optional: Transform the image (resize, format, quality). */
   transformImage?: (body: ReadableStream, options: {
     width: number;
     format: string;
@@ -139,7 +146,8 @@ declare function handleImageOptimization(request: Request, handlers: ImageHandle
  * {@link setImageOptimizer}.
  */
 type ImageOptimizer = {
-  /** Transform the source image (resize, format, quality). */transformImage: (body: ReadableStream, options: {
+  /** Transform the source image (resize, format, quality). */
+  transformImage: (body: ReadableStream, options: {
     width: number;
     format: string;
     quality: number;

package/dist/server/image-optimization.js

@@ -59,7 +59,6 @@ const DEFAULT_DEVICE_SIZES = [
 	3840
 ];
 const DEFAULT_IMAGE_SIZES = [
-	16,
 	32,
 	48,
 	64,

package/dist/server/instrumentation.d.ts

@@ -1,5 +1,4 @@
 import { ValidFileMatcher } from "../routing/file-matcher.js";
-
 //#region src/server/instrumentation.d.ts
 /**
  * Minimal duck-typed interface for the module runner passed to
@@ -31,9 +30,13 @@ declare function findInstrumentationClientFile(root: string, fileMatcher: ValidF
  * Provides the error, the request info, and an error context.
  */
 type OnRequestErrorContext = {
-  /** The route path (e.g., '/blog/[slug]') */routerKind: "Pages Router" | "App Router"; /** The matched route pattern */
-  routePath: string; /** The route type */
-  routeType: "render" | "route" | "action" | "middleware"; /** HTTP status code that will be sent */
+  /** The route path (e.g., '/blog/[slug]') */
+  routerKind: "Pages Router" | "App Router";
+  /** The matched route pattern */
+  routePath: string;
+  /** The route type */
+  routeType: "render" | "route" | "action" | "middleware";
+  /** HTTP status code that will be sent */
   revalidateReason?: "on-demand" | "stale" | undefined;
 };
 type OnRequestErrorHandler = (error: Error, request: {

package/dist/server/isr-cache.d.ts

@@ -3,8 +3,7 @@ import { RenderObservation } from "./cache-proof.js";
 import { AppRscRenderMode } from "./app-rsc-render-mode.js";
 import { PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER } from "../utils/protocol-headers.js";
 import { normalizeMountedSlotsHeader } from "./app-mounted-slots-header.js";
-import { CacheHandlerValue, CachedAppPageValue, CachedPagesValue, IncrementalCacheValue } from "../shims/cache-handler.js";
-
+import { CacheControlMetadata, CacheHandlerValue, CachedAppPageValue, CachedPagesValue, IncrementalCacheValue } from "../shims/cache-handler.js";
 //#region src/server/isr-cache.d.ts
 declare function getRevalidateSecret(): string;
 declare function isRevalidateSecret(value: string | null | undefined): boolean;
@@ -17,7 +16,8 @@ declare function isRevalidateSecret(value: string | null | undefined): boolean;
 declare function isOnDemandRevalidateRequest(headerValue: string | string[] | null | undefined): boolean;
 type ISRCacheEntry = {
   value: CacheHandlerValue;
-  isStale: boolean; /** The entry crossed its hard expire boundary and must not be served. */
+  isStale: boolean;
+  /** The entry crossed its hard expire boundary and must not be served. */
   isExpired?: boolean;
 };
 /**
@@ -30,12 +30,34 @@ type ISRCacheEntry = {
  */
 declare function isrGet(key: string): Promise<ISRCacheEntry | null>;
 /**
- * Store a value in the ISR cache with a revalidation period.
+ * Assemble cache-control metadata, omitting the dimensions the producing
+ * render made no claim about. Shared by every ISR writer so `expire`/`stale`
+ * are never invented from `revalidate`.
  */
-declare function isrSet(key: string, data: IncrementalCacheValue | null, revalidateSeconds: number | false, tags?: string[], expireSeconds?: number): Promise<void>;
+declare function isrCacheControl(revalidateSeconds: number | false, claims?: {
+  expireSeconds?: number;
+  staleSeconds?: number;
+}): CacheControlMetadata;
+/**
+ * Write policy for one ISR entry: the cache metadata the producing render
+ * resolved, plus the tags that can invalidate it. Routers differ only in which
+ * `cacheControl` dimensions they populate — App pages carry the client-router
+ * `stale` bound, Pages Router and route handlers do not.
+ */
+type IsrWritePolicy = {
+  cacheControl: CacheControlMetadata;
+  tags?: string[];
+};
+/**
+ * Store a value in the ISR cache under the given write policy.
+ */
+declare function isrSet(key: string, data: IncrementalCacheValue | null, policy: IsrWritePolicy): Promise<void>;
+type AppPageCacheSetter = (key: string, data: CachedAppPageValue, policy: IsrWritePolicy) => Promise<void>;
 declare function isrSetPrerenderedAppPage(key: string, data: CachedAppPageValue, metadata: {
   expireSeconds?: number;
   revalidateSeconds?: number;
+  /** Client reuse bound from the prerender's `cacheLife`. */
+  staleSeconds?: number;
   /**
    * Implicit/path tags to attach to the seeded entry. Required so that
    * `revalidatePath()` (and `revalidateTag()`) can invalidate prerender-seeded
@@ -110,4 +132,4 @@ declare function setRevalidateDuration(key: string, seconds: number): void;
  */
 declare function getRevalidateDuration(key: string): number | undefined;
 //#endregion
-export { ISRCacheEntry, PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER, appIsrCacheKey, appIsrHtmlKey, appIsrRouteKey, appIsrRscKey, buildAppPageCacheValue, buildPagesCacheValue, coalesceOnDemandRevalidation, getRevalidateDuration, getRevalidateSecret, isOnDemandRevalidateRequest, isRevalidateSecret, isrCacheKey, isrGet, isrSet, isrSetPrerenderedAppPage, normalizeMountedSlotsHeader, setRevalidateDuration, triggerBackgroundRegeneration };
+export { AppPageCacheSetter, ISRCacheEntry, IsrWritePolicy, PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER, appIsrCacheKey, appIsrHtmlKey, appIsrRouteKey, appIsrRscKey, buildAppPageCacheValue, buildPagesCacheValue, coalesceOnDemandRevalidation, getRevalidateDuration, getRevalidateSecret, isOnDemandRevalidateRequest, isRevalidateSecret, isrCacheControl, isrCacheKey, isrGet, isrSet, isrSetPrerenderedAppPage, normalizeMountedSlotsHeader, setRevalidateDuration, triggerBackgroundRegeneration };

package/dist/server/isr-cache.js

@@ -89,16 +89,25 @@ async function isrGet(key) {
 	};
 }
 /**
-* Store a value in the ISR cache with a revalidation period.
+* Assemble cache-control metadata, omitting the dimensions the producing
+* render made no claim about. Shared by every ISR writer so `expire`/`stale`
+* are never invented from `revalidate`.
 */
-async function isrSet(key, data, revalidateSeconds, tags, expireSeconds) {
-	await getCdnCacheAdapter().set(key, data, {
-		cacheControl: expireSeconds === void 0 ? { revalidate: revalidateSeconds } : {
-			revalidate: revalidateSeconds,
-			expire: expireSeconds
-		},
+function isrCacheControl(revalidateSeconds, claims = {}) {
+	return {
 		revalidate: revalidateSeconds,
-		tags: tags ?? []
+		...claims.expireSeconds === void 0 ? {} : { expire: claims.expireSeconds },
+		...claims.staleSeconds === void 0 ? {} : { stale: claims.staleSeconds }
+	};
+}
+/**
+* Store a value in the ISR cache under the given write policy.
+*/
+async function isrSet(key, data, policy) {
+	await getCdnCacheAdapter().set(key, data, {
+		cacheControl: policy.cacheControl,
+		revalidate: policy.cacheControl.revalidate,
+		tags: policy.tags ?? []
 	});
 }
 async function isrSetPrerenderedAppPage(key, data, metadata) {
@@ -108,10 +117,7 @@ async function isrSetPrerenderedAppPage(key, data, metadata) {
 	const ctx = {};
 	if (revalidateSeconds !== void 0) {
 		ctx.revalidate = revalidateSeconds;
-		ctx.cacheControl = metadata.expireSeconds === void 0 ? { revalidate: revalidateSeconds } : {
-			revalidate: revalidateSeconds,
-			expire: metadata.expireSeconds
-		};
+		ctx.cacheControl = isrCacheControl(revalidateSeconds, metadata);
 	}
 	if (tags && tags.length > 0) ctx.tags = tags;
 	await getCdnCacheAdapter().set(key, data, ctx);
@@ -273,4 +279,4 @@ function getRevalidateDuration(key) {
 	return revalidateDurations.get(key);
 }
 //#endregion
-export { PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER, appIsrCacheKey, appIsrHtmlKey, appIsrRouteKey, appIsrRscKey, buildAppPageCacheValue, buildPagesCacheValue, coalesceOnDemandRevalidation, getRevalidateDuration, getRevalidateSecret, isOnDemandRevalidateRequest, isRevalidateSecret, isrCacheKey, isrGet, isrSet, isrSetPrerenderedAppPage, normalizeMountedSlotsHeader, setRevalidateDuration, triggerBackgroundRegeneration };
+export { PRERENDER_REVALIDATE_HEADER, PRERENDER_REVALIDATE_ONLY_GENERATED_HEADER, appIsrCacheKey, appIsrHtmlKey, appIsrRouteKey, appIsrRscKey, buildAppPageCacheValue, buildPagesCacheValue, coalesceOnDemandRevalidation, getRevalidateDuration, getRevalidateSecret, isOnDemandRevalidateRequest, isRevalidateSecret, isrCacheControl, isrCacheKey, isrGet, isrSet, isrSetPrerenderedAppPage, normalizeMountedSlotsHeader, setRevalidateDuration, triggerBackgroundRegeneration };

package/dist/server/isr-decision.d.ts

@@ -1,11 +1,12 @@
 import { CacheControlMetadata } from "../shims/cache-handler.js";
 import { NEVER_CACHE_CONTROL, NO_STORE_CACHE_CONTROL } from "./cache-control.js";
-
 //#region src/server/isr-decision.d.ts
 type IsrDisposition = "HIT" | "STALE" | "MISS";
 type IsrDecision = {
-  disposition: IsrDisposition; /** True when the caller must schedule a background regeneration. */
-  scheduleRegeneration: boolean; /** The `Cache-Control` string to stamp on the response. */
+  disposition: IsrDisposition;
+  /** True when the caller must schedule a background regeneration. */
+  scheduleRegeneration: boolean;
+  /** The `Cache-Control` string to stamp on the response. */
   cacheControl: string;
 };
 /**
@@ -24,7 +25,8 @@ type DecideIsrOptions = {
    * query-variant-unproven) must have already passed before passing
    * `"HIT"` or `"STALE"` here.
    */
-  cacheState: "HIT" | "STALE" | "MISS"; /** Which router is making the decision. */
+  cacheState: "HIT" | "STALE" | "MISS";
+  /** Which router is making the decision. */
   kind: IsrPolicyKind;
   /**
    * The route's configured revalidate window in seconds. Used as the fallback

package/dist/server/metadata-route-build-data.d.ts

@@ -1,5 +1,4 @@
 import { MetadataFileRoute, MetadataRouteHeadData } from "./metadata-routes.js";
-
 //#region src/server/metadata-route-build-data.d.ts
 type MetadataRouteEntrySourceInput = {
   entryData: MetadataRouteEntryData;

package/dist/server/metadata-route-response.d.ts

@@ -1,5 +1,4 @@
 import { MetadataFileRoute } from "./metadata-routes.js";
-
 //#region src/server/metadata-route-response.d.ts
 type AppPageParams = Record<string, string | string[]>;
 type MetadataRouteMakeThenableParams = (params: AppPageParams) => unknown;

package/dist/server/metadata-route-response.js

@@ -1,3 +1,4 @@
+import { markFullyBufferedBody } from "../shims/unified-request-context.js";
 import { notFoundResponse } from "./http-error-responses.js";
 import { isValidMetadataImageId, manifestToJson, matchMetadataRoutePattern, robotsToText, sitemapToXml } from "./metadata-routes.js";
 //#region src/server/metadata-route-response.ts
@@ -115,10 +116,10 @@ async function handleGeneratedSitemap(route, cleanPathname, functions) {
 	const result = await functions.defaultExport({ id: makeThenableMetadataRouteId(matchedId) });
 	if (result instanceof Response) return withMetadataRouteCacheHeader(result, route);
 	if (!isSitemapEntries(result)) throw new TypeError("Metadata sitemap routes must return an array.");
-	return new Response(sitemapToXml(result), { headers: {
+	return markFullyBufferedBody(new Response(sitemapToXml(result), { headers: {
 		"Content-Type": route.contentType,
 		"Cache-Control": metadataRouteCacheHeader(route)
-	} });
+	} }));
 }
 function findGeneratedImageId(imageMetadata, imageId, servedUrl) {
 	if (!Array.isArray(imageMetadata)) return null;
@@ -163,10 +164,10 @@ async function callDynamicMetadataRoute(route, match, makeThenableParams, functi
 		body = manifestToJson(result);
 	} else if (isImageMetadataRoute(route)) throw new TypeError(`Dynamic metadata ${route.type} route ${route.servedUrl} must return a Response.`);
 	else body = JSON.stringify(result);
-	return new Response(body, { headers: {
+	return markFullyBufferedBody(new Response(body, { headers: {
 		"Content-Type": route.contentType,
 		"Cache-Control": metadataRouteCacheHeader(route)
-	} });
+	} }));
 }
 function serveStaticMetadataRoute(route) {
 	if (typeof route.fileDataBase64 !== "string") throw new Error(`[vinext] Static metadata route ${route.servedUrl} is missing embedded file data.`);
@@ -174,10 +175,10 @@ function serveStaticMetadataRoute(route) {
 		const binary = atob(route.fileDataBase64);
 		const bytes = new Uint8Array(binary.length);
 		for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
-		return new Response(bytes, { headers: {
+		return markFullyBufferedBody(new Response(bytes, { headers: {
 			"Content-Type": route.contentType,
 			"Cache-Control": metadataRouteCacheHeader(route)
-		} });
+		} }));
 	} catch (error) {
 		const reason = error instanceof Error && error.message ? `: ${error.message}` : "";
 		throw new Error(`[vinext] Failed to decode embedded metadata route file data for ${route.servedUrl}${reason}`, { cause: error });