@salesforce/storefront-next-dev 1.4.0 → 1.5.0-alpha.0

package/dist/audit/catalog/categories/performance/rules/html-document-size.md

@@ -0,0 +1,20 @@
+---
+id: performance/html-document-size
+title: HTML Document Size
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.network-har, playhouse.scripts]
+---
+
+## Intent
+Checks that each page's HTML is 350 KiB or less before compression. The browser has to download and parse all of the HTML, and React then hydrates it, before the page responds, so large HTML slows the first render on mobile. The result splits each page into its main parts (page data, app config, other inline scripts and markup) so the biggest one is easy to spot.
+## Inspect
+The rule script takes the decoded size of each page's document response from `network-mobile-cold.har`. It splits that size using the inline scripts Playhouse archived from the same HTML (`scripts/index.json`): React Router page data (`streamController.enqueue(...)` scripts), the app config (`window.__APP_CONFIG__`), other inline scripts, and everything else, counted as markup.
+## Evaluate
+Pass when every measured page's decoded HTML is at or under 350 KiB; fail otherwise. A page whose document can't be matched in the HAR is skipped. If no page can be measured, the rule is not decided.
+## Evidence
+The document's HAR entry for each failing page, with its size and breakdown.
+## Remediation
+Start with the largest part of the breakdown: page data is covered by `performance/page-data-size`, the app config by `performance/app-config-size`, and markup by `performance/dom-size`. Re-run Playhouse to confirm each page's HTML is at or under 350 KiB.
+## Examples
+Compliant: a PLP of 290 KiB. Problematic: a PDP of 501 KiB, of which 297 KiB is page data.

package/dist/audit/catalog/categories/performance/rules/image-dimensions.js

