@dolby-optiview/ads-sdk-core 1.0.0-beta.1

package/dist/id3/parseId3Geob.js

@@ -0,0 +1 @@
+export function parseId3GeobFrames(e){const n=[];if(e.length<10||73!==e[0]||68!==e[1]||51!==e[2])return n;const r=e[3],f=e[5],c=Math.min(10+u(e,6),e.length);let a=10;for(64&f&&(a+=function(e,n,t){return n+4>e.length?0:t>=4?u(e,n):4+o(e,n)}(e,a,r));a+10<=c&&0!==e[a];){const f=t(e.subarray(a,a+4)),d=r>=4?u(e,a+4):o(e,a+4),l=a+10;if(d<=0||l+d>c)break;if("GEOB"===f){const t=parseId3GeobBody(e.subarray(l,l+d));t&&n.push(t)}a=l+d}return n}export function parseId3GeobBody(r){if(r.length<1)return null;const u=r[0],o=e(r,1,0);if(!o)return null;const f=e(r,o.next,u);if(!f)return null;const c=e(r,f.next,u);return c?{mimeType:t(r.subarray(1,o.end)),fileName:n(r.subarray(o.next,f.end),u),description:n(r.subarray(f.next,c.end),u),data:r.subarray(c.next)}:null}function e(e,n,t){if(!(1===t||2===t)){for(let t=n;t<e.length;t++)if(0===e[t])return{end:t,next:t+1};return null}for(let t=n;t+1<e.length;t+=2)if(0===e[t]&&0===e[t+1])return{end:t,next:t+2};return null}function n(e,n){switch(n){case 0:return t(e);case 1:return r(e,!1);case 2:return r(e,!0);default:return decodeUtf8(e)}}export function decodeUtf8(e){return new TextDecoder("utf-8").decode(e)}function t(e){let n="";for(let t=0;t<e.length;t++)n+=String.fromCharCode(e[t]);return n}function r(e,n){return e.length>=2&&255===e[0]&&254===e[1]?new TextDecoder("utf-16le").decode(e.subarray(2)):e.length>=2&&254===e[0]&&255===e[1]?new TextDecoder("utf-16be").decode(e.subarray(2)):new TextDecoder(n?"utf-16be":"utf-16le").decode(e)}function u(e,n){return(127&e[n])<<21|(127&e[n+1])<<14|(127&e[n+2])<<7|127&e[n+3]}function o(e,n){return(e[n]<<24|e[n+1]<<16|e[n+2]<<8|e[n+3])>>>0}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+export { OptiViewAds } from './OptiViewAds';
+export type { PlayerAdapter, PlayerAdapterEvent, PlayerAdapterEventHandler, TimedMetadataCue, VideoQuality, } from './interfaces/PlayerAdapter';
+export type { BreakManifest, Break, BreakPosition, EventTrigger, BreakVariant, SingleBreakVariant, DoubleBreakVariant, LshapeAdBreakVariant, LshapeContentBreakVariant, OverlayBreakVariant, AssetWithCompanion, OverlayPosition, OverlaySize, Asset, StaticAsset, VastAsset, VendorAsset, Polling, Controls, Targeting, Interaction, AssetUri, DeliveryRule, VendorConfiguration, VendorConfigurationBase, GamVendorConfiguration, GamSgaiConfiguration, GamSsaiConfiguration, } from './types/BreakManifest';
+export { BreakFormat, AssetType, MediaType, Vendor, Timebase, DeviceType, DeliveryMode, BreakEvent, } from './types/BreakManifest';
+export { isStaticAsset, isVastAsset, isVendorAsset, isGamVendorConfiguration, isEventTrigger, isPauseBreak, } from './types/BreakManifest';
+export { resolveDeliveryMode, resolveStitchedStreamVendor, SsaiUnavailableError, } from './services/resolveDeliveryMode';
+export type { DeliveryModeDecision } from './services/resolveDeliveryMode';
+export type { StitchedStreamVendor } from './services/resolveDeliveryMode';
+export type { OptiViewAdsConfig, OptiViewAdsMode, PtsSource, GamConfig, SessionConfig, SsaiSessionConfig, StartSessionConfig, CreateAdAdapter, AdPreloadMode, AdInsertionMode, AdInsertionType, SsaiConfig, DoubleBoxAudio, ChainingConfig, ResolvedChaining, TuneInConfig, ResolvedTuneIn, ManifestResponseInterceptor, ManifestInterceptContext, ManifestRequestInterceptor, ManifestRequestContext, ManifestRequest, ManifestMockResponse, ManifestRequestInterceptorResult, } from './types/OptiViewAdsConfig';
+export { DEFAULT_MODE, DEFAULT_AD_PRELOAD_MODE, DEFAULT_AD_INSERTION_MODE, DEFAULT_CHAINING, resolveChaining, DEFAULT_TUNE_IN, resolveTuneIn, DEFAULT_PDT_GRACE_SECONDS, resolvePdtGraceSeconds, } from './types/OptiViewAdsConfig';
+export type { StitcherMasterUrlParams } from './services/StitcherUrlBuilder';
+export { buildStitcherMasterUrl } from './services/StitcherUrlBuilder';
+export type { GamStreamConfig, GamAdEventCallbacks } from './services/GamStreamManager';
+export { GamStreamManager } from './services/GamStreamManager';
+export type { AssetParameterMacro, AssetParameterMacroValue, AssetParameterMacros, } from './services/assetParameterMacros';
+export { OPTIVIEW_ASSET_PARAMETER_MACROS } from './services/assetParameterMacros';
+export type { VastAdCallbacks } from './services/VastAdManager';
+export { VastAdManager, isImaCsaiSdkAvailable } from './services/VastAdManager';
+export type { SsaiControllerOptions, SsaiControllerCallbacks } from './services/SsaiController';
+export { SsaiController } from './services/SsaiController';
+export type { ResolvedPreloadMode } from './services/detectPreloadMode';
+export { resolvePreloadMode, isSingleDecoderUserAgent } from './services/detectPreloadMode';
+export type { ResolvedInsertionMode, MediaSourceCapabilities, } from './services/detectInsertionMode';
+export { resolveInsertionMode, isSharedElementUserAgent, detectMediaSourceCapabilities, } from './services/detectInsertionMode';
+export type { Clock, TuneInOptions, BreakStartContext } from './services/BreakScheduler';
+export { systemClock } from './services/BreakScheduler';
+export { MetadataCueTracker, isAnvatoCue, isId3InEmsgScheme, anvatoPayloadFromCue, parseAnvatoPayload, ANVATO_ID3_DESCRIPTION, ANVATO_ID3_MIME_TYPE, ANVATO_EMSG_SCHEME_ID_URI, ID3_IN_EMSG_SCHEME_ID_URIS, PTS_MATCH_TOLERANCE_SECONDS, } from './services/MetadataCueTracker';
+export type { PauseAdResolution, PauseAdShowCallback, PauseAdHideCallback, PauseAdDiagnoseCallback, } from './services/PauseAdController';
+export { PauseAdController } from './services/PauseAdController';
+export type { VastCompanionImage } from './services/parseVastCompanion';
+export { parseVastCompanionImage } from './services/parseVastCompanion';
+export type { EffectiveInsertionMode, AdBreakStep, AdBreakAction, AdBreakOutcome, AdBreakTransition, NoPlayableAssetReason, NoPlayableAssetNotice, ChainResolver, } from './services/AdBreakSequencer';
+export { AdBreakSequencer, selectVariant, extractAssets, assetsOfVariant, resolveBreakFormat, breakPlanEmptyReason, } from './services/AdBreakSequencer';
+export type { VariantSelectionInputs, VariantSelection } from './services/selectVariant';
+export { selectVariantDetailed, playableFormatsFor, variantsOf, RENDERABLE_BREAK_FORMATS, KNOWN_BREAK_FORMATS, } from './services/selectVariant';
+export type { GamPodAdInfo, GamPodAdStep, GamPodCurrentAd } from './services/GamPodAdTracker';
+export { GamPodAdTracker, derivePodAdAsset } from './services/GamPodAdTracker';
+export type { DiagnosticEvent, DiagnosticHandler, DiagnosticReport, ConfigSummary, DiagnosticCategory, DiagnosticLevel, DiagnosticCodeInfo, KnownDiagnosticCode, } from './diagnostics';
+export { DIAGNOSTIC_CODES, getDiagnosticCodeInfo, DiagnosticBuffer, DEFAULT_DIAGNOSTIC_BUFFER_SIZE, SDK_VERSION, } from './diagnostics';
+export type { DiagnosticsConfig, BreakWarningsConfig } from './types/OptiViewAdsConfig';
+export { parseBreakManifest, SUPPORTED_MANIFEST_MAJOR_VERSION, } from './services/parseBreakManifest';
+export { fetchWithTimeout, AUX_FETCH_TIMEOUT_MS } from './services/fetchWithTimeout';
+export type { GamVendorParameters } from './services/GamPodUrlBuilder';
+export { buildGamPodUrl, isGamVendorParameters } from './services/GamPodUrlBuilder';
+export type { OptiViewAdsEventType, OptiViewAdsEventHandler, OptiViewAdsEventMap, OptiViewAdsEvent, AdBreakBeginEvent, AdBreakEndEvent, AdBeginEvent, AdEndEvent, AdErrorEvent, AdFirstQuartileEvent, AdMidpointEvent, AdThirdQuartileEvent, AdTimeupdateEvent, WaitingEvent, PlayingEvent, VolumeChangeEvent, AdClickEvent, PlaybackSource, AdBreakPhase, AdBreakStatus, AdBreakStatusEvent, AdChannelChangeEvent, AdChannelChangeReason, } from './types/Events';

