@classytic/stage 0.2.0 → 0.4.0

package/dist/colour/absorption.d.mts

@@ -0,0 +1,79 @@
+import { Spectrum, XYZ } from "./spectrum.mjs";
+import { SRGB } from "./srgb.mjs";
+
+//#region src/colour/absorption.d.ts
+/** One absorption band, as a spectrum is quoted: where it peaks, how wide, how strong. */
+interface AbsorptionBand {
+  /** Absorption maximum, λmax, in nm. */
+  readonly peakNm: number;
+  /** Full width at half maximum, in nm. A d-d band in water is typically 80 to 150. */
+  readonly widthNm: number;
+  /** Peak absorbance at `amount` = 1. Around 1 gives a clearly coloured solution. */
+  readonly strength: number;
+}
+/** Total absorbance at one wavelength, summed over every band and scaled by c·l. */
+declare function absorbance(bands: readonly AbsorptionBand[], nm: number, amount?: number): number;
+/** The fraction of light getting through at each wavelength: Beer-Lambert, `10^-A`. */
+declare const transmittance: (bands: readonly AbsorptionBand[], amount?: number) => Spectrum;
+/** A colour, in every form a caller here needs. */
+interface Colour {
+  readonly xyz: XYZ;
+  readonly srgb: SRGB;
+  /** `#rrggbb`, ready to draw with. */
+  readonly hex: string;
+  /** Hue in degrees, saturation and lightness 0 to 1. */
+  readonly hsl: {
+    readonly h: number;
+    readonly s: number;
+    readonly l: number;
+  };
+  /**
+   * The single wavelength the eye would call this colour, if there is one.
+   *
+   * `undefined` for a purple, which is not a wavelength at all. That is the honest answer for a
+   * solution absorbing green: what is left is red plus blue, and no lamp emits it.
+   */
+  readonly dominantNm: number | undefined;
+}
+/**
+ * The colour of any spectrum: the general entry point into this engine.
+ *
+ * Until this existed the only way in was through {@link solutionColour}, which asks what colour is
+ * LEFT when a sample absorbs. That is the right question for a solution in a beaker and the wrong
+ * one for anything that emits its own light, where the spectrum is what arrives rather than what
+ * survives. A flame, a discharge tube and a star all needed a door that was not there.
+ *
+ * The white point is what the result is balanced against, and it defaults to equal energy. Pass the
+ * illuminant instead when the sample is being viewed under a particular light.
+ */
+declare const colourFromSpectrum: (spectrum: Spectrum, white?: Spectrum) => Colour;
+/**
+ * The colour of one wavelength, at the brightness a spectrum is DRAWN at.
+ *
+ * The luminance is normalised, and that is a deliberate departure from the raw physics. One 5 nm
+ * slice of an equal-energy spectrum carries very little light, so unnormalised every wavelength
+ * came out near black: the bar was ten shades of very dark. What a spectrum illustration shows is
+ * the HUE at each wavelength, which is what this returns.
+ *
+ * The ends still fade, because they have to. Below about 410 nm and above about 690 the eye's own
+ * response has nearly gone, and a bar that stayed vivid to 780 would claim a visibility that is not
+ * there. The taper is that response, not a decoration.
+ */
+declare function spectralColour(nm: number): Colour;
+/**
+ * The colour of a solution, from its absorption bands.
+ *
+ * `white` defaults to equal energy, so the result is a transmittance colour: absorb nothing and it
+ * comes out white, which is the correct answer for a colourless solution.
+ */
+declare function solutionColour(bands: readonly AbsorptionBand[], amount?: number, white?: Spectrum): Colour;
+/**
+ * The colour left when ONE band is taken out of white light: the complementary colour, computed.
+ *
+ * This is the whole of "a solution is the colour it does not absorb", and it is derived rather than
+ * tabulated. Absorbing 575 nm gives a violet, and the violet has no dominant wavelength of its own,
+ * which is the reason the rule cannot be stated as "the opposite wavelength".
+ */
+declare const complementaryOf: (absorbedNm: number, widthNm?: number, strength?: number) => Colour;
+//#endregion
+export { AbsorptionBand, Colour, absorbance, colourFromSpectrum, complementaryOf, solutionColour, spectralColour, transmittance };

