refactor(hls): [PKG-HLS-03] separate menus and SDK lifecycle

refactor/changes/2026-09-12-PKG-HLS-03-modules.md

@@ -0,0 +1,48 @@
+# PKG-HLS-03：HLS 映射、菜单与订阅分层
+
+## 结构调整
+
+入口只协调核心生命周期、实例绑定和刷新代次；mapping.js 负责标签/选择模型，menu.js 负责
+既有 controls/setting API 与回调归属，sdk-events.js 负责 SDK 能力探测、订阅与解绑。
+没有引入 Hls 运行时依赖或新公开参数/方法。自有源码仍是 JS，严格 TS 和公开声明迁移继续
+由 PKG-HLS-04 完成，不能把本步的源码拆分计入 TS 文件数。
+
+## 缺陷修正与兼容处理
+
+- HLS-UI-01：空 levels/audioTracks 或关闭显示开关时删除相应旧菜单，再恢复时可以重建。
+- HLS-LIFE-01：旧菜单回调检查当前实例/菜单归属；核心销毁解绑自身 core/SDK 监听器，保留
+  update 调用不再触碰 SDK/UI。SDK DESTROYING 清理自身菜单、永久拒绝该实例重新绑定。
+- HLS-AUTO-01：自动策略与实际播放档位分开；真实 Auto 播放的标签保持 Auto，手动选择与
+  外部音轨切换通过 SDK 事件同步。无 autoLevelEnabled 能力的旧适配对象保留 currentLevel fallback。
+- 重复标签合并时，如果实际选中项位于后面的重复项，用该项的 value 代表同名组，避免丢失
+  default；这一内部代表项修正单独测试，不将它称为完全无行为变化的文件移动。
+- SDK 事件优先复用未变化的菜单，不在 ABR 事件中反复销毁控件；当前音轨未知时清除旧高亮。
+  同步 SDK 事件延后至本次选择操作完成，保留 write→notice→checks→同步返回顺序。
+- formatter 销毁/替换实例或嵌套 update 时，旧刷新不能覆盖较新的 UI；SDK 注册异常撤回已经
+  安装的监听器并允许重试。没有延后 SDK 写入或将 update 改成 Promise。
+
+公开工厂、name/update、配置、原回调对象与可选索引、控件名、SVG、布局和分发路径保持。
+getName 的旧声明缺陷仍属 04；自动模式不再为错误的当前档位标签调用一次 selected getName，
+列表命名仍按原对象与索引执行。参见 [包内实际架构](../../packages/artplayer-plugin-hls-control/ARCHITECTURE.md)。
+
+## 验证与范围
+
+证据见 [冻结记录](../baselines/hls-modules-validation.json)。Node 专项含共享发布契约和候选修复；
+额外读取本次 build 生成的 main/legacy/ESM 运行同一组正常契约。浏览器使用明确的构建文件，
+覆盖新旧核心/插件组合及真实 SDK 外部事件的选中态、菜单节点身份、清理等行为。
+Hls 1.5.17、Chromium/Firefox、Windows WebKit 的不支持能力边界与旧版测试分开保留。
+
+本步构建产物及 docs/compiled 副本由正式 build 生成；未手改分发文件。真实 Safari/native、
+SDK worker/版本/分组轨道、官方示例和隔离 tarball 消费仍为 05/06，SDK-01/HLS-ENV-01 不关闭。
+完整 ci:check 检查类型、lint、工程与旧基线；没有把源码浏览器或工作区 dist 当作 npm 安装通过。
+本任务没有改变核心源码，不重复全量核心浏览器矩阵。
+
+最终 Node 专项 56 项通过；加入三个构建格式后 83 项通过。modern/legacy 浏览器各 35 passed、
+16 skipped、0 failed/retry；跳过仅 Windows WebKit 的无 MSE 播放场景，能力/失败清理仍执行。
+完整 CI 533 项通过（496 单元、11 工程、26 基线），249 个既有生产 TS 文件严格检查通过。
+modern 为 5257 raw / 2536 gzip9 字节，发布基线为 3156 / 1439；增加订阅与生命周期成本，
+不称为体积优化。package/dist 与 docs/compiled 三格式逐字一致，源/产物/报告指纹已核对。
+既有生成 editor 声明的 unused eslint-disable warning 沿用，不手改生成文件。
+
+回退本任务的独立 commit 可恢复单文件实现及其生成产物，保留 01/02 冻结来源和缺陷观察。
+下一步 PKG-HLS-04，迁移已拆分模块与兼容公开类型，同样独立提交。

