senza-sdk 4.5.1 → 4.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "senza-sdk",
-    "version": "4.5.1",
+    "version": "4.5.3",
     "main": "./src/api.js",
     "description": "API for Senza application",
     "license": "MIT",

package/src/api.js

@@ -153,12 +153,13 @@ export const envInfo = {
  * @param {ArrayBuffer|string} licenseResponse a license response that was received from the license server to be passed to platform.
  * @param {string} fcid a fcid received with the license request
  * @param {string} sessionId a sessionId received with the license request
- * In case of success licenceResponse is of type @type {ArrayBuffer}
+ * @param {string} playbackId the current playbackId, propagated to platform for session correlation
+ * In case of success licenseResponse is of type @type {ArrayBuffer}
  * In case of error licenseResponse is of type @type {string}
  */
-export function writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId) {
+export function writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId, playbackId) {
     if (window?.senzaSDKImplementation) {
-        return window.senzaSDKImplementation.writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId);
+        return window.senzaSDKImplementation.writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId, playbackId);
     }
     sdkLogger.error("writeLicenseResponse: window.cefQuery is undefined");
 }

package/src/implementation/api.js

@@ -303,10 +303,11 @@ import "./devHelper.js";
  * @param {ArrayBuffer|string} licenseResponse a license response that was received from the license server to be passed to platform.
  * @param {string} fcid a fcid received with the license request
  * @param {string} sessionId a sessionId received with the license request
- * In case of success licenceResponse is of type @type {ArrayBuffer}
+ * @param {string} playbackId the current playbackId, propagated to platform for session correlation
+ * In case of success licenseResponse is of type @type {ArrayBuffer}
  * In case of error licenseResponse is of type @type {string}
  */
