refactor(core): CORE-10 type playback properties and add compatible controls view

2026-10-21 12:41:20 -08:00 · 2026-09-11 02:51:55 +08:00
1 parent 44f4e083a9
commit 5e31274f1d
@@ -0,0 +1,40 @@
+# CORE-10 播放与时间/状态属性
+
+状态：完成；本地源码、产物、安装消费和三浏览器检查通过。
+
+## 范围与兼容决策
+
+迁移 toggle/currentTime/seek/volume/playbackRate/played/loaded/state 八个 mixin，增加 media/playback.ts 最小宿主类型；play/pause/playing/duration 已在 CORE-06/09 迁移，本任务继续复验。显示模式实现归 CORE-16，媒体转发归 CORE-11，剩余通用 attr/type 门面归 CORE-20。
+
+保留 API-02/03/04/07：toggle 精确返回当前 play/pause 分支结果；currentTime 保持 parseFloat/NaN 忽略/范围限制；seek 保留原输入事件参数；forward 的 JS 加法与 backward 的减法不互换；音量按原 parseInt 百分比格式且非零才持久化；速率假值重置 1、相同值不刷新通知。played/loaded 在未加载或零时长时可能 NaN/Infinity，不能为了测试方便改成 0。保留捕获媒体引用和 duration 动态读取的差别。
+
+state getter 优先 mini、pip、fullscreen、fullscreenWeb；setter 仅退出其他状态，不主动进入指定状态。未把它变成新的显示模式状态机。
+
+## 类型策略
+
+新增纯类型 PlaybackControls，现有 art 可直接赋给该视图，无转换/代理对象；toggle 返回 Promise<void> | void。原 art.toggle(): void 声明保留，使旧合法赋值继续编译。此为 BASE-TYPE-04 的 toggle 分支兼容方案，plugins.add 及总体公开门面仍由 CORE-21 收口。
+
+发现 BASE-TYPE-08：seek/forward/backward/switch/quality 的运行时描述符只有 setter，读取 undefined；旧公共声明却有数字、字符串或数组 getter。源接口按实际读取值建模，旧公开读取声明暂保留并交 CORE-21，不能凭添加 getter 来伪造兼容。
+
+## 验证与回退
+
+完整证据见 [playback-properties-validation.json](../baselines/playback-properties-validation.json)，含源码、声明、测试、生成编辑器声明和安装包指纹，以及逐项浏览器结果。
+
+| 检查 | 结果 |
+| --- | --- |
+| yarn ci:check | 145 项：116 单元、4 工程、25 基线；47 个生产 TS 文件严格编译 |
+| 属性专项 | 新增 8 项 Node，覆盖转换、通知、存储、范围、描述符、状态和引用 |
+| 安装包消费 | 核心/chapter 的 27 项运行时通过，五组类型模式零诊断 |
+| UMD 三浏览器 | 195 项通过，无跳过、重试或 flaky |
+| legacy 三浏览器 | 195 项通过，无跳过、重试或 flaky |
+| 生成声明 | build:ts 重新生成编辑器声明；PlaybackControls 命名导出进入 CJS/ESM/共享类型入口 |
+
+测试入口：test/playback-properties.test.js、test/types/playback-properties.ts、test/types/playback-public.ts、test/browser/playback-properties.spec.js；既有 play/source/canvas 及发布基线全部继续通过。新旧类型消费同时包含旧 toggle:void、命令属性读取赋值和新 PlaybackControls 分支。
+
+没有执行实体设备、远端 CI、完整 fullscreen/PiP 或全部生态包发布验收。本任务不关闭 BASE-TYPE-04/08 的剩余公共门面工作。
+
+专项浏览器首轮 WebKit 的旧/新版本均在 seek 后出现空 buffered 区间，说明“此时必须大于 0”的测试假设不成立。改为与同一媒体的原始 TimeRanges 最后一个区间精确对照，保留空区间检查；非空/多区间公式由专项单元测试固定验证。未修改实现或添加等待来隐藏差异。
+
+完整检查另发现风险台账的负向测试依赖“第一项风险尚未关闭”。CORE-09 关闭该项后，重复设置 resolved 已不是非法操作。测试现在显式移除关闭证据，继续验证无证据关闭必定失败，不再依赖台账顺序或当前完成程度。
+
+未新增依赖或改变锁文件/版本。任务结束单独本地 commit。需要回退时整体回退源码、声明、生成产物和文档；不单独删除类型桥接或源宿主文件。
@@ -4,7 +4,7 @@

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

