@basiclines/rampa-sdk 1.4.0 → 1.5.1

package/README.md

@@ -221,17 +221,41 @@ rampa.convert('#fe0000', 'oklch');  // 'oklch(62.8% 0.257 29)'
 rampa.convert('#fe0000', 'hex');    // '#fe0000'
 ```
 
+### `rampa.mix(color1, color2, t)`
+
+Mix two colors in OKLCH space at a given ratio. Produces perceptually uniform transitions — hues travel the color wheel naturally, lightness steps look even, and chroma stays vivid instead of dipping through gray.
+
+```js
+rampa.mix('#ff0000', '#0000ff', 0);    // '#ff0302' (start color)
+rampa.mix('#ff0000', '#0000ff', 0.5);  // midpoint — vivid purple, not muddy gray
+rampa.mix('#ff0000', '#0000ff', 1);    // '#0031e5' (end color)
+rampa.mix('#000000', '#ffffff', 0.5);  // perceptual mid-gray
+```
+
+Generate a gradient with multiple steps:
+
+```js
+const steps = 10;
+const gradient = Array.from({ length: steps }, (_, i) =>
+  rampa.mix('#ff0000', '#0000ff', i / (steps - 1))
+);
+```
+
 ## Types
 
 ```typescript
 import type {
-  ColorFormat,    // 'hex' | 'hsl' | 'rgb' | 'oklch'
-  ScaleType,      // 'linear' | 'fibonacci' | 'golden-ratio' | ...
-  BlendMode,      // 'normal' | 'multiply' | 'screen' | ...
-  HarmonyType,    // 'complementary' | 'triadic' | 'analogous' | ...
-  RampResult,     // { name, baseColor, colors }
-  RampaResult,    // { ramps: RampResult[] }
-  ColorInfo,      // { hex, rgb, hsl, oklch } — returned by readOnly()
+  ColorFormat,         // 'hex' | 'hsl' | 'rgb' | 'oklch'
+  ScaleType,           // 'linear' | 'fibonacci' | 'golden-ratio' | ...
+  BlendMode,           // 'normal' | 'multiply' | 'screen' | ...
+  HarmonyType,         // 'complementary' | 'triadic' | 'analogous' | ...
+  RampResult,          // { name, baseColor, colors }
+  RampaResult,         // { ramps: RampResult[] }
+  ColorInfo,           // { hex, rgb, hsl, oklch } — returned by readOnly()
+  InterpolationMode,   // 'oklch' | 'lab' | 'rgb'
+  ColorResult,         // { hex, format(), toString() }
+  LinearColorSpaceFn,  // callable function returned by LinearColorSpace.size()
+  CubeColorSpaceFn,    // callable function returned by CubeColorSpace.size()
 } from '@basiclines/rampa-sdk';
 ```
 
@@ -319,6 +343,136 @@ rampa --color "#3b82f6" --size=5 --lightness 10:90 --add=complementary --output
 rampa('#3b82f6').size(5).lightness(10, 90).add('complementary').toJSON();
 ```
 
