refactor(jassub): [PKG-JASSUB-03] isolate registration and fix adapter cleanup

2026-10-24 06:31:20 -08:00 · 2026-09-14 01:12:03 +08:00
1 parent 944e2cc9d0
commit 38e7b37878
@@ -0,0 +1,46 @@
+# PKG-JASSUB-03 自有注册与清理职责
+
+入口仅保留惰性工厂，新增 registration.js 管理实例构造后的样式、宿主监听和
+失败回滚。仍在 registrar 调用时读取 art.video 再展开原 option；返回同步的
+原 vendor 实例，不复制 options、不包装公开 instance、不绑定或改写其 destroy。
+两文件职责明确，未建立额外通用框架。vendor JS、Worker/WASM、字体、声明未变。
+严格 TS/公开类型迁移继续由 04 处理；vendor 的实质修复在独立 07 中完成。
+
+## 修复及兼容边界
+
+只有 vendor 创建了 _canvasParent 时才设置原 z-index=20。用户自定义 canvas
+不再在 Worker 创建后因空 parent 抛错，canvas 节点仍归调用者，销毁后不删除它。
+宿主清理检查 vendor 已销毁状态，并在调用期间防同步重入；仍动态查找当前
+instance.destroy，所以用户包装该方法继续生效。正常销毁错误原样传播，
+内部 guard 在失败时复位，允许下次尝试；成功后本次注册不重复清理。
+
+构造成功后若样式或宿主订阅失败，分别尽力移除相同 callback 并销毁实例，
+始终抛原错误。off 自身失败不会阻止尝试释放实例；这种异常宿主可能保留已
+失效的 callback，不能宣称已强制清除所有外部状态。vendor 构造尚未返回实例
+时的遗留资源，以及 vendor 自己的 destroy 再次调用、跨父节点、旧 RVFC 和
+ratechange 问题继续保留在 07。JASSUB-DESTROY-01 因而仍 open。
+
+## 验证
+
+新增八项候选回归：自定义 canvas、直接再宿主销毁、ready 前销毁、同步重入、
+错误传播/重试、订阅失败的两个回滚边界、样式失败。相同断言先对未重建的旧
+工作区主产物运行，1 通过/7 失败；改造源码八项通过。历史 63 项失败/保护断言
+保持原期待，本包联合 128 项通过；候选公共行为七项通过。
+
+正常脚本构建 main/legacy/ESM 并生成 docs 副本，产物各 15 项公共行为和清理
+测试通过。原生浏览器以实际候选产物和真实 Worker/WASM/字体验证自定义 canvas、
+seek 后字幕、网页全屏、直接 instance.destroy 再 art.destroy(false)，并检查
+调用者 canvas 保留、Worker 只终止一次。运行选择、数量和指纹见
+[验证记录](../baselines/jassub-registration-validation.json)。自定义 canvas 矩阵
+显式使用 onDemandRender=false；不能据此关闭 WebKit 默认逐帧问题。默认逐帧
+模式另测 Chromium/Firefox 的 vendor 创建容器路径，仍保留原生验收边界。
+
+test:jassub 与 test:unit 加入候选注册测试。原生测试支持
+ARTPLAYER_JASSUB_ARTIFACT 指定实际 global 产物，ARTPLAYER_JASSUB_CUSTOM_CANVAS=true
+指定调用者 canvas，报告区分 npm 归档与候选文件。没有提供这些参数时仍是
+02 的真实发布基线；该套件不把 ESM 当普通 script 加载。
+
+定向 lint、原有来源/资产校验及计划/风险校验通过；没有新增依赖、
+锁变化或远端运行。本次关闭自定义 canvas 的 adapter 缺陷，其他实例、设备、
+字体许可与完整分发问题保持原任务门槛。回退 index/registration 并正常重建
+即可恢复原行为；不要直接编辑 dist。独立本地提交，不推送或发布。
@@ -4,7 +4,7 @@

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

-状态：todo 65 / doing 14 / blocked 0 / done 153 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 64 / doing 14 / blocked 0 / done 154 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -231,7 +231,7 @@
 | --- | --- | --- | --- | --- | --- | --- |
 | PKG-JASSUB-01 | artplayer-plugin-jassub<br>核对包契约与历史用法 | BASE-05 | 选项透传、result.instance、vendor 来源、worker/WASM/font 路径 | 源码/声明/README/demo/发布包差异已登记；公开形状和版本范围冻结；接续 VENDOR-04/05，核对 wrapper/worker/WASM/font 的独立来源与通知，保持资源路径和选项透传 | H | done |
 | PKG-JASSUB-02 | artplayer-plugin-jassub<br>建立特有行为与错误测试 | PKG-JASSUB-01, ENG-03, ENG-05 | ASS 字体、时钟/seek/倍率/resize、加载失败和销毁 | 旧版本行为可重跑，成功/失败/切源/销毁有必要断言 | H | done |
