@zombie-mermaid/core 2.2.1

package/src/__tests__/diagram-type.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest'
+import { detectDiagramType } from '@zombie-mermaid/core'
+
+describe('detectDiagramType', () => {
+  it('detects each diagram type from its header keyword', () => {
+    expect(detectDiagramType('flowchart TD\nA-->B')).toBe('flowchart')
+    expect(detectDiagramType('sequenceDiagram\nA->>B: Hi')).toBe('sequence')
+    expect(detectDiagramType('classDiagram\nclass Foo')).toBe('class')
+    expect(detectDiagramType('erDiagram\nFOO ||--o{ BAR : has')).toBe('er')
+    expect(detectDiagramType('xychart-beta\nx-axis [a, b]')).toBe('xychart')
+  })
+
+  it('isolates the header on a semicolon-separated single line', () => {
+    expect(detectDiagramType('sequenceDiagram;A->>B: Hi')).toBe('sequence')
+    expect(detectDiagramType('classDiagram;class Foo')).toBe('class')
+    expect(detectDiagramType('erDiagram;FOO ||--o{ BAR : has')).toBe('er')
+    expect(detectDiagramType('flowchart TD;A-->B')).toBe('flowchart')
+  })
+
+  it('does not match an xychart header with an unsupported suffix', () => {
+    expect(detectDiagramType('xychart-foo\nx-axis [a, b]')).toBe('flowchart')
+  })
+
+  it('falls back to flowchart for unrecognized input', () => {
+    expect(detectDiagramType('')).toBe('flowchart')
+    expect(detectDiagramType('not a real header')).toBe('flowchart')
+  })
+})

package/src/__tests__/text-metrics.test.ts

