@decocms/apps-vtex 7.66.4 → 7.66.6

package/package.json

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

package/src/client.ts

@@ -206,6 +206,55 @@ export function vtexHost(environment: string = "vtexcommercestable", config?: Vt
 	return `${c.account}.${environment}.${domain}`;
 }
 
+/**
+ * Origin every product/SKU/breadcrumb URL in the schema.org payload is built
+ * from.
+ *
+ * Order matters, and the first branch is the whole point: a storefront answers
+ * on the host the shopper actually typed, and that is the host its canonical
+ * URLs, JSON-LD and sitemap entries have to name. deco-cx/apps got this from
+ * the request too (`vtex/loaders/intelligentSearch/productList.ts` passes
+ * `baseUrl: url`), and dropping it here is what made a migrated storefront
+ * publish structured data pointing somewhere else.
+ *
+ * `publicUrl` is only a fallback. It is the VTEX *checkout* host
+ * (`secure.<brand>.com`), which is a different site from the storefront, and
+ * it is stored with whatever shape the admin typed — commonly a full URL
+ * (`https://secure.example.com/`). Interpolating that into `https://${...}`
+ * produced `https://https://secure.example.com/`, which `new URL()` parses
+ * with host `https`, so every product ended up at `https://https/<slug>/p`.
+ * Normalising through `URL` removes that whole class of bug.
+ *
+ * Returns no trailing slash, so `new URL(path, baseUrl)` behaves the same for
+ * every branch.
+ */
+export function storefrontBaseUrl(config?: VtexConfig): string {
+	const c = config ?? getVtexConfig();
+
+	// 1. The host serving this request -- the storefront's own origin.
+	const request = RequestContext.current?.request;
+	if (request) {
+		try {
+			return new URL(request.url).origin;
+		} catch {
+			// Fall through: a synthetic Request may carry an unparseable url.
+		}
+	}
+
+	// 2. Configured public URL, normalised whether or not it carries a scheme.
+	if (c.publicUrl) {
+		const normalised = /^https?:\/\//i.test(c.publicUrl) ? c.publicUrl : `https://${c.publicUrl}`;
+		try {
+			return new URL(normalised).origin;
+		} catch {
+			// Fall through to the account host rather than publish a broken origin.
+		}
+	}
+
+	// 3. The account's VTEX host. Always well-formed; never the public brand.
+	return `https://${vtexHost("vtexcommercestable", c)}`;
+}
+
 function baseUrl(): string {
 	return `https://${vtexHost()}`;
 }

package/src/loaders/autocomplete.ts

@@ -4,7 +4,7 @@
  * Combines /autocomplete_suggestions/ and /product_search/ in parallel,
  * transforms IS products to schema.org via pickSku + toProduct.
  */
-import { getVtexConfig, intelligentSearch as vtexIS } from "../client";
+import { getVtexConfig, intelligentSearch as vtexIS, storefrontBaseUrl } from "../client";
 import { pickSku, toProduct as toSchemaProduct } from "../utils/transform";
 
 export interface AutocompleteProps {
@@ -40,9 +40,7 @@ export async function autocompleteSearch(props: AutocompleteProps): Promise<Auto
 		]);
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		return {
 			searches: suggestionsData.searches ?? [],

package/src/loaders/intelligentSearch/productDetailsPage.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ProductDetailsPage } from "@decocms/apps-commerce/types";
-import { getVtexConfig, vtexCachedFetch } from "../../client";
+import { getVtexConfig, storefrontBaseUrl, vtexCachedFetch } from "../../client";
 import PDPDefaultPath from "../paths/PDPDefaultPath";
 import { searchBySlug } from "../../utils/slugCache";
 import { pickSku, toProductPage } from "../../utils/transform";
@@ -74,9 +74,7 @@ export default async function vtexProductDetailsPage(
 		}
 
 		const product = products[0];
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const sku = pickSku(product, skuId);
 

package/src/loaders/intelligentSearch/productList.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Product } from "@decocms/apps-commerce/types";
-import { getVtexConfig, intelligentSearch, toFacetPath } from "../../client";
+import { getVtexConfig, intelligentSearch, storefrontBaseUrl, toFacetPath } from "../../client";
 import { pickSku, sortProducts, toProductShelf } from "../../utils/transform";
 import type { Product as ProductVTEX } from "../../utils/types";
 
@@ -19,6 +19,13 @@ export interface ProductListProps {
 	 * a single in-stock variant per product).
 	 */
 	completeVariants?: boolean;
