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

package/dist/audit/catalog/categories/best-practices/rules/error-boundaries.md

@@ -0,0 +1,19 @@
+---
+id: best-practices/error-boundaries
+title: Route Error Pages
+severity: medium
+appliesTo: [route]
+inputs: [source.code, manual.failure-state]
+---
+## Intent
+Checks that when a route's loader, action or rendering fails, shoppers see a clear error page with the right HTTP status and a way to continue, and that the error is logged. Without this, a failure shows a blank or misleading page.
+## Inspect
+Trace representative route failures to their route-level error handling and inspect the user-visible status, recovery action, and logging boundary.
+## Evaluate
+Report missing or misleading handling for a demonstrated production failure path; do not require a particular framework abstraction by name.
+## Evidence
+Cite the failure path, route source, response/status behavior, and visible fallback.
+## Remediation
+Add scoped error handling that preserves status semantics, safe messaging, recovery, and server-side diagnostics.
+## Examples
+Compliant: failed product load renders a scoped retry state with correct status. Problematic: uncaught failure renders blank content. Ambiguous: global platform handling not observable.

package/dist/audit/catalog/categories/best-practices/rules/production-integrations.md

@@ -0,0 +1,20 @@
+---
+id: best-practices/production-integrations
+title: No Mock or Demo Integrations
+severity: critical
+appliesTo: [cart, checkout, account]
+inputs: [source.code, manual.end-to-end]
+---
+
+## Intent
+Checks that cart, checkout, payment, order management, tax and loyalty flows call real systems, not mock, demo or TODO code left over from development. A stubbed integration in these flows can lose orders or revenue at launch.
+## Inspect
+Trace cart, checkout, payment, OMS, tax, and loyalty flows for demo/mock/TODO paths and validate opaque systems end to end.
+## Evaluate
+Use finding for demonstrated stub behavior; use `not-verified` for opaque integrations lacking test evidence.
+## Evidence
+Cite executable source path or end-to-end result, never a comment marker alone.
+## Remediation
+Wire the production integration or disable the feature until verified.
+## Examples
+Compliant: real integration plus successful E2E evidence. Problematic: mock success on place-order. Ambiguous: TODO comment beside complete code.

package/dist/audit/catalog/categories/best-practices/rules/route-revalidation.md

@@ -0,0 +1,19 @@
+---
+id: best-practices/route-revalidation
+title: "Layout Loaders Don't Rerun Needlessly"
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [source.code]
+---
+## Intent
+Checks that loaders for layouts that stay on screen across pages, such as the app shell, use `shouldRevalidate` so they don't fetch the same data again on every navigation. Rerunning an expensive layout loader slows down every page change.
+## Inspect
+Identify persistent layout loaders and inspect shouldRevalidate against their actual inputs.
+## Evaluate
+Finding requires repeated expensive work without a valid revalidation need.
+## Evidence
+Cite loader, mounted scope, calls, and revalidation behavior.
+## Remediation
+Gate revalidation to meaningful input changes.
+## Examples
+Compliant: scoped shouldRevalidate. Problematic: shell fan-out each navigation. Ambiguous: cheap loader.

package/dist/audit/catalog/categories/best-practices/rules/server-data-loading.md

@@ -0,0 +1,19 @@
+---
+id: best-practices/server-data-loading
+title: First-Render Data Loads on the Server
+severity: high
+appliesTo: [home, plp, pdp]
+inputs: [source.code]
+---
+## Intent
+Checks that the data a page needs for its first render is loaded in server loaders, not fetched in the browser after hydration (with `clientLoader` or a `useEffect` fetch). Loading it on the server sends shoppers and search engines complete HTML without waiting for JavaScript.
+## Inspect
+Trace clientLoader, clientAction, useEffect fetches, and route loader ownership.
+## Evaluate
+Finding requires first-render data being unnecessarily delayed until hydration.
+## Evidence
+Cite route, data need, client call, and available server path.
+## Remediation
+Move required initial data to a server loader/action.
+## Examples
+Compliant: loader-fed render. Problematic: PDP fetch starts after hydration. Ambiguous: post-interaction effect fetch.

