@streamlayer/feature-advertisement 0.4.2 → 1.0.0

package/lib/units/gam.d.ts

@@ -0,0 +1,16 @@
+export type PalNonceManager = {
+    getNonce: () => string;
+    sendAdClick: () => void;
+    sendPlaybackStart: () => void;
+    sendPlaybackEnd: () => void;
+};
+export type GamNonceResult = {
+    url: URL;
+    manager?: PalNonceManager;
+};
+export declare const gam: (url: string, adContainer?: HTMLDivElement) => (() => Promise<{
+    url: URL;
+}>) | (() => Promise<{
+    url: URL;
+    manager: PalNonceManager;
+} | undefined>);

package/lib/units/gam.js

@@ -0,0 +1,99 @@
+/**
+ * Google PAL nonce manager + ad-tag resolution for programmatic (GAM) VAST requests.
+ *
+ * Lives here because the VAST fetcher (`units/external-ad.ts`) is its only consumer: this is the
+ * request side of an ad tag, not the promotion side. The *composition* of a tag URL from the proto
+ * (`processGamAdvertisement` / `selectGamOptions`) stays in `feature-gamification`, next to the
+ * `$store` bridge that is its only consumer — so the two feature packages share no code and
+ * neither depends on the other.
+ */
+import { safeLocalStorage, safeSessionStorage } from '@streamlayer/sdk-web-storage';
+import { validate as uuidValidate, v5 as uuid5, v4 as uuid4 } from 'uuid';
+const urlIsNotGam = (url) => {
+    return url.origin !== 'https://pubads.g.doubleclick.net';
+};
+export const gam = (url, adContainer) => {
+    const parsedUrl = (() => {
+        try {
+            const parsedUrl = new URL(url);
+            return parsedUrl;
+        }
+        catch (_err) {
+            return undefined;
+        }
+    })();
+    // Non-GAM VAST/VMAP URLs carry no GAM ad-request params and need no PAL nonce, so
+    // resolve them directly. PAL is only required for pubads.g.doubleclick.net requests —
+    // raw-VAST consumers (e.g. injected sidebar / l-bar) must not depend on the Google PAL
+    // SDK being loaded, so this must run before touching `goog`.
+    if (parsedUrl && urlIsNotGam(parsedUrl)) {
+        // eslint-disable-next-line require-await
+        return async () => {
+            return { url: parsedUrl };
+        };
+    }
+    // @ts-expect-error goog is injected by the externally-loaded Google PAL SDK
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pal = (typeof goog === 'undefined' ? undefined : goog.pal);
+    if (!pal || !parsedUrl) {
+        // eslint-disable-next-line require-await
+        return async () => {
+            return undefined;
+        };
+    }
+    const consentSettings = new pal.ConsentSettings();
+    consentSettings.allowStorage = false;
+    const nonceLoader = new pal.NonceLoader(consentSettings);
+    const generateUrl = async () => {
+        try {
+            const parsedUrl = new URL(url);
+            const request = new pal.NonceRequest();
+            let deviceId = safeLocalStorage().getItem('sl-device-id') || uuid4();
+            let sessionId = safeSessionStorage().getItem('sl-ad-session-id');
+            if (!sessionId) {
+                sessionId = uuid4();
+                safeSessionStorage().setItem('sl-ad-session-id', sessionId);
+            }
+            if (!uuidValidate(deviceId)) {
+                deviceId = uuid5(`https://${deviceId}`, uuid5.URL);
+            }
+            if (!parsedUrl.searchParams.get('url')) {
+                parsedUrl.searchParams.set('url', 'https://streamlayer.io');
+            }
+            if (!parsedUrl.searchParams.get('description_url')) {
+                parsedUrl.searchParams.set('description_url', 'https://streamlayer.io');
+            }
+            request.adWillAutoPlay = parsedUrl.searchParams.get('vpa') === 'auto';
+            request.adWillPlayMuted = parsedUrl.searchParams.get('vpmute') === '1';
+            request.continuousPlayback = true;
+            request.descriptionUrl = parsedUrl.searchParams.get('description_url');
+            request.iconsSupported = true;
+            request.sessionId = deviceId;
+            // Player support for VPAID 2.0, OMID 1.0, and SIMID 1.1
+            request.supportedApiFrameworks = '2,7,9';
+            request.videoHeight = adContainer?.clientHeight ?? 0;
+            request.videoWidth = adContainer?.clientWidth ?? 0;
+            const nonceManager = await nonceLoader.loadNonceManager(request);
+            if (parsedUrl.searchParams.get('is_lat') === '[placeholder]') {
+                parsedUrl.searchParams.set('is_lat', '1');
+            }
+            if (parsedUrl.searchParams.get('rdid') === '[placeholder]') {
+                parsedUrl.searchParams.set('rdid', deviceId);
+            }
+            if (parsedUrl.searchParams.get('correlator') === '[placeholder]') {
+                parsedUrl.searchParams.set('correlator', sessionId);
+            }
+            parsedUrl.searchParams.set('wta', '1');
+            parsedUrl.searchParams.set('givn', nonceManager.getNonce());
+            return {
+                url: parsedUrl,
+                manager: nonceManager,
+            };
+        }
+        catch (adError) {
+            console.log('AdsManager could not be started', adError);
+            return undefined;
+        }
+    };
+    return generateUrl;
+};