package/dist/colour/absorption.mjs

@@ -0,0 +1,137 @@
+import { yBar } from "./observer.mjs";
+import { EQUAL_ENERGY, dominantWavelength, spectrumToXYZ } from "./spectrum.mjs";
+import { fitGamut, hexOf, hslOf, linearToSRGB, whiteBalance, xyzToLinear } from "./srgb.mjs";
+
+//#region src/colour/absorption.ts
+/**
+* What a solution looks like, worked out from what it absorbs.
+*
+* This is the file a chemistry lab actually wants. Declare the absorption band a species has,
+* say how much of it is in the way, and the colour that reaches the eye comes out. Nothing is
+* looked up: the complementary colour is produced by removing the band from white light and
+* integrating what is left against the eye's own response, which is what the eye does.
+*
+* ## Why the answer changes with concentration, for free
+*
+* Beer-Lambert says absorbance is proportional to concentration and path length, and transmittance
+* is `10^-A`. So `amount` here is the product c·l in whatever units make the band's `strength` an
+* absorbance, and the consequences arrive on their own: a dilute copper solution is a pale blue that
+* a concentrated one deepens without changing hue, until the band saturates and the colour stops
+* responding. A lab that wants to teach colorimetry has that behaviour already, rather than needing
+* a second table of colours for "dilute".
+*
+* ## Why the band is a Gaussian
+*
+* A d-d transition in solution is broadened by every solvent molecule moving, and the observed
+* envelope is close to Gaussian. `widthNm` is the FULL WIDTH AT HALF MAXIMUM, which is the number a
+* spectrum is quoted with, not a standard deviation.
+*/
+/** Converts FWHM to the coefficient of a Gaussian exponent. */
+const FWHM = 4 * Math.LN2;
+/** Total absorbance at one wavelength, summed over every band and scaled by c·l. */
+function absorbance(bands, nm, amount = 1) {
+	let a = 0;
+	for (const band of bands) {
+		const t = (nm - band.peakNm) / band.widthNm;
+		a += band.strength * Math.exp(-FWHM * t * t);
+	}
+	return a * amount;
+}
+/** The fraction of light getting through at each wavelength: Beer-Lambert, `10^-A`. */
+const transmittance = (bands, amount = 1) => (nm) => Math.pow(10, -absorbance(bands, nm, amount));
+/**
+* Every colour here is measured against a lamp, so the lamp is divided out.
+*
+* The default illuminant's own linear RGB is computed once, LAZILY. A module-level `new Map()` was
+* the first version and it is a top-level side effect: a bundler cannot prove it inert, so it
+* pins this module into any build that merely imports the package. A `let` filled on first call
+* costs nothing and leaves the module free of top-level work.
+*/
+let equalEnergyWhite;
+const whiteLinear = (white) => {
+	if (white !== EQUAL_ENERGY) return xyzToLinear(spectrumToXYZ(white, white));
+	equalEnergyWhite ??= xyzToLinear(spectrumToXYZ(white, white));
+	return equalEnergyWhite;
+};
+const colourOf = (xyz, white) => {
+	const srgb = linearToSRGB(whiteBalance(xyzToLinear(xyz), whiteLinear(white)));
+	return {
+		xyz,
+		srgb,
+		hex: hexOf(srgb),
+		hsl: hslOf(srgb),
+		dominantNm: dominantWavelength(xyz)
+	};
+};
+/**
+* The colour of any spectrum: the general entry point into this engine.
+*
+* Until this existed the only way in was through {@link solutionColour}, which asks what colour is
+* LEFT when a sample absorbs. That is the right question for a solution in a beaker and the wrong
+* one for anything that emits its own light, where the spectrum is what arrives rather than what
+* survives. A flame, a discharge tube and a star all needed a door that was not there.
+*
+* The white point is what the result is balanced against, and it defaults to equal energy. Pass the
+* illuminant instead when the sample is being viewed under a particular light.
+*/
+const colourFromSpectrum = (spectrum, white = EQUAL_ENERGY) => colourOf(spectrumToXYZ(spectrum, white), white);
+/**
+* The colour of one wavelength, at the brightness a spectrum is DRAWN at.
+*
+* The luminance is normalised, and that is a deliberate departure from the raw physics. One 5 nm
+* slice of an equal-energy spectrum carries very little light, so unnormalised every wavelength
+* came out near black: the bar was ten shades of very dark. What a spectrum illustration shows is
+* the HUE at each wavelength, which is what this returns.
+*
+* The ends still fade, because they have to. Below about 410 nm and above about 690 the eye's own
+* response has nearly gone, and a bar that stayed vivid to 780 would claim a visibility that is not
+* there. The taper is that response, not a decoration.
+*/
+function spectralColour(nm) {
+	const hueNm = Math.max(400, Math.min(660, nm));
+	const raw = spectrumToXYZ((l) => Math.abs(l - hueNm) <= 2.5 ? 1 : 0);
+	if (raw.Y <= 0) return colourOf(raw, EQUAL_ENERGY);
+	const k = 1.4 / raw.Y;
+	const full = fitGamut(whiteBalance(xyzToLinear({
+		X: raw.X * k,
+		Y: raw.Y * k,
+		Z: raw.Z * k
+	}), whiteLinear(EQUAL_ENERGY)));
+	const visible = Math.sqrt(Math.min(1, yBar(nm) / .05));
+	const srgb = linearToSRGB({
+		r: full.r * visible,
+		g: full.g * visible,
+		b: full.b * visible
+	});
+	return {
+		xyz: raw,
+		srgb,
+		hex: hexOf(srgb),
+		hsl: hslOf(srgb),
+		dominantNm: dominantWavelength(raw)
+	};
+}
+/**
+* The colour of a solution, from its absorption bands.
+*
+* `white` defaults to equal energy, so the result is a transmittance colour: absorb nothing and it
+* comes out white, which is the correct answer for a colourless solution.
+*/
+function solutionColour(bands, amount = 1, white = EQUAL_ENERGY) {
+	return colourOf(spectrumToXYZ(transmittance(bands, amount), white), white);
+}
+/**
+* The colour left when ONE band is taken out of white light: the complementary colour, computed.
+*
+* This is the whole of "a solution is the colour it does not absorb", and it is derived rather than
+* tabulated. Absorbing 575 nm gives a violet, and the violet has no dominant wavelength of its own,
+* which is the reason the rule cannot be stated as "the opposite wavelength".
+*/
+const complementaryOf = (absorbedNm, widthNm = 110, strength = 1.6) => solutionColour([{
+	peakNm: absorbedNm,
+	widthNm,
+	strength
+}]);
+
+//#endregion
+export { absorbance, colourFromSpectrum, complementaryOf, solutionColour, spectralColour, transmittance };

