@oxyhq/bloom 0.36.0 → 0.37.1

package/src/theme/color-engine/dynamic-scheme.ts

@@ -0,0 +1,90 @@
+/**
+ * Bloom colour engine — dynamic scheme.
+ *
+ * Faithful port of Material Color Utilities' `DynamicScheme` core (Apache-2.0).
+ * Holds the five tonal palettes (primary/secondary/tertiary/neutral/
+ * neutralVariant) + error that a scheme variant derives from the seed, plus the
+ * dark/contrast state a `DynamicColor` role reads to resolve into an ARGB. The
+ * ~50 convenience role getters from the reference are omitted — Bloom reads
+ * roles directly through `materialRoles`.
+ */
+import type { ColorRole } from './color-role';
+import { Hct } from './hct';
+import { sanitizeDegreesDouble } from './math-utils';
+import { TonalPalette } from './tonal-palette';
+import { Variant } from './variant';
+
+export interface DynamicSchemeArgs {
+  sourceColorArgb: number;
+  variant: Variant;
+  contrastLevel: number;
+  isDark: boolean;
+  primaryPalette: TonalPalette;
+  secondaryPalette: TonalPalette;
+  tertiaryPalette: TonalPalette;
+  neutralPalette: TonalPalette;
+  neutralVariantPalette: TonalPalette;
+}
+
+export class DynamicScheme {
+  readonly sourceColorArgb: number;
+  readonly variant: Variant;
+  readonly contrastLevel: number;
+  readonly isDark: boolean;
+  readonly sourceColorHct: Hct;
+  readonly primaryPalette: TonalPalette;
+  readonly secondaryPalette: TonalPalette;
+  readonly tertiaryPalette: TonalPalette;
+  readonly neutralPalette: TonalPalette;
+  readonly neutralVariantPalette: TonalPalette;
+  readonly errorPalette: TonalPalette;
+
+  constructor(args: DynamicSchemeArgs) {
+    this.sourceColorArgb = args.sourceColorArgb;
+    this.variant = args.variant;
+    this.contrastLevel = args.contrastLevel;
+    this.isDark = args.isDark;
+    this.sourceColorHct = Hct.fromInt(args.sourceColorArgb);
+    this.primaryPalette = args.primaryPalette;
+    this.secondaryPalette = args.secondaryPalette;
+    this.tertiaryPalette = args.tertiaryPalette;
+    this.neutralPalette = args.neutralPalette;
+    this.neutralVariantPalette = args.neutralVariantPalette;
+    this.errorPalette = TonalPalette.fromHueAndChroma(25.0, 84.0);
+  }
+
+  /**
+   * Rotate the seed hue by a designer-specified amount that depends on which
+   * hue "breakpoint" band the seed falls in.
+   */
+  static getRotatedHue(sourceColor: Hct, hues: number[], rotations: number[]): number {
+    const sourceHue = sourceColor.hue;
+    if (hues.length !== rotations.length) {
+      throw new Error(`mismatch between hue length ${hues.length} & rotations ${rotations.length}`);
+    }
+    if (rotations.length === 1) {
+      const firstRotation = rotations[0];
+      if (firstRotation === undefined) throw new Error('rotations[0] missing');
+      return sanitizeDegreesDouble(sourceColor.hue + firstRotation);
+    }
+    const size = hues.length;
+    for (let i = 0; i <= size - 2; i++) {
+      const thisHue = hues[i];
+      const nextHue = hues[i + 1];
+      const rotation = rotations[i];
+      if (thisHue === undefined || nextHue === undefined || rotation === undefined) continue;
+      if (thisHue < sourceHue && sourceHue < nextHue) {
+        return sanitizeDegreesDouble(sourceHue + rotation);
+      }
+    }
+    return sourceHue;
+  }
+
+  getArgb(role: ColorRole): number {
+    return role.getArgb(this);
+  }
+
+  getHct(role: ColorRole): Hct {
+    return role.getHct(this);
+  }
+}

package/src/theme/color-engine/hct-solver.ts

