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

package/dist/services/resolveResumePoint.d.ts

@@ -0,0 +1,38 @@
+import { AdInsertionType } from '../types/OptiViewAdsConfig';
+/** Inputs (seconds) for the portable resume-point rule, locked by the conformance harness. */
+export interface ResumePointInput {
+    /**
+     * The content position where the break paused content. NOT the break's `start`: on the
+     * wallclock timebase that is an ISO timestamp unrelated to the content timeline.
+     */
+    anchor: number;
+    /** The break's configured (maximum) duration in seconds. */
+    duration: number;
+    /** Ad actually played this break; caps the offset. Non-positive or non-finite disables the cap. */
+    adDuration: number;
+    /** The client's insertion type, ONLY when set explicitly; `undefined` lets the manifest drive. */
+    insertionType?: AdInsertionType | undefined;
+    /** The manifest's seek length from the anchor. Absent lets the ad duration decide; `0` asks for no seek. */
+    resumeOffset?: number | undefined;
+}
+/** Which precedence level produced the offset. */
+export type ResumePointSource = 'client' | 'manifest' | 'ad-duration';
+/** The resolved resume decision. */
+export interface ResumePoint {
+    /** Whether to seek at all. A zero offset means stay where content paused. */
+    seek: boolean;
+    /** Absolute content position to seek to. Only meaningful when `seek`. */
+    target: number;
+    /** The offset in seconds after precedence and clamping. */
+    offset: number;
+    /** The precedence level that produced the offset. */
+    source: ResumePointSource;
+    /** Whether the ad-duration cap shortened the offset. */
+    clamped: boolean;
+}
+/**
+ * Precedence: explicit client `insertionType` (`insertion` → 0, `replacement` → duration), then
+ * the manifest's `resumeOffset` (`0` included), then the ad duration. Capped at the ad duration.
+ * No timebase: identical on VOD and live.
+ */
+export declare function resolveResumePoint(input: ResumePointInput): ResumePoint;

package/dist/services/resolveResumePoint.js

@@ -0,0 +1 @@
+export function resolveResumePoint(e){const{anchor:t,duration:i,adDuration:n,insertionType:o,resumeOffset:r}=e;let s,u;void 0!==o?(s="insertion"===o?0:i,u="client"):void 0!==r?(s=r,u="manifest"):(s=n,u="ad-duration"),(!Number.isFinite(s)||s<0)&&(s=0);const a=Number.isFinite(n)&&n>0?n:0,c=s>0&&a>0&&a<s;return c&&(s=a),{seek:s>0,target:t+s,offset:s,source:u,clamped:c}}

package/dist/services/resolveTargetedUri.d.ts

@@ -0,0 +1,22 @@
+import { AssetUri, DeviceType } from '../types/BreakManifest';
+/**
+ * Resolve a `static`/`vast` asset's `uri` field (a plain string, or an
+ * `AssetUri[]` where each entry may carry `targeting.deviceType`) to the single
+ * URI to play, as a pure function shared (by behavioural contract) with the
+ * Kotlin and Swift cores and locked by the cross-language conformance harness.
+ *
+ * Selection order:
+ * 1. `uri` is a plain string → return it as-is (no targeting is possible).
+ * 2. `deviceType` is known and an entry's `targeting.deviceType` matches it →
+ *    that entry's `value`.
+ * 3. Otherwise, the first entry with no `targeting.deviceType` (the manifest's
+ *    default/untargeted URI) → that entry's `value`.
+ * 4. Otherwise (every entry is targeted and none matched — e.g. an unknown
+ *    device class), fall back to `uris[0].value` so playback still proceeds
+ *    with *some* URI rather than none.
+ * 5. An empty/missing array resolves to `null`.
+ *
+ * This is the single source of truth for `AdPlayerController.resolveUri` and
+ * the native asset-URI resolvers.
+ */
+export declare function resolveTargetedUri(uri: string | AssetUri[], deviceType?: DeviceType): string | null;

package/dist/services/resolveTargetedUri.js

@@ -0,0 +1 @@
+export function resolveTargetedUri(e,r){if("string"==typeof e)return e;if(!Array.isArray(e)||0===e.length)return null;if(r){const t=e.find(e=>e.targeting?.deviceType===r);if(t)return t.value}const t=e.find(e=>void 0===e.targeting?.deviceType);return t?t.value:e[0].value}

package/dist/services/resolveVastAdmission.d.ts

@@ -0,0 +1,34 @@
+import { BreakFormat } from '../types/BreakManifest';
+/**
+ * The structured diagnostic a rejected VAST asset raises. A `null` diagnostic
+ * accompanies an admitted asset. Both codes come from the S1 taxonomy.
+ */
+export type VastAdmissionDiagnostic = 'DA-VAST-SSAI-UNSUPPORTED' | 'DA-VAST-UNSUPPORTED-FORMAT';
+/** Inputs for the portable VAST-admission decision (a `vast` asset is assumed). */
+export interface VastAdmissionInput {
+    /** The break variant's format. */
+    format: BreakFormat;
+    /** Whether the session is running in SSAI (server-guided/stitched) mode. */
+    ssai: boolean;
+}
+/** The decision: whether a `vast` asset is playable, plus the rejection code if not. */
+export interface VastAdmission {
+    admitted: boolean;
+    diagnostic: VastAdmissionDiagnostic | null;
+}
+/**
+ * Decide whether a `vast` (client-side / CSAI) asset may be played, as a pure
+ * function shared (by behavioural contract) with the Kotlin and Swift cores and
+ * locked by the cross-language conformance harness.
+ *
+ * VAST is **SGAI-only** and **linear-only**. In priority order:
+ * 1. SSAI mode → reject with `DA-VAST-SSAI-UNSUPPORTED` (SSAI never reads the
+ *    break manifest; a `vast` asset here is a misconfiguration).
+ * 2. non-linear format (`overlay` / `lshape_content`) → reject with
+ *    `DA-VAST-UNSUPPORTED-FORMAT`.
+ * 3. otherwise (`single` / `double` / `lshape_ad`) → admit.
+ *
+ * This is the single source of truth for the renderer format guard (see
+ * `AdPlayerController.playVastAsset` and the native `OverlayAdRenderer`s).
+ */
+export declare function resolveVastAdmission(input: VastAdmissionInput): VastAdmission;

package/dist/services/resolveVastAdmission.js

@@ -0,0 +1 @@
+import{BreakFormat as t}from"../types/BreakManifest";export function resolveVastAdmission(i){const{format:s,ssai:a}=i;return a?{admitted:!1,diagnostic:"DA-VAST-SSAI-UNSUPPORTED"}:s===t.OVERLAY||s===t.LSHAPE_CONTENT?{admitted:!1,diagnostic:"DA-VAST-UNSUPPORTED-FORMAT"}:{admitted:!0,diagnostic:null}}

package/dist/services/selectVariant.d.ts

