feat: visual polish & UX — fade-in, theme toggle, scroll-to-top, footer, cursor, badge

- Add FadeIn component (IntersectionObserver scroll-reveal + load animation)
- Add dark/light theme toggle (useSyncExternalStore + localStorage)
- Add scroll-to-top button (appears after 300px scroll)
- Add configurable footer with social links (gallery.yaml)
- Add crosshair cursor on photo grid items
- Add 'X photos' count badge on subpage cover images
- Add light theme color palette in tokens.css

lib/__tests__/config.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from 'vitest';
+
+// Mock env.ts so importing config.ts doesn't trigger Zod validation
+vi.mock('@/lib/env', () => ({
+  env: {
+    IMMICH_API_URL: 'http://localhost:2283',
+    IMMICH_API_KEY: 'test-key',
+    SITE_TITLE: 'Test Gallery',
+    SITE_SUBTITLE: '',
+    CACHE_TTL: 300,
+    RATE_LIMIT_RPM: 120,
+  },
+}));
+
+import { slugify } from '@/lib/config';
+
+describe('slugify', () => {
+  it('converts a simple name to lowercase with hyphens', () => {
+    expect(slugify('Kloster Chorin')).toBe('kloster-chorin');
+  });
+
+  it('strips diacritics', () => {
+    expect(slugify('Schöne Aussicht')).toBe('schone-aussicht');
+    expect(slugify('Café Müller')).toBe('cafe-muller');
+  });
+
+  it('replaces special characters with hyphens', () => {
+    expect(slugify('Hello, World!')).toBe('hello-world');
+    expect(slugify('foo & bar (baz)')).toBe('foo-bar-baz');
+  });
+
+  it('trims leading and trailing hyphens', () => {
+    expect(slugify('--leading')).toBe('leading');
+    expect(slugify('trailing---')).toBe('trailing');
+    expect(slugify('---both---')).toBe('both');
+  });
+
+  it('collapses consecutive hyphens', () => {
+    expect(slugify('a   b   c')).toBe('a-b-c');
+  });
+
+  it('handles an empty string', () => {
+    expect(slugify('')).toBe('');
+  });
+
+  it('handles all-special-character input', () => {
+    expect(slugify('!@#$%')).toBe('');
+  });
+
+  it('preserves numbers', () => {
+    expect(slugify('Album 2024')).toBe('album-2024');
+  });
+});

