Palette Gen Developer Reference

tool/palette-gen/package.json defines @auric-artisan/palette-gen, an ESM package that requires Node 20 or newer. The package exposes the root entry and subpath exports for every major subsystem.

Top-level named exports include generatePalette, generateDataset, evaluatePalette, simulateColorBlindness, getAvailableMethods and getSupportedFormats. The package also re-exports subsystem modules for advanced workflows.

The public API lives in src/api/api.js. It wraps lower-level modules and normalizes the output into palette objects with metrics.

const palette = generatePalette({
  method: "deltaE_spaced",
  count: 6,
  seed: 90210
});

const evaluation = evaluatePaletteAPI(palette);
const simulations = simulateColorBlindnessAPI(palette);

src/index.js aliases evaluatePaletteAPI to the public top-level name evaluatePalette, and aliases simulateColorBlindnessAPI to simulateColorBlindness.

createPalette(rgbColors, meta) in src/core/palette.js is the central object factory. It creates a unique palette_id, maps RGB colors to HEX, OKLCH and Lab, and merges method metadata.

{
  palette_id: "pal_lx0a9abc_1",
  colors: [
    {
      hex: "#2f8ed8",
      rgb: [47, 142, 216],
      oklch: [0.61, 0.14, 248.7],
      lab: [56.8, 2.9, -45.2]
    }
  ],
  metadata: {
    method: "triadic",
    color_count: 5,
    timestamp: 1779753600000,
    deltaE_avg: 61.2,
    entropy: 0.8,
    contrast_matrix: [[1, 2.14], [2.14, 1]],
    mood: "balanced"
  }
}

Binary helpers in the same module provide compact RGB transport: createBinaryPalette(), decodeBinaryPalette(), createPaletteBatchBuffer(), writePaletteToBatch() and readPaletteFromBatch(). The single-palette binary shape stores a 4-byte color count followed by 3 RGB bytes per color.

src/core/color-spaces.js is a pure conversion module. It uses D65 white point constants and routes arbitrary conversion requests through RGB when needed.

The key helpers are convert(value, from, to), rgbToAll(r, g, b), rgbToHex(), rgbToLab() and rgbToOklch(). All exported palette colors are derived from this layer, so changes here affect datasets, API responses and the Palette Library.

Algorithm modules return arrays of RGB triplets. The high-level API then normalizes length, creates a palette object and adds metrics.

generatePalette() pads or truncates algorithm output so the returned palette has exactly count colors. That is useful for API stability, but algorithm authors should still return meaningful output lengths to avoid repeated colors.

src/color_science/metrics.js owns the numeric measurements used by generation, evaluation, datasets and the library viewer.

• deltaE76, deltaE94 and deltaE2000 for perceptual difference.
• relativeLuminance, contrastRatio and contrastMatrix for WCAG-style contrast data.
• paletteAvgDeltaE and paletteMinDeltaE for pair-distance summaries.
• paletteEntropy, colorDiversityIndex and perceptualUniformity for palette quality signals.
• chromaStats, luminanceStats and hueDistribution for analysis and filtering.
• evaluatePalette(rgbColors) returns the consolidated metrics object.

Mood classification lives in src/research/research.js. classifyMood() combines warmth, chroma, lightness, entropy and saturation into a primary mood and attribute list. The high-level palette metadata stores classifyMood(rgbColors).primary.

src/accessibility/accessibility.js provides WCAG contrast and CVD helpers. It is used by evaluatePaletteAPI() and can be imported directly for focused reports.

Maintenance note: the current pairwise allPairsPassAA summary uses the AA_large boolean. Keep docs, UI labels and tests clear if that field is renamed or split into normal-text and large-text summaries.

src/dataset_engine/generator.js contains DatasetGenerator, the main streaming dataset factory. Constructor options include colorsPerPalette, useGPU, workerCount, batchSize, includeMetrics and seed.

const generator = new DatasetGenerator({
  colorsPerPalette: 5,
  useGPU: false,
  batchSize: 50000,
  includeMetrics: true,
  seed: 42
});

await generator.init();
const result = await generator.generateDataset({
  paletteCount: 5000000,
  outputPath: "./output",
  format: "ndjson",
  method: "mixed",
  compress: false
});
await generator.destroy();

Current implementation detail: DatasetGenerator.init() can initialize both the GPU pipeline and WorkerPool, but generateDataset() currently uses the CPU byte generator path for batch production. Treat the worker and GPU modules as available lower-level infrastructure unless a future dataset path explicitly routes through them.

src/dataset_engine/streaming.js provides StreamingPaletteWriter, PaletteTransform and ChunkedProcessor. The writer supports JSON, NDJSON, CSV and binary output, plus gzip compression through compress: true.

