Add Dark mode for a screen beside the bed, with every colour in one table (0.2.63)

Dark mode is a new switch under Brightness on the screen's settings page, in
the Screen settings of ESP Screens and as switch.<screen>_dark_mode in Home
Assistant, so an automation can turn it on at bedtime. The screen changes
look at once, open cards and an alert included, and keeps it after a
restart. The design stays the same: a black page, graphite cards with a
hairline, soft white text, Home Assistant's state colours where they tell
something, and pastel card colours as deeper versions of themselves.

Every colour the firmware chooses now lives in components/smart_display/
theme.h: roles with a light and a dark value, the named card colours and
Home Assistant's state colours. The board profiles give widgets colourless
shared styles that theme.h fills, so a change of look refills those styles
and draws again what code painted by state. The light look is unchanged
apart from merges below one panel step. Dark mode costs 440 bytes of static
RAM on the CYD, and the LVGL tree of the host build is 416 bytes smaller; tests
keep colours out of every other file.

Comparing a screen that switched looks with one that booted in it also
found two older bugs, now fixed: a settings switch that was on showed its
knob at the left whenever its page was drawn, and the sun card's sunlit
area turned orange after a palette change. Firmware 0.2.54.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/EASY_SETUP.md

@@ -256,6 +256,7 @@ After this, changes to these settings don't need a new firmware flash.
 | Auto standby | On/off | On |
 | Standby after | 1–1440 minutes after the last touch | 10 minutes |
 | Normal brightness | 5–100% | 100% |
+| Dark mode | On/off: black page, graphite cards, firmware 0.2.54+ | Off |
 | Standby brightness | 0–100%, capped at normal brightness | 20% |
 | Night mode | On/off; applies during standby | On |
 | Night start/end | Hour and minute, can span midnight | 22:00–07:00 |

docs/RELEASING.md

@@ -176,6 +176,53 @@ icons sit off-center in the browser); run `generate_packages.py` afterward.
 The `MDI_GLYPH_*` substitutions are retired: `TILEn_ICON` in manual
 profiles must come from the set. No changed preferences or keys.
 
