diff --git a/refactor/baselines/chapter-contract.md b/refactor/baselines/chapter-contract.md new file mode 100644 index 000000000..bde9f3de4 --- /dev/null +++ b/refactor/baselines/chapter-contract.md @@ -0,0 +1,71 @@ +# Chapter 1.1.0 迁移契约 + +PKG-CHAPTER-01,2026-09-10。来源为 [固定发布归档](releases.json) 的 chapter 1.1.0、 +工作区 packages/artplayer-plugin-chapter,以及 [官方示例](../../docs/assets/example/chapter.js)。 +归档完整性沿用 BASE-01,不依赖 registry 最新版本或陈旧 gitHead。 + +## 已核对的一致性 + +发布包与工作区的 README、package.json、声明经 LF 归一化相同。当前源码插件函数与样式注入 +if 块,与发布 ESM 中相应语句经 TypeScript 5.9.3 提取、esbuild 0.27.7 语法归一化后 SHA-256 +均为 `f0bf5985794454bb2027d1d2bd718bbaf02230907245ef684e3f31ba955c9650`。比较不包含 CSS 字符串 +或 bundler 包装,不能用它声称三个分发文件全部字节相同。 + +| 工作区文件 | SHA-256(LF) | +| --- | --- | +| src/index.js | fcd732e4257597a8cbb192fa4d715488b344df361a3a5b7d0e7c70f7554a73e6 | +| src/style.less | a7506541374cbf5b3a6906b19d4a925406b2ccebdb9be6c7406c3bb8d9045ee5 | +| types/artplayer-plugin-chapter.d.ts | 4ce65f8a55ed8f53ddd7f1cd7324923aacefeaee209d58d5981e1434050a6962 | +| README.md | 04f1d3338acdf7c4f56ac3596d7c5c3282f508400208cb6142da064ced7e72dc | +| package.json | 233ed9b732e14cb06955536157ba1650c4cffded74015a2417942e70ee5aca04 | + +## 调用和行为 + +| ID | 兼容边界 | 后续断言 | +| --- | --- | --- | +| CHAPTER.factory | 默认导出/global 为 artplayerPluginChapter;工厂允许无参或 `{ chapters }`,返回同步插件函数 | 两种工厂调用、旧核心注册 | +| CHAPTER.result | 结果为 name=`artplayerPluginChapter` 与 update 方法;没有新增 Promise 或自动异步注册 | key/name、同步结果 | +| CHAPTER.update | `update({ chapters })` 同步返回 undefined;`update({})` 清空;`update()` 当前会抛 TypeError,不能把它与无参工厂混为一谈 | 正常、空配置与非法调用 | +| CHAPTER.intervals | start/end 为秒;合法范围满足 0 ≤ start < end ≤ duration,禁止重叠;end=Infinity 换成当前 duration;相邻区间允许接触 | 边界、重叠、Infinity、类型错误 | +| CHAPTER.input-mutation | 原地 sort,修改 Infinity end,并通过 unshift/push/splice 给原数组补空标题区间;原章节对象保留引用 | 迁移保留已合法可观察的数组/对象变化 | +| CHAPTER.render | 列表按时长比例展示,dataset start/end/duration/title 是字符串;title trim,只用 textContent,不执行标题 HTML | gap、百分比、标题文本 | +| CHAPTER.progress | `setBar(type, percentage)` 的 hover/loaded/played 更新对应子条;当前秒数小于/大于章节时分别 0/100%;未知 type 不更新 | 边界 seek、各条宽度 | +| CHAPTER.hover | 有标题时根据总进度位置定位,靠左右边缘夹紧;章节边界可能同时命中两段,后段覆盖标题 | 实际 mouse hover 与边缘位置 | +| CHAPTER.init | 创建 DOM 后等待一次 video:loadedmetadata;该回调用创建时 option.chapters;更新成功启用 class 并 emit setBar loaded | ready 前后及 loaded 同步 | +| CHAPTER.empty | 空列表、非数组、duration=0 会先清列表并关闭 class,再返回;校验失败也已经清旧 UI | 回退/异常后 DOM | +| CHAPTER.cleanup | 插件自身没有公开 destroy,也不注册专有清理函数;核心 destroy(removeHtml) 控制 DOM 清理 | destroy 真正移除/保留节点的区别 | +| CHAPTER.style | 导入时按 id 去重注入全局 style;文档 loading 时等待 DOMContentLoaded;SSR 无 document 不注入 | 导入安全、样式不随单实例销毁删除 | + +DOM/CSS hooks:播放器 class `artplayer-plugin-chapter`;进度容器 `.art-control-progress-inner`; +`.art-chapters` → `.art-chapter` → `.art-chapter-inner` → `.art-progress-hover/.art-progress-loaded/.art-progress-played`; +标题 `.art-chapter-title`。保留 dataset start/end/duration/title、4px gap、用户 CSS 变量和 thumbnail +相对位置。样式依赖播放器 hover class,不能只把 title.textContent 当成可见性通过。 + +插件只依赖旧核心 template.$player、query、constructor.utils 的 append/query/clamp/setStyle/ +addClass/removeClass、duration/loaded、on/once/emit。迁移不得意外依赖新核心专有工具。 + +## 入口、类型和版本边界 + +保留 main/module/types/legacy 的历史路径、默认导出以及 exports 的 `.`/`./legacy` 条件入口。 +没有声明 peer 核心最低版本,不能新造一个最低版本或承诺全部旧版本;目前已验证的旧核心基线为 +5.4.0,工作区核心为 5.4.1。其他旧版本范围仍按环境矩阵取证。计划发布 chapter 2.0.0,旧接口保持。 + +声明局部定义 Chapters/Option/Result,只有 default 导出,未导出这些类型名。声明把工厂 option +误写为必填,与运行时默认值不一致(BASE-TYPE-02);PKG-CHAPTER-02 扩展为可选参数并验证。 +NodeNext ESM 与 legacy 旧解析问题仍归 PKG-CHAPTER-04(BASE-TYPE-01/03),不混入此契约冻结。 + +README 只有简介、demo 链接和许可,无新增 API 承诺。示例使用 5 段章节、Infinity 收尾和多语言 +标题,组合 autoSize、fullscreen/fullscreenWeb、miniProgressBar、autoOrientation、thumbnails。 +示例真实组合验收归 PKG-CHAPTER-05/06;基础浏览器 smoke 不代表组合已覆盖。 + +## 已发现的改进点,不作为必须保留的缺陷 + +- 空白 gap 的 hover 不清除上一个标题;更新列表也不清旧 title 文本。PKG-CHAPTER-02 复现,03 修复。 +- 只订阅一次 metadata,切源后章节不会自动按新 duration 重算。02 记录实际行为,03 明确更新责任, + 不悄悄把调用方数组中已替换的 Infinity 恢复成另一个公开语义。 +- NaN 能绕过比较,Infinity duration / 非有限 start/end 缺严格约束。02 复现非法输入边界,03 处理, + 正常章节和已有明确错误类型/消息继续兼容。 +- 保留插件结果调用 update 在销毁后可能继续操作脱离页面的 DOM;02 验证生命周期,03 整理所有权。 + +本任务核对实际实现并冻结范围;上述包特有运行断言由下一步 PKG-CHAPTER-02 执行,未将静态审查 +写成浏览器通过。已有真实播放证据见 [ENG-05](browser-validation.json)。 diff --git a/refactor/changes/2026-09-10-PKG-CHAPTER-01-contract.md b/refactor/changes/2026-09-10-PKG-CHAPTER-01-contract.md new file mode 100644 index 000000000..e39873542 --- /dev/null +++ b/refactor/changes/2026-09-10-PKG-CHAPTER-01-contract.md @@ -0,0 +1,15 @@ +# PKG-CHAPTER-01:冻结章节插件迁移边界 + +核对源码、Less、声明、README、示例和固定 npm 1.1.0 内容,形成 +[chapter 契约](../baselines/chapter-contract.md)。发布与工作区的声明/README/manifest 一致, +插件函数及样式注入语句语法归一化 hash 相同;完整归档完整性复用 BASE-01。 + +明确工厂无参和 update 无参的区别、同步返回值、时间规则、调用方数组原地变更、DOM/CSS、 +setBar、一次 metadata 订阅、样式注入与清理边界。保留现有分发入口、全局名与旧核心集成; +支持窗口缺少历史最低版本声明,没有自创范围。BASE-TYPE-02 在下一步扩展可选参数声明。 + +记录空白标题残留、非有限时间、切源更新责任及销毁后 update,作为包内测试/改进项目。 +没有修改生产代码或把静态审查当成这些行为已通过浏览器验证。 + +验证:归档完整性、三个元数据文件对照、语句提取/归一化对照、计划/文档链接和 Git 差异检查。 +回退本提交只移除契约记录。下一步 PKG-CHAPTER-02 补包特有真实浏览器断言和可选参数类型修复。 diff --git a/refactor/plan.md b/refactor/plan.md index 8bcd1ffdd..a060f7429 100644 --- a/refactor/plan.md +++ b/refactor/plan.md @@ -4,7 +4,7 @@ 基线:`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 214 项,范围 22 个包及工作区/示例。 -状态:todo 185 / doing 0 / blocked 0 / done 29 / deferred 0。风险 L/M/H 表示兼容风险,不表示工期。 +状态:todo 184 / doing 0 / blocked 0 / done 30 / deferred 0。风险 L/M/H 表示兼容风险,不表示工期。 前置依赖是启动条件;验收是完成条件。任务可以继续拆分,但不能复用或悄悄删除旧 ID。 @@ -132,7 +132,7 @@ | ID | 范围 / 步骤 | 前置依赖 | 交付物 | 验收条件 | 风险 | 状态 | | --- | --- | --- | --- | --- | --- | --- | -| PKG-CHAPTER-01 | artplayer-plugin-chapter
核对包契约与历史用法 | BASE-05 | chapters 时间区间、update、name 和进度 DOM 清单 | 源码/声明/README/demo/发布包差异已登记;公开形状和版本范围冻结 | M | todo | +| PKG-CHAPTER-01 | artplayer-plugin-chapter
核对包契约与历史用法 | BASE-05 | chapters 时间区间、update、name 和进度 DOM 清单 | 源码/声明/README/demo/发布包差异已登记;公开形状和版本范围冻结 | M | done | | PKG-CHAPTER-02 | artplayer-plugin-chapter
建立特有行为与错误测试 | PKG-CHAPTER-01, ENG-03, ENG-05 | 区间重叠/空列表/边界 seek、hover 标题和 update 用例 | 旧版本行为可重跑,成功/失败/切源/销毁有必要断言;修正 BASE-TYPE-02 的可选参数声明并补正反例 | M | todo | | PKG-CHAPTER-03 | artplayer-plugin-chapter
整理内部职责与资源 | PKG-CHAPTER-02, ENG-07 | 在已有核心上整理时间区间计算、进度 DOM、事件/布局,合理简单代码可保持 | 不依赖新核心方法或大范围设置重构;旧 API/事件和资源通过,必要适配限包内 | M | todo | | PKG-CHAPTER-04 | artplayer-plugin-chapter
迁移自有源码和公开类型 | PKG-CHAPTER-03, ENG-04, ENG-06 | 基于既有公开核心类型的 Chapters/Option/Result 与 update 推导;JS/TS 工具链试点 | 严格类型检查、旧消费样例通过;声明路径/导出和同步异步兼容;处理 BASE-TYPE-01/03,保持运行时和新旧 TS 模块解析消费 | M | todo | @@ -432,3 +432,4 @@ - ENG-04: [记录](changes/2026-09-10-ENG-04-typechecking.md) [记录](typechecking.md) - ENG-05: [记录](changes/2026-09-10-ENG-05-browser-tests.md) [记录](baselines/browser-validation.json) - ENG-06: [记录](changes/2026-09-10-ENG-06-build-development.md) [记录](build-development.md) [记录](baselines/build-validation.json) +- PKG-CHAPTER-01: [记录](changes/2026-09-10-PKG-CHAPTER-01-contract.md) [记录](baselines/chapter-contract.md) diff --git a/refactor/progress.md b/refactor/progress.md index bac4c5c5a..4593519a4 100644 --- a/refactor/progress.md +++ b/refactor/progress.md @@ -1,5 +1,9 @@ # 进度与证据 +## 当前实施:PKG-CHAPTER-01 契约完成 + +源码/发布插件逻辑和元数据对照完成,冻结 chapter 调用、数组变更、DOM/事件和入口,登记待修问题;见 [契约](baselines/chapter-contract.md)。当前 214 项,30 完成、184 待办。ENG-05 提交 7318d338,下一项 PKG-CHAPTER-02 包特有测试与声明修正。生产源码 TS 迁移仍为零。 + ## 当前实施:ENG-05 真实浏览器入口完成 Playwright 三浏览器 12 项真实播放/失败/映射测试通过,指定候选 UMD 文件的 Firefox 4 项通过;新增 CI smoke、报告与自生成媒体。见 [ENG-05](changes/2026-09-10-ENG-05-browser-tests.md)。当前 214 项,29 完成、185 待办;生产源码 TS 迁移仍为零。已具备 chapter 试点所需浏览器入口,下一项 PKG-CHAPTER-01,接特有测试和 ENG-07,再迁移插件源码。远端 CI、完整编辑器及真机尚未验收。 diff --git a/refactor/tasks.json b/refactor/tasks.json index da78a603e..3ab2a53d5 100644 --- a/refactor/tasks.json +++ b/refactor/tasks.json @@ -1140,11 +1140,14 @@ "dependsOn": [ "BASE-05" ], - "status": "todo", + "status": "done", "risk": "M", "deliverable": "chapters 时间区间、update、name 和进度 DOM 清单", "acceptance": "源码/声明/README/demo/发布包差异已登记;公开形状和版本范围冻结", - "evidence": [] + "evidence": [ + "changes/2026-09-10-PKG-CHAPTER-01-contract.md", + "baselines/chapter-contract.md" + ] }, { "id": "PKG-CHAPTER-02",