• JSON output writes an array stream with comma-safe item boundaries.
• NDJSON output writes one palette object per line.
• CSV output writes palette_id, method, color_count, colors_hex, deltaE_avg and entropy.
• Binary output writes a 4-byte color count plus RGB bytes for each palette object.

src/dataset_engine/worker-pool.js exposes a worker-thread pool with generateDistributed() and evaluateDistributed(). The worker supports generation methods named random, harmony and golden. Keep that naming distinct from the high-level public method list.

src/gpu/gpu-pipeline.js provides optional GPU.js acceleration and stable CPU fallback. initGPU() tries gpu.js in GPU mode, then CPU mode, then disables acceleration if the import fails.

Always call destroy() on a GPUPipeline instance or DatasetGenerator after long-running work so GPU.js resources and worker threads do not remain active.

src/export/exporters.js provides file-writing exporters. These are package-level exporters for local Node workflows; the HTTP API uses a separate in-memory mirror in api/lib/exporters/palette.js.

exportDataset(palettes, outputPath, format, options) dispatches to the appropriate exporter and validates the format against json, ndjson, csv, binary, arrow and parquet.

src/visualization/visualization.js provides direct SVG and terminal-oriented views for generated palettes:

• paletteSwatchSVG() creates a labeled horizontal color strip.
• colorWheelSVG() plots palette colors on a hue wheel.
• contrastMatrixSVG() renders WCAG contrast as a heatmap.
• perceptualMapSVG() plots OKLCH lightness and chroma.
• paletteASCII() and contrastMatrixASCII() support terminal examples.

src/research/research.js analyzes palette datasets with distribution summaries, Lab clustering, entropy histograms, mood distribution and fullResearchReport(). Use these helpers for generated data QA before publishing new manifest or library data.

library/palette/index.html is the public UI and library/palette/palette-library.js is the browser runtime. The UI preloads /data/palette-db/palettes.json, uses Auric Artisan cursor, scroll and loader layers, and exposes Library, Inspect, Harmony, Accessibility, Stats, Export and Saved panels.

The data file is intentionally compact:

{
  "schema": "aa.palette-db.compact.v1",
  "format": "deterministic-palette-gen-manifest",
  "source": "@auric-artisan/palette-gen",
  "count": 5000000,
  "colors_per_palette": 5,
  "seed": 42,
  "batch_size": 50000,
  "batch_seed_stride": 2654435761,
  "methods": [
    "complementary",
    "triadic",
    "analogous",
    "tetradic",
    "golden_ratio",
    "random",
    "monochromatic"
  ]
}

The browser derives the palette id as pal_${index.toString(36)}, regenerates RGB values from the same xorshift batch seed, enriches each visible palette with HEX, OKLCH, Lab, Delta E, entropy and contrast, and caches a bounded number of materialized palettes. This keeps the public page fast while representing a 5,000,000-palette corpus.

Server-side handlers import the package directly:

• api/lib/handlers/palette.js imports generatePalette and evaluatePaletteAPI for /v1/palette/generate and /v1/palette/evaluate.
• api/lib/handlers/meta.js imports getAvailableMethods for /v1/methods/palette.
• api/lib/handlers/graphql.js exposes palette generation through GraphQL.
• api/lib/exporters/palette.js mirrors browser-friendly formats for stateless HTTP export.

The HTTP generator validates count (1 through 64), hue, saturation and lightness, then passes the options object to the package API. Keep route docs and request validation synchronized whenever new high-level options are added.

The package declares the following scripts:

cd tool/palette-gen
npm run example:basic
npm run example:gpu
npm run example:large
npm run generate:dataset
npm run benchmark
npm test

examples/basic-generation.js covers public methods, metrics, ASCII visualization, full evaluation and CVD simulation. benchmarks/benchmark.js is for local throughput comparisons after engine changes.

Current maintenance caveat: package.json defines npm test as node --test tests/, but the package does not currently include a tests directory. Until package tests are added, use smoke imports, example runs, root tests, API contract checks and documentation generation as the release gate.

• Update getAvailableMethods() when adding, renaming or removing generation methods.
• Keep user docs, developer docs, API metadata and Palette Library filter labels aligned with method names.
• Add Node tests before changing color-space conversion, Delta E, contrast, entropy or scoring behavior.
• Check deterministic output when changing generatePalettesCPU(), seed stride, batch size or manifest shape.
• Regenerate or migrate data/palette-db/palettes.json when public dataset parameters change.
• Validate optional Arrow and Parquet exporters when dependency versions move.
• Keep the API in-memory exporter synchronized with browser exports and package file exporters where names overlap.
• Destroy dataset, GPU and worker resources after long-running scripts.
• Run root site tests, docs discovery generation, RSS, sitemap, PWA cache and search-index generation before publishing docs.

For workflow-level usage, see the Palette Gen User Guide.