Integrate PT 1455

docs/epub-toc-navigation.md

@@ -0,0 +1,159 @@
+# EPUB TOC Anchor Navigation
+
+This document describes how the reader handles EPUB Table of Contents (TOC) entries that use fragment anchors to point into spine files, enabling navigation to sub-chapters within a single XHTML file.
+
+## Background: EPUB spine and TOC structure
+
+An EPUB's **spine** is an ordered list of XHTML files that define reading order. The **TOC** (table of contents) maps chapter names to positions in the spine, optionally with fragment anchors (e.g. `chapter1.xhtml#section-5`).
+
+Two layouts are relevant here:
+
+- **1:1** -- one TOC entry per spine item (most common, no anchors needed)
+- **Multi-TOC-per-spine** -- multiple TOC entries point into a single spine file using fragment anchors (e.g. Moby Dick from Project Gutenberg packs 3-9 chapters per file)
+
+Spine items before the first TOC entry (cover pages) and after the last (appendices, copyright) have no TOC entry of their own.
+
+## BookMetadataCache and TOC-to-spine mapping
+
+`BookMetadataCache` builds the mapping between spine items and TOC entries at epub open time. Key details:
+
+- Each `SpineEntry` has a `tocIndex` field set during cache building. For spines with no matching TOC entry, `tocIndex` inherits the previous spine's value (`lastSpineTocIndex`). This means orphan spines (cover pages, appendices) are treated as continuations of the nearest preceding chapter.
+- `getTocIndexForSpineIndex(i)` returns the stored `tocIndex` for spine `i` -- a file seek into BookMetadataCache, not computed on the fly.
+- `getTocItem(i)` returns the TOC entry (title, spineIndex, anchor) for TOC index `i` -- also a file seek per call, not cached in memory. Code that queries TOC metadata in a loop should cache the results locally first.
+- `getSpineIndexForTocIndex(i)` does the reverse lookup (TOC index to spine index).
+
+## Section cache file format
+
+The section cache (`.bin`) stores pre-rendered page data for a spine item. The file layout:
+
+```
+[header: version, render parameters, pageCount, lutOffset, anchorMapOffset]
+[serialized pages...]
+[page LUT: array of uint32_t file offsets, one per page]
+[anchor map: uint16_t count, then (string, uint16_t) pairs]
+```
+
+The header size is defined by `HEADER_SIZE` (a constexpr computed via `sizeof` sum) and validated with a `static_assert`. Three functions read this header independently and must stay in sync:
+
+- `loadSectionFile` -- full section load, reads header + builds TOC boundaries from anchor map
+- `getPageForAnchor` -- seeks directly to anchor map offset from header
+- `writeSectionFileHeader` -- writes the header during cache creation
+
+When modifying the header layout, bump `SECTION_FILE_VERSION` to invalidate stale caches and update all read paths.
+
+## Anchor-to-page mapping
+
+### Recording anchors during parsing
+
+`ChapterHtmlSlimParser` records every HTML `id` attribute and its corresponding page number into `anchorData` (a flat `std::vector<std::pair<std::string, uint16_t>>`). Recording is deferred via `pendingAnchorId` until `startNewTextBlock()`, after the previous text block is flushed to pages via `makePages()`. This ensures `completedPageCount` reflects the correct page.
+
+For TOC anchors specifically, `startNewTextBlock` also forces a page break before recording, so chapters start on fresh pages rather than mid-page. The parser receives the set of TOC anchor strings via `tocAnchors` (a `std::vector<std::string>`) from `Section::createSectionFile`.
+
+### On-disk format
+
+The anchor data is serialized at the end of the section cache file (`.bin`), after the page LUT. The header stores the anchor map offset. Format:
+
+```
+[uint16_t count]
+[string anchor_1][uint16_t page_1]
+[string anchor_2][uint16_t page_2]
+...
+```
+
+This data serves two purposes:
+- **Footnote navigation** (`getPageForAnchor`): on-demand linear scan for a single anchor
+- **TOC boundary resolution** (`buildTocBoundariesFromFile`): scan matching only TOC anchors
+
+### Data structure choices
+
+All anchor storage uses flat vectors, not `std::map` or `std::set`. On the ESP32-C3, each `std::map`/`std::set` node requires its own heap allocation, causing fragmentation. Vectors use a single contiguous allocation. The entry counts are small enough (typically 1-10 TOC anchors per spine, dozens to hundreds of total anchors) that linear scans are faster than tree lookups at these sizes.
+
+## TOC boundaries in Section
+
+When a section is loaded or created, `Section` builds an in-memory `tocBoundaries` vector mapping each TOC entry in that spine to its start page. This is a small vector (1-3 entries typically) that enables O(1) lookups without file I/O.
+
+### Two build paths
+
+**From in-memory anchors** (`buildTocBoundaries`): Called after `createSectionFile` when the parser's anchor vector is still in memory. Iterates TOC entries and does linear scans against the anchor vector.
+
+**From disk** (`buildTocBoundariesFromFile`): Called from `loadSectionFile` when loading a cached section. Caches the small set of TOC anchor strings first (since `getTocItem()` does file I/O to `BookMetadataCache`), then streams through on-disk anchors matching only those, stopping early once all are resolved. Uses a reusable `std::string` buffer to avoid per-entry heap allocation.
+
+The two functions are kept separate because their iteration patterns differ fundamentally: in-memory iterates TOC entries with inner scans of anchors, while the disk path iterates disk entries with inner scans of the small TOC anchor set.
+
+### Early exit optimization
+
+If no TOC entries in the spine have anchors (`unresolvedCount == 0`), both functions return immediately without storing any boundaries. `getTocIndexForPage` falls back to `epub->getTocIndexForSpineIndex`, which gives the correct answer for the common 1:1 case.
+
+### Query methods
+
+- `getTocIndexForPage(page)` -- binary search on sorted `tocBoundaries` to find which chapter a page belongs to
+- `getPageForTocIndex(tocIndex)` -- linear scan to find a chapter's start page
+- `getPageRangeForTocIndex(tocIndex)` -- returns `[startPage, endPage)` range for a chapter within this spine
+
+All are in-memory, no file I/O.
+
+## Chapter navigation in EpubReaderActivity
+
+### Chapter skip (long-press)
+
+Navigates by TOC index, not spine index. Uses `getTocIndexForPage` to determine the current chapter, then increments or decrements.
+
+- **Same-spine skip**: Resolves the target page via `getPageForTocIndex` entirely in memory
+- **Cross-spine skip**: Sets `pendingTocIndex` (a `std::optional<int>`) which is resolved after the target section loads in `render()`
+- **Forward past last TOC entry**: Jumps to end-of-book (spine index clamped in `render()`)
+- **Backward before first TOC entry**: Jumps to the spine before the current chapter's first spine (clamped to 0 in `render()`)
+- **No TOC entry for spine** (`curTocIndex < 0`): Falls back to spine-level skip
+
+### Chapter selector
+
+The chapter selection activity receives `currentTocIndex` (per-page, not per-spine) so it highlights the correct sub-chapter. Returns `ChapterResult` with both `spineIndex` and `std::optional<int> tocIndex`. The reader resolves the page via `getPageForTocIndex` for same-spine navigation or defers via `pendingTocIndex` for cross-spine.
+
+### Footnote navigation
+
+Uses the existing `pendingAnchor` mechanism from the footnote anchor navigation commit (4d222567). `getPageForAnchor` does an on-demand linear scan of the on-disk anchor data. This is separate from TOC boundaries -- it reads all anchors (not just TOC ones) and is only called for footnote jumps.
+
+### Status bar
+
+Uses `getTocIndexForPage()` for the chapter title, so the status bar shows the correct sub-chapter name when reading a multi-TOC-per-spine file.
+
+## Orphan spine handling
+
+Spine items without a TOC entry inherit the previous spine's `tocIndex` in `BookMetadataCache`. This means:
+
+- Pre-TOC spines (cover pages) may have `tocIndex == -1` if they're before any chapter
+- Post-TOC spines (appendices, copyright) inherit the last chapter's `tocIndex`
+
+The chapter skip logic guards against `curTocIndex < 0` and falls back to spine-level navigation.
+
+## Implementation pitfalls and edge cases
+
+### Anchor recording timing
+
+The `pendingAnchorId` deferred recording pattern is critical for correctness. Anchors must be recorded *after* `makePages()` flushes the previous text block (so `completedPageCount` reflects the right page) but the TOC page break must happen *before* recording (so the anchor lands on the new page). Both of these happen inside `startNewTextBlock()`. An earlier design used a `recordAnchor` lambda called at various points in `startElement()`, but this had wrong timing for headings and block elements -- `startNewTextBlock` would consume `pendingAnchorId` before `recordAnchor` could force the page break. Moving all page-break logic into `startNewTextBlock` fixed this.
+
+### pendingAnchorId overwrite on consecutive elements
+
+If two elements with `id` attributes appear before any `startNewTextBlock` call (e.g. nested divs), the second `id` overwrites `pendingAnchorId` and the first anchor is never recorded. This is a known limitation inherited from the footnote anchor navigation commit (4d222567) on master. In practice, TOC anchors are on chapter headings which trigger `startNewTextBlock`, so this doesn't affect TOC navigation.
+
+### wordsExtractedInBlock reset on empty block reuse
+
+When `startNewTextBlock` reuses an empty text block (the early-return path), `wordsExtractedInBlock` must be reset to 0. Without this, footnotes in the reused block could be assigned to wrong pages based on stale word counts from a prior block.
+
+### getTocItem() does file I/O
+
+`epub->getTocItem()` reads from `BookMetadataCache` via file seek on every call. This is why `buildTocBoundariesFromFile` caches the TOC anchor strings into a small vector before entering the disk scan loop -- otherwise the inner loop would do file I/O (BookMetadataCache) for every on-disk anchor entry.
+
+### Defensive sort on tocBoundaries
+
+`tocBoundaries` is sorted by `startPage` after building. In well-formed EPUBs, entries are already in order (TOC follows document order). The sort is a safety net for malformed EPUBs where TOC entries might be out of document order. With 1-3 entries it has no measurable cost.
+
+## Test epub
+
+`scripts/generate_spine_toc_edges_epub.py` generates `test/epubs/test_spine_toc_edges.epub`, a purpose-built epub that exercises spine/TOC relationship patterns. See the script header for the full list of edge cases covered.
+
+## Performance characteristics
+
+- **Per page turn**: All in-memory. `getTocIndexForPage` (binary search on 1-3 entries), `getTocItem` for title (one file seek to BookMetadataCache -- noted as a future optimization opportunity).
+- **Section load**: One file open for the section cache. `buildTocBoundariesFromFile` scans the anchor map for a few TOC entries with early exit.
+- **Footnote navigation**: One additional file open to scan the anchor map for a single anchor.
+- **1:1 TOC-to-spine (common case)**: No overhead. `unresolvedCount == 0`, `tocBoundaries` stays empty, all queries fall back to spine-level methods.