@@ -0,0 +1,47 @@
+import { BreakFormat } from '../types/BreakManifest';
+import type { Break, BreakVariant } from '../types/BreakManifest';
+/**
+ * Break-variant selection per the manifest spec's `targeting`, locked across the three cores by
+ * the `variant-selection` conformance fixture. One ordered walk with two filters:
+ * 1. Device type: `targeting.deviceType` equals the detected class; no `deviceType` is a
+ *    default that qualifies anywhere; an unrecognised value never qualifies and is NOT promoted
+ *    to a default. With no detected device only defaults qualify.
+ * 2. Format playability: a qualifying variant the platform cannot render is passed over;
+ *    unknown formats are never playable.
+ * Declaration order wins. The result is two-stage because the device filter gates the
+ * downgrade path: `selected` null but `deviceQualified` set means the declared formats cannot
+ * render here and the last-resort downgrades may apply; both null means the break must not begin.
+ */
+/** The scheduled break formats a renderer can be asked to draw. */
+export declare const RENDERABLE_BREAK_FORMATS: readonly BreakFormat[];
+/** Every format ANY selection may consider known. */
+export declare const KNOWN_BREAK_FORMATS: readonly string[];
+/** Inputs the platform layer feeds into a selection. */
+export interface VariantSelectionInputs {
+    /** Detected device class. Undefined = unknown: targeted variants never match, defaults still qualify. */
+    deviceType?: string | undefined;
+    /** Formats renderable in the CURRENT context (PiP narrows it, see {@link playableFormatsFor}). Omitted = all renderable. */
+    playableFormats?: readonly string[] | undefined;
+}
+/** The two-stage result of a selection — see the module doc. */
+export interface VariantSelection {
+    /** The variant to play as declared; null when nothing passed both filters. */
+    selected: BreakVariant | null;
+    /** First variant passing the DEVICE filter with a KNOWN format: the downgrade candidate when `selected` is null. */
+    deviceQualified: BreakVariant | null;
+    /**
+     * Raw `format` strings this device WAS allowed to see but were passed over as unknown to this
+     * SDK version (absent format reported as `''`). Only variants actually examined are listed.
+     * Carried on the result so the selector stays pure; each core diagnoses from its own layer.
+     */
+    skippedUnknownFormats: string[];
+}
+/** The playable-format set for the web renderer's current context; native renderers mirror this table. */
+export declare function playableFormatsFor(context: {
+    pictureInPicture?: boolean;
+    singleSurfaceDevice?: boolean;
+}): readonly BreakFormat[];
+/** The break's declared variants as a list (the manifest allows both shapes). */
+export declare function variantsOf(breakInfo: Break): BreakVariant[];
+/** Run the two-filter ordered walk (see the module doc). */
+export declare function selectVariantDetailed(breakInfo: Break, inputs?: VariantSelectionInputs): VariantSelection;

package/dist/services/selectVariant.js

@@ -0,0 +1 @@
+import{BreakFormat as e}from"../types/BreakManifest";export const RENDERABLE_BREAK_FORMATS=[e.SINGLE,e.DOUBLE,e.LSHAPE_AD,e.LSHAPE_CONTENT,e.OVERLAY];export const KNOWN_BREAK_FORMATS=[...RENDERABLE_BREAK_FORMATS];export function playableFormatsFor(t){return t.pictureInPicture?[e.SINGLE,e.LSHAPE_CONTENT]:t.singleSurfaceDevice?RENDERABLE_BREAK_FORMATS.filter(t=>t!==e.DOUBLE):RENDERABLE_BREAK_FORMATS}export function variantsOf(e){const t=e.variant;return Array.isArray(t)?t:t?[t]:[]}function t(e,t){const n=e.targeting?.deviceType;return void 0===n||void 0!==t&&n===t}export function selectVariantDetailed(e,n={}){const r=n.playableFormats??RENDERABLE_BREAK_FORMATS;let i=null,o=null;const E=[];for(const A of variantsOf(e)){if(!t(A,n.deviceType))continue;const e=A.format,a=void 0!==e&&KNOWN_BREAK_FORMATS.includes(e);if(a||E.push(e??""),null===o&&a&&(o=A),null===i&&void 0!==e&&r.includes(e)&&(i=A),null!==i)break}return{selected:i,deviceQualified:o,skippedUnknownFormats:E}}

package/dist/services/urlOrigin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Origin derivation for diagnostics — portable brain behavior.
+ *
+ * The diagnostics report is part of the cross-language contract (AGENTS.md Core
+ * Principle 5), so this is hand-written rather than delegated to `new URL()`,
+ * `URLComponents` or `java.net.URI`: those disagree with each other on explicit
+ * default ports (`https://h:443` — JS drops the port, the others keep it), on
+ * userinfo, and on malformed input. A platform parser per core would give three
+ * subtly different reports for the same session. This rule is locked by the
+ * `url-origin-v1` conformance fixture; the Kotlin and Swift mirrors must stay
+ * character-for-character equivalent.
+ */
+/**
+ * The origin of an absolute URL: `scheme://host` plus `:port` whenever a port
+ * was written, lowercased scheme and host, userinfo and path/query/fragment
+ * dropped. Returns `null` when the input is not an absolute URL (a relative
+ * manifest path is legitimate, it simply has no origin to report).
+ *
+ * Ports are never normalised away: `https://h:443` reports `https://h:443`, not
+ * `https://h`. Reporting what the integrator wrote keeps the three cores
+ * identical and keeps the report honest.
+ */
+export declare function resolveUrlOrigin(url: string): string | null;

package/dist/services/urlOrigin.js

@@ -0,0 +1 @@
+export function resolveUrlOrigin(e){const n=e.indexOf("://");if(n<=0)return null;const l=e.slice(0,n).toLowerCase();if(l.includes("/")||l.includes("?")||l.includes("#"))return null;const t=e.slice(n+3);let s=t.length;for(const e of["/","?","#"]){const n=t.indexOf(e);-1!==n&&n<s&&(s=n)}let c=t.slice(0,s);const i=c.lastIndexOf("@");-1!==i&&(c=c.slice(i+1));const o=c.lastIndexOf("]"),r=c.indexOf(":",-1===o?0:o);let f=c,u="";if(-1!==r){const e=c.slice(r+1);e.length>0&&/^[0-9]+$/.test(e)&&(f=c.slice(0,r),u=e)}return f=f.toLowerCase(),0===f.length?null:u.length>0?`${l}://${f}:${u}`:`${l}://${f}`}

package/dist/session/AdBreakStatusTracker.d.ts

@@ -0,0 +1,49 @@
+import { Asset, Break, BreakFormat } from '../types/BreakManifest';
+import { AdBreakStatus, OptiViewAdsEventMap, OptiViewAdsEventType } from '../types/Events';
+import { BreakTransitionTimer } from '../services/BreakTransitionTimer';
+export type EmitEvent = <T extends OptiViewAdsEventType>(event: T, data: OptiViewAdsEventMap[T]) => void;
+export interface AdBreakStatusTrackerDeps {
+    emit: EmitEvent;
+    effectiveFormatOf: (breakInfo: Break) => BreakFormat | undefined;
+    secondsUntilBreak: (breakId: string) => number | undefined;
+    breakTransitionTimer: () => BreakTransitionTimer | undefined;
+}
+/** Playback-gated `AdBreakStatus` state machine behind `getAdBreakStatus()` and the `adbreakstatus` event. */
+export declare class AdBreakStatusTracker {
+    private readonly deps;
+    adBreakStatus: AdBreakStatus;
+    activeBreak: Break | null;
+    activeBreakRemainingAtStart: number | null;
+    activeBreakStartTimestamp: number | null;
+    activeBreakElapsedSec: number;
+    currentAdStartElapsedSec: number;
+    currentAdIndex: number | null;
+    currentAdTotal: number | null;
+    currentAdTime: number | null;
+    currentAdDuration: number | null;
+    activeBreakWaiting: boolean;
+    activeBreakPlaying: boolean;
+    constructor(deps: AdBreakStatusTrackerDeps);
+    /** Current playback-gated ad break status; for polling when an `adbreakstatus` event was missed. */
+    getAdBreakStatus(): AdBreakStatus;
+    /** Pre-break warning: emits `adbreakstatus` with `phase: 'upcoming'`. */
+    onBreakWarning(breakInfo: Break, warningSec: number, secondsUntil: number): void;
+    /** Promote a break to `phase: 'active'`; `ticking` starts `false` until playback events toggle it. */
+    setAdBreakStatusActive(breakInfo: Break, breakRemainingSec: number): void;
+    /** Mark the active break visible and playing: the first-frame signal for held pre-rolls, the first `playing` otherwise. */
+    setAdBreakVisible(breakInfo: Break): void;
+    onAdStarted(breakInfo: Break, _asset: Asset, index: number, total: number): void;
+    onAdEnded(breakInfo: Break): void;
+    onAdTimeUpdated(breakInfo: Break, currentTime: number, duration: number): void;
+    onAdPlaybackWaiting(): void;
+    onAdPlaybackPlaying(): void;
+    private buildActiveAdBreakStatus;
+    /** Remaining break seconds; falls back to wall-clock for formats without per-ad `timeupdate` (e.g. backdrop). */
+    private computeBreakRemainingSec;
+    /** Ad progress is authoritative once it arrives; before then (IMA fetch, backdrop/image breaks) wall-clock keeps the countdown moving. */
+    currentBreakElapsedSec(): number;
+    resetAdBreakStatus(): void;
+    private emitAdBreakStatus;
+    /** Only compares the scalar fields that affect UI rendering; `break` identity is ignored. */
+    private statusesEqual;
+}

