# Failing Crates Repair Plan

## Goal

Make the bulk Linux and Windows test runners complete without platform-feature build failures, preserve compilation coverage for the existing egui visual examples, and report the exact names of failed crates instead of only a count.

## Confirmed Findings

- `hcie-blend` fails because its `eframe` dev-dependency disables defaults without enabling either Linux backend; `winit 0.30.13` therefore emits “platform ... not supported”.
- The same manifest defect exists in `hcie-draw`, `hcie-filter`, `hcie-text`, and `hcie-vector`.
- `hcie-brush-engine` succeeds because it enables `x11`; `hcie-io` enables both `x11` and `wayland`.
- The root workspace already defines the intended cross-platform `eframe` configuration with `wayland` and `x11`.
- `hcie-text/Cargo.toml` currently repeats `proptest` and `approx`, which is a duplicate-key manifest error and must be fixed before any Cargo validation.
- The supplied terminal output proves one named failure (`hcie-blend`) and six failures in total. It does not expose all six names, so the prior six-name claim must not be treated as authoritative.
- `run_all_tests.*` and `run_tests_categorized.*` only retain failure counts. Their `--no-4k` command also places `--skip` on the Cargo side instead of after Cargo’s `--` test-harness separator.

## Implementation Steps

1. **Restore a valid workspace manifest.**
   - Remove the duplicate `proptest` and `approx` entries from `hcie-text/Cargo.toml`.
   - Run `cargo metadata --no-deps` immediately; stop if any other manifest error remains.

2. **Centralize visual-example GUI dev-dependencies.**
   - In `hcie-blend`, `hcie-brush-engine`, `hcie-draw`, `hcie-filter`, `hcie-text`, `hcie-vector`, and `hcie-io`, replace crate-local `egui = "0.34"` and custom `eframe` feature lists with `egui = { workspace = true }` and `eframe = { workspace = true }` under `[dev-dependencies]`.
   - Preserve all non-GUI dev-dependencies and existing visual examples.
   - Do not add GUI dependencies to runtime `[dependencies]` and do not modify engine source files.
   - This intentionally reuses the root’s `default_fonts`, `glow`, `persistence`, `wayland`, and `x11` configuration so platform support cannot drift between crates.

3. **Verify feature resolution before compiling.**
   - Use `cargo tree -p <crate> -e features -i winit` for the five confirmed failing crates and the two known-good comparison crates.
   - Confirm Linux builds activate at least one backend and the standardized configuration activates both `winit/x11` and `winit/wayland`.

4. **Improve test-runner diagnostics in both platform versions.**
   - Update `run_all_tests.sh`, `run_all_tests.bat`, `run_tests_categorized.sh`, and `run_tests_categorized.bat` to append every failed crate name to a failure list and every skipped crate name to a skip list.
   - Print those lists in the final summary while preserving pass/fail/skip counts and non-zero exit status.
   - In shell scripts, use arrays for Cargo arguments rather than a space-split string.
   - Fix the 4K exclusion to invoke `cargo test -p hcie-engine-api -- --skip benchmark_4k_stroke_on_multilayer_document`; apply equivalent quoting and argument ordering in `.bat` files.
   - Keep default `cargo test -p <crate>` behavior so examples are compiled; do not hide the defect by globally switching to `--tests`.

5. **Run focused crate validation.**
   - Run `cargo check -p <crate> --examples` and `cargo test -p <crate>` for `hcie-blend`, `hcie-draw`, `hcie-filter`, `hcie-text`, and `hcie-vector`.
   - Re-run `hcie-brush-engine` and `hcie-io` to detect regressions from dependency centralization.
   - For `hcie-io`, distinguish build/test failures from missing external PSD fixtures; fixture-dependent early returns are not platform compilation failures.

6. **Identify and repair the sixth failure from evidence.**
   - Run the improved Linux bulk runner first with `--no-io --no-4k` for deterministic feedback.
   - Read the emitted failed-crate list. If a failure remains outside the five confirmed manifests, capture its first compiler/test error and fix that crate’s actual cause rather than assuming another `winit` defect.
   - Re-run only the remaining failed crate until green, then repeat the deterministic bulk run.

7. **Complete end-to-end validation.**
   - Run `./run_all_tests.sh --no-io --no-4k`; require zero failed crates and verify the summary names no failures.
   - Run `cargo test -p hcie-io` separately with the expected fixture set or record fixture skips distinctly.
   - Run the 4K engine test explicitly with the protected command from `AGENTS.md` rather than silently omitting performance coverage.
   - Validate `.bat` parity on Windows (or Windows CI): targeted five-crate tests, `run_all_tests.bat --no-io --no-4k`, correct failed-name reporting, and non-zero exit code on an intentional failing command.

## Risks And Guardrails

- Enabling `x11`/`wayland` compiles native backend support but does not launch windows during tests; headless execution remains safe because examples are only compiled.
- Do not use cached success as proof. At least one validation pass should use a fresh dedicated target directory (`CARGO_TARGET_DIR=target/platform-test`) rather than deleting the shared target directory.
- Do not alter locked engine logic or protected performance mechanisms; this repair is confined to manifests and test runners unless the newly identified sixth failure proves independent.
- Do not relocate the visual examples in this repair. Removing all GUI dev-dependencies from engine crates would require a separate architecture migration into the GUI workspace.
- The Linux environment cannot establish Windows batch correctness alone; Windows execution is a required validation gate, not an inferred result.

## Acceptance Criteria

- `cargo metadata --no-deps` succeeds with no duplicate manifest keys.
- The five confirmed crates compile their examples and pass their tests on Linux.
- The bulk runner reports failed crate names and exits zero when all selected crates pass.
- `./run_all_tests.sh --no-io --no-4k` reports zero failed crates from a fresh target directory.
- Windows `.bat` behavior matches Linux for argument handling, result lists, and exit status.
- Any sixth failure is named and resolved from its own diagnostic output, not from dependency-based speculation.