@zakkster/lite-gradient-studio 1.0.0

package/src/index.d.ts

@@ -0,0 +1,380 @@
+// @zakkster/lite-gradient-studio v1.0.0 -- type definitions.
+//
+// (c) Zahary Shinikchiev. MIT licensed.
+
+// ---------------------------------------------------------------------------
+//  Re-exports from @zakkster/lite-gradient
+// ---------------------------------------------------------------------------
+
+export { Gradient } from '@zakkster/lite-gradient';
+export type {
+    GradientStop,
+    GradientConstructorStop,
+    GradientOptions,
+} from '@zakkster/lite-gradient';
+
+// ---------------------------------------------------------------------------
+//  Common color shapes
+// ---------------------------------------------------------------------------
+
+/** Plain OKLCH color object. Alpha is optional and defaults to 1. */
+export interface OklchColor {
+    l: number;
+    c: number;
+    h: number;
+    a?: number;
+}
+
+/** OKLCH color with alpha always present (after construction-time defaulting). */
+export interface OklchColorA {
+    l: number;
+    c: number;
+    h: number;
+    a: number;
+}
+
+/** Mesh stop with optional deformed-grid position. */
+export interface MeshStop extends OklchColor {
+    x?: number;
+    y?: number;
+}
+
+/** Mesh stop fully populated (post-construction): always has x, y, a. */
+export interface MeshStopFull {
+    l: number;
+    c: number;
+    h: number;
+    a: number;
+    x: number;
+    y: number;
+}
+
+/** 2D position out-parameter shape. */
+export interface XYOut {
+    x: number;
+    y: number;
+}
+
+// ---------------------------------------------------------------------------
+//  MeshGradient
+// ---------------------------------------------------------------------------
+
+export type InterpolationMode = 'bilinear' | 'smooth' | 'cubic';
+
+export interface MeshRasterizeOptions {
+    /** Default 'bilinear'. */
+    interpolation?: InterpolationMode;
+    /** Legacy boolean: `true` is equivalent to `interpolation: 'smooth'`. */
+    smooth?: boolean;
+}
+
+/**
+ * Procedural default color for a control point at (col, row) of a cols x rows
+ * 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.
+ */
+export function defaultMeshColor(
+    col: number,
+    row: number,
+    cols: number,
+    rows: number,
+): OklchColor;
+
+export class MeshGradient {
+    constructor(cols: number, rows: number, stops?: ReadonlyArray<MeshStop>);
+
+    readonly cols: number;
+    readonly rows: number;
+    readonly stops: MeshStopFull[];
+
+    /** Read the (col, row) color into a caller-owned out. Zero-GC. */
+    getPoint<T extends Partial<OklchColor>>(col: number, row: number, out: T): T;
+    /** Mutate the (col, row) color in place. */
+    setPoint(col: number, row: number, l: number, c: number, h: number): void;
+
+    /** Set the (x, y) deformed-grid position of a control point. */
+    setPointPosition(col: number, row: number, x: number, y: number): void;
+    /** Read the (x, y) position into a caller-owned `{ x, y }` out. Zero-GC. */
+    getPointPosition<T extends XYOut>(col: number, row: number, out: T): T;
+    /** Restore all control-point positions to the regular grid. */
+    resetPositions(): void;
+
+    /**
+     * Sample at parametric (u, v) in [0, 1]^2 into `out`. Zero-GC.
+     *
+     * `modeOrSmooth`:
+     *   - false / undefined -> 'bilinear'
+     *   - true              -> 'smooth' (smoothstep)
+     *   - 'cubic'           -> Catmull-Rom 2D
+     *   - any of the strings above explicitly
+     */
+    sampleAt<T extends Partial<OklchColorA>>(
+        u: number,
+        v: number,
+        out: T,
+        modeOrSmooth?: boolean | InterpolationMode,
+    ): T;
+
+    /**
+     * Rasterize on the REGULAR grid into a packed-RGBA Uint32Array (little-
+     * endian byte order; aliasable as Uint8ClampedArray for ImageData).
+     */
+    rasterizeTo(
+        out: Uint32Array,
+        width: number,
+        height: number,
+        opts?: MeshRasterizeOptions,
+    ): Uint32Array;
+
+    /**
+     * 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.
+     */
+    rasterizeDeformedTo(
+        out: Uint32Array,
+        width: number,
+        height: number,
+        opts?: MeshRasterizeOptions,
+    ): Uint32Array;
+
+    /** Release internal references for GC. */
+    destroy(): void;
+}
+
+// ---------------------------------------------------------------------------
+//  CSS emitters
+// ---------------------------------------------------------------------------
+
+/** Gradient shape accepted by the CSS emitters (a `stops` array of OKLCH+pos). */
+export interface GradientLike {
+    stops: ReadonlyArray<OklchColor & { pos: number }>;
+}
+
+export interface FormatCssLinearOptions {
+    /** Default 90 (left -> right). */
+    angle?: number;
+    /** Default true. Emits `in oklch` so browsers interpolate perceptually. */
+    oklchInterp?: boolean;
+}
+
+export interface FormatCssRadialOptions {
+    /** Default 'circle'. */
+    shape?: 'circle' | 'ellipse';
+    /** Default 'farthest-corner'. */
+    size?: string;
+    /** Default 'center'. Accepts CSS position syntax. */
+    position?: string;
+    /** Default true. */
+    oklchInterp?: boolean;
+}
+
+export interface FormatCssConicOptions {
+    /** Default 0. Starting angle in degrees. */
+    from?: number;
+    /** Default 'center'. */
+    position?: string;
+    /** Default true. */
+    oklchInterp?: boolean;
+}
+
+export function formatCssLinear(gradient: GradientLike, opts?: FormatCssLinearOptions): string;
+export function formatCssRadial(gradient: GradientLike, opts?: FormatCssRadialOptions): string;
+export function formatCssConic(gradient: GradientLike, opts?: FormatCssConicOptions): string;
+
+// ---------------------------------------------------------------------------
+//  Mesh CSS approximation
+// ---------------------------------------------------------------------------
+
+export interface FormatCssMeshOptions {
+    /** Layer radius as % of farthest corner. Auto-sized by mesh dims if absent. */
+    radiusPct?: number;
+    /** Default 'circle'. */
+    shape?: 'circle' | 'ellipse';
+    /** Default true. */
+    oklchInterp?: boolean;
+    /** Default true. Append an average-color base layer to fill gaps. */
+    includeBase?: boolean;
+}
+
+export function formatCssMesh(mesh: MeshGradient, opts?: FormatCssMeshOptions): string;
+
+// ---------------------------------------------------------------------------
+//  Color conversion
+// ---------------------------------------------------------------------------
+
+/**
+ * OKLCH -> linear sRGB triplet. sRGB-gamut-mapped via 10-iteration binary
+ * search on chroma when the requested color is out of gamut.
+ *
+ * @param out Optional 3-element `[r, g, b]` array. If supplied, written in
+ *            place and returned (zero allocation). Otherwise a fresh array
+ *            is allocated.
+ */
+export function oklchToLinearSrgb(
+    L: number,
+    C: number,
+    H: number,
+    out?: number[],
+): number[];
+
+/**
+ * Linear sRGB -> OKLCH.
+ * @param out Optional `{l, c, h}` object. If supplied, written in place and
+ *            returned (zero allocation). The `a` field is left untouched.
+ */
+export function linearSrgbToOklch<T extends Partial<OklchColor>>(
+    r: number,
+    g: number,
+    b: number,
+    out?: T,
+): T;
+
+/** sRGB transfer (linear -> gamma-encoded). IEC 61966-2-1. */
+export function srgbGamma(x: number): number;
+/** sRGB inverse transfer (gamma-encoded -> linear). */
+export function srgbInverseGamma(x: number): number;
+
+/**
+ * OKLCH -> hex. Emits '#rrggbb' for opaque colors and '#rrggbbaa' otherwise.
+ * Output always lowercase.
+ */
+export function toHex(color: OklchColor): string;
+
+/**
+ * Hex -> OKLCH. Accepts 3, 4, 6, or 8-char hex; '#' optional; case-insensitive.
+ * @throws on malformed input.
+ */
+export function fromHex(hex: string): OklchColorA;
+
+// ---------------------------------------------------------------------------
+//  Bake / pixel helpers
+// ---------------------------------------------------------------------------
+
+/** Flatten `gradient.stops` into a Float32Array of [L, C, H, L, C, H, ...]. */
+export function flattenStopsToBuffer(
+    gradient: { stops: ReadonlyArray<OklchColor> },
+    out?: Float32Array,
+): Float32Array;
+
+/** Bake a Gradient into a fixed-resolution Uint32Array LUT of packed RGBA. */
+export function bakeGradientToLut(
+    gradient: { stops: ReadonlyArray<OklchColor & { pos: number }>; sampleArray(out: Float32Array, n: number): void },
+    resolution?: number,
+    opts?: {
+        easeFn?: (t: number) => number;
+        packer?: Function;
+    },
+): Uint32Array;
+
+/** Sample a single packed color from a baked LUT at parametric t in [0, 1]. */
+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;
+
+// ---------------------------------------------------------------------------
+//  Palette extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract a designer-friendly palette from raw RGBA pixels. Chroma-weighted
+ * hue-bucketing with >= 50 deg hue separation between picks. Returns up to
+ * `count` colors sorted by L ascending; may return fewer on low-diversity
+ * images (e.g. monochrome).
+ */
+export function extractPalette(
+    pixels: Uint8ClampedArray,
+    count?: number,
+): OklchColor[];
+
+// ---------------------------------------------------------------------------
+//  CSS parser
+// ---------------------------------------------------------------------------
+
+export interface ParsedLinearGradient {
+    mode: 'linear';
+    angle: number;
+    stops: Array<OklchColorA & { stop: number }>;
+}
+
+export interface ParsedRadialGradient {
+    mode: 'radial';
+    radShape: 'circle' | 'ellipse';
+    radCx: number;
+    radCy: number;
+    stops: Array<OklchColorA & { stop: number }>;
+}
+
+export interface ParsedConicGradient {
+    mode: 'conic';
+    conFrom: number;
+    conCx: number;
+    conCy: number;
+    stops: Array<OklchColorA & { stop: number }>;
+}
+
+export type ParsedGradient =
+    | ParsedLinearGradient
+    | ParsedRadialGradient
+    | ParsedConicGradient;
+
+/** Parse a CSS `linear-gradient`/`radial-gradient`/`conic-gradient` string. */
+export function parseGradientCss(input: string): ParsedGradient;
+
+// ---------------------------------------------------------------------------
+//  Multi-format exporters
+// ---------------------------------------------------------------------------
+
+export type Export1dFormat = 'css' | 'css-var' | 'scss' | 'tailwind' | 'json' | 'svg';
+export type ExportMeshFormat = 'css' | 'css-var' | 'json';
+
+export const EXPORT_FORMATS_1D: ReadonlyArray<Export1dFormat>;
+export const EXPORT_FORMATS_MESH: ReadonlyArray<ExportMeshFormat>;
+
+export interface FormatMetaEntry {
+    label: string;
+    hint: string;
+}
+
+export const FORMAT_META: Readonly<Record<Export1dFormat, FormatMetaEntry>>;
+
+/** 1D state shape consumed by the exporters (matches the editor's serialize/load). */
+export interface State1d {
+    mode: 'linear' | 'radial' | 'conic';
+    stops: Array<{
+        l: number;
+        c: number;
+        h: number;
+        a?: number;
+        stop: number;
+    }>;
+    angle?: number;            // linear
+    radShape?: 'circle' | 'ellipse';
+    radCx?: number; radCy?: number;
+    radPos?: string;           // legacy keyword form
+    conFrom?: number;
+    conCx?: number; conCy?: number;
+    conPos?: string;           // legacy keyword form
+}
+
+export interface ExportOptions {
+    name?: string;
+    width?: number;            // svg only
+    height?: number;           // svg only
+}
+
+export function toTokens1d(state: State1d, format: Export1dFormat, opts?: ExportOptions): string;
+export function toTokensMesh(mesh: MeshGradient, format: ExportMeshFormat, opts?: ExportOptions): string;
+
+export function toCss1d(state: State1d, opts?: ExportOptions): string;
+export function toCssVar1d(state: State1d, opts?: ExportOptions): string;
+export function toScss1d(state: State1d, opts?: ExportOptions): string;
+export function toTailwind1d(state: State1d, opts?: ExportOptions): string;
+export function toJson1d(state: State1d, opts?: ExportOptions): string;
+export function toSvg1d(state: State1d, opts?: ExportOptions): string;
+
+export function toCssMesh(mesh: MeshGradient, opts?: ExportOptions): string;
+export function toCssVarMesh(mesh: MeshGradient, opts?: ExportOptions): string;
+export function toJsonMesh(mesh: MeshGradient, opts?: ExportOptions): string;

