ColorLerp.test.js

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { bakeGradientLUT, bakeGradientLUTRGBA, sampleColorLUT } from './ColorLerp.js';
import { multiStopGradientTo } from '@zakkster/lite-color';

// ---------------------------------------------------------------------------
// We isolate the bridge from `@zakkster/lite-color`. Each test that cares about
// specific OKLCH inputs configures the mock per-test via mockImplementation.
// The default impl below is set in beforeEach so accidental leakage between
// tests is impossible.
// ---------------------------------------------------------------------------
vi.mock('@zakkster/lite-color', () => ({
    multiStopGradientTo: vi.fn(),
}));

const dummyColors = [{ l: 0, c: 0, h: 0 }, { l: 1, c: 0, h: 0 }];

beforeEach(() => {
    multiStopGradientTo.mockReset();
    // Default: write a mid-grey so tests that don't care still get a sane value.
    multiStopGradientTo.mockImplementation((colors, t, out) => {
        out.l = 0.5; out.c = 0; out.h = 0; out.a = 1.0;
    });
});

// ---------------------------------------------------------------------------
// Helpers — extract channels from a packed uint32 in either byte order
// ---------------------------------------------------------------------------
const argb = (v) => ({
    a: (v >>> 24) & 0xFF,
    r: (v >>> 16) & 0xFF,
    g: (v >>> 8)  & 0xFF,
    b:  v         & 0xFF,
});

const rgbaLE = (v) => ({
    a: (v >>> 24) & 0xFF,
    b: (v >>> 16) & 0xFF,
    g: (v >>> 8)  & 0xFF,
    r:  v         & 0xFF,
});