refactor/hls-validation.md

@@ -1,5 +1,14 @@
 # HLS control 测试与环境边界
 
+PKG-HLS-03 已在入口、映射、菜单和 SDK 订阅四个模块实施修复，实际地图见
+[包内架构](../packages/artplayer-plugin-hls-control/ARCHITECTURE.md)，本轮证据见
+[模块验证](baselines/hls-modules-validation.json)。下方 02 的数量与缺陷观察属于冻结的迁移前基线。
+新版用例增加事件同步、菜单节点复用和候选生命周期断言，公开 TS 迁移仍是 04。
+
+新增构建文件入口：ARTPLAYER_TEST_HLS 以平台路径分隔符接受 main/legacy/ESM，用于同一 Node
+契约；ARTPLAYER_HLS_ARTIFACT 选择实际 main/legacy 浏览器文件。测试记录实际 hash，错误路径
+明确失败。这是工作区构建验证；隔离安装以及整套 ARTPLAYER_BROWSER_ARTIFACTS 映射仍由 06 完成。
+
 PKG-HLS-02 建立迁移前基线。源码目前仍为 src/index.js，不能把测试任务当作 TS 迁移已完成。
 来源见 [发布契约](baselines/hls-control-contract.md)、[SDK 固定记录](baselines/hls-sdk.json)、
 [本轮证据](baselines/hls-validation.json)。

refactor/plan.md

@@ -4,7 +4,7 @@
 
 基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 215 项，范围 22 个包及工作区/示例。
 
-状态：todo 152 / doing 0 / blocked 0 / done 63 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 151 / doing 0 / blocked 0 / done 64 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
 
 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。
 
@@ -190,7 +190,7 @@
 | --- | --- | --- | --- | --- | --- | --- |
 | PKG-HLS-01 | artplayer-plugin-hls-control<br>核对包契约与历史用法 | BASE-05 | quality/audio 配置、getName、update、控件名及 Hls 实例绑定 | 源码/声明/README/demo/发布包差异已登记；公开形状和版本范围冻结 | H | done |
 | PKG-HLS-02 | artplayer-plugin-hls-control<br>建立特有行为与错误测试 | PKG-HLS-01, ENG-03, ENG-05 | Auto/手动实际 level、音轨、去重/过滤和拓扑变化 | 旧版本行为可重跑，成功/失败/切源/销毁有必要断言 | H | done |
-| PKG-HLS-03 | artplayer-plugin-hls-control<br>整理内部职责与资源 | PKG-HLS-02, CORE-11, CORE-14 | 映射计算与 selector 更新/删除、Hls 事件订阅分离 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | todo |
+| PKG-HLS-03 | artplayer-plugin-hls-control<br>整理内部职责与资源 | PKG-HLS-02, CORE-11, CORE-14 | 映射计算与 selector 更新/删除、Hls 事件订阅分离 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | done |
 | PKG-HLS-04 | artplayer-plugin-hls-control<br>迁移自有源码和公开类型 | PKG-HLS-03, ENG-04, ENG-06, CORE-07 | HLS 能力适配类型、回调上下文和旧 getName 参数 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | H | todo |
 | PKG-HLS-05 | artplayer-plugin-hls-control<br>验证新旧核心和组合 | PKG-HLS-04, CORE-22 | 本地多码率 HLS、换成无轨道来源、旧核心和最终核心 | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | todo |
 | PKG-HLS-06 | artplayer-plugin-hls-control<br>验证分发并同步文档 | PKG-HLS-05, ENG-07 | hls.control.js、依赖范围与回退记录 | tarball 入口/资源、类型、8082 demo 和 README 一致，有回退记录 | H | todo |