@@ -0,0 +1,141 @@
+import { o as readImageRun } from "../../../../../images.js";
+import { z } from "zod";
+
+//#region src/audit/catalog/categories/performance/rules/image-dimensions.ts
+/** Shifts smaller than this aren't noticeable. */
+const MIN_SHIFT = .01;
+const UNSIZED_CAUSE = "Unsized image element";
+const elementSchema = z.object({
+	selector: z.string().nullable(),
+	top: z.number().nullable(),
+	bottom: z.number().nullable()
+}).strict();
+const dataSchema = z.object({
+	cell: z.string(),
+	minShift: z.number(),
+	pages: z.array(z.object({
+		page: z.string(),
+		lighthouseArtifact: z.string(),
+		cls: z.number().nullable(),
+		unsizedShift: z.number(),
+		shifts: z.array(z.object({
+			cluster: z.number(),
+			score: z.number(),
+			element: elementSchema,
+			culprits: z.array(elementSchema.extend({
+				url: z.string().nullable(),
+				plausible: z.boolean()
+			}).strict())
+		}).strict()),
+		unsizedImages: z.array(elementSchema.extend({ url: z.string() }).strict())
+	}).strict()),
+	skipped: z.array(z.object({
+		page: z.string(),
+		reason: z.string()
+	}).strict())
+}).strict();
+const SRC = /\ssrc="([^"]+)"/;
+const element = (node) => ({
+	selector: node?.selector ?? null,
+	top: node?.boundingRect?.top ?? null,
+	bottom: node?.boundingRect?.bottom ?? null
+});
+/**
+* Lighthouse's layout shift culprits insight links a shift to unsized images by timing, so it can name an image that
+* is nowhere near the shifted element. An image moves an element only from above it or beside it, so culprits that
+* start below the element's top are marked implausible and don't count.
+*/
+function unsizedShifts(run$1) {
+	const urls = new Map((run$1.lhr.audits["unsized-images"]?.details?.items ?? []).flatMap((item) => item.url && item.node?.path ? [[item.node.path, item.url]] : []));
+	const shifts = [];
+	let unsizedShift = 0;
+	(run$1.lhr.audits["cls-culprits-insight"]?.details?.items ?? []).forEach((cluster, index) => {
+		let clusterShift = 0;
+		for (const row of cluster.items ?? []) {
+			const causes = (row.subItems?.items ?? []).filter((item) => item.cause === UNSIZED_CAUSE);
+			if (!causes.length || !row.node?.selector) continue;
+			const shifted = element(row.node);
+			const culprits = causes.flatMap(({ extra }) => {
+				if (!extra?.selector) return [];
+				const src = extra.snippet?.match(SRC)?.[1];
+				const url = extra.path && urls.get(extra.path) || (src && !src.includes("…") ? src : null);
+				const image = element(extra);
+				return [{
+					...image,
+					url,
+					plausible: image.top === null || shifted.top === null || image.top <= shifted.top
+				}];
+			});
+			const score = row.score ?? 0;
+			shifts.push({
+				cluster: index,
+				score,
+				element: shifted,
+				culprits
+			});
+			if (causes.length > culprits.length || culprits.some((culprit) => culprit.plausible)) clusterShift += score;
+		}
+		unsizedShift = Math.max(unsizedShift, clusterShift);
+	});
+	return {
+		unsizedShift,
+		shifts
+	};
+}
+const round = (value) => value.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
+const run = async ({ pages, playhouse }) => {
+	const data = {
+		cell: "mobile-cold",
+		minShift: MIN_SHIFT,
+		pages: [],
+		skipped: []
+	};
+	for (const page of pages) {
+		const imageRun = await readImageRun(playhouse, page.label);
+		if ("reason" in imageRun) {
+			data.skipped.push({
+				page: page.label,
+				reason: imageRun.reason
+			});
+			continue;
+		}
+		if (!imageRun.lhr.audits["cls-culprits-insight"]) {
+			data.skipped.push({
+				page: page.label,
+				reason: "The Lighthouse result has no layout shift culprits insight."
+			});
+			continue;
+		}
+		data.pages.push({
+			page: page.label,
+			lighthouseArtifact: imageRun.lighthouseArtifact,
+			cls: imageRun.lhr.audits["cumulative-layout-shift"]?.numericValue ?? null,
+			...unsizedShifts(imageRun),
+			unsizedImages: (imageRun.lhr.audits["unsized-images"]?.details?.items ?? []).flatMap((item) => item.url ? [{
+				url: item.url,
+				...element(item.node)
+			}] : [])
+		});
+	}
+	if (!data.pages.length) return { data };
+	if (data.pages.some((item) => item.unsizedShift >= MIN_SHIFT)) return { data };
+	const unsized = data.pages.reduce((total, item) => total + item.unsizedImages.length, 0);
+	return {
+		data,
+		decision: {
+			status: "pass",
+			summary: `Images without dimensions cause no noticeable layout shift on ${data.pages.map((item) => item.page).join(", ")}${unsized ? `; Lighthouse lists ${unsized} image${unsized === 1 ? "" : "s"} without width and height, but their layout reserves the space` : ""}.`,
+			evidence: data.pages.map((item) => ({
+				type: "playhouse",
+				page: item.page,
+				artifact: item.lighthouseArtifact,
+				pointer: "/audits/cls-culprits-insight",
+				value: `CLS ${round(item.cls ?? 0)}, ${round(item.unsizedShift)} from unsized images`
+			}))
+		}
+	};
+};
+var image_dimensions_default = run;
+
+//#endregion
+export { dataSchema, image_dimensions_default as default };

package/dist/audit/catalog/categories/performance/rules/image-dimensions.md

