mod: Phase 1 - bring forward mod-exclusive files with ActivityManager migration

Brings ~55 mod-exclusive files to the upstream-based mod/master-resync branch:

Activities (migrated to new ActivityManager pattern):
- Clock/Time: SetTimeActivity, SetTimezoneOffsetActivity, NtpSyncActivity
- Dictionary: DictionaryDefinitionActivity, DictionarySuggestionsActivity,
  DictionaryWordSelectActivity, LookedUpWordsActivity
- Bookmark: EpubReaderBookmarkSelectionActivity
- Book management: BookManageMenuActivity, EndOfBookMenuActivity
- OPDS: OpdsServerListActivity, OpdsSettingsActivity
- Utility: DirectoryPickerActivity, NumericStepperActivity

Utilities (unchanged):
- BookManager, BookSettings, BookmarkStore, BootNtpSync
- Dictionary, LookupHistory, TimeSync, OpdsServerStore

Libraries: PlaceholderCover, TableData, ChapterXPathIndexer
Scripts: inject_mod_version, generate_book_icon, preview_placeholder_cover
Docs: KOReader sync XPath mapping

Migration changes:
- ActivityWithSubactivity -> Activity base class
- Callback constructors -> finish()/setResult() pattern
- enterNewActivity() -> startActivityForResult()
- Activity::RenderLock&& -> RenderLock&&

These files won't compile yet - they reference mod settings and I18n
strings that will be added in subsequent phases.

Made-with: Cursor

lib/Epub/Epub/TableData.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#include <memory>
+#include <vector>
+
+#include "ParsedText.h"
+#include "css/CssStyle.h"
+
+/// A single cell in a table row.
+struct TableCell {
+  std::unique_ptr<ParsedText> content;
+  bool isHeader = false;  // true for <th>, false for <td>
+  int colspan = 1;        // number of logical columns this cell spans
+  CssLength widthHint;    // width hint from HTML attribute or CSS (if hasWidthHint)
+  bool hasWidthHint = false;
+};
+
+/// A single row in a table.
+struct TableRow {
+  std::vector<TableCell> cells;
+};
+
+/// Buffered table data collected during SAX parsing.
+/// The entire table must be buffered before layout because column widths
+/// depend on content across all rows.
+struct TableData {
+  std::vector<TableRow> rows;
+  std::vector<CssLength> colWidthHints;  // width hints from <col> tags, indexed by logical column
+};

lib/KOReaderSync/ChapterXPathIndexer.cpp

