电子书阅读核心

我的书.epub（本质是 ZIP 压缩包）
  └── ZIP 解包后
        ├── META-INF/
        │     └── container.xml   → 入口文件：告诉你 .opf 在哪
        ├── content.opf           → 核心元数据：书名、作者、章节顺序
        ├── toc.ncx / nav.xhtml   → 目录结构（可供用户跳转的章节列表）
        ├── style.css             → 样式表（字体大小、缩进、对齐等）
        ├── chapter1.xhtml        → 第一章内容（HTML 格式）
        ├── chapter2.xhtml        → 第二章内容
        ├── ...
        └── images/
              └── cover.jpg       → 封面图片

// lib/Epub/Epub.cpp
bool Epub::load(const std::string& path) {
  zip = std::make_unique<ZipFile>(path);

  // 1. 先尝试加载二进制缓存（如果之前解析过这本书）
  if (bookCache.loadFromFile(cachePath + "/book.bin")) {
    return true;  // 缓存命中，直接用，几十毫秒就完成
  }

  // 2. 缓存不存在（第一次打开），完整解析
  parseContainer();    // container.xml → 找到 .opf 路径
  parseOpf();          // 解析 spine（阅读顺序）+ metadata（元数据）
  parseToc();          // 解析目录结构

  // 3. 将解析结果序列化为二进制缓存，下次打开秒进
  bookCache.saveToFile(cachePath + "/book.bin");
}

// lib/ZipFile/ZipFile.h
struct ZipInflateCtx {
  InflateReader inflater;       // deflate 解压器
  FsFile* file;                 // 指向 SD 卡上的 ZIP 文件
  uint32_t remainingBytes;      // 该条目还剩多少字节未读
  uint8_t readBuffer[512];      // 512 字节的读取缓冲区
};

// 两种提取方式：

// 方式一：读到内存（适用于小文件，如 container.xml）
uint8_t* readFileToMemory(const std::string& filename, size_t& outSize);

// 方式二：流式输出（适用于大文件，如章节 XHTML）
bool readFileToStream(const std::string& filename, Print& out);

SD 卡上的 ZIP 文件
  │
  ├── 读取 512 字节到缓冲区
  │      │
  │      ├── inflate 解压
  │      │      │
  │      │      └── 输出解压后的数据 → 交给 XML 解析器
  │      │
  │      └── 缓冲区用完 → 再读 512 字节
  │
  └── 直到该文件条目的所有字节都处理完毕

book.bin（版本 3）:
┌─────────────────────────────────┐
│ version (1 字节) = 3             │  ← 版本号，格式变了就递增
│ LUT 偏移量 (4 字节)              │  ← Look-Up Table 的位置
│ spine 数量 + TOC 数量            │  ← 有多少章、目录有多少项
│ 书名、作者、封面路径              │  ← 元数据
│ spine 条目数组（href + 累计大小） │  ← 每章的文件路径和累计字节数
│ TOC 条目数组（标题 + 层级）       │  ← 目录结构
│ 查找表                           │  ← 快速定位用
└─────────────────────────────────┘

section.bin（版本 8）:
┌─────────────────────────────────┐
│ version = 8                      │
│ 字体/行距/边距等渲染参数          │  ← 任何参数变化 → 缓存失效，触发重建
│ 页数                             │
│ 各页: TextBlock / ImageBlock     │  ← 每页包含哪些文本块和图片块
│ 脚注列表                         │
│ 页面偏移查找表                   │  ← 快速跳转到第 N 页
│ 锚点 → 页码映射                  │  ← HTML 锚点对应哪一页（用于目录跳转）
└─────────────────────────────────┘

// lib/Epub/Epub/Section.cpp
bool Section::loadSectionFile(uint8_t fontId, uint8_t lineCompression, ...) {
  // 读取缓存文件头部，先校验版本号
  // 版本号必须 = 8，否则格式不兼容

  // 然后逐一对比当前渲染参数：
  //   fontId           — 字体
  //   lineCompression  — 行距压缩
  //   extraParagraphSpacing — 段间距
  //   alignment        — 对齐方式
  //   viewportWidth    — 视口宽度
  //   viewportHeight   — 视口高度
  //   hyphenation      — 是否启用断字
  //   embeddedStyle    — 是否使用内嵌样式
  //   imageRendering   — 图片渲染模式

  // 任何一项不匹配 → return false → 触发完整重建
}

ZIP 流式解压 → 每次输出约 1KB 数据 → 喂给 Expat → 触发回调

贪心法换行（局部最优）：
┌──────────────────────────────────┐
│ 这是一段很长的示例文本用来演示两种│  ← 塞满了
│ 换行算法的区别                    │  ← 剩很多空白
└──────────────────────────────────┘

