ogplayer 1.2.1 → 1.3.1

package/README.md

@@ -64,17 +64,28 @@ el.config = {
 };
 ```
 
+## Keyboard shortcuts
+
+While the player has focus (it takes focus on any click) the keys viewers
+expect just work: `Space`/`K` play-pause, `←`/`→` and `J`/`L` seek by the seek
+increment, `↑`/`↓` volume, `M` mute, `F` fullscreen, `C` subtitles, `0`–`9` jump
+to 0–90 % on VOD, `Home`/`End` start/end (live edge on live), `Esc` leaves
+fullscreen. Seek keys obey the live rules and stay inert during ads; modifier
+chords and unmapped keys reach the page untouched. Turn it off with
+`el.config = { keyboardShortcuts: false }` or change single keys with
+`el.config = { keymap: { m: null, p: "toggleMute" } }`.
+
 ## 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.
+   `scripts/release.sh <version>` run (build, tests, tarball guard, `npm publish`).
 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.
+   Served straight from the npm package via unpkg (or any CDN mirror of npm).
 
 ```html
-<script src="https://cdn.ogplayer.tv/0.1.0/ogplayer.global.js"></script>
+<script src="https://unpkg.com/ogplayer@1.3.1/dist/ogplayer.global.js"></script>
 <script>
   const player = new OGPlayerSDK.OGPlayer();
   document.querySelector("og-player").player = player;

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

@@ -2,8 +2,7 @@ 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,
+ * flow: request → slot schedule → preroll/midroll/catch-up/postroll,
  * a watchdog that abandons a slot that never renders, exactly-once content
  * resume per gate).
  *

package/dist/ads/freewheel.d.ts

@@ -1,6 +1,6 @@
 import type { AdBreakConfig } from "./types.js";
 /**
- * FreeWheel ad configuration — the web counterpart of the Android/iOS
+ * FreeWheel ad configuration
  * `FreewheelConfig`, field-for-field. Pure data: no FreeWheel SDK
  * dependency.
  *
@@ -9,7 +9,7 @@ import type { AdBreakConfig } from "./types.js";
  *      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.
+ *      AdManager.js) — ships later as an adapter.
  *
  * Consent and identity parameters (`_fw_gdpr`, `_fw_gdpr_consent`, device
  * ids…) are the HOST's responsibility via `globalParameters` — the SDK
@@ -47,6 +47,6 @@ export declare function isFreewheelConfig(c: AdBreakConfig): c is FreewheelConfi
 /**
  * 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.
+ * shape of the `asVmapTag` reference implementation.
  */
 export declare function freewheelVmapTagUrl(cfg: FreewheelConfig): string;

package/dist/ads/ima.d.ts

@@ -2,7 +2,6 @@ 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.
  *

package/dist/ads/provider.d.ts

@@ -1,7 +1,7 @@
 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
+ * 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).
  */
