From aa0f543ec5a033b9e5525122bc950afa84ab7996 Mon Sep 17 00:00:00 2001
From: Julian Pawlowski <jpawlowski@users.noreply.github.com>
Date: Tue, 7 Apr 2026 15:32:52 +0000
Subject: [PATCH] fix: ensure SVG backgrounds are solid to prevent transparency
 issues

---
 docs/user/src/css/custom.css          | 25 +++++++++++++++++++++----
 docs/user/src/theme/Mermaid/index.tsx | 12 +++++++++---
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/docs/user/src/css/custom.css b/docs/user/src/css/custom.css
index 18f72d9..0eaadc5 100644
--- a/docs/user/src/css/custom.css
+++ b/docs/user/src/css/custom.css
@@ -237,6 +237,15 @@ h1, h2, h3, h4, h5, h6 {
   border-radius: var(--ifm-card-border-radius, 0.5rem);
   /* Clip the hover overlay to the same rounded corners */
   overflow: hidden;
+  /* Solid background so the SVG is never transparent against the page */
+  background: var(--ifm-background-color);
+}
+
+/* Ensure the SVG itself also has a solid background (covers Mermaid inline styles) */
+.mermaid-zoom-wrapper svg {
+  display: block;
+  background: var(--ifm-background-color);
+  border-radius: inherit;
 }
 
 /* Semi-transparent tint that fades in on hover */
@@ -348,13 +357,21 @@ h1, h2, h3, h4, h5, h6 {
   display: block;
   width: 100%;
   height: auto;
-  /* Solid themed background — auto-switches with light/dark mode */
-  background: var(--ifm-background-color);
+  /* !important: overrides any inline background Mermaid bakes into the SVG */
+  background: var(--ifm-background-color) !important;
   border-radius: calc(var(--ifm-card-border-radius, 0.5rem) - 2px);
 }
 
-/* Override Mermaid's hardcoded background rect (sequence diagrams, etc.) */
-.mermaid-lightbox-inner svg .background {
+/*
+ * Override Mermaid's hardcoded background rects.
+ * Mermaid uses several class names depending on diagram type and version:
+ *   .background  — sequence diagrams
+ *   .bb          — class/state diagrams
+ * The first <rect> child is used as a background fill by all diagram types.
+ */
+.mermaid-lightbox-inner svg .background,
+.mermaid-lightbox-inner svg .bb,
+.mermaid-lightbox-inner svg > rect:first-child {
   fill: var(--ifm-background-color) !important;
 }
 
diff --git a/docs/user/src/theme/Mermaid/index.tsx b/docs/user/src/theme/Mermaid/index.tsx
index 4ea1037..9f874d6 100644
--- a/docs/user/src/theme/Mermaid/index.tsx
+++ b/docs/user/src/theme/Mermaid/index.tsx
@@ -25,7 +25,13 @@ export default function MermaidWrapper(props: Props): React.JSX.Element {
     const clone = svg.cloneNode(true) as SVGElement;
     clone.removeAttribute('width');
     clone.removeAttribute('height');
-    clone.style.cssText = 'width:100%;height:auto;display:block;';
+    // Bake in the current page background so the SVG is never transparent,
+    // even if Mermaid's internal <style> or <rect> elements override CSS.
+    const bg =
+      getComputedStyle(document.documentElement)
+        .getPropertyValue('--ifm-background-color')
+        .trim() || '#ffffff';
+    clone.style.cssText = `width:100%;height:auto;display:block;background:${bg};`;
     setSvgMarkup(clone.outerHTML);
     setOverlayOpen(true);
   }, []);
@@ -125,7 +131,7 @@ export default function MermaidWrapper(props: Props): React.JSX.Element {
             role="dialog"
             aria-modal="true"
             aria-label="Enlarged diagram"
-            onClick={handleClose}
+            onClick={(e) => { e.stopPropagation(); handleClose(); }}
           >
             <div
               className="mermaid-lightbox-inner"
@@ -135,7 +141,7 @@ export default function MermaidWrapper(props: Props): React.JSX.Element {
             />
             <button
               className="mermaid-lightbox-close"
-              onClick={handleClose}
+              onClick={(e) => { e.stopPropagation(); handleClose(); }}
               aria-label="Close enlarged view"
               title="Close (Esc)"
             >