Add TXT file reader support (#240)

## Summary

* **What is the goal of this PR?** 

Add support for reading plain text (.txt) files, enabling users to
browse, read, and track progress in TXT documents alongside existing
EPUB and XTC formats.

* **What changes are included?**

- New Txt library for loading and parsing plain text files
- New TxtReaderActivity with streaming page rendering using 8KB chunks
to handle large files without memory issues on ESP32-C3
- Page index caching system (index.bin) for instant re-open after sleep
or app restart
- Progress bar UI during initial file indexing (matching EPUB style)
- Word wrapping with proper UTF-8 support
- Cover image support for TXT files:
- Primary: image with same filename as TXT (e.g., book.jpg for book.txt)
  - Fallback: cover.bmp/jpg/jpeg in the same folder
  - JPG to BMP conversion using existing converter
  - Sleep screen cover mode now works with TXT files
- File browser now shows .txt files

## Additional Context

* Add any other information that might be helpful for the reviewer

* Memory constraints: The streaming approach was necessary because
ESP32-C3 only has 320KB RAM. A 700KB TXT file cannot be loaded entirely
into memory, so we read 8KB chunks and build a page offset index
instead.

* Cache invalidation: The page index cache automatically invalidates
when file size, viewport width, or lines per page changes (e.g., font
size or orientation change).

* Performance: First open requires indexing (with progress bar),
subsequent opens load from cache instantly.

* Cover image format: PNG is detected but not supported for conversion
(no PNG decoder available). Only BMP and JPG/JPEG work.

lib/Txt/Txt.cpp

@@ -0,0 +1,191 @@
+#include "Txt.h"
+
+#include <FsHelpers.h>
+#include <JpegToBmpConverter.h>
+
+Txt::Txt(std::string path, std::string cacheBasePath)
+    : filepath(std::move(path)), cacheBasePath(std::move(cacheBasePath)) {
+  // Generate cache path from file path hash
+  const size_t hash = std::hash<std::string>{}(filepath);
+  cachePath = this->cacheBasePath + "/txt_" + std::to_string(hash);
+}
+
+bool Txt::load() {
+  if (loaded) {
+    return true;
+  }
+
+  if (!SdMan.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)) {
+    Serial.printf("[%lu] [TXT] Failed to open file: %s\n", millis(), filepath.c_str());
+    return false;
+  }
+
+  fileSize = file.size();
+  file.close();
+
+  loaded = true;
+  Serial.printf("[%lu] [TXT] Loaded TXT file: %s (%zu bytes)\n", millis(), filepath.c_str(), fileSize);
+  return true;
+}
+
+std::string Txt::getTitle() const {
+  // Extract filename without path and extension
+  size_t lastSlash = filepath.find_last_of('/');
+  std::string filename = (lastSlash != std::string::npos) ? filepath.substr(lastSlash + 1) : filepath;
+
+  // Remove .txt extension
+  if (filename.length() >= 4 && filename.substr(filename.length() - 4) == ".txt") {
+    filename = filename.substr(0, filename.length() - 4);
+  }
+
+  return filename;
+}
+
+void Txt::setupCacheDir() const {
+  if (!SdMan.exists(cacheBasePath.c_str())) {
+    SdMan.mkdir(cacheBasePath.c_str());
+  }
+  if (!SdMan.exists(cachePath.c_str())) {
+    SdMan.mkdir(cachePath.c_str());
+  }
+}
+
+std::string Txt::findCoverImage() const {
+  // Get the folder containing the txt file
+  size_t lastSlash = filepath.find_last_of('/');
+  std::string folder = (lastSlash != std::string::npos) ? filepath.substr(0, lastSlash) : "";
+  if (folder.empty()) {
+    folder = "/";
+  }
+
+  // Get the base filename without extension (e.g., "mybook" from "/books/mybook.txt")
+  std::string baseName = getTitle();
+
+  // Image extensions to try
+  const char* extensions[] = {".bmp", ".jpg", ".jpeg", ".png", ".BMP", ".JPG", ".JPEG", ".PNG"};
+
+  // 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())) {
+      Serial.printf("[%lu] [TXT] Found matching cover image: %s\n", millis(), coverPath.c_str());
+      return coverPath;
+    }
+  }
+
+  // Fallback: look for cover image files
+  const char* coverNames[] = {"cover", "Cover", "COVER"};
+  for (const auto& name : coverNames) {
+    for (const auto& ext : extensions) {
+      std::string coverPath = folder + "/" + std::string(name) + ext;
+      if (SdMan.exists(coverPath.c_str())) {
+        Serial.printf("[%lu] [TXT] Found fallback cover image: %s\n", millis(), coverPath.c_str());
+        return coverPath;
+      }
+    }
+  }
+
+  return "";
+}
+
+std::string Txt::getCoverBmpPath() const { return cachePath + "/cover.bmp"; }
+
+bool Txt::generateCoverBmp() const {
+  // Already generated, return true
+  if (SdMan.exists(getCoverBmpPath().c_str())) {
+    return true;
+  }
+
+  std::string coverImagePath = findCoverImage();
+  if (coverImagePath.empty()) {
+    Serial.printf("[%lu] [TXT] No cover image found for TXT file\n", millis());
+    return false;
+  }
+
+  // Setup cache directory
+  setupCacheDir();
+
+  // Get file extension
+  const size_t len = coverImagePath.length();
+  const bool isJpg =
+      (len >= 4 && (coverImagePath.substr(len - 4) == ".jpg" || coverImagePath.substr(len - 4) == ".JPG")) ||
+      (len >= 5 && (coverImagePath.substr(len - 5) == ".jpeg" || coverImagePath.substr(len - 5) == ".JPEG"));
+  const bool isBmp = len >= 4 && (coverImagePath.substr(len - 4) == ".bmp" || coverImagePath.substr(len - 4) == ".BMP");
+
+  if (isBmp) {
+    // 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)) {
+      return false;
+    }
+    if (!SdMan.openFileForWrite("TXT", getCoverBmpPath(), dst)) {
+      src.close();
+      return false;
+    }
+    uint8_t buffer[1024];
+    while (src.available()) {
+      size_t bytesRead = src.read(buffer, sizeof(buffer));
+      dst.write(buffer, bytesRead);
+    }
+    src.close();
+    dst.close();
+    Serial.printf("[%lu] [TXT] Copied BMP cover to cache\n", millis());
+    return true;
+  }
+
+  if (isJpg) {
+    // 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)) {
+      return false;
+    }
+    if (!SdMan.openFileForWrite("TXT", getCoverBmpPath(), coverBmp)) {
+      coverJpg.close();
+      return false;
+    }
+    const bool success = JpegToBmpConverter::jpegFileToBmpStream(coverJpg, coverBmp);
+    coverJpg.close();
+    coverBmp.close();
+
+    if (!success) {
+      Serial.printf("[%lu] [TXT] Failed to generate BMP from JPG cover image\n", millis());
+      SdMan.remove(getCoverBmpPath().c_str());
+    } else {
+      Serial.printf("[%lu] [TXT] Generated BMP from JPG cover image\n", millis());
+    }
+    return success;
+  }
+
+  // PNG files are not supported (would need a PNG decoder)
+  Serial.printf("[%lu] [TXT] Cover image format not supported (only BMP/JPG/JPEG)\n", millis());
+  return false;
+}
+
+bool Txt::readContent(uint8_t* buffer, size_t offset, size_t length) const {
+  if (!loaded) {
+    return false;
+  }
+
+  FsFile file;
+  if (!SdMan.openFileForRead("TXT", filepath, file)) {
+    return false;
+  }
+
+  if (!file.seek(offset)) {
+    file.close();
+    return false;
+  }
+
+  size_t bytesRead = file.read(buffer, length);
+  file.close();
+
+  return bytesRead > 0;
+}

