feat: Sleep screen letterbox fill and image upscaling

Add configurable letterbox fill for sleep screen cover images that don't match the display aspect ratio. Four fill modes are available: Solid (single dominant edge shade), Blended (per-pixel edge colors), Gradient (edge colors interpolated toward white/black), and None. Enable upscaling of cover images smaller than the display in Fit mode by modifying drawBitmap/drawBitmap1Bit to support both up and downscaling via a unified block-fill approach. Edge sampling data is cached to .crosspoint alongside the cover BMP to avoid redundant bitmap scanning on subsequent sleeps. Cache is validated against screen dimensions and auto-regenerated when stale. New settings: Letterbox Fill (None/Solid/Blended/Gradient) and Gradient Direction (To White/To Black). Co-authored-by: Cursor <cursoragent@cursor.com>
.gitignore tweaks for mod fork
2026-02-09 11:52:55 -05:00 · 2026-02-09 04:15:00 -05:00 · 2026-02-09 17:18:24 +11:00 · 2026-02-09 08:31:52 +11:00 · 2026-02-09 08:22:20 +11:00 · 2026-02-09 08:16:36 +11:00
58 changed files with 1771 additions and 372 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,8 @@ build
 **/__pycache__/
 /compile_commands.json
 /.cache
+
+# mod
+mod/*
+.cursor/*
+chat-summaries/*
--- a/lib/Epub/Epub.cpp
+++ b/lib/Epub/Epub.cpp
@@ -1,9 +1,9 @@
 #include "Epub.h"

 #include <FsHelpers.h>
+#include <HalStorage.h>
 #include <HardwareSerial.h>
 #include <JpegToBmpConverter.h>
-#include <SDCardManager.h>
 #include <ZipFile.h>

 #include "Epub/parsers/ContainerParser.h"
@@ -105,12 +105,12 @@ bool Epub::parseTocNcxFile() const {

  const auto tmpNcxPath = getCachePath() + "/toc.ncx";
  FsFile tempNcxFile;
-  if (!SdMan.openFileForWrite("EBP", tmpNcxPath, tempNcxFile)) {
+  if (!Storage.openFileForWrite("EBP", tmpNcxPath, tempNcxFile)) {
    return false;
  }
  readItemContentsToStream(tocNcxItem, tempNcxFile, 1024);
  tempNcxFile.close();
-  if (!SdMan.openFileForRead("EBP", tmpNcxPath, tempNcxFile)) {
+  if (!Storage.openFileForRead("EBP", tmpNcxPath, tempNcxFile)) {
    return false;
  }
  const auto ncxSize = tempNcxFile.size();
@@ -145,7 +145,7 @@ bool Epub::parseTocNcxFile() const {

  free(ncxBuffer);
  tempNcxFile.close();
-  SdMan.remove(tmpNcxPath.c_str());
+  Storage.remove(tmpNcxPath.c_str());

  Serial.printf("[%lu] [EBP] Parsed TOC items\n", millis());
  return true;
@@ -162,12 +162,12 @@ bool Epub::parseTocNavFile() const {

  const auto tmpNavPath = getCachePath() + "/toc.nav";
  FsFile tempNavFile;
-  if (!SdMan.openFileForWrite("EBP", tmpNavPath, tempNavFile)) {
+  if (!Storage.openFileForWrite("EBP", tmpNavPath, tempNavFile)) {
    return false;
  }
  readItemContentsToStream(tocNavItem, tempNavFile, 1024);
  tempNavFile.close();
-  if (!SdMan.openFileForRead("EBP", tmpNavPath, tempNavFile)) {
+  if (!Storage.openFileForRead("EBP", tmpNavPath, tempNavFile)) {
    return false;
  }
  const auto navSize = tempNavFile.size();
@@ -202,7 +202,7 @@ bool Epub::parseTocNavFile() const {

  free(navBuffer);
  tempNavFile.close();
-  SdMan.remove(tmpNavPath.c_str());
+  Storage.remove(tmpNavPath.c_str());

  Serial.printf("[%lu] [EBP] Parsed TOC nav items\n", millis());
  return true;
@@ -212,7 +212,7 @@ std::string Epub::getCssRulesCache() const { return cachePath + "/css_rules.cach

 bool Epub::loadCssRulesFromCache() const {
  FsFile cssCacheFile;
-  if (SdMan.openFileForRead("EBP", getCssRulesCache(), cssCacheFile)) {
+  if (Storage.openFileForRead("EBP", getCssRulesCache(), cssCacheFile)) {
    if (cssParser->loadFromCache(cssCacheFile)) {
      cssCacheFile.close();
      Serial.printf("[%lu] [EBP] Loaded CSS rules from cache\n", millis());
@@ -238,32 +238,32 @@ void Epub::parseCssFiles() const {
      // Extract CSS file to temp location
      const auto tmpCssPath = getCachePath() + "/.tmp.css";
      FsFile tempCssFile;
-      if (!SdMan.openFileForWrite("EBP", tmpCssPath, tempCssFile)) {
+      if (!Storage.openFileForWrite("EBP", tmpCssPath, tempCssFile)) {
        Serial.printf("[%lu] [EBP] Could not create temp CSS file\n", millis());
        continue;
      }
      if (!readItemContentsToStream(cssPath, tempCssFile, 1024)) {
        Serial.printf("[%lu] [EBP] Could not read CSS file: %s\n", millis(), cssPath.c_str());
        tempCssFile.close();
-        SdMan.remove(tmpCssPath.c_str());
+        Storage.remove(tmpCssPath.c_str());
        continue;
      }
      tempCssFile.close();

      // Parse the CSS file
-      if (!SdMan.openFileForRead("EBP", tmpCssPath, tempCssFile)) {
+      if (!Storage.openFileForRead("EBP", tmpCssPath, tempCssFile)) {
        Serial.printf("[%lu] [EBP] Could not open temp CSS file for reading\n", millis());
-        SdMan.remove(tmpCssPath.c_str());
+        Storage.remove(tmpCssPath.c_str());
        continue;
      }
      cssParser->loadFromStream(tempCssFile);
      tempCssFile.close();
-      SdMan.remove(tmpCssPath.c_str());
+      Storage.remove(tmpCssPath.c_str());
    }

    // Save to cache for next time
    FsFile cssCacheFile;
-    if (SdMan.openFileForWrite("EBP", getCssRulesCache(), cssCacheFile)) {
+    if (Storage.openFileForWrite("EBP", getCssRulesCache(), cssCacheFile)) {
      cssParser->saveToCache(cssCacheFile);
      cssCacheFile.close();
    }
@@ -399,12 +399,12 @@ bool Epub::load(const bool buildIfMissing, const bool skipLoadingCss) {
 }

 bool Epub::clearCache() const {
-  if (!SdMan.exists(cachePath.c_str())) {
+  if (!Storage.exists(cachePath.c_str())) {
    Serial.printf("[%lu] [EPB] Cache does not exist, no action needed\n", millis());
    return true;
  }

-  if (!SdMan.removeDir(cachePath.c_str())) {
+  if (!Storage.removeDir(cachePath.c_str())) {
    Serial.printf("[%lu] [EPB] Failed to clear cache\n", millis());
    return false;
  }
@@ -414,11 +414,11 @@ bool Epub::clearCache() const {
 }

 void Epub::setupCacheDir() const {
-  if (SdMan.exists(cachePath.c_str())) {
+  if (Storage.exists(cachePath.c_str())) {
    return;
  }

-  SdMan.mkdir(cachePath.c_str());
+  Storage.mkdir(cachePath.c_str());
 }

 const std::string& Epub::getCachePath() const { return cachePath; }
@@ -459,7 +459,7 @@ std::string Epub::getCoverBmpPath(bool cropped) const {

 bool Epub::generateCoverBmp(bool cropped) const {
  // Already generated, return true
-  if (SdMan.exists(getCoverBmpPath(cropped).c_str())) {
+  if (Storage.exists(getCoverBmpPath(cropped).c_str())) {
    return true;
  }

@@ -480,29 +480,29 @@ bool Epub::generateCoverBmp(bool cropped) const {
    const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";

    FsFile coverJpg;
-    if (!SdMan.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
+    if (!Storage.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
      return false;
    }
    readItemContentsToStream(coverImageHref, coverJpg, 1024);
    coverJpg.close();

-    if (!SdMan.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
+    if (!Storage.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
      return false;
    }

    FsFile coverBmp;
-    if (!SdMan.openFileForWrite("EBP", getCoverBmpPath(cropped), coverBmp)) {
+    if (!Storage.openFileForWrite("EBP", getCoverBmpPath(cropped), coverBmp)) {
      coverJpg.close();
      return false;
    }
    const bool success = JpegToBmpConverter::jpegFileToBmpStream(coverJpg, coverBmp, cropped);
    coverJpg.close();
    coverBmp.close();
-    SdMan.remove(coverJpgTempPath.c_str());
+    Storage.remove(coverJpgTempPath.c_str());

    if (!success) {
      Serial.printf("[%lu] [EBP] Failed to generate BMP from JPG cover image\n", millis());
-      SdMan.remove(getCoverBmpPath(cropped).c_str());
+      Storage.remove(getCoverBmpPath(cropped).c_str());
    }
    Serial.printf("[%lu] [EBP] Generated BMP from JPG cover image, success: %s\n", millis(), success ? "yes" : "no");
    return success;
@@ -518,7 +518,7 @@ std::string Epub::getThumbBmpPath(int height) const { return cachePath + "/thumb

 bool Epub::generateThumbBmp(int height) const {
  // Already generated, return true
-  if (SdMan.exists(getThumbBmpPath(height).c_str())) {
+  if (Storage.exists(getThumbBmpPath(height).c_str())) {
    return true;
  }

@@ -536,18 +536,18 @@ bool Epub::generateThumbBmp(int height) const {
    const auto coverJpgTempPath = getCachePath() + "/.cover.jpg";

    FsFile coverJpg;
-    if (!SdMan.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
+    if (!Storage.openFileForWrite("EBP", coverJpgTempPath, coverJpg)) {
      return false;
    }
    readItemContentsToStream(coverImageHref, coverJpg, 1024);
    coverJpg.close();

-    if (!SdMan.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
+    if (!Storage.openFileForRead("EBP", coverJpgTempPath, coverJpg)) {
      return false;
    }

    FsFile thumbBmp;
-    if (!SdMan.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp)) {
+    if (!Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp)) {
      coverJpg.close();
      return false;
    }
@@ -559,11 +559,11 @@ bool Epub::generateThumbBmp(int height) const {
                                                                             THUMB_TARGET_HEIGHT);
    coverJpg.close();
    thumbBmp.close();
-    SdMan.remove(coverJpgTempPath.c_str());
+    Storage.remove(coverJpgTempPath.c_str());

    if (!success) {
      Serial.printf("[%lu] [EBP] Failed to generate thumb BMP from JPG cover image\n", millis());
-      SdMan.remove(getThumbBmpPath(height).c_str());
+      Storage.remove(getThumbBmpPath(height).c_str());
    }
    Serial.printf("[%lu] [EBP] Generated thumb BMP from JPG cover image, success: %s\n", millis(),
                  success ? "yes" : "no");
@@ -574,7 +574,7 @@ bool Epub::generateThumbBmp(int height) const {

  // Write an empty bmp file to avoid generation attempts in the future
  FsFile thumbBmp;
-  SdMan.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp);
+  Storage.openFileForWrite("EBP", getThumbBmpPath(height), thumbBmp);
  thumbBmp.close();
  return false;
 }
--- a/lib/Epub/Epub/BookMetadataCache.cpp
+++ b/lib/Epub/Epub/BookMetadataCache.cpp
@@ -29,7 +29,7 @@ bool BookMetadataCache::beginContentOpfPass() {
  Serial.printf("[%lu] [BMC] Beginning content opf pass\n", millis());

  // Open spine file for writing
-  return SdMan.openFileForWrite("BMC", cachePath + tmpSpineBinFile, spineFile);
+  return Storage.openFileForWrite("BMC", cachePath + tmpSpineBinFile, spineFile);
 }

 bool BookMetadataCache::endContentOpfPass() {
@@ -40,10 +40,10 @@ bool BookMetadataCache::endContentOpfPass() {
 bool BookMetadataCache::beginTocPass() {
  Serial.printf("[%lu] [BMC] Beginning toc pass\n", millis());

-  if (!SdMan.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
    return false;
  }
-  if (!SdMan.openFileForWrite("BMC", cachePath + tmpTocBinFile, tocFile)) {
+  if (!Storage.openFileForWrite("BMC", cachePath + tmpTocBinFile, tocFile)) {
    spineFile.close();
    return false;
  }
@@ -98,16 +98,16 @@ bool BookMetadataCache::endWrite() {

 bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMetadata& metadata) {
  // Open all three files, writing to meta, reading from spine and toc
-  if (!SdMan.openFileForWrite("BMC", cachePath + bookBinFile, bookFile)) {
+  if (!Storage.openFileForWrite("BMC", cachePath + bookBinFile, bookFile)) {
    return false;
  }

-  if (!SdMan.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + tmpSpineBinFile, spineFile)) {
    bookFile.close();
    return false;
  }

-  if (!SdMan.openFileForRead("BMC", cachePath + tmpTocBinFile, tocFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + tmpTocBinFile, tocFile)) {
    bookFile.close();
    spineFile.close();
    return false;
@@ -275,11 +275,11 @@ bool BookMetadataCache::buildBookBin(const std::string& epubPath, const BookMeta
 }

 bool BookMetadataCache::cleanupTmpFiles() const {
-  if (SdMan.exists((cachePath + tmpSpineBinFile).c_str())) {
-    SdMan.remove((cachePath + tmpSpineBinFile).c_str());
+  if (Storage.exists((cachePath + tmpSpineBinFile).c_str())) {
+    Storage.remove((cachePath + tmpSpineBinFile).c_str());
  }
-  if (SdMan.exists((cachePath + tmpTocBinFile).c_str())) {
-    SdMan.remove((cachePath + tmpTocBinFile).c_str());
+  if (Storage.exists((cachePath + tmpTocBinFile).c_str())) {
+    Storage.remove((cachePath + tmpTocBinFile).c_str());
  }
  return true;
 }
@@ -364,7 +364,7 @@ void BookMetadataCache::createTocEntry(const std::string& title, const std::stri
 /* ============= READING / LOADING FUNCTIONS ================ */

 bool BookMetadataCache::load() {
-  if (!SdMan.openFileForRead("BMC", cachePath + bookBinFile, bookFile)) {
+  if (!Storage.openFileForRead("BMC", cachePath + bookBinFile, bookFile)) {
    return false;
  }

--- a/lib/Epub/Epub/BookMetadataCache.h
+++ b/lib/Epub/Epub/BookMetadataCache.h
@@ -1,6 +1,6 @@
 #pragma once

-#include <SDCardManager.h>
+#include <HalStorage.h>

 #include <algorithm>
 #include <string>
--- a/lib/Epub/Epub/Page.h
+++ b/lib/Epub/Epub/Page.h
@@ -1,5 +1,5 @@
 #pragma once
-#include <SdFat.h>
+#include <HalStorage.h>

 #include <utility>
 #include <vector>
--- a/lib/Epub/Epub/Section.cpp
+++ b/lib/Epub/Epub/Section.cpp
@@ -1,6 +1,6 @@
 #include "Section.h"

-#include <SDCardManager.h>
+#include <HalStorage.h>
 #include <Serialization.h>

 #include "Page.h"
@@ -60,7 +60,7 @@ void Section::writeSectionFileHeader(const int fontId, const float lineCompressi
 bool Section::loadSectionFile(const int fontId, const float lineCompression, const bool extraParagraphSpacing,
                              const uint8_t paragraphAlignment, const uint16_t viewportWidth,
                              const uint16_t viewportHeight, const bool hyphenationEnabled, const bool embeddedStyle) {
-  if (!SdMan.openFileForRead("SCT", filePath, file)) {
+  if (!Storage.openFileForRead("SCT", filePath, file)) {
    return false;
  }

@@ -110,12 +110,12 @@ bool Section::loadSectionFile(const int fontId, const float lineCompression, con

 // Your updated class method (assuming you are using the 'SD' object, which is a wrapper for a specific filesystem)
 bool Section::clearCache() const {
-  if (!SdMan.exists(filePath.c_str())) {
+  if (!Storage.exists(filePath.c_str())) {
    Serial.printf("[%lu] [SCT] Cache does not exist, no action needed\n", millis());
    return true;
  }

-  if (!SdMan.remove(filePath.c_str())) {
+  if (!Storage.remove(filePath.c_str())) {
    Serial.printf("[%lu] [SCT] Failed to clear cache\n", millis());
    return false;
  }
@@ -134,7 +134,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
  // Create cache directory if it doesn't exist
  {
    const auto sectionsDir = epub->getCachePath() + "/sections";
-    SdMan.mkdir(sectionsDir.c_str());
+    Storage.mkdir(sectionsDir.c_str());
  }

  // Retry logic for SD card timing issues
@@ -147,12 +147,12 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
    }

    // Remove any incomplete file from previous attempt before retrying
-    if (SdMan.exists(tmpHtmlPath.c_str())) {
-      SdMan.remove(tmpHtmlPath.c_str());
+    if (Storage.exists(tmpHtmlPath.c_str())) {
+      Storage.remove(tmpHtmlPath.c_str());
    }

    FsFile tmpHtml;
-    if (!SdMan.openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) {
+    if (!Storage.openFileForWrite("SCT", tmpHtmlPath, tmpHtml)) {
      continue;
    }
    success = epub->readItemContentsToStream(localPath, tmpHtml, 1024);
@@ -160,8 +160,8 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
    tmpHtml.close();

    // If streaming failed, remove the incomplete file immediately
-    if (!success && SdMan.exists(tmpHtmlPath.c_str())) {
-      SdMan.remove(tmpHtmlPath.c_str());
+    if (!success && Storage.exists(tmpHtmlPath.c_str())) {
+      Storage.remove(tmpHtmlPath.c_str());
      Serial.printf("[%lu] [SCT] Removed incomplete temp file after failed attempt\n", millis());
    }
  }
@@ -173,7 +173,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c

  Serial.printf("[%lu] [SCT] Streamed temp HTML to %s (%d bytes)\n", millis(), tmpHtmlPath.c_str(), fileSize);

-  if (!SdMan.openFileForWrite("SCT", filePath, file)) {
+  if (!Storage.openFileForWrite("SCT", filePath, file)) {
    return false;
  }
  writeSectionFileHeader(fontId, lineCompression, extraParagraphSpacing, paragraphAlignment, viewportWidth,
@@ -188,11 +188,11 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
  Hyphenator::setPreferredLanguage(epub->getLanguage());
  success = visitor.parseAndBuildPages();

-  SdMan.remove(tmpHtmlPath.c_str());
+  Storage.remove(tmpHtmlPath.c_str());
  if (!success) {
    Serial.printf("[%lu] [SCT] Failed to parse XML and build pages\n", millis());
    file.close();
-    SdMan.remove(filePath.c_str());
+    Storage.remove(filePath.c_str());
    return false;
  }

@@ -210,7 +210,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
  if (hasFailedLutRecords) {
    Serial.printf("[%lu] [SCT] Failed to write LUT due to invalid page positions\n", millis());
    file.close();
-    SdMan.remove(filePath.c_str());
+    Storage.remove(filePath.c_str());
    return false;
  }

@@ -223,7 +223,7 @@ bool Section::createSectionFile(const int fontId, const float lineCompression, c
 }

 std::unique_ptr<Page> Section::loadPageFromSectionFile() {
-  if (!SdMan.openFileForRead("SCT", filePath, file)) {
+  if (!Storage.openFileForRead("SCT", filePath, file)) {
    return nullptr;
  }

--- a/lib/Epub/Epub/blocks/TextBlock.h
+++ b/lib/Epub/Epub/blocks/TextBlock.h
@@ -1,6 +1,6 @@
 #pragma once
 #include <EpdFontFamily.h>
-#include <SdFat.h>
+#include <HalStorage.h>

 #include <list>
 #include <memory>
--- a/lib/Epub/Epub/css/CssParser.h
+++ b/lib/Epub/Epub/css/CssParser.h
@@ -1,6 +1,6 @@
 #pragma once

-#include <SdFat.h>
+#include <HalStorage.h>

 #include <string>
 #include <unordered_map>
--- a/lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp
+++ b/lib/Epub/Epub/parsers/ChapterHtmlSlimParser.cpp
@@ -1,8 +1,8 @@
 #include "ChapterHtmlSlimParser.h"

 #include <GfxRenderer.h>
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <expat.h>

 #include "../Page.h"
@@ -482,7 +482,7 @@ bool ChapterHtmlSlimParser::parseAndBuildPages() {
  }

  FsFile file;
-  if (!SdMan.openFileForRead("EHP", filepath, file)) {
+  if (!Storage.openFileForRead("EHP", filepath, file)) {
    XML_ParserFree(parser);
    return false;
  }
--- a/lib/Epub/Epub/parsers/ContentOpfParser.cpp
+++ b/lib/Epub/Epub/parsers/ContentOpfParser.cpp
@@ -36,8 +36,8 @@ ContentOpfParser::~ContentOpfParser() {
  if (tempItemStore) {
    tempItemStore.close();
  }
-  if (SdMan.exists((cachePath + itemCacheFile).c_str())) {
-    SdMan.remove((cachePath + itemCacheFile).c_str());
+  if (Storage.exists((cachePath + itemCacheFile).c_str())) {
+    Storage.remove((cachePath + itemCacheFile).c_str());
  }
  itemIndex.clear();
  itemIndex.shrink_to_fit();
@@ -118,7 +118,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name

  if (self->state == IN_PACKAGE && (strcmp(name, "manifest") == 0 || strcmp(name, "opf:manifest") == 0)) {
    self->state = IN_MANIFEST;
-    if (!SdMan.openFileForWrite("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
+    if (!Storage.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());
@@ -128,7 +128,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name

  if (self->state == IN_PACKAGE && (strcmp(name, "spine") == 0 || strcmp(name, "opf:spine") == 0)) {
    self->state = IN_SPINE;
-    if (!SdMan.openFileForRead("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
+    if (!Storage.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());
@@ -149,7 +149,7 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
    self->state = IN_GUIDE;
    // TODO Remove print
    Serial.printf("[%lu] [COF] Entering guide state.\n", millis());
-    if (!SdMan.openFileForRead("COF", self->cachePath + itemCacheFile, self->tempItemStore)) {
+    if (!Storage.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());
@@ -232,6 +232,14 @@ void XMLCALL ContentOpfParser::startElement(void* userData, const XML_Char* name
        Serial.printf("[%lu] [COF] Found EPUB 3 nav document: %s\n", millis(), href.c_str());
      }
    }
+
+    // EPUB 3: Check for cover image (properties contains "cover-image")
+    if (!properties.empty() && self->coverItemHref.empty()) {
+      if (properties == "cover-image" || properties.find("cover-image ") == 0 ||
+          properties.find(" cover-image") != std::string::npos) {
+        self->coverItemHref = href;
+      }
+    }
    return;
  }

--- a/lib/GfxRenderer/Bitmap.h
+++ b/lib/GfxRenderer/Bitmap.h
@@ -1,6 +1,6 @@
 #pragma once

-#include <SdFat.h>
+#include <HalStorage.h>

 #include <cstdint>

--- a/lib/GfxRenderer/BitmapHelpers.cpp
+++ b/lib/GfxRenderer/BitmapHelpers.cpp
@@ -104,3 +104,20 @@ uint8_t quantize1bit(int gray, int x, int y) {
  const int adjustedThreshold = 128 + ((threshold - 128) / 2);  // Range: 64-192
  return (gray >= adjustedThreshold) ? 1 : 0;
 }
+
+// Noise dithering for gradient fills - always uses hash-based noise regardless of global dithering config.
+// Produces smooth-looking gradients on the 4-level e-ink display.
+uint8_t quantizeNoiseDither(int gray, int x, int y) {
+  uint32_t hash = static_cast<uint32_t>(x) * 374761393u + static_cast<uint32_t>(y) * 668265263u;
+  hash = (hash ^ (hash >> 13)) * 1274126177u;
+  const int threshold = static_cast<int>(hash >> 24);
+
+  const int scaled = gray * 3;
+  if (scaled < 255) {
+    return (scaled + threshold >= 255) ? 1 : 0;
+  } else if (scaled < 510) {
+    return ((scaled - 255) + threshold >= 255) ? 2 : 1;
+  } else {
+    return ((scaled - 510) + threshold >= 255) ? 3 : 2;
+  }
+}
--- a/lib/GfxRenderer/BitmapHelpers.h
+++ b/lib/GfxRenderer/BitmapHelpers.h
@@ -7,6 +7,7 @@ uint8_t quantize(int gray, int x, int y);
 uint8_t quantizeSimple(int gray);
 uint8_t quantize1bit(int gray, int x, int y);
 int adjustPixel(int gray);
+uint8_t quantizeNoiseDither(int gray, int x, int y);

 // 1-bit Atkinson dithering - better quality than noise dithering for thumbnails
 // Error distribution pattern (same as 2-bit but quantizes to 2 levels):
--- a/lib/GfxRenderer/GfxRenderer.cpp
+++ b/lib/GfxRenderer/GfxRenderer.cpp
@@ -72,6 +72,16 @@ void GfxRenderer::drawPixel(const int x, const int y, const bool state) const {
  }
 }

+void GfxRenderer::drawPixelGray(const int x, const int y, const uint8_t val2bit) const {
+  if (renderMode == BW && val2bit < 3) {
+    drawPixel(x, y);
+  } else if (renderMode == GRAYSCALE_MSB && (val2bit == 1 || val2bit == 2)) {
+    drawPixel(x, y, false);
+  } else if (renderMode == GRAYSCALE_LSB && val2bit == 1) {
+    drawPixel(x, y, false);
+  }
+}
+
 int GfxRenderer::getTextWidth(const int fontId, const char* text, const EpdFontFamily::Style style) const {
  if (fontMap.count(fontId) == 0) {
    Serial.printf("[%lu] [GFX] Font %d not found\n", millis(), fontId);
@@ -422,12 +432,20 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
  Serial.printf("[%lu] [GFX] Cropping %dx%d by %dx%d pix, is %s\n", millis(), bitmap.getWidth(), bitmap.getHeight(),
                cropPixX, cropPixY, bitmap.isTopDown() ? "top-down" : "bottom-up");

-  if (maxWidth > 0 && (1.0f - cropX) * bitmap.getWidth() > maxWidth) {
-    scale = static_cast<float>(maxWidth) / static_cast<float>((1.0f - cropX) * bitmap.getWidth());
+  const float effectiveWidth = (1.0f - cropX) * bitmap.getWidth();
+  const float effectiveHeight = (1.0f - cropY) * bitmap.getHeight();
+
+  // Calculate scale factor: supports both downscaling and upscaling when both constraints are provided
+  if (maxWidth > 0 && maxHeight > 0) {
+    const float scaleX = static_cast<float>(maxWidth) / effectiveWidth;
+    const float scaleY = static_cast<float>(maxHeight) / effectiveHeight;
+    scale = std::min(scaleX, scaleY);
+    isScaled = (scale < 0.999f || scale > 1.001f);
+  } else if (maxWidth > 0 && effectiveWidth > static_cast<float>(maxWidth)) {
+    scale = static_cast<float>(maxWidth) / effectiveWidth;
    isScaled = true;
-  }
-  if (maxHeight > 0 && (1.0f - cropY) * bitmap.getHeight() > maxHeight) {
-    scale = std::min(scale, static_cast<float>(maxHeight) / static_cast<float>((1.0f - cropY) * bitmap.getHeight()));
+  } else if (maxHeight > 0 && effectiveHeight > static_cast<float>(maxHeight)) {
+    scale = static_cast<float>(maxHeight) / effectiveHeight;
    isScaled = true;
  }
  Serial.printf("[%lu] [GFX] Scaling by %f - %s\n", millis(), scale, isScaled ? "scaled" : "not scaled");
@@ -448,12 +466,17 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
  for (int bmpY = 0; bmpY < (bitmap.getHeight() - cropPixY); 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 = -cropPixY + (bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY);
+    const int logicalY = -cropPixY + (bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY);
+    int screenYStart, screenYEnd;
    if (isScaled) {
-      screenY = std::floor(screenY * scale);
+      screenYStart = static_cast<int>(std::floor(logicalY * scale)) + y;
+      screenYEnd = static_cast<int>(std::floor((logicalY + 1) * scale)) + y;
+    } else {
+      screenYStart = logicalY + y;
+      screenYEnd = screenYStart + 1;
    }
-    screenY += y;  // the offset should not be scaled
-    if (screenY >= getScreenHeight()) {
+
+    if (screenYStart >= getScreenHeight()) {
      break;
    }

@@ -464,7 +487,7 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
      return;
    }

-    if (screenY < 0) {
+    if (screenYEnd <= 0) {
      continue;
    }

@@ -473,27 +496,42 @@ void GfxRenderer::drawBitmap(const Bitmap& bitmap, const int x, const int y, con
      continue;
    }

+    const int syStart = std::max(screenYStart, 0);
+    const int syEnd = std::min(screenYEnd, getScreenHeight());
+
    for (int bmpX = cropPixX; bmpX < bitmap.getWidth() - cropPixX; bmpX++) {
-      int screenX = bmpX - cropPixX;
+      const int outX = bmpX - cropPixX;
+      int screenXStart, screenXEnd;
      if (isScaled) {
-        screenX = std::floor(screenX * scale);
+        screenXStart = static_cast<int>(std::floor(outX * scale)) + x;
+        screenXEnd = static_cast<int>(std::floor((outX + 1) * scale)) + x;
+      } else {
+        screenXStart = outX + x;
+        screenXEnd = screenXStart + 1;
      }
-      screenX += x;  // the offset should not be scaled
-      if (screenX >= getScreenWidth()) {
+
+      if (screenXStart >= getScreenWidth()) {
        break;
      }
-      if (screenX < 0) {
+      if (screenXEnd <= 0) {
        continue;
      }

      const uint8_t val = outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8)) & 0x3;

+      const int sxStart = std::max(screenXStart, 0);
+      const int sxEnd = std::min(screenXEnd, getScreenWidth());
+
+      for (int sy = syStart; sy < syEnd; sy++) {
+        for (int sx = sxStart; sx < sxEnd; sx++) {
          if (renderMode == BW && val < 3) {
-        drawPixel(screenX, screenY);
+            drawPixel(sx, sy);
          } else if (renderMode == GRAYSCALE_MSB && (val == 1 || val == 2)) {
-        drawPixel(screenX, screenY, false);
+            drawPixel(sx, sy, false);
          } else if (renderMode == GRAYSCALE_LSB && val == 1) {
-        drawPixel(screenX, screenY, false);
+            drawPixel(sx, sy, false);
+          }
+        }
      }
    }
  }
@@ -506,11 +544,16 @@ void GfxRenderer::drawBitmap1Bit(const Bitmap& bitmap, const int x, const int y,
                                 const int maxHeight) const {
  float scale = 1.0f;
  bool isScaled = false;
-  if (maxWidth > 0 && bitmap.getWidth() > maxWidth) {
+  // Calculate scale factor: supports both downscaling and upscaling when both constraints are provided
+  if (maxWidth > 0 && maxHeight > 0) {
+    const float scaleX = static_cast<float>(maxWidth) / static_cast<float>(bitmap.getWidth());
+    const float scaleY = static_cast<float>(maxHeight) / static_cast<float>(bitmap.getHeight());
+    scale = std::min(scaleX, scaleY);
+    isScaled = (scale < 0.999f || scale > 1.001f);
+  } else if (maxWidth > 0 && bitmap.getWidth() > maxWidth) {
    scale = static_cast<float>(maxWidth) / static_cast<float>(bitmap.getWidth());
    isScaled = true;
-  }
-  if (maxHeight > 0 && bitmap.getHeight() > maxHeight) {
+  } else if (maxHeight > 0 && bitmap.getHeight() > maxHeight) {
    scale = std::min(scale, static_cast<float>(maxHeight) / static_cast<float>(bitmap.getHeight()));
    isScaled = true;
  }
@@ -538,20 +581,37 @@ void GfxRenderer::drawBitmap1Bit(const Bitmap& bitmap, const int x, const int y,

    // Calculate screen Y based on whether BMP is top-down or bottom-up
    const int bmpYOffset = bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY;
-    int screenY = y + (isScaled ? static_cast<int>(std::floor(bmpYOffset * scale)) : bmpYOffset);
-    if (screenY >= getScreenHeight()) {
+    int screenYStart, screenYEnd;
+    if (isScaled) {
+      screenYStart = static_cast<int>(std::floor(bmpYOffset * scale)) + y;
+      screenYEnd = static_cast<int>(std::floor((bmpYOffset + 1) * scale)) + y;
+    } else {
+      screenYStart = bmpYOffset + y;
+      screenYEnd = screenYStart + 1;
+    }
+    if (screenYStart >= getScreenHeight()) {
      continue;  // Continue reading to keep row counter in sync
    }
-    if (screenY < 0) {
+    if (screenYEnd <= 0) {
      continue;
    }

+    const int syStart = std::max(screenYStart, 0);
+    const int syEnd = std::min(screenYEnd, getScreenHeight());
+
    for (int bmpX = 0; bmpX < bitmap.getWidth(); bmpX++) {
-      int screenX = x + (isScaled ? static_cast<int>(std::floor(bmpX * scale)) : bmpX);
-      if (screenX >= getScreenWidth()) {
+      int screenXStart, screenXEnd;
+      if (isScaled) {
+        screenXStart = static_cast<int>(std::floor(bmpX * scale)) + x;
+        screenXEnd = static_cast<int>(std::floor((bmpX + 1) * scale)) + x;
+      } else {
+        screenXStart = bmpX + x;
+        screenXEnd = screenXStart + 1;
+      }
+      if (screenXStart >= getScreenWidth()) {
        break;
      }
-      if (screenX < 0) {
+      if (screenXEnd <= 0) {
        continue;
      }

@@ -561,7 +621,13 @@ void GfxRenderer::drawBitmap1Bit(const Bitmap& bitmap, const int x, const int y,
      // For 1-bit source: 0 or 1 -> map to black (0,1,2) or white (3)
      // val < 3 means black pixel (draw it)
      if (val < 3) {
-        drawPixel(screenX, screenY, true);
+        const int sxStart = std::max(screenXStart, 0);
+        const int sxEnd = std::min(screenXEnd, getScreenWidth());
+        for (int sy = syStart; sy < syEnd; sy++) {
+          for (int sx = sxStart; sx < sxEnd; sx++) {
+            drawPixel(sx, sy, true);
+          }
+        }
      }
      // White pixels (val == 3) are not drawn (leave background)
    }
--- a/lib/GfxRenderer/GfxRenderer.h
+++ b/lib/GfxRenderer/GfxRenderer.h
@@ -77,6 +77,7 @@ class GfxRenderer {

  // Drawing
  void drawPixel(int x, int y, bool state = true) const;
+  void drawPixelGray(int x, int y, uint8_t val2bit) const;
  void drawLine(int x1, int y1, int x2, int y2, bool state = true) const;
  void drawLine(int x1, int y1, int x2, int y2, int lineWidth, bool state) const;
  void drawArc(int maxRadius, int cx, int cy, int xDir, int yDir, int lineWidth, bool state) const;
--- a/lib/JpegToBmpConverter/JpegToBmpConverter.cpp
+++ b/lib/JpegToBmpConverter/JpegToBmpConverter.cpp
@@ -1,7 +1,7 @@
 #include "JpegToBmpConverter.h"

+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SdFat.h>
 #include <picojpeg.h>

 #include <cstdio>
--- a/lib/KOReaderSync/KOReaderCredentialStore.cpp
+++ b/lib/KOReaderSync/KOReaderCredentialStore.cpp
@@ -1,8 +1,8 @@
 #include "KOReaderCredentialStore.h"

+#include <HalStorage.h>
 #include <HardwareSerial.h>
 #include <MD5Builder.h>
-#include <SDCardManager.h>
 #include <Serialization.h>

 // Initialize the static instance
@@ -32,10 +32,10 @@ void KOReaderCredentialStore::obfuscate(std::string& data) const {

 bool KOReaderCredentialStore::saveToFile() const {
  // Make sure the directory exists
-  SdMan.mkdir("/.crosspoint");
+  Storage.mkdir("/.crosspoint");

  FsFile file;
-  if (!SdMan.openFileForWrite("KRS", KOREADER_FILE, file)) {
+  if (!Storage.openFileForWrite("KRS", KOREADER_FILE, file)) {
    return false;
  }

@@ -64,7 +64,7 @@ bool KOReaderCredentialStore::saveToFile() const {

 bool KOReaderCredentialStore::loadFromFile() {
  FsFile file;
-  if (!SdMan.openFileForRead("KRS", KOREADER_FILE, file)) {
+  if (!Storage.openFileForRead("KRS", KOREADER_FILE, file)) {
    Serial.printf("[%lu] [KRS] No credentials file found\n", millis());
    return false;
  }
--- a/lib/KOReaderSync/KOReaderDocumentId.cpp
+++ b/lib/KOReaderSync/KOReaderDocumentId.cpp
@@ -1,8 +1,8 @@
 #include "KOReaderDocumentId.h"

+#include <HalStorage.h>
 #include <HardwareSerial.h>
 #include <MD5Builder.h>
-#include <SDCardManager.h>

 namespace {
 // Extract filename from path (everything after last '/')
@@ -43,7 +43,7 @@ size_t KOReaderDocumentId::getOffset(int i) {

 std::string KOReaderDocumentId::calculate(const std::string& filePath) {
  FsFile file;
-  if (!SdMan.openFileForRead("KODoc", filePath, file)) {
+  if (!Storage.openFileForRead("KODoc", filePath, file)) {
    Serial.printf("[%lu] [KODoc] Failed to open file: %s\n", millis(), filePath.c_str());
    return "";
  }
--- a/lib/Serialization/Serialization.h
+++ b/lib/Serialization/Serialization.h
@@ -1,5 +1,5 @@
 #pragma once
-#include <SdFat.h>
+#include <HalStorage.h>

 #include <iostream>

--- a/lib/Txt/Txt.cpp
+++ b/lib/Txt/Txt.cpp
@@ -15,13 +15,13 @@ bool Txt::load() {
    return true;
  }

-  if (!SdMan.exists(filepath.c_str())) {
+  if (!Storage.exists(filepath.c_str())) {
    Serial.printf("[%lu] [TXT] File does not exist: %s\n", millis(), filepath.c_str());
    return false;
  }

  FsFile file;
-  if (!SdMan.openFileForRead("TXT", filepath, file)) {
+  if (!Storage.openFileForRead("TXT", filepath, file)) {
    Serial.printf("[%lu] [TXT] Failed to open file: %s\n", millis(), filepath.c_str());
    return false;
  }
@@ -48,11 +48,11 @@ std::string Txt::getTitle() const {
 }

 void Txt::setupCacheDir() const {
-  if (!SdMan.exists(cacheBasePath.c_str())) {
-    SdMan.mkdir(cacheBasePath.c_str());
+  if (!Storage.exists(cacheBasePath.c_str())) {
+    Storage.mkdir(cacheBasePath.c_str());
  }
-  if (!SdMan.exists(cachePath.c_str())) {
-    SdMan.mkdir(cachePath.c_str());
+  if (!Storage.exists(cachePath.c_str())) {
+    Storage.mkdir(cachePath.c_str());
  }
 }

@@ -73,7 +73,7 @@ std::string Txt::findCoverImage() const {
  // First priority: look for image with same name as txt file (e.g., mybook.jpg)
  for (const auto& ext : extensions) {
    std::string coverPath = folder + "/" + baseName + ext;
-    if (SdMan.exists(coverPath.c_str())) {
+    if (Storage.exists(coverPath.c_str())) {
      Serial.printf("[%lu] [TXT] Found matching cover image: %s\n", millis(), coverPath.c_str());
      return coverPath;
    }
@@ -84,7 +84,7 @@ std::string Txt::findCoverImage() const {
  for (const auto& name : coverNames) {
    for (const auto& ext : extensions) {
      std::string coverPath = folder + "/" + std::string(name) + ext;
-      if (SdMan.exists(coverPath.c_str())) {
+      if (Storage.exists(coverPath.c_str())) {
        Serial.printf("[%lu] [TXT] Found fallback cover image: %s\n", millis(), coverPath.c_str());
        return coverPath;
      }
@@ -98,7 +98,7 @@ std::string Txt::getCoverBmpPath() const { return cachePath + "/cover.bmp"; }

 bool Txt::generateCoverBmp() const {
  // Already generated, return true
-  if (SdMan.exists(getCoverBmpPath().c_str())) {
+  if (Storage.exists(getCoverBmpPath().c_str())) {
    return true;
  }

@@ -122,10 +122,10 @@ bool Txt::generateCoverBmp() const {
    // Copy BMP file to cache
    Serial.printf("[%lu] [TXT] Copying BMP cover image to cache\n", millis());
    FsFile src, dst;
-    if (!SdMan.openFileForRead("TXT", coverImagePath, src)) {
+    if (!Storage.openFileForRead("TXT", coverImagePath, src)) {
      return false;
    }
-    if (!SdMan.openFileForWrite("TXT", getCoverBmpPath(), dst)) {
+    if (!Storage.openFileForWrite("TXT", getCoverBmpPath(), dst)) {
      src.close();
      return false;
    }
@@ -144,10 +144,10 @@ bool Txt::generateCoverBmp() const {
    // Convert JPG/JPEG to BMP (same approach as Epub)
    Serial.printf("[%lu] [TXT] Generating BMP from JPG cover image\n", millis());
    FsFile coverJpg, coverBmp;
-    if (!SdMan.openFileForRead("TXT", coverImagePath, coverJpg)) {
+    if (!Storage.openFileForRead("TXT", coverImagePath, coverJpg)) {
      return false;
    }
-    if (!SdMan.openFileForWrite("TXT", getCoverBmpPath(), coverBmp)) {
+    if (!Storage.openFileForWrite("TXT", getCoverBmpPath(), coverBmp)) {
      coverJpg.close();
      return false;
    }
@@ -157,7 +157,7 @@ bool Txt::generateCoverBmp() const {

    if (!success) {
      Serial.printf("[%lu] [TXT] Failed to generate BMP from JPG cover image\n", millis());
-      SdMan.remove(getCoverBmpPath().c_str());
+      Storage.remove(getCoverBmpPath().c_str());
    } else {
      Serial.printf("[%lu] [TXT] Generated BMP from JPG cover image\n", millis());
    }
@@ -175,7 +175,7 @@ bool Txt::readContent(uint8_t* buffer, size_t offset, size_t length) const {
  }

  FsFile file;
-  if (!SdMan.openFileForRead("TXT", filepath, file)) {
+  if (!Storage.openFileForRead("TXT", filepath, file)) {
    return false;
  }

--- a/lib/Txt/Txt.h
+++ b/lib/Txt/Txt.h
@@ -1,6 +1,6 @@
 #pragma once

-#include <SDCardManager.h>
+#include <HalStorage.h>

 #include <memory>
 #include <string>
--- a/lib/Xtc/Xtc.cpp
+++ b/lib/Xtc/Xtc.cpp
@@ -7,8 +7,8 @@

 #include "Xtc.h"

+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>

 bool Xtc::load() {
  Serial.printf("[%lu] [XTC] Loading XTC: %s\n", millis(), filepath.c_str());
@@ -30,12 +30,12 @@ bool Xtc::load() {
 }

 bool Xtc::clearCache() const {
-  if (!SdMan.exists(cachePath.c_str())) {
+  if (!Storage.exists(cachePath.c_str())) {
    Serial.printf("[%lu] [XTC] Cache does not exist, no action needed\n", millis());
    return true;
  }

-  if (!SdMan.removeDir(cachePath.c_str())) {
+  if (!Storage.removeDir(cachePath.c_str())) {
    Serial.printf("[%lu] [XTC] Failed to clear cache\n", millis());
    return false;
  }
@@ -45,17 +45,17 @@ bool Xtc::clearCache() const {
 }

 void Xtc::setupCacheDir() const {
-  if (SdMan.exists(cachePath.c_str())) {
+  if (Storage.exists(cachePath.c_str())) {
    return;
  }

  // Create directories recursively
  for (size_t i = 1; i < cachePath.length(); i++) {
    if (cachePath[i] == '/') {
-      SdMan.mkdir(cachePath.substr(0, i).c_str());
+      Storage.mkdir(cachePath.substr(0, i).c_str());
    }
  }
-  SdMan.mkdir(cachePath.c_str());
+  Storage.mkdir(cachePath.c_str());
 }

 std::string Xtc::getTitle() const {
@@ -114,7 +114,7 @@ std::string Xtc::getCoverBmpPath() const { return cachePath + "/cover.bmp"; }

 bool Xtc::generateCoverBmp() const {
  // Already generated
-  if (SdMan.exists(getCoverBmpPath().c_str())) {
+  if (Storage.exists(getCoverBmpPath().c_str())) {
    return true;
  }

@@ -166,7 +166,7 @@ bool Xtc::generateCoverBmp() const {

  // Create BMP file
  FsFile coverBmp;
-  if (!SdMan.openFileForWrite("XTC", getCoverBmpPath(), coverBmp)) {
+  if (!Storage.openFileForWrite("XTC", getCoverBmpPath(), coverBmp)) {
    Serial.printf("[%lu] [XTC] Failed to create cover BMP file\n", millis());
    free(pageBuffer);
    return false;
@@ -306,7 +306,7 @@ std::string Xtc::getThumbBmpPath(int height) const { return cachePath + "/thumb_

 bool Xtc::generateThumbBmp(int height) const {
  // Already generated
-  if (SdMan.exists(getThumbBmpPath(height).c_str())) {
+  if (Storage.exists(getThumbBmpPath(height).c_str())) {
    return true;
  }

@@ -348,8 +348,8 @@ bool Xtc::generateThumbBmp(int height) const {
    // Copy cover.bmp to thumb.bmp
    if (generateCoverBmp()) {
      FsFile src, dst;
-      if (SdMan.openFileForRead("XTC", getCoverBmpPath(), src)) {
-        if (SdMan.openFileForWrite("XTC", getThumbBmpPath(height), dst)) {
+      if (Storage.openFileForRead("XTC", getCoverBmpPath(), src)) {
+        if (Storage.openFileForWrite("XTC", getThumbBmpPath(height), dst)) {
          uint8_t buffer[512];
          while (src.available()) {
            size_t bytesRead = src.read(buffer, sizeof(buffer));
@@ -360,7 +360,7 @@ bool Xtc::generateThumbBmp(int height) const {
        src.close();
      }
      Serial.printf("[%lu] [XTC] Copied cover to thumb (no scaling needed)\n", millis());
-      return SdMan.exists(getThumbBmpPath(height).c_str());
+      return Storage.exists(getThumbBmpPath(height).c_str());
    }
    return false;
  }
@@ -394,7 +394,7 @@ bool Xtc::generateThumbBmp(int height) const {

  // Create thumbnail BMP file - use 1-bit format for fast home screen rendering (no gray passes)
  FsFile thumbBmp;
-  if (!SdMan.openFileForWrite("XTC", getThumbBmpPath(height), thumbBmp)) {
+  if (!Storage.openFileForWrite("XTC", getThumbBmpPath(height), thumbBmp)) {
    Serial.printf("[%lu] [XTC] Failed to create thumb BMP file\n", millis());
    free(pageBuffer);
    return false;
--- a/lib/Xtc/Xtc/XtcParser.cpp
+++ b/lib/Xtc/Xtc/XtcParser.cpp
@@ -8,8 +8,8 @@
 #include "XtcParser.h"

 #include <FsHelpers.h>
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>

 #include <cstring>

@@ -34,7 +34,7 @@ XtcError XtcParser::open(const char* filepath) {
  }

  // Open file
-  if (!SdMan.openFileForRead("XTC", filepath, m_file)) {
+  if (!Storage.openFileForRead("XTC", filepath, m_file)) {
    m_lastError = XtcError::FILE_NOT_FOUND;
    return m_lastError;
  }
@@ -444,7 +444,7 @@ XtcError XtcParser::loadPageStreaming(uint32_t pageIndex,

 bool XtcParser::isValidXtcFile(const char* filepath) {
  FsFile file;
-  if (!SdMan.openFileForRead("XTC", filepath, file)) {
+  if (!Storage.openFileForRead("XTC", filepath, file)) {
    return false;
  }

--- a/lib/Xtc/Xtc/XtcParser.h
+++ b/lib/Xtc/Xtc/XtcParser.h
@@ -7,7 +7,7 @@

 #pragma once

-#include <SdFat.h>
+#include <HalStorage.h>

 #include <functional>
 #include <memory>
--- a/lib/ZipFile/ZipFile.cpp
+++ b/lib/ZipFile/ZipFile.cpp
@@ -1,7 +1,7 @@
 #include "ZipFile.h"

+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <miniz.h>

 #include <algorithm>
@@ -279,7 +279,7 @@ bool ZipFile::loadZipDetails() {
 }

 bool ZipFile::open() {
-  if (!SdMan.openFileForRead("ZIP", filePath, file)) {
+  if (!Storage.openFileForRead("ZIP", filePath, file)) {
    return false;
  }
  return true;
--- a/lib/ZipFile/ZipFile.h
+++ b/lib/ZipFile/ZipFile.h
@@ -1,5 +1,5 @@
 #pragma once
-#include <SdFat.h>
+#include <HalStorage.h>

 #include <string>
 #include <unordered_map>
--- a/lib/hal/HalStorage.cpp
+++ b/lib/hal/HalStorage.cpp
@@ -0,0 +1,65 @@
+#include "HalStorage.h"
+
+#include <SDCardManager.h>
+
+#define SDCard SDCardManager::getInstance()
+
+HalStorage HalStorage::instance;
+
+HalStorage::HalStorage() {}
+
+bool HalStorage::begin() { return SDCard.begin(); }
+
+bool HalStorage::ready() const { return SDCard.ready(); }
+
+std::vector<String> HalStorage::listFiles(const char* path, int maxFiles) { return SDCard.listFiles(path, maxFiles); }
+
+String HalStorage::readFile(const char* path) { return SDCard.readFile(path); }
+
+bool HalStorage::readFileToStream(const char* path, Print& out, size_t chunkSize) {
+  return SDCard.readFileToStream(path, out, chunkSize);
+}
+
+size_t HalStorage::readFileToBuffer(const char* path, char* buffer, size_t bufferSize, size_t maxBytes) {
+  return SDCard.readFileToBuffer(path, buffer, bufferSize, maxBytes);
+}
+
+bool HalStorage::writeFile(const char* path, const String& content) { return SDCard.writeFile(path, content); }
+
+bool HalStorage::ensureDirectoryExists(const char* path) { return SDCard.ensureDirectoryExists(path); }
+
+FsFile HalStorage::open(const char* path, const oflag_t oflag) { return SDCard.open(path, oflag); }
+
+bool HalStorage::mkdir(const char* path, const bool pFlag) { return SDCard.mkdir(path, pFlag); }
+
+bool HalStorage::exists(const char* path) { return SDCard.exists(path); }
+
+bool HalStorage::remove(const char* path) { return SDCard.remove(path); }
+
+bool HalStorage::rmdir(const char* path) { return SDCard.rmdir(path); }
+
+bool HalStorage::openFileForRead(const char* moduleName, const char* path, FsFile& file) {
+  return SDCard.openFileForRead(moduleName, path, file);
+}
+
+bool HalStorage::openFileForRead(const char* moduleName, const std::string& path, FsFile& file) {
+  return openFileForRead(moduleName, path.c_str(), file);
+}
+
+bool HalStorage::openFileForRead(const char* moduleName, const String& path, FsFile& file) {
+  return openFileForRead(moduleName, path.c_str(), file);
+}
+
+bool HalStorage::openFileForWrite(const char* moduleName, const char* path, FsFile& file) {
+  return SDCard.openFileForWrite(moduleName, path, file);
+}
+
+bool HalStorage::openFileForWrite(const char* moduleName, const std::string& path, FsFile& file) {
+  return openFileForWrite(moduleName, path.c_str(), file);
+}
+
+bool HalStorage::openFileForWrite(const char* moduleName, const String& path, FsFile& file) {
+  return openFileForWrite(moduleName, path.c_str(), file);
+}
+
+bool HalStorage::removeDir(const char* path) { return SDCard.removeDir(path); }
--- a/lib/hal/HalStorage.h
+++ b/lib/hal/HalStorage.h
@@ -0,0 +1,54 @@
+#pragma once
+
+#include <SDCardManager.h>
+
+#include <vector>
+
+class HalStorage {
+ public:
+  HalStorage();
+  bool begin();
+  bool ready() const;
+  std::vector<String> listFiles(const char* path = "/", int maxFiles = 200);
+  // Read the entire file at `path` into a String. Returns empty string on failure.
+  String readFile(const char* path);
+  // Low-memory helpers:
+  // Stream the file contents to a `Print` (e.g. `Serial`, or any `Print`-derived object).
+  // Returns true on success, false on failure.
+  bool readFileToStream(const char* path, Print& out, size_t chunkSize = 256);
+  // Read up to `bufferSize-1` bytes into `buffer`, null-terminating it. Returns bytes read.
+  size_t readFileToBuffer(const char* path, char* buffer, size_t bufferSize, size_t maxBytes = 0);
+  // Write a string to `path` on the SD card. Overwrites existing file.
+  // Returns true on success.
+  bool writeFile(const char* path, const String& content);
+  // Ensure a directory exists, creating it if necessary. Returns true on success.
+  bool ensureDirectoryExists(const char* path);
+
+  FsFile open(const char* path, const oflag_t oflag = O_RDONLY);
+  bool mkdir(const char* path, const bool pFlag = true);
+  bool exists(const char* path);
+  bool remove(const char* path);
+  bool rmdir(const char* path);
+
+  bool openFileForRead(const char* moduleName, const char* path, FsFile& file);
+  bool openFileForRead(const char* moduleName, const std::string& path, FsFile& file);
+  bool openFileForRead(const char* moduleName, const String& path, FsFile& file);
+  bool openFileForWrite(const char* moduleName, const char* path, FsFile& file);
+  bool openFileForWrite(const char* moduleName, const std::string& path, FsFile& file);
+  bool openFileForWrite(const char* moduleName, const String& path, FsFile& file);
+  bool removeDir(const char* path);
+
+  static HalStorage& getInstance() { return instance; }
+
+ private:
+  static HalStorage instance;
+
+  bool initialized = false;
+};
+
+#define Storage HalStorage::getInstance()
+
+// Downstream code must use Storage instead of SdMan
+#ifdef SdMan
+#undef SdMan
+#endif
--- a/src/CrossPointSettings.cpp
+++ b/src/CrossPointSettings.cpp
@@ -1,7 +1,7 @@
 #include "CrossPointSettings.h"

+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <Serialization.h>

 #include <cstring>
@@ -22,7 +22,7 @@ void readAndValidate(FsFile& file, uint8_t& member, const uint8_t maxValue) {
 namespace {
 constexpr uint8_t SETTINGS_FILE_VERSION = 1;
 // Increment this when adding new persisted settings fields
-constexpr uint8_t SETTINGS_COUNT = 30;
+constexpr uint8_t SETTINGS_COUNT = 32;
 constexpr char SETTINGS_FILE[] = "/.crosspoint/settings.bin";

 // Validate front button mapping to ensure each hardware button is unique.
@@ -79,10 +79,10 @@ void applyLegacyFrontButtonLayout(CrossPointSettings& settings) {

 bool CrossPointSettings::saveToFile() const {
  // Make sure the directory exists
-  SdMan.mkdir("/.crosspoint");
+  Storage.mkdir("/.crosspoint");

  FsFile outputFile;
-  if (!SdMan.openFileForWrite("CPS", SETTINGS_FILE, outputFile)) {
+  if (!Storage.openFileForWrite("CPS", SETTINGS_FILE, outputFile)) {
    return false;
  }

@@ -118,6 +118,8 @@ bool CrossPointSettings::saveToFile() const {
  serialization::writePod(outputFile, frontButtonRight);
  serialization::writePod(outputFile, fadingFix);
  serialization::writePod(outputFile, embeddedStyle);
+  serialization::writePod(outputFile, sleepScreenLetterboxFill);
+  serialization::writePod(outputFile, sleepScreenGradientDir);
  // New fields added at end for backward compatibility
  outputFile.close();

@@ -127,7 +129,7 @@ bool CrossPointSettings::saveToFile() const {

 bool CrossPointSettings::loadFromFile() {
  FsFile inputFile;
-  if (!SdMan.openFileForRead("CPS", SETTINGS_FILE, inputFile)) {
+  if (!Storage.openFileForRead("CPS", SETTINGS_FILE, inputFile)) {
    return false;
  }

@@ -223,6 +225,10 @@ bool CrossPointSettings::loadFromFile() {
    if (++settingsRead >= fileSettingsCount) break;
    serialization::readPod(inputFile, embeddedStyle);
    if (++settingsRead >= fileSettingsCount) break;
+    readAndValidate(inputFile, sleepScreenLetterboxFill, SLEEP_SCREEN_LETTERBOX_FILL_COUNT);
+    if (++settingsRead >= fileSettingsCount) break;
+    readAndValidate(inputFile, sleepScreenGradientDir, SLEEP_SCREEN_GRADIENT_DIR_COUNT);
+    if (++settingsRead >= fileSettingsCount) break;
    // New fields added at end for backward compatibility
  } while (false);

--- a/src/CrossPointSettings.h
+++ b/src/CrossPointSettings.h
@@ -31,6 +31,14 @@ class CrossPointSettings {
    INVERTED_BLACK_AND_WHITE = 2,
    SLEEP_SCREEN_COVER_FILTER_COUNT
  };
+  enum SLEEP_SCREEN_LETTERBOX_FILL {
+    LETTERBOX_NONE = 0,
+    LETTERBOX_SOLID = 1,
+    LETTERBOX_BLENDED = 2,
+    LETTERBOX_GRADIENT = 3,
+    SLEEP_SCREEN_LETTERBOX_FILL_COUNT
+  };
+  enum SLEEP_SCREEN_GRADIENT_DIR { GRADIENT_TO_WHITE = 0, GRADIENT_TO_BLACK = 1, SLEEP_SCREEN_GRADIENT_DIR_COUNT };

  // Status bar display type enum
  enum STATUS_BAR_MODE {
@@ -125,6 +133,10 @@ class CrossPointSettings {
  uint8_t sleepScreenCoverMode = FIT;
  // Sleep screen cover filter
  uint8_t sleepScreenCoverFilter = NO_FILTER;
+  // Sleep screen letterbox fill mode (None / Solid / Blended / Gradient)
+  uint8_t sleepScreenLetterboxFill = LETTERBOX_GRADIENT;
+  // Sleep screen gradient direction (towards white or black)
+  uint8_t sleepScreenGradientDir = GRADIENT_TO_WHITE;
  // Status bar settings
  uint8_t statusBar = FULL;
  // Text rendering settings
--- a/src/CrossPointState.cpp
+++ b/src/CrossPointState.cpp
@@ -1,7 +1,7 @@
 #include "CrossPointState.h"

+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <Serialization.h>

 namespace {
@@ -13,7 +13,7 @@ CrossPointState CrossPointState::instance;

 bool CrossPointState::saveToFile() const {
  FsFile outputFile;
-  if (!SdMan.openFileForWrite("CPS", STATE_FILE, outputFile)) {
+  if (!Storage.openFileForWrite("CPS", STATE_FILE, outputFile)) {
    return false;
  }

@@ -28,7 +28,7 @@ bool CrossPointState::saveToFile() const {

 bool CrossPointState::loadFromFile() {
  FsFile inputFile;
-  if (!SdMan.openFileForRead("CPS", STATE_FILE, inputFile)) {
+  if (!Storage.openFileForRead("CPS", STATE_FILE, inputFile)) {
    return false;
  }

--- a/src/RecentBooksStore.cpp
+++ b/src/RecentBooksStore.cpp
@@ -1,8 +1,8 @@
 #include "RecentBooksStore.h"

 #include <Epub.h>
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <Serialization.h>
 #include <Xtc.h>

@@ -53,10 +53,10 @@ void RecentBooksStore::updateBook(const std::string& path, const std::string& ti

 bool RecentBooksStore::saveToFile() const {
  // Make sure the directory exists
-  SdMan.mkdir("/.crosspoint");
+  Storage.mkdir("/.crosspoint");

  FsFile outputFile;
-  if (!SdMan.openFileForWrite("RBS", RECENT_BOOKS_FILE, outputFile)) {
+  if (!Storage.openFileForWrite("RBS", RECENT_BOOKS_FILE, outputFile)) {
    return false;
  }

@@ -106,7 +106,7 @@ RecentBook RecentBooksStore::getDataFromBook(std::string path) const {

 bool RecentBooksStore::loadFromFile() {
  FsFile inputFile;
-  if (!SdMan.openFileForRead("RBS", RECENT_BOOKS_FILE, inputFile)) {
+  if (!Storage.openFileForRead("RBS", RECENT_BOOKS_FILE, inputFile)) {
    return false;
  }

--- a/src/SettingsList.h
+++ b/src/SettingsList.h
@@ -0,0 +1,105 @@
+#pragma once
+
+#include <vector>
+
+#include "CrossPointSettings.h"
+#include "KOReaderCredentialStore.h"
+#include "activities/settings/SettingsActivity.h"
+
+// Shared settings list used by both the device settings UI and the web settings API.
+// Each entry has a key (for JSON API) and category (for grouping).
+// ACTION-type entries and entries without a key are device-only.
+inline std::vector<SettingInfo> getSettingsList() {
+  return {
+      // --- Display ---
+      SettingInfo::Enum("Sleep Screen", &CrossPointSettings::sleepScreen,
+                        {"Dark", "Light", "Custom", "Cover", "None", "Cover + Custom"}, "sleepScreen", "Display"),
+      SettingInfo::Enum("Sleep Screen Cover Mode", &CrossPointSettings::sleepScreenCoverMode, {"Fit", "Crop"},
+                        "sleepScreenCoverMode", "Display"),
+      SettingInfo::Enum("Sleep Screen Cover Filter", &CrossPointSettings::sleepScreenCoverFilter,
+                        {"None", "Contrast", "Inverted"}, "sleepScreenCoverFilter", "Display"),
+      SettingInfo::Enum("Letterbox Fill", &CrossPointSettings::sleepScreenLetterboxFill,
+                        {"None", "Solid", "Blended", "Gradient"}, "sleepScreenLetterboxFill", "Display"),
+      SettingInfo::Enum("Gradient Direction", &CrossPointSettings::sleepScreenGradientDir, {"To White", "To Black"},
+                        "sleepScreenGradientDir", "Display"),
+      SettingInfo::Enum(
+          "Status Bar", &CrossPointSettings::statusBar,
+          {"None", "No Progress", "Full w/ Percentage", "Full w/ Book Bar", "Book Bar Only", "Full w/ Chapter Bar"},
+          "statusBar", "Display"),
+      SettingInfo::Enum("Hide Battery %", &CrossPointSettings::hideBatteryPercentage, {"Never", "In Reader", "Always"},
+                        "hideBatteryPercentage", "Display"),
+      SettingInfo::Enum("Refresh Frequency", &CrossPointSettings::refreshFrequency,
+                        {"1 page", "5 pages", "10 pages", "15 pages", "30 pages"}, "refreshFrequency", "Display"),
+      SettingInfo::Enum("UI Theme", &CrossPointSettings::uiTheme, {"Classic", "Lyra"}, "uiTheme", "Display"),
+      SettingInfo::Toggle("Sunlight Fading Fix", &CrossPointSettings::fadingFix, "fadingFix", "Display"),
+
+      // --- Reader ---
+      SettingInfo::Enum("Font Family", &CrossPointSettings::fontFamily, {"Bookerly", "Noto Sans", "Open Dyslexic"},
+                        "fontFamily", "Reader"),
+      SettingInfo::Enum("Font Size", &CrossPointSettings::fontSize, {"Small", "Medium", "Large", "X Large"}, "fontSize",
+                        "Reader"),
+      SettingInfo::Enum("Line Spacing", &CrossPointSettings::lineSpacing, {"Tight", "Normal", "Wide"}, "lineSpacing",
+                        "Reader"),
+      SettingInfo::Value("Screen Margin", &CrossPointSettings::screenMargin, {5, 40, 5}, "screenMargin", "Reader"),
+      SettingInfo::Enum("Paragraph Alignment", &CrossPointSettings::paragraphAlignment,
+                        {"Justify", "Left", "Center", "Right", "Book's Style"}, "paragraphAlignment", "Reader"),
+      SettingInfo::Toggle("Book's Embedded Style", &CrossPointSettings::embeddedStyle, "embeddedStyle", "Reader"),
+      SettingInfo::Toggle("Hyphenation", &CrossPointSettings::hyphenationEnabled, "hyphenationEnabled", "Reader"),
+      SettingInfo::Enum("Reading Orientation", &CrossPointSettings::orientation,
+                        {"Portrait", "Landscape CW", "Inverted", "Landscape CCW"}, "orientation", "Reader"),
+      SettingInfo::Toggle("Extra Paragraph Spacing", &CrossPointSettings::extraParagraphSpacing,
+                          "extraParagraphSpacing", "Reader"),
+      SettingInfo::Toggle("Text Anti-Aliasing", &CrossPointSettings::textAntiAliasing, "textAntiAliasing", "Reader"),
+
+      // --- Controls ---
+      SettingInfo::Enum("Side Button Layout (reader)", &CrossPointSettings::sideButtonLayout,
+                        {"Prev, Next", "Next, Prev"}, "sideButtonLayout", "Controls"),
+      SettingInfo::Toggle("Long-press Chapter Skip", &CrossPointSettings::longPressChapterSkip, "longPressChapterSkip",
+                          "Controls"),
+      SettingInfo::Enum("Short Power Button Click", &CrossPointSettings::shortPwrBtn, {"Ignore", "Sleep", "Page Turn"},
+                        "shortPwrBtn", "Controls"),
+
+      // --- System ---
+      SettingInfo::Enum("Time to Sleep", &CrossPointSettings::sleepTimeout,
+                        {"1 min", "5 min", "10 min", "15 min", "30 min"}, "sleepTimeout", "System"),
+
+      // --- KOReader Sync (web-only, uses KOReaderCredentialStore) ---
+      SettingInfo::DynamicString(
+          "KOReader Username", [] { return KOREADER_STORE.getUsername(); },
+          [](const std::string& v) {
+            KOREADER_STORE.setCredentials(v, KOREADER_STORE.getPassword());
+            KOREADER_STORE.saveToFile();
+          },
+          "koUsername", "KOReader Sync"),
+      SettingInfo::DynamicString(
+          "KOReader Password", [] { return KOREADER_STORE.getPassword(); },
+          [](const std::string& v) {
+            KOREADER_STORE.setCredentials(KOREADER_STORE.getUsername(), v);
+            KOREADER_STORE.saveToFile();
+          },
+          "koPassword", "KOReader Sync"),
+      SettingInfo::DynamicString(
+          "Sync Server URL", [] { return KOREADER_STORE.getServerUrl(); },
+          [](const std::string& v) {
+            KOREADER_STORE.setServerUrl(v);
+            KOREADER_STORE.saveToFile();
+          },
+          "koServerUrl", "KOReader Sync"),
+      SettingInfo::DynamicEnum(
+          "Document Matching", {"Filename", "Binary"},
+          [] { return static_cast<uint8_t>(KOREADER_STORE.getMatchMethod()); },
+          [](uint8_t v) {
+            KOREADER_STORE.setMatchMethod(static_cast<DocumentMatchMethod>(v));
+            KOREADER_STORE.saveToFile();
+          },
+          "koMatchMethod", "KOReader Sync"),
+
+      // --- OPDS Browser (web-only, uses CrossPointSettings char arrays) ---
+      SettingInfo::String("OPDS Server URL", SETTINGS.opdsServerUrl, sizeof(SETTINGS.opdsServerUrl), "opdsServerUrl",
+                          "OPDS Browser"),
+      SettingInfo::String("OPDS Username", SETTINGS.opdsUsername, sizeof(SETTINGS.opdsUsername), "opdsUsername",
+                          "OPDS Browser"),
+      SettingInfo::String("OPDS Password", SETTINGS.opdsPassword, sizeof(SETTINGS.opdsPassword), "opdsPassword",
+                          "OPDS Browser"),
+  };
+}
--- a/src/WifiCredentialStore.cpp
+++ b/src/WifiCredentialStore.cpp
@@ -1,7 +1,7 @@
 #include "WifiCredentialStore.h"

+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>
 #include <Serialization.h>

 // Initialize the static instance
@@ -29,10 +29,10 @@ void WifiCredentialStore::obfuscate(std::string& data) const {

 bool WifiCredentialStore::saveToFile() const {
  // Make sure the directory exists
-  SdMan.mkdir("/.crosspoint");
+  Storage.mkdir("/.crosspoint");

  FsFile file;
-  if (!SdMan.openFileForWrite("WCS", WIFI_FILE, file)) {
+  if (!Storage.openFileForWrite("WCS", WIFI_FILE, file)) {
    return false;
  }

@@ -60,7 +60,7 @@ bool WifiCredentialStore::saveToFile() const {

 bool WifiCredentialStore::loadFromFile() {
  FsFile file;
-  if (!SdMan.openFileForRead("WCS", WIFI_FILE, file)) {
+  if (!Storage.openFileForRead("WCS", WIFI_FILE, file)) {
    return false;
  }

--- a/src/activities/boot_sleep/SleepActivity.cpp
+++ b/src/activities/boot_sleep/SleepActivity.cpp
@@ -1,11 +1,15 @@
 #include "SleepActivity.h"

+#include <BitmapHelpers.h>
 #include <Epub.h>
 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
+#include <Serialization.h>
 #include <Txt.h>
 #include <Xtc.h>

+#include <algorithm>
+
 #include "CrossPointSettings.h"
 #include "CrossPointState.h"
 #include "components/UITheme.h"
@@ -13,6 +17,364 @@
 #include "images/Logo120.h"
 #include "util/StringUtils.h"

+namespace {
+
+// Number of source pixels along the image edge to average for the gradient color
+constexpr int EDGE_SAMPLE_DEPTH = 20;
+
+// Map a 2-bit quantized pixel value to an 8-bit grayscale value
+constexpr uint8_t val2bitToGray(uint8_t val2bit) { return val2bit * 85; }
+
+// Edge gradient data produced by sampleBitmapEdges and consumed by drawLetterboxGradients.
+// edgeA is the "first" edge (top or left), edgeB is the "second" edge (bottom or right).
+struct LetterboxGradientData {
+  uint8_t* edgeA = nullptr;
+  uint8_t* edgeB = nullptr;
+  int edgeCount = 0;
+  int letterboxA = 0;       // pixel size of the first letterbox area (top or left)
+  int letterboxB = 0;       // pixel size of the second letterbox area (bottom or right)
+  bool horizontal = false;  // true = top/bottom letterbox, false = left/right
+
+  void free() {
+    ::free(edgeA);
+    ::free(edgeB);
+    edgeA = nullptr;
+    edgeB = nullptr;
+  }
+};
+
+// Binary cache version for edge data files
+constexpr uint8_t EDGE_CACHE_VERSION = 1;
+
+// Load cached edge data from a binary file. Returns true if the cache was valid and loaded successfully.
+// Validates cache version and screen dimensions to detect stale data.
+bool loadEdgeCache(const std::string& path, int screenWidth, int screenHeight, LetterboxGradientData& data) {
+  FsFile file;
+  if (!Storage.openFileForRead("SLP", path, file)) return false;
+
+  uint8_t version;
+  serialization::readPod(file, version);
+  if (version != EDGE_CACHE_VERSION) {
+    file.close();
+    return false;
+  }
+
+  uint16_t cachedW, cachedH;
+  serialization::readPod(file, cachedW);
+  serialization::readPod(file, cachedH);
+  if (cachedW != static_cast<uint16_t>(screenWidth) || cachedH != static_cast<uint16_t>(screenHeight)) {
+    file.close();
+    return false;
+  }
+
+  uint8_t horizontal;
+  serialization::readPod(file, horizontal);
+  data.horizontal = (horizontal != 0);
+
+  uint16_t edgeCount;
+  serialization::readPod(file, edgeCount);
+  data.edgeCount = edgeCount;
+
+  int16_t lbA, lbB;
+  serialization::readPod(file, lbA);
+  serialization::readPod(file, lbB);
+  data.letterboxA = lbA;
+  data.letterboxB = lbB;
+
+  if (edgeCount == 0 || edgeCount > 2048) {
+    file.close();
+    return false;
+  }
+
+  data.edgeA = static_cast<uint8_t*>(malloc(edgeCount));
+  data.edgeB = static_cast<uint8_t*>(malloc(edgeCount));
+  if (!data.edgeA || !data.edgeB) {
+    data.free();
+    file.close();
+    return false;
+  }
+
+  if (file.read(data.edgeA, edgeCount) != static_cast<int>(edgeCount) ||
+      file.read(data.edgeB, edgeCount) != static_cast<int>(edgeCount)) {
+    data.free();
+    file.close();
+    return false;
+  }
+
+  file.close();
+  Serial.printf("[%lu] [SLP] Loaded edge cache from %s (%d edges)\n", millis(), path.c_str(), edgeCount);
+  return true;
+}
+
+// Save edge data to a binary cache file for reuse on subsequent sleep screens.
+bool saveEdgeCache(const std::string& path, int screenWidth, int screenHeight, const LetterboxGradientData& data) {
+  if (!data.edgeA || !data.edgeB || data.edgeCount <= 0) return false;
+
+  FsFile file;
+  if (!Storage.openFileForWrite("SLP", path, file)) return false;
+
+  serialization::writePod(file, EDGE_CACHE_VERSION);
+  serialization::writePod(file, static_cast<uint16_t>(screenWidth));
+  serialization::writePod(file, static_cast<uint16_t>(screenHeight));
+  serialization::writePod(file, static_cast<uint8_t>(data.horizontal ? 1 : 0));
+  serialization::writePod(file, static_cast<uint16_t>(data.edgeCount));
+  serialization::writePod(file, static_cast<int16_t>(data.letterboxA));
+  serialization::writePod(file, static_cast<int16_t>(data.letterboxB));
+  file.write(data.edgeA, data.edgeCount);
+  file.write(data.edgeB, data.edgeCount);
+  file.close();
+
+  Serial.printf("[%lu] [SLP] Saved edge cache to %s (%d edges)\n", millis(), path.c_str(), data.edgeCount);
+  return true;
+}
+
+// Read the bitmap once to sample the first/last EDGE_SAMPLE_DEPTH rows or columns.
+// Returns edge color arrays in source pixel resolution.  Caller must call data.free() when done.
+// After sampling the bitmap is rewound via rewindToData().
+LetterboxGradientData sampleBitmapEdges(const Bitmap& bitmap, int imgX, int imgY, int pageWidth, int pageHeight,
+                                        float scale, float cropX, float cropY) {
+  LetterboxGradientData data;
+
+  const int cropPixX = static_cast<int>(std::floor(bitmap.getWidth() * cropX / 2.0f));
+  const int cropPixY = static_cast<int>(std::floor(bitmap.getHeight() * cropY / 2.0f));
+  const int visibleWidth = bitmap.getWidth() - 2 * cropPixX;
+  const int visibleHeight = bitmap.getHeight() - 2 * cropPixY;
+
+  if (visibleWidth <= 0 || visibleHeight <= 0) return data;
+
+  const int 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) {
+    ::free(outputRow);
+    ::free(rowBytes);
+    return data;
+  }
+
+  if (imgY > 0) {
+    // Top/bottom letterboxing -- sample per-column averages of first/last N rows
+    data.horizontal = true;
+    data.edgeCount = visibleWidth;
+    const int scaledHeight = static_cast<int>(std::round(static_cast<float>(visibleHeight) * scale));
+    data.letterboxA = imgY;
+    data.letterboxB = pageHeight - imgY - scaledHeight;
+    if (data.letterboxB < 0) data.letterboxB = 0;
+
+    const int sampleRows = std::min(EDGE_SAMPLE_DEPTH, visibleHeight);
+
+    auto* accumTop = static_cast<uint32_t*>(calloc(visibleWidth, sizeof(uint32_t)));
+    auto* accumBot = static_cast<uint32_t*>(calloc(visibleWidth, sizeof(uint32_t)));
+    data.edgeA = static_cast<uint8_t*>(malloc(visibleWidth));
+    data.edgeB = static_cast<uint8_t*>(malloc(visibleWidth));
+
+    if (!accumTop || !accumBot || !data.edgeA || !data.edgeB) {
+      ::free(accumTop);
+      ::free(accumBot);
+      data.free();
+      ::free(outputRow);
+      ::free(rowBytes);
+      return data;
+    }
+
+    for (int bmpY = 0; bmpY < bitmap.getHeight(); bmpY++) {
+      if (bitmap.readNextRow(outputRow, rowBytes) != BmpReaderError::Ok) break;
+      const int logicalY = bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY;
+      if (logicalY < cropPixY || logicalY >= bitmap.getHeight() - cropPixY) continue;
+      const int outY = logicalY - cropPixY;
+
+      const bool inTop = (outY < sampleRows);
+      const bool inBot = (outY >= visibleHeight - sampleRows);
+      if (!inTop && !inBot) continue;
+
+      for (int bmpX = cropPixX; bmpX < bitmap.getWidth() - cropPixX; bmpX++) {
+        const int outX = bmpX - cropPixX;
+        const uint8_t val = (outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8))) & 0x3;
+        const uint8_t gray = val2bitToGray(val);
+        if (inTop) accumTop[outX] += gray;
+        if (inBot) accumBot[outX] += gray;
+      }
+    }
+
+    for (int i = 0; i < visibleWidth; i++) {
+      data.edgeA[i] = static_cast<uint8_t>(accumTop[i] / sampleRows);
+      data.edgeB[i] = static_cast<uint8_t>(accumBot[i] / sampleRows);
+    }
+    ::free(accumTop);
+    ::free(accumBot);
+
+  } else if (imgX > 0) {
+    // Left/right letterboxing -- sample per-row averages of first/last N columns
+    data.horizontal = false;
+    data.edgeCount = visibleHeight;
+    const int scaledWidth = static_cast<int>(std::round(static_cast<float>(visibleWidth) * scale));
+    data.letterboxA = imgX;
+    data.letterboxB = pageWidth - imgX - scaledWidth;
+    if (data.letterboxB < 0) data.letterboxB = 0;
+
+    const int sampleCols = std::min(EDGE_SAMPLE_DEPTH, visibleWidth);
+
+    auto* accumLeft = static_cast<uint32_t*>(calloc(visibleHeight, sizeof(uint32_t)));
+    auto* accumRight = static_cast<uint32_t*>(calloc(visibleHeight, sizeof(uint32_t)));
+    data.edgeA = static_cast<uint8_t*>(malloc(visibleHeight));
+    data.edgeB = static_cast<uint8_t*>(malloc(visibleHeight));
+
+    if (!accumLeft || !accumRight || !data.edgeA || !data.edgeB) {
+      ::free(accumLeft);
+      ::free(accumRight);
+      data.free();
+      ::free(outputRow);
+      ::free(rowBytes);
+      return data;
+    }
+
+    for (int bmpY = 0; bmpY < bitmap.getHeight(); bmpY++) {
+      if (bitmap.readNextRow(outputRow, rowBytes) != BmpReaderError::Ok) break;
+      const int logicalY = bitmap.isTopDown() ? bmpY : bitmap.getHeight() - 1 - bmpY;
+      if (logicalY < cropPixY || logicalY >= bitmap.getHeight() - cropPixY) continue;
+      const int outY = logicalY - cropPixY;
+
+      // Sample left edge columns
+      for (int bmpX = cropPixX; bmpX < cropPixX + sampleCols; bmpX++) {
+        const uint8_t val = (outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8))) & 0x3;
+        accumLeft[outY] += val2bitToGray(val);
+      }
+      // Sample right edge columns
+      for (int bmpX = bitmap.getWidth() - cropPixX - sampleCols; bmpX < bitmap.getWidth() - cropPixX; bmpX++) {
+        const uint8_t val = (outputRow[bmpX / 4] >> (6 - ((bmpX * 2) % 8))) & 0x3;
+        accumRight[outY] += val2bitToGray(val);
+      }
+    }
+
+    for (int i = 0; i < visibleHeight; i++) {
+      data.edgeA[i] = static_cast<uint8_t>(accumLeft[i] / sampleCols);
+      data.edgeB[i] = static_cast<uint8_t>(accumRight[i] / sampleCols);
+    }
+    ::free(accumLeft);
+    ::free(accumRight);
+  }
+
+  ::free(outputRow);
+  ::free(rowBytes);
+  bitmap.rewindToData();
+  return data;
+}
+
+// Draw dithered fills in the letterbox areas using the sampled edge colors.
+// fillMode selects the fill algorithm: SOLID (single dominant shade), BLENDED (per-pixel edge color),
+// or GRADIENT (per-pixel edge color interpolated toward targetColor).
+// targetColor is the color the gradient fades toward (255=white, 0=black); only used in GRADIENT mode.
+// Must be called once per render pass (BW, GRAYSCALE_LSB, GRAYSCALE_MSB).
+void drawLetterboxFill(GfxRenderer& renderer, const LetterboxGradientData& data, float scale, uint8_t fillMode,
+                       int targetColor) {
+  if (!data.edgeA || !data.edgeB || data.edgeCount <= 0) return;
+
+  const bool isSolid = (fillMode == CrossPointSettings::SLEEP_SCREEN_LETTERBOX_FILL::LETTERBOX_SOLID);
+  const bool isGradient = (fillMode == CrossPointSettings::SLEEP_SCREEN_LETTERBOX_FILL::LETTERBOX_GRADIENT);
+
+  // For SOLID mode, compute the dominant (average) shade for each edge once
+  uint8_t solidColorA = 0, solidColorB = 0;
+  if (isSolid) {
+    uint32_t sumA = 0, sumB = 0;
+    for (int i = 0; i < data.edgeCount; i++) {
+      sumA += data.edgeA[i];
+      sumB += data.edgeB[i];
+    }
+    solidColorA = static_cast<uint8_t>(sumA / data.edgeCount);
+    solidColorB = static_cast<uint8_t>(sumB / data.edgeCount);
+  }
+
+  // Helper: compute gray value for a pixel given the edge color and interpolation factor t (0..1)
+  // GRADIENT interpolates from edgeColor toward targetColor; SOLID and BLENDED return edgeColor directly.
+  auto computeGray = [&](int edgeColor, float t) -> int {
+    if (isGradient) return edgeColor + static_cast<int>(static_cast<float>(targetColor - edgeColor) * t);
+    return edgeColor;
+  };
+
+  if (data.horizontal) {
+    // Top letterbox
+    if (data.letterboxA > 0) {
+      const int imgTopY = data.letterboxA;
+      for (int screenY = 0; screenY < imgTopY; screenY++) {
+        const float t = static_cast<float>(imgTopY - screenY) / static_cast<float>(imgTopY);
+        for (int screenX = 0; screenX < renderer.getScreenWidth(); screenX++) {
+          int edgeColor;
+          if (isSolid) {
+            edgeColor = solidColorA;
+          } else {
+            int srcCol = static_cast<int>(screenX / scale);
+            srcCol = std::max(0, std::min(srcCol, data.edgeCount - 1));
+            edgeColor = data.edgeA[srcCol];
+          }
+          const int gray = computeGray(edgeColor, t);
+          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+        }
+      }
+    }
+
+    // Bottom letterbox
+    if (data.letterboxB > 0) {
+      const int imgBottomY = renderer.getScreenHeight() - data.letterboxB;
+      for (int screenY = imgBottomY; screenY < renderer.getScreenHeight(); screenY++) {
+        const float t = static_cast<float>(screenY - imgBottomY + 1) / static_cast<float>(data.letterboxB);
+        for (int screenX = 0; screenX < renderer.getScreenWidth(); screenX++) {
+          int edgeColor;
+          if (isSolid) {
+            edgeColor = solidColorB;
+          } else {
+            int srcCol = static_cast<int>(screenX / scale);
+            srcCol = std::max(0, std::min(srcCol, data.edgeCount - 1));
+            edgeColor = data.edgeB[srcCol];
+          }
+          const int gray = computeGray(edgeColor, t);
+          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+        }
+      }
+    }
+  } else {
+    // Left letterbox
+    if (data.letterboxA > 0) {
+      const int imgLeftX = data.letterboxA;
+      for (int screenX = 0; screenX < imgLeftX; screenX++) {
+        const float t = static_cast<float>(imgLeftX - screenX) / static_cast<float>(imgLeftX);
+        for (int screenY = 0; screenY < renderer.getScreenHeight(); screenY++) {
+          int edgeColor;
+          if (isSolid) {
+            edgeColor = solidColorA;
+          } else {
+            int srcRow = static_cast<int>(screenY / scale);
+            srcRow = std::max(0, std::min(srcRow, data.edgeCount - 1));
+            edgeColor = data.edgeA[srcRow];
+          }
+          const int gray = computeGray(edgeColor, t);
+          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+        }
+      }
+    }
+
+    // Right letterbox
+    if (data.letterboxB > 0) {
+      const int imgRightX = renderer.getScreenWidth() - data.letterboxB;
+      for (int screenX = imgRightX; screenX < renderer.getScreenWidth(); screenX++) {
+        const float t = static_cast<float>(screenX - imgRightX + 1) / static_cast<float>(data.letterboxB);
+        for (int screenY = 0; screenY < renderer.getScreenHeight(); screenY++) {
+          int edgeColor;
+          if (isSolid) {
+            edgeColor = solidColorB;
+          } else {
+            int srcRow = static_cast<int>(screenY / scale);
+            srcRow = std::max(0, std::min(srcRow, data.edgeCount - 1));
+            edgeColor = data.edgeB[srcRow];
+          }
+          const int gray = computeGray(edgeColor, t);
+          renderer.drawPixelGray(screenX, screenY, quantizeNoiseDither(gray, screenX, screenY));
+        }
+      }
+    }
+  }
+}
+
+}  // namespace
+
 void SleepActivity::onEnter() {
  Activity::onEnter();
  GUI.drawPopup(renderer, "Entering Sleep...");
@@ -32,7 +394,7 @@ void SleepActivity::onEnter() {

 void SleepActivity::renderCustomSleepScreen() const {
  // Check if we have a /sleep directory
-  auto dir = SdMan.open("/sleep");
+  auto dir = Storage.open("/sleep");
  if (dir && dir.isDirectory()) {
    std::vector<std::string> files;
    char name[500];
@@ -75,7 +437,7 @@ void SleepActivity::renderCustomSleepScreen() const {
      APP_STATE.saveToFile();
      const auto filename = "/sleep/" + files[randomFileIndex];
      FsFile file;
-      if (SdMan.openFileForRead("SLP", filename, file)) {
+      if (Storage.openFileForRead("SLP", filename, file)) {
        Serial.printf("[%lu] [SLP] Randomly loading: /sleep/%s\n", millis(), files[randomFileIndex].c_str());
        delay(100);
        Bitmap bitmap(file, true);
@@ -92,7 +454,7 @@ void SleepActivity::renderCustomSleepScreen() const {
  // Look for sleep.bmp on the root of the sd card to determine if we should
  // render a custom sleep screen instead of the default.
  FsFile file;
-  if (SdMan.openFileForRead("SLP", "/sleep.bmp", file)) {
+  if (Storage.openFileForRead("SLP", "/sleep.bmp", file)) {
    Bitmap bitmap(file, true);
    if (bitmap.parseHeaders() == BmpReaderError::Ok) {
      Serial.printf("[%lu] [SLP] Loading: /sleep.bmp\n", millis());
@@ -121,7 +483,7 @@ void SleepActivity::renderDefaultSleepScreen() const {
  renderer.displayBuffer(HalDisplay::HALF_REFRESH);
 }

-void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap) const {
+void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap, const std::string& edgeCachePath) const {
  int x, y;
  const auto pageWidth = renderer.getScreenWidth();
  const auto pageHeight = renderer.getScreenHeight();
@@ -129,14 +491,14 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap) const {

  Serial.printf("[%lu] [SLP] bitmap %d x %d, screen %d x %d\n", millis(), bitmap.getWidth(), bitmap.getHeight(),
                pageWidth, pageHeight);
-  if (bitmap.getWidth() > pageWidth || bitmap.getHeight() > pageHeight) {
-    // image will scale, make sure placement is right
+
+  // Always compute aspect-ratio-preserving scale and position (supports both larger and smaller images)
  float ratio = static_cast<float>(bitmap.getWidth()) / static_cast<float>(bitmap.getHeight());
  const float screenRatio = static_cast<float>(pageWidth) / static_cast<float>(pageHeight);

  Serial.printf("[%lu] [SLP] bitmap ratio: %f, screen ratio: %f\n", millis(), ratio, screenRatio);
  if (ratio > screenRatio) {
-      // image wider than viewport ratio, scaled down image needs to be centered vertically
+    // image wider than viewport ratio, needs to be centered vertically
    if (SETTINGS.sleepScreenCoverMode == CrossPointSettings::SLEEP_SCREEN_COVER_MODE::CROP) {
      cropX = 1.0f - (screenRatio / ratio);
      Serial.printf("[%lu] [SLP] Cropping bitmap x: %f\n", millis(), cropX);
@@ -146,7 +508,7 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap) const {
    y = std::round((static_cast<float>(pageHeight) - static_cast<float>(pageWidth) / ratio) / 2);
    Serial.printf("[%lu] [SLP] Centering with ratio %f to y=%d\n", millis(), ratio, y);
  } else {
-      // image taller than viewport ratio, scaled down image needs to be centered horizontally
+    // image taller than or equal to viewport ratio, needs to be centered horizontally
    if (SETTINGS.sleepScreenCoverMode == CrossPointSettings::SLEEP_SCREEN_COVER_MODE::CROP) {
      cropY = 1.0f - (ratio / screenRatio);
      Serial.printf("[%lu] [SLP] Cropping bitmap y: %f\n", millis(), cropY);
@@ -156,18 +518,52 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap) const {
    y = 0;
    Serial.printf("[%lu] [SLP] Centering with ratio %f to x=%d\n", millis(), ratio, x);
  }
-  } else {
-    // center the image
-    x = (pageWidth - bitmap.getWidth()) / 2;
-    y = (pageHeight - bitmap.getHeight()) / 2;
-  }

  Serial.printf("[%lu] [SLP] drawing to %d x %d\n", millis(), x, y);
+
+  // Compute the scale factor (same formula as drawBitmap) so we can map screen coords to source coords
+  const float effectiveWidth = (1.0f - cropX) * bitmap.getWidth();
+  const float effectiveHeight = (1.0f - cropY) * bitmap.getHeight();
+  const float scale =
+      std::min(static_cast<float>(pageWidth) / effectiveWidth, static_cast<float>(pageHeight) / effectiveHeight);
+
+  // Determine letterbox fill settings
+  const uint8_t fillMode = SETTINGS.sleepScreenLetterboxFill;
+  const bool wantFill = (fillMode != CrossPointSettings::SLEEP_SCREEN_LETTERBOX_FILL::LETTERBOX_NONE);
+  const int targetColor =
+      (SETTINGS.sleepScreenGradientDir == CrossPointSettings::SLEEP_SCREEN_GRADIENT_DIR::GRADIENT_TO_BLACK) ? 0 : 255;
+
+  static const char* fillModeNames[] = {"none", "solid", "blended", "gradient"};
+  const char* fillModeName = (fillMode < 4) ? fillModeNames[fillMode] : "unknown";
+
+  // Load cached edge data or sample from bitmap (first pass over bitmap, then rewind)
+  LetterboxGradientData gradientData;
+  const bool hasLetterbox = (x > 0 || y > 0);
+  if (hasLetterbox && wantFill) {
+    bool cacheLoaded = false;
+    if (!edgeCachePath.empty()) {
+      cacheLoaded = loadEdgeCache(edgeCachePath, pageWidth, pageHeight, gradientData);
+    }
+    if (!cacheLoaded) {
+      Serial.printf("[%lu] [SLP] Letterbox detected (x=%d, y=%d), sampling edges for %s fill\n", millis(), x, y,
+                    fillModeName);
+      gradientData = sampleBitmapEdges(bitmap, x, y, pageWidth, pageHeight, scale, cropX, cropY);
+      if (!edgeCachePath.empty() && gradientData.edgeA) {
+        saveEdgeCache(edgeCachePath, pageWidth, pageHeight, gradientData);
+      }
+    }
+  }
+
  renderer.clearScreen();

  const bool hasGreyscale = bitmap.hasGreyscale() &&
                            SETTINGS.sleepScreenCoverFilter == CrossPointSettings::SLEEP_SCREEN_COVER_FILTER::NO_FILTER;

+  // Draw letterbox fill (BW pass)
+  if (gradientData.edgeA) {
+    drawLetterboxFill(renderer, gradientData, scale, fillMode, targetColor);
+  }
+
  renderer.drawBitmap(bitmap, x, y, pageWidth, pageHeight, cropX, cropY);

  if (SETTINGS.sleepScreenCoverFilter == CrossPointSettings::SLEEP_SCREEN_COVER_FILTER::INVERTED_BLACK_AND_WHITE) {
@@ -180,18 +576,26 @@ void SleepActivity::renderBitmapSleepScreen(const Bitmap& bitmap) const {
    bitmap.rewindToData();
    renderer.clearScreen(0x00);
    renderer.setRenderMode(GfxRenderer::GRAYSCALE_LSB);
+    if (gradientData.edgeA) {
+      drawLetterboxFill(renderer, gradientData, scale, fillMode, targetColor);
+    }
    renderer.drawBitmap(bitmap, x, y, pageWidth, pageHeight, cropX, cropY);
    renderer.copyGrayscaleLsbBuffers();

    bitmap.rewindToData();
    renderer.clearScreen(0x00);
    renderer.setRenderMode(GfxRenderer::GRAYSCALE_MSB);
+    if (gradientData.edgeA) {
+      drawLetterboxFill(renderer, gradientData, scale, fillMode, targetColor);
+    }
    renderer.drawBitmap(bitmap, x, y, pageWidth, pageHeight, cropX, cropY);
    renderer.copyGrayscaleMsbBuffers();

    renderer.displayGrayBuffer();
    renderer.setRenderMode(GfxRenderer::BW);
  }
+
+  gradientData.free();
 }

 void SleepActivity::renderCoverSleepScreen() const {
@@ -261,12 +665,18 @@ void SleepActivity::renderCoverSleepScreen() const {
    return (this->*renderNoCoverSleepScreen)();
  }

+  // Derive edge cache path from cover BMP path (e.g. cover.bmp -> cover_edges.bin)
+  std::string edgeCachePath;
+  if (coverBmpPath.size() > 4) {
+    edgeCachePath = coverBmpPath.substr(0, coverBmpPath.size() - 4) + "_edges.bin";
+  }
+
  FsFile file;
-  if (SdMan.openFileForRead("SLP", coverBmpPath, file)) {
+  if (Storage.openFileForRead("SLP", coverBmpPath, file)) {
    Bitmap bitmap(file);
    if (bitmap.parseHeaders() == BmpReaderError::Ok) {
      Serial.printf("[SLP] Rendering sleep cover: %s\n", coverBmpPath.c_str());
-      renderBitmapSleepScreen(bitmap);
+      renderBitmapSleepScreen(bitmap, edgeCachePath);
      return;
    }
  }
--- a/src/activities/boot_sleep/SleepActivity.h
+++ b/src/activities/boot_sleep/SleepActivity.h
@@ -1,4 +1,6 @@
 #pragma once
+#include <string>
+
 #include "../Activity.h"

 class Bitmap;
@@ -13,6 +15,6 @@ class SleepActivity final : public Activity {
  void renderDefaultSleepScreen() const;
  void renderCustomSleepScreen() const;
  void renderCoverSleepScreen() const;
-  void renderBitmapSleepScreen(const Bitmap& bitmap) const;
+  void renderBitmapSleepScreen(const Bitmap& bitmap, const std::string& edgeCachePath = "") const;
  void renderBlankSleepScreen() const;
 };
--- a/src/activities/home/HomeActivity.cpp
+++ b/src/activities/home/HomeActivity.cpp
@@ -3,7 +3,7 @@
 #include <Bitmap.h>
 #include <Epub.h>
 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
 #include <Utf8.h>
 #include <Xtc.h>

@@ -47,7 +47,7 @@ void HomeActivity::loadRecentBooks(int maxBooks) {
    }

    // Skip if file no longer exists
-    if (!SdMan.exists(book.path.c_str())) {
+    if (!Storage.exists(book.path.c_str())) {
      continue;
    }

@@ -64,7 +64,7 @@ void HomeActivity::loadRecentCovers(int coverHeight) {
  for (RecentBook& book : recentBooks) {
    if (!book.coverBmpPath.empty()) {
      std::string coverPath = UITheme::getCoverThumbPath(book.coverBmpPath, coverHeight);
-      if (!SdMan.exists(coverPath.c_str())) {
+      if (!Storage.exists(coverPath.c_str())) {
        // If epub, try to load the metadata for title/author and cover
        if (StringUtils::checkFileExtension(book.path, ".epub")) {
          Epub epub(book.path, "/.crosspoint");
--- a/src/activities/home/MyLibraryActivity.cpp
+++ b/src/activities/home/MyLibraryActivity.cpp
@@ -1,7 +1,7 @@
 #include "MyLibraryActivity.h"

 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>

 #include <algorithm>

@@ -33,7 +33,7 @@ void MyLibraryActivity::taskTrampoline(void* param) {
 void MyLibraryActivity::loadFiles() {
  files.clear();

-  auto root = SdMan.open(basepath.c_str());
+  auto root = Storage.open(basepath.c_str());
  if (!root || !root.isDirectory()) {
    if (root) root.close();
    return;
--- a/src/activities/home/RecentBooksActivity.cpp
+++ b/src/activities/home/RecentBooksActivity.cpp
@@ -1,7 +1,7 @@
 #include "RecentBooksActivity.h"

 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>

 #include <algorithm>

@@ -28,7 +28,7 @@ void RecentBooksActivity::loadRecentBooks() {

  for (const auto& book : books) {
    // Skip if file no longer exists
-    if (!SdMan.exists(book.path.c_str())) {
+    if (!Storage.exists(book.path.c_str())) {
      continue;
    }
    recentBooks.push_back(book);
--- a/src/activities/reader/EpubReaderActivity.cpp
+++ b/src/activities/reader/EpubReaderActivity.cpp
@@ -3,7 +3,7 @@
 #include <Epub/Page.h>
 #include <FsHelpers.h>
 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>

 #include "CrossPointSettings.h"
 #include "CrossPointState.h"
@@ -77,7 +77,7 @@ void EpubReaderActivity::onEnter() {
  epub->setupCacheDir();

  FsFile f;
-  if (SdMan.openFileForRead("ERS", epub->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForRead("ERS", epub->getCachePath() + "/progress.bin", f)) {
    uint8_t data[6];
    int dataSize = f.read(data, 6);
    if (dataSize == 4 || dataSize == 6) {
@@ -204,15 +204,15 @@ void EpubReaderActivity::loop() {
    xSemaphoreGive(renderingMutex);
  }

-  // Long press BACK (1s+) goes directly to home
+  // Long press BACK (1s+) goes to file selection
  if (mappedInput.isPressed(MappedInputManager::Button::Back) && mappedInput.getHeldTime() >= goHomeMs) {
-    onGoHome();
+    onGoBack();
    return;
  }

-  // Short press BACK goes to file selection
+  // Short press BACK goes directly to home
  if (mappedInput.wasReleased(MappedInputManager::Button::Back) && mappedInput.getHeldTime() < goHomeMs) {
-    onGoBack();
+    onGoHome();
    return;
  }

@@ -654,7 +654,7 @@ void EpubReaderActivity::renderScreen() {

 void EpubReaderActivity::saveProgress(int spineIndex, int currentPage, int pageCount) {
  FsFile f;
-  if (SdMan.openFileForWrite("ERS", epub->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForWrite("ERS", epub->getCachePath() + "/progress.bin", f)) {
    uint8_t data[6];
    data[0] = currentSpineIndex & 0xFF;
    data[1] = (currentSpineIndex >> 8) & 0xFF;
--- a/src/activities/reader/KOReaderSyncActivity.cpp
+++ b/src/activities/reader/KOReaderSyncActivity.cpp
@@ -317,7 +317,6 @@ void KOReaderSyncActivity::render() {
             localProgress.percentage * 100);
    renderer.drawText(UI_10_FONT_ID, 20, 320, localPageStr);

-    // Options
    const int optionY = 350;
    const int optionHeight = 30;

@@ -333,13 +332,8 @@ void KOReaderSyncActivity::render() {
    }
    renderer.drawText(UI_10_FONT_ID, 20, optionY + optionHeight, "Upload local progress", selectedOption != 1);

-    // Cancel option
-    if (selectedOption == 2) {
-      renderer.fillRect(0, optionY + optionHeight * 2 - 2, pageWidth - 1, optionHeight);
-    }
-    renderer.drawText(UI_10_FONT_ID, 20, optionY + optionHeight * 2, "Cancel", selectedOption != 2);
-
-    const auto labels = mappedInput.mapLabels("", "Select", "", "");
+    // Bottom button hints: show Back and Select
+    const auto labels = mappedInput.mapLabels("Back", "Select", "", "");
    GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
    renderer.displayBuffer();
    return;
@@ -349,7 +343,7 @@ void KOReaderSyncActivity::render() {
    renderer.drawCenteredText(UI_10_FONT_ID, 280, "No remote progress found", true, EpdFontFamily::BOLD);
    renderer.drawCenteredText(UI_10_FONT_ID, 320, "Upload current position?");

-    const auto labels = mappedInput.mapLabels("Cancel", "Upload", "", "");
+    const auto labels = mappedInput.mapLabels("Back", "Upload", "", "");
    GUI.drawButtonHints(renderer, labels.btn1, labels.btn2, labels.btn3, labels.btn4);
    renderer.displayBuffer();
    return;
@@ -392,11 +386,11 @@ void KOReaderSyncActivity::loop() {
    // Navigate options
    if (mappedInput.wasPressed(MappedInputManager::Button::Up) ||
        mappedInput.wasPressed(MappedInputManager::Button::Left)) {
-      selectedOption = (selectedOption + 2) % 3;  // Wrap around
+      selectedOption = (selectedOption + 1) % 2;  // Wrap around among 2 options
      updateRequired = true;
    } else if (mappedInput.wasPressed(MappedInputManager::Button::Down) ||
               mappedInput.wasPressed(MappedInputManager::Button::Right)) {
-      selectedOption = (selectedOption + 1) % 3;
+      selectedOption = (selectedOption + 1) % 2;  // Wrap around among 2 options
      updateRequired = true;
    }

@@ -407,9 +401,6 @@ void KOReaderSyncActivity::loop() {
      } else if (selectedOption == 1) {
        // Upload local progress
        performUpload();
-      } else {
-        // Cancel
-        onCancel();
      }
    }

--- a/src/activities/reader/KOReaderSyncActivity.h
+++ b/src/activities/reader/KOReaderSyncActivity.h
@@ -18,7 +18,7 @@
 * 1. Connect to WiFi (if not connected)
 * 2. Calculate document hash
 * 3. Fetch remote progress
- * 4. Show comparison and options (Apply/Upload/Cancel)
+ * 4. Show comparison and options (Apply/Upload)
 * 5. Apply or upload progress
 */
 class KOReaderSyncActivity final : public ActivityWithSubactivity {
@@ -82,7 +82,7 @@ class KOReaderSyncActivity final : public ActivityWithSubactivity {
  // Local progress as KOReader format (for display)
  KOReaderPosition localProgress;

-  // Selection in result screen (0=Apply, 1=Upload, 2=Cancel)
+  // Selection in result screen (0=Apply, 1=Upload)
  int selectedOption = 0;

  OnCancelCallback onCancel;
--- a/src/activities/reader/ReaderActivity.cpp
+++ b/src/activities/reader/ReaderActivity.cpp
@@ -1,5 +1,7 @@
 #include "ReaderActivity.h"

+#include <HalStorage.h>
+
 #include "Epub.h"
 #include "EpubReaderActivity.h"
 #include "Txt.h"
@@ -27,7 +29,7 @@ bool ReaderActivity::isTxtFile(const std::string& path) {
 }

 std::unique_ptr<Epub> ReaderActivity::loadEpub(const std::string& path) {
-  if (!SdMan.exists(path.c_str())) {
+  if (!Storage.exists(path.c_str())) {
    Serial.printf("[%lu] [   ] File does not exist: %s\n", millis(), path.c_str());
    return nullptr;
  }
@@ -42,7 +44,7 @@ std::unique_ptr<Epub> ReaderActivity::loadEpub(const std::string& path) {
 }

 std::unique_ptr<Xtc> ReaderActivity::loadXtc(const std::string& path) {
-  if (!SdMan.exists(path.c_str())) {
+  if (!Storage.exists(path.c_str())) {
    Serial.printf("[%lu] [   ] File does not exist: %s\n", millis(), path.c_str());
    return nullptr;
  }
@@ -57,7 +59,7 @@ std::unique_ptr<Xtc> ReaderActivity::loadXtc(const std::string& path) {
 }

 std::unique_ptr<Txt> ReaderActivity::loadTxt(const std::string& path) {
-  if (!SdMan.exists(path.c_str())) {
+  if (!Storage.exists(path.c_str())) {
    Serial.printf("[%lu] [   ] File does not exist: %s\n", millis(), path.c_str());
    return nullptr;
  }
--- a/src/activities/reader/TxtReaderActivity.cpp
+++ b/src/activities/reader/TxtReaderActivity.cpp
@@ -1,7 +1,7 @@
 #include "TxtReaderActivity.h"

 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
 #include <Serialization.h>
 #include <Utf8.h>

@@ -102,15 +102,15 @@ void TxtReaderActivity::loop() {
    return;
  }

-  // Long press BACK (1s+) goes directly to home
+  // Long press BACK (1s+) goes to file selection
  if (mappedInput.isPressed(MappedInputManager::Button::Back) && mappedInput.getHeldTime() >= goHomeMs) {
-    onGoHome();
+    onGoBack();
    return;
  }

-  // Short press BACK goes to file selection
+  // Short press BACK goes directly to home
  if (mappedInput.wasReleased(MappedInputManager::Button::Back) && mappedInput.getHeldTime() < goHomeMs) {
-    onGoBack();
+    onGoHome();
    return;
  }

@@ -565,7 +565,7 @@ void TxtReaderActivity::renderStatusBar(const int orientedMarginRight, const int

 void TxtReaderActivity::saveProgress() const {
  FsFile f;
-  if (SdMan.openFileForWrite("TRS", txt->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForWrite("TRS", txt->getCachePath() + "/progress.bin", f)) {
    uint8_t data[4];
    data[0] = currentPage & 0xFF;
    data[1] = (currentPage >> 8) & 0xFF;
@@ -578,7 +578,7 @@ void TxtReaderActivity::saveProgress() const {

 void TxtReaderActivity::loadProgress() {
  FsFile f;
-  if (SdMan.openFileForRead("TRS", txt->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForRead("TRS", txt->getCachePath() + "/progress.bin", f)) {
    uint8_t data[4];
    if (f.read(data, 4) == 4) {
      currentPage = data[0] + (data[1] << 8);
@@ -609,7 +609,7 @@ bool TxtReaderActivity::loadPageIndexCache() {

  std::string cachePath = txt->getCachePath() + "/index.bin";
  FsFile f;
-  if (!SdMan.openFileForRead("TRS", cachePath, f)) {
+  if (!Storage.openFileForRead("TRS", cachePath, f)) {
    Serial.printf("[%lu] [TRS] No page index cache found\n", millis());
    return false;
  }
@@ -701,7 +701,7 @@ bool TxtReaderActivity::loadPageIndexCache() {
 void TxtReaderActivity::savePageIndexCache() const {
  std::string cachePath = txt->getCachePath() + "/index.bin";
  FsFile f;
-  if (!SdMan.openFileForWrite("TRS", cachePath, f)) {
+  if (!Storage.openFileForWrite("TRS", cachePath, f)) {
    Serial.printf("[%lu] [TRS] Failed to save page index cache\n", millis());
    return;
  }
--- a/src/activities/reader/XtcReaderActivity.cpp
+++ b/src/activities/reader/XtcReaderActivity.cpp
@@ -9,7 +9,7 @@

 #include <FsHelpers.h>
 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>

 #include "CrossPointSettings.h"
 #include "CrossPointState.h"
@@ -102,15 +102,15 @@ void XtcReaderActivity::loop() {
    }
  }

-  // Long press BACK (1s+) goes directly to home
+  // Long press BACK (1s+) goes to file selection
  if (mappedInput.isPressed(MappedInputManager::Button::Back) && mappedInput.getHeldTime() >= goHomeMs) {
-    onGoHome();
+    onGoBack();
    return;
  }

-  // Short press BACK goes to file selection
+  // Short press BACK goes directly to home
  if (mappedInput.wasReleased(MappedInputManager::Button::Back) && mappedInput.getHeldTime() < goHomeMs) {
-    onGoBack();
+    onGoHome();
    return;
  }

@@ -372,7 +372,7 @@ void XtcReaderActivity::renderPage() {

 void XtcReaderActivity::saveProgress() const {
  FsFile f;
-  if (SdMan.openFileForWrite("XTR", xtc->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForWrite("XTR", xtc->getCachePath() + "/progress.bin", f)) {
    uint8_t data[4];
    data[0] = currentPage & 0xFF;
    data[1] = (currentPage >> 8) & 0xFF;
@@ -385,7 +385,7 @@ void XtcReaderActivity::saveProgress() const {

 void XtcReaderActivity::loadProgress() {
  FsFile f;
-  if (SdMan.openFileForRead("XTR", xtc->getCachePath() + "/progress.bin", f)) {
+  if (Storage.openFileForRead("XTR", xtc->getCachePath() + "/progress.bin", f)) {
    uint8_t data[4];
    if (f.read(data, 4) == 4) {
      currentPage = data[0] | (data[1] << 8) | (data[2] << 16) | (data[3] << 24);
--- a/src/activities/settings/ClearCacheActivity.cpp
+++ b/src/activities/settings/ClearCacheActivity.cpp
@@ -1,8 +1,8 @@
 #include "ClearCacheActivity.h"

 #include <GfxRenderer.h>
+#include <HalStorage.h>
 #include <HardwareSerial.h>
-#include <SDCardManager.h>

 #include "MappedInputManager.h"
 #include "components/UITheme.h"
@@ -107,7 +107,7 @@ void ClearCacheActivity::clearCache() {
  Serial.printf("[%lu] [CLEAR_CACHE] Clearing cache...\n", millis());

  // Open .crosspoint directory
-  auto root = SdMan.open("/.crosspoint");
+  auto root = Storage.open("/.crosspoint");
  if (!root || !root.isDirectory()) {
    Serial.printf("[%lu] [CLEAR_CACHE] Failed to open cache directory\n", millis());
    if (root) root.close();
@@ -132,7 +132,7 @@ void ClearCacheActivity::clearCache() {

      file.close();  // Close before attempting to delete

-      if (SdMan.removeDir(fullPath.c_str())) {
+      if (Storage.removeDir(fullPath.c_str())) {
        clearedCount++;
      } else {
        Serial.printf("[%lu] [CLEAR_CACHE] Failed to remove: %s\n", millis(), fullPath.c_str());
--- a/src/activities/settings/SettingsActivity.cpp
+++ b/src/activities/settings/SettingsActivity.cpp
@@ -10,6 +10,7 @@
 #include "KOReaderSettingsActivity.h"
 #include "MappedInputManager.h"
 #include "OtaUpdateActivity.h"
+#include "SettingsList.h"
 #include "components/UITheme.h"
 #include "fontIds.h"

@@ -17,54 +18,6 @@ const char* SettingsActivity::categoryNames[categoryCount] = {"Display", "Reader

 namespace {
 constexpr int changeTabsMs = 700;
-constexpr int displaySettingsCount = 8;
-const SettingInfo displaySettings[displaySettingsCount] = {
-    // Should match with SLEEP_SCREEN_MODE
-    SettingInfo::Enum("Sleep Screen", &CrossPointSettings::sleepScreen,
-                      {"Dark", "Light", "Custom", "Cover", "None", "Cover + Custom"}),
-    SettingInfo::Enum("Sleep Screen Cover Mode", &CrossPointSettings::sleepScreenCoverMode, {"Fit", "Crop"}),
-    SettingInfo::Enum("Sleep Screen Cover Filter", &CrossPointSettings::sleepScreenCoverFilter,
-                      {"None", "Contrast", "Inverted"}),
-    SettingInfo::Enum(
-        "Status Bar", &CrossPointSettings::statusBar,
-        {"None", "No Progress", "Full w/ Percentage", "Full w/ Book Bar", "Book Bar Only", "Full w/ Chapter Bar"}),
-    SettingInfo::Enum("Hide Battery %", &CrossPointSettings::hideBatteryPercentage, {"Never", "In Reader", "Always"}),
-    SettingInfo::Enum("Refresh Frequency", &CrossPointSettings::refreshFrequency,
-                      {"1 page", "5 pages", "10 pages", "15 pages", "30 pages"}),
-    SettingInfo::Enum("UI Theme", &CrossPointSettings::uiTheme, {"Classic", "Lyra"}),
-    SettingInfo::Toggle("Sunlight Fading Fix", &CrossPointSettings::fadingFix),
-};
-
-constexpr int readerSettingsCount = 10;
-const SettingInfo readerSettings[readerSettingsCount] = {
-    SettingInfo::Enum("Font Family", &CrossPointSettings::fontFamily, {"Bookerly", "Noto Sans", "Open Dyslexic"}),
-    SettingInfo::Enum("Font Size", &CrossPointSettings::fontSize, {"Small", "Medium", "Large", "X Large"}),
-    SettingInfo::Enum("Line Spacing", &CrossPointSettings::lineSpacing, {"Tight", "Normal", "Wide"}),
-    SettingInfo::Value("Screen Margin", &CrossPointSettings::screenMargin, {5, 40, 5}),
-    SettingInfo::Enum("Paragraph Alignment", &CrossPointSettings::paragraphAlignment,
-                      {"Justify", "Left", "Center", "Right", "Book's Style"}),
-    SettingInfo::Toggle("Book's Embedded Style", &CrossPointSettings::embeddedStyle),
-    SettingInfo::Toggle("Hyphenation", &CrossPointSettings::hyphenationEnabled),
-    SettingInfo::Enum("Reading Orientation", &CrossPointSettings::orientation,
-                      {"Portrait", "Landscape CW", "Inverted", "Landscape CCW"}),
-    SettingInfo::Toggle("Extra Paragraph Spacing", &CrossPointSettings::extraParagraphSpacing),
-    SettingInfo::Toggle("Text Anti-Aliasing", &CrossPointSettings::textAntiAliasing)};
-
-constexpr int controlsSettingsCount = 4;
-const SettingInfo controlsSettings[controlsSettingsCount] = {
-    // Launches the remap wizard for front buttons.
-    SettingInfo::Action("Remap Front Buttons"),
-    SettingInfo::Enum("Side Button Layout (reader)", &CrossPointSettings::sideButtonLayout,
-                      {"Prev, Next", "Next, Prev"}),
-    SettingInfo::Toggle("Long-press Chapter Skip", &CrossPointSettings::longPressChapterSkip),
-    SettingInfo::Enum("Short Power Button Click", &CrossPointSettings::shortPwrBtn, {"Ignore", "Sleep", "Page Turn"})};
-
-constexpr int systemSettingsCount = 5;
-const SettingInfo systemSettings[systemSettingsCount] = {
-    SettingInfo::Enum("Time to Sleep", &CrossPointSettings::sleepTimeout,
-                      {"1 min", "5 min", "10 min", "15 min", "30 min"}),
-    SettingInfo::Action("KOReader Sync"), SettingInfo::Action("OPDS Browser"), SettingInfo::Action("Clear Cache"),
-    SettingInfo::Action("Check for updates")};
 }  // namespace

 void SettingsActivity::taskTrampoline(void* param) {
@@ -76,13 +29,40 @@ void SettingsActivity::onEnter() {
  Activity::onEnter();
  renderingMutex = xSemaphoreCreateMutex();

+  // Build per-category vectors from the shared settings list
+  displaySettings.clear();
+  readerSettings.clear();
+  controlsSettings.clear();
+  systemSettings.clear();
+
+  for (auto& setting : getSettingsList()) {
+    if (!setting.category) continue;
+    if (strcmp(setting.category, "Display") == 0) {
+      displaySettings.push_back(std::move(setting));
+    } else if (strcmp(setting.category, "Reader") == 0) {
+      readerSettings.push_back(std::move(setting));
+    } else if (strcmp(setting.category, "Controls") == 0) {
+      controlsSettings.push_back(std::move(setting));
+    } else if (strcmp(setting.category, "System") == 0) {
+      systemSettings.push_back(std::move(setting));
+    }
+    // Web-only categories (KOReader Sync, OPDS Browser) are skipped for device UI
+  }
+
+  // Append device-only ACTION items
+  controlsSettings.insert(controlsSettings.begin(), SettingInfo::Action("Remap Front Buttons"));
+  systemSettings.push_back(SettingInfo::Action("KOReader Sync"));
+  systemSettings.push_back(SettingInfo::Action("OPDS Browser"));
+  systemSettings.push_back(SettingInfo::Action("Clear Cache"));
+  systemSettings.push_back(SettingInfo::Action("Check for updates"));
+
  // Reset selection to first category
  selectedCategoryIndex = 0;
  selectedSettingIndex = 0;

  // Initialize with first category (Display)
-  settingsList = displaySettings;
-  settingsCount = displaySettingsCount;
+  currentSettings = &displaySettings;
+  settingsCount = static_cast<int>(displaySettings.size());

  // Trigger first update
  updateRequired = true;
@@ -162,23 +142,20 @@ void SettingsActivity::loop() {
  if (hasChangedCategory) {
    selectedSettingIndex = (selectedSettingIndex == 0) ? 0 : 1;
    switch (selectedCategoryIndex) {
-      case 0:  // Display
-        settingsList = displaySettings;
-        settingsCount = displaySettingsCount;
+      case 0:
+        currentSettings = &displaySettings;
        break;
-      case 1:  // Reader
-        settingsList = readerSettings;
-        settingsCount = readerSettingsCount;
+      case 1:
+        currentSettings = &readerSettings;
        break;
-      case 2:  // Controls
-        settingsList = controlsSettings;
-        settingsCount = controlsSettingsCount;
+      case 2:
+        currentSettings = &controlsSettings;
        break;
-      case 3:  // System
-        settingsList = systemSettings;
-        settingsCount = systemSettingsCount;
+      case 3:
+        currentSettings = &systemSettings;
        break;
    }
+    settingsCount = static_cast<int>(currentSettings->size());
  }
 }

@@ -188,7 +165,7 @@ void SettingsActivity::toggleCurrentSetting() {
    return;
  }

-  const auto& setting = settingsList[selectedSetting];
+  const auto& setting = (*currentSettings)[selectedSetting];

  if (setting.type == SettingType::TOGGLE && setting.valuePtr != nullptr) {
    // Toggle the boolean value using the member pointer
@@ -283,24 +260,24 @@ void SettingsActivity::render() const {
  GUI.drawTabBar(renderer, Rect{0, metrics.topPadding + metrics.headerHeight, pageWidth, metrics.tabBarHeight}, tabs,
                 selectedSettingIndex == 0);

+  const auto& settings = *currentSettings;
  GUI.drawList(
      renderer,
      Rect{0, metrics.topPadding + metrics.headerHeight + metrics.tabBarHeight + metrics.verticalSpacing, pageWidth,
           pageHeight - (metrics.topPadding + metrics.headerHeight + metrics.tabBarHeight + metrics.buttonHintsHeight +
                         metrics.verticalSpacing * 2)},
-      settingsCount, selectedSettingIndex - 1, [this](int index) { return std::string(settingsList[index].name); },
+      settingsCount, selectedSettingIndex - 1, [&settings](int index) { return std::string(settings[index].name); },
      nullptr, nullptr,
-      [this](int i) {
-        const auto& setting = settingsList[i];
+      [&settings](int i) {
        std::string valueText = "";
-        if (settingsList[i].type == SettingType::TOGGLE && settingsList[i].valuePtr != nullptr) {
-          const bool value = SETTINGS.*(settingsList[i].valuePtr);
+        if (settings[i].type == SettingType::TOGGLE && settings[i].valuePtr != nullptr) {
+          const bool value = SETTINGS.*(settings[i].valuePtr);
          valueText = value ? "ON" : "OFF";
-        } else if (settingsList[i].type == SettingType::ENUM && settingsList[i].valuePtr != nullptr) {
-          const uint8_t value = SETTINGS.*(settingsList[i].valuePtr);
-          valueText = settingsList[i].enumValues[value];
-        } else if (settingsList[i].type == SettingType::VALUE && settingsList[i].valuePtr != nullptr) {
-          valueText = std::to_string(SETTINGS.*(settingsList[i].valuePtr));
+        } else if (settings[i].type == SettingType::ENUM && settings[i].valuePtr != nullptr) {
+          const uint8_t value = SETTINGS.*(settings[i].valuePtr);
+          valueText = settings[i].enumValues[value];
+        } else if (settings[i].type == SettingType::VALUE && settings[i].valuePtr != nullptr) {
+          valueText = std::to_string(SETTINGS.*(settings[i].valuePtr));
        }
        return valueText;
      });
--- a/src/activities/settings/SettingsActivity.h
+++ b/src/activities/settings/SettingsActivity.h
@@ -11,12 +11,12 @@

 class CrossPointSettings;

-enum class SettingType { TOGGLE, ENUM, ACTION, VALUE };
+enum class SettingType { TOGGLE, ENUM, ACTION, VALUE, STRING };

 struct SettingInfo {
  const char* name;
  SettingType type;
-  uint8_t CrossPointSettings::* valuePtr;
+  uint8_t CrossPointSettings::* valuePtr = nullptr;
  std::vector<std::string> enumValues;

  struct ValueRange {
@@ -24,20 +24,100 @@ struct SettingInfo {
    uint8_t max;
    uint8_t step;
  };
-  ValueRange valueRange;
+  ValueRange valueRange = {};

-  static SettingInfo Toggle(const char* name, uint8_t CrossPointSettings::* ptr) {
-    return {name, SettingType::TOGGLE, ptr};
+  const char* key = nullptr;       // JSON API key (nullptr for ACTION types)
+  const char* category = nullptr;  // Category for web UI grouping
+
+  // Direct char[] string fields (for settings stored in CrossPointSettings)
+  char* stringPtr = nullptr;
+  size_t stringMaxLen = 0;
+
+  // Dynamic accessors (for settings stored outside CrossPointSettings, e.g. KOReaderCredentialStore)
+  std::function<uint8_t()> valueGetter;
+  std::function<void(uint8_t)> valueSetter;
+  std::function<std::string()> stringGetter;
+  std::function<void(const std::string&)> stringSetter;
+
+  static SettingInfo Toggle(const char* name, uint8_t CrossPointSettings::* ptr, const char* key = nullptr,
+                            const char* category = nullptr) {
+    SettingInfo s;
+    s.name = name;
+    s.type = SettingType::TOGGLE;
+    s.valuePtr = ptr;
+    s.key = key;
+    s.category = category;
+    return s;
  }

-  static SettingInfo Enum(const char* name, uint8_t CrossPointSettings::* ptr, std::vector<std::string> values) {
-    return {name, SettingType::ENUM, ptr, std::move(values)};
+  static SettingInfo Enum(const char* name, uint8_t CrossPointSettings::* ptr, std::vector<std::string> values,
+                          const char* key = nullptr, const char* category = nullptr) {
+    SettingInfo s;
+    s.name = name;
+    s.type = SettingType::ENUM;
+    s.valuePtr = ptr;
+    s.enumValues = std::move(values);
+    s.key = key;
+    s.category = category;
+    return s;
  }

-  static SettingInfo Action(const char* name) { return {name, SettingType::ACTION, nullptr}; }
+  static SettingInfo Action(const char* name) {
+    SettingInfo s;
+    s.name = name;
+    s.type = SettingType::ACTION;
+    return s;
+  }

-  static SettingInfo Value(const char* name, uint8_t CrossPointSettings::* ptr, const ValueRange valueRange) {
-    return {name, SettingType::VALUE, ptr, {}, valueRange};
+  static SettingInfo Value(const char* name, uint8_t CrossPointSettings::* ptr, const ValueRange valueRange,
+                           const char* key = nullptr, const char* category = nullptr) {
+    SettingInfo s;
+    s.name = name;
+    s.type = SettingType::VALUE;
+    s.valuePtr = ptr;
+    s.valueRange = valueRange;
+    s.key = key;
+    s.category = category;
+    return s;
+  }
+
+  static SettingInfo String(const char* name, char* ptr, size_t maxLen, const char* key = nullptr,
+                            const char* category = nullptr) {
+    SettingInfo s;
+    s.name = name;
+    s.type = SettingType::STRING;
+    s.stringPtr = ptr;
+    s.stringMaxLen = maxLen;
+    s.key = key;
+    s.category = category;
+    return s;
+  }
+
+  static SettingInfo DynamicEnum(const char* name, std::vector<std::string> values, std::function<uint8_t()> getter,
+                                 std::function<void(uint8_t)> setter, const char* key = nullptr,
+                                 const char* category = nullptr) {
+    SettingInfo s;
+    s.name = name;
+    s.type = SettingType::ENUM;
+    s.enumValues = std::move(values);
+    s.valueGetter = std::move(getter);
+    s.valueSetter = std::move(setter);
+    s.key = key;
+    s.category = category;
+    return s;
+  }
+
+  static SettingInfo DynamicString(const char* name, std::function<std::string()> getter,
+                                   std::function<void(const std::string&)> setter, const char* key = nullptr,
+                                   const char* category = nullptr) {
+    SettingInfo s;
+    s.name = name;
+    s.type = SettingType::STRING;
+    s.stringGetter = std::move(getter);
+    s.stringSetter = std::move(setter);
+    s.key = key;
+    s.category = category;
+    return s;
  }
 };

@@ -48,7 +128,13 @@ class SettingsActivity final : public ActivityWithSubactivity {
  int selectedCategoryIndex = 0;  // Currently selected category
  int selectedSettingIndex = 0;
  int settingsCount = 0;
-  const SettingInfo* settingsList = nullptr;
+
+  // Per-category settings derived from shared list + device-only actions
+  std::vector<SettingInfo> displaySettings;
+  std::vector<SettingInfo> readerSettings;
+  std::vector<SettingInfo> controlsSettings;
+  std::vector<SettingInfo> systemSettings;
+  const std::vector<SettingInfo>* currentSettings = nullptr;

  const std::function<void()> onGoHome;

--- a/src/components/themes/BaseTheme.cpp
+++ b/src/components/themes/BaseTheme.cpp
@@ -1,7 +1,7 @@
 #include "BaseTheme.h"

 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
 #include <Utf8.h>

 #include <cstdint>
@@ -308,7 +308,7 @@ void BaseTheme::drawRecentBookCover(GfxRenderer& renderer, Rect rect, const std:

      // First time: load cover from SD and render
      FsFile file;
-      if (SdMan.openFileForRead("HOME", coverBmpPath, file)) {
+      if (Storage.openFileForRead("HOME", coverBmpPath, file)) {
        Bitmap bitmap(file);
        if (bitmap.parseHeaders() == BmpReaderError::Ok) {
          Serial.printf("Rendering bmp\n");
--- a/src/components/themes/lyra/LyraTheme.cpp
+++ b/src/components/themes/lyra/LyraTheme.cpp
@@ -1,7 +1,7 @@
 #include "LyraTheme.h"

 #include <GfxRenderer.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>

 #include <cstdint>
 #include <string>
@@ -283,7 +283,7 @@ void LyraTheme::drawRecentBookCover(GfxRenderer& renderer, Rect rect, const std:

          // First time: load cover from SD and render
          FsFile file;
-          if (SdMan.openFileForRead("HOME", coverBmpPath, file)) {
+          if (Storage.openFileForRead("HOME", coverBmpPath, file)) {
            Bitmap bitmap(file);
            if (bitmap.parseHeaders() == BmpReaderError::Ok) {
              float coverHeight = static_cast<float>(bitmap.getHeight());
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -3,7 +3,7 @@
 #include <GfxRenderer.h>
 #include <HalDisplay.h>
 #include <HalGPIO.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
 #include <SPI.h>
 #include <builtinFonts/all.h>

@@ -293,7 +293,7 @@ void setup() {

  // SD Card Initialization
  // We need 6 open files concurrently when parsing a new chapter
-  if (!SdMan.begin()) {
+  if (!Storage.begin()) {
    Serial.printf("[%lu] [   ] SD card initialization failed\n", millis());
    setupDisplayAndFonts();
    exitActivity();
--- a/src/network/CrossPointWebServer.cpp
+++ b/src/network/CrossPointWebServer.cpp
@@ -3,14 +3,17 @@
 #include <ArduinoJson.h>
 #include <Epub.h>
 #include <FsHelpers.h>
-#include <SDCardManager.h>
+#include <HalStorage.h>
 #include <WiFi.h>
 #include <esp_task_wdt.h>

 #include <algorithm>

+#include "CrossPointSettings.h"
+#include "SettingsList.h"
 #include "html/FilesPageHtml.generated.h"
 #include "html/HomePageHtml.generated.h"
+#include "html/SettingsPageHtml.generated.h"
 #include "util/StringUtils.h"

 namespace {
@@ -148,6 +151,11 @@ void CrossPointWebServer::begin() {
  // Delete file/folder endpoint
  server->on("/delete", HTTP_POST, [this] { handleDelete(); });

+  // Settings endpoints
+  server->on("/settings", HTTP_GET, [this] { handleSettingsPage(); });
+  server->on("/api/settings", HTTP_GET, [this] { handleGetSettings(); });
+  server->on("/api/settings", HTTP_POST, [this] { handlePostSettings(); });
+
  server->onNotFound([this] { handleNotFound(); });
  Serial.printf("[%lu] [WEB] [MEM] Free heap after route setup: %d bytes\n", millis(), ESP.getFreeHeap());

@@ -316,7 +324,7 @@ void CrossPointWebServer::handleStatus() const {
 }

 void CrossPointWebServer::scanFiles(const char* path, const std::function<void(FileInfo)>& callback) const {
-  FsFile root = SdMan.open(path);
+  FsFile root = Storage.open(path);
  if (!root) {
    Serial.printf("[%lu] [WEB] Failed to open directory: %s\n", millis(), path);
    return;
@@ -458,12 +466,12 @@ void CrossPointWebServer::handleDownload() const {
    }
  }

-  if (!SdMan.exists(itemPath.c_str())) {
+  if (!Storage.exists(itemPath.c_str())) {
    server->send(404, "text/plain", "Item not found");
    return;
  }

-  FsFile file = SdMan.open(itemPath.c_str());
+  FsFile file = Storage.open(itemPath.c_str());
  if (!file) {
    server->send(500, "text/plain", "Failed to open file");
    return;
@@ -574,15 +582,15 @@ void CrossPointWebServer::handleUpload(UploadState& state) const {

    // Check if file already exists - SD operations can be slow
    esp_task_wdt_reset();
-    if (SdMan.exists(filePath.c_str())) {
+    if (Storage.exists(filePath.c_str())) {
      Serial.printf("[%lu] [WEB] [UPLOAD] Overwriting existing file: %s\n", millis(), filePath.c_str());
      esp_task_wdt_reset();
-      SdMan.remove(filePath.c_str());
+      Storage.remove(filePath.c_str());
    }

    // Open file for writing - this can be slow due to FAT cluster allocation
    esp_task_wdt_reset();
-    if (!SdMan.openFileForWrite("WEB", filePath, state.file)) {
+    if (!Storage.openFileForWrite("WEB", filePath, state.file)) {
      state.error = "Failed to create file on SD card";
      Serial.printf("[%lu] [WEB] [UPLOAD] FAILED to create file: %s\n", millis(), filePath.c_str());
      return;
@@ -660,7 +668,7 @@ void CrossPointWebServer::handleUpload(UploadState& state) const {
      String filePath = state.path;
      if (!filePath.endsWith("/")) filePath += "/";
      filePath += state.fileName;
-      SdMan.remove(filePath.c_str());
+      Storage.remove(filePath.c_str());
    }
    state.error = "Upload aborted";
    Serial.printf("[%lu] [WEB] Upload aborted\n", millis());
@@ -711,13 +719,13 @@ void CrossPointWebServer::handleCreateFolder() const {
  Serial.printf("[%lu] [WEB] Creating folder: %s\n", millis(), folderPath.c_str());

  // Check if already exists
-  if (SdMan.exists(folderPath.c_str())) {
+  if (Storage.exists(folderPath.c_str())) {
    server->send(400, "text/plain", "Folder already exists");
    return;
  }

  // Create the folder
-  if (SdMan.mkdir(folderPath.c_str())) {
+  if (Storage.mkdir(folderPath.c_str())) {
    Serial.printf("[%lu] [WEB] Folder created successfully: %s\n", millis(), folderPath.c_str());
    server->send(200, "text/plain", "Folder created: " + folderName);
  } else {
@@ -763,12 +771,12 @@ void CrossPointWebServer::handleRename() const {
    return;
  }

-  if (!SdMan.exists(itemPath.c_str())) {
+  if (!Storage.exists(itemPath.c_str())) {
    server->send(404, "text/plain", "Item not found");
    return;
  }

-  FsFile file = SdMan.open(itemPath.c_str());
+  FsFile file = Storage.open(itemPath.c_str());
  if (!file) {
    server->send(500, "text/plain", "Failed to open file");
    return;
@@ -789,7 +797,7 @@ void CrossPointWebServer::handleRename() const {
  }
  newPath += newName;

-  if (SdMan.exists(newPath.c_str())) {
+  if (Storage.exists(newPath.c_str())) {
    file.close();
    server->send(409, "text/plain", "Target already exists");
    return;
@@ -839,12 +847,12 @@ void CrossPointWebServer::handleMove() const {
    }
  }

-  if (!SdMan.exists(itemPath.c_str())) {
+  if (!Storage.exists(itemPath.c_str())) {
    server->send(404, "text/plain", "Item not found");
    return;
  }

-  FsFile file = SdMan.open(itemPath.c_str());
+  FsFile file = Storage.open(itemPath.c_str());
  if (!file) {
    server->send(500, "text/plain", "Failed to open file");
    return;
@@ -855,12 +863,12 @@ void CrossPointWebServer::handleMove() const {
    return;
  }

-  if (!SdMan.exists(destPath.c_str())) {
+  if (!Storage.exists(destPath.c_str())) {
    file.close();
    server->send(404, "text/plain", "Destination not found");
    return;
  }
-  FsFile destDir = SdMan.open(destPath.c_str());
+  FsFile destDir = Storage.open(destPath.c_str());
  if (!destDir || !destDir.isDirectory()) {
    if (destDir) {
      destDir.close();
@@ -882,7 +890,7 @@ void CrossPointWebServer::handleMove() const {
    server->send(200, "text/plain", "Already in destination");
    return;
  }
-  if (SdMan.exists(newPath.c_str())) {
+  if (Storage.exists(newPath.c_str())) {
    file.close();
    server->send(409, "text/plain", "Target already exists");
    return;
@@ -942,7 +950,7 @@ void CrossPointWebServer::handleDelete() const {
  }

  // Check if item exists
-  if (!SdMan.exists(itemPath.c_str())) {
+  if (!Storage.exists(itemPath.c_str())) {
    Serial.printf("[%lu] [WEB] Delete failed - item not found: %s\n", millis(), itemPath.c_str());
    server->send(404, "text/plain", "Item not found");
    return;
@@ -954,7 +962,7 @@ void CrossPointWebServer::handleDelete() const {

  if (itemType == "folder") {
    // For folders, try to remove (will fail if not empty)
-    FsFile dir = SdMan.open(itemPath.c_str());
+    FsFile dir = Storage.open(itemPath.c_str());
    if (dir && dir.isDirectory()) {
      // Check if folder is empty
      FsFile entry = dir.openNextFile();
@@ -968,10 +976,10 @@ void CrossPointWebServer::handleDelete() const {
      }
      dir.close();
    }
-    success = SdMan.rmdir(itemPath.c_str());
+    success = Storage.rmdir(itemPath.c_str());
  } else {
    // For files, use remove
-    success = SdMan.remove(itemPath.c_str());
+    success = Storage.remove(itemPath.c_str());
  }

  if (success) {
@@ -983,6 +991,168 @@ void CrossPointWebServer::handleDelete() const {
  }
 }

+void CrossPointWebServer::handleSettingsPage() const {
+  server->send(200, "text/html", SettingsPageHtml);
+  Serial.printf("[%lu] [WEB] Served settings page\n", millis());
+}
+
+void CrossPointWebServer::handleGetSettings() const {
+  auto settings = getSettingsList();
+
+  server->setContentLength(CONTENT_LENGTH_UNKNOWN);
+  server->send(200, "application/json", "");
+  server->sendContent("[");
+
+  char output[512];
+  constexpr size_t outputSize = sizeof(output);
+  bool seenFirst = false;
+  JsonDocument doc;
+
+  for (const auto& s : settings) {
+    if (!s.key) continue;  // Skip ACTION-only entries
+
+    doc.clear();
+    doc["key"] = s.key;
+    doc["name"] = s.name;
+    doc["category"] = s.category;
+
+    switch (s.type) {
+      case SettingType::TOGGLE: {
+        doc["type"] = "toggle";
+        if (s.valuePtr) {
+          doc["value"] = static_cast<int>(SETTINGS.*(s.valuePtr));
+        }
+        break;
+      }
+      case SettingType::ENUM: {
+        doc["type"] = "enum";
+        if (s.valuePtr) {
+          doc["value"] = static_cast<int>(SETTINGS.*(s.valuePtr));
+        } else if (s.valueGetter) {
+          doc["value"] = static_cast<int>(s.valueGetter());
+        }
+        JsonArray options = doc["options"].to<JsonArray>();
+        for (const auto& opt : s.enumValues) {
+          options.add(opt);
+        }
+        break;
+      }
+      case SettingType::VALUE: {
+        doc["type"] = "value";
+        if (s.valuePtr) {
+          doc["value"] = static_cast<int>(SETTINGS.*(s.valuePtr));
+        }
+        doc["min"] = s.valueRange.min;
+        doc["max"] = s.valueRange.max;
+        doc["step"] = s.valueRange.step;
+        break;
+      }
+      case SettingType::STRING: {
+        doc["type"] = "string";
+        if (s.stringGetter) {
+          doc["value"] = s.stringGetter();
+        } else if (s.stringPtr) {
+          doc["value"] = s.stringPtr;
+        }
+        break;
+      }
+      default:
+        continue;
+    }
+
+    const size_t written = serializeJson(doc, output, outputSize);
+    if (written >= outputSize) {
+      Serial.printf("[%lu] [WEB] Skipping oversized setting JSON for: %s\n", millis(), s.key);
+      continue;
+    }
+
+    if (seenFirst) {
+      server->sendContent(",");
+    } else {
+      seenFirst = true;
+    }
+    server->sendContent(output);
+  }
+
+  server->sendContent("]");
+  server->sendContent("");
+  Serial.printf("[%lu] [WEB] Served settings API\n", millis());
+}
+
+void CrossPointWebServer::handlePostSettings() {
+  if (!server->hasArg("plain")) {
+    server->send(400, "text/plain", "Missing JSON body");
+    return;
+  }
+
+  const String body = server->arg("plain");
+  JsonDocument doc;
+  const DeserializationError err = deserializeJson(doc, body);
+  if (err) {
+    server->send(400, "text/plain", String("Invalid JSON: ") + err.c_str());
+    return;
+  }
+
+  auto settings = getSettingsList();
+  int applied = 0;
+
+  for (auto& s : settings) {
+    if (!s.key) continue;
+    if (!doc[s.key].is<JsonVariant>()) continue;
+
+    switch (s.type) {
+      case SettingType::TOGGLE: {
+        const int val = doc[s.key].as<int>() ? 1 : 0;
+        if (s.valuePtr) {
+          SETTINGS.*(s.valuePtr) = val;
+        }
+        applied++;
+        break;
+      }
+      case SettingType::ENUM: {
+        const int val = doc[s.key].as<int>();
+        if (val >= 0 && val < static_cast<int>(s.enumValues.size())) {
+          if (s.valuePtr) {
+            SETTINGS.*(s.valuePtr) = static_cast<uint8_t>(val);
+          } else if (s.valueSetter) {
+            s.valueSetter(static_cast<uint8_t>(val));
+          }
+          applied++;
+        }
+        break;
+      }
+      case SettingType::VALUE: {
+        const int val = doc[s.key].as<int>();
+        if (val >= s.valueRange.min && val <= s.valueRange.max) {
+          if (s.valuePtr) {
+            SETTINGS.*(s.valuePtr) = static_cast<uint8_t>(val);
+          }
+          applied++;
+        }
+        break;
+      }
+      case SettingType::STRING: {
+        const std::string val = doc[s.key].as<std::string>();
+        if (s.stringSetter) {
+          s.stringSetter(val);
+        } else if (s.stringPtr && s.stringMaxLen > 0) {
+          strncpy(s.stringPtr, val.c_str(), s.stringMaxLen - 1);
+          s.stringPtr[s.stringMaxLen - 1] = '\0';
+        }
+        applied++;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  SETTINGS.saveToFile();
+
+  Serial.printf("[%lu] [WEB] Applied %d setting(s)\n", millis(), applied);
+  server->send(200, "text/plain", String("Applied ") + String(applied) + " setting(s)");
+}
+
 // WebSocket callback trampoline
 void CrossPointWebServer::wsEventCallback(uint8_t num, WStype_t type, uint8_t* payload, size_t length) {
  if (wsInstance) {
@@ -1007,7 +1177,7 @@ void CrossPointWebServer::onWebSocketEvent(uint8_t num, WStype_t type, uint8_t*
        String filePath = wsUploadPath;
        if (!filePath.endsWith("/")) filePath += "/";
        filePath += wsUploadFileName;
-        SdMan.remove(filePath.c_str());
+        Storage.remove(filePath.c_str());
        Serial.printf("[%lu] [WS] Deleted incomplete upload: %s\n", millis(), filePath.c_str());
      }
      wsUploadInProgress = false;
@@ -1051,13 +1221,13 @@ void CrossPointWebServer::onWebSocketEvent(uint8_t num, WStype_t type, uint8_t*

          // Check if file exists and remove it
          esp_task_wdt_reset();
-          if (SdMan.exists(filePath.c_str())) {
-            SdMan.remove(filePath.c_str());
+          if (Storage.exists(filePath.c_str())) {
+            Storage.remove(filePath.c_str());
          }

          // Open file for writing
          esp_task_wdt_reset();
-          if (!SdMan.openFileForWrite("WS", filePath, wsUploadFile)) {
+          if (!Storage.openFileForWrite("WS", filePath, wsUploadFile)) {
            wsServer->sendTXT(num, "ERROR:Failed to create file");
            wsUploadInProgress = false;
            return;
--- a/src/network/CrossPointWebServer.h
+++ b/src/network/CrossPointWebServer.h
@@ -1,6 +1,6 @@
 #pragma once

-#include <SDCardManager.h>
+#include <HalStorage.h>
 #include <WebServer.h>
 #include <WebSocketsServer.h>
 #include <WiFiUdp.h>
@@ -100,4 +100,9 @@ class CrossPointWebServer {
  void handleRename() const;
  void handleMove() const;
  void handleDelete() const;
+
+  // Settings handlers
+  void handleSettingsPage() const;
+  void handleGetSettings() const;
+  void handlePostSettings();
 };
--- a/src/network/HttpDownloader.cpp
+++ b/src/network/HttpDownloader.cpp
@@ -100,13 +100,13 @@ HttpDownloader::DownloadError HttpDownloader::downloadToFile(const std::string&
  Serial.printf("[%lu] [HTTP] Content-Length: %zu\n", millis(), contentLength);

  // Remove existing file if present
-  if (SdMan.exists(destPath.c_str())) {
-    SdMan.remove(destPath.c_str());
+  if (Storage.exists(destPath.c_str())) {
+    Storage.remove(destPath.c_str());
  }

  // Open file for writing
  FsFile file;
-  if (!SdMan.openFileForWrite("HTTP", destPath.c_str(), file)) {
+  if (!Storage.openFileForWrite("HTTP", destPath.c_str(), file)) {
    Serial.printf("[%lu] [HTTP] Failed to open file for writing\n", millis());
    http.end();
    return FILE_ERROR;
@@ -117,7 +117,7 @@ HttpDownloader::DownloadError HttpDownloader::downloadToFile(const std::string&
  if (!stream) {
    Serial.printf("[%lu] [HTTP] Failed to get stream\n", millis());
    file.close();
-    SdMan.remove(destPath.c_str());
+    Storage.remove(destPath.c_str());
    http.end();
    return HTTP_ERROR;
  }
@@ -145,7 +145,7 @@ HttpDownloader::DownloadError HttpDownloader::downloadToFile(const std::string&
    if (written != bytesRead) {
      Serial.printf("[%lu] [HTTP] Write failed: wrote %zu of %zu bytes\n", millis(), written, bytesRead);
      file.close();
-      SdMan.remove(destPath.c_str());
+      Storage.remove(destPath.c_str());
      http.end();
      return FILE_ERROR;
    }
@@ -165,7 +165,7 @@ HttpDownloader::DownloadError HttpDownloader::downloadToFile(const std::string&
  // Verify download size if known
  if (contentLength > 0 && downloaded != contentLength) {
    Serial.printf("[%lu] [HTTP] Size mismatch: got %zu, expected %zu\n", millis(), downloaded, contentLength);
-    SdMan.remove(destPath.c_str());
+    Storage.remove(destPath.c_str());
    return HTTP_ERROR;
  }

--- a/src/network/HttpDownloader.h
+++ b/src/network/HttpDownloader.h
@@ -1,5 +1,5 @@
 #pragma once
-#include <SDCardManager.h>
+#include <HalStorage.h>

 #include <functional>
 #include <string>
--- a/src/network/html/FilesPage.html
+++ b/src/network/html/FilesPage.html
@@ -628,6 +628,7 @@
 <div class="nav-links">
  <a href="/">Home</a>
  <a href="/files">File Manager</a>
+  <a href="/settings">Settings</a>
 </div>

 <div class="page-header">
--- a/src/network/html/HomePage.html
+++ b/src/network/html/HomePage.html
@@ -77,6 +77,7 @@
    <div class="nav-links">
      <a href="/">Home</a>
      <a href="/files">File Manager</a>
+      <a href="/settings">Settings</a>
    </div>

    <div class="card">
--- a/src/network/html/SettingsPage.html
+++ b/src/network/html/SettingsPage.html
@@ -0,0 +1,414 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>CrossPoint Reader - Settings</title>
+  <style>
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+        Oxygen, Ubuntu, sans-serif;
+      max-width: 800px;
+      margin: 0 auto;
+      padding: 20px;
+      background-color: #f5f5f5;
+      color: #333;
+    }
+    h1 {
+      color: #2c3e50;
+      border-bottom: 2px solid #3498db;
+      padding-bottom: 10px;
+    }
+    h2 {
+      color: #34495e;
+      margin-top: 0;
+    }
+    .card {
+      background: white;
+      border-radius: 8px;
+      padding: 20px;
+      margin: 15px 0;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+    }
+    .nav-links {
+      margin: 20px 0;
+    }
+    .nav-links a {
+      display: inline-block;
+      padding: 10px 20px;
+      background-color: #3498db;
+      color: white;
+      text-decoration: none;
+      border-radius: 4px;
+      margin-right: 10px;
+    }
+    .nav-links a:hover {
+      background-color: #2980b9;
+    }
+    .setting-row {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      padding: 10px 0;
+      border-bottom: 1px solid #eee;
+    }
+    .setting-row:last-child {
+      border-bottom: none;
+    }
+    .setting-name {
+      font-weight: 500;
+      color: #2c3e50;
+      flex: 1;
+      min-width: 0;
+      padding-right: 12px;
+    }
+    .setting-control {
+      flex-shrink: 0;
+    }
+    .setting-control select,
+    .setting-control input[type="number"],
+    .setting-control input[type="text"],
+    .setting-control input[type="password"] {
+      padding: 6px 10px;
+      border: 1px solid #ddd;
+      border-radius: 4px;
+      font-size: 0.95em;
+      background: white;
+    }
+    .setting-control select {
+      min-width: 160px;
+    }
+    .setting-control input[type="text"],
+    .setting-control input[type="password"] {
+      width: 220px;
+    }
+    .setting-control input[type="number"] {
+      width: 80px;
+    }
+    /* Toggle switch */
+    .toggle-switch {
+      display: inline-block;
+      position: relative;
+      width: 48px;
+      height: 26px;
+    }
+    .toggle-switch input {
+      opacity: 0;
+      width: 0;
+      height: 0;
+    }
+    .toggle-slider {
+      position: absolute;
+      cursor: pointer;
+      top: 0; left: 0; right: 0; bottom: 0;
+      background-color: #ccc;
+      border-radius: 26px;
+      transition: 0.3s;
+    }
+    .toggle-slider:before {
+      position: absolute;
+      content: "";
+      height: 20px;
+      width: 20px;
+      left: 3px;
+      bottom: 3px;
+      background-color: white;
+      border-radius: 50%;
+      transition: 0.3s;
+    }
+    .toggle-switch input:checked + .toggle-slider {
+      background-color: #27ae60;
+    }
+    .toggle-switch input:checked + .toggle-slider:before {
+      transform: translateX(22px);
+    }
+    .save-container {
+      text-align: center;
+      margin: 20px 0;
+    }
+    .save-btn {
+      background-color: #27ae60;
+      color: white;
+      padding: 12px 40px;
+      border: none;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 1.1em;
+      font-weight: 600;
+    }
+    .save-btn:hover {
+      background-color: #219a52;
+    }
+    .save-btn:disabled {
+      background-color: #95a5a6;
+      cursor: not-allowed;
+    }
+    .message {
+      padding: 12px;
+      border-radius: 4px;
+      margin: 15px 0;
+      text-align: center;
+      display: none;
+    }
+    .message.success {
+      background-color: #d4edda;
+      color: #155724;
+      border: 1px solid #c3e6cb;
+    }
+    .message.error {
+      background-color: #f8d7da;
+      color: #721c24;
+      border: 1px solid #f5c6cb;
+    }
+    .loader-container {
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      margin: 20px 0;
+    }
+    .loader {
+      width: 48px;
+      height: 48px;
+      border: 5px solid #AAA;
+      border-bottom-color: transparent;
+      border-radius: 50%;
+      display: inline-block;
+      box-sizing: border-box;
+      animation: rotation 1s linear infinite;
+    }
+    @keyframes rotation {
+      from { transform: rotate(0deg); }
+      to { transform: rotate(360deg); }
+    }
+    @media (max-width: 600px) {
+      body {
+        padding: 10px;
+        font-size: 14px;
+      }
+      .card {
+        padding: 12px;
+        margin: 10px 0;
+      }
+      h1 {
+        font-size: 1.3em;
+      }
+      .nav-links a {
+        padding: 8px 12px;
+        margin-right: 6px;
+        font-size: 0.9em;
+      }
+      .setting-row {
+        flex-wrap: wrap;
+        gap: 6px;
+      }
+      .setting-control select,
+      .setting-control input[type="text"],
+      .setting-control input[type="password"] {
+        min-width: 0;
+        width: 100%;
+      }
+    }
+  </style>
+</head>
+<body>
+  <h1>⚙️ Settings</h1>
+
+  <div class="nav-links">
+    <a href="/">Home</a>
+    <a href="/files">File Manager</a>
+    <a href="/settings">Settings</a>
+  </div>
+
+  <div id="message" class="message"></div>
+
+  <div id="settings-container">
+    <div class="loader-container">
+      <span class="loader"></span>
+    </div>
+  </div>
+
+  <div class="save-container" id="save-container" style="display:none;">
+    <button class="save-btn" id="saveBtn" onclick="saveSettings()">Save Settings</button>
+  </div>
+
+  <div class="card">
+    <p style="text-align: center; color: #95a5a6; margin: 0;">
+      CrossPoint E-Reader • Open Source
+    </p>
+  </div>
+
+<script>
+  let allSettings = [];
+  let originalValues = {};
+
+  function escapeHtml(unsafe) {
+    return unsafe
+      .replaceAll("&", "&amp;")
+      .replaceAll("<", "&lt;")
+      .replaceAll(">", "&gt;")
+      .replaceAll('"', "&quot;")
+      .replaceAll("'", "&#039;");
+  }
+
+  function showMessage(text, isError) {
+    const msg = document.getElementById('message');
+    msg.textContent = text;
+    msg.className = 'message ' + (isError ? 'error' : 'success');
+    msg.style.display = 'block';
+    setTimeout(function() { msg.style.display = 'none'; }, 4000);
+  }
+
+  function renderControl(setting) {
+    const id = 'setting-' + setting.key;
+
+    if (setting.type === 'toggle') {
+      const checked = setting.value ? 'checked' : '';
+      return '<label class="toggle-switch">' +
+        '<input type="checkbox" id="' + id + '" ' + checked + ' onchange="markChanged()">' +
+        '<span class="toggle-slider"></span></label>';
+    }
+
+    if (setting.type === 'enum') {
+      let html = '<select id="' + id + '" onchange="markChanged()">';
+      setting.options.forEach(function(opt, idx) {
+        const selected = idx === setting.value ? ' selected' : '';
+        html += '<option value="' + idx + '"' + selected + '>' + escapeHtml(opt) + '</option>';
+      });
+      html += '</select>';
+      return html;
+    }
+
+    if (setting.type === 'value') {
+      return '<input type="number" id="' + id + '" value="' + setting.value + '"' +
+        ' min="' + setting.min + '" max="' + setting.max + '" step="' + setting.step + '"' +
+        ' onchange="markChanged()">';
+    }
+
+    if (setting.type === 'string') {
+      const inputType = setting.name.toLowerCase().includes('password') ? 'password' : 'text';
+      const val = setting.value || '';
+      return '<input type="' + inputType + '" id="' + id + '" value="' + escapeHtml(val) + '"' +
+        ' oninput="markChanged()">';
+    }
+
+    return '';
+  }
+
+  function getValue(setting) {
+    const el = document.getElementById('setting-' + setting.key);
+    if (!el) return undefined;
+
+    if (setting.type === 'toggle') {
+      return el.checked ? 1 : 0;
+    }
+    if (setting.type === 'enum') {
+      return parseInt(el.value, 10);
+    }
+    if (setting.type === 'value') {
+      return parseInt(el.value, 10);
+    }
+    if (setting.type === 'string') {
+      return el.value;
+    }
+    return undefined;
+  }
+
+  function markChanged() {
+    document.getElementById('saveBtn').disabled = false;
+  }
+
+  async function loadSettings() {
+    try {
+      const response = await fetch('/api/settings');
+      if (!response.ok) {
+        throw new Error('Failed to load settings: ' + response.status);
+      }
+      allSettings = await response.json();
+
+      // Store original values
+      originalValues = {};
+      allSettings.forEach(function(s) {
+        originalValues[s.key] = s.value;
+      });
+
+      // Group by category
+      const groups = {};
+      allSettings.forEach(function(s) {
+        if (!groups[s.category]) groups[s.category] = [];
+        groups[s.category].push(s);
+      });
+
+      const container = document.getElementById('settings-container');
+      let html = '';
+
+      for (const category in groups) {
+        html += '<div class="card"><h2>' + escapeHtml(category) + '</h2>';
+        groups[category].forEach(function(s) {
+          html += '<div class="setting-row">' +
+            '<span class="setting-name">' + escapeHtml(s.name) + '</span>' +
+            '<span class="setting-control">' + renderControl(s) + '</span>' +
+            '</div>';
+        });
+        html += '</div>';
+      }
+
+      container.innerHTML = html;
+      document.getElementById('save-container').style.display = '';
+      document.getElementById('saveBtn').disabled = true;
+    } catch (e) {
+      console.error(e);
+      document.getElementById('settings-container').innerHTML =
+        '<div class="card"><p style="text-align:center;color:#e74c3c;">Failed to load settings</p></div>';
+    }
+  }
+
+  async function saveSettings() {
+    const btn = document.getElementById('saveBtn');
+    btn.disabled = true;
+    btn.textContent = 'Saving...';
+
+    // Collect only changed values
+    const changes = {};
+    allSettings.forEach(function(s) {
+      const current = getValue(s);
+      if (current !== undefined && current !== originalValues[s.key]) {
+        changes[s.key] = current;
+      }
+    });
+
+    if (Object.keys(changes).length === 0) {
+      showMessage('No changes to save.', false);
+      btn.textContent = 'Save Settings';
+      return;
+    }
+
+    try {
+      const response = await fetch('/api/settings', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(changes)
+      });
+
+      if (!response.ok) {
+        const text = await response.text();
+        throw new Error(text || 'Save failed');
+      }
+
+      // Update original values to new values
+      for (const key in changes) {
+        originalValues[key] = changes[key];
+      }
+
+      showMessage('Settings saved successfully!', false);
+    } catch (e) {
+      console.error(e);
+      showMessage('Error: ' + e.message, true);
+    }
+
+    btn.textContent = 'Save Settings';
+  }
+
+  loadSettings();
+</script>
+</body>
+</html>
Author	SHA1	Message	Date
cottongin	4edb14bdd9	feat: Sleep screen letterbox fill and image upscaling Some checks failed CI (build) / clang-format (push) Has been cancelled Details CI (build) / cppcheck (push) Has been cancelled Details CI (build) / build (push) Has been cancelled Details CI (build) / Test Status (push) Has been cancelled Details Add configurable letterbox fill for sleep screen cover images that don't match the display aspect ratio. Four fill modes are available: Solid (single dominant edge shade), Blended (per-pixel edge colors), Gradient (edge colors interpolated toward white/black), and None. Enable upscaling of cover images smaller than the display in Fit mode by modifying drawBitmap/drawBitmap1Bit to support both up and downscaling via a unified block-fill approach. Edge sampling data is cached to .crosspoint alongside the cover BMP to avoid redundant bitmap scanning on subsequent sleeps. Cache is validated against screen dimensions and auto-regenerated when stale. New settings: Letterbox Fill (None/Solid/Blended/Gradient) and Gradient Direction (To White/To Black). Co-authored-by: Cursor <cursoragent@cursor.com>	2026-02-09 11:52:55 -05:00
cottongin	a85d5e627b	.gitignore tweaks for mod fork	2026-02-09 04:15:00 -05:00
Dave Allie	6202bfd651	Merge branch 'release/1.0.0'	2026-02-09 17:18:24 +11:00
Jake Kenneally	9b04c2ec76	feat: Add percentage support to CSS properties (#738 ) ## Summary - Closes #730 What is the goal of this PR? - Adds percentage-based value support to CSS properties that accept percentages (padding, margin, text-indent) What changes are included? - Adds `Percent` as another CSS unit - Passes the viewport width to `fromCssStyle` so that we can resolve percentage-based values - Adds a fallback of using an emspace for text-indent if we have an unresolvable value for whatever reason ## Additional Context - This was missed in my CSS support feature, and the fallback when we encounter a percentage value is to use px instead. This means 5% (which would be ~30px on the screen) turns into 5px. When percentages are used in `text-indent`, this fallback behavior makes the indent look like a single space character. Whoops! 😬 My test EPUB has been updated [here](https://github.com/jdk2pq/css-test-epub) with percentage based CSS values at the end of the book. --- ### 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_, Claude Code	2026-02-09 08:31:52 +11:00
Dave Allie	ffddc2472b	Use GITHUB_REF_NAME over GITHUB_HEAD_REF in release candidate workflow	2026-02-09 08:22:20 +11:00
Dave Allie	5765bbe821	Add release candidate workflow	2026-02-09 08:16:36 +11:00
Dave Allie	b4b028be3a	fix: Allow OTA update from RC build to full release (#778 ) ## Summary * Allow OTA update from RC build to full release * If all the segments match, then also check if the current version contains "-rc" --- ### 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? No	2026-02-09 08:08:19 +11:00
Yaroslav	f34d7d2aac	fix(ui): Add Back label in KOReader Sync screen (#770 ) ## Summary - Remove duplicate Cancel option - Add Back label <img width="435" height="613" alt="image" src="https://github.com/user-attachments/assets/a3af4133-46fa-46e6-8360-a15dd7c4fe2a" /> ## Result <img width="575" height="431" alt="image" src="https://github.com/user-attachments/assets/6ccdac89-43df-45bf-bcfa-3a7cc4bd88e4" /> --- ### AI Usage Did you use AI tools to help write this code? _< PARTIALLY >_ Closes #754	2026-02-09 07:51:51 +11:00
Justin Mitchell	71769490fb	fix: Add EPUB 3 cover image detection (#760 ) I had an epub that just showed a blank cover and wouldnt work for the sleep screen either, turns out it was an epub3 and I guess we didn't support that. Super simple fix here	2026-02-09 07:49:49 +11:00
Jesse Vincent	cda0a3f898	feat: A web editor for settings (#667 ) ## Summary This is an updated version of @itsthisjustin's #346 that builds on current master and also deduplicates the settings list so we don't have two copies of the settings. In the Web UI, it should organize the settings a little closer to what you see on device. ## Additional Context I tested this live on device and it seems to play nicely for me. It's re-based on master since master's settings stuff has moved somewhat since the original PR and addresses the sole review comment #346 - it also means that I don't need to manually key in the URL for my OPDS server. :) --- ### AI Usage My changes were implemented with Claude Opus 4.5 and Claude Code 2.1.25. I don't know if @itsthisjustin's original work used AI assistance. Co-authored-by: Dave Allie <dave@daveallie.com>	2026-02-09 07:46:14 +11:00
Xuan-Son Nguyen	7f40c3f477	feat: add HalStorage (#656 ) ## Summary Continue my changes to introduce the HAL infrastructure from https://github.com/crosspoint-reader/crosspoint-reader/pull/522 This PR touches quite a lot of files, but most of them are just name changing. It should not have any impacts to the end behavior. ## Additional Context My plan is to firstly add this small shim layer, which sounds useless at first, but then I'll implement an emulated driver which can be helpful for testing and for development. Currently, on my fork, I'm using a FS driver that allow "mounting" a local directory from my computer to the device, much like the `-v` mount option on docker. This allows me to quickly reset `.crosspoint` directory if anything goes wrong. I plan to upstream this feature when this PR get merged. --- ### 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? NO	2026-02-09 07:29:14 +11:00
Xuan-Son Nguyen	a87eacc6ab	perf: optimize drawPixel() (#748 ) ## Summary Ref https://github.com/crosspoint-reader/crosspoint-reader/pull/737 This PR further reduce ~25ms from rendering time, testing inside the Setting screen: ``` master: [68440] [GFX] Time = 73 ms from clearScreen to displayBuffer PR: [97806] [GFX] Time = 47 ms from clearScreen to displayBuffer ``` And in extreme case (fill the entire screen with black or gray color): ``` master: [1125] [ ] Test fillRectDither drawn in 327 ms [1347] [ ] Test fillRect drawn in 222 ms PR: [1334] [ ] Test fillRectDither drawn in 225 ms [1455] [ ] Test fillRect drawn in 121 ms ``` Note that https://github.com/crosspoint-reader/crosspoint-reader/pull/737 is NOT applied on top of this PR. But with 2 of them combined, it should reduce from 47ms --> 42ms ## Details This PR based on the fact that function calls are costly if the function is small enough. For example, this simple call: ``` int rotatedX = 0; int rotatedY = 0; rotateCoordinates(x, y, &rotatedX, &rotatedY); ``` Generated assembly code: <img width="771" height="215" alt="image" src="https://github.com/user-attachments/assets/37991659-3304-41c3-a3b2-fb967da53f82" /> This adds ~10 instructions just to prepare the registers prior to the function call, plus some more instructions for the function's epilogue/prologue. Inlining it removing all of these: <img width="1471" height="832" alt="image" src="https://github.com/user-attachments/assets/b67a22ee-93ba-4017-88ed-c973e28ec914" /> Of course, this optimization is not magic. It's only beneficial under 3 conditions: - The function is small, not in size, but in terms of effective instructions. For example, the `rotateCoordinates` is simply a jump table, where each branch is just 3-4 inst - The function has multiple input arguments, which requires some move to put it onto the correct place - The function is called very frequently (i.e. critical path) --- ### 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? NO	2026-02-09 05:05:42 +11:00
Arthur Tazhitdinov	1caad578fc	feat: wakeup target detection (#731 ) ## Summary * If going to sleep was from the Reader view, wake up to the same book. Otherwise, wakeup to the Home view	2026-02-09 05:01:30 +11:00
CaptainFrito	5b90b68e99	fix: Scrolling page items calculation (#716 ) ## Summary Fix for the page skip issue detected https://github.com/crosspoint-reader/crosspoint-reader/pull/700#issuecomment-3856374323 by user @whyte-j Skipping down on the last page now skips to the last item, and up on the first page to the first item, rather than wrapping around the list in a weird way. ## Additional Context The calculation was outdated after several changes were added afterwards --- ### 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? _NO_	2026-02-09 04:58:46 +11:00
Jake Kenneally	67ddd60fce	refactor: Rename "Embedded Style" to "Book's Embedded Style" (#746 ) ## Summary What is the goal of this PR? - Just a simple rename after feedback in #738 What changes are included? - Renamed "Embedded Style" to "Book's Embedded Style" to more clearly associate it with "Book's Style" option in "Paragraph Alignment" settings --- ### 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? _NO_	2026-02-08 20:34:06 +03:00
Xuan-Son Nguyen	76908d38e1	feat: optimize fillRectDither (#737 ) ## Summary This PR optimizes the `fillRectDither` function, making it as fast as a normal `fillRect` Testing code: ```cpp { auto start_t = millis(); renderer.fillRectDither(0, 0, renderer.getScreenWidth(), renderer.getScreenHeight(), Color::LightGray); auto elapsed = millis() - start_t; Serial.printf("[%lu] [ ] Test fillRectDither drawn in %lu ms\n", millis(), elapsed); } { auto start_t = millis(); renderer.fillRect(0, 0, renderer.getScreenWidth(), renderer.getScreenHeight(), true); auto elapsed = millis() - start_t; Serial.printf("[%lu] [ ] Test fillRect drawn in %lu ms\n", millis(), elapsed); } ``` Before: ``` [1125] [ ] Test fillRectDither drawn in 327 ms [1347] [ ] Test fillRect drawn in 222 ms ``` After: ``` [1065] [ ] Test fillRectDither drawn in 238 ms [1287] [ ] Test fillRect drawn in 222 ms ``` ## Visual validation Before: <img width="415" height="216" alt="Screenshot 2026-02-07 at 01 04 19" src="https://github.com/user-attachments/assets/5802dbba-187b-4d2b-a359-1318d3932d38" /> After: <img width="420" height="191" alt="Screenshot 2026-02-07 at 01 36 30" src="https://github.com/user-attachments/assets/3c3c8e14-3f3a-4205-be78-6ed771dcddf4" /> ## Details The original version is quite slow because it does quite a lot of computations. A single pixel needs around 20 instructions just to know if it's black or white: <img width="1170" height="693" alt="Screenshot 2026-02-07 at 00 15 54" src="https://github.com/user-attachments/assets/7c5a55e7-0598-4340-8b7b-17307d7921cb" /> With the new, templated and more light-weight approach, each pixel takes only 3-4 instructions, the modulo operator is translated into bitwise ops: <img width="1175" height="682" alt="Screenshot 2026-02-07 at 01 47 51" src="https://github.com/user-attachments/assets/4ec2cf74-6cc0-4b5b-87d5-831563ef164f" /> --- ### 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? NO	2026-02-08 14:59:13 +03:00
Arthur Tazhitdinov	e6f5fa43e6	feat(ux): invert BACK button behavior in reader activities (#726 ) ## Summary * Inverts back button behaviour while reading - short press to go home, long press to open file browser ## Additional Context * It seems counterintuitive that going into a book from home screen and pressing back doesn’t take you back to the home screen. With the recent books now displayed in the home view and a separate recents view, going directly to the file browser is less necessary.	2026-02-07 10:17:00 -05:00
James Whyte	e7e31ac487	fix: increase lyra sideButtonHintsWidth to 30 (#727 ) ## Summary Increase the width of Lyra's side button hints. It has been set to 30, the same width as the classic theme. Before: <img width="457" height="742" alt="image" src="https://github.com/user-attachments/assets/316e4679-fbf0-4f6e-b117-413075da1be2" /> After: <img width="512" height="849" alt="image" src="https://github.com/user-attachments/assets/3b0cf069-55ad-4d5a-a93c-4aeca3ff67f8" /> ## Additional Context Resolves https://github.com/crosspoint-reader/crosspoint-reader/pull/700#issuecomment-3856983832 --- ### 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? No	2026-02-07 10:15:41 -05:00
Jake Kenneally	9f78fd33e8	fix: Remove separations after style changes (#720 ) Closes #182. Closes #710. Closes #711. ## Summary What is the goal of this PR? - A longer-term, more robust fix for the issue with spurious spaces appearing after style changes. Replaces solution from #694. What changes are included? - Add continuation flags to determine if to add a space after a word or if the word connects to the previous word. Replaces simple solution that only considered ending punctuation. - Fixed an issue with greedy line-breaking algorithm where punctuation could appear on the next line, separated from the word, if there was a style change between the word and punctuation --- ### 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_, Claude Code	2026-02-06 19:10:37 +11:00
CaptainFrito	bd8132a260	fix: Lag before displaying covers on home screen (#721 ) ## Summary Reduce/fix the lag on the home screen before recent book covers are rendered ## Additional Context We were previously rendering the screen in two steps, delaying the recent book covers render to avoid a lag before the screen loads. In this PR, we are now doing that only if at least one book doesn't have the cover thumbnail generated yet. If all thumbs are already generated, we load and display them right away, with no lag. --- ### 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? _NO _	2026-02-06 18:58:32 +11:00
Jake Kenneally	f89ce514c8	feat: Add Settings for toggling CSS on or off (#717 ) Closes #712 ## Summary What is the goal of this PR? - To add new settings for toggling on/off embedded CSS styles in the reader. This gives more control and customization to the user over how the ereader experience looks. What changes are included? - Added new "Embedded Style" option to the Reader settings - Added new "Book's Style" option for "Paragraph Alignment" - User's selected "Paragraph Alignment" will take precedence and override the embedded CSS `text-align` property, _unless_ the user has "Book's Style" set as their "Paragraph Alignment" ## Additional Context ![IMG_6336](https://github.com/user-attachments/assets/dff619ef-986d-465e-b352-73a76baae334) https://github.com/user-attachments/assets/9e404b13-c7e0-41c7-9406-4715f389166a Addresses feedback from the community about the new CSS feature: https://github.com/crosspoint-reader/crosspoint-reader/pull/700 --- ### 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_, Claude Code	2026-02-06 18:49:04 +11:00