+### Compatibility 0.2.63 / firmware 0.2.54
+
+Firmware (`components/smart_display`, new `theme.h`), both board profiles and the app's settings. The tile protocol
+and the layout message are unchanged; nothing new on the wire.
+
+- **Colours in one table.** `theme.h` holds every colour the firmware chooses: roles with a light and a dark value,
+  the named card colours (`SWATCHES`, moved out of `tile_palette.h`, which now looks them up) and Home Assistant's
+  state colours (`theme::ha`). Headers ask for roles; the profiles give widgets paints (`styles: paint_card`), shared
+  styles without a colour that the profile's `theme::paints` list fills (`theme::fill()`, code in flash rather than a
+  table in RAM). `tests/test_theme.py` fails on a hex colour anywhere else (the light's colour picker and the value
+  card's colour wheel keep their hues) and on a paint that is not defined, filled once and used in every profile and
+  package; `tests/test_theme.cpp` checks the values.
+- **The light look is the old one.** Host renders of every page, card, alert and settings page against firmware
+  0.2.53 are pixel-identical, apart from merges below one panel step: the text of the simple cards (`#202020` to
+  `#1B1B1B`) and of some secondary words (`#5F6368` to `#616161`), the colour card's page (`#F7F7F7` to `#F8F8F8`,
+  what the eye saw through the old sheet), an unavailable tile's circle and the off brightness track (to `#F1F1F1`),
+  a pressed round key (`#DADADA` and `#D9D9D9` to `#DDDDDD`) and the tints of the vacuum's halo and the cover sliders,
+  now computed from their state colour (within two steps of the old hand-picked values), and the two fixes below.
+- **Two redraws that drew differently**, found by comparing a screen that switched looks with one that booted in it,
+  and both older than 0.2.54. `settings_screen::draw()` ends in `refresh()`, whose `move_knob()` read the new track's
+  coordinates before LVGL had laid the page out (still 0 wide), so every switch that was on showed its knob at the
+  left until the next refresh; the knob is now placed from the size `pill()` gave the track (`knob_x()`), and a
+  change of look, which draws the page again, no longer throws the Dark mode switch's own knob to the left. And
+  `render_slot`'s palette gave the sun path's fill the tile's accent (orange) whenever the palette changed, while
+  `render_sunpath` sets the sun's yellow on every render, so the sunlit area changed colour by itself a minute later;
+  the sun path keeps its own fill now.
+- **Dark mode** is `settings_screen::dark_mode` beside the other settings outside the frozen block, with a uint32
+  preference of its own (`0x44524B31`, "DRK1"); `screen_settings::Settings` stays version 1. It is a row under
+  Brightness (five rows: no pager on either board), the template switch `Dark mode` (config, `restore_mode: DISABLED`)
+  and the app's key `dark_mode` (`SETTING_RULES`, `SETTINGS_BESIDE_BLOCK`, `SETTING_ENTITIES`). A screen that gets its
+  settings with the layout never has it: `settings_view` leaves it out, the layout message never carries it.
+  `DARK_MODE_MIN_FIRMWARE` is 0.2.54.
+- **A change of look** runs through `set()` -> `apply_screen_settings` -> `theme::set_dark()`: the profile's and the
+  firmware's own paints are refilled, LVGL is told once (`lv_obj_report_style_change(nullptr)`), and `theme::redraw`
+  (set in `on_boot`) draws again what code painted by state: the tiles' palettes and the top bar
+  (`runtime_tiles::restyle`), an open card in place, the colour card (`light_controls::restyle`), the settings page,
+  an alert that is up (`alert_card_color`) and the climate card and its mode picker. The same pass, so no frame
+  mixes the looks; at boot `set_dark()` runs before the first frame.
+- **Profiles:** the substitutions `BG_TOP_COLOR`, `BG_BOTTOM_COLOR` and `ACCENT_*` are gone (an override that set them
+  has no effect any more), `style_bg_grad` is `style_page` (one fill, no gradient between two equal stops), the four
+  unused `*_disabled` styles and the colour card's `color_detail_bg` and `color_detail_scrim` are removed, and
+  `open_value_overlay` lost its three colour parameters (the value card's slider takes paints).
+- App 0.2.63 with firmware 0.2.53 or older: no Dark mode row, everything else as before. Firmware 0.2.54 with an
+  older app: Dark mode works on the screen and in Home Assistant; the older editor does not show the row.
+- A layout of a screen that gets its settings with the layout is stored with `dark_mode` among its settings. An app
+  from before 0.2.63 refuses that key: restore the data backup when rolling back, as for every settings key before.
+
 ### Compatibility 0.2.62 / firmware 0.2.53
 
 Firmware (`components/smart_display`), the icon fonts and the top bar's icon. Storage, tile protocol, preferences and

docs/SETTINGS.md

@@ -16,6 +16,7 @@ changes them with the entity's own action, and leaves them out of the layout mes
 | Row on the screen | Entity | Key in ESP Screens |
 |---|---|---|
 | Brightness | `number.<screen>_normal_brightness` | `brightness` |
+| Dark mode (0.2.54+) | `switch.<screen>_dark_mode` | `dark_mode` |
 | Auto standby | `switch.<screen>_auto_standby` | `standby_enabled` |
 | Standby after | `number.<screen>_standby_after` | `standby_seconds` |
 | Standby brightness | `number.<screen>_standby_brightness` | `standby_brightness` |
@@ -29,7 +30,9 @@ changes them with the entity's own action, and leaves them out of the layout mes
 | Rotation (Guition) | `select.<screen>_rotation` | `rotation` |
 
 The first four entities and Auto standby existed before 0.2.49; ESP Screens recognizes a screen that owns
-its settings by one of the others (`OWNED_SETTINGS_MARKERS` in `core.py`).
+its settings by one of the others (`OWNED_SETTINGS_MARKERS` in `core.py`). Dark mode came with firmware 0.2.54:
+a screen without its switch shows no Dark mode row in ESP Screens, and firmware that gets its settings with the
+layout never gets it at all. What Dark mode changes on the glass is in [docs/THEME.md](THEME.md).
 
 **Older firmware: ESP Screens.** The values travel in the layout message: `settings`, the frozen block of
 eleven keys, with `swipe_pages`, `auto_home`, `auto_home_seconds` and `rotation` as keys of their own. A
@@ -47,7 +50,7 @@ The page is a menu of groups, each of which opens a page of its own:
 
 | Group | Rows |
 |---|---|
-| Brightness | Brightness, Auto standby, Standby after, Standby brightness |
+| Brightness | Brightness, Dark mode, Auto standby, Standby after, Standby brightness |
 | Night | Night mode, Starts, Ends, Night brightness |
 | Screen | Clock, Back to page 1, After, Also on standby, Swipe between pages, Rotation (boards that turn) |
 | This screen | Screen, Address, Firmware, Home Assistant, Restart |

docs/THEME.md

@@ -0,0 +1,84 @@
+# Colours and Dark mode
+
+Every colour the screens choose themselves lives in one file, `components/smart_display/theme.h`
+(firmware 0.2.54+). Dark mode is a second value for each of them, not a second design: the
+layout, the fonts and the sizes stay exactly as they are. This page says how the colours reach
+the glass and what a new colour takes.
+
+## The model
+
+| Part | What it is | Where |
+|---|---|---|
+| Role | What a colour is for (`PAGE`, `CARD`, `INK`, `MUTED`, `KEY_PRESSED`, ...), with a light and a dark value | `theme::ROLES`, the table at the top of `theme.h` |
+| Swatch | A named card colour a tile or an alert can pick (`red` ... `gray`), light and dark | `theme::SWATCHES` |
+| State colour | Home Assistant's colour for a state (the amber of a light that is on), the same in both looks | `theme::ha` |
+| Paint | A shared LVGL style filled from roles: `card` is a card's background, hairline and text | `theme::Paint`, `theme::PAINTS` |
+| Look | `theme::dark`, set by `theme::set_dark()` from the Dark mode setting | `settings_screen::dark_mode` |
+
+The light values are the design as it has always been; `tests/test_theme.cpp` pins the main ones.
+The dark values follow a few rules: a black page, graphite cards (`#1A1A1A`) with a hairline,
+soft white text (`#DADADA`) and greys for secondary words, Home Assistant's state colours
+unchanged, their tints a little stronger over graphite, and a grey whose red, green and blue land
+on the same step of the RGB565 panel, so it stays grey on both boards.
+
+## How a colour reaches the glass
+
+- **Board profiles** write no colour. A widget names a paint, `styles: paint_card`, or a style that
+  carries one (`style_page`, `style_tile`, `style_room`, ...). The style definitions have no colour;
+  `on_boot` sets `theme::paints` to the list of `theme::fill(id(style), Paint::...)` calls and runs it. The list is
+  code in flash, not a table in RAM, and `theme::set_dark()` runs it again.
+  Scripts that colour a widget by state ask for a role: `theme::color(selected ? theme::ACCENT_BRIGHT : theme::CARD)`.
+- **Firmware** asks for roles: `theme::color(theme::INK)`, `theme::hex(theme::MUTED)`, the
+  `detail_text(..., theme::SUBTLE)` and `detail_shape(..., theme::TRACK, ...)` overloads. A widget
+  that lives as long as the screen and never changes colour by state takes a paint too:
+  `lv_obj_add_style(obj, theme::style(theme::Paint::knob), LV_PART_KNOB)`.
+- **State colours** pass through a helper on their way to the glass:
+  `state()` (Home Assistant's greys become the dark greys), `foreground()` (a glyph, a line or words:
+  deep colours are lifted in dark), `tint()` (the pale circle, a halo, a slider track), `icon()`
+  (a tile's icon), `surface()` and `outline()` (a card's own colour and hairline), `key_on()` (keys
+  inside a card of any colour) and `fill_opacity()` (the area under a graph).
+
+## A change of look
+
+`settings_screen::set("dark_mode", ...)` stores the setting in its own preference (`DRK1`), runs
+`apply_screen_settings`, and that calls `theme::set_dark()`. A look the screen already has costs
+nothing. A real change runs `theme::paints`, refills the firmware's own paints, tells LVGL once, and calls
+`theme::redraw`, set in `on_boot`, which draws again what code painted by state:
+
+- `runtime_tiles::restyle()`: every tile's palette, the top bar's icons, and an open card, in place;
+- `light_controls::restyle()`, `settings_screen::restyle()`;
+- an alert that is up (`theme::surface(id(alert_card_color))`), and the climate card and its mode
+  picker when they are open.
+
+Everything happens in the same pass, so no frame shows half of each look. At boot `set_dark()`
+runs before the first frame.
+
+A redraw has to give exactly what a first draw gives, whatever came before it. Two things that did
+not were found by comparing a screen that switched with one that booted in that look: a position
+worked out from coordinates LVGL had not laid out yet (they read 0 until its next pass: use the size
+you set), and a palette pass that overwrote a colour the sun path had chosen itself.
+
+## Adding a colour
+
+1. **A role**: one line in `enum Role` and one row in `ROLES`, in the same order (the tests read
+   both). The light value is the design; choose the dark value on a render, not in the table.
+2. **In firmware code**: `theme::color(theme::YOUR_ROLE)`. Never `lv_color_hex(0x...)`.
+3. **In a board profile**: the widget takes a paint. For a new combination add it to `enum class
+   Paint` and `PAINTS`, a colourless `- id: paint_<name>` in the `style_definitions` of both profiles,
+   and `theme::fill(id(paint_<name>), Paint::<name>);` in their `theme::paints` list. Then
+   `python3 tools/generate_packages.py`.
+4. **Something drawn once and kept that changes colour by state**: set it where the state is drawn,
+   and make sure the redraw above reaches that code.
+5. A local colour always wins over a paint: an object that takes a paint must not also get a local
+   colour for the same property and part.
+
+## Checks
+
+- `tests/test_theme.cpp`: the light design, contrast of the text roles on every surface and swatch in
+  both looks, neutral dark greys, and the helpers.
+- `tests/test_theme.py`: no colour outside `theme.h` (the light's colour picker and the value card's
+  colour wheel keep their hues), every paint defined, filled once and used, and the look applied at
+  boot, after a change and in the redraw.
+- Renders of the host build in both looks (see `docs/RELEASING.md`, Compatibility 0.2.63): the light
+  look pixel for pixel against the previous firmware, a screen that boots dark against one that
+  switched, and every card opened in light and switched while open against the same card opened in dark.