@zakkster/lite-gradient-studio 1.0.0 → 1.1.0

package/src/color-convert.js

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

package/src/exporters.js

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

package/src/index.d.ts

@@ -143,6 +143,45 @@ export class MeshGradient {
     destroy(): void;
 }
 
+// ---------------------------------------------------------------------------
+//  Monochrome mesh (v1.1.0)
+// ---------------------------------------------------------------------------
+
+export type MonoMode = 'tinted' | 'grayscale';
+export type MonoMeshDirection = 'horizontal' | 'vertical' | 'diagonal' | 'radial';
+
+export interface MonochromeMeshOptions {
+    /**
+     * Chroma handling.
+     * - `'tinted'` (default): retain base color's chroma/hue at every point.
+     * - `'grayscale'`: force chroma to 0 for pure achromatic tones.
+     */
+    mode?: MonoMode;
+    /** L-axis endpoints [lo, hi], must satisfy `0 <= lo < hi <= 1`. Default `[0, 1]`. */
+    range?: readonly [number, number];
+    /**
+     * How L varies across the mesh:
+     * - `'horizontal'`: left-to-right, uniform per row.
+     * - `'vertical'`: top-to-bottom, uniform per column.
+     * - `'diagonal'` (default): top-left corner (lo) to bottom-right corner (hi).
+     * - `'radial'`: center (lo) outward to corners (hi).
+     */
+    direction?: MonoMeshDirection;
+}
+
+/**
+ * Build a monochromatic MeshGradient from a single base OKLCH color.
+ * Chroma and hue are held constant across every control point; only
+ * lightness varies according to `direction`. Client-work-friendly:
+ * never looks "AI-generated" because the palette is fixed to one brand tone.
+ */
+export function monochromeMesh(
+    base: OklchColor,
+    cols: number,
+    rows: number,
+    opts?: MonochromeMeshOptions
+): MeshGradient;
+
 // ---------------------------------------------------------------------------
 //  CSS emitters
 // ---------------------------------------------------------------------------

package/src/index.js

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

package/src/mesh.js

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