iccery-v2-mac/docs/24-issues-invariants.md

# 24 — Issue tickets and rewrite invariants

> Line numbers refer to ICCery v0.8.5 (`/tmp/ICCery` at analysis time) and the Gronod ArgyllCMS 3.5.0 fork.

Source corpus: Gitea issues `#1`–`#225` (`/tmp/iccery-research/issues/`), `issues-index.md`, `ROADMAP.md`, `git log` on `/tmp/ICCery` (main @ `e12ef41`, tag `v0.8.5`), PR titles pages 1–2, plus sibling issue dumps `argyll-issues.json` and `cpu-issues.json`.

This is a rewrite-invariants document. Every closed bug gets a **root cause → fix → invariant**. Features are traced so a rewrite does not re-invent the same CLI/IPC contracts.

Open tickets `#223` and `#224` are **implemented on main** (see § Open issues). Won't-fix `#90` / `#96` are documented in § Won't-fix.

---

## 1. Feature genealogy (issue → ship)

The product is a **printer-profiling workstation**: vanilla JS + Tauri v2 wrapping ArgyllCMS sidecars over stdin/stdout JSON (`-u`) with a disk-artefact wizard.

| Era | Version | Issues | What landed |
|---|---|---|---|
| Scaffold | `v0.1.0` | `#1`, `#2` | Tauri v2 shell, AGPLv3 isolation, `ProcessManager` with `process:stdout/stderr/exit` events |
| Stage 1–2 | `v0.1.3` | `#3`, `#4` | `targen` patch sets; `printtarg` layout + instrument geometry |
| Stage 3 | `v0.1.6` | `#5`, `#6` | `chartread -u` state machine + live swatch grid + ΔE₀₀ |
| Stage 4–5 | `v0.1.9` | `#7`, `#8` | `colprof` cLUT; `profcheck` peak/avg/RMS |
| Print + UI | `v0.1.10`–`0.1.13` | `#21`, `#23`, `#25`–`#28`, `#34`, `#54`, `#61` | Logo; raw GDI/CUPS print; DEVMODE prefs; collapsible logs; 1280×800 window |
| Gamut + ship | `v0.1.14`–`0.2.0` | `#9`, `#10`, `#57`, `#58`, `#60`, `#69` | `iccgamut` + Three.js; settings/packaging; artefact-gated wizard |
| Hotfix | `v0.2.1` | `#84` (from `#63` regression) | Stdin decoupled from `Child::wait()` |
| M8 | `v0.3.0` | `#86`, `#87`, `#88`, `#89` | `instlist`; multi-pass `average`; presets; 3D hull |
| Hotfixes | `v0.3.1`–`0.3.6` | `#103`, `#108`–`#116`, `#119`, `#127`, `#134`, `#137` | Browse dialogs, GLIBC, averaging snapshots, comm-port vs index, density vs dir, XSS/DPI, fetch-argyll, `ARGYLL_NOT_INTERACTIVE`, Accept/Override |
| macOS print | `v0.4.0` | `#91`, `#92` | Universal dmg path + CUPS raw spooler |
| Production | `v0.5.0`–`0.5.5` | `#139`–`#141`, `#147`/`#149`, `#151`, `#158`–`#165` | Logging, Stage 3 resume from `.ti2`, advanced `targen`, `kill_all` on exit, deterministic `-R 1`, universal sidecars |
| Enterprise colour | `v0.6.0`–`0.7.4` | `#94`, `#171`, `#172`, `#175`–`#179`, `#184`, `#185`, `#188`, `#189` | CGATS import, overlay tooltips, profile picker, `d`/`u` chartread keys, OBA/FWA, button system, swatch split, `.gam` dual-table parse, ΔE thresholds, ColorSync/vendor bypass, DMG background |
| Hardware + analytics | `v0.8.1`–`0.8.2` | `#204`, `#93`, `#95` | i1Pro2 `-Y l`; XY tables; drift history |
| Reliability | `v0.8.3`–`0.8.4` | `#210`–`#215`, `#225` | Native file pickers, Node-safe gamut tests, atomic history, frontend CI, Monterey WKWebView survival |
| Cal + install | `v0.8.5` | `#224`, `#223` (tickets still *open*) | Stage 0 `printcal`/`applycal`; OS profile install |

