feat(themes): weather scenes — a theme can follow the weather (#247)

[jherforth]

Closes #247 (phase 1: the core). The Weather theme itself, with its art, ships from HomeGlowThemes as phase 2.

What

A theme can now list a scene per weather condition (manifest version 4, weather), and the display shows the scene for the weather outside. To the household it's still one theme in the picker.

"weather": {
  "default": { "ambience": [ ... ] },
  "scenes": {
    "rainy": { "colors": { ... }, "tokens": { "dark": { ... } }, "ambience": [ ... ] },
    "lightning": { "ambience": [ ..., { "layer": "flash" }] }
  }
}

Scenes

• Keys are the server's condition tokens: sunny, partlycloudy, cloudy, fog, windy, windy-variant, rainy, pouring, snowy, snowy-rainy, hail, lightning and lightning-rainy. default covers anything else, or no data.
• What a scene changes: its colors and tokens go over the theme's, and its ambience and confetti replace the theme's.
• Fallbacks let a theme grow a few scenes at a time. A missing scene falls back to a related one, then to default:
  • pouring → rainy;
  • lightning-rainy → lightning → rainy;
  • hail → snowy-rainy → snowy;
  • windy-variant → windy;
  • partlycloudy → cloudy.
• Night is the display mode. A scene's dark look is its night, and a clear night is the sunny scene. On Auto, night follows sunset.

Asking for the weather

GET /api/weather/condition?lat=&lon= returns { condition, checkedAt, maxAgeMs }.

• It answers from any fresh reading of the place, whatever its units or language. That includes a weather widget's reading made by place name: each reading carries its resolved coordinates, matched to about 1 km. Otherwise it makes one fetch.
• Displays poll it as often as the server's reading lasts (10 minutes), and again when they come back into view. That costs no extra provider calls.
• It uses polling, not the plugin event stream.
• The location is the one Auto mode already has, so there's no new setting. Home Assistant needs no location.

Admin → Look → Appearance

These appear when the chosen theme has weather scenes:

• the location field, labelled for both uses;
• what the theme would show now, e.g. "Outside now: Rain. Showing the Rain scene.", or why the weather can't be read;
• a hint when the mode isn't Auto, because night scenes then won't follow sunset;
• Preview a scene: shows any scene on this display for 10 minutes, and is never saved.

Engine

• Scene changes fade in over 2.5 s, opacity only, and stay still under reduced motion. Each scene draws from its own seed.
• New flash layer for lightning, gentle by design:
  • opacity only;
  • a soft glow from the top of the sky, not a full-screen field;
  • strength capped at 0.5, at least 4 s between strikes, at most two flickers;
  • nothing under reduced motion.
• Manifest version 4 on both client and server (a server test keeps them equal). weather and flash require it.
• Each scene is validated as strictly as a theme's top level: tokens, colors, layers, and assets inside the folder.

Docs

• theme-development.md has a new §4b, "Weather scenes", and the flash layer.
• theme-architecture.md lists version 4.
• features.md and backend-api.md are updated.

Tested

• Server: npm test passes 362 of 363. The one failure is the migration-20 test timing out at 30 s under load; alone it passes in 6 s, and this change doesn't touch it. New weatherCondition.test.js covers:
  • a widget's reading by place name answering a request by coordinates, with no second upstream call;
  • fetching once, then sharing;
  • another place not answering;
  • a 400 with no location;
  • demo mode.
• Client: npx vitest run passes (545 tests), and npm run check:i18n and npm run build succeed. New tests cover:
  • pickWeatherScene, with every fallback and clear-night;
  • scene validation, rejecting unknown scenes, bad colors, CSS injection, missing assets, and too-strong flashes;
  • resolveTheme scene merging;
  • the manifest-version rules;
  • the poll interval.
• Browser, with a small test theme ("Skies": default, sunny, rainy, snowy, lightning) installed through the normal upload, and the condition intercepted:
  • rainy, then snowy, then pouring → rain, clear-night → sunny, fog → default, and lightning-rainy → lightning, each with the scene's accent and background;
  • a lightning strike was caught;
  • dark mode shows the rain scene's night background;
  • under reduced motion, nothing animates;
  • the Appearance page shows the real "OpenWeatherMap API key is not configured" reason and the Auto hint;
  • Preview → Snow switches the dashboard to the snow scene.
• Performance: every scene held the display's full frame rate with the CPU throttled 4×.

🤖 Generated with Claude Code