-| PKG-JASSUB-03 | artplayer-plugin-jassub<br>整理内部职责与资源 | PKG-JASSUB-02, CORE-15, CORE-16 | 仅整理自有 adapter/销毁；保留第三方文件及来源 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | todo |
+| PKG-JASSUB-03 | artplayer-plugin-jassub<br>整理内部职责与资源 | PKG-JASSUB-02, CORE-15, CORE-16 | 仅整理自有 adapter/销毁；保留第三方文件及来源 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | done |
 | PKG-JASSUB-04 | artplayer-plugin-jassub<br>迁移自有源码和公开类型 | PKG-JASSUB-03, ENG-04, ENG-06, CORE-07 | JASSUB option/instance 的兼容类型包装，vendor JS 例外记录 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | H | todo |
 | PKG-JASSUB-05 | artplayer-plugin-jassub<br>验证新旧核心和组合 | PKG-JASSUB-04, CORE-22, PKG-JASSUB-07 | 真实 worker/WASM 字幕渲染与全屏、旧核心测试 | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | todo |
 | PKG-JASSUB-06 | artplayer-plugin-jassub<br>验证分发并同步文档 | PKG-JASSUB-05, ENG-07 | jassub.js、外部资源路径、许可和离线失败记录；接续 VENDOR-04/05 完整组件/字体通知、LGPL 源码分发核对及六份未明确字体的分发处置 | tarball 入口/资源、类型、8082 demo 和 README 一致，有回退记录；来源身份已由01冻结，完整通知和未明确字体的发布处理必须闭环，不能以来源相同替代许可结论 | H | todo |
@@ -534,6 +534,7 @@
 - PKG-MULTI-SUB-07: [记录](baselines/multiple-subtitles-timestamps.json) [记录](changes/2026-09-13-PKG-MULTI-SUB-07-timestamps.md)
 - PKG-JASSUB-01: [记录](baselines/jassub-release.json) [记录](baselines/jassub-vendor.json) [记录](baselines/jassub-font-metadata.json) [记录](baselines/jassub-contract.md) [记录](baselines/jassub-contract-validation.json) [记录](changes/2026-09-13-PKG-JASSUB-01-baseline.md) [记录](baselines/jassub-provenance.json) [记录](baselines/jassub-provenance-validation.json) [记录](changes/2026-09-14-PKG-JASSUB-01-provenance.md)
 - PKG-JASSUB-02: [记录](changes/2026-09-14-PKG-JASSUB-02-failure-baseline.md) [记录](baselines/jassub-failures-validation.json)
+- PKG-JASSUB-03: [记录](changes/2026-09-14-PKG-JASSUB-03-registration.md) [记录](baselines/jassub-registration-validation.json)
 - PKG-MASK-01: [记录](baselines/danmuku-mask-release.json) [记录](baselines/danmuku-mask-registry.json) [记录](baselines/danmuku-mask-contract.md) [记录](baselines/danmuku-mask-contract-validation.json) [记录](changes/2026-09-13-PKG-MASK-01-contract.md)
 - PKG-MASK-02: [记录](changes/2026-09-13-PKG-MASK-02-failures.md) [记录](baselines/danmuku-mask-failures-validation.json)
 - PKG-MASK-03: [记录](changes/2026-09-13-PKG-MASK-03-lifecycle.md) [记录](baselines/danmuku-mask-lifecycle-validation.json)
@@ -1,5 +1,14 @@
 # 进度与证据

+## PKG-JASSUB-03 自有注册/清理改造完成
+
+入口与 registration 分离；自定义 canvas、直接实例销毁后的宿主清理、重入与
+注册异常回滚已修复。旧产物同断言 1 通过/7 失败，候选八项通过；联合 128 项、
+main/legacy 各 15 项和实际浏览器 24 项通过，三格式正常构建。
+[实现记录](changes/2026-09-14-PKG-JASSUB-03-registration.md)说明 onDemand=false 的
+自定义 canvas 验证边界；WebKit 默认逐帧和 vendor 其他问题仍在 07/05。04 接着
+完成自有 TS 和公开类型，vendor/资源/声明本次未变；每项单独本地提交。
+
 ## PKG-JASSUB-02 历史缺陷与原生渲染基线完成

 联合 120 项通过，其中 63 项确认旧失败/已有保护；没有宣称修复。Chromium/Firefox
