updated files with new features and improvements: caching proper

app/ui-tarot-lightbox.js

@@ -54,6 +54,8 @@
   let activePinchGesture = null;
   let suppressNextCardClick = false;
   let suppressDeckCompareToggleUntil = 0;
+  let primaryImageRequestToken = 0;
+  let overlayImageRequestToken = 0;
 
   const LIGHTBOX_ZOOM_SCALE = 6.66;
   const LIGHTBOX_ZOOM_STEP = 0.1;
@@ -837,6 +839,7 @@
     const label = String(normalized.label || normalized.altText || "Tarot card enlarged image").trim() || "Tarot card enlarged image";
     return {
       src: String(normalized.src || "").trim(),
+      previewSrc: String(normalized.previewSrc || "").trim(),
       altText: String(normalized.altText || label).trim() || label,
       label,
       cardId: String(normalized.cardId || "").trim(),
@@ -847,6 +850,66 @@
     };
   }
 
+  function getImageRequestToken(layer = "primary") {
+    if (layer === "overlay") {
+      overlayImageRequestToken += 1;
+      return overlayImageRequestToken;
+    }
+
+    primaryImageRequestToken += 1;
+    return primaryImageRequestToken;
+  }
+
+  function getCurrentImageRequestToken(layer = "primary") {
+    return layer === "overlay" ? overlayImageRequestToken : primaryImageRequestToken;
+  }
+
+  function applyCardImageToElement(targetImageEl, cardRequest, layer = "primary") {
+    if (!(targetImageEl instanceof HTMLImageElement)) {
+      return;
+    }
+
+    const normalizedCard = normalizeCardRequest(cardRequest);
+    const fullSrc = String(normalizedCard.src || "").trim();
+    const previewSrc = String(normalizedCard.previewSrc || "").trim();
+    const normalizedPreviewSrc = previewSrc && previewSrc !== fullSrc ? previewSrc : "";
+    const imageCache = window.TarotCardImages || {};
+    const fullImageLoaded = typeof imageCache.isImageLoaded === "function"
+      ? imageCache.isImageLoaded(fullSrc)
+      : false;
+    const requestToken = getImageRequestToken(layer);
+    const initialSrc = fullSrc && (!normalizedPreviewSrc || fullImageLoaded)
+      ? fullSrc
+      : (normalizedPreviewSrc || fullSrc);
+
+    if (initialSrc) {
+      targetImageEl.src = initialSrc;
+      targetImageEl.alt = normalizedCard.altText;
+    } else {
+      targetImageEl.removeAttribute("src");
+      targetImageEl.alt = normalizedCard.altText;
+      return;
+    }
+
+    if (!fullSrc || initialSrc === fullSrc || typeof imageCache.ensureImageLoaded !== "function") {
+      return;
+    }
+
+    imageCache.ensureImageLoaded(fullSrc)
+      .then((loadedImage) => {
+        if (!loadedImage || getCurrentImageRequestToken(layer) !== requestToken || !lightboxState.isOpen) {
+          return;
+        }
+
+        if (targetImageEl.src !== fullSrc) {
+          targetImageEl.src = fullSrc;
+          targetImageEl.alt = normalizedCard.altText;
+        }
+      })
+      .catch(() => {
+      });
+  }
+
   function normalizeDeckOptions(deckOptions) {
     if (!Array.isArray(deckOptions)) {
       return [];
@@ -3198,8 +3261,7 @@
       if (isCompactLightboxLayout()) {
         lightboxState.mobileInfoView = "overlay";
       }
-      overlayImageEl.src = normalizedCard.src;
-      overlayImageEl.alt = normalizedCard.altText;
+      applyCardImageToElement(overlayImageEl, normalizedCard, "overlay");
       overlayImageEl.style.display = "block";
       overlayImageEl.style.opacity = String(lightboxState.overlayOpacity);
       if (syncSelection && typeof lightboxState.onSelectCardId === "function") {
@@ -3254,8 +3316,7 @@
       }
 
       lightboxState.primaryCard = nextCard;
-      imageEl.src = nextCard.src;
-      imageEl.alt = nextCard.altText;
+  applyCardImageToElement(imageEl, nextCard, "primary");
       resetZoom();
       if (lightboxState.deckCompareMode) {
         syncDeckCompareCards();
@@ -3279,10 +3340,8 @@
       lightboxState.primaryCard = nextPrimaryCard;
       lightboxState.secondaryCard = nextSecondaryCard;
 
-      imageEl.src = nextPrimaryCard.src;
-      imageEl.alt = nextPrimaryCard.altText;
-      overlayImageEl.src = nextSecondaryCard.src;
-      overlayImageEl.alt = nextSecondaryCard.altText;
+      applyCardImageToElement(imageEl, nextPrimaryCard, "primary");
+      applyCardImageToElement(overlayImageEl, nextSecondaryCard, "overlay");
       overlayImageEl.style.display = "block";
       overlayImageEl.style.opacity = String(lightboxState.overlayOpacity);
 
@@ -3723,8 +3782,7 @@
     setInfoPanelOpen(getPersistedInfoPanelVisibility(), { persist: false });
     lightboxState.mobileInfoView = "primary";
 
-    imageEl.src = normalizedPrimary.src;
-    imageEl.alt = normalizedPrimary.altText;
+    applyCardImageToElement(imageEl, normalizedPrimary, "primary");
     clearSecondaryCard();
     resetZoom();
     previousFocusedEl = document.activeElement instanceof HTMLElement ? document.activeElement : null;