package/dist/audit/catalog/categories/performance/CATEGORY.md

@@ -0,0 +1,18 @@
+# Performance
+
+## Purpose and boundaries
+
+Use Playhouse summary, Opportunities, LCP, TBT, third-party, document, and network artifacts as measured evidence. Inspect source only to explain measured symptoms or delivered response policy; never recreate Playhouse algorithms. The exception is `performance/server-request-waterfall`, which maps server-render network calls from source because Playhouse can't see inside the server.
+
+## Investigation sequence
+
+Inspect every rule, compare representative and outlier cells, then trace measured symptoms to source.
+
+## Evidence and redaction
+
+Cite artifact name, JSON pointer/value, page, and line-addressable source where used.
+
+## Severity and blind spots
+
+Uncollected and authenticated pages remain explicit coverage gaps. Header policy requires a representative sanitized HAR with trustworthy response type and size evidence.
+Public-resource caching does not establish that personalized or API responses are safe for shared caches.

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

@@ -0,0 +1,15 @@
+import "../../../../../har.js";
+import { i as kib, n as documentSizeDataSchema, r as documentSizeRule } from "../../../../../document-size.js";
+
+//#region src/audit/catalog/categories/performance/rules/app-config-size.ts
+var app_config_size_default = documentSizeRule({
+	label: "App config",
+	budget: 12 * 1024,
+	value: (size) => size.appConfigBytes,
+	format: kib,
+	evidence: (size) => size.scripts.appConfig[0] ? { artifact: size.scripts.appConfig[0] } : null,
+	decideFailures: false
+});
+
+//#endregion
+export { documentSizeDataSchema as dataSchema, app_config_size_default as default };

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

@@ -0,0 +1,22 @@
+---
+id: performance/app-config-size
+title: App Config Size
+severity: low
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.scripts, source.code]
+---
+
+## Intent
+Checks that the app config Storefront Next writes into every page (`window.__APP_CONFIG__`) is 12 KiB or less. The config is repeated in each page's HTML, so settings the browser never reads add to every page load. When a page is over budget, the report points to the config sections the browser doesn't need.
+## Inspect
+The rule script measures the archived `window.__APP_CONFIG__` script in each page's HTML. If every page is within 12 KiB, it passes and this rule needs no analysis.
+
+Otherwise, use the `data` file (sizes are in bytes): `appConfigSections` gives each top-level config section's size, largest first, and `scripts.appConfig` names the archived config script (relative to the page's `archiveDir`). Read the largest sections in that script, then check in the project where each large section is read (`getConfig`, `useConfig`, `window.__APP_CONFIG__`) and whether the browser needs it, or only server code does. Settings browser code reads at any point, including after hydration or on interaction, are needed. Also check whether the root loader returns the same config, which embeds it in the page data a second time.
+## Evaluate
+Report one `finding` for the rule when any page's config is over 12 KiB; when the config is the same on every page, cite it once and say so. Name the largest sections and, for each, whether the browser reads it, with an approximate size. Suggest keeping server-only settings out of the config sent to the browser, as suggestions the customer can choose from.
+## Evidence
+The archived config script (`playhouse`, with its size as `value`) and `source` evidence for where the large sections are defined and read.
+## Remediation
+Leave settings the browser never reads out of the config sent to the browser. Re-run Playhouse to confirm the config is at or under 12 KiB.
+## Examples
+Compliant: a 10 KiB config. Problematic: a 15 KiB config whose largest section is only read on the server.

package/dist/audit/catalog/categories/performance/rules/cache-control.js

