@akinon/pz-theme 2.0.37-beta.0 → 2.0.37

package/src/blocks/product-gallery-block.tsx

@@ -0,0 +1,1523 @@
+'use client';
+
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { useOverlay } from '../hooks/use-overlay';
+import { getResponsiveValue, partAttrs } from '../utils';
+import { BlockRendererProps } from './block-renderer-registry';
+import { hasItemTemplate, ItemTemplateList } from './item-template';
+import {
+  DesignerPlaceholder,
+  ThemeProductImage,
+  getProductName,
+  pickProductField,
+  readToggle,
+  useThemeProduct
+} from './product-block-utils';
+
+const ALLOWED_ASPECT_RATIOS = ['1/1', '3/4', '4/3'];
+const ALLOWED_OBJECT_FITS = ['cover', 'contain', 'fill', 'scale-down'];
+const ALLOWED_THUMB_POSITIONS = ['bottom', 'top', 'left', 'right'];
+const ALLOWED_LAYOUTS = ['carousel', 'grid'];
+
+/** How far a one-finger drag must travel before it counts as a swipe. */
+const SWIPE_THRESHOLD_PX = 48;
+/** Below this a drag is a tap, not a gesture — thumbs wobble on every press. */
+const DRAG_SLOP_PX = 4;
+
+/**
+ * A merchant-authored image url, or '' when it is not one.
+ *
+ * The fallback photo and the high-resolution template are typed into the
+ * editor by a brand and both end up in `src`. Browsers strip whitespace and
+ * control characters while parsing a url, so a tab wedged into "java script:"
+ * still resolves to a live handler — the value is normalised the same way
+ * before it is judged.
+ */
+const sanitizeImageUrl = (value: unknown): string => {
+  const url = String(value ?? '').trim();
+  if (!url) return '';
+
+  const probe = url.replace(/[\u0000-\u0020]/g, '').toLowerCase();
+  if (/^(?:javascript|vbscript):/.test(probe)) return '';
+
+  // An inline raster image is a legitimate fallback; everything else in the
+  // data: scheme is markup, and svg is the one image type that carries markup
+  // with it.
+  if (probe.startsWith('data:')) {
+    return probe.startsWith('data:image/') &&
+      !probe.startsWith('data:image/svg')
+      ? url
+      : '';
+  }
+
+  return url;
+};
+
+const clamp = (value: number, min: number, max: number): number =>
+  Math.min(max, Math.max(min, value));
+
+const pointerDistance = (
+  a: { x: number; y: number },
+  b: { x: number; y: number }
+): number => Math.hypot(a.x - b.x, a.y - b.y);
+
+const clampColumns = (value: unknown, fallback: number, max: number): number => {
+  const numeric = Math.round(Number(value));
+
+  return Number.isFinite(numeric) && numeric >= 1
+    ? Math.min(numeric, max)
+    : fallback;
+};
+
+/**
+ * Accessible copy is authored, not hardcoded, so a non-English storefront can
+ * translate it. `{name}` / `{index}` / `{total}` are the bindings a brand gets.
+ */
+const fillTemplate = (
+  template: string,
+  values: { name: string; index: number; total: number }
+): string =>
+  template
+    .replace(/\{name\}/g, values.name)
+    .replace(/\{index\}/g, String(values.index))
+    .replace(/\{total\}/g, String(values.total));
+
+const ChevronIcon = ({ direction }: { direction: 'prev' | 'next' }) => (
+  <svg
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="1.8"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <path d={direction === 'prev' ? 'M15 5l-7 7 7 7' : 'M9 5l7 7-7 7'} />
+  </svg>
+);
+
+const CloseIcon = () => (
+  <svg
+    width="20"
+    height="20"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="1.8"
+    strokeLinecap="round"
+    aria-hidden="true"
+  >
+    <path d="M6 6l12 12M18 6L6 18" />
+  </svg>
+);
+
+/**
+ * Functional PDP block: main product image plus a thumbnail strip, or — when
+ * the grid layout is chosen — every product photo laid out in columns. The
+ * image CONTENT stays commerce-driven (product.images / product.image); the
+ * editor owns placement, aspect ratio, thumbnail visibility, the optional
+ * arrows and dots, and — through named parts — the styling of every piece.
+ *
+ * Enlargement is the second half of the block and every piece of it is off
+ * until a designer asks for it:
+ *
+ * - POINTER ZOOM magnifies a region under the cursor. Commerce sends ONE url
+ *   per photo, so by default the magnified layer is the SAME asset drawn
+ *   larger — it goes soft past the intrinsic resolution, and that is the
+ *   honest limit of one url. `highResTemplate` is how a brand asks its CDN for
+ *   a bigger one (`{url}` is the binding, e.g. `{url}?width=2000`); if that
+ *   url fails to load the photo falls back to the asset commerce sent, once,
+ *   remembered per url so a dead template cannot become a request loop.
+ * - The VIEWER is a full-screen dialog with every photo reachable from inside
+ *   it, an optional thumbnail rail, pinch-to-zoom, drag-to-pan and swipe. Its
+ *   close button is not a toggle: a viewer a phone user cannot leave is worse
+ *   than no viewer.
+ * - The FALLBACK photo covers the three cases that actually happen — a product
+ *   with no images, a url that 404s wherever it is first requested (the viewer
+ *   included, since lazy grid cells are often never fetched before it opens),
+ *   and an empty string in the payload.
+ *
+ * Parts: main, image, zoom-image, zoom-hint, viewer-trigger, viewer-backdrop,
+ * viewer, viewer-close, viewer-stage, viewer-image, viewer-arrow,
+ * viewer-counter, viewer-thumb-list, viewer-thumb, viewer-thumb-image, arrow,
+ * dot-list, dot, thumb-list, thumb, thumb-image, grid.
+ * Properties: layout, gridColumnsDesktop, gridColumnsMobile, showThumbs,
+ * aspectRatio, objectFit, thumbSize, thumbPosition, thumbLimit, thumbLabel,
+ * gap, showArrows, loopArrows, prevLabel, nextLabel, showDots, dotDirection,
+ * dotLabel, showCounter, counterLabel, enableZoom, zoomLevel, zoomHint,
+ * highResTemplate, enableViewer, viewerOpenLabel, viewerTitle,
+ * viewerCloseLabel, viewerShowArrows, viewerPrevLabel, viewerNextLabel,
+ * viewerShowThumbs, viewerThumbLabel, viewerShowCounter, viewerCounterLabel,
+ * viewerCloseOnEscape, viewerLockScroll, viewerGestures, viewerMaxZoom,
+ * fallbackImage, fallbackAlt.
+ */
+const ProductGalleryBlock = ({
+  block,
+  placeholderId,
+  sectionId,
+  selectedBlockId = null,
+  currentBreakpoint = 'desktop',
+  isDesigner = false
+}: BlockRendererProps) => {
+  const product = useThemeProduct();
+  const [activeIndex, setActiveIndex] = useState(0);
+  /** Which frame the pointer is magnifying, and where inside it, in percent. */
+  const [zoomPoint, setZoomPoint] = useState<{
+    index: number;
+    x: number;
+    y: number;
+  } | null>(null);
+  const [viewerOpen, setViewerOpen] = useState(false);
+  const [viewerScale, setViewerScale] = useState(1);
+  const [viewerPan, setViewerPan] = useState({ x: 0, y: 0 });
+  /** Photo urls the browser could not load, so the fallback takes over. */
+  const [failedUrls, setFailedUrls] = useState<Record<string, boolean>>({});
+  /** Photos whose high-resolution variant does not exist at the CDN. */
+  const [failedHighRes, setFailedHighRes] = useState<Record<string, boolean>>(
+    {}
+  );
+  // Only populated by the grid layout; the carousel has a single frame.
+  const cellRefs = useRef<Array<HTMLDivElement | null>>([]);
+  /** What opened the viewer, so focus can be handed back to exactly that. */
+  const openerRef = useRef<HTMLElement | null>(null);
+  /** Every hit area that can open the viewer, by photo index. */
+  const triggerRefs = useRef<Array<HTMLElement | null>>([]);
+  const gestureRef = useRef<{
+    distance: number;
+    scale: number;
+    panX: number;
+    panY: number;
+    x: number;
+    y: number;
+  } | null>(null);
+
+  const prop = (key: string, fallback: string) =>
+    String(
+      getResponsiveValue(block.properties?.[key], currentBreakpoint, fallback)
+    );
+
+  const layoutValue = prop('layout', 'carousel');
+  const layout = ALLOWED_LAYOUTS.includes(layoutValue)
+    ? layoutValue
+    : 'carousel';
+  const gridColumnsDesktop = clampColumns(
+    getResponsiveValue(
+      block.properties?.gridColumnsDesktop,
+      currentBreakpoint,
+      2
+    ),
+    2,
+    4
+  );
+  const gridColumnsMobile = clampColumns(
+    getResponsiveValue(block.properties?.gridColumnsMobile, currentBreakpoint, 1),
+    1,
+    3
+  );
+  const showThumbs = readToggle(
+    block.properties?.showThumbs,
+    currentBreakpoint,
+    true
+  );
+  const aspectRatioValue = String(
+    getResponsiveValue(block.properties?.aspectRatio, currentBreakpoint, '3/4')
+  );
+  const aspectRatio = ALLOWED_ASPECT_RATIOS.includes(aspectRatioValue)
+    ? aspectRatioValue
+    : '3/4';
+  const objectFitValue = prop('objectFit', 'cover');
+  const objectFit = (
+    ALLOWED_OBJECT_FITS.includes(objectFitValue) ? objectFitValue : 'cover'
+  ) as React.CSSProperties['objectFit'];
+  const thumbPositionValue = prop('thumbPosition', 'bottom');
+  const thumbPosition = ALLOWED_THUMB_POSITIONS.includes(thumbPositionValue)
+    ? thumbPositionValue
+    : 'bottom';
+  const thumbSize = Number(
+    getResponsiveValue(block.properties?.thumbSize, currentBreakpoint, 64)
+  );
+  const thumbLimit = Number(
+    getResponsiveValue(block.properties?.thumbLimit, currentBreakpoint, 0)
+  );
+  const gap = Number(
+    getResponsiveValue(block.properties?.gap, currentBreakpoint, 8)
+  );
+  const thumbLabel = prop('thumbLabel', '{name} image {index}');
+  const showArrows = readToggle(
+    block.properties?.showArrows,
+    currentBreakpoint,
+    false
+  );
+  const loopArrows = readToggle(
+    block.properties?.loopArrows,
+    currentBreakpoint,
+    true
+  );
+  const prevLabel = prop('prevLabel', 'Previous image');
+  const nextLabel = prop('nextLabel', 'Next image');
+  const showDots = readToggle(
+    block.properties?.showDots,
+    currentBreakpoint,
+    false
+  );
+  const showCounter = readToggle(
+    block.properties?.showCounter,
+    currentBreakpoint,
+    false
+  );
+  const counterLabel = prop('counterLabel', '{index} / {total}');
+  const dotDirectionValue = prop('dotDirection', 'row');
+  const dotDirection = dotDirectionValue === 'column' ? 'column' : 'row';
+  const dotLabel = prop('dotLabel', 'Go to image {index}');
+
+  const enableZoom = readToggle(
+    block.properties?.enableZoom,
+    currentBreakpoint,
+    false
+  );
+  const zoomLevelValue = Number(
+    getResponsiveValue(block.properties?.zoomLevel, currentBreakpoint, 2)
+  );
+  const zoomLevel = Number.isFinite(zoomLevelValue)
+    ? clamp(zoomLevelValue, 1, 6)
+    : 2;
+  const zoomHint = prop('zoomHint', '');
+  /**
+   * Ignored unless it carries the binding: without `{url}` every photo would
+   * resolve to the same fixed address, which is a broken gallery rather than a
+   * sharper one.
+   */
+  const highResTemplateValue = prop('highResTemplate', '');
+  const highResTemplate = highResTemplateValue.includes('{url}')
+    ? highResTemplateValue
+    : '';
+
+  const enableViewer = readToggle(
+    block.properties?.enableViewer,
+    currentBreakpoint,
+    false
+  );
+  const viewerOpenLabel = prop('viewerOpenLabel', 'Enlarge image');
+  const viewerTitle = prop('viewerTitle', 'Product images');
+  const viewerCloseLabel = prop('viewerCloseLabel', 'Close');
+  const viewerShowArrows = readToggle(
+    block.properties?.viewerShowArrows,
+    currentBreakpoint,
+    true
+  );
+  const viewerPrevLabel = prop('viewerPrevLabel', 'Previous image');
+  const viewerNextLabel = prop('viewerNextLabel', 'Next image');
+  const viewerShowThumbs = readToggle(
+    block.properties?.viewerShowThumbs,
+    currentBreakpoint,
+    false
+  );
+  const viewerThumbLabel = prop('viewerThumbLabel', '{name} image {index}');
+  const viewerShowCounter = readToggle(
+    block.properties?.viewerShowCounter,
+    currentBreakpoint,
+    false
+  );
+  const viewerCounterLabel = prop('viewerCounterLabel', '{index} / {total}');
+  const viewerCloseOnEscape = readToggle(
+    block.properties?.viewerCloseOnEscape,
+    currentBreakpoint,
+    true
+  );
+  const viewerLockScroll = readToggle(
+    block.properties?.viewerLockScroll,
+    currentBreakpoint,
+    true
+  );
+  const viewerGestures = readToggle(
+    block.properties?.viewerGestures,
+    currentBreakpoint,
+    true
+  );
+  const viewerMaxZoomValue = Number(
+    getResponsiveValue(block.properties?.viewerMaxZoom, currentBreakpoint, 3)
+  );
+  const viewerMaxZoom = Number.isFinite(viewerMaxZoomValue)
+    ? clamp(viewerMaxZoomValue, 1, 6)
+    : 3;
+
+  // Merchant-typed and headed for `src`, so it is judged before it is used.
+  const fallbackImage = sanitizeImageUrl(prop('fallbackImage', ''));
+  const fallbackAlt = prop('fallbackAlt', '');
+
+  /**
+   * Where focus goes when the hit area it came from is gone by the time the
+   * viewer closes. A PDP swaps the photo list under the gallery when the
+   * shopper picks another colour, and it can do that with the viewer still up,
+   * taking that cell with it — the handover then lands on a detached node and
+   * a keyboard shopper is dropped at the top of the document, nowhere near the
+   * gallery they were reading. Read at close rather than captured at open, so
+   * it reports whichever hit area is still on the page.
+   */
+  const survivingTriggerRef = useMemo(
+    () => ({
+      get current(): HTMLElement | null {
+        return triggerRefs.current.find((node) => node?.isConnected) ?? null;
+      }
+    }),
+    []
+  );
+
+  /**
+   * Focus, Escape, the scroll lock and the book of pointers still down are
+   * page-wide concerns rather than gallery ones — a page can carry a second
+   * gallery, or a filter panel, and every one of those pieces of state is
+   * shared. The primitive owns them so the overlays queue instead of fighting
+   * over focus, so the page's own overflow survives more than one holder, and
+   * so a finger still down when the viewer closes cannot stay booked for the
+   * rest of the session.
+   */
+  const overlay = useOverlay<HTMLDivElement>({
+    open: enableViewer && viewerOpen,
+    onClose: () => setViewerOpen(false),
+    isDesigner,
+    closeOnEscape: viewerCloseOnEscape,
+    lockScroll: viewerLockScroll,
+    returnFocusRef: openerRef,
+    fallbackFocusRef: survivingTriggerRef,
+    // The pinch baseline was measured from pointers that are gone, so it has
+    // to be dropped with them or the next visit starts mid-gesture.
+    onDeactivate: () => {
+      gestureRef.current = null;
+    }
+  });
+
+  const productImages = useMemo(() => {
+    const list = pickProductField<ThemeProductImage[]>(product, 'images');
+    const resolved = (Array.isArray(list) ? list : [])
+      .map((item) => ({
+        url: String(item?.url || item?.image || '').trim(),
+        alt: String(item?.alt || '').trim()
+      }))
+      .filter((item) => item.url);
+
+    if (resolved.length > 0) return resolved;
+
+    const single = String(
+      pickProductField<string>(product, 'image') || ''
+    ).trim();
+
+    return single ? [{ url: single, alt: '' }] : [];
+  }, [product]);
+
+  /**
+   * A product with no photos at all — the payload carried none, or carried
+   * only empty strings, which the memo above drops for the same reason. With
+   * no fallback authored the block behaves exactly as it always has: nothing
+   * on the storefront, a hint on the canvas. With one, the gallery is that
+   * single photo, so the page keeps its shape instead of collapsing.
+   *
+   * The identity is deliberate: without a fallback this IS `productImages`,
+   * so nothing downstream can tell the two apart.
+   */
+  const fallbackApplied = fallbackImage !== '' && productImages.length === 0;
+  const images = fallbackApplied
+    ? [{ url: fallbackImage, alt: fallbackAlt }]
+    : productImages;
+
+  const imageCount = images.length;
+
+  /**
+   * The grid has no hero, so "which photo am I on" is a scroll position. The
+   * band across the viewport middle is what the indicator reports; the effect
+   * does nothing at all in the carousel layout, which is why that path is
+   * unchanged.
+   */
+  useEffect(() => {
+    // Cells write their ref by index and nothing ever shortens the array, so a
+    // product with fewer photos than the last render can leave a detached node
+    // sitting past the end. It survives .filter(Boolean) and shifts every index
+    // the observer reports, which points the indicator at the wrong photo.
+    cellRefs.current.length = imageCount;
+
+    if (layout !== 'grid' || !showDots || imageCount < 2) return;
+    if (typeof IntersectionObserver === 'undefined') return;
+
+    const nodes = cellRefs.current.filter(Boolean) as HTMLElement[];
+    if (nodes.length === 0) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (!entry.isIntersecting) return;
+
+          const index = nodes.indexOf(entry.target as HTMLElement);
+          if (index >= 0) setActiveIndex(index);
+        });
+      },
+      { rootMargin: '-50% 0px -50% 0px', threshold: 0 }
+    );
+
+    nodes.forEach((node) => observer.observe(node));
+
+    return () => observer.disconnect();
+  }, [layout, showDots, imageCount]);
+
+  useEffect(() => {
+    // A photo the shopper zoomed into stays zoomed when they swipe to the next
+    // one otherwise, which lands them somewhere in the middle of a picture
+    // they have not seen yet. Closing resets it for the next open.
+    setViewerScale(1);
+    setViewerPan((current) =>
+      current.x === 0 && current.y === 0 ? current : { x: 0, y: 0 }
+    );
+  }, [activeIndex, viewerOpen]);
+
+  const hasCustomThumbs = hasItemTemplate(block, currentBreakpoint);
+
+  // Both layouts scope a stylesheet to their own instance, so the id is shared.
+  const galleryId = String(block.id || 'gallery').replace(/[^a-zA-Z0-9_-]/g, '');
+
+  if (images.length === 0) {
+    return isDesigner ? (
+      <DesignerPlaceholder
+        label="Product gallery (no product images)"
+        attribute="data-product-gallery"
+      />
+    ) : null;
+  }
+
+  const safeThumbSize = Number.isFinite(thumbSize) && thumbSize > 0 ? thumbSize : 64;
+  const safeGap = Number.isFinite(gap) && gap >= 0 ? gap : 8;
+  const safeIndex = Math.min(Math.max(activeIndex, 0), images.length - 1);
+  const activeImage = images[safeIndex];
+  const productName = getProductName(product) || 'Product';
+  // 0 means "all": a limit is only a cap, never a way to hide the strip.
+  const safeThumbLimit =
+    Number.isFinite(thumbLimit) && thumbLimit > 0
+      ? Math.min(thumbLimit, images.length)
+      : images.length;
+  const thumbImages = images.slice(0, safeThumbLimit);
+
+  const isSideThumbs = thumbPosition === 'left' || thumbPosition === 'right';
+  const rootDirection =
+    thumbPosition === 'top'
+      ? 'column-reverse'
+      : thumbPosition === 'left'
+      ? 'row-reverse'
+      : thumbPosition === 'right'
+      ? 'row'
+      : 'column';
+
+  const atFirst = safeIndex === 0;
+  const atLast = safeIndex === images.length - 1;
+  const step = (delta: number) => {
+    const next = safeIndex + delta;
+    if (next < 0) return loopArrows ? images.length - 1 : 0;
+    if (next > images.length - 1) return loopArrows ? 0 : images.length - 1;
+    return next;
+  };
+
+  // In the carousel a dot swaps the hero; in the grid every photo is already
+  // on the page, so it scrolls to the one the shopper asked for.
+  const selectImage = (index: number) => {
+    setActiveIndex(index);
+
+    if (layout !== 'grid') return;
+
+    const node = cellRefs.current[index];
+    if (node && typeof node.scrollIntoView === 'function') {
+      node.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }
+  };
+
+  /**
+   * What one frame actually shows.
+   *
+   * `isFallback` is true either because the whole gallery IS the fallback (the
+   * product carried no photo) or because this photo's url failed to load — the
+   * two are the same thing to a shopper and to a designer styling the `empty`
+   * state, so they resolve to one answer here.
+   *
+   * With no fallback authored this is the identity: the src and alt are the
+   * exact expressions the block has always rendered.
+   */
+  const resolveFrame = (image: { url: string; alt: string }) => {
+    const failed =
+      fallbackImage !== '' &&
+      image.url !== fallbackImage &&
+      failedUrls[image.url] === true;
+
+    return {
+      src: failed ? fallbackImage : image.url,
+      alt: failed
+        ? fallbackAlt || image.alt || productName
+        : image.alt || productName,
+      isFallback: failed || fallbackApplied
+    };
+  };
+
+  /**
+   * Commerce sends one url per photo. Without a template the magnified layer
+   * is that same asset drawn larger — sharp up to its intrinsic resolution and
+   * soft past it. With one, the brand's CDN is asked for a bigger rendition;
+   * a rendition that does not exist is remembered so the next paint asks for
+   * the original instead of retrying forever.
+   */
+  const highResFor = (url: string): string => {
+    if (!highResTemplate || !url || failedHighRes[url]) return url;
+
+    return sanitizeImageUrl(highResTemplate.replace(/\{url\}/g, url)) || url;
+  };
+
+  /**
+   * Only attached once a fallback exists, so a gallery without one carries no
+   * handler at all. The fallback's own failure is ignored: there is nothing
+   * further to fall back to, and re-recording it would loop.
+   */
+  const handleImageError = fallbackImage
+    ? (url: string) => {
+        if (!url || url === fallbackImage) return;
+        setFailedUrls((current) =>
+          current[url] ? current : { ...current, [url]: true }
+        );
+      }
+    : undefined;
+
+  const handleHighResError = (url: string) => {
+    if (!url) return;
+    setFailedHighRes((current) =>
+      current[url] ? current : { ...current, [url]: true }
+    );
+  };
+
+  /**
+   * The viewer is regularly the FIRST thing to request a photo: grid cells
+   * past the first row are lazy, so one the shopper never scrolled to has
+   * never been fetched, and the viewer's request is the first anything hears
+   * of a dead url. Its failure therefore has to walk both steps rather than
+   * only the first — drop the larger rendition when that is what was asked
+   * for, and otherwise give up on the url itself so the fallback takes over
+   * and the frame reports `empty`. Without the second step the viewer sits on
+   * a broken image for the rest of the visit.
+   *
+   * The magnifier needs none of this: it draws over a frame whose own photo
+   * has already been requested, so a dead url is recorded before the
+   * magnified layer is ever painted.
+   */
+  const handleViewerImageError = (url: string) => {
+    if (highResFor(url) !== url) {
+      handleHighResError(url);
+      return;
+    }
+
+    handleImageError?.(url);
+  };
+
+  const openViewer = (index: number, opener: HTMLElement | null) => {
+    openerRef.current = opener;
+    setActiveIndex(index);
+    setViewerOpen(true);
+  };
+
+  /**
+   * The transparent hit area that opens the viewer. A sibling rather than a
+   * wrapper: the photo keeps the exact element and part it has always had, and
+   * the arrows — which come after it in the frame — stay on top of it.
+   */
+  const viewerTrigger = (index: number) =>
+    enableViewer ? (
+      <button
+        type="button"
+        ref={(node) => {
+          triggerRefs.current[index] = node;
+        }}
+        data-product-gallery-viewer-open=""
+        {...partAttrs('viewer-trigger')}
+        aria-haspopup="dialog"
+        aria-label={fillTemplate(viewerOpenLabel, {
+          name: productName,
+          index: index + 1,
+          total: imageCount
+        })}
+        onClick={(event) => openViewer(index, event.currentTarget)}
+        style={{
+          position: 'absolute',
+          inset: 0,
+          width: '100%',
+          height: '100%',
+          padding: 0,
+          border: 'none',
+          background: 'transparent',
+          cursor: 'zoom-in'
+        }}
+      />
+    ) : null;
+
+  /**
+   * The magnified layer. A separate image rather than a transform on the photo
+   * itself: the hero keeps its own element untouched, and while the larger
+   * asset is still downloading the shopper looks at the photo underneath
+   * instead of a blank frame.
+   *
+   * Touch pointers are ignored — a finger has no hover, and a tap there is the
+   * shopper asking for the viewer, not for a magnifier stuck under their thumb.
+   */
+  const zoomLayer = (index: number, image: { url: string; alt: string }) => {
+    if (!enableZoom || !zoomPoint || zoomPoint.index !== index) return null;
+
+    const frame = resolveFrame(image);
+
+    return (
+      <img
+        data-product-gallery-zoom=""
+        {...partAttrs('zoom-image', { empty: frame.isFallback })}
+        src={highResFor(frame.src)}
+        alt=""
+        aria-hidden="true"
+        onError={() => handleHighResError(frame.src)}
+        style={{
+          position: 'absolute',
+          inset: 0,
+          width: '100%',
+          height: '100%',
+          objectFit,
+          transform: `scale(${zoomLevel})`,
+          transformOrigin: `${zoomPoint.x}% ${zoomPoint.y}%`,
+          // The magnifier must never eat the click that opens the viewer.
+          pointerEvents: 'none'
+        }}
+      />
+    );
+  };
+
+  /**
+   * Magnify is a hover affordance, and a finger has no hover — so with the
+   * viewer switched off there is no enlargement a touch shopper can reach at
+   * all. The hint would still be drawn over the photo, and a brand that
+   * authored "Tap to enlarge" would be promising something a tap cannot
+   * deliver. On a pointer that cannot hover it is therefore not drawn.
+   *
+   * A media rule rather than a runtime check: the block is server-rendered and
+   * hover capability is not knowable until the client, so deciding this in JS
+   * would mean shipping one answer and then correcting it.
+   */
+  const hintNeedsHoverGate = zoomHint !== '' && enableZoom && !enableViewer;
+
+  const hintHoverGateNode = hintNeedsHoverGate ? (
+    <style>
+      {`@media (hover:none){[data-product-gallery-id="${galleryId}"] [data-part="zoom-hint"]{display:none;}}`}
+    </style>
+  ) : null;
+
+  const hintNode =
+    (enableZoom || enableViewer) && zoomHint ? (
+      <span
+        data-product-gallery-zoom-hint=""
+        {...partAttrs('zoom-hint')}
+        aria-hidden="true"
+        style={{
+          position: 'absolute',
+          left: '8px',
+          bottom: '8px',
+          padding: '2px 8px',
+          background: 'var(--product-gallery-hint-bg, rgba(255, 255, 255, 0.85))',
+          color: 'inherit',
+          pointerEvents: 'none'
+        }}
+      >
+        {zoomHint}
+      </span>
+    ) : null;
+
+  /**
+   * Pointer zoom is a mouse affordance, and in the designer the author's
+   * pointer belongs to the canvas — magnifying under it would fight every
+   * attempt to select or drag the block. The `open` state is still reachable
+   * there through the editor's part-state preview.
+   */
+  const zoomHandlers = (index: number) =>
+    enableZoom && !isDesigner
+      ? {
+          onPointerMove: (event: React.PointerEvent<HTMLDivElement>) => {
+            if (event.pointerType === 'touch') return;
+
+            const rect = event.currentTarget.getBoundingClientRect();
+            if (!rect.width || !rect.height) return;
+
+            setZoomPoint({
+              index,
+              x: clamp(((event.clientX - rect.left) / rect.width) * 100, 0, 100),
+              y: clamp(((event.clientY - rect.top) / rect.height) * 100, 0, 100)
+            });
+          },
+          onPointerLeave: () => setZoomPoint(null)
+        }
+      : null;
+
+  /**
+   * Reported as `open` rather than `active`: the `active` state also carries
+   * the browser's own `:active`, so a brand styling "while the cursor is
+   * magnifying it" would get that styling on every mousedown — including on a
+   * gallery with magnify switched off entirely.
+   */
+  const isZooming = (index: number) =>
+    zoomPoint !== null && zoomPoint.index === index;
+
+  // A frame only needs a positioning context once something is layered over
+  // it; adding one unconditionally would change how a brand's own CSS lands.
+  const frameNeedsPosition = showArrows || enableViewer || enableZoom;
+
+  const arrowStyle = (side: 'left' | 'right'): React.CSSProperties => ({
+    position: 'absolute',
+    top: '50%',
+    [side]: '8px',
+    transform: 'translateY(-50%)',
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: '32px',
+    height: '32px',
+    padding: 0,
+    border: 'none',
+    borderRadius: '50%',
+    background: 'var(--product-gallery-arrow-bg, rgba(255, 255, 255, 0.85))',
+    color: 'inherit',
+    cursor: 'pointer'
+  });
+
+  // "2 / 10" — the position read as text rather than counted off a dot row.
+  // Both are allowed at once: a design that uses dots on desktop and the
+  // readout on a phone is a breakpoint choice, not an exclusive one.
+  const counterNode = showCounter && imageCount > 0 && (
+    <div
+      data-product-gallery-counter=""
+      {...partAttrs('counter')}
+      // Announced only when the shopper moves, not read out mid-swipe.
+      aria-live="polite"
+      aria-atomic="true"
+      style={{ textAlign: 'center' }}
+    >
+      {fillTemplate(counterLabel, {
+        name: productName,
+        index: safeIndex + 1,
+        total: imageCount
+      })}
+    </div>
+  );
+
+  const dotsNode = showDots && images.length > 1 && (
+    <div
+      data-product-gallery-dots=""
+      {...partAttrs('dot-list')}
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: '6px',
+        // Only written for the column indicator, so the existing dot row keeps
+        // the exact style attribute it has always rendered.
+        ...(dotDirection === 'column' ? { flexDirection: 'column' } : null)
+      }}
+    >
+      {images.map((image, index) => (
+        <button
+          key={`dot-${image.url}-${index}`}
+          type="button"
+          data-product-gallery-dot={index === safeIndex ? 'active' : 'default'}
+          {...partAttrs('dot', { selected: index === safeIndex })}
+          aria-label={fillTemplate(dotLabel, {
+            name: productName,
+            index: index + 1,
+            total: images.length
+          })}
+          aria-current={index === safeIndex}
+          onClick={() => selectImage(index)}
+          style={{
+            width: '8px',
+            height: '8px',
+            padding: 0,
+            border: 'none',
+            borderRadius: '50%',
+            cursor: 'pointer',
+            background:
+              index === safeIndex
+                ? 'currentColor'
+                : 'var(--product-gallery-dot, #d1d5db)'
+          }}
+        />
+      ))}
+    </div>
+  );
+
+  // A designer who marked a child as the thumbnail layout gets that layout
+  // repeated per image; otherwise the built-in thumbnail button renders.
+  const customThumbs = hasCustomThumbs ? (
+    <ItemTemplateList
+      block={block}
+      items={thumbImages.map((image, index) => ({
+        image: image.url,
+        alt: image.alt || productName,
+        name: productName,
+        index: index + 1,
+        total: images.length,
+        active: index === safeIndex
+      }))}
+      placeholderId={placeholderId}
+      sectionId={sectionId}
+      isDesigner={isDesigner}
+      selectedBlockId={selectedBlockId}
+      currentBreakpoint={currentBreakpoint}
+      designerPlaceholderCount={4}
+    />
+  ) : null;
+
+  const viewerFrame = resolveFrame(activeImage);
+
+  /**
+   * Pinch, pan and swipe share one pointer book: a phone reports each finger
+   * separately, and telling a two-finger pinch from a one-finger drag is only
+   * possible by counting the ones that are still down. The book belongs to the
+   * overlay because a finger still down when the viewer closes is never
+   * followed by a pointerup — kept per block, that id stayed booked for the
+   * rest of the session and every later one-finger drag was read as the second
+   * finger of a pinch that never started, so no swipe fired again.
+   */
+  const pointers = overlay.pointers;
+
+  const handleStagePointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
+    if (!viewerGestures) return;
+
+    // Tracking also takes pointer capture, which keeps the gesture alive when
+    // the finger leaves the stage — exactly what a fast swipe does — and the
+    // overlay hands every capture back when it closes.
+    pointers.track(event);
+
+    const points = pointers.points();
+
+    gestureRef.current = {
+      distance:
+        points.length >= 2 ? pointerDistance(points[0], points[1]) : 0,
+      scale: viewerScale,
+      panX: viewerPan.x,
+      panY: viewerPan.y,
+      x: event.clientX,
+      y: event.clientY
+    };
+  };
+
+  const handleStagePointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
+    const gesture = gestureRef.current;
+    if (!viewerGestures || !gesture || !pointers.has(event.pointerId)) return;
+
+    pointers.track(event);
+    const points = pointers.points();
+
+    if (points.length >= 2) {
+      const spread = pointerDistance(points[0], points[1]);
+      // The second finger can land a frame after the first, so the baseline is
+      // taken on the first move that actually has two.
+      if (!gesture.distance) {
+        gesture.distance = spread;
+        gesture.scale = viewerScale;
+        return;
+      }
+
+      setViewerScale(
+        clamp((gesture.scale * spread) / gesture.distance, 1, viewerMaxZoom)
+      );
+      return;
+    }
+
+    // One finger on a photo that is already magnified moves the photo; on one
+    // that is not, the same drag is on its way to being a swipe.
+    if (viewerScale > 1) {
+      setViewerPan({
+        x: gesture.panX + (event.clientX - gesture.x),
+        y: gesture.panY + (event.clientY - gesture.y)
+      });
+    }
+  };
+
+  const handleStagePointerUp = (event: React.PointerEvent<HTMLDivElement>) => {
+    const gesture = gestureRef.current;
+    pointers.release(event.pointerId);
+
+    if (!viewerGestures || !gesture) return;
+
+    if (pointers.size() > 0) {
+      // Coming out of a pinch with one finger still down: re-baseline against
+      // it so the photo does not jump when the drag continues.
+      const [remaining] = pointers.points();
+      gestureRef.current = {
+        distance: 0,
+        scale: viewerScale,
+        panX: viewerPan.x,
+        panY: viewerPan.y,
+        x: remaining.x,
+        y: remaining.y
+      };
+      return;
+    }
+
+    gestureRef.current = null;
+
+    const dx = event.clientX - gesture.x;
+    const dy = event.clientY - gesture.y;
+
+    if (Math.abs(dx) < DRAG_SLOP_PX && Math.abs(dy) < DRAG_SLOP_PX) return;
+    // A magnified photo is being panned, not swiped away.
+    if (viewerScale > 1 || images.length < 2) return;
+
+    if (Math.abs(dx) >= SWIPE_THRESHOLD_PX && Math.abs(dx) > Math.abs(dy)) {
+      setActiveIndex(step(dx < 0 ? 1 : -1));
+    }
+  };
+
+  /**
+   * The way back out of a pinch, and the only zoom a mouse has inside the
+   * viewer. Browsers synthesise `dblclick` from a double tap, so one handler
+   * serves both.
+   */
+  const handleStageDoubleClick = () => {
+    if (!viewerGestures) return;
+
+    setViewerScale((current) => (current > 1 ? 1 : viewerMaxZoom));
+    setViewerPan({ x: 0, y: 0 });
+  };
+
+  const viewerNode = enableViewer && viewerOpen && (
+    <div
+      data-product-gallery-viewer-root=""
+      style={{
+        position: 'fixed',
+        inset: 0,
+        zIndex: 1000,
+        display: 'flex'
+      }}
+    >
+      {/* The dark sheet, and only that. The dialog below is a full-viewport
+          sibling painted after it, so nothing a shopper taps ever reaches
+          this element — a dismiss handler here would be dead code that reads
+          like an affordance. The reachable ways out are the close button and
+          Escape; the stage cannot be one of them, because the first half of a
+          double-tap-to-zoom lands there. */}
+      <div
+        data-product-gallery-viewer-backdrop=""
+        {...partAttrs('viewer-backdrop', { open: true })}
+        style={{
+          position: 'absolute',
+          inset: 0,
+          background: 'var(--product-gallery-viewer-bg, rgba(0, 0, 0, 0.92))'
+        }}
+      />
+
+      <div
+        data-product-gallery-viewer=""
+        {...partAttrs('viewer', { open: true })}
+        /**
+         * Carries the ref and the `aria-modal` claim, which the primitive
+         * makes only where it is true: not in the designer, where focus is
+         * deliberately left with the author, and not for the lower of two open
+         * dialogs, which is not the one holding the page.
+         */
+        {...overlay.overlayProps}
+        role="dialog"
+        aria-label={viewerTitle}
+        // Focus target of last resort, before the close button mounts.
+        tabIndex={-1}
+        style={{
+          position: 'relative',
+          display: 'flex',
+          flexDirection: 'column',
+          margin: 'auto',
+          width: '100%',
+          height: '100%',
+          color: 'var(--product-gallery-viewer-color, #ffffff)',
+          outline: 'none'
+        }}
+      >
+        {/* Not a toggle. Every other way out is a designer choice, and a
+            viewer a phone user cannot leave is worse than no viewer. */}
+        <button
+          type="button"
+          data-product-gallery-viewer-close=""
+          {...partAttrs('viewer-close')}
+          aria-label={viewerCloseLabel}
+          onClick={() => setViewerOpen(false)}
+          style={{
+            position: 'absolute',
+            top: '12px',
+            right: '12px',
+            zIndex: 2,
+            display: 'inline-flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            width: '40px',
+            height: '40px',
+            padding: 0,
+            border: 'none',
+            background: 'transparent',
+            color: 'inherit',
+            cursor: 'pointer'
+          }}
+        >
+          <CloseIcon />
+        </button>
+
+        <div
+          data-product-gallery-viewer-stage=""
+          {...partAttrs('viewer-stage', { active: viewerScale > 1 })}
+          onPointerDown={handleStagePointerDown}
+          onPointerMove={handleStagePointerMove}
+          onPointerUp={handleStagePointerUp}
+          onPointerCancel={handleStagePointerUp}
+          onDoubleClick={handleStageDoubleClick}
+          style={{
+            position: 'relative',
+            flex: '1 1 auto',
+            minHeight: 0,
+            overflow: 'hidden',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            // Without this the browser claims the pinch and the drag for its
+            // own page zoom and scroll, and neither gesture ever arrives.
+            touchAction: viewerGestures ? 'none' : undefined
+          }}
+        >
+          <img
+            data-product-gallery-viewer-image=""
+            {...partAttrs('viewer-image', {
+              empty: viewerFrame.isFallback,
+              active: viewerScale > 1
+            })}
+            src={highResFor(viewerFrame.src)}
+            alt={viewerFrame.alt}
+            draggable={false}
+            onError={() => handleViewerImageError(viewerFrame.src)}
+            style={{
+              maxWidth: '100%',
+              maxHeight: '100%',
+              objectFit: 'contain',
+              transform: `translate(${viewerPan.x}px, ${viewerPan.y}px) scale(${viewerScale})`,
+              // The photo is the thing being dragged; the stage above owns the
+              // pointer so a drag that starts on the image is not two gestures.
+              pointerEvents: 'none',
+              userSelect: 'none'
+            }}
+          />
+
+          {viewerShowArrows && images.length > 1 && (
+            <>
+              <button
+                type="button"
+                data-product-gallery-viewer-arrow="prev"
+                {...partAttrs('viewer-arrow', {
+                  disabled: !loopArrows && atFirst
+                })}
+                aria-label={viewerPrevLabel}
+                disabled={!loopArrows && atFirst}
+                onClick={() => setActiveIndex(step(-1))}
+                style={arrowStyle('left')}
+              >
+                <ChevronIcon direction="prev" />
+              </button>
+              <button
+                type="button"
+                data-product-gallery-viewer-arrow="next"
+                {...partAttrs('viewer-arrow', {
+                  disabled: !loopArrows && atLast
+                })}
+                aria-label={viewerNextLabel}
+                disabled={!loopArrows && atLast}
+                onClick={() => setActiveIndex(step(1))}
+                style={arrowStyle('right')}
+              >
+                <ChevronIcon direction="next" />
+              </button>
+            </>
+          )}
+        </div>
+
+        {viewerShowCounter && (
+          <div
+            data-product-gallery-viewer-counter=""
+            {...partAttrs('viewer-counter')}
+            aria-live="polite"
+            aria-atomic="true"
+            style={{ flex: '0 0 auto', padding: '8px', textAlign: 'center' }}
+          >
+            {fillTemplate(viewerCounterLabel, {
+              name: productName,
+              index: safeIndex + 1,
+              total: imageCount
+            })}
+          </div>
+        )}
+
+        {viewerShowThumbs && images.length > 1 && (
+          <div
+            data-product-gallery-viewer-thumbs=""
+            {...partAttrs('viewer-thumb-list')}
+            style={{
+              display: 'flex',
+              flex: '0 0 auto',
+              gap: `${safeGap}px`,
+              padding: '8px',
+              justifyContent: 'center',
+              overflowX: 'auto',
+              flexWrap: 'nowrap'
+            }}
+          >
+            {images.map((image, index) => {
+              const thumbFrame = resolveFrame(image);
+
+              return (
+                <button
+                  key={`viewer-thumb-${image.url}-${index}`}
+                  type="button"
+                  data-product-gallery-viewer-thumb={
+                    index === safeIndex ? 'active' : 'default'
+                  }
+                  {...partAttrs('viewer-thumb', {
+                    selected: index === safeIndex,
+                    empty: thumbFrame.isFallback
+                  })}
+                  aria-label={fillTemplate(viewerThumbLabel, {
+                    name: productName,
+                    index: index + 1,
+                    total: imageCount
+                  })}
+                  aria-current={index === safeIndex}
+                  onClick={() => setActiveIndex(index)}
+                  style={{
+                    flex: '0 0 auto',
+                    width: `${safeThumbSize}px`,
+                    height: `${safeThumbSize}px`,
+                    padding: 0,
+                    cursor: 'pointer',
+                    overflow: 'hidden',
+                    background: 'transparent',
+                    border:
+                      index === safeIndex
+                        ? '1px solid var(--product-gallery-thumb-active, currentColor)'
+                        : '1px solid var(--product-gallery-thumb-border, rgba(255, 255, 255, 0.4))'
+                  }}
+                >
+                  <img
+                    src={thumbFrame.src}
+                    alt=""
+                    loading="lazy"
+                    {...partAttrs('viewer-thumb-image')}
+                    onError={
+                      handleImageError
+                        ? () => handleImageError(image.url)
+                        : undefined
+                    }
+                    style={{
+                      display: 'block',
+                      width: '100%',
+                      height: '100%',
+                      objectFit: 'cover'
+                    }}
+                  />
+                </button>
+              );
+            })}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+
+  if (layout === 'grid') {
+    // Column counts are block PROPERTIES, and properties resolve against the
+    // designer breakpoint only — on the storefront currentBreakpoint is always
+    // 'desktop'. A scoped rule with the same 1023px cutoff the theme CSS
+    // generator uses keeps real mobile viewports in sync with the editor.
+    const baseColumns =
+      currentBreakpoint === 'mobile' ? gridColumnsMobile : gridColumnsDesktop;
+
+    // The same authored row the thumbnail strip would repeat, given every
+    // photo: a designer who built one keeps it in this layout too.
+    const customCells = hasCustomThumbs ? (
+      <ItemTemplateList
+        block={block}
+        items={images.map((image, index) => ({
+          image: image.url,
+          alt: image.alt || productName,
+          name: productName,
+          index: index + 1,
+          total: images.length,
+          active: index === safeIndex
+        }))}
+        placeholderId={placeholderId}
+        sectionId={sectionId}
+        isDesigner={isDesigner}
+        selectedBlockId={selectedBlockId}
+        currentBreakpoint={currentBreakpoint}
+        designerPlaceholderCount={4}
+      />
+    ) : null;
+
+    // The indicator follows the scroll through refs only the built-in cells
+    // carry, and it scrolls to a cell the same way. An authored cell template
+    // exposes neither, so the dots there would render and do nothing at all —
+    // better no indicator than a dead one.
+    const gridDots = customCells ? null : dotsNode;
+    // Same reason as the dots: without the built-in cells there is nothing to
+    // observe, so the number would sit on 1 for the whole scroll.
+    const gridCounter = customCells ? null : counterNode;
+
+    return (
+      <div
+        data-product-gallery=""
+        data-product-gallery-layout="grid"
+        data-product-gallery-id={galleryId}
+        style={{
+          // The indicator is placed with the position controls on the dot row,
+          // which need a positioned ancestor to resolve against.
+          position:
+            (showDots || showCounter) && !customCells ? 'relative' : undefined,
+          width: '100%'
+        }}
+      >
+        <style>
+          {`[data-product-gallery-id="${galleryId}"] [data-part="grid"]{grid-template-columns:repeat(${baseColumns},minmax(0,1fr));}` +
+            `@media (max-width:1023px){[data-product-gallery-id="${galleryId}"] [data-part="grid"]{grid-template-columns:repeat(${gridColumnsMobile},minmax(0,1fr));}}`}
+        </style>
+
+        {hintHoverGateNode}
+
+        <div
+          {...partAttrs('grid')}
+          style={{ display: 'grid', gap: `${safeGap}px`, width: '100%' }}
+        >
+          {customCells ??
+            images.map((image, index) => {
+              const frame = resolveFrame(image);
+
+              return (
+              <div
+                key={`${image.url}-${index}`}
+                ref={(node) => {
+                  cellRefs.current[index] = node;
+                }}
+                data-product-gallery-cell={index === safeIndex ? 'active' : 'default'}
+                {...partAttrs('main', {
+                  selected: index === safeIndex,
+                  open: isZooming(index),
+                  empty: frame.isFallback
+                })}
+                {...zoomHandlers(index)}
+                style={{
+                  // Undefined until something is layered over the cell, so the
+                  // shipped grid keeps the exact style attribute it had.
+                  position: frameNeedsPosition ? 'relative' : undefined,
+                  aspectRatio,
+                  overflow: 'hidden',
+                  background: 'var(--product-gallery-bg, #f3f4f6)'
+                }}
+              >
+                <img
+                  src={frame.src}
+                  alt={frame.alt}
+                  {...partAttrs('image', { empty: frame.isFallback })}
+                  // The first rows are above the fold on a PDP grid.
+                  loading={index < baseColumns ? 'eager' : 'lazy'}
+                  onError={
+                    handleImageError
+                      ? () => handleImageError(image.url)
+                      : undefined
+                  }
+                  style={{
+                    display: 'block',
+                    width: '100%',
+                    height: '100%',
+                    objectFit
+                  }}
+                />
+
+                {zoomLayer(index, image)}
+                {viewerTrigger(index)}
+                {hintNode}
+              </div>
+              );
+            })}
+        </div>
+
+        {gridDots}
+        {gridCounter}
+        {viewerNode}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      data-product-gallery=""
+      data-product-gallery-thumb-position={thumbPosition}
+      // Only written when the hover gate above needs something to scope to, so
+      // a gallery without one keeps the exact attributes it has always had.
+      data-product-gallery-id={hintNeedsHoverGate ? galleryId : undefined}
+      style={{
+        display: 'flex',
+        flexDirection: rootDirection,
+        alignItems: isSideThumbs ? 'flex-start' : undefined,
+        gap: `${safeGap}px`,
+        width: '100%'
+      }}
+    >
+      {hintHoverGateNode}
+
+      <div
+        data-product-gallery-main=""
+        {...partAttrs('main', {
+          open: isZooming(safeIndex),
+          empty: viewerFrame.isFallback
+        })}
+        {...zoomHandlers(safeIndex)}
+        style={{
+          // Only a gallery with arrows, zoom or the viewer needs a positioning
+          // context; adding it unconditionally would change how a brand's own
+          // CSS lands.
+          position: frameNeedsPosition ? 'relative' : undefined,
+          width: isSideThumbs ? undefined : '100%',
+          flex: isSideThumbs ? '1 1 auto' : undefined,
+          minWidth: isSideThumbs ? 0 : undefined,
+          aspectRatio,
+          overflow: 'hidden',
+          background: 'var(--product-gallery-bg, #f3f4f6)'
+        }}
+      >
+        <img
+          key={activeImage.url}
+          src={viewerFrame.src}
+          alt={viewerFrame.alt}
+          {...partAttrs('image', { empty: viewerFrame.isFallback })}
+          // The PDP hero is above the fold, so the first frame is never lazy.
+          loading={safeIndex === 0 ? 'eager' : 'lazy'}
+          onError={
+            handleImageError
+              ? () => handleImageError(activeImage.url)
+              : undefined
+          }
+          style={{
+            display: 'block',
+            width: '100%',
+            height: '100%',
+            objectFit
+          }}
+        />
+
+        {zoomLayer(safeIndex, activeImage)}
+        {viewerTrigger(safeIndex)}
+        {hintNode}
+
+        {showArrows && images.length > 1 && (
+          <>
+            <button
+              type="button"
+              data-product-gallery-arrow="prev"
+              {...partAttrs('arrow', { disabled: !loopArrows && atFirst })}
+              aria-label={prevLabel}
+              disabled={!loopArrows && atFirst}
+              onClick={() => setActiveIndex(step(-1))}
+              style={arrowStyle('left')}
+            >
+              <ChevronIcon direction="prev" />
+            </button>
+            <button
+              type="button"
+              data-product-gallery-arrow="next"
+              {...partAttrs('arrow', { disabled: !loopArrows && atLast })}
+              aria-label={nextLabel}
+              disabled={!loopArrows && atLast}
+              onClick={() => setActiveIndex(step(1))}
+              style={arrowStyle('right')}
+            >
+              <ChevronIcon direction="next" />
+            </button>
+          </>
+        )}
+      </div>
+
+      {dotsNode}
+      {counterNode}
+
+      {showThumbs && images.length > 1 && (
+        <div
+          data-product-gallery-thumbs=""
+          {...partAttrs('thumb-list')}
+          style={{
+            display: 'flex',
+            flexDirection: isSideThumbs ? 'column' : 'row',
+            gap: `${safeGap}px`,
+            overflowX: isSideThumbs ? 'visible' : 'auto',
+            overflowY: isSideThumbs ? 'auto' : 'visible',
+            flexWrap: 'nowrap'
+          }}
+        >
+          {customThumbs ??
+            thumbImages.map((image, index) => {
+              const thumbFrame = resolveFrame(image);
+
+              return (
+              <button
+                key={`${image.url}-${index}`}
+                type="button"
+                data-product-gallery-thumb={
+                  index === safeIndex ? 'active' : 'default'
+                }
+                {...partAttrs('thumb', {
+                  selected: index === safeIndex,
+                  empty: thumbFrame.isFallback
+                })}
+                aria-label={fillTemplate(thumbLabel, {
+                  name: productName,
+                  index: index + 1,
+                  total: images.length
+                })}
+                aria-current={index === safeIndex}
+                onClick={() => setActiveIndex(index)}
+                style={{
+                  flex: '0 0 auto',
+                  width: `${safeThumbSize}px`,
+                  height: `${safeThumbSize}px`,
+                  padding: 0,
+                  cursor: 'pointer',
+                  overflow: 'hidden',
+                  background: 'transparent',
+                  border:
+                    index === safeIndex
+                      ? '1px solid var(--product-gallery-thumb-active, currentColor)'
+                      : '1px solid var(--product-gallery-thumb-border, #e5e7eb)'
+                }}
+              >
+                <img
+                  src={thumbFrame.src}
+                  alt=""
+                  loading="lazy"
+                  {...partAttrs('thumb-image', { empty: thumbFrame.isFallback })}
+                  onError={
+                    handleImageError
+                      ? () => handleImageError(image.url)
+                      : undefined
+                  }
+                  style={{
+                    display: 'block',
+                    width: '100%',
+                    height: '100%',
+                    objectFit: 'cover'
+                  }}
+                />
+              </button>
+              );
+            })}
+        </div>
+      )}
+
+      {viewerNode}
+    </div>
+  );
+};
+
+export default ProductGalleryBlock;