refactor(core): CORE-08 type plugin registration and guard closed instances

2026-10-21 04:31:20 -08:00 · 2026-09-11 02:09:36 +08:00
1 parent f9707bad71
commit 874dac9f22
@@ -0,0 +1,65 @@
+# CORE-08：插件注册与扩展类型
+
+## 结构与类型
+
+plugins/index.js 拆为四个 TS 文件：index.ts 管理调用与同步/异步结算，builtins.ts 按原顺序
+装配内置插件，registration.ts 负责命名与属性写入，types.ts 定义最小宿主和内部返回类型。
+内置插件实现仍由 CORE-18 逐项迁移；本任务没有把它们计作已 TS 化。
+
+内部已知同步工厂返回 registry，当前 realm 的 Promise 工厂返回 Promise registry，unknown
+返回保留 union；保持 instanceof Promise 的历史识别规则，不用 Promise.resolve 同化普通
+thenable 或外部 realm Promise。PluginFactory 只有原来的一个 art 参数与 this receiver。
+
+新增公开类型 PluginFactory/Plugins，并加入仅含 types 条件的 artplayer/types 子路径及旧
+typesVersions 回退。该路径指向共享声明，允许跨 Node10、NodeNext CJS/ESM、Bundler 和
+TS 4.3.5 扩展同一个 Plugins/Events 接口；运行时 require/import 均被拒绝。没有新增 JS
+导出或依赖。根 CJS namespace 的类型别名不能直接当成可合并接口，故采用共享类型入口。
+插件类型扩展不会安装插件；示例保留可选属性与存在性检查。
+
+公开 plugins.add 的历史 Promise 返回声明不在这里静默收紧；BASE-TYPE-04 继续开放至
+CORE-21，内部精确类型与旧消费者测试并存。
+
+## 兼容与故障修正
+
+API-03/04/05/06/07/09/11：保留内置/用户顺序、一次 option 捕获、后续实时条件读取、用户
+数组实时遍历、返回结果优先命名、函数名回退和 completion-time id 回退。失败调用仍消耗 id；
+结果属性仍不可枚举、不可写、不可配置；重复名称与同步/异步错误继续保留原始错误对象。
+没有新增名称黑名单，保留旧 prototype 方法遮蔽语义。
+
+动态 name 读取与 PropertyKey 边界保留局部断言；普通活跃注册中的对象键三次原生转换位置
+不变。只有对象/函数键的最终转换在临时对象上提前完成，以便写入前再次检查是否发生销毁，
+不因 ToPropertyKey 中的重入而在关闭后新增不可删除的属性。名称 getter、重复检查和消息
+转换之后也检查关闭状态。
+
+修复 BASE-LIFE-03：销毁前发起的异步 add 仍按原 Promise 成功/失败规则结算，但晚到结果
+不再进入注册表。既有拒绝继续传播；没有引入新的“取消拒绝”。销毁后直接 add 则在 id
+递增及工厂执行前同步抛 ArtPlayerError，明确阻止继续初始化已经关闭的实例。
+生命周期新增内部 isClosing，覆盖 reset 已开始而 scope 尚未 dispose 的重入窗口。
+
+同步工厂关闭构造时停止后续插件；构造器自己发起、没有外部接收者的 Promise 注册增加
+拒绝观察，console.warn 一次原错误，避免孤立的 unhandled rejection。公开 add 的 Promise
+不被该观察器吞掉。未将任何结果的 destroy 方法自动当成清理协议；工厂 await 后自行创建
+的 DOM/SDK/监听器仍需各插件负责，不能把阻止晚到注册宣称为整个生态无资源泄漏。
+
+## 验证
+
+- 八项 Node 测试覆盖 this/参数/描述符/id/命名、同步/Promise 返回、完成时 id、原始错误、
+  thenable/跨 realm、迟到结果、四个命名重入位置、构造停止与拒绝观察、reset 重入。
+- 内部类型正反例检查同步/异步/unknown union 和宿主参数；公开插件结果及事件扩展在五组
+  工作区和实际安装消费模式通过。所有原声明消费者继续编译，新增类型路径无运行时入口。
+- yarn ci:check 共 120 项：91 单元、4 工程、25 基线；32 个生产 TS 文件严格检查，其中
+  核心 27 个、chapter 5 个。build:ts、build artplayer、build:i18n 由仓库脚本生成产物。
+- 严格打包消费 27 项运行时及五组类型零诊断；实际安装 UMD 三浏览器全套 162 项、legacy
+  插件/章节/生命周期 90 项通过，无重试或跳过。新增插件专项 18 项含旧版迟到注册负例、
+  候选修复、同步关闭/拒绝观察以及模拟 mobile UA 的内置顺序与直播排除；不是真机证据。
+
+验证曾捕获拆分时遗漏的 fastForward 直播排除条件；已与 Git 起点和发布版对照恢复，保留
+对照测试。Firefox 的 console 文本只显示 Error，测试改为核对 console 参数中原错误对象
+的 identity/message，而非放宽错误要求。初始失败日志保留在本地 cache。
+
+详见 [验证报告](../baselines/plugins-validation.json)、[核心维护地图](../../packages/artplayer/ARCHITECTURE.md)
+与 [类型说明](../../packages/artplayer/types/README.md)。依赖/锁文件未变，test:unit 加入插件
+测试，工作区及安装类型脚本加入扩展用例。没有远端 CI、推送、发布或真机通过结论。
+
+本任务独立提交，回退提交可恢复管理器、生命周期辅助函数、声明/子路径、测试、生成产物和
+状态。下一项 CORE-09 处理 URL/切源操作身份及异步结算；内置插件资源清理仍属 CORE-18。
@@ -4,7 +4,7 @@

 基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 214 项，范围 22 个包及工作区/示例。

