diff --git a/docs/nested-player-frame-targeting.md b/docs/nested-player-frame-targeting.md
new file mode 100644
index 0000000..b7f5b98
--- /dev/null
+++ b/docs/nested-player-frame-targeting.md
@@ -0,0 +1,212 @@
+# Targeting a nested cross-origin player without `webNavigation` (open)
+
+> **Status:** Largely fixed, one confirmed defect still open — see
+> [Open: a dead frame election is never released](#open-a-dead-frame-election-is-never-released).
+> Everything under *Fixed* 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.
+
+---
+
+## Open: a dead frame election is never released
+
+**Reported:** 2026-08-18, against the build at `e0c6865`.
+
+Symptom in the dev panel:
+
+```
+Kommunikation mit dem Tab-Video fehlgeschlagen.
+(Could not establish connection. Receiving end does not exist.)
+```
+
+with `targetReady: true`, `Video Count: 0`, `In Iframe: NO`, and no activation errors in
+the log.
+
+### What is verified
+
+- `targetReady` is true, so activation completed and the tab selection is intact.
+- The error is the raw failure of `chrome.tabs.sendMessage` to the **elected frame**:
+  nothing is listening there.
+- Kodik rebuilds and renavigates its player frame, which invalidates the `documentId` the
+  election is pinned to.
+
+### Root cause (verified by reading, not yet by instrumentation)
+
+`getReadyTabVideoState()` recovers via
+`refreshCurrentMediaTarget(tabId, { onlyIfTargetMoved: true })`. On a page with no
+reachable video, `selectedMediaTargetMoved()` returns `false`, the refresh reports
+`unchanged`, and **the stale `currentTargetFrameId` / `currentTargetDocumentId` are kept**.
+The second read fails identically and the error is returned.
+
+`adoptReportingFrame()` compounds it: adoption sets `currentTargetHasVideo = true`, and
+once that is true `selectedMediaTargetMoved()` only moves on a frame/document *change*. If
+the adopted frame then dies, there is no path back.
+
+### Intended fix
+
+When the content script in the elected frame is provably unreachable
+(`Receiving end does not exist`, `No document with id`), the election is invalid: reset
+the **frame** election to the top frame with `hasVideo: false` — never the tab selection —
+so ordinary discovery and adoption can find the player again. Apply it in both places that
+see the error: `getReadyTabVideoState()` and the connection-error branch of
+`_routeToContentInternal()`.
+
+---
+
+## 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.