@rafters/color-utils 0.2.3

package/src/apca-w3.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Type declarations for apca-w3 library
+ * apca-w3 is a vanilla JS library with no official TypeScript types
+ */
+declare module 'apca-w3' {
+  export function APCAcontrast(txtY: number, bgY: number, places?: number): number;
+
+  export function sRGBtoY(rgb: [number, number, number, number?]): number;
+
+  export function displayP3toY(rgb: [number, number, number, number?]): number;
+
+  export function adobeRGBtoY(rgb: [number, number, number, number?]): number;
+
+  export function alphaBlend(
+    rgbaFG: [number, number, number, number?],
+    rgbBG: [number, number, number],
+    round?: boolean,
+  ): [number, number, number];
+
+  export function fontLookupAPCA(contrast: number, places?: number): number[];
+
+  export function calcAPCA(
+    textColor: [number, number, number, number?],
+    bgColor: [number, number, number, number?],
+    places?: number,
+    round?: boolean,
+  ): number;
+}

package/src/builder.ts

@@ -0,0 +1,164 @@
+/**
+ * ColorValue Builder
+ *
+ * Builds a complete ColorValue from an OKLCH input using pure math.
+ * No AI, no network calls - just deterministic color calculations.
+ *
+ * This is the single source of truth for constructing ColorValue objects
+ * with all computed properties (scale, harmonies, accessibility, etc.)
+ */
+
+import type { ColorValue, OKLCH } from '@rafters/shared';
+import {
+  assembleWcagAccessibility,
+  calculateAPCAContrast,
+  CONTRAST_BLACK,
+  CONTRAST_WHITE,
+  minFontSizeForAPCA,
+} from './accessibility.js';
+import {
+  calculateAtmosphericWeight,
+  calculatePerceptualWeight,
+  getColorTemperature,
+  isLightColor,
+} from './analysis.js';
+import { generateHarmony, generateOKLCHScale } from './harmony.js';
+import { generateColorName } from './naming/index.js';
+import { SCALE_POSITIONS } from './scale-positions.js';
+import { generateSemanticColorSuggestions } from './semantic.js';
+
+/**
+ * Options for building a ColorValue
+ */
+export interface BuildColorValueOptions {
+  /**
+   * Semantic token assignment (e.g., "primary", "destructive")
+   */
+  token?: string;
+
+  /**
+   * Scale position reference (e.g., "500", "400")
+   */
+  value?: string;
+
+  /**
+   * Human notes about the color choice
+   */
+  use?: string;
+
+  /**
+   * State mappings (e.g., { hover: "blue-900", focus: "blue-700" })
+   */
+  states?: Record<string, string>;
+}
+
+/**
+ * Build a complete ColorValue from OKLCH using pure math calculations.
+ *
+ * This function computes:
+ * - 11-position scale (50-950)
+ * - Color harmonies (complementary, triadic, analogous, tetradic, monochromatic)
+ * - Accessibility metadata (WCAG AA/AAA, APCA, contrast on white/black)
+ * - Color analysis (temperature, lightness)
+ * - Atmospheric and perceptual weights
+ * - Semantic color suggestions (danger, success, warning, info)
+ *
+ * @param oklch - The base color in OKLCH format
+ * @param options - Optional metadata (token, value, use, states)
+ * @returns A complete ColorValue with all computed properties
+ *
+ * @example
+ * ```ts
+ * import { buildColorValue } from '@rafters/color-utils';
+ *
+ * const primary = buildColorValue(
+ *   { l: 0.5, c: 0.15, h: 240, alpha: 1 },
+ *   { token: 'primary', use: 'Brand primary color' }
+ * );
+ *
+ * console.log(primary.name); // e.g., "slate-bold-sapphire"
+ * console.log(primary.scale.length); // 11
+ * console.log(primary.accessibility.onWhite.wcagAA); // true/false
+ * ```
+ */
+export function buildColorValue(oklch: OKLCH, options: BuildColorValueOptions = {}): ColorValue {
+  // Generate the 11-position scale
+  const scaleRecord = generateOKLCHScale(oklch);
+  const scale = SCALE_POSITIONS.map((pos) => scaleRecord[pos]).filter(
+    (v): v is OKLCH => v !== undefined,
+  );
+
+  // Generate harmonies
+  const harmony = generateHarmony(oklch);
+
+  // WCAG accessibility (pair matrices + on-white/on-black) via the shared
+  // assembler; APCA is layered on below, builder-only.
+  const wcagAccessibility = assembleWcagAccessibility(scale, oklch);
+  const apcaOnWhite = calculateAPCAContrast(oklch, CONTRAST_WHITE);
+  const apcaOnBlack = calculateAPCAContrast(oklch, CONTRAST_BLACK);
+
+  // Get color analysis
+  const temperature = getColorTemperature(oklch);
+  const light = isLightColor(oklch);
+
+  // Get perceptual weights
+  const atmospheric = calculateAtmosphericWeight(oklch);
+  const perceptual = calculatePerceptualWeight(oklch);
+
+  // Get semantic suggestions
+  const semanticSuggestions = generateSemanticColorSuggestions(oklch);
+
+  // Generate the color name
+  const name = generateColorName(oklch);
+
+  // Build the complete ColorValue
+  const colorValue: ColorValue = {
+    name,
+    scale,
+    tokenId: `color-${oklch.l.toFixed(3)}-${oklch.c.toFixed(3)}-${Math.round(oklch.h)}`,
+
+    // Optional metadata from options
+    ...(options.token && { token: options.token }),
+    ...(options.value && { value: options.value }),
+    ...(options.use && { use: options.use }),
+    ...(options.states && { states: options.states }),
+
+    // Harmonies - pure hue rotation arrays
+    harmonies: {
+      complementary: harmony.complementary,
+      triadic: harmony.triadic,
+      analogous: harmony.analogous,
+      tetradic: harmony.tetradic,
+      splitComplementary: harmony.splitComplementary,
+      monochromatic: harmony.monochromatic,
+    },
+
+    // Accessibility
+    accessibility: {
+      ...wcagAccessibility,
+      apca: {
+        onWhite: apcaOnWhite,
+        onBlack: apcaOnBlack,
+        minFontSize: minFontSizeForAPCA(apcaOnWhite),
+      },
+    },
+
+    // Analysis
+    analysis: {
+      temperature,
+      isLight: light,
+      name,
+    },
+
+    // Atmospheric weight
+    atmosphericWeight: atmospheric,
+
+    // Perceptual weight
+    perceptualWeight: perceptual,
+
+    // Semantic suggestions
+    semanticSuggestions,
+  };
+
+  return colorValue;
+}