@@ -0,0 +1,22 @@
+---
+id: performance/image-dimensions
+title: Image Dimensions
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.lighthouse, source.code]
+---
+
+## Intent
+Checks that images without `width` and `height` don't shift the page's layout as they load. A browser can only reserve space for an image when it knows its size, from its attributes or from CSS such as a fixed height or `aspect-ratio`. An image without attributes is fine when its CSS or container already reserves the space, so only images that actually shift the layout are reported.
+## Inspect
+The rule script reads Lighthouse's layout shift culprits insight (`cls-culprits-insight`) from each page's mobile cold-cache median run. Lighthouse links a shift to unsized images by timing, not position, so it can name the wrong image or none: the script marks a named culprit `plausible: false` when it starts below the shifted element's top (an image can only move content below or beside it), and `unsizedShift` is the worst cluster's shift that a plausible or unnamed image could have caused. `unsizedImages` lists every image Lighthouse found without dimensions, with its position. The script passes when no page's `unsizedShift` reaches `minShift`.
+
+Otherwise, for each page with a shift of at least `minShift`, find the candidates: plausible culprits, and unsized images above or beside the shifted element (`top` at most the element's `top`). Images inside a shifted container don't move it. In the project source, find the component that renders each one and check whether its size is fixed before it loads: `width` and `height` attributes, a CSS height and width (a fixed height alone still lets the width change), `aspect-ratio`, or a wrapper with a fixed size or aspect ratio. A candidate whose size is fixed can't cause the shift.
+## Evaluate
+Fail when a candidate's size isn't fixed before it loads and it can move the shifted element; medium severity when the page's CLS is over 0.1, low when it's within. Pass when there is no candidate or every candidate's size is fixed, and say the shift comes from something other than an image (for example a web font or content inserted after load), naming the shifted element. Undecided only when no page could be measured.
+## Evidence
+The layout shift culprits insight for each page with a shift, with the shift score and the shifted element as its `value`, and the source file and line of each image that can cause it.
+## Remediation
+Give the image `width` and `height` attributes (`DynamicImage` passes them through), or fix its size or its container's `aspect-ratio` in CSS. Re-run Playhouse to confirm the shift is gone.
+## Examples
+Compliant: product tiles whose image wrapper has `aspect-ratio: 1`; a logo with a fixed CSS height and width. Problematic: a banner image with only `w-full` and no dimensions above the product grid, so the grid moves down when it loads.

package/dist/audit/catalog/categories/performance/rules/image-transformation.js

@@ -0,0 +1,117 @@
+import { a as kib, i as isImage, o as readImageRun, t as MIN_SAVINGS_BYTES } from "../../../../../images.js";
+import { z } from "zod";
+
+//#region src/audit/catalog/categories/performance/rules/image-transformation.ts
+/** Dynamic Imaging Service URLs: `/dw/image/v2/<realm>/on/demandware.static/...`. */
+const DIS_PATH = /\/dw\/image\/v\d+\//i;
+/** B2C Commerce static files (catalog and library images) served as uploaded. */
+const STATIC_PATH = /\/on\/demandware\.static\//i;
+/** Formats DIS isn't used for here: vector images, and animated GIFs (`performance/large-images` suggests a video). */
+const OUT_OF_SCOPE = /^image\/(svg\+xml|gif|x-icon|vnd\.microsoft\.icon)/;
+const LEGACY = /^image\/(jpeg|png)/;
+const problemSchema = z.enum([
+	"bypasses-dis",
+	"not-resized",
+	"legacy-format"
+]);
+const dataSchema = z.object({
+	cell: z.string(),
+	minBytes: z.number(),
+	pages: z.array(z.object({
+		page: z.string(),
+		harArtifact: z.string(),
+		checked: z.number(),
+		dis: z.number(),
+		images: z.array(z.object({
+			url: z.string(),
+			entry: z.number(),
+			bytes: z.number(),
+			mimeType: z.string(),
+			problems: z.array(problemSchema),
+			lcp: z.boolean(),
+			requestedBeforeLcp: z.boolean().nullable()
+		}).strict())
+	}).strict()),
+	skipped: z.array(z.object({
+		page: z.string(),
+		reason: z.string()
+	}).strict())
+}).strict();
+function problems(url, mimeType) {
+	if (!DIS_PATH.test(url.pathname)) return ["bypasses-dis"];
+	const found = [];
+	if (!url.searchParams.has("sw") && !url.searchParams.has("sh")) found.push("not-resized");
+	if (LEGACY.test(mimeType)) found.push("legacy-format");
+	return found;
+}
+const run = async ({ pages, playhouse }) => {
+	const data = {
+		cell: "mobile-cold",
+		minBytes: MIN_SAVINGS_BYTES,
+		pages: [],
+		skipped: []
+	};
+	for (const page of pages) {
+		const imageRun = await readImageRun(playhouse, page.label);
+		if ("reason" in imageRun) {
+			data.skipped.push({
+				page: page.label,
+				reason: imageRun.reason
+			});
+			continue;
+		}
+		const result = {
+			page: page.label,
+			harArtifact: imageRun.harArtifact,
+			checked: 0,
+			dis: 0,
+			images: []
+		};
+		imageRun.entries.forEach((entry, index) => {
+			const mimeType = entry.response.content?.mimeType ?? "";
+			const bytes = entry.response.bodySize ?? 0;
+			if (!isImage(entry) || entry.response.status !== 200 || OUT_OF_SCOPE.test(mimeType) || bytes < MIN_SAVINGS_BYTES) return;
+			let url;
+			try {
+				url = new URL(entry.request.url);
+			} catch {
+				return;
+			}
+			if (!DIS_PATH.test(url.pathname) && !STATIC_PATH.test(url.pathname)) return;
+			result.checked += 1;
+			if (DIS_PATH.test(url.pathname)) result.dis += 1;
+			const found = problems(url, mimeType);
+			const start = imageRun.startMs(entry);
+			if (found.length) result.images.push({
+				url: entry.request.url,
+				entry: index,
+				bytes,
+				mimeType,
+				problems: found,
+				lcp: entry.request.url === imageRun.lcpUrl,
+				requestedBeforeLcp: Number.isFinite(start) && imageRun.lcpMs !== null ? start < imageRun.lcpMs : null
+			});
+		});
+		data.pages.push(result);
+	}
+	const checked = data.pages.reduce((total, item) => total + item.checked, 0);
+	if (!checked) return { data };
+	if (data.pages.some((item) => item.images.length)) return { data };
+	return {
+		data,
+		decision: {
+			status: "pass",
+			summary: `All ${checked} Commerce images of ${kib(MIN_SAVINGS_BYTES)} or more on ${data.pages.filter((item) => item.checked).map((item) => item.page).join(", ")} are resized by DIS and served as WebP or AVIF.`,
+			evidence: data.pages.filter((item) => item.checked).map((item) => ({
+				type: "playhouse",
+				page: item.page,
+				artifact: item.harArtifact,
+				value: `${item.checked} Commerce image${item.checked === 1 ? "" : "s"} checked, all through DIS`
+			}))
+		}
+	};
+};
+var image_transformation_default = run;
+
+//#endregion
+export { dataSchema, image_transformation_default as default };

package/dist/audit/catalog/categories/performance/rules/image-transformation.md

@@ -0,0 +1,22 @@
+---
+id: performance/image-transformation
+title: Image Transformation
+severity: high
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.network-har, source.code]
+---
+
+## Intent
+Checks that product and content images from B2C Commerce are served through the Dynamic Imaging Service (DIS), which resizes them to the width the page asks for and converts them to WebP or AVIF. An image linked as uploaded (`/on/demandware.static/...` instead of `/dw/image/v2/...`) is sent at its full original size and format, often several times larger than needed. Vector images (SVG) and animated GIFs are left out: DIS doesn't help them, and `performance/large-images` covers GIFs.
+## Inspect
+The rule script lists every image of 10 KiB or more that each page's mobile cold-cache median run downloaded from B2C Commerce, and flags three problems: `bypasses-dis` (a static file URL, not DIS), `not-resized` (a DIS URL without `sw` or `sh`) and `legacy-format` (DIS returned JPEG or PNG instead of WebP or AVIF). If no image has a problem, it passes and this rule needs no analysis.
+
+Otherwise, use the `data` file (sizes are in bytes): each page lists the flagged `images` with their HAR `entry`, size, response type, problems, and whether the image is the page's LCP image (`lcp`) or was requested before the LCP. The HAR is the run's `harArtifact`, which redacts query values; cite it as the data does. For each, find where the project builds the image URL. The storefront's `DynamicImage` component and its URL helpers (`toImageUrl`, `getSrc`) produce DIS URLs; images usually bypass DIS when a component renders the API's `link` directly instead of `disBaseLink`, when a content asset's HTML embeds static URLs, or when a host isn't recognized as DIS-capable (check `images.host` and `images.realmHostMappings` in the app config).
+## Evaluate
+Report one `finding` for the rule, covering every flagged image. Group images by the component or content that renders them. Base severity on size: high when a flagged image is 200 KiB or more, or the flagged images on a page total 200 KiB or more; medium at 50 KiB or more; low otherwise. Raise it one level when a flagged image is the page's LCP image or is requested before the LCP, since it then slows the page's main content. Suggest rendering the image through `DynamicImage` (or its URL helpers) with widths that match the layout.
+## Evidence
+For each component or content source: one flagged image (`playhouse`, citing the HAR with pointer `/log/entries/<entry>` and a `value` such as `CEP754_B1245_01.jpg, 640 KiB, image/jpeg: not through DIS`), and `source` evidence for where its URL is built.
+## Remediation
+Build Commerce image URLs through `DynamicImage` or its URL helpers from the image's `disBaseLink`, with `widths` for each breakpoint, so DIS resizes and converts them. Re-run Playhouse to confirm every Commerce image is a resized DIS URL served as WebP or AVIF.
+## Examples
+Compliant: `/dw/image/v2/ABCD_PRD/on/demandware.static/.../shoe.webp?sw=720&q=70&sfrm=jpg`, served as `image/webp`. Problematic: `/on/demandware.static/-/Sites-catalog/default/dw1234/images/large/shoe.jpg`, the 2400-pixel original, used as a gallery thumbnail.

