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:

// 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:

Checking out older commits removed these changes
IDE buffers or manual re-application restored them as "local changes"
This created a mismatch between committed code and working directory

Resolution

Force checkout to HEAD: git checkout -f catch-up-PR-merges
Verified all PR changes are properly committed
Built and tested - no ghosting
Working directory is now clean (matches committed state)

Key Lessons

Always check git status before bisecting - local changes can persist across checkouts
Use git checkout -f or git checkout <commit> -- . to ensure clean state
IDE buffers can reintroduce changes - close/reload files after checkout if needed
Bisecting with compilation errors requires temporary fixes that don't affect the bug being investigated
The "bug" may not be in commits at all - it could be in uncommitted working directory changes

Commands Reference

# 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

5.1 KiB Raw Blame History