@zakkster/lite-gradient-studio 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,165 @@ 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.1.0] — 2026-07-03
+
+### Added — Monochrome mesh
+
+Mesh-level analogue of the `monochromeGradient` factory that shipped in
+`@zakkster/lite-gradient` v1.1.0. Both together form a coordinated
+monochrome capability across the ecosystem — 1D continuous gradients in
+lite-gradient, 2D deformable meshes in lite-gradient-studio.
+
+- **`monochromeMesh(base, cols, rows, opts?)`** — factory returning a
+  `MeshGradient` where every control point shares `base.c` and `base.h`
+  (or `c=0` if `mode: 'grayscale'`); only L varies according to
+  `direction`. Post-construction, the returned mesh behaves like any
+  other `MeshGradient` — `setPointPosition(...)` to warp the L
+  distribution off-grid, `rasterizeTo(...)` / `rasterizeDeformedTo(...)`
+  to render.
+
+- **Options:**
+  - `mode`: `'tinted'` (default) | `'grayscale'`
+  - `range`: `[lo, hi]` with `0 <= lo < hi <= 1`, default `[0, 1]`
+  - `direction`: `'horizontal'` | `'vertical'` | `'diagonal'` (default) | `'radial'`
+
+- **Directions:**
+  - `'horizontal'` — L varies left-to-right, uniform per row (equivalent
+    to a linear gradient, but with mesh deformability post-hoc).
+  - `'vertical'` — L varies top-to-bottom, uniform per column.
+  - `'diagonal'` (default) — top-left corner (lo) to bottom-right
+    corner (hi). Uses both axes meaningfully — the most versatile default.
+  - `'radial'` — center (lo) outward to corners (hi). Atmospheric,
+    "premium background" feel.
+
+- **Type declarations:** `MonoMode`, `MonoMeshDirection`,
+  `MonochromeMeshOptions`, plus the factory signature in
+  `src/index.d.ts`.
+
+- **Re-exports flow through:** `monochromeGradient`, `gradientMonoWarm`,
+  `gradientMonoCool` from `@zakkster/lite-gradient` v1.1.0 are already
+  visible via the existing `export * from '@zakkster/lite-gradient'`
+  in `src/index.js`. No new studio-level 1D monochrome factory needed;
+  users import from either package interchangeably.
+
+### Why this matters
+
+Designer feedback on the mesh-gradient positioning (the original
+mesh-gradient authoring focus) surfaced two problems: (1) AI image
+generators can produce arbitrary decorative gradients on demand, eating
+the "generate a wild gradient" use case at the low end; (2) designers
+doing client work don't have creative freedom to ship wild mesh
+gradients — they're constrained to brand palettes.
+
+Monochrome mesh dodges both problems. The palette is fixed to a single
+brand tone (nothing "wild" or "random-looking"); the mesh capability
+still gives designers organic-feeling backgrounds that flat 1D
+gradients can't — subtle asymmetry via `setPointPosition`, off-center
+radial gradients, non-linear L distributions. Same authoring surface,
+narrower creative space that lands in the client-work zone.
+
+### Peer dependency bump
+
+- `@zakkster/lite-gradient`: `^1.0.4` → `^1.1.0`
+
+Existing consumers using only pre-1.1.0 exports continue to work
+identically. The bump ensures `monochromeGradient` and the two Mono
+presets are guaranteed available via the re-export.
+
+### Tests
+
+18 new tests across `test/mesh-monochrome.test.js`. Coverage: the four
+directions (verified by inspecting the initialized `stops` array — e.g.
+horizontal makes row 0 == row 1 == row 2; radial makes center = lo and
+all four corners = hi), both modes, custom range, sampling correctness,
+every validation throw path, and base non-mutation.
+
+The 4 previously-failing `color-convert.test.js` tests (documented in
+1.0.1 as a docs-vs-implementation mismatch) now pass — see "Fixed"
+below. Total: 218 tests, **203 pass**, 0 fail, 15 skipped.
+
+### Fixed
+
+- **`oklchToLinearSrgb(L, C, H, out?)` and `linearSrgbToOklch(r, g, b, out?)`
+  now honor the optional `out` parameter** documented since 1.0.0 in
+  `index.d.ts` and covered by tests that had been failing since publish.
+  Pass a caller-owned 3-element array (or `{ l, c, h }` object) as the
+  final argument; the function writes into it in place and returns the
+  same reference — zero allocation on the hot path. Omitting `out` (or
+  passing `null` / `undefined`) preserves the existing 3-arg call shape
+  and returns a freshly-allocated result.
+
+  Real impact: `oklchToLinearSrgb` is called per-pixel in `rasterizeTo` /
+  `rasterizeDeformedTo` and per-color in every exporter. Callers threading
+  a scratch array through that hot loop can now avoid allocating one
+  triplet per pixel. Existing 3-arg calls are unchanged.
+
+  The 1.0.1 CHANGELOG framed this as "docs drifted from implementation"
+  and rolled back the docs. That was a stopgap. The correct resolution
+  was implementing the feature the docs, types, and tests all documented;
+  this ship does that. Non-breaking either way (the 3-arg signature is
+  a strict subset of the new 4-arg signature).
+
+### Non-breaking
+
+Additive only. No existing API surface changed.
+
+## [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 +224,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

