web-font/task.md
崮生(子虚) 26e34ea850 refactor(vendor): fonteditor-core 全量 js→ts + 原生 ESM 迁移(131 文件)
- 零 .js 残留,含 main.js→main.ts ESM 重写与 woff2/woff2-encode 重写
- ESM interop 修复:运行时 require 全部改 import *(zlib 静态、@xmldom 走 createRequire 惰性 Proxy)
- 迁移期间修复:readWindowsAllCodes startId 循环变量、ttf.ts computePath 联合类型守卫等
- 配套:scripts/verify_table_migration.ts(108 断言字节级双管线验证)、robustness-scan.ts(24字体×5文本 三层校验 240/240 PASS)、table-size-analysis.ts
- 验收:双 tsconfig tsc 0 错误、指纹 4/4 逐字节一致、基准 22 用例全 PASS、SSIM 无回退
- 性能:worktree 同机交替对照确认与迁移前持平(总 min -0.5%)
2026-10-28 19:49:39 +08:00

58 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 任务:字体子集化持续优化(/loop 持续循环)
## 角色
你是本仓库(web-font)的性能优化工程师。核心资产是 `backend/font_util/font.ts` 的 `fontSubset`(含 TTF/CFF/GSUB/GPOS 子集化与纯 JS WOFF2 编码器),前端 SDK 在 `packages/`,基准测试为 `基准测试.test.ts`(puppeteer 无头渲染 + SSIM)。
## 目标(按优先级)
1. **正确性不可破**:任何改动后基准必须全 PASS,且与改动前基线对比——输出字节应逐字节一致或差异可解释,SSIM 不低于该用例历史值
2. **性能**:继续压缩子集化耗时(avg 与 min 都要看,min 才是真本事,avg 含噪声),以及输出体积
3. **能力扩展**:见「待探索方向」,完成一项验证一项
## 验收流程(每轮改动必须走完)
1. 改动前先跑一次基准留存基线:`pnpx tsx ./基准测试.test.ts`
2. 小步改动:一次只改一个热点,禁止混合多项优化
3. 改动后再跑基准,与步骤 1 结果逐用例对比:
- 耗时:avg 下降或持平即合格;波动大时跑两次交叉验证(参考 `benchmark_results/BASELINE_2026-08-27.md` 的 min1/min2 对照法)
- 字节:逐用例对比输出 bytes,不一致必须能解释(如重映射后序列化更紧凑)并写进日志
- SSIM:不得低于该用例历史值。注意:篆体用例历史 min=0.9876 是原字体光栅化固有差异(已三重验证),**不是回归**,不要试图"修"它
4. TS 改动执行 `pnpm tsc --noEmit` 确认无类型错误(类型错误≈逻辑错误)
5. 全部通过后才写入 `benchmark_results/OPTIMIZATION_LOG.md`
## 硬性约束
- **禁止修改基准测试中 full 的生成方案**;基准结果异常 = 你的代码改动有问题,先自查,不要归咎于浏览器渲染等外部因素
- 优化必须先测量后动手:用 `node --prof` 或微基准定位热点,不做无 profile 支撑的猜测性优化
- 不做回退方案,只实现最好方案;开发期 let it crash,不为兜底乱加 try
- Git:改动留在工作区,禁止 stash/reset;阶段性完成时提醒提交落库
## 工作方式
- 直接开始做,不切计划模式、不询问、不中断,持续自主迭代
- 每个优化节点在 `benchmark_results/OPTIMIZATION_LOG.md` 追加记录:优化方法 / 瓶颈定位证据(profile 数据)/ 前后对比(各用例 avg/min/max、bytes、ssim)/ 下一步方向
## 当前状态(2026-08-27 基线,30/30 用例全 PASS)
耗时已到亚毫秒~毫秒级(ttf 千字文 min 0.3ms、woff2 千字文 min 2.3ms),继续优化需靠 profile 找剩余热点,不要凭旧数据判断瓶颈。详细数据:`benchmark_results/BASELINE_2026-08-27.md`。已完成大项:GSUB 子集化 33×、WOFF2 纯 JS 编码器重构、glyf triplet inline、共享 gidLookup。
## 待探索方向
1. ~~前端 SDK 扫描策略可配置化~~ **已达成(2026-10-25 核验)**:`WebFontCSSMode` 现有 API 即三种模式——`loadFont`(定时轮询,setInterval 默认 1000ms)/ `observeFont`(MutationObserver+input 事件触发,debounce 50ms)/ `loadText`(用户直接传文本,零扫描返回 ITextLoader);三者共享 IncrementalEngine 的去重/并发池/失败记忆。无需再造 mode 枚举配置项,按场景选 API 即可
2. **profile 驱动的剩余热点**:FiraCode-代码(GSUB 密集)与千字文 woff2(轮廓点多)仍是相对最慢用例,值得继续下钻
3. **输出体积**:表级体积分析工具 `scripts/table-size-analysis.ts`(第 15 轮借此发现 hinting 死表 -36%)。OTF/CFF 侧已测(2026-10-26):CFF 占 66% brotli 硬下限、GSUB/GPOS 已深度优化、**BASE/vmtx/vhea 是活功能不可删**(竖排 vertical-rl 真实消费,与浏览器不走的 hinting 有本质区别)——OTF 侧无结构性死重,方向饱和
4. **多字体鲁棒性扫描补测试覆盖**(注意区分原字体缺字与真回归)——**已完成(2026-10-26 第 18 轮)**:`scripts/robustness-scan.ts`(24 字体 × 5 文本 × ttf/woff2,头合法性+确定性),首跑揪出 4 个空子集非法输出 bug 并双层修复(ttf writeZeroContoursGlyfData 12B header + tofu .notdef 注入救 woff2 spec 盲区),120/120 PASS。**遗留**:白狐 OTF(font/temp)被 temp_cleaner 清除,下载源全反爬,需人工恢复后补跑全量基准
5. ~~scripts/ 侧遗留维护~~ **已清零(2026-10-26 第 19 轮)**:test-leafer-node.mts 2 类型错误已修(Buffer.from + @types/pngjs),`pnpm exec tsc -p tsconfig.scripts.json` 首次全净;robustness-scan 升级三层校验(头合法性+确定性+OTS 真实加载,puppeteer FontFace),240 产物全过。**唯一遗留**:白狐 OTF 人工恢复(font/temp/BaiHuOTFJiaoYuHanZi-2.otf)→ 补跑第 18 轮欠的全量基准(writeZeroContoursGlyfData + tofu .notdef,字节影响已可解释,SSIM 预期不变)
## vendor js→ts 迁移路线(2026-10-25 启动)→ **已全部完成(2026-10-27 终结)**
vendor/fonteditor-core 全部 131 个 js 已迁为 TS + 原生 ESM(4 个 sub agent 并行批次:common/graphics/math 叶子、ttf/util+svg、ttf/table+cff、reader/writer/facade/woff2)。**零 js 残留**(含 main.js→main.ts ESM 重写)。
**迁移中发现并修复的坑(重要)**:
- **tsx/node ESM 对 CJS 的 interop 不识别 `__esModule`**:ESM 入口 `import X from './cjs.js'` 拿到整个 module.exports 而非 `exports.default`,报 "X is not a constructor"。此前指纹验证(/tmp 下 CJS 入口跑)与 vite build(打包器 interop 正确)都测不出,只有仓库 ESM 入口(基准测试/后端 dev)会崩——**验证必须覆盖 ESM 直跑路径**。中间态曾用 interopDefault 包装层过渡,全迁完已整体删除。
- 运行时 `require()`(DOMParser 的 @xmldom/xmldom、woff2 的 zlib)在 ESM 下全部改为 `import * as`(zlib LLRT 内置同名 API,静态 import 安全;@xmldom 走 createRequire 惰性 Proxy)。
- 迁移会引入新类型错误(BoundBox|false 联合、let 变 const 改坏循环变量等):批次C 曾把 readWindowsAllCodes 的 startId 误改 const(format12 字体必崩),靠字节级双管线对比脚本(scripts/verify_table_migration.ts,108 断言)抓回。
- vite 的 commonjs 转译插件与 patch-interop 插件(vite.config.ts)现已无消费对象,可择机删除简化。
**终验(2026-10-27)**:tsconfig.scripts/app 两项目 tsc 0 错误;指纹 4/4 逐字节一致;基准 22 个现存字体用例全 PASS(30 用例中 8 个依赖 font/temp 易失字体被清,含白狐 OTF——恢复后需补跑);vite-ssg build 通过;ESM 直跑(tsx 仓库根入口)正常。
## 性能候选点备忘(2026-10-25 profile 实测,FiraCode-代码 woff2 avg 1.43ms 微基准)
- `processChunkSync`(node:zlib brotli q2):14.8% 自耗时——已到拐点,q1/q0 体积损失不值,**不动**
- `collectReachableGsubTargets` 系列(gsub-reachable.ts):合计 ~12.4%,已是 TS 且多轮深挖;剩余空间可能在 lookups 解析阶段的 dv 读取合并
- `read @glyf.js`(5.7%)+ `dump @ttfwriter.js`(2.0%)+ `write @write.js`(1.9%):vendor js 解析/序列化主链,**js→ts 重写时顺带优化**(如热路径去对象分配)
- `ceilReduceAndSizeFlat @optimizettf.js`(2.2%):null 检查/取整逻辑可尝试位运算化
- `__name @gsub-subset.ts`(2.4%):tsx 的 CJS/ESM interop 包装开销,构建产物无此问题,仅 dev 现象,**不修**