@@ -12,6 +12,14 @@ export interface AdsProviderCallbacks {
     onAdCompleted(ad: AdInfo): void;
     onAdBreakCompleted(breakType: AdBreakType): void;
     onAdPaused(ad: AdInfo): void;
+    /** The viewer tapped/clicked the ad itself — not its skip, clickthrough or
+     *  AdChoices control. Providers that own the layer over the video (IMA)
+     *  report it and the SDK toggles the ad's playback; a provider that draws
+     *  nothing there never needs to (the stage click handles that). Optional. */
+    onAdTapped?(ad: AdInfo): void;
+    /** The viewer opened the ad's clickthrough: a new tab/window covers the page.
+     *  The SDK pauses the ad and resumes it when the page is visible again. Optional. */
+    onAdClicked?(ad: AdInfo): void;
     onAdResumed(ad: AdInfo): void;
     onAdProgress(ad: AdInfo, positionMs: number, durationMs: number): void;
     onAdError(error: OGAdError): void;

package/dist/ads/types.d.ts

@@ -1,10 +1,10 @@
 /**
- * Ads SPI — same shape as Android's `com.ogplayer.api.ads`. Web ad providers
+ * Ads SPI. 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`). */
+/** Marker for per-item ad configuration (. */
 export interface AdBreakConfig {
 }
 /** A VAST/VMAP ad tag (consumed by an IMA-style provider). */
@@ -36,6 +36,8 @@ export interface AdListener {
     onAdBreakCompleted?(breakType: AdBreakType): void;
     onAdPaused?(ad: AdInfo): void;
     onAdResumed?(ad: AdInfo): void;
+    /** The viewer opened the ad's clickthrough; the SDK pauses the ad and resumes it when the page is visible again. */
+    onAdClicked?(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/fairplay.d.ts

@@ -14,7 +14,7 @@ export interface FairPlayConfig {
 }
 /**
  * FairPlay Streaming via standard EME on Safari's NATIVE HLS path — the web
- * counterpart of the iOS SDK's `AVContentKeySession` flow: fetch the app
+ * 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.

package/dist/core/license.d.ts

@@ -1,5 +1,5 @@
 /**
- * Offline license verification — the web counterpart of the Android/iOS
+ * Offline license verification
  * `LicenseVerifier`, using the SAME ECDSA P-256 keypair: one license issued
  * by the shared private key unlocks all three platforms. No network, ever.
  *

package/dist/core/player.d.ts

@@ -5,7 +5,7 @@ import type { AdsProvider } from "../ads/provider.js";
 export interface OGPlayerOptions {
     /** Offline license key (`OGP1.…`); without one the watermark shows. */
     licenseKey?: string;
-    /** onProgress cadence, default 250ms (Android DEFAULT_PROGRESS_INTERVAL_MS). */
+    /** onProgress cadence, default 250ms. */
     progressUpdateIntervalMs?: number;
     /** Seek button increments, default 10s each way. */
     seekForwardIncrementMs?: number;
@@ -32,8 +32,7 @@ export interface LoadOptions {
     autoplay?: boolean;
 }
 /**
- * The OGPlayer playback engine — the web counterpart of the Android
- * `OGPlayer` (the reference platform), wrapping an HTML `<video>` element:
+ * The OGPlayer playback engine
  * HLS via hls.js (MSE) everywhere, natively on Safari, progressive files
  * directly. UI is `<og-player>` from the `ui` module; the engine also works
  * fully headless.
@@ -90,6 +89,10 @@ export declare class OGPlayer {
     private isPlayingAdFlag;
     private adsPendingFlag;
     private adPausedFlag;
+    /** A clickthrough paused the ad and its tab covers the page — see onAdClicked. */
+    private adClickthroughPending;
+    private readonly onVisibilityForClickthrough;
+    private clearClickthrough;
     private adProgressValue;
     private adCuePointsValue;
     private lastAdInfo;
@@ -117,14 +120,13 @@ export declare class OGPlayer {
     get isMuted(): boolean;
     set isMuted(v: boolean);
     /** Loop the current item seamlessly (native `<video loop>`); survives
-     *  across load() calls, mirroring Android/iOS `setLooping`. */
+     *  across load() calls,. */
     get isLooping(): boolean;
     setLooping(v: boolean): void;
     /**
      * Buffer discipline for pooled players (the vertical feed): STANDBY caps
      * appetite (10s forward / 8MB, no back-buffer, metadata-only preload for
-     * progressive sources); ACTIVE restores full defaults. Mirrors Android's
-     * `setBufferRole` / iOS `setPreferredForwardBufferDuration`.
+     * progressive sources); ACTIVE restores full defaults.
      */
     setBufferRole(role: "STANDBY" | "ACTIVE"): void;
     /** Web routes all volume to the element; kept for API parity. */
@@ -163,12 +165,12 @@ export declare class OGPlayer {
     removeAdListener(l: AdListener): void;
     private dispatch;
     /** Single exit for analytics: every event leaves stamped with the session
-     *  id and asset URL of the load it belongs to (Android parity). */
+     *  id and asset URL of the load it belongs to. */
     private emit;
     /** @internal Feeds a view-layer analytics event into this player's stream,
      * session-stamped like every other event. Called by the SDK's own elements
      * (`<og-player>`) — not host-app API (the web `emitViewAnalytics` of
-     * Android's internal hook; kept off the docs surface via `@internal`). */
+     * an internal hook; kept off the docs surface via `@internal`). */
     emitViewAnalytics(e: Extract<AnalyticsEvent, {
         type: "FullscreenChanged" | "OrientationChanged";
     }>): void;
@@ -251,7 +253,7 @@ export declare class OGPlayer {
     pause(): void;
     skipAd(): void;
     clickAd(): void;
-    /** Ad-break cue positions in ms, Android encoding (postroll = duration). */
+    /** Ad-break cue positions in ms (postroll = duration). */
     get adCuePositionsMs(): number[];
     /** True when the current item carries a storyboard (trick-play) track. */
     get hasThumbnails(): boolean;

package/dist/core/session-tracker.d.ts

@@ -4,7 +4,7 @@ import type { BufferReason } from "./types.js";
  * (`BufferReason`) and time-to-first-frame. Reset by every load; driven by
  * the media-element events the player receives ('seeking', 'seeked',
  * 'canplay'/'playing'). Pure logic — unit-tested in node without a DOM.
- * The web port of Android's `PlaybackSessionTracker` (the reference).
+ * The web.
  */
 export declare class PlaybackSessionTracker {
     private readySeen;

package/dist/core/token-fetch.d.ts

@@ -1,6 +1,6 @@
 import type { DrmTokenProvider, DrmTokenRequest } from "./types.js";
 /**
- * Fenced DRM token fetch — the web counterpart of the Android SDK's
+ * Fenced DRM token fetch
  * `OGMediaDrmCallback.fetchToken()`: a hung token service must never hold
  * playback forever. Bounded attempts with a per-attempt timeout and a
  * progressive backoff; the last failure propagates so callers map it to
@@ -9,7 +9,7 @@ import type { DrmTokenProvider, DrmTokenRequest } from "./types.js";
 export declare const TOKEN_ATTEMPTS = 3;
 export declare const TOKEN_TIMEOUT_MS = 8000;
 /** Whole-call deadline for license/certificate HTTP requests — the web
- *  mirror of Android's `boundedHttpClient` callTimeout and iOS's
+ *
  *  `timeoutIntervalForResource` (15 s on every platform). */
 export declare const LICENSE_CALL_TIMEOUT_MS = 15000;
 export declare function fetchTokenHeaders(provider: DrmTokenProvider, request: DrmTokenRequest, timeoutMs?: number): Promise<Record<string, string>>;

package/dist/core/types.d.ts

@@ -1,7 +1,5 @@
 /**
- * OGPlayer web SDK — public model types. The web counterpart of Android's
- * `com.ogplayer.api` (the reference platform): same names, same semantics,
- * so code and docs translate 1:1 across Android / iOS / web.
+ * OGPlayer web SDK — public model types.
  */
 export type StreamType = "VOD" | "LIVE" | "LIVE_DVR";
 export type PlaybackState = "IDLE" | "BUFFERING" | "READY" | "ENDED";
@@ -56,15 +54,14 @@ export interface DrmTokenRequest {
 }
 /**
  * Fresh headers for every license request — the web counterpart of the
- * Android/iOS token providers. Called per request (renewals included) so
+ * token providers. Called per request (renewals included) so
  * expiring tokens can rotate; the result is merged OVER the scheme's static
  * `headers`. Failures surface as DRM_TOKEN_FETCH_FAILED (4002).
  */
 export type DrmTokenProvider = (request: DrmTokenRequest) => Promise<Record<string, string>>;
 /**
- * Multi-DRM configuration — the web counterpart of Android's `DrmConfig` /
- * iOS's `FairPlayConfig`, unified: configure every scheme you have and the
- * SDK picks whichever the visitor's browser supports (Chrome/Firefox/Android
+ * Multi-DRM configuration: configure every scheme you have and the
+ * SDK picks whichever the visitor's browser supports (Chrome/Firefox
  * → Widevine, Edge → PlayReady or Widevine, Safari → FairPlay).
  */
 export interface DrmConfig {
@@ -119,7 +116,7 @@ export interface LiveInfo {
     latencyMs: number;
     playheadWallClockMs: number | null;
 }
-/** Android's PlaybackListener, method-for-method. All members optional. */
+/** Playback lifecycle callbacks. All members optional. */
 export interface PlaybackListener {
     onStateChanged?(state: PlaybackState): void;
     onPlay?(): void;
@@ -169,7 +166,7 @@ export interface AnalyticsEventBase {
     assetUrl?: string;
 }
 /** Why a `PlaybackRecovered` happened. Web values are the hls.js self-healing
- *  classes; the Android values (`DRM_RENEWAL_AFTERSHOCK`, `CODEC_RESTART`,
+ *  classes; the native values (`DRM_RENEWAL_AFTERSHOCK`, `CODEC_RESTART`,
  *  `LIVE_WINDOW_RESET`) are listed so shared mappers can switch over one type. */
 export type RecoveryReason = "NETWORK_RETRY" | "BUFFER_STALL" | "DRM_RETRY" | "MEDIA_RETRY" | "DRM_RENEWAL_AFTERSHOCK" | "CODEC_RESTART" | "LIVE_WINDOW_RESET";
 export type AnalyticsEvent = AnalyticsEventBase & ({
@@ -252,8 +249,7 @@ export type AnalyticsEvent = AnalyticsEventBase & ({
  *  `onError` did not fire, but the viewer may have seen a short rebuffer.
  *  Count these for QoE; they are recoveries, not failures. On web this is
  *  hls.js's own retry/stall handling (`detail` carries the hls.js error
- *  detail for diagnosis); Android reports its silent re-prepares here
- *  under its own reasons. */
+ *  detail for diagnosis). */
  | {
     type: "PlaybackRecovered";
     reason: RecoveryReason;
@@ -282,7 +278,7 @@ export type AnalyticsEvent = AnalyticsEventBase & ({
     error: OGPlayerError;
 });
 export type OGAnalyticsListener = (event: AnalyticsEvent) => void;
-/** Error taxonomy — same numeric codes as Android/iOS. */
+/** Error taxonomy — the same numeric codes on every platform. */
 export declare const ErrorCodes: {
     readonly NETWORK_CONNECTION_FAILED: 2000;
     readonly NETWORK_TIMEOUT: 2001;

package/dist/core/vertical-feed.d.ts

@@ -2,8 +2,7 @@ import { OGPlayer } from "./player.js";
 import type { AnalyticsEvent, OGMediaItem, OGPlayerError } from "./types.js";
 /**
  * Vertical feed data model + player pool — the web counterpart of the
- * Android `VerticalFeedPlayerPool` (the reference implementation) and its
- * iOS mirror. The pool owns at most `preloadAhead + keepBehind + 1` (≤3)
+ * native pools. The pool owns at most `preloadAhead + keepBehind + 1` (≤3)
  * engine instances: neighbours of the visible page sit PREPARED — muted,
  * paused at 0, on capped standby buffers — so swipes start instantly;
  * pages outside the window are recycled; everything is released on dispose.
@@ -47,7 +46,7 @@ export interface OGVerticalFeedItem {
     /** Marks an ad item: "Sponsored" chip, never loops, auto-advances. */
     isSponsored?: boolean;
 }
-/** All knobs, mirroring the Android `OGVerticalFeedConfig` names. */
+/** All knobs,. */
 export interface OGVerticalFeedConfig {
     preloadAhead: number;
     keepBehind: number;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * OGPlayer web SDK — one video player API across Android, iOS and the web.
+ * OGPlayer web SDK.
  * A product of Inverse DOO.
  */
 export { OGPlayer, type OGPlayerOptions, type LoadOptions } from "./core/player.js";
@@ -14,6 +14,7 @@ export { OGPlayerElement, defineOGPlayerElement, hidingAllControls, type OGUICon
 export { VerticalFeedPlayerPool, defaultVerticalFeedConfig, type OGVerticalFeedItem, type OGVerticalFeedConfig, type RailAction, type SplitAudioSource, type TextPlacement, type VerticalFeedContentFit, } from "./core/vertical-feed.js";
 export { OGVerticalFeedElement, defineOGVerticalFeedElement } from "./ui/og-vertical-feed.js";
 export type { OGControlColors, OGControlDimens } from "./ui/tokens.js";
+export { DEFAULT_KEYMAP, type OGKeyAction, type OGKeymap } from "./ui/keymap.js";
 export { defaultColors, embeddedDimens, fullscreenDimens } from "./ui/tokens.js";
 /** Build timestamp of this bundle (diagnosing stale caches). */
 export declare const OGPLAYER_BUILD: string;