@decocms/apps-vtex 7.59.1 → 7.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-vtex",
-  "version": "7.59.1",
+  "version": "7.61.0",
   "type": "module",
   "description": "Deco commerce app: VTEX integration",
   "repository": {
@@ -51,10 +51,10 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.59.1",
-    "@decocms/apps-commerce": "7.59.1",
-    "@decocms/apps-website": "7.59.1",
-    "@decocms/tanstack": "7.59.1"
+    "@decocms/blocks": "7.61.0",
+    "@decocms/apps-commerce": "7.61.0",
+    "@decocms/apps-website": "7.61.0",
+    "@decocms/tanstack": "7.61.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",

package/src/loaders/__tests__/legacyProductList.test.ts

@@ -0,0 +1,157 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// `legacyProductList` is the SHELF loader. It accepted no payload-shaping
+// options, so every shelf paid the full product for every entry — measured on a
+// real home shelf (`count: 28`): 1095 KB, 39.1 KB per product, of which
+// `isVariantOf` 19.1 KB and the 48-rung `offers.priceSpecification` 12.8 KB.
+// `legacyProductListingPage` already took them; this file pins the pass-through,
+// because declaring the options WITHOUT forwarding them is exactly the bug the
+// PLP loader had.
+
+vi.mock("../../client", () => ({
+	getVtexConfig: () => ({ account: "test", salesChannel: "1" }),
+	vtexFetch: vi.fn(),
+	vtexFetchResponse: vi.fn(),
+}));
+
+import { vtexFetch } from "../../client";
+import { legacyProductList } from "../legacy";
+
+const sellers = (price: number) => [
+	{
+		sellerId: "1",
+		sellerName: "Seller One",
+		sellerDefault: true,
+		commertialOffer: {
+			AvailableQuantity: 5,
+			Price: price,
+			ListPrice: price + 30,
+			PriceWithoutDiscount: price + 30,
+			spotPrice: price,
+			PriceValidUntil: "2025-12-31",
+			// A real ladder: every method the store accepts, every installment count.
+			Installments: ["Visa", "Master", "Amex", "Boleto"].flatMap((method) =>
+				Array.from({ length: 4 }, (_, i) => ({
+					Value: price / (i + 1),
+					NumberOfInstallments: i + 1,
+					Name: `${method} ${i + 1}x`,
+					InterestRate: 0,
+					TotalValuePlusInterestRate: price,
+					PaymentSystemName: method,
+				})),
+			),
+			GiftSkuIds: [],
+			teasers: [],
+		},
+	},
+];
+
+const sku = (itemId: string, price: number) => ({
+	itemId,
+	name: `SKU ${itemId}`,
+	nameComplete: `SKU ${itemId}`,
+	complementName: "",
+	ean: "1234567890123",
+	referenceId: [{ Key: "RefId", Value: `REF-${itemId}` }],
+	images: Array.from({ length: 4 }, (_, i) => ({
+		imageId: `${itemId}-${i}`,
+		imageUrl: `https://img.com/${itemId}-${i}.jpg`,
+		imageText: `img${i}`,
+		imageLabel: `label${i}`,
+	})),
+	sellers: sellers(price),
+	Videos: [],
+	estimatedDateArrival: null,
+	measurementUnit: "un",
+	unitMultiplier: 1,
+	variations: [],
+	attachments: [],
+	isKit: false,
+});
+
+const legacyProduct = () => ({
+	productId: "PROD1",
+	productName: "Test Product",
+	brand: "TestBrand",
+	brandId: 1,
+	brandImageUrl: null,
+	linkText: "test-product",
+	productReference: "REF1",
+	categoryId: "1",
+	productTitle: "Test Product",
+	metaTagDescription: "meta",
+	clusterHighlights: {},
+	productClusters: {},
+	searchableClusters: {},
+	categories: ["/Electronics/"],
+	categoriesIds: ["/1/"],
+	link: "https://test/test-product/p",
+	description: "x".repeat(2000),
+	items: [sku("SKU1", 90), sku("SKU2", 60), sku("SKU3", 120)],
+	allSpecifications: [],
+	allSpecificationsGroups: [],
+	skuSpecifications: [],
+	releaseDate: "2024-01-01",
+});
+
+const opts = { query: { count: 1 } as any, baseUrl: "https://example.com" };
+const ladderOf = (p: any) => p?.offers?.offers?.[0]?.priceSpecification ?? [];
+
+describe("legacyProductList — payload-shaping options reach toProduct", () => {
+	beforeEach(() => {
+		(vtexFetch as any).mockReset();
+		(vtexFetch as any).mockResolvedValue([legacyProduct()]);
+	});
+
+	it("no options: full product, full ladder, every variant, every image", async () => {
+		const [p] = (await legacyProductList(opts)) as any[];
+		expect(ladderOf(p).length).toBeGreaterThan(10);
+		expect(p.isVariantOf.hasVariant).toHaveLength(3);
+		expect(ladderOf(p.isVariantOf.hasVariant[0]).length).toBeGreaterThan(10);
+		expect(p.image).toHaveLength(4);
+		expect(p.description).toBeTruthy();
+	});
+
+	it("leanVariants empties the ladder on every variant", async () => {
+		const [p] = (await legacyProductList({ ...opts, leanVariants: true })) as any[];
+		for (const v of p.isVariantOf.hasVariant) expect(ladderOf(v)).toEqual([]);
+	});
+
+	it("displayedVariantId keeps the ladder on the one variant the card renders", async () => {
+		const [p] = (await legacyProductList({
+			...opts,
+			leanVariants: true,
+			displayedVariantId: (items: any[]) => items[1].itemId,
+		})) as any[];
+		const kept = p.isVariantOf.hasVariant.find((v: any) => v.sku === "SKU2");
+		expect(ladderOf(kept).length).toBeGreaterThan(0);
+		// ...and it is the LEAN shape, not a second full product.
+		expect(kept.description).toBeUndefined();
+	});
+
+	it("priceSpecifications rewrites the root ladder with the caller's rule", async () => {
+		const [p] = (await legacyProductList({
+			...opts,
+			priceSpecifications: (specs) => specs.filter((s) => !s.priceComponentType),
+		})) as any[];
+		expect(ladderOf(p).every((s: any) => !s.priceComponentType)).toBe(true);
+		expect(ladderOf(p).length).toBeLessThan(10);
+	});
+
+	it("maxImages caps image[] by position", async () => {
+		const [p] = (await legacyProductList({ ...opts, maxImages: 2 })) as any[];
+		expect(p.image).toHaveLength(2);
+	});
+
+	it("every option absent is byte-for-byte the previous output", async () => {
+		const [before] = (await legacyProductList(opts)) as any[];
+		const [after] = (await legacyProductList({
+			...opts,
+			leanVariants: undefined,
+			displayedVariantId: undefined,
+			maxImages: undefined,
+			priceSpecifications: undefined,
+		})) as any[];
+		expect(JSON.stringify(after)).toBe(JSON.stringify(before));
+	});
+});

package/src/loaders/legacy.ts

@@ -33,6 +33,7 @@ import {
 	toProduct,
 	toProductPage,
 } from "../utils/transform";
+import type { ProductOptions } from "../utils/transform";
 import type { LegacyFacet, LegacyItem, LegacyProduct, LegacySort, PageType } from "../utils/types";
 
 // ---------------------------------------------------------------------------
@@ -158,6 +159,23 @@ export interface LegacyProductListOptions {
 	query: LegacyProductListQuery;
 	baseUrl: string;
 	priceCurrency?: string;
+	/**
+	 * Payload-shaping options, forwarded verbatim to `toProduct`. Same set the
+	 * PLP loader already accepts, and for the same reason: a shelf renders a
+	 * CARD, but this loader built the full product for every entry. Measured on
+	 * a real home shelf (`count: 28`), 1095 KB — 39.1 KB per product, of which
+	 * `isVariantOf` 19.1 KB and the 48-rung `offers.priceSpecification` 12.8 KB.
+	 *
+	 * All default to undefined, which keeps the previous output byte for byte.
+	 * See the matching fields on {@link ProductOptions}.
+	 */
+	leanVariants?: ProductOptions["leanVariants"];
+	displayedVariantId?: ProductOptions["displayedVariantId"];
+	variantPropertyNames?: ProductOptions["variantPropertyNames"];
+	variantIncludeImage?: ProductOptions["variantIncludeImage"];
+	variantIncludeInventory?: ProductOptions["variantIncludeInventory"];
+	maxImages?: ProductOptions["maxImages"];
+	priceSpecifications?: ProductOptions["priceSpecifications"];
 }
 
 function isCollectionQuery(
@@ -233,7 +251,18 @@ function queryToSearchParams(
  * Ported from: vtex/loaders/legacy/productList.ts
  */
 export async function legacyProductList(opts: LegacyProductListOptions): Promise<Product[] | null> {
-	const { query, baseUrl, priceCurrency = "BRL" } = opts;
+	const {
+		query,
+		baseUrl,
+		priceCurrency = "BRL",
+		leanVariants,
+		displayedVariantId,
+		variantPropertyNames,
+		variantIncludeImage,
+		variantIncludeInventory,
+		maxImages,
+		priceSpecifications,
+	} = opts;
 	const searchArgs = queryToSearchParams(query);
 	const qs = buildSearchParams(searchArgs);
 
@@ -254,7 +283,17 @@ export async function legacyProductList(opts: LegacyProductListOptions): Promise
 	};
 
 	let products = vtexProducts.map((p) =>
-		toProduct(p, preferredSKU(p.items), 0, { baseUrl, priceCurrency }),
+		toProduct(p, preferredSKU(p.items), 0, {
+			baseUrl,
+			priceCurrency,
+			leanVariants,
+			displayedVariantId,
+			variantPropertyNames,
+			variantIncludeImage,
+			variantIncludeInventory,
+			maxImages,
+			priceSpecifications,
+		}),
 	);
 
 	if (isSkuIdsQuery(query)) {
@@ -342,6 +381,28 @@ export interface LegacyPLPOptions {
 	/** Ignore case when checking if a facet is selected */
 	ignoreCaseSelected?: boolean;
 	includeOriginalAttributes?: string[];
+	/**
+	 * Build `isVariantOf.hasVariant[]` with the lean variant transform instead of
+	 * a full nested `toProduct` per SKU. Off by default (unchanged behaviour).
+	 *
+	 * `productDetailsPage` (intelligent search) already exposes this, but the
+	 * legacy PLP never plumbed it — so a listing always paid the full variant
+	 * tree. Measured on a real store (36 products, 26 variants each): ~9.6 MB
+	 * per page, 96% of each product in `isVariantOf.hasVariant`, because every
+	 * variant carries the whole 48-entry payment ladder plus a copy of the
+	 * parent `description` — none of which a listing card reads.
+	 */
+	leanVariants?: boolean;
+	/** Keep the ladder on the ONE variant the card renders — see ProductOptions.displayedVariantId. */
+	displayedVariantId?: ProductOptions["displayedVariantId"];
+	/** Forwarded to the lean variant transform. */
+	variantPropertyNames?: Set<string>;
+	variantIncludeImage?: boolean;
+	variantIncludeInventory?: boolean;
+	/** Cap image[] to the first N entries — see ProductOptions.maxImages. */
+	maxImages?: number;
+	/** Rewrite priceSpecification on emitted offers — see ProductOptions.priceSpecifications. */
+	priceSpecifications?: ProductOptions["priceSpecifications"];
 }
 
 /**
@@ -362,6 +423,13 @@ export async function legacyProductListingPage(
 		ignoreCaseSelected,
 		useCollectionName,
 		includeOriginalAttributes,
+		leanVariants,
+		displayedVariantId,
+		variantPropertyNames,
+		variantIncludeImage,
+		variantIncludeInventory,
+		maxImages,
+		priceSpecifications,
 	} = opts;
 
 	const currentPageOffset = opts.pageOffset ?? 1;
@@ -447,6 +515,13 @@ export async function legacyProductListingPage(
 			baseUrl,
 			priceCurrency,
 			includeOriginalAttributes,
+			leanVariants,
+			displayedVariantId,
+			variantPropertyNames,
+			variantIncludeImage,
+			variantIncludeInventory,
+			maxImages,
+			priceSpecifications,
 		}),
 	);
 

package/src/utils/__tests__/transform.test.ts

@@ -23,6 +23,7 @@ import {
 	toAdditionalPropertySpecification,
 	toBrand,
 	toPostalAddress,
+	toProduct,
 	toProductShelf,
 	toProductVariant,
 } from "../transform";
@@ -767,3 +768,213 @@ describe("toProductShelf", () => {
 		expect(result.isVariantOf?.additionalProperty).toEqual([]);
 	});
 });
+
+// ---------------------------------------------------------------------------
+// toProduct — escape hatches for leanVariants listings
+// ---------------------------------------------------------------------------
+//
+// `leanVariants` assumes the card renders the ROOT sku, so `buildOfferVariant`
+// empties `priceSpecification` on every `hasVariant[]` entry. A card that picks
+// a representative variant instead (e.g. "cheapest in stock") reads that
+// entry's own offer for list price and installments — blank with the ladder
+// emptied. `displayedVariantId` keeps exactly that one entry full.
+//
+// `maxImages` caps `image[]` by POSITION. Both default to undefined, which
+// preserves the previous output byte for byte — that is what the last two cases
+// pin down.
+
+describe("toProduct — displayedVariantId / maxImages", () => {
+	const sellers = (price: number) => [
+		{
+			sellerId: "1",
+			sellerName: "Seller One",
+			commertialOffer: {
+				AvailableQuantity: 5,
+				Price: price,
+				ListPrice: price + 30,
+				spotPrice: price,
+				PriceValidUntil: "2025-12-31",
+				// A real ladder: every payment method the store accepts, every
+				// installment count. Measured on a live listing: 46 rungs per SKU,
+				// 12.0 KB — the thing `leanOffer` exists to drop.
+				Installments: ["Visa", "Master", "Amex", "PIX"].flatMap((method) =>
+					Array.from({ length: 3 }, (_, i) => ({
+						Value: price / (i + 1),
+						NumberOfInstallments: i + 1,
+						Name: `${method} ${i + 1}x`,
+						InterestRate: 0,
+						TotalValuePlusInterestRate: price,
+						PaymentSystemName: method,
+					})),
+				),
+				GiftSkuIds: [],
+				teasers: [],
+			},
+		},
+	];
+
+	const makeSku = (itemId: string, price: number, imageCount = 4) =>
+		({
+			itemId,
+			name: `SKU ${itemId}`,
+			ean: "1234567890123",
+			referenceId: [{ Key: "RefId", Value: `REF-${itemId}` }],
+			images: Array.from({ length: imageCount }, (_, i) => ({
+				imageUrl: `https://img.com/${itemId}-${i}.jpg`,
+				imageText: `img${i}`,
+				imageLabel: `label${i}`,
+			})),
+			videos: [],
+			sellers: sellers(price),
+			variations: [{ name: "Cor", values: ["Preto"] }],
+			kitItems: [],
+			complementName: "",
+			estimatedDateArrival: null,
+			modalType: null,
+		}) as any;
+
+	const makeProduct = (items: any[]) =>
+		({
+			origin: "intelligent-search",
+			productId: "PROD1",
+			productName: "Test Product",
+			brand: "TestBrand",
+			brandId: 1,
+			brandImageUrl: null,
+			productReference: "REF1",
+			description: "desc",
+			releaseDate: "2024-01-01",
+			linkText: "test-product",
+			categories: ["/Electronics/"],
+			categoriesIds: ["/1/"],
+			categoryId: "1",
+			productClusters: [],
+			clusterHighlights: [],
+			items,
+		}) as any;
+
+	const options = { baseUrl: "https://example.com", priceCurrency: "BRL" };
+	const items = [makeSku("SKU1", 90), makeSku("SKU2", 60), makeSku("SKU3", 120)];
+	const product = makeProduct(items);
+
+	const ladderOf = (variant: any) => variant?.offers?.offers?.[0]?.priceSpecification ?? [];
+
+	/** Regra do caller: só os tipos base, nenhuma parcela. */
+	const onlyListAndSale = (specs: any[]) =>
+		specs.filter((s) => !s.priceComponentType);
+
+	it("leanVariants alone empties the payment ladder on every variant", () => {
+		const result = toProduct(product, items[0], 0, { ...options, leanVariants: true });
+		const variants = result.isVariantOf?.hasVariant ?? [];
+		expect(variants).toHaveLength(3);
+		for (const v of variants) expect(ladderOf(v)).toEqual([]);
+	});
+
+	it("displayedVariantId keeps the ladder on the ONE variant the card renders", () => {
+		const result = toProduct(product, items[0], 0, {
+			...options,
+			leanVariants: true,
+			displayedVariantId: (skus) => skus.find((s: any) => s.itemId === "SKU2")?.itemId,
+		});
+		const variants = result.isVariantOf?.hasVariant ?? [];
+		const kept = variants.find((v: any) => v.sku === "SKU2");
+		const lean = variants.filter((v: any) => v.sku !== "SKU2");
+
+		expect(ladderOf(kept).length).toBeGreaterThan(0);
+		for (const v of lean) expect(ladderOf(v)).toEqual([]);
+	});
+
+	it("the kept variant stays LEAN — only its offer is upgraded", () => {
+		const result = toProduct(product, items[0], 0, {
+			...options,
+			leanVariants: true,
+			displayedVariantId: () => "SKU2",
+		});
+		const kept: any = (result.isVariantOf?.hasVariant ?? []).find((v: any) => v.sku === "SKU2");
+
+		// A full toProduct here would re-emit these; the lean shape must not.
+		expect(kept.description).toBeUndefined();
+		expect(kept.brand).toBeUndefined();
+		expect(kept.gtin).toBeUndefined();
+		expect(kept.isVariantOf).toBeUndefined();
+		// ...but the ladder is real. Without a `priceSpecifications` rule it is
+		// the FULL one — dropping description/brand/isVariantOf is the win here,
+		// and the ladder stays whatever the caller asked for.
+		const full = ladderOf(toProduct(product, items[1], 0, options));
+		expect(ladderOf(kept).length).toBe(full.length);
+	});
+
+	it("the kept variant keeps its real inventoryLevel (selectors read it per SKU)", () => {
+		const result = toProduct(product, items[0], 0, {
+			...options,
+			leanVariants: true,
+			displayedVariantId: () => "SKU2",
+		});
+		const kept: any = (result.isVariantOf?.hasVariant ?? []).find((v: any) => v.sku === "SKU2");
+		// buildOfferShelf hard-zeroes inventoryLevel; the variant path must not
+		// inherit that, or every variant reads as out of stock.
+		expect(kept.offers?.offers?.[0]?.inventoryLevel?.value).toBe(5);
+	});
+
+	it("the ladder flag does NOT leak into the lean variants", () => {
+		// Regression: the internal `variantKeepLadder` reached `variantOptions`,
+		// so every lean variant emitted a ladder instead of an empty one and the
+		// option made the payload BIGGER — measured on a real listing,
+		// isVariantOf 38.6 -> 49.6 KB.
+		const result = toProduct(product, items[0], 0, {
+			...options,
+			leanVariants: true,
+			priceSpecifications: onlyListAndSale,
+			displayedVariantId: () => "SKU2",
+		});
+		const variants = result.isVariantOf?.hasVariant ?? [];
+		for (const v of variants.filter((v: any) => v.sku !== "SKU2")) {
+			expect(ladderOf(v)).toEqual([]);
+		}
+		expect(ladderOf(variants.find((v: any) => v.sku === "SKU2")).length).toBeGreaterThan(0);
+	});
+
+	it("priceSpecifications rewrites the ROOT ladder with the caller's own rule", () => {
+		const full = toProduct(product, items[0], 0, options);
+		const lean = toProduct(product, items[0], 0, {
+			...options,
+			priceSpecifications: onlyListAndSale,
+		});
+
+		expect(ladderOf(full).length).toBeGreaterThan(ladderOf(lean).length);
+		const types = new Set(ladderOf(lean).map((s: any) => s.priceType));
+		expect(types.has("https://schema.org/ListPrice")).toBe(true);
+		expect(types.has("https://schema.org/SalePrice")).toBe(true);
+	});
+
+	it("displayedVariantId returning undefined leaves every variant lean", () => {
+		const result = toProduct(product, items[0], 0, {
+			...options,
+			leanVariants: true,
+			displayedVariantId: () => undefined,
+		});
+		for (const v of result.isVariantOf?.hasVariant ?? []) expect(ladderOf(v)).toEqual([]);
+	});
+
+	it("maxImages caps image[] by position", () => {
+		const full = toProduct(product, items[0], 0, options);
+		expect(full.image).toHaveLength(4);
+
+		const capped = toProduct(product, items[0], 0, { ...options, maxImages: 2 });
+		expect(capped.image).toHaveLength(2);
+		expect(capped.image?.map((i) => i.url)).toEqual(
+			full.image?.slice(0, 2).map((i) => i.url),
+		);
+	});
+
+	it("every option absent is byte-for-byte the previous output", () => {
+		const before = toProduct(product, items[0], 0, options);
+		const after = toProduct(product, items[0], 0, {
+			...options,
+			displayedVariantId: undefined,
+			maxImages: undefined,
+			priceSpecifications: undefined,
+		});
+		expect(JSON.stringify(after)).toBe(JSON.stringify(before));
+	});
+});

package/src/utils/transform.ts

@@ -99,7 +99,7 @@ const getProductURL = (origin: string, product: { linkText: string }, skuId?: st
 const nonEmptyArray = <T>(array: T[] | null | undefined) =>
 	Array.isArray(array) && array.length > 0 ? array : null;
 
-interface ProductOptions {
+export interface ProductOptions {
 	baseUrl: string;
 	/** Price coded currency, e.g.: USD, BRL */
 	priceCurrency: string;
@@ -108,6 +108,69 @@ interface ProductOptions {
 	includeOriginalAttributes?: string[];
 	/** Use lean toProductVariant for hasVariant[] instead of full toProduct at level=1 */
 	leanVariants?: boolean;
+	/**
+	 * With `leanVariants`, keep the payment ladder on the ONE variant the card
+	 * actually renders. Receives the raw SKU list and returns that SKU's
+	 * `itemId` (or undefined to leave every variant lean).
+	 *
+	 * Why this exists: `leanVariants` assumes the card renders the ROOT sku, so
+	 * `buildOfferVariant` empties `priceSpecification` on every entry. Cards that
+	 * instead pick a representative variant out of `isVariantOf.hasVariant` (e.g.
+	 * "cheapest in stock") read that variant's own offer for list price and
+	 * installments — with the ladder emptied, those render blank.
+	 *
+	 * The kept entry stays on the LEAN variant shape and only its offer is
+	 * upgraded, to {@link buildOfferShelf} (ListPrice/SalePrice/SRP + PIX + the
+	 * one installment `useOffer` would pick). A full `toProduct` here would
+	 * instead re-emit `description` and the whole 48-entry ladder the parent
+	 * already carries: measured on a real listing, 17.5 KB of the 53.5 KB in
+	 * every product, for a card that reads price and installment only.
+	 *
+	 * Undefined (default) preserves the current behaviour byte for byte.
+	 */
+	displayedVariantId?: (items: Array<LegacySkuVTEX | SkuVTEX>) => string | undefined;
+	/**
+	 * Rewrite `priceSpecification` on the offers this transform emits. Runs on
+	 * the ROOT offer and on the offer of the variant `displayedVariantId` picks.
+	 *
+	 * A listing renders ONE installment string per card, while the Catalog API
+	 * returns every payment method the store accepts: measured on a real page,
+	 * 48 `UnitPriceSpecification` entries = 12.0 KB per product, 22% of the
+	 * listing payload — built, cached and re-serialized in full.
+	 *
+	 * Deliberately a caller-supplied function and not a boolean: WHICH rungs a
+	 * card reads is store policy, not ours. {@link buildOfferShelf} keeps the
+	 * `bestInstallment` one (lowest total, tie-broken by highest
+	 * `billingDuration`) — and on a store with a boleto discount that resolves to
+	 * "Boleto Bancário 1x", measured against a storefront that renders
+	 * "Visa 10x" on all 36 cards of the page. Same data, different string. Pass
+	 * `(specs) => [buildOfferShelf({ ...offer, priceSpecification: specs }).…]`-style
+	 * logic, or your own predicate; the transform only applies it.
+	 *
+	 * Undefined (default) keeps the full ladder — a PDP needs it.
+	 */
+	priceSpecifications?: (specs: UnitPriceSpecification[]) => UnitPriceSpecification[];
+	/**
+	 * Internal: set by `toProduct`/`toProductShelf` on the ONE variant
+	 * `displayedVariantId` picked, so `toProductVariant` emits a real ladder for
+	 * it instead of `buildOfferVariant`'s empty one. Not meant for callers.
+	 */
+	variantKeepLadder?: boolean;
+	/**
+	 * Cap `image[]` to the first N entries, in path order. Undefined (default)
+	 * keeps every image.
+	 *
+	 * Listings render at most a couple of images per card, while the Catalog API
+	 * returns every asset registered on the SKU (3 on average, up to 5 measured).
+	 *
+	 * NOTE: this truncates by POSITION, so images the consumer selects BY NAME
+	 * can fall outside the cap. Measured on a real listing page: the `vira`
+	 * (hover) image sits at index 1 in only 5 of the 19 products that have one —
+	 * index 2 in 12 of them, index 3 in 2. A cap of 2 therefore drops the hover
+	 * image on most cards that use one. Callers that select by name should keep
+	 * the named entries instead of using this option.
+	 */
+	maxImages?: number;
 	/** Property names to keep on lean variant additionalProperty. Defaults to VARIANT_PROPERTY_NAMES. */
 	variantPropertyNames?: Set<string>;
 	/** When leanVariants is true, still include image[0] on each variant entry. Default true. */
@@ -396,17 +459,31 @@ export const toProduct = <P extends LegacyProductVTEX | ProductVTEX>(
 		: toAdditionalProperties(sku);
 	const referenceIdAdditionalProperty = toAdditionalPropertyReferenceIds(referenceId);
 	const images = nonEmptyArray(sku.images);
-	const offers = (sku.sellers ?? []).map(isLegacyProduct(product) ? toOfferLegacy : toOffer);
-
-	const variantOptions =
-		imagesByKey !== options.imagesByKey ? { ...options, imagesByKey } : options;
+	const rawOffers = (sku.sellers ?? []).map(isLegacyProduct(product) ? toOfferLegacy : toOffer);
+	const offers = applyPriceSpecifications(rawOffers, options);
+
+	// `variantKeepLadder` must NOT be inherited: while it leaked through, every
+	// lean variant emitted a ladder instead of an empty one — measured on a real
+	// listing, `isVariantOf` GREW from 38.6 KB to 49.6 KB, so the option made
+	// the payload bigger. Only the entry `displayedVariantId` picks turns it on,
+	// explicitly, below.
+	const variantOptions = { ...options, imagesByKey, variantKeepLadder: false };
 	const isVariantOf =
 		level < 1
 			? ({
 					"@type": "ProductGroup",
 					productGroupID: productId,
 					hasVariant: options.leanVariants
-						? items.map((sku) => toProductVariant(product, sku, variantOptions))
+						? ((keepId) =>
+								items.map((sku) =>
+									toProductVariant(
+										product,
+										sku,
+										keepId !== undefined && sku.itemId === keepId
+											? { ...variantOptions, variantKeepLadder: true }
+											: variantOptions,
+									),
+								))(options.displayedVariantId?.(items))
 						: items.map((sku) => toProduct(product, sku, 1, variantOptions)),
 					url: getProductGroupURL(baseUrl, product).href,
 					name: product.productName,
@@ -418,7 +495,9 @@ export const toProduct = <P extends LegacyProductVTEX | ProductVTEX>(
 				} satisfies ProductGroup)
 			: undefined;
 
-	const finalImages = images?.map(({ imageUrl, imageText, imageLabel }) => {
+	const cappedImages =
+		typeof options.maxImages === "number" ? images?.slice(0, options.maxImages) : images;
+	const finalImages = cappedImages?.map(({ imageUrl, imageText, imageLabel }) => {
 		const url = imagesByKey.get(getImageKey(imageUrl)) ?? imageUrl;
 		const alternateName = imageText || imageLabel || "";
 		const name = imageLabel || "";
@@ -567,6 +646,19 @@ export const buildOfferShelf = (offer: Offer): Offer => {
 	};
 };
 
+/**
+ * Apply `options.priceSpecifications` to every offer, if the caller supplied it.
+ * Identity (same array reference) when absent, so the default output is
+ * byte-for-byte unchanged.
+ */
+const applyPriceSpecifications = (offers: Offer[], options: ProductOptions): Offer[] =>
+	options.priceSpecifications
+		? offers.map((offer) => ({
+				...offer,
+				priceSpecification: options.priceSpecifications!(offer.priceSpecification ?? []),
+			}))
+		: offers;
+
 /** Property names commonly used by ProductCard/Shelf components */
 const SHELF_PROPERTY_NAMES = new Set([
 	"category",
@@ -646,9 +738,16 @@ export const toProductShelf = <P extends LegacyProductVTEX | ProductVTEX>(
 					const inStockSku = findFirstAvailable(items) ?? items[0];
 					// Opt-in: every SKU as a lean variant (size/color grid on shelf cards).
 					// Default: a single in-stock variant (lean shelf payload).
+					const keepId = options.displayedVariantId?.(items);
 					const hasVariant = options.shelfCompleteVariants
 						? items.map((variantSku) =>
-								toProductVariant(product, variantSku, options),
+								toProductVariant(
+									product,
+									variantSku,
+									keepId !== undefined && variantSku.itemId === keepId
+										? { ...options, variantKeepLadder: true }
+										: options,
+								),
 							)
 						: inStockSku
 							? [toProductShelf(product, inStockSku, 1, options)]
@@ -741,7 +840,20 @@ export const toProductVariant = <P extends LegacyProductVTEX | ProductVTEX>(
 	const offerConverter = isLegacyProduct(product) ? toOfferLegacy : toOffer;
 	const allOffers = (sku.sellers ?? []).map(offerConverter).sort(bestOfferFirst);
 	const bestOffer = allOffers[0];
-	const leanOffers = bestOffer ? [buildOfferVariant(bestOffer, includeInventory)] : [];
+	// `variantKeepLadder` marks the ONE variant the card renders (see
+	// displayedVariantId): it keeps the LEAN shape but needs a real ladder,
+	// through the same `priceSpecifications` hook the root offer uses.
+	const leanOffers = bestOffer
+		? [
+				options.variantKeepLadder
+					? {
+							...buildOfferVariant(bestOffer, includeInventory),
+							priceSpecification: applyPriceSpecifications([bestOffer], options)[0]
+								.priceSpecification,
+						}
+					: buildOfferVariant(bestOffer, includeInventory),
+			]
+		: [];
 
 	// image[0] only — selectors render a single thumbnail. Reuse the same
 	// imagesByKey lookup toProduct uses so URLs stay consistent across variants.