KoalaSync/docs/nested-player-frame-targeting.md

Targeting a nested cross-origin player without webNavigation

Status: Fixed. Everything below was verified against the live site or a fixture rebuilt from it.

Context: v3.1.2 added support for players inside cross-origin frames (Google Drive, anime hosts) and shipped with a webNavigation permission. The permission was not acceptable for the store listing, so 4d78970 removed it. Removing it broke the feature. This document records why, and what replaced it.

---

Why the permission mattered

chrome.webNavigation.getAllFrames({ tabId }) is an observation: a browser-side registry lookup that returns every frame's frameId and documentId without touching the frames. It answers while a frame is loading, navigating or being rebuilt.

chrome.scripting.executeScript({ target: { tabId, allFrames: true } }) is an intervention: it must run code inside every frame. It is all-or-nothing — one frame that is mid-teardown makes Chromium reject the whole call — and it only reports frames it managed to enter.

That difference is the entire regression. The players on these sites renavigate and rebuild their <video> continuously, so an intervention-based discovery reliably lands in a window where it fails, while an observation-based one never had such a window.

No permission is needed to close the gap — see Replacing the frame list below.

The page under test

yummyanime.tv, KODIK mirror selected. Verified live:

top (yummyanime.tv)                        0 videos
├── yastatic share iframe        0x0       hidden
├── xfplayer_<id>                0x0       hidden, same-origin   <- parked mirror
│   └── absciss.thealloha.club   0x0       hidden, cross-origin
├── xfplayer_<id>              830x498     visible, same-origin  <- active wrapper
│   └── kodikplayer.com        830x498     visible, cross-origin <- the player
└── youtube.com/embed            0x0       hidden, cross-origin  <- another mirror

Properties that matter, all confirmed:

• The player is at depth 2, behind a same-origin wrapper.
• It carries no sandbox attribute, so it is injectable.
• It has no <video> element at all until playback starts.
• Its frame navigates after load (a /720p suffix appears), invalidating documentId.
• Unselected mirrors stay in the DOM, collapsed to 0x0.
• Loading kodikplayer.com directly fails a referrer check, so it can only be inspected embedded.

The YouTube mirror works where the others do not, because it is a direct child of the top frame; the failures are specific to depth-2 nesting.

Fixed

Each item was a separate defect on the path from "user picks a tab" to "playback is controlled".

Access was inferred, not measured. Every probe error was swallowed, and any origin that failed to answer was reported as missing host access — so a slow player frame produced a permission prompt for an origin the extension already held. The resolver now calls permissions.contains() before raising an access error.

Probes were unbounded. Nine executeScript calls in the injection path had no timeout; one unresponsive frame pinned activeTargetActivation and the popup showed activating forever with nothing in the log. All are time-boxed, and a watchdog abandons any activation still running after 30s.

Equally-ranked players were a hard failure. Several mirrors loaded at once is an ordinary layout here. The resolver now holds the top frame and waits for one of them to start playing, which breaks the tie.

Inconclusive probes moved the target. A page whose players are still loading resolves differently from call to call, and every difference triggered a full teardown and reinjection, so activation never settled. A probe that finds no video now leaves the target alone.

The video-state poll restarted the target. getReadyTabVideoState() treated "no video found" as a broken injection and forced a reactivation — on every poll, and the dev panel polls on a timer.

Ordinary playback looked like a layout change. The media-frame monitor's candidate signature included paused/readyState/duration, so every play, pause and buffering tick retriggered a full reactivation.

A hidden srcless iframe could hide the page containing it. An <iframe> without src resolves to its parent document's URL. Ad slots are frequently srcless, so a hidden slot could mark a real player's frame as hidden.

The chat overlay followed the player into its frame, rendering on top of the video and scoping close/minimize to that frame. It is now always installed in the top document.

A failed activation discarded the user's selection, so the popup came back empty after being reopened. The selection is now stored in its own right with a terminal state (ready / activating / access_required / error).

Replacing the frame list

Two mechanisms together do what getAllFrames() did, with no permission:

