eb-player 2.0.18 → 2.0.20

package/dist/build/ebplayer.bundle.js

@@ -4,7 +4,7 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.EBPlayer = {}));
 })(this, (function (exports) { 'use strict';
 
-    var __EB_PLAYER_VERSION__ = "2.0.18";
+    var __EB_PLAYER_VERSION__ = "2.0.20";
 
     /**
      * Finite State Machine for player playback state transitions.
@@ -118,6 +118,7 @@
         socialsOpen: false,
         infoOpen: false,
         adPlaying: false,
+        introStreamPlaying: false,
         castAvailable: false,
         isRtl: false,
         isRadio: false,
@@ -608,6 +609,9 @@
         },
         'settings.auto': {
             en: 'Auto', fr: 'Auto', ar: 'تلقائي', es: 'Auto'
+        },
+        'preroll.skip': {
+            en: 'Skip', fr: 'Passer', ar: 'تخطي', es: 'Saltar'
         }
     };
     /**
@@ -1371,6 +1375,7 @@
             this.state.on('bufferedEnd', () => this.scheduleRender(), { signal: this.signal });
             this.state.on('isRtl', () => this.scheduleRender(), { signal: this.signal });
             this.state.on('adPlaying', () => this.scheduleRender(), { signal: this.signal });
+            this.state.on('introStreamPlaying', () => this.scheduleRender(), { signal: this.signal });
             this.state.on('chapters', () => this.scheduleRender(), { signal: this.signal });
             this.state.on('epgPrograms', () => this.scheduleRender(), { signal: this.signal });
             this.render();
@@ -1438,7 +1443,7 @@
         }
         // ---- Drag handlers ----
         handlePointerDown(event) {
-            if (this.state.adPlaying)
+            if (this.state.adPlaying || this.state.introStreamPlaying)
                 return;
             const trackEl = event.currentTarget;
             this.trackEl = trackEl;
@@ -1545,9 +1550,9 @@
         }
         // ---- Template ----
         template() {
-            const { currentTime, duration, bufferedEnd, adPlaying, chapters, epgPrograms } = this.state;
+            const { currentTime, duration, bufferedEnd, adPlaying, introStreamPlaying, chapters, epgPrograms } = this.state;
             const isSeekbarHidden = !this.config.seekbar;
-            const isDisabled = adPlaying;
+            const isDisabled = adPlaying || introStreamPlaying;
             // Progress percentage — use dragValue during drag to prevent live-update jitter
             const progressPercent = duration > 0
                 ? (this.isDragging ? this.dragValue : currentTime) / duration * 100
@@ -2442,15 +2447,16 @@
      *
      * Displayed in the middle bar beside the play/pause button.
      * Renders a circular arrow icon with the seek offset number below.
-     * Hidden during ad playback.
+     * Hidden during ad playback or intro-stream playback.
      */
     class RewindButton extends BaseComponent {
         onConnect() {
             this.state.on('adPlaying', () => this.render(), { signal: this.signal });
+            this.state.on('introStreamPlaying', () => this.render(), { signal: this.signal });
             this.render();
         }
         template() {
-            if (this.state.adPlaying) {
+            if (this.state.adPlaying || this.state.introStreamPlaying) {
                 return b ``;
             }
             const offset = this.config.seekOffset || 15;
@@ -2482,15 +2488,16 @@
      *
      * Displayed in the middle bar beside the play/pause button.
      * Renders a circular arrow icon with the seek offset number below.
-     * Hidden during ad playback.
+     * Hidden during ad playback or intro-stream playback.
      */
     class ForwardButton extends BaseComponent {
         onConnect() {
             this.state.on('adPlaying', () => this.render(), { signal: this.signal });
+            this.state.on('introStreamPlaying', () => this.render(), { signal: this.signal });
             this.render();
         }
         template() {
-            if (this.state.adPlaying) {
+            if (this.state.adPlaying || this.state.introStreamPlaying) {
                 return b ``;
             }
             const offset = this.config.seekOffset || 15;
@@ -2781,6 +2788,101 @@
         }
     }
 
+    /**
+     * PrerollOverlay — V1 parity for the intro-stream skip + click-through UX.
+     *
+     * Two responsibilities:
+     *  1. Skip button + countdown (D-13 / D-14). `Number.isFinite(config.prerollSkip)`
+     *     gates existence. While the countdown is > 0 the button shows `Skip (N)` and
+     *     is disabled. At 0 it shows `Skip` and is clickable. Clicking emits
+     *     `preroll-skip` on the bus.
+     *  2. Whole-overlay click-through (D-16, INTRO-04). Clicks landing on the
+     *     overlay (outside the skip button) open `config.prerollLink` in a new
+     *     tab with the security argument required by ASVS V14 / T-07-05 (blocks
+     *     reverse tabnabbing and Referer leaks). Skip-button clicks
+     *     `stopPropagation()` so they never reach this handler.
+     *
+     * Hidden (empty div) when `state.introStreamPlaying === false`.
+     *
+     * The skip countdown is derived from intro PLAYBACK progress
+     * (`state.currentTime`), not a wall-clock timer — so it only advances while the
+     * intro is actually playing. While the intro is paused (e.g. `autoplay:false`
+     * waiting for the user's gesture, or buffering) the countdown holds. Without
+     * this the skip control would unlock before the user ever saw the intro play.
+     * State subscriptions auto-clean via the `{ signal }` option — no manual timer
+     * teardown is required.
+     */
+    class PrerollOverlay extends BaseComponent {
+        onConnect() {
+            this.state.on('introStreamPlaying', () => this.render(), { signal: this.signal });
+            // currentTime drives the countdown; re-render as intro playback advances.
+            this.state.on('currentTime', () => this.render(), { signal: this.signal });
+            this.render();
+        }
+        /**
+         * Seconds remaining before the intro can be skipped, derived from intro
+         * playback position (`state.currentTime`). Infinity when prerollSkip is
+         * Infinity (no skip button). Clamped at 0 (never negative).
+         */
+        remainingSkip() {
+            const prerollSkip = this.config.prerollSkip;
+            if (!Number.isFinite(prerollSkip))
+                return Infinity;
+            return Math.max(0, Math.ceil(prerollSkip - this.state.currentTime));
+        }
+        template() {
+            if (!this.state.introStreamPlaying) {
+                return b `<div class="eb-preroll-overlay" hidden aria-hidden="true"></div>`;
+            }
+            const prerollSkip = this.config.prerollSkip;
+            const prerollLink = this.config.prerollLink;
+            const showSkip = Number.isFinite(prerollSkip);
+            const remaining = this.remainingSkip();
+            const skipClickable = remaining <= 0;
+            const label = this.i18n?.t('preroll.skip') ?? 'Skip';
+            return b `
+      <div
+        class="eb-preroll-overlay"
+        @click="${(event) => this.handleOverlayClick(event, prerollLink)}"
+      >
+        ${showSkip
+            ? b `<button
+              class="eb-preroll-skip${skipClickable ? '' : ' eb-preroll-skip--locked'}"
+              aria-label="${label}"
+              ?disabled="${!skipClickable}"
+              @click="${(event) => this.handleSkip(event)}"
+            >${label}${remaining > 0 ? b ` (${remaining})` : ''}</button>`
+            : ''}
+      </div>
+    `;
+        }
+        handleSkip(event) {
+            event.stopPropagation();
+            if (this.remainingSkip() > 0)
+                return;
+            this.bus.emit('preroll-skip');
+        }
+        handleOverlayClick(_event, prerollLink) {
+            if (!prerollLink)
+                return;
+            // Reject non-http(s) URIs (blocks javascript:, data:, vbscript:, file:, …).
+            // prerollLink is integrator-provided and may originate from a compromised
+            // CMS; blindly passing it to window.open would let a javascript: URI run
+            // in the user's session. See REVIEW.md CR-04.
+            try {
+                const url = new URL(prerollLink, window.location.href);
+                if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+                    console.warn('PrerollOverlay: refusing to open non-http(s) prerollLink', prerollLink);
+                    return;
+                }
+                window.open(url.href, '_blank', 'noopener,noreferrer');
+            }
+            catch {
+                console.warn('PrerollOverlay: invalid prerollLink', prerollLink);
+            }
+        }
+    }
+
     /**
      * ForjaPlaylistBar renders a horizontal episode list in the bottom-extra
      * extension zone for the Forja brand skin.
@@ -3152,7 +3254,8 @@
                 [new ErrorMessage(), 'eb-error-slot'],
                 [new SocialsOverlay(), 'eb-socials-slot'],
                 [new InfoOverlay(), 'eb-info-slot'],
-                [new ToastNotification(), 'eb-toast-slot']
+                [new ToastNotification(), 'eb-toast-slot'],
+                [new PrerollOverlay(), 'eb-preroll-slot']
             ];
             for (const [component, slotClass] of interactiveOverlays) {
                 const slot = document.createElement('div');
@@ -3221,6 +3324,11 @@
             state.on('controlsVisible', () => {
                 this.updateControlsVisibility();
             }, { signal });
+            // Toggle ad-playing class so the IMA ads container can receive clicks
+            // (skip button, click-through) and sit above the player chrome during ads.
+            state.on('adPlaying', () => {
+                this.updateAdPlayingState();
+            }, { signal });
         }
         /**
          * Toggles poster image visibility based on playbackState.
@@ -3295,6 +3403,19 @@
             inner.classList.toggle('eb-controls-visible', visible);
             inner.classList.toggle('eb-controls-hidden', !visible);
         }
+        /**
+         * Toggles the eb-ad-playing class on the player container. While an IMA ad
+         * plays, CSS raises the ads container above the player chrome and enables
+         * pointer-events on it so IMA's own ad UI (Skip button, click-through) is
+         * clickable — the container is pointer-events:none at rest to avoid blocking
+         * clicks on the content video.
+         */
+        updateAdPlayingState() {
+            const inner = this.el?.firstElementChild;
+            if (inner == null)
+                return;
+            inner.classList.toggle('eb-ad-playing', this.state.adPlaying);
+        }
         /**
          * Applies or removes the dir=rtl attribute without full re-render.
          * More efficient than re-rendering the entire template for a simple attribute change.
@@ -3360,8 +3481,8 @@
      * AutoHideController manages the 3-second auto-hide timer for player controls.
      *
      * On any user activity (pointermove, touchstart, keyup), the timer resets to 3s.
-     * When the timer fires, controls are hidden — but ONLY if no panel is open and
-     * no ad is playing.
+     * When the timer fires, controls are hidden — but ONLY if no panel is open,
+     * no ad is playing, and no intro stream is playing.
      *
      * Note: Uses manual removeEventListener instead of the { signal } option in
      * addEventListener. JSDOM 28 rejects non-JSDOM AbortSignal instances in the
@@ -3406,7 +3527,8 @@
             const shouldKeepVisible = this.state.settingsOpen ||
                 this.state.socialsOpen ||
                 this.state.infoOpen ||
-                this.state.adPlaying;
+                this.state.adPlaying ||
+                this.state.introStreamPlaying;
             if (!shouldKeepVisible) {
                 this.state.controlsVisible = false;
             }
@@ -3421,7 +3543,7 @@
      * ArrowRight: seek forward by config.seekOffset seconds (clamped to duration).
      * m: mutes/unmutes — only when config.supportHotKeys is true.
      *
-     * All shortcuts are disabled during ads (state.adPlaying === true).
+     * All shortcuts are disabled during ads or intro streams (state.adPlaying || state.introStreamPlaying).
      *
      * The container must be focusable to receive keyboard events.
      * If container.tabIndex < 0, it is set to 0 automatically.
@@ -3443,8 +3565,8 @@
             }
             const handleKeyup = (event) => {
                 const keyEvent = event;
-                // Ignore all keys during ad playback
-                if (state.adPlaying) {
+                // Ignore all keys during ad playback or intro-stream playback
+                if (state.adPlaying || state.introStreamPlaying) {
                     return;
                 }
                 if (keyEvent.key === ' ') {
@@ -3776,15 +3898,28 @@
         }
         /**
          * Initialize the IMA SDK preroll ad system.
-         * - Skips if config.preroll is false/undefined
+         * - Skips if config.ad is undefined
          * - If !config.autoplay: waits for user click on video element before initializing
          *   (required by browser autoplay policies to avoid muted/blocked display contexts)
          * - Loads IMA SDK, creates AdDisplayContainer, AdsLoader, and AdsRequest
          * - Wires ad lifecycle events to PlayerState and TypedEventBus
          */
         async init(config, state, bus, video, adsContainer, signal) {
-            if (!config.preroll)
+            if (!config.ad)
                 return;
+            // CR-01: D-10 intro → ad → main precedence. If an intro stream is currently
+            // playing, defer IMA initialization until the bus emits 'intro-stream-complete'.
+            // Without this gate, IMA fires CONTENT_PAUSE_REQUESTED and tries to play the ad
+            // in the same <video> element the intro is using — the two streams race for
+            // the element with order determined by network/SDK timing.
+            if (state.introStreamPlaying) {
+                await new Promise((resolve) => {
+                    bus.on('intro-stream-complete', () => resolve(), { signal });
+                    signal.addEventListener('abort', () => resolve(), { once: true });
+                });
+                if (signal.aborted)
+                    return;
+            }
             // Gate initialization on user gesture when not in autoplay mode
             if (!config.autoplay) {
                 await this.waitForUserGesture(video, signal);
@@ -3797,16 +3932,38 @@
             this.imaDisplayContainer = displayContainer;
             displayContainer.initialize();
             const adsLoader = new ima.AdsLoader(displayContainer);
+            // AD_ERROR fall-through (CR-02): if the VAST tag fails to load (network
+            // error, ad-blocker, malformed XML, autoplay rejection), IMA fires
+            // AD_ERROR and never ALL_ADS_COMPLETED. Without this handler the
+            // orchestration in eb-player.ts would wait forever for 'ad-complete'
+            // and the main stream would never open. Treat AD_ERROR as a normal
+            // completion so the orchestration always advances.
+            adsLoader.addEventListener(ima.AdErrorEvent.Type.AD_ERROR, (errorEvent) => {
+                console.warn('AdsManager: AD_ERROR (loader) — falling through to main', errorEvent);
+                state.adPlaying = false;
+                bus.emit('ad-complete');
+            });
             adsLoader.addEventListener(ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED, (loadedEvent) => {
                 const event = loadedEvent;
                 const adsManager = event.getAdsManager(video);
                 this.imaAdsManager = adsManager;
-                const { width, height } = video.getBoundingClientRect
-                    ? video.getBoundingClientRect()
-                    : { width: 640, height: 360 };
+                // getBoundingClientRect is always defined on HTMLElement; the prior
+                // truthy check on the method reference was dead code. The real edge
+                // case is a zero-sized element (display:none, before layout) which
+                // would make IMA's ads container collapse — fall back to a 16:9
+                // baseline in that case.
+                const rect = video.getBoundingClientRect();
+                const width = rect.width > 0 ? rect.width : 640;
+                const height = rect.height > 0 ? rect.height : 360;
                 // Wire event handlers for ad lifecycle
                 adsManager.addEventListener(ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, () => {
                     state.adPlaying = true;
+                    // Pause the content stream while the ad plays. IMA's integration
+                    // contract requires the publisher to pause its own content video on
+                    // CONTENT_PAUSE_REQUESTED; the symmetric CONTENT_RESUME_REQUESTED
+                    // handler below resumes it with video.play(). Without this the main
+                    // HLS/DASH stream keeps playing (audio + video) underneath the ad.
+                    video.pause();
                 });
                 adsManager.addEventListener(ima.AdEvent.Type.CONTENT_RESUME_REQUESTED, () => {
                     state.adPlaying = false;
@@ -3816,12 +3973,20 @@
                     state.adPlaying = false;
                     bus.emit('ad-complete');
                 });
+                // Same AD_ERROR fall-through on the manager — covers errors that
+                // surface only after the ad starts playing (decode error, mid-roll
+                // load failure, etc.).
+                adsManager.addEventListener(ima.AdErrorEvent.Type.AD_ERROR, (errorEvent) => {
+                    console.warn('AdsManager: AD_ERROR (manager) — falling through to main', errorEvent);
+                    state.adPlaying = false;
+                    bus.emit('ad-complete');
+                });
                 adsManager.init(width, height);
                 adsManager.start();
             });
             // Load the ad tag
             const adsRequest = new ima.AdsRequest();
-            adsRequest.adTagUrl = config.preroll;
+            adsRequest.adTagUrl = config.ad;
             adsLoader.requestAds(adsRequest);
             // Register abort cleanup
             signal.addEventListener('abort', () => {
@@ -3838,23 +4003,95 @@
         /**
          * Wait for a click event on the video element.
          * Used to satisfy browser autoplay policies when autoplay is disabled.
+         *
+         * WR-05: single-shot settle flag guards against the click-vs-abort race —
+         * Promise resolution is already idempotent but settled tightens the
+         * contract by ensuring listener cleanup happens exactly once for either
+         * outcome. Callers still distinguish outcomes via signal.aborted.
          */
         waitForUserGesture(video, signal) {
             return new Promise((resolve) => {
-                const onClick = () => {
+                let settled = false;
+                const settle = () => {
+                    if (settled)
+                        return;
+                    settled = true;
                     video.removeEventListener('click', onClick);
                     resolve();
                 };
+                const onClick = () => settle();
                 video.addEventListener('click', onClick);
-                // Clean up if aborted before click
-                signal.addEventListener('abort', () => {
-                    video.removeEventListener('click', onClick);
-                    resolve();
-                }, { once: true });
+                // Clean up if aborted before click. The abort listener auto-removes
+                // via `{ once: true }`; the click listener is removed inside settle().
+                signal.addEventListener('abort', settle, { once: true });
             });
         }
     }
 
+    /**
+     * IntroStreamManager owns the intro-stream lifecycle.
+     *
+     * - On init(), if config.preroll is set: flips state.introStreamPlaying = true and
+     *   subscribes to:
+     *     - the video element's native `ended` event
+     *     - bus `preroll-skip` (from the PrerollOverlay skip button)
+     *     - bus `error-fatal` (D-04 silent fall-through — intro must never block main)
+     * - Any one of those triggers calls a closure `complete()` exactly once
+     *   (idempotent via a `completed` boolean guard), which flips
+     *   state.introStreamPlaying = false and emits `intro-stream-complete`.
+     * - On abort, the video `ended` listener is removed explicitly via
+     *   removeEventListener. Bus listeners auto-clean via the `{ signal }` option
+     *   (see src/core/event-bus.ts on()).
+     *
+     * Scope: this manager listens and emits — it does NOT itself open the intro
+     * stream. The engine open() call is owned by eb-player.ts (single source of
+     * engine selection + DRM wiring), driven by the orchestration around this
+     * manager's `intro-stream-complete` event.
+     */
+    class IntroStreamManager {
+        /**
+         * Initialize intro-stream lifecycle tracking.
+         * - Skips entirely if config.preroll is falsy (no state flip, no listeners).
+         * - Otherwise flips state.introStreamPlaying = true and registers the three
+         *   completion triggers (video `ended`, bus `preroll-skip`, bus `error-fatal`).
+         */
+        async init(config, state, bus, video, signal) {
+            if (!config.preroll)
+                return;
+            state.introStreamPlaying = true;
+            // Child AbortController scoped to the intro pass. We tear it down inside
+            // complete() so the bus listeners (in particular 'error-fatal') do not
+            // outlive the intro stream. Without this, a fatal error on the MAIN
+            // stream would re-fire this handler and log the misleading
+            // "intro stream errored" message (WR-01).
+            const local = new AbortController();
+            // Mirror outer aborts onto the local controller so dispose() still
+            // cleans everything up.
+            signal.addEventListener('abort', () => local.abort(), { once: true });
+            let completed = false;
+            const complete = () => {
+                if (completed)
+                    return;
+                completed = true;
+                state.introStreamPlaying = false;
+                bus.emit('intro-stream-complete');
+                local.abort(); // tear down bus listeners after the intro completes
+            };
+            const onEnded = () => complete();
+            video.addEventListener('ended', onEnded);
+            bus.on('preroll-skip', complete, { signal: local.signal });
+            // D-04: intro stream errors fall through silently to main. Log a warning
+            // and treat the failure as a normal completion.
+            bus.on('error-fatal', () => {
+                console.warn('IntroStreamManager: intro stream errored — falling through to main');
+                complete();
+            }, { signal: local.signal });
+            signal.addEventListener('abort', () => {
+                video.removeEventListener('ended', onEnded);
+            }, { once: true });
+        }
+    }
+
     /**
      * Poster HLS handler.
      *
@@ -4100,8 +4337,8 @@
                 const playlistManager = new PlaylistManager();
                 playlistManager.init(config, state, bus, signal);
             }
-            // AdsManager: skip when config.preroll is false
-            if (config.preroll && this.skinRoot !== null) {
+            // AdsManager: skip when config.ad is undefined (D-09)
+            if (config.ad && this.skinRoot !== null) {
                 const adsManager = new AdsManager();
                 const video = this.skinRoot.getVideoElement();
                 const adsContainer = this.skinRoot.getAdsContainer();
@@ -4111,6 +4348,16 @@
                     });
                 }
             }
+            // IntroStreamManager: skip when config.preroll is false (D-02)
+            if (config.preroll && this.skinRoot !== null) {
+                const introManager = new IntroStreamManager();
+                const video = this.skinRoot.getVideoElement();
+                if (video !== null) {
+                    introManager.init(config, state, bus, video, signal).catch((error) => {
+                        console.error('EBPlayer: IntroStreamManager init failed:', error);
+                    });
+                }
+            }
             // Poster handler: loop an HLS stream as video background when configured
             if (config.posterStream) {
                 const posterHandler = createPosterHandler();
@@ -4255,6 +4502,14 @@
             this.signal = null;
             this.bus = null;
             this.config = null;
+            /**
+             * The URL to load — set by reference.open(src) via setLoadSource().
+             * Takes precedence over config.src in engine init so the intro stream URL
+             * is loaded rather than the main stream URL (root cause of Phase 7 bug:
+             * reference.open(preroll) wired config but engines read config.src, which
+             * always points at the main stream).
+             */
+            this.loadSourceUrl = '';
             this.watchdog = null;
             this.driverReady = new Promise((resolve) => {
                 this.resolveDriverReady = resolve;
@@ -4277,6 +4532,7 @@
             this.signal = null;
             this.bus = null;
             this.config = null;
+            this.loadSourceUrl = '';
         }
         // -------------------------------------------------------------------------
         // Stall watchdog helpers
@@ -4318,6 +4574,16 @@
         setVideo(video) {
             this.video = video;
         }
+        /**
+         * Set the URL that the engine driver should load.
+         * Must be called by reference.open(src) BEFORE controller.setEngineSync()
+         * so that onAttach() → init() picks up the correct URL.
+         * This decouples the stream URL from config.src, which always points at the
+         * main stream URL (set once at start() time and never mutated).
+         */
+        setLoadSource(src) {
+            this.loadSourceUrl = src;
+        }
         // -------------------------------------------------------------------------
         // Video element event binding
         // -------------------------------------------------------------------------
@@ -5093,7 +5359,8 @@
      * automatic recovery:
      * - Fatal mediaError: calls recoverMediaError() after 1s
      * - Fatal keySystemError: unrecoverable (e.g. no HTTPS for DRM) — no retry
-     * - Fatal other error: calls startLoad() after 1s
+     * - Fatal other error (intro pass): calls onFatalNetworkError() to fall through to main
+     * - Fatal other error (main pass): calls startLoad() after 1s (keeps retrying)
      * - Non-fatal error: re-checks after 3s; if currentTime has not advanced
      *   (and Chromecast is not casting), applies the same recovery
      *
@@ -5112,6 +5379,8 @@
         const exhaustedErrors = new Set();
         /** Tracks unrecoverable fatal errors that have already been reported */
         const reportedUnrecoverable = new Set();
+        /** Ensures onFatalNetworkError is only called once per handler instance */
+        let fatalNetworkErrorReported = false;
         let lastSuccessfulTime;
         driver.on('hlsError', (event, data) => {
             const errorKey = data.details ?? data.type;
@@ -5132,6 +5401,17 @@
                     engine?.onUnrecoverableError?.(`DRM error: ${errorKey}`);
                     return;
                 }
+                // Intro-pass fall-through: when onFatalNetworkError is provided, signal
+                // the caller once and stop retrying. This lets the player fall through to
+                // the main stream instead of looping startLoad() on an unreachable intro.
+                if (engine?.onFatalNetworkError !== undefined) {
+                    if (fatalNetworkErrorReported)
+                        return;
+                    fatalNetworkErrorReported = true;
+                    console.warn(`HLS Retry: Fatal error on intro pass — signalling fall-through (${errorKey}).`, event, data);
+                    engine.onFatalNetworkError(errorKey);
+                    return;
+                }
                 console.warn('HLS Retry: Fatal error, trying to fix now.', event, data);
                 setTimeout(() => {
                     if (data.type === 'mediaError')
@@ -5470,7 +5750,13 @@
             applyDiscontinuityWorkaround(driver, Hls.Events);
             // Wire retry handler — pass engine context so unrecoverable DRM errors
             // stop the stall watchdog (prevents useless reload loops) and surface to UI.
+            // For the intro pass (loadSourceUrl matches config.preroll), also wire
+            // onFatalNetworkError so a permanently-unreachable intro manifest emits
+            // error-fatal and falls through to main instead of looping startLoad() forever.
+            // This callback is intentionally NOT set for the main stream so transient
+            // network blips still trigger the normal startLoad() recovery.
             if (config.retry) {
+                const isIntroPass = Boolean(config.preroll) && this.loadSourceUrl === config.preroll;
                 handleHlsRetry(driver, {
                     get chromecast_casting() { return state.isCasting; },
                     onUnrecoverableError: (message) => {
@@ -5481,7 +5767,18 @@
                         // hls.js nulls its media on a fatal keySystemError; signal so the
                         // P2P SDK is torn down before it loops on a null media element.
                         this.bus?.emit('error-fatal', { code: 'DRM', message });
-                    }
+                    },
+                    ...(isIntroPass
+                        ? {
+                            onFatalNetworkError: (errorKey) => {
+                                // D-04: intro stream fatal network/manifest error — stop retrying
+                                // and signal fall-through to main. IntroStreamManager's error-fatal
+                                // listener completes the intro pass so openMainStream() can proceed.
+                                this.stopWatchdog();
+                                this.bus?.emit('error-fatal', { code: 'NETWORK', message: `Intro stream error: ${errorKey}` });
+                            }
+                        }
+                        : {}),
                 });
             }
             // Geo-block detection (opt-in, ported from v1.x).
@@ -5506,8 +5803,10 @@
             this.bindVideoEvents(video, state, signal);
             // Attach media and load source
             driver.attachMedia(video);
-            // Build source URL with token params if applicable
-            let src = config.src ?? '';
+            // Build source URL with token params if applicable.
+            // Use loadSourceUrl (set by reference.open(src) via setLoadSource) so the intro
+            // stream URL is loaded rather than config.src which always points at the main stream.
+            let src = this.loadSourceUrl || config.src || '';
             if (this.tokenManager && src) {
                 src = await this.tokenManager.updateUrlWithTokenParams({ url: src });
                 // Guard: abort if detached during token URL update
@@ -6015,7 +6314,9 @@
             }
             this.driver = player;
             this.resolveDriverReady();
-            player.initialize(video, config.src ?? '', config.autoplay ?? false);
+            // Use loadSourceUrl (set by reference.open(src) via setLoadSource) so the intro
+            // stream URL is loaded rather than config.src which always points at the main stream.
+            player.initialize(video, this.loadSourceUrl || config.src || '', config.autoplay ?? false);
             // Apply retry settings if requested
             if (config.retry) {
                 applyDashRetrySettings(player);
@@ -6574,6 +6875,25 @@
         return isDash ? new DashEngine() : new HlsEngine();
     }
     // ---------------------------------------------------------------------------
+    // EME teardown timing
+    // ---------------------------------------------------------------------------
+    /**
+     * Empirical delay to give the browser time to complete async EME teardown
+     * (setMediaKeys(null)) before the next stream is opened on the same <video>.
+     * hls.js destroy() does not await setMediaKeys(null), so reusing the element
+     * too soon yields "The existing ContentDecryptor" errors on DRM streams.
+     *
+     * Tuned at 500ms: 100ms was too short on slower hardware. There is no
+     * promise-able event for setMediaKeys(null) completion; switch this helper
+     * to an event-driven wait once one exists.
+     */
+    const EME_TEARDOWN_DELAY_MS = 500;
+    function waitForEmeTeardown() {
+        // TODO: replace with an event-driven wait once setMediaKeys(null) is
+        // observably awaitable.
+        return new Promise((resolve) => setTimeout(resolve, EME_TEARDOWN_DELAY_MS));
+    }
+    // ---------------------------------------------------------------------------
     // Public API
     // ---------------------------------------------------------------------------
     /**
@@ -6596,6 +6916,17 @@
             instances.delete(container);
         }
         const mergedConfig = mergeConfig(DEFAULT_CONFIG, runtimeConfig);
+        // Phase 7 — capture original runtime overrides BEFORE controller.mount() so
+        // any future mutation of mergedConfig.muted / .manager inside mount or
+        // initIntegrations (e.g. an autoplay-policy normalization) cannot poison the
+        // snapshot. They are restored on `<video>.muted` + PlayerState.muted (the
+        // runtime ABI per command-handler.ts:115 and lifecycle.ts:158) and on
+        // `mergedConfig.manager` (the P2P opt-in IS re-read on each `reference.open`,
+        // so the config-level swap is legitimate for that field only). NEVER mutate
+        // `mergedConfig.muted` — it is consumed only at video element creation in
+        // skin-root.ts:141/318 and is a no-op for runtime mute.
+        const originalMuted = mergedConfig.muted ?? false;
+        const originalManager = mergedConfig.manager;
         const controller = new PlayerController(runtimeConfig);
         controller.mount(container);
         // Video element is available after mount() creates the skin DOM
@@ -6624,6 +6955,11 @@
                 }
                 engine.setBus(controller.bus);
                 engine.setConfig(mergedConfig);
+                // Tell the engine which URL to load. Must be set BEFORE setEngineSync() triggers
+                // onAttach() → init(), where loadSourceUrl is consumed. config.src always holds
+                // the main stream URL (never mutated); loadSourceUrl carries the per-open URL
+                // (intro or main depending on the call site).
+                engine.setLoadSource(src);
                 controller.setEngineSync(engine);
                 inst.engine = engine;
                 // P2P integration: wire EasyBroadcast SDK when config.lib and config.manager are set
@@ -6646,8 +6982,12 @@
                         console.error('EBPlayer: P2PManager integrate failed:', error);
                     });
                 }
-                // Snapshot handler: create snapshot engine for seekbar preview thumbnails
-                if (mergedConfig.showProgressThumb) {
+                // Snapshot handler: create snapshot engine for seekbar preview thumbnails.
+                // Gated by `src !== mergedConfig.preroll` so the intro pass does NOT
+                // initialize snapshot (Pitfall 5) — seekbar is hidden during intro anyway
+                // and we want to avoid duplicate CDN tokens for the short intro stream.
+                // The main pass still initializes snapshot normally.
+                if (mergedConfig.showProgressThumb && src !== mergedConfig.preroll) {
                     // Clean up any previous snapshot handler
                     if (inst.snapshotDestroy !== null) {
                         inst.snapshotDestroy();
@@ -6743,10 +7083,8 @@
             // Get saved selections before close (CommandHandler saved them before emitting request-reload)
             const saved = controller.getSavedSelections();
             reference.close();
-            // 500ms delay gives the browser time to complete async EME teardown
-            // (setMediaKeys(null) is async and hls.js destroy() doesn't await it).
-            // 100ms was too short and caused "The existing ContentDecryptor" errors.
-            setTimeout(() => {
+            // EME teardown delay — see waitForEmeTeardown / EME_TEARDOWN_DELAY_MS.
+            waitForEmeTeardown().then(() => {
                 reference.open(currentSrc);
                 // Restore selections after manifest loads (~2s pragmatic delay for async manifest parsing)
                 setTimeout(() => {
@@ -6756,7 +7094,7 @@
                         inst.engine.setSubtitle(saved.subtitleTrack);
                     }
                 }, 2000);
-            }, 500);
+            });
         });
         // On an unrecoverable engine error (e.g. fatal DRM keySystemError), tear down
         // the P2P SDK. hls.js nulls its media element, so a still-running eblib would
@@ -6765,11 +7103,92 @@
         controller.bus.on('error-fatal', () => {
             inst.p2p?.stop();
         }, { signal: controller.signal });
+        // Phase 7 — intro→main orchestration.
+        // When mergedConfig.preroll is set, open the intro stream first, then on
+        // bus 'intro-stream-complete' (emitted by IntroStreamManager on video.ended,
+        // preroll-skip, or error-fatal) close → 500ms EME teardown delay → open main.
+        // If config.ad is also set, wait additionally for bus 'ad-complete' before
+        // opening main (D-10: intro → ad → main precedence).
+        //
+        // Runtime mute override: the live <video>.muted and PlayerState.muted are
+        // forced to false for the intro pass (D-13 — intros always audible) and
+        // restored to `originalMuted` before opening main. We do NOT mutate
+        // `mergedConfig.muted` because it is consumed only at video element creation
+        // (skin-root.ts:141/318) and is a no-op for runtime mute.
+        //
+        // P2P opt-in: `mergedConfig.manager` IS re-read on each reference.open() in
+        // the P2P branch (eb-player.ts:192), so we config-level swap it to false for
+        // the intro pass and restore it for main (D-08 — P2P attaches only to main).
+        const openMainStream = () => {
+            if (video !== null) {
+                video.muted = originalMuted;
+            }
+            controller.state.muted = originalMuted;
+            // CR-05: keep mergedConfig.manager and controller.config.manager in sync.
+            // start() builds mergedConfig and PlayerController builds its own merged
+            // config independently from the same runtimeConfig (lifecycle.ts:73), so
+            // they are SEPARATE object references with the same initial values. Today
+            // only the engine path reads mergedConfig.manager, but any future
+            // consumer of controller.config.manager would observe the wrong value
+            // during the intro pass. Synchronize both objects on every swap.
+            mergedConfig.manager = originalManager;
+            controller.config.manager = originalManager;
+            // CR-03: clear any stale error that leaked from the intro/ad pass.
+            // IntroStreamManager's silent fall-through (D-04) treats error-fatal as a
+            // normal completion but leaves state.error populated with the intro
+            // stream's message — without this, ErrorMessage overlay would keep
+            // showing the intro's error on top of the successfully-loading main
+            // stream. Same applies on the ad-complete branch (an IMA AD_ERROR may
+            // surface a non-recoverable error before falling through).
+            controller.state.error = null;
+            if (!mergedConfig.src)
+                return;
+            reference.open(mergedConfig.src);
+        };
+        if (mergedConfig.preroll) {
+            const hasAd = Boolean(mergedConfig.ad);
+            controller.bus.on('intro-stream-complete', () => {
+                reference.close();
+                // WR-08: restore PlayerState.muted synchronously — DO NOT wait for the
+                // EME teardown delay. introStreamPlaying is now false, so skin
+                // components (volume button, etc.) immediately re-render from
+                // state.muted; leaving the intro-forced value of `false` until
+                // openMainStream() would briefly show an unmuted speaker icon for a
+                // user whose original config was `muted: true`. video.muted is
+                // restored later in openMainStream() — the live element can wait, but
+                // the visual state should reflect user intent immediately.
+                controller.state.muted = originalMuted;
+                // EME teardown delay — see waitForEmeTeardown / EME_TEARDOWN_DELAY_MS.
+                waitForEmeTeardown().then(() => {
+                    if (!hasAd) {
+                        openMainStream();
+                    }
+                    // If hasAd, the ad-complete handler below will call openMainStream
+                    // after the AdsManager finishes (D-10 precedence).
+                });
+            }, { signal: controller.signal });
+            if (hasAd) {
+                controller.bus.on('ad-complete', () => {
+                    openMainStream();
+                }, { signal: controller.signal });
+            }
+            // Force runtime mute off for the intro pass — applied to the LIVE <video>
+            // element and PlayerState, NOT to mergedConfig.muted (no-op for runtime).
+            if (video !== null) {
+                video.muted = false;
+            }
+            controller.state.muted = false;
+            // Skip P2P attach for the intro stream (D-08); restored before main open.
+            // CR-05: keep the dual-merged configs in sync (see openMainStream).
+            mergedConfig.manager = false;
+            controller.config.manager = false;
+            reference.open(mergedConfig.preroll);
+        }
         // Auto-open the stream if src is provided in config (matches legacy player behaviour
         // where consumers call start({ src: '...' }) and expect playback to begin immediately).
         // When autoplay is false, defer open() until the user requests play — this avoids
         // fetching CDN tokens and loading manifests before playback is actually needed.
-        if (mergedConfig.src) {
+        else if (mergedConfig.src) {
             if (mergedConfig.autoplay) {
                 reference.open(mergedConfig.src);
             }