Use screenshots in social media cards

Author: stever

apps/gif-service/src/hasura.ts

@@ -105,6 +105,53 @@ export async function fetchProject(
     return data.project[0] ?? null;
 }
 
+export interface ProjectMeta {
+    projectId: string;
+    title: string;
+    updatedAt: string;
+}
+
+/** Public project meta from a /u/<userSlug>/<projectSlug> URL (public profile + public project). */
+export async function fetchProjectMetaBySlug(
+    userSlug: string,
+    projectSlug: string,
+): Promise<ProjectMeta | null> {
+    const query = `
+        query ($userSlug: String!, $projectSlug: String!) {
+            project(where: { slug: { _eq: $projectSlug }, owner: { slug: { _eq: $userSlug } } }, limit: 1) {
+                project_id
+                title
+                updated_at
+            }
+        }
+    `;
+    const data = await gql<{ project: Array<{ project_id: string; title: string; updated_at: string }> }>(
+        query,
+        { userSlug, projectSlug },
+    );
+    const p = data.project[0];
+    return p ? { projectId: p.project_id, title: p.title, updatedAt: p.updated_at } : null;
+}
+
+/** Public project meta by id (for /projects/<id> URLs). */
+export async function fetchProjectMetaById(id: string): Promise<ProjectMeta | null> {
+    const query = `
+        query ($id: uuid!) {
+            project(where: { project_id: { _eq: $id } }, limit: 1) {
+                project_id
+                title
+                updated_at
+            }
+        }
+    `;
+    const data = await gql<{ project: Array<{ project_id: string; title: string; updated_at: string }> }>(
+        query,
+        { id },
+    );
+    const p = data.project[0];
+    return p ? { projectId: p.project_id, title: p.title, updatedAt: p.updated_at } : null;
+}
+
 /**
  * Compile ZX BASIC (Boriel) or C (z88dk) through the Hasura actions, returning
  * the TAP bytes. A rejection here usually means the source did not compile, so

apps/gif-service/src/index.ts

@@ -4,6 +4,7 @@ import basicRoutes from './routes/basic.js';
 import projectRoutes from './routes/project.js';
 import sourceRoutes from './routes/source.js';
 import screenshotRoutes from './routes/screenshot.js';
+import ogRoutes from './routes/og.js';
 
 // Safety net: a single bad render must never take down the whole service. Log
 // and keep serving rather than letting an unhandled error exit the process
@@ -22,6 +23,9 @@ app.use('/api', projectRoutes);
 app.use('/api', sourceRoutes);
 // Public, read-only screenshots (only this path is exposed via the proxy).
 app.use('/screenshots', screenshotRoutes);
+// OpenGraph cards for /u/* and /projects/* — the proxy routes only social
+// crawlers here; real users get the SPA.
+app.use(ogRoutes);
 
 app.get('/health', (req, res) => {
     res.json({ status: 'ok' });

apps/gif-service/src/routes/og.ts

@@ -0,0 +1,110 @@
+import { Router, Request, Response } from 'express';
+import { fetchProjectMetaBySlug, fetchProjectMetaById, ProjectMeta } from '../hasura.js';
+
+// OpenGraph cards for shared project links. Caddy routes only social-crawler
+// requests for /u/* and /projects/* here; real users fall through to the SPA.
+// So we serve a small purpose-built page with the project's card metadata
+// (og:image -> the rendered screenshot) — crawlers parse the tags, they don't
+// run the app.
+const router = Router();
+
+const PUBLIC_ORIGIN = (process.env.PUBLIC_ORIGIN ?? 'https://code.zxplay.org').replace(/\/$/, '');
+const SLUG = /^[a-z0-9-]+$/i;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function esc(s: string): string {
+    return s
+        .replace(/&/g, '&')
+        .replace(/"/g, '"')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+
+const SITE_TITLE = 'Code · ZX Play';
+const SITE_DESC = 'A ZX Spectrum emulator & programming environment for the browser.';
+const SITE_IMAGE = `${PUBLIC_ORIGIN}/assets/images/embed-preview.png`;
+
+function ogPage(opts: { title: string; description: string; image: string; url: string }): string {
+    const title = esc(opts.title);
+    const description = esc(opts.description);
+    const image = esc(opts.image);
+    const url = esc(opts.url);
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>${title}</title>
+<meta property="og:type" content="website">
+<meta property="og:title" content="${title}">
+<meta property="og:description" content="${description}">
+<meta property="og:image" content="${image}">
+<meta property="og:url" content="${url}">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="${title}">
+<meta name="twitter:description" content="${description}">
+<meta name="twitter:image" content="${image}">
+</head>
+<body><p><a href="${esc(opts.url || PUBLIC_ORIGIN)}">View on ZX Play</a></p></body>
+</html>`;
+}
+
+function projectCard(meta: ProjectMeta, canonicalUrl: string): string {
+    const version = Date.parse(meta.updatedAt) || 0;
+    return ogPage({
+        title: `${meta.title} · ZX Play`,
+        description: `${meta.title} — a ZX Spectrum program on ZX Play.`,
+        image: `${PUBLIC_ORIGIN}/screenshots/${meta.projectId}.png?v=${version}`,
+        url: canonicalUrl,
+    });
+}
+
+const genericCard = (url: string): string =>
+    ogPage({ title: SITE_TITLE, description: SITE_DESC, image: SITE_IMAGE, url: url || PUBLIC_ORIGIN });
+
+async function send(res: Response, html: string): Promise<void> {
+    // Short cache: a crawler re-fetch picks up edits / new screenshots reasonably soon.
+    res.setHeader('Cache-Control', 'public, max-age=300');
+    res.type('html').send(html);
+}
+
+router.get('/u/:user/:project', async (req: Request, res: Response) => {
+    const user = (req.params.user || '').toLowerCase();
+    const project = (req.params.project || '').toLowerCase();
+    const canonical = `${PUBLIC_ORIGIN}/u/${req.params.user}/${req.params.project}`;
+    if (SLUG.test(user) && SLUG.test(project)) {
+        try {
+            const meta = await fetchProjectMetaBySlug(user, project);
+            if (meta) {
+                await send(res, projectCard(meta, canonical));
+                return;
+            }
+        } catch (err) {
+            console.error('OG slug lookup failed:', err);
+        }
+    }
+    await send(res, genericCard(canonical));
+});
+
+router.get('/projects/:id', async (req: Request, res: Response) => {
+    const id = (req.params.id || '').toLowerCase();
+    const canonical = `${PUBLIC_ORIGIN}/projects/${req.params.id}`;
+    if (UUID.test(id)) {
+        try {
+            const meta = await fetchProjectMetaById(id);
+            if (meta) {
+                await send(res, projectCard(meta, canonical));
+                return;
+            }
+        } catch (err) {
+            console.error('OG id lookup failed:', err);
+        }
+    }
+    await send(res, genericCard(canonical));
+});
+
+// Other crawler hits under these prefixes (profiles, lists) → generic site card.
+router.get(['/u', '/u/*', '/projects', '/projects/*'], async (_req: Request, res: Response) => {
+    await send(res, genericCard(''));
+});
+
+export default router;

apps/proxy/Caddyfile

@@ -39,6 +39,16 @@
 		reverse_proxy localhost:5001
 	}
 
+	# OpenGraph cards for shared project links: social crawlers only; browsers
+	# fall through to the SPA.
+	@ogcrawler {
+		path /u/* /projects/*
+		header_regexp User-Agent (?i)(Mastodon|gotosocial|Pleroma|Akkoma|Misskey|Twitterbot|facebookexternalhit|Facebot|Discordbot|Slackbot|TelegramBot|WhatsApp|bsky|LinkedInBot|redditbot|Iframely|Embedly|Synapse|SkypeUriPreview|vkShare|Google-PageRenderer)
+	}
+	handle @ogcrawler {
+		reverse_proxy localhost:5001
+	}
+
 	handle {
 		reverse_proxy localhost:8000
 	}

apps/proxy/prod.Caddyfile

@@ -35,6 +35,17 @@
         reverse_proxy gif-service:5001
     }
 
+    # OpenGraph cards for shared project links: only social-media crawlers
+    # fetching a project URL get the gif-service OG page (which points og:image
+    # at the screenshot). Real browsers fall through to the SPA below.
+    @ogcrawler {
+        path /u/* /projects/*
+        header_regexp User-Agent (?i)(Mastodon|gotosocial|Pleroma|Akkoma|Misskey|Twitterbot|facebookexternalhit|Facebot|Discordbot|Slackbot|TelegramBot|WhatsApp|bsky|LinkedInBot|redditbot|Iframely|Embedly|Synapse|SkypeUriPreview|vkShare|Google-PageRenderer)
+    }
+    handle @ogcrawler {
+        reverse_proxy gif-service:5001
+    }
+
     handle {
         # Strict Content Security Policy for production
         header {