-状态：todo 169 / doing 0 / blocked 0 / done 45 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 168 / doing 0 / blocked 0 / done 46 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -113,7 +113,7 @@
 | 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 | 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 | done |
-| 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-10 | artplayer<br>迁移播放与时间/状态属性 | CORE-09 | play/pause/toggle/seek/volume/rate/duration 等模块 | 旧返回值、拒绝、mutex、位置恢复、属性描述符与事件通过；接续 CORE-07 / BASE-TYPE-04 的 toggle void 与实际 Promise 分支冲突，不吞拒绝 | H | done |
 | CORE-11 | artplayer<br>整理媒体事件、ready 与重连 | CORE-10 | 媒体转发、重连、UI 响应职责分离 | readiness 次数/顺序、过期重连、原错误参数有回归 | H | todo |
 | CORE-12 | artplayer<br>迁移模板及公开资源入口 | CORE-06, CORE-04, BASE-04 | template/icons/i18n/style、SSR 与 proxy 挂载 | DOM/CSS/global/样式注入、i18n 子路径及 SSR import 保持；不把 SSR import/useSSR 保持扩大为服务端构造播放器；复跑 BASE-05 的 SSR import/模板、浏览器 useSSR 节点复用和非浏览器构造错误；接续 VENDOR-01/02，核对 screenfull/hint 复制版本、修改与分发通知，保留 DOM/CSS/fullscreen 行为 | H | todo |
 | CORE-13 | artplayer<br>迁移组件注册与控件 | CORE-12, CORE-08 | Component/control/layer/contextmenu 的资源与 TS 边界 | add/update/remove、name、selector、mounted/beforeUnmount 通过；处理 BASE-DOM-02 窄容器控件裁切，保留 controls.update 的旧 undefined 返回值 | H | todo |
@@ -124,7 +124,7 @@
 | CORE-18 | artplayer<br>迁移内置插件和提示模块 | CORE-14, CORE-16, CORE-17 | autoPlayback/autoOrientation/fastForward/lock/miniProgressBar 及 info/notice/loading/mask | 默认启用条件、storage 格式、定时器/动画清理通过；结合 BASE-PERF-01 防止销毁后重新安排 notice timer；接续 BASE-TYPE-07 的 notice.show boolean getter 与历史读类型冲突 | M | todo |
 | CORE-19 | artplayer<br>整理进度、质量、缩略图和截图 | CORE-10, CORE-13, CORE-16 | 相关 player/control 功能与纯计算分离 | 截图跨域失败、缩略图布局、quality/进度边界保持 | M | todo |
 | CORE-20 | artplayer<br>收敛核心入口与依赖方向 | CORE-14, CORE-15, CORE-18, CORE-19 | Artplayer 门面、初始化依赖与最终目录 | 所有核心自有源码迁移，公开描述符/静态接口/事件差分通过 | H | todo |
