feat(power): add battery monitoring and status overlays

components/platform/include/platform.h

@@ -302,6 +302,33 @@ esp_err_t platform_stepper_rotate_angle_with_accel_timeout(float angle,
                                                            int target_delay_us,
                                                            int timeout_ms);
 void platform_stepper_power_off(void);
+
+typedef enum {
+    PLATFORM_BATTERY_CHARGE_UNKNOWN = 0,
+    PLATFORM_BATTERY_CHARGE_NOT_CHARGING,
+    PLATFORM_BATTERY_CHARGE_CHARGING,
+} platform_battery_charge_state_t;
+
+typedef struct {
+    int adc_voltage_mv;
+    int voltage_mv;
+    platform_battery_charge_state_t charge_state;
+    bool voltage_valid;
+    bool high_load_active;
+    bool cooldown_active;
+} platform_battery_sample_t;
+
+/** Initialize the board battery ADC and TP4057 status input. Idempotent. */
+esp_err_t platform_battery_init(void);
+
+/**
+ * Read one trimmed-mean battery voltage sample and a load-quality snapshot.
+ * A successful call can still return voltage_valid=false for an implausible
+ * electrical reading; callers must not interpret such a sample as an empty
+ * battery.
+ */
+esp_err_t platform_battery_read_sample(platform_battery_sample_t *out_sample);
+
 esp_err_t platform_configure_digital_input(const platform_digital_input_config_t *config);
 bool platform_is_digital_input_active(const platform_digital_input_config_t *config);
 
@@ -480,6 +507,19 @@ typedef struct {
     size_t step_count;
 } platform_lcd_presentation_request_t;
 
+typedef struct {
+    bool low_battery_visible;
+    bool charging_visible;
+} platform_lcd_status_overlay_t;
+
+/**
+ * @brief Set persistent LCD status overlays composited over presentation frames.
+ *
+ * The state is copied synchronously and remains active until replaced. The
+ * render task owns all PNG decoding and panel access.
+ */
+esp_err_t platform_lcd_set_status_overlay(const platform_lcd_status_overlay_t *overlay);
+
 /**
  * @brief Request a LCD presentation playback.
  *