diff --git a/claude_notes/ghosting-bisect-debug_2026-01-27_09-42-35.md b/claude_notes/ghosting-bisect-debug_2026-01-27_09-42-35.md new file mode 100644 index 0000000..999a661 --- /dev/null +++ b/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 -- .`** 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 + +# Checkout specific commit with clean state +git checkout -- . && git checkout + +# Check for uncommitted changes +git status +git diff --stat + +# View what's in a specific commit +git show :path/to/file +```