@snowcone-app/ui 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/ui",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "React components for merchandise visualization and customization",
   "keywords": [
     "react",
@@ -103,7 +103,7 @@
     "react-instantsearch": "^7.15.5",
     "react-zoom-pan-pinch": "^3.6.4",
     "tailwind-merge": "^3.0.0",
-    "@snowcone-app/sdk": "0.17.0"
+    "@snowcone-app/sdk": "0.17.1"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.2",

package/src/composed/HeroProductImage.tsx

@@ -16,6 +16,7 @@ import {
 import { useShopOptional } from "../patterns/ShopProvider";
 import { useRealtimeOptional } from "../patterns/RealtimeProvider";
 import { useMockupPriorityOptional } from "../patterns/MockupPriorityProvider";
+import { LoadingOverlayPrismCandyInline } from "../components/LoadingOverlayPrismCandy";
 import {
   createDesignForPlacements,
   type DesignElement,
@@ -880,8 +881,29 @@ export const HeroProductImage = memo(function HeroProductImage({
   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.
+  // rainbow loader up until the first image has painted.
   const [firstImageLoaded, setFirstImageLoaded] = useState(false);
+  // The loader lingers one beat past `firstImageLoaded` so it can fade OUT —
+  // revealing the freshly-loaded image beneath in the same crossfade — instead
+  // of vanishing the instant the image paints. Unmounted on the overlay's
+  // onExited (fade-out complete).
+  const [loaderMounted, setLoaderMounted] = useState(true);
+  // The visible <img> failed to load (dead/expired URL — e.g. a revoked blob:
+  // from an in-progress design, or a stale signed mockup URL on a later visit).
+  // Tracked so we can UNMOUNT the broken <img> and show a clean fallback
+  // instead of the browser's native broken-image glyph. Reset on every new
+  // URL attempt (below) so a fresh render can recover.
+  const [imgFailed, setImgFailed] = useState(false);
+  // One-shot cache-bust retry. A reload / Safari bfcache restore can serve a
+  // mockup from WebKit's disk cache as a CORS-less entry (cached by an earlier
+  // non-crossorigin request), which then fails the crossorigin <img> here and
+  // paints a broken image. On the FIRST load failure for a URL we retry once
+  // with a `_cb` query param — a fresh URL can't hit the poisoned cache entry.
+  // This fires ONLY on failure, so the cached happy path (and realtime, which
+  // already cache-busts via `_t`) is untouched; only a genuinely-broken image
+  // pays the re-fetch. A second failure falls through to the clean fallback.
+  const [retryNonce, setRetryNonce] = useState(0);
+  const retriedUrlRef = useRef<string | null>(null);
   const prevDisplayUrlRef = useRef<string | null>(displayUrl);
   // Fire the L3 "you forgot signMockupUrl" dev hint at most once per component.
   const signHintShownRef = useRef(false);
@@ -890,6 +912,10 @@ export const HeroProductImage = memo(function HeroProductImage({
     if (!displayUrl || displayUrl === prevDisplayUrlRef.current) return;
     const oldUrl = prevDisplayUrlRef.current;
     prevDisplayUrlRef.current = displayUrl;
+    // New URL to try — clear any prior load failure so the <img> remounts,
+    // and give this URL a fresh retry budget.
+    setImgFailed(false);
+    retriedUrlRef.current = null;
 
     // Initial load — no crossfade. Just update rendered URL.
     if (!oldUrl) {
@@ -924,6 +950,9 @@ export const HeroProductImage = memo(function HeroProductImage({
     setShowNew(false);
   }, []);
 
+  // Unmount the rainbow loader once its fade-out transition has finished.
+  const handleLoaderExited = useCallback(() => setLoaderMounted(false), []);
+
   // Early returns now go AFTER every hook above so React sees a stable
   // hook count regardless of artwork / error state.
   if (!hasArtwork) {
@@ -976,31 +1005,33 @@ export const HeroProductImage = memo(function HeroProductImage({
       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 && (
+      {renderedUrl && !imgFailed && (
         <img
           alt={`Product mockup${placement ? ` - ${placement}` : ""}`}
           crossOrigin="anonymous"
           className="absolute inset-0 w-full h-full object-cover"
           draggable={draggable}
-          src={renderedUrl}
+          // On a retry, append a cache-bust param so the request can't be
+          // served from the poisoned (CORS-less) disk-cache entry. The base
+          // `renderedUrl` is what we hand back to `onUrlGenerated` — never the
+          // busted variant — so caches/state stay keyed on the canonical URL.
+          src={
+            retriedUrlRef.current === renderedUrl
+              ? `${renderedUrl}${renderedUrl.includes("?") ? "&" : "?"}_cb=${retryNonce}`
+              : renderedUrl
+          }
           loading="eager"
           // eslint-disable-next-line react/no-unknown-property
           fetchPriority="high"
           onClick={onClick}
           onLoad={() => {
+            setImgFailed(false);
             setFirstImageLoaded(true);
             if (!onLoadCalledRef.current && onLoad) {
               onLoadCalledRef.current = true;
@@ -1009,6 +1040,20 @@ export const HeroProductImage = memo(function HeroProductImage({
             onUrlGeneratedRef.current?.(renderedUrl);
           }}
           onError={() => {
+            // First failure for this URL → retry once with a cache-bust before
+            // giving up (recovers a WebKit disk-cache entry cached without CORS
+            // headers). Fires only on failure, so the cached happy path and the
+            // realtime `_t` flow are untouched.
+            if (renderedUrl && retriedUrlRef.current !== renderedUrl) {
+              retriedUrlRef.current = renderedUrl;
+              setRetryNonce((n) => n + 1);
+              return;
+            }
+            // Retry also failed → genuine failure. Unmount the broken <img> so
+            // the browser doesn't paint its native broken-image glyph; a clean
+            // fallback renders in its place below (unless a stale crossfade
+            // image is still available to keep).
+            setImgFailed(true);
             setFirstImageLoaded(true);
             onError?.();
             // Dev-only guidance for the most common signed-shop trap: a mockup
@@ -1044,6 +1089,16 @@ export const HeroProductImage = memo(function HeroProductImage({
         />
       )}
 
+      {/* Image load failed with no stale image to fall back on. Show a neutral
+          panel instead of the browser's broken-image glyph. `prevUrl` (the
+          crossfade-from layer below) is kept when present — a stale mockup
+          beats a blank one — so we only show this when there's nothing else. */}
+      {imgFailed && !prevUrl && (
+        <div className="absolute inset-0 flex items-center justify-center bg-muted">
+          <p className="text-muted-foreground text-xs">Preview unavailable</p>
+        </div>
+      )}
+
       {/* Server render error badge — the realtime renderer rejected the last
           render (e.g. asset_not_allowed). The stale image above stays visible
           on purpose (stale + clearly marked beats blank); the typed code is
@@ -1074,6 +1129,19 @@ export const HeroProductImage = memo(function HeroProductImage({
         />
       )}
 
+      {/* Rainbow prism loader — the same one /create shows while a mockup
+          generates. Rendered LAST so it sits ON TOP of the <img>: the image
+          loads underneath, then the loader fades OUT to reveal it (a quick
+          ~400ms crossfade) instead of the image popping in. First load only;
+          later URL changes use the prevUrl crossfade above. */}
+      {loaderMounted && (
+        <LoadingOverlayPrismCandyInline
+          visible={!firstImageLoaded}
+          variant="light"
+          onExited={handleLoaderExited}
+        />
+      )}
+
       {/* SAFARI FIX: Disabled shimmer overlay - it depends on layers state which causes re-renders */}
       {/* {showShimmer && layers.length > 0 && (
         <div

package/src/composed/SafeImg.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import React, { useEffect, useState } from "react";
+
+export interface SafeImgProps extends React.ImgHTMLAttributes<HTMLImageElement> {
+  /**
+   * Rendered in place of the <img> when the image fails to load. Defaults to
+   * nothing — the broken image simply disappears, so the container's own
+   * background shows instead of the browser's native broken-image glyph.
+   */
+  fallback?: React.ReactNode;
+}
+
+/**
+ * An `<img>` that never paints the browser's native broken-image glyph (the
+ * "?" box on iOS Safari). On a load failure — a dead/expired URL, a revoked
+ * `blob:` from an in-progress design, or a CORS-less disk-cache entry replayed
+ * to a crossorigin request — it unmounts and renders `fallback` (or nothing).
+ *
+ * Use this for any remote/blob image whose URL can go stale. Components with
+ * richer recovery (crossfade, retry, skeletons) like `HeroProductImage` keep
+ * their own handling; this is the simple guard for plain thumbnails/previews.
+ */
+export const SafeImg = React.forwardRef<HTMLImageElement, SafeImgProps>(
+  function SafeImg({ fallback = null, onError, src, ...rest }, ref) {
+    const [failed, setFailed] = useState(false);
+    // A new src is a fresh attempt — clear any prior failure so it can recover.
+    useEffect(() => {
+      setFailed(false);
+    }, [src]);
+
+    if (failed) return <>{fallback}</>;
+
+    return (
+      <img
+        {...rest}
+        ref={ref}
+        src={src}
+        onError={(e) => {
+          setFailed(true);
+          onError?.(e);
+        }}
+      />
+    );
+  },
+);

package/src/composed/carousels/MobileProductCarousel.tsx

@@ -51,10 +51,46 @@ import React, {
 import type { CarouselImage } from "./types";
 import { EnhancedImageViewer } from "../zoom/EnhancedImageViewer";
 import { HeroProductImage } from "../HeroProductImage";
+import { LoadingOverlayPrismCandyInline } from "../../components/LoadingOverlayPrismCandy";
 import type { ArtworkData } from "@snowcone-app/sdk";
 import { useMockupPriorityOptional } from "../../patterns/MockupPriorityProvider";
 import { useRealtimeOptional } from "../../patterns/RealtimeProvider";
 
+/**
+ * Static (non-mockup) carousel image with a graceful fallback. A reload or
+ * Safari bfcache restore can leave a dead `src` — a revoked `blob:` URL from an
+ * in-progress design, or an expired signed mockup URL — and without handling
+ * the browser paints its native broken-image icon (the question-mark box).
+ * On load failure we swap to a neutral muted panel so the carousel degrades
+ * cleanly instead of showing a broken image.
+ */
+function StaticCarouselImage({
+  src,
+  alt,
+  className,
+}: {
+  src: string;
+  alt: string;
+  className?: string;
+}) {
+  const [failed, setFailed] = useState(false);
+  if (failed || !src) {
+    return <div className={`bg-muted ${className ?? ""}`} role="img" aria-label={alt} />;
+  }
+  return (
+    <img
+      src={src}
+      alt={alt}
+      crossOrigin="anonymous"
+      className={className}
+      loading="lazy"
+      decoding="async"
+      draggable={false}
+      onError={() => setFailed(true)}
+    />
+  );
+}
+
 export interface MobileProductCarouselProps {
   /** Array of images to display in the carousel */
   images: CarouselImage[];
@@ -838,7 +874,9 @@ export const MobileProductCarousel = memo(function MobileProductCarousel({
                 {!isWithinDecodeWindow ? (
                   <div className="w-full h-full bg-muted" />
                 ) : image.isPlaceholder ? (
-                  <div className="w-full h-full bg-muted-foreground/20 animate-pulse" />
+                  // Rainbow prism loader (same as the /create route) instead of
+                  // a flat pulse; fills this relative slide via inset:0.
+                  <LoadingOverlayPrismCandyInline visible variant="light" />
                 ) : image.isRealMockup && currentArtwork ? (
                   <HeroProductImage
                     productId={productId}
@@ -861,16 +899,12 @@ export const MobileProductCarousel = memo(function MobileProductCarousel({
                     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" />
+                  <LoadingOverlayPrismCandyInline visible variant="light" />
                 ) : (
-                  <img
+                  <StaticCarouselImage
                     src={image.src}
-                    alt={image.label}
-                    crossOrigin="anonymous"
+                    alt={image.label ?? ""}
                     className="w-full h-full object-cover cursor-pointer pointer-events-none"
-                    loading="lazy"
-                    decoding="async"
-                    draggable={false}
                   />
                 )}
               </div>

package/src/composed/search/meilisearchAdapter.ts

@@ -6,7 +6,7 @@ const MEILISEARCH_HOST =
   "https://ms-e5d999b2eaca-15654.sfo.meilisearch.io";
 const MEILISEARCH_API_KEY =
   readEnv("NEXT_PUBLIC_MEILISEARCH_API_KEY") ||
-  "eee819b849798ad9091228c486ec05d0931e5292";
+  "4a11f6599e39af365f6289dab46b77a30ef78ba1ac078f7d74e152c099b3b63c";
 
 const { searchClient } = instantMeiliSearch(
   MEILISEARCH_HOST,

package/src/composed/zoom/EnhancedImageViewer.tsx

@@ -9,6 +9,7 @@ import React, {
   type ComponentType,
 } from "react";
 import { createPortal } from "react-dom";
+import { SafeImg } from "../SafeImg";
 import {
   TransformWrapper as OriginalTransformWrapper,
   TransformComponent as OriginalTransformComponent,
@@ -332,7 +333,7 @@ export const EnhancedImageViewer = ({
                   justifyContent: "center",
                 }}
               >
-                <img
+                <SafeImg
                   ref={imgRef}
                   src={imageUrl}
                   alt={alt}

package/src/index.ts

@@ -191,6 +191,7 @@ export type { ArtworkCustomizerProps } from "./composed/ArtworkCustomizer";
 // TEMPORARY: Canvas editor mockup for testing
 export * from "./composed/CanvasEditor";
 export * from "./composed/HeroProductImage";
+export * from "./composed/SafeImg";
 
 // Re-export types from SDK for convenience
 export type {