@oxyhq/bloom 0.36.0 → 0.37.0

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

@@ -0,0 +1,320 @@
+/**
+ * Bloom colour engine — Wu colour quantizer.
+ *
+ * Faithful port of Material Color Utilities' `QuantizerWu` (Apache-2.0). Builds a
+ * 3-D histogram of the image in a 32³ RGB grid, computes cumulative moments, then
+ * greedily splits the colour cube along the axis of greatest variance until it
+ * has `maxColors` boxes — each box's mean colour is a representative. Fully
+ * DETERMINISTIC (no k-means/randomness), which is why Bloom uses it directly.
+ */
+import { blueFromArgb, greenFromArgb, redFromArgb } from './color-utils';
+import { countByColor } from './quantizer-map';
+
+const INDEX_BITS = 5;
+const SIDE_LENGTH = 33; // (1 << INDEX_BITS) + 1
+const TOTAL_SIZE = 35937; // SIDE_LENGTH³
+
+type Direction = 'red' | 'green' | 'blue';
+
+interface Box {
+  r0: number;
+  r1: number;
+  g0: number;
+  g1: number;
+  b0: number;
+  b1: number;
+  vol: number;
+}
+
+const makeBox = (): Box => ({ r0: 0, r1: 0, g0: 0, g1: 0, b0: 0, b1: 0, vol: 0 });
+
+/**
+ * Read a moment/weight cell. Every index here is produced by `getIndex` (or a
+ * bounded loop) and is always in range for the fixed-size grids, but under
+ * `noUncheckedIndexedAccess` the element type is `number | undefined`; this
+ * asserts the in-range invariant honestly instead of masking it.
+ */
+function cell(grid: number[], index: number): number {
+  const value = grid[index];
+  if (value === undefined) throw new RangeError(`quantizer grid index ${index} out of range`);
+  return value;
+}
+
+/** Read a colour box by index (the box array is fully pre-populated). */
+function boxAt(cubes: Box[], index: number): Box {
+  const box = cubes[index];
+  if (box === undefined) throw new RangeError(`quantizer box index ${index} out of range`);
+  return box;
+}
+
+function getIndex(r: number, g: number, b: number): number {
+  return (r << (INDEX_BITS * 2)) + (r << (INDEX_BITS + 1)) + r + (g << INDEX_BITS) + g + b;
+}
+
+/** Wu-quantize `pixels` into at most `maxColors` representative ARGB colours. */
+export function quantizeWu(pixels: number[], maxColors: number): number[] {
+  const weights = new Array<number>(TOTAL_SIZE).fill(0);
+  const momentsR = new Array<number>(TOTAL_SIZE).fill(0);
+  const momentsG = new Array<number>(TOTAL_SIZE).fill(0);
+  const momentsB = new Array<number>(TOTAL_SIZE).fill(0);
+  const moments = new Array<number>(TOTAL_SIZE).fill(0);
+
+  // Histogram.
+  const counts = countByColor(pixels);
+  const bitsToRemove = 8 - INDEX_BITS;
+  for (const [pixel, count] of counts.entries()) {
+    const red = redFromArgb(pixel);
+    const green = greenFromArgb(pixel);
+    const blue = blueFromArgb(pixel);
+    const index = getIndex((red >> bitsToRemove) + 1, (green >> bitsToRemove) + 1, (blue >> bitsToRemove) + 1);
+    weights[index] = cell(weights, index) + count;
+    momentsR[index] = cell(momentsR, index) + count * red;
+    momentsG[index] = cell(momentsG, index) + count * green;
+    momentsB[index] = cell(momentsB, index) + count * blue;
+    moments[index] = cell(moments, index) + count * (red * red + green * green + blue * blue);
+  }
+
+  // Cumulative moments.
+  for (let r = 1; r < SIDE_LENGTH; r++) {
+    const area = new Array<number>(SIDE_LENGTH).fill(0);
+    const areaR = new Array<number>(SIDE_LENGTH).fill(0);
+    const areaG = new Array<number>(SIDE_LENGTH).fill(0);
+    const areaB = new Array<number>(SIDE_LENGTH).fill(0);
+    const area2 = new Array<number>(SIDE_LENGTH).fill(0.0);
+    for (let g = 1; g < SIDE_LENGTH; g++) {
+      let line = 0;
+      let lineR = 0;
+      let lineG = 0;
+      let lineB = 0;
+      let line2 = 0.0;
+      for (let b = 1; b < SIDE_LENGTH; b++) {
+        const index = getIndex(r, g, b);
+        line += cell(weights, index);
+        lineR += cell(momentsR, index);
+        lineG += cell(momentsG, index);
+        lineB += cell(momentsB, index);
+        line2 += cell(moments, index);
+        area[b] = cell(area, b) + line;
+        areaR[b] = cell(areaR, b) + lineR;
+        areaG[b] = cell(areaG, b) + lineG;
+        areaB[b] = cell(areaB, b) + lineB;
+        area2[b] = cell(area2, b) + line2;
+        const prev = getIndex(r - 1, g, b);
+        weights[index] = cell(weights, prev) + cell(area, b);
+        momentsR[index] = cell(momentsR, prev) + cell(areaR, b);
+        momentsG[index] = cell(momentsG, prev) + cell(areaG, b);
+        momentsB[index] = cell(momentsB, prev) + cell(areaB, b);
+        moments[index] = cell(moments, prev) + cell(area2, b);
+      }
+    }
+  }
+
+  const volume = (cube: Box, moment: number[]): number =>
+    cell(moment, getIndex(cube.r1, cube.g1, cube.b1)) -
+    cell(moment, getIndex(cube.r1, cube.g1, cube.b0)) -
+    cell(moment, getIndex(cube.r1, cube.g0, cube.b1)) +
+    cell(moment, getIndex(cube.r1, cube.g0, cube.b0)) -
+    cell(moment, getIndex(cube.r0, cube.g1, cube.b1)) +
+    cell(moment, getIndex(cube.r0, cube.g1, cube.b0)) +
+    cell(moment, getIndex(cube.r0, cube.g0, cube.b1)) -
+    cell(moment, getIndex(cube.r0, cube.g0, cube.b0));
+
+  const bottom = (cube: Box, direction: Direction, moment: number[]): number => {
+    switch (direction) {
+      case 'red':
+        return (
+          -cell(moment, getIndex(cube.r0, cube.g1, cube.b1)) +
+          cell(moment, getIndex(cube.r0, cube.g1, cube.b0)) +
+          cell(moment, getIndex(cube.r0, cube.g0, cube.b1)) -
+          cell(moment, getIndex(cube.r0, cube.g0, cube.b0))
+        );
+      case 'green':
+        return (
+          -cell(moment, getIndex(cube.r1, cube.g0, cube.b1)) +
+          cell(moment, getIndex(cube.r1, cube.g0, cube.b0)) +
+          cell(moment, getIndex(cube.r0, cube.g0, cube.b1)) -
+          cell(moment, getIndex(cube.r0, cube.g0, cube.b0))
+        );
+      case 'blue':
+        return (
+          -cell(moment, getIndex(cube.r1, cube.g1, cube.b0)) +
+          cell(moment, getIndex(cube.r1, cube.g0, cube.b0)) +
+          cell(moment, getIndex(cube.r0, cube.g1, cube.b0)) -
+          cell(moment, getIndex(cube.r0, cube.g0, cube.b0))
+        );
+    }
+  };
+
+  const top = (cube: Box, direction: Direction, position: number, moment: number[]): number => {
+    switch (direction) {
+      case 'red':
+        return (
+          cell(moment, getIndex(position, cube.g1, cube.b1)) -
+          cell(moment, getIndex(position, cube.g1, cube.b0)) -
+          cell(moment, getIndex(position, cube.g0, cube.b1)) +
+          cell(moment, getIndex(position, cube.g0, cube.b0))
+        );
+      case 'green':
+        return (
+          cell(moment, getIndex(cube.r1, position, cube.b1)) -
+          cell(moment, getIndex(cube.r1, position, cube.b0)) -
+          cell(moment, getIndex(cube.r0, position, cube.b1)) +
+          cell(moment, getIndex(cube.r0, position, cube.b0))
+        );
+      case 'blue':
+        return (
+          cell(moment, getIndex(cube.r1, cube.g1, position)) -
+          cell(moment, getIndex(cube.r1, cube.g0, position)) -
+          cell(moment, getIndex(cube.r0, cube.g1, position)) +
+          cell(moment, getIndex(cube.r0, cube.g0, position))
+        );
+    }
+  };
+
+  const variance = (cube: Box): number => {
+    const dr = volume(cube, momentsR);
+    const dg = volume(cube, momentsG);
+    const db = volume(cube, momentsB);
+    const xx =
+      cell(moments, getIndex(cube.r1, cube.g1, cube.b1)) -
+      cell(moments, getIndex(cube.r1, cube.g1, cube.b0)) -
+      cell(moments, getIndex(cube.r1, cube.g0, cube.b1)) +
+      cell(moments, getIndex(cube.r1, cube.g0, cube.b0)) -
+      cell(moments, getIndex(cube.r0, cube.g1, cube.b1)) +
+      cell(moments, getIndex(cube.r0, cube.g1, cube.b0)) +
+      cell(moments, getIndex(cube.r0, cube.g0, cube.b1)) -
+      cell(moments, getIndex(cube.r0, cube.g0, cube.b0));
+    const hypotenuse = dr * dr + dg * dg + db * db;
+    return xx - hypotenuse / volume(cube, weights);
+  };
+
+  const maximize = (
+    cube: Box,
+    direction: Direction,
+    first: number,
+    last: number,
+    wholeR: number,
+    wholeG: number,
+    wholeB: number,
+    wholeW: number,
+  ): { cutLocation: number; maximum: number } => {
+    const bottomR = bottom(cube, direction, momentsR);
+    const bottomG = bottom(cube, direction, momentsG);
+    const bottomB = bottom(cube, direction, momentsB);
+    const bottomW = bottom(cube, direction, weights);
+    let max = 0.0;
+    let cut = -1;
+    for (let i = first; i < last; i++) {
+      let halfR = bottomR + top(cube, direction, i, momentsR);
+      let halfG = bottomG + top(cube, direction, i, momentsG);
+      let halfB = bottomB + top(cube, direction, i, momentsB);
+      let halfW = bottomW + top(cube, direction, i, weights);
+      if (halfW === 0) continue;
+      let temp = (halfR * halfR + halfG * halfG + halfB * halfB) / halfW;
+      halfR = wholeR - halfR;
+      halfG = wholeG - halfG;
+      halfB = wholeB - halfB;
+      halfW = wholeW - halfW;
+      if (halfW === 0) continue;
+      temp += (halfR * halfR + halfG * halfG + halfB * halfB) / halfW;
+      if (temp > max) {
+        max = temp;
+        cut = i;
+      }
+    }
+    return { cutLocation: cut, maximum: max };
+  };
+
+  const cut = (one: Box, two: Box): boolean => {
+    const wholeR = volume(one, momentsR);
+    const wholeG = volume(one, momentsG);
+    const wholeB = volume(one, momentsB);
+    const wholeW = volume(one, weights);
+    const maxR = maximize(one, 'red', one.r0 + 1, one.r1, wholeR, wholeG, wholeB, wholeW);
+    const maxG = maximize(one, 'green', one.g0 + 1, one.g1, wholeR, wholeG, wholeB, wholeW);
+    const maxB = maximize(one, 'blue', one.b0 + 1, one.b1, wholeR, wholeG, wholeB, wholeW);
+    let direction: Direction;
+    if (maxR.maximum >= maxG.maximum && maxR.maximum >= maxB.maximum) {
+      if (maxR.cutLocation < 0) return false;
+      direction = 'red';
+    } else if (maxG.maximum >= maxR.maximum && maxG.maximum >= maxB.maximum) {
+      direction = 'green';
+    } else {
+      direction = 'blue';
+    }
+    two.r1 = one.r1;
+    two.g1 = one.g1;
+    two.b1 = one.b1;
+    switch (direction) {
+      case 'red':
+        one.r1 = maxR.cutLocation;
+        two.r0 = one.r1;
+        two.g0 = one.g0;
+        two.b0 = one.b0;
+        break;
+      case 'green':
+        one.g1 = maxG.cutLocation;
+        two.r0 = one.r0;
+        two.g0 = one.g1;
+        two.b0 = one.b0;
+        break;
+      case 'blue':
+        one.b1 = maxB.cutLocation;
+        two.r0 = one.r0;
+        two.g0 = one.g0;
+        two.b0 = one.b1;
+        break;
+    }
+    one.vol = (one.r1 - one.r0) * (one.g1 - one.g0) * (one.b1 - one.b0);
+    two.vol = (two.r1 - two.r0) * (two.g1 - two.g0) * (two.b1 - two.b0);
+    return true;
+  };
+
+  // Greedily split the colour cube.
+  const cubes: Box[] = Array.from({ length: maxColors }, makeBox);
+  const volumeVariance = new Array<number>(maxColors).fill(0.0);
+  const firstCube = boxAt(cubes, 0);
+  firstCube.r0 = 0;
+  firstCube.g0 = 0;
+  firstCube.b0 = 0;
+  firstCube.r1 = SIDE_LENGTH - 1;
+  firstCube.g1 = SIDE_LENGTH - 1;
+  firstCube.b1 = SIDE_LENGTH - 1;
+  let generatedColorCount = maxColors;
+  let next = 0;
+  for (let i = 1; i < maxColors; i++) {
+    if (cut(boxAt(cubes, next), boxAt(cubes, i))) {
+      volumeVariance[next] = boxAt(cubes, next).vol > 1 ? variance(boxAt(cubes, next)) : 0.0;
+      volumeVariance[i] = boxAt(cubes, i).vol > 1 ? variance(boxAt(cubes, i)) : 0.0;
+    } else {
+      volumeVariance[next] = 0.0;
+      i--;
+    }
+    next = 0;
+    let temp = cell(volumeVariance, 0);
+    for (let j = 1; j <= i; j++) {
+      if (cell(volumeVariance, j) > temp) {
+        temp = cell(volumeVariance, j);
+        next = j;
+      }
+    }
+    if (temp <= 0.0) {
+      generatedColorCount = i + 1;
+      break;
+    }
+  }
+
+  // Mean colour of each box.
+  const colors: number[] = [];
+  for (let i = 0; i < generatedColorCount; i++) {
+    const cube = boxAt(cubes, i);
+    const weight = volume(cube, weights);
+    if (weight > 0) {
+      const r = Math.round(volume(cube, momentsR) / weight);
+      const g = Math.round(volume(cube, momentsG) / weight);
+      const b = Math.round(volume(cube, momentsB) / weight);
+      colors.push(((255 << 24) | ((r & 0x0ff) << 16) | ((g & 0x0ff) << 8) | (b & 0x0ff)) >>> 0);
+    }
+  }
+  return colors;
+}

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

