Cut release 0.12.0

## Summary

* **What is the goal of this PR?** (e.g., Fixes a bug in the user
authentication module, Implements the new feature for
  file uploading.)
* **What changes are included?**

## Additional Context

* Add any other information that might be helpful for the reviewer
(e.g., performance implications, potential risks, specific areas to
focus on).

---------

Co-authored-by: ratedcounsel <hello@ratedcounsel.com>
Co-authored-by: Dave Allie <dave@daveallie.com>

README.md

@@ -25,7 +25,7 @@ This project is **not affiliated with Xteink**; it's built as a community projec
 
 ## Features & Usage
 
-- [x] EPUB parsing and rendering
+- [x] EPUB parsing and rendering (EPUB 2 and EPUB 3)
 - [ ] Image support within EPUB
 - [x] Saved reading position
 - [x] File explorer with file picker

USER_GUIDE.md

@@ -5,7 +5,7 @@ the device.
 
 ## 1. Hardware Overview
 
-The device utilises the standard buttons on the Xtink X4 in the same layout:
+The device utilises the standard buttons on the Xtink X4 (in the same layout as the manufacturer firmware, by default):
 
 ### Button Layout
 | Location        | Buttons                                    |
@@ -13,20 +13,23 @@ The device utilises the standard buttons on the Xtink X4 in the same layout:
 | **Bottom Edge** | **Back**, **Confirm**, **Left**, **Right** |
 | **Right Side**  | **Power**, **Volume Up**, **Volume Down**  |
 