+	/**
+	 * `imageLabel`s that survive the shelf transform's 2-image cap. Storefronts
+	 * that pick the card image by name (a still/packshot asset, a colour
+	 * thumbnail) need this: those assets are registered last on the SKU, so the
+	 * positional cap drops them and the card falls back to the first photo.
+	 */
+	keepImageNames?: string[];
 }
 
 interface CollectionProps {
@@ -136,9 +143,7 @@ export default async function vtexProductListShelf(
 		const data = await intelligentSearch<{ products: ProductVTEX[] }>(endpoint, params);
 
 		const vtexProducts = data.products ?? [];
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		let products = vtexProducts.map((p) => {
 			const fetchedSkus = ids ? new Set(ids) : null;
@@ -149,6 +154,7 @@ export default async function vtexProductListShelf(
 				baseUrl,
 				priceCurrency: "BRL",
 				shelfCompleteVariants: props.completeVariants,
+				keepImageNames: props.keepImageNames,
 			});
 		});
 

package/src/loaders/intelligentSearch/productListingPage.ts

@@ -4,6 +4,7 @@ import {
 	intelligentSearch,
 	type PageType,
 	pageTypesFromPath,
+	storefrontBaseUrl,
 	toFacetPath,
 } from "../../client";
 import { pickSku, toProduct } from "../../utils/transform";
@@ -441,9 +442,7 @@ export default async function vtexProductListingPage(props: PLPProps): Promise<a
 		const { products: vtexProducts, pagination, recordsFiltered } = productsResult;
 
 		// 3. Transform products using shared transform pipeline (same as deco-cx/apps)
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.com.br`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const schemaProducts = (vtexProducts as ProductVTEX[]).map((p) => {
 			const sku = pickSku(p);

package/src/loaders/intelligentSearch/suggestions.ts

@@ -4,7 +4,7 @@
  */
 
 import type { Product, Suggestion } from "@decocms/apps-commerce/types";
-import { getVtexConfig, intelligentSearch } from "../../client";
+import { getVtexConfig, intelligentSearch, storefrontBaseUrl } from "../../client";
 import { pickSku, toProduct } from "../../utils/transform";
 import type { Product as ProductVTEX } from "../../utils/types";
 
@@ -29,9 +29,7 @@ export default async function vtexSuggestions(props: SuggestionsProps): Promise<
 		}));
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const products: Product[] = (data.products ?? []).slice(0, props.count ?? 4).map((p) => {
 			const sku = pickSku(p);

package/src/loaders/legacy/relatedProductsLoader.ts

@@ -8,7 +8,7 @@
  */
 
 import type { Product } from "@decocms/apps-commerce/types";
-import { getVtexConfig, vtexCachedFetch } from "../../client";
+import { getVtexConfig, storefrontBaseUrl, vtexCachedFetch } from "../../client";
 import { resolveProductIdBySlug } from "../../utils/slugCache";
 import { pickSku, toProduct } from "../../utils/transform";
 import type { LegacyProduct } from "../../utils/types";
@@ -58,9 +58,7 @@ export default async function vtexRelatedProducts(
 		if (!related?.length) return [];
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		let result = related.slice(0, count).map((p) => {
 			const sku = pickSku(p);

package/src/loaders/productListFull.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Product } from "@decocms/apps-commerce/types";
-import { getVtexConfig, intelligentSearch, toFacetPath } from "../client";
+import { getVtexConfig, intelligentSearch, storefrontBaseUrl, toFacetPath } from "../client";
 import { pickSku, sortProducts, toProduct } from "../utils/transform";
 import type { Product as ProductVTEX } from "../utils/types";
 
@@ -135,9 +135,7 @@ export default async function vtexProductList(props: ProductListProps): Promise<
 		const data = await intelligentSearch<{ products: ProductVTEX[] }>(endpoint, params);
 
 		const vtexProducts = data.products ?? [];
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		let products = vtexProducts.map((p) => {
 			const fetchedSkus = ids ? new Set(ids) : null;

package/src/loaders/workflow/products.ts

@@ -4,7 +4,7 @@
  */
 
 import type { Product } from "@decocms/apps-commerce/types";
-import { getVtexConfig, intelligentSearch, toFacetPath } from "../../client";
+import { getVtexConfig, intelligentSearch, storefrontBaseUrl, toFacetPath } from "../../client";
 import { pickSku, toProduct } from "../../utils/transform";
 import type { Product as ProductVTEX } from "../../utils/types";
 
@@ -49,9 +49,7 @@ export default async function vtexWorkflowProducts(
 		const data = await intelligentSearch<{ products: ProductVTEX[] }>(endpoint, params);
 
 		const products = data.products ?? [];
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		return products.map((p) => {
 			const sku = pickSku(p);

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

@@ -0,0 +1,61 @@
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { configureVtex, storefrontBaseUrl } from "../../client";
+
+const ACCOUNT = { account: "examplestore" } as const;
+
+describe("storefrontBaseUrl", () => {
+	beforeEach(() => {
+		configureVtex({ ...ACCOUNT });
+	});
+
+	it("uses the origin of the request being served", () => {
+		configureVtex({ ...ACCOUNT, publicUrl: "https://secure.example.com/" });
+
+		const origin = RequestContext.run(new Request("https://www.example.com/camisas?page=2"), () =>
+			storefrontBaseUrl(),
+		);
+
+		expect(origin).toBe("https://www.example.com");
+	});
+
+	it("never returns the double-scheme origin a full publicUrl used to produce", () => {
+		// `https://${publicUrl}` on "https://secure.example.com/" parsed with
+		// host "https", so every product URL came out as https://https/<slug>/p.
+		configureVtex({ ...ACCOUNT, publicUrl: "https://secure.example.com/" });
+
+		const origin = storefrontBaseUrl();
+
+		expect(origin).toBe("https://secure.example.com");
+		expect(new URL("/camisa-paris/p", origin).href).toBe("https://secure.example.com/camisa-paris/p");
+	});
+
+	it("accepts a publicUrl stored without a scheme", () => {
+		configureVtex({ ...ACCOUNT, publicUrl: "secure.example.com" });
+
+		expect(storefrontBaseUrl()).toBe("https://secure.example.com");
+	});
+
+	it("falls back to the account host when publicUrl is absent", () => {
+		expect(storefrontBaseUrl()).toBe("https://examplestore.vtexcommercestable.com.br");
+	});
+
+	it("honours a configured domain in the account-host fallback", () => {
+		configureVtex({ ...ACCOUNT, domain: "com" });
+
+		expect(storefrontBaseUrl()).toBe("https://examplestore.vtexcommercestable.com");
+	});
+
+	it("falls back to the account host rather than publish an unparseable publicUrl", () => {
+		configureVtex({ ...ACCOUNT, publicUrl: "://" });
+
+		expect(storefrontBaseUrl()).toBe("https://examplestore.vtexcommercestable.com.br");
+	});
+
+	it("returns an origin with no trailing slash", () => {
+		configureVtex({ ...ACCOUNT, publicUrl: "https://secure.example.com/" });
+
+		expect(storefrontBaseUrl()).not.toMatch(/\/$/);
+	});
+});

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

