@woosh/meep-engine 3.9.0 → 3.11.0

package/src/core/binary/utf8/utf8_encoded_length.js

@@ -0,0 +1,36 @@
+/**
+ * Number of bytes {@link utf8_encode_into} will write for `text`, excluding any terminator the
+ * caller adds.
+ *
+ * Exists so a caller can size or grow a buffer before encoding into it, which is what lets the
+ * encode itself be a single pass with no allocation.
+ *
+ * @param {string} text
+ * @returns {number}
+ *
+ * @copyright Company Named Limited (c) 2026
+ */
+export function utf8_encoded_length(text) {
+    const length = text.length;
+
+    let count = 0;
+
+    for (let i = 0; i < length; i++) {
+        const code = text.codePointAt(i);
+
+        if (code < 0x80) {
+            count += 1;
+        } else if (code < 0x800) {
+            count += 2;
+        } else if (code < 0x10000) {
+            count += 3;
+        } else {
+            count += 4;
+
+            // codePointAt consumed both halves of the surrogate pair
+            i++;
+        }
+    }
+
+    return count;
+}

package/src/core/color/COLOR_FIX_PLAN_2026_08_28.md

@@ -0,0 +1,417 @@
+# COLOR_FIX_PLAN — `src/core/color`
+
+Date: 2026-08-28 · Companion to [COLOR_REVIEW_2026_08_28.md](COLOR_REVIEW_2026_08_28.md) ·
+Findings are referenced by their review IDs (`C1`…`C16`, `§n`).
+
+Each step is independently shippable and ordered so that nothing later depends on a decision not yet
+made. Every step names the files it touches and the test that proves it.
+
+---
+
+## Scope corrections applied
+
+Four corrections to the review were supplied and are binding on this plan:
+
+| # | Correction | Effect on the plan |
+|---|---|---|
+| **R1** | Don't overload the `Color` class | No new methods on `Color`. All new behaviour ships as free functions (`color_*`). §4.2's "missing members" become **Phase 6 files**, not class methods. Existing methods stay where they are — this is an additive rule, not a migration mandate. |
+| **R2** | Colour-space tag refused; `Color` is a low-level class | The review's §3.4 recommendation (a) and (b) are both **dropped**. `Color` stays four floats plus alpha with no space metadata. The space contract moves to *function* names and docs instead — **Phase 3**. |
+| **R3** | Unused/unimported code is not suspect; meep is a library with downstream consumers | **No deletions anywhere.** Review §1.4, §5.5, §5.6 and §5.8 are struck as *deletion* items. Their real consequence inverts: unimported code is public API that no in-repo caller exercises, so defects in it are unguarded and its **missing specs move up in priority** (Phase 7). |
+| **R4** | `prototype*.js` are playgrounds, stripped at ship | `kelvin/prototype_kelvin_to_rgb.js` is **out of scope**. Its `document.body` side effect and `engine/`/`view/` imports are expected for that file class. |
+
+### Explicitly not doing
+
+- Deleting `int2rgb.js`, `sRGB_cmf.js`, `xyz_cmf_wyman.js`, `D65_spd_analytical.js`,
+  `planckian_radiance.js`, `find_gamut_intersection.js`, `xyz_to_hpe.js`, `MAGMA_LUT.js`, or any of
+  `operations/`. (R3)
+- Touching `prototype_kelvin_to_rgb.js`. (R4)
+- Adding a colour-space field, enum, or brand to `Color`. (R2)
+- Adding `add`/`sub`/`lerp`/`clamp`/`fromHex` &c. as `Color` methods. (R1)
+
+---
+
+## Conventions this plan introduces
+
+Two placement rules, so Phase 6 doesn't turn into a debate per file:
+
+- **`operations/`** — free functions whose *input* is a `Color`. Existing precedent:
+  `color_lerp`, `color_darken`, `color_scale_okhsv_channel`.
+- **`construct/`** — new directory; free functions that *produce* a `Color` from non-`Color` input
+  (`color_from_hex`, `color_from_uint24`, …). Keeps `operations/` meaning "transform", and keeps
+  factories out of the class per R1.
+
+Naming follows the newer Layer-A style throughout: `snake_case`, `color_*` prefix, verb after the
+noun (`color_from_hex`, not `hex_to_color`, so the whole family sorts together).
+
+---
+
+## Phase 1 — Major correctness
+
+> Every step here: **write the failing spec first**, then fix. All four are currently invisible to
+> the suite (33 files / 158 tests, all green).
+
+### Step 1 — Stop dropping alpha in the two `Color` sRGB statics · `C5` · major
+
+**Files:** [Color.js](Color.js) (`from_linear_to_sRGB` ~L788, `from_sRGB_to_linear` ~L801)
+
+**Do:**
+1. Convert into a local scratch triple, then write the result through `output.set(r, g, b, input.a)`.
+   This fixes both halves of C5 at once: alpha is carried, and the write goes through `set()` so
+   `onChanged` fires and the no-change short-circuit applies.
+2. Do **not** keep the positional `output[0] = …` path — that is the mechanism of the silent
+   mutation.
+
+**Test:** `Color.spec.js` — (a) alpha survives a round trip through both statics; (b) passing an
+existing `Color` as `output` fires `onChanged` exactly once with the correct old/new payload.
+
+**Why first:** `Color.onChanged` has live consumers — `engine/graphics/render/forward_plus/model/PointLight.js`,
+`SpotLight.js`, and `view/elements/ColorPickerView.js` all subscribe. Today a colour converted in
+place updates without notifying any of them.
+
+---
+
+### Step 2 — Stop dropping alpha in the four OkHSV operations · `C6` · major
+
+**Files:** [operations/color_scale_okhsv_channel.js](operations/color_scale_okhsv_channel.js)
+
+**Do:** add `result.a = input.a;` before the return. One line fixes `color_lighten`,
+`color_darken`, `color_saturate` and `color_desaturate` together, and brings them in line with
+`color_lerp`, which already interpolates alpha.
+
+**Test:** new `operations/color_scale_okhsv_channel.spec.js` asserting alpha passthrough; extend
+`color_darken.spec.js` with an alpha case.
+
+---
+
+### Step 3 — Make `hex2rgb` reject or expand short-form hex · `C3` · major
+
+**Files:** [hex/hex2rgb.js](hex/hex2rgb.js)
+
+**Do:**
+1. Branch on `hex.length`: accept `#RGB` (4) and `#RGBA` (5) by nibble expansion (`f` → `ff`),
+   plus the existing `#RRGGBB` (7) and `#RRGGBBAA` (9).
+2. Anything else → `throw new Error()` naming the offending string. Do not rely on the caller's
+   `assert.notNaN` — that guard is downstream, mislabels the cause, and disappears if asserts are
+   stripped from a build.
+
+**Test:** extend `hex/hex2rgb.spec.js` — `#f00` → `{255,0,0,255}`, `#f00a` → alpha `0xAA`,
+`#ff00` (4 digits *without* `#`-relative alpha intent), `#gg0000`, and `''` all throw.
+
+---
+
+### Step 4 — Mask and validate `parse_color`'s numeric branch · `C4` · major
+
+**Files:** [parse_color.js](parse_color.js) (~L66-70)
+
+**Do:**
+1. Mask all three channels (`(c >> 16) & 0xFF`), not two of three.
+2. Reject `c < 0 || c > 0xFFFFFF` with a thrown error. Decide and document explicitly whether
+   `0xAARRGGBB` is supported — today it is neither supported nor rejected, which is how
+   `0xFF8000FF` becomes `r: -0.502`.
+3. `Color`'s HDR tolerance means no assert downstream will ever catch this, so the check has to be
+   here.
+
+**Test:** `parse_color.spec.js` — `0xFF8000` decodes; `0xFF8000FF`, `-1`, `0x1000000` throw.
+
+---
+
+### Step 5 — Close the 2000 K seam in `kelvin_to_rgb` · `C1` · major
+
+**Files:** [kelvin/kelvin_to_rgb.js](kelvin/kelvin_to_rgb.js) (`approximate_regime_red`, ~L23)
+
+**Do:** the blue gate `t <= 20 ? 0 : clamp01(fit)` steps 0 → 0.0779 in one 0.01 K increment because
+the fit does not reach zero at its own gate. Pick one:
+- **(a) preferred** — shift/rescale the blue term so it is continuous at `t = 20`; or
+- **(b)** blend across a short window (`t ∈ [20, 21]`) using `inverseLerp` + `lerp`, mirroring the
+  existing `BLEND_MIN`/`BLEND_MAX` treatment of the 6600 K seam.
+
+(b) matches the file's established house style and is the lower-risk change; (a) is correct rather
+than papered over. The 1000 K seam already does the right thing (hue locked to the red regime's
+`t = 10` value, matching to 6 dp) and needs no change.
+
+**Test:** new `kelvin_seam.spec.js` — sweep 500 K…40000 K in fine steps, assert a bounded
+first difference per channel. This test shape catches all three seams and is the reason C1 survived
+9 existing tests.
+
+---
+
+### Step 6 — Restore injectivity to `rgb_to_kelvin` below 2000 K · `C2` · major
+
+**Files:** [kelvin/rgb_to_kelvin.js](kelvin/rgb_to_kelvin.js)
+
+**Do:** depends on Step 5 — the collapse is downstream of the flat `b/r === 0` region. After Step 5,
+re-measure. Then either:
+- **(a) minimal** — keep the bisection, verify it now resolves below 2000 K, and correct the JSDoc
+  (it promises "approx 1000 to 40000" but returns `0` for black); or
+- **(b) better** — replace with McCamy's approximation over CIE 1960 `uv`, or Robertson. No solver,
+  uses all three channels (the current version never reads green, so any colour with a matching
+  `b/r` maps to the same temperature regardless of distance from the Planckian locus), and has a
+  defined Duv validity domain.
+
+**Test:** extend `rgb_to_kelvin.spec.js` — round-trip `kelvin_to_rgb → rgb_to_kelvin` at 800, 1200,
+1500, 1800, 1999, 2100, 2700, 5000, 6500, 20000 K within tolerance.
+
+---
+
+## Phase 2 — Minor correctness
+
+Small, independent, one commit each.
+
+| Step | Finding | File | Do | Test |
+|---|---|---|---|---|
+| **7** | `C7` | [rgb2uint32.js](rgb2uint32.js) | Append `>>> 0` to the return. Behaviour-preserving: both existing consumers (`Color.spec.js`, `deserialize_scene.js`) already normalise. Removes a method whose name promises `uint32` and returns `-1` for white. | Drop the `>>> 0` from `Color.spec.js`'s assertions; they must still pass. |
+| **8** | `C12` | [oklab/linear_srgb_to_okhsv.js](oklab/linear_srgb_to_okhsv.js) | Early-return `h = 0, s = 0, v = toe(L)` when `C < epsilon`, not only when `L === 0`. Today every neutral gets the arbitrary hue `0.2496` with `s ≈ 1e-7`. | Neutrals at several lightnesses return `s === 0`; `v` still round-trips. |
+| **9** | `C12` | [operations/color_scale_okhsv_channel.js](operations/color_scale_okhsv_channel.js) | `clamp01` the three output channels. OkHSV round-trips overshoot by ~1e-7 (`v = 1.0000000270` for white), so the operations can return out-of-`[0,1]` colours. | White in → all channels exactly ≤ 1. |
+| **10** | `C13` | [operations/color_lighten.js](operations/color_lighten.js) | Multiplicative `v * (1 + amount)` has a fixed point at 0, so black cannot be lightened. Switch to `v + amount * (1 - v)` (no fixed point at either end) or document the limitation. Mirror the decision in `color_saturate`. | `color_lighten(black, 1)` ≠ black. |
+| **11** | `C8` | [Color.js](Color.js) `setHCL` ~L332, `setHSI` ~L393 | Decide per method: clamped-to-gamut, or unbounded-caller-clamps. Document the choice. Add a `default:` to both switches (unreachable today, one refactor from `undefined`). If `setHSI` cannot be validated against a reference, its own `NOTE: I'm not sure if the implementation is correct` should be resolved or the method marked `@deprecated` — **not deleted** (R3). | New `Color` spec cases for both, at the primaries and at neutral. |
+| **12** | `C9` | [Color.js](Color.js) ~L702 | `multiplyScalar` and `multiply` scale alpha. Keep the behaviour, document it explicitly, and add `color_multiply_rgb` in Phase 6 for the exposure/tint case. | Doc-only; spec pins current behaviour so it can't drift. |
+| **13** | `C10` | [Color.js](Color.js) ~L501 | `fromUint`: mask red with `& 0xFF`. Superseded in substance by Step 20 (single unpacker) but harmless and immediate. | `fromUint(toUint())` round-trip across the full byte range. |
+| **14** | `C11` | [parse_color.js](parse_color.js) L6-8 | Anchor the three regexes (`^…$` after `trim()`), **or** document the substring-scan behaviour. Today `'background: rgb(1,2,3) !important'` parses, which contradicts the docstring. | Malformed-wrapper strings throw (or are documented as accepted). |
+| **15** | `C15` | [Color.js](Color.js) ~L563 | `hash()` → `toUint32()` (after Step 7) so alpha participates. Currently colours differing only in alpha collide. | Two colours differing only in alpha hash differently. |
+| **16** | `C16` | [illuminant/D65_spd_tabulated.js](illuminant/D65_spd_tabulated.js), [xyz/xyz_cmf_tabulated.js](xyz/xyz_cmf_tabulated.js) | Same problem, two shapes: `<=`/`>=` with an inner equality re-test vs `<`/`>` with a clamped `i1`; one asserts its input, the other doesn't. Converge on one. | Both return the tabulated endpoint exactly at both bounds and `0` outside. |
+| **17** | `C14` | [rgb_to_luminance.js](rgb_to_luminance.js) | Doc-only. Replace *"linear or gamma-corrected"* with the GPU twin's wording: input must be linear for the result to be luminance; on encoded input this is luma (`Y′`). Cross-reference `chunk_rgb_to_luminance`. | — |
+
+---
+
+## Phase 3 — Space contract without a space tag
+
+> Replaces review §3.4. R2 forbids putting the contract *in* `Color`; it goes into function names and
+> docs instead, which is the right layer given `Color` is deliberately low-level.
+
+### Step 18 — State the contract on `Color` and on every consumer
+
+**Files:** [Color.js](Color.js) class JSDoc; `operations/*`; `rgb_to_luminance.js` (done in Step 17)
+
+**Do:**
+1. `Color` class docstring: state plainly that `Color` is a **space-agnostic** 4-float container —
+   it holds whatever the caller put in it, values may fall outside `[0,1]` for HDR, and *the
+   functions operating on it* declare which space they expect. Also correct the false
+   `@extends {Array.<number>}` (`Array.isArray(color) === false`) and document that the numeric
+   index setters (`set 0(v)`) bypass `set()` and therefore do not notify `onChanged`.
+2. Every function in `operations/` gets an explicit `@param {Color} input **linear** sRGB` line.
+   They all call `linear_srgb_to_okhsv` today, so linear is the existing de facto contract —
+   write it down.
+3. `Color.parse` / `toHex` / `toCssRGBAString` get the converse note: these produce/consume
+   **encoded** sRGB, so a `Color` built by `parse` must be converted before reaching `operations/`.
+
+**Test:** doc-only, but add one spec to `color_darken.spec.js` that builds its input via
+`Color.from_sRGB_to_linear(Color.parse('#808080'))` — the correct pipeline — so the intended usage is
+executable and visible.
+
+### Step 19 — Add encoded-input variants so callers aren't required to remember
+
+**Files:** new `operations/color_srgb_scale_okhsv_channel.js` (or a `{ encoded: true }` option — pick one)
+
+**Do:** the UI path (`ColorPickerView`, `ColorEditor`, anything built from `Color.parse`) holds
+encoded values, and the operations assume linear. Provide the decode→operate→encode wrapper once,
+here, rather than in every caller. This is the practical substitute for the refused space tag.
+
+**Test:** encoded variant on `#808080` produces a visibly different (and correct) result from
+feeding the same encoded values to the linear variant.
+
+---
+
+## Phase 4 — Deduplication (no deletions — R3)
+
+Consolidate by **delegation**, keeping every existing export in place so downstream imports keep
+working.
+
+### Step 20 — One uint24 unpacker, three call sites · `§5.1`
+
+**Files:** [int2rgb.js](int2rgb.js) (keep, becomes the implementation), [Color.js](Color.js)
+`fromUint`, [parse_color.js](parse_color.js) numeric branch
+
+**Do:** three copies exist with three masking behaviours. Make `int2rgb` the masked, validating
+implementation and have `Color.fromUint` and `parse_color` call it. Subsumes Steps 4 and 13.
+`int2rgb` keeps its export and signature.
+
+**Test:** all three paths agree across the byte range and reject out-of-range identically.
+
+### Step 21 — Reuse the existing hue-wrap helper · `§5.2`
+
+**Files:** [Color.js](Color.js) `setHSL`/`setHCL`/`setHSI`, [hsv/hsv2rgb_float.js](hsv/hsv2rgb_float.js)
+
+**Do:** the same wrap is inlined four times in two different orders (`% 1` then fix-up, vs fix-up
+then `% 1`). `core/math/euclidean_modulo.js` **already exists** and is exactly this:
+`euclidean_modulo(h, 1)`. Replace all four. No new helper needed.
+
+**Test:** existing specs must stay green; add negative and >1 hue cases (`-3.5`, `2.25`) to each of
+the four.
+
+### Step 22 — One sextant dispatch · `§5.3`
+
+**Files:** [Color.js](Color.js) `setHCL`/`setHSI`, [hsv/hsv2rgb_float.js](hsv/hsv2rgb_float.js),
+new `hsv/hue_to_rgb_sextant.js`
+
+**Do:** `setHCL` and `setHSI` contain byte-identical 30-line switches; `hsv2rgb_float` has a third
+variant. Extract `hue_to_rgb_sextant(out, h_face, c, x)`. This is also what makes Step 11's clamp a
+one-place change instead of three.
+
+**Test:** existing HSV/HSL specs green; new direct spec for the helper at all six sextant boundaries.
+
+### Step 23 — Cross-reference the two lerps · `§5.4`
+
+**Files:** [Color.js](Color.js) `lerpColors`, [operations/color_lerp.js](operations/color_lerp.js)
+
+**Do:** doc-only. `lerpColors` is per-channel linear; `color_lerp` is OkHSV shortest-arc. Neither
+mentions the other, and the results differ substantially at mid-`t`. Add `@see` both ways and one
+sentence on when to pick which.
+
+### Step 24 — Disambiguate spec filenames and suite names · `§5.9`
+
+**Files:** [xyz/XYZ.spec.js](xyz/XYZ.spec.js) → `rgb_xyz_roundtrip.spec.js`;
+[oklab/XYZ.spec.js](oklab/XYZ.spec.js) → `oklab_xyz_roundtrip.spec.js`;
+[sRGB/sRGB.spec.js](sRGB/sRGB.spec.js) → `srgb_transfer_roundtrip.spec.js`
+
+**Do:** two files share the name `XYZ.spec.js` and three share the test name
+`"to/from consistency"`, so a failure report is ambiguous. Rename files and give each test a
+distinct name.
+
+---
+
+## Phase 5 — Cross-boundary consistency
+
+### Step 25 — Reconcile the PQ/ST 2084 reference white · `§3.5` · **highest cross-cutting risk**
+
+**Files:** [PQ/PQ_constants.js](PQ/PQ_constants.js) (203 nits, BT.2408) vs
+`src/shade/renderer/shader/chunk/color/iCtCp/chunk_eotf_st2084.js` and
+`chunk_inverse_eotf_st2084.js` (100 nits)
+
+**Do:** the same engine holds two SDR-white conventions — content encoded on the CPU path and decoded
+on the GPU path is off by 2.03×. Decide which is normative (BT.2408's 203 is the modern answer and is
+what `avif/encoder_worker.js` already ships), then make the other match. `PQ_constants.js` explicitly
+documents why folding a white point into the transfer function is dangerous; the GPU chunk folds a
+*different* one in.
+
+**Test:** a spec that runs the JS `linear_to_PQ`/`PQ_to_linear` pair against the WGSL chunks' expected
+values at several nit levels — per the project's WGSL-validate / JS-emulator tiering.
+
+### Step 26 — Single source of truth for shared constants · `§5.7`
+
+**Files:** [rgb_to_luminance.js](rgb_to_luminance.js), [xyz/rgb_to_xyz.js](xyz/rgb_to_xyz.js),
+the corresponding WGSL chunks
+
+**Do:** the Rec.709 luma weights appear at 4, 15 and 20 significant digits in three places; the sRGB
+OETF exponent and the XYZ matrix each have two spellings. Generate the shared matrices and
+transfer-function coefficients into both JS and WGSL from one definition — the AVIF work already does
+exactly this (`feat(avif): generate the normative AV1 constant tables`), so the mechanism exists.
+This is what makes Step 25 stay fixed.
+
+**Test:** generated output is committed; a spec asserts JS and WGSL constants agree bit-for-bit.
+
+---
+
+## Phase 6 — Missing members, as free functions (R1)
+
+New files only. **No `Color` methods are added.** Order within the phase is by value; each is
+independent.
+
+### Step 27 — Gamut clipping · `§4.3` · highest-value missing feature
+
+**Files:** new `oklab/gamut_clip_preserve_chroma.js`, `oklab/gamut_clip_project_to_lcusp.js`,
+`oklab/gamut_clip_adaptive_l0.js`
+
+**Do:** [find_gamut_intersection.js](oklab/find_gamut_intersection.js) is present and correct and is
+the primitive these are built from — the hard part is already written, only the thin wrappers are
+missing. Ships the package's only route to "make this out-of-gamut colour displayable".
+
+**Test:** new `gamut_clip.spec.js` — clipped colours are in-gamut; in-gamut colours are unchanged;
+hue is preserved by the preserve-chroma variant.
+
+### Step 28 — Missing inverses · `§4.1`
+
+| New file | Note |
+|---|---|
+| `lab/lab_to_xyz.js` | Lab is currently write-only, which defeats the main reason to enter it. |
+| `hunt/hpe_to_xyz.js` | Pairs with the existing `xyz_to_hpe`. |
+| `hex/rgba2hex.js` | `hex2rgb` already **reads** `#RRGGBBAA`; nothing can write it. |
+| `oklab/oklab_to_oklch.js`, `oklch_to_oklab.js` | The space CSS Color 4 exposes and the natural one for hue rotation. |
+| `oklab/okhsl_*.js` | Ottosson defines OkHSL beside OkHSV; `toe`/`toe_inv` are already here. Better basis for lighten/darken than OkHSV (Step 10). |
+
+**Test:** absolute reference values, not only mutual round-trips — see Step 32.
+
+### Step 29 — `Color` free functions replacing the "missing methods" · `§4.2` under R1
+
+**Files:** new, in `operations/` (Color in) and `construct/` (Color out)
+
+| File | Replaces the rejected method |
+|---|---|
+| `operations/color_add.js`, `color_sub.js`, `color_add_scaled.js` | `Color.prototype.add` &c. |
+| `operations/color_multiply_rgb.js` | the alpha-preserving multiply (Step 12) |
+| `operations/color_clamp.js`, `color_is_in_gamut.js` | pairs with Steps 9 & 11 |
+| `construct/color_from_hex.js` | `Color.fromHex` |
+| `construct/color_from_uint24.js`, `color_from_uint32.js` | `Color.fromUint` as a static |
+| `construct/color_from_temperature.js` | wraps the existing `kelvin_to_rgb` |
+| `construct/color_gray.js` | — |
+| `operations/color_get_hsl.js` | `getHSV` exists, `getHSL` does not |
+
+**Do:** each is a thin function over machinery that already exists. Existing `Color` methods are left
+untouched — this is additive.
+
+### Step 30 — Lazy `onChanged` · `§4.2` · **defer; highest blast radius**
+
+**Files:** [Color.js](Color.js) constructor + `set()`
+
+**Do:** every `Color` eagerly allocates a `Signal`; measured **71.7 ms vs 17.9 ms per 500k
+constructions** — a 4× cost on a low-level type used in per-particle and per-vertex paths, which sits
+badly with R2's "Color is a low-level class". Make the signal lazy (allocate on first `add`, guard
+the `send8`). `Color.onChanged` has three known consumer sites (`PointLight`, `SpotLight`,
+`ColorPickerView`) but is accessed as a plain property, so a getter must preserve that shape.
+
+**Test:** existing `onChanged` specs green; a new allocation benchmark spec pinning the improvement;
+manual check of the three consumers.
+
+**Sequencing:** do this **after** Step 1, which is the step that makes `onChanged` correct in the
+first place.
+
+---
+
+## Phase 7 — Test coverage (raised in priority by R3)
+
+> Because nothing downstream is visible from this repo, the specs *are* the contract for the 33
+> unspecced source files. Absolute reference values, not just mutual inverses.
+
+| Step | Target | What to add |
+|---|---|---|
+| **31** | `oklab/` primitives | `linear_srgb_to_oklab`, `oklab_to_linear_srgb`, `find_cusp`, `toe`/`toe_inv`, `find_gamut_intersection` — currently 6 assertions across two whole-pipeline round-trips, and `find_gamut_intersection` has none. Add per-function specs with published reference values. |
+| **32** | Matrix pairs | `rgb_to_xyz`/`xyz_to_rgb`, `ycxcz`, `YCoCg`, `PQ` are covered only by mutual round-trips — a forward matrix wrong in both directions passes. Add absolute expected values (D65 white, the three primaries, mid-grey). |
+| **33** | Untested leaves | `rgb_to_luminance` (3 non-spec importers), `rgb2uint24`/`rgb2uint32`, `hsv2rgb_float`, `xyz_to_hpe`, `rgb_to_xyz`, `PQ_constants`. |
+| **34** | Seams | The sweep spec from Step 5, generalised: assert bounded first differences across every piecewise function in the package (`kelvin_to_rgb`, `convert_channel_*`, `xyz_to_lab`'s `compress`). |
+| **35** | Alpha | An alpha case on every function in `operations/` and on both `Color` sRGB statics. Steps 1 and 2 survived because none existed. |
+| **36** | Allocation | A guard spec on `Color` construction cost, so Step 30 can't regress. |
+
+---
+
+## Phase 8 — Convention convergence (last, one sweep)
+
+> Large, mechanical, mostly rename. Deliberately last so churn lands once, after behaviour is
+> correct. Nothing here is a deletion (R3) — old names stay as re-exports for one release if needed.
+
+| Step | Finding | Do |
+|---|---|---|
+| **37** | `§3.1` | Give `rgb_to_xyz` / `xyz_to_rgb` the `(out, out_off, in, in_off)` signature. Highest-value single change in the phase — 4 non-spec importers each, and they're the two most-imported conversions in the package. Keep the current 2-arg form as a delegating overload. |
+| **38** | `§3.1` | Same treatment for the remaining `(out, in)` member, `xyz_to_hpe`. Leave `(out, …scalars)` alone where inputs genuinely aren't a contiguous triple (`kelvin_to_rgb`, the CMFs). |
+| **39** | `§3.2` | Rename `hsv2rgb` → an explicitly byte-scaled name so the unsuffixed name isn't the non-default unit. Fix `parse_color`'s mixed `[0-255, 0-255, 0-255, 0-1]` return, moving the `/255` knowledge out of `Color.parse`. |
+| **40** | `§3.3` | `name2name` → `name_to_name` across Layer B (`hsv2rgb`, `rgb2hsv`, `rgb2hex`, `hex2rgb`, `int2rgb`, `rgb2uint24`, `rgb2uint32`). Splits cleanly by age, so it's mechanical. |
+| **41** | `§3.3` | One casing for the `sRGB` token (`sRGB_to_linear` vs `linear_srgb_to_oklab`), and one for directory names (`PQ`/`YCbCr`/`YCoCg`/`sRGB` vs the twelve lowercase ones). |
+| **42** | `§1.3` | `hunt/` holds `xyz_to_hpe`, the Hunt–Pointer–Estévez *matrix*, while the Hunt-*effect* function lives in `lab/` and carries a disclaimer saying so. Move `xyz_to_hpe` to `xyz/` and retire the `hunt/` directory (move, not delete). |
+| **43** | `§3.6` | One assert policy. Today `planckian_radiance` and `D65_spd_tabulated` validate scalars while `xyz_cmf_tabulated`, `xyz_cmf_wyman`, `linear_to_PQ` and `D65_spd_analytical` don't; `kelvin_to_rgb` asserts, `rgb_to_ycocg` doesn't. Also add the missing `@author`/`@copyright` to `linear_srgb_to_okhsv`, `linear_srgb_to_oklab`, `toe`. |
+
+---
+
+## Suggested batching
+
+| Batch | Steps | Character |
+|---|---|---|
+| **A** | 1–4 | Alpha + ingest. Small edits, immediate risk reduction, no design decisions. |
+| **B** | 5–6 | Kelvin. One decision (a vs b), one new test shape that pays off in Step 34. |
+| **C** | 7–17 | Minor correctness sweep. Mostly one-liners plus docs. |
+| **D** | 18–19 | Space contract. Doc + one new wrapper; unblocks correct downstream usage. |
+| **E** | 20–24 | Deduplication by delegation. No exports removed. |
+| **F** | 25–26 | CPU/GPU reconciliation. Do before more HDR work lands. |
+| **G** | 27–29 | New surface area. Purely additive, no risk to existing callers. |
+| **H** | 31–36, 30 | Coverage, then the lazy signal last (Step 30 needs 36 as its guard). |
+| **I** | 37–43 | Convention sweep. |
+
+**Regression baseline for every batch:** `npx vitest run src/core/color` — currently 33 files, 158
+tests, all passing. No step in this plan may reduce that count.