Gradient Gen Developer Reference

tool/gradient-gen/package.json defines an ESM package named @auric-artisan/gradient-gen. It requires Node 20 or newer and exposes both the main package entry and subpath exports.

src/index.js re-exports every module except utils and names the common entry points from src/api/api.js.

generateGradientBatch(), generateGradientRecipe(), generateStopColors() and exportDataset() are also available through the default API object and module re-exports.

src/core/gradient.js is the central model. createGradient() normalizes stops, samples colors and returns a gradient object.

{
  gradient_id: "grad_...",
  name: "Auric Gradient",
  stops: [
    {
      index: 0,
      position: 0,
      label: "stop-1",
      hex: "#0ea5e9",
      rgb: [14, 165, 233],
      hsl: [199.7, 0.83, 0.48],
      lab: [...],
      lch: [...],
      oklab: [...],
      oklch: [...],
      luminance: 0.3204
    }
  ],
  colors: [
    {
      index: 0,
      position: 0,
      travel: 0,
      source_stop: [0, 0],
      hex: "#0ea5e9",
      rgb: [14, 165, 233],
      ...
    }
  ],
  metadata: {
    topology: "linear",
    angle: 90,
    interpolation_space: "oklch-short",
    easing: "linear",
    stop_count: 3,
    sample_count: 128,
    complexity: 0.0932,
    css: "linear-gradient(...)"
  }
}

Stop normalization accepts stops entries with color, hex, position and label, or a simpler colors array. Positions are clamped from 0 to 1, sorted and forced to start at 0 and end at 1.

createBinaryGradient() encodes a compact binary buffer with AAGD magic, version, stop count, sample count, channel count and RGB bytes. decodeBinaryGradient() validates that magic and returns HEX samples.

src/core/color.js is dependency-free and uses D65 assumptions for XYZ and Lab conversions. It includes:

• sRGB transfer functions: srgbToLinear() and linearToSrgb().
• HEX and RGB helpers: rgbToHex(), hexToRgb() and normalizeRgb().
• HSL conversion: rgbToHsl() and hslToRgb().
• XYZ and Lab conversion: rgbToXyz(), xyzToRgb(), rgbToLab(), labToRgb().
• LCH conversion and gamut clipping: rgbToLch(), lchToRgb(), lchToRgbGamut().
• OKLab and OKLCH conversion and gamut clipping: rgbToOklab(), rgbToOklch(), oklchToRgbGamut().
• Hue mixing helpers for short and long hue travel.

colorRecord() is the shared conversion bundle used for both source stops and sampled colors.

src/algorithms/generators.js defines the procedural recipe engine. It exports GRADIENT_METHODS, COMPLEXITY_PROFILES, generateStopColors(), generateGradientRecipe() and generateComplexGradient().

• simple: 2 to 4 stops, 64 recommended steps, low jitter.
• detailed: 5 to 12 stops, 256 recommended steps, moderate jitter.
• extreme: 16 to 64 stops, 1,024 recommended steps, high jitter.

The method functions combine seeded RNG, HSL conversion, OKLCH gamut clipping, sinusoidal hue movement, harmonic hue relationships and weighted method selection. mixed is not a direct method; it resolves through weightedPick() using the method weights.

Recipes return method, complexity, normalized stop objects and recommendedSteps. generateComplexGradient() then calls createGradient() with metadata containing method, profile, seed and generated flag.

src/interpolation/spaces.js exports INTERPOLATION_SPACES and interpolateColor(). Each branch normalizes RGB inputs and mixes in the requested color space.

src/interpolation/easing.js provides linear, polynomial, sine, exponential, smoothstep, smootherstep and stepped easing modes. sampleGradientStops() applies easing to the travel value, finds the active stop segment and stores both original position and eased travel.

src/metrics/metrics.js provides direct metrics and the full evaluateGradient() report.

• deltaE76() and deltaE2000() operate on Lab coordinates.
• deltaERgb() converts RGB to Lab before measuring color difference.
• contrastRatio() computes relative-luminance contrast.
• evaluateGradient() accepts a gradient object or an array of RGB values.

