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

# 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
```