mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-22 05:11:20 -08:00
refactor(multiple-subtitles): [PKG-MULTI-SUB-04] type runtime modules and vendor boundaries
This commit is contained in:
Harvey Zhao committed
1 parent
beaa93d6cc
commit
da64aae267
28 files changed
+7075
-86
No files matched your search
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,45 @@
|
||||
# PKG-MULTI-SUB-04 严格运行时 TS 检查点
|
||||
|
||||
五个自有 JS 模块迁为 TS，新增 types.ts 描述真实 Promise<Result>、轨道、生命周期、
|
||||
converter 和宿主安装边界。parser.js 原始 vendor 执行体保持；parser.d.ts 区分文本、
|
||||
标签和数字时间戳节点，描述 cue settings、错误/样式结果及序列化输入。
|
||||
分包 tsconfig 使用 strict/noUncheckedIndexedAccess/allowJs=false，既有浏览器目标不变。
|
||||
|
||||
## 兼容与断言
|
||||
|
||||
- 内部 TrackOption 复用旧公开配置字段，内部 Option 允许运行时已有的 `{}`；工厂参数
|
||||
本身仍必需。真实返回 Promise，tracks/reset 明确 void。
|
||||
- 公开 types、导出路径和版本尚未改动。旧同步声明与真实异步结果的冲突保留为编译负例；
|
||||
04 未完成，后续必须验证旧提取/替换、模块形式及安装消费者再处理公开入口。
|
||||
- `(art.constructor as typeof Artplayer)` 只恢复构造器静态类型；可选 URL 的 `!` 保留
|
||||
原生 fetch 的旧值转换，不偷偷加默认 URL；关闭状态检查后的 `!`/string[] 对应取消边界。
|
||||
- Promise.all 索引与选项索引配对。未知名称仍在 cue 属性读取时抛 TypeError，不能因
|
||||
类型严格化过滤掉无效项。宿主默认 subtitle 的断言也不新增运行时默认。
|
||||
- parseTracks 返回拥有 url/name 的明确新对象，其 cues/errors/styles 保持相同引用；
|
||||
没有改变 cue 输出、选择顺序和生命周期策略。
|
||||
|
||||
## 类型检查发现的独立缺陷
|
||||
|
||||
旧包装逻辑把所有顶层节点的 value 都改成 div 字符串，包括应该保留数字的时间戳。
|
||||
实际已发布 1.2.0 和本次候选对 `Before <00:02.000> after` 都输出 `<NaN:NaN.NaN>`。
|
||||
九份历史输入新增复现，全部确认同一缺陷；原有 02 验证是当时 162 项，本次历史失败
|
||||
文件扩为 171 项，不改写旧报告数字。实际探针输入/输出写入本次验证记录。
|
||||
|
||||
新增 PKG-MULTI-SUB-07 专门修复并验证内嵌时间戳的序列化，作为 05 的前置；风险保持
|
||||
open。本次 WrappedNode 明确表达这个历史错误，不把类型通过解释为字幕内容已正确。
|
||||
下一步先处理 07，再继续 04 的公开声明；修复需同时更新旧/新差异和原生显示证据。
|
||||
|
||||
## 验证与发布边界
|
||||
|
||||
TS 5.9.3/5.1.6 严格正例通过，移除 expect-error 后各 8 个错误；注册返回、选择名称、
|
||||
格式、只读关闭状态、数字时间戳、序列化返回和旧同步替换均有明确约束。
|
||||
源码/main/legacy 的既有 31 项正常/资源/转换测试分别重跑；三入口原生五场景各 30 项。
|
||||
vendor 没有机械 TS 改写，不计为已迁移生产 TS。实际结果与限制见
|
||||
[验证记录](../baselines/multiple-subtitles-runtime-types.json)。
|
||||
|
||||
正常构建更新三份 dist 及 docs/compiled。新增 tsconfig 加入 .npmignore，并用实际
|
||||
yarn pack 验证自有源码、私有 parser 声明和 tsconfig 未泄漏；公开声明/入口原样保留。
|
||||
最终本包 252 项、完整 CI 2322 项通过（1972 单元、14 工程、336 基线），严格生产
|
||||
TS 增至 352 文件。三入口各 31 项及原生共 90 项通过，状态更新后另有 9 项元数据
|
||||
检查通过。新增源文件/声明/fixture/runner 显式 lint 通过；全量 lint 保留既有生成声明警告。
|
||||
无新依赖，未推送或发布。本次为 04 的独立本地检查点提交，任务继续 doing。
|
||||
+7
-5
@@ -2,9 +2,9 @@
|
||||
|
||||
> 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`，不要手改本表。
|
||||
|
||||
基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 222 项，范围 22 个包及工作区/示例。
|
||||
基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 223 项，范围 22 个包及工作区/示例。
|
||||
|
||||
状态：todo 89 / doing 13 / blocked 0 / done 120 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
|
||||
状态：todo 89 / doing 14 / blocked 0 / done 120 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
|
||||
|
||||
前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。
|
||||
|
||||
@@ -28,7 +28,7 @@
|
||||
| artplayer-plugin-document-pip | 1.1.0 | PKG-DPIP-01, PKG-DPIP-02, PKG-DPIP-03, PKG-DPIP-04, PKG-DPIP-05, PKG-DPIP-06 |
|
||||
| artplayer-plugin-hls-control | 1.1.0 | PKG-HLS-01, PKG-HLS-02, PKG-HLS-03, PKG-HLS-04, PKG-HLS-SDK-01, PKG-HLS-05, PKG-HLS-06 |
|
||||
| artplayer-plugin-jassub | 1.1.0 | PKG-JASSUB-01, PKG-JASSUB-02, PKG-JASSUB-03, PKG-JASSUB-04, PKG-JASSUB-05, PKG-JASSUB-06 |
|
||||
| artplayer-plugin-multiple-subtitles | 1.2.0 | PKG-MULTI-SUB-01, PKG-MULTI-SUB-02, PKG-MULTI-SUB-03, PKG-MULTI-SUB-04, PKG-MULTI-SUB-05, PKG-MULTI-SUB-06 |
|
||||
| artplayer-plugin-multiple-subtitles | 1.2.0 | PKG-MULTI-SUB-01, PKG-MULTI-SUB-02, PKG-MULTI-SUB-03, PKG-MULTI-SUB-04, PKG-MULTI-SUB-07, PKG-MULTI-SUB-05, PKG-MULTI-SUB-06 |
|
||||
| artplayer-plugin-vast | 1.2.0 | PKG-VAST-01, PKG-VAST-02, PKG-VAST-03, PKG-VAST-04, PKG-VAST-05, PKG-VAST-06 |
|
||||
| artplayer-plugin-vtt-thumbnail | 1.1.0 | PKG-VTT-THUMB-01, PKG-VTT-THUMB-02, PKG-VTT-THUMB-03, PKG-VTT-THUMB-04, PKG-VTT-THUMB-05, PKG-VTT-THUMB-06 |
|
||||
| artplayer-proxy-canvas | 1.1.0 | PKG-AMBILIGHT-PROXY-01, PKG-CANVAS-01, PKG-CANVAS-02, PKG-CANVAS-03, PKG-CANVAS-04, PKG-CANVAS-05, PKG-CANVAS-06, PKG-FACTORY-01 |
|
||||
@@ -219,8 +219,9 @@
|
||||
| PKG-MULTI-SUB-01 | artplayer-plugin-multiple-subtitles<br>核对包契约与历史用法 | BASE-05 | subtitles/onParser、multipleSubtitles 名称及实际返回方法 | 源码/声明/README/demo/发布包差异已登记；公开形状和版本范围冻结；接续 VENDOR-03，定位 WebVTT parser 来源/修订及 CC0 头，保留解析/序列化行为 | H | done |
|
||||
| PKG-MULTI-SUB-02 | artplayer-plugin-multiple-subtitles<br>建立特有行为与错误测试 | PKG-MULTI-SUB-01, ENG-03, ENG-05 | VTT/SRT/ASS、编码/重叠 cue/排序/空轨/失败与切换 | 旧版本行为可重跑，成功/失败/切源/销毁有必要断言 | H | done |
|
||||
| PKG-MULTI-SUB-03 | artplayer-plugin-multiple-subtitles<br>整理内部职责与资源 | PKG-MULTI-SUB-02, CORE-15 | 解析与合并/获取/渲染分离，过期请求及对象 URL 清理 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | done |
|
||||
| PKG-MULTI-SUB-04 | artplayer-plugin-multiple-subtitles<br>迁移自有源码和公开类型 | PKG-MULTI-SUB-03, ENG-04, ENG-06, CORE-07 | 准确 parser/cue/tree/result 类型与真实异步形状 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | H | todo |
|
||||
| PKG-MULTI-SUB-05 | artplayer-plugin-multiple-subtitles<br>验证新旧核心和组合 | PKG-MULTI-SUB-04, CORE-22 | 与核心字幕/偏移/全屏组合，旧名称调用不变 | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | todo |
|
||||
| PKG-MULTI-SUB-04 | artplayer-plugin-multiple-subtitles<br>迁移自有源码和公开类型 | PKG-MULTI-SUB-03, ENG-04, ENG-06, CORE-07 | 准确 parser/cue/tree/result 类型与真实异步形状 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | H | doing |
|
||||
| PKG-MULTI-SUB-07 | artplayer-plugin-multiple-subtitles<br>修复字幕内嵌时间戳序列化 | PKG-MULTI-SUB-03 | 保留数字时间戳节点、修正无效 NaN 输出、明确旧/新字幕输出差异 | 旧九份实现可复现，候选有效内嵌时间戳及文字/CSS/原生字幕通过，公开工厂与选择接口不变 | H | todo |
|
||||
| PKG-MULTI-SUB-05 | artplayer-plugin-multiple-subtitles<br>验证新旧核心和组合 | PKG-MULTI-SUB-04, CORE-22, PKG-MULTI-SUB-07 | 与核心字幕/偏移/全屏组合，旧名称调用不变 | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | todo |
|
||||
| PKG-MULTI-SUB-06 | artplayer-plugin-multiple-subtitles<br>验证分发并同步文档 | PKG-MULTI-SUB-05, ENG-07 | multiple.subtitles.js、parser 来源许可及打包边界 | tarball 入口/资源、类型、8082 demo 和 README 一致，有回退记录 | H | todo |
|
||||
|
||||
## 5 包迁移：artplayer-plugin-jassub
|
||||
@@ -514,6 +515,7 @@
|
||||
- PKG-MULTI-SUB-01: [记录](baselines/multiple-subtitles-release.json) [记录](baselines/multiple-subtitles-contract.md) [记录](baselines/multiple-subtitles-contract-validation.json) [记录](changes/2026-09-13-PKG-MULTI-SUB-01-contract.md)
|
||||
- PKG-MULTI-SUB-02: [记录](baselines/multiple-subtitles-failures.json) [记录](changes/2026-09-13-PKG-MULTI-SUB-02-failures.md)
|
||||
- PKG-MULTI-SUB-03: [记录](baselines/multiple-subtitles-resources.json) [记录](changes/2026-09-13-PKG-MULTI-SUB-03-resources.md)
|
||||
- PKG-MULTI-SUB-04: [记录](baselines/multiple-subtitles-runtime-types.json) [记录](changes/2026-09-13-PKG-MULTI-SUB-04-runtime-types.md)
|
||||
- PKG-ADS-01: [记录](baselines/ads-release.json) [记录](baselines/ads-contract.md) [记录](baselines/ads-contract-validation.json) [记录](changes/2026-09-12-PKG-ADS-01-contract.md) [记录](scripts/ads-contract.test.mjs)
|
||||
- PKG-ADS-02: [记录](changes/2026-09-12-PKG-ADS-02-tests.md) [记录](ads-validation.md) [记录](baselines/ads-validation.json)
|
||||
- PKG-ADS-03: [记录](changes/2026-09-12-PKG-ADS-03-lifecycle.md) [记录](ads-validation.md) [记录](baselines/ads-lifecycle-validation.json)
|
||||
|
||||
@@ -1,5 +1,20 @@
|
||||
# 进度与证据
|
||||
|
||||
## PKG-MULTI-SUB-04 严格运行时 TS 检查点（doing）
|
||||
|
||||
五个自有模块迁为 TS，新增明确的 Option/Promise Result/Track/host/lifetime 类型；
|
||||
parser.js 保持原 vendor，私有 parser.d.ts 区分 cue 与节点，分包 allowJs=false。
|
||||
TS 5.9.3/5.1.6 严格正例通过，移除标记后各 8 个负例准确报错；公开旧声明未改。
|
||||
源码/main/legacy 各 31 项通过，三入口原生各 30 项共 90 项通过；实际构建/ESM 导入通过。
|
||||
实际 yarn pack 检查入口、成员及产物字节，私有源码、parser 声明和 tsconfig 未泄漏。
|
||||
本包 252 项通过，完整 CI 2322 项通过（1972 单元、14 工程、336 基线），
|
||||
严格生产 TS 增至 352 文件。见[检查点](changes/2026-09-13-PKG-MULTI-SUB-04-runtime-types.md)
|
||||
和[验证](baselines/multiple-subtitles-runtime-types.json)。公开异步/旧类型及安装消费者仍待 04。
|
||||
类型梳理复现旧/候选内嵌时间戳输出 NaN；九份历史实现均复现，新建 TIMESTAMP 风险与
|
||||
PKG-MULTI-SUB-07，并将 07 加入 05 前置。此问题未修复，下一步先做 07，再继续公开类型。
|
||||
223 项：120 done、14 doing、89 todo；197 项风险。独立本地检查点提交，不推送、不发布。
|
||||
|
||||
|
||||
## PKG-MULTI-SUB-03 模块与资源修复完成
|
||||
|
||||
生产源码拆为入口、请求、纯解析合并、生命周期和宿主安装五个模块，vendor parser 不变。
|
||||
|
||||
@@ -200,3 +200,4 @@
|
||||
| MULTI-SUB-EXPORT-01 | open / 已复现 | Older CommonJS default objects conflict with export-assignment declarations; latest exports a direct factory | PKG-MULTI-SUB-04, PKG-MULTI-SUB-06 |
|
||||
| MULTI-SUB-HTTP-01 | resolved / 已复现 | HTTP error responses with parseable bodies are installed as subtitles | PKG-MULTI-SUB-03, PKG-MULTI-SUB-05 |
|
||||
| MULTI-SUB-HOST-01 | resolved / 已复现 | Subtitle init rejections are ignored and failed installation or URL replacement leaks or invalidates resources | PKG-MULTI-SUB-03, PKG-MULTI-SUB-05 |
|
||||
| MULTI-SUB-TIMESTAMP-01 | open / 已复现 | Text wrappers replace numeric inline cue timestamps and serialize NaN times | PKG-MULTI-SUB-07, PKG-MULTI-SUB-05 |
|
||||
@@ -4398,6 +4398,23 @@
|
||||
"test/browser/multiple-subtitles-lifecycle.spec.js"
|
||||
],
|
||||
"resolutionRationale": "Owned installations retain prior URLs on synchronous failure, observe async rejections, release the failed active URL without affecting newer installs, and clean up on destroy. Controlled sync/async/reentrant/getter failures and native Blob revocation pass; void methods and registration timing are preserved."
|
||||
},
|
||||
{
|
||||
"id": "MULTI-SUB-TIMESTAMP-01",
|
||||
"title": "Text wrappers replace numeric inline cue timestamps and serialize NaN times",
|
||||
"confirmation": "reproduced",
|
||||
"status": "open",
|
||||
"owners": [
|
||||
"PKG-MULTI-SUB-07",
|
||||
"PKG-MULTI-SUB-05"
|
||||
],
|
||||
"evidence": [
|
||||
"refactor/baselines/multiple-subtitles-runtime-types.json",
|
||||
"refactor/changes/2026-09-13-PKG-MULTI-SUB-04-runtime-types.md",
|
||||
"test/multiple-subtitles-failures.test.js"
|
||||
],
|
||||
"compatibleResolution": "Preserve numeric timestamp nodes while retaining subtitle text, track wrappers and selection contracts; record the intentional repair of invalid legacy output.",
|
||||
"closureCriteria": "Valid inline timestamps and surrounding text survive serialization and native subtitle playback; frozen historical failure remains reproducible and ordinary markup regressions pass."
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
import assert from 'node:assert/strict'
|
||||
import fs from 'node:fs'
|
||||
import path from 'node:path'
|
||||
// eslint-disable-next-line test/no-import-node-test -- Internal runtime compiler checks use the repository runner.
|
||||
import test from 'node:test'
|
||||
import ts from 'typescript'
|
||||
import runtimeCompat from 'typescript-runtime-compat'
|
||||
|
||||
for (const compiler of [ts, runtimeCompat]) {
|
||||
test(`Multiple subtitles strict runtime modules and negative consumers: TS ${compiler.version}`, () => {
|
||||
const file = path.resolve('packages/artplayer-plugin-multiple-subtitles/tsconfig.json')
|
||||
const config = compiler.readConfigFile(file, compiler.sys.readFile)
|
||||
assert.equal(config.error, undefined)
|
||||
const parsed = compiler.parseJsonConfigFileContent(config.config, compiler.sys, path.dirname(file))
|
||||
assert.equal(parsed.options.strict, true)
|
||||
assert.equal(parsed.options.allowJs, false)
|
||||
assert.equal(parsed.options.skipLibCheck, false)
|
||||
assert.equal(parsed.options.noEmit, true)
|
||||
assert.deepEqual(parsed.options.types, [])
|
||||
const fixture = path.resolve('test/types/multiple-subtitles-runtime.ts')
|
||||
assert(parsed.fileNames.some(file => path.resolve(file) === fixture))
|
||||
function diagnostics(negative) {
|
||||
const host = compiler.createCompilerHost(parsed.options)
|
||||
const read = host.readFile.bind(host)
|
||||
host.readFile = file => path.resolve(file) === fixture && negative
|
||||
? fs.readFileSync(fixture, 'utf8').replaceAll(/\/\/ @ts-expect-error[^\n]*\n/g, '')
|
||||
: read(file)
|
||||
const program = compiler.createProgram(parsed.fileNames, parsed.options, host)
|
||||
assert(program.getSourceFile(fixture))
|
||||
assert(!program.getSourceFiles().some(file => /multiple-subtitles\/src\/.*\.js$/.test(file.fileName.replaceAll('\\', '/'))), 'Vendored JS must be represented by its explicit declaration')
|
||||
return compiler.getPreEmitDiagnostics(program).map(error => ({ code: error.code, text: compiler.flattenDiagnosticMessageText(error.messageText, '\n') }))
|
||||
}
|
||||
assert.deepEqual(diagnostics(false), [])
|
||||
const rejected = diagnostics(true)
|
||||
assert.equal(rejected.length, 8, JSON.stringify(rejected))
|
||||
})
|
||||
}
|
||||
+22
-2
@@ -2319,10 +2319,29 @@
|
||||
"ENG-06",
|
||||
"CORE-07"
|
||||
],
|
||||
"status": "todo",
|
||||
"status": "doing",
|
||||
"risk": "H",
|
||||
"deliverable": "准确 parser/cue/tree/result 类型与真实异步形状",
|
||||
"acceptance": "严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容",
|
||||
"evidence": [
|
||||
"baselines/multiple-subtitles-runtime-types.json",
|
||||
"changes/2026-09-13-PKG-MULTI-SUB-04-runtime-types.md"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "PKG-MULTI-SUB-07",
|
||||
"phase": "5 包迁移：artplayer-plugin-multiple-subtitles",
|
||||
"title": "修复字幕内嵌时间戳序列化",
|
||||
"scope": [
|
||||
"artplayer-plugin-multiple-subtitles"
|
||||
],
|
||||
"dependsOn": [
|
||||
"PKG-MULTI-SUB-03"
|
||||
],
|
||||
"status": "todo",
|
||||
"risk": "H",
|
||||
"deliverable": "保留数字时间戳节点、修正无效 NaN 输出、明确旧/新字幕输出差异",
|
||||
"acceptance": "旧九份实现可复现，候选有效内嵌时间戳及文字/CSS/原生字幕通过，公开工厂与选择接口不变",
|
||||
"evidence": []
|
||||
},
|
||||
{
|
||||
@@ -2334,7 +2353,8 @@
|
||||
],
|
||||
"dependsOn": [
|
||||
"PKG-MULTI-SUB-04",
|
||||
"CORE-22"
|
||||
"CORE-22",
|
||||
"PKG-MULTI-SUB-07"
|
||||
],
|
||||
"status": "todo",
|
||||
"risk": "H",
|
||||
|
||||
Reference in new issue
Block a user