refactor(core): CORE-06 type media surfaces and playback hosts

2026-10-24 23:51:20 -08:00 · 2026-09-11 01:18:14 +08:00
1 parent 97d320bd74
commit ee859e4804
@@ -0,0 +1,52 @@
+# CORE-06：内部媒体与宿主类型
+
+## 实现与边界
+
+新增 src/media/types.ts 描述 NativeMedia、CanvasMedia、MediaState 和 PlaybackMethods；
+src/media/hosts.ts 描述最小播放、暂停和布局宿主。五个 player 模块 playMix、pauseMix、
+playingMix、durationMix、rectMix 从 JS 迁移 TS，依赖各自实际需要的字段，避免全部接收整个
+Artplayer 或将所有代理都视为 HTMLVideoElement。入口仍按原顺序调用这些模块。
+
+CanvasMedia 包含 canvas 自身能力及媒体字段，source 允许 MediaBunny 使用的 null；
+textTracks、PiP、视频帧回调及 WebKit 扩展为可选能力，NativeMedia 也不能假定所有浏览器
+都有这些功能。PlaybackMethods 保留实际方法返回值，不将所有代理的 pause 改成 Promise。
+Notice 的 getter 与 setter 分开描述，因为读取是显示状态，写入是消息。
+
+模块 assertion 签名表达 def 安装后的属性，rectMix 保留一处说明过的内部 getter 安装断言；
+没有把代理断言成 HTMLVideoElement，没有新增全局 any。主入口目前仍是 JS，其整体静态类型
+集成属于 CORE-20；这些内部类型不是运行时校验器，也不表示所有第三方 proxy 已经验证。
+
+## 保留契约
+
+API-02/03/04/07/09/10/11：公开 art.video 仍返回原始媒体对象，声明和所有分发入口未改变。
+play 仍 await 底层返回值，再设置 notice、emit play、处理 mutex；pause 同步返回底层结果。
+方法可抽取调用，底层方法 receiver 仍是媒体对象。playing 优先读取 shim 的 boolean，
+否则使用原生状态组合；duration 只按原规则处理 Infinity/假值。播放、暂停、playing 捕获
+原媒体引用，duration 动态读取 template.$video；布局 getter 动态读取 DOM 和页面滚动偏移。
+属性安装顺序和 enumerable/configurable/writable 保持原样。
+
+不新增公开媒体包装层，不要求旧用户修改 art.video 调用。旧公开 video 声明不能用来掩盖
+内部 canvas 类型；公开类型扩展需另有消费者兼容检查。没有在本任务宣称修复 proxy 自身的
+异步绘制销毁问题或验证 MediaBunny codec，代理完整迁移及其资源所有权由各包任务继续处理。
+
+## 验证与交接
+
+- 四项 Node 测试覆盖结构化代理返回值、this、事件/互斥顺序、属性描述符、shim playing、
+  时长规范化和实时布局。已有播放拒绝、切源、销毁回归同步执行。
+- 类型正例覆盖原生/canvas、最小宿主、同步返回及 readonly getter；五项负例拒绝裸 canvas、
+  将 shim 当完整 video、无检查调用可选能力、错误暂停返回和写入只读布局。
+- yarn ci:check：83 单元、4 工程、24 冻结基线，共 111 项通过；28 个生产 TS 文件严格检查，
+  其中核心 23 个、chapter 5 个。未迁移 JS 不计入。
+- yarn build artplayer 和 yarn build:i18n 生成产物；yarn test:package:release 在仓库外安装
+  tarball，27 项运行时及五组类型模式零诊断。包内文档与源码指纹已与最终构建快照核对。
+- 安装 UMD 候选完整三浏览器 132 项通过；安装 legacy 的播放、生命周期和媒体宿主 48 项
+  通过，无重试或跳过。新六项 canvas 测试验证真实播放、暂停、seek、对象身份和布局变化。
+  canvas 来自已有 docs/compiled 工件，附件记录其 SHA；它不是独立安装的 npm 发布 proxy。
+
+详见 [验证报告](../baselines/media-hosts-validation.json)、
+[核心维护地图](../../packages/artplayer/ARCHITECTURE.md) 和
+[类型说明](../../packages/artplayer/types/README.md)。无新增依赖或锁文件修改；test:unit
+加入新宿主测试。未推送、发布或执行远端 CI/真机验收。
+
+本任务单独提交，回退该提交可一并恢复五个 JS 模块、生成产物、文档及任务状态。
+下一项 CORE-07 协调公开声明差异，保留历史合法类型消费并以运行时证据补充类型。
@@ -4,7 +4,7 @@

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