@@ -243,7 +243,7 @@
 | DANMUKU-SAMPLING-01 | resolved / 已复现 | Serial asynchronous placement stops native frame eligibility sampling and delays existing visible expiry | PKG-DANMUKU-12 |
 | MASK-SCHEDULING-01 | open / 已复现 | Native Mask startup can coincide with a missed narrow Danmuku timestamp window | PKG-MASK-05 |
 | JASSUB-DESTROY-01 | open / 已复现 | Repeated destruction or cross-parent setVideo can throw before JASSUB cleanup | PKG-JASSUB-02, PKG-JASSUB-03, PKG-JASSUB-07 |
-| JASSUB-CANVAS-01 | open / 已复现 | Custom canvas registration throws after JASSUB Worker allocation | PKG-JASSUB-02, PKG-JASSUB-03 |
+| JASSUB-CANVAS-01 | resolved / 已复现 | Custom canvas registration throws after JASSUB Worker allocation | PKG-JASSUB-02, PKG-JASSUB-03 |
 | JASSUB-CONSTRUCTION-01 | open / 已复现 | Worker construction failure leaves previously allocated JASSUB DOM and listeners | PKG-JASSUB-02, PKG-JASSUB-07 |
 | JASSUB-VIDEO-FRAME-01 | open / 已复现 | Old video frame callbacks can drive replacement subtitle time and duplicate chains | PKG-JASSUB-02, PKG-JASSUB-07 |
 | JASSUB-RATE-01 | open / 已复现 | Fallback ratechange sends an Event instead of numeric playbackRate | PKG-JASSUB-02, PKG-JASSUB-07 |
@@ -5438,26 +5438,38 @@
      ],
      "evidence": [
        "refactor/changes/2026-09-14-PKG-JASSUB-02-failure-baseline.md",
-        "refactor/baselines/jassub-failures-validation.json"
+        "refactor/baselines/jassub-failures-validation.json",
+        "refactor/changes/2026-09-14-PKG-JASSUB-03-registration.md",
+        "refactor/baselines/jassub-registration-validation.json",
+        "test/jassub-registration.test.js"
      ],
-      "compatibleResolution": "Use actual resource ownership and tolerate direct instance teardown before host teardown.",
+      "compatibleResolution": "Use actual resource ownership and tolerate direct instance teardown before host teardown. Task03 fixes host cleanup after direct teardown, reentry and retry/rollback. Direct vendor repetition and cross-parent cleanup remain task07 and this risk stays open.",
      "closureCriteria": "Candidate direct/repeated/host teardown and cross-parent video replacement release container, Worker and listeners without throwing or removing user nodes."
    },
    {
      "id": "JASSUB-CANVAS-01",
      "title": "Custom canvas registration throws after JASSUB Worker allocation",
      "confirmation": "reproduced",
-      "status": "open",
+      "status": "resolved",
      "owners": [
        "PKG-JASSUB-02",
        "PKG-JASSUB-03"
      ],
      "evidence": [
        "refactor/changes/2026-09-14-PKG-JASSUB-02-failure-baseline.md",
-        "refactor/baselines/jassub-failures-validation.json"
+        "refactor/baselines/jassub-failures-validation.json",
+        "refactor/changes/2026-09-14-PKG-JASSUB-03-registration.md",
+        "refactor/baselines/jassub-registration-validation.json",
+        "test/jassub-registration.test.js"
      ],
      "compatibleResolution": "Guard adapter-created parent styling; retain the supplied canvas and roll back failed registration.",
-      "closureCriteria": "Custom canvas registration succeeds and cleanup releases owned work while preserving caller DOM; public instance and option override behavior remain compatible."
+      "closureCriteria": "Custom canvas registration succeeds and cleanup releases owned work while preserving caller DOM; public instance and option override behavior remain compatible.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-14-PKG-JASSUB-03-registration.md",
+        "refactor/baselines/jassub-registration-validation.json",
+        "test/jassub-registration.test.js"
+      ],
+      "resolutionRationale": "Adapter no longer assumes a vendor-created parent for caller canvas. Old-artifact red tests and candidate rollback/ownership tests distinguish the fix. Actual main/legacy native Worker/WASM rendering, seek/fullscreen and direct-then-host cleanup pass with caller nodes preserved across three engines and three cores using explicit event-clock mode. Default WebKit frame delivery is a separate open risk."
    },
    {
      "id": "JASSUB-CONSTRUCTION-01",
@@ -2455,11 +2455,14 @@
        "CORE-15",
        "CORE-16"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "H",
      "deliverable": "仅整理自有 adapter/销毁；保留第三方文件及来源",
      "acceptance": "结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-14-PKG-JASSUB-03-registration.md",
+        "baselines/jassub-registration-validation.json"
+      ]
    },
    {
      "id": "PKG-JASSUB-04",