Cut release 0.11.2

## Summary

* Hide "System Volume Information" folder
* It's a FAT filesystem folder, shouldn't be used

## Additional Context

* Fixes https://github.com/daveallie/crosspoint-reader/issues/177

README.md

@@ -33,11 +33,13 @@ This project is **not affiliated with Xteink**; it's built as a community projec
   - [x] Support nested folders
   - [ ] EPUB picker with cover art
 - [x] Custom sleep screen
-  - [ ] Cover sleep screen
+  - [x] Cover sleep screen
 - [x] Wifi book upload
-- [ ] Wifi OTA updates
-- [ ] Configurable font, layout, and display options
-- [ ] Screen rotation
+- [x] Wifi OTA updates
+- [x] Configurable font, layout, and display options
+  - [ ] User provided fonts
+  - [ ] Full UTF support
+- [x] Screen rotation
 
 See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint.
 
@@ -98,9 +100,9 @@ CrossPoint Reader is pretty aggressive about caching data down to the SD card to
 has ~380KB of usable RAM, so we have to be careful. A lot of the decisions made in the design of the firmware were based
 on this constraint.
 
-### EPUB caching
+### Data caching
 
-The first time chapters of an EPUB are loaded, they are cached to the SD card. Subsequent loads are served from the 
+The first time chapters of a book are loaded, they are cached to the SD card. Subsequent loads are served from the 
 cache. This cache directory exists at `.crosspoint` on the SD card. The structure is as follows:
 
 
@@ -108,25 +110,22 @@ cache. This cache directory exists at `.crosspoint` on the SD card. The structur
 .crosspoint/
 ├── epub_12471232/       # Each EPUB is cached to a subdirectory named `epub_<hash>`
 │   ├── progress.bin     # Stores reading progress (chapter, page, etc.)
