@trillboards/ads-sdk 2.0.0

package/dist/index.mjs

@@ -0,0 +1,1739 @@
+// src/core/config.ts
+var SDK_VERSION = "2.0.0";
+var DEFAULT_CONFIG = {
+  API_BASE: "https://api.trillboards.com/v1/partner",
+  CDN_BASE: "https://cdn.trillboards.com",
+  CACHE_NAME: "trillboards-lite-ads",
+  CACHE_SIZE: 10,
+  REFRESH_INTERVAL: 2 * 60 * 1e3,
+  // 2 minutes
+  HEARTBEAT_INTERVAL: 60 * 1e3,
+  // 1 minute
+  DEFAULT_IMAGE_DURATION: 8e3,
+  // 8 seconds
+  DEFAULT_AD_INTERVAL: 6e4,
+  // 1 minute
+  PROGRAMMATIC_TIMEOUT_MS: 12e3,
+  // 12 seconds
+  PROGRAMMATIC_MIN_INTERVAL_MS: 5e3,
+  // 5 seconds
+  PROGRAMMATIC_RETRY_MS: 5e3,
+  // 5 seconds
+  PROGRAMMATIC_BACKOFF_MAX_MS: 5 * 60 * 1e3,
+  // 5 minutes
+  VERSION: SDK_VERSION
+};
+function resolveConfig(userConfig) {
+  const deviceId = userConfig.deviceId?.trim();
+  if (!deviceId) {
+    throw new Error("TrillboardsConfig: deviceId must be a non-empty string");
+  }
+  return {
+    deviceId,
+    apiBase: userConfig.apiBase ?? DEFAULT_CONFIG.API_BASE,
+    cdnBase: userConfig.cdnBase ?? DEFAULT_CONFIG.CDN_BASE,
+    waterfall: userConfig.waterfall ?? "programmatic_only",
+    autoStart: userConfig.autoStart ?? true,
+    refreshInterval: Math.max(userConfig.refreshInterval ?? DEFAULT_CONFIG.REFRESH_INTERVAL, 1e4),
+    heartbeatInterval: Math.max(userConfig.heartbeatInterval ?? DEFAULT_CONFIG.HEARTBEAT_INTERVAL, 5e3),
+    defaultImageDuration: Math.max(userConfig.defaultImageDuration ?? DEFAULT_CONFIG.DEFAULT_IMAGE_DURATION, 1e3),
+    defaultAdInterval: Math.max(userConfig.defaultAdInterval ?? DEFAULT_CONFIG.DEFAULT_AD_INTERVAL, 1e3),
+    programmaticTimeout: Math.max(userConfig.programmaticTimeout ?? DEFAULT_CONFIG.PROGRAMMATIC_TIMEOUT_MS, 1e3),
+    programmaticMinInterval: Math.max(userConfig.programmaticMinInterval ?? DEFAULT_CONFIG.PROGRAMMATIC_MIN_INTERVAL_MS, 1e3),
+    programmaticRetry: Math.max(userConfig.programmaticRetry ?? DEFAULT_CONFIG.PROGRAMMATIC_RETRY_MS, 1e3),
+    programmaticBackoffMax: Math.max(userConfig.programmaticBackoffMax ?? DEFAULT_CONFIG.PROGRAMMATIC_BACKOFF_MAX_MS, 5e3),
+    cacheSize: Math.max(userConfig.cacheSize ?? DEFAULT_CONFIG.CACHE_SIZE, 1)
+  };
+}
+
+// src/core/state.ts
+var DEFAULT_PUBLIC_STATE = {
+  initialized: false,
+  isPlaying: false,
+  isPaused: false,
+  isOffline: false,
+  currentAd: null,
+  adCount: 0,
+  programmaticPlaying: false,
+  prefetchedReady: false,
+  waterfallMode: "programmatic_only",
+  screenId: null,
+  deviceId: null
+};
+function createInitialState() {
+  return {
+    deviceId: null,
+    partnerId: null,
+    screenId: null,
+    ads: [],
+    currentAdIndex: 0,
+    isPlaying: false,
+    isPaused: false,
+    isOffline: false,
+    settings: {},
+    programmatic: null,
+    programmaticPlaying: false,
+    prefetchedReady: false,
+    waterfallMode: "programmatic_only",
+    autoStart: true,
+    container: null,
+    adTimer: null,
+    refreshTimer: null,
+    heartbeatTimer: null,
+    programmaticRetryTimer: null,
+    programmaticRetryActive: false,
+    programmaticRetryCount: 0,
+    programmaticLastError: null,
+    initialized: false,
+    screenOrientation: null,
+    screenDimensions: null,
+    etag: null
+  };
+}
+function getPublicState(internal) {
+  return {
+    initialized: internal.initialized,
+    isPlaying: internal.isPlaying,
+    isPaused: internal.isPaused,
+    isOffline: internal.isOffline,
+    currentAd: internal.ads[internal.currentAdIndex] ?? null,
+    adCount: internal.ads.length,
+    programmaticPlaying: internal.programmaticPlaying,
+    prefetchedReady: internal.prefetchedReady ?? false,
+    waterfallMode: internal.waterfallMode,
+    screenId: internal.screenId,
+    deviceId: internal.deviceId
+  };
+}
+
+// src/core/events.ts
+var EventEmitter = class {
+  constructor() {
+    this.handlers = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a handler for the given event.
+   * The same handler reference can only be registered once per
+   * event (Set semantics).
+   */
+  on(event, handler) {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this.handlers.get(event).add(handler);
+  }
+  /**
+   * Remove a previously registered handler.
+   * No-op if the handler was never registered.
+   */
+  off(event, handler) {
+    this.handlers.get(event)?.delete(handler);
+  }
+  /**
+   * Emit an event, invoking every registered handler with the
+   * supplied data payload. Handlers are called synchronously in
+   * registration order. Exceptions inside handlers are caught
+   * and logged to the console so they never propagate.
+   */
+  emit(event, data) {
+    const handlers = this.handlers.get(event);
+    if (!handlers) return;
+    for (const handler of [...handlers]) {
+      try {
+        handler(data);
+      } catch (err) {
+        console.error(
+          `[TrillboardsAds] Event handler error for "${String(event)}":`,
+          err
+        );
+      }
+    }
+  }
+  /**
+   * Register a one-shot handler that automatically removes itself
+   * after the first invocation.
+   */
+  once(event, handler) {
+    const wrapper = (data) => {
+      this.off(event, wrapper);
+      handler(data);
+    };
+    this.on(event, wrapper);
+  }
+  /**
+   * Remove all handlers for all events.
+   * Typically called during SDK teardown / destroy.
+   */
+  removeAllListeners() {
+    this.handlers.clear();
+  }
+};
+
+// src/api/client.ts
+function getPlayerTruth(container) {
+  if (typeof window === "undefined") {
+    return {
+      slotWidth: null,
+      slotHeight: null,
+      orientation: null,
+      muted: true,
+      autoplayAllowed: true,
+      userAgent: null
+    };
+  }
+  let width = window.innerWidth;
+  let height = window.innerHeight;
+  if (container) {
+    const rect = container.getBoundingClientRect();
+    if (rect.width > 0 && rect.height > 0) {
+      width = Math.round(rect.width);
+      height = Math.round(rect.height);
+    }
+  }
+  return {
+    slotWidth: width,
+    slotHeight: height,
+    orientation: height > width ? "portrait" : "landscape",
+    muted: true,
+    autoplayAllowed: true,
+    userAgent: typeof navigator !== "undefined" ? navigator.userAgent : null
+  };
+}
+var ApiClient = class {
+  constructor(apiBase) {
+    this.container = null;
+    this.apiBase = apiBase ?? DEFAULT_CONFIG.API_BASE;
+  }
+  /** Bind an optional container element for slot-size measurement. */
+  setContainer(container) {
+    this.container = container;
+  }
+  /**
+   * Fetch the current ad roster for a device.
+   *
+   * Supports conditional requests via `ETag` / `If-None-Match` —
+   * when the server returns 304 the caller receives the previous
+   * ad list untouched (indicated by `notModified: true`).
+   *
+   * The request is aborted after 10 seconds.
+   */
+  async fetchAds(deviceId, etag = null) {
+    const headers = { Accept: "application/json" };
+    if (etag) headers["If-None-Match"] = etag;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 1e4);
+    try {
+      const playerTruth = getPlayerTruth(this.container);
+      const params = new URLSearchParams();
+      if (playerTruth.slotWidth) params.set("slot_w", String(playerTruth.slotWidth));
+      if (playerTruth.slotHeight) params.set("slot_h", String(playerTruth.slotHeight));
+      if (playerTruth.orientation) params.set("orientation", playerTruth.orientation);
+      params.set("muted", playerTruth.muted ? "1" : "0");
+      params.set("autoplay", playerTruth.autoplayAllowed ? "1" : "0");
+      if (playerTruth.userAgent) params.set("ua", playerTruth.userAgent);
+      const query = params.toString();
+      const url = query ? `${this.apiBase}/device/${deviceId}/ads?${query}` : `${this.apiBase}/device/${deviceId}/ads`;
+      const response = await fetch(url, { headers, signal: controller.signal });
+      clearTimeout(timeoutId);
+      if (response.status === 304) {
+        return {
+          ads: [],
+          settings: {},
+          programmatic: null,
+          screenId: null,
+          screenOrientation: null,
+          screenDimensions: null,
+          etag,
+          notModified: true
+        };
+      }
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+      const data = await response.json();
+      const newEtag = response.headers.get("ETag");
+      return {
+        ads: data.data?.ads ?? [],
+        settings: data.data?.settings ?? {},
+        programmatic: data.data?.header_bidding_settings ?? null,
+        screenId: data.data?.screen_id ?? null,
+        screenOrientation: data.data?.screen_orientation ?? null,
+        screenDimensions: data.data?.screen_dimensions ?? null,
+        etag: newEtag,
+        notModified: false
+      };
+    } catch (error) {
+      clearTimeout(timeoutId);
+      throw error;
+    }
+  }
+  /**
+   * Fire an impression pixel.
+   *
+   * Uses a GET request with query-string parameters so the call
+   * survives `navigator.sendBeacon`-like fallback patterns and
+   * can be retried transparently on network failure.
+   *
+   * Returns `true` if the server acknowledged the impression.
+   */
+  async reportImpression(impression) {
+    try {
+      const params = new URLSearchParams({
+        adid: impression.adid,
+        impid: impression.impid,
+        did: impression.did,
+        aid: impression.aid,
+        duration: String(impression.duration || 0),
+        completed: impression.completed ? "true" : "false"
+      });
+      const response = await fetch(`${this.apiBase}/impression?${params}`, {
+        method: "GET",
+        signal: AbortSignal.timeout(5e3)
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Ping the heartbeat endpoint to signal this device is alive.
+   * Returns `true` on 2xx, `false` on any error.
+   */
+  async sendHeartbeat(deviceId, screenId) {
+    try {
+      const response = await fetch(`${this.apiBase}/device/${deviceId}/heartbeat`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          device_id: deviceId,
+          screen_id: screenId,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          status: "active"
+        }),
+        signal: AbortSignal.timeout(5e3)
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Report a programmatic lifecycle event (VAST fill, timeout,
+   * error, etc.) to the analytics backend.
+   */
+  async reportProgrammaticEvent(event) {
+    try {
+      const response = await fetch(`${this.apiBase}/programmatic-event`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          screen_id: event.screenId,
+          device_id: event.deviceId,
+          event_type: event.eventType,
+          vast_source: event.vastSource,
+          variant_name: event.variantName,
+          error_code: event.errorCode,
+          error_message: event.errorMessage,
+          duration: event.duration,
+          telemetry: event.telemetry,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        }),
+        signal: AbortSignal.timeout(5e3)
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/cache/IndexedDBCache.ts
+var IndexedDBCache = class {
+  constructor(maxCacheSize = 10) {
+    this.db = null;
+    this.DB_NAME = "TrillboardsAdsCache";
+    this.DB_VERSION = 1;
+    this.STORE_ADS = "ads";
+    this.STORE_IMPRESSIONS = "pendingImpressions";
+    this.maxCacheSize = maxCacheSize;
+  }
+  /**
+   * Open (or create) the database. Must be called once before any
+   * read/write operations — but calling it multiple times is safe.
+   */
+  async init() {
+    if (this.db) return;
+    return new Promise((resolve, reject) => {
+      if (typeof indexedDB === "undefined") {
+        resolve();
+        return;
+      }
+      const request = indexedDB.open(this.DB_NAME, this.DB_VERSION);
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => {
+        this.db = request.result;
+        resolve();
+      };
+      request.onupgradeneeded = (event) => {
+        const db = event.target.result;
+        if (!db.objectStoreNames.contains(this.STORE_ADS)) {
+          const adsStore = db.createObjectStore(this.STORE_ADS, { keyPath: "id" });
+          adsStore.createIndex("cached_at", "cached_at", { unique: false });
+        }
+        if (!db.objectStoreNames.contains(this.STORE_IMPRESSIONS)) {
+          db.createObjectStore(this.STORE_IMPRESSIONS, { keyPath: "impid" });
+        }
+      };
+    });
+  }
+  /**
+   * Persist an array of ads into the cache, stamping each with the
+   * current time. After writing, any ads beyond `maxCacheSize` are
+   * evicted (oldest-first).
+   */
+  async cacheAds(ads) {
+    if (!this.db) return;
+    const tx = this.db.transaction(this.STORE_ADS, "readwrite");
+    const store = tx.objectStore(this.STORE_ADS);
+    const now = Date.now();
+    for (const ad of ads) {
+      store.put({ ...ad, cached_at: now });
+    }
+    await new Promise((resolve, reject) => {
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => reject(tx.error);
+    });
+    await this.evictOldAds();
+  }
+  /**
+   * Return every cached ad. The results may include the
+   * `cached_at` bookkeeping field added during `cacheAds`.
+   */
+  async getCachedAds() {
+    if (!this.db) return [];
+    return new Promise((resolve) => {
+      const tx = this.db.transaction(this.STORE_ADS, "readonly");
+      const store = tx.objectStore(this.STORE_ADS);
+      const request = store.getAll();
+      request.onsuccess = () => resolve(request.result || []);
+      request.onerror = () => resolve([]);
+    });
+  }
+  /**
+   * Remove the oldest cached ads when the store exceeds
+   * `maxCacheSize`. Sorts by `cached_at` descending and
+   * deletes everything beyond the limit.
+   */
+  async evictOldAds() {
+    if (!this.db) return;
+    const ads = await this.getCachedAds();
+    if (ads.length <= this.maxCacheSize) return;
+    const sorted = [...ads].sort(
+      (a, b) => (b.cached_at ?? 0) - (a.cached_at ?? 0)
+    );
+    const toRemove = sorted.slice(this.maxCacheSize);
+    const tx = this.db.transaction(this.STORE_ADS, "readwrite");
+    const store = tx.objectStore(this.STORE_ADS);
+    for (const ad of toRemove) {
+      store.delete(ad.id);
+    }
+  }
+  /**
+   * Queue an impression payload for later delivery.
+   * The object **must** contain an `impid` field (used as the
+   * primary key).
+   */
+  async savePendingImpression(impression) {
+    if (!this.db) return;
+    const tx = this.db.transaction(this.STORE_IMPRESSIONS, "readwrite");
+    const store = tx.objectStore(this.STORE_IMPRESSIONS);
+    store.put(impression);
+  }
+  /** Retrieve all queued impressions (FIFO order not guaranteed). */
+  async getPendingImpressions() {
+    if (!this.db) return [];
+    return new Promise((resolve) => {
+      const tx = this.db.transaction(this.STORE_IMPRESSIONS, "readonly");
+      const store = tx.objectStore(this.STORE_IMPRESSIONS);
+      const request = store.getAll();
+      request.onsuccess = () => resolve(request.result || []);
+      request.onerror = () => resolve([]);
+    });
+  }
+  /** Remove all pending impressions (typically after a successful flush). */
+  async clearPendingImpressions() {
+    if (!this.db) return;
+    const tx = this.db.transaction(this.STORE_IMPRESSIONS, "readwrite");
+    const store = tx.objectStore(this.STORE_IMPRESSIONS);
+    store.clear();
+  }
+  /** Close the database connection and release the reference. */
+  destroy() {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+};
+
+// src/bridge/NativeBridge.ts
+var NativeBridge = class {
+  constructor() {
+    this.VERSION = "1.0";
+    this.registered = null;
+    this.detected = null;
+    this.sessionId = `sess_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+    this.eventFilter = null;
+    this.commandHandler = null;
+    this.deviceId = null;
+    this.screenId = null;
+    this.messageListener = null;
+    this.targetOrigin = "*";
+  }
+  /**
+   * Attach device / screen identifiers so every outgoing payload
+   * carries them automatically.
+   */
+  setContext(deviceId, screenId) {
+    this.deviceId = deviceId;
+    this.screenId = screenId;
+  }
+  /**
+   * Manually register a custom bridge (useful when the native
+   * shell cannot inject a global but *can* pass callbacks at
+   * construction time).
+   *
+   * Returns `true` if registration succeeded.
+   */
+  register(config) {
+    if (typeof config.send !== "function") {
+      console.error("[TrillboardsAds] Bridge requires send function");
+      return false;
+    }
+    this.registered = {
+      send: config.send,
+      receive: config.receive ?? null,
+      name: config.name ?? "CustomBridge"
+    };
+    if (Array.isArray(config.events)) {
+      this.eventFilter = new Set(config.events);
+    }
+    if (this.registered.receive && this.commandHandler) {
+      this.registered.receive(this.commandHandler);
+    }
+    return true;
+  }
+  /**
+   * Set the handler that will receive inbound commands from the
+   * native shell (e.g. pause, resume, skip).
+   */
+  setCommandHandler(handler) {
+    this.commandHandler = handler;
+  }
+  /**
+   * Set the target origin for iframe postMessage bridge.
+   * Defaults to `'*'` for backwards compatibility; should be
+   * locked down in production to the parent origin.
+   */
+  setTargetOrigin(origin) {
+    this.targetOrigin = origin;
+  }
+  /**
+   * Probe `window` for known native bridge injection points.
+   *
+   * Detection order:
+   *  1. `window.TrillboardsBridge`   -- Android (primary)
+   *  2. `window.Android`             -- Android (legacy)
+   *  3. `window.webkit.messageHandlers.trillboards` -- iOS / WKWebView
+   *  4. `window.ReactNativeWebView`  -- React Native WebView
+   *  5. `window.Flutter`             -- Flutter WebView
+   *  6. `window.__TRILL_CTV_BRIDGE__` -- Trillboards CTV agent
+   *  7. `window.electronAPI`         -- Electron preload
+   *  8. `window.__TAURI__`           -- Tauri IPC
+   *  9. `window.parent !== window`   -- iframe / postMessage
+   *
+   * Re-detects on every call (no caching) so dynamically
+   * injected/removed bridges are picked up immediately.
+   */
+  detect() {
+    if (typeof window === "undefined") return null;
+    let detected = null;
+    if (window.TrillboardsBridge && typeof window.TrillboardsBridge.onEvent === "function") {
+      detected = {
+        type: "android",
+        send: (p) => window.TrillboardsBridge.onEvent(p)
+      };
+    } else if (window.Android && typeof window.Android.onTrillboardsEvent === "function") {
+      detected = {
+        type: "android-alt",
+        send: (p) => window.Android.onTrillboardsEvent(p)
+      };
+    } else if (window.webkit?.messageHandlers?.trillboards?.postMessage) {
+      detected = {
+        type: "ios",
+        send: (p) => window.webkit.messageHandlers.trillboards.postMessage(JSON.parse(p))
+      };
+    } else if (window.ReactNativeWebView && typeof window.ReactNativeWebView.postMessage === "function") {
+      detected = {
+        type: "react-native",
+        send: (p) => window.ReactNativeWebView.postMessage(p)
+      };
+    } else if (window.Flutter && typeof window.Flutter.postMessage === "function") {
+      detected = {
+        type: "flutter",
+        send: (p) => window.Flutter.postMessage(p)
+      };
+    } else if (window.__TRILL_CTV_BRIDGE__ && typeof window.__TRILL_CTV_BRIDGE__.postEvent === "function") {
+      detected = {
+        type: "ctv",
+        send: (p) => window.__TRILL_CTV_BRIDGE__.postEvent(p)
+      };
+    } else if (window.electronAPI && typeof window.electronAPI.trillboardsEvent === "function") {
+      detected = {
+        type: "electron",
+        send: (p) => window.electronAPI.trillboardsEvent(JSON.parse(p))
+      };
+    } else if (window.__TAURI__?.event) {
+      detected = {
+        type: "tauri",
+        send: (p) => {
+          try {
+            window.__TAURI__.event.emit("trillboards-event", JSON.parse(p));
+          } catch {
+          }
+        }
+      };
+    } else if (typeof window !== "undefined" && window.parent !== window && typeof window.parent.postMessage === "function") {
+      const origin = this.targetOrigin;
+      detected = {
+        type: "postMessage",
+        send: (p) => window.parent.postMessage(JSON.parse(p), origin)
+      };
+    }
+    this.detected = detected;
+    return this.detected;
+  }
+  /**
+   * Serialise an event + data into the canonical Trillboards
+   * bridge envelope.
+   */
+  buildPayload(event, data) {
+    const payload = {
+      type: "trillboards",
+      version: this.VERSION,
+      event,
+      data: data ?? {},
+      timestamp: Date.now(),
+      deviceId: this.deviceId,
+      screenId: this.screenId,
+      sessionId: this.sessionId
+    };
+    return JSON.stringify(payload);
+  }
+  /**
+   * Deliver an event to the native host.
+   *
+   * Returns `true` if a bridge accepted the payload, `false` if
+   * the event was filtered out or no bridge is available.
+   */
+  send(event, data) {
+    if (this.eventFilter && !this.eventFilter.has(event)) return false;
+    const payload = this.buildPayload(event, data);
+    if (this.registered?.send) {
+      try {
+        this.registered.send(event, JSON.parse(payload));
+        return true;
+      } catch {
+      }
+    }
+    const detected = this.detect();
+    if (detected?.send) {
+      try {
+        detected.send(payload);
+        return true;
+      } catch {
+      }
+    }
+    return false;
+  }
+  /**
+   * Start listening for inbound `trillboards-command` messages
+   * from the native shell (via `window.postMessage`).
+   *
+   * Call this once during SDK initialisation.
+   */
+  initCommandListener() {
+    if (typeof window === "undefined") return;
+    if (this.messageListener) {
+      window.removeEventListener("message", this.messageListener);
+    }
+    this.messageListener = (event) => {
+      if (event.data?.type === "trillboards-command" && this.commandHandler) {
+        this.commandHandler(event.data);
+      }
+    };
+    window.addEventListener("message", this.messageListener);
+  }
+  /**
+   * Remove the message listener and release references.
+   * Call during SDK teardown to prevent memory leaks.
+   */
+  destroy() {
+    if (typeof window !== "undefined" && this.messageListener) {
+      window.removeEventListener("message", this.messageListener);
+      this.messageListener = null;
+    }
+    this.registered = null;
+    this.detected = null;
+    this.commandHandler = null;
+    this.eventFilter = null;
+  }
+};
+
+// src/player/CircuitBreaker.ts
+var CircuitBreaker = class {
+  constructor(maxFailures = 5, openDurationMs = 3e4) {
+    this.sources = /* @__PURE__ */ new Map();
+    this.maxFailures = maxFailures;
+    this.openDurationMs = openDurationMs;
+  }
+  /**
+   * Record a successful request for a source, resetting its
+   * failure counter and clearing any open-circuit timer.
+   */
+  recordSuccess(sourceName) {
+    if (!sourceName) return;
+    this.sources.set(sourceName, { consecutiveFailures: 0, openUntil: 0 });
+  }
+  /**
+   * Record a failed request for a source. When consecutive
+   * failures reach `maxFailures`, the circuit opens for
+   * `openDurationMs` milliseconds.
+   */
+  recordFailure(sourceName) {
+    if (!sourceName) return;
+    const entry = this.sources.get(sourceName) ?? { consecutiveFailures: 0, openUntil: 0 };
+    entry.consecutiveFailures += 1;
+    if (entry.consecutiveFailures >= this.maxFailures) {
+      entry.openUntil = Date.now() + this.openDurationMs;
+    }
+    this.sources.set(sourceName, entry);
+  }
+  /**
+   * Check whether a source is available for requests.
+   *
+   * Returns `true` when:
+   *  - The source has never been tracked (unknown = available)
+   *  - Consecutive failures are below the threshold (CLOSED)
+   *  - The open-circuit timer has elapsed (HALF-OPEN — allow a probe)
+   */
+  isAvailable(sourceName) {
+    if (!sourceName) return true;
+    const entry = this.sources.get(sourceName);
+    if (!entry) return true;
+    if (entry.consecutiveFailures < this.maxFailures) return true;
+    const now = Date.now();
+    if (now >= entry.openUntil) {
+      entry.openUntil = now + this.openDurationMs;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Return the raw circuit breaker state for a source.
+   * Returns a zeroed-out state for unknown sources.
+   */
+  getState(sourceName) {
+    return this.sources.get(sourceName) ?? { consecutiveFailures: 0, openUntil: 0 };
+  }
+  /**
+   * Clear all tracked source state.
+   */
+  reset() {
+    this.sources.clear();
+  }
+};
+
+// src/player/Telemetry.ts
+var Telemetry = class {
+  constructor() {
+    this.totalRequests = 0;
+    this.fills = 0;
+    this.noFills = 0;
+    this.timeouts = 0;
+    this.errors = 0;
+  }
+  /** Count a new ad request. */
+  recordRequest() {
+    this.totalRequests++;
+  }
+  /** Count a successful fill (ad loaded and ready to play). */
+  recordFill() {
+    this.fills++;
+  }
+  /** Count a request that returned no ad (no fill). */
+  recordNoFill() {
+    this.noFills++;
+  }
+  /** Count a request that timed out before a response arrived. */
+  recordTimeout() {
+    this.timeouts++;
+  }
+  /** Count a request that failed with an error (not a timeout). */
+  recordError() {
+    this.errors++;
+  }
+  /** Ratio of fills to total requests (0-1). */
+  getFillRate() {
+    return this.totalRequests > 0 ? this.fills / this.totalRequests : 0;
+  }
+  /** Ratio of no-fills to total requests (0-1). */
+  getNoFillRate() {
+    return this.totalRequests > 0 ? this.noFills / this.totalRequests : 0;
+  }
+  /** Ratio of timeouts to total requests (0-1). */
+  getTimeoutRate() {
+    return this.totalRequests > 0 ? this.timeouts / this.totalRequests : 0;
+  }
+  /** Ratio of errors to total requests (0-1). */
+  getErrorRate() {
+    return this.totalRequests > 0 ? this.errors / this.totalRequests : 0;
+  }
+  /**
+   * Return a snapshot object suitable for serialization.
+   * Rates are rounded to four decimal places.
+   */
+  getSnapshot() {
+    return {
+      fill_rate: Math.round(this.getFillRate() * 1e4) / 1e4,
+      no_fill_rate: Math.round(this.getNoFillRate() * 1e4) / 1e4,
+      timeout_rate: Math.round(this.getTimeoutRate() * 1e4) / 1e4,
+      error_rate: Math.round(this.getErrorRate() * 1e4) / 1e4
+    };
+  }
+  /** Reset all counters to zero. */
+  reset() {
+    this.totalRequests = 0;
+    this.fills = 0;
+    this.noFills = 0;
+    this.timeouts = 0;
+    this.errors = 0;
+  }
+};
+
+// src/player/WaterfallEngine.ts
+var WaterfallEngine = class {
+  constructor(circuitBreaker) {
+    this.circuitBreaker = circuitBreaker;
+  }
+  /**
+   * Get the next available VAST source from the waterfall.
+   * Sources are sorted by priority (lower = higher priority),
+   * with a random tiebreaker for equal priorities.
+   * Circuit-broken sources are skipped.
+   *
+   * If all sources are circuit-broken, returns `null` to let
+   * the caller handle retry scheduling rather than bypassing
+   * the circuit breaker.
+   */
+  getNextSource(sources) {
+    if (!sources || sources.length === 0) return null;
+    const sorted = [...sources].filter((s) => s.enabled).sort((a, b) => a.priority - b.priority || Math.random() - 0.5);
+    for (const source of sorted) {
+      if (this.circuitBreaker.isAvailable(source.name)) {
+        return { source, vastUrl: source.vast_url };
+      }
+    }
+    return null;
+  }
+  /**
+   * Get all available sources in priority order (for parallel bidding).
+   * Only returns sources that are not circuit-broken.
+   * Equal-priority sources are randomized for load distribution.
+   */
+  getAvailableSources(sources) {
+    if (!sources || sources.length === 0) return [];
+    return sources.filter((s) => s.enabled && this.circuitBreaker.isAvailable(s.name)).sort((a, b) => a.priority - b.priority || Math.random() - 0.5).map((source) => ({ source, vastUrl: source.vast_url }));
+  }
+  /** Record a successful ad fill for a source. */
+  recordSuccess(sourceName) {
+    this.circuitBreaker.recordSuccess(sourceName);
+  }
+  /** Record a failed request for a source. */
+  recordFailure(sourceName) {
+    this.circuitBreaker.recordFailure(sourceName);
+  }
+};
+
+// src/player/ProgrammaticPlayer.ts
+var ProgrammaticPlayer = class {
+  constructor(events, timeoutMs = 12e3) {
+    // ── Public state ──────────────────────────────────────────
+    this.vastTagUrl = null;
+    this.variantName = null;
+    this.screenId = null;
+    this.adContainer = null;
+    this.contentVideo = null;
+    // ── Internal state ────────────────────────────────────────
+    this.ima = {};
+    this.currentSourceName = null;
+    this.isPlaying = false;
+    this.isPrefetching = false;
+    this.prefetchedReady = false;
+    this.prefetchTimer = null;
+    this.adStartTime = 0;
+    // ── Waterfall sources from server ─────────────────────────
+    this.sources = [];
+    this.circuitBreaker = new CircuitBreaker(5, 3e4);
+    this.telemetry = new Telemetry();
+    this.waterfallEngine = new WaterfallEngine(this.circuitBreaker);
+    this.events = events;
+    this.timeoutMs = timeoutMs;
+  }
+  /** Replace the current set of demand sources. */
+  setSources(sources) {
+    this.sources = sources;
+  }
+  /** Return aggregate fill/timeout/error rates. */
+  getTelemetrySnapshot() {
+    return this.telemetry.getSnapshot();
+  }
+  /** Whether a programmatic ad is currently playing. */
+  getIsPlaying() {
+    return this.isPlaying;
+  }
+  /** Whether a prefetched ad is ready for instant playback. */
+  hasPrefetchedAd() {
+    return this.prefetchedReady;
+  }
+  /**
+   * Create the ad container and content video element needed
+   * by IMA SDK. Appended as an overlay to `parentElement`.
+   */
+  createAdContainer(parentElement) {
+    if (this.adContainer) return;
+    this.adContainer = document.createElement("div");
+    this.adContainer.id = "trillboards-ad-container";
+    this.adContainer.style.cssText = "position:absolute;top:0;left:0;width:100%;height:100%;z-index:10000;display:none;";
+    this.contentVideo = document.createElement("video");
+    this.contentVideo.id = "trillboards-content-video";
+    this.contentVideo.style.cssText = "width:100%;height:100%;";
+    this.contentVideo.setAttribute("playsinline", "");
+    this.contentVideo.muted = true;
+    this.adContainer.appendChild(this.contentVideo);
+    parentElement.appendChild(this.adContainer);
+  }
+  /**
+   * Request and play a VAST ad using Google IMA SDK.
+   *
+   * Picks the next available source from the waterfall (or
+   * falls back to `vastTagUrl`), adds a cache-busting correlator,
+   * and delegates to IMA for ad loading + playback.
+   */
+  async play(onComplete, onError) {
+    if (this.isPlaying) return;
+    if (!this.adContainer || !this.contentVideo) {
+      onError("Ad container not initialized");
+      return;
+    }
+    let vastUrl = this.vastTagUrl;
+    let sourceName = "default";
+    if (this.sources.length > 0) {
+      const result = this.waterfallEngine.getNextSource(this.sources);
+      if (result) {
+        vastUrl = result.vastUrl;
+        sourceName = result.source.name;
+      }
+    }
+    if (!vastUrl) {
+      onError("No VAST URL available");
+      return;
+    }
+    this.currentSourceName = sourceName;
+    this.telemetry.recordRequest();
+    const correlator = Date.now();
+    const finalUrl = vastUrl.includes("correlator=") ? vastUrl.replace(/correlator=[^&]*/, `correlator=${correlator}`) : `${vastUrl}${vastUrl.includes("?") ? "&" : "?"}correlator=${correlator}`;
+    if (typeof google === "undefined" || !google?.ima) {
+      onError("Google IMA SDK not loaded");
+      this.telemetry.recordError();
+      this.waterfallEngine.recordFailure(sourceName);
+      return;
+    }
+    this.isPlaying = true;
+    this.adContainer.style.display = "block";
+    try {
+      await this.requestAdsViaIMA(finalUrl, onComplete, onError);
+    } catch (err) {
+      this.isPlaying = false;
+      this.adContainer.style.display = "none";
+      this.telemetry.recordError();
+      this.waterfallEngine.recordFailure(sourceName);
+      onError(err instanceof Error ? err.message : String(err));
+    }
+  }
+  // ── IMA request / playback lifecycle ──────────────────────
+  async requestAdsViaIMA(vastUrl, onComplete, onError) {
+    return new Promise((resolve) => {
+      let settled = false;
+      const guardedComplete = () => {
+        if (settled) return;
+        settled = true;
+        onComplete();
+        resolve();
+      };
+      const guardedError = (msg) => {
+        if (settled) return;
+        settled = true;
+        onError(msg);
+        resolve();
+      };
+      this.destroyIMA();
+      const adDisplayContainer = new google.ima.AdDisplayContainer(
+        this.adContainer,
+        this.contentVideo
+      );
+      adDisplayContainer.initialize();
+      const adsLoader = new google.ima.AdsLoader(adDisplayContainer);
+      this.ima.adDisplayContainer = adDisplayContainer;
+      this.ima.adsLoader = adsLoader;
+      const timeout = setTimeout(() => {
+        this.telemetry.recordTimeout();
+        this.waterfallEngine.recordFailure(this.currentSourceName);
+        this.stop({ silent: true });
+        this.events.emit("programmatic_timeout", {
+          source: this.currentSourceName || "unknown"
+        });
+        guardedError("VAST request timeout");
+      }, this.timeoutMs);
+      adsLoader.addEventListener(
+        google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
+        (adsManagerEvent) => {
+          clearTimeout(timeout);
+          this.telemetry.recordFill();
+          this.waterfallEngine.recordSuccess(this.currentSourceName);
+          const adsManager = adsManagerEvent.getAdsManager(this.contentVideo);
+          this.ima.adsManager = adsManager;
+          this.adStartTime = Date.now();
+          adsManager.addEventListener(
+            google.ima.AdEvent.Type.COMPLETE,
+            () => {
+              const duration = Math.round(
+                (Date.now() - this.adStartTime) / 1e3
+              );
+              this.events.emit("programmatic_ended", {
+                source: this.currentSourceName || "unknown",
+                variant: this.variantName,
+                duration
+              });
+              this.stop({ silent: true });
+              guardedComplete();
+            }
+          );
+          adsManager.addEventListener(
+            google.ima.AdEvent.Type.STARTED,
+            () => {
+              this.events.emit("programmatic_started", {
+                source: this.currentSourceName || "unknown",
+                variant: this.variantName
+              });
+            }
+          );
+          adsManager.addEventListener(
+            google.ima.AdErrorEvent.Type.AD_ERROR,
+            (adErrorEvent) => {
+              const error = adErrorEvent.getError();
+              this.events.emit("programmatic_error", {
+                error: error?.getMessage?.() || "Ad playback error",
+                code: error?.getErrorCode?.()
+              });
+              this.stop({ silent: true });
+              guardedError(error?.getMessage?.() || "Ad error");
+            }
+          );
+          try {
+            const width = this.adContainer.offsetWidth || window.innerWidth;
+            const height = this.adContainer.offsetHeight || window.innerHeight;
+            adsManager.init(width, height, google.ima.ViewMode.NORMAL);
+            adsManager.start();
+          } catch {
+            this.stop({ silent: true });
+            guardedError("Failed to start ad");
+          }
+        }
+      );
+      adsLoader.addEventListener(
+        google.ima.AdErrorEvent.Type.AD_ERROR,
+        (adErrorEvent) => {
+          clearTimeout(timeout);
+          const error = adErrorEvent.getError();
+          const errorCode = error?.getErrorCode?.();
+          const errorMsg = error?.getMessage?.() || "Ad load error";
+          if (errorCode === 303) {
+            this.waterfallEngine.recordFailure(this.currentSourceName);
+            this.events.emit("programmatic_no_fill", {
+              source: this.currentSourceName || "unknown"
+            });
+          } else {
+            this.telemetry.recordError();
+            this.waterfallEngine.recordFailure(this.currentSourceName);
+            this.events.emit("programmatic_error", {
+              error: errorMsg,
+              code: errorCode
+            });
+          }
+          this.stop({ silent: true });
+          guardedError(errorMsg);
+        }
+      );
+      const adsRequest = new google.ima.AdsRequest();
+      adsRequest.adTagUrl = vastUrl;
+      adsRequest.linearAdSlotWidth = this.adContainer.offsetWidth || window.innerWidth;
+      adsRequest.linearAdSlotHeight = this.adContainer.offsetHeight || window.innerHeight;
+      this.ima.adsRequest = adsRequest;
+      adsLoader.requestAds(adsRequest);
+    });
+  }
+  // ── Prefetch ──────────────────────────────────────────────
+  /**
+   * Prefetch the next ad for instant playback.
+   * Currently marks prefetch as ready; actual IMA preloading
+   * is a future enhancement.
+   */
+  async prefetch() {
+    if (this.isPrefetching || this.prefetchedReady) return false;
+    if (!this.vastTagUrl && this.sources.length === 0) return false;
+    this.isPrefetching = true;
+    this.prefetchedReady = true;
+    this.isPrefetching = false;
+    this.events.emit("ad_ready", {
+      type: "programmatic",
+      source: this.currentSourceName || void 0
+    });
+    return true;
+  }
+  /** Destroy any prefetched ad state. */
+  destroyPrefetched() {
+    this.prefetchedReady = false;
+    this.isPrefetching = false;
+    if (this.prefetchTimer) {
+      clearTimeout(this.prefetchTimer);
+      this.prefetchTimer = null;
+    }
+  }
+  // ── Stop / destroy ────────────────────────────────────────
+  /** Stop current ad playback and hide the container. */
+  stop(_options) {
+    this.isPlaying = false;
+    this.destroyIMA();
+    if (this.adContainer) {
+      this.adContainer.style.display = "none";
+    }
+  }
+  destroyIMA() {
+    if (this.ima.adsManager) {
+      try {
+        this.ima.adsManager.removeEventListener(
+          google.ima.AdEvent.Type.COMPLETE
+        );
+        this.ima.adsManager.removeEventListener(
+          google.ima.AdEvent.Type.STARTED
+        );
+        this.ima.adsManager.removeEventListener(
+          google.ima.AdErrorEvent.Type.AD_ERROR
+        );
+      } catch {
+      }
+      try {
+        this.ima.adsManager.destroy();
+      } catch {
+      }
+      this.ima.adsManager = null;
+    }
+    if (this.ima.adsLoader) {
+      try {
+        this.ima.adsLoader.destroy();
+      } catch {
+      }
+      this.ima.adsLoader = null;
+    }
+    this.ima.adDisplayContainer = null;
+    this.ima.adsRequest = null;
+  }
+  /** Tear down everything — DOM, timers, circuit breaker state. */
+  destroy() {
+    this.stop({ silent: true });
+    this.destroyPrefetched();
+    if (this.adContainer) {
+      this.adContainer.remove();
+      this.adContainer = null;
+      this.contentVideo = null;
+    }
+    this.circuitBreaker.reset();
+    this.telemetry.reset();
+  }
+};
+
+// src/player/Player.ts
+var MAX_AD_DURATION_SECONDS = 300;
+var Player = class {
+  /**
+   * @param events           Shared event emitter for SDK-wide events.
+   * @param defaultImageDuration  Fallback display time for images in ms.
+   */
+  constructor(events, defaultImageDuration = 8e3) {
+    this.container = null;
+    this.currentAd = null;
+    this.adTimer = null;
+    this.videoElement = null;
+    this.imageElement = null;
+    this.videoEndedHandler = null;
+    this.videoErrorHandler = null;
+    this.events = events;
+    this.defaultImageDuration = defaultImageDuration;
+  }
+  /** Set the DOM element that ads will be rendered into. */
+  setContainer(container) {
+    this.container = container;
+  }
+  /**
+   * Play a direct ad. Stops any currently playing ad first.
+   * Calls `onComplete` when playback finishes (natural end or
+   * error fallback).
+   *
+   * @param ad          The ad to play.
+   * @param onComplete  Called when the ad finishes or errors.
+   * @param index       Position in the playlist (emitted in ad_started).
+   */
+  play(ad, onComplete, index = 0) {
+    if (!this.container) return;
+    this.stop();
+    this.currentAd = ad;
+    this.events.emit("ad_started", { id: ad.id, type: ad.type, index });
+    if (ad.type === "video") {
+      this.playVideo(ad, onComplete);
+    } else {
+      this.playImage(ad, onComplete);
+    }
+  }
+  // ── Video playback ────────────────────────────────────────
+  playVideo(ad, onComplete) {
+    this.videoElement = document.createElement("video");
+    this.videoElement.src = ad.media_url;
+    this.videoElement.style.cssText = "width:100%;height:100%;object-fit:contain;";
+    this.videoElement.setAttribute("playsinline", "");
+    this.videoElement.muted = true;
+    this.videoElement.autoplay = true;
+    this.videoEndedHandler = () => {
+      const duration = Math.min(
+        Math.round(this.videoElement?.duration ?? ad.duration),
+        MAX_AD_DURATION_SECONDS
+      );
+      this.events.emit("ad_ended", {
+        id: ad.id,
+        type: ad.type,
+        duration
+      });
+      this.stop();
+      onComplete();
+    };
+    this.videoErrorHandler = () => {
+      this.events.emit("ad_error", { error: "Video playback error" });
+      this.stop();
+      onComplete();
+    };
+    this.videoElement.addEventListener("ended", this.videoEndedHandler);
+    this.videoElement.addEventListener("error", this.videoErrorHandler);
+    while (this.container.firstChild) {
+      this.container.removeChild(this.container.firstChild);
+    }
+    this.container.appendChild(this.videoElement);
+  }
+  // ── Image playback ────────────────────────────────────────
+  playImage(ad, onComplete) {
+    this.imageElement = document.createElement("img");
+    this.imageElement.src = ad.media_url;
+    this.imageElement.style.cssText = "width:100%;height:100%;object-fit:contain;";
+    this.imageElement.alt = ad.title ?? "Advertisement";
+    while (this.container.firstChild) {
+      this.container.removeChild(this.container.firstChild);
+    }
+    this.container.appendChild(this.imageElement);
+    const durationSec = Math.min(
+      ad.duration || this.defaultImageDuration / 1e3,
+      MAX_AD_DURATION_SECONDS
+    );
+    const durationMs = durationSec * 1e3;
+    this.adTimer = setTimeout(() => {
+      this.events.emit("ad_ended", {
+        id: ad.id,
+        type: ad.type,
+        duration: Math.round(durationSec)
+      });
+      this.stop();
+      onComplete();
+    }, durationMs);
+  }
+  // ── Stop / destroy ────────────────────────────────────────
+  /** Stop any currently playing ad and clean up DOM nodes. */
+  stop() {
+    if (this.adTimer) {
+      clearTimeout(this.adTimer);
+      this.adTimer = null;
+    }
+    if (this.videoElement) {
+      if (this.videoEndedHandler) {
+        this.videoElement.removeEventListener("ended", this.videoEndedHandler);
+        this.videoEndedHandler = null;
+      }
+      if (this.videoErrorHandler) {
+        this.videoElement.removeEventListener("error", this.videoErrorHandler);
+        this.videoErrorHandler = null;
+      }
+      this.videoElement.pause();
+      this.videoElement.removeAttribute("src");
+      this.videoElement.load();
+      this.videoElement.remove();
+      this.videoElement = null;
+    }
+    if (this.imageElement) {
+      this.imageElement.remove();
+      this.imageElement = null;
+    }
+    this.currentAd = null;
+  }
+  /** Tear down the player, releasing the container reference. */
+  destroy() {
+    this.stop();
+    this.container = null;
+  }
+};
+
+// src/core/TrillboardsAds.ts
+function normalizeWaterfallMode(value) {
+  if (!value) return null;
+  const normalized = String(value).toLowerCase();
+  if (["programmatic_only", "programmatic-only", "programmatic"].includes(normalized)) {
+    return "programmatic_only";
+  }
+  if (["programmatic_then_direct", "programmatic-direct", "programmatic+direct", "hybrid"].includes(normalized)) {
+    return "programmatic_then_direct";
+  }
+  if (["direct_only", "direct-only", "direct"].includes(normalized)) {
+    return "direct_only";
+  }
+  return null;
+}
+var _TrillboardsAds = class _TrillboardsAds {
+  constructor(config) {
+    /** Stored references for window event listeners (cleanup in destroy). */
+    this.onlineHandler = null;
+    this.offlineHandler = null;
+    this.visibilityHandler = null;
+    this.config = resolveConfig(config);
+    this.state = createInitialState();
+    this.events = new EventEmitter();
+    this.api = new ApiClient(this.config.apiBase);
+    this.cache = new IndexedDBCache(this.config.cacheSize);
+    this.bridge = new NativeBridge();
+    this.programmaticPlayer = new ProgrammaticPlayer(this.events, this.config.programmaticTimeout);
+    this.directPlayer = new Player(this.events, this.config.defaultImageDuration);
+  }
+  /**
+   * Create and initialize a new TrillboardsAds instance.
+   * If a previous instance exists, it is destroyed first
+   * (singleton guard).
+   */
+  static async create(config) {
+    if (_TrillboardsAds._instance) {
+      _TrillboardsAds._instance.destroy();
+      _TrillboardsAds._instance = null;
+    }
+    const instance = new _TrillboardsAds(config);
+    await instance.init(config);
+    _TrillboardsAds._instance = instance;
+    return instance;
+  }
+  /**
+   * Initialize the SDK (private — called by `create()` only).
+   */
+  async init(config) {
+    if (this.state.initialized) return;
+    this.config = resolveConfig(config);
+    this.state.deviceId = this.config.deviceId;
+    this.state.waterfallMode = this.config.waterfall;
+    this.state.autoStart = this.config.autoStart;
+    try {
+      await this.cache.init();
+    } catch {
+    }
+    this.bridge.setContext(this.state.deviceId, this.state.screenId);
+    this.bridge.setCommandHandler((command) => this.handleBridgeCommand(command));
+    this.bridge.initCommandListener();
+    this.bridge.detect();
+    const bridgeEvents = [
+      "initialized",
+      "ad_started",
+      "ad_ended",
+      "ad_ready",
+      "ad_error",
+      "programmatic_started",
+      "programmatic_ended",
+      "programmatic_error",
+      "programmatic_no_fill",
+      "state_changed"
+    ];
+    for (const eventName of bridgeEvents) {
+      this.events.on(eventName, (data) => {
+        this.bridge.send(eventName, data);
+      });
+    }
+    this.createContainer();
+    if (typeof window !== "undefined") {
+      this.onlineHandler = () => {
+        if (this.state.isOffline) {
+          this.state.isOffline = false;
+          this.events.emit("online", {});
+        }
+        this.refreshAds().catch(() => {
+        });
+      };
+      this.offlineHandler = () => {
+        this.state.isOffline = true;
+        this.events.emit("offline", {});
+        this.emitStateChanged();
+      };
+      window.addEventListener("online", this.onlineHandler);
+      window.addEventListener("offline", this.offlineHandler);
+      this.visibilityHandler = () => {
+        const visible = !document.hidden;
+        this.events.emit("visibility_changed", { visible });
+        if (visible) {
+          this.refreshAds().catch(() => {
+          });
+        }
+      };
+      document.addEventListener("visibilitychange", this.visibilityHandler);
+    }
+    await this.refreshAds();
+    this.startRefreshTimer();
+    this.startHeartbeatTimer();
+    this.state.initialized = true;
+    this.events.emit("initialized", { deviceId: this.config.deviceId });
+    this.emitStateChanged();
+    if (this.state.autoStart) {
+      this.prefetchNextAd().catch(() => {
+      });
+    }
+  }
+  /**
+   * Destroy the SDK instance and clean up all resources.
+   */
+  destroy() {
+    if (this.state.refreshTimer) clearInterval(this.state.refreshTimer);
+    if (this.state.heartbeatTimer) clearInterval(this.state.heartbeatTimer);
+    if (this.state.adTimer) clearTimeout(this.state.adTimer);
+    if (this.state.programmaticRetryTimer) clearTimeout(this.state.programmaticRetryTimer);
+    this.programmaticPlayer.destroy();
+    this.directPlayer.destroy();
+    this.bridge.destroy();
+    this.cache.destroy();
+    if (typeof window !== "undefined") {
+      if (this.onlineHandler) {
+        window.removeEventListener("online", this.onlineHandler);
+        this.onlineHandler = null;
+      }
+      if (this.offlineHandler) {
+        window.removeEventListener("offline", this.offlineHandler);
+        this.offlineHandler = null;
+      }
+      if (this.visibilityHandler) {
+        document.removeEventListener("visibilitychange", this.visibilityHandler);
+        this.visibilityHandler = null;
+      }
+    }
+    if (this.state.container) {
+      this.state.container.remove();
+    }
+    this.events.removeAllListeners();
+    this.state = createInitialState();
+    if (_TrillboardsAds._instance === this) {
+      _TrillboardsAds._instance = null;
+    }
+  }
+  /**
+   * Show the ad container and start playback.
+   */
+  show() {
+    if (this.state.container) {
+      this.state.container.style.display = "block";
+    }
+    this.state.isPlaying = true;
+    this.state.isPaused = false;
+    this.playNextAd();
+    this.emitStateChanged();
+  }
+  /**
+   * Hide the ad container and pause playback.
+   */
+  hide() {
+    if (this.state.container) {
+      this.state.container.style.display = "none";
+    }
+    this.state.isPlaying = false;
+    this.state.isPaused = true;
+    this.programmaticPlayer.stop();
+    this.directPlayer.stop();
+    this.emitStateChanged();
+  }
+  /**
+   * Skip the current ad.
+   */
+  skipAd() {
+    this.programmaticPlayer.stop();
+    this.directPlayer.stop();
+    this.playNextAd();
+  }
+  /**
+   * Force refresh — re-fetches VAST URLs from server with null etag.
+   */
+  async refresh() {
+    this.programmaticPlayer.destroyPrefetched();
+    this.resetProgrammaticBackoff();
+    this.state.etag = null;
+    await this.refreshAds();
+    this.prefetchNextAd();
+  }
+  /**
+   * Prefetch the next ad for instant playback.
+   */
+  async prefetchNextAd() {
+    const mode = this.state.waterfallMode;
+    if (mode === "programmatic_only" || mode === "programmatic_then_direct") {
+      const prog = this.state.programmatic;
+      if (prog?.vast_tag_url || prog?.sources && prog.sources.length > 0) {
+        await this.programmaticPlayer.prefetch();
+      }
+    }
+  }
+  /**
+   * Get current public state.
+   */
+  getState() {
+    return getPublicState(this.state);
+  }
+  /**
+   * Get current ad list.
+   */
+  getAds() {
+    return [...this.state.ads];
+  }
+  /**
+   * Subscribe to an event.
+   */
+  on(event, handler) {
+    this.events.on(event, handler);
+  }
+  /**
+   * Unsubscribe from an event.
+   */
+  off(event, handler) {
+    this.events.off(event, handler);
+  }
+  /**
+   * Register a custom native bridge.
+   */
+  registerBridge(config) {
+    return this.bridge.register(config);
+  }
+  // ========================
+  // Private methods
+  // ========================
+  createContainer() {
+    if (typeof document === "undefined") return;
+    const container = document.createElement("div");
+    container.id = "trillboards-ads-container";
+    container.style.cssText = "position:fixed;top:0;left:0;width:100%;height:100%;z-index:99999;display:none;background:#000;";
+    document.body.appendChild(container);
+    this.state.container = container;
+    this.api.setContainer(container);
+    this.directPlayer.setContainer(container);
+    this.programmaticPlayer.createAdContainer(container);
+  }
+  async refreshAds() {
+    try {
+      const result = await this.api.fetchAds(this.config.deviceId, this.state.etag);
+      if (result.notModified) return;
+      if (this.state.isOffline) {
+        this.state.isOffline = false;
+        this.events.emit("online", {});
+      }
+      this.state.ads = result.ads;
+      this.state.settings = result.settings;
+      this.state.etag = result.etag;
+      this.state.screenId = result.screenId ?? this.state.screenId;
+      this.state.programmatic = result.programmatic;
+      this.state.screenOrientation = result.screenOrientation ?? this.state.screenOrientation;
+      this.state.screenDimensions = result.screenDimensions ?? this.state.screenDimensions;
+      this.bridge.setContext(this.state.deviceId, this.state.screenId);
+      this.programmaticPlayer.screenId = this.state.screenId;
+      this.programmaticPlayer.vastTagUrl = this.state.programmatic?.vast_tag_url ?? null;
+      this.programmaticPlayer.variantName = this.state.programmatic?.variant_name ?? null;
+      if (this.state.programmatic?.sources) {
+        this.programmaticPlayer.setSources(this.state.programmatic.sources);
+      }
+      if (this.state.ads.length > 0) {
+        await this.cache.cacheAds(this.state.ads);
+      }
+      this.events.emit("ads_refreshed", { count: this.state.ads.length });
+    } catch {
+      this.state.isOffline = true;
+      const cachedAds = await this.cache.getCachedAds();
+      if (cachedAds.length > 0) {
+        this.state.ads = cachedAds;
+        this.events.emit("ads_loaded_from_cache", { count: cachedAds.length });
+      }
+    }
+  }
+  startRefreshTimer() {
+    if (this.state.refreshTimer) clearInterval(this.state.refreshTimer);
+    this.state.refreshTimer = setInterval(() => {
+      this.refreshAds().catch(() => {
+      });
+    }, this.config.refreshInterval);
+  }
+  startHeartbeatTimer() {
+    if (this.state.heartbeatTimer) clearInterval(this.state.heartbeatTimer);
+    this.state.heartbeatTimer = setInterval(() => {
+      this.api.sendHeartbeat(this.config.deviceId, this.state.screenId);
+    }, this.config.heartbeatInterval);
+  }
+  playNextAd() {
+    const mode = this.state.waterfallMode;
+    if (mode === "programmatic_only" || mode === "programmatic_then_direct") {
+      this.playProgrammatic();
+    } else if (mode === "direct_only") {
+      this.playDirect();
+    }
+  }
+  playProgrammatic() {
+    if (this.programmaticPlayer.getIsPlaying()) return;
+    this.state.programmaticPlaying = true;
+    this.emitStateChanged();
+    this.programmaticPlayer.play(
+      () => {
+        this.state.programmaticPlaying = false;
+        this.emitStateChanged();
+        this.scheduleProgrammaticRetry();
+      },
+      (error) => {
+        this.state.programmaticPlaying = false;
+        this.state.programmaticLastError = error;
+        this.state.programmaticRetryCount++;
+        this.emitStateChanged();
+        if (this.state.waterfallMode === "programmatic_then_direct" && this.state.ads.length > 0) {
+          this.playDirect();
+        } else {
+          this.scheduleProgrammaticRetry();
+        }
+      }
+    );
+  }
+  playDirect() {
+    if (this.state.ads.length === 0) return;
+    const index = this.state.currentAdIndex % this.state.ads.length;
+    const ad = this.state.ads[index];
+    if (!ad) return;
+    this.directPlayer.play(
+      ad,
+      () => {
+        this.state.currentAdIndex = (index + 1) % this.state.ads.length;
+        this.api.reportImpression({
+          adid: ad.id,
+          impid: ad.impression_id,
+          did: this.config.deviceId,
+          aid: ad.allocation_id ?? "",
+          duration: ad.duration,
+          completed: true
+        });
+        this.emitStateChanged();
+        this.scheduleNextDirect();
+      },
+      index
+    );
+  }
+  scheduleNextDirect() {
+    if (this.state.adTimer) clearTimeout(this.state.adTimer);
+    this.state.adTimer = setTimeout(() => {
+      this.playNextAd();
+    }, this.config.defaultAdInterval);
+  }
+  scheduleProgrammaticRetry() {
+    if (this.state.programmaticRetryTimer) clearTimeout(this.state.programmaticRetryTimer);
+    const retryCount = this.state.programmaticRetryCount;
+    const baseDelay = this.config.programmaticRetry;
+    const maxDelay = this.config.programmaticBackoffMax;
+    const delay = Math.min(baseDelay * Math.pow(2, retryCount), maxDelay);
+    const jitter = delay * 0.2 * Math.random();
+    this.state.programmaticRetryTimer = setTimeout(() => {
+      this.prefetchNextAd().catch(() => {
+      }).then(() => {
+        this.playNextAd();
+      });
+    }, delay + jitter);
+  }
+  resetProgrammaticBackoff() {
+    this.state.programmaticRetryCount = 0;
+    this.state.programmaticLastError = null;
+    if (this.state.programmaticRetryTimer) {
+      clearTimeout(this.state.programmaticRetryTimer);
+      this.state.programmaticRetryTimer = null;
+    }
+  }
+  emitStateChanged() {
+    this.events.emit("state_changed", this.getState());
+  }
+  handleBridgeCommand(command) {
+    let cmd;
+    try {
+      cmd = typeof command === "string" ? JSON.parse(command) : command;
+    } catch {
+      console.warn("[TrillboardsAds] Failed to parse bridge command:", command);
+      return;
+    }
+    const action = cmd.action || cmd.command;
+    const params = cmd.params || cmd.data || {};
+    switch (action) {
+      case "show":
+        this.show();
+        break;
+      case "hide":
+        this.hide();
+        break;
+      case "skip":
+        this.skipAd();
+        break;
+      case "refresh":
+        this.refresh();
+        break;
+      case "getState":
+        this.bridge.send("state_changed", this.getState());
+        break;
+      case "configure":
+        if (params.waterfall) {
+          const normalized = normalizeWaterfallMode(params.waterfall);
+          if (normalized) this.state.waterfallMode = normalized;
+        }
+        if (typeof params.volume === "number") {
+          this.state.settings.sound_enabled = params.volume > 0;
+        }
+        break;
+    }
+  }
+};
+/** Singleton reference — `create()` destroys any previous instance. */
+_TrillboardsAds._instance = null;
+var TrillboardsAds = _TrillboardsAds;
+
+export { ApiClient, CircuitBreaker, DEFAULT_CONFIG, DEFAULT_PUBLIC_STATE, EventEmitter, SDK_VERSION, Telemetry, TrillboardsAds, WaterfallEngine, createInitialState, getPublicState, resolveConfig };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map