quick-palette 0.2.0

package/dist/cli/prompt.js

@@ -0,0 +1,279 @@
+import { createInterface } from "node:readline/promises";
+import { clearScreenDown, cursorTo, emitKeypressEvents, moveCursor } from "node:readline";
+import { stdin, stdout } from "node:process";
+import { normalizeHex } from "../core/color.js";
+import { COLOR_FAMILY_CANDIDATES, MOOD_CANDIDATES, USE_CASE_CANDIDATES, } from "../core/constants.js";
+export class PromptCancelledError extends Error {
+    constructor() {
+        super("Prompt cancelled.");
+        this.name = "PromptCancelledError";
+    }
+}
+export function createPromptInterface() {
+    const rl = createInterface({ input: stdin, output: stdout, terminal: Boolean(stdin.isTTY) });
+    const lines = stdin.isTTY ? undefined : rl[Symbol.asyncIterator]();
+    const prompt = {
+        async question(message) {
+            if (!lines)
+                return rl.question(message);
+            stdout.write(message);
+            const line = await lines.next();
+            if (line.done)
+                throw new Error("Input was closed before the prompts were completed.");
+            return line.value;
+        },
+        close: () => rl.close(),
+    };
+    if (stdin.isTTY && stdout.isTTY) {
+        prompt.choose = (question, options, defaultValue) => (selectWithCursor(question, options, defaultValue));
+        prompt.readExplorationAction = readExplorationAction;
+    }
+    return prompt;
+}
+export function promptStartupMode(rl) {
+    return select(rl, "How would you like to start?", [
+        { label: "Explore random palettes", value: "explore" },
+        { label: "Create a custom palette", value: "configure" },
+    ], "explore");
+}
+export function promptExplorationAction(rl) {
+    if (rl.readExplorationAction) {
+        console.log("\nEnter: accept   Space: next   e: edit   q: quit");
+        return rl.readExplorationAction();
+    }
+    return select(rl, "What would you like to do?", [
+        { label: "Accept this palette", value: "accept" },
+        { label: "Show the next palette", value: "next" },
+        { label: "Edit this palette", value: "edit" },
+        { label: "Quit", value: "quit" },
+    ], "accept");
+}
+export async function promptBaseColor(rl, currentValue) {
+    const currentOption = currentValue === undefined
+        ? []
+        : [{ label: `Keep current base color (${currentValue})`, value: "current" }];
+    const method = await select(rl, "How would you like to choose the base color?", [
+        ...currentOption,
+        { label: "Enter a HEX value", value: "hex" },
+        { label: "Choose a color family", value: "family" },
+        { label: "Choose a mood", value: "mood" },
+        { label: "Choose a use case", value: "use-case" },
+    ], currentValue === undefined ? undefined : "current");
+    if (method === "current")
+        return currentValue;
+    if (method === "hex")
+        return promptHex(rl);
+    if (method === "family") {
+        const family = await selectKeys(rl, "Choose a color family:", COLOR_FAMILY_CANDIDATES);
+        return promptCandidate(rl, COLOR_FAMILY_CANDIDATES[family]);
+    }
+    if (method === "mood") {
+        const mood = await selectKeys(rl, "Choose a mood:", MOOD_CANDIDATES);
+        return promptCandidate(rl, MOOD_CANDIDATES[mood]);
+    }
+    const useCase = await selectKeys(rl, "Choose a use case:", USE_CASE_CANDIDATES);
+    return promptCandidate(rl, USE_CASE_CANDIDATES[useCase]);
+}
+export function promptHarmony(rl, defaultValue) {
+    return select(rl, "Choose a color harmony:", [
+        { label: "Monochrome (1 hue + neutrals)", value: "monochrome" },
+        { label: "Analogous (3 neighboring hues + neutrals)", value: "analogous" },
+        { label: "Complementary (2 opposite hues + neutrals)", value: "complementary" },
+        { label: "Triadic (3 evenly spaced hues + neutrals)", value: "triadic" },
+    ], defaultValue);
+}
+export function promptHarmonyTuning(rl, defaultValue = "mechanical") {
+    return select(rl, "How should the harmony colors be adjusted?", [
+        { label: "Fixed angles (predictable)", value: "mechanical" },
+        { label: "UI (restrained accents)", value: "ui" },
+        { label: "Branding (vivid accents)", value: "branding" },
+        { label: "Data visualization (separated colors)", value: "data-visualization" },
+    ], defaultValue);
+}
+export function promptNeutralMode(rl, defaultValue) {
+    return select(rl, "Choose a neutral palette:", [
+        { label: "Neutral gray", value: "neutral" },
+        { label: "Base-tinted gray", value: "tinted" },
+    ], defaultValue);
+}
+export function promptConfigurationAction(rl) {
+    return select(rl, "Choose an action:", [
+        { label: "Finish and print HEX values", value: "accept" },
+        { label: "Export as JSON or CSS", value: "export" },
+        { label: "Change palette settings", value: "edit" },
+    ], "accept");
+}
+export function promptConfigurationEditAction(rl) {
+    return select(rl, "What would you like to edit?", [
+        { label: "Base color", value: "base" },
+        { label: "Color harmony", value: "harmony" },
+        { label: "Neutral palette", value: "neutral" },
+        { label: "Step counts", value: "steps" },
+        { label: "Cancel editing", value: "cancel" },
+    ]);
+}
+export function promptExportFormat(rl) {
+    return select(rl, "Choose an export format:", [
+        { label: "JSON", value: "json" },
+        { label: "CSS", value: "css" },
+        { label: "Back to palette", value: "back" },
+    ]);
+}
+export function promptStepCount(rl, label, defaultValue) {
+    return select(rl, `${label} (default: ${defaultValue}):`, [
+        { label: "3 steps", value: 3 },
+        { label: "5 steps", value: 5 },
+        { label: "7 steps", value: 7 },
+        { label: "9 steps", value: 9 },
+    ], defaultValue);
+}
+export async function promptExportDestination(rl, format) {
+    const label = format.toUpperCase();
+    const mode = await select(rl, `Where should the ${label} output go?`, [
+        { label: "Print to the terminal", value: "print" },
+        { label: "Save to a file", value: "save" },
+        { label: "Back to format selection", value: "back" },
+    ], "print");
+    if (mode !== "save")
+        return { mode };
+    while (true) {
+        const path = (await rl.question(`${label} output path: `)).trim();
+        if (path)
+            return { mode, path };
+        console.log(`Enter a path for the ${label} output file.`);
+    }
+}
+export function promptExportCompleteAction(rl) {
+    return select(rl, "Export complete. What would you like to do?", [
+        { label: "Done", value: "done" },
+        { label: "Export another format", value: "another" },
+        { label: "Back to palette", value: "back" },
+    ], "done");
+}
+async function promptHex(rl) {
+    while (true) {
+        const answer = await rl.question("Enter a HEX color (#RGB or #RRGGBB): ");
+        try {
+            return normalizeHex(answer);
+        }
+        catch {
+            console.log("Enter a valid HEX color, such as #2563EB or #F80.");
+        }
+    }
+}
+async function promptCandidate(rl, candidates) {
+    return select(rl, "Choose a base color:", candidates.map((candidate) => ({
+        label: `${candidate.name} (${candidate.hex})`,
+        value: candidate.hex,
+    })));
+}
+async function selectKeys(rl, question, values) {
+    return select(rl, question, Object.keys(values).map((key) => ({
+        label: titleCase(key),
+        value: key,
+    })));
+}
+export async function select(rl, question, options, defaultValue) {
+    if (rl.choose)
+        return rl.choose(question, options, defaultValue);
+    while (true) {
+        console.log(`\n${question}`);
+        options.forEach((option, index) => console.log(`  ${index + 1}. ${option.label}`));
+        const answer = (await rl.question("> ")).trim();
+        if (answer === "" && defaultValue !== undefined)
+            return defaultValue;
+        const selected = Number(answer) - 1;
+        const option = options[selected];
+        if (Number.isInteger(selected) && option)
+            return option.value;
+        console.log(`Enter a number from 1 to ${options.length}.`);
+    }
+}
+async function selectWithCursor(question, options, defaultValue) {
+    if (options.length === 0)
+        throw new Error("At least one option is required.");
+    const defaultIndex = defaultValue === undefined
+        ? -1
+        : options.findIndex((option) => Object.is(option.value, defaultValue));
+    let selectedIndex = defaultIndex >= 0 ? defaultIndex : 0;
+    console.log(`\n${question}`);
+    renderCursorOptions(options, selectedIndex, false);
+    emitKeypressEvents(stdin);
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    try {
+        return await new Promise((resolve, reject) => {
+            const onKeypress = (_input, key) => {
+                if (key.ctrl && key.name === "c") {
+                    stdin.off("keypress", onKeypress);
+                    reject(new PromptCancelledError());
+                    return;
+                }
+                if (key.name === "up" || key.name === "down") {
+                    const direction = key.name === "up" ? -1 : 1;
+                    selectedIndex = (selectedIndex + direction + options.length) % options.length;
+                    renderCursorOptions(options, selectedIndex, true);
+                    return;
+                }
+                if (key.name === "return" || key.name === "enter") {
+                    stdin.off("keypress", onKeypress);
+                    resolve(options[selectedIndex].value);
+                }
+            };
+            stdin.on("keypress", onKeypress);
+        });
+    }
+    finally {
+        stdin.setRawMode(Boolean(wasRaw));
+    }
+}
+async function readExplorationAction() {
+    emitKeypressEvents(stdin);
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    try {
+        return await new Promise((resolve, reject) => {
+            const onKeypress = (input, key) => {
+                if (key.ctrl && key.name === "c") {
+                    stdin.off("keypress", onKeypress);
+                    reject(new PromptCancelledError());
+                    return;
+                }
+                const action = explorationActionForKey(input, key.name);
+                if (action) {
+                    stdin.off("keypress", onKeypress);
+                    stdout.write("\n");
+                    resolve(action);
+                }
+            };
+            stdin.on("keypress", onKeypress);
+        });
+    }
+    finally {
+        stdin.setRawMode(Boolean(wasRaw));
+    }
+}
+export function explorationActionForKey(input, keyName) {
+    if (keyName === "return" || keyName === "enter")
+        return "accept";
+    if (keyName === "space" || input === " ")
+        return "next";
+    if (input.toLowerCase() === "e")
+        return "edit";
+    if (input.toLowerCase() === "q")
+        return "quit";
+    return undefined;
+}
+function renderCursorOptions(options, selectedIndex, redraw) {
+    if (redraw) {
+        moveCursor(stdout, 0, -options.length);
+        cursorTo(stdout, 0);
+        clearScreenDown(stdout);
+    }
+    stdout.write(`${options.map((option, index) => (`${index === selectedIndex ? ">" : " "} ${option.label}`)).join("\n")}\n`);
+}
+function titleCase(value) {
+    return value.replaceAll("-", " ").replace(/\b\w/g, (letter) => letter.toUpperCase());
+}

