feat: theming system, documentation, and photo grid regression tests

- Add configurable theme system with 4 presets (studio, minimal, editorial, classic)
- Theme controls fonts, colors, accent, photo frames, grain, and header dot
- Resolve themes from gallery.yaml: string shorthand or full object override
- Inject theme as CSS custom properties on <html> element
- Dynamic Google Fonts loading based on theme config
- OG image route reads accent/background from theme
- Refactor Studio overrides into conditional CSS via data-attributes

Documentation:
- Add docs/gallery-config.md with comprehensive configuration reference
- Add docs/theming.md with preset reference and custom theme guide
- Slim README to link to detailed docs

Fix CSS regression:
- Fix passepartout frame overflow:visible breaking next/image fill rendering
- Remove duplicate .photo-grid__item block that stripped overflow:hidden

Testing:
- Add e2e/photo-grid.spec.ts with 3 regression tests:
  - Grid items render with real dimensions
  - overflow:hidden CSS guard (catches the exact bug fixed)
  - Images load with real pixel data (not blurhash)

Tooling:
- Add scripts/screenshots.ts for automated theme screenshot generation
- Handles dev server lifecycle, theme cycling, FadeIn + lazy image handling

.gitignore

@@ -45,3 +45,7 @@ next-env.d.ts
 
 # internal dev docs
 dev-docs/
+
+# generated screenshots
+docs/screenshots/
+

README.md

@@ -78,63 +78,21 @@ CACHE_TTL=300                          # seconds, default: 300
 RATE_LIMIT_RPM=120                     # requests/min/IP, default: 120
 ```
 
-### Gallery Config (`content/gallery.yaml`)
+### Gallery Config
+
+All gallery structure — hero images, albums, subpages, grid layout, footer — is defined in `content/gallery.yaml`.
+
+→ **[Gallery Configuration Guide](docs/gallery-config.md)**
+
+### Theming
+
+Customize the visual identity of your gallery with built-in presets or fine-grained control over colors, fonts, corners, photo frames, and more.
 
 ```yaml