package/dist/index.js

@@ -0,0 +1 @@
+export{OptiViewAds}from"./OptiViewAds";export{BreakFormat,AssetType,MediaType,Vendor,Timebase,DeviceType,DeliveryMode,BreakEvent}from"./types/BreakManifest";export{isStaticAsset,isVastAsset,isVendorAsset,isGamVendorConfiguration,isEventTrigger,isPauseBreak}from"./types/BreakManifest";export{resolveDeliveryMode,resolveStitchedStreamVendor,SsaiUnavailableError}from"./services/resolveDeliveryMode";export{DEFAULT_MODE,DEFAULT_AD_PRELOAD_MODE,DEFAULT_AD_INSERTION_MODE,DEFAULT_CHAINING,resolveChaining,DEFAULT_TUNE_IN,resolveTuneIn,DEFAULT_PDT_GRACE_SECONDS,resolvePdtGraceSeconds}from"./types/OptiViewAdsConfig";export{buildStitcherMasterUrl}from"./services/StitcherUrlBuilder";export{GamStreamManager}from"./services/GamStreamManager";export{OPTIVIEW_ASSET_PARAMETER_MACROS}from"./services/assetParameterMacros";export{VastAdManager,isImaCsaiSdkAvailable}from"./services/VastAdManager";export{SsaiController}from"./services/SsaiController";export{resolvePreloadMode,isSingleDecoderUserAgent}from"./services/detectPreloadMode";export{resolveInsertionMode,isSharedElementUserAgent,detectMediaSourceCapabilities}from"./services/detectInsertionMode";export{systemClock}from"./services/BreakScheduler";export{MetadataCueTracker,isAnvatoCue,isId3InEmsgScheme,anvatoPayloadFromCue,parseAnvatoPayload,ANVATO_ID3_DESCRIPTION,ANVATO_ID3_MIME_TYPE,ANVATO_EMSG_SCHEME_ID_URI,ID3_IN_EMSG_SCHEME_ID_URIS,PTS_MATCH_TOLERANCE_SECONDS}from"./services/MetadataCueTracker";export{PauseAdController}from"./services/PauseAdController";export{parseVastCompanionImage}from"./services/parseVastCompanion";export{AdBreakSequencer,selectVariant,extractAssets,assetsOfVariant,resolveBreakFormat,breakPlanEmptyReason}from"./services/AdBreakSequencer";export{selectVariantDetailed,playableFormatsFor,variantsOf,RENDERABLE_BREAK_FORMATS,KNOWN_BREAK_FORMATS}from"./services/selectVariant";export{GamPodAdTracker,derivePodAdAsset}from"./services/GamPodAdTracker";export{DIAGNOSTIC_CODES,getDiagnosticCodeInfo,DiagnosticBuffer,DEFAULT_DIAGNOSTIC_BUFFER_SIZE,SDK_VERSION}from"./diagnostics";export{parseBreakManifest,SUPPORTED_MANIFEST_MAJOR_VERSION}from"./services/parseBreakManifest";export{fetchWithTimeout,AUX_FETCH_TIMEOUT_MS}from"./services/fetchWithTimeout";export{buildGamPodUrl,isGamVendorParameters}from"./services/GamPodUrlBuilder";