@@ -749,6 +749,7 @@ describe("toProductShelf", () => {
 				},
 			],
 			variations: [{ name: "Cor", values: ["Preto"] }],
+			...overrides,
 		}) as any;
 
 	// Campanha is a PRODUCT specification (in specificationGroups), NOT a sku.variation.
@@ -818,6 +819,69 @@ describe("toProductShelf", () => {
 			expect.arrayContaining([expect.objectContaining({ name: "RefId", value: "REF-SKU1" })]),
 		);
 	});
+
+	// A real catalog registers the packshot and the colour thumbnail LAST:
+	// measured on a live store, `secondary` sits at index 6 and `color-thumbnail`
+	// at index 7 of 8. A card that selects either BY NAME gets nothing from a
+	// positional cap and silently falls back to the first photo (the model
+	// wearing the piece).
+	const labelledImages = [
+		...Array.from({ length: 6 }, (_, i) => ({
+			imageUrl: `https://img.com/photo-${i}.jpg`,
+			imageText: `Photo ${i}`,
+			imageLabel: `product-photo-${i}`,
+		})),
+		{ imageUrl: "https://img.com/still.jpg", imageText: "Still", imageLabel: "secondary" },
+		{ imageUrl: "https://img.com/thumb.jpg", imageText: "Thumb", imageLabel: "color-thumbnail" },
+	];
+	const skuWithLabels = () => makeSku({ images: labelledImages });
+	const labelledProduct = () => makeProduct({ items: [skuWithLabels()] });
+
+	it("keeps the 2-image cap when keepImageNames is absent", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, options);
+		expect(result.image?.map((i) => i.name)).toEqual(["product-photo-0", "product-photo-1"]);
+	});
+
+	it("keepImageNames adds back labelled images that fall outside the cap", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			keepImageNames: ["secondary", "color-thumbnail"],
+		});
+		expect(result.image?.map((i) => i.name)).toEqual([
+			"product-photo-0",
+			"product-photo-1",
+			"secondary",
+			"color-thumbnail",
+		]);
+	});
+
+	it("keepImageNames does not duplicate a label already inside the cap", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			keepImageNames: ["product-photo-0", "secondary"],
+		});
+		expect(result.image?.map((i) => i.name)).toEqual([
+			"product-photo-0",
+			"product-photo-1",
+			"secondary",
+		]);
+	});
+
+	it("keepImageNames listing a label the SKU does not have changes nothing", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			keepImageNames: ["vira"],
+		});
+		expect(result.image?.map((i) => i.name)).toEqual(["product-photo-0", "product-photo-1"]);
+	});
+
+	it("maxImages overrides the shelf default cap", () => {
+		const result = toProductShelf(labelledProduct(), skuWithLabels(), 0, {
+			...options,
+			maxImages: 3,
+		});
+		expect(result.image).toHaveLength(3);
+	});
 });
 
 // ---------------------------------------------------------------------------
