@zakkster/lite-gradient-studio 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,237 @@ 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

package/README.md

@@ -8,6 +8,7 @@
 [![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)
 
@@ -284,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

@@ -214,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,7 +1,7 @@
 {
   "name": "@zakkster/lite-gradient-studio",
-  "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.",
+  "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",
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "@zakkster/lite-color": "^1.0.6",
-    "@zakkster/lite-color-engine": "^1.0.0",
-    "@zakkster/lite-gradient": "^1.1.0"
+    "@zakkster/lite-color-engine": "^1.5.0",
+    "@zakkster/lite-gradient": "^1.2.0"
   },
   "keywords": [
     "gradient",

package/src/bake.js

@@ -14,6 +14,7 @@
 import {
     bakeGradientToUint32,
     packOklchBufferToUint32,
+    packOklchBufferToUint32Dithered,
 } from '@zakkster/lite-color-engine';
 
 const EVEN_SPACING_EPS = 1e-9;
@@ -139,3 +140,38 @@ export function packOklchSingle(l, c, h, alpha = 1) {
     _packScratch[2] = h;
     return packOklchBufferToUint32(_packScratch, 0, alpha);
 }
+
+/**
+ * Scalar-arg convenience wrapper around lite-color-engine v1.5's
+ * `packOklchBufferToUint32Dithered`. Same output byte order (RGBA-LE),
+ * same gamma-encode semantics — the only difference from `packOklchSingle`
+ * is a threshold-offset applied at the round step: `byte = (enc*255 + noise01) | 0`
+ * instead of `(enc*255 + 0.5) | 0`.
+ *
+ * Contract from the engine (restated for T2 D8):
+ *   - The **same** noise value is used for R, G, and B at one pixel —
+ *     luminance-patterned dither, no chroma speckle.
+ *   - Alpha is undithered (banding on alpha is rarely visible and would
+ *     interact badly with premultiplication).
+ *   - `noise01 = 0.5` reproduces `packOklchSingle` exactly (identity
+ *     anchor — trivially provable by the +0.5 rounding in the plain
+ *     packer, which is what the dithered form emits at that noise value).
+ *
+ * Zero-GC: reuses the module-scoped `_packScratch` Float32Array(3) that
+ * `packOklchSingle` uses. Consumers must not call both in reentrant
+ * contexts (the studio rasterizers never do — one loop, one packer).
+ *
+ * @param {number} l  OKLCH lightness (0..1)
+ * @param {number} c  OKLCH chroma (~0..0.4)
+ * @param {number} h  OKLCH hue in degrees
+ * @param {number} alpha  (0..1); undithered
+ * @param {number} noise01  Threshold offset in [0, 1). Typically `(tile[i] + 0.5) / 256`
+ *   where `tile` is `getBlueNoise64()` from the engine.
+ * @returns {number} Uint32 RGBA-LE pixel.
+ */
+export function packOklchSingleDithered(l, c, h, alpha, noise01) {
+    _packScratch[0] = l;
+    _packScratch[1] = c;
+    _packScratch[2] = h;
+    return packOklchBufferToUint32Dithered(_packScratch, 0, alpha, noise01);
+}

package/src/index.d.ts

@@ -66,6 +66,23 @@ export interface MeshRasterizeOptions {
     interpolation?: InterpolationMode;
     /** Legacy boolean: `true` is equivalent to `interpolation: 'smooth'`. */
     smooth?: boolean;
+    /**
+     * v1.2.0 — blue-noise dithering (D8). When `true`, `rasterizeTo` uses
+     * `@zakkster/lite-color-engine`'s dithered packer with per-pixel
+     * threshold offsets from the engine's shared 64×64 void-and-cluster
+     * tile. Every channel is within ±1 of the undithered output; the
+     * same offset is shared across R/G/B at each pixel (no chroma
+     * speckle); alpha is undithered.
+     *
+     * `dither: false` (or absent) walks the same code as v1.2.0 — the
+     * byte-parity guarantee for undithered output is preserved.
+     *
+     * Not yet supported on `rasterizeDeformedTo` — throws
+     * `WRAP_DEFORMED_UNSUPPORTED` first if the mesh is wrapped, and
+     * silently ignores the flag otherwise (deformed + dither planned
+     * alongside the v1.3 ghost-quad seam work).
+     */
+    dither?: boolean;
 }
 
 /**
@@ -73,19 +90,58 @@ export interface MeshRasterizeOptions {
  * mesh. Pure function. Used internally by MeshGradient when no `stops` array
  * is supplied; re-exported for callers who want to inspect or override the
  * default field.
+ *
+ * v1.2.0 — trailing `wrapX` / `wrapY` args are optional and default to
+ * false. When set, the corresponding axis uses a periodic parameterization
+ * (uniform 360/cols hue step for wrapX; sinusoidal L and drift for wrapY)
+ * so the default mesh doesn't compress aperiodic sweeps into the final
+ * cell. Four-arg calls stay byte-identical to v1.1.0.
  */
 export function defaultMeshColor(
     col: number,
     row: number,
     cols: number,
     rows: number,
+    wrapX?: boolean,
+    wrapY?: boolean,
 ): OklchColor;
 
+/**
+ * Constructor options for {@link MeshGradient} (v1.2.0+).
+ *
+ * Wrap flags are structural — they change the UV period, the cell count,
+ * and the default control-point positions. Both flags are independent
+ * (torus = both on; cylinder = one on). Non-wrap behaviour is byte-parity
+ * with v1.1.0 when opts is absent or both flags are false.
+ */
+export interface MeshGradientOptions {
+    /**
+     * Treat the X axis as cyclic. `sampleAt` wraps u via `u - Math.floor(u)`,
+     * `rasterizeTo` samples the period (`x / width`, not `x / (width - 1)`),
+     * cubic mode reads real neighbours across the seam via modulo indexing
+     * (C¹ continuity). `rasterizeDeformedTo` throws
+     * `WRAP_DEFORMED_UNSUPPORTED` — ghost-quad seam crossing is deferred
+     * to v1.3.
+     */
+    wrapX?: boolean;
+    /** Symmetric to {@link wrapX} on the Y axis. */
+    wrapY?: boolean;
+}
+
 export class MeshGradient {
-    constructor(cols: number, rows: number, stops?: ReadonlyArray<MeshStop>);
+    constructor(
+        cols: number,
+        rows: number,
+        stops?: ReadonlyArray<MeshStop>,
+        opts?: MeshGradientOptions,
+    );
 
     readonly cols: number;
     readonly rows: number;
+    /** v1.2.0 — reflects the constructor opts; `false` when opts absent. */
+    readonly wrapX: boolean;
+    /** v1.2.0 — reflects the constructor opts; `false` when opts absent. */
+    readonly wrapY: boolean;
     readonly stops: MeshStopFull[];
 
     /** Read the (col, row) color into a caller-owned out. Zero-GC. */
@@ -108,6 +164,9 @@ export class MeshGradient {
      *   - true              -> 'smooth' (smoothstep)
      *   - 'cubic'           -> Catmull-Rom 2D
      *   - any of the strings above explicitly
+     *
+     * v1.2.0 — on wrapped axes, u/v accept any float; input is period-wrapped
+     * via `u - Math.floor(u)` before mapping to a cell coord.
      */
     sampleAt<T extends Partial<OklchColorA>>(
         u: number,
@@ -119,6 +178,10 @@ export class MeshGradient {
     /**
      * Rasterize on the REGULAR grid into a packed-RGBA Uint32Array (little-
      * endian byte order; aliasable as Uint8ClampedArray for ImageData).
+     *
+     * v1.2.0 — on wrapped axes, samples the period (drops the `- 1`
+     * divisor) so pixel column 0 of the "next tile" would land at u ≡ 0,
+     * enabling seamless `drawImage`-style tiling.
      */
     rasterizeTo(
         out: Uint32Array,
@@ -131,6 +194,10 @@ export class MeshGradient {
      * Rasterize honoring control-point positions (deformable mesh). Pixels
      * outside any quad are LEFT UNTOUCHED -- callers that want a clean
      * canvas must fill or zero `out` first.
+     *
+     * v1.2.0 — throws with `err.code = 'WRAP_DEFORMED_UNSUPPORTED'` when
+     * called on a wrapped mesh. Ghost-quad seam crossing is planned for
+     * v1.3; the current behaviour is loud failure instead of silent seams.
      */
     rasterizeDeformedTo(
         out: Uint32Array,
@@ -313,6 +380,21 @@ export function sampleLut(lut: Uint32Array, t: number): number;
 /** Pack a single OKLCH color directly to a 32-bit RGBA value. */
 export function packOklchSingle(l: number, c: number, h: number, alpha?: number): number;
 
+/**
+ * v1.2.0 — dithered scalar packer. Threshold-offset gamma round via
+ * `noise01`: `byte = (encoded * 255 + noise01) | 0`. `noise01 = 0.5`
+ * reproduces `packOklchSingle` exactly (identity anchor). Same buffer
+ * scratch as `packOklchSingle` — safe to alternate between calls, but
+ * do NOT interleave with the plain packer in reentrant contexts.
+ */
+export function packOklchSingleDithered(
+    l: number,
+    c: number,
+    h: number,
+    alpha: number,
+    noise01: number,
+): number;
+
 // ---------------------------------------------------------------------------
 //  Palette extraction
 // ---------------------------------------------------------------------------

package/src/index.js

@@ -20,6 +20,7 @@ export {
     flattenStopsToBuffer,
     sampleLut,
     packOklchSingle,
+    packOklchSingleDithered,
 } from './bake.js';
 export { MeshGradient, defaultMeshColor, monochromeMesh } from './mesh.js';
 export { formatCssLinear, formatCssRadial, formatCssConic } from './css-emitters.js';

package/src/mesh.js

@@ -19,7 +19,8 @@
  */
 
 import { lerpOklchTo } from '@zakkster/lite-color';
-import { packOklchSingle } from './bake.js';
+import { getBlueNoise64 } from '@zakkster/lite-color-engine';
+import { packOklchSingle, packOklchSingleDithered } from './bake.js';
 
 /** Normalize a hue angle to [0, 360). Handles negative and >=360 inputs. */
 function normHue(h) {
@@ -115,28 +116,63 @@ function resolveInterpMode(opts) {
  *
  * Pure function. Same input always returns the same output.
  *
- * @param {number} col   0..cols-1
- * @param {number} row   0..rows-1
- * @param {number} cols  >= 2
- * @param {number} rows  >= 2
+ * v1.2.0: the trailing `wrapX` and `wrapY` args are optional and default
+ * to `false`; when either is set, the corresponding axis's parameterization
+ * switches to a periodic form so a wrapped default mesh doesn't compress
+ * 120° of hue into the final cell. Callers passing four args as before
+ * get byte-identical output.
+ *
+ * @param {number}  col   0..cols-1
+ * @param {number}  row   0..rows-1
+ * @param {number}  cols  >= 2
+ * @param {number}  rows  >= 2
+ * @param {boolean} [wrapX=false]  v1.2.0 — when true, hue advances by
+ *   `360/cols` per column (uniform step everywhere including the seam,
+ *   no aperiodic compression at the wrap boundary).
+ * @param {boolean} [wrapY=false]  v1.2.0 — when true, the small row-driven
+ *   hue drift and the L gradient both take a sinusoidal (periodic) shape
+ *   so `row = 0` and `row = rows` land on the same color.
  * @returns {{l:number,c:number,h:number}} fresh OKLCH triplet
  */
-export function defaultMeshColor(col, row, cols, rows) {
-    const cT = cols === 1 ? 0.5 : col / (cols - 1);
-    const rT = rows === 1 ? 0.5 : row / (rows - 1);
-
-    // L: lighter at top, darker at bottom — gentle so colors stay vivid.
-    const l = 0.70 - 0.30 * rT;
-
-    // C: tent peak at (0.5, 0.5); edges keep some chroma so corners
-    // aren't flat gray. Range ≈ 0.15 (corners) to 0.25 (center).
-    const cDist = 1 - Math.abs(cT * 2 - 1);
-    const rDist = 1 - Math.abs(rT * 2 - 1);
+export function defaultMeshColor(col, row, cols, rows, wrapX = false, wrapY = false) {
+    // Column parameter — periodic when wrapping in x. On a wrapped axis
+    // the "cells" go 0..cols and cell (cols) is identified with cell 0, so
+    // `col / cols` (not `col / (cols - 1)`) is the right period step.
+    const cT = wrapX
+        ? col / cols
+        : (cols === 1 ? 0.5 : col / (cols - 1));
+    const rT = wrapY
+        ? row / rows
+        : (rows === 1 ? 0.5 : row / (rows - 1));
+
+    // L: lighter at top, darker at bottom. In wrapY mode the top and bottom
+    // must agree, so drive L with cos(2π·rT) instead of a linear ramp —
+    // rT = 0 and rT = 1 both give cos = 1, i.e. the same L.
+    const l = wrapY
+        ? 0.55 + 0.15 * Math.cos(2 * Math.PI * rT)
+        : 0.70 - 0.30 * rT;
+
+    // C: tent peak at the center. In wrapY mode the "distance from center"
+    // rDist has to be periodic; use `|sin(π·rT)|` which peaks at rT=0.5 and
+    // reaches 0 at rT=0 and rT=1 — same shape, seamless. Same for wrapX.
+    const cDist = wrapX
+        ? Math.abs(Math.sin(Math.PI * cT))
+        : 1 - Math.abs(cT * 2 - 1);
+    const rDist = wrapY
+        ? Math.abs(Math.sin(Math.PI * rT))
+        : 1 - Math.abs(rT * 2 - 1);
     const c = 0.15 + 0.10 * cDist * rDist;
 
-    // H: sweep across columns (deep blue → magenta → warm) + small
-    // diagonal drift by row. Wrap into [0, 360).
-    const h = normHue(240 + 120 * cT + 30 * rT);
+    // H: sweep across columns + small diagonal drift by row.
+    // - wrapX: uniform 360/cols step per column so cT = 0 and cT = 1 close
+    //   at the same hue (both are 0 mod 360). Base offset 240 preserves the
+    //   familiar "starts in blue" palette.
+    // - wrapY: the row drift becomes periodic via sin(2π·rT) so top and
+    //   bottom rows share the drift value 0. Amplitude kept at 30° to
+    //   match the linear-mode magnitude.
+    const hueSweep = wrapX ? 360 * cT : 120 * cT;
+    const hueDrift = wrapY ? 30 * Math.sin(2 * Math.PI * rT) : 30 * rT;
+    const h = normHue(240 + hueSweep + hueDrift);
 
     return { l, c, h };
 }
@@ -147,10 +183,26 @@ export class MeshGradient {
      * @param {number} rows  Number of rows (>= 2).
      * @param {Array<{l:number,c:number,h:number}>} [stops]
      *   Optional row-major array of cols*rows control points. If omitted,
-     *   a sensible default mesh is generated (currently only supported
-     *   for cols=rows=3; other sizes get a tiled clone of DEFAULT_3x3).
+     *   a sensible default mesh is generated by `defaultMeshColor`.
+     * @param {object} [opts]
+     * @param {boolean} [opts.wrapX=false]  v1.2.0 — treat the X axis as
+     *   cyclic. Structural: changes the UV period (`u = 1` wraps to `u = 0`),
+     *   the cell count (`cols` cells instead of `cols - 1`), and the default
+     *   control-point positions (`col / cols`). `sampleAt` wraps the u
+     *   coordinate via `u = u - Math.floor(u)`. Cubic mode reads real
+     *   neighbours across the seam via modulo indexing → C¹ continuity at
+     *   `u = 0`. `rasterizeTo` samples the period, not the closed interval.
+     *   `rasterizeDeformedTo` throws `WRAP_DEFORMED_UNSUPPORTED` — deformed
+     *   + wrap needs ghost quads that cross the seam, deferred to v1.3.
+     *   `cols` must be `>= 2` for any mesh, wrapped or not (the outer
+     *   integer-check on the constructor rejects `cols < 2` before wrap
+     *   is inspected). Degenerate `cols = 2` wrapped IS legal — cubic
+     *   neighbour indices alternate `(a, b, a, b)` and the Catmull-Rom
+     *   basis handles it as a low-amplitude oscillation.
+     * @param {boolean} [opts.wrapY=false]  v1.2.0 — same for the Y axis.
+     *   Independent of `wrapX` (torus = both, cylinder = one).
      */
-    constructor(cols, rows, stops) {
+    constructor(cols, rows, stops, opts) {
         if (!Number.isInteger(cols) || cols < 2) {
             throw new Error('MeshGradient: cols must be an integer >= 2');
         }
@@ -158,10 +210,33 @@ export class MeshGradient {
             throw new Error('MeshGradient: rows must be an integer >= 2');
         }
 
+        // v1.2.0 wrap opts. Both default false; when either flag is off the
+        // resulting object walks the same code paths as v1.1.0 (byte-parity
+        // is a hard exit-gate for T2).
+        //
+        // The roadmap's `WRAP_AXIS_TOO_SMALL` guard (cols=1 under modulo
+        // collapses every cubic neighbour index to 0, silently breaking the
+        // basis) is already covered by the outer `cols/rows < 2` guards
+        // above — cols=1 can never construct a MeshGradient at all, wrapped
+        // or not. `cols === 2` wrapped IS legal: neighbour indices alternate
+        // `(a, b, a, b)` and Catmull-Rom handles it as a low-amplitude
+        // oscillation.
+        const wrapX = opts != null && opts.wrapX === true;
+        const wrapY = opts != null && opts.wrapY === true;
+
         this.cols = cols;
         this.rows = rows;
+        this.wrapX = wrapX;
+        this.wrapY = wrapY;
         const total = cols * rows;
 
+        // Default-position denominators: on a wrapped axis there are `cols`
+        // cells (not `cols - 1`), so the natural spacing is `col / cols`.
+        // Non-wrapped axes keep the endpoint-inclusive `col / (cols - 1)`
+        // mapping.
+        const xDenom = wrapX ? cols : (cols - 1);
+        const yDenom = wrapY ? rows : (rows - 1);
+
         if (stops) {
             if (stops.length !== total) {
                 throw new Error(
@@ -183,21 +258,23 @@ export class MeshGradient {
                 this.stops[i] = {
                     l: s.l, c: s.c, h: s.h,
                     a: s.a === undefined ? 1 : s.a,
-                    x: s.x !== undefined ? s.x : col / (cols - 1),
-                    y: s.y !== undefined ? s.y : row / (rows - 1),
+                    x: s.x !== undefined ? s.x : col / xDenom,
+                    y: s.y !== undefined ? s.y : row / yDenom,
                 };
             }
         } else {
             // Procedural default: smooth aurora at any size, no tiling.
+            // Passes wrapX/wrapY through so the aperiodic hue sweep gets
+            // swapped for the periodic form on wrapped axes (D6 in T2).
             this.stops = new Array(total);
             for (let i = 0; i < total; i++) {
                 const col = i % cols;
                 const row = (i / cols) | 0;
-                const src = defaultMeshColor(col, row, cols, rows);
+                const src = defaultMeshColor(col, row, cols, rows, wrapX, wrapY);
                 this.stops[i] = {
                     l: src.l, c: src.c, h: src.h, a: 1,
-                    x: col / (cols - 1),
-                    y: row / (rows - 1),
+                    x: col / xDenom,
+                    y: row / yDenom,
                 };
             }
         }
@@ -320,24 +397,44 @@ export class MeshGradient {
             : modeOrSmooth;
         if (mode === 'cubic') return this._sampleAtCubic(u, v, out);
 
-        // Clamp to unit square.
-        if (u < 0) u = 0; else if (u > 1) u = 1;
-        if (v < 0) v = 0; else if (v > 1) v = 1;
-
         const cols = this.cols;
         const rows = this.rows;
         const stops = this.stops;
 
-        // Map to grid coords. Last cell index is (cols-2, rows-2) — the
-        // cell whose right/bottom edge is the mesh boundary.
-        const fu = u * (cols - 1);
-        const fv = v * (rows - 1);
-        let col = fu | 0;
-        let row = fv | 0;
-        let cu = fu - col;
-        let cv = fv - row;
-        if (col >= cols - 1) { col = cols - 2; cu = 1; }
-        if (row >= rows - 1) { row = rows - 2; cv = 1; }
+        // v1.2.0 axis handling — wrapped axes use period wrap
+        // `u - Math.floor(u)` instead of the unit-square clamp. Cell count
+        // becomes `cols` (not `cols - 1`) so `sampleAt(1, v)` maps to the
+        // same cell coordinate as `sampleAt(0, v)`. Non-wrapped axes keep
+        // v1.1.0 semantics byte-for-byte.
+        let fu, col, cu;
+        if (this.wrapX) {
+            const uw = u - Math.floor(u);
+            fu = uw * cols;
+            col = fu | 0;
+            cu = fu - col;
+            if (col >= cols) col = 0;   // safety net for uw ≈ 1.0 float rounding
+        } else {
+            if (u < 0) u = 0; else if (u > 1) u = 1;
+            fu = u * (cols - 1);
+            col = fu | 0;
+            cu = fu - col;
+            if (col >= cols - 1) { col = cols - 2; cu = 1; }
+        }
+
+        let fv, row, cv;
+        if (this.wrapY) {
+            const vw = v - Math.floor(v);
+            fv = vw * rows;
+            row = fv | 0;
+            cv = fv - row;
+            if (row >= rows) row = 0;
+        } else {
+            if (v < 0) v = 0; else if (v > 1) v = 1;
+            fv = v * (rows - 1);
+            row = fv | 0;
+            cv = fv - row;
+            if (row >= rows - 1) { row = rows - 2; cv = 1; }
+        }
 
         if (mode === 'smooth') {
             // smoothstep eases the (cu, cv) → blend mapping; corner colors
@@ -346,11 +443,15 @@ export class MeshGradient {
             cv = cv * cv * (3 - 2 * cv);
         }
 
-        const base = row * cols + col;
-        const c00 = stops[base];
-        const c10 = stops[base + 1];
-        const c01 = stops[base + cols];
-        const c11 = stops[base + cols + 1];
+        // Neighbour indices — modulo on wrapped axes so the last cell blends
+        // back to the first.
+        const colN = this.wrapX ? (col + 1) % cols : col + 1;
+        const rowN = this.wrapY ? (row + 1) % rows : row + 1;
+
+        const c00 = stops[row  * cols + col];
+        const c10 = stops[row  * cols + colN];
+        const c01 = stops[rowN * cols + col];
+        const c11 = stops[rowN * cols + colN];
 
         // Top edge then bottom edge into scratch, then v-lerp into out.
         // Normalize each intermediate hue so subsequent lerps see a value
@@ -381,35 +482,80 @@ export class MeshGradient {
      * clamped to valid ranges since Catmull-Rom can overshoot.
      */
     _sampleAtCubic(u, v, out) {
-        if (u < 0) u = 0; else if (u > 1) u = 1;
-        if (v < 0) v = 0; else if (v > 1) v = 1;
-
         const cols = this.cols;
         const rows = this.rows;
 
-        const fu = u * (cols - 1);
-        const fv = v * (rows - 1);
-        let col = fu | 0;
-        let row = fv | 0;
-        let cu = fu - col;
-        let cv = fv - row;
-        if (col >= cols - 1) { col = cols - 2; cu = 1; }
-        if (row >= rows - 1) { row = rows - 2; cv = 1; }
-
-        // 4×4 neighbour columns + rows, clamped to grid bounds. At a
-        // boundary patch the spline degrades toward bilinear (duplicate
-        // endpoints give a flat tangent there), which is the right
-        // behaviour — there's no extrapolation data to inform a
-        // sharper curve outside the grid.
-        const im1 = col - 1 < 0 ? 0 : col - 1;
-        const i0  = col;
-        const i1  = col + 1;
-        const i2  = col + 2 >= cols ? cols - 1 : col + 2;
-
-        const jm1 = row - 1 < 0 ? 0 : row - 1;
-        const j0  = row;
-        const j1  = row + 1;
-        const j2  = row + 2 >= rows ? rows - 1 : row + 2;
+        // Wrapped-axis handling — same shape as `sampleAt`: period-wrap
+        // the coord and use `cols` cells instead of `cols - 1`.
+        let fu, col, cu;
+        if (this.wrapX) {
+            const uw = u - Math.floor(u);
+            fu = uw * cols;
+            col = fu | 0;
+            cu = fu - col;
+            if (col >= cols) col = 0;
+        } else {
+            if (u < 0) u = 0; else if (u > 1) u = 1;
+            fu = u * (cols - 1);
+            col = fu | 0;
+            cu = fu - col;
+            if (col >= cols - 1) { col = cols - 2; cu = 1; }
+        }
+
+        let fv, row, cv;
+        if (this.wrapY) {
+            const vw = v - Math.floor(v);
+            fv = vw * rows;
+            row = fv | 0;
+            cv = fv - row;
+            if (row >= rows) row = 0;
+        } else {
+            if (v < 0) v = 0; else if (v > 1) v = 1;
+            fv = v * (rows - 1);
+            row = fv | 0;
+            cv = fv - row;
+            if (row >= rows - 1) { row = rows - 2; cv = 1; }
+        }
+
+        // 4×4 neighbour columns + rows. This is D3 — the flagship. On a
+        // wrapped axis, the (col - 1) and (col + 2) neighbours read real
+        // cells across the seam via modulo instead of clamping to a
+        // duplicated endpoint. That is what gives C¹ continuity at the
+        // tile boundary — bilinear and smooth get seamlessness from the
+        // wrap coord alone, but cubic needs its input samples to actually
+        // exist across the seam. Non-wrapped axes keep the v1.1.0 clamp
+        // behaviour byte-for-byte.
+        //
+        // Modulo formula: `((x % n) + n) % n` is the classic safe form for
+        // possibly-negative dividends. On wrapped axes `col` is already in
+        // `[0, cols)` from the cell-index arithmetic above, so `col - 1`
+        // can be -1 (needs the +n rescue) and `col + 2` can be `cols` or
+        // `cols + 1` (harmless — the second `% n` normalizes them).
+        let im1, i0, i1, i2;
+        if (this.wrapX) {
+            im1 = ((col - 1) % cols + cols) % cols;
+            i0  = col;
+            i1  = (col + 1) % cols;
+            i2  = (col + 2) % cols;
+        } else {
+            im1 = col - 1 < 0 ? 0 : col - 1;
+            i0  = col;
+            i1  = col + 1;
+            i2  = col + 2 >= cols ? cols - 1 : col + 2;
+        }
+
+        let jm1, j0, j1, j2;
+        if (this.wrapY) {
+            jm1 = ((row - 1) % rows + rows) % rows;
+            j0  = row;
+            j1  = (row + 1) % rows;
+            j2  = (row + 2) % rows;
+        } else {
+            jm1 = row - 1 < 0 ? 0 : row - 1;
+            j0  = row;
+            j1  = row + 1;
+            j2  = row + 2 >= rows ? rows - 1 : row + 2;
+        }
 
         // Step 1: blend each of the 4 rows along x at parameter cu.
         this._cubicRow(jm1, im1, i0, i1, i2, cu, this._scratchCubicRows[0]);
@@ -471,8 +617,47 @@ export class MeshGradient {
         }
         const mode = resolveInterpMode(opts);
         const tmp = { l: 0, c: 0, h: 0, a: 1 };
-        const wInv = 1 / (width  - 1);
-        const hInv = 1 / (height - 1);
+        // v1.2.0 — D4: on a wrapped axis, sample the period (`x / width`),
+        // NOT the closed interval (`x / (width - 1)`). Pixel column 0 of
+        // the "next tile" would land at `u = 1 ≡ 0` — no duplicated edge
+        // column, so `drawImage`-based tiling of the rasterized output
+        // butts perfectly. Non-wrapped axes keep v1.1.0 semantics.
+        const wInv = this.wrapX ? 1 / width  : 1 / (width  - 1);
+        const hInv = this.wrapY ? 1 / height : 1 / (height - 1);
+
+        // v1.2.0 — D8: dither branch resolved ONCE per call, two loop
+        // bodies. `dither: false` (or absent) walks the exact same code
+        // as v1.2.0 — the byte-parity guarantee for undithered output
+        // is the whole reason the branch is out here and not per-pixel.
+        //
+        // Dither mechanics (contract owned by lite-color-engine v1.5, F1):
+        //   - Blue-noise tile is 64×64 bytes (0..255), shared reference.
+        //   - Per pixel: `noiseByte = tile[((y & 63) << 6) | (x & 63)]`
+        //     — pure bit ops (torus wrap via mask, row stride via shift).
+        //   - `noise01 = (noiseByte + 0.5) / 256` centers the perturbation
+        //     around 0.5 so it matches the plain packer's rounding offset.
+        //     Consequence: uniform 128 fills would still round identically;
+        //     the actual dither effect surfaces on smooth ramps where the
+        //     encoded byte lands near an integer boundary.
+        //   - Same `noise01` reused for R/G/B at the pixel — luminance-
+        //     patterned dither, no chroma speckle.
+        const dither = opts != null && opts.dither === true;
+        if (dither) {
+            const tile = getBlueNoise64();       // shared Uint8Array(4096)
+            const INV_256 = 1 / 256;
+            let i = 0;
+            for (let y = 0; y < height; y++) {
+                const v = y * hInv;
+                const rowBase = (y & 63) << 6;
+                for (let x = 0; x < width; x++) {
+                    const u = x * wInv;
+                    this.sampleAt(u, v, tmp, mode);
+                    const noise01 = (tile[rowBase | (x & 63)] + 0.5) * INV_256;
+                    out[i++] = packOklchSingleDithered(tmp.l, tmp.c, tmp.h, tmp.a, noise01);
+                }
+            }
+            return out;
+        }
         let i = 0;
         for (let y = 0; y < height; y++) {
             const v = y * hInv;
@@ -521,6 +706,21 @@ export class MeshGradient {
         if (!(out instanceof Uint32Array) || out.length < width * height) {
             throw new Error('MeshGradient.rasterizeDeformedTo: out must be a Uint32Array with length >= width*height');
         }
+        // v1.2.0 — D5: deformed + wrap is a real feature (ghost quads
+        // crossing the seam, Newton solve against wrapped corner positions),
+        // deferred to v1.3. Silent seamed output is worse than no output —
+        // fail loudly with a code consumers can branch on cleanly instead
+        // of string-matching. The `WRAP_AXIS_TOO_SMALL` guard in the
+        // constructor carries the same `err.code` pattern.
+        if (this.wrapX || this.wrapY) {
+            const err = new Error(
+                'MeshGradient.rasterizeDeformedTo: deformed rasterization on a ' +
+                'wrapped mesh is not supported in v1.2 (planned for v1.3). ' +
+                'Use rasterizeTo (regular grid) for wrapped meshes.'
+            );
+            err.code = 'WRAP_DEFORMED_UNSUPPORTED';
+            throw err;
+        }
         const mode   = resolveInterpMode(opts);
         const smooth = mode === 'smooth';
         const cubic  = mode === 'cubic';