lib/__tests__/thumbhash.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { thumbHashToBlurDataUrl, thumbHashToDominantHex } from '@/lib/thumbhash';
+
+// A real ThumbHash captured from an Immich asset (13 bytes, valid for the library)
+// This is a minimal valid ThumbHash that produces a tiny image.
+// Generate one via: thumbhash.rgbaToThumbHash(w, h, rgba)
+// For testing, we use a known-good base64 string that the library accepts.
+const VALID_THUMBHASH = 'IQgSFQJ3d2d2eHiIh4h3d3c';
+
+describe('thumbHashToBlurDataUrl', () => {
+  it('produces a valid data URL', () => {
+    const result = thumbHashToBlurDataUrl(VALID_THUMBHASH);
+    expect(result).toMatch(/^data:image\/png;base64,/);
+  });
+
+  it('produces a non-trivial string (has actual image data)', () => {
+    const result = thumbHashToBlurDataUrl(VALID_THUMBHASH);
+    expect(result.length).toBeGreaterThan(30);
+  });
+});
+
+describe('thumbHashToDominantHex', () => {
+  it('returns a valid hex color string', () => {
+    const result = thumbHashToDominantHex(VALID_THUMBHASH);
+    expect(result).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+});

lib/__tests__/tokens.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock the config module so tokens.ts can resolve getConfig().immich.apiKey
+vi.mock('@/lib/config', () => ({
+  getConfig: () => ({
+    immich: { apiKey: 'test-api-key-for-vitest-unit-tests' },
+  }),
+}));
+
+import { encodeAssetId, decodeAssetId } from '@/lib/tokens';
+
+const SAMPLE_UUID = '550e8400-e29b-41d4-a716-446655440000';
+
+describe('tokens', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('encodeAssetId', () => {
+    it('produces a non-empty base64url string', () => {
+      const token = encodeAssetId(SAMPLE_UUID);
+      expect(token).toBeTruthy();
+      expect(typeof token).toBe('string');
+      // base64url characters only
+      expect(token).toMatch(/^[A-Za-z0-9_-]+$/);
+    });
+
+    it('is deterministic — same input yields same token', () => {
+      const t1 = encodeAssetId(SAMPLE_UUID);
+      const t2 = encodeAssetId(SAMPLE_UUID);
+      expect(t1).toBe(t2);
+    });
+
+    it('produces different tokens for different UUIDs', () => {
+      const t1 = encodeAssetId(SAMPLE_UUID);
+      const t2 = encodeAssetId('12345678-aaaa-bbbb-cccc-123456789abc');
+      expect(t1).not.toBe(t2);
+    });
+  });
+
+  describe('decodeAssetId', () => {
+    it('round-trips a valid UUID', () => {
+      const token = encodeAssetId(SAMPLE_UUID);
+      const decoded = decodeAssetId(token);
+      expect(decoded).toBe(SAMPLE_UUID);
+    });
+
+    it('returns null for a garbage string', () => {
+      expect(decodeAssetId('not-a-valid-token')).toBeNull();
+    });
+
+    it('returns null for an empty string', () => {
+      expect(decodeAssetId('')).toBeNull();
+    });
+
+    it('returns null for a token that is too short', () => {
+      // less than 17 bytes when decoded
+      const short = Buffer.from('shortdata').toString('base64url');
+      expect(decodeAssetId(short)).toBeNull();
+    });
+  });
+});

lib/__tests__/urls.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, vi } from 'vitest';
+
+// Mock tokens so we get predictable URL output
+vi.mock('@/lib/tokens', () => ({
+  encodeAssetId: (id: string) => `ENCODED_${id}`,
+}));
+
+// Mock thumbhash helpers
+vi.mock('@/lib/thumbhash', () => ({
+  thumbHashToBlurDataUrl: () => 'data:image/png;base64,mockblur',
+  thumbHashToDominantHex: () => '#aabbcc',
+}));
+
+import {
+  imageUrl,
+  exifUrl,
+  assetPlaceholder,
+  assetExifSummary,
+  assetAspectRatio,
+} from '@/lib/urls';
+
+describe('imageUrl', () => {
+  it('generates a proxy URL with encoded token and default size', () => {
+    const url = imageUrl('some-uuid');
+    expect(url).toBe('/api/image/ENCODED_some-uuid?size=preview');
+  });
+
+  it('uses the specified size parameter', () => {
+    expect(imageUrl('id', 'thumbnail')).toBe('/api/image/ENCODED_id?size=thumbnail');
+    expect(imageUrl('id', 'original')).toBe('/api/image/ENCODED_id?size=original');
+  });
+});
+
+describe('exifUrl', () => {
+  it('generates an EXIF API URL with encoded token', () => {
+    expect(exifUrl('my-asset')).toBe('/api/exif/ENCODED_my-asset');
+  });
+});
+
+describe('assetPlaceholder', () => {
+  it('returns blur data and dominant color for an asset with thumbhash', () => {
+    const result = assetPlaceholder({ thumbhash: 'abc123' });
+    expect(result).toEqual({
+      blurDataURL: 'data:image/png;base64,mockblur',
+      dominantColor: '#aabbcc',
+    });
+  });
+
+  it('returns null when thumbhash is null', () => {
+    expect(assetPlaceholder({ thumbhash: null })).toBeNull();
+  });
+
+  it('returns null when thumbhash is empty string', () => {
+    expect(assetPlaceholder({ thumbhash: '' })).toBeNull();
+  });
+});
+
+describe('assetExifSummary', () => {
+  it('returns camera, lens, and focal length from exifInfo', () => {
+    const result = assetExifSummary({
+      exifInfo: {
+        make: 'Leica',
+        model: 'M11-P',
+        lensModel: 'Summilux-M 50mm',
+        focalLength: 50,
+        fNumber: null,
+        exposureTime: null,
+        iso: null,
+        exifImageWidth: null,
+        exifImageHeight: null,
+        city: null,
+        state: null,
+        country: null,
+        dateTimeOriginal: null,
+        description: null,
+      },
+    });
+    expect(result).toEqual({
+      camera: 'M11-P',
+      lens: 'Summilux-M 50mm',
+      focalLength: '50mm',
+    });
+  });
+
+  it('returns undefined when no exifInfo exists', () => {
+    expect(assetExifSummary({ exifInfo: undefined })).toBeUndefined();
+  });
+
+  it('returns undefined when all relevant fields are null', () => {
+    expect(
+      assetExifSummary({
+        exifInfo: {
+          make: null,
+          model: null,
+          lensModel: null,
+          focalLength: null,
+          fNumber: null,
+          exposureTime: null,
+          iso: null,
+          exifImageWidth: null,
+          exifImageHeight: null,
+          city: null,
+          state: null,
+          country: null,
+          dateTimeOriginal: null,
+          description: null,
+        },
+      }),
+    ).toBeUndefined();
+  });
+});
+
+describe('assetAspectRatio', () => {
+  it('computes width / height ratio', () => {
+    const result = assetAspectRatio({
+      exifInfo: {
+        make: null,
+        model: null,
+        lensModel: null,
+        focalLength: null,
+        fNumber: null,
+        exposureTime: null,
+        iso: null,
+        exifImageWidth: 3000,
+        exifImageHeight: 2000,
+        city: null,
+        state: null,
+        country: null,
+        dateTimeOriginal: null,
+        description: null,
+      },
+    });
+    expect(result).toBe(1.5);
+  });
+
+  it('returns undefined when dimensions are missing', () => {
+    expect(assetAspectRatio({ exifInfo: undefined })).toBeUndefined();
+  });
+
+  it('returns undefined when height is 0', () => {
+    expect(
+      assetAspectRatio({
+        exifInfo: {
+          make: null,
+          model: null,
+          lensModel: null,
+          focalLength: null,
+          fNumber: null,
+          exposureTime: null,
+          iso: null,
+          exifImageWidth: 100,
+          exifImageHeight: 0,
+          city: null,
+          state: null,
+          country: null,
+          dateTimeOriginal: null,
+          description: null,
+        },
+      }),
+    ).toBeUndefined();
+  });
+});