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

package/dist/audit/catalog/categories/performance/rules/render-blocking-font-size.js

@@ -0,0 +1,201 @@
+import "../../../../../har.js";
+import { i as kib } from "../../../../../document-size.js";
+import { z } from "zod";
+
+//#region src/audit/catalog/categories/performance/rules/render-blocking-font-size.ts
+const BUDGET = 75 * 1024;
+const CELL = "mobile-cold";
+/** Fonts listed per failing page, in the summary and as evidence. */
+const MAX_FILES = 4;
+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 requestSchema = z.object({
+	url: z.string(),
+	resourceType: z.string().nullish(),
+	statusCode: z.number().nullish(),
+	rendererStartTime: z.number().nullish(),
+	resourceSize: z.number().nullish(),
+	isLinkPreload: z.boolean().nullish(),
+	entity: z.string().nullish()
+}).passthrough();
+const lhrSchema = z.object({ audits: z.object({
+	"network-requests": z.object({ details: z.object({
+		items: z.array(requestSchema).optional(),
+		debugData: z.object({ networkStartTimeTs: z.number().nullish() }).passthrough().optional()
+	}).passthrough().optional() }).passthrough().optional(),
+	metrics: z.object({ details: z.object({ items: z.array(z.record(z.string(), z.unknown())).optional() }).passthrough().optional() }).passthrough().optional()
+}).passthrough() }).passthrough();
+const fontSchema = z.object({
+	url: z.string(),
+	bytes: z.number(),
+	requestMs: z.number(),
+	preloaded: z.boolean(),
+	renderBlocking: z.boolean(),
+	thirdParty: z.boolean(),
+	entry: z.number()
+}).strict();
+const pageSchema = z.object({
+	page: z.string(),
+	url: z.string(),
+	lighthouseArtifact: z.string(),
+	lcpMs: z.number(),
+	loadMs: z.number().nullable(),
+	renderBlockingBytes: z.number(),
+	laterBytes: z.number(),
+	fonts: z.array(fontSchema)
+}).strict();
+const dataSchema = z.object({
+	cell: z.string(),
+	budget: z.number(),
+	pages: z.array(pageSchema),
+	skipped: z.array(z.object({
+		page: z.string(),
+		reason: z.string()
+	}).strict())
+}).strict();
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+/** The median mobile cold-cache run, so the fonts come from the same run as the page's reported metrics. */
+async function medianRun(playhouse, page) {
+	const runs = ((await playhouse.readJson(page, "summary.json", summarySchema))?.runs ?? []).filter((run) => run.runId && `${run.formFactor}-${run.cacheState}` === CELL);
+	return (runs.find((run) => run.isMedian) ?? runs[0])?.runId ?? `${CELL}-1`;
+}
+function host(url) {
+	try {
+		return new URL(url).host;
+	} catch {
+		return;
+	}
+}
+/** Every font one page downloaded in its median mobile cold-cache run, each URL once, marked render-blocking when preloaded or requested before both LCP and the load event. */
+async function measurePage(playhouse, page) {
+	const lighthouseArtifact = `runs/${await medianRun(playhouse, page)}/lhr.json`;
+	const lhr = await playhouse.readJson(page, lighthouseArtifact, lhrSchema);
+	if (!lhr) return { reason: `${lighthouseArtifact} is missing.` };
+	const network = lhr.audits["network-requests"]?.details;
+	const requests = network?.items;
+	const metrics = lhr.audits.metrics?.details?.items?.[0];
+	if (!requests) return { reason: "The Lighthouse result has no network-requests audit." };
+	const lcpMs = metrics?.observedLargestContentfulPaint;
+	if (!finite(lcpMs)) return { reason: "The Lighthouse result has no observed LCP." };
+	const networkStart = network.debugData?.networkStartTimeTs;
+	const navigationStart = metrics?.observedNavigationStartTs;
+	const offsetMs = finite(networkStart) && finite(navigationStart) ? (networkStart - navigationStart) / 1e3 : 0;
+	const loadMs = metrics?.observedLoad;
+	const cutoffMs = finite(loadMs) ? Math.min(lcpMs, loadMs) : lcpMs;
+	const document = requests.find((request) => request.resourceType === "Document");
+	const fonts = /* @__PURE__ */ new Map();
+	for (const [entry, request] of requests.entries()) {
+		if (request.resourceType !== "Font" || !finite(request.resourceSize) || request.resourceSize <= 0) continue;
+		if (finite(request.statusCode) && request.statusCode >= 400) continue;
+		if (!finite(request.rendererStartTime)) return { reason: `The font request ${request.url} has no start time.` };
+		const requestMs = Math.round(request.rendererStartTime + offsetMs);
+		const preloaded = request.isLinkPreload === true;
+		const known = fonts.get(request.url);
+		if (known) {
+			if (requestMs < known.requestMs) Object.assign(known, {
+				requestMs,
+				entry
+			});
+			known.preloaded ||= preloaded;
+			known.renderBlocking = known.preloaded || known.requestMs < cutoffMs;
+			continue;
+		}
+		const thirdParty = !document ? false : document.entity && request.entity ? request.entity !== document.entity : host(request.url) !== host(document.url);
+		fonts.set(request.url, {
+			url: request.url,
+			bytes: request.resourceSize,
+			requestMs,
+			preloaded,
+			renderBlocking: preloaded || requestMs < cutoffMs,
+			thirdParty,
+			entry
+		});
+	}
+	const list = [...fonts.values()];
+	const total = (items) => items.reduce((sum, font) => sum + font.bytes, 0);
+	return {
+		page,
+		url: document?.url ?? "",
+		lighthouseArtifact,
+		lcpMs: Math.round(lcpMs),
+		loadMs: finite(loadMs) ? Math.round(loadMs) : null,
+		renderBlockingBytes: total(list.filter((font) => font.renderBlocking)),
+		laterBytes: total(list.filter((font) => !font.renderBlocking)),
+		fonts: list
+	};
+}
+/** A size, marked "just over" when it would otherwise read the same as the budget it exceeds. */
+const shown = (bytes) => bytes > BUDGET && kib(bytes) === kib(BUDGET) ? `just over ${kib(BUDGET)}` : kib(bytes);
+function fileName(url) {
+	try {
+		return decodeURIComponent(new URL(url).pathname.split("/").at(-1) || url);
+	} catch {
+		return url;
+	}
+}
+const why = (font, lcpMs) => font.preloaded ? "preloaded" : `requested at ${font.requestMs} ms, before LCP at ${lcpMs} ms`;
+const blocking = (size) => size.fonts.filter((font) => font.renderBlocking).slice().sort((a, b) => b.bytes - a.bytes);
+const pageTotal = (size) => {
+	const count = blocking(size).length;
+	return count ? `${shown(size.renderBlockingBytes)} in ${count} file${count === 1 ? "" : "s"}` : "no render-blocking fonts";
+};
+/** "pdp (96 KiB: inter.woff2 48 KiB, playfair.woff2 48 KiB third-party)". */
+function breakdown(size) {
+	const fonts = blocking(size);
+	const files = fonts.slice(0, MAX_FILES).map((font) => `${fileName(font.url)} ${kib(font.bytes)}${font.thirdParty ? " third-party" : ""}`);
+	if (fonts.length > MAX_FILES) files.push(`+${fonts.length - MAX_FILES} more`);
+	return `${size.page} (${shown(size.renderBlockingBytes)}: ${files.join(", ")})`;
+}
+var render_blocking_font_size_default = (async ({ pages, playhouse }) => {
+	const data = {
+		cell: CELL,
+		budget: BUDGET,
+		pages: [],
+		skipped: []
+	};
+	for (const page of pages) {
+		const size = await measurePage(playhouse, page.label);
+		if ("reason" in size) data.skipped.push({
+			page: page.label,
+			reason: size.reason
+		});
+		else data.pages.push(size);
+	}
+	if (!data.pages.length) return { data };
+	const over = data.pages.filter((size) => size.renderBlockingBytes > BUDGET);
+	if (!over.length) return {
+		data,
+		decision: {
+			status: "pass",
+			summary: `Render-blocking fonts are within ${kib(BUDGET)} on every measured page (${data.pages.map((size) => `${size.page} ${pageTotal(size)}`).join(", ")}).`,
+			evidence: data.pages.map((size) => ({
+				type: "playhouse",
+				page: size.page,
+				artifact: size.lighthouseArtifact,
+				pointer: "/audits/network-requests/details/items",
+				value: `Render-blocking fonts: ${pageTotal(size)} (budget ${kib(BUDGET)})`
+			}))
+		}
+	};
+	return {
+		data,
+		decision: {
+			status: "fail",
+			summary: `Render-blocking fonts are over ${kib(BUDGET)} on ${over.map(breakdown).join("; ")}.`,
+			evidence: over.flatMap((size) => blocking(size).slice(0, MAX_FILES).map((font) => ({
+				type: "playhouse",
+				page: size.page,
+				artifact: size.lighthouseArtifact,
+				pointer: `/audits/network-requests/details/items/${font.entry}/resourceSize`,
+				value: `${fileName(font.url)} ${kib(font.bytes)}${font.thirdParty ? ", third-party" : ""}, ${why(font, size.lcpMs)}`
+			})))
+		}
+	};
+});
+
+//#endregion
+export { dataSchema, render_blocking_font_size_default as default };

