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

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

@@ -0,0 +1,227 @@
+import { a as kib, i as isImage, n as bytesDuring, o as readImageRun, r as fileName, s as withoutQuery, t as MIN_SAVINGS_BYTES } from "../../../../../images.js";
+import { z } from "zod";
+
+//#region src/audit/catalog/categories/performance/rules/lcp-image-priority.ts
+/** Delays shorter than this aren't worth a suggestion. */
+const MIN_DELAY_MS = 100;
+const LCP_GOOD_MS = 2500;
+const HIGH = new Set(["High", "VeryHigh"]);
+const issueSchema = z.object({
+	check: z.enum([
+		"not-in-html",
+		"lazy",
+		"low-priority",
+		"preload-mismatch",
+		"competing-images",
+		"bandwidth",
+		"render-blocking"
+	]),
+	detail: z.string(),
+	artifact: z.string(),
+	pointer: z.string()
+}).strict();
+const dataSchema = z.object({
+	cell: z.string(),
+	pages: z.array(z.object({
+		page: z.string(),
+		lcpMs: z.number().nullable(),
+		image: z.object({
+			url: z.string(),
+			entry: z.number(),
+			bytes: z.number(),
+			startMs: z.number(),
+			loadMs: z.number(),
+			initialPriority: z.string().nullable(),
+			priority: z.string().nullable(),
+			initiator: z.string().nullable(),
+			preloaded: z.boolean(),
+			concurrentImageBytes: z.number(),
+			concurrentScriptBytes: z.number(),
+			imageDelayMs: z.number()
+		}).strict().nullable(),
+		issues: z.array(issueSchema)
+	}).strict()),
+	skipped: z.array(z.object({
+		page: z.string(),
+		reason: z.string()
+	}).strict())
+}).strict();
+/** The `{value}` of one of Lighthouse's LCP discovery checks, or undefined when it wasn't reported. */
+function discovery(run$1, check) {
+	for (const item of run$1.lhr.audits["lcp-discovery-insight"]?.details?.items ?? []) {
+		const value = item.items?.[check]?.value;
+		if (typeof value === "boolean") return value;
+	}
+}
+function checkPage(run$1) {
+	if (!run$1.lcpUrl) return {
+		page: run$1.page,
+		lcpMs: run$1.lcpMs,
+		image: null,
+		issues: []
+	};
+	const index = run$1.entries.findIndex((entry) => entry.request.url === run$1.lcpUrl);
+	const lcp = run$1.entries[index];
+	if (!lcp || lcp._requestTime === void 0) return { reason: "The LCP image request was not found in the median run HAR." };
+	const har = (entry, path$1 = "") => ({
+		artifact: run$1.harArtifact,
+		pointer: `/log/entries/${entry}${path$1}`
+	});
+	const lighthouse = (id) => ({
+		artifact: run$1.lighthouseArtifact,
+		pointer: `/audits/${id}`
+	});
+	const issues = [];
+	const name = fileName(lcp.request.url);
+	if (discovery(run$1, "requestDiscoverable") === false || lcp._initiator_type === "script") issues.push({
+		check: "not-in-html",
+		detail: `The LCP image ${name} is requested by JavaScript instead of being in the HTML, so the browser finds it late.`,
+		...lighthouse("lcp-discovery-insight")
+	});
+	if (discovery(run$1, "eagerlyLoaded") === false) issues.push({
+		check: "lazy",
+		detail: `The LCP image ${name} uses loading="lazy", which waits for layout before downloading it.`,
+		...lighthouse("lcp-discovery-insight")
+	});
+	const initial = lcp._initialPriority ?? null;
+	if (initial && !HIGH.has(initial)) issues.push({
+		check: "low-priority",
+		detail: `The LCP image ${name} starts at ${initial} priority${lcp._priority && lcp._priority !== initial ? ` and is raised to ${lcp._priority} only after layout` : ""}; it has no fetchpriority="high".`,
+		...har(index)
+	});
+	const path = withoutQuery(lcp.request.url);
+	const mismatch = run$1.entries.findIndex((entry) => entry.request._isLinkPreload && entry.request.url !== lcp.request.url && withoutQuery(entry.request.url) === path);
+	if (mismatch >= 0) issues.push({
+		check: "preload-mismatch",
+		detail: `The page preloads ${name} at a different size from the one shown, so it downloads twice (${run$1.entries[mismatch].request.url}).`,
+		...har(mismatch)
+	});
+	const competing = run$1.entries.flatMap((entry, at) => entry !== lcp && isImage(entry) && HIGH.has(entry._priority ?? "") && (entry._requestTime ?? Infinity) <= (lcp._requestTime ?? -Infinity) && (entry.response.bodySize ?? 0) >= MIN_SAVINGS_BYTES ? [at] : []);
+	if (competing.length) issues.push({
+		check: "competing-images",
+		detail: `${competing.length} other image${competing.length === 1 ? "" : "s"} at High priority start before the LCP image: ${competing.slice(0, 3).map((at) => `${fileName(run$1.entries[at].request.url)} (${kib(run$1.entries[at].response.bodySize ?? 0)})`).join(", ")}.`,
+		...har(competing[0])
+	});
+	const start = lcp._requestTime;
+	const end = start + lcp.time / 1e3;
+	const during = run$1.entries.map((entry, at) => ({
+		entry,
+		at,
+		bytes: entry === lcp ? 0 : bytesDuring(entry, start, end)
+	}));
+	const total = during.reduce((sum, item) => sum + item.bytes, lcp.response.bodySize ?? 0);
+	const images = during.filter((item) => item.bytes > 0 && isImage(item.entry)).slice().sort((a, b) => b.bytes - a.bytes);
+	const imageBytes = images.reduce((sum, item) => sum + item.bytes, 0);
+	const scriptBytes = during.filter((item) => item.entry._resourceType === "script").reduce((sum, item) => sum + item.bytes, 0);
+	const imageDelayMs = total > 0 ? Math.round(lcp.time * imageBytes / total) : 0;
+	if (imageDelayMs >= MIN_DELAY_MS) issues.push({
+		check: "bandwidth",
+		detail: `Other images download ${kib(imageBytes)} while the ${kib(lcp.response.bodySize ?? 0)} LCP image loads, delaying it by about ${imageDelayMs} ms; the largest is ${fileName(images[0].entry.request.url)} (${kib(images[0].bytes)} during the LCP download).`,
+		...har(images[0].at)
+	});
+	const blocking = run$1.lhr.audits["render-blocking-insight"];
+	const blockingMs = blocking?.metricSavings?.LCP ?? 0;
+	if (blockingMs >= MIN_DELAY_MS) {
+		const urls = (blocking?.details?.items ?? []).map((item) => fileName(item.url));
+		issues.push({
+			check: "render-blocking",
+			detail: `${urls.length} render-blocking request${urls.length === 1 ? "" : "s"} (${urls.slice(0, 3).join(", ")}) delay the LCP by about ${Math.round(blockingMs)} ms.`,
+			...lighthouse("render-blocking-insight")
+		});
+	}
+	return {
+		page: run$1.page,
+		lcpMs: run$1.lcpMs,
+		image: {
+			url: lcp.request.url,
+			entry: index,
+			bytes: lcp.response.bodySize ?? 0,
+			startMs: run$1.startMs(lcp),
+			loadMs: Math.round(lcp.time),
+			initialPriority: initial,
+			priority: lcp._priority ?? null,
+			initiator: lcp._initiator_type ?? null,
+			preloaded: Boolean(lcp.request._isLinkPreload),
+			concurrentImageBytes: imageBytes,
+			concurrentScriptBytes: scriptBytes,
+			imageDelayMs
+		},
+		issues
+	};
+}
+const run = async ({ pages, playhouse }) => {
+	const data = {
+		cell: "mobile-cold",
+		pages: [],
+		skipped: []
+	};
+	const harArtifacts = /* @__PURE__ */ new Map();
+	for (const page of pages) {
+		const imageRun = await readImageRun(playhouse, page.label);
+		if ("reason" in imageRun) {
+			data.skipped.push({
+				page: page.label,
+				reason: imageRun.reason
+			});
+			continue;
+		}
+		const result = checkPage(imageRun);
+		if ("reason" in result) {
+			data.skipped.push({
+				page: page.label,
+				reason: result.reason
+			});
+			continue;
+		}
+		data.pages.push(result);
+		harArtifacts.set(page.label, imageRun.harArtifact);
+	}
+	if (!data.pages.length) return { data };
+	const withImage = data.pages.filter((item) => item.image);
+	const failing = withImage.filter((item) => item.issues.length);
+	const text = data.pages.filter((item) => !item.image).map((item) => item.page);
+	const textNote = text.length ? ` The LCP element is text on ${text.join(", ")}.` : "";
+	if (!failing.length) return {
+		data,
+		decision: {
+			status: "pass",
+			summary: withImage.length ? `The LCP image on ${withImage.map((item) => item.page).join(", ")} is in the HTML, starts at High priority, isn't lazy-loaded and has no image competing for bandwidth.${textNote}` : `The LCP element is text on every measured page (${text.join(", ")}), so there is no LCP image to prioritize.`,
+			evidence: withImage.length ? withImage.flatMap((item) => {
+				const image = item.image;
+				const artifact = harArtifacts.get(item.page);
+				if (!image || !artifact) return [];
+				return [{
+					type: "playhouse",
+					page: item.page,
+					artifact,
+					pointer: `/log/entries/${image.entry}`,
+					value: `${fileName(image.url)}: ${image.initialPriority ?? "unknown"} priority, ${image.preloaded ? "preloaded" : `found by the ${image.initiator ?? "parser"}`}, ${kib(image.bytes)} in ${image.loadMs} ms`
+				}];
+			}) : data.pages.map((item) => ({
+				type: "playhouse",
+				page: item.page,
+				artifact: "summary-lcp.json",
+				value: "LCP element is text"
+			}))
+		}
+	};
+	return {
+		data,
+		decision: {
+			status: "fail",
+			severity: failing.some((item) => (item.lcpMs ?? 0) > LCP_GOOD_MS) ? "high" : "medium",
+			summary: failing.map((item) => `${item.page} (LCP ${item.lcpMs === null ? "unknown" : `${Math.round(item.lcpMs)} ms`}): ${item.issues.map((issue) => issue.detail).join(" ")}`).join(" ") + textNote,
+			evidence: failing.flatMap((item) => item.issues.map((issue) => ({
+				type: "playhouse",
+				page: item.page,
+				artifact: issue.artifact,
+				pointer: issue.pointer,
+				value: issue.detail
+			})))
+		}
+	};
+};
+var lcp_image_priority_default = run;
+
+//#endregion
+export { dataSchema, lcp_image_priority_default as default };

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