-状态：todo 171 / doing 0 / blocked 0 / done 43 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 170 / doing 0 / blocked 0 / done 44 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。

@@ -111,7 +111,7 @@
 | CORE-05 | artplayer<br>区分输入配置和内部配置 | CORE-01, ENG-04 | Option/ResolvedOption、默认值与校验整理 | 配置合并/错误时机不变，JS 输入仍运行时校验 | M | done |
 | CORE-06 | artplayer<br>建立内部媒体与宿主类型 | CORE-05 | 原生 video、canvas shim、UI host 类型 | 不更改公开 art.video 用法，不以 HTMLVideoElement 断言掩盖 shim | M | done |
 | CORE-07 | artplayer<br>逐项协调公开声明差异 | CORE-02, CORE-06, BASE-07 | plugins/toggle/cue/setting/static 的旧新类型对照 | 每项有兼容重载/扩展或待决结论，不能删除旧类型样例；处理 BASE-TYPE-01/04，分别保留旧合法声明消费并验证真实返回；协调 BASE-TYPE-05 的 Utils 导出、descriptor 和 timer 旧声明差异 | H | done |
-| CORE-08 | artplayer<br>整理插件管理器与扩展类型 | CORE-03, CORE-07 | 注册流程、同步/异步结果、插件/事件扩展接口 | 旧插件同步可见性、重名与命名、销毁中异步插件保持明确语义；处理 baselines/lifecycle-coverage.md 的 BASE-LIFE-03 并增加候选正向回归；接续 CORE-07 / BASE-TYPE-04 的同步/异步注册返回声明冲突，内部返回类型精确，保留历史消费者 | H | todo |
+| CORE-08 | artplayer<br>整理插件管理器与扩展类型 | CORE-03, CORE-07 | 注册流程、同步/异步结果、插件/事件扩展接口 | 旧插件同步可见性、重名与命名、销毁中异步插件保持明确语义；处理 baselines/lifecycle-coverage.md 的 BASE-LIFE-03 并增加候选正向回归；接续 CORE-07 / BASE-TYPE-04 的同步/异步注册返回声明冲突，内部返回类型精确，保留历史消费者 | H | done |
 | CORE-09 | artplayer<br>整理 URL 与切源操作 | CORE-04, CORE-06, CORE-08 | url/switch/customType 的操作身份及取消方案 | 并发切源、错误、同 URL、销毁和 Promise 结算有契约；处理 baselines/lifecycle-coverage.md 的 BASE-LIFE-01/02/06 并增加候选正向回归 | H | todo |
 | CORE-10 | artplayer<br>迁移播放与时间/状态属性 | CORE-09 | play/pause/toggle/seek/volume/rate/duration 等模块 | 旧返回值、拒绝、mutex、位置恢复、属性描述符与事件通过；接续 CORE-07 / BASE-TYPE-04 的 toggle void 与实际 Promise 分支冲突，不吞拒绝 | H | todo |
 | CORE-11 | artplayer<br>整理媒体事件、ready 与重连 | CORE-10 | 媒体转发、重连、UI 响应职责分离 | readiness 次数/顺序、过期重连、原错误参数有回归 | H | todo |
@@ -442,6 +442,7 @@
 - CORE-05: [记录](changes/2026-09-11-CORE-05-resolved-options.md) [记录](baselines/options-validation.json)
 - CORE-06: [记录](changes/2026-09-11-CORE-06-media-hosts.md) [记录](baselines/media-hosts-validation.json)
 - CORE-07: [记录](changes/2026-09-11-CORE-07-declarations.md) [记录](baselines/declarations-validation.json)
+- CORE-08: [记录](changes/2026-09-11-CORE-08-plugin-manager.md) [记录](baselines/plugins-validation.json)
 - PKG-CHAPTER-01: [记录](changes/2026-09-10-PKG-CHAPTER-01-contract.md) [记录](baselines/chapter-contract.md)
 - PKG-CHAPTER-02: [记录](changes/2026-09-10-PKG-CHAPTER-02-tests.md) [记录](baselines/chapter-validation.json)
 - PKG-CHAPTER-03: [记录](changes/2026-09-10-PKG-CHAPTER-03-typescript-modules.md) [记录](baselines/chapter-migration-validation.json)
