@snowcone-app/ui 0.1.42 → 0.2.0

package/src/composed/carousels/MobileProductCarousel.tsx

@@ -0,0 +1,1002 @@
+"use client";
+
+/**
+ * MobileProductCarousel - Production-grade carousel for product images and mockups
+ *
+ * A full-featured carousel optimized for e-commerce product display with:
+ * - Touch and mouse gesture support with drag feedback
+ * - Memory optimization (decode window) for iOS Safari
+ * - Real-time mockup URL integration via RealtimeProvider
+ * - Priority-based rendering via MockupPriorityProvider
+ * - Peek animation for UX education (teaches users they can swipe)
+ * - EnhancedImageViewer integration for pinch-to-zoom
+ *
+ * @example
+ * ```tsx
+ * // Basic usage within provider stack
+ * <ShopProvider>
+ *   <RealtimeProvider>
+ *     <MobileProductCarousel
+ *       images={heroImages}
+ *       productId="tshirt-001"
+ *       currentArtwork={artwork}
+ *     />
+ *   </RealtimeProvider>
+ * </ShopProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With controlled navigation
+ * const [index, setIndex] = useState(0);
+ *
+ * <MobileProductCarousel
+ *   images={images}
+ *   currentIndex={index}
+ *   onIndexChange={setIndex}
+ *   enablePeekAnimation={true}
+ *   enableZoom={true}
+ * />
+ * ```
+ */
+
+import React, {
+  useState,
+  useRef,
+  useEffect,
+  useCallback,
+  useMemo,
+  memo,
+} from "react";
+import type { CarouselImage } from "./types";
+import { EnhancedImageViewer } from "../zoom/EnhancedImageViewer";
+import { HeroProductImage } from "../HeroProductImage";
+import type { ArtworkData } from "@snowcone-app/sdk";
+import { useMockupPriorityOptional } from "../../patterns/MockupPriorityProvider";
+import { useRealtimeOptional } from "../../patterns/RealtimeProvider";
+
+export interface MobileProductCarouselProps {
+  /** Array of images to display in the carousel */
+  images: CarouselImage[];
+
+  /** Current active slide index (controlled) */
+  currentIndex?: number;
+
+  /** Callback when the active slide changes */
+  onIndexChange?: (index: number) => void;
+
+  /** Additional CSS classes */
+  className?: string;
+
+  /** Current artwork for mockup generation */
+  currentArtwork?: ArtworkData;
+
+  /** Product ID for mockup generation */
+  productId?: string;
+
+  /**
+   * Show peek animation after N page views without swiping.
+   * Teaches users they can swipe through images.
+   * @default true
+   */
+  enablePeekAnimation?: boolean;
+
+  /**
+   * Enable tap-to-zoom with EnhancedImageViewer.
+   * @default true
+   */
+  enableZoom?: boolean;
+
+  /**
+   * Show progress indicators below the carousel.
+   * @default true
+   */
+  showIndicators?: boolean;
+
+  /**
+   * Callback when the zoom viewer opens or closes.
+   */
+  onZoomChange?: (isZoomed: boolean) => void;
+
+  /**
+   * Callback for sticky hero context integration.
+   * When provided, the carousel reports its state to the parent layout.
+   */
+  stickyHeroContext?: {
+    isStuck?: boolean;
+    shouldHideDots?: boolean;
+    setCarouselIndicator?: (indicator: React.ReactNode) => void;
+  };
+
+  /**
+   * Explicit mockup width in device pixels to pass to HeroProductImage.
+   * Use when the container uses object-fit: cover with a taller-than-natural
+   * aspect ratio (e.g. ScrollHero) so the mockup is requested at the
+   * cover-adjusted resolution instead of just the container CSS width.
+   */
+  mockupWidth?: number;
+
+  /**
+   * Fires when `HeroProductImage` finishes generating a mockup URL for a
+   * given mockupId — covers the static (SDK-built) URL on first load AND
+   * any realtime URL that subsequently replaces it. Lets the parent share
+   * the URL with sibling surfaces (e.g. the mobile editor preview) that
+   * would otherwise have to wait for a realtime event to populate the
+   * provider's mockup cache themselves.
+   */
+  onMockupUrlGenerated?: (mockupId: string, url: string) => void;
+}
+
+/**
+ * MobileProductCarousel - Memoized for performance
+ *
+ * Prevents re-renders from parent state changes when props are stable.
+ * Critical for preventing HeroProductImage children from re-rendering unnecessarily.
+ */
+export const MobileProductCarousel = memo(function MobileProductCarousel({
+  images,
+  currentIndex = 0,
+  onIndexChange,
+  className = "",
+  currentArtwork,
+  productId,
+  enablePeekAnimation = true,
+  enableZoom = true,
+  showIndicators = true,
+  onZoomChange,
+  stickyHeroContext,
+  mockupWidth,
+  onMockupUrlGenerated,
+}: MobileProductCarouselProps) {
+  const [activeIndex, setActiveIndex] = useState(currentIndex);
+  const [touchStart, setTouchStart] = useState<{ x: number; y: number } | null>(
+    null
+  );
+  const [touchEnd, setTouchEnd] = useState<{ x: number; y: number } | null>(
+    null
+  );
+  const [showImageViewer, setShowImageViewer] = useState(false);
+  const [viewerKey, setViewerKey] = useState(0);
+  const [isDragging, setIsDragging] = useState(false);
+  const [dragOffset, setDragOffset] = useState(0);
+  const [isTransitioning, setIsTransitioning] = useState(false);
+  const [isHorizontalSwipe, setIsHorizontalSwipe] = useState<boolean | null>(
+    null
+  );
+  const [isPeeking, setIsPeeking] = useState(false);
+  const [isPeekReturning, setIsPeekReturning] = useState(false);
+  const carouselRef = useRef<HTMLDivElement>(null);
+  const indicatorRef = useRef<HTMLDivElement>(null);
+  const touchStartRef = useRef<{ x: number; y: number; time: number } | null>(
+    null
+  );
+  const horizontalGestureRef = useRef(false);
+  const hasShownPeekRef = useRef(false);
+  const hasSwipedThisSessionRef = useRef(false);
+
+  // Cache for generated mockup URLs - persists across unmount/remount cycles
+  // This is critical for the decode window optimization to work correctly
+  const generatedUrlsRef = useRef<Map<string, string>>(new Map());
+
+  // Track previous artwork to detect changes and clear stale cache
+  const prevArtworkSrcRef = useRef<string | undefined>(currentArtwork?.src);
+
+  // Clear generated URLs cache when artwork changes
+  // These cached URLs were for the old artwork and are now stale
+  useEffect(() => {
+    if (currentArtwork?.src !== prevArtworkSrcRef.current) {
+      generatedUrlsRef.current.clear();
+      prevArtworkSrcRef.current = currentArtwork?.src;
+    }
+  }, [currentArtwork?.src]);
+
+  // Stable ref so updates to the prop don't invalidate handleUrlGenerated
+  // (which would recreate HeroProductImage's onUrlGenerated each render and
+  // trip its lastUrlRef-based dedup, retriggering generation churn).
+  const onMockupUrlGeneratedRef = useRef(onMockupUrlGenerated);
+  onMockupUrlGeneratedRef.current = onMockupUrlGenerated;
+
+  // Callback to collect URLs generated by HeroProductImage
+  const handleUrlGenerated = useCallback((mockupId: string, url: string) => {
+    generatedUrlsRef.current.set(mockupId, url);
+    onMockupUrlGeneratedRef.current?.(mockupId, url);
+  }, []);
+
+  // Context integration (optional - works with or without providers)
+  const isStuck = stickyHeroContext?.isStuck ?? false;
+  const shouldHideDots = stickyHeroContext?.shouldHideDots ?? false;
+
+  // Priority context for mobile carousel mode
+  const priorityContext = useMockupPriorityOptional();
+
+  // Realtime context for getting updated mockup URLs from centralized cache
+  const realtimeContext = useRealtimeOptional();
+
+  // Subscribe to mockup result updates to trigger re-renders when URLs change
+  const [urlUpdateCounter, setUrlUpdateCounter] = useState(0);
+  useEffect(() => {
+    if (!realtimeContext?.subscribeMockupResults) return;
+
+    const unsubscribe = realtimeContext.subscribeMockupResults(() => {
+      setUrlUpdateCounter((c) => c + 1);
+    });
+
+    return unsubscribe;
+  }, [realtimeContext?.subscribeMockupResults]);
+
+  // Get all mockup IDs for this carousel
+  const mockupIds = useMemo(() => {
+    return images
+      .filter((img) => img.isRealMockup && img.mockupId)
+      .map((img) => img.mockupId!);
+  }, [images]);
+
+  // Get realtime URLs from centralized cache
+  const realtimeMockupUrls = useMemo(() => {
+    if (!realtimeContext?.getMockupUrls || mockupIds.length === 0) {
+      return {};
+    }
+    return realtimeContext.getMockupUrls(mockupIds);
+  }, [realtimeContext?.getMockupUrls, mockupIds, urlUpdateCounter]);
+
+  // Create enhanced images array with realtime URLs substituted for mockups
+  const imagesWithRealtimeUrls = useMemo(() => {
+    return images.map((img) => {
+      if (img.isRealMockup && img.mockupId && realtimeMockupUrls[img.mockupId]) {
+        return {
+          ...img,
+          src: realtimeMockupUrls[img.mockupId],
+        };
+      }
+      return img;
+    });
+  }, [images, realtimeMockupUrls]);
+
+  // Minimum distance required to register a swipe
+  const minSwipeDistance = 50;
+
+  useEffect(() => {
+    setActiveIndex(currentIndex);
+  }, [currentIndex]);
+
+  // Report carousel index to priority context for mobile-optimized priority
+  useEffect(() => {
+    if (!priorityContext) return;
+
+    const realMockups = images
+      .map((img, idx) => ({ img, originalIdx: idx }))
+      .filter(({ img }) => img.isRealMockup && img.mockupId);
+
+    const mockupIdsList = realMockups.map(({ img }) => img.mockupId!);
+
+    if (mockupIdsList.length > 0) {
+      const currentImage = images[activeIndex];
+      let mockupIndex = 0;
+
+      if (currentImage?.isRealMockup && currentImage?.mockupId) {
+        mockupIndex = realMockups.findIndex(
+          ({ originalIdx }) => originalIdx === activeIndex
+        );
+        if (mockupIndex === -1) mockupIndex = 0;
+      } else {
+        let minDistance = Infinity;
+        realMockups.forEach(({ originalIdx }, idx) => {
+          const distance = Math.abs(originalIdx - activeIndex);
+          if (distance < minDistance) {
+            minDistance = distance;
+            mockupIndex = idx;
+          }
+        });
+      }
+
+      priorityContext.reportMobileCarouselIndex(mockupIndex, mockupIdsList);
+    }
+
+    return () => {
+      priorityContext.clearMobileCarouselMode?.();
+    };
+  }, [priorityContext, activeIndex, images]);
+
+  // Counter-scale indicator width for HeroZoomLayout compatibility
+  useEffect(() => {
+    const indicator = indicatorRef.current;
+    if (!indicator) return;
+
+    let ticking = false;
+
+    const updateIndicatorWidth = () => {
+      const heroContainer = document.querySelector(
+        "[data-hero-zoom-container]"
+      );
+
+      if (!heroContainer) {
+        indicator.style.width = "";
+        indicator.style.left = "";
+        indicator.style.transform = "";
+        indicator.style.transformOrigin = "";
+        ticking = false;
+        return;
+      }
+
+      const scaleStr = getComputedStyle(heroContainer).scale;
+      const currentScale = parseFloat(scaleStr) || 1;
+      const counterScale = 1 / currentScale;
+
+      indicator.style.width = "100vw";
+      indicator.style.left = "50%";
+      indicator.style.transformOrigin = "center bottom";
+      indicator.style.transform = `translateX(-50%) scale(${counterScale})`;
+      ticking = false;
+    };
+
+    const onScroll = () => {
+      if (!ticking) {
+        requestAnimationFrame(updateIndicatorWidth);
+        ticking = true;
+      }
+    };
+
+    updateIndicatorWidth();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", updateIndicatorWidth);
+
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", updateIndicatorWidth);
+    };
+  }, []);
+
+  // Swipe education tracking
+  const SWIPE_TRACKING_KEY = "carousel-swipe-tracking";
+  const PDP_VIEWS_BEFORE_PEEK = 10;
+
+  const getSwipeTracking = useCallback(() => {
+    try {
+      const stored = localStorage.getItem(SWIPE_TRACKING_KEY);
+      if (stored) {
+        return JSON.parse(stored) as {
+          viewsWithoutSwipe: number;
+          hasEverSwiped: boolean;
+        };
+      }
+    } catch {}
+    return { viewsWithoutSwipe: 0, hasEverSwiped: false };
+  }, []);
+
+  const recordSwipe = useCallback(() => {
+    if (hasSwipedThisSessionRef.current) return;
+    hasSwipedThisSessionRef.current = true;
+    try {
+      localStorage.setItem(
+        SWIPE_TRACKING_KEY,
+        JSON.stringify({
+          viewsWithoutSwipe: 0,
+          hasEverSwiped: true,
+        })
+      );
+    } catch {}
+  }, []);
+
+  // Peek animation on mount
+  useEffect(() => {
+    if (!enablePeekAnimation || images.length <= 1) return;
+
+    const tracking = getSwipeTracking();
+    const newViewCount = tracking.viewsWithoutSwipe + 1;
+
+    try {
+      localStorage.setItem(
+        SWIPE_TRACKING_KEY,
+        JSON.stringify({
+          ...tracking,
+          viewsWithoutSwipe: newViewCount,
+        })
+      );
+    } catch {}
+
+    const shouldShowPeek =
+      !tracking.hasEverSwiped && newViewCount >= PDP_VIEWS_BEFORE_PEEK;
+
+    if (!shouldShowPeek) return;
+
+    hasShownPeekRef.current = false;
+
+    let returnTimeout: NodeJS.Timeout;
+    let clearTimeout_: NodeJS.Timeout;
+
+    const startDelay = setTimeout(() => {
+      if (hasShownPeekRef.current) return;
+      hasShownPeekRef.current = true;
+
+      setIsPeeking(true);
+      setIsTransitioning(true);
+      setDragOffset(4);
+
+      returnTimeout = setTimeout(() => {
+        setIsPeeking(false);
+        setIsPeekReturning(true);
+        setDragOffset(0);
+
+        clearTimeout_ = setTimeout(() => {
+          setIsPeekReturning(false);
+          setIsTransitioning(false);
+        }, 400);
+      }, 500);
+    }, 800);
+
+    return () => {
+      clearTimeout(startDelay);
+      clearTimeout(returnTimeout);
+      clearTimeout(clearTimeout_);
+    };
+  }, [images.length, getSwipeTracking, enablePeekAnimation]);
+
+  const wasTapRef = useRef(false);
+
+  const handleImageTap = useCallback(() => {
+    if (!enableZoom) return;
+    setViewerKey((prev) => prev + 1);
+    setShowImageViewer(true);
+    onZoomChange?.(true);
+  }, [enableZoom, onZoomChange]);
+
+  // Shared drag calculation logic
+  const calculateDragOffset = useCallback(
+    (startX: number, currentX: number, containerWidth: number) => {
+      const distance = startX - currentX;
+      const offsetPercent = (distance / containerWidth) * 100;
+
+      const isAtStart = activeIndex === 0;
+      const isAtEnd = activeIndex === images.length - 1;
+      const isDraggingLeftDir = offsetPercent > 0;
+      const isDraggingRightDir = offsetPercent < 0;
+
+      let clampedOffset = offsetPercent;
+
+      if (isAtStart && isDraggingRightDir) {
+        clampedOffset = Math.max(-25, offsetPercent * 0.5);
+      } else if (isAtStart && isDraggingLeftDir) {
+        clampedOffset = Math.min(25, offsetPercent * 0.5);
+      } else if (isAtEnd && isDraggingLeftDir) {
+        clampedOffset = Math.min(25, offsetPercent * 0.5);
+      } else if (isAtEnd && isDraggingRightDir) {
+        clampedOffset = Math.max(-25, offsetPercent * 0.5);
+      } else {
+        const maxDrag = 50;
+        clampedOffset = Math.max(-maxDrag, Math.min(maxDrag, offsetPercent));
+      }
+
+      return clampedOffset;
+    },
+    [activeIndex, images.length]
+  );
+
+  // Shared swipe completion logic
+  const handleSwipeEnd = useCallback(
+    (startX: number, endX: number, containerWidth: number) => {
+      const distance = startX - endX;
+      const distancePercent = (Math.abs(distance) / containerWidth) * 100;
+      const snapThreshold = 2;
+
+      const isLeftSwipe = distance > 0 && distancePercent > snapThreshold;
+      const isRightSwipe = distance < 0 && distancePercent > snapThreshold;
+
+      const canGoNext = activeIndex < images.length - 1;
+      const canGoPrev = activeIndex > 0;
+
+      if (isLeftSwipe && canGoNext) {
+        recordSwipe();
+        setIsTransitioning(true);
+        setActiveIndex(activeIndex + 1);
+        setDragOffset(0);
+        onIndexChange?.(activeIndex + 1);
+        setTimeout(() => setIsTransitioning(false), 300);
+      } else if (isRightSwipe && canGoPrev) {
+        recordSwipe();
+        setIsTransitioning(true);
+        setActiveIndex(activeIndex - 1);
+        setDragOffset(0);
+        onIndexChange?.(activeIndex - 1);
+        setTimeout(() => setIsTransitioning(false), 300);
+      } else {
+        setIsTransitioning(true);
+        setDragOffset(0);
+        setTimeout(() => setIsTransitioning(false), 300);
+      }
+    },
+    [activeIndex, images.length, onIndexChange, recordSwipe]
+  );
+
+  // Touch handlers
+  useEffect(() => {
+    const container = carouselRef.current;
+    if (!container) return;
+
+    const handleTouchStart = (e: TouchEvent) => {
+      setIsPeeking(false);
+      setDragOffset(0);
+
+      const touch = e.touches[0];
+      touchStartRef.current = {
+        x: touch.clientX,
+        y: touch.clientY,
+        time: Date.now(),
+      };
+      horizontalGestureRef.current = false;
+      wasTapRef.current = true;
+      setTouchStart({ x: touch.clientX, y: touch.clientY });
+      setTouchEnd(null);
+      setIsDragging(false);
+      setIsTransitioning(false);
+      setIsHorizontalSwipe(null);
+    };
+
+    const handleTouchMove = (e: TouchEvent) => {
+      if (!touchStartRef.current) return;
+
+      const touch = e.touches[0];
+      const deltaX = Math.abs(touch.clientX - touchStartRef.current.x);
+      const deltaY = Math.abs(touch.clientY - touchStartRef.current.y);
+
+      if (deltaX > 10 || deltaY > 10) {
+        wasTapRef.current = false;
+      }
+
+      if (
+        !horizontalGestureRef.current &&
+        deltaX > 1 &&
+        deltaX > deltaY * 0.75
+      ) {
+        horizontalGestureRef.current = true;
+        setIsHorizontalSwipe(true);
+        setIsDragging(true);
+        e.preventDefault();
+        e.stopPropagation();
+      }
+
+      if (horizontalGestureRef.current) {
+        e.preventDefault();
+        e.stopPropagation();
+
+        setTouchEnd({ x: touch.clientX, y: touch.clientY });
+        const containerWidth = container?.offsetWidth || 0;
+        const clampedOffset = calculateDragOffset(
+          touchStartRef.current.x,
+          touch.clientX,
+          containerWidth
+        );
+        setDragOffset(clampedOffset);
+      }
+    };
+
+    const handleTouchEnd = () => {
+      // Tap detection moved to React onClick handler for iOS Safari compatibility
+      // wasTapRef.current is still set/cleared here for onClick to check
+
+      if (!touchStartRef.current) {
+        horizontalGestureRef.current = false;
+        setIsDragging(false);
+        setDragOffset(0);
+        setIsHorizontalSwipe(null);
+        return;
+      }
+
+      if (horizontalGestureRef.current && touchEnd) {
+        const containerWidth = container?.offsetWidth || 0;
+        handleSwipeEnd(touchStartRef.current.x, touchEnd.x, containerWidth);
+      }
+
+      touchStartRef.current = null;
+      horizontalGestureRef.current = false;
+      // Don't reset wasTapRef here - onClick fires AFTER touchend and needs to read it
+      setIsDragging(false);
+      setIsHorizontalSwipe(null);
+      if (!horizontalGestureRef.current) {
+        setDragOffset(0);
+      }
+    };
+
+    container.addEventListener("touchstart", handleTouchStart, {
+      passive: true,
+    });
+    container.addEventListener("touchmove", handleTouchMove, {
+      passive: false,
+    });
+    container.addEventListener("touchend", handleTouchEnd, { passive: true });
+
+    return () => {
+      container.removeEventListener("touchstart", handleTouchStart);
+      container.removeEventListener("touchmove", handleTouchMove);
+      container.removeEventListener("touchend", handleTouchEnd);
+    };
+  }, [
+    activeIndex,
+    touchEnd,
+    images.length,
+    onIndexChange,
+    calculateDragOffset,
+    handleSwipeEnd,
+    handleImageTap,
+  ]);
+
+  // Mouse handlers for desktop
+  const mouseStartRef = useRef<{ x: number; y: number; time: number } | null>(
+    null
+  );
+  const isMouseDraggingRef = useRef(false);
+
+  useEffect(() => {
+    const container = carouselRef.current;
+    if (!container) return;
+
+    const handleMouseDown = (e: MouseEvent) => {
+      if (e.button !== 0) return;
+
+      setIsPeeking(false);
+      setDragOffset(0);
+
+      mouseStartRef.current = {
+        x: e.clientX,
+        y: e.clientY,
+        time: Date.now(),
+      };
+      isMouseDraggingRef.current = false;
+      wasTapRef.current = true;
+      setIsDragging(false);
+      setIsTransitioning(false);
+    };
+
+    const handleMouseMove = (e: MouseEvent) => {
+      if (!mouseStartRef.current) return;
+
+      const deltaX = Math.abs(e.clientX - mouseStartRef.current.x);
+      const deltaY = Math.abs(e.clientY - mouseStartRef.current.y);
+
+      if (deltaX > 5 || deltaY > 5) {
+        wasTapRef.current = false;
+      }
+
+      if (!isMouseDraggingRef.current && deltaX > 5 && deltaX > deltaY) {
+        isMouseDraggingRef.current = true;
+        setIsDragging(true);
+        e.preventDefault();
+      }
+
+      if (isMouseDraggingRef.current) {
+        e.preventDefault();
+        const containerWidth = container?.offsetWidth || 0;
+        const clampedOffset = calculateDragOffset(
+          mouseStartRef.current.x,
+          e.clientX,
+          containerWidth
+        );
+        setDragOffset(clampedOffset);
+      }
+    };
+
+    const handleMouseUp = (e: MouseEvent) => {
+      // Tap detection moved to React onClick handler for consistency with touch
+      // wasTapRef.current is still set/cleared here for onClick to check
+
+      if (!mouseStartRef.current) {
+        isMouseDraggingRef.current = false;
+        setIsDragging(false);
+        setDragOffset(0);
+        return;
+      }
+
+      if (isMouseDraggingRef.current) {
+        const containerWidth = container?.offsetWidth || 0;
+        handleSwipeEnd(mouseStartRef.current.x, e.clientX, containerWidth);
+      }
+
+      mouseStartRef.current = null;
+      isMouseDraggingRef.current = false;
+      // Don't reset wasTapRef here - onClick fires AFTER mouseup and needs to read it
+      setIsDragging(false);
+    };
+
+    const handleMouseLeave = () => {
+      if (isMouseDraggingRef.current) {
+        setIsTransitioning(true);
+        setDragOffset(0);
+        setTimeout(() => setIsTransitioning(false), 300);
+      }
+      mouseStartRef.current = null;
+      isMouseDraggingRef.current = false;
+      // wasTapRef reset happens on next mousedown/touchstart
+      setIsDragging(false);
+    };
+
+    container.addEventListener("mousedown", handleMouseDown);
+    container.addEventListener("mousemove", handleMouseMove);
+    container.addEventListener("mouseup", handleMouseUp);
+    container.addEventListener("mouseleave", handleMouseLeave);
+
+    return () => {
+      container.removeEventListener("mousedown", handleMouseDown);
+      container.removeEventListener("mousemove", handleMouseMove);
+      container.removeEventListener("mouseup", handleMouseUp);
+      container.removeEventListener("mouseleave", handleMouseLeave);
+    };
+  }, [calculateDragOffset, handleSwipeEnd, handleImageTap]);
+
+  const goToSlide = useCallback(
+    (index: number, withTransition = true) => {
+      if (withTransition) {
+        setIsTransitioning(true);
+        setDragOffset(0);
+        setTimeout(() => {
+          setActiveIndex(index);
+          onIndexChange?.(index);
+        }, 50);
+        setTimeout(() => setIsTransitioning(false), 350);
+      } else {
+        setActiveIndex(index);
+        setDragOffset(0);
+        onIndexChange?.(index);
+      }
+    },
+    [onIndexChange]
+  );
+
+  // Register indicator with sticky hero context
+  useEffect(() => {
+    if (stickyHeroContext?.setCarouselIndicator && images.length > 1) {
+      const indicator = (
+        <div
+          className="w-full"
+          role="group"
+          aria-label="Product image navigation"
+        >
+          <div className="relative h-1">
+            <div className="flex h-full">
+              {images.map((_, index) => (
+                <button
+                  key={index}
+                  onClick={() => goToSlide(index)}
+                  className="flex-1 bg-transparent hover:bg-gray-200 transition-colors duration-150"
+                  aria-label={`Go to image ${index + 1} of ${images.length}`}
+                  aria-current={activeIndex === index ? "true" : undefined}
+                />
+              ))}
+            </div>
+            <div
+              className="absolute top-0 h-full bg-primary transition-all duration-300 ease-out"
+              style={{
+                width: `${100 / images.length}%`,
+                left: `${(activeIndex * 100) / images.length}%`,
+              }}
+              aria-hidden="true"
+            />
+          </div>
+        </div>
+      );
+
+      stickyHeroContext.setCarouselIndicator(indicator);
+    }
+
+    return () => {
+      if (stickyHeroContext?.setCarouselIndicator) {
+        stickyHeroContext.setCarouselIndicator(null);
+      }
+    };
+  }, [activeIndex, images.length, goToSlide, stickyHeroContext]);
+
+  if (!images || images.length === 0) {
+    return <div className="w-full aspect-video bg-muted rounded-lg" />;
+  }
+
+  return (
+    <div className={`relative w-full h-full ${className}`}>
+      {/* Main carousel container */}
+      <div
+        ref={carouselRef}
+        className="relative z-20 w-full h-full overflow-hidden select-none"
+        style={{
+          touchAction: "pan-y pinch-zoom",
+          cursor: isDragging ? "grabbing" : "grab",
+        }}
+        onClick={() => {
+          if (wasTapRef.current && enableZoom) {
+            handleImageTap();
+          }
+          wasTapRef.current = false;
+        }}
+        role="region"
+        aria-roledescription="carousel"
+        aria-label="Product images"
+      >
+        {/* Images container */}
+        <div
+          className={`flex h-full ${
+            isPeekReturning
+              ? "transition-transform duration-300 ease-[cubic-bezier(0,0,0.2,1)]"
+              : isPeeking
+              ? "transition-transform duration-500 ease-[cubic-bezier(0.4,0,0.2,1)]"
+              : isTransitioning || !isDragging
+              ? "transition-transform duration-300 ease-[cubic-bezier(0.25,0.46,0.45,0.94)]"
+              : ""
+          }`}
+          style={{
+            transform: `translateX(${-(activeIndex * 100) - dragOffset}%)`,
+          }}
+        >
+          {images.map((image, index) => {
+            // MEMORY OPTIMIZATION: Only decode images within ±1 slide of current
+            // This prevents GPU memory from accumulating for off-screen images
+            // Critical for iOS Safari which has strict memory limits
+            const DECODE_WINDOW = 1;
+            const isWithinDecodeWindow =
+              Math.abs(index - activeIndex) <= DECODE_WINDOW;
+
+            return (
+              <div
+                key={index}
+                className="w-full h-full flex-shrink-0 relative select-none"
+              >
+                {!isWithinDecodeWindow ? (
+                  <div className="w-full h-full bg-muted" />
+                ) : image.isPlaceholder ? (
+                  <div className="w-full h-full bg-muted-foreground/20 animate-pulse" />
+                ) : image.isRealMockup && currentArtwork ? (
+                  <HeroProductImage
+                    productId={productId}
+                    artwork={currentArtwork}
+                    placement={image.placement}
+                    mockupId={image.mockupId}
+                    width={mockupWidth}
+                    realtimeUrl={
+                      image.mockupId
+                        ? realtimeMockupUrls[image.mockupId] ??
+                          generatedUrlsRef.current.get(image.mockupId) ??
+                          undefined
+                        : undefined
+                    }
+                    onUrlGenerated={
+                      image.mockupId
+                        ? (url) => handleUrlGenerated(image.mockupId!, url)
+                        : undefined
+                    }
+                    className="w-full h-full object-cover cursor-pointer pointer-events-none"
+                  />
+                ) : image.isRealMockup && !currentArtwork ? (
+                  <div className="w-full h-full bg-muted animate-pulse" />
+                ) : (
+                  <img
+                    src={image.src}
+                    alt={image.label}
+                    crossOrigin="anonymous"
+                    className="w-full h-full object-cover cursor-pointer pointer-events-none"
+                    loading="lazy"
+                    decoding="async"
+                    draggable={false}
+                  />
+                )}
+              </div>
+            );
+          })}
+        </div>
+      </div>
+
+      {/* Progress bar indicator */}
+      {showIndicators && images.length > 1 && (
+        <div
+          ref={indicatorRef}
+          data-carousel-indicator
+          className="relative z-20 w-full"
+          role="group"
+          aria-label="Product image navigation"
+        >
+          <div className="relative h-1">
+            <div className="flex h-full absolute inset-0">
+              {images.map((_, index) => (
+                <button
+                  key={index}
+                  onClick={() => goToSlide(index)}
+                  className="flex-1 bg-transparent"
+                  aria-label={`Go to image ${index + 1} of ${images.length}`}
+                  aria-current={activeIndex === index ? "true" : undefined}
+                />
+              ))}
+            </div>
+            <div
+              className={`absolute top-0 h-full bg-foreground ${
+                isPeekReturning
+                  ? "transition-all duration-300 ease-[cubic-bezier(0,0,0.2,1)]"
+                  : isPeeking
+                  ? "transition-all duration-500 ease-[cubic-bezier(0.4,0,0.2,1)]"
+                  : isDragging
+                  ? ""
+                  : "transition-all duration-300 ease-out"
+              }`}
+              style={{
+                width: `${100 / images.length}%`,
+                left: `${(activeIndex * 100 + dragOffset) / images.length}%`,
+              }}
+              aria-hidden="true"
+            />
+          </div>
+        </div>
+      )}
+
+{/* Enhanced Image Viewer */}
+      {enableZoom &&
+        showImageViewer &&
+        (() => {
+          const currentImage = imagesWithRealtimeUrls[activeIndex];
+
+          // For real mockups, also check generatedUrlsRef which stores URLs from HeroProductImage
+          let imageUrl = currentImage?.src || "";
+          if (!imageUrl && currentImage?.isRealMockup && currentImage?.mockupId) {
+            imageUrl = generatedUrlsRef.current.get(currentImage.mockupId) || "";
+          }
+
+          if (!imageUrl) {
+            return null;
+          }
+
+          // Convert to ZoomImage format, resolving URLs from all sources
+          const zoomImages = imagesWithRealtimeUrls
+            .map((img) => {
+              let src = img.src || "";
+              if (!src && img.isRealMockup && img.mockupId) {
+                src = generatedUrlsRef.current.get(img.mockupId) || "";
+              }
+              return src ? {
+                src,
+                alt: img.label,
+                naturalWidth: img.naturalWidth,
+                naturalHeight: img.naturalHeight,
+              } : null;
+            })
+            .filter((img): img is NonNullable<typeof img> => img !== null);
+
+          return (
+            <EnhancedImageViewer
+              key={viewerKey}
+              imageUrl={imageUrl}
+              alt={currentImage?.label}
+              onClose={() => { setShowImageViewer(false); onZoomChange?.(false); }}
+              images={zoomImages}
+              currentIndex={activeIndex}
+              onIndexChange={(newIndex) => {
+                setActiveIndex(newIndex);
+                onIndexChange?.(newIndex);
+              }}
+            />
+          );
+        })()}
+    </div>
+  );
+}, (prevProps, nextProps) => {
+  // Custom comparison for memoization
+  // Check primitive props
+  if (prevProps.currentIndex !== nextProps.currentIndex) return false;
+  if (prevProps.productId !== nextProps.productId) return false;
+  if (prevProps.className !== nextProps.className) return false;
+  if (prevProps.enablePeekAnimation !== nextProps.enablePeekAnimation) return false;
+  if (prevProps.enableZoom !== nextProps.enableZoom) return false;
+  if (prevProps.showIndicators !== nextProps.showIndicators) return false;
+
+  // Check artwork (compare by src to avoid object reference issues)
+  if (prevProps.currentArtwork?.src !== nextProps.currentArtwork?.src) return false;
+  if (prevProps.currentArtwork?.type !== nextProps.currentArtwork?.type) return false;
+
+  // Check images array length (assume content is stable if length matches)
+  if (prevProps.images.length !== nextProps.images.length) return false;
+
+  // Shallow check image sources for changes
+  for (let i = 0; i < prevProps.images.length; i++) {
+    if (prevProps.images[i]?.src !== nextProps.images[i]?.src) return false;
+    if (prevProps.images[i]?.mockupId !== nextProps.images[i]?.mockupId) return false;
+  }
+
+  // Callbacks are typically stable (same function reference)
+  // Only check if they changed from defined to undefined or vice versa
+  if (!!prevProps.onIndexChange !== !!nextProps.onIndexChange) return false;
+
+  return true;
+});
+
+export default MobileProductCarousel;