# Dictionary Feature Polish & Menu Reorganization

**Date:** 2026-02-12

## Task Description

Continued polishing the dictionary word lookup feature across multiple iterations: fixing side button hint placement and orientation, adding CCW text rotation, fixing pronunciation line rendering, adding index caching, and reorganizing the reader menu.

## Changes Made

### Side button hint fixes (`DictionaryWordSelectActivity.cpp`)
- Moved `drawSideButtonHints` call inside `drawHints()` where renderer is in portrait mode (fixes wrong placement)
- Made all button hint labels orientation-aware (portrait, inverted, landscape CW/CCW each get correct labels matching their button-to-action mapping)
- Replaced `GUI.drawSideButtonHints()` with custom drawing: solid background, overlap/cursor hiding, text truncation, and orientation-aware rotation
- Changed word navigation labels from "Prev Word"/"Next Word" to "« Word"/"Word »"

### GfxRenderer CCW text rotation (`lib/GfxRenderer/`)
- Added `drawTextRotated90CCW()` to `GfxRenderer.h` and `GfxRenderer.cpp`
- Mirrors the existing CW rotation: text reads top-to-bottom instead of bottom-to-top
- Used for side button hints in landscape CCW orientation

### Definition screen fixes (`DictionaryDefinitionActivity.cpp/.h`)
- Fixed pronunciation commas: definitions start with `/ˈsɪm.pəl/, /ˈsɪmpəl/` before `<p>` — now skips all content before first `<` tag in `parseHtml()`
- Added side button hints with proper CCW rotation and solid backgrounds
- Updated bottom button labels: "« Back", "" (hidden stub), "« Page", "Page »"
- Added half refresh on initial screen entry (`firstRender` flag)

### Dictionary index caching (`Dictionary.h/.cpp`)
- New `loadCachedIndex()`: reads `/.dictionary/dictionary.cache` — validates magic + idx file size, loads sparse offsets directly (~7KB binary read vs 17MB scan)
- New `saveCachedIndex()`: persists after first full scan
- Cache format: `[magic 4B][idxFileSize 4B][totalWords 4B][count 4B][offsets N×4B]`
- Auto-invalidates when `.idx` file size changes
- New public methods: `cacheExists()`, `deleteCache()`

### Reader menu reorganization (`EpubReaderMenuActivity.h`, `EpubReaderActivity.cpp`)
- New `MenuAction` enum values: `ADD_BOOKMARK`, `GO_TO_BOOKMARK`, `DELETE_DICT_CACHE`
- Reordered menu: Add Bookmark, Lookup Word, Lookup Word History, Reading Orientation, Table of Contents, Go to Bookmark, Go to %, Close Book, Sync Progress, Delete Book Cache, Delete Dictionary Cache
- Renamed: "Go to Chapter" → "Table of Contents", "Go Home" → "Close Book", "Lookup" → "Lookup Word"
- Bookmark stubs show "Coming soon" popup
- Delete Dictionary Cache checks existence and clears in-memory state

## Files Modified
- `lib/GfxRenderer/GfxRenderer.h` — added `drawTextRotated90CCW` declaration
- `lib/GfxRenderer/GfxRenderer.cpp` — added `drawTextRotated90CCW` implementation
- `src/util/Dictionary.h` — added `cacheExists()`, `deleteCache()`, `loadCachedIndex()`, `saveCachedIndex()`
- `src/util/Dictionary.cpp` — cache load/save implementation, delete cache
- `src/activities/reader/DictionaryWordSelectActivity.cpp` — orientation-aware hints, custom side button drawing
- `src/activities/reader/DictionaryDefinitionActivity.h` — added `firstRender` flag
- `src/activities/reader/DictionaryDefinitionActivity.cpp` — pronunciation fix, side hints, half refresh, label changes
- `src/activities/reader/EpubReaderMenuActivity.h` — new enum values, reordered menu
- `src/activities/reader/EpubReaderActivity.cpp` — handlers for new menu actions

## Follow-up Items
- Bookmark feature implementation (stubs are in place)
- Test CCW text rotation rendering on device
- Verify cache invalidation works when dictionary files are replaced