ogplayer 0.1.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+# OGPlayer Commercial License
+
+The OGPlayer SDK is commercial software by Inverse DOO — **free to
+evaluate** (the player renders an OGPlayer watermark); **production use
+requires a license key**.
+
+Full terms: https://ogplayer.tv/terms/ · Licensing: sales@ogplayer.tv

package/README.md

@@ -0,0 +1,129 @@
+# OGPlayer — web SDK
+
+One video player API across **Android, iOS and the web**. This package is the
+web implementation: the same model types, listener callbacks, error codes and
+UI behavior as the Android SDK (the reference platform), built on web
+standards.
+
+> OGPlayer is a product of Inverse DOO.
+
+## How the web version works (for non-web people)
+
+- **Language:** TypeScript — typed like Kotlin/Swift, compiles to JavaScript.
+- **Playback:** the browser's `<video>` element plays the media. HLS streams
+  are fed to it through [hls.js](https://github.com/video-dev/hls.js) using
+  Media Source Extensions (the web's ExoPlayer, used by YouTube/Twitch-class
+  players); Safari plays HLS natively so hls.js steps aside there.
+  Progressive MP4 plays directly. This is the exact architecture JW Player,
+  Video.js and Mux use.
+- **UI:** a **custom element** `<og-player>` — the web-standard way to ship a
+  reusable component that works identically in plain HTML, React, Vue and
+  Angular, with all styles isolated in a shadow DOM so host-page CSS can't
+  break the player (and vice versa). The web parallel of "Compose-only /
+  SwiftUI-only": one modern UI technology, no legacy widgets.
+- **License:** the same `OGP1.…` offline keys as Android/iOS, verified with
+  the browser's built-in WebCrypto against the same P-256 public key — one
+  license unlocks all three platforms. On the web, `apps` patterns bind to
+  the page **hostname**.
+
+## Quick start
+
+```html
+<script type="module">
+  import { OGPlayer } from "ogplayer";
+
+  const player = new OGPlayer({ licenseKey: "OGP1...." });
+  document.querySelector("og-player").player = player;
+
+  player.addListener({
+    onStateChanged: (s) => console.log(s),
+    onProgress: (positionMs, bufferedMs, durationMs) => {},
+  });
+  player.load({
+    url: "https://example.com/stream.m3u8",
+    title: "My movie",
+    contentRatings: [{ age: "SIXTEEN" }, { descriptor: "FEAR" }],
+    sideloadedSubtitles: [{ url: "/subs/en.vtt", language: "en", label: "English", isDefault: true }],
+  });
+</script>
+
+<og-player style="width:100%;aspect-ratio:16/9"></og-player>
+```
+
+Overlays (watermarks, logos) use the nine named slots, mirroring
+Android/iOS `OverlaySlot` — including the clearance choreography around the
+controls and rating icons:
+
+```html
+<og-player>
+  <img slot="top-end" src="/logo.png" width="90">
+</og-player>
+```
+
+Custom action icons (max 8, inline in the top-end control row, hide with the
+controls — same contract as Android/iOS):
+
+```js
+el.config = {
+  customActions: [
+    { svg: shareIconSvg, accessibilityLabel: "Share", onClick: () => share() },
+  ],
+};
+```
+
+## How it ships
+
+1. **npm** (the web's Maven Central): `npm install ogplayer` — ESM module
+   with TypeScript types, hls.js pulled in as a dependency. Publishing is one
+   `npm publish` from CI; scoped to the `@ogplayer` org.
+2. **CDN script tag** for no-build websites: `dist/ogplayer.global.js` is a
+   single self-contained file (hls.js included) exposing `window.OGPlayerSDK`.
+   Hosted on our own domain (e.g. `cdn.ogplayer.tv`) or jsDelivr once public.
+
+```html
+<script src="https://cdn.ogplayer.tv/0.1.0/ogplayer.global.js"></script>
+<script>
+  const player = new OGPlayerSDK.OGPlayer();
+  document.querySelector("og-player").player = player;
+  player.load({ url: "…" });
+</script>
+```
+
+## Browser support
+
+Evergreen Chrome / Edge / Firefox / Safari 16+ (desktop & mobile). Every API
+used (MSE, custom elements, shadow DOM, WebCrypto, Fullscreen) has been
+baseline for years; no polyfills.
+
+## Development
+
+```
+npm install
+npm run build      # dist/ogplayer.js (ESM) + dist/ogplayer.global.js (CDN) + types
+npm test           # node --test (license crypto, matchers)
+npm run dev        # rebuild + serve demos at http://localhost:8123/demo/
+```
+
+`scripts/smoke.mjs` runs the demo page in headless Chromium (playwright)
+and asserts the engine reaches READY with zero page errors.
+
+## Feature parity vs Android (reference)
+
+| Feature | Android | iOS | Web |
+|---|---|---|---|
+| Transport / state / listeners | ✅ | ✅ | ✅ same names |
+| Analytics events | ✅ | ✅ | ✅ same shapes |
+| Error taxonomy | ✅ | ✅ | ✅ same codes |
+| HLS + ABR qualities | ✅ | ✅ | ✅ (hls.js/native) |
+| DASH | ✅ | — | ⏳ later (dash.js/Shaka) |
+| Live & DVR | ✅ | ✅ | ✅ |
+| Embedded + sideloaded subtitles | ✅ | ✅ | ✅ (native cue rendering) |
+| Audio tracks | ✅ | ✅ | ✅ |
+| Offline license (shared keypair) | ✅ | ✅ | ✅ WebCrypto |
+| Controls chrome (tokens) | ✅ | ✅ | ✅ same tokens/icons |
+| Title / NICAM ratings / watermark slots | ✅ | ✅ | ✅ incl. reflow choreography |
+| Custom action icons (≤8) | ✅ | ✅ | ✅ |
+| Ads (IMA / FreeWheel) | ✅ | ✅ | ⏳ SPI defined, provider later |
+| DRM | Widevine/PlayReady | FairPlay | ⏳ EME later |
+| Casting | Chromecast module | AirPlay | ⏳ Remote Playback API later |
+| Trick-play thumbnails | ✅ | ✅ | ⏳ |

package/dist/ads/freewheel-provider.d.ts

@@ -0,0 +1,159 @@
+import type { AdBreakConfig } from "./types.js";
+import type { AdsProvider, AdsProviderCallbacks } from "./provider.js";
+/**
+ * Native FreeWheel (MRM) implementation of the OGPlayer ads SPI — the web
+ * counterpart of Android's `FreewheelAdsProvider` (whose `FreewheelSession`
+ * this mirrors: request → slot schedule → preroll/midroll/catch-up/postroll,
+ * a watchdog that abandons a slot that never renders, exactly-once content
+ * resume per gate).
+ *
+ * FreeWheel's HTML5 SDK (`AdManager.js`) is **customer-licensed** and is
+ * never bundled: it is loaded at runtime from FreeWheel's CDN (the same way
+ * FW customers' own sites load it), overridable via `adManagerUrl`. The
+ * alternative integration — FW server as a VMAP tag through IMA — needs no
+ * FW SDK at all: pass the same `FreewheelConfig` to `ImaAdsProvider`.
+ */
+interface FwSlot {
+    play(): void;
+    stop?(): void;
+    pause?(): void;
+    resume?(): void;
+    getTimePosition(): number;
+    getTimePositionClass(): string;
+    getCustomId(): string;
+    getAdInstances?(): FwAdInstance[];
+    getPlayheadTime?(): number;
+    getTotalDuration?(): number;
+}
+interface FwAdInstance {
+    getAdId?(): number | string;
+    getDuration?(): number;
+    getActiveCreativeRendition?(): {
+        getDuration?(): number;
+    } | null;
+    getRendererController?(): {
+        skipCurrentAd?(): void;
+    } | null;
+}
+interface FwEvent {
+    success?: boolean;
+    slot?: FwSlot;
+    adInstance?: FwAdInstance;
+    errorInfo?: unknown;
+    [k: string]: unknown;
+}
+interface FwContext {
+    setProfile(profile: string): void;
+    setVideoAsset(id: string, durationSec: number, networkId?: number): void;
+    setSiteSection(id: string, networkId?: number): void;
+    addKeyValue(key: string, value: string): void;
+    setParameter(name: string, value: string, level: unknown): void;
+    registerVideoDisplayBase(elementId: string): void;
+    setContentVideoElement?(el: HTMLVideoElement): void;
+    addEventListener(type: string, cb: (e: FwEvent) => void): void;
+    removeEventListener?(type: string, cb: (e: FwEvent) => void): void;
+    submitRequest(): void;
+    getTemporalSlots(): FwSlot[];
+    setVideoState?(state: unknown): void;
+    dispose?(): void;
+}
+interface FwSdkNamespace {
+    AdManager: new () => {
+        setNetwork(id: number): void;
+        setServer(url: string): void;
+        newContext(): FwContext;
+    };
+    EVENT_REQUEST_COMPLETE: string;
+    EVENT_SLOT_STARTED: string;
+    EVENT_SLOT_ENDED: string;
+    EVENT_AD_IMPRESSION: string;
+    EVENT_AD_IMPRESSION_END?: string;
+    EVENT_AD_PAUSE?: string;
+    EVENT_AD_RESUME?: string;
+    EVENT_ERROR?: string;
+    TIME_POSITION_CLASS_PREROLL: string;
+    TIME_POSITION_CLASS_MIDROLL: string;
+    TIME_POSITION_CLASS_POSTROLL: string;
+    TIME_POSITION_CLASS_OVERLAY?: string;
+    PARAMETER_LEVEL_GLOBAL: unknown;
+    VIDEO_STATE_PLAYING?: unknown;
+    VIDEO_STATE_PAUSED?: unknown;
+    VIDEO_STATE_COMPLETED?: unknown;
+}
+declare global {
+    interface Window {
+        tv?: {
+            freewheel?: {
+                SDK?: FwSdkNamespace;
+            };
+        };
+    }
+}
+/** Options for {@link FreewheelAdsProvider}. */
+export interface FreewheelAdsProviderOptions {
+    /** Where to load FreeWheel's AdManager.js from; defaults to FW's CDN
+     * (`libs/adm/7.5.0`). Point it at the version your network is on. */
+    adManagerUrl?: string;
+}
+export declare class FreewheelAdsProvider implements AdsProvider {
+    private readonly options;
+    constructor(options?: FreewheelAdsProviderOptions);
+    /** FW's HTML5 VideoRenderer plays ads IN the content element by design
+     * (`this._adVideo = getContentVideoElement()` in AdManager.js) — the
+     * engine releases the element around breaks and restores content after. */
+    readonly usesContentVideoElement = true;
+    private video;
+    private container;
+    private callbacks;
+    private sdk;
+    private context;
+    private cfg;
+    private generation;
+    private destroyed;
+    private prerollSlots;
+    private midrollSlots;
+    private postrollSlots;
+    private catchUpQueue;
+    private flow;
+    private contentGateOpened;
+    private pendingStart;
+    private currentSlot;
+    private currentBreakType;
+    private currentAd;
+    private currentInstance;
+    private adIndexInSlot;
+    private totalAdsInSlot;
+    private requestTimer;
+    private watchdogTimer;
+    private progressTimer;
+    private lastContentPosMs;
+    private videoListeners;
+    attach(video: HTMLVideoElement, adContainer: HTMLElement, callbacks: AdsProviderCallbacks): void;
+    requestAds(config: AdBreakConfig, autostart: boolean): void;
+    private submitRequest;
+    private onRequestComplete;
+    private publishCuePoints;
+    private playNextPreroll;
+    private openContentGateOnce;
+    private playSlot;
+    private onSlotEnded;
+    private onAdImpression;
+    private bindContentWatchers;
+    private unbindContentWatchers;
+    contentDidComplete(): void;
+    private playNextPostroll;
+    private armWatchdog;
+    private cancelWatchdog;
+    private abandonSlot;
+    private startProgressTicker;
+    private stopProgressTicker;
+    startPendingBreak(): boolean;
+    pause(): void;
+    resume(): void;
+    skip(): void;
+    click(): void;
+    resize(): void;
+    private fail;
+    destroy(): void;
+}
+export {};

package/dist/ads/freewheel.d.ts

@@ -0,0 +1,52 @@
+import type { AdBreakConfig } from "./types.js";
+/**
+ * FreeWheel ad configuration — the web counterpart of the Android/iOS
+ * `FreewheelConfig`, field-for-field. Pure data: no FreeWheel SDK
+ * dependency.
+ *
+ * Two integration options, mirroring the mobile SDKs:
+ *  (a) **FreeWheel as VMAP through IMA** — `freewheelVmapTagUrl(config)`
+ *      builds the network's `/ad/g/1` VMAP request; play it with
+ *      `ImaAdsProvider` via `adBreaks: { adTagUri }`. Works today.
+ *  (b) A native FreeWheel HTML5 provider (their customer-licensed
+ *      AdManager.js) — ships later as an adapter, like the iOS one.
+ *
+ * Consent and identity parameters (`_fw_gdpr`, `_fw_gdpr_consent`, device
+ * ids…) are the HOST's responsibility via `globalParameters` — the SDK
+ * never fabricates consent; it adds only the `pvrn`/`vprn` randomizers.
+ */
+export interface FreewheelConfig extends AdBreakConfig {
+    /** FreeWheel ad server base URL, e.g. `https://<your-network>.v.fwmrm.net`. */
+    serverUrl: string;
+    networkId: number;
+    /** FreeWheel profile, e.g. `<networkId>:<your_profile>`. */
+    profile: string;
+    siteSectionId: string;
+    videoAssetId: string;
+    /** Content duration in ms — explicit, never inferred. */
+    videoDurationMs: number;
+    /** GLOBAL-level request parameters, host-supplied verbatim. NOTE:
+     * FreeWheel's `flag` list is space-separated — pass real spaces
+     * (" play sltp …"); they encode to the `+` signs FreeWheel expects. */
+    globalParameters?: Record<string, string>;
+    /** Ad request timeout, default 5000. */
+    requestTimeoutMs?: number;
+    /** How close content time must get to a midroll cue, default 1000. */
+    midrollToleranceMs?: number;
+    /** Seeks shorter than this never trigger midroll catch-up, default 2000. */
+    seekThresholdMs?: number;
+    /** What plays after seeking across midroll cues, default "MOST_RECENT". */
+    seekCatchUpPolicy?: "NONE" | "MOST_RECENT" | "ALL_MOST_RECENT_FIRST";
+    /** AdInfo duration when FW doesn't expose one, default 15000. */
+    fallbackAdDurationMs?: number;
+    /** Renderer start watchdog before a slot is abandoned, default 10000. */
+    adStartTimeoutMs?: number;
+}
+/** True when an `AdBreakConfig` is a {@link FreewheelConfig}. */
+export declare function isFreewheelConfig(c: AdBreakConfig): c is FreewheelConfig;
+/**
+ * Build the VMAP tag URL for a FreeWheel network — integration option (a):
+ * feed the result to the IMA provider as a plain ad tag. Matches the request
+ * shape of the Android `asVmapTag` reference implementation.
+ */
+export declare function freewheelVmapTagUrl(cfg: FreewheelConfig): string;

package/dist/ads/ima.d.ts

@@ -0,0 +1,157 @@
+import type { AdBreakConfig } from "./types.js";
+import type { AdsProvider, AdsProviderCallbacks } from "./provider.js";
+/**
+ * Google IMA (HTML5) implementation of the OGPlayer ads SPI — the web
+ * counterpart of Android's `ImaAdsProvider` / iOS's `IMAAdsProvider`.
+ * Client-side VAST/VMAP: IMA plays the ad in its own layer over the paused
+ * content element, then hands playback back.
+ *
+ * The IMA SDK script is loaded on demand from Google's servers (required by
+ * its terms — it cannot be bundled). As on the other platforms, IMA renders
+ * its own skip / clickthrough UI; the SDK draws the yellow bar and AD chip.
+ */
+interface ImaAd {
+    getAdId(): string;
+    getDuration(): number;
+    getAdPodInfo(): {
+        getAdPosition(): number;
+        getTotalAds(): number;
+        getPodIndex(): number;
+    };
+    getSkipTimeOffset(): number;
+}
+interface ImaAdEvent {
+    type: string;
+    getAd(): ImaAd | null;
+    getAdData(): {
+        currentTime?: number;
+        duration?: number;
+    } | null;
+}
+interface ImaAdError {
+    getErrorCode(): number;
+    getMessage(): string;
+}
+interface ImaAdsManager {
+    init(w: number, h: number, viewMode: unknown): void;
+    start(): void;
+    pause(): void;
+    resume(): void;
+    skip(): void;
+    destroy(): void;
+    resize(w: number, h: number, viewMode: unknown): void;
+    getCuePoints(): number[];
+    addEventListener(type: string, cb: (e: ImaAdEvent) => void): void;
+}
+interface ImaNamespace {
+    AdDisplayContainer: new (el: HTMLElement, video: HTMLVideoElement) => {
+        initialize(): void;
+        destroy(): void;
+    };
+    AdsLoader: new (adc: unknown) => {
+        requestAds(req: unknown): void;
+        contentComplete(): void;
+        destroy(): void;
+        addEventListener(type: string, cb: (e: {
+            getAdsManager(video: HTMLVideoElement, settings: unknown): ImaAdsManager;
+            getError?(): ImaAdError;
+        }) => void): void;
+    };
+    AdsRequest: new () => {
+        adTagUrl: string;
+        linearAdSlotWidth: number;
+        linearAdSlotHeight: number;
+        nonLinearAdSlotWidth: number;
+        nonLinearAdSlotHeight: number;
+        setAdWillAutoPlay(v: boolean): void;
+        setAdWillPlayMuted(v: boolean): void;
+    };
+    AdsRenderingSettings: new () => {
+        uiElements: string[];
+        restoreCustomPlaybackStateOnAdBreakComplete: boolean;
+    };
+    AdsManagerLoadedEvent: {
+        Type: {
+            ADS_MANAGER_LOADED: string;
+        };
+    };
+    AdErrorEvent: {
+        Type: {
+            AD_ERROR: string;
+        };
+    };
+    AdEvent: {
+        Type: Record<string, string>;
+    };
+    ViewMode: {
+        NORMAL: unknown;
+        FULLSCREEN: unknown;
+    };
+    ImaSdkSettings: {
+        VpaidMode: {
+            DISABLED: unknown;
+            ENABLED: unknown;
+            INSECURE: unknown;
+        };
+    };
+    settings: {
+        setVpaidMode(mode: unknown): void;
+    };
+}
+declare global {
+    interface Window {
+        google?: {
+            ima?: ImaNamespace;
+        };
+    }
+}
+/** Options for {@link ImaAdsProvider}. */
+export interface ImaAdsProviderOptions {
+    /**
+     * How IMA runs VPAID (interactive JavaScript) creatives:
+     * - `"enabled"` (default) — VPAID in a secure cross-origin iframe.
+     * - `"insecure"` — VPAID in a friendly iframe. Some ad servers (e.g.
+     *   FreeWheel networks) traffic VPAID creatives that stall in the secure
+     *   sandbox, especially on plain-http origins; insecure mode lets them run.
+     * - `"disabled"` — VPAID creatives error out and are skipped.
+     */
+    vpaidMode?: "enabled" | "insecure" | "disabled";
+}
+export declare class ImaAdsProvider implements AdsProvider {
+    private readonly options;
+    constructor(options?: ImaAdsProviderOptions);
+    private video;
+    private container;
+    private callbacks;
+    private ima;
+    private adDisplayContainer;
+    private adsLoader;
+    private adsManager;
+    private lastAd;
+    private lastBreakType;
+    private tagUrl;
+    private autostart;
+    private started;
+    private destroyed;
+    private requestGeneration;
+    private verdictTimer;
+    private gotVerdict;
+    attach(video: HTMLVideoElement, adContainer: HTMLElement, callbacks: AdsProviderCallbacks): void;
+    requestAds(config: AdBreakConfig, autostart: boolean): void;
+    private settleVerdict;
+    private startSession;
+    private bindManager;
+    /** After any ad failure, verify reachability — a confirmed blocker is
+     * reported as the dedicated 902 so the UI can show its notice. */
+    private adBlockFlagged;
+    private maybeFlagAdBlock;
+    startPendingBreak(): boolean;
+    contentDidComplete(): void;
+    pause(): void;
+    resume(): void;
+    skip(): void;
+    click(): void;
+    resize(width: number, height: number, fullscreen: boolean): void;
+    destroy(): void;
+}
+export {};

package/dist/ads/provider.d.ts

@@ -0,0 +1,56 @@
+import type { AdBreakConfig, AdBreakType, AdInfo, OGAdError } from "./types.js";
+/**
+ * Events an `AdsProvider` reports back to the player — the web counterpart
+ * of the Android/iOS `AdsProviderCallbacks`. Implemented by `OGPlayer`. In
+ * addition to the ad lifecycle, the provider drives content pause/resume
+ * (client-side ads play while the content element is paused).
+ */
+export interface AdsProviderCallbacks {
+    onAdBreakStarted(breakType: AdBreakType, totalAds: number): void;
+    onAdStarted(ad: AdInfo): void;
+    onAdSkipped(ad: AdInfo): void;
+    onAdCompleted(ad: AdInfo): void;
+    onAdBreakCompleted(breakType: AdBreakType): void;
+    onAdPaused(ad: AdInfo): void;
+    onAdResumed(ad: AdInfo): void;
+    onAdProgress(ad: AdInfo, positionMs: number, durationMs: number): void;
+    onAdError(error: OGAdError): void;
+    /** VMAP cue-point times (seconds into content; negative = postroll). */
+    onAdCuePoints(cuePointsSeconds: number[]): void;
+    /** The whole ad schedule for this session finished (no breaks remain). */
+    onAllAdsCompleted?(): void;
+    /** A break is about to play — pause and hide the content. */
+    onContentPauseRequested(): void;
+    /** The break finished — resume content. */
+    onContentResumeRequested(): void;
+}
+/**
+ * SPI for a client-side ads integration (Google IMA HTML5, future slot
+ * providers) — the web mirror of the mobile `AdsProvider` SPI. Opt-in: apps
+ * that never touch ads load none of this.
+ */
+export interface AdsProvider {
+    /** True when the provider plays its ads IN the content video element
+     * (FreeWheel's HTML5 SDK design — it swaps the src and the player
+     * restores content afterwards). The engine then releases the media
+     * element around each break and reloads content at the saved position
+     * when the break completes. */
+    readonly usesContentVideoElement?: boolean;
+    /** Wire the provider to the content element and the ad UI container.
+     * Called once before the first `requestAds`. */
+    attach(video: HTMLVideoElement, adContainer: HTMLElement, callbacks: AdsProviderCallbacks): void;
+    /** Request ads for the item's config. `autostart` carries the content's
+     * autoplay intent: false = hold the break until `startPendingBreak()`. */
+    requestAds(config: AdBreakConfig, autostart: boolean): void;
+    /** Start a loaded-but-held break. True if one was started. */
+    startPendingBreak(): boolean;
+    /** Content reached its end (so VMAP postrolls fire). */
+    contentDidComplete(): void;
+    pause(): void;
+    resume(): void;
+    skip(): void;
+    click(): void;
+    /** The player/container was resized (fullscreen, layout). */
+    resize(width: number, height: number, fullscreen: boolean): void;
+    destroy(): void;
+}

package/dist/ads/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Ads SPI — same shape as Android's `com.ogplayer.api.ads`. Web ad providers
+ * (Google IMA HTML5, native slot providers) plug in behind this; the first
+ * provider ships in a later release, the types are stable now so host code
+ * written against them doesn't churn.
+ */
+/** Marker for per-item ad configuration (mirrors Android `AdBreakConfig`). */
+export interface AdBreakConfig {
+}
+/** A VAST/VMAP ad tag (consumed by an IMA-style provider). */
+export interface AdTagConfig extends AdBreakConfig {
+    adTagUri: string;
+}
+export type AdBreakType = "PREROLL" | "MIDROLL" | "POSTROLL";
+export interface AdInfo {
+    adId: string;
+    positionInPod: number;
+    podSize: number;
+    breakType: AdBreakType;
+    isSkippable: boolean;
+    skipOffsetMs: number;
+    durationMs: number;
+    clickThroughUrl?: string;
+    providerRendersUi: boolean;
+}
+export interface OGAdError {
+    code: number;
+    phase: "LOAD" | "PLAY";
+    message: string;
+}
+export interface AdListener {
+    onAdBreakStarted?(breakType: AdBreakType, totalAds: number): void;
+    onAdStarted?(ad: AdInfo): void;
+    onAdSkipped?(ad: AdInfo): void;
+    onAdCompleted?(ad: AdInfo): void;
+    onAdBreakCompleted?(breakType: AdBreakType): void;
+    onAdPaused?(ad: AdInfo): void;
+    onAdResumed?(ad: AdInfo): void;
+    onAdProgress?(ad: AdInfo, positionMs: number, durationMs: number): void;
+    onAdSkippableStateChanged?(ad: AdInfo, isSkippable: boolean, skipOffsetMs: number): void;
+    onAdError?(error: OGAdError): void;
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,14 @@
+import { type ErrorCategory, type OGPlayerError } from "./types.js";
+export declare function makeError(code: number, category: ErrorCategory, message: string, retryable: boolean, httpStatusCode?: number, cause?: unknown): OGPlayerError;
+/** Map the native `<video>` element MediaError. */
+export declare function fromMediaError(err: MediaError | null): OGPlayerError;
+/** Map an hls.js error event (data.type/details/response). */
+export declare function fromHlsError(data: {
+    type: string;
+    details: string;
+    fatal: boolean;
+    response?: {
+        code?: number;
+    };
+    error?: Error;
+}): OGPlayerError;

package/dist/core/fairplay.d.ts

@@ -0,0 +1,24 @@
+import { type OGPlayerError } from "./types.js";
+export interface FairPlayConfig {
+    /** FairPlay Streaming license (CKC) endpoint. */
+    licenseUrl: string;
+    /** The FPS application certificate issued by Apple (binary .cer/.der). */
+    certificateUrl: string;
+    headers?: Record<string, string>;
+    /** Fresh headers per license request (renewals included), merged over
+     * `headers` — the rotating-token hook (mobile parity). */
+    tokenProvider?: (request: {
+        licenseUrl: string;
+        renewal: boolean;
+    }) => Promise<Record<string, string>>;
+}
+/**
+ * FairPlay Streaming via standard EME on Safari's NATIVE HLS path — the web
+ * counterpart of the iOS SDK's `AVContentKeySession` flow: fetch the app
+ * certificate, then for every encrypted key request POST the SPC to the
+ * license server and feed the CKC back. Widevine/PlayReady run through
+ * hls.js's EME controller instead; this module only ever engages on Safari.
+ *
+ * Returns a detach function; errors are soft-reported through `onError`.
+ */
+export declare function attachFairPlay(video: HTMLVideoElement, cfg: FairPlayConfig, onError: (e: OGPlayerError) => void, onKeysLoaded?: () => void, onSessionRenewed?: () => void): () => void;

package/dist/core/license.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Offline license verification — the web counterpart of the Android/iOS
+ * `LicenseVerifier`, using the SAME ECDSA P-256 keypair: one license issued
+ * by the shared private key unlocks all three platforms. No network, ever.
+ *
+ * License format: `OGP1.<base64url payload JSON>.<base64url ECDSA sig>`.
+ * On the web the `apps` patterns bind to the page HOSTNAME (exact match, or
+ * prefix match when the pattern ends with `*`). Failure is soft — the caller
+ * shows the watermark, playback is unaffected.
+ */
+export type LicenseResult = {
+    licensed: true;
+    licensee: string;
+    edition: string;
+    exp: string;
+} | {
+    licensed: false;
+    reason: string;
+};
+export declare function verifyLicense(licenseKey: string | undefined, hostname: string, publicKeyB64?: string): Promise<LicenseResult>;
+/** DER SEQUENCE { INTEGER r, INTEGER s } → 64-byte raw r||s. */
+export declare function derSignatureToRaw(der: Uint8Array): Uint8Array | null;
+/** Exact match, or prefix match when the pattern ends with `*`. */
+export declare function licensePatternMatches(host: string, pattern: string): boolean;
+/** Valid through the end of `exp` (YYYY-MM-DD), device local date. */
+export declare function isExpired(exp: string): boolean;