package/dist/audit/catalog/categories/performance/rules/javascript-size.js

@@ -0,0 +1,126 @@
+import { t as readLivePage } from "../../../../../live.js";
+import { z } from "zod";
+
+//#region src/audit/catalog/categories/performance/rules/javascript-size.ts
+const BUDGET_BYTES = 14e5;
+const HIGH_BYTES = 27e5;
+const LARGEST = 10;
+const pageSchema = z.object({
+	page: z.string(),
+	lighthouseArtifact: z.string(),
+	scripts: z.number().int(),
+	decodedBytes: z.number(),
+	transferBytes: z.number(),
+	beforeLoad: z.object({
+		scripts: z.number().int(),
+		decodedBytes: z.number()
+	}).strict(),
+	afterLoad: z.object({
+		scripts: z.number().int(),
+		decodedBytes: z.number()
+	}).strict(),
+	largest: z.array(z.object({
+		file: z.string(),
+		item: z.number().int(),
+		decodedBytes: z.number(),
+		transferBytes: z.number()
+	}).strict())
+}).strict();
+const dataSchema = z.object({
+	budget: z.number(),
+	pages: z.array(pageSchema),
+	skipped: z.array(z.object({
+		page: z.string(),
+		reason: z.string()
+	}).strict())
+}).strict();
+const mb = (bytes) => `${(bytes / 1e6).toFixed(2)} MB`;
+const kib = (bytes) => `${Math.round(bytes / 1024)} KiB`;
+function measured(live) {
+	const sum = (scripts) => scripts.reduce((total, script) => total + script.decodedBytes, 0);
+	const before = live.scripts.filter((script) => script.beforeLoad);
+	const after = live.scripts.filter((script) => !script.beforeLoad);
+	return {
+		page: live.page,
+		lighthouseArtifact: live.lighthouseArtifact,
+		scripts: live.scripts.length,
+		decodedBytes: sum(live.scripts),
+		transferBytes: live.scripts.reduce((total, script) => total + script.transferBytes, 0),
+		beforeLoad: {
+			scripts: before.length,
+			decodedBytes: sum(before)
+		},
+		afterLoad: {
+			scripts: after.length,
+			decodedBytes: sum(after)
+		},
+		largest: live.scripts.slice().sort((a, b) => b.decodedBytes - a.decodedBytes).slice(0, LARGEST).map(({ file, item, decodedBytes, transferBytes }) => ({
+			file,
+			item,
+			decodedBytes,
+			transferBytes
+		}))
+	};
+}
+const totalEvidence = (page) => ({
+	type: "playhouse",
+	page: page.page,
+	artifact: page.lighthouseArtifact,
+	pointer: "/audits/network-requests/details/items",
+	value: `${mb(page.decodedBytes)} first-party JavaScript (${kib(page.transferBytes)} transferred) in ${page.scripts} scripts, ${page.beforeLoad.scripts} before load (budget ${mb(BUDGET_BYTES)})`
+});
+/** Measured on the live site only: the local build may be built from other code, so it never adds to these numbers. */
+async function javascriptSize({ pages, playhouse }) {
+	const data = {
+		budget: BUDGET_BYTES,
+		pages: [],
+		skipped: []
+	};
+	for (const { label } of pages) {
+		const live = await readLivePage(playhouse, label);
+		if ("reason" in live) {
+			data.skipped.push({
+				page: label,
+				reason: live.reason
+			});
+			continue;
+		}
+		if (!live.scripts.length) {
+			data.skipped.push({
+				page: label,
+				reason: "The run loaded no scripts from its own bundle path (mobify/bundle)."
+			});
+			continue;
+		}
+		data.pages.push(measured(live));
+	}
+	if (!data.pages.length) return { data };
+	const over = data.pages.filter((page) => page.decodedBytes > BUDGET_BYTES);
+	const list = data.pages.map((page) => `${page.page} ${mb(page.decodedBytes)}`).join(", ");
+	if (!over.length) return {
+		data,
+		decision: {
+			status: "pass",
+			summary: `First-party JavaScript is within ${mb(BUDGET_BYTES)} on every measured page (${list}).`,
+			evidence: data.pages.map(totalEvidence)
+		}
+	};
+	return {
+		data,
+		decision: {
+			status: "fail",
+			severity: over.some((page) => page.decodedBytes >= HIGH_BYTES) ? "high" : "medium",
+			summary: `First-party JavaScript is over ${mb(BUDGET_BYTES)} on ${over.map((page) => `${page.page} (${mb(page.decodedBytes)} in ${page.scripts} scripts)`).join("; ")}.`,
+			evidence: over.flatMap((page) => [totalEvidence(page), ...page.largest.slice(0, 3).map((script) => ({
+				type: "playhouse",
+				page: page.page,
+				artifact: page.lighthouseArtifact,
+				pointer: `/audits/network-requests/details/items/${script.item}/resourceSize`,
+				value: `${script.file} ${kib(script.decodedBytes)}`
+			}))])
+		}
+	};
+}
+
+//#endregion
+export { dataSchema, javascriptSize as default };

