senza-sdk 4.5.1 → 4.5.2

package/package.json

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

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/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.2";