From 6c440fc437ea1a4c170937b40cbe9845d6a59a34 Mon Sep 17 00:00:00 2001
From: 4gray <fourgray@proton.me>
Date: Sun, 23 Aug 2026 19:35:46 +0200
Subject: [PATCH] fix(playback): re-sync embedded MPV bounds on position-only
 layout shifts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An ancestor re-layout can translate the player host without resizing it
(sidebar content settling, EPG panel loading below the player).
ResizeObserver reports size changes only and no DOM event observes
"position changed", so the native child window silently kept its stale
coordinates and rendered offset from the DOM stage.

The session controller now polls the host bounds every 500 ms while a
session is active, compares them against the last synced bounds with a
half-pixel tolerance, and re-syncs only on drift — idle cost is one
getBoundingClientRect per tick with no IPC.

Fixes #1428

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../playback-embedded-mpv-position-drift.md   |  10 +
 CLAUDE.md                                     |   2 +-
 docs/architecture/embedded-mpv-native.md      |  10 +
 ...ed-mpv-session-controller.position.spec.ts | 180 ++++++++++++++++++
 .../embedded-mpv-session-controller.ts        |  49 ++++-
 5 files changed, 246 insertions(+), 5 deletions(-)
 create mode 100644 .changes/playback-embedded-mpv-position-drift.md
 create mode 100644 libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.position.spec.ts

diff --git a/.changes/playback-embedded-mpv-position-drift.md b/.changes/playback-embedded-mpv-position-drift.md
new file mode 100644
index 000000000..6da47542f
--- /dev/null
+++ b/.changes/playback-embedded-mpv-position-drift.md
@@ -0,0 +1,10 @@
+---
+type: fix
+area: playback
+issues: [1428]
+---
+
+The embedded MPV video no longer drifts out of its frame when the layout
+shifts around it — for example when the channel sidebar or the EPG panel
+finishes loading after playback has started. The player now notices such
+moves and snaps the video back into place within half a second.
diff --git a/CLAUDE.md b/CLAUDE.md
index 2f8892bb7..e0ae2581a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -968,7 +968,7 @@ app as a real argument, so it is not an option.
   API. Radio's `<audio>` deliberately never blocks display sleep. Embedded
   MPV holds its own blocker in `EmbeddedMpvNativeService`; external MPV/VLC
   inhibit the screensaver themselves.
