fix(og): brandable static title + wider crawler UA coverage (#521)

@Rekoo-PS reported that gallery URLs sent via the WhatsApp Business
API render an unbranded "PicPeak - Photo Sharing Platform" preview
even though manual link sends from the WhatsApp app pick up the
per-event rich preview correctly. Two root causes, two fixes:

1. WhatsApp Business and 3rd-party preview services (Twilio,
   LinkPreview.net, etc.) don't always crawl with the recognisable
   "WhatsApp/X.Y.Z" UA we matched in nginx + galleryOgService.
   Extend the regex (both copies) to also catch WhatsAppBot, wa-bot,
   LinkPreview, and Slack-ImgProxy.

2. Even with broader UA coverage, some senders cache metadata with
   no UA at all and fetch the static SPA shell. That shell's
   <title> was hard-coded to "PicPeak - Photo Sharing Platform" —
   embarrassingly generic for any self-hosted brand. Switch to
   Vite's %VITE_DEFAULT_TITLE% / %VITE_DEFAULT_DESCRIPTION% HTML
   substitution so self-hosters can bake their brand into the
   fallback at build time. Defaults stay "PicPeak" so the upstream
   image doesn't change behaviour for anyone.

The per-event rich preview path (handleGalleryOgRequest, fired on
matched crawler UAs) is unchanged — this only improves the fallback
for unrecognised UAs and for the SPA-shell title that humans see in
their browser tab.

Adds a vite.config plugin to provide the defaults when env vars
aren't set, so unsubstituted "%VITE_..." literals never reach the
built HTML. Adds .env.example entries explaining the override.

Tests: extend galleryOgService.shareImage.test.js with an
isSocialCrawler suite that pins every documented UA (incl. the new
ones) plus three browser UAs (negative) and null/empty edge cases.
Verified locally: `vite build` with VITE_DEFAULT_TITLE="MyBrand"
produces <title>MyBrand</title> + og:title="MyBrand"; without the
env var falls back to "PicPeak".

Refs: #521

backend/src/__tests__/galleryOgService.shareImage.test.js

@@ -35,6 +35,7 @@ const { getStorage } = require('../services/storage');
 const {
   buildOgMetadata,
   handleGalleryOgCover,
+  isSocialCrawler,
 } = require('../services/galleryOgService');
 
 // The service hits two tables in sequence:
@@ -237,3 +238,52 @@ describe('handleGalleryOgCover — 404 unless explicitly opted in', () => {
     expect(ensureThumbnail).not.toHaveBeenCalled();
   });
 });
+
+// Regression for #521 — WhatsApp Business API + 3rd-party preview
+// services use UAs that aren't "WhatsApp/X.Y.Z". If isSocialCrawler
+// misses them, those requests fall through to the static SPA shell
+// and the link preview ends up unbranded.
+describe('isSocialCrawler — extended bot coverage (#521)', () => {
+  it('matches every UA the README/changelog claims to support', () => {
+    // Pin the contract: each listed UA must hit the crawler path so the
+    // nginx rewrite + backend OG handler stay in sync. Adding a new UA
+    // here without also adding it to nginx.conf would silently regress.
+    const knownBots = [
+      // Main WhatsApp app
+      'WhatsApp/2.23.20.0',
+      // WhatsApp Business / Cloud API variants
+      'WhatsAppBot/1.0',
+      'wa-bot/2.0',
+      // Other messaging app crawlers
+      'facebookexternalhit/1.1',
+      'Twitterbot/1.0',
+      'Slackbot-LinkExpanding 1.0',
+      'TelegramBot (like TwitterBot)',
+      // 3rd-party preview services used by business-messaging stacks
+      'LinkPreview/1.0',
+      'Slack-ImgProxy/1.0',
+    ];
+    for (const ua of knownBots) {
+      expect(isSocialCrawler(ua)).toBe(true);
+    }
+  });
+
+  it('does not match a regular browser UA', () => {
+    const browsers = [
+      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36',
+      'Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15',
+      // Browser UA that happens to contain "Mobile" — guard against an
+      // over-broad regex landing on it.
+      'Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 Chrome/120.0 Mobile Safari/537.36',
+    ];
+    for (const ua of browsers) {
+      expect(isSocialCrawler(ua)).toBe(false);
+    }
+  });
+
+  it('returns false for null/empty/undefined UAs', () => {
+    expect(isSocialCrawler(null)).toBe(false);
+    expect(isSocialCrawler(undefined)).toBe(false);
+    expect(isSocialCrawler('')).toBe(false);
+  });
+});