package/dist/interfaces/PlayerAdapter.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Events a PlayerAdapter must support. `timedmetadata` is capability-style: adapters that
+ * can surface in-stream markers (HLS ID3 / EXT-X-DATERANGE, DASH emsg) emit it per marker.
+ * @category Player Integration */
+export type PlayerAdapterEvent = 'timeupdate' | 'ended' | 'error' | 'seeked' | 'volumechange' | 'waiting' | 'playing' | 'pause' | 'timedmetadata';
+/**
+ * One in-stream timed-metadata marker (payload of `timedmetadata`). Minimal, player-agnostic:
+ * - `id3`: HLS ID3 — parsed text `frames` and/or undecoded `raw` bytes.
+ * - `daterange`: HLS `EXT-X-DATERANGE` — `id` / `schemeIdUri` / `messageData`.
+ * - `emsg`: DASH/CMAF event message — `schemeIdUri` / `messageData`.
+ * @category Player Integration */
+export interface TimedMetadataCue {
+    /** Marker source type. */
+    type: 'id3' | 'daterange' | 'emsg';
+    /** Presentation time of the marker, in seconds. */
+    startTime: number;
+    /** Optional end/active-until time, in seconds. */
+    endTime?: number | undefined;
+    /** Parsed ID3 text frames keyed by frame id (e.g. `TXXX`). */
+    frames?: Record<string, string> | undefined;
+    /** ID3 frame description (e.g. GEOB `Anvatos` for Anvato break-signaling cues), when surfaced. */
+    description?: string | undefined;
+    /** ID3 GEOB MIME type (e.g. `application/json`), when surfaced. */
+    mimeType?: string | undefined;
+    /** Undecoded marker bytes (ID3/emsg), when available. */
+    raw?: Uint8Array | undefined;
+    /** Marker identifier (`EXT-X-DATERANGE` ID / emsg id). */
+    id?: string | undefined;
+    /** Scheme URI (`EXT-X-DATERANGE` scheme / emsg schemeIdUri). */
+    schemeIdUri?: string | undefined;
+    /** emsg message data, daterange client attribute, or the decoded (UTF-8) data of an ID3 GEOB frame. */
+    messageData?: string | undefined;
+    /**
+     * When the cue was delivered relative to `startTime`. `parsed` means the segment was
+     * parsed before playback reached the cue; `presented` means the playhead reached it.
+     * Omit this property when the adapter cannot distinguish the two. Marking an early
+     * parsed cue as `presented` can cause an ad break to start before its scheduled time.
+     */
+    phase?: 'parsed' | 'presented' | undefined;
+}
+/** For `timedmetadata` the payload is a {@link TimedMetadataCue}; other events are event-specific (often undefined, or a media error for `error`). @category Player Integration */
+export type PlayerAdapterEventHandler = (event?: unknown) => void;
+/** A quality selection understood by the optional adapter operation. @category Player Integration */
+export type VideoQuality = 'lowest';
+/**
+ * The abstraction layer between the SDK and any video player. The core only talks to players
+ * through this interface; each player gets its own adapter package.
+ *
+ * @example
+ * ```typescript
+ * class HlsJsAdapter implements PlayerAdapter {
+ *   constructor(private hls: Hls, private video: HTMLVideoElement) {}
+ *   // ... implement all methods
+ * }
+ * ```
+ * @category Player Integration */
+export interface PlayerAdapter {
+    /** Current playback time in seconds. */
+    readonly currentTime: number;
+    /** Content duration in seconds; may be Infinity for live streams. */
+    readonly duration: number;
+    /** Whether the player is paused. */
+    readonly paused: boolean;
+    /** Settable so the SDK can sync mute state between content and ad players. */
+    muted: boolean;
+    /** Volume in [0, 1]; settable so the SDK can sync it between content and ad players. */
+    volume: number;
+    /** Program Date Time (HLS EXT-X-PROGRAM-DATE-TIME) for wallclock break matching; null if unavailable. */
+    readonly programDateTime: Date | null;
+    /** Pause playback (called when an ad break starts). */
+    pause(): void;
+    /** Resume playback (called when an ad break ends); resolves when playback starts. */
+    play(): Promise<void>;
+    /** Seek to a time in seconds. Needed for snapback during locked breaks without touching the video element. */
+    seek(time: number): void;
+    /** Load a media source without playing; resolves when it is ready to play. Used to preload ads. */
+    load(url: string): Promise<void>;
+    /**
+     * Current content manifest URL, used to restore content after a shared-element ad.
+     * Read it from the player engine, not the element's `src` (which can be a `blob:` URL)
+     * or the last `load()` argument, since applications may load sources directly.
+     * Return `null` when unavailable; shared-element insertion is then unsupported
+     * (`DA-SHARED-ELEMENT-UNSUPPORTED`).
+     */
+    readonly sourceUrl?: string | null;
+    /**
+     * Optional: warm caches (manifest, optionally the first fragment) WITHOUT attaching media or
+     * engaging a decoder, for single-decoder Smart TVs that cannot hold two MediaSources. Must not
+     * call attachMedia(). Leave undefined if unsupported; the SDK loads on demand at break start.
+     */
+    preload?(url: string): Promise<void>;
+    /**
+     * Release the held media without destroying the adapter; the next `load()` must reattach it.
+     * Called on single-decoder TVs at break end, before content resumes, to free the hardware
+     * decoder and avoid `MEDIA_ERR_DECODE`. Not called in parallel-preload mode.
+     */
+    unload?(): void;
+    /**
+     * Optional capability hint: can content and ad pipelines buffer in parallel without decoder
+     * contention? `false` prevents continued content playout during a break. Undefined counts as capable.
+     */
+    readonly supportsParallelBuffering?: boolean;
+    /** Subscribe to player events. */
+    on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void;
+    /** Unsubscribe from player events. */
+    off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void;
+    /**
+     * Whether the content is live, as reported by the player engine. Return `null` or omit
+     * this property when unknown; the SDK then falls back to checking for an infinite duration.
+     * A finite duration does not reliably identify VOD: HLS.js can report a finite live playlist.
+     *
+     * | Player | Live status |
+     * |--------|-------------|
+     * | HLS.js | `hls.latestLevelDetails.live` |
+     * | Shaka | `player.isLive()` |
+     * | THEOplayer | `duration === Infinity` |
+     *
+     * Do not infer live status from {@link maxLiveSeekPosition}; a seek range can exist for VOD too.
+     */
+    readonly isLive?: boolean | null;
+    /**
+     * Latest live playback position the player can seek to without moving back to maintain
+     * its minimum live offset, in seconds. Return `null` when unknown or not live; the SDK
+     * then leaves the seek target unclamped. Use the player engine's seek limit rather than
+     * guessing an offset: HLS.js exposes `liveSyncPosition`, THEOplayer exposes
+     * `latencyManager.currentLatency` / `minimumOffset`, and Shaka exposes
+     * `seekRange()` / `safeSeekEndOffset`.
+     */
+    readonly maxLiveSeekPosition?: number | null;
+    /**
+     * End of the available media in seconds, or `null` when unknown. This differs from
+     * {@link maxLiveSeekPosition}, which includes the player's minimum live offset.
+     * Read the engine's seek range if the video element reports an unbounded sentinel value
+     * instead of the actual DVR window. If omitted, the SDK uses `videoElement.seekable`
+     * and rejects sentinel values.
+     */
+    readonly seekableEnd?: number | null;
+    /**
+     * Playback rate (`1` = normal). Used to correct drift while content continues behind an
+     * ad with `continueContentDuringBreak`. Report the engine's current rate, not just the last
+     * assigned value, so the SDK can detect changes made by the player's live-latency controller.
+     * If omitted, drift is reported but not corrected.
+     */
+    playbackRate?: number;
+    /** The underlying HTMLVideoElement, if any. Required for GAM (the IMA SDK needs the element). */
+    readonly videoElement?: HTMLVideoElement | null;
+    /**
+     * Release control of the content video element so a shared-element ad can use it.
+     * Resolve only when the element is free; do not destroy the adapter. The SDK restores
+     * content with `load()` when the break ends. Omit this method if your player supports
+     * sharing the element without an explicit release, as HLS.js does.
+     */
+    releaseMediaElement?(): void | Promise<void>;
+    /**
+     * Optionally select a content quality, or pass `null` to release the SDK's override.
+     * A successful `lowest` request snapshots the integrator's current selection and applies the
+     * cheapest rendition without flushing buffered media. Returns whether the request was applied;
+     * passing `null` restores the exact prior selection.
+     */
+    setVideoQuality?(quality: VideoQuality | null): boolean;
+    /** Clean up resources when the SDK is destroyed. */
+    destroy(): void;
+}

