Comment cleanup, added refresh delays for stability

CLAUDE.md

@@ -35,7 +35,16 @@ output (LOW silences it). No impact on UART download mode or OTA flashing.
 - 2-bit grayscale fully working via custom component `waveshare_epaper_2bit`
 - LVGL rendering working, 4-shade colorspace confirmed
 - Bayer ordered dithering implemented for gradient smoothing
-- Touchscreen wiring complete, driver integration in progress
+- Touchscreen working: polling mode, mirror_x + mirror_y transforms confirmed correct
+- LVGL touch input and button state working end-to-end
+- **Active: LVGL layout work**
+
+## Display Refresh Pattern
+Two-tier refresh wired to `lvgl.on_draw_end` via two `mode: restart` scripts:
+- **Partial** (`refresh_display`, 60ms): calls `display_partial()` — fast 1-bit, non-blocking, immediate interaction feedback
+- **Full** (`full_refresh_display`, 10s): calls `component.update: display0` → `display()` — full 2-bit grayscale quality restore after idle
+
+60ms was empirically tuned: 80ms felt sluggish, 40ms intermittently raced. `component.update: display0` only pushes the frame buffer to hardware and does not re-trigger `on_draw_end`.
 
 ## Grayscale Implementation
 Custom component model name: `2.90inv2-r2-2bpp`
@@ -43,7 +52,7 @@ Custom component model name: `2.90inv2-r2-2bpp`
 Key implementation details:
 - Gray4 waveform LUT loaded via register 0x32 on every display() call
 - Activation uses 0xC7 (custom LUT), not 0xF7 (which reloads OTP LUT)
-- Always does full refresh — partial update removed from 2bpp class
+- `display()` = full 2-bit grayscale refresh; `display_partial()` = fast 1-bit partial refresh
 - Second bitplane buffer (`buffer2_`) allocated in `initialize()`
 
 Confirmed bitplane table for this panel with Gray4 LUT:
@@ -66,7 +75,7 @@ Amplitude chosen to keep 0xAAAAAA and 0x555555 as solid fills.
 - Touch count at register 0x1001, touch data at 0x1002 (7 bytes/point), clear by writing 0x00 to 0x1001
 - Waveshare's own driver inverts both axes: X = 295 - raw_x, Y = 127 - raw_y
 - INT pulse is very brief (sub-ms); component works in polling mode regardless
-- Coordinate transform (mirror_x, mirror_y, swap_xy) to be confirmed after first flash
+- Coordinate transform: mirror_x + mirror_y confirmed correct; swap_xy not needed
 
 ## Relevant Files
 - Custom component: `custom_components/waveshare_epaper_2bit/`