-export function writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId) {
+export function writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId, playbackId) {
 
     if (statusCode >= 200 && statusCode < 300) {
         licenseResponse = window.btoa(String.fromCharCode.apply(null, new Uint8Array(licenseResponse))); // to base64
@@ -316,7 +317,8 @@ export function writeLicenseResponse(statusCode, licenseResponse, fcid, sessionI
         const message = {
             type: "updateLicense",
             sessionId,
-            fcid
+            fcid,
+            playbackId
         };
         message[statusCode >= 200 && statusCode < 300 ? "response" : "error"] = licenseResponse;
         const request = { target: "TC", waitForResponse: false, message: JSON.stringify(message) };

package/src/implementation/overlay.js

@@ -1,6 +1,28 @@
 import { Overlay as OverlayInterface } from "../interface/overlay.js";
 import { getFCID, sdkLogger, SenzaError } from "./utils";
 
+/**
+ * Named overlay capture plans. Each step: `{ quality, conditional, delay }`.
+ * Steps run when refresh() is called; `delay` is ms after the previous step in the batch.
+ * `conditional`: when true, capture only if overlay content changed since the last
+ * required (non-conditional) capture in this batch; when false, always capture on that step.
+ * Set per step by the plan author; the SDK does not derive it.
+ */
+const OVERLAY_CAPTURE_PRESETS = {
+    default: [
+        { quality: "low", conditional: false, delay: 0 },
+        { quality: "low", conditional: true, delay: 150 },
+        { quality: "low", conditional: true, delay: 300 },
+        { quality: "high", conditional: false, delay: 600 }
+    ],
+    once: [
+        { quality: "high", conditional: true, delay: 0 }
+    ]
+};
+
+const DEFAULT_CAPTURE_PRESET = "default";
+const VALID_QUALITIES = new Set(["low", "mid", "high"]);
+
 class Overlay extends OverlayInterface {
     constructor() {
         super();
@@ -8,51 +30,102 @@ class Overlay extends OverlayInterface {
         this._element = null;
         this._configuration = {
             useTransparency: true,
-            autoRefreshSeconds: 2
+            overlayCapturePreset: DEFAULT_CAPTURE_PRESET,
+            overlayCapturePlan: null
         };
+        this._activeCapturePlan = OVERLAY_CAPTURE_PRESETS[DEFAULT_CAPTURE_PRESET];
         this._retryGeneration = 0;
-        this._retryTimerId = null;
+        this._planTimerId = null;
+        this._currentBatchId = null;
     }
 
     _isTransparencyEnabled() {
         return this._configuration.useTransparency !== false;
     }
 
+    _clearPlanTimer() {
+        if (this._planTimerId != null) {
+            clearTimeout(this._planTimerId);
+            this._planTimerId = null;
+        }
+    }
+
     _clearRetryTimers() {
         this._retryGeneration++;
-        clearTimeout(this._retryTimerId);
-        this._retryTimerId = null;
+        this._clearPlanTimer();
     }
 
-    _scheduleRetries(maxMs) {
-        const startTime = Date.now();
-        let delay = 100;
-        const generation = ++this._retryGeneration;
+    _validateCapturePlan(plan) {
+        if (!Array.isArray(plan) || plan.length === 0) {
+            return false;
+        }
+        for (let i = 0; i < plan.length; i++) {
+            const step = plan[i];
+            if (!step || typeof step !== "object") {
+                return false;
+            }
+            if (!VALID_QUALITIES.has(step.quality)) {
+                return false;
+            }
+            if (typeof step.conditional !== "boolean") {
+                return false;
+            }
+            if (typeof step.delay !== "number" || !Number.isFinite(step.delay) || step.delay < 0) {
+                return false;
+            }
+        }
+        return true;
+    }
 
-        const scheduleNext = () => {
-            if (this._retryGeneration !== generation) return;
-            const elapsed = Date.now() - startTime;
-            if (elapsed + delay > maxMs) return;
+    _resolveCapturePlan() {
+        if (this._configuration.overlayCapturePlan != null) {
+            return structuredClone(this._configuration.overlayCapturePlan);
+        }
+        const presetName = this._configuration.overlayCapturePreset ?? DEFAULT_CAPTURE_PRESET;
+        const preset = OVERLAY_CAPTURE_PRESETS[presetName];
+        if (!preset) {
+            throw new Error(`Overlay: unknown overlayCapturePreset "${presetName}"`);
+        }
+        return structuredClone(preset);
+    }
 
-            this._retryTimerId = setTimeout(async () => {
-                if (this._retryGeneration !== generation) return;
+    _scheduleCapturePlanFromStep(batchId, plan, generation, startIndex) {
+        const scheduleStep = (index) => {
+            if (this._retryGeneration !== generation) {
+                return;
+            }
+            const step = plan[index];
+            if (!step) {
+                sdkLogger.error(`Overlay: missing capture plan step at index ${index} (plan length ${plan.length})`);
+                return;
+            }
+            this._clearPlanTimer();
+            this._planTimerId = setTimeout(async () => {
+                if (this._retryGeneration !== generation) {
+                    return;
+                }
                 try {
-                    await this._renderFrame(true);
+                    await this._renderFrame(batchId, step, index);
                 } catch (err) {
-                    sdkLogger.log(`Overlay: conditional refresh error: ${err}`);
+                    sdkLogger.error("Overlay: capture plan step error:", err);
+                }
+                if (index + 1 < plan.length && this._retryGeneration === generation) {
+                    scheduleStep(index + 1);
                 }
-                delay *= 2;
-                scheduleNext();
-            }, delay);
+            }, step.delay);
         };
 
-        scheduleNext();
+        scheduleStep(startIndex);
     }
 
-    _sendFrame(x, y, width, height, conditional = false) {
+    /**
+     * @param {boolean} conditional - When true, capture only if overlay content changed since
+     * the last required capture in this batch; when false, always capture on this step.
+     */
+    _sendFrame(x, y, width, height, batchId, quality, conditional, stepIndex = 0) {
         if (window.cefQuery) {
             return new Promise((resolve, reject) => {
-                const FCID = getFCID();
+                const FCID = `${stepIndex}-${getFCID()}`;
                 const message = {
                     type: "displayOverlay",
                     x,
@@ -61,8 +134,11 @@ class Overlay extends OverlayInterface {
                     height,
                     useTransparency: this._isTransparencyEnabled(),
                     fcid: FCID,
+                    batchId,
+                    quality,
                     conditional
                 };
+                sdkLogger.log(`Overlay: rendering frame x=${x} y=${y} width=${width} height=${height} fcid=${FCID} (batchId=${batchId}, quality=${quality}, conditional=${conditional})`);
                 const request = { target: "UI-Streamer", waitForResponse: false, message: JSON.stringify(message) };
                 window.cefQuery({
                     request: JSON.stringify(request),
@@ -79,7 +155,7 @@ class Overlay extends OverlayInterface {
         return Promise.reject("Overlay is not supported if NOT running e2e");
     }
 
-    _renderFrame(conditional = false) {
+    _renderFrame(batchId, captureStep = { quality: "high", conditional: false }, stepIndex = 0) {
         if (!this._element) {
             return Promise.reject("No element configured");
         }
@@ -91,9 +167,10 @@ class Overlay extends OverlayInterface {
             return Promise.resolve(false);
         }
 
-        sdkLogger.log(`Overlay: rendering frame x=${frame.x} y=${frame.y} width=${frame.width} height=${frame.height} (conditional=${conditional})`);
-        return this._sendFrame(frame.x, frame.y, frame.width, frame.height, conditional).then(() => {
-            if (!conditional) {
+        const id = batchId ?? this._currentBatchId ?? getFCID();
+
+        return this._sendFrame(frame.x, frame.y, frame.width, frame.height, id, captureStep.quality, captureStep.conditional, stepIndex).then(() => {
+            if (!captureStep.conditional) {
                 const refreshEvent = new Event("refresh");
                 refreshEvent.frame = frame;
                 this.dispatchEvent(refreshEvent);
@@ -108,7 +185,7 @@ class Overlay extends OverlayInterface {
         const x = Math.round(toFiniteNumber(rect.x));
         const y = Math.round(toFiniteNumber(rect.y));
         const width = Math.round(toFiniteNumber(rect.width));
-        const height =Math.round(toFiniteNumber(rect.height));
+        const height = Math.round(toFiniteNumber(rect.height));
 
         return { x, y, width, height };
     }
@@ -116,16 +193,41 @@ class Overlay extends OverlayInterface {
     _applyConfiguration(configuration) {
         const normalizedConfiguration = { ...configuration };
 
+        if (
+            Object.prototype.hasOwnProperty.call(normalizedConfiguration, "overlayCapturePreset") ||
+            Object.prototype.hasOwnProperty.call(normalizedConfiguration, "overlayCapturePlan")
+        ) {
+            this._clearRetryTimers();
+        }
+
         if (Object.prototype.hasOwnProperty.call(normalizedConfiguration, "useTransparency")) {
             normalizedConfiguration.useTransparency = normalizedConfiguration.useTransparency !== false;
         }
 
-        if (Object.prototype.hasOwnProperty.call(normalizedConfiguration, "autoRefreshSeconds")) {
-            const v = normalizedConfiguration.autoRefreshSeconds;
-            normalizedConfiguration.autoRefreshSeconds = (typeof v === "number" && v >= 0) ? v : this._configuration.autoRefreshSeconds;
+        if (Object.prototype.hasOwnProperty.call(normalizedConfiguration, "overlayCapturePreset")) {
+            const preset = normalizedConfiguration.overlayCapturePreset;
+            if (typeof preset === "string" && OVERLAY_CAPTURE_PRESETS[preset]) {
+                normalizedConfiguration.overlayCapturePreset = preset;
+            } else if (preset != null) {
+                sdkLogger.warn(`Overlay: invalid overlayCapturePreset "${preset}", keeping previous preset`);
+                delete normalizedConfiguration.overlayCapturePreset;
+            }
+        }
+
+        if (Object.prototype.hasOwnProperty.call(normalizedConfiguration, "overlayCapturePlan")) {
+            const plan = normalizedConfiguration.overlayCapturePlan;
+            if (plan == null) {
+                normalizedConfiguration.overlayCapturePlan = null;
+            } else if (this._validateCapturePlan(plan)) {
+                normalizedConfiguration.overlayCapturePlan = structuredClone(plan);
+            } else {
+                sdkLogger.warn("Overlay: invalid overlayCapturePlan, keeping previous plan");
+                delete normalizedConfiguration.overlayCapturePlan;
+            }
         }
 
         this._configuration = { ...this._configuration, ...normalizedConfiguration };
+        this._activeCapturePlan = this._resolveCapturePlan();
     }
 
     async addElement(element) {
@@ -171,14 +273,19 @@ class Overlay extends OverlayInterface {
             return Promise.reject(errorMsg);
         }
         this._clearRetryTimers();
-        const result = await this._renderFrame();
-        if (result === true) {
-            const maxMs = (this._configuration.autoRefreshSeconds ?? 0) * 1000;
-            if (maxMs > 0) {
-                this._scheduleRetries(maxMs);
+        this._currentBatchId = getFCID();
+        const batchId = this._currentBatchId;
+        const generation = this._retryGeneration;
+        const plan = this._activeCapturePlan;
+        if (plan[0].delay === 0) {
+            const result = await this._renderFrame(batchId, plan[0], 0);
+            if (result === true && plan.length > 1) {
+                this._scheduleCapturePlanFromStep(batchId, plan, generation, 1);
             }
+            return result;
         }
-        return result;
+        this._scheduleCapturePlanFromStep(batchId, plan, generation, 0);
+        return true;
     }
 
     async removeAllElements() {

package/src/implementation/remotePlayer.js

@@ -2,6 +2,7 @@
 import { RemotePlayer as RemotePlayerInterface, RemotePlayerError as RemotePlayerErrorInterface, Config } from "../interface/remotePlayer";
 import {
     getFCID,
+    generatePlaybackId,
     isAudioSyncConfigured,
     clearTimer,
     sdkLogger,
@@ -145,6 +146,13 @@ class RemotePlayer extends RemotePlayerInterface {
          * @private
          */
         this._isPlaying = false;
+
+        /**
+         * @type {string}
+         * @description Unique identifier generated on every load attempt. Propagated on all API requests and events.
+         * @private
+         */
+        this._playbackId = "";
     }
 
     /** @private Initialize the remote player
@@ -219,17 +227,33 @@ class RemotePlayer extends RemotePlayerInterface {
 
     }
 
+    /**
+     * @private Returns true and logs an error when an incoming event's playbackId does not match the current one.
+     * @param {Object} detail - The event detail object that may contain a playbackId field.
+     * @param {string} eventType - Name of the incoming event, used in the log message.
+     */
+    _hasPlaybackIdMismatch(detail, eventType) {
+        const incomingId = detail?.playbackId;
+        if (incomingId && this._playbackId && incomingId !== this._playbackId) {
+            sdkLogger.error(`${eventType}: playbackId mismatch. current=${this._playbackId} incoming=${incomingId}. Ignoring.`);
+            return true;
+        }
+        return false;
+    }
+
     /**
      * @private Add event listeners for system events
      */
     _addSenzaEventListeners() {
 
         typeof document !== "undefined" && document.addEventListener("hs/remotePlayerEvent", (e) => {
+            if (this._hasPlaybackIdMismatch(e?.detail, "hs/remotePlayerEvent")) return;
             sdkLogger.info("Got hs/remotePlayerEvent event with detail", JSON.stringify(e?.detail));
             this.dispatchEvent(new Event(e?.detail?.eventName));
         });
 
-        typeof document !== "undefined" && document.addEventListener("hs/playbackInfoEvent", () => {
+        typeof document !== "undefined" && document.addEventListener("hs/playbackInfoEvent", (e) => {
+            if (this._hasPlaybackIdMismatch(e?.detail, "hs/playbackInfoEvent")) return;
             sdkLogger.info("Got hs/playbackInfoEvent");
             // When attached, the sdk controls the synchronization between the local and remote player.
             if (this._videoElement) {
@@ -243,13 +267,15 @@ class RemotePlayer extends RemotePlayerInterface {
         });
 
         typeof document !== "undefined" && document.addEventListener("hs/playback", (e) => {
+            if (this._hasPlaybackIdMismatch(e?.detail, "hs/playback")) return;
             sdkLogger.info("Got hs/playback event with detail", JSON.stringify(e?.detail));
             this._availabilityStartTime = e?.detail?.availabilityStartTime;
             this._updateTracks(e?.detail);
             this.dispatchEvent(new Event("tracksupdate"));
         });
 
-        typeof document !== "undefined" && document.addEventListener("hs/EOS", () => {
+        typeof document !== "undefined" && document.addEventListener("hs/EOS", (e) => {
+            if (this._hasPlaybackIdMismatch(e?.detail, "hs/EOS")) return;
             sdkLogger.info("Got hs/EOS event");
             this._changePlayMode(false);
             this.dispatchEvent(new Event("ended"));
@@ -268,6 +294,7 @@ class RemotePlayer extends RemotePlayerInterface {
             }
         });
         typeof document !== "undefined" && document.addEventListener("hs/senzaPlayerSetRate", (event) => {
+            if (this._hasPlaybackIdMismatch(event?.detail, "hs/senzaPlayerSetRate")) return;
             if (!this._videoElement) return;
             if (this._isSeekingByApplication) {
                 sdkLogger.info("Skip senzaPlayerSetRate while seek performed");
@@ -276,6 +303,7 @@ class RemotePlayer extends RemotePlayerInterface {
             this._videoElement.playbackRate = event.detail.rate;
         });
         typeof document !== "undefined" && document.addEventListener("hs/senzaPlayerSetTime", (event) => {
+            if (this._hasPlaybackIdMismatch(event?.detail, "hs/senzaPlayerSetTime")) return;
             // For simplicity, make sure we only accept syncing the current time if audio sync is enabled
             if (!this._isAudioSyncEnabled()) return;
             if (this._isSeekingByApplication) {
@@ -291,6 +319,7 @@ class RemotePlayer extends RemotePlayerInterface {
 
 
         typeof document !== "undefined" && document.addEventListener("hs/ERR", (event) => {
+            if (this._hasPlaybackIdMismatch(event?.detail, "hs/ERR")) return;
             sdkLogger.info("Got hs/ERR event");
             delete event?.detail?.type; // type is always videoPlaybackEvent, so no need to pass it
             delete event?.detail?.eventCode; // eventCode is always ERR, so no need to pass it
@@ -298,6 +327,7 @@ class RemotePlayer extends RemotePlayerInterface {
         });
 
         typeof document !== "undefined" && document.addEventListener("hs/getLicense", (event) => {
+            if (this._hasPlaybackIdMismatch(event?.detail, "hs/getLicense")) return;
             sdkLogger.info("Got hs/getLicense event");
             const getLicenseEventData = event?.detail;
 
@@ -308,9 +338,10 @@ class RemotePlayer extends RemotePlayerInterface {
             this.licenseRequest = licenseRequest;
             const fcid = getLicenseEventData.fcid;
             const sessionId = getLicenseEventData.sessionId;
+            const playbackId = this._playbackId;
             const licenseRequestEvent = new CustomEvent("license-request", { "detail": { licenseRequest } });
             licenseRequestEvent.writeLicenseResponse = (statusCode, responseBody) => {
-                writeLicenseResponse(statusCode, responseBody, fcid, sessionId);
+                writeLicenseResponse(statusCode, responseBody, fcid, sessionId, playbackId);
             };
             this.dispatchEvent(licenseRequestEvent);
         });
@@ -485,7 +516,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 class: "remotePlayer",
                 action: "seek",
                 playbackPosition,
-                fcid: FCID
+                fcid: FCID,
+                playbackId: this._playbackId
             };
             const request = { target: "TC", waitForResponse: waitForResponse, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {
@@ -544,7 +576,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 fcid: FCID,
                 audioLanguage,
                 subtitlesLanguage,
-                playbackPosition: this.currentTime
+                playbackPosition: this.currentTime,
+                playbackId: this._playbackId
             };
             let waitForResponse = false;
             if (this._remotePlayerApiVersion >= 2) {
@@ -611,7 +644,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 type: "remotePlayer.pause",
                 class: "remotePlayer",
                 action: "pause",
-                fcid: FCID
+                fcid: FCID,
+                playbackId: this._playbackId
             };
             if (this._remotePlayerApiVersion >= 2) {
                 message.streamType = this._isAudioSyncEnabled() && isForegroundState ? StreamType.AUDIO : StreamType.AUDIO | StreamType.VIDEO | StreamType.SUBTITLE;
@@ -662,7 +696,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 class: "remotePlayer",
                 action: "stop",
                 streamType: streamType,
-                fcid: FCID
+                fcid: FCID,
+                playbackId: this._playbackId
             };
             const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {
@@ -784,6 +819,7 @@ class RemotePlayer extends RemotePlayerInterface {
             this._abortSeeking = true;
             if (reset) {
                 this._reset();
+                this._playbackId = generatePlaybackId();
             }
             const previousLoadMode = this._loadMode;
             this._changeLoadMode(this.LoadMode.LOADING);
@@ -804,7 +840,8 @@ class RemotePlayer extends RemotePlayerInterface {
                     timeout: this._remotePlayerConfirmationTimeout,
                     autoPlay: false,
                     playbackPosition,
-                    fcid: FCID
+                    fcid: FCID,
+                    playbackId: this._playbackId
                 };
                 if (this._uiAvSyncIntervalMs !== undefined) {
                     message.connectorSettings = message.connectorSettings || {};
@@ -905,7 +942,8 @@ class RemotePlayer extends RemotePlayerInterface {
                     type: "remotePlayer.unload",
                     class: "remotePlayer",
                     action: "unload",
-                    fcid: FCID
+                    fcid: FCID,
+                    playbackId: this._playbackId
                 };
                 const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
                 let timerId = 0;
@@ -918,6 +956,7 @@ class RemotePlayer extends RemotePlayerInterface {
                         logger.withFields({ duration }).log(`unload completed successfully after ${duration} ms`);
                         timerId = clearTimer(timerId);
                         this._reset();
+                        this._playbackId = "";
                         this._changeLoadMode(this.LoadMode.NOT_LOADED);
                         this._loadedUrl = undefined;
                         resolve();
@@ -1240,7 +1279,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 class: "remotePlayer",
                 action: "setAudioLanguage",
                 fcid: FCID,
-                language: audioTrackId
+                language: audioTrackId,
+                playbackId: this._playbackId
             };
             const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {
@@ -1387,7 +1427,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 class: "remotePlayer",
                 action: "setSubtitleLanguage",
                 fcid: FCID,
-                language: textTrackId
+                language: textTrackId,
+                playbackId: this._playbackId
             };
             const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {
@@ -1889,7 +1930,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 class: "remotePlayer",
                 action: "screenBlackout",
                 fcid: FCID,
-                blackoutTime
+                blackoutTime,
+                playbackId: this._playbackId
             };
             const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {

package/src/implementation/utils.js

@@ -14,6 +14,19 @@ export function getFCID() {
     return Math.round(Math.random() * 100000) + "-" + getPlatformInfo().sessionInfo?.connectionId;
 }
 
+export function generatePlaybackId() {
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+    const size = 5;
+    let id = "";
+    const bytes = (typeof crypto !== "undefined" && crypto.getRandomValues)
+        ? crypto.getRandomValues(new Uint8Array(size))
+        : Array.from({ length: size }, () => Math.floor(Math.random() * 256));
+    for (let i = 0; i < size; i++) {
+        id += alphabet[bytes[i] & 63];
+    }
+    return id;
+}
+
 export class SenzaError extends Error {
     constructor(code, message) {
         super(message);

package/src/interface/overlay.js

@@ -46,13 +46,11 @@ class Overlay extends EventTarget {
      * This is useful when the element's content or position has changed.
      * The overlay must have an element registered before calling refresh.
      *
-     * After the initial capture, conditional retries are automatically scheduled using
-     * exponential backoff (starting at 100 ms, doubling each step) until the window
-     * configured by `configure({ autoRefreshSeconds })` expires (default: 2 seconds).
-     * Each retry is skipped by the UI-Streamer unless the browser has repainted since
-     * the last non-conditional capture, eliminating redundant JPEG encodes.
-     * Pending retries are cancelled by a subsequent call to refresh(), hideOverlay(),
-     * or removeElement().
+     * Runs the configured overlay capture plan after each call. The `default` preset sends
+     * low-quality captures with relative delays, ending with a high-quality capture.
+     * The `once` preset runs one high-quality conditional step immediately.
+     * All steps in one refresh share the same `batchId` (from `getFCID()`). Pending plan
+     * steps are cancelled by a subsequent call to refresh(), hideOverlay(), or removeElement().
      *
      * @returns {Promise<boolean>} Resolves to true if successful, rejects with error if failed.
      */
@@ -85,9 +83,13 @@ class Overlay extends EventTarget {
      * @param {Object} configuration - The new configuration to apply.
      * @param {boolean} [configuration.useTransparency=true] - Controls whether the overlay should be rendered with transparency.
      * When set to `true`, the value is forwarded to UI-Streamer in `displayOverlay` requests.
-     * @param {number} [configuration.autoRefreshSeconds=2] - Maximum window in seconds for automatic
-     * conditional retries after each refresh() call. Retries are spaced with exponential backoff
-     * starting at 100 ms. Set to 0 to disable automatic retries.
+     * @param {string} [configuration.overlayCapturePreset="default"] - Named capture plan preset:
+     * `default` (progressive low→high captures) or `once` (one immediate high-quality conditional step).
+     * @param {Array<{quality: "low"|"mid"|"high", conditional: boolean, delay: number}>} [configuration.overlayCapturePlan]
+     * Explicit capture plan; overrides preset. Steps run on refresh(); each step's `delay` is ms after
+     * the previous step in the batch. Set `conditional` per step (the SDK does not derive it):
+     * when `true`, capture only if overlay content changed since the last required (non-conditional)
+     * capture in this batch; when `false`, always capture on that step.
      */
     configure(configuration) {
         noop(configuration);

package/src/interface/version.js

@@ -1 +1 @@
-export const version = "4.5.1";
+export const version = "4.5.3";