first commit

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

@@ -0,0 +1,29 @@
+# @suaveplan/colour-convert-adapt - Bradford chromatic adaptation between XYZ illuminants for ICC-style colour management
+
+Bradford chromatic adaptation for XYZ colour coordinates. Chromatic adaptation adjusts a colour's appearance so that it looks the same under different light sources (illuminants). The Bradford transform is the industry-standard method, used in ICC colour management and many colour science toolkits.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [adapt](./src/adapt/adapt.md) — `adapt.ts` provides Bradford chromatic adaptation for XYZ colour coordinates. Chromatic adaptation adjusts a colour's a…
+  - [adapt](./src/adapt/adapt.md) — `adapt.ts` provides Bradford chromatic adaptation for XYZ colour coordinates. Chromatic adaptation adjusts a colour's a…
+<!-- end:auto-docs -->
+
+## Installation
+
+```bash
+bun add @suaveplan/colour-convert-adapt
+```
+
+## Quick Start
+
+```ts
+import { bradfordAdapt } from "@suaveplan/colour-convert-adapt";
+
+const d50 = bradfordAdapt({ x: 50, y: 50, z: 50 }, "D65", "D50");
+console.log(d50); // { x: ~52.9, y: ~50, z: ~37.7 }
+```
+
+## Modules
+
+- [`src/adapt/adapt.md`](./src/adapt/adapt.md) — Bradford chromatic adaptation implementation and API reference

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

@@ -0,0 +1,48 @@
+# adapt
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`adapt.ts` provides Bradford chromatic adaptation for XYZ colour coordinates. Chromatic adaptation adjusts a colour's appearance so that it looks the same under different light sources (illuminants). The Bradford transform is the industry-standard method for this, used in ICC colour management and many colour science toolkits. When a photograph is taken under tungsten lighting but viewed under daylight, chromatic adaptation predicts how the colours should be shifted to preserve their perceived appearance.
+
+## Features
+
+- 11 built-in standard illuminants (A, B, C, D50/55/65/75, E, F2/F7/F11)
+- Custom XYZ illuminant support for specialised workflows
+- Default destination is D65, the most common reference white
+- Full XYZ round-trip fidelity when source and destination match
+
+## Usage: Basic Example
+
+```ts
+import { bradfordAdapt } from "@suaveplan/colour-convert-adapt";
+
+const d50 = bradfordAdapt({ x: 50, y: 50, z: 50 }, "D65", "D50");
+```
+
+## Usage: Advanced Example
+
+```ts
+import { bradfordAdapt } from "@suaveplan/colour-convert-adapt";
+
+function matchIlluminant(colours: XYZ[], from: string, to: string) {
+    return colours.map((c) => bradfordAdapt(c, from, to));
+}
+```
+
+## API Reference
+
+### `bradfordAdapt(xyz: XYZ, source: string | XYZ, dest?: string | XYZ): XYZ`
+
+Adapts an XYZ colour from one illuminant to another using the Bradford chromatic adaptation transform. The `source` and `dest` parameters may be a named illuminant string or a custom XYZ white point. Defaults to D65 when `dest` is omitted.
+
+### `ILLUMINANTS: Record<string, XYZ>`
+
+Map of standard CIE illuminant white points used by the Bradford transform.
+
+## Implementation Notes
+
+The Bradford adaptation uses a cone-response space (LMS) via the Bradford matrix and its inverse. The XYZ colour is first converted to LMS, scaled by the ratio of destination to source white point in LMS space, then converted back to XYZ. This preserves colour appearance under changing lighting conditions. The matrix coefficients are from the ICC specification. Small floating-point differences may occur in identity transformations due to the finite precision of the matrix coefficients, but these are typically on the order of 0.0001% and negligible for practical applications.