package/dist/audit/catalog/categories/performance/rules/javascript-size.md

@@ -0,0 +1,20 @@
+---
+id: performance/javascript-size
+title: First-Party JavaScript Size
+severity: high
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.lighthouse]
+---
+
+## Intent
+Checks that the storefront's own JavaScript on each page, everything served from the bundle path (`/mobify/bundle/…`) including the npm packages bundled into it, is 1.4 MB or less before compression, just above the Storefront Next template's heaviest page (its PDP, about 1.36 MB). The browser downloads, parses and runs all of it before the page responds to taps, so it adds directly to mobile load and blocking time. Scripts loaded by tags (analytics, pixels, tag managers) are third-party and aren't counted here.
+## Inspect
+The rule script reads the mobile cold-cache median run's `runs/<runId>/lhr.json` (the run named by `summary-lcp.json`) and keeps the `network-requests` items that are scripts served from `/mobify/bundle/`. It sums their decoded size (`resourceSize`) and transfer size, and splits them at the run's own load event (`observedLoad`). Everything here is measured on the live site; the local build never adds to it, because the live site may be built from other code.
+## Evaluate
+Pass when every measured page's decoded first-party JavaScript is at or under 1,400,000 bytes; fail otherwise, with high severity when a page is at or over 2,700,000 bytes and medium below that. A page whose run has no `network-requests` audit, or that loaded no first-party scripts, is skipped. If no page can be measured, the rule is not decided.
+## Evidence
+For each page, the run's `network-requests` items with the total decoded and transfer bytes and the script count; for a failing page, the largest scripts' `resourceSize` too.
+## Remediation
+See `performance/reduce-javascript-on-load`, which analyzes a local build of the project and recommends code to load later. Load code for closed overlays, below-the-fold widgets and forms with `React.lazy` or a dynamic `import()` when it's first needed. Deploy the changes and re-run the audit to confirm each page is at or under 1.4 MB.
+## Examples
+Compliant: a home page that loads 131 first-party scripts, 1.16 MB decoded. Problematic: a PDP that loads 2.9 MB, a third of it a carousel and a date library imported by the page route.