@@ -1,5 +1,9 @@
 # 进度与证据

+## 当前实施：CORE-08 插件管理器 TS 完成
+
+插件注册、内置装配、命名与内部类型拆成四个 TS 模块；修复销毁后晚到注册，保持 Promise 结算与同步可见性，新增共享类型扩展入口。120 项 Node/基线、安装 UMD 三浏览器 162 项及 legacy 插件/章节/生命周期 90 项通过；严格打包 27 项运行时、五组类型零诊断。见 [交付](changes/2026-09-11-CORE-08-plugin-manager.md)。关闭 BASE-LIFE-03；公开返回声明和各插件自有资源清理仍有后续责任。当前 214 项，44 完成、170 待办；核心 27 个 TS 文件、chapter 5 个。下一项 CORE-09 URL/切源操作。
+
 ## 当前实施：CORE-07 公开声明逐项协调完成

 OptionInput、数字组件输入、Utils 缺失项、静态 Emitter 和显式 cue 数组重载已补充，旧合法返回赋值样例保留。112 项 Node/基线、安装 UMD 三浏览器 144 项及 legacy 声明/配置 30 项通过；严格打包 27 项运行时与五组类型零诊断。见 [交付](changes/2026-09-11-CORE-07-declarations.md)。关闭 BASE-TYPE-06；BASE-TYPE-04/05/07 的返回/隐式推断冲突保持开放，已接入模块任务与 CORE-21 出口，不代表全部公开类型已精确化。当前 214 项，43 完成、171 待办；下一项 CORE-08 插件管理器与扩展类型。
@@ -7,7 +7,7 @@
 | BASE-LIFE-06 | open / 已复现 | Published switch leaves an unhandled rejection and an unsettled promise when resume fails | CORE-09 |
 | BASE-LIFE-01 | open / 已复现 | Superseded switch resolves along with the latest source | CORE-09 |
 | BASE-LIFE-02 | open / 已复现 | Switch remains unsettled during the bounded observation after destroy | CORE-09 |
-| BASE-LIFE-03 | open / 已复现 | Async plugin registers its result after destroy | CORE-08 |
+| BASE-LIFE-03 | resolved / 已复现 | Async plugin registers its result after destroy | CORE-08 |
 | BASE-LIFE-04 | resolved / 已复现 | Destroying an instance twice unregisters a different live instance | CORE-04 |
 | BASE-LIFE-05 | resolved / 已复现 | Failed constructor leaves initialized markup/listeners until explicit probe cleanup | CORE-04 |
 | BASE-DOM-01 | open / 已复现 | 控件 Tab 不可达 | CORE-23, CORE-17 |
@@ -56,7 +56,7 @@
      "id": "BASE-LIFE-03",
      "title": "Async plugin registers its result after destroy",
      "confirmation": "reproduced",
-      "status": "open",
+      "status": "resolved",
      "owners": [
        "CORE-08"
      ],
@@ -65,7 +65,14 @@
        "refactor/baselines/lifecycle-coverage.md"
      ],
      "compatibleResolution": "按对应 CORE 任务修复，保持合法旧调用；异步取消需明确结算策略，不把 pending 或重复销毁当正常兼容要求。",
-      "closureCriteria": "候选正向回归和旧新差异记录通过；有界观察问题不得仅靠延长等待隐藏。"
+      "closureCriteria": "候选正向回归和旧新差异记录通过；有界观察问题不得仅靠延长等待隐藏。",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-11-CORE-08-plugin-manager.md",
+        "refactor/baselines/plugins-validation.json",
+        "test/plugins.test.js",
+        "test/browser/plugins.spec.js"
+      ],
+      "resolutionRationale": "Closing guards stop late writes, post-close factories and reentrant name/coercion/reset registration. Pending success still fulfills with the registry and public rejection identity is preserved. This closes late registration only, not arbitrary plugin resource ownership."
    },
    {
      "id": "BASE-LIFE-04",
@@ -890,11 +890,14 @@
        "CORE-03",
        "CORE-07"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "H",
      "deliverable": "注册流程、同步/异步结果、插件/事件扩展接口",
      "acceptance": "旧插件同步可见性、重名与命名、销毁中异步插件保持明确语义；处理 baselines/lifecycle-coverage.md 的 BASE-LIFE-03 并增加候选正向回归；接续 CORE-07 / BASE-TYPE-04 的同步/异步注册返回声明冲突，内部返回类型精确，保留历史消费者",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-11-CORE-08-plugin-manager.md",
+        "baselines/plugins-validation.json"
+      ]
    },
    {
      "id": "CORE-09",