package/dist/interfaces/PlayerAdapter.js

@@ -0,0 +1 @@
+export{};

package/dist/internal/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/index.js

@@ -0,0 +1 @@
+export{};

package/dist/server/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Server-safe subset of `@dolby-optiview/ads-sdk-core`.
+ *
+ * Exposes only the **pure** units needed off the browser — manifest types +
+ * validation and the GAM pod-URL builder — without pulling the player/DOM/IMA
+ * runtime (`OptiViewAds`, `AdPlayerController`, `GamStreamManager`). Consumed by
+ * the SSAI stitcher (`@dolby-optiview/ads-sdk-stitcher`) and any other Node-side tooling.
+ */
+export type { BreakManifest, Break, BreakVariant, SingleBreakVariant, DoubleBreakVariant, LshapeAdBreakVariant, LshapeContentBreakVariant, OverlayBreakVariant, AssetWithCompanion, OverlayPosition, OverlaySize, Asset, StaticAsset, VendorAsset, Polling, Controls, Targeting, Interaction, AssetUri, EventTrigger, BreakPosition, } from '../types/BreakManifest';
+export { BreakFormat, AssetType, MediaType, Vendor, Timebase, DeviceType, BreakEvent, isEventTrigger, isPauseBreak, } from '../types/BreakManifest';
+export { parseBreakManifest, SUPPORTED_MANIFEST_MAJOR_VERSION, } from '../services/parseBreakManifest';
+export type { AdPreloadMode, AdInsertionMode, AdInsertionType, OptiViewAdsMode, } from '../types/OptiViewAdsConfig';
+export type { ResolvedPreloadMode } from '../services/detectPreloadMode';
+export { resolvePreloadMode, isSingleDecoderUserAgent } from '../services/detectPreloadMode';
+export type { ResolvedInsertionMode, MediaSourceCapabilities, } from '../services/detectInsertionMode';
+export { resolveInsertionMode, isSharedElementUserAgent, isSingleSurfaceWebDevice, } from '../services/detectInsertionMode';
+export { detectDeviceType } from '../services/detectDeviceType';
+export type { GamVendorParameters } from '../services/GamPodUrlBuilder';
+export { buildGamPodUrl, isGamVendorParameters } from '../services/GamPodUrlBuilder';
+export { SDK_VERSION } from '../generated/version';