@@ -0,0 +1,497 @@
+#include "ChapterXPathIndexer.h"
+
+#include <Logging.h>
+#include <expat.h>
+
+#include <algorithm>
+#include <cctype>
+#include <cstdlib>
+#include <limits>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace {
+
+// Anchor used for both mapping directions.
+// textOffset is counted as visible (non-whitespace) bytes from chapter start.
+// xpath points to the nearest element path at/near that offset.
+
+struct XPathAnchor {
+  size_t textOffset = 0;
+  std::string xpath;
+  std::string xpathNoIndex;  // precomputed removeIndices(xpath)
+};
+
+struct StackNode {
+  std::string tag;
+  int index = 1;
+  bool hasTextAnchor = false;
+};
+
+// ParserState is intentionally ephemeral and created per lookup call.
+// It holds only one spine parse worth of data to avoid retaining structures
+// that would increase long-lived heap usage on the ESP32-C3.
+struct ParserState {
+  explicit ParserState(const int spineIndex) : spineIndex(spineIndex) { siblingCounters.emplace_back(); }
+
+  int spineIndex = 0;
+  int skipDepth = -1;
+  size_t totalTextBytes = 0;
+
+  std::vector<StackNode> stack;
+  std::vector<std::unordered_map<std::string, int>> siblingCounters;
+  std::vector<XPathAnchor> anchors;
+
+  std::string baseXPath() const { return "/body/DocFragment[" + std::to_string(spineIndex + 1) + "]/body"; }
+
+  // Canonicalize incoming KOReader XPath before matching:
+  // - remove all whitespace
+  // - lowercase tags
+  // - strip optional trailing /text()
+  // - strip trailing slash
+  static std::string normalizeXPath(const std::string& input) {
+    if (input.empty()) {
+      return "";
+    }
+
+    std::string out;
+    out.reserve(input.size());
+    for (char c : input) {
+      const unsigned char uc = static_cast<unsigned char>(c);
+      if (std::isspace(uc)) {
+        continue;
+      }
+      out.push_back(static_cast<char>(std::tolower(uc)));
+    }
+
+    const std::string textSuffix = "/text()";
+    const size_t textPos = out.rfind(textSuffix);
+    if (textPos != std::string::npos && textPos + textSuffix.size() == out.size()) {
+      out.erase(textPos);
+    }
+
+    while (!out.empty() && out.back() == '/') {
+      out.pop_back();
+    }
+
+    return out;
+  }
+
+  // Remove bracketed numeric predicates so paths can be compared even when
+  // index counters differ between parser implementations.
+  static std::string removeIndices(const std::string& xpath) {
+    std::string out;
+    out.reserve(xpath.size());
+
+    bool inBracket = false;
+    for (char c : xpath) {
+      if (c == '[') {
+        inBracket = true;
+        continue;
+      }
+      if (c == ']') {
+        inBracket = false;
+        continue;
+      }
+      if (!inBracket) {
+        out.push_back(c);
+      }
+    }
+    return out;
+  }
+
+  static int pathDepth(const std::string& xpath) {
+    int depth = 0;
+    for (char c : xpath) {
+      if (c == '/') {
+        depth++;
+      }
+    }
+    return depth;
+  }
+
+  // Resolve a path to the best anchor offset.
+  // If exact node path is not found, progressively trim trailing segments and
+  // match ancestors to obtain a stable approximate location.
+  bool pickBestAnchorByPath(const std::string& targetPath, const bool ignoreIndices, size_t& outTextOffset,
+                            bool& outExact) const {
+    if (targetPath.empty() || anchors.empty()) {
+      return false;
+    }
+
+    const std::string normalizedTarget = ignoreIndices ? removeIndices(targetPath) : targetPath;
+    std::string probe = normalizedTarget;
+    bool exactProbe = true;
+
+    while (!probe.empty()) {
+      int bestDepth = -1;
+      size_t bestOffset = 0;
+      bool found = false;
+
+      for (const auto& anchor : anchors) {
+        const std::string& anchorPath = ignoreIndices ? anchor.xpathNoIndex : anchor.xpath;
+        if (anchorPath == probe) {
+          const int depth = pathDepth(anchorPath);
+          if (!found || depth > bestDepth || (depth == bestDepth && anchor.textOffset < bestOffset)) {
+            found = true;
+            bestDepth = depth;
+            bestOffset = anchor.textOffset;
+          }
+        }
+      }
+
+      if (found) {
+        outTextOffset = bestOffset;
+        outExact = exactProbe;
+        return true;
+      }
+
+      const size_t lastSlash = probe.find_last_of('/');
+      if (lastSlash == std::string::npos || lastSlash == 0) {
+        break;
+      }
+      probe.erase(lastSlash);
+      exactProbe = false;
+    }
+
+    return false;
+  }
+
+  static std::string toLower(std::string value) {
+    for (char& c : value) {
+      c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+    }
+    return value;
+  }
+
+  // Elements that should not contribute text position anchors.
+  static bool isSkippableTag(const std::string& tag) { return tag == "head" || tag == "script" || tag == "style"; }
+
+  static bool isWhitespaceOnly(const XML_Char* text, const int len) {
+    for (int i = 0; i < len; i++) {
+      if (!std::isspace(static_cast<unsigned char>(text[i]))) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  // Count non-whitespace bytes to keep offsets stable against formatting-only
+  // differences and indentation in source XHTML.
+  static size_t countVisibleBytes(const XML_Char* text, const int len) {
+    size_t count = 0;
+    for (int i = 0; i < len; i++) {
+      if (!std::isspace(static_cast<unsigned char>(text[i]))) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  int bodyDepth() const {
+    for (int i = static_cast<int>(stack.size()) - 1; i >= 0; i--) {
+      if (stack[i].tag == "body") {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  bool insideBody() const { return bodyDepth() >= 0; }
+
+  std::string currentXPath() const {
+    const int bodyIdx = bodyDepth();
+    if (bodyIdx < 0) {
+      return baseXPath();
+    }
+
+    std::string xpath = baseXPath();
+    for (size_t i = static_cast<size_t>(bodyIdx + 1); i < stack.size(); i++) {
+      xpath += "/" + stack[i].tag + "[" + std::to_string(stack[i].index) + "]";
+    }
+    return xpath;
+  }
+
+  // Adds first anchor for an element when text begins and periodic anchors in
+  // longer runs so matching has sufficient granularity without exploding memory.
+  void addAnchorIfNeeded() {
+    if (!insideBody() || stack.empty()) {
+      return;
+    }
+
+    if (!stack.back().hasTextAnchor) {
+      const std::string xpath = currentXPath();
+      anchors.push_back({totalTextBytes, xpath, removeIndices(xpath)});
+      stack.back().hasTextAnchor = true;
+    } else if (anchors.empty() || totalTextBytes - anchors.back().textOffset >= 192) {
+      const std::string xpath = currentXPath();
+      if (anchors.empty() || anchors.back().xpath != xpath) {
+        anchors.push_back({totalTextBytes, xpath, removeIndices(xpath)});
+      }
+    }
+  }
+
+  void onStartElement(const XML_Char* rawName) {
+    std::string name = toLower(rawName ? rawName : "");
+    const size_t depth = stack.size();
+
+    if (siblingCounters.size() <= depth) {
+      siblingCounters.resize(depth + 1);
+    }
+    const int siblingIndex = ++siblingCounters[depth][name];
+
+    stack.push_back({name, siblingIndex, false});
+    siblingCounters.emplace_back();
+
+    if (skipDepth < 0 && isSkippableTag(name)) {
+      skipDepth = static_cast<int>(stack.size()) - 1;
+    }
+  }
+
+  void onEndElement() {
+    if (stack.empty()) {
+      return;
+    }
+
+    if (skipDepth == static_cast<int>(stack.size()) - 1) {
+      skipDepth = -1;
+    }
+
+    stack.pop_back();
+    if (!siblingCounters.empty()) {
+      siblingCounters.pop_back();
+    }
+  }
+
+  void onCharacterData(const XML_Char* text, const int len) {
+    if (skipDepth >= 0 || len <= 0 || !insideBody() || isWhitespaceOnly(text, len)) {
+      return;
+    }
+
+    addAnchorIfNeeded();
+    totalTextBytes += countVisibleBytes(text, len);
+  }
+
+  std::string chooseXPath(const float intraSpineProgress) const {
+    if (anchors.empty()) {
+      return baseXPath();
+    }
+    if (totalTextBytes == 0) {
+      return anchors.front().xpath;
+    }
+
+    const float clampedProgress = std::max(0.0f, std::min(1.0f, intraSpineProgress));
+    const size_t target = static_cast<size_t>(clampedProgress * static_cast<float>(totalTextBytes));
+
+    // upper_bound returns the first anchor strictly after target; step back to get
+    // the last anchor at-or-before target (the element the user is currently inside).
+    auto it = std::upper_bound(anchors.begin(), anchors.end(), target,
+                               [](const size_t value, const XPathAnchor& anchor) { return value < anchor.textOffset; });
+    if (it != anchors.begin()) {
+      --it;
+    }
+    return it->xpath;
+  }
+
+  // Convert path -> progress ratio by matching to nearest available anchor.
+  bool chooseProgressForXPath(const std::string& xpath, float& outIntraSpineProgress, bool& outExactMatch) const {
+    if (anchors.empty()) {
+      return false;
+    }
+
+    const std::string normalized = normalizeXPath(xpath);
+    if (normalized.empty()) {
+      return false;
+    }
+
+    size_t matchedOffset = 0;
+    bool exact = false;
+    const char* matchTier = nullptr;
+
+    bool matched = pickBestAnchorByPath(normalized, false, matchedOffset, exact);
+    if (matched) {
+      matchTier = exact ? "exact" : "ancestor";
+    } else {
+      bool exactRaw = false;
+      matched = pickBestAnchorByPath(normalized, true, matchedOffset, exactRaw);
+      if (matched) {
+        exact = false;
+        matchTier = exactRaw ? "index-insensitive" : "index-insensitive-ancestor";
+      }
+    }
+
+    if (!matched) {
+      LOG_DBG("KOX", "Reverse: spine=%d no anchor match for '%s' (%zu anchors)", spineIndex, normalized.c_str(),
+              anchors.size());
+      return false;
+    }
+
+    outExactMatch = exact;
+    if (totalTextBytes == 0) {
+      outIntraSpineProgress = 0.0f;
+      LOG_DBG("KOX", "Reverse: spine=%d %s match offset=%zu -> progress=0.0 (no text)", spineIndex, matchTier,
+              matchedOffset);
+      return true;
+    }
+
+    outIntraSpineProgress = static_cast<float>(matchedOffset) / static_cast<float>(totalTextBytes);
+    outIntraSpineProgress = std::max(0.0f, std::min(1.0f, outIntraSpineProgress));
+    LOG_DBG("KOX", "Reverse: spine=%d %s match offset=%zu/%zu -> progress=%.3f", spineIndex, matchTier, matchedOffset,
+            totalTextBytes, outIntraSpineProgress);
+    return true;
+  }
+};
+
+void XMLCALL onStartElement(void* userData, const XML_Char* name, const XML_Char**) {
+  auto* state = static_cast<ParserState*>(userData);
+  state->onStartElement(name);
+}
+
+void XMLCALL onEndElement(void* userData, const XML_Char*) {
+  auto* state = static_cast<ParserState*>(userData);
+  state->onEndElement();
+}
+
+void XMLCALL onCharacterData(void* userData, const XML_Char* text, const int len) {
+  auto* state = static_cast<ParserState*>(userData);
+  state->onCharacterData(text, len);
+}
+
+void XMLCALL onDefaultHandlerExpand(void* userData, const XML_Char* text, const int len) {
+  // The default handler fires for comments, PIs, DOCTYPE, and entity references.
+  // Only forward entity references (&..;) to avoid skewing text offsets with
+  // non-visible markup.
+  if (len < 3 || text[0] != '&' || text[len - 1] != ';') {
+    return;
+  }
+  for (int i = 1; i < len - 1; ++i) {
+    if (text[i] == '<' || text[i] == '>') {
+      return;
+    }
+  }
+  auto* state = static_cast<ParserState*>(userData);
+  state->onCharacterData(text, len);
+}
+
+// Parse one spine item and return a fully populated ParserState.
+// Returns std::nullopt if validation, I/O, or XML parse fails.
+static std::optional<ParserState> parseSpineItem(const std::shared_ptr<Epub>& epub, const int spineIndex) {
+  if (!epub || spineIndex < 0 || spineIndex >= epub->getSpineItemsCount()) {
+    return std::nullopt;
+  }
+
+  const auto spineItem = epub->getSpineItem(spineIndex);
+  if (spineItem.href.empty()) {
+    return std::nullopt;
+  }
+
+  size_t chapterSize = 0;
+  uint8_t* chapterBytes = epub->readItemContentsToBytes(spineItem.href, &chapterSize, false);
+  if (!chapterBytes || chapterSize == 0) {
+    free(chapterBytes);
+    return std::nullopt;
+  }
+
+  ParserState state(spineIndex);
+
+  XML_Parser parser = XML_ParserCreate(nullptr);
+  if (!parser) {
+    free(chapterBytes);
+    LOG_ERR("KOX", "Failed to allocate XML parser for spine=%d", spineIndex);
+    return std::nullopt;
+  }
+
+  XML_SetUserData(parser, &state);
+  XML_SetElementHandler(parser, onStartElement, onEndElement);
+  XML_SetCharacterDataHandler(parser, onCharacterData);
+  XML_SetDefaultHandlerExpand(parser, onDefaultHandlerExpand);
+
+  const bool parseOk = XML_Parse(parser, reinterpret_cast<const char*>(chapterBytes), static_cast<int>(chapterSize),
+                                 XML_TRUE) != XML_STATUS_ERROR;
+
+  if (!parseOk) {
+    LOG_ERR("KOX", "XPath parse failed for spine=%d at line %lu: %s", spineIndex, XML_GetCurrentLineNumber(parser),
+            XML_ErrorString(XML_GetErrorCode(parser)));
+  }
+
+  XML_ParserFree(parser);
+  free(chapterBytes);
+
+  if (!parseOk) {
+    return std::nullopt;
+  }
+
+  return state;
+}
+
+}  // namespace
+
+std::string ChapterXPathIndexer::findXPathForProgress(const std::shared_ptr<Epub>& epub, const int spineIndex,
+                                                      const float intraSpineProgress) {
+  const auto state = parseSpineItem(epub, spineIndex);
+  if (!state) {
+    return "";
+  }
+
+  const std::string result = state->chooseXPath(intraSpineProgress);
+  LOG_DBG("KOX", "Forward: spine=%d progress=%.3f anchors=%zu textBytes=%zu -> %s", spineIndex, intraSpineProgress,
+          state->anchors.size(), state->totalTextBytes, result.c_str());
+  return result;
+}
+
+bool ChapterXPathIndexer::findProgressForXPath(const std::shared_ptr<Epub>& epub, const int spineIndex,
+                                               const std::string& xpath, float& outIntraSpineProgress,
+                                               bool& outExactMatch) {
+  outIntraSpineProgress = 0.0f;
+  outExactMatch = false;
+
+  if (xpath.empty()) {
+    return false;
+  }
+
+  const auto state = parseSpineItem(epub, spineIndex);
+  if (!state) {
+    return false;
+  }
+
+  LOG_DBG("KOX", "Reverse: spine=%d anchors=%zu textBytes=%zu for '%s'", spineIndex, state->anchors.size(),
+          state->totalTextBytes, xpath.c_str());
+  return state->chooseProgressForXPath(xpath, outIntraSpineProgress, outExactMatch);
+}
+
+bool ChapterXPathIndexer::tryExtractSpineIndexFromXPath(const std::string& xpath, int& outSpineIndex) {
+  outSpineIndex = -1;
+  if (xpath.empty()) {
+    return false;
+  }
+
+  const std::string normalized = ParserState::normalizeXPath(xpath);
+  const std::string key = "/docfragment[";
+  const size_t pos = normalized.find(key);
+  if (pos == std::string::npos) {
+    LOG_DBG("KOX", "No DocFragment in xpath: '%s'", xpath.c_str());
+    return false;
+  }
+
+  const size_t start = pos + key.size();
+  size_t end = start;
+  while (end < normalized.size() && std::isdigit(static_cast<unsigned char>(normalized[end]))) {
+    end++;
+  }
+
+  if (end == start || end >= normalized.size() || normalized[end] != ']') {
+    return false;
+  }
+
+  const std::string value = normalized.substr(start, end - start);
+  const long parsed = std::strtol(value.c_str(), nullptr, 10);
+  // KOReader uses 1-based DocFragment indices; convert to 0-based spine index.
+  if (parsed < 1 || parsed > std::numeric_limits<int>::max()) {
+    return false;
+  }
+
+  outSpineIndex = static_cast<int>(parsed) - 1;
+  return true;
+}

lib/KOReaderSync/ChapterXPathIndexer.h

@@ -0,0 +1,67 @@
+#pragma once
+
+#include <Epub.h>
+
+#include <memory>
+#include <string>
+
+/**
+ * Lightweight XPath/progress bridge for KOReader sync.
+ *
+ * Why this exists:
+ * - CrossPoint stores reading position as chapter/page.
+ * - KOReader sync uses XPath + percentage.
+ *
+ * This utility reparses exactly one spine XHTML item with Expat and builds
+ * transient text anchors (<xpath, textOffset>) so we can translate in both
+ * directions without keeping a full DOM in memory.
+ *
+ * Design constraints (ESP32-C3):
+ * - No persistent full-book structures.
+ * - Parse-on-demand and free memory immediately.
+ * - Keep fallback behavior deterministic if parsing/matching fails.
+ */
+class ChapterXPathIndexer {
+ public:
+  /**
+   * Convert an intra-spine progress ratio to the nearest element-level XPath.
+   *
+   * @param epub Loaded EPUB instance
+   * @param spineIndex Current spine item index
+   * @param intraSpineProgress Position within the spine item [0.0, 1.0]
+   * @return Best matching XPath for KOReader, or empty string on failure
+   */
+  static std::string findXPathForProgress(const std::shared_ptr<Epub>& epub, int spineIndex, float intraSpineProgress);
+
+  /**
+   * Resolve a KOReader XPath to an intra-spine progress ratio.
+   *
+   * Matching strategy:
+   * 1) exact anchor path match,
+   * 2) index-insensitive path match,
+   * 3) ancestor fallback.
+   *
+   * @param epub Loaded EPUB instance
+   * @param spineIndex Spine item index to parse
+   * @param xpath Incoming KOReader XPath
+   * @param outIntraSpineProgress Resolved position within spine [0.0, 1.0]
+   * @param outExactMatch True only for full exact path match
+   * @return true if any match was resolved; false means caller should fallback
+   */
+  static bool findProgressForXPath(const std::shared_ptr<Epub>& epub, int spineIndex, const std::string& xpath,
+                                   float& outIntraSpineProgress, bool& outExactMatch);
+
+  /**
+   * Parse DocFragment index from KOReader-style path segment:
+   * /body/DocFragment[N]/body/...
+   *
+   * KOReader uses 1-based DocFragment indices; N is converted to the 0-based
+   * spine index stored in outSpineIndex (i.e. outSpineIndex = N - 1).
+   *
+   * @param xpath KOReader XPath
+   * @param outSpineIndex 0-based spine index derived from DocFragment[N]
+   * @return true when DocFragment[N] exists and N is a valid integer >= 1
+   *         (converted to 0-based outSpineIndex); false otherwise
+   */
+  static bool tryExtractSpineIndexFromXPath(const std::string& xpath, int& outSpineIndex);
+};

lib/PlaceholderCover/BookIcon.h

@@ -0,0 +1,25 @@
+#pragma once
+#include <cstdint>
+
+// Book icon: 48x48, 1-bit packed (MSB first)
+// 0 = black, 1 = white (same format as Logo120.h)
+static constexpr int BOOK_ICON_WIDTH = 48;
+static constexpr int BOOK_ICON_HEIGHT = 48;
+static const uint8_t BookIcon[] = {
+    0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xfc, 0x00, 0x00, 0x00, 0x00, 0x1f,
+    0xfc, 0x00, 0x00, 0x00, 0x00, 0x1f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1c, 0x00, 0x00, 0x01, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1c, 0x00, 0x01, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1c, 0x00, 0x00, 0x1f, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f, 0xfc, 0x1f, 0xff, 0xff, 0xff, 0x9f,
+    0xfc, 0x00, 0x00, 0x00, 0x00, 0x1f, 0xfc, 0x00, 0x00, 0x00, 0x00, 0x1f, 0xff, 0x00, 0x00, 0x00, 0x00, 0x3f,
+    0xff, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0x00, 0x00, 0x00, 0x00, 0x3f, 0xff, 0x00, 0x00, 0x00, 0x00, 0x3f,
+    0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff,
+};

lib/PlaceholderCover/PlaceholderCoverGenerator.cpp

@@ -0,0 +1,474 @@
+#include "PlaceholderCoverGenerator.h"
+
+#include <EpdFont.h>
+#include <HalStorage.h>
+#include <Logging.h>
+#include <Utf8.h>
+
+#include <algorithm>
+#include <cstring>
+#include <vector>
+
+// Include the UI fonts directly for self-contained placeholder rendering.
+// These are 1-bit bitmap fonts compiled from Ubuntu TTF.
+#include "builtinFonts/ubuntu_10_regular.h"
+#include "builtinFonts/ubuntu_12_bold.h"
+
+// Book icon bitmap (48x48 1-bit, generated by scripts/generate_book_icon.py)
+#include "BookIcon.h"
+
+namespace {
+
+// BMP writing helpers (same format as JpegToBmpConverter)
+inline void write16(Print& out, const uint16_t value) {
+  out.write(value & 0xFF);
+  out.write((value >> 8) & 0xFF);
+}
+
+inline void write32(Print& out, const uint32_t value) {
+  out.write(value & 0xFF);
+  out.write((value >> 8) & 0xFF);
+  out.write((value >> 16) & 0xFF);
+  out.write((value >> 24) & 0xFF);
+}
+
+inline void write32Signed(Print& out, const int32_t value) {
+  out.write(value & 0xFF);
+  out.write((value >> 8) & 0xFF);
+  out.write((value >> 16) & 0xFF);
+  out.write((value >> 24) & 0xFF);
+}
+
+void writeBmpHeader1bit(Print& bmpOut, const int width, const int height) {
+  const int bytesPerRow = (width + 31) / 32 * 4;
+  const int imageSize = bytesPerRow * height;
+  const uint32_t fileSize = 62 + imageSize;
+
+  // BMP File Header (14 bytes)
+  bmpOut.write('B');
+  bmpOut.write('M');
+  write32(bmpOut, fileSize);
+  write32(bmpOut, 0);   // Reserved
+  write32(bmpOut, 62);  // Offset to pixel data
+
+  // DIB Header (BITMAPINFOHEADER - 40 bytes)
+  write32(bmpOut, 40);
+  write32Signed(bmpOut, width);
+  write32Signed(bmpOut, -height);  // Negative = top-down
+  write16(bmpOut, 1);              // Color planes
+  write16(bmpOut, 1);              // Bits per pixel
+  write32(bmpOut, 0);              // BI_RGB
+  write32(bmpOut, imageSize);
+  write32(bmpOut, 2835);  // xPixelsPerMeter
+  write32(bmpOut, 2835);  // yPixelsPerMeter
+  write32(bmpOut, 2);     // colorsUsed
+  write32(bmpOut, 2);     // colorsImportant
+
+  // Palette: index 0 = black, index 1 = white
+  const uint8_t palette[8] = {
+      0x00, 0x00, 0x00, 0x00,  // Black
+      0xFF, 0xFF, 0xFF, 0x00   // White
+  };
+  for (const uint8_t b : palette) {
+    bmpOut.write(b);
+  }
+}
+
+/// 1-bit pixel buffer that can render text, icons, and shapes, then write as BMP.
+class PixelBuffer {
+ public:
+  PixelBuffer(int width, int height) : width(width), height(height) {
+    bytesPerRow = (width + 31) / 32 * 4;
+    bufferSize = bytesPerRow * height;
+    buffer = static_cast<uint8_t*>(malloc(bufferSize));
+    if (buffer) {
+      memset(buffer, 0xFF, bufferSize);  // White background
+    }
+  }
+
+  ~PixelBuffer() {
+    if (buffer) {
+      free(buffer);
+    }
+  }
+
+  bool isValid() const { return buffer != nullptr; }
+
+  /// Set a pixel to black.
+  void setBlack(int x, int y) {
+    if (x < 0 || x >= width || y < 0 || y >= height) return;
+    const int byteIndex = y * bytesPerRow + x / 8;
+    const uint8_t bitMask = 0x80 >> (x % 8);
+    buffer[byteIndex] &= ~bitMask;
+  }
+
+  /// Set a scaled "pixel" (scale x scale block) to black.
+  void setBlackScaled(int x, int y, int scale) {
+    for (int dy = 0; dy < scale; dy++) {
+      for (int dx = 0; dx < scale; dx++) {
+        setBlack(x + dx, y + dy);
+      }
+    }
+  }
+
+  /// Draw a filled rectangle in black.
+  void fillRect(int x, int y, int w, int h) {
+    for (int row = y; row < y + h && row < height; row++) {
+      for (int col = x; col < x + w && col < width; col++) {
+        setBlack(col, row);
+      }
+    }
+  }
+
+  /// Draw a rectangular border in black.
+  void drawBorder(int x, int y, int w, int h, int thickness) {
+    fillRect(x, y, w, thickness);                  // Top
+    fillRect(x, y + h - thickness, w, thickness);  // Bottom
+    fillRect(x, y, thickness, h);                  // Left
+    fillRect(x + w - thickness, y, thickness, h);  // Right
+  }
+
+  /// Draw a horizontal line in black with configurable thickness.
+  void drawHLine(int x, int y, int length, int thickness = 1) { fillRect(x, y, length, thickness); }
+
+  /// Render a single glyph at (cursorX, baselineY) with integer scaling. Returns advance in X (scaled).
+  int renderGlyph(const EpdFontData* font, uint32_t codepoint, int cursorX, int baselineY, int scale = 1) {
+    const EpdFont fontObj(font);
+    const EpdGlyph* glyph = fontObj.getGlyph(codepoint);
+    if (!glyph) {
+      glyph = fontObj.getGlyph(REPLACEMENT_GLYPH);
+    }
+    if (!glyph) {
+      return 0;
+    }
+
+    const uint8_t* bitmap = &font->bitmap[glyph->dataOffset];
+    const int glyphW = glyph->width;
+    const int glyphH = glyph->height;
+
+    for (int gy = 0; gy < glyphH; gy++) {
+      const int screenY = baselineY - glyph->top * scale + gy * scale;
+      for (int gx = 0; gx < glyphW; gx++) {
+        const int pixelPos = gy * glyphW + gx;
+        const int screenX = cursorX + glyph->left * scale + gx * scale;
+
+        bool isSet = false;
+        if (font->is2Bit) {
+          const uint8_t byte = bitmap[pixelPos / 4];
+          const uint8_t bitIndex = (3 - pixelPos % 4) * 2;
+          const uint8_t val = 3 - ((byte >> bitIndex) & 0x3);
+          isSet = (val < 3);
+        } else {
+          const uint8_t byte = bitmap[pixelPos / 8];
+          const uint8_t bitIndex = 7 - (pixelPos % 8);
+          isSet = ((byte >> bitIndex) & 1);
+        }
+
+        if (isSet) {
+          setBlackScaled(screenX, screenY, scale);
+        }
+      }
+    }
+
+    return glyph->advanceX * scale;
+  }
+
+  /// Render a UTF-8 string at (x, y) where y is the top of the text line, with integer scaling.
+  void drawText(const EpdFontData* font, int x, int y, const char* text, int scale = 1) {
+    const int baselineY = y + font->ascender * scale;
+    int cursorX = x;
+    uint32_t cp;
+    while ((cp = utf8NextCodepoint(reinterpret_cast<const uint8_t**>(&text)))) {
+      cursorX += renderGlyph(font, cp, cursorX, baselineY, scale);
+    }
+  }
+
+  /// Draw a 1-bit icon bitmap (MSB first, 0=black, 1=white) with integer scaling.
+  void drawIcon(const uint8_t* icon, int iconW, int iconH, int x, int y, int scale = 1) {
+    const int bytesPerIconRow = iconW / 8;
+    for (int iy = 0; iy < iconH; iy++) {
+      for (int ix = 0; ix < iconW; ix++) {
+        const int byteIdx = iy * bytesPerIconRow + ix / 8;
+        const uint8_t bitMask = 0x80 >> (ix % 8);
+        // In the icon data: 0 = black (drawn), 1 = white (skip)
+        if (!(icon[byteIdx] & bitMask)) {
+          const int sx = x + ix * scale;
+          const int sy = y + iy * scale;
+          setBlackScaled(sx, sy, scale);
+        }
+      }
+    }
+  }
+
+  /// Write the pixel buffer to a file as a 1-bit BMP.
+  bool writeBmp(Print& out) const {
+    if (!buffer) return false;
+    writeBmpHeader1bit(out, width, height);
+    out.write(buffer, bufferSize);
+    return true;
+  }
+
+  int getWidth() const { return width; }
+  int getHeight() const { return height; }
+
+ private:
+  int width;
+  int height;
+  int bytesPerRow;
+  size_t bufferSize;
+  uint8_t* buffer;
+};
+
+/// Measure the width of a UTF-8 string in pixels (at 1x scale).
+int measureTextWidth(const EpdFontData* font, const char* text) {
+  const EpdFont fontObj(font);
+  int w = 0, h = 0;
+  fontObj.getTextDimensions(text, &w, &h);
+  return w;
+}
+
+/// Get the advance width of a single character.
+int getCharAdvance(const EpdFontData* font, uint32_t cp) {
+  const EpdFont fontObj(font);
+  const EpdGlyph* glyph = fontObj.getGlyph(cp);
+  if (!glyph) return 0;
+  return glyph->advanceX;
+}
+
+/// Split a string into words (splitting on spaces).
+std::vector<std::string> splitWords(const std::string& text) {
+  std::vector<std::string> words;
+  std::string current;
+  for (size_t i = 0; i < text.size(); i++) {
+    if (text[i] == ' ') {
+      if (!current.empty()) {
+        words.push_back(current);
+        current.clear();
+      }
+    } else {
+      current += text[i];
+    }
+  }
+  if (!current.empty()) {
+    words.push_back(current);
+  }
+  return words;
+}
+
+/// Word-wrap text into lines that fit within maxWidth pixels at the given scale.
+std::vector<std::string> wrapText(const EpdFontData* font, const std::string& text, int maxWidth, int scale = 1) {
+  std::vector<std::string> lines;
+  const auto words = splitWords(text);
+  if (words.empty()) return lines;
+
+  const int spaceWidth = getCharAdvance(font, ' ') * scale;
+  std::string currentLine;
+  int currentWidth = 0;
+
+  for (const auto& word : words) {
+    const int wordWidth = measureTextWidth(font, word.c_str()) * scale;
+
+    if (currentLine.empty()) {
+      currentLine = word;
+      currentWidth = wordWidth;
+    } else if (currentWidth + spaceWidth + wordWidth <= maxWidth) {
+      currentLine += " " + word;
+      currentWidth += spaceWidth + wordWidth;
+    } else {
+      lines.push_back(currentLine);
+      currentLine = word;
+      currentWidth = wordWidth;
+    }
+  }
+
+  if (!currentLine.empty()) {
+    lines.push_back(currentLine);
+  }
+
+  return lines;
+}
+
+/// Truncate a string with "..." if it exceeds maxWidth pixels at the given scale.
+std::string truncateText(const EpdFontData* font, const std::string& text, int maxWidth, int scale = 1) {
+  if (measureTextWidth(font, text.c_str()) * scale <= maxWidth) {
+    return text;
+  }
+
+  std::string truncated = text;
+  const char* ellipsis = "...";
+  const int ellipsisWidth = measureTextWidth(font, ellipsis) * scale;
+
+  while (!truncated.empty()) {
+    utf8RemoveLastChar(truncated);
+    if (measureTextWidth(font, truncated.c_str()) * scale + ellipsisWidth <= maxWidth) {
+      return truncated + ellipsis;
+    }
+  }
+
+  return ellipsis;
+}
+
+}  // namespace
+
+bool PlaceholderCoverGenerator::generate(const std::string& outputPath, const std::string& title,
+                                         const std::string& author, int width, int height) {
+  LOG_DBG("PHC", "Generating placeholder cover %dx%d: \"%s\" by \"%s\"", width, height, title.c_str(), author.c_str());
+
+  const EpdFontData* titleFont = &ubuntu_12_bold;
+  const EpdFontData* authorFont = &ubuntu_10_regular;
+
+  PixelBuffer buf(width, height);
+  if (!buf.isValid()) {
+    LOG_ERR("PHC", "Failed to allocate %dx%d pixel buffer (%d bytes)", width, height, (width + 31) / 32 * 4 * height);
+    return false;
+  }
+
+  // Proportional layout constants based on cover dimensions.
+  // The device bezel covers ~2-3px on each edge, so we pad inward from the edge.
+  const int edgePadding = std::max(3, width / 48);   // ~10px at 480w, ~3px at 136w
+  const int borderWidth = std::max(2, width / 96);   // ~5px at 480w, ~2px at 136w
+  const int innerPadding = std::max(4, width / 32);  // ~15px at 480w, ~4px at 136w
+
+  // Text scaling: 2x for full-size covers, 1x for thumbnails
+  const int titleScale = (height >= 600) ? 2 : 1;
+  const int authorScale = (height >= 600) ? 2 : 1;  // Author also larger on full covers
+  // Icon: 2x for full cover, 1x for medium thumb, skip for small
+  const int iconScale = (height >= 600) ? 2 : (height >= 350 ? 1 : 0);
+
+  // Draw border inset from edge
+  buf.drawBorder(edgePadding, edgePadding, width - 2 * edgePadding, height - 2 * edgePadding, borderWidth);
+
+  // Content area (inside border + inner padding)
+  const int contentX = edgePadding + borderWidth + innerPadding;
+  const int contentY = edgePadding + borderWidth + innerPadding;
+  const int contentW = width - 2 * contentX;
+  const int contentH = height - 2 * contentY;
+
+  if (contentW <= 0 || contentH <= 0) {
+    LOG_ERR("PHC", "Cover too small for content (%dx%d)", width, height);
+    FsFile file;
+    if (!Storage.openFileForWrite("PHC", outputPath, file)) {
+      return false;
+    }
+    buf.writeBmp(file);
+    file.close();
+    return true;
+  }
+
+  // --- Layout zones ---
+  // Title zone: top 2/3 of content area (icon + title)
+  // Author zone: bottom 1/3 of content area
+  const int titleZoneH = contentH * 2 / 3;
+  const int authorZoneH = contentH - titleZoneH;
+  const int authorZoneY = contentY + titleZoneH;
+
+  // --- Separator line at the zone boundary ---
+  const int separatorWidth = contentW / 3;
+  const int separatorX = contentX + (contentW - separatorWidth) / 2;
+  buf.drawHLine(separatorX, authorZoneY, separatorWidth);
+
+  // --- Icon dimensions (needed for title text wrapping) ---
+  const int iconW = (iconScale > 0) ? BOOK_ICON_WIDTH * iconScale : 0;
+  const int iconGap = (iconScale > 0) ? std::max(8, width / 40) : 0;  // Gap between icon and title text
+  const int titleTextW = contentW - iconW - iconGap;                  // Title wraps in narrower area beside icon
+
+  // --- Prepare title text (wraps within the area to the right of the icon) ---
+  const std::string displayTitle = title.empty() ? "Untitled" : title;
+  auto titleLines = wrapText(titleFont, displayTitle, titleTextW, titleScale);
+
+  constexpr int MAX_TITLE_LINES = 5;
+  if (static_cast<int>(titleLines.size()) > MAX_TITLE_LINES) {
+    titleLines.resize(MAX_TITLE_LINES);
+    titleLines.back() = truncateText(titleFont, titleLines.back(), titleTextW, titleScale);
+  }
+
+  // --- Prepare author text (multi-line, max 3 lines) ---
+  std::vector<std::string> authorLines;
+  if (!author.empty()) {
+    authorLines = wrapText(authorFont, author, contentW, authorScale);
+    constexpr int MAX_AUTHOR_LINES = 3;
+    if (static_cast<int>(authorLines.size()) > MAX_AUTHOR_LINES) {
+      authorLines.resize(MAX_AUTHOR_LINES);
+      authorLines.back() = truncateText(authorFont, authorLines.back(), contentW, authorScale);
+    }
+  }
+
+  // --- Calculate title zone layout (icon LEFT of title) ---
+  // Tighter line spacing so 2-3 title lines fit within the icon height
+  const int titleLineH = titleFont->advanceY * titleScale * 3 / 4;
+  const int iconH = (iconScale > 0) ? BOOK_ICON_HEIGHT * iconScale : 0;
+  const int numTitleLines = static_cast<int>(titleLines.size());
+  // Visual height: distance from top of first line to bottom of last line's glyphs.
+  // Use ascender (not full advanceY) for the last line since trailing line-gap isn't visible.
+  const int titleVisualH =
+      (numTitleLines > 0) ? (numTitleLines - 1) * titleLineH + titleFont->ascender * titleScale : 0;
+  const int titleBlockH = std::max(iconH, titleVisualH);  // Taller of icon or text
+
+  int titleStartY = contentY + (titleZoneH - titleBlockH) / 2;
+  if (titleStartY < contentY) {
+    titleStartY = contentY;
+  }
+
+  // If title fits within icon height, center it vertically against the icon.
+  // Otherwise top-align so extra lines overflow below.
+  const int iconY = titleStartY;
+  const int titleTextY = (iconH > 0 && titleVisualH <= iconH) ? titleStartY + (iconH - titleVisualH) / 2 : titleStartY;
+
+  // --- Horizontal centering: measure the widest title line, then center icon+gap+text block ---
+  int maxTitleLineW = 0;
+  for (const auto& line : titleLines) {
+    const int w = measureTextWidth(titleFont, line.c_str()) * titleScale;
+    if (w > maxTitleLineW) maxTitleLineW = w;
+  }
+  const int titleBlockW = iconW + iconGap + maxTitleLineW;
+  const int titleBlockX = contentX + (contentW - titleBlockW) / 2;
+
+  // --- Draw icon ---
+  if (iconScale > 0) {
+    buf.drawIcon(BookIcon, BOOK_ICON_WIDTH, BOOK_ICON_HEIGHT, titleBlockX, iconY, iconScale);
+  }
+
+  // --- Draw title lines (to the right of the icon) ---
+  const int titleTextX = titleBlockX + iconW + iconGap;
+  int currentY = titleTextY;
+  for (const auto& line : titleLines) {
+    buf.drawText(titleFont, titleTextX, currentY, line.c_str(), titleScale);
+    currentY += titleLineH;
+  }
+
+  // --- Draw author lines (centered vertically in bottom 1/3, centered horizontally) ---
+  if (!authorLines.empty()) {
+    const int authorLineH = authorFont->advanceY * authorScale;
+    const int authorBlockH = static_cast<int>(authorLines.size()) * authorLineH;
+    int authorStartY = authorZoneY + (authorZoneH - authorBlockH) / 2;
+    if (authorStartY < authorZoneY + 4) {
+      authorStartY = authorZoneY + 4;  // Small gap below separator
+    }
+
+    for (const auto& line : authorLines) {
+      const int lineWidth = measureTextWidth(authorFont, line.c_str()) * authorScale;
+      const int lineX = contentX + (contentW - lineWidth) / 2;
+      buf.drawText(authorFont, lineX, authorStartY, line.c_str(), authorScale);
+      authorStartY += authorLineH;
+    }
+  }
+
+  // --- Write to file ---
+  FsFile file;
+  if (!Storage.openFileForWrite("PHC", outputPath, file)) {
+    LOG_ERR("PHC", "Failed to open output file: %s", outputPath.c_str());
+    return false;
+  }
+
+  const bool success = buf.writeBmp(file);
+  file.close();
+
+  if (success) {
+    LOG_DBG("PHC", "Placeholder cover written to %s", outputPath.c_str());
+  } else {
+    LOG_ERR("PHC", "Failed to write placeholder BMP");
+    Storage.remove(outputPath.c_str());
+  }
+
+  return success;
+}

lib/PlaceholderCover/PlaceholderCoverGenerator.h

@@ -0,0 +1,14 @@
+#pragma once
+
+#include <string>
+
+/// Generates simple 1-bit BMP placeholder covers with title/author text
+/// for books that have no embedded cover image.
+class PlaceholderCoverGenerator {
+ public:
+  /// Generate a placeholder cover BMP with title and author text.
+  /// The BMP is written to outputPath as a 1-bit black-and-white image.
+  /// Returns true if the file was written successfully.
+  static bool generate(const std::string& outputPath, const std::string& title, const std::string& author, int width,
+                       int height);
+};