Widget system Phase 1: per-type render/action modules

New app/widgets/ package (photos.py, calendar.py, whiteboard.py, plus
the WIDGET_TYPES registry) -- the widget-system analogue of
routers/device.py's old RENDERERS/ADVANCE_RENDERERS/BACK_RENDERERS,
generalized from "one mode owns the whole panel" to "each widget renders
into its own region and responds to named button actions." Each module
exposes render(db, frame, widget, target_w, target_h) -> Image.Image
(never raises -- a widget's own fetch hiccup falls back to a small
placeholder rather than taking the whole panel's render down) and an
ACTIONS registry for NEXT/BACK button assignment.

Supporting changes needed to give the widget modules something to call,
all mechanical/behavior-preserving for every existing caller:

- image_pipeline.py: render_panel(regions, ...) generalizes render_frame's
  tail (paste, enhance once, overlay once, quantize once, pack once) from
  one photo to N regions -- not a restructuring, since calendar mode's
  photo-inlay feature already pastes a second composed image onto the
  canvas before that single shared pipeline runs.
- photo_queue.py: advance_forced/back_forced/remove_from_rotation/
  get_current take an explicit `frame` param now that `cfg` won't always
  be the Frame itself once photo-queue state moves to PhotoWidgetConfig
  -- caught a real latent bug while doing this: get_current was reading
  refresh_interval_s off `cfg`, but that's a frame-level wake-cadence
  setting, not something that becomes per-widget, so it now reads that
  off `frame` explicitly instead.
- routers/common.py: list_assets/fetch_source_and_faces take album_id/
  display_mode directly instead of a whole Frame (both only ever read
  that one attribute off it); new get_or_refresh_*_for_widget siblings
  of the existing calendar/weather/tasks/whiteboard cache helpers, read/
  writing the new per-widget config tables -- the Frame-scoped originals
  are untouched and still what routers/device.py's actual dispatch calls
  until the Phase 2 cutover.

26 new tests (95 total): render_panel size/placement/orientation
coverage, and per-widget-type render/action tests (unconfigured ->
placeholder, a fetch failure -> placeholder not a crash, actions mutate
the right state). Full suite passes; diff-reviewed to confirm
device.py's actual RENDERERS dispatch and the old Frame-scoped
get_or_refresh_* bodies are unchanged, so this is safe to deploy on its
own despite being step 1 of a two-step cutover (see the project plan on
why the *next* step, not this one, has to ship atomically).

server/tests/test_render_size_invariants.py

@@ -8,9 +8,11 @@ high-value regression guard: pure PIL rendering, no DB/HTTP/Node."""
 from __future__ import annotations
 
 import pytest
+from PIL import Image
 
 from app.calendar_render import CALENDAR_VIEWS, render_calendar
-from app.image_pipeline import EPD_HEIGHT, EPD_WIDTH, render_placeholder
+from app.grid import cell_to_pixels, full_panel_rect, grid_dims
+from app.image_pipeline import EPD_HEIGHT, EPD_WIDTH, render_panel, render_placeholder
 
 EXPECTED_BYTES = EPD_WIDTH * EPD_HEIGHT // 2
 ORIENTATIONS = ["landscape", "landscape_flipped", "portrait", "portrait_flipped"]
@@ -65,3 +67,79 @@ def test_calendar_render_size_with_week_start_offset():
     data = render_calendar(_SAMPLE_EVENTS, "week", browse_offset=0, orientation="landscape",
                            palette_rgb=None, timezone="UTC", week_days=3, week_start_offset=2)
     assert len(data) == EXPECTED_BYTES
+
+
+# --- render_panel (the widget-system compositor) ---
+
+
+@pytest.mark.parametrize("orientation", ORIENTATIONS)
+def test_render_panel_size_single_full_panel_region(orientation):
+    from app.image_pipeline import logical_render_size
+
+    w, h = logical_render_size(orientation)
+    region = Image.new("RGB", (w, h), (200, 0, 0))
+    data = render_panel([((0, 0, w, h), region)], orientation=orientation)
+    assert len(data) == EXPECTED_BYTES
+
+
+def test_render_panel_size_multiple_non_overlapping_regions():
+    cols, rows = grid_dims("landscape")
+    left_px = cell_to_pixels("landscape", EPD_WIDTH, EPD_HEIGHT, (0, 0, cols // 2, rows))
+    right_px = cell_to_pixels("landscape", EPD_WIDTH, EPD_HEIGHT, (cols // 2, 0, cols - cols // 2, rows))
+    regions = [
+        (left_px, Image.new("RGB", left_px[2:], (200, 0, 0))),
+        (right_px, Image.new("RGB", right_px[2:], (0, 0, 200))),
+    ]
+    data = render_panel(regions, orientation="landscape")
+    assert len(data) == EXPECTED_BYTES
+
+
+def test_render_panel_empty_region_list_is_blank_but_correctly_sized():
+    """No widgets on a frame yet (or all somehow filtered out) shouldn't
+    crash the compositor -- just a blank panel, same size invariant."""
+    data = render_panel([], orientation="landscape")
+    assert len(data) == EXPECTED_BYTES
+
+
+def test_render_panel_pastes_regions_at_the_right_place():
+    """Not just a size check -- confirms two regions actually land where
+    their rects say, not just that *something* the right size comes out."""
+    cols, rows = grid_dims("landscape")
+    left_rect = (0, 0, cols // 2, rows)
+    right_rect = (cols // 2, 0, cols - cols // 2, rows)
+    left_px = cell_to_pixels("landscape", EPD_WIDTH, EPD_HEIGHT, left_rect)
+    right_px = cell_to_pixels("landscape", EPD_WIDTH, EPD_HEIGHT, right_rect)
+    # Pure red vs pure blue, both already-palette colors, dither_strength=0
+    # so quantization can't introduce any blending/dithering noise --
+    # every pixel on each side should land on exactly the color it started as.
+    regions = [
+        (left_px, Image.new("RGB", left_px[2:], (255, 0, 0))),
+        (right_px, Image.new("RGB", right_px[2:], (0, 0, 255))),
+    ]
+    data = render_panel(regions, orientation="landscape", dither_strength=0.0)
+
+    from app.image_pipeline import PANEL_CODES
+
+    def code_at(x, y):
+        i = (y * EPD_WIDTH + x) // 2
+        byte = data[i]
+        return (byte >> 4) if x % 2 == 0 else (byte & 0x0F)
+
+    red_code = PANEL_CODES[3]  # DEFAULT_PALETTE_RGB index 3 = RED
+    blue_code = PANEL_CODES[4]  # index 4 = BLUE
+    # Sample well inside each half, away from the boundary, at a y
+    # comfortably inside the panel.
+    assert code_at(50, 240) == red_code
+    assert code_at(750, 240) == blue_code
+
+
+def test_render_panel_backfilled_full_panel_widget_matches_grid_full_panel_rect():
+    """Sanity-links app.grid's full_panel_rect (what the migration backfill
+    uses for the single auto-migrated widget) to render_panel's own size
+    invariant, so a mismatch between the two would fail loudly here."""
+    rect = full_panel_rect("landscape")
+    px = cell_to_pixels("landscape", EPD_WIDTH, EPD_HEIGHT, rect)
+    assert px == (0, 0, EPD_WIDTH, EPD_HEIGHT)
+    region = Image.new("RGB", px[2:], (10, 20, 30))
+    data = render_panel([(px, region)], orientation="landscape")
+    assert len(data) == EXPECTED_BYTES

server/tests/test_widgets_calendar.py

@@ -0,0 +1,102 @@
+"""app.widgets.calendar -- unit-level, no HTTP: constructs Widget/
+CalendarWidgetConfig rows directly and monkeypatches the underlying
+fetch calls (get_or_refresh_*_for_widget), which have their own
+dedicated fetch/merge test coverage elsewhere (test_calendar_feed.py
+etc.) -- this file is about the widget wiring itself: does render()
+produce a correctly-sized image, do advance/back move browse_offset."""
+
+from __future__ import annotations
+
+import time
+
+from app import widgets
+from app.db import widget_locked
+from app.models import CalendarWidgetConfig, Frame, Widget
+
+
+def _make_widget(db_session, **cfg_kwargs) -> tuple[Frame, Widget]:
+    frame = db_session.get(Frame, 1)
+    widget = Widget(frame_id=frame.id, widget_type="calendar", x=0, y=0, w=8, h=5,
+                    sort_order=0, created_at=time.time())
+    db_session.add(widget)
+    db_session.flush()
+    db_session.add(CalendarWidgetConfig(widget_id=widget.id, **cfg_kwargs))
+    db_session.commit()
+    return frame, widget
+
+
+def _stub_fetches(monkeypatch, events=None, weather=None, tasks=None):
+    monkeypatch.setattr(widgets.calendar, "get_or_refresh_calendar_events_for_widget",
+                        lambda db, frame, widget: (events or [], ""))
+    monkeypatch.setattr(widgets.calendar, "get_or_refresh_weather_for_widget",
+                        lambda db, frame, widget: weather or [])
+    monkeypatch.setattr(widgets.calendar, "get_or_refresh_tasks_for_widget",
+                        lambda db, frame, widget: tasks or [])
+
+
+def test_render_produces_a_correctly_sized_image(db_session, monkeypatch):
+    frame, widget = _make_widget(db_session, view="agenda")
+    _stub_fetches(monkeypatch)
+
+    img = widgets.calendar.render(db_session, frame, widget, 400, 300)
+    assert img.size == (400, 300)
+    assert img.mode == "RGB"
+
+
+def test_render_resizes_when_target_differs_from_full_panel(db_session, monkeypatch):
+    """Phase-1 calendar widgets are still full-panel-layout internally
+    (see app/widgets/calendar.py's own module docstring) -- resizing to
+    fit whatever target box is asked for keeps render_panel's contract
+    (exact target_w x target_h) satisfied even before real small-widget
+    layout support lands."""
+    frame, widget = _make_widget(db_session, view="week")
+    _stub_fetches(monkeypatch)
+
+    img = widgets.calendar.render(db_session, frame, widget, 250, 150)
+    assert img.size == (250, 150)
+
+
+def test_weather_only_fetched_when_enabled(db_session, monkeypatch):
+    frame, widget = _make_widget(db_session, view="agenda", weather_enabled=False)
+    calls = []
+    monkeypatch.setattr(widgets.calendar, "get_or_refresh_calendar_events_for_widget",
+                        lambda db, frame, widget: ([], ""))
+    monkeypatch.setattr(widgets.calendar, "get_or_refresh_weather_for_widget",
+                        lambda db, frame, widget: calls.append(1) or [])
+    monkeypatch.setattr(widgets.calendar, "get_or_refresh_tasks_for_widget",
+                        lambda db, frame, widget: [])
+
+    widgets.calendar.render(db_session, frame, widget, 400, 300)
+    assert calls == []
+
+
+def test_tasks_only_fetched_for_week_view_when_enabled(db_session, monkeypatch):
+    frame, widget = _make_widget(db_session, view="agenda", tasks_enabled=True)  # not week view
+    calls = []
+    monkeypatch.setattr(widgets.calendar, "get_or_refresh_calendar_events_for_widget",
+                        lambda db, frame, widget: ([], ""))
+    monkeypatch.setattr(widgets.calendar, "get_or_refresh_weather_for_widget",
+                        lambda db, frame, widget: [])
+    monkeypatch.setattr(widgets.calendar, "get_or_refresh_tasks_for_widget",
+                        lambda db, frame, widget: calls.append(1) or [])
+
+    widgets.calendar.render(db_session, frame, widget, 400, 300)
+    assert calls == []  # agenda view -- tasks never shown, so never fetched
+
+
+def test_advance_action_increments_browse_offset(db_session):
+    frame, widget = _make_widget(db_session, view="week", browse_offset=0)
+    widgets.calendar.ACTIONS["advance"](db_session, frame, widget)
+    cfg = db_session.get(CalendarWidgetConfig, widget.id)
+    assert cfg.browse_offset == 1
+
+    widgets.calendar.ACTIONS["advance"](db_session, frame, widget)
+    cfg = db_session.get(CalendarWidgetConfig, widget.id)
+    assert cfg.browse_offset == 2  # accumulates, doesn't reset-then-increment
+
+
+def test_back_action_decrements_browse_offset(db_session):
+    frame, widget = _make_widget(db_session, view="week", browse_offset=3)
+    widgets.calendar.ACTIONS["back"](db_session, frame, widget)
+    cfg = db_session.get(CalendarWidgetConfig, widget.id)
+    assert cfg.browse_offset == 2

server/tests/test_widgets_photos.py

@@ -0,0 +1,116 @@
+"""app.widgets.photos -- unit-level, no HTTP: constructs Widget/
+PhotoWidgetConfig rows directly and monkeypatches the Immich-facing
+calls (list_assets/fetch_source_and_faces/immich_client_for) rather than
+standing up a fake Immich server, since this module's own logic (what it
+does with whatever Immich returns) is what's under test, not Immich's
+API shape -- already covered by ImmichClient's own tests if any, and by
+this suite's HTTP-level permission-boundary tests elsewhere."""
+
+from __future__ import annotations
+
+import time
+
+from PIL import Image
+
+from app import widgets
+from app.db import widget_locked
+from app.models import Frame, PhotoWidgetConfig, Widget
+
+_ASSETS = [{"id": "asset-1"}, {"id": "asset-2"}, {"id": "asset-3"}]
+
+
+def _make_widget(db_session, album_id="album-1") -> tuple[Frame, Widget]:
+    frame = db_session.get(Frame, 1)
+    widget = Widget(frame_id=frame.id, widget_type="photos", x=0, y=0, w=8, h=5,
+                    sort_order=0, created_at=time.time())
+    db_session.add(widget)
+    db_session.flush()
+    db_session.add(PhotoWidgetConfig(widget_id=widget.id, album_id=album_id, queue_target_len=5))
+    db_session.commit()
+    return frame, widget
+
+
+def test_render_unconfigured_widget_returns_correctly_sized_placeholder(db_session):
+    frame, widget = _make_widget(db_session, album_id="")
+    img = widgets.photos.render(db_session, frame, widget, 400, 300)
+    assert img.size == (400, 300)
+    assert img.mode == "RGB"
+
+
+def test_render_configured_widget_composes_a_photo(db_session, monkeypatch):
+    frame, widget = _make_widget(db_session)
+
+    monkeypatch.setattr(widgets.photos, "immich_client_for", lambda frame: object())
+    monkeypatch.setattr(widgets.photos, "list_assets", lambda client, album_id: _ASSETS)
+    source = Image.new("RGB", (100, 80), (10, 20, 30))
+    monkeypatch.setattr(widgets.photos, "fetch_source_and_faces", lambda client, mode, asset_id: (source, None))
+
+    img = widgets.photos.render(db_session, frame, widget, 400, 300)
+    assert img.size == (400, 300)
+
+    cfg = db_session.get(PhotoWidgetConfig, widget.id)
+    assert cfg.current_asset_id == "asset-1"  # get_current picked the first asset
+
+
+def test_render_falls_back_to_placeholder_on_immich_failure(db_session, monkeypatch):
+    from fastapi import HTTPException
+
+    frame, widget = _make_widget(db_session)
+
+    def _raise(client, album_id):
+        raise HTTPException(502, "Could not reach Immich")
+
+    monkeypatch.setattr(widgets.photos, "immich_client_for", lambda frame: object())
+    monkeypatch.setattr(widgets.photos, "list_assets", _raise)
+
+    img = widgets.photos.render(db_session, frame, widget, 400, 300)
+    assert img.size == (400, 300)  # placeholder, not a crash
+
+
+def test_advance_action_moves_to_next_photo(db_session, monkeypatch):
+    frame, widget = _make_widget(db_session)
+    monkeypatch.setattr(widgets.photos, "immich_client_for", lambda frame: object())
+    monkeypatch.setattr(widgets.photos, "list_assets", lambda client, album_id: _ASSETS)
+
+    with widget_locked(db_session, frame.id, widget.id) as (_, _, cfg):
+        cfg.current_asset_id = "asset-1"
+
+    widgets.photos.ACTIONS["advance"](db_session, frame, widget)
+
+    cfg = db_session.get(PhotoWidgetConfig, widget.id)
+    assert cfg.current_asset_id != "asset-1"
+    assert cfg.history == ["asset-1"]
+
+
+def test_back_action_undoes_advance(db_session, monkeypatch):
+    frame, widget = _make_widget(db_session)
+    monkeypatch.setattr(widgets.photos, "immich_client_for", lambda frame: object())
+    monkeypatch.setattr(widgets.photos, "list_assets", lambda client, album_id: _ASSETS)
+
+    # advance_forced only pushes the *previous* current photo onto history
+    # -- the very first advance from an empty current_asset_id has nothing
+    # to push, so a second advance is needed before there's anything for
+    # "back" to undo.
+    widgets.photos.ACTIONS["advance"](db_session, frame, widget)
+    first = db_session.get(PhotoWidgetConfig, widget.id).current_asset_id
+    widgets.photos.ACTIONS["advance"](db_session, frame, widget)
+    second = db_session.get(PhotoWidgetConfig, widget.id).current_asset_id
+    assert second != first
+
+    widgets.photos.ACTIONS["back"](db_session, frame, widget)
+    cfg = db_session.get(PhotoWidgetConfig, widget.id)
+    assert cfg.current_asset_id == first
+
+
+def test_advance_action_is_a_no_op_when_unconfigured(db_session):
+    frame, widget = _make_widget(db_session, album_id="")
+    widgets.photos.ACTIONS["advance"](db_session, frame, widget)  # must not raise
+    cfg = db_session.get(PhotoWidgetConfig, widget.id)
+    assert cfg.current_asset_id == ""
+
+
+def test_advance_uses_the_frame_stats_counter_not_the_widget_config():
+    """advance_forced's frame/stats split (see app/photo_queue.py) means
+    stats_photos_displayed should land on the Frame row, never on
+    PhotoWidgetConfig (which has no such column at all)."""
+    assert not hasattr(PhotoWidgetConfig, "stats_photos_displayed")

