From 30e01f5f1d9f94373ee1ef6a99a1d47c76d95f32 Mon Sep 17 00:00:00 2001
From: John Riccardi <riccjohn@gmail.com>
Date: Thu, 9 Apr 2026 16:05:30 -0500
Subject: [PATCH 1/2] Add image lightbox component for blog posts

Clicking any article image opens it enlarged in a centered modal overlay.
Closes on backdrop click, Escape, close button, or clicking the enlarged image.
Includes loading skeleton for large images (e.g. GIFs), respects
prefers-reduced-motion, and excludes the hero image via data-no-lightbox.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/components/Lightbox.astro | 225 ++++++++++++++++++++++++++++++++++
 src/layouts/BlogPost.astro    |   3 +
 2 files changed, 228 insertions(+)
 create mode 100644 src/components/Lightbox.astro

diff --git a/src/components/Lightbox.astro b/src/components/Lightbox.astro
new file mode 100644
index 0000000..df50c59
--- /dev/null
+++ b/src/components/Lightbox.astro
@@ -0,0 +1,225 @@
+---
+
+---
+
+<dialog id="lightbox" aria-label="Image lightbox">
+    <div class="lightbox-inner">
+        <button
+            id="lightbox-close"
+            autofocus
+            aria-label="Close lightbox"
+            class="bg-bg-tertiary border-border-default text-text-secondary hover:border-accent-primary hover:text-accent-primary flex cursor-pointer items-center justify-center rounded border p-2 transition-all duration-200"
+        >
+            <svg
+                width="16"
+                height="16"
+                viewBox="0 0 16 16"
+                fill="none"
+                xmlns="http://www.w3.org/2000/svg"
+            >
+                <line
+                    x1="2"
+                    y1="2"
+                    x2="14"
+                    y2="14"
+                    stroke="currentColor"
+                    stroke-width="2"
+                    stroke-linecap="round"></line>
+                <line
+                    x1="14"
+                    y1="2"
+                    x2="2"
+                    y2="14"
+                    stroke="currentColor"
+                    stroke-width="2"
+                    stroke-linecap="round"></line>
+            </svg>
+        </button>
+        <div id="lightbox-skeleton" hidden></div>
+        <img id="lightbox-img" src="" alt="" />
+        <p id="lightbox-caption"></p>
+    </div>
+</dialog>
+
+<!-- is:global required: article img lives in slotted MDX content outside this component's scope -->
+<style is:global>
+    article img:not([data-no-lightbox]) {
+        cursor: zoom-in;
+    }
+
+    #lightbox {
+        padding: 0;
+        border: none;
+        background: transparent;
+        max-width: 100vw;
+        max-height: 100vh;
+        position: fixed;
+        top: 50%;
+        left: 50%;
+        transform: translate(-50%, -50%);
+        margin: 0;
+    }
+
+    #lightbox::backdrop {
+        background: rgba(0, 0, 0, 0.85);
+        backdrop-filter: blur(4px);
+    }
+
+    .lightbox-inner {
+        position: relative;
+        background: var(--color-bg-primary);
+        border: 1px solid var(--color-border-default);
+        box-shadow: 0 8px 32px var(--color-shadow-default);
+        padding: 1rem;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        gap: 0.75rem;
+        max-width: 90vw;
+        max-height: 90vh;
+    }
+
+    #lightbox-close {
+        position: absolute;
+        top: 0.5rem;
+        right: 0.5rem;
+    }
+
+    #lightbox-img {
+        display: block;
+        max-width: 85vw;
+        max-height: 75vh;
+        cursor: zoom-out;
+    }
+
+    #lightbox-skeleton {
+        background: var(--color-border-default);
+        max-width: 85vw;
+        max-height: 75vh;
+        animation: lightbox-pulse 1.5s ease-in-out infinite;
+    }
+
+    @keyframes lightbox-pulse {
+        0%,
+        100% {
+            opacity: 0.6;
+        }
+        50% {
+            opacity: 0.15;
+        }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        #lightbox-skeleton {
+            animation: none;
+            opacity: 0.4;
+        }
+    }
+
+    #lightbox-caption {
+        color: var(--color-text-secondary);
+        font-family: monospace;
+        font-size: 0.875rem;
+        text-align: center;
+        margin: 0;
+    }
+
+    #lightbox-caption::before {
+        content: '// ';
+    }
+</style>
+
+<script>
+    const dialog = document.querySelector<HTMLDialogElement>('#lightbox')
+    const lightboxImg =
+        document.querySelector<HTMLImageElement>('#lightbox-img')
+    const lightboxCaption =
+        document.querySelector<HTMLParagraphElement>('#lightbox-caption')
+    const lightboxSkeleton =
+        document.querySelector<HTMLElement>('#lightbox-skeleton')
+
+    if (!dialog || !lightboxImg || !lightboxCaption || !lightboxSkeleton) {
+        throw new Error('Lightbox: required elements not found in DOM')
+    }
+
+    document.addEventListener('click', (e) => {
+        const img = (e.target as Element).closest(
+            'article img:not([data-no-lightbox])'
+        )
+        if (!img || !(img instanceof HTMLImageElement)) return
+        lightboxImg.src = img.src
+        lightboxImg.alt = img.alt
+        const figcaption = img.closest('figure')?.querySelector('figcaption')
+        // Strip the CSS-injected "// " prefix (see #lightbox-caption::before)
+        const captionText =
+            figcaption?.textContent?.replace(/^\/\/\s*/, '') ?? ''
+        lightboxCaption.textContent = captionText
+        lightboxCaption.hidden = !captionText
+        // Scale image to fill available lightbox space
+        const maxW = window.innerWidth * 0.85
+        const maxH = window.innerHeight * 0.75
+        if (img.naturalWidth && img.naturalHeight) {
+            const scale = Math.min(
+                maxW / img.naturalWidth,
+                maxH / img.naturalHeight
+            )
+            lightboxImg.style.width =
+                Math.round(img.naturalWidth * scale) + 'px'
+            lightboxImg.style.height = 'auto'
+        } else {
+            lightboxImg.style.width = Math.round(maxW) + 'px'
+            lightboxImg.style.height = 'auto'
+        }
+        // Show skeleton until image loads
+        const showImage = () => {
+            lightboxSkeleton.hidden = true
+            lightboxImg.hidden = false
+        }
+        if (lightboxImg.complete && lightboxImg.naturalWidth) {
+            showImage()
+        } else {
+            lightboxImg.hidden = true
+            lightboxSkeleton.style.width = lightboxImg.style.width
+            // Fall back to 16:9 if natural dimensions unavailable (e.g. uncached image)
+            const aspectRatio =
+                img.naturalWidth && img.naturalHeight
+                    ? img.naturalHeight / img.naturalWidth
+                    : 9 / 16
+            lightboxSkeleton.style.height =
+                Math.round(
+                    Number.parseInt(lightboxImg.style.width, 10) * aspectRatio
+                ) + 'px'
+            lightboxSkeleton.hidden = false
+            lightboxImg.addEventListener('load', showImage, { once: true })
+            lightboxImg.addEventListener(
+                'error',
+                () => {
+                    lightboxSkeleton.hidden = true
+                    lightboxImg.hidden = false
+                },
+                { once: true }
+            )
+        }
+        dialog.showModal()
+    })
+
+    dialog.addEventListener('click', (e) => {
+        if (e.target === dialog) dialog.close()
+    })
+
+    lightboxImg.addEventListener('click', () => dialog.close())
+
+    document
+        .querySelector('#lightbox-close')
+        ?.addEventListener('click', () => dialog.close())
+
+    dialog.addEventListener('close', () => {
+        lightboxImg.src = ''
+        lightboxImg.style.width = ''
+        lightboxImg.style.height = ''
+        lightboxImg.hidden = false
+        lightboxSkeleton.hidden = true
+        lightboxSkeleton.style.width = ''
+        lightboxSkeleton.style.height = ''
+    })
+</script>
diff --git a/src/layouts/BlogPost.astro b/src/layouts/BlogPost.astro
index 33351c0..78deabb 100644
--- a/src/layouts/BlogPost.astro
+++ b/src/layouts/BlogPost.astro
@@ -8,6 +8,7 @@ import FormattedDate from '@/components/FormattedDate.astro'
 import { THEME_INIT_SCRIPT } from '@/utils/theme'
 import { formatReadingTime } from '@/utils/readingTime'
 import ShareButtons from '@/components/ShareButtons.astro'