@@ -467,3 +467,4 @@
 - PKG-CHAPTER-04: [记录](changes/2026-09-10-PKG-CHAPTER-04-public-types.md) [记录](baselines/chapter-types-validation.json)
 - PKG-HLS-01: [记录](baselines/hls-control-contract.md) [记录](baselines/hls-control-release.json) [记录](changes/2026-09-11-PKG-HLS-01-contract.md)
 - PKG-HLS-02: [记录](hls-validation.md) [记录](baselines/hls-sdk.json) [记录](baselines/hls-validation.json) [记录](changes/2026-09-11-PKG-HLS-02-tests.md)
+- PKG-HLS-03: [记录](changes/2026-09-12-PKG-HLS-03-modules.md) [记录](baselines/hls-modules-validation.json) [记录](hls-validation.md)

refactor/progress.md

@@ -1,5 +1,13 @@
 # 进度与证据
 
+## 最新完成：PKG-HLS-03 源码分层与生命周期修复
+
+HLS control 已拆为入口、选择映射、菜单管理、SDK 订阅四个 JS 模块，保持公开入口和同步调用；修复空轨道旧菜单、过期回调、Auto 标签、重复组丢失选中态，并补事件同步、销毁/订阅失败恢复及重入保护。公开类型和严格 TS 迁移属于下一步 04。
+
+56 项 Node 专项通过，加入三种构建格式后 83 项通过；完整 CI 533 项、249 个既有生产 TS 文件通过。modern/legacy 浏览器各 35 passed、16 skipped，无失败/重试；Windows WebKit 的 MSE 缺口未关闭。三份 package/dist 与 docs/compiled 一致，modern gzip 为 2536 字节（发布基线 1439），不声称体积优化。
+
+见 [交付记录](changes/2026-09-12-PKG-HLS-03-modules.md)、[冻结证据](baselines/hls-modules-validation.json) 与包内 ARCHITECTURE.md。HLS-UI-01/LIFE-01/AUTO-01 已按范围关闭，SDK-01/ENV-01 与其余发布门槛仍 open。64 done、151 todo；本任务独立本地 commit，核实后进入 PKG-HLS-04。没有 push/tag/publish/merge。
+
 ## 最新完成：PKG-HLS-02 行为与 SDK 基线
 
 45 项 HLS Node 契约通过，覆盖源码及发布 main/legacy/ESM；完整 CI 522 项、249 个生产 TS 文件通过。真实 Hls.js 1.5.17 与本地双档位/双音轨流验证四组合的解码、实际选择、pause/seek、切源、失败恢复和销毁。

refactor/risk-table.md

@@ -33,7 +33,7 @@
 | VENDOR-06 | open / 待取证 | monaco-static-assets 来源、版本与许可闭环 | SITE-01, SITE-05 |
 | VENDOR-07 | open / 待取证 | vconsole 来源、版本与许可闭环 | SITE-01 |
 | VENDOR-08 | open / 待取证 | console-bundle 来源、版本与许可闭环 | SITE-01 |
-| SDK-01 | open / 源码/产物事实 | hls.js 实际集成验证范围 | PKG-HLS-03, PKG-HLS-05, EX-03 |
+| SDK-01 | open / 源码/产物事实 | hls.js 实际集成验证范围 | PKG-HLS-05, EX-03 |
 | SDK-02 | open / 待取证 | dash.js 实际集成验证范围 | PKG-DASH-01, EX-03 |
 | SDK-03 | open / 待取证 | flv.js 实际集成验证范围 | EX-03 |
 | SDK-04 | open / 待取证 | mpegts.js 实际集成验证范围 | EX-03 |
