@vinext/cloudflare 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/cdn-warm.js

@@ -1,9 +1,28 @@
-import path from "node:path";
+import { VINEXT_CDN_BUILD_ID_HEADER } from "./cache/cdn-build-id.js";
 import fs from "node:fs";
+import path from "node:path";
+import { cacheabilityRoutePathname } from "vinext/internal/server/cacheability-manifest";
+import { randomUUID } from "node:crypto";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { VINEXT_CACHE_HEADER, VINEXT_PRERENDER_READINESS_HEADER, VINEXT_PRERENDER_READINESS_PATH, VINEXT_PRERENDER_SECRET_HEADER } from "vinext/internal/server/headers";
 import { PRERENDER_PATHS_MANIFEST } from "vinext/internal/build/prerender-paths";
 import { getPrerenderedConcretePaths, readPrerenderManifest } from "vinext/internal/server/prerender-manifest";
+import { VINEXT_RSC_BUILD_ID_HEADER, VINEXT_RSC_CONTENT_TYPE, VINEXT_RSC_VARY_HEADER as VINEXT_RSC_VARY_HEADER$1, createCanonicalLoadingShellRscRequestHeaders, createCanonicalRscRequestHeaders, createCanonicalRscRequestUrl, createRscRequestUrl } from "vinext/internal/server/app-rsc-cache-busting";
+import { isNonCacheableCacheControl } from "vinext/shims/cdn-cache";
+import { normalizePathTrailingSlash } from "vinext/shims/url-utils";
 //#region src/cdn-warm.ts