package/dist/audit/catalog/categories/performance/rules/render-blocking-font-size.md

@@ -0,0 +1,20 @@
+---
+id: performance/render-blocking-font-size
+title: Render-Blocking Font Size
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.summary, playhouse.lighthouse]
+---
+
+## Intent
+Checks that the web fonts each page needs for its first render add up to 75 KiB or less. A font counts as render-blocking when it is preloaded, or requested before both the page's Largest Contentful Paint (LCP) and its load event: text that uses it can't appear in its final font until the file arrives, and the download competes with CSS and the LCP image for bandwidth on mobile. Fonts requested later, such as those a tag manager or a third-party widget adds after the page has loaded, are not counted.
+## Inspect
+The rule script reads each page's median mobile cold-cache run from `summary.json` and that run's Lighthouse result (`runs/<run>/lhr.json`). From the `network-requests` audit it takes every request Chrome classified as a font, counting each URL once at its decoded size, and compares the request's start time with the observed LCP and load event of the same run from the `metrics` audit, whichever came first (LCP alone when the load event is missing). First- and third-party fonts both count when they are render-blocking. A page whose Lighthouse result lacks these audits, an observed LCP or a font's start time is skipped; if no page can be measured, the rule is not decided.
+## Evaluate
+Pass when every measured page's render-blocking fonts total 75 KiB or less, including pages with no web fonts; fail otherwise.
+## Evidence
+For each failing page, the Lighthouse network request of its largest render-blocking fonts (up to 4 per page), with each font's size and why it counts: preloaded, or requested before LCP and the load event.
+## Remediation
+Start with the largest file. Subset fonts to the characters the storefront uses (for example Latin, with `unicode-range` for other scripts), serve WOFF2, and replace several static weights with one variable font. Preload only the one or two fonts used above the fold; let other weights and families load without a preload so they arrive after the first render. Re-run Playhouse to confirm.
+## Examples
+Compliant: one preloaded 22 KiB variable font. Problematic: four preloaded static weights of 30 KiB each (120 KiB).