package/dist/server/index.js

@@ -0,0 +1 @@
+export{BreakFormat,AssetType,MediaType,Vendor,Timebase,DeviceType,BreakEvent,isEventTrigger,isPauseBreak}from"../types/BreakManifest";export{parseBreakManifest,SUPPORTED_MANIFEST_MAJOR_VERSION}from"../services/parseBreakManifest";export{resolvePreloadMode,isSingleDecoderUserAgent}from"../services/detectPreloadMode";export{resolveInsertionMode,isSharedElementUserAgent,isSingleSurfaceWebDevice}from"../services/detectInsertionMode";export{detectDeviceType}from"../services/detectDeviceType";export{buildGamPodUrl,isGamVendorParameters}from"../services/GamPodUrlBuilder";export{SDK_VERSION}from"../generated/version";

package/dist/services/AdBreakSequencer.d.ts

@@ -0,0 +1,146 @@
+import { Asset, Break, BreakFormat, BreakVariant } from '../types/BreakManifest';
+import { type VariantSelectionInputs } from './selectVariant';
+/**
+ * Portable, DOM-free authority on the ORDER of the public ad events for a break (and a chain):
+ * `adbreakbegin` → per asset `adbegin`/`adend` (or `aderror` then `adend`, no `adbegin`) →
+ * `adbreakend`. It performs no I/O and starts no timers; the render layer drives it and reports
+ * outcomes, so the event contract has one source of truth across platforms (`conformance/`).
+ * - `lshape_content` shows a backdrop with no ad video: only `adbreakbegin`/`adbreakend`.
+ * - Shared-element plays only the first asset as a single fullscreen ad; `lshape_content` is skipped.
+ * - Chaining is overlay-only: the finished break `adbreakend`s and the successor `adbreakbegin`s at once.
+ */
+/** The insertion mode the sequencer needs, after `adaptive` has been resolved. */
+export type EffectiveInsertionMode = 'overlay' | 'shared-element';
+/** A single SDK ad event, in emission order. */
+export interface AdBreakStep {
+    type: 'adbreakbegin' | 'adbegin' | 'adend' | 'aderror' | 'adbreakend';
+    break: Break;
+    /** The declared format of the break's selected variant. */
+    format?: BreakFormat | undefined;
+    asset?: Asset;
+    adIndex?: number;
+    totalAds?: number;
+}
+/** The side effect the driver must perform next. */
+export type AdBreakAction = 
+/** Load + play this asset through the overlay ad player. */
+{
+    kind: 'play-asset';
+    asset: Asset;
+    index: number;
+    total: number;
+}
+/** Play a single fullscreen ad through the content element (shared-element). */
+ | {
+    kind: 'play-shared';
+    asset: Asset;
+}
+/** Render the lshape_content backdrop (no ad video); end on the duration timer. */
+ | {
+    kind: 'render-backdrop';
+}
+/** The break has fully ended (no chain): tear down and resume content. */
+ | {
+    kind: 'end-break';
+}
+/** Nothing to do; the driver awaits the next outcome (asset end/error/timer). */
+ | {
+    kind: 'await';
+};
+/** An outcome the driver reports back to advance the sequence. */
+export type AdBreakOutcome = 
+/** Overlay/shared asset playback actually started (play() resolved). */
+{
+    kind: 'asset-started';
+}
+/** The current asset finished playing. */
+ | {
+    kind: 'asset-ended';
+}
+/** The current asset failed to load/play. */
+ | {
+    kind: 'asset-errored';
+}
+/** The lshape_content backdrop duration elapsed. */
+ | {
+    kind: 'backdrop-elapsed';
+}
+/** The break's max-duration timer elapsed, cutting the break short. */
+ | {
+    kind: 'break-elapsed';
+};
+/**
+ * Why a break produced no ad: `no-variant`, `no-qualifying-variant` (none passed device
+ * targeting + format playability, no downgrade), `no-assets` (selected variant had no usable
+ * asset), `lshape-content-skipped` (shared-element cannot render a backdrop).
+ */
+export type NoPlayableAssetReason = 'no-variant' | 'no-qualifying-variant' | 'no-assets' | 'lshape-content-skipped';
+/** A break that began and ended without a single ad, and why. */
+export interface NoPlayableAssetNotice {
+    breakId: string;
+    reason: NoPlayableAssetReason;
+    /** The declared format of the selected variant; absent when none was selected. */
+    format?: BreakFormat | undefined;
+    /** Assets the manifest declared. `no-assets` with a non-zero count means they were all filtered out (targeting, media type), not missing. */
+    declaredAssetCount: number;
+}
+/** The steps to emit plus the next action, returned by every transition. */
+export interface AdBreakTransition {
+    steps: AdBreakStep[];
+    action: AdBreakAction;
+    /**
+     * Breaks in THIS transition that went `adbreakbegin` → `adbreakend` with no `adbegin`; from
+     * outside that is indistinguishable from an ad that failed to start. A list because
+     * `finalizeBreak` recurses through chained successors. Absent when every break had something to play.
+     */
+    noPlayableAsset?: NoPlayableAssetNotice[];
+}
+/** Resolver returning the break chained immediately after `breakId`, or null. */
+export type ChainResolver = (breakId: string) => Break | null;
+/**
+ * Pick the active variant via {@link selectVariantDetailed}. Without `inputs` the walk runs
+ * with no device type and every KNOWN format playable ("first variant wins", pause variants resolvable).
+ */
+export declare function selectVariant(breakInfo: Break, inputs?: VariantSelectionInputs): BreakVariant | null;
+/** The selected variant's {@link BreakFormat}, surfaced on public events; `undefined` when the break has no variant. */
+export declare function resolveBreakFormat(breakInfo: Break, inputs?: VariantSelectionInputs): BreakFormat | undefined;
+/** The ordered primary ad assets of one variant, across all five formats. */
+export declare function assetsOfVariant(variant: BreakVariant | null): Asset[];
+/** The ordered primary ad assets of a break, across all five variant formats. */
+export declare function extractAssets(breakInfo: Break, inputs?: VariantSelectionInputs): Asset[];
+/**
+ * The host's pre-`adbreakbegin` gate: a non-null reason means the break must not begin (host
+ * emits `aderror` + `DA-BREAK-NO-PLAYABLE-ASSET` and completes it in the scheduler).
+ */
+export declare function breakPlanEmptyReason(breakInfo: Break, insertionMode: EffectiveInsertionMode, selection?: VariantSelectionInputs): NoPlayableAssetReason | null;
+/** Drives one break-chain's event sequence: {@link beginBreak}, then feed every {@link AdBreakOutcome} into {@link onOutcome}. */
+export declare class AdBreakSequencer {
+    private readonly insertionMode;
+    private readonly chainResolver;
+    private readonly selection;
+    private currentBreak;
+    private plan;
+    private assetIndex;
+    /** True once the current asset emitted `adbegin` and has not yet settled. */
+    private assetStarted;
+    constructor(insertionMode: EffectiveInsertionMode, chainResolver?: ChainResolver, selection?: VariantSelectionInputs);
+    /** The SELECTED (or downgrade-candidate) variant's format, not the first declared variant's. */
+    private planFormat;
+    /** Emits `adbreakbegin` and returns the first action; a break with nothing to play is retired without beginning. */
+    beginBreak(breakInfo: Break): AdBreakTransition;
+    /** Built here because the host never sees a CHAINED successor's break object, so it cannot report its format/asset count. */
+    private noticeFor;
+    /** Emit one asset-less `aderror` step for an empty break, then advance to any chained successor (recursing if that is empty too). */
+    private retireEmptyBreak;
+    /** The first driver action for a (non-empty) plan. */
+    private startAction;
+    /** Advance the sequence with a driver outcome. */
+    onOutcome(outcome: AdBreakOutcome): AdBreakTransition;
+    /** The `adend` owed to an ad that began but has not settled, when a break is cut short. */
+    private inFlightAdendPrefix;
+    private onAssetStarted;
+    /** A failure emits `aderror` then `adend` regardless; then advance or finalize. */
+    private onAssetSettled;
+    /** Emit `adbreakend`; an overlay chained successor `adbreakbegin`s at once through the held overlay. */
+    private finalizeBreak;
+}