@@ -0,0 +1,27 @@
+---
+id: performance/lcp-image-priority
+title: LCP Image Priority
+severity: high
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.summary-lcp, playhouse.lighthouse, playhouse.network-har]
+---
+
+## Intent
+Checks that when the largest element on screen is an image, the browser finds it in the HTML and downloads it first. The LCP image should be in the server-rendered HTML (or preloaded), start at High priority with `fetchpriority="high"`, not be lazy-loaded, be downloaded once at the size shown, and not share the connection with other large images. Pages whose largest element is text are left out.
+## Inspect
+The rule script takes the LCP image from each page's `summary-lcp.json` (mobile cold-cache median run) and finds its request in that run's HAR and Lighthouse result. It checks:
+- `not-in-html`: Lighthouse's LCP discovery insight says the request isn't discoverable in the HTML, or JavaScript started it.
+- `lazy`: the image uses `loading="lazy"`.
+- `low-priority`: the request didn't start at High priority (it may be raised once layout shows it's on screen, which is too late).
+- `preload-mismatch`: the page preloads the same image at a different URL, so it downloads twice.
+- `competing-images`: other images of 10 KiB or more start at High priority before it.
+- `bandwidth`: other images downloading at the same time delay it by 100 ms or more, estimated from their share of the bytes downloaded while it loads.
+- `render-blocking`: Lighthouse estimates render-blocking requests delay the LCP by 100 ms or more.
+## Evaluate
+Pass when no page's LCP image has an issue; fail otherwise, at high severity when a page with an issue has an LCP over 2.5 s and medium when it is within. Undecided only when no page could be measured.
+## Evidence
+One `playhouse` item per issue, citing the HAR entry or Lighthouse audit, with the issue as its `value`.
+## Remediation
+Render the LCP image in the server HTML with `fetchpriority="high"` and without `loading="lazy"` (in the storefront, `DynamicImage` with `priority="high"`), make sure any preload uses the same URL and widths as the image, give other images default priority, and lazy-load images below the fold so they don't share the connection. Re-run Playhouse to confirm.
+## Examples
+Compliant: a home hero preloaded at High priority that downloads before the below-the-fold images start. Problematic: a PDP whose main image downloads alongside a 2.7 MB animated GIF thumbnail, or a hero image added after hydration that starts at Low priority.

