From 7573e48458dbf079085c52de441b6a0136f1080e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 1 Oct 2026 09:00:30 +0000
Subject: [PATCH] README badges: put your Codey stats on your GitHub profile

/b/<userId> (served by /api/og with kind=badge, no new function) returns
an SVG badge that keeps itself up to date: best code WPM, division, runs and
streak, with the player's own Kap. Two styles, a card and a shields-sized
flat pill, each in dark and light. It uses only shapes and system fonts,
since GitHub's image proxy blocks outside resources, and caches for half
an hour so the badge catches up as you practice.

Share profile now has a README badge section: a live preview, style and
theme pickers, and a snippet to copy (Markdown, or <picture> HTML that
follows the reader's GitHub theme).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018xNjY7412Rp5bFuw5h69yu
---
 api/_lib/badge.test.ts                |  33 +++++++
 api/_lib/badge.ts                     | 118 ++++++++++++++++++++++++++
 api/_lib/kap-look.ts                  |  14 ++-
 api/og/[id].ts                        |  16 +++-
 src/components/ProfileShareDialog.tsx |   3 +
 src/components/social/ReadmeBadge.tsx |  73 ++++++++++++++++
 src/lib/share-links.test.ts           |  15 ++++
 src/lib/share-links.ts                |  30 +++++++
 vercel.json                           |   1 +
 9 files changed, 297 insertions(+), 6 deletions(-)
 create mode 100644 api/_lib/badge.test.ts
 create mode 100644 api/_lib/badge.ts
 create mode 100644 src/components/social/ReadmeBadge.tsx

diff --git a/api/_lib/badge.test.ts b/api/_lib/badge.test.ts
new file mode 100644
index 0000000..ec8fb0b
--- /dev/null
+++ b/api/_lib/badge.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { renderBadge, textWidth } from './badge';
+import { FLAME_TIERS } from '../../src/utils/flame-tiers';
+import type { SharedProfile } from './profile-card';
+
+const profile = { userId: 'u', name: 'Nan <script>', username: 'nannndev', avatarUrl: null, runs: 212, bestWpm: 112.4, bestLanguage: 'C++ & Rust', avgWpm: 90, avgAccuracy: 97, bestStreak: 31, topLanguage: 'TypeScript', division: { name: 'Gold II', color: '#ffd700' }, trend: [], badges: { earned: 3, top: [] } } as SharedProfile;
+
+describe('README badges', () => {
+  it('draws the card with speed, division and Kap, escaping text', () => {
+    const svg = renderBadge({ profile, kap: { tier: FLAME_TIERS[2], look: { eyes: 'shades' } } });
+    expect(svg.startsWith('<svg xmlns="http://www.w3.org/2000/svg" width="440" height="120"')).toBe(true);
+    expect(svg).toContain('>112.4<');
+    expect(svg).toContain('Gold II');
+    expect(svg).toContain('best in C++ &amp; Rust · 212 runs · 31-day streak');
+    expect(svg).toContain('Nan &lt;script&gt; on Codey');
+    expect(svg).not.toContain('<script');
+    // Kap nested inline, so no outside requests.
+    expect(svg).toContain('<svg x="17" y="13"');
+    expect(svg).not.toMatch(/https?:\/\/(?!www\.w3\.org)/);
+  });
+
+  it('has a shields-sized flat style and a placeholder for new players', () => {
+    const flat = renderBadge({ profile, style: 'flat' });
+    expect(flat).toContain('height="20"');
+    expect(flat).toContain('112.4 WPM · Gold II');
+    expect(renderBadge({ profile: null })).toContain('Typing real code');
+    expect(renderBadge({ profile: null, style: 'flat' })).toContain('typing real code');
+  });
+
+  it('estimates wider text for longer strings', () => {
+    expect(textWidth('112.4 WPM · Platinum III', 11)).toBeGreaterThan(textWidth('98 WPM', 11));
+  });
+});
diff --git a/api/_lib/badge.ts b/api/_lib/badge.ts
new file mode 100644
index 0000000..532f871
--- /dev/null
+++ b/api/_lib/badge.ts
@@ -0,0 +1,118 @@
+import type { SharedProfile } from './profile-card.js';
+import { kapSvg, type KapLook } from '../../src/utils/kap-art.js';
+import type { FlameTier } from '../../src/utils/flame-tiers.js';
+import { formatWpm } from './og-image.js';
+
+/**
+ * README badges: /b/<userId> (or /api/og/<userId>?kind=badge) returns an SVG
+ * a developer can put on their GitHub profile. Two styles: `card` (default,
+ * with their Kap) and `flat` (a shields.io-sized pill). GitHub proxies README
+ * images through camo, which blocks outside fonts and scripts, so everything
+ * here is plain shapes and system fonts.
+ */
+
+export type BadgeStyle = 'card' | 'flat';
+export type BadgeTheme = 'dark' | 'light';
+
+export interface BadgeInput {
+  profile: SharedProfile | null;
+  kap?: { tier: FlameTier; look: KapLook } | null;
+  style?: BadgeStyle;
+  theme?: BadgeTheme;
+}
+
+const escape = (value: string) => value.replace(/[&<>"']/g, (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char]!);
+const SANS = "-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif";
+const AMBER = '#f59e0b';
+
+/** Rough text width for a sans-serif face; badges have no font metrics to measure with. */
+export function textWidth(text: string, size: number, bold = false): number {
+  let units = 0;
+  for (const char of text) {
+    if (/[0-9]/.test(char)) units += 0.56;
+    else if (/[ilI.,:;'|!]/.test(char)) units += 0.28;
+    else if (/[mwMW]/.test(char)) units += 0.84;
+    else if (/[A-Z]/.test(char)) units += 0.66;
+    else if (char === ' ') units += 0.28;
+    else units += 0.54;
+  }
+  return Math.ceil(units * size * (bold ? 1.06 : 1));
+}
+
+function division(profile: SharedProfile | null) {
+  return profile?.division ?? null;
+}
+
+function cardBadge({ profile, kap, theme = 'dark' }: BadgeInput): string {
+  const dark = theme === 'dark';
+  const bg = dark ? '#0f1117' : '#ffffff';
+  const ink = dark ? '#f4f4f5' : '#18181b';
+  const muted = dark ? '#a1a1aa' : '#71717a';
+  const border = dark ? '#27272a' : '#e4e4e7';
+  const width = 440;
+  const height = 120;
+  const div = division(profile);
+  const hasRuns = Boolean(profile?.runs);
+
+  const kapMarkup = kap ? kapSvg(kap.tier, kap.look, 86).replace('<svg ', '<svg x="17" y="13" ') : '';
+  const pillText = div?.name ?? 'Codey typist';
+  const pillColor = div?.color ?? AMBER;
+  // Pale division colours (Gold, Silver) need dark text on a light card.
+  const pillInk = dark ? pillColor : ink;
+  const pillWidth = textWidth(pillText, 11, true) + 22;
+
+  const wpm = hasRuns ? formatWpm(profile!.bestWpm) : '';
+  const wpmWidth = textWidth(wpm, 40, true);
+  const where = profile?.bestLanguage && profile.bestLanguage !== 'Mixed' ? profile.bestLanguage : 'code';
+  const runs = profile?.runs ?? 0;
+  const facts = [`best in ${where}`, `${runs.toLocaleString('en-US')} ${runs === 1 ? 'run' : 'runs'}`, profile?.bestStreak ? `${profile.bestStreak}-day streak` : ''].filter(Boolean).join(' · ');
+
+  const body = hasRuns
+    ? `<text x="128" y="78" font-family="${SANS}" font-size="40" font-weight="800" fill="${ink}">${escape(wpm)}</text>`
+      + `<text x="${132 + wpmWidth}" y="78" font-family="${SANS}" font-size="15" font-weight="600" fill="${muted}">wpm</text>`
+      + `<text x="128" y="101" font-family="${SANS}" font-size="12" fill="${muted}">${escape(facts)}</text>`
+    : `<text x="128" y="72" font-family="${SANS}" font-size="20" font-weight="800" fill="${ink}">Typing real code</text>`
+      + `<text x="128" y="96" font-family="${SANS}" font-size="12" fill="${muted}">First run coming soon on Codey</text>`;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-label="${escape(hasRuns ? `Codey: ${wpm} WPM best on code${div ? `, ${div.name}` : ''}` : 'Codey typing profile')}">`
+    + `<title>${escape(profile ? `${profile.name} on Codey` : 'Codey')}</title>`
+    + `<rect x="0.5" y="0.5" width="${width - 1}" height="${height - 1}" rx="16" fill="${bg}" stroke="${border}"/>`
+    + `<rect x="10" y="10" width="100" height="100" rx="14" fill="${AMBER}"/>`
+    + (kapMarkup || `<text x="60" y="72" text-anchor="middle" font-family="${SANS}" font-size="34" font-weight="800" fill="#18181b">&lt;/&gt;</text>`)
+    + `<text x="128" y="32" font-family="${SANS}" font-size="11" font-weight="800" letter-spacing="2" fill="${AMBER}">CODEY</text>`
+    + `<rect x="${width - 14 - pillWidth}" y="17" width="${pillWidth}" height="22" rx="11" fill="${dark ? 'none' : `${pillColor}33`}" stroke="${pillColor}" stroke-width="1.5"/>`
+    + `<text x="${width - 14 - pillWidth / 2}" y="32" text-anchor="middle" font-family="${SANS}" font-size="11" font-weight="700" fill="${pillInk}">${escape(pillText)}</text>`
+    + body
+    + `</svg>`;
+}
+
+function flatBadge({ profile, theme = 'dark' }: BadgeInput): string {
+  const div = division(profile);
+  const label = 'Codey';
+  const value = profile?.runs ? `${formatWpm(profile.bestWpm)} WPM${div ? ` · ${div.name}` : ''}` : 'typing real code';
+  const font = "Verdana,Geneva,'DejaVu Sans',sans-serif";
+  // Verdana runs about a fifth wider than the generic estimate, more in bold.
+  const left = Math.ceil(textWidth(label, 11) * 1.18) + 28;
+  const right = Math.ceil(textWidth(value, 11, true) * 1.24) + 14;
+  const width = left + right;
+  const color = div?.color ?? AMBER;
+  const labelBg = theme === 'light' ? '#e4e4e7' : '#3f3f46';
+  const labelInk = theme === 'light' ? '#18181b' : '#ffffff';
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="20" viewBox="0 0 ${width} 20" role="img" aria-label="${escape(`${label}: ${value}`)}">`
+    + `<title>${escape(`${label}: ${value}`)}</title>`
+    + `<clipPath id="r"><rect width="${width}" height="20" rx="4"/></clipPath>`
+    + `<g clip-path="url(#r)"><rect width="${left}" height="20" fill="${labelBg}"/><rect x="${left}" width="${right}" height="20" fill="${color}"/></g>`
+    // A tiny keycap glyph.
+    + `<rect x="6" y="5" width="11" height="10" rx="2.5" fill="${AMBER}"/><rect x="8" y="6.5" width="7" height="5" rx="1.5" fill="#fde68a"/>`
+    + `<g font-family="${font}" font-size="11">`
+    + `<text x="${left / 2 + 7}" y="14" text-anchor="middle" fill="${labelInk}">${label}</text>`
+    + `<text x="${left + right / 2}" y="14" text-anchor="middle" fill="#18181b" font-weight="bold">${escape(value)}</text>`
+    + `</g></svg>`;
+}
+
+export function renderBadge(input: BadgeInput): string {
+  return input.style === 'flat' ? flatBadge(input) : cardBadge(input);
+}
+
+export const badgeStyle = (value: string): BadgeStyle => (value === 'flat' ? 'flat' : 'card');
+export const badgeTheme = (value: string): BadgeTheme => (value === 'light' ? 'light' : 'dark');
diff --git a/api/_lib/kap-look.ts b/api/_lib/kap-look.ts
index e2bab3e..7ff3872 100644
--- a/api/_lib/kap-look.ts
+++ b/api/_lib/kap-look.ts
@@ -1,6 +1,6 @@
 import { Client, Users } from 'node-appwrite';
 import { APPWRITE } from './appwrite-admin.js';
-import { FLAME_TIERS, tierFor } from '../../src/utils/flame-tiers.js';
+import { FLAME_TIERS, tierFor, type FlameTier } from '../../src/utils/flame-tiers.js';
 import { kapDataUri, sanitizeLook, type KapLook } from '../../src/utils/kap-art.js';
 
 /**
@@ -23,13 +23,19 @@ async function readPrefs(userId: string): Promise<Prefs> {
   return (await new Users(client).getPrefs({ userId })) as Prefs;
 }
 
-/** A data URI of the player's Kap; the plain Kap when the look cannot be read. */
-export async function playerKap(userId: string, streakDays = 7, width = 200, read: (id: string) => Promise<Prefs> = readPrefs): Promise<string> {
+/** The player's Kap: their flame by streak and their Wardrobe look (plain when it cannot be read). */
+export async function playerLook(userId: string, streakDays = 7, read: (id: string) => Promise<Prefs> = readPrefs): Promise<{ tier: FlameTier; look: KapLook }> {
   let look: KapLook = {};
   try {
     if (userId) look = lookFromPrefs(await read(userId));
   } catch {
     // The card still draws, with Kap in his usual amber.
   }
-  return kapDataUri(tierFor(streakDays) ?? FLAME_TIERS[1], look, width);
+  return { tier: tierFor(streakDays) ?? FLAME_TIERS[1], look };
+}
+
+/** A data URI of the player's Kap. */
+export async function playerKap(userId: string, streakDays = 7, width = 200, read: (id: string) => Promise<Prefs> = readPrefs): Promise<string> {
+  const { tier, look } = await playerLook(userId, streakDays, read);
+  return kapDataUri(tier, look, width);
 }
diff --git a/api/og/[id].ts b/api/og/[id].ts
index 3e2820d..ca2d570 100644
--- a/api/og/[id].ts
+++ b/api/og/[id].ts
@@ -3,12 +3,13 @@ import { loadSharedRun } from '../_lib/share-card.js';
 import { renderChallengeImage, renderProfileImage, renderShareImage } from '../_lib/og-image.js';
 import { loadChallenge } from '../_lib/challenge-card.js';
 import { loadSharedProfile } from '../_lib/profile-card.js';
-import { playerKap } from '../_lib/kap-look.js';
+import { playerKap, playerLook } from '../_lib/kap-look.js';
+import { badgeStyle, badgeTheme, renderBadge } from '../_lib/badge.js';
 
 interface BinaryResponse {
   status: (code: number) => BinaryResponse;
   setHeader: (name: string, value: string) => void;
-  end: (body: Buffer) => void;
+  end: (body: Buffer | string) => void;
 }
 
 const first = (value: string | string[] | undefined) => (Array.isArray(value) ? value[0] : value) ?? '';
@@ -17,6 +18,7 @@ const first = (value: string | string[] | undefined) => (Array.isArray(value) ?
  * GET /api/og/<runId>: the PNG preview for a shared run; runs never change, so it caches hard.
  * GET /api/og/<userId>?kind=profile: a player's card, cached briefly since it moves with each run.
  * GET /api/og/<challengeId>?kind=challenge: the score to beat and the snippet.
+ * GET /api/og/<userId>?kind=badge&style=card|flat&theme=dark|light: an SVG README badge (also /b/<userId>).
  */
 export default async function handler(req: ApiRequest, res: BinaryResponse) {
   const id = first(req.query.id).replace(/\.png$/, '');
@@ -31,6 +33,16 @@ export default async function handler(req: ApiRequest, res: BinaryResponse) {
     res.status(200).end(body);
     return;
   }
+  if (first(req.query.kind) === 'badge') {
+    const profile = isConfigured() ? await loadSharedProfile(id.replace(/\.svg$/, '')) : null;
+    const style = badgeStyle(first(req.query.style));
+    const kap = profile && style === 'card' ? await playerLook(profile.userId, profile.bestStreak) : null;
+    res.setHeader('Content-Type', 'image/svg+xml; charset=utf-8');
+    // GitHub's image proxy honours this, so a badge catches up within the hour.
+    res.setHeader('Cache-Control', 'public, max-age=1800, s-maxage=1800, stale-while-revalidate=86400');
+    res.status(200).end(renderBadge({ profile, kap, style, theme: badgeTheme(first(req.query.theme)) }));
+    return;
+  }
   if (first(req.query.kind) === 'profile') {
     const profile = isConfigured() ? await loadSharedProfile(id) : null;
     const image = profile ? renderProfileImage(profile, host, await playerKap(profile.userId, profile.bestStreak)) : renderShareImage(null, host);
diff --git a/src/components/ProfileShareDialog.tsx b/src/components/ProfileShareDialog.tsx
index 1438c72..dbfc121 100644
--- a/src/components/ProfileShareDialog.tsx
+++ b/src/components/ProfileShareDialog.tsx
@@ -1,4 +1,5 @@
 import { useEffect, useState } from "react";
+import { ReadmeBadge } from "@/components/social/ReadmeBadge";
 import { Check, Copy, Download, LoaderCircle, Share2, UserRound, X } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { SharePostPanel } from "@/components/SharePostPanel";
@@ -107,6 +108,8 @@ export function ProfileShareDialog({ target, onClose }: ProfileShareDialogProps)
 
         <SharePostPanel text={text} url={url} hint="Anyone with the link sees the card as its preview. For Instagram stories, download the image and post it there." />
 
+        {target.own && <ReadmeBadge userId={target.userId} />}
+
         <div className="flex flex-col-reverse gap-2 p-4 sm:flex-row sm:items-center sm:justify-between">
           <Button type="button" variant="ghost" size="sm" onClick={copyCaption} className="text-xs text-muted-foreground hover:text-foreground">
             {copiedCaption ? <Check data-icon="inline-start" className="size-3.5 text-green-500" /> : <Copy data-icon="inline-start" className="size-3.5" />}
diff --git a/src/components/social/ReadmeBadge.tsx b/src/components/social/ReadmeBadge.tsx
new file mode 100644
index 0000000..b4d66fd
--- /dev/null
+++ b/src/components/social/ReadmeBadge.tsx
@@ -0,0 +1,73 @@
+import { useState } from "react";
+import { BadgeCheck, Check, Copy } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { badgeImageUrl, badgeSnippet, type BadgeStyle, type BadgeTheme } from "@/lib/share-links";
+import { cn } from "@/lib/utils";
+
+function Segmented<T extends string>({ value, options, onChange, label }: { value: T; options: [T, string][]; onChange: (value: T) => void; label: string }) {
+  return (
+    <div className="inline-flex rounded-lg border bg-background p-0.5" role="radiogroup" aria-label={label}>
+      {options.map(([id, text]) => (
+        <button
+          key={id}
+          type="button"
+          role="radio"
+          aria-checked={value === id}
+          onClick={() => onChange(id)}
+          className={cn("rounded-md px-2.5 py-1 text-[11px] font-semibold transition-colors cursor-pointer", value === id ? "bg-foreground text-background" : "text-muted-foreground hover:text-foreground")}
+        >
+          {text}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+/** "Put this on your GitHub profile": a live badge, its preview and the snippet to paste. */
+export function ReadmeBadge({ userId }: { userId: string }) {
+  const [style, setStyle] = useState<BadgeStyle>("card");
+  const [theme, setTheme] = useState<BadgeTheme>("auto");
+  const [copied, setCopied] = useState(false);
+  const origin = window.location.origin;
+  const snippet = badgeSnippet(origin, userId, style, theme);
+  const previews: ("dark" | "light")[] = theme === "auto" ? ["dark", "light"] : [theme];
+
+  return (
+    <section className="border-t px-4 py-4 sm:px-5" aria-labelledby="readme-badge-title">
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <div>
+          <h3 id="readme-badge-title" className="flex items-center gap-2 text-sm font-bold"><BadgeCheck className="size-4 text-amber-500" /> Badge for your GitHub README</h3>
+          <p className="text-[11px] text-muted-foreground">It updates on its own as you practice, and links back to your profile.</p>
+        </div>
+        <div className="flex flex-wrap gap-2">
+          <Segmented label="Badge style" value={style} onChange={setStyle} options={[["card", "Card"], ["flat", "Flat"]]} />
+          <Segmented label="Badge theme" value={theme} onChange={setTheme} options={[["auto", "Auto"], ["dark", "Dark"], ["light", "Light"]]} />
+        </div>
+      </div>
+      <div className="mt-3 flex flex-wrap items-center gap-3 rounded-xl border bg-muted/35 p-3">
+        {previews.map((tone) => (
+          <div key={tone} className={cn("rounded-lg p-2", tone === "dark" ? "bg-[#0d1117]" : "bg-white")}>
+            <img src={badgeImageUrl(origin, userId, style, tone)} alt={`Codey badge, ${tone} theme`} className={style === "card" ? "h-[100px] w-auto" : "h-5 w-auto"} loading="lazy" />
+          </div>
+        ))}
+      </div>
+      <div className="mt-3 flex flex-col gap-2 sm:flex-row sm:items-start">
+        <pre className="min-w-0 flex-1 overflow-x-auto rounded-lg border bg-background px-3 py-2 font-mono text-[11px] leading-relaxed text-muted-foreground">{snippet}</pre>
+        <Button
+          type="button"
+          variant="outline"
+          onClick={() => void navigator.clipboard.writeText(snippet).then(() => {
+            setCopied(true);
+            window.setTimeout(() => setCopied(false), 2000);
+          })}
+        >
+          {copied ? <Check data-icon="inline-start" className="text-green-500" /> : <Copy data-icon="inline-start" />}
+          {copied ? "Copied!" : theme === "auto" ? "Copy HTML" : "Copy Markdown"}
+        </Button>
+      </div>
+      <p className="mt-2 text-[11px] text-muted-foreground">
+        Paste it into the README of the repo named after your username (github.com/you/you) to show it on your profile.
+      </p>
+    </section>
+  );
+}
diff --git a/src/lib/share-links.test.ts b/src/lib/share-links.test.ts
index c4f8c0c..6292874 100644
--- a/src/lib/share-links.test.ts
+++ b/src/lib/share-links.test.ts
@@ -45,3 +45,18 @@ describe("profile share links", () => {
     expect(profileShareText({ name: "Ada", bestWpm: 0, runs: 0 }, false)).toContain("Ada is practicing");
   });
 });
+
+describe("README badge snippets", async () => {
+  const { badgeImageUrl, badgeSnippet } = await import("./share-links");
+  it("builds the badge URL with only non-default options", () => {
+    expect(badgeImageUrl("https://codey.app", "u1", "card", "dark")).toBe("https://codey.app/b/u1");
+    expect(badgeImageUrl("https://codey.app", "u1", "flat", "light")).toBe("https://codey.app/b/u1?style=flat&theme=light");
+  });
+
+  it("gives Markdown for a fixed theme and <picture> for auto", () => {
+    expect(badgeSnippet("https://codey.app", "u1", "card", "dark")).toBe("[![Codey typing stats](https://codey.app/b/u1)](https://codey.app/p/u1)");
+    const auto = badgeSnippet("https://codey.app", "u1", "flat", "auto");
+    expect(auto).toContain('<source media="(prefers-color-scheme: dark)" srcset="https://codey.app/b/u1?style=flat">');
+    expect(auto).toContain('src="https://codey.app/b/u1?style=flat&theme=light"');
+  });
+});
diff --git a/src/lib/share-links.ts b/src/lib/share-links.ts
index bfe736a..7f5c633 100644
--- a/src/lib/share-links.ts
+++ b/src/lib/share-links.ts
@@ -80,3 +80,33 @@ export function profileShareText(profile: { name: string; bestWpm: number; runs:
   const best = `${profile.bestWpm.toFixed(1)} WPM best over ${profile.runs} runs`;
   return own ? `My Codey profile: ${best}. Real code, real speed.` : `${profile.name} on Codey: ${best}.`;
 }
+
+export type BadgeStyle = "card" | "flat";
+export type BadgeTheme = "auto" | "dark" | "light";
+
+/** The README badge image: /b/<userId>, an SVG kept fresh by the server. */
+export function badgeImageUrl(origin: string, userId: string, style: BadgeStyle, theme: Exclude<BadgeTheme, "auto">) {
+  const params = new URLSearchParams();
+  if (style !== "card") params.set("style", style);
+  if (theme !== "dark") params.set("theme", theme);
+  const query = params.toString();
+  return `${origin}/b/${encodeURIComponent(userId)}${query ? `?${query}` : ""}`;
+}
+
+/**
+ * What to paste in a GitHub README. "auto" uses <picture>, which GitHub
+ * renders with the reader's light or dark theme.
+ */
+export function badgeSnippet(origin: string, userId: string, style: BadgeStyle, theme: BadgeTheme): string {
+  const link = profileShareUrl(origin, userId);
+  const alt = "Codey typing stats";
+  if (theme !== "auto") return `[![${alt}](${badgeImageUrl(origin, userId, style, theme)})](${link})`;
+  return [
+    `<a href="${link}">`,
+    "  <picture>",
+    `    <source media="(prefers-color-scheme: dark)" srcset="${badgeImageUrl(origin, userId, style, "dark")}">`,
+    `    <img alt="${alt}" src="${badgeImageUrl(origin, userId, style, "light")}">`,
+    "  </picture>",
+    "</a>",
+  ].join("\n");
+}
diff --git a/vercel.json b/vercel.json
index 81076fb..22774a5 100644
--- a/vercel.json
+++ b/vercel.json
@@ -12,6 +12,7 @@
     { "source": "/r/:id", "destination": "/api/share/:id" },
     { "source": "/p/:id", "destination": "/api/share/:id?kind=profile" },
     { "source": "/c/:id", "destination": "/api/share/:id?kind=challenge" },
+    { "source": "/b/:id", "destination": "/api/og/:id?kind=badge" },
     { "source": "/history", "destination": "/index.html" },
     { "source": "/statistics", "destination": "/index.html" },
     { "source": "/stats", "destination": "/index.html" },