test(iframe): [PKG-IFRAME-05] verify native cached history and interrupted navigation

2026-10-17 10:01:20 -08:00 · 2026-09-13 02:55:57 +08:00
1 parent b35183c7af
commit cb6c767731
@@ -0,0 +1,122 @@
+# PKG-IFRAME-05 native cached history and interrupted navigation checkpoint
+
+Started from b35183c7af10a7309c9409b50fe8d5fda9db9ffb with a clean worktree.
+The preceding checkpoint verifies actual player and Monaco integration. This
+checkpoint addresses genuine BFCache restoration and external navigation
+interruption without changing public APIs or production runtime bytes.
+
+## Reproducible browser environment
+
+The installed Playwright 1.63.0 source explicitly adds
+`--disable-back-forward-cache` to Chromium. Its default headless shell also
+reloaded this fixture after that argument was removed. The separate
+`playwright.iframe-history.config.js` therefore uses the full `chromium` channel
+and removes only that BFCache-disabling argument. Ordinary browser tests retain
+their original configuration and report directory.
+
+Initial download of full Chromium 153.0.8010.12 timed out. A supplementary probe
+with the already installed full 151.0.7922.34 demonstrated actual restoration,
+but is not substituted for the pinned-version results. After confirming a local
+proxy listener, a process-scoped HTTPS_PROXY allowed the normal Playwright
+installer to download full 153.0.8010.12. No machine proxy or repository proxy
+configuration was changed. No package dependency version was changed.
+
+`yarn test:iframe-history` uses a separate local fixture server on port 8085 and
+records to `refactor/.cache/iframe-history`. The browser receives real HTTP pages,
+core/tool scripts and media with cacheable headers. There is no request routing,
+synthetic pageshow event, reconstructed document, or mocked media in this matrix.
+The parent and child each retain an independent random document witness and
+native page lifecycle events. All candidate script and fixture hashes are in
+the environment attachment. Artifact overrides never silently fall back to source.
+
+The GitHub browser job now runs this command and uploads its evidence directory.
+Local Windows evidence is not evidence that the hosted macOS job has executed.
+
+## History assertions
+
+The history matrix has 36 cases: cores 4.5.9, frozen 5.4.0 and candidate; same
+and cross origin; paused and playing; Chromium, Firefox and WebKit. Full Chromium
+must show actual `pageshow.persisted`, unchanged parent/child witnesses and
+unchanged private document IDs. Player position/rate and the pending resolver
+survive in the same document, communication resumes, playback works and resources
+can be destroyed. Private resume packets must not become public callbacks or
+duplicate the original inject callback.
+
+Whole-page caching freezes the parent too. A child's best-effort pagehide message
+may not reach that frozen parent. The test correlates the request state with the
+actual delivered private phases: with no delivered leave, the old request stays
+pending and can resolve after restoration; with a delivered leave it must already
+be rejected and a late resolver cannot change the result. This is distinct from
+the existing child-only navigation tests, where an active parent processes leave.
+
+Firefox and WebKit currently recreate both documents. These cases explicitly
+record `reload-control`, verify changed witnesses and successful fresh playback,
+and do not count toward actual BFCache acceptance. Native Firefox/WebKit cached
+restoration and physical devices remain unverified.
+
+## Interrupted navigation assertions
+
+Another 54 cases cover the same three cores and two origins on all three engines:
+
+- Stop a genuinely pending HTTP navigation. Chromium uses native CDP
+  `Page.stopLoading`; Firefox and WebKit use top-window `window.stop()`.
+- Return HTTP 204, retaining the old document.
+- Start an HTTP 200 document response, declare more bytes than are sent, then
+  destroy the connection after writing the partial HTML.
+
+An active old document can still settle a request it already received. A committed
+replacement cancels old owned work. Queued new requests cannot execute in the old
+document and remain waiting until a subsequent valid iframe source injects. The
+test then starts another stalled navigation, destroys the tool and removes the
+frame, checking immediate rejection and release of the test server's barrier.
+
+This preserves the existing absence of implicit request timeouts. A failed target
+does not automatically authorize commands to run in a different old document.
+The application can navigate to another valid source or destroy the tool. These
+tests establish those recovery paths, not automatic recovery from every network
+failure or an undocumented timeout policy.
+
+## Failed probes retained
+
+`iframe05-history-probe*.json/log` retain shell/full browser comparisons, the
+missing full-browser executable, and actual supplementary/pinned-version probes.
+The full installer logs retain direct timeout and process-proxy success.
+
+Chromium's automation frame inventory omitted the restored cross-origin child in
+the probe even while native parent/child witnesses and SDK communication survived.
+The permanent tests inspect the restored child through the actual public commit
+protocol rather than relying on an automation-side Frame object.
+
+The first stop probe stalled while evaluating the old cross-origin child during
+its pending navigation. Sending a stop signal to that child, and then calling
+top-window stop, also failed to terminate the pending cross-process navigation in
+Chromium. The final test uses the browser's Page.stopLoading command there. These
+failures are preserved in `iframe05-interruption-probe*.json` and complete results
+directories. No SDK behavior was changed to work around the driver/browser stop
+boundary; the exact stop mechanism is recorded per engine.
+
+Final source/main/legacy results, input hashes, CI and workflow verification are
+recorded in `baselines/iframe-history-validation.json`. Task 05 remains doing and
+its risk records stay open for remaining device/cache-engine/release acceptance.
+No push, tag, npm publication or major-version release is performed.
+
+## Final verification and rollback
+
+- Source/main/legacy each pass 90 cases without skips, retries or flaky results:
+  270 total, including 36 actual Chromium cache restorations, 72 explicit reload
+  controls and 162 interruption/recovery cases.
+- Full CI passes 1544 tests (1365 unit, 14 engineering, 165 baseline) and strict
+  checking of 330 production TypeScript files; import/SSR checks pass 3 tests.
+- actionlint 1.7.12 validates the updated workflow. All new browser/config files
+  pass lint. The generated core editor's existing unused directive warning is
+  unchanged. No new coverage run is claimed for unchanged production source.
+- The runtime source and all three iframe distribution files match the preceding
+  checkpoint byte-for-byte. No package rebuild is necessary for these test/docs
+  and CI-only changes. Hosted CI, physical devices and other cache engines are
+  not promoted to passed from local evidence.
+
+Rollback removes the independent history test/config/server/script and CI step
+together, and restores the linked documentation/evidence. It does not require a
+runtime rollback or change the old public API.
+
+Checkpoint subject: `test(iframe): [PKG-IFRAME-05] verify native cached history and interrupted navigation`.
@@ -1,6 +1,6 @@
 # 复用 docs HTML 与在线编辑器进行真实测试

