@jekrch/react-viewport-lightbox 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -19,8 +19,19 @@ interface ViewerItem<TData = unknown> {
     /** Arbitrary per-slide payload, surfaced as `ctx.item.data` in render slots. */
     data?: TData;
 }
+/**
+ * A rectangle in viewport coordinates. Structurally compatible with the
+ * `DOMRect` returned by `element.getBoundingClientRect()`, so you can pass one
+ * straight through.
+ */
+interface ViewerRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
 /** Named, themeable regions of the viewer that accept a `className` override. */
-type ViewerSlot = "root" | "backdrop" | "topBar" | "bottomBar" | "image" | "button" | "counter" | "navButton" | "navStart" | "navEnd" | "overlay";
+type ViewerSlot = "root" | "backdrop" | "topBar" | "bottomBar" | "image" | "button" | "counter" | "navButton" | "navStart" | "navEnd" | "overlay" | "spinner";
 /** Overridable control icons. Each is a React node rendered inside its button. */
 interface ViewerIcons {
     close: ReactNode;
@@ -79,12 +90,33 @@ interface ImageViewerProps<TData = unknown> {
     onNavigate?: (direction: "prev" | "next") => void;
     /** Called AFTER the exit animation completes. */
     onClose: () => void;
+    /**
+     * Enables a shared-element "zoom from thumbnail" open/close transition. Given
+     * the active index, return the on-screen rect of the source element (e.g. the
+     * gallery thumbnail) — typically `el.getBoundingClientRect()`. The active
+     * image expands from that rect on open and collapses back into it on close.
+     * Return `null` for an index with no on-screen source (or omit the prop
+     * entirely) to fall back to the default fade. Honors reduced-motion.
+     */
+    getOriginRect?: (index: number) => ViewerRect | null;
     /** Enable zoom/pan (wheel, pinch, double-tap). Default `true`. */
     zoom?: boolean;
+    /**
+     * Anchor wheel- and pinch-zoom on the pointer: scrolling zooms toward the
+     * cursor and a pinch zooms toward the gesture midpoint. Set `false` to zoom
+     * about the viewport center instead. Default `true`.
+     */
+    zoomToCursor?: boolean;
     /** Show the `index / total` counter. Default `true`. */
     showCounter?: boolean;
     /** Wrap around at the ends. Default `false`. */
     loop?: boolean;
+    /**
+     * Close the viewer when the empty area around the image (the backdrop) is
+     * clicked. Clicks on the image, the bars, and the control buttons are
+     * unaffected. Default `false`.
+     */
+    closeOnBackdropClick?: boolean;
     /** Top-left title area. */
     renderHeader?: (ctx: ViewerContext<TData>) => ReactNode;
     /** Extra top-right buttons, rendered before the close button. */
@@ -112,7 +144,7 @@ interface ImageViewerProps<TData = unknown> {
  * `onIndexChange`; mount it when open and it runs its own enter/exit animation,
  * calling `onClose` after the exit completes.
  */
-declare function ImageViewer<TData = unknown>({ items, index, onIndexChange, onNavigate, onClose, zoom, showCounter, loop, renderHeader, renderHeaderActions, renderNavStart, renderNavEnd, renderFooter, renderOverlay, classNames, icons, ariaLabel, }: ImageViewerProps<TData>): react.JSX.Element | null;
+declare function ImageViewer<TData = unknown>({ items, index, onIndexChange, onNavigate, onClose, getOriginRect, zoom, zoomToCursor, showCounter, loop, closeOnBackdropClick, renderHeader, renderHeaderActions, renderNavStart, renderNavEnd, renderFooter, renderOverlay, classNames, icons, ariaLabel, }: ImageViewerProps<TData>): react.JSX.Element | null;
 
 interface NavButtonProps {
     direction: "prev" | "next";
@@ -172,7 +204,12 @@ interface ImageZoomPanState {
  */
 declare function useImageZoomPan(imgWrapperRef: RefObject<HTMLDivElement | null>, currentIndex: number, 
 /** When false, wheel-zoom and double-click-zoom are disabled. Default true. */
-enabled?: boolean): ImageZoomPanState;
+enabled?: boolean, 
+/**
+ * When true (default), wheel-zoom anchors on the cursor. When false, it zooms
+ * about the viewport center.
+ */
+zoomToCursor?: boolean): ImageZoomPanState;
 
 interface SlideNavigationState {
     slideTrackRef: React.RefObject<HTMLDivElement | null>;
@@ -195,7 +232,9 @@ interface SlideNavigationState {
  * preloaded/decoded before navigation commits so the swipe lands on a painted
  * frame.
  */
-declare function useSlideNavigation(items: ViewerItem[], currentIndex: number, onNavigate: (index: number) => void, onSlideStart?: (direction: "prev" | "next") => void): SlideNavigationState;
+declare function useSlideNavigation(items: ViewerItem[], currentIndex: number, onNavigate: (index: number) => void, onSlideStart?: (direction: "prev" | "next") => void, 
+/** When true, navigation wraps around the ends instead of stopping. */
+loop?: boolean): SlideNavigationState;
 
 interface GestureHandlers {
     handlePointerDown: (e: React.PointerEvent) => void;
@@ -215,7 +254,12 @@ interface GestureHandlers {
  */
 declare function useGestureHandler(zoomPan: ImageZoomPanState, slide: SlideNavigationState, hasPrev: boolean, hasNext: boolean, 
 /** When false, pinch-zoom and double-tap-zoom are disabled. Default true. */
-zoomEnabled?: boolean): GestureHandlers;
+zoomEnabled?: boolean, 
+/**
+ * When true (default), pinch-zoom anchors on the gesture midpoint. When
+ * false, it zooms about the viewport center.
+ */
+zoomToCursor?: boolean): GestureHandlers;
 
 /**
  * Measures the height of the top and bottom bars so the image area
@@ -274,4 +318,4 @@ declare function resolveSlideDirection({ offset, elapsedMs, viewportWidth, hasPr
  */
 declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, active: boolean): void;
 
-export { ChevronLeftIcon, ChevronRightIcon, CloseIcon, type Dims, type ImageTransform, ImageViewer, type ImageViewerProps, type ImageZoomPanState, MAX_SCALE, MIN_SCALE, NavButton, type ResolveSlideArgs, type SlideAction, type SlideNavigationState, type ViewerContext, type ViewerIcons, type ViewerItem, type ViewerSlot, ZoomInIcon, ZoomOutIcon, clampTranslate, defaultIcons, resolveSlideDirection, useBarMeasure, useBodyScrollLock, useFocusTrap, useGestureHandler, useImageZoomPan, useSlideNavigation };
+export { ChevronLeftIcon, ChevronRightIcon, CloseIcon, type Dims, type ImageTransform, ImageViewer, type ImageViewerProps, type ImageZoomPanState, MAX_SCALE, MIN_SCALE, NavButton, type ResolveSlideArgs, type SlideAction, type SlideNavigationState, type ViewerContext, type ViewerIcons, type ViewerItem, type ViewerRect, type ViewerSlot, ZoomInIcon, ZoomOutIcon, clampTranslate, defaultIcons, resolveSlideDirection, useBarMeasure, useBodyScrollLock, useFocusTrap, useGestureHandler, useImageZoomPan, useSlideNavigation };

package/dist/index.js

@@ -19,6 +19,15 @@ function clampTranslate(x, y, scale, baseDims, viewport) {
     y: Math.max(-maxY, Math.min(maxY, y))
   };
 }
+function zoomToPoint(prevScale, nextScale, prev, focal, viewport) {
+  const relX = focal.x - viewport.width / 2;
+  const relY = focal.y - viewport.height / 2;
+  const k = nextScale / prevScale;
+  return {
+    x: relX * (1 - k) + k * prev.x,
+    y: relY * (1 - k) + k * prev.y
+  };
+}
 function resolveSlideDirection({
   offset,
   elapsedMs,
@@ -39,7 +48,7 @@ function resolveSlideDirection({
 // src/hooks/useImageZoomPan.ts
 var MIN_SCALE = 1;
 var MAX_SCALE = 5;
-function useImageZoomPan(imgWrapperRef, currentIndex, enabled = true) {
+function useImageZoomPan(imgWrapperRef, currentIndex, enabled = true, zoomToCursor = true) {
   const imgRef = useRef(null);
   const [displayScale, setDisplayScale] = useState(1);
   const transformRef = useRef({ scale: 1, x: 0, y: 0 });
@@ -125,12 +134,26 @@ function useImageZoomPan(imgWrapperRef, currentIndex, enabled = true) {
       const step = -(normalized / 100) * 0.05;
       const factor = 1 + step;
       const nextScale = Math.min(MAX_SCALE, Math.max(MIN_SCALE, t.scale * factor));
-      const clamped = nextScale <= 1 ? { x: 0, y: 0 } : clampTranslate2(t.x, t.y, nextScale);
+      let clamped;
+      if (nextScale <= 1) {
+        clamped = { x: 0, y: 0 };
+      } else if (zoomToCursor) {
+        const focal = zoomToPoint(
+          t.scale,
+          nextScale,
+          { x: t.x, y: t.y },
+          { x: e.clientX, y: e.clientY },
+          { width: window.innerWidth, height: window.innerHeight }
+        );
+        clamped = clampTranslate2(focal.x, focal.y, nextScale);
+      } else {
+        clamped = clampTranslate2(t.x, t.y, nextScale);
+      }
       setTransform({ scale: nextScale, ...clamped });
     };
     wrapper.addEventListener("wheel", handleWheel, { passive: false });
     return () => wrapper.removeEventListener("wheel", handleWheel);
-  }, [imgWrapperRef, setTransform, clampTranslate2, enabled]);
+  }, [imgWrapperRef, setTransform, clampTranslate2, enabled, zoomToCursor]);
   const handleDoubleClick = useCallback(
     (e) => {
       if (!enabled) return;
@@ -161,15 +184,15 @@ function useImageZoomPan(imgWrapperRef, currentIndex, enabled = true) {
     handleDoubleClick
   };
 }
-function useSlideNavigation(items, currentIndex, onNavigate, onSlideStart) {
+function useSlideNavigation(items, currentIndex, onNavigate, onSlideStart, loop = false) {
   const slideTrackRef = useRef(null);
   const swipeOffsetRef = useRef(0);
   const [swipeOffset, setSwipeOffset] = useState(0);
   const [slideAnimating, setSlideAnimating] = useState(false);
   const [slideActive, setSlideActive] = useState(false);
   const commitLockRef = useRef(false);
-  const hasPrev = currentIndex > 0;
-  const hasNext = currentIndex < items.length - 1;
+  const hasPrev = loop ? items.length > 1 : currentIndex > 0;
+  const hasNext = loop ? items.length > 1 : currentIndex < items.length - 1;
   const applySlideOffset = useCallback((offset, animate = false) => {
     swipeOffsetRef.current = offset;
     const track = slideTrackRef.current;
@@ -215,7 +238,8 @@ function useSlideNavigation(items, currentIndex, onNavigate, onSlideStart) {
           if (cleaned) return;
           cleaned = true;
           track?.removeEventListener("transitionend", onTransitionEnd);
-          const newIndex = direction === "prev" ? currentIndex - 1 : currentIndex + 1;
+          let newIndex = direction === "prev" ? currentIndex - 1 : currentIndex + 1;
+          if (loop) newIndex = (newIndex + items.length) % items.length;
           if (newIndex < 0 || newIndex >= items.length) {
             commitLockRef.current = false;
             return;
@@ -240,7 +264,7 @@ function useSlideNavigation(items, currentIndex, onNavigate, onSlideStart) {
         }
       });
     },
-    [applySlideOffset, currentIndex, items, onNavigate, onSlideStart]
+    [applySlideOffset, currentIndex, items, onNavigate, onSlideStart, loop]
   );
   const resolveSlide = useCallback(
     (gestureStartTime) => {
@@ -287,7 +311,7 @@ function useSlideNavigation(items, currentIndex, onNavigate, onSlideStart) {
     setSlideActive
   };
 }
-function useGestureHandler(zoomPan, slide, hasPrev, hasNext, zoomEnabled = true) {
+function useGestureHandler(zoomPan, slide, hasPrev, hasNext, zoomEnabled = true, zoomToCursor = true) {
   const { transformRef, clampTranslate: clampTranslate2, setTransform, applyTransform, resetTransform } = zoomPan;
   const { applySlideOffset, resolveSlide, snapBack, setSlideActive, swipeOffsetRef } = slide;
   const panRef = useRef({
@@ -442,7 +466,23 @@ function useGestureHandler(zoomPan, slide, hasPrev, hasNext, zoomEnabled = true)
         const ratio = dist / p.pinchStartDist;
         const nextScale = Math.min(5, Math.max(1, p.pinchStartScale * ratio));
         const t = transformRef.current;
-        const clamped = nextScale <= 1 ? { x: 0, y: 0 } : clampTranslate2(t.x, t.y, nextScale);
+        let clamped;
+        if (nextScale <= 1) {
+          clamped = { x: 0, y: 0 };
+        } else if (zoomToCursor) {
+          const midX = (e.touches[0].clientX + e.touches[1].clientX) / 2;
+          const midY = (e.touches[0].clientY + e.touches[1].clientY) / 2;
+          const focal = zoomToPoint(
+            t.scale,
+            nextScale,
+            { x: t.x, y: t.y },
+            { x: midX, y: midY },
+            { width: window.innerWidth, height: window.innerHeight }
+          );
+          clamped = clampTranslate2(focal.x, focal.y, nextScale);
+        } else {
+          clamped = clampTranslate2(t.x, t.y, nextScale);
+        }
         const next = { scale: nextScale, ...clamped };
         transformRef.current = next;
         applyTransform(next);
@@ -461,7 +501,7 @@ function useGestureHandler(zoomPan, slide, hasPrev, hasNext, zoomEnabled = true)
         updateSlide(touch.clientX, touch.clientY, 6, 0.8);
       }
     },
-    [transformRef, clampTranslate2, applyTransform, updateSlide]
+    [transformRef, clampTranslate2, applyTransform, updateSlide, zoomToCursor]
   );
   const handleTouchEnd = useCallback(
     (e) => {
@@ -534,7 +574,7 @@ function useGestureHandler(zoomPan, slide, hasPrev, hasNext, zoomEnabled = true)
 function useBarMeasure(topBarRef, bottomBarRef, measureKey) {
   const [topBarH, setTopBarH] = useState(0);
   const [bottomBarH, setBottomBarH] = useState(0);
-  useEffect(() => {
+  useLayoutEffect(() => {
     const measure = () => {
       if (topBarRef.current) setTopBarH(topBarRef.current.offsetHeight);
       if (bottomBarRef.current) setBottomBarH(bottomBarRef.current.offsetHeight);
@@ -682,19 +722,37 @@ function NavButton({ direction, enabled, onClick, icon, className }) {
 }
 var ANIM_MS = 250;
 var IMG_PADDING = 44;
+var ZOOM_EASE = "cubic-bezier(0.22, 1, 0.36, 1)";
 function prefersReducedMotion() {
   if (typeof window === "undefined" || !window.matchMedia) return false;
   return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
+function flipTransform(from, to) {
+  const sx = to.width / from.width;
+  const sy = to.height / from.height;
+  const dx = to.left - from.left;
+  const dy = to.top - from.top;
+  return `translate(${dx}px, ${dy}px) scale(${sx}, ${sy})`;
+}
+function canAnimate(el) {
+  return !!el && typeof el.animate === "function";
+}
+function isRectInViewport(rect) {
+  if (typeof window === "undefined") return true;
+  return rect.top < window.innerHeight && rect.top + rect.height > 0 && rect.left < window.innerWidth && rect.left + rect.width > 0;
+}
 function ImageViewer({
   items,
   index,
   onIndexChange,
   onNavigate,
   onClose,
+  getOriginRect,
   zoom = true,
+  zoomToCursor = true,
   showCounter = true,
   loop = false,
+  closeOnBackdropClick = false,
   renderHeader,
   renderHeaderActions,
   renderNavStart,
@@ -707,6 +765,7 @@ function ImageViewer({
 }) {
   const [visible, setVisible] = useState(false);
   const [closing, setClosing] = useState(false);
+  const [collapsing, setCollapsing] = useState(false);
   const [isTouchDevice, setIsTouchDevice] = useState(false);
   const [contentShift, setContentShiftState] = useState({ transform: null, animate: true });
   const containerRef = useRef(null);
@@ -726,7 +785,7 @@ function ImageViewer({
   useBodyScrollLock(true);
   useFocusTrap(containerRef, visible && !closing);
   const { topBarH, bottomBarH } = useBarMeasure(topBarRef, bottomBarRef, index);
-  const zoomPan = useImageZoomPan(imgWrapperRef, index, zoom);
+  const zoomPan = useImageZoomPan(imgWrapperRef, index, zoom, zoomToCursor);
   const {
     imgRef,
     displayScale,
@@ -738,9 +797,9 @@ function ImageViewer({
     measureBaseDims,
     handleDoubleClick
   } = zoomPan;
-  const slide = useSlideNavigation(items, index, onIndexChange, onNavigate);
+  const slide = useSlideNavigation(items, index, onIndexChange, onNavigate, loop);
   const { slideTrackRef, slideActive, slideAnimating, swipeOffset, commitSlide } = slide;
-  const gestures = useGestureHandler(zoomPan, slide, hasPrevLinear, hasNextLinear, zoom);
+  const gestures = useGestureHandler(zoomPan, slide, hasPrev, hasNext, zoom, zoomToCursor);
   useEffect(() => {
     setIsTouchDevice("ontouchstart" in window || navigator.maxTouchPoints > 0);
   }, []);
@@ -753,29 +812,110 @@ function ImageViewer({
     const raf = requestAnimationFrame(() => setVisible(true));
     return () => cancelAnimationFrame(raf);
   }, []);
+  const zoomTransition = !!getOriginRect;
+  const reduceMotion = prefersReducedMotion();
+  const gateEntry = zoomTransition && !reduceMotion;
+  const [fullLoaded, setFullLoaded] = useState(false);
+  const [showSpinner, setShowSpinner] = useState(false);
+  const entryStartedRef = useRef(false);
+  const entryCleanupRef = useRef(null);
+  const runZoomEntry = useCallback(() => {
+    if (entryStartedRef.current) return;
+    if (!getOriginRect || prefersReducedMotion()) return;
+    const img = imgRef.current;
+    const thumb = getOriginRect(index);
+    if (!thumb || !canAnimate(img)) return;
+    const bottomH = bottomBarRef.current?.offsetHeight ?? 0;
+    const lockedMaxHeight = `calc(100vh - ${bottomH + IMG_PADDING * 2}px)`;
+    img.style.maxHeight = lockedMaxHeight;
+    const imgRect = img.getBoundingClientRect();
+    if (imgRect.width === 0 || imgRect.height === 0) {
+      img.style.maxHeight = "";
+      return;
+    }
+    entryStartedRef.current = true;
+    const startTransform = flipTransform(imgRect, thumb);
+    img.style.transformOrigin = "top left";
+    img.style.transform = startTransform;
+    const wrapper = imgWrapperRef.current;
+    if (wrapper) wrapper.style.overflow = "visible";
+    const anim = img.animate(
+      [
+        { transformOrigin: "top left", transform: startTransform },
+        { transformOrigin: "top left", transform: "none" }
+      ],
+      { duration: ANIM_MS, easing: ZOOM_EASE, fill: "forwards" }
+    );
+    const cleanup = () => {
+      img.style.transform = "";
+      img.style.transformOrigin = "";
+      if (wrapper) wrapper.style.overflow = "";
+      img.style.maxHeight = lockedMaxHeight;
+      anim.cancel();
+      entryCleanupRef.current = null;
+    };
+    entryCleanupRef.current = cleanup;
+    anim.onfinish = cleanup;
+  }, [getOriginRect, index, imgRef, imgWrapperRef, bottomBarRef]);
+  const markFullLoaded = useCallback(() => {
+    measureBaseDims();
+    const img = imgRef.current;
+    if (img && typeof img.decode === "function") {
+      img.decode().then(
+        () => setFullLoaded(true),
+        () => setFullLoaded(true)
+      );
+    } else {
+      setFullLoaded(true);
+    }
+  }, [measureBaseDims, imgRef]);
+  useLayoutEffect(() => {
+    const img = imgRef.current;
+    if (img && img.complete && img.naturalWidth > 0) markFullLoaded();
+  }, []);
+  useLayoutEffect(() => {
+    if (fullLoaded) runZoomEntry();
+  }, [fullLoaded]);
+  useEffect(() => {
+    if (!gateEntry || fullLoaded) {
+      setShowSpinner(false);
+      return;
+    }
+    const t = setTimeout(() => setShowSpinner(true), 500);
+    return () => clearTimeout(t);
+  }, [gateEntry, fullLoaded]);
   const handleClose = useCallback(() => {
+    const reduce = prefersReducedMotion();
+    const origin = !reduce && !isZoomed ? getOriginRect?.(index) ?? null : null;
+    const thumb = origin && isRectInViewport(origin) ? origin : null;
+    const img = imgRef.current;
+    entryCleanupRef.current?.();
     setClosing(true);
     setVisible(false);
-    const delay = prefersReducedMotion() ? 0 : ANIM_MS;
-    setTimeout(onClose, delay);
-  }, [onClose]);
+    if (thumb && canAnimate(img)) {
+      const imgRect = img.getBoundingClientRect();
+      const wrapper = imgWrapperRef.current;
+      if (wrapper) wrapper.style.overflow = "visible";
+      setCollapsing(true);
+      img.animate(
+        [
+          { transformOrigin: "top left", transform: "none" },
+          { transformOrigin: "top left", transform: flipTransform(imgRect, thumb) }
+        ],
+        { duration: ANIM_MS, easing: ZOOM_EASE, fill: "forwards" }
+      );
+    }
+    setTimeout(onClose, reduce ? 0 : ANIM_MS);
+  }, [onClose, getOriginRect, index, isZoomed, imgRef, imgWrapperRef]);
   const navigate = useCallback(
     (dir) => {
       if (dir === "prev") {
-        if (hasPrevLinear) commitSlide("prev");
-        else if (loop) {
-          onNavigate?.("prev");
-          onIndexChange(items.length - 1);
-        }
+        if (hasPrev) commitSlide("prev");
       } else {
-        if (hasNextLinear) commitSlide("next");
-        else if (loop) {
-          onNavigate?.("next");
-          onIndexChange(0);
-        }
+        if (hasNext) commitSlide("next");
       }
     },
-    [hasPrevLinear, hasNextLinear, loop, commitSlide, onIndexChange, onNavigate, items.length]
+    [hasPrev, hasNext, commitSlide]
   );
   useEffect(() => {
     const handler = (e) => {
@@ -830,10 +970,13 @@ function ImageViewer({
   const reservedH = bottomBarH + IMG_PADDING * 2;
   const imgMaxHeight = `calc(100vh - ${reservedH}px)`;
   const imgStyle = { maxHeight: imgMaxHeight };
+  if (gateEntry && !fullLoaded) imgStyle.opacity = 0;
   const totalDigits = String(items.length).length;
   const counterMinWidth = `${totalDigits * 2 * 0.6 + 1.5}em`;
-  const prevItem = hasPrevLinear ? items[index - 1] : null;
-  const nextItem = hasNextLinear ? items[index + 1] : null;
+  const prevIndex = hasPrevLinear ? index - 1 : hasPrev ? items.length - 1 : -1;
+  const nextIndex = hasNextLinear ? index + 1 : hasNext ? 0 : -1;
+  const prevItem = prevIndex >= 0 ? items[prevIndex] : null;
+  const nextItem = nextIndex >= 0 ? items[nextIndex] : null;
   const showAdjacent = slideActive || slideAnimating || swipeOffset !== 0;
   const adjacentOpacity = Math.min(1, Math.abs(swipeOffset) / (viewportWidth * 0.8 || 1));
   const showZoomControls = zoom && !isTouchDevice;
@@ -856,7 +999,7 @@ function ImageViewer({
           "div",
           {
             className: cx("rvl-backdrop", cn("backdrop")),
-            onClick: handleClose,
+            onClick: closeOnBackdropClick ? handleClose : void 0,
             "aria-hidden": "true"
           }
         ),
@@ -929,6 +1072,9 @@ function ImageViewer({
           "div",
           {
             className: "rvl-stage",
+            onClick: closeOnBackdropClick ? (e) => {
+              if (e.target === e.currentTarget) handleClose();
+            } : void 0,
             style: {
               transform: contentShift.transform ?? "translateY(0)",
               // animate=false snaps with no transition (overrides the CSS transition)
@@ -938,7 +1084,15 @@ function ImageViewer({
               "div",
               {
                 ref: slideTrackRef,
-                className: cx("rvl-track", visible && !closing && "rvl-track-visible"),
+                className: cx(
+                  "rvl-track",
+                  // During a thumbnail zoom the track is opaque from the first frame
+                  // (the image itself is hidden until the zoom starts), so the picture
+                  // flies in crisply instead of cross-fading. On close it only stays
+                  // opaque while a FLIP collapse is animating the image back; otherwise
+                  // it fades out (so a zoomed close still animates instead of vanishing).
+                  (closing ? collapsing : zoomTransition || visible) && "rvl-track-visible"
+                ),
                 children: [
                   showAdjacent && prevItem && /* @__PURE__ */ jsx(
                     "div",
@@ -980,11 +1134,13 @@ function ImageViewer({
                           className: cx("rvl-img", cn("image")),
                           style: imgStyle,
                           draggable: false,
-                          onLoad: measureBaseDims
+                          onLoad: markFullLoaded,
+                          onError: () => setFullLoaded(true)
                         }
                       )
                     }
                   ),
+                  gateEntry && showSpinner && !fullLoaded && /* @__PURE__ */ jsx("div", { className: cx("rvl-spinner", cn("spinner")), role: "status", "aria-label": "Loading", children: /* @__PURE__ */ jsx("span", { className: "rvl-spinner-ring", "aria-hidden": "true" }) }),
                   showAdjacent && nextItem && /* @__PURE__ */ jsx(
                     "div",
                     {