package/dist/cli/terminal-color.js

@@ -0,0 +1,13 @@
+export function hexToRgb(hex) {
+    return {
+        r: Number.parseInt(hex.slice(1, 3), 16),
+        g: Number.parseInt(hex.slice(3, 5), 16),
+        b: Number.parseInt(hex.slice(5, 7), 16),
+    };
+}
+export function formatColorSwatch(hex, useColor) {
+    if (!useColor)
+        return `  ${hex}`;
+    const { r, g, b } = hexToRgb(hex);
+    return `  \u001B[48;2;${r};${g};${b}m    \u001B[0m  ${hex}`;
+}

package/dist/core/color.js

@@ -0,0 +1,58 @@
+import Color from "colorjs.io";
+const HEX_PATTERN = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+const CHROMA_DECREMENT = 0.002;
+export class InvalidHexColorError extends Error {
+    constructor(value) {
+        super(`Invalid HEX color: ${value}`);
+        this.name = "InvalidHexColorError";
+    }
+}
+export function normalizeHex(value) {
+    const trimmed = value.trim();
+    if (!HEX_PATTERN.test(trimmed)) {
+        throw new InvalidHexColorError(value);
+    }
+    const digits = trimmed.slice(1);
+    const expanded = digits.length === 3
+        ? digits.split("").map((digit) => digit.repeat(2)).join("")
+        : digits;
+    return `#${expanded.toUpperCase()}`;
+}
+export function isValidHex(value) {
+    return HEX_PATTERN.test(value.trim());
+}
+export function hexToOklch(value) {
+    const [l, c, hue] = new Color(normalizeHex(value)).to("oklch").coords;
+    return {
+        l: l ?? 0,
+        c: c ?? 0,
+        h: Number.isFinite(hue) ? hue : 0,
+    };
+}
+export function isInSrgb(color) {
+    return new Color("oklch", [color.l, color.c, normalizeHue(color.h)]).inGamut("srgb");
+}
+export function oklchToHex(color) {
+    const mapped = mapToSrgb(color).to("srgb");
+    const channels = mapped.coords.map((channel) => {
+        const value = Math.min(1, Math.max(0, channel ?? 0));
+        return Math.round(value * 255).toString(16).padStart(2, "0");
+    });
+    return `#${channels.join("").toUpperCase()}`;
+}
+export function mapToSrgb(color) {
+    const l = Math.min(1, Math.max(0, color.l));
+    const h = normalizeHue(color.h);
+    let c = Math.max(0, color.c);
+    while (c > 0) {
+        const candidate = new Color("oklch", [l, c, h]);
+        if (candidate.inGamut("srgb")) {
+            return candidate;
+        }
+        c = Math.max(0, c - CHROMA_DECREMENT);
+    }
+    return new Color("oklch", [l, 0, h]);
+}
+export function normalizeHue(hue) {
+    return ((hue % 360) + 360) % 360;
+}