package/dist/session/AdBreakStatusTracker.js

@@ -0,0 +1 @@
+export class AdBreakStatusTracker{constructor(t){this.deps=t,this.adBreakStatus={phase:"idle",break:null,ticking:!1},this.activeBreak=null,this.activeBreakRemainingAtStart=null,this.activeBreakStartTimestamp=null,this.activeBreakElapsedSec=0,this.currentAdStartElapsedSec=0,this.currentAdIndex=null,this.currentAdTotal=null,this.currentAdTime=null,this.currentAdDuration=null,this.activeBreakWaiting=!1,this.activeBreakPlaying=!1}getAdBreakStatus(){if("active"===this.adBreakStatus.phase)return{...this.adBreakStatus,breakRemainingSec:this.computeBreakRemainingSec()};if("upcoming"===this.adBreakStatus.phase&&this.activeBreak){const t=this.deps.secondsUntilBreak(this.activeBreak.id);return{...this.adBreakStatus,secondsUntilBreak:t}}return{...this.adBreakStatus}}onBreakWarning(t,e,i){this.activeBreak=t,this.emitAdBreakStatus({phase:"upcoming",break:t,format:this.deps.effectiveFormatOf(t),secondsUntilBreak:i,ticking:!1,warningSec:e})}setAdBreakStatusActive(t,e){this.activeBreak=t,this.activeBreakRemainingAtStart=e,this.activeBreakStartTimestamp=Date.now(),this.activeBreakElapsedSec=0,this.currentAdStartElapsedSec=0,this.currentAdIndex=null,this.currentAdTotal=null,this.currentAdTime=null,this.currentAdDuration=null,this.activeBreakWaiting=!1,this.activeBreakPlaying=!1,this.emitAdBreakStatus({phase:"active",break:t,format:this.deps.effectiveFormatOf(t),breakRemainingSec:this.activeBreakRemainingAtStart,ticking:!1})}setAdBreakVisible(t){this.activeBreakWaiting=!1,this.activeBreakPlaying=!0,this.emitAdBreakStatus({...this.buildActiveAdBreakStatus(t),ticking:!0})}onAdStarted(t,e,i,a){this.currentAdIndex=i,this.currentAdTotal=a,this.currentAdTime=null,this.currentAdDuration=null,this.currentAdStartElapsedSec=this.currentBreakElapsedSec(),this.activeBreakElapsedSec=this.currentAdStartElapsedSec,this.activeBreakWaiting=!1,this.activeBreakPlaying=!0,this.deps.breakTransitionTimer()?.settle("into-break","ad-to-ad","break-to-break"),this.emitAdBreakStatus({...this.buildActiveAdBreakStatus(t),adIndex:i,totalAds:a,adsRemaining:a-i,ticking:!0})}onAdEnded(t){null!==this.currentAdDuration&&Number.isFinite(this.currentAdDuration)?this.activeBreakElapsedSec=this.currentAdStartElapsedSec+this.currentAdDuration:null!==this.currentAdTime&&(this.activeBreakElapsedSec=this.currentAdStartElapsedSec+this.currentAdTime),this.currentAdIndex=null,this.currentAdTime=null,this.currentAdDuration=null,this.activeBreakPlaying=!1,this.emitAdBreakStatus({...this.buildActiveAdBreakStatus(t),adsRemaining:0,breakRemainingSec:this.computeBreakRemainingSec(),ticking:!1})}onAdTimeUpdated(t,e,i){this.currentAdTime=e,this.currentAdDuration=i,this.activeBreakElapsedSec=this.currentAdStartElapsedSec+e,this.activeBreakWaiting=!1,this.activeBreakPlaying=!0,this.emitAdBreakStatus({...this.buildActiveAdBreakStatus(t),breakRemainingSec:this.computeBreakRemainingSec(),ticking:!0})}onAdPlaybackWaiting(){this.activeBreakWaiting=!0,this.activeBreakPlaying=!1,this.activeBreak&&this.emitAdBreakStatus({...this.buildActiveAdBreakStatus(this.activeBreak),ticking:!1})}onAdPlaybackPlaying(){this.activeBreakWaiting=!1,this.activeBreakPlaying=!0,this.activeBreak&&this.emitAdBreakStatus({...this.buildActiveAdBreakStatus(this.activeBreak),ticking:!0})}buildActiveAdBreakStatus(t){return{phase:"active",break:t,format:this.deps.effectiveFormatOf(t),adIndex:this.currentAdIndex??void 0,totalAds:this.currentAdTotal??void 0,adsRemaining:null!==this.currentAdIndex&&null!==this.currentAdTotal?this.currentAdTotal-this.currentAdIndex:void 0,breakRemainingSec:this.computeBreakRemainingSec(),ticking:this.activeBreakPlaying&&!this.activeBreakWaiting}}computeBreakRemainingSec(){if(null!==this.activeBreakRemainingAtStart)return Math.max(0,this.activeBreakRemainingAtStart-this.currentBreakElapsedSec())}currentBreakElapsedSec(){let t=this.activeBreakElapsedSec;return 0===t&&null!==this.activeBreakStartTimestamp&&null===this.currentAdTime&&(t=(Date.now()-this.activeBreakStartTimestamp)/1e3),t}resetAdBreakStatus(){this.activeBreak=null,this.activeBreakRemainingAtStart=null,this.activeBreakStartTimestamp=null,this.activeBreakElapsedSec=0,this.currentAdStartElapsedSec=0,this.currentAdIndex=null,this.currentAdTotal=null,this.currentAdTime=null,this.currentAdDuration=null,this.activeBreakWaiting=!1,this.activeBreakPlaying=!1,this.emitAdBreakStatus({phase:"idle",break:null,ticking:!1})}emitAdBreakStatus(t){this.statusesEqual(this.adBreakStatus,t)||(this.adBreakStatus=t,this.deps.emit("adbreakstatus",{type:"adbreakstatus",timestamp:Date.now(),status:t}))}statusesEqual(t,e){return t.phase===e.phase&&t.format===e.format&&t.secondsUntilBreak===e.secondsUntilBreak&&t.breakRemainingSec===e.breakRemainingSec&&t.adIndex===e.adIndex&&t.totalAds===e.totalAds&&t.adsRemaining===e.adsRemaining&&t.ticking===e.ticking&&t.warningSec===e.warningSec&&t.break?.id===e.break?.id}}

package/dist/session/BreakLifecycle.d.ts