+import Lightbox from '@/components/Lightbox.astro'
 
 type Props = CollectionEntry<'blog'>['data'] & {
     readingTime?: number
@@ -41,6 +42,7 @@ const { title, description, pubDate, updatedDate, heroImage, readingTime } =
                                     class="h-full w-full object-cover"
                                     width={1020}
                                     height={574}
+                                    data-no-lightbox
                                 />
                             </div>
                         )
@@ -78,5 +80,6 @@ const { title, description, pubDate, updatedDate, heroImage, readingTime } =
             </article>
         </main>
         <Footer />
+        <Lightbox />
     </body>
 </html>

From 166dcd39385b6f670ab4c83e3d48a41d1af417a2 Mon Sep 17 00:00:00 2001
From: John Riccardi <riccjohn@gmail.com>
Date: Thu, 9 Apr 2026 16:10:30 -0500
Subject: [PATCH 2/2] Add lightbox research and plan artifacts

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .crafter/scratch/image-lightbox-plan.md     | 171 ++++++++++++++++++++
 .crafter/scratch/image-lightbox-research.md | 157 ++++++++++++++++++
 2 files changed, 328 insertions(+)
 create mode 100644 .crafter/scratch/image-lightbox-plan.md
 create mode 100644 .crafter/scratch/image-lightbox-research.md