package/dist/core/constants.js

@@ -0,0 +1,64 @@
+import { HARMONY_MODES, HARMONY_TUNINGS, NEUTRAL_MODES, } from "./types.js";
+export const COLOR_FAMILY_CANDIDATES = {
+    red: [{ name: "Crimson", hex: "#DC2626" }, { name: "Rose", hex: "#E11D48" }],
+    orange: [{ name: "Orange", hex: "#EA580C" }, { name: "Amber", hex: "#D97706" }],
+    yellow: [{ name: "Gold", hex: "#CA8A04" }, { name: "Lemon", hex: "#EAB308" }],
+    green: [{ name: "Emerald", hex: "#059669" }, { name: "Forest", hex: "#15803D" }],
+    blue: [{ name: "Blue", hex: "#2563EB" }, { name: "Sky", hex: "#0284C7" }],
+    purple: [{ name: "Violet", hex: "#7C3AED" }, { name: "Purple", hex: "#9333EA" }],
+};
+export const MOOD_CANDIDATES = {
+    calm: [{ name: "Quiet Blue", hex: "#3B82F6" }, { name: "Soft Teal", hex: "#0D9488" }],
+    energetic: [{ name: "Bright Orange", hex: "#F97316" }, { name: "Hot Pink", hex: "#DB2777" }],
+    elegant: [{ name: "Deep Navy", hex: "#1E3A8A" }, { name: "Burgundy", hex: "#881337" }],
+    playful: [{ name: "Candy Purple", hex: "#A855F7" }, { name: "Fresh Green", hex: "#22C55E" }],
+};
+export const USE_CASE_CANDIDATES = {
+    brand: [{ name: "Confident Blue", hex: "#2563EB" }, { name: "Bold Red", hex: "#DC2626" }],
+    dashboard: [{ name: "Data Blue", hex: "#0369A1" }, { name: "Data Teal", hex: "#0F766E" }],
+    editorial: [{ name: "Ink", hex: "#334155" }, { name: "Accent Red", hex: "#BE123C" }],
+    wellness: [{ name: "Sage", hex: "#65A30D" }, { name: "Ocean", hex: "#0891B2" }],
+};
+export const HUE_OFFSETS = {
+    monochrome: [0],
+    analogous: [-30, 0, 30],
+    complementary: [0, 180],
+    triadic: [0, 120, 240],
+};
+export const COLOR_LIGHTNESS_RANGE = { min: 0.35, max: 0.9 };
+export const NEUTRAL_LIGHTNESS_RANGE = { min: 0.18, max: 0.98 };
+export const TINTED_NEUTRAL_MAX_CHROMA = 0.02;
+export const TINTED_NEUTRAL_CHROMA_RATIO = 0.12;
+export const DEFAULT_COLOR_STEPS = 5;
+export const DEFAULT_NEUTRAL_STEPS = 5;
+export const RANDOM_BASE_COLORS = [
+    ...new Set([
+        ...Object.values(COLOR_FAMILY_CANDIDATES).flat().map(({ hex }) => hex),
+        ...Object.values(MOOD_CANDIDATES).flat().map(({ hex }) => hex),
+        ...Object.values(USE_CASE_CANDIDATES).flat().map(({ hex }) => hex),
+    ]),
+];
+export const RANDOM_HARMONIES = HARMONY_MODES;
+export const RANDOM_HARMONY_TUNINGS = HARMONY_TUNINGS;
+export const RANDOM_NEUTRAL_MODES = NEUTRAL_MODES;
+export const PERCEPTUAL_HUE_SHIFTS = [-12, -8, -4, 0, 4, 8, 12];
+export const PERCEPTUAL_REPRESENTATIVE_LIGHTNESS = 0.625;
+export const PERCEPTUAL_MIN_DISTANCE = 0.08;
+export const PERCEPTUAL_COLLAPSE_DISTANCE = 0.035;
+// UI and branding scores are maximized. Data visualization uses a lexicographic
+// comparison so chroma cannot override its minimum-distance priority.
+export const PERCEPTUAL_SCORING_WEIGHTS = {
+    ui: {
+        chromaRetention: 20,
+        minimumDistance: 3,
+        targetDeviation: 0.02,
+        collapse: 10,
+    },
+    branding: {
+        chromaRetention: 30,
+        minimumDistance: 8,
+        baseSeparation: 2,
+        targetDeviation: 0.005,
+        collapse: 12,
+    },
+};

