# Letterbox Fill Redesign

**Date:** 2026-02-13
**Task:** Strip out the 5-mode letterbox edge fill system and replace with a simplified 3-mode design

## Changes Made

### Problem
The existing letterbox fill feature had 5 modes (None, Solid, Blended, Gradient, Matched) with ~300 lines of complex code including per-pixel edge arrays, malloc'd buffers, binary edge caching, framebuffer-level column/row copying, and a gradient direction sub-setting. Several modes introduced visual corruption that couldn't be resolved.

### New Design
Simplified to 3 modes:
- **None** -- no fill
- **Solid** -- computes dominant edge color, snaps to nearest of 4 e-ink levels (black/dark gray/light gray/white), fills uniformly
- **Blended** -- computes dominant edge color, fills with exact gray value using noise dithering for smooth approximation

### Files Changed

1. **`src/CrossPointSettings.h`** -- Removed `LETTERBOX_GRADIENT`, `LETTERBOX_MATCHED` enum values; removed `SLEEP_SCREEN_GRADIENT_DIR` enum and `sleepScreenGradientDir` member; changed default to `LETTERBOX_NONE`

2. **`src/SettingsList.h`** -- Trimmed Letterbox Fill options to `{None, Solid, Blended}`; removed Gradient Direction setting entry

3. **`src/CrossPointSettings.cpp`** -- Removed `sleepScreenGradientDir` from write path; added dummy read for backward compatibility with old settings files; decremented `SETTINGS_COUNT` from 32 to 31

4. **`src/activities/boot_sleep/SleepActivity.cpp`** -- Major rewrite:
   - Removed: `LetterboxGradientData` struct, `loadEdgeCache()`/`saveEdgeCache()`, `sampleBitmapEdges()`, `copyEdgeRowsToLetterbox()`, old `drawLetterboxFill()`
   - Added: `LetterboxFillData` struct (2 bytes vs arrays), `snapToEinkLevel()`, `computeEdgeAverages()` (running sums only, no malloc), simplified `drawLetterboxFill()`
   - Cleaned `renderBitmapSleepScreen()`: removed matched/gradient logic, edge cache paths, unused `scaledWidth`/`scaledHeight`
   - Cleaned `renderCoverSleepScreen()`: removed edge cache path derivation
   - Removed unused includes (`<Serialization.h>`, `<cstring>`), added `<cmath>`

5. **`src/activities/boot_sleep/SleepActivity.h`** -- Removed `edgeCachePath` parameter from `renderBitmapSleepScreen()` signature; removed unused `<string>` include

### Backward Compatibility
- Enum values 0/1/2 (None/Solid/Blended) unchanged -- existing settings preserved
- Old Gradient (3) or Matched (4) values rejected by `readAndValidate`, falling back to default (None)
- Old `sleepScreenGradientDir` byte consumed via dummy read during settings load
- Orphaned `_edges.bin` cache files on SD cards are harmless

## Follow-up Items
- Test all 3 fill modes on device with various cover aspect ratios
- Consider cleaning up orphaned `_edges.bin` files (optional, low priority)