+Button layout can be customized in **[Settings](#35-settings)**.
+
 ---
 
 ## 2. Power & Startup
 
 ### Power On / Off
 
-To turn the device on or off, **press and hold the Power button for half a second**. In **Settings** you can configure
+To turn the device on or off, **press and hold the Power button for half a second**. In **[Settings](#35-settings)** you can configure
 the power button to trigger on a short press instead of a long one.
 
 ### First Launch
 
-Upon turning the device on for the first time, you will be placed on the **Home** screen.
+Upon turning the device on for the first time, you will be placed on the **[Home](#31-home-screen)** screen.
 
-> **Note:** On subsequent restarts, the firmware will automatically reopen the last book you were reading.
+> [!NOTE]
+> On subsequent restarts, the firmware will automatically reopen the last book you were reading.
 
 ---
 
@@ -34,10 +37,10 @@ Upon turning the device on for the first time, you will be placed on the **Home*
 
 ### 3.1 Home Screen
 
-The Home Screen is the main entry point to the firmware. From here you can navigate to the **Book Selection** screen,
-**Settings** screen, or **File Upload** screen.
+The Home Screen is the main entry point to the firmware. From here you can navigate to **[Reading Mode](#4-reading-mode)** with the most recently read book, **[Book Selection](#32-book-selection)**,
+**[Settings](#35-settings)**, or the **[File Upload](#34-file-upload-screen)** screen.
 
-### 3.2 Book Selection (Read)
+### 3.2 Book Selection
 
 The Book Selection acts as a folder and file browser.
 
@@ -45,13 +48,13 @@ The Book Selection acts as a folder and file browser.
   and down through folders and books.
 * **Open Selection:** Press **Confirm** to open a folder or read a selected book.
 
-### 3.3 Reading Screen
+### 3.3 Reading Mode
 
-See [4. Reading Mode](#4-reading-mode) below for more information.
+See [Reading Mode](#4-reading-mode) below for more information.
 
 ### 3.4 File Upload Screen
 
-The File Upload screen allows you to upload new e-books to the device. When you enter the screen you'll be prompted with
+The File Upload screen allows you to upload new e-books to the device. When you enter the screen, you'll be prompted with
 a WiFi selection dialog and then your X4 will start hosting a web server.
 
 See the [webserver docs](./docs/webserver.md) for more information on how to connect to the web server and upload files.
@@ -62,7 +65,7 @@ The Settings screen allows you to configure the device's behavior. There are a f
 - **Sleep Screen**: Which sleep screen to display when the device sleeps, options are:
   - "Dark" (default) - The default dark sleep screen
   - "Light" - The same default sleep screen, on a white background
-  - "Custom" - Custom images from the SD card, see [3.6 Sleep Screen](#36-sleep-screen) below for more information
+  - "Custom" - Custom images from the SD card, see [Sleep Screen](#36-sleep-screen) below for more information
   - "Cover" - The book cover image (Note: this is experimental and may not work as expected)
 - **Status Bar**: Configure the status bar displayed while reading, options are:
   - "None" - No status bar
@@ -95,7 +98,7 @@ You can customize the sleep screen by placing custom images in specific location
 
 - **Single Image:** Place a file named `sleep.bmp` in the root directory.
 - **Multiple Images:** Create a `sleep` directory in the root of the SD card and place any number of `.bmp` images
-  inside. If images are found in this directory, they will take priority over the `sleep.png` file, and one will be
+  inside. If images are found in this directory, they will take priority over the `sleep.bmp` file, and one will be
   randomly selected each time the device sleeps.
 
 > [!NOTE]
@@ -123,8 +126,9 @@ Once you have opened a book, the button layout changes to facilitate reading.
 * **Previous Chapter:** Press and **hold** the **Left** (or **Volume Up**) button briefly, then release.
 
 ### System Navigation
-* **Return to Home:** Press **Back** to close the book and return to the Book Selection screen.
-* **Chapter Menu:** Press **Confirm** to open the Table of Contents/Chapter Selection screen.
+* **Return to Book Selection:** Press **Back** to close the book and return to the **[Book Selection](#32-book-selection)** screen.
+* **Return to Home:** Press and hold **Back** to close the book and return to the **[Home](#31-home-screen)** screen.
+* **Chapter Menu:** Press **Confirm** to open the **[Table of Contents/Chapter Selection](#5-chapter-selection-screen)**.
 
 ---
 

docs/file-formats.md

@@ -2,8 +2,220 @@
 
 ## `book.bin`
 
-![](./images/file-formats/book-bin.png)
+### Version 3
+
+ImHex Pattern:
+
+```c++
+import std.mem;
+import std.string;
+import std.core;
+
+// === Configuration ===
+#define EXPECTED_VERSION 3
+#define MAX_STRING_LENGTH 65535
+
+// === String Structure ===
+
+struct String {
+    u32 length [[hidden, comment("String byte length")]];
+    if (length > MAX_STRING_LENGTH) {
+        std::warning(std::format("Unusually large string length: {} bytes", length));
+    }
+    char data[length] [[comment("UTF-8 string data")]];
+} [[sealed, format("format_string"), comment("Length-prefixed UTF-8 string")]];
+
+fn format_string(String s) {
+    return s.data;
+};
+
+// === Metadata Structure ===
+
+struct Metadata {
+    String title [[comment("Book title")]];
+    String author [[comment("Book author")]];
+    String coverItemHref [[comment("Path to cover image")]];
+    String textReferenceHref [[comment("Path to guided first text reference")]];
+} [[comment("Book metadata information")]];
+
+// === Spine Entry Structure ===
+
+struct SpineEntry {
+    String href [[comment("Resource path")]];
+    u32 cumulativeSize [[comment("Cumulative size in bytes"), color("FF6B6B")]];
+    s16 tocIndex [[comment("Index into TOC (-1 if none)"), color("4ECDC4")]];
+} [[comment("Spine entry defining reading order")]];
+
+// === TOC Entry Structure ===
+
+struct TocEntry {
+    String title [[comment("Chapter/section title")]];
+    String href [[comment("Resource path")]];
+    String anchor [[comment("Fragment identifier")]];
+    u8 level [[comment("Nesting level (0-255)"), color("95E1D3")]];
+    s16 spineIndex [[comment("Index into spine (-1 if none)"), color("F38181")]];
+} [[comment("Table of contents entry")]];
+
+// === Book Bin Structure ===
+
+struct BookBin {
+    // Header
+    u8 version [[comment("Format version"), color("FFD93D")]];
+    
+    // Version validation
+    if (version != EXPECTED_VERSION) {
+        std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION));
+    }
+    
+    u32 lutOffset [[comment("Offset to lookup tables"), color("6BCB77")]];
+    u16 spineCount [[comment("Number of spine entries"), color("4D96FF")]];
+    u16 tocCount [[comment("Number of TOC entries"), color("FF6B9D")]];
+    
+    // Metadata section
+    Metadata metadata [[comment("Book metadata")]];
+    
+    // Validate LUT offset alignment
+    u32 currentOffset = $;
+    if (currentOffset != lutOffset) {
+        std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset));
+    }
+    
+    // Lookup Tables
+    u32 spineLut[spineCount] [[comment("Spine entry offsets"), color("4D96FF")]];
+    u32 tocLut[tocCount] [[comment("TOC entry offsets"), color("FF6B9D")]];
+    
+    // Data Entries
+    SpineEntry spines[spineCount] [[comment("Spine entries (reading order)")]];
+    TocEntry toc[tocCount] [[comment("Table of contents entries")]];
+};
+
+// === File Parsing ===
+
+BookBin book @ 0x00;
+
+// Validate we've consumed the entire file
+u32 fileSize = std::mem::size();
+u32 parsedSize = $;
+
+if (parsedSize != fileSize) {
+    std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize));
+}
+```
 
 ## `section.bin`
 
-![](./images/file-formats/section-bin.png)
+### Version 8
+
+ImHex Pattern:
+
+```c++
+import std.mem;
+import std.string;
+import std.core;
+
+// === Configuration ===
+#define EXPECTED_VERSION 8
+#define MAX_STRING_LENGTH 65535
+
+// === String Structure ===
+
+struct String {
+    u32 length [[hidden, comment("String byte length")]];
+    if (length > MAX_STRING_LENGTH) {
+        std::warning(std::format("Unusually large string length: {} bytes", length));
+    }
+    char data[length] [[comment("UTF-8 string data")]];
+} [[sealed, format("format_string"), comment("Length-prefixed UTF-8 string")]];
+
+fn format_string(String s) {
+    return s.data;
+};
+
+// === Page Structure ===
+
+enum StorageType : u8 {
+    PageLine = 1
+};
+
+enum WordStyle : u8 {
+    REGULAR = 0,
+    BOLD = 1,
+    ITALIC = 2,
+    BOLD_ITALIC = 3
+};
+
+enum BlockStyle : u8 {
+    JUSTIFIED = 0,
+    LEFT_ALIGN = 1,
+    CENTER_ALIGN = 2,
+    RIGHT_ALIGN = 3,
+};
+
+struct PageLine {
+  s16 xPos;
+  s16 yPos;
+  u16 wordCount;
+  String words[wordCount];
+  u16 wordXPos[wordCount];
+  WordStyle wordStyle[wordCount];
+  BlockStyle blockStyle;
+};
+
+struct PageElement {
+    u8 pageElementType;
+    if (pageElementType == 1) {
+        PageLine pageLine [[inline]];
+    } else {
+        std::error(std::format("Unknown page element type: {}", pageElementType));
+    }
+};
+
+struct Page {
+    u16 elementCount;
+    PageElement elements[elementCount] [[inline]];
+};
+
+// === Section Bin Structure ===
+
+struct SectionBin {
+    // Header
+    u8 version [[comment("Format version"), color("FFD93D")]];
+    
+    // Version validation
+    if (version != EXPECTED_VERSION) {
+        std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION));
+    }
+    
+    // Cache busting parameters
+    s32 fontId;
+    float lineCompression;
+    bool extraParagraphSpacing;
+    u16 viewportWidth;
+    u16 vieportHeight;
+    u16 pageCount;
+    u32 lutOffset;
+    
+    Page page[pageCount];
+    
+    // Validate LUT offset alignment
+    u32 currentOffset = $;
+    if (currentOffset != lutOffset) {
+        std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset));
+    }
+    
+    // Lookup Tables
+    u32 lut[pageCount];
+};
+
+// === File Parsing ===
+
+SectionBin book @ 0x00;
+
+// Validate we've consumed the entire file
+u32 fileSize = std::mem::size();
+u32 parsedSize = $;
+
+if (parsedSize != fileSize) {
+    std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize));
+}
+```

lib/EpdFont/EpdFontFamily.cpp

@@ -1,6 +1,6 @@
 #include "EpdFontFamily.h"
 
-const EpdFont* EpdFontFamily::getFont(const EpdFontStyle style) const {
+const EpdFont* EpdFontFamily::getFont(const Style style) const {
   if (style == BOLD && bold) {
     return bold;
   }
@@ -22,16 +22,16 @@ const EpdFont* EpdFontFamily::getFont(const EpdFontStyle style) const {
   return regular;
 }
 
-void EpdFontFamily::getTextDimensions(const char* string, int* w, int* h, const EpdFontStyle style) const {
+void EpdFontFamily::getTextDimensions(const char* string, int* w, int* h, const Style style) const {
   getFont(style)->getTextDimensions(string, w, h);
 }
 
-bool EpdFontFamily::hasPrintableChars(const char* string, const EpdFontStyle style) const {
+bool EpdFontFamily::hasPrintableChars(const char* string, const Style style) const {
   return getFont(style)->hasPrintableChars(string);
 }
 
-const EpdFontData* EpdFontFamily::getData(const EpdFontStyle style) const { return getFont(style)->data; }
+const EpdFontData* EpdFontFamily::getData(const Style style) const { return getFont(style)->data; }
 
-const EpdGlyph* EpdFontFamily::getGlyph(const uint32_t cp, const EpdFontStyle style) const {
+const EpdGlyph* EpdFontFamily::getGlyph(const uint32_t cp, const Style style) const {
   return getFont(style)->getGlyph(cp);
 };

lib/EpdFont/EpdFontFamily.h

@@ -1,24 +1,24 @@
 #pragma once
 #include "EpdFont.h"
 
-enum EpdFontStyle { REGULAR, BOLD, ITALIC, BOLD_ITALIC };
-
 class EpdFontFamily {
+ public:
+  enum Style : uint8_t { REGULAR = 0, BOLD = 1, ITALIC = 2, BOLD_ITALIC = 3 };
+
+  explicit EpdFontFamily(const EpdFont* regular, const EpdFont* bold = nullptr, const EpdFont* italic = nullptr,
+                         const EpdFont* boldItalic = nullptr)
+      : regular(regular), bold(bold), italic(italic), boldItalic(boldItalic) {}
+  ~EpdFontFamily() = default;
+  void getTextDimensions(const char* string, int* w, int* h, Style style = REGULAR) const;
+  bool hasPrintableChars(const char* string, Style style = REGULAR) const;
+  const EpdFontData* getData(Style style = REGULAR) const;
+  const EpdGlyph* getGlyph(uint32_t cp, Style style = REGULAR) const;
+
+ private:
   const EpdFont* regular;
   const EpdFont* bold;
   const EpdFont* italic;
   const EpdFont* boldItalic;
 
-  const EpdFont* getFont(EpdFontStyle style) const;
-
- public:
-  explicit EpdFontFamily(const EpdFont* regular, const EpdFont* bold = nullptr, const EpdFont* italic = nullptr,
-                         const EpdFont* boldItalic = nullptr)
-      : regular(regular), bold(bold), italic(italic), boldItalic(boldItalic) {}
-  ~EpdFontFamily() = default;
-  void getTextDimensions(const char* string, int* w, int* h, EpdFontStyle style = REGULAR) const;
-  bool hasPrintableChars(const char* string, EpdFontStyle style = REGULAR) const;
-
-  const EpdFontData* getData(EpdFontStyle style = REGULAR) const;
-  const EpdGlyph* getGlyph(uint32_t cp, EpdFontStyle style = REGULAR) const;
+  const EpdFont* getFont(Style style) const;
 };

lib/Epub/Epub.cpp

@@ -8,6 +8,7 @@
 
 #include "Epub/parsers/ContainerParser.h"
 #include "Epub/parsers/ContentOpfParser.h"
+#include "Epub/parsers/TocNavParser.h"
 #include "Epub/parsers/TocNcxParser.h"
 
 bool Epub::findContentOpfFile(std::string* contentOpfFile) const {
@@ -80,6 +81,10 @@ bool Epub::parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata) {
     tocNcxItem = opfParser.tocNcxPath;
   }
 
+  if (!opfParser.tocNavPath.empty()) {
+    tocNavItem = opfParser.tocNavPath;
+  }
+
   Serial.printf("[%lu] [EBP] Successfully parsed content.opf\n", millis());
   return true;
 }
@@ -141,6 +146,60 @@ bool Epub::parseTocNcxFile() const {
   return true;
 }
 
+bool Epub::parseTocNavFile() const {
+  // the nav file should have been specified in the content.opf file (EPUB 3)
+  if (tocNavItem.empty()) {
+    Serial.printf("[%lu] [EBP] No nav file specified\n", millis());
+    return false;
+  }
+
+  Serial.printf("[%lu] [EBP] Parsing toc nav file: %s\n", millis(), tocNavItem.c_str());
+
+  const auto tmpNavPath = getCachePath() + "/toc.nav";
+  FsFile tempNavFile;
+  if (!SdMan.openFileForWrite("EBP", tmpNavPath, tempNavFile)) {
+    return false;
+  }
+  readItemContentsToStream(tocNavItem, tempNavFile, 1024);
+  tempNavFile.close();
+  if (!SdMan.openFileForRead("EBP", tmpNavPath, tempNavFile)) {
+    return false;
+  }
+  const auto navSize = tempNavFile.size();
+
+  TocNavParser navParser(contentBasePath, navSize, bookMetadataCache.get());
+
+  if (!navParser.setup()) {
+    Serial.printf("[%lu] [EBP] Could not setup toc nav parser\n", millis());
+    return false;
+  }
+
+  const auto navBuffer = static_cast<uint8_t*>(malloc(1024));
+  if (!navBuffer) {
+    Serial.printf("[%lu] [EBP] Could not allocate memory for toc nav parser\n", millis());
+    return false;
+  }
+
+  while (tempNavFile.available()) {
+    const auto readSize = tempNavFile.read(navBuffer, 1024);
+    const auto processedSize = navParser.write(navBuffer, readSize);
+
+    if (processedSize != readSize) {
+      Serial.printf("[%lu] [EBP] Could not process all toc nav data\n", millis());
+      free(navBuffer);
+      tempNavFile.close();
+      return false;
+    }
+  }
+
+  free(navBuffer);
+  tempNavFile.close();
+  SdMan.remove(tmpNavPath.c_str());
+
+  Serial.printf("[%lu] [EBP] Parsed TOC nav items\n", millis());
+  return true;
+}
+
 // load in the meta data for the epub file
 bool Epub::load(const bool buildIfMissing) {
   Serial.printf("[%lu] [EBP] Loading ePub: %s\n", millis(), filepath.c_str());
@@ -184,15 +243,31 @@ bool Epub::load(const bool buildIfMissing) {
     return false;
   }
 
-  // TOC Pass
+  // TOC Pass - try EPUB 3 nav first, fall back to NCX
   if (!bookMetadataCache->beginTocPass()) {
     Serial.printf("[%lu] [EBP] Could not begin writing toc pass\n", millis());
     return false;
   }
-  if (!parseTocNcxFile()) {
-    Serial.printf("[%lu] [EBP] Could not parse toc\n", millis());
-    return false;
+
+  bool tocParsed = false;
+
+  // Try EPUB 3 nav document first (preferred)
+  if (!tocNavItem.empty()) {
+    Serial.printf("[%lu] [EBP] Attempting to parse EPUB 3 nav document\n", millis());
+    tocParsed = parseTocNavFile();
   }
+
+  // Fall back to NCX if nav parsing failed or wasn't available
+  if (!tocParsed && !tocNcxItem.empty()) {
+    Serial.printf("[%lu] [EBP] Falling back to NCX TOC\n", millis());
+    tocParsed = parseTocNcxFile();
+  }
+
+  if (!tocParsed) {
+    Serial.printf("[%lu] [EBP] Warning: Could not parse any TOC format\n", millis());
+    // Continue anyway - book will work without TOC
+  }
+
   if (!bookMetadataCache->endTocPass()) {
     Serial.printf("[%lu] [EBP] Could not end writing toc pass\n", millis());
     return false;

lib/Epub/Epub.h

@@ -12,8 +12,10 @@
 class ZipFile;
 
 class Epub {
-  // the ncx file
+  // the ncx file (EPUB 2)
   std::string tocNcxItem;
+  // the nav file (EPUB 3)
+  std::string tocNavItem;
   // where is the EPUBfile?
   std::string filepath;
   // the base path for items in the EPUB file
@@ -26,6 +28,7 @@ class Epub {
   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)) {

lib/Epub/Epub/Page.cpp

@@ -32,7 +32,7 @@ void Page::render(GfxRenderer& renderer, const int fontId, const int xOffset, co
 }
 
 bool Page::serialize(FsFile& file) const {
-  const uint32_t count = elements.size();
+  const uint16_t count = elements.size();
   serialization::writePod(file, count);
 
   for (const auto& el : elements) {
@@ -49,10 +49,10 @@ bool Page::serialize(FsFile& file) const {
 std::unique_ptr<Page> Page::deserialize(FsFile& file) {
   auto page = std::unique_ptr<Page>(new Page());
 
-  uint32_t count;
+  uint16_t count;
   serialization::readPod(file, count);
 
-  for (uint32_t i = 0; i < count; i++) {
+  for (uint16_t i = 0; i < count; i++) {
     uint8_t tag;
     serialization::readPod(file, tag);
 

lib/Epub/Epub/ParsedText.cpp

@@ -10,7 +10,7 @@
 
 constexpr int MAX_COST = std::numeric_limits<int>::max();
 
-void ParsedText::addWord(std::string word, const EpdFontStyle fontStyle) {
+void ParsedText::addWord(std::string word, const EpdFontFamily::Style fontStyle) {
   if (word.empty()) return;
 
   words.push_back(std::move(word));
@@ -18,7 +18,7 @@ void ParsedText::addWord(std::string word, const EpdFontStyle fontStyle) {
 }
 
 // Consumes data to minimize memory usage
-void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fontId, const int viewportWidth,
+void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fontId, const uint16_t viewportWidth,
                                        const std::function<void(std::shared_ptr<TextBlock>)>& processLine,
                                        const bool includeLastLine) {
   if (words.empty()) {
@@ -188,7 +188,7 @@ void ParsedText::extractLine(const size_t breakIndex, const int pageWidth, const
   // *** CRITICAL STEP: CONSUME DATA USING SPLICE ***
   std::list<std::string> lineWords;
   lineWords.splice(lineWords.begin(), words, words.begin(), wordEndIt);
-  std::list<EpdFontStyle> lineWordStyles;
+  std::list<EpdFontFamily::Style> lineWordStyles;
   lineWordStyles.splice(lineWordStyles.begin(), wordStyles, wordStyles.begin(), wordStyleEndIt);
 
   processLine(std::make_shared<TextBlock>(std::move(lineWords), std::move(lineXPos), std::move(lineWordStyles), style));

lib/Epub/Epub/ParsedText.h

@@ -14,8 +14,8 @@ class GfxRenderer;
 
 class ParsedText {
   std::list<std::string> words;
-  std::list<EpdFontStyle> wordStyles;
-  TextBlock::BLOCK_STYLE style;
+  std::list<EpdFontFamily::Style> wordStyles;
+  TextBlock::Style style;
   bool extraParagraphSpacing;
 
   std::vector<size_t> computeLineBreaks(int pageWidth, int spaceWidth, const std::vector<uint16_t>& wordWidths) const;
@@ -25,16 +25,16 @@ class ParsedText {
   std::vector<uint16_t> calculateWordWidths(const GfxRenderer& renderer, int fontId);
 
  public:
-  explicit ParsedText(const TextBlock::BLOCK_STYLE style, const bool extraParagraphSpacing)
+  explicit ParsedText(const TextBlock::Style style, const bool extraParagraphSpacing)
       : style(style), extraParagraphSpacing(extraParagraphSpacing) {}
   ~ParsedText() = default;
 
-  void addWord(std::string word, EpdFontStyle fontStyle);
-  void setStyle(const TextBlock::BLOCK_STYLE style) { this->style = style; }
-  TextBlock::BLOCK_STYLE getStyle() const { return style; }
+  void addWord(std::string word, EpdFontFamily::Style fontStyle);
+  void setStyle(const TextBlock::Style style) { this->style = style; }
+  TextBlock::Style getStyle() const { return style; }
   size_t size() const { return words.size(); }
   bool isEmpty() const { return words.empty(); }
-  void layoutAndExtractLines(const GfxRenderer& renderer, int fontId, int viewportWidth,
+  void layoutAndExtractLines(const GfxRenderer& renderer, int fontId, uint16_t viewportWidth,
                              const std::function<void(std::shared_ptr<TextBlock>)>& processLine,
                              bool includeLastLine = true);
 };

lib/Epub/Epub/Section.cpp

@@ -7,9 +7,9 @@
 #include "parsers/ChapterHtmlSlimParser.h"
 
 namespace {
-constexpr uint8_t SECTION_FILE_VERSION = 7;
-constexpr uint32_t HEADER_SIZE = sizeof(uint8_t) + sizeof(int) + sizeof(float) + sizeof(bool) + sizeof(int) +
-                                 sizeof(int) + sizeof(int) + sizeof(uint32_t);
+constexpr uint8_t SECTION_FILE_VERSION = 9;
+constexpr uint32_t HEADER_SIZE = sizeof(uint8_t) + sizeof(int) + sizeof(float) + sizeof(bool) + sizeof(uint8_t) +
+                                 sizeof(uint16_t) + sizeof(uint16_t) + sizeof(uint16_t) + sizeof(uint32_t);
 }  // namespace
 
 uint32_t Section::onPageComplete(std::unique_ptr<Page> page) {
@@ -30,19 +30,21 @@ uint32_t Section::onPageComplete(std::unique_ptr<Page> page) {
 }
 
 void Section::writeSectionFileHeader(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
-                                     const int viewportWidth, const int viewportHeight) {
+                                     const uint8_t paragraphAlignment, const uint16_t viewportWidth,
+                                     const uint16_t viewportHeight) {
   if (!file) {
     Serial.printf("[%lu] [SCT] File not open for writing header\n", millis());
     return;
   }
   static_assert(HEADER_SIZE == sizeof(SECTION_FILE_VERSION) + sizeof(fontId) + sizeof(lineCompression) +
-                                   sizeof(extraParagraphSpacing) + sizeof(viewportWidth) + sizeof(viewportHeight) +
-                                   sizeof(pageCount) + sizeof(uint32_t),
+                                   sizeof(extraParagraphSpacing) + sizeof(paragraphAlignment) + sizeof(viewportWidth) +
+                                   sizeof(viewportHeight) + sizeof(pageCount) + sizeof(uint32_t),
                 "Header size mismatch");
   serialization::writePod(file, SECTION_FILE_VERSION);
   serialization::writePod(file, fontId);
   serialization::writePod(file, lineCompression);
   serialization::writePod(file, extraParagraphSpacing);
+  serialization::writePod(file, paragraphAlignment);
   serialization::writePod(file, viewportWidth);
   serialization::writePod(file, viewportHeight);
   serialization::writePod(file, pageCount);  // Placeholder for page count (will be initially 0 when written)
@@ -50,7 +52,8 @@ void Section::writeSectionFileHeader(const int fontId, const float lineCompressi
 }
 
 bool Section::loadSectionFile(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
-                              const int viewportWidth, const int viewportHeight) {
+                              const uint8_t paragraphAlignment, const uint16_t viewportWidth,
+                              const uint16_t viewportHeight) {
   if (!SdMan.openFileForRead("SCT", filePath, file)) {
     return false;
   }
@@ -66,18 +69,21 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con
       return false;
     }
 
-    int fileFontId, fileViewportWidth, fileViewportHeight;
+    int fileFontId;
+    uint16_t fileViewportWidth, fileViewportHeight;
     float fileLineCompression;
     bool fileExtraParagraphSpacing;
+    uint8_t fileParagraphAlignment;
     serialization::readPod(file, fileFontId);
     serialization::readPod(file, fileLineCompression);
     serialization::readPod(file, fileExtraParagraphSpacing);
+    serialization::readPod(file, fileParagraphAlignment);
     serialization::readPod(file, fileViewportWidth);
     serialization::readPod(file, fileViewportHeight);
 
     if (fontId != fileFontId || lineCompression != fileLineCompression ||
-        extraParagraphSpacing != fileExtraParagraphSpacing || viewportWidth != fileViewportWidth ||
-        viewportHeight != fileViewportHeight) {
+        extraParagraphSpacing != fileExtraParagraphSpacing || paragraphAlignment != fileParagraphAlignment ||
+        viewportWidth != fileViewportWidth || viewportHeight != fileViewportHeight) {
       file.close();
       Serial.printf("[%lu] [SCT] Deserialization failed: Parameters do not match\n", millis());
       clearCache();
@@ -108,8 +114,8 @@ bool Section::clearCache() const {
 }
 
 bool Section::createSectionFile(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
-                                const int viewportWidth, const int viewportHeight,
-                                const std::function<void()>& progressSetupFn,
+                                const uint8_t paragraphAlignment, const uint16_t viewportWidth,
+                                const uint16_t viewportHeight, 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;
@@ -165,11 +171,13 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
   if (!SdMan.openFileForWrite("SCT", filePath, file)) {
     return false;
   }
-  writeSectionFileHeader(fontId, lineCompression, extraParagraphSpacing, viewportWidth, viewportHeight);
+  writeSectionFileHeader(fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
+                         viewportHeight);
   std::vector<uint32_t> lut = {};
 
   ChapterHtmlSlimParser visitor(
-      tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, viewportWidth, viewportHeight,
+      tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
+      viewportHeight,
       [this, &lut](std::unique_ptr<Page> page) { lut.emplace_back(this->onPageComplete(std::move(page))); },
       progressFn);
   success = visitor.parseAndBuildPages();

lib/Epub/Epub/Section.h

@@ -14,12 +14,12 @@ class Section {
   std::string filePath;
   FsFile file;
 
-  void writeSectionFileHeader(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
-                              int viewportHeight);
+  void writeSectionFileHeader(int fontId, float lineCompression, bool extraParagraphSpacing, uint8_t paragraphAlignment,
+                              uint16_t viewportWidth, uint16_t viewportHeight);
   uint32_t onPageComplete(std::unique_ptr<Page> page);
 
  public:
-  int pageCount = 0;
+  uint16_t pageCount = 0;
   int currentPage = 0;
 
   explicit Section(const std::shared_ptr<Epub>& epub, const int spineIndex, GfxRenderer& renderer)
@@ -28,11 +28,12 @@ class Section {
         renderer(renderer),
         filePath(epub->getCachePath() + "/sections/" + std::to_string(spineIndex) + ".bin") {}
   ~Section() = default;
-  bool loadSectionFile(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
-                       int viewportHeight);
+  bool loadSectionFile(int fontId, float lineCompression, bool extraParagraphSpacing, uint8_t paragraphAlignment,
+                       uint16_t viewportWidth, uint16_t viewportHeight);
   bool clearCache() const;
-  bool createSectionFile(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
-                         int viewportHeight, const std::function<void()>& progressSetupFn = nullptr,
+  bool createSectionFile(int fontId, float lineCompression, bool extraParagraphSpacing, uint8_t paragraphAlignment,
+                         uint16_t viewportWidth, uint16_t viewportHeight,
+                         const std::function<void()>& progressSetupFn = nullptr,
                          const std::function<void(int)>& progressFn = nullptr);
   std::unique_ptr<Page> loadPageFromSectionFile();
 };

lib/Epub/Epub/blocks/TextBlock.cpp

@@ -32,7 +32,7 @@ bool TextBlock::serialize(FsFile& file) const {
   }
 
   // Word data
-  serialization::writePod(file, static_cast<uint32_t>(words.size()));
+  serialization::writePod(file, static_cast<uint16_t>(words.size()));
   for (const auto& w : words) serialization::writeString(file, w);
   for (auto x : wordXpos) serialization::writePod(file, x);
   for (auto s : wordStyles) serialization::writePod(file, s);
@@ -44,11 +44,11 @@ bool TextBlock::serialize(FsFile& file) const {
 }
 
 std::unique_ptr<TextBlock> TextBlock::deserialize(FsFile& file) {
-  uint32_t wc;
+  uint16_t wc;
   std::list<std::string> words;
   std::list<uint16_t> wordXpos;
-  std::list<EpdFontStyle> wordStyles;
-  BLOCK_STYLE style;
+  std::list<EpdFontFamily::Style> wordStyles;
+  Style style;
 
   // Word count
   serialization::readPod(file, wc);

lib/Epub/Epub/blocks/TextBlock.h

@@ -8,10 +8,10 @@
 
 #include "Block.h"
 
-// represents a block of words in the html document
+// Represents a line of text on a page
 class TextBlock final : public Block {
  public:
-  enum BLOCK_STYLE : uint8_t {
+  enum Style : uint8_t {
     JUSTIFIED = 0,
     LEFT_ALIGN = 1,
     CENTER_ALIGN = 2,
@@ -21,16 +21,16 @@ class TextBlock final : public Block {
  private:
   std::list<std::string> words;
   std::list<uint16_t> wordXpos;
-  std::list<EpdFontStyle> wordStyles;
-  BLOCK_STYLE style;
+  std::list<EpdFontFamily::Style> wordStyles;
+  Style style;
 
  public:
-  explicit TextBlock(std::list<std::string> words, std::list<uint16_t> word_xpos, std::list<EpdFontStyle> word_styles,
-                     const BLOCK_STYLE style)
+  explicit TextBlock(std::list<std::string> words, std::list<uint16_t> word_xpos,
+                     std::list<EpdFontFamily::Style> word_styles, const Style style)
       : words(std::move(words)), wordXpos(std::move(word_xpos)), wordStyles(std::move(word_styles)), style(style) {}
   ~TextBlock() override = default;
-  void setStyle(const BLOCK_STYLE style) { this->style = style; }
-  BLOCK_STYLE getStyle() const { return style; }
+  void setStyle(const Style style) { this->style = style; }
+  Style getStyle() const { return style; }
   bool isEmpty() override { return words.empty(); }
   void layout(GfxRenderer& renderer) override {};
   // given a renderer works out where to break the words into lines

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -42,7 +42,7 @@ bool matches(const char* tag_name, const char* possible_tags[], const int possib
 }
 
 // start a new text block if needed
-void ChapterHtmlSlimParser::startNewTextBlock(const TextBlock::BLOCK_STYLE style) {
+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()) {
@@ -97,7 +97,7 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
     if (strcmp(name, "br") == 0) {
       self->startNewTextBlock(self->currentTextBlock->getStyle());
     } else {
-      self->startNewTextBlock(TextBlock::JUSTIFIED);
+      self->startNewTextBlock((TextBlock::Style)self->paragraphAlignment);
     }
   } else if (matches(name, BOLD_TAGS, NUM_BOLD_TAGS)) {
     self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
@@ -116,13 +116,13 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
     return;
   }
 
-  EpdFontStyle fontStyle = REGULAR;
+  EpdFontFamily::Style fontStyle = EpdFontFamily::REGULAR;
   if (self->boldUntilDepth < self->depth && self->italicUntilDepth < self->depth) {
-    fontStyle = BOLD_ITALIC;
+    fontStyle = EpdFontFamily::BOLD_ITALIC;
   } else if (self->boldUntilDepth < self->depth) {
-    fontStyle = BOLD;
+    fontStyle = EpdFontFamily::BOLD;
   } else if (self->italicUntilDepth < self->depth) {
-    fontStyle = ITALIC;
+    fontStyle = EpdFontFamily::ITALIC;
   }
 
   for (int i = 0; i < len; i++) {
@@ -137,6 +137,21 @@ void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char
       continue;
     }
 
+    // Skip soft-hyphen with UTF-8 representation (U+00AD) = 0xC2 0xAD
+    const XML_Char SHY_BYTE_1 = static_cast<XML_Char>(0xC2);
+    const XML_Char SHY_BYTE_2 = static_cast<XML_Char>(0xAD);
+    // 1. Check for the start of the 2-byte Soft Hyphen sequence
+    if (s[i] == SHY_BYTE_1) {
+      // 2. Check if the next byte exists AND if it completes the sequence
+      //    We must check i + 1 < len to prevent reading past the end of the buffer.
+      if ((i + 1 < len) && (s[i + 1] == SHY_BYTE_2)) {
+        // Sequence 0xC2 0xAD found!
+        // Skip the current byte (0xC2) and the next byte (0xAD)
+        i++;       // Increment 'i' one more time to skip the 0xAD byte
+        continue;  // Skip the rest of the loop and 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->partWordBuffer[self->partWordBufferIndex] = '\0';
@@ -172,13 +187,13 @@ void XMLCALL ChapterHtmlSlimParser::endElement(void* userData, const XML_Char* n
         matches(name, BOLD_TAGS, NUM_BOLD_TAGS) || matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS) || self->depth == 1;
 
     if (shouldBreakText) {
-      EpdFontStyle fontStyle = REGULAR;
+      EpdFontFamily::Style fontStyle = EpdFontFamily::REGULAR;
       if (self->boldUntilDepth < self->depth && self->italicUntilDepth < self->depth) {
-        fontStyle = BOLD_ITALIC;
+        fontStyle = EpdFontFamily::BOLD_ITALIC;
       } else if (self->boldUntilDepth < self->depth) {
-        fontStyle = BOLD;
+        fontStyle = EpdFontFamily::BOLD;
       } else if (self->italicUntilDepth < self->depth) {
-        fontStyle = ITALIC;
+        fontStyle = EpdFontFamily::ITALIC;
       }
 
       self->partWordBuffer[self->partWordBufferIndex] = '\0';
@@ -206,7 +221,7 @@ void XMLCALL ChapterHtmlSlimParser::endElement(void* userData, const XML_Char* n
 }
 
 bool ChapterHtmlSlimParser::parseAndBuildPages() {
-  startNewTextBlock(TextBlock::JUSTIFIED);
+  startNewTextBlock((TextBlock::Style)this->paragraphAlignment);
 
   const XML_Parser parser = XML_ParserCreate(nullptr);
   int done;

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h

@@ -33,10 +33,11 @@ class ChapterHtmlSlimParser {
   int fontId;
   float lineCompression;
   bool extraParagraphSpacing;
-  int viewportWidth;
-  int viewportHeight;
+  uint8_t paragraphAlignment;
+  uint16_t viewportWidth;
+  uint16_t viewportHeight;
 
-  void startNewTextBlock(TextBlock::BLOCK_STYLE style);
+  void startNewTextBlock(TextBlock::Style style);
   void makePages();
   // XML callbacks
   static void XMLCALL startElement(void* userData, const XML_Char* name, const XML_Char** atts);
@@ -45,8 +46,9 @@ class ChapterHtmlSlimParser {
 
  public:
   explicit ChapterHtmlSlimParser(const std::string& filepath, GfxRenderer& renderer, const int fontId,
-                                 const float lineCompression, const bool extraParagraphSpacing, const int viewportWidth,
-                                 const int viewportHeight,
+                                 const float lineCompression, const bool extraParagraphSpacing,
+                                 const uint8_t paragraphAlignment, const uint16_t viewportWidth,
+                                 const uint16_t viewportHeight,
                                  const std::function<void(std::unique_ptr<Page>)>& completePageFn,
                                  const std::function<void(int)>& progressFn = nullptr)
       : filepath(filepath),
@@ -54,6 +56,7 @@ class ChapterHtmlSlimParser {
         fontId(fontId),
         lineCompression(lineCompression),
         extraParagraphSpacing(extraParagraphSpacing),
+        paragraphAlignment(paragraphAlignment),
         viewportWidth(viewportWidth),
         viewportHeight(viewportHeight),
         completePageFn(completePageFn),

lib/Epub/Epub/parsers/ContentOpfParser.cpp

@@ -161,6 +161,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
     std::string itemId;
     std::string href;
     std::string mediaType;
+    std::string properties;
 
     for (int i = 0; atts[i]; i += 2) {
       if (strcmp(atts[i], "id") == 0) {
@@ -169,6 +170,8 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
         href = self->baseContentPath + atts[i + 1];
       } else if (strcmp(atts[i], "media-type") == 0) {
         mediaType = atts[i + 1];
+      } else if (strcmp(atts[i], "properties") == 0) {
+        properties = atts[i + 1];
       }
     }
 
@@ -188,6 +191,15 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
                       href.c_str());
       }
     }
+
+    // EPUB 3: Check for nav document (properties contains "nav")
+    if (!properties.empty() && self->tocNavPath.empty()) {
+      // Properties is space-separated, check if "nav" is present as a word
+      if (properties == "nav" || properties.find("nav ") == 0 || properties.find(" nav") != std::string::npos) {
+        self->tocNavPath = href;
+        Serial.printf("[%lu] [COF] Found EPUB 3 nav document: %s\n", millis(), href.c_str());
+      }
+    }
     return;
   }
 

lib/Epub/Epub/parsers/ContentOpfParser.h

@@ -35,6 +35,7 @@ class ContentOpfParser final : public Print {
   std::string title;
   std::string author;
   std::string tocNcxPath;
+  std::string tocNavPath;  // EPUB 3 nav document path
   std::string coverItemHref;
   std::string textReferenceHref;