@shiinasaku/github-card 4.1.0 → 5.0.0

package/src/card.ts

@@ -1,28 +1,17 @@
+import { parse, formatHex, formatHex8 } from "culori";
 import {
   resolveColors,
   kFormat,
   escapeXml,
   icon,
   wrapText,
+  measureText,
   FONT_FAMILY,
   resolveTw,
 } from "./utils/index";
-import type { UserProfile, UserStats, LanguageStat } from "./types";
-
-export type CardOpts = {
-  theme?: string;
-  title_color?: string;
-  text_color?: string;
-  icon_color?: string;
-  bg_color?: string;
-  border_color?: string;
-  hide_border?: boolean;
-  compact?: boolean;
-  hide?: string[];
-  hide_langs?: string[];
-  show_langs?: string[];
-  animate?: boolean;
-};
+import type { UserProfile, UserStats, LanguageStat, CardOptions } from "./types";
+
+export type CardOpts = CardOptions;
 
 const STAT_DEFS = [
   { key: "stars", iconName: "star" as const, label: "Stars" },
@@ -38,15 +27,46 @@ type LangVisual = {
   size: number;
 };
 
+/* ── tiny SVG builder ──────────────────────────────────────── */
+
+function el(
+  tag: string,
+  attrs: Record<string, string | number | undefined>,
+  children = "",
+): string {
+  let a = "";
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === undefined || v === null || v === "") continue;
+    a += ` ${k}="${escapeXml(String(v))}"`;
+  }
+  if (!children) return `<${tag}${a} />`;
+  return `<${tag}${a}>${children}</${tag}>`;
+}
+
 /* ── helpers ───────────────────────────────────────────────── */
 
 function raw(token: string): string {
-  const m = resolveTw(token, "fill").match(/fill="([^"]+)"/);
-  return m?.[1] ?? token;
+  const value = resolveTw(token, "fill").match(/fill="([^"]+)"/)?.[1] ?? token;
+  const color = parse(value);
+  return color
+    ? color.alpha === undefined || color.alpha === 1
+      ? formatHex(color)
+      : formatHex8(color)
+    : "#6b7280";
 }
 
-function clamp(s: string, n: number): string {
-  return s.length <= n ? s : s.slice(0, n - 1).trimEnd() + "\u2026";
+function fitText(text: string, width: number, size: number, weight = 400): string {
+  if (measureText(text, size, weight) <= width) return text;
+  const chars = Array.from(text);
+  while (chars.length && measureText(chars.join("") + "…", size, weight) > width) chars.pop();
+  return chars.join("").trimEnd() + "…";
+}
+
+// Stable output keeps ETags useful; the gallery supplies a distinct prefix per theme.
+function cardId(value: string): string {
+  let hash = 2166136261;
+  for (const char of value) hash = Math.imul(hash ^ char.codePointAt(0)!, 16777619);
+  return `card-${(hash >>> 0).toString(36)}`;
 }
 
 function buildLanguageSegments(
@@ -64,7 +84,6 @@ function buildLanguageSegments(
       tinySize += lang.size;
       continue;
     }
-
     visible.push(lang);
   }
 
@@ -72,7 +91,7 @@ function buildLanguageSegments(
     visible.push({ name: "Other", color: "#6b7280", size: tinySize });
   }
 
-  return visible.length > 0 ? visible : langs;
+  return visible;
 }
 
 /* ── renderer ──────────────────────────────────────────────── */
