@zakkster/lite-gradient-studio 1.0.1 → 1.1.0

package/CHANGELOG.md

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

package/README.md

@@ -1,8 +1,14 @@
 # @zakkster/lite-gradient-studio
 
+> Authoring engine for OKLCH gradients -- linear, radial, conic, and N×M mesh -- with zero-GC rasterization, multi-format export, and chroma-weighted palette extraction.
+
 [![npm version](https://img.shields.io/npm/v/@zakkster/lite-gradient-studio.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-gradient-studio)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Engine-00C853?style=for-the-badge&logo=leaf&logoColor=white)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-gradient-studio?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-gradient-studio)
 [![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-gradient-studio?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-gradient-studio)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-gradient-studio?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-gradient-studio)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
 
 Authoring engine for OKLCH gradients — linear, radial, conic, and N×M mesh — with zero-GC rasterization, multi-format export, and chroma-weighted palette extraction.
@@ -183,6 +189,47 @@ Each box is one module under `src/` with one test file under `test/`. Modules co
 - `'smooth'` — bilinear with smoothstep-eased u/v. Softens cell-border artifacts.
 - `'cubic'` — Catmull-Rom across cell boundaries. Smoothest; ~2.5× the cost of `'bilinear'`.
 
+### Monochrome mesh (v1.1.0)
+
+Mesh-level analogue of `lite-gradient`'s `monochromeGradient` — chroma and hue held
+constant across every control point; only lightness varies. Client-work-friendly:
+subtle premium backgrounds without the "AI-generated random gradient" look.
+
+```js
+import { monochromeMesh } from '@zakkster/lite-gradient-studio';
+
+// 3×3 mesh, all points share the brand hue, L varies diagonally
+const mesh = monochromeMesh({ l: 0.5, c: 0.06, h: 245 }, 3, 3);
+
+// Rasterize to a canvas
+const buf = new Uint32Array(800 * 600);
+mesh.rasterizeTo(buf, 800, 600);
+const img = new ImageData(new Uint8ClampedArray(buf.buffer), 800, 600);
+ctx.putImageData(img, 0, 0);
+
+// Or emit CSS (canvas-free rendering)
+const css = formatCssMesh(mesh);
+element.style.background = css;
+```
+
+**`monochromeMesh(base, cols, rows, opts?)`** → `MeshGradient`
+
+| Option      | Type                                                          | Default        | Notes                                                                       |
+|-------------|---------------------------------------------------------------|----------------|-----------------------------------------------------------------------------|
+| `mode`      | `'tinted' \| 'grayscale'`                                     | `'tinted'`     | `'tinted'` retains base c/h; `'grayscale'` forces c=0.                      |
+| `range`     | `[number, number]`                                            | `[0, 1]`       | L-axis endpoints. Must satisfy `0 ≤ lo < hi ≤ 1`.                           |
+| `direction` | `'horizontal' \| 'vertical' \| 'diagonal' \| 'radial'`        | `'diagonal'`   | How L varies across the mesh. See below.                                    |
+
+**Directions:**
+- **`'horizontal'`** — L varies left-to-right, uniform across each row. Like a linear gradient, but you can deform post-hoc.
+- **`'vertical'`** — L varies top-to-bottom, uniform across each column.
+- **`'diagonal'`** (default) — top-left corner (lo) to bottom-right corner (hi). Most versatile; uses both axes meaningfully.
+- **`'radial'`** — center (lo) outward to corners (hi). Atmospheric "premium" feel.
+
+Post-construction, you can `setPointPosition(...)` to warp the L distribution off-grid
+— something you can't do with a flat 1D gradient. This is what mesh capability buys you
+in the client-work scenario: brand-safe base + designer-controlled organic character.
+
 ### CSS emitters
 
 | Function | Description |

package/llms.txt

@@ -72,6 +72,47 @@ Mesh interpolation modes (sampleAt's `mode` arg / rasterize's
 Legacy boolean accepted for sampleAt: `false` → bilinear, `true` → smooth.
 Rasterize also accepts `opts.smooth: true` as a legacy alias.
 
+## Monochrome mesh (v1.1.0)
+
+Factory for meshes where every control point shares base c/h (or c=0 for
+grayscale) and only L varies across the grid. Client-work-friendly:
+never looks like an "AI-generated random gradient" because the palette
+is fixed to one brand tone.
+
+    import { monochromeMesh, formatCssMesh } from '@zakkster/lite-gradient-studio';
+
+    // Brand-tinted mesh, L varies diagonally
+    const m = monochromeMesh({ l: 0.5, c: 0.06, h: 245 }, 3, 3);
+
+    // Or explicit direction + grayscale + printable-safe range
+    const gm = monochromeMesh(
+        { l: 0.5, c: 0, h: 0 },
+        4, 4,
+        { mode: 'grayscale', range: [0.05, 0.95], direction: 'radial' }
+    );
+
+    // Emit CSS without canvas
+    element.style.background = formatCssMesh(m);
+
+Options:
+- mode:       'tinted' (default) | 'grayscale'
+- range:      [lo, hi] with 0 <= lo < hi <= 1 (default [0, 1])
+- direction:  'horizontal' | 'vertical' | 'diagonal' (default) | 'radial'
+
+Directions:
+- horizontal:  L varies left-to-right, uniform per row
+- vertical:    L varies top-to-bottom, uniform per column
+- diagonal:    top-left corner (lo) to bottom-right corner (hi)
+- radial:      center (lo) outward to corners (hi)
+
+Returns a MeshGradient. All post-construction methods (setPointPosition,
+setPoint, sampleAt, rasterizeTo, etc.) work as normal — the factory just
+initializes the color basis. Deform handles off-grid to warp L across
+the surface without disturbing the brand palette.
+
+Pairs with @zakkster/lite-gradient's monochromeGradient(base, opts) which
+returns a continuous 1D Gradient; monochromeMesh returns a 2D MeshGradient.
+
 ## Multi-format export
 
     const state = { mode: 'linear', angle: 135, stops };

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@zakkster/lite-gradient-studio",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Authoring engine for OKLCH gradients — linear, radial, conic, and N×M mesh — with zero-GC rasterization, multi-format export (CSS/SCSS/Tailwind/JSON/SVG), and chroma-weighted palette extraction.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
   "type": "module",
-  "main": "src/index.js",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "node": "./src/index.js",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
   },
   "files": [
     "src",
@@ -17,13 +24,13 @@
     "README.md"
   ],
   "scripts": {
-    "test":  "node --test --expose-gc test/*.test.js",
+    "test": "node --test --expose-gc test/*.test.js",
     "bench": "node --expose-gc bench/run.mjs"
   },
   "dependencies": {
-    "@zakkster/lite-color":        "^1.0.6",
+    "@zakkster/lite-color": "^1.0.6",
     "@zakkster/lite-color-engine": "^1.0.0",
-    "@zakkster/lite-gradient":     "^1.0.4"
+    "@zakkster/lite-gradient": "^1.1.0"
   },
   "keywords": [
     "gradient",
@@ -42,12 +49,17 @@
     "no-build",
     "esm"
   ],
-  "homepage":   "https://github.com/PeshoVurtoleta/lite-gradient-studio#readme",
+  "homepage": "https://github.com/PeshoVurtoleta/lite-gradient-studio#readme",
   "repository": {
     "type": "git",
-    "url":  "git+https://github.com/PeshoVurtoleta/lite-gradient-studio.git"
+    "url": "git+https://github.com/PeshoVurtoleta/lite-gradient-studio.git"
   },
   "bugs": {
     "url": "https://github.com/PeshoVurtoleta/lite-gradient-studio/issues"
-  }
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "sideEffects": false
 }

package/src/color-convert.js

@@ -13,9 +13,13 @@
 
 /**
  * OKLCH → linear sRGB triplet, with sRGB-gamut mapping by chroma reduction.
- * Output: [r, g, b] each in [0, 1].
+ * Output: `[r, g, b]` each in `[0, 1]`.
+ *
+ * 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) {
+export function oklchToLinearSrgb(L, C, H, out) {
     const hRad = H * Math.PI / 180;
     const cosH = Math.cos(hRad);
     const sinH = Math.sin(hRad);
@@ -38,6 +42,7 @@ export function oklchToLinearSrgb(L, C, H) {
     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];
     }
 
@@ -49,6 +54,7 @@ export function oklchToLinearSrgb(L, C, H) {
         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];
     }
 
@@ -64,6 +70,7 @@ export function oklchToLinearSrgb(L, C, H) {
             hi = midC;
         }
     }
+    if (out) { out[0] = fitR; out[1] = fitG; out[2] = fitB; return out; }
     return [fitR, fitG, fitB];
 }
 
@@ -111,7 +118,14 @@ function clampByte(v) {
 /**
  * Linear sRGB → OKLCH. Used by fromHex and the palette extractor.
  */
-export function linearSrgbToOklch(r, g, b) {
+/**
+ * Linear sRGB → OKLCH. Inverse of `oklchToLinearSrgb`.
+ *
+ * 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) {
     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;
@@ -124,6 +138,7 @@ export function linearSrgbToOklch(r, g, b) {
     const C = Math.sqrt(a * a + bb * bb);
     let H = Math.atan2(bb, a) * 180 / Math.PI;
     if (H < 0) H += 360;
+    if (out) { out.l = L; out.c = C; out.h = H; return out; }
     return { l: L, c: C, h: H };
 }
 

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

@@ -678,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);
+}