-状态：todo 173 / doing 0 / blocked 0 / done 41 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 172 / doing 0 / blocked 0 / done 42 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -109,7 +109,7 @@
 | CORE-03 | artplayer<br>建立内部资源作用域 | CORE-02 | 监听/订阅/定时器/RAF/请求/URL 的资源登记 | 实例与操作作用域分离，单项清理失败不阻断其他资源 | H | done |
 | CORE-04 | artplayer<br>修复初始化与销毁生命周期 | CORE-03, ENG-05, BASE-07 | 构造失败回收、重复/重入 destroy、instances 修复 | 事件顺序、removeHtml、多实例和销毁中异步有真实回归；处理 baselines/lifecycle-coverage.md 的 BASE-LIFE-04/05 并增加候选正向回归；协调 BASE-PERF-01 销毁后定时器与回调归属 | H | done |
 | 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 | todo |
+| 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 | todo |
 | CORE-08 | artplayer<br>整理插件管理器与扩展类型 | CORE-03, CORE-07 | 注册流程、同步/异步结果、插件/事件扩展接口 | 旧插件同步可见性、重名与命名、销毁中异步插件保持明确语义；处理 baselines/lifecycle-coverage.md 的 BASE-LIFE-03 并增加候选正向回归 | H | todo |
 | 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 |
@@ -440,6 +440,7 @@
 - CORE-03: [记录](changes/2026-09-11-CORE-03-resource-scope.md) [记录](baselines/resource-scope-validation.json)
 - CORE-04: [记录](changes/2026-09-11-CORE-04-instance-lifecycle.md) [记录](baselines/instance-lifecycle-validation.json)
 - 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)
 - 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-06 媒体与宿主类型完成
+
+建立原生 video/canvas 媒体及最小宿主类型，五个播放/布局 mixin 迁移 TS，保持公开 art.video 身份、描述符和返回时序。111 项 Node/基线、安装 UMD 三浏览器 132 项及 legacy 播放/生命周期/代理 48 项通过；严格打包 27 项运行时、五组类型零诊断。见 [交付](changes/2026-09-11-CORE-06-media-hosts.md)。当前 214 项，42 完成、172 待办；核心二十三个 TS 文件、chapter 五个。代理完整迁移和主入口静态集成尚未完成；下一项 CORE-07 逐项协调公开声明差异。
+
 ## 当前实施：CORE-05 配置与默认值 TS 拆分完成

 核心入口接入独立默认值/解析模块，scheme 迁移 TS，区分 Option 与 ResolvedOption 并保留应用扩展类型。107 项 Node/基线、安装 UMD 三浏览器 126 项及 legacy 配置/生命周期 48 项通过；严格打包 27 项运行时、五组类型零诊断。见 [交付](changes/2026-09-11-CORE-05-resolved-options.md)。新登记 BASE-TYPE-06（省略 URL/数字控件 HTML 的声明缺口）交 CORE-07。当前 214 项，41 完成、173 待办；核心十六个 TS 文件、chapter 五个。下一项 CORE-06 内部媒体与宿主类型。
@@ -849,11 +849,14 @@
      "dependsOn": [
        "CORE-05"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "M",
      "deliverable": "原生 video、canvas shim、UI host 类型",
      "acceptance": "不更改公开 art.video 用法，不以 HTMLVideoElement 断言掩盖 shim",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-11-CORE-06-media-hosts.md",
+        "baselines/media-hosts-validation.json"
+      ]
    },
    {
      "id": "CORE-07",