-2026-09-10 已核对下列页面及脚本源码，尚未实际运行页面。优先复用现有 HTML 和示例作为浏览器验收入口，保留旧 URL/参数和编辑器功能；另补可靠断言、状态隔离和报告，不把演示能打开当作兼容性通过。
+2026-09-10 首次清点时仅核对源码。后续实际运行以各任务证据为准：IFRAME-05 已验证真实iframe页面、Monaco Run和桌面历史导航，见[播放器/编辑器记录](changes/2026-09-13-PKG-IFRAME-05-integration.md)及[缓存/中断记录](changes/2026-09-13-PKG-IFRAME-05-history.md)。保留旧 URL/参数和编辑器功能，补可靠断言、状态隔离和报告，不把演示能打开当作兼容性通过。

 ## 入口与实际加载方式

@@ -38,6 +38,12 @@ ENG-05 已提供 `yarn test:browser`、8084 隔离服务和 `ARTPLAYER_BROWSER_A

 ## 任务归属与验收

+IFRAME-05 的 `yarn test:iframe-history` 使用8085的独立缓存页面及完整Chromium通道，
+移除Playwright默认禁用BFCache的参数。原8084配置保持不变。只有父子文档标识连续且
+原生pageshow.persisted为true才记为缓存恢复；Firefox/WebKit的reload-control单独计数。
+该命令还验证真实停止加载、HTTP 204、截断文档响应和后续导航/销毁，GitHub浏览器任务
+运行并上传对应报告。它不替代8082实际分发、完整站点、物理设备或其他缓存引擎的验收。
+
 | 任务 | 负责交付 |
 | --- | --- |
 | BASE-04 | 记录上述页面、核心/插件加载路径、存储状态及核心/chapter 的真实行为基线 |
@@ -47,6 +47,15 @@ WindowProxy在导航中保持身份。旧协议只用Date.now的请求ID，无
 `The instance has been destroyed`。调用方需要处理commit/postMessage的拒绝。
 未确认离开前，原文档已完成的响应仍可结算原请求；这属于活文档的正常完成，不是假定所有导航意图都是换页。

+整页进入BFCache时父页也会冻结，子页的best-effort leave不一定送达。实际完整Chromium
+恢复证明父子文档及标记可以保持不变：未收到leave的原请求可以在恢复后继续完成；已收到
+leave的原请求保持拒绝。resume不伪造公开inject，也不会让已结算的请求复活。测试同时
+核对实际私有消息阶段和Promise结果，而不只检查history.back或Navigation Timing类型。
+
+停止加载、HTTP 204及截断响应不会授权把新请求发送给旧目标。旧文档仍活跃时可完成
+原请求，新队列继续等实际inject；设置后续有效iframe.src或destroy分别恢复或取消队列。
+没有新增隐式超时、自动旧源回退或覆盖window.stop。真实停止方法和网络响应见history测试记录。
+
 公开promises记录保留resove/reject和对象身份。普通响应仍尊重用户替换的公开回调；
 内部取消独立持有原Promise拒绝入口，不能因用户删除/替换记录而泄漏原Promise。

@@ -56,8 +65,9 @@ WindowProxy在导航中保持身份。旧协议只用Date.now的请求ID，无
  不能通过未升级的一侧可靠证明。完整文档保护需双方使用新实现，旧正常协议继续兼容。
 - MutationObserver不可用时，只能在公开方法/轮询时检查可观察的源变化；语法legacy目标不等于补齐DOM能力。
 - 未标记的自定义原生消息仍按旧协议接受；其文档级归属由应用管理。SDK提供的消息在协商后携带标记。
- 历史返回用例记录实际pageshow.persisted。普通重新加载不能计作原生BFCache验证；完整播放器、
-  原生BFCache/设备、外部中断导航与文档站实际组合仍在IFRAME-05及发布复盘核验，未由本轮自动豁免。
+- 历史返回必须核对实际pageshow.persisted与文档标识。IFRAME-05新增完整Chromium真实缓存恢复、
+  实际播放器及编辑器、停止/204/截断响应验收。Firefox/WebKit的重新加载对照不能计作缓存恢复；
+  原生设备、其余缓存引擎及最终分发仍待验收，不由桌面通过结果自动豁免。
 - 本协议不验证父页origin许可，也不把可执行commit变成代码沙箱；嵌入父页和选定子内容仍需可信。

 验证入口为test/iframe-navigation.test.js和test/browser/iframe-navigation.spec.js，记录见
@@ -534,5 +534,5 @@
 - 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) [记录](changes/2026-09-12-PKG-IFRAME-03-boundaries-checkpoint.md) [记录](baselines/iframe-boundaries-checkpoint.json) [记录](iframe-message-boundary.md) [记录](changes/2026-09-13-PKG-IFRAME-03-navigation.md) [记录](baselines/iframe-navigation-validation.json) [记录](iframe-document-protocol.md)
 - PKG-IFRAME-04: [记录](changes/2026-09-13-PKG-IFRAME-04-types.md) [记录](baselines/iframe-types-validation.json)
- PKG-IFRAME-05: [记录](changes/2026-09-13-PKG-IFRAME-05-integration.md) [记录](baselines/iframe-integration-validation.json)
+- PKG-IFRAME-05: [记录](changes/2026-09-13-PKG-IFRAME-05-integration.md) [记录](baselines/iframe-integration-validation.json) [记录](changes/2026-09-13-PKG-IFRAME-05-history.md) [记录](baselines/iframe-history-validation.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-05 原生缓存与中断导航检查点（doing）
+
+新增独立 `yarn test:iframe-history`：完整Chromium通道与可缓存HTTP页面，避免默认
+Playwright禁用BFCache产生的错误验收。源码/main/legacy各90项通过，共270项；其中
+36项实际Chromium缓存恢复、72项Firefox/WebKit重新加载对照、162项停止/204/截断响应
+后的恢复和销毁。核对父子文档标识、原生persisted、媒体状态、请求结算和后续通信。
+GitHub浏览器任务已增加运行及报告上传，actionlint通过；未推送或声称远端CI已执行。
+全仓CI1544、330生产TS检查和3导入测试通过；不把未重新运行的覆盖率标成本轮新结果。
+原生产源码/产物及公开接口未变；整页冻结可能保留未收到leave的原请求，已明确记录。
+见[变更](changes/2026-09-13-PKG-IFRAME-05-history.md)与
+[验证](baselines/iframe-history-validation.json)。物理设备、Firefox/WebKit实际缓存恢复、
+最终分发仍待验收。222项：109 done、10 doing、103 todo。
+
 ## PKG-IFRAME-05 播放器与真实编辑器检查点（doing）

 冻结原支持核心4.5.9的176个npm文件，与已冻结5.4.0、候选核心组成真实媒体矩阵。
@@ -9,8 +22,8 @@ Monaco页面Run流程。覆盖播放、seek/rate、网页全屏、切源、播
 源码和运行产物字节未变，旧公开API保持；失败探针、trace及后续通过报告均留存。
 全仓CI1544、330生产TS检查、3导入测试通过，配置覆盖率门槛0违例（224运行文件）。
 见[变更](changes/2026-09-13-PKG-IFRAME-05-integration.md)和
-[验证](baselines/iframe-integration-validation.json)。实际BFCache、物理设备、外部
-中断导航及最终分发仍待验收，不因此关闭任务或风险。222项：109 done、10 doing、103 todo。
+[验证](baselines/iframe-integration-validation.json)。后续缓存/中断证据见上方；物理设备与
+最终分发仍待验收，不因此关闭任务或风险。222项：109 done、10 doing、103 todo。

 ## PKG-IFRAME-04 完成：公开类型、模块入口和编辑器

@@ -3776,7 +3776,7 @@
      ],
      "status": "open",
      "confirmation": "reproduced",
-      "compatibleResolution": "Owned requests and ADR-026 document cancellation are implemented. IFRAME-05 now verifies actual desktop players and Monaco Run on source/main/legacy, including pending-request and multiple-player cleanup. Keep open for actual BFCache/device and interrupted-navigation acceptance; unchanged legacy peers retain documented document-identity limits.",
+      "compatibleResolution": "Owned requests and ADR-026 document cancellation are implemented. Task 05 verifies actual desktop players/Monaco and source/main/legacy cached history plus stop/204/truncated-response recovery. Full Chromium proves native BFCache; Firefox/WebKit only prove reload controls. Keep open for physical devices, remaining cache engines and final release acceptance; legacy peers retain documented document-identity limits.",
      "closureCriteria": "Old behavior and candidate fixes have deterministic race/resource tests plus actual iframe integration.",
      "evidence": [
        "refactor/baselines/iframe-contract.md",
@@ -3792,7 +3792,9 @@
        "refactor/baselines/iframe-navigation-validation.json",
        "refactor/iframe-document-protocol.md",
        "refactor/changes/2026-09-13-PKG-IFRAME-05-integration.md",
-        "refactor/baselines/iframe-integration-validation.json"
+        "refactor/baselines/iframe-integration-validation.json",
+        "refactor/changes/2026-09-13-PKG-IFRAME-05-history.md",
+        "refactor/baselines/iframe-history-validation.json"
      ]
    },
    {
@@ -3819,7 +3821,9 @@
        "refactor/baselines/iframe-navigation-validation.json",
        "refactor/iframe-document-protocol.md",
        "refactor/changes/2026-09-13-PKG-IFRAME-05-integration.md",
-        "refactor/baselines/iframe-integration-validation.json"
+        "refactor/baselines/iframe-integration-validation.json",
+        "refactor/changes/2026-09-13-PKG-IFRAME-05-history.md",
+        "refactor/baselines/iframe-history-validation.json"
      ]
    },
    {
@@ -3710,7 +3710,9 @@
      "acceptance": "最终核心与原支持范围核心分别通过；设备/SDK 缺证据不能标完成",
      "evidence": [
        "changes/2026-09-13-PKG-IFRAME-05-integration.md",
-        "baselines/iframe-integration-validation.json"
+        "baselines/iframe-integration-validation.json",
+        "changes/2026-09-13-PKG-IFRAME-05-history.md",
+        "baselines/iframe-history-validation.json"
      ]
    },
    {