-# Hero image(s) — single UUID or list for carousel
+theme: minimal   # or: studio, editorial, classic
-hero: 00000000-0000-0000-0000-000000000000
-# hero:
-#   - uuid-1
-#   - uuid-2
-
-# Standalone albums on the homepage
-albums:
-  - 11111111-1111-1111-1111-111111111111
-  - 22222222-2222-2222-2222-222222222222
-
-# EXIF on hover (default: true)
-# exifOnHover: false
-
-# Global grid layout
-# grid:
-#   columns: 3
-#   gap: 12
-#   aspectRatio: "1"
-#   layout: masonry       # "masonry" or "uniform"
-
-# Subpages — group albums into collections
-subpages:
-  - name: Japan
-    grid:
-      columns: 4
-      layout: uniform
-      aspectRatio: '3/2'
-    albums:
-      - uuid-tokyo
-      - uuid-kyoto
-
-  - name: Wedding – Smith
-    password: clientpass123
-    albums:
-      - uuid-wedding
 ```
 
-See `content/gallery.yaml.example` for the full reference.
+→ **[Theming Guide](docs/theming.md)**
-
-### About Page (`content/about.md`)
-
-```markdown
----
-portrait: asset-uuid
-name: Your Name
-location: City, Country
-gear:
-  - Camera Body
-  - Favorite Lens
----
-
-Your bio text here.
-```
 
 ## Docker
 

app/api/og/route.tsx

@@ -1,12 +1,14 @@
 /**
  * Dynamic OG image generator — renders social share previews.
  * Uses next/og (ImageResponse) to create 1200×630 cards.
+ * Reads accent color from theme config.
  *
  * GET /api/og?title=Album+Name&subtitle=12+photos
  */
 
 import { ImageResponse } from 'next/og';
 import { NextRequest } from 'next/server';
+import { getConfig } from '@/lib/config';
 
 export const runtime = 'edge';
 
@@ -14,6 +16,7 @@ export async function GET(request: NextRequest) {
   const { searchParams } = request.nextUrl;
   const title = searchParams.get('title') || 'Gallery';
   const subtitle = searchParams.get('subtitle') || '';
+  const { theme } = getConfig();
 
   return new ImageResponse(
     <div
@@ -34,7 +37,7 @@ export async function GET(request: NextRequest) {
         style={{
           width: '60px',
           height: '2px',
-          backgroundColor: '#d4af37',
+          backgroundColor: theme.accent,
           marginBottom: '40px',
         }}
       />
@@ -75,7 +78,7 @@ export async function GET(request: NextRequest) {
         style={{
           width: '60px',
           height: '2px',
-          backgroundColor: '#d4af37',
+          backgroundColor: theme.accent,
           marginTop: '40px',
         }}
       />

app/globals.css

@@ -279,12 +279,10 @@
   flex-direction: column;
   justify-content: flex-end;
   padding: 24px;
-  background: linear-gradient(
+  background: linear-gradient(to top,
-    to top,
+      rgba(0, 0, 0, 0.8) 0%,
-    rgba(0, 0, 0, 0.8) 0%,
+      rgba(0, 0, 0, 0.3) 40%,
-    rgba(0, 0, 0, 0.3) 40%,
+      transparent 100%);
-    transparent 100%
-  );
   opacity: 0;
   transition: opacity var(--transition-normal);
 }
@@ -414,12 +412,10 @@
 
 /* ── Loading States ───────────────────────────────── */
 .skeleton {
-  background: linear-gradient(
+  background: linear-gradient(90deg,
-    90deg,
+      var(--bg-card) 0%,
-    var(--bg-card) 0%,
+      var(--bg-card-hover) 50%,
-    var(--bg-card-hover) 50%,
+      var(--bg-card) 100%);
-    var(--bg-card) 100%
-  );
   background-size: 200% 100%;
   animation: skeleton-shimmer 1.5s infinite;
   border-radius: var(--radius-sm);
@@ -604,10 +600,11 @@
   font-weight: 300;
 }
 
-/* ── Studio-Inspired Defaults ────────────────────── */
+/* ── Theme Conditionals ──────────────────────────── */
+/* Features toggled via data attributes on <html>, set by theme config */
 
-/* Red dot in header */
+/* ─ Header dot (accent circle in nav) ─ */
-.header__nav::before {
+[data-header-dot='true'] .header__nav::before {
   content: '';
   display: block;
   width: 10px;
@@ -618,6 +615,78 @@
   flex-shrink: 0;
 }
 
+/* ─ Passepartout photo frame ─ */
+[data-photo-frame='passepartout'] .photo-grid__item {
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  padding: 8px 8px 24px;
+  margin-bottom: var(--grid-gap, 24px);
+  background: #111;
+  overflow: hidden;
+}
+
+[data-photo-frame='passepartout'][data-theme='light'] .photo-grid__item {
+  border-color: rgba(0, 0, 0, 0.1);
+  background: #fff;
+}
+
+[data-photo-frame='passepartout'] .photo-grid__item-exif {
+  position: relative;
+  bottom: auto;
+  left: auto;
+  right: auto;
+  background: none;
+  padding: 8px 0 0;
+  color: var(--text-muted);
+  font-family: var(--font-caption);
+  font-style: italic;
+  font-size: 0.75rem;
+  letter-spacing: 0.02em;
+  white-space: normal;
+  opacity: 1;
+  text-align: center;
+}
+
+[data-photo-frame='passepartout'] .photo-grid__item:hover .photo-grid__item-exif {
+  opacity: 1;
+}
+
+/* ─ Shadow photo frame ─ */
+[data-photo-frame='shadow'] .photo-grid__item {
+  border-radius: var(--radius-sm);
+  box-shadow: 0 2px 20px rgba(0, 0, 0, 0.3);
+  overflow: hidden;
+}
+
+[data-photo-frame='shadow'][data-theme='light'] .photo-grid__item {
+  box-shadow: 0 2px 16px rgba(0, 0, 0, 0.12);
+}
+
+/* ─ Film grain overlay ─ */
+[data-grain='true'] .photo-grid__item::after {
+  content: '';
+  position: absolute;
+  top: 8px;
+  left: 8px;
+  right: 8px;
+  bottom: 24px;
+  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.04'/%3E%3C/svg%3E");
+  background-size: 128px 128px;
+  pointer-events: none;
+  z-index: 1;
+  mix-blend-mode: overlay;
+}
+
+/* Grain without passepartout — fill the whole item */
+[data-grain='true'][data-photo-frame='none'] .photo-grid__item::after,
+[data-grain='true'][data-photo-frame='shadow'] .photo-grid__item::after {
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+}
+
+/* ── Gallery Aesthetics (all themes) ─────────────── */
+
 /* Generous spacing — gallery exhibition feel */
 .main {
   padding: 64px 40px 120px;
@@ -639,68 +708,11 @@
   letter-spacing: 0.2em;
 }
 
-/* Photo grid — passepartout white borders */
+/* Photo grid gap */
 .photo-grid {
   column-gap: var(--grid-gap, 24px);
 }
 
-.photo-grid__item {
-  border: 1px solid rgba(255, 255, 255, 0.12);
-  padding: 8px 8px 24px;
-  margin-bottom: var(--grid-gap, 24px);
-  background: #111;
-  border-radius: 0;
-  cursor: pointer;
-  position: relative;
-  overflow: visible;
-}
-
-[data-theme='light'] .photo-grid__item {
-  border-color: rgba(0, 0, 0, 0.1);
-  background: #fff;
-}
-
-.photo-grid__item img {
-  border-radius: 0;
-}
-
-/* Film grain overlay */
-.photo-grid__item::after {
-  content: '';
-  position: absolute;
-  top: 8px;
-  left: 8px;
-  right: 8px;
-  bottom: 24px;
-  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.04'/%3E%3C/svg%3E");
-  background-size: 128px 128px;
-  pointer-events: none;
-  z-index: 1;
-  mix-blend-mode: overlay;
-}
-
-/* Print-style captions (replaces EXIF overlay) */
-.photo-grid__item-exif {
-  position: relative;
-  bottom: auto;
-  left: auto;
-  right: auto;
-  background: none;
-  padding: 8px 0 0;
-  color: var(--text-muted);
-  font-family: var(--font-caption, 'EB Garamond', Georgia, serif);
-  font-style: italic;
-  font-size: 0.75rem;
-  letter-spacing: 0.02em;
-  white-space: normal;
-  opacity: 1;
-  text-align: center;
-}
-
-.photo-grid__item:hover .photo-grid__item-exif {
-  opacity: 1;
-}
-
 /* Shutter-click feedback */
 .photo-grid__item:active img {
   filter: brightness(0.6);
@@ -740,9 +752,9 @@
   color: var(--accent);
 }
 
-/* Album cards — sharper, no rounded corners */
+/* Album cards */
 .album-card {
-  border-radius: 0;
+  border-radius: var(--radius-md);
   border-color: rgba(255, 255, 255, 0.08);
 }
 
@@ -755,7 +767,7 @@
   transform: none;
 }
 
-/* Subpage grid — clean */
+/* Subpage grid */
 .subpage-grid__item {
   border: 1px solid rgba(255, 255, 255, 0.08);
 }
@@ -764,19 +776,17 @@
   border-color: rgba(0, 0, 0, 0.08);
 }
 
-/* Nav link accent on hover */
+/* Accent hover effects (works with any accent color) */
 .header__nav-link:hover,
 .header__nav-link.active {
   color: var(--accent);
   border-bottom-color: var(--accent);
 }
 
-/* Footer — red accent on hover */
 .footer__link:hover {
   color: var(--accent);
 }
 
-/* Scroll-to-top — red accent on hover */
 .scroll-to-top:hover {
   border-color: var(--accent);
   color: var(--accent);
@@ -846,7 +856,7 @@
     opacity: 1;
   }
 
-  .photo-grid__item {
+  [data-photo-frame='passepartout'] .photo-grid__item {
     padding: 6px 6px 18px;
   }
-}
+}

app/layout.tsx

@@ -1,6 +1,7 @@
 /**
  * Root layout — site header with portfolio-style navigation.
  * Shows all subpages + standalone albums as nav links.
+ * Injects theme CSS custom properties from gallery.yaml config.
  */
 
 import type { Metadata } from 'next';
@@ -10,6 +11,7 @@ import { SubpageNav } from '@/components/SubpageNav';
 import { ThemeToggle } from '@/components/ThemeToggle';
 import { ScrollToTop } from '@/components/ScrollToTop';
 import { Footer } from '@/components/Footer';
+import { getConfig, getGoogleFontsUrl } from '@/lib/config';
 
 const siteTitle = process.env.SITE_TITLE || 'Gallery';
 const siteDescription = 'A curated photography portfolio';
@@ -35,8 +37,35 @@ export const metadata: Metadata = {
 };
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const { theme } = getConfig();
+  const fontsUrl = getGoogleFontsUrl(theme);
+
+  // Inject theme values as CSS custom properties
+  const themeVars: Record<string, string> = {
+    '--accent': theme.accent,
+    '--accent-dim': `${theme.accent}1f`,
+    '--font-serif': `'${theme.fonts.heading}', Georgia, 'Times New Roman', serif`,
+    '--font-sans': `'${theme.fonts.body}', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif`,
+    '--font-caption': `'${theme.fonts.caption}', Georgia, serif`,
+    '--radius-sm': `${theme.radius}px`,
+    '--radius-md': `${Math.round(theme.radius * 1.5)}px`,
+    '--radius-lg': `${theme.radius * 2}px`,
+  };
+
   return (
-    <html lang="en" suppressHydrationWarning>
+    <html
+      lang="en"
+      suppressHydrationWarning
+      style={themeVars as React.CSSProperties}
+      data-grain={theme.grain}
+      data-header-dot={theme.headerDot}
+      data-photo-frame={theme.photoFrame}
+    >
+      <head>
+        <link rel="preconnect" href="https://fonts.googleapis.com" />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+        <link rel="stylesheet" href={fontsUrl} />
+      </head>
       <body>
         <header className="header">
           <nav className="header__nav">

app/tokens.css

@@ -1,6 +1,7 @@
-@import url('https://fonts.googleapis.com/css2?family=DM+Sans:wght@300;400;500;600&family=Playfair+Display:wght@400;500;600&family=EB+Garamond:ital,wght@0,400;1,400&display=swap');
+/* Fonts are loaded dynamically via layout.tsx based on theme config */
 
-/* ── Design Tokens (Studio Dark — Default) ───────── */
+/* ── Design Tokens (Fallback Defaults) ───────────── */
+/* These are overridden at runtime by CSS vars injected from gallery.yaml theme config. */
 :root {
   --bg-primary: #1a1a1a;
   --bg-secondary: #141414;
@@ -83,4 +84,4 @@ a {
 img {
   display: block;
   max-width: 100%;
-}
+}

content/gallery.yaml.example

@@ -49,3 +49,24 @@ subpages:
 #   instagram: johndoe
 #   email: hello@example.com
 #   website: https://example.com
+
+# ── Theme ─────────────────────────────────────────────────────
+# Control the visual identity of your gallery. Use a preset name:
+#   theme: studio     # Leica-inspired, red accent, passepartout frames, film grain
+#   theme: minimal    # Clean, no distractions, grey accent
+#   theme: editorial  # Magazine feel, shadow frames
+#   theme: classic    # Warm, golden accent, rounded corners
+#
+# Or customize individual properties (defaults from the preset):
+# theme:
+#   preset: studio              # base preset to extend
+#   accent: "#2563eb"           # brand/accent color
+#   fonts:
+#     heading: "Inter"          # Google Fonts name for headings
+#     body: "Inter"             # body text
+#     caption: "JetBrains Mono" # EXIF captions
+#   radius: 8                   # border-radius in pixels (0 = sharp)
+#   photoFrame: none            # "none" | "passepartout" | "shadow"
+#   grain: false                # film grain overlay on photos
+#   headerDot: false            # accent dot in the nav bar
+#   heroStyle: split            # "split" | "fullbleed" | "minimal"

docs/gallery-config.md

@@ -0,0 +1,113 @@
+# Gallery Configuration
+
+All gallery structure is defined in `content/gallery.yaml`. Copy the example to get started:
+
+```bash
+cp content/gallery.yaml.example content/gallery.yaml
+```
+
+## Hero Images
+
+Single image or crossfade carousel on the homepage:
+
+```yaml
+# Single hero image
+hero: 00000000-0000-0000-0000-000000000000
+
+# Carousel (crossfade between multiple images)
+hero:
+  - 00000000-0000-0000-0000-000000000000
+  - 11111111-1111-1111-1111-111111111111
+  - 22222222-2222-2222-2222-222222222222
+```
+
+## Standalone Albums
+
+Albums shown directly on the homepage as cards:
+
+```yaml
+albums:
+  - 11111111-1111-1111-1111-111111111111
+  - 22222222-2222-2222-2222-222222222222
+```
+
+## Subpages
+
+Group multiple albums into named collections. URLs are auto-generated from the name:
+
+```yaml
+subpages:
+  - name: Japan                    # → /japan
+    albums:
+      - 33333333-3333-3333-3333-333333333333  # Tokyo
+      - 44444444-4444-4444-4444-444444444444  # Kyoto
+
+  - name: Wedding – Smith         # → /wedding-smith
+    password: clientpass123        # password-protected
+    albums:
+      - 55555555-5555-5555-5555-555555555555
+```
+
+## Grid Layout
+
+Configure the photo grid globally or per-subpage:
+
+```yaml
+# Global defaults
+grid:
+  columns: 3            # number of columns (default: 3)
+  gap: 12               # gap in pixels (default: 12)
+  aspectRatio: "1"       # "1", "3/2", "auto", etc. (default: "1")
+  layout: masonry        # "masonry" or "uniform" (default: "masonry")
+
+subpages:
+  - name: Japan
+    grid:                # per-subpage override
+      columns: 4
+      layout: uniform
+      aspectRatio: "3/2"
+    albums:
+      - ...
+```
+
+## EXIF on Hover
+
+Show camera/lens/settings when hovering over photos (enabled by default):
+
+```yaml
+exifOnHover: false    # set to false to disable
+```
+
+## Footer
+
+Optional minimal footer with social links:
+
+```yaml
+footer:
+  name: John Doe
+  instagram: johndoe
+  email: hello@example.com
+  website: https://example.com
+```
+
+## About Page
+
+Create `content/about.md` with YAML frontmatter:
+
+```markdown
+---
+portrait: asset-uuid-for-your-portrait
+name: Your Name
+location: City, Country
+gear:
+  - Camera Body
+  - Favorite Lens
+---
+
+Your bio text here. Supports full Markdown.
+```
+
+## Finding UUIDs
+
+- **Album UUIDs**: In Immich, go to Albums → click an album → the UUID is in the URL bar
+- **Asset UUIDs**: Click any photo → the UUID is in the URL bar

docs/theming.md

@@ -0,0 +1,121 @@
+# Theming
+
+Control the visual identity of your gallery from `content/gallery.yaml`. Choose a built-in preset or customize individual properties — no CSS editing required.
+
+## Quick Start
+
+Add a single line to your `gallery.yaml`:
+
+```yaml
+theme: minimal
+```
+
+That's it. Your entire gallery switches to the minimal theme.
+
+## Built-in Presets
+
+| Preset | Look | Accent | Fonts | Corners | Frame | Grain |
+|--------|------|--------|-------|---------|-------|-------|
+| **studio** | Leica-inspired, editorial | 🔴 `#e60012` | Playfair Display + DM Sans | Sharp | Passepartout | ✓ |
+| **minimal** | Clean, no distractions | ⚪ `#666666` | Inter | Sharp | None | ✗ |
+| **editorial** | Magazine feel | ⚫ `#1a1a1a` | Libre Baskerville + Source Sans | Slight | Shadow | ✗ |
+| **classic** | Warm, inviting | 🟡 `#8b6914` | Cormorant Garamond + Lato | Rounded | None | ✗ |
+
+Default is `studio` if no theme is specified.
+
+## Custom Theme
+
+Start from any preset and override individual properties:
+
+```yaml
+theme:
+  preset: studio              # base preset to extend (default: studio)
+  accent: "#2563eb"           # brand/accent color (any hex)
+  fonts:
+    heading: "Inter"          # Google Fonts name for headings
+    body: "Inter"             # body text
+    caption: "JetBrains Mono" # EXIF captions
+  radius: 8                   # border-radius in px (0 = sharp corners)
+  photoFrame: none            # "none" | "passepartout" | "shadow"
+  grain: false                # film grain overlay on photos
+  headerDot: false            # accent-colored dot in the nav bar
+  heroStyle: split            # "split" | "fullbleed" | "minimal"
+```
+
+All properties are optional — omitted values fall back to the preset defaults.
+
+## Properties Reference
+
+### `accent`
+
+The brand color used for hover effects, navigation highlights, the header dot, and OG social preview images.
+
+### `fonts`
+
+Google Fonts names. Fonts are loaded automatically — just use the name as it appears on [fonts.google.com](https://fonts.google.com). Three font slots:
+
+- **heading** — album titles, hero title, section labels
+- **body** — navigation, descriptions, UI text
+- **caption** — EXIF metadata, photo captions
+
+### `radius`
+
+Border radius in pixels applied to photo grid items and album cards:
+- `0` — sharp, editorial corners
+- `4-8` — subtle rounding
+- `12+` — soft, modern feel
+
+### `photoFrame`
+
+How photos are framed in the grid:
+
+- **`none`** — photos fill the grid cell directly
+- **`passepartout`** — museum-style mat border around each photo with print-style EXIF captions below
+- **`shadow`** — subtle drop shadow behind each photo
+
+### `grain`
+
+When `true`, a subtle film grain texture overlays each photo in the grid. Adds an analog, filmic character.
+
+### `headerDot`
+
+When `true`, shows a small accent-colored dot in the navigation bar (inspired by the Leica red dot).
+
+### `heroStyle`
+
+Controls the homepage hero layout:
+- **`split`** — title/nav on the left, hero image on the right (default)
+- **`fullbleed`** — hero image fills the entire viewport
+- **`minimal`** — text-only, no hero image
+
+## Examples
+
+### Minimal portfolio
+```yaml
+theme:
+  preset: minimal
+  accent: "#0066cc"
+  fonts:
+    heading: "Outfit"
+    body: "Outfit"
+```
+
+### Film photography blog
+```yaml
+theme:
+  preset: studio
+  accent: "#d4a017"
+  grain: true
+  photoFrame: passepartout
+```
+
+### Modern magazine
+```yaml
+theme:
+  preset: editorial
+  radius: 12
+  fonts:
+    heading: "Fraunces"
+    body: "Inter"
+    caption: "IBM Plex Mono"
+```

e2e/photo-grid.spec.ts

@@ -0,0 +1,75 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Photo Grid', () => {
+    // Use a known public subpage that has photos
+    const GRID_URL = '/deutschland/kloster-chorin-2024';
+
+    test('renders grid items with visible images', async ({ page }) => {
+        await page.goto(GRID_URL);
+
+        // Grid container should exist
+        const grid = page.locator('.photo-grid');
+        await expect(grid).toBeVisible();
+
+        // Should have grid items
+        const items = grid.locator('.photo-grid__item');
+        const count = await items.count();
+        expect(count).toBeGreaterThan(0);
+
+        // Scroll to trigger IntersectionObserver (FadeIn)
+        await items.first().scrollIntoViewIfNeeded();
+        await page.waitForTimeout(1000);
+
+        // First grid item should have real dimensions (not collapsed)
+        const firstItem = items.first();
+        const box = await firstItem.boundingBox();
+        expect(box).not.toBeNull();
+        expect(box!.width).toBeGreaterThan(100);
+        expect(box!.height).toBeGreaterThan(50);
+
+        // Image inside should exist and have the fill layout
+        const img = firstItem.locator('img');
+        await expect(img).toBeAttached();
+    });
+
+    test('grid items have overflow hidden (CSS regression)', async ({ page }) => {
+        // This test guards against the CSS cascade bug where a later rule
+        // strips `overflow: hidden` from .photo-grid__item, which breaks
+        // next/image fill rendering.
+        await page.goto(GRID_URL);
+
+        const grid = page.locator('.photo-grid');
+        await expect(grid).toBeVisible();
+
+        const item = grid.locator('.photo-grid__item').first();
+        await item.scrollIntoViewIfNeeded();
+
+        const overflow = await item.evaluate((el) => getComputedStyle(el).overflow);
+        expect(overflow).toBe('hidden');
+    });
+
+    test('images load with real content (not just blurhash)', async ({ page }) => {
+        await page.goto(GRID_URL);
+
+        // Scroll to trigger lazy loading
+        const grid = page.locator('.photo-grid');
+        await grid.scrollIntoViewIfNeeded();
+        await page.waitForTimeout(3000);
+
+        // Check that at least one image has loaded with real pixel data
+        const imgLoaded = await page.evaluate(() => {
+            const img = document.querySelector('.photo-grid__item img') as HTMLImageElement;
+            if (!img) return { found: false };
+            return {
+                found: true,
+                complete: img.complete,
+                naturalWidth: img.naturalWidth,
+                src: img.src.substring(0, 60),
+            };
+        });
+
+        expect(imgLoaded.found).toBe(true);
+        expect(imgLoaded.complete).toBe(true);
+        expect(imgLoaded.naturalWidth).toBeGreaterThan(0);
+    });
+});

