@oxyhq/bloom 0.36.0 → 0.37.0

package/src/theme/color-engine/color-roles.ts

@@ -0,0 +1,435 @@
+/**
+ * Bloom colour engine — the colour roles.
+ *
+ * Faithful port of Material Color Utilities' `MaterialDynamicColors` (Apache-2.0),
+ * renamed to Bloom's own `Roles`. Each role is a {@link ColorRole} recipe over
+ * the scheme's palettes: surfaces, on-surfaces, the accent trio + their
+ * containers, outlines and error. Resolving a role against a scheme yields the
+ * final colour. The 12 "*Fixed" roles the reference ships are omitted — Bloom's
+ * token contract doesn't use them.
+ */
+import { ColorRole } from './color-role';
+import { ContrastCurve } from './contrast-curve';
+import type { DynamicScheme } from './dynamic-scheme';
+import { fixIfDisliked } from './dislike-analyzer';
+import { Hct } from './hct';
+import { ToneDeltaPair } from './tone-delta-pair';
+import { Variant } from './variant';
+
+const isFidelity = (s: DynamicScheme): boolean =>
+  s.variant === Variant.FIDELITY || s.variant === Variant.CONTENT;
+const isMonochrome = (s: DynamicScheme): boolean => s.variant === Variant.MONOCHROME;
+
+/** For fidelity schemes: find the tone nearest a target chroma. */
+function findDesiredChromaByTone(
+  hue: number,
+  chroma: number,
+  tone: number,
+  byDecreasingTone: boolean,
+): number {
+  let answer = tone;
+  let closestToChroma = Hct.from(hue, chroma, tone);
+  if (closestToChroma.chroma < chroma) {
+    let chromaPeak = closestToChroma.chroma;
+    while (closestToChroma.chroma < chroma) {
+      answer += byDecreasingTone ? -1.0 : 1.0;
+      const potentialSolution = Hct.from(hue, chroma, answer);
+      if (chromaPeak > potentialSolution.chroma) break;
+      if (Math.abs(potentialSolution.chroma - chroma) < 0.4) break;
+      const potentialDelta = Math.abs(potentialSolution.chroma - chroma);
+      const currentDelta = Math.abs(closestToChroma.chroma - chroma);
+      if (potentialDelta < currentDelta) closestToChroma = potentialSolution;
+      chromaPeak = Math.max(chromaPeak, potentialSolution.chroma);
+    }
+  }
+  return answer;
+}
+
+/** The most-elevated surface a scheme can show — the brightest/dimmest ground. */
+const highestSurface = (s: DynamicScheme): ColorRole => (s.isDark ? surfaceBright : surfaceDim);
+
+// ---- palette key colours ----
+const primaryPaletteKeyColor = ColorRole.fromPalette({
+  name: 'primary_palette_key_color',
+  palette: (s) => s.primaryPalette,
+  tone: (s) => s.primaryPalette.keyColor.tone,
+});
+const secondaryPaletteKeyColor = ColorRole.fromPalette({
+  name: 'secondary_palette_key_color',
+  palette: (s) => s.secondaryPalette,
+  tone: (s) => s.secondaryPalette.keyColor.tone,
+});
+const tertiaryPaletteKeyColor = ColorRole.fromPalette({
+  name: 'tertiary_palette_key_color',
+  palette: (s) => s.tertiaryPalette,
+  tone: (s) => s.tertiaryPalette.keyColor.tone,
+});
+const neutralPaletteKeyColor = ColorRole.fromPalette({
+  name: 'neutral_palette_key_color',
+  palette: (s) => s.neutralPalette,
+  tone: (s) => s.neutralPalette.keyColor.tone,
+});
+const neutralVariantPaletteKeyColor = ColorRole.fromPalette({
+  name: 'neutral_variant_palette_key_color',
+  palette: (s) => s.neutralVariantPalette,
+  tone: (s) => s.neutralVariantPalette.keyColor.tone,
+});
+
+// ---- surfaces ----
+const background = ColorRole.fromPalette({
+  name: 'background',
+  palette: (s) => s.neutralPalette,
+  tone: (s) => (s.isDark ? 6 : 98),
+  isBackground: true,
+});
+const onBackground = ColorRole.fromPalette({
+  name: 'on_background',
+  palette: (s) => s.neutralPalette,
+  tone: (s) => (s.isDark ? 90 : 10),
+  background: () => background,
+  contrastCurve: new ContrastCurve(3, 3, 4.5, 7),
+});
+const surface = ColorRole.fromPalette({
+  name: 'surface',
+  palette: (s) => s.neutralPalette,
+  tone: (s) => (s.isDark ? 6 : 98),
+  isBackground: true,
+});
+const surfaceDim = ColorRole.fromPalette({
+  name: 'surface_dim',
+  palette: (s) => s.neutralPalette,
+  tone: (s) => (s.isDark ? 6 : new ContrastCurve(87, 87, 80, 75).get(s.contrastLevel)),
+  isBackground: true,
+});
+const surfaceBright = ColorRole.fromPalette({
+  name: 'surface_bright',
+  palette: (s) => s.neutralPalette,
+  tone: (s) => (s.isDark ? new ContrastCurve(24, 24, 29, 34).get(s.contrastLevel) : 98),
+  isBackground: true,
+});
+const surfaceContainerLowest = ColorRole.fromPalette({
+  name: 'surface_container_lowest',
+  palette: (s) => s.neutralPalette,
+  tone: (s) => (s.isDark ? new ContrastCurve(4, 4, 2, 0).get(s.contrastLevel) : 100),
+  isBackground: true,
+});
+const surfaceContainerLow = ColorRole.fromPalette({
+  name: 'surface_container_low',
+  palette: (s) => s.neutralPalette,
+  tone: (s) =>
+    s.isDark
+      ? new ContrastCurve(10, 10, 11, 12).get(s.contrastLevel)
+      : new ContrastCurve(96, 96, 96, 95).get(s.contrastLevel),
+  isBackground: true,
+});
+const surfaceContainer = ColorRole.fromPalette({
+  name: 'surface_container',
+  palette: (s) => s.neutralPalette,
+  tone: (s) =>
+    s.isDark
+      ? new ContrastCurve(12, 12, 16, 20).get(s.contrastLevel)
+      : new ContrastCurve(94, 94, 92, 90).get(s.contrastLevel),
+  isBackground: true,
+});
+const surfaceContainerHigh = ColorRole.fromPalette({
+  name: 'surface_container_high',
+  palette: (s) => s.neutralPalette,
+  tone: (s) =>
+    s.isDark
+      ? new ContrastCurve(17, 17, 21, 25).get(s.contrastLevel)
+      : new ContrastCurve(92, 92, 88, 85).get(s.contrastLevel),
+  isBackground: true,
+});
+const surfaceContainerHighest = ColorRole.fromPalette({
+  name: 'surface_container_highest',
+  palette: (s) => s.neutralPalette,
+  tone: (s) =>
+    s.isDark
+      ? new ContrastCurve(22, 22, 26, 30).get(s.contrastLevel)
+      : new ContrastCurve(90, 90, 84, 80).get(s.contrastLevel),
+  isBackground: true,
+});
+const onSurface = ColorRole.fromPalette({
+  name: 'on_surface',
+  palette: (s) => s.neutralPalette,
+  tone: (s) => (s.isDark ? 90 : 10),
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(4.5, 7, 11, 21),
+});
+const surfaceVariant = ColorRole.fromPalette({
+  name: 'surface_variant',
+  palette: (s) => s.neutralVariantPalette,
+  tone: (s) => (s.isDark ? 30 : 90),
+  isBackground: true,
+});
+const onSurfaceVariant = ColorRole.fromPalette({
+  name: 'on_surface_variant',
+  palette: (s) => s.neutralVariantPalette,
+  tone: (s) => (s.isDark ? 80 : 30),
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(3, 4.5, 7, 11),
+});
+const inverseSurface = ColorRole.fromPalette({
+  name: 'inverse_surface',
+  palette: (s) => s.neutralPalette,
+  tone: (s) => (s.isDark ? 90 : 20),
+});
+const inverseOnSurface = ColorRole.fromPalette({
+  name: 'inverse_on_surface',
+  palette: (s) => s.neutralPalette,
+  tone: (s) => (s.isDark ? 20 : 95),
+  background: () => inverseSurface,
+  contrastCurve: new ContrastCurve(4.5, 7, 11, 21),
+});
+const outline = ColorRole.fromPalette({
+  name: 'outline',
+  palette: (s) => s.neutralVariantPalette,
+  tone: (s) => (s.isDark ? 60 : 50),
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(1.5, 3, 4.5, 7),
+});
+const outlineVariant = ColorRole.fromPalette({
+  name: 'outline_variant',
+  palette: (s) => s.neutralVariantPalette,
+  tone: (s) => (s.isDark ? 30 : 80),
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(1, 1, 3, 4.5),
+});
+const shadow = ColorRole.fromPalette({
+  name: 'shadow',
+  palette: (s) => s.neutralPalette,
+  tone: () => 0,
+});
+const scrim = ColorRole.fromPalette({
+  name: 'scrim',
+  palette: (s) => s.neutralPalette,
+  tone: () => 0,
+});
+const surfaceTint = ColorRole.fromPalette({
+  name: 'surface_tint',
+  palette: (s) => s.primaryPalette,
+  tone: (s) => (s.isDark ? 80 : 40),
+  isBackground: true,
+});
+
+// ---- primary ----
+const primary = ColorRole.fromPalette({
+  name: 'primary',
+  palette: (s) => s.primaryPalette,
+  tone: (s) => (isMonochrome(s) ? (s.isDark ? 100 : 0) : s.isDark ? 80 : 40),
+  isBackground: true,
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(3, 4.5, 7, 7),
+  toneDeltaPair: () => new ToneDeltaPair(primaryContainer, primary, 10, 'nearer', false),
+});
+const onPrimary = ColorRole.fromPalette({
+  name: 'on_primary',
+  palette: (s) => s.primaryPalette,
+  tone: (s) => (isMonochrome(s) ? (s.isDark ? 10 : 90) : s.isDark ? 20 : 100),
+  background: () => primary,
+  contrastCurve: new ContrastCurve(4.5, 7, 11, 21),
+});
+const primaryContainer = ColorRole.fromPalette({
+  name: 'primary_container',
+  palette: (s) => s.primaryPalette,
+  tone: (s) => {
+    if (isFidelity(s)) return s.sourceColorHct.tone;
+    if (isMonochrome(s)) return s.isDark ? 85 : 25;
+    return s.isDark ? 30 : 90;
+  },
+  isBackground: true,
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(1, 1, 3, 4.5),
+  toneDeltaPair: () => new ToneDeltaPair(primaryContainer, primary, 10, 'nearer', false),
+});
+const onPrimaryContainer = ColorRole.fromPalette({
+  name: 'on_primary_container',
+  palette: (s) => s.primaryPalette,
+  tone: (s) => {
+    if (isFidelity(s)) return ColorRole.foregroundTone(primaryContainer.tone(s), 4.5);
+    if (isMonochrome(s)) return s.isDark ? 0 : 100;
+    return s.isDark ? 90 : 30;
+  },
+  background: () => primaryContainer,
+  contrastCurve: new ContrastCurve(3, 4.5, 7, 11),
+});
+const inversePrimary = ColorRole.fromPalette({
+  name: 'inverse_primary',
+  palette: (s) => s.primaryPalette,
+  tone: (s) => (s.isDark ? 40 : 80),
+  background: () => inverseSurface,
+  contrastCurve: new ContrastCurve(3, 4.5, 7, 7),
+});
+
+// ---- secondary ----
+const secondary = ColorRole.fromPalette({
+  name: 'secondary',
+  palette: (s) => s.secondaryPalette,
+  tone: (s) => (s.isDark ? 80 : 40),
+  isBackground: true,
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(3, 4.5, 7, 7),
+  toneDeltaPair: () => new ToneDeltaPair(secondaryContainer, secondary, 10, 'nearer', false),
+});
+const onSecondary = ColorRole.fromPalette({
+  name: 'on_secondary',
+  palette: (s) => s.secondaryPalette,
+  tone: (s) => (isMonochrome(s) ? (s.isDark ? 10 : 100) : s.isDark ? 20 : 100),
+  background: () => secondary,
+  contrastCurve: new ContrastCurve(4.5, 7, 11, 21),
+});
+const secondaryContainer = ColorRole.fromPalette({
+  name: 'secondary_container',
+  palette: (s) => s.secondaryPalette,
+  tone: (s) => {
+    const initialTone = s.isDark ? 30 : 90;
+    if (isMonochrome(s)) return s.isDark ? 30 : 85;
+    if (!isFidelity(s)) return initialTone;
+    return findDesiredChromaByTone(
+      s.secondaryPalette.hue,
+      s.secondaryPalette.chroma,
+      initialTone,
+      !s.isDark,
+    );
+  },
+  isBackground: true,
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(1, 1, 3, 4.5),
+  toneDeltaPair: () => new ToneDeltaPair(secondaryContainer, secondary, 10, 'nearer', false),
+});
+const onSecondaryContainer = ColorRole.fromPalette({
+  name: 'on_secondary_container',
+  palette: (s) => s.secondaryPalette,
+  tone: (s) => {
+    if (isMonochrome(s)) return s.isDark ? 90 : 10;
+    if (!isFidelity(s)) return s.isDark ? 90 : 30;
+    return ColorRole.foregroundTone(secondaryContainer.tone(s), 4.5);
+  },
+  background: () => secondaryContainer,
+  contrastCurve: new ContrastCurve(3, 4.5, 7, 11),
+});
+
+// ---- tertiary ----
+const tertiary = ColorRole.fromPalette({
+  name: 'tertiary',
+  palette: (s) => s.tertiaryPalette,
+  tone: (s) => (isMonochrome(s) ? (s.isDark ? 90 : 25) : s.isDark ? 80 : 40),
+  isBackground: true,
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(3, 4.5, 7, 7),
+  toneDeltaPair: () => new ToneDeltaPair(tertiaryContainer, tertiary, 10, 'nearer', false),
+});
+const onTertiary = ColorRole.fromPalette({
+  name: 'on_tertiary',
+  palette: (s) => s.tertiaryPalette,
+  tone: (s) => (isMonochrome(s) ? (s.isDark ? 10 : 90) : s.isDark ? 20 : 100),
+  background: () => tertiary,
+  contrastCurve: new ContrastCurve(4.5, 7, 11, 21),
+});
+const tertiaryContainer = ColorRole.fromPalette({
+  name: 'tertiary_container',
+  palette: (s) => s.tertiaryPalette,
+  tone: (s) => {
+    if (isMonochrome(s)) return s.isDark ? 60 : 49;
+    if (!isFidelity(s)) return s.isDark ? 30 : 90;
+    const proposedHct = s.tertiaryPalette.getHct(s.sourceColorHct.tone);
+    return fixIfDisliked(proposedHct).tone;
+  },
+  isBackground: true,
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(1, 1, 3, 4.5),
+  toneDeltaPair: () => new ToneDeltaPair(tertiaryContainer, tertiary, 10, 'nearer', false),
+});
+const onTertiaryContainer = ColorRole.fromPalette({
+  name: 'on_tertiary_container',
+  palette: (s) => s.tertiaryPalette,
+  tone: (s) => {
+    if (isMonochrome(s)) return s.isDark ? 0 : 100;
+    if (!isFidelity(s)) return s.isDark ? 90 : 30;
+    return ColorRole.foregroundTone(tertiaryContainer.tone(s), 4.5);
+  },
+  background: () => tertiaryContainer,
+  contrastCurve: new ContrastCurve(3, 4.5, 7, 11),
+});
+
+// ---- error ----
+const error = ColorRole.fromPalette({
+  name: 'error',
+  palette: (s) => s.errorPalette,
+  tone: (s) => (s.isDark ? 80 : 40),
+  isBackground: true,
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(3, 4.5, 7, 7),
+  toneDeltaPair: () => new ToneDeltaPair(errorContainer, error, 10, 'nearer', false),
+});
+const onError = ColorRole.fromPalette({
+  name: 'on_error',
+  palette: (s) => s.errorPalette,
+  tone: (s) => (s.isDark ? 20 : 100),
+  background: () => error,
+  contrastCurve: new ContrastCurve(4.5, 7, 11, 21),
+});
+const errorContainer = ColorRole.fromPalette({
+  name: 'error_container',
+  palette: (s) => s.errorPalette,
+  tone: (s) => (s.isDark ? 30 : 90),
+  isBackground: true,
+  background: (s) => highestSurface(s),
+  contrastCurve: new ContrastCurve(1, 1, 3, 4.5),
+  toneDeltaPair: () => new ToneDeltaPair(errorContainer, error, 10, 'nearer', false),
+});
+const onErrorContainer = ColorRole.fromPalette({
+  name: 'on_error_container',
+  palette: (s) => s.errorPalette,
+  tone: (s) => (isMonochrome(s) ? (s.isDark ? 90 : 10) : s.isDark ? 90 : 30),
+  background: () => errorContainer,
+  contrastCurve: new ContrastCurve(3, 4.5, 7, 11),
+});
+
+/** The full set of Bloom colour roles, keyed by name. Resolve via `.getArgb(scheme)`. */
+export const Roles = {
+  primaryPaletteKeyColor,
+  secondaryPaletteKeyColor,
+  tertiaryPaletteKeyColor,
+  neutralPaletteKeyColor,
+  neutralVariantPaletteKeyColor,
+  background,
+  onBackground,
+  surface,
+  surfaceDim,
+  surfaceBright,
+  surfaceContainerLowest,
+  surfaceContainerLow,
+  surfaceContainer,
+  surfaceContainerHigh,
+  surfaceContainerHighest,
+  onSurface,
+  surfaceVariant,
+  onSurfaceVariant,
+  inverseSurface,
+  inverseOnSurface,
+  outline,
+  outlineVariant,
+  shadow,
+  scrim,
+  surfaceTint,
+  primary,
+  onPrimary,
+  primaryContainer,
+  onPrimaryContainer,
+  inversePrimary,
+  secondary,
+  onSecondary,
+  secondaryContainer,
+  onSecondaryContainer,
+  tertiary,
+  onTertiary,
+  tertiaryContainer,
+  onTertiaryContainer,
+  error,
+  onError,
+  errorContainer,
+  onErrorContainer,
+} as const;
+
+export type RoleName = keyof typeof Roles;