1. A learned frame registry. Every executeScript result carries frameId and documentId, and every content script that messages the background carries sender.frameId. Those are recorded per tab (capped, top frame never evicted) and any frame the sweep missed is then probed individually, so one rejected probe costs one frame instead of the whole page.

   The registry must not be cleared on navigation: tabs.onUpdated reports status: 'loading' for same-document History API navigations too, which is exactly what these sites do when switching mirror or episode part. Clearing there wiped the registry while the player frame was being built. It self-corrects instead — a probe that reached more than the top frame supersedes the stored ids.

2. Not needing the answer. Frame election is the fragile half, and playback does not depend on it:

   • Outbound, a command is broadcast to the tab when the elected frame reports no video. Every content-script handler starts with findVideo() and returns when there is none, so only the frame that owns the player acts.
   • Inbound, isCurrentContentSender() no longer requires sender.frameId to equal the elected frame while that frame has no video — otherwise the user's own play/pause arriving from the real player frame was discarded as a stale sender. The reporting frame is then adopted as the target.

   Both relaxations apply only while the elected frame reports no video; a good election still takes the strict path, so hidden-player rejection is unaffected.

Latency

Selection felt broken at ~20s. Measured against the two anime fixtures after the fix, calm page / heavy ad churn:

	calm	ad churn
selection	2.5s	2.6s
player promotion	0.34s	2.7s

What was removed: the visibility handshake ran even when no frame had a video (its only job is ranking candidates); its pass count was fixed at the worst-case nesting depth of four rather than the observed two; the retry budget was spent waiting for a video no frame had; and both probe timeouts were 2000ms for what is synchronous DOM work — a live frame answers in tens of milliseconds, anything slower is a frame being torn down.

The remaining ~2.5s is the injection chain itself (monitors, page-API bridge, chat overlay, content script), not discovery.

---

A dead frame election, and the deadlock behind it

Reported: 2026-08-18. Could not establish connection. Receiving end does not exist. with targetReady: true and no activation errors — the election named a frame the player had already torn down.

Three defects were stacked here, each hidden by the one in front of it.

The election was never released. getReadyTabVideoState() recovered through the guarded refresh, which reports unchanged when no video is reachable, so the stale frameId/documentId survived. Adoption compounded it: it sets hasVideo, and once that is true the target only moves on a frame change. An unreachable content script — as opposed to a page that simply has no video yet — now releases the frame election back to the top frame. The tab selection is never touched.

Switching frames destroyed the top frame's scripts. Promoting the target from frame 0 into a nested player called deactivateTargetTab() on the previous target, which sent TARGET_DEACTIVATE to frame 0 and tore down both its content script and the chat overlay there. That is why chat delivery failed after promotion, and why releasing the election pointed at an empty frame. An in-tab frame switch now leaves the top frame alone.

Discovery could deadlock. Monitors announce new players, but a rebuilt frame is a new document with no monitor, so the video created in it was never reported — and nothing then triggered the upkeep that would have installed one. Reinstalling monitors is cheap, bounded and idempotent, so it now runs on every lifecycle notification with a trailing-edge debounce; and a bounded discovery poll (2s, capped, only while a tab is selected with no video found, stopping the moment one is) breaks the cycle when no notification arrives at all.

Covered by recovers when the adopted player frame is torn down and rebuilt, which adopts a nested player, destroys its document the way the real player does, and asserts both that the election is released and that the rebuilt player is picked up again without touching the popup.

---

Guardrails

Contract tests in extension/target-tab-lifecycle.test.mjs hold the invariants that were each violated at least once during this work:

• no chrome.webNavigation anywhere, and permissions limited to the v3.1.1 set
• the frame registry is bounded and is not cleared on navigation
• monitors are injected and deactivated across known frames, not only via the sweep
• forcing a rebuild stays rare: only an unreachable content script, an explicit request, and a completed navigation
• playback state stays out of the monitor's candidate signature
• chat messages never go to the media frame

Browser-level coverage lives in tests/e2e/extension.spec.mjs against fixtures rebuilt from the real page: yummy-style-player.html (player present up front), yummy-deferred-player.html (player built on play) and yummy-churning-player.html (live ad churn), plus drive-style-player.html for the chat-placement case.