feat(power): add battery monitoring and status overlays

components/domain/include/domain.h

@@ -29,6 +29,47 @@ typedef struct {
     int settle_delay_ms;
 } domain_direction_calibration_t;
 
+typedef enum {
+    DOMAIN_BATTERY_CHARGE_UNKNOWN = 0,
+    DOMAIN_BATTERY_CHARGE_NOT_CHARGING,
+    DOMAIN_BATTERY_CHARGE_CHARGING,
+} domain_battery_charge_state_t;
+
+typedef enum {
+    DOMAIN_BATTERY_LEVEL_UNKNOWN = 0,
+    DOMAIN_BATTERY_LEVEL_NORMAL,
+    DOMAIN_BATTERY_LEVEL_LOW,
+    DOMAIN_BATTERY_LEVEL_CRITICAL,
+} domain_battery_level_state_t;
+
+typedef struct {
+    int voltage_mv;
+    int latest_adc_mv;
+    int latest_sample_mv;
+    uint8_t percentage;
+    domain_battery_charge_state_t charge_state;
+    domain_battery_level_state_t level_state;
+    bool valid;
+    bool latest_sample_valid;
+    bool measurement_suppressed;
+    bool high_load_active;
+    bool cooldown_active;
+    uint32_t consecutive_failures;
+    int64_t last_valid_sample_time_ms;
+} domain_battery_status_t;
+
+/** Initialize the battery measurement domain. Idempotent and thread-safe. */
+esp_err_t domain_battery_init(void);
+
+/** Acquire and process one battery sample without applying product policy. */
+esp_err_t domain_battery_sample(void);
+
+/** Copy the latest battery SSOT snapshot into `out_status`. */
+esp_err_t domain_battery_get_status(domain_battery_status_t *out_status);
+
+/** Reserved policy hook; this release intentionally performs no shutdown. */
+esp_err_t domain_battery_prepare_shutdown(void);
+
 typedef enum {
     DOMAIN_WIFI_PROMPT_WIFI_SUCCESS = 0,
     DOMAIN_WIFI_PROMPT_AFTER_WIFI_SUCCESS,
@@ -560,6 +601,10 @@ void domain_runtime_start_lcd_render_loop(void);
  * values wait up to the bound before lower layers apply deterministic fallback.
  */
 esp_err_t domain_runtime_stop_lcd_render_loop(int timeout_ms);
+
+/** Map the domain battery snapshot to persistent LCD status overlays. */
+esp_err_t domain_runtime_update_battery_overlay(const domain_battery_status_t *status);
+
 esp_err_t domain_runtime_request_expression(const domain_expression_request_t *request);
 
 /**