-- Embedded MPV (experimental, macOS/Windows/Linux): renders mpv video inside the Electron window through a native addon. macOS uses the libmpv render API in an `NSOpenGLView`; Windows uses in-process libmpv with `--wid` against an app-owned child `HWND`; Linux spawns an out-of-process `mpv --wid=<x11-window>` controlled over a JSON IPC socket (X11/XWayland only, requires system `mpv` on PATH; subtitles/speed/aspect/recording are not exported there). mpv's own screensaver inhibition does not apply to any of these paths, so `EmbeddedMpvNativeService` holds an Electron `powerSaveBlocker` (`prevent-display-sleep`) whenever any session's status is `playing`, and releases it on pause, dispose, or shutdown. Renderer bounds are CSS pixels; the service converts them to native units in the main process (`embedded-mpv-bounds.util.ts`: × page zoom everywhere, × display scale on Windows/Linux whose child windows are positioned in physical pixels; frame-copy bounds stay unscaled), and the session controller re-syncs bounds when `devicePixelRatio` changes. Service: `apps/electron-backend/src/app/services/embedded-mpv-native.service.ts`; full architecture: `docs/architecture/embedded-mpv-native.md`.
+- Embedded MPV (experimental, macOS/Windows/Linux): renders mpv video inside the Electron window through a native addon. macOS uses the libmpv render API in an `NSOpenGLView`; Windows uses in-process libmpv with `--wid` against an app-owned child `HWND`; Linux spawns an out-of-process `mpv --wid=<x11-window>` controlled over a JSON IPC socket (X11/XWayland only, requires system `mpv` on PATH; subtitles/speed/aspect/recording are not exported there). mpv's own screensaver inhibition does not apply to any of these paths, so `EmbeddedMpvNativeService` holds an Electron `powerSaveBlocker` (`prevent-display-sleep`) whenever any session's status is `playing`, and releases it on pause, dispose, or shutdown. Renderer bounds are CSS pixels; the service converts them to native units in the main process (`embedded-mpv-bounds.util.ts`: × page zoom everywhere, × display scale on Windows/Linux whose child windows are positioned in physical pixels; frame-copy bounds stay unscaled), and the session controller re-syncs bounds when `devicePixelRatio` changes and polls (500 ms, drift-gated) for position-only layout shifts that `ResizeObserver` cannot observe. Service: `apps/electron-backend/src/app/services/embedded-mpv-native.service.ts`; full architecture: `docs/architecture/embedded-mpv-native.md`.
 - Embedded MPV frame-copy engine (experimental, macOS Apple Silicon + Linux
   x64 + Windows; enabled via `Settings > Playback > Embedded MPV: frame-copy
 engine` (restart required) or
diff --git a/docs/architecture/embedded-mpv-native.md b/docs/architecture/embedded-mpv-native.md
index a6a533376..7b11179ef 100644
--- a/docs/architecture/embedded-mpv-native.md
+++ b/docs/architecture/embedded-mpv-native.md
@@ -667,6 +667,16 @@ re-armed `matchMedia('(resolution: …dppx)')` query and re-syncs bounds when
 it changes; page zoom changes are covered by the same watch plus the ordinary
 resize-driven syncs.
 
+An ancestor re-layout can also translate the host **without resizing it** —
+the channel sidebar's content settling, panels loading below the player.
+`ResizeObserver` reports size changes only and no DOM event observes
+"position changed", so before #1428 the native child window silently kept its
+stale coordinates and rendered offset from the DOM stage. The session
+controller therefore polls the host bounds every 500 ms while a session is
+active, compares them against the last synced bounds with a half-pixel
+tolerance, and schedules a re-sync only on drift — idle cost is one
+`getBoundingClientRect` per tick with no IPC.
+
 ### Controls ownership by engine
 
 `EmbeddedMpvPlayerComponent` selects one control owner from
diff --git a/libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.position.spec.ts b/libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.position.spec.ts
new file mode 100644
index 000000000..dbdf7e30b
--- /dev/null
+++ b/libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.position.spec.ts
@@ -0,0 +1,180 @@
+import { TestBed } from '@angular/core/testing';
+import {
+    EmbeddedMpvSession,
+    ResolvedPortalPlayback,
+} from '@iptvnator/shared/interfaces';
+import { EmbeddedMpvSessionController } from './embedded-mpv-session-controller';
+
+/**
+ * An ancestor re-layout can translate the host element without resizing it
+ * (sidebar content settling, panels loading below the player). ResizeObserver
+ * reports size changes only and no resize/scroll event fires, so before the
+ * position poll the native child window silently kept its stale coordinates
+ * and rendered offset from the DOM stage (#1428). The controller now polls
+ * the host bounds at a low frequency and re-syncs only when they drift from
+ * the last synced bounds.
+ */
+describe('EmbeddedMpvSessionController position drift poll', () => {
+    let electron: {
+        platform: string;
+        getEmbeddedMpvSupport: jest.Mock;
+        prepareEmbeddedMpv: jest.Mock;
+        createEmbeddedMpvSession: jest.Mock;
+        loadEmbeddedMpvPlayback: jest.Mock;
+        disposeEmbeddedMpvSession: jest.Mock;
+        setEmbeddedMpvBounds: jest.Mock;
+        onEmbeddedMpvSessionUpdate: jest.Mock;
+    };
+
+    beforeEach(() => {
+        // See `waitFor`: the startup chain is drained on a virtual clock so a
+        // loaded machine cannot change the outcome.
+        jest.useFakeTimers();
+        electron = {
+            platform: 'linux',
+            getEmbeddedMpvSupport: jest
+                .fn()
+                .mockResolvedValue({ supported: true, platform: 'linux' }),
+            prepareEmbeddedMpv: jest
+                .fn()
+                .mockResolvedValue({ supported: true, platform: 'linux' }),
+            createEmbeddedMpvSession: jest
+                .fn()
+                .mockResolvedValue(createSession()),
+            loadEmbeddedMpvPlayback: jest.fn().mockResolvedValue(undefined),
+            disposeEmbeddedMpvSession: jest.fn().mockResolvedValue(undefined),
+            setEmbeddedMpvBounds: jest.fn().mockResolvedValue(undefined),
+            onEmbeddedMpvSessionUpdate: jest.fn(() => jest.fn()),
+        };
+        Object.defineProperty(window, 'electron', {
+            configurable: true,
+            value: electron,
+        });
+        Object.defineProperty(globalThis, 'ResizeObserver', {
+            configurable: true,
+            value: class MockResizeObserver {
+                observe = jest.fn();
+                disconnect = jest.fn();
+            },
+        });
+        Object.defineProperty(window, 'requestAnimationFrame', {
+            configurable: true,
+            value: (callback: FrameRequestCallback) =>
+                window.setTimeout(() => callback(0), 0),
+        });
+        Object.defineProperty(window, 'cancelAnimationFrame', {
+            configurable: true,
+            value: (handle: number) => window.clearTimeout(handle),
+        });
+
+        TestBed.configureTestingModule({
+            providers: [EmbeddedMpvSessionController],
+        });
+    });
+
+    afterEach(() => {
+        TestBed.resetTestingModule();
+        delete (window as unknown as { electron?: unknown }).electron;
+        jest.useRealTimers();
+        jest.restoreAllMocks();
+    });
+
+    it('re-syncs when the host moves without resizing, and stays silent otherwise', async () => {
+        const rect = { left: 10, top: 20, width: 640, height: 360 };
+        const host = {
+            getBoundingClientRect: () => ({ ...rect }),
+        } as HTMLElement;
+
+        const controller = TestBed.inject(EmbeddedMpvSessionController);
+        const teardown = controller.startSession(host, createPlayback(), 0.5);
+        await waitFor(
+            () => controller.sessionId() === 'mpv-1',
+            'session to start'
+        );
+        // The post-create catch-up sync records the initial bounds.
+        await waitFor(
+            () => electron.setEmbeddedMpvBounds.mock.calls.length > 0,
+            'initial bounds sync'
+        );
+        electron.setEmbeddedMpvBounds.mockClear();
+
+        // A stationary host must not produce any IPC across several ticks.
+        await jest.advanceTimersByTimeAsync(2000);
+        expect(electron.setEmbeddedMpvBounds).not.toHaveBeenCalled();
+
+        // Position-only shift: getBoundingClientRect changes while nothing
+        // fires ResizeObserver, window resize, or scroll.
+        rect.left = 29;
+        await jest.advanceTimersByTimeAsync(600);
+        await waitFor(
+            () => electron.setEmbeddedMpvBounds.mock.calls.length > 0,
+            'bounds re-sync after position drift'
+        );
+        expect(electron.setEmbeddedMpvBounds).toHaveBeenLastCalledWith(
+            'mpv-1',
+            { x: 29, y: 20, width: 640, height: 360 }
+        );
+
+        // Once synced, the settled position produces no further IPC.
+        electron.setEmbeddedMpvBounds.mockClear();
+        await jest.advanceTimersByTimeAsync(2000);
+        expect(electron.setEmbeddedMpvBounds).not.toHaveBeenCalled();
+
+        // Teardown stops the poll: later drift must not reach the bridge.
+        teardown();
+        rect.left = 100;
+        await jest.advanceTimersByTimeAsync(2000);
+        expect(electron.setEmbeddedMpvBounds).not.toHaveBeenCalled();
+    });
+});
+
+function createPlayback(): ResolvedPortalPlayback {
+    return {
+        streamUrl: 'https://example.com/movie.mp4',
+        title: 'Example Movie',
+    };
+}
+
+function createSession(): EmbeddedMpvSession {
+    return {
+        id: 'mpv-1',
+        title: 'Example Movie',
+        streamUrl: 'https://example.com/movie.mp4',
+        status: 'playing',
+        positionSeconds: 0,
+        durationSeconds: null,
+        volume: 0.5,
+        audioTracks: [],
+        selectedAudioTrackId: null,
+        subtitleTracks: [],
+        selectedSubtitleTrackId: null,
+        playbackSpeed: 1,
+        aspectOverride: 'no',
+        recording: { active: false },
+        startedAt: '2026-08-23T00:00:00.000Z',
+        updatedAt: '2026-08-23T00:00:01.000Z',
+    };
+}
+
+/**
+ * Settle the controller's async startup chain on the fake clock, bounded by
+ * drain rounds rather than wall-clock time — under parallel Jest workers a
+ * real-timer deadline expired before the chain settled and failed at random.
+ *
+ * One millisecond per round, never zero: `waitForStartupPaint` nests rAF
+ * inside rAF, and a zero-delay timer scheduled from inside a timer callback is
+ * clamped to the next millisecond, so a 0ms advance strands the inner hop.
+ */
+async function waitFor(
+    condition: () => boolean,
+    description: string
+): Promise<void> {
+    for (let round = 0; round < 100; round += 1) {
+        if (condition()) {
+            return;
+        }
+        await Promise.resolve();
+        await jest.advanceTimersByTimeAsync(1);
+    }
+    throw new Error(`Timed out waiting for ${description}`);
+}
diff --git a/libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts b/libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts
index f760bec97..6c4ab1f4f 100644
--- a/libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts
+++ b/libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.ts
@@ -28,6 +28,29 @@ export type EmbeddedMpvBoundsProvider = (
 
 type ElectronBridge = Window['electron'];
 
+/**
+ * Cadence of the host-position drift poll. 500 ms keeps a stuck native
+ * window user-invisible (it snaps back within half a second) while costing
+ * one getBoundingClientRect per tick and zero IPC while nothing moves.
+ */
+const POSITION_POLL_INTERVAL_MS = 500;
+
+/**
+ * Sub-pixel measurement noise must not re-send bounds every tick: after a
+ * sync the next poll re-measures the same layout, so anything below half a
+ * CSS pixel is the same position. Real layout shifts move by whole pixels.
+ */
+const POSITION_POLL_EPSILON_PX = 0.5;
+
+function boundsDiffer(a: EmbeddedMpvBounds, b: EmbeddedMpvBounds): boolean {
+    return (
+        Math.abs(a.x - b.x) > POSITION_POLL_EPSILON_PX ||
+        Math.abs(a.y - b.y) > POSITION_POLL_EPSILON_PX ||
+        Math.abs(a.width - b.width) > POSITION_POLL_EPSILON_PX ||
+        Math.abs(a.height - b.height) > POSITION_POLL_EPSILON_PX
+    );
+}
+
 @Injectable()
 export class EmbeddedMpvSessionController {
     readonly support = signal<EmbeddedMpvSupport | null>(null);
@@ -121,16 +144,16 @@ export class EmbeddedMpvSessionController {
     ): () => void {
         let disposed = false;
         let activeSessionId: string | null = null;
+        let lastSyncedBounds: EmbeddedMpvBounds | null = null;
 
         const syncBounds = () => {
             if (!activeSessionId) {
                 return;
             }
+            const bounds = this.boundsProvider(host);
+            lastSyncedBounds = bounds;
             void window.electron
-                ?.setEmbeddedMpvBounds(
-                    activeSessionId,
-                    this.boundsProvider(host)
-                )
+                ?.setEmbeddedMpvBounds(activeSessionId, bounds)
                 .catch(() => undefined);
         };
 
@@ -151,6 +174,23 @@ export class EmbeddedMpvSessionController {
         window.addEventListener('resize', scheduleBoundsSync);
         window.addEventListener('scroll', scheduleBoundsSync, true);
 
+        // ResizeObserver reports size changes only: an ancestor re-layout
+        // that translates the host without resizing it (sidebar content
+        // settling, panels loading below the player) moves the DOM while the
+        // native child window keeps its old coordinates, and no DOM event
+        // observes "position changed" (#1428). A low-frequency poll compares
+        // the measured bounds against the last synced ones and re-syncs only
+        // on drift, so the idle cost is one getBoundingClientRect per tick
+        // with no IPC.
+        const positionPoll = window.setInterval(() => {
+            if (!activeSessionId || !lastSyncedBounds) {
+                return;
+            }
+            if (boundsDiffer(this.boundsProvider(host), lastSyncedBounds)) {
+                scheduleBoundsSync();
+            }
+        }, POSITION_POLL_INTERVAL_MS);
+
         // Page zoom and monitor DPI rescale the CSS→native-pixel mapping the
         // backend applies to these bounds. Moving the window to a display
         // with a different scale can keep the CSS layout identical (no
@@ -262,6 +302,7 @@ export class EmbeddedMpvSessionController {
             resizeObserver.disconnect();
             window.removeEventListener('resize', scheduleBoundsSync);
             window.removeEventListener('scroll', scheduleBoundsSync, true);
+            window.clearInterval(positionPoll);
             detachDprWatch?.();
             detachDprWatch = null;