package/dist/audit/catalog/categories/performance/rules/large-images.js

@@ -0,0 +1,187 @@
+import { a as kib, o as readImageRun, t as MIN_SAVINGS_BYTES } from "../../../../../images.js";
+import { z } from "zod";
+
+//#region src/audit/catalog/categories/performance/rules/large-images.ts
+/** An image is oversized when it has at least this many times the pixels the screen needs (srcset steps leave some slack). */
+const MIN_PIXEL_RATIO = 2;
+const reasonSchema = z.object({
+	kind: z.enum([
+		"oversized",
+		"animated-gif",
+		"format"
+	]),
+	savingsBytes: z.number(),
+	detail: z.string()
+}).strict();
+const imageSchema = z.object({
+	url: z.string(),
+	item: z.number(),
+	bytes: z.number(),
+	shown: z.object({
+		width: z.number(),
+		height: z.number()
+	}).strict().nullable(),
+	intrinsic: z.object({
+		width: z.number(),
+		height: z.number()
+	}).strict().nullable(),
+	savingsBytes: z.number(),
+	reasons: z.array(reasonSchema),
+	selector: z.string().nullable(),
+	label: z.string().nullable(),
+	aboveFold: z.boolean().nullable(),
+	requestedBeforeLcp: z.boolean().nullable()
+}).strict();
+const dataSchema = z.object({
+	cell: z.string(),
+	minSavingsBytes: z.number(),
+	minPixelRatio: z.number(),
+	pages: z.array(z.object({
+		page: z.string(),
+		dpr: z.number(),
+		lcpMs: z.number().nullable(),
+		lighthouseArtifact: z.string(),
+		harArtifact: z.string(),
+		lighthouseItems: z.number(),
+		dropped: z.number(),
+		totalSavingsBytes: z.number(),
+		images: z.array(imageSchema)
+	}).strict()),
+	skipped: z.array(z.object({
+		page: z.string(),
+		reason: z.string()
+	}).strict())
+}).strict();
+const SIZE_REASON = /\((\d+)x(\d+)\) for its displayed dimensions/;
+/**
+* Lighthouse's compression-only estimate isn't used: it targets a fixed number of bytes per CSS pixel, so it counts
+* an image right-sized for a 3× screen as badly compressed (it put a q=70 DIS WebP of 21 KiB at 4 KiB, below what
+* DIS produces even at q=30).
+*/
+function otherReason(reason) {
+	if (/video formats/i.test(reason)) return "animated-gif";
+	if (/modern image format|webp|avif/i.test(reason)) return "format";
+	return null;
+}
+/**
+* Lighthouse's image delivery insight compares each image with its displayed size in CSS pixels, which overstates the
+* savings on high-density screens. This recomputes the resize savings at the emulated pixel density, and keeps
+* Lighthouse's format and animated GIF savings.
+*/
+function oversizedImages(run$1) {
+	const result = [];
+	(run$1.lhr.audits["image-delivery-insight"]?.details?.items ?? []).forEach((item, index) => {
+		const rect = item.node?.boundingRect;
+		const shown = rect && rect.width > 0 && rect.height > 0 ? {
+			width: Math.round(rect.width),
+			height: Math.round(rect.height)
+		} : null;
+		const reasons = [];
+		let intrinsic = null;
+		for (const sub of item.subItems?.items ?? []) {
+			const size = sub.reason.match(SIZE_REASON);
+			if (size) {
+				intrinsic = {
+					width: Number(size[1]),
+					height: Number(size[2])
+				};
+				if (!shown) continue;
+				const needed = {
+					width: Math.min(intrinsic.width, Math.ceil(shown.width * run$1.dpr)),
+					height: Math.min(intrinsic.height, Math.ceil(shown.height * run$1.dpr))
+				};
+				const ratio = intrinsic.width * intrinsic.height / (needed.width * needed.height);
+				const savings = Math.round(item.totalBytes * (1 - 1 / ratio));
+				if (ratio >= MIN_PIXEL_RATIO && savings >= MIN_SAVINGS_BYTES) reasons.push({
+					kind: "oversized",
+					savingsBytes: savings,
+					detail: `${intrinsic.width}×${intrinsic.height} delivered; ${needed.width}×${needed.height} shows it at ${shown.width}×${shown.height} on a ${run$1.dpr}× screen`
+				});
+				continue;
+			}
+			const kind = otherReason(sub.reason);
+			if (kind && sub.wastedBytes >= MIN_SAVINGS_BYTES) reasons.push({
+				kind,
+				savingsBytes: Math.round(sub.wastedBytes),
+				detail: sub.reason
+			});
+		}
+		if (!reasons.length) return;
+		const entry = run$1.entries.find((candidate) => candidate.request.url === item.url);
+		const start = entry ? run$1.startMs(entry) : NaN;
+		result.push({
+			url: item.url,
+			item: index,
+			bytes: Math.round(item.totalBytes),
+			shown,
+			intrinsic,
+			savingsBytes: Math.max(...reasons.map((reason) => reason.savingsBytes)),
+			reasons,
+			selector: item.node?.selector ?? null,
+			label: item.node?.nodeLabel ?? null,
+			aboveFold: rect ? rect.top < run$1.viewportHeight : null,
+			requestedBeforeLcp: Number.isFinite(start) && run$1.lcpMs !== null ? start < run$1.lcpMs : null
+		});
+	});
+	return result.slice().sort((a, b) => b.savingsBytes - a.savingsBytes);
+}
+const run = async ({ pages, playhouse }) => {
+	const data = {
+		cell: "mobile-cold",
+		minSavingsBytes: MIN_SAVINGS_BYTES,
+		minPixelRatio: MIN_PIXEL_RATIO,
+		pages: [],
+		skipped: []
+	};
+	for (const page of pages) {
+		const imageRun = await readImageRun(playhouse, page.label);
+		if ("reason" in imageRun) {
+			data.skipped.push({
+				page: page.label,
+				reason: imageRun.reason
+			});
+			continue;
+		}
+		const insight = imageRun.lhr.audits["image-delivery-insight"];
+		if (!insight) {
+			data.skipped.push({
+				page: page.label,
+				reason: "The Lighthouse result has no image delivery insight."
+			});
+			continue;
+		}
+		const items = insight.details?.items?.length ?? 0;
+		const images = oversizedImages(imageRun);
+		data.pages.push({
+			page: page.label,
+			dpr: imageRun.dpr,
+			lcpMs: imageRun.lcpMs,
+			lighthouseArtifact: imageRun.lighthouseArtifact,
+			harArtifact: imageRun.harArtifact,
+			lighthouseItems: items,
+			dropped: items - images.length,
+			totalSavingsBytes: images.reduce((total, image) => total + image.savingsBytes, 0),
+			images
+		});
+	}
+	if (!data.pages.length) return { data };
+	if (data.pages.some((item) => item.images.length)) return { data };
+	return {
+		data,
+		decision: {
+			status: "pass",
+			summary: `No image on ${data.pages.map((item) => item.page).join(", ")} would save ${kib(MIN_SAVINGS_BYTES)} or more by resizing, converting to WebP or AVIF, or replacing an animated GIF.`,
+			evidence: data.pages.map((item) => ({
+				type: "playhouse",
+				page: item.page,
+				artifact: item.lighthouseArtifact,
+				pointer: "/audits/image-delivery-insight",
+				value: item.lighthouseItems ? `Lighthouse listed ${item.lighthouseItems} image${item.lighthouseItems === 1 ? "" : "s"}; each is right-sized for a ${item.dpr}× screen or would save less than ${kib(MIN_SAVINGS_BYTES)}` : "Lighthouse found no image delivery savings"
+			}))
+		}
+	};
+};
+var large_images_default = run;
+
+//#endregion
+export { dataSchema, large_images_default as default };