@@ -0,0 +1,59 @@
+import { a as harRuleDataSchema, d as sameHostResponses, i as harRule, o as header, r as cacheControl, u as resourceKind } from "../../../../../har.js";
+
+//#region src/audit/catalog/categories/performance/rules/cache-control.ts
+const dataSchema = harRuleDataSchema;
+const YEAR = 31536e3;
+const HOUR = 3600;
+const DAY = 86400;
+/** A content hash before the extension, e.g. `entry.client-Be9z2OkY.js` or `main.3f2a9c0d.css`; it needs a digit or an uppercase letter so words don't count. */
+function fingerprinted(url) {
+	const hash = /[.-]([A-Za-z0-9_-]{8}|[a-f0-9]{8,})\.(?:m?js|css)$/.exec(new URL(url).pathname)?.[1];
+	return hash !== void 0 && /[0-9A-Z]/.test(hash);
+}
+function minimumMaxAge(entry) {
+	const kind = resourceKind(entry);
+	if (kind === "js" || kind === "css") return fingerprinted(entry.request.url) ? {
+		seconds: YEAR,
+		label: "a fingerprinted asset"
+	} : {
+		seconds: HOUR,
+		label: "a non-fingerprinted script or stylesheet"
+	};
+	if (kind === "image" || kind === "font") return {
+		seconds: DAY,
+		label: `a public ${kind}`
+	};
+}
+var cache_control_default = harRule("same-host script, stylesheet, image and font responses", (match) => {
+	const eligible = sameHostResponses(match).flatMap((item) => {
+		const minimum = minimumMaxAge(item.entry);
+		return minimum ? [{
+			item,
+			minimum
+		}] : [];
+	});
+	const failures = eligible.flatMap(({ item, minimum }) => {
+		const value = header(item.entry, "cache-control");
+		const directives = cacheControl(item.entry);
+		const reasons = [];
+		if (!value) reasons.push("Cache-Control is missing.");
+		else {
+			for (const directive of ["private", "no-store"]) if (directives.has(directive)) reasons.push(`Cache-Control is ${directive}.`);
+			const maxAge = directives.get("max-age");
+			if (maxAge === void 0 || !/^\d+$/.test(maxAge)) reasons.push("Cache-Control has no valid max-age.");
+			else if (Number(maxAge) < minimum.seconds) reasons.push(`max-age=${maxAge} is under ${minimum.seconds} seconds for ${minimum.label}.`);
+		}
+		return reasons.length ? [{
+			entry: item,
+			reasons,
+			headers: { "cache-control": value }
+		}] : [];
+	});
+	return {
+		responses: eligible.length,
+		failures
+	};
+}, "have long enough Cache-Control lifetimes");
+
+//#endregion
+export { dataSchema, cache_control_default as default };

package/dist/audit/catalog/categories/performance/rules/cache-control.md

@@ -0,0 +1,20 @@
+---
+id: performance/cache-control
+title: Browser Cache Lifetimes for Static Files
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.network-har]
+---
+
+## Intent
+Checks the `Cache-Control` header on the storefront's own scripts, stylesheets, images and fonts: at least 1 year for fingerprinted scripts and stylesheets (a content hash in the file name, e.g. `entry.client-Be9z2OkY.js`), 1 hour for other scripts and stylesheets, and 1 day for images and fonts. Long enough lifetimes let browsers and CDNs reuse files instead of downloading them again. HTML, API responses and third-party files are not checked.
+## Inspect
+The rule script matches the final document response in `network-mobile-cold.har` (via `network-mobile-cold.json`) for each page. Only same-host responses with status 200 are checked; third-party responses are skipped. It classifies scripts, stylesheets, images and fonts by content type, treats a script or stylesheet as fingerprinted when its file name carries a content hash (e.g. `entry.client-Be9z2OkY.js`), and reads `Cache-Control`. If no page's document can be matched, the rule is not decided.
+## Evaluate
+Fail when `Cache-Control` is missing, `private` or `no-store`, or its `max-age` is missing or under: 1 year for fingerprinted scripts and stylesheets, 1 hour for other scripts and stylesheets, 1 day for images and fonts. HTML and API/JSON responses are not graded. Pass otherwise.
+## Evidence
+The HAR entry of each failing response (up to 10), with its `Cache-Control`.
+## Remediation
+Set the policy at the layer that owns the response: Managed Runtime or the public edge for bundle assets, a customer CDN when it rewrites headers, application code for application-owned responses. Use `public, max-age=31536000, immutable` only for content-hashed files and shorter lifetimes for URLs that change in place. Re-run Playhouse to confirm.
+## Examples
+Compliant: `app-a1b2c3d4.js` with `public, max-age=31536000`. Problematic: a fingerprinted bundle with no `Cache-Control`, or a product image with `private, no-store`.

