# 可选字体包构建

本目录保存字体包配方、许可证、来源说明和正式冻结字体资产。字体二进制
位于固定的 `font-packs/assets/`，统一由 Git LFS 管理，普通 Git 对象只保存
LFS 指针。普通 Desktop 主安装包不包含字体；组合 Desktop 发行把字体作为
同目录可选附件，Docker 发行构建则把本次受校验的字体包写入镜像层。

## 源目录

正式发布字体必须先完成许可证、来源、内部字族名、嵌入权限和哈希审查，
随后固定存放在以下版本化仓库目录：

```text
font-packs/assets/mdtp-serif-sc/1.0.0/
├── MdTPSerifSC-Regular.ttf
├── MdTPSerifSC-Regular.woff2
├── MdTPSerifSC-Bold.ttf
└── MdTPSerifSC-Bold.woff2
```

该目录中的 `ttf/otf/woff/woff2` 由 `.gitattributes` 强制使用 Git LFS。
构建器不会联网下载、转换或自动替换字体。每个输入文件都必须与配方声明的
字节数和 SHA-256 完全一致；TTF 还必须是无需运行时规范化的原生静态
TrueType，并具有可安装或可编辑的文档嵌入权限。

## 构建与验证

```powershell
npm run build:font-pack
npm run verify:font-pack
```

也可以显式指定源目录：

```powershell
npm run build:font-pack -- --source-root D:/font-pack-sources/mdtp-serif-sc/1.0.0
```

克隆仓库后应先执行 `git lfs pull`。缺少 LFS 内容时，字体构建会因文件大小
或 SHA-256 不匹配而拒绝继续，不允许使用系统字体或相近字体静默替代。

默认运行时字体包根目录为 `output/font-packs/root`，构建报告写入
`output/font-packs/build-report.json`，两者均被 Git 忽略。输出布局为：

```text
root/<pack-id>/<semver>/font-pack.json
```

同一 ID 和版本的内容完全相同时，重复构建保持幂等；只要任一文件发生
变化，构建器就会拒绝覆盖。发行内容变化必须提升字体包 SemVer。

当前 `mdtp-serif-sc@1.0.0` 只替换 `FandolSong` 与
`Mdpdf Fandol Song` 的 400/700 字重，不匹配 `SimSun` 等通用别名，避免
错误替换仿宋、黑体、楷体或普通外部主题字体。

## Windows 独立安装器

发布人员可以使用 electron-builder 锁定并校验的 NSIS 工具链构建独立
字体包安装器，不需要额外安装系统 NSIS：

```powershell
npm run build:font-pack:windows
```

默认产物为：

```text
output/font-packs/windows/
└── MorphDoc-FontPack-mdtp-serif-sc-1.0.0-x86_64-Setup.exe
```

安装器使用当前用户权限，将整个 `mdtp-serif-sc` ID 安装到：

```text
%LOCALAPPDATA%/md-to-pdf/font-packs/mdtp-serif-sc/1.0.0/
```

它不向 Windows 系统字体目录注册字体。同一版本重装保持幂等，升级时先把
该 ID 的现有目录移入备份，再原子提升新版本；失败会回滚。独立卸载项只
删除安装器拥有的 `mdtp-serif-sc` ID，不影响其他字体包 ID。安装器支持
`/S` 静默安装和卸载。

## Desktop 伴随发行

组合构建命令为：

```powershell
npm run desktop:make:with-font-pack
```

该命令把主安装器、字体包安装器和字体包 ZIP 作为同目录文件发行。主安装器
只编译字体包安装器的文件名与 SHA-256，不嵌入字体二进制；仅当同目录文件
存在且哈希完全一致时，交互安装向导才显示默认勾选的字体包选项。字体包
失败不回滚已安装的主程序。

主安装器静默运行时默认不安装伴随字体包；只有显式传入以下参数才会安装：

```powershell
MorphDoc-<version>-x86_64-Setup.exe /S /WITHFONTPACK=1
```

普通 `npm run make -w @md-to-pdf/desktop` 不启用伴随逻辑，避免本地残留的
生成文件影响常规桌面构建。

## ZIP 发行附件

独立生成可手动部署的确定性 ZIP：

```powershell
npm run build:font-pack:archive
```

产物为 `output/font-packs/release/MorphDoc-FontPack-mdtp-serif-sc-1.0.0.zip`。
归档顶层已经包含 `mdtp-serif-sc/1.0.0/`，用户可直接解压到
`%LOCALAPPDATA%/md-to-pdf/font-packs`。ZIP 内保留清单、许可证、来源说明
以及 Web/DOCX 两类字体资产；相同输入会生成逐字节一致的附件。

## Docker 内置发行

Docker 构建前必须先执行 `npm run build:font-pack`。构建上下文只放行
`output/font-packs/root`，Dockerfile 将其复制到
`/app/.local/font-packs`；Compose 不再挂载宿主机字体目录。字体因此随
镜像离线分发，同时仍由运行时注册器校验版本、路径、容量和 SHA-256。