package/dist/audit/catalog/categories/performance/rules/server-request-waterfall.md

@@ -0,0 +1,85 @@
+---
+id: performance/server-request-waterfall
+title: Chained Server-Side Data Requests
+severity: high
+appliesTo: [home, plp, pdp]
+inputs: [source.code, playhouse.summary]
+---
+## Intent
+Traces the network calls each page makes while it renders on the server, and shows which calls wait for another call to finish before they start. Every chained call adds a full round trip before the page can be sent, so the report suggests chains that could run in parallel, be combined or be streamed. Some chains are necessary, when a call needs the earlier result.
+## Inspect
+For each page in `prepared.json`, find the routes that match its URL (`src/root.tsx`, the `_app` layout and the page route) and trace the server-side network calls an SSR request makes: SCAPI/SLAS/OCAPI clients, Einstein, `fetch`, MRT data store reads, and calls made by Page Designer component loaders. For each call, record:
+
+- where it starts (file and line of the call, not of a wrapper);
+- which other calls it waits on: an `await`, a `.then` on another call's result, or a middleware that runs earlier;
+- whether it blocks the shell (awaited before the loader returns) or is returned as an un-awaited promise and streamed;
+- whether it is conditional (for example, only without a valid access token);
+- whether its data is critical: needed for LCP, above-the-fold content or SEO content (title, meta, structured data, the main product or product grid). Critical data should stay awaited.
+
+React Router semantics: root middlewares run in order, and only I/O before `next()` delays the loaders. All matched loaders start together after the middleware chain. Request-scoped GET dedupe in `lib/api-clients.server.ts` turns identical reads into one call. List a deduped call once.
+
+The calls Storefront Next makes by default are listed below to help you trace. Judge every call the same way, wherever it comes from.
+
+### Default Storefront Next calls (template 2026.9)
+
+- **Middleware (all pages).** `sitesConfigMiddleware` does one MRT data store read when `commerce.sitesFromDal` is on (the default). `auth` makes 0 SLAS calls with a valid access token, 1 (`POST /oauth2/token`, refresh) with an expired token, and 2 chained calls (`GET /oauth2/authorize` → `POST /oauth2/token`) for a public-client guest login. A failed refresh followed by a guest login is 3. Basket, shopper context, data store preferences, site URL config and Page Designer resolution do no I/O by default.
+- **Root loader.** No I/O.
+- **`_app` loader (streamed).** `getCategory(root, levels=1)` → `getCategories(children, levels=2)` (chained); `getComponent('header')` and `getComponent('mega-menu')` in parallel, each followed by its component loaders.
+- **Home.** Bare `/` redirects to `/{site}/{locale}/` after the full middleware chain. On the prefixed URL, `getPage('homepage')` is awaited and blocking, followed by its component loaders (streamed). `productSearch(cgid=root)` and `getCategory(root)` start in parallel and stream; `getCategory(root)` is deduped with `_app`.
+- **PLP.** `getCategory`, the critical `productSearch` (first 4 hits) and `getPages(plp)` start in parallel; the loader awaits the category, the critical search and the pages. The non-critical `productSearch` is chained after the critical search and streamed.
+- **PDP.** `getProduct` (with expansions; it already includes variations, sets, bundles and the primary category) is awaited and blocking. `getPages(pdp)` is chained after it and streamed. A product-recommendations component makes Einstein → `getProducts` (chained, streamed). Reviews, BNPL and product content are mocks with no I/O; default recommendation carousels fetch client-side.
+
+## Evaluate
+The customer decides which suggestions to apply.
+
+A chain is a call that waits on another data call; waiting only on middleware is the normal request pipeline. For every chained call and every awaited non-critical call, decide whether there is an opportunity:
+
+- `parallelize`: the call doesn't need the earlier result (for example, it only needs a route param), so it can start alongside it.
+- `scapi-hook`: the call fetches data that could come back with the earlier response, for example product custom attributes or inventory added to `getProduct` by a SCAPI `modifyGETResponse` hook, so one call replaces two.
+- `stream`: the data isn't critical, so the loader can return the promise un-awaited and let it stream after the shell. Never suggest this for critical data.
+
+Leave `opportunity` out when the chain is necessary (it needs the earlier result and the data is critical) and say why in `note`.
+
+- `finding`: at least one opportunity.
+- `pass`: every chain is streamed or necessary.
+- `not-verified`: call sites that can't be resolved (opaque wrappers, compiled extensions).
+
+TTFB from `summary.json` may corroborate the impact; never invent per-call timings.
+
+## Evidence
+Cite each call with an opportunity as `source` evidence (file and line), and optionally the page's TTFB as `playhouse` evidence (`summary.json`, `/cells/<n>/medianRun/ttfb`).
+
+Also add a `waterfall` field to the output file with one entry per captured page you traced. The dashboard draws it; it does not carry timings:
+
+```json
+"waterfall": { "pages": [{
+  "page": "pdp", "route": "src/routes/_app.product.$productId.tsx",
+  "summary": "Auth, then getProduct, then an inventory call that only needs the product id.",
+  "steps": [
+    { "id": "auth", "kind": "middleware", "label": "auth · SLAS guest login", "service": "slas", "source": { "file": "src/middlewares/auth.server.ts", "line": 965 }, "after": [], "blocking": true, "conditional": "only without a valid access token" },
+    { "id": "get-product", "kind": "api", "label": "shopperProducts.getProduct", "service": "scapi", "source": { "file": "src/routes/_app.product.$productId.tsx", "line": 172 }, "after": ["auth"], "blocking": true, "critical": true },
+    { "id": "get-inventory", "kind": "api", "label": "GET /inventory/{id}", "service": "other", "source": { "file": "src/routes/_app.product.$productId.tsx", "line": 196 }, "after": ["get-product"], "blocking": true, "critical": true, "opportunity": "parallelize", "note": "Only needs params.productId, so it can start alongside getProduct." },
+    { "id": "get-pages", "kind": "api", "label": "shopperExperience.getPages(pdp)", "service": "scapi", "source": { "file": "src/routes/_app.product.$productId.tsx", "line": 230 }, "after": ["get-product"], "blocking": false },
+    { "id": "render", "kind": "render", "label": "Shell render", "source": { "file": "src/entry.server.tsx", "line": 68 }, "after": ["get-inventory"], "blocking": true }
+  ]
+}] }
+```
+
+- One step per network call. When a component calls Einstein and then `getProducts`, that's two steps, the second with `after` the first.
+- `id`: lowercase letters, digits and hyphens, unique within the page.
+- `kind`: `middleware`, `loader`, `api` (a network call) or `render` (the shell flush; add one, waiting on the last blocking calls).
+- `service` (optional): `scapi`, `slas`, `ocapi`, `einstein`, `data-store` or `other`.
+- `after`: ids this step waits on, including the previous middleware with I/O. Empty means it starts with the request.
+- `blocking`: `false` for streamed (un-awaited) promises.
+- `critical` (optional): `true` for LCP, above-the-fold or SEO data; `false` for the rest. Set it on every call you suggest changing.
+- `opportunity` (optional): `parallelize`, `scapi-hook` or `stream`, as described under Evaluate. `stream` requires `blocking: true` and `critical: false`; `parallelize` and `scapi-hook` require a non-empty `after`.
+- `conditional` and `note` (optional): short plain text. In `note`, explain the opportunity concretely, or why a chain is necessary.
+
+The customer reads `summary` and `note`. Describe what each call does and what it waits on, not where it came from: don't compare calls to the template or label them as added or customized. Describe opportunities as options, not mistakes.
+- At most 60 steps per page. Use project-relative file paths. Leave out middlewares and loaders with no I/O.
+
+## Remediation
+These are suggestions for the customer to weigh, not required fixes. Start independent calls before the first `await` (or use `Promise.all`). Return extra data with the earlier response through a SCAPI hook instead of a second call. Return non-critical data as un-awaited promises so it streams, but keep awaiting critical data (LCP, above-the-fold and SEO content) so it's in the first HTML.
+
+## Examples
+Compliant: PDP awaits auth, then `getProduct`, with `getPages` streamed. Also compliant: a PLP promotions call that needs the category's promotion ids and renders the above-the-fold banner, so it stays chained and awaited. Problematic: a PDP loader does `await getProduct`, then `await getInventory(params.productId)` (could run in parallel), then `await getReviews(params.productId)` (below the fold, could stream). Ambiguous: a chain inside a vendor extension whose source isn't in the project.

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