package/src/color-wheel.ts

@@ -0,0 +1,235 @@
+/**
+ * colorWheel: generate a complete 11-family semantic color system from a single OKLCH seed.
+ *
+ * Dispatches to harmony-specific functions. Complementary is fully deterministic.
+ * All other harmony types delegate to complementaryWheel until their specific
+ * semantic role mappings are designed.
+ */
+
+import type { ColorValue, OKLCH } from '@rafters/shared';
+import { buildColorValue } from './builder.js';
+import { roundOKLCH } from './conversion.js';
+import { clamp, VIVID_CHROMA_CAP } from './internal/math.js';
+import { adjustHue } from './manipulation.js';
+import { statusAnchor } from './semantic.js';
+
+export type HarmonyType =
+  | 'complementary'
+  | 'triadic'
+  | 'tetradic'
+  | 'analogous'
+  | 'split-complementary';
+
+export interface ColorWheelOptions {
+  chromaDistribution?: 'gaussian' | 'flat';
+}
+
+export interface SemanticColorSystem {
+  primary: ColorValue;
+  secondary: ColorValue;
+  tertiary: ColorValue;
+  accent: ColorValue;
+  highlight: ColorValue;
+  neutral: ColorValue;
+  muted: ColorValue;
+  success: ColorValue;
+  warning: ColorValue;
+  destructive: ColorValue;
+  info: ColorValue;
+}
+
+/**
+ * Apply gaussian chroma distribution centered at L=0.6 with sigma=0.25.
+ * Reduces chroma at light and dark extremes, preserving peak saturation
+ * near mid-tones where colors are most perceptually legible.
+ *
+ * Applied to: secondary, tertiary, highlight, neutral, muted.
+ * NOT applied to: primary (exact designer choice), accent (needs full chroma),
+ * status colors (success/warning/destructive/info must remain recognizable).
+ */
+function applyGaussianChroma(oklch: OKLCH): OKLCH {
+  const peakL = 0.6;
+  const sigma = 0.25;
+  const gaussian = Math.exp(-((oklch.l - peakL) ** 2) / (2 * sigma ** 2));
+  return { ...oklch, c: oklch.c * gaussian };
+}
+
+/**
+ * Derive secondary lightness from the primary's accessibility matrix.
+ *
+ * Uses primary's wcagAAA.normal pairs to find the scale position farthest from
+ * primary in lightness that still passes AAA. That position's OKLCH lightness
+ * becomes secondary's lightness, ensuring AAA contrast between primary and secondary.
+ *
+ * Falls back to the opposite-end heuristic (dark seed -> light secondary, vice versa)
+ * if the accessibility matrix yields no AAA pairs.
+ */
+function resolveSecondaryLightness(primaryColorValue: ColorValue, primaryOklch: OKLCH): number {
+  const aaaPairs = primaryColorValue.accessibility?.wcagAAA?.normal ?? [];
+  const scale = primaryColorValue.scale;
+
+  // Find the pair with the greatest lightness distance from primary
+  let bestL: number | null = null;
+  let bestDistance = 0;
+
+  for (const pair of aaaPairs) {
+    const idxA = pair[0];
+    const idxB = pair[1];
+    if (idxA === undefined || idxB === undefined) continue;
+
+    // Both indices in the pair are from the primary scale.
+    // We want the one that is farthest in lightness from primary.
+    for (const idx of [idxA, idxB]) {
+      const scaleColor = scale[idx];
+      if (!scaleColor) continue;
+      const dist = Math.abs(scaleColor.l - primaryOklch.l);
+      if (dist > bestDistance) {
+        bestDistance = dist;
+        bestL = scaleColor.l;
+      }
+    }
+  }
+
+  if (bestL !== null) {
+    return bestL;
+  }
+
+  // Fallback: opposite end of the lightness range
+  return primaryOklch.l > 0.5 ? 0.25 : 0.75;
+}
+
+/**
+ * Full complementary color wheel.
+ *
+ * Roles:
+ *   primary     - the seed as-is
+ *   secondary   - same hue, opposite lightness end (AAA against primary), chroma * 0.33
+ *   accent      - complement (+180), full chroma
+ *   tertiary    - CTA from complement hue, chroma * 1.2 (max 0.30), L clamped 0.45-0.65
+ *   highlight   - secondary math applied to tertiary hue
+ *   neutral     - seed hue, chroma * 0.02, L = 0.50
+ *   muted       - seed hue, chroma * 0.05, L = 0.85
+ *   success     - hue 145, L 0.55, C = min(0.18, seed.c * 0.9)
+ *   warning     - hue 85,  L 0.75, C = min(0.18, seed.c * 0.9)
+ *   destructive - hue 25,  L 0.55, C = min(0.20, seed.c)
+ *   info        - hue 230, L 0.58, C = min(0.15, seed.c * 0.85)
+ */
+function complementaryWheel(seed: OKLCH, options: ColorWheelOptions): SemanticColorSystem {
+  const useGaussian = (options.chromaDistribution ?? 'gaussian') === 'gaussian';
+  const alpha = seed.alpha ?? 1;
+
+  // primary: exact designer seed
+  const primaryColorValue = buildColorValue(seed, { token: 'primary' });
+
+  // secondary: same hue, AAA-verified lightness from primary matrix, chroma * 0.33
+  const secondaryL = resolveSecondaryLightness(primaryColorValue, seed);
+  const secondaryOklch: OKLCH = { l: secondaryL, c: seed.c * 0.33, h: seed.h, alpha };
+  const secondaryFinal = useGaussian ? applyGaussianChroma(secondaryOklch) : secondaryOklch;
+  const secondaryColorValue = buildColorValue(roundOKLCH(secondaryFinal), { token: 'secondary' });
+
+  // accent: pure complement, full chroma -- no gaussian (needs full chroma)
+  const accentOklch = adjustHue(seed, 180);
+  const accentColorValue = buildColorValue(accentOklch, { token: 'accent' });
+
+  // tertiary: CTA from complement hue, chroma boosted but capped, mid lightness
+  const tertiaryRaw: OKLCH = {
+    l: clamp(seed.l, 0.45, 0.65),
+    c: Math.min(VIVID_CHROMA_CAP, seed.c * 1.2),
+    h: accentOklch.h,
+    alpha,
+  };
+  const tertiaryFinal = useGaussian ? applyGaussianChroma(tertiaryRaw) : tertiaryRaw;
+  const tertiaryColorValue = buildColorValue(roundOKLCH(tertiaryFinal), { token: 'tertiary' });
+
+  // highlight: secondary math applied to tertiary hue
+  // AAA lightness from the tertiary's accessibility matrix, same desaturation as secondary.
+  const highlightL = resolveSecondaryLightness(tertiaryColorValue, tertiaryFinal);
+  const highlightOklch: OKLCH = {
+    l: highlightL,
+    c: tertiaryFinal.c * 0.33,
+    h: tertiaryFinal.h,
+    alpha,
+  };
+  const highlightFinal = useGaussian ? applyGaussianChroma(highlightOklch) : highlightOklch;
+  const highlightColorValue = buildColorValue(roundOKLCH(highlightFinal), { token: 'highlight' });
+
+  // neutral: seed hue, very low chroma, mid lightness
+  const neutralOklch: OKLCH = { l: 0.5, c: seed.c * 0.02, h: seed.h, alpha };
+  const neutralFinal = useGaussian ? applyGaussianChroma(neutralOklch) : neutralOklch;
+  const neutralColorValue = buildColorValue(roundOKLCH(neutralFinal), { token: 'neutral' });
+
+  // muted: seed hue, slightly more chroma than neutral, high lightness
+  const mutedOklch: OKLCH = { l: 0.85, c: seed.c * 0.05, h: seed.h, alpha };
+  const mutedFinal = useGaussian ? applyGaussianChroma(mutedOklch) : mutedOklch;
+  const mutedColorValue = buildColorValue(roundOKLCH(mutedFinal), { token: 'muted' });
+
+  // status colors -- no gaussian, must stay recognizable. Anchored by the
+  // shared STATUS_ROLE_ANCHORS (semantic.ts) so the wheel and the
+  // semanticSuggestions on every ColorValue can never drift apart.
+  const successColorValue = buildColorValue(statusAnchor('success', seed), { token: 'success' });
+  const warningColorValue = buildColorValue(statusAnchor('warning', seed), { token: 'warning' });
+  const destructiveColorValue = buildColorValue(statusAnchor('destructive', seed), {
+    token: 'destructive',
+  });
+  const infoColorValue = buildColorValue(statusAnchor('info', seed), { token: 'info' });
+
+  return {
+    primary: primaryColorValue,
+    secondary: secondaryColorValue,
+    tertiary: tertiaryColorValue,
+    accent: accentColorValue,
+    highlight: highlightColorValue,
+    neutral: neutralColorValue,
+    muted: mutedColorValue,
+    success: successColorValue,
+    warning: warningColorValue,
+    destructive: destructiveColorValue,
+    info: infoColorValue,
+  };
+}
+
+/**
+ * Generate a complete 11-family semantic color system from a single OKLCH seed.
+ *
+ * Dispatches to harmony-specific functions. Complementary is fully deterministic.
+ * Triadic, tetradic, analogous, and split-complementary delegate to complementaryWheel
+ * until their correct semantic role mappings are designed.
+ *
+ * @param seed - Base color in OKLCH
+ * @param harmony - Harmony relationship type
+ * @param options - Optional configuration (chromaDistribution: 'gaussian' | 'flat')
+ * @returns SemanticColorSystem with 11 fully-built ColorValues
+ *
+ * @example
+ * ```ts
+ * import { colorWheel } from '@rafters/color-utils';
+ *
+ * const system = colorWheel(
+ *   { l: 0.5, c: 0.15, h: 240, alpha: 1 },
+ *   'complementary'
+ * );
+ *
+ * console.log(system.primary.name);   // e.g. "slate-bold-sapphire"
+ * console.log(system.destructive.accessibility?.onWhite.wcagAAA); // true/false
+ * ```
+ */
+export function colorWheel(
+  seed: OKLCH,
+  harmony: HarmonyType,
+  options?: ColorWheelOptions,
+): SemanticColorSystem {
+  const opts = options ?? {};
+
+  switch (harmony) {
+    case 'complementary':
+      return complementaryWheel(seed, opts);
+
+    // Stubs: correct semantic role mappings need design research.
+    // Delegating to complementary until those mappings are known.
+    case 'triadic':
+    case 'tetradic':
+    case 'analogous':
+    case 'split-complementary':
+      return complementaryWheel(seed, opts);
+  }
+}