@@ -0,0 +1,113 @@
+/**
+ * Bloom colour engine — scheme variants.
+ *
+ * How each variant derives its five tonal palettes from the seed HCT. Faithful
+ * port of Material Color Utilities' `Scheme*` families (Apache-2.0), expressed
+ * as plain builder functions (our style) rather than subclasses. Fidelity/
+ * Content are intentionally left out — they need the temperature-cache complement
+ * and aren't useful for Bloom's fixed brand seeds.
+ */
+import { DynamicScheme } from './dynamic-scheme';
+import type { Hct } from './hct';
+import { sanitizeDegreesDouble } from './math-utils';
+import { TonalPalette } from './tonal-palette';
+import { Variant } from './variant';
+
+export type SchemeVariant = 'vibrant' | 'expressive' | 'tonalSpot' | 'neutral';
+
+const VIBRANT_HUES = [0.0, 41.0, 61.0, 101.0, 131.0, 181.0, 251.0, 301.0, 360.0];
+const VIBRANT_SECONDARY_ROTATIONS = [18.0, 15.0, 10.0, 12.0, 15.0, 18.0, 15.0, 12.0, 12.0];
+const VIBRANT_TERTIARY_ROTATIONS = [35.0, 30.0, 20.0, 25.0, 30.0, 35.0, 30.0, 25.0, 25.0];
+
+const EXPRESSIVE_HUES = [0.0, 21.0, 51.0, 121.0, 151.0, 191.0, 271.0, 321.0, 360.0];
+const EXPRESSIVE_SECONDARY_ROTATIONS = [45.0, 95.0, 45.0, 20.0, 45.0, 90.0, 45.0, 45.0, 45.0];
+const EXPRESSIVE_TERTIARY_ROTATIONS = [120.0, 120.0, 20.0, 45.0, 20.0, 15.0, 20.0, 120.0, 120.0];
+
+/** Maxed-out colourfulness at each position of the primary palette. */
+export function schemeVibrant(source: Hct, isDark: boolean, contrastLevel: number): DynamicScheme {
+  return new DynamicScheme({
+    sourceColorArgb: source.toInt(),
+    variant: Variant.VIBRANT,
+    contrastLevel,
+    isDark,
+    primaryPalette: TonalPalette.fromHueAndChroma(source.hue, 200.0),
+    secondaryPalette: TonalPalette.fromHueAndChroma(
+      DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_SECONDARY_ROTATIONS),
+      24.0,
+    ),
+    tertiaryPalette: TonalPalette.fromHueAndChroma(
+      DynamicScheme.getRotatedHue(source, VIBRANT_HUES, VIBRANT_TERTIARY_ROTATIONS),
+      32.0,
+    ),
+    neutralPalette: TonalPalette.fromHueAndChroma(source.hue, 10.0),
+    neutralVariantPalette: TonalPalette.fromHueAndChroma(source.hue, 12.0),
+  });
+}
+
+/** Playful, intentionally detached from the seed hue (primary rotated 240°). */
+export function schemeExpressive(source: Hct, isDark: boolean, contrastLevel: number): DynamicScheme {
+  return new DynamicScheme({
+    sourceColorArgb: source.toInt(),
+    variant: Variant.EXPRESSIVE,
+    contrastLevel,
+    isDark,
+    primaryPalette: TonalPalette.fromHueAndChroma(sanitizeDegreesDouble(source.hue + 240.0), 40.0),
+    secondaryPalette: TonalPalette.fromHueAndChroma(
+      DynamicScheme.getRotatedHue(source, EXPRESSIVE_HUES, EXPRESSIVE_SECONDARY_ROTATIONS),
+      24.0,
+    ),
+    tertiaryPalette: TonalPalette.fromHueAndChroma(
+      DynamicScheme.getRotatedHue(source, EXPRESSIVE_HUES, EXPRESSIVE_TERTIARY_ROTATIONS),
+      32.0,
+    ),
+    neutralPalette: TonalPalette.fromHueAndChroma(source.hue + 15, 8.0),
+    neutralVariantPalette: TonalPalette.fromHueAndChroma(source.hue + 15, 12.0),
+  });
+}
+
+/** The Material You default — a calm, balanced treatment of the seed. */
+export function schemeTonalSpot(source: Hct, isDark: boolean, contrastLevel: number): DynamicScheme {
+  return new DynamicScheme({
+    sourceColorArgb: source.toInt(),
+    variant: Variant.TONAL_SPOT,
+    contrastLevel,
+    isDark,
+    primaryPalette: TonalPalette.fromHueAndChroma(source.hue, 36.0),
+    secondaryPalette: TonalPalette.fromHueAndChroma(source.hue, 16.0),
+    tertiaryPalette: TonalPalette.fromHueAndChroma(sanitizeDegreesDouble(source.hue + 60.0), 24.0),
+    neutralPalette: TonalPalette.fromHueAndChroma(source.hue, 6.0),
+    neutralVariantPalette: TonalPalette.fromHueAndChroma(source.hue, 8.0),
+  });
+}
+
+/** Near-greyscale — the seed hue is present only as a whisper. */
+export function schemeNeutral(source: Hct, isDark: boolean, contrastLevel: number): DynamicScheme {
+  return new DynamicScheme({
+    sourceColorArgb: source.toInt(),
+    variant: Variant.NEUTRAL,
+    contrastLevel,
+    isDark,
+    primaryPalette: TonalPalette.fromHueAndChroma(source.hue, 12.0),
+    secondaryPalette: TonalPalette.fromHueAndChroma(source.hue, 8.0),
+    tertiaryPalette: TonalPalette.fromHueAndChroma(source.hue, 16.0),
+    neutralPalette: TonalPalette.fromHueAndChroma(source.hue, 2.0),
+    neutralVariantPalette: TonalPalette.fromHueAndChroma(source.hue, 2.0),
+  });
+}
+
+const BUILDERS: Record<SchemeVariant, (s: Hct, d: boolean, c: number) => DynamicScheme> = {
+  vibrant: schemeVibrant,
+  expressive: schemeExpressive,
+  tonalSpot: schemeTonalSpot,
+  neutral: schemeNeutral,
+};
+
+/** Build a scheme by variant name. */
+export function buildScheme(
+  variant: SchemeVariant,
+  source: Hct,
+  isDark: boolean,
+  contrastLevel = 0,
+): DynamicScheme {
+  return BUILDERS[variant](source, isDark, contrastLevel);
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Bloom colour engine — seed scoring.
+ *
+ * Faithful port of Material Color Utilities' `Score` (Apache-2.0). Given a map
+ * of quantized colours → population, ranks them for theme suitability — favouring
+ * colours whose hue is well-represented in the image AND chromatic enough to make
+ * a good accent — and de-duplicates by hue. Returns the best seed candidates.
+ */
+import { Hct } from './hct';
+import { differenceDegrees, sanitizeDegreesInt } from './math-utils';
+
+const TARGET_CHROMA = 48.0;
+const WEIGHT_PROPORTION = 0.7;
+const WEIGHT_CHROMA_ABOVE = 0.3;
+const WEIGHT_CHROMA_BELOW = 0.1;
+const CUTOFF_CHROMA = 5.0;
+const CUTOFF_EXCITED_PROPORTION = 0.01;
+
+export interface ScoreOptions {
+  desired?: number;
+  fallbackColorARGB?: number;
+  filter?: boolean;
+}
+
+/** Rank quantized colours as theme seeds. Best first. */
+export function score(colorsToPopulation: Map<number, number>, options: ScoreOptions = {}): number[] {
+  const desired = options.desired ?? 4;
+  const fallbackColorARGB = options.fallbackColorARGB ?? 0xff4285f4;
+  const filter = options.filter ?? true;
+
+  const colorsHct: Hct[] = [];
+  const huePopulation = new Array<number>(360).fill(0);
+  let populationSum = 0;
+  for (const [argb, population] of colorsToPopulation.entries()) {
+    const hct = Hct.fromInt(argb);
+    colorsHct.push(hct);
+    const hueIndex = Math.floor(hct.hue);
+    huePopulation[hueIndex] = (huePopulation[hueIndex] ?? 0) + population;
+    populationSum += population;
+  }
+
+  const hueExcitedProportions = new Array<number>(360).fill(0.0);
+  for (let hue = 0; hue < 360; hue++) {
+    const proportion = (huePopulation[hue] ?? 0) / populationSum;
+    for (let i = hue - 14; i < hue + 16; i++) {
+      const index = sanitizeDegreesInt(i);
+      hueExcitedProportions[index] = (hueExcitedProportions[index] ?? 0) + proportion;
+    }
+  }
+
+  const scoredHct: Array<{ hct: Hct; score: number }> = [];
+  for (const hct of colorsHct) {
+    const hue = sanitizeDegreesInt(Math.round(hct.hue));
+    const proportion = hueExcitedProportions[hue] ?? 0;
+    if (filter && (hct.chroma < CUTOFF_CHROMA || proportion <= CUTOFF_EXCITED_PROPORTION)) {
+      continue;
+    }
+    const proportionScore = proportion * 100.0 * WEIGHT_PROPORTION;
+    const chromaWeight = hct.chroma < TARGET_CHROMA ? WEIGHT_CHROMA_BELOW : WEIGHT_CHROMA_ABOVE;
+    const chromaScore = (hct.chroma - TARGET_CHROMA) * chromaWeight;
+    scoredHct.push({ hct, score: proportionScore + chromaScore });
+  }
+  scoredHct.sort((a, b) => (a.score > b.score ? -1 : a.score < b.score ? 1 : 0));
+
+  const chosenColors: Hct[] = [];
+  for (let differenceLimit = 90; differenceLimit >= 15; differenceLimit--) {
+    chosenColors.length = 0;
+    for (const { hct } of scoredHct) {
+      const duplicateHue = chosenColors.find(
+        (chosen) => differenceDegrees(hct.hue, chosen.hue) < differenceLimit,
+      );
+      if (!duplicateHue) chosenColors.push(hct);
+      if (chosenColors.length >= desired) break;
+    }
+    if (chosenColors.length >= desired) break;
+  }
+
+  const colors: number[] = [];
+  if (chosenColors.length === 0) colors.push(fallbackColorARGB);
+  for (const chosen of chosenColors) colors.push(chosen.toInt());
+  return colors;
+}

package/src/theme/color-engine/seed-from-image.ts

@@ -0,0 +1,64 @@
+/**
+ * Bloom colour engine — a seed colour from an image.
+ *
+ * The "theme from your photo/wallpaper" entry point. Wu-quantizes the pixels to
+ * a small representative palette, tallies each pixel to its nearest
+ * representative (a deterministic single assignment in L*a*b* — Bloom's stand-in
+ * for the reference's stochastic k-means, so results are reproducible), then
+ * scores the palette for theme suitability. Feed the top result straight into
+ * `generateRoleColors({ seed })`.
+ */
+import { hexFromArgb } from './index';
+import { labDistance, labFromInt, type LabPoint } from './lab-point-provider';
+import { quantizeWu } from './quantizer-wu';
+import { countByColor } from './quantizer-map';
+import { score, type ScoreOptions } from './score';
+
+/**
+ * Quantize `pixels` to a representative palette with its populations. Uses Wu
+ * (deterministic) for the palette, then assigns every pixel to its nearest
+ * representative in L*a*b* — no randomness, so the same image always yields the
+ * same result.
+ */
+export function quantizeImage(pixels: number[], maxColors = 128): Map<number, number> {
+  const representatives = quantizeWu(pixels, maxColors);
+  if (representatives.length === 0) return new Map();
+  const repPoints: LabPoint[] = representatives.map(labFromInt);
+
+  const populations = new Array<number>(representatives.length).fill(0);
+  for (const [pixel, count] of countByColor(pixels).entries()) {
+    const point = labFromInt(pixel);
+    let best = 0;
+    let bestDistance = Infinity;
+    for (let i = 0; i < repPoints.length; i++) {
+      const repPoint = repPoints[i];
+      if (repPoint === undefined) continue;
+      const d = labDistance(point, repPoint);
+      if (d < bestDistance) {
+        bestDistance = d;
+        best = i;
+      }
+    }
+    populations[best] = (populations[best] ?? 0) + count;
+  }
+
+  const result = new Map<number, number>();
+  for (let i = 0; i < representatives.length; i++) {
+    const representative = representatives[i];
+    const population = populations[i] ?? 0;
+    if (representative !== undefined && population > 0) result.set(representative, population);
+  }
+  return result;
+}
+
+/** Ranked seed candidates (best first) extracted from an image's pixels (ARGB). */
+export function seedsFromImagePixels(pixels: number[], options?: ScoreOptions): number[] {
+  return score(quantizeImage(pixels), options);
+}
+
+/** The single best seed colour from an image, as `#rrggbb`. */
+export function seedHexFromImagePixels(pixels: number[]): string {
+  const [top] = seedsFromImagePixels(pixels, { desired: 1 });
+  if (top === undefined) throw new Error('no seed colour could be extracted');
+  return hexFromArgb(top);
+}

package/src/theme/color-engine/tonal-palette.ts

@@ -0,0 +1,94 @@
+/**
+ * Bloom colour engine — tonal palettes.
+ *
+ * Faithful port of Material Color Utilities' `TonalPalette` (Apache-2.0). A
+ * palette holds a fixed hue + chroma and yields a colour for any tone (0–100).
+ * Schemes build primary/secondary/tertiary/neutral palettes and read specific
+ * tones per role.
+ */
+import { Hct } from './hct';
+
+export class TonalPalette {
+  private readonly cache = new Map<number, number>();
+
+  private constructor(
+    readonly hue: number,
+    readonly chroma: number,
+    readonly keyColor: Hct,
+  ) {}
+
+  static fromInt(argb: number): TonalPalette {
+    return TonalPalette.fromHct(Hct.fromInt(argb));
+  }
+
+  static fromHct(hct: Hct): TonalPalette {
+    return new TonalPalette(hct.hue, hct.chroma, hct);
+  }
+
+  static fromHueAndChroma(hue: number, chroma: number): TonalPalette {
+    const keyColor = new KeyColor(hue, chroma).create();
+    return new TonalPalette(hue, chroma, keyColor);
+  }
+
+  /** ARGB of this palette at the given tone. */
+  tone(tone: number): number {
+    let argb = this.cache.get(tone);
+    if (argb === undefined) {
+      argb = Hct.from(this.hue, this.chroma, tone).toInt();
+      this.cache.set(tone, argb);
+    }
+    return argb;
+  }
+
+  /** HCT of this palette at the given tone. */
+  getHct(tone: number): Hct {
+    return Hct.fromInt(this.tone(tone));
+  }
+}
+
+/** The colour that represents a palette's hue + chroma (first from T50). */
+class KeyColor {
+  private readonly chromaCache = new Map<number, number>();
+  private readonly maxChromaValue = 200.0;
+
+  constructor(
+    private readonly hue: number,
+    private readonly requestedChroma: number,
+  ) {}
+
+  create(): Hct {
+    const pivotTone = 50;
+    const toneStepSize = 1;
+    const epsilon = 0.01;
+    let lowerTone = 0;
+    let upperTone = 100;
+    while (lowerTone < upperTone) {
+      const midTone = Math.floor((lowerTone + upperTone) / 2);
+      const isAscending = this.maxChroma(midTone) < this.maxChroma(midTone + toneStepSize);
+      const sufficientChroma = this.maxChroma(midTone) >= this.requestedChroma - epsilon;
+      if (sufficientChroma) {
+        if (Math.abs(lowerTone - pivotTone) < Math.abs(upperTone - pivotTone)) {
+          upperTone = midTone;
+        } else {
+          if (lowerTone === midTone) {
+            return Hct.from(this.hue, this.requestedChroma, lowerTone);
+          }
+          lowerTone = midTone;
+        }
+      } else if (isAscending) {
+        lowerTone = midTone + toneStepSize;
+      } else {
+        upperTone = midTone;
+      }
+    }
+    return Hct.from(this.hue, this.requestedChroma, lowerTone);
+  }
+
+  private maxChroma(tone: number): number {
+    const cached = this.chromaCache.get(tone);
+    if (cached !== undefined) return cached;
+    const chroma = Hct.from(this.hue, this.maxChromaValue, tone).chroma;
+    this.chromaCache.set(tone, chroma);
+    return chroma;
+  }
+}

package/src/theme/color-engine/tone-delta-pair.ts

@@ -0,0 +1,21 @@
+/**
+ * Bloom colour engine — tone-delta pair.
+ *
+ * Faithful port of Material Color Utilities' `ToneDeltaPair` (Apache-2.0).
+ * Constrains two related roles to keep a minimum tonal distance in a given
+ * direction (e.g. a fixed colour must stay lighter than its dim variant), so
+ * paired roles never collapse into each other.
+ */
+import type { ColorRole } from './color-role';
+
+export type TonePolarity = 'darker' | 'lighter' | 'nearer' | 'farther';
+
+export class ToneDeltaPair {
+  constructor(
+    readonly roleA: ColorRole,
+    readonly roleB: ColorRole,
+    readonly delta: number,
+    readonly polarity: TonePolarity,
+    readonly stayTogether: boolean,
+  ) {}
+}