ArgyllCMS fork genealogy (why ICCery's CLI looks the way it does):

| Argyll issue | Flag / contract ICCery depends on |
|---|---|
| argyll `#1` | `chartread -u` → `ROW_COLORS_JSON:` per row |
| argyll `#2` | `targen -u` JSON progress |
| argyll `#3` | `printtarg -u` page manifest JSON |
| argyll `#4` | `colprof -u` JSON progress |
| argyll `#5` | `profcheck -u` JSON ΔE report |
| argyll `#6` | `instlist` JSON `{event:"instruments", devices:[{port,name,type}]}` |
| argyll `#19` | `printtarg -d "<label>"` custom chart legend (ICCery `#119`) |
| argyll `#24` | Windows anonymous-pipe `PeekNamedPipe` so `chartread` does not deadlock on `ReadFile` |
| argyll `#32` | ad-hoc `codesign -s -` of Mach-O sidecars (ICCery `#165`) |
| argyll `#37` | i1Pro2 LED — ICCery shipped as `chartread -Y l` (`#204`), **not** the originally proposed `-L` |

---

## 2. Closed bugs — root cause → fix → rewrite invariant

Grouped by subsystem. Issue numbers are always cited.

### 2.1 Process manager / IPC

**`#21` Process logs spill horizontally**
- **Root cause:** `#colprofLog` / `#profcheckLog` had no CSS; even stages with `white-space: pre-wrap` could not wrap Argyll's space-less progress dots.
- **Fix:** Class selector `.log-container pre { white-space: pre-wrap; overflow-wrap: anywhere; overflow-y: auto; max-height: 200px; }` (PR `#22`). Later `#54` made boxes collapsible.
- **Invariant:** All subprocess consoles share one CSS class. Never style per-stage IDs. Argyll stdout is not English prose; it is long runs of `.` and must wrap *anywhere*.

**`#46` Visible cmd.exe on every Argyll spawn (Windows)**
- **Root cause:** Sidecars are `IMAGE_SUBSYSTEM_WINDOWS_CUI`. `tokio::process::Command` without creation flags allocates a console.
- **Fix:** `command.creation_flags(0x08000000)` (`CREATE_NO_WINDOW`) in `ProcessManager::spawn` (`#[cfg(windows)]`).
- **Invariant:** Every Windows spawn of an Argyll CUI binary **must** set `CREATE_NO_WINDOW`. Do not "fix" this by rebuilding Argyll as WINDOWS_GUI — that would also kill stdin/stdout.

**`#63` Zombie children (enhancement that caused `#84`)**
- **Root cause:** 100 ms `try_wait` polling never removed finished `Child` handles.
- **Fix (PR `#77`):** `child.wait().await` and reap from the map.
- **Invariant:** Reap is required. But **never** `wait()` while still holding the `Mutex<Child>` that `send_stdin` needs — see `#84`.

**`#84` P0: `Child::wait()` deadlocks `send_stdin` and closes stdin (v0.2.1)**
- **Root cause:** PR `#77` awaited `c.wait()` under `Arc<Mutex<Child>>`. Tokio's `Child::wait` **drops stdin** to avoid parent/child deadlock. Interactive `chartread` therefore (1) could not acquire the mutex for Calibrate/Retry/Skip/Cancel, and (2) had its pipe closed immediately after spawn.
- **Fix (PR `#83`, v0.2.1):** `take()` stdin/stdout/stderr at spawn; store `ChildStdin` in a separate `stdins: HashMap<String, Arc<Mutex<ChildStdin>>>`; `tokio::select!` between `child.wait()` and a oneshot `kill_rx`.
- **Invariant:** Interactive subprocess lifetime has **three** independent handles: wait task, stdin mutex, kill oneshot. `send_stdin` must never take the `Child` lock. Never call `wait()` before `take()`-ing stdin.

**`#85` `resolve_binary` ignores `.exe`**
- **Root cause:** Path joins used `"targen"`; on disk the file is `targen.exe`. `exists()` returned false for custom dirs and bundled resources.
- **Fix (PR `#97`):** On Windows, try `{name}` and `{name}.exe` for both settings dir and resource resolution. Unit-test both.
- **Invariant:** Windows binary lookup is always a two-candidate search. Do not assume Unix names in `tauri.conf.json` resources.

**`#116` Duplicate spawn ids steal the live child's maps**
- **Root cause:** `stdins.insert(id)` / `killers.insert(id)` with no occupancy check. Averaging reuses `chartread_${basename}`. Old wait-task `remove()`s the **new** child's entries → "Process not found" on Calibrate.
- **Fix (PR `#123`):** Hard-error if `id` is occupied; disable Start / Measure Another Sheet until `process:exit`. Tokio test: spawn, reject duplicate, stdin still works, kill, reuse.
- **Invariant:** Process IDs are exclusive leases. Prefer a loud error over silently replacing the occupant. After exit, the id is reusable.

**`#134` Calibrate button does nothing; `instlist` shows nothing**
- **Root cause:** (1) Without `ARGYLL_NOT_INTERACTIVE=1`, Argyll on Windows uses `_getch()` / `ReadConsoleInput()`, ignoring piped stdin — especially combined with `#46`'s hidden console. (2) Forked `instlist` emits JSON; frontend only had a text regex.
- **Fix (PR `#135`, v0.3.5):** `command.env("ARGYLL_NOT_INTERACTIVE", "1")` on every spawn; parse `event === "instruments"` JSON with text fallback.
- **Invariant:** All Argyll children get `ARGYLL_NOT_INTERACTIVE=1`. Frontend instrument lists parse JSON first. Related upstream: argyll `#24` (`PeekNamedPipe` before `ReadFile` on anonymous pipes) — the env var is necessary but not sufficient on Windows.

**`#147` / `#149` Orphan `chartread` after window close**
- **Root cause:** Only Stage 3 Cancel called `kill_process`. `lib.rs` used bare `.run(...)` with no `RunEvent::Exit` / `CloseRequested`. Spectrophotometer stays USB-locked.
- **Fix:** `ProcessManager::kill_all` (drop stdins, signal killers, `start_kill`); hook app/window exit.
- **Invariant:** Host exit **always** drains the process table. Interactive instruments are the scary case, but `colprof`/`printtarg` must die too.

**`#158` Settings log level is decorative**
- **Root cause:** `tauri-plugin-log` filter hardcoded `Debug` vs `Info` from `cfg!(debug_assertions)`. `AppSettings.log_level` was persisted and ignored.
- **Fix:** Map stored string → `LevelFilter` at startup and on Save.
- **Invariant:** A settings control that does not change observable behaviour is a bug. Log level is runtime state, not a compile-time constant.

---

### 2.2 Print (Win / Mac / Linux)

**`#33` Windows CI: unresolved GDI imports**
- **Root cause:** `windows` crate 0.58 does not export `SetICMMode` / `ICM_OFF` under `Win32::Graphics::Gdi` as used in `print/windows.rs`. GitHub `windows-2025` runner compiled the print backend and died with `error[E0432]`.
- **Fix:** Declare the GDI printing functions/structs used (`CreateDCW`, ICM off, `StretchDIBits`, …) directly rather than depending on incomplete crate bindings (`a9802ad`, `c9e16ab`). Later also: runner label, native rustup, `shell: powershell`.
- **Invariant:** Colour-management bypass (`SetICMMode(ICM_OFF)`) is a **link-time** contract. Pin/vend the FFI; do not assume `windows` crate surface area. CI on the real Windows target is the only proof.

**`#36` DEVMODE preferences not applied**
- **Root cause:** OEM dialog (`DocumentPropertiesW`) writes public `DEVMODEW` **plus** `dmDriverExtra` private bytes. The print path was not forwarding the full buffer (and mishandled the anonymous union for `dmDefaultSource` / `dmOrientation`) into `CreateDCW`/`StartDocW`. Epson "Print Preview" etc. therefore vanished.
- **Fix:** Retain the entire DEVMODE allocation including `dmDriverExtra`; fix union field access (`19449e3`).
- **Invariant:** Windows driver settings are a **blob**, not a parsed struct. Never memcpy only `dmSize` bytes. Never reconstruct DEVMODE from a handful of public fields.

**`#48` CUPS/PPD "Uncorrected Passthrough" shown on Windows**
- **Root cause:** `#cupsOptionsGroup` rendered unconditionally.
- **Fix:** Hide on `navigator.userAgent` Windows (v0.1.7).
- **Invariant:** Print UI is per-backend. Windows = DEVMODE; Unix = PPD/CUPS. Do not show controls the active spooler cannot honour.

**`#67` Duplicate print IPC (cleanup, not a user bug)**
- **Fix:** Collapse `get_windows_printers`/`get_cups_printers`/`print_target_*` into `get_printers` / `print_target`.
- **Invariant:** One IPC surface, platform switch inside Rust.

**`#188` macOS: Preferences opens System Settings; no way to disable driver CM (Epson XP-55, Canon Pro 9500 II)**
- **Root cause:** "Preferences" deep-linked to the OS Printers & Scanners pane, not the selected queue's driver panel. ColorSync plus vendor filters (`CNIJIntent2`, Epson `ColorCorrection`) re-managed the raw target. Follow-on: `PMSessionSetColorMatchingMode` 3-arg SPI **crashed**.
- **Fix (v0.7.2–0.7.3):** Native `NSPrintPanel` bound to the current `PMPrinter`; PPD/`lpoptions` media-type extraction; vendor uncorrected-color keys; `AP_ColorMatchingMode=AP_ApplicationColorMatching`; **remove** the crashing 3-arg SPI and use the validated 2-arg / lock sequence (`8b01c98`). Windows media_types added in the same stack so CI still built.
- **Invariant:** Raw print means **three** layers must all be off: OS ColorSync, driver colour, and ICM/CUPS filters. Opening the generic Printers pane is not a preferences dialog. Never call private Core Printing SPIs whose arity is guessed.

**Sister-product traps (ICCery-CPU `#1`, `#2`, `#5`) that also apply to any CUPS rewrite:**
- PPD `ChoiceName/TranslationString` — UI must show the title, send the code (`MediaType=13` not `MediaType=Epson Premium Glossy`).
- Tray keywords are vendor-specific (`InputSlot` vs Epson `EPIJ_FdSo` vs Canon `CNIJMediaSupply`). Empty arrays are not `nil` — coalescing `?? ["Auto"]` does not fire.
- Canon Super Fine is three coordinated keys (`CNIJPrintQuality=0`, `CNIJPrintMode2=5`, `CNIJPQualitySlider=5`), not `cupsPrintQuality=High`.

---

### 2.3 Stage 1 — targen

**`#44` Patch count ignored → always 836**
- **Root cause:** Frontend sent `patch_count`; Rust `build_targen_args` only read `total_patches`. `-f` omitted → Argyll's built-in default **836** RGB patches.
- **Fix (v0.1.5, PR `#45`):** Honour `patch_count` (fallback `total_patches`); unit-test argv.
- **Invariant:** `targen` without `-f` is not "use the UI value". Default 836 is an Argyll formula, not an ICCery default. Serde field names must match across JS and Rust **and** be tested.

**`#59` Empty working directory**
- **Root cause:** Basename typed without Browse → `cwd: ""` → process launch dir (read-only / undefined). Same hole in later stages.
- **Fix (v0.1.12):** Init `currentWorkingDir` to `document_dir`/`home_dir`; disable Generate until both basename and cwd exist; backend also refuses empty cwd.
- **Invariant:** Empty cwd is illegal. Frontend guard **and** backend fallback. Never spawn Argyll in the install/resource directory.

**`#103` Stage 1 Browse does nothing; Generate stays disabled**
- **Root cause:** Frontend called `window.__TAURI__.dialog` (Tauri v1 API). With `withGlobalTauri: true` on Tauri v2, `window.__TAURI__.dialog` is **undefined**. Same class of bug as `#210`/`#211`.
- **Fix (v0.3.1, PR `#104`):** Backend command `select_target_file` using `app.dialog()`.
- **Invariant:** **Never** use `window.__TAURI__.dialog`. All file pickers are Rust commands with explicit filters. See also `#172`, `#210`, `#211`.

**`#162` Advanced options misaligned**
- **Root cause:** Mixed control heights (number vs range vs checkbox-without-label) plus a full-width `-c` row breaking the 2-col grid; flex-end hacks.
- **Fix (v0.5.5 / v0.6.1):** Semantic sub-groups, normalized row heights, flexbox auto-margins.
- **Invariant:** Advanced `targen` controls are a 2-column grid of equal-height rows. Checkboxes get a label column. Do not use `justify-content: flex-end` to fake alignment.

**`#172` Preconditioning browse filters `.ti1/.ti2/.ti3` instead of `.icc/.icm/.mpp`**
- **Root cause:** Reused `select_target_file` (target artefacts) for `targen -c`.
- **Fix:** Dedicated `select_profile_file`.
- **Invariant:** Each browse button has its **own** backend command and extension filter. Sharing "the dialog command" is how you open a Save-`.ti1` dialog for an ICC.

**`#211` CGATS Import opens a Save `.ti1` dialog and jumps to Stage 4 with empty basename**
- **Root cause:** `handleImport` invoked `select_target_file` (`save_file`, filter `ti1`). Empty `cwd`/`basename` were forwarded into `import_measurement_dataset`; `wizardState.setTarget` never ran.
- **Fix (v0.8.3):** `select_dataset_file` (open, filters `ti3/txt/cgats/csv`); sync wizard target dir+basename from the imported artefact.
- **Invariant:** Import = **open** dialog. After import, `basename`/`cwd` are initialized from the dataset before any stage jump. Do not reuse the target-save picker.

---

### 2.4 Stage 2 — printtarg

**`#50` Redundant Stage 2 badges (cleanup)**
- **Fix:** Remove duplicate status text. Not a functional invariant beyond "one source of layout truth".

**`#58` / `#70` TIFF previews fail in WebView; `image` crate Windows-only**
- **Root cause:** Browsers/WKWebView/WebView2 do not decode TIFF. `img.src = base64(tiff)` is a blank. `image` was under `[target.'cfg(windows)'.dependencies]` (GDI print), so Linux/macOS could not even compile a converter.
- **Fix:** Move `image` (png+tiff features) to common deps; `read_tiff_preview_png` decodes, caps ~1200 px, returns PNG base64. Keep `read_file_base64` for **text** artefacts (`.gam`).
- **Invariant:** Never feed TIFF to `<img>`. Preview pipeline is always TIFF→PNG in Rust. The `image` crate is a **common** dependency, not Windows-only.

**`#68` printtarg JSON parsed by hunting for a brace**
- **Root cause:** String-index search for `{\n  "event": "manifest"` instead of a structured object.
- **Fix:** Parse a single JSON event (Argyll `#3` `-u` manifest).
- **Invariant:** `-u` tools emit one JSON object per event. Accumulate stdout, `JSON.parse` whole objects; do not `indexOf` pretty-printed fragments.

**`#163` Regenerating Stage 2 shuffles patches (printed sheet ≠ `.ti2`)**
- **Root cause:** `printtarg` randomizes layout unless `-R <seed>` or `-r`. `build_printtarg_args` passed neither.
- **Fix (v0.5.5):** Default `-R 1`; optional custom seed and raster-order `-r`.
- **Invariant:** Printed charts are not reproducible without an explicit seed. Default is **deterministic**. Re-running Stage 2 on the same `.ti1` must produce the same `.ti2`/`.tif` or `chartread` will score the wrong patches.

**`#119` (feature, not bug) `printtarg -d` is a *label*, not a directory**
- See idiosyncrasies. Do not confuse with `iccgamut -d` (`#112`).

---

### 2.5 Stage 3 — chartread / averaging / XY

**`#109` Multi-pass averaging overwrites the same `.ti3`**
- **Root cause:** `#87` UI shipped, but every `chartread` wrote `{basename}.ti3`. Pass 2 clobbered pass 1. `average` was invoked as `foo.ti3 foo.ti3 foo.ti3`.
- **Fix:** After each successful exit, snapshot `{basename}.ti3` → `{basename}_pass{N}.ti3`. Canonical `{basename}.ti3` is written only at Finish (copy of pass1, or `average -v pass1 pass2 … basename.ti3`). Do **not** change the `chartread` inoutfile (still must match `.ti2` basename).
- **Invariant:** Measurement identity ≠ averaging identity. `chartread` always uses the chart basename. Pass files are snapshots. Stage 4 never sees a pass file unless Finish has run.

**`#110` Stage 4 unlocks on first pass, before Average**
- **Root cause:** `process:exit` of pass 1 called `wizardState.setStage3Result`. `verify_stage_artefacts` saw `{basename}.ti3` and enabled Stage 4 while "Measure Another Sheet" was still offered.
- **Fix:** Same PR as `#109`. `setStage3Result` only from **Finish and Average** / Accept-single-pass. Prefer the canonical-file rule over a new `stage3_accepted` flag.
- **Invariant:** Wizard gates on **disk artefacts with defined meaning**. `{basename}.ti3` means "accepted measurement", not "a pass happened".

**`#111` `instlist` ordinal passed as `chartread -c`**
- **Root cause:** Dropdown `value = inst.index` (1-based instrument list). `build_chartread_args` emitted `-c {index}`. Argyll `-c` is a **communication port** list (`chartread -??`), a different enumeration. Works by coincidence for a single USB i1Pro on port 1.
- **Fix:** Do not assume ordinal equality. Use `instlist` as presence/health; pass `-c` only when the value is a documented comm-port. Tighten regex to require instrument tokens.
- **Invariant:** `instlist` index ≠ `-c` port. After JSON `instlist` (argyll `#6` / ICCery `#134`), the field to pass is `device.port`, never the array index, and only if it is a real comm port.

**`#137` (feature) Accept/Override + multi-sheet prompts**
- Chartread emits multi-key warnings. UI must send the exact key (`n`/`y`/…) the prompt asks for, not just Enter.

**`#175` Stage 3 cannot complete — never sends `d`**
- **Root cause:** After the last strip, `chartread` waits for `d` (Done) before writing `.ti3`. ICCery never sent it. Follow-on: `snapshot_ti3` IPC used `passIndex` vs the deserializer's expected key.
- **Fix (v0.6.7–0.6.8):** Explicit **Done & Save .ti3** → `d\n`; **Undo Strip** → `u\n`; completion state machine; `invoke("snapshot_ti3", { passIndex })` camelCase to match Tauri v2 serde rename.
- **Invariant:** `chartread` is not finished when the last row JSON arrives. Done is a **keystroke**. Tauri v2 IPC argument names are camelCase on the JS side. Always add a completion control rather than inferring EOF.

**`#93` XY tables (SpectroScan / i1iO)** — feature, but its invariants are bug-shaped: classify **multi-line** prompts; fiducial alignment is a 4-step checklist; cancel must **park the head**.

**`#204` i1Pro2 LEDs** — pass `-Y l` (not `-L`). Silent no-op on instruments without LEDs.

---

### 2.6 Stage 4 — colprof

**`#56` Stage 4 is broken (IPC schema / process-id mismatch)**
- **Root cause:** `colprof.js` sent `{ basename, cwd }`. Rust expected `{ ti3_path, icc_path }`. Process IDs disagreed (`colprof_${basename}` vs `colprof_{icc_path}`), so UI listeners never fired even on a successful spawn.
- **Fix (PR `#64`, v0.1.11):** Align struct, argv builder, and process id with the frontend.
- **Invariant:** Spawn id is a **protocol**. Frontend listen-filters and backend spawn ids are the same string. Serde structs are tested against the JS payload, not against a parallel imagined schema.

**`#69` Profile extension `.icm` (Windows) vs `.icc` (Unix)**
- **Root cause:** Hardcoded `${basename}.icc`. Argyll `colprof` writes `.icm` on Windows. `profcheck` / `iccgamut` then "cannot find profile".
- **Fix:** Platform-aware resolver, or existence-check both extensions. Used by Stage 5 and gamut (`#57`).
- **Invariant:** Never hardcode `.icc`. Resolve `{icc, icm}` on disk. This also applies to install (`#223`) and preconditioning (`#172`).

**`#176` OBA/FWA + viewing conditions** — feature. `colprof -c` / `-d` here are **illuminant / viewing condition**, not directories and not `printtarg -d` labels.

**`#210` Custom `.sp` Browse: `window.__TAURI__.dialog` TypeError**
- **Root cause:** Identical to `#103`. No `select_spectrum_file` command.
- **Fix (v0.8.3):** Native `select_spectrum_file` (filter `.sp`).
- **Invariant:** Same as `#103`. Third time this class of bug shipped (`#103`, `#210`, `#211`). A rewrite should have a single `pick_file { filters }` command and never touch `window.__TAURI__.dialog`.

---

### 2.7 Stage 5 — gamut / profcheck / history

**`#57` 3D gamut is a dead panel**
- **Root cause:** `extract_gamut` / `loadGamutMesh` existed but nothing called them after `colprof`. `initGamutViewer` never stored meshes. Blocked by `#56` and `#69`.
- **Fix (v0.1.14):** Run `iccgamut` after successful profile; load printer `.gam` + bundled `sRGB.gam`; dispose previous geometries; `ResizeObserver` on the hidden Stage 5 canvas.
- **Invariant:** Gamut is a **post-colprof artefact**, not a demo mesh. Viewer must not allocate WebGL until the stage is shown (`#225`).

**`#112` `iccgamut -d 50.0` is surface density, not a directory**
- **Root cause:** `extract_gamut` passed `-d 50.0`. In Argyll, `iccgamut -d s` is **surface point density** (useful ~1–10). Density 50 yields thousands of vertices and freezes the O(n²) hull filter. Cwd is already set on the spawn.
- **Fix (PR `#121`):** `-d 10`; extract `build_iccgamut_args`; unit-test argv. Do not pass `-w` (VRML) unless required.
- **Invariant:** `-d` is **not** "directory" on `iccgamut`. Cwd is a ProcessManager concern. Density default is 10. Argv builders exist so this cannot silently regress.

**`#179` Mesh empty; profcheck cards show 0.00**
- **Root cause:** `.gam` has **two** CGATS tables (vertices `VERTEX_NO LAB_L LAB_A LAB_B`, then faces `VERTEX_0 VERTEX_1 VERTEX_2`). Parser kept only the first `BEGIN_DATA` and produced `{L,a,b}`. QuickHull indexed `p.x/p.y/p.z` → all undefined → empty hull. Profcheck regex expected one wording of `errors(CIEDE2000): max. =`; real output variants yielded 0.
- **Fix (v0.7.0):** Dual-table parse; map `x=a*, y=L*, z=b*`; use file faces when present; broader max/avg/rms regexes + user-visible parse warnings.
- **Invariant:** `.gam` is two tables. Lab is not XYZ-style `{x,y,z}` until remapped. Profcheck text is not a stable API — prefer `profcheck -u` JSON (argyll `#5`) and keep regex as fallback only.

**`#117` Inlined QuickHull** — modularize under `src/js/vendor/quickhull.js` (and later prefer file faces over recomputing hulls).

**`#185` Gamut rework** — CIELAB axes + CSS2D labels, `EdgesGeometry` sRGB reference, per-vertex `labToSrgb()`, layer toggles. Invariant: reference overlay is edges, not a competing solid that hides the profile.

**`#212` `gamut_viewer.test.js` : `window is not defined`**
- **Root cause:** Module top-level `const { invoke } = window.__TAURI__.core`. Node test import evaluates that before any polyfill. Unlike `profcheck.test.js` / `chartread.test.js`, no `globalThis.window` mock and no CLI auto-run.
- **Fix:** Guard `typeof window !== 'undefined'`; polyfill in the test; `node src/js/gamut_viewer.test.js` must exit non-zero on failure. Later `#215` runs this in CI.
- **Invariant:** Frontend modules that `import` in Node tests cannot touch `window` at load time. Tests are first-class; if AGENTS.md documents `node src/js/….test.js`, CI must run it (`#215`).

**`#213` `verification_history.json` non-atomic write**
- **Root cause:** `fs::write` in place. Crash ⇒ truncated JSON. `load_history_file` treats parse failure as **empty vec**, so the next save wipes the archive. Contradicted AGENTS.md's own atomic-write rule.
- **Fix (v0.8.4):** Write `.tmp`, flush/sync, `rename`.
- **Invariant:** History files are append-only user data. Write temp+rename. Parse failure must **not** be indistinguishable from "no history".

**`#95` Drift analytics** — 1,000-record cap, SVG dual-series, consecutive-breach card, RFC-4180 CSV. Relies on `#213`.

---

### 2.8 macOS window / WebKit

**`#61` Default window 800×600**
- **Fix:** 1280×800 default, min 1100×700.
- **Invariant:** The wizard + TIFF cards + WebGL viewer are not a mobile layout. Set min bounds in `tauri.conf.json`.

**`#148` Align `minimumSystemVersion` with Argyll**
- Argyll macOS builds and Tauri 2 / WebGL do not support 10.15 in practice.

**`#165` Unsigned Argyll sidecars `SIGKILL` on Apple Silicon**
- **Root cause:** arm64 requires at least ad-hoc signature. `fetch-argyll.mjs` staged Jam-built unsigned Mach-Os into Resources. Kernel kills with `Killed: 9`, no useful error.
- **Fix:** Upstream argyll `#32` (`v3.5.0-ICCery.1.5`) `codesign -f -s -` in `makepackagebin.sh` + CI `codesign -dvv`, including `lipo` fat binaries.
- **Invariant:** Every shipped Mach-O sidecar is signed (ad-hoc at minimum). Fetch pipeline must verify signatures, not assume "it ran on Intel".

**`#164` Universal binary (Intel + arm64)**
- Need universal Argyll archive (argyll `#27`), runtime fallback if a slice is missing, CI `--no-run` when cross-compiling tests for the other arch.

**`#225` Monterey white-flash loop then silent exit (v0.8.4)**
- **Root cause:** Main window `visible: true` with no dark backing. `initGamutViewer()` created `THREE.WebGLRenderer({ antialias: true, alpha: true })` and started rAF at `DOMContentLoaded` **while Stage 5 was hidden**. On macOS 12 (esp. Intel GPU) the Web Content/GPU helper died; WKWebView respawned its **white** default store; after a few cycles the host tore the window down. No Crash Reporter on `ICCery.app`. `minimumSystemVersion` still claimed 10.15.
- **Fix:** Defer WebGL until the gamut viewer is shown; survive context-lost; hide window until first paint; dark WKWebView `backgroundColor`; log unexpected window destroy / Web Content death; raise `minimumSystemVersion` to **12.0**.
- **Invariant:** Do not create a WebGL context at startup. Do not show a window before first paint on macOS. Helper-process death ≠ app crash — log it. Support matrix must match WKWebView/WebGL reality.

---

### 2.9 Packaging / CI

**`#38` Unused / duplicated crates** — audit deps; don't let Windows-only crates leak (inverse of `#70`).

**`#40` Linux CI too slow**
- **Fix (PR `#41`):** Allow strip (`NO_STRIP` off), rust-cache `workspaces: "src-tauri -> target"`, apt archive cache, `--bundles deb,appimage` (skip rpm), upload-artifact v4.

**`#42` Windows MSI/NSIS branding.**

**`#52` Strip foreign-platform Argyll binaries from each OS bundle.**
- **Invariant:** A Windows installer must not ship `linux-x86_64/` and `macOS/` trees. Fetch-at-build (`#127`) makes this a packaging filter, not a git-lfs problem.

**`#80` Mermaid diagram does not render**
- **Root cause:** Node label `Raw Print Subsystem (GDI / CUPS)` — parentheses parsed as shape syntax.
- **Fix:** Quote / drop parens.
- **Invariant:** Mermaid node text with `()` must be quoted.

**`#91` Universal `.dmg` + codesign pipeline (still evolving through `#189`).**

**`#108` `.deb` requires GLIBC_2.39 (won't run on Ubuntu 22.04)**
- **Root cause:** Linux CI runner newer than the support target. Binary linked against glibc 2.39; 22.04 ships 2.35.
- **Fix (v0.3.2):** Build on **Ubuntu 22.04 LTS**.
- **Invariant:** The CI image **is** the minimum glibc. If you support 22.04, you build on 22.04 (or older), not `ubuntu-latest`.

**`#127` Fetch Argyll at build time + Windows USB driver offer**
- Removed vendored binaries. NSIS hook for `ArgyllCMS_install_USB.exe`. Follow-on Windows NSIS bugs in the same train: LogicLib admin check, domain-user install path must be a local fixed disk, shell-folder drive mapping, skip WebView2 bootstrapper `msiexec` invalid-drive.
- **Invariant:** Sidecars are release artefacts of `gronod/argyllcms`, not git blobs. Windows USB instruments need the libusb0 INF. Packaging scripts must `tr -d '\r'` manifest lists (argyll `#21` — CRLF in `binfiles` dropped drivers/docs from the zip).

**`#189` DMG has no background image**
- AppleScript Finder decoration does not run headlessly. Multiple CI attempts (`#196`, `#208`, `#219`) then **dmgbuild** (`#222`, commit `6976ced`).
- **Invariant:** Do not use Finder AppleScript to style a DMG on a headless runner. Use `dmgbuild`.

**`#215` Frontend tests not in CI**
- Added `npm test` (profcheck, chartread, gamut_viewer) to macOS/Linux/Windows workflows. Prevents `#212`-class breakage.

**`#214` Docs drift** — AGENTS/README/licenses vs code. Keep ROADMAP version = Cargo version (`#115`, `#152`).

---

### 2.10 Security (innerHTML presets)

**`#114` Preset manager XSS via `innerHTML`**
- **Root cause:** `renderManagePresetsList` interpolated `p.name` / `p.description` into `innerHTML`. Imported JSON is attacker-controlled. Tauri WebView is a privileged surface (`<img src=x onerror=…>` runs with backend IPC).
- **Fix (PR `#122`, with `#113`):** `createElement` + `textContent`. Optional Rust reject of `<` / control chars. **No** HTML sanitizer.
- **Invariant:** Untrusted strings (preset import, CGATS descriptors, chart labels, log excerpts) never go through `innerHTML`. `textContent` only.

---

### 2.11 Settings / presets / wizard chrome

**`#113` `applyPreset` never applies TIFF DPI**
- **Root cause:** Schema had `dpi`; Fast RGB Draft is 150. `applyPreset` skipped `#tiffDpi`; `collectCurrentSettingsAsPreset` hardcoded `dpi: 300`.
- **Fix:** Round-trip `#tiffDpi` (72–600); show DPI in manage-presets subtitle.
- **Invariant:** Every `ProfilingPreset` field that exists on disk has a DOM binding in both directions. Adding a Stage 1/2/4 control without a preset field (or vice versa) is a bug. (v0.7.0 also broke the build by adding fields without updating the struct — `c917f05`.)

**`#60` Wizard is not a wizard**
- **Root cause:** Stepper allowed clicking Stage 5 with no files. Modules fell back to `"test_target"`.
- **Fix (v0.1.15 / v0.2.0):** Gate `.ti1` → `.ti2`+`.tif` → `.ti3` → `.icc`/`.icm`. Remove every `|| "test_target"`. Completed stages remain clickable backwards.
- **Invariant:** No placeholder basenames. Navigation = disk. `#151` re-validates artefacts on stage entry and app start (deleted files must re-lock).

**`#171` Tooltips reflow the layout**
- **Root cause:** Tooltip content inserted in-flow.
- **Fix (v0.6.2):** Absolute overlay on hover/focus; in-flow hints only when the global "show tooltip hints" toggle is on.
- **Invariant:** Hover must not change document flow.

**`#184` Configurable ΔE₀₀ thresholds** — settings persistence applied to the Stage 3 traffic lights. Same "settings must actually apply" rule as `#158`.

---

### 2.12 UI leftovers that still encode invariants

**`#178` Swatch grid:** honour `is_pad` (padding patches, `id == "0"`); render white patches; diagonal split intended vs measured; `printtarg` row/column order is canonical after bi-directional reverse. Device channels are 0–100%; XYZ in JSON is 0–100 and **must be /100** before `icmXYZ2Lab`.

**`#177` Buttons:** `.btn-sm/.btn-md/.btn-lg/.btn-icon-sq` only. No inline sizes. `#223` install button must use this hierarchy.

**`#140` Resume:** opening a `.ti2` jumps to Stage 3; `.ti1` to Stage 2. Parse header (instrument, patch count, colorants, pages). Do not regenerate `#163`-style random layouts over a chart that was already printed.

---

## 3. Open issues — implemented on main (`v0.8.5`)

Gitea still shows these as **open**. Git on `main` (merge `e12ef41`, tag `v0.8.5`) already contains the work. ROADMAP "Printer Calibration Release (`v0.8.5`)" matches.

| Ticket | State in tracker | Evidence on `main` | What shipped |
|---|---|---|---|
| **`#223` System-wide ICC/ICM install** | open | `980b44b` `feat(stage5): install generated ICC/ICM profiles into the OS (#223)` ; PR `#228` → development; PR `#229` → main | Stage 5 "Install Profile to System": copy into OS colour store (user or system), overwrite/rename/cancel, elevation guidance, note when printcal curves were applied |
| **`#224` printcal / applycal** | open | `24318bc` `feat(cal): printer linearization via printcal / applycal (#224)` ; PR `#227` → development; PR `#229` → main | Optional Stage 0: `CAL_` artefacts, Apply Calibration toggle → `printtarg -K` + `applycal`, channel-response plots, stale-cal warnings, project/library persistence |

Rewrite must treat Stage 0 calibration and Stage 5 install as **shipped** contracts, not backlog. Close the tickets when convenient.

---

## 4. Won't-fix

### `#90` Display wizard (`dispwin` / `dispread`) — Reviewed/Won't Fix

Asked for a second wizard mode: emissive monitor profiling (white point, gamma, cd/m², colorimeter loop, `dispwin -I` install).

**Why not:**
- ICCery's architecture, print engine, artefact chain (`.ti1`→`.tif`→`.ti3`→`.icc`), and raw-print colour-bypass work are **reflective printer** problems. Display calibration is a different product (full-screen test patches, VCGT, per-monitor ColorSync/ICC install).
- `dispwin`/`dispread` already *are* interactive GUIs; wrapping them duplicates Argyll's own display tools and DisplayCAL without sharing the print pipeline.
- Hardware, prompts, and OS install APIs do not reuse Stage 3's strip-reader state machine.
- Priority/Low, closed the same day it was filed during M8 triage. Printer-only scope is the product.

Do not quietly add a "Print vs Display" toggle in a rewrite. If display profiling happens, it is a separate app.

### `#96` i18n (en/de/fr/ja) — Reviewed/Won't Fix

ROADMAP: *Closed — Won't Fix (English UI retained as standard color-management terminology).*

**Why not:**
- The domain language **is** English: ΔE₀₀, cLUT, CGATS, Lab, FWA, OFPS, `targen -f`. Translating chrome without translating Argyll's English prompts (`Place the instrument on its reflective white reference…`) produces a mixed UI. Translating prompt matchers (`#137`, `#93`, `#175`) is how Stage 3 silently deadlocks.
- Argyll itself is English-only; `ARGYLL_NOT_INTERACTIVE` keystroke protocol is letter keys (`d`, `u`, `n`), not localized buttons.
- Cost of four complete dictionaries + locale-aware regex across every prompt classifier exceeded the value for a specialist tool.

Keep the UI English. Do not introduce `t()` until prompt classification is table-driven **and** Argyll grows locale support — which it will not.

---

## 5. Idiosyncrasies (do not rediscover)

These are the sharp edges issues burned in. A rewrite that "simplifies" any of them will re-open the ticket.

### 5.1 Argyll CLI is a minefield of one-letter flags

| Tool | Flag | Means | Ticket |
|---|---|---|---|
| `targen` | `-f N` | patch count; omit ⇒ **836** RGB | `#44` |
| `targen` | `-c file` | preconditioning **profile** (`.icc/.icm/.mpp`) | `#172` |
| `targen` | `-u` | JSON progress | argyll `#2` |
| `printtarg` | `-d "str"` | **custom label** on the chart | `#119` / argyll `#19` |
| `printtarg` | `-D` | 8-bit TIFF dither (different letter) | argyll `#19` |
| `printtarg` | `-R N` | PRNG seed; omit ⇒ non-deterministic layout | `#163` |
| `printtarg` | `-r` | raster order, no randomize | `#163` |
| `printtarg` | `-K` | apply calibration (Stage 0) | `#224` |
| `printtarg` | `-u` | JSON page manifest | `#68` / argyll `#3` |
| `chartread` | `-u` | `ROW_COLORS_JSON:` stream | `#5` / argyll `#1` |
| `chartread` | `-c N` | **comm port**, not instlist index | `#111` |
| `chartread` | `-d` | **display** read mode (not a directory, not a label) | argyll `#37` audit |
| `chartread` | `-Y l` | i1Pro2 LED (not `-L`) | `#204` |
| `chartread` | stdin `d` | **Done**, write `.ti3` | `#175` |
| `chartread` | stdin `u` | undo last strip | `#175` |
| `iccgamut` | `-d s` | **surface density** (use 10, not 50, not a path) | `#112` |
| `colprof` | `-d` | viewing condition | `#176` |
| `colprof` | `-c` | illuminant / FWA | `#176` |
| `colprof` | `-u` | JSON progress | argyll `#4` |
| `profcheck` | `-u` | JSON ΔE report | argyll `#5` |
| `instlist` | stdout JSON | `{event:"instruments", devices:[{port,name,type}]}` | `#134` / argyll `#6` |

**Same letter, four meanings of `-d`:** printtarg label, iccgamut density, chartread display mode, colprof viewing condition. Never name a helper `dash_d` without the tool.

### 5.2 Process / Windows / stdin

- Argyll binaries are **console** subsystem → `CREATE_NO_WINDOW` (`0x08000000`) (`#46`).
- `ARGYLL_NOT_INTERACTIVE=1` is mandatory or Windows ignores pipes (`#134`).
- Even then, Argyll's `SetNamedPipeHandleState(PIPE_NOWAIT)` **fails on anonymous pipes**; upstream `PeekNamedPipe` (argyll `#24`) is required or the instrument trigger never fires.
- `Child::wait()` drops stdin (`#84`). Take streams first; store stdin separately; kill via oneshot.
- Spawn ids are exclusive (`#116`).
- App exit must `kill_all` (`#147`, `#149`) or the spectro stays locked.
- Windows resolve: `targen` **and** `targen.exe` (`#85`).
- `tokio::process` + GDI print FFI: don't trust `windows` crate completeness (`#33`).

### 5.3 Files, extensions, artefacts

- `colprof` writes **`.icm` on Windows, `.icc` on Unix** (`#69`). Always probe both.
- Wizard chain: `.ti1` → `.ti2` + `.tif` → `.ti3` → `.icc`/`.icm` (+ `.gam`) (`#60`, `#151`).
- `{basename}.ti3` is the **accepted** measurement; passes live in `{basename}_passN.ti3` (`#109`, `#110`).
- Calibration artefacts use `CAL_` prefix and `.cal` (`#224`).
- TIFF is not a web image (`#58`). Convert in Rust.
- `.gam` = vertex table **plus** face table (`#179`).
- History JSON: atomic rename or you delete the user's drift archive (`#213`).
- Empty cwd is forbidden (`#59`).

### 5.4 Frontend / Tauri v2

- `window.__TAURI__.dialog` **does not exist**. Three tickets (`#103`, `#210`, `#211`). File dialogs are Rust commands with dedicated filters.
- Tauri v2 invoke args are **camelCase** (`passIndex`, not `pass_index`) (`#175`).
- JS payload field names must match Rust (`patch_count` vs `total_patches` — `#44`; `basename/cwd` vs `ti3_path/icc_path` — `#56`).
- Spawn id strings are part of the UI protocol (`colprof_${basename}`).
- Do not `innerHTML` untrusted preset/CGATS text (`#114`).
- Do not read `window` at module top-level if Node tests import the file (`#212`).
- Do not create WebGL on `DOMContentLoaded` (`#225`).
- Tooltips are overlays (`#171`).

### 5.5 Colour / print pipeline

- Raw print = unmanaged raster. Bypass **OS + driver + ICM** (`#25`–`#28`, `#36`, `#188`).
- Windows: full DEVMODE blob including `dmDriverExtra` (`#36`); `SetICMMode(ICM_OFF)` (`#33`).
- macOS: `AP_ApplicationColorMatching` + vendor keys (`CNIJIntent2`, Epson `ColorCorrection`); never crash-call 3-arg `PMSessionSetColorMatchingMode` (`#188`).
- PPD: send **choice codes**, display **titles**; vendor keywords differ (`InputSlot` / `EPIJ_FdSo` / `CNIJMediaSupply`; `MediaType` / `CNIJMediaType`) — CPU `#1`/`#2`.
- Hide CUPS widgets on Windows (`#48`).
- Default printtarg seed `-R 1` (`#163`).
- Device JSON is 0–100%; XYZ 0–100 must be divided by 100 before Lab (`ROW_COLORS_JSON` contract, argyll `#1`).
- Padding patches: `is_pad` / `id == "0"` (`#178`).

### 5.6 Packaging

- Linux: build on the oldest glibc you support (`#108` = Ubuntu 22.04).
- Strip foreign Argyll trees (`#52`).
- Fetch sidecars from `gronod/argyllcms` releases (`#127`); verify macOS ad-hoc signatures (`#165`).
- Manifest copy loops: strip CR (`\r`) or Windows zips silently omit USB drivers (argyll `#21`).
- Headless DMG: `dmgbuild`, not Finder AppleScript (`#189`).
- `minimumSystemVersion` is 12.0 after Monterey WebKit reality (`#225`), not 10.15.

### 5.7 Defaults people will hardcode wrong

- Patch count default if `-f` missing: **836**, not 0, not 1000 (`#44`).
- TIFF DPI built-in Standard = 300; Fast RGB Draft preset = **150** (`#113`).
- `iccgamut -d` = **10** (`#112`).
- Window 1280×800, min 1100×700 (`#61`).
- Log level is a setting, not `cfg!(debug_assertions)` (`#158`).
- LED flag is `-Y l` (`#204`).

---

## 6. Suggested rewrite test locks (from the tickets)

If the rewrite has tests, these are the ones the history says you will regret omitting:

1. `build_targen_args` includes `-f` from `patch_count` (`#44`).
2. `build_printtarg_args` includes `-R 1` (or explicit seed) (`#163`).
3. `build_iccgamut_args` is `-v -d 10 {profile}` — never a path, never 50 (`#112`).
4. `build_chartread_args` does not pass instlist ordinal as `-c` (`#111`).
5. Windows `resolve_binary("targen")` finds `targen.exe` (`#85`).
6. ProcessManager: duplicate id errors; stdin works during wait; kill_all on drop (`#84`, `#116`, `#149`).
7. Averaging: two snapshots, `average` argv unique files, Stage 4 locked until Finish (`#109`, `#110`).
8. Preset round-trip includes DPI; imported `<img onerror>` is text (`#113`, `#114`).
9. Profile resolver accepts `.icc` and `.icm` (`#69`).
10. `.gam` dual-table parse; profcheck JSON then regex fallback (`#179`).
11. History write is temp+rename (`#213`).
12. Node can `import` gamut/profcheck/chartread modules (`#212`, `#215`).

---

## 7. PR title index (page 2, remaining)

Page 2 of `pulls?state=all&limit=50&page=2` (older half of the genealogy):

`#144` Stage 1 advanced targen (`#141`) · `#143` resume `.ti2` (`#140`) · `#142` logging (`#139`) · `#138` Accept/Override (`#137`) · `#136`/`#135` v0.3.5 `ARGYLL_NOT_INTERACTIVE` (`#134`) · `#133` v0.3.4 · `#132` printtarg `-d` (`#119`) · `#131` v0.4.0 · `#130` macOS CUPS (`#92`) · `#129`/`#128` fetch-argyll (`#127`) · `#126` v0.3.3 · `#125` QuickHull module (`#117`) · `#124` docs v0.3.2 (`#115`) · `#123` duplicate spawn (`#116`) · `#122` preset DPI+XSS (`#113`,`#114`) · `#121` iccgamut density (`#112`) · `#120` comm port (`#111`) · `#118` averaging unique ti3 (`#109`,`#110`) · `#107` release asset naming · `#105`/`#104` Stage 1 browse (`#103`) · `#102` v0.3.0 · `#101` 3D hull (`#89`) · `#100` presets (`#88`) · `#99` averaging (`#87`) · `#98` instlist (`#86`) · `#97` `.exe` (`#85`) · `#83` process deadlock v0.2.1 (`#84`) · `#81` mermaid (`#80`) · `#79` print IPC consolidate (`#67`,`#68`) · `#77` wait/reap (`#63`) · `#75` wizard gating (`#60`) · `#74` gamut+extension (`#57`,`#69`) · `#73` TIFF PNG + window (`#58`,`#61`) · `#72` default cwd (`#59`) · `#64` colprof IPC (`#56`) · `#55` collapsible logs (`#54`) · `#53` strip foreign binaries (`#52`) · `#51` Stage 2 cleanup (`#50`) · `#49` hide CUPS on Windows (`#48`) · `#47` `CREATE_NO_WINDOW` (`#46`) · `#45` targen `-f` (`#44`) · `#43` installer art (`#42`) · `#41` Linux CI (`#40`)

Recent page-1 merges of note: `#229` v0.8.5 (`#223`+`#224`) · `#228` install · `#227` printcal · `#226` Monterey (`#225`) · `#222` dmgbuild (`#189`).