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

package/README.md

@@ -137,8 +137,17 @@ Run these commands from your project directory:
 # Generate cartridge metadata for your site
 pnpm sfnext generate-cartridge
 
-# Deploy generated metadata to B2C Commerce (uses dw.json for all settings)
-pnpm sfnext deploy-cartridge
+# Select a site other than app.defaultSiteId for PDP/PLP route metadata
+pnpm sfnext generate-cartridge --site-id RefArch
+
+# Generate a site-specific cartridge (scaffolds identity files once; no base required)
+pnpm sfnext generate-cartridge --site-id RefArch --cartridge-name app_storefrontnext_refarch
+
+# Validate a custom cartridge
+pnpm sfnext validate-cartridge --cartridge-name app_storefrontnext_refarch
+
+# Deploy a named cartridge with the existing filter
+pnpm sfnext deploy-cartridge -c app_storefrontnext_refarch
 ```
 
 ## CLI Options
@@ -273,6 +282,8 @@ The cartridge commands are independent tools for working with B2C Commerce metad
 - Scans `src/` directory for `@Component`, `@PageType`, and `@Aspect` decorators
 - Generates JSON metadata files in `cartridge/cartridge/experience/` directory
 - Creates separate files for components, page types, and aspects
+- Canonical PDP/PLP route metadata uses the selected site's complete `app.url.seoRoutes` entry (default: `app.defaultSiteId`); `--site-id` overrides it. A `'*'` entry is used only when no site-specific entry exists. Without `seoRoutes`, the metadata route prefixes are `p` and `c`.
+- `--cartridge-name` writes to `cartridges/<name>` instead of `app_storefrontnext_base`. A new name scaffolds only `.project` and `<name>.properties` (no base cartridge, hooks, or sample assets). An existing target is left unchanged, so non-metadata files are preserved; generated components/pages/aspects are replaced. Put the named cartridge **before** the base entry in that site's cartridge path so the base still supplies hooks and shared behavior. Deploy with existing `-c`. Separate outputs must be regenerated explicitly.
 
 **Deploy Metadata**: `deploy-cartridge` uploads metadata directories to B2C Commerce
 

package/dist/assets.js

@@ -0,0 +1,25 @@
+import { t as version } from "./package.js";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/audit/assets.ts
+/** The storefront-next-dev version, not the host CLI's: under `b2c sfnext`, oclif's config version is b2c's. */
+const VERSION = version;
+function packageRoot(from) {
+	for (let dir = from;; dir = path.dirname(dir)) {
+		if (existsSync(path.join(dir, "package.json"))) return dir;
+		if (path.dirname(dir) === dir) throw new Error(`No package.json above ${from}`);
+	}
+}
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = packageRoot(here);
+/**
+* The directory holding the audit's runtime assets (catalog, instructions, UI). tsdown moves shared code into
+* chunks at the top of `dist`, so paths relative to a module break after bundling. This resolves to `src/audit`
+* when running from source (tests) and `dist/audit` when running the build.
+*/
+const AUDIT_ROOT = path.join(root, path.relative(root, here).split(path.sep)[0] === "src" ? "src" : "dist", "audit");
+
+//#endregion
+export { VERSION as n, AUDIT_ROOT as t };

package/dist/audit/catalog/categories/best-practices/CATEGORY.md

@@ -0,0 +1,21 @@
+# Best Practices
+
+## Purpose and boundaries
+
+Inspect storefront-next framework use, server loaders/actions, and production integrations. Follow data flow before judging a text match.
+
+## Investigation sequence
+
+Map routes and data boundaries, inspect every rule, and corroborate source conclusions with captured behavior.
+
+## Evidence and redaction
+
+Cite source lines and Playhouse diagnostics without secrets or personal data.
+
+## Severity and blind spots
+
+Opaque integrations without independent end-to-end evidence are `not-verified`.
+
+## Draft rules and migration gaps
+
+Application/data caching strategy, authenticated cache safety, observability, localization, resilient image handling, CSP integration, and framework-version-specific recommendations remain uncodified. Deployed public-resource caching is owned by `performance/cache-control`. Do not silently treat the remaining gaps as active rules; record relevant review as an ad hoc observation and coverage gap.

package/dist/audit/catalog/categories/best-practices/rules/commerce-api-client.md

@@ -0,0 +1,20 @@
+---
+id: best-practices/commerce-api-client
+title: Commerce API Calls Use the SDK Clients
+severity: high
+appliesTo: [home, plp, pdp]
+inputs: [source.code]
+---
+
+## Intent
+Checks that calls to the Commerce APIs (SCAPI and OCAPI) go through the Storefront Next SDK clients instead of hand-built `fetch` requests. The SDK clients handle authentication, token refresh, routing and request correlation, which hand-built calls tend to get wrong.
+## Inspect
+Trace raw fetches and SCAPI/OCAPI URLs through authentication, routing, token refresh, and correlation handling; exclude generated clients.
+## Evaluate
+Finding requires a hand-built commerce call that bypasses the supported client, not a URL text match alone.
+## Evidence
+Cite call site and the data/auth path it bypasses.
+## Remediation
+Route the operation through the supported request-scoped SDK client.
+## Examples
+Compliant: createApiClients call in a server loader. Problematic: direct fetch to a commerce endpoint. Ambiguous: URL in documentation.

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/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 };

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 };