feat(shell): startup window mode, --fullscreen switch and F11 toggle (#1514)

Settings > General gains "Window on startup" (normal / maximized /
fullscreen), Electron only, mirrored into the main-process config by
SETTINGS_UPDATE and applied at the next window creation. `--fullscreen`
forces one fullscreen launch (consumed by the first window). F11 toggles
OS-level fullscreen through WINDOW:TOGGLE_FULLSCREEN — the exit path on
Windows/Linux where the title bar is hidden — and is skipped while the
player owns document.fullscreenElement.

attachWindowStateEvents tracks native and HTML fullscreen as two flags,
since Electron leaves only the HTML state when the window was already
natively fullscreen. macOS ignores the constructor `fullscreen` option on a
hidden window, so ready-to-show repeats the request after show(). Toggles
are decided by an observe-only, event-fed tracker
(native-fullscreen-transitions.ts), never against isFullScreen().

Closes #1455

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

libs/shared/interfaces/src/lib/electron-api.interface.ts

@@ -662,6 +662,12 @@ export interface ElectronBridgeApi {
     ) => () => void;
     minimizeWindow: () => Promise<void>;
     toggleMaximizeWindow: () => Promise<ElectronBridgeWindowState>;
+    /**
+     * Toggles OS-level window fullscreen (F11). Reports the requested state;
+     * the `onWindowStateChange` push stays authoritative once the window
+     * manager has acted.
+     */
+    toggleFullScreenWindow: () => Promise<ElectronBridgeWindowState>;
     closeWindow: () => Promise<void>;
     getWindowState: () => Promise<ElectronBridgeWindowState>;
     onWindowStateChange: (

libs/shared/interfaces/src/lib/ipc-commands.ts

@@ -129,6 +129,10 @@ export const PLAYBACK_SET_KEEP_AWAKE = 'PLAYBACK:SET_KEEP_AWAKE';
 // Window controls (custom title bar on Windows/Linux)
 export const WINDOW_MINIMIZE = 'WINDOW:MINIMIZE';
 export const WINDOW_TOGGLE_MAXIMIZE = 'WINDOW:TOGGLE_MAXIMIZE';
+// OS-level window fullscreen toggle (F11). The exit path from a fullscreen
+// launch on Windows/Linux, where the title bar is hidden and the custom
+// window controls hide themselves while fullscreen.
+export const WINDOW_TOGGLE_FULLSCREEN = 'WINDOW:TOGGLE_FULLSCREEN';
 export const WINDOW_CLOSE = 'WINDOW:CLOSE';
 export const WINDOW_GET_STATE = 'WINDOW:GET_STATE';
 export const WINDOW_STATE_CHANGED = 'WINDOW:STATE_CHANGED';

libs/shared/interfaces/src/lib/settings.interface.ts

@@ -39,6 +39,34 @@ export enum StartupBehavior {
     RestoreLastView = 'restore-last-view',
 }
 
+/**
+ * How the desktop window is presented when the app launches. Electron only.
+ *
+ * Persisted like every other setting in the renderer and mirrored into the
+ * main-process config file by the `SETTINGS_UPDATE` handler, because the
+ * window is created before the renderer exists — so a change applies on the
+ * next launch. `--fullscreen` on the command line forces `'fullscreen'` for
+ * that launch only, and F11 toggles fullscreen at any time.
+ */
+export type StartupWindowMode = 'normal' | 'maximized' | 'fullscreen';
+
+export const STARTUP_WINDOW_MODES: readonly StartupWindowMode[] = [
+    'normal',
+    'maximized',
+    'fullscreen',
+];
+
+/**
+ * Collapses anything that is not a known mode to `'normal'`. Shared by the
+ * renderer form and the main-process mirror so junk never reaches the
+ * config file or the window options.
+ */
+export function normalizeStartupWindowMode(value: unknown): StartupWindowMode {
+    return STARTUP_WINDOW_MODES.includes(value as StartupWindowMode)
+        ? (value as StartupWindowMode)
+        : 'normal';
+}
+
 export type CoverSize = 'small' | 'medium' | 'large';
 
 /** Rendering of the live EPG panel under the player. */
@@ -147,6 +175,12 @@ export interface Settings {
     showCaptions: boolean;
     showDashboard: boolean;
     startupBehavior: StartupBehavior;
+    /**
+     * Desktop window presentation at launch: normal (last size), maximized,
+     * or fullscreen. Electron only and applied on the next launch; a missing
+     * value means `'normal'`. F11 leaves or re-enters fullscreen.
+     */
+    startupWindowMode?: StartupWindowMode;
     /** Show the desktop footer bar for external playback status */
     showExternalPlaybackBar?: boolean;
     /** Strip country/group prefixes like "US | " or "UK - " from channel names */