-| CORE-21 | artplayer<br>生成核心声明并校验包内容 | CORE-20, ENG-07 | 由 TS 生成的既有入口声明与三种发布产物 | 内部类型不泄漏，旧 JS/TS 消费者与 i18n 通过；逐项完成 CORE-07 留下的 BASE-TYPE-04/05/07 声明方案，旧合法消费者与实际返回分别留证；不能以虚假的交叉返回类型或改变运行时来掩盖冲突，未决项阻止核心声明出口 | H | todo |
+| CORE-21 | artplayer<br>生成核心声明并校验包内容 | CORE-20, ENG-07 | 由 TS 生成的既有入口声明与三种发布产物 | 内部类型不泄漏，旧 JS/TS 消费者与 i18n 通过；逐项完成 CORE-07 留下的 BASE-TYPE-04/05/07 声明方案，旧合法消费者与实际返回分别留证；不能以虚假的交叉返回类型或改变运行时来掩盖冲突，未决项阻止核心声明出口；处理 CORE-10 / BASE-TYPE-08 的 setter-only 属性虚构 getter 声明，并复核 PlaybackControls 精确视图与旧 toggle 声明共存策略 | H | todo |
 | CORE-23 | artplayer<br>检查并补齐键盘、焦点与可访问名称 | CORE-13, CORE-14, CORE-17, ENG-05, BASE-04 | 主要控件/设置/模式退出的键盘与焦点回归、名称和字幕可用性检查及必要兼容修正 | 保持旧快捷键和 DOM/CSS 钩子；真实浏览器验证，不以静态属性检查代替交互；处理 BASE-DOM-01 的主要控件 Tab 不可达，保留既有名称与快捷键 | H | todo |
 | CORE-22 | artplayer<br>核心阶段完整验收 | CORE-21, CORE-23, PILOT-01, ENG-08, ENG-10 | 核心与旧插件的可自动化完整回归、资源/性能及明确外部验证缺口 | 核心自动化和公开差异处置通过；真实环境缺口链接包集成/REL 门槛，阶段完成不代表可公开发布 | H | todo |

@@ -444,6 +444,7 @@
 - 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)
 - CORE-09: [记录](changes/2026-09-11-CORE-09-source-operations.md) [记录](baselines/source-operations-validation.json)
+- CORE-10: [记录](changes/2026-09-11-CORE-10-playback-properties.md) [记录](baselines/playback-properties-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-10 播放与时间/状态属性完成
+
+八个 mixin 迁移 TS，新增最小播放属性宿主；保持转换、通知、存储、进度和状态优先级。新增 PlaybackControls 精确视图，旧 toggle 声明仍兼容。145 项 Node/基线、安装 UMD 与 legacy 各 195 项三浏览器、打包 27 项运行时和五组类型检查通过。见 [交付](changes/2026-09-11-CORE-10-playback-properties.md)。发现 BASE-TYPE-08 的只写属性虚构 getter 声明，已交 CORE-21；没有添加运行时 getter 来掩盖它。当前 214 项，46 完成、168 待办；核心 42 个 TS 文件、chapter 5 个。下一项 CORE-11 媒体事件、ready 与重连。
+
 ## 当前实施：CORE-09 URL 与切源操作完成

 URL/switch 门面迁移 TS，新增四个 source 模块，统一切源取消、事件清理、同步代理事件和 Promise 结算；真实 playMix 同步接入源身份，避免晚到播放覆盖新状态。137 项 Node/基线、安装 UMD 与 legacy 各 183 项三浏览器检查、打包 27 项运行时和五组类型检查通过。见 [交付](changes/2026-09-11-CORE-09-source-operations.md)。关闭 BASE-LIFE-01/02/06；customType 外部 SDK 清理、对象 URL 归属和过期重连仍由对应后续任务处理。当前 214 项，45 完成、169 待办；核心 33 个 TS 文件、chapter 5 个。下一项 CORE-10 播放与时间/状态属性。
@@ -51,3 +51,4 @@
 | EVENT-ONCE-01 | resolved / 已复现 | Nested dispatch snapshots invoke the same once registration twice | CORE-02 |
 | BASE-TYPE-06 | resolved / 已复现 | Public Option requires url and excludes numeric control HTML accepted by existing JS | CORE-07 |
 | BASE-TYPE-07 | open / 已复现 | Setting returns, subtitle contextual payloads and notice getter conflict with historical declarations | CORE-07, CORE-14, CORE-15, CORE-18, CORE-21 |
+| BASE-TYPE-08 | open / 已复现 | Write-only player commands have fictitious public getter declarations | CORE-21 |
@@ -281,7 +281,8 @@
      ],
      "compatibleResolution": "保留旧声明接受范围并协调精确重载/扩展，不静默把同步注册改成 async。",
      "closureCriteria": "返回值类型与运行时差异逐项说明，旧合法消费和拒绝传播回归通过。",
