feat: photography features & image optimizations

- Hero carousel: gallery.yaml hero accepts single UUID or array, crossfade component
- Full-bleed single albums: subpages with 1 album skip grid, render photos directly
- EXIF on hover: camera/lens/focal length overlay on grid items (toggle via exifOnHover)
- Customizable grid: columns/gap/aspectRatio/layout (masonry|uniform) via gallery.yaml
- Per-subpage grid overrides: each subpage can override global grid config
- True masonry: per-image aspect ratios from EXIF dimensions
- next/image migration: homepage hero, album covers, grid thumbnails, about portrait
- ThumbHash blur placeholders and dominant color backgrounds
- Custom next/image loader via image proxy with width/quality params
- Lightbox fade-in transition with dominant color background
- Password-protected subpages, health check, rate limiting, OG images

app/api/auth/route.ts

@@ -0,0 +1,46 @@
+/**
+ * Auth API — validates album passwords and sets auth cookies.
+ * POST /api/auth { slug, password }
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { authenticate, isProtected } from '@/lib/auth';
+
+export async function POST(request: NextRequest) {
+    try {
+        const body = await request.json();
+        const { slug, password } = body;
+
+        if (!slug || !password) {
+            return NextResponse.json(
+                { error: 'Missing slug or password' },
+                { status: 400 },
+            );
+        }
+
+        if (!isProtected(slug)) {
+            return NextResponse.json(
+                { error: 'Album is not password-protected' },
+                { status: 400 },
+            );
+        }
+
+        const setCookie = authenticate(slug, password);
+        if (!setCookie) {
+            return NextResponse.json(
+                { error: 'Invalid password' },
+                { status: 401 },
+            );
+        }
+
+        return NextResponse.json(
+            { success: true },
+            { headers: { 'Set-Cookie': setCookie } },
+        );
+    } catch {
+        return NextResponse.json(
+            { error: 'Invalid request body' },
+            { status: 400 },
+        );
+    }
+}

app/api/health/route.ts

@@ -0,0 +1,26 @@
+/**
+ * Health check endpoint — reports app and Immich connectivity status.
+ * Used by Docker HEALTHCHECK, monitoring tools, and load balancers.
+ *
+ * GET /api/health → { status, immich, uptime }
+ */
+
+import { NextResponse } from 'next/server';
+import { immich } from '@/lib/immich';
+
+const startTime = Date.now();
+
+export async function GET() {
+    const immichOk = await immich.ping();
+
+    const body = {
+        status: immichOk ? 'ok' : 'degraded',
+        immich: immichOk ? 'connected' : 'unreachable',
+        uptime: Math.floor((Date.now() - startTime) / 1000),
+    };
+
+    return NextResponse.json(body, {
+        status: immichOk ? 200 : 503,
+        headers: { 'Cache-Control': 'no-store' },
+    });
+}

app/api/image/[id]/route.ts

@@ -3,19 +3,49 @@
  * without exposing the Immich server or API key.
  *
  * Usage: GET /api/image/:token?size=thumbnail|preview|original
+ *        GET /api/image/:token?w=640&q=75  (for next/image loader)
  * The :token is an encoded asset ID (not a raw UUID).
  */
 
 import { NextRequest, NextResponse } from 'next/server';
 import { immich, ImageSize } from '@/lib/immich';
 import { decodeAssetId } from '@/lib/tokens';
+import { getConfig } from '@/lib/config';
+import { checkRateLimit } from '@/lib/rate-limit';
 
 const VALID_SIZES: ImageSize[] = ['thumbnail', 'preview', 'original'];
 
