Add battery widget (device's own last-reported level, no live upstream)

Shows Frame.battery_percent/battery_as_of, already set by every device
wake-on-battery report, plus routers/common.py's existing
battery_estimate_s time-remaining estimate -- nothing new to fetch or
cache. Compact (icon + percent) or detailed (+ estimate, last report
age) display mode. No button actions.

server/tests/test_widget_config_and_queue_endpoints.py

@@ -14,6 +14,7 @@ import io
 from PIL import Image
 
 from app.models import (
+    BatteryWidgetConfig,
     CalendarWidgetConfig,
     Frame,
     PhotoWidgetConfig,
@@ -93,6 +94,18 @@ def _add_weather_widget(db_session, **cfg_kwargs) -> Widget:
     return widget
 
 
+def _add_battery_widget(db_session, **cfg_kwargs) -> Widget:
+    import time
+
+    widget = Widget(frame_id=1, widget_type="battery", x=0, y=0, w=1, h=1,
+                    sort_order=1, created_at=time.time())
+    db_session.add(widget)
+    db_session.flush()
+    db_session.add(BatteryWidgetConfig(widget_id=widget.id, **cfg_kwargs))
+    db_session.commit()
+    return widget
+
+
 def _png_bytes(size=(20, 10), color=(10, 20, 30)) -> bytes:
     buf = io.BytesIO()
     Image.new("RGB", size, color).save(buf, format="PNG")
@@ -277,6 +290,38 @@ def test_config_save_rejects_an_unrecognized_static_display_mode(client, db_sess
     assert cfg.display_mode == "crop_fill"
 
 
+def test_config_save_updates_a_battery_widget(client, db_session):
+    client.post("/setup", data={"username": "alice", "password": "hunter22"})
+    widget = _add_battery_widget(db_session)
+
+    resp = client.post(
+        f"/api/frames/1/widgets/{widget.id}/config",
+        data={"battery_mode": "compact"},
+        headers=csrf_headers(client),
+    )
+    assert resp.status_code == 200, resp.text
+
+    cfg = db_session.get(BatteryWidgetConfig, widget.id)
+    assert cfg.mode == "compact"
+
+
+def test_config_save_rejects_an_unrecognized_battery_mode(client, db_session):
+    """Falls back to the default rather than erroring -- same "clamp,
+    don't reject" posture as the other config-save fields."""
+    client.post("/setup", data={"username": "alice", "password": "hunter22"})
+    widget = _add_battery_widget(db_session)
+
+    resp = client.post(
+        f"/api/frames/1/widgets/{widget.id}/config",
+        data={"battery_mode": "graph"},
+        headers=csrf_headers(client),
+    )
+    assert resp.status_code == 200, resp.text
+
+    cfg = db_session.get(BatteryWidgetConfig, widget.id)
+    assert cfg.mode == "detailed"
+
+
 def test_config_save_updates_a_text_widget(client, db_session):
     client.post("/setup", data={"username": "alice", "password": "hunter22"})
     widget = _add_text_widget(db_session)
@@ -502,6 +547,38 @@ def test_preview_text_400s_for_a_widget_that_is_not_text(client, db_session):
     assert resp.status_code == 400
 
 
+# --- battery: preview ---------------------------------------------------
+
+def test_preview_battery_renders_even_before_any_report(client, db_session):
+    """Unlike every other widget type's preview endpoint, there's no
+    "not configured yet" 400 -- render() always has something to show
+    (a placeholder, here, since the frame's never reported)."""
+    client.post("/setup", data={"username": "alice", "password": "hunter22"})
+    widget = _add_battery_widget(db_session)
+    resp = client.get(f"/api/frames/1/widgets/{widget.id}/preview/battery")
+    assert resp.status_code == 200, resp.text
+    assert resp.headers["content-type"] == "image/png"
+
+
+def test_preview_battery_renders_after_a_report(client, db_session):
+    client.post("/setup", data={"username": "alice", "password": "hunter22"})
+    widget = _add_battery_widget(db_session)
+    frame = db_session.get(Frame, 1)
+    frame.battery_percent = 77
+    db_session.commit()
+
+    resp = client.get(f"/api/frames/1/widgets/{widget.id}/preview/battery")
+    assert resp.status_code == 200, resp.text
+    assert resp.headers["content-type"] == "image/png"
+
+
+def test_preview_battery_400s_for_a_widget_that_is_not_battery(client, db_session):
+    client.post("/setup", data={"username": "alice", "password": "hunter22"})
+    widget = _add_static_widget(db_session)
+    resp = client.get(f"/api/frames/1/widgets/{widget.id}/preview/battery")
+    assert resp.status_code == 400
+
+
 # --- weather: location/cities/preview ---------------------------------
 
 def _mock_geocode(monkeypatch, label="Portland, Oregon, United States", latitude=45.5, longitude=-122.6):