@@ -0,0 +1,13 @@
+import "../../../../../measured-run.js";
+import { n as metricBudget, r as milliseconds, t as dataSchema } from "../../../../../metric-budget.js";
+
+//#region src/audit/catalog/categories/performance/rules/tbt-budget.ts
+var tbt_budget_default = metricBudget({
+	metric: "tbt",
+	label: "TBT",
+	threshold: 200,
+	format: milliseconds
+});
+
+//#endregion
+export { dataSchema, tbt_budget_default as default };

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

@@ -0,0 +1,20 @@
+---
+id: performance/tbt-budget
+title: Total Blocking Time (TBT)
+severity: high
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.summary]
+---
+
+## Intent
+Checks that each page's median Total Blocking Time, measured by Lighthouse on mobile with a cold cache, is 200 ms or less, Lighthouse's "good" threshold. TBT adds up how long JavaScript blocks the main thread while the page loads, which delays the page's response to taps and clicks.
+## Inspect
+The rule script reads each page's `summary.json` and takes the mobile cold-cache cell's `medianRun.tbt`. 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.tbt`.
+## Evaluate
+Pass when every measured page's median TBT is at or under 200 ms; 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/tbt` (or `/runs/<j>/row/tbt` when runs were left out), with the measured value and how many runs were not measured.
+## Remediation
+Use `opportunities.json` and `summary-tbt.json` for the failing page to find the long tasks and the scripts behind them. Defer or remove non-critical third-party scripts, split large bundles, and move hydration-heavy work off the initial load. Re-run the same Playhouse capture to confirm the mobile cold-cache median is at or under 200 ms.
+## Examples
+Compliant: home median TBT 120 ms. Problematic: pdp median TBT 650 ms.

