feat: add overexposed_frame_pct to frame stats

[Sagar-024]

Summary

Adds overexposed_frame_pct to FrameStats and records it per camera topic in camera_frame_stats. Closes #33.

Blackout already has black_frame_pct, but the symmetric failure (blown highlights from bad exposure, IR flood, or sun in frame) had no counterpart, and luma_avg_max alone cannot distinguish one bright frame from a thousand. The new measurement is the percentage of frames whose average luma is at or above bright_luma_threshold (default 235.0; thresholds stay user-owned), computed from the existing luma_avg_values list with the same frame-count denominator as black_frame_pct. No new ffmpeg filter, no second decode pass.

Changes

• src/hflow/ffmpeg/_instrument.py: FrameStats gains overexposed_frame_count and overexposed_frame_pct; frame_stats() and _stats_from_instrument_output() gain bright_luma_threshold.
• src/hflow/checks.py: camera_frame_stats threads the threshold and records {topic}/overexposed_frame_pct next to black_frame_pct.
• tests/test_ffmpeg.py: synthetic instrument-output test with exact math at the default threshold, plus a white-tail real-video test exercising the threshold parameter.
• tests/test_checks.py: asserts the measurement is surfaced as 0.0 on a non-bright camera fixture.

Validation

• uv run ruff check --fix && uv run ruff format
• uv run ty check (only pre-existing Windows platform diagnostics; none in the new code)
• uv run pytest -q tests/test_ffmpeg.py tests/test_checks.py (all new tests pass; 2 pre-existing Windows failures unrelated to this change: test_env_override_wins, test_local_install_extracts_both_binaries_and_executes)

Checklist

• Outcome-focused tests for the new measurement (synthetic exact math, real video, checks surfacing)
• Docstrings updated where thresholds and measurements are documented
• ruff, ty, and pytest run
• git status contains no unrelated files

[kstonekuan]

Thanks @Sagar-024! Validated locally: quality gate and full suite pass (298 tests). This matches #33 exactly, and the test work is excellent: the pure-text aggregation case, the white-tail fixture with the freezedetect guard (nice catch that 2s of identical white frames would otherwise register as a freeze), and the limited-range-white threshold note all show real understanding of the instrument. Merging.

One gentle ask for next time: you are well past needing the training wheels, so we would love to keep the good first issue pool for brand-new contributors when possible. A more valuable direction for someone at your level: run HFlow against a real corpus like Egocentric-10K (or the 100K variant) and tell us what breaks, what is slow, or what is awkward. Real-data findings like your #24 measurement are the highest-leverage contributions this project can get right now.