stormcloud-video-player 0.7.50 → 0.8.1

package/README.md

@@ -1,19 +1,20 @@
 # Stormcloud Video Player
 
-A professional video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, and Prebid Server integration for server-side header bidding and VAST ad playback. Now featuring a modern, extensible architecture inspired by react-player.
+A professional video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, VMAP ad-break scheduling, custom VAST ad serving, and optional Google IMA SDK integration for seamless ad playback. Now featuring a modern, extensible architecture inspired by react-player.
 
 ## 🎯 Key Features
 
 - **Multi-Format Support**: Automatic detection and playback of HLS streams and regular video files
 - **Precision Ad Alignment**: Tight synchronization with SCTE-35 CUE-OUT signals
+- **VMAP 1.0 Support**: Schedule pre-roll, mid-roll, and post-roll ad breaks via a VMAP manifest
 - **Smart Mid-Roll Handling**: Automatic detection and playback of remaining ad portions when joining late
-- **Flexible Ad Scheduling**: Support for both SCTE-35 markers and external ad schedules
+- **Flexible Ad Scheduling**: Support for SCTE-35 markers, VMAP manifests, and external ad schedules
 - **Enhanced UI Controls**: Beautiful, adaptive video controls that work on any background color
 - **Live Mode Support**: Specialized controls for live streaming with volume adjustment
-- **Cross-Platform**: Works on desktop, mobile, tablets, and smart TVs
+- **Cross-Platform & Smart TV Ready**: Desktop, mobile, tablets, LG WebOS, Samsung Tizen, Sony BRAVIA, Android TV, Roku, Apple TV
+- **Automatic Browser Compatibility**: Built-in browser detection, polyfills, and automatic ad-player selection for legacy Smart TVs
 - **React Ready**: Multiple React components for different use cases
 - **TypeScript Support**: Full type definitions included
-- **Prebid Server Support**: Server-side header bidding via OpenRTB 2.5 with zero client-side SDK
 - **Professional Architecture**: Modular player system with lazy loading
 
 ## 🚀 Quick Start