@@ -120,7 +120,7 @@
 | BASE-LIFE-47 | resolved / 已复现 | AirPlay methods can call a picker or publish events and notices after destruction | CORE-20 |
 | BASE-LIFE-48 | resolved / 已复现 | Proxy-time destruction cannot clean a template before its public assignment | CORE-20 |
 | BASE-LIFE-49 | resolved / 已复现 | Constructor and Player initialization continue after a callback destroys the instance | CORE-20 |
-| HLS-UI-01 | open / 已复现 | 空轨道和关闭配置仍残留 HLS 菜单 | PKG-HLS-03 |
-| HLS-LIFE-01 | open / 已复现 | 过期 HLS 选择回调与销毁后 update 仍工作 | PKG-HLS-03 |
-| HLS-AUTO-01 | open / 已复现 | 真实 ABR 播放的 Auto 标签在 update 后丢失 | PKG-HLS-03, PKG-HLS-05 |
+| HLS-UI-01 | resolved / 已复现 | 空轨道和关闭配置仍残留 HLS 菜单 | PKG-HLS-03 |
+| HLS-LIFE-01 | resolved / 已复现 | 过期 HLS 选择回调与销毁后 update 仍工作 | PKG-HLS-03 |
+| HLS-AUTO-01 | resolved / 已复现 | 真实 ABR 播放的 Auto 标签在 update 后丢失 | PKG-HLS-03, PKG-HLS-05 |
 | HLS-ENV-01 | open / 已复现 | Windows WebKit 缺失 MSE，HLS 播放矩阵尚缺 Safari 证据 | PKG-HLS-05, REL-09, REVIEW-02 |

refactor/risks.json

@@ -606,7 +606,6 @@
       "confirmation": "source-observed",
       "status": "open",
       "owners": [
-        "PKG-HLS-03",
         "PKG-HLS-05",
         "EX-03"
       ],
@@ -2527,7 +2526,7 @@
       "id": "HLS-UI-01",
       "title": "空轨道和关闭配置仍残留 HLS 菜单",
       "confirmation": "reproduced",
-      "status": "open",
+      "status": "resolved",
       "owners": [
         "PKG-HLS-03"
       ],
@@ -2537,13 +2536,19 @@
         "test/browser/hls-control.spec.js"
       ],
       "compatibleResolution": "使用既有 remove API 清理不再可用的 UI，保留菜单名称及选择语义。",
-      "closureCriteria": "候选空轨道、关闭开关及恢复测试通过。"
+      "closureCriteria": "候选空轨道、关闭开关及恢复测试通过。",
+      "resolutionEvidence": [
+        "refactor/baselines/hls-modules-validation.json",
+        "refactor/changes/2026-09-12-PKG-HLS-03-modules.md",
+        "packages/artplayer-plugin-hls-control/ARCHITECTURE.md"
+      ],
+      "resolutionRationale": "PKG-HLS-03 候选回归与新旧核心/实际 Hls.js 1.5.17 验证：空菜单、过期回调/订阅、Auto 及音轨同步。环境/SDK 扩展范围仍由 SDK-01 与 HLS-ENV-01 保持 open，不据此放行发布。"
     },
     {
       "id": "HLS-LIFE-01",
       "title": "过期 HLS 选择回调与销毁后 update 仍工作",
       "confirmation": "reproduced",
-      "status": "open",
+      "status": "resolved",
       "owners": [
         "PKG-HLS-03"
       ],
@@ -2553,13 +2558,19 @@
         "test/browser/hls-control.spec.js"
       ],
       "compatibleResolution": "限制过期实例回调，整理监听器归属，Hls 仍由调用方销毁。",