lib/config.ts

@@ -31,11 +31,80 @@ export interface FooterConfig {
   website?: string;
 }
 
+/** Theme configuration — controls the visual identity of the gallery. */
+export interface ThemeConfig {
+  preset: string;
+  accent: string;
+  fonts: { heading: string; body: string; caption: string };
+  radius: number;
+  photoFrame: 'none' | 'passepartout' | 'shadow';
+  grain: boolean;
+  headerDot: boolean;
+  heroStyle: 'split' | 'fullbleed' | 'minimal';
+}
+
+// ── Theme Presets ──────────────────────────────────────────────
+
+const THEME_PRESETS: Record<string, ThemeConfig> = {
+  studio: {
+    preset: 'studio',
+    accent: '#e60012',
+    fonts: { heading: 'Playfair Display', body: 'DM Sans', caption: 'EB Garamond' },
+    radius: 0,
+    photoFrame: 'passepartout',
+    grain: true,
+    headerDot: true,
+    heroStyle: 'split',
+  },
+  minimal: {
+    preset: 'minimal',
+    accent: '#666666',
+    fonts: { heading: 'Inter', body: 'Inter', caption: 'JetBrains Mono' },
+    radius: 0,
+    photoFrame: 'none',
+    grain: false,
+    headerDot: false,
+    heroStyle: 'split',
+  },
+  editorial: {
+    preset: 'editorial',
+    accent: '#1a1a1a',
+    fonts: { heading: 'Libre Baskerville', body: 'Source Sans 3', caption: 'Source Sans 3' },
+    radius: 4,
+    photoFrame: 'shadow',
+    grain: false,
+    headerDot: false,
+    heroStyle: 'split',
+  },
+  classic: {
+    preset: 'classic',
+    accent: '#8b6914',
+    fonts: { heading: 'Cormorant Garamond', body: 'Lato', caption: 'Lato' },
+    radius: 8,
+    photoFrame: 'none',
+    grain: false,
+    headerDot: false,
+    heroStyle: 'split',
+  },
+};
+
 /** Raw YAML structure (before validation). */
 interface GalleryYaml {
   hero?: string | string[];
   albums?: string[];
   exifOnHover?: boolean;
+  theme?:
+    | string
+    | {
+        preset?: string;
+        accent?: string;
+        fonts?: { heading?: string; body?: string; caption?: string };
+        radius?: number;
+        photoFrame?: string;
+        grain?: boolean;
+        headerDot?: boolean;
+        heroStyle?: string;
+      };
   grid?: {
     columns?: number;
     gap?: number;
@@ -133,12 +202,74 @@ export interface AppConfig {
   exifOnHover: boolean;
   /** Photo grid layout configuration. */
   grid: GridConfig;
+  /** Theme configuration. */
+  theme: ThemeConfig;
   /** Footer social links config. */
   footer: FooterConfig | null;
   cacheTtl: number;
   rateLimitRpm: number;
 }
 
+// ── Theme resolution ───────────────────────────────────────────
+
+const VALID_PHOTO_FRAMES = ['none', 'passepartout', 'shadow'];
+const VALID_HERO_STYLES = ['split', 'fullbleed', 'minimal'];
+
+function resolveTheme(raw?: GalleryYaml['theme']): ThemeConfig {
+  // No theme key → default preset
+  if (!raw) return { ...THEME_PRESETS.studio };
+
+  // String shorthand: `theme: minimal`
+  if (typeof raw === 'string') {
+    const preset = THEME_PRESETS[raw];
+    if (!preset) {
+      throw new Error(
+        `Unknown theme preset "${raw}". Valid presets: ${Object.keys(THEME_PRESETS).join(', ')}`,
+      );
+    }
+    return { ...preset };
+  }
+
+  // Object: merge with base preset
+  const baseName = raw.preset ?? 'studio';
+  const base = THEME_PRESETS[baseName];
+  if (!base) {
+    throw new Error(
+      `Unknown theme preset "${baseName}". Valid presets: ${Object.keys(THEME_PRESETS).join(', ')}`,
+    );
+  }
+
+  return {
+    preset: baseName,
+    accent: raw.accent ?? base.accent,
+    fonts: {
+      heading: raw.fonts?.heading ?? base.fonts.heading,
+      body: raw.fonts?.body ?? base.fonts.body,
+      caption: raw.fonts?.caption ?? base.fonts.caption,
+    },
+    radius: raw.radius ?? base.radius,
+    photoFrame: VALID_PHOTO_FRAMES.includes(raw.photoFrame ?? '')
+      ? (raw.photoFrame as ThemeConfig['photoFrame'])
+      : base.photoFrame,
+    grain: raw.grain ?? base.grain,
+    headerDot: raw.headerDot ?? base.headerDot,
+    heroStyle: VALID_HERO_STYLES.includes(raw.heroStyle ?? '')
+      ? (raw.heroStyle as ThemeConfig['heroStyle'])
+      : base.heroStyle,
+  };
+}
+
+/**
+ * Build a Google Fonts URL for the theme's fonts.
+ * Deduplicates fonts and includes key weights.
+ */
+export function getGoogleFontsUrl(theme: ThemeConfig): string {
+  const weights = '300;400;500;600';
+  const families = [...new Set([theme.fonts.heading, theme.fonts.body, theme.fonts.caption])];
+  const params = families.map((f) => `family=${f.replace(/ /g, '+')}:wght@${weights}`).join('&');
+  return `https://fonts.googleapis.com/css2?${params}&display=swap`;
+}
+
 // ── Config builder ─────────────────────────────────────────────
 
 let _config: AppConfig | null = null;
@@ -150,6 +281,9 @@ export function getConfig(): AppConfig {
   const apiKey = env.IMMICH_API_KEY;
   const gallery = loadGalleryYaml();
 
+  // Resolve theme: string shorthand → preset, object → merged with preset base
+  const theme = resolveTheme(gallery.theme);
+
   // Parse standalone albums
   const standaloneAlbumIds = (gallery.albums ?? []).map((id) =>
     validateUuid(id, 'gallery.yaml albums'),
@@ -216,6 +350,7 @@ export function getConfig(): AppConfig {
       aspectRatio: gallery.grid?.aspectRatio ?? '1',
       layout: (gallery.grid?.layout === 'uniform' ? 'uniform' : 'masonry') as GridConfig['layout'],
     },
+    theme,
     footer: gallery.footer
       ? {
           name: gallery.footer.name,

scripts/screenshots.ts

@@ -0,0 +1,200 @@
+/**
+ * Theme Screenshot Generator
+ *
+ * Captures homepage and grid view screenshots for each theme preset.
+ * Uses Playwright to wait for images to fully load (not just blurhash placeholders).
+ *
+ * Usage:
+ *   npx tsx scripts/screenshots.ts
+ *
+ * Prerequisites:
+ *   - Dev server NOT running (script manages its own server lifecycle)
+ *   - Playwright browsers installed: npx playwright install chromium
+ *
+ * Output:
+ *   docs/screenshots/theme-{preset}-{page}.png
+ */
+
+import { execSync, spawn, type ChildProcess } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+const THEMES = ['studio', 'minimal', 'editorial', 'classic'];
+const BASE_URL = 'http://localhost:3000';
+const GRID_PATH = '/deutschland/kloster-chorin-2024'; // public subpage with photos
+const OUTPUT_DIR = path.join(process.cwd(), 'docs', 'screenshots');
+const GALLERY_YAML = path.join(process.cwd(), 'content', 'gallery.yaml');
+const VIEWPORT = { width: 1440, height: 900 };
+const IMAGE_LOAD_TIMEOUT = 8000; // ms to wait for images after networkidle
+
+async function main() {
+    // Ensure output directory exists
+    fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+
+    // Read original gallery.yaml to restore later
+    const originalYaml = fs.readFileSync(GALLERY_YAML, 'utf8');
+
+    // Dynamic import for Playwright (may not be installed globally)
+    const { chromium } = await import('playwright');
+    const browser = await chromium.launch();
+
+    try {
+        for (const theme of THEMES) {
+            console.log(`\n🎨 Theme: ${theme}`);
+            console.log('─'.repeat(50));
+
+            // Update gallery.yaml with the theme
+            const yamlWithTheme = setThemeInYaml(originalYaml, theme);
+            fs.writeFileSync(GALLERY_YAML, yamlWithTheme);
+
+            // Start dev server
+            console.log('  ⏳ Starting dev server...');
+            const server = startDevServer();
+            await waitForServer(BASE_URL, 15000);
+            console.log('  ✅ Server ready');
+
+            const context = await browser.newContext({ viewport: VIEWPORT });
+            const page = await context.newPage();
+
+            // ── Homepage screenshot ──
+            console.log('  📸 Capturing homepage...');
+            await page.goto(BASE_URL, { waitUntil: 'networkidle' });
+            await waitForImages(page);
+            await page.screenshot({
+                path: path.join(OUTPUT_DIR, `theme-${theme}-home.png`),
+                fullPage: false,
+            });
+            console.log(`  ✅ theme-${theme}-home.png`);
+
+            // ── Grid view screenshot ──
+            console.log('  📸 Capturing grid view...');
+            await page.goto(`${BASE_URL}${GRID_PATH}`, { waitUntil: 'networkidle' });
+            // Force all fade-in elements visible (don't scroll — keep album title in view)
+            await page.evaluate(() => {
+                document.querySelectorAll('.fade-in').forEach(el => el.classList.add('fade-in--visible'));
+                // Trigger lazy images by switching to eager loading
+                document.querySelectorAll('img[loading="lazy"]').forEach(img => {
+                    (img as HTMLImageElement).loading = 'eager';
+                });
+            });
+            await waitForImages(page);
+            // Extra settle time for late-loading images in lower columns
+            await page.waitForTimeout(3000);
+            await page.screenshot({
+                path: path.join(OUTPUT_DIR, `theme-${theme}-grid.png`),
+                fullPage: false,
+            });
+            console.log(`  ✅ theme-${theme}-grid.png`);
+
+            await context.close();
+
+            // Stop dev server
+            server.kill('SIGTERM');
+            await new Promise((resolve) => server.on('close', resolve));
+            console.log('  🛑 Server stopped');
+        }
+    } finally {
+        // Always restore original gallery.yaml
+        fs.writeFileSync(GALLERY_YAML, originalYaml);
+        console.log('\n✅ Restored original gallery.yaml');
+        await browser.close();
+    }
+
+    console.log(`\n🎉 Done! Screenshots saved to ${OUTPUT_DIR}/`);
+    console.log(`   ${fs.readdirSync(OUTPUT_DIR).filter(f => f.endsWith('.png')).join(', ')}`);
+}
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function setThemeInYaml(yaml: string, theme: string): string {
+    // Replace existing theme line or insert after the header comment
+    if (/^theme:\s*.+$/m.test(yaml)) {
+        return yaml.replace(/^theme:\s*.+$/m, `theme: ${theme}`);
+    }
+    // Insert theme after the header comments
+    const marker = '# Secrets (API key, server URL) stay in .env.local.';
+    return yaml.replace(marker, `${marker}\n\ntheme: ${theme}`);
+}
+
+function startDevServer(): ChildProcess {
+    const server = spawn('npm', ['run', 'dev'], {
+        cwd: process.cwd(),
+        stdio: 'pipe',
+        env: { ...process.env },
+    });
+
+    // Suppress server output unless DEBUG is set
+    if (process.env.DEBUG) {
+        server.stdout?.pipe(process.stdout);
+        server.stderr?.pipe(process.stderr);
+    }
+
+    return server;
+}
+
+async function waitForServer(url: string, timeoutMs: number): Promise<void> {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            const res = await fetch(url);
+            if (res.ok) return;
+        } catch {
+            // Server not ready yet
+        }
+        await sleep(500);
+    }
+    throw new Error(`Server did not start within ${timeoutMs}ms`);
+}
+
+/**
+ * Wait for all <img> elements to finish loading their full-resolution images.
+ * This prevents capturing blurhash placeholders instead of real photos.
+ */
+async function waitForImages(page: import('playwright').Page): Promise<void> {
+    await page.waitForTimeout(1000); // Initial settle
+
+    await page.evaluate((timeout) => {
+        return new Promise<void>((resolve) => {
+            const images = Array.from(document.querySelectorAll('img'));
+            let pending = images.filter((img) => !img.complete).length;
+
+            if (pending === 0) {
+                // All images already loaded, wait a bit for any CSS transitions
+                setTimeout(resolve, 500);
+                return;
+            }
+
+            const done = () => {
+                pending--;
+                if (pending <= 0) setTimeout(resolve, 500);
+            };
+
+            images.forEach((img) => {
+                if (!img.complete) {
+                    img.addEventListener('load', done);
+                    img.addEventListener('error', done);
+                }
+            });
+
+            // Safety timeout
+            setTimeout(resolve, timeout);
+        });
+    }, IMAGE_LOAD_TIMEOUT);
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ── Run ──────────────────────────────────────────────────────────
+main().catch((err) => {
+    console.error('❌ Screenshot generation failed:', err);
+    // Try to restore gallery.yaml on error
+    try {
+        const original = fs.readFileSync(GALLERY_YAML + '.bak', 'utf8');
+        fs.writeFileSync(GALLERY_YAML, original);
+    } catch {
+        // Backup may not exist
+    }
+    process.exit(1);
+});