fix(iframe): [PKG-IFRAME-03] own pending requests and cancellation

2026-10-19 03:11:20 -08:00 · 2026-09-12 23:41:48 +08:00
1 parent b3f22652c2
commit b8d03e7366
@@ -0,0 +1,82 @@
+# PKG-IFRAME-03 request ownership checkpoint (doing)
+
+The old single JS file is now a strict TS public entry plus a request ownership
+module. Entry methods and fields remain in place; the private WeakMap does not
+add reflective instance keys. Source types are checked by a new package tsconfig,
+without changing published declarations or installing dependencies. Package
+ARCHITECTURE.md explains state, ownership, compatibility and follow-up work.
+
+## Corrections and compatibility
+
+| Boundary | Previous result | Candidate result |
+| --- | --- | --- |
+| Same millisecond / clock rollback | Callbacks overwrite each other or old IDs recur | Module-wide increasing numeric IDs preserve independent responses |
+| Multiple instances, one frame | Each instance can settle from the same response ID | Instances from the same module allocate distinct IDs |
+| Destroy sent/waiting request | Sent promise hangs; waiting poll remains until its next tick | Immediate rejection with the existing destroyed Error message, timers/registry released |
+| Saved callback after destroy | Can settle or notify | Inert |
+| Native send failure | Immediate rejection leaks record; delayed failure escapes callback | Same original error rejects in both paths, all owned state removed |
+| Public resove/reject | Promise settles but its registry entry remains | Promise and corresponding owned registry entry released once |
+| Inherited response ID | `toString` can be mistaken for a request and throws | Only own registry entries participate, generic message callback still runs |
+
+These are deliberate fixes under API-02/03/04/05/12, not a new wire format.
+Constructor validation, seven field descriptors/order, bound onMessage, callback
+receiver/packet shape, numeric envelopes, `resove`, ordinary registry identity,
+wildcard target origin, 200ms polling, generic non-error responses, function-body
+commit serialization, child sync/resolve timing and child error channel remain.
+An ID is now a correlation number rather than an exact clock reading. Callers
+must handle pending request rejection on destroy; old promises hung indefinitely.
+No automatic timeout, new public option, SDK or version change is introduced.
+
+The counter is local to a library module; separately evaluated copies are not
+coordinated. Source typing uses `any` only for the existing arbitrary message
+payload/callback/result boundary; ownership and state are explicit. The child
+error `.message` assertion intentionally retains the old error serialization,
+including its existing behavior for unusual thrown values. The contentWindow
+assertion does not add an availability guarantee: a null window throws inside the
+send boundary and rejects the request rather than leaving it owned.
+
+## Validation
+
+The same 16 candidate Node assertions against the frozen workspace pass 5 and
+fail 11; candidate source passes all 16. The unchanged candidate browser checks
+against that old artifact pass 2 round trips and fail 8 lifecycle cases across
+same/cross-origin Chromium. Full failure reports/results/traces are archived in
+`refactor/.cache/iframe03-before-results`; Node log is `iframe03-before-node.log`.
+This contrasts candidate acceptance with the separate historical defect assertions.
+
+During the independent diff review, the new own-property guard was found to
+throw for consumer-cleared `promises[id] = undefined`, whereas the old workspace
+ignored it. `iframe03-empty-record-before.log` records that old/current contrast.
+The guard now retains the old truthiness check as well; the existing regression
+case covers this edge. Earlier passing CI/browser records predate this fix and
+remain archived; final candidate builds and checks are rerun against the new bytes.
+
+Final production/browser/CI results and hashes are recorded in the checkpoint
+validation file after execution. No player is created by these iframe-only
+fixtures; they do not establish full demo/core/media integration.
+
+## Remaining work and rollback
+
+PKG-IFRAME-03 remains doing. Navigation/reinjection, malformed packets, constructor
+setup failure cleanup and the independent source/origin policy still need work.
+IFRAME-LIFE-01, IFRAME-TRUST-01 and IFRAME-DIST-01 remain open. Trust policy has not
+silently changed; current foreign-message behavior is still a known defect.
+PKG-IFRAME-04 owns declaration/helper/old-name compatibility and 05/06 own complete
+integration/distribution. This checkpoint is not release acceptance.
+
+Rollback by reverting this checkpoint and rebuilding `artplayer-tool-iframe`
+through the normal script. The frozen artifacts and previous evidence remain
+immutable. Commit subject: `fix(iframe): [PKG-IFRAME-03] own pending requests and cancellation`.
+
+Final source/main/legacy Node checks each pass 16. Final main browser matrix
+passes 174 (144 historical defect assertions + 30 candidate acceptance), and
+final legacy passes 30 candidate rows. All three engines execute real windows;
+there are no skips/capability substitutes. CI passes 1505 (1331 unit + 14
+engineering + 160 baseline), 44 repeated contracts and 326 production TS files;
+3 import/SSR files pass after the final rebuild. All hashes match archived
+reports and the final source/artifacts; docs copies are byte-identical.
+
+One normal build attempt failed copying the legacy file into docs with Windows
+copyfile UNKNOWN; the cause is not established. The failure log is retained,
+and a normal build rerun succeeded before final checks. No manual artifact edit
+or ignored build failure was used. Status stays doing and all three risks open.
@@ -4,7 +4,7 @@

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