lib/Txt/Txt.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include <SDCardManager.h>
+
+#include <memory>
+#include <string>
+
+class Txt {
+  std::string filepath;
+  std::string cacheBasePath;
+  std::string cachePath;
+  bool loaded = false;
+  size_t fileSize = 0;
+
+ public:
+  explicit Txt(std::string path, std::string cacheBasePath);
+
+  bool load();
+  [[nodiscard]] const std::string& getPath() const { return filepath; }
+  [[nodiscard]] const std::string& getCachePath() const { return cachePath; }
+  [[nodiscard]] std::string getTitle() const;
+  [[nodiscard]] size_t getFileSize() const { return fileSize; }
+
+  void setupCacheDir() const;
+
+  // Cover image support - looks for cover.bmp/jpg/jpeg/png in same folder as txt file
+  [[nodiscard]] std::string getCoverBmpPath() const;
+  [[nodiscard]] bool generateCoverBmp() const;
+  [[nodiscard]] std::string findCoverImage() const;
+
+  // Read content from file
+  [[nodiscard]] bool readContent(uint8_t* buffer, size_t offset, size_t length) const;
+};

src/activities/boot_sleep/SleepActivity.cpp

@@ -3,6 +3,7 @@
 #include <Epub.h>
 #include <GfxRenderer.h>
 #include <SDCardManager.h>
+#include <Txt.h>
 #include <Xtc.h>
 
 #include "CrossPointSettings.h"