describe('lite-color-lerp', () => {

    describe('Validation', () => {
        it('throws when oklchColors is undefined', () => {
            expect(() => bakeGradientLUT()).toThrow(/non-empty/);
        });

        it('throws when oklchColors is empty', () => {
            expect(() => bakeGradientLUT([])).toThrow(/non-empty/);
            expect(() => bakeGradientLUTRGBA([])).toThrow(/non-empty/);
        });

        it('throws when resolution < 2', () => {
            expect(() => bakeGradientLUT(dummyColors, 1)).toThrow(/resolution/);
            expect(() => bakeGradientLUT(dummyColors, 0)).toThrow(/resolution/);
            expect(() => bakeGradientLUTRGBA(dummyColors, 1)).toThrow(/resolution/);
        });

        it('accepts the minimum resolution of 2', () => {
            const lut = bakeGradientLUT(dummyColors, 2);
            expect(lut.length).toBe(2);
        });
    });

    describe('Output shape & zero-GC contract', () => {
        it('returns a Uint32Array of the requested length', () => {
            const lut = bakeGradientLUT(dummyColors, 256);
            expect(lut).toBeInstanceOf(Uint32Array);
            expect(lut.length).toBe(256);
            expect(lut.BYTES_PER_ELEMENT).toBe(4);
            expect(lut.byteLength).toBe(1024);
        });

        it('handles large resolutions', () => {
            const lut = bakeGradientLUT(dummyColors, 1024);
            expect(lut.length).toBe(1024);
        });

        it('calls multiStopGradientTo exactly `resolution` times', () => {
            bakeGradientLUT(dummyColors, 128);
            expect(multiStopGradientTo).toHaveBeenCalledTimes(128);
        });

        it('passes t in [0, 1] across the full range', () => {
            const tValues = [];
            multiStopGradientTo.mockImplementation((colors, t, out) => {
                tValues.push(t);
                out.l = 0.5; out.c = 0; out.h = 0; out.a = 1.0;
            });
            bakeGradientLUT(dummyColors, 5);
            expect(tValues).toEqual([0, 0.25, 0.5, 0.75, 1.0]);
        });
    });

    describe('OKLCH → sRGB conversion correctness', () => {
        it('OKLCH(1, 0, 0) bakes to white', () => {
            multiStopGradientTo.mockImplementation((c, t, out) => {
                out.l = 1.0; out.c = 0; out.h = 0; out.a = 1.0;
            });
            const lut = bakeGradientLUT(dummyColors, 2);
            const px = argb(lut[0]);
            // Allow ±1 for rounding at the gamut boundary.
            expect(px.a).toBe(255);
            expect(px.r).toBeGreaterThanOrEqual(254);
            expect(px.g).toBeGreaterThanOrEqual(254);
            expect(px.b).toBeGreaterThanOrEqual(254);
        });

        it('OKLCH(0, 0, 0) bakes to opaque black', () => {
            multiStopGradientTo.mockImplementation((c, t, out) => {
                out.l = 0.0; out.c = 0; out.h = 0; out.a = 1.0;
            });
            const lut = bakeGradientLUT(dummyColors, 2);
            expect(argb(lut[0])).toEqual({ a: 255, r: 0, g: 0, b: 0 });
        });

        it('mid-grey OKLCH(0.5, 0, 0) bakes to a non-zero, non-white grey', () => {
            multiStopGradientTo.mockImplementation((c, t, out) => {
                out.l = 0.5; out.c = 0; out.h = 0; out.a = 1.0;
            });
            const lut = bakeGradientLUT(dummyColors, 2);
            const px = argb(lut[0]);
            // Equal channels (achromatic), and within the inner sRGB range.
            expect(px.r).toBe(px.g);
            expect(px.g).toBe(px.b);
            expect(px.r).toBeGreaterThan(20);
            expect(px.r).toBeLessThan(200);
        });
    });

    describe('Alpha handling', () => {
        it('alpha = 1 packs as 255', () => {
            multiStopGradientTo.mockImplementation((c, t, out) => {
                out.l = 0.5; out.c = 0; out.h = 0; out.a = 1.0;
            });
            const lut = bakeGradientLUT(dummyColors, 2);
            expect(argb(lut[0]).a).toBe(255);
        });

        it('alpha = 0 packs as 0', () => {
            multiStopGradientTo.mockImplementation((c, t, out) => {
                out.l = 0.5; out.c = 0; out.h = 0; out.a = 0.0;
            });
            const lut = bakeGradientLUT(dummyColors, 2);
            expect(argb(lut[0]).a).toBe(0);
        });

        it('alpha = 0.5 quantizes to 128 (rounding mid-band)', () => {
            multiStopGradientTo.mockImplementation((c, t, out) => {
                out.l = 0.5; out.c = 0; out.h = 0; out.a = 0.5;
            });
            const lut = bakeGradientLUT(dummyColors, 2);
            // (0.5 * 255 + 0.5) | 0 === 128
            expect(argb(lut[0]).a).toBe(128);
        });

        it('defaults alpha to 1.0 when the gradient does not write it', () => {
            // Mock simulates a gradient sampler that omits `a`.
            multiStopGradientTo.mockImplementation((c, t, out) => {
                out.l = 0.5; out.c = 0; out.h = 0;
                // intentionally do not touch out.a
            });
            const lut = bakeGradientLUT(dummyColors, 2);
            expect(argb(lut[0]).a).toBe(255);
        });

        it('resets alpha between samples (no leakage from previous iteration)', () => {
            // First call sets a=0.2, second call leaves a unwritten.
            // The bake's `_tempOklch.a = 1.0` reset must prevent leakage.
            let call = 0;
            multiStopGradientTo.mockImplementation((c, t, out) => {
                out.l = 0.5; out.c = 0; out.h = 0;
                if (call++ === 0) out.a = 0.2;
                // second call: do not write a; expect default 1.0
            });
            const lut = bakeGradientLUT(dummyColors, 2);
            expect(argb(lut[0]).a).toBe(51);   // 0.2 * 255 + 0.5 | 0
            expect(argb(lut[1]).a).toBe(255);  // reset honored
        });
    });

    describe('Byte order — ARGB vs RGBA-LE', () => {
        // Use a vivid red OKLCH so R clearly dominates, making channel
        // positions trivially identifiable in either packing.
        const redImpl = (c, t, out) => {
            out.l = 0.628; out.c = 0.258; out.h = 29.0; out.a = 1.0;
        };

        it('ARGB places A in the highest byte and B in the lowest', () => {
            multiStopGradientTo.mockImplementation(redImpl);
            const lut = bakeGradientLUT(dummyColors, 2);
            const px = argb(lut[0]);
            expect(px.a).toBe(255);
            expect(px.r).toBeGreaterThan(px.b);
            expect(px.r).toBeGreaterThan(px.g);
        });

        it('RGBA-LE places A in the highest byte and R in the lowest', () => {
            multiStopGradientTo.mockImplementation(redImpl);
            const lut = bakeGradientLUTRGBA(dummyColors, 2);
            const px = rgbaLE(lut[0]);
            expect(px.a).toBe(255);
            expect(px.r).toBeGreaterThan(px.b);
            expect(px.r).toBeGreaterThan(px.g);
        });

        it('ARGB and RGBA-LE differ for non-grayscale colors', () => {
            multiStopGradientTo.mockImplementation(redImpl);
            const a = bakeGradientLUT(dummyColors, 2)[0];
            const b = bakeGradientLUTRGBA(dummyColors, 2)[0];
            expect(a).not.toBe(b);
        });

        it('ARGB and RGBA-LE produce equal values for achromatic colors (R=G=B)', () => {
            // Mid-grey: R=G=B, so swapping R and B is a no-op.
            multiStopGradientTo.mockImplementation((c, t, out) => {
                out.l = 0.5; out.c = 0; out.h = 0; out.a = 1.0;
            });
            const a = bakeGradientLUT(dummyColors, 2)[0];
            const b = bakeGradientLUTRGBA(dummyColors, 2)[0];
            expect(a).toBe(b);
        });

        it('RGBA-LE output writes correctly into Canvas-shaped memory', () => {
            // Simulate Canvas2D ImageData: a Uint8ClampedArray viewed as Uint32.
            multiStopGradientTo.mockImplementation(redImpl);
            const lut = bakeGradientLUTRGBA(dummyColors, 2);

            const buf = new ArrayBuffer(4);
            const u32 = new Uint32Array(buf);
            const u8  = new Uint8ClampedArray(buf);
            u32[0] = lut[0];

            // After write, byte 0 must be R (highest channel for our red input).
            expect(u8[0]).toBeGreaterThan(u8[2]); // R > B
            expect(u8[3]).toBe(255);              // A
        });
    });

    describe('sampleColorLUT — hot path', () => {
        const lut = new Uint32Array([1000, 2000, 3000, 4000, 5000]);

        it('returns lut[0] at t=0', () => {
            expect(sampleColorLUT(lut, 0)).toBe(1000);
        });

        it('returns lut[max] at t=1', () => {
            expect(sampleColorLUT(lut, 1)).toBe(5000);
        });

        it('returns the middle index at t=0.5 with maxIdx=4', () => {
            // 0.5 * 4 = 2.0 → index 2
            expect(sampleColorLUT(lut, 0.5)).toBe(3000);
        });

        it('clamps t < 0 to lut[0]', () => {
            expect(sampleColorLUT(lut, -5.5)).toBe(1000);
            expect(sampleColorLUT(lut, -Infinity)).toBe(1000);
        });

        it('clamps t > 1 to lut[max]', () => {
            expect(sampleColorLUT(lut, 42.0)).toBe(5000);
            expect(sampleColorLUT(lut, Infinity)).toBe(5000);
        });

        it('fast-floors fractional indices', () => {
            // maxIdx = 4
            expect(sampleColorLUT(lut, 0.24)).toBe(1000); // 0.96 → 0
            expect(sampleColorLUT(lut, 0.26)).toBe(2000); // 1.04 → 1
            expect(sampleColorLUT(lut, 0.74)).toBe(3000); // 2.96 → 2
            expect(sampleColorLUT(lut, 0.76)).toBe(4000); // 3.04 → 3
        });

        it('handles a 2-entry LUT (minimum size)', () => {
            // With maxIdx=1, ANY t in [0, 1) hits index 0; only t≥1 hits index 1.
            // This is documented behavior of nearest-neighbor sampling.
            const tiny = new Uint32Array([111, 222]);
            expect(sampleColorLUT(tiny, 0)).toBe(111);
            expect(sampleColorLUT(tiny, 0.4)).toBe(111); // 0.4 * 1 = 0.4 → 0
            expect(sampleColorLUT(tiny, 0.99)).toBe(111); // 0.99 * 1 = 0.99 → 0
            expect(sampleColorLUT(tiny, 1)).toBe(222);
        });

        it('NaN input falls through to lut[0] (NaN comparisons are false)', () => {
            // tc = NaN, NaN * anything = NaN, NaN | 0 === 0
            expect(sampleColorLUT(lut, NaN)).toBe(1000);
        });
    });
});