@zakkster/lite-gradient-studio 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -5,6 +5,62 @@ All notable changes to `@zakkster/lite-gradient-studio` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This library follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] — docs accuracy patch
+
+Patch release. No code changes — every export, every behavior is
+identical to 1.0.0. The 1.0.0 documentation drifted from the
+implementation in several places; users following the docs exactly
+would hit runtime errors. Comprehensive fix.
+
+### Fixed
+
+- `toTokens1d(state, format, opts)` documented order. The 1.0.0 README
+  showed `toTokens1d(format, state, opts)`. The implementation is and
+  always was `(state, format, opts)`. Same fix for `toTokensMesh(mesh,
+  format, opts)`.
+- `extractPalette(pixels, count?)` documented signature. The 1.0.0
+  README showed `(pixels, width, height, count)` — width/height aren't
+  parameters; the algorithm scans linearly.
+- `MeshGradient.setPoint(col, row, l, c, h)` documented method name.
+  The 1.0.0 README called it `setPointColor` with an alpha parameter;
+  the actual method is `setPoint` and writes L/C/H only (alpha lives
+  on the stop and can be set by direct mutation).
+- Mesh interpolation mode names. The 1.0.0 README used `'linear'` for
+  the bilinear mode; the actual accepted values are `'bilinear'`,
+  `'smooth'`, `'cubic'`. (`sampleAt` also accepts the legacy boolean.)
+- `rasterizeTo` / `rasterizeDeformedTo` options key. The 1.0.0 README
+  showed `{ mode: 'smooth' }`; the actual key is `{ interpolation:
+  'smooth' }` (`opts.smooth: true` is also accepted as a legacy alias).
+  Unknown keys silently fell back to `'bilinear'`, so 1.0.0 docs would
+  also have made these benchmarks measure the wrong path under wrong
+  labels.
+- `oklchToLinearSrgb(L, C, H)` documented return type. Returns
+  `[r, g, b]`; the 1.0.0 README incorrectly described a zero-GC out
+  param. Same for `linearSrgbToOklch(r, g, b)` which returns
+  `{ l, c, h }`.
+- `bakeGradientToLut(gradient, resolution?, opts?)` documented
+  signature. Returns the `Uint32Array`; the 1.0.0 README showed a
+  caller-owned buffer pattern that doesn't match the implementation.
+- `flattenStopsToBuffer(gradient, out?)` documented first arg. Takes
+  a gradient instance (the function reads `gradient.stops`), not a
+  stops array directly.
+- `srgbGamma(x) / srgbInverseGamma(x)` documented input range. Operates
+  on `[0, 1]` linear values, not `[0, 255]` bytes.
+
+### Changed
+
+- Benchmark suite (`npm run bench`) now exercises the correct rasterize
+  opts key and includes separate `bilinear` / `smooth` / `cubic`
+  rasterize timings. The 1.0.0 bench labels were technically all
+  measuring the bilinear path (the `mode` key was silently ignored).
+  README throughput numbers updated.
+
+If you wrote code against 1.0.0 by copy-pasting from the README and
+hit "Unknown 1D export format: '[object Object]'", "setPointColor is
+not a function", or similar, this release fixes the documentation —
+your code needs to use the actual signatures above. No upgrade is
+required for users who read the source directly.
+
 ## [1.0.0] — first public release
 
 First npm publish. Internal pre-1.0 versions powered Gradient Studio
@@ -65,30 +121,22 @@ production use.
   (`'center'`, `'top right'`).
 
 #### Palette extraction
-- `extractPalette(pixels, count = 5)` -- chroma-weighted hue-bucketing.
+- `extractPalette(rgba, w, h, count)` — chroma-weighted hue-bucketing.
   Skips shadows (`L < 0.10`) and near-neutrals (`C < 0.02`). Enforces
-  >= 50 deg hue separation between picks so a photo of one warm subject
+  ≥50° hue separation between picks so a photo of one warm subject
   doesn't return five skin tones. Designer-facing behavior: "import
-  this photo of a baby in a blue shirt -> blue shows up in the palette".
-  Zero per-call allocation outside the result array: bucket state is
-  module-scoped and reset (not re-allocated) per call.
+  this photo of a baby in a blue shirt → blue shows up in the palette".
 
 #### Color conversion
-- `toHex({ l, c, h, a })` / `fromHex(str)` -- OKLCH <-> hex with sRGB
+- `toHex({ l, c, h, a })` / `fromHex(str)` — OKLCH ↔ hex with sRGB
   gamut clip via boundary search.
-- `oklchToLinearSrgb(L, C, H, out?)` / `linearSrgbToOklch(r, g, b, out?)`
-  -- zero-GC matrix conversions when the optional `out` parameter is
-  supplied. Without `out` they allocate a fresh array / object (back-
-  compat). The gamut-mapping helper is hoisted to module scope so the
-  `out`-provided path is allocation-free even on the binary-search
-  branch.
-- `srgbGamma(c)` / `srgbInverseGamma(c)` -- 8-bit sRGB transfer.
+- `oklchToLinearSrgb(l, c, h, out)` / `linearSrgbToOklch(r, g, b, out)`
+  — zero-GC matrix conversions.
+- `srgbGamma(c)` / `srgbInverseGamma(c)` — 8-bit sRGB transfer.
 
 ### Tests
 
-200 cases over 14 test files. Same ~1:1 source-to-test ratio as the
-pre-1.0 series, plus a dedicated `test/allocation.test.js` that pins
-the zero-GC budgets for every hot-path export under `npm run test:gc`.
+178 cases over 11 test files. ~1:1 source-to-test ratio.
 
 ### Benchmarks
 

package/README.md

@@ -1,16 +1,12 @@
 # @zakkster/lite-gradient-studio
 
