@livepeer-frameworks/player-core 0.1.1 → 0.1.2

package/dist/esm/core/PlayerController.js

@@ -0,0 +1,2651 @@
+import { TypedEventEmitter } from './EventEmitter.js';
+import { GatewayClient } from './GatewayClient.js';
+import { StreamStateClient } from './StreamStateClient.js';
+import { globalPlayerManager, ensurePlayersRegistered } from './PlayerRegistry.js';
+import { ABRController } from './ABRController.js';
+import { InteractionController } from './InteractionController.js';
+import { MistReporter } from './MistReporter.js';
+import { QualityMonitor } from './QualityMonitor.js';
+import { MetaTrackManager } from './MetaTrackManager.js';
+import { isMediaStreamSource, supportsPlaybackRate, getLatencyTier, calculateLiveThresholds, calculateSeekableRange, canSeekStream, calculateIsNearLive } from './SeekingUtils.js';
+
+/**
+ * PlayerController.ts
+ *
+ * Main headless orchestrator for the player. This class encapsulates all business logic
+ * (gateway resolution, stream state polling, player selection/initialization) in a
+ * framework-agnostic manner.
+ *
+ * Both React and Vanilla wrappers use this class internally.
+ */
+// ============================================================================
+// Content Type Resolution Helpers
+// ============================================================================
+// ============================================================================
+// MistServer Source Type Mapping
+// ============================================================================
+/**
+ * Complete MistServer source type mapping
+ * Maps MistServer's `source[].type` field to player selection info
+ *
+ * type field = MIME type used for player selection
+ * hrn = human readable name for UI
+ * player = recommended player implementation
+ * supported = whether we have a working player for it
+ */
+const MIST_SOURCE_TYPES = {
+    // ===== VIDEO STREAMING (Primary) =====
+    "html5/application/vnd.apple.mpegurl": { hrn: "HLS (TS)", player: "hlsjs", supported: true },
+    "html5/application/vnd.apple.mpegurl;version=7": {
+        hrn: "HLS (CMAF)",
+        player: "hlsjs",
+        supported: true,
+    },
+    "dash/video/mp4": { hrn: "DASH", player: "dashjs", supported: true },
+    "html5/video/mp4": { hrn: "MP4 progressive", player: "native", supported: true },
+    "html5/video/webm": { hrn: "WebM progressive", player: "native", supported: true },
+    // ===== WEBSOCKET STREAMING =====
+    "ws/video/mp4": { hrn: "MP4 WebSocket", player: "mews", supported: true },
+    "wss/video/mp4": { hrn: "MP4 WebSocket (SSL)", player: "mews", supported: true },
+    "ws/video/webm": { hrn: "WebM WebSocket", player: "mews", supported: true },
+    "wss/video/webm": { hrn: "WebM WebSocket (SSL)", player: "mews", supported: true },
+    "ws/video/raw": { hrn: "Raw WebSocket", player: "webcodecs", supported: true },
+    "wss/video/raw": { hrn: "Raw WebSocket (SSL)", player: "webcodecs", supported: true },
+    "ws/video/h264": { hrn: "Annex B WebSocket", player: "webcodecs", supported: true },
+    "wss/video/h264": { hrn: "Annex B WebSocket (SSL)", player: "webcodecs", supported: true },
+    // ===== WEBRTC =====
+    whep: { hrn: "WebRTC (WHEP)", player: "native", supported: true },
+    webrtc: { hrn: "WebRTC (WebSocket)", player: "mist-webrtc", supported: true },
+    "mist/webrtc": { hrn: "MistServer WebRTC", player: "mist-webrtc", supported: true },
+    // ===== AUDIO ONLY =====
+    "html5/audio/aac": { hrn: "AAC progressive", player: "native", supported: true },
+    "html5/audio/mp3": { hrn: "MP3 progressive", player: "native", supported: true },
+    "html5/audio/flac": { hrn: "FLAC progressive", player: "native", supported: true },
+    "html5/audio/wav": { hrn: "WAV progressive", player: "native", supported: true },
+    // ===== SUBTITLES/TEXT =====
+    "html5/text/vtt": { hrn: "WebVTT subtitles", player: "track", supported: true },
+    "html5/text/plain": { hrn: "SRT subtitles", player: "track", supported: true },
+    // ===== IMAGES =====
+    "html5/image/jpeg": { hrn: "JPEG thumbnail", player: "image", supported: true },
+    // ===== METADATA =====
+    "html5/text/javascript": { hrn: "JSON metadata", player: "fetch", supported: true },
+    // ===== LEGACY/UNSUPPORTED =====
+    "html5/video/mpeg": { hrn: "TS progressive", player: "none", supported: false },
+    "html5/video/h264": { hrn: "Annex B progressive", player: "none", supported: false },
+    "html5/application/sdp": { hrn: "SDP", player: "none", supported: false },
+    "html5/application/vnd.ms-sstr+xml": {
+        hrn: "Smooth Streaming",
+        player: "none",
+        supported: false,
+    },
+    "flash/7": { hrn: "FLV", player: "none", supported: false },
+    "flash/10": { hrn: "RTMP", player: "none", supported: false },
+    "flash/11": { hrn: "HDS", player: "none", supported: false },
+    // ===== SERVER-SIDE ONLY =====
+    rtsp: { hrn: "RTSP", player: "none", supported: false },
+    srt: { hrn: "SRT", player: "none", supported: false },
+    dtsc: { hrn: "DTSC", player: "none", supported: false },
+};
+/**
+ * Map Gateway protocol names to MistServer MIME types
+ * Gateway outputs use simplified protocol names like "HLS", "WHEP"
+ * while MistServer uses full MIME types
+ */
+const PROTOCOL_TO_MIME = {
+    // Standard protocols
+    HLS: "html5/application/vnd.apple.mpegurl",
+    DASH: "dash/video/mp4",
+    MP4: "html5/video/mp4",
+    WEBM: "html5/video/webm",
+    WHEP: "whep",
+    WebRTC: "webrtc",
+    MIST_WEBRTC: "mist/webrtc", // MistServer native WebRTC signaling
+    // WebSocket variants
+    MEWS: "ws/video/mp4",
+    MEWS_WS: "ws/video/mp4",
+    MEWS_WSS: "wss/video/mp4",
+    MEWS_WEBM: "ws/video/webm",
+    MEWS_WEBM_SSL: "wss/video/webm",
+    RAW_WS: "ws/video/raw",
+    RAW_WSS: "wss/video/raw",
+    H264_WS: "ws/video/h264",
+    H264_WSS: "wss/video/h264",
+    // Audio
+    AAC: "html5/audio/aac",
+    MP3: "html5/audio/mp3",
+    FLAC: "html5/audio/flac",
+    WAV: "html5/audio/wav",
+    // Subtitles
+    VTT: "html5/text/vtt",
+    SRT: "html5/text/plain",
+    // CMAF variants
+    CMAF: "html5/application/vnd.apple.mpegurl;version=7",
+    HLS_CMAF: "html5/application/vnd.apple.mpegurl;version=7",
+    // Images
+    JPEG: "html5/image/jpeg",
+    JPG: "html5/image/jpeg",
+    // MistServer specific
+    HTTP: "html5/video/mp4", // Default HTTP is MP4
+    MIST_HTML: "mist/html",
+    PLAYER_JS: "mist/html",
+};
+/**
+ * Get the MIME type for a Gateway protocol name
+ */
+function getMimeTypeForProtocol(protocol) {
+    return PROTOCOL_TO_MIME[protocol] || PROTOCOL_TO_MIME[protocol.toUpperCase()] || protocol;
+}
+/**
+ * Get source type info for a MIME type
+ */
+function getSourceTypeInfo(mimeType) {
+    return MIST_SOURCE_TYPES[mimeType];
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+function mapCodecLabel(codecstr) {
+    const c = codecstr.toLowerCase();
+    if (c.startsWith("avc1"))
+        return "H264";
+    if (c.startsWith("hev1") || c.startsWith("hvc1"))
+        return "HEVC";
+    if (c.startsWith("av01"))
+        return "AV1";
+    if (c.startsWith("vp09"))
+        return "VP9";
+    if (c.startsWith("vp8"))
+        return "VP8";
+    if (c.startsWith("mp4a"))
+        return "AAC";
+    if (c.includes("opus"))
+        return "Opus";
+    if (c.includes("ec-3") || c.includes("ac3"))
+        return "AC3";
+    return codecstr;
+}
+// ============================================================================
+// Standalone Stream Info Builder
+// ============================================================================
+/**
+ * Build StreamInfo from Gateway ContentEndpoints.
+ *
+ * This function extracts playback sources and track information from
+ * the Gateway's resolved endpoint data. It handles:
+ * - Parsing `outputs` JSON string (GraphQL returns JSON scalar as string)
+ * - Converting output protocols to StreamSource format
+ * - Deriving track info from capabilities
+ *
+ * Use this for VOD/clip content where Gateway data is sufficient,
+ * without waiting for MistServer to load the stream.
+ *
+ * @param endpoints - ContentEndpoints from Gateway resolution
+ * @param contentId - Stream/content identifier
+ * @returns StreamInfo with sources and tracks, or null if no valid data
+ */
+function buildStreamInfoFromEndpoints(endpoints, contentId) {
+    const primary = endpoints.primary;
+    if (!primary)
+        return null;
+    // Parse outputs if it's a JSON string (GraphQL returns JSON scalar as string)
+    let outputs = {};
+    if (primary.outputs) {
+        if (typeof primary.outputs === "string") {
+            try {
+                outputs = JSON.parse(primary.outputs);
+            }
+            catch {
+                console.warn("[buildStreamInfoFromEndpoints] Failed to parse outputs JSON");
+                outputs = {};
+            }
+        }
+        else {
+            outputs = primary.outputs;
+        }
+    }
+    const sources = [];
+    const oKeys = Object.keys(outputs);
+    const attachMistSource = (html, playerJs) => {
+        if (!html && !playerJs)
+            return;
+        const src = {
+            url: html || playerJs || "",
+            type: "mist/html",
+            streamName: contentId,
+        };
+        if (playerJs) {
+            src.mistPlayerUrl = playerJs;
+        }
+        sources.push(src);
+    };
+    if (oKeys.length) {
+        const html = outputs["MIST_HTML"]?.url;
+        const pjs = outputs["PLAYER_JS"]?.url;
+        attachMistSource(html, pjs);
+        // Process all outputs using PROTOCOL_TO_MIME mapping
+        // Skip MIST_HTML and PLAYER_JS (already handled above)
+        const skipProtocols = new Set(["MIST_HTML", "PLAYER_JS"]);
+        for (const protocol of oKeys) {
+            if (skipProtocols.has(protocol))
+                continue;
+            const output = outputs[protocol];
+            if (!output?.url)
+                continue;
+            // Convert Gateway protocol name to MistServer MIME type
+            const mimeType = getMimeTypeForProtocol(protocol);
+            // Check if this source type is supported
+            const sourceInfo = getSourceTypeInfo(mimeType);
+            if (sourceInfo && !sourceInfo.supported) {
+                // Skip unsupported source types
+                continue;
+            }
+            sources.push({ url: output.url, type: mimeType });
+        }
+    }
+    else if (primary) {
+        // Fallback: single primary URL
+        sources.push({
+            url: primary.url,
+            type: primary.protocol || "mist/html",
+            streamName: contentId,
+        });
+    }
+    // Derive tracks from capabilities
+    const tracks = [];
+    const pushCodecTracks = (cap) => {
+        if (!cap)
+            return;
+        const codecs = cap.codecs || [];
+        const addTrack = (type, codecstr) => {
+            tracks.push({ type, codec: mapCodecLabel(codecstr), codecstring: codecstr });
+        };
+        codecs.forEach((c) => {
+            const lc = c.toLowerCase();
+            if (lc.startsWith("avc1") ||
+                lc.startsWith("hev1") ||
+                lc.startsWith("hvc1") ||
+                lc.startsWith("vp") ||
+                lc.startsWith("av01")) {
+                addTrack("video", c);
+            }
+            else if (lc.startsWith("mp4a") ||
+                lc.includes("opus") ||
+                lc.includes("vorbis") ||
+                lc.includes("ac3") ||
+                lc.includes("ec-3")) {
+                addTrack("audio", c);
+            }
+        });
+        if (!codecs.length) {
+            // Fallback codecs with valid codecstrings for cold-start playback
+            if (cap.hasVideo)
+                tracks.push({ type: "video", codec: "H264", codecstring: "avc1.42E01E" });
+            if (cap.hasAudio)
+                tracks.push({ type: "audio", codec: "AAC", codecstring: "mp4a.40.2" });
+        }
+    };
+    Object.values(outputs).forEach((out) => pushCodecTracks(out.capabilities));
+    if (!tracks.length) {
+        // Fallback with valid codecstring for cold-start playback
+        tracks.push({ type: "video", codec: "H264", codecstring: "avc1.42E01E" });
+    }
+    // Determine content type from metadata
+    const contentType = endpoints.metadata?.isLive === false ? "vod" : "live";
+    return sources.length ? { source: sources, meta: { tracks }, type: contentType } : null;
+}
+// ============================================================================
+// PlayerController Class
+// ============================================================================
+/**
+ * Headless player controller that manages the entire player lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const controller = new PlayerController({
+ *   contentId: 'pk_...', // playbackId (view key)
+ *   contentType: 'live',
+ *   gatewayUrl: 'https://gateway.example.com/graphql',
+ * });
+ *
+ * controller.on('stateChange', ({ state }) => console.log('State:', state));
+ * controller.on('ready', ({ videoElement }) => console.log('Ready!'));
+ *
+ * const container = document.getElementById('player');
+ * await controller.attach(container);
+ *
+ * // Later...
+ * controller.destroy();
+ * ```
+ */
+class PlayerController extends TypedEventEmitter {
+    constructor(config) {
+        super();
+        this.state = "booting";
+        this.lastEmittedState = null;
+        this.suppressPlayPauseEventsUntil = 0;
+        this.gatewayClient = null;
+        this.streamStateClient = null;
+        this.currentPlayer = null;
+        this.videoElement = null;
+        this.container = null;
+        this.endpoints = null;
+        this.streamInfo = null;
+        this.streamState = null;
+        /** Tracks parsed from MistServer JSON response (used for direct MistServer mode) */
+        this.mistTracks = null;
+        /** Gateway-seeded metadata (used as base for Mist enrichment) */
+        this.metadataSeed = null;
+        /** Merged metadata (gateway seed + Mist enrichment) */
+        this.metadata = null;
+        this.cleanupFns = [];
+        this.isDestroyed = false;
+        this.isAttached = false;
+        // ============================================================================
+        // Internal State Tracking (Phase A1)
+        // ============================================================================
+        this._isBuffering = false;
+        this._hasPlaybackStarted = false;
+        this._errorText = null;
+        this._isPassiveError = false;
+        this._isHoldingSpeed = false;
+        this._holdSpeed = 2;
+        this._isLoopEnabled = false;
+        this._currentPlayerInfo = null;
+        this._currentSourceInfo = null;
+        // One-shot force options (used once by selectCombo, then cleared)
+        this._pendingForceOptions = null;
+        // ============================================================================
+        // Error Handling State (Phase A3)
+        // ============================================================================
+        this._errorShownAt = 0;
+        this._errorCleared = false;
+        this._isTransitioning = false;
+        this._errorCount = 0;
+        this._lastErrorTime = 0;
+        // ============================================================================
+        // Stream State Tracking (Phase A4)
+        // ============================================================================
+        this._prevStreamIsOnline = undefined;
+        // ============================================================================
+        // Hover/Controls Visibility (Phase A5b)
+        // ============================================================================
+        this._isHovering = false;
+        this._hoverTimeout = null;
+        // ============================================================================
+        // Subtitles/Captions (Phase A5b audit)
+        // ============================================================================
+        this._subtitlesEnabled = false;
+        // ============================================================================
+        // Stall Detection (Phase A5b audit)
+        // ============================================================================
+        this._stallStartTime = 0;
+        // ============================================================================
+        // Seeking & Live Detection State (Centralized from wrappers)
+        // ============================================================================
+        this._seekableStart = 0;
+        this._liveEdge = 0;
+        this._canSeek = false;
+        this._isNearLive = true;
+        this._latencyTier = "medium";
+        this._liveThresholds = { exitLive: 15, enterLive: 5 };
+        this._buffered = null;
+        this._hasAudio = true;
+        this._lastVolume = 1;
+        this._supportsPlaybackRate = true;
+        this._isWebRTC = false;
+        // ============================================================================
+        // Sub-Controllers (Phase A2)
+        // ============================================================================
+        this.abrController = null;
+        this.interactionController = null;
+        this.mistReporter = null;
+        this.qualityMonitor = null;
+        this.metaTrackManager = null;
+        this._playbackQuality = null;
+        this.bootMs = Date.now();
+        this.config = config;
+        this.playerManager = config.playerManager || globalPlayerManager;
+        // Forward error handling events from PlayerManager
+        this.playerManager.on("protocolSwapped", (data) => this.emit("protocolSwapped", data));
+        this.playerManager.on("playbackFailed", (data) => this.emit("playbackFailed", data));
+        // Load loop state from localStorage
+        try {
+            if (typeof localStorage !== "undefined") {
+                this._isLoopEnabled = localStorage.getItem("frameworks-player-loop") === "true";
+            }
+        }
+        catch {
+            // localStorage not available
+        }
+    }
+    // ============================================================================
+    // Lifecycle Methods
+    // ============================================================================
+    /**
+     * Attach to a container element and start the player lifecycle.
+     * This is the main entry point after construction.
+     */
+    async attach(container) {
+        if (this.isDestroyed) {
+            throw new Error("PlayerController is destroyed and cannot be reused");
+        }
+        if (this.isAttached) {
+            this.log("Already attached, detaching first");
+            this.detach();
+        }
+        this.container = container;
+        this.isAttached = true;
+        this.setState("booting");
+        try {
+            // Ensure players are registered
+            ensurePlayersRegistered();
+            // Step 1: Resolve endpoints
+            await this.resolveEndpoints();
+            // Guard against zombie operations (React Strict Mode cleanup)
+            if (this.isDestroyed || !this.container) {
+                this.log("[attach] Aborted - controller destroyed during endpoint resolution");
+                return;
+            }
+            if (!this.endpoints?.primary) {
+                this.setState("no_endpoint", { gatewayStatus: "error" });
+                return;
+            }
+            // Step 2: Start stream state polling (for live content)
+            this.startStreamStatePolling();
+            // Step 3: Build StreamInfo and initialize player
+            this.streamInfo = this.buildStreamInfo(this.endpoints);
+            if (!this.streamInfo || this.streamInfo.source.length === 0) {
+                this.setState("error", { error: "No playable sources found" });
+                this.emit("error", { error: "No playable sources found" });
+                return;
+            }
+            // Guard again before player init (async boundary)
+            if (this.isDestroyed || !this.container) {
+                this.log("[attach] Aborted - controller destroyed before player init");
+                return;
+            }
+            await this.initializePlayer();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            this.setState("error", { error: message });
+            this.emit("error", { error: message });
+            // Even if initial resolution failed (e.g., stream offline), start polling
+            // so we can detect when the stream comes online and re-initialize
+            if (this.config.mistUrl && !this.streamStateClient) {
+                this.log("[attach] Starting stream polling despite resolution failure");
+                this.startStreamStatePolling();
+            }
+        }
+    }
+    /**
+     * Detach from the current container and clean up resources.
+     * The controller can be re-attached to a new container.
+     */
+    detach() {
+        this.cleanup();
+        this.clearHoverTimeout();
+        this.isAttached = false;
+        this.container = null;
+        this.endpoints = null;
+        this.streamInfo = null;
+        this.streamState = null;
+        this.metadataSeed = null;
+        this.metadata = null;
+        this.videoElement = null;
+        this.currentPlayer = null;
+        this.lastEmittedState = null;
+        this._isHovering = false;
+    }
+    /**
+     * Fully destroy the controller. Cannot be reused after this.
+     */
+    destroy() {
+        if (this.isDestroyed)
+            return;
+        this.detach();
+        this.setState("destroyed");
+        this.emit("destroyed", undefined);
+        this.removeAllListeners();
+        this.isDestroyed = true;
+    }
+    // ============================================================================
+    // State Getters
+    // ============================================================================
+    /** Get current player state */
+    getState() {
+        return this.state;
+    }
+    /** Get current stream state (for live streams) */
+    getStreamState() {
+        return this.streamState;
+    }
+    /** Get resolved endpoints */
+    getEndpoints() {
+        return this.endpoints;
+    }
+    /** Get content metadata (title, description, duration, etc.) */
+    getMetadata() {
+        return this.metadata ?? null;
+    }
+    // ============================================================================
+    // Metadata Merge (Gateway seed + Mist enrichment)
+    // ============================================================================
+    setMetadataSeed(seed) {
+        this.metadataSeed = seed ? { ...seed } : null;
+        this.refreshMergedMetadata();
+    }
+    refreshMergedMetadata() {
+        const seed = this.metadataSeed ? { ...this.metadataSeed } : null;
+        const mist = this.streamState?.streamInfo;
+        const streamStatus = this.streamState?.status;
+        if (!seed && !mist) {
+            this.metadata = null;
+            return;
+        }
+        const merged = seed ? { ...seed } : {};
+        if (mist) {
+            merged.mist = this.sanitizeMistInfo(mist);
+            if (mist.type) {
+                merged.contentType = mist.type;
+                merged.isLive = mist.type === "live";
+            }
+            if (streamStatus) {
+                merged.status = streamStatus;
+            }
+            if (mist.meta?.duration && (!merged.durationSeconds || merged.durationSeconds <= 0)) {
+                merged.durationSeconds = Math.round(mist.meta.duration);
+            }
+            if (mist.meta?.tracks) {
+                merged.tracks = this.buildMetadataTracks(mist.meta.tracks);
+            }
+        }
+        this.metadata = merged;
+    }
+    buildMetadataTracks(tracksObj) {
+        const tracks = [];
+        for (const [, trackData] of Object.entries(tracksObj)) {
+            const t = trackData;
+            const trackType = t.type;
+            if (trackType !== "video" && trackType !== "audio" && trackType !== "meta") {
+                continue;
+            }
+            const bitrate = typeof t.bps === "number" ? Math.round(t.bps) : undefined;
+            const fps = typeof t.fpks === "number" ? t.fpks / 1000 : undefined;
+            tracks.push({
+                type: trackType,
+                codec: t.codec,
+                width: t.width,
+                height: t.height,
+                bitrate,
+                fps,
+                channels: t.channels,
+                sampleRate: t.rate,
+            });
+        }
+        return tracks.length ? tracks : undefined;
+    }
+    sanitizeMistInfo(info) {
+        const sanitized = {
+            error: info.error,
+            on_error: info.on_error,
+            perc: info.perc,
+            type: info.type,
+            hasVideo: info.hasVideo,
+            hasAudio: info.hasAudio,
+            unixoffset: info.unixoffset,
+            lastms: info.lastms,
+        };
+        if (info.source) {
+            sanitized.source = info.source.map((src) => ({
+                url: src.url,
+                type: src.type,
+                priority: src.priority,
+                simul_tracks: src.simul_tracks,
+                relurl: src.relurl,
+            }));
+        }
+        if (info.meta) {
+            sanitized.meta = {
+                buffer_window: info.meta.buffer_window,
+                duration: info.meta.duration,
+                mistUrl: info.meta.mistUrl,
+            };
+            if (info.meta.tracks) {
+                const tracks = {};
+                for (const [key, track] of Object.entries(info.meta.tracks)) {
+                    tracks[key] = {
+                        type: track.type,
+                        codec: track.codec,
+                        width: track.width,
+                        height: track.height,
+                        bps: track.bps,
+                        fpks: track.fpks,
+                        codecstring: track.codecstring,
+                        firstms: track.firstms,
+                        lastms: track.lastms,
+                        lang: track.lang,
+                        idx: track.idx,
+                        channels: track.channels,
+                        rate: track.rate,
+                        size: track.size,
+                    };
+                }
+                sanitized.meta.tracks = tracks;
+            }
+        }
+        return sanitized;
+    }
+    /** Get stream info (sources + tracks for player selection) */
+    getStreamInfo() {
+        return this.streamInfo;
+    }
+    /** Get video element (null if not ready) */
+    getVideoElement() {
+        return this.videoElement;
+    }
+    /** Get current player instance */
+    getPlayer() {
+        return this.currentPlayer;
+    }
+    /** Check if player is ready */
+    isReady() {
+        return this.videoElement !== null;
+    }
+    // ============================================================================
+    // Extended State Getters (Phase A1)
+    // ============================================================================
+    /** Check if video is currently playing (not paused) */
+    isPlaying() {
+        const paused = this.currentPlayer?.isPaused?.() ?? this.videoElement?.paused ?? true;
+        return !paused;
+    }
+    /** Check if currently buffering */
+    isBuffering() {
+        return this._isBuffering;
+    }
+    /** Get current error message (null if no error) */
+    getError() {
+        return this._errorText;
+    }
+    /** Check if error is passive (video still playing despite error) */
+    isPassiveError() {
+        return this._isPassiveError;
+    }
+    /** Check if playback has ever started (for idle screen logic) */
+    hasPlaybackStarted() {
+        return this._hasPlaybackStarted;
+    }
+    /** Check if currently holding for speed boost */
+    isHoldingSpeed() {
+        return this._isHoldingSpeed;
+    }
+    /** Get current hold speed value */
+    getHoldSpeed() {
+        return this._holdSpeed;
+    }
+    /** Get current player implementation info */
+    getCurrentPlayerInfo() {
+        return this._currentPlayerInfo;
+    }
+    /** Get current source info (URL and type) */
+    getCurrentSourceInfo() {
+        return this._currentSourceInfo;
+    }
+    /** Get current volume (0-1) */
+    getVolume() {
+        return this.videoElement?.volume ?? 1;
+    }
+    /** Check if loop mode is enabled */
+    isLoopEnabled() {
+        return this._isLoopEnabled;
+    }
+    /** Check if subtitles/captions are enabled */
+    isSubtitlesEnabled() {
+        return this._subtitlesEnabled;
+    }
+    /** Set subtitles/captions enabled state */
+    setSubtitlesEnabled(enabled) {
+        if (this._subtitlesEnabled === enabled)
+            return;
+        this._subtitlesEnabled = enabled;
+        // Apply to video text tracks if available
+        if (this.videoElement) {
+            const tracks = this.videoElement.textTracks;
+            for (let i = 0; i < tracks.length; i++) {
+                const track = tracks[i];
+                if (track.kind === "subtitles" || track.kind === "captions") {
+                    track.mode = enabled ? "showing" : "hidden";
+                }
+            }
+        }
+        this.emit("captionsChange", { enabled });
+    }
+    /** Toggle subtitles/captions */
+    toggleSubtitles() {
+        this.setSubtitlesEnabled(!this._subtitlesEnabled);
+    }
+    // ============================================================================
+    // Seeking & Live State Getters (Centralized from wrappers)
+    // ============================================================================
+    /** Get start of seekable range (seconds) */
+    getSeekableStart() {
+        return this._seekableStart;
+    }
+    /** Get live edge / end of seekable range (seconds) */
+    getLiveEdge() {
+        return this._liveEdge;
+    }
+    /** Check if seeking is currently available */
+    canSeekStream() {
+        return this._canSeek;
+    }
+    /** Check if playback is near the live edge (for live badge display) */
+    isNearLive() {
+        return this._isNearLive;
+    }
+    /** Get buffered ranges, preferring player override when available */
+    getBufferedRanges() {
+        if (this.currentPlayer && typeof this.currentPlayer.getBufferedRanges === "function") {
+            return this.currentPlayer.getBufferedRanges();
+        }
+        return this.videoElement?.buffered ?? null;
+    }
+    /** Get current latency tier based on protocol */
+    getLatencyTier() {
+        return this._latencyTier;
+    }
+    /** Get live thresholds for entering/exiting "LIVE" state */
+    getLiveThresholds() {
+        return this._liveThresholds;
+    }
+    /** Get buffered time ranges */
+    getBuffered() {
+        return this._buffered;
+    }
+    /** Check if stream has audio track */
+    hasAudioTrack() {
+        return this._hasAudio;
+    }
+    /** Check if playback rate adjustment is supported */
+    canAdjustPlaybackRate() {
+        return this._supportsPlaybackRate;
+    }
+    /** Resolve content type from config override or Gateway metadata */
+    getResolvedContentType() {
+        if (this.config.contentType) {
+            return this.config.contentType;
+        }
+        const metadata = this.getMetadata();
+        const metaType = metadata?.contentType?.toLowerCase();
+        if (metaType === "live" || metaType === "clip" || metaType === "dvr" || metaType === "vod") {
+            return metaType;
+        }
+        const mistType = this.streamState?.streamInfo?.type;
+        if (mistType === "live" || mistType === "vod") {
+            return mistType;
+        }
+        if (metadata?.isLive === true) {
+            return "live";
+        }
+        if (metadata?.isLive === false) {
+            return "vod";
+        }
+        return null;
+    }
+    /** Check if source is WebRTC/MediaStream */
+    isWebRTCSource() {
+        return this._isWebRTC;
+    }
+    /** Check if currently in fullscreen mode */
+    isFullscreen() {
+        if (typeof document === "undefined")
+            return false;
+        return document.fullscreenElement === this.container;
+    }
+    /** Check if content is effectively live (live or DVR still recording) */
+    isEffectivelyLive() {
+        const contentType = this.getResolvedContentType() ?? "live";
+        const metadata = this.getMetadata();
+        // Explicit VOD content types are never live
+        if (contentType === "vod" || contentType === "clip") {
+            return false;
+        }
+        // If Gateway metadata says it's not live, trust it
+        if (metadata?.isLive === false) {
+            return false;
+        }
+        // DVR that's finished recording is not live
+        if (contentType === "dvr" && metadata?.dvrStatus === "completed") {
+            return false;
+        }
+        // Default: trust contentType or duration-based detection
+        return (contentType === "live" ||
+            (contentType === "dvr" && metadata?.dvrStatus === "recording") ||
+            !Number.isFinite(this.getDuration()));
+    }
+    /** Check if content is strictly live (not DVR/clip/vod) */
+    isLive() {
+        return (this.getResolvedContentType() ?? "live") === "live";
+    }
+    /**
+     * Check if content needs cold start (VOD-like loading).
+     * True for: clips, DVR (recording OR completed) - any stored/VOD content
+     * False for: live streams only (real-time MistServer stream)
+     * DVR-while-recording needs cold start because MistServer may not be serving the VOD yet
+     */
+    needsColdStart() {
+        const contentType = this.getResolvedContentType();
+        if (!contentType)
+            return true;
+        return contentType !== "live";
+    }
+    /**
+     * Check if we should show idle/loading screen.
+     * Logic:
+     * - For cold start content (VOD/DVR): Show loading only while waiting for Gateway sources
+     * - For live streams: Show loading while waiting for MistServer to come online
+     * - Never show idle after playback has started (unless explicit error)
+     */
+    shouldShowIdleScreen() {
+        // Never show idle after playback has started
+        if (this._hasPlaybackStarted)
+            return false;
+        if (this.needsColdStart()) {
+            // VOD content (clips, DVR recording or completed): DON'T wait for MistServer
+            // Use Gateway sources immediately - MistServer will cold start when player requests
+            // Show loading only while waiting for Gateway sources (not MistServer)
+            const sources = this.streamInfo?.source ?? [];
+            return sources.length === 0;
+        }
+        else {
+            // Live streams: Wait for MistServer online status
+            if (!this.streamState?.isOnline || this.streamState?.status !== "ONLINE") {
+                return true;
+            }
+            // Show loading if no stream info or sources
+            if (!this.streamInfo || (this.streamInfo.source?.length ?? 0) === 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Get the effective content type for playback mode selection.
+     * This ensures WHEP/WebRTC gets penalized for VOD content (no seek support)
+     * while HLS/MP4 are preferred for clips and completed DVR recordings.
+     */
+    getEffectiveContentType() {
+        return this.isEffectivelyLive() ? "live" : "vod";
+    }
+    // ============================================================================
+    // Hover/Controls Visibility (Phase A5b)
+    // ============================================================================
+    /** Check if user is currently hovering over the player */
+    isHovering() {
+        return this._isHovering;
+    }
+    /**
+     * Check if controls should be visible.
+     * Controls are visible when:
+     * - User is hovering over the player
+     * - Video is paused
+     * - There's an error
+     */
+    shouldShowControls() {
+        return this._isHovering || this.isPaused() || this._errorText !== null;
+    }
+    /**
+     * Handle mouse enter event - show controls immediately.
+     * Call this from your UI wrapper's onMouseEnter handler.
+     */
+    handleMouseEnter() {
+        this.clearHoverTimeout();
+        if (!this._isHovering) {
+            this._isHovering = true;
+            this.emit("hoverStart", undefined);
+        }
+    }
+    /**
+     * Handle mouse leave event - hide controls after delay.
+     * Call this from your UI wrapper's onMouseLeave handler.
+     */
+    handleMouseLeave() {
+        this.clearHoverTimeout();
+        this._hoverTimeout = setTimeout(() => {
+            if (this._isHovering) {
+                this._isHovering = false;
+                this.emit("hoverEnd", undefined);
+            }
+        }, PlayerController.HOVER_LEAVE_DELAY_MS);
+    }
+    /**
+     * Handle mouse move event - show controls and reset hide timer.
+     * Call this from your UI wrapper's onMouseMove handler.
+     */
+    handleMouseMove() {
+        if (!this._isHovering) {
+            this._isHovering = true;
+            this.emit("hoverStart", undefined);
+        }
+        // Reset hide timeout on any movement
+        this.clearHoverTimeout();
+        this._hoverTimeout = setTimeout(() => {
+            if (this._isHovering) {
+                this._isHovering = false;
+                this.emit("hoverEnd", undefined);
+            }
+        }, PlayerController.HOVER_HIDE_DELAY_MS);
+    }
+    /**
+     * Handle touch start event - show controls.
+     * Call this from your UI wrapper's onTouchStart handler.
+     */
+    handleTouchStart() {
+        this.handleMouseEnter();
+        // Reset hide timer for touch
+        this.clearHoverTimeout();
+        this._hoverTimeout = setTimeout(() => {
+            if (this._isHovering) {
+                this._isHovering = false;
+                this.emit("hoverEnd", undefined);
+            }
+        }, PlayerController.HOVER_HIDE_DELAY_MS);
+    }
+    /** Clear hover timeout */
+    clearHoverTimeout() {
+        if (this._hoverTimeout) {
+            clearTimeout(this._hoverTimeout);
+            this._hoverTimeout = null;
+        }
+    }
+    /** Get current playback rate */
+    getPlaybackRate() {
+        return this.videoElement?.playbackRate ?? 1;
+    }
+    /** Get playback quality metrics from QualityMonitor */
+    getPlaybackQuality() {
+        return this._playbackQuality;
+    }
+    /** Get current ABR mode */
+    getABRMode() {
+        return this.abrController?.getMode() ?? "auto";
+    }
+    /** Set ABR mode at runtime */
+    setABRMode(mode) {
+        this.abrController?.setMode(mode);
+    }
+    // ============================================================================
+    // Playback Control
+    // ============================================================================
+    /** Start playback */
+    async play() {
+        if (this.currentPlayer?.play) {
+            await this.currentPlayer.play();
+            return;
+        }
+        if (this.videoElement) {
+            await this.videoElement.play();
+        }
+    }
+    /** Pause playback */
+    pause() {
+        if (this.currentPlayer?.pause) {
+            this.currentPlayer.pause();
+            return;
+        }
+        this.videoElement?.pause();
+    }
+    /** Seek to time */
+    seek(time) {
+        // Use player-specific seek if available (for WebCodecs, MEWS, etc.)
+        if (this.currentPlayer?.seek) {
+            this.currentPlayer.seek(time);
+            return;
+        }
+        // Fallback to direct video element seek
+        if (this.videoElement) {
+            this.videoElement.currentTime = time;
+        }
+    }
+    /** Set volume (0-1). Dragging to 0 mutes, dragging above 0 unmutes. */
+    setVolume(volume) {
+        if (!this.videoElement)
+            return;
+        const newVolume = Math.max(0, Math.min(1, volume));
+        // Remember non-zero volumes for restore on unmute
+        if (newVolume > 0) {
+            this._lastVolume = newVolume;
+        }
+        // Dragging to 0 should mute, dragging above 0 should unmute
+        const shouldMute = newVolume === 0;
+        if (this.videoElement.muted !== shouldMute) {
+            this.videoElement.muted = shouldMute;
+            if (this.currentPlayer?.setMuted) {
+                this.currentPlayer.setMuted(shouldMute);
+            }
+        }
+        this.videoElement.volume = newVolume;
+        this.emit("volumeChange", { volume: newVolume, muted: shouldMute });
+    }
+    /** Set muted state. Unmuting restores the previous volume. */
+    setMuted(muted) {
+        if (!this.videoElement)
+            return;
+        if (muted) {
+            // Save current volume before muting (if non-zero)
+            if (this.videoElement.volume > 0) {
+                this._lastVolume = this.videoElement.volume;
+            }
+        }
+        if (this.currentPlayer?.setMuted) {
+            this.currentPlayer.setMuted(muted);
+        }
+        else {
+            this.videoElement.muted = muted;
+        }
+        // Restore volume when unmuting
+        if (!muted && this.videoElement.volume === 0) {
+            this.videoElement.volume = this._lastVolume;
+        }
+        this.emit("volumeChange", {
+            volume: muted ? 0 : this.videoElement.volume,
+            muted,
+        });
+    }
+    /** Set playback rate */
+    setPlaybackRate(rate) {
+        if (this.currentPlayer?.setPlaybackRate) {
+            this.currentPlayer.setPlaybackRate(rate);
+        }
+        else if (this.videoElement) {
+            this.videoElement.playbackRate = rate;
+        }
+        this.emit("speedChange", { rate });
+    }
+    /** Jump to live edge (for live streams) */
+    jumpToLive() {
+        // Try player-specific implementation first (WebCodecs uses server time)
+        if (this.currentPlayer?.jumpToLive) {
+            this.currentPlayer.jumpToLive();
+            const el = this.videoElement;
+            if (el && !isMediaStreamSource(el)) {
+                const target = this._liveEdge;
+                if (Number.isFinite(target) && target > 0) {
+                    // Fallback: if player-specific jump doesn't move, seek to computed live edge
+                    setTimeout(() => {
+                        if (!this.videoElement)
+                            return;
+                        const current = this.getEffectiveCurrentTime();
+                        if (target - current > 1) {
+                            try {
+                                this.videoElement.currentTime = target;
+                            }
+                            catch { }
+                        }
+                    }, 200);
+                }
+            }
+            this._isNearLive = true;
+            this.emitSeekingState();
+            return;
+        }
+        const el = this.videoElement;
+        if (!el)
+            return;
+        // For WebRTC/MediaStream: we're always at live, nothing to do
+        if (isMediaStreamSource(el)) {
+            this._isNearLive = true;
+            this.emitSeekingState();
+            return;
+        }
+        // Try browser's seekable range first (most reliable for HLS/DASH/MEWS)
+        if (el.seekable && el.seekable.length > 0) {
+            const liveEdge = el.seekable.end(el.seekable.length - 1);
+            if (Number.isFinite(liveEdge) && liveEdge > 0) {
+                el.currentTime = liveEdge;
+                this._isNearLive = true;
+                this.emitSeekingState();
+                return;
+            }
+        }
+        // Try our computed live edge (from MistServer metadata)
+        if (this._liveEdge > 0 && Number.isFinite(this._liveEdge)) {
+            el.currentTime = this._liveEdge;
+            this._isNearLive = true;
+            this.emitSeekingState();
+            return;
+        }
+        // Fallback: seek to duration (for VOD or finite-duration live)
+        if (Number.isFinite(el.duration) && el.duration > 0) {
+            el.currentTime = el.duration;
+            this._isNearLive = true;
+            this.emitSeekingState();
+        }
+    }
+    /** Emit current seeking state */
+    emitSeekingState() {
+        this.emit("seekingStateChange", {
+            seekableStart: this._seekableStart,
+            liveEdge: this._liveEdge,
+            canSeek: this._canSeek,
+            isNearLive: this._isNearLive,
+            isLive: this.isEffectivelyLive(),
+            isWebRTC: this._isWebRTC,
+            latencyTier: this._latencyTier,
+            buffered: this._buffered,
+            hasAudio: this._hasAudio,
+            supportsPlaybackRate: this._supportsPlaybackRate,
+        });
+    }
+    /** Request fullscreen */
+    async requestFullscreen() {
+        if (this.container) {
+            await this.container.requestFullscreen();
+        }
+    }
+    /** Request Picture-in-Picture */
+    async requestPiP() {
+        if (this.currentPlayer?.requestPiP) {
+            await this.currentPlayer.requestPiP();
+        }
+        else if (this.videoElement && "requestPictureInPicture" in this.videoElement) {
+            await this.videoElement.requestPictureInPicture();
+        }
+    }
+    /** Get available quality levels */
+    getQualities() {
+        return this.currentPlayer?.getQualities?.() ?? [];
+    }
+    /** Select a quality level */
+    selectQuality(id) {
+        this.currentPlayer?.selectQuality?.(id);
+    }
+    /** Get available text tracks */
+    getTextTracks() {
+        return this.currentPlayer?.getTextTracks?.() ?? [];
+    }
+    /** Select a text track */
+    selectTextTrack(id) {
+        this.currentPlayer?.selectTextTrack?.(id);
+    }
+    getEffectiveCurrentTime() {
+        if (this.currentPlayer && typeof this.currentPlayer.getCurrentTime === "function") {
+            const t = this.currentPlayer.getCurrentTime();
+            if (Number.isFinite(t))
+                return t;
+        }
+        return this.videoElement?.currentTime ?? 0;
+    }
+    getEffectiveDuration() {
+        if (this.currentPlayer && typeof this.currentPlayer.getDuration === "function") {
+            const d = this.currentPlayer.getDuration();
+            if (Number.isFinite(d) || d === Infinity)
+                return d;
+        }
+        return this.videoElement?.duration ?? NaN;
+    }
+    getPlayerSeekableRange() {
+        if (this.currentPlayer && typeof this.currentPlayer.getSeekableRange === "function") {
+            const range = this.currentPlayer.getSeekableRange();
+            if (range &&
+                Number.isFinite(range.start) &&
+                Number.isFinite(range.end) &&
+                range.end >= range.start) {
+                return range;
+            }
+        }
+        return null;
+    }
+    getFrameStepSecondsFromTracks() {
+        const tracks = this.streamInfo?.meta?.tracks;
+        if (!tracks || tracks.length === 0)
+            return undefined;
+        const videoTracks = tracks.filter((t) => t.type === "video" && typeof t.fpks === "number" && t.fpks > 0);
+        if (videoTracks.length === 0)
+            return undefined;
+        const fpks = Math.max(...videoTracks.map((t) => t.fpks));
+        if (!Number.isFinite(fpks) || fpks <= 0)
+            return undefined;
+        // fpks = frames per kilosecond => frame duration in seconds = 1000 / fpks
+        return 1000 / fpks;
+    }
+    deriveBufferWindowMsFromTracks(tracks) {
+        if (!tracks)
+            return undefined;
+        const trackList = Object.values(tracks);
+        if (trackList.length === 0)
+            return undefined;
+        const firstmsValues = trackList
+            .map((t) => t.firstms)
+            .filter((v) => v !== undefined);
+        const lastmsValues = trackList.map((t) => t.lastms).filter((v) => v !== undefined);
+        if (firstmsValues.length === 0 || lastmsValues.length === 0)
+            return undefined;
+        const firstms = Math.max(...firstmsValues);
+        const lastms = Math.min(...lastmsValues);
+        const window = lastms - firstms;
+        if (!Number.isFinite(window) || window <= 0)
+            return undefined;
+        return window;
+    }
+    /** Get current time */
+    getCurrentTime() {
+        return this.getEffectiveCurrentTime();
+    }
+    /** Get duration */
+    getDuration() {
+        return this.getEffectiveDuration();
+    }
+    /** Check if paused */
+    isPaused() {
+        return this.currentPlayer?.isPaused?.() ?? this.videoElement?.paused ?? true;
+    }
+    /** Suppress play/pause-driven UI updates for a short window */
+    suppressPlayPauseEvents(ms = 200) {
+        this.suppressPlayPauseEventsUntil = Date.now() + ms;
+    }
+    /** Check if play/pause UI updates should be suppressed */
+    shouldSuppressVideoEvents() {
+        return Date.now() < this.suppressPlayPauseEventsUntil;
+    }
+    /** Check if muted */
+    isMuted() {
+        return this.videoElement?.muted ?? true;
+    }
+    /** Skip backward by specified seconds (default 10) */
+    skipBack(seconds = 10) {
+        this.seekBy(-seconds);
+        this.emit("skipBackward", { seconds });
+    }
+    /** Skip forward by specified seconds (default 10) */
+    skipForward(seconds = 10) {
+        this.seekBy(seconds);
+        this.emit("skipForward", { seconds });
+    }
+    /** Toggle play/pause */
+    togglePlay() {
+        const isPaused = this.currentPlayer?.isPaused?.() ?? this.videoElement?.paused ?? true;
+        if (isPaused) {
+            if (this.currentPlayer?.play) {
+                this.currentPlayer.play().catch(() => { });
+            }
+            else {
+                this.videoElement?.play().catch(() => { });
+            }
+            return;
+        }
+        if (this.currentPlayer?.pause) {
+            this.currentPlayer.pause();
+        }
+        else {
+            this.videoElement?.pause();
+        }
+    }
+    /** Toggle mute */
+    toggleMute() {
+        if (this.videoElement) {
+            this.setMuted(!this.videoElement.muted);
+        }
+    }
+    /** Seek relative to current position */
+    seekBy(delta) {
+        const currentTime = this.getEffectiveCurrentTime();
+        const duration = this.getEffectiveDuration();
+        const newTime = currentTime + delta;
+        const maxTime = isFinite(duration) ? duration : currentTime + Math.abs(delta);
+        this.seek(Math.max(0, Math.min(maxTime, newTime)));
+    }
+    /** Seek to percentage (0-1) of duration */
+    seekPercent(percent) {
+        const duration = this.getEffectiveDuration();
+        if (isFinite(duration)) {
+            this.seek(duration * Math.max(0, Math.min(1, percent)));
+        }
+    }
+    /** Toggle loop mode */
+    toggleLoop() {
+        this._isLoopEnabled = !this._isLoopEnabled;
+        if (this.videoElement) {
+            this.videoElement.loop = this._isLoopEnabled;
+        }
+        // Persist to localStorage
+        try {
+            if (typeof localStorage !== "undefined") {
+                localStorage.setItem("frameworks-player-loop", String(this._isLoopEnabled));
+            }
+        }
+        catch {
+            // localStorage not available
+        }
+        this.emit("loopChange", { isLoopEnabled: this._isLoopEnabled });
+    }
+    /** Set loop mode */
+    setLoopEnabled(enabled) {
+        if (this._isLoopEnabled === enabled)
+            return;
+        this._isLoopEnabled = enabled;
+        if (this.videoElement) {
+            this.videoElement.loop = enabled;
+        }
+        try {
+            if (typeof localStorage !== "undefined") {
+                localStorage.setItem("frameworks-player-loop", String(enabled));
+            }
+        }
+        catch { }
+        this.emit("loopChange", { isLoopEnabled: enabled });
+    }
+    /** Clear current error */
+    clearError() {
+        this._errorText = null;
+        this._isPassiveError = false;
+        this._errorCleared = true;
+    }
+    // ============================================================================
+    // Seeking & Live State Update (Centralized from wrappers)
+    // ============================================================================
+    /**
+     * Update seeking and live detection state.
+     * Called on timeupdate and progress events.
+     * Emits seekingStateChange event when values change.
+     */
+    updateSeekingState() {
+        const el = this.videoElement;
+        if (!el)
+            return;
+        const currentTime = this.getEffectiveCurrentTime();
+        const duration = this.getEffectiveDuration();
+        const isLive = this.isEffectivelyLive();
+        const sourceType = this._currentSourceInfo?.type;
+        const mistStreamInfo = this.streamState?.streamInfo;
+        // Update WebRTC detection
+        const wasWebRTC = this._isWebRTC;
+        this._isWebRTC = isMediaStreamSource(el);
+        // Update playback rate support
+        this._supportsPlaybackRate = supportsPlaybackRate(el);
+        // Update latency tier based on source type
+        this._latencyTier = sourceType
+            ? getLatencyTier(sourceType)
+            : this._isWebRTC
+                ? "ultra-low"
+                : "medium";
+        // Update live thresholds (with buffer window scaling)
+        const bufferWindowMs = mistStreamInfo?.meta?.buffer_window ??
+            this.deriveBufferWindowMsFromTracks(mistStreamInfo?.meta?.tracks);
+        this._liveThresholds = calculateLiveThresholds(sourceType, this._isWebRTC, bufferWindowMs);
+        // Calculate seekable range using centralized logic (allow player overrides)
+        const playerRange = this.getPlayerSeekableRange();
+        const allowMediaStreamDvr = isMediaStreamSource(el) &&
+            bufferWindowMs !== undefined &&
+            bufferWindowMs > 0 &&
+            sourceType !== "whep" &&
+            sourceType !== "webrtc";
+        const { seekableStart, liveEdge } = playerRange
+            ? { seekableStart: playerRange.start, liveEdge: playerRange.end }
+            : calculateSeekableRange({
+                isLive,
+                video: el,
+                mistStreamInfo,
+                currentTime,
+                duration,
+                allowMediaStreamDvr,
+            });
+        // Update can seek - pass player's canSeek if available (e.g., WebCodecs uses server commands)
+        const playerCanSeek = this.currentPlayer && typeof this.currentPlayer.canSeek === "function"
+            ? () => this.currentPlayer.canSeek()
+            : undefined;
+        this._canSeek = canSeekStream({
+            video: el,
+            isLive,
+            duration,
+            bufferWindowMs,
+            playerCanSeek,
+        });
+        // Update buffered ranges
+        this._buffered = el.buffered.length > 0 ? el.buffered : null;
+        // Check if values changed
+        const seekableChanged = this._seekableStart !== seekableStart || this._liveEdge !== liveEdge;
+        this._seekableStart = seekableStart;
+        this._liveEdge = liveEdge;
+        // Update interaction controller live-only state (allow DVR shortcuts when seekable window exists)
+        const hasDvrWindow = isLive &&
+            Number.isFinite(liveEdge) &&
+            Number.isFinite(seekableStart) &&
+            liveEdge > seekableStart;
+        const isLiveOnly = isLive && !hasDvrWindow;
+        this.interactionController?.updateConfig({
+            isLive: isLiveOnly,
+            frameStepSeconds: this.getFrameStepSecondsFromTracks(),
+        });
+        // Update isNearLive using hysteresis
+        if (isLive) {
+            const newIsNearLive = calculateIsNearLive(currentTime, liveEdge, this._liveThresholds, this._isNearLive);
+            if (newIsNearLive !== this._isNearLive) {
+                this._isNearLive = newIsNearLive;
+            }
+        }
+        else {
+            this._isNearLive = true; // Always "at live" for VOD
+        }
+        // Emit event for wrappers to consume
+        // Only emit if something meaningful changed to avoid spam
+        if (seekableChanged || wasWebRTC !== this._isWebRTC) {
+            this.emit("seekingStateChange", {
+                seekableStart: this._seekableStart,
+                liveEdge: this._liveEdge,
+                canSeek: this._canSeek,
+                isNearLive: this._isNearLive,
+                isLive,
+                isWebRTC: this._isWebRTC,
+                latencyTier: this._latencyTier,
+                buffered: this._buffered,
+                hasAudio: this._hasAudio,
+                supportsPlaybackRate: this._supportsPlaybackRate,
+            });
+        }
+    }
+    /**
+     * Detect audio tracks on the video element.
+     * Called after video metadata is loaded.
+     */
+    detectAudioTracks() {
+        const el = this.videoElement;
+        if (!el)
+            return;
+        // Check MediaStream audio tracks
+        if (el.srcObject instanceof MediaStream) {
+            const audioTracks = el.srcObject.getAudioTracks();
+            this._hasAudio = audioTracks.length > 0;
+            return;
+        }
+        // Check HTML5 audio tracks (if available)
+        // audioTracks is only available in some browsers (Safari, Edge)
+        const elWithAudio = el;
+        if (elWithAudio.audioTracks && elWithAudio.audioTracks.length !== undefined) {
+            this._hasAudio = elWithAudio.audioTracks.length > 0;
+            return;
+        }
+        // Default to true if we can't detect
+        this._hasAudio = true;
+    }
+    // ============================================================================
+    // Error Handling (Phase A3)
+    // ============================================================================
+    /**
+     * Attempt to clear error automatically if playback is progressing.
+     * Called on timeupdate, playing, and canplay events.
+     */
+    attemptClearError() {
+        if (!this._errorText || this._errorCleared)
+            return;
+        const now = Date.now();
+        const elapsed = now - this._errorShownAt;
+        if (elapsed >= PlayerController.AUTO_CLEAR_ERROR_DELAY_MS) {
+            this._errorCleared = true;
+            this._errorText = null;
+            this._isPassiveError = false;
+            this.log("Error auto-cleared after playback resumed");
+            this.emit("errorCleared", undefined);
+        }
+    }
+    /**
+     * Check if we should attempt playback fallback due to hard failure.
+     * Returns true if:
+     * - Error count exceeds threshold (5+) within time window (60s)
+     * - Error contains fatal keywords
+     * - Sustained stall for 30+ seconds
+     */
+    shouldAttemptFallback(error) {
+        const now = Date.now();
+        // Track error count within window
+        if (now - this._lastErrorTime > PlayerController.HARD_FAILURE_ERROR_WINDOW_MS) {
+            this._errorCount = 0; // Reset counter if outside window
+        }
+        this._errorCount++;
+        this._lastErrorTime = now;
+        // Check for repeated errors (5+ errors within 60s)
+        if (this._errorCount >= PlayerController.HARD_FAILURE_ERROR_THRESHOLD) {
+            this.log(`Hard failure: repeated errors (${this._errorCount})`);
+            return true;
+        }
+        // Check for fatal error keywords
+        const lowerError = error.toLowerCase();
+        for (const keyword of PlayerController.FATAL_ERROR_KEYWORDS) {
+            if (lowerError.includes(keyword)) {
+                this.log(`Hard failure: fatal keyword "${keyword}" detected`);
+                return true;
+            }
+        }
+        // Check for sustained stall (30+ seconds of continuous buffering)
+        if (this._stallStartTime > 0) {
+            const stallDuration = now - this._stallStartTime;
+            if (stallDuration >= PlayerController.HARD_FAILURE_STALL_THRESHOLD_MS) {
+                this.log(`Hard failure: sustained stall for ${stallDuration}ms`);
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Set error with passive mode support.
+     * - Ignores errors during player transitions
+     * - Marks error as passive if video is still playing
+     * - Attempts automatic fallback on hard failures
+     */
+    async setPassiveError(error) {
+        // Ignore errors during player switching transitions (old player cleanup can fire errors)
+        if (this._isTransitioning) {
+            this.log(`Ignoring error during player transition: ${error}`);
+            return;
+        }
+        // Check if video is still playing (passive error scenario)
+        const video = this.videoElement;
+        const isVideoPlaying = video && !video.paused && video.currentTime > 0;
+        // Attempt fallback on hard failures before showing error UI
+        if (this.shouldAttemptFallback(error) && this.playerManager.canAttemptFallback()) {
+            this.log("Attempting playback fallback...");
+            this._isTransitioning = true;
+            const fallbackSucceeded = await this.playerManager.tryPlaybackFallback();
+            this._isTransitioning = false;
+            if (fallbackSucceeded) {
+                // Fallback succeeded - clear error state and reset counters
+                this._errorCount = 0;
+                this._errorText = null;
+                this._isPassiveError = false;
+                this.log("Fallback succeeded");
+                return;
+            }
+            // Fallback failed or exhausted - fall through to show error
+            this.log("Fallback exhausted, showing error UI");
+        }
+        // Set error state
+        this._errorShownAt = Date.now();
+        this._errorCleared = false;
+        this._errorText = error;
+        this._isPassiveError = isVideoPlaying ?? false;
+        this.setState("error", { error });
+        this.emit("error", { error });
+    }
+    /**
+     * Retry playback with fallback to next player/source.
+     * Returns true if a fallback option was available and attempted.
+     */
+    async retryWithFallback() {
+        if (!this.playerManager.canAttemptFallback()) {
+            return false;
+        }
+        this._isTransitioning = true;
+        const success = await this.playerManager.tryPlaybackFallback();
+        this._isTransitioning = false;
+        if (success) {
+            this._errorCount = 0;
+            this.clearError();
+        }
+        return success;
+    }
+    /** Toggle fullscreen */
+    async toggleFullscreen() {
+        if (typeof document === "undefined")
+            return;
+        if (document.fullscreenElement) {
+            await document.exitFullscreen().catch(() => { });
+        }
+        else if (this.container) {
+            await this.container.requestFullscreen().catch(() => { });
+        }
+    }
+    /** Toggle Picture-in-Picture */
+    async togglePictureInPicture() {
+        if (typeof document === "undefined")
+            return;
+        if (document.pictureInPictureElement) {
+            await document.exitPictureInPicture().catch(() => { });
+        }
+        else if (this.videoElement && "requestPictureInPicture" in this.videoElement) {
+            await this.videoElement.requestPictureInPicture().catch(() => { });
+        }
+    }
+    /** Check if Picture-in-Picture is supported */
+    isPiPSupported() {
+        if (typeof document === "undefined")
+            return false;
+        return document.pictureInPictureEnabled ?? false;
+    }
+    /** Check if currently in Picture-in-Picture mode */
+    isPiPActive() {
+        if (typeof document === "undefined")
+            return false;
+        return document.pictureInPictureElement === this.videoElement;
+    }
+    // ============================================================================
+    // Advanced Control
+    // ============================================================================
+    /** Force a retry of the current playback */
+    async retry() {
+        if (!this.container || !this.streamInfo)
+            return;
+        try {
+            this.playerManager.destroy();
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        this.container.innerHTML = "";
+        this.videoElement = null;
+        this.currentPlayer = null;
+        try {
+            await this.initializePlayer();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Retry failed";
+            this.setState("error", { error: message });
+            this.emit("error", { error: message });
+        }
+    }
+    /** Get playback statistics */
+    async getStats() {
+        return this.currentPlayer?.getStats?.();
+    }
+    /** Get current latency (for live streams) */
+    async getLatency() {
+        return this.currentPlayer?.getLatency?.();
+    }
+    // ============================================================================
+    // Runtime Configuration (Phase A5)
+    // ============================================================================
+    /**
+     * Update configuration at runtime without full re-initialization.
+     * Only certain options can be updated without re-init.
+     */
+    updateConfig(partialConfig) {
+        if (partialConfig.debug !== undefined) {
+            this.config.debug = partialConfig.debug;
+        }
+        if (partialConfig.autoplay !== undefined) {
+            this.config.autoplay = partialConfig.autoplay;
+        }
+        if (partialConfig.muted !== undefined) {
+            this.config.muted = partialConfig.muted;
+            if (this.videoElement) {
+                this.videoElement.muted = partialConfig.muted;
+            }
+        }
+    }
+    /**
+     * Force a complete re-initialization with current config.
+     * Stops and re-initializes the entire player.
+     */
+    async reload() {
+        if (!this.container || this.isDestroyed)
+            return;
+        const container = this.container;
+        this.detach();
+        await this.attach(container);
+    }
+    /**
+     * Select a specific player/source combination (one-shot).
+     * Used by DevModePanel to manually pick a combo.
+     *
+     * Note: This is a ONE-SHOT selection. The force settings are used for
+     * the next initialization only. If that player fails, normal fallback
+     * logic proceeds without the force settings.
+     */
+    async selectCombo(options) {
+        const container = this.container;
+        if (!container)
+            return;
+        this.log(`[selectCombo] One-shot selection: player=${options.forcePlayer}, type=${options.forceType}, source=${options.forceSource}`);
+        // Store as one-shot options (will be cleared after use)
+        this._pendingForceOptions = {
+            forcePlayer: options.forcePlayer,
+            forceType: options.forceType,
+            forceSource: options.forceSource,
+        };
+        // Detach and re-attach - initializePlayer will use pending options once
+        this.detach();
+        await this.attach(container);
+    }
+    /**
+     * Set playback mode preference.
+     * Unlike selectCombo, this is a persistent preference that affects scoring.
+     */
+    setPlaybackMode(mode) {
+        this.config.playbackMode = mode;
+        this.log(`[setPlaybackMode] Mode set to: ${mode}`);
+    }
+    /**
+     * @deprecated Use selectCombo() for one-shot selection or setPlaybackMode() for mode changes.
+     * This method exists for backwards compatibility but may override fallback behavior.
+     */
+    async setDevModeOptions(options) {
+        // Update playback mode if provided (this is a persistent preference)
+        if (options.playbackMode) {
+            this.setPlaybackMode(options.playbackMode);
+        }
+        // Use selectCombo for the force settings (one-shot)
+        if (options.forcePlayer !== undefined ||
+            options.forceType !== undefined ||
+            options.forceSource !== undefined) {
+            await this.selectCombo({
+                forcePlayer: options.forcePlayer,
+                forceType: options.forceType,
+                forceSource: options.forceSource,
+            });
+        }
+        else if (options.playbackMode) {
+            // Mode-only change, trigger reload
+            const container = this.container;
+            if (container) {
+                this.detach();
+                await this.attach(container);
+            }
+        }
+    }
+    /**
+     * Get metadata update payload for external consumers.
+     * Combines current state into a single metadata object.
+     */
+    getMetadataPayload() {
+        const video = this.videoElement;
+        const bufferedAhead = video && video.buffered.length > 0
+            ? video.buffered.end(video.buffered.length - 1) - video.currentTime
+            : 0;
+        return {
+            currentTime: video?.currentTime ?? 0,
+            duration: video?.duration ?? NaN,
+            bufferedAhead: Math.max(0, bufferedAhead),
+            qualityScore: this._playbackQuality?.score,
+            playerInfo: this._currentPlayerInfo ?? undefined,
+            sourceInfo: this._currentSourceInfo ?? undefined,
+            isLive: this.isEffectivelyLive(),
+            isBuffering: this._isBuffering,
+            isPaused: video?.paused ?? true,
+            volume: video?.volume ?? 1,
+            muted: video?.muted ?? true,
+        };
+    }
+    /**
+     * Emit a metadata update event with current state.
+     * Useful for periodic telemetry/reporting.
+     */
+    emitMetadataUpdate() {
+        this.emit("metadataUpdate", this.getMetadataPayload());
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    async resolveEndpoints() {
+        const { endpoints, gatewayUrl, mistUrl, contentId, authToken } = this.config;
+        // Priority 1: Use pre-resolved endpoints if provided
+        if (endpoints?.primary) {
+            this.endpoints = endpoints;
+            this.setMetadataSeed(endpoints.metadata ?? null);
+            this.setState("gateway_ready", { gatewayStatus: "ready" });
+            return;
+        }
+        // Priority 2: Direct MistServer resolution (playground/standalone mode)
+        if (mistUrl) {
+            await this.resolveFromMistServer(mistUrl, contentId);
+            return;
+        }
+        // Priority 3: Gateway resolution
+        if (gatewayUrl) {
+            await this.resolveFromGateway(gatewayUrl, contentId, authToken);
+            return;
+        }
+        throw new Error("No endpoints provided and no gatewayUrl or mistUrl configured");
+    }
+    /**
+     * Resolve endpoints directly from MistServer (bypasses Gateway)
+     * Fetches json_{contentId}.js and builds ContentEndpoints from source array
+     */
+    async resolveFromMistServer(mistUrl, contentId) {
+        this.setState("gateway_loading", { gatewayStatus: "loading" });
+        try {
+            let baseUrl = mistUrl;
+            while (baseUrl.endsWith("/"))
+                baseUrl = baseUrl.slice(0, -1);
+            const jsonUrl = `${baseUrl}/json_${encodeURIComponent(contentId)}.js`;
+            this.log(`[resolveFromMistServer] Fetching ${jsonUrl}`);
+            const response = await fetch(jsonUrl, { cache: "no-store" });
+            if (!response.ok) {
+                throw new Error(`MistServer HTTP ${response.status}`);
+            }
+            // MistServer can return JSONP: callback({...}); - strip wrapper if present
+            let text = await response.text();
+            const jsonpMatch = text.match(/^[^(]+\(([\s\S]*)\);?$/);
+            if (jsonpMatch) {
+                text = jsonpMatch[1];
+            }
+            const data = JSON.parse(text);
+            if (data.error) {
+                throw new Error(data.error);
+            }
+            const sources = Array.isArray(data.source)
+                ? data.source
+                : [];
+            if (sources.length === 0) {
+                throw new Error("No sources available from MistServer");
+            }
+            // Build outputs map from all sources
+            const outputs = {};
+            for (const source of sources) {
+                const protocol = this.mapMistTypeToProtocol(source.type);
+                if (!outputs[protocol]) {
+                    outputs[protocol] = { protocol, url: source.url };
+                }
+            }
+            // Select primary source (prefer HLS/DASH over WebSocket-based)
+            const httpSources = sources.filter((s) => !s.url.startsWith("ws://"));
+            const primarySource = httpSources.length > 0 ? this.selectBestSource(httpSources) : sources[0];
+            const primary = {
+                nodeId: `mist-${contentId}`,
+                protocol: this.mapMistTypeToProtocol(primarySource.type),
+                url: primarySource.url,
+                baseUrl: mistUrl,
+                outputs,
+            };
+            this.endpoints = { primary, fallbacks: [] };
+            this.setMetadataSeed(null);
+            // Parse track metadata from MistServer response
+            if (data.meta?.tracks && typeof data.meta.tracks === "object") {
+                const tracks = this.parseMistTracks(data.meta.tracks);
+                this.mistTracks = tracks.length > 0 ? tracks : null;
+                this.log(`[resolveFromMistServer] Parsed ${tracks.length} tracks from MistServer`);
+            }
+            this.setState("gateway_ready", { gatewayStatus: "ready" });
+            this.log(`[resolveFromMistServer] Resolved: ${primary.protocol} @ ${primary.url}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "MistServer resolution failed";
+            this.setState("gateway_error", { gatewayStatus: "error", error: message });
+            throw error;
+        }
+    }
+    /**
+     * Map MistServer type to protocol identifier
+     */
+    mapMistTypeToProtocol(mistType) {
+        // WebCodecs raw streams - check BEFORE generic ws/ catch-all
+        if (mistType === "ws/video/raw")
+            return "RAW_WS";
+        if (mistType === "wss/video/raw")
+            return "RAW_WSS";
+        // Annex B H264 over WebSocket (video-only, uses same 12-byte header as raw)
+        if (mistType === "ws/video/h264")
+            return "H264_WS";
+        if (mistType === "wss/video/h264")
+            return "H264_WSS";
+        // WebM over WebSocket - check BEFORE generic ws/ catch-all
+        if (mistType === "ws/video/webm")
+            return "MEWS_WEBM";
+        if (mistType === "wss/video/webm")
+            return "MEWS_WEBM_SSL";
+        // MEWS MP4 over WebSocket - catch remaining ws/* types (defaults to mp4)
+        if (mistType.startsWith("ws/"))
+            return "MEWS_WS";
+        if (mistType.startsWith("wss/"))
+            return "MEWS_WSS";
+        if (mistType.includes("webrtc"))
+            return "MIST_WEBRTC";
+        if (mistType.includes("mpegurl") || mistType.includes("m3u8"))
+            return "HLS";
+        if (mistType.includes("dash") || mistType.includes("mpd"))
+            return "DASH";
+        if (mistType.includes("whep"))
+            return "WHEP";
+        if (mistType.includes("mp4"))
+            return "MP4";
+        if (mistType.includes("webm"))
+            return "WEBM";
+        return mistType;
+    }
+    /**
+     * Select best source based on protocol priority
+     */
+    selectBestSource(sources) {
+        const priority = {
+            HLS: 1,
+            DASH: 2,
+            MP4: 3,
+            WEBM: 4,
+            WHEP: 5,
+            MIST_WEBRTC: 6,
+            MEWS_WS: 99,
+        };
+        return sources.sort((a, b) => {
+            const pa = priority[this.mapMistTypeToProtocol(a.type)] ?? 50;
+            const pb = priority[this.mapMistTypeToProtocol(b.type)] ?? 50;
+            return pa - pb;
+        })[0];
+    }
+    /**
+     * Resolve endpoints from Gateway GraphQL API
+     */
+    async resolveFromGateway(gatewayUrl, contentId, authToken) {
+        this.setState("gateway_loading", { gatewayStatus: "loading" });
+        this.gatewayClient = new GatewayClient({
+            gatewayUrl,
+            contentId,
+            authToken,
+        });
+        // Subscribe to status changes
+        const unsub = this.gatewayClient.on("statusChange", ({ status, error }) => {
+            if (status === "error") {
+                this.setState("gateway_error", { gatewayStatus: status, error });
+            }
+        });
+        this.cleanupFns.push(unsub);
+        this.cleanupFns.push(() => this.gatewayClient?.destroy());
+        try {
+            this.endpoints = await this.gatewayClient.resolve();
+            this.setMetadataSeed(this.endpoints?.metadata ?? null);
+            this.setState("gateway_ready", { gatewayStatus: "ready" });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Gateway resolution failed";
+            this.setState("gateway_error", { gatewayStatus: "error", error: message });
+            throw error;
+        }
+    }
+    startStreamStatePolling() {
+        const { contentId, mistUrl } = this.config;
+        const contentType = this.getResolvedContentType();
+        // Only poll for live-like content. DVR should only poll while recording.
+        // If contentType is unknown but mistUrl is provided, still poll so we can
+        // detect when a stream comes online and initialize playback.
+        if (contentType == null) {
+            if (!mistUrl)
+                return;
+        }
+        else if (contentType !== "live" && contentType !== "dvr") {
+            return;
+        }
+        if (contentType === "dvr") {
+            const dvrStatus = this.getMetadata()?.dvrStatus;
+            if (dvrStatus && dvrStatus !== "recording")
+                return;
+        }
+        // Use endpoint baseUrl if available, otherwise fall back to config.mistUrl
+        // This allows polling to start even when initial endpoint resolution failed
+        const mistBaseUrl = this.endpoints?.primary?.baseUrl || mistUrl;
+        if (!mistBaseUrl)
+            return;
+        // Use playback ID from metadata if available
+        const metadata = this.getMetadata();
+        const streamName = metadata?.contentId || contentId;
+        // For effectively live content, use WebSocket for real-time updates
+        // For completed VOD content, use HTTP polling only
+        const useWebSocket = this.isEffectivelyLive();
+        const pollInterval = this.isEffectivelyLive() ? 3000 : 5000;
+        this.streamStateClient = new StreamStateClient({
+            mistBaseUrl,
+            streamName,
+            useWebSocket,
+            pollInterval,
+        });
+        // Subscribe to state changes
+        const unsubState = this.streamStateClient.on("stateChange", ({ state }) => {
+            const wasOnline = this._prevStreamIsOnline;
+            const isNowOnline = state.isOnline;
+            this.streamState = state;
+            this._prevStreamIsOnline = isNowOnline;
+            // Update track metadata if MistServer provides better data
+            // This handles cold-start: Gateway gives fallback codecs, MistServer gives real ones
+            if (state.streamInfo?.meta?.tracks && this.streamInfo) {
+                const mistTracks = this.parseMistTracks(state.streamInfo.meta.tracks);
+                if (mistTracks.length > 0) {
+                    this.streamInfo.meta.tracks = mistTracks;
+                    this.log(`[stateChange] Updated ${mistTracks.length} tracks from MistServer`);
+                }
+            }
+            // Merge Mist metadata into the unified metadata surface
+            this.refreshMergedMetadata();
+            this.emit("streamStateChange", { state });
+            // Auto-play when stream transitions from offline to online
+            // This handles the case where user is watching IdleScreen and stream comes online
+            if (wasOnline === false && isNowOnline === true && this.isEffectivelyLive()) {
+                this.log("Stream came online, triggering auto-play");
+                if (this.videoElement) {
+                    // Player already initialized - just play
+                    this.videoElement
+                        .play()
+                        .catch((e) => this.log(`Auto-play on online transition failed: ${e}`));
+                }
+                else if (this.container && !this.endpoints?.primary) {
+                    // Player wasn't initialized because stream was offline - re-attempt full initialization
+                    this.log("Stream came online, attempting late initialization");
+                    this.initializeLateFromStreamState(state.streamInfo);
+                }
+            }
+        });
+        this.cleanupFns.push(unsubState);
+        this.cleanupFns.push(() => this.streamStateClient?.destroy());
+        this.streamStateClient.start();
+    }
+    /**
+     * Initialize player late when stream comes online after initial attach failed.
+     * Uses MistStreamInfo from stream state polling instead of re-fetching.
+     */
+    async initializeLateFromStreamState(streamInfo) {
+        if (!streamInfo?.source ||
+            !Array.isArray(streamInfo.source) ||
+            streamInfo.source.length === 0) {
+            this.log("[initializeLateFromStreamState] No sources in stream info");
+            return;
+        }
+        if (!this.container || !this.config.mistUrl) {
+            this.log("[initializeLateFromStreamState] Missing container or mistUrl");
+            return;
+        }
+        try {
+            const sources = streamInfo.source;
+            const mistUrl = this.config.mistUrl;
+            const contentId = this.config.contentId;
+            // Build outputs map from all sources
+            const outputs = {};
+            for (const source of sources) {
+                const protocol = this.mapMistTypeToProtocol(source.type);
+                if (!outputs[protocol]) {
+                    outputs[protocol] = { protocol, url: source.url };
+                }
+            }
+            // Select primary source (prefer HLS/DASH over WebSocket-based)
+            const httpSources = sources.filter((s) => !s.url.startsWith("ws://"));
+            const primarySource = httpSources.length > 0 ? this.selectBestSource(httpSources) : sources[0];
+            const primary = {
+                nodeId: `mist-${contentId}`,
+                protocol: this.mapMistTypeToProtocol(primarySource.type),
+                url: primarySource.url,
+                baseUrl: mistUrl,
+                outputs,
+            };
+            this.endpoints = { primary, fallbacks: [] };
+            this.setMetadataSeed(this.endpoints.metadata ?? null);
+            // Parse track metadata from stream info
+            if (streamInfo.meta?.tracks && typeof streamInfo.meta.tracks === "object") {
+                const tracks = this.parseMistTracks(streamInfo.meta.tracks);
+                this.mistTracks = tracks.length > 0 ? tracks : null;
+                this.log(`[initializeLateFromStreamState] Parsed ${tracks.length} tracks`);
+            }
+            this.setState("gateway_ready", { gatewayStatus: "ready" });
+            this.log(`[initializeLateFromStreamState] Built endpoints from stream state: ${primary.protocol}`);
+            // Build StreamInfo and initialize player
+            this.streamInfo = this.buildStreamInfo(this.endpoints);
+            if (!this.streamInfo || this.streamInfo.source.length === 0) {
+                this.setState("error", { error: "No playable sources found" });
+                return;
+            }
+            await this.initializePlayer();
+            this.log("[initializeLateFromStreamState] Player initialized successfully");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Late initialization failed";
+            this.log(`[initializeLateFromStreamState] Failed: ${message}`);
+            this.setState("error", { error: message });
+        }
+    }
+    buildStreamInfo(endpoints) {
+        // Delegate to standalone exported function
+        const info = buildStreamInfoFromEndpoints(endpoints, this.config.contentId);
+        // If we have tracks from direct MistServer resolution, use those instead
+        // (they have accurate codecstring and init data for proper codec detection)
+        if (info && this.mistTracks && this.mistTracks.length > 0) {
+            info.meta.tracks = this.mistTracks;
+            this.log(`[buildStreamInfo] Using ${this.mistTracks.length} tracks from MistServer`);
+        }
+        return info;
+    }
+    /**
+     * Parse MistServer track metadata from the tracks object.
+     * MistServer returns tracks as a Record keyed by track name (e.g., "video_H264_800x600_25fps_1").
+     * This converts to our StreamTrack[] format with codecstring and init data.
+     */
+    parseMistTracks(tracksObj) {
+        const tracks = [];
+        for (const [, trackData] of Object.entries(tracksObj)) {
+            const t = trackData;
+            const trackType = t.type;
+            if (trackType === "video" || trackType === "audio" || trackType === "meta") {
+                tracks.push({
+                    type: trackType,
+                    codec: t.codec,
+                    codecstring: t.codecstring,
+                    init: t.init,
+                    idx: t.idx,
+                    width: t.width,
+                    height: t.height,
+                    fpks: t.fpks,
+                    channels: t.channels,
+                    rate: t.rate,
+                    size: t.size,
+                });
+            }
+        }
+        return tracks;
+    }
+    async initializePlayer() {
+        const container = this.container;
+        const streamInfo = this.streamInfo;
+        this.log(`[initializePlayer] Starting - container: ${!!container}, streamInfo: ${!!streamInfo}, sources: ${streamInfo?.source?.length ?? 0}`);
+        if (!container || !streamInfo) {
+            throw new Error("Container or streamInfo not available");
+        }
+        // Log source details for debugging
+        this.log(`[initializePlayer] Sources: ${JSON.stringify(streamInfo.source.map((s) => ({ type: s.type, url: s.url.slice(0, 60) + "..." })))}`);
+        this.log(`[initializePlayer] Tracks: ${streamInfo.meta.tracks.map((t) => `${t.type}:${t.codec}`).join(", ")}`);
+        const { autoplay, muted, controls, poster } = this.config;
+        // Clear container
+        container.innerHTML = "";
+        // Listen for player selection
+        const onSelected = (e) => {
+            // Track current player info
+            const playerImpl = this.playerManager
+                .getRegisteredPlayers()
+                .find((p) => p.capability.shortname === e.player);
+            if (playerImpl) {
+                this._currentPlayerInfo = {
+                    name: playerImpl.capability.name,
+                    shortname: playerImpl.capability.shortname,
+                };
+            }
+            // Track current source info
+            if (e.source) {
+                this._currentSourceInfo = {
+                    url: e.source.url,
+                    type: e.source.type,
+                };
+            }
+            this.setState("connecting", {
+                selectedPlayer: e.player,
+                selectedProtocol: (e.source?.type || "").toString(),
+                endpointUrl: e.source?.url,
+            });
+            // Bubble up playerSelected event
+            this.emit("playerSelected", { player: e.player, source: e.source, score: e.score });
+        };
+        try {
+            this.playerManager.on?.("playerSelected", onSelected);
+        }
+        catch { }
+        this.cleanupFns.push(() => {
+            try {
+                this.playerManager.off?.("playerSelected", onSelected);
+            }
+            catch { }
+        });
+        this.setState("selecting_player");
+        const playerOptions = {
+            autoplay: autoplay !== false,
+            muted: muted !== false,
+            controls: controls !== false,
+            poster: poster,
+            debug: this.config.debug,
+            onReady: (el) => {
+                // Guard against zombie callbacks after destroy
+                if (this.isDestroyed || !this.container) {
+                    this.log("[initializePlayer] onReady callback aborted - controller destroyed");
+                    return;
+                }
+                // Defensive: some flows (e.g. failed fallback attempt) can temporarily detach
+                // the current video element from the container while playback continues.
+                // Ensure the element is actually attached for rendering.
+                try {
+                    if (this.container && !this.container.contains(el)) {
+                        this.log("[initializePlayer] Video element was detached; re-attaching to container");
+                        this.container.appendChild(el);
+                    }
+                }
+                catch { }
+                this.videoElement = el;
+                this.currentPlayer = this.playerManager.getCurrentPlayer();
+                this.setupVideoEventListeners(el);
+                // Initialize sub-controllers after video is ready
+                this.initializeSubControllers();
+                this.emit("ready", { videoElement: el });
+            },
+            onTimeUpdate: (_t) => {
+                if (this.isDestroyed)
+                    return;
+                // Defensive: keep video element attached even if some other lifecycle cleared the container.
+                // (Playback can continue even when detached, which looks like "audio only".)
+                try {
+                    if (this.container && this.videoElement && !this.container.contains(this.videoElement)) {
+                        this.log("[initializePlayer] Video element was detached during playback; re-attaching to container");
+                        this.container.appendChild(this.videoElement);
+                    }
+                }
+                catch { }
+                this.emit("timeUpdate", {
+                    currentTime: this.getEffectiveCurrentTime(),
+                    duration: this.getEffectiveDuration(),
+                });
+            },
+            onError: (err) => {
+                if (this.isDestroyed)
+                    return;
+                const message = typeof err === "string" ? err : String(err);
+                // Use setPassiveError for smart error handling with fallback support
+                this.setPassiveError(message);
+            },
+        };
+        // Manager options for player selection
+        // Use pending force options (one-shot from selectCombo) if available, otherwise use config
+        const pendingForce = this._pendingForceOptions;
+        this._pendingForceOptions = null; // Clear immediately - one-shot only
+        const managerOptions = {
+            // One-shot force options take precedence, then fall back to config
+            forcePlayer: pendingForce?.forcePlayer ?? this.config.forcePlayer,
+            forceType: pendingForce?.forceType ?? this.config.forceType,
+            forceSource: pendingForce?.forceSource ?? this.config.forceSource,
+            // Playback mode is a persistent preference
+            playbackMode: this.config.playbackMode,
+        };
+        this.log(`[initializePlayer] Calling playerManager.initializePlayer...`);
+        this.log(`[initializePlayer] Manager options: ${JSON.stringify(managerOptions)} (pending force: ${pendingForce ? "yes" : "no"})`);
+        try {
+            await this.playerManager.initializePlayer(container, streamInfo, playerOptions, managerOptions);
+            this.log(`[initializePlayer] Player initialized successfully`);
+        }
+        catch (e) {
+            this.log(`[initializePlayer] Player initialization FAILED: ${e}`);
+            throw e;
+        }
+    }
+    setupVideoEventListeners(el) {
+        // Apply loop setting
+        el.loop = this._isLoopEnabled;
+        const onWaiting = () => {
+            this._isBuffering = true;
+            // Start stall timer if not already started
+            if (this._stallStartTime === 0) {
+                this._stallStartTime = Date.now();
+                this.log("Stall started");
+            }
+            this.setState("buffering");
+        };
+        const onPlaying = () => {
+            if (this.shouldSuppressVideoEvents())
+                return;
+            this._isBuffering = false;
+            this._hasPlaybackStarted = true;
+            // Clear stall timer on successful playback
+            if (this._stallStartTime > 0) {
+                this.log(`Stall cleared after ${Date.now() - this._stallStartTime}ms`);
+                this._stallStartTime = 0;
+            }
+            this.setState("playing");
+            // Attempt to clear error on playback resume
+            this.attemptClearError();
+        };
+        const onCanPlay = () => {
+            this._isBuffering = false;
+            // Clear stall timer on canplay
+            this._stallStartTime = 0;
+            this.setState("playing");
+            // Attempt to clear error on canplay
+            this.attemptClearError();
+        };
+        const onPause = () => {
+            if (this.shouldSuppressVideoEvents())
+                return;
+            this.setState("paused");
+        };
+        const onEnded = () => this.setState("ended");
+        const onError = () => {
+            const message = el.error ? el.error.message || "Playback error" : "Playback error";
+            // Use setPassiveError for smart error handling with fallback support
+            this.setPassiveError(message);
+        };
+        const onTimeUpdate = () => {
+            this.emit("timeUpdate", {
+                currentTime: this.getEffectiveCurrentTime(),
+                duration: this.getEffectiveDuration(),
+            });
+            // Update seeking state (seekable range, isNearLive, etc.)
+            this.updateSeekingState();
+            // Attempt to clear error when playback is progressing
+            if (this.getEffectiveCurrentTime() > 0) {
+                this.attemptClearError();
+            }
+        };
+        const onDurationChange = () => {
+            this.emit("timeUpdate", {
+                currentTime: this.getEffectiveCurrentTime(),
+                duration: this.getEffectiveDuration(),
+            });
+            // Update seeking state on duration change
+            this.updateSeekingState();
+        };
+        const onProgress = () => {
+            // Update buffered ranges
+            this._buffered = el.buffered;
+            // Recalculate seeking state when buffer updates
+            this.updateSeekingState();
+        };
+        const onLoadedMetadata = () => {
+            // Detect audio tracks and WebRTC source
+            this.detectAudioTracks();
+            this._isWebRTC = isMediaStreamSource(el);
+            this._supportsPlaybackRate = !this._isWebRTC;
+            // Initial seeking state calculation
+            this.updateSeekingState();
+        };
+        // Fullscreen change handler
+        const onFullscreenChange = () => {
+            const isFullscreen = document.fullscreenElement === this.container;
+            this.emit("fullscreenChange", { isFullscreen });
+        };
+        // PiP change handlers
+        const onEnterPiP = () => this.emit("pipChange", { isPiP: true });
+        const onLeavePiP = () => this.emit("pipChange", { isPiP: false });
+        // Volume change handler (for external changes, e.g., via native controls)
+        const onVolumeChange = () => {
+            this.emit("volumeChange", { volume: el.volume, muted: el.muted });
+        };
+        el.addEventListener("waiting", onWaiting);
+        el.addEventListener("playing", onPlaying);
+        el.addEventListener("canplay", onCanPlay);
+        el.addEventListener("pause", onPause);
+        el.addEventListener("ended", onEnded);
+        el.addEventListener("error", onError);
+        el.addEventListener("timeupdate", onTimeUpdate);
+        el.addEventListener("durationchange", onDurationChange);
+        el.addEventListener("progress", onProgress);
+        el.addEventListener("loadedmetadata", onLoadedMetadata);
+        el.addEventListener("volumechange", onVolumeChange);
+        el.addEventListener("enterpictureinpicture", onEnterPiP);
+        el.addEventListener("leavepictureinpicture", onLeavePiP);
+        document.addEventListener("fullscreenchange", onFullscreenChange);
+        this.cleanupFns.push(() => {
+            el.removeEventListener("waiting", onWaiting);
+            el.removeEventListener("playing", onPlaying);
+            el.removeEventListener("canplay", onCanPlay);
+            el.removeEventListener("pause", onPause);
+            el.removeEventListener("ended", onEnded);
+            el.removeEventListener("error", onError);
+            el.removeEventListener("timeupdate", onTimeUpdate);
+            el.removeEventListener("durationchange", onDurationChange);
+            el.removeEventListener("progress", onProgress);
+            el.removeEventListener("loadedmetadata", onLoadedMetadata);
+            el.removeEventListener("volumechange", onVolumeChange);
+            el.removeEventListener("enterpictureinpicture", onEnterPiP);
+            el.removeEventListener("leavepictureinpicture", onLeavePiP);
+            document.removeEventListener("fullscreenchange", onFullscreenChange);
+        });
+    }
+    // ============================================================================
+    // Sub-Controller Initialization (Phase A2)
+    // ============================================================================
+    initializeSubControllers() {
+        if (!this.videoElement || !this.container)
+            return;
+        // Initialize ABRController
+        this.initializeABRController();
+        // Initialize QualityMonitor
+        this.initializeQualityMonitor();
+        // Initialize InteractionController
+        this.initializeInteractionController();
+        // Initialize MistReporter (needs WebSocket from StreamStateClient)
+        this.initializeMistReporter();
+        // Initialize MetaTrackManager
+        this.initializeMetaTrackManager();
+    }
+    initializeABRController() {
+        const player = this.currentPlayer;
+        if (!player || !this.videoElement)
+            return;
+        this.abrController = new ABRController({
+            options: { mode: "auto" },
+            getQualities: () => player.getQualities?.() ?? [],
+            selectQuality: (id) => player.selectQuality?.(id),
+            getCurrentQuality: () => {
+                const qualities = player.getQualities?.() ?? [];
+                const currentId = player.getCurrentQuality?.();
+                return qualities.find((q) => q.id === currentId) ?? null;
+            },
+            // Wire up bandwidth estimate from player stats
+            getBandwidthEstimate: async () => {
+                if (!this.currentPlayer?.getStats)
+                    return 0;
+                try {
+                    const stats = await this.currentPlayer.getStats();
+                    // HLS.js provides bandwidthEstimate directly
+                    if (stats?.bandwidthEstimate) {
+                        return stats.bandwidthEstimate;
+                    }
+                    // DASH.js provides throughput info
+                    if (stats?.averageThroughput) {
+                        return stats.averageThroughput;
+                    }
+                    return 0;
+                }
+                catch {
+                    return 0;
+                }
+            },
+            debug: this.config.debug,
+        });
+        this.abrController.start(this.videoElement);
+        this.cleanupFns.push(() => {
+            this.abrController?.stop();
+            this.abrController = null;
+        });
+    }
+    initializeQualityMonitor() {
+        if (!this.videoElement)
+            return;
+        this.qualityMonitor = new QualityMonitor({ sampleInterval: 1000 });
+        this.qualityMonitor.start(this.videoElement);
+        // Subscribe to quality updates
+        const handleQualityUpdate = () => {
+            if (this.qualityMonitor) {
+                this._playbackQuality = this.qualityMonitor.getCurrentQuality();
+                // Feed quality score to MistReporter
+                if (this.mistReporter && this._playbackQuality) {
+                    // Convert 0-100 score to MistPlayer-style 0-2.0 scale
+                    const mistScore = this._playbackQuality.score / 100;
+                    this.mistReporter.setPlaybackScore(mistScore);
+                }
+            }
+        };
+        // Sample quality periodically
+        const qualityInterval = setInterval(handleQualityUpdate, 1000);
+        this.cleanupFns.push(() => {
+            clearInterval(qualityInterval);
+            this.qualityMonitor?.stop();
+            this.qualityMonitor = null;
+        });
+    }
+    initializeInteractionController() {
+        if (!this.container || !this.videoElement)
+            return;
+        const isLive = this.isEffectivelyLive();
+        const hasDvrWindow = isLive &&
+            Number.isFinite(this._liveEdge) &&
+            Number.isFinite(this._seekableStart) &&
+            this._liveEdge > this._seekableStart;
+        const isLiveOnly = isLive && !hasDvrWindow;
+        const interactionContainer = this.container.closest('[data-player-container="true"]') ??
+            this.container;
+        this.interactionController = new InteractionController({
+            container: interactionContainer,
+            videoElement: this.videoElement,
+            isLive: isLiveOnly,
+            isPaused: () => this.currentPlayer?.isPaused?.() ?? this.videoElement?.paused ?? true,
+            frameStepSeconds: this.getFrameStepSecondsFromTracks(),
+            onFrameStep: (direction, seconds) => {
+                const player = this.currentPlayer ?? this.playerManager.getCurrentPlayer();
+                const playerName = player?.capability?.shortname ?? this._currentPlayerInfo?.shortname ?? "unknown";
+                const hasFrameStep = typeof player?.frameStep === "function";
+                this.log(`[interaction] frameStep dir=${direction} player=${playerName} hasFrameStep=${hasFrameStep}`);
+                if (playerName === "webcodecs") {
+                    this.suppressPlayPauseEvents(250);
+                }
+                if (hasFrameStep && player && player.frameStep) {
+                    player.frameStep(direction, seconds);
+                    return true;
+                }
+                return false;
+            },
+            onPlayPause: () => this.togglePlay(),
+            onSeek: (delta) => {
+                // End any speed hold before seeking
+                if (this._isHoldingSpeed) {
+                    this._isHoldingSpeed = false;
+                    this.emit("holdSpeedEnd", undefined);
+                }
+                this.seekBy(delta);
+                // Emit skip events
+                if (delta > 0) {
+                    this.emit("skipForward", { seconds: delta });
+                }
+                else {
+                    this.emit("skipBackward", { seconds: Math.abs(delta) });
+                }
+            },
+            onVolumeChange: (delta) => {
+                if (this.videoElement) {
+                    const newVolume = Math.max(0, Math.min(1, this.videoElement.volume + delta));
+                    this.videoElement.volume = newVolume;
+                    this.emit("volumeChange", { volume: newVolume, muted: this.videoElement.muted });
+                }
+            },
+            onMuteToggle: () => this.toggleMute(),
+            onFullscreenToggle: () => this.toggleFullscreen(),
+            onCaptionsToggle: () => {
+                this.toggleSubtitles();
+            },
+            onSpeedChange: (speed, isHolding) => {
+                const wasHolding = this._isHoldingSpeed;
+                this._isHoldingSpeed = isHolding;
+                this._holdSpeed = speed;
+                this.setPlaybackRate(speed);
+                // Emit holdSpeed events on state transitions
+                if (isHolding && !wasHolding) {
+                    this.emit("holdSpeedStart", { speed });
+                }
+                else if (!isHolding && wasHolding) {
+                    this.emit("holdSpeedEnd", undefined);
+                }
+            },
+            onSeekPercent: (percent) => this.seekPercent(percent),
+            speedHoldValue: this._holdSpeed,
+        });
+        this.interactionController.attach();
+        this.cleanupFns.push(() => {
+            this.interactionController?.detach();
+            this.interactionController = null;
+        });
+    }
+    initializeMistReporter() {
+        if (!this.streamStateClient)
+            return;
+        const socket = this.streamStateClient.getSocket();
+        if (!socket)
+            return;
+        this.mistReporter = new MistReporter({
+            socket,
+            bootMs: this.bootMs,
+            reportInterval: 5000,
+        });
+        // Initialize with video element
+        if (this.videoElement) {
+            this.mistReporter.init(this.videoElement, this.container ?? undefined);
+        }
+        // Send initial report
+        if (this._currentSourceInfo) {
+            this.mistReporter.sendInitialReport({
+                player: this._currentPlayerInfo?.shortname || "unknown",
+                sourceType: this._currentSourceInfo.type,
+                sourceUrl: this._currentSourceInfo.url,
+                pageUrl: typeof window !== "undefined" ? window.location.href : "",
+            });
+        }
+        this.cleanupFns.push(() => {
+            this.mistReporter?.sendFinalReport("unmount");
+            this.mistReporter?.destroy();
+            this.mistReporter = null;
+        });
+    }
+    initializeMetaTrackManager() {
+        const mistUrl = this.endpoints?.primary?.baseUrl;
+        if (!mistUrl)
+            return;
+        this.metaTrackManager = new MetaTrackManager({
+            mistBaseUrl: mistUrl,
+            streamName: this.config.contentId,
+            debug: this.config.debug,
+        });
+        this.metaTrackManager.connect();
+        // Wire video timeupdate to MetaTrackManager
+        if (this.videoElement) {
+            const handleTimeUpdate = () => {
+                if (this.videoElement && this.metaTrackManager) {
+                    this.metaTrackManager.setPlaybackTime(this.videoElement.currentTime);
+                }
+            };
+            const handleSeeking = () => {
+                if (this.videoElement && this.metaTrackManager) {
+                    this.metaTrackManager.onSeek(this.videoElement.currentTime);
+                }
+            };
+            this.videoElement.addEventListener("timeupdate", handleTimeUpdate);
+            this.videoElement.addEventListener("seeking", handleSeeking);
+            this.cleanupFns.push(() => {
+                this.videoElement?.removeEventListener("timeupdate", handleTimeUpdate);
+                this.videoElement?.removeEventListener("seeking", handleSeeking);
+            });
+        }
+        this.cleanupFns.push(() => {
+            this.metaTrackManager?.disconnect();
+            this.metaTrackManager = null;
+        });
+    }
+    cleanup() {
+        // Run all cleanup functions
+        this.cleanupFns.forEach((fn) => {
+            try {
+                fn();
+            }
+            catch { }
+        });
+        this.cleanupFns = [];
+        // Destroy player manager's current player
+        try {
+            this.playerManager.destroy();
+        }
+        catch { }
+    }
+    setState(state, context) {
+        this.state = state;
+        // Only emit if state actually changed
+        if (this.lastEmittedState !== state) {
+            this.lastEmittedState = state;
+            this.emit("stateChange", { state, context });
+        }
+    }
+    log(message) {
+        if (this.config.debug) {
+            console.log(`[PlayerController] ${message}`);
+        }
+    }
+}
+PlayerController.HOVER_HIDE_DELAY_MS = 3000;
+PlayerController.HOVER_LEAVE_DELAY_MS = 200;
+PlayerController.HARD_FAILURE_STALL_THRESHOLD_MS = 30000; // 30 seconds sustained stall
+// Error handling constants
+PlayerController.AUTO_CLEAR_ERROR_DELAY_MS = 2000;
+PlayerController.HARD_FAILURE_ERROR_THRESHOLD = 5;
+PlayerController.HARD_FAILURE_ERROR_WINDOW_MS = 60000;
+PlayerController.FATAL_ERROR_KEYWORDS = [
+    "fatal",
+    "network error",
+    "media error",
+    "decode error",
+    "source not supported",
+];
+
+export { MIST_SOURCE_TYPES, PROTOCOL_TO_MIME, PlayerController, buildStreamInfoFromEndpoints, getMimeTypeForProtocol, getSourceTypeInfo };
+//# sourceMappingURL=PlayerController.js.map