@@ -0,0 +1,62 @@
+import { Break, BreakFormat } from '../types/BreakManifest';
+import { BreakScheduler, BreakStartContext } from '../services/BreakScheduler';
+import { ManifestService } from '../services/ManifestService';
+import { AdPlayerController } from '../services/AdPlayerController';
+import { BreakTransitionTimer } from '../services/BreakTransitionTimer';
+import { CmcdAdReporter } from '../services/CmcdAdReporter';
+import { KnownDiagnosticCode } from '../diagnostics/errorCodes';
+import { AdBreakStatusTracker, EmitEvent } from './AdBreakStatusTracker';
+import { SessionState } from './SessionState';
+export type Diagnose = (code: KnownDiagnosticCode, message: string, context?: Record<string, unknown>) => void;
+export type Log = (...args: unknown[]) => void;
+export interface BreakLifecycleDeps {
+    adPlayerController: AdPlayerController;
+    breakScheduler: BreakScheduler;
+    manifestService: ManifestService;
+    breakTransitionTimer: BreakTransitionTimer | undefined;
+    cmcdAdReporter: CmcdAdReporter;
+    adBreakStatusTracker: AdBreakStatusTracker;
+    emit: EmitEvent;
+    diagnose: Diagnose;
+    log: Log;
+    effectiveFormatOf: (breakInfo: Break) => BreakFormat | undefined;
+    onBreakSettled?: () => void;
+}
+/** Scheduler and ad-player callbacks for one SGAI break: event emission, status updates, teardown reporting. */
+export declare class BreakLifecycle {
+    private readonly state;
+    private readonly deps;
+    private breakBeginEmittedId;
+    private pendingAdBreakBegin;
+    constructor(state: SessionState, deps: BreakLifecycleDeps);
+    /**
+     * Emit `adbreakbegin` at most once per break id. Routing every begin through here, plus a flush
+     * before any terminal event, keeps the break bracketed even when the ad errors before its first frame.
+     */
+    emitAdBreakBegin(brk: Break, context?: BreakStartContext): void;
+    /** Flush a deferred (first-frame-gated) `adbreakbegin`, if one is pending. */
+    flushPendingAdBreakBegin(): void;
+    onBreakStart(breakInfo: Break, context: BreakStartContext): Promise<void>;
+    /** A chained break begins (overlay held, content not resumed): emit `adbreakbegin`, promote it to ACTIVE, keep polling. */
+    onChainedBreakBegin(next: Break): void;
+    onBreakEnd(breakInfo: Break): void;
+    /**
+     * A content-covering break ended before its content pause landed, so no player transition
+     * announces the resume; emit the content `playing` the resumed path would have produced.
+     * Only the deferred-pause renderers (Kotlin/Swift) signal this; kept in the TS reference for lockstep.
+     */
+    onBreakEndedWithoutContentPause(): void;
+    /**
+     * The ACTIVE break disappeared from a polled manifest (the manifest spec's "early return").
+     * Ends it through the controller's abort path: balanced `adend` + `adbreakend`, resume at
+     * `break.start + seconds played`, chaining suppressed. If the removal races the natural end,
+     * the scheduler entry is completed so it cannot linger ACTIVE.
+     */
+    onBreakAborted(breakInfo: Break): void;
+    /**
+     * Report a break still in flight at teardown. Web aborts it (`stopActiveBreak`), but an
+     * `adbegin` already emitted never gets its `adend` — the same shape a stalled ad produces.
+     * `unbalancedAdBegin` tells them apart. Must run before `resetAdBreakStatus()` clears the evidence.
+     */
+    reportAbandonedBreak(cause: string): void;
+}

package/dist/session/BreakLifecycle.js

@@ -0,0 +1 @@
+import{BreakFormat as e}from"../types/BreakManifest";import{playbackErrorContext as t}from"../diagnostics/playbackErrorContext";export class BreakLifecycle{constructor(e,t){this.state=e,this.deps=t,this.breakBeginEmittedId=null,this.pendingAdBreakBegin=null}emitAdBreakBegin(e,t){this.breakBeginEmittedId!==e.id&&(this.breakBeginEmittedId=e.id,this.pendingAdBreakBegin=null,this.deps.emit("adbreakbegin",{type:"adbreakbegin",timestamp:Date.now(),break:e,format:this.deps.effectiveFormatOf(e),elapsedSec:t?.elapsedSec??0,remainingSec:t?.remainingSec??e.duration??0,...t?.tuneIn?{tuneIn:{elapsedSec:t.elapsedSec,remainingSec:t.remainingSec}}:{}}))}flushPendingAdBreakBegin(){this.pendingAdBreakBegin?.()}async onBreakStart(a,i){if(this.state.snapbackSeekInFlight=!1,this.deps.adPlayerController.isAdPlaying())return this.deps.diagnose("DA-BREAK-SUPPRESSED-OVERLAP",`Break suppressed (ad already playing): ${a.id}`,{breakId:a.id}),this.deps.breakScheduler.completeBreak(a.id),void this.deps.onBreakSettled?.();this.deps.adPlayerController.diagnoseUnknownVariantFormats(a);const d=this.deps.adPlayerController.breakNothingToPlayReason(a);if(d)return this.deps.log("Break not begun (no playable variant):",a.id,d),this.deps.diagnose("DA-BREAK-NO-PLAYABLE-ASSET",`break ${a.id} has no playable variant (${d}); it will not begin.`,{breakId:a.id,reason:d}),this.deps.emit("aderror",{type:"aderror",timestamp:Date.now(),source:"ad",break:a,format:this.deps.effectiveFormatOf(a),error:new Error(`Break ${a.id} has no playable variant (${d})`)}),this.deps.breakScheduler.completeBreak(a.id),void this.deps.onBreakSettled?.();this.deps.log("Break starting:",a.id,i.tuneIn?"(tune-in)":""),this.deps.breakTransitionTimer?.mark("into-break",a.id),this.breakBeginEmittedId=null,this.pendingAdBreakBegin=null;const r=this.state.heldImmediatePreRollId===a.id,s=this.deps.effectiveFormatOf(a),n=s===e.SINGLE||s===e.LSHAPE_AD,o=r&&n;r&&(this.state.heldImmediatePreRollId=null),this.deps.adBreakStatusTracker.setAdBreakStatusActive(a,void 0!==i.remainingSec?i.remainingSec:a.duration),o||this.emitAdBreakBegin(a,i),this.deps.manifestService.setActive(!0),this.deps.breakScheduler.claimChain(a.id);const k={onAdStart:(e,t,a,i,d)=>{this.deps.adBreakStatusTracker.onAdStarted(e,t,a,i),this.deps.emit("adbegin",{type:"adbegin",timestamp:Date.now(),break:e,format:this.deps.effectiveFormatOf(e),asset:t,adIndex:a,totalAds:i,...d?.adId?{adId:d.adId}:{},...d?.creativeId?{creativeId:d.creativeId}:{},...void 0!==d?.podPosition?{podPosition:d.podPosition}:{}})},onAdEnd:(e,t,a,i,d)=>{this.deps.adBreakStatusTracker.onAdEnded(e),a+1<i&&this.deps.breakTransitionTimer?.mark("ad-to-ad",e.id),this.deps.emit("adend",{type:"adend",timestamp:Date.now(),break:e,format:this.deps.effectiveFormatOf(e),asset:t,adIndex:a,totalAds:i,...d?.adId?{adId:d.adId}:{},...d?.creativeId?{creativeId:d.creativeId}:{}})},onAdError:(e,a,i)=>{this.flushPendingAdBreakBegin(),this.deps.diagnose("DA-AD-PLAYBACK-ERROR",i.message,{breakId:e.id,assetId:a?.id,...t(i)}),this.deps.emit("aderror",{type:"aderror",timestamp:Date.now(),source:"ad",break:e,format:this.deps.effectiveFormatOf(e),...a?{asset:a}:{},error:i})},onAdTimeUpdate:(e,t,a,i)=>{this.deps.adBreakStatusTracker.onAdTimeUpdated(e,a,i),this.deps.emit("adtimeupdate",{type:"adtimeupdate",timestamp:Date.now(),break:e,format:this.deps.effectiveFormatOf(e),asset:t,currentTime:a,duration:i})},onAdWaiting:(e,t)=>{this.deps.adBreakStatusTracker.onAdPlaybackWaiting(),this.deps.emit("waiting",{type:"waiting",timestamp:Date.now(),source:"ad",break:e,asset:t})},onAdPlaying:(e,t)=>{this.deps.adBreakStatusTracker.onAdPlaybackPlaying(),this.deps.emit("playing",{type:"playing",timestamp:Date.now(),source:"ad",break:e,asset:t})},onBreakEnd:e=>{this.onBreakEnd(e)},onBreakEndedWithoutContentPause:()=>{this.onBreakEndedWithoutContentPause()},onChainedBreakBegin:e=>{this.onChainedBreakBegin(e)},onChainedBreakSkipped:e=>{this.deps.log("Chained break skipped (no playable variant):",e.id),this.deps.breakScheduler.completeBreak(e.id)},onContentResumeSeek:(e,t)=>{this.deps.breakScheduler.notifyResumeSeek(e,t)},onContentReloading:e=>{this.deps.breakScheduler.setContentReloading(e)}};o&&(this.pendingAdBreakBegin=()=>this.emitAdBreakBegin(a,i),k.onBreakVisible=e=>{this.deps.adBreakStatusTracker.setAdBreakVisible(e),this.flushPendingAdBreakBegin()}),await this.deps.adPlayerController.playBreak(a,k,{effectiveDurationSec:i.remainingSec,firstFrameGate:o})}onChainedBreakBegin(e){this.deps.log("Chained break starting:",e.id),this.deps.breakTransitionTimer?.mark("break-to-break",e.id),this.deps.breakScheduler.activateChainedBreak(e.id),this.deps.manifestService.setActive(!0),this.deps.adBreakStatusTracker.setAdBreakStatusActive(e,e.duration),this.emitAdBreakBegin(e)}onBreakEnd(e){this.deps.log("Break ended:",e.id),this.deps.breakTransitionTimer?.mark("out-of-break",e.id),this.deps.breakScheduler.completeBreak(e.id),this.deps.manifestService.setActive(!1),this.deps.adBreakStatusTracker.resetAdBreakStatus(),this.flushPendingAdBreakBegin(),this.deps.emit("adbreakend",{type:"adbreakend",timestamp:Date.now(),break:e,format:this.deps.effectiveFormatOf(e)}),this.deps.onBreakSettled?.()}onBreakEndedWithoutContentPause(){this.deps.breakTransitionTimer?.settle("out-of-break"),this.deps.emit("playing",{type:"playing",timestamp:Date.now(),source:"content"})}onBreakAborted(e){if(this.deps.adPlayerController.isAdPlaying()){const t=this.deps.adBreakStatusTracker.currentBreakElapsedSec();this.deps.log(`Early return — ending break '${e.id}' at ${t.toFixed(2)}s`),this.deps.cmcdAdReporter.onBreakAborted(e.id),this.deps.adPlayerController.abortBreak(t)}else this.deps.breakScheduler.completeBreak(e.id),this.deps.onBreakSettled?.()}reportAbandonedBreak(e){const t=this.deps.adBreakStatusTracker.activeBreak;if(!t)return;const a=this.deps.adBreakStatusTracker.currentAdIndex;this.deps.diagnose("DA-BREAK-ABANDONED",`Session torn down (${e}) while break ${t.id} was still in flight`+(null!==a?"; an ad began and will never end.":"."),{breakId:t.id,cause:e,phase:this.deps.adBreakStatusTracker.adBreakStatus.phase,unbalancedAdBegin:null!==a,...null!==a?{adIndex:a}:{},...null!==this.deps.adBreakStatusTracker.currentAdTotal?{totalAds:this.deps.adBreakStatusTracker.currentAdTotal}:{}})}}