package/dist/services/AdBreakSequencer.js

@@ -0,0 +1 @@
+import{BreakFormat as t}from"../types/BreakManifest";import{KNOWN_BREAK_FORMATS as e,selectVariantDetailed as s,variantsOf as a}from"./selectVariant";export function selectVariant(t,a){return s(t,a??{playableFormats:e}).selected}export function resolveBreakFormat(t,e){return selectVariant(t,e)?.format}export function assetsOfVariant(e){if(!e)return[];switch(e.format){case t.SINGLE:case t.DOUBLE:case t.LSHAPE_AD:case t.LSHAPE_CONTENT:case t.OVERLAY:return e.assets;default:return[]}}export function extractAssets(t,e){return assetsOfVariant(selectVariant(t,e))}export function breakPlanEmptyReason(t,e,s={}){const a=r(t,e,s);return"empty"===a.mode?a.reason??null:null}function r(r,n,i={}){if(0===a(r).length)return{mode:"empty",reason:"no-variant",variant:null};const o=s(r,{deviceType:i.deviceType,playableFormats:"shared-element"===n?e:i.playableFormats}),d=o.selected,l=d??o.deviceQualified;if(!l)return{mode:"empty",reason:"no-qualifying-variant",variant:null};if("shared-element"===n){if(l.format===t.LSHAPE_CONTENT)return{mode:"empty",reason:"lshape-content-skipped",variant:l};const e=assetsOfVariant(l)[0];return e?{mode:"shared-single",asset:e,variant:l}:{mode:"empty",reason:"no-assets",variant:l}}if(d){if(d.format===t.LSHAPE_CONTENT)return{mode:"overlay-backdrop",variant:d};const e=assetsOfVariant(d);return e.length>0?{mode:"overlay-assets",assets:e,variant:d}:{mode:"empty",reason:"no-assets",variant:d}}if(l.format===t.LSHAPE_CONTENT)return{mode:"overlay-backdrop",variant:l};const h=assetsOfVariant(l)[0];return h?{mode:"overlay-assets",assets:[h],variant:l}:{mode:"empty",reason:"no-assets",variant:l}}export class AdBreakSequencer{constructor(t,e=()=>null,s={}){this.insertionMode=t,this.chainResolver=e,this.selection=s,this.currentBreak=null,this.plan={mode:"empty"},this.assetIndex=0,this.assetStarted=!1}planFormat(){return"variant"in this.plan?this.plan.variant?.format:void 0}beginBreak(t){if(this.currentBreak=t,this.plan=r(t,this.insertionMode,this.selection),this.assetIndex=0,this.assetStarted=!1,"empty"===this.plan.mode)return this.retireEmptyBreak(t,[],this.noticeFor(t));return{steps:[{type:"adbreakbegin",break:t,format:this.planFormat()}],action:this.startAction(this.plan)}}noticeFor(t){return"empty"===this.plan.mode&&this.plan.reason?[{breakId:t.id,reason:this.plan.reason,format:this.plan.variant?.format,declaredAssetCount:a(t).reduce((t,e)=>t+assetsOfVariant(e).length,0)}]:[]}retireEmptyBreak(t,e,s){const a=[...e,{type:"aderror",break:t,format:this.planFormat()}],n="overlay"===this.insertionMode?this.chainResolver(t.id):null;return n?(this.currentBreak=n,this.plan=r(n,this.insertionMode,this.selection),this.assetIndex=0,this.assetStarted=!1,"empty"===this.plan.mode?this.retireEmptyBreak(n,a,[...s,...this.noticeFor(n)]):(a.push({type:"adbreakbegin",break:n,format:this.planFormat()}),{steps:a,action:this.startAction(this.plan),noPlayableAsset:s})):(this.currentBreak=null,{steps:a,action:{kind:"end-break"},noPlayableAsset:s})}startAction(t){switch(t.mode){case"overlay-assets":return{kind:"play-asset",asset:t.assets[0],index:0,total:t.assets.length};case"overlay-backdrop":return{kind:"render-backdrop"};case"shared-single":return{kind:"play-shared",asset:t.asset}}}onOutcome(t){if(!this.currentBreak)return{steps:[],action:{kind:"await"}};const e=this.currentBreak;switch(t.kind){case"asset-started":return this.onAssetStarted(e);case"asset-ended":return this.onAssetSettled(e,!1);case"asset-errored":return this.onAssetSettled(e,!0);case"backdrop-elapsed":case"break-elapsed":return this.finalizeBreak(this.inFlightAdendPrefix(e))}}inFlightAdendPrefix(t){if(!this.assetStarted)return[];const e=this.planFormat();return"overlay-assets"===this.plan.mode?[{type:"adend",break:t,format:e,asset:this.plan.assets[this.assetIndex],adIndex:this.assetIndex,totalAds:this.plan.assets.length}]:"shared-single"===this.plan.mode?[{type:"adend",break:t,format:e,asset:this.plan.asset,adIndex:0,totalAds:1}]:[]}onAssetStarted(t){if("overlay-assets"===this.plan.mode){const e=this.plan.assets.length,s=this.plan.assets[this.assetIndex];return this.assetStarted=!0,{steps:[{type:"adbegin",break:t,format:this.planFormat(),asset:s,adIndex:this.assetIndex,totalAds:e}],action:{kind:"await"}}}return"shared-single"===this.plan.mode?(this.assetStarted=!0,{steps:[{type:"adbegin",break:t,format:this.planFormat(),asset:this.plan.asset,adIndex:0,totalAds:1}],action:{kind:"await"}}):{steps:[],action:{kind:"await"}}}onAssetSettled(t,e){if(this.assetStarted=!1,"shared-single"===this.plan.mode){const s=[],a=this.plan.asset,r=this.planFormat();return e&&s.push({type:"aderror",break:t,format:r,asset:a,adIndex:0,totalAds:1}),s.push({type:"adend",break:t,format:r,asset:a,adIndex:0,totalAds:1}),this.finalizeBreak(s)}if("overlay-assets"!==this.plan.mode)return{steps:[],action:{kind:"await"}};const s=this.plan.assets.length,a=this.plan.assets[this.assetIndex],r=[],n=this.planFormat();return e&&r.push({type:"aderror",break:t,format:n,asset:a,adIndex:this.assetIndex,totalAds:s}),r.push({type:"adend",break:t,format:n,asset:a,adIndex:this.assetIndex,totalAds:s}),this.assetIndex+=1,this.assetIndex<s?{steps:r,action:{kind:"play-asset",asset:this.plan.assets[this.assetIndex],index:this.assetIndex,total:s}}:this.finalizeBreak(r)}finalizeBreak(t,e=[]){const s=t=>e.length>0?{...t,noPlayableAsset:e}:t,a=this.currentBreak;if(!a)return s({steps:t,action:{kind:"end-break"}});const n=[...t,{type:"adbreakend",break:a,format:this.planFormat()}],i="overlay"===this.insertionMode?this.chainResolver(a.id):null;return i?(this.currentBreak=i,this.plan=r(i,this.insertionMode,this.selection),this.assetIndex=0,this.assetStarted=!1,"empty"===this.plan.mode?this.retireEmptyBreak(i,n,[...e,...this.noticeFor(i)]):(n.push({type:"adbreakbegin",break:i,format:this.planFormat()}),s({steps:n,action:this.startAction(this.plan)}))):(this.currentBreak=null,s({steps:n,action:{kind:"end-break"}}))}}