fix(iframe): [PKG-IFRAME-05] checkpoint player and editor integration

refactor/changes/2026-09-13-PKG-IFRAME-05-integration.md

@@ -0,0 +1,112 @@
+# PKG-IFRAME-05 real player and docs integration
+
+Started at 047e2df945fffe5699def60f2cf0497c00264117 with a clean worktree.
+Task 04 completed type and installed-consumer validation. This task remains
+responsible for actual player/media behavior, including old supported cores,
+same/cross-origin documents, navigation and demo integration.
+
+The real docs/assets/example/iframe.js and docs/iframe.html are integration inputs.
+The original plugin release is associated with core 4.5.9; freeze its actual npm
+archive rather than substituting the unrelated 4.5.5 or 5.1.7 fixtures. Current
+published core is the already frozen 5.4.0; candidate is the actual current build.
+
+Browser scope and any fixture adaptation must be recorded. A standalone player
+harness using the docs inputs is not the complete Monaco editor or physical
+device/BFCache acceptance. A normal history reload is not cached restoration.
+The editor currently destroys parent Artplayer.instances before eval, but the
+iframe tool lives outside that registry: repeated-run cleanup needs evidence.
+
+No task completion, risk closure, version or release claim is made at this point.
+
+## Player and editor checkpoint
+
+The frozen 4.5.9 npm archive has 176 members. `iframe-core.test.mjs` checks the
+historical release association, complete member inventory, manifest and every
+member hash; the browser server independently verifies its selected entry.
+
+The player matrix has 72 rows: three cores (4.5.9, frozen 5.4.0, candidate), two
+origins, four old/new parent-child bridge pairs and three browser engines. It
+loads the actual docs iframe HTML, example and stylesheet, adapting only the
+child URL and test-only historical global-name aliases. Each row decodes and
+plays actual video, seeks, changes rate, clicks fullscreenWeb controls, checks
+parent geometry/messages, switches media, destroys the player and proves that
+the tool can still execute a separate request. Helper/package aliases are not
+implemented by this test adaptation.
+
+The additional three editor rows use the actual docs index, local Monaco and Run
+button. Only the iframe constructor is observed through a test subclass; the
+external advertising script is stubbed in this test, with no production change.
+The test runs the iframe example three times, rejects an outstanding request on
+cleanup, switches to two parent players, then runs an empty example and checks
+that both parent players were destroyed.
+
+Real defects found and fixed:
+
+- Loading Monaco's AMD loader before the UMD core produced `Artplayer is not
+  defined` before editor initialization. The docs index now loads the core,
+  Monaco loader and editor bootstrap in dependency order.
+- Repeated Run left the previous iframe tool alive. The editor now emits the
+  docs-only `artplayer:example:cleanup` event before evaluating another example;
+  the iframe example listens once, destroys its tool and removes its frame.
+  Initial setup handles expected cancellation when the example is cleaned up.
+- The parent instance registry is mutable during destroy. Run now iterates a
+  snapshot, and the two-player editor assertion checks complete cleanup.
+
+All changes are in the docs integration and test infrastructure; the core/tool
+runtime source and distribution bytes are unchanged. No public player API is
+added or removed. Standalone consumers still own tool destruction.
+
+## Failed probes and limits
+
+Failed reports and complete trace/result directories are retained in `.cache`:
+`iframe05-player-probe*`, `iframe05-player-source-before*`,
+`iframe05-editor-before*`, `iframe05-editor-cleanup-before*`, and
+`iframe05-editor-cleanup-probe*`.
+
+The first player probe had an incorrect test URL; response status is now checked
+before injecting bytes. The next probe exposed the existing serialized-body
+regex's requirement for a recognizable `resolve(...)` call: compilation of an
+inline object argument added newlines. The test now assigns the result to a local
+variable and calls `resolve(result)`, preserving the historical protocol.
+
+The initial full matrix passed 68/72. All four failures were old core 4.5.9 on
+cross-origin WebKit, where traces showed successful playback but an invisible
+control during click. Moving the pointer over the player, as an actual user
+does, reveals the controls; no forced click, timeout increase or product API
+change was used. The original failed traces remain available.
+
+The first editor probe reproduced the AMD startup defect. After that fix, a
+probe attempted Run while the full-screen iframe covered it; the test now exits
+fullscreen through its real control first. The corrected probe then reproduced
+the live old-tool cleanup defect. Subsequent editor checks cover real Run clicks.
+
+This is a desktop integration checkpoint, not task completion. Actual BFCache
+restoration, physical devices, externally interrupted navigation and final
+8082/distribution acceptance remain open. Normal history reload does not count
+as BFCache, and Windows WebKit does not count as physical Safari. Old unmarked
+peers retain the limitations recorded in ADR-026. Final verification counts and
+input/report hashes are in `baselines/iframe-integration-validation.json`.
+
+## Verification
+
+- Source, main and legacy each passed all 75 desktop browser rows, with no
+  retries, skipped rows or flaky results: 225 passing cases in total.
+- Historical archive verification passed for all 176 members.
+- Browser test/server lint and docs JavaScript syntax checks passed.
+- ESM, i18n and SSR imports: 3 passing tests.
+- Full CI passed 1544 tests (1365 unit, 14 engineering, 165 historical/baseline)
+  and strict checking of 330 production TypeScript files. The browser counts
+  above are independent native-browser runs, not unit-test counts.
+- Configured coverage passed with 0 gate violations across 224 runtime files
+  and 26 documented/type-only exclusions. Lines: 61.04%, branches: 86.7%,
+  functions: 66.75%. This does not claim full coverage of every package.
+- The generated core editor declaration retains the pre-existing unused
+  `ts/no-namespace` disable warning, also present in task 04's final CI log.
+  There are no new lint errors; no generated declaration was hand-edited.
+
+No dependencies, package versions, runtime build bytes, push or publication were
+changed. Roll back the docs index, common Run handler and iframe example together
+to restore the preceding integration; this also restores the documented defects.
+Task status remains doing and all three iframe risks remain open.
+
+Checkpoint subject: `fix(iframe): [PKG-IFRAME-05] checkpoint player and editor integration`.