Merge 94411049c8 into da4d3b5ea5

## Summary

Extracted some changes from
https://github.com/crosspoint-reader/crosspoint-reader/pull/500 to make
reviewing easier

This PR adds HAL (Hardware Abstraction Layer) for display and GPIO
components, making it easier to write a stub or an emulated
implementation of the hardware.

SD card HAL will be added via another PR, because it's a bit more
tricky.

---

### AI Usage

While CrossPoint doesn't have restrictions on AI tools in contributing,
please be transparent about their usage as it
helps set the right context for reviewers.

Did you use AI tools to help write this code? **NO**

.gitignore

@@ -6,4 +6,6 @@ lib/EpdFont/fontsrc
 *.generated.h
 .vs
 build
-**/__pycache__/
+**/__pycache__/
+/compile_commands.json
+/.cache

lib/Epub/Epub.cpp

@@ -208,6 +208,10 @@ bool Epub::parseTocNavFile() const {
 bool Epub::load(const bool buildIfMissing) {
   Serial.printf("[%lu] [EBP] Loading ePub: %s\n", millis(), filepath.c_str());
 
+  if (!footnotePages) {
+    footnotePages = new std::unordered_set<std::string>();
+  }
+
   // Initialize spine/TOC cache
   bookMetadataCache.reset(new BookMetadataCache(cachePath));
 
@@ -528,7 +532,8 @@ int Epub::getSpineItemsCount() const {
   if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
     return 0;
   }
-  return bookMetadataCache->getSpineCount();
+  int virtualCount = virtualSpineItems ? virtualSpineItems->size() : 0;
+  return bookMetadataCache->getSpineCount() + virtualCount;
 }
 
 size_t Epub::getCumulativeSpineItemSize(const int spineIndex) const { return getSpineItem(spineIndex).cumulativeSize; }
@@ -539,6 +544,15 @@ BookMetadataCache::SpineEntry Epub::getSpineItem(const int spineIndex) const {
     return {};
   }
 
+  // Virtual spine item
+  if (isVirtualSpineItem(spineIndex)) {
+    int virtualIndex = spineIndex - bookMetadataCache->getSpineCount();
+    if (virtualSpineItems && virtualIndex >= 0 && virtualIndex < static_cast<int>(virtualSpineItems->size())) {
+      // Create a dummy spine entry for virtual item
+      return BookMetadataCache::SpineEntry((*virtualSpineItems)[virtualIndex], 0, -1);
+    }
+  }
+
   if (spineIndex < 0 || spineIndex >= bookMetadataCache->getSpineCount()) {
     Serial.printf("[%lu] [EBP] getSpineItem index:%d is out of range\n", millis(), spineIndex);
     return bookMetadataCache->getSpineEntry(0);
@@ -628,6 +642,83 @@ int Epub::getSpineIndexForTextReference() const {
   return 0;
 }
 
+void Epub::markAsFootnotePage(const std::string& href) {
+  // Lazy initialization
+  if (!footnotePages) {
+    footnotePages = new std::unordered_set<std::string>();
+  }
+
+  // Extract filename from href (remove #anchor if present)
+  size_t hashPos = href.find('#');
+  std::string filename = (hashPos != std::string::npos) ? href.substr(0, hashPos) : href;
+
+  // Extract just the filename without path
+  size_t lastSlash = filename.find_last_of('/');
+  if (lastSlash != std::string::npos) {
+    filename = filename.substr(lastSlash + 1);
+  }
+
+  footnotePages->insert(filename);
+  Serial.printf("[%lu] [EPUB] Marked as footnote page: %s\n", millis(), filename.c_str());
+}
+
+bool Epub::isFootnotePage(const std::string& filename) const {
+  if (!footnotePages) return false;
+  return footnotePages->find(filename) != footnotePages->end();
+}
+
+bool Epub::shouldHideFromToc(int spineIndex) const {
+  // Always hide virtual spine items
+  if (isVirtualSpineItem(spineIndex)) {
+    return true;
+  }
+
+  BookMetadataCache::SpineEntry entry = getSpineItem(spineIndex);
+  const std::string& spineItem = entry.href;
+
+  // Extract filename from spine item
+  size_t lastSlash = spineItem.find_last_of('/');
+  std::string filename = (lastSlash != std::string::npos) ? spineItem.substr(lastSlash + 1) : spineItem;
+
+  return isFootnotePage(filename);
+}
+
+// Virtual spine items
+int Epub::addVirtualSpineItem(const std::string& path) {
+  // Lazy initialization
+  if (!virtualSpineItems) {
+    virtualSpineItems = new std::vector<std::string>();
+  }
+
+  virtualSpineItems->push_back(path);
+  // Fix: use cache spine count instead of spine.size()
+  int currentSpineSize = bookMetadataCache ? bookMetadataCache->getSpineCount() : 0;
+  int newIndex = currentSpineSize + virtualSpineItems->size() - 1;
+  Serial.printf("[%lu] [EPUB] Added virtual spine item: %s (index %d)\n", millis(), path.c_str(), newIndex);
+  return newIndex;
+}
+
+bool Epub::isVirtualSpineItem(int spineIndex) const {
+  int currentSpineSize = bookMetadataCache ? bookMetadataCache->getSpineCount() : 0;
+  return spineIndex >= currentSpineSize;
+}
+
+int Epub::findVirtualSpineIndex(const std::string& filename) const {
+  if (!virtualSpineItems) return -1;
+  int currentSpineSize = bookMetadataCache ? bookMetadataCache->getSpineCount() : 0;
+
+  for (size_t i = 0; i < virtualSpineItems->size(); i++) {
+    std::string virtualPath = (*virtualSpineItems)[i];
+    size_t lastSlash = virtualPath.find_last_of('/');
+    std::string virtualFilename = (lastSlash != std::string::npos) ? virtualPath.substr(lastSlash + 1) : virtualPath;
+
+    if (virtualFilename == filename) {
+      return currentSpineSize + i;
+    }
+  }
+  return -1;
+}
+
 // Calculate progress in book (returns 0.0-1.0)
 float Epub::calculateProgress(const int currentSpineIndex, const float currentSpineRead) const {
   const size_t bookSize = getBookSize();

lib/Epub/Epub.h

@@ -5,6 +5,7 @@
 #include <memory>
 #include <string>
 #include <unordered_map>
+#include <unordered_set>
 #include <vector>
 
 #include "Epub/BookMetadataCache.h"
@@ -20,22 +21,30 @@ class Epub {
   std::string filepath;
   // the base path for items in the EPUB file
   std::string contentBasePath;
-  // Uniq cache key based on filepath
   std::string cachePath;
   // Spine and TOC cache
   std::unique_ptr<BookMetadataCache> bookMetadataCache;
 
+  // Use pointers, allocate only if needed
+  std::unordered_set<std::string>* footnotePages;
+  std::vector<std::string>* virtualSpineItems;
+
   bool findContentOpfFile(std::string* contentOpfFile) const;
   bool parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata);
   bool parseTocNcxFile() const;
   bool parseTocNavFile() const;
 
  public:
-  explicit Epub(std::string filepath, const std::string& cacheDir) : filepath(std::move(filepath)) {
+  explicit Epub(std::string filepath, const std::string& cacheDir)
-    // create a cache key based on the filepath
+      : filepath(std::move(filepath)), footnotePages(nullptr), virtualSpineItems(nullptr) {
     cachePath = cacheDir + "/epub_" + std::to_string(std::hash<std::string>{}(this->filepath));
   }
-  ~Epub() = default;
+
+  ~Epub() {
+    delete footnotePages;
+    delete virtualSpineItems;
+  }
+
   std::string& getBasePath() { return contentBasePath; }
   bool load(bool buildIfMissing = true);
   bool clearCache() const;
@@ -62,6 +71,13 @@ class Epub {
   size_t getCumulativeSpineItemSize(int spineIndex) const;
   int getSpineIndexForTextReference() const;
 
+  void markAsFootnotePage(const std::string& href);
+  bool isFootnotePage(const std::string& filename) const;
+  bool shouldHideFromToc(int spineIndex) const;
+  int addVirtualSpineItem(const std::string& path);
+  bool isVirtualSpineItem(int spineIndex) const;
+  int findVirtualSpineIndex(const std::string& filename) const;
+
   size_t getBookSize() const;
   float calculateProgress(int currentSpineIndex, float currentSpineRead) const;
 };

lib/Epub/Epub/FootnoteEntry.h

@@ -0,0 +1,12 @@
+#pragma once
+
+struct FootnoteEntry {
+  char number[3];
+  char href[64];
+  bool isInline;
+
+  FootnoteEntry() : isInline(false) {
+    number[0] = '\0';
+    href[0] = '\0';
+  }
+};

lib/Epub/Epub/Page.cpp

@@ -43,6 +43,16 @@ bool Page::serialize(FsFile& file) const {
     }
   }
 
+  // Serialize footnotes
+  int32_t fCount = footnotes.size();
+  serialization::writePod(file, fCount);
+  for (const auto& fn : footnotes) {
+    file.write(fn.number, 3);
+    file.write(fn.href, 64);
+    uint8_t isInlineFlag = fn.isInline ? 1 : 0;
+    file.write(&isInlineFlag, 1);
+  }
+
   return true;
 }
 
@@ -65,5 +75,18 @@ std::unique_ptr<Page> Page::deserialize(FsFile& file) {
     }
   }
 
+  int32_t footnoteCount;
+  serialization::readPod(file, footnoteCount);
+
+  for (int i = 0; i < footnoteCount; i++) {
+    FootnoteEntry entry;
+    file.read(entry.number, 3);
+    file.read(entry.href, 64);
+    uint8_t isInlineFlag = 0;
+    file.read(&isInlineFlag, 1);
+    entry.isInline = (isInlineFlag != 0);
+    page->footnotes.push_back(entry);
+  }
+
   return page;
 }

lib/Epub/Epub/Page.h

@@ -1,16 +1,15 @@
-#pragma once
 #include <SdFat.h>
 
 #include <utility>
 #include <vector>
 
+#include "FootnoteEntry.h"
 #include "blocks/TextBlock.h"
 
 enum PageElementTag : uint8_t {
   TAG_PageLine = 1,
 };
 
