feat(images): expose variant base URL + align next/image sizes (BE-4)

[Zheaoli]

BE-4 — variant delivery config

Part of the image-performance overhaul (parent task #1). This wires the responsive-variant delivery config, which (a) lets the merged FE-3 gallery loader activate, and (b) provides the storage resolution the preprocessing queue (BE-3) will use to upload variants.

What

• server/lib/variant-storage.ts — resolves the configured variant storage backend (variant_storage = s3 | r2; empty disables the pipeline):
  • getVariantBaseUrl() — public base URL for variants (no trailing slash, storage folder already included), derived from the backend's existing public-URL config (S3 cdn / endpoint / path-style, or R2 public domain). Returns '' when unconfigured.
  • resolveVariantStorage() — backend client + bucket + folder + base, for the BE-3 upload path.
  • Open List intentionally unsupported for variants (it returns a per-file URL via API with no predictable {key}_{w}.{fmt} pattern the client loader can rebuild) → those images keep the preview/blurhash fallback.
• getDisplayConfig / getAlbumDisplayConfig — fill GalleryDisplayConfig.variantBaseUrl (the field FE-3 added). Empty → the loader sleeps and falls back to preview/blurhash, so this is safe to merge before any backfill exists.
• next.config — imageSizes: [320,480] + deviceSizes: [640,800,1080,1280,1920,2560], aligned to the pipeline tier ladder so next/image only ever requests widths the pipeline generates.
• seed — add the variant_storage config key (default empty).

Contract (with FE-3, locked)

Loader builds {variantBaseUrl}/{image_key}_{w}.{fmt}; variantBaseUrl already includes the storage folder. Matches BE-2's buildVariantKey + tier ladder.

Notes / scope

• No behavior change until an admin sets variant_storage and BE-3 backfills variants — until then variantBaseUrl is '' and the gallery behaves as today (minus the removed 20MB-original fallback from FE-3).
• Follow-up (coordinated with @Picimpact-Design): extract the tier ladder + buildVariantKey into a client-safe module so FE-3's loader imports the same source instead of mirroring the constants.

Verification

• tsc --noEmit: no errors in changed files. eslint --fix: clean. Rebased on current main (incl. FE-3), so GalleryDisplayConfig.variantBaseUrl is the existing field — no type duplication.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
picimpact	Ready	Preview, Comment	May 30, 2026 11:41am