package/dist/audit/catalog/categories/performance/rules/cls-budget.js

@@ -0,0 +1,13 @@
+import "../../../../../measured-run.js";
+import { n as metricBudget, t as dataSchema } from "../../../../../metric-budget.js";
+
+//#region src/audit/catalog/categories/performance/rules/cls-budget.ts
+var cls_budget_default = metricBudget({
+	metric: "cls",
+	label: "CLS",
+	threshold: .1,
+	format: (value) => value.toFixed(2)
+});
+
+//#endregion
+export { dataSchema, cls_budget_default as default };

package/dist/audit/catalog/categories/performance/rules/cls-budget.md

@@ -0,0 +1,20 @@
+---
+id: performance/cls-budget
+title: Cumulative Layout Shift (CLS)
+severity: high
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.summary]
+---
+
+## Intent
+Checks that each page's median Cumulative Layout Shift, measured by Lighthouse on mobile with a cold cache, is 0.1 or less, the Core Web Vitals "good" threshold. A high CLS means content jumps around while the page loads.
+## Inspect
+The rule script reads each page's `summary.json` and takes the mobile cold-cache cell's `medianRun.cls`. Playhouse writes 0 for metrics it could not measure, and a rendered page always has a positive LCP, so a run with an LCP of 0 or less measured nothing. Such runs are left out: when any run failed, the script picks the median again from the measured runs the way Playhouse does (the run closest to the median LCP, ties to the earlier run) and reads that run's `runs[].row.cls`.
+## Evaluate
+Pass when every measured page's median CLS is at or under 0.1; fail otherwise. A page without a mobile cold-cache cell, or without any measured run, is skipped. If no page can be measured, the rule is not decided.
+## Evidence
+One `summary.json` pointer per page, `/cells/<i>/medianRun/cls` (or `/runs/<j>/row/cls` when runs were left out), with the measured value and how many runs were not measured.
+## Remediation
+Use `opportunities.json` and `report-mobile-cold.html` for the failing page to find the shifting elements. Reserve space for images, embeds and late-loading content (explicit width/height or aspect-ratio), and avoid inserting content above existing content. Re-run the same Playhouse capture to confirm the mobile cold-cache median is at or under 0.1.
+## Examples
+Compliant: home median CLS 0.04. Problematic: pdp median CLS 0.22.

package/dist/audit/catalog/categories/performance/rules/content-encoding.js

@@ -0,0 +1,35 @@
+import { a as harRuleDataSchema, d as sameHostResponses, f as tokens, i as harRule, o as header, t as COMPRESSED_ENCODINGS, u as resourceKind } from "../../../../../har.js";
+
+//#region src/audit/catalog/categories/performance/rules/content-encoding.ts
+const dataSchema = harRuleDataSchema;
+const MIN_BYTES = {
+	html: 1024,
+	js: 10 * 1024,
+	css: 10 * 1024
+};
+var content_encoding_default = harRule("same-host HTML (1 KiB+), JavaScript and CSS (10 KiB+) responses", (match) => {
+	const eligible = sameHostResponses(match).filter(({ entry }) => {
+		const min = MIN_BYTES[resourceKind(entry)];
+		const size = entry.response.content?.size;
+		return min !== void 0 && typeof size === "number" && size >= min;
+	});
+	const failures = eligible.flatMap((item) => {
+		const encoding = header(item.entry, "content-encoding");
+		if (tokens(encoding).some((token) => COMPRESSED_ENCODINGS.includes(token))) return [];
+		return [{
+			entry: item,
+			reasons: [`${resourceKind(item.entry).toUpperCase()} response of ${Math.round((item.entry.response.content?.size ?? 0) / 1024)} KiB has no br, gzip or zstd Content-Encoding.`],
+			headers: {
+				"content-type": header(item.entry, "content-type"),
+				"content-encoding": encoding
+			}
+		}];
+	});
+	return {
+		responses: eligible.length,
+		failures
+	};
+}, "are compressed with Brotli, gzip or zstd");
+
+//#endregion
+export { dataSchema, content_encoding_default as default };

package/dist/audit/catalog/categories/performance/rules/content-encoding.md