package/lib/units/parse-vast-extensions.d.ts

@@ -0,0 +1,17 @@
+import { AdType } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+export interface VastCreative {
+    adName: string;
+    adType: AdType;
+    landscapeBackground?: string;
+    portraitBackground?: string;
+    sponsorLogo?: string;
+    ctaLabel?: string;
+}
+interface VastNode {
+    name: string;
+    value: string | null;
+    attributes: Record<string, string>;
+    children: VastNode[];
+}
+export declare function parseVastExtension(root: VastNode): VastCreative | undefined;
+export {};

package/lib/units/parse-vast-extensions.js

@@ -0,0 +1,47 @@
+import { AdType } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+const MAP_EXTENSION_NAME_AD_TYPE = {
+    DoubleBox: AdType.SIDE_BY_SIDE,
+};
+export function parseVastExtension(root) {
+    if (!root) {
+        return undefined;
+    }
+    const child = (node, name) => node.children.find((c) => c.name === name);
+    const childrenByName = (node, name) => node.children.filter((c) => c.name === name);
+    const urlOf = (node) => child(node, 'Url')?.value ?? '';
+    const num = (v) => (v == null ? NaN : Number(v));
+    const adName = child(root, 'AdName')?.value ?? '';
+    const backgroundsNode = child(root, 'Backgrounds');
+    const backgrounds = backgroundsNode
+        ? childrenByName(backgroundsNode, 'Background').map((bg) => ({
+            orientation: bg.attributes.orientation,
+            width: num(bg.attributes.width),
+            height: num(bg.attributes.height),
+            type: bg.attributes.type,
+            url: urlOf(bg),
+        }))
+        : [];
+    const logosNode = child(root, 'Logos');
+    const logos = logosNode
+        ? childrenByName(logosNode, 'Logo').map((logo) => ({
+            role: logo.attributes.role,
+            width: num(logo.attributes.width),
+            height: num(logo.attributes.height),
+            type: logo.attributes.type,
+            url: urlOf(logo),
+        }))
+        : [];
+    const ctaNode = child(root, 'CTA');
+    const cta = {
+        label: ctaNode ? (child(ctaNode, 'Label')?.value ?? '') : '',
+        type: ctaNode ? (child(ctaNode, 'Type')?.value ?? '') : '',
+    };
+    return {
+        adName,
+        adType: MAP_EXTENSION_NAME_AD_TYPE[root.name] || AdType.SIDE_BY_SIDE,
+        landscapeBackground: backgrounds.find((b) => b.orientation === 'landscape')?.url,
+        portraitBackground: backgrounds.find((b) => b.orientation === 'portrait')?.url,
+        sponsorLogo: logos.find((l) => l.role === 'header')?.url,
+        ctaLabel: cta.label,
+    };
+}

package/lib/units/pause-ad.d.ts

