@linktr.ee/messaging-react 3.31.1-rc-1785925535 → 3.31.1

package/src/components/LinkAttachment/components/_shared/CardShell.tsx

@@ -35,12 +35,11 @@ export interface CardShellProps {
    */
   bgClassName?: string
   /**
-   * Raw extracted accent colour, published as the `--accent` custom property.
-   * `styles.css` derives the card surface from it in CSS (`oklch(from …)`) and
-   * paints it over the `bg-[…]` fallback where the browser supports it —
-   * MES-1412. `undefined` keeps the variant / `bgClassName` fill.
+   * Inline background for the dynamic accent colour extracted from the
+   * attachment image. Wins over `bgClassName` / the variant default when
+   * set — Tailwind cannot express a runtime hex.
    */
-  accentHex?: string
+  accentStyle?: React.CSSProperties
   /**
    * Locks the card to Figma's 250px box and makes it a flex column, so the
    * hero absorbs whatever height the chin leaves. Only the `featured` layout
@@ -89,21 +88,18 @@ const CardShell: React.FC<CardShellProps> = ({
   rootRef,
   topRight,
   bgClassName,
-  accentHex,
+  accentStyle,
   fixedHeight = false,
   busy = false,
   'data-testid': dataTestId,
 }) => {
   const isInteractive = href != null || onClick != null
   const className = classNames(
-    'messaging-link-card',
     SHELL_CLASS,
     fixedHeight ? FIXED_HEIGHT_CLASS : 'block',
-    // The plain fallback fill, kept underneath the `--accent` derivation: the
-    // `.messaging-link-card[style*='--accent']` rule in `styles.css` outranks
-    // this single class, so a published accent paints over it where the browser
-    // resolves `oklch(from …)`, and an accent that can't (or was never set)
-    // lands on this sane surface.
+    // Kept underneath `accentStyle` rather than swapped out: the inline
+    // background wins on specificity, and leaving the class in place means
+    // an accent that somehow doesn't paint still lands on a sane surface.
     //
     // MUST be an arbitrary value, not a theme token. This package ships no
     // Tailwind utilities — `dist/assets/index.css` is only the hand-written
@@ -119,7 +115,7 @@ const CardShell: React.FC<CardShellProps> = ({
     // usable accent matches the text bubbles around it: `#1e2330` is
     // `--str-chat__own-message-bubble-background-color` and `#f1f0ee` is
     // `--str-chat__message-bubble-background-color`. Mirrored in
-    // and mirrored by the bubble tail's own fills in `styles.css`.
+    // `chinContrast.BUBBLE_BG_BY_VARIANT`, which the bubble tail reads.
     bgClassName ?? (variant === 'dark' ? 'bg-[#1e2330]' : 'bg-[#f1f0ee]'),
     // `focus-ring` is a design-system utility from the component-library
     // tailwind preset — outline-none + a black 2px focus-visible ring
@@ -131,12 +127,6 @@ const CardShell: React.FC<CardShellProps> = ({
     ? { role: 'status', 'aria-busy': true, 'aria-label': LOADING_LABEL }
     : undefined
 
-  // Published as a custom property, not a `background`: the `[style*='--accent']`
-  // rule in `styles.css` keys off its presence and derives the surface in CSS.
-  const accentStyle = accentHex
-    ? ({ '--accent': accentHex } as React.CSSProperties)
-    : undefined
-
   const corner = topRight ? (
     <div className="pointer-events-auto absolute right-3 top-3 z-10">
       {topRight}
@@ -152,7 +142,6 @@ const CardShell: React.FC<CardShellProps> = ({
         rel="noopener noreferrer"
         onClick={onClick}
         data-testid={dataTestId}
-        data-variant={variant}
         className={className}
         style={accentStyle}
         {...busyProps}
@@ -171,7 +160,6 @@ const CardShell: React.FC<CardShellProps> = ({
         onClick={onClick}
         aria-label={ariaLabel}
         data-testid={dataTestId}
-        data-variant={variant}
         className={classNames(className, 'text-left')}
         style={accentStyle}
         {...busyProps}
@@ -186,7 +174,6 @@ const CardShell: React.FC<CardShellProps> = ({
     <div
       ref={rootRef as React.Ref<HTMLDivElement>}
       data-testid={dataTestId}
-      data-variant={variant}
       className={className}
       style={accentStyle}
       {...busyProps}

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

@@ -0,0 +1,135 @@
+import { converter } from 'culori'
+import { describe, expect, it } from 'vitest'
+
+import { accentSurface } from './accentSurface'
+import {
+  contrastRatio,
+  inkFor,
+  INK_ON_DARK,
+  INK_ON_LIGHT,
+  WCAG_AA_NORMAL_TEXT,
+} from './chinContrast'
+
+const toOklch = converter('oklch')
+
+/** Hue is only meaningful above a little chroma, so tests gate on this. */
+function chromaOf(hex: string): number {
+  return toOklch(hex)?.c ?? 0
+}
+
+function hueOf(hex: string): number {
+  return toOklch(hex)?.h ?? 0
+}
+
+/** Hues far enough apart to be visibly different colours. */
+const SAMPLES = [
+  '#7008E7', // violet — chroma well outside sRGB at both stops
+  '#2FCB5F', // green
+  '#FFF099', // pale yellow
+  '#00B6FF', // cyan
+  '#738883', // the Figma mock's desaturated green
+  '#FCF5E3', // the near-white from the MES-1388 report
+  '#1e2330', // already as dark as the sender fallback
+  '#767676', // fully neutral, zero chroma
+]
+
+describe('accentSurface', () => {
+  it('always produces a surface its own ink can clear AA on', () => {
+    // The whole point of deriving rather than admitting: no extracted colour is
+    // ever rejected for contrast, and none is ever illegible.
+    for (const sample of SAMPLES) {
+      for (const [variant, ink] of [
+        ['dark', INK_ON_DARK],
+        ['light', INK_ON_LIGHT],
+      ] as const) {
+        const surface = accentSurface(sample, variant)
+        expect(surface, `${sample} on ${variant}`).toBeDefined()
+        expect(
+          contrastRatio(surface as string, ink),
+          `${sample} on ${variant}`
+        ).toBeGreaterThanOrEqual(WCAG_AA_NORMAL_TEXT)
+        // And the ink the card will actually pick agrees with that side.
+        expect(inkFor(surface as string)).toBe(ink)
+      }
+    }
+  })
+
+  it('keeps the image hue so different links stay distinguishable', () => {
+    for (const sample of SAMPLES) {
+      // Hue is only meaningful above a little chroma: `#FCF5E3` and `#767676`
+      // are near-neutral, where the angle is numerically unstable and invisible.
+      if (chromaOf(sample) < 0.03) continue
+      const expected = hueOf(sample)
+      for (const variant of ['dark', 'light'] as const) {
+        const surface = accentSurface(sample, variant) as string
+        const drift = Math.abs(hueOf(surface) - expected)
+        // Tight on purpose. `clampChroma` holds hue while it desaturates, so
+        // this stays under 2° — the same fidelity as the hand-rolled OKLCH pass
+        // it replaced. Swapping to culori's `toGamut` would drift up to 12° and
+        // trip this, which is exactly the regression it is here to catch.
+        expect(
+          Math.min(drift, 360 - drift),
+          `${sample} ${variant}`
+        ).toBeLessThan(2)
+      }
+    }
+  })
+
+  it('separates the two sides, so each is legible under its own ink', () => {
+    // Sent lands dark, received pale — the same link, the same hue, opposite
+    // ends of the lightness axis because the inks are opposites.
+    for (const sample of SAMPLES) {
+      const sent = accentSurface(sample, 'dark') as string
+      const received = accentSurface(sample, 'light') as string
+      expect(contrastRatio(sent, INK_ON_DARK)).toBeGreaterThan(
+        contrastRatio(sent, INK_ON_LIGHT)
+      )
+      expect(contrastRatio(received, INK_ON_LIGHT)).toBeGreaterThan(
+        contrastRatio(received, INK_ON_DARK)
+      )
+    }
+  })
+
+  it('holds AA at every hue, at chroma beyond what sRGB can show', () => {
+    // Sweeps the failure mode that a fixed lightness stop could plausibly have:
+    // a hue whose maximum chroma pushes the derived colour out of gamut.
+    for (let hue = 0; hue < 360; hue += 15) {
+      const vivid = `#${[0, 120, 240]
+        .map((offset) =>
+          Math.round(127 + 127 * Math.cos(((hue + offset) * Math.PI) / 180))
+            .toString(16)
+            .padStart(2, '0')
+        )
+        .join('')}`
+      for (const [variant, ink] of [
+        ['dark', INK_ON_DARK],
+        ['light', INK_ON_LIGHT],
+      ] as const) {
+        const surface = accentSurface(vivid, variant)
+        expect(
+          contrastRatio(surface as string, ink),
+          `hue ${hue} on ${variant}`
+        ).toBeGreaterThanOrEqual(WCAG_AA_NORMAL_TEXT)
+      }
+    }
+  })
+
+  it('accepts the shapes the extractor and CSS disagree about', () => {
+    // `accent_color` arrives from the ugc-kit query as a bare hex often enough
+    // that a missing `#` must not silently drop the colour.
+    expect(accentSurface('7008E7', 'dark')).toBe(
+      accentSurface('#7008E7', 'dark')
+    )
+    expect(accentSurface('  #7008E7  ', 'dark')).toBe(
+      accentSurface('#7008E7', 'dark')
+    )
+    expect(accentSurface('#70E', 'dark')).toBeDefined()
+  })
+
+  it('has no surface when there was no colour to derive from', () => {
+    expect(accentSurface(undefined, 'dark')).toBeUndefined()
+    expect(accentSurface('', 'dark')).toBeUndefined()
+    expect(accentSurface('rebeccapurple', 'dark')).toBeUndefined()
+    expect(accentSurface('#ff', 'light')).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,95 @@
+/**
+ * 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, the sRGB gamut mapping and the WCAG ratio are all `culori`'s.
+ * An earlier revision of this module hand-rolled them (~90 lines of OKLab
+ * matrices and a bisecting chroma search); `culori` is zero-dependency and ships
+ * a real CJS build, so it is safe for both frontyard's Jest and profiles' build.
+ */
+import { clampChroma, converter, formatHex, wcagContrast } from 'culori'
+
+import type { LinkAttachmentVariant } from './CardShell'
+import { INK_ON_DARK, INK_ON_LIGHT, WCAG_AA_NORMAL_TEXT } from './chinContrast'
+import { HEX_PATTERN, toCssHex } from './hex'
+
+/**
+ * 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 every hue at maximum chroma the worst
+ * case is comfortably above the 4.5:1 floor (see `accentSurface.test.ts`).
+ */
+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 toOklch = converter('oklch')
+
+/**
+ * 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.
+ *
+ * The input is validated as a hex rather than handed to `culori` directly.
+ * `culori` accepts every CSS colour, including names like `rebeccapurple`, and
+ * `accent_color` is always a hex from `getDominantColorFromImageUrl` — widening
+ * that contract by accident would let a caller pass something no other part of
+ * this module can reason about. The bare-hex case *is* supported, because the
+ * extractor omits the `#` often enough that dropping it would silently lose the
+ * colour (MES-1349).
+ *
+ * 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 || !HEX_PATTERN.test(accentColor.trim())) {
+    return undefined
+  }
+
+  const base = toOklch(toCssHex(accentColor))
+  if (!base) return undefined
+
+  // `clampChroma`, not `toGamut`: both bring an out-of-sRGB colour back into
+  // range, but `toGamut` follows the CSS Color 4 path and drifts hue by up to
+  // 12° on saturated bases, while `clampChroma` reduces chroma at constant hue
+  // and lightness — 2.8° worst case. Vivid hues desaturate rather than shift,
+  // which is what keeps the card recognisably the image's colour.
+  const surface = formatHex(
+    clampChroma({ ...base, l: SURFACE_LIGHTNESS[variant] }, 'oklch')
+  )
+
+  return wcagContrast(surface, INK_BY_VARIANT[variant]) >= WCAG_AA_NORMAL_TEXT
+    ? surface
+    : undefined
+}

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

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+
+import { AUDIO_BG, AUDIO_BG_CLASS } from './CardThumbnail'
+import {
+  BUBBLE_BG_BY_VARIANT,
+  contrastRatio,
+  inkFor,
+  INK_ON_DARK,
+  INK_ON_LIGHT,
+  WCAG_AA_NORMAL_TEXT,
+} from './chinContrast'
+
+describe('contrastRatio', () => {
+  // The arithmetic is culori's. What this module owns is the input contract:
+  // which strings are colours, and what happens to the ones that are not.
+  it('matches the WCAG maximum for black on white', () => {
+    expect(contrastRatio('#000000', '#ffffff')).toBeCloseTo(21, 2)
+  })
+
+  it('is symmetric and self-referential', () => {
+    expect(contrastRatio('#1e2330', '#ffffff')).toBeCloseTo(
+      contrastRatio('#ffffff', '#1e2330'),
+      5
+    )
+    expect(contrastRatio('#1e2330', '#1e2330')).toBeCloseTo(1, 5)
+  })
+
+  it('accepts short hex and the missing hash the extractor omits', () => {
+    const canonical = contrastRatio('#ffffff', '#1e2330')
+    for (const white of ['#fff', 'ffffff', '  #fff  ']) {
+      expect(contrastRatio(white, '#1e2330')).toBeCloseTo(canonical, 5)
+    }
+  })
+
+  it('is NaN for anything that is not a hex, including CSS colour names', () => {
+    // culori would happily resolve `rebeccapurple`; this module deliberately
+    // does not, because every colour reaching it comes from a hex extractor.
+    for (const input of ['', '#ff', '#gggggg', 'rebeccapurple', '#ffffff00']) {
+      expect(contrastRatio(input, '#ffffff')).toBeNaN()
+      expect(contrastRatio('#ffffff', input)).toBeNaN()
+    }
+  })
+})
+
+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('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',
+    })
+  })
+})
+
+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)
+  })
+
+  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('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('has no ink for an unparseable surface', () => {
+    expect(inkFor('rebeccapurple')).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,79 @@
+/**
+ * Ink and fallback fills for the `LinkAttachment` card, whose background is a
+ * colour derived from the attachment image (see `accentSurface`).
+ *
+ * The card's text is chosen by measuring contrast against whatever surface the
+ * card actually paints. Ink used to be fixed per variant, which left any
+ * background the card imposed on *itself* unchecked: `AUDIO_BG_CLASS`
+ * (`#F2F3F4`) is applied on either variant, so a sent audio card drew white ink
+ * on near-white at 1.13:1 and the title was invisible (MES-1388).
+ *
+ * The ratio itself is `culori`'s `wcagContrast`. A previous revision computed
+ * relative luminance here by hand; the only thing this module adds now is the
+ * decision of *which* ink, and the hex validation that keeps the surface a hex
+ * rather than any CSS colour.
+ */
+import { wcagContrast } from 'culori'
+
+import type { LinkAttachmentVariant } from './CardShell'
+import { HEX_PATTERN, toCssHex } from './hex'
+
+/** WCAG 2.1 SC 1.4.3 (AA), normal text. Both chin lines are normal text. */
+export const WCAG_AA_NORMAL_TEXT = 4.5
+
+/**
+ * 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 because the contrast arithmetic needs a colour, not a `var()`.
+ * Keep in sync with those two custom properties.
+ */
+export const BUBBLE_BG_BY_VARIANT: Record<LinkAttachmentVariant, string> = {
+  dark: '#1e2330',
+  light: '#f1f0ee',
+}
+
+/** 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'
+
+/**
+ * WCAG contrast ratio between two hex colours, or `NaN` if either is not a hex.
+ *
+ * The hex guard is deliberate: `culori` resolves any CSS colour, and every
+ * colour reaching this module comes from an image extractor or from the two
+ * constants above. `NaN` rather than a throw so callers can branch on
+ * `Number.isNaN` and fall back.
+ */
+export function contrastRatio(a: string, b: string): number {
+  if (typeof a !== 'string' || typeof b !== 'string') return Number.NaN
+  if (!HEX_PATTERN.test(a.trim()) || !HEX_PATTERN.test(b.trim())) {
+    return Number.NaN
+  }
+
+  return wcagContrast(toCssHex(a), toCssHex(b))
+}
+
+/**
+ * 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 not a hex, so callers keep the
+ * variant's own `text-*` classes.
+ *
+ * This is the rule the accent derivation cannot cover. A derived accent suits
+ * its side's ink by construction; an imposed background has to be met the other
+ * way round, by moving the ink. Only decoration can be refused (MES-1388).
+ */
+export function inkFor(background: string): string | undefined {
+  const againstDarkInk = contrastRatio(background, INK_ON_LIGHT)
+  if (Number.isNaN(againstDarkInk)) return undefined
+
+  return againstDarkInk >= contrastRatio(background, INK_ON_DARK)
+    ? INK_ON_LIGHT
+    : INK_ON_DARK
+}

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

@@ -1,11 +1,11 @@
 /**
- * The hex contract for the accent colour `useChinPalette` publishes.
+ * The hex contract shared by `chinContrast` and `accentSurface`.
  *
- * The extracted `accent_color` (from `getDominantColorFromImageUrl` via a Stream
- * attachment field) is always a hex, but CSS `oklch(from …)` would resolve any
- * colour name — including `rebeccapurple` — so the input is narrowed to a hex
- * before it is published as `--accent`, rather than widening that contract by
- * accident.
+ * `culori` does the parsing, and it accepts every CSS colour — including names
+ * like `rebeccapurple` and formats with alpha. Every colour reaching these two
+ * modules comes from `getDominantColorFromImageUrl` via a Stream attachment
+ * field, or from a constant in this directory, so both narrow the input to a hex
+ * before handing it over rather than widening their contract by accident.
  */
 
 /**
@@ -19,7 +19,7 @@
  */
 export const HEX_PATTERN = /^#?(?:[0-9a-f]{3}|[0-9a-f]{6})$/i
 
-/** Normalizes a hex for CSS, adding the `#` the extractor omits. */
+/** Normalizes a hex for CSS and for culori, adding the `#` the extractor omits. */
 export function toCssHex(hex: string): string {
   const trimmed = hex.trim()
   return trimmed.startsWith('#') ? trimmed : `#${trimmed}`

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

@@ -5,19 +5,10 @@ import React from 'react'
 
 import type { LinkAttachmentLayout, LinkAttachmentStatus } from '../../types'
 
+import { accentSurface } from './accentSurface'
 import type { LinkAttachmentVariant } from './CardShell'
-import { isPlayableAudio } from './CardThumbnail'
-import { HEX_PATTERN, toCssHex } from './hex'
-
-/** White on the dark stop, near-black on the light stop and the audio strip. */
-const INK_ON_DARK = '#FFFFFF'
-/** The near-black used across the Figma frames. */
-const INK_ON_LIGHT = '#040403'
-
-const INK_BY_VARIANT: Record<LinkAttachmentVariant, string> = {
-  dark: INK_ON_DARK,
-  light: INK_ON_LIGHT,
-}
+import { AUDIO_BG, isPlayableAudio } from './CardThumbnail'
+import { BUBBLE_BG_BY_VARIANT, inkFor } from './chinContrast'
 
 export interface ChinPaletteInput {
   variant: LinkAttachmentVariant
@@ -40,17 +31,21 @@ export interface ChinPalette {
    */
   thumbnailUrl?: string
   /**
-   * Raw extracted colour to publish as the `--accent` custom property on the
-   * shell and the tail, or `undefined` when there is no paintable accent. The
-   * hue-preserving lightness swap is done in CSS (`styles.css`) — see MES-1412.
+   * Inline background for the card shell, or `undefined` to keep the variant's
+   * own `bg-*` class.
+   */
+  accentStyle?: React.CSSProperties
+  /**
+   * Ink for both chin lines, chosen against the surface the card actually
+   * paints — the derived accent, the audio strip, or the fallback fill. Always
+   * defined for a parseable surface.
    */
-  accentHex?: string
+  chinTextColor?: string
   /**
-   * Ink for both chin lines: white on the sender's dark stop, near-black on the
-   * receiver's pale stop and on the audio strip. Fixed per surface, so no
-   * runtime contrast measurement is needed (the stops clear AA by construction).
+   * Colour the bubble tail paints in, always defined: the accent when one is
+   * paintable, otherwise this side's plain bubble fill.
    */
-  chinTextColor: string
+  tailColor: string
   /** True while the card renders as a skeleton. */
   isLoading: boolean
   /** Hand to `CardThumbnail` so a broken hero drops the accent with it. */
@@ -119,27 +114,23 @@ export function useChinPalette({
   const isAudio = isPlayableAudio(mimeType, sourceUrl)
   const hasHero =
     layout === 'featured' && !!thumbnailUrl && !isAudio && !heroFailed
-  const canDerive = hasHero && status === 'ready'
-  // Only a validated hex is published: `accent_color` is always a hex from the
-  // extractor, and CSS would resolve any colour name — narrowing keeps the input
-  // contract the same one the old `accentSurface` enforced. The bare-hex case is
-  // supported because the extractor omits the `#` often enough that dropping it
-  // would silently lose the colour (MES-1349).
-  const accentHex =
-    canDerive && accentColor != null && HEX_PATTERN.test(accentColor.trim())
-      ? toCssHex(accentColor)
+  const surface =
+    hasHero && status === 'ready'
+      ? accentSurface(accentColor, variant)
       : undefined
 
-  // The accent surface and the sender's dark fallback both take white ink; the
-  // pale receiver fallback and the imposed audio strip both take near-black. So
-  // the ink is fixed per surface and needs no runtime contrast — a sent audio
-  // card put white ink on the strip's near-white at 1.13:1 before (MES-1388).
-  const chinTextColor = isAudio ? INK_ON_LIGHT : INK_BY_VARIANT[variant]
+  // Whatever the card ends up painted with, legible or not, the ink is chosen
+  // against it. The accent is derived to suit this side's ink, but the audio
+  // strip and the fallback fill are imposed and cannot be refused — a sent
+  // audio card put white ink on `AUDIO_BG`'s near-white at 1.13:1 (MES-1388).
+  const painted =
+    surface ?? (isAudio ? AUDIO_BG : BUBBLE_BG_BY_VARIANT[variant])
 
   return {
     thumbnailUrl: heroFailed ? undefined : thumbnailUrl,
-    accentHex,
-    chinTextColor,
+    accentStyle: surface ? { backgroundColor: surface } : undefined,
+    chinTextColor: inkFor(painted),
+    tailColor: painted,
     isLoading: status === 'loading',
     onImageError,
   }

package/src/components/LinkAttachment/types.ts

@@ -77,17 +77,16 @@ export interface LinkAttachmentBaseProps {
   /**
    * Dominant colour extracted from `thumbnailUrl`, as a hex string
    * (`#RRGGBB` or `#RGB`). Paints the card and — when the card is the last
-   * bubble in a same-author run — its tail. Its hue is kept while the lightness
-   * is swapped to a fixed per-side stop (`oklch(from …)` in `styles.css`); the
-   * stops clear WCAG AA at every hue by construction, so callers never pass a
+   * bubble in a same-author run — its tail. The card derives its own chin
+   * text colour from this value for WCAG AA contrast; callers never pass a
    * text colour.
    *
    * Only painted while the hero image it was extracted from is actually on
    * screen. Omitted, unparseable, `layout: 'classic'`, no `thumbnailUrl`,
    * `status` other than `'ready'`, a playable-audio `mimeType` + `sourceUrl`
-   * (whose hero is the native player rather than an image), or a hero that fails
-   * to load => the card keeps the plain bubble fill. Browsers without
-   * relative-colour-syntax support also keep that fill (progressive enhancement).
+   * (whose hero is the native player rather than an image), or a hero that
+   * fails to load, or the colour cannot clear AA against this side's ink =>
+   * the card falls back to `BUBBLE_BG_BY_VARIANT[variant]`, the plain bubble fill.
    */
   accentColor?: string