test(iframe): [PKG-IFRAME-01] freeze historical exports and message contract

2026-10-20 04:01:20 -08:00 · 2026-09-12 23:00:01 +08:00
1 parent 7e37fd4d0e
commit a52f79a0cc
@@ -0,0 +1,37 @@
+{
+  "task": "PKG-IFRAME-01",
+  "status": "done",
+  "sourcesSha256LF": {
+    "refactor/scripts/iframe-contract.mjs": "a709828ac0f3d35eb8f94ff915d8243e42903adb4e75f32a4907829e4fdf38b1",
+    "refactor/scripts/iframe-contract.test.mjs": "c1ab0bfbb88d0604c6b9e5467f5e581f0fdae75c5da4fea55b00ebcf2a3bb69f",
+    "test/helpers/iframe.js": "fd05f4fc10e97f1a0b8961ea8f82976ea9d58d0ea75bb652af2ee13b8a89c9a0",
+    "refactor/baselines/iframe-release.json": "c58a952a4a5a2f0c02e7c76521537898874eb6d7955b9daa6b427c51aeadece7",
+    "refactor/baselines/iframe-contract.md": "ac1c2ed68c02f0981ecff21edeeafde260dbf739caa763ca1b28c91831dba087"
+  },
+  "frozenArchiveMembers": 8,
+  "frozenWorkspaceInputs": 11,
+  "contractTests": 19,
+  "checks": [
+    {
+      "command": "node --test refactor/scripts/iframe-contract.test.mjs",
+      "result": "pass",
+      "log": "refactor/.cache/iframe01-contract-final.log"
+    },
+    {
+      "command": "yarn ci:check",
+      "result": "pass",
+      "tests": 1437,
+      "unit": 1263,
+      "engineering": 14,
+      "baseline": 160,
+      "repeatedContracts": 44,
+      "strictProductionTypeScriptFiles": 324,
+      "log": "refactor/.cache/iframe01-ci.log"
+    }
+  ],
+  "limitations": [
+    "Registry 404 is time scoped; tool-name publication history is not inferred.",
+    "No lifecycle fixes, production migration, origin policy change, actual iframe browser or installed-type acceptance in this contract task.",
+    "Auxiliary helper is a distinct historical protocol, not an alias for the main class."
+  ]
+}
@@ -0,0 +1,65 @@
+# iframe 工具的发布与工作区契约
+
+来源：[冻结清单](iframe-release.json)。查询npm时artplayer-tool-iframe返回404；这只说明
+该次查询不可获得包，不能推导历史上从未发布。实际旧包artplayer-plugin-iframe只有1.0.0，
+发布于2022-11-05，gitHead关联核心4.5.9；仓库改名提交为1c75731ca。
+当前工具版本1.1.0和发布包不是同一版本/包名，不得编造tool@1.1.0归档或拿重构产物代替旧包。
+
+## 入口与文件
+
+| 范围 | 已核实的真实形状 |
+| --- | --- |
+| npm plugin@1.0.0 | 8文件，含README、package.json、src、声明、4个JS产物；无module/exports |
+| 主main/legacy | CommonJS是含default的namespace，浏览器window.ArtplayerPluginIframe是类 |
+| 额外helper main/legacy | namespace.default及window.ArtplayerHelperIframe；有不同协议，不是主类别名 |
+| 旧声明 | export = / export as namespace ArtplayerPluginIframe；与运行时require返回namespace存在既有偏差 |
+| 冻结工作区tool@1.1.0 | main/legacy直接导出类，浏览器ArtplayerToolIframe；mjs只有default；root/legacy条件入口 |
+| 工作区声明 | default类ArtplayerToolIframe，旧readonly字段和resove拼写保留；静态onMessage仍声明void |
+
+初始工作区11个输入由Git固定：源、类型、README、manifest、npmignore、三产物、父demo、
+子iframe.html和编辑器声明。旧归档SHA512/SHA256与每个成员SHA256均核验；auxiliary helper
+也在验证中，不能漏掉它后再说旧包只有一个公共类。旧包导入名与新工具名的分发迁移、额外
+helper入口是否提供独立兼容门面，由IFRAME-04/06明确处理，不能把旧helper强行映射成新类。
+
+## 主类与协议
+
+构造参数仍为必需的{iframe: HTMLIFrameElement, url: string}。校验属于当前realm的iframe；
+先注册message监听，再设置src。自身可枚举字段顺序为url、$iframe、promises、injected、
+destroyed、messageCallback、绑定的onMessage。旧发布包非法参数抛Error，工作区已改为TypeError，
+这是改造前已有差异；不能把两者报告为完全相同。
+
+- static iframe读取window.top !== window；inject/postMessage/onMessage只能用于子frame。
+- inject先发{type:'inject', data:undefined, id:0}，再addEventListener；没有静态destroy。
+- static postMessage默认id=0，向window.parent发送，targetOrigin='*'。
+- 实例postMessage返回Promise；未inject时每200ms轮询，发出时使用Date.now()覆盖传入id。
+- promises[id]的公开字段是resove/reject，不能直接“纠正”resove拼写。
+- 收到inject设置injected；同id的error拒绝Error(data)，其他type也会resolve(data)，然后删除条目。
+- message回调收到{type,data}而不是id，this是实例；message与destroy返回undefined。
+- commit要求function，只截取toString中大括号内的body，不传闭包/参数。子端用new Function执行。
+  匹配resolve(...)时包入Promise(resolve)，否则同步执行并返回response；出错发error后重新抛出。
+- static onMessage实际返回Promise，而旧/当前声明为void；commit类型是Promise<ReturnType<T>>，
+  保留历史推导，不在本任务随意修正嵌套Promise或callback resolver类型。
+- destroy设置destroyed并移除实例监听；未清空promises，也未取消已安排的轮询，具体失败测试由02接续。
+
+## 额外helper是另一代协议
+
+helper使用实例isInject/isDestroy，没有iframe getter或主类的构造/函数参数校验。静态inject设置
+isInject/isDestroy，静态destroy会发送destroy包并移除静态监听；收到destroy也会进入相应流程。
+其静态onMessage出错发送error但不重新抛出；实例销毁后等待inject的Promise可一直悬挂。
+它没有对应独立d.ts；主类声明不能用来证明其类型兼容。
+
+## README、demo与待处理风险
+
+README仅简介/demo/许可证。父demo iframe.js使用新类名、url:'/iframe.html'，commit创建
+Artplayer，并由子端static postMessage通知fullscreenWeb；子页面加载两份uncompiled脚本后inject。
+当前demo注释提示npm安装tool名，但该名本次registry查询404，分发阶段须处理，不能在此宣称
+已完成真实跨源浏览器或npm安装验收。
+
+源码显示Date.now ID可能同毫秒冲突；destroy留下pending请求/轮询；重复inject先发握手再注册。
+当前父/子onMessage均未校验event.source/origin，子端接收可执行函数body，发包目标为'*'。
+这既是跨窗口信任边界，也是既有协议，须独立设计、取证并记录兼容性决策；不能借TS迁移默默
+删除commit、改成另一套RPC、或假称已验证来源隔离。上述生命周期/信任风险均保持open。
+
+运行`node --test refactor/scripts/iframe-contract.test.mjs`：19项覆盖实际主包/legacy、额外helper、
+工作区main/legacy/ESM、公开字段、消息包、callback receiver、commit body和resolver返回。
+它是可复现的契约基线；真正浏览器、异常时序、销毁/切源及安装类型矩阵由后续任务完成。
@@ -0,0 +1,76 @@
+{
+  "packageName": "artplayer-tool-iframe",
+  "registryObservation": {
+    "url": "https://registry.npmjs.org/artplayer-tool-iframe",
+    "status": 404,
+    "observedAt": "2026-09-12T14:45:37.698Z",
+    "body": {
+      "error": "Not found"
+    },
+    "meaning": "Registry returned 404 at observation; this is not proof the name was never published."
+  },
+  "release": {
+    "name": "artplayer-plugin-iframe",
+    "version": "1.0.0",
+    "publishedAt": "2022-11-05T01:42:14.095Z",
+    "tarball": "https://registry.npmjs.org/artplayer-plugin-iframe/-/artplayer-plugin-iframe-1.0.0.tgz",
+    "integrity": "sha512-9eh5NVjZ8/Vxl0ojZxnMY6IlYxCVVfyGH2Rzl7uYDJnGc8NQ4y9vMN/gVh1h8R2m5qaYm7/XDo/45O9a7hDiKg==",
+    "sha256": "16dc92aa84d93bd99bc0a34815dc49f1609fafc1ff255eb353ea893e70b5f91f",
+    "gitHead": "824baca8b408d9f3e0eb2f3d7e0eb2bdee2ff3a8",
+    "manifest": {
+      "license": "MIT",
+      "version": "1.0.0",
+      "name": "artplayer-plugin-iframe",
+      "types": "types/artplayer-plugin-iframe.d.ts",
+      "description": "Iframe plugin for ArtPlayer",
+      "main": "dist/artplayer-plugin-iframe.js",
+      "legacy": "dist/artplayer-plugin-iframe.legacy.js",
+      "author": "Harvey Zack <laozhaochaguan@gmail.com>",
+      "browserslist": "> 0.5%, last 2 versions, not dead",
+      "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"
+      ]
+    },
+    "files": {
+      "package/README.md": "52c0a1199b6529d60ce8f4414984f9bd1bc3a8daa5bb6cfec8f0aae0c8338e46",
+      "package/dist/artplayer-helper-iframe.js": "47730ed608f0637594549b9762c01191686a4a55b3bd467132304a016d227f4a",
+      "package/dist/artplayer-helper-iframe.legacy.js": "f4c3b11806cad6d984f03a2d9de63deba78cbe538ffe4044a106b0dddc5d4197",
+      "package/dist/artplayer-plugin-iframe.js": "df469c3e4582b127f35798494d0845f1fc4ca2d19bbaf01b918492e035479745",
+      "package/dist/artplayer-plugin-iframe.legacy.js": "15299cb5c848cc61614f7573a802443d69b7c6d0a938a1867835c7cbb4884edd",
+      "package/package.json": "563a6c8407753b92b86319a5e6d9d567525146c32cb010b45b0d88ff481859f6",
+      "package/src/index.js": "2e0b9efeedef0d6c4f2d2b526db35f634cd02af044e4e28dd1a0b26a5b9a02bf",
+      "package/types/artplayer-plugin-iframe.d.ts": "d55d99a2488d60892a0ab82882dc96a0f373dab0c3d2a3cee978bc35aa7c2d0c"
+    },
+    "historicalCore": {
+      "commit": "824baca8b408d9f3e0eb2f3d7e0eb2bdee2ff3a8",
+      "file": "packages/artplayer/package.json",
+      "version": "4.5.9",
+      "sha256LF": "7fe8f4a728c4895d2323a4214f024239f03b985f530529a5d257fa010252c195"
+    }
+  },
+  "sourceCommit": "40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f",
+  "source": {
+    "packages/artplayer-tool-iframe/src/index.js": "5fd5452640ff57fa35cd0f3378505ffc1318e9c114d9a2a6e2f1adbeaec6fd28",
+    "packages/artplayer-tool-iframe/types/artplayer-tool-iframe.d.ts": "4f02aa22a6b373393ead533ae3421ad5acf0de7116057f351021c72d3448bd1e",
+    "packages/artplayer-tool-iframe/README.md": "6910a44b767ff80c1d1edc3c90ca7ca77a9b45307fb61d4abd9d52526c7614b3",
+    "packages/artplayer-tool-iframe/package.json": "b28f5156f02a250539f0acaf302ec87fdd506f63b0e73dd308326ec78c691d03",
+    "packages/artplayer-tool-iframe/.npmignore": "46063058e98be55dba5cf5f33d379e73eca048f4126e7af75f8011bab7f09145",
+    "packages/artplayer-tool-iframe/dist/artplayer-tool-iframe.js": "2ec257c8055a9448d12af3fecf1fae8ba58c06f47e85072d02c386cd258b0c86",
+    "packages/artplayer-tool-iframe/dist/artplayer-tool-iframe.legacy.js": "c0755d79f316cda71f045da86749648f95faf47c09180d525fb04bb753576d5f",
+    "packages/artplayer-tool-iframe/dist/artplayer-tool-iframe.mjs": "cbcdb0516dd5f17ca2572a6b3e363ea63b0cfd9733f3e47689c02088f23f29b9",
+    "docs/assets/example/iframe.js": "00a8441d2a9873f7be342a98b58acab1cf6aca2359414f126ffb63f6ee20c218",
+    "docs/iframe.html": "bc262262c66ad32459b7c91ae22a97217414dd5b18cbf68fe105c2269456f879",
+    "docs/assets/ts/artplayer-tool-iframe.d.ts": "fe261fd8fb6a8f8838290a3eef3d624cf7587cec30edaa2644bcf0fb7b44bb5d"
+  },
+  "renameCommit": "1c75731ca9cf2edb7a2f1f26b1bac1de9847b9c3"
+}