package/src/theme/color-engine/color-utils.ts

@@ -0,0 +1,157 @@
+/**
+ * Bloom colour engine — colour-science conversions (non-HCT).
+ *
+ * ARGB ⇄ XYZ ⇄ L*a*b*, sRGB (de)linearisation, and L*↔Y. Self-contained port of
+ * Material Color Utilities' `color_utils` (Apache-2.0) into Bloom's own code —
+ * no external colour dependency. Verified byte-for-byte by golden tests.
+ */
+import { clampInt, matrixMultiply } from './math-utils';
+
+type Matrix3 = [
+  [number, number, number],
+  [number, number, number],
+  [number, number, number],
+];
+
+const SRGB_TO_XYZ: Matrix3 = [
+  [0.41233895, 0.35762064, 0.18051042],
+  [0.2126, 0.7152, 0.0722],
+  [0.01932141, 0.11916382, 0.95034478],
+];
+
+const XYZ_TO_SRGB: Matrix3 = [
+  [3.2413774792388685, -1.5376652402851851, -0.49885366846268053],
+  [-0.9691452513005321, 1.8758853451067872, 0.04156585616912061],
+  [0.05562093689691305, -0.20395524564742123, 1.0571799111220335],
+];
+
+const WHITE_POINT_D65: [number, number, number] = [95.047, 100.0, 108.883];
+
+/** Pack 0–255 R/G/B into an opaque ARGB int. */
+export function argbFromRgb(red: number, green: number, blue: number): number {
+  return ((255 << 24) | ((red & 255) << 16) | ((green & 255) << 8) | (blue & 255)) >>> 0;
+}
+
+/** Pack linear-RGB (0–100 per channel) into an opaque ARGB int. */
+export function argbFromLinrgb(linrgb: [number, number, number]): number {
+  return argbFromRgb(delinearized(linrgb[0]), delinearized(linrgb[1]), delinearized(linrgb[2]));
+}
+
+export function alphaFromArgb(argb: number): number {
+  return (argb >> 24) & 255;
+}
+export function redFromArgb(argb: number): number {
+  return (argb >> 16) & 255;
+}
+export function greenFromArgb(argb: number): number {
+  return (argb >> 8) & 255;
+}
+export function blueFromArgb(argb: number): number {
+  return argb & 255;
+}
+export function isOpaque(argb: number): boolean {
+  return alphaFromArgb(argb) >= 255;
+}
+
+/** XYZ → ARGB. */
+export function argbFromXyz(x: number, y: number, z: number): number {
+  const m = XYZ_TO_SRGB;
+  const linearR = m[0][0] * x + m[0][1] * y + m[0][2] * z;
+  const linearG = m[1][0] * x + m[1][1] * y + m[1][2] * z;
+  const linearB = m[2][0] * x + m[2][1] * y + m[2][2] * z;
+  return argbFromRgb(delinearized(linearR), delinearized(linearG), delinearized(linearB));
+}
+
+/** ARGB → XYZ. */
+export function xyzFromArgb(argb: number): [number, number, number] {
+  const r = linearized(redFromArgb(argb));
+  const g = linearized(greenFromArgb(argb));
+  const b = linearized(blueFromArgb(argb));
+  return matrixMultiply([r, g, b], SRGB_TO_XYZ);
+}
+
+/** L*a*b* → ARGB. */
+export function argbFromLab(l: number, a: number, b: number): number {
+  const wp = WHITE_POINT_D65;
+  const fy = (l + 16.0) / 116.0;
+  const fx = a / 500.0 + fy;
+  const fz = fy - b / 200.0;
+  const x = labInvf(fx) * wp[0];
+  const y = labInvf(fy) * wp[1];
+  const z = labInvf(fz) * wp[2];
+  return argbFromXyz(x, y, z);
+}
+
+/** ARGB → L*a*b*. */
+export function labFromArgb(argb: number): [number, number, number] {
+  const linearR = linearized(redFromArgb(argb));
+  const linearG = linearized(greenFromArgb(argb));
+  const linearB = linearized(blueFromArgb(argb));
+  const m = SRGB_TO_XYZ;
+  const x = m[0][0] * linearR + m[0][1] * linearG + m[0][2] * linearB;
+  const y = m[1][0] * linearR + m[1][1] * linearG + m[1][2] * linearB;
+  const z = m[2][0] * linearR + m[2][1] * linearG + m[2][2] * linearB;
+  const wp = WHITE_POINT_D65;
+  const fx = labF(x / wp[0]);
+  const fy = labF(y / wp[1]);
+  const fz = labF(z / wp[2]);
+  return [116.0 * fy - 16, 500.0 * (fx - fy), 200.0 * (fy - fz)];
+}
+
+/** L* → ARGB (a grayscale color with that lightness). */
+export function argbFromLstar(lstar: number): number {
+  const component = delinearized(yFromLstar(lstar));
+  return argbFromRgb(component, component, component);
+}
+
+/** ARGB → L*. */
+export function lstarFromArgb(argb: number): number {
+  const y = xyzFromArgb(argb)[1];
+  return 116.0 * labF(y / 100.0) - 16.0;
+}
+
+/** L* → Y (XYZ luminance). */
+export function yFromLstar(lstar: number): number {
+  return 100.0 * labInvf((lstar + 16.0) / 116.0);
+}
+
+/** Y (XYZ luminance) → L*. */
+export function lstarFromY(y: number): number {
+  return labF(y / 100.0) * 116.0 - 16.0;
+}
+
+/** sRGB component (0–255) → linear (0–100). */
+export function linearized(rgbComponent: number): number {
+  const normalized = rgbComponent / 255.0;
+  return normalized <= 0.040449936
+    ? (normalized / 12.92) * 100.0
+    : Math.pow((normalized + 0.055) / 1.055, 2.4) * 100.0;
+}
+
+/** Linear component (0–100) → sRGB (0–255). */
+export function delinearized(rgbComponent: number): number {
+  const normalized = rgbComponent / 100.0;
+  const delin =
+    normalized <= 0.0031308
+      ? normalized * 12.92
+      : 1.055 * Math.pow(normalized, 1.0 / 2.4) - 0.055;
+  return clampInt(0, 255, Math.round(delin * 255.0));
+}
+
+/** The D65 white point. */
+export function whitePointD65(): [number, number, number] {
+  return WHITE_POINT_D65;
+}
+
+function labF(t: number): number {
+  const e = 216.0 / 24389.0;
+  const kappa = 24389.0 / 27.0;
+  return t > e ? Math.pow(t, 1.0 / 3.0) : (kappa * t + 16) / 116;
+}
+
+function labInvf(ft: number): number {
+  const e = 216.0 / 24389.0;
+  const kappa = 24389.0 / 27.0;
+  const ft3 = ft * ft * ft;
+  return ft3 > e ? ft3 : (116 * ft - 16) / kappa;
+}