package/dist/colour/index.d.mts

@@ -0,0 +1,6 @@
+import { VISIBLE_FROM, VISIBLE_TO, observer, xBar, yBar, zBar } from "./observer.mjs";
+import { EQUAL_ENERGY, Spectrum, XYZ, chromaticity, dominantWavelength, monochromatic, spectrumToXYZ } from "./spectrum.mjs";
+import { LinearRGB, SRGB, fitGamut, hexOf, hslOf, linearToSRGB, xyzToLinear, xyzToSRGB } from "./srgb.mjs";
+import { AbsorptionBand, Colour, absorbance, colourFromSpectrum, complementaryOf, solutionColour, spectralColour, transmittance } from "./absorption.mjs";
+import { ColourName, nameOf } from "./name.mjs";
+export { type AbsorptionBand, type Colour, type ColourName, EQUAL_ENERGY, type LinearRGB, type SRGB, type Spectrum, VISIBLE_FROM, VISIBLE_TO, type XYZ, absorbance, chromaticity, colourFromSpectrum, complementaryOf, dominantWavelength, fitGamut, hexOf, hslOf, linearToSRGB, monochromatic, nameOf, observer, solutionColour, spectralColour, spectrumToXYZ, transmittance, xBar, xyzToLinear, xyzToSRGB, yBar, zBar };