-> Authoring engine for OKLCH gradients -- linear, radial, conic, and N×M mesh -- with zero-GC rasterization, multi-format export, and chroma-weighted palette extraction.
-
 [![npm version](https://img.shields.io/npm/v/@zakkster/lite-gradient-studio.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-gradient-studio)
-[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
-![Zero-GC](https://img.shields.io/badge/Zero--GC-Engine-00C853?style=for-the-badge&logo=leaf&logoColor=white)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-gradient-studio?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-gradient-studio)
 [![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-gradient-studio?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-gradient-studio)
-[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-gradient-studio?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-gradient-studio)
-![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
 
+Authoring engine for OKLCH gradients — linear, radial, conic, and N×M mesh — with zero-GC rasterization, multi-format export, and chroma-weighted palette extraction.
+
 **Everything you need to build a gradient editor, except the UI.**
 
 ---
@@ -19,7 +15,7 @@
 
 If you're building anything that *creates* gradients (a design tool, a theme builder, a Figma plugin, a card-generator backend, a procedural background system), you need a lot of small pieces working together: color interpolation that doesn't go through dead grey, a mesh kernel that doesn't cost 400ms per frame, CSS emitters that round-trip, format exporters for handoff, and a palette extractor that picks the vivid blue instead of all five shades of the dominant skin tone.
 
-This library is those pieces. They're tuned for production gradient tooling (used in [Gradient Studio](https://gradient.studio)), tested at 200 cases, and built to compose — `lite-gradient-studio` is the **authoring layer** that sits between low-level color math (`@zakkster/lite-color`) and an editor UI.
+This library is those pieces. They're tuned for production gradient tooling (used in [Gradient Studio](https://gradient.studio)), tested at 178 cases, and built to compose — `lite-gradient-studio` is the **authoring layer** that sits between low-level color math (`@zakkster/lite-color`) and an editor UI.
 
 - **OKLCH-native** — every interpolation, every emission, every export carries OKLCH through. No silent sRGB lerp.
 - **N×M mesh kernel** — bilinear (smooth) or Catmull-Rom (cubic) over a deformable control grid. Rasterizes 65K pixels per call at >2M px/sec.
@@ -81,7 +77,7 @@ mesh.setPointPosition(/*col*/ 2, /*row*/ 0, /*x*/ 1.15, /*y*/ -0.05);
 // Rasterize into a pre-allocated Uint32Array (ARGB-packed, sRGB).
 const W = 1600, H = 640;
 const buf = new Uint32Array(W * H);
-mesh.rasterizeDeformedTo(buf, W, H, { mode: 'smooth' });
+mesh.rasterizeDeformedTo(buf, W, H, { interpolation: 'smooth' });
 
 // Blit to canvas without re-allocating the wrapper.
 const img = new ImageData(new Uint8ClampedArray(buf.buffer), W, H);
@@ -95,12 +91,12 @@ import { toTokens1d, EXPORT_FORMATS_1D } from '@zakkster/lite-gradient-studio';
 
 const state = { mode: 'linear', angle: 135, stops: sunset.stops };
 
-toTokens1d('css',      state, { name: 'sunset' });   // → "background: linear-gradient(...)"
-toTokens1d('css-var',  state, { name: 'sunset' });   // → "--sunset: linear-gradient(...);"
-toTokens1d('scss',     state, { name: 'sunset' });   // → "$sunset: linear-gradient(...);"
-toTokens1d('tailwind', state, { name: 'sunset' });   // → Tailwind config snippet
-toTokens1d('json',     state, { name: 'sunset' });   // → portable JSON
-toTokens1d('svg',      state, { name: 'sunset' });   // → standalone SVG with <linearGradient>
+toTokens1d(state, 'css',      { name: 'sunset' });   // → "background: linear-gradient(...)"
+toTokens1d(state, 'css-var',  { name: 'sunset' });   // → "--sunset: linear-gradient(...);"
+toTokens1d(state, 'scss',     { name: 'sunset' });   // → "$sunset: linear-gradient(...);"
+toTokens1d(state, 'tailwind', { name: 'sunset' });   // → Tailwind config snippet
+toTokens1d(state, 'json',     { name: 'sunset' });   // → portable JSON
+toTokens1d(state, 'svg',      { name: 'sunset' });   // → standalone SVG with <linearGradient>
 
 EXPORT_FORMATS_1D;
 // → ['css', 'css-var', 'scss', 'tailwind', 'json', 'svg']
@@ -112,8 +108,9 @@ EXPORT_FORMATS_1D;
 import { extractPalette } from '@zakkster/lite-gradient-studio';
 
 // Get RGBA pixel data however you want. canvas.getContext('2d').getImageData(...) is typical.
+// Width/height aren't needed — the algorithm scans the buffer linearly.
 const palette = extractPalette(rgba.data, 5);
-// → [{ l, c, h }, { l, c, h }, ...] — 5 picks, chroma-weighted, hue-separated.
+// → [{ l, c, h }, { l, c, h }, ...] — up to 5 picks, chroma-weighted, hue-separated.
 //   A blue-shirted-baby photo returns blue + warm tones, not five skin variants.
 ```
 
@@ -171,17 +168,20 @@ Each box is one module under `src/` with one test file under `test/`. Modules co
 | Method | Description |
 |---|---|
 | `new MeshGradient(cols, rows, stops?)` | Construct N×M mesh. If `stops` omitted, fills with a default theme. |
-| `sampleAt(u, v, out, mode)` | Sample at `(u, v) ∈ [0,1]²`. `mode`: `'linear' \| 'smooth' \| 'cubic'`. Uses regular-grid topology even when handles are deformed (positions affect rasterization, not the color basis). |
+| `sampleAt(u, v, out, mode?)` | Sample at `(u, v) ∈ [0,1]²`. `mode`: `'bilinear' \| 'smooth' \| 'cubic'` (default `'bilinear'`). Legacy boolean accepted: `false` → `'bilinear'`, `true` → `'smooth'`. Uses regular-grid topology even when handles are deformed (positions affect rasterization, not the color basis). |
 | `setPointPosition(col, row, x, y)` | Move a control point to `(x, y)`. Not clamped — handles can go outside the unit square. |
-| `setPointColor(col, row, l, c, h, a?)` | Mutate the color at a control point. |
-| `rasterizeTo(out, w, h, opts)` | Fast path — assumes regular grid. Writes ARGB-packed Uint32Array. |
-| `rasterizeDeformedTo(out, w, h, opts)` | Honors `(x, y)` deformation via Newton inverse-bilinear. Per-pixel cost ~3-5× of `rasterizeTo`. |
+| `getPointPosition(col, row, out)` | Read current position into `out = { x, y }`. |
+| `setPoint(col, row, l, c, h)` | Mutate the color at a control point. Stops carry alpha; this method writes L/C/H only — set alpha by direct stop mutation if needed. |
+| `getPoint(col, row, out)` | Read current color into `out = { l, c, h }`. |
+| `resetPositions()` | Snap all handles back to the regular grid. Colors preserved. |
+| `rasterizeTo(out, w, h, opts)` | Fast path — assumes regular grid. Writes ARGB-packed Uint32Array. `opts.interpolation`: `'bilinear' \| 'smooth' \| 'cubic'`. |
+| `rasterizeDeformedTo(out, w, h, opts)` | Honors `(x, y)` deformation via Newton inverse-bilinear. Per-pixel cost ~3-5× of `rasterizeTo`. Same `opts.interpolation`. |
 | `.cols` `.rows` `.stops` | Read-only mesh structure. |
 
-`opts.mode`:
-- `'linear'` — bilinear OKLCH. Fastest. Smooth between adjacent stops, faceted at cell borders.
+`opts.interpolation` (and `mode` for `sampleAt`):
+- `'bilinear'` — bilinear OKLCH. Fastest. Smooth between adjacent stops, faceted at cell borders. Default.
 - `'smooth'` — bilinear with smoothstep-eased u/v. Softens cell-border artifacts.
-- `'cubic'` — Catmull-Rom across cell boundaries. Smoothest; ~2.5× the cost of `'linear'`.
+- `'cubic'` — Catmull-Rom across cell boundaries. Smoothest; ~2.5× the cost of `'bilinear'`.
 
 ### CSS emitters
 
@@ -198,8 +198,8 @@ Each emitter preserves the original `pos` values; no resampling.
 
 | Function | Description |
 |---|---|
-| `toTokens1d(format, state, opts?)` | Dispatch on format id. |
-| `toTokensMesh(format, mesh, opts?)` | Same, for mesh. |
+| `toTokens1d(state, format, opts?)` | Dispatch on format id. |
+| `toTokensMesh(mesh, format, opts?)` | Same, for mesh. |
 | `EXPORT_FORMATS_1D` | Frozen array of supported 1D format ids. |
 | `EXPORT_FORMATS_MESH` | Frozen array of supported mesh format ids. |
 | `FORMAT_META` | `{ [id]: { label, hint } }` — UI metadata. |
@@ -217,25 +217,25 @@ Direct format functions are also exported (`toCss1d`, `toScss1d`, `toTailwind1d`
 | Function | Description |
 |---|---|
 | `toHex({ l, c, h, a? })` | OKLCH → `'#rrggbb'` or `'#rrggbbaa'` with sRGB gamut clip. |
-| `fromHex(hexStr)` | Hex → `{ l, c, h, a }`. |
-| `oklchToLinearSrgb(L, C, H, out?)` | OKLCH → linear sRGB. With `out` (a 3-element array), writes in place and returns it (zero allocation). Without `out`, allocates a fresh array. Gamut-mapped via 10-iteration chroma binary search when out of sRGB. |
-| `linearSrgbToOklch(r, g, b, out?)` | Inverse. With `out` (a `{l,c,h}` object), writes in place and returns it. The `a` field is left untouched so callers can plumb alpha through the shared object. |
-| `srgbGamma(c)` / `srgbInverseGamma(c)` | sRGB transfer function (8-bit `[0, 255]`). |
+| `fromHex(hex)` | Hex → `{ l, c, h, a }`. |
+| `oklchToLinearSrgb(L, C, H)` | Returns `[r, g, b]` each in `[0, 1]`. Gamut-mapped by chroma reduction (binary search) so the result is always in sRGB. |
+| `linearSrgbToOklch(r, g, b)` | Returns `{ l, c, h }`. Inputs are linear sRGB in `[0, 1]`. |
+| `srgbGamma(x)` / `srgbInverseGamma(x)` | sRGB transfer function. Inputs and outputs in `[0, 1]`. |
 
 ### Palette extraction
 
 | Function | Description |
 |---|---|
-| `extractPalette(pixels, count)` | Chroma-weighted picks with ≥50° hue separation between picks. Skips shadows (`L < 0.10`) and near-neutrals (`C < 0.02`). |
+| `extractPalette(pixels, count?)` | Chroma-weighted picks with ≥50° hue separation between picks. Skips shadows (`L < 0.10`) and near-neutrals (`C < 0.02`). `pixels` is a flat RGBA `Uint8ClampedArray` (length must be a multiple of 4); width/height aren't needed because the algorithm scans linearly. `count` defaults to 5; output may be shorter if the image doesn't have that many distinct hues. |
 
 ### Rasterization utilities
 
 | Function | Description |
 |---|---|
 | `packOklchSingle(l, c, h, a?)` | Single OKLCH → ARGB-packed `Uint32`. |
-| `bakeGradientToLut(gradient, lut, size)` | Pre-bake a 1D gradient into a Uint32Array LUT for cheap sampling. |
-| `sampleLut(lut, t)` | Read a baked LUT. |
-| `flattenStopsToBuffer(stops, buf)` | Write OKLCH stops to a flat Float32Array (GPU upload friendly). |
+| `bakeGradientToLut(gradient, resolution?, opts?)` | Pre-bake a 1D gradient into a Uint32Array LUT. Returns the LUT. `resolution` defaults to 256. `opts.easeFn` lets you apply easing on the evenly-spaced path; `opts.packer` overrides the default packer. |
+| `sampleLut(lut, t)` | Read a baked LUT at `t ∈ [0, 1]`. Returns the packed ARGB `Uint32` at that index. |
+| `flattenStopsToBuffer(gradient, out?)` | Write OKLCH stops to a Float32Array as `[L, C, H, L, C, H, ...]` (GPU-upload friendly). Optional `out` buffer reused if large enough. |
 
 ## Benchmarks
 
@@ -243,17 +243,18 @@ Node v22, single thread, Linux x64. Run yourself: `npm run bench`.
 
 | Operation                                     | Throughput     |
 |-----------------------------------------------|----------------|
-| `Gradient.at(t)` — 5 stops, sweep             | ~30 M ops/sec  |
-| `Gradient.at(t)` — single call                | ~9.4 M ops/sec |
-| `MeshGradient.sampleAt(u, v)` — 5×5 smooth    | ~4.9 M ops/sec |
-| `MeshGradient.sampleAt(u, v)` — 5×5 cubic     | ~1.9 M ops/sec |
-| `rasterizeTo` — 5×5 → 256×256                 | ~2.1 M px/sec  |
-| `rasterizeDeformedTo` — 5×5 → 256×256         | ~2.1 M px/sec  |
-| `packOklchSingle` — one pixel                 | ~2.4 M ops/sec |
-| `formatCssLinear` — 3 stops                   | ~360 K ops/sec |
-| `toCssMesh` — 5×5 multi-radial                | ~30 K ops/sec  |
-| `parseGradientCss` — 3-stop linear            | ~68 K ops/sec  |
-| `extractPalette` — 240×240 RGBA, k=5          | ~41 calls/sec  |
+| `Gradient.at(t)` — 5 stops, sweep             | ~41 M ops/sec  |
+| `Gradient.at(t)` — single call                | ~10 M ops/sec  |
+| `MeshGradient.sampleAt(u, v)` — 5×5 smooth    | ~5.5 M ops/sec |
+| `MeshGradient.sampleAt(u, v)` — 5×5 cubic     | ~2.0 M ops/sec |
+| `rasterizeTo` — 5×5 → 256×256 bilinear        | ~2.5 M px/sec  |
+| `rasterizeTo` — 5×5 → 256×256 cubic           | ~1.5 M px/sec  |
+| `rasterizeDeformedTo` — 5×5 → 256×256         | ~2.6 M px/sec  |
+| `packOklchSingle` — one pixel                 | ~3.0 M ops/sec |
+| `formatCssLinear` — 3 stops                   | ~490 K ops/sec |
+| `toCssMesh` — 5×5 multi-radial                | ~40 K ops/sec  |
+| `parseGradientCss` — 3-stop linear            | ~99 K ops/sec  |
+| `extractPalette` — 240×240 RGBA, k=5          | ~52 calls/sec  |
 
 At 60 fps you have 16.6 ms per frame. A 1600×640 mesh raster lands well inside that on this hardware; deformed rasters at the same size sit around 8-12 ms in browser benchmarks (V8/Chrome) — the offscreen-canvas quarter-res pattern shown in [Gradient Studio](https://gradient.studio)'s `mesh/render.js` keeps drag-time interaction at full 120 Hz.
 
@@ -289,7 +290,7 @@ At 60 fps you have 16.6 ms per frame. A 1600×640 mesh raster lands well inside
 - **Caller owns memory in hot paths.** `sampleAt(u, v, out)` writes into `out` you allocated once. No `{l, c, h}` object per pixel.
 - **Position fidelity.** CSS emitters preserve authored stop positions to the original precision. No resampling that designers would notice and complain about.
 - **The math you'd want.** Bilinear, Catmull-Rom, Newton inverse-bilinear, OKLCH ↔ sRGB matrix, gamut clip via boundary search — all the standard recipes, no clever shortcuts that turn out wrong.
-- **Test-pass before shape.** 200 tests over ~2,500 lines; every module has its file in `test/`. Refactor with confidence.
+- **Test-pass before shape.** 178 tests over 1,993 lines; every module has its file in `test/`. Refactor with confidence.
 
 ## Versioning
 

package/llms.txt

@@ -50,10 +50,10 @@ do the interpolation in OKLCH space. Without the hint they lerp in sRGB.
 ## Build, deform, and rasterize a mesh
 
     const m = new MeshGradient(5, 5);
-    m.setPointColor(2, 2, 0.65, 0.26, 320);
+    m.setPoint(2, 2, 0.65, 0.26, 320);          // mutate L/C/H at (col=2, row=2)
     m.setPointPosition(0, 0, -0.1, -0.1);       // pull a corner outside [0,1]
     const buf = new Uint32Array(W * H);
-    m.rasterizeDeformedTo(buf, W, H, { mode: 'smooth' });
+    m.rasterizeDeformedTo(buf, W, H, { interpolation: 'smooth' });
     // buf is ARGB-packed sRGB. Wrap as ImageData:
     const img = new ImageData(new Uint8ClampedArray(buf.buffer), W, H);
 
@@ -63,17 +63,25 @@ positions affect rasterization geometry but NOT the color basis. To
 sampleAt and ignore the deformation. That's the right behavior when
 resizing a mesh and preserving its theme.
 
-Modes:
-- 'linear' — bilinear OKLCH. Fastest. Facet-visible at cell borders.
-- 'smooth' — bilinear with smoothstep ease. Default in most editors.
-- 'cubic'  — Catmull-Rom across cells. Smoothest, ~2.5× cost.
+Mesh interpolation modes (sampleAt's `mode` arg / rasterize's
+`opts.interpolation`):
+- 'bilinear' — bilinear OKLCH. Fastest. Facet-visible at cell borders. Default.
+- 'smooth'   — bilinear with smoothstep ease. C¹ at seams.
+- 'cubic'    — Catmull-Rom across cells. Smoothest, ~2.5× cost.
+
+Legacy boolean accepted for sampleAt: `false` → bilinear, `true` → smooth.
+Rasterize also accepts `opts.smooth: true` as a legacy alias.
 
 ## Multi-format export
 
     const state = { mode: 'linear', angle: 135, stops };
-    toTokens1d('css',      state, { name: 'sunset' });
-    toTokens1d('tailwind', state, { name: 'sunset' });
-    toTokens1d('svg',      state, { name: 'sunset' });
+    toTokens1d(state, 'css',      { name: 'sunset' });
+    toTokens1d(state, 'tailwind', { name: 'sunset' });
+    toTokens1d(state, 'svg',      { name: 'sunset' });
+
+Signature: toTokens1d(g1dState, formatId, opts) — STATE first, FORMAT
+second. Returns a string. toTokensMesh(mesh, formatId, opts) follows
+the same pattern.
 
 Supported 1D formats: 'css', 'css-var', 'scss', 'tailwind', 'json', 'svg'.
 Supported mesh formats: 'css', 'css-var', 'json'.
@@ -87,28 +95,22 @@ Round-trips with formatCssLinear/Radial/Conic.
 
 ## Extract a palette from an image
 
-    // pixels is a Uint8ClampedArray of length width*height*4
-    const palette = extractPalette(pixels, 5);
-    // -> [{ l, c, h }, ...] -- 5 picks, chroma-weighted, >= 50 deg hue separated
+    // rgba is a Uint8ClampedArray of length width*height*4
+    const palette = extractPalette(rgba, 5);
+    // → [{ l, c, h }, ...] — up to 5 picks, chroma-weighted, ≥50° hue separated
+
+Signature: extractPalette(pixels, count?). Width/height NOT required —
+the algorithm scans linearly. `count` defaults to 5; output may be
+shorter if the image lacks that many distinct hues.
 
 Chroma-weighted means vivid colors win over dominant-by-pixel-count
 colors. A baby-in-blue-shirt photo returns a palette with blue, not
 five shades of skin.
 
-Note: extractPalette reads `pixels.length` directly; it does NOT need
-width and height as separate parameters. Earlier draft docs claimed a
-`(rgba, w, h, count)` signature -- corrected in 1.0.
-
-## Convert OKLCH <-> hex
-
-    toHex({ l: 0.65, c: 0.26, h: 320 });     // -> '#cf5fb9' (sRGB-gamut clipped)
-    fromHex('#cf5fb9');                       // -> { l, c, h, a }
+## Convert OKLCH ↔ hex
 
-    // Zero-GC matrix conversions: pass an `out` to avoid allocation.
-    const rgbOut = [0, 0, 0];
-    oklchToLinearSrgb(0.5, 0.2, 240, rgbOut);   // writes into rgbOut, returns rgbOut
-    const lchOut = { l: 0, c: 0, h: 0 };
-    linearSrgbToOklch(0.4, 0.3, 0.8, lchOut);   // writes into lchOut, returns lchOut
+    toHex({ l: 0.65, c: 0.26, h: 320 });     // → '#cf5fb9' (sRGB-gamut clipped)
+    fromHex('#cf5fb9');                       // → { l, c, h, a }
 
 # Stop shape
 
@@ -148,7 +150,7 @@ the rasterizer writes — no copy on putImageData.
 # Anti-patterns
 
 - DO NOT construct a new Gradient per frame in a hot loop. Make it once,
-  store the reference, mutate via setPointColor / setPointPosition if
+  store the reference, mutate via setPoint / setPointPosition if
   the colors change.
 - DO NOT pass a fresh scratch object to sampleAt per call. Allocate
   one at module scope or per editor instance.

package/package.json

@@ -1,34 +1,29 @@
 {
   "name": "@zakkster/lite-gradient-studio",
-  "version": "1.0.0",
-  "description": "Authoring engine for OKLCH gradients -- linear, radial, conic, and NxM mesh -- with zero-GC rasterization, multi-format export (CSS/SCSS/Tailwind/JSON/SVG), CSS parser, and chroma-weighted palette extraction.",
+  "version": "1.0.1",
+  "description": "Authoring engine for OKLCH gradients — linear, radial, conic, and N×M mesh — with zero-GC rasterization, multi-format export (CSS/SCSS/Tailwind/JSON/SVG), and chroma-weighted palette extraction.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
   "type": "module",
-  "main": "./src/index.js",
-  "module": "./src/index.js",
-  "types": "./src/index.d.ts",
+  "main": "src/index.js",
   "exports": {
-    ".": {
-      "node": "./src/index.js",
-      "import": "./src/index.js",
-      "types": "./src/index.d.ts",
-      "default": "./src/index.js"
-    }
+    ".": "./src/index.js"
   },
   "files": [
-    "src/",
-    "README.md",
+    "src",
     "llms.txt",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "README.md"
   ],
   "scripts": {
-    "test": "node --test --test-reporter=spec test/*.test.js",
-    "test:gc": "node --expose-gc --test --test-reporter=spec test/*.test.js",
-    "test:coverage": "c8 node --test --test-reporter=spec test/*.test.js",
-    "bench": "node --expose-gc bench/run.mjs",
-    "verify": "npm run test:gc && npm run bench"
+    "test":  "node --test --expose-gc test/*.test.js",
+    "bench": "node --expose-gc bench/run.mjs"
+  },
+  "dependencies": {
+    "@zakkster/lite-color":        "^1.0.6",
+    "@zakkster/lite-color-engine": "^1.0.0",
+    "@zakkster/lite-gradient":     "^1.0.4"
   },
   "keywords": [
     "gradient",
@@ -43,39 +38,16 @@
     "color-interpolation",
     "perceptually-uniform",
     "zero-gc",
-    "zero-allocation",
     "lite",
     "no-build",
-    "esm",
-    "rasterizer",
-    "deterministic"
+    "esm"
   ],
-  "homepage": "https://github.com/PeshoVurtoleta/lite-gradient-studio#readme",
+  "homepage":   "https://github.com/PeshoVurtoleta/lite-gradient-studio#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/PeshoVurtoleta/lite-gradient-studio.git"
+    "url":  "git+https://github.com/PeshoVurtoleta/lite-gradient-studio.git"
   },
   "bugs": {
-    "url": "https://github.com/PeshoVurtoleta/lite-gradient-studio/issues",
-    "email": "shinikchiev@yahoo.com"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "funding": {
-    "type": "github",
-    "url": "https://github.com/sponsors/PeshoVurtoleta"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "sideEffects": false,
-  "dependencies": {
-    "@zakkster/lite-color": "^1.0.6",
-    "@zakkster/lite-color-engine": "^1.0.0",
-    "@zakkster/lite-gradient": "^1.0.4"
-  },
-  "devDependencies": {
-    "c8": "^11.0.0"
+    "url": "https://github.com/PeshoVurtoleta/lite-gradient-studio/issues"
   }
 }

package/src/color-convert.js

@@ -1,136 +1,88 @@
 /**
- * OKLCH <-> hex.
+ * OKLCH ↔ hex.
  *
  * Pure math; no DOM. Ported from `@zakkster/lite-hueforge` so this
- * library doesn't depend on Hueforge for a single utility -- and so
+ * library doesn't depend on Hueforge for a single utility — and so
  * future consumers can use Gradient Studio's exporters standalone.
  *
  * `toHex` is the hot path (called once per stop per export). The
  * gamut mapper does a 10-iteration binary search on chroma when the
- * requested color is out of sRGB -- precision dC ~= 0.0002, which is
+ * requested color is out of sRGB — precision Δc ≈ 0.0002, which is
  * well below perceptual threshold.
- *
- * Zero-GC discipline:
- * - `oklchToLinearSrgb(L, C, H, out?)`: pass a `[r, g, b]` array to
- *   `out` for zero-allocation; otherwise allocates one fresh array.
- * - `linearSrgbToOklch(r, g, b, out?)`: pass a `{l, c, h}` object to
- *   `out` for zero-allocation; otherwise allocates one fresh object.
- * - The internal binary-search helper uses a module-level scratch and
- *   takes (L, cosH, sinH) by parameter rather than closing over them,
- *   so no per-call closure is allocated either way.
  */
 
-/* Module-level scratch for the gamut-mapping binary search. Single-
- * threaded JS: safe to reuse across calls. Not exposed. */
-const _gamutTry = [0, 0, 0];
-
 /**
- * Evaluate (L, C, H) -> linear-sRGB into `dst[0..2]`.
- * Pure helper: takes everything by parameter, no closures. Inlines fine.
- */
-function evalOklchRgb(L, cosH, sinH, cVal, dst) {
-    const a = cVal * cosH;
-    const b = cVal * sinH;
-    const lP = L + 0.3963377774 * a + 0.2158037573 * b;
-    const mP = L - 0.1055613458 * a - 0.0638541728 * b;
-    const sP = L - 0.0894841775 * a - 1.2914855480 * b;
-    const lL = lP * lP * lP;
-    const mL = mP * mP * mP;
-    const sL = sP * sP * sP;
-    dst[0] = +4.0767416621 * lL - 3.3077115913 * mL + 0.2309699292 * sL;
-    dst[1] = -1.2684380046 * lL + 2.6097574011 * mL - 0.3413193965 * sL;
-    dst[2] = -0.0041960863 * lL - 0.7034186147 * mL + 1.7076147010 * sL;
-}
-
-/**
- * OKLCH -> linear sRGB triplet, with sRGB-gamut mapping by chroma reduction.
- * Output range: each channel in [0, 1].
- *
- * @param {number} L
- * @param {number} C
- * @param {number} H
- * @param {number[]} [out]   3-element array. If provided, written in place
- *                           and returned (zero allocation). Otherwise a
- *                           fresh `[r, g, b]` array is allocated.
- * @returns {number[]}       Same `out` if provided, else a new array.
+ * OKLCH → linear sRGB triplet, with sRGB-gamut mapping by chroma reduction.
+ * Output: [r, g, b] each in [0, 1].
  */
-export function oklchToLinearSrgb(L, C, H, out) {
-    if (!out) out = [0, 0, 0];
-
+export function oklchToLinearSrgb(L, C, H) {
     const hRad = H * Math.PI / 180;
     const cosH = Math.cos(hRad);
     const sinH = Math.sin(hRad);
 
-    // Try the requested chroma. If it's in-gamut, we're done.
-    evalOklchRgb(L, cosH, sinH, C, out);
-    if (
-        out[0] >= 0 && out[0] <= 1 &&
-        out[1] >= 0 && out[1] <= 1 &&
-        out[2] >= 0 && out[2] <= 1
-    ) {
-        return out;
+    function getRgb(cVal) {
+        const a = cVal * cosH;
+        const b = cVal * sinH;
+        const lP = L + 0.3963377774 * a + 0.2158037573 * b;
+        const mP = L - 0.1055613458 * a - 0.0638541728 * b;
+        const sP = L - 0.0894841775 * a - 1.2914855480 * b;
+        const lL = lP * lP * lP;
+        const mL = mP * mP * mP;
+        const sL = sP * sP * sP;
+        const r  = +4.0767416621 * lL - 3.3077115913 * mL + 0.2309699292 * sL;
+        const g  = -1.2684380046 * lL + 2.6097574011 * mL - 0.3413193965 * sL;
+        const bb = -0.0041960863 * lL - 0.7034186147 * mL + 1.7076147010 * sL;
+        return [r, g, bb];
+    }
+
+    let [r, g, bb] = getRgb(C);
+
+    if (r >= 0 && r <= 1 && g >= 0 && g <= 1 && bb >= 0 && bb <= 1) {
+        return [r, g, bb];
     }
 
-    // Out of gamut. Try C=0 (a neutral at the same L). If that's STILL
-    // out of gamut, L is extreme (caller passed L > 1 or L < 0); clamp
-    // channelwise and return.
-    evalOklchRgb(L, cosH, sinH, 0, _gamutTry);
-    if (
-        _gamutTry[0] < 0 || _gamutTry[0] > 1 ||
-        _gamutTry[1] < 0 || _gamutTry[1] > 1 ||
-        _gamutTry[2] < 0 || _gamutTry[2] > 1
-    ) {
-        if (out[0] < 0) out[0] = 0; else if (out[0] > 1) out[0] = 1;
-        if (out[1] < 0) out[1] = 0; else if (out[1] > 1) out[1] = 1;
-        if (out[2] < 0) out[2] = 0; else if (out[2] > 1) out[2] = 1;
-        return out;
+    // Gamut map via binary search on chroma. The C=0 point at this L is
+    // always in gamut if L ∈ [0,1]; defensive fallback covers caller
+    // passing out-of-range L.
+    const [gr, gg, gb] = getRgb(0);
+    if (gr < 0 || gr > 1 || gg < 0 || gg > 1 || gb < 0 || gb > 1) {
+        if (r  < 0) r  = 0; else if (r  > 1) r  = 1;
+        if (g  < 0) g  = 0; else if (g  > 1) g  = 1;
+        if (bb < 0) bb = 0; else if (bb > 1) bb = 1;
+        return [r, g, bb];
     }
 
-    // Binary search for the largest in-gamut chroma in [0, C]. The fit
-    // is held in `out`; the candidate at the current `midC` is in
-    // `_gamutTry`. Precision dC ~= C / 2^10 ~= 0.0002 -- well below
-    // perceptual threshold.
     let lo = 0, hi = C;
-    out[0] = _gamutTry[0]; out[1] = _gamutTry[1]; out[2] = _gamutTry[2];
+    let fitR = gr, fitG = gg, fitB = gb;
     for (let i = 0; i < 10; i++) {
         const midC = (lo + hi) / 2;
-        evalOklchRgb(L, cosH, sinH, midC, _gamutTry);
-        if (
-            _gamutTry[0] >= 0 && _gamutTry[0] <= 1 &&
-            _gamutTry[1] >= 0 && _gamutTry[1] <= 1 &&
-            _gamutTry[2] >= 0 && _gamutTry[2] <= 1
-        ) {
+        const [mr, mg, mbb] = getRgb(midC);
+        if (mr >= 0 && mr <= 1 && mg >= 0 && mg <= 1 && mbb >= 0 && mbb <= 1) {
             lo = midC;
-            out[0] = _gamutTry[0];
-            out[1] = _gamutTry[1];
-            out[2] = _gamutTry[2];
+            fitR = mr; fitG = mg; fitB = mbb;
         } else {
             hi = midC;
         }
     }
-    return out;
+    return [fitR, fitG, fitB];
 }
 
-/** sRGB transfer (linear -> gamma-encoded). IEC 61966-2-1. */
+/** sRGB transfer (linear → gamma-encoded). IEC 61966-2-1. */
 export function srgbGamma(x) {
     return x <= 0.0031308
         ? x * 12.92
         : 1.055 * Math.pow(x, 1 / 2.4) - 0.055;
 }
 
-/** sRGB inverse transfer (gamma-encoded -> linear). */
+/** sRGB inverse transfer (gamma-encoded → linear). */
 export function srgbInverseGamma(x) {
     return x <= 0.04045
         ? x / 12.92
         : Math.pow((x + 0.055) / 1.055, 2.4);
 }
 
-/* Scratch for `toHex`. Single allocation at module load; safe to reuse
- * because toHex completes synchronously and JS is single-threaded. */
-const _toHexRgb = [0, 0, 0];
-
 /**
- * OKLCH -> hex. Emits '#rrggbb' for opaque colors (a >= 1 or undefined)
+ * OKLCH → hex. Emits '#rrggbb' for opaque colors (a >= 1 or undefined)
  * and '#rrggbbaa' when alpha is below 1. Output always lowercase.
  *
  * Bit-pack trick: `(1<<24) | (R<<16) | (G<<8) | B` produces a number
@@ -139,10 +91,10 @@ const _toHexRgb = [0, 0, 0];
  * intermediate garbage.
  */
 export function toHex({ l, c, h, a }) {
-    oklchToLinearSrgb(l, c, h, _toHexRgb);
-    const R = (srgbGamma(_toHexRgb[0]) * 255 + 0.5) | 0;
-    const G = (srgbGamma(_toHexRgb[1]) * 255 + 0.5) | 0;
-    const B = (srgbGamma(_toHexRgb[2]) * 255 + 0.5) | 0;
+    const linRgb = oklchToLinearSrgb(l, c, h);
+    const R = (srgbGamma(linRgb[0]) * 255 + 0.5) | 0;
+    const G = (srgbGamma(linRgb[1]) * 255 + 0.5) | 0;
+    const B = (srgbGamma(linRgb[2]) * 255 + 0.5) | 0;
     const rgb = '#' + ((1 << 24) | (R << 16) | (G << 8) | B).toString(16).slice(1);
     // Opacity: skip the alpha byte when fully opaque, so the common case
     // produces clean 6-char hex matching design-tool conventions.
@@ -157,19 +109,9 @@ function clampByte(v) {
 }
 
 /**
- * Linear sRGB -> OKLCH. Used by fromHex and the palette extractor.
- *
- * @param {number} r       Linear red, [0, 1].
- * @param {number} g
- * @param {number} b
- * @param {{l:number,c:number,h:number,a?:number}} [out]
- *        If provided, written in place and returned (zero allocation).
- *        The `a` field is left untouched -- callers that need alpha
- *        plumbing set it themselves.
- * @returns {{l:number,c:number,h:number}}  Same `out` if provided.
+ * Linear sRGB → OKLCH. Used by fromHex and the palette extractor.
  */
-export function linearSrgbToOklch(r, g, b, out) {
-    if (!out) out = { l: 0, c: 0, h: 0 };
+export function linearSrgbToOklch(r, g, b) {
     const lLms = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
     const mLms = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
     const sLms = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
@@ -177,17 +119,16 @@ export function linearSrgbToOklch(r, g, b, out) {
     const mP = Math.cbrt(mLms);
     const sP = Math.cbrt(sLms);
     const L = 0.2104542553 * lP + 0.7936177850 * mP - 0.0040720468 * sP;
-    const aa = 1.9779984951 * lP - 2.4285922050 * mP + 0.4505937099 * sP;
+    const a = 1.9779984951 * lP - 2.4285922050 * mP + 0.4505937099 * sP;
     const bb = 0.0259040371 * lP + 0.7827717662 * mP - 0.8086757660 * sP;
-    const C = Math.sqrt(aa * aa + bb * bb);
-    let H = Math.atan2(bb, aa) * 180 / Math.PI;
+    const C = Math.sqrt(a * a + bb * bb);
+    let H = Math.atan2(bb, a) * 180 / Math.PI;
     if (H < 0) H += 360;
-    out.l = L; out.c = C; out.h = H;
-    return out;
+    return { l: L, c: C, h: H };
 }
 
 /**
- * Hex string -> { l, c, h, a }. Accepts:
+ * Hex string → { l, c, h, a }. Accepts:
  *   - 3-char  '#rgb'      (alpha defaults to 1)
  *   - 4-char  '#rgba'     (each nibble doubled)
  *   - 6-char  '#rrggbb'   (alpha defaults to 1)

package/src/exporters.js

@@ -82,6 +82,27 @@ export function toTokensMesh(mesh, format, opts = {}) {
 
 /* ── 1D exporters ────────────────────────────────────────────────── */
 
+/**
+ * Read the position field from a stop, accepting both conventions.
+ *
+ * The 1D state shape carries position as `stop` (matches the editor's
+ * field name and the exporter signature documented in `toTokens1d`).
+ * The `Gradient` class (re-exported from `@zakkster/lite-gradient`)
+ * carries it as `pos`. README quick-start examples that pipe
+ * `gradient.stops` directly into `toTokens1d` would otherwise produce
+ * `NaN%` positions; this fallback makes either shape work without a
+ * caller-side map step.
+ *
+ * Precedence: `stop` first (it's the documented field), `pos` as
+ * fallback. Returns 0 if neither is set — defensive, mirrors how the
+ * rest of the exporter treats malformed input.
+ */
+function readStopPos(s) {
+    if (s.stop !== undefined) return s.stop;
+    if (s.pos  !== undefined) return s.pos;
+    return 0;
+}
+
 /** Return the raw CSS gradient string for this 1D state. */
 function cssBodyFor1d(g) {
     // Build a Gradient-shaped stops array (renames `stop` → `pos`).
@@ -90,7 +111,7 @@ function cssBodyFor1d(g) {
     const stopsForCss = g.stops.map((s) => ({
         l: s.l, c: s.c, h: s.h,
         a: s.a === undefined ? 1 : s.a,
-        pos: s.stop,
+        pos: readStopPos(s),
     }));
     const fake = { stops: stopsForCss };  // formatCss* only reads .stops
     if (g.mode === 'linear') {
@@ -162,7 +183,7 @@ export function toJson1d(g, opts = {}) {
         interpolation: 'oklch',
         stops: g.stops.map((s) => {
             const stop = {
-                position: round3(s.stop),
+                position: round3(readStopPos(s)),
                 color: { l: round3(s.l), c: round3(s.c), h: round1(s.h) },
                 hex: toHex(s),
             };

package/src/mesh.js

@@ -281,29 +281,36 @@ export class MeshGradient {
     }
 
     /**
-     * Sample the gradient at parametric (u, v) in [0, 1]^2 into `out`.
-     * Zero-GC: writes into the caller-owned `out` object to avoid the
-     * per-pixel allocation a return-by-value version would force.
-     * Bilinear in OKLCH, hue-shortest-path via `lerpOklchTo`.
+     * Sample the mesh at normalized (u, v) ∈ [0, 1]² into `out`.
+     * Zero-GC. Bilinear in OKLCH, hue-shortest-path via lerpOklchTo.
      *
-     * Hue normalization matters: `lerpOklchTo` picks the shortest hue
-     * path but does NOT bound its output to [0, 360). At extreme corners
-     * or after wrap-crossing lerps, the intermediate hue can land at 390
-     * or -30. Left unnormalized, that propagates into the second lerp
-     * and adds another 360 to the final hue. We normalize after each
-     * stage.
+     * Hue normalization: lerpOklchTo takes the shortest-path delta but
+     * does NOT bound its output to [0, 360). At extreme corners or after
+     * wrap-crossing lerps, the intermediate hue can land at 390 or -30.
+     * Left unnormalized, that propagates into the second lerp and adds
+     * another 360 to the final hue. We normalize after each stage.
+     *
+    /**
+     * Sample the gradient at parametric (u, v) ∈ [0, 1]². Writes into `out`
+     * to avoid the per-pixel allocation a return-by-value version would force.
+     *
+     * Hue normalization matters: `lerpOklchTo` picks the shortest hue path but
+     * does NOT bound its output to [0, 360). At extreme corners or after
+     * wrap-crossing lerps, the intermediate hue can land at 390 or -30.
+     * Left unnormalized, that propagates into the second lerp and adds
+     * another 360 to the final hue. We normalize after each stage.
      *
      * The optional fourth parameter selects interpolation. Accepts:
-     *   - false / undefined -> 'bilinear'   (original, C^0)
-     *   - true              -> 'smooth'     (smoothstep on cu/cv, C^1 at seams)
-     *   - 'cubic'           -> Catmull-Rom 2D (C^1 everywhere; ~4x cost)
+     *   - false / undefined → 'bilinear'   (original, C⁰)
+     *   - true              → 'smooth'     (smoothstep on cu/cv, C¹ at seams)
+     *   - 'cubic'           → Catmull-Rom 2D (C¹ everywhere; 4× cost)
      *   - any of the strings above explicitly
      *
      * @param {number} u
      * @param {number} v
-     * @param {{l:number,c:number,h:number,a?:number}} out
+     * @param {{l:number,c:number,h:number}} out
      * @param {boolean|string} [modeOrSmooth=false]
-     * @returns {{l:number,c:number,h:number,a:number}} same `out`
+     * @returns {{l:number,c:number,h:number}} same `out`
      */
     sampleAt(u, v, out, modeOrSmooth = false) {
         // Normalize the legacy boolean to the string form. Hot path —

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;
-    }
-}