diff --git a/.crafter/scratch/image-lightbox-plan.md b/.crafter/scratch/image-lightbox-plan.md
new file mode 100644
index 0000000..5a60db9
--- /dev/null
+++ b/.crafter/scratch/image-lightbox-plan.md
@@ -0,0 +1,171 @@
+# Image Lightbox — Implementation Plan
+
+## Feature
+
+Add click-to-enlarge lightbox to all images in blog posts. Clicking any image opens it in a centered modal overlay. Clicking outside, pressing Escape, or clicking the close button dismisses it.
+
+## Scope
+
+- All `<img>` tags inside `<article>` in blog posts (covers `<CaptionedImage>`, plain markdown images, direct `<Image>` components)
+- Hero image excluded (already full-width, opt-out via `data-no-lightbox`)
+- No external libraries — native `<dialog>` + vanilla JS
+
+## Files to Change
+
+### 1. `src/layouts/BlogPost.astro`
+
+- Add shared `<dialog id="lightbox">` element to the end of `<body>` (before `</body>`)
+- Add `<script>` tag with lightbox logic
+- Add `cursor: zoom-in` CSS for `article img:not([data-no-lightbox])`
+- Add `data-no-lightbox` attribute to the existing hero `<img>` element
+
+### 2. No other files need to change
+
+`CaptionedImage.astro` does not need modification — caption is read from the nearest `<figcaption>` at runtime.
+
+## Dialog HTML Structure
+
+```html
+<dialog id="lightbox" aria-label="Image lightbox">
+    <div class="lightbox-inner">
+        <button id="lightbox-close" autofocus aria-label="Close">✕</button>
+        <img id="lightbox-img" src="" alt="" />
+        <p id="lightbox-caption"></p>
+    </div>
+</dialog>
+```
+
+**Critical:** `padding: 0` on `<dialog>` itself, padding on `.lightbox-inner`. Otherwise padding area falsely triggers close.
+
+## JavaScript Logic
+
+Use **event delegation** on `document` (not per-image listeners) — this is View-Transitions-safe if ever added later.
+
+```javascript
+const dialog = document.getElementById('lightbox')
+const lightboxImg = document.getElementById('lightbox-img')
+const lightboxCaption = document.getElementById('lightbox-caption')
+
+document.addEventListener('click', (e) => {
+    const img = e.target.closest('article img:not([data-no-lightbox])')
+    if (!img) return
+    lightboxImg.src = img.src
+    lightboxImg.alt = img.alt
+    const figcaption = img.closest('figure')?.querySelector('figcaption')
+    lightboxCaption.textContent =
+        figcaption?.textContent?.replace(/^\/\/\s*/, '') ?? ''
+    lightboxCaption.hidden = !lightboxCaption.textContent
+    document.body.style.overflow = 'hidden'
+    dialog.showModal()
+})
+
+// Click outside to close (backdrop maps to dialog element)
+dialog.addEventListener('click', (e) => {
+    if (e.target === dialog) dialog.close()
+})
+
+// Restore scroll on close
+dialog.addEventListener('close', () => {
+    document.body.style.overflow = ''
+    lightboxImg.src = ''
+})
+```
+
+## CSS (in `<style>` block or inline in BlogPost.astro)
+
+Use existing CSS custom properties for theme consistency:
+
+```css
+article img:not([data-no-lightbox]) {
+    cursor: zoom-in;
+}
+
+#lightbox {
+    padding: 0;
+    border: none;
+    background: transparent;
+    max-width: 100vw;
+    max-height: 100vh;
+}
+
+#lightbox::backdrop {
+    background: rgba(0, 0, 0, 0.85);
+    backdrop-filter: blur(4px);
+}
+
+.lightbox-inner {
+    position: relative;
+    background: var(--color-bg-primary);
+    border: 1px solid var(--color-border-default);
+    box-shadow: 0 8px 32px var(--color-shadow-default);
+    padding: 1rem;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.75rem;
+    max-width: 90vw;
+    max-height: 90vh;
+}
+
+#lightbox-close {
+    position: absolute;
+    top: 0.5rem;
+    right: 0.5rem;
+    background: transparent;
+    border: 1px solid var(--color-border-default);
+    color: var(--color-text-primary);
+    font-family: monospace;
+    padding: 0.25rem 0.5rem;
+    cursor: pointer;
+    line-height: 1;
+}
+
+#lightbox-close:hover {
+    border-color: var(--color-accent-primary);
+    color: var(--color-accent-primary);
+}
+
+#lightbox-img {
+    max-width: 85vw;
+    max-height: 75vh;
+    width: auto;
+    height: auto;
+    display: block;
+    cursor: zoom-out;
+}
+
+#lightbox-caption {
+    color: var(--color-text-secondary);
+    font-family: monospace;
+    font-size: 0.875rem;
+    text-align: center;
+    margin: 0;
+}
+
+#lightbox-caption::before {
+    content: '// ';
+}
+```
+
+## Aesthetic Notes
+
+- Terminal aesthetic: monospace fonts, `//` caption prefix (matches existing `figcaption` style)
+- No `rounded-lg` — square/sharp borders
+- Accent color (`--color-accent-primary`) used on close button hover only
+- Caption prefix `// ` matches existing `CaptionedImage` figcaption `::before` style
+
+## After Implementation
+
+Run visual verification per CLAUDE.md:
+
+1. `pnpm dev` to start dev server
+2. Playwright screenshots at 375px, 768px, 1280px
+3. Save to `.playwright-mcp/screenshots/`
+4. Check browser console for errors
+
+## Notes from Research
+
+- `dialog.showModal()` handles focus trap, Escape key, and focus return automatically
+- No need for `aria-modal="true"` when using `showModal()` (redundant but harmless)
+- The `// ` prefix on captions in existing `CaptionedImage` is added via CSS `::before` — strip it before displaying in lightbox caption (`.replace(/^\/\/\s*/, '')`)
+- View Transitions not currently enabled — no lifecycle event handling needed. If added later, the delegation pattern already handles it without changes.
diff --git a/.crafter/scratch/image-lightbox-research.md b/.crafter/scratch/image-lightbox-research.md
new file mode 100644
index 0000000..455f2fc
--- /dev/null
+++ b/.crafter/scratch/image-lightbox-research.md
@@ -0,0 +1,157 @@
+# Research: Site-Wide Image Lightbox
+
+## Feature Summary
+
+Add click-to-enlarge lightbox behavior to all images in blog posts — `<CaptionedImage>` components, plain markdown `img` tags, and the hero image — using native `<dialog>`, vanilla JS, no libraries.
+
+---
+
+## Codebase Findings
+
+### Rendering Pipeline
+
+- `src/pages/blog/[...slug].astro` → fetches post, calls `render(post)`, passes `<Content />` to `BlogPost.astro`
+- `src/layouts/BlogPost.astro` — full HTML document, renders hero image + `<slot />` for post content inside `<article>`
+- **Injection point:** `BlogPost.astro` body (after `<Footer />`) for the shared `<dialog>` and script
+
+### Image Sources in Posts
+
+1. `<CaptionedImage>` — renders as `<figure><img ...><figcaption>` — covered by `article img` selector
+2. Plain markdown images — render as bare `<img>` in `<article>` — covered by `article img` selector
+3. Direct `<Image>` from `astro:assets` — renders as `<img>` — covered by `article img` selector
+4. Hero image — in `BlogPost.astro` layout, outside `<article>` — needs separate handling or opt-out
+
+### Existing Patterns
+
+- Scripts: `<script>` tags in components (hydrated module scripts), `is:inline` only for FOUC-critical code
+- No `src/scripts/` directory; scripts live in their components
+- No View Transitions enabled (safe to use standard DOM APIs)
+- Images scoped to `<article>` element in BlogPost layout
+
+### Theming / CSS Variables
+
+- `--color-bg-primary`: `#ffffff` / `#0d1117` (dark)
+- `--color-accent-primary`: `#00b894` / `#07f5bd` (dark) ← cyan accent
+- `--color-border-default`: `#d0d7de` / `#30363d`
+- `--color-shadow-default`: `rgba(31,35,40,0.12)` / `rgba(1,4,9,0.8)`
+- `--color-text-secondary`: for captions
+- Existing hero shadow: `shadow-[0_4px_12px_var(--color-shadow-default)]`
+
+---
+
+## Web Research Findings
+
+### Approach: Global DOM query vs MDX component override
+
+**Confidence: High**
+
+`document.querySelectorAll('article img')` is the right approach. It catches all image types uniformly without modifying individual MDX files. The MDX `components` prop override only handles markdown-rendered images, misses `<CaptionedImage>` internals, and requires per-post changes.
+
+### Shared dialog vs per-image dialogs
+
+**Confidence: High**
+
+One shared `<dialog>` is the clear winner:
+
+- Smaller DOM (1 element vs N)
+- Accessibility: single managed focus/aria state
+- W3C APG and eBay MIND Patterns both recommend single-instance pattern
+
+Pattern: store references to `dialog`, inner `img`, and `figcaption`. On click, update `img.src`, `img.alt`, caption text, then call `dialog.showModal()`.
+
+### Native `<dialog>` best practices
+
+**Confidence: High**
+
+- Use `dialog.showModal()` — puts element in top layer, creates `::backdrop`, traps focus, handles Escape natively
+- **Close button first** in DOM order (before the image), or use `autofocus` on close button
+- Click-outside: `e.target === dialog` — works because backdrop maps to dialog element. **Critical:** put `padding: 0` on `<dialog>`, padding on inner wrapper `<div>`. Otherwise padding area triggers false closes.
+- Background scroll: `showModal()` does NOT lock scroll — must manually set `document.body.style.overflow = 'hidden'` on open, restore on close
+- Return focus: `dialog.close()` automatically returns focus to the element that triggered `showModal()` — no manual management needed
+- `dialog::backdrop` for overlay; `backdrop-filter: blur(4px)` optional
+
+```css
+dialog::backdrop {
+    background: rgba(0, 0, 0, 0.85);
+    backdrop-filter: blur(4px);
+}
+```
+
+### Event delegation (future-proof)
+
+**Confidence: High**
+
+Using event delegation on `document` rather than per-image listeners is more robust and View-Transitions-safe (if ever added):
+
+```javascript
+document.addEventListener('click', (e) => {
+    const img = e.target.closest('article img')
+    if (img) openLightbox(img.src, img.alt)
+})
+```
+
+This avoids the re-attachment problem if View Transitions are added later.
+
+### View Transitions (currently moot, worth noting)
+
+**Confidence: High**
+
+No View Transitions in this project. If added later: bundled module scripts run once and don't re-run after soft navigation. The event delegation pattern above is immune to this. If per-image listeners are used instead, wrap init in `astro:after-swap` + direct call.
+
+---
+
+## Recommended Architecture
+
+### Files to modify/create
+
+1. **`src/layouts/BlogPost.astro`** — add `<dialog>` element + `<script>` for lightbox
+2. **`src/components/CaptionedImage.astro`** — add `data-lightbox-caption` attribute on `<figcaption>` text so the lightbox can pick up the caption
+
+### Implementation sketch
+
+**HTML (in BlogPost.astro body):**
+
+```html
+<dialog id="lightbox" aria-label="Image lightbox">
+    <div class="lightbox-inner">
+        <button id="lightbox-close" autofocus aria-label="Close lightbox">
+            ✕
+        </button>
+        <img id="lightbox-img" src="" alt="" />
+        <p id="lightbox-caption"></p>
+    </div>
+</dialog>
+```
+
+**JS (delegated, in BlogPost.astro `<script>`):**
+
+- Delegated click listener on `document` for `article img`
+- On open: set img src/alt, caption from closest `figcaption` or `alt`, `showModal()`, lock scroll
+- On close: clear src, unlock scroll (handled by `close` event)
+- Click-outside: `e.target === dialog` → `dialog.close()`
+
+**CSS:**
+
+- `dialog::backdrop`: dark overlay + optional blur
+- Inner div: `border: 1px solid var(--color-border-default)`, `background: var(--color-bg-primary)`
+- Close button: styled with `--color-accent-primary` hover, no rounded-lg
+- Caption: `color: var(--color-text-secondary)`, monospace, `// ` prefix (matches existing figcaption style)
+- `img` inside dialog: `max-height: 80vh; max-width: 90vw; width: auto`
+- `cursor: zoom-in` on `article img` via CSS
+
+### Hero image
+
+Hero image is outside `<article>` in BlogPost layout. Two options:
+
+- Add `data-lightbox` attribute to hero `<img>` and include in the selector
+- Or exclude it (hero is already large/full-width)
+
+**Recommendation:** Exclude hero image from lightbox — it's already displayed at full width and clicking it to enlarge would be confusing.
+
+---
+
+## Open Questions
+
+1. Should `cursor: zoom-in` be applied globally to `article img` via `global.css`, or scoped to the script?
+2. Caption text source: use `closest('figure') .querySelector('figcaption')?.textContent` — will be empty for non-captioned images, which is fine.
+3. Hero image opt-out: add `data-no-lightbox` attribute to hero `<img>` in BlogPost layout and scope selector to `article img:not([data-no-lightbox])`.