@snowcone-app/ui 0.1.43 → 0.2.1

package/src/patterns/MockupPriorityProvider.tsx

@@ -0,0 +1,1014 @@
+"use client";
+
+/**
+ * MockupPriorityProvider - Priority-based mockup rendering coordinator
+ *
+ * Manages a 3-level priority system for mockup rendering:
+ * - Level 1: Single most visible mockup (highest priority, pauses others)
+ * - Level 2: Other visible/partially visible mockups
+ * - Level 3: Off-screen mockups (max 5 prefetch, sorted by likelihood)
+ *
+ * Architecture:
+ * - Uses refs for visibility state to avoid re-renders during scroll
+ * - Only triggers state update when Level 1 mockup changes
+ * - Provides subscription system for components that need reactive updates
+ *
+ * @example
+ * ```tsx
+ * <RealtimeProvider>
+ *   <MockupPriorityProvider>
+ *     <HeroProductImage mockupId="front" />
+ *     <HeroProductImage mockupId="back" />
+ *   </MockupPriorityProvider>
+ * </RealtimeProvider>
+ * ```
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useCallback,
+  useRef,
+  useMemo,
+  useState,
+  useEffect,
+} from 'react';
+import {
+  useScrollDirection,
+  createScrollDirectionTracker,
+  type ScrollDirection,
+} from '../hooks/useScrollDirection';
+import { useRealtimeOptional } from './RealtimeProvider';
+
+// Constants
+const MAX_LEVEL3_PREFETCH = 5;
+const PRIORITY_RECALC_DEBOUNCE_MS = 50;
+const PRELOAD_MARGIN_PX = 750; // Load images 750px before they enter viewport
+
+// Types
+export type PriorityLevel = 1 | 2 | 3;
+
+export interface VisibilityInfo {
+  mockupId: string;
+  placement: string;
+  intersectionRatio: number;
+  visibleArea: number;
+  boundingRect: DOMRectReadOnly | null;
+  distanceFromCenter: number;
+  isAboveViewport: boolean;
+  lastUpdated: number;
+  /** True if element is within PRELOAD_MARGIN_PX of viewport (for preloading before visible) */
+  isInPreloadZone: boolean;
+}
+
+export interface MockupPriorityContextValue {
+  // Registration - pass element ref for scroll-based visibility calculation
+  registerMockup: (
+    mockupId: string,
+    placement: string,
+    initialPriority?: PriorityLevel,
+    elementRef?: HTMLElement | null
+  ) => void;
+  unregisterMockup: (mockupId: string) => void;
+
+  // Update element ref (if element mounts after registration)
+  updateElementRef: (mockupId: string, element: HTMLElement | null) => void;
+
+  // Legacy: kept for compatibility but no longer needed with scroll-based approach
+  reportVisibility: (
+    mockupId: string,
+    ratio: number,
+    boundingRect: DOMRectReadOnly
+  ) => void;
+
+  // Mobile carousel integration
+  reportMobileCarouselIndex: (currentIndex: number, mockupIds: string[]) => void;
+  clearMobileCarouselMode: () => void;
+
+  // Priority queries (synchronous, reads from refs)
+  getPriorityLevel: (mockupId: string) => PriorityLevel;
+  /**
+   * Get numeric priority for Shop queue (100 for L1, 50 for L2, 10 for L3).
+   * Used by ProductImage to integrate with Shop's priority queue in non-realtime mode.
+   */
+  getQueuePriority: (mockupId: string) => number;
+  getLevel1Mockup: () => string | null;
+  getLevel2Mockups: () => string[];
+  getLevel3Queue: () => string[];
+  getVisibility: (mockupId: string) => VisibilityInfo | null;
+
+  /**
+   * Get all mockupIds for a specific priority level.
+   * Returns array of mockupIds that should be rendered at that level.
+   */
+  getMockupIdsForLevel: (level: PriorityLevel) => string[];
+
+  // Pause state (for RealtimeProvider)
+  shouldPauseLevel: (level: 2 | 3) => boolean;
+  isLevel1Active: () => boolean;
+
+  // Subscriptions for reactive updates (optional)
+  subscribePriorityChange: (
+    mockupId: string,
+    callback: (level: PriorityLevel) => void
+  ) => () => void;
+
+  // Subscribe to Level 1 changes (for RealtimeProvider)
+  subscribeLevel1Change: (
+    callback: (mockupId: string | null) => void
+  ) => () => void;
+}
+
+const MockupPriorityContext = createContext<MockupPriorityContextValue | undefined>(
+  undefined
+);
+
+export interface MockupPriorityProviderProps {
+  children: React.ReactNode;
+}
+
+export function MockupPriorityProvider({ children }: MockupPriorityProviderProps) {
+  // Log on mount
+  useEffect(() => {
+    return () => {
+    };
+  }, []);
+
+  // REF-BASED STATE (no re-renders on visibility changes)
+  const visibilityMapRef = useRef<Map<string, VisibilityInfo>>(new Map());
+  const prioritiesRef = useRef<Map<string, PriorityLevel>>(new Map());
+  const level1MockupRef = useRef<string | null>(null);
+  const level2MockupsRef = useRef<string[]>([]);
+  const level3QueueRef = useRef<string[]>([]);
+
+  // Mobile carousel state - when set, uses index-based priority instead of visibility
+  const mobileCarouselRef = useRef<{
+    currentIndex: number;
+    mockupIds: string[];
+  } | null>(null);
+
+  // Track registration order for index-based L2 assignment (desktop scroll mode)
+  const registrationOrderRef = useRef<string[]>([]);
+
+  // Store element refs for scroll-based visibility calculation
+  const elementRefsRef = useRef<Map<string, HTMLElement>>(new Map());
+
+  // Subscriptions for reactive updates
+  const prioritySubscribersRef = useRef<Map<string, Set<(level: PriorityLevel) => void>>>(
+    new Map()
+  );
+  const level1SubscribersRef = useRef<Set<(mockupId: string | null) => void>>(
+    new Set()
+  );
+
+  // Scroll direction for Level 3 ordering
+  const scrollState = useScrollDirection();
+  const scrollDirectionRef = useRef<ScrollDirection>('idle');
+  scrollDirectionRef.current = scrollState.direction;
+
+  // Debounce timer for priority recalculation
+  const recalcTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  // Track pending rAF for first-visible recalculation (to avoid multiple rAF calls)
+  const pendingRafRef = useRef<number | null>(null);
+
+  // STATE: Only track Level 1 for minimal re-renders (used by RealtimeProvider)
+  const [level1MockupId, setLevel1MockupId] = useState<string | null>(null);
+
+  // Access RealtimeProvider for priority-based mockup requests
+  const realtimeContext = useRealtimeOptional();
+
+  // Priority rendering state
+  const currentRenderingLevelRef = useRef<PriorityLevel | null>(null);
+  const pendingMockupsRef = useRef<Set<string>>(new Set());
+  const renderedMockupsRef = useRef<Set<string>>(new Set());
+
+  // Track pending blob timestamps to prevent premature level advancement during drag
+  const lastPendingBlobTimeRef = useRef<number>(0);
+  const DRAG_STOP_DEBOUNCE_MS = 250; // Time to wait after last blob before advancing to Level 2+
+  const BLOB_SEND_DELAY_MS = 100; // Short delay to let blob be sent before requesting mockups
+
+  // Timer for delayed mockup request after drag stops
+  const pendingBlobRequestTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  /**
+   * Request mockups for a specific priority level.
+   * Uses updateMockupIds to tell server which mockups to render.
+   */
+  const requestMockupsForLevel = useCallback((level: PriorityLevel) => {
+
+    if (!realtimeContext?.updateMockupIds) {
+      return;
+    }
+
+    let mockupIds: string[];
+    switch (level) {
+      case 1:
+        mockupIds = level1MockupRef.current ? [level1MockupRef.current] : [];
+        break;
+      case 2:
+        mockupIds = [...level2MockupsRef.current];
+        break;
+      case 3:
+        mockupIds = [...level3QueueRef.current];
+        break;
+      default:
+        mockupIds = [];
+    }
+
+    if (mockupIds.length === 0) {
+      // No mockups at this level, advance to next
+      if (level < 3) {
+        requestMockupsForLevel((level + 1) as PriorityLevel);
+      }
+      return;
+    }
+
+    currentRenderingLevelRef.current = level;
+    pendingMockupsRef.current = new Set(mockupIds);
+    realtimeContext.updateMockupIds(mockupIds);
+  }, [realtimeContext]);
+
+  // Timer ref for delayed level advancement
+  const levelAdvanceTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  /**
+   * Handle mockup result - check if current level is complete
+   */
+  const handleMockupResult = useCallback((mockupId: string) => {
+    // Mark as rendered
+    renderedMockupsRef.current.add(mockupId);
+    pendingMockupsRef.current.delete(mockupId);
+
+    const currentLevel = currentRenderingLevelRef.current;
+    if (currentLevel === null) return;
+
+    // Check if all pending mockups for current level are done
+    if (pendingMockupsRef.current.size === 0) {
+      const timeSinceLastPendingBlob = Date.now() - lastPendingBlobTimeRef.current;
+      const isStillDragging = timeSinceLastPendingBlob < DRAG_STOP_DEBOUNCE_MS;
+
+
+      // Level 1 complete - decide whether to advance to Level 2+
+      if (currentLevel === 1 && isStillDragging) {
+        // Still dragging - stay on Level 1, don't advance to Level 2
+        // The next pending blob will re-request Level 1
+        currentRenderingLevelRef.current = null; // Ready for next Level 1 request
+        return;
+      }
+
+      if (isStillDragging) {
+        // For Level 2/3 during drag, delay advancement
+
+        if (levelAdvanceTimeoutRef.current) {
+          clearTimeout(levelAdvanceTimeoutRef.current);
+        }
+
+        levelAdvanceTimeoutRef.current = setTimeout(() => {
+          const newTimeSince = Date.now() - lastPendingBlobTimeRef.current;
+          if (newTimeSince >= DRAG_STOP_DEBOUNCE_MS && pendingMockupsRef.current.size === 0) {
+            if (currentLevel < 3) {
+              requestMockupsForLevel((currentLevel + 1) as PriorityLevel);
+            } else {
+              currentRenderingLevelRef.current = null;
+            }
+          }
+          levelAdvanceTimeoutRef.current = null;
+        }, DRAG_STOP_DEBOUNCE_MS - timeSinceLastPendingBlob + 10);
+
+        return;
+      }
+
+      // Not dragging - advance immediately
+      if (currentLevel < 3) {
+        requestMockupsForLevel((currentLevel + 1) as PriorityLevel);
+      } else {
+        currentRenderingLevelRef.current = null;
+      }
+    }
+  }, [requestMockupsForLevel]);
+
+  // Subscribe to mockup results for level advancement
+  useEffect(() => {
+    if (!realtimeContext?.subscribeMockupResults) return;
+
+    const unsubscribe = realtimeContext.subscribeMockupResults((results) => {
+      results.forEach((result) => {
+        handleMockupResult(result.mockupId);
+      });
+    });
+
+    return unsubscribe;
+  }, [realtimeContext, handleMockupResult]);
+
+  // Log when realtimeContext changes and trigger priority flow when isConfigured becomes true
+  useEffect(() => {
+
+    // When isConfigured becomes true and we have a Level 1 mockup, start priority flow
+    if (realtimeContext?.isConfigured && level1MockupRef.current) {
+      renderedMockupsRef.current.clear();
+      requestMockupsForLevel(1);
+    }
+  }, [realtimeContext, requestMockupsForLevel]);
+
+  // When Level 1 changes, restart the priority flow (only if realtime is configured)
+  useEffect(() => {
+
+    if (level1MockupId === null) {
+      return;
+    }
+
+    // Wait until realtime is configured before starting priority flow
+    if (!realtimeContext?.isConfigured) {
+      return;
+    }
+
+    // Reset rendered tracking for new priority calculation
+    renderedMockupsRef.current.clear();
+
+    // Start requesting from Level 1
+    requestMockupsForLevel(1);
+  }, [level1MockupId, realtimeContext?.isConfigured, requestMockupsForLevel]);
+
+  // Subscribe to pending blob notifications to track drag timing (for L2+ delay)
+  useEffect(() => {
+    if (!realtimeContext?.subscribePendingBlob) return;
+
+    const handlePendingBlob = (placement: string) => {
+
+      // Track the time of this pending blob event for drag detection
+      lastPendingBlobTimeRef.current = Date.now();
+
+      // Cancel any pending level advancement - user is still making changes
+      if (levelAdvanceTimeoutRef.current) {
+        clearTimeout(levelAdvanceTimeoutRef.current);
+        levelAdvanceTimeoutRef.current = null;
+      }
+
+      // NOTE: Do NOT reset currentRenderingLevelRef, pendingMockupsRef, or renderedMockupsRef here!
+      // This handler fires repeatedly during drag, and resetting state here would cause
+      // in-flight L1 requests to be ignored when their results arrive.
+      // The state reset happens in handleBlobReceived when we actually start a new request.
+    };
+
+    const unsubscribe = realtimeContext.subscribePendingBlob(handlePendingBlob);
+    return unsubscribe;
+  }, [realtimeContext]);
+
+  // Subscribe to blob sent notifications to trigger mockup requests
+  // This fires when the blob is actually sent (after throttle completes)
+  // More reliable than blob_received which only fires for NEW placements
+  useEffect(() => {
+    if (!realtimeContext?.subscribeBlobSent) return;
+
+    const handleBlobSent = (placement: string) => {
+
+      // Cancel any pending mockup request timeout (shouldn't happen, but just in case)
+      if (pendingBlobRequestTimeoutRef.current) {
+        clearTimeout(pendingBlobRequestTimeoutRef.current);
+        pendingBlobRequestTimeoutRef.current = null;
+      }
+
+      // Reset state for new priority flow - we're starting fresh with the new blob
+      currentRenderingLevelRef.current = null;
+      pendingMockupsRef.current.clear();
+      renderedMockupsRef.current.clear();
+
+      // NOTE: Do NOT update lastPendingBlobTimeRef here!
+      // That timestamp tracks when the user is actively dragging (pendingBlob events).
+      // blob_sent happens after throttle delay, and we use the
+      // time since last pendingBlob to detect if user stopped dragging.
+      // If we reset it here, L1 might complete within 250ms and we'd think
+      // we're still dragging, preventing advancement to L2.
+
+      // Request Level 1 mockups immediately - blob is now on its way to server
+      if (level1MockupRef.current) {
+        requestMockupsForLevel(1);
+      }
+    };
+
+    const unsubscribe = realtimeContext.subscribeBlobSent(handleBlobSent);
+    return unsubscribe;
+  }, [realtimeContext, requestMockupsForLevel]);
+
+  /**
+   * Recalculate priorities based on current state.
+   *
+   * MOBILE CAROUSEL MODE (simple index-based):
+   * - Level 1: Current carousel item
+   * - Level 2: Adjacent items (±1)
+   * - Level 3: All other items
+   *
+   * DESKTOP MODE (visibility-based):
+   * - Level 1: Mockup with largest visible pixel area
+   * - Level 2: Other visible mockups
+   * - Level 3: Off-screen mockups
+   */
+  const recalculatePriorities = useCallback(() => {
+    const mobileState = mobileCarouselRef.current;
+
+    // ===== MOBILE CAROUSEL MODE =====
+    if (mobileState && mobileState.mockupIds.length > 0) {
+      const { currentIndex, mockupIds } = mobileState;
+
+      let newLevel1: string | null = null;
+      const newLevel2Set = new Set<string>();
+      const newLevel3Set = new Set<string>();
+      const changedMockups: Array<{ mockupId: string; newLevel: PriorityLevel }> = [];
+
+      // Calculate new priorities based on carousel index
+      mockupIds.forEach((id, index) => {
+        const oldLevel = prioritiesRef.current.get(id);
+        let newLevel: PriorityLevel;
+
+        if (index === currentIndex) {
+          newLevel = 1;
+        } else if (Math.abs(index - currentIndex) === 1) {
+          newLevel = 2;
+        } else {
+          newLevel = 3;
+        }
+
+        // Always set the priority (carousel index is authoritative)
+        prioritiesRef.current.set(id, newLevel);
+
+        if (newLevel === 1) {
+          newLevel1 = id;
+        } else if (newLevel === 2) {
+          newLevel2Set.add(id);
+        } else {
+          newLevel3Set.add(id);
+        }
+
+        // Track if priority actually changed (for subscriber notification)
+        if (oldLevel !== newLevel) {
+          changedMockups.push({ mockupId: id, newLevel });
+        }
+      });
+
+      level2MockupsRef.current = [...newLevel2Set];
+      level3QueueRef.current = [...newLevel3Set].slice(0, MAX_LEVEL3_PREFETCH);
+
+      // Update Level 1 if changed
+      if (newLevel1 !== level1MockupRef.current) {
+        level1MockupRef.current = newLevel1;
+        setLevel1MockupId(newLevel1);
+        level1SubscribersRef.current.forEach((cb) => cb(newLevel1));
+      }
+
+      // Only notify subscribers for mockups whose priority actually changed
+      changedMockups.forEach(({ mockupId, newLevel }) => {
+        const subscribers = prioritySubscribersRef.current.get(mockupId);
+        subscribers?.forEach((cb) => cb(newLevel));
+      });
+
+      return;
+    }
+
+    // ===== DESKTOP MODE (visibility-based) =====
+    const visibilities = [...visibilityMapRef.current.entries()];
+
+    if (visibilities.length === 0) {
+      return;
+    }
+
+    // Find the mockup with the largest visible area
+    let maxVisibleArea = 0;
+    let level1Candidate: string | null = null;
+
+    visibilities.forEach(([mockupId, info]) => {
+      if (info.visibleArea > maxVisibleArea) {
+        maxVisibleArea = info.visibleArea;
+        level1Candidate = mockupId;
+      }
+    });
+
+    // Assign levels based on visibility and track changes
+    const newLevel2: string[] = [];
+    const newLevel3: string[] = [];
+    const changedMockups: Array<{ mockupId: string; newLevel: PriorityLevel }> = [];
+
+    visibilities.forEach(([mockupId, info]) => {
+      const oldLevel = prioritiesRef.current.get(mockupId);
+      let newLevel: PriorityLevel;
+
+      if (mockupId === level1Candidate) {
+        newLevel = 1;
+      } else if (info.visibleArea > 0) {
+        // Actually visible in viewport
+        newLevel = 2;
+        newLevel2.push(mockupId);
+      } else if (info.isInPreloadZone) {
+        // Within preload margin - promote to Level 2 to start loading before visible
+        newLevel = 2;
+        newLevel2.push(mockupId);
+      } else {
+        newLevel = 3;
+        newLevel3.push(mockupId);
+      }
+
+      prioritiesRef.current.set(mockupId, newLevel);
+
+      // Track if priority changed
+      if (oldLevel !== newLevel) {
+        changedMockups.push({ mockupId, newLevel });
+      }
+    });
+
+    level2MockupsRef.current = newLevel2;
+    level3QueueRef.current = newLevel3.slice(0, MAX_LEVEL3_PREFETCH);
+
+    // Update Level 1 if changed
+    if (level1Candidate !== level1MockupRef.current && (level1Candidate !== null || maxVisibleArea > 0)) {
+      level1MockupRef.current = level1Candidate;
+      setLevel1MockupId(level1Candidate);
+      level1SubscribersRef.current.forEach((cb) => cb(level1Candidate));
+    }
+
+    // Only notify subscribers for mockups whose priority actually changed
+    changedMockups.forEach(({ mockupId, newLevel }) => {
+      const subscribers = prioritySubscribersRef.current.get(mockupId);
+      subscribers?.forEach((cb) => cb(newLevel));
+    });
+  }, []);
+
+  /**
+   * Debounced priority recalculation
+   */
+  const scheduleRecalculation = useCallback(() => {
+    if (recalcTimeoutRef.current) {
+      clearTimeout(recalcTimeoutRef.current);
+    }
+    recalcTimeoutRef.current = setTimeout(() => {
+      recalculatePriorities();
+      recalcTimeoutRef.current = null;
+    }, PRIORITY_RECALC_DEBOUNCE_MS);
+  }, [recalculatePriorities]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (recalcTimeoutRef.current) {
+        clearTimeout(recalcTimeoutRef.current);
+      }
+      if (levelAdvanceTimeoutRef.current) {
+        clearTimeout(levelAdvanceTimeoutRef.current);
+      }
+      if (pendingBlobRequestTimeoutRef.current) {
+        clearTimeout(pendingBlobRequestTimeoutRef.current);
+      }
+      if (pendingRafRef.current !== null) {
+        cancelAnimationFrame(pendingRafRef.current);
+      }
+    };
+  }, []);
+
+  /**
+   * Update visibility data for all mockups from their element refs.
+   * Called on scroll to keep visibility data fresh.
+   */
+  const updateVisibilityFromRefs = useCallback(() => {
+    const viewportHeight = typeof window !== 'undefined' ? window.innerHeight : 800;
+    const viewportWidth = typeof window !== 'undefined' ? window.innerWidth : 1200;
+    const viewportCenterY = viewportHeight / 2;
+
+    const elementCount = elementRefsRef.current.size;
+    if (elementCount === 0) {
+      return;
+    }
+
+    elementRefsRef.current.forEach((element, mockupId) => {
+      const existing = visibilityMapRef.current.get(mockupId);
+      if (!existing) {
+        return;
+      }
+
+      const rect = element.getBoundingClientRect();
+
+      // Skip hidden elements (display: none returns all zeros)
+      // This handles responsive layouts where only one version is visible
+      if (rect.height === 0 || rect.width === 0) {
+        return;
+      }
+
+      const elementCenterY = rect.top + rect.height / 2;
+      const distanceFromCenter = Math.abs(viewportCenterY - elementCenterY);
+
+      // Calculate visible area
+      const visibleTop = Math.max(0, rect.top);
+      const visibleBottom = Math.min(viewportHeight, rect.bottom);
+      const visibleLeft = Math.max(0, rect.left);
+      const visibleRight = Math.min(viewportWidth, rect.right);
+      const visibleWidth = Math.max(0, visibleRight - visibleLeft);
+      const visibleHeight = Math.max(0, visibleBottom - visibleTop);
+      const visibleArea = visibleWidth * visibleHeight;
+
+      // Calculate intersection ratio
+      const totalArea = rect.width * rect.height;
+      const intersectionRatio = totalArea > 0 ? visibleArea / totalArea : 0;
+
+      // Calculate if element is in preload zone (within PRELOAD_MARGIN_PX of viewport)
+      const isInPreloadZone =
+        rect.bottom > -PRELOAD_MARGIN_PX &&
+        rect.top < viewportHeight + PRELOAD_MARGIN_PX;
+
+      // Update visibility info
+      visibilityMapRef.current.set(mockupId, {
+        ...existing,
+        intersectionRatio,
+        visibleArea,
+        boundingRect: rect,
+        distanceFromCenter,
+        isAboveViewport: rect.bottom < 0,
+        isInPreloadZone,
+        lastUpdated: Date.now(),
+      });
+    });
+  }, []);
+
+  // Visibility polling for priority updates
+  // Uses polling instead of scroll events for reliable cross-platform behavior
+  // (iOS momentum scrolling doesn't fire scroll events reliably)
+  useEffect(() => {
+
+    const pollVisibility = () => {
+      updateVisibilityFromRefs();
+      recalculatePriorities();
+    };
+
+    // Poll every 100ms for responsive updates on all platforms
+    const pollInterval = setInterval(pollVisibility, 100);
+
+    // Also listen to scroll for immediate response on desktop
+    // NOTE: Removed resize listener - it causes flash on Safari iPad when address bar
+    // shows/hides (triggers state updates). The 100ms poll handles resize cases adequately.
+    window.addEventListener('scroll', pollVisibility, { passive: true });
+
+    // Initial calculation
+    pollVisibility();
+
+    return () => {
+      clearInterval(pollInterval);
+      window.removeEventListener('scroll', pollVisibility);
+    };
+  }, [updateVisibilityFromRefs, recalculatePriorities]);
+
+  // --- Context Methods ---
+
+  const registerMockup = useCallback(
+    (mockupId: string, placement: string, initialPriority?: PriorityLevel, elementRef?: HTMLElement | null) => {
+
+      // Track registration order (if not already registered)
+      if (!registrationOrderRef.current.includes(mockupId)) {
+        registrationOrderRef.current.push(mockupId);
+      }
+
+      // Store element ref if provided
+      if (elementRef) {
+        elementRefsRef.current.set(mockupId, elementRef);
+      }
+
+      // Initialize with default values
+      visibilityMapRef.current.set(mockupId, {
+        mockupId,
+        placement,
+        intersectionRatio: 0,
+        visibleArea: 0,
+        boundingRect: null,
+        distanceFromCenter: Infinity,
+        isAboveViewport: true,
+        isInPreloadZone: false,
+        lastUpdated: Date.now(),
+      });
+
+      // Use initialPriority if provided, otherwise fall back to existing logic
+      if (initialPriority !== undefined) {
+        prioritiesRef.current.set(mockupId, initialPriority);
+
+        // Update level refs based on initial priority
+        if (initialPriority === 1 && !level1MockupRef.current) {
+          level1MockupRef.current = mockupId;
+          setLevel1MockupId(mockupId);
+        } else if (initialPriority === 2) {
+          if (!level2MockupsRef.current.includes(mockupId)) {
+            level2MockupsRef.current.push(mockupId);
+          }
+        } else {
+          // Level 3
+          if (!level3QueueRef.current.includes(mockupId)) {
+            level3QueueRef.current.push(mockupId);
+          }
+        }
+
+        // Notify subscribers of initial priority
+        const callbacks = prioritySubscribersRef.current.get(mockupId);
+        if (callbacks) {
+          callbacks.forEach((callback) => callback(initialPriority));
+        }
+      } else {
+        // Fallback: Level 3 until visibility is reported
+        prioritiesRef.current.set(mockupId, 3);
+
+        // If this is the first mockup, assume it might be visible (above the fold)
+        if (prioritiesRef.current.size === 1 && !level1MockupRef.current) {
+          prioritiesRef.current.set(mockupId, 1);
+          level1MockupRef.current = mockupId;
+          setLevel1MockupId(mockupId);
+        } else {
+        }
+      }
+    },
+    []
+  );
+
+  const unregisterMockup = useCallback((mockupId: string) => {
+    visibilityMapRef.current.delete(mockupId);
+    prioritiesRef.current.delete(mockupId);
+    prioritySubscribersRef.current.delete(mockupId);
+    elementRefsRef.current.delete(mockupId);
+
+    // Remove from registration order
+    const orderIndex = registrationOrderRef.current.indexOf(mockupId);
+    if (orderIndex !== -1) {
+      registrationOrderRef.current.splice(orderIndex, 1);
+    }
+
+    // If this was Level 1, recalculate
+    if (level1MockupRef.current === mockupId) {
+      level1MockupRef.current = null;
+      setLevel1MockupId(null);
+      // Schedule recalculation to find new Level 1
+      scheduleRecalculation();
+    }
+  }, [scheduleRecalculation]);
+
+  // Update element ref (if element mounts after registration)
+  const updateElementRef = useCallback((mockupId: string, element: HTMLElement | null) => {
+    if (element) {
+      // Only store refs for visible elements (skip display:none)
+      // This handles responsive layouts with multiple HeroProductImage per mockupId
+      const rect = element.getBoundingClientRect();
+      if (rect.height === 0 || rect.width === 0) {
+        return;
+      }
+
+      elementRefsRef.current.set(mockupId, element);
+      // Trigger visibility update AND priority recalculation
+      updateVisibilityFromRefs();
+      scheduleRecalculation();
+    } else {
+      elementRefsRef.current.delete(mockupId);
+    }
+  }, [updateVisibilityFromRefs, scheduleRecalculation]);
+
+  const reportVisibility = useCallback(
+    (mockupId: string, ratio: number, boundingRect: DOMRectReadOnly) => {
+      const existing = visibilityMapRef.current.get(mockupId);
+      if (!existing) {
+        return;
+      }
+
+      const viewportHeight =
+        typeof window !== 'undefined' ? window.innerHeight : 800;
+      const viewportCenterY = viewportHeight / 2;
+      const elementCenterY = boundingRect.top + boundingRect.height / 2;
+      const distanceFromCenter = Math.abs(viewportCenterY - elementCenterY);
+
+      // Calculate visible area
+      const visibleTop = Math.max(0, boundingRect.top);
+      const visibleBottom = Math.min(viewportHeight, boundingRect.bottom);
+      const visibleLeft = Math.max(0, boundingRect.left);
+      const visibleRight = Math.min(
+        typeof window !== 'undefined' ? window.innerWidth : 1200,
+        boundingRect.right
+      );
+      const visibleWidth = Math.max(0, visibleRight - visibleLeft);
+      const visibleHeight = Math.max(0, visibleBottom - visibleTop);
+      const visibleArea = visibleWidth * visibleHeight;
+
+      // Check if this is the first real visibility report for a visible mockup
+      // (transition from no data to visible)
+      const isFirstVisibleReport = existing.intersectionRatio === 0 && ratio > 0;
+
+      // Calculate if element is in preload zone (within PRELOAD_MARGIN_PX of viewport)
+      const isInPreloadZone =
+        boundingRect.bottom > -PRELOAD_MARGIN_PX &&
+        boundingRect.top < viewportHeight + PRELOAD_MARGIN_PX;
+
+      // Update visibility info
+      visibilityMapRef.current.set(mockupId, {
+        ...existing,
+        intersectionRatio: ratio,
+        visibleArea,
+        boundingRect,
+        distanceFromCenter,
+        isAboveViewport: boundingRect.bottom < 0,
+        isInPreloadZone,
+        lastUpdated: Date.now(),
+      });
+
+      // If this is the first visibility report for a visible mockup,
+      // trigger immediate recalculation to fix initial priorities quickly
+      if (isFirstVisibleReport) {
+        // Cancel any pending debounced recalculation
+        if (recalcTimeoutRef.current) {
+          clearTimeout(recalcTimeoutRef.current);
+          recalcTimeoutRef.current = null;
+        }
+        // Use requestAnimationFrame to batch multiple first-visible reports in the same frame
+        // Only schedule one rAF callback
+        if (pendingRafRef.current === null) {
+          pendingRafRef.current = requestAnimationFrame(() => {
+            pendingRafRef.current = null;
+            recalculatePriorities();
+          });
+        }
+      } else {
+        // Normal scroll: use debounced recalculation
+        scheduleRecalculation();
+      }
+    },
+    [scheduleRecalculation, recalculatePriorities]
+  );
+
+  // Mobile carousel mode - uses simple index-based priority
+  const reportMobileCarouselIndex = useCallback(
+    (currentIndex: number, mockupIds: string[]) => {
+      mobileCarouselRef.current = { currentIndex, mockupIds };
+      // Immediate recalculation with index-based priority
+      recalculatePriorities();
+    },
+    [recalculatePriorities]
+  );
+
+  const clearMobileCarouselMode = useCallback(() => {
+    mobileCarouselRef.current = null;
+    // Switch to visibility-based priority
+    recalculatePriorities();
+  }, [recalculatePriorities]);
+
+  const getPriorityLevel = useCallback((mockupId: string): PriorityLevel => {
+    return prioritiesRef.current.get(mockupId) || 3;
+  }, []);
+
+  const getQueuePriority = useCallback((mockupId: string): number => {
+    const level = prioritiesRef.current.get(mockupId) || 3;
+    switch (level) {
+      case 1: return 100;
+      case 2: return 50;
+      case 3: return 10;
+      default: return 10;
+    }
+  }, []);
+
+  const getLevel1Mockup = useCallback((): string | null => {
+    return level1MockupRef.current;
+  }, []);
+
+  const getLevel2Mockups = useCallback((): string[] => {
+    return [...level2MockupsRef.current];
+  }, []);
+
+  const getLevel3Queue = useCallback((): string[] => {
+    return [...level3QueueRef.current];
+  }, []);
+
+  const getVisibility = useCallback((mockupId: string): VisibilityInfo | null => {
+    return visibilityMapRef.current.get(mockupId) || null;
+  }, []);
+
+  const getMockupIdsForLevel = useCallback((level: PriorityLevel): string[] => {
+    switch (level) {
+      case 1:
+        return level1MockupRef.current ? [level1MockupRef.current] : [];
+      case 2:
+        return [...level2MockupsRef.current];
+      case 3:
+        return [...level3QueueRef.current];
+      default:
+        return [];
+    }
+  }, []);
+
+  const shouldPauseLevel = useCallback((level: 2 | 3): boolean => {
+    // Level 2 is paused when Level 1 is active
+    // Level 3 is paused when Level 1 or Level 2 is active
+    if (level === 2) {
+      return level1MockupRef.current !== null;
+    }
+    // level === 3
+    return (
+      level1MockupRef.current !== null || level2MockupsRef.current.length > 0
+    );
+  }, []);
+
+  const isLevel1Active = useCallback((): boolean => {
+    return level1MockupRef.current !== null;
+  }, []);
+
+  const subscribePriorityChange = useCallback(
+    (mockupId: string, callback: (level: PriorityLevel) => void) => {
+      if (!prioritySubscribersRef.current.has(mockupId)) {
+        prioritySubscribersRef.current.set(mockupId, new Set());
+      }
+      prioritySubscribersRef.current.get(mockupId)!.add(callback);
+
+      // Immediately call with current priority
+      const currentLevel = prioritiesRef.current.get(mockupId) || 3;
+      callback(currentLevel);
+
+      return () => {
+        const subscribers = prioritySubscribersRef.current.get(mockupId);
+        if (subscribers) {
+          subscribers.delete(callback);
+          if (subscribers.size === 0) {
+            prioritySubscribersRef.current.delete(mockupId);
+          }
+        }
+      };
+    },
+    []
+  );
+
+  const subscribeLevel1Change = useCallback(
+    (callback: (mockupId: string | null) => void) => {
+      level1SubscribersRef.current.add(callback);
+      // Immediately call with current Level 1
+      callback(level1MockupRef.current);
+
+      return () => {
+        level1SubscribersRef.current.delete(callback);
+      };
+    },
+    []
+  );
+
+  // Create stable context value
+  const contextValue = useMemo<MockupPriorityContextValue>(
+    () => ({
+      registerMockup,
+      unregisterMockup,
+      updateElementRef,
+      reportVisibility,
+      reportMobileCarouselIndex,
+      clearMobileCarouselMode,
+      getPriorityLevel,
+      getQueuePriority,
+      getLevel1Mockup,
+      getLevel2Mockups,
+      getLevel3Queue,
+      getVisibility,
+      getMockupIdsForLevel,
+      shouldPauseLevel,
+      isLevel1Active,
+      subscribePriorityChange,
+      subscribeLevel1Change,
+    }),
+    [
+      registerMockup,
+      unregisterMockup,
+      updateElementRef,
+      reportVisibility,
+      reportMobileCarouselIndex,
+      clearMobileCarouselMode,
+      getPriorityLevel,
+      getQueuePriority,
+      getLevel1Mockup,
+      getLevel2Mockups,
+      getLevel3Queue,
+      getVisibility,
+      getMockupIdsForLevel,
+      shouldPauseLevel,
+      isLevel1Active,
+      subscribePriorityChange,
+      subscribeLevel1Change,
+    ]
+  );
+
+  return (
+    <MockupPriorityContext.Provider value={contextValue}>
+      {children}
+    </MockupPriorityContext.Provider>
+  );
+}
+
+/**
+ * Hook to access mockup priority context
+ * Throws if not inside MockupPriorityProvider
+ */
+export function useMockupPriority(): MockupPriorityContextValue {
+  const context = useContext(MockupPriorityContext);
+  if (!context) {
+    throw new Error(
+      'useMockupPriority must be used within a MockupPriorityProvider'
+    );
+  }
+  return context;
+}
+
+/**
+ * Hook to optionally access mockup priority context
+ * Returns undefined if not inside MockupPriorityProvider
+ */
+export function useMockupPriorityOptional(): MockupPriorityContextValue | undefined {
+  return useContext(MockupPriorityContext);
+}