@@ -40,9 +41,11 @@ function MyVideoApp() {
       muted={true}
       controls={true}
       showCustomControls={true} // Enable enhanced UI controls
+      hideLoadingIndicator={false} // Hide the built-in loading spinner
       allowNativeHls={true} // Allow native HLS for better performance
       licenseKey="your_license_key_here"
       vastMode="adstorm" // Use AdStorm mode with HLS ad player
+      vmapUrl="https://your-cdn.com/ads.vmap" // Optional VMAP manifest for scheduled breaks
       style={{ width: "100%", aspectRatio: "16/9" }}
       wrapperStyle={{ borderRadius: "12px", overflow: "hidden" }}
       onReady={(player) => {
@@ -78,8 +81,10 @@ function MyVideoApp() {
       // Stormcloud-specific props
       allowNativeHls={true}
       showCustomControls={true}
+      hideLoadingIndicator={false}
       licenseKey="your_license_key_here"
       vastMode="adstorm" // Use AdStorm mode (or omit for default mode)
+      vmapUrl="https://your-cdn.com/ads.vmap" // Optional: VMAP manifest URL
       onReady={(player) => {
         console.log("Player is ready!", player);
       }}
@@ -115,9 +120,12 @@ const player = new StormcloudVideoPlayer({
   muted: true,
   allowNativeHls: true, // Enable native HLS when supported
   showCustomControls: true, // Enable enhanced UI controls
+  hideLoadingIndicator: false, // Hide built-in loading spinner
   lowLatencyMode: false, // Set to true for live streams
   driftToleranceMs: 3000, // Drift tolerance for live streams
   licenseKey: "your_license_key_here",
+  vastMode: "default", // "adstorm" | "default"
+  vmapUrl: "https://your-cdn.com/ads.vmap", // Optional VMAP manifest for scheduled ad breaks
   onVolumeToggle: () => console.log("Volume toggled"),
   onFullscreenToggle: () => console.log("Fullscreen toggled"),
 });
@@ -127,8 +135,6 @@ await player.load();
 
 ### CDN Usage
 
-Include the single script tag and access everything from `window.StormcloudVP`:
-
 ```html
 <script src="https://cdn.jsdelivr.net/npm/stormcloud-video-player/dist/stormcloud-vp.min.js"></script>
 
@@ -147,8 +153,6 @@ Include the single script tag and access everything from `window.StormcloudVP`:
 </script>
 ```
 
-Prebid utilities (`createPrebidManager`, `createPrebidController`) are available on the `window.StormcloudVP` global. See the [Prebid Mode](#3-prebid-mode-server-side-header-bidding) section for a full CDN example with Prebid Server.
-
 ## 🏗️ Professional Architecture
 
 The Stormcloud Video Player now follows a professional, modular architecture similar to react-player:
@@ -170,7 +174,7 @@ StormcloudPlayer (Main Component)
 - **Purpose**: Handles HLS (.m3u8) streams with advanced features
 - **Features**:
   - SCTE-35 ad marker detection and processing
-  - Prebid Server integration for VAST ad playback
+  - Google IMA SDK integration for VAST/VPAID ads
   - Live stream support with low-latency mode
   - Drift correction for live timing
   - Manifest-based and ID3 ad markers
@@ -269,14 +273,16 @@ interface StormcloudPlayerProps {
   immediateManifestAds?: boolean;
   debugAdTiming?: boolean;
   showCustomControls?: boolean;
+  hideLoadingIndicator?: boolean; // Hide the built-in loading spinner (default: false)
   licenseKey?: string;
   adFailsafeTimeoutMs?: number;
   minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
 
   // Ad player configuration
-  vastMode?: 'adstorm' | 'default'; // VAST mode (default: 'default')
-  vastTagUrl?: string; // Custom VAST URL (if provided)
-  prebid?: PrebidConfig; // Prebid Server configuration for ad auctions
+  vastMode?: 'adstorm' | 'default'; // VAST mode: 'adstorm' (HLS player + AdStorm VAST endpoint) or 'default' (IMA SDK + /ads/web endpoint) (default: 'default')
+  vastTagUrl?: string; // Custom VAST URL (used in default mode if provided; when not provided, uses /ads/web endpoint)
+  vmapUrl?: string; // Optional VMAP 1.0 manifest URL used to schedule pre/mid/post-roll ad breaks
+  adPlayerType?: 'ima' | 'hls'; // Manual override for ad player type (auto-determined by vastMode if not specified)
 
   // Event handlers
   onReady?: (player: StormcloudVideoPlayer) => void;
@@ -352,6 +358,7 @@ interface StormcloudVideoPlayerConfig {
   muted?: boolean; // Start muted (default: false)
   allowNativeHls?: boolean; // Use native HLS when available (default: false)
   showCustomControls?: boolean; // Enable enhanced UI controls (default: false)
+  hideLoadingIndicator?: boolean; // Hide the built-in loading spinner (default: false)
   lowLatencyMode?: boolean; // Enable low-latency mode for live streams (default: false)
   driftToleranceMs?: number; // Drift tolerance for live streams (default: 1000)
   immediateManifestAds?: boolean; // Load ads immediately from manifest (default: true)
@@ -360,10 +367,15 @@ interface StormcloudVideoPlayerConfig {
   adFailsafeTimeoutMs?: number; // Ad timeout in milliseconds (default: 10000)
   minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
 
+  // Ad break timing
+  adBreakCheckIntervalMs?: number; // Interval used to re-check an active ad break (default: 1000, min: 250)
+  maxAdBreakExtensionMs?: number; // Max time an ad break may be extended past its SCTE-35 duration when ads are still playing/queued (default: 60000)
+
   // Ad configuration
-  vastMode?: 'adstorm' | 'default'; // VAST mode (default: 'default')
-  vastTagUrl?: string; // Custom VAST tag URL (if provided)
-  prebid?: PrebidConfig; // Prebid Server configuration for ad auctions
+  vastMode?: 'adstorm' | 'default'; // VAST mode: 'adstorm' (uses HLS player + AdStorm VAST endpoint) or 'default' (uses Google IMA SDK + /ads/web endpoint) (default: 'default')
+  vastTagUrl?: string; // Custom VAST tag URL (used in default mode if provided; when not provided, defaults to /ads/web endpoint)
+  vmapUrl?: string; // Optional VMAP 1.0 manifest URL used to schedule pre/mid/post-roll ad breaks
+  adPlayerType?: 'ima' | 'hls'; // Manual override for ad player type (auto-determined by vastMode/browser if not specified)
 
   onVolumeToggle?: () => void; // Callback for volume toggle
   onFullscreenToggle?: () => void; // Callback for fullscreen toggle
@@ -446,7 +458,7 @@ const player = new StormcloudVideoPlayer({
 ```
 
 **What happens:**
-- 🎯 Ad playback via Prebid Controller
+- 🎯 Automatically uses HLS ad player (`adPlayerType: 'hls'`)
 - 🔗 VAST endpoint: `GET https://adstorm.co/api-adstorm-dev/adstorm/vast/{licenseKey}`
   - License key is passed in the URL path (no authorization header needed)
   - Returns VAST XML directly with HLS media files
@@ -460,7 +472,7 @@ const player = new StormcloudVideoPlayer({
 4. HLS ad player loads and plays the ad segments
 
 **Benefits:**
-- ✅ Zero external ad SDK dependencies (Prebid Server only)
+- ✅ Zero external dependencies (no Google IMA SDK)
 - ✅ Full control over ad serving
 - ✅ Native HLS playback (same format as content)
 - ✅ Better performance and reliability
@@ -469,7 +481,7 @@ const player = new StormcloudVideoPlayer({
 
 #### 2. **Default Mode**
 
-Ad playback uses Prebid Server for VAST ads:
+Uses Google IMA SDK for traditional ad serving:
 
 ```javascript
 const player = new StormcloudVideoPlayer({
@@ -477,7 +489,7 @@ const player = new StormcloudVideoPlayer({
   src: "https://your-stream.com/playlist.m3u8",
   licenseKey: "your-license-key",
 
-  // Uses Prebid Controller for ad playback
+  // Default mode - uses Google IMA SDK automatically
   vastMode: 'default', // or omit this property entirely
   vastTagUrl: 'https://your-vast-server.com/vast.xml', // optional
 
@@ -486,20 +498,20 @@ const player = new StormcloudVideoPlayer({
 ```
 
 **What happens:**
-- 🎯 Ad playback via Prebid Controller
+- 🎯 Automatically uses Google IMA SDK (`adPlayerType: 'ima'`)
 - 🔗 VAST endpoint resolution:
   1. If `vastTagUrl` is provided, uses that URL directly
   2. Otherwise, calls `GET https://adstorm.co/api-adstorm-dev/adstorm/ads/web`
      - Requires `Authorization: Bearer {licenseKey}` header
-     - Returns VAST URLs from your ad backend
+     - Returns JSON response with IMA payload: `{ response: { ima: { "publisherdesk.ima": { payload: "VAST_URL" } } } }`
      - Extracts VAST tag URL from the `payload` field
-- 📊 VAST ad serving through Prebid Server
+- 📊 Standard VAST/VPAID ad serving through Google IMA SDK
 
 **API Flow:**
 1. Player calls `/ads/web` endpoint with Bearer token (if no `vastTagUrl` provided)
-2. Backend or Prebid Server provides VAST URLs
+2. Backend returns JSON with IMA configuration
 3. Player extracts VAST tag URL from `response.ima["publisherdesk.ima"].payload`
-4. Prebid Controller loads and plays the VAST ad
+4. Google IMA SDK loads and plays the VAST ad
 
 **Benefits:**
 - ✅ Industry-standard ad serving
@@ -508,186 +520,6 @@ const player = new StormcloudVideoPlayer({
 - ✅ Backward compatible with existing VAST tags
 - ✅ Supports both custom VAST URLs and AdStorm backend
 
-#### 3. **Prebid Mode** (Server-Side Header Bidding)
-
-Uses Prebid Server for server-side header bidding auctions. The player sends OpenRTB requests directly to a Prebid Server instance, receives bid responses with VAST creatives, and plays the winning ad — all without any external SDK.
-
-**Vanilla JavaScript:**
-
-```javascript
-const player = new StormcloudVideoPlayer({
-  videoElement: video,
-  src: "https://your-stream.com/playlist.m3u8",
-  licenseKey: "your-license-key",
-
-  prebid: { /* PrebidConfig */ },
-  prebid: {
-    enabled: true,
-    serverUrl: "https://prebid-server.example.com",
-    timeout: 3000,
-    debug: true,
-    cpmFloor: 0.50,
-    ortbRequest: {
-      id: "my-video-player",
-      imp: [
-        {
-          id: "video-imp-1",
-          video: {
-            w: 640,
-            h: 480,
-            mimes: ["video/mp4", "application/x-mpegURL"],
-            protocols: [2, 5],
-            minduration: 5,
-            maxduration: 60,
-            linearity: 1,
-            playbackmethod: [1, 2],
-          },
-          ext: {
-            prebid: {
-              bidder: {
-                appnexus: { placement_id: 12345 },
-                rubicon: { account_id: 1001, site_id: 2002, zone_id: 3003 },
-              },
-            },
-          },
-        },
-      ],
-      tmax: 3000,
-      site: {
-        domain: "example.com",
-        page: "https://example.com/video-page",
-      },
-    },
-  },
-
-  debugAdTiming: true,
-});
-
-await player.load();
-```
-
-**CDN Usage:**
-
-```html
-<video id="video" style="width:100%;aspect-ratio:16/9"></video>
-
-<script src="https://cdn.jsdelivr.net/npm/stormcloud-video-player/dist/stormcloud-vp.min.js"></script>
-<script>
-  var StormcloudVideoPlayer = window.StormcloudVP.StormcloudVideoPlayer;
-
-  var video = document.getElementById("video");
-
-  var player = new StormcloudVideoPlayer({
-    videoElement: video,
-    src: "https://your-stream.com/playlist.m3u8",
-    autoplay: true,
-    muted: true,
-    licenseKey: "your-license-key",
-
-    prebid: {
-      enabled: true,
-      serverUrl: "https://prebid-server.example.com",
-      timeout: 3000,
-      debug: true,
-      cpmFloor: 0.50,
-      ortbRequest: {
-        id: "my-video-player",
-        imp: [
-          {
-            id: "video-imp-1",
-            video: {
-              w: 640,
-              h: 480,
-              mimes: ["video/mp4", "application/x-mpegURL"],
-              protocols: [2, 5],
-              minduration: 5,
-              maxduration: 60,
-              linearity: 1,
-              playbackmethod: [1, 2],
-            },
-            ext: {
-              prebid: {
-                bidder: {
-                  appnexus: { placement_id: 12345 },
-                },
-              },
-            },
-          },
-        ],
-        tmax: 3000,
-      },
-    },
-
-    debugAdTiming: true,
-  });
-
-  player.load();
-</script>
-```
-
-**What happens:**
-- Sends OpenRTB 2.5 auction requests directly to your Prebid Server
-- Receives bid responses with VAST URLs (cached via Prebid Server) or inline VAST XML
-- Automatically selects the highest-CPM winning bid
-- Enforces CPM floor pricing (bids below the floor are rejected)
-- Plays the winning ad creative natively (MP4 or HLS)
-- Fires all VAST tracking events (impression, quartiles, complete, error, pause/resume, mute/unmute)
-
-**Auction Flow:**
-1. Player builds an OpenRTB request with device/site info auto-populated from the browser
-2. Request is sent to `{serverUrl}/openrtb2/auction` via POST
-3. Prebid Server runs the server-side auction across all configured bidders
-4. Player parses the response, selects the highest-CPM bid
-5. VAST creative (cached URL or inline XML) is loaded and played
-
-**Benefits:**
-- Zero external SDK dependencies (no Google IMA, no Prebid.js client-side library)
-- Full server-side auction — lower client-side resource usage
-- Support for any Prebid Server bidder (AppNexus, Rubicon, Index Exchange, etc.)
-- CPM floor enforcement on the client side
-- Native VAST ad playback with full tracking support
-- Works on all platforms including Smart TVs and legacy browsers
-- Complete OpenRTB 2.5 compliance
-
-### PrebidConfig Reference
-
-```typescript
-interface PrebidConfig {
-  enabled?: boolean;       // Enable/disable prebid (default: true)
-  serverUrl?: string;      // Prebid Server URL (e.g. "https://prebid-server.example.com")
-  ortbRequest: {           // OpenRTB 2.5 request template
-    id: string;            // Request ID (will be made unique per auction)
-    imp: [{                // Impression objects (at least one required)
-      id: string;
-      video?: {
-        w?: number;        // Video width
-        h?: number;        // Video height
-        mimes?: string[];  // Supported MIME types
-        protocols?: number[];
-        minduration?: number;
-        maxduration?: number;
-        linearity?: number;
-        playbackmethod?: number[];
-      };
-      ext?: {
-        prebid?: {
-          bidder: {        // Bidder configurations
-            [bidderName: string]: Record<string, any>;
-          };
-        };
-      };
-    }];
-    tmax?: number;         // Auction timeout in ms (default: 3000)
-    site?: Record<string, any>;   // Auto-populated from window.location if omitted
-    device?: Record<string, any>; // Auto-populated from navigator if omitted
-    ext?: Record<string, any>;
-  };
-  timeout?: number;        // Client-side fetch timeout in ms (default: 3000)
-  debug?: boolean;         // Enable debug logging (default: false)
-  cpmFloor?: number;       // Minimum CPM to accept a bid (default: 0, accepts all)
-}
-```
-
 ### Ad Pod Generation (Multiple Consecutive Ads)
 
 The player automatically generates **ad pods** (multiple ads played consecutively) from a single VAST URL. This works differently for VOD and live streams:
@@ -806,6 +638,94 @@ Final: 3 ads played (perfectly fills 120 seconds)
 - ✅ **Smart**: Improves calculation as more data is gathered (uses average of fetched durations)
 - ✅ **Self-Correcting**: Automatically adjusts if actual ad lengths differ from expectations
 
+### VMAP Ad Break Scheduling
+
+In addition to SCTE-35 markers and continuous-ad-fetch, the player supports **VMAP 1.0** manifests for scheduling ad breaks at specific positions in the timeline. This is ideal for VOD content where you want to declaratively define pre-roll, mid-roll, and post-roll breaks with explicit time offsets.
+
+#### Usage
+
+Provide a `vmapUrl` in addition to (or instead of) a VAST/AdStorm configuration:
+
+```javascript
+const player = new StormcloudVideoPlayer({
+  videoElement: video,
+  src: "https://your-stream.com/video.m3u8",
+  licenseKey: "your-license-key",
+
+  vastMode: 'default',
+  vmapUrl: 'https://your-cdn.com/schedule.vmap', // VMAP 1.0 manifest
+
+  debugAdTiming: true,
+});
+```
+
+Or with React:
+
+```jsx
+<StormcloudPlayer
+  src="https://your-stream.com/video.m3u8"
+  licenseKey="your-license-key"
+  vmapUrl="https://your-cdn.com/schedule.vmap"
+  playing={true}
+/>
+```
+
+#### Supported `timeOffset` Formats
+
+The VMAP parser recognizes all standard `timeOffset` values:
+
+| Value                 | Meaning                                              |
+| --------------------- | ---------------------------------------------------- |
+| `start`               | Pre-roll (playback position 0)                       |
+| `end`                 | Post-roll (resolved at runtime using media duration) |
+| `HH:MM:SS` / `HH:MM:SS.mmm` | Absolute timestamp mid-roll                    |
+| `NN%`                 | Percentage of media duration (resolved at runtime)   |
+
+#### Example VMAP Manifest
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<vmap:VMAP xmlns:vmap="http://www.iab.net/videosuite/vmap" version="1.0">
+  <vmap:AdBreak timeOffset="start" breakType="linear" breakId="preroll">
+    <vmap:AdSource>
+      <vmap:AdTagURI templateType="vast3">
+        <![CDATA[https://your-ad-server.com/vast?position=preroll]]>
+      </vmap:AdTagURI>
+    </vmap:AdSource>
+  </vmap:AdBreak>
+
+  <vmap:AdBreak timeOffset="00:05:00" breakType="linear" breakId="midroll-1">
+    <vmap:AdSource>
+      <vmap:AdTagURI templateType="vast3">
+        <![CDATA[https://your-ad-server.com/vast?position=midroll-1]]>
+      </vmap:AdTagURI>
+    </vmap:AdSource>
+  </vmap:AdBreak>
+
+  <vmap:AdBreak timeOffset="end" breakType="linear" breakId="postroll">
+    <vmap:AdSource>
+      <vmap:AdTagURI templateType="vast3">
+        <![CDATA[https://your-ad-server.com/vast?position=postroll]]>
+      </vmap:AdTagURI>
+    </vmap:AdSource>
+  </vmap:AdBreak>
+</vmap:VMAP>
+```
+
+#### How It Works
+
+1. The player fetches the VMAP manifest on load (before playback starts).
+2. Each `<AdBreak>` is parsed into an `AdBreak` object with a resolved `startTimeMs` and the associated `vastTagUrl` from `<AdTagURI>`.
+3. During playback, the player matches the current time against each scheduled break and triggers the ad request at the correct offset.
+4. **Mid-roll join behavior**: If the viewer joins mid-stream and has already passed a scheduled break, the player will honor the configured late-join policy (e.g., play the remaining portion or skip to content).
+5. Each break is only consumed once per session to avoid replaying breaks after seeking.
+
+**Benefits:**
+- ✅ Declarative ad scheduling — no custom code needed per break
+- ✅ Works alongside `vastMode: 'adstorm'` and `vastMode: 'default'`
+- ✅ Supports pre-roll, mid-roll, percentage-based, and post-roll breaks
+- ✅ Gracefully handles malformed XML and fetch failures (logged when `debugAdTiming` is enabled)
+
 ### Manual Ad Player Override
 
 You can still manually override the ad player type if needed:
@@ -816,13 +736,16 @@ const player = new StormcloudVideoPlayer({
   src: "https://your-stream.com/playlist.m3u8",
 
   vastMode: 'default',
-  vastTagUrl: 'https://your-backend.com/vast', // Optional custom VAST URL
+  adPlayerType: 'hls', // Manual override to use HLS player with default mode
+  vastTagUrl: 'https://your-backend.com/vast', // Will use this URL directly
 
   debugAdTiming: true,
 });
 ```
 
-**Note:** The player uses Prebid Controller for ad playback. Provide `prebid` config for Prebid Server auctions.
+**Note:** When `adPlayerType` is manually set, the `vastMode` property still determines which backend endpoint is called:
+- `vastMode: 'adstorm'` → Always calls `/vast/{licenseKey}` endpoint
+- `vastMode: 'default'` → Calls `/ads/web` endpoint (unless `vastTagUrl` is provided)
 
 ### SCTE-35 Support
 
@@ -996,11 +919,57 @@ Authenticated requests are sent to:
   
 - **Default Mode** (`vastMode: 'default'`):
   - Ad configuration: `GET https://adstorm.co/api-adstorm-dev/adstorm/ads/web` (requires `Authorization: Bearer {licenseKey}` header)
-  - Returns VAST tag URL or Prebid Server provides creatives
+  - Returns JSON with IMA payload containing VAST tag URL
 
 - **Player Tracking** (both modes):
   - Player tracking: `POST https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/track` (requires `Authorization: Bearer {licenseKey}` header)
   - Heartbeat monitoring: `POST https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/heartbeat` (requires `Authorization: Bearer {licenseKey}` header)
+  - Ad-detect, ad-loaded, and ad-impression events are automatically emitted during ad breaks.
+
+### Tracking Utilities
+
+The player exposes low-level tracking helpers if you want to fire events manually or build custom analytics:
+
+```javascript
+import {
+  getClientInfo,
+  getBrowserID,
+  sendInitialTracking,
+  sendHeartbeat,
+  sendAdDetectTracking,
+  sendAdLoadedTracking,
+  sendAdImpressionTracking,
+} from "stormcloud-video-player";
+
+const clientInfo = getClientInfo();
+const browserId = getBrowserID();
+
+await sendInitialTracking(licenseKey, clientInfo);
+await sendHeartbeat(licenseKey, { browserId, timestamp: new Date().toISOString() });
+
+// Ad lifecycle tracking
+await sendAdDetectTracking(licenseKey, {
+  source: "scte35",
+  durationSeconds: 30,
+  ptsSeconds: 120.5,
+  detectedAtFragmentSn: 1234,
+  timestamp: new Date().toISOString(),
+});
+
+await sendAdLoadedTracking(licenseKey, {
+  source: "ima", // 'prebid' | 'ima' | 'hls'
+  vastUrl: "https://...",
+  durationSeconds: 15,
+  timestamp: new Date().toISOString(),
+});
+
+await sendAdImpressionTracking(licenseKey, {
+  source: "ima",
+  adIndex: 0,
+  durationSeconds: 15,
+  timestamp: new Date().toISOString(),
+});
+```
 
 ## 🔧 Advanced Configuration
 
@@ -1109,11 +1078,74 @@ console.log("Supports PIP:", canPIP); // true for file player
 />
 ```
 
-## 🌐 Browser Support
+## 🌐 Browser & Smart TV Support
 
 - **Desktop**: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
 - **Mobile**: iOS Safari 12+, Chrome Mobile 60+
-- **Smart TV**: WebOS, Tizen, Android TV, Roku, Apple TV
+- **Smart TV**: LG WebOS (v2+), Samsung Tizen (v2+), Sony BRAVIA, Android TV, Roku, Apple TV, generic Smart TV user-agents
+
+### Automatic Browser Detection & Ad Player Selection
+
+The player automatically detects the runtime environment and chooses the optimal ad-player configuration. This is especially useful for Smart TVs where the Google IMA SDK may not be available on older devices.
+
+```javascript
+import {
+  detectBrowser,
+  supportsGoogleIMA,
+  getRecommendedAdPlayer,
+  supportsModernJS,
+  logBrowserInfo,
+  getBrowserConfigOverrides,
+  supportsFeature,
+} from "stormcloud-video-player";
+
+const info = detectBrowser();
+// {
+//   name: 'LG WebOS',
+//   version: '5.0',
+//   majorVersion: 5,
+//   isSmartTV: true,
+//   isLegacyTV: false,
+//   supportsIMA: true,
+//   supportsModernJS: true,
+//   recommendedAdPlayer: 'ima',
+//   webOSVersion: 5,
+//   chromeVersion: 79,
+//   ...
+// }
+
+console.log(supportsGoogleIMA());   // true | false
+console.log(getRecommendedAdPlayer()); // 'ima' | 'hls'
+console.log(supportsFeature('fetch')); // true | false
+```
+
+**What happens automatically:**
+
+- **Legacy Smart TVs** (LG NetCast, old WebOS < 3, old Tizen): `adPlayerType` is forced to `'hls'` and `allowNativeHls` is enabled.
+- **Modern Smart TVs**: `allowNativeHls` is enabled by default (TVs generally play HLS better natively).
+- **If IMA SDK is unsupported**: the player falls back to the HLS ad player automatically.
+- **Browser overrides** are merged with your config — user-provided options always take precedence.
+
+Call `logBrowserInfo(true)` (or enable `debugAdTiming`) to print a detailed compatibility report to the console.
+
+### Automatic Polyfills for Legacy Devices
+
+On older Smart TVs and browsers, `initializePolyfills()` is invoked automatically at construction time. It adds missing primitives needed for the player to run:
+
+- `URLSearchParams`
+- `TextEncoder`
+- `Promise.prototype.finally`
+- `Object.assign`
+- `Array.from`
+- `String.prototype.startsWith` / `endsWith` / `includes`
+
+You can also run it manually before bootstrapping anything else:
+
+```javascript
+import { initializePolyfills } from "stormcloud-video-player";
+
+initializePolyfills();
+```
 
 ### Format Support by Player
 
@@ -1162,18 +1194,19 @@ src/
 │   ├── HlsPlayer.tsx                  # HLS stream handler
 │   └── FilePlayer.tsx                 # Regular video handler
 ├── player/
-│   └── StormcloudVideoPlayer.ts       # Core player class
+│   └── StormcloudVideoPlayer.ts       # Core player class (SCTE-35, VMAP, ad pods)
 ├── ui/
 │   └── StormcloudVideoPlayer.tsx      # Legacy React component
 ├── sdk/
-│   ├── prebid.ts                      # Prebid Server auction manager
-│   ├── prebidController.ts            # Prebid ad controller (VAST playback + tracking)
-│   └── vastParser.ts                  # VAST XML parser
+│   ├── ima.ts                         # Google IMA integration
+│   └── hlsAdPlayer.ts                 # Native HLS ad player (AdStorm mode, legacy TVs)
 ├── utils/
-│   ├── tracking.ts                    # Analytics and tracking
-│   └── index.ts                       # Utility functions
+│   ├── tracking.ts                    # Analytics and ad tracking
+│   ├── browserCompat.ts               # Browser / Smart TV detection & auto-overrides
+│   └── polyfills.ts                   # Legacy browser polyfills
 ├── props.ts                           # Centralized props system
 ├── patterns.ts                        # URL pattern matching
+├── utils.ts                           # Shared utilities
 └── types.ts                           # TypeScript definitions
 ```
 
@@ -1288,14 +1321,19 @@ Built with ❤️ by the Stormcloud team
 
 ### What's New in v0.5
 
-- **Prebid Server Integration**: Server-side header bidding via Prebid Server (OpenRTB 2.5)
-- **Zero-SDK Ad Auctions**: Run server-side auctions across multiple bidders (AppNexus, Rubicon, Index Exchange, etc.) without any client-side ad SDK
-- **PrebidConfig**: Full OpenRTB 2.5 request configuration with auto-populated device/site fields
-- **CPM Floor Enforcement**: Client-side floor pricing to reject bids below a minimum CPM threshold
-- **Native VAST Playback**: Winning bid creatives (cached VAST URL or inline VAST XML) played natively with full tracking (impression, quartiles, complete, pause/resume, mute/unmute, error)
-- **Smart Media Selection**: Automatic selection of the best ad media file based on the main stream's current resolution and bitrate
-- **HLS Ad Creatives**: Support for HLS-format ad creatives alongside MP4, with automatic format detection
-- **CDN-Ready**: Full prebid support available via CDN (`window.StormcloudVP.StormcloudVideoPlayer`) with no build step required
+- 🗓️ **VMAP 1.0 Support**: New `vmapUrl` config/prop loads a VMAP manifest and schedules pre-roll, mid-roll, percentage-based, and post-roll breaks automatically
+  - Supports `start`, `end`, `HH:MM:SS[.mmm]`, and `NN%` `timeOffset` values
+  - Namespaced (`vmap:AdBreak`) and non-namespaced manifests both supported
+  - Breaks are consumed-once-per-session and integrate with the existing late-join policy
+- 📺 **Smart TV First-Class Support**: New browser-compat layer auto-detects LG WebOS, Samsung Tizen, Sony BRAVIA, LG NetCast and generic Smart TV UAs
+  - Exports `detectBrowser`, `supportsGoogleIMA`, `getRecommendedAdPlayer`, `supportsModernJS`, `logBrowserInfo`, `getBrowserConfigOverrides`, `supportsFeature`
+  - Automatically forces HLS ad player on legacy TVs where IMA SDK is not available
+  - Automatically enables `allowNativeHls` on Smart TVs for more reliable playback
+- 🧩 **Automatic Polyfills**: `initializePolyfills()` runs at construction time and backfills `URLSearchParams`, `TextEncoder`, `Promise.prototype.finally`, `Object.assign`, `Array.from`, and `String.prototype.startsWith/endsWith/includes` for legacy environments
+- 📊 **Expanded Ad Tracking**: New `sendAdDetectTracking`, `sendAdLoadedTracking`, and `sendAdImpressionTracking` helpers (plus `AdDetectInfo`, `AdLoadedInfo`, `AdImpressionInfo`, and `AdTrackingSource` types) for prebid/IMA/HLS ad lifecycle events
+- ⚙️ **Ad-Break Timing Controls**: New `adBreakCheckIntervalMs` (default 1000ms, min 250ms) and `maxAdBreakExtensionMs` (default 60000ms) options give you precise control over how long the player is allowed to extend an ad break past its SCTE-35 duration when ads are still playing or queued
+- 🙈 **Hide Loading Indicator**: New `hideLoadingIndicator` prop/config hides the built-in buffering spinner when you want to render your own overlay
+- 🔌 **Expanded Public API**: `createImaController`, `createHlsAdPlayer`, and `initializePolyfills` are now exported alongside the new browser-compat utilities, making it easier to build custom integrations on top of the player core
 
 ### What's New in v0.4
 
@@ -1320,14 +1358,17 @@ Built with ❤️ by the Stormcloud team
 
 ### What's New in v0.3
 
-- 🎬 **Prebid Ad Controller**: VAST ad playback via Prebid Server
-- 🎯 **Ad Integration**: Prebid Server for server-side header bidding
+- 🎬 **Custom HLS Ad Player**: Native HLS ad playback with custom VAST service
+- 🎯 **Flexible Ad Integration**: Choose between custom HLS or Google IMA SDK
 - 📊 **Direct Analytics**: Full control over ad tracking and metrics
-- ⚡ **Better Performance**: Native VAST playback for ads
+- ⚡ **Better Performance**: Native HLS playback for ads (same format as content)
 - 🔧 **Custom VAST URLs**: Point to your own ad serving backend
-- 📦 **Zero Dependencies**: No external ad SDKs (Prebid Server only)
+- 🔄 **Backward Compatible**: Existing Google IMA integration still works
+- 📦 **Zero Dependencies**: No external ad SDKs required (when using HLS ad player)
 - 🎨 **Seamless Playback**: Same player for content and ads
-- 🔀 **VAST Mode**: `vastMode` property for endpoint configuration
+- 🔀 **VAST Mode System**: `vastMode` property automatically configures endpoints and ad players
+  - `vastMode: 'adstorm'` → Uses `/vast/{licenseKey}` endpoint with HLS ad player
+  - `vastMode: 'default'` → Uses `/ads/web` endpoint with Google IMA SDK
 - ⚠️ **Improved Error Handling**: Distinguishes between parsing errors and "no ads available" scenarios
   - Logs warnings for "no ads available" (graceful handling)
   - Logs errors for actual parsing/fetch failures