Per-diagnostic OG card rendering on Cloudflare Workers (#53)

rafavalls · claude · web-flow · commit 334fe94fb297 · 2026-05-12T12:13:08.000-03:00
Previously /og-default.png was bundled as a single static PNG because
Satori 0.26.x cannot run on Cloudflare Workers (yoga-layout instantiates
WASM from bytes, which Workers forbids). Crawlers thus saw the same
generic image for every share URL.

This change keeps the static default as a fallback but adds a real
per-diagnostic /og/{token}.png endpoint that runs on Workers. The trick
is dropping Satori entirely and hand-writing the SVG ourselves — then
using @resvg/resvg-wasm alone for SVG → PNG, which is fine on Workers
when handed a pre-compiled WebAssembly.Module via wrangler's CompiledWasm
rule.

Design (in api/lib/og-card.ts):
- Solid dark background, no gradients.
- Left column: site favicon (fetched from Google's favicon service),
  diagnostic title (auto-wraps to 2 lines if needed, ellipsised after),
  domain underneath.
- Right column: huge health-score number color-coded (green ≥80,
  yellow ≥50, red &lt;50, gray for N/A) + "HEALTH SCORE" label.
- Title cleaned of duplicate "(domain)" parentheticals since domain is
  shown separately below.

Behavior (api/app.ts):
- /og/{token}.png renders on first hit, caches in R2 fire-and-forget.
- R2 cache hit returns the PNG directly — same path the previous
  endpoint used.
- Any miss (bad token, share gone, render error) 302s to /og-default.png
  so crawlers always get a valid image.
- HEAD requests supported (Response with null body, same headers).
- Share-page &lt;head&gt; meta now points og:image at /og/{token}.png so
  Discord/WhatsApp/Facebook get the per-diagnostic card.

Verified locally against wrangler dev:
- /og/{real-token}.png returns a fresh per-token PNG (26720 bytes for
  the Centauro share, vs 81863 for the static default — different
  content confirms dynamic rendering).
- /og/{bad-token}.png returns 302 → /og-default.png.
- Share page meta tag now serializes as /og/{token}.png.

Co-authored-by: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/api/app.ts b/api/app.ts
@@ -9,10 +9,13 @@ import { resolveOrg } from "../src/auth/resolve-org.ts";
 import type { KVStore } from "../src/cache/interface.ts";
 import ogDefaultPngAsset from "./assets/og-default.png";
 import { renderLoginPage } from "./lib/login-page.ts";
+import { generateOgCard } from "./lib/og-card.ts";
 import {
 	getScreenshot,
 	loadDiagnostic,
+	loadOgImage,
 	loadPublicShare,
+	saveOgImage,
 } from "./lib/storage.ts";
 import { prompts } from "./prompts/index.ts";
 import { createDiagnoseAppResource } from "./resources/diagnose.ts";
@@ -384,7 +387,7 @@ export function createApp(config: AppConfig = {}) {
 						);
 				const canonicalUrl = `${url.origin}/d/${token}`;
 
-				const ogImageUrl = `${url.origin}/og-default.png`;
+				const ogImageUrl = `${url.origin}/og/${token}.png`;
 				const pageImageAlt = escapeAttr(
 					`Site Diagnostics report preview for ${diagDomain}`,
 				);
@@ -468,15 +471,74 @@ export function createApp(config: AppConfig = {}) {
 				);
 			}
 
-			// Legacy /og/{token}.png — point at the static card so any links
-			// that social-card scrapers cached before this change keep working.
+			// Per-diagnostic OG card: /og/{token}.png — rendered on first hit,
+			// cached in R2 for subsequent hits. On any miss (bad token, share
+			// gone, render failure) we 302 to /og-default.png so crawlers
+			// always get a valid image.
 			if (
 				url.pathname.startsWith("/og/") &&
 				(req.method === "GET" || req.method === "HEAD")
 			) {
-				return new Response(null, {
-					status: 302,
-					headers: { location: "/og-default.png" },
+				const m = url.pathname.match(/^\/og\/([A-Za-z0-9_-]{16,64})\.png$/);
+				if (!m) {
+					return new Response(null, {
+						status: 302,
+						headers: { location: "/og-default.png" },
+					});
+				}
+				const ogToken = m[1];
+
+				const cached = await loadOgImage(ogToken).catch(() => null);
+				if (cached) {
+					return new Response(cached, {
+						headers: {
+							"content-type": "image/png",
+							"cache-control": "public, max-age=31536000, immutable",
+						},
+					});
+				}
+
+				const ogShare = await loadPublicShare(ogToken).catch(() => null);
+				if (!ogShare) {
+					return new Response(null, {
+						status: 302,
+						headers: { location: "/og-default.png" },
+					});
+				}
+				const ogDiagnostic = await loadDiagnostic(
+					ogShare.diagnosticId,
+					ogShare.orgId,
+				).catch(() => null);
+				if (!ogDiagnostic) {
+					return new Response(null, {
+						status: 302,
+						headers: { location: "/og-default.png" },
+					});
+				}
+
+				let png: Uint8Array;
+				try {
+					png = await generateOgCard(ogDiagnostic);
+				} catch (err) {
+					console.error("[og-card] render failed:", err);
+					return new Response(null, {
+						status: 302,
+						headers: { location: "/og-default.png" },
+					});
+				}
+
+				// Fire-and-forget R2 write. If it fails the next request just
+				// regenerates — no correctness impact.
+				saveOgImage(ogToken, png).catch((err) => {
+					console.error("[og-card] cache write failed:", err);
+				});
+
+				return new Response(req.method === "HEAD" ? null : (png as BodyInit), {
+					headers: {
+						"content-type": "image/png",
+						"content-length": String(png.byteLength),
+						"cache-control": "public, max-age=31536000, immutable",
+					},
 				});
 			}
 
diff --git a/api/lib/og-card.ts b/api/lib/og-card.ts
@@ -0,0 +1,214 @@
+/**
+ * Per-diagnostic OG card. Runs on both Bun and Cloudflare Workers.
+ *
+ * Implementation detail: we hand-write the SVG instead of using Satori
+ * because Satori bundles yoga-layout (Emscripten WASM) which calls
+ * `WebAssembly.instantiate(bytes)` — Cloudflare Workers forbids that
+ * ("Wasm code generation disallowed by embedder"). resvg-wasm alone is
+ * fine when given a pre-compiled WebAssembly.Module (via wrangler's
+ * `[[rules]] CompiledWasm` rule for *.wasm imports), so SVG → PNG works.
+ */
+
+import { readFile } from "node:fs/promises";
+import { initWasm, Resvg } from "@resvg/resvg-wasm";
+import resvgWasmAsset from "@resvg/resvg-wasm/index_bg.wasm";
+import fontBoldAsset from "../assets/Lato-Bold.ttf";
+import fontRegularAsset from "../assets/Lato-Regular.ttf";
+import type { Diagnostic } from "../types/diagnostic.ts";
+
+type DataAsset = string | ArrayBuffer | Uint8Array | WebAssembly.Module;
+
+const WIDTH = 1200;
+const HEIGHT = 630;
+
+let initPromise: Promise<void> | null = null;
+let fontRegular: Uint8Array | null = null;
+let fontBold: Uint8Array | null = null;
+
+async function assetToUint8Array(
+	asset: DataAsset,
+	label: string,
+): Promise<Uint8Array> {
+	if (asset instanceof Uint8Array) return asset;
+	if (asset instanceof ArrayBuffer) return new Uint8Array(asset);
+	if (typeof asset === "string") {
+		const buf = await readFile(asset);
+		return new Uint8Array(buf);
+	}
+	throw new Error(`[${label}] unsupported asset shape`);
+}
+
+function init(): Promise<void> {
+	if (initPromise) return initPromise;
+	initPromise = (async () => {
+		try {
+			const [regular, bold] = await Promise.all([
+				assetToUint8Array(fontRegularAsset as DataAsset, "font-regular"),
+				assetToUint8Array(fontBoldAsset as DataAsset, "font-bold"),
+			]);
+			const wasmInput =
+				resvgWasmAsset instanceof WebAssembly.Module
+					? resvgWasmAsset
+					: await assetToUint8Array(resvgWasmAsset as DataAsset, "resvg-wasm");
+			await initWasm(wasmInput);
+			fontRegular = regular;
+			fontBold = bold;
+		} catch (err) {
+			initPromise = null;
+			throw err;
+		}
+	})();
+	return initPromise;
+}
+
+function getDomain(url: string): string {
+	try {
+		return new URL(url).hostname.replace(/^www\./, "");
+	} catch {
+		return url;
+	}
+}
+
+function scoreColor(score: number | null): string {
+	if (score == null) return "#71717a";
+	if (score >= 80) return "#22c55e";
+	if (score >= 50) return "#eab308";
+	return "#ef4444";
+}
+
+function xmlEscape(s: string): string {
+	return s
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+function uint8ToBase64(bytes: Uint8Array): string {
+	let s = "";
+	for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+	return btoa(s);
+}
+
+async function fetchFaviconDataUri(domain: string): Promise<string | null> {
+	try {
+		const res = await fetch(
+			`https://www.google.com/s2/favicons?domain=${domain}&sz=128`,
+			{ signal: AbortSignal.timeout(3000) },
+		);
+		if (!res.ok) return null;
+		const buf = await res.arrayBuffer();
+		const ct = res.headers.get("content-type") ?? "image/png";
+		return `data:${ct};base64,${uint8ToBase64(new Uint8Array(buf))}`;
+	} catch {
+		return null;
+	}
+}
+
+const TITLE_FONT_SIZE = 56;
+const TITLE_LINE_HEIGHT = 68;
+const TITLE_MAX_CHARS_PER_LINE = 22;
+const TITLE_MAX_LINES = 2;
+
+function truncate(text: string, maxLength: number): string {
+	const trimmed = text.replace(/\s+/g, " ").trim();
+	if (trimmed.length <= maxLength) return trimmed;
+	return `${trimmed.slice(0, maxLength - 1).trim()}…`;
+}
+
+// Greedy word-wrap. Returns up to TITLE_MAX_LINES lines, last one truncated
+// with ellipsis if the text exceeds the budget. SVG has no native wrapping —
+// we emit each line as its own <tspan>.
+function wrapTitle(text: string): string[] {
+	const words = text.replace(/\s+/g, " ").trim().split(" ");
+	const lines: string[] = [];
+	let current = "";
+	for (const word of words) {
+		const candidate = current ? `${current} ${word}` : word;
+		if (candidate.length > TITLE_MAX_CHARS_PER_LINE && current) {
+			lines.push(current);
+			current = word;
+		} else {
+			current = candidate;
+		}
+	}
+	if (current) lines.push(current);
+
+	if (lines.length > TITLE_MAX_LINES) {
+		const out = lines.slice(0, TITLE_MAX_LINES);
+		out[TITLE_MAX_LINES - 1] = truncate(
+			out[TITLE_MAX_LINES - 1],
+			TITLE_MAX_CHARS_PER_LINE,
+		);
+		return out;
+	}
+	return lines;
+}
+
+// Strip "(domain)" or "(www.domain)" from the title — we show the domain
+// separately on the URL line below, so it would otherwise be duplicated.
+function cleanTitle(rawTitle: string, domain: string): string {
+	const escaped = domain.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return rawTitle
+		.replace(new RegExp(`\\s*\\((?:www\\.)?${escaped}\\)\\s*`, "gi"), " ")
+		.trim();
+}
+
+function buildSvg(
+	title: string,
+	domain: string,
+	score: number | null,
+	faviconDataUri: string | null,
+): string {
+	const color = scoreColor(score);
+	const scoreDisplay = score != null ? String(score) : "N/A";
+	const titleLines = wrapTitle(title);
+	const safeDomain = xmlEscape(truncate(domain, 40));
+	const favicon = faviconDataUri
+		? `<image x="80" y="180" width="96" height="96" preserveAspectRatio="xMidYMid meet" href="${faviconDataUri}"/>`
+		: "";
+
+	// Layout: favicon top, title starts 32px below it, URL 40px below
+	// the final title line. Title is multi-line via <tspan>.
+	const titleFirstBaseline = 360;
+	const titleTspans = titleLines
+		.map(
+			(line, i) =>
+				`<tspan x="80" y="${
+					titleFirstBaseline + i * TITLE_LINE_HEIGHT
+				}">${xmlEscape(line)}</tspan>`,
+		)
+		.join("");
+	const urlY =
+		titleFirstBaseline + (titleLines.length - 1) * TITLE_LINE_HEIGHT + 44;
+
+	return `<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="${HEIGHT}">
+<rect width="${WIDTH}" height="${HEIGHT}" fill="#0a0a0a"/>
+${favicon}
+<text font-family="Lato" font-size="${TITLE_FONT_SIZE}" font-weight="700" fill="#fafafa">${titleTspans}</text>
+<text x="80" y="${urlY}" font-family="Lato" font-size="28" font-weight="400" fill="#a1a1aa">${safeDomain}</text>
+<text x="1120" y="380" font-family="Lato" font-size="200" font-weight="700" fill="${color}" text-anchor="end">${scoreDisplay}</text>
+<text x="1120" y="425" font-family="Lato" font-size="22" font-weight="400" fill="#a1a1aa" letter-spacing="4" text-anchor="end">HEALTH SCORE</text>
+</svg>`;
+}
+
+export async function generateOgCard(
+	diagnostic: Diagnostic,
+): Promise<Uint8Array> {
+	await init();
+	const domain = getDomain(diagnostic.url);
+	const title = cleanTitle(diagnostic.title || domain, domain);
+	const favicon = await fetchFaviconDataUri(domain);
+	const svg = buildSvg(title, domain, diagnostic.healthScore ?? null, favicon);
+	const resvg = new Resvg(svg, {
+		font: {
+			// biome-ignore lint/style/noNonNullAssertion: guaranteed by init()
+			fontBuffers: [fontRegular!, fontBold!],
+			loadSystemFonts: false,
+		},
+		fitTo: { mode: "width", value: WIDTH },
+		background: "#0a0a0a",
+	});
+	return resvg.render().asPng();
+}
diff --git a/api/lib/storage.ts b/api/lib/storage.ts
@@ -196,6 +196,50 @@ export async function loadPublicShare(
 	return share;
 }
 
+// ---------------------------------------------------------------------------
+// OG image cache (per-token, R2-backed)
+// ---------------------------------------------------------------------------
+// Per-diagnostic OG cards are rendered on first request and cached here so
+// subsequent crawler hits are O(1) and don't re-fetch the favicon or run
+// resvg again.
+
+export async function saveOgImage(
+	token: string,
+	png: Uint8Array,
+): Promise<void> {
+	await getClient().send(
+		new PutObjectCommand({
+			Bucket: getBucket(),
+			Key: `og-images/${token}.png`,
+			Body: png,
+			ContentType: "image/png",
+			CacheControl: "public, max-age=31536000, immutable",
+		}),
+	);
+}
+
+export async function loadOgImage(
+	token: string,
+): Promise<ReadableStream | null> {
+	try {
+		const res = await getClient().send(
+			new GetObjectCommand({
+				Bucket: getBucket(),
+				Key: `og-images/${token}.png`,
+			}),
+		);
+		return (res.Body?.transformToWebStream() as ReadableStream) ?? null;
+	} catch (err: unknown) {
+		if (
+			err instanceof Error &&
+			(err.name === "NoSuchKey" || err.name === "NotFound")
+		) {
+			return null;
+		}
+		throw err;
+	}
+}
+
 export async function deletePublicShare(token: string): Promise<void> {
 	await getClient().send(
 		new DeleteObjectCommand({
diff --git a/scripts/preview-og.ts b/scripts/preview-og.ts
