feat(embedded-mpv): real macOS native fullscreen for the embedded player

Use native NSWindow fullscreen instead of DOM fullscreen for the
embedded player. Extend the player-controls contract with a fullscreen
delegate (PlayerFullscreenController + ControlsFullscreenBinding) and
add window-state IPC so OS-initiated exits (green button, Ctrl+Cmd+F,
ESC) reconcile with the in-app fullscreen state.

Review-driven hardening: the deferred window-fullscreen request is now
gated by a generation counter + destroyed flag so it becomes a no-op if
fullscreen is exited/re-toggled or the component is torn down before the
two requestAnimationFrame ticks run (pending rAF ids are cancelled in
ngOnDestroy); the fill snap is awaited (raced with a ~150ms timeout so a
hung IPC can not block fullscreen) before scheduling the window request;
and the fullscreen controller now requires BOTH the setMainWindowFullScreen
and setEmbeddedMpvFill bridges in canToggle (older bridges fall back to the
built-in DOM fullscreen path).

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

Author: larsemig

apps/electron-backend/native/src/embedded_mpv.mm

@@ -121,6 +121,21 @@ - (NSView*)hitTest:(NSPoint)point
     dispatch_queue_t renderQueue = nullptr;
     std::thread eventThread;
     std::atomic<bool> running{false};
+    // When true, the container view fills the host content view via an
+    // autoresizing mask and rides the window's resize animation (the fullscreen
+    // grow). Per-frame bounds syncs are ignored so a snapped setFrame can't
+    // interrupt that animation.
+    std::atomic<bool> fillMode{false};
+    // When true, mpv frame rendering is paused. Used during the fullscreen grow:
+    // active rendering into the (stale-size) GL drawable mid-animation snaps the
+    // image, but freezing it lets the last frame scale smoothly with the view
+    // (the same reason a PAUSED video grows cleanly). Resumed when the animation
+    // settles.
+    std::atomic<bool> renderFrozen{false};
+    // Bumped on every setSessionFill call so a deferred unfreeze timer can detect
+    // it was superseded by a newer fill cycle (rapid enter/exit/enter) and skip,
+    // instead of unfreezing mid-way through the new transition.
+    std::atomic<uint64_t> fillGeneration{0};
     std::atomic<bool> renderScheduled{false};
     std::atomic<bool> renderNeeded{false};
     std::atomic<uint64_t> renderedFrameCount{0};
@@ -372,6 +387,12 @@ void setSessionFrame(const std::shared_ptr<Session>& session, double x, double y
           return;
       }
 
+      // In fill mode the autoresizing mask owns the frame and animates it with
+      // the window; a snapped setFrame here would fight that, so skip the sync.
+      if (session->fillMode.load()) {
+          return;
+      }
+
       NSRect parentBounds = [session->parentView bounds];
       const CGFloat frameWidth = static_cast<CGFloat>(std::max(width, 0.0));
       const CGFloat frameHeight = static_cast<CGFloat>(std::max(height, 0.0));
@@ -386,14 +407,93 @@ void setSessionFrame(const std::shared_ptr<Session>& session, double x, double y
                                             fromView:session->parentView];
       }
 
+      // Snap the frame with NO implicit Core Animation. The container view is
+      // layer-backed, so a plain setFrame: animates position+size (~0.25s) —
+      // which made the surface visibly slide/grow on fullscreen and lag during
+      // window resizes. Disabling actions makes it track the bounds instantly.
+      [CATransaction begin];
+      [CATransaction setDisableActions:YES];
       [session->containerView setFrame:frameRect];