package/src/index.js

@@ -0,0 +1,38 @@
+/**
+ * @zakkster/lite-gradient-studio
+ *
+ * Authoring layer on top of @zakkster/lite-gradient:
+ *   - High-fidelity CSS emitters (preserve authored stop positions, optional `in oklch` hint)
+ *   - Conic CSS emitter (missing from lite-gradient)
+ *   - Mesh gradient kernel — bilinear OKLCH over deformable control grid
+ *   - Multi-radial mesh → CSS approximation
+ *   - Multi-format exporters (CSS, SCSS, Tailwind, JSON, SVG)
+ *   - OKLCH ↔ hex conversion with sRGB-gamut mapping
+ *   - Pixel-buffer rasterizer for previews + PNG export
+ */
+
+import { Gradient } from '@zakkster/lite-gradient';
+
+export { Gradient };
+export * from '@zakkster/lite-gradient';
+export {
+    bakeGradientToLut,
+    flattenStopsToBuffer,
+    sampleLut,
+    packOklchSingle,
+} from './bake.js';
+export { MeshGradient, defaultMeshColor } from './mesh.js';
+export { formatCssLinear, formatCssRadial, formatCssConic } from './css-emitters.js';
+export { formatCssMesh } from './mesh-css.js';
+export {
+    toHex, fromHex, oklchToLinearSrgb, srgbGamma, srgbInverseGamma,
+    linearSrgbToOklch,
+} from './color-convert.js';
+export { extractPalette } from './palette-extract.js';
+export { parseGradientCss } from './gradient-parse.js';
+export {
+    EXPORT_FORMATS_1D, EXPORT_FORMATS_MESH, FORMAT_META,
+    toTokens1d, toTokensMesh,
+    toCss1d, toCssVar1d, toScss1d, toTailwind1d, toJson1d, toSvg1d,
+    toCssMesh, toCssVarMesh, toJsonMesh,
+} from './exporters.js';

