@zakkster/lite-gradient-studio 1.0.1 → 1.2.0

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/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

@@ -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,
@@ -143,6 +210,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
 // ---------------------------------------------------------------------------
@@ -274,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,8 +20,9 @@ export {
     flattenStopsToBuffer,
     sampleLut,
     packOklchSingle,
+    packOklchSingleDithered,
 } 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 {