Cut release 0.9.0

## Summary

* Use single unified cache file for book spine, table of contents, and
core metadata (title, author, cover image)
* Use new temp item store file in OPF parsing to store items to be
rescaned when parsing spine
  * This avoids us holding these items in memory
* Use new toc.bin.tmp and spine.bin.tmp to build out partial toc / spine
data as part of parsing content.opf and the NCX file
  * These files are re-read multiple times to ultimately build book.bin

## Additional Context

* Spec for file format included below as an image
* This should help with:
  * #10 
  * #60 
  * #99

.clangd

@@ -0,0 +1,2 @@
+CompileFlags:
+    Add: [-std=c++2a]

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: [daveallie]
+ko_fi: daveallie

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,54 @@
+name: Bug Report
+description: Report an issue or unexpected behavior
+title: "Short, descriptive title of the issue"
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report this bug! Please fill out the details below.
+
+  - type: input
+    id: version
+    attributes:
+      label: Affected Version
+      description: What version of the project/library are you using? (e.g., v1.2.3, master branch commit SHA)
+      placeholder: Ex. v1.2.3
+    validations:
+      required: true
+
+  - type: textarea
+    id: bug-description
+    attributes:
+      label: Describe the Bug
+      description: A clear and concise description of what the bug is.
+      placeholder:
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Clearly list the steps necessary to reproduce the unexpected behavior.
+      placeholder: |
+        1. Go to '...'
+        2. Select '...'
+        3. Crash
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: A clear and concise description of what you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Log Output/Screenshots
+      description: If applicable, error messages, or log output to help explain your problem. You can drag and drop images here.
+      render: shell

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## 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).

.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+'on':
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.platformio/.cache
+          key: ${{ runner.os }}-pio
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install PlatformIO Core
+        run: pip install --upgrade platformio
+
+      - name: Install clang-format-21
+        run: |
+          wget https://apt.llvm.org/llvm.sh
+          chmod +x llvm.sh
+          sudo ./llvm.sh 21
+          sudo apt-get update
+          sudo apt-get install -y clang-format-21
+
+      - name: Run cppcheck
+        run: pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
+
+      - name: Run clang-format
+        run: PATH="/usr/lib/llvm-21/bin:$PATH" ./bin/clang-format-fix && git diff --exit-code || (echo "Please run 'bin/clang-format-fix' to fix formatting issues" && exit 1)
+
+      - name: Build CrossPoint
+        run: pio run

.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Compile Release
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  build-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+      - uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cache/pip
+            ~/.platformio/.cache
+          key: ${{ runner.os }}-pio
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install PlatformIO Core
+        run: pip install --upgrade platformio
+
+      - name: Build CrossPoint
+        run: pio run -e gh_release
+
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: CrossPoint-${{ github.ref_name }}
+          path: |
+            .pio/build/gh_release/bootloader.bin
+            .pio/build/gh_release/firmware.bin
+            .pio/build/gh_release/firmware.elf
+            .pio/build/gh_release/firmware.map
+            .pio/build/gh_release/partitions.bin

.gitignore

@@ -1,3 +1,6 @@
 .pio
 .idea
 .DS_Store
+.vscode
+lib/EpdFont/fontsrc
+*.generated.h

README.md

@@ -6,10 +6,7 @@ Built using **PlatformIO** and targeting the **ESP32-C3** microcontroller.
 CrossPoint Reader is a purpose-built firmware designed to be a drop-in, fully open-source replacement for the official 
 Xteink firmware. It aims to match or improve upon the standard EPUB reading experience.
 
