fix(media): resolve React VDOM crashes, lightbox leaks, Mermaid SVG ID collisions, and i18n caption sync

src/client/imageFigureNumber.js

@@ -1,105 +1,8 @@
 /**
- * Client module to automatically add figure numbers and captions to images
- * based on their alt text in blog posts and docs.
+ * Client module hook for route updates.
+ * Figure numbering and captions are now handled natively via React MDX component
+ * (@theme/MDXComponents/Img) and CSS counters, avoiding raw VDOM DOM mutations.
  */
-export function onRouteDidUpdate({ location, previousLocation }) {
-  // Only run on blog and doc pages
-  if (!location.pathname.match(/\/blog\//) && !location.pathname.match(/\/docs\//)) {
-    return;
-  }
-
-  // Wait for DOM to be ready with multiple attempts
-  setTimeout(() => addFigureNumbers(), 100);
-  setTimeout(() => addFigureNumbers(), 500);
-  setTimeout(() => addFigureNumbers(), 1000);
-}
-
-function addFigureNumbers() {
-  // Find all images in markdown content
-  const articleContent = document.querySelector("article");
-  if (!articleContent) {
-    return;
-  }
-
-  // Find all images that are not in header or footer
-  const images = Array.from(articleContent.querySelectorAll("img")).filter((img) => {
-    // Filter out logos, avatars, icons
-    const parentClass = img.parentElement?.className || "";
-    const isLogo = parentClass.includes("logo") || img.alt.includes("logo");
-    const isIcon = img.width < 100 || img.height < 100;
-    return !isLogo && !isIcon;
-  });
-
-  let figureCount = 0;
-
-  images.forEach((img) => {
-    // Get alt text
-    const altText = img.getAttribute("alt") || "";
-    if (!altText.trim()) {
-      return;
-    }
-
-    // Check if already has figcaption with figure number
-    const existingFigure = img.closest("figure");
-    if (existingFigure) {
-      const existingFigcaption = existingFigure.querySelector("figcaption");
-      if (existingFigcaption && existingFigcaption.textContent.match(/^(图|Figure)\d+:/)) {
-        figureCount++;
-        return;
-      }
-    }
-
-    // Increment counter
-    figureCount++;
-
-    // Create figure wrapper if it doesn't exist
-    let figure = img.closest("figure");
-    if (!figure) {
-      figure = document.createElement("figure");
-      img.parentNode.insertBefore(figure, img);
-      figure.appendChild(img);
-    }
-
-    // Remove existing figcaption if any (but only if it doesn't have figure number)
-    const existingFigcaption = figure.querySelector("figcaption");
-    if (existingFigcaption && !existingFigcaption.textContent.match(/^(图|Figure)\d+:/)) {
-      existingFigcaption.remove();
-    } else if (existingFigcaption) {
-      // Update existing figcaption with figure number
-      const currentLang = document.documentElement.lang || "en";
-      const prefix = currentLang.startsWith("zh") ? "图" : "Figure";
-      existingFigcaption.textContent = `${prefix}${figureCount}: ${altText}`;
-      return;
-    }
-
-    // Create figcaption with number and alt text
-    const figcaption = document.createElement("figcaption");
-    const currentLang = document.documentElement.lang || "en";
-
-    // Use appropriate prefix based on language
-    const prefix = currentLang.startsWith("zh") ? "图" : "Figure";
-    figcaption.textContent = `${prefix}${figureCount}: ${altText}`;
-
-    // Append figcaption to figure
-    figure.appendChild(figcaption);
-
-    // Add styling class
-    figure.style.cssText = `
-      margin: 2em 0;
-      text-align: center;
-    `;
-
-    img.style.cssText = `
-      max-width: 100%;
-      height: auto;
-      border-radius: 8px;
-    `;
-
-    figcaption.style.cssText = `
-      margin-top: 0.8em;
-      font-size: 0.9em;
-      color: var(--ifm-color-emphasis-600);
-      font-style: italic;
-    `;
-  });
+export function onRouteDidUpdate() {
+  // No imperative DOM mutation needed
 }

src/css/custom.css

@@ -356,15 +356,48 @@ pre {
   box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.6);
 }
 
+.theme-doc-markdown article,
+.theme-blog-markdown article,
+article.markdown,
+.markdown {
+  counter-reset: hami-figure-counter;
+}
+
+figure.hami-doc-figure {
+  counter-increment: hami-figure-counter;
+  margin: 2em 0;
+  text-align: center;
+}
+
+figure.hami-doc-figure img,
 .theme-doc-markdown img,
 .theme-blog-markdown img,
 article.markdown img {
+  max-width: 100%;
+  height: auto;
   background: #ffffff;
   border-radius: 10px;
   padding: 4px;
   cursor: zoom-in;
 }
 
+figure.hami-doc-figure figcaption {
+  margin-top: 0.8em;
+  font-size: 0.9em;
+  color: var(--ifm-color-emphasis-600);
+  font-style: italic;
+}
+
+figure.hami-doc-figure figcaption::before {
+  content: "Figure " counter(hami-figure-counter) ": ";
+  font-weight: 600;
+}
+
+html[lang^="zh"] figure.hami-doc-figure figcaption::before {
+  content: "图 " counter(hami-figure-counter) ": ";
+  font-weight: 600;
+}
+
 body.hami-lightbox-open {
   overflow: hidden;
 }

src/theme/MDXComponents/Img/index.js

@@ -0,0 +1,22 @@
+import React from "react";
+
+export default function MDXImg(props) {
+  const { alt = "", className = "" } = props;
+  const trimmedAlt = alt.trim();
+
+  const isLogo =
+    className.includes("logo") ||
+    className.includes("avatar") ||
+    trimmedAlt.toLowerCase().includes("logo");
+
+  if (!trimmedAlt || isLogo) {
+    return <img {...props} />;
+  }
+
+  return (
+    <figure className="hami-doc-figure">
+      <img {...props} />
+      <figcaption>{trimmedAlt}</figcaption>
+    </figure>
+  );
+}

src/theme/MDXComponents/index.js

@@ -0,0 +1,7 @@
+import MDXComponents from "@theme-original/MDXComponents";
+import MDXImg from "@site/src/theme/MDXComponents/Img";
+
+export default {
+  ...MDXComponents,
+  img: MDXImg,
+};

src/theme/utils/useImageLightbox.js

@@ -29,6 +29,40 @@ function shouldOpenLightbox(image) {
   return Boolean(image.currentSrc || image.src);
 }
 
+function sanitizeSvgIds(clone) {
+  const uniqueSuffix = `-lb-${Math.random().toString(36).substring(2, 8)}`;
+  const idElements = clone.querySelectorAll("[id]");
+  const idMap = new Map();
+
+  idElements.forEach((el) => {
+    const oldId = el.getAttribute("id");
+    if (oldId) {
+      const newId = `${oldId}${uniqueSuffix}`;
+      idMap.set(oldId, newId);
+      el.setAttribute("id", newId);
+    }
+  });
+
+  if (idMap.size > 0) {
+    const allElements = clone.querySelectorAll("*");
+    allElements.forEach((el) => {
+      Array.from(el.attributes).forEach((attr) => {
+        let val = attr.value;
+        let changed = false;
+        idMap.forEach((newId, oldId) => {
+          if (val.includes(`#${oldId}`)) {
+            val = val.replace(new RegExp(`#${oldId}\\b`, "g"), `#${newId}`);
+            changed = true;
+          }
+        });
+        if (changed) {
+          el.setAttribute(attr.name, val);
+        }
+      });
+    });
+  }
+}
+
 function ensureLightbox() {
   let root = document.querySelector(".hami-lightbox");
   if (root) {
@@ -92,14 +126,21 @@ function ensureLightbox() {
 
   lightboxImage.addEventListener("click", close);
   svgHost.addEventListener("click", close);
-
   closeButton.addEventListener("click", close);
 
-  document.addEventListener("keydown", (event) => {
+  const handleKeyDown = (event) => {
     if (event.key === "Escape" && !root.hidden) {
       close();
     }
-  });
+  };
+
+  document.addEventListener("keydown", handleKeyDown);
+  root.__hamiLightboxCleanup = () => {
+    document.removeEventListener("keydown", handleKeyDown);
+    if (root.parentNode) {
+      root.parentNode.removeChild(root);
+    }
+  };
 
   root.__hamiLightboxOpen = ({ src, alt, caption: captionText }) => {
     lightboxImage.src = src;
@@ -114,9 +155,8 @@ function ensureLightbox() {
 
   root.__hamiLightboxOpenSvg = (svg, captionText) => {
     const clone = svg.cloneNode(true);
-    // Mermaid caps the inline SVG at its rendered size; lift the cap and let
-    // it scale to fit the lightbox box in both dimensions (the viewBox keeps
-    // the aspect ratio), so the whole diagram is visible without scrolling.
+    sanitizeSvgIds(clone);
+
     clone.style.maxWidth = "none";
     clone.style.width = "100%";
     clone.style.height = "100%";
@@ -152,7 +192,6 @@ function handleImageClick(event) {
     return;
   }
 
-  // Mermaid diagrams: clicking anywhere in the rendered container zooms it.
   const mermaidContainer = target.closest(MERMAID_CONTAINER);
   if (
     mermaidContainer &&
@@ -205,6 +244,10 @@ export default function useImageLightbox() {
 
     return () => {
       document.removeEventListener("click", handleImageClick);
+      const root = document.querySelector(".hami-lightbox");
+      if (root && typeof root.__hamiLightboxCleanup === "function") {
+        root.__hamiLightboxCleanup();
+      }
       window.__hamiLightboxInitialized = false;
     };
   }, []);