@woosh/meep-engine 3.8.0 → 3.10.0

package/src/core/color/COLOR_REVIEW_2026_08_28.md

@@ -0,0 +1,779 @@
+# COLOR_REVIEW — `src/core/color`
+
+Date: 2026-08-28 · Reviewer: Claude (Opus 5) · Scope: every one of the 58 source files and 33 spec
+files under `src/core/color`, plus the CPU/GPU boundary with `src/shade/renderer/shader/chunk/color`.
+
+**Method.** Every source file was read in full. Claims that could be executed were executed: the
+package's own suite (`npx vitest run src/core/color` — **33 files, 158 tests, all passing**) plus six
+throwaway probe scripts run against the real modules (Appendix A). Every defect below marked
+*(reproduced)* has a printed failing value next to it; nothing in §2 is inferred from reading alone.
+Reachability was established by grepping actual `import ... from ".../<file>.js"` statements across
+`src/`, not by symbol name.
+
+Severity, following the `core/geom` reviews: **major** = wrong results, silent data loss, or a
+cross-cutting trap the caller cannot predict; **minor** = consistency/ergonomics gap with no
+correctness impact.
+
+---
+
+## 0. TL;DR
+
+The package is a **well-built colour-science library with a badly maintained perimeter**. The
+numerically hard parts — Lab, OkLab/OkHSV, PQ, ycxcz, the D65/CMF tables, ACES — are correct,
+carefully documented, and in several places better than the textbook (the D65 white point is derived
+from the actual matrix rows so linear white lands on `L* = 100, a* = 0, b* = 0` *exactly*, which I
+confirmed). The problems are all at the edges: the ingest path (`parse_color`/`hex2rgb`), the
+`Color` façade, the alpha channel, and the seams between approximation regimes.
+
+Five things worth acting on first:
+
+1. **`kelvin_to_rgb` has a 0.078 hard step in blue at exactly 2000 K** (§2.1 C1, reproduced). The
+   author already blended the 6600 K seam; the 2000 K seam was missed. Any temperature ramp bands
+   there.
+2. **`rgb_to_kelvin` is non-injective below 2000 K** — 800 K, 1500 K and 1999 K all return 1000 K
+   (§2.1 C2, reproduced). It is a consequence of C1 and cannot be fixed independently.
+3. **Alpha is silently dropped in five public entry points** — `Color.from_linear_to_sRGB`,
+   `from_sRGB_to_linear`, and all four `color_lighten/darken/saturate/desaturate` (§2.1 C5, C6,
+   reproduced). `color_lerp` handles alpha correctly, which makes the inconsistency worse, not better.
+4. **`Color.parse` accepts malformed input and produces garbage instead of throwing** — `#f00`
+   yields `b: NaN`, `0xFF8000FF` yields `r: -0.502` (§2.1 C3, C4, reproduced). This is the one
+   defect class that reaches user-authored data.
+5. **A third of the package is unreachable** (§1.4): 8 files no module imports at all, another 12
+   reachable only from their own tests. Including `prototype_kelvin_to_rgb.js`, a dev scratch script
+   that calls `document.body.append` at import time from inside a core library folder.
+
+The single largest *structural* issue is not a bug: **nothing in the package records whether a
+`Color` holds linear or encoded values** (§3.4). `color_lighten` calls `linear_srgb_to_okhsv` on
+whatever `Color` you hand it, and `Color.parse("#808080")` produces encoded values. Both are
+reasonable; together they are wrong, silently.
+
+---
+
+## 1. Overall shape of the package
+
+### 1.1 Inventory
+
+| | |
+|---|---|
+| Source files / LOC | 58 / 3,263 (544 of which are tabulated data) |
+| Spec files / LOC / tests | 33 / 2,090 / 158 — all passing |
+| Directories | 16 — `PQ` `YCbCr` `YCoCg` `colormap` `hex` `hsv` `hunt` `illuminant` `kelvin` `lab` `oklab` `operations` `sRGB` `tonemap` `xyz` `ycxcz` |
+| Entry point | none — no barrel, consistent with the rest of `core` (no `index.js` exists anywhere under `src/core`). Not a gap. |
+
+### 1.2 The three layers that are actually there
+
+The directory listing suggests one flat namespace; the code is really three layers with different
+authors, ages, and quality levels.
+
+**Layer A — the modern colour-science core.** `lab/`, `ycxcz/`, `oklab/`, `PQ/`, `illuminant/`,
+`xyz/`, `tonemap/`, `colormap/`. Snake-case, out-param-first, offset-aware, heavily documented with
+the *reason* for each choice, not just the formula. [illuminant/D65_TRISTIMULUS_XYZ.js](illuminant/D65_TRISTIMULUS_XYZ.js)
+and [lab/xyz_to_lab.js](lab/xyz_to_lab.js) are the best files in the package: they explain why the
+white point is derived rather than quoted, and what breaks if you mix sources. This layer exists
+because of two consumers — the ꟻLIP image-difference metric (`engine/graphics/texture/sampler/compare/flip/`)
+and the AVIF encoder — and it shows: it is exactly as complete as those two need and no more.
+
+**Layer B — the legacy CSS/UI layer.** [Color.js](Color.js), [parse_color.js](parse_color.js),
+`hex/`, `hsv/`, [int2rgb.js](int2rgb.js), [rgb2uint24.js](rgb2uint24.js), [rgb2uint32.js](rgb2uint32.js).
+`name2name` naming, object-returning, allocating, 0–255 units, no offsets. This is the layer with
+essentially all of §2's defects. It has 29 non-spec importers (via `Color.js`) and is the most-used
+and least-maintained part of the package.
+
+**Layer C — orphan experiments.** `hunt/`, `kelvin/`, `YCbCr/`, `YCoCg/`,
+[sRGB/sRGB_cmf.js](sRGB/sRGB_cmf.js), [oklab/find_gamut_intersection.js](oklab/find_gamut_intersection.js),
+[illuminant/D65_spd_analytical.js](illuminant/D65_spd_analytical.js). Each is a competent
+implementation of something nobody calls (§1.4).
+
+### 1.3 Where the boundary is drawn wrong
+
+Three placement problems, in descending order of how much they cost:
+
+- **`operations/` sits above `Color`, but `Color` sits above nothing.** `Color.js` imports
+  `hsv2rgb_float`, `rgb2hsv`, `rgb2uint24/32`, `rgb_to_luminance`, `parse_color`, `rgb2hex`,
+  `linear_to_sRGB`, `sRGB_to_linear` — eight modules. Meanwhile `operations/` imports `Color`. So
+  the dependency graph is `operations → Color → {8 leaf modules}`, and the OkHSV operations live
+  *outside* the class while HSV/HSL/HCL/HSI setters live *inside* it. There is no principle
+  separating the two sets; `setHSV` could as easily have been `color_set_hsv`.
+- **`hunt/` contains the wrong Hunt.** [hunt/xyz_to_hpe.js](hunt/xyz_to_hpe.js) is the
+  Hunt–Pointer–Estévez *cone response matrix*; the actual Hunt-*effect* function is
+  [lab/lab_apply_hunt_adjustment.js](lab/lab_apply_hunt_adjustment.js). The latter carries an
+  explicit disclaimer — *"Unrelated to `xyz_to_hpe`"* — which is the tell that the directory name is
+  doing damage. `xyz_to_hpe` has zero importers; it belongs in `xyz/` or nowhere.
+- **`colormap/` holds one unused LUT.** Magma, base64-encoded, well documented, zero importers,
+  while the GPU side ships four different LUTs (inferno/plasma/turbo/viridis) that the CPU cannot
+  reach. The directory is right; the contents are the wrong four-fifths.
+
+### 1.4 Reachability
+
+Established by grepping real import statements. This is the most actionable single table in the
+review.
+
+**Unreferenced by anything, including their own tests (8 files):**
+
+| File | Note |
+|---|---|
+| [kelvin/prototype_kelvin_to_rgb.js](kelvin/prototype_kelvin_to_rgb.js) | **Side-effecting dev script.** Appends a canvas to `document.body` and `console.log`s at *import* time. Reaches into `engine/graphics` and `view/elements` from `core/`, inverting the layering. Delete or move to a playground. |
+| [oklab/find_gamut_intersection.js](oklab/find_gamut_intersection.js) | 100 lines of correct Halley-iteration gamut math. Its whole purpose is gamut clipping, and no clipper exists (§4.3). |
+| [int2rgb.js](int2rgb.js) | Third copy of uint24 unpacking (§5.1). |
+| [hunt/xyz_to_hpe.js](hunt/xyz_to_hpe.js) | Matrix verified correct against the standard HPE matrix. |
+| [illuminant/D65_spd_analytical.js](illuminant/D65_spd_analytical.js) | Sole importer of `planckian_radiance` → a dead 2-file subtree. |
+| [operations/color_lighten.js](operations/color_lighten.js) · [color_saturate.js](operations/color_saturate.js) · [color_desaturate.js](operations/color_desaturate.js) | Untested *and* unused; `color_darken` is the only one of the four with a spec. |
+
+**Reachable only from their own spec (12 files):** [PQ/PQ_to_linear.js](PQ/PQ_to_linear.js) (the
+encoder only encodes), `YCbCr/*` (2), `YCoCg/*` (2), [colormap/MAGMA_LUT.js](colormap/MAGMA_LUT.js),
+[kelvin/rgb_to_kelvin.js](kelvin/rgb_to_kelvin.js), [oklab/oklab_to_xyz.js](oklab/oklab_to_xyz.js),
+[oklab/xyz_to_oklab.js](oklab/xyz_to_oklab.js), [operations/color_darken.js](operations/color_darken.js),
+[operations/color_lerp.js](operations/color_lerp.js), [rgb_to_rgbe9995.js](rgb_to_rgbe9995.js),
+[rgbe9995_to_rgb.js](rgbe9995_to_rgb.js), [sRGB/sRGB_cmf.js](sRGB/sRGB_cmf.js).
+
+**Load-bearing (≥3 non-spec importers):** `Color.js` (29), `sRGB/sRGB_to_linear.js` (5),
+`xyz/rgb_to_xyz.js` (4), `xyz/xyz_to_rgb.js` (4), `sRGB/linear_to_sRGB.js` (4),
+`operations/color_scale_okhsv_channel.js` (4), `oklab/okhsv_to_linear_srgb.js` (4),
+`illuminant/D65_TRISTIMULUS_XYZ.js` (3), `kelvin/kelvin_to_rgb.js` (3), `oklab/find_cusp.js` (3),
+`oklab/oklab_to_linear_srgb.js` (3), `rgb_to_luminance.js` (3).
+
+---
+
+## 2. Correctness
+
+### 2.1 Confirmed defects
+
+| # | Symbol | File | Defect | Sev |
+|---|---|---|---|---|
+| C1 | `kelvin_to_rgb` | [kelvin/kelvin_to_rgb.js:23](kelvin/kelvin_to_rgb.js) | Blue steps 0 → 0.0779 across 2000 K | major |
+| C2 | `rgb_to_kelvin` | [kelvin/rgb_to_kelvin.js](kelvin/rgb_to_kelvin.js) | All T < 2000 K collapse to 1000 K | major |
+| C3 | `hex2rgb` | [hex/hex2rgb.js:12](hex/hex2rgb.js) | 3-/4-digit hex silently yields `NaN` | major |
+| C4 | `parse_color` | [parse_color.js:68](parse_color.js) | Numeric branch unmasked; negative channels | major |
+| C5 | `Color.from_*` | [Color.js:788](Color.js) | Drop alpha; never fire `onChanged` | major |
+| C6 | `color_lighten` &c. | [operations/color_scale_okhsv_channel.js](operations/color_scale_okhsv_channel.js) | Drop alpha (but `color_lerp` keeps it) | major |
+| C7 | `rgb2uint32` | [rgb2uint32.js:17](rgb2uint32.js) | Returns signed int32, not uint32 | minor |
+| C8 | `Color.setHCL` / `setHSI` | [Color.js:332](Color.js) | Emit out-of-gamut, unclamped, undocumented | minor |
+| C9 | `Color.multiplyScalar` | [Color.js:702](Color.js) | Scales alpha along with RGB | minor |
+| C10 | `Color.fromUint` | [Color.js:497](Color.js) | `>> 16` with no `& 0xFF` | minor |
+| C11 | `parse_color` | [parse_color.js:6](parse_color.js) | Regexes unanchored | minor |
+| C12 | `linear_srgb_to_okhsv` | [oklab/linear_srgb_to_okhsv.js:43](oklab/linear_srgb_to_okhsv.js) | Unguarded divide by zero chroma | minor |
+| C13 | `color_lighten` | [operations/color_lighten.js](operations/color_lighten.js) | Multiplicative — cannot lighten black | minor |
+| C14 | `rgb_to_luminance` | [rgb_to_luminance.js](rgb_to_luminance.js) | Doc conflates luminance with luma | minor |
+| C15 | `Color.hash` | [Color.js:563](Color.js) | Ignores alpha | minor |
+| C16 | `D65_spd_tabulated` | [illuminant/D65_spd_tabulated.js](illuminant/D65_spd_tabulated.js) | Boundary logic asymmetric with its CMF twin | minor |
+
+---
+
+#### C1 · `kelvin_to_rgb` — 0.078 discontinuity in blue at exactly 2000 K · **major** · *(reproduced)*
+
+`approximate_regime_red` gates the blue channel with `t <= 20 ? 0 : clamp01(...)`
+([kelvin/kelvin_to_rgb.js:23](kelvin/kelvin_to_rgb.js)). The logarithmic fit it guards does not
+approach 0 at `t = 20`; it approaches 0.0779. So blue jumps by a step ~20× the 8-bit quantum:
+
+```
+1999.99 K  →  1.000000, 0.544072, 0.000000
+2000.00 K  →  1.000000, 0.544074, 0.000000
+2000.01 K  →  1.000000, 0.544076, 0.077917   ← +0.0779 in one 0.01 K step
+```
+
+The 1000 K seam is clean (the blackbody-fade hue is locked to the value the red regime produces at
+`t = 10`, and it matches to 6 decimals — verified), and the 6600 K seam is explicitly blended over
+`t ∈ [65, 67]`. So the author already understood this class of problem and solved it twice; this
+third seam was simply not noticed.
+
+**Fix:** either blend across `t ∈ [20, 20.x]` the way the 6600 K seam is blended, or — better —
+shift the fit so the blue term is continuous at its own gate. The seam is where the physical
+Draper-adjacent region hands over to the fit, so a short blend window matches the existing house
+style. Add a spec that walks temperature in fine steps and asserts a bounded first difference on
+each channel; the existing [kelvin/kelvin_to_rgb.spec.js](kelvin/kelvin_to_rgb.spec.js) has 9 tests
+and none of them samples across a seam.
+
+#### C2 · `rgb_to_kelvin` collapses everything below 2000 K to 1000 K · **major** · *(reproduced)*
+
+The solver bisects on the ratio `b / r`. Because C1 pins blue to exactly 0 for all `t <= 20`, that
+ratio is 0 across the entire 0–2000 K span, so the bisection has no gradient to follow and always
+walks to the lower bound:
+
+```
+kelvin_to_rgb(T) → rgb_to_kelvin:
+   800 K → 1000      1500 K → 1000      1999 K → 1000
+  1000 K → 1000      1800 K → 1000      2000 K → 1000
+  2100 K → 2100      2500 K → 2500      (correct from here up)
+```
+
+Candle-light (~1900 K) and tungsten (~2400 K) straddle the break, so this is not an academic range.
+Two secondary issues in the same file: the green channel is never read, so any colour with a matching
+`b/r` maps to the same temperature regardless of how far it is from the Planckian locus; and the
+JSDoc promises "approx 1000 to 40000" while the function returns `0` for black.
+
+**Fix:** C1 first — the collapse is downstream of it. Then either document the ±0.4 K `epsilon` and
+the 2000 K floor honestly, or switch to a proper CCT estimator (McCamy's approximation over CIE
+1960 `uv`, or Robertson) which needs no solver, uses all three channels, and has a well-defined
+Duv-based validity domain.
+
+#### C3 · `hex2rgb` silently produces `NaN` for short-form hex · **major** · *(reproduced)*
+
+[hex/hex2rgb.js](hex/hex2rgb.js) slices fixed byte offsets and never validates length, so the two
+most common CSS hex forms decode to nonsense:
+
+```
+hex2rgb('#f00')            → { r: 240, g: 0, b: NaN, a: 255 }
+parse_color('#f00')        → [ 240, 0, NaN, 1 ]
+```
+
+`Color.parse('#f00')` then reaches `set()`, whose `assert.notNaN` throws — but with a message about
+a NaN channel, pointing at `Color.js`, five frames away from the actual cause. And that only holds
+while asserts are live: the guard is `assert`, not a validating parser, so any build that strips
+asserts propagates `NaN` downstream.
+
+**Fix:** handle `#RGB` and `#RGBA` by expansion (`f00` → `ff0000`), and throw a message naming the
+offending string for anything that is not 3/4/6/8 hex digits. `rgb2hex` should grow the matching
+alpha form at the same time (§4.1).
+
+#### C4 · `parse_color` numeric branch is unmasked and unvalidated · **major** · *(reproduced)*
+
+[parse_color.js:68](parse_color.js) does `r = c >> 16` with no `& 0xFF` and no range check.
+For any value with bit 23 set, the shift is signed:
+
+```
+parse_color(0xFF8000)      → [ 255, 128,   0, 1 ]   ✓
+parse_color(0xFF8000FF)    → [ -128,  0, 255, 1 ]   ✗ (a plausible RGBA literal)
+parse_color(-1)            → [  -1, 255, 255, 1 ]   ✗
+Color.parse(0xFF8000FF)    → { r: -0.502, g: 0, b: 1, a: 1 }
+```
+
+No assert fires, because `-0.502` is a finite number — `Color` explicitly supports out-of-`[0,1]`
+values for HDR, so the very feature that makes the class useful is what lets this through silently.
+`Color.parse`'s own JSDoc advertises `Color.parse(0xFF00FF)`, so numeric input is a documented path.
+
+**Fix:** mask all three channels, and reject values outside `[0, 0xFFFFFF]` with a thrown error
+rather than wrapping. Decide explicitly whether `0xAARRGGBB`-style 32-bit input is supported; today
+it is neither supported nor rejected.
+
+#### C5 · `Color.from_linear_to_sRGB` / `from_sRGB_to_linear` drop alpha and skip `onChanged` · **major** · *(reproduced)*
+
+```js
+Color.from_linear_to_sRGB(new Color(0.5, 0.5, 0.5, 0.25))
+// → { r: 0.735, g: 0.735, b: 0.735, a: 1 }     alpha 0.25 lost
+
+const out = new Color(); let fired = 0; out.onChanged.add(() => fired++);
+Color.from_sRGB_to_linear(new Color(0.5, 0.5, 0.5), out);
+// → out mutated to 0.214…, fired === 0        listeners never notified
+```
+
+Two distinct causes, one call site. The underlying `linear_to_sRGB(output, 0, input, 0)` writes
+indices 0–2 only, so with the default `output = new Color()` alpha stays at the constructor's `1`
+and the caller's alpha is discarded. And because the write goes through `Color`'s numeric index
+setters (`set 0(v) { this.r = v }`), it bypasses `set()` entirely — no equality check, no
+`onChanged.send8`. Any observer bound to that `Color` (the editor's `ColorEditor`, a material
+uniform, a signal-driven binding) sees stale state while the object has already changed. This is the
+most dangerous defect in the review because it is *silent on both sides*.
+
+**Fix:** in both statics, copy `input.a` to `output` and route the write through `output.set(...)`
+rather than raw index assignment. The same pattern is used by `okhsv_to_linear_srgb(result, …)` in
+`color_scale_okhsv_channel` — safe there only because the target is freshly allocated, which is a
+precondition nothing states. Worth a comment on the index setters warning that writing a `Color`
+positionally is an unobserved mutation.
+
+#### C6 · The four `operations/` scale functions drop alpha · **major** · *(reproduced)*
+
+```js
+color_lighten(new Color(0.2, 0.4, 0.6, 0.3), 0.5)
+// → { r: 0.333, g: 0.667, b: 1.0, a: 1 }        alpha 0.3 → 1
+```
+
+[operations/color_scale_okhsv_channel.js](operations/color_scale_okhsv_channel.js) allocates
+`new Color()` and never touches `.a`. Its sibling [color_lerp](operations/color_lerp.js) *does*
+interpolate alpha (`r.a = lerp(color_0.a, color_1.a, _t)`), so within a five-file directory two
+different alpha policies coexist with nothing marking the difference. Fix: `result.a = input.a` in
+`color_scale_okhsv_channel`; it fixes all four callers at once.
+
+#### C7 · `rgb2uint32` returns a signed int32 · **minor**
+
+`(partial << 8) | (_a & 0xFF)` ([rgb2uint32.js:17](rgb2uint32.js)) overflows into the sign bit
+for any red ≥ 0x80: `Color.white.toUint32() === -1`. This is **already known** —
+[Color.spec.js:51](Color.spec.js) documents it and normalises with `>>> 0` in every assertion,
+and `deserialize_scene.js` reads the value back through `>>>`. So it is not a live bug; it is a
+method whose name promises a `uint32` and whose contract is "an int32 you must convert". Appending
+`>>> 0` to the return is behaviour-preserving for every existing consumer (both already normalise)
+and removes the wart. Low risk, worth doing.
+
+#### C8 · `setHCL` and `setHSI` emit unclamped out-of-gamut values · **minor** · *(reproduced)*
+
+```
+setHCL(0,   1, 0.5) → { r:  1.2,   g: 0.2,  b:  0.2  }
+setHCL(1/3, 1, 0.5) → { r: -0.09,  g: 0.91, b: -0.09 }
+setHSI(0,   1, 0.5) → { r:  1.5,   g: 0,    b:  0    }
+```
+
+For a class documented as "0 to 1 for SDR" this is surprising, and `setHSL`/`setHSV` — verified
+correct against CSS at all six primaries — do not behave this way. `setHSI` additionally carries the
+author's own `NOTE: I'm not sure if the implementation is correct`. Neither has a spec.
+Both switch statements also leave `r`/`g`/`b` as bare `let` with no `default` case; the sextant range
+makes that unreachable today, but it is one refactor away from `undefined` propagation.
+
+**Fix:** decide per method whether the contract is "clamped to gamut" or "unbounded, caller clamps",
+document it, and add a spec. If `setHSI` cannot be validated against a reference, deleting it is a
+better outcome than shipping a method whose docstring says it might be wrong.
+
+#### C9 · `multiplyScalar` scales alpha · **minor** · *(reproduced)*
+
+`new Color(0.5,0.5,0.5,1).multiplyScalar(0.5)` → `{ …, a: 0.5 }`. Defensible as "scale the 4-vector",
+but the overwhelming use of a scalar multiply on a colour is exposure/tint adjustment, where fading
+transparency as a side effect is a bug in the caller that looks like a bug in the engine. `multiply`
+(component-wise) has the same behaviour. At minimum document it; better, add `multiplyRGB`.
+
+#### C10 · `Color.fromUint` does not mask the red byte · **minor** · *(reproduced)*
+
+`value >> 16` with no `& 0xFF` ([Color.js:501](Color.js)). Round-trips with `toUint()` correctly
+(uint24 never sets bit 31), but `fromUint(0xFF8000FF)` throws `Expected -128 >= 0` from inside
+`uint8_to_float` — an error message that names neither the method nor the input. `int2rgb` masks all
+three channels; `parse_color` masks two of three; `fromUint` masks two of three. Three copies, three
+behaviours (§5.1).
+
+#### C11 · `parse_color` regexes are unanchored · **minor** · *(reproduced)*
+
+`parse_color('background: rgb(1,2,3) !important')` → `[1, 2, 3, 1]`. Lenient parsing of a
+colour literal is a reasonable choice, but it is not the documented one ("Parses most CSS-format
+colors"), and it means a malformed string that happens to contain a colour never surfaces as an
+error. Anchor with `^…$` after trimming, or state the substring-scan behaviour in the docstring.
+
+#### C12 · `linear_srgb_to_okhsv` divides by an unguarded chroma · **minor**
+
+[oklab/linear_srgb_to_okhsv.js:43](oklab/linear_srgb_to_okhsv.js) computes `a_ = Lab[1] / C`
+with an early return only for `L === 0`, not `C === 0`. In practice exact-zero chroma appears
+unreachable from the sRGB path — the three OkLab row sums differ in their last bits, so neutrals
+land at `C ≈ 1e-7` rather than 0 — but the consequence of that near-miss is itself worth knowing:
+
+```
+linear rgb (1,1,1)       → okhsv (0.24965…, 1.0348e-7, 1.0000000270)
+linear rgb (0.5,0.5,0.5) → okhsv (0.24965…, 1.0348e-7, 0.7600066)
+```
+
+Every neutral gets the same **arbitrary hue 0.2496** and a saturation of `1e-7` instead of `0`. That
+is what makes `color_lerp(white, red)` behave (it interpolates from a stable, if meaningless, hue) —
+but it is load-bearing accident, not design. Note also `v = 1.0000000270 > 1`, and the OkHSV
+round-trip of white returns `(1.00000007, 0.99999998, 0.99999974)`: the `operations/` functions do
+not clamp their output, so they can hand back marginally out-of-`[0,1]` colours.
+
+**Fix:** early-return `s = 0, h = 0` when `C` is below a small epsilon (not just when it is exactly
+0), and clamp the final RGB in `color_scale_okhsv_channel`.
+
+#### C13 · `color_lighten` cannot lighten black · **minor** · *(reproduced)*
+
+`color_lighten(new Color(0,0,0), 1)` → `{0,0,0}`. The operation is `v * (1 + amount)`, and `0`
+is a fixed point. Symmetrically `color_darken` cannot darken further once `v` hits 0, which is
+fine, but the lighten direction failing at the most common input (black) is a design gap.
+`v + amount * (1 - v)` is the usual formulation and has no fixed point at either end. Whatever is
+chosen, this needs a spec — three of the four operations have none at all.
+
+#### C14 · `rgb_to_luminance` documents itself as space-agnostic · **minor**
+
+The docstring says *"Red component (linear or gamma-corrected)"* and the function is named
+`…_luminance`. Applied to linear values these coefficients give **luminance**; applied to encoded
+values they give **luma** (`Y′`). Both are legitimate quantities and both use these numbers by
+definition, but they are not interchangeable, and the doc invites callers to treat them as such. The
+GPU twin gets this right — `chunk_rgb_to_luminance` says *"Input color must be in linear space to get
+correct results"*. Align the JS doc with it. (See also §3.5 on the coefficient precision split.)
+
+#### C15 · `Color.hash()` ignores alpha · **minor** · *(reproduced)*
+
+`hash()` delegates to `toUint()` (24-bit, RGB only) while `equals()` compares all four channels, so
+colours differing only in alpha share a hash. The `equals ⇒ same hash` contract still holds, so this
+is correct-but-lossy rather than broken; using `toUint32()` would make it exact at no cost.
+
+#### C16 · `D65_spd_tabulated` and `xyz_cmf_tabulated` guard their edges differently · **minor**
+
+[D65_spd_tabulated](illuminant/D65_spd_tabulated.js) uses `<=` / `>=` and then re-tests for equality
+inside the rejection branch; [xyz_cmf_tabulated](xyz/xyz_cmf_tabulated.js) uses `<` / `>` and clamps
+`i1`. Both produce correct values; they are two solutions to the same problem sitting in sibling
+files, and one asserts its input while the other does not. Pick one shape.
+
+### 2.2 Verified correct
+
+Recorded so the next reviewer does not re-derive it. Each was checked by execution, not by reading.
+
+- **sRGB OETF/EOTF** round-trip to a maximum error of `2.2e-11` over 100,001 samples of `[0,1]`;
+  breakpoints `0.0031308` / `0.04045` are mutually consistent; negative and >1 inputs both behave.
+- **`rgb_to_xyz` → `xyz_to_lab`** maps linear white to `(100, 0, 0)` **exactly**, and black to
+  `(0,0,0)`. This is the payoff of deriving `D65_TRISTIMULUS_XYZ` from the matrix rows and it works.
+  `xyz_to_ycxcz` lands within `5.6e-14` of the same, as expected.
+- **YCbCr** Rec.709 coefficients re-derived from `Kr = 0.2126 / Kb = 0.0722`: forward and inverse
+  both match to 4 dp. **YCoCg** forward/inverse are exact algebraic inverses (verified symbolically).
+  **ycxcz ↔ xyz** is an exact inverse.
+- **PQ** OETF/EOTF round-trip to ~1e-15 relative across `[0, 1]`; the 203-nit normalisation is
+  correctly applied by the one real consumer (`avif/encoder_worker.js`). The `PQ_constants.js`
+  docstring's warning about "the classic way this round-trip ends up off by a factor of ~49" is
+  earned — see §3.5 for where the engine does still disagree with itself.
+- **rgbe9995** round-trips `[1,1,1]`, `[0.5,0.25,0.125]`, `[10,5,0]` exactly and `[0.001,0,0]` to
+  0.05%; the shared-exponent crush at `[100000,1,1]` is inherent to the format. Both files are
+  marked `TODO unverified` — that TODO can be retired.
+- **`xyz_to_hpe`** matches the standard Hunt–Pointer–Estévez matrix; in-place safe.
+- **`setHSL`** matches CSS `hsl()` at all six primaries and at neutral.
+- **In-place safety** claimed by `tonemap_aces`, `lab_apply_hunt_adjustment`, `rgb_to_xyz`,
+  `xyz_to_rgb`, `xyz_to_hpe` holds — all read their inputs before the first write.
+- **Frozen constants** (`Color.red` &c.) do throw on mutation under module strict mode. Note the
+  failure is state-dependent: `Color.red.set(1,0,0,1)` returns silently via `set()`'s no-change
+  early return, while `Color.red.setA(0.5)` throws `TypeError`. Worth a one-line comment.
+
+---
+
+## 3. Consistency
+
+### 3.1 Seven calling conventions for one package
+
+This is the package's largest consistency cost, and unlike naming it is not fixable by rename alone.
+
+| Convention | Members |
+|---|---|
+| `(out, out_off, in, in_off)` | `linear_to_sRGB`, `sRGB_to_linear`, `xyz_to_lab`, `xyz_to_ycxcz`, `ycxcz_to_xyz`, `lab_apply_hunt_adjustment`, `tonemap_aces`, `lab_distance_hyab` (as `(a, a_off, b, b_off)`) |
+| `(out, in)` — no offsets | `rgb_to_xyz`, `xyz_to_rgb`, `xyz_to_hpe` |
+| `(out, out_off, …scalars)` | `rgb_to_ycocg`, `ycocg_to_rgb`, `kelvin_to_rgb`, `rgbe9995_to_rgb` |
+| `(out, …scalars)` — no offset | `xyz_to_oklab`, `oklab_to_xyz`, `linear_srgb_to_oklab`, `oklab_to_linear_srgb`, `linear_srgb_to_okhsv`, `okhsv_to_linear_srgb`, `find_cusp`, `xyz_cmf_wyman`, `xyz_cmf_tabulated`, `sRGB_cmf` |
+| `(…scalars) → new object` | `hsv2rgb`, `hsv2rgb_float`, `rgb2hsv`, `hex2rgb`, `int2rgb` |
+| `(…scalars) → scalar` | `linear_to_PQ`, `PQ_to_linear`, `convert_channel_*`, `rgb_to_luminance`, `toe`, `toe_inv`, `compute_max_saturation`, `find_gamut_intersection`, `D65_spd_*`, `planckian_radiance`, `rgb_to_YCbCr_uint24`, `YCbCr_to_rgb_uint24`, `rgb_to_rgbe9995`, `rgb2uint24`, `rgb2uint32`, `rgb2hex` |
+| `(Color, …) → new Color` | `color_lerp`, `color_lighten`, `color_darken`, `color_saturate`, `color_desaturate`, `color_scale_okhsv_channel` |
+
+The split is not even directory-clean. `xyz/` holds both `rgb_to_xyz(out, in)` and
+`xyz_cmf_wyman(out, nm)`. `oklab/` holds `(out, scalars)` conversions next to
+`find_gamut_intersection(a,b,L1,C1,L0) → number`. Chaining across two conventions requires a
+temporary and an offset the caller has to remember is *not* there:
+
+```js
+rgb_to_xyz(xyz, rgb);            // no offsets
+xyz_to_lab(lab, 0, xyz, 0);      // offsets
+lab_apply_hunt_adjustment(lab, 0, lab, 0);
+```
+
+— which is real code from `flip_compute_color_difference.js`.
+
+**Recommendation:** the `(out, out_off, in, in_off)` form is the most capable and is what the newest
+and most-used code uses; treat it as the target. The `(out, …scalars)` form is legitimate where the
+inputs genuinely are not a contiguous triple (`kelvin_to_rgb`, the CMFs). What has no defence is
+`(out, in)` without offsets on `rgb_to_xyz`/`xyz_to_rgb` — the two most-imported conversions in the
+package (4 non-spec importers each) — and the allocating object-returning Layer-B set. Note this is
+the same finding the `core/geom` review raised as *"API shape: parameter order, output-argument
+placement, calling conventions"*; the same disease, one directory over.
+
+### 3.2 Units are not encoded in names or checked at boundaries
+
+| Unit | Members |
+|---|---|
+| `[0,1]` float | `Color`, `hsv2rgb_float`, `sRGB_*`, all of `oklab/`, `rgb2uint24/32` inputs |
+| `[0,255]` | `hsv2rgb`, `rgb2hex`, `hex2rgb`, `int2rgb`, `rgb_to_YCbCr_uint24`, `YCbCr_to_rgb_uint24` |
+| **mixed within one value** | `parse_color` returns `[0-255, 0-255, 0-255, 0-1]` — RGB in bytes, alpha normalised |
+| `L* ∈ [0,100]` | `xyz_to_lab`, `xyz_to_ycxcz` |
+| `1.0 = 10000 nits` | `PQ/*` (documented loudly, and correctly) |
+| Kelvin / Kelvin÷100 | `kelvin_to_rgb` public vs its three private regime helpers |
+
+`hsv2rgb` and `hsv2rgb_float` differ *only* in output scale, and the byte version is the one with
+the unsuffixed name — so the default-looking call is the non-default unit. `parse_color`'s mixed
+return is the most surprising: `Color.parse` compensates by dividing three of four elements by 255,
+which is exactly the kind of knowledge that should not live in the caller.
+
+### 3.3 Naming
+
+- **`2` vs `to`.** `hsv2rgb`, `rgb2hsv`, `rgb2hex`, `hex2rgb`, `int2rgb`, `rgb2uint24`, `rgb2uint32`
+  (Layer B) against `rgb_to_xyz`, `xyz_to_lab`, `linear_to_PQ`, `rgb_to_ycocg`, … (Layers A/C).
+  Splits cleanly by age, which makes it a mechanical rename.
+- **sRGB casing.** `sRGB_to_linear` / `linear_to_sRGB` / `sRGB_cmf` against `linear_srgb_to_oklab` /
+  `oklab_to_linear_srgb` / `linear_srgb_to_okhsv`. Same token, two casings, adjacent directories.
+- **Directory casing.** `PQ`, `YCbCr`, `YCoCg`, `sRGB` uppercase; `colormap`, `hex`, `hsv`, `hunt`,
+  `illuminant`, `kelvin`, `lab`, `oklab`, `operations`, `tonemap`, `xyz`, `ycxcz` lowercase. Under
+  `YCoCg/` the functions are `rgb_to_ycocg` (lower) while under `YCbCr/` they are
+  `rgb_to_YCbCr_uint24` (mixed).
+- **Two files named `XYZ.spec.js`** — [xyz/XYZ.spec.js](xyz/XYZ.spec.js) and
+  [oklab/XYZ.spec.js](oklab/XYZ.spec.js) — and *three* tests all called `"to/from consistency"`
+  (those two plus [sRGB/sRGB.spec.js](sRGB/sRGB.spec.js)). A failure report naming
+  `XYZ.spec.js > to/from consistency` is genuinely ambiguous.
+- **`hunt/`** — see §1.3.
+
+### 3.4 The unstated linear-vs-encoded contract — the most consequential inconsistency
+
+Nothing in the package records which transfer function a value carries. Consider what a caller
+actually gets:
+
+- `Color.parse("#808080")` divides bytes by 255 → the `Color` holds **encoded** sRGB.
+- `color_lighten(that)` calls `linear_srgb_to_okhsv(hsv, input.r, input.g, input.b)` → treats it as
+  **linear**.
+- `Color.prototype.computeLuminance()` applies Rec.709 weights → correct only for **linear**.
+- `Color.prototype.lerpColors` interpolates raw channels → correct only for **linear**.
+- `kelvin_to_rgb`'s docstring explicitly says its output is **encoded** and warns you to convert
+  before mixing — the one place the distinction is stated.
+
+So the most common construction path yields encoded values and three of the class's own methods
+assume linear. Each individual choice is defensible; the combination is a silent, systematic error
+in the perceptual operations. It is not visible in tests because every `operations/` spec builds its
+inputs from raw floats rather than from `Color.parse`.
+
+**Recommendation:** this is the one issue worth a design decision rather than a patch. Either (a)
+declare `Color` to be linear, make `parse`/`toHex`/`toCssRGBAString` apply the transfer function, and
+fix the resulting fallout; or (b) keep `Color` encoded and have `operations/` decode on entry and
+re-encode on exit. (a) is the right answer for an HDR renderer and matches what `Color`'s own
+`@param {number} [r=0] Red from 0 to 1 for SDR` and the HDR-tolerant `set()` already imply; (b) is
+the smaller change. Either way, say so in `Color`'s class docstring, which currently says nothing.
+
+### 3.5 CPU and GPU disagree about the same constants
+
+`src/shade/renderer/shader/chunk/color/` reimplements much of this package in WGSL. Independent
+implementations are fine; independently drifting constants are not.
+
+| Quantity | CPU | GPU | Note |
+|---|---|---|---|
+| Rec.709 luma weights | `0.2126, 0.7152, 0.0722` ([rgb_to_luminance.js](rgb_to_luminance.js)) | `0.212639005871510, …` (`chunk_rgb_to_luminance`) | and `rgb_to_xyz` row 1 carries **20** digits of the same number. Three precisions, one quantity. |
+| **PQ / ST 2084 reference white** | **203 nits** (BT.2408, [PQ/PQ_constants.js](PQ/PQ_constants.js)) | **100 nits** (`chunk_eotf_st2084`) | **Real divergence.** Same engine, two SDR-white conventions; content encoded on one path and decoded on the other is off by 2.03×. |
+| sRGB OETF exponent | `0.4166666666666667` | `0.41666666666` | Harmless; still two spellings of `1/2.4`. |
+| `rgb_to_xyz` matrix | 20 significant digits | 16 | Same matrix, two roundings. |
+
+The PQ row is the one to act on. `PQ_constants.js` goes out of its way to document why folding a
+white point into the transfer function is dangerous — and the GPU chunk folds a *different* white
+point into it. Whichever is right, they must agree, and the constant should exist once.
+
+### 3.6 Documentation, asserts and tests are applied unevenly
+
+- **Docs.** Layer A files carry multi-paragraph rationale. Layer B files carry a bare `@param`
+  list, and `int2rgb.js` has no prose at all. `Color.js` — the most-imported file in the package —
+  documents index accessors that need no explanation and says nothing about colour space, HDR range,
+  the `onChanged` contract, or why the numeric index setters bypass `set()`. Its class JSDoc also
+  claims `@extends {Array.<number>}`, which is false (`Array.isArray(color) === false`).
+- **Asserts.** `planckian_radiance` and `D65_spd_tabulated` validate their scalar inputs;
+  `xyz_cmf_tabulated`, `xyz_cmf_wyman`, `linear_to_PQ`, `D65_spd_analytical` do not. `kelvin_to_rgb`
+  asserts, `rgb_to_ycocg` does not. No visible rule.
+- **`@author` / `@copyright`.** Present on `compute_max_saturation`, `find_cusp`,
+  `find_gamut_intersection`, `okhsv_to_linear_srgb`, `oklab_to_linear_srgb`, `oklab_to_xyz`,
+  `xyz_to_oklab`, `color_scale_okhsv_channel`, `PQ/*`; absent on `linear_srgb_to_okhsv`,
+  `linear_srgb_to_oklab`, `toe` — sitting in the same directory, from the same source.
+- **Tests.** 158 tests over 33 files, but the distribution is 21 for `Color` and 1 each for
+  `Okhsv.spec.js`, `YCbCr.spec.js`, `oklab/XYZ.spec.js`, `xyz/XYZ.spec.js`, `sRGB.spec.js`,
+  `compute_max_saturation.spec.js`. Six of the package's hardest files share six assertions between
+  them. §4.5 lists what is untested.
+
+---
+
+## 4. Prominent missing features and members
+
+### 4.1 Missing inverses and partners
+
+Every one of these has its opposite direction already present.
+
+| Present | Missing | Consequence |
+|---|---|---|
+| `xyz_to_lab` | **`lab_to_xyz`** | Lab is write-only. Nothing can move a colour *in* Lab and come back — the standard reason to go there. |
+| `xyz_to_hpe` | `hpe_to_xyz` | Cone-space adaptation is one-way. |
+| `rgb2hex` | alpha-aware `rgba2hex` | `hex2rgb` already **reads** `#RRGGBBAA`; the writer cannot produce it, and `Color.toHex()` silently drops alpha. |
+| `hsv2rgb` (0-255) | `rgb2hsv_uint8` | Asymmetric pair — one direction has both unit variants, the other has one. |
+| `Color.setHSL` | `Color.getHSL`, `Color.fromHSL` | `getHSV`/`fromHSV` exist; HSL has neither. |
+| `Color.setHCL` / `setHSI` | `getHCL` / `getHSI` | Write-only. |
+| `linear_srgb_to_okhsv` | `srgb_to_okhsv` (encoded input) | Every UI caller has encoded values (§3.4). |
+| `oklab` L/a/b | **OkLCh** (`oklab_to_oklch` / back) | OkLCh is the space CSS Color 4 exposes and the natural one for hue rotation; the package has OkHSV but not OkLCh. |
+| `toe` / `toe_inv` | **OkHSL** pair | Ottosson defines OkHSL alongside OkHSV; only OkHSV was ported. OkHSL is the better choice for lighten/darken (§4.3). |
+| `linear_to_PQ` | HLG (`linear_to_HLG` / back) | The other half of the HDR transfer-function pair. |
+
+### 4.2 Missing on `Color`
+
+`Color` is the package's public face (29 non-spec importers) and its surface has gaps a caller hits
+in the first hour:
+
+- **No `static fromUint` / `fromHex` / `setHex`** — `fromUint` and `parse` exist as instance
+  methods, but only `fromRGB`, `fromHSV`, `fromArray` and `parse` are static. Constructing from a
+  packed integer takes two lines.
+- **No arithmetic** beyond `multiply` / `multiplyScalar`: no `add`, `sub`, `addScaled`, `divide`.
+  Blending and accumulation — the two things an engine does most with colour — are absent.
+- **No instance `lerp(other, f)`**, only `lerpColors(a, b, f)` which writes into `this` from two
+  *other* colours. `Color.lerp(a,b,f) → Color` as a static is also missing.
+- **No `Color.gray(v)`**, no `Color.fromTemperature(k)` (despite `kelvin_to_rgb` existing), no
+  `Color.orange`/`grey` — the constant set stops at the six primaries plus black/white/transparent.
+- **No `clamp()` / `isInGamut()`**, despite three methods that can produce out-of-gamut values (C8)
+  and OkHSV round-trips that overshoot by ~1e-7 (C12).
+- **No space tag** (§3.4) — the single most valuable missing member.
+- **`onChanged` is allocated eagerly for every instance.** Measured: 500k `Color` allocations take
+  **71.7 ms** versus **17.9 ms** for an otherwise identical class without the `Signal` — a **4×**
+  construction cost paid by every caller, including the many that never subscribe. A lazily created
+  signal (or a `Color`/`ObservableColor` split) is the standard fix, and matters because `Color` is
+  used in per-particle and per-vertex paths.
+
+### 4.3 Missing spaces and operations
+
+- **No gamut clipping.** `find_gamut_intersection` — the exact primitive Ottosson provides *for*
+  gamut clipping — is present, correct, and imported by nothing. There is no `gamut_clip_preserve_chroma`
+  / `_project_to_lcusp` / `_adaptive_L0` entry point. This is the largest single missing feature: the
+  hard part is done and the 10-line wrapper that makes it usable is absent.
+- **No colour-difference metrics beyond HyAB.** No ΔE76, ΔE94, ΔE2000, or ΔE-OK. `lab_distance_hyab`
+  exists solely for ꟻLIP; anything wanting a perceptual "are these two colours the same" must
+  reimplement.
+- **No chromatic adaptation.** No Bradford / CAT02 / von Kries, and no white point other than D65.
+  `xyz_to_lab` hardcodes `D65_TRISTIMULUS_XYZ`, so D50 workflows (ICC, print, most JPEG/TIFF
+  metadata) are unreachable.
+- **No primaries other than sRGB/Rec.709.** No Display-P3, Rec.2020, ACEScg, or Adobe RGB matrices —
+  while the GPU side ships all four `CRM_FROM_*` conversion matrices. An HDR renderer that can encode
+  PQ (a Rec.2020-centric format) has no CPU-side way to get *into* Rec.2020.
+- **No BT.601 YCbCr.** The `YCbCr/` directory is Rec.709 only, so `engine/asset/loaders/image/jpeg/JpegImage.js`
+  carries its own inline BT.601 matrix (`1.402`, `-0.3441363`, `-0.71413636`, `1.772`) — the correct
+  coefficients for JPEG, which the package cannot supply.
+- **No `Color`-level gradient/palette type**, despite `color_lerp` and `MAGMA_LUT` both existing.
+
+### 4.4 CPU/GPU parity gaps
+
+Every one of these exists on the GPU and not on the CPU, which matters for CPU-side baking,
+thumbnailing, and test oracles:
+
+| GPU has | CPU has |
+|---|---|
+| ACES, AgX, BT.2390, Khronos PBR, PBR-neutral, Reinhard-luma, GT7 | **ACES only** |
+| inferno, plasma, turbo, viridis LUTs | **magma only** (and unused) |
+| iCtCp (+ ST 2084 pair) | PQ scalars only, no iCtCp |
+| LogLuv encode/decode | — |
+| P3↔Rec2020↔Rec709 matrices | — |
+| EV100 / exposure helpers | — |
+| Purkinje shift | — |
+
+### 4.5 Test gaps
+
+**33 of 58 source files have no spec.** The ones that matter:
+
+- **All of `oklab/`'s primitives** — `linear_srgb_to_oklab`, `oklab_to_linear_srgb`, `find_cusp`,
+  `toe`, `linear_srgb_to_okhsv`, `okhsv_to_linear_srgb` are covered only by two whole-pipeline
+  round-trip tests with 5 sample points between them. `find_gamut_intersection` has none at all.
+- **`xyz/rgb_to_xyz` and `xyz_to_rgb`** (4 non-spec importers each) are covered only by a single
+  mutual round-trip, which cannot catch a matrix that is wrong in both directions.
+- **`rgb_to_luminance`** — 3 non-spec importers, no spec.
+- **`rgb2uint24` / `rgb2uint32`** — tested only indirectly through `Color`.
+- **`ycxcz`, `YCoCg`, `PQ`** are covered only by combined round-trip specs; a systematically wrong
+  forward matrix with a matching inverse passes every one of them. Absolute reference values are
+  needed, not just inverses.
+- **No seam/monotonicity tests** anywhere — which is why C1 survived.
+- **No alpha tests** on any `operations/` function — which is why C6 survived.
+- **No allocation or performance guard** on `Color`.
+
+---
+
+## 5. Redundancies
+
+### 5.1 Three implementations of uint24 → RGB, with three different behaviours
+
+| Site | Red | Green | Blue |
+|---|---|---|---|
+| [int2rgb.js](int2rgb.js) | `(v >> 16) & 255` | masked | masked |
+| [Color.js:501](Color.js) `fromUint` | `v >> 16` **unmasked** | masked | masked |
+| [parse_color.js:68](parse_color.js) | `c >> 16` **unmasked** | masked | masked |
+
+`int2rgb` has no importers; the other two both carry C4/C10. Keep one (masked, validating), delete
+`int2rgb.js`, and route the other two through it.
+
+### 5.2 Hue wrapping copy-pasted four times, in two orders
+
+`Color.setHSL`, `setHCL` and `setHSI` all do `h % 1` then a negative fixup; `hsv2rgb_float` does the
+negative fixup *then* `% 1`. Both orders happen to be correct, which is why the divergence has
+survived. One `wrap01(h)` helper in `core/math` replaces all four.
+
+### 5.3 The HCL/HSI sextant switch is duplicated verbatim
+
+`setHCL` and `setHSI` contain **byte-identical** 30-line `switch (Math.floor(h_face))` blocks; only
+the `c`/`x` derivation above and the `m` offset below differ. `hsv2rgb_float` contains a third
+variant of the same sextant dispatch. One `hue_to_rgb_sextant(out, h_face, c, x)` collapses all
+three — and would have made C8's missing clamp a one-place fix.
+
+### 5.4 Two lerps with different semantics and no signpost
+
+`Color.prototype.lerpColors` interpolates raw channels linearly;
+[operations/color_lerp.js](operations/color_lerp.js) converts to OkHSV and interpolates hue along the
+shortest arc. Neither docstring mentions the other. A caller reaching for "blend two colours" will
+find whichever they grep first, and the results differ substantially at mid-`t`.
+
+### 5.5 Two D65 SPDs and two CMF sets, one of each dead
+
+- `D65_spd_tabulated` (used by the Mie scattering code) vs `D65_spd_analytical` (**0 importers**),
+  which is the sole importer of `planckian_radiance` → a dead two-file subtree.
+- `xyz_cmf_tabulated` (used) vs `xyz_cmf_wyman` (reachable only via `sRGB_cmf`, itself unused) →
+  a second dead two-file subtree.
+
+Keeping an analytic alternative alongside a tabulated one is defensible — the MBOIT chunk library
+sets that precedent. If that is the intent here, say so in the file header the way the MBOIT chunks
+do; today nothing marks them as deliberately-retained.
+
+### 5.6 `sRGB_cmf` documents itself as the wrong choice
+
+Its own docstring reads *"Prefer to integrate in XYZ space and then perform the conversion to sRGB"* —
+i.e. do not call this. It has no importers. It is a two-line composition of `xyz_cmf_wyman` and
+`xyz_to_rgb` that a caller can write inline. Deleting it also frees `xyz_cmf_wyman` for deletion or
+promotion.
+
+### 5.7 CPU/GPU duplication with drifting constants
+
+`rgb_to_xyz`, `xyz_to_rgb`, the OkLab pair, the sRGB OETF, ACES, rgbe9995, YCoCg and ST 2084 all
+exist twice (§3.5). The duplication is unavoidable — WGSL cannot import JS — but the *constants*
+need not be: a single generated source of truth for matrices and transfer-function coefficients
+would remove the 203-vs-100-nit divergence structurally rather than by vigilance. The AVIF work
+already generates normative constant tables into source (`feat(avif): generate the normative AV1
+constant tables`), so the mechanism exists in-repo.
+
+### 5.8 `prototype_kelvin_to_rgb.js`
+
+A dev visualisation script inside a core library directory. It executes at import time
+(`document.body.append`), imports from `engine/` and `view/` — inverting the `core/` layering — and
+would crash any non-DOM consumer that touched it. Delete it, or move it to a playground directory
+where side-effecting entry points are expected.
+
+### 5.9 Test-name collisions
+
+`xyz/XYZ.spec.js` and `oklab/XYZ.spec.js` — same filename, same suite name, plus `sRGB/sRGB.spec.js`
+sharing the test name `"to/from consistency"`. Rename to `rgb_xyz_roundtrip.spec.js`,
+`oklab_xyz_roundtrip.spec.js`, `srgb_transfer_roundtrip.spec.js`.
+
+---
+
+## 6. Suggested order of work
+
+Sequenced by risk-reduction per unit of effort; each step is independently shippable.
+
+1. **Alpha** — C5, C6. Two small edits (`result.a = input.a`, route through `set()`), removes a
+   whole class of silent data loss, and fixes the `onChanged` blind spot at the same time.
+2. **Ingest hardening** — C3, C4, C11. Make `parse_color`/`hex2rgb` reject what they cannot parse
+   instead of emitting `NaN` and negative channels. Add short-hex support while in there.
+3. **Kelvin seam** — C1, then C2 falls out. Add a monotonicity/continuity spec that sweeps
+   temperature; it is the test shape that would have caught this and is reusable for the 1000 K and
+   6600 K seams.
+4. **Decide the colour-space contract** (§3.4) and write it into `Color`'s class docstring. This is
+   a decision, not a patch, and everything in `operations/` depends on it.
+5. **Delete the dead perimeter** — §1.4's 8 unreferenced files (`prototype_kelvin_to_rgb.js` first),
+   §5.5's two dead subtrees, §5.6, §5.1's `int2rgb.js`. Roughly 400 lines, zero behavioural risk.
+   For anything deliberately retained, add the "kept on purpose, here's why" header.
+6. **Reconcile the PQ white point** with the GPU (§3.5) — a correctness issue that only shows up
+   across the CPU/GPU boundary and will be expensive to diagnose later.
+7. **Gamut clipping** (§4.3) — the highest-value missing feature, and most of it is already written.
+8. **Convention convergence** (§3.1, §3.2, §3.3) — mechanical, large, best done last and in one
+   sweep so the churn lands once. `rgb_to_xyz`/`xyz_to_rgb` gaining offsets is the highest-value
+   single change.
+
+---
+
+## Appendix A — reproduction
+
+Every *(reproduced)* claim above came from running the modules directly. To re-check, save as
+`probe.mjs` in the repo root and run `node probe.mjs`:
+
+```js
+import { Color } from './src/core/color/Color.js';
+import { kelvin_to_rgb } from './src/core/color/kelvin/kelvin_to_rgb.js';
+import { rgb_to_kelvin } from './src/core/color/kelvin/rgb_to_kelvin.js';
+import { parse_color } from './src/core/color/parse_color.js';
+import { hex2rgb } from './src/core/color/hex/hex2rgb.js';
+import { color_lighten } from './src/core/color/operations/color_lighten.js';
+
+const o = [0, 0, 0];
+for (const T of [1999.99, 2000, 2000.01]) {           // C1
+    kelvin_to_rgb(o, 0, T); console.log(T, o.map(x => x.toFixed(6)).join(', '));
+}
+for (const T of [800, 1500, 1999, 2100]) {            // C2
+    kelvin_to_rgb(o, 0, T); console.log(T, '->', rgb_to_kelvin(o, 0));
+}
+console.log(hex2rgb('#f00'));                          // C3  b: NaN
+console.log(parse_color(0xFF8000FF));                  // C4  r: -128
+console.log(Color.from_linear_to_sRGB(new Color(0.5, 0.5, 0.5, 0.25)).toJSON());  // C5  a: 1
+const out = new Color(); let fired = 0; out.onChanged.add(() => fired++);
+Color.from_sRGB_to_linear(new Color(0.5, 0.5, 0.5), out);
+console.log('onChanged fired:', fired);                // C5  0
+console.log(color_lighten(new Color(0.2, 0.4, 0.6, 0.3), 0.5).toJSON());          // C6  a: 1
+console.log(new Color(1, 1, 1, 1).toUint32());         // C7  -1
+const c = new Color(); c.setHCL(0, 1, 0.5); console.log(c.toJSON());              // C8  r: 1.2
+console.log(parse_color('background: rgb(1,2,3) !important'));                    // C11
+console.log(color_lighten(new Color(0, 0, 0), 1).toJSON());                       // C13 unchanged
+```
+
+Baseline for comparison: `npx vitest run src/core/color` → **33 files, 158 tests, all passing** as of
+this review. None of the defects above is caught by the existing suite.