package/dist/session/SessionStarter.d.ts

@@ -0,0 +1,98 @@
+import { PlayerAdapter } from '../interfaces/PlayerAdapter';
+import { BreakManifest } from '../types/BreakManifest';
+import { OptiViewAdsMode, SessionConfig, SsaiSessionConfig, StartSessionConfig } from '../types/OptiViewAdsConfig';
+import { ManifestService } from '../services/ManifestService';
+import { BreakScheduler } from '../services/BreakScheduler';
+import { AdPlayerController } from '../services/AdPlayerController';
+import { PauseAdController } from '../services/PauseAdController';
+import { LensReporter } from '../services/LensReporter';
+import { CmcdAdReporter } from '../services/CmcdAdReporter';
+import { AdBreakStatusTracker, EmitEvent } from './AdBreakStatusTracker';
+import { BreakLifecycle, Diagnose, Log } from './BreakLifecycle';
+import { SessionState } from './SessionState';
+export interface SessionStarterDeps {
+    player: PlayerAdapter;
+    debug: boolean;
+    mode: OptiViewAdsMode;
+    hasExplicitMode: boolean;
+    continueContentDuringBreak: boolean;
+    manifestService: ManifestService | undefined;
+    breakScheduler: BreakScheduler | undefined;
+    adPlayerController: AdPlayerController | undefined;
+    pauseAdController: PauseAdController | undefined;
+    breakLifecycle: BreakLifecycle | undefined;
+    cmcdAdReporter: CmcdAdReporter;
+    lensReporter: LensReporter;
+    adBreakStatusTracker: AdBreakStatusTracker;
+    emit: EmitEvent;
+    diagnose: Diagnose;
+    log: Log;
+    endSessionInternal: (cause: string) => void;
+    notedManifestBreakIds: (manifest: {
+        breaks: Array<{
+            id: string;
+        }>;
+    }) => string[];
+}
+/** startSession() flow: validation, delivery-mode steering, GAM/SSAI start, scheduler and polling start. */
+export declare class SessionStarter {
+    private readonly state;
+    private readonly deps;
+    constructor(state: SessionState, deps: SessionStarterDeps);
+    /**
+     * Start monetization for a piece of content: begins manifest polling and (if configured)
+     * GAM session initialization. Ends any previously active session first.
+     */
+    startSession(config: StartSessionConfig): Promise<void>;
+    /**
+     * Content already playing when the session starts emits no further `playing`; the pre-roll
+     * anchor (spec `event: 'start'`) is then the session start itself.
+     */
+    private markPlaybackStartIfPlaying;
+    /**
+     * Tear down a session that failed to start and report it. `hostOk`/`hostFail` say whether this
+     * host was serving this client moments ago — a backend to escalate vs a network path to fix.
+     */
+    failSessionStart(error: unknown): Error;
+    /**
+     * Resolve the delivery mode once, on the first manifest fetch, and pin it. Manifest `delivery`
+     * rules are evaluated against the device type; an explicit constructor `mode` wins.
+     * Absent/unmatched rules and unrecognized values resolve to sgai.
+     */
+    resolveSessionDeliveryMode(manifest: BreakManifest, source?: 'manifest' | 'channel-switch'): OptiViewAdsMode;
+    /**
+     * Manifest-steered ssai: play the DAI stitched stream through the content player, keep
+     * polling the break manifest, and schedule only event-triggered breaks client-side.
+     * Throws {@link SsaiUnavailableError} when no vendor configuration supports it (no silent sgai fallback).
+     */
+    startSteeredSsaiSession(manifest: BreakManifest, config: SessionConfig, startStep: (step: string) => void): Promise<void>;
+    private createSsaiController;
+    /** Start the break scheduler with the SDK's standard callbacks (both sgai and steered ssai). */
+    startBreakScheduler(): void;
+    /** Start manifest polling. Ordinary updates keep the current delivery mode. */
+    startManifestPolling(): void;
+    applyPendingChannelSwitch(): void;
+    private applyManifestUpdate;
+    private diagnoseIgnoredDeliveryModeChange;
+    /**
+     * A poll returned a manifest of another channel: re-align the ad setup after the current break
+     * settles (the latest poll wins). Scheduler ledgers are rebuilt, GAM is re-opened when its
+     * identity changes, CMCD/Lens roll to the new channel, and startup/runtime asset-parameter
+     * layers are re-applied. Delivery mode is resolved again for the new channel. Before playback starts,
+     * the new manifest's `adStartDelay` applies; afterwards, the delay in effect stays.
+     */
+    private switchChannel;
+    private emitChannelChange;
+    private applySameModeChannelSwitch;
+    private switchToSteeredSsai;
+    private switchToSgai;
+    /**
+     * Resolve the GAM stream identity from the manifest and open the IMA/DAI session. GAM failure
+     * is non-fatal: non-GAM breaks still schedule, only the GAM assets are skipped.
+     */
+    startGamForManifest(manifest: BreakManifest, sessionParams: Record<string, string> | undefined, startStep: (step: string) => void): Promise<void>;
+    /** SSAI session: create the IMA DAI stream, load the stitched master, wire timed-metadata forwarding. Throws on failure. */
+    startSsaiSession(config: SsaiSessionConfig, generation: number): Promise<void>;
+    /** Whether a startSession() begun at {@link generation} was invalidated by a later end/destroy/restart. */
+    isStaleStart(generation: number): boolean;
+}

