feat(graphics): DisplayMirror for screen mirroring and remote input

include/graphics/DeviceScreen.h

@@ -35,6 +35,9 @@ class DeviceScreen
     void toggleDisplay(void);
     bool prepareShutdown(uint32_t timeoutMs = 1000);
 
+    /** The display driver behind this screen, for hosts that drive it directly. */
+    DisplayDriver *getDisplayDriver(void) const { return gui->getDisplayDriver(); }
+
 #if defined(ARDUINO_ARCH_ESP32)
     int prepareSleep(void *);
     int wakeUp(esp_sleep_wakeup_cause_t cause);

include/graphics/DisplayMirror.h

@@ -0,0 +1,38 @@
+#pragma once
+
+#include <cstdint>
+
+class DisplayDriver;
+
+/**
+ * @brief Streams the rendered screen to a host and feeds the host's input back
+ *        into LVGL. Idle until start(); no driver knows this class exists.
+ */
+class DisplayMirror
+{
+  public:
+    // LVGL thread: pixels is the area's top-left, rows stride pixels apart, in the
+    // byte order pixelsByteSwapped() reports. Copy, never write, and return.
+    using FrameObserver = void (*)(int16_t x, int16_t y, uint16_t width, uint16_t height, const uint16_t *pixels,
+                                   uint16_t stride);
+
+    // once, after DeviceScreen::init() and before the UI task starts
+    static void start(DisplayDriver *driver);
+
+    // nullptr stops capture; a flush may still be in flight for one UI tick
+    static void setFrameObserver(FrameObserver observer);
+
+    static bool pixelsByteSwapped(void);
+
+    // any thread; repaints the screen and its overlay layers
+    static void requestFullRefresh(void);
+
+    // remote input, from a single producer thread; dropped when the queue is full
+    static void injectTouch(int16_t x, int16_t y);
+    // held past this device's long-press threshold, so it behaves like a finger
+    static void injectLongPress(int16_t x, int16_t y);
+    static void injectKey(uint32_t key); // LV_KEY_* or a printable character
+    static void injectLongPressKey(uint32_t key);
+    // moves group focus; negative is backwards, clamped to a byte
+    static void injectEncoder(int16_t steps);
+};

include/graphics/driver/DisplayDriver.h

@@ -3,6 +3,7 @@
 #include "graphics/DeviceGUI.h"
 #include "graphics/LVGL/LVGLGraphics.h"
 #include <cstdint>
+#include <functional>
 
 #define H_NORM_PX(h_scr_percent) ((int16_t)((screenWidth / 100.0) * (h_scr_percent)))
 #define V_NORM_PX(v_scr_percent) ((int16_t)((screenHeight / 100.0) * (v_scr_percent)))
@@ -42,7 +43,17 @@ class DisplayDriver
 
     lv_display_t *getDisplay(void) { return display; }
 
+    // pixels: top-left of the flushed area, rows stride pixels apart; LVGL thread
+    using FlushCallback =
+        std::function<void(int16_t x, int16_t y, uint16_t width, uint16_t height, const uint16_t *pixels, uint16_t stride)>;
+
+    // set once, before the UI task starts
+    void setFlushCB(FlushCallback cb) { flushCB = std::move(cb); }
+
   protected:
+    // subclasses call this from their LVGL flush callback
+    void flush(lv_display_t *disp, const lv_area_t *area, const uint8_t *px_map);
+
     LVGLGraphics lvgl;
     LVGLDisplay *display;
     LVGLTouch *touch;
@@ -52,4 +63,5 @@ class DisplayDriver
 
   private:
     static void displayToggleCb(void *displayDriver);
+    FlushCallback flushCB;
 };

include/graphics/driver/LGFXDriver.h

@@ -226,6 +226,7 @@ template <class LGFX> void LGFXDriver<LGFX>::display_flush(lv_display_t *disp, c
 {
     uint32_t w = lv_area_get_width(area);
     uint32_t h = lv_area_get_height(area);
+    static_cast<LGFXDriver *>(lv_display_get_driver_data(disp))->flush(disp, area, px_map);
     {
         ISpiLock::Guard bus;
         lgfx->startWrite();
@@ -248,12 +249,14 @@ template <class LGFX> void LGFXDriver<LGFX>::display_flush(lv_display_t *disp, c
     uint32_t h = lv_area_get_height(area);
     lgfx->setAddrWindow(area->x1, area->y1, w, h);
     lgfx->pushPixelsDMA((uint16_t *)px_map, w * h);
+    static_cast<LGFXDriver *>(lv_display_get_driver_data(disp))->flush(disp, area, px_map);
     lv_display_flush_ready(disp);
 }
 #elif defined(USE_FULL_DOUBLE_BUFFER)
 template <class LGFX> void LGFXDriver<LGFX>::display_flush(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map)
 {
     auto driver = static_cast<LGFXDriver *>(lv_display_get_driver_data(disp));
+    driver->flush(disp, area, px_map);
     if (!driver->flushAreaValid) {
         driver->flushArea = *area;
         driver->flushAreaValid = true;
@@ -290,6 +293,7 @@ template <class LGFX> void LGFXDriver<LGFX>::display_flush(lv_display_t *disp, c
 {
     uint32_t w = lv_area_get_width(area);
     uint32_t h = lv_area_get_height(area);
+    static_cast<LGFXDriver *>(lv_display_get_driver_data(disp))->flush(disp, area, px_map);
     {
         ISpiLock::Guard bus;
         lgfx->pushImage(area->x1, area->y1, w, h, (uint16_t *)px_map);