-// TODO include some images
-
-I look at the [**diy-esp32-epub-reader** by atomic14](https://github.com/atomic14/diy-esp32-epub-reader) project a lot 
-when making CrossPoint and a handful of lessons and some direct source code comes directly from that repo.
+![](./docs/images/cover.jpg)
 
 ## Motivation
 
@@ -26,20 +23,48 @@ CrossPoint Reader aims to:
 
 This project is **not affiliated with Xteink**; it's built as a community project.
 
-## Features
+## Features & Usage
 
 - [x] EPUB parsing and rendering
-- [x] Saved reading position
-- [ ] File explorer with file picker
-  - [x] Basic EPUB picker from root directory
-  - [ ] Support nested folders
-  - [ ] EPUB picker with cover art
 - [ ] Image support within EPUB
+- [x] Saved reading position
+- [x] File explorer with file picker
+  - [x] Basic EPUB picker from root directory
+  - [x] Support nested folders
+  - [ ] EPUB picker with cover art
+- [x] Custom sleep screen
+  - [ ] Cover sleep screen
+- [x] Wifi book upload
+- [ ] Wifi OTA updates
 - [ ] Configurable font, layout, and display options
-- [ ] WiFi connectivity
-- [ ] BLE connectivity
+- [ ] Screen rotation
 
-## Getting Started
+See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint.
+
+## Installing
+
+### Web (latest firmware)
+
+1. Connect your Xteink X4 to your computer via USB-C
+2. Go to https://xteink.dve.al/ and click "Flash CrossPoint firmware"
+
+To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap
+back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.
+
+### Web (specific firmware version)
+
+1. Connect your Xteink X4 to your computer via USB-C
+2. Download the `firmware.bin` file from the release of your choice via the [releases page](https://github.com/daveallie/crosspoint-reader/releases)
+3. Go to https://xteink.dve.al/ and flash the firmware file using the "OTA fast flash controls" section
+
+To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap
+back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug.
+
+### Manual
+
+See [Development](#development) below.
+
+## Development
 
 ### Prerequisites
 
@@ -48,9 +73,18 @@ This project is **not affiliated with Xteink**; it's built as a community projec
 * USB-C cable for flashing the ESP32-C3
 * Xteink X4
 
-### Flashing your device
+### Checking out the code
 
-#### Command line
+CrossPoint uses PlatformIO for building and flashing the firmware. To get started, clone the repository:
+
+```
+git clone --recursive https://github.com/daveallie/crosspoint-reader
+
+# Or, if you've already cloned without --recursive:
+git submodule update --init --recursive
+```
+
+### Flashing your device
 
 Connect your Xteink X4 to your computer via USB-C and run the following command.
 
@@ -58,16 +92,6 @@ Connect your Xteink X4 to your computer via USB-C and run the following command.
 pio run --target upload
 ```
 
-#### Web
-
-1. Connect your Xteink X4 to your computer via USB-C
-2. Download the `firmware.bin` file from the latest release via the [releases page](https://github.com/daveallie/crosspoint-reader/releases)
-3. Go to https://xteink.dve.al/ and flash the firmware file using the "OTA fast flash controls" section
-4. Press the reset button on the Xteink X4 to restart the device
-
-To revert back to the official firmware, you can flash the latest official firmware from https://xteink.dve.al/, or swap
-back to the other partition using the "Swap boot partition" button here https://xteink.dve.al/debug. 
-
 ## Internals
 
 CrossPoint Reader is pretty aggressive about caching data down to the SD card to minimise RAM usage. The ESP32-C3 only
@@ -108,6 +132,9 @@ EPUB file will reset the reading progress.
 
 Contributions are very welcome!
 
+If you're looking for a way to help out, take a look at the [ideas discussion board](https://github.com/daveallie/crosspoint-reader/discussions/categories/ideas).
+If there's something there you'd like to work on, leave a comment so that we can avoid duplicated effort.
+
 ### To submit a contribution:
 
 1. Fork the repo
@@ -118,3 +145,6 @@ Contributions are very welcome!
 ---
 
 CrossPoint Reader is **not affiliated with Xteink or any manufacturer of the X4 hardware**.
+
+Huge shoutout to [**diy-esp32-epub-reader** by atomic14](https://github.com/atomic14/diy-esp32-epub-reader), which was a project I took a lot of inspiration from as I
+was making CrossPoint.

USER_GUIDE.md

@@ -0,0 +1,127 @@
+# CrossPoint User Guide
+
+Welcome to the **CrossPoint** firmware. This guide outlines the hardware controls, navigation, and reading features of 
+the device.
+
+## 1. Hardware Overview
+
+The device utilises the standard buttons on the Xtink X4 in the same layout:
+
+### Button Layout
+| Location        | Buttons                                    |
+|-----------------|--------------------------------------------|
+| **Bottom Edge** | **Back**, **Confirm**, **Left**, **Right** |
+| **Right Side**  | **Power**, **Volume Up**, **Volume Down**  |
+
+---
+
+## 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
+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.
+
+> **Note:** On subsequent restarts, the firmware will automatically reopen the last book you were reading.
+
+---
+
+## 3. Screens
+
+### 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.
+
+### 3.2 Book Selection (Read)
+
+The Book Selection acts as a folder and file browser.
+
+* **Navigate List:** Use **Left** (or **Volume Up**), or **Right** (or **Volume Down**) to move the selection cursor up 
+  and down through folders and books.
+* **Open Selection:** Press **Confirm** to open a folder or read a selected book.
+
+### 3.3 Reading Screen
+
+See [4. 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
+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.
+
+### 3.5 Settings
+
+The Settings screen allows you to configure the device's behavior. There are a few settings you can adjust:
+- **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
+  - "Cover" - The book cover image (Note: this is experimental and may not work as expected)
+- **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.
+
+### 3.6 Sleep Screen
+
+You can customize the sleep screen by placing custom images in specific locations on the SD card:
+
+- **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
+  randomly selected each time the device sleeps.
+
+> [!NOTE]
+> You'll need to set the **Sleep Screen** setting to **Custom** in order to use these images.
+
+> [!TIP]
+> For best results:
+> - Use uncompressed BMP files with 24-bit color depth
+> - Use a resolution of 480x800 pixels to match the device's screen resolution.
+
+---
+
+## 4. Reading Mode
+
+Once you have opened a book, the button layout changes to facilitate reading.
+
+### Page Turning
+| Action            | Buttons                              |
+|-------------------|--------------------------------------|
+| **Previous Page** | Press **Left** _or_ **Volume Up**    |
+| **Next Page**     | Press **Right** _or_ **Volume Down** |
+
+### Chapter Navigation
+* **Next Chapter:** Press and **hold** the **Right** (or **Volume Down**) button briefly, then release.
+* **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.
+
+---
+
+## 5. Chapter Selection Screen
+
+Accessible by pressing **Confirm** while inside a book.
+
+1.  Use **Left** (or **Volume Up**), or **Right** (or **Volume Down**) to highlight the desired chapter.
+2.  Press **Confirm** to jump to that chapter.
+3.  *Alternatively, press **Back** to cancel and return to your current page.*
+
+---
+
+## 6. Current Limitations & Roadmap
+
+Please note that this firmware is currently in active development. The following features are **not yet supported** but
+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.

docs/comparison.md

@@ -0,0 +1,19 @@
+# CrossPoint vs XTOS
+
+Below is like for like comparison of CrossPoint (version 0.5.1) and XTOS (version 3.1.1). CrossPoint is on the left, 
+XTOS is on the right. CrossPoint does not currently support all features of XTOS, so this comparison is just of key 
+features which both firmwares support.
+
+## EPUB reading
+
+![](./images/comparison/reading-1.jpg)
+
+![](./images/comparison/reading-2.jpg)
+
+![](./images/comparison/reading-3.jpg)
+
+## Menus
+
+![](./images/comparison/menu.jpg)
+
+![](./images/comparison/chapter-menu.jpg)

docs/webserver.md

@@ -0,0 +1,272 @@
+# Web Server Guide
+
+This guide explains how to connect your CrossPoint Reader to WiFi and use the built-in web server to upload EPUB files from your computer or phone.
+
+## Overview
+
+CrossPoint Reader includes a built-in web server that allows you to:
+
+- Upload EPUB files wirelessly from any device on the same WiFi network
+- Browse and manage files on your device's SD card
+- Create folders to organize your ebooks
+- Delete files and folders
+
+## Prerequisites
+
+- Your CrossPoint Reader device
+- A WiFi network
+- A computer, phone, or tablet connected to the **same WiFi network**
+
+---
+
+## Step 1: Accessing the WiFi Screen
+
+1. From the main menu or file browser, navigate to the **Settings** screen
+2. Select the **WiFi** option
+3. The device will automatically start scanning for available networks
+
+---
+
+## Step 2: Connecting to WiFi
+
+### Viewing Available Networks
+
+Once the scan completes, you'll see a list of available WiFi networks with the following indicators:
+
+- **Signal strength bars** (`||||`, `|||`, `||`, `|`) - Shows connection quality
+- **`*` symbol** - Indicates the network is password-protected (encrypted)
+- **`+` symbol** - Indicates you have previously saved credentials for this network
+
+<img src="./images/wifi/wifi_networks.jpeg" height="500">
+
+### Selecting a Network
+
+1. Use the **Left/Right** (or **Volume Up/Down**) buttons to navigate through the network list
+2. Press **Confirm** to select the highlighted network
+
+### Entering Password (for encrypted networks)
+
+If the network requires a password:
+
+1. An on-screen keyboard will appear
+2. Use the navigation buttons to select characters
+3. Press **Confirm** to enter each character
+4. When complete, select the **Done** option on the keyboard
+
+<img src="./images/wifi/wifi_password.jpeg" height="500">
+
+**Note:** If you've previously connected to this network, the saved password will be used automatically.
+
+### Connection Process
+
+The device will display "Connecting..." while establishing the connection. This typically takes 5-10 seconds.
+
+### Saving Credentials
+
+If this is a new network, you'll be prompted to save the password:
+
+- Select **Yes** to save credentials for automatic connection next time (NOTE: These are stored in plaintext on the device's SD card. Do not use this for sensitive networks.)
+- Select **No** to connect without saving
+
+---
+
+## Step 3: Connection Success
+
+Once connected, the screen will display:
+
+- **Network name** (SSID)
+- **IP Address** (e.g., `192.168.1.102`)
+- **Web server URL** (e.g., `http://192.168.1.102/`)
+
+<img src="./images/wifi/wifi_connected.jpeg" height="500">
+
+**Important:** Make note of the IP address - you'll need this to access the web interface from your computer or phone.
+
+---
+
+## Step 4: Accessing the Web Interface
+
+### From a Computer
+
+1. Ensure your computer is connected to the **same WiFi network** as your CrossPoint Reader
+2. Open any web browser (Chrome is recommended)
+3. Type the IP address shown on your device into the browser's address bar
+   - Example: `http://192.168.1.102/`
+4. Press Enter
+
+### From a Phone or Tablet
+
+1. Ensure your phone/tablet is connected to the **same WiFi network** as your CrossPoint Reader
+2. Open your mobile browser (Safari, Chrome, etc.)
+3. Type the IP address into the address bar
+   - Example: `http://192.168.1.102/`
+4. Tap Go
+
+---
+
+## Step 5: Using the Web Interface
+
+### Home Page
+
+The home page displays:
+
+- Device status and version information
+- WiFi connection status
+- Current IP address
+- Available memory
+
+Navigation links:
+
+- **Home** - Returns to the status page
+- **File Manager** - Access file management features
+
+<img src="./images/wifi/webserver_homepage.png" width="600">
+
+### File Manager
+
+Click **File Manager** to access file management features.
+
+#### Browsing Files
+
+- The file manager displays all files and folders on your SD card
+- **Folders** are highlighted in yellow with a 📁 icon
+- **EPUB files** are highlighted in green with a 📗 icon
+- Click on a folder name to navigate into it
+- Use the breadcrumb navigation at the top to go back to parent folders
+
+<img src="./images/wifi/webserver_files.png" width="600">
+
+#### Uploading EPUB Files
+
+1. Click the **+ Add** button in the top-right corner
+2. Select **Upload eBook** from the dropdown menu
+3. Click **Choose File** and select an `.epub` file from your device
+4. Click **Upload**
+5. A progress bar will show the upload status
+6. The page will automatically refresh when the upload is complete
+
+**Note:** Only `.epub` files are accepted. Other file types will be rejected.
+
+<img src="./images/wifi/webserver_upload.png" width="600">
+
+#### Creating Folders
+
+1. Click the **+ Add** button in the top-right corner
+2. Select **New Folder** from the dropdown menu
+3. Enter a folder name (letters, numbers, underscores, and hyphens only)
+4. Click **Create Folder**
+
+This is useful for organizing your ebooks by genre, author, or series.
+
+#### Deleting Files and Folders
+
+1. Click the **🗑️** (trash) icon next to any file or folder
+2. Confirm the deletion in the popup dialog
+3. Click **Delete** to permanently remove the item
+
+**Warning:** Deletion is permanent and cannot be undone!
+
+**Note:** Folders must be empty before they can be deleted.
+
+---
+
+## Troubleshooting
+
+### Cannot See the Device on the Network
+
+**Problem:** Browser shows "Cannot connect" or "Site can't be reached"
+
+**Solutions:**
+
+1. Verify both devices are on the **same WiFi network**
+   - Check your computer/phone WiFi settings
+   - Confirm the CrossPoint Reader shows "Connected" status
+2. Double-check the IP address
+   - Make sure you typed it correctly
+   - Include `http://` at the beginning
+3. Try disabling VPN if you're using one
+4. Some networks have "client isolation" enabled - check with your network administrator
+
+### Connection Drops or Times Out
+
+**Problem:** WiFi connection is unstable
+
+**Solutions:**
+
+1. Move closer to the WiFi router
+2. Check signal strength on the device (should be at least `||` or better)
+3. Avoid interference from other devices
+4. Try a different WiFi network if available
+
+### Upload Fails
+
+**Problem:** File upload doesn't complete or shows an error
+
+**Solutions:**
+
+1. Ensure the file is a valid `.epub` file
+2. Check that the SD card has enough free space
+3. Try uploading a smaller file first to test
+4. Refresh the browser page and try again
+
+### Saved Password Not Working
+
+**Problem:** Device fails to connect with saved credentials
+
+**Solutions:**
+
+1. When connection fails, you'll be prompted to "Forget Network"
+2. Select **Yes** to remove the saved password
+3. Reconnect and enter the password again
+4. Choose to save the new password
+
+---
+
+## Security Notes
+
+- The web server runs on port 80 (standard HTTP)
+- **No authentication is required** - anyone on the same network can access the interface
+- The web server is only accessible while the WiFi screen shows "Connected"
+- The web server automatically stops when you exit the WiFi screen
+- For security, only use on trusted private networks
+
+---
+
+## Technical Details
+
+- **Supported WiFi:** 2.4GHz networks (802.11 b/g/n)
+- **Web Server Port:** 80 (HTTP)
+- **Maximum Upload Size:** Limited by available SD card space
+- **Supported File Format:** `.epub` only
+- **Browser Compatibility:** All modern browsers (Chrome, Firefox, Safari, Edge)
+
+---
+
+## Tips and Best Practices
+
+1. **Organize with folders** - Create folders before uploading to keep your library organized
+2. **Check signal strength** - Stronger signals (`|||` or `||||`) provide faster, more reliable uploads
+3. **Upload multiple files** - You can upload files one at a time; the page refreshes after each upload
+4. **Use descriptive names** - Name your folders clearly (e.g., "SciFi", "Mystery", "Non-Fiction")
+5. **Keep credentials saved** - Save your WiFi password for quick reconnection in the future
+6. **Exit when done** - Press **Back** to exit the WiFi screen and save battery
+
+---
+
+## Exiting WiFi Mode
+
+When you're finished uploading files:
+
+1. Press the **Back** button on your CrossPoint Reader
+2. The web server will automatically stop
+3. WiFi will disconnect to conserve battery
+4. You'll return to the previous screen
+
+Your uploaded files will be immediately available in the file browser!
+
+---
+
+## Related Documentation
+
+- [User Guide](../USER_GUIDE.md) - General device operation
+- [README](../README.md) - Project overview and features

lib/EpdFont/EpdFont.cpp

@@ -2,12 +2,9 @@
 
 #include <Utf8.h>
 
-EpdFont::EpdFont(const EpdFontData* data) { this->data = data; }
-
 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; }
 
-// TODO: Text properties??
 void EpdFont::getTextBounds(const char* string, const int startX, const int startY, int* minX, int* minY, int* maxX,
                             int* maxY) const {
   *minX = startX;

lib/EpdFont/EpdFont.h

@@ -6,7 +6,7 @@ class EpdFont {
 
  public:
   const EpdFontData* data;
-  explicit EpdFont(const EpdFontData* data);
+  explicit EpdFont(const EpdFontData* data) : data(data) {}
   ~EpdFont() = default;
   void getTextDimensions(const char* string, int* w, int* h) const;
   bool hasPrintableChars(const char* string) const;

lib/EpdFont/EpdFontData.h

@@ -6,13 +6,13 @@
 
 /// Font data stored PER GLYPH
 typedef struct {
-  uint8_t width;            ///< Bitmap dimensions in pixels
-  uint8_t height;           ///< Bitmap dimensions in pixels
-  uint8_t advanceX;         ///< Distance to advance cursor (x axis)
-  int16_t left;             ///< X dist from cursor pos to UL corner
-  int16_t top;              ///< Y dist from cursor pos to UL corner
-  uint16_t compressedSize;  ///< Size of the zlib-compressed font data.
-  uint32_t dataOffset;      ///< Pointer into EpdFont->bitmap
+  uint8_t width;        ///< Bitmap dimensions in pixels
+  uint8_t height;       ///< Bitmap dimensions in pixels
+  uint8_t advanceX;     ///< Distance to advance cursor (x axis)
+  int16_t left;         ///< X dist from cursor pos to UL corner
+  int16_t top;          ///< Y dist from cursor pos to UL corner
+  uint16_t dataLength;  ///< Size of the font data.
+  uint32_t dataOffset;  ///< Pointer into EpdFont->bitmap
 } EpdGlyph;
 
 /// Glyph interval structure
@@ -28,8 +28,8 @@ typedef struct {
   const EpdGlyph* glyph;                ///< Glyph array
   const EpdUnicodeInterval* intervals;  ///< Valid unicode intervals for this font
   uint32_t intervalCount;               ///< Number of unicode intervals.
-  bool compressed;                      ///< Does this font use compressed glyph bitmaps?
   uint8_t advanceY;                     ///< Newline distance (y axis)
   int ascender;                         ///< Maximal height of a glyph above the base line
   int descender;                        ///< Maximal height of a glyph below the base line
+  bool is2Bit;
 } EpdFontData;

lib/EpdFont/EpdFontFamily.cpp

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

lib/EpdFont/EpdFontFamily.h

@@ -0,0 +1,24 @@
+#pragma once
+#include "EpdFont.h"
+
+enum EpdFontStyle { REGULAR, BOLD, ITALIC, BOLD_ITALIC };
+
+class EpdFontFamily {
+  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;
+};

lib/EpdFont/scripts/fontconvert.py

@@ -7,20 +7,20 @@ import math
 import argparse
 from collections import namedtuple
 
-# From: https://github.com/vroland/epdiy
+# Originally from https://github.com/vroland/epdiy
 
 parser = argparse.ArgumentParser(description="Generate a header file from a font to be used with epdiy.")
 parser.add_argument("name", action="store", help="name of the font.")
 parser.add_argument("size", type=int, help="font size to use.")
 parser.add_argument("fontstack", action="store", nargs='+', help="list of font files, ordered by descending priority.")
-parser.add_argument("--compress", dest="compress", action="store_true", help="compress glyph bitmaps.")
+parser.add_argument("--2bit", dest="is2Bit", action="store_true", help="generate 2-bit greyscale bitmap instead of 1-bit black and white.")
 parser.add_argument("--additional-intervals", dest="additional_intervals", action="append", help="Additional code point intervals to export as min,max. This argument can be repeated.")
 args = parser.parse_args()
 
-GlyphProps = namedtuple("GlyphProps", ["width", "height", "advance_x", "left", "top", "compressed_size", "data_offset", "code_point"])
+GlyphProps = namedtuple("GlyphProps", ["width", "height", "advance_x", "left", "top", "data_length", "data_offset", "code_point"])
 
 font_stack = [freetype.Face(f) for f in args.fontstack]
-compress = args.compress
+is2Bit = args.is2Bit
 size = args.size
 font_name = args.name
 
@@ -54,7 +54,7 @@ intervals = [
     # (0x0370, 0x03FF),
     ### Cyrillic ###
     # Russian, Ukrainian, Bulgarian, etc.
-    # (0x0400, 0x04FF),
+    (0x0400, 0x04FF),
     ### Math Symbols (common subset) ###
     # General math operators
     (0x2200, 0x22FF),
@@ -148,19 +148,18 @@ for i_start, i_end in unvalidated_intervals:
         intervals.append((start, i_end))
 
 for face in font_stack:
-    # shift by 6 bytes, because sizes are given as 6-bit fractions
-    # the display has about 150 dpi.
     face.set_char_size(size << 6, size << 6, 150, 150)
 
 total_size = 0
-total_packed = 0
 all_glyphs = []
 
 for i_start, i_end in intervals:
     for code_point in range(i_start, i_end + 1):
         face = load_glyph(code_point)
         bitmap = face.glyph.bitmap
-        pixels = []
+
+        # Build out 4-bit greyscale bitmap
+        pixels4g = []
         px = 0
         for i, v in enumerate(bitmap.buffer):
             y = i / bitmap.width
@@ -169,31 +168,92 @@ for i_start, i_end in intervals:
                 px = (v >> 4)
             else:
                 px = px | (v & 0xF0)
-                pixels.append(px);
+                pixels4g.append(px);
                 px = 0
             # eol
             if x == bitmap.width - 1 and bitmap.width % 2 > 0:
-                pixels.append(px)
+                pixels4g.append(px)
                 px = 0
 
-        packed = bytes(pixels);
-        total_packed += len(packed)
-        compressed = packed
-        if compress:
-            compressed = zlib.compress(packed)
+        if is2Bit:
+            # 0-3 white, 4-7 light grey, 8-11 dark grey, 12-15 black
+            # Downsample to 2-bit bitmap
+            pixels2b = []
+            px = 0
+            pitch = (bitmap.width // 2) + (bitmap.width % 2)
+            for y in range(bitmap.rows):
+                for x in range(bitmap.width):
+                    px = px << 2
+                    bm = pixels4g[y * pitch + (x // 2)]
+                    bm = (bm >> ((x % 2) * 4)) & 0xF
 
+                    if bm >= 12:
+                        px += 3
+                    elif bm >= 8:
+                        px += 2
+                    elif bm >= 4:
+                        px += 1
+
+                    if (y * bitmap.width + x) % 4 == 3:
+                        pixels2b.append(px)
+                        px = 0
+            if (bitmap.width * bitmap.rows) % 4 != 0:
+                px = px << (4 - (bitmap.width * bitmap.rows) % 4) * 2
+                pixels2b.append(px)
+
+            # for y in range(bitmap.rows):
+            #     line = ''
+            #     for x in range(bitmap.width):
+            #         pixelPosition = y * bitmap.width + x
+            #         byte = pixels2b[pixelPosition // 4]
+            #         bit_index = (3 - (pixelPosition % 4)) * 2
+            #         line += '#' if ((byte >> bit_index) & 3) > 0 else '.'
+            #     print(line)
+            # print('')
+        else:
+            # Downsample to 1-bit bitmap - treat any 2+ as black
+            pixelsbw = []
+            px = 0
+            pitch = (bitmap.width // 2) + (bitmap.width % 2)
+            for y in range(bitmap.rows):
+                for x in range(bitmap.width):
+                    px = px << 1
+                    bm = pixels4g[y * pitch + (x // 2)]
+                    px += 1 if ((x & 1) == 0 and bm & 0xE > 0) or ((x & 1) == 1 and bm & 0xE0 > 0) else 0
+
+                    if (y * bitmap.width + x) % 8 == 7:
+                        pixelsbw.append(px)
+                        px = 0
+            if (bitmap.width * bitmap.rows) % 8 != 0:
+                px = px << (8 - (bitmap.width * bitmap.rows) % 8)
+                pixelsbw.append(px)
+
+            # for y in range(bitmap.rows):
+            #     line = ''
+            #     for x in range(bitmap.width):
+            #         pixelPosition = y * bitmap.width + x
+            #         byte = pixelsbw[pixelPosition // 8]
+            #         bit_index = 7 - (pixelPosition % 8)
+            #         line += '#' if (byte >> bit_index) & 1 else '.'
+            #     print(line)
+            # print('')
+
+        pixels = pixels2b if is2Bit else pixelsbw
+
+        # Build output data
+        packed = bytes(pixels)
         glyph = GlyphProps(
             width = bitmap.width,
             height = bitmap.rows,
             advance_x = norm_floor(face.glyph.advance.x),
             left = face.glyph.bitmap_left,
             top = face.glyph.bitmap_top,
-            compressed_size = len(compressed),
+            data_length = len(packed),
             data_offset = total_size,
             code_point = code_point,
         )
-        total_size += len(compressed)
-        all_glyphs.append((glyph, compressed))
+        total_size += len(packed)
+        all_glyphs.append((glyph, packed))
 
 # pipe seems to be a good heuristic for the "real" descender
 face = load_glyph(ord('|'))
@@ -201,11 +261,11 @@ face = load_glyph(ord('|'))
 glyph_data = []
 glyph_props = []
 for index, glyph in enumerate(all_glyphs):
-    props, compressed = glyph
-    glyph_data.extend([b for b in compressed])
+    props, packed = glyph
+    glyph_data.extend([b for b in packed])
     glyph_props.append(props)
 
-print(f"/**\n * generated by fontconvert.py\n * name: {font_name}\n * size: {size}\n * compressed: {compress}\n */")
+print(f"/**\n * generated by fontconvert.py\n * name: {font_name}\n * size: {size}\n * mode: {'2-bit' if is2Bit else '1-bit'}\n */")
 print("#pragma once")
 print("#include \"EpdFontData.h\"\n")
 print(f"static const uint8_t {font_name}Bitmaps[{len(glyph_data)}] = {{")
@@ -230,8 +290,8 @@ print(f"    {font_name}Bitmaps,")
 print(f"    {font_name}Glyphs,")
 print(f"    {font_name}Intervals,")
 print(f"    {len(intervals)},")
-print(f"    {1 if compress else 0},")
 print(f"    {norm_ceil(face.size.height)},")
 print(f"    {norm_ceil(face.size.ascender)},")
 print(f"    {norm_floor(face.size.descender)},")
+print(f"    {'true' if is2Bit else 'false'},")
 print("};")

lib/EpdFontRenderer/EpdFontRenderer.hpp

@@ -1,132 +0,0 @@
-#pragma once
-#include <EpdFont.h>
-#include <HardwareSerial.h>
-#include <Utf8.h>
-#include <miniz.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 ? a : b; }
-
-static tinfl_decompressor decomp;
-
-template <typename Renderable>
-class EpdFontRenderer {
-  Renderable* renderer;
-  void renderChar(uint32_t cp, int* x, const int* y, uint16_t color);
-
- public:
-  const EpdFont* font;
-  explicit EpdFontRenderer(const EpdFont* font, Renderable* renderer);
-  ~EpdFontRenderer() = default;
-  void renderString(const char* string, int* x, int* y, uint16_t color);
-};
-
-inline int uncompress(uint8_t* dest, size_t uncompressedSize, const uint8_t* source, size_t sourceSize) {
-  if (uncompressedSize == 0 || dest == nullptr || sourceSize == 0 || source == nullptr) {
-    return -1;
-  }
-  tinfl_init(&decomp);
-
-  // we know everything will fit into the buffer.
-  const tinfl_status decomp_status =
-      tinfl_decompress(&decomp, source, &sourceSize, dest, dest, &uncompressedSize,
-                       TINFL_FLAG_PARSE_ZLIB_HEADER | TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF);
-  if (decomp_status != TINFL_STATUS_DONE) {
-    return decomp_status;
-  }
-  return 0;
-}
-
-template <typename Renderable>
-EpdFontRenderer<Renderable>::EpdFontRenderer(const EpdFont* font, Renderable* renderer) {
-  this->font = font;
-  this->renderer = renderer;
-}
-
-template <typename Renderable>
-void EpdFontRenderer<Renderable>::renderString(const char* string, int* x, int* y, const uint16_t color) {
-  // cannot draw a NULL / empty string
-  if (string == nullptr || *string == '\0') {
-    return;
-  }
-
-  // no printable characters
-  if (!font->hasPrintableChars(string)) {
-    return;
-  }
-
-  uint32_t cp;
-  while ((cp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&string)))) {
-    renderChar(cp, x, y, color);
-  }
-
-  *y += font->data->advanceY;
-}
-
-template <typename Renderable>
-void EpdFontRenderer<Renderable>::renderChar(const uint32_t cp, int* x, const int* y, uint16_t color) {
-  const EpdGlyph* glyph = font->getGlyph(cp);
-  if (!glyph) {
-    // TODO: Replace with fallback glyph property?
-    glyph = font->getGlyph('?');
-  }
-
-  // no glyph?
-  if (!glyph) {
-    Serial.printf("No glyph for codepoint %d\n", cp);
-    return;
-  }
-
-  const uint32_t offset = glyph->dataOffset;
-  const uint8_t width = glyph->width;
-  const uint8_t height = glyph->height;
-  const int left = glyph->left;
-
-  const int byteWidth = width / 2 + width % 2;
-  const unsigned long bitmapSize = byteWidth * height;
-  const uint8_t* bitmap = nullptr;
-
-  if (font->data->compressed) {
-    auto* tmpBitmap = static_cast<uint8_t*>(malloc(bitmapSize));
-    if (tmpBitmap == nullptr && bitmapSize) {
-      // ESP_LOGE("font", "malloc failed.");
-      return;
-    }
-
-    uncompress(tmpBitmap, bitmapSize, &font->data->bitmap[offset], glyph->compressedSize);
-    bitmap = tmpBitmap;
-  } else {
-    bitmap = &font->data->bitmap[offset];
-  }
-
-  if (bitmap != nullptr) {
-    for (int localY = 0; localY < height; localY++) {
-      int yy = *y - glyph->top + localY;
-      const int startPos = *x + left;
-      bool byteComplete = startPos % 2;
-      int localX = max(0, -startPos);
-      const int maxX = startPos + width;
-
-      for (int xx = startPos; xx < maxX; xx++) {
-        uint8_t bm = bitmap[localY * byteWidth + localX / 2];
-        if ((localX & 1) == 0) {
-          bm = bm & 0xF;
-        } else {
-          bm = bm >> 4;
-        }
-
-        if (bm) {
-          renderer->drawPixel(xx, yy, color);
-        }
-        byteComplete = !byteComplete;
-        localX++;
-      }
-    }
-
-    if (font->data->compressed) {
-      free(const_cast<uint8_t*>(bitmap));
-    }
-  }
-
-  *x += glyph->advanceX;
-}

lib/EpdRenderer/EpdRenderer.cpp

@@ -1,151 +0,0 @@
-#include "EpdRenderer.h"
-
-#include "builtinFonts/babyblue.h"
-#include "builtinFonts/bookerly.h"
-#include "builtinFonts/bookerly_bold.h"
-#include "builtinFonts/bookerly_bold_italic.h"
-#include "builtinFonts/bookerly_italic.h"
-
-EpdRenderer::EpdRenderer(XteinkDisplay* display) {
-  this->display = display;
-  this->regularFont = new EpdFontRenderer<XteinkDisplay>(new EpdFont(&bookerly), display);
-  this->boldFont = new EpdFontRenderer<XteinkDisplay>(new EpdFont(&bookerly_bold), display);
-  this->italicFont = new EpdFontRenderer<XteinkDisplay>(new EpdFont(&bookerly_italic), display);
-  this->bold_italicFont = new EpdFontRenderer<XteinkDisplay>(new EpdFont(&bookerly_bold_italic), display);
-  this->smallFont = new EpdFontRenderer<XteinkDisplay>(new EpdFont(&babyblue), display);
-
-  this->marginTop = 11;
-  this->marginBottom = 30;
-  this->marginLeft = 10;
-  this->marginRight = 10;
-  this->lineCompression = 0.95f;
-}
-
-EpdFontRenderer<XteinkDisplay>* EpdRenderer::getFontRenderer(const bool bold, const bool italic) const {
-  if (bold && italic) {
-    return bold_italicFont;
-  }
-  if (bold) {
-    return boldFont;
-  }
-  if (italic) {
-    return italicFont;
-  }
-  return regularFont;
-}
-
-int EpdRenderer::getTextWidth(const char* text, const bool bold, const bool italic) const {
-  int w = 0, h = 0;
-
-  getFontRenderer(bold, italic)->font->getTextDimensions(text, &w, &h);
-
-  return w;
-}
-
-int EpdRenderer::getSmallTextWidth(const char* text) const {
-  int w = 0, h = 0;
-
-  smallFont->font->getTextDimensions(text, &w, &h);
-
-  return w;
-}
-
-void EpdRenderer::drawText(const int x, const int y, const char* text, const bool bold, const bool italic,
-                           const uint16_t color) const {
-  int ypos = y + getLineHeight() + marginTop;
-  int xpos = x + marginLeft;
-  getFontRenderer(bold, italic)->renderString(text, &xpos, &ypos, color > 0 ? GxEPD_BLACK : GxEPD_WHITE);
-}
-
-void EpdRenderer::drawSmallText(const int x, const int y, const char* text, const uint16_t color) const {
-  int ypos = y + smallFont->font->data->advanceY + marginTop;
-  int xpos = x + marginLeft;
-  smallFont->renderString(text, &xpos, &ypos, color > 0 ? GxEPD_BLACK : GxEPD_WHITE);
-}
-
-void EpdRenderer::drawTextBox(const int x, const int y, const std::string& text, const int width, const int height,
-                              const bool bold, const bool italic) const {
-  const size_t length = text.length();
-  // fit the text into the box
-  int start = 0;
-  int end = 1;
-  int ypos = 0;
-  while (true) {
-    if (end >= length) {
-      drawText(x, y + ypos, text.substr(start, length - start).c_str(), bold, italic);
-      break;
-    }
-
-    if (ypos + getLineHeight() >= height) {
-      break;
-    }
-
-    if (text[end - 1] == '\n') {
-      drawText(x, y + ypos, text.substr(start, end - start).c_str(), bold, italic);
-      ypos += getLineHeight();
-      start = end;
-      end = start + 1;
-      continue;
-    }
-
-    if (getTextWidth(text.substr(start, end - start).c_str(), bold, italic) > width) {
-      drawText(x, y + ypos, text.substr(start, end - start - 1).c_str(), bold, italic);
-      ypos += getLineHeight();
-      start = end - 1;
-      continue;
-    }
-
-    end++;
-  }
-}
-
-void EpdRenderer::drawLine(int x1, int y1, int x2, int y2, uint16_t color) const {
-  display->drawLine(x1 + marginLeft, y1 + marginTop, x2 + marginLeft, y2 + marginTop,
-                    color > 0 ? GxEPD_BLACK : GxEPD_WHITE);
-}
-
-void EpdRenderer::drawRect(const int x, const int y, const int width, const int height, const uint16_t color) const {
-  display->drawRect(x + marginLeft, y + marginTop, width, height, color > 0 ? GxEPD_BLACK : GxEPD_WHITE);
-}
-
-void EpdRenderer::fillRect(const int x, const int y, const int width, const int height,
-                           const uint16_t color = 0) const {
-  display->fillRect(x + marginLeft, y + marginTop, width, height, color > 0 ? GxEPD_BLACK : GxEPD_WHITE);
-}
-
-void EpdRenderer::clearScreen(const bool black) const {
-  Serial.println("Clearing screen");
-  display->fillScreen(black ? GxEPD_BLACK : GxEPD_WHITE);
-}
-
-void EpdRenderer::flushDisplay() const { display->display(true); }
-
-void EpdRenderer::flushArea(int x, int y, int width, int height) const {
-  // TODO: Fix
-  display->display(true);
-}
-
-int EpdRenderer::getPageWidth() const { return display->width() - marginLeft - marginRight; }
-
-int EpdRenderer::getPageHeight() const { return display->height() - marginTop - marginBottom; }
-
-int EpdRenderer::getSpaceWidth() const { return regularFont->font->getGlyph(' ')->advanceX; }
-
-int EpdRenderer::getLineHeight() const { return regularFont->font->data->advanceY * lineCompression; }
-
-// deep sleep helper - persist any state to disk that may be needed on wake
-bool EpdRenderer::dehydrate() {
-  // TODO: Implement
-  return false;
-};
-
-// deep sleep helper - retrieve any state from disk after wake
-bool EpdRenderer::hydrate() {
-  // TODO: Implement
-  return false;
-};
-
-// really really clear the screen
-void EpdRenderer::reset() {
-  // TODO: Implement
-};

lib/EpdRenderer/EpdRenderer.h

@@ -1,56 +0,0 @@
-#pragma once
-
-#include <GxEPD2_BW.h>
-
-#include <EpdFontRenderer.hpp>
-
-#define XteinkDisplay GxEPD2_BW<GxEPD2_426_GDEQ0426T82, GxEPD2_426_GDEQ0426T82::HEIGHT>
-
-class EpdRenderer {
-  XteinkDisplay* display;
-  EpdFontRenderer<XteinkDisplay>* regularFont;
-  EpdFontRenderer<XteinkDisplay>* boldFont;
-  EpdFontRenderer<XteinkDisplay>* italicFont;
-  EpdFontRenderer<XteinkDisplay>* bold_italicFont;
-  EpdFontRenderer<XteinkDisplay>* smallFont;
-  int marginTop;
-  int marginBottom;
-  int marginLeft;
-  int marginRight;
-  float lineCompression;
-  EpdFontRenderer<XteinkDisplay>* getFontRenderer(bool bold, bool italic) const;
-
- public:
-  explicit EpdRenderer(XteinkDisplay* display);
-  ~EpdRenderer() = default;
-  int getTextWidth(const char* text, bool bold = false, bool italic = false) const;
-  int getSmallTextWidth(const char* text) const;
-  void drawText(int x, int y, const char* text, bool bold = false, bool italic = false, uint16_t color = 1) const;
-  void drawSmallText(int x, int y, const char* text, uint16_t color = 1) const;
-  void drawTextBox(int x, int y, const std::string& text, int width, int height, bool bold = false,
-                   bool italic = false) const;
-  void drawLine(int x1, int y1, int x2, int y2, uint16_t color) const;
-  void drawRect(int x, int y, int width, int height, uint16_t color) const;
-  void fillRect(int x, int y, int width, int height, uint16_t color) const;
-  void clearScreen(bool black = false) const;
-  void flushDisplay() const;
-  void flushArea(int x, int y, int width, int height) const;
-
-  int getPageWidth() const;
-  int getPageHeight() const;
-  int getSpaceWidth() const;
-  int getLineHeight() const;
-  // set margins
-  void setMarginTop(const int newMarginTop) { this->marginTop = newMarginTop; }
-  void setMarginBottom(const int newMarginBottom) { this->marginBottom = newMarginBottom; }
-  void setMarginLeft(const int newMarginLeft) { this->marginLeft = newMarginLeft; }
-  void setMarginRight(const int newMarginRight) { this->marginRight = newMarginRight; }
-  // deep sleep helper - persist any state to disk that may be needed on wake
-  bool dehydrate();
-  // deep sleep helper - retrieve any state from disk after wake
-  bool hydrate();
-  // really really clear the screen
-  void reset();
-
-  uint8_t temperature = 20;
-};

lib/Epub/Epub.cpp

@@ -1,254 +1,239 @@
 #include "Epub.h"
 
+#include <FsHelpers.h>
 #include <HardwareSerial.h>
+#include <JpegToBmpConverter.h>
 #include <SD.h>
 #include <ZipFile.h>
 
-#include <map>
+#include "Epub/parsers/ContainerParser.h"
+#include "Epub/parsers/ContentOpfParser.h"
+#include "Epub/parsers/TocNcxParser.h"
 
-bool Epub::findContentOpfFile(const ZipFile& zip, std::string& contentOpfFile) {
-  // open up the meta data to find where the content.opf file lives
-  size_t s;
-  const auto metaInfo = zip.readTextFileToMemory("META-INF/container.xml", &s);
-  if (!metaInfo) {
-    Serial.println("Could not find META-INF/container.xml");
+bool Epub::findContentOpfFile(std::string* contentOpfFile) const {
+  const auto containerPath = "META-INF/container.xml";
+  size_t containerSize;
+
+  // Get file size without loading it all into heap
+  if (!getItemSize(containerPath, &containerSize)) {
+    Serial.printf("[%lu] [EBP] Could not find or size META-INF/container.xml\n", millis());
     return false;
   }
 
-  // parse the meta data
-  tinyxml2::XMLDocument metaDataDoc;
-  const auto result = metaDataDoc.Parse(metaInfo);
-  free(metaInfo);
+  ContainerParser containerParser(containerSize);
 
-  if (result != tinyxml2::XML_SUCCESS) {
-    Serial.printf("Could not parse META-INF/container.xml. Error: %d\n", result);
+  if (!containerParser.setup()) {
     return false;
   }
 
-  const auto container = metaDataDoc.FirstChildElement("container");
-  if (!container) {
-    Serial.println("Could not find container element in META-INF/container.xml");
+  // Stream read (reusing your existing stream logic)
+  if (!readItemContentsToStream(containerPath, containerParser, 512)) {
+    Serial.printf("[%lu] [EBP] Could not read META-INF/container.xml\n", millis());
     return false;
   }
 
-  const auto rootfiles = container->FirstChildElement("rootfiles");
-  if (!rootfiles) {
-    Serial.println("Could not find rootfiles element in META-INF/container.xml");
+  // Extract the result
+  if (containerParser.fullPath.empty()) {
+    Serial.printf("[%lu] [EBP] Could not find valid rootfile in container.xml\n", millis());
     return false;
   }
 
-  // find the root file that has the media-type="application/oebps-package+xml"
-  auto rootfile = rootfiles->FirstChildElement("rootfile");
-  while (rootfile) {
-    const char* mediaType = rootfile->Attribute("media-type");
-    if (mediaType && strcmp(mediaType, "application/oebps-package+xml") == 0) {
-      const char* full_path = rootfile->Attribute("full-path");
-      if (full_path) {
-        contentOpfFile = full_path;
-        return true;
-      }
-    }
-    rootfile = rootfile->NextSiblingElement("rootfile");
-  }
-
-  Serial.println("Could not get path to content.opf file");
-  return false;
-}
-
-bool Epub::parseContentOpf(ZipFile& zip, std::string& content_opf_file) {
-  // read in the content.opf file and parse it
-  auto contents = zip.readTextFileToMemory(content_opf_file.c_str());
-
-  // parse the contents
-  tinyxml2::XMLDocument doc;
-  auto result = doc.Parse(contents);
-  free(contents);
-
-  if (result != tinyxml2::XML_SUCCESS) {
-    Serial.printf("Error parsing content.opf - %s\n", tinyxml2::XMLDocument::ErrorIDToName(result));
-    return false;
-  }
-
-  auto package = doc.FirstChildElement("package");
-  if (!package) package = doc.FirstChildElement("opf:package");
-
-  if (!package) {
-    Serial.println("Could not find package element in content.opf");
-    return false;
-  }
-
-  // get the metadata - title and cover image
-  auto metadata = package->FirstChildElement("metadata");
-  if (!metadata) metadata = package->FirstChildElement("opf:metadata");
-  if (!metadata) {
-    Serial.println("Missing metadata");
-    return false;
-  }
-
-  auto titleEl = metadata->FirstChildElement("dc:title");
-  if (!titleEl) {
-    Serial.println("Missing title");
-    return false;
-  }
-  this->title = titleEl->GetText();
-
-  auto cover = metadata->FirstChildElement("meta");
-  if (!cover) cover = metadata->FirstChildElement("opf:meta");
-  while (cover && cover->Attribute("name") && strcmp(cover->Attribute("name"), "cover") != 0) {
-    cover = cover->NextSiblingElement("meta");
-  }
-  if (!cover) {
-    Serial.println("Missing cover");
-  }
-  auto coverItem = cover ? cover->Attribute("content") : nullptr;
-
-  // read the manifest and spine
-  // the manifest gives us the names of the files
-  // the spine gives us the order of the files
-  // we can then read the files in the order they are in the spine
-  auto manifest = package->FirstChildElement("manifest");
-  if (!manifest) manifest = package->FirstChildElement("opf:manifest");
-  if (!manifest) {
-    Serial.println("Missing manifest");
-    return false;
-  }
-
-  // create a mapping from id to file name
-  auto item = manifest->FirstChildElement("item");
-  if (!item) item = manifest->FirstChildElement("opf:item");
-  std::map<std::string, std::string> items;
-
-  while (item) {
-    std::string itemId = item->Attribute("id");
-    std::string href = contentBasePath + item->Attribute("href");
-
-    // grab the cover image
-    if (coverItem && itemId == coverItem) {
-      coverImageItem = href;
-    }
-
-    // grab the ncx file
-    if (itemId == "ncx" || itemId == "ncxtoc") {
-      tocNcxItem = href;
-    }
-
-    items[itemId] = href;
-    auto nextItem = item->NextSiblingElement("item");
-    if (!nextItem) nextItem = item->NextSiblingElement("opf:item");
-    item = nextItem;
-  }
-
-  // find the spine
-  auto spineEl = package->FirstChildElement("spine");
-  if (!spineEl) spineEl = package->FirstChildElement("opf:spine");
-  if (!spineEl) {
-    Serial.println("Missing spine");
-    return false;
-  }
-
-  // read the spine
-  auto itemref = spineEl->FirstChildElement("itemref");
-  if (!itemref) itemref = spineEl->FirstChildElement("opf:itemref");
-  while (itemref) {
-    auto id = itemref->Attribute("idref");
-    if (items.find(id) != items.end()) {
-      spine.emplace_back(id, items[id]);
-    }
-    auto nextItemRef = itemref->NextSiblingElement("itemref");
-    if (!nextItemRef) nextItemRef = itemref->NextSiblingElement("opf:itemref");
-    itemref = nextItemRef;
-  }
+  *contentOpfFile = std::move(containerParser.fullPath);
   return true;
 }
 
-bool Epub::parseTocNcxFile(const ZipFile& zip) {
+bool Epub::parseContentOpf(BookMetadataCache::BookMetadata& bookMetadata) {
+  std::string contentOpfFilePath;
+  if (!findContentOpfFile(&contentOpfFilePath)) {
+    Serial.printf("[%lu] [EBP] Could not find content.opf in zip\n", millis());
+    return false;
+  }
+
+  contentBasePath = contentOpfFilePath.substr(0, contentOpfFilePath.find_last_of('/') + 1);
+
+  Serial.printf("[%lu] [EBP] Parsing content.opf: %s\n", millis(), contentOpfFilePath.c_str());
+
+  size_t contentOpfSize;
+  if (!getItemSize(contentOpfFilePath, &contentOpfSize)) {
+    Serial.printf("[%lu] [EBP] Could not get size of content.opf\n", millis());
+    return false;
+  }
+
+  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;
+  }
+
+  if (!readItemContentsToStream(contentOpfFilePath, opfParser, 1024)) {
+    Serial.printf("[%lu] [EBP] Could not read content.opf\n", millis());
+    return false;
+  }
+
+  // Grab data from opfParser into epub
+  bookMetadata.title = opfParser.title;
+  // TODO: Parse author
+  bookMetadata.author = "";
+  bookMetadata.coverItemHref = opfParser.coverItemHref;
+
+  if (!opfParser.tocNcxPath.empty()) {
+    tocNcxItem = opfParser.tocNcxPath;
+  }
+
+  Serial.printf("[%lu] [EBP] Successfully parsed content.opf\n", millis());
+  return true;
+}
+
+bool Epub::parseTocNcxFile() const {
   // the ncx file should have been specified in the content.opf file
   if (tocNcxItem.empty()) {
-    Serial.println("No ncx file specified");
+    Serial.printf("[%lu] [EBP] No ncx file specified\n", millis());
     return false;
   }
 
-  const auto ncxData = zip.readTextFileToMemory(tocNcxItem.c_str());
-  if (!ncxData) {
-    Serial.printf("Could not find %s\n", tocNcxItem.c_str());
+  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)) {
+    return false;
+  }
+  readItemContentsToStream(tocNcxItem, tempNcxFile, 1024);
+  tempNcxFile.close();
+  if (!FsHelpers::openFileForRead("EBP", tmpNcxPath, tempNcxFile)) {
+    return false;
+  }
+  const auto ncxSize = tempNcxFile.size();
+
+  TocNcxParser ncxParser(contentBasePath, ncxSize, bookMetadataCache.get());
+
+  if (!ncxParser.setup()) {
+    Serial.printf("[%lu] [EBP] Could not setup toc ncx parser\n", millis());
     return false;
   }
 
-  // Parse the Toc contents
-  tinyxml2::XMLDocument doc;
-  const auto result = doc.Parse(ncxData);
-  free(ncxData);
-
-  if (result != tinyxml2::XML_SUCCESS) {
-    Serial.printf("Error parsing toc %s\n", tinyxml2::XMLDocument::ErrorIDToName(result));
+  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());
     return false;
   }
 
-  const auto ncx = doc.FirstChildElement("ncx");
-  if (!ncx) {
-    Serial.println("Could not find first child ncx in toc");
-    return false;
+  while (tempNcxFile.available()) {
+    const auto readSize = tempNcxFile.read(ncxBuffer, 1024);
+    const auto processedSize = ncxParser.write(ncxBuffer, readSize);
+
+    if (processedSize != readSize) {
+      Serial.printf("[%lu] [EBP] Could not process all toc ncx data\n", millis());
+      free(ncxBuffer);
+      tempNcxFile.close();
+      return false;
+    }
   }
 
-  const auto navMap = ncx->FirstChildElement("navMap");
-  if (!navMap) {
-    Serial.println("Could not find navMap child in ncx");
-    return false;
-  }
+  free(ncxBuffer);
+  tempNcxFile.close();
+  SD.remove(tmpNcxPath.c_str());
 
-  recursivelyParseNavMap(navMap->FirstChildElement("navPoint"));
+  Serial.printf("[%lu] [EBP] Parsed TOC items\n", millis());
   return true;
 }
 
-void Epub::recursivelyParseNavMap(tinyxml2::XMLElement* element) {
-  // Fills toc map
-  while (element) {
-    std::string navTitle = element->FirstChildElement("navLabel")->FirstChildElement("text")->FirstChild()->Value();
-    const auto content = element->FirstChildElement("content");
-    std::string href = contentBasePath + content->Attribute("src");
-    // split the href on the # to get the href and the anchor
-    const size_t pos = href.find('#');
-    std::string anchor;
-
-    if (pos != std::string::npos) {
-      anchor = href.substr(pos + 1);
-      href = href.substr(0, pos);
-    }
-
-    toc.emplace_back(navTitle, href, anchor, 0);
-
-    tinyxml2::XMLElement* nestedNavPoint = element->FirstChildElement("navPoint");
-    if (nestedNavPoint) {
-      recursivelyParseNavMap(nestedNavPoint);
-    }
-    element = element->NextSiblingElement("navPoint");
-  }
-}
-
 // load in the meta data for the epub file
 bool Epub::load() {
-  ZipFile zip("/sd" + filepath);
+  Serial.printf("[%lu] [EBP] Loading ePub: %s\n", millis(), filepath.c_str());
 
-  std::string contentOpfFile;
-  if (!findContentOpfFile(zip, contentOpfFile)) {
-    Serial.println("Could not open ePub");
+  // Initialize spine/TOC cache
+  bookMetadataCache.reset(new BookMetadataCache(cachePath));
+
+  // Try to load existing cache first
+  if (bookMetadataCache->load()) {
+    Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
+    return true;
+  }
+
+  // Cache doesn't exist or is invalid, build it
+  Serial.printf("[%lu] [EBP] Cache not found, building spine/TOC cache\n", millis());
+  setupCacheDir();
+
+  // Begin building cache - stream entries to disk immediately
+  if (!bookMetadataCache->beginWrite()) {
+    Serial.printf("[%lu] [EBP] Could not begin writing cache\n", millis());
     return false;
   }
 
-  contentBasePath = contentOpfFile.substr(0, contentOpfFile.find_last_of('/') + 1);
-
-  if (!parseContentOpf(zip, contentOpfFile)) {
+  // OPF Pass
+  BookMetadataCache::BookMetadata bookMetadata;
+  if (!bookMetadataCache->beginContentOpfPass()) {
+    Serial.printf("[%lu] [EBP] Could not begin writing content.opf pass\n", millis());
+    return false;
+  }
+  if (!parseContentOpf(bookMetadata)) {
+    Serial.printf("[%lu] [EBP] Could not parse content.opf\n", millis());
+    return false;
+  }
+  if (!bookMetadataCache->endContentOpfPass()) {
+    Serial.printf("[%lu] [EBP] Could not end writing content.opf pass\n", millis());
     return false;
   }
 
-  if (!parseTocNcxFile(zip)) {
+  // TOC Pass
+  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;
+  }
+  if (!bookMetadataCache->endTocPass()) {
+    Serial.printf("[%lu] [EBP] Could not end writing toc pass\n", millis());
     return false;
   }
 
+  // Close the cache files
+  if (!bookMetadataCache->endWrite()) {
+    Serial.printf("[%lu] [EBP] Could not end writing cache\n", millis());
+    return false;
+  }
+
+  // Build final book.bin
+  if (!bookMetadataCache->buildBookBin(filepath, bookMetadata)) {
+    Serial.printf("[%lu] [EBP] Could not update mappings and sizes\n", millis());
+    return false;
+  }
+
+  if (!bookMetadataCache->cleanupTmpFiles()) {
+    Serial.printf("[%lu] [EBP] Could not cleanup tmp files - ignoring\n", millis());
+  }
+
+  // Reload the cache from disk so it's in the correct state
+  bookMetadataCache.reset(new BookMetadataCache(cachePath));
+  if (!bookMetadataCache->load()) {
+    Serial.printf("[%lu] [EBP] Failed to reload cache after writing\n", millis());
+    return false;
+  }
+
+  Serial.printf("[%lu] [EBP] Loaded ePub: %s\n", millis(), filepath.c_str());
   return true;
 }
 
-void Epub::clearCache() const { SD.rmdir(cachePath.c_str()); }
+bool Epub::clearCache() const {
+  if (!SD.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())) {
+    Serial.printf("[%lu] [EPB] Failed to clear cache\n", millis());
+    return false;
+  }
+
+  Serial.printf("[%lu] [EPB] Cache cleared successfully\n", millis());
+  return true;
+}
 
 void Epub::setupCacheDir() const {
   if (SD.exists(cachePath.c_str())) {
@@ -268,119 +253,186 @@ const std::string& Epub::getCachePath() const { return cachePath; }
 
 const std::string& Epub::getPath() const { return filepath; }
 
-const std::string& Epub::getTitle() const { return title; }
-
-const std::string& Epub::getCoverImageItem() const { return coverImageItem; }
-
-std::string 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;
-    }
+const std::string& Epub::getTitle() const {
+  static std::string blank;
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    return blank;
   }
 
-  if (!component.empty()) {
-    components.push_back(component);
-  }
-
-  std::string result;
-  for (const auto& c : components) {
-    if (!result.empty()) {
-      result += "/";
-    }
-    result += c;
-  }
-
-  return result;
+  return bookMetadataCache->coreMetadata.title;
 }
 
-uint8_t* Epub::getItemContents(const std::string& itemHref, size_t* size) const {
-  const ZipFile zip("/sd" + filepath);
-  const std::string path = normalisePath(itemHref);
+std::string Epub::getCoverBmpPath() const { return cachePath + "/cover.bmp"; }
 
-  const auto content = zip.readFileToMemory(path.c_str(), size);
+bool Epub::generateCoverBmp() const {
+  // Already generated, return true
+  if (SD.exists(getCoverBmpPath().c_str())) {
+    return true;
+  }
+
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    Serial.printf("[%lu] [EBP] Cannot generate cover BMP, cache not loaded\n", millis());
+    return false;
+  }
+
+  const auto coverImageHref = bookMetadataCache->coreMetadata.coverItemHref;
+  if (coverImageHref.empty()) {
+    Serial.printf("[%lu] [EBP] No known cover image\n", millis());
+    return false;
+  }
+
+  if (coverImageHref.substr(coverImageHref.length() - 4) == ".jpg" ||
+      coverImageHref.substr(coverImageHref.length() - 5) == ".jpeg") {
+    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)) {
+      return false;
+    }
+    readItemContentsToStream(coverImageHref, coverJpg, 1024);
+    coverJpg.close();
+
+    if (!FsHelpers::openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
+      return false;
+    }
+
+    File coverBmp;
+    if (!FsHelpers::openFileForWrite("EBP", getCoverBmpPath(), coverBmp)) {
+      coverJpg.close();
+      return false;
+    }
+    const bool success = JpegToBmpConverter::jpegFileToBmpStream(coverJpg, coverBmp);
+    coverJpg.close();
+    coverBmp.close();
+    SD.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());
+    }
+    Serial.printf("[%lu] [EBP] Generated BMP from JPG cover image, success: %s\n", millis(), success ? "yes" : "no");
+    return success;
+  } else {
+    Serial.printf("[%lu] [EBP] Cover image is not a JPG, skipping\n", millis());
+  }
+
+  return false;
+}
+
+uint8_t* Epub::readItemContentsToBytes(const std::string& itemHref, size_t* size, const bool trailingNullByte) const {
+  const ZipFile zip("/sd" + filepath);
+  const std::string path = FsHelpers::normalisePath(itemHref);
+
+  const auto content = zip.readFileToMemory(path.c_str(), size, trailingNullByte);
   if (!content) {
-    Serial.printf("Failed to read item %s\n", path.c_str());
+    Serial.printf("[%lu] [EBP] Failed to read item %s\n", millis(), path.c_str());
     return nullptr;
   }
 
   return content;
 }
 
-char* Epub::getTextItemContents(const std::string& itemHref, size_t* size) const {
+bool Epub::readItemContentsToStream(const std::string& itemHref, Print& out, const size_t chunkSize) const {
   const ZipFile zip("/sd" + filepath);
-  const std::string path = normalisePath(itemHref);
+  const std::string path = FsHelpers::normalisePath(itemHref);
 
-  const auto content = zip.readTextFileToMemory(path.c_str(), size);
-  if (!content) {
-    Serial.printf("Failed to read item %s\n", path.c_str());
-    return nullptr;
-  }
-
-  return content;
+  return zip.readFileToStream(path.c_str(), out, chunkSize);
 }
 
-int Epub::getSpineItemsCount() const { return spine.size(); }
-
-std::string& Epub::getSpineItem(const int spineIndex) {
-  if (spineIndex < 0 || spineIndex >= spine.size()) {
-    Serial.printf("getSpineItem index:%d is out of range\n", spineIndex);
-    return spine.at(0).second;
-  }
-
-  return spine.at(spineIndex).second;
+bool Epub::getItemSize(const std::string& itemHref, size_t* size) const {
+  const ZipFile zip("/sd" + filepath);
+  return getItemSize(zip, itemHref, size);
 }
 
-EpubTocEntry& Epub::getTocItem(const int tocTndex) {
-  if (tocTndex < 0 || tocTndex >= toc.size()) {
-    Serial.printf("getTocItem index:%d is out of range\n", tocTndex);
-    return toc.at(0);
-  }
-
-  return toc.at(tocTndex);
+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);
 }
 
-int Epub::getTocItemsCount() const { return toc.size(); }
+int Epub::getSpineItemsCount() const {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    return 0;
+  }
+  return bookMetadataCache->getSpineCount();
+}
+
+size_t Epub::getCumulativeSpineItemSize(const int spineIndex) const { return getSpineItem(spineIndex).cumulativeSize; }
+
+BookMetadataCache::SpineEntry Epub::getSpineItem(const int spineIndex) const {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    Serial.printf("[%lu] [EBP] getSpineItem called but cache not loaded\n", millis());
+    return {};
+  }
+
+  if (spineIndex < 0 || spineIndex >= bookMetadataCache->getSpineCount()) {
+    Serial.printf("[%lu] [EBP] getSpineItem index:%d is out of range\n", millis(), spineIndex);
+    return bookMetadataCache->getSpineEntry(0);
+  }
+
+  return bookMetadataCache->getSpineEntry(spineIndex);
+}
+
+BookMetadataCache::TocEntry Epub::getTocItem(const int tocIndex) const {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    Serial.printf("[%lu] [EBP] getTocItem called but cache not loaded\n", millis());
+    return {};
+  }
+
+  if (tocIndex < 0 || tocIndex >= bookMetadataCache->getTocCount()) {
+    Serial.printf("[%lu] [EBP] getTocItem index:%d is out of range\n", millis(), tocIndex);
+    return {};
+  }
+
+  return bookMetadataCache->getTocEntry(tocIndex);
+}
+
+int Epub::getTocItemsCount() const {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    return 0;
+  }
+
+  return bookMetadataCache->getTocCount();
+}
 
 // work out the section index for a toc index
 int Epub::getSpineIndexForTocIndex(const int tocIndex) const {
-  // the toc entry should have an href that matches the spine item
-  // so we can find the spine index by looking for the href
-  for (int i = 0; i < spine.size(); i++) {
-    if (spine[i].second == toc[tocIndex].href) {
-      return i;
-    }
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded()) {
+    Serial.printf("[%lu] [EBP] getSpineIndexForTocIndex called but cache not loaded\n", millis());
+    return 0;
   }
 
-  Serial.println("Section not found");
-  // not found - default to the start of the book
-  return 0;
-}
-
-int Epub::getTocIndexForSpineIndex(const int spineIndex) const {
-  // the toc entry should have an href that matches the spine item
-  // so we can find the toc index by looking for the href
-  for (int i = 0; i < toc.size(); i++) {
-    if (toc[i].href == spine[spineIndex].second) {
-      return i;
-    }
+  if (tocIndex < 0 || tocIndex >= bookMetadataCache->getTocCount()) {
+    Serial.printf("[%lu] [EBP] getSpineIndexForTocIndex: tocIndex %d out of range\n", millis(), tocIndex);
+    return 0;
   }
 
-  Serial.println("TOC item not found");
-  // not found - default to first item
-  return 0;
+  const int spineIndex = bookMetadataCache->getTocEntry(tocIndex).spineIndex;
+  if (spineIndex < 0) {
+    Serial.printf("[%lu] [EBP] Section not found for TOC index %d\n", millis(), tocIndex);
+    return 0;
+  }
+
+  return spineIndex;
+}
+
+int Epub::getTocIndexForSpineIndex(const int spineIndex) const { return getSpineItem(spineIndex).tocIndex; }
+
+size_t Epub::getBookSize() const {
+  if (!bookMetadataCache || !bookMetadataCache->isLoaded() || bookMetadataCache->getSpineCount() == 0) {
+    return 0;
+  }
+  return getCumulativeSpineItemSize(getSpineItemsCount() - 1);
+}
+
+// Calculate progress in book
+uint8_t Epub::calculateProgress(const int currentSpineIndex, const float currentSpineRead) const {
+  const size_t bookSize = getBookSize();
+  if (bookSize == 0) {
+    return 0;
+  }
+  const size_t prevChapterSize = (currentSpineIndex >= 1) ? getCumulativeSpineItemSize(currentSpineIndex - 1) : 0;
+  const size_t curChapterSize = getCumulativeSpineItemSize(currentSpineIndex) - prevChapterSize;
+  const size_t sectionProgSize = currentSpineRead * curChapterSize;
+  return round(static_cast<float>(prevChapterSize + sectionProgSize) / bookSize * 100.0);
 }

lib/Epub/Epub.h

@@ -1,46 +1,30 @@
 #pragma once
-#include <HardwareSerial.h>
-#include <tinyxml2.h>
 
+#include <memory>
 #include <string>
 #include <unordered_map>
 #include <vector>
 
+#include "Epub/BookMetadataCache.h"
+
 class ZipFile;
 
-class EpubTocEntry {
- public:
-  std::string title;
-  std::string href;
-  std::string anchor;
-  int level;
-  EpubTocEntry(std::string title, std::string href, std::string anchor, const int level)
-      : title(std::move(title)), href(std::move(href)), anchor(std::move(anchor)), level(level) {}
-};
-
 class Epub {
-  // the title read from the EPUB meta data
-  std::string title;
-  // the cover image
-  std::string coverImageItem;
   // the ncx file
   std::string tocNcxItem;
   // where is the EPUBfile?
   std::string filepath;
-  // the spine of the EPUB file
-  std::vector<std::pair<std::string, std::string>> spine;
-  // the toc of the EPUB file
-  std::vector<EpubTocEntry> toc;
   // the base path for items in the EPUB file
   std::string contentBasePath;
   // Uniq cache key based on filepath
   std::string cachePath;
+  // Spine and TOC cache
+  std::unique_ptr<BookMetadataCache> bookMetadataCache;
 
-  // find the path for the content.opf file
-  static bool findContentOpfFile(const ZipFile& zip, std::string& contentOpfFile);
-  bool parseContentOpf(ZipFile& zip, std::string& content_opf_file);
-  bool parseTocNcxFile(const ZipFile& zip);
-  void recursivelyParseNavMap(tinyxml2::XMLElement* element);
+  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)) {
@@ -50,18 +34,25 @@ class Epub {
   ~Epub() = default;
   std::string& getBasePath() { return contentBasePath; }
   bool load();
-  void clearCache() const;
+  bool clearCache() const;
   void setupCacheDir() const;
   const std::string& getCachePath() const;
   const std::string& getPath() const;
   const std::string& getTitle() const;
-  const std::string& getCoverImageItem() const;
-  uint8_t* getItemContents(const std::string& itemHref, size_t* size = nullptr) const;
-  char* getTextItemContents(const std::string& itemHref, size_t* size = nullptr) const;
-  std::string& getSpineItem(int spineIndex);
+  std::string getCoverBmpPath() const;
+  bool generateCoverBmp() const;
+  uint8_t* readItemContentsToBytes(const std::string& itemHref, size_t* size = nullptr,
+                                   bool trailingNullByte = false) const;
+  bool readItemContentsToStream(const std::string& itemHref, Print& out, size_t chunkSize) const;
+  bool getItemSize(const std::string& itemHref, size_t* size) const;
+  BookMetadataCache::SpineEntry getSpineItem(int spineIndex) const;
+  BookMetadataCache::TocEntry getTocItem(int tocIndex) const;
   int getSpineItemsCount() const;
-  EpubTocEntry& getTocItem(int tocTndex);
   int getTocItemsCount() const;
   int getSpineIndexForTocIndex(int tocIndex) const;
   int getTocIndexForSpineIndex(int spineIndex) const;
+  size_t getCumulativeSpineItemSize(int spineIndex) const;
+
+  size_t getBookSize() const;
+  uint8_t calculateProgress(const int currentSpineIndex, const float currentSpineRead) const;
 };

lib/Epub/Epub/BookMetadataCache.cpp

@@ -0,0 +1,326 @@
+#include "BookMetadataCache.h"
+
+#include <HardwareSerial.h>
+#include <SD.h>
+#include <Serialization.h>
+#include <ZipFile.h>
+
+#include <vector>
+
+#include "FsHelpers.h"
+
+namespace {
+constexpr uint8_t BOOK_CACHE_VERSION = 1;
+constexpr char bookBinFile[] = "/book.bin";
+constexpr char tmpSpineBinFile[] = "/spine.bin.tmp";
+constexpr char tmpTocBinFile[] = "/toc.bin.tmp";
+}  // namespace
+
+/* ============= WRITING / BUILDING FUNCTIONS ================ */
+
+bool BookMetadataCache::beginWrite() {
+  buildMode = true;
+  spineCount = 0;
+  tocCount = 0;
+  Serial.printf("[%lu] [BMC] Entering write mode\n", millis());
+  return true;
+}
+
+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);
+}
+
+bool BookMetadataCache::endContentOpfPass() {
+  spineFile.close();
+  return true;
+}
+
+bool BookMetadataCache::beginTocPass() {
+  Serial.printf("[%lu] [BMC] Beginning toc pass\n", millis());
+
+  // Open spine file for reading
+  if (!FsHelpers::openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+    return false;
+  }
+  if (!FsHelpers::openFileForWrite("BMC", cachePath + tmpTocBinFile, tocFile)) {
+    spineFile.close();
+    return false;
+  }
+  return true;
+}
+
+bool BookMetadataCache::endTocPass() {
+  tocFile.close();
+  spineFile.close();
+  return true;
+}
+
+bool BookMetadataCache::endWrite() {
+  if (!buildMode) {
+    Serial.printf("[%lu] [BMC] endWrite called but not in build mode\n", millis());
+    return false;
+  }
+
+  buildMode = false;
+  Serial.printf("[%lu] [BMC] Wrote %d spine, %d TOC entries\n", millis(), spineCount, tocCount);
+  return true;
+}
+
+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)) {
+    return false;
+  }
+
+  if (!FsHelpers::openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+    bookFile.close();
+    return false;
+  }
+
+  if (!FsHelpers::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;
+
+  // Header A
+  serialization::writePod(bookFile, BOOK_CACHE_VERSION);
+  serialization::writePod(bookFile, lutOffset);
+  serialization::writePod(bookFile, spineCount);
+  serialization::writePod(bookFile, tocCount);
+  // Metadata
+  serialization::writeString(bookFile, metadata.title);
+  serialization::writeString(bookFile, metadata.author);
+  serialization::writeString(bookFile, metadata.coverItemHref);
+
+  // Loop through spine entries, writing LUT positions
+  spineFile.seek(0);
+  for (int i = 0; i < spineCount; i++) {
+    auto pos = spineFile.position();
+    auto spineEntry = readSpineEntry(spineFile);
+    serialization::writePod(bookFile, pos + lutOffset + lutSize);
+  }
+
+  // Loop through toc entries, writing LUT positions
+  tocFile.seek(0);
+  for (int i = 0; i < tocCount; i++) {
+    auto pos = tocFile.position();
+    auto tocEntry = readTocEntry(tocFile);
+    serialization::writePod(bookFile, pos + lutOffset + lutSize + 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;
+  spineFile.seek(0);
+  for (int i = 0; i < spineCount; i++) {
+    auto spineEntry = readSpineEntry(spineFile);
+
+    tocFile.seek(0);
+    for (int j = 0; j < tocCount; j++) {
+      auto tocEntry = readTocEntry(tocFile);
+      if (tocEntry.spineIndex == i) {
+        spineEntry.tocIndex = j;
+        break;
+      }
+    }
+
+    // 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());
+    }
+
+    // Calculate size for cumulative size
+    size_t itemSize = 0;
+    const std::string path = FsHelpers::normalisePath(spineEntry.href);
+    if (zip.getInflatedFileSize(path.c_str(), &itemSize)) {
+      cumSize += itemSize;
+      spineEntry.cumulativeSize = cumSize;
+    } else {
+      Serial.printf("[%lu] [BMC] Warning: Could not get size for spine item: %s\n", millis(), path.c_str());
+    }
+
+    // Write out spine data to book.bin
+    writeSpineEntry(bookFile, spineEntry);
+  }
+
+  // Loop through toc entries from toc file writing to book.bin
+  tocFile.seek(0);
+  for (int i = 0; i < tocCount; i++) {
+    auto tocEntry = readTocEntry(tocFile);
+    writeTocEntry(bookFile, tocEntry);
+  }
+
+  bookFile.close();
+  spineFile.close();
+  tocFile.close();
+
+  Serial.printf("[%lu] [BMC] Successfully built book.bin\n", millis());
+  return true;
+}
+
+bool BookMetadataCache::cleanupTmpFiles() const {
+  if (SD.exists((cachePath + tmpSpineBinFile).c_str())) {
+    SD.remove((cachePath + tmpSpineBinFile).c_str());
+  }
+  if (SD.exists((cachePath + tmpTocBinFile).c_str())) {
+    SD.remove((cachePath + tmpTocBinFile).c_str());
+  }
+  return true;
+}
+
+size_t BookMetadataCache::writeSpineEntry(File& file, const SpineEntry& entry) const {
+  const auto 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();
+  serialization::writeString(file, entry.title);
+  serialization::writeString(file, entry.href);
+  serialization::writeString(file, entry.anchor);
+  serialization::writePod(file, entry.level);
+  serialization::writePod(file, entry.spineIndex);
+  return pos;
+}
+
+// Note: for the LUT to be accurate, this **MUST** be called for all spine items before `addTocEntry` is ever called
+// this is because in this function we're marking positions of the items
+void BookMetadataCache::createSpineEntry(const std::string& href) {
+  if (!buildMode || !spineFile) {
+    Serial.printf("[%lu] [BMC] createSpineEntry called but not in build mode\n", millis());
+    return;
+  }
+
+  const SpineEntry entry(href, 0, -1);
+  writeSpineEntry(spineFile, entry);
+  spineCount++;
+}
+
+void BookMetadataCache::createTocEntry(const std::string& title, const std::string& href, const std::string& anchor,
+                                       const uint8_t level) {
+  if (!buildMode || !tocFile || !spineFile) {
+    Serial.printf("[%lu] [BMC] createTocEntry called but not in build mode\n", millis());
+    return;
+  }
+
+  int spineIndex = -1;
+  // find spine index
+  spineFile.seek(0);
+  for (int i = 0; i < spineCount; i++) {
+    auto spineEntry = readSpineEntry(spineFile);
+    if (spineEntry.href == href) {
+      spineIndex = i;
+      break;
+    }
+  }
+
+  if (spineIndex == -1) {
+    Serial.printf("[%lu] [BMC] addTocEntry: Could not find spine item for TOC href %s\n", millis(), href.c_str());
+  }
+
+  const TocEntry entry(title, href, anchor, level, spineIndex);
+  writeTocEntry(tocFile, entry);
+  tocCount++;
+}
+
+/* ============= READING / LOADING FUNCTIONS ================ */
+
+bool BookMetadataCache::load() {
+  if (!FsHelpers::openFileForRead("BMC", cachePath + bookBinFile, bookFile)) {
+    return false;
+  }
+
+  uint8_t version;
+  serialization::readPod(bookFile, version);
+  if (version != BOOK_CACHE_VERSION) {
+    Serial.printf("[%lu] [BMC] Cache version mismatch: expected %d, got %d\n", millis(), BOOK_CACHE_VERSION, version);
+    bookFile.close();
+    return false;
+  }
+
+  serialization::readPod(bookFile, lutOffset);
+  serialization::readPod(bookFile, spineCount);
+  serialization::readPod(bookFile, tocCount);
+
+  serialization::readString(bookFile, coreMetadata.title);
+  serialization::readString(bookFile, coreMetadata.author);
+  serialization::readString(bookFile, coreMetadata.coverItemHref);
+
+  loaded = true;
+  Serial.printf("[%lu] [BMC] Loaded cache data: %d spine, %d TOC entries\n", millis(), spineCount, tocCount);
+  return true;
+}
+
+BookMetadataCache::SpineEntry BookMetadataCache::getSpineEntry(const int index) {
+  if (!loaded) {
+    Serial.printf("[%lu] [BMC] getSpineEntry called but cache not loaded\n", millis());
+    return {};
+  }
+
+  if (index < 0 || index >= static_cast<int>(spineCount)) {
+    Serial.printf("[%lu] [BMC] getSpineEntry index %d out of range\n", millis(), index);
+    return {};
+  }
+
+  // Seek to spine LUT item, read from LUT and get out data
+  bookFile.seek(lutOffset + sizeof(size_t) * index);
+  size_t spineEntryPos;
+  serialization::readPod(bookFile, spineEntryPos);
+  bookFile.seek(spineEntryPos);
+  return readSpineEntry(bookFile);
+}
+
+BookMetadataCache::TocEntry BookMetadataCache::getTocEntry(const int index) {
+  if (!loaded) {
+    Serial.printf("[%lu] [BMC] getTocEntry called but cache not loaded\n", millis());
+    return {};
+  }
+
+  if (index < 0 || index >= static_cast<int>(tocCount)) {
+    Serial.printf("[%lu] [BMC] getTocEntry index %d out of range\n", millis(), index);
+    return {};
+  }
+
+  // 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;
+  serialization::readPod(bookFile, tocEntryPos);
+  bookFile.seek(tocEntryPos);
+  return readTocEntry(bookFile);
+}
+
+BookMetadataCache::SpineEntry BookMetadataCache::readSpineEntry(File& file) const {
+  SpineEntry entry;
+  serialization::readString(file, entry.href);
+  serialization::readPod(file, entry.cumulativeSize);
+  serialization::readPod(file, entry.tocIndex);
+  return entry;
+}
+
+BookMetadataCache::TocEntry BookMetadataCache::readTocEntry(File& file) const {
+  TocEntry entry;
+  serialization::readString(file, entry.title);
+  serialization::readString(file, entry.href);
+  serialization::readString(file, entry.anchor);
+  serialization::readPod(file, entry.level);
+  serialization::readPod(file, entry.spineIndex);
+  return entry;
+}

lib/Epub/Epub/BookMetadataCache.h

@@ -0,0 +1,87 @@
+#pragma once
+
+#include <SD.h>
+
+#include <string>
+
+class BookMetadataCache {
+ public:
+  struct BookMetadata {
+    std::string title;
+    std::string author;
+    std::string coverItemHref;
+  };
+
+  struct SpineEntry {
+    std::string href;
+    size_t cumulativeSize;
+    int16_t tocIndex;
+
+    SpineEntry() : cumulativeSize(0), tocIndex(-1) {}
+    SpineEntry(std::string href, const size_t cumulativeSize, const int16_t tocIndex)
+        : href(std::move(href)), cumulativeSize(cumulativeSize), tocIndex(tocIndex) {}
+  };
+
+  struct TocEntry {
+    std::string title;
+    std::string href;
+    std::string anchor;
+    uint8_t level;
+    int16_t spineIndex;
+
+    TocEntry() : level(0), spineIndex(-1) {}
+    TocEntry(std::string title, std::string href, std::string anchor, const uint8_t level, const int16_t spineIndex)
+        : title(std::move(title)),
+          href(std::move(href)),
+          anchor(std::move(anchor)),
+          level(level),
+          spineIndex(spineIndex) {}
+  };
+
+ private:
+  std::string cachePath;
+  size_t lutOffset;
+  uint16_t spineCount;
+  uint16_t tocCount;
+  bool loaded;
+  bool buildMode;
+
+  File bookFile;
+  // Temp file handles during build
+  File spineFile;
+  File 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;
+
+ public:
+  BookMetadata coreMetadata;
+
+  explicit BookMetadataCache(std::string cachePath)
+      : cachePath(std::move(cachePath)), lutOffset(0), spineCount(0), tocCount(0), loaded(false), buildMode(false) {}
+  ~BookMetadataCache() = default;
+
+  // Building phase (stream to disk immediately)
+  bool beginWrite();
+  bool beginContentOpfPass();
+  void createSpineEntry(const std::string& href);
+  bool endContentOpfPass();
+  bool beginTocPass();
+  void createTocEntry(const std::string& title, const std::string& href, const std::string& anchor, uint8_t level);
+  bool endTocPass();
+  bool endWrite();
+  bool cleanupTmpFiles() const;
+
+  // Post-processing to update mappings and sizes
+  bool buildBookBin(const std::string& epubPath, const BookMetadata& metadata);
+
+  // Reading phase (read mode)
+  bool load();
+  SpineEntry getSpineEntry(int index);
+  TocEntry getTocEntry(int index);
+  int getSpineCount() const { return spineCount; }
+  int getTocCount() const { return tocCount; }
+  bool isLoaded() const { return loaded; }
+};

lib/Epub/Epub/EpubHtmlParser.cpp

@@ -1,181 +0,0 @@
-#include "EpubHtmlParser.h"
-
-#include <EpdRenderer.h>
-#include <HardwareSerial.h>
-
-#include "Page.h"
-#include "htmlEntities.h"
-
-const char* HEADER_TAGS[] = {"h1", "h2", "h3", "h4", "h5", "h6"};
-constexpr int NUM_HEADER_TAGS = sizeof(HEADER_TAGS) / sizeof(HEADER_TAGS[0]);
-
-const char* BLOCK_TAGS[] = {"p", "li", "div", "br"};
-constexpr int NUM_BLOCK_TAGS = sizeof(BLOCK_TAGS) / sizeof(BLOCK_TAGS[0]);
-
-const char* BOLD_TAGS[] = {"b"};
-constexpr int NUM_BOLD_TAGS = sizeof(BOLD_TAGS) / sizeof(BOLD_TAGS[0]);
-
-const char* ITALIC_TAGS[] = {"i"};
-constexpr int NUM_ITALIC_TAGS = sizeof(ITALIC_TAGS) / sizeof(ITALIC_TAGS[0]);
-
-const char* IMAGE_TAGS[] = {"img"};
-constexpr int NUM_IMAGE_TAGS = sizeof(IMAGE_TAGS) / sizeof(IMAGE_TAGS[0]);
-
-const char* SKIP_TAGS[] = {"head", "table"};
-constexpr int NUM_SKIP_TAGS = sizeof(SKIP_TAGS) / sizeof(SKIP_TAGS[0]);
-
-// given the start and end of a tag, check to see if it matches a known tag
-bool matches(const char* tag_name, const char* possible_tags[], const int possible_tag_count) {
-  for (int i = 0; i < possible_tag_count; i++) {
-    if (strcmp(tag_name, possible_tags[i]) == 0) {
-      return true;
-    }
-  }
-  return false;
-}
-
-// start a new text block if needed
-void EpubHtmlParser::startNewTextBlock(const BLOCK_STYLE style) {
-  if (currentTextBlock) {
-    // already have a text block running and it is empty - just reuse it
-    if (currentTextBlock->isEmpty()) {
-      currentTextBlock->set_style(style);
-      return;
-    }
-
-    currentTextBlock->finish();
-    makePages();
-    delete currentTextBlock;
-  }
-  currentTextBlock = new TextBlock(style);
-}
-
-bool EpubHtmlParser::VisitEnter(const tinyxml2::XMLElement& element, const tinyxml2::XMLAttribute* firstAttribute) {
-  const char* tag_name = element.Name();
-  if (matches(tag_name, IMAGE_TAGS, NUM_IMAGE_TAGS)) {
-    const char* src = element.Attribute("src");
-    if (src) {
-      // don't leave an empty text block in the list
-      // const BLOCK_STYLE style = currentTextBlock->get_style();
-      if (currentTextBlock->isEmpty()) {
-        delete currentTextBlock;
-        currentTextBlock = nullptr;
-      }
-      // TODO: Fix this
-      // blocks.push_back(new ImageBlock(m_base_path + src));
-      // start a new text block - with the same style as before
-      // startNewTextBlock(style);
-    } else {
-      // ESP_LOGE(TAG, "Could not find src attribute");
-    }
-    return false;
-  }
-
-  if (matches(tag_name, SKIP_TAGS, NUM_SKIP_TAGS)) {
-    return false;
-  }
-
-  // Serial.printf("Text: %s\n", element.GetText());
-
-  if (matches(tag_name, HEADER_TAGS, NUM_HEADER_TAGS)) {
-    insideBoldTag = true;
-    startNewTextBlock(CENTER_ALIGN);
-  } else if (matches(tag_name, BLOCK_TAGS, NUM_BLOCK_TAGS)) {
-    if (strcmp(tag_name, "br") == 0) {
-      startNewTextBlock(currentTextBlock->get_style());
-    } else {
-      startNewTextBlock(JUSTIFIED);
-    }
-  } else if (matches(tag_name, BOLD_TAGS, NUM_BOLD_TAGS)) {
-    insideBoldTag = true;
-  } else if (matches(tag_name, ITALIC_TAGS, NUM_ITALIC_TAGS)) {
-    insideItalicTag = true;
-  }
-  return true;
-}
-/// Visit a text node.
-bool EpubHtmlParser::Visit(const tinyxml2::XMLText& text) {
-  const char* content = text.Value();
-  currentTextBlock->addSpan(replaceHtmlEntities(content), insideBoldTag, insideItalicTag);
-  return true;
-}
-
-bool EpubHtmlParser::VisitExit(const tinyxml2::XMLElement& element) {
-  const char* tag_name = element.Name();
-  if (matches(tag_name, HEADER_TAGS, NUM_HEADER_TAGS)) {
-    insideBoldTag = false;
-  } else if (matches(tag_name, BLOCK_TAGS, NUM_BLOCK_TAGS)) {
-    // nothing to do
-  } else if (matches(tag_name, BOLD_TAGS, NUM_BOLD_TAGS)) {
-    insideBoldTag = false;
-  } else if (matches(tag_name, ITALIC_TAGS, NUM_ITALIC_TAGS)) {
-    insideItalicTag = false;
-  }
-  return true;
-}
-
-bool EpubHtmlParser::parseAndBuildPages() {
-  startNewTextBlock(JUSTIFIED);
-  tinyxml2::XMLDocument doc(false, tinyxml2::COLLAPSE_WHITESPACE);
-
-  const tinyxml2::XMLError result = doc.LoadFile(filepath);
-  if (result != tinyxml2::XML_SUCCESS) {
-    Serial.printf("Failed to load file, Error: %s\n", tinyxml2::XMLDocument::ErrorIDToName(result));
-    return false;
-  }
-
-  doc.Accept(this);
-  if (currentTextBlock) {
-    makePages();
-    completePageFn(currentPage);
-    currentPage = nullptr;
-    delete currentTextBlock;
-    currentTextBlock = nullptr;
-  }
-
-  return true;
-}
-
-void EpubHtmlParser::makePages() {
-  if (!currentTextBlock) {
-    Serial.println("!! No text block to make pages for !!");
-    return;
-  }
-
-  if (!currentPage) {
-    currentPage = new Page();
-  }
-
-  const int lineHeight = renderer->getLineHeight();
-  const int pageHeight = renderer->getPageHeight();
-
-  // Long running task, make sure to let other things happen
-  vTaskDelay(1);
-
-  if (currentTextBlock->getType() == TEXT_BLOCK) {
-    const auto lines = currentTextBlock->splitIntoLines(renderer);
-
-    for (const auto line : lines) {
-      if (currentPage->nextY + lineHeight > pageHeight) {
-        completePageFn(currentPage);
-        currentPage = new Page();
-      }
-
-      currentPage->elements.push_back(new PageLine(line, currentPage->nextY));
-      currentPage->nextY += lineHeight;
-    }
-    // TODO: Fix spacing between paras
-    // add some extra line between blocks
-    currentPage->nextY += lineHeight / 2;
-  }
-  // TODO: Image block support
-  // if (block->getType() == BlockType::IMAGE_BLOCK) {
-  //   ImageBlock *imageBlock = (ImageBlock *)block;
-  //   if (y + imageBlock->height > page_height) {
-  //     pages.push_back(new Page());
-  //     y = 0;
-  //   }
-  //   pages.back()->elements.push_back(new PageImage(imageBlock, y));
-  //   y += imageBlock->height;
-  // }
-}

lib/Epub/Epub/EpubHtmlParser.h

@@ -1,34 +0,0 @@
-#pragma once
-#include <tinyxml2.h>
-
-#include <functional>
-
-#include "blocks/TextBlock.h"
-
-class Page;
-class EpdRenderer;
-
-class EpubHtmlParser final : public tinyxml2::XMLVisitor {
-  const char* filepath;
-  EpdRenderer* renderer;
-  std::function<void(Page*)> completePageFn;
-
-  bool insideBoldTag = false;
-  bool insideItalicTag = false;
-  TextBlock* currentTextBlock = nullptr;
-  Page* currentPage = nullptr;
-
-  void startNewTextBlock(BLOCK_STYLE style);
-  void makePages();
-
-  // xml parser callbacks
-  bool VisitEnter(const tinyxml2::XMLElement& element, const tinyxml2::XMLAttribute* firstAttribute) override;
-  bool Visit(const tinyxml2::XMLText& text) override;
-  bool VisitExit(const tinyxml2::XMLElement& element) override;
-  // xml parser callbacks
- public:
-  explicit EpubHtmlParser(const char* filepath, EpdRenderer* renderer, const std::function<void(Page*)>& completePageFn)
-      : filepath(filepath), renderer(renderer), completePageFn(completePageFn) {}
-  ~EpubHtmlParser() override = default;
-  bool parseAndBuildPages();
-};

lib/Epub/Epub/FsHelpers.cpp

@@ -0,0 +1,92 @@
+#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

@@ -0,0 +1,12 @@
+#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,61 +3,72 @@
 #include <HardwareSerial.h>
 #include <Serialization.h>
 
-void PageLine::render(EpdRenderer* renderer) { block->render(renderer, 0, yPos); }
+namespace {
+constexpr uint8_t PAGE_FILE_VERSION = 3;
+}
 
-void PageLine::serialize(std::ostream& os) {
-  serialization::writePod(os, yPos);
+void PageLine::render(GfxRenderer& renderer, const int fontId) { block->render(renderer, fontId, xPos, yPos); }
+
+void PageLine::serialize(File& file) {
+  serialization::writePod(file, xPos);
+  serialization::writePod(file, yPos);
 
   // serialize TextBlock pointed to by PageLine
-  block->serialize(os);
+  block->serialize(file);
 }
 
-PageLine* PageLine::deserialize(std::istream& is) {
-  int32_t yPos;
-  serialization::readPod(is, yPos);
+std::unique_ptr<PageLine> PageLine::deserialize(File& file) {
+  int16_t xPos;
+  int16_t yPos;
+  serialization::readPod(file, xPos);
+  serialization::readPod(file, yPos);
 
-  const auto tb = TextBlock::deserialize(is);
-  return new PageLine(tb, yPos);
+  auto tb = TextBlock::deserialize(file);
+  return std::unique_ptr<PageLine>(new PageLine(std::move(tb), xPos, yPos));
 }
 
-void Page::render(EpdRenderer* renderer) const {
-  const auto start = millis();
-  for (const auto element : elements) {
-    element->render(renderer);
+void Page::render(GfxRenderer& renderer, const int fontId) const {
+  for (auto& element : elements) {
+    element->render(renderer, fontId);
   }
-  Serial.printf("Rendered page elements (%u) in %dms\n", elements.size(), millis() - start);
 }
 
-void Page::serialize(std::ostream& os) const {
-  serialization::writePod(os, nextY);
+void Page::serialize(File& file) const {
+  serialization::writePod(file, PAGE_FILE_VERSION);
 
   const uint32_t count = elements.size();
-  serialization::writePod(os, count);
+  serialization::writePod(file, count);
 
-  for (auto* el : elements) {
+  for (const auto& el : elements) {
     // Only PageLine exists currently
-    serialization::writePod(os, static_cast<uint8_t>(TAG_PageLine));
-    static_cast<PageLine*>(el)->serialize(os);
+    serialization::writePod(file, static_cast<uint8_t>(TAG_PageLine));
+    el->serialize(file);
   }
 }
 
-Page* Page::deserialize(std::istream& is) {
-  auto* page = new Page();
+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;
+  }
 
-  serialization::readPod(is, page->nextY);
+  auto page = std::unique_ptr<Page>(new Page());
 
   uint32_t count;
-  serialization::readPod(is, count);
+  serialization::readPod(file, count);
 
   for (uint32_t i = 0; i < count; i++) {
     uint8_t tag;
-    serialization::readPod(is, tag);
+    serialization::readPod(file, tag);
 
     if (tag == TAG_PageLine) {
-      auto* pl = PageLine::deserialize(is);
-      page->elements.push_back(pl);
+      auto pl = PageLine::deserialize(file);
+      page->elements.push_back(std::move(pl));
     } else {
-      throw std::runtime_error("Unknown PageElement tag");
+      Serial.printf("[%lu] [PGE] Deserialization failed: Unknown tag %u\n", millis(), tag);
+      return nullptr;
     }
   }
 

lib/Epub/Epub/Page.h

@@ -1,4 +1,9 @@
 #pragma once
+#include <FS.h>
+
+#include <utility>
+#include <vector>
+
 #include "blocks/TextBlock.h"
 
 enum PageElementTag : uint8_t {
@@ -8,36 +13,31 @@ enum PageElementTag : uint8_t {
 // represents something that has been added to a page
 class PageElement {
  public:
-  int yPos;
-  explicit PageElement(const int yPos) : yPos(yPos) {}
+  int16_t xPos;
+  int16_t yPos;
+  explicit PageElement(const int16_t xPos, const int16_t yPos) : xPos(xPos), yPos(yPos) {}
   virtual ~PageElement() = default;
-  virtual void render(EpdRenderer* renderer) = 0;
-  virtual void serialize(std::ostream& os) = 0;
+  virtual void render(GfxRenderer& renderer, int fontId) = 0;
+  virtual void serialize(File& file) = 0;
 };
 
 // a line from a block element
 class PageLine final : public PageElement {
-  const TextBlock* block;
+  std::shared_ptr<TextBlock> block;
 
  public:
-  PageLine(const TextBlock* block, const int yPos) : PageElement(yPos), block(block) {}
-  ~PageLine() override { delete block; }
-  void render(EpdRenderer* renderer) override;
-  void serialize(std::ostream& os) override;
-  static PageLine* deserialize(std::istream& is);
+  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) override;
+  void serialize(File& file) override;
+  static std::unique_ptr<PageLine> deserialize(File& file);
 };
 
 class Page {
  public:
-  int nextY = 0;
   // the list of block index and line numbers on this page
-  std::vector<PageElement*> elements;
-  void render(EpdRenderer* renderer) const;
-  ~Page() {
-    for (const auto element : elements) {
-      delete element;
-    }
-  }
-  void serialize(std::ostream& os) const;
-  static Page* deserialize(std::istream& is);
+  std::vector<std::shared_ptr<PageElement>> elements;
+  void render(GfxRenderer& renderer, int fontId) const;
+  void serialize(File& file) const;
+  static std::unique_ptr<Page> deserialize(File& file);
 };

lib/Epub/Epub/ParsedText.cpp

@@ -0,0 +1,182 @@
+#include "ParsedText.h"
+
+#include <GfxRenderer.h>
+
+#include <algorithm>
+#include <cmath>
+#include <functional>
+#include <limits>
+#include <vector>
+
+constexpr int MAX_COST = std::numeric_limits<int>::max();
+
+void ParsedText::addWord(std::string word, const EpdFontStyle fontStyle) {
+  if (word.empty()) return;
+
+  words.push_back(std::move(word));
+  wordStyles.push_back(fontStyle);
+}
+
+// Consumes data to minimize memory usage
+void ParsedText::layoutAndExtractLines(const GfxRenderer& renderer, const int fontId, const int horizontalMargin,
+                                       const std::function<void(std::shared_ptr<TextBlock>)>& processLine,
+                                       const bool includeLastLine) {
+  if (words.empty()) {
+    return;
+  }
+
+  const int pageWidth = renderer.getScreenWidth() - horizontalMargin;
+  const int spaceWidth = renderer.getSpaceWidth(fontId);
+  const auto wordWidths = calculateWordWidths(renderer, fontId);
+  const auto lineBreakIndices = computeLineBreaks(pageWidth, spaceWidth, wordWidths);
+  const size_t lineCount = includeLastLine ? lineBreakIndices.size() : lineBreakIndices.size() - 1;
+
+  for (size_t i = 0; i < lineCount; ++i) {
+    extractLine(i, pageWidth, spaceWidth, wordWidths, lineBreakIndices, processLine);
+  }
+}
+
+std::vector<uint16_t> ParsedText::calculateWordWidths(const GfxRenderer& renderer, const int fontId) {
+  const size_t totalWordCount = words.size();
+
+  std::vector<uint16_t> wordWidths;
+  wordWidths.reserve(totalWordCount);
+
+  // add em-space at the beginning of first word in paragraph to indent
+  if (!extraParagraphSpacing) {
+    std::string& first_word = words.front();
+    first_word.insert(0, "\xe2\x80\x83");
+  }
+
+  auto wordsIt = words.begin();
+  auto wordStylesIt = wordStyles.begin();
+
+  while (wordsIt != words.end()) {
+    wordWidths.push_back(renderer.getTextWidth(fontId, wordsIt->c_str(), *wordStylesIt));
+
+    std::advance(wordsIt, 1);
+    std::advance(wordStylesIt, 1);
+  }
+
+  return wordWidths;
+}
+
+std::vector<size_t> ParsedText::computeLineBreaks(const int pageWidth, const int spaceWidth,
+                                                  const std::vector<uint16_t>& wordWidths) const {
+  const size_t totalWordCount = words.size();
+
+  // DP table to store the minimum badness (cost) of lines starting at index i
+  std::vector<int> dp(totalWordCount);
+  // 'ans[i]' stores the index 'j' of the *last word* in the optimal line starting at 'i'
+  std::vector<size_t> ans(totalWordCount);
+
+  // Base Case
+  dp[totalWordCount - 1] = 0;
+  ans[totalWordCount - 1] = totalWordCount - 1;
+
+  for (int i = totalWordCount - 2; i >= 0; --i) {
+    int currlen = -spaceWidth;
+    dp[i] = MAX_COST;
+
+    for (size_t j = i; j < totalWordCount; ++j) {
+      // Current line length: previous width + space + current word width
+      currlen += wordWidths[j] + spaceWidth;
+
+      if (currlen > pageWidth) {
+        break;
+      }
+
+      int cost;
+      if (j == totalWordCount - 1) {
+        cost = 0;  // Last line
+      } else {
+        const int remainingSpace = pageWidth - currlen;
+        // Use long long for the square to prevent overflow
+        const long long cost_ll = static_cast<long long>(remainingSpace) * remainingSpace + dp[j + 1];
+
+        if (cost_ll > MAX_COST) {
+          cost = MAX_COST;
+        } else {
+          cost = static_cast<int>(cost_ll);
+        }
+      }
+
+      if (cost < dp[i]) {
+        dp[i] = cost;
+        ans[i] = j;  // j is the index of the last word in this optimal line
+      }
+    }
+  }
+
+  // Stores the index of the word that starts the next line (last_word_index + 1)
+  std::vector<size_t> lineBreakIndices;
+  size_t currentWordIndex = 0;
+  constexpr size_t MAX_LINES = 1000;
+
+  while (currentWordIndex < totalWordCount) {
+    if (lineBreakIndices.size() >= MAX_LINES) {
+      break;
+    }
+
+    size_t nextBreakIndex = ans[currentWordIndex] + 1;
+    lineBreakIndices.push_back(nextBreakIndex);
+
+    currentWordIndex = nextBreakIndex;
+  }
+
+  return lineBreakIndices;
+}
+
+void ParsedText::extractLine(const size_t breakIndex, const int pageWidth, const int spaceWidth,
+                             const std::vector<uint16_t>& wordWidths, const std::vector<size_t>& lineBreakIndices,
+                             const std::function<void(std::shared_ptr<TextBlock>)>& processLine) {
+  const size_t lineBreak = lineBreakIndices[breakIndex];
+  const size_t lastBreakAt = breakIndex > 0 ? lineBreakIndices[breakIndex - 1] : 0;
+  const size_t lineWordCount = lineBreak - lastBreakAt;
+
+  // Calculate total word width for this line
+  int lineWordWidthSum = 0;
+  for (size_t i = lastBreakAt; i < lineBreak; i++) {
+    lineWordWidthSum += wordWidths[i];
+  }
+
+  // Calculate spacing
+  const int spareSpace = pageWidth - lineWordWidthSum;
+
+  int spacing = spaceWidth;
+  const bool isLastLine = breakIndex == lineBreakIndices.size() - 1;
+
+  if (style == TextBlock::JUSTIFIED && !isLastLine && lineWordCount >= 2) {
+    spacing = spareSpace / (lineWordCount - 1);
+  }
+
+  // Calculate initial x position
+  uint16_t xpos = 0;
+  if (style == TextBlock::RIGHT_ALIGN) {
+    xpos = spareSpace - (lineWordCount - 1) * spaceWidth;
+  } else if (style == TextBlock::CENTER_ALIGN) {
+    xpos = (spareSpace - (lineWordCount - 1) * spaceWidth) / 2;
+  }
+
+  // Pre-calculate X positions for words
+  std::list<uint16_t> lineXPos;
+  for (size_t i = lastBreakAt; i < lineBreak; i++) {
+    const uint16_t currentWordWidth = wordWidths[i];
+    lineXPos.push_back(xpos);
+    xpos += currentWordWidth + spacing;
+  }
+
+  // Iterators always start at the beginning as we are moving content with splice below
+  auto wordEndIt = words.begin();
+  auto wordStyleEndIt = wordStyles.begin();
+  std::advance(wordEndIt, lineWordCount);
+  std::advance(wordStyleEndIt, lineWordCount);
+
+  // *** CRITICAL STEP: CONSUME DATA USING SPLICE ***
+  std::list<std::string> lineWords;
+  lineWords.splice(lineWords.begin(), words, words.begin(), wordEndIt);
+  std::list<EpdFontStyle> 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

@@ -0,0 +1,40 @@
+#pragma once
+
+#include <EpdFontFamily.h>
+
+#include <functional>
+#include <list>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "blocks/TextBlock.h"
+
+class GfxRenderer;
+
+class ParsedText {
+  std::list<std::string> words;
+  std::list<EpdFontStyle> wordStyles;
+  TextBlock::BLOCK_STYLE style;
+  bool extraParagraphSpacing;
+
+  std::vector<size_t> computeLineBreaks(int pageWidth, int spaceWidth, const std::vector<uint16_t>& wordWidths) const;
+  void extractLine(size_t breakIndex, int pageWidth, int spaceWidth, const std::vector<uint16_t>& wordWidths,
+                   const std::vector<size_t>& lineBreakIndices,
+                   const std::function<void(std::shared_ptr<TextBlock>)>& processLine);
+  std::vector<uint16_t> calculateWordWidths(const GfxRenderer& renderer, int fontId);
+
+ public:
+  explicit ParsedText(const TextBlock::BLOCK_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; }
+  size_t size() const { return words.size(); }
+  bool isEmpty() const { return words.empty(); }
+  void layoutAndExtractLines(const GfxRenderer& renderer, int fontId, int horizontalMargin,
+                             const std::function<void(std::shared_ptr<TextBlock>)>& processLine,
+                             bool includeLastLine = true);
+};

lib/Epub/Epub/Section.cpp

@@ -1,46 +1,94 @@
 #include "Section.h"
 
-#include <EpdRenderer.h>
+#include <FsHelpers.h>
 #include <SD.h>
+#include <Serialization.h>
 
-#include <fstream>
-
-#include "EpubHtmlParser.h"
 #include "Page.h"
+#include "parsers/ChapterHtmlSlimParser.h"
 
-void Section::onPageComplete(const Page* page) {
-  Serial.printf("Page %d complete\n", pageCount);
+namespace {
+constexpr uint8_t SECTION_FILE_VERSION = 5;
+}
 
+void Section::onPageComplete(std::unique_ptr<Page> page) {
   const auto filePath = cachePath + "/page_" + std::to_string(pageCount) + ".bin";
-  // TODO can this be removed?
-  SD.open(filePath.c_str(), FILE_WRITE).close();
 
-  std::ofstream outputFile("/sd" + filePath);
+  File outputFile;
+  if (!FsHelpers::openFileForWrite("SCT", filePath, outputFile)) {
+    return;
+  }
   page->serialize(outputFile);
   outputFile.close();
 
+  Serial.printf("[%lu] [SCT] Page %d processed\n", millis(), pageCount);
+
   pageCount++;
-  delete page;
 }
 
-bool Section::hasCache() {
-  if (!SD.exists(cachePath.c_str())) {
-    return false;
+void Section::writeCacheMetadata(const int fontId, const float lineCompression, const int marginTop,
+                                 const int marginRight, const int marginBottom, const int marginLeft,
+                                 const bool extraParagraphSpacing) const {
+  File outputFile;
+  if (!FsHelpers::openFileForWrite("SCT", cachePath + "/section.bin", outputFile)) {
+    return;
   }
+  serialization::writePod(outputFile, SECTION_FILE_VERSION);
+  serialization::writePod(outputFile, fontId);
+  serialization::writePod(outputFile, lineCompression);
+  serialization::writePod(outputFile, marginTop);
+  serialization::writePod(outputFile, marginRight);
+  serialization::writePod(outputFile, marginBottom);
+  serialization::writePod(outputFile, marginLeft);
+  serialization::writePod(outputFile, extraParagraphSpacing);
+  serialization::writePod(outputFile, pageCount);
+  outputFile.close();
+}
 
+bool Section::loadCacheMetadata(const int fontId, const float lineCompression, const int marginTop,
+                                const int marginRight, const int marginBottom, const int marginLeft,
+                                const bool extraParagraphSpacing) {
   const auto sectionFilePath = cachePath + "/section.bin";
-  if (!SD.exists(sectionFilePath.c_str())) {
+  File inputFile;
+  if (!FsHelpers::openFileForRead("SCT", sectionFilePath, inputFile)) {
     return false;
   }
 
-  File sectionFile = SD.open(sectionFilePath.c_str(), FILE_READ);
-  uint8_t pageCountBytes[2] = {0, 0};
-  sectionFile.read(pageCountBytes, 2);
-  sectionFile.close();
+  // Match parameters
+  {
+    uint8_t version;
+    serialization::readPod(inputFile, version);
+    if (version != SECTION_FILE_VERSION) {
+      inputFile.close();
+      Serial.printf("[%lu] [SCT] Deserialization failed: Unknown version %u\n", millis(), version);
+      clearCache();
+      return false;
+    }
 
-  pageCount = pageCountBytes[0] + (pageCountBytes[1] << 8);
-  Serial.printf("Loaded cache: %d pages\n", pageCount);
+    int fileFontId, fileMarginTop, fileMarginRight, fileMarginBottom, fileMarginLeft;
+    float fileLineCompression;
+    bool fileExtraParagraphSpacing;
+    serialization::readPod(inputFile, fileFontId);
+    serialization::readPod(inputFile, fileLineCompression);
+    serialization::readPod(inputFile, fileMarginTop);
+    serialization::readPod(inputFile, fileMarginRight);
+    serialization::readPod(inputFile, fileMarginBottom);
+    serialization::readPod(inputFile, fileMarginLeft);
+    serialization::readPod(inputFile, fileExtraParagraphSpacing);
 
+    if (fontId != fileFontId || lineCompression != fileLineCompression || marginTop != fileMarginTop ||
+        marginRight != fileMarginRight || marginBottom != fileMarginBottom || marginLeft != fileMarginLeft ||
+        extraParagraphSpacing != fileExtraParagraphSpacing) {
+      inputFile.close();
+      Serial.printf("[%lu] [SCT] Deserialization failed: Parameters do not match\n", millis());
+      clearCache();
+      return false;
+    }
+  }
+
+  serialization::readPod(inputFile, pageCount);
+  inputFile.close();
+  Serial.printf("[%lu] [SCT] Deserialization succeeded: %d pages\n", millis(), pageCount);
   return true;
 }
 
@@ -49,69 +97,65 @@ void Section::setupCacheDir() const {
   SD.mkdir(cachePath.c_str());
 }
 
-void Section::clearCache() const { SD.rmdir(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())) {
+    Serial.printf("[%lu] [SCT] Cache does not exist, no action needed\n", millis());
+    return true;
+  }
 
-bool Section::persistPageDataToSD() {
-  size_t size = 0;
-  auto localPath = epub->getSpineItem(spineIndex);
-
-  const auto html = epub->getItemContents(epub->getSpineItem(spineIndex), &size);
-  if (!html) {
-    Serial.println("Failed to read item contents");
+  if (!FsHelpers::removeDir(cachePath.c_str())) {
+    Serial.printf("[%lu] [SCT] Failed to clear cache\n", millis());
     return false;
   }
 
-  // TODO: Would love to stream this through an XML visitor
+  Serial.printf("[%lu] [SCT] Cache cleared successfully\n", millis());
+  return true;
+}
+
+bool Section::persistPageDataToSD(const int fontId, const float lineCompression, const int marginTop,
+                                  const int marginRight, const int marginBottom, const int marginLeft,
+                                  const bool extraParagraphSpacing) {
+  const auto localPath = epub->getSpineItem(spineIndex).href;
   const auto tmpHtmlPath = epub->getCachePath() + "/.tmp_" + std::to_string(spineIndex) + ".html";
-  File f = SD.open(tmpHtmlPath.c_str(), FILE_WRITE);
-  const auto written = f.write(html, size);
-  f.close();
-  free(html);
+  File tmpHtml;
+  if (!FsHelpers::openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) {
+    return false;
+  }
+  bool success = epub->readItemContentsToStream(localPath, tmpHtml, 1024);
+  tmpHtml.close();
 
-  Serial.printf("Wrote %d bytes to %s\n", written, tmpHtmlPath.c_str());
-
-  if (size != written) {
-    Serial.println("Failed to inflate section contents to SD");
-    SD.remove(tmpHtmlPath.c_str());
+  if (!success) {
+    Serial.printf("[%lu] [SCT] Failed to stream item contents to temp file\n", millis());
     return false;
   }
 
-  const auto sdTmpHtmlPath = "/sd" + tmpHtmlPath;
-  auto visitor =
-      EpubHtmlParser(sdTmpHtmlPath.c_str(), renderer, [this](const Page* page) { this->onPageComplete(page); });
+  Serial.printf("[%lu] [SCT] Streamed temp HTML to %s\n", millis(), tmpHtmlPath.c_str());
+
+  ChapterHtmlSlimParser visitor(tmpHtmlPath, renderer, fontId, lineCompression, marginTop, marginRight, marginBottom,
+                                marginLeft, extraParagraphSpacing,
+                                [this](std::unique_ptr<Page> page) { this->onPageComplete(std::move(page)); });
+  success = visitor.parseAndBuildPages();
 
-  // TODO: Come back and see if mem used here can be lowered?
-  const bool success = visitor.parseAndBuildPages();
   SD.remove(tmpHtmlPath.c_str());
   if (!success) {
-    Serial.println("Failed to parse and build pages");
+    Serial.printf("[%lu] [SCT] Failed to parse XML and build pages\n", millis());
     return false;
   }
 
-  File sectionFile = SD.open((cachePath + "/section.bin").c_str(), FILE_WRITE, true);
-  const uint8_t pageCountBytes[2] = {static_cast<uint8_t>(pageCount & 0xFF),
-                                     static_cast<uint8_t>((pageCount >> 8) & 0xFF)};
-  sectionFile.write(pageCountBytes, 2);
-  sectionFile.close();
+  writeCacheMetadata(fontId, lineCompression, marginTop, marginRight, marginBottom, marginLeft, extraParagraphSpacing);
 
   return true;
 }
 
-void Section::renderPage() {
-  if (0 <= currentPage && currentPage < pageCount) {
-    const auto filePath = "/sd" + cachePath + "/page_" + std::to_string(currentPage) + ".bin";
-    std::ifstream inputFile(filePath);
-    const Page* p = Page::deserialize(inputFile);
-    inputFile.close();
-    p->render(renderer);
-    delete p;
-  } else if (pageCount == 0) {
-    Serial.println("No pages to render");
-    const int width = renderer->getTextWidth("Empty chapter", true);
-    renderer->drawText((renderer->getPageWidth() - width) / 2, 300, "Empty chapter", true);
-  } else {
-    Serial.printf("Page out of bounds: %d (max %d)\n", currentPage, pageCount);
-    const int width = renderer->getTextWidth("Out of bounds", true);
-    renderer->drawText((renderer->getPageWidth() - width) / 2, 300, "Out of bounds", 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)) {
+    return nullptr;
   }
+  auto page = Page::deserialize(inputFile);
+  inputFile.close();
+  return page;
 }

lib/Epub/Epub/Section.h

@@ -1,29 +1,36 @@
 #pragma once
+#include <memory>
+
 #include "Epub.h"
 
 class Page;
-class EpdRenderer;
+class GfxRenderer;
 
 class Section {
-  Epub* epub;
+  std::shared_ptr<Epub> epub;
   const int spineIndex;
-  EpdRenderer* renderer;
+  GfxRenderer& renderer;
   std::string cachePath;
 
-  void onPageComplete(const Page* page);
+  void writeCacheMetadata(int fontId, float lineCompression, int marginTop, int marginRight, int marginBottom,
+                          int marginLeft, bool extraParagraphSpacing) const;
+  void onPageComplete(std::unique_ptr<Page> page);
 
  public:
   int pageCount = 0;
   int currentPage = 0;
 
-  explicit Section(Epub* epub, const int spineIndex, EpdRenderer* renderer)
-      : epub(epub), spineIndex(spineIndex), renderer(renderer) {
-    cachePath = epub->getCachePath() + "/" + std::to_string(spineIndex);
-  }
+  explicit Section(const std::shared_ptr<Epub>& epub, const int spineIndex, GfxRenderer& renderer)
+      : epub(epub),
+        spineIndex(spineIndex),
+        renderer(renderer),
+        cachePath(epub->getCachePath() + "/" + std::to_string(spineIndex)) {}
   ~Section() = default;
-  bool hasCache();
+  bool loadCacheMetadata(int fontId, float lineCompression, int marginTop, int marginRight, int marginBottom,
+                         int marginLeft, bool extraParagraphSpacing);
   void setupCacheDir() const;
-  void clearCache() const;
-  bool persistPageDataToSD();
-  void renderPage();
+  bool clearCache() const;
+  bool persistPageDataToSD(int fontId, float lineCompression, int marginTop, int marginRight, int marginBottom,
+                           int marginLeft, bool extraParagraphSpacing);
+  std::unique_ptr<Page> loadPageFromSD() const;
 };

lib/Epub/Epub/blocks/Block.h

@@ -1,6 +1,6 @@
 #pragma once
 
-class EpdRenderer;
+class GfxRenderer;
 
 typedef enum { TEXT_BLOCK, IMAGE_BLOCK } BlockType;
 
@@ -8,7 +8,7 @@ typedef enum { TEXT_BLOCK, IMAGE_BLOCK } BlockType;
 class Block {
  public:
   virtual ~Block() = default;
-  virtual void layout(EpdRenderer* renderer) = 0;
+  virtual void layout(GfxRenderer& renderer) = 0;
   virtual BlockType getType() = 0;
   virtual bool isEmpty() = 0;
   virtual void finish() {}

lib/Epub/Epub/blocks/TextBlock.cpp

@@ -1,235 +1,66 @@
 #include "TextBlock.h"
 
-#include <EpdRenderer.h>
+#include <GfxRenderer.h>
 #include <Serialization.h>
 
-static bool isWhitespace(const char c) { return c == ' ' || c == '\r' || c == '\n'; }
+void TextBlock::render(const GfxRenderer& renderer, const int fontId, const int x, const int y) const {
+  auto wordIt = words.begin();
+  auto wordStylesIt = wordStyles.begin();
+  auto wordXposIt = wordXpos.begin();
 
-// move past anything that should be considered part of a work
-static int skipWord(const std::string& text, int index, const int length) {
-  while (index < length && !isWhitespace(text[index])) {
-    index++;
-  }
-  return index;
-}
-
-// skip past any white space characters
-static int skipWhitespace(const std::string& html, int index, const int length) {
-  while (index < length && isWhitespace(html[index])) {
-    index++;
-  }
-  return index;
-}
-
-void TextBlock::addSpan(const std::string& span, const bool is_bold, const bool is_italic) {
-  // adding a span to text block
-  // make a copy of the text as we'll modify it
-  const int length = span.length();
-  // const auto text = new char[length + 1];
-  // strcpy(text, span);
-  // work out where each word is in the span
-  int index = 0;
-  while (index < length) {
-    // skip past any whitespace to the start of a word
-    index = skipWhitespace(span, index, length);
-    const int wordStart = index;
-    // find the end of the word
-    index = skipWord(span, index, length);
-    const int wordLength = index - wordStart;
-    if (wordLength > 0) {
-      words.push_back(span.substr(wordStart, wordLength));
-      wordStyles.push_back((is_bold ? BOLD_SPAN : 0) | (is_italic ? ITALIC_SPAN : 0));
-    }
-  }
-}
-
-std::list<TextBlock*> TextBlock::splitIntoLines(const EpdRenderer* renderer) {
-  const int totalWordCount = words.size();
-  const int pageWidth = renderer->getPageWidth();
-  const int spaceWidth = renderer->getSpaceWidth();
-
-  words.shrink_to_fit();
-  wordStyles.shrink_to_fit();
-  wordXpos.reserve(totalWordCount);
-
-  // measure each word
-  uint16_t wordWidths[totalWordCount];
   for (int i = 0; i < words.size(); i++) {
-    // measure the word
-    const int width = renderer->getTextWidth(words[i].c_str(), wordStyles[i] & BOLD_SPAN, wordStyles[i] & ITALIC_SPAN);
-    wordWidths[i] = width;
-  }
+    renderer.drawText(fontId, *wordXposIt + x, y, wordIt->c_str(), true, *wordStylesIt);
 
-  // now apply the dynamic programming algorithm to find the best line breaks
-  // DP table in which dp[i] represents cost of line starting with word words[i]
-  int dp[totalWordCount];
-
-  // Array in which ans[i] store index of last word in line starting with word
-  // word[i]
-  size_t ans[totalWordCount];
-
-  // If only one word is present then only one line is required. Cost of last
-  // line is zero. Hence cost of this line is zero. Ending point is also n-1 as
-  // single word is present
-  dp[totalWordCount - 1] = 0;
-  ans[totalWordCount - 1] = totalWordCount - 1;
-
-  // Make each word first word of line by iterating over each index in arr.
-  for (int i = totalWordCount - 2; i >= 0; i--) {
-    int currlen = -1;
-    dp[i] = INT_MAX;
-
-    // Variable to store possible minimum cost of line.
-    int cost;
-
-    // Keep on adding words in current line by iterating from starting word upto
-    // last word in arr.
-    for (int j = i; j < totalWordCount; j++) {
-      // Update the width of the words in current line + the space between two
-      // words.
-      currlen += wordWidths[j] + spaceWidth;
-
-      // If we're bigger than the current pagewidth then we can't add more words
-      if (currlen > pageWidth) break;
-
-      // if we've run out of words then this is last line and the cost should be
-      // 0 Otherwise the cost is the sqaure of the left over space + the costs
-      // of all the previous lines
-      if (j == totalWordCount - 1)
-        cost = 0;
-      else
-        cost = (pageWidth - currlen) * (pageWidth - currlen) + dp[j + 1];
-
-      // Check if this arrangement gives minimum cost for line starting with
-      // word words[i].
-      if (cost < dp[i]) {
-        dp[i] = cost;
-        ans[i] = j;
-      }
-    }
-  }
-
-  // We can now iterate through the answer to find the line break positions
-  std::list<uint16_t> lineBreaks;
-  for (size_t i = 0; i < totalWordCount;) {
-    i = ans[i] + 1;
-    if (i > totalWordCount) {
-      break;
-    }
-    lineBreaks.push_back(i);
-    // Text too big, just exit
-    if (lineBreaks.size() > 1000) {
-      break;
-    }
-  }
-
-  std::list<TextBlock*> lines;
-
-  // With the line breaks calculated we can now position the words along the
-  // line
-  int startWord = 0;
-  for (const auto lineBreak : lineBreaks) {
-    const int lineWordCount = lineBreak - startWord;
-
-    int lineWordWidthSum = 0;
-    for (int i = startWord; i < lineBreak; i++) {
-      lineWordWidthSum += wordWidths[i];
-    }
-
-    // Calculate spacing between words
-    const uint16_t spareSpace = pageWidth - lineWordWidthSum;
-    uint16_t spacing = spaceWidth;
-    // evenly space words if using justified style, not the last line, and at
-    // least 2 words
-    if (style == JUSTIFIED && lineBreak != lineBreaks.back() && lineWordCount >= 2) {
-      spacing = spareSpace / (lineWordCount - 1);
-    }
-
-    uint16_t xpos = 0;
-    if (style == RIGHT_ALIGN) {
-      xpos = spareSpace - (lineWordCount - 1) * spaceWidth;
-    } else if (style == CENTER_ALIGN) {
-      xpos = (spareSpace - (lineWordCount - 1) * spaceWidth) / 2;
-    }
-
-    for (int i = startWord; i < lineBreak; i++) {
-      wordXpos[i] = xpos;
-      xpos += wordWidths[i] + spacing;
-    }
-
-    std::vector<std::string> lineWords;
-    std::vector<uint16_t> lineXPos;
-    std::vector<uint8_t> lineWordStyles;
-    lineWords.reserve(lineWordCount);
-    lineXPos.reserve(lineWordCount);
-    lineWordStyles.reserve(lineWordCount);
-
-    for (int i = startWord; i < lineBreak; i++) {
-      lineWords.push_back(words[i]);
-      lineXPos.push_back(wordXpos[i]);
-      lineWordStyles.push_back(wordStyles[i]);
-    }
-    const auto textLine = new TextBlock(lineWords, lineXPos, lineWordStyles, style);
-    lines.push_back(textLine);
-    startWord = lineBreak;
-  }
-
-  return lines;
-}
-
-void TextBlock::render(const EpdRenderer* renderer, const int x, const int y) const {
-  for (int i = 0; i < words.size(); i++) {
-    // get the style
-    const uint8_t wordStyle = wordStyles[i];
-    // render the word
-    renderer->drawText(x + wordXpos[i], y, words[i].c_str(), wordStyle & BOLD_SPAN, wordStyle & ITALIC_SPAN);
+    std::advance(wordIt, 1);
+    std::advance(wordStylesIt, 1);
+    std::advance(wordXposIt, 1);
   }
 }
 
-void TextBlock::serialize(std::ostream& os) const {
+void TextBlock::serialize(File& file) const {
   // words
   const uint32_t wc = words.size();
-  serialization::writePod(os, wc);
-  for (const auto& w : words) serialization::writeString(os, w);
+  serialization::writePod(file, wc);
+  for (const auto& w : words) serialization::writeString(file, w);
 
   // wordXpos
   const uint32_t xc = wordXpos.size();
-  serialization::writePod(os, xc);
-  for (auto x : wordXpos) serialization::writePod(os, x);
+  serialization::writePod(file, xc);
+  for (auto x : wordXpos) serialization::writePod(file, x);
 
   // wordStyles
   const uint32_t sc = wordStyles.size();
-  serialization::writePod(os, sc);
-  for (auto s : wordStyles) serialization::writePod(os, s);
+  serialization::writePod(file, sc);
+  for (auto s : wordStyles) serialization::writePod(file, s);
 
   // style
-  serialization::writePod(os, style);
+  serialization::writePod(file, style);
 }
 
-TextBlock* TextBlock::deserialize(std::istream& is) {
+std::unique_ptr<TextBlock> TextBlock::deserialize(File& file) {
   uint32_t wc, xc, sc;
-  std::vector<std::string> words;
-  std::vector<uint16_t> wordXpos;
-  std::vector<uint8_t> wordStyles;
+  std::list<std::string> words;
+  std::list<uint16_t> wordXpos;
+  std::list<EpdFontStyle> wordStyles;
   BLOCK_STYLE style;
 
   // words
-  serialization::readPod(is, wc);
+  serialization::readPod(file, wc);
   words.resize(wc);
-  for (auto& w : words) serialization::readString(is, w);
+  for (auto& w : words) serialization::readString(file, w);
 
   // wordXpos
-  serialization::readPod(is, xc);
+  serialization::readPod(file, xc);
   wordXpos.resize(xc);
-  for (auto& x : wordXpos) serialization::readPod(is, x);
+  for (auto& x : wordXpos) serialization::readPod(file, x);
 
   // wordStyles
-  serialization::readPod(is, sc);
+  serialization::readPod(file, sc);
   wordStyles.resize(sc);
-  for (auto& s : wordStyles) serialization::readPod(is, s);
+  for (auto& s : wordStyles) serialization::readPod(file, s);
 
   // style
-  serialization::readPod(is, style);
+  serialization::readPod(file, style);
 
-  return new TextBlock(words, wordXpos, wordStyles, 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,50 +1,41 @@
 #pragma once
+#include <EpdFontFamily.h>
+#include <FS.h>
+
 #include <list>
+#include <memory>
 #include <string>
-#include <vector>
 
 #include "Block.h"
 
-enum SPAN_STYLE : uint8_t {
-  BOLD_SPAN = 1,
-  ITALIC_SPAN = 2,
-};
-
-enum BLOCK_STYLE : uint8_t {
-  JUSTIFIED = 0,
-  LEFT_ALIGN = 1,
-  CENTER_ALIGN = 2,
-  RIGHT_ALIGN = 3,
-};
-
 // represents a block of words in the html document
 class TextBlock final : public Block {
-  // pointer to each word
-  std::vector<std::string> words;
-  // x position of each word
-  std::vector<uint16_t> wordXpos;
-  // the styles of each word
-  std::vector<uint8_t> wordStyles;
+ public:
+  enum BLOCK_STYLE : uint8_t {
+    JUSTIFIED = 0,
+    LEFT_ALIGN = 1,
+    CENTER_ALIGN = 2,
+    RIGHT_ALIGN = 3,
+  };
 
-  // the style of the block - left, center, right aligned
+ private:
+  std::list<std::string> words;
+  std::list<uint16_t> wordXpos;
+  std::list<EpdFontStyle> wordStyles;
   BLOCK_STYLE style;
 
  public:
-  void addSpan(const std::string& span, bool is_bold, bool is_italic);
-  explicit TextBlock(const BLOCK_STYLE style) : style(style) {}
-  explicit TextBlock(const std::vector<std::string>& words, const std::vector<uint16_t>& word_xpos,
-                     // the styles of each word
-                     const std::vector<uint8_t>& word_styles, const BLOCK_STYLE style)
-      : words(words), wordXpos(word_xpos), wordStyles(word_styles), style(style) {}
+  explicit TextBlock(std::list<std::string> words, std::list<uint16_t> word_xpos, std::list<EpdFontStyle> word_styles,
+                     const BLOCK_STYLE style)
+      : words(std::move(words)), wordXpos(std::move(word_xpos)), wordStyles(std::move(word_styles)), style(style) {}
   ~TextBlock() override = default;
-  void set_style(const BLOCK_STYLE style) { this->style = style; }
-  BLOCK_STYLE get_style() const { return style; }
+  void setStyle(const BLOCK_STYLE style) { this->style = style; }
+  BLOCK_STYLE getStyle() const { return style; }
   bool isEmpty() override { return words.empty(); }
-  void layout(EpdRenderer* renderer) override {};
+  void layout(GfxRenderer& renderer) override {};
   // given a renderer works out where to break the words into lines
-  std::list<TextBlock*> splitIntoLines(const EpdRenderer* renderer);
-  void render(const EpdRenderer* renderer, int x, int y) const;
+  void render(const GfxRenderer& renderer, int fontId, int x, int y) const;
   BlockType getType() override { return TEXT_BLOCK; }
-  void serialize(std::ostream& os) const;
-  static TextBlock* deserialize(std::istream& is);
+  void serialize(File& file) const;
+  static std::unique_ptr<TextBlock> deserialize(File& file);
 };

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp

@@ -0,0 +1,316 @@
+#include "ChapterHtmlSlimParser.h"
+
+#include <FsHelpers.h>
+#include <GfxRenderer.h>
+#include <HardwareSerial.h>
+#include <expat.h>
+
+#include "../Page.h"
+#include "../htmlEntities.h"
+
+const char* HEADER_TAGS[] = {"h1", "h2", "h3", "h4", "h5", "h6"};
+constexpr int NUM_HEADER_TAGS = sizeof(HEADER_TAGS) / sizeof(HEADER_TAGS[0]);
+
+const char* BLOCK_TAGS[] = {"p", "li", "div", "br", "blockquote"};
+constexpr int NUM_BLOCK_TAGS = sizeof(BLOCK_TAGS) / sizeof(BLOCK_TAGS[0]);
+
+const char* BOLD_TAGS[] = {"b", "strong"};
+constexpr int NUM_BOLD_TAGS = sizeof(BOLD_TAGS) / sizeof(BOLD_TAGS[0]);
+
+const char* ITALIC_TAGS[] = {"i", "em"};
+constexpr int NUM_ITALIC_TAGS = sizeof(ITALIC_TAGS) / sizeof(ITALIC_TAGS[0]);
+
+const char* IMAGE_TAGS[] = {"img"};
+constexpr int NUM_IMAGE_TAGS = sizeof(IMAGE_TAGS) / sizeof(IMAGE_TAGS[0]);
+
+const char* SKIP_TAGS[] = {"head", "table"};
+constexpr int NUM_SKIP_TAGS = sizeof(SKIP_TAGS) / sizeof(SKIP_TAGS[0]);
+
+bool isWhitespace(const char c) { return c == ' ' || c == '\r' || c == '\n' || c == '\t'; }
+
+// given the start and end of a tag, check to see if it matches a known tag
+bool matches(const char* tag_name, const char* possible_tags[], const int possible_tag_count) {
+  for (int i = 0; i < possible_tag_count; i++) {
+    if (strcmp(tag_name, possible_tags[i]) == 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// start a new text block if needed
+void ChapterHtmlSlimParser::startNewTextBlock(const TextBlock::BLOCK_STYLE style) {
+  if (currentTextBlock) {
+    // already have a text block running and it is empty - just reuse it
+    if (currentTextBlock->isEmpty()) {
+      currentTextBlock->setStyle(style);
+      return;
+    }
+
+    makePages();
+  }
+  currentTextBlock.reset(new ParsedText(style, extraParagraphSpacing));
+}
+
+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) {
+    self->depth += 1;
+    return;
+  }
+
+  if (matches(name, IMAGE_TAGS, NUM_IMAGE_TAGS)) {
+    // TODO: Start processing image tags
+    self->skipUntilDepth = self->depth;
+    self->depth += 1;
+    return;
+  }
+
+  if (matches(name, SKIP_TAGS, NUM_SKIP_TAGS)) {
+    // start skip
+    self->skipUntilDepth = self->depth;
+    self->depth += 1;
+    return;
+  }
+
+  // Skip blocks with role="doc-pagebreak" and epub:type="pagebreak"
+  if (atts != nullptr) {
+    for (int i = 0; atts[i]; i += 2) {
+      if (strcmp(atts[i], "role") == 0 && strcmp(atts[i + 1], "doc-pagebreak") == 0 ||
+          strcmp(atts[i], "epub:type") == 0 && strcmp(atts[i + 1], "pagebreak") == 0) {
+        self->skipUntilDepth = self->depth;
+        self->depth += 1;
+        return;
+      }
+    }
+  }
+
+  if (matches(name, HEADER_TAGS, NUM_HEADER_TAGS)) {
+    self->startNewTextBlock(TextBlock::CENTER_ALIGN);
+    self->boldUntilDepth = min(self->boldUntilDepth, self->depth);
+  } else if (matches(name, BLOCK_TAGS, NUM_BLOCK_TAGS)) {
+    if (strcmp(name, "br") == 0) {
+      self->startNewTextBlock(self->currentTextBlock->getStyle());
+    } else {
+      self->startNewTextBlock(TextBlock::JUSTIFIED);
+    }
+  } else if (matches(name, BOLD_TAGS, NUM_BOLD_TAGS)) {
+    self->boldUntilDepth = min(self->boldUntilDepth, self->depth);
+  } else if (matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS)) {
+    self->italicUntilDepth = min(self->italicUntilDepth, self->depth);
+  }
+
+  self->depth += 1;
+}
+
+void XMLCALL ChapterHtmlSlimParser::characterData(void* userData, const XML_Char* s, const int len) {
+  auto* self = static_cast<ChapterHtmlSlimParser*>(userData);
+
+  // Middle of skip
+  if (self->skipUntilDepth < self->depth) {
+    return;
+  }
+
+  EpdFontStyle fontStyle = REGULAR;
+  if (self->boldUntilDepth < self->depth && self->italicUntilDepth < self->depth) {
+    fontStyle = BOLD_ITALIC;
+  } else if (self->boldUntilDepth < self->depth) {
+    fontStyle = BOLD;
+  } else if (self->italicUntilDepth < self->depth) {
+    fontStyle = ITALIC;
+  }
+
+  for (int i = 0; i < len; i++) {
+    if (isWhitespace(s[i])) {
+      // Currently looking at whitespace, if there's anything in the partWordBuffer, flush it
+      if (self->partWordBufferIndex > 0) {
+        self->partWordBuffer[self->partWordBufferIndex] = '\0';
+        self->currentTextBlock->addWord(std::move(replaceHtmlEntities(self->partWordBuffer)), fontStyle);
+        self->partWordBufferIndex = 0;
+      }
+      // Skip the whitespace char
+      continue;
+    }
+
+    // If we're about to run out of space, then cut the word off and start a new one
+    if (self->partWordBufferIndex >= MAX_WORD_SIZE) {
+      self->partWordBuffer[self->partWordBufferIndex] = '\0';
+      self->currentTextBlock->addWord(std::move(replaceHtmlEntities(self->partWordBuffer)), fontStyle);
+      self->partWordBufferIndex = 0;
+    }
+
+    self->partWordBuffer[self->partWordBufferIndex++] = s[i];
+  }
+
+  // If we have > 750 words buffered up, perform the layout and consume out all but the last line
+  // There should be enough here to build out 1-2 full pages and doing this will free up a lot of
+  // memory.
+  // Spotted when reading Intermezzo, there are some really long text blocks in there.
+  if (self->currentTextBlock->size() > 750) {
+    Serial.printf("[%lu] [EHP] Text block too long, splitting into multiple pages\n", millis());
+    self->currentTextBlock->layoutAndExtractLines(
+        self->renderer, self->fontId, self->marginLeft + self->marginRight,
+        [self](const std::shared_ptr<TextBlock>& textBlock) { self->addLineToPage(textBlock); }, false);
+  }
+}
+
+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.
+    // We don't want to flush out content when closing inline tags like <span>.
+    // Currently this also flushes out on closing <b> and <i> tags, but they are line tags so that shouldn't happen,
+    // text styling needs to be overhauled to fix it.
+    const bool shouldBreakText =
+        matches(name, BLOCK_TAGS, NUM_BLOCK_TAGS) || matches(name, HEADER_TAGS, NUM_HEADER_TAGS) ||
+        matches(name, BOLD_TAGS, NUM_BOLD_TAGS) || matches(name, ITALIC_TAGS, NUM_ITALIC_TAGS) || self->depth == 1;
+
+    if (shouldBreakText) {
+      EpdFontStyle fontStyle = REGULAR;
+      if (self->boldUntilDepth < self->depth && self->italicUntilDepth < self->depth) {
+        fontStyle = BOLD_ITALIC;
+      } else if (self->boldUntilDepth < self->depth) {
+        fontStyle = BOLD;
+      } else if (self->italicUntilDepth < self->depth) {
+        fontStyle = ITALIC;
+      }
+
+      self->partWordBuffer[self->partWordBufferIndex] = '\0';
+      self->currentTextBlock->addWord(std::move(replaceHtmlEntities(self->partWordBuffer)), fontStyle);
+      self->partWordBufferIndex = 0;
+    }
+  }
+
+  self->depth -= 1;
+
+  // Leaving skip
+  if (self->skipUntilDepth == self->depth) {
+    self->skipUntilDepth = INT_MAX;
+  }
+
+  // Leaving bold
+  if (self->boldUntilDepth == self->depth) {
+    self->boldUntilDepth = INT_MAX;
+  }
+
+  // Leaving italic
+  if (self->italicUntilDepth == self->depth) {
+    self->italicUntilDepth = INT_MAX;
+  }
+}
+
+bool ChapterHtmlSlimParser::parseAndBuildPages() {
+  startNewTextBlock(TextBlock::JUSTIFIED);
+
+  const XML_Parser parser = XML_ParserCreate(nullptr);
+  int done;
+
+  if (!parser) {
+    Serial.printf("[%lu] [EHP] Couldn't allocate memory for parser\n", millis());
+    return false;
+  }
+
+  File file;
+  if (!FsHelpers::openFileForRead("EHP", filepath, file)) {
+    XML_ParserFree(parser);
+    return false;
+  }
+
+  XML_SetUserData(parser, this);
+  XML_SetElementHandler(parser, startElement, endElement);
+  XML_SetCharacterDataHandler(parser, characterData);
+
+  do {
+    void* const buf = XML_GetBuffer(parser, 1024);
+    if (!buf) {
+      Serial.printf("[%lu] [EHP] Couldn't allocate memory for buffer\n", millis());
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
+      XML_ParserFree(parser);
+      file.close();
+      return false;
+    }
+
+    const size_t len = file.read(static_cast<uint8_t*>(buf), 1024);
+
+    if (len == 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
+      XML_SetCharacterDataHandler(parser, nullptr);
+      XML_ParserFree(parser);
+      file.close();
+      return false;
+    }
+
+    done = file.available() == 0;
+
+    if (XML_ParseBuffer(parser, static_cast<int>(len), done) == XML_STATUS_ERROR) {
+      Serial.printf("[%lu] [EHP] Parse error at line %lu:\n%s\n", millis(), XML_GetCurrentLineNumber(parser),
+                    XML_ErrorString(XML_GetErrorCode(parser)));
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
+      XML_ParserFree(parser);
+      file.close();
+      return false;
+    }
+  } while (!done);
+
+  XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+  XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+  XML_SetCharacterDataHandler(parser, nullptr);
+  XML_ParserFree(parser);
+  file.close();
+
+  // Process last page if there is still text
+  if (currentTextBlock) {
+    makePages();
+    completePageFn(std::move(currentPage));
+    currentPage.reset();
+    currentTextBlock.reset();
+  }
+
+  return true;
+}
+
+void ChapterHtmlSlimParser::addLineToPage(std::shared_ptr<TextBlock> line) {
+  const int lineHeight = renderer.getLineHeight(fontId) * lineCompression;
+  const int pageHeight = GfxRenderer::getScreenHeight() - marginTop - marginBottom;
+
+  if (currentPageNextY + lineHeight > pageHeight) {
+    completePageFn(std::move(currentPage));
+    currentPage.reset(new Page());
+    currentPageNextY = marginTop;
+  }
+
+  currentPage->elements.push_back(std::make_shared<PageLine>(line, marginLeft, currentPageNextY));
+  currentPageNextY += lineHeight;
+}
+
+void ChapterHtmlSlimParser::makePages() {
+  if (!currentTextBlock) {
+    Serial.printf("[%lu] [EHP] !! No text block to make pages for !!\n", millis());
+    return;
+  }
+
+  if (!currentPage) {
+    currentPage.reset(new Page());
+    currentPageNextY = marginTop;
+  }
+
+  const int lineHeight = renderer.getLineHeight(fontId) * lineCompression;
+  currentTextBlock->layoutAndExtractLines(
+      renderer, fontId, marginLeft + marginRight,
+      [this](const std::shared_ptr<TextBlock>& textBlock) { addLineToPage(textBlock); });
+  // Extra paragraph spacing if enabled
+  if (extraParagraphSpacing) {
+    currentPageNextY += lineHeight / 2;
+  }
+}

lib/Epub/Epub/parsers/ChapterHtmlSlimParser.h

@@ -0,0 +1,65 @@
+#pragma once
+
+#include <expat.h>
+
+#include <climits>
+#include <functional>
+#include <memory>
+
+#include "../ParsedText.h"
+#include "../blocks/TextBlock.h"
+
+class Page;
+class GfxRenderer;
+
+#define MAX_WORD_SIZE 200
+
+class ChapterHtmlSlimParser {
+  const std::string& filepath;
+  GfxRenderer& renderer;
+  std::function<void(std::unique_ptr<Page>)> completePageFn;
+  int depth = 0;
+  int skipUntilDepth = INT_MAX;
+  int boldUntilDepth = INT_MAX;
+  int italicUntilDepth = INT_MAX;
+  // buffer for building up words from characters, will auto break if longer than this
+  // leave one char at end for null pointer
+  char partWordBuffer[MAX_WORD_SIZE + 1] = {};
+  int partWordBufferIndex = 0;
+  std::unique_ptr<ParsedText> currentTextBlock = nullptr;
+  std::unique_ptr<Page> currentPage = nullptr;
+  int16_t currentPageNextY = 0;
+  int fontId;
+  float lineCompression;
+  int marginTop;
+  int marginRight;
+  int marginBottom;
+  int marginLeft;
+  bool extraParagraphSpacing;
+
+  void startNewTextBlock(TextBlock::BLOCK_STYLE style);
+  void makePages();
+  // XML callbacks
+  static void XMLCALL startElement(void* userData, const XML_Char* name, const XML_Char** atts);
+  static void XMLCALL characterData(void* userData, const XML_Char* s, int len);
+  static void XMLCALL endElement(void* userData, const XML_Char* name);
+
+ public:
+  explicit ChapterHtmlSlimParser(const std::string& filepath, GfxRenderer& renderer, const int fontId,
+                                 const float lineCompression, const int marginTop, const int marginRight,
+                                 const int marginBottom, const int marginLeft, const bool extraParagraphSpacing,
+                                 const std::function<void(std::unique_ptr<Page>)>& completePageFn)
+      : filepath(filepath),
+        renderer(renderer),
+        fontId(fontId),
+        lineCompression(lineCompression),
+        marginTop(marginTop),
+        marginRight(marginRight),
+        marginBottom(marginBottom),
+        marginLeft(marginLeft),
+        extraParagraphSpacing(extraParagraphSpacing),
+        completePageFn(completePageFn) {}
+  ~ChapterHtmlSlimParser() = default;
+  bool parseAndBuildPages();
+  void addLineToPage(std::shared_ptr<TextBlock> line);
+};

lib/Epub/Epub/parsers/ContainerParser.cpp

@@ -0,0 +1,97 @@
+#include "ContainerParser.h"
+
+#include <HardwareSerial.h>
+
+bool ContainerParser::setup() {
+  parser = XML_ParserCreate(nullptr);
+  if (!parser) {
+    Serial.printf("[%lu] [CTR] Couldn't allocate memory for parser\n", millis());
+    return false;
+  }
+
+  XML_SetUserData(parser, this);
+  XML_SetElementHandler(parser, startElement, endElement);
+  return true;
+}
+
+ContainerParser::~ContainerParser() {
+  if (parser) {
+    XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+    XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+    XML_ParserFree(parser);
+    parser = nullptr;
+  }
+}
+
+size_t ContainerParser::write(const uint8_t data) { return write(&data, 1); }
+
+size_t ContainerParser::write(const uint8_t* buffer, const size_t size) {
+  if (!parser) return 0;
+
+  const uint8_t* currentBufferPos = buffer;
+  auto remainingInBuffer = size;
+
+  while (remainingInBuffer > 0) {
+    void* const buf = XML_GetBuffer(parser, 1024);
+    if (!buf) {
+      Serial.printf("[%lu] [CTR] Couldn't allocate buffer\n", millis());
+      return 0;
+    }
+
+    const auto toRead = remainingInBuffer < 1024 ? remainingInBuffer : 1024;
+    memcpy(buf, currentBufferPos, toRead);
+
+    if (XML_ParseBuffer(parser, static_cast<int>(toRead), remainingSize == toRead) == XML_STATUS_ERROR) {
+      Serial.printf("[%lu] [CTR] Parse error: %s\n", millis(), XML_ErrorString(XML_GetErrorCode(parser)));
+      return 0;
+    }
+
+    currentBufferPos += toRead;
+    remainingInBuffer -= toRead;
+    remainingSize -= toRead;
+  }
+  return size;
+}
+
+void XMLCALL ContainerParser::startElement(void* userData, const XML_Char* name, const XML_Char** atts) {
+  auto* self = static_cast<ContainerParser*>(userData);
+
+  // Simple state tracking to ensure we are looking at the valid schema structure
+  if (self->state == START && strcmp(name, "container") == 0) {
+    self->state = IN_CONTAINER;
+    return;
+  }
+
+  if (self->state == IN_CONTAINER && strcmp(name, "rootfiles") == 0) {
+    self->state = IN_ROOTFILES;
+    return;
+  }
+
+  if (self->state == IN_ROOTFILES && strcmp(name, "rootfile") == 0) {
+    const char* mediaType = nullptr;
+    const char* path = nullptr;
+
+    for (int i = 0; atts[i]; i += 2) {
+      if (strcmp(atts[i], "media-type") == 0) {
+        mediaType = atts[i + 1];
+      } else if (strcmp(atts[i], "full-path") == 0) {
+        path = atts[i + 1];
+      }
+    }
+
+    // Check if this is the standard OEBPS package
+    if (mediaType && path && strcmp(mediaType, "application/oebps-package+xml") == 0) {
+      self->fullPath = path;
+    }
+  }
+}
+
+void XMLCALL ContainerParser::endElement(void* userData, const XML_Char* name) {
+  auto* self = static_cast<ContainerParser*>(userData);
+
+  if (self->state == IN_ROOTFILES && strcmp(name, "rootfiles") == 0) {
+    self->state = IN_CONTAINER;
+  } else if (self->state == IN_CONTAINER && strcmp(name, "container") == 0) {
+    self->state = START;
+  }
+}

lib/Epub/Epub/parsers/ContainerParser.h

@@ -0,0 +1,32 @@
+#pragma once
+#include <Print.h>
+
+#include <string>
+
+#include "expat.h"
+
+class ContainerParser final : public Print {
+  enum ParserState {
+    START,
+    IN_CONTAINER,
+    IN_ROOTFILES,
+  };
+
+  size_t remainingSize;
+  XML_Parser parser = nullptr;
+  ParserState state = START;
+
+  static void startElement(void* userData, const XML_Char* name, const XML_Char** atts);
+  static void endElement(void* userData, const XML_Char* name);
+
+ public:
+  std::string fullPath;
+
+  explicit ContainerParser(const size_t xmlSize) : remainingSize(xmlSize) {}
+  ~ContainerParser() override;
+
+  bool setup();
+
+  size_t write(uint8_t) override;
+  size_t write(const uint8_t* buffer, size_t size) override;
+};

lib/Epub/Epub/parsers/ContentOpfParser.cpp

@@ -0,0 +1,243 @@
+#include "ContentOpfParser.h"
+
+#include <FsHelpers.h>
+#include <HardwareSerial.h>
+#include <Serialization.h>
+#include <ZipFile.h>
+
+#include "../BookMetadataCache.h"
+
+namespace {
+constexpr char MEDIA_TYPE_NCX[] = "application/x-dtbncx+xml";
+constexpr char itemCacheFile[] = "/.items.bin";
+}  // namespace
+
+bool ContentOpfParser::setup() {
+  parser = XML_ParserCreate(nullptr);
+  if (!parser) {
+    Serial.printf("[%lu] [COF] Couldn't allocate memory for parser\n", millis());
+    return false;
+  }
+
+  XML_SetUserData(parser, this);
+  XML_SetElementHandler(parser, startElement, endElement);
+  XML_SetCharacterDataHandler(parser, characterData);
+  return true;
+}
+
+ContentOpfParser::~ContentOpfParser() {
+  if (parser) {
+    XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+    XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+    XML_SetCharacterDataHandler(parser, nullptr);
+    XML_ParserFree(parser);
+    parser = nullptr;
+  }
+  if (tempItemStore) {
+    tempItemStore.close();
+  }
+  if (SD.exists((cachePath + itemCacheFile).c_str())) {
+    SD.remove((cachePath + itemCacheFile).c_str());
+  }
+}
+
+size_t ContentOpfParser::write(const uint8_t data) { return write(&data, 1); }
+
+size_t ContentOpfParser::write(const uint8_t* buffer, const size_t size) {
+  if (!parser) return 0;
+
+  const uint8_t* currentBufferPos = buffer;
+  auto remainingInBuffer = size;
+
+  while (remainingInBuffer > 0) {
+    void* const buf = XML_GetBuffer(parser, 1024);
+
+    if (!buf) {
+      Serial.printf("[%lu] [COF] Couldn't allocate memory for buffer\n", millis());
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
+      XML_ParserFree(parser);
+      parser = nullptr;
+      return 0;
+    }
+
+    const auto toRead = remainingInBuffer < 1024 ? remainingInBuffer : 1024;
+    memcpy(buf, currentBufferPos, toRead);
+
+    if (XML_ParseBuffer(parser, static_cast<int>(toRead), remainingSize == toRead) == XML_STATUS_ERROR) {
+      Serial.printf("[%lu] [COF] Parse error at line %lu: %s\n", millis(), XML_GetCurrentLineNumber(parser),
+                    XML_ErrorString(XML_GetErrorCode(parser)));
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
+      XML_ParserFree(parser);
+      parser = nullptr;
+      return 0;
+    }
+
+    currentBufferPos += toRead;
+    remainingInBuffer -= toRead;
+    remainingSize -= toRead;
+  }
+
+  return size;
+}
+
+void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name, const XML_Char** atts) {
+  auto* self = static_cast<ContentOpfParser*>(userData);
+  (void)atts;
+
+  if (self->state == START && (strcmp(name, "package") == 0 || strcmp(name, "opf:package") == 0)) {
+    self->state = IN_PACKAGE;
+    return;
+  }
+
+  if (self->state == IN_PACKAGE && (strcmp(name, "metadata") == 0 || strcmp(name, "opf:metadata") == 0)) {
+    self->state = IN_METADATA;
+    return;
+  }
+
+  if (self->state == IN_METADATA && strcmp(name, "dc:title") == 0) {
+    self->state = IN_BOOK_TITLE;
+    return;
+  }
+
+  if (self->state == IN_PACKAGE && (strcmp(name, "manifest") == 0 || strcmp(name, "opf:manifest") == 0)) {
+    self->state = IN_MANIFEST;
+    if (!FsHelpers::openFileForWrite("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
+      Serial.printf(
+          "[%lu] [COF] Couldn't open temp items file for writing. This is probably going to be a fatal error.\n",
+          millis());
+    }
+    return;
+  }
+
+  if (self->state == IN_PACKAGE && (strcmp(name, "spine") == 0 || strcmp(name, "opf:spine") == 0)) {
+    self->state = IN_SPINE;
+    if (!FsHelpers::openFileForRead("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
+      Serial.printf(
+          "[%lu] [COF] Couldn't open temp items file for reading. This is probably going to be a fatal error.\n",
+          millis());
+    }
+    return;
+  }
+
+  if (self->state == IN_METADATA && (strcmp(name, "meta") == 0 || strcmp(name, "opf:meta") == 0)) {
+    bool isCover = false;
+    std::string coverItemId;
+
+    for (int i = 0; atts[i]; i += 2) {
+      if (strcmp(atts[i], "name") == 0 && strcmp(atts[i + 1], "cover") == 0) {
+        isCover = true;
+      } else if (strcmp(atts[i], "content") == 0) {
+        coverItemId = atts[i + 1];
+      }
+    }
+
+    if (isCover) {
+      self->coverItemId = coverItemId;
+    }
+    return;
+  }
+
+  if (self->state == IN_MANIFEST && (strcmp(name, "item") == 0 || strcmp(name, "opf:item") == 0)) {
+    std::string itemId;
+    std::string href;
+    std::string mediaType;
+
+    for (int i = 0; atts[i]; i += 2) {
+      if (strcmp(atts[i], "id") == 0) {
+        itemId = atts[i + 1];
+      } else if (strcmp(atts[i], "href") == 0) {
+        href = self->baseContentPath + atts[i + 1];
+      } else if (strcmp(atts[i], "media-type") == 0) {
+        mediaType = atts[i + 1];
+      }
+    }
+
+    // Write items down to SD card
+    serialization::writeString(self->tempItemStore, itemId);
+    serialization::writeString(self->tempItemStore, href);
+
+    if (itemId == self->coverItemId) {
+      self->coverItemHref = href;
+    }
+
+    if (mediaType == MEDIA_TYPE_NCX) {
+      if (self->tocNcxPath.empty()) {
+        self->tocNcxPath = href;
+      } else {
+        Serial.printf("[%lu] [COF] Warning: Multiple NCX files found in manifest. Ignoring duplicate: %s\n", millis(),
+                      href.c_str());
+      }
+    }
+    return;
+  }
+
+  // NOTE: This relies on spine appearing after item manifest (which is pretty safe as it's part of the EPUB spec)
+  // Only run the spine parsing if there's a cache to add it to
+  if (self->cache) {
+    if (self->state == IN_SPINE && (strcmp(name, "itemref") == 0 || strcmp(name, "opf:itemref") == 0)) {
+      for (int i = 0; atts[i]; i += 2) {
+        if (strcmp(atts[i], "idref") == 0) {
+          const std::string idref = atts[i + 1];
+          // Resolve the idref to href using items map
+          self->tempItemStore.seek(0);
+          std::string itemId;
+          std::string href;
+          while (self->tempItemStore.available()) {
+            serialization::readString(self->tempItemStore, itemId);
+            serialization::readString(self->tempItemStore, href);
+            if (itemId == idref) {
+              self->cache->createSpineEntry(href);
+              break;
+            }
+          }
+        }
+      }
+      return;
+    }
+  }
+}
+
+void XMLCALL ContentOpfParser::characterData(void* userData, const XML_Char* s, const int len) {
+  auto* self = static_cast<ContentOpfParser*>(userData);
+
+  if (self->state == IN_BOOK_TITLE) {
+    self->title.append(s, len);
+    return;
+  }
+}
+
+void XMLCALL ContentOpfParser::endElement(void* userData, const XML_Char* name) {
+  auto* self = static_cast<ContentOpfParser*>(userData);
+  (void)name;
+
+  if (self->state == IN_SPINE && (strcmp(name, "spine") == 0 || strcmp(name, "opf:spine") == 0)) {
+    self->state = IN_PACKAGE;
+    self->tempItemStore.close();
+    return;
+  }
+
+  if (self->state == IN_MANIFEST && (strcmp(name, "manifest") == 0 || strcmp(name, "opf:manifest") == 0)) {
+    self->state = IN_PACKAGE;
+    self->tempItemStore.close();
+    return;
+  }
+
+  if (self->state == IN_BOOK_TITLE && strcmp(name, "dc:title") == 0) {
+    self->state = IN_METADATA;
+    return;
+  }
+
+  if (self->state == IN_METADATA && (strcmp(name, "metadata") == 0 || strcmp(name, "opf:metadata") == 0)) {
+    self->state = IN_PACKAGE;
+    return;
+  }
+
+  if (self->state == IN_PACKAGE && (strcmp(name, "package") == 0 || strcmp(name, "opf:package") == 0)) {
+    self->state = START;
+    return;
+  }
+}

lib/Epub/Epub/parsers/ContentOpfParser.h

@@ -0,0 +1,46 @@
+#pragma once
+#include <Print.h>
+
+#include "Epub.h"
+#include "expat.h"
+
+class BookMetadataCache;
+
+class ContentOpfParser final : public Print {
+  enum ParserState {
+    START,
+    IN_PACKAGE,
+    IN_METADATA,
+    IN_BOOK_TITLE,
+    IN_MANIFEST,
+    IN_SPINE,
+  };
+
+  const std::string& cachePath;
+  const std::string& baseContentPath;
+  size_t remainingSize;
+  XML_Parser parser = nullptr;
+  ParserState state = START;
+  BookMetadataCache* cache;
+  File tempItemStore;
+  std::string coverItemId;
+
+  static void startElement(void* userData, const XML_Char* name, const XML_Char** atts);
+  static void characterData(void* userData, const XML_Char* s, int len);
+  static void endElement(void* userData, const XML_Char* name);
+
+ public:
+  std::string title;
+  std::string tocNcxPath;
+  std::string coverItemHref;
+
+  explicit ContentOpfParser(const std::string& cachePath, const std::string& baseContentPath, const size_t xmlSize,
+                            BookMetadataCache* cache)
+      : cachePath(cachePath), baseContentPath(baseContentPath), remainingSize(xmlSize), cache(cache) {}
+  ~ContentOpfParser() override;
+
+  bool setup();
+
+  size_t write(uint8_t) override;
+  size_t write(const uint8_t* buffer, size_t size) override;
+};

lib/Epub/Epub/parsers/TocNcxParser.cpp

@@ -0,0 +1,180 @@
+#include "TocNcxParser.h"
+
+#include <HardwareSerial.h>
+
+#include "../BookMetadataCache.h"
+
+bool TocNcxParser::setup() {
+  parser = XML_ParserCreate(nullptr);
+  if (!parser) {
+    Serial.printf("[%lu] [TOC] Couldn't allocate memory for parser\n", millis());
+    return false;
+  }
+
+  XML_SetUserData(parser, this);
+  XML_SetElementHandler(parser, startElement, endElement);
+  XML_SetCharacterDataHandler(parser, characterData);
+  return true;
+}
+
+TocNcxParser::~TocNcxParser() {
+  if (parser) {
+    XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+    XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+    XML_SetCharacterDataHandler(parser, nullptr);
+    XML_ParserFree(parser);
+    parser = nullptr;
+  }
+}
+
+size_t TocNcxParser::write(const uint8_t data) { return write(&data, 1); }
+
+size_t TocNcxParser::write(const uint8_t* buffer, const size_t size) {
+  if (!parser) return 0;
+
+  const uint8_t* currentBufferPos = buffer;
+  auto remainingInBuffer = size;
+
+  while (remainingInBuffer > 0) {
+    void* const buf = XML_GetBuffer(parser, 1024);
+    if (!buf) {
+      Serial.printf("[%lu] [TOC] Couldn't allocate memory for buffer\n", millis());
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
+      XML_ParserFree(parser);
+      parser = nullptr;
+      return 0;
+    }
+
+    const auto toRead = remainingInBuffer < 1024 ? remainingInBuffer : 1024;
+    memcpy(buf, currentBufferPos, toRead);
+
+    if (XML_ParseBuffer(parser, static_cast<int>(toRead), remainingSize == toRead) == XML_STATUS_ERROR) {
+      Serial.printf("[%lu] [TOC] Parse error at line %lu: %s\n", millis(), XML_GetCurrentLineNumber(parser),
+                    XML_ErrorString(XML_GetErrorCode(parser)));
+      XML_StopParser(parser, XML_FALSE);                // Stop any pending processing
+      XML_SetElementHandler(parser, nullptr, nullptr);  // Clear callbacks
+      XML_SetCharacterDataHandler(parser, nullptr);
+      XML_ParserFree(parser);
+      parser = nullptr;
+      return 0;
+    }
+
+    currentBufferPos += toRead;
+    remainingInBuffer -= toRead;
+    remainingSize -= toRead;
+  }
+  return size;
+}
+
+void XMLCALL TocNcxParser::startElement(void* userData, const XML_Char* name, const XML_Char** atts) {
+  // NOTE: We rely on navPoint label and content coming before any nested navPoints, this will be fine:
+  // <navPoint>
+  //   <navLabel><text>Chapter 1</text></navLabel>
+  //   <content src="ch1.html"/>
+  //   <navPoint> ...nested... </navPoint>
+  // </navPoint>
+  //
+  // This will NOT:
+  // <navPoint>
+  //   <navPoint> ...nested... </navPoint>
+  //   <navLabel><text>Chapter 1</text></navLabel>
+  //   <content src="ch1.html"/>
+  // </navPoint>
+
+  auto* self = static_cast<TocNcxParser*>(userData);
+
+  if (self->state == START && strcmp(name, "ncx") == 0) {
+    self->state = IN_NCX;
+    return;
+  }
+
+  if (self->state == IN_NCX && strcmp(name, "navMap") == 0) {
+    self->state = IN_NAV_MAP;
+    return;
+  }
+
+  // Handles both top-level and nested navPoints
+  if ((self->state == IN_NAV_MAP || self->state == IN_NAV_POINT) && strcmp(name, "navPoint") == 0) {
+    self->state = IN_NAV_POINT;
+    self->currentDepth++;
+
+    self->currentLabel.clear();
+    self->currentSrc.clear();
+    return;
+  }
+
+  if (self->state == IN_NAV_POINT && strcmp(name, "navLabel") == 0) {
+    self->state = IN_NAV_LABEL;
+    return;
+  }
+
+  if (self->state == IN_NAV_LABEL && strcmp(name, "text") == 0) {
+    self->state = IN_NAV_LABEL_TEXT;
+    return;
+  }
+
+  if (self->state == IN_NAV_POINT && strcmp(name, "content") == 0) {
+    for (int i = 0; atts[i]; i += 2) {
+      if (strcmp(atts[i], "src") == 0) {
+        self->currentSrc = atts[i + 1];
+        break;
+      }
+    }
+    return;
+  }
+}
+
+void XMLCALL TocNcxParser::characterData(void* userData, const XML_Char* s, const int len) {
+  auto* self = static_cast<TocNcxParser*>(userData);
+  if (self->state == IN_NAV_LABEL_TEXT) {
+    self->currentLabel.append(s, len);
+  }
+}
+
+void XMLCALL TocNcxParser::endElement(void* userData, const XML_Char* name) {
+  auto* self = static_cast<TocNcxParser*>(userData);
+
+  if (self->state == IN_NAV_LABEL_TEXT && strcmp(name, "text") == 0) {
+    self->state = IN_NAV_LABEL;
+    return;
+  }
+
+  if (self->state == IN_NAV_LABEL && strcmp(name, "navLabel") == 0) {
+    self->state = IN_NAV_POINT;
+    return;
+  }
+
+  if (self->state == IN_NAV_POINT && strcmp(name, "navPoint") == 0) {
+    self->currentDepth--;
+    if (self->currentDepth == 0) {
+      self->state = IN_NAV_MAP;
+    }
+    return;
+  }
+
+  if (self->state == IN_NAV_POINT && strcmp(name, "content") == 0) {
+    // At this point (end of content tag), we likely have both Label (from previous tags) and Src.
+    // This is the safest place to push the data, assuming <navLabel> always comes before <content>.
+    // NCX spec says navLabel comes before content.
+    if (!self->currentLabel.empty() && !self->currentSrc.empty()) {
+      std::string href = self->baseContentPath + self->currentSrc;
+      std::string anchor;
+
+      const size_t pos = href.find('#');
+      if (pos != std::string::npos) {
+        anchor = href.substr(pos + 1);
+        href = href.substr(0, pos);
+      }
+
+      if (self->cache) {
+        self->cache->createTocEntry(self->currentLabel, href, anchor, self->currentDepth);
+      }
+
+      // Clear them so we don't re-add them if there are weird XML structures
+      self->currentLabel.clear();
+      self->currentSrc.clear();
+    }
+  }
+}

lib/Epub/Epub/parsers/TocNcxParser.h

@@ -0,0 +1,35 @@
+#pragma once
+#include <Print.h>
+#include <expat.h>
+
+#include <string>
+
+class BookMetadataCache;
+
+class TocNcxParser final : public Print {
+  enum ParserState { START, IN_NCX, IN_NAV_MAP, IN_NAV_POINT, IN_NAV_LABEL, IN_NAV_LABEL_TEXT, IN_CONTENT };
+
+  const std::string& baseContentPath;
+  size_t remainingSize;
+  XML_Parser parser = nullptr;
+  ParserState state = START;
+  BookMetadataCache* cache;
+
+  std::string currentLabel;
+  std::string currentSrc;
+  uint8_t currentDepth = 0;
+
+  static void startElement(void* userData, const XML_Char* name, const XML_Char** atts);
+  static void characterData(void* userData, const XML_Char* s, int len);
+  static void endElement(void* userData, const XML_Char* name);
+
+ public:
+  explicit TocNcxParser(const std::string& baseContentPath, const size_t xmlSize, BookMetadataCache* cache)
+      : baseContentPath(baseContentPath), remainingSize(xmlSize), cache(cache) {}
+  ~TocNcxParser() override;
+
+  bool setup();
+
+  size_t write(uint8_t) override;
+  size_t write(const uint8_t* buffer, size_t size) override;
+};

lib/FsHelpers/FsHelpers.cpp

@@ -0,0 +1,112 @@
+#include "FsHelpers.h"
+
+#include <SD.h>
+
+#include <vector>
+
+bool FsHelpers::openFileForRead(const char* moduleName, const char* path, File& file) {
+  if (!SD.exists(path)) {
+    return false;
+  }
+
+  file = SD.open(path, FILE_READ);
+  if (!file) {
+    Serial.printf("[%lu] [%s] Failed to open file for reading: %s\n", millis(), moduleName, path);
+    return false;
+  }
+  return true;
+}
+
+bool FsHelpers::openFileForRead(const char* moduleName, const std::string& path, File& file) {
+  return openFileForRead(moduleName, path.c_str(), file);
+}
+
+bool FsHelpers::openFileForRead(const char* moduleName, const String& path, File& file) {
+  return openFileForRead(moduleName, path.c_str(), file);
+}
+
+bool FsHelpers::openFileForWrite(const char* moduleName, const char* path, File& file) {
+  file = SD.open(path, FILE_WRITE, true);
+  if (!file) {
+    Serial.printf("[%lu] [%s] Failed to open file for writing: %s\n", millis(), moduleName, path);
+    return false;
+  }
+  return true;
+}
+
+bool FsHelpers::openFileForWrite(const char* moduleName, const std::string& path, File& file) {
+  return openFileForWrite(moduleName, path.c_str(), file);
+}
+
+bool FsHelpers::openFileForWrite(const char* moduleName, const String& path, File& file) {
+  return openFileForWrite(moduleName, path.c_str(), file);
+}
+
+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/FsHelpers/FsHelpers.h

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

lib/GfxRenderer/Bitmap.cpp

@@ -0,0 +1,200 @@
+#include "Bitmap.h"
+
+#include <cstdlib>
+#include <cstring>
+
+uint16_t Bitmap::readLE16(File& f) {
+  const int c0 = f.read();
+  const int c1 = f.read();
+  const auto b0 = static_cast<uint8_t>(c0 < 0 ? 0 : c0);
+  const auto b1 = static_cast<uint8_t>(c1 < 0 ? 0 : c1);
+  return static_cast<uint16_t>(b0) | (static_cast<uint16_t>(b1) << 8);
+}
+
+uint32_t Bitmap::readLE32(File& f) {
+  const int c0 = f.read();
+  const int c1 = f.read();
+  const int c2 = f.read();
+  const int c3 = f.read();
+
+  const auto b0 = static_cast<uint8_t>(c0 < 0 ? 0 : c0);
+  const auto b1 = static_cast<uint8_t>(c1 < 0 ? 0 : c1);
+  const auto b2 = static_cast<uint8_t>(c2 < 0 ? 0 : c2);
+  const auto b3 = static_cast<uint8_t>(c3 < 0 ? 0 : c3);
+
+  return static_cast<uint32_t>(b0) | (static_cast<uint32_t>(b1) << 8) | (static_cast<uint32_t>(b2) << 16) |
+         (static_cast<uint32_t>(b3) << 24);
+}
+
+const char* Bitmap::errorToString(BmpReaderError err) {
+  switch (err) {
+    case BmpReaderError::Ok:
+      return "Ok";
+    case BmpReaderError::FileInvalid:
+      return "FileInvalid";
+    case BmpReaderError::SeekStartFailed:
+      return "SeekStartFailed";
+    case BmpReaderError::NotBMP:
+      return "NotBMP (missing 'BM')";
+    case BmpReaderError::DIBTooSmall:
+      return "DIBTooSmall (<40 bytes)";
+    case BmpReaderError::BadPlanes:
+      return "BadPlanes (!= 1)";
+    case BmpReaderError::UnsupportedBpp:
+      return "UnsupportedBpp (expected 1, 2, 8, 24, or 32)";
+    case BmpReaderError::UnsupportedCompression:
+      return "UnsupportedCompression (expected BI_RGB or BI_BITFIELDS for 32bpp)";
+    case BmpReaderError::BadDimensions:
+      return "BadDimensions";
+    case BmpReaderError::PaletteTooLarge:
+      return "PaletteTooLarge";
+
+    case BmpReaderError::SeekPixelDataFailed:
+      return "SeekPixelDataFailed";
+    case BmpReaderError::BufferTooSmall:
+      return "BufferTooSmall";
+
+    case BmpReaderError::OomRowBuffer:
+      return "OomRowBuffer";
+    case BmpReaderError::ShortReadRow:
+      return "ShortReadRow";
+  }
+  return "Unknown";
+}
+
+BmpReaderError Bitmap::parseHeaders() {
+  if (!file) return BmpReaderError::FileInvalid;
+  if (!file.seek(0)) return BmpReaderError::SeekStartFailed;
+
+  // --- BMP FILE HEADER ---
+  const uint16_t bfType = readLE16(file);
+  if (bfType != 0x4D42) return BmpReaderError::NotBMP;
+
+  file.seek(8, SeekCur);
+  bfOffBits = readLE32(file);
+
+  // --- DIB HEADER ---
+  const uint32_t biSize = readLE32(file);
+  if (biSize < 40) return BmpReaderError::DIBTooSmall;
+
+  width = static_cast<int32_t>(readLE32(file));
+  const auto rawHeight = static_cast<int32_t>(readLE32(file));
+  topDown = rawHeight < 0;
+  height = topDown ? -rawHeight : rawHeight;
+
+  const uint16_t planes = readLE16(file);
+  bpp = readLE16(file);
+  const uint32_t comp = readLE32(file);
+  const bool validBpp = bpp == 1 || bpp == 2 || bpp == 8 || bpp == 24 || bpp == 32;
+
+  if (planes != 1) return BmpReaderError::BadPlanes;
+  if (!validBpp) return BmpReaderError::UnsupportedBpp;
+  // Allow BI_RGB (0) for all, and BI_BITFIELDS (3) for 32bpp which is common for BGRA masks.
+  if (!(comp == 0 || (bpp == 32 && comp == 3))) return BmpReaderError::UnsupportedCompression;
+
+  file.seek(12, SeekCur);  // biSizeImage, biXPelsPerMeter, biYPelsPerMeter
+  const uint32_t colorsUsed = readLE32(file);
+  if (colorsUsed > 256u) return BmpReaderError::PaletteTooLarge;
+  file.seek(4, SeekCur);  // biClrImportant
+
+  if (width <= 0 || height <= 0) return BmpReaderError::BadDimensions;
+
+  // Pre-calculate Row Bytes to avoid doing this every row
+  rowBytes = (width * bpp + 31) / 32 * 4;
+
+  for (int i = 0; i < 256; i++) paletteLum[i] = static_cast<uint8_t>(i);
+  if (colorsUsed > 0) {
+    for (uint32_t i = 0; i < colorsUsed; i++) {
+      uint8_t rgb[4];
+      file.read(rgb, 4);  // Read B, G, R, Reserved in one go
+      paletteLum[i] = (77u * rgb[2] + 150u * rgb[1] + 29u * rgb[0]) >> 8;
+    }
+  }
+
+  if (!file.seek(bfOffBits)) {
+    return BmpReaderError::SeekPixelDataFailed;
+  }
+
+  return BmpReaderError::Ok;
+}
+
+// packed 2bpp output, 0 = black, 1 = dark gray, 2 = light gray, 3 = white
+BmpReaderError Bitmap::readRow(uint8_t* data, uint8_t* rowBuffer) const {
+  // Note: rowBuffer should be pre-allocated by the caller to size 'rowBytes'
+  if (file.read(rowBuffer, rowBytes) != rowBytes) return BmpReaderError::ShortReadRow;
+
+  uint8_t* outPtr = data;
+  uint8_t currentOutByte = 0;
+  int bitShift = 6;
+
+  // Helper lambda to pack 2bpp color into the output stream
+  auto packPixel = [&](const uint8_t lum) {
+    uint8_t color = (lum >> 6);  // Simple 2-bit reduction: 0-255 -> 0-3
+    currentOutByte |= (color << bitShift);
+    if (bitShift == 0) {
+      *outPtr++ = currentOutByte;
+      currentOutByte = 0;
+      bitShift = 6;
+    } else {
+      bitShift -= 2;
+    }
+  };
+
+  uint8_t lum;
+
+  switch (bpp) {
+    case 32: {
+      const uint8_t* p = rowBuffer;
+      for (int x = 0; x < width; x++) {
+        lum = (77u * p[2] + 150u * p[1] + 29u * p[0]) >> 8;
+        packPixel(lum);
+        p += 4;
+      }
+      break;
+    }
+    case 24: {
+      const uint8_t* p = rowBuffer;
+      for (int x = 0; x < width; x++) {
+        lum = (77u * p[2] + 150u * p[1] + 29u * p[0]) >> 8;
+        packPixel(lum);
+        p += 3;
+      }
+      break;
+    }
+    case 8: {
+      for (int x = 0; x < width; x++) {
+        packPixel(paletteLum[rowBuffer[x]]);
+      }
+      break;
+    }
+    case 2: {
+      for (int x = 0; x < width; x++) {
+        lum = paletteLum[(rowBuffer[x >> 2] >> (6 - ((x & 3) * 2))) & 0x03];
+        packPixel(lum);
+      }
+      break;
+    }
+    case 1: {
+      for (int x = 0; x < width; x++) {
+        lum = (rowBuffer[x >> 3] & (0x80 >> (x & 7))) ? 0xFF : 0x00;
+        packPixel(lum);
+      }
+      break;
+    }
+    default:
+      return BmpReaderError::UnsupportedBpp;
+  }
+
+  // Flush remaining bits if width is not a multiple of 4
+  if (bitShift != 6) *outPtr = currentOutByte;
+
+  return BmpReaderError::Ok;
+}
+
+BmpReaderError Bitmap::rewindToData() const {
+  if (!file.seek(bfOffBits)) {
+    return BmpReaderError::SeekPixelDataFailed;
+  }
+
+  return BmpReaderError::Ok;
+}

lib/GfxRenderer/Bitmap.h

@@ -0,0 +1,52 @@
+#pragma once
+
+#include <FS.h>
+
+enum class BmpReaderError : uint8_t {
+  Ok = 0,
+  FileInvalid,
+  SeekStartFailed,
+
+  NotBMP,
+  DIBTooSmall,
+
+  BadPlanes,
+  UnsupportedBpp,
+  UnsupportedCompression,
+
+  BadDimensions,
+  PaletteTooLarge,
+
+  SeekPixelDataFailed,
+  BufferTooSmall,
+  OomRowBuffer,
+  ShortReadRow,
+};
+
+class Bitmap {
+ public:
+  static const char* errorToString(BmpReaderError err);
+
+  explicit Bitmap(File& file) : file(file) {}
+  BmpReaderError parseHeaders();
+  BmpReaderError readRow(uint8_t* data, uint8_t* rowBuffer) const;
+  BmpReaderError rewindToData() const;
+  int getWidth() const { return width; }
+  int getHeight() const { return height; }
+  bool isTopDown() const { return topDown; }
+  bool hasGreyscale() const { return bpp > 1; }
+  int getRowBytes() const { return rowBytes; }
+
+ private:
+  static uint16_t readLE16(File& f);
+  static uint32_t readLE32(File& f);
+
+  File& file;
+  int width = 0;
+  int height = 0;
+  bool topDown = false;
+  uint32_t bfOffBits = 0;
+  uint16_t bpp = 0;
+  int rowBytes = 0;
+  uint8_t paletteLum[256] = {};
+};

lib/GfxRenderer/GfxRenderer.cpp

@@ -0,0 +1,410 @@
+#include "GfxRenderer.h"
+
+#include <Utf8.h>
+
+void GfxRenderer::insertFont(const int fontId, EpdFontFamily font) { fontMap.insert({fontId, font}); }
+
+void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
+  uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+
+  // Early return if no framebuffer is set
+  if (!frameBuffer) {
+    Serial.printf("[%lu] [GFX] !! No framebuffer\n", millis());
+    return;
+  }
+
+  // Rotate coordinates: portrait (480x800) -> landscape (800x480)
+  // Rotation: 90 degrees clockwise
+  const int rotatedX = y;
+  const int rotatedY = EInkDisplay::DISPLAY_HEIGHT - 1 - x;
+
+  // Bounds checking (portrait: 480x800)
+  if (rotatedX < 0 || rotatedX >= EInkDisplay::DISPLAY_WIDTH || rotatedY < 0 ||
+      rotatedY >= EInkDisplay::DISPLAY_HEIGHT) {
+    Serial.printf("[%lu] [GFX] !! Outside range (%d, %d)\n", millis(), x, y);
+    return;
+  }
+
+  // Calculate byte position and bit position
+  const uint16_t byteIndex = rotatedY * EInkDisplay::DISPLAY_WIDTH_BYTES + (rotatedX / 8);
+  const uint8_t bitPosition = 7 - (rotatedX % 8);  // MSB first
+
+  if (state) {
+    frameBuffer[byteIndex] &= ~(1 << bitPosition);  // Clear bit
+  } else {
+    frameBuffer[byteIndex] |= 1 << bitPosition;  // Set bit
+  }
+}
+
+int GfxRenderer::getTextWidth(const int fontId, const char* text, const EpdFontStyle style) const {
+  if (fontMap.count(fontId) == 0) {
+    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    return 0;
+  }
+
+  int w = 0, h = 0;
+  fontMap.at(fontId).getTextDimensions(text, &w, &h, style);
+  return w;
+}
+
+void GfxRenderer::drawCenteredText(const int fontId, const int y, const char* text, const bool black,
+                                   const EpdFontStyle style) const {
+  const int x = (getScreenWidth() - getTextWidth(fontId, text, style)) / 2;
+  drawText(fontId, x, y, text, black, style);
+}
+
+void GfxRenderer::drawText(const int fontId, const int x, const int y, const char* text, const bool black,
+                           const EpdFontStyle style) const {
+  const int yPos = y + getLineHeight(fontId);
+  int xpos = x;
+
+  // cannot draw a NULL / empty string
+  if (text == nullptr || *text == '\0') {
+    return;
+  }
+
+  if (fontMap.count(fontId) == 0) {
+    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    return;
+  }
+  const auto font = fontMap.at(fontId);
+
+  // no printable characters
+  if (!font.hasPrintableChars(text, style)) {
+    return;
+  }
+
+  uint32_t cp;
+  while ((cp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&text)))) {
+    renderChar(font, cp, &xpos, &yPos, black, style);
+  }
+}
+
+void GfxRenderer::drawLine(int x1, int y1, int x2, int y2, const bool state) const {
+  if (x1 == x2) {
+    if (y2 < y1) {
+      std::swap(y1, y2);
+    }
+    for (int y = y1; y <= y2; y++) {
+      drawPixel(x1, y, state);
+    }
+  } else if (y1 == y2) {
+    if (x2 < x1) {
+      std::swap(x1, x2);
+    }
+    for (int x = x1; x <= x2; x++) {
+      drawPixel(x, y1, state);
+    }
+  } else {
+    // TODO: Implement
+    Serial.printf("[%lu] [GFX] Line drawing not supported\n", millis());
+  }
+}
+
+void GfxRenderer::drawRect(const int x, const int y, const int width, const int height, const bool state) const {
+  drawLine(x, y, x + width - 1, y, state);
+  drawLine(x + width - 1, y, x + width - 1, y + height - 1, state);
+  drawLine(x + width - 1, y + height - 1, x, y + height - 1, state);
+  drawLine(x, y, x, y + height - 1, state);
+}
+
+void GfxRenderer::fillRect(const int x, const int y, const int width, const int height, const bool state) const {
+  for (int fillY = y; fillY < y + height; fillY++) {
+    drawLine(x, fillY, x + width - 1, fillY, state);
+  }
+}
+
+void GfxRenderer::drawImage(const uint8_t bitmap[], const int x, const int y, const int width, const int height) const {
+  // Flip X and Y for portrait mode
+  einkDisplay.drawImage(bitmap, y, x, height, width);
+}
+
+void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, const int maxWidth,
+                             const int maxHeight) const {
+  float scale = 1.0f;
+  bool isScaled = false;
+  if (maxWidth > 0 && bitmap.getWidth() > maxWidth) {
+    scale = static_cast<float>(maxWidth) / static_cast<float>(bitmap.getWidth());
+    isScaled = true;
+  }
+  if (maxHeight > 0 && bitmap.getHeight() > maxHeight) {
+    scale = std::min(scale, static_cast<float>(maxHeight) / static_cast<float>(bitmap.getHeight()));
+    isScaled = true;
+  }
+
+  const uint8_t outputRowSize = (bitmap.getWidth() + 3) / 4;
+  auto* outputRow = static_cast<uint8_t*>(malloc(outputRowSize));
+  auto* rowBytes = static_cast<uint8_t*>(malloc(bitmap.getRowBytes()));
+
+  if (!outputRow || !rowBytes) {
+    Serial.printf("[%lu] [GFX] !! Failed to allocate BMP row buffers\n", millis());
+    free(outputRow);
+    free(rowBytes);
+    return;
+  }
+
+  for (int bmpY = 0; bmpY < bitmap.getHeight(); bmpY++) {
+    // The BMP's (0, 0) is the bottom-left corner (if the height is positive, top-left if negative).
+    // Screen's (0, 0) is the top-left corner.
+    int screenY = y + (bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY);
+    if (isScaled) {
+      screenY = std::floor(screenY * scale);
+    }
+    if (screenY >= getScreenHeight()) {
+      break;
+    }
+
+    if (bitmap.readRow(outputRow, rowBytes) != BmpReaderError::Ok) {
+      Serial.printf("[%lu] [GFX] Failed to read row %d from bitmap\n", millis(), bmpY);
+      free(outputRow);
+      free(rowBytes);
+      return;
+    }
+
+    for (int bmpX = 0; bmpX < bitmap.getWidth(); bmpX++) {
+      int screenX = x + bmpX;
+      if (isScaled) {
+        screenX = std::floor(screenX * scale);
+      }
+      if (screenX >= getScreenWidth()) {
+        break;
+      }
+
+      const uint8_t val = outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8)) & 0x3;
+
+      if (renderMode == BW && val < 3) {
+        drawPixel(screenX, screenY);
+      } else if (renderMode == GRAYSCALE_MSB && (val == 1 || val == 2)) {
+        drawPixel(screenX, screenY, false);
+      } else if (renderMode == GRAYSCALE_LSB && val == 1) {
+        drawPixel(screenX, screenY, false);
+      }
+    }
+  }
+
+  free(outputRow);
+  free(rowBytes);
+}
+
+void GfxRenderer::clearScreen(const uint8_t color) const { einkDisplay.clearScreen(color); }
+
+void GfxRenderer::invertScreen() const {
+  uint8_t* buffer = einkDisplay.getFrameBuffer();
+  if (!buffer) {
+    Serial.printf("[%lu] [GFX] !! No framebuffer in invertScreen\n", millis());
+    return;
+  }
+  for (int i = 0; i < EInkDisplay::BUFFER_SIZE; i++) {
+    buffer[i] = ~buffer[i];
+  }
+}
+
+void GfxRenderer::displayBuffer(const EInkDisplay::RefreshMode refreshMode) const {
+  einkDisplay.displayBuffer(refreshMode);
+}
+
+void GfxRenderer::displayWindow(const int x, const int y, const int width, const int height) const {
+  // Rotate coordinates from portrait (480x800) to landscape (800x480)
+  // Rotation: 90 degrees clockwise
+  // Portrait coordinates: (x, y) with dimensions (width, height)
+  // Landscape coordinates: (rotatedX, rotatedY) with dimensions (rotatedWidth, rotatedHeight)
+
+  const int rotatedX = y;
+  const int rotatedY = EInkDisplay::DISPLAY_HEIGHT - 1 - x - width + 1;
+  const int rotatedWidth = height;
+  const int rotatedHeight = width;
+
+  einkDisplay.displayWindow(rotatedX, rotatedY, rotatedWidth, rotatedHeight);
+}
+
+// Note: Internal driver treats screen in command orientation, this library treats in portrait orientation
+int GfxRenderer::getScreenWidth() { return EInkDisplay::DISPLAY_HEIGHT; }
+int GfxRenderer::getScreenHeight() { return EInkDisplay::DISPLAY_WIDTH; }
+
+int GfxRenderer::getSpaceWidth(const int fontId) const {
+  if (fontMap.count(fontId) == 0) {
+    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    return 0;
+  }
+
+  return fontMap.at(fontId).getGlyph(' ', REGULAR)->advanceX;
+}
+
+int GfxRenderer::getLineHeight(const int fontId) const {
+  if (fontMap.count(fontId) == 0) {
+    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
+    return 0;
+  }
+
+  return fontMap.at(fontId).getData(REGULAR)->advanceY;
+}
+
+uint8_t* GfxRenderer::getFrameBuffer() const { return einkDisplay.getFrameBuffer(); }
+
+size_t GfxRenderer::getBufferSize() { return EInkDisplay::BUFFER_SIZE; }
+
+void GfxRenderer::grayscaleRevert() const { einkDisplay.grayscaleRevert(); }
+
+void GfxRenderer::copyGrayscaleLsbBuffers() const { einkDisplay.copyGrayscaleLsbBuffers(einkDisplay.getFrameBuffer()); }
+
+void GfxRenderer::copyGrayscaleMsbBuffers() const { einkDisplay.copyGrayscaleMsbBuffers(einkDisplay.getFrameBuffer()); }
+
+void GfxRenderer::displayGrayBuffer() const { einkDisplay.displayGrayBuffer(); }
+
+void GfxRenderer::freeBwBufferChunks() {
+  for (auto& bwBufferChunk : bwBufferChunks) {
+    if (bwBufferChunk) {
+      free(bwBufferChunk);
+      bwBufferChunk = nullptr;
+    }
+  }
+}
+
+/**
+ * This should be called before grayscale buffers are populated.
+ * A `restoreBwBuffer` call should always follow the grayscale render if this method was called.
+ * Uses chunked allocation to avoid needing 48KB of contiguous memory.
+ */
+void GfxRenderer::storeBwBuffer() {
+  const uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  if (!frameBuffer) {
+    Serial.printf("[%lu] [GFX] !! No framebuffer in storeBwBuffer\n", millis());
+    return;
+  }
+
+  // Allocate and copy each chunk
+  for (size_t i = 0; i < BW_BUFFER_NUM_CHUNKS; i++) {
+    // Check if any chunks are already allocated
+    if (bwBufferChunks[i]) {
+      Serial.printf("[%lu] [GFX] !! BW buffer chunk %zu already stored - this is likely a bug, freeing chunk\n",
+                    millis(), i);
+      free(bwBufferChunks[i]);
+      bwBufferChunks[i] = nullptr;
+    }
+
+    const size_t offset = i * BW_BUFFER_CHUNK_SIZE;
+    bwBufferChunks[i] = static_cast<uint8_t*>(malloc(BW_BUFFER_CHUNK_SIZE));
+
+    if (!bwBufferChunks[i]) {
+      Serial.printf("[%lu] [GFX] !! Failed to allocate BW buffer chunk %zu (%zu bytes)\n", millis(), i,
+                    BW_BUFFER_CHUNK_SIZE);
+      // Free previously allocated chunks
+      freeBwBufferChunks();
+      return;
+    }
+
+    memcpy(bwBufferChunks[i], frameBuffer + offset, BW_BUFFER_CHUNK_SIZE);
+  }
+
+  Serial.printf("[%lu] [GFX] Stored BW buffer in %zu chunks (%zu bytes each)\n", millis(), BW_BUFFER_NUM_CHUNKS,
+                BW_BUFFER_CHUNK_SIZE);
+}
+
+/**
+ * This can only be called if `storeBwBuffer` was called prior to the grayscale render.
+ * It should be called to restore the BW buffer state after grayscale rendering is complete.
+ * Uses chunked restoration to match chunked storage.
+ */
+void GfxRenderer::restoreBwBuffer() {
+  // Check if any all chunks are allocated
+  bool missingChunks = false;
+  for (const auto& bwBufferChunk : bwBufferChunks) {
+    if (!bwBufferChunk) {
+      missingChunks = true;
+      break;
+    }
+  }
+
+  if (missingChunks) {
+    freeBwBufferChunks();
+    return;
+  }
+
+  uint8_t* frameBuffer = einkDisplay.getFrameBuffer();
+  if (!frameBuffer) {
+    Serial.printf("[%lu] [GFX] !! No framebuffer in restoreBwBuffer\n", millis());
+    freeBwBufferChunks();
+    return;
+  }
+
+  for (size_t i = 0; i < BW_BUFFER_NUM_CHUNKS; i++) {
+    // Check if chunk is missing
+    if (!bwBufferChunks[i]) {
+      Serial.printf("[%lu] [GFX] !! BW buffer chunks not stored - this is likely a bug\n", millis());
+      freeBwBufferChunks();
+      return;
+    }
+
+    const size_t offset = i * BW_BUFFER_CHUNK_SIZE;
+    memcpy(frameBuffer + offset, bwBufferChunks[i], BW_BUFFER_CHUNK_SIZE);
+  }
+
+  einkDisplay.cleanupGrayscaleBuffers(frameBuffer);
+
+  freeBwBufferChunks();
+  Serial.printf("[%lu] [GFX] Restored and freed BW buffer chunks\n", millis());
+}
+
+void GfxRenderer::renderChar(const EpdFontFamily& fontFamily, const uint32_t cp, int* x, const int* y,
+                             const bool pixelState, const EpdFontStyle style) const {
+  const EpdGlyph* glyph = fontFamily.getGlyph(cp, style);
+  if (!glyph) {
+    // TODO: Replace with fallback glyph property?
+    glyph = fontFamily.getGlyph('?', style);
+  }
+
+  // no glyph?
+  if (!glyph) {
+    Serial.printf("[%lu] [GFX] No glyph for codepoint %d\n", millis(), cp);
+    return;
+  }
+
+  const int is2Bit = fontFamily.getData(style)->is2Bit;
+  const uint32_t offset = glyph->dataOffset;
+  const uint8_t width = glyph->width;
+  const uint8_t height = glyph->height;
+  const int left = glyph->left;
+
+  const uint8_t* bitmap = nullptr;
+  bitmap = &fontFamily.getData(style)->bitmap[offset];
+
+  if (bitmap != nullptr) {
+    for (int glyphY = 0; glyphY < height; glyphY++) {
+      const int screenY = *y - glyph->top + glyphY;
+      for (int glyphX = 0; glyphX < width; glyphX++) {
+        const int pixelPosition = glyphY * width + glyphX;
+        const int screenX = *x + left + glyphX;
+
+        if (is2Bit) {
+          const uint8_t byte = bitmap[pixelPosition / 4];
+          const uint8_t bit_index = (3 - pixelPosition % 4) * 2;
+          // the direct bit from the font is 0 -> white, 1 -> light gray, 2 -> dark gray, 3 -> black
+          // we swap this to better match the way images and screen think about colors:
+          // 0 -> black, 1 -> dark grey, 2 -> light grey, 3 -> white
+          const uint8_t bmpVal = 3 - (byte >> bit_index) & 0x3;
+
+          if (renderMode == BW && bmpVal < 3) {
+            // Black (also paints over the grays in BW mode)
+            drawPixel(screenX, screenY, pixelState);
+          } else if (renderMode == GRAYSCALE_MSB && (bmpVal == 1 || bmpVal == 2)) {
+            // Light gray (also mark the MSB if it's going to be a dark gray too)
+            // We have to flag pixels in reverse for the gray buffers, as 0 leave alone, 1 update
+            drawPixel(screenX, screenY, false);
+          } else if (renderMode == GRAYSCALE_LSB && bmpVal == 1) {
+            // Dark gray
+            drawPixel(screenX, screenY, false);
+          }
+        } else {
+          const uint8_t byte = bitmap[pixelPosition / 8];
+          const uint8_t bit_index = 7 - (pixelPosition % 8);
+
+          if ((byte >> bit_index) & 1) {
+            drawPixel(screenX, screenY, pixelState);
+          }
+        }
+      }
+    }
+  }
+
+  *x += glyph->advanceX;
+}

lib/GfxRenderer/GfxRenderer.h

@@ -0,0 +1,72 @@
+#pragma once
+
+#include <EInkDisplay.h>
+#include <EpdFontFamily.h>
+#include <FS.h>
+
+#include <map>
+
+#include "Bitmap.h"
+
+class GfxRenderer {
+ public:
+  enum RenderMode { BW, GRAYSCALE_LSB, GRAYSCALE_MSB };
+
+ private:
+  static constexpr size_t BW_BUFFER_CHUNK_SIZE = 8000;  // 8KB chunks to allow for non-contiguous memory
+  static constexpr size_t BW_BUFFER_NUM_CHUNKS = EInkDisplay::BUFFER_SIZE / BW_BUFFER_CHUNK_SIZE;
+  static_assert(BW_BUFFER_CHUNK_SIZE * BW_BUFFER_NUM_CHUNKS == EInkDisplay::BUFFER_SIZE,
+                "BW buffer chunking does not line up with display buffer size");
+
+  EInkDisplay& einkDisplay;
+  RenderMode renderMode;
+  uint8_t* bwBufferChunks[BW_BUFFER_NUM_CHUNKS] = {nullptr};
+  std::map<int, EpdFontFamily> fontMap;
+  void renderChar(const EpdFontFamily& fontFamily, uint32_t cp, int* x, const int* y, bool pixelState,
+                  EpdFontStyle style) const;
+  void freeBwBufferChunks();
+
+ public:
+  explicit GfxRenderer(EInkDisplay& einkDisplay) : einkDisplay(einkDisplay), renderMode(BW) {}
+  ~GfxRenderer() = default;
+
+  // Setup
+  void insertFont(int fontId, EpdFontFamily font);
+
+  // Screen ops
+  static int getScreenWidth();
+  static int getScreenHeight();
+  void displayBuffer(EInkDisplay::RefreshMode refreshMode = EInkDisplay::FAST_REFRESH) const;
+  // EXPERIMENTAL: Windowed update - display only a rectangular region (portrait coordinates)
+  void displayWindow(int x, int y, int width, int height) const;
+  void invertScreen() const;
+  void clearScreen(uint8_t color = 0xFF) const;
+
+  // Drawing
+  void drawPixel(int x, int y, bool state = true) const;
+  void drawLine(int x1, int y1, int x2, int y2, bool state = true) const;
+  void drawRect(int x, int y, int width, int height, bool state = true) const;
+  void fillRect(int x, int y, int width, int height, bool state = true) const;
+  void drawImage(const uint8_t bitmap[], int x, int y, int width, int height) const;
+  void drawBitmap(const Bitmap& bitmap, int x, int y, int maxWidth, int maxHeight) const;
+
+  // Text
+  int getTextWidth(int fontId, const char* text, EpdFontStyle style = REGULAR) const;
+  void drawCenteredText(int fontId, int y, const char* text, bool black = true, EpdFontStyle style = REGULAR) const;
+  void drawText(int fontId, int x, int y, const char* text, bool black = true, EpdFontStyle style = REGULAR) const;
+  int getSpaceWidth(int fontId) const;
+  int getLineHeight(int fontId) const;
+
+  // Grayscale functions
+  void setRenderMode(const RenderMode mode) { this->renderMode = mode; }
+  void copyGrayscaleLsbBuffers() const;
+  void copyGrayscaleMsbBuffers() const;
+  void displayGrayBuffer() const;
+  void storeBwBuffer();
+  void restoreBwBuffer();
+
+  // Low level functions
+  uint8_t* getFrameBuffer() const;
+  static size_t getBufferSize();
+  void grayscaleRevert() const;
+};

lib/JpegToBmpConverter/JpegToBmpConverter.cpp

@@ -0,0 +1,258 @@
+#include "JpegToBmpConverter.h"
+
+#include <picojpeg.h>
+
+#include <cstdio>
+#include <cstring>
+
+// Context structure for picojpeg callback
+struct JpegReadContext {
+  File& file;
+  uint8_t buffer[512];
+  size_t bufferPos;
+  size_t bufferFilled;
+};
+
+// Helper function: Convert 8-bit grayscale to 2-bit (0-3)
+uint8_t JpegToBmpConverter::grayscaleTo2Bit(const uint8_t grayscale) {
+  // Simple threshold mapping:
+  // 0-63 -> 0 (black)
+  // 64-127 -> 1 (dark gray)
+  // 128-191 -> 2 (light gray)
+  // 192-255 -> 3 (white)
+  return grayscale >> 6;
+}
+
+inline void write16(Print& out, const uint16_t value) {
+  // out.write(reinterpret_cast<const uint8_t *>(&value), 2);
+  out.write(value & 0xFF);
+  out.write((value >> 8) & 0xFF);
+}
+
+inline void write32(Print& out, const uint32_t value) {
+  // out.write(reinterpret_cast<const uint8_t *>(&value), 4);
+  out.write(value & 0xFF);
+  out.write((value >> 8) & 0xFF);
+  out.write((value >> 16) & 0xFF);
+  out.write((value >> 24) & 0xFF);
+}
+
+inline void write32Signed(Print& out, const int32_t value) {
+  // out.write(reinterpret_cast<const uint8_t *>(&value), 4);
+  out.write(value & 0xFF);
+  out.write((value >> 8) & 0xFF);
+  out.write((value >> 16) & 0xFF);
+  out.write((value >> 24) & 0xFF);
+}
+
+// Helper function: Write BMP header with 2-bit color depth
+void JpegToBmpConverter::writeBmpHeader(Print& bmpOut, const int width, const int height) {
+  // Calculate row padding (each row must be multiple of 4 bytes)
+  const int bytesPerRow = (width * 2 + 31) / 32 * 4;  // 2 bits per pixel, round up
+  const int imageSize = bytesPerRow * height;
+  const uint32_t fileSize = 70 + imageSize;  // 14 (file header) + 40 (DIB header) + 16 (palette) + image
+
+  // BMP File Header (14 bytes)
+  bmpOut.write('B');
+  bmpOut.write('M');
+  write32(bmpOut, fileSize);  // File size
+  write32(bmpOut, 0);         // Reserved
+  write32(bmpOut, 70);        // Offset to pixel data
+
+  // DIB Header (BITMAPINFOHEADER - 40 bytes)
+  write32(bmpOut, 40);
+  write32Signed(bmpOut, width);
+  write32Signed(bmpOut, -height);  // Negative height = top-down bitmap
+  write16(bmpOut, 1);              // Color planes
+  write16(bmpOut, 2);              // Bits per pixel (2 bits)
+  write32(bmpOut, 0);              // BI_RGB (no compression)
+  write32(bmpOut, imageSize);
+  write32(bmpOut, 2835);  // xPixelsPerMeter (72 DPI)
+  write32(bmpOut, 2835);  // yPixelsPerMeter (72 DPI)
+  write32(bmpOut, 4);     // colorsUsed
+  write32(bmpOut, 4);     // colorsImportant
+
+  // Color Palette (4 colors x 4 bytes = 16 bytes)
+  // Format: Blue, Green, Red, Reserved (BGRA)
+  uint8_t palette[16] = {
+      0x00, 0x00, 0x00, 0x00,  // Color 0: Black
+      0x55, 0x55, 0x55, 0x00,  // Color 1: Dark gray (85)
+      0xAA, 0xAA, 0xAA, 0x00,  // Color 2: Light gray (170)
+      0xFF, 0xFF, 0xFF, 0x00   // Color 3: White
+  };
+  for (const uint8_t i : palette) {
+    bmpOut.write(i);
+  }
+}
+
+// Callback function for picojpeg to read JPEG data
+unsigned char JpegToBmpConverter::jpegReadCallback(unsigned char* pBuf, const unsigned char buf_size,
+                                                   unsigned char* pBytes_actually_read, void* pCallback_data) {
+  auto* context = static_cast<JpegReadContext*>(pCallback_data);
+
+  if (!context || !context->file) {
+    return PJPG_STREAM_READ_ERROR;
+  }
+
+  // Check if we need to refill our context buffer
+  if (context->bufferPos >= context->bufferFilled) {
+    context->bufferFilled = context->file.read(context->buffer, sizeof(context->buffer));
+    context->bufferPos = 0;
+
+    if (context->bufferFilled == 0) {
+      // EOF or error
+      *pBytes_actually_read = 0;
+      return 0;  // Success (EOF is normal)
+    }
+  }
+
+  // Copy available bytes to picojpeg's buffer
+  const size_t available = context->bufferFilled - context->bufferPos;
+  const size_t toRead = available < buf_size ? available : buf_size;
+
+  memcpy(pBuf, context->buffer + context->bufferPos, toRead);
+  context->bufferPos += toRead;
+  *pBytes_actually_read = static_cast<unsigned char>(toRead);
+
+  return 0;  // Success
+}
+
+// Core function: Convert JPEG file to 2-bit BMP
+bool JpegToBmpConverter::jpegFileToBmpStream(File& jpegFile, Print& bmpOut) {
+  Serial.printf("[%lu] [JPG] Converting JPEG to BMP\n", millis());
+
+  // Setup context for picojpeg callback
+  JpegReadContext context = {.file = jpegFile, .bufferPos = 0, .bufferFilled = 0};
+
+  // Initialize picojpeg decoder
+  pjpeg_image_info_t imageInfo;
+  const unsigned char status = pjpeg_decode_init(&imageInfo, jpegReadCallback, &context, 0);
+  if (status != 0) {
+    Serial.printf("[%lu] [JPG] JPEG decode init failed with error code: %d\n", millis(), status);
+    return false;
+  }
+
+  Serial.printf("[%lu] [JPG] JPEG dimensions: %dx%d, components: %d, MCUs: %dx%d\n", millis(), imageInfo.m_width,
+                imageInfo.m_height, imageInfo.m_comps, imageInfo.m_MCUSPerRow, imageInfo.m_MCUSPerCol);
+
+  // Write BMP header
+  writeBmpHeader(bmpOut, imageInfo.m_width, imageInfo.m_height);
+
+  // Calculate row parameters
+  const int bytesPerRow = (imageInfo.m_width * 2 + 31) / 32 * 4;
+
+  // Allocate row buffer for packed 2-bit pixels
+  auto* rowBuffer = static_cast<uint8_t*>(malloc(bytesPerRow));
+  if (!rowBuffer) {
+    Serial.printf("[%lu] [JPG] Failed to allocate row buffer\n", millis());
+    return false;
+  }
+
+  // Allocate a buffer for one MCU row worth of grayscale pixels
+  // This is the minimal memory needed for streaming conversion
+  const int mcuPixelHeight = imageInfo.m_MCUHeight;
+  const int mcuRowPixels = imageInfo.m_width * mcuPixelHeight;
+  auto* mcuRowBuffer = static_cast<uint8_t*>(malloc(mcuRowPixels));
+  if (!mcuRowBuffer) {
+    Serial.printf("[%lu] [JPG] Failed to allocate MCU row buffer\n", millis());
+    free(rowBuffer);
+    return false;
+  }
+
+  // Process MCUs row-by-row and write to BMP as we go (top-down)
+  const int mcuPixelWidth = imageInfo.m_MCUWidth;
+
+  for (int mcuY = 0; mcuY < imageInfo.m_MCUSPerCol; mcuY++) {
+    // Clear the MCU row buffer
+    memset(mcuRowBuffer, 0, mcuRowPixels);
+
+    // Decode one row of MCUs
+    for (int mcuX = 0; mcuX < imageInfo.m_MCUSPerRow; mcuX++) {
+      const unsigned char mcuStatus = pjpeg_decode_mcu();
+      if (mcuStatus != 0) {
+        if (mcuStatus == PJPG_NO_MORE_BLOCKS) {
+          Serial.printf("[%lu] [JPG] Unexpected end of blocks at MCU (%d, %d)\n", millis(), mcuX, mcuY);
+        } else {
+          Serial.printf("[%lu] [JPG] JPEG decode MCU failed at (%d, %d) with error code: %d\n", millis(), mcuX, mcuY,
+                        mcuStatus);
+        }
+        free(mcuRowBuffer);
+        free(rowBuffer);
+        return false;
+      }
+
+      // Process MCU block into MCU row buffer
+      // MCUs are composed of 8x8 blocks. For 16x16 MCUs, there are four 8x8 blocks:
+      // Block layout for 16x16 MCU:  [0, 64]  (top row of blocks)
+      //                              [128, 192] (bottom row of blocks)
+      for (int blockY = 0; blockY < mcuPixelHeight; blockY++) {
+        for (int blockX = 0; blockX < mcuPixelWidth; blockX++) {
+          const int pixelX = mcuX * mcuPixelWidth + blockX;
+
+          // Skip pixels outside image width (can happen with MCU alignment)
+          if (pixelX >= imageInfo.m_width) {
+            continue;
+          }
+
+          // Calculate which 8x8 block and position within that block
+          const int block8x8Col = blockX / 8;  // 0 or 1 for 16-wide MCU
+          const int block8x8Row = blockY / 8;  // 0 or 1 for 16-tall MCU
+          const int pixelInBlockX = blockX % 8;
+          const int pixelInBlockY = blockY % 8;
+
+          // Calculate byte offset: each 8x8 block is 64 bytes
+          // Blocks are arranged: [0, 64], [128, 192]
+          const int blockOffset = (block8x8Row * (mcuPixelWidth / 8) + block8x8Col) * 64;
+          const int mcuIndex = blockOffset + pixelInBlockY * 8 + pixelInBlockX;
+
+          // Get grayscale value
+          uint8_t gray;
+          if (imageInfo.m_comps == 1) {
+            // Grayscale image
+            gray = imageInfo.m_pMCUBufR[mcuIndex];
+          } else {
+            // RGB image - convert to grayscale
+            const uint8_t r = imageInfo.m_pMCUBufR[mcuIndex];
+            const uint8_t g = imageInfo.m_pMCUBufG[mcuIndex];
+            const uint8_t b = imageInfo.m_pMCUBufB[mcuIndex];
+            // Luminance formula: Y = 0.299*R + 0.587*G + 0.114*B
+            // Using integer approximation: (30*R + 59*G + 11*B) / 100
+            gray = (r * 30 + g * 59 + b * 11) / 100;
+          }
+
+          // Store grayscale value in MCU row buffer
+          mcuRowBuffer[blockY * imageInfo.m_width + pixelX] = gray;
+        }
+      }
+    }
+
+    // Write all pixel rows from this MCU row to BMP file
+    const int startRow = mcuY * mcuPixelHeight;
+    const int endRow = (mcuY + 1) * mcuPixelHeight;
+
+    for (int y = startRow; y < endRow && y < imageInfo.m_height; y++) {
+      memset(rowBuffer, 0, bytesPerRow);
+
+      // Pack 4 pixels per byte (2 bits each)
+      for (int x = 0; x < imageInfo.m_width; x++) {
+        const int bufferY = y - startRow;
+        const uint8_t gray = mcuRowBuffer[bufferY * imageInfo.m_width + x];
+        const uint8_t twoBit = grayscaleTo2Bit(gray);
+
+        const int byteIndex = (x * 2) / 8;
+        const int bitOffset = 6 - ((x * 2) % 8);  // 6, 4, 2, 0
+        rowBuffer[byteIndex] |= (twoBit << bitOffset);
+      }
+
+      // Write row with padding
+      bmpOut.write(rowBuffer, bytesPerRow);
+    }
+  }
+
+  // Clean up
+  free(mcuRowBuffer);
+  free(rowBuffer);
+
+  Serial.printf("[%lu] [JPG] Successfully converted JPEG to BMP\n", millis());
+  return true;
+}

lib/JpegToBmpConverter/JpegToBmpConverter.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#include <FS.h>
+
+class ZipFile;
+
+class JpegToBmpConverter {
+  static void writeBmpHeader(Print& bmpOut, int width, int height);
+  static uint8_t grayscaleTo2Bit(uint8_t grayscale);
+  static unsigned char jpegReadCallback(unsigned char* pBuf, unsigned char buf_size,
+                                        unsigned char* pBytes_actually_read, void* pCallback_data);
+
+ public:
+  static bool jpegFileToBmpStream(File& jpegFile, Print& bmpOut);
+};

lib/Serialization/Serialization.h

@@ -1,4 +1,6 @@
 #pragma once
+#include <FS.h>
+
 #include <iostream>
 
 namespace serialization {
@@ -7,21 +9,44 @@ static void writePod(std::ostream& os, const T& value) {
   os.write(reinterpret_cast<const char*>(&value), sizeof(T));
 }
 
+template <typename T>
+static void writePod(File& file, const T& value) {
+  file.write(reinterpret_cast<const uint8_t*>(&value), sizeof(T));
+}
+
 template <typename T>
 static void readPod(std::istream& is, T& value) {
   is.read(reinterpret_cast<char*>(&value), sizeof(T));
 }
 
+template <typename T>
+static void readPod(File& file, T& value) {
+  file.read(reinterpret_cast<uint8_t*>(&value), sizeof(T));
+}
+
 static void writeString(std::ostream& os, const std::string& s) {
   const uint32_t len = s.size();
   writePod(os, len);
   os.write(s.data(), len);
 }
 
+static void writeString(File& file, const std::string& s) {
+  const uint32_t len = s.size();
+  writePod(file, len);
+  file.write(reinterpret_cast<const uint8_t*>(s.data()), len);
+}
+
 static void readString(std::istream& is, std::string& s) {
   uint32_t len;
   readPod(is, len);
   s.resize(len);
   is.read(&s[0], len);
 }
+
+static void readString(File& file, std::string& s) {
+  uint32_t len;
+  readPod(file, len);
+  s.resize(len);
+  file.read(reinterpret_cast<uint8_t*>(&s[0]), len);
+}
 }  // namespace serialization

lib/ZipFile/ZipFile.cpp

@@ -3,138 +3,336 @@
 #include <HardwareSerial.h>
 #include <miniz.h>
 
-int libzInflateOneShot(const uint8_t* inputBuff, const size_t compSize, uint8_t* outputBuff, const size_t uncompSize) {
-  mz_stream pStream = {
-      .next_in = inputBuff,
-      .avail_in = compSize,
-      .total_in = 0,
-      .next_out = outputBuff,
-      .avail_out = uncompSize,
-      .total_out = 0,
-  };
+bool inflateOneShot(const uint8_t* inputBuf, const size_t deflatedSize, uint8_t* outputBuf, const size_t inflatedSize) {
+  // Setup inflator
+  const auto inflator = static_cast<tinfl_decompressor*>(malloc(sizeof(tinfl_decompressor)));
+  if (!inflator) {
+    Serial.printf("[%lu] [ZIP] Failed to allocate memory for inflator\n", millis());
+    return false;
+  }
+  memset(inflator, 0, sizeof(tinfl_decompressor));
+  tinfl_init(inflator);
 
-  int status = 0;
-  status = mz_inflateInit2(&pStream, -MZ_DEFAULT_WINDOW_BITS);
+  size_t inBytes = deflatedSize;
+  size_t outBytes = inflatedSize;
+  const tinfl_status status = tinfl_decompress(inflator, inputBuf, &inBytes, nullptr, outputBuf, &outBytes,
+                                               TINFL_FLAG_USING_NON_WRAPPING_OUTPUT_BUF);
+  free(inflator);
 
-  if (status != MZ_OK) {
-    Serial.printf("inflateInit2 failed: %d\n", status);
-    return status;
+  if (status != TINFL_STATUS_DONE) {
+    Serial.printf("[%lu] [ZIP] tinfl_decompress() failed with status %d\n", millis(), status);
+    return false;
   }
 
-  status = mz_inflate(&pStream, MZ_FINISH);
-  if (status != MZ_STREAM_END) {
-    Serial.printf("inflate failed: %d\n", status);
-    return status;
-  }
-
-  status = mz_inflateEnd(&pStream);
-  if (status != MZ_OK) {
-    Serial.printf("inflateEnd failed: %d\n", status);
-    return status;
-  }
-
-  return status;
+  return true;
 }
 
-char* ZipFile::readTextFileToMemory(const char* filename, size_t* size) const {
-  const auto data = readFileToMemory(filename, size, true);
-  return data ? reinterpret_cast<char*>(data) : nullptr;
-}
-
-uint8_t* ZipFile::readFileToMemory(const char* filename, size_t* size, bool trailingNullByte) const {
-  mz_zip_archive zipArchive = {};
-  const bool status = mz_zip_reader_init_file(&zipArchive, filePath.c_str(), 0);
+ZipFile::ZipFile(std::string filePath) : filePath(std::move(filePath)) {
+  const bool status = mz_zip_reader_init_file(&zipArchive, this->filePath.c_str(), 0);
 
   if (!status) {
-    Serial.printf("mz_zip_reader_init_file() failed!\nError %s\n", mz_zip_get_error_string(zipArchive.m_last_error));
-    return nullptr;
+    Serial.printf("[%lu] [ZIP] mz_zip_reader_init_file() failed for %s! Error: %s\n", millis(), this->filePath.c_str(),
+                  mz_zip_get_error_string(zipArchive.m_last_error));
   }
+}
 
+bool ZipFile::loadFileStat(const char* filename, mz_zip_archive_file_stat* fileStat) const {
   // find the file
   mz_uint32 fileIndex = 0;
   if (!mz_zip_reader_locate_file_v2(&zipArchive, filename, nullptr, 0, &fileIndex)) {
-    Serial.printf("Could not find file %s\n", filename);
-    mz_zip_reader_end(&zipArchive);
-    return nullptr;
+    Serial.printf("[%lu] [ZIP] Could not find file %s\n", millis(), filename);
+    return false;
   }
 
-  mz_zip_archive_file_stat fileStat;
-  if (!mz_zip_reader_file_stat(&zipArchive, fileIndex, &fileStat)) {
-    Serial.printf("mz_zip_reader_file_stat() failed!\nError %s\n", mz_zip_get_error_string(zipArchive.m_last_error));
-    mz_zip_reader_end(&zipArchive);
-    return nullptr;
+  if (!mz_zip_reader_file_stat(&zipArchive, fileIndex, fileStat)) {
+    Serial.printf("[%lu] [ZIP] mz_zip_reader_file_stat() failed! Error: %s\n", millis(),
+                  mz_zip_get_error_string(zipArchive.m_last_error));
+    return false;
   }
-  mz_zip_reader_end(&zipArchive);
+  return true;
+}
 
-  uint8_t pLocalHeader[30];
-  uint64_t fileOffset = fileStat.m_local_header_ofs;
+long ZipFile::getDataOffset(const mz_zip_archive_file_stat& fileStat) const {
+  constexpr auto localHeaderSize = 30;
 
-  // Reopen the file to manual read out delated bytes
-  FILE* file = fopen(filePath.c_str(), "rb");
+  uint8_t pLocalHeader[localHeaderSize];
+  const uint64_t fileOffset = fileStat.m_local_header_ofs;
+
+  FILE* file = fopen(filePath.c_str(), "r");
+  if (!file) {
+    Serial.printf("[%lu] [ZIP] Failed to open file for reading local header\n", millis());
+    return -1;
+  }
   fseek(file, fileOffset, SEEK_SET);
+  const size_t read = fread(pLocalHeader, 1, localHeaderSize, file);
+  fclose(file);
 
-  const size_t read = fread(pLocalHeader, 1, 30, file);
-  if (read != 30) {
-    Serial.println("Something went wrong reading the local header");
-    fclose(file);
-    return nullptr;
+  if (read != localHeaderSize) {
+    Serial.printf("[%lu] [ZIP] Something went wrong reading the local header\n", millis());
+    return -1;
   }
 
   if (pLocalHeader[0] + (pLocalHeader[1] << 8) + (pLocalHeader[2] << 16) + (pLocalHeader[3] << 24) !=
       0x04034b50 /* MZ_ZIP_LOCAL_DIR_HEADER_SIG */) {
-    Serial.println("Not a valid zip file header");
-    fclose(file);
-    return nullptr;
+    Serial.printf("[%lu] [ZIP] Not a valid zip file header\n", millis());
+    return -1;
   }
 
   const uint16_t filenameLength = pLocalHeader[26] + (pLocalHeader[27] << 8);
   const uint16_t extraOffset = pLocalHeader[28] + (pLocalHeader[29] << 8);
-  fileOffset += 30 + filenameLength + extraOffset;
+  return fileOffset + localHeaderSize + filenameLength + extraOffset;
+}
+
+bool ZipFile::getInflatedFileSize(const char* filename, size_t* size) const {
+  mz_zip_archive_file_stat fileStat;
+  if (!loadFileStat(filename, &fileStat)) {
+    return false;
+  }
+
+  *size = static_cast<size_t>(fileStat.m_uncomp_size);
+  return true;
+}
+
+uint8_t* ZipFile::readFileToMemory(const char* filename, size_t* size, const bool trailingNullByte) const {
+  mz_zip_archive_file_stat fileStat;
+  if (!loadFileStat(filename, &fileStat)) {
+    return nullptr;
+  }
+
+  const long fileOffset = getDataOffset(fileStat);
+  if (fileOffset < 0) {
+    return nullptr;
+  }
+
+  FILE* file = fopen(filePath.c_str(), "rb");
+  if (!file) {
+    Serial.printf("[%lu] [ZIP] Failed to open file for reading\n", millis());
+    return nullptr;
+  }
   fseek(file, fileOffset, SEEK_SET);
 
   const auto deflatedDataSize = static_cast<size_t>(fileStat.m_comp_size);
   const auto inflatedDataSize = static_cast<size_t>(fileStat.m_uncomp_size);
   const auto dataSize = trailingNullByte ? inflatedDataSize + 1 : inflatedDataSize;
   const auto data = static_cast<uint8_t*>(malloc(dataSize));
+  if (data == nullptr) {
+    Serial.printf("[%lu] [ZIP] Failed to allocate memory for output buffer (%zu bytes)\n", millis(), dataSize);
+    fclose(file);
+    return nullptr;
+  }
 
-  if (!fileStat.m_method) {
+  if (fileStat.m_method == MZ_NO_COMPRESSION) {
     // no deflation, just read content
     const size_t dataRead = fread(data, 1, inflatedDataSize, file);
     fclose(file);
+
     if (dataRead != inflatedDataSize) {
-      Serial.println("Failed to read data");
+      Serial.printf("[%lu] [ZIP] Failed to read data\n", millis());
+      free(data);
       return nullptr;
     }
-  } else {
+
+    // Continue out of block with data set
+  } else if (fileStat.m_method == MZ_DEFLATED) {
     // Read out deflated content from file
     const auto deflatedData = static_cast<uint8_t*>(malloc(deflatedDataSize));
     if (deflatedData == nullptr) {
-      Serial.println("Failed to allocate memory for decompression buffer");
+      Serial.printf("[%lu] [ZIP] Failed to allocate memory for decompression buffer\n", millis());
       fclose(file);
       return nullptr;
     }
 
     const size_t dataRead = fread(deflatedData, 1, deflatedDataSize, file);
     fclose(file);
+
     if (dataRead != deflatedDataSize) {
-      Serial.printf("Failed to read data, expected %d got %d\n", deflatedDataSize, dataRead);
+      Serial.printf("[%lu] [ZIP] Failed to read data, expected %d got %d\n", millis(), deflatedDataSize, dataRead);
       free(deflatedData);
+      free(data);
       return nullptr;
     }
 
-    const int result = libzInflateOneShot(deflatedData, deflatedDataSize, data, inflatedDataSize);
+    bool success = inflateOneShot(deflatedData, deflatedDataSize, data, inflatedDataSize);
     free(deflatedData);
-    if (result != MZ_OK) {
-      Serial.println("Failed to inflate file");
+
+    if (!success) {
+      Serial.printf("[%lu] [ZIP] Failed to inflate file\n", millis());
+      free(data);
       return nullptr;
     }
+
+    // Continue out of block with data set
+  } else {
+    Serial.printf("[%lu] [ZIP] Unsupported compression method\n", millis());
+    fclose(file);
+    return nullptr;
   }
 
-  if (trailingNullByte) {
-    data[inflatedDataSize] = '\0';
-  }
-  if (size) {
-    *size = inflatedDataSize;
-  }
+  if (trailingNullByte) data[inflatedDataSize] = '\0';
+  if (size) *size = inflatedDataSize;
   return data;
 }
+
+bool ZipFile::readFileToStream(const char* filename, Print& out, const size_t chunkSize) const {
+  mz_zip_archive_file_stat fileStat;
+  if (!loadFileStat(filename, &fileStat)) {
+    return false;
+  }
+
+  const long fileOffset = getDataOffset(fileStat);
+  if (fileOffset < 0) {
+    return false;
+  }
+
+  FILE* file = fopen(filePath.c_str(), "rb");
+  if (!file) {
+    Serial.printf("[%lu] [ZIP] Failed to open file for streaming\n", millis());
+    return false;
+  }
+  fseek(file, fileOffset, SEEK_SET);
+
+  const auto deflatedDataSize = static_cast<size_t>(fileStat.m_comp_size);
+  const auto inflatedDataSize = static_cast<size_t>(fileStat.m_uncomp_size);
+
+  if (fileStat.m_method == MZ_NO_COMPRESSION) {
+    // no deflation, just read content
+    const auto buffer = static_cast<uint8_t*>(malloc(chunkSize));
+    if (!buffer) {
+      Serial.printf("[%lu] [ZIP] Failed to allocate memory for buffer\n", millis());
+      fclose(file);
+      return false;
+    }
+
+    size_t remaining = inflatedDataSize;
+    while (remaining > 0) {
+      const size_t dataRead = fread(buffer, 1, remaining < chunkSize ? remaining : chunkSize, file);
+      if (dataRead == 0) {
+        Serial.printf("[%lu] [ZIP] Could not read more bytes\n", millis());
+        free(buffer);
+        fclose(file);
+        return false;
+      }
+
+      out.write(buffer, dataRead);
+      remaining -= dataRead;
+    }
+
+    fclose(file);
+    free(buffer);
+    return true;
+  }
+
+  if (fileStat.m_method == MZ_DEFLATED) {
+    // Setup inflator
+    const auto inflator = static_cast<tinfl_decompressor*>(malloc(sizeof(tinfl_decompressor)));
+    if (!inflator) {
+      Serial.printf("[%lu] [ZIP] Failed to allocate memory for inflator\n", millis());
+      fclose(file);
+      return false;
+    }
+    memset(inflator, 0, sizeof(tinfl_decompressor));
+    tinfl_init(inflator);
+
+    // Setup file read buffer
+    const auto fileReadBuffer = static_cast<uint8_t*>(malloc(chunkSize));
+    if (!fileReadBuffer) {
+      Serial.printf("[%lu] [ZIP] Failed to allocate memory for zip file read buffer\n", millis());
+      free(inflator);
+      fclose(file);
+      return false;
+    }
+
+    const auto outputBuffer = static_cast<uint8_t*>(malloc(TINFL_LZ_DICT_SIZE));
+    if (!outputBuffer) {
+      Serial.printf("[%lu] [ZIP] Failed to allocate memory for dictionary\n", millis());
+      free(inflator);
+      free(fileReadBuffer);
+      fclose(file);
+      return false;
+    }
+    memset(outputBuffer, 0, TINFL_LZ_DICT_SIZE);
+
+    size_t fileRemainingBytes = deflatedDataSize;
+    size_t processedOutputBytes = 0;
+    size_t fileReadBufferFilledBytes = 0;
+    size_t fileReadBufferCursor = 0;
+    size_t outputCursor = 0;  // Current offset in the circular dictionary
+
+    while (true) {
+      // Load more compressed bytes when needed
+      if (fileReadBufferCursor >= fileReadBufferFilledBytes) {
+        if (fileRemainingBytes == 0) {
+          // Should not be hit, but a safe protection
+          break;  // EOF
+        }
+
+        fileReadBufferFilledBytes =
+            fread(fileReadBuffer, 1, fileRemainingBytes < chunkSize ? fileRemainingBytes : chunkSize, file);
+        fileRemainingBytes -= fileReadBufferFilledBytes;
+        fileReadBufferCursor = 0;
+
+        if (fileReadBufferFilledBytes == 0) {
+          // Bad read
+          break;  // EOF
+        }
+      }
+
+      // Available bytes in fileReadBuffer to process
+      size_t inBytes = fileReadBufferFilledBytes - fileReadBufferCursor;
+      // Space remaining in outputBuffer
+      size_t outBytes = TINFL_LZ_DICT_SIZE - outputCursor;
+
+      const tinfl_status status = tinfl_decompress(inflator, fileReadBuffer + fileReadBufferCursor, &inBytes,
+                                                   outputBuffer, outputBuffer + outputCursor, &outBytes,
+                                                   fileRemainingBytes > 0 ? TINFL_FLAG_HAS_MORE_INPUT : 0);
+
+      // Update input position
+      fileReadBufferCursor += inBytes;
+
+      // Write output chunk
+      if (outBytes > 0) {
+        processedOutputBytes += outBytes;
+        if (out.write(outputBuffer + outputCursor, outBytes) != outBytes) {
+          Serial.printf("[%lu] [ZIP] Failed to write all output bytes to stream\n", millis());
+          fclose(file);
+          free(outputBuffer);
+          free(fileReadBuffer);
+          free(inflator);
+          return false;
+        }
+        // Update output position in buffer (with wraparound)
+        outputCursor = (outputCursor + outBytes) & (TINFL_LZ_DICT_SIZE - 1);
+      }
+
+      if (status < 0) {
+        Serial.printf("[%lu] [ZIP] tinfl_decompress() failed with status %d\n", millis(), status);
+        fclose(file);
+        free(outputBuffer);
+        free(fileReadBuffer);
+        free(inflator);
+        return false;
+      }
+
+      if (status == TINFL_STATUS_DONE) {
+        Serial.printf("[%lu] [ZIP] Decompressed %d bytes into %d bytes\n", millis(), deflatedDataSize,
+                      inflatedDataSize);
+        fclose(file);
+        free(inflator);
+        free(fileReadBuffer);
+        free(outputBuffer);
+        return true;
+      }
+    }
+
+    // If we get here, EOF reached without TINFL_STATUS_DONE
+    Serial.printf("[%lu] [ZIP] Unexpected EOF\n", millis());
+    fclose(file);
+    free(outputBuffer);
+    free(fileReadBuffer);
+    free(inflator);
+    return false;
+  }
+
+  Serial.printf("[%lu] [ZIP] Unsupported compression method\n", millis());
+  return false;
+}

lib/ZipFile/ZipFile.h

@@ -1,12 +1,20 @@
 #pragma once
+#include <Print.h>
+
 #include <string>
 
+#include "miniz.h"
+
 class ZipFile {
   std::string filePath;
+  mutable mz_zip_archive zipArchive = {};
+  bool loadFileStat(const char* filename, mz_zip_archive_file_stat* fileStat) const;
+  long getDataOffset(const mz_zip_archive_file_stat& fileStat) const;
 
  public:
-  explicit ZipFile(std::string filePath) : filePath(std::move(filePath)) {}
-  ~ZipFile() = default;
-  char* readTextFileToMemory(const char* filename, size_t* size = nullptr) const;
+  explicit ZipFile(std::string filePath);
+  ~ZipFile() { mz_zip_reader_end(&zipArchive); }
+  bool getInflatedFileSize(const char* filename, size_t* size) const;
   uint8_t* readFileToMemory(const char* filename, size_t* size = nullptr, bool trailingNullByte = false) const;
+  bool readFileToStream(const char* filename, Print& out, size_t chunkSize) const;
 };

lib/expat/.gitignore

@@ -0,0 +1,17 @@
+Makefile
+.libs
+*.lo
+Debug
+Debug-w
+Release
+Release-w
+expat.ncb
+expat.opt
+expat.plg
+Debug_static
+Debug-w_static
+Release_static
+Release-w_static
+expat_static.plg
+expatw.plg
+expatw_static.plg

lib/expat/Makefile.am

@@ -0,0 +1,87 @@
+#
+#                          __  __            _
+#                       ___\ \/ /_ __   __ _| |_
+#                      / _ \\  /| '_ \ / _` | __|
+#                     |  __//  \| |_) | (_| | |_
+#                      \___/_/\_\ .__/ \__,_|\__|
+#                               |_| XML parser
+#
+# Copyright (c) 2017-2024 Sebastian Pipping <sebastian@pipping.org>
+# Copyright (c) 2017      Tomasz Kłoczko <kloczek@fedoraproject.org>
+# Copyright (c) 2019      David Loffredo <loffredo@steptools.com>
+# Licensed under the MIT license:
+#
+# Permission is  hereby granted,  free of charge,  to any  person obtaining
+# a  copy  of  this  software   and  associated  documentation  files  (the
+# "Software"),  to  deal in  the  Software  without restriction,  including
+# without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+# distribute, sublicense, and/or sell copies of the Software, and to permit
+# persons  to whom  the Software  is  furnished to  do so,  subject to  the
+# following conditions:
+#
+# The above copyright  notice and this permission notice  shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+# EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+# NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+# DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+# USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+include_HEADERS = \
+    ../expat_config.h \
+    expat.h \
+    expat_external.h
+
+lib_LTLIBRARIES = libexpat.la
+if WITH_TESTS
+noinst_LTLIBRARIES = libtestpat.la
+endif
+
+libexpat_la_LDFLAGS = \
+    @AM_LDFLAGS@ \
+    @LIBM@ \
+    -no-undefined \
+    -version-info @LIBCURRENT@:@LIBREVISION@:@LIBAGE@
+
+libexpat_la_SOURCES = \
+    xmlparse.c \
+    xmltok.c \
+    xmlrole.c
+
+if WITH_TESTS
+libtestpat_la_CPPFLAGS = -DXML_TESTING
+
+libtestpat_la_SOURCES = $(libexpat_la_SOURCES)
+endif
+
+doc_DATA = \
+    ../AUTHORS \
+    ../Changes
+
+install-data-hook:
+	cd "$(DESTDIR)$(docdir)" && $(am__mv) Changes changelog
+
+uninstall-local:
+	$(RM) "$(DESTDIR)$(docdir)/changelog"
+
+EXTRA_DIST = \
+    ascii.h \
+    asciitab.h \
+    expat_external.h \
+    expat.h \
+    iasciitab.h \
+    internal.h \
+    latin1tab.h \
+    libexpat.def.cmake \
+    nametab.h \
+    siphash.h \
+    utf8tab.h \
+    winconfig.h \
+    xmlrole.h \
+    xmltok.h \
+    xmltok_impl.c \
+    xmltok_impl.h \
+    xmltok_ns.c

lib/expat/ascii.h

@@ -0,0 +1,123 @@
+/*
+                            __  __            _
+                         ___\ \/ /_ __   __ _| |_
+                        / _ \\  /| '_ \ / _` | __|
+                       |  __//  \| |_) | (_| | |_
+                        \___/_/\_\ .__/ \__,_|\__|
+                                 |_| XML parser
+
+   Copyright (c) 1999-2000 Thai Open Source Software Center Ltd
+   Copyright (c) 2000      Clark Cooper <coopercc@users.sourceforge.net>
+   Copyright (c) 2002      Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
+   Copyright (c) 2007      Karl Waclawek <karl@waclawek.net>
+   Copyright (c) 2017      Sebastian Pipping <sebastian@pipping.org>
+   Licensed under the MIT license:
+
+   Permission is  hereby granted,  free of charge,  to any  person obtaining
+   a  copy  of  this  software   and  associated  documentation  files  (the
+   "Software"),  to  deal in  the  Software  without restriction,  including
+   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+   distribute, sublicense, and/or sell copies of the Software, and to permit
+   persons  to whom  the Software  is  furnished to  do so,  subject to  the
+   following conditions:
+
+   The above copyright  notice and this permission notice  shall be included
+   in all copies or substantial portions of the Software.
+
+   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+#define ASCII_A 0x41
+#define ASCII_B 0x42
+#define ASCII_C 0x43
+#define ASCII_D 0x44
+#define ASCII_E 0x45
+#define ASCII_F 0x46
+#define ASCII_G 0x47
+#define ASCII_H 0x48
+#define ASCII_I 0x49
+#define ASCII_J 0x4A
+#define ASCII_K 0x4B
+#define ASCII_L 0x4C
+#define ASCII_M 0x4D
+#define ASCII_N 0x4E
+#define ASCII_O 0x4F
+#define ASCII_P 0x50
+#define ASCII_Q 0x51
+#define ASCII_R 0x52
+#define ASCII_S 0x53
+#define ASCII_T 0x54
+#define ASCII_U 0x55
+#define ASCII_V 0x56
+#define ASCII_W 0x57
+#define ASCII_X 0x58
+#define ASCII_Y 0x59
+#define ASCII_Z 0x5A
+
+#define ASCII_a 0x61
+#define ASCII_b 0x62
+#define ASCII_c 0x63
+#define ASCII_d 0x64
+#define ASCII_e 0x65
+#define ASCII_f 0x66
+#define ASCII_g 0x67
+#define ASCII_h 0x68
+#define ASCII_i 0x69
+#define ASCII_j 0x6A
+#define ASCII_k 0x6B
+#define ASCII_l 0x6C
+#define ASCII_m 0x6D
+#define ASCII_n 0x6E
+#define ASCII_o 0x6F
+#define ASCII_p 0x70
+#define ASCII_q 0x71
+#define ASCII_r 0x72
+#define ASCII_s 0x73
+#define ASCII_t 0x74
+#define ASCII_u 0x75
+#define ASCII_v 0x76
+#define ASCII_w 0x77
+#define ASCII_x 0x78
+#define ASCII_y 0x79
+#define ASCII_z 0x7A
+
+#define ASCII_0 0x30
+#define ASCII_1 0x31
+#define ASCII_2 0x32
+#define ASCII_3 0x33
+#define ASCII_4 0x34
+#define ASCII_5 0x35
+#define ASCII_6 0x36
+#define ASCII_7 0x37
+#define ASCII_8 0x38
+#define ASCII_9 0x39
+
+#define ASCII_TAB 0x09
+#define ASCII_SPACE 0x20
+#define ASCII_EXCL 0x21
+#define ASCII_QUOT 0x22
+#define ASCII_AMP 0x26
+#define ASCII_APOS 0x27
+#define ASCII_MINUS 0x2D
+#define ASCII_PERIOD 0x2E
+#define ASCII_COLON 0x3A
+#define ASCII_SEMI 0x3B
+#define ASCII_LT 0x3C
+#define ASCII_EQUALS 0x3D
+#define ASCII_GT 0x3E
+#define ASCII_LSQB 0x5B
+#define ASCII_RSQB 0x5D
+#define ASCII_UNDERSCORE 0x5F
+#define ASCII_LPAREN 0x28
+#define ASCII_RPAREN 0x29
+#define ASCII_FF 0x0C
+#define ASCII_SLASH 0x2F
+#define ASCII_HASH 0x23
+#define ASCII_PIPE 0x7C
+#define ASCII_COMMA 0x2C

lib/expat/asciitab.h

@@ -0,0 +1,66 @@
+/*
+                            __  __            _
+                         ___\ \/ /_ __   __ _| |_
+                        / _ \\  /| '_ \ / _` | __|
+                       |  __//  \| |_) | (_| | |_
+                        \___/_/\_\ .__/ \__,_|\__|
+                                 |_| XML parser
+
+   Copyright (c) 1997-2000 Thai Open Source Software Center Ltd
+   Copyright (c) 2000      Clark Cooper <coopercc@users.sourceforge.net>
+   Copyright (c) 2002      Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
+   Copyright (c) 2017      Sebastian Pipping <sebastian@pipping.org>
+   Licensed under the MIT license:
+
+   Permission is  hereby granted,  free of charge,  to any  person obtaining
+   a  copy  of  this  software   and  associated  documentation  files  (the
+   "Software"),  to  deal in  the  Software  without restriction,  including
+   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+   distribute, sublicense, and/or sell copies of the Software, and to permit
+   persons  to whom  the Software  is  furnished to  do so,  subject to  the
+   following conditions:
+
+   The above copyright  notice and this permission notice  shall be included
+   in all copies or substantial portions of the Software.
+
+   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+/* 0x00 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x04 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x08 */ BT_NONXML, BT_S, BT_LF, BT_NONXML,
+    /* 0x0C */ BT_NONXML, BT_CR, BT_NONXML, BT_NONXML,
+    /* 0x10 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x14 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x18 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x1C */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x20 */ BT_S, BT_EXCL, BT_QUOT, BT_NUM,
+    /* 0x24 */ BT_OTHER, BT_PERCNT, BT_AMP, BT_APOS,
+    /* 0x28 */ BT_LPAR, BT_RPAR, BT_AST, BT_PLUS,
+    /* 0x2C */ BT_COMMA, BT_MINUS, BT_NAME, BT_SOL,
+    /* 0x30 */ BT_DIGIT, BT_DIGIT, BT_DIGIT, BT_DIGIT,
+    /* 0x34 */ BT_DIGIT, BT_DIGIT, BT_DIGIT, BT_DIGIT,
+    /* 0x38 */ BT_DIGIT, BT_DIGIT, BT_COLON, BT_SEMI,
+    /* 0x3C */ BT_LT, BT_EQUALS, BT_GT, BT_QUEST,
+    /* 0x40 */ BT_OTHER, BT_HEX, BT_HEX, BT_HEX,
+    /* 0x44 */ BT_HEX, BT_HEX, BT_HEX, BT_NMSTRT,
+    /* 0x48 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x4C */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x50 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x54 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x58 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_LSQB,
+    /* 0x5C */ BT_OTHER, BT_RSQB, BT_OTHER, BT_NMSTRT,
+    /* 0x60 */ BT_OTHER, BT_HEX, BT_HEX, BT_HEX,
+    /* 0x64 */ BT_HEX, BT_HEX, BT_HEX, BT_NMSTRT,
+    /* 0x68 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x6C */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x70 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x74 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x78 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_OTHER,
+    /* 0x7C */ BT_VERBAR, BT_OTHER, BT_OTHER, BT_OTHER,

lib/expat/expat_external.h

@@ -0,0 +1,163 @@
+/*
+                            __  __            _
+                         ___\ \/ /_ __   __ _| |_
+                        / _ \\  /| '_ \ / _` | __|
+                       |  __//  \| |_) | (_| | |_
+                        \___/_/\_\ .__/ \__,_|\__|
+                                 |_| XML parser
+
+   Copyright (c) 1997-2000 Thai Open Source Software Center Ltd
+   Copyright (c) 2000      Clark Cooper <coopercc@users.sourceforge.net>
+   Copyright (c) 2000-2004 Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
+   Copyright (c) 2001-2002 Greg Stein <gstein@users.sourceforge.net>
+   Copyright (c) 2002-2006 Karl Waclawek <karl@waclawek.net>
+   Copyright (c) 2016      Cristian Rodríguez <crrodriguez@opensuse.org>
+   Copyright (c) 2016-2019 Sebastian Pipping <sebastian@pipping.org>
+   Copyright (c) 2017      Rhodri James <rhodri@wildebeest.org.uk>
+   Copyright (c) 2018      Yury Gribov <tetra2005@gmail.com>
+   Licensed under the MIT license:
+
+   Permission is  hereby granted,  free of charge,  to any  person obtaining
+   a  copy  of  this  software   and  associated  documentation  files  (the
+   "Software"),  to  deal in  the  Software  without restriction,  including
+   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+   distribute, sublicense, and/or sell copies of the Software, and to permit
+   persons  to whom  the Software  is  furnished to  do so,  subject to  the
+   following conditions:
+
+   The above copyright  notice and this permission notice  shall be included
+   in all copies or substantial portions of the Software.
+
+   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+#ifndef Expat_External_INCLUDED
+#define Expat_External_INCLUDED 1
+
+/* External API definitions */
+
+/* Expat tries very hard to make the API boundary very specifically
+   defined.  There are two macros defined to control this boundary;
+   each of these can be defined before including this header to
+   achieve some different behavior, but doing so it not recommended or
+   tested frequently.
+
+   XMLCALL    - The calling convention to use for all calls across the
+                "library boundary."  This will default to cdecl, and
+                try really hard to tell the compiler that's what we
+                want.
+
+   XMLIMPORT  - Whatever magic is needed to note that a function is
+                to be imported from a dynamically loaded library
+                (.dll, .so, or .sl, depending on your platform).
+
+   The XMLCALL macro was added in Expat 1.95.7.  The only one which is
+   expected to be directly useful in client code is XMLCALL.
+
+   Note that on at least some Unix versions, the Expat library must be
+   compiled with the cdecl calling convention as the default since
+   system headers may assume the cdecl convention.
+*/
+#ifndef XMLCALL
+#if defined(_MSC_VER)
+#define XMLCALL __cdecl
+#elif defined(__GNUC__) && defined(__i386) && !defined(__INTEL_COMPILER)
+#define XMLCALL __attribute__((cdecl))
+#else
+/* For any platform which uses this definition and supports more than
+   one calling convention, we need to extend this definition to
+   declare the convention used on that platform, if it's possible to
+   do so.
+
+   If this is the case for your platform, please file a bug report
+   with information on how to identify your platform via the C
+   pre-processor and how to specify the same calling convention as the
+   platform's malloc() implementation.
+*/
+#define XMLCALL
+#endif
+#endif /* not defined XMLCALL */
+
+#if !defined(XML_STATIC) && !defined(XMLIMPORT)
+#ifndef XML_BUILDING_EXPAT
+/* using Expat from an application */
+
+#if defined(_MSC_VER) && !defined(__BEOS__) && !defined(__CYGWIN__)
+#define XMLIMPORT __declspec(dllimport)
+#endif
+
+#endif
+#endif /* not defined XML_STATIC */
+
+#ifndef XML_ENABLE_VISIBILITY
+#define XML_ENABLE_VISIBILITY 0
+#endif
+
+#if !defined(XMLIMPORT) && XML_ENABLE_VISIBILITY
+#define XMLIMPORT __attribute__((visibility("default")))
+#endif
+
+/* If we didn't define it above, define it away: */
+#ifndef XMLIMPORT
+#define XMLIMPORT
+#endif
+
+#if defined(__GNUC__) && (__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 96))
+#define XML_ATTR_MALLOC __attribute__((__malloc__))
+#else
+#define XML_ATTR_MALLOC
+#endif
+
+#if defined(__GNUC__) && ((__GNUC__ > 4) || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3))
+#define XML_ATTR_ALLOC_SIZE(x) __attribute__((__alloc_size__(x)))
+#else
+#define XML_ATTR_ALLOC_SIZE(x)
+#endif
+
+#define XMLPARSEAPI(type) XMLIMPORT type XMLCALL
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef XML_UNICODE_WCHAR_T
+#ifndef XML_UNICODE
+#define XML_UNICODE
+#endif
+#if defined(__SIZEOF_WCHAR_T__) && (__SIZEOF_WCHAR_T__ != 2)
+#error "sizeof(wchar_t) != 2; Need -fshort-wchar for both Expat and libc"
+#endif
+#endif
+
+#ifdef XML_UNICODE /* Information is UTF-16 encoded. */
+#ifdef XML_UNICODE_WCHAR_T
+typedef wchar_t XML_Char;
+typedef wchar_t XML_LChar;
+#else
+typedef unsigned short XML_Char;
+typedef char XML_LChar;
+#endif /* XML_UNICODE_WCHAR_T */
+#else  /* Information is UTF-8 encoded. */
+typedef char XML_Char;
+typedef char XML_LChar;
+#endif /* XML_UNICODE */
+
+#ifdef XML_LARGE_SIZE /* Use large integers for file/stream positions. */
+typedef long long XML_Index;
+typedef unsigned long long XML_Size;
+#else
+typedef long XML_Index;
+typedef unsigned long XML_Size;
+#endif /* XML_LARGE_SIZE */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* not Expat_External_INCLUDED */

lib/expat/iasciitab.h

@@ -0,0 +1,67 @@
+/*
+                            __  __            _
+                         ___\ \/ /_ __   __ _| |_
+                        / _ \\  /| '_ \ / _` | __|
+                       |  __//  \| |_) | (_| | |_
+                        \___/_/\_\ .__/ \__,_|\__|
+                                 |_| XML parser
+
+   Copyright (c) 1997-2000 Thai Open Source Software Center Ltd
+   Copyright (c) 2000      Clark Cooper <coopercc@users.sourceforge.net>
+   Copyright (c) 2002      Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
+   Copyright (c) 2017      Sebastian Pipping <sebastian@pipping.org>
+   Licensed under the MIT license:
+
+   Permission is  hereby granted,  free of charge,  to any  person obtaining
+   a  copy  of  this  software   and  associated  documentation  files  (the
+   "Software"),  to  deal in  the  Software  without restriction,  including
+   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+   distribute, sublicense, and/or sell copies of the Software, and to permit
+   persons  to whom  the Software  is  furnished to  do so,  subject to  the
+   following conditions:
+
+   The above copyright  notice and this permission notice  shall be included
+   in all copies or substantial portions of the Software.
+
+   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+/* Like asciitab.h, except that 0xD has code BT_S rather than BT_CR */
+/* 0x00 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x04 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x08 */ BT_NONXML, BT_S, BT_LF, BT_NONXML,
+    /* 0x0C */ BT_NONXML, BT_S, BT_NONXML, BT_NONXML,
+    /* 0x10 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x14 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x18 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x1C */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0x20 */ BT_S, BT_EXCL, BT_QUOT, BT_NUM,
+    /* 0x24 */ BT_OTHER, BT_PERCNT, BT_AMP, BT_APOS,
+    /* 0x28 */ BT_LPAR, BT_RPAR, BT_AST, BT_PLUS,
+    /* 0x2C */ BT_COMMA, BT_MINUS, BT_NAME, BT_SOL,
+    /* 0x30 */ BT_DIGIT, BT_DIGIT, BT_DIGIT, BT_DIGIT,
+    /* 0x34 */ BT_DIGIT, BT_DIGIT, BT_DIGIT, BT_DIGIT,
+    /* 0x38 */ BT_DIGIT, BT_DIGIT, BT_COLON, BT_SEMI,
+    /* 0x3C */ BT_LT, BT_EQUALS, BT_GT, BT_QUEST,
+    /* 0x40 */ BT_OTHER, BT_HEX, BT_HEX, BT_HEX,
+    /* 0x44 */ BT_HEX, BT_HEX, BT_HEX, BT_NMSTRT,
+    /* 0x48 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x4C */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x50 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x54 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x58 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_LSQB,
+    /* 0x5C */ BT_OTHER, BT_RSQB, BT_OTHER, BT_NMSTRT,
+    /* 0x60 */ BT_OTHER, BT_HEX, BT_HEX, BT_HEX,
+    /* 0x64 */ BT_HEX, BT_HEX, BT_HEX, BT_NMSTRT,
+    /* 0x68 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x6C */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x70 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x74 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0x78 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_OTHER,
+    /* 0x7C */ BT_VERBAR, BT_OTHER, BT_OTHER, BT_OTHER,

lib/expat/internal.h

@@ -0,0 +1,187 @@
+/* internal.h
+
+   Internal definitions used by Expat.  This is not needed to compile
+   client code.
+
+   The following calling convention macros are defined for frequently
+   called functions:
+
+   FASTCALL    - Used for those internal functions that have a simple
+                 body and a low number of arguments and local variables.
+
+   PTRCALL     - Used for functions called though function pointers.
+
+   PTRFASTCALL - Like PTRCALL, but for low number of arguments.
+
+   inline      - Used for selected internal functions for which inlining
+                 may improve performance on some platforms.
+
+   Note: Use of these macros is based on judgement, not hard rules,
+         and therefore subject to change.
+                            __  __            _
+                         ___\ \/ /_ __   __ _| |_
+                        / _ \\  /| '_ \ / _` | __|
+                       |  __//  \| |_) | (_| | |_
+                        \___/_/\_\ .__/ \__,_|\__|
+                                 |_| XML parser
+
+   Copyright (c) 2002-2003 Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
+   Copyright (c) 2002-2006 Karl Waclawek <karl@waclawek.net>
+   Copyright (c) 2003      Greg Stein <gstein@users.sourceforge.net>
+   Copyright (c) 2016-2025 Sebastian Pipping <sebastian@pipping.org>
+   Copyright (c) 2018      Yury Gribov <tetra2005@gmail.com>
+   Copyright (c) 2019      David Loffredo <loffredo@steptools.com>
+   Copyright (c) 2023-2024 Sony Corporation / Snild Dolkow <snild@sony.com>
+   Copyright (c) 2024      Taichi Haradaguchi <20001722@ymail.ne.jp>
+   Licensed under the MIT license:
+
+   Permission is  hereby granted,  free of charge,  to any  person obtaining
+   a  copy  of  this  software   and  associated  documentation  files  (the
+   "Software"),  to  deal in  the  Software  without restriction,  including
+   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+   distribute, sublicense, and/or sell copies of the Software, and to permit
+   persons  to whom  the Software  is  furnished to  do so,  subject to  the
+   following conditions:
+
+   The above copyright  notice and this permission notice  shall be included
+   in all copies or substantial portions of the Software.
+
+   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+#if defined(__GNUC__) && defined(__i386__) && !defined(__MINGW32__)
+/* We'll use this version by default only where we know it helps.
+
+   regparm() generates warnings on Solaris boxes.   See SF bug #692878.
+
+   Instability reported with egcs on a RedHat Linux 7.3.
+   Let's comment out:
+   #define FASTCALL __attribute__((stdcall, regparm(3)))
+   and let's try this:
+*/
+#define FASTCALL __attribute__((regparm(3)))
+#define PTRFASTCALL __attribute__((regparm(3)))
+#endif
+
+/* Using __fastcall seems to have an unexpected negative effect under
+   MS VC++, especially for function pointers, so we won't use it for
+   now on that platform. It may be reconsidered for a future release
+   if it can be made more effective.
+   Likely reason: __fastcall on Windows is like stdcall, therefore
+   the compiler cannot perform stack optimizations for call clusters.
+*/
+
+/* Make sure all of these are defined if they aren't already. */
+
+#ifndef FASTCALL
+#define FASTCALL
+#endif
+
+#ifndef PTRCALL
+#define PTRCALL
+#endif
+
+#ifndef PTRFASTCALL
+#define PTRFASTCALL
+#endif
+
+#ifndef XML_MIN_SIZE
+#if !defined(__cplusplus) && !defined(inline)
+#ifdef __GNUC__
+#define inline __inline
+#endif /* __GNUC__ */
+#endif
+#endif /* XML_MIN_SIZE */
+
+#ifdef __cplusplus
+#define inline inline
+#else
+#ifndef inline
+#define inline
+#endif
+#endif
+
+#include <limits.h>  // ULONG_MAX
+#include <stddef.h>  // size_t
+
+#if defined(_WIN32) && (!defined(__USE_MINGW_ANSI_STDIO) || (1 - __USE_MINGW_ANSI_STDIO - 1 == 0))
+#define EXPAT_FMT_ULL(midpart) "%" midpart "I64u"
+#if defined(_WIN64)  // Note: modifiers "td" and "zu" do not work for MinGW
+#define EXPAT_FMT_PTRDIFF_T(midpart) "%" midpart "I64d"
+#define EXPAT_FMT_SIZE_T(midpart) "%" midpart "I64u"
+#else
+#define EXPAT_FMT_PTRDIFF_T(midpart) "%" midpart "d"
+#define EXPAT_FMT_SIZE_T(midpart) "%" midpart "u"
+#endif
+#else
+#define EXPAT_FMT_ULL(midpart) "%" midpart "llu"
+#if !defined(ULONG_MAX)
+#error Compiler did not define ULONG_MAX for us
+#elif ULONG_MAX == 18446744073709551615u  // 2^64-1
+#define EXPAT_FMT_PTRDIFF_T(midpart) "%" midpart "ld"
+#define EXPAT_FMT_SIZE_T(midpart) "%" midpart "lu"
+#elif defined(EMSCRIPTEN)  // 32bit mode Emscripten
+#define EXPAT_FMT_PTRDIFF_T(midpart) "%" midpart "ld"
+#define EXPAT_FMT_SIZE_T(midpart) "%" midpart "zu"
+#else
+#define EXPAT_FMT_PTRDIFF_T(midpart) "%" midpart "d"
+#define EXPAT_FMT_SIZE_T(midpart) "%" midpart "u"
+#endif
+#endif
+
+#ifndef UNUSED_P
+#define UNUSED_P(p) (void)p
+#endif
+
+/* NOTE BEGIN If you ever patch these defaults to greater values
+              for non-attack XML payload in your environment,
+              please file a bug report with libexpat.  Thank you!
+*/
+#define EXPAT_BILLION_LAUGHS_ATTACK_PROTECTION_MAXIMUM_AMPLIFICATION_DEFAULT 100.0f
+#define EXPAT_BILLION_LAUGHS_ATTACK_PROTECTION_ACTIVATION_THRESHOLD_DEFAULT 8388608  // 8 MiB, 2^23
+
+#define EXPAT_ALLOC_TRACKER_MAXIMUM_AMPLIFICATION_DEFAULT 100.0f
+#define EXPAT_ALLOC_TRACKER_ACTIVATION_THRESHOLD_DEFAULT 67108864  // 64 MiB, 2^26
+
+// NOTE: If function expat_alloc was user facing, EXPAT_MALLOC_ALIGNMENT would
+//       have to take sizeof(long double) into account
+#define EXPAT_MALLOC_ALIGNMENT sizeof(long long)  // largest parser (sub)member
+#define EXPAT_MALLOC_PADDING ((EXPAT_MALLOC_ALIGNMENT) - sizeof(size_t))
+
+/* NOTE END */
+
+#include "expat.h"  // so we can use type XML_Parser below
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+void _INTERNAL_trim_to_complete_utf8_characters(const char* from, const char** fromLimRef);
+
+#if defined(XML_GE) && XML_GE == 1
+unsigned long long testingAccountingGetCountBytesDirect(XML_Parser parser);
+unsigned long long testingAccountingGetCountBytesIndirect(XML_Parser parser);
+const char* unsignedCharToPrintable(unsigned char c);
+#endif
+
+extern
+#if !defined(XML_TESTING)
+    const
+#endif
+    XML_Bool g_reparseDeferralEnabledDefault;  // written ONLY in runtests.c
+#if defined(XML_TESTING)
+void* expat_malloc(XML_Parser parser, size_t size, int sourceLine);
+void expat_free(XML_Parser parser, void* ptr, int sourceLine);
+void* expat_realloc(XML_Parser parser, void* ptr, size_t size, int sourceLine);
+extern unsigned int g_bytesScanned;  // used for testing only
+#endif
+
+#ifdef __cplusplus
+}
+#endif

lib/expat/latin1tab.h

@@ -0,0 +1,66 @@
+/*
+                            __  __            _
+                         ___\ \/ /_ __   __ _| |_
+                        / _ \\  /| '_ \ / _` | __|
+                       |  __//  \| |_) | (_| | |_
+                        \___/_/\_\ .__/ \__,_|\__|
+                                 |_| XML parser
+
+   Copyright (c) 1997-2000 Thai Open Source Software Center Ltd
+   Copyright (c) 2000      Clark Cooper <coopercc@users.sourceforge.net>
+   Copyright (c) 2002      Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
+   Copyright (c) 2017      Sebastian Pipping <sebastian@pipping.org>
+   Licensed under the MIT license:
+
+   Permission is  hereby granted,  free of charge,  to any  person obtaining
+   a  copy  of  this  software   and  associated  documentation  files  (the
+   "Software"),  to  deal in  the  Software  without restriction,  including
+   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+   distribute, sublicense, and/or sell copies of the Software, and to permit
+   persons  to whom  the Software  is  furnished to  do so,  subject to  the
+   following conditions:
+
+   The above copyright  notice and this permission notice  shall be included
+   in all copies or substantial portions of the Software.
+
+   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+/* 0x80 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0x84 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0x88 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0x8C */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0x90 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0x94 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0x98 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0x9C */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0xA0 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0xA4 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0xA8 */ BT_OTHER, BT_OTHER, BT_NMSTRT, BT_OTHER,
+    /* 0xAC */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0xB0 */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0xB4 */ BT_OTHER, BT_NMSTRT, BT_OTHER, BT_NAME,
+    /* 0xB8 */ BT_OTHER, BT_OTHER, BT_NMSTRT, BT_OTHER,
+    /* 0xBC */ BT_OTHER, BT_OTHER, BT_OTHER, BT_OTHER,
+    /* 0xC0 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xC4 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xC8 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xCC */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xD0 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xD4 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_OTHER,
+    /* 0xD8 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xDC */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xE0 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xE4 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xE8 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xEC */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xF0 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xF4 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_OTHER,
+    /* 0xF8 */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,
+    /* 0xFC */ BT_NMSTRT, BT_NMSTRT, BT_NMSTRT, BT_NMSTRT,

lib/expat/libexpat.def.cmake

@@ -0,0 +1,84 @@
+; DEF file for MS VC++
+
+EXPORTS
+  XML_DefaultCurrent @1
+  XML_ErrorString @2
+  XML_ExpatVersion @3
+  XML_ExpatVersionInfo @4
+  XML_ExternalEntityParserCreate @5
+  XML_GetBase @6
+  XML_GetBuffer @7
+  XML_GetCurrentByteCount @8
+  XML_GetCurrentByteIndex @9
+  XML_GetCurrentColumnNumber @10
+  XML_GetCurrentLineNumber @11
+  XML_GetErrorCode @12
+  XML_GetIdAttributeIndex @13
+  XML_GetInputContext @14
+  XML_GetSpecifiedAttributeCount @15
+  XML_Parse @16
+  XML_ParseBuffer @17
+  XML_ParserCreate @18
+  XML_ParserCreateNS @19
+  XML_ParserCreate_MM @20
+  XML_ParserFree @21
+  XML_SetAttlistDeclHandler @22
+  XML_SetBase @23
+  XML_SetCdataSectionHandler @24
+  XML_SetCharacterDataHandler @25
+  XML_SetCommentHandler @26
+  XML_SetDefaultHandler @27
+  XML_SetDefaultHandlerExpand @28
+  XML_SetDoctypeDeclHandler @29
+  XML_SetElementDeclHandler @30
+  XML_SetElementHandler @31
+  XML_SetEncoding @32
+  XML_SetEndCdataSectionHandler @33
+  XML_SetEndDoctypeDeclHandler @34
+  XML_SetEndElementHandler @35
+  XML_SetEndNamespaceDeclHandler @36
+  XML_SetEntityDeclHandler @37
+  XML_SetExternalEntityRefHandler @38
+  XML_SetExternalEntityRefHandlerArg @39
+  XML_SetNamespaceDeclHandler @40
+  XML_SetNotStandaloneHandler @41
+  XML_SetNotationDeclHandler @42
+  XML_SetParamEntityParsing @43
+  XML_SetProcessingInstructionHandler @44
+  XML_SetReturnNSTriplet @45
+  XML_SetStartCdataSectionHandler @46
+  XML_SetStartDoctypeDeclHandler @47
+  XML_SetStartElementHandler @48
+  XML_SetStartNamespaceDeclHandler @49
+  XML_SetUnknownEncodingHandler @50
+  XML_SetUnparsedEntityDeclHandler @51
+  XML_SetUserData @52
+  XML_SetXmlDeclHandler @53
+  XML_UseParserAsHandlerArg @54
+; added with version 1.95.3
+  XML_ParserReset @55
+  XML_SetSkippedEntityHandler @56
+; added with version 1.95.5
+  XML_GetFeatureList @57
+  XML_UseForeignDTD @58
+; added with version 1.95.6
+  XML_FreeContentModel @59
+  XML_MemMalloc @60
+  XML_MemRealloc @61
+  XML_MemFree @62
+; added with version 1.95.8
+  XML_StopParser @63
+  XML_ResumeParser @64
+  XML_GetParsingStatus @65
+; added with version 2.1.1
+@_EXPAT_COMMENT_ATTR_INFO@ XML_GetAttributeInfo @66
+  XML_SetHashSalt @67
+; internal @68 removed with version 2.3.1
+; added with version 2.4.0
+@_EXPAT_COMMENT_DTD_OR_GE@ XML_SetBillionLaughsAttackProtectionActivationThreshold @69
+@_EXPAT_COMMENT_DTD_OR_GE@ XML_SetBillionLaughsAttackProtectionMaximumAmplification @70
+; added with version 2.6.0
+  XML_SetReparseDeferralEnabled @71
+; added with version 2.7.2
+@_EXPAT_COMMENT_DTD_OR_GE@ XML_SetAllocTrackerMaximumAmplification @72
+@_EXPAT_COMMENT_DTD_OR_GE@ XML_SetAllocTrackerActivationThreshold @73

lib/expat/library.json

@@ -0,0 +1,11 @@
+{
+  "name": "expat",
+  "version": "2.7.3",
+  "build": {
+    "srcFilter": [
+      "+<xmlparse.c>",
+      "+<xmlrole.c>",
+      "+<xmltok.c>"
+    ]
+  }
+}

lib/expat/nametab.h

@@ -0,0 +1,102 @@
+/*
+                            __  __            _
+                         ___\ \/ /_ __   __ _| |_
+                        / _ \\  /| '_ \ / _` | __|
+                       |  __//  \| |_) | (_| | |_
+                        \___/_/\_\ .__/ \__,_|\__|
+                                 |_| XML parser
+
+   Copyright (c) 2000 Clark Cooper <coopercc@users.sourceforge.net>
+   Copyright (c) 2017 Sebastian Pipping <sebastian@pipping.org>
+   Licensed under the MIT license:
+
+   Permission is  hereby granted,  free of charge,  to any  person obtaining
+   a  copy  of  this  software   and  associated  documentation  files  (the
+   "Software"),  to  deal in  the  Software  without restriction,  including
+   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+   distribute, sublicense, and/or sell copies of the Software, and to permit
+   persons  to whom  the Software  is  furnished to  do so,  subject to  the
+   following conditions:
+
+   The above copyright  notice and this permission notice  shall be included
+   in all copies or substantial portions of the Software.
+
+   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+static const unsigned namingBitmap[] = {
+    0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0xFFFFFFFF,
+    0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0x00000000, 0x04000000,
+    0x87FFFFFE, 0x07FFFFFE, 0x00000000, 0x00000000, 0xFF7FFFFF, 0xFF7FFFFF, 0xFFFFFFFF, 0x7FF3FFFF, 0xFFFFFDFE,
+    0x7FFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFE00F, 0xFC31FFFF, 0x00FFFFFF, 0x00000000, 0xFFFF0000, 0xFFFFFFFF,
+    0xFFFFFFFF, 0xF80001FF, 0x00000003, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0xFFFFD740,
+    0xFFFFFFFB, 0x547F7FFF, 0x000FFFFD, 0xFFFFDFFE, 0xFFFFFFFF, 0xDFFEFFFF, 0xFFFFFFFF, 0xFFFF0003, 0xFFFFFFFF,
+    0xFFFF199F, 0x033FCFFF, 0x00000000, 0xFFFE0000, 0x027FFFFF, 0xFFFFFFFE, 0x0000007F, 0x00000000, 0xFFFF0000,
+    0x000707FF, 0x00000000, 0x07FFFFFE, 0x000007FE, 0xFFFE0000, 0xFFFFFFFF, 0x7CFFFFFF, 0x002F7FFF, 0x00000060,
+    0xFFFFFFE0, 0x23FFFFFF, 0xFF000000, 0x00000003, 0xFFF99FE0, 0x03C5FDFF, 0xB0000000, 0x00030003, 0xFFF987E0,
+    0x036DFDFF, 0x5E000000, 0x001C0000, 0xFFFBAFE0, 0x23EDFDFF, 0x00000000, 0x00000001, 0xFFF99FE0, 0x23CDFDFF,
+    0xB0000000, 0x00000003, 0xD63DC7E0, 0x03BFC718, 0x00000000, 0x00000000, 0xFFFDDFE0, 0x03EFFDFF, 0x00000000,
+    0x00000003, 0xFFFDDFE0, 0x03EFFDFF, 0x40000000, 0x00000003, 0xFFFDDFE0, 0x03FFFDFF, 0x00000000, 0x00000003,
+    0x00000000, 0x00000000, 0x00000000, 0x00000000, 0xFFFFFFFE, 0x000D7FFF, 0x0000003F, 0x00000000, 0xFEF02596,
+    0x200D6CAE, 0x0000001F, 0x00000000, 0x00000000, 0x00000000, 0xFFFFFEFF, 0x000003FF, 0x00000000, 0x00000000,
+    0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x00000000, 0xFFFFFFFF, 0xFFFF003F,
+    0x007FFFFF, 0x0007DAED, 0x50000000, 0x82315001, 0x002C62AB, 0x40000000, 0xF580C900, 0x00000007, 0x02010800,
+    0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0x0FFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0x03FFFFFF, 0x3F3FFFFF,
+    0xFFFFFFFF, 0xAAFF3F3F, 0x3FFFFFFF, 0xFFFFFFFF, 0x5FDFFFFF, 0x0FCF1FDC, 0x1FDC1FFF, 0x00000000, 0x00004C40,
+    0x00000000, 0x00000000, 0x00000007, 0x00000000, 0x00000000, 0x00000000, 0x00000080, 0x000003FE, 0xFFFFFFFE,
+    0xFFFFFFFF, 0x001FFFFF, 0xFFFFFFFE, 0xFFFFFFFF, 0x07FFFFFF, 0xFFFFFFE0, 0x00001FFF, 0x00000000, 0x00000000,
+    0x00000000, 0x00000000, 0x00000000, 0x00000000, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF,
+    0x0000003F, 0x00000000, 0x00000000, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0xFFFFFFFF, 0x0000000F,
+    0x00000000, 0x00000000, 0x00000000, 0x07FF6000, 0x87FFFFFE, 0x07FFFFFE, 0x00000000, 0x00800000, 0xFF7FFFFF,
+    0xFF7FFFFF, 0x00FFFFFF, 0x00000000, 0xFFFF0000, 0xFFFFFFFF, 0xFFFFFFFF, 0xF80001FF, 0x00030003, 0x00000000,
+    0xFFFFFFFF, 0xFFFFFFFF, 0x0000003F, 0x00000003, 0xFFFFD7C0, 0xFFFFFFFB, 0x547F7FFF, 0x000FFFFD, 0xFFFFDFFE,
+    0xFFFFFFFF, 0xDFFEFFFF, 0xFFFFFFFF, 0xFFFF007B, 0xFFFFFFFF, 0xFFFF199F, 0x033FCFFF, 0x00000000, 0xFFFE0000,
+    0x027FFFFF, 0xFFFFFFFE, 0xFFFE007F, 0xBBFFFFFB, 0xFFFF0016, 0x000707FF, 0x00000000, 0x07FFFFFE, 0x0007FFFF,
+    0xFFFF03FF, 0xFFFFFFFF, 0x7CFFFFFF, 0xFFEF7FFF, 0x03FF3DFF, 0xFFFFFFEE, 0xF3FFFFFF, 0xFF1E3FFF, 0x0000FFCF,
+    0xFFF99FEE, 0xD3C5FDFF, 0xB080399F, 0x0003FFCF, 0xFFF987E4, 0xD36DFDFF, 0x5E003987, 0x001FFFC0, 0xFFFBAFEE,
+    0xF3EDFDFF, 0x00003BBF, 0x0000FFC1, 0xFFF99FEE, 0xF3CDFDFF, 0xB0C0398F, 0x0000FFC3, 0xD63DC7EC, 0xC3BFC718,
+    0x00803DC7, 0x0000FF80, 0xFFFDDFEE, 0xC3EFFDFF, 0x00603DDF, 0x0000FFC3, 0xFFFDDFEC, 0xC3EFFDFF, 0x40603DDF,
+    0x0000FFC3, 0xFFFDDFEC, 0xC3FFFDFF, 0x00803DCF, 0x0000FFC3, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
+    0xFFFFFFFE, 0x07FF7FFF, 0x03FF7FFF, 0x00000000, 0xFEF02596, 0x3BFF6CAE, 0x03FF3F5F, 0x00000000, 0x03000000,
+    0xC2A003FF, 0xFFFFFEFF, 0xFFFE03FF, 0xFEBF0FDF, 0x02FE3FFF, 0x00000000, 0x00000000, 0x00000000, 0x00000000,
+    0x00000000, 0x00000000, 0x00000000, 0x00000000, 0x1FFF0000, 0x00000002, 0x000000A0, 0x003EFFFE, 0xFFFFFFFE,
+    0xFFFFFFFF, 0x661FFFFF, 0xFFFFFFFE, 0xFFFFFFFF, 0x77FFFFFF,
+};
+static const unsigned char nmstrtPages[] = {
+    0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x00, 0x00, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F, 0x10, 0x11, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x12, 0x13, 0x00, 0x14, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x15, 0x16, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x17, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x18, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+};
+static const unsigned char namePages[] = {
+    0x19, 0x03, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x00, 0x00, 0x1F, 0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x10, 0x11, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x12, 0x13, 0x26, 0x14, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x27, 0x16, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x17, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01,
+    0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x18, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+};

lib/expat/siphash.h

@@ -0,0 +1,379 @@
+/* ==========================================================================
+ * siphash.h - SipHash-2-4 in a single header file
+ * --------------------------------------------------------------------------
+ * Derived by William Ahern from the reference implementation[1] published[2]
+ * by Jean-Philippe Aumasson and Daniel J. Berstein.
+ * Minimal changes by Sebastian Pipping and Victor Stinner on top, see below.
+ * Licensed under the CC0 Public Domain Dedication license.
+ *
+ * 1. https://www.131002.net/siphash/siphash24.c
+ * 2. https://www.131002.net/siphash/
+ * --------------------------------------------------------------------------
+ * HISTORY:
+ *
+ * 2020-10-03  (Sebastian Pipping)
+ *   - Drop support for Visual Studio 9.0/2008 and earlier
+ *
+ * 2019-08-03  (Sebastian Pipping)
+ *   - Mark part of sip24_valid as to be excluded from clang-format
+ *   - Re-format code using clang-format 9
+ *
+ * 2018-07-08  (Anton Maklakov)
+ *   - Add "fall through" markers for GCC's -Wimplicit-fallthrough
+ *
+ * 2017-11-03  (Sebastian Pipping)
+ *   - Hide sip_tobin and sip_binof unless SIPHASH_TOBIN macro is defined
+ *
+ * 2017-07-25  (Vadim Zeitlin)
+ *   - Fix use of SIPHASH_MAIN macro
+ *
+ * 2017-07-05  (Sebastian Pipping)
+ *   - Use _SIP_ULL macro to not require a C++11 compiler if compiled as C++
+ *   - Add const qualifiers at two places
+ *   - Ensure <=80 characters line length (assuming tab width 4)
+ *
+ * 2017-06-23  (Victor Stinner)
+ *   - Address Win64 compile warnings
+ *
+ * 2017-06-18  (Sebastian Pipping)
+ *   - Clarify license note in the header
+ *   - Address C89 issues:
+ *     - Stop using inline keyword (and let compiler decide)
+ *     - Replace _Bool by int
+ *     - Turn macro siphash24 into a function
+ *     - Address invalid conversion (void pointer) by explicit cast
+ *   - Address lack of stdint.h for Visual Studio 2003 to 2008
+ *   - Always expose sip24_valid (for self-tests)
+ *
+ * 2012-11-04 - Born.  (William Ahern)
+ * --------------------------------------------------------------------------
+ * USAGE:
+ *
+ * SipHash-2-4 takes as input two 64-bit words as the key, some number of
+ * message bytes, and outputs a 64-bit word as the message digest. This
+ * implementation employs two data structures: a struct sipkey for
+ * representing the key, and a struct siphash for representing the hash
+ * state.
+ *
+ * For converting a 16-byte unsigned char array to a key, use either the
+ * macro sip_keyof or the routine sip_tokey. The former instantiates a
+ * compound literal key, while the latter requires a key object as a
+ * parameter.
+ *
+ * 	unsigned char secret[16];
+ * 	arc4random_buf(secret, sizeof secret);
+ * 	struct sipkey *key = sip_keyof(secret);
+ *
+ * For hashing a message, use either the convenience macro siphash24 or the
+ * routines sip24_init, sip24_update, and sip24_final.
+ *
+ * 	struct siphash state;
+ * 	void *msg;
+ * 	size_t len;
+ * 	uint64_t hash;
+ *
+ * 	sip24_init(&state, key);
+ * 	sip24_update(&state, msg, len);
+ * 	hash = sip24_final(&state);
+ *
+ * or
+ *
+ * 	hash = siphash24(msg, len, key);
+ *
+ * To convert the 64-bit hash value to a canonical 8-byte little-endian
+ * binary representation, use either the macro sip_binof or the routine
+ * sip_tobin. The former instantiates and returns a compound literal array,
+ * while the latter requires an array object as a parameter.
+ * --------------------------------------------------------------------------
+ * NOTES:
+ *
+ * o Neither sip_keyof, sip_binof, nor siphash24 will work with compilers
+ *   lacking compound literal support. Instead, you must use the lower-level
+ *   interfaces which take as parameters the temporary state objects.
+ *
+ * o Uppercase macros may evaluate parameters more than once. Lowercase
+ *   macros should not exhibit any such side effects.
+ * ==========================================================================
+ */
+#ifndef SIPHASH_H
+#define SIPHASH_H
+
+#include <stddef.h> /* size_t */
+#include <stdint.h> /* uint64_t uint32_t uint8_t */
+
+/*
+ * Workaround to not require a C++11 compiler for using ULL suffix
+ * if this code is included and compiled as C++; related GCC warning is:
+ * warning: use of C++11 long long integer constant [-Wlong-long]
+ */
+#define SIP_ULL(high, low) ((((uint64_t)high) << 32) | (low))
+
+#define SIP_ROTL(x, b) (uint64_t)(((x) << (b)) | ((x) >> (64 - (b))))
+
+#define SIP_U32TO8_LE(p, v)      \
+  (p)[0] = (uint8_t)((v) >> 0);  \
+  (p)[1] = (uint8_t)((v) >> 8);  \
+  (p)[2] = (uint8_t)((v) >> 16); \
+  (p)[3] = (uint8_t)((v) >> 24);
+
+#define SIP_U64TO8_LE(p, v)                     \
+  SIP_U32TO8_LE((p) + 0, (uint32_t)((v) >> 0)); \
+  SIP_U32TO8_LE((p) + 4, (uint32_t)((v) >> 32));
+
+#define SIP_U8TO64_LE(p)                                                                                             \
+  (((uint64_t)((p)[0]) << 0) | ((uint64_t)((p)[1]) << 8) | ((uint64_t)((p)[2]) << 16) | ((uint64_t)((p)[3]) << 24) | \
+   ((uint64_t)((p)[4]) << 32) | ((uint64_t)((p)[5]) << 40) | ((uint64_t)((p)[6]) << 48) | ((uint64_t)((p)[7]) << 56))
+
+#define SIPHASH_INITIALIZER {0, 0, 0, 0, {0}, 0, 0}
+
+struct siphash {
+  uint64_t v0, v1, v2, v3;
+
+  unsigned char buf[8], *p;
+  uint64_t c;
+}; /* struct siphash */
+
+#define SIP_KEYLEN 16
+
+struct sipkey {
+  uint64_t k[2];
+}; /* struct sipkey */
+
+#define sip_keyof(k) sip_tokey(&(struct sipkey){{0}}, (k))
+
+static struct sipkey* sip_tokey(struct sipkey* key, const void* src) {
+  key->k[0] = SIP_U8TO64_LE((const unsigned char*)src);
+  key->k[1] = SIP_U8TO64_LE((const unsigned char*)src + 8);
+  return key;
+} /* sip_tokey() */
+
+#ifdef SIPHASH_TOBIN
+
+#define sip_binof(v) sip_tobin((unsigned char[8]){0}, (v))
+
+static void* sip_tobin(void* dst, uint64_t u64) {
+  SIP_U64TO8_LE((unsigned char*)dst, u64);
+  return dst;
+} /* sip_tobin() */
+
+#endif /* SIPHASH_TOBIN */
+
+static void sip_round(struct siphash* H, const int rounds) {
+  int i;
+
+  for (i = 0; i < rounds; i++) {
+    H->v0 += H->v1;
+    H->v1 = SIP_ROTL(H->v1, 13);
+    H->v1 ^= H->v0;
+    H->v0 = SIP_ROTL(H->v0, 32);
+
+    H->v2 += H->v3;
+    H->v3 = SIP_ROTL(H->v3, 16);
+    H->v3 ^= H->v2;
+
+    H->v0 += H->v3;
+    H->v3 = SIP_ROTL(H->v3, 21);
+    H->v3 ^= H->v0;
+
+    H->v2 += H->v1;
+    H->v1 = SIP_ROTL(H->v1, 17);
+    H->v1 ^= H->v2;
+    H->v2 = SIP_ROTL(H->v2, 32);
+  }
+} /* sip_round() */
+
+static struct siphash* sip24_init(struct siphash* H, const struct sipkey* key) {
+  H->v0 = SIP_ULL(0x736f6d65U, 0x70736575U) ^ key->k[0];
+  H->v1 = SIP_ULL(0x646f7261U, 0x6e646f6dU) ^ key->k[1];
+  H->v2 = SIP_ULL(0x6c796765U, 0x6e657261U) ^ key->k[0];
+  H->v3 = SIP_ULL(0x74656462U, 0x79746573U) ^ key->k[1];
+
+  H->p = H->buf;
+  H->c = 0;
+
+  return H;
+} /* sip24_init() */
+
+#define sip_endof(a) (&(a)[sizeof(a) / sizeof *(a)])
+
+static struct siphash* sip24_update(struct siphash* H, const void* src, size_t len) {
+  const unsigned char *p = (const unsigned char*)src, *pe = p + len;
+  uint64_t m;
+
+  do {
+    while (p < pe && H->p < sip_endof(H->buf)) *H->p++ = *p++;
+
+    if (H->p < sip_endof(H->buf)) break;
+
+    m = SIP_U8TO64_LE(H->buf);
+    H->v3 ^= m;
+    sip_round(H, 2);
+    H->v0 ^= m;
+
+    H->p = H->buf;
+    H->c += 8;
+  } while (p < pe);
+
+  return H;
+} /* sip24_update() */
+
+static uint64_t sip24_final(struct siphash* H) {
+  const char left = (char)(H->p - H->buf);
+  uint64_t b = (H->c + left) << 56;
+
+  switch (left) {
+    case 7:
+      b |= (uint64_t)H->buf[6] << 48;
+      /* fall through */
+    case 6:
+      b |= (uint64_t)H->buf[5] << 40;
+      /* fall through */
+    case 5:
+      b |= (uint64_t)H->buf[4] << 32;
+      /* fall through */
+    case 4:
+      b |= (uint64_t)H->buf[3] << 24;
+      /* fall through */
+    case 3:
+      b |= (uint64_t)H->buf[2] << 16;
+      /* fall through */
+    case 2:
+      b |= (uint64_t)H->buf[1] << 8;
+      /* fall through */
+    case 1:
+      b |= (uint64_t)H->buf[0] << 0;
+      /* fall through */
+    case 0:
+      break;
+  }
+
+  H->v3 ^= b;
+  sip_round(H, 2);
+  H->v0 ^= b;
+  H->v2 ^= 0xff;
+  sip_round(H, 4);
+
+  return H->v0 ^ H->v1 ^ H->v2 ^ H->v3;
+} /* sip24_final() */
+
+static uint64_t siphash24(const void* src, size_t len, const struct sipkey* key) {
+  struct siphash state = SIPHASH_INITIALIZER;
+  return sip24_final(sip24_update(sip24_init(&state, key), src, len));
+} /* siphash24() */
+
+/*
+ * SipHash-2-4 output with
+ * k = 00 01 02 ...
+ * and
+ * in = (empty string)
+ * in = 00 (1 byte)
+ * in = 00 01 (2 bytes)
+ * in = 00 01 02 (3 bytes)
+ * ...
+ * in = 00 01 02 ... 3e (63 bytes)
+ */
+static int sip24_valid(void) {
+  /* clang-format off */
+  static const unsigned char vectors[64][8] = {
+    { 0x31, 0x0e, 0x0e, 0xdd, 0x47, 0xdb, 0x6f, 0x72, },
+    { 0xfd, 0x67, 0xdc, 0x93, 0xc5, 0x39, 0xf8, 0x74, },
+    { 0x5a, 0x4f, 0xa9, 0xd9, 0x09, 0x80, 0x6c, 0x0d, },
+    { 0x2d, 0x7e, 0xfb, 0xd7, 0x96, 0x66, 0x67, 0x85, },
+    { 0xb7, 0x87, 0x71, 0x27, 0xe0, 0x94, 0x27, 0xcf, },
+    { 0x8d, 0xa6, 0x99, 0xcd, 0x64, 0x55, 0x76, 0x18, },
+    { 0xce, 0xe3, 0xfe, 0x58, 0x6e, 0x46, 0xc9, 0xcb, },
+    { 0x37, 0xd1, 0x01, 0x8b, 0xf5, 0x00, 0x02, 0xab, },
+    { 0x62, 0x24, 0x93, 0x9a, 0x79, 0xf5, 0xf5, 0x93, },
+    { 0xb0, 0xe4, 0xa9, 0x0b, 0xdf, 0x82, 0x00, 0x9e, },
+    { 0xf3, 0xb9, 0xdd, 0x94, 0xc5, 0xbb, 0x5d, 0x7a, },
+    { 0xa7, 0xad, 0x6b, 0x22, 0x46, 0x2f, 0xb3, 0xf4, },
+    { 0xfb, 0xe5, 0x0e, 0x86, 0xbc, 0x8f, 0x1e, 0x75, },
+    { 0x90, 0x3d, 0x84, 0xc0, 0x27, 0x56, 0xea, 0x14, },
+    { 0xee, 0xf2, 0x7a, 0x8e, 0x90, 0xca, 0x23, 0xf7, },
+    { 0xe5, 0x45, 0xbe, 0x49, 0x61, 0xca, 0x29, 0xa1, },
+    { 0xdb, 0x9b, 0xc2, 0x57, 0x7f, 0xcc, 0x2a, 0x3f, },
+    { 0x94, 0x47, 0xbe, 0x2c, 0xf5, 0xe9, 0x9a, 0x69, },
+    { 0x9c, 0xd3, 0x8d, 0x96, 0xf0, 0xb3, 0xc1, 0x4b, },
+    { 0xbd, 0x61, 0x79, 0xa7, 0x1d, 0xc9, 0x6d, 0xbb, },
+    { 0x98, 0xee, 0xa2, 0x1a, 0xf2, 0x5c, 0xd6, 0xbe, },
+    { 0xc7, 0x67, 0x3b, 0x2e, 0xb0, 0xcb, 0xf2, 0xd0, },
+    { 0x88, 0x3e, 0xa3, 0xe3, 0x95, 0x67, 0x53, 0x93, },
+    { 0xc8, 0xce, 0x5c, 0xcd, 0x8c, 0x03, 0x0c, 0xa8, },
+    { 0x94, 0xaf, 0x49, 0xf6, 0xc6, 0x50, 0xad, 0xb8, },
+    { 0xea, 0xb8, 0x85, 0x8a, 0xde, 0x92, 0xe1, 0xbc, },
+    { 0xf3, 0x15, 0xbb, 0x5b, 0xb8, 0x35, 0xd8, 0x17, },
+    { 0xad, 0xcf, 0x6b, 0x07, 0x63, 0x61, 0x2e, 0x2f, },
+    { 0xa5, 0xc9, 0x1d, 0xa7, 0xac, 0xaa, 0x4d, 0xde, },
+    { 0x71, 0x65, 0x95, 0x87, 0x66, 0x50, 0xa2, 0xa6, },
+    { 0x28, 0xef, 0x49, 0x5c, 0x53, 0xa3, 0x87, 0xad, },
+    { 0x42, 0xc3, 0x41, 0xd8, 0xfa, 0x92, 0xd8, 0x32, },
+    { 0xce, 0x7c, 0xf2, 0x72, 0x2f, 0x51, 0x27, 0x71, },
+    { 0xe3, 0x78, 0x59, 0xf9, 0x46, 0x23, 0xf3, 0xa7, },
+    { 0x38, 0x12, 0x05, 0xbb, 0x1a, 0xb0, 0xe0, 0x12, },
+    { 0xae, 0x97, 0xa1, 0x0f, 0xd4, 0x34, 0xe0, 0x15, },
+    { 0xb4, 0xa3, 0x15, 0x08, 0xbe, 0xff, 0x4d, 0x31, },
+    { 0x81, 0x39, 0x62, 0x29, 0xf0, 0x90, 0x79, 0x02, },
+    { 0x4d, 0x0c, 0xf4, 0x9e, 0xe5, 0xd4, 0xdc, 0xca, },
+    { 0x5c, 0x73, 0x33, 0x6a, 0x76, 0xd8, 0xbf, 0x9a, },
+    { 0xd0, 0xa7, 0x04, 0x53, 0x6b, 0xa9, 0x3e, 0x0e, },
+    { 0x92, 0x59, 0x58, 0xfc, 0xd6, 0x42, 0x0c, 0xad, },
+    { 0xa9, 0x15, 0xc2, 0x9b, 0xc8, 0x06, 0x73, 0x18, },
+    { 0x95, 0x2b, 0x79, 0xf3, 0xbc, 0x0a, 0xa6, 0xd4, },
+    { 0xf2, 0x1d, 0xf2, 0xe4, 0x1d, 0x45, 0x35, 0xf9, },
+    { 0x87, 0x57, 0x75, 0x19, 0x04, 0x8f, 0x53, 0xa9, },
+    { 0x10, 0xa5, 0x6c, 0xf5, 0xdf, 0xcd, 0x9a, 0xdb, },
+    { 0xeb, 0x75, 0x09, 0x5c, 0xcd, 0x98, 0x6c, 0xd0, },
+    { 0x51, 0xa9, 0xcb, 0x9e, 0xcb, 0xa3, 0x12, 0xe6, },
+    { 0x96, 0xaf, 0xad, 0xfc, 0x2c, 0xe6, 0x66, 0xc7, },
+    { 0x72, 0xfe, 0x52, 0x97, 0x5a, 0x43, 0x64, 0xee, },
+    { 0x5a, 0x16, 0x45, 0xb2, 0x76, 0xd5, 0x92, 0xa1, },
+    { 0xb2, 0x74, 0xcb, 0x8e, 0xbf, 0x87, 0x87, 0x0a, },
+    { 0x6f, 0x9b, 0xb4, 0x20, 0x3d, 0xe7, 0xb3, 0x81, },
+    { 0xea, 0xec, 0xb2, 0xa3, 0x0b, 0x22, 0xa8, 0x7f, },
+    { 0x99, 0x24, 0xa4, 0x3c, 0xc1, 0x31, 0x57, 0x24, },
+    { 0xbd, 0x83, 0x8d, 0x3a, 0xaf, 0xbf, 0x8d, 0xb7, },
+    { 0x0b, 0x1a, 0x2a, 0x32, 0x65, 0xd5, 0x1a, 0xea, },
+    { 0x13, 0x50, 0x79, 0xa3, 0x23, 0x1c, 0xe6, 0x60, },
+    { 0x93, 0x2b, 0x28, 0x46, 0xe4, 0xd7, 0x06, 0x66, },
+    { 0xe1, 0x91, 0x5f, 0x5c, 0xb1, 0xec, 0xa4, 0x6c, },
+    { 0xf3, 0x25, 0x96, 0x5c, 0xa1, 0x6d, 0x62, 0x9f, },
+    { 0x57, 0x5f, 0xf2, 0x8e, 0x60, 0x38, 0x1b, 0xe5, },
+    { 0x72, 0x45, 0x06, 0xeb, 0x4c, 0x32, 0x8a, 0x95, }
+  };
+  /* clang-format on */
+
+  unsigned char in[64];
+  struct sipkey k;
+  size_t i;
+
+  sip_tokey(&k,
+            "\000\001\002\003\004\005\006\007\010\011"
+            "\012\013\014\015\016\017");
+
+  for (i = 0; i < sizeof in; ++i) {
+    in[i] = (unsigned char)i;
+
+    if (siphash24(in, i, &k) != SIP_U8TO64_LE(vectors[i])) return 0;
+  }
+
+  return 1;
+} /* sip24_valid() */
+
+#ifdef SIPHASH_MAIN
+
+#include <stdio.h>
+
+int main(void) {
+  const int ok = sip24_valid();
+
+  if (ok)
+    puts("OK");
+  else
+    puts("FAIL");
+
+  return !ok;
+} /* main() */
+
+#endif /* SIPHASH_MAIN */
+
+#endif /* SIPHASH_H */

lib/expat/utf8tab.h

@@ -0,0 +1,66 @@
+/*
+                            __  __            _
+                         ___\ \/ /_ __   __ _| |_
+                        / _ \\  /| '_ \ / _` | __|
+                       |  __//  \| |_) | (_| | |_
+                        \___/_/\_\ .__/ \__,_|\__|
+                                 |_| XML parser
+
+   Copyright (c) 1997-2000 Thai Open Source Software Center Ltd
+   Copyright (c) 2000      Clark Cooper <coopercc@users.sourceforge.net>
+   Copyright (c) 2002      Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
+   Copyright (c) 2017      Sebastian Pipping <sebastian@pipping.org>
+   Licensed under the MIT license:
+
+   Permission is  hereby granted,  free of charge,  to any  person obtaining
+   a  copy  of  this  software   and  associated  documentation  files  (the
+   "Software"),  to  deal in  the  Software  without restriction,  including
+   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+   distribute, sublicense, and/or sell copies of the Software, and to permit
+   persons  to whom  the Software  is  furnished to  do so,  subject to  the
+   following conditions:
+
+   The above copyright  notice and this permission notice  shall be included
+   in all copies or substantial portions of the Software.
+
+   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+/* 0x80 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0x84 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0x88 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0x8C */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0x90 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0x94 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0x98 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0x9C */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0xA0 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0xA4 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0xA8 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0xAC */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0xB0 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0xB4 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0xB8 */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0xBC */ BT_TRAIL, BT_TRAIL, BT_TRAIL, BT_TRAIL,
+    /* 0xC0 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2,
+    /* 0xC4 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2,
+    /* 0xC8 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2,
+    /* 0xCC */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2,
+    /* 0xD0 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2,
+    /* 0xD4 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2,
+    /* 0xD8 */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2,
+    /* 0xDC */ BT_LEAD2, BT_LEAD2, BT_LEAD2, BT_LEAD2,
+    /* 0xE0 */ BT_LEAD3, BT_LEAD3, BT_LEAD3, BT_LEAD3,
+    /* 0xE4 */ BT_LEAD3, BT_LEAD3, BT_LEAD3, BT_LEAD3,
+    /* 0xE8 */ BT_LEAD3, BT_LEAD3, BT_LEAD3, BT_LEAD3,
+    /* 0xEC */ BT_LEAD3, BT_LEAD3, BT_LEAD3, BT_LEAD3,
+    /* 0xF0 */ BT_LEAD4, BT_LEAD4, BT_LEAD4, BT_LEAD4,
+    /* 0xF4 */ BT_LEAD4, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0xF8 */ BT_NONXML, BT_NONXML, BT_NONXML, BT_NONXML,
+    /* 0xFC */ BT_NONXML, BT_NONXML, BT_MALFORM, BT_MALFORM,

lib/expat/winconfig.h

@@ -0,0 +1,48 @@
+/*
+                            __  __            _
+                         ___\ \/ /_ __   __ _| |_
+                        / _ \\  /| '_ \ / _` | __|
+                       |  __//  \| |_) | (_| | |_
+                        \___/_/\_\ .__/ \__,_|\__|
+                                 |_| XML parser
+
+   Copyright (c) 2000      Clark Cooper <coopercc@users.sourceforge.net>
+   Copyright (c) 2002      Greg Stein <gstein@users.sourceforge.net>
+   Copyright (c) 2005      Karl Waclawek <karl@waclawek.net>
+   Copyright (c) 2017-2023 Sebastian Pipping <sebastian@pipping.org>
+   Copyright (c) 2023      Orgad Shaneh <orgad.shaneh@audiocodes.com>
+   Licensed under the MIT license:
+
+   Permission is  hereby granted,  free of charge,  to any  person obtaining
+   a  copy  of  this  software   and  associated  documentation  files  (the
+   "Software"),  to  deal in  the  Software  without restriction,  including
+   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+   distribute, sublicense, and/or sell copies of the Software, and to permit
+   persons  to whom  the Software  is  furnished to  do so,  subject to  the
+   following conditions:
+
+   The above copyright  notice and this permission notice  shall be included
+   in all copies or substantial portions of the Software.
+
+   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+#ifndef WINCONFIG_H
+#define WINCONFIG_H
+
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN
+#endif
+#include <windows.h>
+#undef WIN32_LEAN_AND_MEAN
+
+#include <memory.h>
+#include <string.h>
+
+#endif /* ndef WINCONFIG_H */

lib/expat/xmlrole.h

@@ -0,0 +1,134 @@
+/*
+                            __  __            _
+                         ___\ \/ /_ __   __ _| |_
+                        / _ \\  /| '_ \ / _` | __|
+                       |  __//  \| |_) | (_| | |_
+                        \___/_/\_\ .__/ \__,_|\__|
+                                 |_| XML parser
+
+   Copyright (c) 1997-2000 Thai Open Source Software Center Ltd
+   Copyright (c) 2000      Clark Cooper <coopercc@users.sourceforge.net>
+   Copyright (c) 2002      Karl Waclawek <karl@waclawek.net>
+   Copyright (c) 2002      Fred L. Drake, Jr. <fdrake@users.sourceforge.net>
+   Copyright (c) 2017-2025 Sebastian Pipping <sebastian@pipping.org>
+   Licensed under the MIT license:
+
+   Permission is  hereby granted,  free of charge,  to any  person obtaining
+   a  copy  of  this  software   and  associated  documentation  files  (the
+   "Software"),  to  deal in  the  Software  without restriction,  including
+   without  limitation the  rights  to use,  copy,  modify, merge,  publish,
+   distribute, sublicense, and/or sell copies of the Software, and to permit
+   persons  to whom  the Software  is  furnished to  do so,  subject to  the
+   following conditions:
+
+   The above copyright  notice and this permission notice  shall be included
+   in all copies or substantial portions of the Software.
+
+   THE  SOFTWARE  IS  PROVIDED  "AS  IS",  WITHOUT  WARRANTY  OF  ANY  KIND,
+   EXPRESS  OR IMPLIED,  INCLUDING  BUT  NOT LIMITED  TO  THE WARRANTIES  OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+   NO EVENT SHALL THE AUTHORS OR  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR  OTHER LIABILITY, WHETHER  IN AN  ACTION OF CONTRACT,  TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+#ifndef XmlRole_INCLUDED
+#define XmlRole_INCLUDED 1
+
+#include "xmltok.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+enum {
+  XML_ROLE_ERROR = -1,
+  XML_ROLE_NONE = 0,
+  XML_ROLE_XML_DECL,
+  XML_ROLE_INSTANCE_START,
+  XML_ROLE_DOCTYPE_NONE,
+  XML_ROLE_DOCTYPE_NAME,
+  XML_ROLE_DOCTYPE_SYSTEM_ID,
+  XML_ROLE_DOCTYPE_PUBLIC_ID,
+  XML_ROLE_DOCTYPE_INTERNAL_SUBSET,
+  XML_ROLE_DOCTYPE_CLOSE,
+  XML_ROLE_GENERAL_ENTITY_NAME,
+  XML_ROLE_PARAM_ENTITY_NAME,
+  XML_ROLE_ENTITY_NONE,
+  XML_ROLE_ENTITY_VALUE,
+  XML_ROLE_ENTITY_SYSTEM_ID,
+  XML_ROLE_ENTITY_PUBLIC_ID,
+  XML_ROLE_ENTITY_COMPLETE,
+  XML_ROLE_ENTITY_NOTATION_NAME,
+  XML_ROLE_NOTATION_NONE,
+  XML_ROLE_NOTATION_NAME,
+  XML_ROLE_NOTATION_SYSTEM_ID,
+  XML_ROLE_NOTATION_NO_SYSTEM_ID,
+  XML_ROLE_NOTATION_PUBLIC_ID,
+  XML_ROLE_ATTRIBUTE_NAME,
+  XML_ROLE_ATTRIBUTE_TYPE_CDATA,
+  XML_ROLE_ATTRIBUTE_TYPE_ID,
+  XML_ROLE_ATTRIBUTE_TYPE_IDREF,
+  XML_ROLE_ATTRIBUTE_TYPE_IDREFS,
+  XML_ROLE_ATTRIBUTE_TYPE_ENTITY,
+  XML_ROLE_ATTRIBUTE_TYPE_ENTITIES,
+  XML_ROLE_ATTRIBUTE_TYPE_NMTOKEN,
+  XML_ROLE_ATTRIBUTE_TYPE_NMTOKENS,
+  XML_ROLE_ATTRIBUTE_ENUM_VALUE,
+  XML_ROLE_ATTRIBUTE_NOTATION_VALUE,
+  XML_ROLE_ATTLIST_NONE,
+  XML_ROLE_ATTLIST_ELEMENT_NAME,
+  XML_ROLE_IMPLIED_ATTRIBUTE_VALUE,
+  XML_ROLE_REQUIRED_ATTRIBUTE_VALUE,
+  XML_ROLE_DEFAULT_ATTRIBUTE_VALUE,
+  XML_ROLE_FIXED_ATTRIBUTE_VALUE,
+  XML_ROLE_ELEMENT_NONE,
+  XML_ROLE_ELEMENT_NAME,
+  XML_ROLE_CONTENT_ANY,
+  XML_ROLE_CONTENT_EMPTY,
+  XML_ROLE_CONTENT_PCDATA,
+  XML_ROLE_GROUP_OPEN,
+  XML_ROLE_GROUP_CLOSE,
+  XML_ROLE_GROUP_CLOSE_REP,
+  XML_ROLE_GROUP_CLOSE_OPT,
+  XML_ROLE_GROUP_CLOSE_PLUS,
+  XML_ROLE_GROUP_CHOICE,
+  XML_ROLE_GROUP_SEQUENCE,
+  XML_ROLE_CONTENT_ELEMENT,
+  XML_ROLE_CONTENT_ELEMENT_REP,
+  XML_ROLE_CONTENT_ELEMENT_OPT,
+  XML_ROLE_CONTENT_ELEMENT_PLUS,
+  XML_ROLE_PI,
+  XML_ROLE_COMMENT,
+#ifdef XML_DTD
+  XML_ROLE_TEXT_DECL,
+  XML_ROLE_IGNORE_SECT,
+  XML_ROLE_INNER_PARAM_ENTITY_REF,
+#endif /* XML_DTD */
+  XML_ROLE_PARAM_ENTITY_REF
+};
+
+typedef struct prolog_state {
+  int(PTRCALL* handler)(struct prolog_state* state, int tok, const char* ptr, const char* end, const ENCODING* enc);
+  unsigned level;
+  int role_none;
+#ifdef XML_DTD
+  unsigned includeLevel;
+  int documentEntity;
+  int inEntityValue;
+#endif /* XML_DTD */
+} PROLOG_STATE;
+
+void XmlPrologStateInit(PROLOG_STATE* state);
+#ifdef XML_DTD
+void XmlPrologStateInitExternalEntity(PROLOG_STATE* state);
+#endif /* XML_DTD */
+
+#define XmlTokenRole(state, tok, ptr, end, enc) (((state)->handler)(state, tok, ptr, end, enc))
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* not XmlRole_INCLUDED */