@streamlayer/feature-advertisement 0.4.3 → 1.0.0

package/lib/units/ssai-detector.js

@@ -0,0 +1,1150 @@
+import { createLogger } from '@streamlayer/sdk-web-logger';
+const log = createLogger('ssai:detector');
+const RANGE_EXPIRY_MS = 10 * 60 * 1000;
+const ACTIVE_POLL_MS = 250;
+const MANIFEST_POLL_MS = 3000;
+/**
+ * Supplemental manifest poll cadence on the hls.js path.
+ *
+ * hls.js re-reads a live playlist about once per target duration, and a DAI
+ * playout publishes an ad's tracking markers only seconds AFTER that ad started
+ * at the live edge (measured on the live playout: ~5s), while a default-config
+ * viewer trails the edge by ~3 target durations. The leftover headroom is close
+ * to zero — the bar for the second ad of a pod rose late simply because the
+ * manifest carrying its markers had not been re-read yet. Polling the active
+ * level's playlist at 1s shaves that reload latency. DATERANGE merging only;
+ * the program clock still comes from `playingDate`.
+ */
+const LIVE_EDGE_POLL_MS = 1000;
+/**
+ * The end edge's ambiguity window. Both edges normally fire on the poll tick —
+ * the end is decided from the schedule, not a timer (see `updateActiveAd`): a
+ * break with no further window opening within this span is really over and
+ * closes immediately. The timer covers only what the schedule cannot settle on
+ * the spot: the next ad of a pod opens within this window (hold the bar through
+ * the gap — entering it cancels the timer), or the program clock is momentarily
+ * unreadable.
+ */
+const END_DEBOUNCE_MS = 1000;
+/**
+ * A window shorter than this is noise, not an ad — no real creative runs under
+ * 2s (bumpers are 6s), while a misread marker or degenerate fold easily does.
+ * This is the data-domain replacement for the start debounce that used to keep
+ * short windows from flashing: filtering them out entirely costs no latency on
+ * real ads.
+ */
+const MIN_AD_WINDOW_MS = 2000;
+const DEBUG_EVENTS_MAX = 50;
+const DROPPED_KEYS_MAX = 100;
+/**
+ * How far before the active ad window's end `onAdEnding` fires. Sized to fit
+ * the overlay's closing fade (200ms) plus one poll tick, so the bar finishes
+ * dissolving roughly AT the boundary — and the next ad of a pod then enters
+ * with its own animation instead of the content swapping inside an open
+ * overlay.
+ */
+const AD_ENDING_LEAD_MS = 500;
+/** Lifecycle beacons, keyed by the fraction of the ad window that triggers them. */
+const PROGRESS_THRESHOLDS = [
+    ['start', 0],
+    ['firstQuartile', 0.25],
+    ['midpoint', 0.5],
+    ['thirdQuartile', 0.75],
+];
+// hls.js event names — kept as string constants to avoid importing hls.js.
+const HLS_EVENT_LEVEL_UPDATED = 'hlsLevelUpdated';
+const HLS_EVENT_FRAG_CHANGED = 'hlsFragChanged';
+const readAttr = (attrs, key) => {
+    if (!attrs) {
+        return undefined;
+    }
+    if (typeof attrs.get === 'function') {
+        return attrs.get(key);
+    }
+    return attrs[key];
+};
+const toTimeMs = (value) => {
+    if (value instanceof Date) {
+        return value.getTime();
+    }
+    if (typeof value === 'number') {
+        return value > 1_000_000_000_000 ? value : value * 1000;
+    }
+    if (typeof value === 'string' && value.length > 0) {
+        const parsed = Date.parse(value);
+        return Number.isFinite(parsed) ? parsed : NaN;
+    }
+    return NaN;
+};
+const normalizeRange = (range) => {
+    if (!range.creativeId || !Number.isFinite(range.startMs) || !Number.isFinite(range.durationSec)) {
+        return null;
+    }
+    const id = range.id || `${range.creativeId}-${range.startMs}`;
+    return {
+        id,
+        creativeId: range.creativeId,
+        startMs: range.startMs,
+        durationSec: range.durationSec,
+        endMs: range.startMs + range.durationSec * 1000,
+    };
+};
+// -- DATERANGE dialects ------------------------------------------------------
+//
+// Two shapes of ad signalling are supported, told apart by the tags themselves
+// rather than by configuration — a stream may even carry both.
+//
+// 1. CREATIVE ranges (StreamLayer): ONE DATERANGE per creative whose own
+//    START-DATE/DURATION *is* the ad window, identified by `X-CREATIVE-ID`
+//    (or `X-AD-ID`).
+//
+// 2. TRACKING markers (Synamedia/Quortex DAI): a burst of DATERANGEs per ad,
+//    each `DURATION=0.250`, carrying `X-AD-ID` + `X-AD-EVENT-TYPE`
+//    (impression / start / quartiles / complete) and the beacon in `X-AD-URL`,
+//    plus one `CLASS="com.synamedia.dai.adbreak"` range spanning the break.
+//
+//    A marker's own 250ms duration is NOT the ad window — taking it literally
+//    would put every break below MIN_AD_WINDOW_MS, and the bar would never show
+//    at all. The ad's real window is its `start` marker through its `complete`
+//    marker, which is what `foldTrackingMarkers` reconstructs (measured against
+//    the live stream: start 10:38:04.628 → complete 10:38:19.610 = 14.982s,
+//    exactly the sibling adbreak range's DURATION).
+const SYNAMEDIA_ADBREAK_CLASS = 'com.synamedia.dai.adbreak';
+/**
+ * Classify one DATERANGE. Order matters: a tracking marker also carries
+ * `X-AD-ID`, so the event-type test has to come before the creative test or
+ * every marker would be mistaken for a 250ms ad.
+ */
+const classifyDateRange = (fields) => {
+    const { id, creativeId, adId, eventType, className, adUrl, startMs, durationSec } = fields;
+    if (!Number.isFinite(startMs)) {
+        return {
+            kind: 'invalid',
+            key: id || `${creativeId || adId || className || 'unknown'}-no-start`,
+            detail: `no usable START-DATE (id=${id || 'n/a'}, creative=${creativeId || adId || 'n/a'})`,
+        };
+    }
+    if (eventType && adId) {
+        return {
+            kind: 'marker',
+            marker: { id: id || `${adId}-${eventType}-${startMs}`, adId, event: eventType, timeMs: startMs, url: adUrl },
+        };
+    }
+    if (className === SYNAMEDIA_ADBREAK_CLASS && Number.isFinite(durationSec)) {
+        return {
+            kind: 'adbreak',
+            window: { id: id || `adbreak-${startMs}`, startMs, endMs: startMs + durationSec * 1000 },
+        };
+    }
+    // `X-AD-ID` is accepted alongside `X-CREATIVE-ID` so a stream that marks the
+    // ad directly (id + real duration, no tracking burst) still works.
+    const resolvedCreativeId = creativeId || adId;
+    const range = normalizeRange({ id, creativeId: resolvedCreativeId, startMs, durationSec });
+    if (!range) {
+        return {
+            kind: 'invalid',
+            key: id || `no-creative-id-${startMs}`,
+            detail: `no usable creative id or duration (id=${id || 'n/a'}, start=${debugClock(startMs)})`,
+        };
+    }
+    return { kind: 'creative', range };
+};
+// A playout rotates a small ad pool, so the SAME creative re-airs minutes apart
+// and its markers — up to RANGE_EXPIRY_MS of them — share one `X-AD-ID`.
+// Markers of one ad id therefore must be clustered into AIRINGS before folding;
+// a global min→max fold spans the CONTENT between two airings (observed live: a
+// 15s creative folded into a 305s window, so the bar opened 282s before its ad
+// video, all four quartile beacons fired in one tick, and the error grew with
+// watch time as older markers stretched the window further back).
+//
+// An airing boundary is decided by the playout's own break signalling first —
+// two markers inside DIFFERENT `com.synamedia.dai.adbreak` windows are different
+// airings — and by dwell gap when either marker sits outside every known break
+// window: within one airing, consecutive markers are at most a quartile apart
+// (ad duration / 4), so a gap above this threshold cannot be the same airing.
+const MARKER_AIRING_GAP_MS = 60 * 1000;
+// A `complete` marker regularly lands exactly ON its break's end boundary (and
+// encoders jitter a little past it), so window membership is tested with slack.
+const MARKER_BREAK_TOLERANCE_MS = 1000;
+/**
+ * `X-AD-EVENT-TYPE` values that map onto lifecycle beacons, lowercased. The
+ * marker's own timestamp is the ad server's declared time for that beacon, so it
+ * beats deriving the quartile from fractions of the (possibly provisional) window.
+ */
+const PROGRESS_MARKER_EVENTS = {
+    start: 'start',
+    firstquartile: 'firstQuartile',
+    midpoint: 'midpoint',
+    thirdquartile: 'thirdQuartile',
+    complete: 'complete',
+};
+/**
+ * Which break window does a marker belong to?
+ *
+ * The live playout emits ONE `adbreak` range PER AD, back-to-back — so two
+ * windows share a boundary instant exactly, and time alone cannot decide it:
+ * ad N's `complete` and ad N+1's `impression`/`start` sit on the SAME
+ * millisecond, one belonging left and one right. (Observed live: assigning
+ * ad N+1's start markers to ad N's window split them off into a separate
+ * degenerate airing, so the visible window began at the FIRST QUARTILE and the
+ * second ad's bar rose ~a quarter of the ad late.) The event's meaning breaks
+ * the tie — a closing marker sits on its break's END, an opening one on its
+ * START. Everything else prefers strict containment, with the ±tolerance pass
+ * as the fallback for encoder jitter past a boundary.
+ */
+const findEnclosingBreak = (breaks, timeMs, event) => {
+    const kind = event ? event.toLowerCase() : '';
+    if (kind === 'complete') {
+        const closing = breaks.find((window) => Math.abs(window.endMs - timeMs) <= MARKER_BREAK_TOLERANCE_MS);
+        if (closing) {
+            return closing;
+        }
+    }
+    if (kind === 'impression' || kind === 'start') {
+        const opening = breaks.find((window) => Math.abs(window.startMs - timeMs) <= MARKER_BREAK_TOLERANCE_MS);
+        if (opening) {
+            return opening;
+        }
+    }
+    return (breaks.find((window) => timeMs >= window.startMs && timeMs < window.endMs) ||
+        breaks.find((window) => timeMs >= window.startMs - MARKER_BREAK_TOLERANCE_MS && timeMs <= window.endMs + MARKER_BREAK_TOLERANCE_MS));
+};
+/**
+ * Reconstruct one ad window per AIRING of an `X-AD-ID` from its tracking
+ * markers: earliest marker (impression/start) to latest (complete).
+ *
+ * `breaks` separates re-airings of the same creative (see above) and is the
+ * fallback end: until the `complete` marker shows up, an airing whose markers
+ * all share one timestamp would fold to a zero-length window and never display;
+ * when an enclosing adbreak range covers it, its end is used instead, and the
+ * window tightens on the refresh that brings `complete` in.
+ *
+ * Exported for unit tests only — production code reaches it through the
+ * detector.
+ */
+export const foldTrackingMarkers = (markers, breaks) => {
+    const byAdId = new Map();
+    for (const marker of markers) {
+        const group = byAdId.get(marker.adId);
+        if (group) {
+            group.push(marker);
+        }
+        else {
+            byAdId.set(marker.adId, [marker]);
+        }
+    }
+    const ranges = [];
+    for (const [adId, group] of byAdId.entries()) {
+        group.sort((left, right) => left.timeMs - right.timeMs);
+        // Split the sorted markers into airings.
+        const airings = [];
+        let current = [];
+        let currentBreak;
+        for (const marker of group) {
+            const markerBreak = findEnclosingBreak(breaks, marker.timeMs, marker.event);
+            if (current.length > 0) {
+                const previous = current[current.length - 1];
+                const startsNewAiring = markerBreak && currentBreak
+                    ? markerBreak !== currentBreak
+                    : marker.timeMs - previous.timeMs > MARKER_AIRING_GAP_MS;
+                if (startsNewAiring) {
+                    airings.push(current);
+                    current = [];
+                    currentBreak = undefined;
+                }
+            }
+            current.push(marker);
+            if (markerBreak) {
+                currentBreak = markerBreak;
+            }
+        }
+        if (current.length > 0) {
+            airings.push(current);
+        }
+        for (const airing of airings) {
+            const startMs = airing[0].timeMs;
+            let endMs = airing[airing.length - 1].timeMs;
+            if (endMs <= startMs) {
+                // An airing's first marker is its impression/start, so resolve the
+                // enclosing break with opening semantics — on a shared boundary the
+                // window STARTING here is the one this airing belongs to.
+                const enclosing = findEnclosingBreak(breaks, startMs, 'start');
+                endMs = enclosing ? enclosing.endMs : startMs;
+            }
+            if (endMs <= startMs) {
+                continue;
+            }
+            // The airing is sorted, so the first marker of an event is its earliest —
+            // and the only one there should be.
+            const progressAtMs = {};
+            for (const airingMarker of airing) {
+                const progressEvent = PROGRESS_MARKER_EVENTS[airingMarker.event.toLowerCase()];
+                if (progressEvent && progressAtMs[progressEvent] === undefined) {
+                    progressAtMs[progressEvent] = airingMarker.timeMs;
+                }
+            }
+            ranges.push({
+                id: `ssai-ad:${adId}:${startMs}`,
+                creativeId: adId,
+                startMs,
+                durationSec: (endMs - startMs) / 1000,
+                endMs,
+                ...(Object.keys(progressAtMs).length > 0 ? { progressAtMs } : {}),
+            });
+        }
+    }
+    return ranges;
+};
+const parseHlsDateRange = (raw) => {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const attr = raw.attr || raw.attrs || raw.attributes;
+    return classifyDateRange({
+        id: raw.id || readAttr(attr, 'ID'),
+        creativeId: readAttr(attr, 'X-CREATIVE-ID') || raw['X-CREATIVE-ID'],
+        adId: readAttr(attr, 'X-AD-ID') || raw['X-AD-ID'],
+        eventType: readAttr(attr, 'X-AD-EVENT-TYPE'),
+        className: readAttr(attr, 'CLASS'),
+        adUrl: readAttr(attr, 'X-AD-URL'),
+        startMs: toTimeMs(raw.startDate || raw.startDateTime || readAttr(attr, 'START-DATE')),
+        durationSec: Number(raw.duration || readAttr(attr, 'DURATION')),
+    });
+};
+const parseAttributeList = (input) => {
+    const attrs = {};
+    let index = 0;
+    while (index < input.length) {
+        while (input[index] === ',' || input[index] === ' ') {
+            index += 1;
+        }
+        const keyStart = index;
+        while (index < input.length && input[index] !== '=') {
+            index += 1;
+        }
+        const key = input.slice(keyStart, index).trim();
+        index += 1;
+        let value;
+        if (input[index] === '"') {
+            index += 1;
+            const valueStart = index;
+            while (index < input.length && input[index] !== '"') {
+                index += 1;
+            }
+            value = input.slice(valueStart, index);
+            index += 1;
+        }
+        else {
+            const valueStart = index;
+            while (index < input.length && input[index] !== ',') {
+                index += 1;
+            }
+            value = input.slice(valueStart, index).trim();
+        }
+        if (key) {
+            attrs[key] = value;
+        }
+        if (input[index] === ',') {
+            index += 1;
+        }
+    }
+    return attrs;
+};
+const parseManifestDateRanges = (manifest) => {
+    return manifest
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith('#EXT-X-DATERANGE:'))
+        .map((line) => {
+        const attr = parseAttributeList(line.slice('#EXT-X-DATERANGE:'.length));
+        return classifyDateRange({
+            id: attr.ID,
+            creativeId: attr['X-CREATIVE-ID'],
+            adId: attr['X-AD-ID'],
+            eventType: attr['X-AD-EVENT-TYPE'],
+            className: attr.CLASS,
+            adUrl: attr['X-AD-URL'],
+            startMs: toTimeMs(attr['START-DATE']),
+            durationSec: Number(attr.DURATION),
+        });
+    })
+        .filter((parsed) => Boolean(parsed));
+};
+// Parse media-playlist segments and assign each a program time (ms).
+//
+// EXT-X-PROGRAM-DATE-TIME anchors absolute time to the *next* segment; we then
+// accumulate EXTINF durations forward until the next explicit PDT re-anchors.
+// For a live sliding window, only some refreshes carry a fresh PDT (typically
+// the first segment), so we must accept a PDT that appears mid-playlist and
+// re-anchor from there rather than latching the first value of the file.
+const parseManifestSegments = (manifest) => {
+    const segments = [];
+    let nextDurationSec = NaN;
+    let currentProgramDateTimeMs = NaN;
+    for (const rawLine of manifest.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line) {
+            continue;
+        }
+        if (line.startsWith('#EXTINF:')) {
+            nextDurationSec = Number(line.slice('#EXTINF:'.length).split(',')[0]);
+            continue;
+        }
+        if (line.startsWith('#EXT-X-PROGRAM-DATE-TIME:')) {
+            // Explicit anchor — re-base accumulation from here (handles refreshes whose
+            // first segment carries the only PDT, and mid-playlist re-anchors).
+            currentProgramDateTimeMs = toTimeMs(line.slice('#EXT-X-PROGRAM-DATE-TIME:'.length));
+            continue;
+        }
+        if (line.startsWith('#')) {
+            continue;
+        }
+        const durationSec = Number.isFinite(nextDurationSec) ? nextDurationSec : 0;
+        segments.push({ url: line, durationSec, programDateTimeMs: currentProgramDateTimeMs });
+        currentProgramDateTimeMs = Number.isFinite(currentProgramDateTimeMs)
+            ? currentProgramDateTimeMs + durationSec * 1000
+            : NaN;
+        nextDurationSec = NaN;
+    }
+    return segments;
+};
+const mediaRangeEnd = (ranges) => {
+    if (!ranges || ranges.length === 0) {
+        return NaN;
+    }
+    return ranges.end(ranges.length - 1);
+};
+const findLast = (items, predicate) => {
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        if (predicate(items[index])) {
+            return items[index];
+        }
+    }
+    return undefined;
+};
+/** "HH:MM:SS.mmm" (UTC) for debug-event details; program time and START-DATE share the UTC timeline. */
+const debugClock = (ms) => (Number.isFinite(ms) ? new Date(ms).toISOString().slice(11, 23) : 'n/a');
+export const createSsaiDetector = (options) => {
+    const { player, videoRef, manifestUrl, onAdDiscovered, onBreakStart, onCreativeChange, onAdEnding, onBreakEnd, onProgress, } = options;
+    const video = player?.media ?? videoRef;
+    if (!player && !video) {
+        log.info('ssai detector: neither player nor videoRef provided, no-op');
+        return {
+            destroy: () => undefined,
+            dismissActiveBreak: () => undefined,
+            getDebugSnapshot: () => ({
+                wallMs: Date.now(),
+                programMs: NaN,
+                clockSource: 'wall-clock',
+                attachMode: 'none',
+                playingDateMs: NaN,
+                pdtOriginProgramMs: NaN,
+                programTimeOriginMs: NaN,
+                hls: null,
+                video: null,
+                ranges: [],
+                markerCount: 0,
+                adBreakCount: 0,
+                breakActive: false,
+                breakSuppressed: false,
+                activeRangeId: null,
+                activeCreativeId: null,
+                progress: null,
+                events: [],
+            }),
+        };
+    }
+    // Creative ranges arrive ready to use; tracking markers have to be kept raw and
+    // re-folded on every refresh, since a later manifest is what carries the
+    // `complete` marker that closes an ad's window.
+    const rangesById = new Map();
+    const markersById = new Map();
+    const adBreaksById = new Map();
+    let programTimeOriginMs = NaN;
+    // active state
+    let activeRangeId = '';
+    let activeCreativeId = '';
+    // End-edge debounce only; a break START fires the instant the playhead enters
+    // a window (short/bogus windows are filtered by MIN_AD_WINDOW_MS instead).
+    let breakEndTimer = null;
+    let breakActive = false;
+    // User dismissed the current break: stay hidden (no creative-change re-show)
+    // until this break ends. A NEW break after this one shows again.
+    let breakSuppressed = false;
+    // Which range already got its one `onAdEnding` announcement.
+    let endingNotifiedRangeId = '';
+    // Lifecycle-beacon state for the ad currently being watched. Tracked per ad
+    // (not per break) so each ad of a pod reports its own quartiles.
+    let progressRange = null;
+    let progressFired = {};
+    let destroyed = false;
+    // Debug-only state. Recording is side-effect free for detection: nothing
+    // below ever reads it back.
+    const debugEvents = [];
+    const seenMarkerAdIds = new Set();
+    // Malformed tags persist in the manifest across refreshes; log each once.
+    const seenDroppedKeys = new Set();
+    const attachMode = player
+        ? 'hls'
+        : videoRef && manifestUrl
+            ? 'manifest-poll'
+            : 'none';
+    const recordDebugEvent = (type, detail, programMs) => {
+        debugEvents.push({
+            wallMs: Date.now(),
+            programMs: programMs !== undefined ? programMs : currentProgramTimeMs(),
+            type,
+            detail,
+        });
+        if (debugEvents.length > DEBUG_EVENTS_MAX) {
+            debugEvents.splice(0, debugEvents.length - DEBUG_EVENTS_MAX);
+        }
+    };
+    const getVideo = () => player?.media ?? video ?? null;
+    // Memoized view over the three marker maps. `updateActiveAd` polls 4×/s and
+    // re-folding markers + sorting on every tick is measurable churn on low-end
+    // TV CPUs; the underlying sets only actually change on a manifest refresh
+    // (every few seconds), so the fold is rebuilt exactly then — `mergeDateRanges`
+    // invalidates when (and only when) an add, a content change or an expiry
+    // really altered them.
+    let rangesCache = null;
+    const invalidateRangesCache = () => {
+        rangesCache = null;
+    };
+    const getRangesCache = () => {
+        if (!rangesCache) {
+            const folded = foldTrackingMarkers(Array.from(markersById.values()), Array.from(adBreaksById.values()));
+            const sorted = Array.from(rangesById.values())
+                .concat(folded)
+                .sort((left, right) => left.startMs - right.startMs);
+            rangesCache = { folded, sorted };
+        }
+        return rangesCache;
+    };
+    /**
+     * A creative id is new to us — hand it to the prefetch hook. Guarded so a
+     * throwing handler can never abort the manifest merge it interrupts.
+     */
+    const notifyAdDiscovered = (creativeId) => {
+        if (!onAdDiscovered) {
+            return;
+        }
+        try {
+            onAdDiscovered(creativeId);
+        }
+        catch (error) {
+            log.warn(error, 'ssai onAdDiscovered handler threw');
+        }
+    };
+    const mergeDateRanges = (parsed) => {
+        const nowMs = Date.now();
+        const expiredBefore = nowMs - RANGE_EXPIRY_MS;
+        let changed = false;
+        for (const entry of parsed) {
+            if (entry.kind === 'invalid') {
+                if (!seenDroppedKeys.has(entry.key)) {
+                    if (seenDroppedKeys.size >= DROPPED_KEYS_MAX) {
+                        seenDroppedKeys.clear();
+                    }
+                    seenDroppedKeys.add(entry.key);
+                    recordDebugEvent('range-dropped', entry.detail);
+                    log.warn({ detail: entry.detail }, 'ssai DATERANGE dropped');
+                }
+                continue;
+            }
+            if (entry.kind === 'creative') {
+                const existing = rangesById.get(entry.range.id);
+                if (!existing) {
+                    changed = true;
+                    recordDebugEvent('range-discovered', `${entry.range.creativeId} ${debugClock(entry.range.startMs)}+${entry.range.durationSec}s`);
+                    notifyAdDiscovered(entry.range.creativeId);
+                }
+                else if (existing.startMs !== entry.range.startMs || existing.endMs !== entry.range.endMs) {
+                    changed = true;
+                }
+                rangesById.set(entry.range.id, entry.range);
+            }
+            else if (entry.kind === 'marker') {
+                if (!seenMarkerAdIds.has(entry.marker.adId)) {
+                    seenMarkerAdIds.add(entry.marker.adId);
+                    recordDebugEvent('marker-ad-discovered', `${entry.marker.adId} ${entry.marker.event}@${debugClock(entry.marker.timeMs)}`);
+                    notifyAdDiscovered(entry.marker.adId);
+                }
+                const existing = markersById.get(entry.marker.id);
+                if (!existing || existing.timeMs !== entry.marker.timeMs) {
+                    changed = true;
+                }
+                markersById.set(entry.marker.id, entry.marker);
+            }
+            else {
+                const existing = adBreaksById.get(entry.window.id);
+                if (!existing) {
+                    changed = true;
+                    recordDebugEvent('adbreak-discovered', `${debugClock(entry.window.startMs)}-${debugClock(entry.window.endMs)}`);
+                }
+                else if (existing.startMs !== entry.window.startMs || existing.endMs !== entry.window.endMs) {
+                    changed = true;
+                }
+                adBreaksById.set(entry.window.id, entry.window);
+            }
+        }
+        for (const [id, range] of rangesById.entries()) {
+            if (range.endMs < expiredBefore) {
+                rangesById.delete(id);
+                changed = true;
+            }
+        }
+        for (const [id, marker] of markersById.entries()) {
+            if (marker.timeMs < expiredBefore) {
+                markersById.delete(id);
+                changed = true;
+            }
+        }
+        // Keep the discovery set in step with expiry so an ad id that legitimately
+        // recurs later (and a stream running for hours) re-logs instead of leaking.
+        if (seenMarkerAdIds.size > 0) {
+            const liveAdIds = new Set();
+            for (const marker of markersById.values()) {
+                liveAdIds.add(marker.adId);
+            }
+            for (const adId of seenMarkerAdIds) {
+                if (!liveAdIds.has(adId)) {
+                    seenMarkerAdIds.delete(adId);
+                }
+            }
+        }
+        for (const [id, window] of adBreaksById.entries()) {
+            if (window.endMs < expiredBefore) {
+                adBreaksById.delete(id);
+                changed = true;
+            }
+        }
+        if (changed) {
+            invalidateRangesCache();
+        }
+    };
+    const findActiveRange = (programTimeMs) => {
+        // A non-finite program time means we have no usable origin yet (e.g. native
+        // HLS before the first PDT-bearing manifest). Skip rather than risk matching
+        // a range against a bogus time.
+        if (!Number.isFinite(programTimeMs)) {
+            return null;
+        }
+        // The LATEST-starting window containing the playhead, not the earliest:
+        // windows overlap while a marker airing's end is still provisional (its
+        // fallback end spans the whole adbreak), and inside the overlap the ad
+        // actually on screen is the one that started last. Picking the earliest
+        // kept the previous ad's creative on the bar until the `complete` marker
+        // arrived to tighten its window — the next ad of a pod showed late.
+        return (findLast(getRangesCache().sorted, (range) => range.endMs - range.startMs >= MIN_AD_WINDOW_MS &&
+            programTimeMs >= range.startMs &&
+            programTimeMs < range.endMs) || null);
+    };
+    /**
+     * Does another qualifying ad window open within `withinMs` after
+     * `programTimeMs`? The data-domain end edge on a live schedule: between two
+     * ads of a pod the next window is already in the manifest, so the bar is held
+     * through the gap — while a break that is really over has nothing upcoming
+     * and closes on the spot.
+     */
+    const nextRangeStartsWithin = (programTimeMs, withinMs) => getRangesCache().sorted.some((range) => range.endMs - range.startMs >= MIN_AD_WINDOW_MS &&
+        range.startMs > programTimeMs &&
+        range.startMs - programTimeMs <= withinMs);
+    /**
+     * Program time of the frame the viewer is looking at — NOT the wall clock.
+     *
+     * The distinction is the whole ballgame for sync. `START-DATE` on a DATERANGE is
+     * program time, while a live viewer's playhead sits seconds behind the live edge
+     * (hls.js starts ~3 target durations back, plus whatever the CDN adds). Answering
+     * with `Date.now()` therefore fires every edge EARLY by exactly that latency: the
+     * overlay would appear a few seconds before the ad video it belongs to — which is
+     * precisely the drift this ordering exists to prevent.
+     *
+     * Preference order: hls.js' own `playingDate`, then our PDT-anchored origin, then
+     * nothing. "Nothing" (NaN) parks the detector until it can answer honestly, which
+     * is the right call — a late bar is a blemish, an early one is wrong.
+     */
+    const currentProgramTimeMs = () => {
+        const playingDateMs = player?.playingDate ? player.playingDate.getTime() : NaN;
+        if (Number.isFinite(playingDateMs)) {
+            return playingDateMs;
+        }
+        const el = getVideo();
+        if (Number.isFinite(programTimeOriginMs) && el && Number.isFinite(el.currentTime)) {
+            return programTimeOriginMs + el.currentTime * 1000;
+        }
+        // There IS a media element, we just cannot map it yet (no PDT seen). Wait for
+        // one rather than guessing with the wall clock and showing the bar early.
+        if (el) {
+            return NaN;
+        }
+        // No media element at all — nothing better than the wall clock exists, and a
+        // player-less integration still deserves break detection.
+        return Date.now();
+    };
+    const updateTimeMapperFromFragment = (fragment, targetDuration) => {
+        if (!fragment) {
+            return;
+        }
+        const start = Number(fragment.start);
+        if (!Number.isFinite(start)) {
+            return;
+        }
+        const pdtMs = toTimeMs(fragment.programDateTime || fragment.rawProgramDateTime || fragment.pdt);
+        if (Number.isFinite(pdtMs)) {
+            programTimeOriginMs = pdtMs - start * 1000;
+            return;
+        }
+        const sequence = Number(fragment.sn);
+        const segmentSec = Number(targetDuration || fragment.duration || 10);
+        if (Number.isFinite(sequence) && Number.isFinite(segmentSec) && segmentSec > 0) {
+            programTimeOriginMs = sequence * segmentSec * 1000 - start * 1000;
+        }
+    };
+    const updateTimeMapperFromDetails = (details) => {
+        const el = getVideo();
+        const fragments = details && (details.fragments || details.frags);
+        if (!el || !Array.isArray(fragments) || fragments.length === 0) {
+            return;
+        }
+        const currentFragment = fragments.find((fragment) => {
+            const start = Number(fragment.start);
+            const duration = Number(fragment.duration);
+            return (Number.isFinite(start) &&
+                Number.isFinite(duration) &&
+                el.currentTime >= start &&
+                el.currentTime < start + duration);
+        });
+        if (currentFragment) {
+            updateTimeMapperFromFragment(currentFragment, details?.targetduration);
+        }
+    };
+    const ingestHlsDateRanges = (details) => {
+        if (!details || !details.dateRanges) {
+            return;
+        }
+        const rawRanges = details.dateRanges instanceof Map
+            ? Array.from(details.dateRanges.values())
+            : Array.isArray(details.dateRanges)
+                ? details.dateRanges
+                : Object.values(details.dateRanges);
+        mergeDateRanges(rawRanges.map(parseHlsDateRange).filter((parsed) => Boolean(parsed)));
+    };
+    // -- native-HLS manifest polling --
+    const nativeBufferedTimeAnchorSec = (el) => {
+        if (!el.buffered || el.buffered.length === 0) {
+            return NaN;
+        }
+        const currentTime = el.currentTime;
+        if (Number.isFinite(currentTime)) {
+            for (let index = 0; index < el.buffered.length; index += 1) {
+                if (currentTime >= el.buffered.start(index) && currentTime <= el.buffered.end(index)) {
+                    return el.buffered.end(index);
+                }
+            }
+        }
+        return mediaRangeEnd(el.buffered);
+    };
+    // Native HLS (no hls.js): derive `programTimeOriginMs` so that
+    //   programTime(ms) = programTimeOriginMs + video.currentTime * 1000
+    //
+    // We re-derive the origin on EVERY manifest poll. For a live sliding window the
+    // PDT->media-time relationship drifts as old segments fall off the front, so a
+    // once-latched origin (or one guarded by a tiny anchor delta) goes stale. By
+    // re-anchoring each poll from the freshest segment that actually carries a PDT
+    // we always track the current window.
+    const updateNativeTimeMapperFromManifest = (manifest) => {
+        const el = getVideo();
+        if (!el) {
+            return;
+        }
+        const timeAnchorSec = nativeBufferedTimeAnchorSec(el);
+        if (!Number.isFinite(timeAnchorSec)) {
+            return;
+        }
+        const segments = parseManifestSegments(manifest);
+        // Use the latest segment that has a resolved program time. parseManifestSegments
+        // already forward-fills PDT across segments, so a refresh whose first segment
+        // is the only one carrying #EXT-X-PROGRAM-DATE-TIME still yields finite times.
+        const lastSegment = findLast(segments, (segment) => Number.isFinite(segment.programDateTimeMs) && segment.durationSec > 0);
+        if (!lastSegment) {
+            // No segment had a usable PDT this refresh — leave the previous origin in
+            // place rather than latching a NaN/stale value.
+            return;
+        }
+        const segmentEndMs = lastSegment.programDateTimeMs + lastSegment.durationSec * 1000;
+        programTimeOriginMs = segmentEndMs - timeAnchorSec * 1000;
+    };
+    const pollManifest = () => {
+        if (destroyed || !manifestUrl) {
+            return;
+        }
+        fetch(manifestUrl, { cache: 'no-store' })
+            .then((response) => response.text())
+            .then((manifest) => {
+            if (destroyed) {
+                return;
+            }
+            mergeDateRanges(parseManifestDateRanges(manifest));
+            updateNativeTimeMapperFromManifest(manifest);
+        })
+            .catch((error) => {
+            log.warn(error, 'ssai manifest poll failed');
+        });
+    };
+    // -- live-edge supplement (hls path) --
+    /**
+     * The playlist the player is actually playing — that is where the DATERANGEs
+     * live (a multivariant "master" URL carries none). Mirrors the demo/dashboard
+     * level-picking order; falls back to the host-supplied `manifestUrl` for
+     * single-playlist streams whose one URL IS the media playlist.
+     */
+    const currentLevelUrl = () => {
+        const levels = player?.levels;
+        if (Array.isArray(levels) && levels.length > 0) {
+            const currentLevel = Number(player?.currentLevel);
+            const loadLevel = Number(player?.loadLevel);
+            const index = currentLevel >= 0 ? currentLevel : loadLevel >= 0 ? loadLevel : 0;
+            const level = levels[index] ?? levels[0];
+            const raw = level?.uri ?? level?.url;
+            const resolved = Array.isArray(raw) ? raw[0] : raw;
+            if (typeof resolved === 'string' && resolved.length > 0) {
+                return resolved;
+            }
+        }
+        return manifestUrl;
+    };
+    // Guards overlapping fetches when the manifest host answers slower than the
+    // poll cadence — the next tick simply skips.
+    let liveEdgePollInflight = false;
+    const pollLiveEdge = () => {
+        if (destroyed || liveEdgePollInflight) {
+            return;
+        }
+        const url = currentLevelUrl();
+        if (!url) {
+            return;
+        }
+        liveEdgePollInflight = true;
+        // CORS is already granted here: hls.js fetches this same playlist via XHR.
+        fetch(url, { cache: 'no-store' })
+            .then((response) => response.text())
+            .then((manifest) => {
+            liveEdgePollInflight = false;
+            if (!destroyed) {
+                mergeDateRanges(parseManifestDateRanges(manifest));
+            }
+        })
+            .catch((error) => {
+            liveEdgePollInflight = false;
+            log.debug(error, 'ssai live-edge poll failed');
+        });
+    };
+    // -- active-ad resolution --
+    const clearBreakEndTimer = () => {
+        if (breakEndTimer !== null) {
+            clearTimeout(breakEndTimer);
+            breakEndTimer = null;
+        }
+    };
+    const emitProgress = (range, event) => {
+        if (!onProgress || progressFired[event]) {
+            return;
+        }
+        progressFired[event] = true;
+        recordDebugEvent(`progress:${event}`, range.creativeId);
+        try {
+            onProgress(range, event);
+        }
+        catch (error) {
+            log.warn(error, 'ssai onProgress handler threw');
+        }
+    };
+    /**
+     * Close out the ad we were tracking. `complete` is only honest once playback
+     * actually reached the end of the ad window — leaving it early (a seek out of
+     * the break, a stream switch, `destroy`) must NOT report a completed view.
+     */
+    const finishProgress = (programTimeMs) => {
+        const range = progressRange;
+        if (!range) {
+            return;
+        }
+        if (Number.isFinite(programTimeMs) && programTimeMs >= range.endMs) {
+            emitProgress(range, 'complete');
+        }
+        progressRange = null;
+        progressFired = {};
+    };
+    /** Fire whichever milestones the playhead has passed inside the active ad. */
+    const updateProgress = (range, programTimeMs) => {
+        if (!onProgress) {
+            return;
+        }
+        if (!progressRange || progressRange.id !== range.id) {
+            // A new ad (first of the break, or the next one in a pod): the previous
+            // one is over, and by definition the playhead has left it.
+            finishProgress(programTimeMs);
+            progressRange = range;
+            progressFired = {};
+        }
+        const spanMs = range.endMs - range.startMs;
+        if (spanMs <= 0) {
+            return;
+        }
+        for (const [event, threshold] of PROGRESS_THRESHOLDS) {
+            // The stream's own marker for this event is the ad server's declared time
+            // and stays honest while the window's end is still provisional (before the
+            // `complete` marker has been published); fractions of the window are the
+            // fallback for the creative-DATERANGE dialect.
+            const eventAtMs = range.progressAtMs?.[event] ?? range.startMs + spanMs * threshold;
+            if (programTimeMs >= eventAtMs) {
+                emitProgress(range, event);
+            }
+        }
+    };
+    const emitBreakEnd = () => {
+        if (!breakActive) {
+            return;
+        }
+        breakActive = false;
+        breakSuppressed = false;
+        activeRangeId = '';
+        activeCreativeId = '';
+        endingNotifiedRangeId = '';
+        recordDebugEvent('break-end');
+        try {
+            onBreakEnd();
+        }
+        catch (error) {
+            log.warn(error, 'ssai onBreakEnd handler threw');
+        }
+    };
+    const updateActiveAd = () => {
+        if (destroyed) {
+            return;
+        }
+        const programTimeMs = currentProgramTimeMs();
+        const range = findActiveRange(programTimeMs);
+        if (!range) {
+            // Playback has left the ad — settle its lifecycle beacons before anything
+            // else. Never deferred: `complete` reports what playback did, and delaying
+            // it by a second would only risk losing it if the page goes away in
+            // between.
+            finishProgress(programTimeMs);
+            if (!breakActive) {
+                return;
+            }
+            // The end edge is decided from the schedule, on this very tick: with a
+            // trustworthy clock and no further window opening within END_DEBOUNCE_MS,
+            // the break is really over — a bar that outlives its ad by a debounce
+            // reads as lag, exactly like a bar that trails its start did.
+            if (Number.isFinite(programTimeMs) && !nextRangeStartsWithin(programTimeMs, END_DEBOUNCE_MS)) {
+                clearBreakEndTimer();
+                emitBreakEnd();
+                return;
+            }
+            // Ambiguous: the next ad of a pod starts inside the window (hold the bar
+            // through the gap — entering that ad cancels the timer and becomes a
+            // creative change), or the clock is momentarily unreadable. The timer is
+            // the fallback if the playhead never actually arrives there.
+            if (breakEndTimer === null) {
+                breakEndTimer = setTimeout(() => {
+                    breakEndTimer = null;
+                    emitBreakEnd();
+                }, END_DEBOUNCE_MS);
+            }
+            return;
+        }
+        // We have an active range — cancel any pending end.
+        clearBreakEndTimer();
+        // Beacons are deliberately updated BEFORE the visibility logic below: the ad
+        // is stitched into the stream, so it plays — and must be reported —
+        // regardless of whether the overlay is showing or was dismissed.
+        updateProgress(range, programTimeMs);
+        if (!breakActive) {
+            // Fire on the same tick the playhead enters the window. There is no start
+            // debounce: every millisecond here is the bar lagging an ad that is
+            // already on screen, and the flash the old debounce guarded against is
+            // prevented in the data instead (MIN_AD_WINDOW_MS in findActiveRange).
+            breakActive = true;
+            activeRangeId = range.id;
+            activeCreativeId = range.creativeId;
+            // `at+X.Xs` = how far into the ad window the bar actually fired — the
+            // number to compare with what the screen shows when sync is in doubt.
+            recordDebugEvent('break-start', `${range.creativeId} at+${((programTimeMs - range.startMs) / 1000).toFixed(1)}s`, programTimeMs);
+            try {
+                onBreakStart(range);
+            }
+            catch (error) {
+                log.warn(error, 'ssai onBreakStart handler threw');
+            }
+            return;
+        }
+        // Break already active — detect creative change within a multi-ad pod.
+        if (activeRangeId !== range.id || activeCreativeId !== range.creativeId) {
+            activeRangeId = range.id;
+            activeCreativeId = range.creativeId;
+            recordDebugEvent(breakSuppressed ? 'creative-change-suppressed' : 'creative-change', range.creativeId, programTimeMs);
+            // User dismissed this break: track the new creative internally but don't
+            // re-show the bar. Suppression lifts when the break ends (emitBreakEnd).
+            if (breakSuppressed) {
+                return;
+            }
+            try {
+                onCreativeChange(range);
+            }
+            catch (error) {
+                log.warn(error, 'ssai onCreativeChange handler threw');
+            }
+        }
+        // Announce the approaching end once per airing, so the UI can play its
+        // closing animation BEFORE the boundary instead of after it.
+        if (onAdEnding && endingNotifiedRangeId !== range.id && range.endMs - programTimeMs <= AD_ENDING_LEAD_MS) {
+            endingNotifiedRangeId = range.id;
+            recordDebugEvent('ad-ending', range.creativeId, programTimeMs);
+            try {
+                onAdEnding(range);
+            }
+            catch (error) {
+                log.warn(error, 'ssai onAdEnding handler threw');
+            }
+        }
+    };
+    // -- wiring --
+    const handleLevelUpdated = (...args) => {
+        const data = (args[1] ?? args[0]);
+        ingestHlsDateRanges(data?.details);
+        updateTimeMapperFromDetails(data?.details);
+    };
+    const handleFragChanged = (...args) => {
+        const data = (args[1] ?? args[0]);
+        updateTimeMapperFromFragment(data?.frag);
+    };
+    let manifestInterval = null;
+    let liveEdgeInterval = null;
+    if (player) {
+        try {
+            player.on(HLS_EVENT_LEVEL_UPDATED, handleLevelUpdated);
+            player.on(HLS_EVENT_FRAG_CHANGED, handleFragChanged);
+        }
+        catch (error) {
+            log.warn(error, 'ssai detector: failed to attach hls.js listeners');
+        }
+        liveEdgeInterval = setInterval(pollLiveEdge, LIVE_EDGE_POLL_MS);
+    }
+    else if (videoRef && manifestUrl) {
+        pollManifest();
+        manifestInterval = setInterval(pollManifest, MANIFEST_POLL_MS);
+    }
+    else if (videoRef && !manifestUrl) {
+        log.info('ssai detector: videoRef provided without manifestUrl, native polling disabled');
+    }
+    const activeInterval = setInterval(updateActiveAd, ACTIVE_POLL_MS);
+    // hls.js diagnostics are getters over live controllers — read them guarded so
+    // an exotic host object can never take the snapshot down.
+    const readOptionalNumber = (read) => {
+        try {
+            const value = read();
+            return typeof value === 'number' && Number.isFinite(value) ? value : NaN;
+        }
+        catch {
+            return NaN;
+        }
+    };
+    const getDebugSnapshot = () => {
+        const el = getVideo();
+        const playingDateMs = player?.playingDate ? player.playingDate.getTime() : NaN;
+        const pdtOriginProgramMs = Number.isFinite(programTimeOriginMs) && el && Number.isFinite(el.currentTime)
+            ? programTimeOriginMs + el.currentTime * 1000
+            : NaN;
+        // Mirrors currentProgramTimeMs()'s preference order, spelled out per source.
+        const clockSource = Number.isFinite(playingDateMs)
+            ? 'playingDate'
+            : Number.isFinite(pdtOriginProgramMs)
+                ? 'pdt-origin'
+                : el
+                    ? 'waiting-for-pdt'
+                    : 'wall-clock';
+        const ranges = Array.from(rangesById.values())
+            .map((range) => ({ ...range, source: 'daterange' }))
+            .concat(getRangesCache().folded.map((range) => ({ ...range, source: 'markers' })))
+            .sort((left, right) => left.startMs - right.startMs);
+        return {
+            wallMs: Date.now(),
+            programMs: currentProgramTimeMs(),
+            clockSource,
+            attachMode,
+            playingDateMs,
+            pdtOriginProgramMs,
+            programTimeOriginMs,
+            hls: player
+                ? {
+                    latencySec: readOptionalNumber(() => player.latency),
+                    driftSec: readOptionalNumber(() => player.drift),
+                    liveSyncPositionSec: readOptionalNumber(() => player.liveSyncPosition),
+                    targetLatencySec: readOptionalNumber(() => player.targetLatency),
+                }
+                : null,
+            video: el
+                ? {
+                    currentTimeSec: el.currentTime,
+                    bufferedEndSec: mediaRangeEnd(el.buffered),
+                    seekableEndSec: mediaRangeEnd(el.seekable),
+                    paused: el.paused,
+                    playbackRate: el.playbackRate,
+                    readyState: el.readyState,
+                }
+                : null,
+            ranges,
+            markerCount: markersById.size,
+            adBreakCount: adBreaksById.size,
+            breakActive,
+            breakSuppressed,
+            activeRangeId: breakActive ? activeRangeId : null,
+            activeCreativeId: breakActive ? activeCreativeId : null,
+            progress: progressRange
+                ? {
+                    rangeId: progressRange.id,
+                    creativeId: progressRange.creativeId,
+                    fired: Object.keys(progressFired),
+                }
+                : null,
+            events: debugEvents.slice(),
+        };
+    };
+    return {
+        getDebugSnapshot,
+        dismissActiveBreak: () => {
+            if (breakActive) {
+                breakSuppressed = true;
+                recordDebugEvent('dismissed', activeCreativeId);
+            }
+        },
+        destroy: () => {
+            if (destroyed) {
+                return;
+            }
+            destroyed = true;
+            clearInterval(activeInterval);
+            if (manifestInterval !== null) {
+                clearInterval(manifestInterval);
+            }
+            if (liveEdgeInterval !== null) {
+                clearInterval(liveEdgeInterval);
+            }
+            clearBreakEndTimer();
+            if (player) {
+                try {
+                    player.off(HLS_EVENT_LEVEL_UPDATED, handleLevelUpdated);
+                    player.off(HLS_EVENT_FRAG_CHANGED, handleFragChanged);
+                }
+                catch (error) {
+                    log.warn(error, 'ssai detector: failed to detach hls.js listeners (host may be destroyed)');
+                }
+            }
+            rangesById.clear();
+            markersById.clear();
+            adBreaksById.clear();
+        },
+    };
+};