package/dist/colour/index.mjs

@@ -0,0 +1,7 @@
+import { VISIBLE_FROM, VISIBLE_TO, observer, xBar, yBar, zBar } from "./observer.mjs";
+import { EQUAL_ENERGY, chromaticity, dominantWavelength, monochromatic, spectrumToXYZ } from "./spectrum.mjs";
+import { fitGamut, hexOf, hslOf, linearToSRGB, xyzToLinear, xyzToSRGB } from "./srgb.mjs";
+import { absorbance, colourFromSpectrum, complementaryOf, solutionColour, spectralColour, transmittance } from "./absorption.mjs";
+import { nameOf } from "./name.mjs";
+
+export { EQUAL_ENERGY, VISIBLE_FROM, VISIBLE_TO, absorbance, chromaticity, colourFromSpectrum, complementaryOf, dominantWavelength, fitGamut, hexOf, hslOf, linearToSRGB, monochromatic, nameOf, observer, solutionColour, spectralColour, spectrumToXYZ, transmittance, xBar, xyzToLinear, xyzToSRGB, yBar, zBar };

package/dist/colour/name.d.mts

@@ -0,0 +1,14 @@
+import { Colour } from "./absorption.mjs";
+
+//#region src/colour/name.d.ts
+type ColourName = 'red' | 'orange' | 'yellow' | 'yellow-green' | 'green' | 'blue-green' | 'green-blue' | 'blue' | 'violet' | 'purple' | 'pink' | 'brown' | 'grey' | 'colourless';
+/**
+ * Name a colour.
+ *
+ * Saturation and lightness are checked BEFORE hue, because a pale unsaturated thing has a hue angle
+ * and is not that colour. A copper(II) solution and a drop of it in a swimming pool have nearly the
+ * same hue; only one of them is blue.
+ */
+declare function nameOf(colour: Colour): ColourName;
+//#endregion
+export { ColourName, nameOf };

package/dist/colour/name.mjs

@@ -0,0 +1,76 @@
+//#region src/colour/name.ts
+/**
+* Hue bands, in degrees, each holding the upper bound of the name before it.
+*
+* The boundaries are calibrated against complexes whose colour a mark scheme names, not spaced
+* evenly. Two of them were moved after measurement:
+*
+*   YELLOW starts at 34, not 42. [Cr(NH₃)₆]³⁺ computes to hue 38 and every syllabus calls it
+*   yellow. Chemistry's "yellow" reaches further into the orange than a designer's does.
+*
+*   BLUE ends at 246, not 250. [Cr(H₂O)₆]³⁺ computes to hue 250 and is violet, which put it exactly
+*   on the old boundary and therefore one rounding away from being named wrong.
+*/
+const HUES = [
+	{
+		upTo: 14,
+		name: "red"
+	},
+	{
+		upTo: 34,
+		name: "orange"
+	},
+	{
+		upTo: 66,
+		name: "yellow"
+	},
+	{
+		upTo: 90,
+		name: "yellow-green"
+	},
+	{
+		upTo: 152,
+		name: "green"
+	},
+	{
+		upTo: 176,
+		name: "blue-green"
+	},
+	{
+		upTo: 196,
+		name: "green-blue"
+	},
+	{
+		upTo: 246,
+		name: "blue"
+	},
+	{
+		upTo: 290,
+		name: "violet"
+	},
+	{
+		upTo: 330,
+		name: "purple"
+	},
+	{
+		upTo: 360,
+		name: "red"
+	}
+];
+/**
+* Name a colour.
+*
+* Saturation and lightness are checked BEFORE hue, because a pale unsaturated thing has a hue angle
+* and is not that colour. A copper(II) solution and a drop of it in a swimming pool have nearly the
+* same hue; only one of them is blue.
+*/
+function nameOf(colour) {
+	const { h, s, l } = colour.hsl;
+	if (l > .93 || s < .06) return l > .93 ? "colourless" : "grey";
+	if (l < .42 && s < .7 && h >= 14 && h < 50) return "brown";
+	if (l > .72 && (h < 20 || h >= 330)) return "pink";
+	return HUES.find((band) => h < band.upTo)?.name ?? "red";
+}
+
+//#endregion
+export { nameOf };

