eb-player 2.5.3 → 2.7.0

package/dist/build/types/src/core/browser-support.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Runtime feature floor of the player.
+ *
+ * The bundle's *syntax* floor is ES2017 (see scripts/check-syntax-floor.ts),
+ * which parses on Chrome 55+, Safari 10.1+ and Firefox 52+. Some of those
+ * engines still lack runtime APIs the player cannot work without:
+ *
+ *   - Proxy           — the reactive PlayerState store (Chrome 49, Safari 10)
+ *   - AbortController — every subscription/listener cleanup (Chrome 66,
+ *                       Safari 12.1, Firefox 57)
+ *
+ * On such a browser `start()` used to throw a bare ReferenceError from deep
+ * inside PlayerController's constructor, leaving the integrator's container
+ * as an empty white box. This module lets start() detect the gap up front
+ * and show a readable message instead, using only pre-ES2015 DOM APIs.
+ */
+export declare const REQUIRED_RUNTIME_FEATURES: readonly ["Proxy", "AbortController"];
+/**
+ * Returns the names of the required runtime features that are not
+ * constructors on `scope` (defaults to `window`).
+ */
+export declare function findMissingRuntimeFeatures(scope?: Record<string, unknown>): string[];
+/**
+ * Replaces the container's content with the skin's error overlay markup
+ * (same class names as ErrorMessage, so the shipped CSS styles it) carrying
+ * the translated "browser not supported" text. Plain DOM calls only: this
+ * runs precisely on the browsers where lit-html/PlayerState cannot.
+ */
+export declare function renderUnsupportedBrowser(container: HTMLElement, lang?: string): void;

package/dist/build/types/src/core/config.d.ts

@@ -7,6 +7,18 @@
  * 3. Fixes the JSON.parse/stringify bug in generator/mergeConfig.js by
  *    passing function values by reference instead of serializing them
  */
