@dilemmagx/palette 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,7 @@
 # @dilemmagx/palette
 
 Palette is a CLI + TypeScript toolkit that reads a single input (HEX, data URI, URL, or local path), detects its type automatically, and generates palettes.
+It supports both built-in and custom algorithms.
 
 ## Install
 
@@ -42,7 +43,7 @@ Output:
 - URL: `http://` or `https://`
 - Path: local image path (default fallback)
 
-## Algorithms
+## Built-in Algorithms
 
 - analogous
 - complementary
@@ -54,6 +55,20 @@ Output:
 
 Monet uses image quantization and color scoring inspired by Material Color Utilities.
 
+## Custom Algorithms
+
+```ts
+import { registerAlgorithm, generatePaletteFromHex } from '@dilemmagx/palette';
+
+registerAlgorithm('duotone', (input) => {
+  const base = input.baseColor;
+  return [base, '#000000'];
+});
+
+const result = await generatePaletteFromHex('#ff7a18', { algorithm: 'duotone' });
+console.log(result.colors);
+```
+
 ## Presets
 
 - `getGameBoyPalette()`: Returns the classic Game Boy colors (#9bbc0f, #8bac0f, #306230, #0f380f)

package/dist/cli.js

@@ -9933,18 +9933,20 @@ function hexFromArgb(argb) {
 }
 
 // src/core.ts
-var ALGORITHMS = [
-  "analogous",
-  "complementary",
-  "triadic",
-  "tetradic",
-  "split-complementary",
-  "monochrome",
-  "monet"
-];
 var DEFAULT_ALGORITHM = "analogous";
+var algorithmRegistry = /* @__PURE__ */ new Map();
+var builtInsRegistered = false;
+function registerAlgorithm(name, generator) {
+  if (!name.trim()) {
+    throw new Error("Algorithm name is required");
+  }
+  algorithmRegistry.set(name, generator);
+}
+function getAlgorithm(name) {
+  return algorithmRegistry.get(name);
+}
 function listAlgorithms() {
-  return [...ALGORITHMS];
+  return Array.from(algorithmRegistry.keys()).sort();
 }
 function detectInputType(input) {
   const trimmed = input.trim();
@@ -9981,47 +9983,39 @@ async function generatePaletteFromPath(filePath, options = {}) {
 async function buildPaletteResultFromBuffer(buffer, inputType, algorithm, count) {
   const resolvedAlgorithm = resolveAlgorithm(algorithm);
   const baseRgb = await getAverageColor(buffer);
-  if (resolvedAlgorithm === "monet") {
-    const colors = await extractMonetPalette(buffer, resolveMonetCount(count, 6));
-    if (colors.length > 0) {
-      return {
-        inputType,
-        algorithm: resolvedAlgorithm,
-        baseColor: rgbToHex(baseRgb),
-        colors
-      };
-    }
-  }
-  return buildPaletteResultFromBase(baseRgb, inputType, resolvedAlgorithm, count);
+  const baseHex = rgbToHex(baseRgb);
+  return buildPaletteResult(
+    {
+      inputType,
+      baseColor: baseHex,
+      baseRgb,
+      baseHsl: rgbToHsl(baseRgb),
+      count,
+      buffer
+    },
+    resolvedAlgorithm
+  );
 }
-function buildPaletteResultFromBase(baseRgb, inputType, algorithm, count) {
+async function buildPaletteResultFromBase(baseRgb, inputType, algorithm, count) {
   const resolvedAlgorithm = resolveAlgorithm(algorithm);
   const baseHex = rgbToHex(baseRgb);
-  if (resolvedAlgorithm === "monet") {
-    const sourceArgb = argbFromHex(baseHex);
-    return {
+  return buildPaletteResult(
+    {
       inputType,
-      algorithm: resolvedAlgorithm,
       baseColor: baseHex,
-      colors: buildMonetPaletteFromSourceArgb(sourceArgb, resolveMonetCount(count, 6))
-    };
-  }
-  const baseHsl = rgbToHsl(baseRgb);
-  const paletteHsl = buildPaletteHsl(baseHsl, resolvedAlgorithm, count);
-  const colors = paletteHsl.map((color) => rgbToHex(hslToRgb(color)));
-  return {
-    inputType,
-    algorithm: resolvedAlgorithm,
-    baseColor: baseHex,
-    colors
-  };
+      baseRgb,
+      baseHsl: rgbToHsl(baseRgb),
+      count
+    },
+    resolvedAlgorithm
+  );
 }
 function resolveAlgorithm(algorithm) {
-  if (!algorithm) return DEFAULT_ALGORITHM;
-  if (!ALGORITHMS.includes(algorithm)) {
-    throw new Error(`Unknown algorithm: ${algorithm}`);
+  const resolved = algorithm ?? DEFAULT_ALGORITHM;
+  if (!algorithmRegistry.has(resolved)) {
+    throw new Error(`Unknown algorithm: ${resolved}`);
   }
-  return algorithm;
+  return resolved;
 }
 function buildPaletteHsl(base, algorithm, count) {
   const hue = normalizeHue(base.h);
@@ -10047,6 +10041,56 @@ function buildPaletteHsl(base, algorithm, count) {
   }
   return buildMonochrome(hue, sat, light, resolveCount(count, 6));
 }
+function buildHslPaletteColors(input, algorithm) {
+  const paletteHsl = buildPaletteHsl(input.baseHsl, algorithm, input.count);
+  return paletteHsl.map((color) => rgbToHex(hslToRgb(color)));
+}
+function registerBuiltInAlgorithms() {
+  if (builtInsRegistered) return;
+  builtInsRegistered = true;
+  registerAlgorithm("analogous", (input) => buildHslPaletteColors(input, "analogous"));
+  registerAlgorithm("complementary", (input) => buildHslPaletteColors(input, "complementary"));
+  registerAlgorithm("triadic", (input) => buildHslPaletteColors(input, "triadic"));
+  registerAlgorithm("tetradic", (input) => buildHslPaletteColors(input, "tetradic"));
+  registerAlgorithm(
+    "split-complementary",
+    (input) => buildHslPaletteColors(input, "split-complementary")
+  );
+  registerAlgorithm("monochrome", (input) => buildHslPaletteColors(input, "monochrome"));
+  registerAlgorithm("monet", async (input) => {
+    if (input.buffer) {
+      const colors = await extractMonetPalette(input.buffer, resolveMonetCount(input.count, 6));
+      if (colors.length > 0) {
+        return colors;
+      }
+    }
+    const sourceArgb = argbFromHex(input.baseColor);
+    return buildMonetPaletteFromSourceArgb(sourceArgb, resolveMonetCount(input.count, 6));
+  });
+  registerAlgorithm("dominant", async (input) => {
+    if (input.buffer) {
+      const colors = await extractDominantPalette(input.buffer, resolveCount(input.count, 8));
+      if (colors.length > 0) {
+        return colors;
+      }
+    }
+    return buildHslPaletteColors(input, "monochrome");
+  });
+}
+registerBuiltInAlgorithms();
+async function buildPaletteResult(input, algorithm) {
+  const generator = getAlgorithm(algorithm);
+  if (!generator) {
+    throw new Error(`Unknown algorithm: ${algorithm}`);
+  }
+  const colors = await generator(input);
+  return {
+    inputType: input.inputType,
+    algorithm,
+    baseColor: input.baseColor,
+    colors
+  };
+}
 function isHex(value) {
   return /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(value);
 }
@@ -10164,6 +10208,70 @@ async function extractMonetPalette(buffer, count) {
   const sourceArgb = ranked[0] ?? sampled[0];
   return buildMonetPaletteFromSourceArgb(sourceArgb, count);
 }
+async function extractDominantPalette(buffer, count) {
+  const { data, info } = await (0, import_sharp.default)(buffer).resize({ width: 96, height: 96, fit: "inside" }).removeAlpha().raw().toBuffer({ resolveWithObject: true });
+  const step = info.channels;
+  const pixels = [];
+  for (let i = 0; i < data.length; i += step) {
+    const r = data[i] ?? 0;
+    const g = data[i + 1] ?? 0;
+    const b = data[i + 2] ?? 0;
+    pixels.push(argbFromRgb(r, g, b));
+  }
+  if (pixels.length === 0) return [];
+  const sampled = downsamplePixels(pixels, 2400);
+  const quantized = QuantizerCelebi.quantize(sampled, 128);
+  const entries = Array.from(quantized.entries()).map(([argb, population]) => ({
+    rgb: argbToRgb(argb),
+    count: population
+  }));
+  if (entries.length === 0) return [];
+  entries.sort((a, b) => b.count - a.count);
+  const totalCount = entries.reduce((sum, entry) => sum + entry.count, 0);
+  const coverageTarget = 0.95;
+  const candidateEntries = [];
+  let coverage = 0;
+  for (const entry of entries) {
+    if (candidateEntries.length >= count) {
+      candidateEntries.push(entry);
+      continue;
+    }
+    candidateEntries.push(entry);
+    coverage += entry.count / Math.max(1, totalCount);
+    if (coverage >= coverageTarget) {
+      break;
+    }
+  }
+  if (candidateEntries.length < count) {
+    candidateEntries.splice(0, candidateEntries.length, ...entries);
+  }
+  if (entries.length <= count) {
+    return entries.map((entry) => rgbToHex(entry.rgb));
+  }
+  const maxCount = Math.max(1, entries[0]?.count ?? 1);
+  const seeds = [candidateEntries[0].rgb];
+  while (seeds.length < count) {
+    let best = null;
+    let bestScore = -1;
+    for (const entry of candidateEntries) {
+      if (seeds.some((seed) => rgbDistanceSq(seed, entry.rgb) === 0)) continue;
+      let minDist = Number.POSITIVE_INFINITY;
+      for (const seed of seeds) {
+        minDist = Math.min(minDist, rgbDistanceSq(seed, entry.rgb));
+      }
+      const weight = entry.count / maxCount;
+      const score = minDist * (0.2 + Math.sqrt(weight));
+      if (score > bestScore) {
+        bestScore = score;
+        best = entry;
+      }
+    }
+    if (!best) break;
+    seeds.push(best.rgb);
+  }
+  const refined = refineCentroids(seeds, entries);
+  return refined.slice(0, count).map((color) => rgbToHex(color));
+}
 function resolveCount(count, fallback) {
   if (!count) return fallback;
   return Math.max(2, Math.min(12, Math.floor(count)));
@@ -10264,6 +10372,47 @@ async function fetchBuffer(url) {
 function clamp(value, min, max) {
   return Math.min(max, Math.max(min, value));
 }
+function rgbDistanceSq(a, b) {
+  const dr = a.r - b.r;
+  const dg = a.g - b.g;
+  const db = a.b - b.b;
+  return dr * dr + dg * dg + db * db;
+}
+function argbToRgb(argb) {
+  return {
+    r: argb >>> 16 & 255,
+    g: argb >>> 8 & 255,
+    b: argb & 255
+  };
+}
+function refineCentroids(seeds, entries) {
+  const accum = seeds.map(() => ({ r: 0, g: 0, b: 0, count: 0 }));
+  for (const entry of entries) {
+    let bestIndex = 0;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < seeds.length; i += 1) {
+      const dist = rgbDistanceSq(seeds[i], entry.rgb);
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestIndex = i;
+      }
+    }
+    const target = accum[bestIndex];
+    target.r += entry.rgb.r * entry.count;
+    target.g += entry.rgb.g * entry.count;
+    target.b += entry.rgb.b * entry.count;
+    target.count += entry.count;
+  }
+  return seeds.map((seed, index) => {
+    const bucket = accum[index];
+    if (!bucket || bucket.count === 0) return seed;
+    return {
+      r: clamp(bucket.r / bucket.count, 0, 255),
+      g: clamp(bucket.g / bucket.count, 0, 255),
+      b: clamp(bucket.b / bucket.count, 0, 255)
+    };
+  });
+}
 function normalizeHue(hue) {
   const normalized = hue % 360;
   return normalized < 0 ? normalized + 360 : normalized;

package/dist/core.d.ts

@@ -3,9 +3,30 @@
  */
 export type InputType = 'hex' | 'datauri' | 'url' | 'path';
 /**
- * Supported palette algorithms.
+ * Built-in palette algorithms.
  */
-export type PaletteAlgorithm = 'analogous' | 'complementary' | 'triadic' | 'tetradic' | 'split-complementary' | 'monochrome' | 'monet';
+export type BuiltInPaletteAlgorithm = 'analogous' | 'complementary' | 'triadic' | 'tetradic' | 'split-complementary' | 'monochrome' | 'monet' | 'dominant';
+/**
+ * Palette algorithm name, including custom algorithms.
+ */
+export type PaletteAlgorithm = BuiltInPaletteAlgorithm | (string & {
+    __paletteAlgorithm?: never;
+});
+/**
+ * Input for palette generators.
+ */
+export interface PaletteGeneratorInput {
+    inputType: InputType;
+    baseColor: string;
+    baseRgb: RgbColor;
+    baseHsl: HslColor;
+    count?: number;
+    buffer?: Buffer;
+}
+/**
+ * Palette generator contract.
+ */
+export type PaletteGenerator = (input: PaletteGeneratorInput) => Promise<string[]> | string[];
 /**
  * Options used when generating palettes.
  */
@@ -40,6 +61,28 @@ export interface PaletteResult {
      */
     colors: string[];
 }
+interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+interface HslColor {
+    h: number;
+    s: number;
+    l: number;
+}
+/**
+ * Registers a custom palette algorithm.
+ */
+export declare function registerAlgorithm(name: string, generator: PaletteGenerator): void;
+/**
+ * Unregisters a palette algorithm.
+ */
+export declare function unregisterAlgorithm(name: string): boolean;
+/**
+ * Returns a registered algorithm by name.
+ */
+export declare function getAlgorithm(name: string): PaletteGenerator | undefined;
 /**
  * Returns the list of supported palette algorithms.
  */
@@ -79,3 +122,4 @@ export declare function generatePaletteFromUrl(url: string, options?: PaletteOpt
  * @param options Optional palette options.
  */
 export declare function generatePaletteFromPath(filePath: string, options?: PaletteOptions): Promise<PaletteResult>;
+export {};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { InputType, PaletteAlgorithm, PaletteOptions, PaletteResult } from './core';
-export { detectInputType, generatePalette, generatePaletteFromHex, generatePaletteFromDataUri, generatePaletteFromUrl, generatePaletteFromPath, listAlgorithms, } from './core';
+export type { BuiltInPaletteAlgorithm, InputType, PaletteAlgorithm, PaletteGenerator, PaletteGeneratorInput, PaletteOptions, PaletteResult, } from './core';
+export { detectInputType, generatePalette, generatePaletteFromHex, generatePaletteFromDataUri, generatePaletteFromUrl, generatePaletteFromPath, getAlgorithm, listAlgorithms, registerAlgorithm, unregisterAlgorithm, } from './core';
 export { getGameBoyPalette } from './presets';
 export type { RgbaColor } from './presets';