chore: Cut release 0.13.0

copy: Tweak pull request template wording
fix: Handle EPUB 3 TOC to spine mapping when nav file in subdirectory (#332 )
2026-04-29 10:26:52 -07:00 · 2026-01-13 00:59:13 +11:00 · 2026-01-13 00:59:04 +11:00 · 2026-01-13 00:57:34 +11:00 · 2026-01-12 22:36:19 +11:00 · 2026-01-12 21:49:42 +11:00
273 changed files with 294279 additions and 31119 deletions
@@ -0,0 +1,2 @@
+CompileFlags:
+    Add: [-std=c++2a]
@@ -0,0 +1,2 @@
+github: [daveallie]
+ko_fi: daveallie
@@ -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
@@ -0,0 +1,18 @@
+## Summary
+
+* **What is the goal of this PR?** (e.g., 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).
+
+---
+
+### AI Usage
+
+While CrossPoint doesn't have restrictions on AI tools in contributing, please be transparent about their usage as it 
+helps set the right context for reviewers.
+
+Did you use AI tools to help write this code? _**< YES | PARTIALLY | NO >**_
@@ -0,0 +1,37 @@
+name: CI
+'on':
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - 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
@@ -0,0 +1,41 @@
+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
@@ -1,3 +1,6 @@
 .pio
 .idea
 .DS_Store
+.vscode
+lib/EpdFont/fontsrc
+*.generated.h
@@ -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,50 @@ 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] EPUB parsing and rendering (EPUB 2 and EPUB 3)
+- [ ] Image support within EPUB
 - [x] Saved reading position
- [ ] File explorer with file picker
+- [x] File explorer with file picker
  - [x] Basic EPUB picker from root directory
  - [x] Support nested folders
  - [ ] EPUB picker with cover art
- [ ] Image support within EPUB
- [ ] Configurable font, layout, and display options
- [ ] WiFi connectivity
- [ ] BLE connectivity
+- [x] Custom sleep screen
+  - [x] Cover sleep screen
+- [x] Wifi book upload
+- [x] Wifi OTA updates
+- [x] Configurable font, layout, and display options
+  - [ ] User provided fonts
+  - [ ] Full UTF support
+- [x] 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

@@ -61,33 +88,21 @@ git submodule update --init --recursive

 ### Flashing your device

-#### Command line
-
 Connect your Xteink X4 to your computer via USB-C and run the following command.

 ```sh
 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
 has ~380KB of usable RAM, so we have to be careful. A lot of the decisions made in the design of the firmware were based
 on this constraint.

-### EPUB caching
+### Data caching

-The first time chapters of an EPUB are loaded, they are cached to the SD card. Subsequent loads are served from the 
+The first time chapters of a book are loaded, they are cached to the SD card. Subsequent loads are served from the 
 cache. This cache directory exists at `.crosspoint` on the SD card. The structure is as follows:


@@ -95,30 +110,30 @@ cache. This cache directory exists at `.crosspoint` on the SD card. The structur
 .crosspoint/
 ├── epub_12471232/       # Each EPUB is cached to a subdirectory named `epub_<hash>`
 │   ├── progress.bin     # Stores reading progress (chapter, page, etc.)
-│   ├── 0/               # Each chapter is stored in a subdirectory named by its index (based on the spine order)
-│   │   ├── section.bin  # Section metadata (page count)
-│   │   ├── page_0.bin   # Each page is stored in a separate file, it
-│   │   ├── page_1.bin   #   contains the position (x, y) and text for each word
-│   │   └── ...
-│   ├── 1/
-│   │   ├── section.bin
-│   │   ├── page_0.bin
-│   │   ├── page_1.bin
-│   │   └── ...
-│   └── ...
+│   ├── cover.bmp        # Book cover image (once generated)
+│   ├── book.bin         # Book metadata (title, author, spine, table of contents, etc.)
+│   └── sections/        # All chapter data is stored in the sections subdirectory
+│       ├── 0.bin        # Chapter data (screen count, all text layout info, etc.)
+│       ├── 1.bin        #     files are named by their index in the spine
+│       └── ...
 │
 └── epub_189013891/
 ```

-Deleting the `.crosspoint` directory will clear the cache. 
+Deleting the `.crosspoint` directory will clear the entire cache. 

