From 36e1291d2c10303d5b3f4c210c6b172923c416c9 Mon Sep 17 00:00:00 2001
From: KoalaDev <6156589+Shik3i@users.noreply.github.com>
Date: Fri, 14 Aug 2026 07:23:12 +0200
Subject: [PATCH] feat: rank player candidates by ordered signals, add browser
 E2E suite

The weighted score summed incomparable units, so size could outvote traits
that disqualify an element outright. Measured on a real page: a display:none
preload reports its full 1080p intrinsic size and scored 2073600, beating a
visible unmuted player at 509920.

Selection now compares an ordered list of signals, highest priority first:
has a source, is rendered, is not a silent background loop, rendered size
bucket, is playing, has controls, duration. Rendered size replaces intrinsic
resolution, and mute state is gone from the ranking entirely: it is a viewer
preference, not evidence about which element is the player.

It stays a ranking rather than a filter, so a page of only bad candidates
still yields one and findVideo never returns null where a video exists.

The new tests/e2e suite runs the shipped finder against real fixture pages
and drives the packed extension for injection, reinjection and remote
play/pause/seek into a first-party frame. All five scoring scenarios fail
against the previous implementation.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .github/workflows/ci.yml                      |  29 ++++
 .gitignore                                    |   5 +
 docs/CHANGELOG.md                             |   5 +
 docs/ROADMAP.md                               |  11 +-
 extension/content.js                          | 100 +++++++++---
 package.json                                  |   2 +
 scripts/test-content-video-finder.cjs         |  28 +++-
 tests/e2e/README.md                           |  63 ++++++++
 tests/e2e/detection.spec.mjs                  |  86 +++++++++++
 tests/e2e/extension.spec.mjs                  | 143 ++++++++++++++++++
 tests/e2e/fixture-server.mjs                  |  72 +++++++++
 tests/e2e/fixtures/media/ad-360p-5s.mp4       | Bin 0 -> 3152 bytes
 tests/e2e/fixtures/media/loop-720p-3s.mp4     | Bin 0 -> 3203 bytes
 tests/e2e/fixtures/media/player-1080p-30s.mp4 | Bin 0 -> 26431 bytes
 tests/e2e/fixtures/media/player-480p-12s.mp4  | Bin 0 -> 5873 bytes
 tests/e2e/fixtures/pages/ad-frame.html        |   7 +
 tests/e2e/fixtures/pages/background-loop.html |  13 ++
 tests/e2e/fixtures/pages/frames/ad-frame.html |   7 +
 .../fixtures/pages/frames/player-frame.html   |   5 +
 tests/e2e/fixtures/pages/hidden-preload.html  |   9 ++
 tests/e2e/fixtures/pages/iframe-player.html   |   6 +
 tests/e2e/fixtures/pages/late-frame.html      |  16 ++
 tests/e2e/fixtures/pages/multi-player.html    |  11 ++
 tests/e2e/fixtures/pages/muted-player.html    |   8 +
 tests/e2e/fixtures/pages/ready.js             |  51 +++++++
 tests/e2e/fixtures/pages/shadow-player.html   |  19 +++
 tests/e2e/fixtures/pages/simple-player.html   |   6 +
 tests/e2e/fixtures/pages/sourceless.html      |   9 ++
 tests/e2e/helpers/content-source.mjs          |  65 ++++++++
 tests/e2e/playwright.config.mjs               |  34 +++++
 30 files changed, 781 insertions(+), 29 deletions(-)
 create mode 100644 tests/e2e/README.md
 create mode 100644 tests/e2e/detection.spec.mjs
 create mode 100644 tests/e2e/extension.spec.mjs
 create mode 100644 tests/e2e/fixture-server.mjs
 create mode 100644 tests/e2e/fixtures/media/ad-360p-5s.mp4
 create mode 100644 tests/e2e/fixtures/media/loop-720p-3s.mp4
 create mode 100644 tests/e2e/fixtures/media/player-1080p-30s.mp4
 create mode 100644 tests/e2e/fixtures/media/player-480p-12s.mp4
 create mode 100644 tests/e2e/fixtures/pages/ad-frame.html
 create mode 100644 tests/e2e/fixtures/pages/background-loop.html
 create mode 100644 tests/e2e/fixtures/pages/frames/ad-frame.html
 create mode 100644 tests/e2e/fixtures/pages/frames/player-frame.html
 create mode 100644 tests/e2e/fixtures/pages/hidden-preload.html
 create mode 100644 tests/e2e/fixtures/pages/iframe-player.html
 create mode 100644 tests/e2e/fixtures/pages/late-frame.html
 create mode 100644 tests/e2e/fixtures/pages/multi-player.html
 create mode 100644 tests/e2e/fixtures/pages/muted-player.html
 create mode 100644 tests/e2e/fixtures/pages/ready.js
 create mode 100644 tests/e2e/fixtures/pages/shadow-player.html
 create mode 100644 tests/e2e/fixtures/pages/simple-player.html
 create mode 100644 tests/e2e/fixtures/pages/sourceless.html
 create mode 100644 tests/e2e/helpers/content-source.mjs
 create mode 100644 tests/e2e/playwright.config.mjs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8e4d203..8383631 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -46,3 +46,32 @@ jobs:
 
       - name: Run verification suite
         run: npm run verify
+
+  e2e:
+    # Kept separate from `verify`: this job needs a downloaded browser, so a
+    # failure here should read as "the browser flow broke", not as a broken
+    # lint or unit run. `verify` stays usable offline and in the release job.
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: package-lock.json
+
+      - name: Install root dependencies
+        run: npm ci
+
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium chromium-headless-shell
+
+      # The extension specs load dist/chrome, so the artifact has to exist.
+      - name: Build the extension
+        run: npm run build:extension
+
+      - name: Run extension E2E smoke tests
+        run: npm run test:e2e
diff --git a/.gitignore b/.gitignore
index e193446..f05187c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,6 +45,11 @@ extension/shared/
 website/www/
 website/.avif-cache.json
 
+# Playwright E2E artifacts (the fixtures themselves are committed)
+test-results/
+playwright-report/
+blob-report/
+
 # Temporary scratch files
 scratch/
 
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 99cd4b1..c8240aa 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -11,6 +11,11 @@ All notable changes to the KoalaSync browser extension and relay server.
 - **Extension: Editable Hide-Clutter list** — Adds a validated, deduplicated domain editor in Settings, prefilled with the shipped blacklist, with a defaults reset and per-device persistence in `chrome.storage.local`. The editor groups entries into your own and the shipped defaults, and only your changes are stored, so domains added to the shipped list in later versions still reach you without overriding what you removed or added. Lists saved by an earlier version are migrated automatically.
 - **Extension: Independent default audio boost** — Adds a configurable `0–20 dB` output gain in half-decibel steps. The boost works with or without the compressor and applies live to the selected video tab.
 
+- **Testing: Browser E2E smoke suite** — Adds a local Playwright suite (`npm run test:e2e`) that runs the shipped video finder against real fixture pages and drives the packed extension end to end: injection into the target tab, reinjection after navigation, and remote play, pause and seek applied to a player inside a first-party frame. Runs as its own CI job so `npm run verify` stays browser-free.
+
+### Changed
+- **Extension: Rebuilt player selection** — Replaces the weighted score with an ordered list of signals, so a video that cannot be the player (no source, not rendered) is never picked just for being large. Rendered size now decides instead of intrinsic resolution, a video that is actually playing wins between equally sized players, silent looping background videos are demoted, and mute state no longer influences the choice at all.
+
 ### Fixed
 - **Extension: Google Drive tab selection** — A broad parent domain in the Hide-Clutter list no longer hides a host that has its own supported player path, so Drive videos stay selectable while the filter is on. An exact entry for the host itself still filters it.
 - **Extension: Debug report frame visibility** — Video counts now include players inside same-origin frames and the report states whether the selected video sits in a frame.
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index a16f712..083c602 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -57,13 +57,12 @@
 - **Possible approach:** Add an opt-in frame bridge (`allFrames: true` injection) where child frames announce detected videos to the top frame, and the top frame routes remote play/pause/seek commands to the active child video. Needs a frame-election rule so ad frames cannot claim the session.
 - **Status:** Same-origin part completed; cross-origin frame bridge still open. Not needed for current Emby behavior.
 