@@ -207,6 +208,7 @@ void SleepActivity::renderCoverSleepScreen() const {
   std::string coverBmpPath;
   bool cropped = SETTINGS.sleepScreenCoverMode == CrossPointSettings::SLEEP_SCREEN_COVER_MODE::CROP;
 
+  // Check if the current book is XTC, TXT, or EPUB
   if (StringUtils::checkFileExtension(APP_STATE.openEpubPath, ".xtc") ||
       StringUtils::checkFileExtension(APP_STATE.openEpubPath, ".xtch")) {
     // Handle XTC file
@@ -222,6 +224,20 @@ void SleepActivity::renderCoverSleepScreen() const {
     }
 
     coverBmpPath = lastXtc.getCoverBmpPath();
+  } else if (StringUtils::checkFileExtension(APP_STATE.openEpubPath, ".txt")) {
+    // Handle TXT file - looks for cover image in the same folder
+    Txt lastTxt(APP_STATE.openEpubPath, "/.crosspoint");
+    if (!lastTxt.load()) {
+      Serial.println("[SLP] Failed to load last TXT");
+      return renderDefaultSleepScreen();
+    }
+
+    if (!lastTxt.generateCoverBmp()) {
+      Serial.println("[SLP] No cover image found for TXT file");
+      return renderDefaultSleepScreen();
+    }
+
+    coverBmpPath = lastTxt.getCoverBmpPath();
   } else if (StringUtils::checkFileExtension(APP_STATE.openEpubPath, ".epub")) {
     // Handle EPUB file
     Epub lastEpub(APP_STATE.openEpubPath, "/.crosspoint");

src/activities/reader/FileSelectionActivity.cpp

@@ -52,7 +52,7 @@ void FileSelectionActivity::loadFiles() {
     } else {
       auto filename = std::string(name);
       if (StringUtils::checkFileExtension(filename, ".epub") || StringUtils::checkFileExtension(filename, ".xtch") ||
-          StringUtils::checkFileExtension(filename, ".xtc")) {
+          StringUtils::checkFileExtension(filename, ".xtc") || StringUtils::checkFileExtension(filename, ".txt")) {
         files.emplace_back(filename);
       }
     }

src/activities/reader/ReaderActivity.cpp

@@ -3,6 +3,8 @@
 #include "Epub.h"
 #include "EpubReaderActivity.h"
 #include "FileSelectionActivity.h"
+#include "Txt.h"
+#include "TxtReaderActivity.h"
 #include "Xtc.h"
 #include "XtcReaderActivity.h"
 #include "activities/util/FullScreenMessageActivity.h"
@@ -20,6 +22,12 @@ bool ReaderActivity::isXtcFile(const std::string& path) {
   return StringUtils::checkFileExtension(path, ".xtc") || StringUtils::checkFileExtension(path, ".xtch");
 }
 
+bool ReaderActivity::isTxtFile(const std::string& path) {
+  if (path.length() < 4) return false;
+  std::string ext4 = path.substr(path.length() - 4);
+  return ext4 == ".txt" || ext4 == ".TXT";
+}
+
 std::unique_ptr<Epub> ReaderActivity::loadEpub(const std::string& path) {
   if (!SdMan.exists(path.c_str())) {
     Serial.printf("[%lu] [   ] File does not exist: %s\n", millis(), path.c_str());
@@ -50,6 +58,21 @@ std::unique_ptr<Xtc> ReaderActivity::loadXtc(const std::string& path) {
   return nullptr;
 }
 
+std::unique_ptr<Txt> ReaderActivity::loadTxt(const std::string& path) {
+  if (!SdMan.exists(path.c_str())) {
+    Serial.printf("[%lu] [   ] File does not exist: %s\n", millis(), path.c_str());
+    return nullptr;
+  }
+
+  auto txt = std::unique_ptr<Txt>(new Txt(path, "/.crosspoint"));
+  if (txt->load()) {
+    return txt;
+  }
+
+  Serial.printf("[%lu] [   ] Failed to load TXT\n", millis());
+  return nullptr;
+}
+
 void ReaderActivity::onSelectBookFile(const std::string& path) {
   currentBookPath = path;  // Track current book path
   exitActivity();
@@ -67,6 +90,18 @@ void ReaderActivity::onSelectBookFile(const std::string& path) {
       delay(2000);
       onGoToFileSelection();
     }
+  } else if (isTxtFile(path)) {
+    // Load TXT file
+    auto txt = loadTxt(path);
+    if (txt) {
+      onGoToTxtReader(std::move(txt));
+    } else {
+      exitActivity();
+      enterNewActivity(new FullScreenMessageActivity(renderer, mappedInput, "Failed to load TXT",
+                                                     EpdFontFamily::REGULAR, EInkDisplay::HALF_REFRESH));
+      delay(2000);
+      onGoToFileSelection();
+    }
   } else {
     // Load EPUB file
     auto epub = loadEpub(path);
@@ -108,6 +143,15 @@ void ReaderActivity::onGoToXtcReader(std::unique_ptr<Xtc> xtc) {
       [this] { onGoBack(); }));
 }
 
+void ReaderActivity::onGoToTxtReader(std::unique_ptr<Txt> txt) {
+  const auto txtPath = txt->getPath();
+  currentBookPath = txtPath;
+  exitActivity();
+  enterNewActivity(new TxtReaderActivity(
+      renderer, mappedInput, std::move(txt), [this, txtPath] { onGoToFileSelection(txtPath); },
+      [this] { onGoBack(); }));
+}
+
 void ReaderActivity::onEnter() {
   ActivityWithSubactivity::onEnter();
 
@@ -125,6 +169,13 @@ void ReaderActivity::onEnter() {
       return;
     }
     onGoToXtcReader(std::move(xtc));
+  } else if (isTxtFile(initialBookPath)) {
+    auto txt = loadTxt(initialBookPath);
+    if (!txt) {
+      onGoBack();
+      return;
+    }
+    onGoToTxtReader(std::move(txt));
   } else {
     auto epub = loadEpub(initialBookPath);
     if (!epub) {

src/activities/reader/ReaderActivity.h

@@ -5,6 +5,7 @@
 
 class Epub;
 class Xtc;
+class Txt;
 
 class ReaderActivity final : public ActivityWithSubactivity {
   std::string initialBookPath;
@@ -12,13 +13,16 @@ class ReaderActivity final : public ActivityWithSubactivity {
   const std::function<void()> onGoBack;
   static std::unique_ptr<Epub> loadEpub(const std::string& path);
   static std::unique_ptr<Xtc> loadXtc(const std::string& path);
+  static std::unique_ptr<Txt> loadTxt(const std::string& path);
   static bool isXtcFile(const std::string& path);
+  static bool isTxtFile(const std::string& path);
 
   static std::string extractFolderPath(const std::string& filePath);
   void onSelectBookFile(const std::string& path);
   void onGoToFileSelection(const std::string& fromBookPath = "");
   void onGoToEpubReader(std::unique_ptr<Epub> epub);
   void onGoToXtcReader(std::unique_ptr<Xtc> xtc);
+  void onGoToTxtReader(std::unique_ptr<Txt> txt);
 
  public:
   explicit ReaderActivity(GfxRenderer& renderer, MappedInputManager& mappedInput, std::string initialBookPath,

src/activities/reader/TxtReaderActivity.h

@@ -0,0 +1,60 @@
+#pragma once
+
+#include <Txt.h>
+#include <freertos/FreeRTOS.h>
+#include <freertos/semphr.h>
+#include <freertos/task.h>
+
+#include <vector>
+
+#include "CrossPointSettings.h"
+#include "activities/ActivityWithSubactivity.h"
+
+class TxtReaderActivity final : public ActivityWithSubactivity {
+  std::unique_ptr<Txt> txt;
+  TaskHandle_t displayTaskHandle = nullptr;
+  SemaphoreHandle_t renderingMutex = nullptr;
+  int currentPage = 0;
+  int totalPages = 1;
+  int pagesUntilFullRefresh = 0;
+  bool updateRequired = false;
+  const std::function<void()> onGoBack;
+  const std::function<void()> onGoHome;
+
+  // Streaming text reader - stores file offsets for each page
+  std::vector<size_t> pageOffsets;  // File offset for start of each page
+  std::vector<std::string> currentPageLines;
+  int linesPerPage = 0;
+  int viewportWidth = 0;
+  bool initialized = false;
+
+  // Cached settings for cache validation (different fonts/margins require re-indexing)
+  int cachedFontId = 0;
+  int cachedScreenMargin = 0;
+  uint8_t cachedParagraphAlignment = CrossPointSettings::LEFT_ALIGN;
+
+  static void taskTrampoline(void* param);
+  [[noreturn]] void displayTaskLoop();
+  void renderScreen();
+  void renderPage();
+  void renderStatusBar(int orientedMarginRight, int orientedMarginBottom, int orientedMarginLeft) const;
+
+  void initializeReader();
+  bool loadPageAtOffset(size_t offset, std::vector<std::string>& outLines, size_t& nextOffset);
+  void buildPageIndex();
+  bool loadPageIndexCache();
+  void savePageIndexCache() const;
+  void saveProgress() const;
+  void loadProgress();
+
+ public:
+  explicit TxtReaderActivity(GfxRenderer& renderer, MappedInputManager& mappedInput, std::unique_ptr<Txt> txt,
+                             const std::function<void()>& onGoBack, const std::function<void()>& onGoHome)
+      : ActivityWithSubactivity("TxtReader", renderer, mappedInput),
+        txt(std::move(txt)),
+        onGoBack(onGoBack),
+        onGoHome(onGoHome) {}
+  void onEnter() override;
+  void onExit() override;
+  void loop() override;
+};