-const DEFAULT_CDN_WARM_TIMEOUT_MS = 5e3;
+const DEFAULT_CDN_WARM_CONCURRENCY = 25;
+const DEFAULT_CDN_WARM_TIMEOUT_MS = 1e4;
+const DEFAULT_STAGED_READINESS_RETRIES = 60;
+const DEFAULT_STAGED_READINESS_INTERVAL_MS = 1e3;
+const DEFAULT_STAGED_READINESS_PHASE_TIMEOUT_MS = 12e4;
+const DEFAULT_STAGED_READINESS_SUCCESSES = 6;
+const STAGED_READINESS_QUERY_PARAM = "__vinext_cdn_warm_readiness";
+function applyWarmPathConfig(pathname, config) {
+	const withBasePath = config.basePath ? pathname === "/" ? config.basePath : `${config.basePath}${pathname}` : pathname;
+	const normalized = normalizePathTrailingSlash(withBasePath, config.trailingSlash === true);
+	return new URL(normalized, "http://vinext.local").pathname;
+}
 function readBuiltBuildId(root) {
 	try {
 		const buildId = fs.readFileSync(path.join(root, "dist", "server", "BUILD_ID"), "utf-8").trim();
@@ -19,52 +38,83 @@ function readPrerenderPathManifest(manifestPath) {
 		const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
 		if (!parsed || typeof parsed !== "object") return null;
 		const manifest = parsed;
-		if (!Array.isArray(manifest.paths)) return null;
+		if (!Array.isArray(manifest.paths) || !manifest.paths.every((pathname) => typeof pathname === "string") || manifest.appPaths !== void 0 && (!Array.isArray(manifest.appPaths) || !manifest.appPaths.every((pathname) => typeof pathname === "string")) || manifest.pagesPaths !== void 0 && (!Array.isArray(manifest.pagesPaths) || !manifest.pagesPaths.every((pathname) => typeof pathname === "string")) || manifest.pagesDataPaths !== void 0 && (!Array.isArray(manifest.pagesDataPaths) || !manifest.pagesDataPaths.every((pathname) => typeof pathname === "string")) || manifest.excludedWarmPaths !== void 0 && (!Array.isArray(manifest.excludedWarmPaths) || !manifest.excludedWarmPaths.every((pathname) => typeof pathname === "string")) || manifest.fallbackRoutePatterns !== void 0 && (!Array.isArray(manifest.fallbackRoutePatterns) || !manifest.fallbackRoutePatterns.every((route) => route !== null && typeof route === "object" && !Array.isArray(route) && (route.kind === "app-page" || route.kind === "app-route" || route.kind === "pages-page") && typeof route.pattern === "string" && route.pattern.startsWith("/"))) || manifest.rscPaths !== void 0 && (!Array.isArray(manifest.rscPaths) || !manifest.rscPaths.every((pathname) => typeof pathname === "string")) || manifest.routeHandlerPaths !== void 0 && (!Array.isArray(manifest.routeHandlerPaths) || !manifest.routeHandlerPaths.every((pathname) => typeof pathname === "string")) || manifest.routePatterns !== void 0 && (!manifest.routePatterns || typeof manifest.routePatterns !== "object" || Array.isArray(manifest.routePatterns) || !Object.entries(manifest.routePatterns).every(([pathname, route]) => pathname.startsWith("/") && route !== null && typeof route === "object" && !Array.isArray(route) && (route.kind === "app-page" || route.kind === "app-route" || route.kind === "pages-page") && typeof route.pattern === "string" && route.pattern.startsWith("/") && (route.cacheabilityProbe === void 0 || route.cacheabilityProbe !== null && typeof route.cacheabilityProbe === "object" && !Array.isArray(route.cacheabilityProbe) && typeof route.cacheabilityProbe.canPrunePattern === "boolean" && (route.cacheabilityProbe.concretePathname === void 0 || typeof route.cacheabilityProbe.concretePathname === "string" && route.cacheabilityProbe.concretePathname.startsWith("/")) && (route.cacheabilityProbe.routeMayResolve === void 0 || typeof route.cacheabilityProbe.routeMayResolve === "boolean") && (route.cacheabilityProbe.requestStageMayTerminate === void 0 || typeof route.cacheabilityProbe.requestStageMayTerminate === "boolean")))) || manifest.loadingShellPaths !== void 0 && (!Array.isArray(manifest.loadingShellPaths) || !manifest.loadingShellPaths.every((pathname) => typeof pathname === "string")) || manifest.basePath !== void 0 && typeof manifest.basePath !== "string" || manifest.buildIdentity !== void 0 && typeof manifest.buildIdentity !== "string" || manifest.deploymentId !== void 0 && typeof manifest.deploymentId !== "string" || manifest.rscBuildId !== void 0 && typeof manifest.rscBuildId !== "string" || manifest.trailingSlash !== void 0 && typeof manifest.trailingSlash !== "boolean" || manifest.responseVary !== void 0 && manifest.responseVary !== "verbatim") return null;
 		return manifest;
 	} catch (error) {
 		console.warn(`[vinext] Failed to read prerender path manifest at ${manifestPath}:`, error);
 		return null;
 	}
 }
-function readPrerenderPathWarmPaths(root, options) {
-	const manifest = readPrerenderPathManifest(path.join(root, "dist", "server", PRERENDER_PATHS_MANIFEST));
-	if (!manifest) return null;
+function createPrerenderPathWarmPaths(root, manifest, options) {
 	const builtBuildId = readBuiltBuildId(root);
 	if (!manifest.buildId || !builtBuildId || manifest.buildId !== builtBuildId) {
 		const message = "[vinext] CDN warmup skipped: prerender path manifest buildId does not match dist/server/BUILD_ID.";
 		if (options?.strict) throw new Error(message);
 		console.warn(message);
-		return [];
+		return null;
 	}
-	return manifest.paths.filter((pathname) => pathname.startsWith("/"));
+	return {
+		manifest,
+		pagesPaths: (manifest.pagesPaths ?? []).filter((pathname) => pathname.startsWith("/")).filter((pathname) => !manifest.excludedWarmPaths?.includes(pathname)).map((pathname) => applyWarmPathConfig(pathname, manifest)),
+		paths: manifest.paths.filter((pathname) => pathname.startsWith("/")).filter((pathname) => !manifest.excludedWarmPaths?.includes(pathname)).map((pathname) => applyWarmPathConfig(pathname, manifest))
+	};
 }
-function readPrerenderWarmPaths(root, options) {
-	const shouldPreferPrerenderManifest = options?.includeFallbackShells === true;
-	if (!shouldPreferPrerenderManifest) {
-		const pathManifestPaths = readPrerenderPathWarmPaths(root, options);
-		if (pathManifestPaths !== null) return pathManifestPaths;
-	}
-	const manifest = readPrerenderManifest(path.join(root, "dist", "server", "vinext-prerender.json"));
-	if (!manifest) {
-		if (shouldPreferPrerenderManifest) {
-			const pathManifestPaths = readPrerenderPathWarmPaths(root, options);
-			if (pathManifestPaths !== null) {
-				console.warn("[vinext] CDN warmup fallback shells requested, but prerender manifest not found; warming build-discovered paths only.");
-				return pathManifestPaths;
-			}
-		}
-		const message = "[vinext] CDN warmup skipped: prerender manifest not found.";
+function createPrerenderWarmPlan(root, manifest, options) {
+	const pathPlan = createPrerenderPathWarmPaths(root, manifest, options);
+	if (!pathPlan) {
+		const message = "[vinext] CDN warmup skipped: prerender path discovery is invalid.";
 		if (options?.strict) throw new Error(message);
-		return [];
+		return {
+			loadingShellPaths: [],
+			paths: [],
+			rscPaths: []
+		};
 	}
-	const builtBuildId = readBuiltBuildId(root);
-	if (!manifest.buildId || !builtBuildId || manifest.buildId !== builtBuildId) {
-		const message = "[vinext] CDN warmup skipped: prerender manifest buildId does not match dist/server/BUILD_ID.";
+	const supportsCanonicalRsc = (manifest.responseVary === "verbatim" || options?.includeCanonicalRsc === true) && manifest.rscPaths !== void 0 && manifest.rscBuildId !== void 0;
+	const applyConfig = (pathname) => applyWarmPathConfig(pathname, manifest);
+	const routePatterns = manifest.routePatterns ? Object.fromEntries(Object.entries(manifest.routePatterns).map(([pathname, route]) => [pathname.includes("/_next/data/") ? pathname : applyConfig(pathname), route])) : void 0;
+	let htmlPaths = pathPlan.paths;
+	if (options?.includeFallbackShells === true) {
+		const prerenderManifest = readPrerenderManifest(path.join(root, "dist", "server", "vinext-prerender.json"));
+		if (!prerenderManifest) console.warn("[vinext] CDN warmup fallback shells requested, but prerender manifest not found; warming build-discovered paths only.");
+		else if (!prerenderManifest.buildId || prerenderManifest.buildId !== manifest.buildId) {
+			const message = "[vinext] CDN warmup skipped: prerender manifest buildId does not match dist/server/BUILD_ID.";
+			if (options.strict) throw new Error(message);
+			console.warn(message);
+			htmlPaths = [];
+		} else htmlPaths = getPrerenderedConcretePaths(prerenderManifest, { includeFallbackShells: true }).filter((pathname) => pathname.startsWith("/")).filter((pathname) => !manifest.excludedWarmPaths?.includes(pathname)).map(applyConfig);
+	}
+	return {
+		...manifest.appPaths ? { appPaths: manifest.appPaths.map(applyConfig) } : {},
+		buildId: manifest.buildId,
+		...manifest.buildIdentity ? { buildIdentity: manifest.buildIdentity } : {},
+		...manifest.deploymentId ? { deploymentId: manifest.deploymentId } : {},
+		...manifest.fallbackRoutePatterns ? { fallbackRoutePatterns: manifest.fallbackRoutePatterns } : {},
+		loadingShellPaths: supportsCanonicalRsc ? (manifest.loadingShellPaths ?? []).map(applyConfig) : [],
+		...manifest.pagesDataPaths ? { pagesDataPaths: manifest.pagesDataPaths } : {},
+		...manifest.pagesPaths ? { pagesPaths: manifest.pagesPaths.map(applyConfig) } : {},
+		paths: htmlPaths,
+		...supportsCanonicalRsc ? { rscBuildId: manifest.rscBuildId } : {},
+		rscPaths: supportsCanonicalRsc ? manifest.rscPaths.map(applyConfig) : [],
+		...manifest.routeHandlerPaths ? { routeHandlerPaths: manifest.routeHandlerPaths.map(applyConfig) } : {},
+		...routePatterns ? { routePatterns } : {}
+	};
+}
+function readPrerenderWarmPlan(root, options) {
+	const manifest = readPrerenderPathManifest(path.join(root, "dist", "server", PRERENDER_PATHS_MANIFEST));
+	if (!manifest) {
+		const message = "[vinext] CDN warmup skipped: prerender path manifest not found.";
 		if (options?.strict) throw new Error(message);
-		console.warn(message);
-		return [];
+		return {
+			loadingShellPaths: [],
+			paths: [],
+			rscPaths: []
+		};
 	}
-	return getPrerenderedConcretePaths(manifest, options);
+	return createPrerenderWarmPlan(root, manifest, options);
+}
+function readPrerenderWarmPaths(root, options) {
+	return readPrerenderWarmPlan(root, options).paths;
 }
 function getWarmPathsFromPrerenderManifest(manifest, options) {
 	return getPrerenderedConcretePaths(manifest, options);
@@ -75,45 +125,676 @@ function normalizeWarmPath(pathname) {
 function buildWarmupUrl(targetUrl, pathname) {
 	return new URL(normalizeWarmPath(pathname), targetUrl.endsWith("/") ? targetUrl : `${targetUrl}/`);
 }
-function isRetryableStatus(status) {
-	return status === 408 || status === 429 || status >= 500;
+function isRetryableStatus(status, retryNotFound) {
+	return status === 408 || status === 429 || status >= 500 || retryNotFound && status === 404;
+}
+const WORKER_VERSION_OVERRIDE_HEADER = "Cloudflare-Workers-Version-Overrides";
+async function fetchWithTimeout(fetchImpl, url, timeoutMs, headers, redirect) {
+	const controller = new AbortController();
+	let response;
+	let timer;
+	const requestHeaders = new Headers(headers);
+	requestHeaders.set("User-Agent", "vinext-cloudflare-cdn-warm");
+	try {
+		const timedOut = new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				controller.abort();
+				reject(new DOMException(`Timed out after ${timeoutMs}ms`, "AbortError"));
+			}, timeoutMs);
+		});
+		return await Promise.race([(async () => {
+			response = await fetchImpl(url, {
+				method: "GET",
+				redirect,
+				headers: requestHeaders,
+				signal: controller.signal
+			});
+			return {
+				body: await response.arrayBuffer(),
+				response
+			};
+		})(), timedOut]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+		if (controller.signal.aborted && response?.body) response.body.cancel().catch(() => {});
+	}
 }
-async function fetchWithTimeout(fetchImpl, url, timeoutMs, headers) {
+async function fetchHeadersWithTimeout(fetchImpl, url, timeoutMs, headers, method = "GET") {
 	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), timeoutMs);
 	const requestHeaders = new Headers(headers);
 	requestHeaders.set("User-Agent", "vinext-cloudflare-cdn-warm");
+	let timer;
 	try {
-		return await fetchImpl(url, {
-			method: "GET",
-			redirect: "follow",
+		const timedOut = new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				controller.abort();
+				reject(new DOMException(`Timed out after ${timeoutMs}ms`, "AbortError"));
+			}, timeoutMs);
+		});
+		return await Promise.race([fetchImpl(url, {
+			method,
+			redirect: "manual",
 			headers: requestHeaders,
 			signal: controller.signal
-		});
+		}), timedOut]);
 	} finally {
-		clearTimeout(timer);
-	}
-}
-async function warmOnePath(pathname, options) {
-	const url = buildWarmupUrl(options.targetUrl, pathname);
-	let lastError = "unknown error";
-	for (let attempt = 0; attempt <= options.retries; attempt++) try {
-		const response = await fetchWithTimeout(options.fetchImpl, url, options.timeoutMs, options.headers);
-		await response.arrayBuffer();
-		if (response.status < 400) return {
-			path: pathname,
-			ok: true
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+const MAX_CDN_WARM_REPORT_ROUTES = 10;
+const MAX_CDN_WARM_REPORT_PATTERN_WIDTH = 48;
+const CDN_WARM_ROUTE_KIND_LABELS = {
+	"app-page": "App page",
+	"app-route": "Route Handler",
+	"pages-page": "Pages page"
+};
+function formatCount(count, singular, plural = `${singular}s`) {
+	return `${count.toLocaleString("en-US")} ${count === 1 ? singular : plural}`;
+}
+function formatNumber(count) {
+	return count.toLocaleString("en-US");
+}
+function truncateMiddle(value, maxLength) {
+	if (value.length <= maxLength) return value;
+	const remaining = maxLength - 1;
+	const startLength = Math.ceil(remaining / 2);
+	return `${value.slice(0, startLength)}…${value.slice(-(remaining - startLength))}`;
+}
+function printCdnWarmTable(headings, rows, rightAlignedFrom) {
+	const widths = headings.map((heading, index) => Math.max(heading.length, ...rows.map((row) => row[index]?.length ?? 0)));
+	for (const row of [headings, ...rows]) console.log(`    ${row.map((value, index) => index >= rightAlignedFrom ? value.padStart(widths[index]) : value.padEnd(widths[index])).join("  ")}`);
+}
+function createCdnWarmRouteReport(targets, outcomes) {
+	const routes = /* @__PURE__ */ new Map();
+	for (const [index, target] of targets.entries()) {
+		const key = target.route ? `${target.route.kind}\0${target.route.pattern}` : "unmatched";
+		const route = routes.get(key) ?? {
+			failed: 0,
+			kind: target.route ? CDN_WARM_ROUTE_KIND_LABELS[target.route.kind] : "Other",
+			key,
+			pattern: target.route?.pattern ?? "Other discovered requests",
+			paths: /* @__PURE__ */ new Set(),
+			skipped: 0,
+			total: 0,
+			warmed: 0
 		};
-		lastError = `HTTP ${response.status}`;
-		if (!isRetryableStatus(response.status)) break;
-	} catch (error) {
-		if (error instanceof DOMException && error.name === "AbortError") lastError = `timed out after ${options.timeoutMs}ms`;
-		else lastError = error instanceof Error ? error.message : String(error);
+		route.paths.add(target.route?.cacheabilityProbe?.concretePathname ?? cacheabilityRoutePathname(target.pathname, target.kind));
+		route.total++;
+		const outcome = outcomes?.[index];
+		if (outcome) route[outcome]++;
+		routes.set(key, route);
+	}
+	return [...routes.values()].sort((left, right) => right.total - left.total || left.key.localeCompare(right.key));
+}
+function printCdnWarmRouteReport(targets, outcomes) {
+	if (!targets.some((target) => target.route)) return;
+	const routes = createCdnWarmRouteReport(targets, outcomes);
+	if (routes.length === 0) return;
+	console.log(`  CDN warmup ${outcomes ? "result" : "plan"} by route:`);
+	const visible = routes.slice(0, MAX_CDN_WARM_REPORT_ROUTES);
+	const routeColumns = (route) => [truncateMiddle(route.pattern, MAX_CDN_WARM_REPORT_PATTERN_WIDTH), route.kind];
+	if (outcomes) printCdnWarmTable([
+		"Route pattern",
+		"Kind",
+		"Warmed",
+		"Skipped",
+		"Failed"
+	], visible.map((route) => [
+		...routeColumns(route),
+		`${formatNumber(route.warmed)}/${formatNumber(route.total)}`,
+		formatNumber(route.skipped),
+		formatNumber(route.failed)
+	]), 2);
+	else printCdnWarmTable([
+		"Route pattern",
+		"Kind",
+		"Paths",
+		"Entries"
+	], visible.map((route) => [
+		...routeColumns(route),
+		formatNumber(route.paths.size),
+		formatNumber(route.total)
+	]), 2);
+	const omitted = routes.slice(MAX_CDN_WARM_REPORT_ROUTES);
+	if (omitted.length > 0) {
+		const omittedEntries = omitted.reduce((total, route) => total + route.total, 0);
+		console.log(`    ... ${formatCount(omitted.length, "additional route pattern")} omitted (${formatCount(omittedEntries, "cache entry", "cache entries")})`);
+	}
+}
+function cdnWarmTargetKey(target) {
+	return `${target.kind}\0${target.sourcePathname}`;
+}
+async function createCdnWarmTargets(options) {
+	const requests = [];
+	const fullRscPaths = new Set(options.rscPaths ?? []);
+	const loadingShellPaths = new Set(options.loadingShellPaths ?? []);
+	const commonHeaders = new Headers(options.headers);
+	for (const pathname of /* @__PURE__ */ new Set([...fullRscPaths, ...loadingShellPaths])) {
+		if (fullRscPaths.has(pathname)) {
+			const rscHeaders = new Headers(commonHeaders);
+			for (const [name, value] of createCanonicalRscRequestHeaders(options.deploymentId)) rscHeaders.set(name, value);
+			requests.push({
+				headers: rscHeaders,
+				kind: "rsc-full",
+				label: `${pathname} (RSC full)`,
+				pathname: createCanonicalRscRequestUrl(pathname),
+				sourcePathname: pathname,
+				route: options.routePatterns?.[pathname]
+			});
+		}
+		if (loadingShellPaths.has(pathname)) {
+			const loadingHeaders = new Headers(commonHeaders);
+			for (const [name, value] of createCanonicalLoadingShellRscRequestHeaders(options.deploymentId)) loadingHeaders.set(name, value);
+			requests.push({
+				headers: loadingHeaders,
+				kind: "rsc-loading-shell",
+				label: `${pathname} (RSC loading shell)`,
+				pathname: await createRscRequestUrl(pathname, loadingHeaders),
+				sourcePathname: pathname,
+				route: options.routePatterns?.[pathname]
+			});
+		}
+	}
+	for (const pathname of new Set(options.paths)) {
+		const htmlHeaders = new Headers(commonHeaders);
+		htmlHeaders.set("Accept", "text/html");
+		requests.push({
+			headers: htmlHeaders,
+			kind: "html",
+			label: pathname,
+			pathname,
+			sourcePathname: pathname,
+			route: options.routePatterns?.[pathname]
+		});
+	}
+	for (const pathname of new Set(options.pagesDataPaths ?? [])) {
+		const dataHeaders = new Headers(commonHeaders);
+		dataHeaders.set("Accept", "application/json");
+		requests.push({
+			headers: dataHeaders,
+			kind: "pages-data",
+			label: `${pathname} (Pages data)`,
+			pathname,
+			sourcePathname: pathname,
+			route: options.routePatterns?.[pathname]
+		});
+	}
+	for (const pathname of new Set(options.routeHandlerPaths ?? [])) {
+		const routeHeaders = new Headers(commonHeaders);
+		routeHeaders.set("Accept", "*/*");
+		requests.push({
+			headers: routeHeaders,
+			kind: "app-route",
+			label: `${pathname} (Route Handler)`,
+			pathname,
+			sourcePathname: pathname,
+			route: options.routePatterns?.[pathname]
+		});
+	}
+	return requests;
+}
+var CdnOperationProgress = class {
+	isTTY = process.stderr.isTTY;
+	lastLineLength = 0;
+	update(completed, total, label, phase = "Warming CDN cache") {
+		if (!this.isTTY) return;
+		const percent = total > 0 ? Math.floor(completed / total * 100) : 0;
+		const filled = Math.floor(percent / 5);
+		const bar = `[${"█".repeat(filled)}${" ".repeat(20 - filled)}]`;
+		const shortLabel = label.length > 40 ? `…${label.slice(-39)}` : label;
+		const line = `${phase}... ${bar} ${String(completed).padStart(String(total).length)}/${total} ${shortLabel}`;
+		process.stderr.write(`\r${line.padEnd(this.lastLineLength)}`);
+		this.lastLineLength = line.length;
+	}
+	finish() {
+		if (!this.isTTY || this.lastLineLength === 0) return;
+		process.stderr.write(`\r${" ".repeat(this.lastLineLength)}\r`);
+		this.lastLineLength = 0;
+	}
+};
+const REQUIRED_RSC_VARY_HEADERS = VINEXT_RSC_VARY_HEADER$1.split(",").map((name) => name.trim().toLowerCase());
+const ADMITTED_CF_CACHE_STATUSES = /* @__PURE__ */ new Set([
+	"HIT",
+	"MISS",
+	"EXPIRED",
+	"REVALIDATED",
+	"UPDATING"
+]);
+const REUSABLE_CF_CACHE_STATUSES = /* @__PURE__ */ new Set([
+	"HIT",
+	"REVALIDATED",
+	"UPDATING"
+]);
+const TRANSITIONAL_VINEXT_CACHE_STATUSES = /* @__PURE__ */ new Set(["MISS", "UPDATING"]);
+const NON_CACHEABLE_CF_CACHE_STATUSES = /* @__PURE__ */ new Set(["BYPASS"]);
+const CDN_CACHE_POLICY_HEADERS = [
+	"Cloudflare-CDN-Cache-Control",
+	"CDN-Cache-Control",
+	"Cache-Control"
+];
+function splitCacheControlDirectives(value) {
+	const directives = [];
+	let start = 0;
+	let quoted = false;
+	let escaped = false;
+	for (let index = 0; index < value.length; index++) {
+		const character = value[index];
+		if (escaped) escaped = false;
+		else if (quoted && character === "\\") escaped = true;
+		else if (character === "\"") quoted = !quoted;
+		else if (character === "," && !quoted) {
+			directives.push(value.slice(start, index));
+			start = index + 1;
+		}
+	}
+	directives.push(value.slice(start));
+	return directives;
+}
+function hasFieldQualifiedSetCookie(value) {
+	return splitCacheControlDirectives(value).some((directive) => {
+		const separator = directive.indexOf("=");
+		if (separator === -1) return false;
+		const name = directive.slice(0, separator).trim().toLowerCase();
+		if (name !== "private" && name !== "no-cache") return false;
+		const rawFields = directive.slice(separator + 1).trim();
+		return (rawFields.startsWith("\"") && rawFields.endsWith("\"") ? rawFields.slice(1, -1) : rawFields).split(",").some((field) => field.trim().toLowerCase() === "set-cookie");
+	});
+}
+function validateCachePolicy(response, requireCacheStatus, requireCacheHit = false) {
+	const effectivePolicy = CDN_CACHE_POLICY_HEADERS.map((name) => ({
+		name,
+		value: response.headers.get(name)
+	})).find((entry) => entry.value !== null);
+	const nonCacheableHeaders = effectivePolicy && isNonCacheableCacheControl(effectivePolicy.value) ? [effectivePolicy.name] : [];
+	const hasSetCookie = response.headers.has("Set-Cookie");
+	const cacheStatus = response.headers.get("CF-Cache-Status")?.trim().toUpperCase();
+	if (requireCacheHit && !REUSABLE_CF_CACHE_STATUSES.has(cacheStatus ?? "")) return {
+		outcome: "failed",
+		error: `CF-Cache-Status is ${cacheStatus ?? "missing"}; the cache fill is not reusable`
+	};
+	if (cacheStatus && ADMITTED_CF_CACHE_STATUSES.has(cacheStatus)) {
+		if (hasSetCookie && (!effectivePolicy || !hasFieldQualifiedSetCookie(effectivePolicy.value))) return {
+			outcome: "failed",
+			error: "response sets a cookie without an observable field-qualified cache policy"
+		};
+		return { outcome: "warmed" };
+	}
+	if (cacheStatus && NON_CACHEABLE_CF_CACHE_STATUSES.has(cacheStatus)) return {
+		outcome: "skipped",
+		reason: nonCacheableHeaders.length > 0 ? `${nonCacheableHeaders.join(", ")} opts out of caching` : hasSetCookie ? "response sets a cookie" : `CF-Cache-Status is ${cacheStatus}`
+	};
+	if (cacheStatus === "DYNAMIC") {
+		if (nonCacheableHeaders.length > 0 || hasSetCookie) return {
+			outcome: "skipped",
+			reason: nonCacheableHeaders.length > 0 ? `${nonCacheableHeaders.join(", ")} opts out of caching` : "response sets a cookie"
+		};
+		return {
+			outcome: "failed",
+			error: "CF-Cache-Status is DYNAMIC"
+		};
+	}
+	if (nonCacheableHeaders.length > 0 || hasSetCookie) return {
+		outcome: "failed",
+		error: `${nonCacheableHeaders.length > 0 ? `${nonCacheableHeaders.join(", ")} opts out of caching` : "response sets a cookie"}, but CF-Cache-Status is ${cacheStatus ?? "missing"}`
+	};
+	if (!cacheStatus) return requireCacheStatus ? {
+		outcome: "failed",
+		error: "response is missing CF-Cache-Status"
+	} : { outcome: "warmed" };
+	return {
+		outcome: "failed",
+		error: `CF-Cache-Status is ${cacheStatus}`
+	};
+}
+function validateVinextCacheStatus(response, missingStatus = "failed", requireCacheHit = false) {
+	const status = response.headers.get(VINEXT_CACHE_HEADER)?.trim().toUpperCase();
+	if (requireCacheHit && status !== "HIT") return {
+		outcome: "failed",
+		error: `${VINEXT_CACHE_HEADER} is ${status ?? "missing"}; the cache fill is not reusable`
+	};
+	if (status === "MISS" || status === "HIT" || status === "UPDATING") return { outcome: "warmed" };
+	if (status === "BYPASS" || status === "DYNAMIC") return {
+		outcome: "skipped",
+		reason: `${VINEXT_CACHE_HEADER} is ${status}`
+	};
+	return missingStatus === "skipped" ? {
+		outcome: "skipped",
+		reason: `response is missing ${VINEXT_CACHE_HEADER}`
+	} : {
+		outcome: "failed",
+		error: `response is missing ${VINEXT_CACHE_HEADER}`
+	};
+}
+function validateWarmAdmission(response, statusSource, requireCacheHit) {
+	if (statusSource === "vinext") return validateVinextCacheStatus(response, "failed", requireCacheHit);
+	if (statusSource === "data-cache") return validateVinextCacheStatus(response, "skipped", requireCacheHit);
+	return validateCachePolicy(response, true, requireCacheHit);
+}
+function validateBuildIdentity(response, expectedBuildId) {
+	if (expectedBuildId !== void 0 && response.headers.get("X-Vinext-Build-Id") !== expectedBuildId) {
+		const actualBuildId = response.headers.get("X-Vinext-Build-Id") ?? "missing";
+		return {
+			outcome: "failed",
+			error: `response ${VINEXT_CDN_BUILD_ID_HEADER} does not match build ${expectedBuildId} (received ${actualBuildId})`
+		};
+	}
+	return null;
+}
+function isExpectedTerminalStatus(status) {
+	return status >= 300 && status < 400 || status === 404;
+}
+function validateRscWarmResponse(response, expectedBuildId, expectedRscBuildId, requireCacheHit = false, statusSource = "cloudflare") {
+	const buildIdentityValidation = validateBuildIdentity(response, expectedBuildId);
+	if (buildIdentityValidation) return buildIdentityValidation;
+	if (expectedRscBuildId !== void 0 && response.headers.get(VINEXT_RSC_BUILD_ID_HEADER) !== expectedRscBuildId) return {
+		outcome: "failed",
+		error: `response ${VINEXT_RSC_BUILD_ID_HEADER} does not match build ${expectedRscBuildId}`
+	};
+	if (response.redirected) return {
+		outcome: "failed",
+		error: "redirected response"
+	};
+	const terminalResponse = response.status < 200 || response.status >= 300;
+	if (terminalResponse) {
+		if (!isExpectedTerminalStatus(response.status) || expectedBuildId === void 0 && expectedRscBuildId === void 0) return {
+			outcome: "failed",
+			error: `HTTP ${response.status}`
+		};
+	} else if (!response.headers.get("Content-Type")?.toLowerCase().startsWith(VINEXT_RSC_CONTENT_TYPE)) return {
+		outcome: "failed",
+		error: `expected ${VINEXT_RSC_CONTENT_TYPE} response`
+	};
+	const cachePolicyValidation = validateWarmAdmission(response, statusSource, requireCacheHit);
+	if (cachePolicyValidation.outcome !== "warmed") return cachePolicyValidation;
+	if (terminalResponse && !response.headers.get("Content-Type")?.toLowerCase().startsWith(VINEXT_RSC_CONTENT_TYPE)) return {
+		outcome: "failed",
+		error: `expected ${VINEXT_RSC_CONTENT_TYPE} response`
+	};
+	const vary = new Set((response.headers.get("Vary") ?? "").split(",").map((name) => name.trim().toLowerCase()).filter(Boolean));
+	const missingVary = REQUIRED_RSC_VARY_HEADERS.find((name) => !vary.has(name));
+	if (missingVary) return {
+		outcome: "failed",
+		error: `response Vary is missing ${missingVary}`
+	};
+	return { outcome: "warmed" };
+}
+function validateHtmlWarmResponse(response, expectedBuildId, requireCacheHit = false, statusSource = "cloudflare") {
+	const buildIdentityValidation = validateBuildIdentity(response, expectedBuildId);
+	if (buildIdentityValidation) return buildIdentityValidation;
+	if (response.redirected) return {
+		outcome: "failed",
+		error: "redirected response"
+	};
+	if (response.status < 200 || response.status >= 300) {
+		if (!isExpectedTerminalStatus(response.status) || expectedBuildId === void 0) return {
+			outcome: "failed",
+			error: `HTTP ${response.status}`
+		};
+	}
+	const cachePolicyValidation = validateWarmAdmission(response, statusSource, requireCacheHit);
+	if (cachePolicyValidation.outcome !== "warmed") return cachePolicyValidation;
+	return { outcome: "warmed" };
+}
+function validatePagesDataWarmResponse(response, expectedBuildId, requireCacheHit = false, statusSource = "cloudflare") {
+	const validation = validateHtmlWarmResponse(response, expectedBuildId, requireCacheHit, statusSource);
+	if (validation.outcome !== "warmed") return validation;
+	if (!response.headers.get("Content-Type")?.toLowerCase().startsWith("application/json")) return {
+		outcome: "failed",
+		error: "expected application/json response"
+	};
+	return validation;
+}
+function validateReadinessResponse(response, kind, expectedBuildId, expectedRscBuildId) {
+	const buildIdentityValidation = validateBuildIdentity(response, expectedBuildId);
+	if (buildIdentityValidation?.outcome === "failed") return buildIdentityValidation.error;
+	if (kind === "rsc" && expectedRscBuildId !== void 0 && response.headers.get(VINEXT_RSC_BUILD_ID_HEADER) !== expectedRscBuildId) return `response ${VINEXT_RSC_BUILD_ID_HEADER} does not match build ${expectedRscBuildId}`;
+	if (response.redirected) return "redirected response";
+	if (response.status >= 500) return `HTTP ${response.status}`;
+	if (response.status >= 200 && response.status < 300) {
+		const contentType = response.headers.get("Content-Type")?.toLowerCase();
+		if (kind === "rsc" && !contentType?.startsWith(VINEXT_RSC_CONTENT_TYPE)) return `expected ${VINEXT_RSC_CONTENT_TYPE} response`;
+		if (kind === "pages-data" && !contentType?.startsWith("application/json")) return "expected application/json response";
+	}
+	return null;
+}
+function validatePrerenderReadinessResponse(response, expectedBuildId) {
+	const buildIdentityValidation = validateBuildIdentity(response, expectedBuildId);
+	if (buildIdentityValidation?.outcome === "failed") return buildIdentityValidation.error;
+	if (response.redirected) return "redirected response";
+	if (response.status !== 204) return `expected readiness HTTP 204, received ${response.status}`;
+	if (response.headers.get(VINEXT_PRERENDER_READINESS_HEADER) !== "1") return `response is missing ${VINEXT_PRERENDER_READINESS_HEADER}: 1`;
+	const cacheControl = response.headers.get("Cache-Control");
+	if (!cacheControl || !/(?:^|,)\s*no-store\s*(?:,|$)/i.test(cacheControl)) return "readiness response is missing Cache-Control: no-store";
+	return null;
+}
+/**
+* Wait until version-override requests consistently reach the uploaded build
+* before any real cache key is filled. Every probe has a unique query key, so
+* an early response cannot make a later readiness attempt pass from cache.
+*/
+async function waitForCdnWarmTargetReadiness(options) {
+	const rscPath = options.plan.rscPaths[0] ?? options.plan.loadingShellPaths[0];
+	const htmlPath = options.plan.paths[0];
+	const pagesDataPath = options.plan.pagesDataPaths[0];
+	const routeHandlerPath = options.plan.routeHandlerPaths?.[0];
+	const kind = rscPath ? "rsc" : htmlPath ? "html" : pagesDataPath ? "pages-data" : "app-route";
+	const pathname = rscPath ?? htmlPath ?? pagesDataPath ?? routeHandlerPath;
+	if (!pathname) return { ready: true };
+	if (options.expectedBuildId === void 0 && options.expectedRscBuildId === void 0) return {
+		error: "no response build identity is available for a staged-version readiness probe",
+		ready: false
+	};
+	const headers = new Headers(options.headers);
+	const readinessSecret = options.prerenderSecret;
+	const useReadinessEndpoint = Boolean(readinessSecret);
+	const probePath = useReadinessEndpoint ? VINEXT_PRERENDER_READINESS_PATH : kind === "rsc" ? createCanonicalRscRequestUrl(pathname) : pathname;
+	if (readinessSecret) {
+		headers.set("Accept", "text/html");
+		headers.set(VINEXT_PRERENDER_SECRET_HEADER, readinessSecret);
+	} else if (kind === "rsc") for (const [name, value] of createCanonicalRscRequestHeaders(options.deploymentId)) headers.set(name, value);
+	else if (kind === "html") headers.set("Accept", "text/html");
+	else if (kind === "pages-data") headers.set("Accept", "application/json");
+	else headers.set("Accept", "*/*");
+	headers.set("Cache-Control", "no-cache");
+	headers.set("Pragma", "no-cache");
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const timeoutMs = Math.max(1, options.timeoutMs ?? 1e4);
+	const probeIntervalMs = Math.max(0, options.probeIntervalMs ?? 1e3);
+	const requiredConsecutiveSuccesses = Math.max(1, options.requiredConsecutiveSuccesses ?? DEFAULT_STAGED_READINESS_SUCCESSES);
+	const readinessRetries = Math.max(0, options.retries ?? 60);
+	const maxAttempts = Math.max(requiredConsecutiveSuccesses, options.maxAttempts ?? requiredConsecutiveSuccesses + readinessRetries);
+	const phaseTimeoutMs = Math.max(1, options.phaseTimeoutMs ?? 12e4);
+	const deadlineAt = Date.now() + phaseTimeoutMs;
+	const probeId = randomUUID();
+	let consecutiveSuccesses = 0;
+	let lastError = "readiness probe did not run";
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		const remainingMs = deadlineAt - Date.now();
+		if (remainingMs <= 0) {
+			lastError = `staged readiness exceeded its ${phaseTimeoutMs}ms phase deadline`;
+			break;
+		}
+		const url = buildWarmupUrl(options.targetUrl, probePath);
+		url.searchParams.set(STAGED_READINESS_QUERY_PARAM, `${probeId}-${attempt}`);
+		let response;
+		try {
+			response = await fetchHeadersWithTimeout(fetchImpl, url, Math.min(timeoutMs, remainingMs), headers, useReadinessEndpoint ? "POST" : "GET");
+			const validationError = useReadinessEndpoint ? validatePrerenderReadinessResponse(response, options.expectedBuildId) : validateReadinessResponse(response, kind, options.expectedBuildId, options.expectedRscBuildId);
+			if (process.env.VINEXT_CDN_WARM_DEBUG === "1") console.log(`  CDN warm readiness attempt ${attempt + 1}: ${url.pathname}${url.search} HTTP ${response.status} build=${response.headers.get(VINEXT_RSC_BUILD_ID_HEADER) ?? response.headers.get("X-Vinext-Build-Id") ?? "missing"}`);
+			if (validationError === null) {
+				consecutiveSuccesses++;
+				if (consecutiveSuccesses >= requiredConsecutiveSuccesses) return { ready: true };
+			} else {
+				consecutiveSuccesses = 0;
+				lastError = validationError;
+			}
+		} catch (error) {
+			consecutiveSuccesses = 0;
+			lastError = Date.now() >= deadlineAt ? `staged readiness exceeded its ${phaseTimeoutMs}ms phase deadline` : error instanceof DOMException && error.name === "AbortError" ? `timed out after ${Math.min(timeoutMs, remainingMs)}ms` : error instanceof Error ? error.message : String(error);
+		} finally {
+			if (response?.body) response.body.cancel().catch(() => {});
+		}
+		if (attempt + 1 < maxAttempts && probeIntervalMs > 0) {
+			const delayMs = Math.min(probeIntervalMs, Math.max(0, deadlineAt - Date.now()));
+			if (delayMs <= 0) {
+				lastError = `staged readiness exceeded its ${phaseTimeoutMs}ms phase deadline`;
+				break;
+			}
+			await setTimeout$1(delayMs);
+		}
 	}
 	return {
-		path: pathname,
+		error: `${lastError}; uploaded build was not stable for ${requiredConsecutiveSuccesses} consecutive probe(s)`,
+		ready: false
+	};
+}
+function shouldRetryValidationFailure(response, target, options) {
+	if (!options.retryPropagationFailures) return isRetryableStatus(response.status, options.retryNotFound);
+	const expectedIdentities = [options.expectedBuildId === void 0 ? null : response.headers.get(VINEXT_CDN_BUILD_ID_HEADER) === options.expectedBuildId, !target.kind.startsWith("rsc-") || options.expectedRscBuildId === void 0 ? null : response.headers.get(VINEXT_RSC_BUILD_ID_HEADER) === options.expectedRscBuildId].filter((matches) => matches !== null);
+	if (expectedIdentities.some((matches) => matches)) return isRetryableStatus(response.status, false);
+	if (expectedIdentities.some((matches) => !matches)) return true;
+	return isRetryableStatus(response.status, options.retryNotFound);
+}
+function isRetryableCertificationFailure(response, statusSource, retryPropagationFailures) {
+	if (statusSource === "cloudflare") {
+		const status = response.headers.get("CF-Cache-Status")?.trim().toUpperCase();
+		return !REUSABLE_CF_CACHE_STATUSES.has(status ?? "") && (retryPropagationFailures || ADMITTED_CF_CACHE_STATUSES.has(status ?? ""));
+	}
+	const status = response.headers.get(VINEXT_CACHE_HEADER)?.trim().toUpperCase();
+	return TRANSITIONAL_VINEXT_CACHE_STATUSES.has(status ?? "");
+}
+async function warmOnePath(target, options) {
+	const url = buildWarmupUrl(options.targetUrl, target.pathname);
+	let lastError = "request failed before the first attempt";
+	let lastRetryable = true;
+	let lastSkippedReason = null;
+	const phaseDeadlineError = () => `CDN warmup exceeded its ${options.phaseTimeoutMs}ms phase deadline`;
+	const remainingPhaseMs = () => options.deadlineAt === void 0 ? options.timeoutMs : options.deadlineAt - Date.now();
+	const canRetry = (attempt) => attempt < options.retries;
+	const waitBeforeRetry = async () => {
+		if (options.retryDelayMs <= 0) return remainingPhaseMs() > 0;
+		const delayMs = Math.min(options.retryDelayMs, Math.max(0, remainingPhaseMs()));
+		if (delayMs <= 0) return false;
+		await setTimeout$1(delayMs);
+		return remainingPhaseMs() > 0;
+	};
+	for (let attempt = 0; attempt <= options.retries; attempt++) {
+		const remainingMs = remainingPhaseMs();
+		if (remainingMs <= 0) return {
+			path: target.label,
+			ok: false,
+			error: phaseDeadlineError(),
+			retryable: false
+		};
+		const attemptTimeoutMs = Math.min(options.timeoutMs, remainingMs);
+		const phaseLimitedAttempt = options.deadlineAt !== void 0 && remainingMs <= options.timeoutMs;
+		try {
+			const response = options.requireCacheHit ? await fetchHeadersWithTimeout(options.fetchImpl, url, attemptTimeoutMs, target.headers ?? options.headers) : (await fetchWithTimeout(options.fetchImpl, url, attemptTimeoutMs, target.headers ?? options.headers, "manual")).response;
+			if (options.deadlineAt !== void 0 && Date.now() >= options.deadlineAt) return {
+				path: target.label,
+				ok: false,
+				error: phaseDeadlineError(),
+				retryable: false
+			};
+			if (options.requireCacheHit) response.body?.cancel().catch(() => {});
+			if (process.env.VINEXT_CDN_WARM_DEBUG === "1") console.log(`  CDN warm debug ${target.label} attempt ${attempt + 1}: ${url.pathname}${url.search} HTTP ${response.status} cache=${response.headers.get("CF-Cache-Status") ?? "missing"} ray=${response.headers.get("CF-Ray") ?? "missing"} encoding=${response.headers.get("Content-Encoding") ?? "identity"} rscBuild=${response.headers.get(VINEXT_RSC_BUILD_ID_HEADER) ?? "missing"}`);
+			if (target.kind.startsWith("rsc-")) {
+				const validation = validateRscWarmResponse(response, options.expectedBuildId, options.expectedRscBuildId, options.requireCacheHit, options.statusSource);
+				if (validation.outcome === "warmed") return {
+					path: target.label,
+					ok: true,
+					skipped: false
+				};
+				if (validation.outcome === "skipped") {
+					if (!options.retrySkipped) return {
+						path: target.label,
+						ok: true,
+						skipped: true,
+						reason: validation.reason
+					};
+					lastSkippedReason = validation.reason;
+					lastRetryable = true;
+					if (!canRetry(attempt)) break;
+					if (!await waitBeforeRetry()) return {
+						path: target.label,
+						ok: false,
+						error: phaseDeadlineError(),
+						retryable: false
+					};
+					continue;
+				}
+				lastSkippedReason = null;
+				lastError = validation.error;
+				lastRetryable = options.requireCacheHit && isRetryableCertificationFailure(response, options.statusSource, options.retryPropagationFailures) || shouldRetryValidationFailure(response, target, options);
+				if (!lastRetryable) break;
+				if (!canRetry(attempt)) break;
+				if (!await waitBeforeRetry()) return {
+					path: target.label,
+					ok: false,
+					error: phaseDeadlineError(),
+					retryable: false
+				};
+				continue;
+			}
+			const validation = target.kind === "pages-data" ? validatePagesDataWarmResponse(response, options.expectedBuildId, options.requireCacheHit, options.statusSource) : validateHtmlWarmResponse(response, options.expectedBuildId, options.requireCacheHit, options.statusSource);
+			if (validation.outcome === "warmed") return {
+				path: target.label,
+				ok: true,
+				skipped: false
+			};
+			if (validation.outcome === "skipped") {
+				if (!options.retrySkipped) return {
+					path: target.label,
+					ok: true,
+					skipped: true,
+					reason: validation.reason
+				};
+				lastSkippedReason = validation.reason;
+				lastRetryable = true;
+				if (!canRetry(attempt)) break;
+				if (!await waitBeforeRetry()) return {
+					path: target.label,
+					ok: false,
+					error: phaseDeadlineError(),
+					retryable: false
+				};
+				continue;
+			}
+			lastSkippedReason = null;
+			lastError = validation.error;
+			lastRetryable = options.requireCacheHit && isRetryableCertificationFailure(response, options.statusSource, options.retryPropagationFailures) || shouldRetryValidationFailure(response, target, options);
+			if (!lastRetryable) break;
+		} catch (error) {
+			lastSkippedReason = null;
+			lastRetryable = true;
+			if (error instanceof DOMException && error.name === "AbortError") {
+				if (phaseLimitedAttempt) return {
+					path: target.label,
+					ok: false,
+					error: phaseDeadlineError(),
+					retryable: false
+				};
+				lastError = `timed out after ${attemptTimeoutMs}ms`;
+			} else lastError = error instanceof Error ? error.message : String(error);
+		}
+		if (!canRetry(attempt)) break;
+		if (!await waitBeforeRetry()) return {
+			path: target.label,
+			ok: false,
+			error: phaseDeadlineError(),
+			retryable: false
+		};
+	}
+	return lastSkippedReason === null ? {
+		path: target.label,
 		ok: false,
-		error: lastError
+		error: lastError,
+		retryable: lastRetryable
+	} : {
+		path: target.label,
+		ok: true,
+		skipped: true,
+		reason: lastSkippedReason
 	};
 }
 async function runWithConcurrency(items, concurrency, fn) {
@@ -131,53 +812,170 @@ async function runWithConcurrency(items, concurrency, fn) {
 	return results;
 }
 async function warmCdnCache(options) {
-	const paths = options.paths;
-	const concurrency = Math.max(1, options.concurrency ?? 10);
-	const timeoutMs = Math.max(1, options.timeoutMs ?? 5e3);
-	const retries = Math.max(0, options.retries ?? 1);
+	const targets = await createCdnWarmTargets(options);
+	const requests = targets.filter((target) => target.kind !== "html");
+	const htmlRequests = targets.filter((target) => target.kind === "html");
+	requests.push(...htmlRequests);
+	const timeoutMs = Math.max(1, options.timeoutMs ?? 1e4);
+	const hasVersionOverride = new Headers(options.headers).has(WORKER_VERSION_OVERRIDE_HEADER);
+	const propagatingTarget = options.propagatingTarget ?? hasVersionOverride;
+	const concurrency = Math.max(1, options.concurrency ?? 25);
+	const normalRetries = Math.max(0, options.retries ?? 1);
+	const propagationRetries = Math.max(0, options.retries ?? 60);
+	const normalRetryDelayMs = Math.max(0, options.retryDelayMs ?? 0);
+	const propagationRetryDelayMs = Math.max(0, options.retryDelayMs ?? 1e3);
 	const fetchImpl = options.fetchImpl ?? fetch;
-	if (paths.length === 0) return {
+	const phaseTimeoutMs = options.phaseTimeoutMs === void 0 ? void 0 : Math.max(1, options.phaseTimeoutMs);
+	const deadlineAt = phaseTimeoutMs === void 0 ? void 0 : Date.now() + phaseTimeoutMs;
+	if (requests.length === 0) return {
 		total: 0,
 		warmed: 0,
+		skipped: 0,
 		failed: 0,
-		failures: []
-	};
-	console.log(`\n  Warming CDN cache for ${paths.length} build-discovered path(s)...`);
-	const results = await runWithConcurrency(paths, concurrency, (pathname) => warmOnePath(pathname, {
-		targetUrl: options.targetUrl,
-		timeoutMs,
-		retries,
-		fetchImpl,
-		headers: options.headers
-	}));
-	const failures = results.filter((result) => !result.ok).map(({ path, error }) => ({
+		failures: [],
+		skippedTargets: [],
+		warmedPlan: {
+			loadingShellPaths: [],
+			pagesDataPaths: [],
+			paths: [],
+			rscPaths: []
+		},
+		retryPlan: {
+			loadingShellPaths: [],
+			pagesDataPaths: [],
+			paths: [],
+			rscPaths: []
+		}
+	};
+	console.log(`\n  Warming ${formatCount(requests.length, "CDN cache entry", "CDN cache entries")}...`);
+	printCdnWarmRouteReport(requests);
+	const progress = new CdnOperationProgress();
+	let completedRequests = 0;
+	progress.update(0, requests.length, "starting warmup");
+	const warmTarget = (target, retryMode = "normal") => {
+		const isPropagationRequest = retryMode !== "normal";
+		const retries = retryMode === "propagation-retry" ? Math.max(0, propagationRetries - 1) : retryMode === "propagation-pass" ? 0 : normalRetries;
+		return warmOnePath(target, {
+			targetUrl: options.targetUrl,
+			timeoutMs,
+			retries,
+			deadlineAt,
+			fetchImpl,
+			headers: options.headers,
+			expectedBuildId: options.expectedBuildId,
+			expectedRscBuildId: options.expectedRscBuildId,
+			retryPropagationFailures: isPropagationRequest,
+			retryDelayMs: isPropagationRequest ? propagationRetryDelayMs : normalRetryDelayMs,
+			retryNotFound: isPropagationRequest,
+			phaseTimeoutMs,
+			requireCacheHit: options.requireCacheHit === true,
+			statusSource: options.statusSource ?? "cloudflare",
+			retrySkipped: isPropagationRequest && options.retrySkippedTargetKeys?.has(cdnWarmTargetKey(target)) === true
+		});
+	};
+	const warmRequest = async (target, retryMode = "normal") => {
+		const result = await warmTarget(target, retryMode);
+		completedRequests++;
+		progress.update(completedRequests, requests.length, target.label);
+		return result;
+	};
+	const warmPropagatingPass = async (targets) => {
+		const results = await runWithConcurrency(targets, concurrency, (target) => warmRequest(target, "propagation-pass"));
+		const retryable = targets.map((target, index) => ({
+			index,
+			result: results[index],
+			target
+		})).filter(({ result, target }) => result.ok ? result.skipped && options.retrySkippedTargetKeys?.has(cdnWarmTargetKey(target)) === true : result.retryable);
+		if (retryable.length === 0 || propagationRetries === 0) return results;
+		progress.finish();
+		console.log(`  CDN warmup: retrying ${retryable.length} unresolved request(s) after completing the initial pass...`);
+		let completedRetries = 0;
+		progress.update(0, retryable.length, "starting retry pass", "Retrying CDN cache");
+		const retried = await runWithConcurrency(retryable.map(({ target }) => target), concurrency, async (target) => {
+			const result = await warmTarget(target, "propagation-retry");
+			completedRetries++;
+			progress.update(completedRetries, retryable.length, target.label, "Retrying CDN cache");
+			return result;
+		});
+		progress.finish();
+		for (const [retryIndex, { index }] of retryable.entries()) results[index] = retried[retryIndex];
+		return results;
+	};
+	let results;
+	if (propagatingTarget) results = await warmPropagatingPass(requests);
+	else results = await runWithConcurrency(requests, concurrency, (target) => warmRequest(target));
+	progress.finish();
+	const failedRequests = requests.map((target, index) => ({
+		result: results[index],
+		target
+	})).filter((entry) => !entry.result.ok);
+	const failures = failedRequests.map(({ result: { path, error } }) => ({
 		path,
 		error
 	}));
-	const warmed = results.length - failures.length;
-	console.log(`  CDN warmup: ${warmed}/${paths.length} path(s) warmed.`);
+	const skippedResults = results.filter((result) => result.ok && result.skipped);
+	const skippedTargets = requests.filter((_target, index) => {
+		const result = results[index];
+		return result.ok && result.skipped;
+	});
+	const warmedRequests = requests.filter((_target, index) => {
+		const result = results[index];
+		return result.ok && !result.skipped;
+	});
+	const warmed = results.length - failures.length - skippedResults.length;
+	const warmedRouteHandlerPaths = warmedRequests.filter((target) => target.kind === "app-route").map((target) => target.sourcePathname);
+	const failedRouteHandlerPaths = failedRequests.filter(({ target }) => target.kind === "app-route").map(({ target }) => target.sourcePathname);
+	printCdnWarmRouteReport(requests, results.map((result) => !result.ok ? "failed" : result.skipped ? "skipped" : "warmed"));
+	console.log(`  CDN warmup: ${warmed} warmed, ${skippedResults.length} skipped, ${failures.length} failed.`);
+	for (const skipped of skippedResults.slice(0, 5)) console.log(`  CDN warmup skipped ${skipped.path}: ${skipped.reason}`);
 	if (failures.length > 0) {
 		for (const failure of failures.slice(0, 5)) console.warn(`  CDN warmup failed for ${failure.path}: ${failure.error}`);
 		if (failures.length > 5) console.warn(`  CDN warmup: ${failures.length - 5} additional failure(s) omitted.`);
 	}
 	const result = {
-		total: paths.length,
+		total: requests.length,
 		warmed,
+		skipped: skippedResults.length,
 		failed: failures.length,
-		failures
+		failures,
+		skippedTargets,
+		warmedPlan: {
+			loadingShellPaths: warmedRequests.filter((target) => target.kind === "rsc-loading-shell").map((target) => target.sourcePathname),
+			pagesDataPaths: warmedRequests.filter((target) => target.kind === "pages-data").map((target) => target.sourcePathname),
+			paths: warmedRequests.filter((target) => target.kind === "html").map((target) => target.sourcePathname),
+			rscPaths: warmedRequests.filter((target) => target.kind === "rsc-full").map((target) => target.sourcePathname),
+			...warmedRouteHandlerPaths.length > 0 ? { routeHandlerPaths: warmedRouteHandlerPaths } : {}
+		},
+		retryPlan: {
+			loadingShellPaths: failedRequests.filter(({ target }) => target.kind === "rsc-loading-shell").map(({ target }) => target.sourcePathname),
+			pagesDataPaths: failedRequests.filter(({ target }) => target.kind === "pages-data").map(({ target }) => target.sourcePathname),
+			paths: failedRequests.filter(({ target }) => target.kind === "html").map(({ target }) => target.sourcePathname),
+			rscPaths: failedRequests.filter(({ target }) => target.kind === "rsc-full").map(({ target }) => target.sourcePathname),
+			...failedRouteHandlerPaths.length > 0 ? { routeHandlerPaths: failedRouteHandlerPaths } : {}
+		}
 	};
-	if (options.strict && failures.length > 0) throw new Error(`CDN warmup failed for ${failures.length}/${paths.length} path(s). First failure: ${failures[0].path}: ${failures[0].error}`);
+	if (options.strict && failures.length > 0) throw new Error(`CDN warmup failed for ${failures.length}/${requests.length} request(s). First failure: ${failures[0].path}: ${failures[0].error}`);
 	return result;
 }
 async function warmCdnCacheFromPrerender(options) {
-	const paths = readPrerenderWarmPaths(options.root, {
+	const plan = readPrerenderWarmPlan(options.root, {
 		includeFallbackShells: options.includeFallbackShells,
 		strict: options.strict
 	});
+	const warmPlan = {
+		deploymentId: plan.deploymentId,
+		loadingShellPaths: plan.loadingShellPaths,
+		pagesDataPaths: plan.pagesDataPaths,
+		paths: plan.paths,
+		routeHandlerPaths: plan.routeHandlerPaths,
+		rscPaths: plan.rscPaths
+	};
 	return warmCdnCache({
 		...options,
-		paths
+		...warmPlan,
+		expectedBuildId: options.expectedBuildId ?? (options.validateBuildIdentity === false ? void 0 : plan.buildIdentity),
+		expectedRscBuildId: options.expectedRscBuildId ?? plan.rscBuildId
 	});
 }
 //#endregion
-export { DEFAULT_CDN_WARM_TIMEOUT_MS, buildWarmupUrl, getWarmPathsFromPrerenderManifest, readPrerenderWarmPaths, warmCdnCache, warmCdnCacheFromPrerender };
+export { CdnOperationProgress, DEFAULT_CDN_WARM_CONCURRENCY, DEFAULT_CDN_WARM_TIMEOUT_MS, DEFAULT_STAGED_READINESS_INTERVAL_MS, DEFAULT_STAGED_READINESS_PHASE_TIMEOUT_MS, DEFAULT_STAGED_READINESS_RETRIES, buildWarmupUrl, createCdnWarmTargets, createPrerenderWarmPlan, getWarmPathsFromPrerenderManifest, readPrerenderWarmPaths, readPrerenderWarmPlan, waitForCdnWarmTargetReadiness, warmCdnCache, warmCdnCacheFromPrerender };