notes for troubleshooting later, maybe

claude_notes/ghosting-bisect-debug_2026-01-27_09-42-35.md

@@ -0,0 +1,137 @@
+# Ghosting Issue Bisect Debug Summary
+
+**Date:** 2026-01-27  
+**Branch:** `catch-up-PR-merges`  
+**Issue:** Text ghosting on page turns when anti-aliasing enabled
+
+---
+
+## Problem Description
+
+After merging 15 upstream PRs, ghosting artifacts appeared when turning pages in the EPUB reader. The ghosting manifested as residual edges/outlines of previous page text, visible only when text anti-aliasing was enabled.
+
+---
+
+## The 15 Merged PRs (in merge order)
+
+| Order | Commit | PR | Description |
+|-------|--------|-----|-------------|
+| 1 | `703d955` | #466 | fix: Add .vs folder to .gitignore |
+| 2 | `7a4af97` | #530 | docs: Update README with supported languages for EPUB |
+| 3 | `aa87b3f` | #547 | docs: add font generation commands to builtin font headers |
+| 4 | `25b75b7` | #425 | fix: Allow line break after ellipsis and underscore |
+| 5 | `31199f9` | #507 | fix: remove decimal places from progress % |
+| 6 | `d8b8c5b` | #526 | fix: add txt books to recent tab |
+| 7 | `991b6b5` | #498 | feat: treat .md files as .txt |
+| 8 | `8920c62` | #525 | fix: line break - flush word before br tag |
+| 9 | `3cee01b` | #460 | feat: add new configuration for front buttons |
+| 10 | `f01f397` | #557 | fix: rotate origin in drawImage |
+| 11 | `03a18fb` | #484 | UX improvement to Forget Network page |
+| 12 | `ff0392b` | #492 | fix: Validate settings on read |
+| 13 | `6ffd19a` | #482 | fix: short-press power button to wakeup |
+| 14 | `c90304f` | #465 | fix: cover artifacts - merge crop parameter |
+| 15 | `bc4edee` | #404 | Refactor: Replace CalibreWirelessActivity with CalibreConnectActivity |
+
+**Base commit:** `1a38fd9` (before any PR merges)  
+**Checkpoint commit:** `397abe1` (after all PR merges)
+
+---
+
+## Bisect Process
+
+### Initial State
+- **GOOD:** `1a38fd9` - no ghosting
+- **BAD:** `397abe1` (HEAD) - ghosting present
+
+### Bisect Steps
+
+| Step | Commit | PR | Result | Remaining |
+|------|--------|-----|--------|-----------|
+| 1 | `991b6b5` | #498 (midpoint) | NO ghosting | Bug in commits 8-15 |
+| 2 | `ff0392b` | #492 (midpoint of 8-15) | NO ghosting | Bug in commits 13-15 |
+| 3 | `c90304f` | #465 | NO ghosting | Bug in commits 15 or checkpoint |
+| 4 | `bc4edee` | #404 | NO ghosting | Bug in checkpoint only |
+
+### Compilation Issue During Bisect
+
+A conflict from PR #526 merge left `RECENT_BOOKS.addBook()` with 1 argument instead of 3. This caused compilation failures at intermediate commits. Temporary fix applied at each step:
+
+```cpp
+// Changed from:
+RECENT_BOOKS.addBook(txt->getPath());
+// To:
+RECENT_BOOKS.addBook(txt->getPath(), txt->getTitle(), "");
+```
+
+---
+
+## Root Cause Finding
+
+**The ghosting was NOT caused by any upstream PR.**
+
+After testing all commits, the bisect pointed to the checkpoint commit `397abe1`. However, the diff between `bc4edee` and `397abe1` only contained:
+- The `addBook` fix (unrelated to display)
+- Removing duplicate `handleDownload` (unrelated to display)
+
+### Actual Cause: Uncommitted Local Changes
+
+The ghosting was caused by **uncommitted local changes in the IDE working directory**. These changes were being preserved across `git checkout` operations because they existed in IDE buffers.
+
+When `git checkout -f catch-up-PR-merges` was executed (force checkout), all local changes were discarded and the ghosting disappeared.
+
+---
+
+## Local Changes That Were Present
+
+The following modifications existed in the working directory but were NOT in the checkpoint commit:
+
+- `CrossPointSettings.h/cpp` - enum `_COUNT` suffixes, `readAndValidate`, OPDS auth fields
+- `ChapterHtmlSlimParser.h/cpp` - `flushPartWordBuffer()` function
+- `SleepActivity.cpp` - `drawImage` coordinate changes
+- `JpegToBmpConverter.h/cpp` - `crop` parameter
+- `HomeActivity.cpp` - "OPDS Browser" label
+- `SettingsActivity.cpp` - front button layout options
+- `CrossPointWebServer.h/cpp` - UDP discovery, `WsUploadStatus`
+
+**Important:** These changes were actually already committed in the PR merge commits. The confusion arose because:
+1. Checking out older commits removed these changes
+2. IDE buffers or manual re-application restored them as "local changes"
+3. This created a mismatch between committed code and working directory
+
+---
+
+## Resolution
+
+1. Force checkout to HEAD: `git checkout -f catch-up-PR-merges`
+2. Verified all PR changes are properly committed
+3. Built and tested - no ghosting
+4. Working directory is now clean (matches committed state)
+
+---
+
+## Key Lessons
+
+1. **Always check `git status` before bisecting** - local changes can persist across checkouts
+2. **Use `git checkout -f` or `git checkout <commit> -- .`** to ensure clean state
+3. **IDE buffers can reintroduce changes** - close/reload files after checkout if needed
+4. **Bisecting with compilation errors** requires temporary fixes that don't affect the bug being investigated
+5. **The "bug" may not be in commits at all** - it could be in uncommitted working directory changes
+
+---
+
+## Commands Reference
+
+```bash
+# Force checkout to discard local changes
+git checkout -f <branch>
+
+# Checkout specific commit with clean state
+git checkout <commit> -- . && git checkout <commit>
+
+# Check for uncommitted changes
+git status
+git diff --stat
+
+# View what's in a specific commit
+git show <commit>:path/to/file
+```