@@ -1018,12 +1082,28 @@ describe("toProduct — displayedVariantId / maxImages", () => {
 		);
 	});
 
+	it("keepImageNames rescues a labelled image from the maxImages cap", () => {
+		const capped = toProduct(product, items[0], 0, {
+			...options,
+			maxImages: 2,
+			keepImageNames: ["label3"],
+		});
+		expect(capped.image?.map((i) => i.name)).toEqual(["label0", "label1", "label3"]);
+	});
+
+	it("keepImageNames without maxImages is a no-op — every image is already there", () => {
+		const before = toProduct(product, items[0], 0, options);
+		const after = toProduct(product, items[0], 0, { ...options, keepImageNames: ["label3"] });
+		expect(JSON.stringify(after)).toBe(JSON.stringify(before));
+	});
+
 	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,
+			keepImageNames: undefined,
 			priceSpecifications: undefined,
 		});
 		expect(JSON.stringify(after)).toBe(JSON.stringify(before));

package/src/utils/enrichment.ts

@@ -24,7 +24,7 @@
  */
 
 import type { Product, ProductLeaf } from "@decocms/apps-commerce/types";
-import { getVtexConfig, vtexFetch, vtexIOGraphQL } from "../client";
+import { getVtexConfig, storefrontBaseUrl, vtexFetch, vtexIOGraphQL } from "../client";
 import { listBrands } from "../loaders/brands";
 import { batch } from "./batch";
 import { withIsSimilarTo } from "./similars";