package/src/colorjs.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Type declarations for colorjs.io library
+ * Minimal subset of the API that we use
+ */
+declare module 'colorjs.io' {
+  interface ToStringOptions {
+    format?: string;
+    collapse?: boolean;
+  }
+
+  export default class Color {
+    // Constructor can take various forms
+    constructor(space: string, coords: [number, number, number], alpha?: number);
+    constructor(cssString: string);
+
+    // Color space properties
+    coords: [number | undefined, number | undefined, number | undefined];
+    alpha: number;
+    r: number;
+    g: number;
+    b: number;
+    srgb: { r: number; g: number; b: number };
+
+    // Gamut methods
+    inGamut(space?: string): boolean;
+
+    // Conversion methods
+    to(space: string): Color;
+    toGamut(options?: { space?: string; method?: string }): Color;
+    toString(options?: ToStringOptions): string;
+
+    // Static methods
+    static get(color: unknown, prop: string): number;
+    static set(color: unknown, prop: string, value: number): void;
+  }
+}

package/src/conversion.ts

@@ -0,0 +1,92 @@
+/**
+ * OKLCH color conversion functions using colorjs.io
+ */
+
+import type { OKLCH } from '@rafters/shared';
+import Color from 'colorjs.io';
+
+/** Options for formatting an OKLCH color as a CSS `oklch()` string. */
+export interface OklchToCSSOptions {
+  /**
+   * Decimal places applied to every emitted channel (L, C, H, and A when
+   * present). Omitted means no rounding: channels are stringified as-is.
+   */
+  precision?: number;
+}
+
+/**
+ * Convert OKLCH to a CSS oklch() function string.
+ *
+ * Emits `oklch(L C H)`, or `oklch(L C H / A)` when alpha is defined and not 1.
+ * With no options and no alpha the output is byte-identical to the original
+ * three-channel formatter -- design-tokens callers depend on that exact string.
+ */
+export function oklchToCSS(oklch: OKLCH, options?: OklchToCSSOptions): string {
+  const precision = options?.precision;
+  const format = (value: number): string =>
+    precision === undefined ? String(value) : value.toFixed(precision);
+
+  const base = `${format(oklch.l)} ${format(oklch.c)} ${format(oklch.h)}`;
+  const { alpha } = oklch;
+  if (alpha === undefined || alpha === 1) {
+    return `oklch(${base})`;
+  }
+  return `oklch(${base} / ${format(alpha)})`;
+}
+
+/**
+ * Convert hex string to OKLCH color object
+ */
+export function hexToOKLCH(hex: string): OKLCH {
+  try {
+    const color = new Color(hex);
+    const oklch = color.to('oklch');
+
+    // colorjs.io returns boxed `Number` objects (not primitives) for some
+    // input formats (oklch() literals notably). Schemas downstream check
+    // `typeof === 'number'` and reject boxed Numbers. Coerce to primitives
+    // here so every consumer sees plain numbers.
+    return {
+      l: Number(oklch.coords[0] ?? 0),
+      c: Number(oklch.coords[1] ?? 0),
+      // Achromatic colors (grays) get NaN hue from colorjs.io, not undefined
+      h: Number.isNaN(oklch.coords[2]) ? 0 : Number(oklch.coords[2] ?? 0),
+      alpha: Number(oklch.alpha ?? 1),
+    };
+  } catch (_error) {
+    throw new Error(`Invalid hex color: ${hex}`);
+  }
+}
+
+/**
+ * Predicate-form CSS color parser. Returns the parsed OKLCH on success and
+ * null on any parse failure (invalid format, missing channels, gibberish).
+ *
+ * Used by callers that need to test "is this string a color?" without a
+ * try/catch around `hexToOKLCH` (which throws). Despite the historical name,
+ * `hexToOKLCH` already accepts every CSS color format via colorjs.io --
+ * `tryParseColor` is just the null-on-failure wrapper.
+ */
+export function tryParseColor(css: string): OKLCH | null {
+  try {
+    return hexToOKLCH(css);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Round OKLCH values to standard precision for consistency
+ * L and C: 3 decimal places (perceptually meaningful differentiation)
+ * H: whole degrees, Alpha: 2 decimal places
+ * Prevents floating point precision issues and optimizes cache keys
+ */
+export function roundOKLCH(oklch: OKLCH): OKLCH {
+  return {
+    l: Math.round(oklch.l * 1000) / 1000,
+    c: Math.round(oklch.c * 1000) / 1000,
+    // NaN hue from achromatic colors defaults to 0
+    h: Number.isNaN(oklch.h) ? 0 : Math.round(oklch.h),
+    alpha: oklch.alpha !== undefined ? Math.round(oklch.alpha * 100) / 100 : 1,
+  };
+}

package/src/gamut.ts

@@ -0,0 +1,117 @@
+/**
+ * OKLCH gamut awareness utilities
+ *
+ * Three-tier gamut model based on real-world display support:
+ * - srgb: in sRGB (safe on every screen, also in P3 by inclusion)
+ * - p3:   in Display P3 but NOT sRGB (modern wide-gamut displays only)
+ * - out:  outside both gamuts (not displayable anywhere)
+ */
+
+import type { OKLCH } from '@rafters/shared';
+import Color from 'colorjs.io';
+import { z } from 'zod';
+import { roundOKLCH } from './conversion.js';
+import { MAX_CHROMA } from './internal/math.js';
+
+export const GamutTierSchema = z.enum(['srgb', 'p3', 'out']);
+export type GamutTier = z.infer<typeof GamutTierSchema>;
+
+export const GamutBoundaryPointSchema = z.object({
+  l: z.number(),
+  /** Maximum chroma within sRGB gamut */
+  maxC_srgb: z.number(),
+  /** Maximum chroma within P3 gamut */
+  maxC_p3: z.number(),
+});
+export type GamutBoundaryPoint = z.infer<typeof GamutBoundaryPointSchema>;
+
+/** Check whether an OKLCH color is within the sRGB gamut. */
+export function isInSRGBGamut(oklch: OKLCH): boolean {
+  const color = new Color('oklch', [oklch.l, oklch.c, oklch.h]);
+  return color.inGamut('srgb');
+}
+
+/** Check whether an OKLCH color is within the Display P3 gamut. */
+export function isInP3Gamut(oklch: OKLCH): boolean {
+  const color = new Color('oklch', [oklch.l, oklch.c, oklch.h]);
+  return color.inGamut('p3');
+}
+
+/** Classify an OKLCH color by the gamut it fits in. */
+export function getGamutTier(oklch: OKLCH): GamutTier {
+  if (isInSRGBGamut(oklch)) return 'srgb';
+  if (isInP3Gamut(oklch)) return 'p3';
+  return 'out';
+}
+
+/**
+ * Snap an OKLCH color to the nearest in-gamut color.
+ * Returns the snapped color and its tier.
+ */
+export function toNearestGamut(oklch: OKLCH): { color: OKLCH; tier: GamutTier } {
+  const color = new Color('oklch', [oklch.l, oklch.c, oklch.h]);
+
+  if (color.inGamut('srgb')) {
+    return { color: { ...oklch }, tier: 'srgb' };
+  }
+
+  const srgbMapped = color.toGamut({ space: 'srgb' });
+  const mappedOklch = srgbMapped.to('oklch');
+  return {
+    color: {
+      l: mappedOklch.coords[0] ?? 0,
+      c: mappedOklch.coords[1] ?? 0,
+      h: mappedOklch.coords[2] ?? oklch.h,
+      alpha: oklch.alpha,
+    },
+    tier: 'srgb',
+  };
+}
+
+/**
+ * Snap an OKLCH into sRGB and round it -- the shape every generated color is
+ * emitted in. Lives here because both halves are gamut/conversion concerns;
+ * harmony.ts and semantic.ts are callers, not owners.
+ */
+export function clampColor(color: OKLCH): OKLCH {
+  return roundOKLCH(toNearestGamut(color).color);
+}
+
+const DEFAULT_STEPS = 101;
+const TOLERANCE = 0.001;
+
+function findMaxChroma(l: number, h: number, gamutSpace: string): number {
+  let lo = 0;
+  let hi = MAX_CHROMA;
+  if (l <= 0 || l >= 1) return 0;
+  const maxColor = new Color('oklch', [l, hi, h]);
+  if (maxColor.inGamut(gamutSpace)) return hi;
+  while (hi - lo > TOLERANCE) {
+    const mid = (lo + hi) / 2;
+    const color = new Color('oklch', [l, mid, h]);
+    if (color.inGamut(gamutSpace)) {
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+  }
+  return lo;
+}
+
+/**
+ * Compute both sRGB and P3 gamut boundaries for a given hue.
+ * The two boundary curves define three zones:
+ *   0 .. maxC_srgb            -> srgb
+ *   maxC_srgb .. maxC_p3      -> p3
+ *   beyond maxC_p3            -> out
+ */
+export function computeGamutBoundaries(hue: number, steps = DEFAULT_STEPS): GamutBoundaryPoint[] {
+  const boundaries: GamutBoundaryPoint[] = [];
+  for (let i = 0; i < steps; i++) {
+    const l = i / (steps - 1);
+    const maxC_srgb = findMaxChroma(l, hue, 'srgb');
+    const maxC_p3 = findMaxChroma(l, hue, 'p3');
+    boundaries.push({ l, maxC_srgb, maxC_p3 });
+  }
+  return boundaries;
+}