@snowcone-app/ui 0.1.43 → 0.2.1

package/src/composed/HeroProductImage.tsx

@@ -0,0 +1,1079 @@
+"use client";
+
+import React, {
+  useMemo,
+  useState,
+  useEffect,
+  useRef,
+  memo,
+  useCallback,
+} from "react";
+import {
+  useProductOptional,
+  useDesignOptional,
+  type PlacementDesign,
+} from "../patterns/Product";
+import { useShopOptional } from "../patterns/ShopProvider";
+import { useRealtimeOptional } from "../patterns/RealtimeProvider";
+import { useMockupPriorityOptional } from "../patterns/MockupPriorityProvider";
+import {
+  createDesignForPlacements,
+  type DesignElement,
+  getMockupUrl,
+  type Design,
+  resolveVariantId,
+  resolveMockupId,
+} from "@snowcone-app/sdk";
+
+/** Slugify a placement label into the catalog's `placements[].key` form. */
+function slugifyPlacementKey(label: string): string {
+  return label
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+}
+
+type PlacementLike = { label: string; key?: string; type?: string | null };
+
+/**
+ * Convert the SDK's `DesignElement[]` (label-keyed, used by the realtime/canvas
+ * path) into the public resolver's `Design` (placement-key → fill), so a static
+ * `<img>` can be built via the **signing resolver** (`getMockupUrl`) rather than
+ * the unsigned direct-renderer builder. The renderer requires a `seal`, which
+ * only the resolver adds (ADR-0076).
+ */
+function toPublicDesign(
+  elements: DesignElement[],
+  placements: PlacementLike[]
+): Design {
+  const design: Design = {};
+  for (const el of elements) {
+    if (!el.placement) continue;
+    const match = placements.find((p) => p.label === el.placement);
+    const key = match?.key || slugifyPlacementKey(el.placement);
+    if (el.type === "color") {
+      if (el.hex) design[key] = { color: el.hex };
+    } else if (el.imageUrl) {
+      const aligned = el.alignment && el.alignment !== "center";
+      design[key] =
+        aligned || el.tiles
+          ? {
+              src: el.imageUrl,
+              ...(aligned ? { align: el.alignment } : {}),
+              ...(el.tiles ? { tile: el.tiles } : {}),
+            }
+          : el.imageUrl;
+    }
+  }
+  return design;
+}
+
+/**
+ * Build a static mockup `<img>` URL through the signing resolver (ADR-0076).
+ * Returns null when the shop isn't configured or the design is empty. `shop` +
+ * the local resolver host are published on `window.snowcone` by ShopProvider
+ * (prod falls back to img.snowcone.app).
+ */
+function buildHeroMockupUrl(args: {
+  productCode: string;
+  design: DesignElement[];
+  placements: PlacementLike[];
+  mockupId: string;
+  variantId: string;
+  width: number;
+}): string | null {
+  const snow =
+    (typeof window !== "undefined" &&
+      (window as unknown as { snowcone?: { shop?: string; resolver?: string } })
+        .snowcone) ||
+    {};
+  if (!snow.shop) return null;
+  const publicDesign = toPublicDesign(args.design, args.placements);
+  if (Object.keys(publicDesign).length === 0) return null;
+  return getMockupUrl(args.productCode, {
+    shop: snow.shop,
+    design: publicDesign,
+    width: args.width,
+    view: args.mockupId,
+    variant: args.variantId,
+    ...(snow.resolver ? { base: snow.resolver } : {}),
+  });
+}
+import { useImageTransition } from "../hooks/useImageTransition";
+import { useContainerWidth } from "../hooks/viewport/useContainerWidth";
+import { observe } from "../hooks/visibility/observerPool";
+
+const EMPTY_IMAGES: DesignElement[] = [];
+
+export interface HeroProductImageProps {
+  productId?: string;
+  mockupId?: string;
+  variantId?: string;
+  gvid?: string;
+  images?: DesignElement[];
+  width?: number;
+  effects?: { grain?: 1 | 2 };
+  endpoint?: string;
+  className?: string;
+  style?: React.CSSProperties;
+  draggable?: boolean;
+  placement?: string;
+
+  // Optional explicit props (takes priority over context)
+  artwork?:
+    | { type: "regular"; src: string }
+    | { type: "pattern"; src: string; tileCount?: number };
+  product?: { id: string; name?: string; placements?: any[] };
+
+  // Event handlers for compatibility with img elements
+  onClick?: (e: React.MouseEvent<HTMLImageElement>) => void;
+  onLoad?: () => void;
+  onError?: () => void;
+  onUrlGenerated?: (url: string) => void;
+
+  // Priority system
+  initialPriority?: 1 | 2 | 3;
+
+  /**
+   * Controls how the component sources mockup images:
+   * - `static`: Only use static mockup URLs (no realtime subscription)
+   * - `realtime`: Only use realtime system (shimmer during pending exports, no static fallback)
+   * - `auto` (default): Start with static, prefer realtime when available
+   */
+  mode?: "static" | "realtime" | "auto";
+
+  // Realtime URL passed directly from parent (bypasses internal cache lookup)
+  // Use this when parent already has the URL from getMockupUrls()
+  realtimeUrl?: string;
+
+  // Transition timing (all in ms)
+  fadeDuration?: number;
+  shimmerDelay?: number;
+  shimmerFadeDuration?: number;
+  darkShimmerFadeInDuration?: number;
+}
+
+/**
+ * Hero-compatible version of ProductImage that renders as a simple img element
+ * for better compatibility with hero image layouts and zoom functionality.
+ *
+ * Supports realtime mockup updates when used inside RealtimeProvider.
+ * The RealtimeProvider coordinates WebSocket connections and canvas exports,
+ * while this component simply displays the appropriate mockup for its placement.
+ *
+ * @example
+ * // With realtime updates:
+ * <RealtimeProvider productId="abc" placements={[...]}>
+ *   <HeroProductImage placement="Front" mockupId="..." />
+ * </RealtimeProvider>
+ *
+ * // Without realtime (static mockups):
+ * <HeroProductImage placement="Front" mockupId="..." artwork={artwork} />
+ */
+export const HeroProductImage = memo(function HeroProductImage({
+  productId,
+  mockupId,
+  variantId,
+  gvid,
+  images = EMPTY_IMAGES,
+  width: widthProp,
+  effects,
+  endpoint,
+  className,
+  style,
+  draggable = false,
+  placement,
+  artwork,
+  product,
+  onClick,
+  onLoad,
+  onError,
+  onUrlGenerated,
+  initialPriority,
+  mode = "auto",
+  realtimeUrl,
+  fadeDuration = 300, // Quick crossfade
+  shimmerDelay = 200,
+  shimmerFadeDuration = 500,
+  darkShimmerFadeInDuration = 300,
+}: HeroProductImageProps) {
+  // Context
+  const context = useProductOptional();
+  const designContext = useDesignOptional();
+  const shopContext = useShopOptional();
+  const realtimeContext = useRealtimeOptional();
+  const priorityContext = useMockupPriorityOptional();
+  const priorityContextRef = useRef(priorityContext);
+  priorityContextRef.current = priorityContext;
+
+  // Keep context in a ref for polling access (avoids stale closures)
+  const contextRef = useRef(context);
+  contextRef.current = context;
+
+  // Get product ID from explicit prop or context - MOVED UP for initial URL computation
+  const actualProductId = product?.id || productId || context?.product?.id;
+
+  // Resolve variant and mockup IDs - MOVED UP for initial URL computation
+  const actualGvid = useMemo(() => {
+    return resolveVariantId(context, gvid, variantId);
+  }, [gvid, variantId, context?.selection, context?.combinations]);
+
+  const actualMockupId = useMemo(() => {
+    return resolveMockupId(context, actualGvid, mockupId);
+  }, [mockupId, actualGvid, context]);
+
+  // Extract artwork source for initial URL computation
+  const artworkSrc = artwork?.src;
+  const selectedArtworkSrc = designContext?.selectedArtwork?.src;
+  const effectiveArtworkSrc = artworkSrc || selectedArtworkSrc;
+
+  // Container ref + responsive width (must be before initialStaticUrl which uses width)
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const measuredWidth = useContainerWidth(containerRef);
+  const width = widthProp ?? measuredWidth;
+
+  // SAFARI FIX: Compute initial static URL during render (not in useEffect)
+  // Safari doesn't properly decode images added after initial render,
+  // causing a flash when they become visible. By computing the URL during render
+  // and passing it as initialUrl, the img element exists from the first render.
+  const initialStaticUrl = useMemo(() => {
+    // Skip if we have a realtimeUrl (that takes priority)
+    if (realtimeUrl) return null;
+    // Skip in realtime mode
+    if (mode === "realtime") return null;
+    // L3 shops: a signer is installed (window.snowcone.signMockupUrl), so the
+    // static URL must be signed asynchronously (see the generation effect below).
+    // Skip the synchronous unsigned first-paint to avoid a 403 flash.
+    if (
+      typeof window !== "undefined" &&
+      (window as unknown as { snowcone?: { signMockupUrl?: unknown } }).snowcone
+        ?.signMockupUrl
+    ) {
+      return null;
+    }
+    // Skip if context is still loading
+    if (context?.loading) return null;
+    // Skip if no valid artwork
+    if (!effectiveArtworkSrc || effectiveArtworkSrc.trim() === "") return null;
+    // Skip if missing required IDs or width not yet measured
+    if (!actualProductId || !actualMockupId || !actualGvid || actualGvid === "default" || !width) return null;
+
+    // Get placements for design creation
+    const allPlacements = product?.placements || context?.product?.placements || [];
+    if (allPlacements.length === 0) return null;
+
+    // Build placementDesigns with alignment info from design context
+    // This ensures alignment changes trigger URL regeneration
+    const placementDesigns: Record<string, PlacementDesign> = {};
+    if (designContext?.getPlacementDesign && allPlacements) {
+      for (const p of allPlacements) {
+        // Skip color placements
+        if (p.type === "color") continue;
+        const design = designContext.getPlacementDesign(p.label);
+        placementDesigns[p.label] = {
+          imageUrl: effectiveArtworkSrc,
+          alignment: design?.alignment || "center",
+        } as PlacementDesign;
+      }
+    }
+
+    // Create design for the URL
+    const design = createDesignForPlacements(allPlacements, images, {
+      artworkSrc: effectiveArtworkSrc,
+      placementDesigns,
+    });
+    if (!design || design.length === 0) return null;
+
+    // Build the static URL through the SIGNING RESOLVER (img), not the unsigned
+    // direct-renderer builder: the renderer now mandates a `seal` that only the
+    // resolver adds (ADR-0076).
+    return buildHeroMockupUrl({
+      productCode: actualProductId,
+      design,
+      placements: allPlacements,
+      mockupId: actualMockupId,
+      variantId: actualGvid,
+      width,
+    });
+  }, [
+    realtimeUrl,
+    mode,
+    context?.loading,
+    effectiveArtworkSrc,
+    actualProductId,
+    actualMockupId,
+    actualGvid,
+    product?.placements,
+    context?.product?.placements,
+    images,
+    width,
+    effects,
+    // Include placements to trigger recomputation when alignment changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    JSON.stringify(designContext?.placements),
+  ]);
+
+  // Use the state machine hook for image transitions
+  // SAFARI FIX: Pass initialStaticUrl so the img element exists from the first render
+  // This prevents the flash caused by Safari not decoding images added after initial render
+  const {
+    layers,
+    setTargetUrl,
+    addLayerDirectly,
+    onImageLoad,
+    onLayerTransitionEnd,
+    durations,
+    showShimmer,
+    shimmerOpacity,
+  } = useImageTransition({
+    fadeDuration,
+    shimmerDelay,
+    initialUrl: realtimeUrl || initialStaticUrl,
+  });
+
+  // Error state
+  const [error, setError] = useState<string | null>(null);
+
+  // SAFARI FIX: Disable visibility-based loading - always compute URLs immediately.
+  // Safari handles lazy loading natively, and state changes when images scroll into view
+  // can cause a flash. Let Safari manage everything by computing all URLs on mount.
+  const [isInPreloadZone, setIsInPreloadZone] = useState(true);
+
+  // Refs
+  const componentIdRef = useRef<string>(
+    `hero-product-image-${Math.random().toString(36).substr(2, 9)}`
+  );
+  const [containerMounted, setContainerMounted] = useState(false);
+  const setContainerRef = useCallback((node: HTMLDivElement | null) => {
+    containerRef.current = node;
+    setContainerMounted(!!node);
+  }, []);
+  // Initialize lastUrlRef with computed initial URL, so deduplication works
+  const lastUrlRef = useRef<string | null>(realtimeUrl ?? initialStaticUrl ?? null);
+  const priorityRegisteredRef = useRef(false);
+  // Track if external onLoad has been called (only call once per load)
+  const onLoadCalledRef = useRef(false);
+  // Track previous artwork src to detect changes and clear cache
+  const prevArtworkSrcRef = useRef<string | undefined>(undefined);
+  // Track which artwork the current realtimeUrl is for (to detect stale realtime URLs)
+  const realtimeArtworkSrcRef = useRef<string | undefined>(undefined);
+  // Track whether we've received a realtime result (for auto mode to switch from static to realtime)
+  const hasReceivedRealtimeRef = useRef(false);
+  // Track whether there's a pending export (to skip static URL generation during realtime updates)
+  const isPendingExportRef = useRef(false);
+  // Ref for onUrlGenerated callback (used in realtime subscription without adding to deps)
+  const onUrlGeneratedRef = useRef(onUrlGenerated);
+  onUrlGeneratedRef.current = onUrlGenerated;
+
+  // Track layers.length in a ref so we can read it without depending on it
+  // This prevents effect re-runs when layers change (which would cause duplicate requests)
+  const layersLengthRef = useRef(layers.length);
+  layersLengthRef.current = layers.length;
+
+  // Visibility-based preloading: observe when container enters preload zone (1000px margin)
+  // Priority 1 mockups are already in preload zone, others wait until they approach viewport
+  useEffect(() => {
+    // Priority 1 already set isInPreloadZone=true on init
+    if (initialPriority === 1) return;
+    // Need a mounted container to observe
+    if (!containerMounted || !containerRef.current) return;
+    // Already in preload zone, no need to observe
+    if (isInPreloadZone) return;
+
+    // SSR check
+    if (typeof IntersectionObserver === "undefined") {
+      setIsInPreloadZone(true);
+      return;
+    }
+
+    const unobserve = observe(
+      containerRef.current,
+      (entry) => {
+        if (entry.isIntersecting) {
+          setIsInPreloadZone(true);
+        }
+      },
+      { rootMargin: "1000px 0px", threshold: 0 }
+    );
+
+    return unobserve;
+  }, [containerMounted, initialPriority, isInPreloadZone]);
+
+  // Handle realtimeUrl prop passed directly from parent
+  // This bypasses cache lookup and is more reliable for carousel decode window scenarios
+  // Uses addLayerDirectly so actual <img> element loads with loading="eager" fetchPriority="high"
+  useEffect(() => {
+    if (!realtimeUrl) return;
+    if (realtimeUrl === lastUrlRef.current) return;
+
+    lastUrlRef.current = realtimeUrl;
+    // Track which artwork this realtimeUrl is for (used to detect stale realtime URLs)
+    realtimeArtworkSrcRef.current = artworkSrc || selectedArtworkSrc;
+    // addLayerDirectly handles shimmer timing internally (500ms delay)
+    // SAFARI FIX: Skip transition for initial load to prevent flash
+    const isInitialLoad = layersLengthRef.current === 0;
+    addLayerDirectly(realtimeUrl, { skipTransition: isInitialLoad });
+  }, [realtimeUrl, addLayerDirectly, actualMockupId, placement]);
+
+  // Watch for realtime mockup results from centralized cache
+  // The provider handles cache-busting, so we just need to react to changes
+  // Note: If realtimeUrl prop is provided, that takes priority
+  // Uses addLayerDirectly so actual <img> element loads with loading="eager" fetchPriority="high"
+  useEffect(() => {
+    // Only subscribe in realtime or auto modes
+    if (mode === "static") {
+      return;
+    }
+    // Skip if realtimeUrl prop is provided - parent is handling URL management
+    if (realtimeUrl) {
+      return;
+    }
+    if (!actualMockupId) {
+      return;
+    }
+
+    // Always check for cached URL, even when not configured (e.g., after exiting editor)
+    // This preserves the last realtime mockup instead of falling back to static
+    const existingUrl = realtimeContext?.getMockupUrl?.(actualMockupId);
+    if (existingUrl && existingUrl !== lastUrlRef.current) {
+      hasReceivedRealtimeRef.current = true;
+      lastUrlRef.current = existingUrl;
+      // addLayerDirectly handles shimmer timing internally (500ms delay)
+      // SAFARI FIX: Skip transition for initial load to prevent flash
+      const isInitialLoad = layersLengthRef.current === 0;
+      addLayerDirectly(existingUrl, { skipTransition: isInitialLoad });
+    }
+
+    // Subscribe for updates - no need to wait for isConfigured since subscription
+    // is safe to set up early (it will just receive results once connected)
+    // The mobile carousel also subscribes without checking isConfigured
+    const subscribeFn = realtimeContext?.subscribeMockupResultById;
+    if (!subscribeFn) return;
+
+    const handleMockupResult = (result: {
+      mockupId: string;
+      imageUrl: string;
+    }) => {
+      if (!result?.imageUrl) return;
+
+      // Mark that we've received a realtime result (for auto mode)
+      hasReceivedRealtimeRef.current = true;
+      // Clear pending flag - realtime result has arrived
+      isPendingExportRef.current = false;
+
+      // Get the cache-busted URL from the centralized cache
+      // The provider already adds cache-busting, so we use getMockupUrl()
+      const cachedUrl = realtimeContext.getMockupUrl(result.mockupId);
+      if (!cachedUrl) return;
+
+      // Skip if this is the same URL we already have
+      if (cachedUrl === lastUrlRef.current) return;
+      lastUrlRef.current = cachedUrl;
+
+      // addLayerDirectly handles shimmer timing internally (500ms delay)
+      // SAFARI FIX: Skip transition for initial load to prevent flash
+      const isInitialLoad = layersLengthRef.current === 0;
+      addLayerDirectly(cachedUrl, { skipTransition: isInitialLoad });
+      // Notify parent of the new realtime URL (for ImageEdgeBlur, etc.)
+      onUrlGeneratedRef.current?.(cachedUrl);
+    };
+
+    const unsubscribe = subscribeFn(actualMockupId, handleMockupResult);
+    return () => {
+      unsubscribe?.();
+    };
+  }, [
+    mode,
+    realtimeUrl,
+    realtimeContext?.subscribeMockupResultById,
+    realtimeContext?.getMockupUrl,
+    actualMockupId,
+    addLayerDirectly,
+    // NOTE: layers.length removed - use layersLengthRef instead to prevent duplicate requests
+  ]);
+
+  // Subscribe to pending export notifications
+  // Marks pending to prevent static URL effect from adding a layer while export is in progress
+  // Shimmer is handled by addLayerDirectly with a 500ms delay (skipped for fast loads)
+  useEffect(() => {
+    // Only subscribe in realtime or auto modes
+    if (mode === "static") return;
+    if (!realtimeContext?.subscribePendingBlob || !placement) return;
+
+    const handlePendingExport = (pendingPlacement: string) => {
+      // Only mark pending if this is for our placement
+      if (pendingPlacement === placement) {
+        // Mark as pending to prevent static URL effect from adding a layer
+        isPendingExportRef.current = true;
+      }
+    };
+
+    const unsubscribe = realtimeContext.subscribePendingBlob(handlePendingExport);
+    return () => {
+      unsubscribe?.();
+    };
+  }, [mode, realtimeContext?.subscribePendingBlob, placement]);
+
+  // Register with priority context
+  useEffect(() => {
+    if (!priorityContext || !actualMockupId || !placement) return;
+
+    priorityContext.registerMockup(actualMockupId, placement, initialPriority);
+    priorityRegisteredRef.current = true;
+
+    return () => {
+      if (priorityRegisteredRef.current) {
+        priorityContextRef.current?.unregisterMockup(actualMockupId);
+        priorityRegisteredRef.current = false;
+      }
+    };
+  }, [priorityContext, actualMockupId, placement, initialPriority]);
+
+  // Pass element ref to priority context
+  useEffect(() => {
+    if (!priorityContext?.updateElementRef || !actualMockupId) return;
+
+    if (containerMounted && containerRef.current) {
+      priorityContext.updateElementRef(actualMockupId, containerRef.current);
+    }
+
+    return () => {
+      priorityContextRef.current?.updateElementRef?.(actualMockupId, null);
+    };
+  }, [priorityContext, containerMounted, actualMockupId]);
+
+  // Extract only PRIMITIVE values we need from contexts to avoid
+  // recreating the callback when object references change.
+  // This prevents infinite render loops.
+  const getPlacementDesign = designContext?.getPlacementDesign;
+
+  // Extract primitives from artwork prop (artworkSrc and selectedArtworkSrc defined above for initial URL)
+  const artworkType = artwork?.type;
+  const artworkTileCount =
+    artwork?.type === "pattern" ? artwork?.tileCount : undefined;
+
+  // Extract primitives from context (selectedArtworkSrc defined above for initial URL)
+  const selectedArtworkType = designContext?.selectedArtwork?.type;
+  const selectedArtworkTileCount =
+    designContext?.selectedArtwork?.type === "pattern"
+      ? designContext?.selectedArtwork?.tileCount
+      : undefined;
+
+  // Detect artwork changes and reset local URL tracking
+  // This ensures we don't skip updates when artwork changes
+  useEffect(() => {
+    const currentSrc = artworkSrc || selectedArtworkSrc;
+    if (currentSrc !== prevArtworkSrcRef.current) {
+      // Artwork changed - reset local tracking so next update is applied
+      lastUrlRef.current = null;
+      prevArtworkSrcRef.current = currentSrc;
+      // Reset onLoad tracking so it fires again for new artwork
+      onLoadCalledRef.current = false;
+      // Reset realtime tracking so static URL generation isn't blocked
+      hasReceivedRealtimeRef.current = false;
+      // Reset realtime artwork tracking so stale URLs are detected correctly
+      realtimeArtworkSrcRef.current = undefined;
+    }
+  }, [artworkSrc, selectedArtworkSrc]);
+
+  // Keep refs to objects we need to pass through (these don't need to trigger re-creation)
+  const contextSelectionRef = useRef(context?.selection);
+  const contextOptionAttributesRef = useRef(context?.optionAttributes);
+  contextSelectionRef.current = context?.selection;
+  contextOptionAttributesRef.current = context?.optionAttributes;
+
+  // Wrapper for createDesignForPlacements
+  const createDesignForPlacementsWrapper = useCallback(
+    (
+      placements: any[],
+      providedImages?: DesignElement[]
+    ): DesignElement[] | null => {
+      const effectiveArtworkSrc = artworkSrc || selectedArtworkSrc;
+
+      if (
+        !effectiveArtworkSrc ||
+        effectiveArtworkSrc.trim() === "" ||
+        effectiveArtworkSrc === "undefined" ||
+        effectiveArtworkSrc === "null"
+      ) {
+        return [];
+      }
+
+      const placementDesigns: Record<string, PlacementDesign> = {};
+      if (getPlacementDesign && placements) {
+        for (const p of placements) {
+          // Skip color placements - treat null/undefined/missing type as "image" (default)
+          if (p.type === "color") continue;
+          const design = getPlacementDesign(p.label);
+          // Always create a placement design with current artwork
+          // Use alignment from context if available, otherwise default to center
+          placementDesigns[p.label] = {
+            imageUrl: effectiveArtworkSrc,
+            alignment: design?.alignment || "center",
+          };
+        }
+      }
+
+      // Get tiles from multiple sources (in order of priority):
+      // 1. Placement design tiles (set by TileCount slider with placement prop)
+      // 2. Explicit artwork prop tileCount
+      // 3. Design context selectedArtwork tileCount
+      // 4. undefined (no tiles)
+      // Note: We check the first placement's design for tiles since patterns apply globally
+      // IMPORTANT: Only apply tiles if the current artwork is a pattern!
+      // This prevents stale placement tiles from being applied to regular artwork.
+      const firstPlacement = placements.find((p: any) => p.type !== "color");
+      const placementTiles = firstPlacement
+        ? getPlacementDesign?.(firstPlacement.label)?.tiles
+        : undefined;
+
+      // Determine if current artwork is a pattern (check both explicit prop and context)
+      const isCurrentArtworkPattern =
+        artworkType === "pattern" || selectedArtworkType === "pattern";
+
+      // Only apply tiles if current artwork is a pattern
+      const tiles = isCurrentArtworkPattern
+        ? placementTiles
+          ? (placementTiles as 0.25 | 0.5 | 1 | 2 | 4)
+          : artworkTileCount
+          ? (artworkTileCount as 0.25 | 0.5 | 1 | 2 | 4)
+          : selectedArtworkTileCount
+          ? (selectedArtworkTileCount as 0.25 | 0.5 | 1 | 2 | 4)
+          : undefined
+        : undefined;
+
+      return createDesignForPlacements(placements, providedImages, {
+        selection: contextSelectionRef.current,
+        attributes: contextOptionAttributesRef.current,
+        artworkSrc: effectiveArtworkSrc,
+        placementDesigns: placementDesigns,
+        tiles: tiles,
+      });
+    },
+    [
+      getPlacementDesign,
+      artworkSrc,
+      artworkType,
+      artworkTileCount,
+      selectedArtworkSrc,
+      selectedArtworkType,
+      selectedArtworkTileCount,
+    ]
+  );
+
+  // Generate static mockup URL
+  // This runs even when realtimeUrl is provided - realtimeUrl is for keeping the OLD
+  // image visible while we generate and load the NEW image with current artwork
+  useEffect(() => {
+    // Skip entirely in realtime mode - only use realtime subscription for mockups
+    if (mode === "realtime") return;
+
+    // SAFARI FIX: Skip if we already have initialStaticUrl computed during render.
+    // The useImageTransition hook was initialized with this URL, so calling addLayerDirectly
+    // would just trigger unnecessary state changes (decode(), markAsLoaded, etc.) that
+    // cause re-renders and flash in Safari.
+    // Only run this effect for SUBSEQUENT artwork changes, not initial load.
+    if (initialStaticUrl && lastUrlRef.current === initialStaticUrl) {
+      return;
+    }
+
+    // VISIBILITY-BASED LOADING: Skip until component is in preload zone (1000px from viewport)
+    // This prevents all mockups from loading at once on page load (Safari optimization)
+    // Priority 1 mockups start with isInPreloadZone=true so they load immediately
+    if (!isInPreloadZone) return;
+
+    // Check for valid artwork (use primitive values from outer scope)
+    const effectiveArtwork = artworkSrc || selectedArtworkSrc;
+
+    // Wait for context to load
+    if (context?.loading) {
+      return;
+    }
+    const hasValidArtwork =
+      effectiveArtwork &&
+      effectiveArtwork.trim() !== "" &&
+      effectiveArtwork !== "undefined" &&
+      effectiveArtwork !== "null";
+
+    if (!hasValidArtwork) {
+      setTargetUrl(null);
+      return;
+    }
+
+    // Check for required props
+    if (
+      !actualProductId ||
+      !actualMockupId ||
+      !actualGvid ||
+      actualGvid === "default" ||
+      !width
+    ) {
+      return;
+    }
+
+    // Pre-generate URL
+    const allPlacements =
+      product?.placements || context?.product?.placements || [];
+    const designToUse = createDesignForPlacementsWrapper(allPlacements, images);
+
+    if (designToUse === null) {
+      return;
+    }
+
+    const url = buildHeroMockupUrl({
+      productCode: actualProductId,
+      design: designToUse,
+      placements: allPlacements,
+      mockupId: actualMockupId,
+      variantId: actualGvid,
+      width: width,
+    });
+    if (!url) return;
+
+    // Skip if we already requested this exact URL
+    // This prevents infinite loops where the effect keeps calling setTargetUrl
+    // with the same URL, which triggers state updates that re-trigger the effect.
+    //
+    // IMPORTANT: We do NOT check layers.length here because:
+    // 1. lastUrlRef is set BEFORE calling setTargetUrl (line below)
+    // 2. So on subsequent effect runs, we'll skip even if the image hasn't loaded yet
+    // 3. This prevents the infinite loop that occurred when layers.length === 0
+    //
+    // For initial load / navigation / StrictMode remount:
+    // - lastUrlRef starts as null, so url !== lastUrlRef.current, and we proceed
+    if (url === lastUrlRef.current) return;
+
+    // Update lastUrlRef IMMEDIATELY when we decide to request a new URL
+    lastUrlRef.current = url;
+
+    // If we have a realtimeUrl (old image showing), show shimmer during transition
+    // Use addLayerDirectly so the actual <img> element loads with loading="eager" fetchPriority="high"
+    // This lets Safari track images in its "Images" memory category
+    const hasExistingImage = !!realtimeUrl || layersLengthRef.current > 0;
+    setError(null);
+
+    // Skip adding layer if realtimeUrl is for the CURRENT artwork
+    // If artwork changed, the realtimeUrl is stale and we should show the new static URL
+    const currentArtworkSrc = artworkSrc || selectedArtworkSrc;
+    const isRealtimeUrlFresh = realtimeUrl && realtimeArtworkSrcRef.current === currentArtworkSrc;
+
+    if (isRealtimeUrlFresh) {
+      // Pass the realtimeUrl (not static url) since it's already showing correctly
+      onUrlGeneratedRef.current?.(realtimeUrl);
+      return;
+    }
+
+    // Skip adding static layer if there's a pending export
+    // The realtime result will arrive shortly with the correct mockup
+    if (isPendingExportRef.current) {
+      // Don't call onUrlGenerated during pending - wait for realtime result
+      return;
+    }
+
+    // In auto mode, skip static layer if we've already received realtime results
+    // This preserves the realtime mockup when exiting the editor
+    if (mode === "auto" && hasReceivedRealtimeRef.current) {
+      // Don't call onUrlGenerated - let the realtime URL stay as-is
+      return;
+    }
+    // Use addLayerDirectly - lets the actual <img> handle loading
+    // Shimmer timing is handled internally (500ms delay, skipped for fast/cached loads)
+    // SAFARI FIX: Skip transition for initial load (when no existing layers) to prevent flash
+    // The fade transition is only useful for artwork changes, not initial display
+    const isInitialLoad = layersLengthRef.current === 0;
+    const render = (finalUrl: string) => {
+      // Guard against a newer URL having been requested while we were signing.
+      if (lastUrlRef.current !== url) return;
+      addLayerDirectly(finalUrl, { skipTransition: isInitialLoad });
+      // Use ref to avoid re-running this effect when onUrlGenerated changes
+      // This prevents static URL from overwriting realtime URL on parent re-render
+      onUrlGeneratedRef.current?.(finalUrl);
+    };
+    // L3 shops: the host app installs `window.snowcone.signMockupUrl` to append
+    // an &signature (the resolver rejects unsigned URLs). Without it (L0), the
+    // public URL renders as-is.
+    const signer =
+      typeof window !== "undefined"
+        ? (window as unknown as {
+            snowcone?: { signMockupUrl?: (u: string) => Promise<string> };
+          }).snowcone?.signMockupUrl
+        : undefined;
+    if (signer) {
+      signer(url)
+        .then((signed) => render(signed || url))
+        .catch(() => render(url));
+    } else {
+      render(url);
+    }
+  }, [
+    mode,
+    isInPreloadZone, // Visibility-based loading: only generate URL when in preload zone
+    // NOTE: realtimeContext?.isConfigured intentionally NOT included
+    // We don't want to re-run static URL generation when realtime is disabled
+    // The artwork change detection effect handles clearing the cache when needed
+    actualProductId,
+    actualMockupId,
+    actualGvid,
+    images,
+    width,
+    effects,
+    // Use primitive values extracted at the top of the component
+    artworkSrc,
+    artworkType,
+    artworkTileCount,
+    selectedArtworkSrc,
+    selectedArtworkType,
+    selectedArtworkTileCount,
+    // Stringify arrays/objects to create stable string dependencies
+    JSON.stringify(product?.placements),
+    JSON.stringify(context?.selection),
+    JSON.stringify(context?.product?.placements),
+    JSON.stringify(designContext?.placements),
+    context?.loading,
+    addLayerDirectly,
+    createDesignForPlacementsWrapper,
+    // NOTE: onUrlGenerated intentionally NOT included - use onUrlGeneratedRef instead
+    // This prevents the static URL effect from re-running on parent re-renders,
+    // which would overwrite the realtime URL that was just set by handleMockupResult
+    realtimeUrl,
+    // NOTE: Do NOT include layers or preloadUrl as dependencies!
+    // They change when addLayerDirectly is called, which would cause infinite loops.
+    // The useImageTransition hook handles deduplication internally.
+  ]);
+
+  // Check if we have artwork (effectiveArtworkSrc defined at top of component)
+  const hasArtwork =
+    effectiveArtworkSrc &&
+    effectiveArtworkSrc.trim() !== "" &&
+    effectiveArtworkSrc !== "undefined" &&
+    effectiveArtworkSrc !== "null";
+
+  // DISPLAY URL PRIORITY:
+  // 1. layers (if we have any) - this includes realtime mockup updates
+  // 2. realtimeUrl prop (passed from parent)
+  // 3. initialStaticUrl (computed at mount)
+  //
+  // Note: We MUST read from layers for realtime updates to work.
+  // The realtime subscription calls addLayerDirectly() which updates layers state.
+  const topLayer = layers[layers.length - 1];
+  const displayUrl = topLayer?.url || realtimeUrl || initialStaticUrl;
+
+  // CSS crossfade: two stacked <img> elements. When displayUrl changes,
+  // the old image stays visible while the new one fades in on top.
+  // No View Transition API — stays in normal stacking context, no z-index issues.
+  //
+  // IMPORTANT: these hooks (and the crossfade `useEffect` below) MUST stay
+  // above the `!hasArtwork` / `error` early-return branches. Otherwise React
+  // sees a different hook count per render whenever artwork (un)loads or an
+  // error toggles, and throws "change in the order of Hooks called by
+  // HeroProductImage". Same rule for any new hook added in this component.
+  const CROSSFADE_MS = 400;
+  const [prevUrl, setPrevUrl] = useState<string | null>(null);
+  const [showNew, setShowNew] = useState(false);
+  // `renderedUrl` is what the visible <img> actually paints. We delay updating
+  // it from `displayUrl` until the new image is preloaded, so the displayed
+  // <img> never flashes the new src before the prevUrl crossfade-from layer
+  // is in place. Without this delay, when the browser already has the new
+  // image cached, the visible <img> snaps to NEW immediately, then the
+  // useEffect runs and overlays prevUrl (showing OLD on top), then prevUrl
+  // fades out to reveal NEW again — i.e. the new → old → new flash.
+  const [renderedUrl, setRenderedUrl] = useState<string | null>(displayUrl);
+  // `renderedUrl` is set as soon as a URL exists, but the <img> paints nothing
+  // until the render is actually fetched (seconds, on a cold render). Keep the
+  // pulsing skeleton up until the first image has painted.
+  const [firstImageLoaded, setFirstImageLoaded] = useState(false);
+  const prevDisplayUrlRef = useRef<string | null>(displayUrl);
+  // Fire the L3 "you forgot signMockupUrl" dev hint at most once per component.
+  const signHintShownRef = useRef(false);
+
+  useEffect(() => {
+    if (!displayUrl || displayUrl === prevDisplayUrlRef.current) return;
+    const oldUrl = prevDisplayUrlRef.current;
+    prevDisplayUrlRef.current = displayUrl;
+
+    // Initial load — no crossfade. Just update rendered URL.
+    if (!oldUrl) {
+      setRenderedUrl(displayUrl);
+      return;
+    }
+
+    // Preload new image, then atomically: set prevUrl = old, set rendered = new.
+    // Both happen in the same render so the user always sees either OLD or
+    // OLD-on-top-of-NEW, never bare NEW before prev is in place.
+    const preload = new Image();
+    preload.crossOrigin = 'anonymous';
+    preload.src = displayUrl;
+    const startCrossfade = () => {
+      setPrevUrl(oldUrl);
+      setRenderedUrl(displayUrl);
+      setShowNew(false);
+      // Trigger fade-in on next frame so the CSS transition plays
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => setShowNew(true));
+      });
+    };
+    if (preload.complete) startCrossfade();
+    else preload.onload = startCrossfade;
+
+    return () => { preload.onload = null; };
+  }, [displayUrl]);
+
+  // Clean up old layer after crossfade completes
+  const handleCrossfadeEnd = useCallback(() => {
+    setPrevUrl(null);
+    setShowNew(false);
+  }, []);
+
+  // Early returns now go AFTER every hook above so React sees a stable
+  // hook count regardless of artwork / error state.
+  if (!hasArtwork) {
+    return (
+      <div
+        className={`bg-gray-100 flex items-center justify-center ${
+          className || ""
+        }`}
+        style={style}
+      >
+        <div className="text-gray-400 text-center p-4">
+          <svg
+            className="w-8 h-8 mx-auto mb-2"
+            fill="none"
+            stroke="currentColor"
+            viewBox="0 0 24 24"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={1.5}
+              d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z"
+            />
+          </svg>
+          <p className="text-xs">No artwork</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div
+        className={`bg-red-50 flex items-center justify-center ${
+          className || ""
+        }`}
+        style={style}
+      >
+        <div className="text-red-600 text-center p-4">
+          <p className="text-xs">Error loading</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={setContainerRef}
+      className={`relative overflow-hidden ${className || ""}`}
+      style={style}
+      data-hero-image="true"
+    >
+      {/* Loading skeleton — painted UNDER the <img> so the image covers it the
+          instant it renders, with no state-flush flash. Removed once the first
+          image has loaded; later URL changes crossfade over a visible image. */}
+      {!firstImageLoaded && (
+        <div className="absolute inset-0 bg-muted-foreground/20 animate-pulse" />
+      )}
+
+      {/* Current image — shows `renderedUrl`, which the crossfade effect only
+          advances after the next image has finished preloading. This prevents
+          the new → old → new flash that happened when displayUrl was bound
+          directly to <img src> (the browser snapped to NEW from the cache
+          before prevUrl could be staged on top, then prevUrl appeared and
+          covered NEW with OLD, then OLD faded back to NEW). */}
+      {renderedUrl && (
+        <img
+          alt={`Product mockup${placement ? ` - ${placement}` : ""}`}
+          crossOrigin="anonymous"
+          className="absolute inset-0 w-full h-full object-cover"
+          draggable={draggable}
+          src={renderedUrl}
+          loading="eager"
+          // eslint-disable-next-line react/no-unknown-property
+          fetchPriority="high"
+          onClick={onClick}
+          onLoad={() => {
+            setFirstImageLoaded(true);
+            if (!onLoadCalledRef.current && onLoad) {
+              onLoadCalledRef.current = true;
+              onLoad();
+            }
+            onUrlGeneratedRef.current?.(renderedUrl);
+          }}
+          onError={() => {
+            setFirstImageLoaded(true);
+            onError?.();
+            // Dev-only guidance for the most common signed-shop trap: a mockup
+            // <img> that loads an UNSIGNED resolver URL gets a 403 "Missing
+            // required signature", with nothing pointing at the fix.
+            if (
+              process.env.NODE_ENV !== "production" &&
+              !signHintShownRef.current &&
+              renderedUrl &&
+              /\/[A-Za-z0-9]+\?/.test(renderedUrl) &&
+              !/[?&]signature=/.test(renderedUrl)
+            ) {
+              signHintShownRef.current = true;
+              const hasSigner =
+                typeof window !== "undefined" &&
+                !!(
+                  window as unknown as {
+                    snowcone?: { signMockupUrl?: unknown };
+                  }
+                ).snowcone?.signMockupUrl;
+              console.warn(
+                hasSigner
+                  ? "[Snowcone] A mockup image failed to load and its URL is unsigned. " +
+                      "Your `signMockupUrl` likely errored — check your /api/sign route " +
+                      "and that its secret matches the shop's signing secret."
+                  : "[Snowcone] A mockup image failed to load (likely 'Missing required " +
+                      "signature'). If your shop requires signed URLs, pass `signMockupUrl` " +
+                      "to <Shop> so the UI can sign mockup <img> URLs. Docs: " +
+                      "https://developers.snowcone.app/design-system/signing-at-scale",
+              );
+            }
+          }}
+        />
+      )}
+
+      {/* Previous image — fades out during crossfade */}
+      {prevUrl && (
+        <img
+          alt=""
+          crossOrigin="anonymous"
+          className="absolute inset-0 w-full h-full object-cover"
+          src={prevUrl}
+          style={{
+            opacity: showNew ? 0 : 1,
+            transition: `opacity ${CROSSFADE_MS}ms ease-in-out`,
+            pointerEvents: 'none',
+          }}
+          onTransitionEnd={handleCrossfadeEnd}
+        />
+      )}
+
+      {/* SAFARI FIX: Disabled shimmer overlay - it depends on layers state which causes re-renders */}
+      {/* {showShimmer && layers.length > 0 && (
+        <div
+          className="absolute inset-0 z-10 pointer-events-none bg-black/30"
+          style={{
+            opacity: shimmerOpacity,
+            transition: `opacity ${
+              shimmerOpacity === 1
+                ? durations.darkShimmerFadeIn
+                : durations.fade
+            }ms ease-out`,
+          }}
+        />
+      )} */}
+    </div>
+  );
+});