The report computes adjacent Delta E, adjacent contrast, luminance statistics, OKLCH chroma statistics, total hue travel, luminance monotonicity, Delta E uniformity, banding risk, complexity and a weighted score. The score weights uniformity, monotonicity, banding risk and complexity.

classifyBanding() is heuristic: a very low minimum Delta E on a ramp of more than 128 samples can indicate subtle compression, while very high mean Delta E can indicate visible step risk. Treat it as a useful design signal, not a formal visual threshold.

src/dataset_engine/generator.js contains GradientDatasetGenerator. Its constructor stores batchSize, seed, includeMetrics, steps, complexity and total generated count.

generateDataset() creates a StreamingGradientWriter, generates gradients in batches, rotates interpolation spaces and easing methods with weighted picks, and calls the optional progress callback after each batch.

generateRawDataset() writes an AAGR binary header followed by raw RGB rows, one gradient at a time. It uses stream backpressure and reports total bytes, elapsed time and generation rate.

generateGradientBatch(size, options) is the small-batch helper used by examples, benchmarks and tests. It returns an array and should not be used for million-scale output.

There are two export layers. The streaming writer supports long-running dataset jobs. The file exporters write already-materialized arrays.

compactGradient() keeps gradient_id, name, stops, sampled HEX colors and metadata. This is the shape used by JSON, NDJSON and streaming output.

SVG export creates horizontal strips with linearGradient definitions. CSS export creates class rules with a configurable prefix, defaulting to aa-gradient.

src/gpu/gpu-pipeline.js currently provides a CPU fallback and exports WGSL source for browser or WebGPU integration.

• generateGradientSeedsCPU(count, maxStops, seed) returns packed RGB seed bytes.
• GPUPipeline.init() detects navigator.gpu but still uses the CPU generator today.
• GPUPipeline.generateBatched() splits work into batches and invokes an optional batch callback.
• WGSL_GRADIENT_SEED_GENERATOR is a compute shader for future direct GPU generation.

Treat this module as GPU-adjacent infrastructure. The production path is still CPU generation with a dependency-free fallback.

scripts/generate-data.js adapts package gradients into the existing site gradient collection shape. The output directory is data/gradient-gen.

toSiteGradient() maps stops to { pos, hex, oklch }, names gradients by method and index, and stores score, complexity score, Delta E mean, uniformity, banding, CSS preview, source and seed in meta.

Several server-side handlers import the package directly:

• api/lib/handlers/gradient.js imports generateGradient and gradientCSS for /v1/gradient/generate.
• api/lib/handlers/image.js imports generateGradient for gradient PNG rendering.
• api/lib/handlers/graphql.js exposes a gradient resolver.
• api/lib/handlers/meta.js imports getAvailableMethods for /v1/methods/gradient.
• api/lib/exporters/gradient.js imports gradientToCss for API export payloads.

Maintenance note: the direct package option is interpolationSpace. The current /v1/gradient/generate adapter parses a request field named interpolation into opts.interpolation, so update the adapter if that endpoint must expose interpolation-space selection.

tests/gradient.test.js uses Node's built-in node:test. It covers:

• Multi-stop perceptual gradient creation.
• Procedural aurora generation with extreme complexity.
• Metric evaluation on a 32-sample gradient.
• CSS output and binary encoding/decoding.
• Async batch generation.

cd tool/gradient-gen
npm test
npm run benchmark

benchmarks/benchmark.js measures handmade generation, procedural generation, evaluation, CPU seed generation and a 10,000-gradient simple batch. Use benchmark results as relative signals after engine changes, not as absolute product guarantees.

• Keep README examples, user docs and developer docs aligned when public options change.
• Add tests whenever adding an interpolation space, easing mode, export format or metric field.
• Update getAvailableMethods() when methods, complexity profiles, spaces, easing modes or formats change.
• Regenerate data/gradient-gen when site-facing method plans, metadata or data shapes change.
• Keep compactGradient(), CSV headers and API exporters synchronized when metadata changes.
• Validate gzip output when changing StreamingGradientWriter compression behavior.
• Review API adapters after renaming package options such as interpolationSpace.
• Run package tests, root validation and documentation discovery generation before shipping docs or data changes.

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