@@ -372,9 +372,7 @@ export function withKitItems(): ProductEnricher {
 		if (!productIDs.size) return products;
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const batches = batch([...productIDs], KIT_ITEMS_BATCH_SIZE);
 		const productsById = new Map<string, ProductLeaf>();
@@ -428,9 +426,7 @@ export function withVariants(): ProductEnricher {
 		if (!productIDs.size) return products;
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const batches = batch([...productIDs], VARIANTS_BATCH_SIZE);
 		const productsById = new Map<string, Product>();

package/src/utils/similars.ts

@@ -1,5 +1,5 @@
 import type { Product } from "@decocms/apps-commerce/types";
-import { getVtexConfig, vtexFetch } from "../client";
+import { getVtexConfig, storefrontBaseUrl, vtexFetch } from "../client";
 import { pickSku, toProduct } from "./transform";
 import type { LegacyProduct } from "./types";
 
@@ -18,9 +18,7 @@ export const withIsSimilarTo = async (product: Product): Promise<Product> => {
 		if (!rawSimilars?.length) return product;
 
 		const config = getVtexConfig();
-		const baseUrl = config.publicUrl
-			? `https://${config.publicUrl}`
-			: `https://${config.account}.vtexcommercestable.${config.domain ?? "com.br"}`;
+		const baseUrl = storefrontBaseUrl(config);
 
 		const similars = rawSimilars.map((p) => {
 			const sku = pickSku(p);

package/src/utils/transform.ts

@@ -168,9 +168,24 @@ export interface ProductOptions {
 	 * (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.
+	 * the named entries through {@link keepImageNames}.
 	 */
 	maxImages?: number;
+	/**
+	 * `imageLabel`s that survive the positional cap. An image whose label is
+	 * listed here is kept even when it falls outside {@link maxImages} (and
+	 * outside the shelf transform's own default cap), in its original order.
+	 *
+	 * This is the escape hatch the `maxImages` note asks for. A storefront that
+	 * picks the card image BY NAME — a "still"/packshot asset, a colour
+	 * thumbnail — cannot use a positional cap on its own: those assets are
+	 * registered last on the SKU, so any cap drops them and the card silently
+	 * falls back to the first photo. Pass the labels the card selects and the
+	 * payload stays lean everywhere else.
+	 *
+	 * Undefined (default) preserves the current behaviour byte for byte.
+	 */
+	keepImageNames?: string[];
 	/** 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. */
@@ -186,6 +201,28 @@ export interface ProductOptions {
 	shelfCompleteVariants?: boolean;
 }
 
+/**
+ * Apply the positional image cap, then add back the entries the caller selects
+ * by name. Order is preserved: the capped head first, then the named tail in
+ * catalog order. No cap means no work.
+ */
+const capImages = <I extends { imageLabel?: string | null }>(
+	images: I[] | null | undefined,
+	maxImages: number | undefined,
+	keepImageNames: string[] | undefined,
+): I[] | null | undefined => {
+	if (!images || typeof maxImages !== "number") return images;
+
+	const capped = images.slice(0, maxImages);
+
+	if (!keepImageNames?.length) return capped;
+
+	const keep = new Set(keepImageNames);
+	const named = images.slice(maxImages).filter((image) => keep.has(image.imageLabel ?? ""));
+
+	return named.length > 0 ? [...capped, ...named] : capped;
+};
+
 /** Returns first available sku */
 const findFirstAvailable = (items: Array<LegacySkuVTEX | SkuVTEX>) =>
 	items?.find((item) =>
@@ -495,8 +532,7 @@ export const toProduct = <P extends LegacyProductVTEX | ProductVTEX>(
 				} satisfies ProductGroup)
 			: undefined;
 
-	const cappedImages =
-		typeof options.maxImages === "number" ? images?.slice(0, options.maxImages) : images;
+	const cappedImages = capImages(images, options.maxImages, options.keepImageNames);
 	const finalImages = cappedImages?.map(({ imageUrl, imageText, imageLabel }) => {
 		const url = imagesByKey.get(getImageKey(imageUrl)) ?? imageUrl;
 		const alternateName = imageText || imageLabel || "";
@@ -659,6 +695,9 @@ const applyPriceSpecifications = (offers: Offer[], options: ProductOptions): Off
 			}))
 		: offers;
 
+/** Default positional image cap for the shelf transform (front + back). */
+const SHELF_MAX_IMAGES = 2;
+
 /** Property names commonly used by ProductCard/Shelf components */
 const SHELF_PROPERTY_NAMES = new Set([
 	"category",
@@ -674,7 +713,8 @@ const SHELF_PROPERTY_NAMES = new Set([
  * Lean product transform for shelf/card display. Same signature as toProduct().
  *
  * Differences from toProduct():
- * - Images: capped at 2 per SKU (front + back)
+ * - Images: capped at 2 per SKU (front + back), overridable via `maxImages`;
+ *   `keepImageNames` adds back labelled assets that fall outside the cap
  * - Offers: best seller only (in-stock first, then cheapest), stripped installments (keeps ListPrice, SalePrice, SRP, PIX, best no-interest)
  * - isVariantOf: single in-stock variant at level 0
  * - additionalProperty: filtered to known-used property names
@@ -690,9 +730,11 @@ export const toProductShelf = <P extends LegacyProductVTEX | ProductVTEX>(
 	const { productId, items, productReference } = product;
 	const { name, itemId: skuId } = sku;
 
-	// Images: cap at 2
+	// Images: cap at 2, keeping any label the caller selects by name
 	const rawImages = nonEmptyArray(sku.images);
-	const mappedImages = (rawImages ?? []).slice(0, 2).map(({ imageUrl, imageText, imageLabel }) => ({
+	const cappedImages =
+		capImages(rawImages, options.maxImages ?? SHELF_MAX_IMAGES, options.keepImageNames) ?? [];
+	const mappedImages = cappedImages.map(({ imageUrl, imageText, imageLabel }) => ({
 		"@type": "ImageObject" as const,
 		alternateName: imageText || imageLabel || "",
 		url: imageUrl,