backend/src/services/galleryOgService.js

@@ -7,7 +7,12 @@ const SOCIAL_CRAWLER_PATTERNS = [
   /facebookexternalhit/i,
   /facebot/i,
   /Twitterbot/i,
+  // WhatsApp's main app crawler is "WhatsApp/X.Y.Z"; the Business
+  // API and some Cloud API senders use "WhatsAppBot" or "wa-bot/" —
+  // detect both so API-driven sends get the rich preview too (#521).
   /WhatsApp/i,
+  /WhatsAppBot/i,
+  /wa-bot/i,
   /Slackbot/i,
   /TelegramBot/i,
   /SkypeUriPreview/i,
@@ -24,7 +29,12 @@ const SOCIAL_CRAWLER_PATTERNS = [
   /Mastodon/i,
   /Bluesky/i,
   /OpenGraph/i,
-  /opengraph/i
+  /opengraph/i,
+  // Generic preview/scrape services commonly used in business
+  // messaging stacks (Twilio, LinkPreview.net, etc.). Match the
+  // canonical lowercase substring; the /i flag handles case.
+  /LinkPreview/i,
+  /Slack-ImgProxy/i
 ];
 
 function isSocialCrawler(userAgent) {

frontend/.env.example

@@ -1,3 +1,19 @@
+# Static HTML fallback for social-link previews (#521).
+#
+# Most link previews (WhatsApp, Facebook, Slack, etc.) hit the backend's
+# per-event OG endpoint and get the actual event name + branding. Some
+# third-party preview services and the WhatsApp Business API cache
+# metadata with a non-crawler User-Agent and end up reading these static
+# values instead. Set these to your brand so that fallback isn't generic
+# "PicPeak - Photo Sharing Platform".
+#
+# These are baked into index.html at build time, so they take effect on
+# the next `npm run build` / docker build. Live admin Branding settings
+# do NOT propagate here — for that, use the per-event OG endpoint, which
+# always serves the live branded preview.
+VITE_DEFAULT_TITLE=PicPeak
+VITE_DEFAULT_DESCRIPTION=Photo gallery shared with PicPeak.
+
 # Backend API URL
 # For local development with Docker:
 VITE_API_URL=http://localhost:3001/api

frontend/.env.production.example

@@ -1,6 +1,12 @@
 # Production Environment Configuration
 # When running behind a reverse proxy like Traefik, use relative URLs
 
+# Static HTML fallback for social-link previews (#521).
+# Override these with your brand so previews that hit the static
+# index.html (vs the per-event OG endpoint) aren't generic.
+VITE_DEFAULT_TITLE=PicPeak
+VITE_DEFAULT_DESCRIPTION=Photo gallery shared with PicPeak.
+
 # Backend API URL
 # For production behind reverse proxy, use relative URL:
 VITE_API_URL=/api

frontend/index.html

@@ -4,7 +4,33 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
-    <title>PicPeak - Photo Sharing Platform</title>
+    <!--
+      Static fallback title + Open Graph defaults (#521).
+
+      The runtime SPA updates these once React loads, and social-crawler
+      User-Agents hitting /gallery/<slug> get a per-event rich preview
+      served by backend's galleryOgService instead of this static shell.
+
+      But the third path — link previews fetched by WhatsApp Business
+      API, Twilio, LinkPreview, or any service that caches metadata
+      with a non-crawler UA — gets *this* HTML as-is. Defaulting the
+      title to "PicPeak - Photo Sharing Platform" left every such
+      preview looking unbranded for self-hosted installs.
+
+      Self-hosters set VITE_DEFAULT_TITLE / VITE_DEFAULT_DESCRIPTION
+      at build time (see .env.example) to bake their brand into this
+      fallback. Default values keep the upstream-image behaviour for
+      anyone who doesn't override them.
+    -->
+    <title>%VITE_DEFAULT_TITLE%</title>
+    <meta name="description" content="%VITE_DEFAULT_DESCRIPTION%" />
+    <meta property="og:type" content="website" />
+    <meta property="og:site_name" content="%VITE_DEFAULT_TITLE%" />
+    <meta property="og:title" content="%VITE_DEFAULT_TITLE%" />
+    <meta property="og:description" content="%VITE_DEFAULT_DESCRIPTION%" />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="%VITE_DEFAULT_TITLE%" />
+    <meta name="twitter:description" content="%VITE_DEFAULT_DESCRIPTION%" />
 
     <!-- Pre-React theme bootstrap (#358).
          The browser may paint the very first frame before our inline

frontend/nginx.conf

@@ -184,7 +184,11 @@ server {
     # meta tags never reach them. Route those UAs to backend's /og handler
     # via internal rewrite; humans fall through to the SPA via try_files.
     location ~ ^/gallery/(?<gallery_slug>[A-Za-z0-9_-]+)(?:/[^/]+)?/?$ {
-        if ($http_user_agent ~* "(facebookexternalhit|facebot|Twitterbot|WhatsApp|Slackbot|TelegramBot|SkypeUriPreview|Discordbot|LinkedInBot|Pinterest|vkShare|redditbot|Embedly|iframely|Snapchat|Applebot|Mastodon|Bluesky|OpenGraph)") {
+        # Keep this list in sync with SOCIAL_CRAWLER_PATTERNS in
+        # backend/src/services/galleryOgService.js. WhatsAppBot / wa-bot
+        # and LinkPreview / Slack-ImgProxy added in #521 to catch
+        # business-API preview fetchers that aren't the main WhatsApp app.
+        if ($http_user_agent ~* "(facebookexternalhit|facebot|Twitterbot|WhatsApp|WhatsAppBot|wa-bot|Slackbot|Slack-ImgProxy|TelegramBot|SkypeUriPreview|Discordbot|LinkedInBot|Pinterest|vkShare|redditbot|Embedly|iframely|Snapchat|Applebot|Mastodon|Bluesky|OpenGraph|LinkPreview)") {
             rewrite ^ /og/gallery/$gallery_slug last;
         }
         try_files $uri $uri/ /index.html;

frontend/vite.config.ts

@@ -1,13 +1,34 @@
 /// <reference types="vitest" />
 // @ts-nocheck
 
-import { defineConfig } from 'vite'
+import { defineConfig, loadEnv } from 'vite'
 import react from '@vitejs/plugin-react'
 import type { UserConfig as VitestUserConfig } from 'vitest/config'
 
+// Inject defaults for the %VITE_DEFAULT_TITLE% / %VITE_DEFAULT_DESCRIPTION%
+// placeholders in index.html when the env vars aren't set (#521). Without
+// this, Vite would leave the literal "%VITE_DEFAULT_TITLE%" string in the
+// built HTML, breaking the link-preview fallback we're trying to create.
+//
+// Self-hosters override by exporting the env vars at build time
+// (typical Docker build pattern: --build-arg VITE_DEFAULT_TITLE="My Brand").
+function htmlTitleDefaults(mode: string) {
+  const env = loadEnv(mode, process.cwd(), 'VITE_')
+  const title = env.VITE_DEFAULT_TITLE || 'PicPeak'
+  const description = env.VITE_DEFAULT_DESCRIPTION || 'Photo gallery shared with PicPeak.'
+  return {
+    name: 'html-title-defaults',
+    transformIndexHtml(html: string) {
+      return html
+        .replaceAll('%VITE_DEFAULT_TITLE%', title)
+        .replaceAll('%VITE_DEFAULT_DESCRIPTION%', description)
+    },
+  }
+}
+
 // https://vite.dev/config/
 const config: VitestUserConfig = {
-  plugins: [react()],
+  plugins: [react(), htmlTitleDefaults(process.env.NODE_ENV || 'production')],
   build: {
     rollupOptions: {
       output: {