-状态：todo 106 / doing 9 / blocked 0 / done 107 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 105 / doing 10 / blocked 0 / done 107 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

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

@@ -346,7 +346,7 @@
 | --- | --- | --- | --- | --- | --- | --- |
 | PKG-IFRAME-01 | artplayer-tool-iframe<br>核对包契约与历史用法 | BASE-05 | constructor/commit/message/inject、postMessage 协议与历史公开拼写 | 源码/声明/README/demo/发布包差异已登记；公开形状和版本范围冻结 | H | done |
 | PKG-IFRAME-02 | artplayer-tool-iframe<br>建立特有行为与错误测试 | PKG-IFRAME-01, ENG-03, ENG-05 | 跨窗口消息、ID 匹配、请求失败、重复 inject、销毁中请求 | 旧版本行为可重跑，成功/失败/切源/销毁有必要断言 | H | done |
-| PKG-IFRAME-03 | artplayer-tool-iframe<br>整理内部职责与资源 | PKG-IFRAME-02, CORE-02, BASE-07 | 请求注册/响应匹配/监听清理分离；origin/source 安全边界独立决策 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | todo |
+| PKG-IFRAME-03 | artplayer-tool-iframe<br>整理内部职责与资源 | PKG-IFRAME-02, CORE-02, BASE-07 | 请求注册/响应匹配/监听清理分离；origin/source 安全边界独立决策 | 结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过 | H | doing |
 | PKG-IFRAME-04 | artplayer-tool-iframe<br>迁移自有源码和公开类型 | PKG-IFRAME-03, ENG-04, ENG-06, CORE-07 | 消息联合类型、回调/Promise 推导、旧公开字段兼容；旧npm export=与实际namespace、额外helper协议分别核验 | 严格类型检查、旧消费样例通过；声明路径/导出和同步异步兼容 | H | todo |
 | PKG-IFRAME-05 | artplayer-tool-iframe<br>验证新旧核心和组合 | PKG-IFRAME-04, CORE-22 | 真实同源/跨源 iframe、既有 commit 协议；安全变化有独立结论 | 最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成 | H | todo |
 | PKG-IFRAME-06 | artplayer-tool-iframe<br>验证分发并同步文档 | PKG-IFRAME-05, ENG-07 | iframe.js、示例集成和原 script/class 导出验证；旧包名/额外helper深入口与新工具名的迁移结论 | tarball 入口/资源、类型、8082 demo 和 README 一致，有回退记录 | H | todo |
@@ -532,4 +532,5 @@
 - PKG-MB-09: [记录](changes/2026-09-12-PKG-MB-09-native-pip-checkpoint.md) [记录](baselines/mb-native-pip-checkpoint.json) [记录](changes/2026-09-12-PKG-MB-09-sustained-playback-checkpoint.md) [记录](baselines/mb-sustained-validation.json) [记录](baselines/mb-sustained-media.json)
 - PKG-IFRAME-01: [记录](changes/2026-09-12-PKG-IFRAME-01-contract.md) [记录](baselines/iframe-release.json) [记录](baselines/iframe-contract.md) [记录](baselines/iframe-contract-validation.json)
 - PKG-IFRAME-02: [记录](changes/2026-09-12-PKG-IFRAME-02-behavior.md) [记录](baselines/iframe-behavior-validation.json)