-      "scopeNote": "CORE-07 retains historical legal return assignments and records actual runtime separately; incompatible return tightening remains open through CORE-21. No release waiver."
+      "scopeNote": "CORE-07 retains historical legal return assignments and records actual runtime separately; incompatible return tightening remains open through CORE-21. No release waiver.",
+      "playbackResolution": "CORE-10 adds assignable PlaybackControls with Promise<void> | void toggle; legacy root void remains accepted. All five installed type modes pass. The overall facade and plugins.add conflict stay open through CORE-21."
    },
    {
      "id": "BASE-DIST-01",
@@ -871,6 +872,25 @@
      "compatibleResolution": "Keep legacy consumers; add explicit cue-array listener overloads, type internal implementations accurately, and resolve remaining generated/public facade contracts at CORE-21 without false intersections.",
      "closureCriteria": "Actual setting/null/void and notice boolean returns, cue array callbacks and old legal type consumers all have an explicit compatible declaration strategy and package tests.",
      "scopeNote": "CORE-07 provides runtime evidence and explicit cue-array overloads; old inferred scalar event callbacks and return signatures are not claimed corrected."
+    },
+    {
+      "id": "BASE-TYPE-08",
+      "title": "Write-only player commands have fictitious public getter declarations",
+      "confirmation": "reproduced",
+      "status": "open",
+      "owners": [
+        "CORE-21"
+      ],
+      "evidence": [
+        "packages/artplayer/types/player.d.ts",
+        "test/playback-properties.test.js",
+        "test/browser/playback-properties.spec.js",
+        "refactor/changes/2026-09-11-CORE-10-playback-properties.md",
+        "refactor/baselines/playback-properties-validation.json",
+        "test/types/declaration-legacy.ts"
+      ],
+      "compatibleResolution": "Keep historical consumer acceptance, model source command reads as undefined, and provide an accurate public facade without inventing runtime getters.",
+      "closureCriteria": "seek/forward/backward/switch/quality reads and writes have an explicit accurate compatibility strategy validated against old TypeScript consumers and real package descriptors."
    }
  ]
 }
@@ -13,7 +13,10 @@ test('Risk register rejects omitted findings, missing owners and unsupported clo
  for (const mutate of [
    value => value.items = value.items.filter(item => item.id !== 'BASE-LIFE-04'),
    value => value.items[0].owners = ['NO-SUCH-TASK'],
-    value => value.items[0].status = 'resolved',
+    (value) => {
+      value.items[0].status = 'resolved'
+      delete value.items[0].resolutionEvidence
+    },
    value => value.items[0].evidence = ['../outside-workspace'],
  ]) {
    const changed = structuredClone(register)
@@ -930,11 +930,14 @@
      "dependsOn": [
        "CORE-09"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "H",
      "deliverable": "play/pause/toggle/seek/volume/rate/duration 等模块",
      "acceptance": "旧返回值、拒绝、mutex、位置恢复、属性描述符与事件通过；接续 CORE-07 / BASE-TYPE-04 的 toggle void 与实际 Promise 分支冲突，不吞拒绝",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-11-CORE-10-playback-properties.md",
+        "baselines/playback-properties-validation.json"
+      ]
    },
    {
      "id": "CORE-11",
@@ -1123,7 +1126,7 @@
      "status": "todo",
      "risk": "H",
      "deliverable": "由 TS 生成的既有入口声明与三种发布产物",
-      "acceptance": "内部类型不泄漏，旧 JS/TS 消费者与 i18n 通过；逐项完成 CORE-07 留下的 BASE-TYPE-04/05/07 声明方案，旧合法消费者与实际返回分别留证；不能以虚假的交叉返回类型或改变运行时来掩盖冲突，未决项阻止核心声明出口",
+      "acceptance": "内部类型不泄漏，旧 JS/TS 消费者与 i18n 通过；逐项完成 CORE-07 留下的 BASE-TYPE-04/05/07 声明方案，旧合法消费者与实际返回分别留证；不能以虚假的交叉返回类型或改变运行时来掩盖冲突，未决项阻止核心声明出口；处理 CORE-10 / BASE-TYPE-08 的 setter-only 属性虚构 getter 声明，并复核 PlaybackControls 精确视图与旧 toggle 声明共存策略",
      "evidence": []
    },
    {