@zakkster/lite-gradient-studio 1.0.1 → 1.2.0

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';
@@ -678,3 +878,136 @@ export class MeshGradient {
         this._scratchBot = null;
     }
 }
+
+// ---- Monochrome mesh (v1.1.0) --------------------------------------------
+
+/**
+ * Build a monochromatic MeshGradient from a single base OKLCH color.
+ *
+ * Chroma and hue are held constant across every control point in the mesh;
+ * only lightness varies according to `direction`. This is the mesh-level
+ * analogue to lite-gradient's `monochromeGradient(base, opts)` — a
+ * client-work-friendly mesh that never looks like an "AI-generated random
+ * gradient" because the palette is fixed to a single brand tone.
+ *
+ * Typical use: subtle premium backgrounds for cards, hero sections,
+ * editorial layouts. The mesh structure means users can post-hoc
+ * `setPointPosition(...)` control points off-grid to warp the L
+ * distribution — impossible with a flat 1D gradient.
+ *
+ * @param {{ l: number, c: number, h: number }} base
+ *   OKLCH base color. `c` and `h` are held constant across the mesh
+ *   (or c=0 if `mode: 'grayscale'`).
+ * @param {number} cols  Number of columns (integer >= 2).
+ * @param {number} rows  Number of rows (integer >= 2).
+ * @param {Object} [opts]
+ * @param {'tinted' | 'grayscale'} [opts.mode='tinted']
+ * @param {[number, number]} [opts.range=[0, 1]]
+ *   L-axis endpoints. Must satisfy `0 <= lo < hi <= 1`.
+ * @param {'horizontal' | 'vertical' | 'diagonal' | 'radial'} [opts.direction='diagonal']
+ *   How L varies across the mesh:
+ *   - `'horizontal'`: L varies left-to-right, uniform across each row.
+ *   - `'vertical'`: L varies top-to-bottom, uniform across each column.
+ *   - `'diagonal'`: L varies from top-left (lo) to bottom-right (hi).
+ *   - `'radial'`: L is `lo` at center, `hi` at corners.
+ * @returns {MeshGradient}
+ *
+ * @throws {TypeError}  On invalid `base`, `mode`, `direction`, or `range` shape.
+ * @throws {RangeError} On invalid `range` values or `cols`/`rows` < 2.
+ *
+ * @example
+ * // Subtle premium background for a brand card
+ * const mesh = monochromeMesh({ l: 0.5, c: 0.06, h: 245 }, 3, 3);
+ * 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);
+ */
+export function monochromeMesh(base, cols, rows, opts) {
+    if (base == null || typeof base !== 'object' ||
+        typeof base.l !== 'number' || typeof base.c !== 'number' ||
+        typeof base.h !== 'number') {
+        throw new TypeError(
+            'monochromeMesh: base must be { l, c, h } with numeric fields'
+        );
+    }
+    if (!Number.isInteger(cols) || cols < 2) {
+        throw new RangeError(
+            'monochromeMesh: cols must be an integer >= 2, got ' + cols
+        );
+    }
+    if (!Number.isInteger(rows) || rows < 2) {
+        throw new RangeError(
+            'monochromeMesh: rows must be an integer >= 2, got ' + rows
+        );
+    }
+
+    const o = opts || {};
+    const mode = o.mode == null ? 'tinted' : o.mode;
+    const range = o.range == null ? [0, 1] : o.range;
+    const direction = o.direction == null ? 'diagonal' : o.direction;
+
+    if (mode !== 'tinted' && mode !== 'grayscale') {
+        throw new TypeError(
+            'monochromeMesh: mode must be "tinted" or "grayscale", got ' + mode
+        );
+    }
+    if (!Array.isArray(range) || range.length !== 2) {
+        throw new TypeError(
+            'monochromeMesh: range must be a two-element [lo, hi] array'
+        );
+    }
+    const lo = range[0];
+    const hi = range[1];
+    if (typeof lo !== 'number' || typeof hi !== 'number' ||
+        !(lo >= 0 && hi <= 1 && lo < hi)) {
+        throw new RangeError(
+            'monochromeMesh: range must satisfy 0 <= lo < hi <= 1, got [' +
+            lo + ', ' + hi + ']'
+        );
+    }
+    if (direction !== 'horizontal' && direction !== 'vertical' &&
+        direction !== 'diagonal' && direction !== 'radial') {
+        throw new TypeError(
+            'monochromeMesh: direction must be "horizontal", "vertical", ' +
+            '"diagonal", or "radial", got ' + direction
+        );
+    }
+
+    const c = mode === 'grayscale' ? 0 : base.c;
+    const h = base.h;
+    const span = hi - lo;
+    const cx = (cols - 1) / 2;
+    const cy = (rows - 1) / 2;
+    // Half-diagonal from center to a corner, used to normalize radial t.
+    const maxRadial = Math.sqrt(cx * cx + cy * cy);
+    // Diagonal length in grid units (top-left to bottom-right corner),
+    // used to normalize diagonal t.
+    const diagDenom = (cols - 1) + (rows - 1);
+
+    const total = cols * rows;
+    const stops = new Array(total);
+
+    for (let i = 0; i < total; i++) {
+        const col = i % cols;
+        const row = (i / cols) | 0;
+
+        let t;
+        if (direction === 'horizontal') {
+            t = cols === 1 ? 0 : col / (cols - 1);
+        } else if (direction === 'vertical') {
+            t = rows === 1 ? 0 : row / (rows - 1);
+        } else if (direction === 'diagonal') {
+            t = diagDenom === 0 ? 0 : (col + row) / diagDenom;
+        } else {
+            // radial: 0 at center, 1 at corners
+            const dx = col - cx;
+            const dy = row - cy;
+            t = maxRadial === 0 ? 0 : Math.sqrt(dx * dx + dy * dy) / maxRadial;
+        }
+
+        stops[i] = { l: lo + span * t, c, h };
+    }
+
+    return new MeshGradient(cols, rows, stops);
+}