@@ -11,6 +11,8 @@
 ![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 +21,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 +83,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 +97,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 +114,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 +174,61 @@ 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'`.
+
+### Monochrome mesh (v1.1.0)
+
+Mesh-level analogue of `lite-gradient`'s `monochromeGradient` — chroma and hue held
+constant across every control point; only lightness varies. Client-work-friendly:
+subtle premium backgrounds without the "AI-generated random gradient" look.
+
+```js
+import { monochromeMesh } from '@zakkster/lite-gradient-studio';
+
+// 3×3 mesh, all points share the brand hue, L varies diagonally
+const mesh = monochromeMesh({ l: 0.5, c: 0.06, h: 245 }, 3, 3);
+
+// Rasterize to a canvas
+const buf = new Uint32Array(800 * 600);
+mesh.rasterizeTo(buf, 800, 600);
+const img = new ImageData(new Uint8ClampedArray(buf.buffer), 800, 600);
+ctx.putImageData(img, 0, 0);
+
+// Or emit CSS (canvas-free rendering)
+const css = formatCssMesh(mesh);
+element.style.background = css;
+```
+
+**`monochromeMesh(base, cols, rows, opts?)`** → `MeshGradient`
+
+| Option      | Type                                                          | Default        | Notes                                                                       |
+|-------------|---------------------------------------------------------------|----------------|-----------------------------------------------------------------------------|
+| `mode`      | `'tinted' \| 'grayscale'`                                     | `'tinted'`     | `'tinted'` retains base c/h; `'grayscale'` forces c=0.                      |
+| `range`     | `[number, number]`                                            | `[0, 1]`       | L-axis endpoints. Must satisfy `0 ≤ lo < hi ≤ 1`.                           |
+| `direction` | `'horizontal' \| 'vertical' \| 'diagonal' \| 'radial'`        | `'diagonal'`   | How L varies across the mesh. See below.                                    |
+
+**Directions:**
+- **`'horizontal'`** — L varies left-to-right, uniform across each row. Like a linear gradient, but you can deform post-hoc.
+- **`'vertical'`** — L varies top-to-bottom, uniform across each column.
+- **`'diagonal'`** (default) — top-left corner (lo) to bottom-right corner (hi). Most versatile; uses both axes meaningfully.
+- **`'radial'`** — center (lo) outward to corners (hi). Atmospheric "premium" feel.
+
+Post-construction, you can `setPointPosition(...)` to warp the L distribution off-grid
+— something you can't do with a flat 1D gradient. This is what mesh capability buys you
+in the client-work scenario: brand-safe base + designer-controlled organic character.
 
 ### CSS emitters
 
@@ -198,8 +245,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 +264,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 +290,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 +337,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,66 @@ 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.
+
+## Monochrome mesh (v1.1.0)
+
+Factory for meshes where every control point shares base c/h (or c=0 for
+grayscale) and only L varies across the grid. Client-work-friendly:
+never looks like an "AI-generated random gradient" because the palette
+is fixed to one brand tone.
+
+    import { monochromeMesh, formatCssMesh } from '@zakkster/lite-gradient-studio';
+
+    // Brand-tinted mesh, L varies diagonally
+    const m = monochromeMesh({ l: 0.5, c: 0.06, h: 245 }, 3, 3);
+
+    // Or explicit direction + grayscale + printable-safe range
+    const gm = monochromeMesh(
+        { l: 0.5, c: 0, h: 0 },
+        4, 4,
+        { mode: 'grayscale', range: [0.05, 0.95], direction: 'radial' }
+    );
+
+    // Emit CSS without canvas
+    element.style.background = formatCssMesh(m);
+
+Options:
+- mode:       'tinted' (default) | 'grayscale'
+- range:      [lo, hi] with 0 <= lo < hi <= 1 (default [0, 1])
+- direction:  'horizontal' | 'vertical' | 'diagonal' (default) | 'radial'
+
+Directions:
+- horizontal:  L varies left-to-right, uniform per row
+- vertical:    L varies top-to-bottom, uniform per column
+- diagonal:    top-left corner (lo) to bottom-right corner (hi)
+- radial:      center (lo) outward to corners (hi)
+
+Returns a MeshGradient. All post-construction methods (setPointPosition,
+setPoint, sampleAt, rasterizeTo, etc.) work as normal — the factory just
+initializes the color basis. Deform handles off-grid to warp L across
+the surface without disturbing the brand palette.
+
+Pairs with @zakkster/lite-gradient's monochromeGradient(base, opts) which
+returns a continuous 1D Gradient; monochromeMesh returns a 2D MeshGradient.
 
 ## 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 +136,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 +191,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,7 +1,7 @@
 {
   "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.1.0",
+  "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",
@@ -10,25 +10,27 @@
   "types": "./src/index.d.ts",
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
       "node": "./src/index.js",
       "import": "./src/index.js",
-      "types": "./src/index.d.ts",
       "default": "./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.1.0"
   },
   "keywords": [
     "gradient",
@@ -43,12 +45,9 @@
     "color-interpolation",
     "perceptually-uniform",
     "zero-gc",
-    "zero-allocation",
     "lite",
     "no-build",
-    "esm",
-    "rasterizer",
-    "deterministic"
+    "esm"
   ],
   "homepage": "https://github.com/PeshoVurtoleta/lite-gradient-studio#readme",
   "repository": {
@@ -56,26 +55,11 @@
     "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"
+    "url": "https://github.com/PeshoVurtoleta/lite-gradient-studio/issues"
   },
   "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"
-  }
+  "sideEffects": false
 }