package/dist/colour/observer.d.mts

@@ -0,0 +1,31 @@
+//#region src/colour/observer.d.ts
+/**
+ * The CIE 1931 2° standard observer: how a human eye responds to each wavelength.
+ *
+ * This is the measured data the whole engine rests on. Three response curves, one per cone type as
+ * reconciled by the CIE in 1931, and everything else here is arithmetic on top of them.
+ *
+ * ## Why an analytic fit rather than a 81-row table
+ *
+ * The published data is tabulated at 5 nm and would be 243 numbers typed by hand, every one of them
+ * a chance to transpose a digit that no test would notice. Wyman, Sloan and Shirley (2013),
+ * "Simple Analytic Approximations to the CIE XYZ Color Matching Functions", JCGT 2(2), fit each
+ * curve with a sum of piecewise-Gaussian lobes to under about 1% error. Their constants are the
+ * whole dataset in twenty numbers, and the fit is checked the only way that matters: the white
+ * points it produces. `tests/colour.test.ts` asserts that an equal-energy spectrum lands on
+ * (1/3, 1/3) in chromaticity, which is the definition of illuminant E and which a mistyped constant
+ * would miss.
+ */
+/** Visible range, in nanometres. Outside it the response is zero and a colour is not defined. */
+declare const VISIBLE_FROM = 380;
+declare const VISIBLE_TO = 780;
+/** The x̄ response: two red-orange lobes, with a small negative correction near cyan. */
+declare const xBar: (nm: number) => number;
+/** The ȳ response, which is also the luminous efficiency curve: what "bright" means. */
+declare const yBar: (nm: number) => number;
+/** The z̄ response: entirely in the blue and violet. */
+declare const zBar: (nm: number) => number;
+/** All three at one wavelength. */
+declare const observer: (nm: number) => readonly [number, number, number];
+//#endregion
+export { VISIBLE_FROM, VISIBLE_TO, observer, xBar, yBar, zBar };

package/dist/colour/observer.mjs

