@zakkster/lite-gradient-studio 1.0.0 → 1.1.0

package/src/palette-extract.js

@@ -11,32 +11,32 @@
  * top buckets from the warm cluster (variants of skin) and the blue
  * either gets dedup'd against the warm picks or ranked below them.
  * Designer's lived expectation: "import this photo of a baby in a blue
- * shirt -> I should see blue in the palette."
+ * shirt → I should see blue in the palette."
  *
- * The fix is to count CHROMA, not pixels -- and to enforce a minimum hue
- * separation between picks. A handful of vivid-blue pixels at C ~= 0.20
- * contribute more weight than a thousand near-grey pixels at C ~= 0.02.
- * A 50 deg hue-separation rule then guarantees the second pick can't be
+ * The fix is to count CHROMA, not pixels — and to enforce a minimum hue
+ * separation between picks. A handful of vivid-blue pixels at C ≈ 0.20
+ * contribute more weight than a thousand near-grey pixels at C ≈ 0.02.
+ * A 50° hue-separation rule then guarantees the second pick can't be
  * another shade of the first pick's hue.
  *
  * Algorithm:
  *   1. Single-pass walk of RGBA pixels. Convert each to OKLCH inline
- *      (no per-pixel function call overhead -- the matrix path is
+ *      (no per-pixel function call overhead — the matrix path is
  *      duplicated from color-convert.js for speed).
- *   2. Skip pixels darker than `darkFloor` (L < 0.10) -- shadows, not
+ *   2. Skip pixels darker than `darkFloor` (L < 0.10) — shadows, not
  *      "colors". Skip fully-transparent pixels.
  *   3. Pixels below `chromaticThreshold` (C < 0.02) feed a NEUTRAL
- *      pool -- accumulated L average becomes the single representative
+ *      pool — accumulated L average becomes the single representative
  *      neutral output, slotted at the desired position.
- *   4. Chromatic pixels are binned into 24 hue buckets (15 deg each).
+ *   4. Chromatic pixels are binned into 24 hue buckets (15° each).
  *      Per bucket we track: total chroma weight, count, and the
  *      MOST VIVID pixel's L/C/H (this becomes the bucket's
- *      representative -- picking the most-vivid avoids muddy
+ *      representative — picking the most-vivid avoids muddy
  *      "average" colors that real-photo k-means produces).
  *   5. Sort buckets by total chroma weight. Greedy pick top buckets,
  *      enforcing `minHueSeparation` between picks. If we can't fill
- *      enough slots at 50 deg, progressively relax to 30 / 15 / 0.
- *   6. Sort the final picks by L for natural dark->light gradient order.
+ *      enough slots at 50°, progressively relax to 30° / 15° / 0°.
+ *   6. Sort the final picks by L for natural dark→light gradient order.
  *
  * Behavior preserved from v1:
  *   - Returns Array<{l, c, h}> sorted by lightness ascending.
@@ -51,38 +51,18 @@
  *     1D callers still get the same neutral via the standard pick path
  *     when they request enough slots.
  *
- * Performance: a 240x180 sample = 43 200 pixels iterates in ~5 ms on
- * a typical laptop. Zero per-pixel allocation, zero per-call allocation
- * once the module is loaded: the 24-entry bucket state is module-scoped
- * and reset (not re-allocated) on each call.
+ * Performance: a 240×180 sample = 43 200 pixels iterates in ~5 ms on
+ * a typical laptop. Single Map allocation (none — pre-allocated
+ * buckets array). Zero per-pixel allocations in the inner loop.
  */
 
-const HUE_BUCKETS         = 24;     // 15 deg per bucket
+const HUE_BUCKETS         = 24;     // 15° per bucket
 const DEFAULT_MIN_HUE_SEP = 50;     // initial hue separation requirement
