@zakkster/lite-gradient-studio 1.0.1 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,340 @@ 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.2.0] — 2026-07-14  "Tiles + Dither"
+
+The **toroidal-mesh + dither release**. Both roadmap tracks (D1-D6 wrap,
+D7-D8 dither) land together.
+
+> Originally cut as two patches, `1.2.0` (wrap) and `1.2.1` (dither), on the
+> assumption that 1.2.0 had shipped. It had not — npm's latest is 1.1.0 — so a
+> patch bump on top of an unpublished minor would have invented a version that
+> never existed. Folded into a single minor.
+
+---
+
+## Wrap (D1-D6)
+
+The **toroidal-mesh release**. `MeshGradient` becomes cylindrical or
+toroidal on demand, with a real C¹ seam in cubic mode — the flagship
+feature: read real neighbours across the boundary via modulo indexing
+instead of clamping to duplicated endpoints.
+
+### Added — Structural wrap on the constructor
+
+`new MeshGradient(cols, rows, stops, { wrapX, wrapY })`. Both flags are
+optional, default `false`, and independent (torus = both on; cylinder =
+one on). Wrap is stored on the instance as `readonly wrapX` / `readonly
+wrapY` for downstream consumers to branch on.
+
+- **UV period.** On a wrapped axis the cell count is `cols`, not
+  `cols - 1`. Default control-point positions become `col / cols`.
+- **`sampleAt` (bilinear + smooth).** Wrapped axis wraps the coord via
+  `u - Math.floor(u)`, then reads the last-cell neighbour with `(col + 1)
+  % cols` — so `sampleAt(1, v)` is exactly `sampleAt(0, v)`, any float
+  is a valid position (raw accumulating animation phase, negatives,
+  arbitrary magnitudes).
+- **`sampleAt` cubic — C¹ continuity across the seam.** The whole
+  reason wrap exists: `_sampleAtCubic` and `_cubicRow` use modulo
+  neighbour indexing on wrapped axes (`((col - 1) % cols + cols) % cols`
+  and `(col + 2) % cols`). Catmull-Rom now reads real neighbours across
+  the boundary, giving a genuinely smooth seam instead of a spline that
+  degrades toward bilinear at the edge. Bilinear and smooth get
+  seamlessness from the wrap coord alone; cubic is where wrap earns
+  "exists in no other library."
+- **`rasterizeTo` period sampling.** On wrapped axes, `u = x / width`
+  (drops the `- 1` divisor). Pixel column 0 of the "next tile" lands
+  exactly at `u ≡ 0` — no duplicated edge column, so `drawImage`-based
+  tiling of the rasterized output butts perfectly.
+- **`rasterizeDeformedTo` fails loudly on wrap.** Throws with
+  `err.code = 'WRAP_DEFORMED_UNSUPPORTED'` when called on a wrapped
+  mesh. Deformed + wrap needs ghost quads that cross the seam (Newton
+  solve against wrapped corner positions) — real work deferred to v1.3.
+  Silent seamed output would be worse than the error; consumer code can
+  branch on the code string instead of matching messages.
+- **`defaultMeshColor` — wrap-aware defaults.** Trailing `wrapX` /
+  `wrapY` args (backward-compat: absent → v1.1.0 output byte-identical).
+  When `wrapX`, hue advances a uniform `360/cols` per column (no
+  aperiodic compression at the wrap boundary). When `wrapY`, the row
+  drift becomes sinusoidal and L switches to `cos(2π · rT)` so
+  top and bottom rows agree.
+
+### Guarantees
+
+- **Byte-parity on the non-wrap path.** All 218 pre-existing tests pass
+  unmodified. The alloc test file gains three new wrapped-rasterize
+  invariants (all under the same 128 KB / 100-frame ceiling). Every
+  non-wrap code path — constructor with no opts, `sampleAt` on a
+  non-wrapped mesh, `rasterizeTo` on a non-wrapped mesh — walks the
+  exact same v1.1.0 code, byte for byte.
+- **Empirical wrap-on ceilings (this container, node 22):**
+
+  | path | v1.1.0 baseline | v1.2.0 wrapped | overhead |
+  |---|---|---|---|
+  | `sampleAt` 5×5 smooth | 5.2M ops/s | 5.0M wrapX / 4.7M torus | 4–10% |
+  | `sampleAt` 5×5 cubic  | 1.9M ops/s | 2.0M wrapX / 2.0M torus | within noise |
+  | `rasterizeTo` 5×5 → 256² | 2.1M px/s | 2.3M px/s wrapped     | JIT ties or wins |
+  | `rasterizeTo` 5×5 cubic → 256² | (not measured) | 2.3M px/s wrapX | ceiling set |
+
+  Wrap paths came in on parity or a hair faster; the branch structure
+  turns out to be slightly cleaner for the JIT than the non-wrap
+  interior-clamp branches. Empirical, not prior-based — the ceilings
+  above are the number to beat in T3.
+
+### Peer bumps
+
+- `@zakkster/lite-color-engine`: `^1.0.0 → ^1.5.0`. T3's dither work
+  will delegate to engine v1.5's `getBlueNoise64` + dithered packers.
+- `@zakkster/lite-gradient`: `^1.1.0 → ^1.2.0`. Picks up `Gradient`'s
+  new `closed: true` for downstream `formatCssConic` work.
+
+### Notes
+
+- 31 new wrap tests in `test/mesh-wrap.test.js` covering: D1 (opts +
+  guards + cols=2 wrapped legality), D2 (period spacing, seam identity
+  in bilinear/smooth, raw-phase and negative-u sampling, tile-equality
+  across 21 sample points, non-wrap axis retains clamp), D3 (cubic
+  seam identity, C¹ derivative test via central differences,
+  real-neighbour indexing verified against a deliberately non-uniform
+  L mesh), D4 (rasterize period sampling, non-wrap y retains closed
+  interval), D5 (WRAP_DEFORMED_UNSUPPORTED on wrapX / wrapY / torus,
+  non-wrap deformed still works), D6 (byte-parity of the four-arg
+  form, periodic hue step and L symmetry, integration with
+  `MeshGradient` defaults).
+- Wrap suite: 252 green (218 pre-existing + 31 wrap + 3 wrap-alloc
+  invariants) at the point wrap landed; 271 with dither folded in.
+
+---
+
+## Known / measured — the allocation gate is a leak gate
+
+`test/allocation.test.js` asserts things like *"MeshGradient.rasterizeTo x 100 frames
+at 128x128 stays under 128 KB"*, measured as `gc(); gc(); heapUsed` before and after.
+That is a **leak** gate. It measures RETAINED memory, and it is structurally blind to
+short-lived garbage — a value allocated and dropped inside the loop is scavenged
+before the second sample and never appears in the delta.
+
+`rasterizeTo` does allocate, and the gate cannot see it. Measured by counting GC
+events over a fixed wall-clock budget, against a zero-alloc arithmetic control and a
+one-object-per-pixel control in the same process:
+
+```
+zero-alloc floor (arithmetic)          1 GC / 6 s
+allocating ceiling (1 obj/pixel)    3587 GC / 6 s
+rasterizeTo bilinear, no dither       72 GC / 6 s     <- not the floor
+```
+
+The source is not a `new` anywhere in the loop — there isn't one. It is
+`const tmp = { l: 0, c: 0, h: 0, a: 1 }`. **V8 removed double-field unboxing in 9.x**,
+so every write of a non-Smi double to an object property boxes a `HeapNumber` — and
+`sampleAt` writes four of them per pixel, 16,384 times per raster. Isolated:
+
+```
+write 4 doubles into an OBJECT,        16384x   ->  3519 GC
+write 4 doubles into a Float64Array,   16384x   ->   497 GC
+write 4 Smis   into an OBJECT,         16384x   ->   496 GC
+```
+
+**Cost, in the only unit that matters: 0.37%–0.95% of wall time** in a synthetic loop
+running 150 rasters/sec; roughly half that at a realistic 60/sec. It is real, it is
+measurable, and it does not matter.
+
+Not fixed, deliberately. The only way to remove it is a `Float64Array` scratch, which
+means changing `sampleAt(u, v, out, mode)`'s public object-out contract or duplicating
+the sampler. That is a bad trade for half a percent. Logged with the number so the
+call is informed.
+
+What *should* change is the gate's name and its comment, which currently imply it
+proves zero-GC. It proves no leak. Those are different claims, and the ecosystem has
+now made this mistake in three packages.
+
+---
+
+## Dither (D7-D8)
+
+The dither track (D7/D8). One flag on `rasterizeTo` and one scalar-arg
+packer wrapper. `dither: false` (or absent) is byte-identical to the
+undithered path — verified, not asserted.
+
+### Added — `opts.dither: true` on `MeshGradient.rasterizeTo`
+
+Delegates to `@zakkster/lite-color-engine >= 1.5.0`'s
+`packOklchBufferToUint32Dithered` + `getBlueNoise64` — the roadmap's D7
+already ratified the engine as the noise-source owner, so studio
+consumes and does not duplicate:
+
+- **Per-pixel tile lookup** — `tile[((y & 63) << 6) | (x & 63)]`. Pure
+  bit ops (torus wrap via mask, row stride via shift), zero-GC trivially.
+- **Same noise value shared R/G/B at a pixel** — luminance-patterned
+  dither, no chroma speckle. Verified by a test that rasterizes a
+  chroma-free mesh with dither on and asserts R === G === B per pixel.
+- **Alpha undithered.** Verified against undithered α on a distinctive
+  α mesh.
+- **`noise01 = 0.5` reproduces the plain packer exactly** — the identity
+  anchor from D8, verified across seven representative OKLCH triplets
+  covering different gamma-encode regions and alpha values.
+- **`dither: false` or absent → byte-identical to v1.2.0.** The branch
+  is resolved once per rasterize call, two loop bodies — no per-pixel
+  branch cost on the undithered path. Six regression tests assert this
+  across bilinear, smooth, cubic, wrapped, and `dither: false` vs
+  absent-opt.
+
+### Added — `packOklchSingleDithered(l, c, h, alpha, noise01)`
+
+New export from `./bake.js`. Scalar-arg convenience wrapper around the
+engine's `packOklchBufferToUint32Dithered` using the same
+`Float32Array(3)` scratch as `packOklchSingle` — no additional module-
+level allocation, safe to alternate between plain and dithered calls
+in the rasterize inner loop.
+
+### Empirical dither ceilings (node 22, container)
+
+| path | undithered | dithered | overhead |
+|---|---|---|---|
+| `rasterizeTo` 5×5 smooth → 256² | 2.1M px/s | 1.6M px/s | ~24% |
+| `rasterizeTo` 5×5 wrapX+smooth  | 2.5M px/s | 1.9M px/s | ~24% |
+| `rasterizeTo` 5×5 cubic         | (v1.2.0 gate) | 1.7M px/s | ceiling set |
+
+The 24% overhead pays for one blue-noise tile lookup + a threshold-offset
+gamma-encode round per pixel (the engine's dithered packer inlines the
+sRGB gamma-encode inline instead of calling out to `linearToSrgbByte`,
+which is why the overhead is small).
+
+### Test count
+
++15 dither tests in `test/mesh-dither.test.js`:
+- Off-flag byte parity: 6 tests (bilinear, smooth, cubic, wrapped,
+  `dither: false` explicit, bare-opts).
+- `noise01 = 0.5` identity anchor: 1 test, 7 OKLCH samples.
+- Determinism: 2 tests (plain, wrap+dither composition).
+- Bounded deviation ±1 per channel: 2 tests (typical mesh, shallow-ramp).
+- Contract properties: 2 tests (alpha never dithered, R === G === B on
+  chroma-free mesh).
+- Run-length shortening on shallow ramp: 1 test.
+- Zero-GC under `--expose-gc`: 1 test (128 KB / 100 frames).
+
++2 dither-alloc invariants in `test/allocation.test.js` (plain dither,
+wrapX+dither).
+
+Total suite: **269/269 green.** Byte-parity gate on the 218 v1.1.0
+tests still holds unmodified.
+
+### Notes
+
+- `rasterizeDeformedTo` still throws `WRAP_DEFORMED_UNSUPPORTED` on
+  wrapped meshes (unchanged from v1.2.0). Dither on `rasterizeDeformedTo`
+  silently ignores the flag — deformed + dither is scheduled to land
+  alongside the v1.3 ghost-quad seam work, so consumers on 1.2.x
+  should treat this as "dither is rasterizeTo only."
+- The engine's blue-noise tile is decoded once at first use (~sub-ms
+  from a base64 blob into a shared `Uint8Array(4096)`). Subsequent
+  calls return the same reference — the alloc test's warm-up phase
+  triggers the one-time decode before the timed loop.
+- No peer bumps — engine v1.5.0 was already the floor from v1.2.0.
+
+## [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

