refactor(embedded-mpv): split session controller into focused collaborators

Mechanical decomposition of the embedded-MPV session controller into
focused collaborators under embedded-mpv-player/:

- embedded-mpv-command-runner.ts: transport/track/recording IPC
  delegators with guarded snapshot reconciliation
- embedded-mpv-session-factory.ts: pure placeholder-session factories
  (loading/attaching/error) and the startup-paint wait
- embedded-mpv-stalled-tracker.ts: loading-stall timer and stalled flag
- embedded-mpv-compositor.ts: host bounds measurement (measureBounds),
  re-exported from embedded-mpv-format.utils for existing imports

No behavior change. The existing embedded-mpv-player component is kept
untouched and keeps working against the controller's unchanged public
API (commands are now bound fields delegating to the runner).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: larsemig

libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-command-runner.ts

@@ -0,0 +1,167 @@
+import { Signal, WritableSignal } from '@angular/core';
+import { EmbeddedMpvSession } from '@iptvnator/shared/interfaces';
+
+type ElectronBridge = Window['electron'];
+
+/**
+ * Context the {@link EmbeddedMpvCommandRunner} reads/writes. The controller owns
+ * the signals; the runner only delegates IPC and reconciles the returned
+ * snapshot back into `session`.
+ */
+export interface EmbeddedMpvCommandContext {
+    readonly sessionId: Signal<string | null>;
+    readonly session: WritableSignal<EmbeddedMpvSession | null>;
+}
+
+/**
+ * Thin IPC delegators for embedded-MPV transport/track/recording commands.
+ * Split out of the controller so each stays a one-liner around `guardIpc`,
+ * which swallows races where the session was torn down mid-call (the next
+ * broadcast snapshot resyncs state).
+ */
+export class EmbeddedMpvCommandRunner {
+    constructor(private readonly ctx: EmbeddedMpvCommandContext) {}
+
+    async togglePaused(): Promise<void> {
+        const id = this.ctx.sessionId();
+        const session = this.ctx.session();
+        const electron = this.bridge();
+        if (!id || !session || !electron?.setEmbeddedMpvPaused) {
+            return;
+        }
+        await this.run(() =>
+            electron.setEmbeddedMpvPaused(id, session.status !== 'paused')
+        );
+    }
+
+    async seekBy(deltaSeconds: number): Promise<boolean> {
+        const id = this.ctx.sessionId();
+        const session = this.ctx.session();
+        const electron = this.bridge();
+        if (!id || !session || !electron?.seekEmbeddedMpv) {
+            return false;
+        }
+        const next = Math.max(0, session.positionSeconds + deltaSeconds);
+        await this.run(() => electron.seekEmbeddedMpv(id, next));
+        return true;
+    }
+
+    async seekTo(seconds: number): Promise<void> {
+        const id = this.ctx.sessionId();
+        const electron = this.bridge();
+        if (!id || !electron?.seekEmbeddedMpv) {
+            return;
+        }
+        await this.run(() => electron.seekEmbeddedMpv(id, seconds));
+    }
+
+    async applyVolume(value: number): Promise<void> {
+        const id = this.ctx.sessionId();
+        const electron = this.bridge();
+        if (!id || !electron?.setEmbeddedMpvVolume) {
+            return;
+        }
+        await this.run(() => electron.setEmbeddedMpvVolume(id, value));
+    }
+
+    async setAudioTrack(trackId: number): Promise<void> {
+        const id = this.ctx.sessionId();
+        const electron = this.bridge();
+        if (!id || !electron?.setEmbeddedMpvAudioTrack) {
+            return;
+        }
+        await this.run(() => electron.setEmbeddedMpvAudioTrack(id, trackId));
+    }
+
+    async setSubtitleTrack(trackId: number): Promise<void> {
+        const id = this.ctx.sessionId();
+        const electron = this.bridge();
+        if (!id || !electron?.setEmbeddedMpvSubtitleTrack) {
+            return;
+        }
+        const setSubtitleTrack = electron.setEmbeddedMpvSubtitleTrack;
+        await this.run(() => setSubtitleTrack(id, trackId));
+    }
+
+    async setSpeed(speed: number): Promise<void> {
+        const id = this.ctx.sessionId();
+        const electron = this.bridge();
+        if (!id || !electron?.setEmbeddedMpvSpeed) {
+            return;
+        }
+        const setSpeed = electron.setEmbeddedMpvSpeed;
+        await this.run(() => setSpeed(id, speed));
+    }
+
+    async setAspect(aspect: string): Promise<void> {
+        const id = this.ctx.sessionId();
+        const electron = this.bridge();
+        if (!id || !electron?.setEmbeddedMpvAspect) {
+            return;
+        }
+        const setAspect = electron.setEmbeddedMpvAspect;
+        await this.run(() => setAspect(id, aspect));
+    }
+
+    async startRecording(
+        directory: string | undefined,
+        title: string
+    ): Promise<EmbeddedMpvSession['recording'] | null> {
+        const id = this.ctx.sessionId();
+        const electron = this.bridge();
+        if (!id || !electron?.startEmbeddedMpvRecording) {
+            return null;
+        }
+
+        const startEmbeddedMpvRecording = electron.startEmbeddedMpvRecording;
+        const resolvedDirectory =
+            directory?.trim() ||
+            (await electron.getEmbeddedMpvDefaultRecordingFolder?.());
+        const updated = await this.run(() =>
+            startEmbeddedMpvRecording(id, {
+                directory: resolvedDirectory,
+                title,
+            })
+        );
+        return updated?.recording ?? null;
+    }
+
+    async stopRecording(): Promise<EmbeddedMpvSession['recording'] | null> {
+        const id = this.ctx.sessionId();
+        const electron = this.bridge();
+        if (!id || !electron?.stopEmbeddedMpvRecording) {
+            return null;
+        }
+        const stopEmbeddedMpvRecording = electron.stopEmbeddedMpvRecording;
+        const updated = await this.run(() => stopEmbeddedMpvRecording(id));
+        return updated?.recording ?? null;
+    }
+
+    /**
+     * Run an IPC call, reconcile the returned snapshot into `session`, and
+     * return it (or null when the call was swallowed). Errors are intentionally
+     * swallowed: the session may have been torn down or an addon-side throw may
+     * have raced the IPC — the next snapshot resyncs state.
+     */
+    private async run(
+        call: () => Promise<EmbeddedMpvSession | null>
+    ): Promise<EmbeddedMpvSession | null> {
+        const updated = await this.guardIpc(call);
+        if (updated) {
+            this.ctx.session.set(updated);
+        }
+        return updated;
+    }
+
+    private async guardIpc<T>(call: () => Promise<T>): Promise<T | null> {
+        try {
+            return await call();
+        } catch {
+            return null;
+        }
+    }
+
+    private bridge(): ElectronBridge | undefined {
+        return window.electron;
+    }
+}

libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-compositor.spec.ts

@@ -0,0 +1,41 @@
+import { measureBounds } from './embedded-mpv-compositor';
+
+function createHost(rect: Partial<DOMRect>): HTMLElement {
+    return {
+        getBoundingClientRect: () =>
+            ({
+                left: 0,
+                top: 0,
+                width: 800,
+                height: 600,
+                ...rect,
+            }) as DOMRect,
+    } as HTMLElement;
+}
+
+describe('embedded MPV compositor', () => {
+    it('measures the full host viewport (always full-bleed)', () => {
+        expect(measureBounds(createHost({ height: 600 }))).toEqual({
+            x: 0,
+            y: 0,
+            width: 800,
+            height: 600,
+        });
+    });
+
+    it('rounds host bounds and keeps minimum native view dimensions', () => {
+        const host = createHost({
+            left: 10.4,
+            top: 20.6,
+            width: 0,
+            height: 0.2,
+        });
+
+        expect(measureBounds(host)).toEqual({
+            x: 10,
+            y: 21,
+            width: 1,
+            height: 1,
+        });
+    });
+});

libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-compositor.ts

@@ -0,0 +1,19 @@
+import { EmbeddedMpvBounds } from '@iptvnator/shared/interfaces';
+
+/**
+ * Measure the host's viewport rect as native-surface bounds.
+ *
+ * The native MPV surface composites over the WebContents and simply follows
+ * the host viewport, so this single measurement is the default bounds
+ * provider of the session controller. Hosts can override the provider (via
+ * `setBoundsProvider`) when they need to inset or hide the surface.
+ */
+export function measureBounds(host: HTMLElement): EmbeddedMpvBounds {
+    const rect = host.getBoundingClientRect();
+    return {
+        x: Math.round(rect.left),
+        y: Math.round(rect.top),
+        width: Math.max(1, Math.round(rect.width)),
+        height: Math.max(1, Math.round(rect.height)),
+    };
+}

libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-format.utils.ts

@@ -117,12 +117,6 @@ export function persistVolume(value: number): void {
     localStorage.setItem('volume', String(value));
 }
 
-export function measureBounds(host: HTMLElement): EmbeddedMpvBounds {
-    const rect = host.getBoundingClientRect();
-    return {
-        x: Math.round(rect.left),
-        y: Math.round(rect.top),
-        width: Math.max(1, Math.round(rect.width)),
-        height: Math.max(1, Math.round(rect.height)),
-    };
-}
+// Kept as a re-export for existing imports; the implementation moved to the
+// compositor module alongside the session controller's bounds handling.
+export { measureBounds } from './embedded-mpv-compositor';

libs/ui/playback/src/lib/embedded-mpv-player/embedded-mpv-session-controller.spec.ts

@@ -167,6 +167,27 @@ describe('EmbeddedMpvSessionController', () => {
         );
     });
 
+    it('attaches to an existing session and applies only matching broadcasts', async () => {
+        const controller = TestBed.inject(EmbeddedMpvSessionController);
+
+        controller.attach('mpv-1');
+
+        expect(controller.sessionId()).toBe('mpv-1');
+        // A loading placeholder is set until the first broadcast arrives.
+        expect(controller.session()).toEqual(
+            expect.objectContaining({ id: 'mpv-1', status: 'loading' })
+        );
+        // attach must not create or load a session.
+        expect(electron.createEmbeddedMpvSession).not.toHaveBeenCalled();
+        expect(electron.loadEmbeddedMpvPlayback).not.toHaveBeenCalled();
+
+        sessionUpdate?.(createSession({ id: 'other', status: 'paused' }));
+        expect(controller.session()?.status).toBe('loading');
+
+        sessionUpdate?.(createSession({ id: 'mpv-1', status: 'playing' }));
+        expect(controller.session()?.status).toBe('playing');
+    });
+
     it('sets an error session when Electron cannot create playback', async () => {
         electron.prepareEmbeddedMpv.mockRejectedValueOnce(
             new Error('native module missing')