-Due the way it's currently implemented, the cache is not automatically cleared when the EPUB is deleted and moving an 
-EPUB file will reset the reading progress.
+Due the way it's currently implemented, the cache is not automatically cleared when a book is deleted and moving a book
+file will use a new cache directory, resetting the reading progress.
+
+For more details on the internal file structures, see the [file formats document](./docs/file-formats.md).

 ## Contributing

 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
@@ -129,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.
@@ -0,0 +1,152 @@
+# 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 as the manufacturer firmware, by default):
+
+### Button Layout
+| Location        | Buttons                                              |
+| --------------- | ---------------------------------------------------- |
+| **Bottom Edge** | **Back**, **Confirm**, **Left**, **Right**           |
+| **Right Side**  | **Power**, **Volume Up**, **Volume Down**, **Reset** |
+
+Button layout can be customized in **[Settings](#35-settings)**.
+
+---
+
+## 2. Power & Startup
+
+### Power On / Off
+
+To turn the device on or off, **press and hold the Power button for half a second**. In **[Settings](#35-settings)** you can configure the power button to trigger on a short press instead of a long one.
+
+To reboot the device (for example if it's frozen, or after a firmware update), press and release the Reset button, and then hold the Power button for a few seconds.
+
+### First Launch
+
+Upon turning the device on for the first time, you will be placed on the **[Home](#31-home-screen)** screen.
+
+> [!NOTE]
+> On subsequent restarts, the firmware will automatically reopen the last book you were reading.
+
+---
+
+## 3. Screens
+
+### 3.1 Home Screen
+
+The Home Screen is the main entry point to the firmware. From here you can navigate to **[Reading Mode](#4-reading-mode)** with the most recently read book, **[Book Selection](#32-book-selection)**, **[Settings](#35-settings)**, or the **[File Upload](#34-file-upload-screen)** screen.
+
+### 3.2 Book Selection
+
+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. You can also long-press these buttons to scroll a full page up or down.
+* **Open Selection:** Press **Confirm** to open a folder or read a selected book.
+
+### 3.3 Reading Mode
+
+See [Reading Mode](#4-reading-mode) below for more information.
+
+### 3.4 File Upload Screen
+
+The File Upload screen allows you to upload new e-books to the device. When you enter the screen, you'll be prompted with 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.
+
+> [!TIP]
+> Advanced users can also manage files programmatically or via the command line using `curl`. See the [webserver docs](./docs/webserver.md) for details.
+
+### 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:
+  - "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 [Sleep Screen](#36-sleep-screen) below for more information
+  - "Cover" - The book cover image (Note: this is experimental and may not work as expected)
+  - "Blank" - A blank screen
+- **Status Bar**: Configure the status bar displayed while reading:
+  - "None" - No status bar
+  - "No Progress" - Show status bar without reading progress
+  - "Full" - Show status bar with reading progress
+- **Extra Paragraph Spacing**: If enabled, vertical space will be added between paragraphs in the book. If disabled, paragraphs will not have vertical space between them, but will have first-line indentation.
+- **Short Power Button Click**: Whether to trigger the power button on a short press or a long press.
+- **Reading Orientation**: Set the screen orientation for reading:
+  - "Portrait" (default) - Standard portrait orientation
+  - "Landscape CW" - Landscape, rotated clockwise
+  - "Inverted" - Portrait, upside down
+  - "Landscape CCW" - Landscape, rotated counter-clockwise
+- **Front Button Layout**: Configure the order of the bottom edge buttons:
+  - Back, Confirm, Left, Right (default)
+  - Left, Right, Back, Confirm
+  - Left, Back, Confirm, Right
+- **Side Button Layout**: Swap the order of the up and down volume buttons from Previous/Next to Next/Previous. This change is only in effect when reading.
+- **Reader Font Family**: Choose the font used for reading:
+  - "Bookerly" (default) - Amazon's reading font
+  - "Noto Sans" - Google's sans-serif font
+  - "Open Dyslexic" - Font designed for readers with dyslexia
+- **Reader Font Size**: Adjust the text size for reading; options are "Small", "Medium", "Large", or "X Large".
+- **Reader Line Spacing**: Adjust the spacing between lines; options are "Tight", "Normal", or "Wide".
+- **Reader Paragraph Alignment**: Set the alignment of paragraphs; options are "Justified" (default), "Left", "Center", or "Right".
+- **Time to Sleep**: Set the duration of inactivity before the device automatically goes to sleep.
+- **Refresh Frequency**: Set how often the screen does a full refresh while reading to reduce ghosting.
+- **Check for updates**: Check for firmware updates over WiFi.
+
+### 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.bmp` 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** |
+
+The role of the volume (side) buttons can be swapped in **[Settings](#35-settings)**.
+
+### 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 Book Selection:** Press **Back** to close the book and return to the **[Book Selection](#32-book-selection)** screen.
+* **Return to Home:** Press and **hold** the **Back** button to close the book and return to the **[Home](#31-home-screen)** screen.
+* **Chapter Menu:** Press **Confirm** to open the **[Table of Contents/Chapter Selection](#5-chapter-selection-screen)**.
+
+---
+
+## 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.
@@ -1,3 +1,19 @@
 #!/bin/bash

-find src lib \( -name "*.c" -o -name "*.cpp" -o -name "*.h" -o -name "*.hpp" \) -exec clang-format -style=file -i {} +
+GIT_LS_FILES_FLAGS=""
+if [[ "$1" == "-g" ]]; then
+  GIT_LS_FILES_FLAGS="--modified"
+fi
+
+# --- Main Logic ---
+
+# Format all files (or only modified files if -g is passed)
+
+# Use 'git ls-files' to get a list of all files tracked by git:
+# --modified: files tracked by git that have been modified (staged or unstaged)
+# --exclude-standard: ignores files in .gitignore
+# Additionally exclude files in 'lib/EpdFont/builtinFonts/' as they are script-generated.
+git ls-files  --exclude-standard ${GIT_LS_FILES_FLAGS} \
+    | grep -E '\.(c|cpp|h|hpp)$' \
+    | grep -v -E '^lib/EpdFont/builtinFonts/' \
+    | xargs -r clang-format -style=file -i
@@ -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)
@@ -0,0 +1,221 @@
+# File Formats
+
+## `book.bin`
+
+### Version 3
+
+ImHex Pattern:
+
+```c++
+import std.mem;
+import std.string;
+import std.core;
+
+// === Configuration ===
+#define EXPECTED_VERSION 3
+#define MAX_STRING_LENGTH 65535
+
+// === String Structure ===
+
+struct String {
+    u32 length [[hidden, comment("String byte length")]];
+    if (length > MAX_STRING_LENGTH) {
+        std::warning(std::format("Unusually large string length: {} bytes", length));
+    }
+    char data[length] [[comment("UTF-8 string data")]];
+} [[sealed, format("format_string"), comment("Length-prefixed UTF-8 string")]];
+
+fn format_string(String s) {
+    return s.data;
+};
+
+// === Metadata Structure ===
+
+struct Metadata {
+    String title [[comment("Book title")]];
+    String author [[comment("Book author")]];
+    String coverItemHref [[comment("Path to cover image")]];
+    String textReferenceHref [[comment("Path to guided first text reference")]];
+} [[comment("Book metadata information")]];
+
+// === Spine Entry Structure ===
+
+struct SpineEntry {
+    String href [[comment("Resource path")]];
+    u32 cumulativeSize [[comment("Cumulative size in bytes"), color("FF6B6B")]];
+    s16 tocIndex [[comment("Index into TOC (-1 if none)"), color("4ECDC4")]];
+} [[comment("Spine entry defining reading order")]];
+
+// === TOC Entry Structure ===
+
+struct TocEntry {
+    String title [[comment("Chapter/section title")]];
+    String href [[comment("Resource path")]];
+    String anchor [[comment("Fragment identifier")]];
+    u8 level [[comment("Nesting level (0-255)"), color("95E1D3")]];
+    s16 spineIndex [[comment("Index into spine (-1 if none)"), color("F38181")]];
+} [[comment("Table of contents entry")]];
+
+// === Book Bin Structure ===
+
+struct BookBin {
+    // Header
+    u8 version [[comment("Format version"), color("FFD93D")]];
+    
+    // Version validation
+    if (version != EXPECTED_VERSION) {
+        std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION));
+    }
+    
+    u32 lutOffset [[comment("Offset to lookup tables"), color("6BCB77")]];
+    u16 spineCount [[comment("Number of spine entries"), color("4D96FF")]];
+    u16 tocCount [[comment("Number of TOC entries"), color("FF6B9D")]];
+    
+    // Metadata section
+    Metadata metadata [[comment("Book metadata")]];
+    
+    // Validate LUT offset alignment
+    u32 currentOffset = $;
+    if (currentOffset != lutOffset) {
+        std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset));
+    }
+    
+    // Lookup Tables
+    u32 spineLut[spineCount] [[comment("Spine entry offsets"), color("4D96FF")]];
+    u32 tocLut[tocCount] [[comment("TOC entry offsets"), color("FF6B9D")]];
+    
+    // Data Entries
+    SpineEntry spines[spineCount] [[comment("Spine entries (reading order)")]];
+    TocEntry toc[tocCount] [[comment("Table of contents entries")]];
+};
+
+// === File Parsing ===
+
+BookBin book @ 0x00;
+
+// Validate we've consumed the entire file
+u32 fileSize = std::mem::size();
+u32 parsedSize = $;
+
+if (parsedSize != fileSize) {
+    std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize));
+}
+```
+
+## `section.bin`
+
+### Version 8
+
+ImHex Pattern:
+
+```c++
+import std.mem;
+import std.string;
+import std.core;
+
+// === Configuration ===
+#define EXPECTED_VERSION 8
+#define MAX_STRING_LENGTH 65535
+
+// === String Structure ===
+
+struct String {
+    u32 length [[hidden, comment("String byte length")]];
+    if (length > MAX_STRING_LENGTH) {
+        std::warning(std::format("Unusually large string length: {} bytes", length));
+    }
+    char data[length] [[comment("UTF-8 string data")]];
+} [[sealed, format("format_string"), comment("Length-prefixed UTF-8 string")]];
+
+fn format_string(String s) {
+    return s.data;
+};
+
+// === Page Structure ===
+
+enum StorageType : u8 {
+    PageLine = 1
+};
+
+enum WordStyle : u8 {
+    REGULAR = 0,
+    BOLD = 1,
+    ITALIC = 2,
+    BOLD_ITALIC = 3
+};
+
+enum BlockStyle : u8 {
+    JUSTIFIED = 0,
+    LEFT_ALIGN = 1,
+    CENTER_ALIGN = 2,
+    RIGHT_ALIGN = 3,
+};
+
+struct PageLine {
+  s16 xPos;
+  s16 yPos;
+  u16 wordCount;
+  String words[wordCount];
+  u16 wordXPos[wordCount];
+  WordStyle wordStyle[wordCount];
+  BlockStyle blockStyle;
+};
+
+struct PageElement {
+    u8 pageElementType;
+    if (pageElementType == 1) {
+        PageLine pageLine [[inline]];
+    } else {
+        std::error(std::format("Unknown page element type: {}", pageElementType));
+    }
+};
+
+struct Page {
+    u16 elementCount;
+    PageElement elements[elementCount] [[inline]];
+};
+
+// === Section Bin Structure ===
+
+struct SectionBin {
+    // Header
+    u8 version [[comment("Format version"), color("FFD93D")]];
+    
+    // Version validation
+    if (version != EXPECTED_VERSION) {
+        std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION));
+    }
+    
+    // Cache busting parameters
+    s32 fontId;
+    float lineCompression;
+    bool extraParagraphSpacing;
+    u16 viewportWidth;
+    u16 vieportHeight;
+    u16 pageCount;
+    u32 lutOffset;
+    
+    Page page[pageCount];
+    
+    // Validate LUT offset alignment
+    u32 currentOffset = $;
+    if (currentOffset != lutOffset) {
+        std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset));
+    }
+    
+    // Lookup Tables
+    u32 lut[pageCount];
+};
+
+// === File Parsing ===
+
+SectionBin book @ 0x00;
+
+// Validate we've consumed the entire file
+u32 fileSize = std::mem::size();
+u32 parsedSize = $;
+
+if (parsedSize != fileSize) {
+    std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize));
+}
+```
--- a/Show More
+++ b/Show More