@@ -0,0 +1,20 @@
+---
+id: performance/content-encoding
+title: HTML, JavaScript and CSS Compression
+severity: high
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.network-har]
+---
+
+## Intent
+Checks that the storefront's own HTML (1 KiB or more), JavaScript and CSS (10 KiB or more) are sent compressed with Brotli, gzip or zstd, so pages download fewer bytes. Third-party files and smaller responses are not checked. Managed Runtime compresses by default, so a failure usually points to a CDN or proxy in front of it.
+## Inspect
+The rule script matches the final document response in `network-mobile-cold.har` (via `network-mobile-cold.json`) for each page. Only same-host responses with status 200 are checked; third-party responses are skipped. It reads the content type and decoded size (`response.content`) and `Content-Encoding`. If no page's document can be matched, the rule is not decided.
+## Evaluate
+Fail when HTML of at least 1 KiB, or JavaScript or CSS of at least 10 KiB (decoded size), has no `br`, `gzip` or `zstd` `Content-Encoding`. Responses without a known type or size are skipped. Pass otherwise.
+## Evidence
+The HAR entry of each failing response (up to 10), with its size, `Content-Type` and `Content-Encoding`.
+## Remediation
+Check that the public edge and every customer CDN in front of Managed Runtime preserve its compression; do not add application-level compression on Managed Runtime. Escalate an MRT-owned miss to Salesforce. For a non-MRT origin, enable Brotli or gzip. Re-run Playhouse to confirm.
+## Examples
+Compliant: a 180 KiB bundle with `Content-Encoding: br`. Problematic: a 40 KiB stylesheet with no `Content-Encoding`.

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

@@ -0,0 +1,18 @@
+import "../../../../../har.js";
+import { n as documentSizeDataSchema, r as documentSizeRule, t as count } from "../../../../../document-size.js";
+
+//#region src/audit/catalog/categories/performance/rules/dom-size.ts
+var dom_size_default = documentSizeRule({
+	label: "Element count",
+	budget: 1400,
+	value: (size) => size.elements,
+	format: count,
+	evidence: (size) => size.lighthouseArtifact ? {
+		artifact: size.lighthouseArtifact,
+		pointer: "/audits/dom-size-insight/details/items"
+	} : null,
+	decideFailures: false
+});
+
+//#endregion
+export { documentSizeDataSchema as dataSchema, dom_size_default as default };

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

@@ -0,0 +1,22 @@
+---
+id: performance/dom-size
+title: DOM Size (Number of Elements)
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.lighthouse, playhouse.scripts, source.code]
+---
+
+## Intent
+Checks that each page has 1,400 HTML elements or fewer after it loads, the limit Lighthouse used to flag. Every element adds to the HTML download and to the browser's style, layout and hydration work, so pages with large DOMs render and respond more slowly. When a page is over the limit, the report points to the components that render markup the shopper doesn't need yet.
+## Inspect
+The rule script reads the element count and DOM depth from Lighthouse's DOM size insight (`dom-size-insight`) in each page's mobile cold-cache Lighthouse result. If every page has 1,400 elements or fewer, it passes and this rule needs no analysis.
+
+Otherwise, use the `data` file and the Lighthouse result it names (`lighthouseArtifact`). The insight also names the deepest element and the element with the most children. Fetch the page (`curl -sL <url>`) to see which parts of the markup repeat most, then find the components in the project that render them.
+## Evaluate
+Report a `finding` for each page over 1,400 elements. Name the parts of the page that add the most elements and the components behind them. Typical causes: a mega menu that renders every category up front, every carousel slide or variant panel rendered while hidden, long lists without pagination, and deeply nested wrapper elements. Suggest rendering hidden or below-the-fold markup only when it's needed, as suggestions the customer can choose from.
+## Evidence
+The Lighthouse DOM size insight for each page over the limit (`playhouse`, with the element count as `value`), and `source` evidence for each component that renders the most markup.
+## Remediation
+Render menus, hidden panels and off-screen slides when they open, paginate long lists, and remove wrapper elements that add no styling. Re-run Playhouse to confirm each page has 1,400 elements or fewer.
+## Examples
+Compliant: a PLP with 720 elements. Problematic: a PLP with 1,620 elements because every product tile renders all of its color swatches.

