No actionable comments were generated in the recent review. 🎉

Learnt from: Uri-Tauber
Repo: crosspoint-reader/crosspoint-reader PR: 988
File: lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp:649-661
Timestamp: 2026-02-19T12:17:05.421Z
Learning: In ChapterHtmlSlimParser.cpp, when computing footnote word indices in endElement() for footnote links, the wordIndex must be cumulative across the 750-word mid-paragraph flush boundary. The correct calculation is: `wordIndex = wordsExtractedInBlock + currentTextBlock->size()`, not just `currentTextBlock->size()`. This ensures footnotes attach to the page containing their actual anchor word, even after layoutAndExtractLines(false) has extracted and removed earlier words from the block.

Learnt from: Uri-Tauber
Repo: crosspoint-reader/crosspoint-reader PR: 988
File: lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp:649-661
Timestamp: 2026-02-19T12:17:05.421Z
Learning: In ChapterHtmlSlimParser.cpp, when computing footnote word indices in endElement() for footnote links, the wordIndex must be cumulative across the 750-word mid-paragraph flush boundary. The correct calculation is: `wordIndex = wordsExtractedInBlock + currentTextBlock->size()`, not just `currentTextBlock->size()`. This ensures footnotes attach to the page containing their actual anchor word, even after layoutAndExtractLines(false) has extracted and removed earlier words from the block.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

I added some logging for the various layout phases and had Claude put together a summary of the differences:

List vs Vector Text Layout Performance Comparison

Test book: Intermezzo by Sally Rooney, chapter 14 (contains a 2,420-word paragraph).
Device: ESP32-C3, ~230KB total heap.

Headline numbers

Early flush behavior

Both logs show exactly 3 early flushes for the 2,420-word paragraph, with size dropping to single digits after each:

early flush triggered: size=880  → size after=2
early flush triggered: size=793  → size after=4
early flush triggered: size=752  → size after=1

This confirms the erase change works correctly. Without it, you'd see size=751, 752, 753... firing on every word -- ~1,670 redundant flushes instead of 3.

The three early flush passes compared

The first flush is an outlier where list's extract was faster (possibly cold cache). On the 2nd and 3rd flushes, vector's contiguous memory wins decisively.

Medium paragraphs

Vector is 10-14% faster across the board for medium paragraphs.

Smallest paragraphs

These samples span the full 1-25 word range. At tiny sizes, fixed overhead dominates and results can be noisy, but vector is generally faster across this range.

Memory

The heap values during the early flushes tell the real story. Look at the heap before each flush (the low-water mark, when all the words are buffered but not yet extracted):

The list version dipped to 63KB free during the second flush. On an ESP32 with ~230KB total heap, that's only 27% remaining -- dangerously close to allocation failures if other subsystems (fonts, zip streams, CSS) need memory simultaneously.

The vector version never went below 126KB free -- roughly double the headroom. The ~63KB difference directly matches the per-node overhead: 880 words x 3 lists x ~24 bytes (prev/next pointers + malloc bookkeeping) = ~63KB.

Phase breakdown

The biggest wins come from extract, but the phase-level breakdown shows where both small and large gains appear:

What this shows:

• measure is almost identical between list and vector (typically <2% delta).
• breaks improves modestly with vector (about 1-10% depending on paragraph).
• extract carries almost all of the total win on medium/large paragraphs (about 15-21% faster in the examples above).
• erase is present only in vector and adds just ~90-133 us, far too small to offset extract gains.

This aligns with expected access patterns: extracting 100+ lines repeatedly touches many word entries; contiguous storage keeps iteration cache-friendly while list traversal pays pointer-chasing costs on every pass.

Erase cost

The erase step added by the fix costs 90-133 microseconds per flush -- 0.1% of total flush time. Completely negligible.