quiver-cli 1.2.0 → 1.3.1

package/template/.agents/skills/design/impeccable/scripts/lib/font-fingerprint.mjs

@@ -0,0 +1,564 @@
+/**
+ * font-fingerprint: size-invariant, text-robust shape features for lettering
+ * in a raster (a comp crop or a rendered sample). fingerprint(img) returns the
+ * feature vector; distance(a, b) compares two vectors over noise-normalized,
+ * weighted features. Used by font-match.mjs (comp measurement and ranking)
+ * and by the catalog index build (scripts/build-font-index.mjs at the repo root). Depends only on
+ * lib/image-metrics.mjs and lib/raster.mjs.
+ *
+ * Every measure is taken per text line and normalized by R, the line's
+ * reference height (median of the tallest column heights above the baseline:
+ * the cap line on an all-caps line, the ascender line on a mixed line), so
+ * the same face gives the same numbers at any point size; per-glyph measures
+ * are medians so the numbers survive a change of text. Small crops are
+ * upsampled (bilinear) so R is at least 24px, and stroke runs are measured
+ * with antialiased edge pixels counted by coverage, so stem widths do not
+ * fatten at small sizes.
+ *
+ * Features (all in R units unless noted; null when not measurable):
+ *   advance/advTall/advX  median glyph width over baseline glyphs / tall glyphs / x-height glyphs
+ *   advCV                 spread of glyph widths (std/median): mono ~0.15, sans ~0.3, script > 0.5
+ *   gap                   median inter-glyph gap
+ *   xRatio                x-line / R (null on all-caps lines)
+ *   descRatio             descender depth (90th pct)
+ *   stemW                 median horizontal ink run in the x band (stem width)
+ *   contrast              stem width / median thin (vertical) run: didone high, grotesque ~1
+ *   serif                 foot width / mid-stem width on stems that reach the baseline
+ *   roundFrac             fraction of glyphs with bbox aspect > 0.9
+ *   densTall / densX      ink / bbox area for tall / x-height glyphs (weight)
+ *   runDensity            horizontal ink runs per row per R of line width (stroke busyness)
+ *   vprof0..9             normalized vertical ink profile from 0.35R below baseline to 1.05R above
+ *   hrun25/50/75/90       quantiles of horizontal run lengths over the letter body
+ *   vrun25/50/75/90       quantiles of vertical run lengths over the whole line
+ *   colq25/75             quantiles of column heights above the baseline
+ *   wq25/75               quantiles of glyph widths
+ * Also returned: lines, glyphs, capHeightPx (R in source pixels), allCaps, inkIsDark,
+ * upsampled, weight (densTall, so v1 callers keep a weight field).
+ */
+import { toGray } from './image-metrics.mjs';
+import { resize } from './raster.mjs';
+
+function otsu(gray) {
+  const hist = new Float64Array(256);
+  for (let i = 0; i < gray.data.length; i++) hist[Math.max(0, Math.min(255, Math.round(gray.data[i])))]++;
+  const total = gray.data.length;
+  let sum = 0; for (let i = 0; i < 256; i++) sum += i * hist[i];
+  let sumB = 0, wB = 0, best = 0, thr = 128;
+  for (let t = 0; t < 256; t++) {
+    wB += hist[t]; if (!wB) continue;
+    const wF = total - wB; if (!wF) break;
+    sumB += t * hist[t];
+    const mB = sumB / wB, mF = (sum - sumB) / wF;
+    const between = wB * wF * (mB - mF) ** 2;
+    if (between > best) { best = between; thr = t; }
+  }
+  return thr;
+}
+
+const med = (a) => { if (!a.length) return null; const s = [...a].sort((p, q) => p - q); const m = s.length >> 1; return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2; };
+const pct = (a, p) => { if (!a.length) return null; const s = [...a].sort((p, q) => p - q); return s[Math.min(s.length - 1, Math.floor(p * s.length))]; };
+const mean = (a) => (a.length ? a.reduce((s, x) => s + x, 0) / a.length : null);
+
+/** Binarize; returns { W, H, ink: Uint8Array, inkIsDark }. */
+function binarize(img) {
+  const g = toGray(img);
+  let thr = otsu(g);
+  let dark = 0; for (let i = 0; i < g.data.length; i++) if (g.data[i] < thr) dark++;
+  // a two-level raster (no antialiasing) puts the Otsu threshold on the dark
+  // level itself; step it up so that level counts as ink
+  if (!dark) { thr += 1; for (let i = 0; i < g.data.length; i++) if (g.data[i] < thr) dark++; }
+  const inkIsDark = dark <= g.data.length / 2;
+  const ink = new Uint8Array(g.data.length);
+  let sI = 0, nI = 0, sG = 0, nG = 0;
+  for (let i = 0; i < g.data.length; i++) {
+    const on = (inkIsDark ? g.data[i] < thr : g.data[i] >= thr) ? 1 : 0;
+    ink[i] = on;
+    if (on) { sI += g.data[i]; nI++; } else { sG += g.data[i]; nG++; }
+  }
+  const inkLevel = nI ? sI / nI : (inkIsDark ? 0 : 255), groundLevel = nG ? sG / nG : (inkIsDark ? 255 : 0);
+  // coverage per pixel: 0 = ground, 1 = ink, linear between the two class means, so
+  // antialiased edge pixels count fractionally and stroke widths do not fatten at small sizes
+  const covA = new Float32Array(g.data.length);
+  const den = groundLevel - inkLevel || 1;
+  for (let i = 0; i < g.data.length; i++) covA[i] = Math.max(0, Math.min(1, (groundLevel - g.data[i]) / den));
+  const cov = (i) => covA[i];
+  return { W: g.width, H: g.height, ink, inkIsDark, cov, covA };
+}
+
+/** Text lines from the row-ink profile (same rules as font-match v1). */
+function findLines(bin) {
+  const { W, H, ink } = bin;
+  // Columns inked top to bottom (a rule, a black margin, a page edge) span
+  // every line and would fuse them into one run: leave them out of the row
+  // profile. Lettering never fills a column for more than ~85% of the crop.
+  const colInk = new Uint32Array(W);
+  for (let y = 0; y < H; y++) { const o = y * W; for (let x = 0; x < W; x++) colInk[x] += ink[o + x]; }
+  const colOk = new Uint8Array(W);
+  let okCount = 0;
+  for (let x = 0; x < W; x++) { if (colInk[x] < H * 0.85) { colOk[x] = 1; okCount++; } }
+  if (!okCount) return { lines: [], rowInk: new Uint32Array(H) };
+  const rowInk = new Uint32Array(H);
+  for (let y = 0; y < H; y++) { let c = 0; const o = y * W; for (let x = 0; x < W; x++) if (colOk[x]) c += ink[o + x]; rowInk[y] = c; }
+  const floor = Math.max(1, W * 0.004);
+  const runs = [];
+  let y = 0;
+  while (y < H) {
+    if (rowInk[y] > floor) {
+      const y0 = y; while (y < H && (rowInk[y] > floor || (y + 1 < H && rowInk[y + 1] > floor))) y++;
+      if (y - y0 >= 4) runs.push({ y0, y1: y });
+    } else y++;
+  }
+  const lines = [];
+  for (const run of runs) {
+    let peak = 0; for (let yy = run.y0; yy < run.y1; yy++) peak = Math.max(peak, rowInk[yy]);
+    const valley = peak * 0.15;
+    let start = run.y0, inValley = false, valleyStart = 0;
+    for (let yy = run.y0; yy < run.y1; yy++) {
+      const low = rowInk[yy] < valley;
+      if (low && !inValley) { inValley = true; valleyStart = yy; }
+      if (!low && inValley) {
+        inValley = false;
+        if (yy - valleyStart >= 3 && valleyStart - start >= 4) { lines.push({ y0: start, y1: valleyStart, run }); start = yy; }
+      }
+    }
+    if (run.y1 - start >= 4) lines.push({ y0: start, y1: run.y1, run });
+  }
+  // A piece split off inside one run with a fraction of the ink of the text
+  // lines is not a line: a thin band of ascenders or tittles above the x band
+  // (few letters reach it, so the valley rule fires) or a stray rule. Ascender
+  // bands merge back into the line below them; anything else is dropped.
+  for (const ln of lines) { let m = 0; for (let yy = ln.y0; yy < ln.y1; yy++) m += rowInk[yy]; ln.mass = m; }
+  // A drawing or photo sharing the crop with body copy is one tall, massive
+  // 'line' that would carry maxMass and drop every real line under the 30%
+  // rule (a 461x307 thread crop measured as one 160px 'cap' off a
+  // carburetor drawing). When several lines exist, ones far taller than the
+  // median are not lettering: leave them out of the mass reference and out
+  // of the result.
+  // The median is taken over lines carrying real mass (rule slivers and
+  // tittles do not vote), and needs three of them: two 145px headline lines
+  // above a 26px artist line were dropped as 'tall' against a median pulled
+  // to 28 by three slivers.
+  const massMax = Math.max(1, ...lines.map((l) => l.mass));
+  const real = lines.filter((l) => l.mass >= massMax * 0.05);
+  if (real.length >= 3) {
+    const hs = real.map((l) => l.y1 - l.y0).sort((a, b) => a - b);
+    const medH = hs[Math.floor(hs.length / 2)];
+    for (const ln of lines) if (ln.y1 - ln.y0 > medH * 3) ln.tall = true;
+  }
+  const maxMass = Math.max(0, ...lines.filter((l) => !l.tall).map((l) => l.mass));
+  const merged = [];
+  for (let i = 0; i < lines.length; i++) {
+    const ln = lines[i];
+    if (ln.tall) continue;
+    if (ln.mass >= maxMass * 0.3) { merged.push({ y0: ln.y0, y1: ln.y1, mass: ln.mass }); continue; }
+    const next = lines[i + 1];
+    if (next && next.run === ln.run && next.mass >= maxMass * 0.3 && (ln.y1 - ln.y0) <= (next.y1 - next.y0) * 0.5) { next.y0 = ln.y0; }
+  }
+  return { lines: merged, rowInk };
+}
+
+/** Feature names in fingerprint order (used by distance). */
+const VBINS = 10, HQ = [0.25, 0.5, 0.75, 0.9];
+export const FEATURES = ['advance', 'advTall', 'advX', 'advCV', 'gap', 'xRatio', 'descRatio', 'stemW', 'contrast', 'serif', 'roundFrac', 'densTall', 'densX', 'runDensity',
+  ...Array.from({ length: VBINS }, (_, i) => `vprof${i}`), ...HQ.map((q) => `hrun${Math.round(q * 100)}`), ...HQ.map((q) => `vrun${Math.round(q * 100)}`), 'colq25', 'colq75', 'wq25', 'wq75'];
+
+/** Center of the densest window of width tol in a list of values, and its count. */
+function modeOf(vals, tol) {
+  let best = null, bestC = -1;
+  const s = [...vals].sort((a, b) => a - b);
+  let j = 0;
+  for (let i = 0; i < s.length; i++) {
+    while (s[i] - s[j] > tol) j++;
+    const c = i - j + 1;
+    if (c > bestC) { bestC = c; best = (s[i] + s[j]) / 2; }
+  }
+  return { v: best, n: bestC };
+}
+
+/**
+ * Per-line vertical metrics from column extrema, which do not need glyphs to
+ * be separable. baseline = mode of column bottoms. R (the reference height)
+ * is the top line of the tallest cluster: the cap line on an all-caps line,
+ * the ascender line (or the cap line when caps are taller) on a mixed line.
+ * The x-line is a second mode of column heights well below R; when there is
+ * none the line is read as all-caps.
+ */
+function lineMetrics(bin, ln) {
+  const { W, ink, cov } = bin;
+  const cols = [];
+  for (let x = 0; x < W; x++) {
+    let top = -1, bot = -1;
+    for (let yy = ln.y0; yy < ln.y1; yy++) if (ink[yy * W + x]) { if (top < 0) top = yy; bot = yy + 1; }
+    if (top < 0) continue;
+    // sub-pixel edges from the antialiased boundary pixel's coverage
+    const t = top > 0 ? top - cov((top - 1) * W + x) : top;
+    const b = bot < bin.H ? bot + cov(bot * W + x) : bot;
+    cols.push({ x, top: t, bot: b });
+  }
+  if (cols.length < 8) return null;
+  const roughH = pct(cols.map((c) => c.bot - c.top), 0.9);
+  const tol = Math.max(1, Math.round(roughH * 0.04));
+  const baseF = modeOf(cols.map((c) => c.bot), tol).v;
+  const base = Math.round(baseF);
+  const hs = cols.filter((c) => c.bot <= baseF + tol * 1.5).map((c) => baseF - c.top).filter((h) => h > 0);
+  if (hs.length < 8) return null;
+  const hMaxAbs = pct(hs, 0.995);
+  const topCluster = hs.filter((h) => h >= hMaxAbs * 0.94);
+  const R = med(topCluster);
+  if (!R || R < 4) return null;
+  const lowHs = hs.filter((h) => h >= R * 0.3 && h <= R * 0.86);
+  let xh = null;
+  if (lowHs.length >= Math.max(6, hs.length * 0.12)) {
+    const m = modeOf(lowHs, tol);
+    if (m.n >= Math.max(4, lowHs.length * 0.25)) xh = m.v;
+  }
+  const dsc = cols.filter((c) => c.bot > baseF + tol * 1.5 && c.top < baseF - R * 0.3).map((c) => (c.bot - baseF) / R);
+  const descRatio = dsc.length >= 4 ? pct(dsc, 0.9) : null;
+  return { base, R, cap: R, xh, descRatio, tol, xL: cols[0].x, xR: cols[cols.length - 1].x + 1, hs, ln };
+}
+
+/** Glyph boxes: column runs of ink inside the x band, so ascender/descender bridges do not merge letters. */
+function segment(bin, ln, m) {
+  const { W, ink } = bin;
+  const bandTop = Math.max(ln.y0, Math.round(m.base - (m.xh || m.cap * 0.6)));
+  const bandH = m.base - bandTop;
+  const thr = 1;
+  const colBand = new Uint32Array(W);
+  for (let yy = bandTop; yy < m.base; yy++) { const o = yy * W; for (let x = m.xL; x < m.xR; x++) colBand[x] += ink[o + x]; }
+  const runs = [];
+  let x = m.xL;
+  while (x < m.xR) {
+    if (colBand[x] >= thr) { const x0 = x; while (x < m.xR && colBand[x] >= thr) x++; runs.push({ x0, x1: x }); } else x++;
+  }
+  const out = [];
+  for (const r of runs) {
+    let top = -1, bot = -1, area = 0;
+    for (let yy = ln.y0; yy < ln.y1; yy++) {
+      let c = 0, cv = 0; const o = yy * W; for (let xx = r.x0; xx < r.x1; xx++) { c += ink[o + xx]; cv += bin.covA[o + xx]; }
+      if (c) { if (top < 0) top = yy; bot = yy + 1; }
+      area += cv;
+    }
+    if (top >= 0) out.push({ x0: r.x0, x1: r.x1, w: r.x1 - r.x0, top, bot, h: bot - top, area });
+  }
+  return out;
+}
+
+function measure(bin, lines) {
+  const { W, H, ink, covA } = bin;
+  // run lengths with the antialiased edge pixels counted by coverage
+  const hLen = (o, x0, x1) => { let s = 0; for (let x = Math.max(0, x0 - 1); x < Math.min(W, x1 + 1); x++) s += covA[o + x]; return s; };
+  const vLen = (x, y0, y1) => { let s = 0; for (let y = Math.max(0, y0 - 1); y < Math.min(H, y1 + 1); y++) s += covA[y * W + x]; return s; };
+  let glyphN = 0;
+  const per = { xh: [], desc: [], runDensity: [] };
+  let allCapsLines = 0;
+  const vprof = new Float64Array(VBINS); const hruns = [], vruns = [], colHs = [], widths = [];
+  const advTall = [], advAll = [], advX = [], gaps = [], stems = [], thins = [], serifR = [], round = [], densTall = [], densX = [];
+  let capSum = 0, capN = 0;
+  // One crop, one case. In a multi-line all-caps headline one line can grow a
+  // spurious x-height from crossbars (the A and E arms of "JAPANESE" at 0.32R)
+  // while its neighbours report none; that line then measures its stems and
+  // its x band on the crossbar zone. Lines vote: when most lines see no
+  // x-height, none does.
+  const metrics = lines.map((ln) => lineMetrics(bin, ln)).filter(Boolean);
+  if (metrics.length >= 2) {
+    const withX = metrics.filter((m) => m.xh).length;
+    if (withX * 2 <= metrics.length) for (const m of metrics) m.xh = null;
+  }
+  for (const m of metrics) {
+    const ln = m.ln;
+    const { base, cap, xh, tol, xL, xR } = m;
+    capSum += cap; capN++;
+    if (xh) per.xh.push(xh / cap);
+    if (!xh) allCapsLines++;
+    if (m.descRatio != null) per.desc.push(m.descRatio);
+    for (const h of m.hs) colHs.push(h / cap);
+    // vertical ink profile from 0.35R below the baseline to 1.05R above, VBINS bins
+    for (let yy = ln.y0; yy < ln.y1; yy++) {
+      const u = (base - yy - 0.5) / cap; // height above baseline in R units
+      const bi = Math.floor((u + 0.35) / 1.4 * VBINS);
+      if (bi < 0 || bi >= VBINS) continue;
+      let c = 0; const o = yy * W; for (let x = xL; x < xR; x++) c += ink[o + x];
+      vprof[bi] += c;
+    }
+    // horizontal run lengths over the whole line body (x band to cap line), vertical run lengths over all columns
+    for (let yy = Math.max(ln.y0, Math.round(base - cap)); yy < base; yy++) {
+      const o = yy * W; let x = xL;
+      while (x < xR) { if (ink[o + x]) { const x0 = x; while (x < xR && ink[o + x]) x++; hruns.push(hLen(o, x0, x) / cap); } else x++; }
+    }
+    for (let x = xL; x < xR; x++) {
+      let yy = ln.y0;
+      while (yy < ln.y1) { if (ink[yy * W + x]) { const y0 = yy; while (yy < ln.y1 && ink[yy * W + x]) yy++; vruns.push(vLen(x, y0, yy) / cap); } else yy++; }
+    }
+    const gl = segment(bin, ln, m);
+    const G = gl.filter((g) => g.w >= cap * 0.12 && (base - g.top) >= cap * 0.3);
+    glyphN += G.length;
+    const onBase = G.filter((g) => Math.abs(g.bot - base) <= tol * 1.5);
+    const capG = onBase.filter((g) => base - g.top >= cap * 0.88);
+    const xs = xh ? onBase.filter((g) => Math.abs(base - g.top - xh) <= Math.max(tol * 1.5, cap * 0.05)) : [];
+    for (const g of capG) { advTall.push(g.w / cap); densTall.push(g.area / (g.w * g.h)); }
+    for (const g of xs) { densX.push(g.area / (g.w * g.h)); advX.push(g.w / cap); }
+    for (const g of onBase) { advAll.push(g.w / cap); widths.push(g.w / cap); round.push(g.w / (base - g.top) > 0.9 ? 1 : 0); }
+    for (let i = 0; i + 1 < G.length; i++) { const gap = G[i + 1].x0 - G[i].x1; if (gap >= 0 && gap < cap * 0.6) gaps.push(gap / cap); }
+    const xTop = base - (xh || cap * 0.55);
+    const bandTop = Math.round(xTop + (base - xTop) * 0.2), bandBot = Math.round(base - (base - xTop) * 0.2);
+    let runCount = 0, runRows = 0;
+    for (let yy = bandTop; yy < bandBot; yy++) {
+      const o = yy * W; let x = xL; runRows++;
+      while (x < xR) { if (ink[o + x]) { const x0 = x; while (x < xR && ink[o + x]) x++; const L = hLen(o, x0, x); runCount++; if (L < cap * 0.5) stems.push(L / cap); } else x++; }
+    }
+    if (runRows) per.runDensity.push((runCount / runRows) / ((xR - xL) / cap));
+    for (let x = xL; x < xR; x++) {
+      let yy = ln.y0;
+      while (yy < ln.y1) { if (ink[yy * W + x]) { const y0 = yy; while (yy < ln.y1 && ink[yy * W + x]) yy++; const L = vLen(x, y0, yy); if (L < cap * 0.35) thins.push(L / cap); } else yy++; }
+    }
+    // serif: stems that run straight to the baseline; foot width vs mid-stem width
+    const runAt = (yy, x) => { const o = yy * W; if (!ink[o + x]) return 0; let a = x, b = x; while (a > xL && ink[o + a - 1]) a--; while (b + 1 < xR && ink[o + b + 1]) b++; return hLen(o, a, b + 1); };
+    const yMid = Math.round(base - cap * 0.4), yHi = Math.round(base - cap * 0.18), yFoot = base - Math.max(1, Math.round(cap * 0.04));
+    let x = xL;
+    while (x < xR) {
+      let yy = base - 1; if (!ink[yy * W + x]) { x++; continue; }
+      while (yy > ln.y0 && ink[(yy - 1) * W + x]) yy--;
+      if (yy > yMid) { x++; continue; }
+      const x0 = x; x++; while (x < xR && ink[(base - 1) * W + x] && ink[yMid * W + x]) x++;
+      const xc = Math.round((x0 + x - 1) / 2);
+      const wMid = runAt(yMid, xc), wHi = runAt(yHi, xc), wFoot = runAt(yFoot, xc);
+      if (wMid > 0 && wMid < cap * 0.5 && wHi <= wMid * 1.3 && wHi >= wMid * 0.7) serifR.push(wFoot / wMid);
+    }
+  }
+  if (!capN) return null;
+  const stemW = med(stems), thinW = med(thins);
+  const advM = med(advAll);
+  const advSd = advAll.length > 3 ? Math.sqrt(advAll.reduce((s, v) => s + (v - advM) ** 2, 0) / advAll.length) : null;
+  const vsum = vprof.reduce((s, x) => s + x, 0) || 1;
+  const extra = {};
+  for (let i = 0; i < VBINS; i++) extra[`vprof${i}`] = vprof[i] / vsum;
+  for (const q of HQ) { extra[`hrun${Math.round(q * 100)}`] = pct(hruns, q); extra[`vrun${Math.round(q * 100)}`] = pct(vruns, q); }
+  extra.colq25 = pct(colHs, 0.25); extra.colq75 = pct(colHs, 0.75);
+  extra.wq25 = pct(widths, 0.25); extra.wq75 = pct(widths, 0.75);
+  return {
+    ...extra,
+    capHeightPx: capSum / capN,
+    glyphs: glyphN,
+    advance: advM,
+    advTall: advTall.length ? med(advTall) : null,
+    advX: advX.length ? med(advX) : null,
+    advCV: advSd != null && advM ? advSd / advM : null,
+    gap: gaps.length ? med(gaps) : 0,
+    xRatio: per.xh.length ? med(per.xh) : null,
+    descRatio: per.desc.length ? med(per.desc) : null,
+    allCaps: allCapsLines * 2 > capN,
+    runDensity: med(per.runDensity),
+    stemW,
+    contrast: stemW && thinW ? stemW / thinW : null,
+    serif: serifR.length >= 3 ? med(serifR) : null,
+    roundFrac: round.length ? mean(round) : null,
+    densTall: densTall.length ? med(densTall) : null,
+    densX: densX.length ? med(densX) : null,
+  };
+}
+
+/**
+ * fingerprint(img) -> features, or null when no lettering is found. Upsamples (bilinear) when the
+ * cap height is under 24px so runs and edges are measured on finer pixels.
+ */
+/**
+ * Keep the dominant lettering in a region crop: the lines whose cap height is
+ * within `tol` of the tallest, clipped horizontally to their own ink. A comp
+ * region drawn on a 10x10 grid over-covers: the headline crop carries the
+ * first line of body copy below it and a slice of the neighbouring column,
+ * and every one of those small letters pulls stem width, run lengths and the
+ * x-height vote toward a lighter, wider face. Returns { lines, x0, x1 } in
+ * the binarized image, or null when nothing survives.
+ */
+export function isolateDominant(bin, lines, { tol = 0.28 } = {}) {
+  const ms = lines.map((ln) => ({ ln, m: lineMetrics(bin, ln) })).filter((x) => x.m);
+  if (!ms.length) return null;
+  // The dominant class is the one holding most of the ink, not the tallest
+  // line: a body-copy crop that clips the last line of the headline above it
+  // is body copy. Cluster caps within tol of each other and pick the cluster
+  // with the most ink mass; the tallest wins only a tie.
+  const clusters = [];
+  for (const x of [...ms].sort((a, b) => b.m.cap - a.m.cap)) {
+    const c = clusters.find((cl) => Math.abs(cl.cap - x.m.cap) <= cl.cap * tol);
+    if (c) { c.items.push(x); c.mass += x.ln.mass || 0; } else clusters.push({ cap: x.m.cap, items: [x], mass: x.ln.mass || 0 });
+  }
+  // Mass per line-height, so one heavy display line does not outvote five
+  // lines of body copy; and a cluster of a single clipped line never wins
+  // over a cluster of three or more.
+  for (const c of clusters) { c.rows = c.items.reduce((n, x) => n + (x.ln.y1 - x.ln.y0), 0); c.density = c.mass / Math.max(1, c.rows); c.n = c.items.length; }
+  clusters.sort((a, b) => {
+    const aMulti = a.n >= 3, bMulti = b.n >= 3;
+    if (aMulti !== bMulti) return aMulti ? -1 : 1;
+    return (b.mass - a.mass) || (b.cap - a.cap);
+  });
+  const keep = clusters[0].items;
+  const capMax = Math.max(...keep.map((x) => x.m.cap));
+  // horizontal extent of the kept lines' tallest ink columns only: a small
+  // column of body text beside the headline shares its rows but not its height
+  const { W, ink } = bin;
+  let x0 = W, x1 = 0;
+  for (const { ln, m } of keep) {
+    const top = Math.round(m.base - m.cap * 0.75);
+    for (let x = m.xL; x < m.xR; x++) {
+      let tall = false;
+      for (let y = top; y < m.base && !tall; y++) if (ink[y * W + x]) tall = true;
+      if (!tall) continue;
+      // a column is headline ink when a run of at least 0.5 cap of ink stands in it
+      let run = 0, best = 0;
+      for (let y = ln.y0; y < ln.y1; y++) { if (ink[y * W + x]) { run++; if (run > best) best = run; } else run = 0; }
+      if (best >= m.cap * 0.5) { if (x < x0) x0 = x; if (x + 1 > x1) x1 = x + 1; }
+    }
+  }
+  if (x1 <= x0) return null;
+  // grow the box by half a cap so glyph sides and the tracking gap survive
+  const pad = Math.round(capMax * 0.5);
+  return { lines: keep.map((x) => x.ln), x0: Math.max(0, x0 - pad), x1: Math.min(W, x1 + pad), dropped: ms.length - keep.length };
+}
+
+function maskOutside(bin, x0, x1, lines) {
+  const { W, H, ink, covA } = bin;
+  const keepRow = new Uint8Array(H);
+  for (const ln of lines) for (let y = ln.y0; y < ln.y1; y++) keepRow[y] = 1;
+  const ink2 = new Uint8Array(ink.length), cov2 = new Float32Array(covA.length);
+  for (let y = 0; y < H; y++) {
+    if (!keepRow[y]) continue;
+    for (let x = x0; x < x1; x++) { const i = y * W + x; ink2[i] = ink[i]; cov2[i] = covA[i]; }
+  }
+  return { ...bin, ink: ink2, covA: cov2, cov: (i) => cov2[i] };
+}
+
+export function fingerprint(img, { minCap = 24, minGlyphs = 3, isolate = true } = {}) {
+  let bin = binarize(img);
+  let { lines } = findLines(bin);
+  if (!lines.length) return null;
+  let isolated = 0;
+  if (isolate && lines.length > 1) {
+    const iso = isolateDominant(bin, lines);
+    if (iso && (iso.dropped > 0 || iso.x1 - iso.x0 < bin.W * 0.9)) {
+      bin = maskOutside(bin, iso.x0, iso.x1, iso.lines);
+      lines = iso.lines;
+      isolated = iso.dropped;
+    }
+  }
+  let f = measure(bin, lines);
+  // fewer than minGlyphs separable glyphs is not lettering (a rule, a solid
+  // bar, one letterform): callers read null as "no separable lettering"
+  if (!f || f.glyphs < minGlyphs) return null;
+  let scale = 1;
+  if (f.capHeightPx < minCap && f.capHeightPx >= 4) {
+    scale = Math.min(4, Math.ceil(minCap / f.capHeightPx));
+    const up = resize(img, img.width * scale, img.height * scale);
+    bin = binarize(up);
+    lines = findLines(bin).lines;
+    // the upsample re-reads the whole crop: isolate again so the clipped
+    // headline or the drawing does not come back at scale
+    if (isolate && lines.length > 1) {
+      const iso2 = isolateDominant(bin, lines);
+      if (iso2 && (iso2.dropped > 0 || iso2.x1 - iso2.x0 < bin.W * 0.9)) { bin = maskOutside(bin, iso2.x0, iso2.x1, iso2.lines); lines = iso2.lines; isolated = Math.max(isolated, iso2.dropped); }
+    }
+    const f2 = lines.length ? measure(bin, lines) : null;
+    if (f2) f = f2;
+    else scale = 1;
+  }
+  const r = { lines: lines.length, glyphs: f.glyphs, capHeightPx: +(f.capHeightPx / scale).toFixed(1), inkIsDark: bin.inkIsDark, upsampled: scale > 1, allCaps: f.allCaps, isolatedFrom: isolated, weight: f.densTall == null && f.densX == null ? null : +(f.densTall ?? f.densX).toFixed(4) };
+  for (const k of FEATURES) r[k] = f[k] == null ? null : +f[k].toFixed(4);
+  return r;
+}
+
+/**
+ * Distance normalization fitted on 299 held-out probes (150 at ~30px cap, 149
+ * at ~14px, text different from the index text) against a 3,092-entry Google
+ * Fonts index: std = within-family noise (1.4826 x median |probe - own index
+ * entry|, floored at 5% of the catalog IQR spread), w = group weight from
+ * coordinate descent on top-5 family recall. mean is unused by the distance.
+ */
+export const STATS = {
+  advance: { std: 0.07648, w: 0 },
+  advTall: { std: 0.25331, w: 0 },
+  advX: { std: 0.05144, w: 1.5 },
+  advCV: { std: 0.0857, w: 1 },
+  gap: { std: 0.02668, w: 1 },
+  xRatio: { std: 0.02315, w: 1 },
+  descRatio: { std: 0.17831, w: 1 },
+  stemW: { std: 0.01922, w: 1 },
+  contrast: { std: 0.05969, w: 3 },
+  serif: { std: 0.31477, w: 0.5 },
+  roundFrac: { std: 0.09341, w: 1 },
+  densTall: { std: 0.05708, w: 2 },
+  densX: { std: 0.07666, w: 0 },
+  runDensity: { std: 0.18199, w: 1 },
+  vprof0: { std: 0.01178, w: 1 },
+  vprof1: { std: 0.01331, w: 1 },
+  vprof2: { std: 0.02745, w: 1 },
+  vprof3: { std: 0.03046, w: 1 },
+  vprof4: { std: 0.01933, w: 1 },
+  vprof5: { std: 0.01737, w: 1 },
+  vprof6: { std: 0.0336, w: 1 },
+  vprof7: { std: 0.03195, w: 1 },
+  vprof8: { std: 0.03271, w: 1 },
+  vprof9: { std: 0.02951, w: 1 },
+  hrun25: { std: 0.01751, w: 1 },
+  hrun50: { std: 0.02124, w: 1 },
+  hrun75: { std: 0.04503, w: 1 },
+  hrun90: { std: 0.06844, w: 1 },
+  vrun25: { std: 0.01895, w: 1 },
+  vrun50: { std: 0.02405, w: 1 },
+  vrun75: { std: 0.06199, w: 1 },
+  vrun90: { std: 0.09486, w: 1 },
+  colq25: { std: 0.02906, w: 1 },
+  colq75: { std: 0.18204, w: 1 },
+  wq25: { std: 0.19862, w: 1 },
+  wq75: { std: 0.09687, w: 1 },
+};
+export const Z_CLIP = 3;
+
+/** Weighted L1 over z-scored features; a feature missing on either side is skipped and the weight mass renormalized. */
+/**
+ * The two readings a designer makes before any detail: how wide, how heavy.
+ * Width from the advance of tall glyphs (all-caps crops) or x-height glyphs;
+ * weight from ink density of tall glyphs. Both are on the same scale in the
+ * comp crop and in a catalog render, so their gap is a plain ratio. Distance
+ * adds a penalty that grows with the ratio's log: a face 50% wider or 35%
+ * lighter than the comp cannot rank above one that is right on both, whatever
+ * its run-length profile says. Weighted like three fine features (the width
+ * gap and the weight gap each score up to zClip x 1.5).
+ */
+export function grossGap(a, b) {
+  const pick = (f, keys) => { for (const k of keys) if (f[k] != null) return { k, v: f[k] }; return null; };
+  const wa = pick(a, ['advX', 'advTall', 'advance']), wb = wa ? (b[wa.k] != null ? { k: wa.k, v: b[wa.k] } : null) : null;
+  const ha = pick(a, ['densTall', 'densX', 'stemW']), hb = ha ? (b[ha.k] != null ? { k: ha.k, v: b[ha.k] } : null) : null;
+  const gap = (x, y) => (x && y && x.v > 0 && y.v > 0 ? Math.abs(Math.log(y.v / x.v)) : null);
+  return { width: gap(wa, wb), weight: gap(ha, hb) };
+}
+
+export const GROSS_STD = { width: 0.12, weight: 0.12 }; // one "step" of width class or weight class, in log ratio
+export const GROSS_W = 1.5;
+
+export function distance(a, b, stats = STATS, { p = 1, zClip = Z_CLIP, gross = true } = {}) {
+  let d = 0, wsum = 0;
+  if (gross) {
+    const g = grossGap(a, b);
+    for (const k of ['width', 'weight']) {
+      if (g[k] == null) continue;
+      const z = Math.min(zClip, g[k] / GROSS_STD[k]);
+      d += GROSS_W * (p === 1 ? z : z * z); wsum += GROSS_W;
+    }
+  }
+  for (const k of FEATURES) {
+    const s = stats[k]; if (!s || !s.w) continue;
+    const av = a[k], bv = b[k];
+    if (av == null || bv == null) continue;
+    const z = Math.min(zClip, Math.abs(av - bv) / s.std);
+    d += s.w * (p === 1 ? z : z * z); wsum += s.w;
+  }
+  if (!wsum) return Infinity;
+  const v = d / wsum;
+  return p === 1 ? v : Math.sqrt(v);
+}
+
+/** Debug: per-line metrics (base, R, xh, mode counts) for a raster. */
+export function _debugLines(img) {
+  const bin = binarize(img);
+  const { lines } = findLines(bin);
+  return lines.map((ln) => { const m = lineMetrics(bin, ln); if (!m) return { ln, m: null }; const hs = m.hs.map((h) => +(h / m.R).toFixed(2)).sort((a, b) => a - b); const hist = {}; for (const h of hs) { const b = Math.round(h * 20) / 20; hist[b] = (hist[b] || 0) + 1; } return { y0: ln.y0, y1: ln.y1, base: m.base, R: +m.R.toFixed(1), xh: m.xh && +m.xh.toFixed(1), hist }; });
+}