+      [CATransaction commit];
+      if (session->openGLContext) {
+          [session->openGLContext update];
+      } else {
+          [session->containerView setNeedsDisplay:YES];
+      }
+    });
+
+    updateRenderSurfaceMetrics(session);
+    requestRender(session);
+}
+
+// Approximate duration of the macOS fullscreen transition. Rendering is frozen
+// for this long during the transition so the last frame scales smoothly with the
+// view, then resumed at the final size.
+constexpr double kFillAnimationSeconds = 0.4;
+
+// Toggle fullscreen "fill" mode. On enable, snap the container to cover the host
+// content view NOW, give it a flexible autoresizing mask so it grows in lockstep
+// with the window's animated resize, and FREEZE rendering for the animation so
+// the last frame scales smoothly (active rendering into the stale-size drawable
+// would snap). On disable, drop the mask and resume; the next bounds sync
+// restores the inline rect.
+void setSessionFill(const std::shared_ptr<Session>& session, bool fill)
+{
+    session->fillMode.store(fill);
+    // Freeze before the snap so no in-flight frame draws at the new size.
+    session->renderFrozen.store(fill);
+    // Mark this fill cycle so a pending unfreeze timer from a previous cycle
+    // (e.g. a fast enter/exit/enter) knows it is stale and bows out.
+    const uint64_t generation = session->fillGeneration.fetch_add(1) + 1;
+    runOnMainSync(^{
+      if (!session->hostView || !session->containerView) {
+          return;
+      }
+      if (fill) {
+          session->containerView.autoresizingMask =
+              NSViewWidthSizable | NSViewHeightSizable;
+          [CATransaction begin];
+          [CATransaction setDisableActions:YES];
+          [session->containerView setFrame:[session->hostView bounds]];
+          [CATransaction commit];
+      } else {
+          session->containerView.autoresizingMask = NSViewNotSizable;
+      }
       if (session->openGLContext) {
           [session->openGLContext update];
       } else {
           [session->containerView setNeedsDisplay:YES];
       }
     });
 
+    if (fill) {
+        // Resume rendering once the transition has settled, re-reading the (now
+        // final) view size so mpv draws crisply at full resolution.
+        auto sessionCopy = session;
+        dispatch_after(
+            dispatch_time(
+                DISPATCH_TIME_NOW,
+                static_cast<int64_t>(kFillAnimationSeconds * NSEC_PER_SEC)
+            ),
+            dispatch_get_main_queue(),
+            ^{
+              if (!sessionCopy->fillMode.load() ||
+                  sessionCopy->fillGeneration.load() != generation) {
+                  // Exited fullscreen, or a newer fill cycle superseded this one,
+                  // before the animation settled.
+                  return;
+              }
+              if (sessionCopy->openGLContext) {
+                  [sessionCopy->openGLContext update];
+              }
+              updateRenderSurfaceMetrics(sessionCopy);
+              sessionCopy->renderFrozen.store(false);
+              requestRender(sessionCopy);
+            }
+        );
+        return;
+    }
+
     updateRenderSurfaceMetrics(session);
     requestRender(session);
 }
@@ -406,6 +506,9 @@ void destroySession(const std::shared_ptr<Session>& session)
 
     session->running.store(false);
     session->renderNeeded.store(false);
+    // Defensive: never leave fill/freeze flags set on a torn-down session.
+    session->fillMode.store(false);
+    session->renderFrozen.store(false);
 
     if (session->displayLink) {
         CVDisplayLinkStop(session->displayLink);
@@ -688,6 +791,12 @@ void renderSessionFrame(const std::shared_ptr<Session>& session)
         return;
     }
 
+    // Frozen during the fullscreen grow so the last frame scales smoothly with
+    // the animating view instead of snapping (see Session::renderFrozen).
+    if (session->renderFrozen.load()) {
+        return;
+    }
+
     if (session->renderBackend == RenderBackend::OpenGL) {
         renderOpenGLFrame(session);
         return;
@@ -1957,6 +2066,20 @@ bool startDisplayLink(const std::shared_ptr<Session>& session)
     return env.Undefined();
 }
 