@@ -0,0 +1,263 @@
+/**
+ * Bloom colour engine — the HCT solver.
+ *
+ * Faithful port of Material Color Utilities' `HctSolver` (Apache-2.0) into
+ * Bloom's own code. Given a desired hue, chroma and tone (L*), it finds the
+ * closest sRGB colour — an analytic Newton solve with a geometric bisection
+ * fallback that maximises chroma when the exact colour is out of gamut. This is
+ * what makes tonal palettes possible. Precision-critical; verified by golden
+ * tests. Constants are the reference values verbatim.
+ */
+import { argbFromLinrgb, argbFromLstar, yFromLstar } from './color-utils';
+import { matrixMultiply, sanitizeDegreesDouble, signum } from './math-utils';
+import { ViewingConditions } from './viewing-conditions';
+
+type Vec3 = [number, number, number];
+type Mat3 = [Vec3, Vec3, Vec3];
+
+const SCALED_DISCOUNT_FROM_LINRGB: Mat3 = [
+  [0.001200833568784504, 0.002389694492170889, 0.0002795742885861124],
+  [0.0005891086651375999, 0.0029785502573438758, 0.0003270666104008398],
+  [0.00010146692491640572, 0.0005364214359186694, 0.0032979401770712076],
+];
+const LINRGB_FROM_SCALED_DISCOUNT: Mat3 = [
+  [1373.2198709594231, -1100.4251190754821, -7.278681089101213],
+  [-271.815969077903, 559.6580465940733, -32.46047482791194],
+  [1.9622899599665666, -57.173814538844006, 308.7233197812385],
+];
+const Y_FROM_LINRGB: Vec3 = [0.2126, 0.7152, 0.0722];
+
+// prettier-ignore
+const CRITICAL_PLANES: number[] = [
+  0.015176349177441876, 0.045529047532325624, 0.07588174588720938, 0.10623444424209313, 0.13658714259697685, 0.16693984095186062, 0.19729253930674434, 0.2276452376616281, 0.2579979360165119, 0.28835063437139563, 0.3188300904430532, 0.350925934958123, 0.3848314933096426, 0.42057480301049466, 0.458183274052838, 0.4976837250274023, 0.5391024159806381, 0.5824650784040898, 0.6277969426914107, 0.6751227633498623, 0.7244668422128921, 0.775853049866786, 0.829304845476233, 0.8848452951698498, 0.942497089126609, 1.0022825574869039, 1.0642236851973577, 1.1283421258858297, 1.1946592148522128, 1.2631959812511864, 1.3339731595349034, 1.407011200216447, 1.4823302800086415, 1.5599503113873272, 1.6398909516233677, 1.7221716113234105, 1.8068114625156377, 1.8938294463134073, 1.9832442801866852, 2.075074464868551, 2.1693382909216234, 2.2660538449872063, 2.36523901573795, 2.4669114995532007, 2.5710888059345764, 2.6777882626779785, 2.7870270208169257, 2.898822059350997, 3.0131901897720907, 3.1301480604002863, 3.2497121605402226, 3.3718988244681087, 3.4967242352587946, 3.624204428461639, 3.754355295633311, 3.887192587735158, 4.022731918402185, 4.160988767090289, 4.301978482107941, 4.445716283538092, 4.592217266055746, 4.741496401646282, 4.893568542229298, 5.048448422192488, 5.20615066083972, 5.3666897647573375, 5.5300801301023865, 5.696336044816294, 5.865471690767354, 6.037501145825082, 6.212438385869475, 6.390297286737924, 6.571091626112461, 6.7548350853498045, 6.941541251256611, 7.131223617812143, 7.323895587840543, 7.5195704746346665, 7.7182615035334345, 7.919981813454504, 8.124744458384042, 8.332562408825165, 8.543448553206703, 8.757415699253682, 8.974476575321063, 9.194643831691977, 9.417930041841839, 9.644347703669503, 9.873909240696694, 10.106627003236781, 10.342513269534024, 10.58158024687427, 10.8238400726681, 11.069304815507364, 11.317986476196008, 11.569896988756009, 11.825048221409341, 12.083451977536606, 12.345119996613247, 12.610063955123938, 12.878295467455942, 13.149826086772048, 13.42466730586372, 13.702830557985108, 13.984327217668513, 14.269168601521828, 14.55736596900856, 14.848930523210871, 15.143873411576273, 15.44220572664832, 15.743938506781891, 16.04908273684337, 16.35764934889634, 16.66964922287304, 16.985093187232053, 17.30399201960269, 17.62635644741625, 17.95219714852476, 18.281524751807332, 18.614349837764564, 18.95068293910138, 19.290534541298456, 19.633915083172692, 19.98083495742689, 20.331304511189067, 20.685334046541502, 21.042933821039977, 21.404114048223256, 21.76888489811322, 22.137256497705877, 22.50923893145328, 22.884842241736916, 23.264076429332462, 23.6469514538663, 24.033477234264016, 24.42366364919083, 24.817520537484558, 25.21505769858089, 25.61628489293138, 26.021211842414342, 26.429848230738664, 26.842203703840827, 27.258287870275353, 27.678110301598522, 28.10168053274597, 28.529008062403893, 28.96010235337422, 29.39497283293396, 29.83362889318845, 30.276079891419332, 30.722335150426627, 31.172403958865512, 31.62629557157785, 32.08401920991837, 32.54558406207592, 33.010999283389665, 33.4802739966603, 33.953417292456834, 34.430438229418264, 34.911345834551085, 35.39614910352207, 35.88485700094671, 36.37747846067349, 36.87402238606382, 37.37449765026789, 37.87891309649659, 38.38727753828926, 38.89959975977785, 39.41588851594697, 39.93615253289054, 40.460400508064545, 40.98864111053629, 41.520882981230194, 42.05713473317016, 42.597404951718396, 43.141702194811224, 43.6900349931913, 44.24241185063697, 44.798841244188324, 45.35933162437017, 45.92389141541209, 46.49252901546552, 47.065252796817916, 47.64207110610409, 48.22299226451468, 48.808024568002054, 49.3971762874833, 49.9904556690408, 50.587870934119984, 51.189430279724725, 51.79514187861014, 52.40501387947288, 53.0190544071392, 53.637271562750364, 54.259673423945976, 54.88626804504493, 55.517063457223934, 56.15206766869424, 56.79128866487574, 57.43473440856916, 58.08241284012621, 58.734331877617365, 59.39049941699807, 60.05092333227251, 60.715611475655585, 61.38457167773311, 62.057811747619894, 62.7353394731159, 63.417162620860914, 64.10328893648692, 64.79372614476921, 65.48848194977529, 66.18756403501224, 66.89098006357258, 67.59873767827808, 68.31084450182222, 69.02730813691093, 69.74813616640164, 70.47333615344107, 71.20291564160104, 71.93688215501312, 72.67524319850172, 73.41800625771542, 74.16517879925733, 74.9167682708136, 75.67278210128072, 76.43322770089146, 77.1981124613393, 77.96744375590167, 78.74122893956174, 79.51947534912904, 80.30219030335869, 81.08938110306934, 81.88105503125999, 82.67721935322541, 83.4778813166706, 84.28304815182372, 85.09272707154808, 85.90692527145302, 86.72564993000343, 87.54890820862819, 88.3767072518277, 89.2090541872801, 90.04595612594655, 90.88742016217518, 91.73345337380438, 92.58406282226491, 93.43925555268066, 94.29903859396902, 95.16341895893969, 96.03240364439274, 96.9059996312159, 97.78421388448044, 98.6670533535366, 99.55452497210776,
+];
+
+function sanitizeRadians(angle: number): number {
+  return (angle + Math.PI * 8) % (Math.PI * 2);
+}
+
+function trueDelinearized(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 delin * 255.0;
+}
+
+function chromaticAdaptation(component: number): number {
+  const af = Math.pow(Math.abs(component), 0.42);
+  return (signum(component) * 400.0 * af) / (af + 27.13);
+}
+
+function hueOf(linrgb: Vec3): number {
+  const scaledDiscount = matrixMultiply(linrgb, SCALED_DISCOUNT_FROM_LINRGB);
+  const rA = chromaticAdaptation(scaledDiscount[0]);
+  const gA = chromaticAdaptation(scaledDiscount[1]);
+  const bA = chromaticAdaptation(scaledDiscount[2]);
+  const a = (11.0 * rA + -12.0 * gA + bA) / 11.0;
+  const b = (rA + gA - 2.0 * bA) / 9.0;
+  return Math.atan2(b, a);
+}
+
+function areInCyclicOrder(a: number, b: number, c: number): boolean {
+  const deltaAB = sanitizeRadians(b - a);
+  const deltaAC = sanitizeRadians(c - a);
+  return deltaAB < deltaAC;
+}
+
+function intercept(source: number, mid: number, target: number): number {
+  return (mid - source) / (target - source);
+}
+
+function lerpPoint(source: Vec3, t: number, target: Vec3): Vec3 {
+  return [
+    source[0] + (target[0] - source[0]) * t,
+    source[1] + (target[1] - source[1]) * t,
+    source[2] + (target[2] - source[2]) * t,
+  ];
+}
+
+/**
+ * Read a Vec3 lane by a runtime axis index. The axis is always 0–2 in the
+ * callers below; this asserts that invariant honestly under
+ * `noUncheckedIndexedAccess` rather than masking it.
+ */
+function coord(v: Vec3, axis: number): number {
+  const value = v[axis];
+  if (value === undefined) throw new RangeError(`Vec3 axis ${axis} out of range`);
+  return value;
+}
+
+function setCoordinate(source: Vec3, coordinate: number, target: Vec3, axis: number): Vec3 {
+  const t = intercept(coord(source, axis), coordinate, coord(target, axis));
+  return lerpPoint(source, t, target);
+}
+
+function isBounded(x: number): boolean {
+  return 0.0 <= x && x <= 100.0;
+}
+
+function nthVertex(y: number, n: number): Vec3 {
+  const kR = Y_FROM_LINRGB[0];
+  const kG = Y_FROM_LINRGB[1];
+  const kB = Y_FROM_LINRGB[2];
+  const coordA = n % 4 <= 1 ? 0.0 : 100.0;
+  const coordB = n % 2 === 0 ? 0.0 : 100.0;
+  if (n < 4) {
+    const g = coordA;
+    const b = coordB;
+    const r = (y - g * kG - b * kB) / kR;
+    return isBounded(r) ? [r, g, b] : [-1.0, -1.0, -1.0];
+  } else if (n < 8) {
+    const b = coordA;
+    const r = coordB;
+    const g = (y - r * kR - b * kB) / kG;
+    return isBounded(g) ? [r, g, b] : [-1.0, -1.0, -1.0];
+  } else {
+    const r = coordA;
+    const g = coordB;
+    const b = (y - r * kR - g * kG) / kB;
+    return isBounded(b) ? [r, g, b] : [-1.0, -1.0, -1.0];
+  }
+}
+
+function bisectToSegment(y: number, targetHue: number): [Vec3, Vec3] {
+  let left: Vec3 = [-1.0, -1.0, -1.0];
+  let right: Vec3 = left;
+  let leftHue = 0.0;
+  let rightHue = 0.0;
+  let initialized = false;
+  let uncut = true;
+  for (let n = 0; n < 12; n++) {
+    const mid = nthVertex(y, n);
+    if (mid[0] < 0) continue;
+    const midHue = hueOf(mid);
+    if (!initialized) {
+      left = mid;
+      right = mid;
+      leftHue = midHue;
+      rightHue = midHue;
+      initialized = true;
+      continue;
+    }
+    if (uncut || areInCyclicOrder(leftHue, midHue, rightHue)) {
+      uncut = false;
+      if (areInCyclicOrder(leftHue, targetHue, midHue)) {
+        right = mid;
+        rightHue = midHue;
+      } else {
+        left = mid;
+        leftHue = midHue;
+      }
+    }
+  }
+  return [left, right];
+}
+
+function midpoint(a: Vec3, b: Vec3): Vec3 {
+  return [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2, (a[2] + b[2]) / 2];
+}
+
+const criticalPlaneBelow = (x: number): number => Math.floor(x - 0.5);
+const criticalPlaneAbove = (x: number): number => Math.ceil(x - 0.5);
+
+function bisectToLimit(y: number, targetHue: number): Vec3 {
+  const segment = bisectToSegment(y, targetHue);
+  let left = segment[0];
+  let leftHue = hueOf(left);
+  let right = segment[1];
+  for (let axis = 0; axis < 3; axis++) {
+    const leftAxis = coord(left, axis);
+    const rightAxis = coord(right, axis);
+    if (leftAxis !== rightAxis) {
+      let lPlane = -1;
+      let rPlane = 255;
+      if (leftAxis < rightAxis) {
+        lPlane = criticalPlaneBelow(trueDelinearized(leftAxis));
+        rPlane = criticalPlaneAbove(trueDelinearized(rightAxis));
+      } else {
+        lPlane = criticalPlaneAbove(trueDelinearized(leftAxis));
+        rPlane = criticalPlaneBelow(trueDelinearized(rightAxis));
+      }
+      for (let i = 0; i < 8; i++) {
+        if (Math.abs(rPlane - lPlane) <= 1) break;
+        const mPlane = Math.floor((lPlane + rPlane) / 2.0);
+        const midPlaneCoordinate = CRITICAL_PLANES[mPlane];
+        if (midPlaneCoordinate === undefined) throw new RangeError(`critical plane ${mPlane} out of range`);
+        const mid = setCoordinate(left, midPlaneCoordinate, right, axis);
+        const midHue = hueOf(mid);
+        if (areInCyclicOrder(leftHue, targetHue, midHue)) {
+          right = mid;
+          rPlane = mPlane;
+        } else {
+          left = mid;
+          leftHue = midHue;
+          lPlane = mPlane;
+        }
+      }
+    }
+  }
+  return midpoint(left, right);
+}
+
+function inverseChromaticAdaptation(adapted: number): number {
+  const adaptedAbs = Math.abs(adapted);
+  const base = Math.max(0, (27.13 * adaptedAbs) / (400.0 - adaptedAbs));
+  return signum(adapted) * Math.pow(base, 1.0 / 0.42);
+}
+
+function findResultByJ(hueRadians: number, chroma: number, y: number): number {
+  let j = Math.sqrt(y) * 11.0;
+  // Read the CAM16 default viewing conditions directly (no magic constants).
+  const vc = ViewingConditions.DEFAULT;
+  const tInnerCoeff = 1 / Math.pow(1.64 - Math.pow(0.29, vc.n), 0.73);
+  const eHue = 0.25 * (Math.cos(hueRadians + 2.0) + 3.8);
+  const p1 = eHue * (50000.0 / 13.0) * vc.nc * vc.ncb;
+  const hSin = Math.sin(hueRadians);
+  const hCos = Math.cos(hueRadians);
+  for (let iterationRound = 0; iterationRound < 5; iterationRound++) {
+    const jNormalized = j / 100.0;
+    const alpha = chroma === 0.0 || j === 0.0 ? 0.0 : chroma / Math.sqrt(jNormalized);
+    const t = Math.pow(alpha * tInnerCoeff, 1.0 / 0.9);
+    const ac = vc.aw * Math.pow(jNormalized, 1.0 / vc.c / vc.z);
+    const p2 = ac / vc.nbb;
+    const gamma = (23.0 * (p2 + 0.305) * t) / (23.0 * p1 + 11 * t * hCos + 108.0 * t * hSin);
+    const a = gamma * hCos;
+    const b = gamma * hSin;
+    const rA = (460.0 * p2 + 451.0 * a + 288.0 * b) / 1403.0;
+    const gA = (460.0 * p2 - 891.0 * a - 261.0 * b) / 1403.0;
+    const bA = (460.0 * p2 - 220.0 * a - 6300.0 * b) / 1403.0;
+    const rCScaled = inverseChromaticAdaptation(rA);
+    const gCScaled = inverseChromaticAdaptation(gA);
+    const bCScaled = inverseChromaticAdaptation(bA);
+    const linrgb = matrixMultiply([rCScaled, gCScaled, bCScaled], LINRGB_FROM_SCALED_DISCOUNT);
+    if (linrgb[0] < 0 || linrgb[1] < 0 || linrgb[2] < 0) return 0;
+    const kR = Y_FROM_LINRGB[0];
+    const kG = Y_FROM_LINRGB[1];
+    const kB = Y_FROM_LINRGB[2];
+    const fnj = kR * linrgb[0] + kG * linrgb[1] + kB * linrgb[2];
+    if (fnj <= 0) return 0;
+    if (iterationRound === 4 || Math.abs(fnj - y) < 0.002) {
+      if (linrgb[0] > 100.01 || linrgb[1] > 100.01 || linrgb[2] > 100.01) return 0;
+      return argbFromLinrgb(linrgb);
+    }
+    j = j - ((fnj - y) * j) / (2 * fnj);
+  }
+  return 0;
+}
+
+/**
+ * Find the sRGB ARGB with the given hue (deg), chroma, and L*. When the exact
+ * colour is out of gamut, hue + L* are preserved and chroma is maximised.
+ */
+export function solveToInt(hueDegrees: number, chroma: number, lstar: number): number {
+  if (chroma < 0.0001 || lstar < 0.0001 || lstar > 99.9999) {
+    return argbFromLstar(lstar);
+  }
+  hueDegrees = sanitizeDegreesDouble(hueDegrees);
+  const hueRadians = (hueDegrees / 180) * Math.PI;
+  const y = yFromLstar(lstar);
+  const exactAnswer = findResultByJ(hueRadians, chroma, y);
+  if (exactAnswer !== 0) return exactAnswer;
+  const linrgb = bisectToLimit(y, hueRadians);
+  return argbFromLinrgb(linrgb);
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Bloom colour engine — HCT (Hue · Chroma · Tone).
+ *
+ * Faithful port of Material Color Utilities' `Hct` (Apache-2.0) into Bloom's own
+ * code. HCT pairs CAM16 hue + chroma with L* as "tone", giving a perceptually
+ * even lightness axis: a tone difference of 40 guarantees a ≥3:1 contrast ratio,
+ * 50 guarantees ≥4.5:1. Every tonal palette and colour role is built on it.
+ */
+import { Cam16 } from './cam16';
+import { lstarFromArgb } from './color-utils';
+import { solveToInt } from './hct-solver';
+
+export class Hct {
+  private argb: number;
+  private internalHue: number;
+  private internalChroma: number;
+  private internalTone: number;
+
+  private constructor(argb: number) {
+    this.argb = argb;
+    const cam = Cam16.fromInt(argb);
+    this.internalHue = cam.hue;
+    this.internalChroma = cam.chroma;
+    this.internalTone = lstarFromArgb(argb);
+  }
+
+  /** Build an HCT colour from hue (deg), chroma, and tone (L*, 0–100). */
+  static from(hue: number, chroma: number, tone: number): Hct {
+    return new Hct(solveToInt(hue, chroma, tone));
+  }
+
+  /** Wrap an existing ARGB colour as HCT. */
+  static fromInt(argb: number): Hct {
+    return new Hct(argb);
+  }
+
+  toInt(): number {
+    return this.argb;
+  }
+
+  get hue(): number {
+    return this.internalHue;
+  }
+  set hue(newHue: number) {
+    this.setInternalState(solveToInt(newHue, this.internalChroma, this.internalTone));
+  }
+
+  get chroma(): number {
+    return this.internalChroma;
+  }
+  set chroma(newChroma: number) {
+    this.setInternalState(solveToInt(this.internalHue, newChroma, this.internalTone));
+  }
+
+  get tone(): number {
+    return this.internalTone;
+  }
+  set tone(newTone: number) {
+    this.setInternalState(solveToInt(this.internalHue, this.internalChroma, newTone));
+  }
+
+  private setInternalState(argb: number): void {
+    const cam = Cam16.fromInt(argb);
+    this.internalHue = cam.hue;
+    this.internalChroma = cam.chroma;
+    this.internalTone = lstarFromArgb(argb);
+    this.argb = argb;
+  }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * Bloom colour engine — public surface.
+ *
+ * A dependency-free tonal colour system (HCT + tonal palettes + dynamic roles)
+ * reimplemented in Bloom from the Material Color Utilities algorithm (Apache-2.0)
+ * and verified byte-for-byte against it. Give it ANY seed colour and it derives a
+ * full, self-consistent, WCAG-legible set of roles for light and dark at any
+ * contrast level — the same dynamic theming MaterialKolor does, but ours.
+ */
+export { Hct } from './hct';
+export { TonalPalette } from './tonal-palette';
+export { DynamicScheme } from './dynamic-scheme';
+export { buildScheme, schemeVibrant, schemeExpressive, schemeTonalSpot, schemeNeutral } from './scheme-variants';
+export type { SchemeVariant } from './scheme-variants';
+export { Roles } from './color-roles';
+export type { RoleName } from './color-roles';
+export { ColorRole } from './color-role';
+export { quantizeWu } from './quantizer-wu';
+export { score } from './score';
+export type { ScoreOptions } from './score';
+export { quantizeImage, seedsFromImagePixels, seedHexFromImagePixels } from './seed-from-image';
+export { argbFromRgb, redFromArgb, greenFromArgb, blueFromArgb } from './color-utils';
+
+import { blueFromArgb, greenFromArgb, redFromArgb } from './color-utils';
+import { Roles, type RoleName } from './color-roles';
+import { Hct } from './hct';
+import { buildScheme, type SchemeVariant } from './scheme-variants';
+
+/** Parse a `#rrggbb` (or `#aarrggbb`) hex string into an ARGB int. */
+export function argbFromHex(hex: string): number {
+  const h = hex.replace('#', '');
+  const v = h.length === 6 ? `ff${h}` : h;
+  return parseInt(v, 16) >>> 0;
+}
+
+/** Format an ARGB int as `#rrggbb`. */
+export function hexFromArgb(argb: number): string {
+  const r = redFromArgb(argb).toString(16).padStart(2, '0');
+  const g = greenFromArgb(argb).toString(16).padStart(2, '0');
+  const b = blueFromArgb(argb).toString(16).padStart(2, '0');
+  return `#${r}${g}${b}`;
+}
+
+/** Every colour role as a modern `rgb(r g b)` string. */
+export type RoleColors = Record<RoleName, string>;
+
+export interface GenerateOptions {
+  /** The brand/seed colour, `#rrggbb`. */
+  seed: string;
+  variant?: SchemeVariant;
+  isDark?: boolean;
+  /** −1 (low) … 0 (normal) … 1 (high). */
+  contrastLevel?: number;
+}
+
+/**
+ * Generate the full role set from ANY seed colour — the dynamic-theming entry
+ * point. Presets are just fixed seeds; a user-picked colour works identically.
+ */
+export function generateRoleColors(opts: GenerateOptions): RoleColors {
+  const scheme = buildScheme(
+    opts.variant ?? 'vibrant',
+    Hct.fromInt(argbFromHex(opts.seed)),
+    opts.isDark ?? false,
+    opts.contrastLevel ?? 0,
+  );
+  const out = {} as RoleColors;
+  for (const name of Object.keys(Roles) as RoleName[]) {
+    const argb = Roles[name].getArgb(scheme);
+    out[name] = `rgb(${redFromArgb(argb)} ${greenFromArgb(argb)} ${blueFromArgb(argb)})`;
+  }
+  return out;
+}

package/src/theme/color-engine/lab-point-provider.ts

@@ -0,0 +1,26 @@
+/**
+ * Bloom colour engine — L*a*b* point provider.
+ *
+ * Faithful port of Material Color Utilities' `LabPointProvider` (Apache-2.0).
+ * Quantization clusters colours in L*a*b* (perceptually even), so pixels map to
+ * points and back through here, with squared-distance as the metric.
+ */
+import { argbFromLab, labFromArgb } from './color-utils';
+
+export type LabPoint = [number, number, number];
+
+export function labFromInt(argb: number): LabPoint {
+  return labFromArgb(argb);
+}
+
+export function intFromLab(point: LabPoint): number {
+  return argbFromLab(point[0], point[1], point[2]);
+}
+
+/** Squared Euclidean distance in L*a*b* (cheaper than the real distance). */
+export function labDistance(from: LabPoint, to: LabPoint): number {
+  const dL = from[0] - to[0];
+  const dA = from[1] - to[1];
+  const dB = from[2] - to[2];
+  return dL * dL + dA * dA + dB * dB;
+}

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

@@ -0,0 +1,69 @@
+/**
+ * Bloom colour engine — scalar/vector maths.
+ *
+ * Self-contained port of the Material Color Utilities maths helpers (the same
+ * primitives MaterialKolor uses), reimplemented in Bloom's own TypeScript so the
+ * theme has ZERO external colour dependencies. Algorithm © Google, Apache-2.0;
+ * this is a faithful derivative kept byte-compatible via golden tests.
+ */
+
+/** 1 if `n > 0`, -1 if `n < 0`, 0 if `n === 0`. */
+export function signum(n: number): number {
+  return n < 0 ? -1 : n === 0 ? 0 : 1;
+}
+
+/** Linear interpolation: `start` at `amount = 0`, `stop` at `amount = 1`. */
+export function lerp(start: number, stop: number, amount: number): number {
+  return (1.0 - amount) * start + amount * stop;
+}
+
+/** Clamp `input` into `[min, max]`. */
+export function clampInt(min: number, max: number, input: number): number {
+  return input < min ? min : input > max ? max : input;
+}
+
+/** Clamp `input` into `[min, max]` (floating point). */
+export function clampDouble(min: number, max: number, input: number): number {
+  return input < min ? min : input > max ? max : input;
+}
+
+/** Wrap a degree measure into `[0, 360)` as an integer. */
+export function sanitizeDegreesInt(degrees: number): number {
+  degrees = degrees % 360;
+  return degrees < 0 ? degrees + 360 : degrees;
+}
+
+/** Wrap a degree measure into `[0, 360)` as a float. */
+export function sanitizeDegreesDouble(degrees: number): number {
+  degrees = degrees % 360.0;
+  return degrees < 0 ? degrees + 360.0 : degrees;
+}
+
+/**
+ * Sign of the shortest rotation from `from` to `to` on a circle.
+ * @returns 1 if increasing `from` is shortest, -1 if decreasing is.
+ */
+export function rotationDirection(from: number, to: number): number {
+  const increasingDifference = sanitizeDegreesDouble(to - from);
+  return increasingDifference <= 180.0 ? 1.0 : -1.0;
+}
+
+/** Shortest angular distance (degrees) between two hues. */
+export function differenceDegrees(a: number, b: number): number {
+  return 180.0 - Math.abs(Math.abs(a - b) - 180.0);
+}
+
+/** Multiply a 1×3 row vector by a 3×3 matrix. */
+export function matrixMultiply(
+  row: [number, number, number],
+  matrix: [
+    [number, number, number],
+    [number, number, number],
+    [number, number, number],
+  ],
+): [number, number, number] {
+  const a = row[0] * matrix[0][0] + row[1] * matrix[0][1] + row[2] * matrix[0][2];
+  const b = row[0] * matrix[1][0] + row[1] * matrix[1][1] + row[2] * matrix[1][2];
+  const c = row[0] * matrix[2][0] + row[1] * matrix[2][1] + row[2] * matrix[2][2];
+  return [a, b, c];
+}

package/src/theme/color-engine/quantizer-map.ts

@@ -0,0 +1,17 @@
+/**
+ * Bloom colour engine — exact colour histogram.
+ *
+ * Faithful port of Material Color Utilities' `QuantizerMap` (Apache-2.0). Counts
+ * how many opaque pixels are each exact colour — the input to Wu quantization.
+ */
+import { alphaFromArgb } from './color-utils';
+
+/** Count opaque pixels by exact ARGB. Fully-transparent pixels are dropped. */
+export function countByColor(pixels: number[]): Map<number, number> {
+  const counts = new Map<number, number>();
+  for (const pixel of pixels) {
+    if (alphaFromArgb(pixel) < 255) continue;
+    counts.set(pixel, (counts.get(pixel) ?? 0) + 1);
+  }
+  return counts;
+}