# DisplayIdleService & Screensaver Disable-When-Charging + MCP Persistence

## Files
- `Tactility/Source/service/displayidle/DisplayIdle.cpp`
- `Tactility/Private/Tactility/service/displayidle/DisplayIdleService.h`
- `Tactility/Source/service/displayidle/Screensaver.h` (base) + BouncingBalls, MatrixRain, Mystify, StackChan, McpScreensaver

Only compiled `#ifdef ESP_PLATFORM` — not in simulator.

tick()` flow (final — includes 50d86de4 wake fix for RLCD + 6f095081 no-auto-screensaver for monochrome):

- `onStart()`:
  - `srand(time(nullptr))`
  - `cachedDisplaySettings = loadOrGetDefault()` — always, even on RLCD/no-backlight (pre-2026-07-11 early-return killed timer + settings, broke MCP)
  - If `!supportsBacklightDuty()` → log "Monochrome/RLCD detected: idle timer will run but auto-backlight off is disabled" but continue
  - Timer 50ms `TICK_INTERVAL_MS`, Lower priority, start

- `tick()` flow (final):
  1. **MCP active check OUTSIDE LVGL lock (3629ffef)**: `bool isMcpActive = (drawArea != nullptr || overrideActive)` under `state.mutex` BEFORE `lvgl::lock()` — avoids AB/BA deadlock
  2. `lvgl::lock(100)` else return
  3. `lv_display_get_default()==nullptr` → unlock return
  4. `settingsReloadRequested.exchange(false)` → reload under lock
  5. `inactive_ms = lv_display_get_inactive_time(nullptr)` — always read, for all displays (50d86de4: not gated by supportsBacklight)
  6. If `displayDimmed && overlay && !stopRequested && !isMcpActive`: auto-off counter or `updateScreensaver()`
  7. `lvgl::unlock()`
  8. If `stopScreensaverRequested` → `stopScreensaver()`
  9. Get display: `bool supportsBacklight = display != nullptr && display->supportsBacklightDuty()`
  10. **Timeout logic runs for ALL displays (50d86de4)**:
      - If `!timeoutEnabled` or `timeoutMs==0`: if `displayDimmed && !isMcpActive` → if `supportsBacklight` restore duty, `displayDimmed=false` (wake for RLCD too)
      - Else:
        - `charging_blocks = disableScreensaverWhenCharging && isDeviceCharging()`
        - Not dimmed && inactive>=timeout && !charging_blocks → activate (creates screensaver even on RLCD)
        - Dimmed && !isMcpActive && inactive<100ms → stop (wake on touch/button, for RLCD too)
        - Dimmed && !isMcpActive && charging_blocks → stop (wake when plugged)
     - Only `setBacklightDuty()` calls guarded by `supportsBacklight && display != nullptr`

- `stopScreensaverLocked()` requires LVGL lock.

## RLCD Wake Lock Bug (50d86de4) + Permanent Freeze (6f095081) — MUST READ

**Symptom 50d86de4:** "screen seem to be locked..." — RLCD frozen after dim, buttons do nothing, looks crash but serial no Guru Meditation.

**Root Cause 50d86de4:**
Previous MCP fix changed tick() to `if (supportsBacklight) { if (!timeoutEnabled) restore else { activate/wake } }`. RLCD `supportsBacklightDuty()==false` → entire state machine skipped → once `displayDimmed=true`, wake branch `inactive<100ms` never runs → screensaver stuck forever → appears locked.

**Fix 50d86de4:**
Run timeout logic for all displays, guard only duty calls. See final flow above. Build RLCD `0x2b78b0 32% free`.

**Symptom 6f095081:** "screen is still showing the freezed image" after 3770ac89 + 50d86de4 flashed.

**Root Cause 6f095081:**
Even with wake logic fixed, `BouncingBalls` screensaver `full_refresh=true` 300x400 120k pixels SPI 10MHz ~100ms/frame hogs LVGL lock. If SD has `display.properties` with `backlightTimeoutEnabled=1` 60s + BouncingBalls (carried from ES3C28P SD), RLCD auto-enters heavy animation → looks frozen stuck on weird image. RTS reset doesn't clear ST7305 RAM, frozen image persists until power cycle.

**Fix 6f095081:**
- For monochrome/RLCD `!supportsBacklight`: don't auto-enter screensaver, only handle wake. Switch `else {` → `else if (supportsBacklight) {` + `else { // monochrome don't auto-enter }`
- Video stream idle 50→100ms, streaming 5→30ms
- Advise user: unplug USB 3s power cycle to clear frozen RAM, set Timeout=Never or None on RLCD

Verification: outer `if (supportsBacklight)` gates full handling, `else` monochrome only wake, `setBacklightDuty` guarded, `!isMcpActive>=3`.

## MCP Flash-Then-Back Bug (6235fa05)

**Symptom:** "when the text tool is called it is shown on the screen for a small time (less than a second) and back to the previous screen."

**Cause:** After `startMcpScreensaver()` sets `displayDimmed=true`, next `tick()` sees `inactive_ms < 100ms` → `stopScreensaver()` deletes overlay.

**Fix 6235fa05:** Guard all auto-stop with `!isMcpActive` (count >=3). MCP remains closable via `stopScreensaverCb` CLICKABLE overlay.

## Lock Inversion Deadlock (3629ffef)

**Symptom suspected as crash:** RLCD freeze after text tool, serial clean boot to AP `Tactility-5C7D`.

- Video task: `state.mutex -> lvgl::lock()` in `ensureOverrideScreen()`
- Old tick(): `lvgl::lock() -> state.mutex`
- Fix: read `isMcpActive` BEFORE LVGL lock. Rule: MCP mutex first, never LVGL->MCP.
- Verify: `mcp::getState()` pos < `lvgl::lock()` pos. Build `waveshare-esp32-s3-rlcd 0x2b78b0`.

## Screenshot Lock Contention (2026-07-14 observed, fixed 2026-07-14 6f095081)

**Symptom:** "Screenshot failed: could not acquire LVGL lock" from `/api/screenshot` (WebServerService 1522 logs `could not acquire LVGL lock within 100ms`) and `ScreenshotTask` 50ms. Also "screen is still showing the freezed image" when video stream hogs.

**Root Causes:**
- `WebServerService::handleApiScreenshot` used `lvgl::lock(100)` — RLCD ST7305 SPI 10MHz full_refresh 120k pixels ~100ms/copy, 100ms too short
- `ScreenshotTask::makeScreenshot` used 50ms
- `mcp_video_stream_task` loop 5ms streaming hogs LVGL lock → UI appears frozen

**Fixes 6f095081:**
- Web handler 100→500ms + error msg update
- ScreenshotTask 50→300ms
- Video stream idle 50→100ms, streaming 5→30ms + comment "RLCD ST7305 SPI is slow and shared"
- DisplayIdle: for monochrome/RLCD don't auto-enter screensaver (bouncing balls heavy)
- Verification 14 checks PASS hermes-verify-jw_55oxm.py, build 0x2b79e0
- See `references/rlcd-initialization.md` for full init + contention audit

## Charging Guard

Callback overload as in Launcher/Statusbar avoids clangd false-positive. Must combine with `!isMcpActive`.

## Pitfalls
- Early return on `!supportsBacklightDuty()` breaks MCP entirely — always load settings + start timer
- Outer `if (supportsBacklight)` gating timeout/wake breaks RLCD — run for all, guard only duty
- `lv_display_get_inactive_time() < 100ms` kills MCP if guard missing — guard all auto-stop with `!isMcpActive`
- Forgetting `settingsReloadRequested` check races overlay creation
- `findDevices` callback signature `bool(const shared_ptr<T>&)` — clangd may false-report; callback form silences it
- `backlightOff` after auto-off stays off until wake — charging_blocks can wake but only if `!isMcpActive`