package/src/mesh-css.js

@@ -0,0 +1,113 @@
+/**
+ * Mesh → CSS approximation.
+ *
+ * Real mesh gradients don't have a CSS primitive — `mesh-gradient()`
+ * isn't standardized. The conventional workaround (Mesher.app, Stripe-
+ * style aurora backgrounds, etc.) is to stack one `radial-gradient()`
+ * per control point, each fading from the point's color at center to
+ * transparent at an outer radius. With sensible overlap the alpha
+ * composites approximate the true bilinear field.
+ *
+ * This is genuinely an approximation, not a faithful reproduction —
+ * adjacent control points blend through the alpha layer, not through
+ * OKLCH interpolation. The visible result is close enough that most
+ * users prefer it to a giant PNG. For pixel-perfect output, use the
+ * PNG export path which renders our deformable bilinear kernel direct
+ * to a buffer.
+ *
+ * Output uses the `in oklch` interpolation hint on each radial so the
+ * color → transparent fade respects perceptual uniformity in browsers
+ * that support it (Chrome 111+, Firefox 113+, Safari 16.4+).
+ */
+
+import { toCssOklch } from '@zakkster/lite-color';
+
+/**
+ * @param {object} mesh         A MeshGradient instance (uses .stops, .cols, .rows)
+ * @param {object} [opts]
+ * @param {number} [opts.radiusPct]    Layer radius as % of farthest-corner.
+ *                                      Defaults to a formula scaled by mesh size.
+ * @param {string} [opts.shape='circle']  'circle' or 'ellipse'
+ * @param {boolean} [opts.oklchInterp=true]  Emit `in oklch` per layer.
+ * @param {boolean} [opts.includeBase=true]  Append a base color layer at end so
+ *                                            gaps between radials are filled.
+ * @returns {string}  A CSS `background:` value (no `background:` keyword, no
+ *                    trailing semicolon — caller decides how to wrap it).
+ */
+export function formatCssMesh(mesh, opts = {}) {
+    const {
+        radiusPct   = autoRadius(mesh),
+        shape       = 'circle',
+        oklchInterp = true,
+        includeBase = true,
+    } = opts;
+
+    const scratch = { l: 0, c: 0, h: 0, a: 1 };
+    const layers  = [];
+    const interp  = oklchInterp ? ' in oklch' : '';
+
+    for (const s of mesh.stops) {
+        scratch.l = s.l; scratch.c = s.c; scratch.h = s.h;
+        scratch.a = s.a === undefined ? 1 : s.a;
+        const color = toCssOklch(scratch);
+        const x = (s.x * 100).toFixed(1);
+        const y = (s.y * 100).toFixed(1);
+        // `transparent` resolves to oklch(0 0 0 / 0) — same hue interpolation.
+        layers.push(
+            `radial-gradient(${shape} at ${x}% ${y}%${interp}, ` +
+            `${color}, transparent ${radiusPct.toFixed(0)}%)`
+        );
+    }
+
+    if (includeBase) {
+        // Base layer = average of all stops. Picks a sensible "background"
+        // tone so gaps between radials don't show as transparent.
+        const avg = averageColor(mesh.stops);
+        scratch.l = avg.l; scratch.c = avg.c; scratch.h = avg.h;
+        scratch.a = avg.a;
+        layers.push(toCssOklch(scratch));
+    }
+
+    return layers.join(',\n            ');
+}
+
+/**
+ * Heuristic radius. Larger meshes → smaller per-layer radii (each
+ * layer covers less canvas, so seams between adjacent points stay
+ * tight; otherwise the alpha stack reduces to a muddy average).
+ *
+ * Tuned against 2×2 → 5×5: the multiplier (1.2×) gives ~20% overlap
+ * between neighbouring layers — enough that they blend, not enough
+ * that the field collapses toward the average. The base layer beneath
+ * fills any remaining gaps.
+ */
+function autoRadius(mesh) {
+    const n = Math.max(mesh.cols, mesh.rows);
+    if (n <= 2) return 70;
+    return Math.round(100 / (n - 1) * 1.2);
+}
+
+/**
+ * Average L/C and circular-mean H of the stops. Used as the base layer
+ * so the visible field has a sensible color where layers don't reach.
+ *
+ * Hue is averaged via vector mean (sum unit vectors at each hue, take
+ * angle of the resultant) so that a 350°/10° pair averages to ~0°/360°,
+ * not 180°. Standard circular-statistics trick.
+ */
+function averageColor(stops) {
+    let lSum = 0, cSum = 0, aSum = 0;
+    let hxSum = 0, hySum = 0;
+    const n = stops.length;
+    for (const s of stops) {
+        lSum += s.l;
+        cSum += s.c;
+        aSum += s.a === undefined ? 1 : s.a;
+        const rad = s.h * Math.PI / 180;
+        hxSum += Math.cos(rad);
+        hySum += Math.sin(rad);
+    }
+    let hAvg = Math.atan2(hySum / n, hxSum / n) * 180 / Math.PI;
+    if (hAvg < 0) hAvg += 360;
+    return { l: lSum / n, c: cSum / n, h: hAvg, a: aSum / n };
+}