lib/Epub/Epub/Section.cpp

@@ -4,6 +4,8 @@
 #include <Logging.h>
 #include <Serialization.h>
 
+#include <algorithm>
+
 #include "Epub/css/CssParser.h"
 #include "Page.h"
 #include "hyphenation/Hyphenator.h"
@@ -147,6 +149,10 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con
       return false;
     }
   }
+  // Build TOC boundaries by scanning anchor data from the still-open file,
+  // matching only the TOC anchors we need (avoids loading all anchors into memory).
+  buildTocBoundariesFromFile(file);
+
   // File is intentionally left open; subsequent loadPageFromSectionFile() calls
   // seek within this handle instead of re-opening the file each time.
   LOG_DBG("SCT", "Deserialization succeeded: %d pages, LUT cached", pageCount);
@@ -244,11 +250,24 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
     }
   }
 
+  // Collect TOC anchors for this spine so the parser can insert page breaks at chapter boundaries
+  std::vector<std::string> tocAnchors;
+  const int startTocIndex = epub->getTocIndexForSpineIndex(spineIndex);
+  if (startTocIndex >= 0) {
+    for (int i = startTocIndex; i < epub->getTocItemsCount(); i++) {
+      auto entry = epub->getTocItem(i);
+      if (entry.spineIndex != spineIndex) break;
+      if (!entry.anchor.empty()) {
+        tocAnchors.push_back(std::move(entry.anchor));
+      }
+    }
+  }
+
   ChapterHtmlSlimParser visitor(
       epub, tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
       viewportHeight, hyphenationEnabled,
       [this, &lut](std::unique_ptr<Page> page) { lut.emplace_back(this->onPageComplete(std::move(page))); },
-      embeddedStyle, contentBase, imageBasePath, imageRendering, progressFn, cssParser);
+      embeddedStyle, contentBase, imageBasePath, imageRendering, std::move(tocAnchors), progressFn, cssParser);
   Hyphenator::setPreferredLanguage(epub->getLanguage());
   success = visitor.parseAndBuildPages();
 