+/**
+ * Map a requested pixel width to the best Immich size tier.
+ */
+function widthToSize(w: number): ImageSize {
+    if (w <= 250) return 'thumbnail';
+    if (w <= 1440) return 'preview';
+    return 'original';
+}
+
 export async function GET(
     request: NextRequest,
     { params }: { params: Promise<{ id: string }> },
 ) {
+    // ── Rate limiting ──────────────────────────────────
+    const ip = request.headers.get('x-forwarded-for')?.split(',')[0].trim() || 'unknown';
+    const { success, remaining, resetAt } = checkRateLimit(ip, getConfig().rateLimitRpm);
+
+    if (!success) {
+        const retryAfter = Math.ceil((resetAt - Date.now()) / 1000);
+        return NextResponse.json(
+            { error: 'Too many requests' },
+            {
+                status: 429,
+                headers: {
+                    'Retry-After': String(retryAfter),
+                    'X-RateLimit-Remaining': '0',
+                },
+            },
+        );
+    }
+
     const { id: token } = await params;
 
     // Decode the opaque token back to an Immich asset ID
@@ -24,11 +54,19 @@ export async function GET(
         return NextResponse.json({ error: 'Invalid token' }, { status: 400 });
     }
 
-    // Parse and validate size parameter
-    const sizeParam = request.nextUrl.searchParams.get('size') || 'preview';
-    const size: ImageSize = VALID_SIZES.includes(sizeParam as ImageSize)
-        ? (sizeParam as ImageSize)
-        : 'preview';
+    // Determine size: prefer explicit ?size=, then infer from ?w=
+    const sizeParam = request.nextUrl.searchParams.get('size');
+    const widthParam = request.nextUrl.searchParams.get('w');
+
+    let size: ImageSize = 'preview';
+    if (sizeParam && VALID_SIZES.includes(sizeParam as ImageSize)) {
+        size = sizeParam as ImageSize;
+    } else if (widthParam) {
+        const w = parseInt(widthParam, 10);
+        if (!isNaN(w) && w > 0) {
+            size = widthToSize(w);
+        }
+    }
 
     const result = await immich.streamAsset(assetId, size);
     if (!result) {
@@ -39,6 +77,7 @@ export async function GET(
         'Content-Type': result.contentType,
         // Images are immutable once uploaded to Immich — cache aggressively
         'Cache-Control': 'public, max-age=31536000, immutable',
+        'X-RateLimit-Remaining': String(remaining),
     };
 
     if (result.contentLength) {
@@ -47,3 +86,4 @@ export async function GET(
 
     return new NextResponse(result.stream, { headers });
 }
+

app/api/og/route.tsx

@@ -0,0 +1,93 @@
+/**
+ * Dynamic OG image generator — renders social share previews.
+ * Uses next/og (ImageResponse) to create 1200×630 cards.
+ *
+ * GET /api/og?title=Album+Name&subtitle=12+photos
+ */
+
+import { ImageResponse } from 'next/og';
+import { NextRequest } from 'next/server';
+
+export const runtime = 'edge';
+
+export async function GET(request: NextRequest) {
+    const { searchParams } = request.nextUrl;
+    const title = searchParams.get('title') || 'Gallery';
+    const subtitle = searchParams.get('subtitle') || '';
+
+    return new ImageResponse(
+        (
+            <div
+                style={{
+                    width: '100%',
+                    height: '100%',
+                    display: 'flex',
+                    flexDirection: 'column',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    backgroundColor: '#0a0a0a',
+                    fontFamily: 'system-ui, -apple-system, sans-serif',
+                    padding: '60px',
+                }}
+            >
+                {/* Decorative top line */}
+                <div
+                    style={{
+                        width: '60px',
+                        height: '2px',
+                        backgroundColor: '#d4af37',
+                        marginBottom: '40px',
+                    }}
+                />
+
+                {/* Title */}
+                <div
+                    style={{
+                        fontSize: '64px',
+                        fontWeight: 600,
+                        color: '#f0f0f0',
+                        letterSpacing: '0.02em',
+                        textAlign: 'center',
+                        lineHeight: 1.2,
+                        maxWidth: '900px',
+                    }}
+                >
+                    {title}
+                </div>
+
+                {/* Subtitle */}
+                {subtitle && (
+                    <div
+                        style={{
+                            fontSize: '24px',
+                            color: '#999999',
+                            fontWeight: 300,
+                            marginTop: '16px',
+                            letterSpacing: '0.08em',
+                            textTransform: 'lowercase',
+                        }}
+                    >
+                        {subtitle}
+                    </div>
+                )}
+
+                {/* Bottom decorative line */}
+                <div
+                    style={{
+                        width: '60px',
+                        height: '2px',
+                        backgroundColor: '#d4af37',
+                        marginTop: '40px',
+                    }}
+                />
+            </div>
+        ),
+        {
+            width: 1200,
+            height: 630,
+            headers: {
+                'Cache-Control': 'public, max-age=86400, s-maxage=86400',
+            },
+        },
+    );
+}