-// represents something that has been added to a page
 class PageElement {
  public:
   int16_t xPos;
@@ -21,7 +20,6 @@ class PageElement {
   virtual bool serialize(FsFile& file) = 0;
 };
 
-// a line from a block element
 class PageLine final : public PageElement {
   std::shared_ptr<TextBlock> block;
 
@@ -37,6 +35,19 @@ class Page {
  public:
   // the list of block index and line numbers on this page
   std::vector<std::shared_ptr<PageElement>> elements;
+  std::vector<FootnoteEntry> footnotes;
+
+  void addFootnote(const char* number, const char* href) {
+    FootnoteEntry entry;
+    // ensure null termination and bounds
+    strncpy(entry.number, number, 2);
+    entry.number[2] = '\0';
+    strncpy(entry.href, href, 63);
+    entry.href[63] = '\0';
+    entry.isInline = false;  // Default
+    footnotes.push_back(entry);
+  }
+
   void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) const;
   bool serialize(FsFile& file) const;
   static std::unique_ptr<Page> deserialize(FsFile& file);

lib/Epub/Epub/Section.cpp

@@ -3,6 +3,10 @@
 #include <SDCardManager.h>
 #include <Serialization.h>
 
+#include <fstream>
+#include <set>
+
+#include "FsHelpers.h"
 #include "Page.h"
 #include "hyphenation/Hyphenator.h"
 #include "parsers/ChapterHtmlSlimParser.h"
@@ -14,6 +18,60 @@ constexpr uint32_t HEADER_SIZE = sizeof(uint8_t) + sizeof(int) + sizeof(float) +
                                  sizeof(uint32_t);
 }  // namespace
 
+// Helper function to write XML-escaped text directly to file
+static bool writeEscapedXml(FsFile& file, const char* text) {
+  if (!text) return true;
+
+  // Use a static buffer to avoid heap allocation
+  static char buffer[2048];
+  int bufferPos = 0;
+
+  while (*text && bufferPos < sizeof(buffer) - 10) {  // Leave margin for entities
+    unsigned char c = (unsigned char)*text;
+
+    // Only escape the 5 XML special characters
+    if (c == '<') {
+      if (bufferPos + 4 < sizeof(buffer)) {
+        memcpy(&buffer[bufferPos], "&lt;", 4);
+        bufferPos += 4;
+      }
+    } else if (c == '>') {
+      if (bufferPos + 4 < sizeof(buffer)) {
+        memcpy(&buffer[bufferPos], "&gt;", 4);
+        bufferPos += 4;
+      }
+    } else if (c == '&') {
+      if (bufferPos + 5 < sizeof(buffer)) {
+        memcpy(&buffer[bufferPos], "&amp;", 5);
+        bufferPos += 5;
+      }
+    } else if (c == '"') {
+      if (bufferPos + 6 < sizeof(buffer)) {
+        memcpy(&buffer[bufferPos], "&quot;", 6);
+        bufferPos += 6;
+      }
+    } else if (c == '\'') {
+      if (bufferPos + 6 < sizeof(buffer)) {
+        memcpy(&buffer[bufferPos], "&apos;", 6);
+        bufferPos += 6;
+      }
+    } else {
+      // Keep everything else (include UTF8)
+      buffer[bufferPos++] = (char)c;
+    }
+
+    text++;
+  }
+
+  buffer[bufferPos] = '\0';
+
+  // Write all at once
+  size_t written = file.write((const uint8_t*)buffer, bufferPos);
+  file.flush();
+
+  return written == bufferPos;
+}
+
 uint32_t Section::onPageComplete(std::unique_ptr<Page> page) {
   if (!file) {
     Serial.printf("[%lu] [SCT] File not open for writing page %d\n", millis(), pageCount);
@@ -25,7 +83,8 @@ uint32_t Section::onPageComplete(std::unique_ptr<Page> page) {
     Serial.printf("[%lu] [SCT] Failed to serialize page %d\n", millis(), pageCount);
     return 0;
   }
-  Serial.printf("[%lu] [SCT] Page %d processed\n", millis(), pageCount);
+  // Debug reduce log spam
+  // Serial.printf("[%lu] [SCT] Page %d processed\n", millis(), pageCount);
 
   pageCount++;
   return position;
@@ -104,7 +163,6 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con
   return true;
 }
 
-// Your updated class method (assuming you are using the 'SD' object, which is a wrapper for a specific filesystem)
 bool Section::clearCache() const {
   if (!SdMan.exists(filePath.c_str())) {
     Serial.printf("[%lu] [SCT] Cache does not exist, no action needed\n", millis());
@@ -126,7 +184,9 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
                                 const std::function<void()>& progressSetupFn,
                                 const std::function<void(int)>& progressFn) {
   constexpr uint32_t MIN_SIZE_FOR_PROGRESS = 50 * 1024;  // 50KB
-  const auto localPath = epub->getSpineItem(spineIndex).href;
+
+  BookMetadataCache::SpineEntry spineEntry = epub->getSpineItem(spineIndex);
+  const std::string localPath = spineEntry.href;
   const auto tmpHtmlPath = epub->getCachePath() + "/.tmp_" + std::to_string(spineIndex) + ".html";
 
   // Create cache directory if it doesn't exist
@@ -135,43 +195,43 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
     SdMan.mkdir(sectionsDir.c_str());
   }
 
-  // Retry logic for SD card timing issues
+  bool isVirtual = epub->isVirtualSpineItem(spineIndex);
   bool success = false;
   uint32_t fileSize = 0;
-  for (int attempt = 0; attempt < 3 && !success; attempt++) {
+  std::string fileToParse = tmpHtmlPath;
-    if (attempt > 0) {
+
-      Serial.printf("[%lu] [SCT] Retrying stream (attempt %d)...\n", millis(), attempt + 1);
+  if (isVirtual) {
-      delay(50);  // Brief delay before retry
+    Serial.printf("[%lu] [SCT] Processing virtual spine item: %s\n", millis(), localPath.c_str());
+    // For virtual items, the path is already on SD, e.g. /sd/cache/...
+    // But we need to make sure the parser can read it.
+    // If it starts with /sd/, we might need to strip it if using SdFat with root?
+    // Assuming absolute path is fine.
+    fileToParse = localPath;
+    success = true;
+    fileSize = 0;  // Don't check size for progress bar on virtual items
+  } else {
+    // Normal file - stream from zip
+    for (int attempt = 0; attempt < 3 && !success; attempt++) {
+      if (attempt > 0) delay(50);
+
+      if (SdMan.exists(tmpHtmlPath.c_str())) SdMan.remove(tmpHtmlPath.c_str());
+
+      FsFile tmpHtml;
+      if (!SdMan.openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) continue;
+      success = epub->readItemContentsToStream(localPath, tmpHtml, 1024);
+      fileSize = tmpHtml.size();
+      tmpHtml.close();
+
+      if (!success && SdMan.exists(tmpHtmlPath.c_str())) SdMan.remove(tmpHtmlPath.c_str());
     }
 
-    // Remove any incomplete file from previous attempt before retrying
+    if (!success) {
-    if (SdMan.exists(tmpHtmlPath.c_str())) {
+      Serial.printf("[%lu] [SCT] Failed to stream item contents\n", millis());
-      SdMan.remove(tmpHtmlPath.c_str());
+      return false;
-    }
-
-    FsFile tmpHtml;
-    if (!SdMan.openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) {
-      continue;
-    }
-    success = epub->readItemContentsToStream(localPath, tmpHtml, 1024);
-    fileSize = tmpHtml.size();
-    tmpHtml.close();
-
-    // If streaming failed, remove the incomplete file immediately
-    if (!success && SdMan.exists(tmpHtmlPath.c_str())) {
-      SdMan.remove(tmpHtmlPath.c_str());
-      Serial.printf("[%lu] [SCT] Removed incomplete temp file after failed attempt\n", millis());
     }
   }
 
-  if (!success) {
+  // Only show progress bar for larger chapters
-    Serial.printf("[%lu] [SCT] Failed to stream item contents to temp file after retries\n", millis());
-    return false;
-  }
-
-  Serial.printf("[%lu] [SCT] Streamed temp HTML to %s (%d bytes)\n", millis(), tmpHtmlPath.c_str(), fileSize);
-
-  // Only show progress bar for larger chapters where rendering overhead is worth it
   if (progressSetupFn && fileSize >= MIN_SIZE_FOR_PROGRESS) {
     progressSetupFn();
   }
@@ -183,15 +243,44 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
                          viewportHeight, hyphenationEnabled);
   std::vector<uint32_t> lut = {};
 
-  ChapterHtmlSlimParser visitor(
+  std::unique_ptr<ChapterHtmlSlimParser> visitor(new ChapterHtmlSlimParser(
-      tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
+      fileToParse, renderer, fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
       viewportHeight, hyphenationEnabled,
       [this, &lut](std::unique_ptr<Page> page) { lut.emplace_back(this->onPageComplete(std::move(page))); },
-      progressFn);
+      progressFn));
-  Hyphenator::setPreferredLanguage(epub->getLanguage());
+
-  success = visitor.parseAndBuildPages();
+  Hyphenator::setPreferredLanguage(epub->getLanguage());
+
+  // Track which inline footnotes AND paragraph notes are actually referenced in this file
+  std::set<std::string> rewrittenInlineIds;
+  int noterefCount = 0;
+
+  visitor->setNoterefCallback([this, &noterefCount, &rewrittenInlineIds](Noteref& noteref) {
+    // Extract the ID from the href for tracking
+    std::string href(noteref.href);
+
+    // Check if this was rewritten to an inline or paragraph note
+    if (href.find("inline_") == 0 || href.find("pnote_") == 0) {
+      size_t underscorePos = href.find('_');
+      size_t dotPos = href.find('.');
+
+      if (underscorePos != std::string::npos && dotPos != std::string::npos) {
+        std::string noteId = href.substr(underscorePos + 1, dotPos - underscorePos - 1);
+        rewrittenInlineIds.insert(noteId);
+      }
+    } else {
+      // Normal external footnote
+      epub->markAsFootnotePage(noteref.href);
+    }
+    noterefCount++;
+  });
+
+  success = visitor->parseAndBuildPages();
+
+  if (!isVirtual) {
+    SdMan.remove(tmpHtmlPath.c_str());
+  }
 
-  SdMan.remove(tmpHtmlPath.c_str());
   if (!success) {
     Serial.printf("[%lu] [SCT] Failed to parse XML and build pages\n", millis());
     file.close();
@@ -199,9 +288,77 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
     return false;
   }
 
+  // --- Footnote Generation Logic (Merged from HEAD) ---
+
+  // Inline footnotes
+  for (int i = 0; i < visitor->inlineFootnoteCount; i++) {
+    const char* inlineId = visitor->inlineFootnotes[i].id;
+    const char* inlineText = visitor->inlineFootnotes[i].text;
+
+    if (rewrittenInlineIds.find(std::string(inlineId)) == rewrittenInlineIds.end()) continue;
+    if (!inlineText || strlen(inlineText) == 0) continue;
+
+    char inlineFilename[64];
+    snprintf(inlineFilename, sizeof(inlineFilename), "inline_%s.html", inlineId);
+    std::string fullPath = epub->getCachePath() + "/" + std::string(inlineFilename);
+
+    FsFile file;
+    if (SdMan.openFileForWrite("SCT", fullPath, file)) {
+      file.println("<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
+      file.println("<!DOCTYPE html>");
+      file.println("<html xmlns=\"http://www.w3.org/1999/xhtml\">");
+      file.println("<head><meta charset=\"UTF-8\"/><title>Footnote</title></head>");
+      file.println("<body>");
+      file.print("<p id=\"");
+      file.print(inlineId);
+      file.print("\">");
+      writeEscapedXml(file, inlineText);
+      file.println("</p></body></html>");
+      file.close();
+
+      int virtualIndex = epub->addVirtualSpineItem(fullPath);
+      char newHref[128];
+      snprintf(newHref, sizeof(newHref), "%s#%s", inlineFilename, inlineId);
+      epub->markAsFootnotePage(newHref);
+    }
+  }
+
+  // Paragraph notes
+  for (int i = 0; i < visitor->paragraphNoteCount; i++) {
+    const char* pnoteId = visitor->paragraphNotes[i].id;
+    const char* pnoteText = visitor->paragraphNotes[i].text;
+
+    if (!pnoteText || strlen(pnoteText) == 0) continue;
+    if (rewrittenInlineIds.find(std::string(pnoteId)) == rewrittenInlineIds.end()) continue;
+
+    char pnoteFilename[64];
+    snprintf(pnoteFilename, sizeof(pnoteFilename), "pnote_%s.html", pnoteId);
+    std::string fullPath = epub->getCachePath() + "/" + std::string(pnoteFilename);
+
+    FsFile file;
+    if (SdMan.openFileForWrite("SCT", fullPath, file)) {
+      file.println("<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
+      file.println("<!DOCTYPE html>");
+      file.println("<html xmlns=\"http://www.w3.org/1999/xhtml\">");
+      file.println("<head><meta charset=\"UTF-8\"/><title>Note</title></head>");
+      file.println("<body>");
+      file.print("<p id=\"");
+      file.print(pnoteId);
+      file.print("\">");
+      writeEscapedXml(file, pnoteText);
+      file.println("</p></body></html>");
+      file.close();
+
+      int virtualIndex = epub->addVirtualSpineItem(fullPath);
+      char newHref[128];
+      snprintf(newHref, sizeof(newHref), "%s#%s", pnoteFilename, pnoteId);
+      epub->markAsFootnotePage(newHref);
+    }
+  }
+
+  // Write LUT (master)
   const uint32_t lutOffset = file.position();
   bool hasFailedLutRecords = false;
-  // Write LUT
   for (const uint32_t& pos : lut) {
     if (pos == 0) {
       hasFailedLutRecords = true;

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -30,7 +30,6 @@ constexpr int NUM_SKIP_TAGS = sizeof(SKIP_TAGS) / sizeof(SKIP_TAGS[0]);
 
 bool isWhitespace(const char c) { return c == ' ' || c == '\r' || c == '\n' || c == '\t'; }
 
-// given the start and end of a tag, check to see if it matches a known tag
 bool matches(const char* tag_name, const char* possible_tags[], const int possible_tag_count) {
   for (int i = 0; i < possible_tag_count; i++) {
     if (strcmp(tag_name, possible_tags[i]) == 0) {
@@ -40,89 +39,378 @@ bool matches(const char* tag_name, const char* possible_tags[], const int possib
   return false;
 }
 
+const char* getAttribute(const XML_Char** atts, const char* attrName) {
+  if (!atts) return nullptr;
+
+  for (int i = 0; atts[i]; i += 2) {
+    if (strcmp(atts[i], attrName) == 0) {
+      return atts[i + 1];
+    }
+  }
+  return nullptr;
+}
+
+// Simple HTML entity replacement for noteref text
+std::string replaceHtmlEntities(const char* text) {
+  if (!text) return "";
+  std::string s(text);
+
+  // Replace common entities
+  size_t pos = 0;
+  while ((pos = s.find("&lt;", pos)) != std::string::npos) {
+    s.replace(pos, 4, "<");
+    pos += 1;
+  }
+  pos = 0;
+  while ((pos = s.find("&gt;", pos)) != std::string::npos) {
+    s.replace(pos, 4, ">");
+    pos += 1;
+  }
+  pos = 0;
+  while ((pos = s.find("&amp;", pos)) != std::string::npos) {
+    s.replace(pos, 5, "&");
+    pos += 1;
+  }
+  pos = 0;
+  while ((pos = s.find("&quot;", pos)) != std::string::npos) {
+    s.replace(pos, 6, "\"");
+    pos += 1;
+  }
+  pos = 0;
+  while ((pos = s.find("&apos;", pos)) != std::string::npos) {
+    s.replace(pos, 6, "'");
+    pos += 1;
+  }
+  return s;
+}
+
+EpdFontFamily::Style ChapterHtmlSlimParser::getCurrentFontStyle() const {
+  if (boldUntilDepth < depth && italicUntilDepth < depth) {
+    return EpdFontFamily::BOLD_ITALIC;
+  } else if (boldUntilDepth < depth) {
+    return EpdFontFamily::BOLD;
+  } else if (italicUntilDepth < depth) {
+    return EpdFontFamily::ITALIC;
+  }
+  return EpdFontFamily::REGULAR;
+}
+
 // flush the contents of partWordBuffer to currentTextBlock
 void ChapterHtmlSlimParser::flushPartWordBuffer() {
-  // determine font style
+  EpdFontFamily::Style fontStyle = getCurrentFontStyle();
-  EpdFontFamily::Style fontStyle = EpdFontFamily::REGULAR;
-  if (boldUntilDepth < depth && italicUntilDepth < depth) {
-    fontStyle = EpdFontFamily::BOLD_ITALIC;
-  } else if (boldUntilDepth < depth) {
-    fontStyle = EpdFontFamily::BOLD;
-  } else if (italicUntilDepth < depth) {
-    fontStyle = EpdFontFamily::ITALIC;
-  }
   // flush the buffer
   partWordBuffer[partWordBufferIndex] = '\0';
-  currentTextBlock->addWord(partWordBuffer, fontStyle);
+  currentTextBlock->addWord(std::move(replaceHtmlEntities(partWordBuffer)), fontStyle);
   partWordBufferIndex = 0;
 }
 
 // start a new text block if needed
 void ChapterHtmlSlimParser::startNewTextBlock(const TextBlock::Style style) {
   if (currentTextBlock) {
-    // already have a text block running and it is empty - just reuse it
     if (currentTextBlock->isEmpty()) {
       currentTextBlock->setStyle(style);
       return;
     }
-
     makePages();
   }
   currentTextBlock.reset(new ParsedText(style, extraParagraphSpacing, hyphenationEnabled));
 }
 
+void ChapterHtmlSlimParser::addFootnoteToCurrentPage(const char* number, const char* href) {
+  if (currentPageFootnoteCount >= 16) return;
+
+  Serial.printf("[%lu] [ADDFT] Adding footnote: num=%s, href=%s\n", millis(), number, href);
+
+  // Copy number
+  strncpy(currentPageFootnotes[currentPageFootnoteCount].number, number, 2);
+  currentPageFootnotes[currentPageFootnoteCount].number[2] = '\0';
+
+  // Check if this is an inline footnote reference
+  const char* hashPos = strchr(href, '#');
+  if (hashPos) {
+    const char* inlineId = hashPos + 1;  // Skip the '#'
+
+    // Check if we have this inline footnote
+    bool foundInline = false;
+    for (int i = 0; i < inlineFootnoteCount; i++) {
+      if (strcmp(inlineFootnotes[i].id, inlineId) == 0) {
+        // This is an inline footnote! Rewrite the href
+        char rewrittenHref[64];
+        snprintf(rewrittenHref, sizeof(rewrittenHref), "inline_%s.html#%s", inlineId, inlineId);
+
+        strncpy(currentPageFootnotes[currentPageFootnoteCount].href, rewrittenHref, 63);
+        currentPageFootnotes[currentPageFootnoteCount].href[63] = '\0';
+
+        Serial.printf("[%lu] [ADDFT] Rewrote inline href to: %s\n", millis(), rewrittenHref);
+        foundInline = true;
+        break;
+      }
+    }
+
+    // Check if we have this as a paragraph note
+    if (!foundInline) {
+      for (int i = 0; i < paragraphNoteCount; i++) {
+        if (strcmp(paragraphNotes[i].id, inlineId) == 0) {
+          char rewrittenHref[64];
+          snprintf(rewrittenHref, sizeof(rewrittenHref), "pnote_%s.html#%s", inlineId, inlineId);
+
+          strncpy(currentPageFootnotes[currentPageFootnoteCount].href, rewrittenHref, 63);
+          currentPageFootnotes[currentPageFootnoteCount].href[63] = '\0';
+
+          Serial.printf("[%lu] [ADDFT] Rewrote paragraph note href to: %s\n", millis(), rewrittenHref);
+          foundInline = true;
+          break;
+        }
+      }
+    }
+
+    if (!foundInline) {
+      // Normal href, just copy it
+      strncpy(currentPageFootnotes[currentPageFootnoteCount].href, href, 63);
+      currentPageFootnotes[currentPageFootnoteCount].href[63] = '\0';
+    }
+  } else {
+    // No anchor, just copy
+    strncpy(currentPageFootnotes[currentPageFootnoteCount].href, href, 63);
+    currentPageFootnotes[currentPageFootnoteCount].href[63] = '\0';
+  }
+
+  currentPageFootnoteCount++;
+
+  Serial.printf("[%lu] [ADDFT] Stored as: num=%s, href=%s\n", millis(),
+                currentPageFootnotes[currentPageFootnoteCount - 1].number,
+                currentPageFootnotes[currentPageFootnoteCount - 1].href);
+}
+
 void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char* name, const XML_Char** atts) {
   auto* self = static_cast<ChapterHtmlSlimParser*>(userData);
 
+  // ============================================================================
+  // PASS 1: Detect and collect <p class="note">
+  // ============================================================================
+  if (strcmp(name, "p") == 0 && self->isPass1CollectingAsides) {
+    const char* classAttr = getAttribute(atts, "class");
+
+    if (classAttr && (strcmp(classAttr, "note") == 0 || strstr(classAttr, "note"))) {
+      Serial.printf("[%lu] [PNOTE] Found paragraph note (pass1=1)\n", millis());
+
+      self->insideParagraphNote = true;
+      self->paragraphNoteDepth = self->depth;
+      self->currentParagraphNoteTextLen = 0;
+      self->currentParagraphNoteText[0] = '\0';
+      self->currentParagraphNoteId[0] = '\0';
+
+      self->depth += 1;
+      return;
+    }
+  }
+
+  // Inside paragraph note in Pass 1, look for <a id="rnoteX">
+  if (self->insideParagraphNote && self->isPass1CollectingAsides && strcmp(name, "a") == 0) {
+    const char* id = getAttribute(atts, "id");
+
+    if (id && strncmp(id, "rnote", 5) == 0) {
+      strncpy(self->currentParagraphNoteId, id, 15);
+      self->currentParagraphNoteId[15] = '\0';
+      Serial.printf("[%lu] [PNOTE] Found note ID: %s\n", millis(), id);
+    }
+
+    self->depth += 1;
+    return;
+  }
+
+  // ============================================================================
+  // PASS 1: Detect and collect <aside epub:type="footnote">
+  // ============================================================================
+  if (strcmp(name, "aside") == 0) {
+    const char* epubType = getAttribute(atts, "epub:type");
+    const char* id = getAttribute(atts, "id");
+
+    if (epubType && strcmp(epubType, "footnote") == 0 && id) {
+      if (self->isPass1CollectingAsides) {
+        // Pass 1: Collect aside
+        Serial.printf("[%lu] [ASIDE] Found inline footnote: id=%s (pass1=%d)\n", millis(), id,
+                      self->isPass1CollectingAsides);
+
+        self->insideAsideFootnote = true;
+        self->asideDepth = self->depth;
+        self->currentAsideTextLen = 0;
+        self->currentAsideText[0] = '\0';
+
+        strncpy(self->currentAsideId, id, 2);
+        self->currentAsideId[2] = '\0';
+      } else {
+        // Pass 2: Skip the aside (we already have it from Pass 1)
+        Serial.printf("[%lu] [ASIDE] Skipping aside in Pass 2: id=%s\n", millis(), id);
+
+        // Find the inline footnote text
+        for (int i = 0; i < self->inlineFootnoteCount; i++) {
+          if (strcmp(self->inlineFootnotes[i].id, id) == 0 && self->inlineFootnotes[i].text) {
+            // Output the footnote text as normal text
+            const char* text = self->inlineFootnotes[i].text;
+            int textLen = strlen(text);
+
+            // Process it through characterData
+            self->characterData(self, text, textLen);
+
+            Serial.printf("[%lu] [ASIDE] Rendered aside text: %.80s...\n", millis(), text);
+            break;
+          }
+        }
+
+        // Skip the aside element itself
+        self->skipUntilDepth = self->depth;
+      }
+
+      self->depth += 1;
+      return;
+    }
+  }
+
+  // ============================================================================
+  // PASS 1: Skip everything else
+  // ============================================================================
+  if (self->isPass1CollectingAsides) {
+    self->depth += 1;
+    return;
+  }
+
+  // ============================================================================
+  // PASS 2: Skip <p class="note"> (we already have them from Pass 1)
+  // ============================================================================
+  if (strcmp(name, "p") == 0) {
+    const char* classAttr = getAttribute(atts, "class");
+
+    if (classAttr && (strcmp(classAttr, "note") == 0 || strstr(classAttr, "note"))) {
+      Serial.printf("[%lu] [PNOTE] Skipping paragraph note in Pass 2\n", millis());
+      self->skipUntilDepth = self->depth;
+      self->depth += 1;
+      return;
+    }
+  }
+
+  // ============================================================================
+  // PASS 2: Normal parsing
+  // ============================================================================
+
   // Middle of skip
   if (self->skipUntilDepth < self->depth) {
     self->depth += 1;
     return;
   }
 
+  // Rest of startElement logic for pass 2...
+  if (strcmp(name, "sup") == 0) {
+    self->supDepth = self->depth;
+
+    // Case A: Found <sup> inside a normal <a> (which wasn't marked as a note yet)
+    // Example: <a href="..."><sup>*</sup></a>
+    if (self->anchorDepth != -1 && !self->insideNoteref) {
+      Serial.printf("[%lu] [NOTEREF] Found <sup> inside <a>, promoting to noteref\n", millis());
+
+      // Flush the current word buffer (text before the sup is normal text)
+      if (self->partWordBufferIndex > 0) {
+        self->flushPartWordBuffer();
+      }
+
+      // Activate footnote mode
+      self->insideNoteref = true;
+      self->currentNoterefTextLen = 0;
+      self->currentNoterefText[0] = '\0';
+      // Note: The href was already saved to currentNoterefHref when the <a> was opened (see below)
+    }
+  }
+
+  // === Update the existing A block ===
+  if (strcmp(name, "a") == 0) {
+    const char* epubType = getAttribute(atts, "epub:type");
+    const char* href = getAttribute(atts, "href");
+
+    // Save Anchor state
+    self->anchorDepth = self->depth;
+
+    // Optimistically save the href, in case this becomes a footnote later (via internal <sup>)
+    if (!self->insideNoteref) {
+      if (href) {
+        strncpy(self->currentNoterefHref, href, 127);
+        self->currentNoterefHref[127] = '\0';
+      } else {
+        self->currentNoterefHref[0] = '\0';
+      }
+    }
+
+    // Footnote detection: via epub:type, rnote pattern, or if we are already inside a <sup>
+    // Case B: Found <a> inside <sup>
+    // Example: <sup><a href="...">1</a></sup>
+    bool isNoteref = (epubType && strcmp(epubType, "noteref") == 0);
+
+    if (!isNoteref && href && href[0] == '#' && strncmp(href + 1, "rnote", 5) == 0) {
+      isNoteref = true;
+    }
+
+    // New detection: if we are inside SUP, this link is a footnote
+    if (!isNoteref && self->supDepth != -1) {
+      isNoteref = true;
+      Serial.printf("[%lu] [NOTEREF] Found <a> inside <sup>, treating as noteref\n", millis());
+    }
+
+    if (isNoteref) {
+      Serial.printf("[%lu] [NOTEREF] Found noteref: href=%s\n", millis(), href ? href : "null");
+      // Flush word buffer
+      if (self->partWordBufferIndex > 0) {
+        self->flushPartWordBuffer();
+      }
+      self->insideNoteref = true;
+      self->currentNoterefTextLen = 0;
+      self->currentNoterefText[0] = '\0';
+      self->depth += 1;
+      return;
+    }
+  }
+
   // Special handling for tables - show placeholder text instead of dropping silently
   if (strcmp(name, "table") == 0) {
     // Add placeholder text
     self->startNewTextBlock(TextBlock::CENTER_ALIGN);
-    if (self->currentTextBlock) {
-      self->currentTextBlock->addWord("[Table omitted]", EpdFontFamily::ITALIC);
-    }
 
-    // Skip table contents
+    self->italicUntilDepth = min(self->italicUntilDepth, self->depth);
-    self->skipUntilDepth = self->depth;
+    // Advance depth before processing character data (like you would for a element with text)
     self->depth += 1;
+    self->characterData(userData, "[Table omitted]", strlen("[Table omitted]"));
+
+    // Skip table contents (skip until parent as we pre-advanced depth above)
+    self->skipUntilDepth = self->depth - 1;
     return;
   }
 
   if (matches(name, IMAGE_TAGS, NUM_IMAGE_TAGS)) {
     // TODO: Start processing image tags
-    std::string alt;
+    std::string alt = "[Image]";
     if (atts != nullptr) {
       for (int i = 0; atts[i]; i += 2) {
         if (strcmp(atts[i], "alt") == 0) {
-          // add " " (counts as whitespace) at the end of alt
+          if (strlen(atts[i + 1]) > 0) {
-          //  so the corresponding text block ends.
+            alt = "[Image: " + std::string(atts[i + 1]) + "]";
-          // TODO: A zero-width breaking space would be more appropriate (once/if we support it)
+          }
-          alt = "[Image: " + std::string(atts[i + 1]) + "] ";
+          break;
         }
       }
-      Serial.printf("[%lu] [EHP] Image alt: %s\n", millis(), alt.c_str());
-
-      self->startNewTextBlock(TextBlock::CENTER_ALIGN);
-      self->italicUntilDepth = min(self->italicUntilDepth, self->depth);
-      self->depth += 1;
-      self->characterData(userData, alt.c_str(), alt.length());
-      return;
-    } else {
-      // Skip for now
-      self->skipUntilDepth = self->depth;
-      self->depth += 1;
-      return;
     }
+
+    Serial.printf("[%lu] [EHP] Image alt: %s\n", millis(), alt.c_str());
+
+    self->startNewTextBlock(TextBlock::CENTER_ALIGN);
+    self->italicUntilDepth = min(self->italicUntilDepth, self->depth);
+    // Advance depth before processing character data (like you would for a element with text)
+    self->depth += 1;
+    self->characterData(userData, alt.c_str(), alt.length());
+
+    // Skip table contents (skip until parent as we pre-advanced depth above)
+    self->skipUntilDepth = self->depth - 1;
+    return;
   }
 
   if (matches(name, SKIP_TAGS, NUM_SKIP_TAGS)) {
-    // start skip
     self->skipUntilDepth = self->depth;
     self->depth += 1;
     return;
@@ -143,46 +431,140 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
   if (matches(name, HEADER_TAGS, NUM_HEADER_TAGS)) {
     self->startNewTextBlock(TextBlock::CENTER_ALIGN);
     self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
-  } else if (matches(name, BLOCK_TAGS, NUM_BLOCK_TAGS)) {
+    self->depth += 1;
+    return;
+  }
+
+  if (matches(name, BLOCK_TAGS, NUM_BLOCK_TAGS)) {
     if (strcmp(name, "br") == 0) {
       if (self->partWordBufferIndex > 0) {
         // flush word preceding <br/> to currentTextBlock before calling startNewTextBlock
         self->flushPartWordBuffer();
       }
       self->startNewTextBlock(self->currentTextBlock->getStyle());
-    } else {
+      self->depth += 1;
-      self->startNewTextBlock((TextBlock::Style)self->paragraphAlignment);
+      return;
-      if (strcmp(name, "li") == 0) {
-        self->currentTextBlock->addWord("\xe2\x80\xa2", EpdFontFamily::REGULAR);
-      }
     }
-  } else if (matches(name, BOLD_TAGS, NUM_BOLD_TAGS)) {
+
-    self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
+    self->startNewTextBlock(static_cast<TextBlock::Style>(self->paragraphAlignment));
-  } else if (matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS)) {
+    if (strcmp(name, "li") == 0) {
-    self->italicUntilDepth = std::min(self->italicUntilDepth, self->depth);
+      self->currentTextBlock->addWord("\xe2\x80\xa2", EpdFontFamily::REGULAR);
+    }
+
+    self->depth += 1;
+    return;
   }
 
+  if (matches(name, BOLD_TAGS, NUM_BOLD_TAGS)) {
+    self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
+    self->depth += 1;
+    return;
+  }
+
+  if (matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS)) {
+    self->italicUntilDepth = std::min(self->italicUntilDepth, self->depth);
+    self->depth += 1;
+    return;
+  }
+
+  // Unprocessed tag, just increasing depth and continue forward
   self->depth += 1;
 }
 
 void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char* s, const int len) {
   auto* self = static_cast<ChapterHtmlSlimParser*>(userData);
 
-  // Middle of skip
+  // Collect paragraph note text in Pass 1
+  if (self->insideParagraphNote && self->isPass1CollectingAsides) {
+    for (int i = 0; i < len; i++) {
+      if (self->currentParagraphNoteTextLen >= self->MAX_PNOTE_BUFFER - 2) {
+        if (self->currentParagraphNoteTextLen == self->MAX_PNOTE_BUFFER - 2) {
+          Serial.printf("[%lu] [PNOTE] WARNING: Note text truncated at %d chars\n", millis(),
+                        self->MAX_PNOTE_BUFFER - 2);
+        }
+        break;
+      }
+
+      unsigned char c = (unsigned char)s[i];
+
+      if (isWhitespace(c)) {
+        if (self->currentParagraphNoteTextLen > 0 &&
+            self->currentParagraphNoteText[self->currentParagraphNoteTextLen - 1] != ' ') {
+          self->currentParagraphNoteText[self->currentParagraphNoteTextLen++] = ' ';
+        }
+      } else if (c >= 32 || c >= 0x80) {  // Accept printable ASCII AND UTF-8
+        self->currentParagraphNoteText[self->currentParagraphNoteTextLen++] = c;
+      }
+    }
+    self->currentParagraphNoteText[self->currentParagraphNoteTextLen] = '\0';
+    return;
+  }
+
+  // If inside aside, collect the text ONLY in pass 1
+  if (self->insideAsideFootnote) {
+    if (!self->isPass1CollectingAsides) {
+      return;
+    }
+
+    for (int i = 0; i < len; i++) {
+      if (self->currentAsideTextLen >= self->MAX_ASIDE_BUFFER - 2) {
+        if (self->currentAsideTextLen == self->MAX_ASIDE_BUFFER - 2) {
+          Serial.printf("[%lu] [ASIDE] WARNING: Footnote text truncated at %d chars (id=%s)\n", millis(),
+                        self->MAX_ASIDE_BUFFER - 2, self->currentAsideId);
+        }
+        break;
+      }
+
+      unsigned char c = (unsigned char)s[i];  // Cast to unsigned char
+
+      if (isWhitespace(c)) {
+        if (self->currentAsideTextLen > 0 && self->currentAsideText[self->currentAsideTextLen - 1] != ' ') {
+          self->currentAsideText[self->currentAsideTextLen++] = ' ';
+        }
+      } else if (c >= 32 || c >= 0x80) {  // Accept printable ASCII AND UTF-8 bytes
+        self->currentAsideText[self->currentAsideTextLen++] = c;
+      }
+      // Skip control characters (0x00-0x1F) except whitespace
+    }
+    self->currentAsideText[self->currentAsideTextLen] = '\0';
+    return;
+  }
+
+  // During pass 1, skip all other content
+  if (self->isPass1CollectingAsides) {
+    return;
+  }
+
+  // Rest of characterData logic for pass 2...
+  if (self->insideNoteref) {
+    for (int i = 0; i < len; i++) {
+      unsigned char c = (unsigned char)s[i];
+      // Skip whitespace and brackets []
+      if (!isWhitespace(c) && c != '[' && c != ']' && self->currentNoterefTextLen < 15) {
+        self->currentNoterefText[self->currentNoterefTextLen++] = c;
+        self->currentNoterefText[self->currentNoterefTextLen] = '\0';
+      }
+    }
+    return;
+  }
+
   if (self->skipUntilDepth < self->depth) {
     return;
   }
 
   for (int i = 0; i < len; i++) {
     if (isWhitespace(s[i])) {
-      // Currently looking at whitespace, if there's anything in the partWordBuffer, flush it
       if (self->partWordBufferIndex > 0) {
         self->flushPartWordBuffer();
       }
-      // Skip the whitespace char
       continue;
     }
 
+    // If we're about to run out of space, then cut the word off and start a new one
+    if (self->partWordBufferIndex >= MAX_WORD_SIZE) {
+      self->flushPartWordBuffer();
+    }
+
     // Skip Zero Width No-Break Space / BOM (U+FEFF) = 0xEF 0xBB 0xBF
     const XML_Char FEFF_BYTE_1 = static_cast<XML_Char>(0xEF);
     const XML_Char FEFF_BYTE_2 = static_cast<XML_Char>(0xBB);
@@ -196,8 +578,6 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
         continue;  // Move to the next iteration
       }
     }
-
-    // If we're about to run out of space, then cut the word off and start a new one
     if (self->partWordBufferIndex >= MAX_WORD_SIZE) {
       self->flushPartWordBuffer();
     }
@@ -220,14 +600,149 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
 void XMLCALL ChapterHtmlSlimParser::endElement(void* userData, const XML_Char* name) {
   auto* self = static_cast<ChapterHtmlSlimParser*>(userData);
 
+  // Closing paragraph note in Pass 1
+  if (strcmp(name, "p") == 0 && self->insideParagraphNote && self->depth - 1 == self->paragraphNoteDepth) {
+    if (self->isPass1CollectingAsides && self->currentParagraphNoteTextLen > 0 && self->paragraphNoteCount < 32 &&
+        self->currentParagraphNoteId[0] != '\0') {
+      // Copy ID
+      strncpy(self->paragraphNotes[self->paragraphNoteCount].id, self->currentParagraphNoteId, 15);
+      self->paragraphNotes[self->paragraphNoteCount].id[15] = '\0';
+
+      // Allocate memory for text
+      size_t textLen = strlen(self->currentParagraphNoteText);
+      self->paragraphNotes[self->paragraphNoteCount].text = static_cast<char*>(malloc(textLen + 1));
+
+      if (self->paragraphNotes[self->paragraphNoteCount].text) {
+        strcpy(self->paragraphNotes[self->paragraphNoteCount].text, self->currentParagraphNoteText);
+
+        Serial.printf("[%lu] [PNOTE] Stored: %s -> %.80s... (allocated %d bytes)\n", millis(),
+                      self->currentParagraphNoteId, self->currentParagraphNoteText, textLen + 1);
+
+        self->paragraphNoteCount++;
+      }
+    }
+
+    self->insideParagraphNote = false;
+    self->depth -= 1;
+    return;
+  }
+
+  // Closing aside - handle differently for Pass 1 vs Pass 2
+  if (strcmp(name, "aside") == 0 && self->insideAsideFootnote && self->depth - 1 == self->asideDepth) {
+    // Store footnote ONLY in Pass 1
+    if (self->isPass1CollectingAsides && self->currentAsideTextLen > 0 && self->inlineFootnoteCount < 16) {
+      // Copy ID (max 2 digits)
+      strncpy(self->inlineFootnotes[self->inlineFootnoteCount].id, self->currentAsideId, 2);
+      self->inlineFootnotes[self->inlineFootnoteCount].id[2] = '\0';
+
+      // DYNAMIC ALLOCATION: allocate exactly the needed size + 1
+      size_t textLen = strlen(self->currentAsideText);
+      self->inlineFootnotes[self->inlineFootnoteCount].text = static_cast<char*>(malloc(textLen + 1));
+
+      if (self->inlineFootnotes[self->inlineFootnoteCount].text) {
+        strcpy(self->inlineFootnotes[self->inlineFootnoteCount].text, self->currentAsideText);
+
+        Serial.printf("[%lu] [ASIDE] Stored: %s -> %.80s... (allocated %d bytes)\n", millis(), self->currentAsideId,
+                      self->currentAsideText, textLen + 1);
+
+        self->inlineFootnoteCount++;
+      } else {
+        Serial.printf("[%lu] [ASIDE] ERROR: Failed to allocate %d bytes for footnote %s\n", millis(), textLen + 1,
+                      self->currentAsideId);
+      }
+    }
+
+    // Reset state AFTER processing
+    self->insideAsideFootnote = false;
+    self->depth -= 1;
+    return;
+  }
+
+  // During pass 1, skip all other processing
+  if (self->isPass1CollectingAsides) {
+    self->depth -= 1;
+    return;
+  }
+
+  // ---------------------------------------------------------
+  // PASS 2: Normal Parsing Logic
+  // ---------------------------------------------------------
+
+  // [NEW] 1. Reset Superscript State
+  // We must ensure we know when we are leaving a <sup> tag
+  if (strcmp(name, "sup") == 0) {
+    if (self->supDepth == self->depth) {
+      self->supDepth = -1;
+    }
+  }
+
+  // [MODIFIED] 2. Handle 'a' tags (Anchors/Footnotes)
+  // We check "a" generally now, to handle both Noterefs AND resetting regular links
+  if (strcmp(name, "a") == 0) {
+    // Track if this was a noteref so we can return early later
+    bool wasNoteref = self->insideNoteref;
+
+    if (self->insideNoteref) {
+      self->insideNoteref = false;
+
+      if (self->currentNoterefTextLen > 0) {
+        Serial.printf("[%lu] [NOTEREF] %s -> %s\n", millis(), self->currentNoterefText, self->currentNoterefHref);
+
+        // Add footnote first (this does the rewriting)
+        self->addFootnoteToCurrentPage(self->currentNoterefText, self->currentNoterefHref);
+
+        // Then call callback with the REWRITTEN href from currentPageFootnotes
+        if (self->noterefCallback && self->currentPageFootnoteCount > 0) {
+          Noteref noteref;
+          strncpy(noteref.number, self->currentNoterefText, 15);
+          noteref.number[15] = '\0';
+
+          // Use the STORED href which has been rewritten
+          FootnoteEntry* lastFootnote = &self->currentPageFootnotes[self->currentPageFootnoteCount - 1];
+          strncpy(noteref.href, lastFootnote->href, 127);
+          noteref.href[127] = '\0';
+
+          self->noterefCallback(noteref);
+        }
+
+        // Ensure [1] appears inline after the word it references
+        EpdFontFamily::Style fontStyle = self->getCurrentFontStyle();
+
+        // Format the noteref text with brackets
+        char formattedNoteref[32];
+        snprintf(formattedNoteref, sizeof(formattedNoteref), "[%s]", self->currentNoterefText);
+
+        // Add it as a word to the current text block
+        if (self->currentTextBlock) {
+          self->currentTextBlock->addWord(formattedNoteref, fontStyle);
+        }
+      }
+
+      self->currentNoterefTextLen = 0;
+      self->currentNoterefText[0] = '\0';
+      self->currentNoterefHrefLen = 0;
+      // Note: We do NOT clear currentNoterefHref here yet, we do it below
+    }
+
+    // [NEW] Reset Anchor Depth
+    // This runs for BOTH footnotes and regular links to ensure state is clean
+    if (self->anchorDepth == self->depth) {
+      self->anchorDepth = -1;
+      self->currentNoterefHref[0] = '\0';
+    }
+
+    // If it was a noteref, we are done with this tag, return early
+    if (wasNoteref) {
+      self->depth -= 1;
+      return;
+    }
+  }
+
   if (self->partWordBufferIndex > 0) {
-    // Only flush out part word buffer if we're closing a block tag or are at the top of the HTML file.
-    // We don't want to flush out content when closing inline tags like <span>.
-    // Currently this also flushes out on closing <b> and <i> tags, but they are line tags so that shouldn't happen,
-    // text styling needs to be overhauled to fix it.
     const bool shouldBreakText =
         matches(name, BLOCK_TAGS, NUM_BLOCK_TAGS) || matches(name, HEADER_TAGS, NUM_HEADER_TAGS) ||
-        matches(name, BOLD_TAGS, NUM_BOLD_TAGS) || matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS) || self->depth == 1;
+        matches(name, BOLD_TAGS, NUM_BOLD_TAGS) || matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS) ||
+        strcmp(name, "table") == 0 || matches(name, IMAGE_TAGS, NUM_IMAGE_TAGS) || self->depth == 1;
 
     if (shouldBreakText) {
       self->flushPartWordBuffer();
@@ -236,56 +751,56 @@ void XMLCALL ChapterHtmlSlimParser::endElement(void* userData, const XML_Char* n
 
   self->depth -= 1;
 
-  // Leaving skip
   if (self->skipUntilDepth == self->depth) {
     self->skipUntilDepth = INT_MAX;
   }
 
-  // Leaving bold
   if (self->boldUntilDepth == self->depth) {
     self->boldUntilDepth = INT_MAX;
   }
 
-  // Leaving italic
   if (self->italicUntilDepth == self->depth) {
     self->italicUntilDepth = INT_MAX;
   }
 }
 
 bool ChapterHtmlSlimParser::parseAndBuildPages() {
-  startNewTextBlock((TextBlock::Style)this->paragraphAlignment);
+  // ============================================================================
+  // PASS 1: Extract all inline footnotes (aside elements) FIRST
+  // ============================================================================
+  Serial.printf("[%lu] [PARSER] === PASS 1: Extracting inline footnotes ===\n", millis());
 
-  const XML_Parser parser = XML_ParserCreate(nullptr);
+  // Reset state for pass 1
-  int done;
+  depth = 0;
+  skipUntilDepth = INT_MAX;
+  insideAsideFootnote = false;
+  insideParagraphNote = false;
+  inlineFootnoteCount = 0;
+  paragraphNoteCount = 0;
+  isPass1CollectingAsides = true;
 
-  if (!parser) {
+  XML_Parser parser1 = XML_ParserCreate(nullptr);
+  if (!parser1) {
     Serial.printf("[%lu] [EHP] Couldn't allocate memory for parser\n", millis());
     return false;
   }
 
+  XML_SetUserData(parser1, this);
+  XML_SetElementHandler(parser1, startElement, endElement);
+  XML_SetCharacterDataHandler(parser1, characterData);
+
   FsFile file;
   if (!SdMan.openFileForRead("EHP", filepath, file)) {
-    XML_ParserFree(parser);
+    XML_ParserFree(parser1);
     return false;
   }
 
-  // Get file size for progress calculation
+  bool done = false;
-  const size_t totalSize = file.size();
-  size_t bytesRead = 0;
-  int lastProgress = -1;
-
-  XML_SetUserData(parser, this);
-  XML_SetElementHandler(parser, startElement, endElement);
-  XML_SetCharacterDataHandler(parser, characterData);
-
   do {
-    void* const buf = XML_GetBuffer(parser, 1024);
+    void* const buf = XML_GetBuffer(parser1, 1024);
     if (!buf) {
       Serial.printf("[%lu] [EHP] Couldn't allocate memory for buffer\n", millis());
-      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_ParserFree(parser1);
-      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
-      XML_SetCharacterDataHandler(parser, nullptr);
-      XML_ParserFree(parser);
       file.close();
       return false;
     }
@@ -294,10 +809,88 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
 
     if (len == 0 && file.available() > 0) {
       Serial.printf("[%lu] [EHP] File read error\n", millis());
-      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_ParserFree(parser1);
-      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      file.close();
-      XML_SetCharacterDataHandler(parser, nullptr);
+      return false;
-      XML_ParserFree(parser);
+    }
+
+    done = file.available() == 0;
+
+    if (XML_ParseBuffer(parser1, static_cast<int>(len), done) == XML_STATUS_ERROR) {
+      Serial.printf("[%lu] [EHP] Parse error at line %lu:\n%s\n", millis(), XML_GetCurrentLineNumber(parser1),
+                    XML_ErrorString(XML_GetErrorCode(parser1)));
+      XML_ParserFree(parser1);
+      file.close();
+      return false;
+    }
+  } while (!done);
+
+  XML_ParserFree(parser1);
+  file.close();
+
+  Serial.printf("[%lu] [PARSER] Pass 1 complete: found %d inline footnotes\n", millis(), inlineFootnoteCount);
+  for (int i = 0; i < inlineFootnoteCount; i++) {
+    Serial.printf("[%lu] [PARSER]   - %s: %.80s\n", millis(), inlineFootnotes[i].id, inlineFootnotes[i].text);
+  }
+
+  // ============================================================================
+  // PASS 2: Build pages with inline footnotes already available
+  // ============================================================================
+  Serial.printf("[%lu] [PARSER] === PASS 2: Building pages ===\n", millis());
+
+  // Reset parser state for pass 2
+  depth = 0;
+  skipUntilDepth = INT_MAX;
+  boldUntilDepth = INT_MAX;
+  italicUntilDepth = INT_MAX;
+  partWordBufferIndex = 0;
+  insideNoteref = false;
+  insideAsideFootnote = false;
+  currentPageFootnoteCount = 0;
+  isPass1CollectingAsides = false;
+
+  supDepth = -1;
+  anchorDepth = -1;
+
+  startNewTextBlock((TextBlock::Style)this->paragraphAlignment);
+
+  const XML_Parser parser2 = XML_ParserCreate(nullptr);
+  if (!parser2) {
+    Serial.printf("[%lu] [EHP] Couldn't allocate memory for parser\n", millis());
+    return false;
+  }
+
+  XML_SetUserData(parser2, this);
+  XML_SetElementHandler(parser2, startElement, endElement);
+  XML_SetCharacterDataHandler(parser2, characterData);
+
+  if (!SdMan.openFileForRead("EHP", filepath, file)) {
+    XML_ParserFree(parser2);
+    return false;
+  }
+
+  // Get file size for progress calculation
+  const size_t totalSize = file.size();
+  size_t bytesRead = 0;
+  int lastProgress = -1;
+
+  do {
+    void* const buf = XML_GetBuffer(parser2, 1024);
+    if (!buf) {
+      Serial.printf("[%lu] [EHP] Couldn't allocate memory for buffer\n", millis());
+      XML_ParserFree(parser2);
+      file.close();
+      return false;
+    }
+
+    const size_t len = file.read(buf, 1024);
+
+    if (len == 0 && file.available() > 0) {
+      Serial.printf("[%lu] [EHP] File read error\n", millis());
+      XML_StopParser(parser2, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser2, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser2, nullptr);
+      XML_ParserFree(parser2);
       file.close();
       return false;
     }
@@ -315,28 +908,33 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
 
     done = file.available() == 0;
 
-    if (XML_ParseBuffer(parser, static_cast<int>(len), done) == XML_STATUS_ERROR) {
+    if (XML_ParseBuffer(parser2, static_cast<int>(len), done) == XML_STATUS_ERROR) {
-      Serial.printf("[%lu] [EHP] Parse error at line %lu:\n%s\n", millis(), XML_GetCurrentLineNumber(parser),
+      Serial.printf("[%lu] [EHP] Parse error at line %lu:\n%s\n", millis(), XML_GetCurrentLineNumber(parser2),
-                    XML_ErrorString(XML_GetErrorCode(parser)));
+                    XML_ErrorString(XML_GetErrorCode(parser2)));
-      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_StopParser(parser2, XML_FALSE);                // Stop any pending processing
-      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetElementHandler(parser2, nullptr, nullptr);  // Clear callbacks
-      XML_SetCharacterDataHandler(parser, nullptr);
+      XML_SetCharacterDataHandler(parser2, nullptr);
-      XML_ParserFree(parser);
+      XML_ParserFree(parser2);
       file.close();
       return false;
     }
   } while (!done);
 
-  XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+  XML_ParserFree(parser2);
-  XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
-  XML_SetCharacterDataHandler(parser, nullptr);
-  XML_ParserFree(parser);
   file.close();
 
   // Process last page if there is still text
   if (currentTextBlock) {
     makePages();
-    completePageFn(std::move(currentPage));
+
+    if (currentPage) {
+      for (int i = 0; i < currentPageFootnoteCount; i++) {
+        currentPage->addFootnote(currentPageFootnotes[i].number, currentPageFootnotes[i].href);
+      }
+      currentPageFootnoteCount = 0;
+      completePageFn(std::move(currentPage));
+    }
+
     currentPage.reset();
     currentTextBlock.reset();
   }
@@ -348,13 +946,24 @@ void ChapterHtmlSlimParser::addLineToPage(std::shared_ptr<TextBlock> line) {
   const int lineHeight = renderer.getLineHeight(fontId) * lineCompression;
 
   if (currentPageNextY + lineHeight > viewportHeight) {
+    if (currentPage) {
+      for (int i = 0; i < currentPageFootnoteCount; i++) {
+        currentPage->addFootnote(currentPageFootnotes[i].number, currentPageFootnotes[i].href);
+      }
+      currentPageFootnoteCount = 0;
+    }
+
     completePageFn(std::move(currentPage));
     currentPage.reset(new Page());
     currentPageNextY = 0;
   }
 
-  currentPage->elements.push_back(std::make_shared<PageLine>(line, 0, currentPageNextY));
+  if (currentPage && currentPage->elements.size() < 24) {  // Assuming generic capacity check or vector size
-  currentPageNextY += lineHeight;
+    currentPage->elements.push_back(std::make_shared<PageLine>(line, 0, currentPageNextY));
+    currentPageNextY += lineHeight;
+  } else if (currentPage) {
+    Serial.printf("[%lu] [EHP] WARNING: Page element capacity reached, skipping element\n", millis());
+  }
 }
 
 void ChapterHtmlSlimParser::makePages() {

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h

@@ -3,9 +3,11 @@
 #include <expat.h>
 
 #include <climits>
+#include <cstring>
 #include <functional>
 #include <memory>
 
+#include "../FootnoteEntry.h"
 #include "../ParsedText.h"
 #include "../blocks/TextBlock.h"
 
@@ -14,6 +16,37 @@ class GfxRenderer;
 
 #define MAX_WORD_SIZE 200
 
+struct Noteref {
+  char number[16];
+  char href[128];
+};
+
+// Struct to store collected inline footnotes (aside elements)
+struct InlineFootnote {
+  char id[3];
+  char* text;
+
+  InlineFootnote() : text(nullptr) { id[0] = '\0'; }
+};
+
+// Struct to store collected inline footnotes from <p class="note">
+struct ParagraphNote {
+  char id[16];  // ID from <a id="rnote1">
+  char* text;   // Pointer to dynamically allocated text
+
+  ParagraphNote() : text(nullptr) { id[0] = '\0'; }
+
+  ~ParagraphNote() {
+    if (text) {
+      free(text);
+      text = nullptr;
+    }
+  }
+
+  ParagraphNote(const ParagraphNote&) = delete;
+  ParagraphNote& operator=(const ParagraphNote&) = delete;
+};
+
 class ChapterHtmlSlimParser {
   const std::string& filepath;
   GfxRenderer& renderer;
@@ -23,8 +56,6 @@ class ChapterHtmlSlimParser {
   int skipUntilDepth = INT_MAX;
   int boldUntilDepth = INT_MAX;
   int italicUntilDepth = INT_MAX;
-  // buffer for building up words from characters, will auto break if longer than this
-  // leave one char at end for null pointer
   char partWordBuffer[MAX_WORD_SIZE + 1] = {};
   int partWordBufferIndex = 0;
   std::unique_ptr<ParsedText> currentTextBlock = nullptr;
@@ -38,15 +69,62 @@ class ChapterHtmlSlimParser {
   uint16_t viewportHeight;
   bool hyphenationEnabled;
 
+  // Noteref tracking
+  bool insideNoteref = false;
+  char currentNoterefText[16] = {0};
+  int currentNoterefTextLen = 0;
+  char currentNoterefHref[128] = {0};
+  int currentNoterefHrefLen = 0;
+  std::function<void(Noteref&)> noterefCallback = nullptr;
+
+  // Footnote tracking for current page
+  FootnoteEntry currentPageFootnotes[16];
+  int currentPageFootnoteCount = 0;
+
+  // Inline footnotes (aside) tracking
+  bool insideAsideFootnote = false;
+  int asideDepth = 0;
+  char currentAsideId[3] = {0};
+
+  // Paragraph note tracking
+  bool insideParagraphNote = false;
+  int paragraphNoteDepth = 0;
+  char currentParagraphNoteId[16] = {0};
+  static constexpr int MAX_PNOTE_BUFFER = 256;
+  char currentParagraphNoteText[MAX_PNOTE_BUFFER] = {0};
+  int currentParagraphNoteTextLen = 0;
+
+  // Temporary buffer for accumulation, will be copied to dynamic allocation
+  static constexpr int MAX_ASIDE_BUFFER = 1024;
+  char currentAsideText[MAX_ASIDE_BUFFER] = {0};
+  int currentAsideTextLen = 0;
+
+  // Flag to indicate we're in Pass 1 (collecting asides only)
+  bool isPass1CollectingAsides = false;
+
+  // Track superscript depth
+  int supDepth = -1;
+  int anchorDepth = -1;
+
+  void addFootnoteToCurrentPage(const char* number, const char* href);
   void startNewTextBlock(TextBlock::Style style);
+  EpdFontFamily::Style getCurrentFontStyle() const;
   void flushPartWordBuffer();
   void makePages();
+
   // XML callbacks
   static void XMLCALL startElement(void* userData, const XML_Char* name, const XML_Char** atts);
   static void XMLCALL characterData(void* userData, const XML_Char* s, int len);
   static void XMLCALL endElement(void* userData, const XML_Char* name);
 
  public:
+  // inline footnotes
+  InlineFootnote inlineFootnotes[16];
+  int inlineFootnoteCount = 0;
+  // paragraph notes
+  ParagraphNote paragraphNotes[16];
+  int paragraphNoteCount = 0;
+
   explicit ChapterHtmlSlimParser(const std::string& filepath, GfxRenderer& renderer, const int fontId,
                                  const float lineCompression, const bool extraParagraphSpacing,
                                  const uint8_t paragraphAlignment, const uint16_t viewportWidth,
@@ -55,6 +133,7 @@ class ChapterHtmlSlimParser {
                                  const std::function<void(int)>& progressFn = nullptr)
       : filepath(filepath),
         renderer(renderer),
+        completePageFn(completePageFn),
         fontId(fontId),
         lineCompression(lineCompression),
         extraParagraphSpacing(extraParagraphSpacing),
@@ -62,9 +141,27 @@ class ChapterHtmlSlimParser {
         viewportWidth(viewportWidth),
         viewportHeight(viewportHeight),
         hyphenationEnabled(hyphenationEnabled),
-        completePageFn(completePageFn),
+        progressFn(progressFn),
-        progressFn(progressFn) {}
+        inlineFootnoteCount(0) {
-  ~ChapterHtmlSlimParser() = default;
+    // Initialize all footnote pointers to null
+    for (int i = 0; i < 16; i++) {
+      inlineFootnotes[i].text = nullptr;
+      inlineFootnotes[i].id[0] = '\0';
+    }
+  }
+
+  ~ChapterHtmlSlimParser() {
+    // Manual cleanup of inline footnotes
+    for (int i = 0; i < inlineFootnoteCount; i++) {
+      if (inlineFootnotes[i].text) {
+        free(inlineFootnotes[i].text);
+        inlineFootnotes[i].text = nullptr;
+      }
+    }
+  }
+
   bool parseAndBuildPages();
   void addLineToPage(std::shared_ptr<TextBlock> line);
+
+  void setNoterefCallback(const std::function<void(Noteref&)>& callback) { noterefCallback = callback; }
 };

lib/GfxRenderer/GfxRenderer.cpp

@@ -10,19 +10,19 @@ void GfxRenderer::rotateCoordinates(const int x, const int y, int* rotatedX, int
       // Logical portrait (480x800) → panel (800x480)
       // Rotation: 90 degrees clockwise
       *rotatedX = y;
-      *rotatedY = EInkDisplay::DISPLAY_HEIGHT - 1 - x;
+      *rotatedY = HalDisplay::DISPLAY_HEIGHT - 1 - x;
       break;
     }
     case LandscapeClockwise: {
       // Logical landscape (800x480) rotated 180 degrees (swap top/bottom and left/right)
-      *rotatedX = EInkDisplay::DISPLAY_WIDTH - 1 - x;
+      *rotatedX = HalDisplay::DISPLAY_WIDTH - 1 - x;
-      *rotatedY = EInkDisplay::DISPLAY_HEIGHT - 1 - y;
+      *rotatedY = HalDisplay::DISPLAY_HEIGHT - 1 - y;
       break;
     }
     case PortraitInverted: {
       // Logical portrait (480x800) → panel (800x480)
       // Rotation: 90 degrees counter-clockwise
-      *rotatedX = EInkDisplay::DISPLAY_WIDTH - 1 - y;
+      *rotatedX = HalDisplay::DISPLAY_WIDTH - 1 - y;
       *rotatedY = x;
       break;
     }
@@ -36,7 +36,7 @@ void GfxRenderer::rotateCoordinates(const int x, const int y, int* rotatedX, int
 }
 
 void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
-  uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  uint8_t* frameBuffer = display.getFrameBuffer();
 
   // Early return if no framebuffer is set
   if (!frameBuffer) {
@@ -49,14 +49,13 @@ void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
   rotateCoordinates(x, y, &rotatedX, &rotatedY);
 
   // Bounds checking against physical panel dimensions
-  if (rotatedX < 0 || rotatedX >= EInkDisplay::DISPLAY_WIDTH || rotatedY < 0 ||
+  if (rotatedX < 0 || rotatedX >= HalDisplay::DISPLAY_WIDTH || rotatedY < 0 || rotatedY >= HalDisplay::DISPLAY_HEIGHT) {
-      rotatedY >= EInkDisplay::DISPLAY_HEIGHT) {
     Serial.printf("[%lu] [GFX] !! Outside range (%d, %d) -> (%d, %d)\n", millis(), x, y, rotatedX, rotatedY);
     return;
   }
 
   // Calculate byte position and bit position
-  const uint16_t byteIndex = rotatedY * EInkDisplay::DISPLAY_WIDTH_BYTES + (rotatedX / 8);
+  const uint16_t byteIndex = rotatedY * HalDisplay::DISPLAY_WIDTH_BYTES + (rotatedX / 8);
   const uint8_t bitPosition = 7 - (rotatedX % 8);  // MSB first
 
   if (state) {
@@ -164,7 +163,7 @@ void GfxRenderer::drawImage(const uint8_t bitmap[], const int x, const int y, co
       break;
   }
   // TODO: Rotate bits
-  einkDisplay.drawImage(bitmap, rotatedX, rotatedY, width, height);
+  display.drawImage(bitmap, rotatedX, rotatedY, width, height);
 }
 
 void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, const int maxWidth, const int maxHeight,
@@ -399,22 +398,20 @@ void GfxRenderer::fillPolygon(const int* xPoints, const int* yPoints, int numPoi
   free(nodeX);
 }
 
-void GfxRenderer::clearScreen(const uint8_t color) const { einkDisplay.clearScreen(color); }
+void GfxRenderer::clearScreen(const uint8_t color) const { display.clearScreen(color); }
 
 void GfxRenderer::invertScreen() const {
-  uint8_t* buffer = einkDisplay.getFrameBuffer();
+  uint8_t* buffer = display.getFrameBuffer();
   if (!buffer) {
     Serial.printf("[%lu] [GFX] !! No framebuffer in invertScreen\n", millis());
     return;
   }
-  for (int i = 0; i < EInkDisplay::BUFFER_SIZE; i++) {
+  for (int i = 0; i < HalDisplay::BUFFER_SIZE; i++) {
     buffer[i] = ~buffer[i];
   }
 }
 
-void GfxRenderer::displayBuffer(const EInkDisplay::RefreshMode refreshMode) const {
+void GfxRenderer::displayBuffer(const HalDisplay::RefreshMode refreshMode) const { display.displayBuffer(refreshMode); }
-  einkDisplay.displayBuffer(refreshMode);
-}
 
 std::string GfxRenderer::truncatedText(const int fontId, const char* text, const int maxWidth,
                                        const EpdFontFamily::Style style) const {
@@ -433,13 +430,13 @@ int GfxRenderer::getScreenWidth() const {
     case Portrait:
     case PortraitInverted:
       // 480px wide in portrait logical coordinates
-      return EInkDisplay::DISPLAY_HEIGHT;
+      return HalDisplay::DISPLAY_HEIGHT;
     case LandscapeClockwise:
     case LandscapeCounterClockwise:
       // 800px wide in landscape logical coordinates
-      return EInkDisplay::DISPLAY_WIDTH;
+      return HalDisplay::DISPLAY_WIDTH;
   }
-  return EInkDisplay::DISPLAY_HEIGHT;
+  return HalDisplay::DISPLAY_HEIGHT;
 }
 
 int GfxRenderer::getScreenHeight() const {
@@ -447,13 +444,13 @@ int GfxRenderer::getScreenHeight() const {
     case Portrait:
     case PortraitInverted:
       // 800px tall in portrait logical coordinates
-      return EInkDisplay::DISPLAY_WIDTH;
+      return HalDisplay::DISPLAY_WIDTH;
     case LandscapeClockwise:
     case LandscapeCounterClockwise:
       // 480px tall in landscape logical coordinates
-      return EInkDisplay::DISPLAY_HEIGHT;
+      return HalDisplay::DISPLAY_HEIGHT;
   }
-  return EInkDisplay::DISPLAY_WIDTH;
+  return HalDisplay::DISPLAY_WIDTH;
 }
 
 int GfxRenderer::getSpaceWidth(const int fontId) const {
@@ -653,17 +650,18 @@ void GfxRenderer::drawTextRotated90CW(const int fontId, const int x, const int y
   }
 }
 
-uint8_t* GfxRenderer::getFrameBuffer() const { return einkDisplay.getFrameBuffer(); }
+uint8_t* GfxRenderer::getFrameBuffer() const { return display.getFrameBuffer(); }
 
-size_t GfxRenderer::getBufferSize() { return EInkDisplay::BUFFER_SIZE; }
+size_t GfxRenderer::getBufferSize() { return HalDisplay::BUFFER_SIZE; }
 
-void GfxRenderer::grayscaleRevert() const { einkDisplay.grayscaleRevert(); }
+// unused
+// void GfxRenderer::grayscaleRevert() const { display.grayscaleRevert(); }
 
-void GfxRenderer::copyGrayscaleLsbBuffers() const { einkDisplay.copyGrayscaleLsbBuffers(einkDisplay.getFrameBuffer()); }
+void GfxRenderer::copyGrayscaleLsbBuffers() const { display.copyGrayscaleLsbBuffers(display.getFrameBuffer()); }
 
-void GfxRenderer::copyGrayscaleMsbBuffers() const { einkDisplay.copyGrayscaleMsbBuffers(einkDisplay.getFrameBuffer()); }
+void GfxRenderer::copyGrayscaleMsbBuffers() const { display.copyGrayscaleMsbBuffers(display.getFrameBuffer()); }
 
-void GfxRenderer::displayGrayBuffer() const { einkDisplay.displayGrayBuffer(); }
+void GfxRenderer::displayGrayBuffer() const { display.displayGrayBuffer(); }
 
 void GfxRenderer::freeBwBufferChunks() {
   for (auto& bwBufferChunk : bwBufferChunks) {
@@ -681,7 +679,7 @@ void GfxRenderer::freeBwBufferChunks() {
  * Returns true if buffer was stored successfully, false if allocation failed.
  */
 bool GfxRenderer::storeBwBuffer() {
-  const uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  const uint8_t* frameBuffer = display.getFrameBuffer();
   if (!frameBuffer) {
     Serial.printf("[%lu] [GFX] !! No framebuffer in storeBwBuffer\n", millis());
     return false;
@@ -736,7 +734,7 @@ void GfxRenderer::restoreBwBuffer() {
     return;
   }
 
-  uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  uint8_t* frameBuffer = display.getFrameBuffer();
   if (!frameBuffer) {
     Serial.printf("[%lu] [GFX] !! No framebuffer in restoreBwBuffer\n", millis());
     freeBwBufferChunks();
@@ -755,7 +753,7 @@ void GfxRenderer::restoreBwBuffer() {
     memcpy(frameBuffer + offset, bwBufferChunks[i], BW_BUFFER_CHUNK_SIZE);
   }
 
-  einkDisplay.cleanupGrayscaleBuffers(frameBuffer);
+  display.cleanupGrayscaleBuffers(frameBuffer);
 
   freeBwBufferChunks();
   Serial.printf("[%lu] [GFX] Restored and freed BW buffer chunks\n", millis());
@@ -766,9 +764,9 @@ void GfxRenderer::restoreBwBuffer() {
  * Use this when BW buffer was re-rendered instead of stored/restored.
  */
 void GfxRenderer::cleanupGrayscaleWithFrameBuffer() const {
-  uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  uint8_t* frameBuffer = display.getFrameBuffer();
   if (frameBuffer) {
-    einkDisplay.cleanupGrayscaleBuffers(frameBuffer);
+    display.cleanupGrayscaleBuffers(frameBuffer);
   }
 }
 

lib/GfxRenderer/GfxRenderer.h

@@ -1,7 +1,7 @@
 #pragma once
 
-#include <EInkDisplay.h>
 #include <EpdFontFamily.h>
+#include <HalDisplay.h>
 
 #include <map>
 
@@ -21,11 +21,11 @@ class GfxRenderer {
 
  private:
   static constexpr size_t BW_BUFFER_CHUNK_SIZE = 8000;  // 8KB chunks to allow for non-contiguous memory
-  static constexpr size_t BW_BUFFER_NUM_CHUNKS = EInkDisplay::BUFFER_SIZE / BW_BUFFER_CHUNK_SIZE;
+  static constexpr size_t BW_BUFFER_NUM_CHUNKS = HalDisplay::BUFFER_SIZE / BW_BUFFER_CHUNK_SIZE;
-  static_assert(BW_BUFFER_CHUNK_SIZE * BW_BUFFER_NUM_CHUNKS == EInkDisplay::BUFFER_SIZE,
+  static_assert(BW_BUFFER_CHUNK_SIZE * BW_BUFFER_NUM_CHUNKS == HalDisplay::BUFFER_SIZE,
                 "BW buffer chunking does not line up with display buffer size");
 
-  EInkDisplay& einkDisplay;
+  HalDisplay& display;
   RenderMode renderMode;
   Orientation orientation;
   uint8_t* bwBufferChunks[BW_BUFFER_NUM_CHUNKS] = {nullptr};
@@ -36,7 +36,7 @@ class GfxRenderer {
   void rotateCoordinates(int x, int y, int* rotatedX, int* rotatedY) const;
 
  public:
-  explicit GfxRenderer(EInkDisplay& einkDisplay) : einkDisplay(einkDisplay), renderMode(BW), orientation(Portrait) {}
+  explicit GfxRenderer(HalDisplay& halDisplay) : display(halDisplay), renderMode(BW), orientation(Portrait) {}
   ~GfxRenderer() { freeBwBufferChunks(); }
 
   static constexpr int VIEWABLE_MARGIN_TOP = 9;
@@ -54,7 +54,7 @@ class GfxRenderer {
   // Screen ops
   int getScreenWidth() const;
   int getScreenHeight() const;
-  void displayBuffer(EInkDisplay::RefreshMode refreshMode = EInkDisplay::FAST_REFRESH) const;
+  void displayBuffer(HalDisplay::RefreshMode refreshMode = HalDisplay::FAST_REFRESH) const;
   // EXPERIMENTAL: Windowed update - display only a rectangular region
   void displayWindow(int x, int y, int width, int height) const;
   void invertScreen() const;

lib/hal/HalDisplay.cpp

@@ -0,0 +1,51 @@
+#include <HalDisplay.h>
+#include <HalGPIO.h>
+
+#define SD_SPI_MISO 7
+
+HalDisplay::HalDisplay() : einkDisplay(EPD_SCLK, EPD_MOSI, EPD_CS, EPD_DC, EPD_RST, EPD_BUSY) {}
+
+HalDisplay::~HalDisplay() {}
+
+void HalDisplay::begin() { einkDisplay.begin(); }
+
+void HalDisplay::clearScreen(uint8_t color) const { einkDisplay.clearScreen(color); }
+
+void HalDisplay::drawImage(const uint8_t* imageData, uint16_t x, uint16_t y, uint16_t w, uint16_t h,
+                           bool fromProgmem) const {
+  einkDisplay.drawImage(imageData, x, y, w, h, fromProgmem);
+}
+
+EInkDisplay::RefreshMode convertRefreshMode(HalDisplay::RefreshMode mode) {
+  switch (mode) {
+    case HalDisplay::FULL_REFRESH:
+      return EInkDisplay::FULL_REFRESH;
+    case HalDisplay::HALF_REFRESH:
+      return EInkDisplay::HALF_REFRESH;
+    case HalDisplay::FAST_REFRESH:
+    default:
+      return EInkDisplay::FAST_REFRESH;
+  }
+}
+
+void HalDisplay::displayBuffer(HalDisplay::RefreshMode mode) { einkDisplay.displayBuffer(convertRefreshMode(mode)); }
+
+void HalDisplay::refreshDisplay(HalDisplay::RefreshMode mode, bool turnOffScreen) {
+  einkDisplay.refreshDisplay(convertRefreshMode(mode), turnOffScreen);
+}
+
+void HalDisplay::deepSleep() { einkDisplay.deepSleep(); }
+
+uint8_t* HalDisplay::getFrameBuffer() const { return einkDisplay.getFrameBuffer(); }
+
+void HalDisplay::copyGrayscaleBuffers(const uint8_t* lsbBuffer, const uint8_t* msbBuffer) {
+  einkDisplay.copyGrayscaleBuffers(lsbBuffer, msbBuffer);
+}
+
+void HalDisplay::copyGrayscaleLsbBuffers(const uint8_t* lsbBuffer) { einkDisplay.copyGrayscaleLsbBuffers(lsbBuffer); }
+
+void HalDisplay::copyGrayscaleMsbBuffers(const uint8_t* msbBuffer) { einkDisplay.copyGrayscaleMsbBuffers(msbBuffer); }
+
+void HalDisplay::cleanupGrayscaleBuffers(const uint8_t* bwBuffer) { einkDisplay.cleanupGrayscaleBuffers(bwBuffer); }
+
+void HalDisplay::displayGrayBuffer() { einkDisplay.displayGrayBuffer(); }

lib/hal/HalDisplay.h

@@ -0,0 +1,52 @@
+#pragma once
+#include <Arduino.h>
+#include <EInkDisplay.h>
+
+class HalDisplay {
+ public:
+  // Constructor with pin configuration
+  HalDisplay();
+
+  // Destructor
+  ~HalDisplay();
+
+  // Refresh modes
+  enum RefreshMode {
+    FULL_REFRESH,  // Full refresh with complete waveform
+    HALF_REFRESH,  // Half refresh (1720ms) - balanced quality and speed
+    FAST_REFRESH   // Fast refresh using custom LUT
+  };
+
+  // Initialize the display hardware and driver
+  void begin();
+
+  // Display dimensions
+  static constexpr uint16_t DISPLAY_WIDTH = EInkDisplay::DISPLAY_WIDTH;
+  static constexpr uint16_t DISPLAY_HEIGHT = EInkDisplay::DISPLAY_HEIGHT;
+  static constexpr uint16_t DISPLAY_WIDTH_BYTES = DISPLAY_WIDTH / 8;
+  static constexpr uint32_t BUFFER_SIZE = DISPLAY_WIDTH_BYTES * DISPLAY_HEIGHT;
+
+  // Frame buffer operations
+  void clearScreen(uint8_t color = 0xFF) const;
+  void drawImage(const uint8_t* imageData, uint16_t x, uint16_t y, uint16_t w, uint16_t h,
+                 bool fromProgmem = false) const;
+
+  void displayBuffer(RefreshMode mode = RefreshMode::FAST_REFRESH);
+  void refreshDisplay(RefreshMode mode = RefreshMode::FAST_REFRESH, bool turnOffScreen = false);
+
+  // Power management
+  void deepSleep();
+
+  // Access to frame buffer
+  uint8_t* getFrameBuffer() const;
+
+  void copyGrayscaleBuffers(const uint8_t* lsbBuffer, const uint8_t* msbBuffer);
+  void copyGrayscaleLsbBuffers(const uint8_t* lsbBuffer);
+  void copyGrayscaleMsbBuffers(const uint8_t* msbBuffer);
+  void cleanupGrayscaleBuffers(const uint8_t* bwBuffer);
+
+  void displayGrayBuffer();
+
+ private:
+  EInkDisplay einkDisplay;
+};

lib/hal/HalGPIO.cpp

@@ -0,0 +1,55 @@
+#include <HalGPIO.h>
+#include <SPI.h>
+#include <esp_sleep.h>
+
+void HalGPIO::begin() {
+  inputMgr.begin();
+  SPI.begin(EPD_SCLK, SPI_MISO, EPD_MOSI, EPD_CS);
+  pinMode(BAT_GPIO0, INPUT);
+  pinMode(UART0_RXD, INPUT);
+}
+
+void HalGPIO::update() { inputMgr.update(); }
+
+bool HalGPIO::isPressed(uint8_t buttonIndex) const { return inputMgr.isPressed(buttonIndex); }
+
+bool HalGPIO::wasPressed(uint8_t buttonIndex) const { return inputMgr.wasPressed(buttonIndex); }
+
+bool HalGPIO::wasAnyPressed() const { return inputMgr.wasAnyPressed(); }
+
+bool HalGPIO::wasReleased(uint8_t buttonIndex) const { return inputMgr.wasReleased(buttonIndex); }
+
+bool HalGPIO::wasAnyReleased() const { return inputMgr.wasAnyReleased(); }
+
+unsigned long HalGPIO::getHeldTime() const { return inputMgr.getHeldTime(); }
+
+void HalGPIO::startDeepSleep() {
+  esp_deep_sleep_enable_gpio_wakeup(1ULL << InputManager::POWER_BUTTON_PIN, ESP_GPIO_WAKEUP_GPIO_LOW);
+  // Ensure that the power button has been released to avoid immediately turning back on if you're holding it
+  while (inputMgr.isPressed(BTN_POWER)) {
+    delay(50);
+    inputMgr.update();
+  }
+  // Enter Deep Sleep
+  esp_deep_sleep_start();
+}
+
+int HalGPIO::getBatteryPercentage() const {
+  static const BatteryMonitor battery = BatteryMonitor(BAT_GPIO0);
+  return battery.readPercentage();
+}
+
+bool HalGPIO::isUsbConnected() const {
+  // U0RXD/GPIO20 reads HIGH when USB is connected
+  return digitalRead(UART0_RXD) == HIGH;
+}
+
+bool HalGPIO::isWakeupByPowerButton() const {
+  const auto wakeupCause = esp_sleep_get_wakeup_cause();
+  const auto resetReason = esp_reset_reason();
+  if (isUsbConnected()) {
+    return wakeupCause == ESP_SLEEP_WAKEUP_GPIO;
+  } else {
+    return (wakeupCause == ESP_SLEEP_WAKEUP_UNDEFINED) && (resetReason == ESP_RST_POWERON);
+  }
+}

lib/hal/HalGPIO.h

@@ -0,0 +1,61 @@
+#pragma once
+
+#include <Arduino.h>
+#include <BatteryMonitor.h>
+#include <InputManager.h>
+
+// Display SPI pins (custom pins for XteinkX4, not hardware SPI defaults)
+#define EPD_SCLK 8   // SPI Clock
+#define EPD_MOSI 10  // SPI MOSI (Master Out Slave In)
+#define EPD_CS 21    // Chip Select
+#define EPD_DC 4     // Data/Command
+#define EPD_RST 5    // Reset
+#define EPD_BUSY 6   // Busy
+
+#define SPI_MISO 7  // SPI MISO, shared between SD card and display (Master In Slave Out)
+
+#define BAT_GPIO0 0  // Battery voltage
+
+#define UART0_RXD 20  // Used for USB connection detection
+
+class HalGPIO {
+#if CROSSPOINT_EMULATED == 0
+  InputManager inputMgr;
+#endif
+
+ public:
+  HalGPIO() = default;
+
+  // Start button GPIO and setup SPI for screen and SD card
+  void begin();
+
+  // Button input methods
+  void update();
+  bool isPressed(uint8_t buttonIndex) const;
+  bool wasPressed(uint8_t buttonIndex) const;
+  bool wasAnyPressed() const;
+  bool wasReleased(uint8_t buttonIndex) const;
+  bool wasAnyReleased() const;
+  unsigned long getHeldTime() const;
+
+  // Setup wake up GPIO and enter deep sleep
+  void startDeepSleep();
+
+  // Get battery percentage (range 0-100)
+  int getBatteryPercentage() const;
+
+  // Check if USB is connected
+  bool isUsbConnected() const;
+
+  // Check if wakeup was caused by power button press
+  bool isWakeupByPowerButton() const;
+
+  // Button indices
+  static constexpr uint8_t BTN_BACK = 0;
+  static constexpr uint8_t BTN_CONFIRM = 1;
+  static constexpr uint8_t BTN_LEFT = 2;
+  static constexpr uint8_t BTN_RIGHT = 3;
+  static constexpr uint8_t BTN_UP = 4;
+  static constexpr uint8_t BTN_DOWN = 5;
+  static constexpr uint8_t BTN_POWER = 6;
+};

platformio.ini

@@ -2,7 +2,7 @@
 default_envs = default
 
 [crosspoint]
-version = 0.15.0
+version = 0.16.0
 
 [base]
 platform = espressif32 @ 6.12.0

src/MappedInputManager.cpp

@@ -19,20 +19,20 @@ struct SideLayoutMap {
 
 // Order matches CrossPointSettings::FRONT_BUTTON_LAYOUT.
 constexpr FrontLayoutMap kFrontLayouts[] = {
-    {InputManager::BTN_BACK, InputManager::BTN_CONFIRM, InputManager::BTN_LEFT, InputManager::BTN_RIGHT},
+    {HalGPIO::BTN_BACK, HalGPIO::BTN_CONFIRM, HalGPIO::BTN_LEFT, HalGPIO::BTN_RIGHT},
-    {InputManager::BTN_LEFT, InputManager::BTN_RIGHT, InputManager::BTN_BACK, InputManager::BTN_CONFIRM},
+    {HalGPIO::BTN_LEFT, HalGPIO::BTN_RIGHT, HalGPIO::BTN_BACK, HalGPIO::BTN_CONFIRM},
-    {InputManager::BTN_CONFIRM, InputManager::BTN_LEFT, InputManager::BTN_BACK, InputManager::BTN_RIGHT},
+    {HalGPIO::BTN_CONFIRM, HalGPIO::BTN_LEFT, HalGPIO::BTN_BACK, HalGPIO::BTN_RIGHT},
-    {InputManager::BTN_BACK, InputManager::BTN_CONFIRM, InputManager::BTN_RIGHT, InputManager::BTN_LEFT},
+    {HalGPIO::BTN_BACK, HalGPIO::BTN_CONFIRM, HalGPIO::BTN_RIGHT, HalGPIO::BTN_LEFT},
 };
 
 // Order matches CrossPointSettings::SIDE_BUTTON_LAYOUT.
 constexpr SideLayoutMap kSideLayouts[] = {
-    {InputManager::BTN_UP, InputManager::BTN_DOWN},
+    {HalGPIO::BTN_UP, HalGPIO::BTN_DOWN},
-    {InputManager::BTN_DOWN, InputManager::BTN_UP},
+    {HalGPIO::BTN_DOWN, HalGPIO::BTN_UP},
 };
 }  // namespace
 
-bool MappedInputManager::mapButton(const Button button, bool (InputManager::*fn)(uint8_t) const) const {
+bool MappedInputManager::mapButton(const Button button, bool (HalGPIO::*fn)(uint8_t) const) const {
   const auto frontLayout = static_cast<CrossPointSettings::FRONT_BUTTON_LAYOUT>(SETTINGS.frontButtonLayout);
   const auto sideLayout = static_cast<CrossPointSettings::SIDE_BUTTON_LAYOUT>(SETTINGS.sideButtonLayout);
   const auto& front = kFrontLayouts[frontLayout];
@@ -40,41 +40,39 @@ bool MappedInputManager::mapButton(const Button button, bool (InputManager::*fn)
 
   switch (button) {
     case Button::Back:
-      return (inputManager.*fn)(front.back);
+      return (gpio.*fn)(front.back);
     case Button::Confirm:
-      return (inputManager.*fn)(front.confirm);
+      return (gpio.*fn)(front.confirm);
     case Button::Left:
-      return (inputManager.*fn)(front.left);
+      return (gpio.*fn)(front.left);
     case Button::Right:
-      return (inputManager.*fn)(front.right);
+      return (gpio.*fn)(front.right);
     case Button::Up:
-      return (inputManager.*fn)(InputManager::BTN_UP);
+      return (gpio.*fn)(HalGPIO::BTN_UP);
     case Button::Down:
-      return (inputManager.*fn)(InputManager::BTN_DOWN);
+      return (gpio.*fn)(HalGPIO::BTN_DOWN);
     case Button::Power:
-      return (inputManager.*fn)(InputManager::BTN_POWER);
+      return (gpio.*fn)(HalGPIO::BTN_POWER);
     case Button::PageBack:
-      return (inputManager.*fn)(side.pageBack);
+      return (gpio.*fn)(side.pageBack);
     case Button::PageForward:
-      return (inputManager.*fn)(side.pageForward);
+      return (gpio.*fn)(side.pageForward);
   }
 
   return false;
 }
 
-bool MappedInputManager::wasPressed(const Button button) const { return mapButton(button, &InputManager::wasPressed); }
+bool MappedInputManager::wasPressed(const Button button) const { return mapButton(button, &HalGPIO::wasPressed); }
 
-bool MappedInputManager::wasReleased(const Button button) const {
+bool MappedInputManager::wasReleased(const Button button) const { return mapButton(button, &HalGPIO::wasReleased); }
-  return mapButton(button, &InputManager::wasReleased);
-}
 
-bool MappedInputManager::isPressed(const Button button) const { return mapButton(button, &InputManager::isPressed); }
+bool MappedInputManager::isPressed(const Button button) const { return mapButton(button, &HalGPIO::isPressed); }
 
-bool MappedInputManager::wasAnyPressed() const { return inputManager.wasAnyPressed(); }
+bool MappedInputManager::wasAnyPressed() const { return gpio.wasAnyPressed(); }
 
-bool MappedInputManager::wasAnyReleased() const { return inputManager.wasAnyReleased(); }
+bool MappedInputManager::wasAnyReleased() const { return gpio.wasAnyReleased(); }
 
-unsigned long MappedInputManager::getHeldTime() const { return inputManager.getHeldTime(); }
+unsigned long MappedInputManager::getHeldTime() const { return gpio.getHeldTime(); }
 
 MappedInputManager::Labels MappedInputManager::mapLabels(const char* back, const char* confirm, const char* previous,
                                                          const char* next) const {
@@ -91,4 +89,4 @@ MappedInputManager::Labels MappedInputManager::mapLabels(const char* back, const
     default:
       return {back, confirm, previous, next};
   }
-}
+}

src/MappedInputManager.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <InputManager.h>
+#include <HalGPIO.h>
 
 class MappedInputManager {
  public:
@@ -13,7 +13,7 @@ class MappedInputManager {
     const char* btn4;
   };
 
-  explicit MappedInputManager(InputManager& inputManager) : inputManager(inputManager) {}
+  explicit MappedInputManager(HalGPIO& gpio) : gpio(gpio) {}
 
   bool wasPressed(Button button) const;
   bool wasReleased(Button button) const;
@@ -24,7 +24,7 @@ class MappedInputManager {
   Labels mapLabels(const char* back, const char* confirm, const char* previous, const char* next) const;
 
  private:
-  InputManager& inputManager;
+  HalGPIO& gpio;
 
-  bool mapButton(Button button, bool (InputManager::*fn)(uint8_t) const) const;
+  bool mapButton(Button button, bool (HalGPIO::*fn)(uint8_t) const) const;
 };

src/RecentBooksStore.cpp

@@ -7,22 +7,23 @@
 #include <algorithm>
 
 namespace {
-constexpr uint8_t RECENT_BOOKS_FILE_VERSION = 1;
+constexpr uint8_t RECENT_BOOKS_FILE_VERSION = 2;
 constexpr char RECENT_BOOKS_FILE[] = "/.crosspoint/recent.bin";
 constexpr int MAX_RECENT_BOOKS = 10;
 }  // namespace
 
 RecentBooksStore RecentBooksStore::instance;
 
-void RecentBooksStore::addBook(const std::string& path) {
+void RecentBooksStore::addBook(const std::string& path, const std::string& title, const std::string& author) {
   // Remove existing entry if present
-  auto it = std::find(recentBooks.begin(), recentBooks.end(), path);
+  auto it =
+      std::find_if(recentBooks.begin(), recentBooks.end(), [&](const RecentBook& book) { return book.path == path; });
   if (it != recentBooks.end()) {
     recentBooks.erase(it);
   }
 
   // Add to front
-  recentBooks.insert(recentBooks.begin(), path);
+  recentBooks.insert(recentBooks.begin(), {path, title, author});
 
   // Trim to max size
   if (recentBooks.size() > MAX_RECENT_BOOKS) {
@@ -46,7 +47,9 @@ bool RecentBooksStore::saveToFile() const {
   serialization::writePod(outputFile, count);
 
   for (const auto& book : recentBooks) {
-    serialization::writeString(outputFile, book);
+    serialization::writeString(outputFile, book.path);
+    serialization::writeString(outputFile, book.title);
+    serialization::writeString(outputFile, book.author);
   }
 
   outputFile.close();
@@ -63,24 +66,41 @@ bool RecentBooksStore::loadFromFile() {
   uint8_t version;
   serialization::readPod(inputFile, version);
   if (version != RECENT_BOOKS_FILE_VERSION) {
-    Serial.printf("[%lu] [RBS] Deserialization failed: Unknown version %u\n", millis(), version);
+    if (version == 1) {
-    inputFile.close();
+      // Old version, just read paths
-    return false;
+      uint8_t count;
-  }
+      serialization::readPod(inputFile, count);
+      recentBooks.clear();
+      recentBooks.reserve(count);
+      for (uint8_t i = 0; i < count; i++) {
+        std::string path;
+        serialization::readString(inputFile, path);
+        // Title and author will be empty, they will be filled when the book is
+        // opened again
+        recentBooks.push_back({path, "", ""});
+      }
+    } else {
+      Serial.printf("[%lu] [RBS] Deserialization failed: Unknown version %u\n", millis(), version);
+      inputFile.close();
+      return false;
+    }
+  } else {
+    uint8_t count;
+    serialization::readPod(inputFile, count);
 
-  uint8_t count;
+    recentBooks.clear();
-  serialization::readPod(inputFile, count);
+    recentBooks.reserve(count);
 
-  recentBooks.clear();
+    for (uint8_t i = 0; i < count; i++) {
-  recentBooks.reserve(count);
+      std::string path, title, author;
-
+      serialization::readString(inputFile, path);
-  for (uint8_t i = 0; i < count; i++) {
+      serialization::readString(inputFile, title);
-    std::string path;
+      serialization::readString(inputFile, author);
-    serialization::readString(inputFile, path);
+      recentBooks.push_back({path, title, author});
-    recentBooks.push_back(path);
+    }
   }
 
   inputFile.close();
-  Serial.printf("[%lu] [RBS] Recent books loaded from file (%d entries)\n", millis(), count);
+  Serial.printf("[%lu] [RBS] Recent books loaded from file (%d entries)\n", millis(), recentBooks.size());
   return true;
 }

src/RecentBooksStore.h

@@ -2,11 +2,19 @@
 #include <string>
 #include <vector>
 
+struct RecentBook {
+  std::string path;
+  std::string title;
+  std::string author;
+
+  bool operator==(const RecentBook& other) const { return path == other.path; }
+};
+
 class RecentBooksStore {
   // Static instance
   static RecentBooksStore instance;
 
-  std::vector<std::string> recentBooks;
+  std::vector<RecentBook> recentBooks;
 
  public:
   ~RecentBooksStore() = default;
@@ -14,11 +22,11 @@ class RecentBooksStore {
   // Get singleton instance
   static RecentBooksStore& getInstance() { return instance; }
 
-  // Add a book path to the recent list (moves to front if already exists)
+  // Add a book to the recent list (moves to front if already exists)
-  void addBook(const std::string& path);
+  void addBook(const std::string& path, const std::string& title, const std::string& author);
 
-  // Get the list of recent book paths (most recent first)
+  // Get the list of recent books (most recent first)
-  const std::vector<std::string>& getBooks() const { return recentBooks; }
+  const std::vector<RecentBook>& getBooks() const { return recentBooks; }
 
   // Get the count of recent books
   int getCount() const { return static_cast<int>(recentBooks.size()); }

src/activities/boot_sleep/SleepActivity.cpp

@@ -133,7 +133,7 @@ void SleepActivity::renderDefaultSleepScreen() const {
     renderer.invertScreen();
   }
 
-  renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+  renderer.displayBuffer(HalDisplay::HALF_REFRESH);
 }
 
 void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap) const {
@@ -189,7 +189,7 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap) const {
     renderer.invertScreen();
   }
 
-  renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+  renderer.displayBuffer(HalDisplay::HALF_REFRESH);
 
   if (hasGreyscale) {
     bitmap.rewindToData();
@@ -280,5 +280,5 @@ void SleepActivity::renderCoverSleepScreen() const {
 
 void SleepActivity::renderBlankSleepScreen() const {
   renderer.clearScreen();
-  renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+  renderer.displayBuffer(HalDisplay::HALF_REFRESH);
 }

src/activities/home/MyLibraryActivity.cpp

@@ -16,6 +16,7 @@ namespace {
 constexpr int TAB_BAR_Y = 15;
 constexpr int CONTENT_START_Y = 60;
 constexpr int LINE_HEIGHT = 30;
+constexpr int RECENTS_LINE_HEIGHT = 65;  // Increased for two-line items
 constexpr int LEFT_MARGIN = 20;
 constexpr int RIGHT_MARGIN = 40;  // Extra space for scroll indicator
 
@@ -47,7 +48,7 @@ int MyLibraryActivity::getPageItems() const {
 
 int MyLibraryActivity::getCurrentItemCount() const {
   if (currentTab == Tab::Recent) {
-    return static_cast<int>(bookTitles.size());
+    return static_cast<int>(recentBooks.size());
   }
   return static_cast<int>(files.size());
 }
@@ -65,34 +66,16 @@ int MyLibraryActivity::getCurrentPage() const {
 }
 
 void MyLibraryActivity::loadRecentBooks() {
-  constexpr size_t MAX_RECENT_BOOKS = 20;
+  recentBooks.clear();
-
-  bookTitles.clear();
-  bookPaths.clear();
   const auto& books = RECENT_BOOKS.getBooks();
-  bookTitles.reserve(std::min(books.size(), MAX_RECENT_BOOKS));
+  recentBooks.reserve(books.size());
-  bookPaths.reserve(std::min(books.size(), MAX_RECENT_BOOKS));
-
-  for (const auto& path : books) {
-    // Limit to maximum number of recent books
-    if (bookTitles.size() >= MAX_RECENT_BOOKS) {
-      break;
-    }
 
+  for (const auto& book : books) {
     // Skip if file no longer exists
-    if (!SdMan.exists(path.c_str())) {
+    if (!SdMan.exists(book.path.c_str())) {
       continue;
     }
-
+    recentBooks.push_back(book);
-    // Extract filename from path for display
-    std::string title = path;
-    const size_t lastSlash = title.find_last_of('/');
-    if (lastSlash != std::string::npos) {
-      title = title.substr(lastSlash + 1);
-    }
-
-    bookTitles.push_back(title);
-    bookPaths.push_back(path);
   }
 }
 
@@ -176,8 +159,6 @@ void MyLibraryActivity::onExit() {
   vSemaphoreDelete(renderingMutex);
   renderingMutex = nullptr;
 
-  bookTitles.clear();
-  bookPaths.clear();
   files.clear();
 }
 
@@ -207,8 +188,8 @@ void MyLibraryActivity::loop() {
   // Confirm button - open selected item
   if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
     if (currentTab == Tab::Recent) {
-      if (!bookPaths.empty() && selectorIndex < static_cast<int>(bookPaths.size())) {
+      if (!recentBooks.empty() && selectorIndex < static_cast<int>(recentBooks.size())) {
-        onSelectBook(bookPaths[selectorIndex], currentTab);
+        onSelectBook(recentBooks[selectorIndex].path, currentTab);
       }
     } else {
       // Files tab
@@ -333,7 +314,7 @@ void MyLibraryActivity::render() const {
 void MyLibraryActivity::renderRecentTab() const {
   const auto pageWidth = renderer.getScreenWidth();
   const int pageItems = getPageItems();
-  const int bookCount = static_cast<int>(bookTitles.size());
+  const int bookCount = static_cast<int>(recentBooks.size());
 
   if (bookCount == 0) {
     renderer.drawText(UI_10_FONT_ID, LEFT_MARGIN, CONTENT_START_Y, "No recent books");
@@ -343,14 +324,37 @@ void MyLibraryActivity::renderRecentTab() const {
   const auto pageStartIndex = selectorIndex / pageItems * pageItems;
 
   // Draw selection highlight
-  renderer.fillRect(0, CONTENT_START_Y + (selectorIndex % pageItems) * LINE_HEIGHT - 2, pageWidth - RIGHT_MARGIN,
+  renderer.fillRect(0, CONTENT_START_Y + (selectorIndex % pageItems) * RECENTS_LINE_HEIGHT - 2,
-                    LINE_HEIGHT);
+                    pageWidth - RIGHT_MARGIN, RECENTS_LINE_HEIGHT);
 
   // Draw items
   for (int i = pageStartIndex; i < bookCount && i < pageStartIndex + pageItems; i++) {
-    auto item = renderer.truncatedText(UI_10_FONT_ID, bookTitles[i].c_str(), pageWidth - LEFT_MARGIN - RIGHT_MARGIN);
+    const auto& book = recentBooks[i];
-    renderer.drawText(UI_10_FONT_ID, LEFT_MARGIN, CONTENT_START_Y + (i % pageItems) * LINE_HEIGHT, item.c_str(),
+    const int y = CONTENT_START_Y + (i % pageItems) * RECENTS_LINE_HEIGHT;
-                      i != selectorIndex);
+
+    // Line 1: Title
+    std::string title = book.title;
+    if (title.empty()) {
+      // Fallback for older entries or files without metadata
+      title = book.path;
+      const size_t lastSlash = title.find_last_of('/');
+      if (lastSlash != std::string::npos) {
+        title = title.substr(lastSlash + 1);
+      }
+      const size_t dot = title.find_last_of('.');
+      if (dot != std::string::npos) {
+        title.resize(dot);
+      }
+    }
+    auto truncatedTitle = renderer.truncatedText(UI_12_FONT_ID, title.c_str(), pageWidth - LEFT_MARGIN - RIGHT_MARGIN);
+    renderer.drawText(UI_12_FONT_ID, LEFT_MARGIN, y + 2, truncatedTitle.c_str(), i != selectorIndex);
+
+    // Line 2: Author
+    if (!book.author.empty()) {
+      auto truncatedAuthor =
+          renderer.truncatedText(UI_10_FONT_ID, book.author.c_str(), pageWidth - LEFT_MARGIN - RIGHT_MARGIN);
+      renderer.drawText(UI_10_FONT_ID, LEFT_MARGIN, y + 32, truncatedAuthor.c_str(), i != selectorIndex);
+    }
   }
 }
 

src/activities/home/MyLibraryActivity.h

@@ -8,6 +8,7 @@
 #include <vector>
 
 #include "../Activity.h"
+#include "RecentBooksStore.h"
 
 class MyLibraryActivity final : public Activity {
  public:
@@ -22,8 +23,7 @@ class MyLibraryActivity final : public Activity {
   bool updateRequired = false;
 
   // Recent tab state
-  std::vector<std::string> bookTitles;  // Display titles for each book
+  std::vector<RecentBook> recentBooks;
-  std::vector<std::string> bookPaths;   // Paths for each visible book (excludes missing)
 
   // Files tab state (from FileSelectionActivity)
   std::string basepath = "/";

src/activities/reader/EpubReaderActivity.cpp

@@ -7,7 +7,7 @@
 
 #include "CrossPointSettings.h"
 #include "CrossPointState.h"
-#include "EpubReaderChapterSelectionActivity.h"
+#include "EpubReaderTocActivity.h"
 #include "MappedInputManager.h"
 #include "RecentBooksStore.h"
 #include "ScreenComponents.h"
@@ -53,7 +53,6 @@ void EpubReaderActivity::onEnter() {
   }
 
   renderingMutex = xSemaphoreCreateMutex();
-
   epub->setupCacheDir();
 
   FsFile f;
@@ -85,13 +84,13 @@ void EpubReaderActivity::onEnter() {
   // Save current epub as last opened epub and add to recent books
   APP_STATE.openEpubPath = epub->getPath();
   APP_STATE.saveToFile();
-  RECENT_BOOKS.addBook(epub->getPath());
+  RECENT_BOOKS.addBook(epub->getPath(), epub->getTitle(), epub->getAuthor());
 
   // Trigger first update
   updateRequired = true;
 
   xTaskCreate(&EpubReaderActivity::taskTrampoline, "EpubReaderActivityTask",
-              8192,               // Stack size
+              24576,              // Stack size
               this,               // Parameters
               1,                  // Priority
               &displayTaskHandle  // Task handle
@@ -123,20 +122,25 @@ void EpubReaderActivity::loop() {
     return;
   }
 
-  // Enter chapter selection activity
+  // Enter chapter selection activity or menu
   if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
     // Don't start activity transition while rendering
     xSemaphoreTake(renderingMutex, portMAX_DELAY);
     const int currentPage = section ? section->currentPage : 0;
     const int totalPages = section ? section->pageCount : 0;
+
+    // Show consolidated TOC activity (Chapters and Footnotes)
     exitActivity();
-    enterNewActivity(new EpubReaderChapterSelectionActivity(
+    enterNewActivity(new EpubReaderTocActivity(
         this->renderer, this->mappedInput, epub, epub->getPath(), currentSpineIndex, currentPage, totalPages,
+        currentPageFootnotes,
         [this] {
+          // onGoBack
           exitActivity();
           updateRequired = true;
         },
-        [this](const int newSpineIndex) {
+        [this](int newSpineIndex) {
+          // onSelectSpineIndex
           if (currentSpineIndex != newSpineIndex) {
             currentSpineIndex = newSpineIndex;
             nextPageNumber = 0;
@@ -145,8 +149,14 @@ void EpubReaderActivity::loop() {
           exitActivity();
           updateRequired = true;
         },
-        [this](const int newSpineIndex, const int newPage) {
+        [this](const char* href) {
-          // Handle sync position
+          // onSelectFootnote
+          navigateToHref(href, true);
+          exitActivity();
+          updateRequired = true;
+        },
+        [this](int newSpineIndex, int newPage) {
+          // onSyncPosition
           if (currentSpineIndex != newSpineIndex || (section && section->currentPage != newPage)) {
             currentSpineIndex = newSpineIndex;
             nextPageNumber = newPage;
@@ -166,8 +176,14 @@ void EpubReaderActivity::loop() {
 
   // Short press BACK goes to file selection
   if (mappedInput.wasReleased(MappedInputManager::Button::Back) && mappedInput.getHeldTime() < goHomeMs) {
-    onGoBack();
+    if (isViewingFootnote) {
-    return;
+      restoreSavedPosition();
+      updateRequired = true;
+      return;
+    } else {
+      onGoBack();
+      return;
+    }
   }
 
   // When long-press chapter skip is disabled, turn pages on press instead of release.
@@ -188,7 +204,7 @@ void EpubReaderActivity::loop() {
     return;
   }
 
-  // any botton press when at end of the book goes back to the last page
+  // any button press when at end of the book goes back to the last page
   if (currentSpineIndex > 0 && currentSpineIndex >= epub->getSpineItemsCount()) {
     currentSpineIndex = epub->getSpineItemsCount() - 1;
     nextPageNumber = UINT16_MAX;
@@ -254,17 +270,16 @@ void EpubReaderActivity::displayTaskLoop() {
   }
 }
 
-// TODO: Failure handling
 void EpubReaderActivity::renderScreen() {
   if (!epub) {
     return;
   }
 
-  // edge case handling for sub-zero spine index
+  // Edge case handling for sub-zero spine index
   if (currentSpineIndex < 0) {
     currentSpineIndex = 0;
   }
-  // based bounds of book, show end of book screen
+  // Based bounds of book, show end of book screen
   if (currentSpineIndex > epub->getSpineItemsCount()) {
     currentSpineIndex = epub->getSpineItemsCount();
   }
@@ -345,7 +360,7 @@ void EpubReaderActivity::renderScreen() {
       auto progressCallback = [this, barX, barY, barWidth, barHeight](int progress) {
         const int fillWidth = (barWidth - 2) * progress / 100;
         renderer.fillRect(barX + 1, barY + 1, fillWidth, barHeight - 2, true);
-        renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+        renderer.displayBuffer(HalDisplay::FAST_REFRESH);
       };
 
       if (!section->createSectionFile(SETTINGS.getReaderFontId(), SETTINGS.getReaderLineCompression(),
@@ -403,6 +418,22 @@ void EpubReaderActivity::renderScreen() {
       section.reset();
       return renderScreen();
     }
+
+    Serial.printf("[%lu] [ERS] Page loaded: %d elements, %d footnotes\n", millis(), p->elements.size(),
+                  p->footnotes.size());
+
+    // Copy footnotes from page to currentPageFootnotes
+    currentPageFootnotes.clear();
+    int maxFootnotes = (p->footnotes.size() < 8) ? p->footnotes.size() : 8;
+
+    for (int i = 0; i < maxFootnotes; i++) {
+      const FootnoteEntry& footnote = p->footnotes[i];
+      if (footnote.href[0] != '\0') {
+        currentPageFootnotes.addFootnote(footnote.number, footnote.href);
+      }
+    }
+    Serial.printf("[%lu] [ERS] Loaded %d footnotes for current page\n", millis(), p->footnotes.size());
+
     const auto start = millis();
     renderContents(std::move(p), orientedMarginTop, orientedMarginRight, orientedMarginBottom, orientedMarginLeft);
     Serial.printf("[%lu] [ERS] Rendered page in %dms\n", millis(), millis() - start);
@@ -428,7 +459,7 @@ void EpubReaderActivity::renderContents(std::unique_ptr<Page> page, const int or
   page->render(renderer, SETTINGS.getReaderFontId(), orientedMarginLeft, orientedMarginTop);
   renderStatusBar(orientedMarginRight, orientedMarginBottom, orientedMarginLeft);
   if (pagesUntilFullRefresh <= 1) {
-    renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+    renderer.displayBuffer(HalDisplay::HALF_REFRESH);
     pagesUntilFullRefresh = SETTINGS.getRefreshFrequency();
   } else {
     renderer.displayBuffer();
@@ -553,3 +584,119 @@ void EpubReaderActivity::renderStatusBar(const int orientedMarginRight, const in
                       title.c_str());
   }
 }
+
+void EpubReaderActivity::navigateToHref(const char* href, bool savePosition) {
+  if (!epub || !href) return;
+
+  // Save current position if requested
+  if (savePosition && section) {
+    savedSpineIndex = currentSpineIndex;
+    savedPageNumber = section->currentPage;
+    isViewingFootnote = true;
+    Serial.printf("[%lu] [ERS] Saved position: spine %d, page %d\n", millis(), savedSpineIndex, savedPageNumber);
+  }
+
+  // Parse href: "filename.html#anchor"
+  std::string hrefStr(href);
+  std::string filename;
+  std::string anchor;
+
+  size_t hashPos = hrefStr.find('#');
+  if (hashPos != std::string::npos) {
+    filename = hrefStr.substr(0, hashPos);
+    anchor = hrefStr.substr(hashPos + 1);
+  } else {
+    filename = hrefStr;
+  }
+
+  // Extract just filename without path
+  size_t lastSlash = filename.find_last_of('/');
+  if (lastSlash != std::string::npos) {
+    filename = filename.substr(lastSlash + 1);
+  }
+
+  Serial.printf("[%lu] [ERS] Navigate to: %s (anchor: %s)\n", millis(), filename.c_str(), anchor.c_str());
+
+  int targetSpineIndex = -1;
+
+  // FIRST: Check if we have an inline footnote or paragraph note for this anchor
+  if (!anchor.empty()) {
+    // Try inline footnote first
+    std::string inlineFilename = "inline_" + anchor + ".html";
+    Serial.printf("[%lu] [ERS] Looking for inline footnote: %s\n", millis(), inlineFilename.c_str());
+
+    targetSpineIndex = epub->findVirtualSpineIndex(inlineFilename);
+
+    // If not found, try paragraph note
+    if (targetSpineIndex == -1) {
+      std::string pnoteFilename = "pnote_" + anchor + ".html";
+      Serial.printf("[%lu] [ERS] Looking for paragraph note: %s\n", millis(), pnoteFilename.c_str());
+
+      targetSpineIndex = epub->findVirtualSpineIndex(pnoteFilename);
+    }
+
+    if (targetSpineIndex != -1) {
+      Serial.printf("[%lu] [ERS] Found note at virtual index: %d\n", millis(), targetSpineIndex);
+
+      // Navigate to the note
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      currentSpineIndex = targetSpineIndex;
+      nextPageNumber = 0;
+      section.reset();
+      xSemaphoreGive(renderingMutex);
+
+      updateRequired = true;
+      return;
+    } else {
+      Serial.printf("[%lu] [ERS] No virtual note found, trying normal navigation\n", millis());
+    }
+  }
+
+  // FALLBACK: Try to find the file in normal spine items
+  for (int i = 0; i < epub->getSpineItemsCount(); i++) {
+    if (epub->isVirtualSpineItem(i)) continue;
+
+    BookMetadataCache::SpineEntry entry = epub->getSpineItem(i);
+    std::string spineItem = entry.href;
+    size_t lastslash = spineItem.find_last_of('/');
+    std::string spineFilename = (lastslash != std::string::npos) ? spineItem.substr(lastslash + 1) : spineItem;
+
+    if (spineFilename == filename) {
+      targetSpineIndex = i;
+      break;
+    }
+  }
+
+  if (targetSpineIndex == -1) {
+    Serial.printf("[%lu] [ERS] Could not find spine index for: %s\n", millis(), filename.c_str());
+    return;
+  }
+
+  // Navigate to the target chapter
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  currentSpineIndex = targetSpineIndex;
+  nextPageNumber = 0;
+  section.reset();
+  xSemaphoreGive(renderingMutex);
+
+  updateRequired = true;
+
+  Serial.printf("[%lu] [ERS] Navigated to spine index: %d\n", millis(), targetSpineIndex);
+}
+
+void EpubReaderActivity::restoreSavedPosition() {
+  if (savedSpineIndex >= 0 && savedPageNumber >= 0) {
+    Serial.printf("[%lu] [ERS] Restoring position: spine %d, page %d\n", millis(), savedSpineIndex, savedPageNumber);
+
+    xSemaphoreTake(renderingMutex, portMAX_DELAY);
+    currentSpineIndex = savedSpineIndex;
+    nextPageNumber = savedPageNumber;
+    section.reset();
+    xSemaphoreGive(renderingMutex);
+
+    savedSpineIndex = -1;
+    savedPageNumber = -1;
+    isViewingFootnote = false;
+    updateRequired = true;
+  }
+}

src/activities/reader/EpubReaderActivity.h

@@ -5,6 +5,7 @@
 #include <freertos/semphr.h>
 #include <freertos/task.h>
 
+#include "FootnotesData.h"
 #include "activities/ActivityWithSubactivity.h"
 
 class EpubReaderActivity final : public ActivityWithSubactivity {
@@ -21,6 +22,11 @@ class EpubReaderActivity final : public ActivityWithSubactivity {
   const std::function<void()> onGoBack;
   const std::function<void()> onGoHome;
 
+  FootnotesData currentPageFootnotes;
+  int savedSpineIndex = -1;
+  int savedPageNumber = -1;
+  bool isViewingFootnote = false;
+
   static void taskTrampoline(void* param);
   [[noreturn]] void displayTaskLoop();
   void renderScreen();
@@ -28,6 +34,10 @@ class EpubReaderActivity final : public ActivityWithSubactivity {
                       int orientedMarginBottom, int orientedMarginLeft);
   void renderStatusBar(int orientedMarginRight, int orientedMarginBottom, int orientedMarginLeft) const;
 
+  // Footnote navigation methods
+  void navigateToHref(const char* href, bool savePosition = false);
+  void restoreSavedPosition();
+
  public:
   explicit EpubReaderActivity(GfxRenderer& renderer, MappedInputManager& mappedInput, std::unique_ptr<Epub> epub,
                               const std::function<void()>& onGoBack, const std::function<void()>& onGoHome)

src/activities/reader/EpubReaderChapterSelectionActivity.cpp

@@ -1,215 +0,0 @@
-#include "EpubReaderChapterSelectionActivity.h"
-
-#include <GfxRenderer.h>
-
-#include "KOReaderCredentialStore.h"
-#include "KOReaderSyncActivity.h"
-#include "MappedInputManager.h"
-#include "fontIds.h"
-
-namespace {
-// Time threshold for treating a long press as a page-up/page-down
-constexpr int SKIP_PAGE_MS = 700;
-}  // namespace
-
-bool EpubReaderChapterSelectionActivity::hasSyncOption() const { return KOREADER_STORE.hasCredentials(); }
-
-int EpubReaderChapterSelectionActivity::getTotalItems() const {
-  // Add 2 for sync options (top and bottom) if credentials are configured
-  const int syncCount = hasSyncOption() ? 2 : 0;
-  return epub->getTocItemsCount() + syncCount;
-}
-
-bool EpubReaderChapterSelectionActivity::isSyncItem(int index) const {
-  if (!hasSyncOption()) return false;
-  // First item and last item are sync options
-  return index == 0 || index == getTotalItems() - 1;
-}
-
-int EpubReaderChapterSelectionActivity::tocIndexFromItemIndex(int itemIndex) const {
-  // Account for the sync option at the top
-  const int offset = hasSyncOption() ? 1 : 0;
-  return itemIndex - offset;
-}
-
-int EpubReaderChapterSelectionActivity::getPageItems() const {
-  // Layout constants used in renderScreen
-  constexpr int startY = 60;
-  constexpr int lineHeight = 30;
-
-  const int screenHeight = renderer.getScreenHeight();
-  const int endY = screenHeight - lineHeight;
-
-  const int availableHeight = endY - startY;
-  int items = availableHeight / lineHeight;
-
-  // Ensure we always have at least one item per page to avoid division by zero
-  if (items < 1) {
-    items = 1;
-  }
-  return items;
-}
-
-void EpubReaderChapterSelectionActivity::taskTrampoline(void* param) {
-  auto* self = static_cast<EpubReaderChapterSelectionActivity*>(param);
-  self->displayTaskLoop();
-}
-
-void EpubReaderChapterSelectionActivity::onEnter() {
-  ActivityWithSubactivity::onEnter();
-
-  if (!epub) {
-    return;
-  }
-
-  renderingMutex = xSemaphoreCreateMutex();
-
-  // Account for sync option offset when finding current TOC index
-  const int syncOffset = hasSyncOption() ? 1 : 0;
-  selectorIndex = epub->getTocIndexForSpineIndex(currentSpineIndex);
-  if (selectorIndex == -1) {
-    selectorIndex = 0;
-  }
-  selectorIndex += syncOffset;  // Offset for top sync option
-
-  // Trigger first update
-  updateRequired = true;
-  xTaskCreate(&EpubReaderChapterSelectionActivity::taskTrampoline, "EpubReaderChapterSelectionActivityTask",
-              4096,               // Stack size
-              this,               // Parameters
-              1,                  // Priority
-              &displayTaskHandle  // Task handle
-  );
-}
-
-void EpubReaderChapterSelectionActivity::onExit() {
-  ActivityWithSubactivity::onExit();
-
-  // Wait until not rendering to delete task to avoid killing mid-instruction to EPD
-  xSemaphoreTake(renderingMutex, portMAX_DELAY);
-  if (displayTaskHandle) {
-    vTaskDelete(displayTaskHandle);
-    displayTaskHandle = nullptr;
-  }
-  vSemaphoreDelete(renderingMutex);
-  renderingMutex = nullptr;
-}
-
-void EpubReaderChapterSelectionActivity::launchSyncActivity() {
-  xSemaphoreTake(renderingMutex, portMAX_DELAY);
-  exitActivity();
-  enterNewActivity(new KOReaderSyncActivity(
-      renderer, mappedInput, epub, epubPath, currentSpineIndex, currentPage, totalPagesInSpine,
-      [this]() {
-        // On cancel
-        exitActivity();
-        updateRequired = true;
-      },
-      [this](int newSpineIndex, int newPage) {
-        // On sync complete
-        exitActivity();
-        onSyncPosition(newSpineIndex, newPage);
-      }));
-  xSemaphoreGive(renderingMutex);
-}
-
-void EpubReaderChapterSelectionActivity::loop() {
-  if (subActivity) {
-    subActivity->loop();
-    return;
-  }
-
-  const bool prevReleased = mappedInput.wasReleased(MappedInputManager::Button::Up) ||
-                            mappedInput.wasReleased(MappedInputManager::Button::Left);
-  const bool nextReleased = mappedInput.wasReleased(MappedInputManager::Button::Down) ||
-                            mappedInput.wasReleased(MappedInputManager::Button::Right);
-
-  const bool skipPage = mappedInput.getHeldTime() > SKIP_PAGE_MS;
-  const int pageItems = getPageItems();
-  const int totalItems = getTotalItems();
-
-  if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
-    // Check if sync option is selected (first or last item)
-    if (isSyncItem(selectorIndex)) {
-      launchSyncActivity();
-      return;
-    }
-
-    // Get TOC index (account for top sync offset)
-    const int tocIndex = tocIndexFromItemIndex(selectorIndex);
-    const auto newSpineIndex = epub->getSpineIndexForTocIndex(tocIndex);
-    if (newSpineIndex == -1) {
-      onGoBack();
-    } else {
-      onSelectSpineIndex(newSpineIndex);
-    }
-  } else if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
-    onGoBack();
-  } else if (prevReleased) {
-    if (skipPage) {
-      selectorIndex = ((selectorIndex / pageItems - 1) * pageItems + totalItems) % totalItems;
-    } else {
-      selectorIndex = (selectorIndex + totalItems - 1) % totalItems;
-    }
-    updateRequired = true;
-  } else if (nextReleased) {
-    if (skipPage) {
-      selectorIndex = ((selectorIndex / pageItems + 1) * pageItems) % totalItems;
-    } else {
-      selectorIndex = (selectorIndex + 1) % totalItems;
-    }
-    updateRequired = true;
-  }
-}
-
-void EpubReaderChapterSelectionActivity::displayTaskLoop() {
-  while (true) {
-    if (updateRequired && !subActivity) {
-      updateRequired = false;
-      xSemaphoreTake(renderingMutex, portMAX_DELAY);
-      renderScreen();
-      xSemaphoreGive(renderingMutex);
-    }
-    vTaskDelay(10 / portTICK_PERIOD_MS);
-  }
-}
-
-void EpubReaderChapterSelectionActivity::renderScreen() {
-  renderer.clearScreen();
-
-  const auto pageWidth = renderer.getScreenWidth();
-  const int pageItems = getPageItems();
-  const int totalItems = getTotalItems();
-
-  const std::string title =
-      renderer.truncatedText(UI_12_FONT_ID, epub->getTitle().c_str(), pageWidth - 40, EpdFontFamily::BOLD);
-  renderer.drawCenteredText(UI_12_FONT_ID, 15, title.c_str(), true, EpdFontFamily::BOLD);
-
-  const auto pageStartIndex = selectorIndex / pageItems * pageItems;
-  renderer.fillRect(0, 60 + (selectorIndex % pageItems) * 30 - 2, pageWidth - 1, 30);
-
-  for (int i = 0; i < pageItems; i++) {
-    int itemIndex = pageStartIndex + i;
-    if (itemIndex >= totalItems) break;
-    const int displayY = 60 + i * 30;
-    const bool isSelected = (itemIndex == selectorIndex);
-
-    if (isSyncItem(itemIndex)) {
-      renderer.drawText(UI_10_FONT_ID, 20, displayY, ">> Sync Progress", !isSelected);
-    } else {
-      const int tocIndex = tocIndexFromItemIndex(itemIndex);
-      auto item = epub->getTocItem(tocIndex);
-
-      const int indentSize = 20 + (item.level - 1) * 15;
-      const std::string chapterName =
-          renderer.truncatedText(UI_10_FONT_ID, item.title.c_str(), pageWidth - 40 - indentSize);
-
-      renderer.drawText(UI_10_FONT_ID, indentSize, displayY, chapterName.c_str(), !isSelected);
-    }
-  }
-
-  const auto labels = mappedInput.mapLabels("« Back", "Select", "Up", "Down");
-  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
-
-  renderer.displayBuffer();
-}

src/activities/reader/EpubReaderChapterSelectionActivity.h

@@ -1,65 +0,0 @@
-#pragma once
-#include <Epub.h>
-#include <freertos/FreeRTOS.h>
-#include <freertos/semphr.h>
-#include <freertos/task.h>
-
-#include <memory>
-
-#include "../ActivityWithSubactivity.h"
-
-class EpubReaderChapterSelectionActivity final : public ActivityWithSubactivity {
-  std::shared_ptr<Epub> epub;
-  std::string epubPath;
-  TaskHandle_t displayTaskHandle = nullptr;
-  SemaphoreHandle_t renderingMutex = nullptr;
-  int currentSpineIndex = 0;
-  int currentPage = 0;
-  int totalPagesInSpine = 0;
-  int selectorIndex = 0;
-  bool updateRequired = false;
-  const std::function<void()> onGoBack;
-  const std::function<void(int newSpineIndex)> onSelectSpineIndex;
-  const std::function<void(int newSpineIndex, int newPage)> onSyncPosition;
-
-  // Number of items that fit on a page, derived from logical screen height.
-  // This adapts automatically when switching between portrait and landscape.
-  int getPageItems() const;
-
-  // Total items including sync options (top and bottom)
-  int getTotalItems() const;
-
-  // Check if sync option is available (credentials configured)
-  bool hasSyncOption() const;
-
-  // Check if given item index is a sync option (first or last)
-  bool isSyncItem(int index) const;
-
-  // Convert item index to TOC index (accounting for top sync option offset)
-  int tocIndexFromItemIndex(int itemIndex) const;
-
-  static void taskTrampoline(void* param);
-  [[noreturn]] void displayTaskLoop();
-  void renderScreen();
-  void launchSyncActivity();
-
- public:
-  explicit EpubReaderChapterSelectionActivity(GfxRenderer& renderer, MappedInputManager& mappedInput,
-                                              const std::shared_ptr<Epub>& epub, const std::string& epubPath,
-                                              const int currentSpineIndex, const int currentPage,
-                                              const int totalPagesInSpine, const std::function<void()>& onGoBack,
-                                              const std::function<void(int newSpineIndex)>& onSelectSpineIndex,
-                                              const std::function<void(int newSpineIndex, int newPage)>& onSyncPosition)
-      : ActivityWithSubactivity("EpubReaderChapterSelection", renderer, mappedInput),
-        epub(epub),
-        epubPath(epubPath),
-        currentSpineIndex(currentSpineIndex),
-        currentPage(currentPage),
-        totalPagesInSpine(totalPagesInSpine),
-        onGoBack(onGoBack),
-        onSelectSpineIndex(onSelectSpineIndex),
-        onSyncPosition(onSyncPosition) {}
-  void onEnter() override;
-  void onExit() override;
-  void loop() override;
-};

src/activities/reader/EpubReaderTocActivity.cpp

@@ -0,0 +1,312 @@
+#include "EpubReaderTocActivity.h"
+
+#include <EpdFontFamily.h>
+#include <GfxRenderer.h>
+
+#include "KOReaderCredentialStore.h"
+#include "KOReaderSyncActivity.h"
+#include "MappedInputManager.h"
+#include "ScreenComponents.h"
+#include "fontIds.h"
+
+namespace {
+constexpr int TAB_BAR_Y = 15;
+constexpr int CONTENT_START_Y = 60;
+constexpr int CHAPTER_LINE_HEIGHT = 30;
+constexpr int FOOTNOTE_LINE_HEIGHT = 40;
+constexpr int SKIP_PAGE_MS = 700;
+}  // namespace
+
+void EpubReaderTocActivity::taskTrampoline(void* param) {
+  auto* self = static_cast<EpubReaderTocActivity*>(param);
+  self->displayTaskLoop();
+}
+
+void EpubReaderTocActivity::onEnter() {
+  ActivityWithSubactivity::onEnter();
+  renderingMutex = xSemaphoreCreateMutex();
+
+  // Init chapters state
+  buildFilteredChapterList();
+  chaptersSelectorIndex = 0;
+  for (size_t i = 0; i < filteredSpineIndices.size(); i++) {
+    if (filteredSpineIndices[i] == currentSpineIndex) {
+      chaptersSelectorIndex = i;
+      break;
+    }
+  }
+  if (hasSyncOption()) {
+    chaptersSelectorIndex += 1;
+  }
+
+  // Init footnotes state
+  footnotesSelectedIndex = 0;
+
+  updateRequired = true;
+  xTaskCreate(&EpubReaderTocActivity::taskTrampoline, "EpubReaderTocTask", 4096, this, 1, &displayTaskHandle);
+}
+
+void EpubReaderTocActivity::onExit() {
+  ActivityWithSubactivity::onExit();
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  if (displayTaskHandle) {
+    vTaskDelete(displayTaskHandle);
+    displayTaskHandle = nullptr;
+  }
+  vSemaphoreDelete(renderingMutex);
+  renderingMutex = nullptr;
+}
+
+void EpubReaderTocActivity::launchSyncActivity() {
+  xSemaphoreTake(renderingMutex, portMAX_DELAY);
+  exitActivity();
+  enterNewActivity(new KOReaderSyncActivity(
+      renderer, mappedInput, this->epub, epubPath, currentSpineIndex, currentPage, totalPagesInSpine,
+      [this]() {
+        exitActivity();
+        this->updateRequired = true;
+      },
+      [this](int newSpineIndex, int newPage) {
+        exitActivity();
+        this->onSyncPosition(newSpineIndex, newPage);
+      }));
+  xSemaphoreGive(renderingMutex);
+}
+
+void EpubReaderTocActivity::loop() {
+  if (subActivity) {
+    subActivity->loop();
+    return;
+  }
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
+    onGoBack();
+    return;
+  }
+
+  const bool leftReleased = mappedInput.wasReleased(MappedInputManager::Button::Left);
+  const bool rightReleased = mappedInput.wasReleased(MappedInputManager::Button::Right);
+
+  if (leftReleased && currentTab == Tab::FOOTNOTES) {
+    currentTab = Tab::CHAPTERS;
+    updateRequired = true;
+    return;
+  }
+  if (rightReleased && currentTab == Tab::CHAPTERS) {
+    currentTab = Tab::FOOTNOTES;
+    updateRequired = true;
+    return;
+  }
+
+  if (currentTab == Tab::CHAPTERS) {
+    loopChapters();
+  } else {
+    loopFootnotes();
+  }
+}
+
+void EpubReaderTocActivity::loopChapters() {
+  const bool upReleased = mappedInput.wasReleased(MappedInputManager::Button::Up);
+  const bool downReleased = mappedInput.wasReleased(MappedInputManager::Button::Down);
+  const bool skipPage = mappedInput.getHeldTime() > SKIP_PAGE_MS;
+  const int totalItems = getChaptersTotalItems();
+
+  if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
+    if (isSyncItem(chaptersSelectorIndex)) {
+      launchSyncActivity();
+      return;
+    }
+
+    int filteredIndex = chaptersSelectorIndex;
+
+    if (hasSyncOption() && chaptersSelectorIndex > 0) filteredIndex -= 1;
+
+    if (filteredIndex >= 0 && filteredIndex < static_cast<int>(filteredSpineIndices.size())) {
+      onSelectSpineIndex(filteredSpineIndices[filteredIndex]);
+    }
+  } else if (mappedInput.wasReleased(MappedInputManager::Button::Back)) {
+    onGoBack();
+  } else if (upReleased) {
+    if (totalItems > 0) {
+      if (skipPage) {
+        // TODO: implement page-skip navigation once page size is available
+      }
+      chaptersSelectorIndex = (chaptersSelectorIndex + totalItems - 1) % totalItems;
+      updateRequired = true;
+    }
+  } else if (downReleased) {
+    if (totalItems > 0) {
+      if (skipPage) {
+        // TODO: implement page-skip navigation once page size is available
+      }
+      chaptersSelectorIndex = (chaptersSelectorIndex + 1) % totalItems;
+      updateRequired = true;
+    }
+  }
+}
+
+void EpubReaderTocActivity::loopFootnotes() {
+  bool needsRedraw = false;
+  if (mappedInput.wasPressed(MappedInputManager::Button::Up)) {
+    if (footnotesSelectedIndex > 0) {
+      footnotesSelectedIndex--;
+      needsRedraw = true;
+    }
+  }
+  if (mappedInput.wasPressed(MappedInputManager::Button::Down)) {
+    if (footnotesSelectedIndex < footnotes.getCount() - 1) {
+      footnotesSelectedIndex++;
+      needsRedraw = true;
+    }
+  }
+  if (mappedInput.wasReleased(MappedInputManager::Button::Confirm)) {
+    const FootnoteEntry* entry = footnotes.getEntry(footnotesSelectedIndex);
+    if (entry) {
+      onSelectFootnote(entry->href);
+    }
+  }
+  if (needsRedraw) {
+    updateRequired = true;
+  }
+}
+
+void EpubReaderTocActivity::displayTaskLoop() {
+  while (true) {
+    if (updateRequired && !subActivity) {
+      updateRequired = false;
+      xSemaphoreTake(renderingMutex, portMAX_DELAY);
+      renderScreen();
+      xSemaphoreGive(renderingMutex);
+    }
+    vTaskDelay(10 / portTICK_PERIOD_MS);
+  }
+}
+
+void EpubReaderTocActivity::renderScreen() {
+  renderer.clearScreen();
+
+  std::vector<TabInfo> tabs = {{"Chapters", currentTab == Tab::CHAPTERS}, {"Footnotes", currentTab == Tab::FOOTNOTES}};
+  ScreenComponents::drawTabBar(renderer, TAB_BAR_Y, tabs);
+
+  const int screenHeight = renderer.getScreenHeight();
+  const int contentHeight = screenHeight - CONTENT_START_Y - 60;
+
+  if (currentTab == Tab::CHAPTERS) {
+    renderChapters(CONTENT_START_Y, contentHeight);
+  } else {
+    renderFootnotes(CONTENT_START_Y, contentHeight);
+  }
+
+  ScreenComponents::drawScrollIndicator(renderer, getCurrentPage(), getTotalPages(), CONTENT_START_Y, contentHeight);
+
+  const auto labels = mappedInput.mapLabels("« Back", "Select", "< Tab", "Tab >");
+  renderer.drawButtonHints(UI_10_FONT_ID, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
+  renderer.drawSideButtonHints(UI_10_FONT_ID, ">", "<");
+
+  renderer.displayBuffer();
+}
+
+void EpubReaderTocActivity::renderChapters(int contentTop, int contentHeight) {
+  const auto pageWidth = renderer.getScreenWidth();
+  const int pageItems = getChaptersPageItems(contentHeight);
+  const int totalItems = getChaptersTotalItems();
+  const auto pageStartIndex = chaptersSelectorIndex / pageItems * pageItems;
+
+  renderer.fillRect(0, contentTop + (chaptersSelectorIndex % pageItems) * CHAPTER_LINE_HEIGHT - 2, pageWidth - 1,
+                    CHAPTER_LINE_HEIGHT);
+
+  for (int i = 0; i < pageItems; i++) {
+    int itemIndex = pageStartIndex + i;
+    if (itemIndex >= totalItems) break;
+
+    const int displayY = contentTop + i * CHAPTER_LINE_HEIGHT;
+    const bool isSelected = (itemIndex == chaptersSelectorIndex);
+
+    if (isSyncItem(itemIndex)) {
+      renderer.drawText(UI_10_FONT_ID, 20, displayY, ">> Sync Progress", !isSelected);
+    } else {
+      int filteredIndex = itemIndex;
+      if (hasSyncOption()) filteredIndex -= 1;
+
+      if (filteredIndex >= 0 && filteredIndex < static_cast<int>(filteredSpineIndices.size())) {
+        int spineIndex = filteredSpineIndices[filteredIndex];
+        int tocIndex = this->epub->getTocIndexForSpineIndex(spineIndex);
+        if (tocIndex == -1) {
+          renderer.drawText(UI_10_FONT_ID, 20, displayY, "Unnamed", !isSelected);
+        } else {
+          auto item = this->epub->getTocItem(tocIndex);
+          const int indentSize = 20 + (item.level - 1) * 15;
+          const std::string chapterName =
+              renderer.truncatedText(UI_10_FONT_ID, item.title.c_str(), pageWidth - 40 - indentSize);
+          renderer.drawText(UI_10_FONT_ID, indentSize, displayY, chapterName.c_str(), !isSelected);
+        }
+      }
+    }
+  }
+}
+
+void EpubReaderTocActivity::renderFootnotes(int contentTop, int contentHeight) {
+  const int marginLeft = 20;
+  if (footnotes.getCount() == 0) {
+    renderer.drawText(SMALL_FONT_ID, marginLeft, contentTop + 20, "No footnotes on this page");
+    return;
+  }
+  for (int i = 0; i < footnotes.getCount(); i++) {
+    const FootnoteEntry* entry = footnotes.getEntry(i);
+    if (!entry) continue;
+    const int y = contentTop + i * FOOTNOTE_LINE_HEIGHT;
+    if (i == footnotesSelectedIndex) {
+      renderer.drawText(UI_12_FONT_ID, marginLeft - 10, y, ">", EpdFontFamily::BOLD);
+      renderer.drawText(UI_12_FONT_ID, marginLeft + 10, y, entry->number, EpdFontFamily::BOLD);
+    } else {
+      renderer.drawText(UI_12_FONT_ID, marginLeft + 10, y, entry->number);
+    }
+  }
+}
+
+void EpubReaderTocActivity::buildFilteredChapterList() {
+  filteredSpineIndices.clear();
+  for (int i = 0; i < this->epub->getSpineItemsCount(); i++) {
+    if (this->epub->shouldHideFromToc(i)) continue;
+    int tocIndex = this->epub->getTocIndexForSpineIndex(i);
+    if (tocIndex == -1) continue;
+    filteredSpineIndices.push_back(i);
+  }
+}
+
+bool EpubReaderTocActivity::hasSyncOption() const { return KOREADER_STORE.hasCredentials(); }
+
+bool EpubReaderTocActivity::isSyncItem(int index) const {
+  if (!hasSyncOption()) return false;
+  return index == 0 || index == getChaptersTotalItems() - 1;
+}
+
+int EpubReaderTocActivity::getChaptersTotalItems() const {
+  const int syncCount = hasSyncOption() ? 2 : 0;
+  return filteredSpineIndices.size() + syncCount;
+}
+
+int EpubReaderTocActivity::getChaptersPageItems(int contentHeight) const {
+  int items = contentHeight / CHAPTER_LINE_HEIGHT;
+  return (items < 1) ? 1 : items;
+}
+
+int EpubReaderTocActivity::getCurrentPage() const {
+  if (currentTab == Tab::CHAPTERS) {
+    const int availableHeight = renderer.getScreenHeight() - 120;
+    const int itemsPerPage = availableHeight / CHAPTER_LINE_HEIGHT;
+    return chaptersSelectorIndex / (itemsPerPage > 0 ? itemsPerPage : 1) + 1;
+  }
+  return 1;
+}
+
+int EpubReaderTocActivity::getTotalPages() const {
+  if (currentTab == Tab::CHAPTERS) {
+    const int availableHeight = renderer.getScreenHeight() - 120;
+    const int itemsPerPage = availableHeight / CHAPTER_LINE_HEIGHT;
+    const int totalItems = getChaptersTotalItems();
+    if (totalItems == 0) return 1;
+    return (totalItems + itemsPerPage - 1) / (itemsPerPage > 0 ? itemsPerPage : 1);
+  }
+  return 1;
+}

src/activities/reader/EpubReaderTocActivity.h

@@ -0,0 +1,90 @@
+#pragma once
+#include <Epub.h>
+#include <freertos/FreeRTOS.h>
+#include <freertos/semphr.h>
+#include <freertos/task.h>
+
+#include <memory>
+#include <vector>
+
+#include "../ActivityWithSubactivity.h"
+#include "FootnotesData.h"
+
+class EpubReaderTocActivity final : public ActivityWithSubactivity {
+ public:
+  enum class Tab { CHAPTERS, FOOTNOTES };
+
+ private:
+  std::shared_ptr<Epub> epub;
+  std::string epubPath;
+  const FootnotesData& footnotes;
+
+  TaskHandle_t displayTaskHandle = nullptr;
+  SemaphoreHandle_t renderingMutex = nullptr;
+
+  int currentSpineIndex = 0;
+  int currentPage = 0;
+  int totalPagesInSpine = 0;
+
+  Tab currentTab = Tab::CHAPTERS;
+  bool updateRequired = false;
+
+  // Chapters tab state
+  int chaptersSelectorIndex = 0;
+  std::vector<int> filteredSpineIndices;
+
+  // Footnotes tab state
+  int footnotesSelectedIndex = 0;
+
+  // Callbacks
+  const std::function<void()> onGoBack;
+  const std::function<void(int newSpineIndex)> onSelectSpineIndex;
+  const std::function<void(const char* href)> onSelectFootnote;
+  const std::function<void(int newSpineIndex, int newPage)> onSyncPosition;
+
+  static void taskTrampoline(void* param);
+  [[noreturn]] void displayTaskLoop();
+  void renderScreen();
+
+  // Tab-specific methods
+  void loopChapters();
+  void loopFootnotes();
+  void renderChapters(int contentTop, int contentHeight);
+  void renderFootnotes(int contentTop, int contentHeight);
+
+  // Chapters helpers
+  void buildFilteredChapterList();
+  bool hasSyncOption() const;
+  bool isSyncItem(int index) const;
+  int getChaptersTotalItems() const;
+  int getChaptersPageItems(int contentHeight) const;
+  int tocIndexFromItemIndex(int itemIndex) const;
+
+  // Indicator helpers
+  int getCurrentPage() const;
+  int getTotalPages() const;
+
+ public:
+  EpubReaderTocActivity(GfxRenderer& renderer, MappedInputManager& mappedInput, const std::shared_ptr<Epub>& epub_ptr,
+                        const std::string& epubPath, int currentSpineIndex, int currentPage, int totalPagesInSpine,
+                        const FootnotesData& footnotes, std::function<void()> onGoBack,
+                        std::function<void(int)> onSelectSpineIndex, std::function<void(const char*)> onSelectFootnote,
+                        std::function<void(int, int)> onSyncPosition)
+      : ActivityWithSubactivity("EpubReaderToc", renderer, mappedInput),
+        epub(epub_ptr),
+        epubPath(epubPath),
+        currentSpineIndex(currentSpineIndex),
+        currentPage(currentPage),
+        totalPagesInSpine(totalPagesInSpine),
+        footnotes(footnotes),
+        onGoBack(onGoBack),
+        onSelectSpineIndex(onSelectSpineIndex),
+        onSelectFootnote(onSelectFootnote),
+        onSyncPosition(onSyncPosition) {}
+
+  void onEnter() override;
+  void onExit() override;
+  void loop() override;
+
+  void launchSyncActivity();
+};

src/activities/reader/FootnotesData.h

@@ -0,0 +1,45 @@
+#pragma once
+#include <Epub/FootnoteEntry.h>
+
+#include <cstring>
+
+class FootnotesData {
+ private:
+  FootnoteEntry entries[16];
+  int count;
+
+ public:
+  FootnotesData() : count(0) {
+    for (int i = 0; i < 16; i++) {
+      entries[i].number[0] = '\0';
+      entries[i].href[0] = '\0';
+    }
+  }
+
+  void addFootnote(const char* number, const char* href) {
+    if (count < 16 && number && href) {
+      strncpy(entries[count].number, number, 2);
+      entries[count].number[2] = '\0';
+      strncpy(entries[count].href, href, 63);
+      entries[count].href[63] = '\0';
+      count++;
+    }
+  }
+
+  void clear() {
+    count = 0;
+    for (int i = 0; i < 16; i++) {
+      entries[i].number[0] = '\0';
+      entries[i].href[0] = '\0';
+    }
+  }
+
+  int getCount() const { return count; }
+
+  const FootnoteEntry* getEntry(int index) const {
+    if (index >= 0 && index < count) {
+      return &entries[index];
+    }
+    return nullptr;
+  }
+};

src/activities/reader/TxtReaderActivity.cpp

@@ -60,7 +60,7 @@ void TxtReaderActivity::onEnter() {
   // Save current txt as last opened file and add to recent books
   APP_STATE.openEpubPath = txt->getPath();
   APP_STATE.saveToFile();
-  RECENT_BOOKS.addBook(txt->getPath());
+  RECENT_BOOKS.addBook(txt->getPath(), "", "");
 
   // Trigger first update
   updateRequired = true;
@@ -256,7 +256,7 @@ void TxtReaderActivity::buildPageIndex() {
       // Fill progress bar
       const int fillWidth = (barWidth - 2) * progressPercent / 100;
       renderer.fillRect(barX + 1, barY + 1, fillWidth, barHeight - 2, true);
-      renderer.displayBuffer(EInkDisplay::FAST_REFRESH);
+      renderer.displayBuffer(HalDisplay::FAST_REFRESH);
     }
 
     // Yield to other tasks periodically
@@ -484,7 +484,7 @@ void TxtReaderActivity::renderPage() {
   renderStatusBar(orientedMarginRight, orientedMarginBottom, orientedMarginLeft);
 
   if (pagesUntilFullRefresh <= 1) {
-    renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+    renderer.displayBuffer(HalDisplay::HALF_REFRESH);
     pagesUntilFullRefresh = SETTINGS.getRefreshFrequency();
   } else {
     renderer.displayBuffer();

src/activities/reader/XtcReaderActivity.cpp

@@ -45,7 +45,7 @@ void XtcReaderActivity::onEnter() {
   // Save current XTC as last opened book and add to recent books
   APP_STATE.openEpubPath = xtc->getPath();
   APP_STATE.saveToFile();
-  RECENT_BOOKS.addBook(xtc->getPath());
+  RECENT_BOOKS.addBook(xtc->getPath(), xtc->getTitle(), xtc->getAuthor());
 
   // Trigger first update
   updateRequired = true;
@@ -276,7 +276,7 @@ void XtcReaderActivity::renderPage() {
 
     // Display BW with conditional refresh based on pagesUntilFullRefresh
     if (pagesUntilFullRefresh <= 1) {
-      renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+      renderer.displayBuffer(HalDisplay::HALF_REFRESH);
       pagesUntilFullRefresh = SETTINGS.getRefreshFrequency();
     } else {
       renderer.displayBuffer();
@@ -356,7 +356,7 @@ void XtcReaderActivity::renderPage() {
 
   // Display with appropriate refresh
   if (pagesUntilFullRefresh <= 1) {
-    renderer.displayBuffer(EInkDisplay::HALF_REFRESH);
+    renderer.displayBuffer(HalDisplay::HALF_REFRESH);
     pagesUntilFullRefresh = SETTINGS.getRefreshFrequency();
   } else {
     renderer.displayBuffer();

src/activities/util/FullScreenMessageActivity.h

@@ -1,6 +1,6 @@
 #pragma once
-#include <EInkDisplay.h>
 #include <EpdFontFamily.h>
+#include <HalDisplay.h>
 
 #include <string>
 #include <utility>
@@ -10,12 +10,12 @@
 class FullScreenMessageActivity final : public Activity {
   std::string text;
   EpdFontFamily::Style style;
-  EInkDisplay::RefreshMode refreshMode;
+  HalDisplay::RefreshMode refreshMode;
 
  public:
   explicit FullScreenMessageActivity(GfxRenderer& renderer, MappedInputManager& mappedInput, std::string text,
                                      const EpdFontFamily::Style style = EpdFontFamily::REGULAR,
-                                     const EInkDisplay::RefreshMode refreshMode = EInkDisplay::FAST_REFRESH)
+                                     const HalDisplay::RefreshMode refreshMode = HalDisplay::FAST_REFRESH)
       : Activity("FullScreenMessage", renderer, mappedInput),
         text(std::move(text)),
         style(style),

src/main.cpp

@@ -1,8 +1,8 @@
 #include <Arduino.h>
-#include <EInkDisplay.h>
 #include <Epub.h>
 #include <GfxRenderer.h>
-#include <InputManager.h>
+#include <HalDisplay.h>
+#include <HalGPIO.h>
 #include <SDCardManager.h>
 #include <SPI.h>
 #include <builtinFonts/all.h>
@@ -26,23 +26,10 @@
 #include "activities/util/FullScreenMessageActivity.h"
 #include "fontIds.h"
 
-#define SPI_FQ 40000000
+HalDisplay display;
-// Display SPI pins (custom pins for XteinkX4, not hardware SPI defaults)
+HalGPIO gpio;
-#define EPD_SCLK 8   // SPI Clock
+MappedInputManager mappedInputManager(gpio);
-#define EPD_MOSI 10  // SPI MOSI (Master Out Slave In)
+GfxRenderer renderer(display);
-#define EPD_CS 21    // Chip Select
-#define EPD_DC 4     // Data/Command
-#define EPD_RST 5    // Reset
-#define EPD_BUSY 6   // Busy
-
-#define UART0_RXD 20  // Used for USB connection detection
-
-#define SD_SPI_MISO 7
-
-EInkDisplay einkDisplay(EPD_SCLK, EPD_MOSI, EPD_CS, EPD_DC, EPD_RST, EPD_BUSY);
-InputManager inputManager;
-MappedInputManager mappedInputManager(inputManager);
-GfxRenderer renderer(einkDisplay);
 Activity* currentActivity;
 
 // Fonts
@@ -170,21 +157,20 @@ void verifyPowerButtonDuration() {
   const uint16_t calibratedPressDuration =
       (calibration < SETTINGS.getPowerButtonDuration()) ? SETTINGS.getPowerButtonDuration() - calibration : 1;
 
-  inputManager.update();
+  gpio.update();
-  // Verify the user has actually pressed
   // Needed because inputManager.isPressed() may take up to ~500ms to return the correct state
-  while (!inputManager.isPressed(InputManager::BTN_POWER) && millis() - start < 1000) {
+  while (!gpio.isPressed(HalGPIO::BTN_POWER) && millis() - start < 1000) {
     delay(10);  // only wait 10ms each iteration to not delay too much in case of short configured duration.
-    inputManager.update();
+    gpio.update();
   }
 
   t2 = millis();
-  if (inputManager.isPressed(InputManager::BTN_POWER)) {
+  if (gpio.isPressed(HalGPIO::BTN_POWER)) {
     do {
       delay(10);
-      inputManager.update();
+      gpio.update();
-    } while (inputManager.isPressed(InputManager::BTN_POWER) && inputManager.getHeldTime() < calibratedPressDuration);
+    } while (gpio.isPressed(HalGPIO::BTN_POWER) && gpio.getHeldTime() < calibratedPressDuration);
-    abort = inputManager.getHeldTime() < calibratedPressDuration;
+    abort = gpio.getHeldTime() < calibratedPressDuration;
   } else {
     abort = true;
   }
@@ -192,16 +178,15 @@ void verifyPowerButtonDuration() {
   if (abort) {
     // Button released too early. Returning to sleep.
     // IMPORTANT: Re-arm the wakeup trigger before sleeping again
-    esp_deep_sleep_enable_gpio_wakeup(1ULL << InputManager::POWER_BUTTON_PIN, ESP_GPIO_WAKEUP_GPIO_LOW);
+    gpio.startDeepSleep();
-    esp_deep_sleep_start();
   }
 }
 
 void waitForPowerRelease() {
-  inputManager.update();
+  gpio.update();
-  while (inputManager.isPressed(InputManager::BTN_POWER)) {
+  while (gpio.isPressed(HalGPIO::BTN_POWER)) {
     delay(50);
-    inputManager.update();
+    gpio.update();
   }
 }
 
@@ -210,14 +195,11 @@ void enterDeepSleep() {
   exitActivity();
   enterNewActivity(new SleepActivity(renderer, mappedInputManager));
 
-  einkDisplay.deepSleep();
+  display.deepSleep();
   Serial.printf("[%lu] [   ] Power button press calibration value: %lu ms\n", millis(), t2 - t1);
   Serial.printf("[%lu] [   ] Entering deep sleep.\n", millis());
-  esp_deep_sleep_enable_gpio_wakeup(1ULL << InputManager::POWER_BUTTON_PIN, ESP_GPIO_WAKEUP_GPIO_LOW);
+
-  // Ensure that the power button has been released to avoid immediately turning back on if you're holding it
+  gpio.startDeepSleep();
-  waitForPowerRelease();
-  // Enter Deep Sleep
-  esp_deep_sleep_start();
 }
 
 void onGoHome();
@@ -261,7 +243,7 @@ void onGoHome() {
 }
 
 void setupDisplayAndFonts() {
-  einkDisplay.begin();
+  display.begin();
   Serial.printf("[%lu] [   ] Display initialized\n", millis());
   renderer.insertFont(BOOKERLY_14_FONT_ID, bookerly14FontFamily);
 #ifndef OMIT_FONTS
@@ -284,27 +266,13 @@ void setupDisplayAndFonts() {
   Serial.printf("[%lu] [   ] Fonts setup\n", millis());
 }
 
-bool isUsbConnected() {
-  // U0RXD/GPIO20 reads HIGH when USB is connected
-  return digitalRead(UART0_RXD) == HIGH;
-}
-
-bool isWakeupByPowerButton() {
-  const auto wakeupCause = esp_sleep_get_wakeup_cause();
-  const auto resetReason = esp_reset_reason();
-  if (isUsbConnected()) {
-    return wakeupCause == ESP_SLEEP_WAKEUP_GPIO;
-  } else {
-    return (wakeupCause == ESP_SLEEP_WAKEUP_UNDEFINED) && (resetReason == ESP_RST_POWERON);
-  }
-}
-
 void setup() {
   t1 = millis();
 
+  gpio.begin();
+
   // Only start serial if USB connected
-  pinMode(UART0_RXD, INPUT);
+  if (gpio.isUsbConnected()) {
-  if (isUsbConnected()) {
     Serial.begin(115200);
     // Wait up to 3 seconds for Serial to be ready to catch early logs
     unsigned long start = millis();
@@ -313,13 +281,6 @@ void setup() {
     }
   }
 
-  inputManager.begin();
-  // Initialize pins
-  pinMode(BAT_GPIO0, INPUT);
-
-  // Initialize SPI with custom pins
-  SPI.begin(EPD_SCLK, SD_SPI_MISO, EPD_MOSI, EPD_CS);
-
   // SD Card Initialization
   // We need 6 open files concurrently when parsing a new chapter
   if (!SdMan.begin()) {
@@ -333,7 +294,7 @@ void setup() {
   SETTINGS.loadFromFile();
   KOREADER_STORE.loadFromFile();
 
-  if (isWakeupByPowerButton()) {
+  if (gpio.isWakeupByPowerButton()) {
     // For normal wakeups, verify power button press duration
     Serial.printf("[%lu] [   ] Verifying power button press duration\n", millis());
     verifyPowerButtonDuration();
@@ -370,7 +331,7 @@ void loop() {
   const unsigned long loopStartTime = millis();
   static unsigned long lastMemPrint = 0;
 
-  inputManager.update();
+  gpio.update();
 
   if (Serial && millis() - lastMemPrint >= 10000) {
     Serial.printf("[%lu] [MEM] Free: %d bytes, Total: %d bytes, Min Free: %d bytes\n", millis(), ESP.getFreeHeap(),
@@ -380,8 +341,7 @@ void loop() {
 
   // Check for any user activity (button press or release) or active background work
   static unsigned long lastActivityTime = millis();
-  if (inputManager.wasAnyPressed() || inputManager.wasAnyReleased() ||
+  if (gpio.wasAnyPressed() || gpio.wasAnyReleased() || (currentActivity && currentActivity->preventAutoSleep())) {
-      (currentActivity && currentActivity->preventAutoSleep())) {
     lastActivityTime = millis();  // Reset inactivity timer
   }
 
@@ -393,8 +353,7 @@ void loop() {
     return;
   }
 
-  if (inputManager.isPressed(InputManager::BTN_POWER) &&
+  if (gpio.isPressed(HalGPIO::BTN_POWER) && gpio.getHeldTime() > SETTINGS.getPowerButtonDuration()) {
-      inputManager.getHeldTime() > SETTINGS.getPowerButtonDuration()) {
     enterDeepSleep();
     // This should never be hit as `enterDeepSleep` calls esp_deep_sleep_start
     return;