@@ -0,0 +1,46 @@
+//#region src/colour/observer.ts
+/**
+* The CIE 1931 2° standard observer: how a human eye responds to each wavelength.
+*
+* This is the measured data the whole engine rests on. Three response curves, one per cone type as
+* reconciled by the CIE in 1931, and everything else here is arithmetic on top of them.
+*
+* ## Why an analytic fit rather than a 81-row table
+*
+* The published data is tabulated at 5 nm and would be 243 numbers typed by hand, every one of them
+* a chance to transpose a digit that no test would notice. Wyman, Sloan and Shirley (2013),
+* "Simple Analytic Approximations to the CIE XYZ Color Matching Functions", JCGT 2(2), fit each
+* curve with a sum of piecewise-Gaussian lobes to under about 1% error. Their constants are the
+* whole dataset in twenty numbers, and the fit is checked the only way that matters: the white
+* points it produces. `tests/colour.test.ts` asserts that an equal-energy spectrum lands on
+* (1/3, 1/3) in chromaticity, which is the definition of illuminant E and which a mistyped constant
+* would miss.
+*/
+/** Visible range, in nanometres. Outside it the response is zero and a colour is not defined. */
+const VISIBLE_FROM = 380;
+const VISIBLE_TO = 780;
+/**
+* A Gaussian that is allowed a different width on each side of its peak.
+*
+* `inv1` and `inv2` are RECIPROCAL widths in 1/nm, which is the form the paper publishes and the
+* form that keeps the constants below readable.
+*/
+const lobe = (nm, peak, inv1, inv2) => {
+	const t = (nm - peak) * (nm < peak ? inv1 : inv2);
+	return Math.exp(-.5 * t * t);
+};
+/** The x̄ response: two red-orange lobes, with a small negative correction near cyan. */
+const xBar = (nm) => .362 * lobe(nm, 442, .0624, .0374) + 1.056 * lobe(nm, 599.8, .0264, .0323) - .065 * lobe(nm, 501.1, .049, .0382);
+/** The ȳ response, which is also the luminous efficiency curve: what "bright" means. */
+const yBar = (nm) => .821 * lobe(nm, 568.8, .0213, .0247) + .286 * lobe(nm, 530.9, .0613, .0322);
+/** The z̄ response: entirely in the blue and violet. */
+const zBar = (nm) => 1.217 * lobe(nm, 437, .0845, .0278) + .681 * lobe(nm, 459, .0385, .0725);
+/** All three at one wavelength. */
+const observer = (nm) => [
+	xBar(nm),
+	yBar(nm),
+	zBar(nm)
+];
+
+//#endregion
+export { VISIBLE_FROM, VISIBLE_TO, observer, xBar, yBar, zBar };

package/dist/colour/spectrum.d.mts

@@ -0,0 +1,61 @@
+//#region src/colour/spectrum.d.ts
+/**
+ * A spectrum, and the tristimulus values it produces in a human eye.
+ *
+ * A spectrum here is a FUNCTION of wavelength, not an array. That is what lets an absorption band
+ * be declared by its peak and width rather than sampled into a table by every caller, and it is
+ * what lets the integration step choose its own resolution.
+ *
+ * ## White light is equal energy, and that is a choice worth stating
+ *
+ * The engine's default white is CIE illuminant E: the same power at every visible wavelength. Real
+ * daylight is D65, which needs its own measured table and is slightly blue. E is used because a
+ * chemistry lesson says "white light goes in, one band is absorbed, the rest reaches your eye", and
+ * in that sentence white light means equal at every wavelength. Using D65 would tint every result
+ * by the lamp rather than by the chemistry, which is the one thing a colour here must not do.
+ *
+ * Pass any other illuminant explicitly if a lab ever needs one.
+ */
+/** Spectral power at a wavelength in nm. Any non-negative scale: only ratios matter. */
+type Spectrum = (nm: number) => number;
+/** CIE XYZ tristimulus values, normalised so that a white spectrum gives Y = 1. */
+interface XYZ {
+  readonly X: number;
+  readonly Y: number;
+  readonly Z: number;
+}
+/** Equal power at every visible wavelength: CIE illuminant E, and what "white light" means here. */
+declare const EQUAL_ENERGY: Spectrum;
+/** A single wavelength, as a spectrum. Width 0 is not representable, so it is one nanometre wide. */
+declare const monochromatic: (peakNm: number) => Spectrum;
+/**
+ * Integrate a spectrum against the observer, normalised so the reference white gives Y = 1.
+ *
+ * The normalisation is what makes the result a REFLECTANCE or transmittance colour rather than a
+ * brightness: a solution that absorbs nothing comes out white rather than some arbitrary Y.
+ *
+ * `step` is 1 nm, which is finer than the 5 nm the observer data is published at, so the
+ * integration error is far below the error in the fit itself.
+ */
+declare function spectrumToXYZ(spectrum: Spectrum, white?: Spectrum): XYZ;
+/**
+ * Chromaticity: the colour with its brightness divided out.
+ *
+ * Useful for one thing above all, which is checking this engine against a published number. An
+ * equal-energy spectrum must land on (1/3, 1/3), and that is a test the fitted observer curves
+ * cannot pass by accident.
+ */
+declare function chromaticity(xyz: XYZ): {
+  readonly x: number;
+  readonly y: number;
+};
+/**
+ * The dominant wavelength: which single wavelength the eye would call this colour.
+ *
+ * Returned as the wavelength whose chromaticity is closest in direction from the white point, and
+ * `undefined` when the colour is a purple, because purples are not on the spectral locus at all.
+ * That is not a limitation to work around: it is why a magenta cannot be written as a wavelength.
+ */
+declare function dominantWavelength(xyz: XYZ): number | undefined;
+//#endregion
+export { EQUAL_ENERGY, Spectrum, XYZ, chromaticity, dominantWavelength, monochromatic, spectrumToXYZ };

