ccolors/PLAN.md

Here is the phased roadmap to achieve the project objectives while strictly adhering to the single-file and architectural constraints.

1. Phase 1: Test Framework & Baseline Verification

• What will be done: Create an end-to-end integration test suite using a script (e.g., test.sh or test_runner.py). This will include generating minimal valid (JPEG/PNG) and invalid test images. The script will execute the ccolors binary and assert against the terminal stdout and the generated palette.json.
• Why in this order: Because the architecture forces a single-file design without separation of concerns, traditional unit testing is impossible. A black-box integration test suite must be established first to provide a safety net before any internal refactoring or optimizations occur.
• Definition of "Done": The test script is fully executable (ideally integrated into ctest via CMake), runs automatically, and successfully validates the "happy path" (successful color extraction) and error paths (file not found, invalid format).
• Risk: Extremely low risk as no production code is altered. Rollback: Delete the test script and revert CMakeLists.txt.

2. Phase 2: Core Debugging & Memory Optimization

• What will be done:
  1. Debug: Fix the file header check logic. Currently, file.read(..., 8) assumes the file is at least 8 bytes long. Furthermore, the file is read twice (once manually, once by stbi_load). This will be streamlined.
  2. Optimize: Eliminate the intermediate std::vector<Pixel> samples array. The brightness/saturation filtering and 16x16x16 histogram bucket accumulation will be calculated directly inside the x and y downsampling loops.
• Why in this order: Fixing immediate crash risks on tiny/invalid files and removing unnecessary heap allocations (std::vector overhead) provides a robust, highly performant foundation before introducing new features.
• Definition of "Done": The vector<Pixel> is entirely removed from the codebase, the program compiles without warnings, and the Phase 1 integration tests all pass.
• Risk: The color quantization or sampling logic might inadvertently change, causing incorrect hex outputs. Rollback: git checkout the main.cpp file to its Phase 1 state.

3. Phase 3: Ease of Use Improvements

• What will be done: Improve error messages and standard output control. Integrate stbi_failure_reason() to tell the user why an image failed to load (e.g., corrupted file vs. unsupported format). Add a --quiet (-q) CLI flag to suppress standard terminal output, making the tool friendly for automated scripts.
• Why in this order: Usability features are best layered on top of a stable, optimized processing core.
• Definition of "Done": Running ccolors corrupted.jpg prints a highly specific error message. Running ccolors image.jpg -q generates the JSON file but prints absolutely nothing to standard output.
• Risk: Modifying the argc/argv parsing loop might accidentally break standard positional arguments. Rollback: Revert main.cpp to its Phase 2 state.

4. Phase 4: New Feature Integration

• What will be done: Add an --output (-o) flag to allow users to specify a custom filename and path for the generated JSON file, replacing the hardcoded palette.json limitation.
• Why in this order: Adding new command-line routing introduces new code paths and file I/O operations. It relies on the extensible CLI parsing structure created in Phase 3.
• Definition of "Done": Running ccolors image.jpg -o /tmp/custom_colors.json successfully parses the image and writes the JSON output specifically to the requested path. A corresponding test is added to the Phase 1 test suite and passes.
• Risk: File stream failures (e.g., specifying a path in a non-existent directory or a read-only location) could crash the app if not handled gracefully. Rollback: Revert main.cpp to its Phase 3 state.

---

Optional (Speculative / "Nice to Have")

• HTML Visualizer: Add an --html <file> flag that outputs a standalone .html file with the extracted top 5 colors rendered as CSS colored blocks, providing a visual alternative to the terminal swatches.
• Multithreaded Downsampling: Utilize C++17 std::execution::par_unseq or #pragma omp parallel for to parallelize the color extraction loops for massive performance gains on extremely high-resolution images.