@@ -0,0 +1,486 @@
+/**
+ * Tests for text-metrics module — variable-width character measurement.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  getCharWidth,
+  measureTextWidth,
+  isWideChar,
+  hasMeasuredAdvance,
+} from '@zombie-mermaid/core'
+
+// ============================================================================
+// Character width classification
+// ============================================================================
+
+describe('getCharWidth', () => {
+  describe('narrow characters', () => {
+    it('measures thin letters as narrow (i, l, t, f, j, I)', () => {
+      for (const ch of ['i', 'l', 't', 'f', 'j', 'I']) {
+        expect(getCharWidth(ch), ch).toBeLessThan(0.7)
+      }
+    })
+
+    it('measures thin punctuation as narrow', () => {
+      for (const ch of ['!', '|', '.', ',', ':', ';', "'", '1']) {
+        expect(getCharWidth(ch), ch).toBeLessThan(0.8)
+      }
+    })
+
+    it('measures r as semi-narrow', () => {
+      expect(getCharWidth('r')).toBeGreaterThan(getCharWidth('i'))
+      expect(getCharWidth('r')).toBeLessThan(getCharWidth('a'))
+    })
+  })
+
+  describe('normal characters', () => {
+    it('measures average lowercase letters near 1.0', () => {
+      for (const ch of ['a', 'e', 'o', 'n', 's']) {
+        expect(getCharWidth(ch), ch).toBeGreaterThan(0.9)
+        expect(getCharWidth(ch), ch).toBeLessThan(1.15)
+      }
+    })
+
+    it('measures digits near 1.0-1.2 (tabular width)', () => {
+      for (const ch of ['0', '2', '9']) {
+        expect(getCharWidth(ch), ch).toBeGreaterThan(1.0)
+        expect(getCharWidth(ch), ch).toBeLessThan(1.2)
+      }
+    })
+  })
+
+  describe('wide characters', () => {
+    it('measures uppercase letters wider than lowercase (except I)', () => {
+      for (const ch of ['A', 'B', 'N', 'Z']) {
+        expect(getCharWidth(ch), ch).toBeGreaterThan(1.1)
+        expect(getCharWidth(ch), ch).toBeLessThan(1.45)
+      }
+    })
+
+    it('measures wide lowercase (w, m) above 1.4', () => {
+      expect(getCharWidth('w')).toBeGreaterThan(1.4)
+      expect(getCharWidth('m')).toBeGreaterThan(1.4)
+    })
+
+    it('measures very wide characters (W, M) above 1.6', () => {
+      expect(getCharWidth('W')).toBeGreaterThan(1.6)
+      expect(getCharWidth('M')).toBeGreaterThan(1.6)
+    })
+  })
+
+  describe('space', () => {
+    it('measures space at its real Inter advance (~0.52)', () => {
+      // The old bucket value of 0.3 underestimated every word gap by ~1.3px
+      expect(getCharWidth(' ')).toBeCloseTo(0.521, 3)
+    })
+  })
+
+  describe('previously-omitted punctuation (measured Inter advances)', () => {
+    // Real Inter advances (canvas measureText, headless Chrome, weight 400,
+    // same method as the rest of INTER_ADVANCES), measured at 100px and
+    // normalized by the weight-400 baseRatio (0.54): ratio = px / (100 * 0.54).
+    // Before this table entry existed, these characters fell through to the
+    // old coarse bucket (`) or the 1.0 default (all others), which could
+    // undersize labels with repeated occurrences of these characters.
+    it.each([
+      ['#', 1.173],
+      ['$', 1.188],
+      ['&', 1.193],
+      ['*', 0.928],
+      ['<', 1.225],
+      ['=', 1.225],
+      ['>', 1.225],
+      ['?', 0.947],
+      ['^', 0.873],
+      ['`', 0.598],
+      ['~', 1.225],
+    ])('measures %s at its real Inter advance', (ch, expected) => {
+      expect(getCharWidth(ch)).toBeCloseTo(expected, 3)
+    })
+  })
+
+  describe('table completeness', () => {
+    it('has an exact measured Inter advance for every printable ASCII character (U+0020–U+007E)', () => {
+      const missing: string[] = []
+      for (let code = 0x20; code <= 0x7e; code++) {
+        const ch = String.fromCharCode(code)
+        if (!hasMeasuredAdvance(ch))
+          missing.push(`U+${code.toString(16).padStart(4, '0')} (${ch})`)
+      }
+      expect(missing).toEqual([])
+    })
+  })
+
+  describe('inherited Object.prototype keys', () => {
+    // INTER_ADVANCES is a plain object literal, so bracket access with
+    // `!== undefined` also matches inherited Object.prototype properties
+    // like 'toString' and 'constructor' — they are not real table entries,
+    // but a naive `obj[key] !== undefined` check can't tell the difference.
+    it.each(['toString', 'constructor', 'hasOwnProperty', '__proto__'])(
+      'hasMeasuredAdvance(%s) is false — not an own property of the table',
+      (key) => {
+        expect(hasMeasuredAdvance(key)).toBe(false)
+      },
+    )
+
+    it('getCharWidth never returns an inherited property instead of a measured width', () => {
+      // Without an own-property check, `INTER_ADVANCES['toString'] !== undefined`
+      // is true (it resolves Object.prototype.toString), so getCharWidth('toString')
+      // would return that function instead of a number. With the own-property
+      // check in place, the direct-table lookup correctly misses, and the
+      // multi-character string instead falls through to the (unrelated,
+      // NFD-based) accented-Latin branch, which matches on its first
+      // normalized character ('t') — still a real measured number, never a
+      // function.
+      const result = getCharWidth('toString')
+      expect(typeof result).toBe('number')
+      expect(result).toBe(getCharWidth('t'))
+    })
+  })
+
+  describe('combining marks (zero-width)', () => {
+    it('returns 0 for combining diacritical marks', () => {
+      // U+0301 = combining acute accent
+      expect(getCharWidth('\u0301')).toBe(0)
+      // U+0308 = combining diaeresis
+      expect(getCharWidth('\u0308')).toBe(0)
+      // U+0327 = combining cedilla
+      expect(getCharWidth('\u0327')).toBe(0)
+    })
+  })
+
+  describe('accented characters (precomposed)', () => {
+    it('returns the base letter width for precomposed accented letters', () => {
+      // Accents don't change the advance — é measures the same as e
+      expect(getCharWidth('é')).toBe(getCharWidth('e')) // U+00E9
+      expect(getCharWidth('ñ')).toBe(getCharWidth('n')) // U+00F1
+      expect(getCharWidth('ü')).toBe(getCharWidth('u')) // U+00FC
+      expect(getCharWidth('ç')).toBe(getCharWidth('c')) // U+00E7
+      expect(getCharWidth('ö')).toBe(getCharWidth('o')) // U+00F6
+    })
+
+    it('falls through to the default character-class logic when the NFD base is not itself a measured ASCII letter', () => {
+      // U+0439 (й, Cyrillic "short i") NFD-decomposes to U+0438 (и) + a
+      // combining breve. The base "и" differs from the char, but it is a
+      // Cyrillic letter, not one of the printable-ASCII keys in
+      // INTER_ADVANCES — so the lookup misses and getCharWidth must fall
+      // through to the coarse character-class buckets below instead of
+      // returning `undefined`-derived garbage.
+      const char = 'й'
+      const base = char.normalize('NFD')[0]
+      if (base === undefined)
+        throw new Error(
+          'unreachable: normalize() of a non-empty string always has index 0',
+        )
+      expect(base).not.toBe(char) // sanity: this char does decompose
+      expect(hasMeasuredAdvance(base)).toBe(false) // sanity: base has no exact advance
+
+      // None of the ASCII character-class buckets match a Cyrillic letter,
+      // and its code point (0x0439) is outside both the A-Z and 0-9 ranges,
+      // so it lands on the final default width.
+      expect(getCharWidth(char)).toBe(1.0)
+    })
+  })
+
+  describe('CJK characters (fullwidth)', () => {
+    it('returns 2.0 for CJK ideographs', () => {
+      expect(getCharWidth('中')).toBe(2.0) // U+4E2D
+      expect(getCharWidth('国')).toBe(2.0) // U+56FD
+      expect(getCharWidth('字')).toBe(2.0) // U+5B57
+    })
+
+    it('returns 2.0 for Japanese hiragana/katakana', () => {
+      expect(getCharWidth('あ')).toBe(2.0) // Hiragana
+      expect(getCharWidth('ア')).toBe(2.0) // Katakana
+    })
+
+    it('returns 2.0 for Korean hangul', () => {
+      expect(getCharWidth('한')).toBe(2.0) // U+D55C
+      expect(getCharWidth('글')).toBe(2.0) // U+AE00
+    })
+  })
+
+  describe('emoji (fullwidth)', () => {
+    it('returns 2.0 for common emoji', () => {
+      expect(getCharWidth('😀')).toBe(2.0)
+      expect(getCharWidth('🚀')).toBe(2.0)
+      expect(getCharWidth('❤')).toBe(2.0)
+    })
+  })
+
+  describe('edge cases', () => {
+    it('returns 0 for empty string', () => {
+      expect(getCharWidth('')).toBe(0)
+    })
+  })
+})
+
+// ============================================================================
+// Text width measurement
+// ============================================================================
+
+describe('measureTextWidth', () => {
+  const fontSize = 13
+  const fontWeight = 500
+  const baseRatio = 0.57 // weight 500 (was 0.55, increased for edge truncation safety)
+  const minPadding = fontSize * 0.15 // minimum padding added to prevent truncation (increased for label separation)
+
+  it('returns minPadding for empty text', () => {
+    // Empty text still gets minimum padding to prevent edge truncation
+    expect(measureTextWidth('', fontSize, fontWeight)).toBeCloseTo(
+      minPadding,
+      1,
+    )
+  })
+
+  // Sum of per-char ratios — verifies the formula without pinning calibration
+  const ratioSum = (text: string) =>
+    [...text].reduce((s, ch) => s + getCharWidth(ch), 0)
+
+  it('handles lowercase text with narrow letters', () => {
+    const width = measureTextWidth('hello', fontSize, fontWeight)
+    expect(width).toBeCloseTo(
+      ratioSum('hello') * fontSize * baseRatio + minPadding,
+      1,
+    )
+  })
+
+  it('narrow text is narrower than uniform estimate', () => {
+    // "illiterate" has many narrow chars (i, l, t)
+    const narrow = measureTextWidth('illicit', fontSize, fontWeight)
+    const uniform = 'illicit'.length * fontSize * baseRatio
+    expect(narrow).toBeLessThan(uniform)
+  })
+
+  it('wide text is wider than uniform estimate', () => {
+    // "MAMMOTH" has wide chars (M, A, O)
+    const wide = measureTextWidth('MAMMOTH', fontSize, fontWeight)
+    const uniform = 'MAMMOTH'.length * fontSize * baseRatio
+    expect(wide).toBeGreaterThan(uniform)
+  })
+
+  it('handles mixed Latin text', () => {
+    const width = measureTextWidth('Will', fontSize, fontWeight)
+    expect(width).toBeCloseTo(
+      ratioSum('Will') * fontSize * baseRatio + minPadding,
+      1,
+    )
+  })
+
+  it('handles spaces correctly', () => {
+    const width = measureTextWidth('a b', fontSize, fontWeight)
+    expect(width).toBeCloseTo(
+      ratioSum('a b') * fontSize * baseRatio + minPadding,
+      1,
+    )
+  })
+
+  it('handles decomposed accents (base + combining mark)', () => {
+    // "café" with decomposed é = c + a + f + e + combining accent
+    // Should be same width as "cafe" since combining mark is zero-width
+    const decomposed = 'cafe\u0301' // e + combining acute
+    const precomposed = 'café'
+    const widthDecomposed = measureTextWidth(decomposed, fontSize, fontWeight)
+    const widthPrecomposed = measureTextWidth(precomposed, fontSize, fontWeight)
+    expect(widthDecomposed).toBeCloseTo(widthPrecomposed, 1)
+  })
+
+  it('handles CJK text', () => {
+    // "中国" = 2 chars × 2.0 width = 4.0
+    const width = measureTextWidth('中国', fontSize, fontWeight)
+    expect(width).toBeCloseTo(4.0 * fontSize * baseRatio + minPadding, 1)
+  })
+
+  it('handles mixed Latin and CJK', () => {
+    const width = measureTextWidth('Hello中国', fontSize, fontWeight)
+    expect(width).toBeCloseTo(
+      ratioSum('Hello中国') * fontSize * baseRatio + minPadding,
+      1,
+    )
+  })
+
+  it('heavier weights produce wider estimates', () => {
+    const regular = measureTextWidth('Test', fontSize, 400)
+    const medium = measureTextWidth('Test', fontSize, 500)
+    const bold = measureTextWidth('Test', fontSize, 600)
+
+    expect(medium).toBeGreaterThan(regular)
+    expect(bold).toBeGreaterThan(medium)
+  })
+
+  it('scales with font size', () => {
+    const small = measureTextWidth('Test', 11, fontWeight)
+    const large = measureTextWidth('Test', 16, fontWeight)
+
+    expect(large).toBeGreaterThan(small)
+    expect(large / small).toBeCloseTo(16 / 11, 1)
+  })
+})
+
+// ============================================================================
+// Calibration against real Inter metrics
+// ============================================================================
+//
+// Fixtures measured with canvas measureText in headless Chrome 138 with the
+// real Inter font loaded (400 weight, 11px — the edge-label spec). If the
+// estimator underestimates these, edge-label text overflows its 8px-padded
+// background rect; if it grossly overestimates, layout gets bloated.
+
+describe('calibration against real Inter widths (11px, weight 400)', () => {
+  const REAL_INTER_WIDTHS: Record<string, number> = {
+    yes: 18.19,
+    no: 13.09,
+    'on failure': 48.47,
+    'validates credentials': 106.56,
+    'sends confirmation email': 130.6,
+    'asynchronous message processing': 184.1,
+    'returns HTTP 401 Unauthorized response': 215.65,
+    'WRITES TO DATABASE': 119.44,
+    'user_id + session_token validation': 177.51,
+    'retry with exponential backoff (max 5)': 197.49,
+  }
+
+  it('never underestimates real width by more than 3%', () => {
+    for (const [text, real] of Object.entries(REAL_INTER_WIDTHS)) {
+      const est = measureTextWidth(text, 11, 400)
+      expect(
+        est,
+        `"${text}" est ${est.toFixed(1)} vs real ${real}`,
+      ).toBeGreaterThanOrEqual(real * 0.97)
+    }
+  })
+
+  it('never overestimates real width by more than 12% + 3px', () => {
+    for (const [text, real] of Object.entries(REAL_INTER_WIDTHS)) {
+      const est = measureTextWidth(text, 11, 400)
+      expect(
+        est,
+        `"${text}" est ${est.toFixed(1)} vs real ${real}`,
+      ).toBeLessThanOrEqual(real * 1.12 + 3)
+    }
+  })
+
+  it('preserves at least 6px of the nominal 8px edge-label padding per side', () => {
+    // Edge-label background rect = estimated width + 8px padding each side.
+    // The visible gap between glyphs and rect wall must stay close to 8px.
+    const EDGE_LABEL_PADDING = 8
+    for (const [text, real] of Object.entries(REAL_INTER_WIDTHS)) {
+      const est = measureTextWidth(text, 11, 400)
+      const gapPerSide = (est + EDGE_LABEL_PADDING * 2 - real) / 2
+      expect(
+        gapPerSide,
+        `"${text}" gap ${gapPerSide.toFixed(1)}px`,
+      ).toBeGreaterThanOrEqual(6)
+    }
+  })
+})
+
+// ============================================================================
+// Real-world examples
+// ============================================================================
+
+describe('real-world text examples', () => {
+  const fontSize = 13
+  const fontWeight = 500
+
+  it('handles typical node labels', () => {
+    const labels = ['User', 'Database', 'API Gateway', 'Load Balancer']
+    for (const label of labels) {
+      const width = measureTextWidth(label, fontSize, fontWeight)
+      expect(width).toBeGreaterThan(0)
+      // Width should be reasonable (not too small or too large)
+      expect(width).toBeGreaterThan(label.length * 3)
+      expect(width).toBeLessThan(label.length * 15)
+    }
+  })
+
+  it('handles Japanese labels', () => {
+    const width = measureTextWidth('データベース', fontSize, fontWeight)
+    // 6 CJK chars × 2.0 × 13 × 0.57 + minPadding
+    const baseRatio = 0.57
+    const minPadding = fontSize * 0.15
+    expect(width).toBeCloseTo(6 * 2.0 * fontSize * baseRatio + minPadding, 1)
+  })
+
+  it('handles Hungarian text with accents', () => {
+    const width = measureTextWidth('Üdvözöljük', fontSize, fontWeight)
+    expect(width).toBeGreaterThan(0)
+    // Should be similar to unaccented version (within 5% difference)
+    const unaccented = measureTextWidth('Udvozoljuk', fontSize, fontWeight)
+    const percentDiff = Math.abs(width - unaccented) / unaccented
+    expect(percentDiff).toBeLessThan(0.05)
+  })
+})
+
+// ============================================================================
+// isWideChar — shared wide-character detection (used by the ASCII grid's
+// display-width helpers in src/ascii/display-width.ts)
+// ============================================================================
+
+describe('isWideChar', () => {
+  it('returns true for CJK ideographs, kana, and hangul', () => {
+    expect(isWideChar('日')).toBe(true)
+    expect(isWideChar('本')).toBe(true)
+    expect(isWideChar('語')).toBe(true)
+    expect(isWideChar('テ')).toBe(true) // katakana
+    expect(isWideChar('あ')).toBe(true) // hiragana
+    expect(isWideChar('한')).toBe(true) // hangul syllable
+  })
+
+  it('returns true for fullwidth-form characters', () => {
+    expect(isWideChar('Ａ')).toBe(true) // fullwidth Latin A (U+FF21)
+    expect(isWideChar('１')).toBe(true) // fullwidth digit 1 (U+FF11)
+  })
+
+  it('returns true for emoji', () => {
+    expect(isWideChar('😀')).toBe(true)
+    expect(isWideChar('🎉')).toBe(true)
+  })
+
+  it('returns false for ASCII letters, digits, and punctuation', () => {
+    expect(isWideChar('A')).toBe(false)
+    expect(isWideChar('a')).toBe(false)
+    expect(isWideChar('1')).toBe(false)
+    expect(isWideChar(' ')).toBe(false)
+    expect(isWideChar('.')).toBe(false)
+  })
+
+  it('returns false for accented Latin characters', () => {
+    expect(isWideChar('Ü')).toBe(false)
+    expect(isWideChar('é')).toBe(false)
+  })
+
+  it('returns false for arrowhead and box-drawing glyphs used by the ASCII renderer', () => {
+    // These are Extended_Pictographic (emoji-capable) but have no default
+    // Emoji_Presentation and render as a single narrow column in every real
+    // terminal. Regression test for the ▶ (U+25B6) misclassification —
+    // used as the sequence-diagram arrowhead in src/ascii/sequence.ts.
+    expect(isWideChar('▶')).toBe(false) // solid ->> / -->> arrowhead
+    expect(isWideChar('◀')).toBe(false) // solid self-message loop arrowhead
+    expect(isWideChar('▼')).toBe(false)
+    expect(isWideChar('▲')).toBe(false)
+    expect(isWideChar('◄')).toBe(false)
+    expect(isWideChar('►')).toBe(false)
+    expect(isWideChar('◁')).toBe(false)
+    expect(isWideChar('▷')).toBe(false)
+    expect(isWideChar('◢')).toBe(false)
+    expect(isWideChar('◣')).toBe(false)
+    expect(isWideChar('◤')).toBe(false)
+    expect(isWideChar('◥')).toBe(false)
+    expect(isWideChar('○')).toBe(false)
+    expect(isWideChar('✕')).toBe(false)
+    // Diagonal edge-routing arrowheads (draw-arrows.ts's drawArrowHead) as
+    // of issue #1062 — JetBrains Mono NL has no glyph for the ◢◣◤◥ set
+    // above, so these Arrows-block glyphs are drawn instead.
+    expect(isWideChar('↖')).toBe(false)
+    expect(isWideChar('↗')).toBe(false)
+    expect(isWideChar('↘')).toBe(false)
+    expect(isWideChar('↙')).toBe(false)
+    // Same Arrows-block misclassification, not drawn by the renderer itself
+    // but reachable if typed into node/edge/note label text.
+    expect(isWideChar('↔')).toBe(false)
+    expect(isWideChar('↕')).toBe(false)
+    expect(isWideChar('↩')).toBe(false)
+    expect(isWideChar('↪')).toBe(false)
+  })
+})

package/src/__tests__/theme-palette-contrast.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Guards the "legible, readable contrast" acceptance criterion the #684
+ * theme-selector restoration's 16 per-theme verification sub-issues
+ * (#691-706) each individually ask for, systematically across every
+ * built-in theme at once rather than eyeballing 16 screenshots one at a
+ * time — see docs/decisions/theme-selector-shared-state.md and this
+ * repo's CLAUDE.md's "favor tooling over manual scanning" convention.
+ *
+ * Computes the actual WCAG 2.x contrast ratio (relative luminance, per
+ * https://www.w3.org/TR/WCAG21/#dfn-relative-luminance) between each
+ * theme's `bg`/`fg` pair — not a hand-picked pass/fail per theme, so a
+ * future THEMES addition with a genuinely illegible pair fails this test
+ * automatically instead of only being caught by a human noticing a
+ * screenshot looks wrong.
+ */
+import { describe, it, expect } from 'vitest'
+import { THEMES } from '@zombie-mermaid/core'
+
+/**
+ * The threshold every theme must clear. WCAG AA's own thresholds are 4.5:1
+ * for normal text and 3:1 for large/bold text; diagram node labels here
+ * are typically medium, semi-bold text, closer to the "large text"
+ * category than dense body copy. 4.0 sits between the two -- strict enough
+ * to catch a genuinely illegible pair, loose enough not to fail
+ * `solarized-light` (4.13:1), whose muted bg/fg pair matches Ethan
+ * Schoonover's actual published Solarized values rather than being a
+ * mistake in this repo's THEMES data -- #684's own non-goals rule out
+ * changing THEMES' colors to "fix" a curated editor-theme's real values.
+ */
+const MIN_CONTRAST_RATIO = 4.0
+
+function hexToRgb(hex: string): [number, number, number] {
+  const clean = hex.replace('#', '')
+  return [
+    parseInt(clean.slice(0, 2), 16),
+    parseInt(clean.slice(2, 4), 16),
+    parseInt(clean.slice(4, 6), 16),
+  ]
+}
+
+/** sRGB channel -> linear-light value, the WCAG relative-luminance step. */
+function linearize(channel: number): number {
+  const c = channel / 255
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+}
+
+function relativeLuminance(hex: string): number {
+  const [r, g, b] = hexToRgb(hex)
+  return 0.2126 * linearize(r) + 0.7152 * linearize(g) + 0.0722 * linearize(b)
+}
+
+/** WCAG contrast ratio between two colors, always >= 1 (order-independent). */
+function contrastRatio(hexA: string, hexB: string): number {
+  const lumA = relativeLuminance(hexA)
+  const lumB = relativeLuminance(hexB)
+  const lighter = Math.max(lumA, lumB)
+  const darker = Math.min(lumA, lumB)
+  return (lighter + 0.05) / (darker + 0.05)
+}
+
+describe('every built-in theme has a legible bg/fg contrast ratio', () => {
+  for (const [themeKey, colors] of Object.entries(THEMES)) {
+    it(`${themeKey}: bg/fg contrast is at least ${MIN_CONTRAST_RATIO}:1`, () => {
+      const ratio = contrastRatio(colors.bg, colors.fg)
+      expect(ratio).toBeGreaterThanOrEqual(MIN_CONTRAST_RATIO)
+    })
+  }
+})
+
+describe('contrastRatio() itself', () => {
+  it('returns 1 for identical colors', () => {
+    expect(contrastRatio('#808080', '#808080')).toBeCloseTo(1, 5)
+  })
+
+  it('returns 21 for pure black vs pure white (the WCAG maximum)', () => {
+    expect(contrastRatio('#000000', '#FFFFFF')).toBeCloseTo(21, 1)
+  })
+
+  it('is symmetric regardless of argument order', () => {
+    const a = contrastRatio('#1a1b26', '#a9b1d6')
+    const b = contrastRatio('#a9b1d6', '#1a1b26')
+    expect(a).toBeCloseTo(b, 10)
+  })
+})