From aea720f5fb159498d744b65400b5134eeb3634fc Mon Sep 17 00:00:00 2001
From: Sebastian Dauenhauer <info@magical.rocks>
Date: Thu, 1 Oct 2026 22:49:07 +0200
Subject: [PATCH 1/2] Add accessible image lightbox to documentation

---
 astro.config.mjs                   |  1 +
 src/components/Footer.astro        |  7 +++
 src/components/ImageLightbox.astro | 80 ++++++++++++++++++++++++++++++
 src/styles/custom.css              | 41 +++++++++++++++
 4 files changed, 129 insertions(+)
 create mode 100644 src/components/Footer.astro
 create mode 100644 src/components/ImageLightbox.astro

diff --git a/astro.config.mjs b/astro.config.mjs
index 944a2b0..1c915c3 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -42,6 +42,7 @@ export default defineConfig({
       },
     }),
     starlight({
+      components: { Footer: './src/components/Footer.astro' },
       title: "Fancy Mumble",
       description:
         "Documentation for the Fancy Mumble app and Starling server. Voice chat reimagined for 2026.",
diff --git a/src/components/Footer.astro b/src/components/Footer.astro
new file mode 100644
index 0000000..83ee952
--- /dev/null
+++ b/src/components/Footer.astro
@@ -0,0 +1,7 @@
+---
+import Footer from '@astrojs/starlight/components/Footer.astro';
+import ImageLightbox from './ImageLightbox.astro';
+---
+
+<Footer />
+<ImageLightbox />
diff --git a/src/components/ImageLightbox.astro b/src/components/ImageLightbox.astro
new file mode 100644
index 0000000..c544a2e
--- /dev/null
+++ b/src/components/ImageLightbox.astro
@@ -0,0 +1,80 @@
+<dialog id="doc-image-lightbox" aria-label="Image preview">
+  <div class="image-lightbox-toolbar">
+    <button type="button" data-image-zoom aria-pressed="false">Actual size</button>
+    <button type="button" data-image-close aria-label="Close image preview">Close ×</button>
+  </div>
+  <div class="image-lightbox-view"><img alt="" /></div>
+  <p class="image-lightbox-caption"></p>
+</dialog>
+
+<script>
+  function setupLightbox() {
+    const dialog = document.querySelector<HTMLDialogElement>('#doc-image-lightbox');
+    if (!dialog || dialog.dataset.ready) return;
+    dialog.dataset.ready = 'true';
+    const preview = dialog.querySelector<HTMLImageElement>('img')!;
+    const caption = dialog.querySelector<HTMLElement>('.image-lightbox-caption')!;
+    const zoom = dialog.querySelector<HTMLButtonElement>('[data-image-zoom]')!;
+    let opener: HTMLButtonElement | null = null;
+    let source: HTMLImageElement | null = null;
+
+    function updateImage() {
+      if (!source) return;
+      const pair = source.closest('.theme-screenshot');
+      const visible = pair
+        ? Array.from(pair.querySelectorAll('img')).find(image => getComputedStyle(image).display !== 'none')
+        : source;
+      if (!visible) return;
+      preview.src = visible.currentSrc || visible.src;
+      preview.alt = visible.alt;
+      caption.textContent = visible.alt;
+    }
+
+    document.querySelectorAll<HTMLImageElement>('.sl-markdown-content img, .hero img').forEach(image => {
+      if (image.closest('a, button') || image.dataset.noLightbox !== undefined) return;
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'doc-image-trigger';
+      button.setAttribute('aria-label', `Enlarge image${image.alt ? ': ' + image.alt : ''}`);
+      button.setAttribute('aria-haspopup', 'dialog');
+      // Keep the trigger hidden whenever its theme variant is hidden.
+      if (image.classList.contains('screenshot-light')) button.classList.add('screenshot-light');
+      if (image.classList.contains('screenshot-dark')) button.classList.add('screenshot-dark');
+      image.before(button);
+      button.append(image);
+      button.addEventListener('click', () => {
+        opener = button;
+        source = image;
+        dialog.classList.remove('actual-size');
+        zoom.setAttribute('aria-pressed', 'false');
+        zoom.textContent = 'Actual size';
+        updateImage();
+        dialog.showModal();
+      });
+    });
+
+    dialog.querySelector('[data-image-close]')!.addEventListener('click', () => dialog.close());
+    dialog.addEventListener('click', event => {
+      if (event.target === dialog) dialog.close();
+    });
+    dialog.addEventListener('close', () => {
+      const pair = source?.closest('.theme-screenshot');
+      if (pair && opener && !opener.getClientRects().length) {
+        opener = Array.from(pair.querySelectorAll<HTMLButtonElement>('.doc-image-trigger'))
+          .find(button => button.getClientRects().length > 0) ?? opener;
+      }
+      preview.removeAttribute('src');
+      source = null;
+      opener?.focus();
+    });
+    zoom.addEventListener('click', () => {
+      const actual = dialog.classList.toggle('actual-size');
+      zoom.setAttribute('aria-pressed', String(actual));
+      zoom.textContent = actual ? 'Fit to window' : 'Actual size';
+    });
+    new MutationObserver(() => { if (dialog.open) updateImage(); })
+      .observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
+  }
+  setupLightbox();
+  document.addEventListener('astro:page-load', setupLightbox);
+</script>
diff --git a/src/styles/custom.css b/src/styles/custom.css
index e85be52..c1357fa 100644
--- a/src/styles/custom.css
+++ b/src/styles/custom.css
@@ -323,3 +323,44 @@ div.header {
 .theme-screenshot .screenshot-dark { display: none; }
 :root[data-theme="dark"] .theme-screenshot .screenshot-light { display: none; }
 :root[data-theme="dark"] .theme-screenshot .screenshot-dark { display: block; }
+
+.doc-image-trigger {
+  display: block;
+  max-width: 100%;
+  padding: 0;
+  border: 0;
+  background: none;
+  cursor: zoom-in;
+}
+.doc-image-trigger img { display: block; margin: 0; }
+.doc-image-trigger:focus-visible { outline: 3px solid var(--sl-color-accent-high); outline-offset: 4px; }
+#doc-image-lightbox {
+  width: 96vw;
+  max-width: 1800px;
+  height: 94dvh;
+  max-height: 94dvh;
+  padding: 1rem;
+  border: 1px solid var(--sl-color-gray-4);
+  border-radius: .75rem;
+  background: var(--sl-color-bg);
+  color: var(--sl-color-white);
+  overflow: hidden;
+}
+#doc-image-lightbox[open] { display: flex; flex-direction: column; gap: .75rem; }
+#doc-image-lightbox::backdrop { background: rgb(0 0 0 / 80%); }
+.image-lightbox-toolbar { display: flex; justify-content: flex-end; gap: .75rem; flex-shrink: 0; }
+.image-lightbox-toolbar button {
+  padding: .5rem .75rem;
+  border: 1px solid var(--sl-color-gray-4);
+  border-radius: .4rem;
+  color: inherit;
+  background: var(--sl-color-gray-6);
+  cursor: pointer;
+  font: inherit;
+}
+.image-lightbox-view { flex: 1; min-height: 0; overflow: auto; display: grid; grid-template: minmax(0, 1fr) / minmax(0, 1fr); place-items: center; }
+.image-lightbox-view img { min-width: 0; min-height: 0; max-width: 100%; max-height: 100%; width: 100%; height: 100%; object-fit: contain; }
+#doc-image-lightbox.actual-size .image-lightbox-view { display: block; }
+#doc-image-lightbox.actual-size img { max-width: none; max-height: none; width: auto; height: auto; }
+.image-lightbox-caption { margin: 0; flex-shrink: 0; font-size: .85rem; color: var(--sl-color-gray-2); }
+html:has(#doc-image-lightbox[open]) { overflow: hidden; }

From ad27d0687a227a5cb4a7708cfea8edf914195238 Mon Sep 17 00:00:00 2001
From: Sebastian Dauenhauer <info@magical.rocks>
Date: Thu, 1 Oct 2026 22:51:50 +0200
Subject: [PATCH 2/2] Preserve positioned profile image layouts in the lightbox

---
 src/components/ImageLightbox.astro | 30 ++++++++++++++++++------------
 src/styles/custom.css              |  3 ++-
 2 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/src/components/ImageLightbox.astro b/src/components/ImageLightbox.astro
index c544a2e..f10212e 100644
--- a/src/components/ImageLightbox.astro
+++ b/src/components/ImageLightbox.astro
@@ -15,7 +15,7 @@
     const preview = dialog.querySelector<HTMLImageElement>('img')!;
     const caption = dialog.querySelector<HTMLElement>('.image-lightbox-caption')!;
     const zoom = dialog.querySelector<HTMLButtonElement>('[data-image-zoom]')!;
-    let opener: HTMLButtonElement | null = null;
+    let opener: HTMLElement | null = null;
     let source: HTMLImageElement | null = null;
 
     function updateImage() {
@@ -32,24 +32,30 @@
 
     document.querySelectorAll<HTMLImageElement>('.sl-markdown-content img, .hero img').forEach(image => {
       if (image.closest('a, button') || image.dataset.noLightbox !== undefined) return;
-      const button = document.createElement('button');
-      button.type = 'button';
-      button.className = 'doc-image-trigger';
-      button.setAttribute('aria-label', `Enlarge image${image.alt ? ': ' + image.alt : ''}`);
-      button.setAttribute('aria-haspopup', 'dialog');
+      // Profile cards position their images independently; preserve that layout.
+      const positioned = image.closest('[data-profile-example]') !== null;
+      const trigger = positioned ? image : document.createElement('button');
+      if (trigger instanceof HTMLButtonElement) trigger.type = 'button';
+      else { trigger.setAttribute('role', 'button'); trigger.tabIndex = 0; }
+      trigger.classList.add(positioned ? 'doc-image-target' : 'doc-image-trigger');
+      trigger.setAttribute('aria-label', `Enlarge image${image.alt ? ': ' + image.alt : ''}`);
+      trigger.setAttribute('aria-haspopup', 'dialog');
       // Keep the trigger hidden whenever its theme variant is hidden.
-      if (image.classList.contains('screenshot-light')) button.classList.add('screenshot-light');
-      if (image.classList.contains('screenshot-dark')) button.classList.add('screenshot-dark');
-      image.before(button);
-      button.append(image);
-      button.addEventListener('click', () => {
-        opener = button;
+      if (image.classList.contains('screenshot-light')) trigger.classList.add('screenshot-light');
+      if (image.classList.contains('screenshot-dark')) trigger.classList.add('screenshot-dark');
+      if (!positioned) { image.before(trigger); trigger.append(image); }
+      const open = () => {
+        opener = trigger;
         source = image;
         dialog.classList.remove('actual-size');
         zoom.setAttribute('aria-pressed', 'false');
         zoom.textContent = 'Actual size';
         updateImage();
         dialog.showModal();
+      };
+      trigger.addEventListener('click', open);
+      if (positioned) trigger.addEventListener('keydown', event => {
+        if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); open(); }
       });
     });
 
diff --git a/src/styles/custom.css b/src/styles/custom.css
index c1357fa..d7437b2 100644
--- a/src/styles/custom.css
+++ b/src/styles/custom.css
@@ -333,7 +333,8 @@ div.header {
   cursor: zoom-in;
 }
 .doc-image-trigger img { display: block; margin: 0; }
-.doc-image-trigger:focus-visible { outline: 3px solid var(--sl-color-accent-high); outline-offset: 4px; }
+.doc-image-target { cursor: zoom-in; }
+.doc-image-trigger:focus-visible, .doc-image-target:focus-visible { outline: 3px solid var(--sl-color-accent-high); outline-offset: 4px; }
 #doc-image-lightbox {
   width: 96vw;
   max-width: 1800px;