fix(core): [CORE-SUBTITLE-OFFSET-01] refresh paused native cue membership and order

2026-10-20 12:11:20 -08:00 · 2026-09-14 12:49:22 +08:00
1 parent b5dee252d4
commit efed847cdf
@@ -0,0 +1,75 @@
+# CORE-SUBTITLE-OFFSET-01: paused subtitle timing invalidation
+
+Baseline: b5dee252d461f91389c282a47401c5f8fd9a4483. Independent core correction
+discovered during PKG-MULTI-SUB-05; that package combination task remains doing.
+
+## Reproduction and implementation
+
+Firefox155 keeps cues in native activeCues after a paused offset changes their
+start/end outside currentTime. At paused time1.5, cues moved from1..3 to2..4
+still render. The old5.4.0 core and pre-change candidate both fail. A native
+HTMLVideoElement/TextTrack probe with no Artplayer instance reproduces the stale
+membership. Chromium153 and Windows WebKit26.6 have separate recorded observations.
+The first script-created-track probe did not become active on WebKit; the final
+probe uses a loaded HTML track matching the real integration, and records this
+fixture correction. Its initial overly precise seek assertion was corrected to
+require the actual1..2 interval; candidate offset tests separately compare each
+synchronous read against the pre-edit time.
+
+`subtitle/timing.ts` owns a small synchronous native invalidation step. After
+changing cue bounds, the existing offset mixin passes the native track, optional
+media capabilities and captured cue array. If paused and native membership/order
+differs from cue intervals at currentTime, remove and re-add the original cue
+objects in that order. Disabled tracks, playing media, missing capabilities and
+already-correct native state do not enter this path. No polling, timer, observer,
+new public option, UA sniffing, media seek or replacement cue is introduced.
+
+The first attempted mode-toggle correction fixed membership but reversed tied
+captions on a subsequent negative offset. That failing candidate report is retained;
+the final reinsertion implementation preserves order through1,-1,0,-3,0 offsets.
+Original cue bounds, identities, track mode and playback time remain. Update,
+notice and the public subtitleOffset event keep their existing synchronous order
+and values. Native cuechange/enter/exit notification can now reflect the corrected
+active membership, which is an intentional consequence of fixing stale activity.
+There is no new owned resource or disposal path.
+
+## Verification and scope
+
+Exact hashes, browser versions, logs, native state and artifact maps are recorded in
+[subtitle-offset-validation.json](../baselines/subtitle-offset-validation.json).
+
+- Five new controlled regressions join the existing subtitle suite: stale/missing
+  members, order drift, cue identity, update/event ordering, correct overlap,
+  disabled/playing/capability-limited hosts. The six-file core group passes58 tests.
+- Strict core and root consumer TS checks pass. Public generated declarations remain
+  unchanged:37 files checked,0 drift. Runtime helper types are internal only.
+- Expanded source browser run153:150 passing assertions,3 failures. Two failures
+  are old WebKit core5.3.0/5.4.0 source switching and remain task05 risks; the third
+  was the diagnostic seek precision assumption explained above. Candidate offset,
+  lifecycle and combination checks pass. The run includes explicitly labelled old
+  defects and must not be presented as153 successful compatibility acceptances.
+- Actual main build:15 passing cases comprise9 native probes,3 published behavior
+  observations and3 candidate offset regressions. Actual legacy build:3 candidate
+  offset cases pass. Candidate tests also cover disabled tracks and resumed play.
+- Three core formats and docs copies are rebuilt. The normal core build clears the
+  dist directory, so build:i18n regenerates all11 languages; those bytes remain
+  unchanged. Actual import/SSR/i18n distribution checks pass5 tests. CI regression
+  passes50 tests. Lint retains only its existing docs declaration warning.
+
+Published Firefox defects remain explicit in the offset and combination suites;
+only the candidate's assertion changes from failing to correct. The independent
+old-host overlap and WebKit source-switch issues are not waived or resolved here.
+No physical-device, full package, remote CI or publication acceptance is claimed.
+No dependency, lockfile, public declaration, version or package entrypoint change.
+
+## Maintenance and rollback
+
+Change timestamp invalidation in timing.ts and property bounds/notice behavior in
+player/subtitleOffsetMix.ts. Keep the native probe independent of player instances.
+Run node --test test/subtitle.test.js, strict core/root tsc, and the subtitle-offset,
+subtitle-lifecycle and multiple-subtitles-combinations browser suites. For actual
+artifact testing use the existing ARTPLAYER_BROWSER_ARTIFACTS map and include both
+core and chapter mappings, as required by the shared fixture server.
+
+Revert the dedicated task commit, including build outputs, to remove this correction.
+This is a local commit only, with no push or npm publication authorization.
@@ -2,9 +2,9 @@

 > 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`，不要手改本表。

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

-状态：todo 55 / doing 17 / blocked 0 / done 175 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 55 / doing 17 / blocked 0 / done 176 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -14,7 +14,7 @@

 | 包 | 基线版本 | 任务 |
 | --- | --- | --- |
-| artplayer | 5.4.1 | CORE-01, CORE-02, CORE-03, CORE-04, CORE-05, CORE-06, CORE-07, CORE-08, CORE-09, CORE-10, CORE-11, CORE-12, CORE-13, CORE-14, CORE-15, CORE-16, CORE-17, CORE-18, CORE-19, CORE-20, CORE-21, CORE-23, CORE-22, CORE-24, SITE-BUILD-01, CORE-25, ENG-12 |
+| artplayer | 5.4.1 | CORE-01, CORE-02, CORE-03, CORE-04, CORE-05, CORE-06, CORE-07, CORE-08, CORE-09, CORE-10, CORE-11, CORE-12, CORE-13, CORE-14, CORE-15, CORE-16, CORE-17, CORE-18, CORE-19, CORE-20, CORE-21, CORE-23, CORE-22, CORE-24, SITE-BUILD-01, CORE-25, ENG-12, CORE-SUBTITLE-OFFSET-01 |
 | artplayer-plugin-ads | 2.1.0 | PKG-ADS-01, PKG-ADS-02, PKG-ADS-03, PKG-ADS-04, PKG-ADS-05, PKG-ADS-06 |
 | artplayer-plugin-ambilight | 1.1.0 | PKG-AMBILIGHT-01, PKG-AMBILIGHT-02, PKG-AMBILIGHT-03, PKG-AMBILIGHT-04, PKG-AMBILIGHT-PROXY-01, PKG-AMBILIGHT-05, PKG-AMBILIGHT-06, PKG-FACTORY-01 |
 | artplayer-plugin-asr | 2.1.0 | PKG-ASR-01, PKG-ASR-02, PKG-ASR-03, PKG-ASR-04, PKG-ASR-05, PKG-ASR-06, PKG-ASR-07, PKG-ASR-08, PKG-ASR-09 |
@@ -133,6 +133,7 @@
 | CORE-22 | artplayer<br>核心阶段完整验收 | CORE-21, CORE-23, PILOT-01, ENG-08, ENG-10, ENG-11 | 核心与旧插件的可自动化完整回归、资源/性能及明确外部验证缺口 | 核心自动化和公开差异处置通过；真实环境缺口链接包集成/REL 门槛，阶段完成不代表可公开发布 | H | done |
 | CORE-24 | artplayer<br>修复连续切源的播放意图继承 | CORE-22, PKG-AUDIO-04 | 连续切源保留原播放意图，同时尊重显式暂停与最新来源，回归旧/新 audio | 真实暂停状态的受控测试、重入/取消/失败/销毁、三引擎和 main/legacy 产物验证通过；不恢复过期来源的公开副作用 | H | done |
 | CORE-25 | artplayer<br>修复无 navigator 环境读取默认选项 | CORE-22, ENG-12 | 安全读取默认语言并保留浏览器已有默认值；实际 Node 与发布产物正反例 | 记录旧发布版 ReferenceError；候选在无 navigator 时可读默认选项，浏览器语言和公开类型不回归；不以补全局对象隐藏错误 | M | done |
+| CORE-SUBTITLE-OFFSET-01 | artplayer<br>修复暂停偏移后的原生活动字幕刷新 | CORE-15, CORE-22 | 暂停字幕偏移的原生轨道一致性修复、兼容回归和维护说明 | 保持cue对象、顺序、媒体时间、模式和公开事件；真实浏览器正负偏移及生命周期通过，历史缺陷单列 | H | done |

 ## 5 包迁移：artplayer-plugin-chapter

@@ -228,7 +229,7 @@
 | PKG-MULTI-SUB-07 | artplayer-plugin-multiple-subtitles<br>修复字幕内嵌时间戳序列化 | PKG-MULTI-SUB-03 | 保留数字时间戳节点、修正无效 NaN 输出、明确旧/新字幕输出差异 | 旧九份实现可复现，候选有效内嵌时间戳及文字/CSS/原生字幕通过，公开工厂与选择接口不变 | H | done |
 | PKG-MULTI-SUB-08 | artplayer-plugin-multiple-subtitles<br>修复字幕实体解码与嵌套标签包装 | PKG-MULTI-SUB-04, PKG-MULTI-SUB-07 | 使用解析器既有实体表入口修复多余分号；保护字面文本并以兄弟节点包装标签，保留CSS钩子和时间戳 | 冻结旧实现复现、实体/双重编码/标签/选择重置回归、新旧核心真实字幕显示通过；vendor原文与来源校验不变，类型/分发兼容 | M | done |
 | PKG-MULTI-SUB-05 | artplayer-plugin-multiple-subtitles<br>验证新旧核心和组合 | PKG-MULTI-SUB-04, CORE-22, PKG-MULTI-SUB-07, PKG-MULTI-SUB-08 | 与核心字幕/偏移/全屏组合，旧名称调用不变 | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | doing |
-| 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 |
+| PKG-MULTI-SUB-06 | artplayer-plugin-multiple-subtitles<br>验证分发并同步文档 | PKG-MULTI-SUB-05, ENG-07, CORE-SUBTITLE-OFFSET-01 | multiple.subtitles.js、parser 来源许可及打包边界 | tarball 入口/资源、类型、8082 demo 和 README 一致，有回退记录 | H | todo |

 ## 5 包迁移：artplayer-plugin-jassub

@@ -645,3 +646,4 @@
 - PKG-AUTO-THUMB-09: [记录](changes/2026-09-14-PKG-AUTO-THUMB-09-alias.md) [记录](baselines/auto-thumbnail-alias-validation.json)
 - PKG-AUTO-THUMB-10: [记录](changes/2026-09-14-PKG-AUTO-THUMB-10-encoding.md) [记录](baselines/auto-thumbnail-encoding-validation.json)
 - ENG-LINT-01: [记录](changes/2026-09-14-ENG-LINT-01-manifest-order.md) [记录](baselines/manifest-lint-validation.json)
+- CORE-SUBTITLE-OFFSET-01: [记录](changes/2026-09-14-CORE-SUBTITLE-OFFSET-01-paused.md) [记录](baselines/subtitle-offset-validation.json)
@@ -1,5 +1,21 @@
 # 进度与证据

+## CORE-SUBTITLE-OFFSET-01 暂停字幕偏移修复完成
+
+原生video/track探针确认Firefox155暂停时cue时间更新后活动标记陈旧；候选核心
+增加独立timing模块，只在暂停且原生cue成员/顺序与当前时间不一致时，将原cue
+按原顺序移除并重新加入。保持对象、模式、媒体时间与update/notice/公开偏移事件。
+先前mode切换方案会逆转同时间字幕顺序，已弃用并保留失败证据。新增5项风险回归，
+核心定向58项、严格核心/消费者TS、37声明零漂移、导入5项及CI50项通过。
+扩展源码浏览器153项中150断言通过，旧WebKit两项切源失败保持open，另一个原生
+探针时间精度假设已修正。正式main15项（含原生和历史观察）、legacy3项全部通过，
+候选覆盖正负/恢复偏移、禁用轨道和恢复播放。lint仅1既有warning。三格式/docs
+重建，i18n经正常脚本重建且无差异；main gzip9增加109字节，无依赖、版本或公开
+声明改动。见[变更](changes/2026-09-14-CORE-SUBTITLE-OFFSET-01-paused.md)与
+[证据](baselines/subtitle-offset-validation.json)。248项：176 done、17 doing、55 todo。
+关闭候选偏移缺陷，旧核心的对应失败保留明确观察；这不完成PKG-MULTI-SUB-05。
+下一步继续旧核心双语显示适配和WebKit切源定位，再完成剩余包组合/分发门槛。
+
 ## PKG-MULTI-SUB-05 新旧核心组合检查点（未完成）

 任务08已独立提交675b095b2，提交审计175 done/171专属提交/4初始例外通过。
@@ -265,5 +265,5 @@
 | DEV-SERVOR-PORT-01 | resolved / 已复现 | Servor exits the entire dev process with status zero when the requested port is occupied | MOD-DEV-01 |
 | AUTO-THUMB-ENCODE-TIMEOUT-01 | resolved / 源码/产物事实 | Pending JPEG encoding has no bounded lifetime after frame readiness finishes | PKG-AUTO-THUMB-10 |
 | MULTI-SUB-MARKUP-01 | resolved / 已复现 | Semantic cue nodes receive HTML wrappers inside their annotation fields | PKG-MULTI-SUB-08 |
-| MULTI-SUB-OFFSET-01 | open / 已复现 | Paused Firefox subtitle offset leaves out-of-time native cues active and captions visible | PKG-MULTI-SUB-05 |
+| MULTI-SUB-OFFSET-01 | resolved / 已复现 | Paused Firefox subtitle offset leaves out-of-time native cues active and captions visible | PKG-MULTI-SUB-05, CORE-SUBTITLE-OFFSET-01 |
 | MULTI-SUB-SWITCH-01 | open / 待取证 | Intermittent WebKit core5.3.0 caption loss after selected-track source switch | PKG-MULTI-SUB-05 |
@@ -6001,24 +6001,35 @@
      "id": "MULTI-SUB-OFFSET-01",
      "title": "Paused Firefox subtitle offset leaves out-of-time native cues active and captions visible",
      "confirmation": "reproduced",
-      "workspaceState": "Two runs on Firefox155 with cores5.3.0/5.4.0/candidate: paused at1.5, subtitleOffset=1 changes start/end to2/4 but native activeCues and HTML still contain both captions after the assertion timeout. Candidate assertion remains failing. No production correction yet.",
+      "workspaceState": "Native Firefox155 probe confirms stale paused membership. Candidate reinserts original cue objects only when paused membership/order is inconsistent; mode toggling was rejected after tied-caption reversal. Real main and legacy pass current paused positive/negative/reset offsets, disabled tracks and resumed playback in all3 engines. Published cores remain immutable defect observations, and package task05 still owns old-host combination acceptance.",
      "compatibleResolution": "Reduce native timing invalidation and ensure offset updates render the correct active captions without seeking media or changing public timing and event contracts.",
      "closureCriteria": "Candidate paused positive/negative/reset offsets refresh correctly, transitions and lifecycle regressions pass; historical behavior and actual old-core compatibility are separately documented.",
-      "status": "open",
+      "status": "resolved",
      "owners": [
-        "PKG-MULTI-SUB-05"
+        "PKG-MULTI-SUB-05",
+        "CORE-SUBTITLE-OFFSET-01"
      ],
      "evidence": [
        "refactor/changes/2026-09-14-PKG-MULTI-SUB-05-combinations.md",
        "refactor/baselines/multiple-subtitles-combinations-validation.json",
-        "test/browser/multiple-subtitles-combinations.spec.js"
-      ]
+        "test/browser/multiple-subtitles-combinations.spec.js",
+        "refactor/changes/2026-09-14-CORE-SUBTITLE-OFFSET-01-paused.md",
+        "refactor/baselines/subtitle-offset-validation.json",
+        "test/browser/subtitle-offset-native.spec.js",
+        "test/browser/subtitle-offset.spec.js",
+        "test/subtitle.test.js"
+      ],
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-14-CORE-SUBTITLE-OFFSET-01-paused.md",
+        "refactor/baselines/subtitle-offset-validation.json"
+      ],
+      "resolutionRationale": "Candidate core fix passes focused native/public/rendered membership, identity/order/time/mode/event and lifecycle checks, with actual main/legacy evidence. Historical Firefox failures are separately asserted and documented; closing this candidate defect does not approve all old-core combinations."
    },
    {
      "id": "MULTI-SUB-SWITCH-01",
      "title": "Intermittent WebKit core5.3.0 caption loss after selected-track source switch",
      "confirmation": "unverified",
-      "workspaceState": "One Windows WebKit26.6 run lost Translation after switchUrl and seek1.5; diagnostic rerun passed without a production change. Root cause and reproducibility are unresolved; do not mark accepted or fixed.",
+      "workspaceState": "One Windows WebKit26.6 run lost Translation after switchUrl and seek1.5; diagnostic rerun passed without a production change. Root cause and reproducibility are unresolved; do not mark accepted or fixed. Expanded153 offset/lifecycle run again lost the selected caption after source switch on published5.3.0 and5.4.0 in WebKit, while candidate core passed. Root cause remains unclassified; the offset fix does not close this issue.",
      "compatibleResolution": "Inspect native track loading and source-switch ordering with deterministic state evidence; distinguish historical host failure from fixture ordering and candidate regression.",
      "closureCriteria": "Root cause classified with targeted evidence, any required fix validated, and changed candidate/old-core combination rerun without hiding the original failure.",
      "status": "open",
@@ -6028,7 +6039,9 @@
      "evidence": [
        "refactor/changes/2026-09-14-PKG-MULTI-SUB-05-combinations.md",
        "refactor/baselines/multiple-subtitles-combinations-validation.json",
-        "test/browser/multiple-subtitles-combinations.spec.js"
+        "test/browser/multiple-subtitles-combinations.spec.js",
+        "refactor/changes/2026-09-14-CORE-SUBTITLE-OFFSET-01-paused.md",
+        "refactor/baselines/subtitle-offset-validation.json"
      ]
    }
  ]
@@ -2429,7 +2429,8 @@
      ],
      "dependsOn": [
        "PKG-MULTI-SUB-05",
-        "ENG-07"
+        "ENG-07",
+        "CORE-SUBTITLE-OFFSET-01"
      ],
      "status": "todo",
      "risk": "H",
@@ -5136,6 +5137,26 @@
        "changes/2026-09-14-ENG-LINT-01-manifest-order.md",
        "baselines/manifest-lint-validation.json"
      ]
+    },
+    {
+      "id": "CORE-SUBTITLE-OFFSET-01",
+      "phase": "3-4 核心迁移",
+      "title": "修复暂停偏移后的原生活动字幕刷新",
+      "scope": [
+        "artplayer"
+      ],
+      "dependsOn": [
+        "CORE-15",
+        "CORE-22"
+      ],
+      "status": "done",
+      "risk": "H",
+      "deliverable": "暂停字幕偏移的原生轨道一致性修复、兼容回归和维护说明",
+      "acceptance": "保持cue对象、顺序、媒体时间、模式和公开事件；真实浏览器正负偏移及生命周期通过，历史缺陷单列",
+      "evidence": [
+        "changes/2026-09-14-CORE-SUBTITLE-OFFSET-01-paused.md",
+        "baselines/subtitle-offset-validation.json"
+      ]
    }
  ]
 }