first commit

docs/media/image/colour-convert-hsluv/README.md

@@ -0,0 +1,32 @@
+# @suaveplan/colour-convert-hsluv - HSLuv perceptually uniform colour space: conversions and harmony generators
+
+HSLuv perceptually-uniform colour space with gamut-mapped ray intersection for sRGB. This plugin provides bidirectional RGB↔HSLuv/HPLuv conversions and uniform colour harmonies (complementary, triad, tetrad) that preserve perceptual lightness across hue rotations.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [colour-convert-hsluv](./src/colour-convert-hsluv/colour-convert-hsluv.md) — `colour-convert-hsluv.ts` implements the HSLuv perceptually uniform colour space. Unlike HSL, which stretches and compr…
+  - [colour-convert-hsluv](./src/colour-convert-hsluv/colour-convert-hsluv.md) — `colour-convert-hsluv.ts` implements the HSLuv perceptually uniform colour space. Unlike HSL, which stretches and compr…
+<!-- end:auto-docs -->
+
+## Installation
+
+```bash
+bun add @suaveplan/colour-convert-hsluv
+```
+
+## Quick Start
+
+```ts
+import { rgbToHsluv, hsluvToRgb, uniformTriad } from "@suaveplan/colour-convert-hsluv";
+
+const hsluv = rgbToHsluv({ r: 255, g: 0, b: 0 });
+console.log(hsluv); // { h: ~12.2, s: ~100, l: ~53.2 }
+
+const colours = uniformTriad({ r: 59, g: 130, b: 246 });
+console.log(colours); // [primary, secondary, tertiary]
+```
+
+## Modules
+
+- [`src/colour-convert-hsluv/colour-convert-hsluv.md`](./src/colour-convert-hsluv/colour-convert-hsluv.md) — HSLuv/HPLuv conversion and uniform harmonies implementation

docs/media/image/colour-convert-hsluv/src/colour-convert-hsluv/colour-convert-hsluv.md

@@ -0,0 +1,53 @@
+# colour-convert-hsluv
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`colour-convert-hsluv.ts` implements the HSLuv perceptually uniform colour space. Unlike HSL, which stretches and compresses hue angles unevenly across lightness levels, HSLuv guarantees that a given saturation percentage produces the same visual intensity regardless of hue. This makes it ideal for generating harmonious colour palettes and accessible UI themes.
+
+## Features
+
+- RGB ↔ HSLuv bidirectional conversion with gamut mapping
+- RGB ↔ HPLuv (pastel variant) bidirectional conversion
+- Uniform colour harmonies: complementary, triad, and tetrad
+
+## Usage: Basic Example
+
+```ts
+import { rgbToHsluv, hsluvToRgb } from "@suaveplan/colour-convert-hsluv";
+
+const hsluv = rgbToHsluv({ r: 255, g: 0, b: 0 });
+const back = hsluvToRgb(hsluv);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { uniformTriad } from "@suaveplan/colour-convert-hsluv";
+
+const colours = uniformTriad({ r: 59, g: 130, b: 246 });
+```
+
+## API Reference
+
+### Conversions
+
+- `rgbToHsluv(rgb: RGB): HSLUV`
+- `hsluvToRgb(hsluv: HSLUV): RGBA`
+- `rgbToHpluv(rgb: RGB): HPLUV`
+- `hpluvToRgb(hpluv: HPLUV): RGBA`
+
+### Harmonies
+
+- `uniformComplementary(rgb: RGB): RGB[]`
+- `uniformTriad(rgb: RGB): RGB[]`
+- `uniformTetrad(rgb: RGB): RGB[]`
+
+## Implementation Notes
+
+The HSLuv algorithm computes the maximum chroma for a given hue by intersecting rays from the white point with the sRGB gamut boundary in CIELUV space. Six rays are tested (one per RGB cube edge) and the minimum positive intersection distance becomes the saturation scale factor. This ensures that 100% saturation always touches the gamut boundary, regardless of hue or lightness.
+
+All conversion pipelines are deterministic and free of side effects. The module has no runtime dependencies beyond the base `@suaveplan/colours` types, making it suitable for both server-side rendering and client-side bundling. Gamut mapping is performed automatically during RGB to HSLuv conversion, so out-of-range inputs are handled gracefully without throwing exceptions.