package/dist/core/generate.js

@@ -0,0 +1,40 @@
+import { COLOR_LIGHTNESS_RANGE, HUE_OFFSETS, NEUTRAL_LIGHTNESS_RANGE, TINTED_NEUTRAL_CHROMA_RATIO, TINTED_NEUTRAL_MAX_CHROMA, } from "./constants.js";
+import { hexToOklch, normalizeHex, normalizeHue, oklchToHex } from "./color.js";
+import { tuneHarmonyHues } from "./perceptual-harmony.js";
+const ACHROMATIC_CHROMA_THRESHOLD = 0.001;
+export function generatePalette(input) {
+    const config = { ...input, baseColor: normalizeHex(input.baseColor) };
+    const base = hexToOklch(config.baseColor);
+    const lightness = interpolate(COLOR_LIGHTNESS_RANGE.min, COLOR_LIGHTNESS_RANGE.max, config.colorSteps);
+    const mechanicalHues = HUE_OFFSETS[config.harmony].map((offset) => normalizeHue(base.h + offset));
+    const hues = config.harmonyTuning && config.harmonyTuning !== "mechanical"
+        ? tuneHarmonyHues({
+            base,
+            harmony: config.harmony,
+            mechanicalHues,
+            purpose: config.harmonyTuning,
+        })
+        : mechanicalHues;
+    const colorChroma = base.c < ACHROMATIC_CHROMA_THRESHOLD
+        ? 0
+        : Math.max(0.08, Math.min(base.c, 0.22));
+    const colors = hues.flatMap((h) => lightness.map((l) => oklchToHex({
+        l,
+        c: colorChroma,
+        h,
+    })));
+    const neutralLightness = interpolate(NEUTRAL_LIGHTNESS_RANGE.max, NEUTRAL_LIGHTNESS_RANGE.min, config.neutralSteps);
+    const neutrals = neutralLightness.map((l) => oklchToHex({
+        l,
+        c: config.neutralMode === "tinted"
+            ? Math.min(TINTED_NEUTRAL_MAX_CHROMA, base.c * TINTED_NEUTRAL_CHROMA_RATIO)
+            : 0,
+        h: base.h,
+    }));
+    return { config, colors, neutrals };
+}
+function interpolate(start, end, count) {
+    if (count === 1)
+        return [start];
+    return Array.from({ length: count }, (_, index) => (start + ((end - start) * index) / (count - 1)));
+}