+## Color Spaces
+
+Color spaces let you create structured palettes from a set of anchor colors and query them semantically. Two primitives are available:
+
+### `LinearColorSpace`
+
+Interpolates between two colors to produce an evenly-spaced ramp.
+
+```typescript
+import { LinearColorSpace } from '@basiclines/rampa-sdk';
+
+const neutral = new LinearColorSpace('#ffffff', '#000000').size(24);
+neutral(1)               // → ColorResult (lightest)
+neutral(12)              // → ColorResult (mid gray)
+neutral(24)              // → ColorResult (darkest)
+neutral(12).hex          // → '#666666'
+neutral(12).format('hsl') // → 'hsl(0, 0%, 40%)'
+neutral.palette          // → string[24]
+```
+
+#### Lookup table mode
+
+Set `.interpolation(false)` for a plain lookup table — no interpolation, just indexed access to the exact colors you provide:
+
+```typescript
+const base = new LinearColorSpace(
+  '#45475a', '#f38ba8', '#a6e3a1', '#f9e2af',
+  '#89b4fa', '#f5c2e7', '#94e2d5', '#a6adc8'
+).interpolation(false).size(8);
+
+base(1)  // → '#45475a' (exact, no interpolation)
+base(3)  // → '#a6e3a1'
+```
+
+### `CubeColorSpace`
+
+Creates a 3D color cube from 8 corner colors via trilinear interpolation. The constructor keys become alias names for semantic lookups.
+
+```typescript
+import { CubeColorSpace } from '@basiclines/rampa-sdk';
+
+const tint = new CubeColorSpace({
+  k: '#1e1e2e',    // origin (0,0,0)
+  r: '#f38ba8',    // x axis
+  g: '#a6e3a1',    // y axis
+  b: '#89b4fa',    // z axis
+  y: '#f9e2af',    // x+y
+  m: '#cba6f7',    // x+z
+  c: '#94e2d5',    // y+z
+  w: '#cdd6f4',    // x+y+z
+}).size(6);
+
+tint({ r: 4 })           // → strong red
+tint({ r: 4, b: 2 })     // → red-blue blend
+tint({ w: 3 })           // → mid-white (all axes at 3)
+tint({ r: 5, w: 2 })     // → pastel red (white raises base)
+tint.palette             // → string[216] (6³)
+```
+
+#### Custom vocabulary
+
+The alias names are whatever you put in the constructor — not limited to ANSI names:
+
+```typescript
+const space = new CubeColorSpace({
+  dark:    '#1a1a2e',
+  warm:    '#e74c3c',
+  nature:  '#2ecc71',
+  ocean:   '#3498db',
+  sunset:  '#f39c12',
+  berry:   '#9b59b6',
+  mint:    '#1abc9c',
+  light:   '#ecf0f1',
+}).size(6);
+
+space({ warm: 4, ocean: 2 })  // → warm-ocean blend
+```
+
+#### How aliases map to the cube
+
+The 8 keys map to cube corners by insertion order:
+
+| Position | Key # | Cube coords | Axis mask |
+|----------|-------|-------------|-----------|
+| 1st | origin | (0,0,0) | — |
+| 2nd | x | (1,0,0) | x |
+| 3rd | y | (0,1,0) | y |
+| 4th | z | (0,0,1) | z |
+| 5th | xy | (1,1,0) | x+y |
+| 6th | xz | (1,0,1) | x+z |
+| 7th | yz | (0,1,1) | y+z |
+| 8th | xyz | (1,1,1) | x+y+z |
+
+When you call `tint({ r: 4, b: 2 })`, each alias's mask is multiplied by its intensity and merged with `Math.max` to produce cube coordinates.
+
+### Interpolation modes
+
+Both `LinearColorSpace` and `CubeColorSpace` support configurable interpolation:
+
+| Mode | Description |
+|------|-------------|
+| `'oklch'` (default) | Perceptually uniform — hues travel the color wheel, even lightness steps |
+| `'lab'` | CIE L\*a\*b\* — perceptual but no hue rotation |
+| `'rgb'` | Linear RGB — fast but perceptually uneven |
+| `false` | No interpolation — plain lookup table (LinearColorSpace only) |
+
+```typescript
+// LinearColorSpace
+new LinearColorSpace('#ff0000', '#0000ff').interpolation('oklch').size(10)
+new LinearColorSpace('#ff0000', '#0000ff').interpolation('lab').size(10)
+new LinearColorSpace('#ff0000', '#0000ff').interpolation('rgb').size(10)
+new LinearColorSpace('#f00', '#0f0', '#00f').interpolation(false).size(3)
+
+// CubeColorSpace
+new CubeColorSpace({ ... }, { interpolation: 'lab' }).size(6)
+```
+
+### Color result chaining
+
+All color space lookups return a `ColorResult` that acts as a hex string but supports format conversion:
+
+```typescript
+const color = tint({ r: 4, b: 2 });
+color.hex              // → '#ab34cd'
+color.format('hsl')    // → 'hsl(280, 60%, 50%)'
+color.format('rgb')    // → 'rgb(171, 52, 205)'
+color.format('oklch')  // → 'oklch(52.3% 0.198 310)'
+color.toString()       // → '#ab34cd'
+```
+
 ## Development
 
 ```bash

package/dist/builder.d.ts

@@ -0,0 +1,38 @@
+import type { ColorFormat, ScaleType, BlendMode, HarmonyType, RampaResult } from './types';
+export declare class RampaBuilder {
+    private _baseColor;
+    private _size;
+    private _format;
+    private _lightnessStart;
+    private _lightnessEnd;
+    private _saturationStart;
+    private _saturationEnd;
+    private _hueStart;
+    private _hueEnd;
+    private _lightnessScale;
+    private _saturationScale;
+    private _hueScale;
+    private _tintColor?;
+    private _tintOpacity;
+    private _tintBlend;
+    private _harmonies;
+    constructor(baseColor: string);
+    size(steps: number): this;
+    format(fmt: ColorFormat): this;
+    lightness(start: number, end: number): this;
+    saturation(start: number, end: number): this;
+    hue(start: number, end: number): this;
+    lightnessScale(scale: ScaleType): this;
+    saturationScale(scale: ScaleType): this;
+    hueScale(scale: ScaleType): this;
+    tint(color: string, opacity: number, blend?: BlendMode): this;
+    add(type: HarmonyType): this;
+    add(type: 'shift', degrees: number): this;
+    private buildConfig;
+    private formatColor;
+    private getHarmonyColors;
+    private buildRamps;
+    generate(): RampaResult;
+    toCSS(): string;
+    toJSON(): string;
+}

package/dist/color-result.d.ts

@@ -0,0 +1,6 @@
+import type { ColorResult } from './types';
+/**
+ * Create a ColorResult from a hex string.
+ * Acts as a string (hex) by default, supports .format() for conversions.
+ */
+export declare function createColorResult(hex: string): ColorResult;

package/dist/cube-color-space.d.ts

@@ -0,0 +1,34 @@
+import type { InterpolationMode, CubeColorSpaceResult } from './types';
+/**
+ * Create a 3D color cube from 8 named corner colors.
+ *
+ * The constructor keys become shortcut function names and tint() aliases.
+ * Key order determines cube position (see CORNER_MASKS above).
+ *
+ * @example
+ * ```ts
+ * const space = new CubeColorSpace({
+ *   k: '#1e1e2e', r: '#f38ba8', g: '#a6e3a1', b: '#89b4fa',
+ *   y: '#f9e2af', m: '#cba6f7', c: '#94e2d5', w: '#cdd6f4',
+ * }).size(6);
+ *
+ * space.r(4)              // → ColorResult (single-axis shortcut)
+ * space.tint({ r: 3, b: 2 }) // → ColorResult (multi-axis)
+ * space.cube(3, 0, 2)     // → ColorResult (raw coordinates)
+ * space.palette            // → string[216]
+ *
+ * // Destructure for convenience:
+ * const { r, w, tint, cube } = space;
+ * ```
+ */
+export declare class CubeColorSpace {
+    private _corners;
+    private _interpolation;
+    constructor(corners: Record<string, string>, options?: {
+        interpolation?: InterpolationMode;
+    });
+    /**
+     * Set the steps per axis and return the color space accessor object.
+     */
+    size(stepsPerAxis: number): CubeColorSpaceResult;
+}

package/dist/formatters/css.d.ts

@@ -0,0 +1,2 @@
+import type { RampResult } from '../types';
+export declare function formatCssOutput(ramps: RampResult[]): string;

package/dist/formatters/json.d.ts

@@ -0,0 +1,2 @@
+import type { RampResult } from '../types';
+export declare function formatJsonOutput(ramps: RampResult[]): string;

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { RampaBuilder } from './builder';
+import { ReadOnlyBuilder } from './read-only';
+import { LinearColorSpace } from './linear-color-space';
+import { CubeColorSpace } from './cube-color-space';
+import type { ColorFormat, ScaleType, BlendMode, HarmonyType, RampResult, RampaResult, ColorInfo, InterpolationMode, ColorResult, RgbComponents, LinearColorSpaceFn, CubeColorSpaceResult, ColorSpaceOptions } from './types';
+/**
+ * Create a new color ramp builder from a base color.
+ *
+ * @example
+ * ```ts
+ * import { rampa } from '@basiclines/rampa-sdk';
+ *
+ * const result = rampa('#3b82f6').size(10).generate();
+ * const css = rampa('#3b82f6').add('complementary').toCSS();
+ * ```
+ */
+export declare function rampa(baseColor: string): RampaBuilder;
+export declare namespace rampa {
+    var convert: (color: string, format: ColorFormat) => string;
+    var readOnly: (color: string) => ReadOnlyBuilder;
+    var mix: (color1: string, color2: string, t: number) => string;
+}
+/**
+ * Create a ColorResult from any hex color string.
+ * Provides .hex, .rgb, .luminance, .format() for color inspection.
+ *
+ * @example
+ * ```ts
+ * import { color } from '@basiclines/rampa-sdk';
+ * const c = color('#ff0000');
+ * c.rgb        // { r: 255, g: 0, b: 0 }
+ * c.luminance  // 0.627 (OKLCH perceptual lightness)
+ * c.format('hsl') // 'hsl(0, 100%, 50%)'
+ * ```
+ */
+export declare function color(hex: string): ColorResult;
+export { RampaBuilder, ReadOnlyBuilder, LinearColorSpace, CubeColorSpace };
+export type { ColorFormat, ScaleType, BlendMode, HarmonyType, RampResult, RampaResult, ColorInfo, InterpolationMode, ColorResult, RgbComponents, LinearColorSpaceFn, CubeColorSpaceResult, ColorSpaceOptions, };

package/dist/index.js

@@ -7473,10 +7473,6 @@ var generateColorRamp = (config) => {
     const colors = [];
     const middleIndex = Math.floor(config.totalSteps / 2);
     for (let i = 0;i < config.totalSteps; i++) {
-      if (config.swatches && config.swatches[i]?.locked) {
-        colors.push(config.swatches[i].color);
-        continue;
-      }
       if (config.colorFormat === "oklch") {
         const color = generateSingleColorOklch(config, i, convertToOklch(config.baseColor), middleIndex);
         colors.push(color);
@@ -7875,34 +7871,261 @@ class ReadOnlyBuilder {
   }
 }
 
-// src/index.ts
-function rampa(baseColor) {
-  return new RampaBuilder(baseColor);
+// ../src/engine/ColorSpaceEngine.ts
+function mixWithMode(color1, color2, t, mode = "oklch") {
+  if (mode === "oklch") {
+    return mixOklch(color1, color2, t);
+  }
+  return chroma_js_default2.mix(color1, color2, t, mode).hex();
 }
-rampa.convert = function convert(color, format) {
-  const c2 = chroma_js_default(color);
-  switch (format) {
-    case "hsl": {
-      const [h, s, l] = c2.hsl();
-      return `hsl(${Math.round(h || 0)}, ${Math.round(s * 100)}%, ${Math.round(l * 100)}%)`;
+function mixOklch(color1, color2, t) {
+  const oklch1 = convertToOklch(color1);
+  const oklch22 = convertToOklch(color2);
+  let h1 = oklch1.h;
+  let h2 = oklch22.h;
+  let hueDiff = h2 - h1;
+  if (hueDiff > 180)
+    hueDiff -= 360;
+  if (hueDiff < -180)
+    hueDiff += 360;
+  let h = h1 + t * hueDiff;
+  if (h < 0)
+    h += 360;
+  if (h >= 360)
+    h -= 360;
+  if (oklch1.c < 0.002 && oklch22.c < 0.002) {
+    h = 0;
+  } else if (oklch1.c < 0.002) {
+    h = oklch22.h;
+  } else if (oklch22.c < 0.002) {
+    h = oklch1.h;
+  }
+  const mixed = {
+    l: oklch1.l + t * (oklch22.l - oklch1.l),
+    c: oklch1.c + t * (oklch22.c - oklch1.c),
+    h
+  };
+  const constrained = constrainOklchValues(mixed);
+  return convertFromOklch(constrained);
+}
+function generateLinearSpace(from, to, steps, mode = "oklch") {
+  const colors = [];
+  for (let i = 0;i < steps; i++) {
+    const t = steps === 1 ? 0.5 : i / (steps - 1);
+    colors.push(mixWithMode(from, to, t, mode));
+  }
+  return colors;
+}
+function generateCubeSpace(corners, stepsPerAxis, mode = "oklch") {
+  const [origin, x, y, z, xy, xz, yz, xyz] = corners;
+  const mix = (a, b, t) => mixWithMode(a, b, t, mode);
+  const max11 = stepsPerAxis - 1;
+  const colors = [];
+  for (let xi = 0;xi < stepsPerAxis; xi++) {
+    const tx = max11 === 0 ? 0 : xi / max11;
+    const c_x0y0 = mix(origin, x, tx);
+    const c_x0y1 = mix(y, xy, tx);
+    const c_x1y0 = mix(z, xz, tx);
+    const c_x1y1 = mix(yz, xyz, tx);
+    for (let yi = 0;yi < stepsPerAxis; yi++) {
+      const ty = max11 === 0 ? 0 : yi / max11;
+      const c_z0 = mix(c_x0y0, c_x0y1, ty);
+      const c_z1 = mix(c_x1y0, c_x1y1, ty);
+      for (let zi = 0;zi < stepsPerAxis; zi++) {
+        const tz = max11 === 0 ? 0 : zi / max11;
+        colors.push(mix(c_z0, c_z1, tz));
+      }
     }
-    case "rgb": {
-      const [r2, g, b] = c2.rgb();
-      return `rgb(${r2}, ${g}, ${b})`;
+  }
+  return colors;
+}
+
+// src/color-result.ts
+function createColorResult(hex6) {
+  const c2 = chroma_js_default(hex6);
+  const [r2, g, b] = c2.rgb();
+  const [l] = c2.oklch();
+  const result = {
+    hex: hex6,
+    rgb: { r: r2, g, b },
+    luminance: l,
+    format(fmt) {
+      switch (fmt) {
+        case "hsl": {
+          const [h, s, l2] = c2.hsl();
+          return `hsl(${Math.round(h || 0)}, ${Math.round(s * 100)}%, ${Math.round(l2 * 100)}%)`;
+        }
+        case "rgb": {
+          const [r3, g2, b2] = c2.rgb();
+          return `rgb(${r3}, ${g2}, ${b2})`;
+        }
+        case "oklch": {
+          const [l2, ch, h] = c2.oklch();
+          return `oklch(${(l2 * 100).toFixed(1)}% ${ch.toFixed(3)} ${Math.round(h || 0)})`;
+        }
+        default:
+          return hex6;
+      }
+    },
+    toString() {
+      return hex6;
     }
-    case "oklch": {
-      const [l, ch, h] = c2.oklch();
-      return `oklch(${(l * 100).toFixed(1)}% ${ch.toFixed(3)} ${Math.round(h || 0)})`;
+  };
+  return result;
+}
+
+// src/linear-color-space.ts
+class LinearColorSpace {
+  _colors;
+  _interpolation = "oklch";
+  constructor(...colors) {
+    if (colors.length < 2) {
+      throw new Error("LinearColorSpace requires at least 2 colors");
     }
-    default:
-      return c2.hex();
+    this._colors = colors;
   }
+  interpolation(mode) {
+    this._interpolation = mode;
+    return this;
+  }
+  size(steps) {
+    let palette;
+    if (this._interpolation === false) {
+      palette = [...this._colors];
+    } else {
+      palette = generateLinearSpace(this._colors[0], this._colors[this._colors.length - 1], steps, this._interpolation);
+    }
+    return buildFn(palette);
+  }
+}
+function buildFn(palette) {
+  const fn4 = (index) => {
+    const i = Math.max(1, Math.min(palette.length, index)) - 1;
+    return createColorResult(palette[i]);
+  };
+  fn4.palette = palette;
+  fn4.size = palette.length;
+  return fn4;
+}
+
+// src/cube-color-space.ts
+var CORNER_MASKS = [
+  { x: 0, y: 0, z: 0 },
+  { x: 1, y: 0, z: 0 },
+  { x: 0, y: 1, z: 0 },
+  { x: 0, y: 0, z: 1 },
+  { x: 1, y: 1, z: 0 },
+  { x: 1, y: 0, z: 1 },
+  { x: 0, y: 1, z: 1 },
+  { x: 1, y: 1, z: 1 }
+];
+
+class CubeColorSpace {
+  _corners;
+  _interpolation;
+  constructor(corners, options) {
+    const keys = Object.keys(corners);
+    if (keys.length !== 8) {
+      throw new Error(`CubeColorSpace requires exactly 8 corner colors, got ${keys.length}`);
+    }
+    this._corners = corners;
+    this._interpolation = options?.interpolation ?? "oklch";
+  }
+  size(stepsPerAxis) {
+    const keys = Object.keys(this._corners);
+    const cornerColors = keys.map((k3) => this._corners[k3]);
+    const aliases = {};
+    for (let i = 0;i < 8; i++) {
+      aliases[keys[i]] = CORNER_MASKS[i];
+    }
+    const palette = generateCubeSpace(cornerColors, stepsPerAxis, this._interpolation);
+    const max11 = stepsPerAxis - 1;
+    const lookup = (cx, cy, cz) => {
+      cx = Math.max(0, Math.min(max11, Math.round(cx)));
+      cy = Math.max(0, Math.min(max11, Math.round(cy)));
+      cz = Math.max(0, Math.min(max11, Math.round(cz)));
+      const index = cx * stepsPerAxis * stepsPerAxis + cy * stepsPerAxis + cz;
+      return createColorResult(palette[index]);
+    };
+    const tint = (query) => {
+      let cx = 0, cy = 0, cz = 0;
+      for (const [key, intensity] of Object.entries(query)) {
+        const mask = aliases[key];
+        if (!mask)
+          continue;
+        cx = Math.max(cx, mask.x * intensity);
+        cy = Math.max(cy, mask.y * intensity);
+        cz = Math.max(cz, mask.z * intensity);
+      }
+      return lookup(cx, cy, cz);
+    };
+    const cube = (x, y, z) => lookup(x, y, z);
+    const result = {
+      tint,
+      cube,
+      palette,
+      size: stepsPerAxis
+    };
+    for (const key of keys) {
+      result[key] = (index) => tint({ [key]: index });
+    }
+    return result;
+  }
+}
+
+// ../src/usecases/MixColors.ts
+function mixColors(color1, color2, t) {
+  const oklch1 = convertToOklch(color1);
+  const oklch22 = convertToOklch(color2);
+  let h1 = oklch1.h;
+  let h2 = oklch22.h;
+  let hueDiff = h2 - h1;
+  if (hueDiff > 180)
+    hueDiff -= 360;
+  if (hueDiff < -180)
+    hueDiff += 360;
+  let h = h1 + t * hueDiff;
+  if (h < 0)
+    h += 360;
+  if (h >= 360)
+    h -= 360;
+  if (oklch1.c < 0.002 && oklch22.c < 0.002) {
+    h = 0;
+  } else if (oklch1.c < 0.002) {
+    h = oklch22.h;
+  } else if (oklch22.c < 0.002) {
+    h = oklch1.h;
+  }
+  const mixed = {
+    l: oklch1.l + t * (oklch22.l - oklch1.l),
+    c: oklch1.c + t * (oklch22.c - oklch1.c),
+    h
+  };
+  const constrained = constrainOklchValues(mixed);
+  return convertFromOklch(constrained);
+}
+
+// src/index.ts
+function rampa(baseColor) {
+  return new RampaBuilder(baseColor);
+}
+rampa.convert = function convert(color, format) {
+  return createColorResult(color).format(format);
 };
 rampa.readOnly = function readOnly(color) {
   return new ReadOnlyBuilder(color);
 };
+rampa.mix = function mix(color1, color2, t) {
+  return mixColors(color1, color2, t);
+};
+function color(hex6) {
+  return createColorResult(hex6);
+}
 export {
   rampa,
+  color,
   ReadOnlyBuilder,
-  RampaBuilder
+  RampaBuilder,
+  LinearColorSpace,
+  CubeColorSpace
 };

package/dist/linear-color-space.d.ts

@@ -0,0 +1,36 @@
+import type { InterpolationMode, LinearColorSpaceFn } from './types';
+/**
+ * Create a linear color space.
+ *
+ * @example
+ * ```ts
+ * // Interpolated (default: oklch)
+ * const neutral = new LinearColorSpace('#ffffff', '#000000').size(24);
+ * neutral(12)                // → ColorResult (mid gray)
+ * neutral(12).format('hsl')  // → 'hsl(...)'
+ *
+ * // Different interpolation
+ * const ramp = new LinearColorSpace('#ff0000', '#0000ff').interpolation('lab').size(10);
+ *
+ * // Lookup table — no interpolation, just a plain color array
+ * const base = new LinearColorSpace('#000', '#f00', '#0f0', '#ff0', '#00f', '#f0f', '#0ff', '#fff')
+ *   .interpolation(false)
+ *   .size(8);
+ * base(1)  // → first color
+ * base(3)  // → third color
+ * ```
+ */
+export declare class LinearColorSpace {
+    private _colors;
+    private _interpolation;
+    constructor(...colors: string[]);
+    /**
+     * Set the interpolation mode.
+     * Pass false for a plain lookup table (no interpolation).
+     */
+    interpolation(mode: InterpolationMode | false): this;
+    /**
+     * Set the number of color steps and return the color accessor function.
+     */
+    size(steps: number): LinearColorSpaceFn;
+}

package/dist/read-only.d.ts

@@ -0,0 +1,8 @@
+import type { ColorFormat, ColorInfo } from './types';
+export declare class ReadOnlyBuilder {
+    private _color;
+    private _format?;
+    constructor(color: string);
+    format(fmt: ColorFormat): this;
+    generate(): ColorInfo | string;
+}

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+export type ColorFormat = 'hex' | 'hsl' | 'rgb' | 'oklch';
+export type ScaleType = 'linear' | 'geometric' | 'fibonacci' | 'golden-ratio' | 'logarithmic' | 'powers-of-2' | 'musical-ratio' | 'cielab-uniform' | 'ease-in' | 'ease-out' | 'ease-in-out';
+export type BlendMode = 'normal' | 'darken' | 'multiply' | 'plus-darker' | 'color-burn' | 'lighten' | 'screen' | 'plus-lighter' | 'color-dodge' | 'overlay' | 'soft-light' | 'hard-light' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity';
+export type HarmonyType = 'complementary' | 'triadic' | 'analogous' | 'split-complementary' | 'square' | 'compound';
+export interface RampResult {
+    name: string;
+    baseColor: string;
+    colors: string[];
+}
+export interface RampaResult {
+    ramps: RampResult[];
+}
+export interface ColorInfo {
+    hex: string;
+    rgb: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    hsl: {
+        h: number;
+        s: number;
+        l: number;
+    };
+    oklch: {
+        l: number;
+        c: number;
+        h: number;
+    };
+}
+export type InterpolationMode = 'oklch' | 'lab' | 'rgb';
+export interface ColorSpaceOptions {
+    interpolation?: InterpolationMode;
+}
+/**
+ * RGB components (0-255).
+ */
+export interface RgbComponents {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * A color result that acts as a hex string but supports format chaining.
+ */
+export interface ColorResult {
+    /** Hex color string */
+    hex: string;
+    /** RGB components (0-255) */
+    rgb: RgbComponents;
+    /** Perceptual luminance (0-1) using OKLCH lightness */
+    luminance: number;
+    /** Format the color as hsl, rgb, oklch, or hex */
+    format(fmt: ColorFormat): string;
+    /** String coercion returns hex */
+    toString(): string;
+}
+/**
+ * The function signature returned by LinearColorSpace.
+ * Call it with a 1-based index to get a color.
+ */
+export interface LinearColorSpaceFn {
+    (index: number): ColorResult;
+    palette: string[];
+    size: number;
+}
+/**
+ * The result object returned by CubeColorSpace.size().
+ * Provides multiple ways to access colors:
+ * - Per-corner shortcut functions (e.g. r(3), w(5))
+ * - tint() for multi-axis lookups
+ * - cube() for raw 3D coordinate access
+ * - palette for the full color array
+ */
+export interface CubeColorSpaceResult {
+    /** Multi-axis lookup: tint({ r: 3, b: 2 }) */
+    tint(query: Record<string, number>): ColorResult;
+    /** Raw 3D coordinate lookup: cube(x, y, z) */
+    cube(x: number, y: number, z: number): ColorResult;
+    /** Full palette array */
+    palette: string[];
+    /** Steps per axis */
+    size: number;
+    /** Per-corner shortcut functions, keyed by constructor key names */
+    [key: string]: ((index: number) => ColorResult) | string[] | number | ((query: Record<string, number>) => ColorResult) | ((x: number, y: number, z: number) => ColorResult);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basiclines/rampa-sdk",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Programmatic JavaScript SDK for generating color palettes with rampa",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,7 +9,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "bun build ./src/index.ts --outfile=./dist/index.js --target=node",
+    "build": "bun build ./src/index.ts --outfile=./dist/index.js --target=node && tsc -p tsconfig.declarations.json && cp dist/sdk/src/*.d.ts dist/ && cp -r dist/sdk/src/formatters dist/formatters 2>/dev/null; rm -rf dist/sdk dist/src",
     "test": "bun test"
   },
   "repository": {
@@ -26,6 +26,10 @@
   ],
   "author": "ismael.fyi",
   "license": "SEE LICENSE IN LICENSE.md",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "dependencies": {
     "chroma-js": "^3.1.2",
     "culori": "^4.0.1"