动态规划换行（全局最优）：
┌──────────────────────────────────┐
│ 这是一段很长的示例文本用         │  ← 适度留白
│ 来演示两种换行算法的区别         │  ← 均匀分布
└──────────────────────────────────┘

// src/activities/reader/EpubReaderActivity.cpp
void EpubReaderActivity::renderContents(std::unique_ptr<Page> page, ...) {
  // === 第 1 遍：字体预热扫描 ===
  auto scope = fcm->createPrewarmScope();
  page->render(renderer, fontId, marginLeft, marginTop);
  scope.endScanAndPrewarm();
  // 这一遍不真正画像素，只是扫描页面用了哪些字形（glyph），
  // 提前从 Flash 加载到缓存中，避免后续渲染时频繁读取 Flash。

  // === 第 2 遍：黑白渲染 ===
  page->render(renderer, fontId, marginLeft, marginTop);
  renderStatusBar();                              // 画底部状态栏
  renderer.displayBuffer(HalDisplay::FAST_REFRESH); // 送到屏幕（快刷模式）
  renderer.storeBwBuffer();                       // 保存黑白缓冲区副本

  // === 第 3-4 遍：灰度抗锯齿（如果用户开启了此功能）===
  if (SETTINGS.textAntiAliasing) {
    // 第 3 遍：渲染灰度低位
    renderer.setRenderMode(GfxRenderer::GRAYSCALE_LSB);
    page->render(...);
    renderer.copyGrayscaleLsbBuffers();

    // 第 4 遍：渲染灰度高位
    renderer.setRenderMode(GfxRenderer::GRAYSCALE_MSB);
    page->render(...);
    renderer.copyGrayscaleMsbBuffers();

    // 将灰度数据叠加到屏幕上
    renderer.displayGrayBuffer();
    renderer.restoreBwBuffer();  // 恢复黑白缓冲区（灰度渲染会修改它）
  }
}

void saveProgress(int spineIndex, int currentPage, int pageCount) {
  uint8_t data[6];
  data[0] = currentSpineIndex & 0xFF;         // spine 索引低 8 位
  data[1] = (currentSpineIndex >> 8) & 0xFF;  // spine 索引高 8 位
  data[2] = currentPage & 0xFF;               // 当前页码低 8 位
  data[3] = (currentPage >> 8) & 0xFF;        // 当前页码高 8 位
  data[4] = pageCount & 0xFF;                 // 总页数低 8 位
  data[5] = (pageCount >> 8) & 0xFF;          // 总页数高 8 位
  f.write(data, 6);
}

旧进度：第 42 页 / 共 100 页 → 阅读进度 = 42%
新字体排版后：共 120 页 → 新页码 = 120 × 42% ≈ 第 50 页

static constexpr int MAX_FOOTNOTE_DEPTH = 3;

struct SavedPosition {
  int spineIndex;   // 章节索引
  int page;         // 页码
};

SavedPosition savedPositions[MAX_FOOTNOTE_DEPTH];  // 位置栈
int footnoteDepth = 0;                             // 当前深度

正文第 5 页 → 点击脚注[1] → 跳转到脚注区
  压栈：savedPositions[0] = {spine=3, page=5}
  footnoteDepth = 1

脚注内容 → 点击"参见脚注[7]" → 跳转到另一个脚注
  压栈：savedPositions[1] = {spine=3, page=末尾}
  footnoteDepth = 2

阅读完毕 → 按返回键
  弹栈：恢复到 savedPositions[1] → 回到脚注[1]
  footnoteDepth = 1

再按返回键
  弹栈：恢复到 savedPositions[0] → 回到正文第 5 页
  footnoteDepth = 0

Without hyphenation:              With hyphenation:
┌────────────────────────┐       ┌────────────────────────┐
│ The process of         │       │ The process of inter-  │
│ internationalization   │       │ nationalization is     │
│ is complex.            │       │ complex.               │
└────────────────────────┘       └────────────────────────┘

TXT 文件（可能几 MB）
  │
  ├── 读取前 8KB → 排版 → 记录每页的起始字节偏移量
  ├── 读取下一个 8KB → 继续排版 → 记录偏移量
  ├── ...
  └── 读完整个文件

一个字节 = 0b10110010
           │││││││└── 像素 7: 白
           ││││││└─── 像素 6: 黑
           │││││└──── 像素 5: 白
           ││││└───── 像素 4: 白
           │││└────── 像素 3: 黑
           ││└─────── 像素 2: 黑
           │└──────── 像素 1: 白
           └───────── 像素 0: 黑

第 1 遍：渲染灰度值 = 0（黑色）的像素    → 写入屏幕
第 2 遍：渲染灰度值 = 1（深灰）的像素    → 写入屏幕
第 3 遍：渲染灰度值 = 2（浅灰）的像素    → 写入屏幕
第 4 遍：渲染灰度值 = 3（白色）的像素    → 写入屏幕