package/dist/core/perceptual-harmony.js

@@ -0,0 +1,125 @@
+import { PERCEPTUAL_COLLAPSE_DISTANCE, PERCEPTUAL_HUE_SHIFTS, PERCEPTUAL_MIN_DISTANCE, PERCEPTUAL_REPRESENTATIVE_LIGHTNESS, PERCEPTUAL_SCORING_WEIGHTS, } from "./constants.js";
+import { mapToSrgb, normalizeHue } from "./color.js";
+const SCORE_EPSILON = 1e-12;
+const ACHROMATIC_CHROMA_THRESHOLD = 0.001;
+export function tuneHarmonyHues(input) {
+    const mechanicalHues = input.mechanicalHues.map(normalizeHue);
+    if (input.harmony === "monochrome" || mechanicalHues.length < 2)
+        return mechanicalHues;
+    const baseIndex = findBaseIndex(mechanicalHues, input.base.h);
+    const adjustableIndexes = mechanicalHues
+        .map((_, index) => index)
+        .filter((index) => index !== baseIndex);
+    const chroma = input.base.c < ACHROMATIC_CHROMA_THRESHOLD
+        ? 0
+        : Math.max(0.08, Math.min(input.base.c, 0.22));
+    let best = mechanicalHues;
+    let bestScore = Number.NEGATIVE_INFINITY;
+    let bestDeviation = Number.POSITIVE_INFINITY;
+    let bestMetrics;
+    for (const shifts of generateShiftSets(adjustableIndexes.length)) {
+        const hues = [...mechanicalHues];
+        adjustableIndexes.forEach((index, shiftIndex) => {
+            hues[index] = normalizeHue(mechanicalHues[index] + shifts[shiftIndex]);
+        });
+        const metrics = measureCandidate(hues, mechanicalHues, baseIndex, chroma);
+        if (input.purpose === "data-visualization") {
+            if (!bestMetrics || isBetterDataVisualizationCandidate(metrics, bestMetrics)) {
+                best = hues;
+                bestMetrics = metrics;
+            }
+            continue;
+        }
+        const score = scoreCandidate(input.purpose, metrics);
+        if (score > bestScore + SCORE_EPSILON
+            || (Math.abs(score - bestScore) <= SCORE_EPSILON && metrics.targetDeviation < bestDeviation)) {
+            best = hues;
+            bestScore = score;
+            bestDeviation = metrics.targetDeviation;
+        }
+    }
+    return best;
+}
+function generateShiftSets(count) {
+    let sets = [[]];
+    for (let index = 0; index < count; index += 1) {
+        sets = sets.flatMap((set) => PERCEPTUAL_HUE_SHIFTS.map((shift) => [...set, shift]));
+    }
+    return sets;
+}
+function measureCandidate(hues, mechanicalHues, baseIndex, chroma) {
+    const mapped = hues.map((h) => mapForScoring({
+        l: PERCEPTUAL_REPRESENTATIVE_LIGHTNESS,
+        c: chroma,
+        h,
+    }));
+    const distances = [];
+    let baseSeparation = 0;
+    for (let left = 0; left < mapped.length; left += 1) {
+        for (let right = left + 1; right < mapped.length; right += 1) {
+            const distance = oklchDistance(mapped[left], mapped[right]);
+            distances.push(distance);
+            if (left === baseIndex || right === baseIndex)
+                baseSeparation += distance;
+        }
+    }
+    const minimumDistance = Math.min(...distances);
+    return {
+        retainedChroma: mapped.reduce((sum, color) => sum + color.c, 0),
+        minimumDistance,
+        baseSeparation,
+        distanceShortfall: Math.max(0, PERCEPTUAL_MIN_DISTANCE - minimumDistance),
+        collapsedPairs: distances.filter((distance) => distance < PERCEPTUAL_COLLAPSE_DISTANCE).length,
+        targetDeviation: hues.reduce((sum, hue, index) => (sum + circularHueDistance(hue, mechanicalHues[index])), 0),
+    };
+}
+function scoreCandidate(purpose, metrics) {
+    if (purpose === "ui") {
+        const weights = PERCEPTUAL_SCORING_WEIGHTS.ui;
+        return (metrics.retainedChroma * weights.chromaRetention)
+            + (metrics.minimumDistance * weights.minimumDistance)
+            - (metrics.targetDeviation * weights.targetDeviation)
+            - (metrics.collapsedPairs * weights.collapse);
+    }
+    const weights = PERCEPTUAL_SCORING_WEIGHTS.branding;
+    return (metrics.retainedChroma * weights.chromaRetention)
+        + (metrics.minimumDistance * weights.minimumDistance)
+        + (metrics.baseSeparation * weights.baseSeparation)
+        - (metrics.targetDeviation * weights.targetDeviation)
+        - (metrics.collapsedPairs * weights.collapse);
+}
+function isBetterDataVisualizationCandidate(candidate, current) {
+    const comparisons = [
+        candidate.minimumDistance - current.minimumDistance,
+        current.distanceShortfall - candidate.distanceShortfall,
+        candidate.retainedChroma - current.retainedChroma,
+        current.targetDeviation - candidate.targetDeviation,
+    ];
+    const decisiveDifference = comparisons.find((difference) => Math.abs(difference) > SCORE_EPSILON);
+    return decisiveDifference !== undefined && decisiveDifference > 0;
+}
+function mapForScoring(color) {
+    const [l, c, hue] = mapToSrgb(color).to("srgb").to("oklch").coords;
+    return {
+        l: l ?? 0,
+        c: c ?? 0,
+        h: Number.isFinite(hue) ? normalizeHue(hue) : 0,
+    };
+}
+function oklchDistance(left, right) {
+    const leftRadians = (left.h * Math.PI) / 180;
+    const rightRadians = (right.h * Math.PI) / 180;
+    const deltaL = left.l - right.l;
+    const deltaA = (left.c * Math.cos(leftRadians)) - (right.c * Math.cos(rightRadians));
+    const deltaB = (left.c * Math.sin(leftRadians)) - (right.c * Math.sin(rightRadians));
+    return Math.sqrt((deltaL ** 2) + (deltaA ** 2) + (deltaB ** 2));
+}
+function findBaseIndex(hues, baseHue) {
+    return hues.reduce((bestIndex, hue, index) => (circularHueDistance(hue, baseHue) < circularHueDistance(hues[bestIndex], baseHue)
+        ? index
+        : bestIndex), 0);
+}
+function circularHueDistance(left, right) {
+    const difference = Math.abs(normalizeHue(left) - normalizeHue(right));
+    return Math.min(difference, 360 - difference);
+}