+import type { PlayerErrorInfo } from './errors';
+/** Player-rendered subtitles. Setting `subtitleStyle` (even `{}`) switches subtitle rendering from the browser to the player. Numbers are pixels. */
+export interface SubtitleStyle {
+    fontFamily?: string;
+    fontSize?: string | number;
+    color?: string;
+    backgroundColor?: string;
+    /** Distance of the text from the bottom of the video while the controls are hidden. */
+    bottom?: string | number;
+    /** Same, while the controls are visible (lifts the text above the seekbar). */
+    bottomWithControls?: string | number;
+}
 export interface SkinColors {
     general: string;
     progressBar: string;
@@ -138,6 +150,26 @@ export interface PlayerConfig {
     token: string | undefined;
     tokenType: string | undefined;
     srcInTokenRequest: boolean;
+    /**
+     * Called for every user-visible player error, with a stable `code` (see
+     * `PlayerErrorCode`), the English diagnostic `message` and the
+     * `localizedMessage` the overlay shows. Fires for errors raised during
+     * start() too, which `player.on('error')` cannot see (no reference yet).
+     */
+    onError?: ((error: PlayerErrorInfo) => void) | null;
+    /**
+     * Override or add UI text: `{ fr: { 'error.geoblocked': '...' } }`. Error
+     * overlay keys are `error.<code lower-cased>`, e.g. `error.drm_error`.
+     * Locales are en / fr / ar / es; text in `{name}` form is interpolated only
+     * where the player passes variables.
+     */
+    messages?: Record<string, Record<string, string>> | null;
+    /**
+     * Render subtitles in the player instead of the browser, to control font,
+     * size and position. `null` (default) keeps native rendering.
+     */
+    subtitleStyle?: SubtitleStyle | null;
+    sentryDsn: string | undefined;
     defaultAudio: string | string[] | undefined;
     defaultSubtitle: string | string[] | undefined;
     forceAutoplay: boolean;

package/dist/build/types/src/core/errors.d.ts

@@ -0,0 +1,39 @@
+import type { PlayerState } from './types';
+import type { TypedEventBus } from './event-bus';
+import type { I18n } from './i18n';
+/**
+ * Stable, documented error codes. Integrators key their own translations and
+ * telemetry on these; the English `message` next to them is diagnostic prose
+ * and may change between releases. The i18n key for a code is
+ * `error.<code lower-cased>` (see `errorMessageKey`).
+ */
+export declare const PlayerErrorCode: {
+    readonly STREAM_UNAVAILABLE: "STREAM_UNAVAILABLE";
+    readonly GEOBLOCKED: "GEOBLOCKED";
+    readonly HLS_INIT_FAILED: "HLS_INIT_FAILED";
+    readonly DASH_INIT_FAILED: "DASH_INIT_FAILED";
+    readonly DRM_ERROR: "DRM_ERROR";
+    readonly LOAD_NEVER_STARTED: "LOAD_NEVER_STARTED";
+    readonly NO_VIDEO_ELEMENT: "NO_VIDEO_ELEMENT";
+};
+export type PlayerErrorCodeValue = (typeof PlayerErrorCode)[keyof typeof PlayerErrorCode];
+/** Payload of the public `error` event / `config.onError` callback. */
+export interface PlayerErrorInfo {
+    /** Stable code — one of `PlayerErrorCode`. */
+    code: string;
+    /** Diagnostic message (English, unlocalized). */
+    message: string;
+    /** The text the error overlay shows, in the configured `lang`. */
+    localizedMessage: string;
+}
+/** i18n key holding the user-facing text for an error code. */
+export declare function errorMessageKey(code: string): string;
+/**
+ * The one place a fatal, user-visible error is surfaced: sets the code before
+ * the message (the overlay re-renders on `error`), and announces it on the bus.
+ * Distinct from `error-fatal`, which has side effects (P2P teardown, intro
+ * fall-through) and is only emitted for a subset of failures.
+ */
+export declare function reportError(state: PlayerState, bus: TypedEventBus | null | undefined, code: PlayerErrorCodeValue, message: string): void;
+/** Overlay text for an error: the code's translation when one exists, else the raw message. */
+export declare function localizeError(code: string | null, rawMessage: string, i18n: I18n | null): string;

package/dist/build/types/src/core/event-bus.d.ts

@@ -16,6 +16,10 @@ export interface EventMap {
         code: string;
         message: string;
     };
+    'player-error': {
+        code: string;
+        message: string;
+    };
     'cast-start': {
         src: string;
     };

package/dist/build/types/src/core/i18n.d.ts

@@ -25,6 +25,14 @@ export declare class I18n {
      * Useful for skin components adding their own translation keys in Phase 3.
      */
     addTranslations(entries: TranslationMap): void;
+    /**
+     * Register integrator overrides shaped `{ locale: { key: text } }` (the
+     * `config.messages` shape). Locale codes are reduced to their language part
+     * ('fr-CA' -> 'fr'); keys are the same ones t() looks up (e.g. 'error.geoblocked').
+     */
+    addMessages(messages: Record<string, Record<string, string>>): void;
+    /** Whether any locale defines this key (a missing key would echo back as itself from t()). */
+    has(key: string): boolean;
     /**
      * Look up a translation key in the current locale.
      * Falls back to English if not found in current locale.

package/dist/build/types/src/core/types.d.ts

@@ -45,6 +45,8 @@ export interface StateMap {
     currentSubtitleTrack: number;
     playbackRate: number;
     error: string | null;
+    /** Stable code of the current error (see `PlayerErrorCode`); null when `error` is null or was set without a code. */
+    errorCode: string | null;
     src: string;
     isFullscreen: boolean;
     isPip: boolean;

package/dist/build/types/src/eb-player.d.ts

@@ -17,6 +17,7 @@
 import { AVAILABLE_THEMES, THEME_LAYOUTS } from './core/index';
 import type { PlayerState } from './core/types';
 import type { PlayerConfig } from './core/config';
+import type { PlayerErrorInfo } from './core/errors';
 /**
  * The PlayerReference returned by start().
  * Gives consumers direct control over the active stream.
@@ -30,6 +31,12 @@ export interface PlayerReference {
     destroy(): void;
     /** Current player state (read-only reference to the reactive state store). */
     readonly state: PlayerState;
+    /**
+     * Subscribe to user-visible player errors, each with a stable `code`
+     * (see `PlayerErrorCode`). Returns an unsubscribe function. Errors raised
+     * while start() is still running are only reachable via `config.onError`.
+     */
+    on(event: 'error', listener: (error: PlayerErrorInfo) => void): () => void;
 }
 /**
  * Start the player with the given config.

package/dist/build/types/src/engines/base-engine.d.ts

@@ -26,6 +26,14 @@ export declare abstract class BaseEngine extends EngineStateSync {
      */
     protected loadSourceUrl: string;
     private watchdog;
+    /**
+     * Every native video listener bound by bindVideoEvents(), so detach() can
+     * remove them itself. They are also registered with `{ signal }`, but
+     * Chromium < 90, Safari < 15 and Firefox < 86 silently ignore that option:
+     * on those engines the listeners outlived destroy() and kept writing a
+     * disposed PlayerState on every timeupdate (Sentry FORJA-FRONTWEB-5B9/5BA).
+     */
+    private videoListeners;
     /**
      * Promise that resolves when the engine driver (hls.js/dash.js) is created
      * and ready for integration (e.g., P2P SDK). Resolved inside onAttach().
@@ -49,6 +57,11 @@ export declare abstract class BaseEngine extends EngineStateSync {
      */
     setLoadSource(src: string): void;
     protected bindVideoEvents(video: HTMLVideoElement, state: PlayerState, signal: AbortSignal): void;
+    /**
+     * Removes every listener bound by bindVideoEvents() — the explicit half of
+     * the cleanup that `{ signal }` was supposed to do on its own.
+     */
+    private unbindVideoEvents;
     protected abstract recoverFromStall(attempt: number): void;
     protected abstract onAttach(): Promise<void> | void;
     protected abstract onDetach(): void;

package/dist/build/types/src/engines/cdn-token-manager.d.ts

@@ -136,6 +136,17 @@ export declare class CDNTokenManager {
     sourceUrl: string | null;
     private resetAttemptCounterTimeout;
     private inFlightFetch;
+    /**
+     * Consecutive CDN-side rejections (see notifyCdnRejection) handled without
+     * an intervening resetCdnRejectionCount(). Capped at maxRetries so a token
+     * that keeps getting rejected for a non-expiration reason (geo-blocking,
+     * revoked entitlement, IP mismatch...) doesn't make us mint a fresh token
+     * forever — after the cap, notifyCdnRejection stops forcing refreshes and
+     * the normal engine error handling (fatal/non-fatal escalation) takes over.
+     */
+    private cdnRejectionCount;
+    /** Set by notifyCdnRejection; consumed once by the next updateUrlWithTokenParams call. */
+    private forceRefreshOnce;
     constructor({ token, tokenType, srcInTokenRequest, extraParamsCallback, onCDNTokenError, maxRetries, retryInterval, expirationMarginInSeconds }: CDNTokenManagerOptions);
     private resetAttemptCounter;
     private _fetchDefaultToken;
@@ -149,6 +160,26 @@ export declare class CDNTokenManager {
         url: string;
     }): Promise<string>;
     isTokenExpired(expirationTime: number | string | null | undefined): boolean;
+    /**
+     * Signals that the CDN itself (not the token generator) rejected a request
+     * signed with the current token — e.g. a 403 on a playlist fetch.
+     * isTokenExpired()'s margin only compares against the token's own
+     * `expires`, so a token the CDN already refused can still look "fresh" and
+     * get replayed unchanged on the next retry/reload. This forces the next
+     * updateUrlWithTokenParams() call to mint a new token regardless of that
+     * margin.
+     *
+     * Capped at maxRetries consecutive calls (cleared by
+     * resetCdnRejectionCount on a subsequent successful load): a freshly-minted
+     * token that also gets rejected is not an expiration problem — e.g.
+     * geo-blocking or a revoked entitlement — and retrying forever would only
+     * hammer the token generator and the CDN for no benefit. Past the cap this
+     * returns false and does nothing, leaving the engine's own error handling
+     * (fatal/non-fatal escalation) to take over.
+     */
+    notifyCdnRejection(): boolean;
+    /** Call after a request signed with the current token succeeds at the CDN. */
+    resetCdnRejectionCount(): void;
     destroy(): void;
     static appendTokenParams(urlString: string, token: string | null, expires: number | string | null, tokenPath: string | null): string;
     static appendAkamaiTokenParams(urlString: string, hdnea: string): string;

package/dist/build/types/src/skin/base-component.d.ts

@@ -63,6 +63,16 @@ export declare abstract class BaseComponent {
     /**
      * Renders the component into this.el using lit-html.
      * No-op if el is null (e.g., after disconnect()).
+     *
+     * A render that throws is contained: lit-html keeps its parts alive through
+     * comment markers inside the component's subtree, and a DOM rewriter
+     * outside the player (page translation, an extension) that rebuilds that
+     * markup without the markers breaks the part for good — every later render
+     * throws the same `this._$AA.nextSibling is null` and, with a component
+     * re-rendering on each state tick, that is thousands of identical errors
+     * per session (Sentry FORJA-FRONTWEB-5EZ..5F1). The failure is logged once,
+     * the view is unsubscribed from state/bus updates, and render() becomes a
+     * no-op. disconnect() stays safe to call afterwards.
      */
     protected render(): void;
 }

package/dist/build/types/src/skin/controls/volume-control.d.ts

@@ -4,17 +4,27 @@ import { BaseComponent } from '../base-component';
  * Volume control with mute toggle button and draggable slider.
  *
  * - Mute button emits 'mute-toggle'
- * - Slider uses Pointer Events API (pointerdown/pointermove/pointerup)
+ * - Slider uses Pointer Events API (pointerdown/pointermove/pointerup/pointercancel)
  * - Slider fill width reflects current volume (0% to 100%)
  * - When muted, fill shows 0% visually
+ *
+ * The document-level drag listeners are stable instance methods, never
+ * per-drag closures: a second pointerdown landing during a drag (a second
+ * finger on a phone) used to overwrite the stored closure, so the first
+ * drag's listeners could never be removed again and kept calling
+ * eventToVolume() against a track rect that pointerup had already nulled
+ * (Sentry FORJA-FRONTWEB-5E3/5E4). With one function reference per event
+ * type, addEventListener is idempotent and removeEventListener always pairs.
  */
 export declare class VolumeControl extends BaseComponent {
     private trackRect;
-    private onPointerMove;
-    private onPointerUp;
+    private readonly onDocumentPointerMove;
+    private readonly onDocumentPointerUp;
+    private readonly onDocumentPointerCancel;
     protected onConnect(): void;
     private eventToVolume;
     private handlePointerDown;
+    private endDrag;
     private getVolumeIcon;
     protected template(): TemplateResult;
 }

package/dist/build/types/src/skin/index.d.ts

@@ -15,6 +15,7 @@ export { SettingsPanel } from './controls/settings-panel';
 export { Seekbar } from './controls/seekbar';
 export { LoadingSpinner } from './overlays/loading-spinner';
 export { ErrorMessage } from './overlays/error-message';
+export { SubtitleOverlay } from './overlays/subtitle-overlay';
 export { SocialsOverlay } from './overlays/socials-overlay';
 export { InfoOverlay } from './overlays/info-overlay';
 export { AutoHideController } from './controllers/auto-hide';

package/dist/build/types/src/skin/overlays/error-message.d.ts

@@ -4,7 +4,8 @@ import { BaseComponent } from '../base-component';
  * Error message overlay.
  *
  * Visible when state.error is not null.
- * Shows the error string (raw text — i18n lookup can be applied at a higher level).
+ * Shows the translation registered for state.errorCode (`error.<code>`, overridable
+ * through config.messages), falling back to the raw state.error string.
  * Has a retry button that emits 'request-reload'.
  */
 export declare class ErrorMessage extends BaseComponent {

package/dist/build/types/src/skin/overlays/subtitle-overlay.d.ts

@@ -0,0 +1,30 @@
+import type { TemplateResult } from 'lit-html';
+import { BaseComponent } from '../base-component';
+/**
+ * Renders subtitle cues in the player's own DOM so integrators control font,
+ * size and position (native `::cue` can style text but cannot move it).
+ *
+ * Only mounted when `config.subtitleStyle` is set; otherwise the browser
+ * renders cues natively, exactly as before. Works from the video's TextTracks,
+ * so it does not depend on which engine created them: a track an engine
+ * switches to `showing` is switched to `hidden` (still firing `cuechange`) and
+ * drawn here instead; a track set back to `disabled` stops being drawn.
+ *
+ * Not mounted-in behaviour: iOS uses the native player, which draws its own.
+ * WebVTT cue settings (`line`, `position`, `align`) are ignored — position is
+ * `subtitleStyle.bottom` / `bottomWithControls`.
+ */
+export declare class SubtitleOverlay extends BaseComponent {
+    private video;
+    private readonly taken;
+    private listRoot;
+    private readonly onTracksChange;
+    private readonly onCueChange;
+    protected onConnect(): void;
+    disconnect(): void;
+    protected template(): TemplateResult;
+    private applyStyle;
+    private syncTracks;
+    private paint;
+    private renderCue;
+}

package/dist/build/types/src/utils/play-quietly.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Call `video.play()` and swallow its rejection.
+ *
+ * play() returns a promise that rejects with `AbortError` whenever pause() —
+ * or a new load — interrupts the pending play request. That is the normal
+ * outcome of a fast pause after play, an ad break, a cast hand-over or a
+ * source switch, never something the caller can act on, and left unhandled
+ * it reaches the page as an unhandled promise rejection (Sentry issues 18
+ * and W, ~420 users/day on forja.ma). Browsers predating the promise return
+ * (and jsdom) return undefined, so the catch is only attached when there is
+ * something to attach it to.
+ */
+/** Anything with a media-element-shaped play(): HTMLVideoElement, or the poster loop's minimal media handle. */
+export interface Playable {
+    play(): unknown;
+}
+export declare function playQuietly(video: Playable): void;

package/dist/build/types/src/utils/telemetry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Kicks off loading the Sentry Browser SDK from a CDN (see SENTRY_LOADER_URL)
+ * and initializing it with the given DSN. Fire-and-forget: does not return a
+ * promise the caller could await, and instrumentedFetch() below never waits
+ * on it either — network calls (notably the CDN token generator retry path)
+ * must never gain latency from telemetry loading.
+ *
+ * A page can host multiple player instances (see src/eb-player.ts's
+ * `instances` map); Sentry's client is inherently page-global, so this is a
+ * module-level singleton guarded against double-init. A second call with a
+ * different DSN is a no-op past a warning — reconciling two Sentry projects
+ * on one page is a host-app concern, not something this player can resolve.
+ */
+export declare function initTelemetry(dsn: string | undefined): void;
+/**
+ * Drop-in replacement for `fetch(url, init)` that additionally records a
+ * response-time span and captures errors to Sentry, when telemetry is
+ * enabled and ready. Never changes the resolved value or the rejection a
+ * caller would have seen from a plain fetch() — callers keep every existing
+ * status check / retry / body-parsing line untouched.
+ *
+ * `name` is a fixed, non-secret label identifying the call site (e.g.
+ * 'cdn-token:bunny') — the request URL itself is never sent to Sentry.
+ *
+ * If Sentry hasn't finished loading yet (or telemetry is disabled), this is
+ * exactly a plain fetch() with no added delay.
+ */
+export declare function instrumentedFetch(name: string, url: string, init?: RequestInit): Promise<Response>;