package/dist/audit/catalog/categories/performance/rules/third-party-fonts.js

@@ -0,0 +1,265 @@
+import "../../../../../har.js";
+import { i as kib } from "../../../../../document-size.js";
+import { z } from "zod";
+
+//#region src/audit/catalog/categories/performance/rules/third-party-fonts.ts
+const CELL = "mobile-cold";
+/** Requests listed per failing page, in the summary and as evidence. */
+const MAX_ITEMS = 4;
+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 requestSchema = z.object({
+	url: z.string(),
+	resourceType: z.string().nullish(),
+	statusCode: z.number().nullish(),
+	rendererStartTime: z.number().nullish(),
+	resourceSize: z.number().nullish(),
+	isLinkPreload: z.boolean().nullish(),
+	entity: z.string().nullish()
+}).passthrough();
+const lhrSchema = z.object({ audits: z.object({
+	"network-requests": z.object({ details: z.object({
+		items: z.array(requestSchema).optional(),
+		debugData: z.object({ networkStartTimeTs: z.number().nullish() }).passthrough().optional()
+	}).passthrough().optional() }).passthrough().optional(),
+	metrics: z.object({ details: z.object({ items: z.array(z.record(z.string(), z.unknown())).optional() }).passthrough().optional() }).passthrough().optional()
+}).passthrough() }).passthrough();
+const harSchema = z.object({ log: z.object({ entries: z.array(z.object({
+	request: z.object({ url: z.string() }).passthrough(),
+	_initiator: z.unknown().optional()
+}).passthrough()) }).passthrough() }).passthrough();
+const itemSchema = z.object({
+	kind: z.enum(["font", "stylesheet"]),
+	url: z.string(),
+	host: z.string(),
+	bytes: z.number(),
+	requestMs: z.number(),
+	preloaded: z.boolean(),
+	renderBlocking: z.boolean(),
+	stylesheet: z.string().nullable(),
+	entry: z.number()
+}).strict();
+const pageSchema = z.object({
+	page: z.string(),
+	url: z.string(),
+	lighthouseArtifact: z.string(),
+	harArtifact: z.string().nullable(),
+	lcpMs: z.number(),
+	loadMs: z.number().nullable(),
+	firstPartyFonts: z.number(),
+	items: z.array(itemSchema)
+}).strict();
+const dataSchema = z.object({
+	cell: z.string(),
+	pages: z.array(pageSchema),
+	skipped: z.array(z.object({
+		page: z.string(),
+		reason: z.string()
+	}).strict())
+}).strict();
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+/** The median mobile cold-cache run, so the requests come from the same run as the page's reported metrics. */
+async function medianRun(playhouse, page) {
+	const runs = ((await playhouse.readJson(page, "summary.json", summarySchema))?.runs ?? []).filter((run) => run.runId && `${run.formFactor}-${run.cacheState}` === CELL);
+	return (runs.find((run) => run.isMedian) ?? runs[0])?.runId ?? `${CELL}-1`;
+}
+function host(url) {
+	try {
+		return new URL(url).host;
+	} catch {
+		return;
+	}
+}
+/** Third-party fonts and font stylesheets one page requested in its median mobile cold-cache run, each URL once. */
+async function measurePage(playhouse, page) {
+	const run = await medianRun(playhouse, page);
+	const lighthouseArtifact = `runs/${run}/lhr.json`;
+	const lhr = await playhouse.readJson(page, lighthouseArtifact, lhrSchema);
+	if (!lhr) return { reason: `${lighthouseArtifact} is missing.` };
+	const network = lhr.audits["network-requests"]?.details;
+	const requests = network?.items;
+	const metrics = lhr.audits.metrics?.details?.items?.[0];
+	if (!requests) return { reason: "The Lighthouse result has no network-requests audit." };
+	const lcpMs = metrics?.observedLargestContentfulPaint;
+	if (!finite(lcpMs)) return { reason: "The Lighthouse result has no observed LCP." };
+	const document = requests.find((request) => request.resourceType === "Document");
+	if (!document) return { reason: "The Lighthouse result has no document request to tell first- from third-party." };
+	const networkStart = network.debugData?.networkStartTimeTs;
+	const navigationStart = metrics?.observedNavigationStartTs;
+	const offsetMs = finite(networkStart) && finite(navigationStart) ? (networkStart - navigationStart) / 1e3 : 0;
+	const loadMs = metrics?.observedLoad;
+	const cutoffMs = finite(loadMs) ? Math.min(lcpMs, loadMs) : lcpMs;
+	const harArtifact = `runs/${run}/network.har`;
+	const har = await playhouse.readJson(page, harArtifact, harSchema);
+	const initiators = /* @__PURE__ */ new Map();
+	for (const entry of har?.log.entries ?? []) if (typeof entry._initiator === "string" && !initiators.has(entry.request.url)) initiators.set(entry.request.url, entry._initiator);
+	const stylesheets = new Set(requests.filter((request) => request.resourceType === "Stylesheet").map((request) => request.url));
+	const stylesheetOf = (url) => {
+		const initiator = initiators.get(url);
+		return initiator && stylesheets.has(initiator) ? initiator : null;
+	};
+	const thirdParty = (request) => document.entity && request.entity ? request.entity !== document.entity : host(request.url) !== host(document.url);
+	const found = /* @__PURE__ */ new Map();
+	let firstPartyFonts = 0;
+	const ok = (request) => !(finite(request.statusCode) && request.statusCode >= 400);
+	for (const [entry, request] of requests.entries()) {
+		if (request.resourceType !== "Font" || !ok(request)) continue;
+		if (!thirdParty(request)) {
+			firstPartyFonts++;
+			continue;
+		}
+		if (!finite(request.rendererStartTime)) return { reason: `The font request ${request.url} has no start time.` };
+		const requestMs = Math.round(request.rendererStartTime + offsetMs);
+		const preloaded = request.isLinkPreload === true;
+		const known = found.get(request.url);
+		if (known) {
+			if (requestMs < known.requestMs) Object.assign(known, {
+				requestMs,
+				entry
+			});
+			known.preloaded ||= preloaded;
+			known.renderBlocking = known.preloaded || known.requestMs < cutoffMs;
+			continue;
+		}
+		found.set(request.url, {
+			kind: "font",
+			url: request.url,
+			host: host(request.url) ?? request.url,
+			bytes: finite(request.resourceSize) ? request.resourceSize : 0,
+			requestMs,
+			preloaded,
+			renderBlocking: preloaded || requestMs < cutoffMs,
+			stylesheet: stylesheetOf(request.url),
+			entry
+		});
+	}
+	const fontList = [...found.values()];
+	const fontSources = new Set(fontList.flatMap((font) => font.stylesheet ?? []));
+	const fontEntities = new Set(fontList.flatMap((font) => requests[font.entry]?.entity ?? []));
+	for (const [entry, request] of requests.entries()) {
+		if (request.resourceType !== "Stylesheet" || !ok(request) || !thirdParty(request) || found.has(request.url)) continue;
+		if (!(fontSources.has(request.url) || !har && request.entity && fontEntities.has(request.entity))) continue;
+		if (!finite(request.rendererStartTime)) continue;
+		const requestMs = Math.round(request.rendererStartTime + offsetMs);
+		const preloaded = request.isLinkPreload === true;
+		found.set(request.url, {
+			kind: "stylesheet",
+			url: request.url,
+			host: host(request.url) ?? request.url,
+			bytes: finite(request.resourceSize) ? request.resourceSize : 0,
+			requestMs,
+			preloaded,
+			renderBlocking: preloaded || requestMs < cutoffMs,
+			stylesheet: stylesheetOf(request.url),
+			entry
+		});
+	}
+	return {
+		page,
+		url: document.url,
+		lighthouseArtifact,
+		harArtifact: har ? harArtifact : null,
+		lcpMs: Math.round(lcpMs),
+		loadMs: finite(loadMs) ? Math.round(loadMs) : null,
+		firstPartyFonts,
+		items: [...found.values()].sort((a, b) => a.requestMs - b.requestMs)
+	};
+}
+function fileName(url) {
+	try {
+		return decodeURIComponent(new URL(url).pathname.split("/").at(-1) || url);
+	} catch {
+		return url;
+	}
+}
+/** "fonts.googleapis.com/css2?family=Inter" for a stylesheet, "inter-latin.woff2 48 KiB" for a font. */
+function label(item) {
+	if (item.kind === "font") return item.bytes > 0 ? `${fileName(item.url)} ${kib(item.bytes)}` : fileName(item.url);
+	try {
+		const url = new URL(item.url);
+		return `${url.host}${url.pathname}${url.search.split("&")[0]}`;
+	} catch {
+		return item.url;
+	}
+}
+/** A stylesheet by file name on the page's own host ("app.css"), by host and path elsewhere ("fonts.googleapis.com/css2"). */
+function sheetName(url, size) {
+	try {
+		const parsed = new URL(url);
+		return parsed.host === host(size.url) ? fileName(url) : `${parsed.host}${parsed.pathname}`;
+	} catch {
+		return url;
+	}
+}
+/** "imported by app.css" for a stylesheet, "loaded by fonts.googleapis.com/css2" for a font; empty when the HAR doesn't say. */
+function source(item, size) {
+	if (!item.stylesheet) return "";
+	return `${item.kind === "stylesheet" ? "imported by" : "loaded by"} ${sheetName(item.stylesheet, size)}`;
+}
+function why(item, size) {
+	const from = source(item, size);
+	return `${item.preloaded ? "preloaded" : `requested at ${item.requestMs} ms, before LCP at ${size.lcpMs} ms`}${from ? `, ${from}` : ""}`;
+}
+const blocking = (size) => size.items.filter((item) => item.renderBlocking);
+/** "home (fonts.googleapis.com/css2?family=Inter imported by app.css; inter-latin.woff2 48 KiB from fonts.gstatic.com)". */
+function breakdown(size) {
+	const items = blocking(size);
+	const shown = items.slice(0, MAX_ITEMS).map((item) => item.kind === "font" ? `${label(item)} from ${item.host}` : [label(item), source(item, size)].filter(Boolean).join(" "));
+	if (items.length > MAX_ITEMS) shown.push(`+${items.length - MAX_ITEMS} more`);
+	return `${size.page} (${shown.join("; ")})`;
+}
+function passDetail(size) {
+	const later = size.items.filter((item) => item.kind === "font").length;
+	const own = `${size.firstPartyFonts} first-party font${size.firstPartyFonts === 1 ? "" : "s"}`;
+	return `${size.page} ${own}${later ? `, ${later} third-party after LCP or load` : ""}`;
+}
+var third_party_fonts_default = (async ({ pages, playhouse }) => {
+	const data = {
+		cell: CELL,
+		pages: [],
+		skipped: []
+	};
+	const measured = await Promise.all(pages.map((page) => measurePage(playhouse, page.label)));
+	for (const [index, size] of measured.entries()) if ("reason" in size) data.skipped.push({
+		page: pages[index].label,
+		reason: size.reason
+	});
+	else data.pages.push(size);
+	if (!data.pages.length) return { data };
+	const failing = data.pages.filter((size) => blocking(size).length);
+	if (!failing.length) return {
+		data,
+		decision: {
+			status: "pass",
+			summary: `No measured page loads fonts from another origin before LCP (${data.pages.map(passDetail).join(", ")}).`,
+			evidence: data.pages.map((size) => ({
+				type: "playhouse",
+				page: size.page,
+				artifact: size.lighthouseArtifact,
+				pointer: "/audits/network-requests/details/items",
+				value: `Third-party fonts before LCP: none (${passDetail(size)})`
+			}))
+		}
+	};
+	return {
+		data,
+		decision: {
+			status: "fail",
+			summary: `Fonts load from another origin before LCP on ${failing.map(breakdown).join("; ")}.`,
+			evidence: failing.flatMap((size) => blocking(size).slice(0, MAX_ITEMS).map((item) => ({
+				type: "playhouse",
+				page: size.page,
+				artifact: size.lighthouseArtifact,
+				pointer: `/audits/network-requests/details/items/${item.entry}/url`,
+				value: `${item.kind === "font" ? "Font" : "Font stylesheet"} ${label(item)} from ${item.host}, ${why(item, size)}`
+			})))
+		}
+	};
+});
+
+//#endregion
+export { dataSchema, third_party_fonts_default as default };