package/dist/session/SessionStarter.js

@@ -0,0 +1 @@
+import{getPreRollDelay as e}from"../types/BreakManifest";import{manifestHasGamAssets as s,resolveGamVendorConfiguration as t}from"../services/resolveGamVendorConfiguration";import{SsaiController as i}from"../services/SsaiController";import{resolveUrlOrigin as a}from"../services/urlOrigin";import{filterSsaiClientBreaks as r,resolveStitchedStreamVendor as n,SsaiUnavailableError as o}from"../services/resolveDeliveryMode";import{detectDeviceType as d}from"../services/detectDeviceType";import{decideDeliveryMode as l,detectChannelSwitch as h,gamPodIdentityChanged as c}from"../services/channelSwitch";function p(e){return"stitcherUrl"in e}function S(e){return"string"==typeof e&&""!==e.trim()}export class SessionStarter{constructor(e,s){this.state=e,this.deps=s}async startSession(s){if("ssai"===this.deps.mode){if(!p(s)||!S(s.stitcherUrl))throw new Error('[OptiViewAds] mode "ssai" requires a stitcherUrl in startSession().')}else if(p(s)||!S(s.manifestUrl))throw new Error("[OptiViewAds] startSession requires a manifestUrl (the full break-manifest URL).");this.state.sessionActive&&(this.deps.log("Ending previous session before starting new one"),this.deps.endSessionInternal("session-restart"));const t=this.state.sessionGeneration;if(this.state.sessionActive=!0,this.deps.lensReporter.startSession(),p(s))return s.adInsertionType&&this.deps.diagnose("DA-INSERTION-TYPE-IGNORED-SSAI",`adInsertionType "${s.adInsertionType}" ignored in SSAI mode; the stitcher controls ad insertion.`,{adInsertionType:s.adInsertionType}),void await this.startSsaiSession(s,t);const i=s.manifestUrl;this.state.sessionConfig=s,this.state.manifestOrigin=a(i),this.deps.manifestService.setManifestUrl(i),this.deps.log("Session starting, manifest URL:",i);const r=Date.now(),n=e=>{this.deps.diagnose("DA-SESSION-STARTING",`Session start: ${e}`,{step:e,manifestUrl:i,elapsedMs:Date.now()-r})};n("begin");const o=s.assetParameters;let d;this.deps.adPlayerController.setSessionAssetParameters(o),this.deps.adPlayerController.setSessionAssetParameterMacros(s.assetParameterMacros),this.state.configSummary.gam&&(this.state.configSummary.gam={...this.state.configSummary.gam,hasAssetParameters:!!o}),n("manifest-fetch");try{d=await this.deps.manifestService.fetchManifest()}catch(e){if(this.isStaleStart(t))return;throw this.failSessionStart(e)}if(this.deps.cmcdAdReporter.onSessionStart(d),!this.isStaleStart(t))if(this.state.sessionManifest=d,"ssai"!==this.resolveSessionDeliveryMode(d))try{if(await this.startGamForManifest(d,o,n),this.isStaleStart(t))return;const a=s.adInsertionType;this.deps.adPlayerController.setBreakResumePolicy(a,d.timebase,this.deps.continueContentDuringBreak),this.deps.diagnose("DA-INSERTION-TYPE-RESOLVED",void 0===a?`Ad insertion type: unset — the manifest's resumeOffset drives the resume point (timebase: ${d.timebase})`:`Ad insertion type: ${a}, client-set (timebase: ${d.timebase})`,{adInsertionType:a??null,source:void 0===a?"unset":"client",timebase:d.timebase}),n("scheduling"),this.deps.breakScheduler.updateManifest(d),this.deps.pauseAdController.updateManifest(d),this.state.pauseAdTickInterval=setInterval(()=>this.deps.pauseAdController?.tick(),250);const r=(d.adStartDelay??0)>0?void 0:d.breaks.find(s=>0===e(s));r?(this.deps.adPlayerController.holdContentForPreRoll(r),this.state.heldImmediatePreRollId=r.id,this.deps.breakScheduler.markPlaybackStart()):this.markPlaybackStartIfPlaying(),this.startBreakScheduler(),this.startManifestPolling(),this.deps.diagnose("DA-SESSION-STARTED",`Session active for manifest ${i}`,{manifestUrl:i}),this.deps.log("Session active")}catch(e){if(this.isStaleStart(t))return;throw this.failSessionStart(e)}else await this.startSteeredSsaiSession(d,s,n)}markPlaybackStartIfPlaying(){this.deps.player.paused||this.deps.breakScheduler.markPlaybackStart()}failSessionStart(e){const s=e instanceof Error?e:new Error(String(e)),t=this.deps.manifestService?.takeLastFailure();return this.deps.diagnose("DA-MANIFEST-FETCH-FAILED",s.message,t?{...t}:void 0),this.state.sessionActive=!1,this.deps.cmcdAdReporter.onSessionEnd(),this.deps.lensReporter.endSession(),s}resolveSessionDeliveryMode(e,s="manifest"){const t=this.state.sessionDeliveryMode,i=l(e,d(),this.deps.hasExplicitMode?this.deps.mode:null,s);return null!==i.unknownMode&&this.deps.diagnose("DA-DELIVERY-MODE-UNKNOWN",`Delivery rule ${i.ruleIndex} carries unrecognized mode "${i.unknownMode}"; using sgai.`,{unknownMode:i.unknownMode,ruleIndex:i.ruleIndex}),this.deps.hasExplicitMode&&i.manifestMode!==i.mode&&this.deps.diagnose("DA-DELIVERY-MODE-OVERRIDDEN",`Manifest delivery rules resolve "${i.manifestMode}" but the explicit config mode "${i.mode}" takes precedence.`,{manifestMode:i.manifestMode,configuredMode:i.mode}),this.state.sessionDeliveryMode=i.mode,this.deps.diagnose("DA-DELIVERY-MODE-RESOLVED",`Delivery mode: ${i.mode}`,{mode:i.mode,ruleIndex:i.ruleIndex,source:i.source,..."channel-switch"===s?{previousMode:t}:{}}),i.mode}async startSteeredSsaiSession(e,s,t){const i=n(e.vendorConfiguration);if(!i){const e="Manifest selected ssai delivery but no vendor configuration provides a stitched stream (no gam entry with an assetKey).";throw this.deps.diagnose("DA-SSAI-UNAVAILABLE",e),this.deps.manifestService.reset(),this.state.sessionActive=!1,new o(e)}try{t("ssai-live-stream"),this.state.steeredSsaiActive=!0,this.state.ssaiController=this.createSsaiController(i.networkCode),await this.state.ssaiController.startSteered(i,s.assetParameters,s.assetParameterMacros),t("scheduling");const a=r(e);this.deps.adPlayerController.setBreakResumePolicy(s.adInsertionType,e.timebase,!1),this.deps.breakScheduler.updateManifest(a),this.deps.pauseAdController.updateManifest(a),this.state.pauseAdTickInterval=setInterval(()=>this.deps.pauseAdController?.tick(),250),this.markPlaybackStartIfPlaying(),this.startBreakScheduler(),this.startManifestPolling(),this.deps.diagnose("DA-SESSION-STARTED",`SSAI session active (manifest-steered) for ${s.manifestUrl}`,{manifestUrl:s.manifestUrl}),this.deps.log("SSAI session active (manifest-steered)")}catch(e){const s=e instanceof Error?e:new Error(String(e));throw this.deps.diagnose("DA-SSAI-SESSION-FAILED",s.message),this.state.steeredSsaiActive=!1,this.deps.manifestService.reset(),this.state.sessionActive=!1,s}}createSsaiController(e){return new i(this.deps.player,{gam:this.state.steeredSsaiOptions?.streamActivityMonitorId?{streamActivityMonitorId:this.state.steeredSsaiOptions.streamActivityMonitorId}:{},ssai:{networkCode:e},maxBitrate:this.state.steeredSsaiOptions?.maxBitrate,autoplay:this.state.steeredSsaiOptions?.autoplay,debug:this.deps.debug},{emit:(e,s)=>this.deps.emit(e,s),diagnose:(e,s,t)=>this.deps.diagnose(e,s,t),log:(...e)=>this.deps.log(...e)})}startBreakScheduler(){this.deps.breakScheduler.start((e,s)=>{this.deps.breakLifecycle.onBreakStart(e,s)},e=>!this.deps.adPlayerController.isAdPlaying()&&(this.deps.adPlayerController.preload(e).catch(s=>{this.deps.diagnose("DA-PRELOAD-FAILED",s instanceof Error?s.message:String(s),{breakId:e.id})}),!0),(e,s,t)=>{this.deps.adBreakStatusTracker.onBreakWarning(e,s,t)},e=>{this.deps.breakLifecycle.onBreakAborted(e)})}startManifestPolling(){this.deps.manifestService.startPolling(e=>{if(!this.state.sessionActive)return;const s=this.deps.notedManifestBreakIds(e);this.deps.diagnose("DA-MANIFEST-POLLED","Manifest polled",{breaks:e.breaks.length,newBreakIds:s,pollingIntervalSeconds:this.deps.manifestService.currentPollingIntervalSeconds});const t=this.state.sessionManifest,i=t?h(t,e):null;if(this.state.pendingChannelSwitch||i&&this.deps.breakScheduler.getActiveBreak())return this.state.pendingChannelSwitch=e,void this.deps.log("Channel switch deferred until the active break ends");i?this.switchChannel(e,i):this.applyManifestUpdate(e)},e=>{this.state.sessionActive&&this.deps.diagnose("DA-MANIFEST-POLL-FAILED",e.message)})}applyPendingChannelSwitch(){if(!this.state.sessionActive||!this.state.pendingChannelSwitch)return;const e=this.state.pendingChannelSwitch;this.state.pendingChannelSwitch=null;const s=h(this.state.sessionManifest,e);s?this.switchChannel(e,s):this.applyManifestUpdate(e)}applyManifestUpdate(e){this.diagnoseIgnoredDeliveryModeChange(e);const s=t(e);this.state.steeredSsaiActive?this.state.ssaiController?.setManifestAssetParameters(s.ssai?.assetParameters):this.deps.adPlayerController.setManifestAssetParameters(s.sgaiAssetParameters);const i=this.state.steeredSsaiActive?r(e):e;this.deps.breakScheduler.updateManifest(i),this.deps.pauseAdController.updateManifest(i)}diagnoseIgnoredDeliveryModeChange(e){if(!this.state.sessionDeliveryMode)return;const s=l(e,d(),null,"manifest");s.manifestMode!==this.state.sessionDeliveryMode&&this.deps.diagnose("DA-DELIVERY-MODE-CHANGE-IGNORED",`Polled manifest resolves delivery mode "${s.manifestMode}" but "${this.state.sessionDeliveryMode}" is pinned for this session.`,{polledMode:s.manifestMode,pinnedMode:this.state.sessionDeliveryMode})}async switchChannel(e,s){if(this.state.channelSwitchInFlight)return;const t=this.state.sessionConfig,i=this.state.sessionManifest,a={previousChannelId:s.previousChannelId,channelId:s.channelId,reason:s.reason,manifestUrl:t.manifestUrl};this.deps.diagnose("DA-MANIFEST-CHANNEL-CHANGED",`Manifest channel changed (${s.reason}): ${s.previousChannelId??"none"} -> ${s.channelId??"none"}`,a),this.state.sessionManifest=e,this.state.channelSwitchInFlight=!0;const r=this.state.sessionGeneration,n=this.state.sessionDeliveryMode??"sgai";try{let s=this.resolveSessionDeliveryMode(e,"channel-switch");if(this.deps.cmcdAdReporter.onSessionEnd(),this.deps.cmcdAdReporter.onSessionStart(e),this.deps.lensReporter.endSession(),this.deps.lensReporter.startSession(),"ssai"===s&&"sgai"===n){const a=await this.switchToSteeredSsai(e,t);if(this.isStaleStart(r))return;a||(s="sgai",this.state.sessionDeliveryMode="sgai",await this.applySameModeChannelSwitch(i,e,t,r))}else"sgai"===s&&"ssai"===n?await this.switchToSgai(e,t,r):await this.applySameModeChannelSwitch(i,e,t,r);if(this.isStaleStart(r))return}finally{this.state.channelSwitchInFlight=!1}this.emitChannelChange({...a,previousDeliveryMode:n,deliveryMode:this.state.sessionDeliveryMode??n})}emitChannelChange(e){this.deps.emit("adchannelchange",{type:"adchannelchange",timestamp:Date.now(),...e})}async applySameModeChannelSwitch(e,s,i,a){const n=this.state.steeredSsaiActive,o=n?r(s):s;if(this.deps.breakScheduler.resetForChannelSwitch(o),this.deps.pauseAdController.updateManifest(o),this.deps.adPlayerController.setBreakResumePolicy(i.adInsertionType,s.timebase,this.deps.continueContentDuringBreak),!n&&c(e,s)){const e=this.deps.adPlayerController.updatedAssetParameters;if(this.deps.adPlayerController.endGamSession(),this.deps.adPlayerController.setSessionAssetParameters(i.assetParameters),this.deps.adPlayerController.setSessionAssetParameterMacros(i.assetParameterMacros),await this.startGamForManifest(s,i.assetParameters,e=>{this.deps.diagnose("DA-SESSION-STARTING",`Channel switch: ${e}`,{step:e,manifestUrl:i.manifestUrl})}),this.isStaleStart(a))return;e&&this.deps.adPlayerController.updateAssetParameters(e)}else if(n){const e=t(s);this.state.ssaiController?.setManifestAssetParameters(e.ssai?.assetParameters)}else{const e=t(s);this.deps.adPlayerController.setManifestAssetParameters(e.sgaiAssetParameters)}}async switchToSteeredSsai(e,s){const t=n(e.vendorConfiguration);if(!t)return this.deps.diagnose("DA-SSAI-UNAVAILABLE","Channel switch resolved ssai delivery but no vendor configuration provides a stitched stream; the session stays in sgai.",{manifestUrl:s.manifestUrl,previousMode:"sgai"}),!1;const i=this.deps.adPlayerController,a=i.updatedAssetParameters;i.stopActiveBreak(),i.releaseContentHold(),i.endGamSession(),i.setSessionAssetParameters(s.assetParameters),i.setSessionAssetParameterMacros(s.assetParameterMacros),a&&i.updateAssetParameters(a);const o=this.createSsaiController(t.networkCode);this.state.ssaiController=o,this.state.steeredSsaiActive=!0,this.deps.diagnose("DA-SESSION-STARTING","Channel switch: ssai-live-stream",{step:"ssai-live-stream",manifestUrl:s.manifestUrl});try{await o.startSteered(t,s.assetParameters,s.assetParameterMacros),a&&o.updateAssetParameters(a);const n=r(e);return this.deps.breakScheduler.resetForChannelSwitch(n),this.deps.pauseAdController.updateManifest(n),i.setBreakResumePolicy(s.adInsertionType,e.timebase,!1),!0}catch(e){const s=e instanceof Error?e.message:String(e);return this.deps.diagnose("DA-SSAI-SESSION-FAILED",s),o.stop(),delete this.state.ssaiController,this.state.steeredSsaiActive=!1,!1}}async switchToSgai(e,s,t){this.state.ssaiController?.stop(),delete this.state.ssaiController,this.state.steeredSsaiActive=!1,this.deps.breakScheduler.resetForChannelSwitch(e),this.deps.pauseAdController.updateManifest(e);const i=this.deps.adPlayerController;i.setBreakResumePolicy(s.adInsertionType,e.timebase,this.deps.continueContentDuringBreak);const a=i.updatedAssetParameters;i.endGamSession(),i.setSessionAssetParameters(s.assetParameters),i.setSessionAssetParameterMacros(s.assetParameterMacros),await this.startGamForManifest(e,s.assetParameters,e=>{this.deps.diagnose("DA-SESSION-STARTING",`Channel switch: ${e}`,{step:e,manifestUrl:s.manifestUrl})}),this.isStaleStart(t)||a&&i.updateAssetParameters(a)}async startGamForManifest(e,i,a){const r=t(e);if(this.deps.adPlayerController.setManifestAssetParameters(r.sgaiAssetParameters),r.unknownTypes.length>0&&this.deps.diagnose("DA-VENDOR-CONFIG-UNKNOWN-TYPE",`Ignored ${r.unknownTypes.length} vendorConfiguration `+(1===r.unknownTypes.length?"entry":"entries")+" with unrecognised type: "+`${r.unknownTypes.join(", ")}.`,{types:r.unknownTypes}),this.deps.adPlayerController.isGamEnabled())if(r.identity){this.deps.diagnose("DA-GAM-CONFIG-RESOLVED",`GAM session identity: network ${r.identity.networkCode}, custom asset ${r.identity.customAssetKey}`,{networkCode:r.identity.networkCode,customAssetKey:r.identity.customAssetKey,channelId:e.channelId,duplicateEntriesIgnored:r.duplicateGam});try{a("gam-init"),await this.deps.adPlayerController.startGamSession(r.identity,i),this.deps.log("GAM session started")}catch(e){this.deps.diagnose("DA-GAM-SESSION-FAILED",e instanceof Error?e.message:String(e))}}else s(e)&&this.deps.diagnose("DA-GAM-CONFIG-MISSING",'The break manifest carries GAM pod assets but no usable "gam" vendorConfiguration entry; those assets will be skipped.',{reason:r.reason});else s(e)&&this.deps.diagnose("DA-GAM-CONFIG-MISSING","The break manifest carries GAM pod assets but GAM is disabled for this session (gam.enabled === false); those assets will be skipped.",{reason:"gam-disabled"})}async startSsaiSession(e,s){try{if(this.state.stitcherOrigin=a(e.stitcherUrl),this.state.configSummary.gam&&(this.state.configSummary.gam={...this.state.configSummary.gam,hasAssetParameters:!!e.assetParameters}),await this.state.ssaiController.start(e),this.isStaleStart(s))return;this.deps.diagnose("DA-SESSION-STARTED",`SSAI session active for ${e.stitcherUrl}`,{stitcherUrl:e.stitcherUrl}),this.deps.log("SSAI session active")}catch(e){if(this.isStaleStart(s))return;const t=e instanceof Error?e:new Error(String(e));throw this.deps.diagnose("DA-SSAI-SESSION-FAILED",t.message),this.state.sessionActive=!1,this.deps.cmcdAdReporter.onSessionEnd(),this.deps.lensReporter.endSession(),t}}isStaleStart(e){return e!==this.state.sessionGeneration&&(this.deps.log("Session start aborted — the session ended or was replaced while starting"),!0)}}