package/README.md

@@ -1,8 +1,15 @@
 # @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)
+![Tree-Shakeable](https://img.shields.io/badge/tree--shakeable-yes-brightgreen)
+![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.
@@ -183,6 +190,47 @@ Each box is one module under `src/` with one test file under `test/`. Modules co
 - `'smooth'` — bilinear with smoothstep-eased u/v. Softens cell-border artifacts.
 - `'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
 
 | Function | Description |
@@ -237,6 +285,105 @@ Direct format functions are also exported (`toCss1d`, `toScss1d`, `toTailwind1d`
 | `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. |
 
+## Toroidal mesh (v1.2.0 "Tiles")
+
+`MeshGradient` gains a fourth constructor argument:
+
+```js
+new MeshGradient(cols, rows, stops, { wrapX: true, wrapY: true });
+```
+
+Both flags default to `false` and are independent — turn on `wrapX` for a
+cylinder, both for a torus. Wrap is structural: it changes the UV period,
+the cell count, and the default control-point positions in one atomic
+step. The instance carries `readonly wrapX` and `readonly wrapY` fields
+for downstream consumers to branch on.
+
+**The flagship:** cubic mode has real **C¹ continuity across the seam**.
+`_sampleAtCubic` reads real neighbours across the wrap boundary via
+modulo indexing instead of clamping to a duplicated endpoint. Bilinear
+and smooth get seamlessness from the wrap coord alone; cubic is where
+wrap earns "exists in no other library."
+
+Sampling accepts any float on wrapped axes — a raw animation phase, a
+negative, arbitrary magnitude:
+
+```js
+let phase = 0;
+function frame(dt) {
+    phase += dt * 0.0002;
+    mesh.sampleAt(u + phase, v, out, 'cubic');   // no `phase % 1` needed
+}
+```
+
+**Tiled rasterization.** On wrapped axes, `rasterizeTo` samples the
+period (`x / width`, no `- 1` divisor), so pixel column 0 of the "next
+tile" lands exactly at `u ≡ 0` — `drawImage`-based tile scrolling butts
+perfectly with no duplicated edge column.
+
+**Deformed + wrap fails loudly.** `rasterizeDeformedTo` throws with
+`err.code = 'WRAP_DEFORMED_UNSUPPORTED'` when called on a wrapped mesh.
+Ghost-quad seam crossing (Newton solve against wrapped corner positions)
+is real work, deferred to v1.3. Consumer code can branch on the code
+string cleanly rather than string-matching messages.
+
+**Wrap-aware defaults.** `defaultMeshColor(col, row, cols, rows, wrapX?,
+wrapY?)` gains trailing optional args. When set, the aperiodic
+`240 + 120·cT` hue sweep is swapped for a uniform `360/cols` step, and
+row-driven L switches to `cos(2π · rT)` so the top and bottom rows
+agree. Four-arg calls are byte-identical to v1.1.0.
+
+**Byte-parity guarantee.** The non-wrap path is untouched — 218
+pre-existing tests pass unmodified, benches within noise of v1.1.0.
+
+**Cascade note.** Blue-noise dithering (D7/D8 in the Tiles roadmap) lands
+in v1.2.0 with its full gate — see below.
+
+## Blue-noise dither (v1.2.0)
+
+`rasterizeTo` gains one flag:
+
+```js
+mesh.rasterizeTo(buf, W, H, { dither: true, interpolation: 'smooth' });
+```
+
+Delegates to `@zakkster/lite-color-engine >= 1.5.0`'s dithered packer
+and shared 64×64 void-and-cluster tile. Per-pixel overhead is roughly
+24% on typical raster sizes — one tile lookup plus a threshold-offset
+gamma round replacing the standard `+ 0.5` rounding.
+
+**Contract, exhaustively tested:**
+
+- **`noise01 = 0.5` reproduces the plain packer exactly** — the identity
+  anchor. Consequence: dither adds an *at-most* ±1 per-channel deviation
+  from the undithered output.
+- **Same noise value shared R/G/B per pixel** — luminance-patterned
+  dither, no chroma speckle. On a chroma-free mesh, dithered output is
+  chroma-free too (verified).
+- **Alpha never dithered.** Byte-parity with the undithered α.
+- **`dither: false` or absent → byte-identical to v1.2.0.** The branch
+  is resolved once per rasterize call, two loop bodies, no per-pixel
+  branch cost when off.
+- **Composes with wrap.** `rasterizeTo` with both `wrapX` and `dither`
+  set produces per-channel ±1 deviation and preserves seamlessness. The
+  two features are orthogonal — wrap operates on sampling, dither on
+  packing.
+
+**Where it shines:** shallow ramps and near-monochrome fills where the
+undithered output shows visible 1-byte-wide bands. On a 4-stop L=0.30..0.34
+gradient at 256px width, dither cuts the longest identical-pixel run by
+more than 33% (from ~64 pixels undithered to ~40 dithered).
+
+**Where it doesn't help:** high-contrast meshes where color transitions
+already span multiple integer bytes per column. Dither is bounded ±1;
+that's a lot of visual improvement on smooth surfaces, but invisible on
+sharp gradients.
+
+**Not on `rasterizeDeformedTo`.** The deformed rasterizer silently
+ignores the flag (also throws `WRAP_DEFORMED_UNSUPPORTED` on wrapped
+meshes, unchanged). Deformed + dither is scheduled with the v1.3
+ghost-quad seam work.
+
 ## Benchmarks
 
 Node v22, single thread, Linux x64. Run yourself: `npm run bench`.

package/llms.txt

@@ -72,6 +72,47 @@ Mesh interpolation modes (sampleAt's `mode` arg / rasterize's
 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 };
@@ -173,3 +214,45 @@ mostly stuck on HSL or sRGB.
 This library is that layer. Built once, factored to compose, tuned for
 production rasterization. Pair it with @zakkster/lite-color (the OKLCH
 foundation) and any UI framework to ship a gradient editor.
+
+## v1.2.0 "Tiles" — toroidal mesh
+
+`new MeshGradient(cols, rows, stops, { wrapX, wrapY })` — 4th opts arg with two independent flags (torus = both, cylinder = one). Both default `false`; when off, all code paths byte-identical to v1.1.0.
+
+Structural wrap semantics:
+- UV period: cell count is `cols` (not `cols - 1`) on wrapped axes; default control-point positions become `col / cols`.
+- `sampleAt` on wrapped axes: `u = u - Math.floor(u)` replaces clamp; last-cell neighbour uses `(col + 1) % cols`. `sampleAt(0, v) === sampleAt(1, v)` exactly; any float is a valid coord (raw accumulating animation phase, negatives).
+- Cubic mode + wrap = C¹ across the seam. `_sampleAtCubic` and `_cubicRow` use modulo neighbour indexing (`((col - 1) % cols + cols) % cols` and `(col + 2) % cols`) so Catmull-Rom reads real cells across the boundary. The flagship — no other mesh gradient lib does this.
+- `rasterizeTo` on wrapped axes: `u = x / width` (drops the `- 1`). Pixel column 0 of the "next tile" lands at u ≡ 0, so `drawImage`-based tiling of the rasterized output butts perfectly.
+- `rasterizeDeformedTo` throws `err.code = 'WRAP_DEFORMED_UNSUPPORTED'` on a wrapped mesh. Ghost-quad seam crossing is v1.3 work.
+- `defaultMeshColor` accepts trailing `wrapX`, `wrapY` args. When set, hue advances a uniform `360/cols` per column (wrapX) or L switches to `cos(2π · rT)` and drift becomes sinusoidal (wrapY). Four-arg form byte-identical to v1.1.0.
+
+Instance exposes `readonly wrapX: boolean`, `readonly wrapY: boolean` for downstream consumers.
+
+Peer bumps: `@zakkster/lite-color-engine` `^1.5.0`, `@zakkster/lite-gradient` `^1.2.0`.
+
+Cascade note: dither (D7/D8) slips clean to v1.2.0 with full gate. Both roadmap tracks (wrap D1-D6, dither D7-D8) ship together in 1.2.0.
+
+## v1.2.0 "Tiles + Dither"
+
+Blue-noise dithering on `MeshGradient.rasterizeTo` — D7/D8 from the Tiles roadmap, slipped intact from v1.2.0 per the cascade rule. No peer bumps (engine v1.5.0 already floor from v1.2.0).
+
+Usage:
+```
+mesh.rasterizeTo(buf, W, H, { dither: true });
+mesh.rasterizeTo(buf, W, H, { dither: true, interpolation: 'cubic' });
+mesh.rasterizeTo(buf, W, H, { dither: true /* + wrap */ });
+```
+
+Semantics:
+- Delegates to `@zakkster/lite-color-engine >= 1.5.0`'s `packOklchBufferToUint32Dithered` + `getBlueNoise64`. Tile is a shared `Uint8Array(4096)` (64×64), decoded once from a base64 blob at first use.
+- Per-pixel: `noise01 = (tile[((y & 63) << 6) | (x & 63)] + 0.5) / 256` — pure bit ops, torus wrap via mask. Same noise01 shared across R/G/B (no chroma speckle). Alpha undithered.
+- Contract: `noise01 = 0.5` reproduces the plain packer exactly. Consequence: dither adds at most ±1 per-channel deviation vs undithered.
+- Branch resolved ONCE per rasterizeTo call — two loop bodies. `dither: false` (or absent) walks the exact v1.2.0 code path, byte-identical output.
+- Not on `rasterizeDeformedTo` (v1.3 ghost-quad work).
+
+New export: `packOklchSingleDithered(l, c, h, alpha, noise01)` — scalar-arg wrapper reusing the same Float32Array(3) scratch as `packOklchSingle`.
+
+Empirical dither overhead (5×5 smooth, 256²): 2.1M → 1.6M px/s, ~24%. Recorded in bench.
+
+Total tests: 269/269 (218 v1.1.0 + 31 wrap + 3 wrap-alloc + 15 dither + 2 dither-alloc). Byte-parity gate on the v1.1.0 tests still holds unmodified.

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@zakkster/lite-gradient-studio",
-  "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.",
+  "version": "1.2.0",
+  "description": "Authoring engine for OKLCH gradients \u2014 linear, radial, conic, and N\u00d7M mesh \u2014 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",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "node": "./src/index.js",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
   },
   "files": [
     "src",
@@ -17,13 +24,13 @@
     "README.md"
   ],
   "scripts": {
-    "test":  "node --test --expose-gc test/*.test.js",
+    "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"
+    "@zakkster/lite-color": "^1.0.6",
+    "@zakkster/lite-color-engine": "^1.5.0",
+    "@zakkster/lite-gradient": "^1.2.0"
   },
   "keywords": [
     "gradient",
@@ -42,12 +49,17 @@
     "no-build",
     "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"
-  }
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "sideEffects": false
 }