-### Local extension E2E smoke tests
+### Sync a second video source per room
 
-- **Priority:** P2
-- **Category:** Testing / Release Confidence
-- **Background:** The release verification covers unit tests, server integration, syntax, lint, audits, and builds, but it does not currently run a real browser extension flow. A small local E2E smoke suite would catch regressions in content-script injection, tab navigation reinjection, remote seek handling, and iframe player support.
-- **Possible approach:** Add a separate local-only Playwright smoke command that loads the unpacked extension, opens two controlled video pages, and verifies play/pause/seek through the actual extension path. Keep it outside `npm run verify` until it is stable enough for CI.
-- **Status:** Backlog, recommended before larger content-script or frame-bridge changes.
+- **Priority:** P3
+- **Category:** Compatibility / Player Selection
+- **Background:** Detection picks exactly one `<video>` per tab. Pages that legitimately show two players side by side (a lecture feed plus slides, a multi-camera stream) can only ever sync one of them.
+- **Status:** Backlog, no demand yet. Listed so the single-player assumption in the ranking is a recorded decision rather than an accident.
 
 ---
 
diff --git a/extension/content.js b/extension/content.js
index edf99f3..e5e0db3 100644
--- a/extension/content.js
+++ b/extension/content.js
@@ -566,18 +566,21 @@
     }

 

     // --- Helper: find the best video element on the page ---

-    // Prefers larger, visible videos over tiny preview/trailer elements.

+    // Ranks candidates by a fixed order of signals rather than a weighted sum,

+    // so a disqualifying trait (no source, not rendered) can never be outvoted

+    // by sheer size. See pickBestVideo for the order and the reasoning.

     function findVideo(root = document, depth = 0) {

-        const candidates = Array.from(root.querySelectorAll('video'));

+        return pickBestVideo(collectVideoCandidates(root, depth));

+    }

+

+    function collectVideoCandidates(root = document, depth = 0, out = []) {

+        for (const video of root.querySelectorAll('video')) out.push(video);

 

         // Scan likely media hosts even when light-DOM videos exist; many players

         // expose a tiny preview/ad video outside Shadow DOM and the real player inside.

         const potentialHosts = root.querySelectorAll('[id*="player" i], [class*="player" i], [id*="video" i], [class*="video" i], [id*="media" i], [class*="media" i], [id*="stream" i], [class*="stream" i], ytd-player, netflix-player, emby-player, jellyfin-player, video-player');

         for (const el of potentialHosts) {

-            if (el.shadowRoot) {

-                const found = findVideo(el.shadowRoot, depth);

-                if (found) candidates.push(found);

-            }

+            if (el.shadowRoot) collectVideoCandidates(el.shadowRoot, depth, out);

         }

 

         // Same-origin player frames (jkanime.net and similar) keep the real

@@ -589,28 +592,81 @@
                 let frameDoc = null;

                 try { frameDoc = frame.contentDocument; } catch (_e) { frameDoc = null; }

                 if (!frameDoc || typeof frameDoc.querySelectorAll !== 'function') continue;

-                const found = findVideo(frameDoc, depth + 1);

-                if (found) candidates.push(found);

+                collectVideoCandidates(frameDoc, depth + 1, out);

             }

         }

 

-        if (candidates.length === 0) return null;

+        return out;

+    }

 

-        // Multiple videos found → pick the best one

-        if (candidates.length === 1) return candidates[0];

+    // Rendered size in CSS pixels. Intrinsic resolution (videoWidth) is

+    // deliberately not used here: a display:none element still reports its full

+    // intrinsic size, which let hidden preloads outrank the visible player.

+    function getRenderedVideoArea(video) {

+        return (video.offsetWidth || 0) * (video.offsetHeight || 0);

+    }

 

+    // Coarse size steps, so two players of roughly the same size tie and the

+    // playback signal decides between them instead of a few stray pixels.

+    function getVideoSizeBucket(video) {

+        return Math.round(Math.sqrt(getRenderedVideoArea(video)) / 40);

+    }

+

+    function isVideoRendered(video) {

+        // A non-zero box is proof enough, and it also covers position:fixed

+        // players, whose offsetParent is null even though they are on screen.

+        if (getRenderedVideoArea(video) > 0) return true;

+        return video.offsetParent !== null && video.offsetParent !== undefined;

+    }

+

+    function hasPlayableVideoSource(video) {

+        if (video.currentSrc || video.src || video.srcObject) return true;

+        // <source> children count before the browser has committed to one.

+        return typeof video.querySelector === 'function' && !!video.querySelector('source[src]');

+    }

+

+    // Marketing hero pattern: silent, endlessly looping, no controls. Often the

+    // largest video on the page and never the one two people sit down to watch.

+    function isBackgroundVideo(video) {

+        return !!video.loop && !!video.muted && !video.controls;

+    }

+

+    function isVideoPlaying(video) {

+        return video.paused === false && video.ended !== true;

+    }

+

+    // Highest priority first. Every signal is a plain number and they are

+    // compared one after another, so an earlier signal is never traded off

+    // against a later one. Mute state is intentionally absent: it is a viewer

+    // preference, not evidence about which element is the real player.

+    const VIDEO_RANKING_SIGNALS = [

+        video => (hasPlayableVideoSource(video) ? 1 : 0),

+        video => (isVideoRendered(video) ? 1 : 0),

+        video => (isBackgroundVideo(video) ? 0 : 1),

+        video => getVideoSizeBucket(video),

+        video => (isVideoPlaying(video) ? 1 : 0),

+        video => (video.controls ? 1 : 0),

+        video => (video.duration && isFinite(video.duration) ? video.duration : 0)

+    ];

+

+    function compareVideoRanks(a, b) {

+        for (let i = 0; i < a.length; i++) {

+            if (a[i] !== b[i]) return a[i] > b[i] ? 1 : -1;

+        }

+        return 0;

+    }

+

+    // Ranking, not filtering: even an all-bad candidate set still yields the

+    // least bad element, so this never returns null where a video exists.

