Extend the radar loop from NOAA's 50 minutes to a configurable 24 hours

[turbo5000c]

Description

The Radar Loop image entity showed NOAA's ready-made animation, which is fixed at ten frames covering roughly 50 minutes. Only those ten frames exist on NOAA's server, so a longer loop cannot be downloaded — it has to be collected. This PR makes the entity collect one frame per refresh, file each under the time NOAA published it, and assemble the animation itself from an evenly time-spaced sample.

The window is a new options-flow step, defaulting to 24 hours. Setting it to 0 restores the previous behaviour exactly: NOAA's own loop, proxied unchanged, with nothing written to disk.

How it behaves

• The loop fills in over time. Below six frames the card shows NOAA's own loop instead, so it is never blank and never worse than before.
• Frames survive restarts, stored one small GIF per scan under <config>/noaa_it_all/radar_frames/<RADAR_SITE>/ — a few megabytes per radar site. Frames outside the window are pruned on every refresh. The directory is removed when the integration is deleted, when the entry switches to another office, and when the option is set back to 0 — unless another configured office still builds a loop from the same site.
• A 24-hour loop is capped at 72 frames (one every 20 minutes) and plays through in about ten seconds. Shorter windows are proportionally finer — a 6-hour loop keeps roughly one frame per scan.
• loop_mode reports which animation is on screen (local or upstream), alongside loop_hours, frame_count, window_start and window_end, so a loop quietly shorter than configured is visible from a template.

Two things the encoder has to get right, both pinned by tests that fail against the obvious implementation:

• Frames arrive separately palettised. Letting the GIF writer adopt frame one's palette as the global table remaps everything after it. Building the palette from frame one alone is wrong in a way that only shows up overnight: the loop starts on an empty radar, so the palette holds nothing but background, and the storm arriving hours later renders as background too. The palette is sampled across the whole window instead.
• Pillow merges pixel-identical neighbouring frames and sums their delays, so a clear night legitimately encodes to fewer frames than it has sources. Playback time and the hold on the newest frame both survive that, so it stands as free compression.

Behaviour changes worth calling out

• The locally built loop is opaque where NOAA's is transparent. Frames are composited onto solid black before being combined — reconciling per-frame transparency across differing palettes is the most reliable way to produce a psychedelic radar loop. Cards relying on transparency should set the option to 0.
• Cached HTTP validators are now kept per upstream resource. This entity fetches two URLs, and an ETag from the single frame must never be sent as a validator for the animation.

Not included: seeding the buffer from NOAA's ten-frame loop at first start. Its per-frame cadence is unpublished and varies by scan strategy, so every back-dated timestamp would be a guess polluting an otherwise exactly-timestamped buffer — for 50 minutes of history on a 24-hour feature that the upstream fallback already covers.

Review pass

A pre-merge review found fifteen issues, all fixed in d83fa39. Each fix is pinned by a test that fails without it.

The worst was a time bomb in this PR's own tests: the two end-to-end radar tests pinned frame timestamps to a calendar date while the code prunes against the wall clock, so from the next day every frame would have fallen outside the window and CI would have gone red with no code change. Timestamps now derive from the clock; verified by running the suite with the clock 2, 40 and 400 days ahead.

Correctness bugs that would otherwise have shipped:

• select_frames applied its window only after the "few enough frames, take them all" shortcut, so a buffer pruning had not caught up with built a loop from the wrong day and reported it as the configured window.
• Pruning ran only when a new frame was stored, so a radar site stuck on one scan for hours never pruned at all.
• The prune had no upper bound on frame age. A future-dated frame from a wrong clock is never reached by a backwards-looking cutoff, so it would outlive every real frame. The file cap did not help — it trims the oldest, and those frames sort newest.
• The oversize retry thinned with paths[::2], which drops the last frame whenever the count is even — the normal case at 72 — so the animation ended, and held, on a stale scan.
• The RADAR_LOOP_MIN_FRAMES floor was checked against every frame on disk rather than the sampled subset that actually ships, so a window with a long outage could send a four-frame loop in place of NOAA's ten.
• The canonical frame size came from the oldest frame, so after a NOAA product-size change every new full-resolution scan would be scaled back down for a whole window.

Regressions introduced earlier in this PR and fixed in the same commit:

• The single validator slot meant the frame fetch and the fallback fetch evicted each other's ETags every cycle, making 304s structurally unreachable for the fallback rather than merely safe.
• Passing an explicit URL skipped cache busting, so the fallback loop lost the ?t= it had before this PR.

Plus: frame_count/window_end reported frames offered to the encoder rather than used — hiding exactly the shortfall those attributes exist to reveal; switching office or setting hours to 0 orphaned the old site's frames forever, contradicting the options screen's "store nothing"; and the invalid-hours error hardcoded "between 0 and 24" while the step description interpolates the constant.

Type

• Bugfix
• Feature
• Documentation
• Other

Checklist

• Follows Home Assistant custom integration structure
• Passes flake8 checks (max-line-length=120)
• Manifest is valid and complete
• README updated if required

Verification

• 850 tests pass (up from 764), flake8 clean, all JSON valid, strings.json and translations/en.json byte-identical. Pillow added to the CI install line so the encoder tests actually run there rather than skipping.
• Pillow is not declared in manifest.json — it is already a Home Assistant core requirement, and the module degrades to NOAA's loop if the import fails.
• Mutation-tested: each of the ten fixes above was reintroduced deliberately and confirmed to turn a test red. One test that passed under mutation was rewritten until it caught the defect it named.
• Clock-shifted: the full suite passes with the wall clock moved 2, 40 and 400 days forward.
• End-to-end against a real directory and a real Pillow: 144 frames of simulated polling sample to 72 at 20-minute spacing, encode in 0.35 s, produce a 191 KiB GIF that plays for exactly 10.0 s with the reflectivity scale intact and the newest scan last.

Known follow-ups (not blocking)

• {SITE}_0.gif is fetched twice per cycle — once by this entity, once by the base-reflectivity entity — plus a HEAD from the radar timestamp coordinator. Deduplicating means either coupling the two entities or adding a shared per-site fetch cache.
• The encoder rebuilds from scratch on every refresh (~151 file opens, ~79 decodes) to incorporate one new scan. Measured at 0.35 s per 10 minutes, so affordable; caching the quantised palette would cut it by roughly an order of magnitude.