-│   ├── 0/               # Each chapter is stored in a subdirectory named by its index (based on the spine order)
-│   │   ├── section.bin  # Section metadata (page count)
-│   │   ├── page_0.bin   # Each page is stored in a separate file, it
-│   │   ├── page_1.bin   #   contains the position (x, y) and text for each word
-│   │   └── ...
-│   ├── 1/
-│   │   ├── section.bin
-│   │   ├── page_0.bin
-│   │   ├── page_1.bin
-│   │   └── ...
-│   └── ...
+│   ├── cover.bmp        # Book cover image (once generated)
+│   ├── book.bin         # Book metadata (title, author, spine, table of contents, etc.)
+│   └── sections/        # All chapter data is stored in the sections subdirectory
+│       ├── 0.bin        # Chapter data (screen count, all text layout info, etc.)
+│       ├── 1.bin        #     files are named by their index in the spine
+│       └── ...
 │
 └── epub_189013891/
 ```
 
-Deleting the `.crosspoint` directory will clear the cache. 
+Deleting the `.crosspoint` directory will clear the entire cache. 
 
-Due the way it's currently implemented, the cache is not automatically cleared when the EPUB is deleted and moving an 
-EPUB file will reset the reading progress.
+Due the way it's currently implemented, the cache is not automatically cleared when a book is deleted and moving a book
+file will use a new cache directory, resetting the reading progress.
+
+For more details on the internal file structures, see the [file formats document](./docs/file-formats.md).
 
 ## Contributing
 

USER_GUIDE.md

@@ -64,9 +64,30 @@ The Settings screen allows you to configure the device's behavior. There are a f
   - "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
   - "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
+  - "No Progress" - Show status bar without reading progress
+  - "Full" - Show status bar with reading progress
 - **Extra Paragraph Spacing**: If enabled, vertical space will be added between paragraphs in the book, if disabled,
   paragraphs will not have vertical space between them, but will have first word indentation.
 - **Short Power Button Click**: Whether to trigger the power button on a short press or a long press.
+- **Reading Orientation**: Set the screen orientation for reading, options are:
+  - "Portrait" (default) - Standard portrait orientation
+  - "Landscape CW" - Landscape, rotated clockwise
+  - "Inverted" - Portrait, upside down
+  - "Landscape CCW" - Landscape, rotated counter-clockwise
+- **Front Button Layout**: Configure the order of the bottom edge buttons, options are:
+  - "Bck, Cnfrm, Lft, Rght" (default) - Back, Confirm, Left, Right
+  - "Lft, Rght, Bck, Cnfrm" - Left, Right, Back, Confirm
+  - "Lft, Bck, Cnfrm, Rght" - Left, Back, Confirm, Right
+- **Side Button Layout**: Swap the order of the volume buttons from Previous/Next to Next/Previous. This change is only in effect when reading.
+- **Reader Font Family**: Choose the font used for reading, options are:
+  - "Bookerly" (default) - Amazon's reading font
+  - "Noto Sans" - Google's sans-serif font
+  - "Open Dyslexic" - Font designed for readers with dyslexia
+- **Reader Font Size**: Adjust the text size for reading, options are "Small", "Medium", "Large", or "X Large".
+- **Reader Line Spacing**: Adjust the spacing between lines, options are "Tight", "Normal", or "Wide".
+- **Check for updates**: Check for firmware updates over WiFi.
 
 ### 3.6 Sleep Screen
 
@@ -123,5 +144,3 @@ Please note that this firmware is currently in active development. The following
 are planned for future updates:
 
 * **Images:** Embedded images in e-books will not render.
-* **Text Formatting:** There are currently no settings to adjust font type, size, line spacing, or margins.
-* **Rotation**: Different rotation options are not supported.

bin/clang-format-fix

@@ -1,3 +1,19 @@
 #!/bin/bash
 
-find src lib \( -name "*.c" -o -name "*.cpp" -o -name "*.h" -o -name "*.hpp" \) -exec clang-format -style=file -i {} +
+GIT_LS_FILES_FLAGS=""
+if [[ "$1" == "-g" ]]; then
+  GIT_LS_FILES_FLAGS="--modified"
+fi
+
+# --- Main Logic ---
+
+# Format all files (or only modified files if -g is passed)
+
+# Use 'git ls-files' to get a list of all files tracked by git:
+# --modified: files tracked by git that have been modified (staged or unstaged)
+# --exclude-standard: ignores files in .gitignore
+# Additionally exclude files in 'lib/EpdFont/builtinFonts/' as they are script-generated.
+git ls-files  --exclude-standard ${GIT_LS_FILES_FLAGS} \
+    | grep -E '\.(c|cpp|h|hpp)$' \
+    | grep -v -E '^lib/EpdFont/builtinFonts/' \
+    | xargs -r clang-format -style=file -i

docs/file-formats.md

@@ -0,0 +1,9 @@
+# File Formats
+
+## `book.bin`
+
+![](./images/file-formats/book-bin.png)
+
+## `section.bin`
+
+![](./images/file-formats/section-bin.png)

lib/EpdFont/EpdFont.cpp

@@ -2,8 +2,7 @@
 
 #include <Utf8.h>
 
-inline int min(const int a, const int b) { return a < b ? a : b; }
-inline int max(const int a, const int b) { return a < b ? b : a; }
+#include <algorithm>
 
 void EpdFont::getTextBounds(const char* string, const int startX, const int startY, int* minX, int* minY, int* maxX,
                             int* maxY) const {
@@ -32,10 +31,10 @@ void EpdFont::getTextBounds(const char* string, const int startX, const int star
       continue;
     }
 
-    *minX = min(*minX, cursorX + glyph->left);
-    *maxX = max(*maxX, cursorX + glyph->left + glyph->width);
-    *minY = min(*minY, cursorY + glyph->top - glyph->height);
-    *maxY = max(*maxY, cursorY + glyph->top);
+    *minX = std::min(*minX, cursorX + glyph->left);
+    *maxX = std::max(*maxX, cursorX + glyph->left + glyph->width);
+    *minY = std::min(*minY, cursorY + glyph->top - glyph->height);
+    *maxY = std::max(*maxY, cursorY + glyph->top);
     cursorX += glyph->advanceX;
   }
 }

lib/EpdFont/builtinFonts/all.h

@@ -0,0 +1,55 @@
+#pragma once
+
+#include <builtinFonts/bookerly_12_bold.h>
+#include <builtinFonts/bookerly_12_bolditalic.h>
+#include <builtinFonts/bookerly_12_italic.h>
+#include <builtinFonts/bookerly_12_regular.h>
+#include <builtinFonts/bookerly_14_bold.h>
+#include <builtinFonts/bookerly_14_bolditalic.h>
+#include <builtinFonts/bookerly_14_italic.h>
+#include <builtinFonts/bookerly_14_regular.h>
+#include <builtinFonts/bookerly_16_bold.h>
+#include <builtinFonts/bookerly_16_bolditalic.h>
+#include <builtinFonts/bookerly_16_italic.h>
+#include <builtinFonts/bookerly_16_regular.h>
+#include <builtinFonts/bookerly_18_bold.h>
+#include <builtinFonts/bookerly_18_bolditalic.h>
+#include <builtinFonts/bookerly_18_italic.h>
+#include <builtinFonts/bookerly_18_regular.h>
+#include <builtinFonts/notosans_8_regular.h>
+#include <builtinFonts/notosans_12_bold.h>
+#include <builtinFonts/notosans_12_bolditalic.h>
+#include <builtinFonts/notosans_12_italic.h>
+#include <builtinFonts/notosans_12_regular.h>
+#include <builtinFonts/notosans_14_bold.h>
+#include <builtinFonts/notosans_14_bolditalic.h>
+#include <builtinFonts/notosans_14_italic.h>
+#include <builtinFonts/notosans_14_regular.h>
+#include <builtinFonts/notosans_16_bold.h>
+#include <builtinFonts/notosans_16_bolditalic.h>
+#include <builtinFonts/notosans_16_italic.h>
+#include <builtinFonts/notosans_16_regular.h>
+#include <builtinFonts/notosans_18_bold.h>
+#include <builtinFonts/notosans_18_bolditalic.h>
+#include <builtinFonts/notosans_18_italic.h>
+#include <builtinFonts/notosans_18_regular.h>
+#include <builtinFonts/opendyslexic_10_bold.h>
+#include <builtinFonts/opendyslexic_10_bolditalic.h>
+#include <builtinFonts/opendyslexic_10_italic.h>
+#include <builtinFonts/opendyslexic_10_regular.h>
+#include <builtinFonts/opendyslexic_12_bold.h>
+#include <builtinFonts/opendyslexic_12_bolditalic.h>
+#include <builtinFonts/opendyslexic_12_italic.h>
+#include <builtinFonts/opendyslexic_12_regular.h>
+#include <builtinFonts/opendyslexic_14_bold.h>
+#include <builtinFonts/opendyslexic_14_bolditalic.h>
+#include <builtinFonts/opendyslexic_14_italic.h>
+#include <builtinFonts/opendyslexic_14_regular.h>
+#include <builtinFonts/opendyslexic_8_bold.h>
+#include <builtinFonts/opendyslexic_8_bolditalic.h>
+#include <builtinFonts/opendyslexic_8_italic.h>
+#include <builtinFonts/opendyslexic_8_regular.h>
+#include <builtinFonts/ubuntu_10_bold.h>
+#include <builtinFonts/ubuntu_10_regular.h>
+#include <builtinFonts/ubuntu_12_bold.h>
+#include <builtinFonts/ubuntu_12_regular.h>

lib/EpdFont/builtinFonts/source/NotoSans/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Noto Project Authors (https://github.com/notofonts/latin-greek-cyrillic)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

lib/EpdFont/builtinFonts/source/OpenDyslexic/OFL.txt

@@ -0,0 +1,94 @@
+Copyright (c) 2019-07-29, Abbie Gonzalez (https://abbiecod.es|support@abbiecod.es),
+with Reserved Font Name OpenDyslexic.
+Copyright (c) 12/2012 - 2019
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

lib/EpdFont/builtinFonts/source/Ubuntu/UFL.txt

@@ -0,0 +1,96 @@
+-------------------------------
+UBUNTU FONT LICENCE Version 1.0
+-------------------------------
+
+PREAMBLE
+This licence allows the licensed fonts to be used, studied, modified and
+redistributed freely. The fonts, including any derivative works, can be
+bundled, embedded, and redistributed provided the terms of this licence
+are met. The fonts and derivatives, however, cannot be released under
+any other licence. The requirement for fonts to remain under this
+licence does not require any document created using the fonts or their
+derivatives to be published under this licence, as long as the primary
+purpose of the document is not to be a vehicle for the distribution of
+the fonts.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this licence and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Original Version" refers to the collection of Font Software components
+as received under this licence.
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to
+a new environment.
+
+"Copyright Holder(s)" refers to all individuals and companies who have a
+copyright ownership of the Font Software.
+
+"Substantially Changed" refers to Modified Versions which can be easily
+identified as dissimilar to the Font Software by users of the Font
+Software comparing the Original Version with the Modified Version.
+
+To "Propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification and with or without charging
+a redistribution fee), making available to the public, and in some
+countries other activities as well.
+
+PERMISSION & CONDITIONS
+This licence does not grant any rights under trademark law and all such
+rights are reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of the Font Software, to propagate the Font Software, subject to
+the below conditions:
+
+1) Each copy of the Font Software must contain the above copyright
+notice and this licence. These can be included either as stand-alone
+text files, human-readable headers or in the appropriate machine-
+readable metadata fields within text or binary files as long as those
+fields can be easily viewed by the user.
+
+2) The font name complies with the following:
+(a) The Original Version must retain its name, unmodified.
+(b) Modified Versions which are Substantially Changed must be renamed to
+avoid use of the name of the Original Version or similar names entirely.
+(c) Modified Versions which are not Substantially Changed must be
+renamed to both (i) retain the name of the Original Version and (ii) add
+additional naming elements to distinguish the Modified Version from the
+Original Version. The name of such Modified Versions must be the name of
+the Original Version, with "derivative X" where X represents the name of
+the new work, appended to that name.
+
+3) The name(s) of the Copyright Holder(s) and any contributor to the
+Font Software shall not be used to promote, endorse or advertise any
+Modified Version, except (i) as required by this licence, (ii) to
+acknowledge the contribution(s) of the Copyright Holder(s) or (iii) with
+their explicit written permission.
+
+4) The Font Software, modified or unmodified, in part or in whole, must
+be distributed entirely under this licence, and must not be distributed
+under any other licence. The requirement for fonts to remain under this
+licence does not affect any document created using the Font Software,
+except any version of the Font Software extracted from a document
+created using the Font Software may only be distributed under this
+licence.
+
+TERMINATION
+This licence becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER
+DEALINGS IN THE FONT SOFTWARE.

lib/EpdFont/scripts/build-font-ids.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+
+set -e
+
+cd "$(dirname "$0")/../builtinFonts"
+
+echo "// The contents of this file are generated by ./lib/EpdFont/scripts/build-font-ids.sh"
+echo "#pragma once"
+echo ""
+
+echo "#define BOOKERLY_12_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./bookerly_12_regular.h",
+  "./bookerly_12_bold.h",
+  "./bookerly_12_bolditalic.h",
+  "./bookerly_12_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define BOOKERLY_14_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./bookerly_14_regular.h",
+  "./bookerly_14_bold.h",
+  "./bookerly_14_bolditalic.h",
+  "./bookerly_14_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define BOOKERLY_16_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./bookerly_16_regular.h",
+  "./bookerly_16_bold.h",
+  "./bookerly_16_bolditalic.h",
+  "./bookerly_16_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define BOOKERLY_18_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./bookerly_18_regular.h",
+  "./bookerly_18_bold.h",
+  "./bookerly_18_bolditalic.h",
+  "./bookerly_18_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define NOTOSANS_12_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./notosans_12_regular.h",
+  "./notosans_12_bold.h",
+  "./notosans_12_bolditalic.h",
+  "./notosans_12_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define NOTOSANS_14_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./notosans_14_regular.h",
+  "./notosans_14_bold.h",
+  "./notosans_14_bolditalic.h",
+  "./notosans_14_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define NOTOSANS_16_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./notosans_16_regular.h",
+  "./notosans_16_bold.h",
+  "./notosans_16_bolditalic.h",
+  "./notosans_16_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define NOTOSANS_18_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./notosans_18_regular.h",
+  "./notosans_18_bold.h",
+  "./notosans_18_bolditalic.h",
+  "./notosans_18_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define OPENDYSLEXIC_8_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./opendyslexic_8_regular.h",
+  "./opendyslexic_8_bold.h",
+  "./opendyslexic_8_bolditalic.h",
+  "./opendyslexic_8_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define OPENDYSLEXIC_10_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./opendyslexic_10_regular.h",
+  "./opendyslexic_10_bold.h",
+  "./opendyslexic_10_bolditalic.h",
+  "./opendyslexic_10_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define OPENDYSLEXIC_12_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./opendyslexic_12_regular.h",
+  "./opendyslexic_12_bold.h",
+  "./opendyslexic_12_bolditalic.h",
+  "./opendyslexic_12_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define OPENDYSLEXIC_14_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./opendyslexic_14_regular.h",
+  "./opendyslexic_14_bold.h",
+  "./opendyslexic_14_bolditalic.h",
+  "./opendyslexic_14_italic.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define UI_10_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./ubuntu_10_regular.h",
+  "./ubuntu_10_bold.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define UI_12_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./ubuntu_12_regular.h",
+  "./ubuntu_12_bold.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"
+
+echo "#define SMALL_FONT_ID ($(
+ruby -rdigest -e 'puts [
+  "./notosans_8_regular.h",
+].map{|f| Digest::SHA256.hexdigest(File.read(f)).to_i(16) }.sum % (2 ** 32) - (2 ** 31)'
+))"

lib/EpdFont/scripts/convert-builtin-fonts.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+
+set -e
+
+cd "$(dirname "$0")"
+
+READER_FONT_STYLES=("Regular" "Italic" "Bold" "BoldItalic")
+BOOKERLY_FONT_SIZES=(12 14 16 18)
+NOTOSANS_FONT_SIZES=(12 14 16 18)
+OPENDYSLEXIC_FONT_SIZES=(8 10 12 14)
+
+for size in ${BOOKERLY_FONT_SIZES[@]}; do
+  for style in ${READER_FONT_STYLES[@]}; do
+    font_name="bookerly_${size}_$(echo $style | tr '[:upper:]' '[:lower:]')"
+    font_path="../builtinFonts/source/Bookerly/Bookerly-${style}.ttf"
+    output_path="../builtinFonts/${font_name}.h"
+    python fontconvert.py $font_name $size $font_path --2bit > $output_path
+    echo "Generated $output_path"
+  done
+done
+
+for size in ${NOTOSANS_FONT_SIZES[@]}; do
+  for style in ${READER_FONT_STYLES[@]}; do
+    font_name="notosans_${size}_$(echo $style | tr '[:upper:]' '[:lower:]')"
+    font_path="../builtinFonts/source/NotoSans/NotoSans-${style}.ttf"
+    output_path="../builtinFonts/${font_name}.h"
+    python fontconvert.py $font_name $size $font_path --2bit > $output_path
+    echo "Generated $output_path"
+  done
+done
+
+for size in ${OPENDYSLEXIC_FONT_SIZES[@]}; do
+  for style in ${READER_FONT_STYLES[@]}; do
+    font_name="opendyslexic_${size}_$(echo $style | tr '[:upper:]' '[:lower:]')"
+    font_path="../builtinFonts/source/OpenDyslexic/OpenDyslexic-${style}.otf"
+    output_path="../builtinFonts/${font_name}.h"
+    python fontconvert.py $font_name $size $font_path --2bit > $output_path
+    echo "Generated $output_path"
+  done
+done
+
+UI_FONT_SIZES=(10 12)
+UI_FONT_STYLES=("Regular" "Bold")
+
+for size in ${UI_FONT_SIZES[@]}; do
+  for style in ${UI_FONT_STYLES[@]}; do
+    font_name="ubuntu_${size}_$(echo $style | tr '[:upper:]' '[:lower:]')"
+    font_path="../builtinFonts/source/Ubuntu/Ubuntu-${style}.ttf"
+    output_path="../builtinFonts/${font_name}.h"
+    python fontconvert.py $font_name $size $font_path > $output_path
+    echo "Generated $output_path"
+  done
+done
+
+python fontconvert.py notosans_8_regular 8 ../builtinFonts/source/NotoSans/NotoSans-Regular.ttf > ../builtinFonts/notosans_8_regular.h

lib/Epub/Epub.cpp

@@ -3,7 +3,7 @@
 #include <FsHelpers.h>
 #include <HardwareSerial.h>
 #include <JpegToBmpConverter.h>
-#include <SD.h>
+#include <SDCardManager.h>
 #include <ZipFile.h>
 
 #include "Epub/parsers/ContainerParser.h"
@@ -60,9 +60,6 @@ bool Epub::parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata) {
   }
 
   ContentOpfParser opfParser(getCachePath(), getBasePath(), contentOpfSize, bookMetadataCache.get());
-  Serial.printf("[%lu] [MEM] Free: %d bytes, Total: %d bytes, Min Free: %d bytes\n", millis(), ESP.getFreeHeap(),
-                ESP.getHeapSize(), ESP.getMinFreeHeap());
-
   if (!opfParser.setup()) {
     Serial.printf("[%lu] [EBP] Could not setup content.opf parser\n", millis());
     return false;
@@ -75,9 +72,9 @@ bool Epub::parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata) {
 
   // Grab data from opfParser into epub
   bookMetadata.title = opfParser.title;
-  // TODO: Parse author
-  bookMetadata.author = "";
+  bookMetadata.author = opfParser.author;
   bookMetadata.coverItemHref = opfParser.coverItemHref;
+  bookMetadata.textReferenceHref = opfParser.textReferenceHref;
 
   if (!opfParser.tocNcxPath.empty()) {
     tocNcxItem = opfParser.tocNcxPath;
@@ -97,13 +94,13 @@ bool Epub::parseTocNcxFile() const {
   Serial.printf("[%lu] [EBP] Parsing toc ncx file: %s\n", millis(), tocNcxItem.c_str());
 
   const auto tmpNcxPath = getCachePath() + "/toc.ncx";
-  File tempNcxFile;
-  if (!FsHelpers::openFileForWrite("EBP", tmpNcxPath, tempNcxFile)) {
+  FsFile tempNcxFile;
+  if (!SdMan.openFileForWrite("EBP", tmpNcxPath, tempNcxFile)) {
     return false;
   }
   readItemContentsToStream(tocNcxItem, tempNcxFile, 1024);
   tempNcxFile.close();
-  if (!FsHelpers::openFileForRead("EBP", tmpNcxPath, tempNcxFile)) {
+  if (!SdMan.openFileForRead("EBP", tmpNcxPath, tempNcxFile)) {
     return false;
   }
   const auto ncxSize = tempNcxFile.size();
@@ -112,17 +109,20 @@ bool Epub::parseTocNcxFile() const {
 
   if (!ncxParser.setup()) {
     Serial.printf("[%lu] [EBP] Could not setup toc ncx parser\n", millis());
+    tempNcxFile.close();
     return false;
   }
 
   const auto ncxBuffer = static_cast<uint8_t*>(malloc(1024));
   if (!ncxBuffer) {
     Serial.printf("[%lu] [EBP] Could not allocate memory for toc ncx parser\n", millis());
+    tempNcxFile.close();
     return false;
   }
 
   while (tempNcxFile.available()) {
     const auto readSize = tempNcxFile.read(ncxBuffer, 1024);
+    if (readSize == 0) break;
     const auto processedSize = ncxParser.write(ncxBuffer, readSize);
 
     if (processedSize != readSize) {
@@ -135,14 +135,14 @@ bool Epub::parseTocNcxFile() const {
 
   free(ncxBuffer);
   tempNcxFile.close();
-  SD.remove(tmpNcxPath.c_str());
+  SdMan.remove(tmpNcxPath.c_str());
 
   Serial.printf("[%lu] [EBP] Parsed TOC items\n", millis());
   return true;
 }
 
 // load in the meta data for the epub file
-bool Epub::load() {
+bool Epub::load(const bool buildIfMissing) {
   Serial.printf("[%lu] [EBP] Loading ePub: %s\n", millis(), filepath.c_str());
 
   // Initialize spine/TOC cache
@@ -154,6 +154,11 @@ bool Epub::load() {
     return true;
   }
 
+  // If we didn't load from cache above and we aren't allowed to build, fail now
+  if (!buildIfMissing) {
+    return false;
+  }
+
   // Cache doesn't exist or is invalid, build it
   Serial.printf("[%lu] [EBP] Cache not found, building spine/TOC cache\n", millis());
   setupCacheDir();
@@ -221,12 +226,12 @@ bool Epub::load() {
 }
 
 bool Epub::clearCache() const {
-  if (!SD.exists(cachePath.c_str())) {
+  if (!SdMan.exists(cachePath.c_str())) {
     Serial.printf("[%lu] [EPB] Cache does not exist, no action needed\n", millis());
     return true;
   }
 
-  if (!FsHelpers::removeDir(cachePath.c_str())) {
+  if (!SdMan.removeDir(cachePath.c_str())) {
     Serial.printf("[%lu] [EPB] Failed to clear cache\n", millis());
     return false;
   }
@@ -236,17 +241,11 @@ bool Epub::clearCache() const {
 }
 
 void Epub::setupCacheDir() const {
-  if (SD.exists(cachePath.c_str())) {
+  if (SdMan.exists(cachePath.c_str())) {
     return;
   }
 
-  // Loop over each segment of the cache path and create directories as needed
-  for (size_t i = 1; i < cachePath.length(); i++) {
-    if (cachePath[i] == '/') {
-      SD.mkdir(cachePath.substr(0, i).c_str());
-    }
-  }
-  SD.mkdir(cachePath.c_str());
+  SdMan.mkdir(cachePath.c_str());
 }
 
 const std::string& Epub::getCachePath() const { return cachePath; }
@@ -262,11 +261,20 @@ const std::string& Epub::getTitle() const {
   return bookMetadataCache->coreMetadata.title;
 }
 
+const std::string& Epub::getAuthor() const {
+  static std::string blank;
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    return blank;
+  }
+
+  return bookMetadataCache->coreMetadata.author;
+}
+
 std::string Epub::getCoverBmpPath() const { return cachePath + "/cover.bmp"; }
 
 bool Epub::generateCoverBmp() const {
   // Already generated, return true
-  if (SD.exists(getCoverBmpPath().c_str())) {
+  if (SdMan.exists(getCoverBmpPath().c_str())) {
     return true;
   }
 
@@ -286,30 +294,30 @@ bool Epub::generateCoverBmp() const {
     Serial.printf("[%lu] [EBP] Generating BMP from JPG cover image\n", millis());
     const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";
 
-    File coverJpg;
-    if (!FsHelpers::openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
+    FsFile coverJpg;
+    if (!SdMan.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
       return false;
     }
     readItemContentsToStream(coverImageHref, coverJpg, 1024);
     coverJpg.close();
 
-    if (!FsHelpers::openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
+    if (!SdMan.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
       return false;
     }
 
-    File coverBmp;
-    if (!FsHelpers::openFileForWrite("EBP", getCoverBmpPath(), coverBmp)) {
+    FsFile coverBmp;
+    if (!SdMan.openFileForWrite("EBP", getCoverBmpPath(), coverBmp)) {
       coverJpg.close();
       return false;
     }
     const bool success = JpegToBmpConverter::jpegFileToBmpStream(coverJpg, coverBmp);
     coverJpg.close();
     coverBmp.close();
-    SD.remove(coverJpgTempPath.c_str());
+    SdMan.remove(coverJpgTempPath.c_str());
 
     if (!success) {
       Serial.printf("[%lu] [EBP] Failed to generate BMP from JPG cover image\n", millis());
-      SD.remove(getCoverBmpPath().c_str());
+      SdMan.remove(getCoverBmpPath().c_str());
     }
     Serial.printf("[%lu] [EBP] Generated BMP from JPG cover image, success: %s\n", millis(), success ? "yes" : "no");
     return success;
@@ -321,10 +329,14 @@ bool Epub::generateCoverBmp() const {
 }
 
 uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size, const bool trailingNullByte) const {
-  const ZipFile zip("/sd" + filepath);
+  if (itemHref.empty()) {
+    Serial.printf("[%lu] [EBP] Failed to read item, empty href\n", millis());
+    return nullptr;
+  }
+
   const std::string path = FsHelpers::normalisePath(itemHref);
 
-  const auto content = zip.readFileToMemory(path.c_str(), size, trailingNullByte);
+  const auto content = ZipFile(filepath).readFileToMemory(path.c_str(), size, trailingNullByte);
   if (!content) {
     Serial.printf("[%lu] [EBP] Failed to read item %s\n", millis(), path.c_str());
     return nullptr;
@@ -334,20 +346,18 @@ uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size
 }
 
 bool Epub::readItemContentsToStream(const std::string& itemHref, Print& out, const size_t chunkSize) const {
-  const ZipFile zip("/sd" + filepath);
-  const std::string path = FsHelpers::normalisePath(itemHref);
+  if (itemHref.empty()) {
+    Serial.printf("[%lu] [EBP] Failed to read item, empty href\n", millis());
+    return false;
+  }
 
-  return zip.readFileToStream(path.c_str(), out, chunkSize);
+  const std::string path = FsHelpers::normalisePath(itemHref);
+  return ZipFile(filepath).readFileToStream(path.c_str(), out, chunkSize);
 }
 
 bool Epub::getItemSize(const std::string& itemHref, size_t* size) const {
-  const ZipFile zip("/sd" + filepath);
-  return getItemSize(zip, itemHref, size);
-}
-
-bool Epub::getItemSize(const ZipFile& zip, const std::string& itemHref, size_t* size) {
   const std::string path = FsHelpers::normalisePath(itemHref);
-  return zip.getInflatedFileSize(path.c_str(), size);
+  return ZipFile(filepath).getInflatedFileSize(path.c_str(), size);
 }
 
 int Epub::getSpineItemsCount() const {
@@ -425,6 +435,35 @@ size_t Epub::getBookSize() const {
   return getCumulativeSpineItemSize(getSpineItemsCount() - 1);
 }
 
+int Epub::getSpineIndexForTextReference() const {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    Serial.printf("[%lu] [EBP] getSpineIndexForTextReference called but cache not loaded\n", millis());
+    return 0;
+  }
+  Serial.printf("[%lu] [ERS] Core Metadata: cover(%d)=%s, textReference(%d)=%s\n", millis(),
+                bookMetadataCache->coreMetadata.coverItemHref.size(),
+                bookMetadataCache->coreMetadata.coverItemHref.c_str(),
+                bookMetadataCache->coreMetadata.textReferenceHref.size(),
+                bookMetadataCache->coreMetadata.textReferenceHref.c_str());
+
+  if (bookMetadataCache->coreMetadata.textReferenceHref.empty()) {
+    // there was no textReference in epub, so we return 0 (the first chapter)
+    return 0;
+  }
+
+  // loop through spine items to get the correct index matching the text href
+  for (size_t i = 0; i < getSpineItemsCount(); i++) {
+    if (getSpineItem(i).href == bookMetadataCache->coreMetadata.textReferenceHref) {
+      Serial.printf("[%lu] [ERS] Text reference %s found at index %d\n", millis(),
+                    bookMetadataCache->coreMetadata.textReferenceHref.c_str(), i);
+      return i;
+    }
+  }
+  // This should not happen, as we checked for empty textReferenceHref earlier
+  Serial.printf("[%lu] [EBP] Section not found for text reference\n", millis());
+  return 0;
+}
+
 // Calculate progress in book
 uint8_t Epub::calculateProgress(const int currentSpineIndex, const float currentSpineRead) const {
   const size_t bookSize = getBookSize();

lib/Epub/Epub.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include <Print.h>
+
 #include <memory>
 #include <string>
 #include <unordered_map>
@@ -24,7 +26,6 @@ class Epub {
   bool findContentOpfFile(std::string* contentOpfFile) const;
   bool parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata);
   bool parseTocNcxFile() const;
-  static bool getItemSize(const ZipFile& zip, const std::string& itemHref, size_t* size);
 
  public:
   explicit Epub(std::string filepath, const std::string& cacheDir) : filepath(std::move(filepath)) {
@@ -33,12 +34,13 @@ class Epub {
   }
   ~Epub() = default;
   std::string& getBasePath() { return contentBasePath; }
-  bool load();
+  bool load(bool buildIfMissing = true);
   bool clearCache() const;
   void setupCacheDir() const;
   const std::string& getCachePath() const;
   const std::string& getPath() const;
   const std::string& getTitle() const;
+  const std::string& getAuthor() const;
   std::string getCoverBmpPath() const;
   bool generateCoverBmp() const;
   uint8_t* readItemContentsToBytes(const std::string& itemHref, size_t* size = nullptr,
@@ -52,7 +54,8 @@ class Epub {
   int getSpineIndexForTocIndex(int tocIndex) const;
   int getTocIndexForSpineIndex(int spineIndex) const;
   size_t getCumulativeSpineItemSize(int spineIndex) const;
+  int getSpineIndexForTextReference() const;
 
   size_t getBookSize() const;
-  uint8_t calculateProgress(const int currentSpineIndex, const float currentSpineRead) const;
+  uint8_t calculateProgress(int currentSpineIndex, float currentSpineRead) const;
 };

lib/Epub/Epub/BookMetadataCache.cpp

@@ -1,7 +1,6 @@
 #include "BookMetadataCache.h"
 
 #include <HardwareSerial.h>
-#include <SD.h>
 #include <Serialization.h>
 #include <ZipFile.h>
 
@@ -10,7 +9,7 @@
 #include "FsHelpers.h"
 
 namespace {
-constexpr uint8_t BOOK_CACHE_VERSION = 1;
+constexpr uint8_t BOOK_CACHE_VERSION = 3;
 constexpr char bookBinFile[] = "/book.bin";
 constexpr char tmpSpineBinFile[] = "/spine.bin.tmp";
 constexpr char tmpTocBinFile[] = "/toc.bin.tmp";
@@ -30,7 +29,7 @@ bool BookMetadataCache::beginContentOpfPass() {
   Serial.printf("[%lu] [BMC] Beginning content opf pass\n", millis());
 
   // Open spine file for writing
-  return FsHelpers::openFileForWrite("BMC", cachePath + tmpSpineBinFile, spineFile);
+  return SdMan.openFileForWrite("BMC", cachePath + tmpSpineBinFile, spineFile);
 }
 
 bool BookMetadataCache::endContentOpfPass() {
@@ -42,10 +41,10 @@ bool BookMetadataCache::beginTocPass() {
   Serial.printf("[%lu] [BMC] Beginning toc pass\n", millis());
 
   // Open spine file for reading
-  if (!FsHelpers::openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+  if (!SdMan.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
     return false;
   }
-  if (!FsHelpers::openFileForWrite("BMC", cachePath + tmpTocBinFile, tocFile)) {
+  if (!SdMan.openFileForWrite("BMC", cachePath + tmpTocBinFile, tocFile)) {
     spineFile.close();
     return false;
   }
@@ -71,27 +70,27 @@ bool BookMetadataCache::endWrite() {
 
 bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMetadata& metadata) {
   // Open all three files, writing to meta, reading from spine and toc
-  if (!FsHelpers::openFileForWrite("BMC", cachePath + bookBinFile, bookFile)) {
+  if (!SdMan.openFileForWrite("BMC", cachePath + bookBinFile, bookFile)) {
     return false;
   }
 
-  if (!FsHelpers::openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+  if (!SdMan.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
     bookFile.close();
     return false;
   }
 
-  if (!FsHelpers::openFileForRead("BMC", cachePath + tmpTocBinFile, tocFile)) {
+  if (!SdMan.openFileForRead("BMC", cachePath + tmpTocBinFile, tocFile)) {
     bookFile.close();
     spineFile.close();
     return false;
   }
 
-  constexpr size_t headerASize =
-      sizeof(BOOK_CACHE_VERSION) + /* LUT Offset */ sizeof(size_t) + sizeof(spineCount) + sizeof(tocCount);
-  const size_t metadataSize =
-      metadata.title.size() + metadata.author.size() + metadata.coverItemHref.size() + sizeof(uint32_t) * 3;
-  const size_t lutSize = sizeof(size_t) * spineCount + sizeof(size_t) * tocCount;
-  const size_t lutOffset = headerASize + metadataSize;
+  constexpr uint32_t headerASize =
+      sizeof(BOOK_CACHE_VERSION) + /* LUT Offset */ sizeof(uint32_t) + sizeof(spineCount) + sizeof(tocCount);
+  const uint32_t metadataSize = metadata.title.size() + metadata.author.size() + metadata.coverItemHref.size() +
+                                metadata.textReferenceHref.size() + sizeof(uint32_t) * 4;
+  const uint32_t lutSize = sizeof(uint32_t) * spineCount + sizeof(uint32_t) * tocCount;
+  const uint32_t lutOffset = headerASize + metadataSize;
 
   // Header A
   serialization::writePod(bookFile, BOOK_CACHE_VERSION);
@@ -102,11 +101,12 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
   serialization::writeString(bookFile, metadata.title);
   serialization::writeString(bookFile, metadata.author);
   serialization::writeString(bookFile, metadata.coverItemHref);
+  serialization::writeString(bookFile, metadata.textReferenceHref);
 
   // Loop through spine entries, writing LUT positions
   spineFile.seek(0);
   for (int i = 0; i < spineCount; i++) {
-    auto pos = spineFile.position();
+    uint32_t pos = spineFile.position();
     auto spineEntry = readSpineEntry(spineFile);
     serialization::writePod(bookFile, pos + lutOffset + lutSize);
   }
@@ -114,17 +114,37 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
   // Loop through toc entries, writing LUT positions
   tocFile.seek(0);
   for (int i = 0; i < tocCount; i++) {
-    auto pos = tocFile.position();
+    uint32_t pos = tocFile.position();
     auto tocEntry = readTocEntry(tocFile);
-    serialization::writePod(bookFile, pos + lutOffset + lutSize + spineFile.position());
+    serialization::writePod(bookFile, pos + lutOffset + lutSize + static_cast<uint32_t>(spineFile.position()));
   }
 
   // LUTs complete
   // Loop through spines from spine file matching up TOC indexes, calculating cumulative size and writing to book.bin
 
-  const ZipFile zip("/sd" + epubPath);
-  size_t cumSize = 0;
+  ZipFile zip(epubPath);
+  // Pre-open zip file to speed up size calculations
+  if (!zip.open()) {
+    Serial.printf("[%lu] [BMC] Could not open EPUB zip for size calculations\n", millis());
+    bookFile.close();
+    spineFile.close();
+    tocFile.close();
+    return false;
+  }
+  // TODO: For large ZIPs loading the all localHeaderOffsets will crash.
+  //       However not having them loaded is extremely slow. Need a better solution here.
+  //       Perhaps only a cache of spine items or a better way to speedup lookups?
+  if (!zip.loadAllFileStatSlims()) {
+    Serial.printf("[%lu] [BMC] Could not load zip local header offsets for size calculations\n", millis());
+    bookFile.close();
+    spineFile.close();
+    tocFile.close();
+    zip.close();
+    return false;
+  }
+  uint32_t cumSize = 0;
   spineFile.seek(0);
+  int lastSpineTocIndex = -1;
   for (int i = 0; i < spineCount; i++) {
     auto spineEntry = readSpineEntry(spineFile);
 
@@ -140,9 +160,12 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
     // Not a huge deal if we don't fine a TOC entry for the spine entry, this is expected behaviour for EPUBs
     // Logging here is for debugging
     if (spineEntry.tocIndex == -1) {
-      Serial.printf("[%lu] [BMC] Warning: Could not find TOC entry for spine item %d: %s\n", millis(), i,
-                    spineEntry.href.c_str());
+      Serial.printf(
+          "[%lu] [BMC] Warning: Could not find TOC entry for spine item %d: %s, using title from last section\n",
+          millis(), i, spineEntry.href.c_str());
+      spineEntry.tocIndex = lastSpineTocIndex;
     }
+    lastSpineTocIndex = spineEntry.tocIndex;
 
     // Calculate size for cumulative size
     size_t itemSize = 0;
@@ -157,6 +180,8 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
     // Write out spine data to book.bin
     writeSpineEntry(bookFile, spineEntry);
   }
+  // Close opened zip file
+  zip.close();
 
   // Loop through toc entries from toc file writing to book.bin
   tocFile.seek(0);
@@ -174,25 +199,25 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
 }
 
 bool BookMetadataCache::cleanupTmpFiles() const {
-  if (SD.exists((cachePath + tmpSpineBinFile).c_str())) {
-    SD.remove((cachePath + tmpSpineBinFile).c_str());
+  if (SdMan.exists((cachePath + tmpSpineBinFile).c_str())) {
+    SdMan.remove((cachePath + tmpSpineBinFile).c_str());
   }
-  if (SD.exists((cachePath + tmpTocBinFile).c_str())) {
-    SD.remove((cachePath + tmpTocBinFile).c_str());
+  if (SdMan.exists((cachePath + tmpTocBinFile).c_str())) {
+    SdMan.remove((cachePath + tmpTocBinFile).c_str());
   }
   return true;
 }
 
-size_t BookMetadataCache::writeSpineEntry(File& file, const SpineEntry& entry) const {
-  const auto pos = file.position();
+uint32_t BookMetadataCache::writeSpineEntry(FsFile& file, const SpineEntry& entry) const {
+  const uint32_t pos = file.position();
   serialization::writeString(file, entry.href);
   serialization::writePod(file, entry.cumulativeSize);
   serialization::writePod(file, entry.tocIndex);
   return pos;
 }
 
-size_t BookMetadataCache::writeTocEntry(File& file, const TocEntry& entry) const {
-  const auto pos = file.position();
+uint32_t BookMetadataCache::writeTocEntry(FsFile& file, const TocEntry& entry) const {
+  const uint32_t pos = file.position();
   serialization::writeString(file, entry.title);
   serialization::writeString(file, entry.href);
   serialization::writeString(file, entry.anchor);
@@ -223,6 +248,8 @@ void BookMetadataCache::createTocEntry(const std::string& title, const std::stri
 
   int spineIndex = -1;
   // find spine index
+  // TODO: This lookup is slow as need to scan through all items each time. We can't hold it all in memory due to size.
+  //       But perhaps we can load just the hrefs in a vector/list to do an index lookup?
   spineFile.seek(0);
   for (int i = 0; i < spineCount; i++) {
     auto spineEntry = readSpineEntry(spineFile);
@@ -244,7 +271,7 @@ void BookMetadataCache::createTocEntry(const std::string& title, const std::stri
 /* ============= READING / LOADING FUNCTIONS ================ */
 
 bool BookMetadataCache::load() {
-  if (!FsHelpers::openFileForRead("BMC", cachePath + bookBinFile, bookFile)) {
+  if (!SdMan.openFileForRead("BMC", cachePath + bookBinFile, bookFile)) {
     return false;
   }
 
@@ -263,6 +290,7 @@ bool BookMetadataCache::load() {
   serialization::readString(bookFile, coreMetadata.title);
   serialization::readString(bookFile, coreMetadata.author);
   serialization::readString(bookFile, coreMetadata.coverItemHref);
+  serialization::readString(bookFile, coreMetadata.textReferenceHref);
 
   loaded = true;
   Serial.printf("[%lu] [BMC] Loaded cache data: %d spine, %d TOC entries\n", millis(), spineCount, tocCount);
@@ -281,8 +309,8 @@ BookMetadataCache::SpineEntry BookMetadataCache::getSpineEntry(const int index)
   }
 
   // Seek to spine LUT item, read from LUT and get out data
-  bookFile.seek(lutOffset + sizeof(size_t) * index);
-  size_t spineEntryPos;
+  bookFile.seek(lutOffset + sizeof(uint32_t) * index);
+  uint32_t spineEntryPos;
   serialization::readPod(bookFile, spineEntryPos);
   bookFile.seek(spineEntryPos);
   return readSpineEntry(bookFile);
@@ -300,14 +328,14 @@ BookMetadataCache::TocEntry BookMetadataCache::getTocEntry(const int index) {
   }
 
   // Seek to TOC LUT item, read from LUT and get out data
-  bookFile.seek(lutOffset + sizeof(size_t) * spineCount + sizeof(size_t) * index);
-  size_t tocEntryPos;
+  bookFile.seek(lutOffset + sizeof(uint32_t) * spineCount + sizeof(uint32_t) * index);
+  uint32_t tocEntryPos;
   serialization::readPod(bookFile, tocEntryPos);
   bookFile.seek(tocEntryPos);
   return readTocEntry(bookFile);
 }
 
-BookMetadataCache::SpineEntry BookMetadataCache::readSpineEntry(File& file) const {
+BookMetadataCache::SpineEntry BookMetadataCache::readSpineEntry(FsFile& file) const {
   SpineEntry entry;
   serialization::readString(file, entry.href);
   serialization::readPod(file, entry.cumulativeSize);
@@ -315,7 +343,7 @@ BookMetadataCache::SpineEntry BookMetadataCache::readSpineEntry(File& file) cons
   return entry;
 }
 
-BookMetadataCache::TocEntry BookMetadataCache::readTocEntry(File& file) const {
+BookMetadataCache::TocEntry BookMetadataCache::readTocEntry(FsFile& file) const {
   TocEntry entry;
   serialization::readString(file, entry.title);
   serialization::readString(file, entry.href);

lib/Epub/Epub/BookMetadataCache.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <SD.h>
+#include <SDCardManager.h>
 
 #include <string>
 
@@ -10,6 +10,7 @@ class BookMetadataCache {
     std::string title;
     std::string author;
     std::string coverItemHref;
+    std::string textReferenceHref;
   };
 
   struct SpineEntry {
@@ -46,15 +47,15 @@ class BookMetadataCache {
   bool loaded;
   bool buildMode;
 
-  File bookFile;
+  FsFile bookFile;
   // Temp file handles during build
-  File spineFile;
-  File tocFile;
+  FsFile spineFile;
+  FsFile tocFile;
 
-  size_t writeSpineEntry(File& file, const SpineEntry& entry) const;
-  size_t writeTocEntry(File& file, const TocEntry& entry) const;
-  SpineEntry readSpineEntry(File& file) const;
-  TocEntry readTocEntry(File& file) const;
+  uint32_t writeSpineEntry(FsFile& file, const SpineEntry& entry) const;
+  uint32_t writeTocEntry(FsFile& file, const TocEntry& entry) const;
+  SpineEntry readSpineEntry(FsFile& file) const;
+  TocEntry readTocEntry(FsFile& file) const;
 
  public:
   BookMetadata coreMetadata;

lib/Epub/Epub/FsHelpers.cpp

@@ -1,92 +0,0 @@
-#include "FsHelpers.h"
-
-#include <SD.h>
-
-#include <vector>
-
-bool FsHelpers::openFileForRead(const char* moduleName, const std::string& path, File& file) {
-  file = SD.open(path.c_str(), FILE_READ);
-  if (!file) {
-    Serial.printf("[%lu] [%s] Failed to open file for reading: %s\n", millis(), moduleName, path.c_str());
-    return false;
-  }
-  return true;
-}
-
-bool FsHelpers::openFileForWrite(const char* moduleName, const std::string& path, File& file) {
-  file = SD.open(path.c_str(), FILE_WRITE, true);
-  if (!file) {
-    Serial.printf("[%lu] [%s] Failed to open file for writing: %s\n", millis(), moduleName, path.c_str());
-    return false;
-  }
-  return true;
-}
-
-bool FsHelpers::removeDir(const char* path) {
-  // 1. Open the directory
-  File dir = SD.open(path);
-  if (!dir) {
-    return false;
-  }
-  if (!dir.isDirectory()) {
-    return false;
-  }
-
-  File file = dir.openNextFile();
-  while (file) {
-    String filePath = path;
-    if (!filePath.endsWith("/")) {
-      filePath += "/";
-    }
-    filePath += file.name();
-
-    if (file.isDirectory()) {
-      if (!removeDir(filePath.c_str())) {
-        return false;
-      }
-    } else {
-      if (!SD.remove(filePath.c_str())) {
-        return false;
-      }
-    }
-    file = dir.openNextFile();
-  }
-
-  return SD.rmdir(path);
-}
-
-std::string FsHelpers::normalisePath(const std::string& path) {
-  std::vector<std::string> components;
-  std::string component;
-
-  for (const auto c : path) {
-    if (c == '/') {
-      if (!component.empty()) {
-        if (component == "..") {
-          if (!components.empty()) {
-            components.pop_back();
-          }
-        } else {
-          components.push_back(component);
-        }
-        component.clear();
-      }
-    } else {
-      component += c;
-    }
-  }
-
-  if (!component.empty()) {
-    components.push_back(component);
-  }
-
-  std::string result;
-  for (const auto& c : components) {
-    if (!result.empty()) {
-      result += "/";
-    }
-    result += c;
-  }
-
-  return result;
-}

lib/Epub/Epub/FsHelpers.h

@@ -1,12 +0,0 @@
-#pragma once
-#include <FS.h>
-
-#include <string>
-
-class FsHelpers {
- public:
-  static bool openFileForRead(const char* moduleName, const std::string& path, File& file);
-  static bool openFileForWrite(const char* moduleName, const std::string& path, File& file);
-  static bool removeDir(const char* path);
-  static std::string normalisePath(const std::string& path);
-};

lib/Epub/Epub/Page.cpp

@@ -3,23 +3,19 @@
 #include <HardwareSerial.h>
 #include <Serialization.h>
 
-namespace {
-constexpr uint8_t PAGE_FILE_VERSION = 3;
-}
-
 void PageLine::render(GfxRenderer& renderer, const int fontId, const int xOffset, const int yOffset) {
   block->render(renderer, fontId, xPos + xOffset, yPos + yOffset);
 }
 
-void PageLine::serialize(File& file) {
+bool PageLine::serialize(FsFile& file) {
   serialization::writePod(file, xPos);
   serialization::writePod(file, yPos);
 
   // serialize TextBlock pointed to by PageLine
-  block->serialize(file);
+  return block->serialize(file);
 }
 
-std::unique_ptr<PageLine> PageLine::deserialize(File& file) {
+std::unique_ptr<PageLine> PageLine::deserialize(FsFile& file) {
   int16_t xPos;
   int16_t yPos;
   serialization::readPod(file, xPos);
@@ -35,27 +31,22 @@ void Page::render(GfxRenderer& renderer, const int fontId, const int xOffset, co
   }
 }
 
-void Page::serialize(File& file) const {
-  serialization::writePod(file, PAGE_FILE_VERSION);
-
+bool Page::serialize(FsFile& file) const {
   const uint32_t count = elements.size();
   serialization::writePod(file, count);
 
   for (const auto& el : elements) {
     // Only PageLine exists currently
     serialization::writePod(file, static_cast<uint8_t>(TAG_PageLine));
-    el->serialize(file);
+    if (!el->serialize(file)) {
+      return false;
+    }
   }
+
+  return true;
 }
 
-std::unique_ptr<Page> Page::deserialize(File& file) {
-  uint8_t version;
-  serialization::readPod(file, version);
-  if (version != PAGE_FILE_VERSION) {
-    Serial.printf("[%lu] [PGE] Deserialization failed: Unknown version %u\n", millis(), version);
-    return nullptr;
-  }
-
+std::unique_ptr<Page> Page::deserialize(FsFile& file) {
   auto page = std::unique_ptr<Page>(new Page());
 
   uint32_t count;

lib/Epub/Epub/Page.h

@@ -1,5 +1,5 @@
 #pragma once
-#include <FS.h>
+#include <SdFat.h>
 
 #include <utility>
 #include <vector>
@@ -18,7 +18,7 @@ class PageElement {
   explicit PageElement(const int16_t xPos, const int16_t yPos) : xPos(xPos), yPos(yPos) {}
   virtual ~PageElement() = default;
   virtual void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) = 0;
-  virtual void serialize(File& file) = 0;
+  virtual bool serialize(FsFile& file) = 0;
 };
 
 // a line from a block element
@@ -29,8 +29,8 @@ class PageLine final : public PageElement {
   PageLine(std::shared_ptr<TextBlock> block, const int16_t xPos, const int16_t yPos)
       : PageElement(xPos, yPos), block(std::move(block)) {}
   void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) override;
-  void serialize(File& file) override;
-  static std::unique_ptr<PageLine> deserialize(File& file);
+  bool serialize(FsFile& file) override;
+  static std::unique_ptr<PageLine> deserialize(FsFile& file);
 };
 
 class Page {
@@ -38,6 +38,6 @@ class Page {
   // the list of block index and line numbers on this page
   std::vector<std::shared_ptr<PageElement>> elements;
   void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) const;
-  void serialize(File& file) const;
-  static std::unique_ptr<Page> deserialize(File& file);
+  bool serialize(FsFile& file) const;
+  static std::unique_ptr<Page> deserialize(FsFile& file);
 };

lib/Epub/Epub/Section.cpp

@@ -1,61 +1,66 @@
 #include "Section.h"
 
-#include <FsHelpers.h>
-#include <SD.h>
+#include <SDCardManager.h>
 #include <Serialization.h>
 
 #include "Page.h"
 #include "parsers/ChapterHtmlSlimParser.h"
 
 namespace {
-constexpr uint8_t SECTION_FILE_VERSION = 6;
+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);
 }  // namespace
 
-void Section::onPageComplete(std::unique_ptr<Page> page) {
-  const auto filePath = cachePath + "/page_" + std::to_string(pageCount) + ".bin";
-
-  File outputFile;
-  if (!FsHelpers::openFileForWrite("SCT", filePath, outputFile)) {
-    return;
+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);
+    return 0;
   }
-  page->serialize(outputFile);
-  outputFile.close();
 
+  const uint32_t position = file.position();
+  if (!page->serialize(file)) {
+    Serial.printf("[%lu] [SCT] Failed to serialize page %d\n", millis(), pageCount);
+    return 0;
+  }
   Serial.printf("[%lu] [SCT] Page %d processed\n", millis(), pageCount);
 
   pageCount++;
+  return position;
 }
 
-void Section::writeCacheMetadata(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
-                                 const int viewportWidth, const int viewportHeight) const {
-  File outputFile;
-  if (!FsHelpers::openFileForWrite("SCT", cachePath + "/section.bin", outputFile)) {
+void Section::writeSectionFileHeader(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
+                                     const int viewportWidth, const int viewportHeight) {
+  if (!file) {
+    Serial.printf("[%lu] [SCT] File not open for writing header\n", millis());
     return;
   }
-  serialization::writePod(outputFile, SECTION_FILE_VERSION);
-  serialization::writePod(outputFile, fontId);
-  serialization::writePod(outputFile, lineCompression);
-  serialization::writePod(outputFile, extraParagraphSpacing);
-  serialization::writePod(outputFile, viewportWidth);
-  serialization::writePod(outputFile, viewportHeight);
-  serialization::writePod(outputFile, pageCount);
-  outputFile.close();
+  static_assert(HEADER_SIZE == sizeof(SECTION_FILE_VERSION) + sizeof(fontId) + sizeof(lineCompression) +
+                                   sizeof(extraParagraphSpacing) + 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, viewportWidth);
+  serialization::writePod(file, viewportHeight);
+  serialization::writePod(file, pageCount);  // Placeholder for page count (will be initially 0 when written)
+  serialization::writePod(file, static_cast<uint32_t>(0));  // Placeholder for LUT offset
 }
 
-bool Section::loadCacheMetadata(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
-                                const int viewportWidth, const int viewportHeight) {
-  const auto sectionFilePath = cachePath + "/section.bin";
-  File inputFile;
-  if (!FsHelpers::openFileForRead("SCT", sectionFilePath, inputFile)) {
+bool Section::loadSectionFile(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
+                              const int viewportWidth, const int viewportHeight) {
+  if (!SdMan.openFileForRead("SCT", filePath, file)) {
     return false;
   }
 
   // Match parameters
   {
     uint8_t version;
-    serialization::readPod(inputFile, version);
+    serialization::readPod(file, version);
     if (version != SECTION_FILE_VERSION) {
-      inputFile.close();
+      file.close();
       Serial.printf("[%lu] [SCT] Deserialization failed: Unknown version %u\n", millis(), version);
       clearCache();
       return false;
@@ -64,41 +69,36 @@ bool Section::loadCacheMetadata(const int fontId, const float lineCompression, c
     int fileFontId, fileViewportWidth, fileViewportHeight;
     float fileLineCompression;
     bool fileExtraParagraphSpacing;
-    serialization::readPod(inputFile, fileFontId);
-    serialization::readPod(inputFile, fileLineCompression);
-    serialization::readPod(inputFile, fileExtraParagraphSpacing);
-    serialization::readPod(inputFile, fileViewportWidth);
-    serialization::readPod(inputFile, fileViewportHeight);
+    serialization::readPod(file, fileFontId);
+    serialization::readPod(file, fileLineCompression);
+    serialization::readPod(file, fileExtraParagraphSpacing);
+    serialization::readPod(file, fileViewportWidth);
+    serialization::readPod(file, fileViewportHeight);
 
     if (fontId != fileFontId || lineCompression != fileLineCompression ||
         extraParagraphSpacing != fileExtraParagraphSpacing || viewportWidth != fileViewportWidth ||
         viewportHeight != fileViewportHeight) {
-      inputFile.close();
+      file.close();
       Serial.printf("[%lu] [SCT] Deserialization failed: Parameters do not match\n", millis());
       clearCache();
       return false;
     }
   }
 
-  serialization::readPod(inputFile, pageCount);
-  inputFile.close();
+  serialization::readPod(file, pageCount);
+  file.close();
   Serial.printf("[%lu] [SCT] Deserialization succeeded: %d pages\n", millis(), pageCount);
   return true;
 }
 
-void Section::setupCacheDir() const {
-  epub->setupCacheDir();
-  SD.mkdir(cachePath.c_str());
-}
-
 // Your updated class method (assuming you are using the 'SD' object, which is a wrapper for a specific filesystem)
 bool Section::clearCache() const {
-  if (!SD.exists(cachePath.c_str())) {
+  if (!SdMan.exists(filePath.c_str())) {
     Serial.printf("[%lu] [SCT] Cache does not exist, no action needed\n", millis());
     return true;
   }
 
-  if (!FsHelpers::removeDir(cachePath.c_str())) {
+  if (!SdMan.remove(filePath.c_str())) {
     Serial.printf("[%lu] [SCT] Failed to clear cache\n", millis());
     return false;
   }
@@ -107,17 +107,23 @@ bool Section::clearCache() const {
   return true;
 }
 
-bool Section::persistPageDataToSD(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
-                                  const int viewportWidth, const int viewportHeight,
-                                  const std::function<void()>& progressSetupFn,
-                                  const std::function<void(int)>& progressFn) {
-  constexpr size_t MIN_SIZE_FOR_PROGRESS = 50 * 1024;  // 50KB
+bool Section::createSectionFile(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
+                                const int viewportWidth, const int 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;
   const auto tmpHtmlPath = epub->getCachePath() + "/.tmp_" + std::to_string(spineIndex) + ".html";
 
+  // Create cache directory if it doesn't exist
+  {
+    const auto sectionsDir = epub->getCachePath() + "/sections";
+    SdMan.mkdir(sectionsDir.c_str());
+  }
+
   // Retry logic for SD card timing issues
   bool success = false;
-  size_t fileSize = 0;
+  uint32_t fileSize = 0;
   for (int attempt = 0; attempt < 3 && !success; attempt++) {
     if (attempt > 0) {
       Serial.printf("[%lu] [SCT] Retrying stream (attempt %d)...\n", millis(), attempt + 1);
@@ -125,12 +131,12 @@ bool Section::persistPageDataToSD(const int fontId, const float lineCompression,
     }
 
     // Remove any incomplete file from previous attempt before retrying
-    if (SD.exists(tmpHtmlPath.c_str())) {
-      SD.remove(tmpHtmlPath.c_str());
+    if (SdMan.exists(tmpHtmlPath.c_str())) {
+      SdMan.remove(tmpHtmlPath.c_str());
     }
 
-    File tmpHtml;
-    if (!FsHelpers::openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) {
+    FsFile tmpHtml;
+    if (!SdMan.openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) {
       continue;
     }
     success = epub->readItemContentsToStream(localPath, tmpHtml, 1024);
@@ -138,8 +144,8 @@ bool Section::persistPageDataToSD(const int fontId, const float lineCompression,
     tmpHtml.close();
 
     // If streaming failed, remove the incomplete file immediately
-    if (!success && SD.exists(tmpHtmlPath.c_str())) {
-      SD.remove(tmpHtmlPath.c_str());
+    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());
     }
   }
@@ -156,30 +162,66 @@ bool Section::persistPageDataToSD(const int fontId, const float lineCompression,
     progressSetupFn();
   }
 
+  if (!SdMan.openFileForWrite("SCT", filePath, file)) {
+    return false;
+  }
+  writeSectionFileHeader(fontId, lineCompression, extraParagraphSpacing, viewportWidth, viewportHeight);
+  std::vector<uint32_t> lut = {};
+
   ChapterHtmlSlimParser visitor(
       tmpHtmlPath, renderer, fontId, lineCompression, extraParagraphSpacing, viewportWidth, viewportHeight,
-      [this](std::unique_ptr<Page> page) { this->onPageComplete(std::move(page)); }, progressFn);
+      [this, &lut](std::unique_ptr<Page> page) { lut.emplace_back(this->onPageComplete(std::move(page))); },
+      progressFn);
   success = visitor.parseAndBuildPages();
 
-  SD.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();
+    SdMan.remove(filePath.c_str());
     return false;
   }
 
-  writeCacheMetadata(fontId, lineCompression, extraParagraphSpacing, viewportWidth, viewportHeight);
+  const uint32_t lutOffset = file.position();
+  bool hasFailedLutRecords = false;
+  // Write LUT
+  for (const uint32_t& pos : lut) {
+    if (pos == 0) {
+      hasFailedLutRecords = true;
+      break;
+    }
+    serialization::writePod(file, pos);
+  }
 
+  if (hasFailedLutRecords) {
+    Serial.printf("[%lu] [SCT] Failed to write LUT due to invalid page positions\n", millis());
+    file.close();
+    SdMan.remove(filePath.c_str());
+    return false;
+  }
+
+  // Go back and write LUT offset
+  file.seek(HEADER_SIZE - sizeof(uint32_t) - sizeof(pageCount));
+  serialization::writePod(file, pageCount);
+  serialization::writePod(file, lutOffset);
+  file.close();
   return true;
 }
 
-std::unique_ptr<Page> Section::loadPageFromSD() const {
-  const auto filePath = cachePath + "/page_" + std::to_string(currentPage) + ".bin";
-
-  File inputFile;
-  if (!FsHelpers::openFileForRead("SCT", filePath, inputFile)) {
+std::unique_ptr<Page> Section::loadPageFromSectionFile() {
+  if (!SdMan.openFileForRead("SCT", filePath, file)) {
     return nullptr;
   }
-  auto page = Page::deserialize(inputFile);
-  inputFile.close();
+
+  file.seek(HEADER_SIZE - sizeof(uint32_t));
+  uint32_t lutOffset;
+  serialization::readPod(file, lutOffset);
+  file.seek(lutOffset + sizeof(uint32_t) * currentPage);
+  uint32_t pagePos;
+  serialization::readPod(file, pagePos);
+  file.seek(pagePos);
+
+  auto page = Page::deserialize(file);
+  file.close();
   return page;
 }

lib/Epub/Epub/Section.h

@@ -11,11 +11,12 @@ class Section {
   std::shared_ptr<Epub> epub;
   const int spineIndex;
   GfxRenderer& renderer;
-  std::string cachePath;
+  std::string filePath;
+  FsFile file;
 
-  void writeCacheMetadata(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
-                          int viewportHeight) const;
-  void onPageComplete(std::unique_ptr<Page> page);
+  void writeSectionFileHeader(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
+                              int viewportHeight);
+  uint32_t onPageComplete(std::unique_ptr<Page> page);
 
  public:
   int pageCount = 0;
@@ -25,14 +26,13 @@ class Section {
       : epub(epub),
         spineIndex(spineIndex),
         renderer(renderer),
-        cachePath(epub->getCachePath() + "/" + std::to_string(spineIndex)) {}
+        filePath(epub->getCachePath() + "/sections/" + std::to_string(spineIndex) + ".bin") {}
   ~Section() = default;
-  bool loadCacheMetadata(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
-                         int viewportHeight);
-  void setupCacheDir() const;
+  bool loadSectionFile(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
+                       int viewportHeight);
   bool clearCache() const;
-  bool persistPageDataToSD(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
-                           int viewportHeight, const std::function<void()>& progressSetupFn = nullptr,
-                           const std::function<void(int)>& progressFn = nullptr);
-  std::unique_ptr<Page> loadPageFromSD() const;
+  bool createSectionFile(int fontId, float lineCompression, bool extraParagraphSpacing, int viewportWidth,
+                         int 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

@@ -24,34 +24,33 @@ void TextBlock::render(const GfxRenderer& renderer, const int fontId, const int
   }
 }
 
-void TextBlock::serialize(File& file) const {
-  // words
-  const uint32_t wc = words.size();
-  serialization::writePod(file, wc);
+bool TextBlock::serialize(FsFile& file) const {
+  if (words.size() != wordXpos.size() || words.size() != wordStyles.size()) {
+    Serial.printf("[%lu] [TXB] Serialization failed: size mismatch (words=%u, xpos=%u, styles=%u)\n", millis(),
+                  words.size(), wordXpos.size(), wordStyles.size());
+    return false;
+  }
+
+  // Word data
+  serialization::writePod(file, static_cast<uint32_t>(words.size()));
   for (const auto& w : words) serialization::writeString(file, w);
-
-  // wordXpos
-  const uint32_t xc = wordXpos.size();
-  serialization::writePod(file, xc);
   for (auto x : wordXpos) serialization::writePod(file, x);
-
-  // wordStyles
-  const uint32_t sc = wordStyles.size();
-  serialization::writePod(file, sc);
   for (auto s : wordStyles) serialization::writePod(file, s);
 
-  // style
+  // Block style
   serialization::writePod(file, style);
+
+  return true;
 }
 
-std::unique_ptr<TextBlock> TextBlock::deserialize(File& file) {
-  uint32_t wc, xc, sc;
+std::unique_ptr<TextBlock> TextBlock::deserialize(FsFile& file) {
+  uint32_t wc;
   std::list<std::string> words;
   std::list<uint16_t> wordXpos;
   std::list<EpdFontStyle> wordStyles;
   BLOCK_STYLE style;
 
-  // words
+  // Word count
   serialization::readPod(file, wc);
 
   // Sanity check: prevent allocation of unreasonably large lists (max 10000 words per block)
@@ -60,27 +59,15 @@ std::unique_ptr<TextBlock> TextBlock::deserialize(File& file) {
     return nullptr;
   }
 
+  // Word data
   words.resize(wc);
+  wordXpos.resize(wc);
+  wordStyles.resize(wc);
   for (auto& w : words) serialization::readString(file, w);
-
-  // wordXpos
-  serialization::readPod(file, xc);
-  wordXpos.resize(xc);
   for (auto& x : wordXpos) serialization::readPod(file, x);
-
-  // wordStyles
-  serialization::readPod(file, sc);
-  wordStyles.resize(sc);
   for (auto& s : wordStyles) serialization::readPod(file, s);
 
-  // Validate data consistency: all three lists must have the same size
-  if (wc != xc || wc != sc) {
-    Serial.printf("[%lu] [TXB] Deserialization failed: size mismatch (words=%u, xpos=%u, styles=%u)\n", millis(), wc,
-                  xc, sc);
-    return nullptr;
-  }
-
-  // style
+  // Block style
   serialization::readPod(file, style);
 
   return std::unique_ptr<TextBlock>(new TextBlock(std::move(words), std::move(wordXpos), std::move(wordStyles), style));

lib/Epub/Epub/blocks/TextBlock.h

@@ -1,6 +1,6 @@
 #pragma once
 #include <EpdFontFamily.h>
-#include <FS.h>
+#include <SdFat.h>
 
 #include <list>
 #include <memory>
@@ -36,6 +36,6 @@ class TextBlock final : public Block {
   // given a renderer works out where to break the words into lines
   void render(const GfxRenderer& renderer, int fontId, int x, int y) const;
   BlockType getType() override { return TEXT_BLOCK; }
-  void serialize(File& file) const;
-  static std::unique_ptr<TextBlock> deserialize(File& file);
+  bool serialize(FsFile& file) const;
+  static std::unique_ptr<TextBlock> deserialize(FsFile& file);
 };

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -1,8 +1,8 @@
 #include "ChapterHtmlSlimParser.h"
 
-#include <FsHelpers.h>
 #include <GfxRenderer.h>
 #include <HardwareSerial.h>
+#include <SDCardManager.h>
 #include <expat.h>
 
 #include "../Page.h"
@@ -57,7 +57,6 @@ void ChapterHtmlSlimParser::startNewTextBlock(const TextBlock::BLOCK_STYLE style
 
 void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char* name, const XML_Char** atts) {
   auto* self = static_cast<ChapterHtmlSlimParser*>(userData);
-  (void)atts;
 
   // Middle of skip
   if (self->skipUntilDepth < self->depth) {
@@ -93,7 +92,7 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
 
   if (matches(name, HEADER_TAGS, NUM_HEADER_TAGS)) {
     self->startNewTextBlock(TextBlock::CENTER_ALIGN);
-    self->boldUntilDepth = min(self->boldUntilDepth, self->depth);
+    self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
   } else if (matches(name, BLOCK_TAGS, NUM_BLOCK_TAGS)) {
     if (strcmp(name, "br") == 0) {
       self->startNewTextBlock(self->currentTextBlock->getStyle());
@@ -101,9 +100,9 @@ void XMLCALL ChapterHtmlSlimParser::startElement(void* userData, const XML_Char*
       self->startNewTextBlock(TextBlock::JUSTIFIED);
     }
   } else if (matches(name, BOLD_TAGS, NUM_BOLD_TAGS)) {
-    self->boldUntilDepth = min(self->boldUntilDepth, self->depth);
+    self->boldUntilDepth = std::min(self->boldUntilDepth, self->depth);
   } else if (matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS)) {
-    self->italicUntilDepth = min(self->italicUntilDepth, self->depth);
+    self->italicUntilDepth = std::min(self->italicUntilDepth, self->depth);
   }
 
   self->depth += 1;
@@ -162,7 +161,6 @@ 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);
-  (void)name;
 
   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.
@@ -218,8 +216,8 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
     return false;
   }
 
-  File file;
-  if (!FsHelpers::openFileForRead("EHP", filepath, file)) {
+  FsFile file;
+  if (!SdMan.openFileForRead("EHP", filepath, file)) {
     XML_ParserFree(parser);
     return false;
   }
@@ -245,9 +243,9 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
       return false;
     }
 
-    const size_t len = file.read(static_cast<uint8_t*>(buf), 1024);
+    const size_t len = file.read(buf, 1024);
 
-    if (len == 0) {
+    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_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks