smartcomply-web-sdk 1.0.68 → 1.0.70

package/dist/smartcomply.browser.js

@@ -4709,6 +4709,7 @@ var SmartComplySDK = (() => {
       this.videoEl.autoplay = true;
       this.videoEl.playsInline = true;
       this.videoEl.muted = true;
+      this.videoEl.setAttribute("aria-label", "Live camera preview for face verification");
       this.videoEl.style.cssText = `
       width:100%;height:100%;display:block;
       filter:brightness(1.03) contrast(1.03);
@@ -4730,6 +4731,7 @@ var SmartComplySDK = (() => {
       this.guideWrapEl = guideWrap;
       const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
       svg.setAttribute("viewBox", "0 0 140 180");
+      svg.setAttribute("aria-hidden", "true");
       svg.style.cssText = "width:100%;height:100%;overflow:visible;";
       const defs = document.createElementNS("http://www.w3.org/2000/svg", "defs");
       const clip = document.createElementNS("http://www.w3.org/2000/svg", "clipPath");
@@ -4769,12 +4771,12 @@ var SmartComplySDK = (() => {
       confOval.setAttribute("ry", "86");
       confOval.setAttribute("fill", "none");
       confOval.setAttribute("stroke", this.colors.primary);
-      confOval.setAttribute("stroke-width", "2.5");
-      confOval.setAttribute("stroke-linecap", "round");
+      confOval.setAttribute("stroke-width", "3");
+      confOval.setAttribute("stroke-linecap", "butt");
       const circ = 2 * Math.PI * Math.sqrt((64 * 64 + 86 * 86) / 2);
       confOval.setAttribute("stroke-dasharray", `${circ}`);
       confOval.setAttribute("stroke-dashoffset", `${circ}`);
-      confOval.style.cssText = "transition:stroke-dashoffset 0.2s linear,stroke 0.3s ease;transform:rotate(-90deg);transform-origin:70px 90px;";
+      confOval.style.cssText = "transition:stroke-dashoffset 0.2s linear,stroke 0.3s ease;transform:rotate(-90deg);transform-origin:70px 90px;filter:drop-shadow(0 0 3px rgba(0,0,0,0.25));";
       this.confidenceRingEl = confOval;
       const bracketGroup = document.createElementNS("http://www.w3.org/2000/svg", "g");
       bracketGroup.setAttribute("stroke", this.colors.primary);
@@ -4822,6 +4824,8 @@ var SmartComplySDK = (() => {
       padding:14px 16px 32px;
     `;
       this.instructionEl = document.createElement("div");
+      this.instructionEl.setAttribute("aria-live", "polite");
+      this.instructionEl.setAttribute("role", "status");
       this.instructionEl.style.cssText = `
       color:#fff;font-size:14px;font-weight:600;text-align:center;line-height:1.4;
     `;
@@ -5857,6 +5861,126 @@ var SmartComplySDK = (() => {
     return Math.min(maxWidth / srcWidth, maxHeight / srcHeight, 1);
   }
 
+  // src/utils/ImageQuality.ts
+  function calculateSharpness(imageData) {
+    const { width, height, data } = imageData;
+    const gray = new Uint8Array(width * height);
+    for (let i2 = 0; i2 < width * height; i2++) {
+      const idx = i2 * 4;
+      gray[i2] = Math.round(0.299 * data[idx] + 0.587 * data[idx + 1] + 0.114 * data[idx + 2]);
+    }
+    const laplacian = new Float32Array(width * height);
+    let sum = 0;
+    let sumSq = 0;
+    let count = 0;
+    for (let y2 = 1; y2 < height - 1; y2++) {
+      for (let x2 = 1; x2 < width - 1; x2++) {
+        const idx = y2 * width + x2;
+        const val = -1 * gray[idx - width] + -1 * gray[idx - 1] + 4 * gray[idx] + -1 * gray[idx + 1] + -1 * gray[idx + width];
+        laplacian[idx] = val;
+        sum += val;
+        sumSq += val * val;
+        count++;
+      }
+    }
+    const mean = sum / count;
+    const variance = sumSq / count - mean * mean;
+    return Math.abs(variance);
+  }
+  function detectGlare(imageData, threshold = 250) {
+    const { data } = imageData;
+    let overexposed = 0;
+    for (let i2 = 0; i2 < data.length; i2 += 4) {
+      const brightness = (data[i2] + data[i2 + 1] + data[i2 + 2]) / 3;
+      if (brightness > threshold) {
+        overexposed++;
+      }
+    }
+    return overexposed / (data.length / 4);
+  }
+  function calculateContrast(imageData) {
+    const { data } = imageData;
+    let sum = 0;
+    let sumSq = 0;
+    const pixelCount = data.length / 4;
+    for (let i2 = 0; i2 < data.length; i2 += 4) {
+      const gray = 0.299 * data[i2] + 0.587 * data[i2 + 1] + 0.114 * data[i2 + 2];
+      sum += gray;
+      sumSq += gray * gray;
+    }
+    const mean = sum / pixelCount;
+    const variance = sumSq / pixelCount - mean * mean;
+    return Math.sqrt(variance);
+  }
+  function calculateBrightness(imageData) {
+    const { data } = imageData;
+    let sum = 0;
+    for (let i2 = 0; i2 < data.length; i2 += 4) {
+      sum += (data[i2] + data[i2 + 1] + data[i2 + 2]) / 3;
+    }
+    return sum / (data.length / 4);
+  }
+  function assessQuality(imageData) {
+    const sharpness = calculateSharpness(imageData);
+    const glare = detectGlare(imageData);
+    const contrast = calculateContrast(imageData);
+    const brightness = calculateBrightness(imageData);
+    const isBlurry = sharpness < 80;
+    const hasGlare = glare > 0.15;
+    const isTooDark = brightness < 50;
+    const isTooBright = brightness > 200;
+    const lowContrast = contrast < 30;
+    let score = 100;
+    if (isBlurry) score -= 40;
+    if (hasGlare) score -= 25;
+    if (isTooDark) score -= 20;
+    if (isTooBright) score -= 20;
+    if (lowContrast) score -= 15;
+    const metrics = {
+      sharpness: Math.round(sharpness * 10) / 10,
+      contrast: Math.round(contrast * 10) / 10,
+      brightness: Math.round(brightness * 10) / 10,
+      isBlurry,
+      hasGlare,
+      overallScore: Math.max(0, score)
+    };
+    const issues = [];
+    const recommendations = [];
+    if (isBlurry) {
+      issues.push("Too blurry");
+      recommendations.push("Hold camera steady");
+      recommendations.push("Ensure good lighting");
+    }
+    if (hasGlare) {
+      issues.push("Too much glare");
+      recommendations.push("Avoid direct light on document");
+      recommendations.push("Tilt document slightly");
+    }
+    if (isTooDark) {
+      issues.push("Too dark");
+      recommendations.push("Move to brighter area");
+      recommendations.push("Turn on more lights");
+    }
+    if (isTooBright) {
+      issues.push("Too bright");
+      recommendations.push("Reduce lighting");
+      recommendations.push("Move away from direct sun");
+    }
+    if (lowContrast) {
+      issues.push("Low contrast");
+      recommendations.push("Ensure even lighting");
+    }
+    const isValid = score >= 60;
+    const message = issues.length > 0 ? issues.join(", ") : "Good quality";
+    return {
+      isValid,
+      message,
+      recommendations: recommendations.slice(0, 3),
+      // Max 3 recommendations
+      quality: metrics
+    };
+  }
+
   // src/flow/icons.ts
   var PATHS = {
     shield: '<path d="M12 2l8 3v6c0 5-3.5 8.5-8 11-4.5-2.5-8-6-8-11V5l8-3z"/>',
@@ -5875,7 +5999,8 @@ var SmartComplySDK = (() => {
     passport: '<rect x="5" y="2" width="14" height="20" rx="2"/><circle cx="12" cy="9" r="2.5"/><path d="M9 15h6"/>',
     car: '<path d="M4 16V11l2-5h12l2 5v5"/><path d="M4 16h16M7 16v2M17 16v2"/><circle cx="7.5" cy="14" r="1"/><circle cx="16.5" cy="14" r="1"/>',
     ballot: '<rect x="4" y="8" width="16" height="12" rx="1"/><path d="M9 8V5a3 3 0 016 0v3"/><path d="M12 12v4"/>',
-    refresh: '<path d="M4 4v6h6"/><path d="M20 20v-6h-6"/><path d="M20 10a8 8 0 00-14.6-4.6M4 14a8 8 0 0014.6 4.6"/>'
+    refresh: '<path d="M4 4v6h6"/><path d="M20 20v-6h-6"/><path d="M20 10a8 8 0 00-14.6-4.6M4 14a8 8 0 0014.6 4.6"/>',
+    rotate: '<rect x="7" y="7" width="12" height="12" rx="2"/><path d="M7 4h5a4 4 0 014 4"/><path d="M13 1.5L16 4l-3 2.5"/>'
   };
   function icon(name, size = 24) {
     const d2 = PATHS[name];
@@ -6126,7 +6251,7 @@ var SmartComplySDK = (() => {
         display:flex;align-items:center;gap:8px;
         font-size:12px;color:${theme.textSecondary};line-height:1.5;
       `;
-        notice.innerHTML = backOptional ? `<span style="font-size:16px;flex-shrink:0;">ℹ️</span><span>After the <strong style="color:${theme.text}">front</strong>, you can optionally add the <strong style="color:${theme.text}">back</strong> if your card has one.</span>` : `<span style="font-size:16px;flex-shrink:0;">ℹ️</span><span>You'll capture both the <strong style="color:${theme.text}">front</strong> and <strong style="color:${theme.text}">back</strong> of this document.</span>`;
+        notice.innerHTML = backOptional ? `<span style="font-size:16px;flex-shrink:0;">ℹ️</span><span>After the <strong style="color:${theme.text}">front</strong>, you can optionally add the <strong style="color:${theme.text}">back</strong> if your document has one.</span>` : `<span style="font-size:16px;flex-shrink:0;">ℹ️</span><span>You'll capture both the <strong style="color:${theme.text}">front</strong> and <strong style="color:${theme.text}">back</strong> of this document.</span>`;
         this.root.appendChild(notice);
       }
       if (requiresBack && !isCapturingFront && backOptional) {
@@ -6137,7 +6262,7 @@ var SmartComplySDK = (() => {
         border:1.5px dashed ${theme.border};border-radius:10px;cursor:pointer;
         font-size:12.5px;font-weight:600;font-family:inherit;
       `;
-        skipBtn.textContent = "Skip — this card has no back side";
+        skipBtn.textContent = "Skip — my document has no back side";
         skipBtn.addEventListener("click", () => {
           this.handleCaptureComplete(null, container, theme, documentType, false, true);
         });
@@ -6384,14 +6509,15 @@ var SmartComplySDK = (() => {
       stepBadge.textContent = "STEP 1 OF 2 · CHECK THE PHOTO";
       this.root.appendChild(stepBadge);
       const img = document.createElement("img");
-      const imageUrl = URL.createObjectURL(imageData);
-      img.src = imageUrl;
+      let currentUrl = URL.createObjectURL(imageData);
+      img.src = currentUrl;
       img.style.cssText = `
       width:100%;max-height:300px;object-fit:contain;border-radius:${RADIUS.md}px;
       border:2px solid ${theme.border};
     `;
       this.root.appendChild(img);
-      img._blobUrl = imageUrl;
+      let currentBlob = imageData;
+      let isRotating = false;
       const label = document.createElement("div");
       label.style.cssText = `color:${theme.text};font-size:${TYPE.base}px;font-weight:700;text-align:center;`;
       label.textContent = "Does the photo look clear?";
@@ -6400,31 +6526,157 @@ var SmartComplySDK = (() => {
       sublabel.style.cssText = `color:${theme.textMuted};font-size:${TYPE.xs}px;text-align:center;line-height:1.6;`;
       sublabel.textContent = "All text must be readable and all four corners must be visible.";
       this.root.appendChild(sublabel);
+      const rotateBtn = document.createElement("button");
+      rotateBtn.type = "button";
+      rotateBtn.setAttribute("aria-label", "Rotate photo 90 degrees");
+      rotateBtn.style.cssText = `
+      display:flex;align-items:center;justify-content:center;gap:6px;
+      margin:0 auto;padding:8px 16px;background:transparent;
+      color:${theme.textSecondary};border:1.5px solid ${theme.border};
+      border-radius:${RADIUS.pill}px;cursor:pointer;
+      font-size:12.5px;font-weight:600;font-family:inherit;
+    `;
+      rotateBtn.innerHTML = `<span style="display:inline-flex;">${icon("rotate", 15)}</span><span>Rotate</span>`;
+      rotateBtn.addEventListener("click", async () => {
+        if (isRotating) return;
+        isRotating = true;
+        rotateBtn.disabled = true;
+        try {
+          const rotated = await this._rotateImage(currentBlob, 90);
+          currentBlob = rotated;
+          URL.revokeObjectURL(currentUrl);
+          currentUrl = URL.createObjectURL(rotated);
+          img.src = currentUrl;
+          this._checkPhotoQuality(currentBlob, qualityNotice, theme);
+        } catch {
+        } finally {
+          isRotating = false;
+          rotateBtn.disabled = false;
+        }
+      });
+      this.root.appendChild(rotateBtn);
+      const qualityNotice = document.createElement("div");
+      qualityNotice.style.cssText = `
+      display:none;width:100%;padding:10px 14px;border-radius:${RADIUS.md}px;
+      background:${theme.warning}15;border:1px solid ${theme.warning}35;
+      color:${theme.text};font-size:12px;text-align:left;line-height:1.5;
+    `;
+      qualityNotice.setAttribute("role", "status");
+      this.root.appendChild(qualityNotice);
+      this._checkPhotoQuality(currentBlob, qualityNotice, theme);
       const btnRow = document.createElement("div");
       btnRow.style.cssText = "display:flex;gap:12px;width:100%;";
       const retakeBtn = this.createButton("Retake", theme, false);
       retakeBtn.style.flex = "1";
       retakeBtn.addEventListener("click", () => {
-        if (img._blobUrl) {
-          URL.revokeObjectURL(img._blobUrl);
-        }
+        URL.revokeObjectURL(currentUrl);
         this.root.innerHTML = "";
         this.renderChoiceScreen(container, theme, documentType);
       });
       const useBtn = this.createButton("Use Photo ✓", theme, true);
       useBtn.style.flex = "1";
       useBtn.addEventListener("click", () => {
-        if (img._blobUrl) {
-          URL.revokeObjectURL(img._blobUrl);
-        }
+        URL.revokeObjectURL(currentUrl);
         useBtn.textContent = "Confirming photo…";
         useBtn.disabled = true;
-        this.ensureUnderUploadLimit(imageData).then((c2) => this.handleCaptureComplete(c2, container, theme, documentType, viaCamera));
+        rotateBtn.disabled = true;
+        this.ensureUnderUploadLimit(currentBlob).then((c2) => this.handleCaptureComplete(c2, container, theme, documentType, viaCamera));
       });
       btnRow.appendChild(retakeBtn);
       btnRow.appendChild(useBtn);
       this.root.appendChild(btnRow);
     }
+    /**
+     * Runs the shared client-side quality heuristic (blur/glare/contrast/
+     * brightness — see utils/ImageQuality.ts) against the just-captured photo
+     * and, if it scores poorly, shows a plain-language nudge on the preview
+     * screen. Fails silently on decode error — this is an advisory extra, not
+     * a required step, so a browser that can't run it must not block capture.
+     */
+    async _checkPhotoQuality(imageData, noticeEl, theme) {
+      try {
+        const canvas = await this._blobToCanvas(imageData, 640);
+        const ctx = canvas.getContext("2d");
+        if (!ctx) return;
+        const pixels = ctx.getImageData(0, 0, canvas.width, canvas.height);
+        const result = assessQuality(pixels);
+        if (noticeEl.isConnected && !result.isValid) {
+          noticeEl.style.display = "block";
+          noticeEl.textContent = "This photo might be hard to read — " + (result.recommendations[0] || "try retaking it in good lighting") + ".";
+        }
+      } catch {
+      }
+    }
+    /** Decodes to a canvas, optionally downscaled to maxDim on the long edge (never upscales). */
+    _blobToCanvas(source, maxDim) {
+      return new Promise((resolve, reject) => {
+        const url = URL.createObjectURL(source);
+        const imgEl = document.createElement("img");
+        imgEl.onload = () => {
+          URL.revokeObjectURL(url);
+          const { naturalWidth: w2, naturalHeight: h2 } = imgEl;
+          const ratio = maxDim ? computeScaleRatio(w2, h2, maxDim, maxDim) : 1;
+          const canvas = document.createElement("canvas");
+          canvas.width = Math.round(w2 * ratio);
+          canvas.height = Math.round(h2 * ratio);
+          const ctx = canvas.getContext("2d");
+          if (!ctx) {
+            reject(new Error("Canvas unavailable"));
+            return;
+          }
+          ctx.drawImage(imgEl, 0, 0, canvas.width, canvas.height);
+          resolve(canvas);
+        };
+        imgEl.onerror = () => {
+          URL.revokeObjectURL(url);
+          reject(new Error("Image load failed"));
+        };
+        imgEl.src = url;
+      });
+    }
+    /**
+     * Rotate an image blob by a multiple of 90° and re-encode it — used by the
+     * preview screen's rotate control for a document photographed or uploaded
+     * sideways/upside-down. EXIF auto-rotation (see compressImage) only fixes
+     * phone photos that embed correct orientation metadata; it can't help a
+     * document whose actual pixel content is sideways (e.g. the phone itself
+     * was held rotated relative to the document, or a pre-cropped/scanned
+     * upload with no EXIF at all) — that needs the user to say so directly.
+     */
+    _rotateImage(source, degrees) {
+      return new Promise((resolve, reject) => {
+        const url = URL.createObjectURL(source);
+        const imgEl = document.createElement("img");
+        imgEl.onload = () => {
+          URL.revokeObjectURL(url);
+          const { naturalWidth: w2, naturalHeight: h2 } = imgEl;
+          const swapped = degrees === 90 || degrees === 270;
+          const canvas = document.createElement("canvas");
+          canvas.width = swapped ? h2 : w2;
+          canvas.height = swapped ? w2 : h2;
+          const ctx = canvas.getContext("2d");
+          if (!ctx) {
+            reject(new Error("Canvas unavailable"));
+            return;
+          }
+          ctx.translate(canvas.width / 2, canvas.height / 2);
+          ctx.rotate(degrees * Math.PI / 180);
+          ctx.drawImage(imgEl, -w2 / 2, -h2 / 2);
+          canvas.toBlob(
+            (blob) => {
+              blob ? resolve(blob) : reject(new Error("Rotation failed"));
+            },
+            "image/jpeg",
+            0.95
+          );
+        };
+        imgEl.onerror = () => {
+          URL.revokeObjectURL(url);
+          reject(new Error("Image load failed"));
+        };
+        imgEl.src = url;
+      });
+    }
     handleCaptureComplete(imageData, container, theme, documentType, viaCamera, skipped = false) {
       const requiresBack = this.shouldCaptureBackSide(documentType);
       const wasCapturingFront = this.currentSide === "front";
@@ -6501,6 +6753,8 @@ var SmartComplySDK = (() => {
       if (!this.root) return;
       this.root.innerHTML = "";
       this.root.style.cssText = "display:flex;flex-direction:column;align-items:center;justify-content:center;gap:20px;padding:40px 20px;min-height:300px;";
+      this.root.setAttribute("aria-live", "polite");
+      this.root.setAttribute("role", "status");
       this.root.appendChild(renderSpinner(theme, { size: 80, icon: icon("document", 28) }));
       const loadingText = document.createElement("div");
       loadingText.style.cssText = `color:${theme.text};font-size:${TYPE.heading}px;font-weight:600;text-align:center;`;
@@ -6510,15 +6764,19 @@ var SmartComplySDK = (() => {
     showError(message) {
       if (!this.root) return;
       const errorContainer = document.createElement("div");
+      errorContainer.setAttribute("role", "alert");
       errorContainer.style.cssText = `
       display:flex;align-items:center;gap:12px;padding:16px;
       background:#ff444415;border:1px solid #ff444430;border-radius:${RADIUS.md}px;
       color:#ff4444;font-size:14px;margin-top:16px;animation:shake 0.5s ease-in-out;
     `;
-      errorContainer.innerHTML = `
-      <span style="font-size:18px;">⚠️</span>
-      <span>${message}</span>
-    `;
+      const errIcon = document.createElement("span");
+      errIcon.style.fontSize = "18px";
+      errIcon.textContent = "⚠️";
+      const errText = document.createElement("span");
+      errText.textContent = message;
+      errorContainer.appendChild(errIcon);
+      errorContainer.appendChild(errText);
       if (!document.head.querySelector("style[data-shake-animation]")) {
         const style = document.createElement("style");
         style.setAttribute("data-shake-animation", "true");
@@ -6693,13 +6951,32 @@ var SmartComplySDK = (() => {
       if (t2.includes("passport")) return "passport";
       if (t2.includes("driver") || t2.includes("licen")) return "driver's license";
       if (t2.includes("voter") || t2.includes("pvc")) return "voter's card";
-      if (t2.includes("national") || t2.includes("nin") || t2.includes("national id")) return "national ID card";
-      if (t2.includes("bvn")) return "BVN card";
+      if (t2.includes("nin")) return "NIN document";
+      if (t2.includes("national")) return "national ID card";
+      if (t2.includes("bvn")) return "BVN document";
       return "identity document";
     }
   };
 
   // src/flow/SmartComplyFlow.ts
+  var _INFRASTRUCTURE_ERROR_PATTERNS = [
+    "camera connection was lost",
+    "network error",
+    "failed after all retries",
+    "camera access is not supported",
+    "camera access failed",
+    "recording failed unexpectedly"
+  ];
+  function _isInfrastructureError(err) {
+    const msg = String(err?.message || "").toLowerCase();
+    return _INFRASTRUCTURE_ERROR_PATTERNS.some((p2) => msg.includes(p2));
+  }
+  function _userFacingLivenessError(err) {
+    if (_isInfrastructureError(err)) {
+      return "We lost connection during your scan — this wasn't anything you did. Please check your camera and internet connection, then try again.";
+    }
+    return err?.message || "We couldn't verify your face. Please try again.";
+  }
   var COUNTRY_LABELS = {
     nigeria: "🇳🇬  Nigeria",
     global: "🌍  Other Countries",
@@ -6722,7 +6999,7 @@ var SmartComplySDK = (() => {
     if (u2.includes("NIN") || u2.includes("NATIONAL IDENTITY NUMBER")) {
       return {
         icon: "🆔",
-        desc: isDocumentFlow ? "Capture or upload your NIN card (back optional)" : "Enter your 11-digit National Identification Number (NIN)",
+        desc: isDocumentFlow ? "Capture or upload your NIN (slip or card) — add the back if your document has one" : "Enter your 11-digit National Identification Number (NIN)",
         requiresBack: isDocumentFlow ? "optional" : false
       };
     }
@@ -6907,9 +7184,14 @@ var SmartComplySDK = (() => {
       this.isDestroyed = false;
       this.headerBackBtn = null;
       this._keydownHandler = null;
+      this._visibilityHandler = null;
+      this._hiddenAtMs = null;
+      this._popstateHandler = null;
+      this._historyGuardActive = false;
       // Retry safety — max 3 confirmation rejections or liveness failures per session
       this._confirmRetries = 0;
       this._livenessFailures = 0;
+      this._livenessAttemptId = 0;
       // IVS result stored for confirm_identity screen
       this._ivsName = "";
       this._ivsGender = "";
@@ -6968,6 +7250,21 @@ var SmartComplySDK = (() => {
         document.removeEventListener("keydown", this._keydownHandler);
         this._keydownHandler = null;
       }
+      if (this._visibilityHandler) {
+        document.removeEventListener("visibilitychange", this._visibilityHandler);
+        this._visibilityHandler = null;
+      }
+      if (this._popstateHandler) {
+        window.removeEventListener("popstate", this._popstateHandler);
+        this._popstateHandler = null;
+      }
+      if (this._historyGuardActive) {
+        this._historyGuardActive = false;
+        try {
+          if (history.state?.scFlowGuard) history.back();
+        } catch {
+        }
+      }
       this.docCapture?.destroy();
       if (this._prewarmedStream) {
         this._prewarmedStream.getTracks().forEach((t2) => t2.stop());
@@ -7084,6 +7381,43 @@ var SmartComplySDK = (() => {
         }
       };
       document.addEventListener("keydown", this._keydownHandler);
+      const REBACKGROUND_RESTART_MS = 3e3;
+      this._visibilityHandler = () => {
+        if (this.isDestroyed) return;
+        if (document.hidden) {
+          this._hiddenAtMs = Date.now();
+          return;
+        }
+        const hiddenAt = this._hiddenAtMs;
+        this._hiddenAtMs = null;
+        if (hiddenAt === null) return;
+        const awayMs = Date.now() - hiddenAt;
+        if (awayMs >= REBACKGROUND_RESTART_MS && this.currentStep === "liveness") {
+          this.showStep("liveness");
+        }
+      };
+      document.addEventListener("visibilitychange", this._visibilityHandler);
+      this._historyGuardActive = true;
+      try {
+        history.pushState({ scFlowGuard: true }, "");
+      } catch {
+        this._historyGuardActive = false;
+      }
+      this._popstateHandler = () => {
+        if (this.isDestroyed || !this._historyGuardActive) return;
+        const backAction = this._getBackAction(this.currentStep);
+        if (backAction) {
+          backAction();
+        } else {
+          this.close();
+          return;
+        }
+        try {
+          history.pushState({ scFlowGuard: true }, "");
+        } catch {
+        }
+      };
+      window.addEventListener("popstate", this._popstateHandler);
     }
     async initialize() {
       this.showStep("loading");
@@ -7324,10 +7658,10 @@ var SmartComplySDK = (() => {
       container.appendChild(btn);
       const trust = document.createElement("div");
       trust.style.cssText = `
-      display:flex;align-items:center;gap:6px;
-      color:${this.theme.textMuted};font-size:10.5px;
+      display:flex;align-items:flex-start;gap:6px;text-align:left;
+      color:${this.theme.textMuted};font-size:10.5px;line-height:1.5;
     `;
-      trust.textContent = "🔒  End-to-end encrypted";
+      trust.innerHTML = `<span style="flex-shrink:0;">🔒</span><span>Your photo and camera scan are used only to verify it's really you, and are kept encrypted.</span>`;
       container.appendChild(trust);
     }
     // ── Country Select ──────────────────────────────────────────────
@@ -8270,6 +8604,7 @@ var SmartComplySDK = (() => {
         this._renderRetryLimitReached(container);
         return;
       }
+      const attemptId = ++this._livenessAttemptId;
       const title = this.createStepTitle("Face verification");
       container.appendChild(title);
       const desc = document.createElement("div");
@@ -8311,9 +8646,10 @@ var SmartComplySDK = (() => {
             warning: this.theme.warning
           }
         },
-        ["BLINK"],
+        [...DEFAULT_CHALLENGE_ACTIONS],
         this.livenessEntryId || void 0
       ).then((result) => {
+        if (attemptId !== this._livenessAttemptId) return;
         if (result.status === "failed") {
           this._livenessFailures++;
         }
@@ -8322,8 +8658,11 @@ var SmartComplySDK = (() => {
         }
         this.showStep("done");
       }).catch((err) => {
-        this._livenessFailures++;
-        this.showErrorStep(err.message || "Liveness verification failed. Please try again.");
+        if (attemptId !== this._livenessAttemptId) return;
+        if (!_isInfrastructureError(err)) {
+          this._livenessFailures++;
+        }
+        this.showErrorStep(_userFacingLivenessError(err));
       });
     }
     // ── Error ───────────────────────────────────────────────────────
@@ -8605,6 +8944,30 @@ var SmartComplySDK = (() => {
       const allFields = Object.values(channels).flat().flatMap((ch) => ch.fields || []);
       return allFields.some((f2) => isUploadFieldType(f2.type));
     }
+    /**
+     * The "go back one step" target for a given step, if that step is
+     * navigable — shared by the header back button and the browser
+     * back-button (popstate) handler in mount() so both agree on the same
+     * step order.
+     */
+    _getBackAction(step) {
+      const countries = Object.keys(this.sdkConfig?.channels || {});
+      const backTargets = {
+        id_type: () => this.showStep(countries.length > 1 ? "country" : "welcome"),
+        country: () => this.showStep("welcome"),
+        id_input: () => this.showStep("id_type"),
+        confirm_identity: () => this.showStep("id_input"),
+        document_capture: () => {
+          this.docCapture?.destroy();
+          this.showStep("id_type");
+        },
+        document_confirm: () => {
+          this.docCapture?.destroy();
+          this.showStep("document_capture");
+        }
+      };
+      return backTargets[step];
+    }
     updateProgress() {
       const isDocFlow = this.isDocumentFlow();
       const countries = Object.keys(this.sdkConfig?.channels || {});
@@ -8642,21 +9005,7 @@ var SmartComplySDK = (() => {
         if (dots[1]) dots[1].style.background = stage2Active ? this.theme.primary : this.theme.border;
       }
       if (this.headerBackBtn) {
-        const backTargets = {
-          id_type: () => this.showStep(countries.length > 1 ? "country" : "welcome"),
-          country: () => this.showStep("welcome"),
-          id_input: () => this.showStep("id_type"),
-          confirm_identity: () => this.showStep("id_input"),
-          document_capture: () => {
-            this.docCapture?.destroy();
-            this.showStep("id_type");
-          },
-          document_confirm: () => {
-            this.docCapture?.destroy();
-            this.showStep("document_capture");
-          }
-        };
-        const backAction = backTargets[this.currentStep];
+        const backAction = this._getBackAction(this.currentStep);
         if (backAction) {
           this.headerBackBtn.style.display = "flex";
           const newBtn = this.headerBackBtn.cloneNode(true);