@@ -83,7 +102,9 @@ export function renderCard(
   langs: LanguageStat[],
   opts: CardOpts = {},
 ): string {
-  const hidden = new Set((opts.hide ?? []).map((k) => k.toLowerCase()));
+  const namespace = cardId(JSON.stringify([user, stats, langs, opts]));
+  const selector = `#${namespace}-root`;
+  const hidden = new Set((opts.hide ?? []).map((k) => k.trim().toLowerCase()));
   const c = resolveColors(opts);
   const compact = opts.compact ?? false;
   const animate = opts.animate ?? false;
@@ -97,531 +118,432 @@ export function renderCard(
   const iconColor = raw(c.icon);
   const borderColor = raw(c.border);
 
-  /* ── font (XML-safe) ──────────────────────────────────────── */
-  const fontFamily = FONT_FAMILY.replace(/"/g, "&apos;");
-
-  /* ── profile text setup ───────────────────────────────────── */
-  const displayName = user.name || user.login;
-  const nameEsc = escapeXml(clamp(displayName, 28));
-  const loginEsc = escapeXml(clamp(user.login, 24));
-  const pronouns = !compact && user.pronouns ? escapeXml(clamp(user.pronouns, 16)) : "";
+  /* ── profile text ─────────────────────────────────────────── */
+  const displayName = user.name?.trim() || user.login;
+  const pronouns = !compact && user.pronouns ? user.pronouns : "";
   const bioRaw = !compact && user.bio ? user.bio : "";
-  const bioLines = bioRaw ? wrapText(bioRaw, 44, 2) : [];
-  const twitter = !compact && user.twitter ? escapeXml(clamp(user.twitter, 22)) : "";
-  const avatar = (user.avatarUrl || "").replace(/&/g, "&amp;");
+  const twitterRaw = !compact && user.twitter ? user.twitter.replace(/^@/, "") : "";
+  const avatar = user.avatarUrl || "";
+  const metaRaw = `@${user.login}${pronouns ? ` · ${pronouns}` : ""}`;
 
   const visible = STAT_DEFS.filter((d) => !hidden.has(d.key));
   const activeLangsList = langs.filter((l) => {
+    if (!Number.isFinite(l.size) || l.size <= 0) return false;
     const name = l.name.toLowerCase().trim();
     if (showLangs.size > 0 && !showLangs.has(name)) return false;
     if (hideLangs.has(name)) return false;
     return true;
   });
 
-  /* ── dimensions (dynamic width) ───────────────────────────── */
-  const PX = 25; // horizontal padding
-  const PY = 25; // top padding
-  const avatarSize = 64;
+  /* ── dimensions (measured, dynamic width) ───────────────── */
+  const PX = 24; // horizontal padding
+  const PY = 22; // top padding
+  const avatarSize = 60;
   const avatarR = avatarSize / 2;
+  const textGap = 16;
 
-  // Estimate text width
-  const metaLen = user.login.length + (pronouns ? pronouns.length + 3 : 0);
-  const maxBioLen = bioLines.length ? Math.max(...bioLines.map((l) => l.length)) : 0;
-  const profileTextW = Math.max(
-    displayName.length * 11, // ~11px per bold char
-    metaLen * 7.5, // ~7.5px per medium char
-    maxBioLen * 6.5, // ~6.5px per small char
-    twitter.length * 7 + 20,
-  );
-
-  const profileW = PX + avatarSize + 16 + profileTextW + PX;
-  const statsW = visible.length > 0 ? visible.length * 85 + PX * 2 : 0;
-  const langsW = activeLangsList.length > 0 ? 300 : 0; // sensible minimum for languages
-
-  const W = Math.round(Math.min(540, Math.max(340, profileW, statsW, langsW)));
+  const nameW = measureText(displayName, 17, 700);
+  const metaW = measureText(metaRaw, 12.5, 500);
+  const profileW = PX + avatarSize + textGap + Math.max(nameW, metaW) + PX;
+  const statsW = visible.length > 0 ? visible.length * 84 + PX * 2 : 0;
+  const W = Math.round(Math.min(540, Math.max(340, profileW, statsW)));
   const contentW = W - PX * 2;
+  const profileTextW = contentW - avatarSize - textGap;
+  const nameEsc = escapeXml(fitText(displayName, profileTextW, 17, 700));
+  const metaStr = escapeXml(fitText(metaRaw, profileTextW, 12.5, 500));
+  const bioLines = wrapText(bioRaw, 44, 2).map((line) => fitText(line, profileTextW, 11.5));
+  const twitter = escapeXml(
+    fitText(twitterRaw ? `@${twitterRaw}` : "", profileTextW - 15, 11.5, 500),
+  );
 
-  /* ── profile section ──────────────────────────────────────── */
-  const infoX = PX + avatarSize + 14;
-  const nameY = PY + 22;
-  const loginY = nameY + 18;
-  const bioStartY = loginY + 16;
+  /* ── profile section ─────────────────────────────────────── */
+  const infoX = PX + avatarSize + textGap;
+  const nameY = PY + 20;
+  const loginY = nameY + 17;
+  const bioStartY = loginY + 15;
   const twitterY = bioStartY + bioLines.length * 14 + (bioLines.length ? 4 : 0);
 
-  let profileH = loginY + 10 - PY;
+  let profileH = loginY + 8 - PY;
   if (bioLines.length) profileH = bioStartY + bioLines.length * 14 - PY;
   if (twitter) profileH = twitterY + 10 - PY;
-  profileH = Math.max(profileH, avatarSize + 4);
+  profileH = Math.max(profileH, avatarSize + 6);
 
   /* ── stats section ────────────────────────────────────────── */
-  const statsY = PY + profileH + 14;
+  const statsY = PY + profileH + 16;
   const statW = visible.length > 0 ? contentW / visible.length : 0;
-  const statsH = visible.length > 0 ? 50 : 0;
+  const statsH = visible.length > 0 ? 58 : 0;
 
-  /* ── languages section ────────────────────────────────────── */
+  /* ── languages section ─────────────────────────────────── */
   const totalSize = activeLangsList.reduce((s, l) => s + l.size, 0) || 1;
   const sorted = [...activeLangsList].sort((a, b) => b.size - a.size);
-  const visualLangs = buildLanguageSegments(sorted, totalSize, contentW);
-  const barY = statsY + statsH + (statsH ? 16 : 12);
+  let visualLangs = buildLanguageSegments(sorted, totalSize, contentW);
+  // The legend and bar must describe the same groups and colors.
+  if (!compact && visualLangs.length > 6) {
+    const named = visualLangs.filter((lang) => lang.name !== "Other").slice(0, 5);
+    const otherSize = totalSize - named.reduce((sum, lang) => sum + lang.size, 0);
+    visualLangs = [...named, { name: "Other", color: "#6b7280", size: otherSize }];
+  }
+  const barY = statsY + statsH + (statsH ? 18 : 14);
   const barH = 10;
-
-  const maxLegend = compact ? 0 : 6;
-  const legendLangs = visualLangs.slice(0, maxLegend);
-  const otherSize = visualLangs.slice(maxLegend).reduce((s, l) => s + l.size, 0);
-
-  const legendY = barY + barH + 12;
-  const legendRowH = 16;
-  const legendCols = 3;
+  const legendY = barY + barH + 14;
+  const legendRowH = 17;
+  const legendCols = Math.min(3, Math.max(1, Math.floor(contentW / 150)));
   const legendColW = contentW / legendCols;
-  const legendItems: { name: string; color: string; pct: string }[] = legendLangs.map((l) => ({
-    name: clamp(l.name, 14),
-    color: l.color,
-    pct: ((l.size / totalSize) * 100).toFixed(1),
-  }));
-  if (otherSize > 0 && legendItems.length > 0) {
-    const existingOther = legendItems.find((item) => item.name === "Other");
-    if (existingOther) {
-      existingOther.pct = (
-        (((Number(existingOther.pct) / 100) * totalSize + otherSize) / totalSize) *
-        100
-      ).toFixed(1);
-    } else {
-      legendItems.push({
-        name: "Other",
-        color: "#6b7280",
-        pct: ((otherSize / totalSize) * 100).toFixed(1),
+  const legendItems = compact
+    ? []
+    : visualLangs.map((lang) => {
+        const pct = ((lang.size / totalSize) * 100).toFixed(1);
+        const suffixW = measureText(` ${pct}%`, 11, 500);
+        return {
+          name: fitText(lang.name, legendColW - 20 - suffixW, 11, 500),
+          color: raw(lang.color),
+          pct,
+        };
       });
-    }
-  }
   const legendRows = compact ? 0 : Math.ceil(legendItems.length / legendCols);
 
   const hasLangs = activeLangsList.length > 0;
-  const langSectionH = hasLangs ? barH + 12 + legendRows * legendRowH + 8 : 0;
+  const langSectionH = hasLangs ? barH + 14 + legendRows * legendRowH + 10 : 0;
 
-  /* ── final height ─────────────────────────────────────────── */
-  const H = barY + (hasLangs ? langSectionH : 0) + 12 + (hasLangs ? 0 : 4);
+  /* ── final height ────────────────────────────────────────── */
+  const H = barY + (hasLangs ? langSectionH : 0) + 14 + (hasLangs ? 0 : 6);
 
-  /* ── build SVG ────────────────────────────────────────────── */
+  /* ── accessibility ────────────────────────────────────────── */
   const parts: string[] = [];
-
-  // root
+  const svgAttrs: Record<string, string | number> = {
+    id: "root",
+    width: W,
+    height: H,
+    viewBox: `0 0 ${W} ${H}`,
+    fill: "none",
+    xmlns: "http://www.w3.org/2000/svg",
+    role: "img",
+    "aria-labelledby": "cardTitle cardDesc",
+  };
+  let svgOpen = "<svg";
+  for (const [k, v] of Object.entries(svgAttrs)) svgOpen += ` ${k}="${escapeXml(String(v))}"`;
+  parts.push(svgOpen + ">");
+  parts.push(el("title", { id: "cardTitle" }, `${escapeXml(displayName)}'s GitHub Stats`));
   parts.push(
-    '<svg width="' +
-      W +
-      '" height="' +
-      H +
-      '" viewBox="0 0 ' +
-      W +
-      " " +
-      H +
-      '" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="cardTitle cardDesc">',
+    el(
+      "desc",
+      { id: "cardDesc" },
+      escapeXml(
+        `GitHub profile card for ${displayName}. ${visible
+          .map(({ key, label }) => {
+            const value = stats[key];
+            return value === null ? `${label}: unavailable` : `${label}: ${kFormat(value)}`;
+          })
+          .join(", ")}. ${activeLangsList.length} highlighted languages.`,
+      ),
+    ),
   );
 
-  // accessibility
-  parts.push('<title id="cardTitle">' + escapeXml(displayName + "'s GitHub Stats") + "</title>");
-  parts.push(
-    '<desc id="cardDesc">GitHub profile card for ' +
-      escapeXml(displayName) +
-      " with " +
-      kFormat(stats.stars) +
-      " stars, " +
-      kFormat(stats.commits) +
-      " commits, and " +
-      activeLangsList.length +
-      " highlighted languages.</desc>",
+  /* ── styles ──────────────────────────────────────────────── */
+  const css: string[] = [];
+  css.push(
+    `${selector} { font-family: ${FONT_FAMILY}; text-rendering: geometricPrecision; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }`,
   );
-
-  // ── <style> block ──────────────────────────────────────────
-  const cssLines: string[] = [];
-  cssLines.push("* { font-family: " + fontFamily + "; }");
-  cssLines.push(".header { font-size: 18px; font-weight: 700; fill: " + titleColor + "; }");
-  cssLines.push(".stat { font-size: 14px; font-weight: 600; fill: " + textColor + "; }");
-  cssLines.push(".bold { font-weight: 700; }");
-  cssLines.push(".icon { fill: " + iconColor + "; }");
-  cssLines.push(".lang-name { font-size: 11px; fill: " + textColor + "; opacity: 0.8; }");
-  cssLines.push(".lang-progress { fill: " + textColor + "; opacity: 0.08; }");
-  cssLines.push(
-    ".meta { font-size: 12px; font-weight: 500; fill: " + textColor + "; opacity: 0.7; }",
+  css.push(
+    `${selector} .header { font-size: 17px; font-weight: 700; fill: ${titleColor}; letter-spacing: -0.015em; }`,
   );
-  cssLines.push(
-    ".bio { font-size: 11px; font-weight: 400; fill: " + textColor + "; opacity: 0.68; }",
+  css.push(`${selector} .lang-name { font-size: 11px; fill: ${textColor}; opacity: 0.82; }`);
+  css.push(`${selector} .lang-progress { fill: ${textColor}; opacity: 0.07; }`);
+  css.push(
+    `${selector} .meta { font-size: 12.5px; font-weight: 500; fill: ${textColor}; opacity: 0.72; }`,
   );
-  cssLines.push(
-    ".stat-label { font-size: 9px; font-weight: 600; fill: " +
-      textColor +
-      "; opacity: 0.5; letter-spacing: 0.08em; }",
+  css.push(
+    `${selector} .bio { font-size: 11.5px; font-weight: 400; fill: ${textColor}; opacity: 0.68; }`,
   );
-  cssLines.push(".stat-value { font-size: 15px; font-weight: 800; fill: " + textColor + "; }");
-  cssLines.push(
-    ".twitter-text { font-size: 11px; font-weight: 500; fill: " + textColor + "; opacity: 0.65; }",
+  css.push(
+    `${selector} .stat-label { font-size: 10px; font-weight: 700; fill: ${textColor}; opacity: 0.68; letter-spacing: 0.06em; }`,
+  );
+  css.push(
+    `${selector} .stat-value { font-size: 16px; font-weight: 700; fill: ${textColor}; letter-spacing: -0.015em; font-variant-numeric: tabular-nums; font-feature-settings: "tnum"; }`,
+  );
+  css.push(
+    `${selector} .twitter-text { font-size: 11.5px; font-weight: 500; fill: ${textColor}; opacity: 0.65; }`,
   );
 
   if (animate) {
-    cssLines.push("@keyframes fadeInAnimation { from { opacity: 0; } to { opacity: 1; } }");
-    cssLines.push(".stagger { opacity: 0; animation: fadeInAnimation 0.3s ease-in-out forwards; }");
+    css.push(`@keyframes ${namespace}-fade { from { opacity: 0; } to { opacity: 1; } }`);
+    css.push(
+      `${selector} .stagger { opacity: 0; animation: ${namespace}-fade 0.3s ease-in-out forwards; }`,
+    );
   }
 
-  parts.push("<style>" + cssLines.join(" ") + "</style>");
+  parts.push(el("style", {}, escapeXml(css.join(" "))));
 
-  // ── <defs> ─────────────────────────────────────────────────
-  parts.push("<defs>");
-  parts.push(
-    '<clipPath id="av"><circle cx="' +
-      (PX + avatarR) +
-      '" cy="' +
-      (PY + avatarR) +
-      '" r="' +
-      avatarR +
-      '"/></clipPath>',
-  );
-  parts.push(
-    '<radialGradient id="gl" cx="12%" cy="15%" r="65%">' +
-      '<stop offset="0%" stop-color="' +
-      iconColor +
-      '" stop-opacity="0.08"/>' +
-      '<stop offset="100%" stop-color="' +
-      iconColor +
-      '" stop-opacity="0"/>' +
-      "</radialGradient>",
-  );
+  /* ── defs ────────────────────────────────────────────────── */
   parts.push(
-    '<radialGradient id="gl2" cx="92%" cy="95%" r="55%">' +
-      '<stop offset="0%" stop-color="' +
-      titleColor +
-      '" stop-opacity="0.035"/>' +
-      '<stop offset="100%" stop-color="' +
-      titleColor +
-      '" stop-opacity="0"/>' +
-      "</radialGradient>",
+    el(
+      "defs",
+      {},
+      [
+        el(
+          "clipPath",
+          { id: "av" },
+          el("circle", { cx: PX + avatarR, cy: PY + avatarR, r: avatarR }),
+        ),
+        el(
+          "radialGradient",
+          { id: "gl", cx: "12%", cy: "15%", r: "65%" },
+          el("stop", { offset: "0%", "stop-color": iconColor, "stop-opacity": "0.08" }) +
+            el("stop", { offset: "100%", "stop-color": iconColor, "stop-opacity": "0" }),
+        ),
+        el(
+          "radialGradient",
+          { id: "gl2", cx: "92%", cy: "95%", r: "55%" },
+          el("stop", { offset: "0%", "stop-color": titleColor, "stop-opacity": "0.035" }) +
+            el("stop", { offset: "100%", "stop-color": titleColor, "stop-opacity": "0" }),
+        ),
+        el(
+          "linearGradient",
+          { id: "ring", x1: "0", y1: "0", x2: "1", y2: "1" },
+          el("stop", { offset: "0%", "stop-color": titleColor }) +
+            el("stop", { offset: "100%", "stop-color": iconColor }),
+        ),
+        el(
+          "linearGradient",
+          { id: "card-bg", x1: "0", y1: "0", x2: W, y2: H, gradientUnits: "userSpaceOnUse" },
+          el("stop", { offset: "0%", "stop-color": bgColor }) +
+            el("stop", { offset: "82%", "stop-color": bgColor }) +
+            el("stop", { offset: "100%", "stop-color": titleColor, "stop-opacity": "0.04" }),
+        ),
+        el(
+          "linearGradient",
+          { id: "rim", x1: "0", y1: "0", x2: W, y2: "0", gradientUnits: "userSpaceOnUse" },
+          el("stop", { offset: "0%", "stop-color": iconColor, "stop-opacity": "0" }) +
+            el("stop", { offset: "45%", "stop-color": iconColor, "stop-opacity": "0.28" }) +
+            el("stop", { offset: "100%", "stop-color": iconColor, "stop-opacity": "0" }),
+        ),
+      ].join(""),
+    ),
   );
-  parts.push(
-    '<linearGradient id="ring" x1="0" y1="0" x2="1" y2="1">' +
-      '<stop offset="0%" stop-color="' +
-      titleColor +
-      '"/>' +
-      '<stop offset="100%" stop-color="' +
-      iconColor +
-      '"/>' +
-      "</linearGradient>",
-  );
-  parts.push(
-    '<linearGradient id="card-bg" x1="0" y1="0" x2="' +
-      W +
-      '" y2="' +
-      H +
-      '" gradientUnits="userSpaceOnUse">' +
-      '<stop offset="0%" stop-color="' +
-      bgColor +
-      '"/>' +
-      '<stop offset="82%" stop-color="' +
-      bgColor +
-      '"/>' +
-      '<stop offset="100%" stop-color="' +
-      titleColor +
-      '" stop-opacity="0.04"/>' +
-      "</linearGradient>",
-  );
-  parts.push(
-    '<linearGradient id="rim" x1="0" y1="0" x2="' +
-      W +
-      '" y2="0" gradientUnits="userSpaceOnUse">' +
-      '<stop offset="0%" stop-color="' +
-      iconColor +
-      '" stop-opacity="0"/>' +
-      '<stop offset="45%" stop-color="' +
-      iconColor +
-      '" stop-opacity="0.28"/>' +
-      '<stop offset="100%" stop-color="' +
-      iconColor +
-      '" stop-opacity="0"/>' +
-      "</linearGradient>",
-  );
-  parts.push("</defs>");
 
-  // ── background rect (inset 0.5px for clean border) ─────────
+  /* ── background & glow ───────────────────────────────────── */
   parts.push(
-    '<rect x="0.5" y="0.5" width="' +
-      (W - 1) +
-      '" height="' +
-      (H - 1) +
-      '" rx="10" fill="' +
-      "url(#card-bg)" +
-      '" stroke-opacity="1"/>',
+    el("rect", { x: "0.5", y: "0.5", width: W - 1, height: H - 1, rx: 12, fill: "url(#card-bg)" }),
   );
-
-  // glow overlays (icon tint top-left, title tint bottom-right)
   parts.push(
-    '<rect x="0.5" y="0.5" width="' +
-      (W - 1) +
-      '" height="' +
-      (H - 1) +
-      '" rx="10" fill="url(#gl)"/>',
+    el("rect", { x: "0.5", y: "0.5", width: W - 1, height: H - 1, rx: 12, fill: "url(#gl)" }),
   );
   parts.push(
-    '<rect x="0.5" y="0.5" width="' +
-      (W - 1) +
-      '" height="' +
-      (H - 1) +
-      '" rx="10" fill="url(#gl2)"/>',
+    el("rect", { x: "0.5", y: "0.5", width: W - 1, height: H - 1, rx: 12, fill: "url(#gl2)" }),
   );
   parts.push(
-    '<line x1="' +
-      PX +
-      '" y1="1.5" x2="' +
-      (W - PX) +
-      '" y2="1.5" stroke="url(#rim)" stroke-width="1"/>',
+    el("line", {
+      x1: PX,
+      y1: "1.5",
+      x2: W - PX,
+      y2: "1.5",
+      stroke: "url(#rim)",
+      "stroke-width": 1,
+    }),
   );
 
-  // border
   if (!hideBorder) {
     parts.push(
-      '<rect x="0.5" y="0.5" width="' +
-        (W - 1) +
-        '" height="' +
-        (H - 1) +
-        '" rx="10" fill="none" stroke="' +
-        borderColor +
-        '" stroke-opacity="0.5"/>',
+      el("rect", {
+        x: "0.5",
+        y: "0.5",
+        width: W - 1,
+        height: H - 1,
+        rx: 12,
+        fill: "none",
+        stroke: borderColor,
+        "stroke-opacity": "0.5",
+      }),
     );
   }
 
-  // ── avatar ─────────────────────────────────────────────────
+  /* ── avatar ───────────────────────────────────────────────── */
   parts.push(
-    '<g transform="translate(0,0)">' +
-      '<circle cx="' +
-      (PX + avatarR + 1) +
-      '" cy="' +
-      (PY + avatarR + 1) +
-      '" r="' +
-      (avatarR + 3) +
-      '" fill="' +
-      titleColor +
-      '" opacity="0.08"/>' +
-      '<image href="' +
-      avatar +
-      '" x="' +
-      PX +
-      '" y="' +
-      PY +
-      '" width="' +
-      avatarSize +
-      '" height="' +
-      avatarSize +
-      '" clip-path="url(#av)" preserveAspectRatio="xMidYMid slice"/>' +
-      '<circle cx="' +
-      (PX + avatarR) +
-      '" cy="' +
-      (PY + avatarR) +
-      '" r="' +
-      (avatarR + 1.5) +
-      '" fill="none" stroke="url(#ring)" stroke-opacity="0.55" stroke-width="1.5"/>' +
-      "</g>",
+    el(
+      "g",
+      {},
+      el("circle", {
+        cx: PX + avatarR + 1,
+        cy: PY + avatarR + 1,
+        r: avatarR + 3,
+        fill: titleColor,
+        opacity: "0.08",
+      }) +
+        el("image", {
+          href: avatar,
+          x: PX,
+          y: PY,
+          width: avatarSize,
+          height: avatarSize,
+          "clip-path": "url(#av)",
+          preserveAspectRatio: "xMidYMid slice",
+        }) +
+        el("circle", {
+          cx: PX + avatarR,
+          cy: PY + avatarR,
+          r: avatarR + 1.5,
+          fill: "none",
+          stroke: "url(#ring)",
+          "stroke-opacity": "0.55",
+          "stroke-width": "1.5",
+        }),
+    ),
   );
 
-  // ── profile text ───────────────────────────────────────────
-  parts.push('<g transform="translate(0,0)">');
-
-  // name
-  parts.push('<text x="' + infoX + '" y="' + nameY + '" class="header">' + nameEsc + "</text>");
-
-  // username + pronouns
-  const metaStr = pronouns ? "@" + loginEsc + " \u00b7 " + pronouns : "@" + loginEsc;
-  parts.push('<text x="' + infoX + '" y="' + loginY + '" class="meta">' + metaStr + "</text>");
-
-  // bio
+  /* ── profile text ─────────────────────────────────────────── */
+  const textParts: string[] = [];
+  textParts.push(el("text", { x: infoX, y: nameY, class: "header" }, nameEsc));
+  textParts.push(el("text", { x: infoX, y: loginY, class: "meta" }, metaStr));
   for (let i = 0; i < bioLines.length; i++) {
-    parts.push(
-      '<text x="' +
-        infoX +
-        '" y="' +
-        (bioStartY + i * 14) +
-        '" class="bio">' +
-        escapeXml(bioLines[i]!.trim()) +
-        "</text>",
+    textParts.push(
+      el("text", { x: infoX, y: bioStartY + i * 14, class: "bio" }, escapeXml(bioLines[i]!.trim())),
     );
   }
-
-  // twitter
   if (twitter) {
-    parts.push(
-      '<g transform="translate(' +
-        infoX +
-        "," +
-        (twitterY - 9) +
-        ')">' +
-        icon("x", textColor, 11) +
-        '<text x="15" y="9" class="twitter-text">@' +
-        twitter +
-        "</text></g>",
+    textParts.push(
+      el(
+        "g",
+        { transform: `translate(${infoX},${twitterY - 9})` },
+        icon("x", textColor, 11) + el("text", { x: 15, y: 9, class: "twitter-text" }, twitter),
+      ),
     );
   }
+  parts.push(el("g", {}, textParts.join("")));
 
-  parts.push("</g>");
-
-  // ── stats row ──────────────────────────────────────────────
+  /* ── stats row ───────────────────────────────────────────── */
   if (visible.length > 0) {
-    parts.push(
-      '<rect x="' +
-        PX +
-        '" y="' +
-        (statsY - 8) +
-        '" width="' +
-        contentW +
-        '" height="' +
-        (statsH + 8) +
-        '" rx="8" fill="' +
-        textColor +
-        '" opacity="0.035"/>',
-    );
-
-    parts.push('<g transform="translate(0,0)">');
+    const statParts: string[] = [];
 
     for (let i = 0; i < visible.length; i++) {
       const d = visible[i]!;
-      const val = stats[d.key as keyof UserStats];
+      const val = stats[d.key];
       const cx = PX + statW * i + statW / 2;
-      const cellX = PX + statW * i + 4;
-      const iy = statsY + 2;
-
-      const staggerStyle = animate ? ' style="animation-delay: ' + (i + 3) * 150 + 'ms"' : "";
-      const staggerClass = animate ? " stagger" : "";
-
-      parts.push(
-        '<rect x="' +
-          cellX +
-          '" y="' +
-          (statsY - 4) +
-          '" width="' +
-          Math.max(0, statW - 8) +
-          '" height="' +
-          (statsH - 2) +
-          '" rx="8" fill="' +
-          textColor +
-          '" opacity="0.028"/>',
+      const iy = statsY + 4;
+
+      // Vertical stack: icon → value → label, all centered, with airy gaps.
+      const iconSize = 15;
+      const iconY = 2;
+      const valueY = 37;
+      const labelY = 52;
+
+      const cellParts: string[] = [
+        el(
+          "title",
+          {},
+          val === null ? `${d.label}: unavailable` : `${d.label}: ${val.toLocaleString("en-US")}`,
+        ),
+      ];
+      cellParts.push(
+        el(
+          "g",
+          { transform: `translate(${-iconSize / 2},${iconY})` },
+          icon(d.iconName, iconColor, iconSize),
+        ),
       );
-
-      // each stat wrapped in its own <g>
-      parts.push(
-        '<g transform="translate(' +
-          cx +
-          "," +
-          iy +
-          ')" class="stat' +
-          staggerClass +
-          '"' +
-          staggerStyle +
-          ">",
+      cellParts.push(
+        el(
+          "text",
+          { x: 0, y: valueY, class: "stat-value", "text-anchor": "middle" },
+          val === null ? "—" : kFormat(val),
+        ),
       );
-
-      // value
-      parts.push(
-        '<text x="0" y="26" class="stat-value" text-anchor="middle">' + kFormat(val) + "</text>",
+      cellParts.push(
+        el(
+          "text",
+          { x: 0, y: labelY, class: "stat-label", "text-anchor": "middle" },
+          d.label.toUpperCase(),
+        ),
       );
 
-      // label with tiny inline icon, centered as a unit
-      const labelText = d.label.toUpperCase();
-      const labelW = labelText.length * 6.8;
-      const rowW = 10 + 4 + labelW;
-      parts.push(
-        '<g transform="translate(' +
-          -rowW / 2 +
-          ',31.5)">' +
-          icon(d.iconName, iconColor, 10) +
-          "</g>",
-      );
-      parts.push(
-        '<text x="' + (-rowW / 2 + 14) + '" y="40" class="stat-label">' + labelText + "</text>",
+      statParts.push(
+        el(
+          "g",
+          {
+            transform: `translate(${cx},${iy})`,
+            class: animate ? "stagger" : undefined,
+            style: animate ? `animation-delay: ${(i + 3) * 150}ms` : undefined,
+          },
+          cellParts.join(""),
+        ),
       );
 
-      parts.push("</g>");
+      // Subtle divider between stats (not after the last one).
+      if (i < visible.length - 1) {
+        const dx = PX + statW * (i + 1);
+        statParts.push(
+          el("line", {
+            x1: dx,
+            y1: statsY + 4,
+            x2: dx,
+            y2: statsY + statsH - 6,
+            stroke: textColor,
+            "stroke-opacity": "0.12",
+          }),
+        );
+      }
     }
-
-    parts.push("</g>");
+    parts.push(el("g", {}, statParts.join("")));
   }
 
-  // ── languages ──────────────────────────────────────────────
+  /* ── languages ───────────────────────────────────────────── */
   if (hasLangs) {
-    // separator
-    parts.push(
-      '<line x1="' +
-        PX +
-        '" y1="' +
-        (barY - 8) +
-        '" x2="' +
-        (W - PX) +
-        '" y2="' +
-        (barY - 8) +
-        '" stroke="' +
-        textColor +
-        '" stroke-opacity="0.08"/>',
+    const langParts: string[] = [];
+    langParts.push(
+      el("line", {
+        x1: PX,
+        y1: barY - 8,
+        x2: W - PX,
+        y2: barY - 8,
+        stroke: textColor,
+        "stroke-opacity": "0.08",
+      }),
     );
 
-    parts.push('<g transform="translate(0,0)">');
-
-    // track background & clip path for rounded corners
-    parts.push(
-      '<clipPath id="lang-clip"><rect x="' +
-        PX +
-        '" y="' +
-        barY +
-        '" width="' +
-        (animate ? "0" : contentW) +
-        '" height="' +
-        barH +
-        '" rx="5">' +
-        (animate
-          ? '<animate attributeName="width" from="0" to="' +
-            contentW +
-            '" dur="0.6s" fill="freeze"/>'
-          : "") +
-        "</rect></clipPath>",
+    langParts.push(
+      el(
+        "clipPath",
+        { id: "lang-clip" },
+        el(
+          "rect",
+          {
+            x: PX,
+            y: barY,
+            width: animate ? "0" : contentW,
+            height: barH,
+            rx: 5,
+          },
+          animate
+            ? el("animate", {
+                attributeName: "width",
+                from: "0",
+                to: contentW,
+                dur: "0.6s",
+                fill: "freeze",
+              })
+            : "",
+        ),
+      ),
     );
-    parts.push(
-      '<rect x="' +
-        PX +
-        '" y="' +
-        barY +
-        '" width="' +
-        contentW +
-        '" height="' +
-        barH +
-        '" rx="5" class="lang-progress"/>',
+    langParts.push(
+      el("rect", { x: PX, y: barY, width: contentW, height: barH, rx: 5, class: "lang-progress" }),
     );
 
-    parts.push('<g clip-path="url(#lang-clip)">');
-
-    const activeLangs = visualLangs;
+    const barParts: string[] = [];
     let off = 0;
-    for (let i = 0; i < activeLangs.length; i++) {
-      const lang = activeLangs[i]!;
+    for (let i = 0; i < visualLangs.length; i++) {
+      const lang = visualLangs[i]!;
       const pct = ((lang.size / totalSize) * 100).toFixed(1);
-      let w = i === activeLangs.length - 1 ? contentW - off : (lang.size / totalSize) * contentW;
+      let w = i === visualLangs.length - 1 ? contentW - off : (lang.size / totalSize) * contentW;
       if (w < 0) w = 0;
       const x = PX + off;
-
-      const tooltip = compact ? "" : "<title>" + escapeXml(lang.name) + " " + pct + "%</title>";
-
-      parts.push(
-        '<rect x="' +
-          x +
-          '" y="' +
-          barY +
-          '" width="' +
-          w +
-          '" height="' +
-          barH +
-          '" fill="' +
-          lang.color +
-          '">' +
-          tooltip +
-          "</rect>",
+      const tooltip = compact ? "" : el("title", {}, `${escapeXml(lang.name)} ${pct}%`);
+      barParts.push(
+        el("rect", { x, y: barY, width: w, height: barH, fill: raw(lang.color) }, tooltip),
       );
       off += w;
     }
+    langParts.push(el("g", { "clip-path": "url(#lang-clip)" }, barParts.join("")));
 
-    parts.push("</g>");
-
-    // legend (3-column grid)
     for (let i = 0; i < legendItems.length; i++) {
       const item = legendItems[i]!;
       const col = i % legendCols;
@@ -629,30 +551,33 @@ export function renderCard(
       const lx = PX + col * legendColW;
       const ly = legendY + row * legendRowH;
 
-      const staggerStyle = animate ? ' style="animation-delay: ' + (i + 3) * 150 + 'ms"' : "";
-      const staggerClass = animate ? ' class="stagger"' : "";
-
-      parts.push("<g" + staggerClass + staggerStyle + ">");
-      parts.push('<circle cx="' + (lx + 5) + '" cy="' + ly + '" r="4" fill="' + item.color + '"/>');
-      parts.push(
-        '<text x="' +
-          (lx + 14) +
-          '" y="' +
-          (ly + 4) +
-          '" class="lang-name" font-weight="500">' +
-          escapeXml(item.name) +
-          " " +
-          item.pct +
-          "%</text>",
+      langParts.push(
+        el(
+          "g",
+          {
+            class: animate ? "stagger" : undefined,
+            style: animate ? `animation-delay: ${(i + 3) * 150}ms` : undefined,
+          },
+          el("circle", { cx: lx + 5, cy: ly, r: 4, fill: item.color }) +
+            el(
+              "text",
+              { x: lx + 14, y: ly + 4, class: "lang-name", "font-weight": "500" },
+              `${escapeXml(item.name)} ${item.pct}%`,
+            ),
+        ),
       );
-      parts.push("</g>");
     }
 
-    parts.push("</g>");
+    parts.push(el("g", {}, langParts.join("")));
   }
 
-  // close
   parts.push("</svg>");
-
-  return parts.join("");
+  return parts
+    .join("")
+    .replace(/\bid="([^"]+)"/g, (_, id: string) => `id="${namespace}-${id}"`)
+    .replace(/="url\(#([^)]+)\)"/g, (_, id: string) => `="url(#${namespace}-${id})"`)
+    .replace(
+      'aria-labelledby="cardTitle cardDesc"',
+      `aria-labelledby="${namespace}-cardTitle ${namespace}-cardDesc"`,
+    );
 }