@woosh/meep-engine 3.60.4 → 3.60.5

package/src/core/cache/wtinylfu/benchmark/CacheWTinylfu.bench.md

@@ -1,243 +0,0 @@
-# W-TinyLFU benchmarks
-
-Benchmarks comparing `CacheWTinylfu` against the LRU `Cache` sibling. They split into **two axes**
-that answer different questions:
-
-| Axis | Question | Answered by |
-|------|----------|-------------|
-| **Effectiveness** (hit rate) | What fraction of accesses hit? Determined by the **policy**. | `hitRate.spec.js` |
-| **Performance** (throughput / latency / space) | What does each operation **cost**? Determined by the **implementation**. | everything else |
-
-You need both to judge the trade: the policy benchmark tells you what W-TinyLFU *saves you in misses*;
-the performance benchmarks tell you what it *costs per op and in RAM*. The exchange rate between them is
-the cost of a miss in your system (a disk/network miss dwarfs a few hundred ns; a cheap recompute does not).
-
-> ⚠️ **About the numbers below.** They're from one dev machine (Node v20.14.0, Windows 11) and microbenchmarks
-> are noisy — absolute nanoseconds wander run-to-run by tens of percent. **Trust the ratios and the shape, not
-> the exact ns.** The ratios are measured *interleaved* (LRU and W-TinyLFU timed back-to-back each round, then
-> the per-round ratios medianed), so they stay stable even as the absolutes drift. Re-run on your own hardware
-> for absolutes.
-
----
-
-## Running
-
-Each benchmark is a self-contained `<name>.spec.js` with a skipped test entry and an explicit manual Node
-entry. The measurement **only ever runs under plain `node`** — never in-process under
-Jest, because Jest's babel transform badly distorts the timings (see *Why not measure under Jest* below).
-The files are stripped from the published npm package by the `*.spec.js` rule.
-
-**To get numbers — run it directly with `node`, from `packages/meep-engine`:**
-
-```bash
-node src/core/cache/wtinylfu/benchmark/<name>.spec.js --benchmark
-```
-
-where `<name>` is one of: `hitRate`, `fillDrain`, `readAll`, `continuousPut`, `mixed`, `latency`, `scaling`,
-`memory`.
-
-The files remain `describe.skip` under the test runner. Vitest's `--mode all` includes them in collection;
-un-skipping one makes its test spawn a native Node child and check that the report contains finite
-measurements. Importing a file or invoking it without `--benchmark` performs no workload setup.
-
-Options for the manual `node` invocation:
-
-- **`--expose-gc`** (a Node flag, goes *before* the script path): lets a benchmark force GC between trials for
-  cleaner numbers. Optional for most; **required** for `memory` (it refuses to run without it). *(When run via
-  Jest, the child is always spawned with `--expose-gc`.)*
-  ```bash
-  node --expose-gc src/core/cache/wtinylfu/benchmark/fillDrain.spec.js --benchmark
-  ```
-- **`HASH=int`** (an env var): the **isolated-hash toggle** — use integer keys + an identity hash instead of
-  string keys + `computeStringHash`, to strip string-hashing cost and see pure-policy overhead. Works on
-  **every** benchmark.
-  ```bash
-  HASH=int node --expose-gc src/core/cache/wtinylfu/benchmark/readAll.spec.js --benchmark
-  ```
-
-All workloads are **seeded**, so runs are reproducible. Both caches are always built at **matched capacity**
-(N weight-1 entries) so the comparison is fair.
-
-### Layout & file structure
-
-Each benchmark lives in its own self-contained file in this `benchmark/` folder as `<name>.spec.js`.
-There is **no shared harness** — each file inlines the scaffolding it needs, so it stands alone (copy it,
-run it, read it without chasing imports). Every file follows the same skeleton:
-
-```
-1. HEADER       what it measures · how to run · how to read it
-2. CONFIG       the knobs: CAPACITY / WARMUP / TRIALS / SEED
-3. SCAFFOLDING  inlined: clock, rng, matched-capacity factories, measureInterleaved, any workload
-                (top-level — pure definitions, safe when Jest imports the file)
-   if (under tests) → skipped native Node child + finite report checks
-   if (manual entry with --benchmark) → runBenchmark():
-4. WORKLOAD       the setup + the timed body                       (the "arrange")
-5. MEASURE        measureInterleaved([LRU, W-TinyLFU], {...})      (the "act")
-6. REPORT         formatting + console.log                         (the "assert" analog — reports, no pass/fail)
-```
-
-The `if (typeof describe === "function")` split keeps measurements in the native child. Workload setup is
-inside `runBenchmark()`, called only by the explicit main-file `--benchmark` entry.
-
-A benchmark **reports** numbers; it does not **assert** pass/fail. That's why the measurement always runs
-under plain `node` — the Jest side only launches it and checks the output isn't empty.
-
-### Why not measure under Jest
-
-Jest runs every file through **babel-jest** before V8 sees it (transpiled to CommonJS, wrapped in Jest's
-module registry). That transformed code JITs differently from the native ES module `node` runs — and the
-overhead is **not uniform**: a cheap op (LRU) takes a bigger proportional hit than a heavier one (W-TinyLFU).
-Measured in-process under Jest, absolutes inflated ~2–12× **and several ratios inverted** — `fill` read
-1.76x → 0.91x, `mixed` 1.48x → 0.90x, `latency p50` 3.0x → 0.86x — i.e. Jest would tell you W-TinyLFU is
-*faster* than LRU on inserts, which is false. It was also ~4× slower wall-clock. So the benchmark body never
-runs under Jest; the spec spawns a clean `node` child and only checks the output is well-formed.
-
----
-
-## Effectiveness — `hitRate.spec.js`
-
-Replays seeded access traces as a read-through cache and reports **hit ratio** (capacity N = 500). This is
-where W-TinyLFU earns its keep.
-
-```
-                                       LRU      W-TinyLFU    Δ
-uniform random (no skew)              10.0%      10.0%      0.0   ← control: no harm
-zipfian skew 0.7 / 0.9 / 1.1        22.7/45.4/70.7  ~equal  ±1    ← realistic skew: roughly even
-scan (hot set + one-shot scans)       31.6%      47.0%     +15.4  ← scan resistance: the big win
-cyclic loop (size > capacity)         LRU pathological case  win  ← incumbent-favoring ties
-```
-
-**Takeaway:** roughly even with LRU on plain skew, *no worse* on uniform, and a large win on **scan-heavy**
-and **cyclic** workloads (where LRU is catastrophic). That scan resistance is the reason to pay the costs below.
-
----
-
-## Performance
-
-Realistic (string-key) mode, `--expose-gc`, interleaved, median of 100 trials. **Capacities:** the read / fill /
-space and `continuousPut` benchmarks use **N = 65,536**; `mixed` uses a quarter of that (**N = 16,384**,
-keyspace 10×N) so its keyspace can dwarf the cache for realistic misses. All are powers of two — safe under
-churn because the shared HashMap grows headroom at its load factor.
-
-### `fillDrain` — insert + teardown
-
-```
-fill (put)       | LRU ~197 ns/op  | W-TinyLFU ~378 ns/op  | ~2.1x
-drain (clear)    | LRU ~21 ms/call | W-TinyLFU ~11 ms/call  | ~0.52x
-drain (remove)   | LRU ~259 ns/op  | W-TinyLFU ~317 ns/op   | ~1.2x
-```
-`fill` is the policy's insert cost (sketch + region routing). The `drain` rows reflect each class's *teardown
-implementation*, not the policy — LRU's `clear()` removes element-by-element while W-TinyLFU bulk-resets, so the
-drain difference is an implementation artifact.
-
-### `readAll` — read path (cold vs warm)
-
-```
-read cold        | LRU ~370 ns/op | W-TinyLFU ~710 ns/op | ~1.9x
-read warm        | LRU ~290 ns/op | W-TinyLFU ~490 ns/op | ~1.7x
-```
-Every get is a hit. `cold` = first read-pass (W-TinyLFU's promotion activity); `warm` = settled steady state.
-The premium is modest and one-time, not a recurring spike.
-
-### `continuousPut` — sustained load (churn vs update)
-
-```
-put churn        | LRU ~660 ns/op | W-TinyLFU ~656 ns/op | ~1.0x   (new keys → evict + admission duel)
-put update       | LRU ~220 ns/op | W-TinyLFU ~447 ns/op | ~2.0x   (re-put existing keys → in-place)
-```
-**The key reframe.** W-TinyLFU's extra policy work is roughly **additive (~150–200 ns/op)**, not a multiplier —
-on the cheap `update` baseline it shows as ~2.1×. On `churn` it doesn't show at all: **element pooling** makes
-W-TinyLFU's inserts allocation-free, while LRU still allocates an element per insert, so that saving *offsets*
-the policy overhead and W-TinyLFU draws level with LRU (~1.0×).
-
-### `mixed` — realistic blended throughput
-
-```
-mixed get/put    | LRU ~157 ns/op | W-TinyLFU ~224 ns/op | ~1.4x
-```
-Zipfian read-through (get; on miss, put) over a keyspace 10× the cache — the most representative single number.
-
-### `latency` — the tail (percentiles)
-
-```
-              p50    p99    p999     max
-LRU           200   ~700   ~2400    multi-ms (GC)
-W-TinyLFU     300   ~1300  ~7400    multi-ms (GC)
-```
-Per-op timing during a fill. W-TinyLFU's whole distribution shifts up ~2× — its heavier insert, paid broadly
-rather than in a rare spike. The **max is a multi-ms GC pause on both**, not a policy event — read the policy
-tail in p99/p999, not max.
-
-### `memory` — bytes per entry (space) · requires `--expose-gc`
-
-```
-                       fresh fill                 after churn (steady state)
-LRU          | ~144 (heap ~136 + ext ~8)  | ~224 (heap ~208 + ext ~16)  bytes/entry
-W-TinyLFU    | ~164 (heap ~152 + ext ~12) | ~245 (heap ~225 + ext ~20)  bytes/entry
-→ fresh, W-TinyLFU vs LRU: +~20 B/entry  (+~16 heap = per-element `region` + `keyHash`; +~4 sketch)
-→ churn cost (both caches): +~80 B/entry  (the shared HashMap doubling its slab at the load factor)
-```
-~14% more RAM per entry for the **policy** (fresh) — the **W-vs-LRU difference of ~4 B ≈ the sketch**. The
-**churn cost** is the same +~80 for both because it's the *shared HashMap*, not the policy: once the cache is
-full and evicting, the entries slab (and its bins) hits the 0.75 load factor and **doubles** to keep amortised
-O(1) inserts, so a churning cache carries ~2× the entry headroom of a fresh fill.
-
-### `scaling` — O(1) check + locality across N
-
-```
-     N        LRU      W-TinyLFU   ratio
-    2,048     62.3       175.6      2.88x
-   16,384    102.8       230.0      2.25x
-  131,072    379.2       556.8      1.47x
-1,048,576    667.7       911.8      1.37x        (warm random read, ns/op)
-```
-Per-op cost rises only ~11× from 2k→1M (not ~500×) → **O(1) confirmed**; the rise is **CPU-cache locality**.
-The ratio **compresses as N grows** — both caches increasingly bottlenecked on RAM latency at large N.
-
-### `HASH=int` — pure-policy overhead (cross-cutting)
-
-Run any benchmark with `HASH=int` to strip string hashing. Example (read warm):
-
-```
-                realistic        isolated (HASH=int)
-LRU              ~290 ns/op        ~151 ns/op
-W-TinyLFU        ~490 ns/op        ~338 ns/op
-ratio             ~1.7x             ~2.3x
-```
-Reveals that **string hashing is a large *shared* cost** (~140 ns of LRU's warm read was just `Map` string
-hashing, paid by both caches). Removing it shrinks the baseline, so the *same* fixed policy overhead becomes a
-bigger multiple.
-
----
-
-## Headline findings
-
-1. **Cost is a roughly fixed additive overhead, not a multiplier** — ~100–300 ns/op of extra work (sketch
-   increment + region bookkeeping), so the "Nx" you see depends mostly on how cheap the underlying op already was.
-2. **O(1) and predictable** — confirmed across 3 orders of magnitude; the only growth is shared CPU-cache locality.
-3. **No tail surprises** — the overhead is spread across the whole distribution (median through p999), not a rare
-   spike; the worst-case `max` is a GC pause both caches share.
-4. **~14% more memory per entry** — the per-element `region` + `keyHash` fields plus the O(N) frequency sketch
-   (plus a shared ~+80 B/entry once any cache is full and churning — the HashMap doubling its slab, not policy-specific).
-5. **Bought against scan resistance** — the effectiveness axis shows large hit-rate wins on scan/cyclic workloads,
-   while staying roughly even with LRU on plain skew and doing no harm on uniform.
-
-**The trade in one line:** ~150–200 ns/op and ~14% RAM, predictable and O(1), in exchange for scan-resistant,
-frequency-aware retention — worth it exactly when your misses are expensive and your traffic isn't purely uniform.
-
-## Methodology notes (why the numbers are trustworthy)
-
-- **Pre-generated keys** outside the timed region (else you measure string allocation, not the cache).
-- **Warmup** discarded so the JIT has compiled the hot path (we measure optimized machine code, not the cold
-  interpreter).
-- **Interleaved trials** — every round times LRU and W-TinyLFU back-to-back, and the ratio is the **median of
-  the per-round ratios** (paired). So machine drift within a round hits both equally and cancels in the ratio.
-- **Median of trials** (not mean) to shrug off the occasional GC pause.
-- **Selective `forceGc`** — forced for low-allocation bodies (reads, teardown) where a stray pause is pure noise;
-  *not* for allocation-heavy bodies (fill, churn) where GC is part of the real cost.
-- **Result sinks** so pure-read loops aren't deleted by dead-code elimination.
-- **Matched capacity & shared seeded workloads** so LRU and W-TinyLFU face identical conditions.
-- **Measured under `node`, never in-process under a test runner** — a transform (babel/esbuild) distorts both
-  the absolute ns *and* the ratio (a cheap op suffers proportionally more overhead). Measured under Jest
-  in-process, several ratios *inverted* (e.g. `fill` read 1.76x → 0.91x). That's why the self-executing spec
-  spawns a clean `node` child instead of measuring inside Jest — see *Why not measure under Jest*.

package/src/core/color/COLOR_FIX_PLAN_2026_08_28.md

@@ -1,417 +0,0 @@
-# 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.