package/dist/audit/catalog/categories/performance/rules/third-party-fonts.md

@@ -0,0 +1,20 @@
+---
+id: performance/third-party-fonts
+title: Third-Party Fonts
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.summary, playhouse.lighthouse, playhouse.network-har]
+---
+
+## Intent
+Checks that the fonts a page needs for its first render are served from the storefront's own origin. A font from a font service such as Google Fonts or Adobe Fonts usually arrives through a stylesheet from that service, often pulled in with a CSS `@import`: the browser has to fetch the page's CSS, then the service's stylesheet, then the font, each from a new origin with its own DNS and TLS setup. Text that uses the font can't render in its final font until the whole chain finishes, and the page shifts when it swaps in.
+## Inspect
+The rule script reads each page's median mobile cold-cache run from `summary.json`, that run's Lighthouse result (`runs/<run>/lhr.json`) and its HAR (`runs/<run>/network.har`). From the `network-requests` audit it takes every font, and every stylesheet that loads one, from another site than the document (Lighthouse's entity, else the host). It counts one when it is preloaded, or requested before both the run's observed LCP and its load event, the same cutoff as `performance/render-blocking-font-size`. The HAR's initiators name the stylesheet that requested each font, and whether that stylesheet was itself imported by another one. Third-party fonts requested later, such as those a tag manager or a widget adds, are reported but not counted. A page whose Lighthouse result lacks these audits, an observed LCP or a document request is skipped; if no page can be measured, the rule is not decided.
+## Evaluate
+Pass when no measured page requests a third-party font or font stylesheet before LCP and the load event, including pages with no web fonts; fail otherwise.
+## Evidence
+For each failing page, the Lighthouse network request of each third-party font and font stylesheet in its first render (up to 4 per page), with its origin, when it was requested or that it was preloaded, and the stylesheet that requested or imported it.
+## Remediation
+Self-host the fonts when their license allows it (Google Fonts are open-source licensed; check commercial fonts with their vendor). Download WOFF2 files subset to the characters the storefront uses (for example Latin, with `unicode-range` for other scripts), preferably one variable font instead of several static weights. In a Storefront Next project, put the files in `public/fonts`, declare them with `@font-face` and `font-display: swap` in the theme CSS, remove the `@import` or `<link>` to the font service and its preconnect, and preload only the face used above the fold from the root route's `links`. If the license only allows the vendor's hosted service, load its stylesheet with a `<link>` in the document instead of an `@import`, and preconnect to the font origin. Re-run Playhouse to confirm the fonts now come from the storefront's origin.
+## Examples
+Compliant: Inter self-hosted as one 35 KiB subset variable WOFF2, preloaded from the root route. Problematic: `@import url('https://fonts.googleapis.com/css2?family=Inter…')` in the theme CSS, which loads the font from `fonts.gstatic.com` after two stylesheet round trips.

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

@@ -0,0 +1,17 @@
+import "../../../../../measured-run.js";
+import { n as metricBudget, r as milliseconds, t as dataSchema } from "../../../../../metric-budget.js";
+
+//#region src/audit/catalog/categories/performance/rules/ttfb-budget.ts
+var ttfb_budget_default = metricBudget({
+	metric: "ttfb",
+	label: "TTFB",
+	threshold: 800,
+	format: milliseconds,
+	severityForFailure: (value) => value > 1800 ? "high" : "medium",
+	validValue: (value) => value > 0,
+	includeSpread: true,
+	measurementLabel: "representative-run"
+});
+
+//#endregion
+export { dataSchema, ttfb_budget_default as default };