docs(refactor): [PKG-HLS-01] freeze HLS control release contract

2026-10-14 08:26:16 -08:00 · 2026-09-11 23:29:39 +08:00
1 parent adec20213f
commit cbbdc03a7c
@@ -1,5 +1,9 @@
 # 已发布基线

+PKG-HLS-01 另行固定 HLS control 1.1.0，见 [契约](hls-control-contract.md) 与
+[归档指纹](hls-control-release.json)。重跑 `node refactor/scripts/hls-contract.mjs`；
+它验证独立冻结记录及历史源码，不改下方 BASE-01 数据，也不表示 HLS 真实播放已通过。
+
 BASE-01 于 2026-09-10 固定核心与 chapter 的 npm 发布内容，数据在 [releases.json](releases.json)。这不是全生态兼容通过报告。

 | 包 | 工作区版本 | 已固定发布基线 | 后续目标 |
@@ -0,0 +1,63 @@
+# HLS control 1.1.0 迁移契约
+
+PKG-HLS-01，2026-09-11。发布依据是 [冻结归档记录](hls-control-release.json)，源码依据为
+adec20213f00375b16231e616d1e249a12ffd345，示例为 docs/assets/example/hls.control.js。
+运行 `node refactor/scripts/hls-contract.mjs` 重验，不随迁移覆盖历史指纹。
+
+## 发布与来源
+
+固定 npm artplayer-plugin-hls-control 1.1.0：SHA-512 SRI、SHA-256、六个成员及各成员摘要均已验证。
+README、package.json、声明经 LF 归一化与该提交相同。TypeScript 5.9.3 提取 uniqBy 和
+artplayerPluginHlsControl 后用 esbuild 0.27.7 归一化，两边 SHA-256 同为
+`b22a09f4de5b56005c5122014624d76a91410e9517889d3e7b1c70b8efb2b554`。
+比较不含 SVG 字符串或 bundler 包装，不等于用现有工具链逐字重建所有发布文件。
+
+查询时 registry 列出 1.0.0、1.0.1、1.1.0，latest 为 1.1.0；时间与 URL 保存在 JSON。
+登记的 gitHead daf133b22630b4a0eecfa3336bbddab0e9119d96 对应包版本 1.0.2，不能当作
+发布源码证明。计划版本 2.0.0，发布前另查版本占用。旧版行为以 tarball 为准。
+
+## 公开边界及测试入口
+
+| ID | 当前行为与兼容要求 | 后续覆盖 |
+| --- | --- | --- |
+| HLS.factory | default/global 为 artplayerPluginHlsControl；工厂默认参数 `{}`，返回同步注册函数 | HLS-02 各格式消费、无参调用 |
+| HLS.result | 注册返回 `{ name: 'artplayerPluginHlsControl', update }`；update 无参、同步返回 undefined | HLS-02 返回与键集合 |
+| HLS.binding | 注册捕获 template.$video；每次 update 检查 art.hls.media 与它同一引用，失败通过 errorHandle 抛出 Cannot find instance of HLS from "art.hls" | HLS-02 缺失/外部媒体/替换实例 |
+| HLS.schedule | 注册时不执行 update；订阅 ready 和 restart，外加公开手动 update；未订阅 Hls SDK 事件 | HLS-02 调用顺序；HLS-03 补同步与解绑 |
+| HLS.option | quality/audio 均可选，子项 control/setting/title/auto/getName；两个显示开关默认关闭，update 仍验证 Hls | HLS-02 默认、单独和同时启用 |
+| HLS.quality | 标签取 name 或 height 加 P；按标签保留第一个，按原索引倒序；最后追加 Auto value=-1；选中项依据 currentLevel | HLS-02 重复/排序/Auto/manual |
+| HLS.audio | 标签取 name/lang/language；按标签保留第一个并维持原顺序；value 为 track.id，不附加 Auto 选项 | HLS-02 标签/排序；HLS-05 实际分组轨道 |
+| HLS.label | title/auto 使用逻辑或默认值；当前标签 getName(item) 在列表 getName(item,index) 之前执行；普通函数调用，无 art 上下文绑定 | HLS-02 参数数目、对象身份、回调异常 |
+| HLS.select | 先写 currentLevel/audioTrack，再 notice，再按开关 controls.check/setting.check，返回 item.html；不返回 Promise | HLS-02 顺序、值和引用 |
+| HLS.ui | 名称 hls-quality/hls-audio；control 在 right，padding 0 10px；setting 宽 200、原 SVG 图标、title 与 tooltip；两处共享 selector/onSelect | HLS-02 对象形状；HLS-05 真 DOM |
+| HLS.owner | Hls 由消费者创建/销毁；插件没有公开 destroy，不拥有媒体实例；旧实现没有自身销毁/SDK 解绑逻辑 | HLS-02 销毁观察；HLS-03 整理资源归属 |
+
+uniqBy 对 undefined 标签不去重；重复标签留下首条，可能移除实际选中的重复条目。
+getName 错误同步传播；质量 UI 可在音轨更新失败前已经提交。不在重构时未经说明改成
+异步回调、绑定 this、克隆 SDK 输入项或全局吞掉异常。
+
+保留根入口和 /legacy 的 exports 条件、main/module/types/legacy 路径与全局名。
+包没有 Hls 或核心 dependency/peerDependencies 最低版本声明，不新造最低版本，也不宣称
+任意旧版本都兼容。旧核心 5.4.0 与当前核心的四组合须由 HLS-05 实测；这里只冻结待验证范围。
+示例绑定 Hls.js 1.5.17，此版本是首个 SDK 实测基线，不是已证明的最低/最高支持版本。
+
+## 声明、示例与设计差异
+
+| 观察 | 依据与边界 | 处理任务 |
+| --- | --- | --- |
+| 工厂 option 声明必填，运行时可省略 | 局部 Config 未按名称导出；只导出 default | HLS-02 类型复现，HLS-04 兼容修正 |
+| getName 声明只接受 object，漏了列表索引 | 当前标签只传一个参数，所以未来索引应可缺省；不能声明总是 number | HLS-02 消费样例，HLS-04 类型 |
+| /legacy 缺少旧解析器 typesVersions fallback | exports types 存在不代表 TS 4.3 node 解析可用 | HLS-04/06 解析矩阵 |
+| 空 levels/audioTracks 直接返回，关闭显示开关也不删除旧菜单 | 静态可见缺少 controls.remove/setting.remove | HLS-02 复现，HLS-03 修复 |
+| 保留旧 selector 回调仍写旧 Hls | 回调捕获上次 update 的实例；公开 update 则读取新 art.hls | HLS-02 复现，HLS-03 限制过期回调 |
+| Auto 依据 currentLevel，未使用 autoLevelEnabled | 不能仅用 currentLevel=-1 的 stub 代表实际 ABR；真实播放档位与手动策略分别取证 | HLS-02/05 SDK 实测，HLS-03 改进 |
+| 音轨当前标签以数组索引取值，选择值用 id | 不仅凭两种写法不同就认定真实 SDK 错误，须验证 Hls 分组后的 id/index 关系 | HLS-02/05 |
+| 示例原生 HLS fallback 未提供 art.hls | customType 中只赋 video.src，插件仍安装；ready 校验可能抛错 | HLS-05 浏览器取证与示例修复 |
+| 示例每次切源注册新的 destroy 回调 | 重建时已销毁旧 Hls，旧闭包仍被保留 | HLS-05/06 生命周期及示例修复 |
+
+README 目前仅简介、demo、许可，不能从中推断未声明的行为。示例同时启用两个菜单，使用
+level.height 和 track.name 回调以及远程 HLS；后续用本地多档位/多音轨样本补确定性验证。
+
+本步只核对来源和契约，没有生产代码变更、SDK 播放或浏览器验收。后续结构规划是把选择项
+映射、核心 UI 提交/删除、SDK 状态与订阅、公开兼容入口分开；实际实现地图随 HLS-03/04
+写入包内 ARCHITECTURE.md，不把未实现的设计写成当前架构。
@@ -0,0 +1,119 @@
+{
+  "schemaVersion": 1,
+  "task": "PKG-HLS-01",
+  "capturedAt": "2026-09-11T15:21:31.189Z",
+  "sourceCommit": "adec20213f00375b16231e616d1e249a12ffd345",
+  "registryObservation": {
+    "capturedAt": "2026-09-11T15:20:11.198Z",
+    "registryUrl": "https://registry.npmjs.org/artplayer-plugin-hls-control",
+    "distTags": {
+      "latest": "1.1.0"
+    },
+    "versions": [
+      "1.0.0",
+      "1.0.1",
+      "1.1.0"
+    ],
+    "publishedAt": "2026-03-12T14:20:47.883Z",
+    "note": "Observed metadata only; not a promise of future latest version or target-version availability."
+  },
+  "release": {
+    "name": "artplayer-plugin-hls-control",
+    "version": "1.1.0",
+    "metadataUrl": "https://registry.npmjs.org/artplayer-plugin-hls-control/1.1.0",
+    "tarball": "https://registry.npmjs.org/artplayer-plugin-hls-control/-/artplayer-plugin-hls-control-1.1.0.tgz",
+    "integrity": "sha512-lWN5oUOWDorWFHdzKcmy9Z8eHcf5f5EcUGDrxBsZBX7aEL5dGRlHPQ5+wqQEizr38D9PYPfTI/nCyun2yFopEw==",
+    "sha256": "598c354d78d3cb77965136fa61dfc0f94cdea6906a91a30781c1acef2b0c3e8b",
+    "archiveBytes": 3192,
+    "registryGitHead": "daf133b22630b4a0eecfa3336bbddab0e9119d96",
+    "files": {
+      "package/README.md": "42bd00dca467b581f6b3e8399ad1a416d68edcc52d42e6cb51b66f1749694556",
+      "package/dist/artplayer-plugin-hls-control.js": "7a6ce18a0b16f61f6149e0ea77efbb6e0503f997d39afe84271b59e366759e6d",
+      "package/dist/artplayer-plugin-hls-control.legacy.js": "893a3de27f9ed02b4b61f03732aec03bfcaf50d02c9beb15cc8a5767ef9121a0",
+      "package/dist/artplayer-plugin-hls-control.mjs": "85c4de4940e031d835b4de3ccf68af449d10aec4f630c89ecaf62f5503348931",
+      "package/package.json": "710ec2a27dc71f7254e7a1d2eb7cff3f56a6e23811047ac97356f1b18c8ac8b5",
+      "package/types/artplayer-plugin-hls-control.d.ts": "7dd8fdf556932e9cf6140b7513c05155cad6d486e2484bf06c6d48f6e823832a"
+    },
+    "manifest": {
+      "name": "artplayer-plugin-hls-control",
+      "version": "1.1.0",
+      "description": "Hls control plugin for ArtPlayer",
+      "author": "Harvey Zhao <laozhaochaguan@gmail.com>",
+      "license": "MIT",
+      "homepage": "https://artplayer.org",
+      "repository": {
+        "type": "git",
+        "url": "git+https://github.com/zhw2590582/ArtPlayer.git"
+      },
+      "bugs": {
+        "url": "https://github.com/zhw2590582/ArtPlayer/issues"
+      },
+      "keywords": [
+        "html5",
+        "video",
+        "player"
+      ],
+      "exports": {
+        ".": {
+          "types": "./types/artplayer-plugin-hls-control.d.ts",
+          "import": "./dist/artplayer-plugin-hls-control.mjs",
+          "require": "./dist/artplayer-plugin-hls-control.js"
+        },
+        "./legacy": {
+          "types": "./types/artplayer-plugin-hls-control.d.ts",
+          "import": "./dist/artplayer-plugin-hls-control.legacy.js",
+          "require": "./dist/artplayer-plugin-hls-control.legacy.js"
+        }
+      },
+      "main": "./dist/artplayer-plugin-hls-control.js",
+      "module": "./dist/artplayer-plugin-hls-control.mjs",
+      "types": "./types/artplayer-plugin-hls-control.d.ts",
+      "legacy": "./dist/artplayer-plugin-hls-control.legacy.js",
+      "browserslist": "last 1 Chrome version"
+    }
+  },
+  "source": {
+    "packages/artplayer-plugin-hls-control/package.json": "710ec2a27dc71f7254e7a1d2eb7cff3f56a6e23811047ac97356f1b18c8ac8b5",
+    "packages/artplayer-plugin-hls-control/README.md": "42bd00dca467b581f6b3e8399ad1a416d68edcc52d42e6cb51b66f1749694556",
+    "packages/artplayer-plugin-hls-control/types/artplayer-plugin-hls-control.d.ts": "7dd8fdf556932e9cf6140b7513c05155cad6d486e2484bf06c6d48f6e823832a",
+    "packages/artplayer-plugin-hls-control/src/index.js": "aa477db8743be2953a23776421edb68566d504c3278269eb13f6e907a4d5f2db",
+    "packages/artplayer-plugin-hls-control/src/audio.svg": "dbee5ce7487c9f8ec927e5286188cf9439345bbe947b6c06c32c07193e01e0be",
+    "packages/artplayer-plugin-hls-control/src/quality.svg": "4666a4c01764422f9008e442f5a889ff9691bb0386083d673943a0718f4d680c",
+    "docs/assets/example/hls.control.js": "b02fd290d79999790501447fad95736642344b9b30af3ccdbe353f80c7d53a6e"
+  },
+  "comparisons": [
+    {
+      "file": "package.json",
+      "publishedLF": "710ec2a27dc71f7254e7a1d2eb7cff3f56a6e23811047ac97356f1b18c8ac8b5",
+      "workspaceLF": "710ec2a27dc71f7254e7a1d2eb7cff3f56a6e23811047ac97356f1b18c8ac8b5",
+      "equal": true
+    },
+    {
+      "file": "README.md",
+      "publishedLF": "42bd00dca467b581f6b3e8399ad1a416d68edcc52d42e6cb51b66f1749694556",
+      "workspaceLF": "42bd00dca467b581f6b3e8399ad1a416d68edcc52d42e6cb51b66f1749694556",
+      "equal": true
+    },
+    {
+      "file": "types/artplayer-plugin-hls-control.d.ts",
+      "publishedLF": "7dd8fdf556932e9cf6140b7513c05155cad6d486e2484bf06c6d48f6e823832a",
+      "workspaceLF": "7dd8fdf556932e9cf6140b7513c05155cad6d486e2484bf06c6d48f6e823832a",
+      "equal": true
+    }
+  ],
+  "functionComparison": {
+    "sha256": "b22a09f4de5b56005c5122014624d76a91410e9517889d3e7b1c70b8efb2b554",
+    "typescript": "5.9.3",
+    "esbuild": "0.27.7",
+    "scope": [
+      "uniqBy",
+      "artplayerPluginHlsControl"
+    ],
+    "excludes": [
+      "SVG strings",
+      "bundler wrappers"
+    ],
+    "note": "Historical source at sourceCommit, not live migration source."
+  },
+  "provenanceNote": "Registry gitHead daf133b22630b4a0eecfa3336bbddab0e9119d96 has package version 1.0.2; it does not prove tarball source provenance."
+}