-const RELAXATION_LADDER   = [30, 15, 0];  // tried in order if 50 deg underfills
-const CHROMATIC_THRESHOLD = 0.02;   // C below this -> neutral pool
-const DARK_FLOOR          = 0.10;   // L below this -> skip (shadow)
+const RELAXATION_LADDER   = [30, 15, 0];  // tried in order if 50° underfills
+const CHROMATIC_THRESHOLD = 0.02;   // C below this → neutral pool
+const DARK_FLOOR          = 0.10;   // L below this → skip (shadow)
 const NEUTRAL_CHROMA      = 0.005;  // tiny tint for the neutral slot
 
-/* Module-level bucket state. One allocation at module load; reset per
- * call. Single-threaded JS: safe to share across calls because each
- * `extractPalette` runs synchronously to completion. */
-const _buckets = new Array(HUE_BUCKETS);
-for (let i = 0; i < HUE_BUCKETS; i++) {
-    _buckets[i] = { weight: 0, count: 0, maxC: 0, mcL: 0, mcH: 0 };
-}
-
-/* Reusable scratch for the "filtered + sorted buckets" view. Sized to
- * fit all chromatic buckets; trim length per call. */
-const _sortedBuckets = new Array(HUE_BUCKETS);
-
-function resetBuckets() {
-    for (let i = 0; i < HUE_BUCKETS; i++) {
-        const b = _buckets[i];
-        b.weight = 0; b.count = 0; b.maxC = 0; b.mcL = 0; b.mcH = 0;
-    }
-}
-
 /**
  * @param {Uint8ClampedArray} pixels   RGBA, length must be multiple of 4.
  * @param {number}            [count]  Target palette size (default 5).
@@ -92,25 +72,27 @@ function resetBuckets() {
 export function extractPalette(pixels, count = 5) {
     if (count < 1) return [];
 
-    // Reset module-scope state. Doing this once per call beats allocating
-    // 24 fresh objects every call.
-    resetBuckets();
+    // Pre-allocated bucket state — written in place, never reallocated.
+    const buckets = new Array(HUE_BUCKETS);
+    for (let i = 0; i < HUE_BUCKETS; i++) {
+        buckets[i] = { weight: 0, count: 0, maxC: 0, mcL: 0, mcH: 0 };
+    }
     let neutralLsum = 0;
     let neutralCount = 0;
 
-    // Single pass. Convert each pixel sRGB byte -> OKLCH inline to keep
+    // Single pass. Convert each pixel sRGB byte → OKLCH inline to keep
     // the hot path allocation-free. The matrix coefficients are the
-    // canonical OKLab transform (Bjorn Ottosson, 2020).
+    // canonical OKLab transform (Björn Ottosson, 2020).
     for (let i = 0; i < pixels.length; i += 4) {
         if (pixels[i + 3] < 128) continue;   // skip transparent
 
         const r8 = pixels[i], g8 = pixels[i + 1], b8 = pixels[i + 2];
         const rN = r8 / 255, gN = g8 / 255, bN = b8 / 255;
-        // sRGB inverse gamma -> linear sRGB.
+        // sRGB inverse gamma → linear sRGB.
         const rL = rN <= 0.04045 ? rN / 12.92 : Math.pow((rN + 0.055) / 1.055, 2.4);
         const gL = gN <= 0.04045 ? gN / 12.92 : Math.pow((gN + 0.055) / 1.055, 2.4);
         const bL = bN <= 0.04045 ? bN / 12.92 : Math.pow((bN + 0.055) / 1.055, 2.4);
-        // Linear sRGB -> LMS' (cube-rooted) -> OKLab.
+        // Linear sRGB → LMS' (cube-rooted) → OKLab.
         const lp = Math.cbrt(0.4122214708 * rL + 0.5363325363 * gL + 0.0514459929 * bL);
         const mp = Math.cbrt(0.2119034982 * rL + 0.6806995451 * gL + 0.1073969566 * bL);
         const sp = Math.cbrt(0.0883024619 * rL + 0.2817188376 * gL + 0.6299787005 * bL);
@@ -121,18 +103,18 @@ export function extractPalette(pixels, count = 5) {
 
         if (L < DARK_FLOOR) continue;        // shadows are not colors
 
-        if (C < CHROMATIC_THRESHOLD) {       // near-grey -> neutral pool
+        if (C < CHROMATIC_THRESHOLD) {       // near-grey → neutral pool
             neutralLsum += L;
             neutralCount++;
             continue;
         }
 
-        // Hue in [0, 360). atan2 returns [-pi, pi].
+        // Hue in [0, 360). atan2 returns [-π, π].
         let H = Math.atan2(B, A) * 180 / Math.PI;
         if (H < 0) H += 360;
 
         const bucketIdx = (H * HUE_BUCKETS / 360) | 0;
-        const bkt = _buckets[bucketIdx];
+        const bkt = buckets[bucketIdx];
         bkt.weight += C;       // chroma-weighted, NOT pixel-count weighted
         bkt.count++;
         if (C > bkt.maxC) {    // track the most-vivid pixel as the rep
@@ -142,25 +124,18 @@ export function extractPalette(pixels, count = 5) {
         }
     }
 
-    // Filter occupied buckets into the sorted view. In-place sort by
-    // total chroma weight, descending.
-    let sortedLen = 0;
-    for (let i = 0; i < HUE_BUCKETS; i++) {
-        if (_buckets[i].count > 0) _sortedBuckets[sortedLen++] = _buckets[i];
-    }
-    // Truncate-length sort via a small bubble-like pass would dominate
-    // for sortedLen <= 24; Array.prototype.sort on the sliced view is
-    // O(n log n) and the allocation is one tiny temporary. We sort the
-    // module-scope view itself in-place over its first sortedLen entries.
-    sortInPlaceByWeightDesc(_sortedBuckets, sortedLen);
+    // Sort buckets by total chroma weight, descending. Only consider
+    // buckets that actually received pixels.
+    const sortedBuckets = buckets
+        .filter((b) => b.count > 0)
+        .sort((a, b) => b.weight - a.weight);
 
     // Greedy pick respecting min hue separation. The separation rule is
     // what surfaces cool subject colors from a warm-dominated photo.
     const pickWithSeparation = (separation) => {
         const picks = [];
-        for (let i = 0; i < sortedLen; i++) {
+        for (const b of sortedBuckets) {
             if (picks.length >= count) break;
-            const b = _sortedBuckets[i];
             let tooClose = false;
             for (const p of picks) {
                 const d = Math.abs(b.mcH - p.h) % 360;
@@ -171,7 +146,7 @@ export function extractPalette(pixels, count = 5) {
         return picks;
     };
 
-    // Try the canonical 50 deg separation. If the image is genuinely low-
+    // Try the canonical 50° separation. If the image is genuinely low-
     // diversity (monochrome, hue-collapsed), relax progressively.
     let picks = pickWithSeparation(DEFAULT_MIN_HUE_SEP);
     if (picks.length < count) {
@@ -193,24 +168,7 @@ export function extractPalette(pixels, count = 5) {
         });
     }
 
-    // Lightness-ascending output -- natural dark->light gradient order.
+    // Lightness-ascending output — natural dark→light gradient order.
     picks.sort((a, b) => a.l - b.l);
     return picks;
 }
-
-/* In-place insertion sort of buckets[0..n-1] by `weight` descending.
- * For n <= 24 (HUE_BUCKETS) this is O(n^2 / 2) ~= 288 comparisons in
- * the worst case -- faster and allocation-free vs `Array.prototype
- * .sort` which builds a temporary copy. */
-function sortInPlaceByWeightDesc(arr, n) {
-    for (let i = 1; i < n; i++) {
-        const cur = arr[i];
-        const curW = cur.weight;
-        let j = i - 1;
-        while (j >= 0 && arr[j].weight < curW) {
-            arr[j + 1] = arr[j];
-            j--;
-        }
-        arr[j + 1] = cur;
-    }
-}