+Napi::Value SetFill(const Napi::CallbackInfo& info)
+{
+    Napi::Env env = info.Env();
+    if (info.Length() < 2 || !info[0].IsString() || !info[1].IsBoolean()) {
+        throw Napi::TypeError::New(env, "Expected session id and fill flag.");
+    }
+
+    const std::string sessionId = info[0].As<Napi::String>().Utf8Value();
+    const auto session = getSessionOrThrow(env, sessionId);
+    setSessionFill(session, info[1].As<Napi::Boolean>().Value());
+
+    return env.Undefined();
+}
+
 Napi::Value SetPaused(const Napi::CallbackInfo& info)
 {
     Napi::Env env = info.Env();
@@ -2524,6 +2647,7 @@ bool startDisplayLink(const std::shared_ptr<Session>& session)
     exports.Set("createSession", Napi::Function::New(env, CreateSession));
     exports.Set("loadPlayback", Napi::Function::New(env, LoadPlayback));
     exports.Set("setBounds", Napi::Function::New(env, SetBounds));
+    exports.Set("setFill", Napi::Function::New(env, SetFill));
     exports.Set("setPaused", Napi::Function::New(env, SetPaused));
     exports.Set("seek", Napi::Function::New(env, Seek));
     exports.Set("setVolume", Napi::Function::New(env, SetVolume));

apps/electron-backend/src/app/api/main.preload.ts

@@ -59,6 +59,7 @@ const WINDOW_TOGGLE_MAXIMIZE = 'WINDOW:TOGGLE_MAXIMIZE';
 const WINDOW_CLOSE = 'WINDOW:CLOSE';
 const WINDOW_GET_STATE = 'WINDOW:GET_STATE';
 const WINDOW_STATE_CHANGED = 'WINDOW:STATE_CHANGED';
+const WINDOW_SET_FULLSCREEN = 'WINDOW:SET_FULLSCREEN';
 
 const dbSaveContentProgressListeners = new Set<
     (
@@ -325,6 +326,8 @@ const electronApi: ElectronBridgeApi = {
     toggleMaximizeWindow: () => ipcRenderer.invoke(WINDOW_TOGGLE_MAXIMIZE),
     closeWindow: () => ipcRenderer.invoke(WINDOW_CLOSE),
     getWindowState: () => ipcRenderer.invoke(WINDOW_GET_STATE),
+    setMainWindowFullScreen: (enabled: boolean) =>
+        ipcRenderer.invoke(WINDOW_SET_FULLSCREEN, enabled),
     onWindowStateChange: (
         callback: (state: ElectronBridgeWindowState) => void
     ) => {
@@ -428,6 +431,8 @@ const electronApi: ElectronBridgeApi = {
         bounds: EmbeddedMpvBounds
     ): Promise<void> =>
         ipcRenderer.invoke('EMBEDDED_MPV_SET_BOUNDS', sessionId, bounds),
+    setEmbeddedMpvFill: (sessionId: string, fill: boolean): Promise<void> =>
+        ipcRenderer.invoke('EMBEDDED_MPV_SET_FILL', sessionId, fill),
     setEmbeddedMpvPaused: (
         sessionId: string,
         paused: boolean

apps/electron-backend/src/app/app.ts

@@ -317,13 +317,6 @@ export default class App {
     }
 
     private static attachWindowStateEvents(win: Electron.BrowserWindow): void {
-        // Only Windows/Linux render custom window controls that subscribe
-        // to these pushes; macOS keeps the native traffic lights, so
-        // sending state updates there would be dead IPC traffic.
-        if (process.platform === 'darwin') {
-            return;
-        }
-
         const sendWindowState = () => {
             if (win.isDestroyed()) {
                 return;
@@ -335,10 +328,18 @@ export default class App {
             });
         };
 
-        win.on('maximize', sendWindowState);
-        win.on('unmaximize', sendWindowState);
+        // Fullscreen state is needed on ALL platforms: the embedded-MPV player
+        // reconciles its in-app fullscreen presentation with OS-initiated exits
+        // (macOS green button / Ctrl+Cmd+F / ESC, which bypass the in-app button).
         win.on('enter-full-screen', sendWindowState);
         win.on('leave-full-screen', sendWindowState);
+
+        // The maximize pushes only drive the custom Windows/Linux title-bar
+        // controls; macOS uses native traffic lights, so they'd be dead traffic.
+        if (process.platform !== 'darwin') {
+            win.on('maximize', sendWindowState);
+            win.on('unmaximize', sendWindowState);
+        }
     }
 
     private static initMainWindow() {

apps/electron-backend/src/app/events/embedded-mpv.events.ts

@@ -8,6 +8,7 @@ import {
     EMBEDDED_MPV_SET_ASPECT,
     EMBEDDED_MPV_SET_AUDIO_TRACK,
     EMBEDDED_MPV_SET_BOUNDS,
+    EMBEDDED_MPV_SET_FILL,
     EMBEDDED_MPV_SET_PAUSED,
     EMBEDDED_MPV_SET_SPEED,
     EMBEDDED_MPV_SET_SUBTITLE_TRACK,
@@ -81,6 +82,11 @@ handleEmbeddedMpv(
         getService().setBounds(sessionId, bounds)
 );
 
+handleEmbeddedMpv(
+    EMBEDDED_MPV_SET_FILL,
+    (sessionId: string, fill: boolean) => getService().setFill(sessionId, fill)
+);
+
 handleEmbeddedMpv(
     EMBEDDED_MPV_SET_PAUSED,
     (sessionId: string, paused: boolean) =>

apps/electron-backend/src/app/events/window.events.spec.ts

@@ -20,6 +20,12 @@ jest.mock('electron', () => ({
     },
 }));
 
+const mockApp = { mainWindow: null as unknown };
+jest.mock('../app', () => ({
+    __esModule: true,
+    default: mockApp,
+}));
+
 function createFakeWindow(
     initial: { maximized?: boolean; fullScreen?: boolean } = {}
 ) {
@@ -59,6 +65,7 @@ describe('WindowEvents', () => {
             'WINDOW:CLOSE',
             'WINDOW:GET_STATE',
             'WINDOW:MINIMIZE',
+            'WINDOW:SET_FULLSCREEN',
             'WINDOW:TOGGLE_MAXIMIZE',
         ]);
     });
@@ -128,6 +135,34 @@ describe('WindowEvents', () => {
         });
     });
 
+    it('toggles real native fullscreen on the sender window', () => {
+        const win = createFakeWindow() as ReturnType<typeof createFakeWindow> & {
+            setFullScreen: jest.Mock;
+        };
+        win.setFullScreen = jest.fn();
+        mockFromWebContents.mockReturnValue(win);
+
+        mockHandlers.get('WINDOW:SET_FULLSCREEN')!(fakeEvent, true);
+        expect(win.setFullScreen).toHaveBeenCalledWith(true);
+
+        mockHandlers.get('WINDOW:SET_FULLSCREEN')!(fakeEvent, false);
+        expect(win.setFullScreen).toHaveBeenLastCalledWith(false);
+    });
+
+    it('is a safe no-op when the sender window is destroyed', () => {
+        const win = createFakeWindow() as ReturnType<typeof createFakeWindow> & {
+            setFullScreen: jest.Mock;
+        };
+        win.setFullScreen = jest.fn();
+        win.isDestroyed.mockReturnValue(true);
+        mockFromWebContents.mockReturnValue(win);
+
+        expect(() =>
+            mockHandlers.get('WINDOW:SET_FULLSCREEN')!(fakeEvent, true)
+        ).not.toThrow();
+        expect(win.setFullScreen).not.toHaveBeenCalled();
+    });
+
     it('treats a destroyed window like a missing window', () => {
         const win = createFakeWindow();
         win.isDestroyed.mockReturnValue(true);

apps/electron-backend/src/app/events/window.events.ts

@@ -10,6 +10,7 @@ import {
     WINDOW_CLOSE,
     WINDOW_GET_STATE,
     WINDOW_MINIMIZE,
+    WINDOW_SET_FULLSCREEN,
     WINDOW_TOGGLE_MAXIMIZE,
 } from '@iptvnator/shared/interfaces';
 
@@ -76,3 +77,11 @@ ipcMain.handle(WINDOW_CLOSE, (event) => {
 ipcMain.handle(WINDOW_GET_STATE, (event): WindowState => {
     return getWindowState(getSenderWindow(event));
 });
+
+// Real macOS native fullscreen (a dedicated Space, menu bar auto-hides) for the
+// embedded-MPV player. The renderer freezes the native video render during the
+// transition (the autoresizing surface scales the last frame, like a paused
+// video) so the system's fullscreen zoom animation doesn't snap the live frame.
+ipcMain.handle(WINDOW_SET_FULLSCREEN, (event, enabled: boolean) => {
+    getSenderWindow(event)?.setFullScreen(enabled);
+});

apps/electron-backend/src/app/services/embedded-mpv-native.service.ts

@@ -51,6 +51,7 @@ interface NativeEmbeddedMpvAddon {
     ): string;
     loadPlayback(sessionId: string, playback: ResolvedPortalPlayback): void;
     setBounds(sessionId: string, bounds: EmbeddedMpvBounds): void;
+    setFill?(sessionId: string, fill: boolean): void;
     setPaused(sessionId: string, paused: boolean): void;
     seek(sessionId: string, seconds: number): void;
     setVolume(sessionId: string, volume: number): void;
@@ -330,6 +331,16 @@ export class EmbeddedMpvNativeService {
         this.getAddon().setBounds(sessionId, bounds);
     }
 
+    /**
+     * Toggle fullscreen "fill" mode: the native view fills the window via an
+     * autoresizing mask and rides the window's resize animation so the video
+     * grows to full screen. No-op on older addons without `setFill`.
+     */
+    setFill(sessionId: string, fill: boolean): void {
+        this.assertEmbeddedMpvEnabled();
+        this.getAddon().setFill?.(sessionId, fill);
+    }
+
     setPaused(sessionId: string, paused: boolean): EmbeddedMpvSession | null {
         this.assertEmbeddedMpvEnabled();
         this.getAddon().setPaused(sessionId, paused);

docs/architecture/embedded-mpv-native.md

@@ -150,7 +150,7 @@ covers the embedded-MPV-specific native/session internals.
 
 The Angular side of the embedded MPV player is intentionally split so the player component stays a view-only orchestrator. The renderer files live under `libs/ui/playback/src/lib/embedded-mpv-player/`:
 
-- `embedded-mpv-session-controller.ts` — component-scoped `Injectable` that owns the `support`, `session`, `sessionId`, `stalled`, and `retryToken` signals. Subscribes to `onEmbeddedMpvSessionUpdate`, runs the polling-driven `stalled` timer, owns the bounds-sync (resize/scroll/RAF), exposes `setBoundsProvider` / `triggerBoundsSync`, and delegates transport/track/recording commands to `EmbeddedMpvCommandRunner`.
+- `embedded-mpv-session-controller.ts` — component-scoped `Injectable` that owns the `support`, `session`, `sessionId`, `stalled`, and `retryToken` signals. Subscribes to `onEmbeddedMpvSessionUpdate`, runs the polling-driven `stalled` timer, owns the bounds-sync (resize/scroll/RAF), exposes `setBoundsProvider` / `triggerBoundsSync` / `setFill`, and delegates transport/track/recording commands to `EmbeddedMpvCommandRunner`.
 - `embedded-mpv-command-runner.ts` — `EmbeddedMpvCommandRunner`: the imperative IPC command surface (`togglePaused`, `seekBy`/`seekTo`, `applyVolume`, `setAudioTrack`, `setSubtitleTrack`, `setSpeed`, `setAspect`, `startRecording`, `stopRecording`) with optimistic snapshot reconciliation.
 - `embedded-mpv-session-factory.ts` — pure session-snapshot constructors (`createLoadingSession`, `createAttachingSession`, `createErrorSession`) and `waitForStartupPaint`.
 - `embedded-mpv-compositor.ts` — `measureBounds(host)` and bounds helpers that keep the native surface aligned with the Angular layout.
@@ -159,13 +159,13 @@ The Angular side of the embedded MPV player is intentionally split so the player
 - `embedded-mpv-labels.ts` — label/format helpers (`formatTime`, audio/subtitle/speed/aspect/volume labels) and the preset constants.
 - `embedded-mpv-stalled-tracker.ts` — `EmbeddedMpvStalledTracker` driving the "taking longer than expected" state.
 - `embedded-mpv-controls.adapter.ts` — `EmbeddedMpvControlsAdapter`, the `PlayerController` implementation bound by `app-player-controls`.
-- `embedded-mpv-player.component.ts` — view-only shell. Holds view children, derived `computed` signals, DOM event listeners (pointermove, pointerdown, fullscreenchange, dblclick), and the `effect()`s (immersive activation, bounds→backdrop rect, session lifecycle, time/ended bridging).
+- `embedded-mpv-player.component.ts` — view-only shell. Holds view children, derived `computed` signals, DOM event listeners (pointermove, pointerdown, dblclick), a window-state subscription that reconciles OS-initiated fullscreen exits, and the `effect()`s (immersive activation, bounds→backdrop rect, session lifecycle, time/ended bridging).
 
 ### Shipped path: immersive overlay
 
 The shipped embedded-MPV player composites the libmpv surface **below** the WebContents (`NSWindowBelow`) and keeps it **always full-bleed** — the controller's default `measureBounds` provider; there are no docked or cutout bound shapes. Because the web layer is on top, modals, popovers, and the inline `app-player-controls` all paint and receive input normally — no off-screen "hide the surface" trick is needed. The app stays opaque via the single global backdrop with a transparent hole at the video rect (`EmbeddedMpvImmersiveService` + `embedded-mpv-immersive-backdrop`). The `setBoundsProvider` hook remains for a future docked / bottom-mini-bar mode but is unused on the current full-bleed path. The full immersive design, and the rationale for choosing it over the earlier (rejected) child-window and docked-above approaches, are documented in [player-controls-refactor.md](./player-controls-refactor.md).
 
-Fullscreen runs the controls component's built-in `ControlsFullscreen` against the player root element: the root goes DOM-fullscreen, the surrounding chrome is hidden via `body.embedded-mpv-fullscreen` (backdrop off) so the transparent fullscreen surface reveals the native video filling the screen, and the bounds sync re-measures the new viewport. See `player-controls-refactor.md` for the immersive-overlay design.
+Fullscreen uses real macOS **native fullscreen** of the Electron window (`setMainWindowFullScreen` → `win.setFullScreen`) via the player-controls `PlayerFullscreenController` delegate — not DOM `requestFullscreen`. On enter the native surface is put in autoresize "fill" mode with its render frozen during macOS's snapshot transition (the last frame scales cleanly; the video briefly pauses, as the HTML5 player also does), and OS-initiated exits (green button / Ctrl+Cmd+F / ESC) are reconciled through the window-state bridge. See `player-controls-refactor.md` for the full fullscreen choreography.
 
 ### Reactivity rules (signals and effects)