+    function pickBestVideo(candidates) {

         let best = null;

-        let bestScore = -1;

-        for (const v of candidates) {

-            if (v.tagName !== 'VIDEO') continue;

-            // Score: visible area + bonus for unmuted + bonus for longer duration

-            const area = (v.videoWidth || v.offsetWidth || 0) * (v.videoHeight || v.offsetHeight || 0);

-            const unmutedBonus = v.muted ? 0 : 100000;

-            const durationBonus = (v.duration && isFinite(v.duration) ? v.duration : 0) * 100;

-            const score = area + unmutedBonus + durationBonus;

-            if (score > bestScore) {

-                bestScore = score;

-                best = v;

+        let bestRank = null;

+        for (const video of candidates) {

+            if (!video || video.tagName !== 'VIDEO') continue;

+            const rank = VIDEO_RANKING_SIGNALS.map(signal => signal(video));

+            if (!best || compareVideoRanks(rank, bestRank) > 0) {

+                best = video;

+                bestRank = rank;

             }

         }

         return best;

diff --git a/package.json b/package.json
index f95c526..7aa12a0 100644
--- a/package.json
+++ b/package.json
@@ -14,6 +14,8 @@
     "lint:fix": "eslint . --fix",
     "subset-flags": "node website/tools/subset-flag-font.mjs",
     "test": "npm run verify",
+    "test:e2e": "playwright test --config tests/e2e/playwright.config.mjs",
+    "test:e2e:install": "playwright install chromium chromium-headless-shell",
     "test:unit": "vitest run",
     "verify": "node scripts/verify-release.mjs"
   },
diff --git a/scripts/test-content-video-finder.cjs b/scripts/test-content-video-finder.cjs
index 7faadc9..b292724 100644
--- a/scripts/test-content-video-finder.cjs
+++ b/scripts/test-content-video-finder.cjs
@@ -61,7 +61,33 @@ const fakeDocument = {
   }
 };
 
-const fnSource = extractFunction('findVideo', source);
+// findVideo delegates to a small set of ranking helpers; they have to be lifted
+// together or this would silently test a stale shape of the finder.
+const VIDEO_FINDER_PARTS = [
+  'findVideo',
+  'collectVideoCandidates',
+  'getRenderedVideoArea',
+  'getVideoSizeBucket',
+  'isVideoRendered',
+  'hasPlayableVideoSource',
+  'isBackgroundVideo',
+  'isVideoPlaying',
+  'compareVideoRanks',
+  'pickBestVideo'
+];
+
+function extractRankingTable(text) {
+  const start = text.indexOf('const VIDEO_RANKING_SIGNALS');
+  assert.notStrictEqual(start, -1, 'VIDEO_RANKING_SIGNALS not found');
+  const end = text.indexOf('];', start);
+  assert.notStrictEqual(end, -1, 'VIDEO_RANKING_SIGNALS did not terminate');
+  return text.slice(start, end + 2);
+}
+
+const fnSource = [
+  ...VIDEO_FINDER_PARTS.map(name => extractFunction(name, source)),
+  extractRankingTable(source)
+].join('\n');
 const findVideo = Function('document', `${fnSource}; return findVideo;`)(fakeDocument);
 
 const selected = findVideo(fakeDocument);
diff --git a/tests/e2e/README.md b/tests/e2e/README.md
new file mode 100644
index 0000000..b15a2c1
--- /dev/null
+++ b/tests/e2e/README.md
@@ -0,0 +1,63 @@
+# Extension E2E smoke tests
+
+Browser-level tests for the parts that unit tests cannot reach: which `<video>`
+the extension picks on a real page, and whether the packed extension gets far
+enough to control it.
+
+```bash
+npm run test:e2e:install   # once, downloads the browsers
+npm run build:extension    # extension.spec.mjs loads dist/chrome
+npm run test:e2e
+```
+
+## Layout
+
+| Path | Purpose |
+| :--- | :--- |
+| `detection.spec.mjs` | Runs the shipped `findVideo()` against the fixture pages |
+| `extension.spec.mjs` | Loads `dist/chrome`, injects into a tab, applies remote play/pause/seek |
+| `fixture-server.mjs` | Static server for the fixtures, with byte-range support for media |
+| `fixtures/pages/` | One page per scenario |
+| `fixtures/media/` | Small generated clips (see below) |
+| `helpers/content-source.mjs` | Lifts the real finder out of `extension/content.js` |
+
+## Two rules worth keeping
+
+**The specs run the shipped source, not a copy.** `helpers/content-source.mjs`
+extracts `findVideo` and its ranking helpers straight out of
+`extension/content.js`. A fixture that passes against a reimplementation would
+prove nothing about the extension. If you split the finder into more functions,
+add them to `VIDEO_FINDER_EXPORTS` there and to `VIDEO_FINDER_PARTS` in
+`scripts/test-content-video-finder.cjs`, or the extraction fails loudly.
+
+**Each fixture marks its own answer.** The element that must win carries
+`data-expected`; videos that have to be playing carry `data-autoplay`, and
+`ready.js` holds the page back until metadata and playback have settled. The
+specs assert those preconditions before judging the finder, so a broken fixture
+reads as a broken fixture instead of a scoring regression.
+
+## Scenarios
+
+| Fixture | What it pins down |
+| :--- | :--- |
+| `simple-player.html` | The ordinary case |
+| `iframe-player.html` | Player inside a same-origin frame, empty top document |
+| `late-frame.html` | Player frame attached after the page settled |
+| `shadow-player.html` | Player in a shadow root, tiny teaser in the light DOM |
+| `muted-player.html` | Mute must not disqualify the only player |
+| `hidden-preload.html` | A `display:none` preload still reports 1080p; it must lose |
+| `ad-frame.html` | 1080p asset in a 300x250 ad slot must lose to the real player |
+| `background-loop.html` | Silent looping hero must lose despite being the largest |
+| `multi-player.html` | Between equal players, the playing one wins |
+| `sourceless.html` | A large `<video>` with no source can never be the player |
+
+## Regenerating the media
+
+Solid-colour clips, a few KB each, committed so the suite needs no network:
+
+```bash
+ffmpeg -y -f lavfi -i "color=c=blue:s=1920x1080:d=30:r=10" -c:v libx264 -preset veryfast -crf 45 -pix_fmt yuv420p -movflags +faststart fixtures/media/player-1080p-30s.mp4
+```
+
+Same command with `green/854x480/12`, `red/640x360/5` and `gray/1280x720/3` for
+the other three.
diff --git a/tests/e2e/detection.spec.mjs b/tests/e2e/detection.spec.mjs
new file mode 100644
index 0000000..bd47118
--- /dev/null
+++ b/tests/e2e/detection.spec.mjs
@@ -0,0 +1,86 @@
+import { test, expect } from '@playwright/test';
+import { buildVideoFinderScript } from './helpers/content-source.mjs';
+
+/**
+ * Runs the shipped findVideo() against real pages in a real browser, where
+ * videoWidth, offsetParent, paused and duration all carry their true values.
+ * Each fixture marks the element that must win with data-expected.
+ */
+
+const SCENARIOS = [
+    { page: 'simple-player.html', expected: 'player', what: 'the only visible player' },
+    { page: 'iframe-player.html', expected: 'framed-player', what: 'a player inside a same-origin frame' },
+    { page: 'shadow-player.html', expected: 'shadow-player', what: 'a player inside a shadow root over a light-DOM teaser' },
+    { page: 'muted-player.html', expected: 'player', what: 'the only player even when muted' },
+    { page: 'hidden-preload.html', expected: 'player', what: 'the visible player over a hidden higher-resolution preload' },
+    { page: 'ad-frame.html', expected: 'player', what: 'the real player over a muted ad in a first-party frame' },
+    { page: 'background-loop.html', expected: 'player', what: 'the real player over a large looping background video' },
+    { page: 'multi-player.html', expected: 'watched', what: 'the player that is actually playing' },
+    { page: 'sourceless.html', expected: 'player', what: 'the real player over a large sourceless placeholder' }
+];
+
+test.describe('video detection', () => {
+    for (const { page: fixture, expected, what } of SCENARIOS) {
+        test(`picks ${what} (${fixture})`, async ({ page }) => {
+            await page.goto(`/pages/${fixture}`);
+            await page.waitForFunction(() => window.__fixtureReady === true);
+
+            // Assert the fixture is in the state it claims before judging the
+            // finder, so a broken fixture never reads as a scoring regression.
+            const preconditions = await page.evaluate(() => {
+                const videos = [];
+                const walk = (doc) => {
+                    for (const v of doc.querySelectorAll('video')) videos.push(v);
+                    for (const f of doc.querySelectorAll('iframe')) {
+                        try { if (f.contentDocument) walk(f.contentDocument); } catch (_e) { /* cross-origin */ }
+                    }
+                    for (const el of doc.querySelectorAll('*')) if (el.shadowRoot) walk(el.shadowRoot);
+                };
+                walk(document);
+                return videos
+                    .filter(v => v.dataset.autoplay !== undefined)
+                    .map(v => ({ id: v.id, paused: v.paused, ended: v.ended }));
+            });
+            for (const video of preconditions) {
+                expect(video.paused, `fixture video ${video.id} should be playing`).toBe(false);
+                expect(video.ended, `fixture video ${video.id} should not have ended`).toBe(false);
+            }
+
+            await page.addScriptTag({ content: buildVideoFinderScript() });
+
+            const picked = await page.evaluate(() => {
+                const video = window.__koalaFindVideo();
+                if (!video) return null;
+                return {
+                    id: video.id,
+                    expected: video.dataset.expected !== undefined,
+                    inFrame: video.ownerDocument !== document
+                };
+            });
+
+            expect(picked, 'a video must be found at all').not.toBeNull();
+            expect(picked.id).toBe(expected);
+            expect(picked.expected, `${picked.id} is not the element marked data-expected`).toBe(true);
+        });
+    }
+
+    test('finds a player frame that is attached later (late-frame.html)', async ({ page }) => {
+        await page.goto('/pages/late-frame.html');
+        await page.addScriptTag({ content: buildVideoFinderScript() });
+
+        // Nothing to find while the slot is still empty.
+        expect(await page.evaluate(() => window.__koalaFindVideo() === null)).toBe(true);
+
+        await page.waitForFunction(() => {
+            const video = window.__koalaFindVideo();
+            return !!video && video.readyState >= 1;
+        });
+        expect(await page.evaluate(() => window.__koalaFindVideo().id)).toBe('framed-player');
+    });
+
+    test('returns null on a page without any video', async ({ page }) => {
+        await page.setContent('<h1>no media here</h1>');
+        await page.addScriptTag({ content: buildVideoFinderScript() });
+        expect(await page.evaluate(() => window.__koalaFindVideo())).toBeNull();
+    });
+});
diff --git a/tests/e2e/extension.spec.mjs b/tests/e2e/extension.spec.mjs
new file mode 100644
index 0000000..dfff3ff
--- /dev/null
+++ b/tests/e2e/extension.spec.mjs
@@ -0,0 +1,143 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { test as base, expect, chromium } from '@playwright/test';
+
+/**
+ * Drives the packed extension itself: real background service worker, real
+ * chrome.scripting injection, real runtime messaging. The detection specs cover
+ * which element gets picked; this file covers whether the extension ever gets
+ * far enough to pick one.
+ */
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const extensionPath = path.join(repoRoot, 'dist/chrome');
+
+const test = base.extend({
+    context: async ({}, use) => {
+        if (!fs.existsSync(path.join(extensionPath, 'manifest.json'))) {
+            throw new Error('dist/chrome is missing. Run: npm run build:extension');
+        }
+        const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'koalasync-e2e-'));
+        const context = await chromium.launchPersistentContext(userDataDir, {
+            // The headless shell does not run MV3 service workers; the full
+            // Chromium build in new headless mode does.
+            channel: 'chromium',
+            headless: true,
+            args: [
+                `--disable-extensions-except=${extensionPath}`,
+                `--load-extension=${extensionPath}`,
+                '--autoplay-policy=no-user-gesture-required'
+            ]
+        });
+        await use(context);
+        await context.close();
+        fs.rmSync(userDataDir, { recursive: true, force: true });
+    },
+    extensionId: async ({ context }, use) => {
+        let [worker] = context.serviceWorkers();
+        if (!worker) worker = await context.waitForEvent('serviceworker');
+        await use(worker.url().split('/')[2]);
+    }
+});
+
+/** Runs code in an extension page, where the privileged chrome.* APIs exist. */
+async function withExtensionPage(context, extensionId, fn) {
+    const page = await context.newPage();
+    await page.goto(`chrome-extension://${extensionId}/popup.html`);
+    const result = await fn(page);
+    await page.close();
+    return result;
+}
+
+async function selectTargetTab(context, extensionId, pageUrl) {
+    return withExtensionPage(context, extensionId, page => page.evaluate(async (url) => {
+        const [tab] = await chrome.tabs.query({ url });
+        if (!tab) throw new Error(`no tab matched ${url}`);
+        const response = await chrome.runtime.sendMessage({ type: 'SET_TARGET_TAB', tabId: tab.id });
+        return { tabId: tab.id, response };
+    }, pageUrl));
+}
+
+async function sendServerCommand(context, extensionId, tabId, action, payload) {
+    return withExtensionPage(context, extensionId, page => page.evaluate(async ({ tabId, action, payload }) => {
+        return chrome.tabs.sendMessage(tabId, {
+            type: 'SERVER_COMMAND',
+            action,
+            payload,
+            actionTimestamp: Date.now(),
+            commandSenderId: 'e2e'
+        });
+    }, { tabId, action, payload }));
+}
+
+test('injects into the target tab and attaches to a same-origin frame player', async ({ context, extensionId, baseURL }) => {
+    const url = `${baseURL}/pages/iframe-player.html`;
+    const page = await context.newPage();
+    await page.goto(url);
+    await page.waitForFunction(() => window.__fixtureReady === true);
+
+    const { response } = await selectTargetTab(context, extensionId, url);
+    expect(response?.status, 'SET_TARGET_TAB should not report a failure').not.toBe('error');
+
+    await expect.poll(
+        () => page.evaluate(() => {
+            const video = document.querySelector('iframe').contentDocument.querySelector('video');
+            return video ? video.dataset.koalaAttached : null;
+        }),
+        { message: 'content script should attach to the video inside the frame' }
+    ).toBe('true');
+});
+
+test('applies remote play, pause and seek to the framed player', async ({ context, extensionId, baseURL }) => {
+    const url = `${baseURL}/pages/iframe-player.html`;
+    const page = await context.newPage();
+    await page.goto(url);
+    await page.waitForFunction(() => window.__fixtureReady === true);
+
+    const { tabId } = await selectTargetTab(context, extensionId, url);
+    await expect.poll(() => page.evaluate(() => {
+        const video = document.querySelector('iframe').contentDocument.querySelector('video');
+        return video ? video.dataset.koalaAttached : null;
+    })).toBe('true');
+
+    await sendServerCommand(context, extensionId, tabId, 'play');
+    await expect.poll(() => page.evaluate(FRAMED_VIDEO_PAUSED), { message: 'remote play should start playback' }).toBe(false);
+
+    await sendServerCommand(context, extensionId, tabId, 'pause');
+    await expect.poll(() => page.evaluate(FRAMED_VIDEO_PAUSED), { message: 'remote pause should stop playback' }).toBe(true);
+
+    await sendServerCommand(context, extensionId, tabId, 'seek', { targetTime: 6 });
+    await expect.poll(
+        () => page.evaluate(() => document.querySelector('iframe').contentDocument.querySelector('video').currentTime),
+        { message: 'remote seek should move the framed player' }
+    ).toBeGreaterThan(5);
+});
+
+test('reinjects after the target tab navigates', async ({ context, extensionId, baseURL }) => {
+    const first = `${baseURL}/pages/iframe-player.html`;
+    const page = await context.newPage();
+    await page.goto(first);
+    await page.waitForFunction(() => window.__fixtureReady === true);
+    await selectTargetTab(context, extensionId, first);
+    await expect.poll(() => page.evaluate(() => {
+        const video = document.querySelector('iframe').contentDocument.querySelector('video');
+        return video ? video.dataset.koalaAttached : null;
+    })).toBe('true');
+
+    await page.goto(`${baseURL}/pages/simple-player.html`);
+    await page.waitForFunction(() => window.__fixtureReady === true);
+
+    await expect.poll(
+        () => page.evaluate(() => {
+            const video = document.getElementById('player');
+            return video ? video.dataset.koalaAttached : null;
+        }),
+        { message: 'the content script should come back after a navigation' }
+    ).toBe('true');
+});
+
+function FRAMED_VIDEO_PAUSED() {
+    return document.querySelector('iframe').contentDocument.querySelector('video').paused;
+}
diff --git a/tests/e2e/fixture-server.mjs b/tests/e2e/fixture-server.mjs
new file mode 100644
index 0000000..b608a4b
--- /dev/null
+++ b/tests/e2e/fixture-server.mjs
@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Static file server for the E2E fixtures. Local only, no directory listing,
+ * paths are resolved and then checked to stay inside the fixture root.
+ */
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'fixtures');
+const port = Number(process.argv[2] || 4173);
+
+const TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mp4': 'video/mp4',
+    '.json': 'application/json'
+};
+
+const server = http.createServer((req, res) => {
+    const requested = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
+    const filePath = path.resolve(root, `.${requested}`);
+
+    if (!filePath.startsWith(root + path.sep)) {
+        res.writeHead(403).end('forbidden');
+        return;
+    }
+
+    fs.stat(filePath, (statErr, stat) => {
+        if (statErr || !stat.isFile()) {
+            res.writeHead(404).end('not found');
+            return;
+        }
+
+        const contentType = TYPES[path.extname(filePath)] || 'application/octet-stream';
+        // Media needs byte ranges: without them Chromium reports an empty
+        // seekable range and seeking silently does nothing, which would make
+        // the remote-seek test fail for a reason that has nothing to do with
+        // the extension.
+        const range = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range || '');
+        if (range) {
+            const start = range[1] ? Number(range[1]) : 0;
+            const end = range[2] ? Number(range[2]) : stat.size - 1;
+            if (Number.isNaN(start) || Number.isNaN(end) || start > end || end >= stat.size) {
+                res.writeHead(416, { 'Content-Range': `bytes */${stat.size}` }).end();
+                return;
+            }
+            res.writeHead(206, {
+                'Content-Type': contentType,
+                'Content-Length': end - start + 1,
+                'Content-Range': `bytes ${start}-${end}/${stat.size}`,
+                'Accept-Ranges': 'bytes',
+                'Cache-Control': 'no-store'
+            });
+            fs.createReadStream(filePath, { start, end }).pipe(res);
+            return;
+        }
+
+        res.writeHead(200, {
+            'Content-Type': contentType,
+            'Content-Length': stat.size,
+            'Accept-Ranges': 'bytes',
+            'Cache-Control': 'no-store'
+        });
+        fs.createReadStream(filePath).pipe(res);
+    });
+});
+
+server.listen(port, '127.0.0.1', () => {
+    console.log(`fixture server on http://localhost:${port}`);
+});
diff --git a/tests/e2e/fixtures/media/ad-360p-5s.mp4 b/tests/e2e/fixtures/media/ad-360p-5s.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..b99930623095b3ec6d029eda14ed308971c9bcf3
GIT binary patch
literal 3152
zcmeHJU1%It6uz4@TE&{yrlm+~uNcvX>}F=NyRDI--Ns-ZDu`eoq%ho>xtkd>voo2Q
zB)jcHtBCepEZ9QQ2Y*nih#-Bj7_p%E=#!NS>5EzvTkxetBz|XRvYkx}BBJ=<WoOR0
z-#O>I=iYPgon?&iX3`1WIPe+kV<hotV!=}Vu&OdP@R}b43yd+(UvO;5LhJvLvF#^W
ziP7&?>*)aA&_8g?^G;eHW1B7{k(h<?NHUv_*<WzX*)Z<Lwqcw*joWtu={RZNh_sU!
z+OYKEB&Pxc@ovs@-c<8#SHQ-7d*j?62mB>_{$d(gc5E-oIoN`0%XOXPVf2G((Xu^B
zKK-k{+iF4?TJTfSV%j5iW*fF6Nj}ube&2lL@l5YO8z-g*eI-uf^@5Pkhg393YDLZz
z=sSUFPeY}LT4~22_}8_Hwy&Zp8uwhYt<|fUF@5h^TZ62_YqDgsooiRvgENrlE*&^K
zb~D_Dnb0u(Y-n(2`BaGwIM-g>JNo;L8x*`X6mbYidC)UtCQ-h~_Z~x^+O9ZB3qU&g
zXed1CLzov8hFTt9I&0nXg&*N4QYwdXx!$KP*;6ja|Lxg&{8Q_b@(!bBR=V=tno&K|
z`dx<YXl^3`y#E2n?Rc<@x(^kqi2c|4lv^=B(y>>q0FoN^+Q8?K=DeK<$QOK>O0qp%
zydZF?L?R6740l`E&2FJb-%SD{+--|A7^IBhq&9I<Rs0lM)y>UF;)=QJbst{1wm-OQ
zU~TQa%Tre`e1B>B{Hf7z_@zgFxkksCm$?;0lB@L^kH$4k<K}p+uG9n!(-k<3J@f3;
z)8#5}9G--yEiD)(gRtYtX2LZ^882&!Rs-lHNjNb!wz#-hp$jhXM5_`+Gh;ML#Yub*
zK0%ncK`Wl%mN12-s~ndY-nKNoz?#+731vdzq9wdeEOn(lKB2T#b)5TBcVwH#^CmQn
zhj9l%cpH(es}%)7cyZrtOWPnu=+cNpYewp7om);6_`*P_%9BWXo*TnsUwfZzC4j6s
zA6;7t`)JSty*jF@yeZ<u2;*5dB#(?>E;NE>GnNV56DLAIti#m{f?469XRL!7k3H8y
zF6)58TTwcO<@zF_Jls|yBTv8yxarMDqGMQr9||J3utfO2xh+t@F%sm{jD#;^eVm&{
z*n#faSP9b*wg_n!reV5*=7p^z(|IjQcg9If*n&{DjF}*WH3Ml<v$6wjU8^a%YT&D*
zs|t@T*^<_LqE{74GZM6<k&GRLN0!l@F8M~5ZbeP*<MNg?Ep+s1t)lQbnvAYg>QF->
zPNit;^(O$ti465BcS95j8v-@NSYi(Kr)shj*uh8S$(Px-wXa`&`{(07+;sN8`Rf;t
zDHq@W=oqIj3VxG)tag3N^}8#ZoE*vUKY!oz2KWaXr$=_Zv?mXZRsd~jEFC<!8=o}r
z56=-$S`ts~&44|t8DMpRD*(1OPCL~@jlp%A&wvd!mR_0KHu_{Q(OW%nV1B0y5HpC*
z6^T|dqOYcQY$Uqc69=N7dH@hzFA`-LE#H3|(Q>&PM>E+{S{~~Hs{pn(&Qyy;E5HUD
z%g^0TG}jXcqPPbDQM*W#XLPDSM1KSj_i;Ba&**#)0HRNdM0rNv7KpN{E#K_Mt!B)>
zbpc`q(Q1(>%V_DL0#TOHlHQHWh?e$ufsE+%NRem-<S75a0@2^xN4J&#-`YnwAJ|8e
apJqF|gdI-R|LfamuyIBO&+(k+yFUOq9Vzkv

literal 0
HcmV?d00001

diff --git a/tests/e2e/fixtures/media/loop-720p-3s.mp4 b/tests/e2e/fixtures/media/loop-720p-3s.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..2a9165d55cb9ba0275fe10197bc97d79fcfa1f37
GIT binary patch
literal 3203
zcmdT`PiP!f7=N2IwbWu8NFkNfzQ$AwCYzbb?lwjSvQ2|IR49TKL>S-9yv+`o*_q5t
zlHFcRRm6km9$Ls+Mf^jNUZe$E?4gIE2n8=jyy!tJf~|O|lp25E%qCewGwG!VAM@t>
z-uM09_x;}Y-kV*<7_Y>Qz=?d1u?|KOT@&+`>IDUrv27oDzCX_xbG`Yh4cXQ@e`D<N
z%Phy}S#SRtz`S8RzK(p5*1=fkcX23Y;CwxvNpg0!0b9|KcVpX-=RtY9FsI{YGI2oK
zaRjYTx>4K;g$NXPM~idkq-Q$<KJM8Y*M1o0I(y}MGIOYEyJ0H^n|Exvs*^m4u|Fkh
zwkrwKamRCN6(~LPUJ|sO_JE!G`s`2=h8p>I&4n&c^^S{CY`V~|MRBycA%wX|n+8d(
zJ!WF)qGeA(rA{rk_c-t+Ew7E{RYl{jW7f4&A$2D2-jx-|5>OL4n;lsBnLRlTd0~0{
zMAuijJ=i8juiW^bZ|{2}$GWPwPahe)fA=m;-V=x@fFvH&d(1d&6}e{-V`{xooNNH;
zgn0^wjr1O@i#CQ@YkrPd>sa8(j!jBrPfM<jX-NJg7UcikpRB77HL;SFt<{9;mDJ~b
z_)fKaBw+764S5KCpshaxo%*WnQH-&7mX93NXb--JH0SJCK)&Y5M3V1d`-Q<J3q=sn
znO<u{PI@a3eHQx^aK9~*$q33APHqJ!SH+`f81JZr5?AiA%N|g;VP9<TT3Px0r^#Da
ze_fusbY}1ezWnqbx9NEEA#VAh<Z7wN!x2r>xH(cRDMbOtR33ogmrhK+I8@-}lM_JN
z(t=~c4;rql#9UL9ks(ddiZE8=I2aoqURYSj(}nk4QOo<`^e|<~S7Xlw#t&l0uSH|r
z5~i?pmE%(5ZA;Vjtr=Y%Q^pi7YQk+qQdjCDV@h3BN4O{Ts;u*9&V;7%AZlO|-bQHa
zYF@!4ytwDorEO3|=+X#9ZCdJTiCfjs_k@9|Dvv|yx=sYdXnoYSVwkL14?|lD`;=cp
zcy&-!c|}CA5kxaiK!`NJY+(46N+e^z<7$Wrk**fG>-#gJijlEuEb_>8EO1#hD7+RX
zIV{H$G4XI}u?$@S5bUNq7m9{q`CcF>xP=nod+*c`0>DrZrV<KIM*0Xhji3SDu~7-r
z5Vi<t6{cZ2g4TtjBa?M4NN2hloACL8tQpgO0B>rfMa{?tV(VH_X{iRj!n&&P$dWZ_
z&Bb~_A)29}l7=#>VtQy9Ys)2UXz5m1;T}F_l9q*mUMS`jK1++ym3#?mK!Fn}>U!yU
z7@}APdVxCuHVFp;dx%_O7W+@T$rf>fzm@O3!@5_jE5_)v$IkET-(T7N*DoJ_O5fPE
z$GYA%(Y<r=#^q~??bUI1lXYBYI~Un=i|ik^?FKve0lUYxA7*1IqHXS4kVmd8)2HWP
z`RqXNTL;#;Z%DhV7a(3<I(l?Jeq$cYvlC{<b4%jbk<Bsm8wre+g_#DXzkIe@I9}ep
zSu(b3UxHeCcd~o%h0XJ|IDNcTK5+UZ3q!oY=|VOqs#1S>>6^*D55eiyR{6l`_pLDC
zbSIlrTBqg{55uWBl$DS6h3A^XS(vm==L*@J(mFL?eke|}Tjc|%Xe&&A`CL7lQ>#vA
zvN_?;F4f@6tbDCHUD^r*PFD)YC%)eFjQ7z$vi@@O$81jN8E^ibl`p+_&3jpx^xmDj
M4^D4x%1Jx_FNRdxMgRZ+

literal 0
HcmV?d00001

diff --git a/tests/e2e/fixtures/media/player-1080p-30s.mp4 b/tests/e2e/fixtures/media/player-1080p-30s.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..a4974aec5aeb9a01062560fd47d61449cae3f095
GIT binary patch
literal 26431
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

literal 0
HcmV?d00001

diff --git a/tests/e2e/fixtures/media/player-480p-12s.mp4 b/tests/e2e/fixtures/media/player-480p-12s.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..c748f05a63a9ea0ca4dd33c941d95b56b5123299
GIT binary patch
literal 5873
zcmeHJO^6&t6s~bhb_3D;IEjlUvBVWU?96u0U*bxW-K>kNL=e$Eh%nT2*X%UgJ>A>g
zvpW-nsE9u&@n8-K?3`4TAR=f$6e4&Kk9tYe!{!nViU}x^AYuJpcTaYvcfBowFhzIQ
ztM9$~>Q&Y2s>c}PwV>^qzGE|X8>1R;UM%UV?G{zWhQGHRXNfUp*-Lc;bx%qE!dPyV
zr5HWyrLO@v(Vkql+)TQSv7wuRCl;W5Ay^2<O!pYZY#29L660((Zh8*xL_J5P5%{1u
zAT2+LslY(I!?DjpP1`U9blf(QbALD_dhYA6XSQxwUd+LkOha~Ms^`#lW<|rWB-spc
z+icVzWR~oZwAbxXBhno(JV`cGNWZh`Sv-=rulhmNf_&Z&{O*R3&BwH9sHyaFhCq4_
z)1HM$FO}53<FGI1bNM4VRmpS9thVyyVx$beBWr7@%dnbG8EpUBC3ep|>a!OoFKCyq
z?O`lU!=zbe*Z%CO6x&w6`tsqio7b;X=iRRGUDV_Uy_ss@#f!Y-3ACw<_(8Y<B$G{x
zvD-<`U|zH_RO0^WZ}fHB<p{?nh5AffciYsYejyj?fj(M~!TLn&K;bcnkN@uf*iGw=
zLp}T-58&U{2|$VeZTjy?PW=hpiBJ=LfTxc_yc_TSo_7Q?y<Ke3{{OBA&U)R!UQ$5}
z?4XOj+B5=z`gvQ1HR<l}y<l-Ed%|_;4!l*eW^{``_(9+h;Xy-$ohir|Zn_$7Iu(zS
zM|-&DNnFu){AI%m!THhlZEI^E{xoyt%gYyM&z%~(z%M@V`&GIQd6w&rC%IZKaj%fi
z=XteIDk~)c#cU1+<4-+3^LVz%r{<<%X-FN4X~%6_vKH{Xq7<@uC0_zq4+3{$e0+I%
zIY$YCV~Ix2@#e>Alw3WqE!a42U^)$dg6pCxbWP<*0`N6t)pGO&O`T9C6fPRVYWq@C
zT7?OvrK$yPORX+j+;3JP<+<y((Fxy*XJ~3pK_`5Wb+n{WAx6lu;)%w*)YLN9>z-qa
z3c9L1@T6s#J}i#3ju?6XNME$kG^8+2I1SLNW2(w)!VfC0zhJs#5fLo96{lA7WdQS_
z?xBOPsU>bX&Vs0;Rq28S?pvk~U%G(88(uhuZrUOsKg>oTJxjm{c-3lpqFvD)+Z9Bv
zV~LO-nhj9E&=X`+^MoyZt-z}lw+-1euoBgZFoa99s8*_`pm`y5WH_&7Y0lS!Ds+x3
z8<ly-g*F0dQVX&TZY^I@VzGj(O;Z)_>#`yBW}p=na?=yEq@MKa=<ey2Thk?5PuFy>
z#%&}&lBR`*RxITdzDSeNlw292OT=L<T3Y!L0Dd4{t;kImn}mSC9%3x9i2bMCWG^9t
z-;{5>%J!^%_xgLko&5PmUCUkC{m0HHe|+c@O33Khaek70KAC!pZGV>CyV^w~-4=fL
zy$xsXnmRo?^2&WZgB+qmfA7@Fv1133Lw3g-Y7&}S5sw}2L5Fe96RP*4ZJ?Q{)Ai!<
zsa@+7>=5!!;481q>=}Esho#H??nV}Hzu%A2h~Pe(<R-7d{q4-YO}VdZWC8cD8&Pmy
zOL9kkckbMryOZr_q1o?Eb;kSA$nP`7BzNR@=b3-uUfjq6Zhs@1nL5)-a>st3N^(;+
z50+2+Sz^D>ZA8KSMUp%A`-dcV6epb<{VY+ObpGx~qc}OUn&gh-<WQ13@_R+=XNhC*
zXg?aq;AoONj+0|a?k$b)&0}y7-|L4#{Lgm=@!hi~gZLht-|OMfy)Qe1^ZQmB!outX
x_x#}e?pc$q%}=I#QZrWKVP3T*`N?we`1Hx1_<r%Li2EJf#hYZ6ozD_C`adwU0fhhn

literal 0
HcmV?d00001

diff --git a/tests/e2e/fixtures/pages/ad-frame.html b/tests/e2e/fixtures/pages/ad-frame.html
new file mode 100644
index 0000000..8febe8e
--- /dev/null
+++ b/tests/e2e/fixtures/pages/ad-frame.html
@@ -0,0 +1,7 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Ad in a same-origin frame</title>
+<h1>Real player plus a muted autoplay ad in a first-party frame</h1>
+<video id="player" data-expected width="854" height="480" controls data-autoplay src="../media/player-480p-12s.mp4"></video>
+<iframe width="300" height="250" src="frames/ad-frame.html"></iframe>
+<script src="ready.js"></script>
diff --git a/tests/e2e/fixtures/pages/background-loop.html b/tests/e2e/fixtures/pages/background-loop.html
new file mode 100644
index 0000000..663bd5a
--- /dev/null
+++ b/tests/e2e/fixtures/pages/background-loop.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Background hero loop</title>
+<style>
+  body { margin: 0 }
+  #hero { display: block; width: 1280px; height: 720px; object-fit: cover }
+</style>
+<!-- Marketing hero: large, muted, looping, no controls. Bigger than the real
+     player in every dimension the old scoring looked at. -->
+<video id="hero" muted loop data-autoplay src="../media/loop-720p-3s.mp4"></video>
+<h1>Article with an embedded player below the hero</h1>
+<video id="player" data-expected width="640" height="360" controls src="../media/player-480p-12s.mp4"></video>
+<script src="ready.js"></script>
diff --git a/tests/e2e/fixtures/pages/frames/ad-frame.html b/tests/e2e/fixtures/pages/frames/ad-frame.html
new file mode 100644
index 0000000..8af9d6d
--- /dev/null
+++ b/tests/e2e/fixtures/pages/frames/ad-frame.html
@@ -0,0 +1,7 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Ad slot</title>
+<style>body { margin: 0 }</style>
+<!-- A 1080p asset rendered into a small ad slot: intrinsic size and rendered
+     size disagree, which is exactly what the scoring has to get right. -->
+<video id="ad" width="300" height="250" muted loop data-autoplay src="../../media/player-1080p-30s.mp4"></video>
diff --git a/tests/e2e/fixtures/pages/frames/player-frame.html b/tests/e2e/fixtures/pages/frames/player-frame.html
new file mode 100644
index 0000000..99f95b7
--- /dev/null
+++ b/tests/e2e/fixtures/pages/frames/player-frame.html
@@ -0,0 +1,5 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>V</title>
+<style>body { margin: 0 }</style>
+<video id="framed-player" data-expected width="854" height="480" controls src="../../media/player-480p-12s.mp4"></video>
diff --git a/tests/e2e/fixtures/pages/hidden-preload.html b/tests/e2e/fixtures/pages/hidden-preload.html
new file mode 100644
index 0000000..a691d9b
--- /dev/null
+++ b/tests/e2e/fixtures/pages/hidden-preload.html
@@ -0,0 +1,9 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Hidden preload</title>
+<h1>Visible 480p player next to a hidden 1080p preload</h1>
+<!-- The hidden element reports its full intrinsic resolution even though it is
+     not rendered at all, so any scoring based on videoWidth prefers it. -->
+<video id="preload" style="display:none" muted src="../media/player-1080p-30s.mp4"></video>
+<video id="player" data-expected width="854" height="480" controls src="../media/player-480p-12s.mp4"></video>
+<script src="ready.js"></script>
diff --git a/tests/e2e/fixtures/pages/iframe-player.html b/tests/e2e/fixtures/pages/iframe-player.html
new file mode 100644
index 0000000..9a5cb1f
--- /dev/null
+++ b/tests/e2e/fixtures/pages/iframe-player.html
@@ -0,0 +1,6 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Same-origin iframe player</title>
+<h1>Player lives in a first-party frame, top document has no video</h1>
+<iframe class="player_frame" width="860" height="490" src="frames/player-frame.html"></iframe>
+<script src="ready.js"></script>
diff --git a/tests/e2e/fixtures/pages/late-frame.html b/tests/e2e/fixtures/pages/late-frame.html
new file mode 100644
index 0000000..767f11d
--- /dev/null
+++ b/tests/e2e/fixtures/pages/late-frame.html
@@ -0,0 +1,16 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Late loading player frame</title>
+<h1>The player frame is attached after the page has settled</h1>
+<div id="slot"></div>
+<script>
+    // Mirrors sites that build the player frame from script once the episode
+    // data arrives, well after the content script was injected.
+    setTimeout(() => {
+        const frame = document.createElement('iframe');
+        frame.width = 860;
+        frame.height = 490;
+        frame.src = 'frames/player-frame.html';
+        document.getElementById('slot').appendChild(frame);
+    }, 400);
+</script>
diff --git a/tests/e2e/fixtures/pages/multi-player.html b/tests/e2e/fixtures/pages/multi-player.html
new file mode 100644
index 0000000..88bb689
--- /dev/null
+++ b/tests/e2e/fixtures/pages/multi-player.html
@@ -0,0 +1,11 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Two players, one playing</title>
+<h1>Identical players, the second one is the one being watched</h1>
+<!-- Same size, same asset, same mute state. Playback is the only signal that
+     tells the two apart, so a scorer that ignores it picks by DOM order. -->
+<!-- The longer asset gives the watched player enough runway that it cannot
+     reach its end while the test is still looking at it. -->
+<video id="idle" width="854" height="480" controls src="../media/player-1080p-30s.mp4"></video>
+<video id="watched" data-expected width="854" height="480" controls data-autoplay src="../media/player-1080p-30s.mp4"></video>
+<script src="ready.js"></script>
diff --git a/tests/e2e/fixtures/pages/muted-player.html b/tests/e2e/fixtures/pages/muted-player.html
new file mode 100644
index 0000000..c309b84
--- /dev/null
+++ b/tests/e2e/fixtures/pages/muted-player.html
@@ -0,0 +1,8 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Muted real player</title>
+<h1>The only player on the page, muted by the viewer</h1>
+<!-- Guard against over-filtering: mute is a viewer preference, not a reason to
+     disqualify the one real player. -->
+<video id="player" data-expected width="854" height="480" controls muted src="../media/player-480p-12s.mp4"></video>
+<script src="ready.js"></script>
diff --git a/tests/e2e/fixtures/pages/ready.js b/tests/e2e/fixtures/pages/ready.js
new file mode 100644
index 0000000..0fed626
--- /dev/null
+++ b/tests/e2e/fixtures/pages/ready.js
@@ -0,0 +1,51 @@
+/**
+ * Fixture helper. Marks the page ready once every <video> that is supposed to
+ * carry metadata has it, and once every video marked data-autoplay is actually
+ * playing. Tests wait for window.__fixtureReady instead of sleeping, so the
+ * scoring signals (videoWidth, duration, paused) are settled before we look.
+ */
+(function () {
+    window.__fixtureReady = false;
+
+    function collectVideos(doc, out) {
+        for (const video of doc.querySelectorAll('video')) out.push(video);
+        for (const frame of doc.querySelectorAll('iframe')) {
+            let frameDoc = null;
+            try { frameDoc = frame.contentDocument; } catch (_e) { frameDoc = null; }
+            if (frameDoc) collectVideos(frameDoc, out);
+        }
+        for (const host of doc.querySelectorAll('*')) {
+            if (host.shadowRoot) collectVideos(host.shadowRoot, out);
+        }
+        return out;
+    }
+
+    function metadataReady(video) {
+        if (video.dataset.sourceless !== undefined) return true;
+        return video.readyState >= 1;
+    }
+
+    function playbackReady(video) {
+        if (video.dataset.autoplay === undefined) return true;
+        return !video.paused;
+    }
+
+    function check() {
+        const videos = collectVideos(document, []);
+        if (!videos.length) return false;
+        if (!videos.every(v => metadataReady(v) && playbackReady(v))) return false;
+        window.__fixtureReady = true;
+        return true;
+    }
+
+    function start() {
+        for (const video of collectVideos(document, [])) {
+            if (video.dataset.autoplay !== undefined) video.play().catch(() => {});
+        }
+        if (check()) return;
+        const timer = setInterval(() => { if (check()) clearInterval(timer); }, 50);
+    }
+
+    if (document.readyState === 'complete') start();
+    else window.addEventListener('load', start);
+})();
diff --git a/tests/e2e/fixtures/pages/shadow-player.html b/tests/e2e/fixtures/pages/shadow-player.html
new file mode 100644
index 0000000..6571937
--- /dev/null
+++ b/tests/e2e/fixtures/pages/shadow-player.html
@@ -0,0 +1,19 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Shadow DOM player</title>
+<h1>Tiny light-DOM teaser, real player inside a shadow root</h1>
+<video id="teaser" width="160" height="90" muted src="../media/ad-360p-5s.mp4"></video>
+<div id="player-host"></div>
+<script>
+    const host = document.getElementById('player-host');
+    const root = host.attachShadow({ mode: 'open' });
+    const video = document.createElement('video');
+    video.id = 'shadow-player';
+    video.setAttribute('data-expected', '');
+    video.width = 854;
+    video.height = 480;
+    video.controls = true;
+    video.src = '../media/player-480p-12s.mp4';
+    root.appendChild(video);
+</script>
+<script src="ready.js"></script>
diff --git a/tests/e2e/fixtures/pages/simple-player.html b/tests/e2e/fixtures/pages/simple-player.html
new file mode 100644
index 0000000..8dadf37
--- /dev/null
+++ b/tests/e2e/fixtures/pages/simple-player.html
@@ -0,0 +1,6 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Simple player</title>
+<h1>Single visible player</h1>
+<video id="player" data-expected width="854" height="480" controls src="../media/player-480p-12s.mp4"></video>
+<script src="ready.js"></script>
diff --git a/tests/e2e/fixtures/pages/sourceless.html b/tests/e2e/fixtures/pages/sourceless.html
new file mode 100644
index 0000000..94bad59
--- /dev/null
+++ b/tests/e2e/fixtures/pages/sourceless.html
@@ -0,0 +1,9 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>Sourceless placeholder</title>
+<h1>Large empty placeholder next to the real player</h1>
+<!-- No src at all: readyState stays 0 and it can never be synchronized, but it
+     occupies a big layout box. -->
+<video id="placeholder" data-sourceless style="width:1280px;height:720px"></video>
+<video id="player" data-expected width="640" height="360" controls src="../media/player-480p-12s.mp4"></video>
+<script src="ready.js"></script>
diff --git a/tests/e2e/helpers/content-source.mjs b/tests/e2e/helpers/content-source.mjs
new file mode 100644
index 0000000..beb09e3
--- /dev/null
+++ b/tests/e2e/helpers/content-source.mjs
@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+const contentPath = path.join(repoRoot, 'extension/content.js');
+
+/**
+ * Pulls a top-level function out of content.js by brace matching.
+ *
+ * The E2E suite deliberately runs the shipped source rather than a copy: a
+ * fixture that passes against a reimplementation proves nothing about what the
+ * extension actually does.
+ */
+export function extractFunction(name, source = fs.readFileSync(contentPath, 'utf8')) {
+    const start = source.indexOf(`function ${name}`);
+    if (start === -1) throw new Error(`${name} not found in extension/content.js`);
+
+    let depth = 0;
+    for (let i = source.indexOf('{', start); i < source.length; i++) {
+        if (source[i] === '{') depth++;
+        if (source[i] === '}') {
+            depth--;
+            if (depth === 0) return source.slice(start, i + 1);
+        }
+    }
+    throw new Error(`${name} body did not terminate`);
+}
+
+/**
+ * Every function the video finder needs, as one evaluatable script that exposes
+ * window.__koalaFindVideo. Keeping this list here means a refactor that splits
+ * findVideo into helpers fails loudly instead of silently testing stale code.
+ */
+export const VIDEO_FINDER_EXPORTS = [
+    'findVideo',
+    'collectVideoCandidates',
+    'getRenderedVideoArea',
+    'getVideoSizeBucket',
+    'isVideoRendered',
+    'hasPlayableVideoSource',
+    'isBackgroundVideo',
+    'isVideoPlaying',
+    'compareVideoRanks',
+    'pickBestVideo'
+];
+
+/** The ranking table lives outside a function, so it is lifted by pattern. */
+function extractRankingTable(source) {
+    const start = source.indexOf('const VIDEO_RANKING_SIGNALS');
+    if (start === -1) throw new Error('VIDEO_RANKING_SIGNALS not found in extension/content.js');
+    const end = source.indexOf('];', start);
+    if (end === -1) throw new Error('VIDEO_RANKING_SIGNALS did not terminate');
+    return source.slice(start, end + 2);
+}
+
+export function buildVideoFinderScript() {
+    const source = fs.readFileSync(contentPath, 'utf8');
+    const bodies = VIDEO_FINDER_EXPORTS.map(name => extractFunction(name, source));
+    return [
+        ...bodies,
+        extractRankingTable(source),
+        'window.__koalaFindVideo = findVideo;'
+    ].join('\n');
+}
diff --git a/tests/e2e/playwright.config.mjs b/tests/e2e/playwright.config.mjs
new file mode 100644
index 0000000..b8ec138
--- /dev/null
+++ b/tests/e2e/playwright.config.mjs
@@ -0,0 +1,34 @@
+import { defineConfig } from '@playwright/test';
+
+const PORT = Number(process.env.KOALA_E2E_PORT || 4173);
+
+export default defineConfig({
+    testDir: '.',
+    testMatch: '**/*.spec.mjs',
+    // Extension tests drive a persistent context and a service worker; running
+    // them in parallel makes the profile directories fight each other.
+    workers: 1,
+    fullyParallel: false,
+    forbidOnly: !!process.env.CI,
+    retries: 0,
+    reporter: process.env.CI ? 'list' : [['list']],
+    timeout: 30_000,
+    expect: { timeout: 10_000 },
+    use: {
+        baseURL: `http://localhost:${PORT}`,
+        trace: 'retain-on-failure',
+        launchOptions: {
+            // Several fixtures hinge on a video actually playing. Without this
+            // the browser's autoplay heuristics decide whether the fixture is
+            // valid, which shows up later as an unexplained flake.
+            args: ['--autoplay-policy=no-user-gesture-required']
+        }
+    },
+    webServer: {
+        command: `node ${new URL('./fixture-server.mjs', import.meta.url).pathname} ${PORT}`,
+        url: `http://localhost:${PORT}/pages/simple-player.html`,
+        reuseExistingServer: !process.env.CI,
+        stdout: 'ignore',
+        stderr: 'pipe'
+    }
+});