package/dist/audit/catalog/categories/performance/rules/page-data-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/page-data-size.ts
+var page_data_size_default = documentSizeRule({
+	label: "Page data",
+	budget: 200 * 1024,
+	value: (size) => size.pageDataBytes,
+	format: kib,
+	evidence: (size) => size.scripts.pageData[0] ? { artifact: size.scripts.pageData[0] } : null,
+	decideFailures: false
+});
+
+//#endregion
+export { documentSizeDataSchema as dataSchema, page_data_size_default as default };

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

@@ -0,0 +1,22 @@
+---
+id: performance/page-data-size
+title: Page Data Size
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [playhouse.scripts, source.code]
+---
+
+## Intent
+Checks that the loader data React Router embeds in each page's HTML is 200 KiB or less. Everything a loader returns is serialized into the page so the browser can hydrate it, including fields the page never shows. Loaders that return raw Commerce API responses are the usual cause: every product's full image list, long absolute image URLs, variation and promotion details, custom attributes and whole category trees. When a page is over budget, the report points to the loaders and fields that could be trimmed.
+## Inspect
+The rule script adds up the page data scripts Playhouse archived from each page's HTML (`window.__reactRouterContext.streamController.enqueue(...)`, including streamed data). If every page is within 200 KiB, it passes and this rule needs no analysis.
+
+Otherwise, use the `data` file (sizes are in bytes): each page lists its sizes and `scripts.pageData`, the archived page data scripts largest first (relative to the page's `archiveDir`). Read the largest ones; they hold React Router's turbo-stream encoding, in which strings appear once and objects refer to them by index. Find which route's data the large strings belong to (keys such as `loaderData` and route ids such as `routes/_app.category.$categoryId`) and which fields take the most space. Then read that route's loaders in the project and the components that render their data, and list the returned fields the components never read.
+## Evaluate
+Report one `finding` for the rule, covering every page over 200 KiB. Lead with the fields that would save the most, with an approximate size for each, and the loader that returns them. Typical trims: map the API response to the fields the page renders before returning it from the loader; request fewer `expand` options; return only the images a product tile shows instead of every image group; return image paths instead of repeated absolute URLs. Data the page renders, or that client code needs later (for example, every color's images so a shopper can switch colors without a request), or that SEO or client-side navigation needs, stays. The customer decides which trims to apply, so phrase each one as a suggestion.
+## Evidence
+For each page over budget: its largest page data script (`playhouse`, with its size as `value`), and `source` evidence for each loader that returns the unused fields and for the components that read the fields that stay.
+## Remediation
+Shape loader data into what the page renders before returning it, so only that is serialized into the HTML. Re-run Playhouse to confirm each page's data is at or under 200 KiB.
+## Examples
+Compliant: a PLP loader that returns, for each product tile, its name, price, link and one image. Problematic: a PLP loader that returns the raw `productSearch` response, embedding every hit's swatch image URLs and variant UPC lists the tiles never show.

package/dist/audit/catalog/categories/performance/rules/reduce-javascript-on-load.js

@@ -0,0 +1,97 @@
+import { a as MIN_RECOMMENDED_BYTES, c as bundlePackageSchema, l as bundlePageSchema, s as bundleCandidateSchema } from "../../../../../schema.js";
+import { z } from "zod";
+
+//#region src/audit/catalog/categories/performance/rules/reduce-javascript-on-load.ts
+const MAX_PACKAGES = 30;
+/**
+* Only what could save `MIN_RECOMMENDED_BYTES` reaches the AI. An npm package the app's start needs (`deferrableBytes`
+* 0, or entry.client's own import) can't load later, so it's left out unless two versions of it are bundled.
+*/
+function worthALook(owner, graph) {
+	if (owner.kind === "build" || owner.bytes < MIN_RECOMMENDED_BYTES) return false;
+	if (owner.kind === "project" || !graph || owner.versions) return true;
+	return (owner.deferrableBytes ?? 0) >= MIN_RECOMMENDED_BYTES;
+}
+const pageSchema = z.object({
+	page: z.string(),
+	route: bundlePageSchema.shape.route,
+	liveDecodedBytes: z.number(),
+	local: z.object({
+		chunks: z.number().int(),
+		bytes: z.number(),
+		candidates: z.array(bundleCandidateSchema),
+		packages: z.array(bundlePackageSchema)
+	}).strict()
+}).strict();
+const dataSchema = z.object({
+	status: z.enum([
+		"complete",
+		"partial",
+		"unavailable"
+	]),
+	notes: z.array(z.string()),
+	visualizer: z.string().nullable(),
+	minSavedBytes: z.number(),
+	pages: z.array(pageSchema),
+	skipped: z.array(z.object({
+		page: z.string(),
+		reason: z.string()
+	}).strict())
+}).strict();
+/** Without a local build there is nothing to recommend from, so the AI isn't asked. */
+function notVerified(data, reason) {
+	return {
+		data,
+		decision: {
+			status: "not-verified",
+			summary: `${reason} Re-run the audit once the project's build script succeeds.`,
+			evidence: []
+		}
+	};
+}
+function reduceJavascriptOnLoad({ bundle }) {
+	if (!bundle) return notVerified({
+		status: "unavailable",
+		notes: ["prepare produced no bundle analysis."],
+		visualizer: null,
+		minSavedBytes: MIN_RECOMMENDED_BYTES,
+		pages: [],
+		skipped: []
+	}, "The run has no bundle analysis.");
+	const data = {
+		status: bundle.status,
+		notes: bundle.notes,
+		visualizer: bundle.build?.visualizer ?? null,
+		minSavedBytes: MIN_RECOMMENDED_BYTES,
+		skipped: bundle.skipped,
+		pages: bundle.pages.flatMap((page) => page.local ? [{
+			page: page.page,
+			route: page.route,
+			liveDecodedBytes: page.live.decodedBytes,
+			local: {
+				chunks: page.local.chunks,
+				bytes: page.local.bytes,
+				candidates: page.local.candidates.filter((item) => item.savedBytes >= MIN_RECOMMENDED_BYTES),
+				packages: page.local.packages.filter((owner) => worthALook(owner, bundle.status === "complete")).slice(0, MAX_PACKAGES)
+			}
+		}] : [])
+	};
+	if (bundle.status === "unavailable") return notVerified(data, `The project wasn't built, so its bundle wasn't analyzed: ${bundle.notes.join(" ")}`);
+	if (!data.pages.length) return notVerified(data, "No page's route was found in the local build, so no page was analyzed.");
+	if (data.pages.some((page) => page.local.candidates.length || page.local.packages.some((owner) => owner.kind === "npm"))) return { data };
+	return {
+		data,
+		decision: {
+			status: "pass",
+			summary: `In the local build, nothing that ${data.pages.map((page) => page.page).join(", ")} load up front could load later and save ${MIN_RECOMMENDED_BYTES / 1024} KiB or more.`,
+			evidence: data.pages.map((page) => ({
+				type: "manual",
+				description: `Local build: ${page.local.chunks} chunks, ${Math.round(page.local.bytes / 1024)} KiB up front.`,
+				location: page.page
+			}))
+		}
+	};
+}
+
+//#endregion
+export { dataSchema, reduceJavascriptOnLoad as default };

package/dist/audit/catalog/categories/performance/rules/reduce-javascript-on-load.md

@@ -0,0 +1,73 @@
+---
+id: performance/reduce-javascript-on-load
+title: Reduce JavaScript on Load
+severity: medium
+appliesTo: [home, plp, pdp]
+inputs: [project.build, source.code]
+---
+
+## Intent
+Recommends changes to the storefront's code that make each page download, parse and run less JavaScript before it responds. Almost always that means loading code later: components and libraries the page bundles up front but needs only after an interaction, further down the page, or on another route. Occasionally code shouldn't reach the client at all. Every number comes from a local build of the project folder, not from the live site, which may run other code. `performance/javascript-size` reports what the live site downloads.
+## Inspect
+The rule script's data comes from `bundle/analysis.json`, which `prepare` writes after building the project folder: the plain build's chunks with their source maps (minified bytes per module), the module graph from the build's `BUNDLES_SIZE_ANALYZE` visualizer report, and the build's React Router manifest. A page is matched to the build by its routes only: the route ids its live HTML names (route ids are route file names, so they survive a rebuild), else the local route whose path matches its URL (`route.source` says which). Never compare the local build with the live site's files or sizes: they come from different builds. `liveDecodedBytes` is context, not something to reconcile.
+
+For each page, `local` describes what its routes load up front in the local build: the entry, each route module and their static imports (`chunks`, `bytes`), and the imports and packages that could save at least `minSavedBytes` (30 KiB minified, about 10 KiB over the network). Anything smaller has already been left out, along with packages the app's start needs (React, React Router):
+
+- `candidates`: static imports in project code (`importer` with file, line and the import statement as `excerpt`; the imported `target` and its `package`), each with the minified bytes (`savedBytes`) and modules the page would no longer load up front if that one import became lazy. An import inside a larger candidate is listed only when it saves noticeably less. `lazyElsewhere` names project files that already load the target with `import()`: this static import defeats that split.
+- `packages`: npm packages and project folders in the page's up-front code: `bytes`, `modules`, `largestModules` (what of it the page pulls in), `versions` when more than one installed version is bundled, the project files that import an npm package statically (`importers`, the first 8 of `importerCount`) and the bytes freed if all of them became lazy (`deferrableBytes`; 0 means something the app needs to start also imports it).
+
+The numbers are exact for the local build; don't recompute them. The audited project is read-only: read and `grep` its source, never build or change it. `<run>/bundle/client-bundle-size.html` is the visualizer report for people; you don't need it.
+
+**Spend your effort only where the bytes are.** The recommendations worth making move 100 KiB or more off a page: a large library or component tree that loads up front but is needed only after a tap, further down the page, or on another route. Sort every page's candidates and packages by `savedBytes` (or `deferrableBytes`) and work down from the top; stop once the remaining ones are close to `minSavedBytes`. There is no quota: recommend only changes you traced and would make yourself, and if the page genuinely needs what it loads up front, recommend nothing. A well-optimized build has no recommendations, and that is a good result, not a gap to fill. One 150 KiB recommendation is worth more than ten 30 KiB ones. Code under `root` or `routes/_app` loads on every page, so one change helps them all. For each one worth a look:
+
+1. **Find what it's used for.** Open the importer at its line and follow the imported component, hook or function to every place it renders or runs. For a package, `grep -rn "from '<name>" src` finds every import, not just the first 8. Read enough to know when the code actually runs.
+2. **Decide when the page first needs it**, and pick the trigger:
+   - Rendered on the first render, in view without scrolling, or needed to make the visible page interactive (the header, the visible navigation bar, the product gallery's first image, the add-to-cart button): the page needs it now. Leave that code up front. Never defer the LCP element or anything above the fold.
+   - Rendered only after a tap, click, hover or focus (dialogs, drawers, the cart and search overlays, mega-menu panels, popovers, unselected tabs, closed accordions, toasts, a lightbox or zoom, a video before play, share menus, store-locator maps, chat): `interaction`.
+   - Part of the target renders up front and part only later (a navigation bar whose flyout panels open on hover or whose mobile drawer opens on tap, a gallery whose zoom viewer opens on tap): don't dismiss it because of the visible part. Recommend moving the later part into its own module and loading that lazily (`lazy-component` on the candidate's `target`, with its trigger), and say in `how` what stays up front. Do this only when the later part is a large share of the target.
+   - Below the fold and not needed for search or the LCP (recommendation carousels, recently viewed items, social feeds): `visible`, mounted when it nears the viewport. Content that matters for SEO (product details, reviews that are indexed) must stay server-rendered: don't recommend moving it to the client.
+   - Used only by other routes, but imported from a shared module (`root.tsx`, `_app.tsx`, a provider, a barrel `index.ts`, a `utils` file): `navigation`. Move the import into the route that uses it, and React Router loads it with that route's chunk.
+   - Needed after load but by nothing the shopper sees first (analytics, monitoring, experiment SDKs, prefetchers): `idle`, imported after the load event or in `requestIdleCallback`.
+   - Run only on the server (loaders, actions, SDK clients, server config) but reaching the client through a shared module: `remove` it from the client bundle by moving it into a `.server.ts` module or the loader.
+3. **Only when the code is needed up front, look for a narrower fix.** Most opportunities are step 2: the library stays, it just loads later. The changes below are exceptions; recommend one only on specific evidence you found in the source, never as a general preference for fewer dependencies, and never as an alternative to a lazy load that works:
+   - `narrower-import`: `largestModules` shows parts of a package the project never imports, because it imports a barrel or the package's root entry (`lodash` rather than `lodash/debounce`, a meta-package rather than `@radix-ui/react-x`). Name the entry point to import instead.
+   - `remove`: a second installed version of the same package (`versions`; align the ranges or add a `pnpm.overrides` entry), a polyfill for something every supported browser has, dev-only code (devtools, mocks), or an import kept only for a side effect nothing uses.
+   - `replace`: rare. Only when the project uses one or two small functions of a large library that must load up front, and a platform API does the same thing exactly (for example one `Intl.DateTimeFormat` call instead of a date library imported for one format). Replacing a library costs the team time and risk, so don't recommend rewriting a library's functionality in project code, and never for security- or correctness-critical code (sanitizing, cryptography, time zones, payments).
+4. **Make sure it works with server rendering.** A `React.lazy` component that renders on the server still downloads during hydration, right after load, so it saves nothing up front. A lazy component saves bytes only when it isn't rendered until the trigger: behind the `open` state, after the tab is selected, or once it's visible. Give it a fallback the same size as the content so the layout doesn't shift. Preload on intent (`onPointerEnter` or `onFocus` calling the same `import()`) so the first open still feels instant. Never defer `entry.client`, React, React Router, providers the first render needs, or styles the first paint needs.
+5. **Check the saving is real.** A candidate's `savedBytes` already excludes code something else still imports. For a package-wide change use `deferrableBytes`. `bytes` is only an upper bound for narrowing, replacing or removing. Don't recommend a change you couldn't trace to its use in the source.
+## Evaluate
+The customer decides which recommendations to apply; they are options, not defects.
+
+- `finding`: at least one change you traced makes a page load `minSavedBytes` or more less up front. Severity `medium` when a recommendation saves 100 KiB or more on a page, `low` otherwise.
+- `pass`: you checked the largest candidates and packages, and the page needs them up front or uses them well. Cite the ones you checked and leave out `recommendations`. Prefer a pass to a weak or speculative recommendation.
+
+Judge only from the local build and the source; the live site's sizes are reported by `performance/javascript-size`.
+## Evidence
+Cite each recommendation's main import as `source` evidence (file, line, and the import statement as `excerpt`). Add one `manual` evidence entry per page with recommendations, saying the figures come from the local build (for example `Local build of the project folder: home loads 61 chunks, 1,097 KiB up front`).
+
+Also add a `recommendations` field to the output file: the changes you recommend, best first (at most 30), each saving at least `minSavedBytes` on a page; `finalize` rejects smaller ones. Expect most of them to be `lazy-component` or `dynamic-import`; a list made mostly of `replace` changes means you skipped step 2. The dashboard shows them as AI recommendations. `finalize` adds each one's savings per page from `bundle/analysis.json`, so don't include sizes:
+
+```json
+"recommendations": [
+  { "pages": ["home", "plp", "pdp"], "change": "lazy-component", "trigger": "interaction",
+    "target": "src/components/navigation-menu-mega/index.tsx",
+    "title": "Load the mega menu's panels when a top-level category is first hovered or focused",
+    "how": "The panels render only while a category is open (navigation-menu-mega/index.tsx:88). Keep the top-level bar static, move the panel into its own module and render it with React.lazy inside Suspense once `openCategory` is set; call the same import() from onPointerEnter and onFocus so it's ready before the first open.",
+    "files": [{ "file": "src/routes/_app.tsx", "line": 28 }, { "file": "src/components/navigation-menu-mega/index.tsx", "line": 88 }] },
+  { "pages": ["pdp"], "change": "dynamic-import", "trigger": "interaction",
+    "target": "zod",
+    "title": "Load the review form's validation when the form is submitted",
+    "how": "zod is used only by the write-a-review form, which is closed on load (review-form.tsx:5). Import the schema module with `await import('./review-schema')` in the submit handler instead of at the top of the file, so the PDP no longer loads zod up front.",
+    "files": [{ "file": "src/components/reviews/review-form.tsx", "line": 5 }] }
+]
+```
+
+- `pages`: every page whose `local` data lists `target` and that the change helps.
+- `target`: exactly a candidate's `target` or a package's `name` from those pages' data. Recommend each piece of code once: not both a candidate and the package it belongs to.
+- `change`: `lazy-component` (a component, rendered with `React.lazy` once the trigger happens), `dynamic-import` (a function, library or data file, loaded with `await import()` where it's first used), `narrower-import`, `replace` or `remove`.
+- `trigger`: `interaction`, `visible`, `navigation` or `idle`, only for `lazy-component` and `dynamic-import`.
+- `title`: one line naming the change and when the code loads. `how`: what to change, in which file, and what keeps the page working, concretely enough to start on (a few sentences). `files`: where to make it, with lines.
+## Remediation
+Make each change in the files the recommendation names, then rebuild with `BUNDLES_SIZE_ANALYZE=true` and open `build/client-bundle-size.html` to confirm the code moved out of the page's up-front chunks. Defer a component by rendering it only once it's needed: `const CartDrawer = lazy(() => import('./cart-drawer'))`, then `{open && <Suspense fallback={<DrawerSkeleton />}><CartDrawer /></Suspense>}`. Defer a library to where it's used: `const { z } = await import('zod')` in the submit handler. Move route-specific imports out of `root.tsx`, `_app.tsx` and shared barrels into the routes that use them. Re-run the audit to see each page's local up-front JavaScript go down.
+## Examples
+Compliant: the cart drawer's contents load with `React.lazy` the first time it opens, and the review form loads its validation library on submit. Problematic: `src/routes/_app.tsx:28` imports the mega menu statically, so every page loads 41 KiB of menu panels that render only after a hover, even though `src/lib/page-designer/static-registry.ts` already imports the same component lazily.