package/dist/colour/spectrum.mjs

@@ -0,0 +1,108 @@
+import { VISIBLE_FROM, VISIBLE_TO, observer } from "./observer.mjs";
+
+//#region src/colour/spectrum.ts
+/**
+* A spectrum, and the tristimulus values it produces in a human eye.
+*
+* A spectrum here is a FUNCTION of wavelength, not an array. That is what lets an absorption band
+* be declared by its peak and width rather than sampled into a table by every caller, and it is
+* what lets the integration step choose its own resolution.
+*
+* ## White light is equal energy, and that is a choice worth stating
+*
+* The engine's default white is CIE illuminant E: the same power at every visible wavelength. Real
+* daylight is D65, which needs its own measured table and is slightly blue. E is used because a
+* chemistry lesson says "white light goes in, one band is absorbed, the rest reaches your eye", and
+* in that sentence white light means equal at every wavelength. Using D65 would tint every result
+* by the lamp rather than by the chemistry, which is the one thing a colour here must not do.
+*
+* Pass any other illuminant explicitly if a lab ever needs one.
+*/
+/** Equal power at every visible wavelength: CIE illuminant E, and what "white light" means here. */
+const EQUAL_ENERGY = () => 1;
+/** A single wavelength, as a spectrum. Width 0 is not representable, so it is one nanometre wide. */
+const monochromatic = (peakNm) => (nm) => Math.abs(nm - peakNm) <= .5 ? 1 : 0;
+/**
+* Integrate a spectrum against the observer, normalised so the reference white gives Y = 1.
+*
+* The normalisation is what makes the result a REFLECTANCE or transmittance colour rather than a
+* brightness: a solution that absorbs nothing comes out white rather than some arbitrary Y.
+*
+* `step` is 1 nm, which is finer than the 5 nm the observer data is published at, so the
+* integration error is far below the error in the fit itself.
+*/
+function spectrumToXYZ(spectrum, white = EQUAL_ENERGY) {
+	let X = 0;
+	let Y = 0;
+	let Z = 0;
+	let norm = 0;
+	for (let nm = 380; nm <= 780; nm += 1) {
+		const [x, y, z] = observer(nm);
+		const w = white(nm);
+		const p = spectrum(nm) * w;
+		X += p * x;
+		Y += p * y;
+		Z += p * z;
+		norm += w * y;
+	}
+	if (norm === 0) return {
+		X: 0,
+		Y: 0,
+		Z: 0
+	};
+	return {
+		X: X / norm,
+		Y: Y / norm,
+		Z: Z / norm
+	};
+}
+/**
+* Chromaticity: the colour with its brightness divided out.
+*
+* Useful for one thing above all, which is checking this engine against a published number. An
+* equal-energy spectrum must land on (1/3, 1/3), and that is a test the fitted observer curves
+* cannot pass by accident.
+*/
+function chromaticity(xyz) {
+	const sum = xyz.X + xyz.Y + xyz.Z;
+	if (sum === 0) return {
+		x: 0,
+		y: 0
+	};
+	return {
+		x: xyz.X / sum,
+		y: xyz.Y / sum
+	};
+}
+/**
+* The dominant wavelength: which single wavelength the eye would call this colour.
+*
+* Returned as the wavelength whose chromaticity is closest in direction from the white point, and
+* `undefined` when the colour is a purple, because purples are not on the spectral locus at all.
+* That is not a limitation to work around: it is why a magenta cannot be written as a wavelength.
+*/
+function dominantWavelength(xyz) {
+	const c = chromaticity(xyz);
+	const dx = c.x - 1 / 3;
+	const dy = c.y - 1 / 3;
+	const len = Math.hypot(dx, dy);
+	if (len < 1e-4) return void 0;
+	let best;
+	let bestDot = -1;
+	for (let nm = 380; nm <= 780; nm += 1) {
+		const s = chromaticity(spectrumToXYZ(monochromatic(nm)));
+		const ex = s.x - 1 / 3;
+		const ey = s.y - 1 / 3;
+		const elen = Math.hypot(ex, ey);
+		if (elen < 1e-6) continue;
+		const dot = (dx * ex + dy * ey) / (len * elen);
+		if (dot > bestDot) {
+			bestDot = dot;
+			best = nm;
+		}
+	}
+	return bestDot > .999 ? best : void 0;
+}
+
+//#endregion
+export { EQUAL_ENERGY, chromaticity, dominantWavelength, monochromatic, spectrumToXYZ };

