#Moonbit_EPUB

• 仓库（GitHub）：https://github.com/668xin/moonbit_epub.git

#特性

• 纯生成方向：只做"结构化内容 → .epub 字节流"的正向链路，与生态中已有的 读取/解析类包互补。
• 零外部依赖：仅依赖 MoonBit 核心库，ZIP 压缩（DEFLATE）与 CRC32 均为自研实现， 输出与标准 Python zipfile 交叉验证兼容。
• 规范对齐：媒体类型、命名空间、OCF 保留文件名等均以规范常量集中管理。
• 可访问性内建：提供 schema.org 可访问性元数据（accessMode、accessibilityFeature、 accessibilityHazard 等）与 WCAG conformance 声明。
• 有声书支持：生成 EPUB Media Overlays（SMIL 3.0）文档，并可通过 PackageOptions.add_media_overlay 写入容器、登记清单元数据与 media-overlay 关联。
• CFI 定位：支持 EPUB CFI 的构造/解析，并可按阅读顺序为章节内容文档生成 CFI。
• 结构校验器：独立于生成层，依据规范常量对书籍模型给出稳定的诊断代码 （MET / CHP / RES / OPF / SPN / RCH / CON），同时检查实际生成的 OPF / nav / NCX 文档一致性，支持文本与 JSON 输出。
• 可复现输出：ZIP 时间戳固定为 1980-01-01，压缩无收益时自动退回存储模式， 未显式设置 dcterms:modified 时注入固定默认值，相同输入产生逐字节一致的产物。

#安装

moon add 668xin/moon_epub

本库的 preferred_target 为 wasm-gc，check / build / test / run 均已验证通过。如需兼容旧版工具链，可显式改用 --target js。

#命令行工具

# 生成 EPUB 并以 Base64 输出（核心库无文件 IO，由 shell 解码落盘）
moon run src/cli --target wasm-gc -- build minimal | base64 -d > minimal.epub

# 以十六进制输出（便于在无 base64 工具的环境中使用）
moon run src/cli --target wasm-gc -- build multi-chapter --format hex

# 校验结构并输出文本诊断报告
moon run src/cli --target wasm-gc -- check multi-chapter

# 以 JSON 输出机器可读报告
moon run src/cli --target wasm-gc -- check multi-chapter --json

# 打印书籍结构树
moon run src/cli --target wasm-gc -- inspect styled

# 列出内置示例
moon run src/cli --target wasm-gc -- examples

#作为库使用

// 取一个示例书籍；也可自行构造 @model.Book，
// package_book / validate_book 会自动装配清单与阅读顺序
let book = @examples.multi_chapter()

// 打包为 EPUB 字节流
let options = @ocf.PackageOptions::new()
// 内容文档位于 OEBPS/text/，样式表位于 OEBPS/styles/
options.add_stylesheet("../styles/style.css")
// 可选：登记 Media Overlay（SMIL 文本可由 @media.render_smil 生成）
// options.add_media_overlay("text/ch1.smil", "text/ch1.xhtml", smil_text, duration_ms=1200)
let epub : Bytes = @ocf.package_book(book, options)

// 按阅读顺序生成章节内容文档的 CFI
let cfi = @cfi.chapter_cfi(book, "ch1")

// 结构校验：模型级 + 生成容器的 OCF 布局
// validate_book 会按默认 nav / NCX 自动装配；如需检查手工装配结果，
// 可改用 @validate.validate_book_raw(book)
let report = @validate.validate_book(book)
report.merge(@validate.validate_package(epub))
println(report.summary())
if report.is_ok() {
  println("结构校验通过")
}

#内置示例

• minimal：单章节单段落，含可访问性元数据，用于最小可用验证。
• multi-chapter：嵌套目录与标题、段落、列表、引用、代码块、表格、脚注等 多种块级元素。
• styled：内置阅读器友好 CSS 与自定义 CSS 合成，另附封面图片资源。
• media：单章节有声书示例，含 MP3 音频资源、SMIL Media Overlay 与 media-overlay 清单关联。

$ moon run src/cli --target wasm-gc -- check multi-chapter
报告：0 个错误，0 个警告，0 个提示

#目录结构

src/
├── spec/      规范常量层
├── model/     书籍领域模型
├── xhtml/     XHTML5 内容文档生成
├── opf/       OPF 包文档序列化
├── nav/       nav.xhtml + toc.ncx 双轨导航
├── zip/       ZIP 写入器（本地文件头、中央目录、CRC32、DEFLATE）
├── ocf/       OCF 容器布局与打包
├── assets/    样式与静态资源管理
├── cfi/       EPUB CFI 定位路径
├── a11y/      可访问性元数据
├── media/     Media Overlays / SMIL
├── validate/  结构校验器
├── examples/  示例书籍
└── cli/       命令行入口

#验证与测试

moon check --target wasm-gc   # 类型检查
moon build --target wasm-gc   # 构建
moon test  --target wasm-gc   # 全量单元测试
moon fmt   --check            # 格式检查
moon info                     # 生成 .mbti 接口摘要

import io, zipfile
data = open("minimal.epub", "rb").read()
z = zipfile.ZipFile(io.BytesIO(data))
print(z.namelist(), z.testzip(), z.read("mimetype").decode())

#发布到 mooncakes.io

moon login            # 登录 mooncakes.io 账号
moon publish --dry-run  # 本地打包校验（仅检查，不实际上传）
moon publish          # 发布当前版本（moon.mod 中的 version 字段）

• moon.mod 的 name / version / license / readme / repository 字段完整；
• moon check --target wasm-gc、moon test --target wasm-gc、moon fmt --check 全部通过；
• 更新 version 后重新执行 moon info 以刷新接口摘要。

#许可证