@@ -5,7 +5,10 @@ export type PauseAdLayout = 'left' | 'center' | 'image';
 export type PauseAdCard = {
     id: string;
     parentId: string;
-    backgroundImageSrc: string;
+    /** Optional: a video-only card (programmatic VAST, SC-322) has no image. */
+    backgroundImageSrc?: string;
+    /** Linear MP4 from VAST → renders full-bleed `<video>` instead of the image (SC-322). */
+    backgroundVideoSrc?: string;
     layout: PauseAdLayout;
     isInteractive: boolean;
     logoSrc?: string;

package/lib/units/ssai-ad-break.d.ts

@@ -0,0 +1,21 @@
+import { createSingleStore } from '@streamlayer/sdk-web-interfaces';
+import type { SsaiCreative } from './ssai-creative';
+/**
+ * 'ending' = the ad's window closes within the detector's lead (~0.5s): the
+ * overlay's cue to play its closing animation so it completes AT the boundary
+ * rather than after it. Beacons are unaffected — playback still owns those.
+ */
+export type SsaiAdBreakStatus = 'detecting' | 'ready' | 'ending' | 'ended';
+export type SsaiAdBreakState = {
+    creativeId: string;
+    creative?: SsaiCreative;
+    status: SsaiAdBreakStatus;
+    startMs: number;
+    durationSec: number;
+};
+export type SsaiAdBreakStore = ReturnType<typeof createSingleStore<SsaiAdBreakState | null>>;
+/**
+ * Imperative atom driven directly by the detector (no nanoquery — the trigger
+ * is push-based, not request/response).
+ */
+export declare const createSsaiAdBreakStore: () => SsaiAdBreakStore;

package/lib/units/ssai-ad-break.js

@@ -0,0 +1,6 @@
+import { createSingleStore } from '@streamlayer/sdk-web-interfaces';
+/**
+ * Imperative atom driven directly by the detector (no nanoquery — the trigger
+ * is push-based, not request/response).
+ */
+export const createSsaiAdBreakStore = () => createSingleStore(null);

package/lib/units/ssai-creative.d.ts

@@ -0,0 +1,89 @@
+import { DEFAULT_CREATIVE_API_BASE, type SsaiCreativeProvider } from './ssai-providers';
+export { DEFAULT_CREATIVE_API_BASE };
+export type SsaiTrackingEvent = {
+    event: string;
+    url: string;
+};
+export type SsaiCompanion = {
+    staticResource: string;
+    width: number;
+    height: number;
+    clickThrough?: string;
+    /** Beacons fired when the companion is clicked. May be empty. */
+    clickTracking: string[];
+};
+/**
+ * Lifecycle events the SDK fires beacons for, in the order they occur.
+ * `impression` is separate: it is tied to the overlay actually being rendered,
+ * not to playback position — see `SsaiCreativeCache.fireImpression`.
+ */
+export type SsaiProgressEvent = 'start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete';
+export type SsaiCreative = {
+    creativeId: string;
+    advertiser: string;
+    title: string;
+    iconUrl?: string;
+    clickThroughUrl?: string;
+    trackingEvents: SsaiTrackingEvent[];
+    companion?: SsaiCompanion;
+};
+/**
+ * Per-instance cache + impression-firing wrapper around a SsaiCreativeProvider.
+ * Caches resolved creatives by creativeId so repeated active-ad polls and pod
+ * repeats don't refetch. In-flight fetches are cancellable via AbortController.
+ */
+export declare class SsaiCreativeCache {
+    private provider;
+    private cache;
+    private inflight;
+    constructor(provider: SsaiCreativeProvider);
+    /**
+     * The already-resolved creative, or undefined — synchronous on purpose: a
+     * prefetched creative lets the ad break flip straight to 'ready' with no
+     * async gap (which the UI would render as a blink between two ads of a pod).
+     */
+    peek: (creativeId: string) => SsaiCreative | undefined;
+    resolve: (creativeId: string) => Promise<SsaiCreative>;
+    /**
+     * Cancel an in-flight fetch (e.g. the break ended before it resolved).
+     */
+    cancel: (creativeId: string) => void;
+    /**
+     * Fire the impression for a creative. Delegates to the provider's
+     * `fireImpression` when present, otherwise the shared default (first
+     * trackingEvent named 'impression' via sendBeacon/fetch). Called once per
+     * visible appearance of the bar (the UI dedupes the ~250ms active-poll so a
+     * single continuous appearance fires exactly one impression). Each genuine pod
+     * insertion of the same creative is a distinct impression and re-fires.
+     */
+    fireImpression: (creative: SsaiCreative) => void;
+    /**
+     * Fire the impression for an already-resolved creativeId. No-op if the
+     * creative isn't cached yet (the bar only renders once resolved, so by the
+     * time the UI calls this the creative is present).
+     */
+    fireImpressionById: (creativeId: string) => void;
+    /**
+     * Fire a lifecycle / click beacon. Delegates to the provider's `fireTracking`
+     * when it defines one, otherwise fires every matching `trackingEvents` URL.
+     */
+    fireTracking: (creative: SsaiCreative, event: string) => void;
+    /**
+     * Fire a beacon for a creativeId that may still be resolving.
+     *
+     * `start` in particular lands the instant the break opens, which is usually
+     * BEFORE the metadata request has come back — dropping it would silently lose
+     * the first beacon of every ad. Resolution is already in flight by then and
+     * `resolve` returns that same promise, so this attaches to it rather than
+     * issuing a second request. A creative that never resolves fires nothing,
+     * which is the correct outcome: there are no URLs to fire.
+     */
+    fireTrackingById: (creativeId: string, event: string) => void;
+    /**
+     * Fire the companion's `clickTracking` beacons. Separate from
+     * {@link fireTracking} because these live on the companion, not in
+     * `trackingEvents` — a provider's `fireTracking` override has no say over them.
+     */
+    fireCompanionClickById: (creativeId: string) => void;
+    destroy: () => void;
+}

package/lib/units/ssai-creative.js

@@ -0,0 +1,131 @@
+import { fireBeacon, fireDefaultImpression, fireTrackingEvents, DEFAULT_CREATIVE_API_BASE, } from './ssai-providers';
+export { DEFAULT_CREATIVE_API_BASE };
+/**
+ * Per-instance cache + impression-firing wrapper around a SsaiCreativeProvider.
+ * Caches resolved creatives by creativeId so repeated active-ad polls and pod
+ * repeats don't refetch. In-flight fetches are cancellable via AbortController.
+ */
+export class SsaiCreativeCache {
+    provider;
+    cache = new Map();
+    inflight = new Map();
+    constructor(provider) {
+        this.provider = provider;
+    }
+    /**
+     * The already-resolved creative, or undefined — synchronous on purpose: a
+     * prefetched creative lets the ad break flip straight to 'ready' with no
+     * async gap (which the UI would render as a blink between two ads of a pod).
+     */
+    peek = (creativeId) => this.cache.get(creativeId);
+    resolve = (creativeId) => {
+        const cached = this.cache.get(creativeId);
+        if (cached) {
+            return Promise.resolve(cached);
+        }
+        const existing = this.inflight.get(creativeId);
+        if (existing) {
+            return existing.promise;
+        }
+        const controller = new AbortController();
+        const promise = this.provider
+            .resolve(creativeId, controller.signal)
+            .then((creative) => {
+            this.cache.set(creativeId, creative);
+            this.inflight.delete(creativeId);
+            return creative;
+        })
+            .catch((error) => {
+            this.inflight.delete(creativeId);
+            throw error;
+        });
+        this.inflight.set(creativeId, { promise, controller });
+        return promise;
+    };
+    /**
+     * Cancel an in-flight fetch (e.g. the break ended before it resolved).
+     */
+    cancel = (creativeId) => {
+        const existing = this.inflight.get(creativeId);
+        if (existing) {
+            existing.controller.abort();
+            this.inflight.delete(creativeId);
+        }
+    };
+    /**
+     * Fire the impression for a creative. Delegates to the provider's
+     * `fireImpression` when present, otherwise the shared default (first
+     * trackingEvent named 'impression' via sendBeacon/fetch). Called once per
+     * visible appearance of the bar (the UI dedupes the ~250ms active-poll so a
+     * single continuous appearance fires exactly one impression). Each genuine pod
+     * insertion of the same creative is a distinct impression and re-fires.
+     */
+    fireImpression = (creative) => {
+        if (this.provider.fireImpression) {
+            this.provider.fireImpression(creative);
+            return;
+        }
+        fireDefaultImpression(creative);
+    };
+    /**
+     * Fire the impression for an already-resolved creativeId. No-op if the
+     * creative isn't cached yet (the bar only renders once resolved, so by the
+     * time the UI calls this the creative is present).
+     */
+    fireImpressionById = (creativeId) => {
+        const creative = this.cache.get(creativeId);
+        if (creative) {
+            this.fireImpression(creative);
+        }
+    };
+    /**
+     * Fire a lifecycle / click beacon. Delegates to the provider's `fireTracking`
+     * when it defines one, otherwise fires every matching `trackingEvents` URL.
+     */
+    fireTracking = (creative, event) => {
+        if (this.provider.fireTracking) {
+            this.provider.fireTracking(creative, event);
+            return;
+        }
+        fireTrackingEvents(creative, event);
+    };
+    /**
+     * Fire a beacon for a creativeId that may still be resolving.
+     *
+     * `start` in particular lands the instant the break opens, which is usually
+     * BEFORE the metadata request has come back — dropping it would silently lose
+     * the first beacon of every ad. Resolution is already in flight by then and
+     * `resolve` returns that same promise, so this attaches to it rather than
+     * issuing a second request. A creative that never resolves fires nothing,
+     * which is the correct outcome: there are no URLs to fire.
+     */
+    fireTrackingById = (creativeId, event) => {
+        const cached = this.cache.get(creativeId);
+        if (cached) {
+            this.fireTracking(cached, event);
+            return;
+        }
+        this.resolve(creativeId)
+            .then((creative) => this.fireTracking(creative, event))
+            .catch(() => undefined);
+    };
+    /**
+     * Fire the companion's `clickTracking` beacons. Separate from
+     * {@link fireTracking} because these live on the companion, not in
+     * `trackingEvents` — a provider's `fireTracking` override has no say over them.
+     */
+    fireCompanionClickById = (creativeId) => {
+        const companion = this.cache.get(creativeId)?.companion;
+        if (!companion) {
+            return;
+        }
+        for (const url of companion.clickTracking) {
+            fireBeacon(url);
+        }
+    };
+    destroy = () => {
+        this.inflight.forEach((entry) => entry.controller.abort());
+        this.inflight.clear();
+        this.cache.clear();
+    };
+}

package/lib/units/ssai-detector.d.ts

@@ -0,0 +1,180 @@
+import type { SsaiProgressEvent } from './ssai-creative';
+export type SsaiDateRange = {
+    id: string;
+    creativeId: string;
+    startMs: number;
+    durationSec: number;
+    endMs: number;
+    /**
+     * Exact program times of lifecycle events, when the stream's tracking markers
+     * state them (Synamedia dialect). `updateProgress` prefers these over fractions
+     * of the window — the markers are the ad server's own quartile schedule, and
+     * they stay honest even while the window's end is still provisional.
+     */
+    progressAtMs?: Partial<Record<SsaiProgressEvent, number>>;
+};
+/** hls.js `Level`, structurally: `uri` is a string, legacy `url` a string[]. */
+type HlsLikeLevel = {
+    uri?: string;
+    url?: string | string[];
+} & Record<string, unknown>;
+export type HlsLike = {
+    on: (event: string, handler: (...args: unknown[]) => void) => void;
+    off: (event: string, handler: (...args: unknown[]) => void) => void;
+    media?: HTMLVideoElement | null;
+    /**
+     * hls.js' level list and level selection, used only to resolve the active
+     * media playlist's URL for the supplemental live-edge poll (see
+     * `LIVE_EDGE_POLL_MS`). All optional — a minimal host player simply gets no
+     * supplement.
+     */
+    levels?: HlsLikeLevel[] | null;
+    currentLevel?: number;
+    loadLevel?: number;
+    /**
+     * hls.js' own PROGRAM-DATE-TIME of the frame on screen right now. When the host
+     * exposes it this is the best answer available — hls.js derives it from the
+     * playlist it is actually playing, so it needs no origin of ours and cannot
+     * drift as the live window slides.
+     */
+    playingDate?: Date | null;
+    /**
+     * hls.js live-latency diagnostics. Never used for detection — only surfaced by
+     * `getDebugSnapshot` so the debug window can cross-check the program clock
+     * against the player's own view of how far behind live it is. All optional:
+     * a minimal host player (or the e2e stub) simply reports them as unavailable.
+     */
+    latency?: number;
+    drift?: number;
+    liveSyncPosition?: number | null;
+    targetLatency?: number | null;
+};
+export type SsaiDetectorOptions = {
+    player?: HlsLike;
+    videoRef?: HTMLVideoElement;
+    manifestUrl?: string;
+    /**
+     * A creative id was seen in the manifest for the first time — typically
+     * seconds before its break starts, since the viewer's playhead trails the
+     * live edge. This is the prefetch hook: resolve the creative and warm its
+     * artwork here and the bar can show the instant the break begins.
+     */
+    onAdDiscovered?: (creativeId: string) => void;
+    onBreakStart: (range: SsaiDateRange) => void;
+    onCreativeChange: (range: SsaiDateRange) => void;
+    /**
+     * The active ad's window ends within `AD_ENDING_LEAD_MS`. Fired once per
+     * airing while a break is active — the UI's cue to start its closing
+     * animation early enough to complete at the boundary. Purely presentational:
+     * beacons and break bookkeeping are unaffected.
+     */
+    onAdEnding?: (range: SsaiDateRange) => void;
+    onBreakEnd: () => void;
+    /**
+     * Playback reached a lifecycle milestone of the given ad. Fires at most once
+     * per event per playthrough, in order, and is INDEPENDENT of whether the
+     * overlay is on screen — the ad is stitched into the stream, so it plays (and
+     * must be reported) whether or not the viewer dismissed the bar.
+     */
+    onProgress?: (range: SsaiDateRange, event: SsaiProgressEvent) => void;
+};
+/** One `X-AD-EVENT-TYPE` marker: an instant in program time, not a window. */
+export type SsaiTrackingMarker = {
+    id: string;
+    adId: string;
+    event: string;
+    timeMs: number;
+    /** Per-session beacon from `X-AD-URL`, kept for diagnostics. */
+    url?: string;
+};
+/** A `com.synamedia.dai.adbreak` range — the whole break, with no ad identity. */
+type SsaiAdBreakWindow = {
+    id: string;
+    startMs: number;
+    endMs: number;
+};
+/**
+ * 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 declare const foldTrackingMarkers: (markers: SsaiTrackingMarker[], breaks: SsaiAdBreakWindow[]) => SsaiDateRange[];
+/** Which source `currentProgramTimeMs()` is answering from right now. */
+export type SsaiClockSource = 'playingDate' | 'pdt-origin' | 'waiting-for-pdt' | 'wall-clock';
+export type SsaiDebugEvent = {
+    wallMs: number;
+    /** Program time at the moment of the event (NaN while the clock is unmapped). */
+    programMs: number;
+    type: string;
+    detail?: string;
+};
+export type SsaiDebugRange = SsaiDateRange & {
+    /** 'daterange' = explicit creative DATERANGE; 'markers' = window folded from tracking markers. */
+    source: 'daterange' | 'markers';
+};
+export type SsaiDebugSnapshot = {
+    wallMs: number;
+    /** Program time of the on-screen frame per the detector's clock (NaN while unmapped). */
+    programMs: number;
+    clockSource: SsaiClockSource;
+    /** How the detector is attached: hls.js events, native manifest polling, or nothing. */
+    attachMode: 'hls' | 'manifest-poll' | 'none';
+    /** hls.js `playingDate`, NaN when the host doesn't expose it. */
+    playingDateMs: number;
+    /** The alternate mapping `programTimeOriginMs + video.currentTime` — cross-check against playingDate. */
+    pdtOriginProgramMs: number;
+    programTimeOriginMs: number;
+    hls: {
+        latencySec: number;
+        driftSec: number;
+        liveSyncPositionSec: number;
+        targetLatencySec: number;
+    } | null;
+    video: {
+        currentTimeSec: number;
+        bufferedEndSec: number;
+        seekableEndSec: number;
+        paused: boolean;
+        playbackRate: number;
+        readyState: number;
+    } | null;
+    /** Every ad window the detector knows, sorted by start. */
+    ranges: SsaiDebugRange[];
+    markerCount: number;
+    adBreakCount: number;
+    breakActive: boolean;
+    breakSuppressed: boolean;
+    activeRangeId: string | null;
+    activeCreativeId: string | null;
+    progress: {
+        rangeId: string;
+        creativeId: string;
+        fired: SsaiProgressEvent[];
+    } | null;
+    /** Ring buffer (newest last, capped) of detector edges: discovery, drops, start/end, beacons. */
+    events: SsaiDebugEvent[];
+};
+export type SsaiDetector = {
+    destroy: () => void;
+    /**
+     * Mark the currently active break as user-dismissed: the detector keeps
+     * tracking it (so it knows when it ends) but stops re-showing the bar on
+     * creative changes until the break ends. A subsequent break shows again.
+     */
+    dismissActiveBreak: () => void;
+    /**
+     * Read-only timing introspection for the debug window. Safe to call at any
+     * frequency; never affects detection.
+     */
+    getDebugSnapshot: () => SsaiDebugSnapshot;
+};
+export declare const createSsaiDetector: (options: SsaiDetectorOptions) => SsaiDetector;
+export {};