package/dist/core/random.js

@@ -0,0 +1,73 @@
+import { DEFAULT_COLOR_STEPS, DEFAULT_NEUTRAL_STEPS, RANDOM_BASE_COLORS, RANDOM_HARMONIES, RANDOM_HARMONY_TUNINGS, RANDOM_NEUTRAL_MODES, } from "./constants.js";
+import { normalizeHex } from "./color.js";
+const UINT32_SIZE = 0x1_0000_0000;
+const UINT32_MAX = UINT32_SIZE - 1;
+const HEX_SEED_PATTERN = /^[0-9a-f]{1,8}$/i;
+export class InvalidRandomSeedError extends Error {
+    constructor(seed) {
+        super(`Invalid random seed: ${String(seed)}`);
+        this.name = "InvalidRandomSeedError";
+    }
+}
+export function generateRandomPaletteConfig(options = {}) {
+    const seedValue = options.seed ?? Math.floor(Math.random() * UINT32_SIZE);
+    const numericSeed = seedToUint32(seedValue);
+    const random = createPrng(numericSeed);
+    const constraints = options.constraints ?? {};
+    const randomized = {
+        baseColor: pick(RANDOM_BASE_COLORS, random),
+        harmony: pick(RANDOM_HARMONIES, random),
+        harmonyTuning: pick(RANDOM_HARMONY_TUNINGS, random),
+        neutralMode: pick(RANDOM_NEUTRAL_MODES, random),
+    };
+    const config = {
+        baseColor: constraints.baseColor === undefined
+            ? randomized.baseColor
+            : normalizeHex(constraints.baseColor),
+        harmony: constraints.harmony ?? randomized.harmony,
+        harmonyTuning: constraints.harmonyTuning ?? randomized.harmonyTuning,
+        neutralMode: constraints.neutralMode ?? randomized.neutralMode,
+        colorSteps: constraints.colorSteps ?? DEFAULT_COLOR_STEPS,
+        neutralSteps: constraints.neutralSteps ?? DEFAULT_NEUTRAL_STEPS,
+    };
+    return { seed: formatSeed(numericSeed), config };
+}
+function seedToUint32(seed) {
+    if (typeof seed === "number") {
+        if (!Number.isSafeInteger(seed) || seed < 0 || seed > UINT32_MAX) {
+            throw new InvalidRandomSeedError(seed);
+        }
+        return seed;
+    }
+    const normalized = seed.trim();
+    if (normalized.length === 0)
+        throw new InvalidRandomSeedError(seed);
+    if (HEX_SEED_PATTERN.test(normalized))
+        return Number.parseInt(normalized, 16);
+    // FNV-1a maps memorable, arbitrary seed strings to the displayed uint32 seed.
+    let hash = 0x811c9dc5;
+    for (const character of normalized) {
+        hash ^= character.codePointAt(0);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+function formatSeed(seed) {
+    return seed.toString(16).padStart(8, "0");
+}
+function createPrng(seed) {
+    let state = seed;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let value = state;
+        value = Math.imul(value ^ (value >>> 15), value | 1);
+        value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+        return ((value ^ (value >>> 14)) >>> 0) / UINT32_SIZE;
+    };
+}
+function pick(values, random) {
+    const value = values[Math.floor(random() * values.length)];
+    if (value === undefined)
+        throw new Error("Cannot select from an empty random candidate list");
+    return value;
+}

package/dist/core/types.js

@@ -0,0 +1,14 @@
+export const HARMONY_MODES = [
+    "monochrome",
+    "analogous",
+    "complementary",
+    "triadic",
+];
+export const NEUTRAL_MODES = ["neutral", "tinted"];
+export const STEP_COUNTS = [3, 5, 7, 9];
+export const HARMONY_TUNINGS = [
+    "mechanical",
+    "ui",
+    "branding",
+    "data-visualization",
+];