@linktr.ee/messaging-react 3.24.2-rc-1785436624 → 3.25.0-rc-1785440433

package/src/components/LinkAttachment/components/_shared/accentSurface.ts

@@ -0,0 +1,211 @@
+/**
+ * Turns the colour extracted from an attachment image into a card surface that
+ * the card's own text can survive.
+ *
+ * `ugc-kit`'s `ImageAnalysis` (`getDominantColorFromImageUrl`) answers only
+ * "what colour is this image?" — it has no notion of contrast or readability.
+ * Painting that colour straight onto the card is what broke: the extracted
+ * colour is whatever the photo happened to be, so roughly half of them left the
+ * title illegible against the side's ink, and refusing those threw away the
+ * colour the feature exists to add (MES-1349, MES-1388).
+ *
+ * So the hue is kept and the *lightness* is replaced with a fixed stop chosen
+ * per side — dark behind the sender's white ink, pale behind the receiver's
+ * near-black. This is the approach already used in `linktr.ee-profiles`
+ * (`ui/src/utils/rgbToTheme.ts`), whose `getPaletteFromColor` generates a
+ * 16-stop OKLCH ramp from one colour and has callers pick a background stop and
+ * a text stop from it. We need exactly one stop per side rather than a whole
+ * theme, so the ramp is collapsed to a single lightness target.
+ *
+ * OKLCH rather than HSL because its lightness axis is perceptually uniform: one
+ * L value gives the same *apparent* lightness — and therefore the same contrast
+ * — across every hue. In HSL, `50%` lightness yellow and `50%` blue differ by
+ * several stops of contrast, so no single target would hold.
+ *
+ * The conversion maths is ported from that same profiles module rather than
+ * invented here; the toolkit has no colour dependency and adding one for two
+ * matrix multiplies is not worth the install.
+ */
+import type { LinkAttachmentVariant } from './CardShell'
+import {
+  contrastRatio,
+  INK_ON_DARK,
+  INK_ON_LIGHT,
+  WCAG_AA_NORMAL_TEXT,
+} from './chinContrast'
+
+/**
+ * Perceived-lightness stop each side paints at, in OKLCH L (0..1) — profiles'
+ * `color12` / `color2` equivalent. Both sit far enough from their ink to clear
+ * AA at any hue and chroma: swept across 72 hues at maximum chroma the worst
+ * case is 13.17:1 sent and 14.72:1 received, against a 4.5:1 floor.
+ */
+const SURFACE_LIGHTNESS: Record<LinkAttachmentVariant, number> = {
+  dark: 0.3,
+  light: 0.9,
+}
+
+/** Ink each side draws, so the derived surface can be checked against it. */
+const INK_BY_VARIANT: Record<LinkAttachmentVariant, string> = {
+  dark: INK_ON_DARK,
+  light: INK_ON_LIGHT,
+}
+
+const SHORT_HEX_LENGTH = 3
+const HEX_PATTERN = /^#?(?:[0-9a-f]{3}|[0-9a-f]{6})$/i
+
+/** Channels are allowed a half-step outside 0..255 before rounding clips them. */
+const GAMUT_EPSILON = 0.5
+/** Bisection steps for the chroma search — 25 resolves well past 8-bit output. */
+const GAMUT_STEPS = 25
+
+type Rgb = [number, number, number]
+
+function parseHex(hex: string): Rgb | undefined {
+  if (typeof hex !== 'string' || !HEX_PATTERN.test(hex.trim())) return undefined
+
+  const digits = hex.trim().replace(/^#/, '')
+  const expanded =
+    digits.length === SHORT_HEX_LENGTH
+      ? digits.replace(/./g, (digit) => digit + digit)
+      : digits
+
+  return [
+    Number.parseInt(expanded.slice(0, 2), 16),
+    Number.parseInt(expanded.slice(2, 4), 16),
+    Number.parseInt(expanded.slice(4, 6), 16),
+  ]
+}
+
+function toHex(rgb: Rgb): string {
+  return `#${rgb
+    .map((channel) =>
+      Math.round(Math.min(255, Math.max(0, channel)))
+        .toString(16)
+        .padStart(2, '0')
+    )
+    .join('')}`
+}
+
+/** sRGB transfer function and its inverse (gamma <-> linear light). */
+function gammaToLinear(channel: number): number {
+  return channel <= 0.04045
+    ? channel / 12.92
+    : ((channel + 0.055) / 1.055) ** 2.4
+}
+
+function linearToGamma(channel: number): number {
+  return channel <= 0.0031308
+    ? 12.92 * channel
+    : 1.055 * channel ** (1 / 2.4) - 0.055
+}
+
+/** sRGB -> OKLCH, as `[lightness, chroma, hue degrees]`. */
+function rgbToOklch(rgb: Rgb): [number, number, number] {
+  const red = gammaToLinear(rgb[0] / 255)
+  const green = gammaToLinear(rgb[1] / 255)
+  const blue = gammaToLinear(rgb[2] / 255)
+
+  const long = Math.cbrt(
+    0.4122214708 * red + 0.5363325363 * green + 0.0514459929 * blue
+  )
+  const medium = Math.cbrt(
+    0.2119034982 * red + 0.6806995451 * green + 0.1073969566 * blue
+  )
+  const short = Math.cbrt(
+    0.0883024619 * red + 0.2817188376 * green + 0.6299787005 * blue
+  )
+
+  const lightness =
+    0.2104542553 * long + 0.793617785 * medium - 0.0040720468 * short
+  const a = 1.9779984951 * long - 2.428592205 * medium + 0.4505937099 * short
+  const b = 0.0259040371 * long + 0.7827717662 * medium - 0.808675766 * short
+
+  return [
+    lightness,
+    Math.hypot(a, b),
+    ((Math.atan2(b, a) * 180) / Math.PI + 360) % 360,
+  ]
+}
+
+/** OKLCH -> sRGB. Channels may land outside 0..255 when out of gamut. */
+function oklchToRgb([lightness, chroma, hue]: [number, number, number]): Rgb {
+  const radians = (hue * Math.PI) / 180
+  const a = chroma * Math.cos(radians)
+  const b = chroma * Math.sin(radians)
+
+  const long = (lightness + 0.3963377774 * a + 0.2158037573 * b) ** 3
+  const medium = (lightness - 0.1055613458 * a - 0.0638541728 * b) ** 3
+  const short = (lightness - 0.0894841775 * a - 1.291485548 * b) ** 3
+
+  return [
+    255 *
+      linearToGamma(
+        4.0767416621 * long - 3.3077115913 * medium + 0.2309699292 * short
+      ),
+    255 *
+      linearToGamma(
+        -1.2684380046 * long + 2.6097574011 * medium - 0.3413193965 * short
+      ),
+    255 *
+      linearToGamma(
+        -0.0041960863 * long - 0.7034186147 * medium + 1.707614701 * short
+      ),
+  ]
+}
+
+function isInGamut(rgb: Rgb): boolean {
+  return rgb.every(
+    (channel) => channel >= -GAMUT_EPSILON && channel <= 255 + GAMUT_EPSILON
+  )
+}
+
+/**
+ * The card surface for an extracted colour: the image's hue at this side's
+ * lightness stop, or `undefined` when there was no colour to work from.
+ *
+ * Chroma is reduced — never the hue — when the requested lightness puts the
+ * colour outside sRGB, which is what stops a saturated yellow or green from
+ * clipping into a different colour on the way to 8-bit output. Vivid hues
+ * therefore desaturate rather than shift.
+ *
+ * The AA check at the end is a guard, not a branch anyone expects to take: the
+ * lightness stops were chosen to clear it everywhere. It exists so that a future
+ * change to `SURFACE_LIGHTNESS` or to the ink cannot quietly reintroduce an
+ * illegible card — it degrades to the plain bubble fill instead.
+ */
+export function accentSurface(
+  accentColor: string | undefined,
+  variant: LinkAttachmentVariant
+): string | undefined {
+  if (accentColor == null) return undefined
+
+  const rgb = parseHex(accentColor)
+  if (!rgb) return undefined
+
+  const [, extractedChroma, hue] = rgbToOklch(rgb)
+  const lightness = SURFACE_LIGHTNESS[variant]
+
+  let chroma = 0
+  if (isInGamut(oklchToRgb([lightness, extractedChroma, hue]))) {
+    chroma = extractedChroma
+  } else {
+    // Largest chroma that still fits sRGB at this lightness and hue.
+    let low = 0
+    let high = extractedChroma
+    for (let step = 0; step < GAMUT_STEPS; step++) {
+      const middle = (low + high) / 2
+      if (isInGamut(oklchToRgb([lightness, middle, hue]))) {
+        chroma = middle
+        low = middle
+      } else {
+        high = middle
+      }
+    }
+  }
+
+  const surface = toHex(oklchToRgb([lightness, chroma, hue]))
+  return contrastRatio(surface, INK_BY_VARIANT[variant]) >= WCAG_AA_NORMAL_TEXT
+    ? surface
+    : undefined
+}

package/src/components/LinkAttachment/components/_shared/chinContrast.test.ts

@@ -1,162 +1,102 @@
 import { describe, expect, it } from 'vitest'
 
+import { AUDIO_BG, AUDIO_BG_CLASS } from './CardThumbnail'
 import {
-  CHIN_FALLBACK_BG,
-  CHIN_TEXT_DARK,
-  CHIN_TEXT_LIGHT,
-  WCAG_AA_NORMAL_TEXT,
-  chinTextColor,
+  BUBBLE_BG_BY_VARIANT,
   contrastRatio,
-  paintableAccent,
+  inkFor,
+  INK_ON_DARK,
+  INK_ON_LIGHT,
   relativeLuminance,
+  WCAG_AA_NORMAL_TEXT,
 } from './chinContrast'
 
 describe('relativeLuminance', () => {
-  it('anchors the sRGB endpoints', () => {
-    expect(relativeLuminance('#FFFFFF')).toBeCloseTo(1, 10)
-    expect(relativeLuminance('#000000')).toBeCloseTo(0, 10)
-  })
-
-  it('applies gamma expansion rather than a linear average', () => {
-    // Mid-grey is ~21.6% luminance, not 50% — a Rec. 601 style weighted
-    // average (the trap the app-local helpers fall into) would say ~0.5.
-    expect(relativeLuminance('#808080')).toBeCloseTo(0.2159, 4)
-  })
-
-  it('weights green above red above blue', () => {
-    expect(relativeLuminance('#00FF00')).toBeCloseTo(0.7152, 4)
-    expect(relativeLuminance('#FF0000')).toBeCloseTo(0.2126, 4)
-    expect(relativeLuminance('#0000FF')).toBeCloseTo(0.0722, 4)
+  it('anchors on the sRGB endpoints', () => {
+    expect(relativeLuminance('#ffffff')).toBeCloseTo(1, 5)
+    expect(relativeLuminance('#000000')).toBeCloseTo(0, 5)
   })
 
-  it('accepts shorthand hex and a missing leading hash', () => {
-    expect(relativeLuminance('#fff')).toBe(relativeLuminance('#FFFFFF'))
-    expect(relativeLuminance('738883')).toBe(relativeLuminance('#738883'))
+  it('accepts short hex and a missing leading hash', () => {
+    expect(relativeLuminance('#fff')).toBeCloseTo(1, 5)
+    expect(relativeLuminance('ffffff')).toBeCloseTo(1, 5)
+    expect(relativeLuminance('  #fff  ')).toBeCloseTo(1, 5)
   })
 
-  it('returns NaN for unparseable input', () => {
-    for (const bad of ['', '#', '#12', '#12345', '#gggggg', 'rebeccapurple']) {
-      expect(relativeLuminance(bad)).toBeNaN()
+  it('reports NaN for anything unparseable', () => {
+    for (const input of ['', '#ff', '#gggggg', 'rebeccapurple', '#ffffff00']) {
+      expect(relativeLuminance(input)).toBeNaN()
     }
   })
 })
 
 describe('contrastRatio', () => {
-  it('is 21:1 for black on white and 1:1 for a colour on itself', () => {
-    expect(contrastRatio('#000000', '#FFFFFF')).toBeCloseTo(21, 10)
-    expect(contrastRatio('#738883', '#738883')).toBeCloseTo(1, 10)
+  it('matches the WCAG maximum for black on white', () => {
+    expect(contrastRatio('#000000', '#ffffff')).toBeCloseTo(21, 2)
   })
 
-  it('is symmetric in its arguments', () => {
-    expect(contrastRatio('#738883', CHIN_TEXT_LIGHT)).toBe(
-      contrastRatio(CHIN_TEXT_LIGHT, '#738883')
+  it('is symmetric and self-referential', () => {
+    expect(contrastRatio('#1e2330', '#ffffff')).toBeCloseTo(
+      contrastRatio('#ffffff', '#1e2330'),
+      5
     )
+    expect(contrastRatio('#1e2330', '#1e2330')).toBeCloseTo(1, 5)
   })
 
-  it('returns NaN when either input is unparseable', () => {
-    expect(contrastRatio('nope', '#FFFFFF')).toBeNaN()
-    expect(contrastRatio('#FFFFFF', 'nope')).toBeNaN()
+  it('propagates NaN when either side is unparseable', () => {
+    expect(contrastRatio('nope', '#ffffff')).toBeNaN()
+    expect(contrastRatio('#ffffff', 'nope')).toBeNaN()
   })
 })
 
-describe('chinTextColor', () => {
-  it('picks dark text on light accents', () => {
-    // #738883 is the Figma mock's own chin colour, where white measures
-    // 3.76:1 and therefore fails AA — the rule deliberately flips it.
-    expect(chinTextColor('#738883')).toBe(CHIN_TEXT_DARK)
-    expect(chinTextColor('#AA9F93')).toBe(CHIN_TEXT_DARK)
-    expect(chinTextColor('#FFF099')).toBe(CHIN_TEXT_DARK)
-    expect(chinTextColor('#FFFFFF')).toBe(CHIN_TEXT_DARK)
-  })
-
-  it('picks light text on dark accents', () => {
-    expect(chinTextColor(CHIN_FALLBACK_BG)).toBe(CHIN_TEXT_LIGHT)
-    expect(chinTextColor('#7008E7')).toBe(CHIN_TEXT_LIGHT)
-    expect(chinTextColor('#000000')).toBe(CHIN_TEXT_LIGHT)
-  })
-
-  it('falls back to light text for missing or malformed input', () => {
-    expect(chinTextColor()).toBe(CHIN_TEXT_LIGHT)
-    expect(chinTextColor(undefined)).toBe(CHIN_TEXT_LIGHT)
-    expect(chinTextColor('')).toBe(CHIN_TEXT_LIGHT)
-    expect(chinTextColor('#12345')).toBe(CHIN_TEXT_LIGHT)
-    expect(chinTextColor('teal')).toBe(CHIN_TEXT_LIGHT)
-  })
-
-  it('clears AA for every accent, including the greys either side of the crossover', () => {
-    // The invariant, not the individual verdicts: whichever colour the rule
-    // returns must clear 4.5:1. `#767676` is the tightest point on the grey
-    // axis (4.54 vs 4.52) and #737373 / #797979 straddle it.
-    const accents = [
-      '#738883',
-      '#AA9F93',
-      CHIN_FALLBACK_BG,
-      '#767676',
-      '#737373',
-      '#797979',
-      '#FFFFFF',
-      '#000000',
-      '#FF0000',
-      '#00FF00',
-      '#0000FF',
-      '#FFF099',
-      '#7008E7',
-      '#F2F1EF',
-      '#121110',
-    ]
-
-    for (const accent of accents) {
-      expect(
-        contrastRatio(accent, chinTextColor(accent))
-      ).toBeGreaterThanOrEqual(WCAG_AA_NORMAL_TEXT)
+describe('the fallback fills stay legible', () => {
+  it('clears AA on both sides, so a card with no accent is always readable', () => {
+    for (const variant of ['dark', 'light'] as const) {
+      const fill = BUBBLE_BG_BY_VARIANT[variant]
+      const ink = inkFor(fill)
+      expect(ink).toBeDefined()
+      expect(contrastRatio(fill, ink as string)).toBeGreaterThanOrEqual(
+        WCAG_AA_NORMAL_TEXT
+      )
     }
   })
 
-  it('clears AA across the whole gamut at 17-step granularity', () => {
-    const steps = [0, 17, 51, 85, 119, 136, 170, 204, 238, 255]
-    const hex = (value: number) => value.toString(16).padStart(2, '0')
-
-    for (const r of steps) {
-      for (const g of steps) {
-        for (const b of steps) {
-          const accent = `#${hex(r)}${hex(g)}${hex(b)}`
-          expect(
-            contrastRatio(accent, chinTextColor(accent))
-          ).toBeGreaterThanOrEqual(WCAG_AA_NORMAL_TEXT)
-        }
-      }
-    }
+  it('uses the plain message bubble fills', () => {
+    // Keep in sync with `--str-chat__own-message-bubble-background-color` and
+    // `--str-chat__message-bubble-background-color` in styles.css.
+    expect(BUBBLE_BG_BY_VARIANT).toEqual({
+      dark: '#1e2330',
+      light: '#f1f0ee',
+    })
   })
+})
 
-  it('pairs the fallback chin with light text at 15.69:1', () => {
-    expect(contrastRatio(CHIN_FALLBACK_BG, chinTextColor())).toBeCloseTo(
-      15.69,
-      2
-    )
+describe('inkFor', () => {
+  it('inks a dark surface light and a light surface dark', () => {
+    expect(inkFor('#1e2330')).toBe(INK_ON_DARK)
+    expect(inkFor('#f1f0ee')).toBe(INK_ON_LIGHT)
   })
-})
 
-describe('paintableAccent', () => {
-  it('passes through anything parseable', () => {
-    expect(paintableAccent('#738883')).toBe('#738883')
-    expect(paintableAccent('#fff')).toBe('#fff')
+  it('inks the audio strip dark, which is the MES-1388 regression', () => {
+    // `AUDIO_BG_CLASS` is imposed on the shell of any variant, so a sent audio
+    // card drew the dark variant's white ink on near-white at ~1.13:1.
+    expect(contrastRatio(AUDIO_BG, INK_ON_DARK)).toBeLessThan(
+      WCAG_AA_NORMAL_TEXT
+    )
+    const ink = inkFor(AUDIO_BG)
+    expect(ink).toBe(INK_ON_LIGHT)
+    expect(contrastRatio(AUDIO_BG, ink as string)).toBeGreaterThanOrEqual(
+      WCAG_AA_NORMAL_TEXT
+    )
   })
 
-  it('adds the leading hash that CSS requires when the input omits it', () => {
-    // `parseHex` accepts a hashless value, `background-color: 738883` is
-    // invalid CSS and gets dropped, and `chinTextColor` resolves against the
-    // parsed colour regardless — so the two would disagree about what the
-    // chin is sitting on. Normalizing on the way out keeps them in step.
-    expect(paintableAccent('738883')).toBe('#738883')
-    expect(paintableAccent('fff')).toBe('#fff')
-    expect(paintableAccent('  738883  ')).toBe('#738883')
-    expect(paintableAccent(' #738883 ')).toBe('#738883')
+  it('keeps the audio hex and its tailwind class in step', () => {
+    // Tailwind only emits utilities it can find as complete literals, so the
+    // class cannot be built from the constant — hence the pair.
+    expect(AUDIO_BG_CLASS).toBe(`bg-[${AUDIO_BG}]`)
   })
 
-  it('drops absent and malformed accents so callers fall back', () => {
-    expect(paintableAccent()).toBeUndefined()
-    expect(paintableAccent('')).toBeUndefined()
-    expect(paintableAccent('#12345')).toBeUndefined()
-    expect(paintableAccent('rgb(1,2,3)')).toBeUndefined()
+  it('has no ink for an unparseable surface', () => {
+    expect(inkFor('rebeccapurple')).toBeUndefined()
   })
 })

package/src/components/LinkAttachment/components/_shared/chinContrast.ts

@@ -1,31 +1,47 @@
 /**
- * WCAG contrast arithmetic for the `LinkAttachment` card "chin" — the bottom
- * bar holding the title + URL, painted with a dominant colour extracted from
- * the attachment image.
+ * WCAG contrast arithmetic for the `LinkAttachment` card, whose background is a
+ * dominant colour extracted from the attachment image
+ * (`getDominantColorFromImageUrl`, via `ugc-kit`'s `ImageAnalysis`).
  *
- * Nothing here touches React or the DOM: given an accent hex it answers which
- * of the two design-system text colours to draw on it. Deliberately dependency
- * free — neither `@linktr.ee/design-tokens` nor the `@linktr.ee/component-library`
+ * The colour exists to make links visually distinguishable and to put something
+ * other than grey/blue in the message window. It is decoration, so it is only
+ * allowed to paint when the card's text stays legible on it: each side draws a
+ * *fixed* ink colour, and an accent that cannot clear AA against that ink is
+ * discarded in favour of the plain bubble fill. Contrast gates the accent here;
+ * it does not pick the text colour. An earlier revision did the opposite —
+ * it kept every parseable accent and flipped the text between white and
+ * near-black to suit it — which meant the accent could never be rejected, and
+ * a sent link and its received twin drew different ink from the surrounding
+ * conversation (MES-1388).
+ *
+ * Nothing here touches React or the DOM. Deliberately dependency free —
+ * neither `@linktr.ee/design-tokens` nor the `@linktr.ee/component-library`
  * tailwind preset ships a luminance or contrast helper, and the app-local
  * `getRelativeLuminance` in `mfe-appearance` thresholds on luminance > 0.5
  * rather than computing a ratio (and is unreachable from the toolkit anyway).
  */
+import type { LinkAttachmentVariant } from './CardShell'
 
-/** Text candidate for dark accents. */
-export const CHIN_TEXT_LIGHT = '#FFFFFF'
-/** Text candidate for light accents — the near-black used across the Figma frames. */
-export const CHIN_TEXT_DARK = '#040403'
-/**
- * Chin fill used whenever no accent is paintable. Matches the `shade` colour
- * token in the component-library tailwind preset (and therefore the card's
- * pre-MES-1349 background), so the fallback is visually a no-op.
- */
-export const CHIN_FALLBACK_BG = '#1e2330'
 /** WCAG 2.1 SC 1.4.3 (AA), normal text. Both chin lines are normal text. */
 export const WCAG_AA_NORMAL_TEXT = 4.5
 
-const SHORT_HEX_LENGTH = 3
+/**
+ * Fill each side falls back to when no accent is paintable: the plain message
+ * bubble's own background, so a link card without a usable colour is indistinct
+ * from the text bubbles around it rather than a third colour nobody chose.
+ *
+ * These are the literal values behind `--str-chat__own-message-bubble-background-color`
+ * and `--str-chat__message-bubble-background-color` in `styles.css`. Duplicated
+ * as hex because the bubble tail paints *outside* the shell's box via an inline
+ * style, and the contrast arithmetic below needs channels, not a `var()`.
+ * Keep in sync with those two custom properties.
+ */
+export const BUBBLE_BG_BY_VARIANT: Record<LinkAttachmentVariant, string> = {
+  dark: '#1e2330',
+  light: '#f1f0ee',
+}
 
+const SHORT_HEX_LENGTH = 3
 /** `#abc`, `#aabbcc`, or either without the leading `#`. */
 const HEX_PATTERN = /^#?(?:[0-9a-f]{3}|[0-9a-f]{6})$/i
 
@@ -51,6 +67,14 @@ function linearize(channel: number): number {
   return scaled <= 0.03928 ? scaled / 12.92 : ((scaled + 0.055) / 1.055) ** 2.4
 }
 
+function luminanceOfRgb(rgb: [number, number, number]): number {
+  return (
+    0.2126 * linearize(rgb[0]) +
+    0.7152 * linearize(rgb[1]) +
+    0.0722 * linearize(rgb[2])
+  )
+}
+
 /**
  * WCAG 2.1 relative luminance of an sRGB hex colour, 0..1.
  * Returns `NaN` for anything unparseable so callers can branch on
@@ -59,69 +83,42 @@ function linearize(channel: number): number {
 export function relativeLuminance(hex: string): number {
   const rgb = parseHex(hex)
   if (!rgb) return Number.NaN
+  return luminanceOfRgb(rgb)
+}
 
-  return (
-    0.2126 * linearize(rgb[0]) +
-    0.7152 * linearize(rgb[1]) +
-    0.0722 * linearize(rgb[2])
-  )
+function ratioOfLuminances(a: number, b: number): number {
+  if (Number.isNaN(a) || Number.isNaN(b)) return Number.NaN
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05)
 }
 
-/**
- * WCAG 2.1 contrast ratio between two hex colours, 1..21. `NaN` when either
- * input is unparseable.
- */
+/** WCAG contrast ratio between two hex colours, or `NaN` if either is unparseable. */
 export function contrastRatio(a: string, b: string): number {
-  const luminanceA = relativeLuminance(a)
-  const luminanceB = relativeLuminance(b)
-  if (Number.isNaN(luminanceA) || Number.isNaN(luminanceB)) return Number.NaN
-
-  const lighter = Math.max(luminanceA, luminanceB)
-  const darker = Math.min(luminanceA, luminanceB)
-
-  return (lighter + 0.05) / (darker + 0.05)
+  return ratioOfLuminances(relativeLuminance(a), relativeLuminance(b))
 }
 
-/**
- * Chin text colour for a given accent: whichever of `CHIN_TEXT_LIGHT` /
- * `CHIN_TEXT_DARK` scores the higher contrast ratio, falling back to
- * `CHIN_TEXT_LIGHT` when the accent is missing or unparseable (which pairs
- * with `CHIN_FALLBACK_BG` at 15.69:1).
- *
- * The rule is total: `CHIN_TEXT_DARK` clears 4.5:1 for every accent whose
- * luminance is >= 0.1804, `CHIN_TEXT_LIGHT` clears it for every accent
- * <= 0.1833, and those ranges overlap — so there is no sRGB colour that
- * fails against both candidates.
- */
-export function chinTextColor(
-  accentColor?: string
-): typeof CHIN_TEXT_LIGHT | typeof CHIN_TEXT_DARK {
-  if (accentColor == null) return CHIN_TEXT_LIGHT
-
-  const againstLight = contrastRatio(accentColor, CHIN_TEXT_LIGHT)
-  if (Number.isNaN(againstLight)) return CHIN_TEXT_LIGHT
-
-  return againstLight >= contrastRatio(accentColor, CHIN_TEXT_DARK)
-    ? CHIN_TEXT_LIGHT
-    : CHIN_TEXT_DARK
-}
+/** Ink candidates for a surface the card cannot refuse. */
+export const INK_ON_DARK = '#FFFFFF'
+/** The near-black used across the Figma frames. */
+export const INK_ON_LIGHT = '#040403'
 
 /**
- * The accent as an actually paintable CSS colour, or `undefined` when there is
- * nothing to paint (absent or unparseable). Single source of truth for
- * "does this card have an accent?" across the shell, hero and chin.
+ * Ink for a surface the card did not choose — the audio strip's flat neutral,
+ * or a variant fallback fill — picking whichever candidate scores the higher
+ * ratio against it. `undefined` when the surface is unparseable, so callers
+ * keep the variant's own `text-*` classes.
  *
- * Normalizes on the way out, because `parseHex` deliberately accepts a missing
- * leading `#` (and surrounding whitespace) and CSS does not. Returned raw,
- * `738883` made the inline shell background and the bubble tail silently
- * invalid while `chinTextColor` still resolved `#040403` against the parsed
- * colour — 1.31:1 near-black on the dark fallback fill, the precise failure
- * this module exists to prevent (MES-1349).
+ * This is the rule the accent gate cannot cover. `AUDIO_BG_CLASS` (`#F2F3F4`)
+ * is imposed on the shell of *any* variant, so a sent audio card drew the
+ * variant's white ink on near-white at 1.13:1 — the title and URL were
+ * invisible, exactly the symptom MES-1388 was reported for, on a second and
+ * unrelated code path to the `bg-shade` regression (both shipped in 3.18.0).
+ * Ink follows the surface it actually lands on; only decoration gets refused.
  */
-export function paintableAccent(accentColor?: string): string | undefined {
-  if (accentColor == null) return undefined
-  if (Number.isNaN(relativeLuminance(accentColor))) return undefined
+export function inkFor(background: string): string | undefined {
+  const againstDarkInk = contrastRatio(background, INK_ON_LIGHT)
+  if (Number.isNaN(againstDarkInk)) return undefined
 
-  const trimmed = accentColor.trim()
-  return trimmed.startsWith('#') ? trimmed : `#${trimmed}`
+  return againstDarkInk >= contrastRatio(background, INK_ON_DARK)
+    ? INK_ON_LIGHT
+    : INK_ON_DARK
 }