package/src/theme/color-engine/contrast-curve.ts

@@ -0,0 +1,25 @@
+/**
+ * Bloom colour engine — contrast curve.
+ *
+ * Faithful port of Material Color Utilities' `ContrastCurve` (Apache-2.0). Maps
+ * a scheme's contrast level (−1 low … 0 normal … 1 high) to the target WCAG
+ * ratio a role should hit, interpolating between four control points.
+ */
+import { lerp } from './math-utils';
+
+export class ContrastCurve {
+  constructor(
+    readonly low: number,
+    readonly normal: number,
+    readonly medium: number,
+    readonly high: number,
+  ) {}
+
+  get(contrastLevel: number): number {
+    if (contrastLevel <= -1.0) return this.low;
+    if (contrastLevel < 0.0) return lerp(this.low, this.normal, (contrastLevel - -1) / 1);
+    if (contrastLevel < 0.5) return lerp(this.normal, this.medium, (contrastLevel - 0) / 0.5);
+    if (contrastLevel < 1.0) return lerp(this.medium, this.high, (contrastLevel - 0.5) / 0.5);
+    return this.high;
+  }
+}

package/src/theme/color-engine/contrast.ts

@@ -0,0 +1,59 @@
+/**
+ * Bloom colour engine — contrast in tone space.
+ *
+ * Faithful port of Material Color Utilities' `Contrast` (Apache-2.0). Because
+ * HCT tone maps to L*, contrast ratios can be computed and *targeted* directly
+ * in tone: given a tone and a desired WCAG ratio, find the lighter/darker tone
+ * that hits it. Drives every role's on-colour and container legibility.
+ */
+import { clampDouble } from './math-utils';
+import { lstarFromY, yFromLstar } from './color-utils';
+
+/** WCAG contrast ratio between two tones (L*). */
+export function ratioOfTones(toneA: number, toneB: number): number {
+  toneA = clampDouble(0.0, 100.0, toneA);
+  toneB = clampDouble(0.0, 100.0, toneB);
+  return ratioOfYs(yFromLstar(toneA), yFromLstar(toneB));
+}
+
+export function ratioOfYs(y1: number, y2: number): number {
+  const lighter = y1 > y2 ? y1 : y2;
+  const darker = lighter === y2 ? y1 : y2;
+  return (lighter + 5.0) / (darker + 5.0);
+}
+
+/** Lightest tone that hits `ratio` against `tone`, or -1 if impossible. */
+export function lighter(tone: number, ratio: number): number {
+  if (tone < 0.0 || tone > 100.0) return -1.0;
+  const darkY = yFromLstar(tone);
+  const lightY = ratio * (darkY + 5.0) - 5.0;
+  const realContrast = ratioOfYs(lightY, darkY);
+  const delta = Math.abs(realContrast - ratio);
+  if (realContrast < ratio && delta > 0.04) return -1;
+  const returnValue = lstarFromY(lightY) + 0.4;
+  return returnValue < 0 || returnValue > 100 ? -1 : returnValue;
+}
+
+/** Darkest tone that hits `ratio` against `tone`, or -1 if impossible. */
+export function darker(tone: number, ratio: number): number {
+  if (tone < 0.0 || tone > 100.0) return -1.0;
+  const lightY = yFromLstar(tone);
+  const darkY = (lightY + 5.0) / ratio - 5.0;
+  const realContrast = ratioOfYs(lightY, darkY);
+  const delta = Math.abs(realContrast - ratio);
+  if (realContrast < ratio && delta > 0.04) return -1;
+  const returnValue = lstarFromY(darkY) - 0.4;
+  return returnValue < 0 || returnValue > 100 ? -1 : returnValue;
+}
+
+/** Like {@link lighter} but returns 100 instead of -1 when unattainable. */
+export function lighterUnsafe(tone: number, ratio: number): number {
+  const lighterSafe = lighter(tone, ratio);
+  return lighterSafe < 0.0 ? 100.0 : lighterSafe;
+}
+
+/** Like {@link darker} but returns 0 instead of -1 when unattainable. */
+export function darkerUnsafe(tone: number, ratio: number): number {
+  const darkerSafe = darker(tone, ratio);
+  return darkerSafe < 0.0 ? 0.0 : darkerSafe;
+}

package/src/theme/color-engine/dislike-analyzer.ts

@@ -0,0 +1,19 @@
+/**
+ * Bloom colour engine — dislike analyzer.
+ *
+ * Faithful port of Material Color Utilities' `DislikeAnalyzer` (Apache-2.0).
+ * Certain dark-yellow-green HCT colours read as "bile"; this nudges their tone
+ * up to 70 so generated palettes never land on a universally-disliked colour.
+ */
+import { Hct } from './hct';
+
+export function isDisliked(hct: Hct): boolean {
+  const huePasses = Math.round(hct.hue) >= 90.0 && Math.round(hct.hue) <= 111.0;
+  const chromaPasses = Math.round(hct.chroma) > 16.0;
+  const tonePasses = Math.round(hct.tone) < 65.0;
+  return huePasses && chromaPasses && tonePasses;
+}
+
+export function fixIfDisliked(hct: Hct): Hct {
+  return isDisliked(hct) ? Hct.from(hct.hue, hct.chroma, 70.0) : hct;
+}