-      "closureCriteria": "替换、销毁、重入及 SDK 订阅解绑的候选回归通过。"
+      "closureCriteria": "替换、销毁、重入及 SDK 订阅解绑的候选回归通过。",
+      "resolutionEvidence": [
+        "refactor/baselines/hls-modules-validation.json",
+        "refactor/changes/2026-09-12-PKG-HLS-03-modules.md",
+        "packages/artplayer-plugin-hls-control/ARCHITECTURE.md"
+      ],
+      "resolutionRationale": "PKG-HLS-03 候选回归与新旧核心/实际 Hls.js 1.5.17 验证：空菜单、过期回调/订阅、Auto 及音轨同步。环境/SDK 扩展范围仍由 SDK-01 与 HLS-ENV-01 保持 open，不据此放行发布。"
     },
     {
       "id": "HLS-AUTO-01",
       "title": "真实 ABR 播放的 Auto 标签在 update 后丢失",
       "confirmation": "reproduced",
-      "status": "open",
+      "status": "resolved",
       "owners": [
         "PKG-HLS-03",
         "PKG-HLS-05"
@@ -2570,7 +2581,13 @@
         "test/browser/hls-control.spec.js"
       ],
       "compatibleResolution": "区分自动策略与实际播放档位，保留手动及 Auto 选择值。",
-      "closureCriteria": "实际 SDK 自动/手动切换和事件同步通过。"
+      "closureCriteria": "实际 SDK 自动/手动切换和事件同步通过。",
+      "resolutionEvidence": [
+        "refactor/baselines/hls-modules-validation.json",
+        "refactor/changes/2026-09-12-PKG-HLS-03-modules.md",
+        "packages/artplayer-plugin-hls-control/ARCHITECTURE.md"
+      ],
+      "resolutionRationale": "PKG-HLS-03 候选回归与新旧核心/实际 Hls.js 1.5.17 验证：空菜单、过期回调/订阅、Auto 及音轨同步。环境/SDK 扩展范围仍由 SDK-01 与 HLS-ENV-01 保持 open，不据此放行发布。"
     },
     {
       "id": "HLS-ENV-01",

refactor/tasks.json

@@ -1827,11 +1827,15 @@
         "CORE-11",
         "CORE-14"
       ],
-      "status": "todo",
+      "status": "done",
       "risk": "H",
       "deliverable": "映射计算与 selector 更新/删除、Hls 事件订阅分离",
       "acceptance": "结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-12-PKG-HLS-03-modules.md",
+        "baselines/hls-modules-validation.json",
+        "hls-validation.md"
+      ]
     },
     {
       "id": "PKG-HLS-04",

refactor/third-party.json

@@ -1023,16 +1023,18 @@
       "id": "hls.js",
       "riskId": "SDK-01",
       "owners": [
-        "PKG-HLS-03",
         "PKG-HLS-05",
         "EX-03"
       ],
       "sourceFiles": [
         "packages/artplayer-plugin-hls-control/src/index.js",
+        "packages/artplayer-plugin-hls-control/src/mapping.js",
+        "packages/artplayer-plugin-hls-control/src/menu.js",
+        "packages/artplayer-plugin-hls-control/src/sdk-events.js",
         "docs/assets/example/hls.control.js"
       ],
       "contract": "Caller supplies art.hls; homepage demo loads hls.js 1.5.17. Preserve quality/audio selectors and old core integration.",
-      "validationStatus": "Hls.js 1.5.17 frozen in refactor/baselines/hls-sdk.json; Chromium/Firefox local playback baseline verified in PKG-HLS-02. Windows WebKit has no MSE; Safari/native/worker/version and installed-package matrices remain open. See refactor/hls-validation.md.",
+      "validationStatus": "PKG-HLS-03 verifies actual Hls.js 1.5.17 on Chromium/Firefox with source/published core and modern/legacy candidate builds. Auto/topology/lifecycle defects fixed; Windows WebKit has no MSE. Safari/native, detach/reattach, worker, grouped tracks, versions and isolated installation remain HLS-05/06 and EX-03.",
       "demoPathsSource": "refactor/baselines/demo-inventory.json"
     },
     {