@web-ppt/fonts 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# 更新日志
+
+本文件记录对使用者可见的变化。版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## 0.4.0
+
+本版围绕**字体**：嵌入字体此前从来没有真正生效过，替换字体则完全没有。
+顺带修掉一个让静态画面把动画的几帧叠在一起的问题。
+
+### 新增
+
+- **嵌入字体真的能用了**。PowerPoint 的 `ppt/fonts/*.fntdata` 不是裸 TTF，是 EOT 容器，
+  而且实测**全部**开着 MTX 压缩（POI 语料 6/6、ORCID 样本 10/10）。此前把这段字节
+  原样当 `font/ttf` 塞进 `@font-face`，浏览器一个都不认，只在控制台留一行
+  `invalid sfntVersion`。现在 core 自己剥容器（含异或混淆），MTX 解压走
+  `setFontDecoder()` 注入——官网接的是 [`mtx-decompressor`](https://www.npmjs.com/package/mtx-decompressor) 的 `eotToTtf`，
+  core 本身仍然只依赖 fflate。解不出来就跳过这个字体，不再塞浏览器注定拒绝的字节
+- **`collectFonts(slides)`**：统计若干页用到哪些字体、每个字体要渲染哪些字。
+  纯函数、只依赖 `types.ts`，`.ppt` 链路同样适用，Worker 里能跑
+- **新包 [`@web-ppt/fonts`](packages/fonts)**（gzip 2.8KB，**包里零字节字体**）：
+  文件没带字体、本机也没装时的兜底。拉丁换**度量兼容**的免费字体
+  （Calibri→Carlito、Arial→Arimo 等，前进宽度逐字相等，断行与 PowerPoint 对齐），
+  中文换思源系 / 霞鹜文楷。切片指向钉死版本的 fontsource，按 `unicode-range` 只下用到的那几片
+- **`Viewer.refresh()`**：重渲当前页而不动页码与动画进度。网络字体到货后必须重渲——
+  排版是同步的、加载是异步的，首帧一定是按回退字体断的行
+
+### 修复
+
+- **静态渲染取动画终态，而不是「全部可见」**。一页里入场与退场的元素属于不同时刻，
+  全画出来等于把几帧叠在一起：ORCID 那份样本的第 7 页三段文字本该逐条替换，
+  叠起来一个字都读不出。终态会清空整页时（全员退场的收尾页）退回全部可见
+- **run 没写 `a:latin` 时落到主题的 minorFont**。ECMA-376 的继承链最后一站就是
+  `fontScheme/minorFont`，此前直接当「没有字体」，渲染掉到 CSS 通用回退上，
+  字宽与 PowerPoint 对不齐。真实文件大多在母版 txStyles 里写了 `+mn-lt` 所以少见，
+  但这是「断行对不齐」的一个隐藏来源
+- 字体栈去重：主题的 ea 字体常常正好是回退列表里的 `PingFang SC`，之前会拼出重复项
+
+### 其它
+
+- 测试：1689 → **1848 项断言**，快照 158 → 160 个；新增 `sample-embedfont.pptx`
+  覆盖嵌入字体的四种容器形态（未压缩 EOT / 未压缩+异或 / MTX 压缩 / 裸 TTF）
+- `@web-ppt/core` gzip 84KB 不变；`@web-ppt/viewer-core` 6.8KB → 7.4KB
+- 两个既有包的 peer 依赖同步升到 `^0.4.0`
+
+## 0.3.0
+
+本版把 ECMA-376 的几处主要缺口补齐，并首次拿 **Apache POI 的 242 个公开测试文件**跑批验证：
+排除 22 个故意损坏的模糊测试样本后，真实文件成功率 **210/220 = 95.5%**。
+
+### 新增
+
+- **预设几何补齐到规范全集**：163 → **187 个**。此前缺的 24 个走的是
+  `PRESETS[name] ?? PRESETS.rect`，会**静默画成矩形**，不报错也不进 `unsupported`——
+  `accentCallout*` 这类常见形状出现即无声画错
+- **运动路径动画**：`p:animMotion@path` 此前从未被读取，`presetClass="path"` 一律退化成淡入。
+  现按弧长等距重采样成位移点，播放层走 linear 缓动（PowerPoint 的路径动画是匀速）
+- **切换效果 21 → 41 种**：补上 PowerPoint 2010+ 的全部 19 种 p14 扩展，以及 p159 的
+  **morph**——按形状 id 在前后两页之间配对做几何补间，不是淡入淡出
+- **数学公式 OMML 真排版**：此前只把 `m:t` 拼成一行文字（分式变成 `a+b/2c`）。
+  现做完整箱模型排版，覆盖分式 / 根式 / 上下标 / 大算符 / 定界符 / 矩阵 / 重音 / 极限等 12 类结构
+- **加密文档**：
+  - `.pptx` 标准加密（AES-ECB）与敏捷加密（AES-CBC 分段）
+  - `.ppt` 老式 RC4 CryptoAPI（40 / 56 / 128 位）
+  - 用法 `parse(input, { password })`；密码错误抛 `WrongPasswordError`，与「文件损坏」区分开
+- **PICT（Apple QuickDraw）解码器**：Mac 版 PowerPoint 存的 OLE 预览与图片此前只能是裂图
+- **SmartArt 无缓存 drawing part 时自行排布**：python-pptx / Google Slides 导出的文件
+  常常只写数据与版式定义，此前只能得到灰色占位框。现支持线性 / 循环 / 金字塔 / 层级 /
+  蛇形 / 辐射六种布局族
+
+### 修复
+
+- `borderCallout2` 的引线是三点**开放**子路径，会被 `fill` 补成实心楔形——引线画成了黑三角
+- 后台标签页的 `document.timeline` 是暂停的，`Animation.finished` 永不 resolve，
+  切换的收尾逻辑（移除旧图层）就永远不执行，配合自动换片会让图层持续堆积
+- OLE 预览优先读 `p:oleObj` 内嵌的 `p:pic`（Office 2010+ 的主要写法），旧式 VML 快照作为后备
+
+### 其它
+
+- `@web-ppt/core` gzip 68KB → 84KB（新增的解码器与公式排版；加密与 PICT 走 hook 注入，可 tree-shake）
+- 测试：1298 → **1689 项断言**，快照 142 → 158 个
+- `@web-ppt/viewer-core` 的 peer 依赖同步升到 `^0.3.0`
+
+## 0.2.0 及更早
+
+见 [提交历史](https://github.com/unStone/web-ppt/commits/master)。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unStone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# @web-ppt/fonts
+
+PPT 里指定的字体，本机往往没有。这个包负责换一份**免费的、能自动按需下载的**替代字体，让文本仍然按接近原样的方式排版。
+
+包里**一个字节的字体都没有**（gzip 2.8KB）。切片指向 [fontsource](https://fontsource.org/) 已发布的版本，由 jsDelivr 分发，用不到就不下载。
+
+```bash
+npm i @web-ppt/fonts
+```
+
+## 用法
+
+```ts
+import { collectFonts } from '@web-ppt/core';
+import { loadFontsFor } from '@web-ppt/fonts';
+
+// 只统计当前页：翻到了再补，已下过的切片是免费的
+const usages = collectFonts([pres.slides[viewer.index]]);
+await loadFontsFor(usages);
+viewer.refresh(); // 排版是同步的、加载是异步的，首帧一定按回退字体断的行
+```
+
+`loadFontsFor` 做三件事，缺一不可：
+
+| 步骤 | 为什么 |
+|---|---|
+| 本机装了原字体就跳过 | 零下载永远优于任何加载策略 |
+| 取替代字体的 `@font-face`，**把家族名改写成原字体名** | 幻灯片里写的是「Calibri」，CSS 没有别名机制，只有让 `@font-face` 顶着这个名字，那段文字才会用上它 |
+| `src` 开头补一条 `local()` | 同名 `@font-face` 会**盖掉**系统里的同名字体，不补这条，装了原字体的人反而被拖去下载替代品 |
+
+按需下载完全交给 `unicode-range`——fontsource 的 CSS 自带切片划分，浏览器只取真正渲染到的那几片。
+
+## 替换表
+
+**拉丁一栏全是度量兼容字体**：每个字符的前进宽度与原字体逐一相等，断行位置因此与 PowerPoint 逐字对齐。LibreOffice 用的就是这一套。
+
+| PPT 里的字体 | 替代 | 度量兼容 |
+|---|---|---|
+| Calibri | Carlito | ✓ |
+| Cambria | Caladea | ✓ |
+| Arial / Helvetica | Arimo | ✓ |
+| Times New Roman | Tinos | ✓ |
+| Courier New | Cousine | ✓ |
+| Segoe UI / Tahoma / Verdana | Open Sans | ✗ 仅形近 |
+
+中文：微软雅黑 / 苹方 / 黑体 / 等线 → Noto Sans SC，宋体系 → Noto Serif SC，楷体 → 霞鹜文楷。
+
+只收**可再分发、可子集化**的字体（OFL / Apache）。MiSans、HarmonyOS Sans、阿里普惠这些「免费商用」的许可各自限制再分发与改字，不进内置表——要用就自己往 `overrides` 里加：
+
+```ts
+await loadFontsFor(usages, {
+  overrides: { 思源黑体: { family: 'Noto Sans SC', metricCompatible: false, cjk: true } },
+});
+```
+
+## 中文的代价要心里有数
+
+中文默认也换——传进来的用量本来就该全部处理。但两边的账完全不同：
+
+| | 拉丁 | 中文 |
+|---|---|---|
+| 一页的代价 | ~30KB（一个切片） | **553KB**（22 个不同汉字跨 18 个切片） |
+| 换来什么 | 度量兼容，断行对齐 PowerPoint | 换个字形——汉字全角等宽，断行本来就不会变 |
+| 不换的后果 | 字宽不同，行尾全错 | 系统自带中文字体接住，看着没问题 |
+
+切片一片约 30KB、装约 160 个码位，用掉一两个也得整片下，整份中文文件收敛下来在 1MB 上下。**边际成本按切片算，不按字算**——「只用了 22 个汉字」反而是最亏的情形。
+
+流量敏感的场景可以关掉，或者做成用户可选（官网就是这么做的）：
+
+```ts
+await loadFontsFor(usages, { cjk: false });
+
+// 用户中途关掉时把已注入的声明撤回，然后重渲当前页。
+// 只撤声明，已下载的字节留在 HTTP 缓存里，再打开是免费的
+unloadFonts({ cjkOnly: true });
+viewer.refresh();
+```
+
+## 自托管
+
+不想依赖 jsDelivr 就换基址，目录结构与 fontsource 的 npm 包一致：
+
+```ts
+await loadFontsFor(usages, { base: 'https://cdn.example.com/npm' });
+```
+
+## 导出的另一半
+
+`<img>` 加载的 SVG 是隔离文档，拿不到页面注册的字体。导出 PNG / 独立 SVG 时必须把命中的切片内联进去——`collectFonts` 给出的字符集就是为这个准备的。
+
+## 许可
+
+MIT。替代字体本身各自遵循其原始许可（OFL-1.1 / Apache-2.0），本包不分发字体文件。

package/dist/fonts.js

@@ -0,0 +1,173 @@
+const N = {
+  calibri: { family: "Carlito", metricCompatible: !0, cjk: !1 },
+  "calibri light": { family: "Carlito", metricCompatible: !0, cjk: !1 },
+  cambria: { family: "Caladea", metricCompatible: !0, cjk: !1 },
+  "cambria math": { family: "Caladea", metricCompatible: !0, cjk: !1 },
+  arial: { family: "Arimo", metricCompatible: !0, cjk: !1 },
+  "arial narrow": { family: "Arimo", metricCompatible: !0, cjk: !1 },
+  helvetica: { family: "Arimo", metricCompatible: !0, cjk: !1 },
+  "helvetica neue": { family: "Arimo", metricCompatible: !0, cjk: !1 },
+  "liberation sans": { family: "Arimo", metricCompatible: !0, cjk: !1 },
+  "times new roman": { family: "Tinos", metricCompatible: !0, cjk: !1 },
+  times: { family: "Tinos", metricCompatible: !0, cjk: !1 },
+  "liberation serif": { family: "Tinos", metricCompatible: !0, cjk: !1 },
+  "courier new": { family: "Cousine", metricCompatible: !0, cjk: !1 },
+  courier: { family: "Cousine", metricCompatible: !0, cjk: !1 },
+  consolas: { family: "Cousine", metricCompatible: !1, cjk: !1 },
+  "liberation mono": { family: "Cousine", metricCompatible: !0, cjk: !1 },
+  // 无度量兼容品，只能形近
+  "segoe ui": { family: "Open Sans", metricCompatible: !1, cjk: !1 },
+  tahoma: { family: "Open Sans", metricCompatible: !1, cjk: !1 },
+  verdana: { family: "Open Sans", metricCompatible: !1, cjk: !1 },
+  georgia: { family: "Tinos", metricCompatible: !1, cjk: !1 }
+}, $ = {
+  // 黑体系
+  微软雅黑: { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  "microsoft yahei": { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  "microsoft yahei ui": { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  苹方: { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  "pingfang sc": { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  黑体: { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  simhei: { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  等线: { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  dengxian: { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  "source han sans sc": { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  思源黑体: { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  "hiragino sans gb": { family: "Noto Sans SC", metricCompatible: !1, cjk: !0 },
+  // 宋体系
+  宋体: { family: "Noto Serif SC", metricCompatible: !1, cjk: !0 },
+  simsun: { family: "Noto Serif SC", metricCompatible: !1, cjk: !0 },
+  新宋体: { family: "Noto Serif SC", metricCompatible: !1, cjk: !0 },
+  nsimsun: { family: "Noto Serif SC", metricCompatible: !1, cjk: !0 },
+  华文宋体: { family: "Noto Serif SC", metricCompatible: !1, cjk: !0 },
+  stsong: { family: "Noto Serif SC", metricCompatible: !1, cjk: !0 },
+  思源宋体: { family: "Noto Serif SC", metricCompatible: !1, cjk: !0 },
+  "source han serif sc": { family: "Noto Serif SC", metricCompatible: !1, cjk: !0 },
+  // 楷体：霞鹜文楷的 OFL 头里有一条附加许可，明确允许「专用于 web font 分发」
+  // 的子集 / WOFF2 转换保留原名，正好是这里的用法
+  楷体: { family: "LXGW WenKai", metricCompatible: !1, cjk: !0 },
+  kaiti: { family: "LXGW WenKai", metricCompatible: !1, cjk: !0 },
+  华文楷体: { family: "LXGW WenKai", metricCompatible: !1, cjk: !0 },
+  stkaiti: { family: "LXGW WenKai", metricCompatible: !1, cjk: !0 },
+  // 仿宋没有对位的免费品，退到宋体系比退到黑体近
+  仿宋: { family: "Noto Serif SC", metricCompatible: !1, cjk: !0 },
+  fangsong: { family: "Noto Serif SC", metricCompatible: !1, cjk: !0 }
+}, T = { ...N, ...$ }, x = /^(wingdings|webdings|symbol|marlett)/i;
+function v(i, t) {
+  const e = i.trim().toLowerCase();
+  return !e || x.test(e) ? null : (t == null ? void 0 : t[e]) ?? T[e] ?? null;
+}
+const w = "https://cdn.jsdelivr.net/npm", A = {
+  Carlito: { pkg: "@fontsource/carlito", version: "5.3.0", weights: [400, 700], italics: [400, 700] },
+  Caladea: { pkg: "@fontsource/caladea", version: "5.3.0", weights: [400, 700], italics: [400, 700] },
+  Arimo: { pkg: "@fontsource/arimo", version: "5.3.0", weights: [400, 500, 600, 700], italics: [400, 500, 600, 700] },
+  Tinos: { pkg: "@fontsource/tinos", version: "5.3.0", weights: [400, 700], italics: [400, 700] },
+  Cousine: { pkg: "@fontsource/cousine", version: "5.3.0", weights: [400, 700], italics: [400, 700] },
+  "Open Sans": { pkg: "@fontsource/open-sans", version: "5.3.0", weights: [300, 400, 500, 600, 700, 800], italics: [300, 400, 500, 600, 700, 800] },
+  "Noto Sans SC": { pkg: "@fontsource/noto-sans-sc", version: "5.3.0", weights: [100, 200, 300, 400, 500, 600, 700, 800, 900], italics: [] },
+  "Noto Serif SC": { pkg: "@fontsource/noto-serif-sc", version: "5.3.0", weights: [200, 300, 400, 500, 600, 700, 800, 900], italics: [] },
+  // 霞鹜文楷只出 Light / Regular / Bold 三档，没有 400
+  "LXGW WenKai": { pkg: "@fontsource/lxgw-wenkai", version: "5.3.0", weights: [300, 500, 700], italics: [] }
+};
+function W(i, t) {
+  let e = null;
+  for (const s of i)
+    (e === null || Math.abs(s - t) < Math.abs(e - t)) && (e = s);
+  return e;
+}
+function F(i, t, e, s = w) {
+  const a = A[i];
+  if (!a) return null;
+  const n = e ? a.italics : a.weights, l = W(n.length ? n : a.weights, t);
+  if (l === null) return null;
+  const o = e && a.italics.includes(l);
+  return `${s}/${a.pkg}@${a.version}/${l}${o ? "-italic" : ""}.css`;
+}
+let u = null, g = !1;
+function L(i) {
+  if (g) return u;
+  g = !0;
+  try {
+    const t = i.createElement("canvas").getContext("2d");
+    u = t && typeof t.measureText == "function" ? t : null;
+  } catch {
+    u = null;
+  }
+  return u;
+}
+const d = "MMMMHHHHiiiill漢字語";
+function M(i, t = globalThis.document) {
+  const e = L(t);
+  if (!e) return !1;
+  for (const s of ["monospace", "serif"]) {
+    e.font = `72px ${s}`;
+    const a = e.measureText(d).width;
+    if (e.font = `72px '${i.replace(/'/g, "")}', ${s}`, Math.abs(e.measureText(d).width - a) > 0.5) return !0;
+  }
+  return !1;
+}
+function O(i, t, e) {
+  const s = e.slice(0, e.lastIndexOf("/") + 1), a = t.replace(/['\\]/g, "");
+  return i.replace(/font-family:\s*'[^']*'/g, `font-family: '${a}'`).replace(/url\(\.\/([^)]+)\)/g, (n, l) => `url(${s}${l})`).replace(/src:\s*url\(/g, `src: local('${a}'), url(`);
+}
+const p = /* @__PURE__ */ new Set(), h = /* @__PURE__ */ new Map();
+async function I(i) {
+  let t = h.get(i);
+  return t || (t = fetch(i).then((e) => e.ok ? e.text() : null).catch(() => null), h.set(i, t)), t;
+}
+async function E(i, t = {}) {
+  const e = t.document ?? globalThis.document, s = t.base ?? w, a = t.skipInstalled !== !1;
+  if (!e || typeof fetch != "function") return [];
+  const n = i.map(async (l) => {
+    const { family: o } = l;
+    if (a && M(o, e)) return { family: o, status: "installed" };
+    const c = v(o, t.overrides);
+    if (!c) return { family: o, status: "unmapped" };
+    if (c.cjk && t.cjk === !1) return { family: o, status: "skipped-cjk" };
+    const b = /* @__PURE__ */ new Set();
+    for (const r of l.styles) {
+      const f = r.bold ? 700 : 400;
+      b.add(`${f}|${c.cjk ? !1 : r.italic}`);
+    }
+    let k = !1;
+    for (const r of b) {
+      const [f, y] = r.split("|"), C = F(c.family, Number(f), y === "true", s);
+      if (!C) continue;
+      const S = `${o}|${r}`;
+      if (!p.has(S)) {
+        const j = await I(C);
+        if (!j) continue;
+        p.add(S);
+        const m = e.createElement("style");
+        m.dataset.webPptFont = o, c.cjk && (m.dataset.webPptCjk = "1"), m.textContent = O(j, o, C), e.head.appendChild(m);
+      }
+      try {
+        await e.fonts.load(`${y === "true" ? "italic " : ""}${f} 16px '${o}'`, l.chars), k = !0;
+      } catch {
+      }
+    }
+    return k ? { family: o, status: "substituted", substitute: c.family } : { family: o, status: "failed" };
+  });
+  return Promise.all(n);
+}
+function K(i = {}) {
+  const t = i.document ?? globalThis.document;
+  if (!t) return;
+  const e = i.cjkOnly ? "style[data-web-ppt-cjk]" : "style[data-web-ppt-font]";
+  for (const s of t.querySelectorAll(e)) {
+    for (const a of [...p])
+      a.startsWith(`${s.dataset.webPptFont}|`) && p.delete(a);
+    s.remove();
+  }
+}
+export {
+  w as DEFAULT_BASE,
+  A as PACKAGES,
+  T as SUBSTITUTIONS,
+  F as cssUrl,
+  M as isInstalled,
+  E as loadFontsFor,
+  O as rewriteFontFaceCss,
+  v as substituteFor,
+  K as unloadFonts
+};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @web-ppt/fonts —— 字体替换与按需加载。
+ *
+ * 文件带了嵌入字体时不需要这个包（`setFontDecoder` 那条路保真度更高）；
+ * 这里解决的是**文件没带字体、本机也没装**的情况：拉丁用度量兼容的免费字体，
+ * 断行与 PowerPoint 逐字对齐；中文换成思源系，行高靠 @font-face 描述符拉近。
+ *
+ * 包里**一个字节的字体都没有**：切片指向 fontsource 的已发布版本，
+ * 由 jsDelivr 分发，用不到就不下载。
+ */
+export { SUBSTITUTIONS, substituteFor } from './substitute';
+export type { Substitution } from './substitute';
+export { DEFAULT_BASE, PACKAGES, cssUrl } from './sources';
+export type { FontPackage } from './sources';
+export { isInstalled, loadFontsFor, rewriteFontFaceCss, unloadFonts } from './load';
+export type { LoadOptions, LoadResult } from './load';

package/dist/load.d.ts

@@ -0,0 +1,77 @@
+import type { FontUsage } from '@web-ppt/core';
+import { type Substitution } from './substitute';
+/**
+ * 把「这份文件用了哪些字体」变成「浏览器真的能按它排版」。
+ *
+ * 三件事，缺一不可：
+ *   1. 本机装了原字体就什么都不做——零下载永远优于任何加载策略；
+ *   2. 没装就取替代字体的 `@font-face`，**把家族名改写成原字体名**。
+ *      不改写没用：幻灯片里写的是「微软雅黑」，CSS 里没有别名机制，
+ *      只有让 `@font-face` 顶着「微软雅黑」这个名字，那段文字才会用上它；
+ *   3. `src` 开头补一条 `local()`。声明了同名 `@font-face` 会**盖掉**系统里
+ *      的同名字体，不补这一条，装了原字体的人反而被拖去下载替代品。
+ *
+ * 按需下载完全交给 `unicode-range`：fontsource 的 CSS 自带切片划分，
+ * 浏览器只取真正渲染到的那几片。我们不重切、不预测。
+ */
+export interface LoadOptions {
+    /** CDN 基址，默认 jsDelivr */
+    base?: string;
+    /** 覆盖 / 扩充内置替换表，键为小写后的原字体名 */
+    overrides?: Readonly<Record<string, Substitution>>;
+    /** 本机已装的字体不替换（默认开启）。关掉可强制统一到替代字体 */
+    skipInstalled?: boolean;
+    /**
+     * 是否替换中日韩字体，默认开启——传进来的用量本来就该全部处理，
+     * 半路砍掉一半才是意外。
+     *
+     * 但代价要心里有数，这是实测的：一页只有 22 个不同汉字，却要跨 18 个切片、
+     * 下 553KB。切片一片约 30KB 装约 160 个码位，用掉一两个也得整片下，
+     * 整份中文文件收敛下来在 1MB 上下。拉丁则一个字重才十几 KB。
+     *
+     * 关掉它的正当理由：流量敏感的场景，或者判断「系统自带中文字体已经够看」——
+     * 汉字全角等宽，换字形不改断行，视觉收益确实比拉丁那边小得多。
+     */
+    cjk?: boolean;
+    /** 目标文档，默认当前文档；渲染到 iframe 时要传 */
+    document?: Document;
+}
+/** 一个家族的处理结果 */
+export interface LoadResult {
+    family: string;
+    /**
+     * `installed` 本机已有 · `substituted` 已换成替代字体 ·
+     * `skipped-cjk` 是中文字体且调用方关了 `cjk` · `unmapped` 表里没有 · `failed` 取不到
+     */
+    status: 'installed' | 'substituted' | 'skipped-cjk' | 'unmapped' | 'failed';
+    /** 实际下载的替代字体家族 */
+    substitute?: string;
+}
+/** 本机是否装了这个字体。量不出来时保守地当作「没装」，走替换路径 */
+export declare function isInstalled(family: string, doc?: Document): boolean;
+/**
+ * 把 fontsource 的 CSS 改造成「顶着原字体名」的 `@font-face`。
+ *
+ * 两处改写：家族名换成 `original`，相对路径 `./files/x.woff2` 换成绝对地址
+ * （我们是把 CSS 文本注入到页面里，相对路径会按页面地址解析，必然 404）。
+ * `unicode-range` 原样保留——按需下载全靠它。
+ */
+export declare function rewriteFontFaceCss(css: string, original: string, cssHref: string): string;
+/**
+ * 为一份演示文稿的字体用量准备好网络字体。
+ *
+ * 返回后调用方应当**重新渲染当前页**：排版是同步的、字体加载是异步的，
+ * 首帧必然是按回退字体断的行。`foreignObject` 路径由浏览器重排，原生
+ * `<text>` 路径则要重新量字宽——两条路都得重渲才对得上。
+ */
+export declare function loadFontsFor(usages: readonly FontUsage[], opts?: LoadOptions): Promise<LoadResult[]>;
+/**
+ * 撤回已注入的 `@font-face`。
+ *
+ * 给「用户中途关掉替换」用。只撤声明，不动浏览器已缓存的字节——再打开时
+ * 那些切片是免费的。撤完宿主要自己重渲当前页。
+ */
+export declare function unloadFonts(opts?: {
+    cjkOnly?: boolean;
+    document?: Document;
+}): void;

package/dist/sources.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 替代字体的字节从哪儿来。
+ *
+ * 不自建切片、也不把字体打进包里。理由是实测出来的：拿一份 437 个不同汉字的
+ * 中文文档试，Google/fontsource 现成的切片划分要下 538KB，按字频重排后
+ * 是 460–700KB——省不下来。原因在分布本身：那 437 个字里 96% 落在词频前 2000 名，
+ * 却只用掉其中约两成，任何覆盖「前 2000 名」的切片都得整片下。真正能把它压到
+ * ~63KB 的只有精确子集（要服务端）或 IFT（浏览器还没发）。
+ *
+ * 所以这里做的事只有一件：指向 fontsource 已发布的切片，版本钉死。
+ * 发到 npm 的包 jsDelivr 自动分发，`access-control-allow-origin: *`、
+ * `cache-control: immutable`，零服务端不破，也不依赖 fonts.googleapis.com
+ * （那个域名在国内不可达）。
+ */
+/** 默认 CDN 基址；自托管时换成自己的地址即可 */
+export declare const DEFAULT_BASE = "https://cdn.jsdelivr.net/npm";
+/** 一个替代字体在 fontsource 上的坐标 */
+export interface FontPackage {
+    pkg: string;
+    version: string;
+    /** 该包实际提供的正体字重；请求别的字重要就近取 */
+    weights: number[];
+    /** 提供真斜体的字重；CJK 一律为空，斜体交给浏览器合成 */
+    italics: number[];
+}
+/**
+ * 替代字体对应的 fontsource 包与版本。
+ *
+ * 版本必须钉死：fontsource 换代时切片划分和文件名都会变，跟着 latest 走
+ * 等于让线上排版随时可能漂。升级时连同这里一起改，别用范围号。
+ *
+ * `weights` / `italics` 是各包**实际提供**的档位，逐个查过的：霞鹜文楷没有
+ * 400，中文包一个真斜体都没有。照着「反正都有 400」写会直接 404。
+ */
+export declare const PACKAGES: Readonly<Record<string, FontPackage>>;
+/**
+ * 一个字重 / 斜体的 CSS 地址。
+ *
+ * 取 fontsource 的**按字重**入口（`400.css`）而不是 `index.css`：后者把九个
+ * 字重的声明全塞进来，光解析就上百 KB，而实际用到的通常只有正文和标题两个。
+ */
+export declare function cssUrl(family: string, weight: number, italic: boolean, base?: string): string | null;

package/dist/substitute.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PPT 字体 → 免费替代字体。
+ *
+ * 拉丁一栏挑的全是**度量兼容**字体：每个字符的前进宽度与原字体逐一相等，
+ * 于是断行位置与 PowerPoint 逐字对齐。LibreOffice 用的就是这一套，
+ * 它解决的正是 README 里「字体缺失导致的断行差异」那条。
+ *
+ * 中文没有度量兼容品，但影响比想象小：汉字都是 1em 全角等宽，换字体不改前进宽度，
+ * 偏差只来自 CJK 字体里的西文 / 数字 / 标点。行高用 @font-face 的
+ * `size-adjust` / `ascent-override` 拉齐即可。
+ *
+ * 只收**可再分发、可子集化**的字体（OFL / Apache）。MiSans、HarmonyOS Sans、
+ * 阿里普惠、OPPO Sans 这些「免费商用」的许可各自限制再分发与改字，不进内置表——
+ * 想用的人自己往 `overrides` 里加。
+ */
+/** 一条替换规则 */
+export interface Substitution {
+    /** 替代字体的家族名 */
+    family: string;
+    /**
+     * 前进宽度与原字体逐字相等。为真时断行与 PowerPoint 完全一致，
+     * 为假时只是形近，行高仍可能要靠 `size-adjust` 修。
+     */
+    metricCompatible: boolean;
+    /** 中日韩字体：切片多、体积大，加载策略与拉丁不同 */
+    cjk: boolean;
+}
+/** 内置替换表；键是小写后的原字体名 */
+export declare const SUBSTITUTIONS: Readonly<Record<string, Substitution>>;
+/** 查一个字体该用什么替代；没有对应项返回 null */
+export declare function substituteFor(family: string, overrides?: Readonly<Record<string, Substitution>>): Substitution | null;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@web-ppt/fonts",
+  "version": "0.4.0",
+  "description": "PPT 字体替换与按需加载：度量兼容的免费替代字体表 + unicode-range 切片加载器，零字节字体入包",
+  "keywords": [
+    "pptx",
+    "ppt",
+    "powerpoint",
+    "font",
+    "webfont",
+    "font-substitution",
+    "metric-compatible",
+    "unicode-range",
+    "subset",
+    "cjk",
+    "browser",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "unStone",
+  "homepage": "https://github.com/unStone/web-ppt#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unStone/web-ppt.git",
+    "directory": "packages/fonts"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/fonts.js",
+  "module": "./dist/fonts.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/fonts.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "prepack": "node ../../tooling/sync-package-docs.mjs"
+  },
+  "peerDependencies": {
+    "@web-ppt/core": "^0.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}