package/dist/colour/srgb.d.mts

@@ -0,0 +1,49 @@
+import { XYZ } from "./spectrum.mjs";
+
+//#region src/colour/srgb.d.ts
+/** Linear RGB in the sRGB primaries. Components may be negative or above one before fitting. */
+interface LinearRGB {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+}
+/** sRGB with the transfer function applied, each channel 0 to 255. */
+interface SRGB {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+}
+/** The sRGB / Rec. 709 matrix, for a D65 white point. */
+declare function xyzToLinear(xyz: XYZ): LinearRGB;
+/**
+ * Bring a colour into gamut: clamp the negative channels, then scale to fit.
+ *
+ * A pure wavelength is more saturated than three phosphors can make, so its linear RGB has a
+ * negative component and something has to give. The alternative tried here first was to desaturate,
+ * mixing toward grey of the same luminance until the negative channel reached zero, on the argument
+ * that desaturation preserves hue and clamping does not.
+ *
+ * Measured across the spectrum at 20 nm, that argument is simply wrong for this data, and in the
+ * red it is badly wrong. Desaturating 650 nm gives `#ff004e`, a pink, because the green channel is
+ * far more negative than the blue: mixing far enough to lift green to zero carries blue up past it.
+ * Clamping gives `#ff0000`. The same holds at 530 nm, where desaturating produces a mint green and
+ * clamping produces green. Published spectral colour tables agree with the clamped values.
+ *
+ * The lesson is that the hue-preservation argument applies to a colour with ONE offending channel,
+ * and a spectral colour usually has two of unequal size.
+ */
+declare function fitGamut(rgb: LinearRGB): LinearRGB;
+/** Linear RGB to 8-bit sRGB, fitting the gamut first. */
+declare function linearToSRGB(rgb: LinearRGB): SRGB;
+/** Tristimulus values straight to a displayable colour. */
+declare const xyzToSRGB: (xyz: XYZ) => SRGB;
+/** `#rrggbb`, for anything that draws. */
+declare const hexOf: (c: SRGB) => string;
+/** Hue in degrees, saturation and lightness each 0 to 1. The form a colour NAME is decided from. */
+declare function hslOf(c: SRGB): {
+  readonly h: number;
+  readonly s: number;
+  readonly l: number;
+};
+//#endregion
+export { LinearRGB, SRGB, fitGamut, hexOf, hslOf, linearToSRGB, xyzToLinear, xyzToSRGB };