+- PKG-IFRAME-03: [记录](changes/2026-09-12-PKG-IFRAME-03-requests-checkpoint.md) [记录](baselines/iframe-requests-checkpoint.json)
 - PKG-FACTORY-01: [记录](baselines/factory-assignment-gaps.json) [记录](baselines/factory-compatibility-proposals.json) [记录](factory-compatibility-decision.md) [记录](changes/2026-09-12-PKG-FACTORY-01-decision.md)
@@ -1,5 +1,18 @@
 # 进度与证据

+## PKG-IFRAME-03 请求资源与TS入口检查点（doing）
+
+入口和请求管理拆为2个严格TS模块，保留7个公开字段及resove/回调/消息协议。
+修复ID冲突/回拨、跨实例串线、销毁悬挂、轮询发送错误和公开回调的资源泄漏。
+同16断言旧版5通过/11失败，候选源码/main/legacy各16通过；旧版真实Chromium
+候选断言2通过/8失败。最终main浏览器174（历史144+候选30）、legacy候选30通过，
+完整CI1505与44重复契约、3导入/SSR文件通过，326生产TS。审查发现并修复空记录
+兼容回归；一次Windows复制失败经正常重建恢复，全部旧/失败/最终报告保留。
+见[变更](changes/2026-09-12-PKG-IFRAME-03-requests-checkpoint.md)和
+[验证](baselines/iframe-requests-checkpoint.json)。222项：107 done、10 doing、105 todo。
+本地检查点提交；IFRAME-03和三个风险仍未关闭。下一步导航/重新注入、构造失败清理、
+畸形消息与独立来源信任策略，随后04处理公开声明与旧helper/分发兼容。
+
 ## PKG-IFRAME-02 完成：历史生命周期与真实窗口缺陷复现

 52项Node和144项Chromium/Firefox/WebKit真实窗口检查通过，覆盖4份历史产物、同源/跨源。
@@ -3775,14 +3775,16 @@
      ],
      "status": "open",
      "confirmation": "reproduced",
-      "compatibleResolution": "Reproduce same-tick request collision, pending injection, response errors and destroy behavior before changing internal ownership; preserve public promises[id].resove.",
+      "compatibleResolution": "Request ownership checkpoint fixes timestamp collisions, polling/send failures and terminal destruction while preserving public resove/registry/envelopes. Navigation/reinjection and setup failure cleanup remain for PKG-IFRAME-03; keep open until complete actual iframe lifecycle acceptance.",
      "closureCriteria": "Old behavior and candidate fixes have deterministic race/resource tests plus actual iframe integration.",
      "evidence": [
        "refactor/baselines/iframe-contract.md",
        "refactor/baselines/iframe-release.json",
        "refactor/changes/2026-09-12-PKG-IFRAME-01-contract.md",
        "refactor/baselines/iframe-behavior-validation.json",
-        "refactor/changes/2026-09-12-PKG-IFRAME-02-behavior.md"
+        "refactor/changes/2026-09-12-PKG-IFRAME-02-behavior.md",
+        "refactor/changes/2026-09-12-PKG-IFRAME-03-requests-checkpoint.md",
+        "refactor/baselines/iframe-requests-checkpoint.json"
      ]
    },
    {
@@ -3656,11 +3656,14 @@
        "CORE-02",
        "BASE-07"
      ],
-      "status": "todo",
+      "status": "doing",
      "risk": "H",
      "deliverable": "请求注册/响应匹配/监听清理分离；origin/source 安全边界独立决策",
      "acceptance": "结构变化和缺陷修复分开记录；原 API/事件/资源生命周期通过",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-12-PKG-IFRAME-03-requests-checkpoint.md",
+        "baselines/iframe-requests-checkpoint.json"
+      ]
    },
    {
      "id": "PKG-IFRAME-04",