Cut release 0.6.0

* add horizontal indent in first line of paragraph in case Extra Paragraph Spacing is OFF

* Treat tabs as whitespace (so they are properly stripped)

* Changed size of indent to 1 em.

* Fixed calculation of space when indenting (avoiding squeezed text).

* Source code formatting

.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 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,5 @@
 .pio
 .idea
 .DS_Store
+.vscode
+lib/EpdFont/fontsrc

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
 
@@ -32,14 +29,41 @@ This project is **not affiliated with Xteink**; it's built as a community projec
 - [x] Saved reading position
 - [ ] File explorer with file picker
   - [x] Basic EPUB picker from root directory
-  - [ ] Support nested folders
+  - [x] Support nested folders
   - [ ] EPUB picker with cover art
 - [ ] Image support within EPUB
 - [ ] Configurable font, layout, and display options
 - [ ] WiFi connectivity
 - [ ] BLE connectivity
 
-## Getting Started
+## 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.
+
+## Usage
+
+See [the user guide](./USER_GUIDE.md) for instructions on operating CrossPoint.
+
+## Development
 
 ### Prerequisites
 
@@ -48,9 +72,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 +91,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 +131,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 +144,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,78 @@
+# 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 1 full second**.
+
+### First Launch
+
+Upon turning the device on for the first time, you will be placed on the **Book Selection Screen** (File Browser).
+
+> **Note:** On subsequent restarts, the firmware will automatically reopen the last book you were reading.
+
+---
+
+## 3. Book Selection
+
+The Home Screen 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.
+
+---
+
+## 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.

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)

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);
+};