package/dist/audit/catalog/categories/performance/rules/font-display.js

@@ -0,0 +1,248 @@
+import { l as normalizedUrl } from "../../../../../har.js";
+import { z } from "zod";
+
+//#region src/audit/catalog/categories/performance/rules/font-display.ts
+const FORM_FACTORS = ["mobile", "desktop"];
+const SAFE_RUN_ID = /^[a-z0-9][a-z0-9_-]*$/i;
+const TRACE_MAX_BYTES = 256 * 1024 * 1024;
+const acceptable = new Set(["swap", "optional"]);
+const summarySchema = z.object({ runs: z.array(z.object({
+	runId: z.string().optional(),
+	formFactor: z.string().optional(),
+	cacheState: z.string().optional(),
+	isMedian: z.boolean().optional()
+}).passthrough()).optional().default([]) }).passthrough();
+const harSchema = z.object({ log: z.object({ entries: z.array(z.object({
+	_resourceType: z.string().optional(),
+	request: z.object({ url: z.string() }).passthrough(),
+	response: z.object({ status: z.number() }).passthrough()
+}).passthrough()) }).passthrough() }).passthrough();
+const fontSchema = z.object({
+	url: z.string(),
+	display: z.string(),
+	status: z.enum(["pass", "fail"]),
+	event: z.number()
+}).strict();
+const unverifiedFontSchema = z.object({
+	url: z.string(),
+	entry: z.number()
+}).strict();
+const cellSchema = z.object({
+	cell: z.enum(["mobile-cold", "desktop-cold"]),
+	runId: z.string(),
+	status: z.enum([
+		"pass",
+		"fail",
+		"undecided"
+	]),
+	traceArtifact: z.string(),
+	harArtifact: z.string(),
+	fonts: z.array(fontSchema),
+	unverifiedFonts: z.array(unverifiedFontSchema)
+}).strict();
+const dataSchema = z.object({
+	pages: z.array(z.object({
+		page: z.string(),
+		cells: z.array(cellSchema)
+	}).strict()),
+	skipped: z.array(z.object({
+		page: z.string(),
+		cell: z.string(),
+		reason: z.string()
+	}).strict())
+}).strict();
+function object(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function traceFonts(trace) {
+	const events = object(trace)?.traceEvents;
+	if (!Array.isArray(events)) return void 0;
+	const fonts = /* @__PURE__ */ new Map();
+	for (const [event, raw] of events.entries()) {
+		const item = object(raw);
+		if (item?.name !== "BeginRemoteFontLoad") continue;
+		const args = object(item.args);
+		const url = args?.url;
+		const display = args?.display;
+		if (typeof url !== "string" || typeof display !== "string") continue;
+		const key = normalizedUrl(url) ?? url;
+		const policy = display.toLowerCase();
+		const candidate = {
+			url,
+			display: policy,
+			status: acceptable.has(policy) ? "pass" : "fail",
+			event
+		};
+		const known = fonts.get(key);
+		if (!known || known.status === "pass" && candidate.status === "fail") fonts.set(key, candidate);
+	}
+	return [...fonts.values()];
+}
+async function medianRun(playhouse, page, formFactor) {
+	const runs = ((await playhouse.readJson(page, "summary.json", summarySchema))?.runs ?? []).filter((run$1) => run$1.runId && SAFE_RUN_ID.test(run$1.runId) && run$1.formFactor === formFactor && run$1.cacheState === "cold");
+	return (runs.find((run$1) => run$1.isMedian) ?? runs[0])?.runId ?? `${formFactor}-cold-1`;
+}
+async function measureCell(playhouse, page, formFactor) {
+	const cell = `${formFactor}-cold`;
+	try {
+		const runId = await medianRun(playhouse, page, formFactor);
+		const traceArtifact = `runs/${runId}/trace.json`;
+		const harArtifact = `runs/${runId}/network.har`;
+		let traceText;
+		let har;
+		try {
+			[traceText, har] = await Promise.all([playhouse.readText(page, traceArtifact, TRACE_MAX_BYTES), playhouse.readJson(page, harArtifact, harSchema)]);
+		} catch {
+			return {
+				cell,
+				reason: `${traceArtifact} could not be read or parsed safely.`
+			};
+		}
+		if (traceText === void 0) return {
+			cell,
+			reason: `${traceArtifact} is missing.`
+		};
+		let trace;
+		try {
+			trace = JSON.parse(traceText);
+		} catch {
+			return {
+				cell,
+				reason: `${traceArtifact} could not be read or parsed safely.`
+			};
+		}
+		const tracePolicies = traceFonts(trace);
+		if (!tracePolicies) return {
+			cell,
+			reason: `${traceArtifact} has no traceEvents array.`
+		};
+		if (!har) return {
+			cell,
+			reason: `${harArtifact} is missing.`
+		};
+		const downloaded = /* @__PURE__ */ new Map();
+		for (const [entry, item] of har.log.entries.entries()) {
+			if (item._resourceType?.toLowerCase() !== "font" || item.response.status <= 0 || item.response.status >= 400) continue;
+			const key = normalizedUrl(item.request.url) ?? item.request.url;
+			if (!downloaded.has(key)) downloaded.set(key, {
+				url: item.request.url,
+				entry
+			});
+		}
+		const fonts = tracePolicies.filter((font) => downloaded.has(normalizedUrl(font.url) ?? font.url));
+		const traced = new Set(fonts.map((font) => normalizedUrl(font.url) ?? font.url));
+		const unverifiedFonts = [...downloaded].flatMap(([key, item]) => traced.has(key) ? [] : [item]);
+		return {
+			cell,
+			runId,
+			status: fonts.some((font) => font.status === "fail") ? "fail" : unverifiedFonts.length ? "undecided" : "pass",
+			traceArtifact,
+			harArtifact,
+			fonts,
+			unverifiedFonts
+		};
+	} catch {
+		return {
+			cell,
+			reason: `${cell} artifacts could not be read or parsed safely.`
+		};
+	}
+}
+function fileName(url) {
+	try {
+		return decodeURIComponent(new URL(url).pathname.split("/").at(-1) || url);
+	} catch {
+		return url;
+	}
+}
+function hostName(url) {
+	try {
+		return new URL(url).host;
+	} catch {
+		return url;
+	}
+}
+const run = async ({ pages, playhouse }) => {
+	const data = {
+		pages: [],
+		skipped: []
+	};
+	const failures = [];
+	const passEvidence = [];
+	let undecided = false;
+	const pageMeasurements = [];
+	for (const page of pages) pageMeasurements.push({
+		page,
+		measured: await Promise.all(FORM_FACTORS.map((formFactor) => measureCell(playhouse, page.label, formFactor)))
+	});
+	for (const { page, measured } of pageMeasurements) {
+		const cells = [];
+		for (const result of measured) {
+			if ("reason" in result) {
+				data.skipped.push({
+					page: page.label,
+					cell: result.cell,
+					reason: result.reason
+				});
+				undecided = true;
+				continue;
+			}
+			cells.push(result);
+			undecided ||= result.status === "undecided";
+			for (const font of result.fonts) {
+				const evidence = {
+					type: "playhouse",
+					page: page.label,
+					artifact: result.traceArtifact,
+					pointer: `/traceEvents/${font.event}/args/display`,
+					value: `${fileName(font.url)} from ${hostName(font.url)} uses font-display: ${font.display} in ${result.cell}.`
+				};
+				if (font.status === "fail") failures.push({
+					page: page.label,
+					cell: result,
+					font
+				});
+				else passEvidence.push(evidence);
+			}
+			if (!result.fonts.length) passEvidence.push({
+				type: "playhouse",
+				page: page.label,
+				artifact: result.harArtifact,
+				pointer: "/log/entries",
+				value: `${result.cell} downloaded no web fonts.`
+			});
+		}
+		data.pages.push({
+			page: page.label,
+			cells
+		});
+	}
+	if (failures.length) return {
+		data,
+		decision: {
+			status: "fail",
+			severity: "medium",
+			summary: failures.map(({ page, cell, font }) => `${page} ${cell.cell}: ${fileName(font.url)} from ${hostName(font.url)} uses font-display: ${font.display}.`).join(" "),
+			evidence: failures.slice(0, 10).map(({ page, cell, font }) => ({
+				type: "playhouse",
+				page,
+				artifact: cell.traceArtifact,
+				pointer: `/traceEvents/${font.event}/args/display`,
+				value: `${fileName(font.url)} from ${hostName(font.url)} uses font-display: ${font.display} in ${cell.cell}.`
+			}))
+		}
+	};
+	if (!data.pages.length || undecided || data.skipped.length) return { data };
+	return {
+		data,
+		decision: {
+			status: "pass",
+			summary: `Every measured web font uses font-display: swap or optional on ${data.pages.map((page) => page.page).join(", ")}.`,
+			evidence: passEvidence
+		}
+	};
+};
+var font_display_default = run;
+
+//#endregion
+export { dataSchema, font_display_default as default };

package/dist/audit/catalog/categories/performance/rules/font-display.md

@@ -0,0 +1,21 @@
+---
+id: performance/font-display
+title: Web Font Display Policy
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.summary, playhouse.trace, playhouse.network-har, source]
+---
+
+## Intent
+Checks that web fonts do not hide text while they download. A blocking `font-display` policy can leave shoppers looking at invisible text, while `swap` and `optional` allow fallback text to render immediately.
+## Inspect
+The rule script reads the median mobile and desktop cold-cache runs from `summary.json`. In each run's trace it finds `BeginRemoteFontLoad` events and reads the font URL and display policy that Chrome used. It compares those URLs with downloaded font responses in the same run's HAR. Chrome does not emit this trace event for every preloaded font, so a downloaded font with no matching event is left undecided for source inspection rather than treated as a pass. For those candidates, inspect the matching `@font-face` declaration in project or fetched stylesheet CSS.
+The layout-shift portion of the original rule specification is deferred until the audit captures a deterministic mapping between layout-shift events and the web font that caused them; this rule currently reports display policy only.
+## Evaluate
+Fail when Chrome reports `auto`, `block`, `fallback`, or any policy other than `swap` or `optional`. Pass only when every downloaded font in both measured cold-cache runs has a trace event and every event uses `swap` or `optional`. When a downloaded font has no matching event, the script leaves the rule undecided; source analysis fails a matching `@font-face` without `swap` or `optional`, passes it when the policy is present, and reports not verified when the declaration cannot be found. A missing trace or HAR also leaves the rule undecided.
+## Evidence
+For a deterministic failure, the trace event's font URL, display policy, form factor and run. For an undecided downloaded font, its HAR URL and the matching `@font-face` declaration when source analysis can find it.
+## Remediation
+Set `font-display: swap` for brand fonts that should replace fallback text as soon as they arrive, or `font-display: optional` when avoiding a late swap is more important than using the web font on the first visit. Add fallback metrics such as `size-adjust`, `ascent-override`, `descent-override` and `line-gap-override` when a font swap contributes to layout shift. Replace icon fonts with inline SVG or an SVG sprite so icons do not depend on a blocking font. Self-host third-party fonts when licensing permits; otherwise preload only critical faces and preconnect to the font origin. Apply the policy to every relevant `@font-face`, including preloaded faces, and re-run both mobile and desktop cold-cache captures.
+## Examples
+Compliant: `@font-face { font-family: Brand; src: url('/fonts/brand.woff2') format('woff2'); font-display: swap; }`. Problematic: a downloaded face whose trace reports `font-display: block`, or a preloaded face whose declaration omits `font-display`.

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

@@ -0,0 +1,15 @@
+import "../../../../../har.js";
+import { i as kib, n as documentSizeDataSchema, r as documentSizeRule } from "../../../../../document-size.js";
+
+//#region src/audit/catalog/categories/performance/rules/html-document-size.ts
+var html_document_size_default = documentSizeRule({
+	label: "HTML size",
+	budget: 350 * 1024,
+	value: (size) => size.htmlBytes,
+	format: kib,
+	evidence: () => null,
+	decideFailures: true
+});
+
+//#endregion
+export { documentSizeDataSchema as dataSchema, html_document_size_default as default };