@amazon/vinyl 1.2.0 → 1.2.2

package/dist/types/current/ad/AdControllerImpl.js

@@ -0,0 +1,741 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { createDisposer, createLogPrefix, EventHostImpl, getElementOrDefault, lerp, logDebug, logError, logVerbose, memoize, noop, resolveValueProvider, roundToNearest, sleep, sortedInsertionIndex, } from '@amazon/vinyl-util';
+import { AdError } from './AdError';
+/**
+ * The % playhead start tolerance for playback progress when emitting ad progress events.
+ */
+export const AD_START_TOLERANCE = 0.05;
+/**
+ * When a break's X-PLAYOUT-LIMIT budget is reached, an ad whose real media end is
+ * within this many seconds is allowed to finish on its own `ended` rather than
+ * being cut. The limit is a coarse, often whole-second budget while the media's
+ * true length is fractional, so without this grace an ad effectively as long as
+ * its budget would be clipped a fraction short. The tolerance is measured against
+ * the playback-reported (media) duration, not the ad's declared duration.
+ */
+export const PLAYOUT_LIMIT_TOLERANCE = 1;
+export const defaultAdControllerImplOptions = {
+    adLoadTimeout: 15,
+    preloadAheadTime: 10,
+};
+/**
+ * Provider-agnostic {@link AdController}. Holds the discovered ad breaks and
+ * derives enter/exit region events from playhead time updates.
+ *
+ * This controller is the *model* for ad playback: it knows which breaks exist,
+ * which break contains the playhead, and which ad within that break is current.
+ * It does NOT create, preload, or activate any tracks — that is the
+ * responsibility of the {@link TrackController}.
+ *
+ * A break is considered active while `startTime <= currentTime < endTime`,
+ * where `endTime` is `startTime + duration`. Breaks whose duration is unknown
+ * (null) or breaks which restrict `jump` will become active at
+ * `currentTime > startTime`
+ *
+ * This class contains no HLS- or DASH-specific logic; discovery code maps its
+ * protocol's signals to {@link AdBreakInfo} exposed by an
+ * {@link AdsProvider.getAds}, which this controller reads once the provider is
+ * set via {@link AdController.setAdsProvider} (and re-reads on `adsChange`).
+ */
+export class AdControllerImpl extends EventHostImpl {
+    deps;
+    get [Symbol.toStringTag]() {
+        return 'AdControllerImpl';
+    }
+    options;
+    _trackAds = null;
+    adsProviderSub = null;
+    adsProvider = null;
+    // The start times of the midroll ads, used for fast midroll break find
+    midrollAds = [];
+    // Midroll and postroll breaks, sorted by start time — the breaks eligible
+    // for the ahead-of-time `adPreload` signal (prerolls are preloaded up front).
+    preloadableBreaks = [];
+    // Breaks for which `adPreload` has already been emitted on the current
+    // approach; cleared on content change and when a break is re-armed by a
+    // seek back, so a re-approached break preloads again.
+    preloadedBreakIds = new Set();
+    lastPlaybackTime = 0;
+    pendingAdBreaks = [];
+    // Breaks permanently suppressed for this presentation (play-once breaks and
+    // prerolls). Cleared only on a content change (clearCompletedAds).
+    completeAdBreakIds = new Set();
+    // Replayable (non-play-once) midroll breaks that have played and are "spent"
+    // until the playhead moves back before their start, at which point they are
+    // re-armed and replay on the next forward crossing.
+    spentBreakIds = new Set();
+    disposer = createDisposer();
+    adBreakState = null;
+    loadingNext = false;
+    constructor(deps, options) {
+        super();
+        this.deps = deps;
+        this.options = { ...defaultAdControllerImplOptions, ...options };
+        const { add } = this.disposer;
+        const { playbackController } = this.deps;
+        add(playbackController.on('playing', () => {
+            if (this.adState) {
+                const adState = this.adState;
+                if (!adState.started) {
+                    // The ad has started playing, initialize the state.
+                    adState.started = true;
+                    adState.timeStart = playbackController.currentTime;
+                    adState.playbackRateAvg =
+                        playbackController.playbackRate;
+                    adState.dataPoints = 1;
+                }
+                this.dispatch('adPlaying', {
+                    adBreak: adState.parentBreak.adBreak,
+                    ad: adState.ad,
+                    index: adState.index,
+                    totalAds: adState.totalAds,
+                });
+            }
+        }));
+        add(playbackController.on('seeked', (event) => {
+            if (this.adState) {
+                this.adState.timeStart = playbackController.currentTime;
+                return;
+            }
+            // A genuine seek back before a break re-arms it: a spent
+            // (replayable) break fires again on the next forward crossing,
+            // and its preload signal re-arms so it warms again on approach.
+            if (event.reason !== 'seeked')
+                return;
+            const time = playbackController.currentTime;
+            for (const adBreak of this.preloadableBreaks) {
+                if (time < adBreak.startTime) {
+                    const key = adBreakKey(adBreak);
+                    this.spentBreakIds.delete(key);
+                    this.preloadedBreakIds.delete(key);
+                }
+            }
+        }));
+        add(playbackController.on('timeUpdate', this.onTimeUpdate));
+        add(playbackController.on('ended', () => {
+            if (this.adState)
+                this.endAd(this.adState);
+        }));
+    }
+    clearCompletedAds() {
+        this.completeAdBreakIds.clear();
+        this.spentBreakIds.clear();
+        this.preloadedBreakIds.clear();
+    }
+    isBreakSuppressed(adBreak) {
+        const key = adBreakKey(adBreak);
+        return this.completeAdBreakIds.has(key) || this.spentBreakIds.has(key);
+    }
+    /** The media-time the current ad has actually played, or 0 if not playing. */
+    adElapsed() {
+        const adState = this.adState;
+        return adState?.started
+            ? Math.max(0, this.deps.playbackController.currentTime - adState.timeStart)
+            : 0;
+    }
+    /**
+     * Computes whether the current ad may be skipped and, when not yet, how many
+     * seconds remain until it can. A `skip` restriction blocks it outright;
+     * otherwise a resolved skip window gates it by the elapsed break playout, and
+     * with no window the ad is freely skippable.
+     */
+    async resolveSkipState(adBreakState, breakPlayed) {
+        const { adBreak } = adBreakState;
+        if (adBreak.restrict.skip === true) {
+            return { canSkip: false, skipIn: null };
+        }
+        const skipControl = await resolveValueProvider(adBreak.skipControl).catch((_v) => null);
+        if (!skipControl) {
+            return { canSkip: true, skipIn: null };
+        }
+        if (breakPlayed < skipControl.offset) {
+            return { canSkip: false, skipIn: skipControl.offset - breakPlayed };
+        }
+        const end = skipControl.duration != null
+            ? skipControl.offset + skipControl.duration
+            : Infinity;
+        return { canSkip: breakPlayed < end, skipIn: null };
+    }
+    get currentTrackAds() {
+        return this._trackAds;
+    }
+    setTrackAds(value) {
+        const previous = this._trackAds;
+        const current = value ?? null;
+        this._trackAds = current;
+        this.midrollAds = (value?.adBreaks ?? []).filter((adBreak) => adBreak.placement === 'midroll');
+        // Midroll + postroll breaks are eligible for the ahead-of-time preload
+        // signal. adBreaks are already sorted by start time, so this stays sorted.
+        this.preloadableBreaks = (value?.adBreaks ?? []).filter((adBreak) => adBreak.placement !== 'preroll');
+        logDebug(this, 'setTrackAds', value);
+        this.dispatch('currentTrackAdsChange', {
+            previous,
+            current,
+        });
+    }
+    /**
+     * Returns a function that returns true if the ads provider has changed
+     * since the callback was created.
+     */
+    providerInterrupted() {
+        const provider = this.adsProvider;
+        return () => this.disposed || provider !== this.adsProvider;
+    }
+    setAdsProvider(provider) {
+        if (this.adsProvider === provider)
+            return;
+        this.pendingAdBreaks = [];
+        this.completeAdBreak(this.adBreakState, 'contentChange');
+        this.adsProviderSub?.();
+        const { add, dispose } = createDisposer();
+        this.adsProviderSub = dispose;
+        this.adsProvider = provider;
+        const interrupted = this.providerInterrupted();
+        this.clearCompletedAds();
+        this.setTrackAds(null);
+        if (!provider)
+            return;
+        const refreshAds = () => {
+            provider
+                .getAds()
+                .then((ads) => {
+                if (interrupted())
+                    return;
+                this.setTrackAds(ads);
+            })
+                .catch((error) => {
+                // Ad discovery failed for the provider. There is no active
+                // break to surface an adError against, so log it rather
+                // than routing through failAd (which would no-op with no
+                // active ad and swallow the failure silently).
+                if (interrupted())
+                    return;
+                logError(this, 'ad discovery failed', error);
+            });
+        };
+        add(provider.on('adsChange', refreshAds));
+        refreshAds();
+    }
+    async enterPreroll() {
+        return this.enterRoll('preroll');
+    }
+    async enterPostroll() {
+        return this.enterRoll('postroll');
+    }
+    async enterRoll(placement) {
+        if (!this.adsProvider)
+            return null;
+        logVerbose(this, `checking for ${placement} ads`);
+        this.lastPlaybackTime = this.deps.playbackController.currentTime;
+        const interrupted = this.providerInterrupted();
+        return this.adsProvider
+            .getAds()
+            .then((ads) => {
+            if (interrupted()) {
+                logVerbose(this, `interrupted, no pending breaks set for ${placement}`);
+                return null;
+            }
+            this.setPendingBreaks(ads.adBreaks.filter((adBreak) => adBreak.placement === placement));
+            return this.currentAdBreak;
+        })
+            .catch(() => {
+            return null;
+        });
+    }
+    // True when we have an ads provider set. Callers gate off this AND their
+    // own "no ad break in progress" checks (currentAdBreak / pendingAdBreaks),
+    // so this is only about "a provider has committed", not track activation.
+    get hasProvider() {
+        return this.adsProvider != null;
+    }
+    skipAdBreak() {
+        const adBreakState = this.adBreakState;
+        if (!adBreakState) {
+            logDebug(this, 'skipAdBreak, no-op');
+            return;
+        }
+        logDebug(this, 'skipAdBreak, active break id:', adBreakState.adBreak.id);
+        this.completeAdBreak(adBreakState, 'skipped');
+        this.nextAdOrBreak();
+    }
+    /**
+     * Marks an ad break as completed (or 'spent' and replayable), emits an `adBreakCompleted` event.
+     */
+    completeAdBreak(adBreakState, reason) {
+        if (!adBreakState || adBreakState.completedReason) {
+            logDebug(this, 'completeAdBreak, no-op');
+            return;
+        }
+        const { adBreak } = adBreakState;
+        adBreakState.completedReason = reason;
+        const key = adBreakKey(adBreak);
+        // A non-once midroll ad may be replayed if the region is re-entered
+        // due to a back-seek.
+        if (adBreak.once ||
+            adBreak.placement === 'preroll' ||
+            adBreak.placement === 'postroll') {
+            this.completeAdBreakIds.add(key);
+        }
+        else {
+            // Non-once midroll
+            this.spentBreakIds.add(key);
+        }
+        // Interstitials play on a separate track, so the content timeline never
+        // advances during the break: content resumes at the cue point plus any
+        // explicit offset (default 0). max() keeps a forward seek from being
+        // rewound.
+        const resumePosition = Math.max(this.lastPlaybackTime, adBreak.startTime + (adBreak.resumeOffset ?? 0));
+        this.completeAd(adBreakState.adState, reason); // does nothing if no current ad
+        logDebug(this, `adBreakCompleted, active break id:${adBreak.id} reason:${reason} resumePosition:${resumePosition}`);
+        if (adBreakState === this.adBreakState) {
+            this.adBreakState = null;
+        }
+        this.dispatch('adBreakCompleted', { adBreak, resumePosition, reason });
+    }
+    get currentAdBreak() {
+        return this.adBreakState?.adBreak ?? null;
+    }
+    /**
+     * Marks an ad as completed and emits an `adCompleted` event.
+     */
+    completeAd(adState, reason) {
+        if (!adState || adState.completedReason)
+            return; // no-op
+        logDebug(this, `adCompleted id=${adState.ad.id} reason=${reason} index=${adState.index} totalAds=${adState.totalAds}`);
+        // Fold this ad's actual playout into the break total before clearing it.
+        adState.parentBreak.playoutElapsed += this.adElapsed();
+        adState.completedReason = reason;
+        this.dispatch('adCompleted', {
+            adBreak: adState.parentBreak.adBreak,
+            ad: adState.ad,
+            reason,
+            index: adState.index,
+            totalAds: adState.totalAds,
+        });
+        if (adState.index >= adState.totalAds - 1) {
+            this.completeAdBreak(adState.parentBreak, reason);
+        }
+    }
+    /**
+     * Polls the next pending ad and activates it.
+     * When there are no remaining ads, activates the next ad break (if any).
+     */
+    nextAdOrBreak() {
+        if (this.disposed || this.loadingNext)
+            return;
+        const adBreakState = this.adBreakState;
+        if (!adBreakState && !this.pendingAdBreaks.length) {
+            logDebug(this, 'nextAdOrBreak no-op');
+            return;
+        }
+        logDebug(this, 'nextAdOrBreak');
+        this.loadingNext = true;
+        const nextAd = async (adBreakState) => {
+            logVerbose(this, 'nextAd');
+            try {
+                const ad = await adBreakState.nextAd();
+                // The break may have been completed or swapped out (a content
+                // change, skip, or playout-limit) while its ads were resolving;
+                // don't start an ad for an abandoned break.
+                if (this.disposed)
+                    return;
+                if (adBreakState.completedReason) {
+                    // Whoever completed it could not advance (this call still
+                    // holds `loadingNext`), and nothing else drains the pending
+                    // list — a non-empty list blocks midroll ingress outright.
+                    if (!this.adBreakState)
+                        await nextBreak();
+                    return;
+                }
+                if (ad) {
+                    this.startAd(ad);
+                }
+                else {
+                    // No remaining ads in this break
+                    logVerbose(this, 'no remaining ads');
+                    this.completeAdBreak(adBreakState, 'ended');
+                    await nextBreak();
+                }
+            }
+            catch (error) {
+                if (this.disposed)
+                    return;
+                // The ad list failed to resolve: surface the error, complete
+                // this break so content can resume, then advance to any pending
+                // break. Re-calling nextAdOrBreak() here would no-op (loadingNext
+                // is still held by this in-flight call) AND would leave the break
+                // stuck non-null, permanently blocking midroll ingress.
+                this.dispatch('adError', {
+                    adBreak: adBreakState.adBreak,
+                    currentAd: null,
+                    error,
+                });
+                this.completeAdBreak(adBreakState, 'error');
+                await nextBreak();
+            }
+        };
+        const nextBreak = async () => {
+            logVerbose(this, 'nextBreak');
+            if (this.pendingAdBreaks.length) {
+                // There are pending breaks, take the next one and start its first ad.
+                const adBreak = this.pendingAdBreaks.shift();
+                this.adBreakState = createAdBreakState(adBreak);
+                logDebug(this, 'adBreakEntered', adBreak);
+                this.dispatch('adBreakEntered', { adBreak });
+                await nextAd(this.adBreakState);
+            }
+            else {
+                logDebug(this, 'no remaining breaks');
+            }
+        };
+        (async () => {
+            if (adBreakState) {
+                await nextAd(adBreakState);
+            }
+            else {
+                await nextBreak().catch(noop);
+            }
+        })()
+            .catch(noop)
+            .finally(() => {
+            this.loadingNext = false;
+        });
+    }
+    get currentAd() {
+        return this.adState?.ad ?? null;
+    }
+    get adState() {
+        return this.adBreakState?.adState ?? null;
+    }
+    startAd(adState) {
+        const { ad, index, totalAds } = adState;
+        logDebug(this, 'adEntered', adState.ad);
+        this.dispatch('adEntered', {
+            adBreak: adState.parentBreak.adBreak,
+            ad,
+            index,
+            totalAds,
+        });
+        this.emitTimeUpdate(adState).catch(noop);
+        sleep(this.options.adLoadTimeout)
+            .then(() => {
+            if (this.disposed)
+                return;
+            if (this.adState === adState && !adState.started) {
+                this.failAd(new AdError(`Ad failed to start after ${this.options.adLoadTimeout} seconds`));
+            }
+        })
+            .catch(noop);
+    }
+    /**
+     * Checks if the playhead has entered a time to activate a midroll ad.
+     */
+    onTimeUpdate = () => {
+        const adBreak = this.currentAdBreak;
+        const adState = this.adState;
+        if (adBreak) {
+            // Ad progress events
+            if (adState && adState.completedReason == null) {
+                this.emitAdProgressEvents(adState).catch(noop);
+                this.enforcePlayoutLimits(adState);
+            }
+            return;
+        }
+        const pC = this.deps.playbackController;
+        if (this.hasProvider && pC.playing && !this.pendingAdBreaks.length) {
+            // Not an ad playing, main content.
+            this.lastPlaybackTime = pC.currentTime;
+            this.checkAdPreload(pC.currentTime);
+            this.checkMidrollIngress();
+        }
+    };
+    /**
+     * Emits `adPreload` once for each midroll/postroll break the playhead is
+     * approaching — within (the break's {@link AdBreakInfo.resolutionTimeOffset}
+     * or, when absent, the `preloadAheadTime` option) seconds before its start —
+     * so a consumer can resolve and warm the break's assets before entry.
+     * Suppressed (played-once/spent) breaks are skipped.
+     */
+    checkAdPreload(time) {
+        for (const adBreak of this.preloadableBreaks) {
+            const key = adBreakKey(adBreak);
+            if (this.preloadedBreakIds.has(key))
+                continue;
+            if (this.isBreakSuppressed(adBreak))
+                continue;
+            const offset = adBreak.resolutionTimeOffset ?? this.options.preloadAheadTime;
+            // Only ahead of the break; at/after its start, ingress takes over.
+            if (time >= adBreak.startTime - offset &&
+                time < adBreak.startTime) {
+                this.preloadedBreakIds.add(key);
+                logDebug(this, 'adPreload', adBreak.id);
+                this.dispatch('adPreload', { adBreak });
+            }
+        }
+    }
+    /**
+     * Main content with ad breaks is playing, check if we have entered a midroll region.
+     */
+    checkMidrollIngress() {
+        const time = this.deps.playbackController.currentTime;
+        const midrolls = this.midrollAds;
+        // Upper bound: the first midroll whose startTime is strictly after the
+        // playhead. Every candidate break is at an index before it.
+        const upper = sortedInsertionIndex(midrolls, time, (time, ad) => time - ad.startTime);
+        const newPending = [];
+        // Scan every break at or before the playhead, ascending (timeline
+        // order), so tied start times and an earlier still-open break that
+        // contains the playhead (e.g. after a seek into or over it) are all
+        // considered — not just the single nearest preceding break.
+        for (let i = 0; i < upper; i++) {
+            const midroll = midrolls[i];
+            if (this.isBreakSuppressed(midroll))
+                continue;
+            const duration = midroll.duration == null || midroll.restrict.jump
+                ? Number.MAX_VALUE
+                : midroll.duration;
+            if (time < midroll.startTime + duration) {
+                newPending.push(midroll);
+            }
+        }
+        if (newPending.length) {
+            logVerbose(this, 'setting midrolls');
+            this.setPendingBreaks(newPending);
+        }
+    }
+    /**
+     * Emits events for `adTimeUpdate`, `adFirstQuartile`, `adMidpoint`, and
+     * `adThirdQuartile`.
+     * (Does not emit `adCompleted`)
+     */
+    async emitAdProgressEvents(adState) {
+        const pC = this.deps.playbackController;
+        await this.emitTimeUpdate(adState);
+        if (isFinite(pC.duration) && pC.duration > 0) {
+            // Take a running average of the playback rate. Applications can
+            // use this to detect tampering when emitting metrics.
+            adState.dataPoints++;
+            adState.playbackRateAvg = lerp(adState.playbackRateAvg, pC.playbackRate, 1 / adState.dataPoints);
+            // If the ad's duration is set, take the shorter of the ad duration
+            const currProgress = pC.currentTimePercent;
+            const progressStart = adState.timeStart / pC.duration;
+            if (!adState.quartile.first &&
+                currProgress > 0.25 &&
+                progressStart < AD_START_TOLERANCE) {
+                adState.quartile.first = true;
+                this.dispatch('adFirstQuartile', createAdProgressEvent(adState));
+            }
+            if (!adState.quartile.midpoint &&
+                currProgress > 0.5 &&
+                progressStart < 0.25 + AD_START_TOLERANCE) {
+                adState.quartile.midpoint = true;
+                this.dispatch('adMidpoint', createAdProgressEvent(adState));
+            }
+            if (!adState.quartile.third &&
+                currProgress > 0.75 &&
+                progressStart < 0.5 + AD_START_TOLERANCE) {
+                adState.quartile.third = true;
+                this.dispatch('adThirdQuartile', createAdProgressEvent(adState));
+            }
+            // adEnded is not on progress but on a call to `endAd()`.
+        }
+    }
+    async emitTimeUpdate(adState) {
+        const pC = this.deps.playbackController;
+        const { ad, parentBreak } = adState;
+        // Surface elapsed/remaining time for the ad and the break as a
+        // whole so applications don't derive it from the media duration.
+        const adPlayed = this.adElapsed();
+        const adBreak = parentBreak.adBreak;
+        const naturalAdTotal = ad.duration ?? (isFinite(pC.duration) ? pC.duration : null);
+        // The break's playout limit is a budget shared across all its ads, so
+        // the current ad can run no longer than the budget left after the ads
+        // that already played. Cap its reported total by that remainder —
+        // matching enforcePlayoutLimits, which cuts the ad (and break) off at
+        // exactly this point. Without the cap adTimeRemaining over-reports (the
+        // full asset duration) while the ad is actually stopped at the limit.
+        const limit = adBreak.playoutLimit;
+        const adTotal = limit != null
+            ? Math.min(naturalAdTotal ?? Infinity, Math.max(0, limit - parentBreak.playoutElapsed))
+            : naturalAdTotal;
+        const breakPlayed = parentBreak.playoutElapsed + adPlayed;
+        const breakTotal = limit ?? adBreak.duration;
+        const { canSkip, skipIn } = await this.resolveSkipState(parentBreak, breakPlayed);
+        this.dispatch('adTimeUpdate', {
+            adBreak: adState.parentBreak.adBreak,
+            ad,
+            index: adState.index,
+            totalAds: adState.totalAds,
+            adCurrentTime: adPlayed,
+            adTimeRemaining: adTotal != null ? Math.max(0, adTotal - adPlayed) : null,
+            breakCurrentTime: breakPlayed,
+            breakTimeRemaining: breakTotal != null
+                ? Math.max(0, breakTotal - breakPlayed)
+                : null,
+            canSkip,
+            skipIn,
+        });
+    }
+    /**
+     * Enforces the break-level playout limit (X-PLAYOUT-LIMIT): a budget shared
+     * across all of the break's ads. When cumulative playout reaches it, the
+     * whole break ends, dropping any ads that have not started.
+     *
+     * This is deliberately NOT a per-ad cap. Each ad asset is its own source and
+     * ends on its media `ended` (see the 'ended' handler), which is what advances
+     * a multi-ad break. Ending an ad at its declared per-ad DURATION instead would
+     * truncate the real asset whenever a packager under-declares it — e.g. rounds
+     * a 6.732s asset down to a whole-second 6 — cutting off the fractional tail.
+     */
+    enforcePlayoutLimits(adState) {
+        if (!adState.started)
+            return;
+        const { parentBreak } = adState;
+        // Enforce independent of a finite content duration so live ads with a
+        // declared playout limit are still bounded.
+        const limit = parentBreak.adBreak.playoutLimit;
+        if (limit == null)
+            return;
+        const pC = this.deps.playbackController;
+        const elapsed = Math.max(0, pC.currentTime - adState.timeStart);
+        if (parentBreak.playoutElapsed + elapsed < limit)
+            return;
+        // Budget reached — but if the current ad is essentially at its natural
+        // media end (within PLAYOUT_LIMIT_TOLERANCE of the playback-reported
+        // duration), let it finish on its own `ended` rather than clipping the
+        // tail. A known finite, positive duration is required; an unknown (0) or
+        // non-finite duration (e.g. live) enforces the limit strictly.
+        if (isFinite(pC.duration) &&
+            pC.duration > 0 &&
+            pC.duration - pC.currentTime <= PLAYOUT_LIMIT_TOLERANCE) {
+            return;
+        }
+        // The break's total playout limit is reached: end the whole break,
+        // dropping any ads that have not started.
+        parentBreak.clear();
+        this.endAd(adState);
+    }
+    setPendingBreaks(newPending) {
+        this.pendingAdBreaks = newPending.filter((adBreak) => !this.isBreakSuppressed(adBreak));
+        const n = this.pendingAdBreaks.length;
+        logDebug(this, `setPendingBreaks len=${n}, suppressed=${newPending.length - n}`);
+        this.nextAdOrBreak();
+    }
+    skipAd() {
+        this.completeAd(this.adState, 'skipped');
+        this.nextAdOrBreak();
+    }
+    failAd(error) {
+        const adState = this.adState;
+        if (adState) {
+            // Capture the failing ad before completeAd() clears it, so the
+            // adError event can distinguish an individual-ad failure from an
+            // ad-list load failure (currentAd == null).
+            this.completeAd(adState, 'error');
+            this.dispatch('adError', {
+                error,
+                adBreak: adState.parentBreak.adBreak,
+                currentAd: adState.ad,
+            });
+        }
+        this.nextAdOrBreak();
+    }
+    endAd(adState) {
+        this.completeAd(adState, 'ended');
+        this.dispatch('adEnded', createAdProgressEvent(adState));
+        this.nextAdOrBreak();
+    }
+    get disposed() {
+        return this.disposer.disposed;
+    }
+    /**
+     * Disposes this controller, removes all listeners.
+     */
+    dispose() {
+        super.dispose();
+        // Tear down the ads-provider subscription so a late adsChange can't
+        // re-run ad discovery (and log) after dispose.
+        this.adsProviderSub?.();
+        this.disposer.dispose();
+        // Detach any active break so currentAd/currentAdBreak read null after
+        // dispose, even if a break's ad list resolves late (startAd is already
+        // guarded by the disposed check, so no adEntered/adPlaying fires).
+        this.adBreakState = null;
+    }
+}
+function createAdProgressEvent(adState) {
+    return {
+        adBreak: adState.parentBreak.adBreak,
+        ad: adState.ad,
+        // Snapped to nearest 0.1 to avoid ~1.0
+        playbackRateAvg: roundToNearest(adState.playbackRateAvg, 0.1),
+        index: adState.index,
+        totalAds: adState.totalAds,
+    };
+}
+function createAdBreakState(adBreak) {
+    let _currentIndex = -1;
+    let _adState = null;
+    const logTarget = {
+        logPrefix: createLogPrefix('AdBreakState'),
+    };
+    const adBreakState = {
+        adBreak,
+        playoutElapsed: 0,
+        completedReason: null,
+        get adState() {
+            return _adState;
+        },
+        async nextAd() {
+            const ads = await getAds();
+            if (_currentIndex >= ads.length)
+                return null;
+            _adState = getElementOrDefault(ads, ++_currentIndex, null);
+            return _adState;
+        },
+        clear() {
+            _adState = null;
+            _currentIndex = Number.MAX_VALUE;
+        },
+    };
+    const getAds = memoize(() => {
+        logVerbose(logTarget, `requesting ads for break ${adBreak.placement} ${adBreak.id}`);
+        return resolveValueProvider(adBreak.ads).then((ads) => {
+            logVerbose(logTarget, 'ads resolved', ads);
+            return ads.map((adInfo, index) => {
+                return createAdState({
+                    adBreakState: adBreakState,
+                    ad: adInfo,
+                    totalAds: ads.length,
+                    index: index,
+                });
+            });
+        });
+    });
+    return adBreakState;
+}
+function createAdState({ adBreakState, ad, totalAds, index, }) {
+    return {
+        parentBreak: adBreakState,
+        ad,
+        index,
+        totalAds,
+        started: false,
+        timeStart: 0,
+        playbackRateAvg: 0,
+        dataPoints: 0,
+        quartile: {
+            first: false,
+            midpoint: false,
+            third: false,
+        },
+        completedReason: null,
+    };
+}
+/** Combines the placement and id of the break for unique reference by placement */
+function adBreakKey(adBreak) {
+    return `${adBreak.placement}_${adBreak.id}`;
+}