server/tests/test_widgets_whiteboard.py

@@ -0,0 +1,85 @@
+"""app.widgets.whiteboard -- unit-level, no HTTP: constructs Widget/
+WhiteboardWidgetConfig rows directly and monkeypatches the underlying
+fetch/render call (get_or_refresh_whiteboard_for_widget, already covered
+against a real WebDAV server + mocked sidecar in
+test_whiteboard_refresh_and_browse.py) rather than re-testing that
+throttle/fetch logic here."""
+
+from __future__ import annotations
+
+import io
+import time
+
+from PIL import Image
+
+from app import widgets
+from app.models import Frame, Widget, WhiteboardWidgetConfig
+
+
+def _make_widget(db_session) -> tuple[Frame, Widget]:
+    frame = db_session.get(Frame, 1)
+    widget = Widget(frame_id=frame.id, widget_type="whiteboard", x=0, y=0, w=8, h=5,
+                    sort_order=0, created_at=time.time())
+    db_session.add(widget)
+    db_session.flush()
+    db_session.add(WhiteboardWidgetConfig(widget_id=widget.id, url="https://example.com/board.whiteboard"))
+    db_session.commit()
+    return frame, widget
+
+
+def _tiny_png() -> bytes:
+    buf = io.BytesIO()
+    Image.new("RGB", (40, 20), (10, 20, 30)).save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def test_render_unconfigured_widget_returns_correctly_sized_placeholder(db_session):
+    frame = db_session.get(Frame, 1)
+    widget = Widget(frame_id=frame.id, widget_type="whiteboard", x=0, y=0, w=8, h=5,
+                    sort_order=0, created_at=time.time())
+    db_session.add(widget)
+    db_session.flush()
+    db_session.add(WhiteboardWidgetConfig(widget_id=widget.id))  # no url/user_id set
+    db_session.commit()
+
+    img = widgets.whiteboard.render(db_session, frame, widget, 300, 200)
+    assert img.size == (300, 200)
+
+
+def test_render_configured_widget_composes_the_fetched_png(db_session, monkeypatch):
+    frame, widget = _make_widget(db_session)
+    png = _tiny_png()
+    monkeypatch.setattr(widgets.whiteboard, "get_or_refresh_whiteboard_for_widget",
+                        lambda db, frame, widget, force=False: png)
+
+    img = widgets.whiteboard.render(db_session, frame, widget, 300, 200)
+    assert img.size == (300, 200)
+    assert img.mode == "RGB"
+
+
+def test_render_falls_back_to_placeholder_when_nothing_cached_yet(db_session, monkeypatch):
+    frame, widget = _make_widget(db_session)
+    monkeypatch.setattr(widgets.whiteboard, "get_or_refresh_whiteboard_for_widget",
+                        lambda db, frame, widget, force=False: None)
+
+    img = widgets.whiteboard.render(db_session, frame, widget, 300, 200)
+    assert img.size == (300, 200)
+
+
+def test_check_now_action_forces_a_refetch(db_session, monkeypatch):
+    frame, widget = _make_widget(db_session)
+    calls = []
+
+    def fake_refresh(db, frame, widget, force=False):
+        calls.append(force)
+        return _tiny_png()
+
+    monkeypatch.setattr(widgets.whiteboard, "get_or_refresh_whiteboard_for_widget", fake_refresh)
+    widgets.whiteboard.ACTIONS["check_now"](db_session, frame, widget)
+    assert calls == [True]
+
+
+def test_both_buttons_map_to_check_now():
+    """No real "next"/"back" concept for a static board -- both physical
+    buttons mean the same thing for a whiteboard widget."""
+    assert set(widgets.whiteboard.ACTIONS) == {"check_now"}