@1agh/maude 0.24.0 → 0.26.0

package/plugins/design/dev-server/draw/palette.ts

@@ -0,0 +1,417 @@
+/**
+ * @file       draw/palette.ts — Phase 25 geometry-engine color layer
+ * @scope      plugins/design/dev-server/draw/palette.ts
+ * @purpose    Color correctness the draw-agent verifies from SOURCE, never from
+ *             the vision model (VLMs misread color confidently):
+ *               • WCAG 2.1 relative-luminance + contrast ratio (4.5 / 3 / 7);
+ *               • OKLCH → sRGB conversion (Björn Ottosson constants) so ramps
+ *                 are generated in a perceptually uniform space;
+ *               • evenly-spaced lightness ramps (rubric check 16);
+ *               • 60-30-10 area-distribution check (accent ≤ ~15%).
+ *             Pure + deterministic; React-free (DDR-067).
+ */
+
+export const CURRENT_COLOR = 'currentColor';
+
+export interface Rgb {
+  /** 0–255 */
+  r: number;
+  g: number;
+  b: number;
+}
+
+export interface Oklch {
+  /** Lightness 0–1. */
+  l: number;
+  /** Chroma (≈0–0.4). */
+  c: number;
+  /** Hue in degrees. */
+  h: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Parsing
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a hex (`#rgb`, `#rrggbb`, `#rrggbbaa`) or `rgb()/rgba()` string to
+ * 0–255 channels. Throws on anything else (use {@link oklchToRgb} for OKLCH).
+ */
+export function parseColor(input: string): Rgb {
+  const s = input.trim();
+  if (s.startsWith('#')) {
+    let hex = s.slice(1);
+    if (hex.length === 3 || hex.length === 4) {
+      hex = hex
+        .split('')
+        .map((ch) => ch + ch)
+        .join('');
+    }
+    if (hex.length !== 6 && hex.length !== 8) throw new Error(`parseColor: bad hex "${input}"`);
+    const r = Number.parseInt(hex.slice(0, 2), 16);
+    const g = Number.parseInt(hex.slice(2, 4), 16);
+    const b = Number.parseInt(hex.slice(4, 6), 16);
+    if ([r, g, b].some((n) => Number.isNaN(n))) throw new Error(`parseColor: bad hex "${input}"`);
+    return { r, g, b };
+  }
+  const m = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i.exec(s);
+  if (m) return { r: Number(m[1]), g: Number(m[2]), b: Number(m[3]) };
+  throw new Error(`parseColor: unsupported color "${input}" (hex or rgb() only)`);
+}
+
+/** Parse an `oklch(L C H)` string (L as `%` or 0–1) into an {@link Oklch}. */
+export function parseOklch(input: string): Oklch {
+  const m = /^oklch\(\s*([\d.]+%?)\s+([\d.]+)\s+([\d.]+)/i.exec(input.trim());
+  if (!m) throw new Error(`parseOklch: bad oklch "${input}"`);
+  const lraw = m[1];
+  const l = lraw.endsWith('%') ? Number(lraw.slice(0, -1)) / 100 : Number(lraw);
+  return { l, c: Number(m[2]), h: Number(m[3]) };
+}
+
+export function toHex({ r, g, b }: Rgb): string {
+  const h = (n: number) =>
+    Math.max(0, Math.min(255, Math.round(n)))
+      .toString(16)
+      .padStart(2, '0');
+  return `#${h(r)}${h(g)}${h(b)}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// WCAG contrast
+// ─────────────────────────────────────────────────────────────────────────────
+
+function srgbToLinear(c8: number): number {
+  const c = c8 / 255;
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+/** WCAG 2.1 relative luminance (0 = black, 1 = white). */
+export function relativeLuminance(color: Rgb | string): number {
+  const { r, g, b } = typeof color === 'string' ? parseColor(color) : color;
+  return 0.2126 * srgbToLinear(r) + 0.7152 * srgbToLinear(g) + 0.0722 * srgbToLinear(b);
+}
+
+/** WCAG contrast ratio between two colors (1–21). Order-independent. */
+export function contrastRatio(a: Rgb | string, b: Rgb | string): number {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  const hi = Math.max(la, lb);
+  const lo = Math.min(la, lb);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+export type WcagLevel = 'AA' | 'AAA';
+
+/**
+ * Does `ratio` clear the WCAG bar? `large` = ≥18.66px bold / ≥24px regular
+ * (3:1 at AA). `nonText` = UI components / graphical objects (always 3:1).
+ */
+export function meetsWcag(
+  ratio: number,
+  opts: { level?: WcagLevel; large?: boolean; nonText?: boolean } = {}
+): boolean {
+  const { level = 'AA', large = false, nonText = false } = opts;
+  if (nonText) return ratio >= 3;
+  if (level === 'AAA') return ratio >= (large ? 4.5 : 7);
+  return ratio >= (large ? 3 : 4.5);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// OKLCH → sRGB (Björn Ottosson)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function linearToSrgb8(c: number): number {
+  const v = c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055;
+  return Math.max(0, Math.min(255, Math.round(v * 255)));
+}
+
+/** Convert OKLCH (L 0–1, C, H°) to clamped sRGB 0–255. */
+export function oklchToRgb({ l, c, h }: Oklch): Rgb {
+  const hr = (h * Math.PI) / 180;
+  const a = c * Math.cos(hr);
+  const b = c * Math.sin(hr);
+
+  const l_ = l + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = l - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = l - 0.0894841775 * a - 1.291485548 * b;
+
+  const lc = l_ * l_ * l_;
+  const mc = m_ * m_ * m_;
+  const sc = s_ * s_ * s_;
+
+  const rLin = 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
+  const gLin = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
+  const bLin = -0.0041960863 * lc - 0.7034186147 * mc + 1.707614701 * sc;
+
+  return { r: linearToSrgb8(rLin), g: linearToSrgb8(gLin), b: linearToSrgb8(bLin) };
+}
+
+export function oklchToHex(o: Oklch): string {
+  return toHex(oklchToRgb(o));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Ramp generation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface RampOpts {
+  hue: number;
+  chroma: number;
+  /** Number of tiers (default 5). */
+  count?: number;
+  /** Lightest / darkest tier lightness (default 0.95 / 0.2). */
+  lMax?: number;
+  lMin?: number;
+}
+
+/**
+ * An OKLCH tonal ramp with evenly spaced lightness — perceptually uniform by
+ * construction (rubric check 16). Each tier holds chroma + hue constant; only
+ * lightness steps, lightest first. Returns OKLCH tiers (convert with
+ * {@link oklchToHex} as needed).
+ */
+export function oklchRamp(opts: RampOpts): Oklch[] {
+  const { hue, chroma, count = 5, lMax = 0.95, lMin = 0.2 } = opts;
+  if (count < 1) return [];
+  if (count === 1) return [{ l: (lMax + lMin) / 2, c: chroma, h: hue }];
+  const step = (lMax - lMin) / (count - 1);
+  const out: Oklch[] = [];
+  for (let i = 0; i < count; i++) {
+    out.push({ l: lMax - step * i, c: chroma, h: hue });
+  }
+  return out;
+}
+
+/**
+ * Are the lightness values of a ramp evenly spaced (within `tol`)? The
+ * machine-checkable form of "perceptually even ramp". Needs ≥3 tiers.
+ */
+export function isPerceptuallyEven(ramp: Oklch[], tol = 0.01): boolean {
+  if (ramp.length < 3) return true;
+  const deltas: number[] = [];
+  for (let i = 1; i < ramp.length; i++) deltas.push(ramp[i].l - ramp[i - 1].l);
+  const mean = deltas.reduce((a, b) => a + b, 0) / deltas.length;
+  return deltas.every((d) => Math.abs(d - mean) <= tol);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 60-30-10 distribution
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface AreaShare {
+  role: string;
+  area: number;
+}
+
+export interface DistributionResult {
+  byRole: Record<string, number>;
+  accentRatio: number;
+  dominantRole: string | null;
+  /** True when an accent role exists and stays ≤ 15% of total area. */
+  ok: boolean;
+}
+
+/**
+ * Check a composition's color area distribution against the 60-30-10 guideline.
+ * Roles whose name contains `accent` are summed as the accent budget; the check
+ * passes when that budget is ≤ 15% of the total painted area (rubric check 14).
+ */
+export function colorDistribution(shares: AreaShare[]): DistributionResult {
+  const total = shares.reduce((a, s) => a + Math.max(0, s.area), 0);
+  const byRole: Record<string, number> = {};
+  let accent = 0;
+  let dominantRole: string | null = null;
+  let dominantArea = -1;
+  for (const s of shares) {
+    const ratio = total > 0 ? s.area / total : 0;
+    byRole[s.role] = (byRole[s.role] ?? 0) + ratio;
+    if (/accent/i.test(s.role)) accent += ratio;
+    if (s.area > dominantArea) {
+      dominantArea = s.area;
+      dominantRole = s.role;
+    }
+  }
+  return { byRole, accentRatio: accent, dominantRole, ok: accent > 0 && accent <= 0.15 };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Color harmony — Cohen-Or et al. eight hue-wheel templates (SIGGRAPH 2006)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** One wedge of a harmonic template: a sector centered at `center`° (relative to
+ *  the template's rotation) spanning `arc`° of the hue wheel. */
+export interface HarmonyWedge {
+  center: number;
+  arc: number;
+}
+
+/**
+ * The eight Cohen-Or harmonic templates (`i V L I T Y X` + achromatic `N`),
+ * expressed as hue-wheel wedges relative to a rotation. These encode the classic
+ * schemes: `i` = monochromatic, `I` = complementary, `V`/`Y` = analogous /
+ * split, `X` = double-complementary, `T` = a 180° span. Used BOTH to generate a
+ * harmonious palette (snap hues into the wedges) AND to score harmony (distance
+ * of a palette's hues to the nearest template).
+ */
+export const HARMONY_TEMPLATES: Record<string, HarmonyWedge[]> = {
+  i: [{ center: 0, arc: 18 }],
+  V: [{ center: 0, arc: 93.6 }],
+  L: [
+    { center: 0, arc: 18 },
+    { center: 90, arc: 79.2 },
+  ],
+  I: [
+    { center: 0, arc: 18 },
+    { center: 180, arc: 18 },
+  ],
+  T: [{ center: 0, arc: 180 }],
+  Y: [
+    { center: 0, arc: 93.6 },
+    { center: 180, arc: 18 },
+  ],
+  X: [
+    { center: 0, arc: 93.6 },
+    { center: 180, arc: 93.6 },
+  ],
+};
+
+/** Smallest absolute angular difference between two hues (degrees, 0–180). */
+export function hueDelta(a: number, b: number): number {
+  const d = Math.abs(((a - b) % 360) + 360) % 360;
+  return d > 180 ? 360 - d : d;
+}
+
+/** Angular distance from hue `h` to the nearest edge of a wedge (0 if inside). */
+function distToWedge(h: number, w: HarmonyWedge, rotation: number): number {
+  const d = hueDelta(h, w.center + rotation);
+  return Math.max(0, d - w.arc / 2);
+}
+
+function minDistToTemplate(h: number, tmpl: HarmonyWedge[], rotation: number): number {
+  let best = Number.POSITIVE_INFINITY;
+  for (const w of tmpl) best = Math.min(best, distToWedge(h, w, rotation));
+  return best;
+}
+
+/**
+ * Saturation-weighted distance of a hue set to a harmonic template at a given
+ * rotation — the Cohen-Or harmony metric. 0 = every hue inside a wedge
+ * (harmonious); larger = more disharmony. `sats` (0–1, default 1) weight vivid
+ * colors more (a gray hue barely matters).
+ */
+export function harmonyDistance(
+  hues: number[],
+  template: keyof typeof HARMONY_TEMPLATES,
+  rotation: number,
+  sats?: number[]
+): number {
+  const tmpl = HARMONY_TEMPLATES[template];
+  let sum = 0;
+  for (let i = 0; i < hues.length; i++) {
+    const s = sats?.[i] ?? 1;
+    sum += s * minDistToTemplate(hues[i], tmpl, rotation);
+  }
+  return sum;
+}
+
+export interface HarmonyFit {
+  template: keyof typeof HARMONY_TEMPLATES;
+  rotation: number;
+  distance: number;
+}
+
+/**
+ * Find the best-fitting harmonic template + rotation for a hue set (brute search
+ * over templates × rotations at 2° steps). The returned `distance` is the
+ * discriminating critic metric: ≈0 = harmonious, large = "fighting colors".
+ */
+export function bestHarmony(hues: number[], sats?: number[]): HarmonyFit {
+  let best: HarmonyFit = { template: 'i', rotation: 0, distance: Number.POSITIVE_INFINITY };
+  for (const template of Object.keys(HARMONY_TEMPLATES) as (keyof typeof HARMONY_TEMPLATES)[]) {
+    for (let rotation = 0; rotation < 360; rotation += 2) {
+      const distance = harmonyDistance(hues, template, rotation, sats);
+      if (distance < best.distance) best = { template, rotation, distance };
+    }
+  }
+  return best;
+}
+
+/**
+ * Snap each hue into the nearest wedge of a template (rotated) — generation-side
+ * harmonization. Hues already inside a wedge are unchanged; outliers clamp to the
+ * nearest wedge edge. Returns the harmonized hues (use these to build the palette).
+ */
+export function harmonize(
+  hues: number[],
+  template: keyof typeof HARMONY_TEMPLATES,
+  rotation = 0
+): number[] {
+  const tmpl = HARMONY_TEMPLATES[template];
+  return hues.map((h) => {
+    let best = h;
+    let bestD = Number.POSITIVE_INFINITY;
+    for (const w of tmpl) {
+      const lo = w.center + rotation - w.arc / 2;
+      const hi = w.center + rotation + w.arc / 2;
+      const inside = distToWedge(h, w, rotation) === 0;
+      if (inside) return ((h % 360) + 360) % 360;
+      // distance to each edge; clamp to the closer one
+      const dLo = hueDelta(h, lo);
+      const dHi = hueDelta(h, hi);
+      const edge = dLo < dHi ? lo : hi;
+      const d = Math.min(dLo, dHi);
+      if (d < bestD) {
+        bestD = d;
+        best = edge;
+      }
+    }
+    return ((best % 360) + 360) % 360;
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Value / contrast — value does the work, color gets the credit
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The WCAG-luminance value range (max − min) across a color set, 0–1. The
+ * "muddy / washed-out" detector: a composition whose colors differ in hue but
+ * cluster in a narrow value band reads as flat soup (exactly the failure that
+ * sank the pastel + the neon-overlap backgrounds). A premium composition needs a
+ * value range that actually spans (rule of thumb: ≥ ~0.35 for a scene with depth).
+ */
+export function valueRange(colors: Array<Rgb | string>): number {
+  if (colors.length === 0) return 0;
+  const ls = colors.map((c) => relativeLuminance(c));
+  return Math.max(...ls) - Math.min(...ls);
+}
+
+function apcaLum(color: Rgb | string): number {
+  const { r, g, b } = typeof color === 'string' ? parseColor(color) : color;
+  // APCA uses a straight 2.4 power (not the WCAG piecewise linearization).
+  const y = 0.2126 * (r / 255) ** 2.4 + 0.7152 * (g / 255) ** 2.4 + 0.0722 * (b / 255) ** 2.4;
+  // biome-ignore lint/suspicious/noApproximativeNumericConstant: APCA-0.98G blkClmp exponent (1.414) for the 0.022 black-soft-clamp — a defined spec constant, NOT √2.
+  return y < 0.022 ? y + (0.022 - y) ** 1.414 : y;
+}
+
+/**
+ * APCA lightness contrast (Lc) between text and background — the perceptual
+ * contrast metric WCAG 3 is built on (value does the perceptual work). Returns
+ * |Lc| 0–~108. Thresholds (text): Lc 90 body-preferred, 75 body-min, 60 content,
+ * 45 large/heavy; Lc 15 is the floor for ANY visible element. Implements the
+ * APCA-0.98G constants; pin the version before treating a number as standard.
+ */
+export function apcaLc(text: Rgb | string, bg: Rgb | string): number {
+  const ytxt = apcaLum(text);
+  const ybg = apcaLum(bg);
+  let sapc: number;
+  let out: number;
+  if (ybg > ytxt) {
+    sapc = (ybg ** 0.56 - ytxt ** 0.57) * 1.14;
+    out = sapc < 0.1 ? 0 : (sapc - 0.027) * 100;
+  } else {
+    sapc = (ybg ** 0.65 - ytxt ** 0.62) * 1.14;
+    out = sapc > -0.1 ? 0 : (sapc + 0.027) * 100;
+  }
+  return Math.abs(out);
+}