package/dist/session/SessionState.d.ts

@@ -0,0 +1,37 @@
+import { OptiViewAdsMode, SessionConfig } from '../types/OptiViewAdsConfig';
+import { BreakManifest } from '../types/BreakManifest';
+import { SsaiController } from '../services/SsaiController';
+import { ConfigSummary } from '../diagnostics/DiagnosticEvent';
+/** Mutable session state owned by `OptiViewAds` and shared by reference with the `session/` modules. */
+export declare class SessionState {
+    sessionActive: boolean;
+    /**
+     * Bumped by `endSessionInternal`. startSession() re-checks it after every await: a
+     * mismatch means the session was ended or replaced mid-flight. A boolean cannot express
+     * "replaced" — the new session sets it back to true before the stale fetch resolves.
+     */
+    sessionGeneration: number;
+    sessionDeliveryMode: OptiViewAdsMode | null;
+    steeredSsaiActive: boolean;
+    steeredSsaiOptions: {
+        maxBitrate: number | undefined;
+        autoplay: boolean;
+        streamActivityMonitorId: string | undefined;
+    } | null;
+    ssaiController?: SsaiController;
+    pauseAdTickInterval: ReturnType<typeof setInterval> | null;
+    configSummary: ConfigSummary;
+    /**
+     * Origin of the polled URL, derived per startSession() and merged into the config summary
+     * (captured at construction, before any URL exists). Kept after endSession() for later reports.
+     */
+    manifestOrigin: string | null;
+    stitcherOrigin: string | null;
+    heldImmediatePreRollId: string | null;
+    snapbackSeekInFlight: boolean;
+    sessionConfig: SessionConfig | null;
+    sessionManifest: BreakManifest | null;
+    channelSwitchInFlight: boolean;
+    pendingChannelSwitch: BreakManifest | null;
+    clearSessionIdentity(): void;
+}

package/dist/session/SessionState.js

@@ -0,0 +1 @@
+export class SessionState{constructor(){this.sessionActive=!1,this.sessionGeneration=0,this.sessionDeliveryMode=null,this.steeredSsaiActive=!1,this.steeredSsaiOptions=null,this.pauseAdTickInterval=null,this.manifestOrigin=null,this.stitcherOrigin=null,this.heldImmediatePreRollId=null,this.snapbackSeekInFlight=!1,this.sessionConfig=null,this.sessionManifest=null,this.channelSwitchInFlight=!1,this.pendingChannelSwitch=null}clearSessionIdentity(){this.sessionDeliveryMode=null,this.sessionManifest=null,this.channelSwitchInFlight=!1,this.pendingChannelSwitch=null}}