@@ -281,7 +300,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
     return false;
   }
 
-  // Write anchor-to-page map for fragment navigation (e.g. footnote targets)
+  // Write anchor-to-page map for fragment navigation (TOC + footnote targets)
   const uint32_t anchorMapOffset = file.position();
   const auto& anchors = visitor.getAnchors();
   serialization::writePod(file, static_cast<uint16_t>(anchors.size()));
@@ -309,6 +328,8 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
     cssParser->clear();
   }
 
+  buildTocBoundaries(anchors);
+
   // Cache the LUT in memory and open the file for reading so that
   // subsequent loadPageFromSectionFile() calls can seek directly without re-opening.
   if (!Storage.openFileForRead("SCT", filePath, file)) {
@@ -342,6 +363,158 @@ std::unique_ptr<Page> Section::loadPageFromSectionFile() {
   // File is intentionally NOT closed; stays open for the next page load
 }
 
+// Resolve TOC anchor-to-page mappings from the parser's in-memory anchor vector.
+// Called after createSectionFile when anchors are already in memory.
+// See buildTocBoundariesFromFile for the on-disk variant; the two are kept separate
+// because the anchor resolution has fundamentally different iteration patterns
+// (scan in-memory vector vs. stream from file with early exit).
+void Section::buildTocBoundaries(const std::vector<std::pair<std::string, uint16_t>>& anchors) {
+  const int startTocIndex = epub->getTocIndexForSpineIndex(spineIndex);
+  if (startTocIndex < 0) return;
+
+  // Count TOC entries for this spine and how many have anchors to resolve
+  const int tocCount = epub->getTocItemsCount();
+  uint16_t totalEntries = 0;
+  uint16_t unresolvedCount = 0;
+  for (int i = startTocIndex; i < tocCount; i++) {
+    const auto entry = epub->getTocItem(i);
+    if (entry.spineIndex != spineIndex) break;
+    totalEntries++;
+    if (!entry.anchor.empty()) unresolvedCount++;
+  }
+
+  // If no TOC entries have anchors, all chapters start at page 0 and
+  // getTocIndexForPage falls back to epub->getTocIndexForSpineIndex,
+  // so there's nothing to resolve and no value in storing boundaries.
+  if (totalEntries == 0 || unresolvedCount == 0) return;
+
+  tocBoundaries.reserve(totalEntries);
+  for (int i = startTocIndex; i < startTocIndex + totalEntries; i++) {
+    const auto entry = epub->getTocItem(i);
+    uint16_t page = 0;
+    if (!entry.anchor.empty()) {
+      for (const auto& [key, val] : anchors) {
+        if (key == entry.anchor) {
+          page = val;
+          break;
+        }
+      }
+    }
+    tocBoundaries.push_back({i, page});
+  }
+
+  // Defensive sort in case TOC entries are out of document order in a malformed epub
+  std::sort(tocBoundaries.begin(), tocBoundaries.end(),
+            [](const TocBoundary& a, const TocBoundary& b) { return a.startPage < b.startPage; });
+}
+
+// Resolve TOC anchor-to-page mappings by scanning the section cache's on-disk anchor data.
+// Called from loadSectionFile when anchors are not in memory. Caches the small set of
+// TOC anchor strings first (since getTocItem does file I/O to BookMetadataCache), then
+// streams through on-disk anchors matching only those, stopping as soon as all are found.
+// See buildTocBoundaries for the in-memory variant.
+void Section::buildTocBoundariesFromFile(FsFile& f) {
+  const int startTocIndex = epub->getTocIndexForSpineIndex(spineIndex);
+  if (startTocIndex < 0) return;
+
+  // Count TOC entries for this spine, then reserve and populate
+  const int tocCount = epub->getTocItemsCount();
+  uint16_t totalEntries = 0;
+  uint16_t unresolvedCount = 0;
+  for (int i = startTocIndex; i < tocCount; i++) {
+    const auto entry = epub->getTocItem(i);
+    if (entry.spineIndex != spineIndex) break;
+    totalEntries++;
+    if (!entry.anchor.empty()) unresolvedCount++;
+  }
+
+  // If no TOC entries have anchors, all chapters start at page 0 and
+  // getTocIndexForPage falls back to epub->getTocIndexForSpineIndex,
+  // so there's nothing to resolve and no value in storing boundaries.
+  if (totalEntries == 0 || unresolvedCount == 0) return;
+
+  // Cache TOC anchor strings before scanning disk, since getTocItem() does file I/O
+  struct TocAnchorEntry {
+    int tocIndex;
+    std::string anchor;
+  };
+  std::vector<TocAnchorEntry> tocAnchorsToResolve;
+  tocAnchorsToResolve.reserve(unresolvedCount);
+  tocBoundaries.reserve(totalEntries);
+  for (int i = startTocIndex; i < startTocIndex + totalEntries; i++) {
+    const auto entry = epub->getTocItem(i);
+    tocBoundaries.push_back({i, 0});
+    if (!entry.anchor.empty()) {
+      tocAnchorsToResolve.push_back({i, std::move(entry.anchor)});
+    }
+  }
+
+  // Single pass through on-disk anchors, matching against cached TOC anchors.
+  // Stop early once all TOC anchors are resolved.
+  // Header layout: ... | lutOffset (u32) | anchorMapOffset (u32) | paragraphLutOffset (u32) |
+  f.seek(HEADER_SIZE - sizeof(uint32_t) * 2);
+  uint32_t anchorMapOffset;
+  serialization::readPod(f, anchorMapOffset);
+
+  if (anchorMapOffset != 0) {
+    f.seek(anchorMapOffset);
+    uint16_t count;
+    serialization::readPod(f, count);
+    std::string key;
+    for (uint16_t i = 0; i < count && unresolvedCount > 0; i++) {
+      uint16_t page;
+      serialization::readString(f, key);
+      serialization::readPod(f, page);
+      for (auto& tocAnchor : tocAnchorsToResolve) {
+        if (!tocAnchor.anchor.empty() && key == tocAnchor.anchor) {
+          tocBoundaries[tocAnchor.tocIndex - startTocIndex].startPage = page;
+          tocAnchor.anchor.clear();  // mark resolved
+          unresolvedCount--;
+          break;
+        }
+      }
+    }
+  }
+
+  // Defensive sort in case TOC entries are out of document order in a malformed epub
+  std::sort(tocBoundaries.begin(), tocBoundaries.end(),
+            [](const TocBoundary& a, const TocBoundary& b) { return a.startPage < b.startPage; });
+}
+
+int Section::getTocIndexForPage(const int page) const {
+  if (tocBoundaries.empty()) {
+    return epub->getTocIndexForSpineIndex(spineIndex);
+  }
+
+  // Find the first boundary AFTER page, then step back one
+  auto it = std::upper_bound(tocBoundaries.begin(), tocBoundaries.end(), static_cast<uint16_t>(page),
+                             [](uint16_t page, const TocBoundary& boundary) { return page < boundary.startPage; });
+  if (it == tocBoundaries.begin()) {
+    return tocBoundaries[0].tocIndex;
+  }
+  return std::prev(it)->tocIndex;
+}
+
+std::optional<int> Section::getPageForTocIndex(const int tocIndex) const {
+  for (const auto& boundary : tocBoundaries) {
+    if (boundary.tocIndex == tocIndex) {
+      return boundary.startPage;
+    }
+  }
+  return std::nullopt;
+}
+
+std::optional<Section::TocPageRange> Section::getPageRangeForTocIndex(const int tocIndex) const {
+  for (size_t i = 0; i < tocBoundaries.size(); i++) {
+    if (tocBoundaries[i].tocIndex == tocIndex) {
+      const int startPage = tocBoundaries[i].startPage;
+      const int endPage = (i + 1 < tocBoundaries.size()) ? static_cast<int>(tocBoundaries[i + 1].startPage) : pageCount;
+      return TocPageRange{startPage, endPage};
+    }
+  }
+  return std::nullopt;
+}
+
 std::optional<uint16_t> Section::getPageForAnchor(const std::string& anchor) const {
   FsFile f;
   if (!Storage.openFileForRead("SCT", filePath, f)) {

lib/Epub/Epub/Section.h

@@ -23,6 +23,15 @@ class Section {
                               bool embeddedStyle, uint8_t imageRendering);
   uint32_t onPageComplete(std::unique_ptr<Page> page);
 
+  struct TocBoundary {
+    int tocIndex = 0;
+    uint16_t startPage = 0;
+  };
+  std::vector<TocBoundary> tocBoundaries;
+
+  void buildTocBoundaries(const std::vector<std::pair<std::string, uint16_t>>& anchors);
+  void buildTocBoundariesFromFile(FsFile& f);
+
  public:
   uint16_t pageCount = 0;
   int currentPage = 0;
@@ -42,6 +51,19 @@ class Section {
                          uint8_t imageRendering, const std::function<void(int)>& progressFn = nullptr);
   std::unique_ptr<Page> loadPageFromSectionFile();
 
+  // Given a page in this section, return the TOC index for that page.
+  int getTocIndexForPage(int page) const;
+  // Given a TOC index, return the start page in this section.
+  // Returns nullopt if the TOC index doesn't map to a boundary in this spine (e.g. belongs to a different spine).
+  std::optional<int> getPageForTocIndex(int tocIndex) const;
+
+  struct TocPageRange {
+    int startPage;  // inclusive
+    int endPage;    // exclusive
+  };
+  // Returns the page range [start, end) within this spine that belongs to the given TOC index.
+  std::optional<TocPageRange> getPageRangeForTocIndex(int tocIndex) const;
+
   // Look up the page number for an anchor id from the section cache file.
   std::optional<uint16_t> getPageForAnchor(const std::string& anchor) const;
 

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -7,6 +7,8 @@
 #include <Utf8.h>
 #include <expat.h>
 
+#include <algorithm>
+
 #include "../../Epub.h"
 #include "../Page.h"
 #include "../converters/ImageDecoderFactory.h"
@@ -146,15 +148,35 @@ void ChapterHtmlSlimParser::startNewTextBlock(const BlockStyle& blockStyle) {
       currentTextBlock->setBlockStyle(currentTextBlock->getBlockStyle().getCombinedBlockStyle(incoming));
 
       if (!pendingAnchorId.empty()) {
+        if (std::find(tocAnchors.begin(), tocAnchors.end(), pendingAnchorId) != tocAnchors.end()) {
+          if (currentPage && !currentPage->elements.empty()) {
+            completePageFn(std::move(currentPage));
+            completedPageCount++;
+            currentPage.reset(new Page());
+            currentPageNextY = 0;
+          }
+        }
         anchorData.push_back({std::move(pendingAnchorId), static_cast<uint16_t>(completedPageCount)});
         pendingAnchorId.clear();
       }
+      wordsExtractedInBlock = 0;
       return;
     }
 
     makePages();
   }
-  // Record deferred anchor after previous block is flushed
+  // If the pending anchor is a TOC chapter boundary, force a page break after the previous
+  // block is flushed so the chapter starts on a fresh page.
+  if (!pendingAnchorId.empty() &&
+      std::find(tocAnchors.begin(), tocAnchors.end(), pendingAnchorId) != tocAnchors.end()) {
+    if (currentPage && !currentPage->elements.empty()) {
+      completePageFn(std::move(currentPage));
+      completedPageCount++;
+      currentPage.reset(new Page());
+      currentPageNextY = 0;
+    }
+  }
+  // Record deferred anchor after previous block is flushed (and any TOC page break)
   if (!pendingAnchorId.empty()) {
     anchorData.push_back({std::move(pendingAnchorId), static_cast<uint16_t>(completedPageCount)});
     pendingAnchorId.clear();
@@ -182,7 +204,8 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
       } else if (strcmp(atts[i], "style") == 0) {
         styleAttr = atts[i + 1];
       } else if (strcmp(atts[i], "id") == 0) {
-        // Defer recording until startNewTextBlock, after previous block is flushed to pages
+        // Defer both anchor recording and TOC page breaks until startNewTextBlock,
+        // after the previous block is flushed to pages via makePages().
         self->pendingAnchorId = atts[i + 1];
       }
     }

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h

@@ -74,6 +74,7 @@ class ChapterHtmlSlimParser {
   int completedPageCount = 0;
   std::vector<std::pair<std::string, uint16_t>> anchorData;
   std::string pendingAnchorId;  // deferred until after previous text block is flushed
+  std::vector<std::string> tocAnchors;
 
   // Paragraph index tracking for XPath-to-page lookup table.
   // Counts <p> sibling indices (1-based, matching XPath convention) during page building.
@@ -110,6 +111,7 @@ class ChapterHtmlSlimParser {
                                  const std::function<void(std::unique_ptr<Page>)>& completePageFn,
                                  const bool embeddedStyle, const std::string& contentBase,
                                  const std::string& imageBasePath, const uint8_t imageRendering = 0,
+                                 std::vector<std::string> tocAnchors = {},
                                  const std::function<void(int)>& progressFn = nullptr,
                                  const CssParser* cssParser = nullptr)
 
@@ -129,7 +131,8 @@ class ChapterHtmlSlimParser {
         embeddedStyle(embeddedStyle),
         imageRendering(imageRendering),
         contentBase(contentBase),
-        imageBasePath(imageBasePath) {}
+        imageBasePath(imageBasePath),
+        tocAnchors(std::move(tocAnchors)) {}
 
   ~ChapterHtmlSlimParser() = default;
   bool parseAndBuildPages();

src/activities/ActivityResult.h

@@ -2,6 +2,7 @@
 
 #include <cstdint>
 #include <functional>
+#include <optional>
 #include <string>
 #include <type_traits>
 #include <utility>
@@ -27,6 +28,7 @@ struct MenuResult {
 
 struct ChapterResult {
   int spineIndex = 0;
+  std::optional<int> tocIndex;
 };
 
 struct PercentResult {

src/activities/reader/EpubReaderActivity.cpp

@@ -219,14 +219,58 @@ void EpubReaderActivity::loop() {
 
   const bool skipChapter = SETTINGS.longPressChapterSkip && mappedInput.getHeldTime() > skipChapterMs;
 
+  // Chapter skip navigates by TOC entries, not spine boundaries.
+  // Spine items without their own TOC entry inherit the previous spine's tocIndex
+  // (see BookMetadataCache), so they're treated as continuations of the last chapter.
+  // At the boundaries: skipping forward past the last TOC entry jumps to end-of-book
+  // (clamped in render()); skipping backward before the first TOC entry jumps to the
+  // spine before the current chapter's first spine (clamped to 0 in render()).
   if (skipChapter) {
     lastPageTurnTime = millis();
-    // We don't want to delete the section mid-render, so grab the semaphore
     {
       RenderLock lock(*this);
-      nextPageNumber = 0;
+
-      currentSpineIndex = nextTriggered ? currentSpineIndex + 1 : currentSpineIndex - 1;
+      if (section && section->pageCount > 0) {
-      section.reset();
+        const int curTocIndex = section->getTocIndexForPage(section->currentPage);
+        const int nextTocIndex = nextTriggered ? curTocIndex + 1 : curTocIndex - 1;
+
+        if (curTocIndex < 0) {
+          // No TOC entry for this spine, fall back to spine-level skip
+          nextPageNumber = 0;
+          currentSpineIndex = nextTriggered ? currentSpineIndex + 1 : currentSpineIndex - 1;
+          section.reset();
+        } else if (nextTocIndex >= 0 && nextTocIndex < epub->getTocItemsCount()) {
+          const int newSpineIndex = epub->getSpineIndexForTocIndex(nextTocIndex);
+
+          if (newSpineIndex == currentSpineIndex) {
+            if (const auto resolvedPage = section->getPageForTocIndex(nextTocIndex)) {
+              section->currentPage = *resolvedPage;
+            } else {
+              LOG_DBG("ERS", "No page boundary for TOC %d in spine %d, staying on current page", nextTocIndex,
+                      currentSpineIndex);
+            }
+          } else {
+            pendingTocIndex = nextTocIndex;
+            nextPageNumber = 0;
+            currentSpineIndex = newSpineIndex;
+            section.reset();
+          }
+        } else if (nextTriggered) {
+          // Beyond last TOC entry, go to end of book
+          nextPageNumber = 0;
+          currentSpineIndex = epub->getSpineItemsCount();
+          section.reset();
+        } else {
+          // Before first TOC entry, skip to spine before the current chapter
+          nextPageNumber = 0;
+          currentSpineIndex = epub->getTocItem(curTocIndex).spineIndex - 1;
+          section.reset();
+        }
+      } else {
+        nextPageNumber = 0;
+        currentSpineIndex = nextTriggered ? currentSpineIndex + 1 : currentSpineIndex - 1;
+        section.reset();
+      }
     }
     requestUpdate();
     return;
@@ -312,13 +356,23 @@ void EpubReaderActivity::onReaderMenuConfirm(EpubReaderMenuActivity::MenuAction
   switch (action) {
     case EpubReaderMenuActivity::MenuAction::SELECT_CHAPTER: {
       const int spineIdx = currentSpineIndex;
+      const int tocIdx = section ? section->getTocIndexForPage(section->currentPage)
+                                 : epub->getTocIndexForSpineIndex(currentSpineIndex);
       const std::string path = epub->getPath();
       startActivityForResult(
-          std::make_unique<EpubReaderChapterSelectionActivity>(renderer, mappedInput, epub, path, spineIdx),
+          std::make_unique<EpubReaderChapterSelectionActivity>(renderer, mappedInput, epub, path, spineIdx, tocIdx),
           [this](const ActivityResult& result) {
-            if (!result.isCancelled && currentSpineIndex != std::get<ChapterResult>(result.data).spineIndex) {
+            if (result.isCancelled) return;
-              RenderLock lock(*this);
+            RenderLock lock(*this);
-              currentSpineIndex = std::get<ChapterResult>(result.data).spineIndex;
+            const auto& chapter = std::get<ChapterResult>(result.data);
+            auto resolvedPage = (chapter.tocIndex && chapter.spineIndex == currentSpineIndex && section)
+                                    ? section->getPageForTocIndex(*chapter.tocIndex)
+                                    : std::nullopt;
+            if (resolvedPage) {
+              section->currentPage = *resolvedPage;
+            } else {
+              pendingTocIndex = chapter.tocIndex;
+              currentSpineIndex = chapter.spineIndex;
               nextPageNumber = 0;
               section.reset();
             }
@@ -613,7 +667,7 @@ void EpubReaderActivity::render(RenderLock&& lock) {
     const uint8_t imageRendering = getEffectiveImageRendering();
     const auto filepath = epub->getSpineItem(currentSpineIndex).href;
     LOG_DBG("ERS", "Loading file: %s, index: %d", filepath.c_str(), currentSpineIndex);
-    section = std::unique_ptr<Section>(new Section(epub, currentSpineIndex, renderer));
+    section = std::make_unique<Section>(epub, currentSpineIndex, renderer);
 
     if (!section->loadSectionFile(SETTINGS.getReaderFontId(), SETTINGS.getReaderLineCompression(),
                                   SETTINGS.extraParagraphSpacing, SETTINGS.paragraphAlignment, viewportWidth,
@@ -646,6 +700,13 @@ void EpubReaderActivity::render(RenderLock&& lock) {
       section->currentPage = nextPageNumber;
     }
 
+    if (pendingTocIndex) {
+      if (const auto resolvedPage = section->getPageForTocIndex(*pendingTocIndex)) {
+        section->currentPage = *resolvedPage;
+      }
+      pendingTocIndex.reset();
+    }
+
     if (!pendingAnchor.empty()) {
       if (const auto page = section->getPageForAnchor(pendingAnchor)) {
         section->currentPage = *page;
@@ -895,28 +956,25 @@ void EpubReaderActivity::renderStatusBar() const {
   const float bookProgress = epub->calculateProgress(currentSpineIndex, sectionChapterProg) * 100;
 
   std::string title;
-
   int textYOffset = 0;
 
   if (automaticPageTurnActive) {
     title = tr(STR_AUTO_TURN_ENABLED) + std::to_string(60 * 1000 / pageTurnDuration);
 
-    // calculates textYOffset when rendering title in status bar
     const uint8_t statusBarHeight = UITheme::getInstance().getStatusBarHeight();
-
-    // offsets text if no status bar or progress bar only
     if (statusBarHeight == 0 || statusBarHeight == UITheme::getInstance().getProgressBarHeight()) {
       textYOffset += UITheme::getInstance().getMetrics().statusBarVerticalMargin;
     }
 
   } else if (SETTINGS.statusBarTitle == CrossPointSettings::STATUS_BAR_TITLE::CHAPTER_TITLE) {
-    title = tr(STR_UNNAMED);
+    const int tocIndex =
-    const int tocIndex = epub->getTocIndexForSpineIndex(currentSpineIndex);
+        section ? section->getTocIndexForPage(section->currentPage) : epub->getTocIndexForSpineIndex(currentSpineIndex);
-    if (tocIndex != -1) {
+    if (tocIndex == -1) {
+      title = tr(STR_UNNAMED);
+    } else {
       const auto tocItem = epub->getTocItem(tocIndex);
       title = tocItem.title;
     }
-
   } else if (SETTINGS.statusBarTitle == CrossPointSettings::STATUS_BAR_TITLE::BOOK_TITLE) {
     title = epub->getTitle();
   }

src/activities/reader/EpubReaderActivity.h

@@ -3,6 +3,8 @@
 #include <Epub/FootnoteEntry.h>
 #include <Epub/Section.h>
 
+#include <optional>
+
 #include "EpubReaderMenuActivity.h"
 #include "activities/Activity.h"
 
@@ -11,6 +13,9 @@ class EpubReaderActivity final : public Activity {
   std::unique_ptr<Section> section = nullptr;
   int currentSpineIndex = 0;
   int nextPageNumber = 0;
+  // Set when navigating to a TOC entry in a different spine (chapter skip or chapter selector).
+  // Cleared on the next render after the new section loads and resolves it to a page.
+  std::optional<int> pendingTocIndex;
   // Set when navigating to a footnote href with a fragment (e.g. #note1).
   // Cleared on the next render after the new section loads and resolves it to a page.
   std::string pendingAnchor;

src/activities/reader/EpubReaderChapterSelectionActivity.cpp

@@ -25,7 +25,9 @@ void EpubReaderChapterSelectionActivity::onEnter() {
     return;
   }
 
-  selectorIndex = epub->getTocIndexForSpineIndex(currentSpineIndex);
+  selectorIndex = (currentTocIndex >= 0 && currentTocIndex < epub->getTocItemsCount())
+                      ? currentTocIndex
+                      : epub->getTocIndexForSpineIndex(currentSpineIndex);
   if (selectorIndex == -1) {
     selectorIndex = 0;
   }
@@ -48,7 +50,7 @@ void EpubReaderChapterSelectionActivity::loop() {
       setResult(std::move(result));
       finish();
     } else {
-      setResult(ChapterResult{newSpineIndex});
+      setResult(ChapterResult{newSpineIndex, selectorIndex});
       finish();
     }
   } else if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {

src/activities/reader/EpubReaderChapterSelectionActivity.h

@@ -11,6 +11,7 @@ class EpubReaderChapterSelectionActivity final : public Activity {
   std::string epubPath;
   ButtonNavigator buttonNavigator;
   int currentSpineIndex = 0;
+  int currentTocIndex = 0;
   int selectorIndex = 0;
 
   // Number of items that fit on a page, derived from logical screen height.
@@ -23,11 +24,12 @@ class EpubReaderChapterSelectionActivity final : public Activity {
  public:
   explicit EpubReaderChapterSelectionActivity(GfxRenderer& renderer, MappedInputManager& mappedInput,
                                               const std::shared_ptr<Epub>& epub, const std::string& epubPath,
-                                              const int currentSpineIndex)
+                                              const int currentSpineIndex, const int currentTocIndex)
       : Activity("EpubReaderChapterSelection", renderer, mappedInput),
         epub(epub),
         epubPath(epubPath),
-        currentSpineIndex(currentSpineIndex) {}
+        currentSpineIndex(currentSpineIndex),
+        currentTocIndex(currentTocIndex) {}
   void onEnter() override;
   void onExit() override;
   void loop() override;